Documentation
¶
Overview ¶
Package catalog owns Starport's immutable view of Starmap facts and the separately versioned runtime availability used to derive routable models.
Index ¶
- Constants
- Variables
- func ProviderFromModelID(modelID string) string
- func SplitModelID(modelID string) (provider, model string, ok bool)
- type AdapterAvailability
- type ControlPlane
- func (p *ControlPlane) Activate(state starmap.CatalogState) error
- func (p *ControlPlane) Current() *RoutableSnapshot
- func (p *ControlPlane) PublishAvailability(snapshot availability.Snapshot) error
- func (p *ControlPlane) Refresh() error
- func (p *ControlPlane) RemoveAdapter(providerID catalogs.ProviderID) error
- func (p *ControlPlane) ReplaceAdapters(adapters []AdapterAvailability) error
- func (p *ControlPlane) ReplaceRuntime(state starmap.CatalogState, adapters []AdapterAvailability) (*RoutableSnapshot, error)
- func (p *ControlPlane) SetAdapter(adapter AdapterAvailability) error
- func (p *ControlPlane) ValidateRuntime(state starmap.CatalogState, adapters []AdapterAvailability) error
- type Diff
- type FreshnessService
- type GenerationIndexEntry
- type GenerationStore
- func (s *GenerationStore) Commit(ctx context.Context, generation catalogs.Generation, ...) error
- func (s *GenerationStore) Current(ctx context.Context) (catalogs.Generation, error)
- func (s *GenerationStore) Get(ctx context.Context, generationID string) (catalogs.Generation, error)
- func (s *GenerationStore) History(ctx context.Context) ([]GenerationIndexEntry, error)
- type OfferingChange
- type OfferingRoutability
- type PriceChange
- type RefreshReport
- type RemoteConfig
- type RemoteRuntime
- func (r *RemoteRuntime) Accept(ctx context.Context, state starmap.CatalogState) error
- func (r *RemoteRuntime) Close(ctx context.Context) error
- func (r *RemoteRuntime) ControlPlane() *ControlPlane
- func (r *RemoteRuntime) CurrentCandidate() starmap.CatalogState
- func (r *RemoteRuntime) RefreshCandidate(ctx context.Context, timeout time.Duration) (starmap.CatalogState, error)
- func (r *RemoteRuntime) Start(ctx context.Context) error
- func (r *RemoteRuntime) Sync(ctx context.Context, _ ...pkgsync.Option) (*pkgsync.Result, starmap.CatalogState, error)
- func (r *RemoteRuntime) Updates() <-chan starmap.CatalogState
- type RoutableSnapshot
- func (s *RoutableSnapshot) AvailabilityRevision() uint64
- func (s *RoutableSnapshot) Catalog() *catalogs.Catalog
- func (s *RoutableSnapshot) CatalogSequence() uint64
- func (s *RoutableSnapshot) Definition(id catalogs.ModelDefinitionID) (catalogs.ModelDefinition, error)
- func (s *RoutableSnapshot) Definitions() []catalogs.ModelDefinition
- func (s *RoutableSnapshot) GeneratedAt() time.Time
- func (s *RoutableSnapshot) GenerationID() string
- func (s *RoutableSnapshot) LowestPagePrice(operation catalogs.ProviderOperation) (float64, bool)
- func (s *RoutableSnapshot) LowestSearchUnitPrice(modelID string) (float64, bool)
- func (s *RoutableSnapshot) Names(modelID string) bool
- func (s *RoutableSnapshot) Offering(route Route) (catalogs.ProviderOffering, error)
- func (s *RoutableSnapshot) OfferingRoutability() []OfferingRoutability
- func (s *RoutableSnapshot) PagePriceFor(modelID string, operation catalogs.ProviderOperation) (float64, bool)
- func (s *RoutableSnapshot) PayloadChecksum() string
- func (s *RoutableSnapshot) ResolveOperation(modelID string, operation catalogs.ProviderOperation) (Route, bool)
- func (s *RoutableSnapshot) ResolveRoute(modelID string) (Route, bool)
- func (s *RoutableSnapshot) Routes() []Route
- func (s *RoutableSnapshot) RoutesForDefinition(definitionID catalogs.ModelDefinitionID) []Route
- func (s *RoutableSnapshot) RoutesForProvider(providerID catalogs.ProviderID) []Route
- type Route
- type RouteExclusion
- type Runtime
- func (r *Runtime) ControlPlane() *ControlPlane
- func (r *Runtime) PublishObservations(ctx context.Context, observations ...sources.Observation) (starmap.Publication, error)
- func (r *Runtime) Refresh(ctx context.Context, options ...pkgsync.Option) (*pkgsync.Result, error)
- func (r *Runtime) RefreshCandidate(ctx context.Context, timeout time.Duration) (starmap.CatalogState, error)
- func (r *Runtime) Sync(ctx context.Context, options ...pkgsync.Option) (*pkgsync.Result, starmap.CatalogState, error)
- type SnapshotMetadata
- type SnapshotSource
- type Source
- type SourceObservation
- type ValidationSummary
Constants ¶
const ( // DefaultRemoteActivationInterval bounds propagation from Starmap's atomic // subscriber state into Starport's runtime transaction. It causes no network // request. DefaultRemoteActivationInterval = 250 * time.Millisecond // DefaultRemoteFetchTimeout bounds manifest and payload requests. The SSE // stream uses Starmap's heartbeat and liveness contract instead. DefaultRemoteFetchTimeout = 2 * time.Minute )
const DefaultRefreshTimeout = 2 * time.Minute
DefaultRefreshTimeout bounds local catalog acquisition when the application does not configure a positive timeout.
Variables ¶
var ( // ErrCatalogSourceRequired reports a missing Starmap catalog source. ErrCatalogSourceRequired = errors.New("catalog source is required") // ErrCatalogRequired means that a Starmap state has no immutable catalog. ErrCatalogRequired = errors.New("catalog state must contain a catalog") // ErrModelNotCatalogued reports a model name the retained generation does // not hold. It is separate from an unreachable model because the two have // different answers: a name the catalog never held is the caller's to // correct, and a catalogued model with no reachable provider is the // gateway's to report. ErrModelNotCatalogued = errors.New("model is not in the catalog") // ErrCatalogGenerationRequired means that a Starmap state has no generation identity. ErrCatalogGenerationRequired = errors.New("catalog state must contain a generation ID") // ErrMissingPagePrice reports an offering that serves document recognition // and states no price per page. // // Recognition is the one operation whose unit is neither a token nor a // request, so a token price says nothing about what a page costs. An // offering the gateway cannot price is one it would serve for free against // real provider time, and a spend limit set on that account would never // fire. Planning drops the operation instead of guessing a price. ErrMissingPagePrice = errors.New("offering serves document recognition with no page price") // ErrRerankUnpriced reports an offering that serves reranking and states // no price in the unit it bills. // // Providers disagree on that unit. Cohere bills a search unit, which is one // query against a bounded document count, and Voyage bills the tokens it // reads. The offering names its own basis, so an offering that names one // and publishes no price for it is a catalog defect rather than a known // gap. Planning drops the operation, which keeps a silent zero out of the // account's spend total. ErrRerankUnpriced = errors.New("offering serves reranking with no price in the unit it bills") )
Functions ¶
func ProviderFromModelID ¶
ProviderFromModelID returns the adapter ID named by a provider-scoped model ID.
func SplitModelID ¶
SplitModelID splits one provider-scoped model ID.
Types ¶
type AdapterAvailability ¶
type AdapterAvailability struct {
ProviderID catalogs.ProviderID
Registered bool
Operations []catalogs.ProviderOperation
EndpointTypes []catalogs.EndpointType
}
AdapterAvailability is runtime state for one compiled provider adapter. It is not a catalog fact and does not contain operator credential state.
type ControlPlane ¶
type ControlPlane struct {
// contains filtered or unexported fields
}
ControlPlane atomically publishes one routable view derived from an immutable Starmap generation and separately versioned runtime availability.
func Open ¶
func Open(source Source) (*ControlPlane, error)
Open creates the catalog control plane from the source's current atomic state.
func (*ControlPlane) Activate ¶
func (p *ControlPlane) Activate(state starmap.CatalogState) error
Activate validates and atomically publishes one complete catalog generation. Retained older snapshots remain valid and do not observe the new generation.
func (*ControlPlane) Current ¶
func (p *ControlPlane) Current() *RoutableSnapshot
Current returns the current immutable routable snapshot in O(1).
func (*ControlPlane) PublishAvailability ¶
func (p *ControlPlane) PublishAvailability(snapshot availability.Snapshot) error
PublishAvailability applies one availability-owner generation to the derived routable projection. It does not own availability state transitions.
func (*ControlPlane) Refresh ¶
func (p *ControlPlane) Refresh() error
Refresh atomically activates the source's current catalog generation.
func (*ControlPlane) RemoveAdapter ¶
func (p *ControlPlane) RemoveAdapter(providerID catalogs.ProviderID) error
RemoveAdapter removes one runtime adapter and atomically republishes the view.
func (*ControlPlane) ReplaceAdapters ¶
func (p *ControlPlane) ReplaceAdapters(adapters []AdapterAvailability) error
ReplaceAdapters replaces the complete runtime adapter set in one publication.
func (*ControlPlane) ReplaceRuntime ¶ added in v1.0.2
func (p *ControlPlane) ReplaceRuntime( state starmap.CatalogState, adapters []AdapterAvailability, ) (*RoutableSnapshot, error)
ReplaceRuntime atomically publishes one catalog state and complete adapter set. Retained snapshots remain immutable.
func (*ControlPlane) SetAdapter ¶
func (p *ControlPlane) SetAdapter(adapter AdapterAvailability) error
SetAdapter updates one runtime adapter and atomically republishes the derived view.
func (*ControlPlane) ValidateRuntime ¶ added in v1.0.2
func (p *ControlPlane) ValidateRuntime( state starmap.CatalogState, adapters []AdapterAvailability, ) error
ValidateRuntime proves that one catalog state and complete adapter set can produce a routable snapshot without changing published state.
type Diff ¶ added in v1.1.0
type Diff struct {
Available bool `json:"available"`
Reason string `json:"reason,omitempty"`
FromGenerationID string `json:"from_generation_id,omitempty"`
ToGenerationID string `json:"to_generation_id,omitempty"`
FromGeneratedAt time.Time `json:"from_generated_at,omitzero"`
ToGeneratedAt time.Time `json:"to_generated_at,omitzero"`
SemanticallyEqual bool `json:"semantically_equal"`
ModelsAdded []string `json:"models_added,omitempty"`
ModelsRemoved []string `json:"models_removed,omitempty"`
OfferingsAdded []OfferingChange `json:"offerings_added,omitempty"`
OfferingsRemoved []OfferingChange `json:"offerings_removed,omitempty"`
PriceChanges []PriceChange `json:"price_changes,omitempty"`
}
Diff compares the previous accepted generation against the current one. When only one generation is recorded, Available is false and Reason says why — that is a normal state, not an error.
type FreshnessService ¶ added in v1.1.0
type FreshnessService struct {
// contains filtered or unexported fields
}
FreshnessService reads catalog freshness from the active snapshot and the durable generation store. It never mutates either.
func NewFreshnessService ¶ added in v1.1.0
func NewFreshnessService(snapshots SnapshotSource, generations *GenerationStore) *FreshnessService
NewFreshnessService creates the freshness read service.
func (*FreshnessService) Changes ¶ added in v1.1.0
func (s *FreshnessService) Changes(ctx context.Context) (Diff, error)
Changes diffs the previous accepted generation against the current one.
func (*FreshnessService) Metadata ¶ added in v1.1.0
func (s *FreshnessService) Metadata(ctx context.Context) (SnapshotMetadata, error)
Metadata reports the active snapshot's identity, age, and manifest facts.
type GenerationIndexEntry ¶ added in v1.1.0
type GenerationIndexEntry struct {
GenerationID string `json:"generation_id"`
GeneratedAt time.Time `json:"generated_at"`
PayloadChecksum string `json:"payload_checksum"`
SemanticChecksum string `json:"semantic_checksum,omitempty"`
}
GenerationIndexEntry records one accepted generation in acceptance order. The semantic checksum excludes provenance, so the diff service can skip provenance-only churn without decoding payloads.
type GenerationStore ¶
type GenerationStore struct {
// contains filtered or unexported fields
}
GenerationStore adapts Starport's configured KV store to Starmap's durable immutable-generation contract.
func NewGenerationStore ¶
func NewGenerationStore(store storage.KVStore) (*GenerationStore, error)
NewGenerationStore creates a durable Starmap generation store.
func (*GenerationStore) Commit ¶
func (s *GenerationStore) Commit( ctx context.Context, generation catalogs.Generation, expectedGenerationID string, ) error
Commit stores one immutable generation, then selects it with compare-and-swap.
func (*GenerationStore) Current ¶
func (s *GenerationStore) Current(ctx context.Context) (catalogs.Generation, error)
Current returns the atomically selected generation.
func (*GenerationStore) Get ¶
func (s *GenerationStore) Get(ctx context.Context, generationID string) (catalogs.Generation, error)
Get returns one immutable generation by ID.
func (*GenerationStore) History ¶ added in v1.1.0
func (s *GenerationStore) History(ctx context.Context) ([]GenerationIndexEntry, error)
History returns accepted generations in acceptance order, oldest first. A store without an index (the remote head store) reports no history.
type OfferingChange ¶ added in v1.1.0
type OfferingChange struct {
Provider string `json:"provider"`
ProviderModelID string `json:"provider_model_id"`
DefinitionID string `json:"definition_id"`
}
OfferingChange identifies one provider offering added or removed between two accepted generations.
type OfferingRoutability ¶ added in v1.1.0
type OfferingRoutability struct {
ProviderID catalogs.ProviderID
ProviderModelID catalogs.ProviderModelID
Routable bool
Exclusion RouteExclusion
}
OfferingRoutability is the planning verdict for one exact catalog offering. The verdict set is total: every offering in the generation carries one, so a caller can tell an advertised offering apart from a reachable one.
type PriceChange ¶ added in v1.1.0
type PriceChange struct {
Provider string `json:"provider"`
ProviderModelID string `json:"provider_model_id"`
DefinitionID string `json:"definition_id"`
Field string `json:"field"`
PreviousPer1M float64 `json:"previous_per_1m"`
CurrentPer1M float64 `json:"current_per_1m"`
}
PriceChange reports one token-price movement on an offering present in both generations. Values are USD per one million tokens.
type RefreshReport ¶ added in v1.1.0
type RefreshReport struct {
PreviousGenerationID string `json:"previous_generation_id"`
GenerationID string `json:"generation_id"`
GeneratedAt time.Time `json:"generated_at"`
Changed bool `json:"changed"`
}
RefreshReport summarizes one forced catalog acquisition.
type RemoteConfig ¶ added in v1.0.2
type RemoteConfig struct {
BaseURL string
APIKey string
ActivationInterval time.Duration
FetchTimeout time.Duration
HTTPClient *http.Client
}
RemoteConfig defines one verified Starmap publication source.
type RemoteRuntime ¶ added in v1.0.2
type RemoteRuntime struct {
// contains filtered or unexported fields
}
RemoteRuntime owns the verified Starmap subscriber, its durable remote head, and Starport's separate accepted runtime generation.
func OpenRemoteRuntime ¶ added in v1.0.2
func OpenRemoteRuntime( ctx context.Context, store storage.KVStore, config RemoteConfig, ) (*RemoteRuntime, error)
OpenRemoteRuntime creates an idle remote runtime without starting network or background work.
func (*RemoteRuntime) Accept ¶ added in v1.0.2
func (r *RemoteRuntime) Accept(ctx context.Context, state starmap.CatalogState) error
Accept records a generation after Starport builds and validates the complete runtime candidate. The remote and accepted current pointers remain independent.
func (*RemoteRuntime) Close ¶ added in v1.0.2
func (r *RemoteRuntime) Close(ctx context.Context) error
Close stops and joins all remote runtime work.
func (*RemoteRuntime) ControlPlane ¶ added in v1.0.2
func (r *RemoteRuntime) ControlPlane() *ControlPlane
ControlPlane returns the last accepted Starport runtime catalog.
func (*RemoteRuntime) CurrentCandidate ¶ added in v1.0.2
func (r *RemoteRuntime) CurrentCandidate() starmap.CatalogState
CurrentCandidate returns the subscriber's current atomic state without I/O.
func (*RemoteRuntime) RefreshCandidate ¶ added in v1.1.0
func (r *RemoteRuntime) RefreshCandidate( ctx context.Context, timeout time.Duration, ) (starmap.CatalogState, error)
RefreshCandidate returns the verified subscriber state without network I/O. Remote publication and retry work belongs to Start.
func (*RemoteRuntime) Start ¶ added in v1.0.2
func (r *RemoteRuntime) Start(ctx context.Context) error
Start starts the Starmap remote lifecycle and the local atomic-state sampler.
func (*RemoteRuntime) Sync ¶ added in v1.0.2
func (r *RemoteRuntime) Sync( ctx context.Context, _ ...pkgsync.Option, ) (*pkgsync.Result, starmap.CatalogState, error)
Sync returns the current verified subscriber state without network I/O. Remote publication and retry work belongs to Start.
func (*RemoteRuntime) Updates ¶ added in v1.0.2
func (r *RemoteRuntime) Updates() <-chan starmap.CatalogState
Updates returns verified atomic states after the initial candidate.
type RoutableSnapshot ¶
type RoutableSnapshot struct {
// contains filtered or unexported fields
}
RoutableSnapshot projects one Starmap generation and one runtime availability revision into an immutable route set.
func (*RoutableSnapshot) AvailabilityRevision ¶
func (s *RoutableSnapshot) AvailabilityRevision() uint64
AvailabilityRevision returns the runtime availability revision.
func (*RoutableSnapshot) Catalog ¶
func (s *RoutableSnapshot) Catalog() *catalogs.Catalog
Catalog returns the retained immutable Starmap catalog. Starmap guarantees that published catalogs are safe to share and retain across goroutines.
func (*RoutableSnapshot) CatalogSequence ¶
func (s *RoutableSnapshot) CatalogSequence() uint64
CatalogSequence returns the source's monotonic generation sequence.
func (*RoutableSnapshot) Definition ¶
func (s *RoutableSnapshot) Definition( id catalogs.ModelDefinitionID, ) (catalogs.ModelDefinition, error)
Definition returns one caller-owned definition from this exact generation.
func (*RoutableSnapshot) Definitions ¶
func (s *RoutableSnapshot) Definitions() []catalogs.ModelDefinition
Definitions returns caller-owned Starmap definitions that have a routable offering.
func (*RoutableSnapshot) GeneratedAt ¶
func (s *RoutableSnapshot) GeneratedAt() time.Time
GeneratedAt returns the Starmap generation timestamp.
func (*RoutableSnapshot) GenerationID ¶
func (s *RoutableSnapshot) GenerationID() string
GenerationID returns the Starmap generation used to derive this snapshot.
func (*RoutableSnapshot) LowestPagePrice ¶ added in v1.1.0
func (s *RoutableSnapshot) LowestPagePrice(operation catalogs.ProviderOperation) (float64, bool)
LowestPagePrice returns the cheapest page price this generation publishes for one operation.
It answers the question a caller has before a route exists: what is the least this document can cost to read? The planner picks the offering afterwards, so no exact price is knowable yet, and the cheapest one is the only bound that refuses no work the account could have paid for.
func (*RoutableSnapshot) LowestSearchUnitPrice ¶ added in v1.1.0
func (s *RoutableSnapshot) LowestSearchUnitPrice(modelID string) (float64, bool)
LowestSearchUnitPrice returns the cheapest search unit price this generation publishes for one model's rerank offerings.
It answers the question a spend budget has before a route exists: what is the least this rerank call can cost? The planner picks the offering afterwards, so no exact price is knowable yet, and the cheapest one is the only bound that refuses no work the account could have paid for. An offering that bills tokens rather than search units states no floor at all before the provider has read the documents, so it answers nothing and the budget refuses nothing.
func (*RoutableSnapshot) Names ¶ added in v1.1.0
func (s *RoutableSnapshot) Names(modelID string) bool
Names reports whether this generation holds one model name at all. It reads every offering the generation carries and not the routable subset, because a name whose provider has no credential today is still a name the catalog holds. A caller that used the routable set here would answer a configuration gap with "no such model" and send an operator looking for a typo.
It accepts the same two spellings ResolveRoute accepts: a provider-scoped route ID and a canonical definition ID.
func (*RoutableSnapshot) Offering ¶
func (s *RoutableSnapshot) Offering(route Route) (catalogs.ProviderOffering, error)
Offering returns one caller-owned offering from this exact generation.
func (*RoutableSnapshot) OfferingRoutability ¶ added in v1.1.0
func (s *RoutableSnapshot) OfferingRoutability() []OfferingRoutability
OfferingRoutability returns the planning verdict for every offering in the generation, routable or not, sorted by provider and provider model ID.
func (*RoutableSnapshot) PagePriceFor ¶ added in v1.1.0
func (s *RoutableSnapshot) PagePriceFor( modelID string, operation catalogs.ProviderOperation, ) (float64, bool)
PagePriceFor returns what one model charges to read one page of a document, in USD. A page is the unit recognition is billed in, and no token price converts into it.
func (*RoutableSnapshot) PayloadChecksum ¶ added in v1.0.2
func (s *RoutableSnapshot) PayloadChecksum() string
PayloadChecksum returns the checksum bound to the Starmap generation.
func (*RoutableSnapshot) ResolveOperation ¶
func (s *RoutableSnapshot) ResolveOperation( modelID string, operation catalogs.ProviderOperation, ) (Route, bool)
ResolveOperation resolves only routes that support one exact operation.
func (*RoutableSnapshot) ResolveRoute ¶
func (s *RoutableSnapshot) ResolveRoute(modelID string) (Route, bool)
ResolveRoute resolves a provider-scoped route ID or a canonical definition ID to the first stable routable offering.
func (*RoutableSnapshot) Routes ¶
func (s *RoutableSnapshot) Routes() []Route
Routes returns a caller-owned copy of the routable offering identities.
func (*RoutableSnapshot) RoutesForDefinition ¶
func (s *RoutableSnapshot) RoutesForDefinition(definitionID catalogs.ModelDefinitionID) []Route
RoutesForDefinition returns routable offerings for one canonical model.
func (*RoutableSnapshot) RoutesForProvider ¶
func (s *RoutableSnapshot) RoutesForProvider(providerID catalogs.ProviderID) []Route
RoutesForProvider returns routable offerings for one provider in stable order.
type Route ¶
type Route struct {
CatalogGenerationID string
DefinitionID catalogs.ModelDefinitionID
ProviderID catalogs.ProviderID
ProviderModelID catalogs.ProviderModelID
Operations []catalogs.ProviderOperation
Endpoints []catalogs.ProviderOfferingEndpoint
PromptCache *bool
}
Route is one immutable, generation-bound provider offering identity.
func (Route) Endpoint ¶
func (r Route) Endpoint(operation catalogs.ProviderOperation) (catalogs.ProviderOfferingEndpoint, bool)
Endpoint returns the exact Starmap endpoint for a supported operation.
func (Route) Key ¶
func (r Route) Key() catalogs.OfferingKey
Key returns the exact Starmap provider offering identity.
func (Route) Supports ¶
func (r Route) Supports(operation catalogs.ProviderOperation) bool
Supports reports whether the catalog offering and compiled adapter both support the operation.
func (Route) SupportsPromptCache ¶
SupportsPromptCache reports exact offering support. Unknown is not support.
type RouteExclusion ¶ added in v1.1.0
type RouteExclusion string
RouteExclusion names the derivation filter that kept one catalog offering out of the routable set. It is the route planner's own vocabulary. A caller that reports operator state maps it into its own reason words.
const ( // RouteExclusionNone marks an offering that planning kept. RouteExclusionNone RouteExclusion = "" // RouteExclusionAdapterNotReady reports that the provider has no adapter // able to carry a request, so none of its offerings can be reached. RouteExclusionAdapterNotReady RouteExclusion = "adapter_not_ready" // RouteExclusionCatalogRetired reports a retired offering lifecycle. RouteExclusionCatalogRetired RouteExclusion = "catalog_retired" RouteExclusionCatalogUnavailable RouteExclusion = "catalog_unavailable" // currently withholds this offering. RouteExclusionOfferingUnavailable RouteExclusion = "offering_unavailable" // RouteExclusionOperationUnsupported reports that the offering and the // adapter share no operation with a usable endpoint. The offering exists in // the catalog and is healthy, and no request can reach it. RouteExclusionOperationUnsupported RouteExclusion = "operation_unsupported" // RouteExclusionOperationUnpriced reports that every operation the offering // and the adapter share is one the gateway cannot bill. It is a separate // verdict from operation_unsupported because the fix is a catalog price, // not a compiled adapter. RouteExclusionOperationUnpriced RouteExclusion = "operation_unpriced" )
Route exclusions are a closed set, ordered the way the derivation applies them. An offering carries the first exclusion that rejected it.
type Runtime ¶
type Runtime struct {
// contains filtered or unexported fields
}
Runtime owns one Starmap client, its acquisition path, and Starport's derived immutable routable control plane.
func OpenRuntime ¶
func OpenRuntime( ctx context.Context, store storage.KVStore, workspacePath string, options ...acquisition.Option, ) (*Runtime, error)
OpenRuntime constructs the catalog runtime over Starport's durable storage. Starmap alone resolves catalog-acquisition credentials.
func (*Runtime) ControlPlane ¶
func (r *Runtime) ControlPlane() *ControlPlane
ControlPlane returns Starport's generation-consistent catalog projection.
func (*Runtime) PublishObservations ¶
func (r *Runtime) PublishObservations( ctx context.Context, observations ...sources.Observation, ) (starmap.Publication, error)
PublishObservations reconciles account or operator observations through Starmap, then activates the resulting immutable generation.
func (*Runtime) Refresh ¶
Refresh runs Starmap acquisition and publishes any new generation into the Starport routable view.
func (*Runtime) RefreshCandidate ¶ added in v1.1.0
func (r *Runtime) RefreshCandidate( ctx context.Context, timeout time.Duration, ) (starmap.CatalogState, error)
RefreshCandidate acquires the standard provider and local catalog sources. It returns the complete unpublished state for runtime-candidate construction.
type SnapshotMetadata ¶ added in v1.1.0
type SnapshotMetadata struct {
GenerationID string `json:"generation_id"`
GeneratedAt time.Time `json:"generated_at"`
AgeSeconds int64 `json:"age_seconds"`
CatalogSequence uint64 `json:"catalog_sequence"`
AvailabilityRevision uint64 `json:"availability_revision"`
PayloadChecksum string `json:"payload_checksum"`
ManifestAvailable bool `json:"manifest_available"`
SchemaVersion uint64 `json:"schema_version,omitempty"`
PayloadSizeBytes int64 `json:"payload_size_bytes,omitempty"`
Completeness string `json:"completeness,omitempty"`
Degraded bool `json:"degraded"`
DegradationReasons []string `json:"degradation_reasons,omitempty"`
Validation ValidationSummary `json:"validation,omitzero"`
SourceObservations []SourceObservation `json:"source_observations,omitempty"`
SyncRunID string `json:"sync_run_id,omitempty"`
}
SnapshotMetadata is the freshness surface of the active catalog snapshot. The scalar identity always comes from the snapshot itself. Manifest detail comes from the stored generation record; when that record is missing the metadata says so instead of silently omitting fields.
type SnapshotSource ¶ added in v1.1.0
type SnapshotSource interface {
Current() *RoutableSnapshot
}
SnapshotSource supplies the active routable snapshot.
type Source ¶
type Source interface {
CurrentCatalogState() starmap.CatalogState
}
Source supplies one atomic Starmap catalog and generation pair.
type SourceObservation ¶ added in v1.1.0
type SourceObservation struct {
Source string `json:"source"`
ObservedAt time.Time `json:"observed_at"`
Completeness string `json:"completeness"`
Status string `json:"status"`
}
SourceObservation reports one acquisition source that fed the generation.
type ValidationSummary ¶ added in v1.1.0
type ValidationSummary struct {
Status string `json:"status"`
ErrorCount int `json:"error_count"`
WarningCount int `json:"warning_count"`
ValidatedAt time.Time `json:"validated_at"`
}
ValidationSummary condenses the generation validation report for operators.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package logos serves the bundled catalog identity marks.
|
Package logos serves the bundled catalog identity marks. |
|
Package view owns the console- and API-facing projections of one routable catalog snapshot.
|
Package view owns the console- and API-facing projections of one routable catalog snapshot. |