Documentation
¶
Overview ¶
Package providerclient provides a core-importable gRPC-client adapter that wraps the plugin/external/proto IaC gRPC services as interfaces.IaCProvider (+ optional sub-interfaces). It is the counterpart of the wfctl-only typedIaCAdapter (cmd/wfctl/iac_typed_adapter.go, package main), rebuilt in a core-importable package so the engine can register external iac.provider plugins as services via app.RegisterService — the foundational gap that v1/v1.1 of infra-admin silently lacked (design doc §Cycle 3 resolution C1).
Usage (via WiringHook in plugin/external/adapter.go):
adapter := providerclient.New(conn, advertisedServices) app.RegisterService(moduleName, adapter)
Steps resolve the provider via:
app.GetService(cfg.Provider, &provider) // provider is interfaces.IaCProvider
Index ¶
- Constants
- type Adapter
- func (a *Adapter) BootstrapStateBackend(ctx context.Context, cfg map[string]any) (*interfaces.BootstrapResult, error)
- func (a *Adapter) Capabilities() []interfaces.IaCCapabilityDeclaration
- func (a *Adapter) Close() error
- func (a *Adapter) Destroy(ctx context.Context, resources []interfaces.ResourceRef) (*interfaces.DestroyResult, error)
- func (a *Adapter) DetectDrift(ctx context.Context, resources []interfaces.ResourceRef) ([]interfaces.DriftResult, error)
- func (a *Adapter) DriftDetector() interfaces.DriftConfigDetector
- func (a *Adapter) Import(ctx context.Context, cloudID string, resourceType string) (*interfaces.ResourceState, error)
- func (a *Adapter) Initialize(ctx context.Context, cfg map[string]any) error
- func (a *Adapter) Name() string
- func (a *Adapter) Plan(ctx context.Context, desired []interfaces.ResourceSpec, ...) (*interfaces.IaCPlan, error)
- func (a *Adapter) RegionLister() interfaces.IaCProviderRegionLister
- func (a *Adapter) ResolveSizing(resourceType string, size interfaces.Size, hints *interfaces.ResourceHints) (*interfaces.ProviderSizing, error)
- func (a *Adapter) ResourceDriver(resourceType string) (interfaces.ResourceDriver, error)
- func (a *Adapter) Status(ctx context.Context, resources []interfaces.ResourceRef) ([]interfaces.ResourceStatus, error)
- func (a *Adapter) SupportedCanonicalKeys() []string
- func (a *Adapter) Version() string
- type DriftDetectorProvider
- type RegionListerProvider
Constants ¶
const ( // IaCServiceRegionLister is the gRPC service name for the optional // IaCProviderRegionLister service. IaCServiceRegionLister = "workflow.plugin.external.iac.IaCProviderRegionLister" // IaCServiceDriftDetector is the gRPC service name for the optional // IaCProviderDriftDetector service. IaCServiceDriftDetector = "workflow.plugin.external.iac.IaCProviderDriftDetector" )
Fully-qualified gRPC service names for optional IaC services. These mirror the constants in cmd/wfctl/iac_typed_adapter.go and are sourced from the generated proto ServiceDesc so they cannot drift. The WiringHook in plugin/external/adapter.go passes the advertised set here; optional gRPC clients are constructed only when the corresponding name is present.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Adapter ¶
type Adapter struct {
// contains filtered or unexported fields
}
Adapter wraps the pb.IaCProviderRequired gRPC client (and advertisement-gated optional clients) as interfaces.IaCProvider. Optional sub-interfaces (IaCProviderRegionLister, DriftConfigDetector) are exposed via typed accessors (RegionLister(), DriftDetector()) that return nil when the plugin did not advertise the corresponding gRPC service.
The critical invariant: *Adapter does NOT unconditionally satisfy interfaces.IaCProviderRegionLister. Callers MUST type-assert to RegionListerProvider and call RegionLister() to discover the capability, then use the returned object. This mirrors typedIaCAdapter which returns nil optional clients for unadvertised services — enabling catalog steps' "static fallback if unadvertised" path to fire correctly.
Compile-time guards are in adapter_test.go.
func New ¶
func New(conn grpc.ClientConnInterface, advertisedServices map[string]bool) *Adapter
New constructs an Adapter over conn. Optional gRPC clients (RegionLister, DriftDetector) are constructed ONLY when the matching service name appears in advertisedServices. Passing nil or an empty map is valid — the adapter exposes only the required surface in that case.
advertisedServices should be populated from the plugin's ContractRegistry (see plugin/external/adapter.go WiringHooks). The service-name constants IaCServiceRegionLister and IaCServiceDriftDetector are provided for the caller's convenience.
func (*Adapter) BootstrapStateBackend ¶
func (a *Adapter) BootstrapStateBackend(ctx context.Context, cfg map[string]any) (*interfaces.BootstrapResult, error)
BootstrapStateBackend calls IaCProviderRequired.BootstrapStateBackend. All three result fields (Bucket, Region, Endpoint) are mapped from the proto response — Endpoint carries the S3-compatible API URL (e.g. DO Spaces endpoint) that was silently dropped in the original implementation.
func (*Adapter) Capabilities ¶
func (a *Adapter) Capabilities() []interfaces.IaCCapabilityDeclaration
Capabilities calls the IaCProviderRequired.Capabilities RPC (cached) and translates the response to []interfaces.IaCCapabilityDeclaration.
func (*Adapter) Close ¶
Close is a no-op on the adapter — the connection lifecycle is owned by the host's plugin manager (see ExternalPluginAdapter.Conn docs).
func (*Adapter) Destroy ¶
func (a *Adapter) Destroy(ctx context.Context, resources []interfaces.ResourceRef) (*interfaces.DestroyResult, error)
Destroy calls IaCProviderRequired.Destroy and translates proto↔interfaces types.
func (*Adapter) DetectDrift ¶
func (a *Adapter) DetectDrift(ctx context.Context, resources []interfaces.ResourceRef) ([]interfaces.DriftResult, error)
DetectDrift routes through the optional IaCProviderDriftDetector gRPC service when the plugin advertised it (advertisement-gated in New). Falls back to ErrProviderMethodUnimplemented when the detector was not advertised — callers use errors.Is to skip or fall back to static drift logic.
func (*Adapter) DriftDetector ¶
func (a *Adapter) DriftDetector() interfaces.DriftConfigDetector
DriftDetector implements DriftDetectorProvider. Returns the drift-detector capability object (satisfying interfaces.DriftConfigDetector) when the plugin advertised IaCProviderDriftDetector, or nil when it did not. Callers MUST nil-check before using.
func (*Adapter) Import ¶
func (a *Adapter) Import(ctx context.Context, cloudID string, resourceType string) (*interfaces.ResourceState, error)
Import calls IaCProviderRequired.Import.
func (*Adapter) Initialize ¶
Initialize calls the IaCProviderRequired.Initialize RPC.
func (*Adapter) Name ¶
Name calls the IaCProviderRequired.Name RPC. Errors are logged and return "".
func (*Adapter) Plan ¶
func (a *Adapter) Plan(ctx context.Context, desired []interfaces.ResourceSpec, current []interfaces.ResourceState) (*interfaces.IaCPlan, error)
Plan calls IaCProviderRequired.Plan and translates proto↔interfaces types.
func (*Adapter) RegionLister ¶
func (a *Adapter) RegionLister() interfaces.IaCProviderRegionLister
RegionLister implements RegionListerProvider. Returns the region-lister capability object when the plugin advertised IaCProviderRegionLister, or nil when it did not. Callers MUST nil-check before using.
func (*Adapter) ResolveSizing ¶
func (a *Adapter) ResolveSizing(resourceType string, size interfaces.Size, hints *interfaces.ResourceHints) (*interfaces.ProviderSizing, error)
ResolveSizing calls IaCProviderRequired.ResolveSizing.
func (*Adapter) ResourceDriver ¶
func (a *Adapter) ResourceDriver(resourceType string) (interfaces.ResourceDriver, error)
ResourceDriver returns an error — the full ResourceDriver optional service is not in PR-1 scope. Steps that need per-action CRUD use wfctlhelpers.ApplyPlanWithHooks which dispatches through the provider's ResourceDriver on the plugin side.
func (*Adapter) Status ¶
func (a *Adapter) Status(ctx context.Context, resources []interfaces.ResourceRef) ([]interfaces.ResourceStatus, error)
Status calls IaCProviderRequired.Status and translates proto↔interfaces types.
func (*Adapter) SupportedCanonicalKeys ¶
SupportedCanonicalKeys returns the canonical keys from the cached CapabilitiesResponse, or the global set when the plugin doesn't declare a subset. Reuses fetchCapabilities so the Capabilities RPC is called at most once per adapter lifetime (per ADR-0029 / typedIaCAdapter precedent).
type DriftDetectorProvider ¶
type DriftDetectorProvider interface {
// DriftDetector returns the drift-detector capability object (satisfying
// interfaces.DriftConfigDetector), or nil when the plugin did not advertise
// IaCProviderDriftDetector.
DriftDetector() interfaces.DriftConfigDetector
}
DriftDetectorProvider is a capability-discovery interface implemented by *Adapter when the plugin advertised IaCProviderDriftDetector. Steps that need config-aware drift detection type-assert the registered interfaces.IaCProvider to DriftDetectorProvider and call DriftDetector(). A nil return means the plugin did not advertise the service.
type RegionListerProvider ¶
type RegionListerProvider interface {
// RegionLister returns the region-lister capability object, or nil when
// the plugin did not advertise IaCProviderRegionLister.
RegionLister() interfaces.IaCProviderRegionLister
}
RegionListerProvider is a capability-discovery interface implemented by *Adapter when the plugin advertised IaCProviderRegionLister. Steps that want to prefer provider-sourced region lists type-assert the registered interfaces.IaCProvider to RegionListerProvider and call RegionLister(). A nil return from RegionLister() means the plugin did not advertise the service — the step MUST fall back to its static catalog.
Source Files