deploy

Documentation

Overview

Package deploy provides deployment management commands for the nSelf CLI. This file implements the SLO-triggered rollback path (S88d.T05).

The SLO watcher (slo-watcher.ts in ping_api) calls:

nself deploy --rollback --service <service> --key <deploy-key>

This package handles that invocation: validates the deploy key, logs to np_auditlog_events, runs the rollback, and returns exit 0 on success or non-zero on failure.

Index

• type AuditEvent
• type RollbackConfig
• type RollbackResult
  • func ExecuteRollback(ctx context.Context, cfg RollbackConfig) RollbackResult
• type RollbackUIState

Types

type AuditEvent

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"`
}

AuditEvent is written to np_auditlog_events on rollback.

type RollbackConfig

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
}

RollbackConfig holds the parameters for a deploy rollback.

type RollbackResult

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
}

RollbackResult is the outcome of a deploy rollback.

func ExecuteRollback

func ExecuteRollback(ctx context.Context, cfg RollbackConfig) RollbackResult

ExecuteRollback performs a service rollback. It: 1. Validates the deploy key 2. Discovers the prior container image tag 3. Re-deploys the prior image 4. Logs an audit event 5. Returns a RollbackResult with the UI state

type RollbackUIState

type RollbackUIState string

RollbackUIState represents the 7 possible states for rollback UI.

const (
	UIStateLoading     RollbackUIState = "loading"           // rollback in progress
	UIStateEmpty       RollbackUIState = "empty"             // no prior version to roll back to
	UIStateError       RollbackUIState = "error"             // rollback command failed
	UIStatePopulated   RollbackUIState = "populated"         // rollback complete + verified
	UIStateOffline     RollbackUIState = "offline"           // no staging connection
	UIStatePermDenied  RollbackUIState = "permission-denied" // no deploy key
	UIStateRateLimited RollbackUIState = "rate-limited"      // circuit breaker engaged
)