service

type Account struct{ UID, GID int }

type DrainOptions struct {
	// Reason is the operator note the dispatcher switch carries.
	Reason string
	// Timeout bounds the whole drain. Zero uses DrainBudget.
	Timeout time.Duration
	// Disable also stops the unit from starting again on its own, so a
	// reboot during maintenance does not undo the drain. It applies to a
	// role that is drained by being stopped: a dispatcher is not stopped,
	// and its switch is a file an administrator owns that survives a reboot
	// on its own, so this says nothing about one.
	Disable bool
}

type DrainReport struct {
	Operation string `json:"operation"`
	Role      string `json:"role"`
	Name      string `json:"name"`
	Unit      string `json:"unit"`
	// Outcome is drained, paused, resumed, started or incomplete.
	Outcome string `json:"outcome"`
	// Joined reports proven local completion: the service manager reports
	// the unit inactive with a successful result and a zero exit status,
	// which is the daemon saying it released what it owned. It is the only
	// field that may be used to authorize deletion, an upgrade or closing
	// the database.
	Joined  bool   `json:"joined"`
	Enabled bool   `json:"enabled"`
	Active  string `json:"active,omitempty"`
	Ready   bool   `json:"ready,omitempty"`
	// Disposition is read from the persistent state once, after the join.
	Disposition *scheduler.Disposition `json:"disposition,omitempty"`
	StateDir    string                 `json:"state_dir,omitempty"`
	Changed     []string               `json:"changed,omitempty"`
	Note        string                 `json:"note,omitempty"`
}

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

type Maintenance struct {
	SchemaVersion int    `json:"schema_version"`
	Paused        bool   `json:"paused"`
	Reason        string `json:"reason,omitempty"`
	Since         string `json:"since,omitempty"`
}

type Manager interface {
	// Reload makes the manager re-read unit files from disk.
	Reload(ctx context.Context) error
	// Enable and Disable change only whether the unit starts at boot.
	Enable(ctx context.Context, unit string) error
	Disable(ctx context.Context, unit string) error
	// Start and Stop are synchronous: Stop returns when the manager has
	// finished stopping the unit or its own stop timeout expired.
	Start(ctx context.Context, unit string) error
	Stop(ctx context.Context, unit string) error
	// State reports what the manager believes about one unit.
	State(ctx context.Context, unit string) (UnitState, error)
}

type Options struct {
	// Root prefixes every managed path; empty means the real root.
	Root string
	// Manager is the service manager to drive. Required.
	Manager Manager
	// LookupAccount resolves the service account. nil uses the host's user
	// database.
	LookupAccount func(user, group string) (Account, error)
	// Chown applies the service account to one already-open managed file.
	// nil uses the operating system's fchown on the descriptor itself.
	Chown func(file *os.File, uid, gid int) error
	// ReadyTimeout bounds the readiness observation. Zero uses ReadyTimeout.
	ReadyTimeout time.Duration
	// StopTimeout bounds a stop and the verification that it finished. Zero
	// uses StopObservation, which allows for a daemon that uses its whole
	// shutdown budget.
	StopTimeout time.Duration
}

type Profile struct {
	Role demo.SchemaRole `json:"role"`
	Name string          `json:"name"`
	// Root is the filesystem prefix every path below is derived from.
	Root string `json:"root"`
	// Unit is the service-manager unit this instance owns.
	Unit string `json:"unit"`
	// User and Group are the service account the daemon runs as. The
	// account has to exist already: installing a service never creates,
	// modifies or removes an account.
	User  string `json:"user"`
	Group string `json:"group"`
	// Version and SourceSHA identify the verified installed payload this
	// unit starts, and PayloadRoot is that payload's directory.
	Version     string `json:"version"`
	SourceSHA   string `json:"source_sha"`
	PayloadRoot string `json:"payload_root"`
	// Executable is the daemon inside PayloadRoot the unit starts.
	Executable string `json:"executable"`
	// StateDir persists the database, the role identity and the generated
	// configuration across restarts; RuntimeDir holds only the readiness
	// record and is recreated for every start.
	StateDir   string `json:"state_dir"`
	RuntimeDir string `json:"runtime_dir"`
	UnitPath   string `json:"unit_path"`
	// ExecutorID is the persistent identity of a managed executor. A
	// restart keeps it; it is empty for a dispatcher.
	ExecutorID string `json:"executor_id,omitempty"`
	// HTTPPort and GRPCPort are the dispatcher's loopback listeners.
	HTTPPort int `json:"http_port,omitempty"`
	GRPCPort int `json:"grpc_port,omitempty"`
	// DispatcherGRPC and DispatcherHTTP are the control addresses a managed
	// executor connects to.
	DispatcherGRPC string `json:"dispatcher_grpc,omitempty"`
	DispatcherHTTP string `json:"dispatcher_http,omitempty"`
	// MaintenanceFile is the dispatcher's admission switch. Its presence
	// stops submission admission; it is empty for an executor.
	MaintenanceFile string `json:"maintenance_file,omitempty"`
	// ConfigPath, DatabasePath and ReadyFile are the generated
	// configuration, the served database and the readiness record.
	ConfigPath   string `json:"config_path"`
	DatabasePath string `json:"database_path"`
	ReadyFile    string `json:"ready_file"`
	// StopBudgetSeconds is the unit's stop timeout, recorded so an operator
	// reading the record knows the budget without parsing the unit.
	StopBudgetSeconds int `json:"stop_budget_seconds"`
}

type Report struct {
	Operation string `json:"operation"`
	Role      string `json:"role"`
	Name      string `json:"name"`
	Unit      string `json:"unit"`
	Version   string `json:"version"`
	// State is the observed outcome: installed, ready, started, stopped,
	// uninstalled, not-installed, or incomplete.
	State string `json:"state"`
	// Ready reports an observed readiness record published by the running
	// process, never the manager's belief that a process exists.
	Ready bool `json:"ready"`
	// Joined reports a daemon that finished its own shutdown. It is the
	// only thing that permits deleting, upgrading or rebuilding state.
	Joined     bool   `json:"joined,omitempty"`
	Enabled    bool   `json:"enabled"`
	Active     string `json:"active,omitempty"`
	MainPID    int    `json:"main_pid,omitempty"`
	ExecutorID string `json:"executor_id,omitempty"`
	Endpoint   string `json:"endpoint,omitempty"`
	StateDir   string `json:"state_dir,omitempty"`
	UnitPath   string `json:"unit_path,omitempty"`
	// Changed lists what this operation actually altered on disk or in the
	// service manager. A repeated identical install changes nothing.
	Changed []string `json:"changed,omitempty"`
	// RestartRequired reports a running unit whose unit file or generated
	// configuration changed. Installing never restarts a running daemon.
	RestartRequired bool `json:"restart_required,omitempty"`
	// Note carries the one thing an operator has to know that the fields
	// above do not already say.
	Note string `json:"note,omitempty"`
}

type Request struct {
	Role demo.SchemaRole
	Name string
	// Root prefixes every managed path. Empty means the real root.
	Root string
	// User and Group default to DefaultAccount.
	User, Group string
	// HTTPPort and GRPCPort are required for a dispatcher; a managed
	// service needs stable ports, so 0 is refused.
	HTTPPort, GRPCPort int
	// DispatcherGRPC and DispatcherHTTP are required for an executor.
	DispatcherGRPC, DispatcherHTTP string
}

type StagingManager struct{}

type Systemctl struct {
	// Path is the absolute systemctl binary. NewSystemctl resolves it.
	Path string
}

type UnitState struct {
	// Loaded reports whether the manager knows a unit of this name at all.
	Loaded bool
	// Active is the manager's active state ("active", "inactive",
	// "failed", "activating", "deactivating").
	Active string
	// Sub is the manager's finer substate ("running", "dead", "exited").
	Sub string
	// Enabled reports whether the unit starts on its own at boot.
	Enabled bool
	// MainPID is the daemon's process ID, or 0 when none is running. A
	// readiness record is only believed when it names this process.
	MainPID int
	// Result is how the manager's last attempt to run the unit ended:
	// "success", or "timeout", "exit-code", "signal", "core-dump",
	// "watchdog" and the like for a failure.
	Result string
	// ExecMainStatus is the daemon's exit status, or the signal number
	// that killed it.
	ExecMainStatus int
}