deploy

type ApplyOptions struct {
	Remote     Remote
	RemotePath string
	// Env names the environment, for the rollback hint in errors.
	Env string
	Set ArtifactSet
	// Expected is the snapshot the build used; the host must still match it.
	// Nil skips that comparison (the local-set comparison still runs).
	Expected     *TargetSnapshot
	LocalPlugins []PluginRef
	// ProdClass: take the verified snapshot and require confirmation for a
	// stateful recreate.
	ProdClass bool
	Yes       bool
	Confirm   func(msg string) bool
	// BackupID is a verified database backup the caller already took for the whole
	// env (one per env, on its primary, before any server is touched). When set,
	// no backup is taken here.
	BackupID string
	// Previous are the paths the env's previous deploy shipped or pruned, from the
	// local record (deploy.json). They alone decide what the prune may remove; the
	// host's own list can only narrow them. Empty: nothing is pruned.
	Previous []string
	// Snapshot takes and verifies a database backup tagged with id and returns
	// its backup id (E206 on failure). Used when ProdClass and BackupID is empty.
	Snapshot func(ctx context.Context, id string) (string, error)
	// StrictHasura makes a failed metadata apply fail the deploy.
	StrictHasura bool
	Clock        docker.Clock
	Out          io.Writer
	Now          func() time.Time
}

type ApplyResult struct {
	BackupID     string // verified database backup (prod-class only)
	BackupHost   string
	PreDeployTar string
	// Synced is true once the artifact sync started and the host's files were not
	// put back: the deploy record must be written. A deploy that failed before
	// the first `up` and was restored in place reports false (the last good
	// record stays); if that restore itself failed it stays true.
	Synced bool
	// Changed are the paths this deploy shipped or pruned, Absent the subset the
	// host did not have before. Recorded locally; they drive a rollback.
	Changed     []string
	Absent      []string
	Recreated   []string
	FrontRecord // the fronting stack's tar and changed/absent lists (D-0425)
	// Touched is true once the first `up` ran: containers may have changed, so
	// the env's database backup belongs in the record.
	Touched bool
}

type ArtifactSet struct {
	StageDir    string
	RemotePath  string
	Files       []string // relative to StageDir and to RemotePath; env files excluded
	EnvFiles    []string // relative; shipped 0600
	Compose     []string // remote absolute compose files, in -f order
	EnvManifest []string // remote absolute env files, in --env-file order
	// KeepHostEnv: the project .env is in EnvManifest but not shipped. It is the
	// host's own file (the target snapshot reads PLUGIN_DIR from it, the host's
	// nself reads it); the operator's copy would replace it with local values.
	// A sync only creates it, empty and 0600, when the host has none.
	KeepHostEnv bool
	// NotShipped are the nginx/ files of the scratch tree that were left out
	// (relative to RemotePath, sorted): not written by this build and not on the
	// operator's NSELF_DEPLOY_NGINX_INCLUDE allowlist (D-0423).
	NotShipped []string
	// Front is the fronting stack's second artifact root (D-0425); nil for a
	// project that runs its own nginx.
	Front *FrontRoot
}

type AuditEvent struct {
	EventType    string    `json:"event_type"`
	Service      string    `json:"service"`
	Environment  string    `json:"environment"`
	Reason       string    `json:"reason"`
	Outcome      string    `json:"outcome"`
	PriorVersion string    `json:"prior_version,omitempty"`
	Error        string    `json:"error,omitempty"`
	TriggeredBy  string    `json:"triggered_by"`
	Timestamp    time.Time `json:"timestamp"`
}

type BlueGreenConfig struct {
	// ProjectRoot is the nSelf project root (contains docker-compose.yml).
	ProjectRoot string

	// Target is the deploy target: local, staging, prod.
	Target string

	// DryRun prints steps without executing them.
	DryRun bool

	// HealthTimeoutSec overrides the default 30-second health check timeout.
	// Zero means use the default.
	HealthTimeoutSec int

	// ForceMigration disables the migration compatibility check and performs a
	// full blue-green flip even when backward-incompatible migrations are pending.
	ForceMigration bool
}

type BlueGreenResult struct {
	// Success is true when the deploy completed without error.
	Success bool

	// Steps is the ordered list of deploy steps with their status.
	Steps []bluegreen.DeployStep

	// Duration is how long the deploy took.
	Duration time.Duration

	// RolledBack is true when an automatic rollback was triggered.
	RolledBack bool

	// Error is set on failure.
	Error string
}

type CanaryConfig struct {
	// ProjectRoot is the nSelf project root (contains docker-compose.yml).
	ProjectRoot string

	// Target is the deploy target: local, staging, prod.
	Target string

	// InitialPercent is the initial canary traffic percentage (1-99).
	// Defaults to 10 when zero.
	InitialPercent int

	// SoakMinutes is the canary soak period in minutes. Defaults to 5.
	SoakMinutes int

	// ErrorThresholdPct is the error rate percentage that triggers auto-rollback.
	// Defaults to 1.0.
	ErrorThresholdPct float64

	// HealthTimeoutSec overrides the default 30-second health check timeout.
	// Zero means use the default.
	HealthTimeoutSec int

	// ForceMigration disables the migration compatibility check.
	// Required when a migration is not backward-compatible with canary traffic.
	ForceMigration bool

	// DryRun prints steps without executing them.
	DryRun bool
}

type CanaryResult struct {
	// Success is true when the deploy completed without error.
	Success bool

	// Steps is the ordered list of deploy steps with their status.
	Steps []bluegreen.DeployStep

	// Duration is how long the deploy took.
	Duration time.Duration

	// FinalPercent is the final canary traffic percentage (100 on success, 0 on rollback).
	FinalPercent int

	// RolledBack is true when an auto-rollback was triggered during the soak.
	RolledBack bool

	// Error is set on failure.
	Error string
}

type CertDir struct {
	Name                      string
	Fullchain, Privkey, Chain bool
}

type ComposeModel struct {
	Project  string
	Services map[string]ModelService
	Order    []string // `config --services` order
}

type FrontRecord struct {
	FrontTar     string
	FrontChanged []string
	FrontAbsent  []string
	// FrontShipped are the front files this deploy shipped (not the pruned ones):
	// the only paths the next deploy may prune.
	FrontShipped []string
	// FrontNames is the server_name set of each shipped file (the file as shipped).
	FrontNames map[string][]string
	// FrontSynced is true once the front sync started (the first front write was
	// allowed). A record carries the front fields only then: a deploy that stopped
	// before it (the re-check refused) changed nothing in the front root, and a
	// rollback must not restore a tar over files the deploy never touched.
	FrontSynced bool
}

type FrontRoot struct {
	StageDir   string   // where the files are staged locally
	RemotePath string   // the fronting stack's directory on the host
	Files      []string // relative to StageDir and RemotePath ("nginx/sites/<x>.conf")
	// Previous are, per host (the Remote label), the front paths this project's
	// previous deploy shipped there (the local deploy.json record); only they may
	// be pruned. Set by the command.
	Previous map[string][]string
	// PreviousNames are, per host and path, the server_name set that deploy shipped
	// there; a path without an entry is unknown (an old record) and is never pruned.
	PreviousNames map[string]map[string][]string
}

type KeptConfD struct {
	Path string
	// DefaultServerIn is set when the file was kept out because the host already
	// declares a default_server in that file (relative to the remote path);
	// empty when the host holds a hand-written file at Path.
	DefaultServerIn string
}

type ModelService struct {
	Spec          docker.ServiceSpec
	Image         string
	ContainerName string
	Mounts        []Mount
	Aliases       []string // network aliases, for the nginx -t host entries
}

type Mount struct {
	Type     string `json:"type"`
	Source   string `json:"source"`
	Target   string `json:"target"`
	ReadOnly bool   `json:"read_only"`
}

type NginxPolicy struct {
	// Generated reports whether a file head carries the generated marker of the
	// build (build.IsGeneratedNginxConf).
	Generated func(head []byte) bool
	// Include are validated allowlist globs relative to nginx/ (ParseNginxInclude).
	Include []string
}

type PathMap struct {
	ScratchRoot  string // the scratch project the build ran in
	OperatorRoot string // the operator's real project root
	PluginDir    string // the local plugin dir the build read
	Home         string // the operator's home dir (reported, never mapped)
	RemotePath   string // the project dir on the target
	// FrontRoot is, for a project fronted by another stack's nginx (D-0425), the
	// local scratch root of that stack: the parent of ScratchRoot. It maps to
	// path.Dir(RemotePath), after ScratchRoot -> RemotePath (longest first).
	FrontRoot string
}

type PluginRef struct {
	Name     string
	Version  string
	Disabled bool
}

type PreDeployBackup struct {
	ID     string
	Tar    string   // absolute path on the host
	Absent []string // artifact paths the host did not have at tar time
}

type PushSecretsOptions struct {
	// Target is the deploy target name (e.g. "ops", "staging", "prod").
	Target string

	// EnvFile is the local path to the .env file to push.
	// Defaults to {ProjectRoot}/.env.{Target}, falling back to {ProjectRoot}/.env.
	EnvFile string

	// RemotePath is the remote destination path. Defaults to ~/app/.env.
	RemotePath string

	// DryRun logs what would be done without executing scp.
	DryRun bool

	// ProjectRoot is the local project root used to resolve the default EnvFile.
	// Defaults to the current working directory when empty.
	ProjectRoot string
}

type RecreatePreview struct {
	Recreate []string // services that exist and would be recreated
	Create   []string // services that would be created new
	Stateful []string // the Recreate subset that keeps data
	// Unknown are dry-run lines about a recreate or create that did not parse or
	// did not map to a known service. A production-class deploy refuses on them.
	Unknown []string
}

type Remote interface {
	// Run runs one shell command string and returns its stdout. A non-zero
	// exit returns an error that carries the stderr tail.
	Run(ctx context.Context, command string) ([]byte, error)
	// Rsync copies the paths listed (one relative path per line) in filesFrom,
	// taken relative to srcDir, into destDir on the host, in place. flags are
	// extra rsync flags; a delete flag is refused.
	Rsync(ctx context.Context, flags []string, filesFrom, srcDir, destDir string) error
	// Label names the host for state records and messages.
	Label() string
}

type RemoteTarget struct {
	// SSHTarget is "user@host" (no path component).
	SSHTarget string
	// RemotePath is the absolute path on the remote host where the nSelf
	// project lives (used only for cd-prefixed commands; empty is fine for
	// a plain `docker exec`, which needs no working directory).
	RemotePath string
	// KeyPath is the SSH private key path.
	KeyPath string
}

type RestoreSpec struct {
	Changed []string
	Absent  []string
}

type RollbackConfig struct {
	// Service is the nSelf service to roll back (e.g., "ping_api").
	Service string

	// DeployKey is the deploy authorization key (NSELF_DEPLOY_KEY).
	// Required — no anonymous rollbacks.
	DeployKey string

	// Reason is a human-readable reason for the rollback.
	// Set by the SLO watcher: "slo-watcher: <alert description>"
	Reason string

	// Environment is "prod", "staging", etc. Defaults to "prod".
	Environment string

	// MaxRetries is the maximum number of rollback retry attempts. Default: 1.
	MaxRetries int

	// ProjectRoot is the nSelf project root directory. Used to locate
	// docker-compose.yml and state files.
	ProjectRoot string
}

type RollbackOptions struct {
	Remote     Remote
	RemotePath string
	Tar        string // PreDeployTar of the record
	BackupID   string // BackupID of the record; empty off prod-class
	// Changed and Absent come from the local deploy.json record of this host.
	Changed []string
	Absent  []string
	// DBRestored: the record says the database backup was already restored; it is
	// not restored again. OnDBRestored runs right after a successful restore,
	// before the re-apply, so the caller can persist it.
	DBRestored   bool
	OnDBRestored func() error
	// FrontTar, FrontChanged and FrontAbsent are the record of the fronting
	// stack's root (D-0425); all empty for a deploy that did not touch one.
	FrontTar     string
	FrontChanged []string
	FrontAbsent  []string
	StrictHasura bool
	Clock        docker.Clock
	Out          io.Writer
}

type RollbackResult struct {
	// Success is true if the rollback completed without error.
	Success bool

	// Service is the service that was rolled back.
	Service string

	// PriorVersion is the version that was restored.
	PriorVersion string

	// Error is set if rollback failed.
	Error string

	// AuditEventID is the ID written to np_auditlog_events.
	AuditEventID string

	// Duration is how long the rollback took.
	Duration time.Duration

	// UIState is one of the 7 UI states for the rollback.
	UIState RollbackUIState
}

type RollbackUIState string

type SSHConfig struct {
	// Host is the remote target in "user@host:/remote/path" format.
	// NSELF_DEPLOY_HOST is the conventional env var name.
	Host string
	// RemotePath is the separately configured install directory for canonical hosts.
	RemotePath string

	// KeyPath is the path to the SSH private key.
	// Falls back to NSELF_DEPLOY_KEY_PATH, then ~/.ssh/id_ed25519.
	KeyPath string

	// Follow streams container logs after a successful deploy until the
	// context is cancelled (e.g. Ctrl-C from the user).
	Follow bool

	// EnvFile, when set, is a local env file rsynced to <remote path>/.env.<EnvName>
	// right after the compose file, so the host gets the env the compose was
	// built from. EnvName must be a plain name (a-z, 0-9, _ and -).
	EnvFile string
	EnvName string
	// InventoryEnv is the inventory key used by the host-key enrolment command.
	InventoryEnv string
	// ServerName is the inventory key used by the host-key enrolment command.
	ServerName string
}

type SSHRemote struct {
	Spec remote.HostSpec
	// Opts are the ssh options placed before the HostSpec argv (-i, host key
	// policy, ForwardAgent=no).
	Opts []string
}

type StageInput struct {
	Map         PathMap
	StageDir    string   // a fresh empty dir
	Compose     []string // local compose files in order
	EnvFiles    []string // local env files in order (the compose env manifest)
	EnvSnapshot string   // local resolved env snapshot, shipped as .env.<EnvName> (optional)
	EnvName     string
	// Nginx decides which scratch nginx/ files ship; nil ships every non-conf.d
	// file (and no conf.d file). See NginxPolicy.
	Nginx *NginxPolicy
	// FrontScratch is the local scratch root of the fronting stack (the parent
	// of Map.ScratchRoot) and FrontedBy its NGINX_FRONTED_BY name; both empty
	// for a project that runs its own nginx. See artifacts_front.go.
	FrontScratch, FrontedBy string
}

type Strategy string

type StrategyState struct {
	// SchemaVersion is the version of the StrategyState schema.
	// Set to 1 on all writes. Readers treat 0 (missing field) as the legacy default.
	SchemaVersion int `json:"schema_version"`

	// Strategy is the deploy strategy used.
	Strategy Strategy `json:"strategy"`

	// Target is the deploy target: local, staging, prod.
	Target string `json:"target"`

	// StartedAt is the timestamp when the deploy started.
	StartedAt time.Time `json:"started_at"`

	// CompletedAt is the timestamp when the deploy completed (success or failure).
	CompletedAt time.Time `json:"completed_at"`

	// Success reports whether the deploy succeeded.
	Success bool `json:"success"`

	// CanaryPercent is the final canary traffic split at completion (0 or 100 for non-canary).
	CanaryPercent int `json:"canary_percent"`

	// RolledBack is true when the deploy triggered an automatic rollback.
	RolledBack bool `json:"rolled_back"`

	// Error is the failure reason when Success is false.
	Error string `json:"error,omitempty"`

	// BlueGreenStateFile is the path to the underlying blue/green state file,
	// populated when strategy is blue-green or canary.
	BlueGreenStateFile string `json:"blue_green_state_file,omitempty"`

	// BackupID is the verified database backup taken before a v1.5 remote apply
	// on a production-class target; BackupHost is the host it lives on, and
	// PreDeployTar the in-place file backup (every tier). `deploy rollback`
	// restores from them. Empty on every other deploy.
	BackupID     string `json:"backup_id,omitempty"`
	BackupHost   string `json:"backup_host,omitempty"`
	PreDeployTar string `json:"pre_deploy_tar,omitempty"`
	// PreDeployTars maps every host the deploy synced to its pre-deploy tar, so
	// `deploy rollback` restores each server of the env, not just the primary.
	PreDeployTars map[string]string `json:"pre_deploy_tars,omitempty"`
	// PreDeployChanged and PreDeployAbsent are, per host, the relative paths the
	// deploy shipped or pruned and the subset the host did not have before. A
	// rollback restores and removes exactly these, never anything read from the host.
	PreDeployChanged map[string][]string `json:"pre_deploy_changed,omitempty"`
	PreDeployAbsent  map[string][]string `json:"pre_deploy_absent,omitempty"`
	// FrontTars, FrontChanged and FrontAbsent are the same per host for the
	// fronting stack's root of a fronted project (D-0425): the front tar and the
	// nginx/sites paths shipped or pruned there. Absent on every other deploy, so
	// a record without them rolls back as before.
	FrontTars    map[string]string   `json:"front_tars,omitempty"`
	FrontChanged map[string][]string `json:"front_changed,omitempty"`
	FrontAbsent  map[string][]string `json:"front_absent,omitempty"`
	// FrontShipped is, per host, the front files that deploy shipped (not the pruned
	// ones): the only paths the next deploy may prune there. Without it nothing is.
	FrontShipped map[string][]string `json:"front_shipped,omitempty"`
	// FrontNames is, per host, the server_name set of each shipped front file: the
	// next deploy replaces or prunes a recorded path only while the host file still has it.
	FrontNames map[string]map[string][]string `json:"front_names,omitempty"`
	// DBRestoredAt is set (RFC 3339) right after `nself backup restore` succeeded,
	// before the re-apply, so a retried rollback never restores the database twice.
	DBRestoredAt string `json:"db_restored_at,omitempty"`
	// HostOutcomes is, per server name, what the deploy did there: "ok", "failed:
	// <err>" (changes kept) or "not changed: <err>" (refused or restored). Success
	// is true only when every server of the env is "ok".
	HostOutcomes map[string]string `json:"host_outcomes,omitempty"`
}

type TargetSnapshot struct {
	PluginDir string
	Plugins   []PluginRef
	SSL       []CertDir
	// FrontSSL is the fronting stack's <front>/ssl/certificates layout for a
	// fronted project (TakeFrontSSL); nil for a project that fronts itself.
	FrontSSL []CertDir
}

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