Documentation
¶
Overview ¶
Package app wires config, store, migrations, service, and the HTTP layer into the runnable subcommands.
Index ¶
- Constants
- Variables
- func AdminUsage(w io.Writer)
- func AuthComponents(cfg *config.Config) (crypto.PasswordParams, *admission.Limiter, error)
- func BackupUsage(w io.Writer)
- func EscrowUsage(w io.Writer)
- func GenerateReleaseCompatibility(ctx context.Context, request ReleaseCompatibilityRequest) ([]byte, error)
- func Logger(dev bool) *slog.Logger
- func RestoreUsage(w io.Writer)
- func RunAdmin(ctx context.Context, cfg *config.Config, log *slog.Logger, args []string, ...) error
- func RunAutomaticUpgrade(ctx context.Context, args []string, out io.Writer, ...) (err error)
- func RunBackup(ctx context.Context, cfg *config.Config, log *slog.Logger, args []string, ...) error
- func RunEscrow(ctx context.Context, cfg *config.Config, _ *slog.Logger, args []string, ...) error
- func RunMigrate(ctx context.Context, cfg *config.Config, log *slog.Logger) error
- func RunRestore(ctx context.Context, cfg *config.Config, log *slog.Logger, args []string, ...) error
- func RunUnattendedUpgrade(ctx context.Context, cfg *config.Config, options UnattendedUpgradeOptions) (cleanup func() error, err error)
- func RunUpgradeBackup(ctx context.Context, cfg *config.Config, args []string, out io.Writer, ...) error
- func RunUpgradeOperator(ctx context.Context, cfg *config.Config, args []string, out io.Writer) error
- type AutomaticHandoff
- type LeaseManager
- type ReleaseCompatibilityRequest
- type ScheduledJob
- type Scheduler
- type Server
- type Status
- type TrustContext
- type UnattendedUpgradeOptions
- type UpgradeDrillRequest
- type UpgradeDrillResult
- type UpgradeWindow
- func (u *UpgradeWindow) Close() error
- func (u *UpgradeWindow) Progress(phase string)
- func (u *UpgradeWindow) RuntimeStatus(context.Context) (service.RuntimeStatus, error)
- func (u *UpgradeWindow) Start(cfg *config.Config) error
- func (u *UpgradeWindow) Started() bool
- func (u *UpgradeWindow) Wait(ctx context.Context) error
Constants ¶
const MinRestoreSchemaVersion = 16
MinRestoreSchemaVersion is the first schema that carries the restore state a restore has to write (migration 00016, pinned to the migration file by TestMinRestoreSchemaVersionMatchesTheMigration). An archive below it is refused by name rather than failing deep inside the load transaction with a missing column — the operator's fix is "restore it with the binary that took it", and an error has to be able to say so.
Variables ¶
var Version = "dev"
Version is the build's version string, set from main's linker-stamped value. It is what /api/v1/meta advertises, so a client that refuses an operation above the server's API revision can name the version it refused.
Functions ¶
func AdminUsage ¶
AdminUsage is the frozen help text for the local-admin group.
func AuthComponents ¶
AuthComponents resolves the two authentication settings and, in doing so, runs two boot invariants that must fail fast rather than surface at the first login:
- the Argon2id parameters are checked against the floor the human-auth ADR fixes, and the server refuses to start below it;
- the admission budget must hold at least one verification plus the global headroom, so a configuration where one login cannot fit is a config error caught here, never a runtime surprise.
It deliberately does not build the service: the service holds the keyring, and the redaction analyzer bans key-bearing types from reaching a log call — so the caller assembles it and logs from these values instead.
func BackupUsage ¶
BackupUsage is the frozen help text for the export verb group.
func EscrowUsage ¶
EscrowUsage is the frozen help text for the escrow verb group.
func GenerateReleaseCompatibility ¶
func GenerateReleaseCompatibility(ctx context.Context, request ReleaseCompatibilityRequest) ([]byte, error)
GenerateReleaseCompatibility applies actual embedded migrations to both scratch engines and uses the same canonical domain catalog inspector as boot.
func RestoreUsage ¶
RestoreUsage is the frozen help text for the restore verb group.
func RunAdmin ¶
func RunAdmin(ctx context.Context, cfg *config.Config, log *slog.Logger, args []string, stderr io.Writer, terminalSession *disclose.TerminalSession, terminalError error, ) error
RunAdmin dispatches the local-admin verb group.
func RunAutomaticUpgrade ¶
func RunAutomaticUpgrade(ctx context.Context, args []string, out io.Writer, readPassword func(string) (string, error)) (err error)
RunAutomaticUpgrade is the root operator entrypoint. It is deliberately separate from the retired remotely callable updater and server boot path.
func RunBackup ¶
func RunBackup(ctx context.Context, cfg *config.Config, log *slog.Logger, args []string, stderr io.Writer, terminalSession *disclose.TerminalSession, terminalError error, ) error
RunBackup dispatches the export verb group.
func RunMigrate ¶
RunMigrate is `hikyo migrate`: explicit migration application. Loads no keyring (DDL only). Signed public evidence authorizes schema application; maintenance remains until the exact candidate boot proves hierarchy health.
func RunRestore ¶
func RunRestore(ctx context.Context, cfg *config.Config, log *slog.Logger, args []string, stderr io.Writer, _ *disclose.TerminalSession, _ error, ) error
RunRestore dispatches the restore verb group.
func RunUnattendedUpgrade ¶
func RunUnattendedUpgrade(ctx context.Context, cfg *config.Config, options UnattendedUpgradeOptions) (cleanup func() error, err error)
RunUnattendedUpgrade prepares the exact running image before ordinary Boot. It never selects latest, replaces the image executable or contacts Docker. The caller retains cleanup until server shutdown to serialize replacements sharing the installation's persistent upgrade directory.
func RunUpgradeBackup ¶
Types ¶
type AutomaticHandoff ¶
AutomaticHandoff asks the entrypoint to run the authenticated target's own coordinator. The current service executable has not been changed at this point.
func (*AutomaticHandoff) Error ¶
func (e *AutomaticHandoff) Error() string
type LeaseManager ¶
type LeaseManager interface {
// Now is the datastore clock. All lease-time comparisons read time from
// here so every node shares one clock, removing per-node skew as a
// split-brain vector.
Now(ctx context.Context) (time.Time, error)
// A nonzero fence returned alongside an error is provisional: it may
// only be confirmed by RenewLease or cleaned up by exact ReleaseLease.
ClaimLease(ctx context.Context, name, owner string, now, expires time.Time) (fence int64, held bool, err error)
RenewLease(ctx context.Context, name, owner string, fence int64, now, expires time.Time) (held bool, err error)
ReleaseLease(ctx context.Context, name, owner string, fence int64) error
}
LeaseManager is the fenced singleton lease the scheduler uses under HA. It is satisfied by *store.Coordination; the scheduler depends on the interface so the app layer never needs a datastore-typed field.
type ReleaseCompatibilityRequest ¶
type ReleaseCompatibilityRequest struct {
Profile releaseidentity.Profile
Version string
Sequence uint64
Commit string
Sources map[releaseidentity.Engine][]upgradecompat.SourceEdge
PostgreSQLDSN string
}
ReleaseCompatibilityRequest is build tooling input, never runtime admission. Sources come from a reviewed source-owned declaration. PostgreSQLDSN must identify an isolated empty scratch database; nonempty targets refuse writes.
type ScheduledJob ¶
type ScheduledJob struct {
Name string
Run func(context.Context) error
LastSuccess func(context.Context) (time.Time, bool, error)
}
ScheduledJob is one bounded background operation. LastSuccess reads the job's persisted health marker; nil means the job has no staleness contract.
type Scheduler ¶
type Scheduler struct {
Jobs []ScheduledJob
Interval time.Duration
Deadline time.Duration
Log *slog.Logger
Now func() time.Time
// Lease, NodeID, LeaseTTL, and Heartbeat drive HA leadership. When Lease
// is nil the scheduler is single-node and always runs its jobs (v1
// behaviour, unchanged). When set, jobs run only while this node holds the
// scheduler lease, so every singleton executes at most once across the
// cluster and a stale leader that loses the lease has its in-flight jobs
// cancelled. Its term identity also travels in the job context: tx.Write
// locks and validates that fence before mutation, so a paused leader cannot
// commit after takeover even before cancellation reaches it.
Lease LeaseManager
NodeID string
LeaseTTL time.Duration
Heartbeat time.Duration
// OnTick runs on every heartbeat on every node, leader or not. HA uses it
// to refresh this node's registry heartbeat (so nodes_seen stays accurate
// on standbys) and to sweep expired admission windows. Nil is a no-op.
OnTick func(context.Context)
// contains filtered or unexported fields
}
Scheduler runs every registered job once on startup and then hourly. Jobs share no transaction or deadline, so one failure cannot roll back another or silently disable future ticks.
type Server ¶
type Server struct {
Maintenance bool
Addr string
OperationalAddr string
CLISocket string
// contains filtered or unexported fields
}
Server is a booted, listening server that has not started serving yet.
func Boot ¶
Boot runs the fail-closed startup sequence: process hardening before any key material exists, migrations (auto-apply by default; with auto-apply disabled a pending migration state refuses to serve), datastore open with the boot-enforced pragma policy, keyring load (root key read, master key unwrapped or minted, root key zeroed), then the listener. Any error means the process must exit without serving.
func (*Server) ReloadTLS ¶
ReloadTLS preserves the applied managed certificate when SIGHUP is received.
func (*Server) ServeWithReady ¶
Serve blocks until ctx is cancelled, then shuts down gracefully. ServeWithReady runs both HTTP serving goroutines and calls ready (when non-nil) after they have started. The command uses the ready hook to present an accurate startup summary without teaching the application package about terminal output; tests pass nil.
type Status ¶
Status is service.Status, aliased so the printer's signature does not drag the service package into every caller's head.
type TrustContext ¶
type TrustContext struct {
BundleDirectory string
Pinned releasetrust.PinnedTrust
Target releaseidentity.Identity
Floor releaseidentity.SnapshotFloor
OperatorPin backupreceipt.PinnedOperator
}
TrustContext is supplied by the shared build/installation gate. No CLI flag can substitute a root, target identity, floor or current operator pin.
type UpgradeDrillRequest ¶
type UpgradeDrillRequest struct {
Scratch store.Config
Ciphertext *backupreceipt.Ciphertext
Receipt []byte
Plan upgradecompat.Plan
Operator backupreceipt.PinnedOperator
Unlock backup.Unlock
RootKey []byte
Principal domain.PrincipalID
Scope domain.Scope
Now time.Time
Lifetime time.Duration
// AutoCredentialProof selects one existing authorized principal only in
// this isolated scratch restore. Ordinary manual drills remain explicit.
AutoCredentialProof bool
}
type UpgradeDrillResult ¶
type UpgradeDrillResult struct {
Attestation []byte
HierarchyReadable bool
SecretProof string
CredentialProof string
}
UpgradeDrillResult contains public proof outcomes and an unsigned statement. Signing occurs only after this function has performed the actual recovery.
func DrillUpgrade ¶
func DrillUpgrade(ctx context.Context, request UpgradeDrillRequest) (UpgradeDrillResult, error)
DrillUpgrade is a local operator operation. It consumes separately supplied root escrow, decrypts a pinned copy in full, restores an empty scratch target, proves the existing hierarchy and never writes private custody to a server.
type UpgradeWindow ¶
type UpgradeWindow struct {
// contains filtered or unexported fields
}
UpgradeWindow owns temporary listeners while the unattended coordinator holds tenant serving closed. Start accepts authenticated effective configuration, never unvalidated bootstrap transport settings.
func NewUpgradeWindow ¶
func NewUpgradeWindow() *UpgradeWindow
func (*UpgradeWindow) Close ¶
func (u *UpgradeWindow) Close() error
func (*UpgradeWindow) Progress ¶
func (u *UpgradeWindow) Progress(phase string)
func (*UpgradeWindow) RuntimeStatus ¶
func (u *UpgradeWindow) RuntimeStatus(context.Context) (service.RuntimeStatus, error)
func (*UpgradeWindow) Started ¶
func (u *UpgradeWindow) Started() bool
Source Files
¶
- adapter_fake_aws_dev.go
- adapter_fake_dev.go
- adapter_loader.go
- adapter_provider.go
- admin.go
- admin_config.go
- app.go
- automatic_apply.go
- automatic_bundle_format.go
- automatic_release.go
- automatic_upgrade.go
- backup.go
- backup_admission.go
- backup_jobs.go
- backup_upgrade.go
- backup_upgrade_drill.go
- candidate_configuration.go
- dev_root.go
- dynamic.go
- escrow.go
- generation.go
- ha.go
- maintenance.go
- next_root_source.go
- operator.go
- owner_runtime.go
- pairing_identity.go
- pki.go
- privacy.go
- privacy_file_unix.go
- releasecompat.go
- runtime_listener.go
- runtime_serve.go
- scheduler.go
- sealed_webhook.go
- self_config.go
- self_config_deployment.go
- ssh.go
- tls.go
- unattended_credential_linux.go
- unattended_evidence.go
- unattended_process.go
- unattended_scratch.go
- unattended_upgrade.go
- upgrade_custody_source.go
- upgrade_gate.go
- upgrade_window.go