Documentation
¶
Overview ¶
Package acquisition composes provider and external-source acquisition above the small immutable Starmap client.
Index ¶
- Constants
- func NewProviderFetcher(providers catalogs.ProvidersReader, opts ...sources.ProviderOption) *sources.ProviderFetcher
- type Acquirer
- 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 ImportResult
- type Option
- type ProviderObservation
- type ProviderObserver
- 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 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.
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) 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.
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 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 WithProviderClientFactory ¶
func WithProviderClientFactory(factory sources.ProviderClientFactory) Option
WithProviderClientFactory replaces the concrete provider-client composition. Use it for source plugins, restricted deployments, and deterministic tests.
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 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 (*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.
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.
Source Files