catalogdistribution

catalogdistribution

import "github.com/agentstation/starmap/pkg/catalogdistribution"

Package catalogdistribution provides the versioned hosted catalog distribution contract used by starmap.agentstation.ai and Starport clients.

Index

• Constants
• type AssetDescriptor
• type Channel
  • func ParseChannel(value string) (Channel, error)
  • func (c Channel) String() string
  • func (c Channel) Validate() error
• type Client
  • func NewClient(baseURL string, httpClient *http.Client, schemaVersion uint64) (*Client, error)
  • func (c *Client) FetchChannel(ctx context.Context, channel Channel) (catalogstore.Generation, error)
  • func (c *Client) FetchLatest(ctx context.Context) (catalogstore.Generation, error)
  • func (c *Client) ProbeChannel(ctx context.Context, channel Channel, policy PromotionPolicy, observedAt time.Time) PromotionProbe
• type Handler
  • func NewHandler(repository Repository) (*Handler, error)
  • func (h *Handler) ServeHTTP(writer http.ResponseWriter, request *http.Request)
• type LatestPointer
  • func (p LatestPointer) String() string
• type MemoryRepository
  • func NewMemoryRepository() *MemoryRepository
  • func NewMemoryRepositoryWithPolicy(policy PromotionPolicy) (*MemoryRepository, error)
  • func (r *MemoryRepository) Get(generationID string) (PublishedGeneration, error)
  • func (r *MemoryRepository) Latest(schemaVersion uint64) (PublishedGeneration, error)
  • func (r *MemoryRepository) LatestForChannel(channel Channel, schemaVersion uint64) (PublishedGeneration, error)
  • func (r *MemoryRepository) Promote(channel Channel, generationID string, probe *PromotionProbe) error
  • func (r *MemoryRepository) PromotionEvents() []PromotionEvent
  • func (r *MemoryRepository) Publish(published PublishedGeneration) error
  • func (r *MemoryRepository) Rollback(channel Channel, generationID, reason string) error
• type PromotionAction
• type PromotionEvent
• type PromotionPolicy
  • func DefaultPromotionPolicy() PromotionPolicy
  • func (p PromotionPolicy) Validate() error
• type PromotionProbe
• type PublishedGeneration
  • func (p PublishedGeneration) Validate() error
• type Repository

Constants

const (
    // DefaultBaseURL is the canonical hosted catalog distribution origin.
    DefaultBaseURL = "https://starmap.agentstation.ai"
    // APIPrefix is the versioned hosted catalog route prefix.
    APIPrefix = "/v1/catalogs"
    // PointerVersion is the current latest-pointer schema.
    PointerVersion uint64 = 1
    // ImmutableCacheControl is sent for generation-addressed assets.
    ImmutableCacheControl = "public, max-age=31536000, immutable"
    // LatestCacheControl is sent for the mutable latest-compatible pointer.
    LatestCacheControl = "public, max-age=60, must-revalidate"
)

const (
    // DefaultMaxGenerationAge is the default stable-promotion freshness SLO.
    DefaultMaxGenerationAge = 7 * 24 * time.Hour
    // DefaultMaxProbeAge is the maximum age of hosted canary evidence used for
    // stable promotion.
    DefaultMaxProbeAge = 5 * time.Minute
    // DefaultMaxProbeLatency is the default hosted canary response SLO.
    DefaultMaxProbeLatency = 2 * time.Second
)

type AssetDescriptor

AssetDescriptor identifies one immutable hosted byte object.

type AssetDescriptor struct {
    URL       string `json:"url"`
    MediaType string `json:"media_type"`
    Checksum  string `json:"checksum"`
    SizeBytes int64  `json:"size_bytes"`
}

type Channel

Channel is a mutable hosted pointer with an explicit promotion role.

type Channel string

const (
    // ChannelDev receives a published generation first.
    ChannelDev Channel = "dev"
    // ChannelCanary receives only the generation currently selected in dev.
    ChannelCanary Channel = "canary"
    // ChannelStable receives only a canary generation with passing hosted SLO evidence.
    ChannelStable Channel = "stable"
)

func ParseChannel

func ParseChannel(value string) (Channel, error)

ParseChannel parses a channel query value. An empty value defaults to stable for backward-compatible consumer behavior.

func (Channel) String

func (c Channel) String() string

String returns the channel wire value.

func (Channel) Validate

func (c Channel) Validate() error

Validate verifies a supported promotion channel.

type Client

Client fetches and verifies hosted catalog generations.

type Client struct {
    // contains filtered or unexported fields
}

func NewClient

func NewClient(baseURL string, httpClient *http.Client, schemaVersion uint64) (*Client, error)

NewClient creates a hosted distribution client for one consumer schema.

func (*Client) FetchChannel

func (c *Client) FetchChannel(ctx context.Context, channel Channel) (catalogstore.Generation, error)

FetchChannel resolves, downloads, and verifies the latest compatible immutable generation selected for one explicit promotion channel.

func (*Client) FetchLatest

func (c *Client) FetchLatest(ctx context.Context) (catalogstore.Generation, error)

FetchLatest resolves, downloads, and verifies the latest compatible immutable generation before returning it.

func (*Client) ProbeChannel

func (c *Client) ProbeChannel(ctx context.Context, channel Channel, policy PromotionPolicy, observedAt time.Time) PromotionProbe

ProbeChannel fetches a hosted channel through the public HTTP protocol and returns evidence suitable for stable promotion under the supplied policy.

type Handler

Handler serves latest-compatible pointers and immutable generation assets.

type Handler struct {
    // contains filtered or unexported fields
}

func NewHandler

func NewHandler(repository Repository) (*Handler, error)

NewHandler creates the versioned hosted distribution HTTP adapter.

func (*Handler) ServeHTTP

func (h *Handler) ServeHTTP(writer http.ResponseWriter, request *http.Request)

ServeHTTP serves /v1/catalogs/latest and immutable generation assets.

type LatestPointer

LatestPointer selects one immutable generation compatible with a consumer's catalog schema.

type LatestPointer struct {
    Version               uint64                         `json:"version"`
    Channel               Channel                        `json:"channel"`
    GenerationID          string                         `json:"generation_id"`
    SchemaVersion         uint64                         `json:"schema_version"`
    ConsumerCompatibility catalogs.ConsumerCompatibility `json:"consumer_compatibility"`
    Artifact              AssetDescriptor                `json:"artifact"`
    Attestation           AssetDescriptor                `json:"attestation"`
}

func (LatestPointer) String

func (p LatestPointer) String() string

String returns a concise latest-pointer description.

type MemoryRepository

MemoryRepository is a thread-safe immutable hosted repository for tests and single-process deployments.

type MemoryRepository struct {
    // contains filtered or unexported fields
}

func NewMemoryRepository

func NewMemoryRepository() *MemoryRepository

NewMemoryRepository creates an empty hosted repository.

func NewMemoryRepositoryWithPolicy

func NewMemoryRepositoryWithPolicy(policy PromotionPolicy) (*MemoryRepository, error)

NewMemoryRepositoryWithPolicy creates an empty repository with explicit stable-promotion SLO budgets.

func (*MemoryRepository) Get

func (r *MemoryRepository) Get(generationID string) (PublishedGeneration, error)

Get returns one immutable generation by logical ID.

func (*MemoryRepository) Latest

func (r *MemoryRepository) Latest(schemaVersion uint64) (PublishedGeneration, error)

Latest returns the stable generation only when its catalog schema range is compatible with the requested consumer schema.

func (*MemoryRepository) LatestForChannel

func (r *MemoryRepository) LatestForChannel(channel Channel, schemaVersion uint64) (PublishedGeneration, error)

LatestForChannel returns the selected channel generation only when its catalog schema range is compatible with the requested consumer schema.

func (*MemoryRepository) Promote

func (r *MemoryRepository) Promote(channel Channel, generationID string, probe *PromotionProbe) error

Promote atomically advances a published generation through dev, canary, or stable. Canary requires the same dev selection. Stable additionally requires recent passing hosted canary evidence bound to the archive checksum.

func (*MemoryRepository) PromotionEvents

func (r *MemoryRepository) PromotionEvents() []PromotionEvent

PromotionEvents returns caller-owned promotion and rollback telemetry, including rejected attempts.

func (*MemoryRepository) Publish

func (r *MemoryRepository) Publish(published PublishedGeneration) error

Publish adds an immutable generation. An exact retry is idempotent; reuse of an existing generation ID with different bytes is a conflict.

func (*MemoryRepository) Rollback

func (r *MemoryRepository) Rollback(channel Channel, generationID, reason string) error

Rollback atomically moves a channel to a generation previously served by that same channel. The reason is mandatory operational telemetry.

type PromotionAction

PromotionAction describes a pointer-control operation.

type PromotionAction string

const (
    // PromotionActionPromote advances a generation through a channel.
    PromotionActionPromote PromotionAction = "promote"
    // PromotionActionRollback returns a channel to a prior generation.
    PromotionActionRollback PromotionAction = "rollback"
)

type PromotionEvent

PromotionEvent is immutable queryable pointer-control telemetry.

type PromotionEvent struct {
    Sequence   uint64
    Action     PromotionAction
    Channel    Channel
    From       string
    To         string
    ObservedAt time.Time
    Success    bool
    Reason     string
}

type PromotionPolicy

PromotionPolicy defines freshness and availability evidence required before a canary generation may become stable.

type PromotionPolicy struct {
    MaxGenerationAge time.Duration
    MaxProbeAge      time.Duration
    MaxProbeLatency  time.Duration
}

func DefaultPromotionPolicy

func DefaultPromotionPolicy() PromotionPolicy

DefaultPromotionPolicy returns the production default hosted SLO policy.

func (PromotionPolicy) Validate

func (p PromotionPolicy) Validate() error

Validate verifies positive promotion SLO budgets.

type PromotionProbe

PromotionProbe is hosted availability, freshness, latency, and identity evidence for one channel generation.

type PromotionProbe struct {
    Channel          Channel
    GenerationID     string
    ArtifactChecksum string
    ObservedAt       time.Time
    Latency          time.Duration
    Available        bool
    Fresh            bool
    Failure          string
}

type PublishedGeneration

PublishedGeneration is one verified generation and its exact distribution artifact set.

type PublishedGeneration struct {
    Generation catalogstore.Generation
    Artifact   catalogartifact.Artifact
}

func (PublishedGeneration) Validate

func (p PublishedGeneration) Validate() error

Validate verifies that the artifact opens to exactly the supplied generation.

type Repository

Repository is the narrow hosted read boundary.

type Repository interface {
    LatestForChannel(channel Channel, schemaVersion uint64) (PublishedGeneration, error)
    Get(generationID string) (PublishedGeneration, error)
}

Generated by gomarkdoc