Help us shape the future of Go! Take the 2026 Go Developer Survey

acquisition

package
v0.17.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 19, 2026 License: AGPL-3.0 Imports: 30 Imported by: 0

Documentation

Overview

Package acquisition composes provider and external-source acquisition above the small immutable Starmap client.

Index

Constants

View Source
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

type AcquirerOption func(*Acquirer) error

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

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

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

func New(client *starmap.Client, opts ...Option) (*Syncer, error)

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

func NewForRuntime(connected *runtime.Runtime, opts ...Option) (*Syncer, error)

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.

func (*Syncer) Sync

func (s *Syncer) Sync(
	ctx context.Context,
	opts ...pkgsync.Option,
) (*pkgsync.Result, error)

Sync observes and reconciles sources. Dry runs require no writable store. Non-dry runs build inside Client.Update so candidate construction, store CAS, and atomic publication remain one serialized mutation transaction.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL