Documentation
¶
Overview ¶
Package settings owns the canonical catalog settings of one Starmap process. It maps every STARMAP_ catalog name onto exactly one connected-runtime option. No other catalog setting name exists.
Index ¶
Constants ¶
const ( // Source selects the upstream catalog source. The default is public. Source = Prefix + "CATALOG_SOURCE" // SourceURL is the safe endpoint or file identity of a custom source. SourceURL = Prefix + "CATALOG_SOURCE_URL" // SourceAPIKey is the Starmap protocol credential. It stays separate from // every provider credential. SourceAPIKey = Prefix + "CATALOG_SOURCE_API_KEY" // SourceRepository names the GitHub repository that holds the channel. SourceRepository = Prefix + "CATALOG_SOURCE_REPOSITORY" // SourceChannel names the mutable attested discovery channel. SourceChannel = Prefix + "CATALOG_SOURCE_CHANNEL" // SourceSignerWorkflow pins the accepted build provenance. SourceSignerWorkflow = Prefix + "CATALOG_SOURCE_SIGNER_WORKFLOW" // SourceToken is the optional GitHub API token. Public local use needs no // token. SourceToken = Prefix + "CATALOG_SOURCE_TOKEN" // SourcePollInterval is the conditional channel check period. SourcePollInterval = Prefix + "CATALOG_SOURCE_POLL_INTERVAL" // SourceStartupPolicy decides what the runtime serves before the first // upstream reply. SourceStartupPolicy = Prefix + "CATALOG_SOURCE_STARTUP_POLICY" // SourceMaxAge is the source freshness warning objective. SourceMaxAge = Prefix + "CATALOG_SOURCE_MAX_AGE" // SourceMaxHops bounds an accepted Starmap source chain. SourceMaxHops = Prefix + "CATALOG_SOURCE_MAX_HOPS" // SourceAliases lists the other stable identities of this same runtime, as // a comma-separated list. A served source chain that names one of them is // a self reference. SourceAliases = Prefix + "CATALOG_SOURCE_ALIASES" // AcquisitionEnabled turns automatic provider acquisition on or off. AcquisitionEnabled = Prefix + "CATALOG_ACQUISITION_ENABLED" // AcquisitionInterval is the acquisition period. Zero means one startup // pass while acquisition stays enabled. AcquisitionInterval = Prefix + "CATALOG_ACQUISITION_INTERVAL" // CoalesceWindow bounds how long a completed provider observation waits // for a slower sibling before it publishes. CoalesceWindow = Prefix + "CATALOG_COALESCE_WINDOW" // WorkspacePath names the reviewed operator catalog input. WorkspacePath = Prefix + "CATALOG_WORKSPACE_PATH" // StartupSpread is the stable admission window for cold automatic work. StartupSpread = Prefix + "CATALOG_STARTUP_SPREAD" // TransferIdleTimeout bounds a transfer that makes no progress. TransferIdleTimeout = Prefix + "CATALOG_TRANSFER_IDLE_TIMEOUT" // TransferMaxDuration bounds one finite HTTP body transfer. TransferMaxDuration = Prefix + "CATALOG_TRANSFER_MAX_DURATION" // RefreshTimeout is the optional whole-operation wall-clock cap. Zero adds // no cap. RefreshTimeout = Prefix + "CATALOG_REFRESH_TIMEOUT" // StateDirectory names the process-local runtime state directory. StateDirectory = Prefix + "STATE_DIR" // SchedulerIdentity replaces the derived stable instance identity. SchedulerIdentity = Prefix + "SCHEDULER_IDENTITY" )
The canonical catalog setting names. Each name selects one runtime option.
const Prefix = "STARMAP_"
Prefix is the canonical Starmap environment prefix. Starport uses STARPORT_ with the same suffixes and the same defaults.
Variables ¶
This section is empty.
Functions ¶
func Flags ¶
func Flags() []string
Flags returns the kebab-case flag name of every canonical setting. A flag carries the name of its setting without the prefix.
func Names ¶
func Names() []string
Names returns every canonical catalog setting name in documented order.
func RegisterFlags ¶
RegisterFlags registers one string flag for every canonical catalog setting. A flag carries the kebab-case name of its setting. A flag value follows the same grammar as the environment value, so one parser reads both.
Types ¶
type Composition ¶
type Composition struct {
// Config holds the canonical settings the process read.
Config Config
// Source supplies an upstream source implementation. It overrides the
// source that the settings select, so a test injects a hermetic source.
Source runtime.Source
// Acquirer collects provider observations. A runtime without one observes
// no provider.
Acquirer runtime.Acquirer
// LeaseStore fences the durable generation commit of a replicated
// deployment. A single instance needs none.
LeaseStore runtime.LeaseStore
// Base holds options that the process supplies before every setting. A
// canonical setting overrides a base option of the same name.
Base []runtime.Option
// Extra holds options that one command supplies last. The serve command
// supplies its listen address here, so two replicas on one host take
// separate schedule phases.
Extra []runtime.Option
}
Composition builds the connected runtime of one process. It joins the parsed canonical settings with the roles that the process injects: the catalog store, the provider acquirer, and an optional upstream source implementation.
The root package cannot construct the Starmap cascade source, because the cascade subscriber imports the root package. This composition step is therefore the one place that builds it from the canonical settings.
func (Composition) Open ¶
Open composes the options and opens the connected runtime. The runtime serves the verified embedded catalog immediately and pulls its source in the background.
func (Composition) Options ¶
func (c Composition) Options() ([]runtime.Option, error)
Options returns the runtime options in precedence order: the process base options first, then one option for each supplied canonical setting, then the injected roles. A later option replaces an earlier one, so a canonical setting always wins over a base default.
type Config ¶
type Config struct {
// SourceKind is the selected upstream source. The default is public.
SourceKind runtime.SourceKind
// SourceURL is the safe endpoint or file identity of a custom source.
SourceURL string
// SchedulerIdentity is the explicit stable instance identity. It spreads
// the cascade subscriber across the startup window of a fleet. An empty
// value leaves one process to reconnect at once.
SchedulerIdentity string
// SourceAPIKey is the Starmap protocol credential. It never reaches
// status, a log line, or an error, and only the composition step reads it.
SourceAPIKey string
// SourceMaxAge is the age at which the served catalog counts as stale.
// Zero selects the runtime default.
SourceMaxAge time.Duration
// SourceMaxHops bounds an accepted Starmap source chain. Zero selects the
// runtime default.
SourceMaxHops int
// SourceAliases lists the other stable identities of this same runtime.
SourceAliases []string
// StartupSpread is the window that admits cold automatic work. It spreads
// the first cascade link of a fleet. Zero selects the default.
StartupSpread time.Duration
// TransferIdleTimeout bounds a transfer that makes no progress. It bounds
// the cascade subscriber transport too.
TransferIdleTimeout time.Duration
// TransferMaxDuration bounds one finite HTTP body transfer of the cascade
// subscriber. It never bounds an open event stream.
TransferMaxDuration time.Duration
// WorkspacePath is the reviewed operator catalog input.
WorkspacePath string
// StateDirectory is the process-local runtime state directory.
StateDirectory string
// contains filtered or unexported fields
}
Config holds the canonical catalog settings that one process read. It carries one runtime option for each supplied setting. The parser accepts every canonical name, the starmap source included. Only Composition rejects a source that this build supplies no implementation for.
func Load ¶
Load reads every canonical catalog setting through lookup. An absent or empty setting keeps its canonical default. A supplied setting that names no valid value returns a typed validation error.
func (Config) Configured ¶
Configured returns the setting names the process supplied, in table order.
type Lookup ¶
Lookup reads one setting and reports whether the setting is present. os.LookupEnv satisfies it.
func Chain ¶
Chain reads each lookup in order and returns the first supplied value. An earlier lookup wins, so a flag overrides the environment.
func FlagLookup ¶
FlagLookup reads a canonical setting from a registered flag. It reports only a flag that the caller changed, so an untouched flag never replaces the environment value.
Source Files