Documentation
¶
Overview ¶
Package acquisition composes provider and external-source acquisition above the small immutable Starmap client.
Index ¶
- Constants
- func InspectCredentialPolicyPublications(ctx context.Context, product CredentialProduct, state CredentialPolicyState, ...) ([]string, error)
- func InspectCredentialPolicyState(ctx context.Context, product CredentialProduct, state CredentialPolicyState) error
- func NewProviderFetcher(providers catalogs.ProvidersReader, opts ...sources.ProviderOption) *sources.ProviderFetcher
- func OpenCredentialResolver(ctx context.Context, config CredentialResolverConfig) (sources.ProviderCredentialResolver, error)
- type Acquirer
- func (a *Acquirer) AcquireProviderBindings(ctx context.Context, request runtime.AcquisitionRequest, ...) (runtime.AcquisitionResult, error)
- func (a *Acquirer) AcquireProviders(ctx context.Context, request runtime.AcquisitionRequest) (runtime.AcquisitionResult, error)
- func (a *Acquirer) CheckFleetAcquisition(ctx context.Context, request runtime.FleetAcquisitionRequirements) error
- func (a *Acquirer) ObserveProviderBinding(ctx context.Context, current *catalogs.Catalog, ...) (ProviderObservation, error)
- type AcquirerOption
- func WithAcquirerClock(now func() time.Time) AcquirerOption
- func WithAcquirerCoalesceTimer(after func(time.Duration) <-chan time.Time) AcquirerOption
- func WithAcquirerCoalesceWindow(window time.Duration) AcquirerOption
- func WithAcquirerCredentialResolver(resolver sources.ProviderCredentialResolver) AcquirerOption
- func WithProviderObserver(observer ProviderObserver) AcquirerOption
- type CredentialPolicyState
- type CredentialProduct
- type CredentialReference
- type CredentialResolverConfig
- type ImportResult
- type Option
- func WithCredentialResolver(resolver sources.ProviderCredentialResolver) Option
- func WithProviderBindings(bindings ...sources.ProviderAcquisitionBinding) Option
- func WithProviderClientFactory(factory sources.ProviderClientFactory) Option
- func WithSourceDirectories(directories productpaths.SourceDirectories) Option
- type ProviderBindingObserver
- type ProviderObservation
- type ProviderObserver
- type SourceAcquirer
- func (a *SourceAcquirer) AcquireSourceReport(ctx context.Context, request runtime.SourceAcquisitionRequest) ([]sources.Observation, []sources.SourceActivity, error)
- func (a *SourceAcquirer) AcquireSources(ctx context.Context, request runtime.SourceAcquisitionRequest) ([]sources.Observation, error)
- func (a *SourceAcquirer) SourceConfiguration() []sources.SourceActivity
- type Syncer
- func (s *Syncer) ImportRelease(ctx context.Context, release artifact.Release, ...) (*ImportResult, error)
- func (s *Syncer) PublishObservations(ctx context.Context, observations ...sources.Observation) (starmap.Publication, error)
- func (s *Syncer) Sync(ctx context.Context, opts ...pkgsync.Option) (*pkgsync.Result, error)
Constants ¶
const DefaultCoalesceWindow = 30 * time.Second
DefaultCoalesceWindow bounds how long a completed provider observation waits for a slower sibling. The window keeps one publication for a run that finishes together, and it bounds the wait for a run that does not.
Variables ¶
This section is empty.
Functions ¶
func InspectCredentialPolicyPublications ¶ added in v0.17.0
func InspectCredentialPolicyPublications(ctx context.Context, product CredentialProduct, state CredentialPolicyState, files map[string]productfiles.RetainedFile, read productfiles.RetainedRecordReader) ([]string, error)
InspectCredentialPolicyPublications selects verified publication evidence to keep inactive. The caller preserves selected files and validates the remaining policy before publication. This check does not accept a migration or authorize credential use.
func InspectCredentialPolicyState ¶ added in v0.17.0
func InspectCredentialPolicyState(ctx context.Context, product CredentialProduct, state CredentialPolicyState) error
InspectCredentialPolicyState validates existing policy without writes or credential access. Product selects the policy family. The retained default takes precedence over LegacyInstallation. The caller must fence writers and verify the complete inventory around this inspection. A valid policy does not approve replica reuse, acquisition, or inference.
func NewProviderFetcher ¶
func NewProviderFetcher( providers catalogs.ProvidersReader, opts ...sources.ProviderOption, ) *sources.ProviderFetcher
NewProviderFetcher returns the repository's opt-in concrete provider composition. Importing starmap alone never imports provider SDKs.
func OpenCredentialResolver ¶ added in v0.17.0
func OpenCredentialResolver(ctx context.Context, config CredentialResolverConfig) (sources.ProviderCredentialResolver, error)
OpenCredentialResolver composes the built-in acquisition secret sources and selection policy. It opens only explicitly selected policy storage and never reads credential sources during construction. Product selects ambient precedence. Explicit references override ambient selection.
Types ¶
type Acquirer ¶ added in v0.16.0
type Acquirer struct {
// contains filtered or unexported fields
}
Acquirer observes providers for a connected runtime. It publishes every completed observation through one bounded coalescing window, so a partial failure still moves the catalog forward.
func NewAcquirer ¶ added in v0.16.0
func NewAcquirer(opts ...AcquirerOption) (*Acquirer, error)
NewAcquirer returns the concrete runtime acquirer. It starts no goroutine and reaches no provider until a run starts.
func (*Acquirer) AcquireProviderBindings ¶ added in v0.17.0
func (a *Acquirer) AcquireProviderBindings(ctx context.Context, request runtime.AcquisitionRequest, bindings []sources.ProviderAcquisitionBinding) (runtime.AcquisitionResult, error)
AcquireProviderBindings observes only the supplied declarations through their selected profiles. It checks the complete selection before credential resolution or provider I/O. Empty bindings select nothing. Request providers can restrict this explicit set.
func (*Acquirer) AcquireProviders ¶ added in v0.16.0
func (a *Acquirer) AcquireProviders( ctx context.Context, request runtime.AcquisitionRequest, ) (runtime.AcquisitionResult, error)
AcquireProviders observes every eligible provider concurrently. The first observation that carries a layer opens one bounded coalescing window. Every layer that arrives inside the window joins the same publication. A window that closes while a provider still runs emits the layers it collected and keeps waiting. One slow provider then delays no completed peer by more than one window, and it still publishes its own layer later.
func (*Acquirer) CheckFleetAcquisition ¶ added in v0.17.0
func (a *Acquirer) CheckFleetAcquisition(ctx context.Context, request runtime.FleetAcquisitionRequirements) error
CheckFleetAcquisition resolves required acquisition profiles without listing models. Scope equivalence comes from the accepted deployment bindings, not secret comparison.
func (*Acquirer) ObserveProviderBinding ¶ added in v0.17.0
func (a *Acquirer) ObserveProviderBinding(ctx context.Context, current *catalogs.Catalog, binding sources.ProviderAcquisitionBinding) (ProviderObservation, error)
ObserveProviderBinding gets one provider observation without retaining or publishing it. Runtime scope policy must approve the returned evidence before activation.
type AcquirerOption ¶ added in v0.16.0
AcquirerOption configures the runtime acquirer.
func WithAcquirerClock ¶ added in v0.16.0
func WithAcquirerClock(now func() time.Time) AcquirerOption
WithAcquirerClock injects the clock that stamps every attempt.
func WithAcquirerCoalesceTimer ¶ added in v0.16.0
func WithAcquirerCoalesceTimer(after func(time.Duration) <-chan time.Time) AcquirerOption
WithAcquirerCoalesceTimer injects the timer that closes the coalescing window. A test drives the window without a real delay.
func WithAcquirerCoalesceWindow ¶ added in v0.16.0
func WithAcquirerCoalesceWindow(window time.Duration) AcquirerOption
WithAcquirerCoalesceWindow bounds how long a completed observation waits for a slower sibling.
func WithAcquirerCredentialResolver ¶ added in v0.16.0
func WithAcquirerCredentialResolver(resolver sources.ProviderCredentialResolver) AcquirerOption
WithAcquirerCredentialResolver injects the process credential resolver into the default per-provider observation. One resolver then owns credential caching for the process. A replaced observer ignores it.
func WithProviderObserver ¶ added in v0.16.0
func WithProviderObserver(observer ProviderObserver) AcquirerOption
WithProviderObserver replaces the concrete per-provider observation. Use it for restricted deployments and for deterministic tests.
type CredentialPolicyState ¶ added in v0.17.0
type CredentialPolicyState struct {
Directory string
Product string
DeploymentID string
InstanceID string
LegacyInstallation bool
}
CredentialPolicyState selects private storage for persistent credential selection history. The host must classify installations without a policy record from its existing state. Existing policy records take precedence over LegacyInstallation.
type CredentialProduct ¶ added in v0.17.0
type CredentialProduct string
CredentialProduct selects the catalog acquisition policy family.
const ( // CredentialProductStarmap selects standalone Starmap acquisition. CredentialProductStarmap CredentialProduct = "starmap" // CredentialProductStarport selects embedded Starport acquisition. CredentialProductStarport CredentialProduct = "starport" )
type CredentialReference ¶ added in v0.17.0
type CredentialReference struct {
ProviderID catalogs.ProviderID
FieldID catalogs.ProviderCredentialFieldID
Reference string
FallbackAmbient bool
}
CredentialReference selects a deployment source for one catalog credential field.
type CredentialResolverConfig ¶ added in v0.17.0
type CredentialResolverConfig struct {
References []CredentialReference
// Product defaults to Starmap. It selects both current and legacy policy ordering.
Product CredentialProduct
// Lookup reads the host environment. Nil uses the process environment.
Lookup func(string) (string, bool)
// State selects explicit persistence. Nil uses the current policy without migration history.
State *CredentialPolicyState
}
CredentialResolverConfig configures Starmap catalog acquisition without inference or account storage.
type ImportResult ¶
type ImportResult struct {
// SourceGenerationID identifies the exact verified release generation.
SourceGenerationID string
// Publication identifies the locally committed reconciled generation.
Publication starmap.Publication
// Projection reports the post-commit human-workspace projection.
Projection *projection.Result
}
ImportResult describes a verified release observation and any local generation it produced after authority-aware reconciliation.
type Option ¶
type Option func(*options) error
Option configures one acquisition Syncer.
func WithCredentialResolver ¶ added in v0.4.0
func WithCredentialResolver(resolver sources.ProviderCredentialResolver) Option
WithCredentialResolver selects the deployment-owned catalog-acquisition credential resolver.
func WithProviderBindings ¶ added in v0.17.0
func WithProviderBindings(bindings ...sources.ProviderAcquisitionBinding) Option
WithProviderBindings limits manual acquisition to the declared provider scopes. An explicit empty set disables provider acquisition. Omission retains legacy selection. Source and provider options can restrict this set, but cannot add bindings.
func WithProviderClientFactory ¶
func WithProviderClientFactory(factory sources.ProviderClientFactory) Option
WithProviderClientFactory replaces the concrete provider-client composition. Use it for source plugins, restricted deployments, and deterministic tests.
func WithSourceDirectories ¶ added in v0.17.0
func WithSourceDirectories(directories productpaths.SourceDirectories) Option
WithSourceDirectories selects host-owned source cache and checkout directories. New validates the paths without reading platform settings or creating files.
type ProviderBindingObserver ¶ added in v0.17.0
type ProviderBindingObserver interface {
ObserveProviderBinding(context.Context, *catalogs.Catalog, sources.ProviderAcquisitionBinding) (ProviderObservation, error)
}
ProviderBindingObserver observes a declared scope through its acquisition profile. Custom observers must implement this contract before they can serve bound requests.
type ProviderObservation ¶ added in v0.16.0
type ProviderObservation struct {
// Layer is the observed provider catalog. It is empty unless the attempt
// succeeded.
Layer runtime.ProviderLayer
// Attempt is the terminal attempt record of the provider.
Attempt sources.ProviderAttempt
}
ProviderObservation is the terminal result of one provider attempt. A skipped or failed attempt carries no layer.
type ProviderObserver ¶ added in v0.16.0
type ProviderObserver interface {
ObserveProvider(
ctx context.Context,
current *catalogs.Catalog,
id catalogs.ProviderID,
) (ProviderObservation, error)
}
ProviderObserver observes exactly one provider. The runtime acquirer runs one observation per provider, so a slow provider never holds the records of a provider that already answered.
type SourceAcquirer ¶ added in v0.17.0
type SourceAcquirer struct {
// contains filtered or unexported fields
}
SourceAcquirer uses the shared registered sources for connected acquisition. Provider APIs remain with Acquirer so their publication windows stay independent.
func NewSourceAcquirer ¶ added in v0.17.0
func NewSourceAcquirer(opts ...pkgsync.Option) (*SourceAcquirer, error)
NewSourceAcquirer prepares non-provider acquisition without source reads. WithSources selects local or one models.dev form. The default uses local and HTTP. Other sync options use the same path, dependency, and timeout semantics as manual acquisition.
func (*SourceAcquirer) AcquireSourceReport ¶ added in v0.17.0
func (a *SourceAcquirer) AcquireSourceReport(ctx context.Context, request runtime.SourceAcquisitionRequest) ([]sources.Observation, []sources.SourceActivity, error)
AcquireSourceReport returns observations and activity owned by this call. Existing callers can use AcquireSources when they need only observations.
func (*SourceAcquirer) AcquireSources ¶ added in v0.17.0
func (a *SourceAcquirer) AcquireSources(ctx context.Context, request runtime.SourceAcquisitionRequest) ([]sources.Observation, error)
AcquireSources returns original observations without publishing a catalog. Provider filters use the shared pipeline contract. A failed scope preserves other results.
func (*SourceAcquirer) SourceConfiguration ¶ added in v0.17.0
func (a *SourceAcquirer) SourceConfiguration() []sources.SourceActivity
SourceConfiguration reports built-in metadata support and constructor defaults. It reads no workspace, tool, network endpoint, or credential material.
type Syncer ¶
type Syncer struct {
// contains filtered or unexported fields
}
Syncer observes configured sources, reconciles a complete candidate, and delegates serialized durable publication to a Client.
func New ¶
New constructs an explicit acquisition composition. It starts no goroutine and does not access sources or the filesystem.
func NewForRuntime ¶ added in v0.17.0
NewForRuntime composes explicit acquisition with retained runtime publication. Construction reads no source. The caller owns the connected runtime's lifecycle.
func (*Syncer) ImportRelease ¶
func (s *Syncer) ImportRelease( ctx context.Context, release artifact.Release, verifier artifact.PublisherVerifier, ) (*ImportResult, error)
ImportRelease verifies a portable catalog release. It reconciles the release as a trusted, low-authority observation with the current catalog and human workspace, then publishes the result atomically. A verification failure cannot mutate the client. ImportRelease never activates the release wholesale. Independent membership scopes retain their original receipts. Conflicting records for one publisher and binding revision require explicit source selection.
func (*Syncer) PublishObservations ¶ added in v0.3.0
func (s *Syncer) PublishObservations( ctx context.Context, observations ...sources.Observation, ) (starmap.Publication, error)
PublishObservations reconciles caller-verified catalog observations and publishes the resulting immutable generation. This is the non-network acquisition boundary for operator and tenant catalog facts.