marketplace

package
v0.3.0-beta.13 Latest Latest
Warning

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

Go to latest
Published: Aug 11, 2026 License: MIT Imports: 27 Imported by: 0

Documentation

Overview

Package marketplace owns Compozy-curated discovery feeds and their durable projection.

Index

Constants

View Source
const (
	RefreshOutcomeSucceeded = "succeeded"
	RefreshOutcomeFailed    = "failed"
	InstallOutcomeSucceeded = "succeeded"
	InstallOutcomeFailed    = "failed"
	InstallPolicyGatePassed = "passed"
)
View Source
const CatalogSource = "compozy-catalog"
View Source
const ManifestVersion = 2
View Source
const RemoteSkillEntryPrefix = "skill_"

RemoteSkillEntryPrefix reserves the synthetic ID namespace used for registry-only skills.

Variables

View Source
var (
	ErrResponseTooLarge  = errors.New("marketplace catalog: response exceeds size limit")
	ErrSourceUnavailable = errors.New("marketplace catalog: source unavailable")
	ErrEntryNotFound     = errors.New("marketplace catalog: entry not found")
	ErrKindStateMissing  = errors.New("marketplace catalog: kind state missing")
	ErrServiceClosed     = errors.New("marketplace catalog: service is closed")
)
View Source
var (
	// ErrCatalogDecode reports malformed JSON or multiple JSON values in a catalog document.
	ErrCatalogDecode = errors.New("marketplace catalog: document decode failed")
	// ErrCatalogValidation reports a decoded catalog document that violates the catalog contract.
	ErrCatalogValidation = errors.New("marketplace catalog: document validation failed")
)

Functions

func DigestFile

func DigestFile(path string) (digest string, err error)

DigestFile computes the lowercase SHA-256 digest required by extension feed entries.

func NormalizeMCPInputValue

func NormalizeMCPInputValue(inputType string, raw string) (string, error)

NormalizeMCPInputValue validates and canonicalizes a catalog input value.

func ValidateCatalogDirectory

func ValidateCatalogDirectory(directory string) error

ValidateCatalogDirectory validates the complete publishable catalog using runtime schemas.

func ValidateMCPInputValue

func ValidateMCPInputValue(value string) error

ValidateMCPInputValue enforces transport-safe bounds shared by feed defaults and install values.

Types

type BrowseResult

type BrowseResult struct {
	Entries []Entry
	Total   int
	State   KindState
}

BrowseResult returns projected rows with their truthful freshness state.

type CatalogService

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

CatalogService coordinates TTL freshness and durable projections.

func NewService

func NewService(
	store Store,
	sources []Source,
	ttl time.Duration,
	refreshTimeout time.Duration,
	options ...ServiceOption,
) (*CatalogService, error)

NewService creates the internal curated catalog service.

func (*CatalogService) Browse

func (s *CatalogService) Browse(
	ctx context.Context,
	kind Kind,
	query string,
	offset int,
	limit int,
) (BrowseResult, error)

Browse refreshes stale state on demand, then returns the durable projection.

func (*CatalogService) Close

func (s *CatalogService) Close(ctx context.Context) error

Close cancels and joins every refresh flight owned by this service generation.

func (*CatalogService) Detail

func (s *CatalogService) Detail(ctx context.Context, kind Kind, entryID string) (*Entry, error)

Detail refreshes stale state on demand and resolves by immutable entry id.

func (*CatalogService) Refresh

func (s *CatalogService) Refresh(ctx context.Context, kinds ...Kind) (RefreshReport, error)

Refresh force-fetches selected kinds even when their TTL is still fresh.

func (*CatalogService) ResolveExtensionInstall

func (s *CatalogService) ResolveExtensionInstall(
	ctx context.Context,
	installSlug string,
	version string,
) (*Entry, error)

ResolveExtensionInstall returns a curated extension by exact slug and optional version.

func (*CatalogService) ResolveSkillInstalls

func (s *CatalogService) ResolveSkillInstalls(
	ctx context.Context,
	installSlugs []string,
) ([]Entry, error)

ResolveSkillInstalls returns the curated identities for exact remote skill slugs.

func (*CatalogService) Status

func (s *CatalogService) Status(ctx context.Context) ([]KindState, error)

Status returns deterministic state for every configured kind.

type DirectorySource

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

DirectorySource reads one per-kind document from an absolute file URL.

func NewDirectorySource

func NewDirectorySource(kind Kind, baseURL string) (*DirectorySource, error)

NewDirectorySource creates a bounded local-checkout catalog source.

func (*DirectorySource) Fetch

func (s *DirectorySource) Fetch(ctx context.Context) (document *Document, err error)

Fetch reads and validates the local document without mutating projection state.

func (*DirectorySource) Kind

func (s *DirectorySource) Kind() Kind

type Document

type Document struct {
	ManifestVersion int
	GeneratedAt     time.Time
	FetchedAt       time.Time
	Entries         []Entry
}

Document is one validated per-kind catalog snapshot.

func DecodeDocument

func DecodeDocument(kind Kind, raw []byte) (*Document, error)

DecodeDocument strictly validates one complete v2 document.

type Entry

type Entry struct {
	Kind         Kind
	EntryID      string
	Name         string
	Description  string
	Version      string
	PublishedAt  *time.Time
	UpdatedAt    *time.Time
	DigestSHA256 string
	Tier         string
	InstallSlug  string
	Payload      json.RawMessage
	FetchedAt    time.Time
}

Entry is the durable common projection plus the kind-specific payload.

type EntryDetails

type EntryDetails struct {
	Author    string
	Source    string
	MCP       *MCPEntryDetails
	Extension *ExtensionEntryDetails
	Skill     *SkillEntryDetails
}

EntryDetails is the typed public projection of one validated catalog payload.

func ProjectEntry

func ProjectEntry(entry Entry) (EntryDetails, error)

ProjectEntry decodes one already-validated catalog row without duplicating feed schemas downstream.

type ExtensionEntryDetails

type ExtensionEntryDetails struct {
	InstallSlug  string
	ArtifactURL  string
	DigestSHA256 string
	Repository   string
}

type ExtensionInstallResolutionError

type ExtensionInstallResolutionError struct {
	RefreshErr error
	LookupErr  error
}

ExtensionInstallResolutionError preserves refresh and last-known lookup failures.

func (*ExtensionInstallResolutionError) Error

func (*ExtensionInstallResolutionError) Unwrap

func (e *ExtensionInstallResolutionError) Unwrap() []error

type HTTPSource

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

HTTPSource fetches one per-kind document from the configured base URL.

func NewHTTPSource

func NewHTTPSource(kind Kind, baseURL string, client *http.Client, options ...HTTPSourceOption) (*HTTPSource, error)

NewHTTPSource creates one explicit-timeout feed source.

func (*HTTPSource) Fetch

func (s *HTTPSource) Fetch(ctx context.Context) (document *Document, err error)

Fetch downloads and validates the source document without mutating projection state.

func (*HTTPSource) Kind

func (s *HTTPSource) Kind() Kind

type HTTPSourceOption

type HTTPSourceOption func(*HTTPSource)

HTTPSourceOption customizes bounded feed fetching.

func WithMaxResponseBytes

func WithMaxResponseBytes(limit int64) HTTPSourceOption

WithMaxResponseBytes overrides the response cap, primarily for constrained deployments and tests.

type InstallOutcome

type InstallOutcome struct {
	Kind       Kind   `json:"kind"`
	EntryID    string `json:"entry_id"`
	Outcome    string `json:"outcome"`
	PolicyGate string `json:"policy_gate"`
}

InstallOutcome is the redacted canonical observation for one marketplace install attempt.

type Kind

type Kind string

Kind identifies one curated feed document and projection partition.

const (
	KindMCP       Kind = "mcp"
	KindExtension Kind = "extension"
	KindSkill     Kind = "skill"
)

func AllKinds

func AllKinds() []Kind

AllKinds returns the curated kinds in stable display-independent order.

type KindState

type KindState struct {
	Kind            Kind
	ManifestVersion int
	GeneratedAt     time.Time
	FetchedAt       time.Time
	Stale           bool
	LastError       string
	ErrorClass      string
	EntryCount      int
}

KindState reports the freshness and failure state for one feed projection.

type ListResult

type ListResult struct {
	Entries []Entry
	Total   int
}

ListResult is one deterministic page from the durable catalog projection.

type MCPAuthDetails

type MCPAuthDetails struct {
	Method       string
	Registration string
	Scopes       []string
}

type MCPEntryDetails

type MCPEntryDetails struct {
	Launch       MCPLaunchDetails
	Auth         *MCPAuthDetails
	Inputs       []MCPInputDetails
	DefaultScope string
}

MCPEntryDetails contains the feed-locked MCP install template.

type MCPInputBindingDetails

type MCPInputBindingDetails struct {
	Type string
	Name string
}

type MCPInputDetails

type MCPInputDetails struct {
	ID       string
	Prompt   string
	Type     string
	Required bool
	Binding  MCPInputBindingDetails
	Default  json.RawMessage
}

type MCPLaunchDetails

type MCPLaunchDetails struct {
	Type    string
	Package string
	Version string
	Image   string
	Digest  string
	URL     string
	Args    []string
}

type Notifier

type Notifier interface {
	NotifyCatalogRefresh(ctx context.Context, outcome RefreshOutcome) error
	NotifyInstall(ctx context.Context, outcome InstallOutcome) error
}

Notifier persists canonical marketplace observations.

type RefreshOutcome

type RefreshOutcome struct {
	Kind       Kind   `json:"kind"`
	Outcome    string `json:"outcome"`
	EntryCount int    `json:"entry_count"`
	Stale      bool   `json:"stale"`
	ErrorClass string `json:"error_class,omitempty"`
}

RefreshOutcome is the canonical per-kind refresh result.

type RefreshReport

type RefreshReport struct {
	Outcomes []RefreshOutcome `json:"outcomes"`
}

RefreshReport contains deterministic per-kind refresh outcomes.

type SQLiteStore

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

SQLiteStore maps validated catalog domain values to the global repository.

func NewSQLiteStore

func NewSQLiteStore(repository storepkg.MarketplaceCatalogRepository) (*SQLiteStore, error)

NewSQLiteStore binds the projection to the global SQLite repository.

func (*SQLiteStore) GetEntry

func (s *SQLiteStore) GetEntry(ctx context.Context, kind Kind, entryID string) (*Entry, error)

GetEntry returns one projected entry by immutable feed identity.

func (*SQLiteStore) GetExtensionByInstallSlug

func (s *SQLiteStore) GetExtensionByInstallSlug(
	ctx context.Context,
	installSlug string,
	version string,
) (*Entry, error)

GetExtensionByInstallSlug resolves one exact feed-authoritative extension acquisition row.

func (*SQLiteStore) KindState

func (s *SQLiteStore) KindState(ctx context.Context, kind Kind) (*KindState, error)

KindState returns persisted freshness plus the current projected row count.

func (*SQLiteStore) ListKind

func (s *SQLiteStore) ListKind(
	ctx context.Context,
	kind Kind,
	query string,
	offset int,
	limit int,
) (ListResult, error)

ListKind returns deterministic projected entries matching name or description.

func (*SQLiteStore) ListSkillsByInstallSlugs

func (s *SQLiteStore) ListSkillsByInstallSlugs(
	ctx context.Context,
	installSlugs []string,
) ([]Entry, error)

ListSkillsByInstallSlugs resolves exact curated skill acquisition identities in one read.

func (*SQLiteStore) MarkKindStale

func (s *SQLiteStore) MarkKindStale(
	ctx context.Context,
	kind Kind,
	errorClass string,
	lastError string,
) error

MarkKindStale records a redacted failure without touching projected entries.

func (*SQLiteStore) ReplaceKind

func (s *SQLiteStore) ReplaceKind(ctx context.Context, kind Kind, document *Document) error

ReplaceKind validates and atomically replaces one kind's projection.

type Service

type Service interface {
	Browse(ctx context.Context, kind Kind, query string, offset int, limit int) (BrowseResult, error)
	Detail(ctx context.Context, kind Kind, entryID string) (*Entry, error)
	ResolveExtensionInstall(ctx context.Context, installSlug string, version string) (*Entry, error)
	Refresh(ctx context.Context, kinds ...Kind) (RefreshReport, error)
	Status(ctx context.Context) ([]KindState, error)
	Close(ctx context.Context) error
}

Service exposes internal curated browse, detail, refresh, and status operations.

type ServiceOption

type ServiceOption func(*CatalogService)

ServiceOption customizes service time and observability seams.

func WithNotifier

func WithNotifier(notifier Notifier) ServiceOption

WithNotifier attaches the failure-isolated canonical refresh notifier.

func WithNow

func WithNow(now func() time.Time) ServiceOption

WithNow injects the UTC clock used for freshness decisions.

type SkillEntryDetails

type SkillEntryDetails struct {
	InstallSlug string
	DisplayName string
	Tags        []string
}

type SkillInstallResolver

type SkillInstallResolver interface {
	ResolveSkillInstalls(ctx context.Context, installSlugs []string) ([]Entry, error)
}

SkillInstallResolver batches curated identity reads for remote skill listings.

type Source

type Source interface {
	Kind() Kind
	Fetch(ctx context.Context) (*Document, error)
}

Source fetches and validates one curated kind.

func NewSource

func NewSource(kind Kind, baseURL string, client *http.Client) (Source, error)

NewSource creates a catalog source for an HTTP(S) endpoint or absolute file URL.

type Store

type Store interface {
	ReplaceKind(ctx context.Context, kind Kind, document *Document) error
	MarkKindStale(ctx context.Context, kind Kind, errorClass string, lastError string) error
	ListKind(ctx context.Context, kind Kind, query string, offset int, limit int) (ListResult, error)
	GetEntry(ctx context.Context, kind Kind, entryID string) (*Entry, error)
	GetExtensionByInstallSlug(ctx context.Context, installSlug string, version string) (*Entry, error)
	ListSkillsByInstallSlugs(ctx context.Context, installSlugs []string) ([]Entry, error)
	KindState(ctx context.Context, kind Kind) (*KindState, error)
}

Store persists the curated projection and freshness state.

type UnsupportedManifestVersionError

type UnsupportedManifestVersionError struct {
	Kind    Kind
	Version int
}

UnsupportedManifestVersionError reports a feed and client manifest-version mismatch.

func (*UnsupportedManifestVersionError) Error

Jump to

Keyboard shortcuts

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