controlplane

type Capability string

type DeployResult struct {
	// Servers contains one entry per server in the resolved target set.
	Servers []ServerResult

	// PrimarySkipped is true when at least one primary app server was skipped
	// due to read-only capability. Callers should return a non-zero exit code.
	PrimarySkipped bool
}

type DrainResult int

type Environment struct {
	// Name is a well-known identifier: "local", "staging", "prod", or a
	// custom label defined by the operator.
	Name string `yaml:"name" json:"name"`

	// Kind is "local" for loopback environments and "remote" for SSH-accessed
	// environments. Capability resolution uses this to short-circuit probes.
	Kind                   string `yaml:"kind" json:"kind"`
	Tier                   Tier   `yaml:"tier,omitempty" json:"tier,omitempty"`
	RequireVerifiedRelease *bool  `yaml:"require_verified_release,omitempty" json:"require_verified_release,omitempty"`

	// Servers is the ordered list of hosts in this environment.
	Servers []Server `yaml:"servers" json:"servers"`
}

type Inventory struct {
	// SchemaVersion is incremented when the YAML structure changes in a
	// backward-incompatible way. Current supported version: 2.
	SchemaVersion int `yaml:"schema_version" json:"schema_version"`

	// Project is the canonical project name, matching the nSelf project
	// identifier (e.g. "nself", "ummat", "unity").
	Project string `yaml:"project" json:"project"`

	// Environments maps environment name to its definition. Keys must be unique
	// and match the Environment.Name field of their value.
	Environments map[string]Environment `yaml:"environments" json:"environments"`
}

type Prober interface {
	// SSHReachable attempts an SSH connection to s and returns (true, nil) on
	// success or (false, err) with a descriptive error on failure. The err
	// value is used to populate TargetStatus.Reason; callers must not treat
	// non-nil err as fatal — it may indicate a transient network condition.
	SSHReachable(s Server) (reachable bool, latencyMS int, err error)

	// DockerOK runs "docker info" over SSH and returns true when the Docker
	// daemon responds. It is only called when SSHReachable returns true.
	DockerOK(s Server) (bool, error)

	// KeyState checks whether the key referenced by s.SSHKeyRef exists on the
	// local filesystem. It returns the resolved key path for logging.
	// KeyState must not perform any network I/O.
	KeyState(s Server) (present bool, path string)
}

type RemoteApply struct {
	Set          deploy.ArtifactSet
	Expected     deploy.TargetSnapshot // the primary's snapshot the build used
	LocalPlugins []deploy.PluginRef
	ProdClass    bool // tier prod: verified backup, stateful recreate needs confirmation
	Yes          bool
	Confirm      func(msg string) bool
	StrictHasura bool
	Clock        docker.Clock
	Out          io.Writer
	// BackupID is the one verified database backup of the env, taken on its
	// primary (BackupHost) before any server was touched; other servers never run
	// `nself backup`. Empty off tier prod.
	BackupID, BackupHost string
	// Previous are the paths the env's previous deploy shipped (local record).
	Previous []string
	// Record is called after each server's apply, whether it succeeded or not.
	Record func(srv Server, res deploy.ApplyResult, err error)
	// Open opens the remote of a server; nil means the strict-host-key ssh
	// remote. Tests substitute a recorder.
	Open func(ctx context.Context, srv Server, keyPath, env string) (deploy.Remote, error)
}

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

type Selector struct {
	Env    string
	Tier   Tier
	Server string
}

type Server struct {
	// Name is a human-readable identifier unique within the environment.
	Name string `yaml:"name" json:"name"`

	// Role classifies the server's function (app, lb, observability, db, worker).
	Role ServerRole `yaml:"role" json:"role"`

	// Host is the SSH target in user@host form. Empty string means local-only
	// (capability is always "manage" for local environments).
	Host string `yaml:"host,omitempty" json:"host,omitempty"`

	// SSHKeyRef is the name of an environment variable whose value holds the
	// absolute path to the SSH private key. Never the key path itself.
	SSHKeyRef string `yaml:"ssh_key_ref,omitempty" json:"ssh_key_ref,omitempty"`

	// RemotePath is the absolute path on the remote host where the nSelf
	// stack is installed (e.g. /opt/nself). Used to locate nself-lb helper.
	RemotePath string `yaml:"remote_path,omitempty" json:"remote_path,omitempty"`

	// Primary marks the authoritative app server. The pipeline returns a
	// non-zero exit code if this server is skipped due to read-only capability.
	Primary bool   `yaml:"primary,omitempty" json:"primary,omitempty"`
	Arch    string `yaml:"arch,omitempty" json:"arch,omitempty"`

	// Upstreams lists the names of app-server backends this LB routes to.
	// Applicable only when Role == RoleLB.
	Upstreams []string `yaml:"upstreams,omitempty" json:"upstreams,omitempty"`
}

type ServerResult struct {
	// Env is the environment name.
	Env string

	// Server is the server name.
	Server string

	// Role is the server's role (used for ordering and reporting).
	Role ServerRole

	// Status is one of "ok", "skipped", "failed".
	Status string

	// Err is non-nil when Status == "failed".
	Err error

	// Primary marks whether this server is the primary app server.
	Primary bool
}

type ServerRole string

type Target struct {
	Env    string
	Tier   Tier
	Server Server
}

type TargetStatus struct {
	// Env is the environment name this status belongs to.
	Env string

	// Server is the server name within that environment.
	Server string

	// Capability is the resolved access level for this target.
	Capability Capability

	// SSHReachable is true when the SSH probe completed without error.
	SSHReachable bool

	// KeyPresent is true when the key file referenced by SSHKeyRef exists on
	// the local filesystem.
	KeyPresent bool

	// DockerOK is true when the docker-info probe over SSH succeeded.
	DockerOK bool

	// LatencyMS is the round-trip time of the SSH probe in milliseconds.
	// Zero if the probe was skipped (local environment, key absent, etc.).
	LatencyMS int

	// Reason provides the human-readable explanation for the assigned
	// Capability. Empty string means capability is CapManage (no caveat).
	Reason string

	// ProbedAt records when these probe results were obtained.
	ProbedAt time.Time
}

type Tier string