Help us shape the future of Go! Take the 2026 Go Developer Survey

app

package
v1.3.0 Latest Latest
Warning

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

 Go to latest Published: Oct 6, 2026 License: AGPL-3.0 Imports: 85 Imported by: 0

Documentation

Overview

Package app owns Starport production composition and lifecycle.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrConfigRequired reports an absent application configuration.
	ErrConfigRequired = errors.New("application config is required")
	// ErrStorageRequired reports a storage factory that returned no adapter.
	ErrStorageRequired = errors.New("storage factory returned no storage")

	// ErrBlobStorageRequired reports a file storage factory that returned no
	// store.
	ErrBlobStorageRequired = errors.New("file storage factory returned no store")
	// ErrCatalogRequired reports a catalog factory that returned no control plane.
	ErrCatalogRequired = errors.New("catalog factory returned no catalog")
	// ErrCredentialsRequired reports an absent provider-credential master key.
	ErrCredentialsRequired = errors.New("provider credential master key is required")
	// ErrAPIKeyRequired reports empty gateway API key storage.
	ErrAPIKeyRequired = errors.New("a gateway API key is required; run \"starport init\"")
	// ErrLocalTokenPathRequired reports a configuration with nowhere to keep this
	// machine's local admin token. The loader derives the path from the platform
	// paths, so an empty value means the configuration did not come from the
	// loader, and guessing a path here would put a credential somewhere the CLI
	// never looks.
	ErrLocalTokenPathRequired = errors.New("a local admin token path is required")
	// ErrLocalTokenExposed reports a gateway that would serve a never-rotated
	// local admin token on an address the network can reach.
	ErrLocalTokenExposed = errors.New("the local admin token has never been rotated")
	// ErrProviderCatalogChanged reports a credential result that was resolved
	// from a catalog generation that is no longer current.
	ErrProviderCatalogChanged = errors.New("provider catalog changed during reconciliation")
)
View Source 
var ErrBaselinePromotionPending = errors.New("baseline promotion is still pending")

ErrBaselinePromotionPending reports a promotion request that no leader settled within the wait.

View Source 
var ErrCatalogDirectoryOccupied = fmt.Errorf("%w: populated adoption requires a new empty catalog state directory", recovery.ErrConflict)

ErrCatalogDirectoryOccupied refuses populated adoption into a catalog state directory that a gateway owns.

Functions

func ApplyConfiguration added in v1.3.0 

func ApplyConfiguration(ctx context.Context, cfg *config.Config, request configrevision.ApplyRequest) (result configrevision.Result, err error)

ApplyConfiguration commits the validated local deployment values as the next shared revision and fences the fleet: it writes the applied policy record, and the next lease acquisition or renewal compares it. A rerun with the same operation ID continues an apply that committed. Resume repeats only the fleet phase. A rollback is a new apply with the previous values.

func ApplyImportedHistory added in v1.3.0 

func ApplyImportedHistory(ctx context.Context, cfg *config.Config, request recovery.ApplyHistoryRequest) (recovery.HistoryReplayReport, error)

ApplyImportedHistory accepts independent evidence and replays typed owner transitions. The command retains every import barrier and starts no gateway or background worker.

func CaptureBackup added in v1.3.0 

func CaptureBackup(ctx context.Context, cfg *config.Config, request recovery.CaptureRequest) (result recovery.CaptureResult, resultErr error)

CaptureBackup captures the configured stopped deployment without source refresh. It does not approve restoration or prove external fencing and later history.

func CatalogBaselineStatus added in v1.3.0 

func CatalogBaselineStatus(ctx context.Context, cfg *config.Config, options ...Option) (report runtimecatalog.BaselineReport, err error)

CatalogBaselineStatus compares the packaged baseline of this binary with the retained fleet baseline. It reads shared storage without a write, never takes the publication lease, and replays the fleet head in a temporary directory instead of the gateway state directory. A fleet without a head is not an error. The report then has only the deployment and the refusal.

func CloseBackupBoundary added in v1.3.0 

func CloseBackupBoundary(ctx context.Context, cfg *config.Config) (result recovery.Record, resultErr error)

CloseBackupBoundary closes admission approval without starting the gateway. Operators must separately stop and fence every writer before capture.

func EffectiveConfiguration added in v1.3.0 

func EffectiveConfiguration(ctx context.Context, cfg *config.Config) (report config.EffectiveReport, err error)

EffectiveConfiguration reports each catalog setting and its authority. Under shared management it reads the stored head without a write or a schema migration. It never falls back to local deployment values.

func InitializeFleet added in v1.3.0 

func InitializeFleet(ctx context.Context, cfg *config.Config, request recovery.FreshRequest) (record recovery.Record, err error)

InitializeFleet approves fresh shared storage without starting a gateway or source refresh.

func InitializeSharedConfiguration added in v1.3.0 

func InitializeSharedConfiguration(ctx context.Context, cfg *config.Config, request configrevision.Request) (result configrevision.Result, err error)

InitializeSharedConfiguration writes revision 1 of the shared configuration from the validated local deployment values. A preview validates the seed and reads the store without a write or a schema migration.

func InspectImportedBackup added in v1.3.0 

func InspectImportedBackup(ctx context.Context, cfg *config.Config, request recovery.InspectImportRequest) (recovery.ImportInspectionResult, error)

InspectImportedBackup checks the configured closed import against explicit retained identities. It never prepares targets, starts a gateway, or approves admission. Every writer must stay fenced.

func MigrateConfiguration added in v1.3.0 

func MigrateConfiguration(ctx context.Context, cfg *config.Config, target string, request configrevision.Request) (result configrevision.Result, err error)

MigrateConfiguration records an authority switch as a revision. To shared, it seeds from the validated local deployment values. A shared revision after a local one also writes the fleet policy record, because the record of an earlier shared revision would refuse every replica. To local, it records the final applied values and releases the shared authority.

func MigrateRuntime added in v1.3.0 

func MigrateRuntime(ctx context.Context, cfg *config.Config, phase string, migration catalog.RuntimeMigration) (result catalog.RuntimeMigrationResult, err error)

MigrateRuntime moves a stopped runtime. Shared storage reads its SQL recovery witness.

func PrepareBackup added in v1.3.0 

func PrepareBackup(ctx context.Context, cfg *config.Config, request recovery.PrepareRequest) (result recovery.PrepareResult, resultErr error)

PrepareBackup restores into the configured isolated targets without starting the gateway. The operator must stop and fence all writers. Preparation does not approve activation.

func PromoteCatalogBaseline added in v1.3.0 

func PromoteCatalogBaseline(
	ctx context.Context,
	cfg *config.Config,
	request runtimecatalog.PromotionRequest,
	wait time.Duration,
	recorded PromotionRecorded,
	options ...Option,
) (receipt runtimecatalog.PromotionReceipt, err error)

PromoteCatalogBaseline records a request to make the packaged baseline of this binary the retained fleet baseline. The gateway that holds the publication lease executes it. The command never takes the lease and never opens a gateway state directory. It waits for the outcome until wait ends. A refusal returns a refused receipt without an error.

func PublishBackupFiles added in v1.3.0 

func PublishBackupFiles(ctx context.Context, cfg *config.Config, request recovery.PublishFilesRequest) (result recovery.PublishFilesResult, err error)

PublishBackupFiles publishes one supported role at its configured canonical location. It verifies or resumes restricted preparation first. All writers must remain fenced. A publication error can leave a complete tree. Exact retries verify it without replacement.

func VerifyBackup added in v1.3.0 

func VerifyBackup(ctx context.Context, cfg *config.Config, request recovery.VerifyRequest) (recovery.CaptureResult, error)

VerifyBackup checks captured bytes and selected-key access without opening live stores.

func WriteImportedHistory added in v1.3.0 

func WriteImportedHistory(ctx context.Context, cfg *config.Config, request recovery.WriteHistoryRequest) (recovery.HistoryWriteReport, error)

WriteImportedHistory writes the final-only history package that binds a verified backup to the fenced target. The KV expectation comes from the backup and the SQL expectation from the target. No target store changes. The command starts no gateway or background worker and grants no admission.

Types

type App 

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

App owns all constructed runtime dependencies.

func New 

func New(cfg *config.Config, options ...Option) (*App, error)

New creates the complete production runtime without starting background work.

func (*App) CancelCatalogOperation added in v1.2.1 

func (a *App) CancelCatalogOperation(
	_ context.Context,
	id string,
) (runtimecatalog.Operation, error)

CancelCatalogOperation ends one open catalog operation.

func (*App) CatalogChanges added in v1.1.0 

func (a *App) CatalogChanges(ctx context.Context) (runtimecatalog.Diff, error)

CatalogChanges diffs the previous accepted generation against the current one.

func (*App) CatalogOperation added in v1.2.1 

func (a *App) CatalogOperation(_ context.Context, id string) (runtimecatalog.Operation, error)

CatalogOperation reports one catalog operation by identifier.

func (*App) CatalogStatus added in v1.2.1 

func (a *App) CatalogStatus(ctx context.Context) (runtimecatalog.AdminStatus, error)

CatalogStatus reports the operator view of the catalog runtime.

func (*App) CatalogSummary added in v1.2.1 

func (a *App) CatalogSummary(ctx context.Context) (runtimecatalog.Summary, error)

CatalogSummary reports the allowlisted catalog view a reader receives. It is the admin status passed through the reader projection, so the two surfaces cannot drift: one status, one allowlist.

func (*App) Close 

func (a *App) Close(ctx context.Context) error

Close stops owned dependencies in reverse construction order.

func (*App) ProviderIncidentLog added in v1.1.0 

func (a *App) ProviderIncidentLog(ctx context.Context, providerID catalogs.ProviderID) (statuspage.History, bool)

ProviderIncidentLog answers one provider's published incident log. The second return reports whether the catalog knows the provider at all, so the HTTP surface can separate "unknown provider" from "no log".

func (*App) ProviderIncidentTransitions added in v1.1.0 

func (a *App) ProviderIncidentTransitions(ctx context.Context, providerID catalogs.ProviderID) ([]providerstate.IncidentTransition, error)

ProviderIncidentTransitions answers the durable record of indicator changes this gateway observed for one provider, newest first.

func (*App) ProviderStates added in v1.0.3 

func (a *App) ProviderStates() providerstate.Snapshot

ProviderStates returns one secret-free provider runtime projection.

The routing verdicts refresh here rather than at each publish. The registry replaces the runtime adapter set on its own schedule — when it opens, when a connector registers, and when it closes — so no publish site in this package observes every change to the routable snapshot. Deriving the verdicts against whichever snapshot the control plane currently holds binds the projection to the state the caller is about to read instead of to whichever publish happened to run last.

func (*App) RefreshProviders added in v1.0.3 

func (a *App) RefreshProviders(ctx context.Context) (providers.ReconcileReport, error)

RefreshProviders forces one shared provider credential reconciliation. The HTTP admin route added by APR5 uses this application port.

func (*App) Run 

func (a *App) Run(ctx context.Context) error

Run starts explicit runtime work and closes all dependencies on exit.

func (*App) StartCatalogRefresh added in v1.2.1 

func (a *App) StartCatalogRefresh(context.Context) (runtimecatalog.Operation, bool, error)

StartCatalogRefresh accepts one catalog refresh and returns the operation that carries it. The second value reports that the request joined the run in flight rather than starting a second one.

The work outlives the request. An operator asked for the refresh, not for the response, so a client that disconnects does not end the run.

type Development added in v1.0.3 

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

Development owns one isolated local application and its one-time key.

func NewDevelopment added in v1.0.3 

func NewDevelopment(ctx context.Context, cfg *config.Config, options ...Option) (*Development, error)

NewDevelopment creates an in-memory gateway bound to loopback.

func (*Development) APIKey added in v1.0.3 

func (runtime *Development) APIKey() string

APIKey returns the one-time ephemeral gateway credential.

func (*Development) Close added in v1.0.3 

func (runtime *Development) Close(ctx context.Context) error

Close releases the development gateway and removes its scratch directory. The CLI calls it on every exit path, started or not.

func (*Development) ConsoleURL added in v1.1.0 

func (runtime *Development) ConsoleURL() (string, error)

ConsoleURL returns a one-time link that signs one browser in to this development gateway.

The session creates this link from its current address and port. It reads no link from a file. A saved link can identify another gateway.

func (*Development) Run added in v1.0.3 

func (runtime *Development) Run(ctx context.Context) error

Run starts the development gateway and closes it on exit.

func (*Development) URL added in v1.0.3 

func (runtime *Development) URL() string

URL returns the loopback gateway URL.

type Option 

type Option func(*buildOptions)

Option changes runtime factories for explicit test composition.

func WithBuildInfo added in v1.2.0 

func WithBuildInfo(version, commit, buildTime string) Option

WithBuildInfo states the version, commit, and build time the linker stamped into this binary, so the health and admin surfaces report the binary that answers. A runtime composed without it reports an unstamped build; the start time comes from the clock either way.

type PopulatedRecoveryPreparation added in v1.3.0 

type PopulatedRecoveryPreparation struct {
	PreparedSHA256 string `json:"prepared_sha256"`
	NextAction     string `json:"next_action"`
}

PopulatedRecoveryPreparation reports the retained prepared record. It grants no claim or permission.

func PreparePopulatedRecovery added in v1.3.0 

func PreparePopulatedRecovery(ctx context.Context, cfg *config.Config, request PopulatedRecoveryRequest) (result PopulatedRecoveryPreparation, resultErr error)

PreparePopulatedRecovery verifies C and H against the fenced live deployment and retains the native control observation. It places no claim. An exact retry returns the retained record and does not observe the controls again.

type PopulatedRecoveryRequest added in v1.3.0 

type PopulatedRecoveryRequest struct {
	Activation           RecoveryActivationRequest
	PriorApproval        recovery.Record
	PreparationDirectory string
	// ExpectedPreparedSHA256 must identify the retained prepared record on activation and inspection.
	ExpectedPreparedSHA256 string
}

PopulatedRecoveryRequest binds one fenced populated deployment to its capture C, the history H, and the prior approval. Activation holds the original activation inputs. Its backup is C, and H binds C.ImportIdentity(operation). The operator retains PriorApproval, the last open witness record, independently of the deployment. PreparationDirectory is an existing private directory that retains the prepared record. It is separate from the activation directory, because the activation journal admits only its own records.

func (PopulatedRecoveryRequest) Format added in v1.3.0 

func (PopulatedRecoveryRequest) Format(state fmt.State, _ rune)

Format excludes operator evidence, the prior approval, and private source paths.

func (PopulatedRecoveryRequest) Original added in v1.3.0 

func (r PopulatedRecoveryRequest) Original() PopulatedRecoveryRequest

Original removes the caller retry selectors from the immutable prepared inputs.

func (PopulatedRecoveryRequest) Validate added in v1.3.0 

func (r PopulatedRecoveryRequest) Validate() error

Validate checks the activation inputs, the prior approval shape, and each retry selector.

type PromotionRecorded added in v1.3.0 

type PromotionRecorded func(record runtimecatalog.PromotionRecord, leader string)

PromotionRecorded receives the pending request and the lease holder that executes it. The holder is empty when no gateway leads the fleet.

type RecoveryActivationRequest added in v1.3.0 

type RecoveryActivationRequest = recovery.ActivationRequest

RecoveryActivationRequest is the recovery owner's operator input contract.

type RecoveryActivationResult added in v1.3.0 

type RecoveryActivationResult = recovery.ActivationResult

RecoveryActivationResult reports the recovery owner's procedure outcome.

func ActivatePopulatedRecovery added in v1.3.0 

func ActivatePopulatedRecovery(ctx context.Context, cfg *config.Config, request PopulatedRecoveryRequest) (result RecoveryActivationResult, resultErr error)

ActivatePopulatedRecovery places the populated claims from the retained observation and accepts H with the closed-adoption transition. The shared activation phases then run unchanged. Exact sealed retries reopen owner evidence without a new claim.

func ActivateRecovery added in v1.3.0 

func ActivateRecovery(ctx context.Context, cfg *config.Config, request RecoveryActivationRequest) (result RecoveryActivationResult, resultErr error)

ActivateRecovery coordinates prepared native imports without starting a gateway. It binds original backup/history and current operator choices, then releases blobs, KV, and SQL. Exact sealed retries reopen owner evidence and native receipts without preparation or permission renewal.

func InspectPopulatedRecovery added in v1.3.0 

func InspectPopulatedRecovery(ctx context.Context, cfg *config.Config, request PopulatedRecoveryRequest) (result RecoveryActivationResult, resultErr error)

InspectPopulatedRecovery reports sealed historical completion and current permission of one populated adoption. It never claims, prepares, repairs, releases, captures, or renews permission.

func InspectRecoveryActivation added in v1.3.0 

func InspectRecoveryActivation(ctx context.Context, cfg *config.Config, request RecoveryActivationRequest) (result RecoveryActivationResult, resultErr error)

InspectRecoveryActivation reports sealed historical completion and current permission. It never prepares state, repairs records, publishes phases, releases imports, or renews permission.

type RecoveryOperatorInputsReport added in v1.3.0 

type RecoveryOperatorInputsReport struct {
	DecisionSHA256 string `json:"decision_sha256"`
	SelectedFiles  int    `json:"selected_files"`
	Restricted     bool   `json:"restricted"`
}

RecoveryOperatorInputsReport contains diagnostics without activation authority.

type RecoveryOperatorInputsRequest added in v1.3.0 

type RecoveryOperatorInputsRequest struct {
	Operation            recovery.RestoreOperation
	JournalDirectory     string
	ExpectedTargetSHA256 string
	ValkeyIncarnation    string
}

RecoveryOperatorInputsRequest binds existing target inputs to one fenced recovery operation. The caller retains external fencing and supplies opened native owner targets.

type VerifiedCanonicalFiles added in v1.3.0 

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

VerifiedCanonicalFiles retains checked application role selections and original publications. Its private state grants no permission, preparation, publication, or component release.

func InspectRecoveryCanonicalFiles added in v1.3.0 

func InspectRecoveryCanonicalFiles(ctx context.Context, cfg *config.Config, request recovery.PrepareRequest, body []byte, sealedSHA256 string) (*VerifiedCanonicalFiles, error)

InspectRecoveryCanonicalFiles reopens sealed evidence after any component release. The digest comes from the immutable activation decision, not a diagnostic report. It never prepares, publishes, repairs, reads external credentials, or issues permission.

func VerifyRecoveryCanonicalFiles added in v1.3.0 

func VerifyRecoveryCanonicalFiles(ctx context.Context, cfg *config.Config, request recovery.PrepareRequest, originals []recovery.PublishFilesResult) (*VerifiedCanonicalFiles, error)

VerifyRecoveryCanonicalFiles checks original successful owner results before the first release. The caller fences all writers and supplies only publications that returned without error. File dispositions come from the verified backup and current owner selections.

func (*VerifiedCanonicalFiles) Check added in v1.3.0 

func (v *VerifiedCanonicalFiles) Check(ctx context.Context, cfg *config.Config, request recovery.PrepareRequest) error

Check passively rechecks original publications and the current target selections.

func (*VerifiedCanonicalFiles) Digest added in v1.3.0 

func (v *VerifiedCanonicalFiles) Digest() string

Digest identifies checked evidence. A supplied digest cannot replace owner checks.

func (VerifiedCanonicalFiles) Format added in v1.3.0 

func (VerifiedCanonicalFiles) Format(state fmt.State, _ rune)

Format excludes native identities, paths, and secret-derived input digests.

func (*VerifiedCanonicalFiles) Record added in v1.3.0 

func (v *VerifiedCanonicalFiles) Record() ([]byte, error)

Record exports bounded original evidence for the immutable activation decision. The record contains no selected file contents and grants no activation authority.

type VerifiedOperatorInputs added in v1.3.0 

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

VerifiedOperatorInputs retains checked settings and selected local trust and administrator inputs. It does not release import barriers, grant catalog permission, or start a gateway.

func InspectRecoveryOperatorInputs added in v1.3.0 

func InspectRecoveryOperatorInputs(ctx context.Context, cfg *config.Config, db *sqlstore.DB, blobs blob.RestoreTarget, request RecoveryOperatorInputsRequest) (*VerifiedOperatorInputs, error)

InspectRecoveryOperatorInputs reopens the original decision without publication or repair. It checks current selected inputs and native targets without granting activation permission.

func VerifyRecoveryOperatorInputs added in v1.3.0 

func VerifyRecoveryOperatorInputs(ctx context.Context, cfg *config.Config, db *sqlstore.DB, blobs blob.RestoreTarget, request RecoveryOperatorInputsRequest) (*VerifiedOperatorInputs, error)

VerifyRecoveryOperatorInputs retains an immutable decision from the configured native targets. Exact retries recheck current selections. Captured backup configuration never replaces target inputs.

func (*VerifiedOperatorInputs) Check added in v1.3.0 

func (v *VerifiedOperatorInputs) Check(ctx context.Context, cfg *config.Config, db *sqlstore.DB, blobs blob.RestoreTarget, request RecoveryOperatorInputsRequest) error

Check rechecks owner inputs and the exact retained decision against opened native targets. The activation coordinator must call it under the original external fence.

func (VerifiedOperatorInputs) Format added in v1.3.0 

func (VerifiedOperatorInputs) Format(state fmt.State, _ rune)

Format excludes private paths, operator references, and secret-derived digests.

func (*VerifiedOperatorInputs) Record added in v1.3.0 

func (v *VerifiedOperatorInputs) Record() ([]byte, error)

Record exports original checked owner selections for the immutable activation decision. A supplied record or digest cannot replace current native owner checks.

func (*VerifiedOperatorInputs) Report added in v1.3.0 

func (v *VerifiedOperatorInputs) Report() RecoveryOperatorInputsReport

Report returns checked input counts. Admission remains closed.

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.