catalog

Documentation

Overview

Package catalog ships a curated set of official Extension specs inside the binary and syncs them into the resource store, so a freshly installed Flynn already knows how to reach common services. The specs are data, not code: each is a JSON file in the embedded filesystem, admitted against the Extension kind like any other resource. A bundled extension carries a provenance label so it can be told apart from one the user authored or forked, and its name is reserved so a runtime spec cannot impersonate an official one.

Index

• Constants
• func Fork(ctx context.Context, store resource.Store, name string) error
• func Names() ([]string, error)
• func Reserved(name string) bool
• type Entry
  • func Entries() ([]Entry, error)
• type Result
  • func Sync(ctx context.Context, store resource.Store) (Result, error)

Constants

const (
	// SourceLabel records where an extension came from. A bundled extension is one
	// this binary ships; a forked extension started bundled and was edited by the
	// user, which the sync must not overwrite.
	SourceLabel = "catalog.ionagent.io/source"
	// SourceBundled marks an extension synced from the embedded catalog.
	SourceBundled = "bundled"
	// SourceForked marks a bundled extension the user has taken ownership of.
	SourceForked = "forked"
)

Functions

func Fork

func Fork(ctx context.Context, store resource.Store, name string) error

Fork takes user ownership of a bundled extension by relabeling it forked, so a later Sync leaves it and the user's edits alone. It is a no-op on an extension that is not bundled.

func Names

func Names() ([]string, error)

Names returns the official extension names in sorted order.

func Reserved

func Reserved(name string) bool

Reserved reports whether a name belongs to an official bundled extension. The runtime-authoring path consults this so a user or the agent cannot register a spec that impersonates an official one by claiming its name.

Types

type Entry

type Entry struct {
	Name string
	Spec extension.Spec
	Raw  json.RawMessage
}

Entry is one official extension from the embedded catalog: its name (the resource name it syncs under), the decoded spec, and the raw spec bytes stored verbatim so the resource carries exactly what shipped.

func Entries

func Entries() ([]Entry, error)

Entries returns the official catalog, parsed once and ordered by name so a sync is deterministic. A malformed embedded spec is a programming error in this package (the build-time gate exists to catch it), surfaced as an error here.

type Result

type Result struct {
	Created   int // bundled extensions newly added
	Updated   int // bundled extensions whose spec changed with the binary
	Unchanged int // bundled extensions already current
	Retired   int // bundled extensions removed from the catalog and deleted
	Forked    int // user-forked extensions left untouched
}

Result reports what a Sync did, for logging and tests.

func Sync

func Sync(ctx context.Context, store resource.Store) (Result, error)

Sync reconciles the embedded official catalog into the resource store. It is idempotent and preserves user intent:

• A new official extension is created, stamped as bundled.
• An official extension whose shipped spec changed is updated in place, carrying its observed status (so a disabled extension stays disabled) forward.
• An official extension already current is left alone (no version churn).
• An extension the user forked is never overwritten.
• A bundled extension no longer in the catalog (removed in a new binary) is retired.

The store must admit the Extension kind (register extension.KindDef first).