catalog

package
v1.0.2 Latest Latest
Warning

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

 Go to latest Published: Aug 11, 2026 License: AGPL-3.0 Imports: 22 Imported by: 0

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

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

Variables

View Source 
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")
	// ErrCatalogGenerationRequired means that a Starmap state has no generation identity.
	ErrCatalogGenerationRequired = errors.New("catalog state must contain a generation ID")
)

Functions

func ProviderFromModelID 

func ProviderFromModelID(modelID string) string

ProviderFromModelID returns the adapter ID named by a provider-scoped model ID.

func SplitModelID 

func SplitModelID(modelID string) (provider, model string, ok bool)

SplitModelID splits one provider-scoped model ID.

Types

type AdapterAvailability 

type AdapterAvailability struct {
	ProviderID       catalogs.ProviderID
	Registered       bool
	Configured       bool
	Operations       []catalogs.ProviderOperation
	EndpointTypes    []catalogs.EndpointType
	BaseURL          string
	EndpointBindings map[string]string
}

AdapterAvailability is runtime state for one provider adapter. It is not a catalog fact. The router can use an adapter only after registration and configuration.

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 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 catalogstore.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) (catalogstore.Generation, error)

Current returns the atomically selected generation.

func (*GenerationStore) Get 

func (s *GenerationStore) Get(ctx context.Context, generationID string) (catalogstore.Generation, error)

Get returns one immutable generation by ID.

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) 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) Offering 

func (s *RoutableSnapshot) Offering(route Route) (catalogs.ProviderOffering, error)

Offering returns one caller-owned offering from this exact generation.

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) ID 

func (r Route) ID() string

ID returns Starport's provider-scoped route ID.

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 

func (r Route) SupportsPromptCache() bool

SupportsPromptCache reports exact offering support. Unknown is not support.

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 tenant or operator observations through Starmap, then activates the resulting immutable generation.

func (*Runtime) Refresh 

func (r *Runtime) Refresh(ctx context.Context, options ...pkgsync.Option) (*pkgsync.Result, error)

Refresh runs Starmap acquisition and publishes any new generation into the Starport routable view.

func (*Runtime) Sync added in v1.0.2 

func (r *Runtime) Sync(
	ctx context.Context,
	options ...pkgsync.Option,
) (*pkgsync.Result, starmap.CatalogState, error)

Sync runs Starmap acquisition and returns the complete unpublished catalog state for runtime-candidate construction.

type Source 

type Source interface {
	CurrentCatalogState() starmap.CatalogState
}

Source supplies one atomic Starmap catalog and generation pair.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.