serverlifecycle

type Action string

type ContainerLauncher struct {
	// NewExecutor builds an executor over the store; it is called once per
	// launch or resume so each run has its own downloaded-artifact state.
	NewExecutor func() (*Executor, error)
	Log         *slog.Logger
	// contains filtered or unexported fields
}

type ContainerRestarter struct {
	// Shutdown asks this process to stop. The default sends SIGTERM to
	// itself, which the server handles the same way as one from outside: the
	// boot graph's stop path takes the nested stack down cleanly.
	Shutdown func() error
	// ExitAfter bounds the graceful stop: a restart that never finishes
	// stopping would leave the container running the build it was meant to
	// replace, with no supervisor to notice. 0 means DefaultExitAfter.
	ExitAfter time.Duration
}

type DataBackup interface {
	// Backup takes a snapshot for the operation and returns its reference.
	Backup(ctx context.Context, opID string) (string, error)
}

type DataRestore struct {
	BackupRef string `json:"backup_ref"`
	// ForVersion and ForCommit name the build the request is for: the one
	// being rolled back to. The request is persisted before the binary is
	// swapped, and the build being rolled back from may still be crash
	// looping under systemd at that point. If it honored the request it
	// would restore, migrate the data again, and fail, leaving a settled
	// request and migrated data for the build that actually needed it.
	ForVersion string `json:"for_version,omitempty"`
	ForCommit  string `json:"for_commit,omitempty"`

	RestoredAt *time.Time `json:"restored_at,omitempty"`
	Error      string     `json:"error,omitempty"`
}

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

type HealthProber struct {
	URL string
	// ServerName is the SNI to send. Empty works with the default autocert
	// ingress, which answers SNI-less handshakes with its self-signed cert.
	ServerName string
	// contains filtered or unexported fields
}

type InstanceProber struct {
	Source *serverinfo.Source
}

type LaunchChecker interface {
	Launched(ctx context.Context, opID string) bool
}

type Launcher interface {
	Launch(ctx context.Context, opID string) error
}

type NodeStep struct {
	Name     string `json:"name"`
	RunnerID string `json:"runner_id"`
	// OperationID is the runner-side operation, minted before the request
	// so a repeated request finds it rather than starting another.
	OperationID string `json:"operation_id,omitempty"`
	// Phase is the runner operation's phase as last observed, PhasePending
	// before the runner was asked, or StepSkipped.
	Phase           Phase  `json:"phase"`
	Error           string `json:"error,omitempty"`
	Progress        string `json:"progress,omitempty"`
	PreviousVersion string `json:"previous_version,omitempty"`
	NewVersion      string `json:"new_version,omitempty"`
	// Cordoned records that the walk cordoned the node for this step, so a
	// resumed walk knows to uncordon it. An operator's cordon is left alone.
	Cordoned bool `json:"cordoned,omitempty"`

	StartedAt  *time.Time `json:"started_at,omitempty"`
	FinishedAt *time.Time `json:"finished_at,omitempty"`
}

type Operation struct {
	ID          string `json:"id"`
	Action      Action `json:"action"`
	RequestedBy string `json:"requested_by,omitempty"`

	// TargetVersion is as requested ("latest", "main", a tag); ResolvedVersion
	// and ResolvedCommit are what it became.
	TargetVersion   string `json:"target_version,omitempty"`
	ResolvedVersion string `json:"resolved_version,omitempty"`
	ResolvedCommit  string `json:"resolved_commit,omitempty"`
	// ArtifactType ("base" or "release"), NoRollback, and ReadyTimeoutSeconds
	// override the executor defaults for one upgrade.
	ArtifactType        string `json:"artifact_type,omitempty"`
	NoRollback          bool   `json:"no_rollback,omitempty"`
	ReadyTimeoutSeconds int    `json:"ready_timeout_seconds,omitempty"`

	Phase Phase  `json:"phase"`
	Error string `json:"error,omitempty"`

	// BackupRef names the data snapshot taken before an upgrade; empty when
	// none was taken. DataRestore is set on rollback and asks the restarted
	// server to put BackupRef back before it serves data; the server's answer
	// lands in it once the executor has read the RestoreResult.
	BackupRef   string       `json:"backup_ref,omitempty"`
	DataRestore *DataRestore `json:"data_restore,omitempty"`
	// Progress is a short note for the current phase, e.g. a download percentage.
	Progress string `json:"progress,omitempty"`

	// DrivenBy is the server instance that took the operation over for the
	// runner phase, and Nodes is one step per runner it found. Both are set
	// together, so DrivenBy on a record with no Nodes means a cluster with
	// nothing to walk.
	DrivenBy string      `json:"driven_by,omitempty"`
	Nodes    []*NodeStep `json:"nodes,omitempty"`

	// A successful operation ends with NewInstanceID != PreviousInstanceID;
	// that change is how we know the restart actually happened.
	PreviousInstanceID string `json:"previous_instance_id,omitempty"`
	PreviousVersion    string `json:"previous_version,omitempty"`
	PreviousCommit     string `json:"previous_commit,omitempty"`
	NewInstanceID      string `json:"new_instance_id,omitempty"`
	NewVersion         string `json:"new_version,omitempty"`
	// Components are the runtime versions (containerd, runc, ...) the server
	// reported once it was up. A base upgrade replaces those binaries next to
	// miren, and this is the record that the restarted server is on them.
	Components map[string]string `json:"components,omitempty"`

	// RollbackFrom names the instance that asked for the rollback's restart,
	// so a resumed rollback can tell a restart that already took (the
	// instance answering now is a different one) from one still to do. The
	// systemd executor outlives the restart and never resumes; the container
	// executor is that instance and dies at the restart it asks for.
	// container-boot, rolling back a build that never answered, writes its
	// own name.
	RollbackFrom string `json:"rollback_from,omitempty"`
	// BootAttempts counts container boots of the new build since the restart
	// phase, kept by container-boot; it is what catches a build that crashes
	// before the executor inside it can run.
	BootAttempts int `json:"boot_attempts,omitempty"`

	CreatedAt  time.Time  `json:"created_at"`
	UpdatedAt  time.Time  `json:"updated_at"`
	FinishedAt *time.Time `json:"finished_at,omitempty"`
}

type Options struct {
	ServiceName string
	// Daemon names what is being restarted in progress notes and errors:
	// "server" or "runner".
	Daemon string
	// StateDir is the daemon's state directory, passed through to the
	// resource-limit refresh that precedes a restart.
	StateDir     string
	InstallPath  string
	TempDir      string
	ArtifactType release.ArtifactType
	// ReadyTimeout bounds how long a restarted server gets to report ready
	// before the operation fails (and, for upgrades, rolls back).
	ReadyTimeout  time.Duration
	ProbeInterval time.Duration
	AutoRollback  bool
	// PathSymlink, when set, is kept pointing at InstallPath after a
	// successful upgrade so the CLI on $PATH tracks the server.
	PathSymlink string
	// UpgradeRunners hands a verified upgrade to the daemon for the
	// upgrading_runners phase instead of finishing it. On for the server,
	// which has runners; off for a runner, which is one.
	UpgradeRunners bool
}

type Phase string

type Prober interface {
	Probe(ctx context.Context) (Snapshot, error)
}

type Restarter interface {
	Restart(ctx context.Context) error
}

type RestoreResult struct {
	OperationID string    `json:"operation_id"`
	BackupRef   string    `json:"backup_ref"`
	RestoredAt  time.Time `json:"restored_at"`
	Error       string    `json:"error,omitempty"`
	// Abandoned records that an operator gave up on the restore and told the
	// server to start on the data as it is.
	Abandoned bool `json:"abandoned,omitempty"`
}

type Snapshot struct {
	InstanceID  string
	Version     string
	Commit      string
	Ready       bool
	InstallKind string
	// Components are the runtime versions the server reports driving
	// (containerd, runc, ...); nil from a server that predates the report.
	Components map[string]string
}

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

type SystemdLauncher struct {
	Binary string
	// Command is the subcommand that runs the executor, without the binary
	// and without the operation flag. Nil means ServerExecutorCommand.
	Command []string
}

type SystemdRestarter struct {
	Unit string
	// StateDir is the daemon's state directory; the resource-limit drop-in
	// refreshed before each restart records stop reasons there.
	StateDir string
}

type UnsupervisedLauncher struct{}