store

type Backup struct {
	ID       string
	Host     string
	Template string
	Slug     string
	State    BackupState
	Volumes  []BackupVolume
	Image    string // image ref at backup time; informational hint only
	Created  time.Time
	Finished time.Time // zero until complete/failed
}

type BackupState string

type BackupStore interface {
	// CreateBackup inserts a new row in state creating, stamping Created.
	// The caller supplies the ID (NewBackupID).
	CreateBackup(ctx context.Context, b Backup) error
	// CompleteBackup transitions creating → complete, recording the exported
	// volumes and Finished. CAS: returns false (no error) if the row is not
	// currently creating.
	CompleteBackup(ctx context.Context, id string, vols []BackupVolume) (bool, error)
	// FailBackup transitions creating → failed, setting Finished. CAS like
	// CompleteBackup.
	FailBackup(ctx context.Context, id string) (bool, error)
	GetBackup(ctx context.Context, id string) (Backup, error) // ErrNotFound when absent
	// ListBackups returns the instance's backups newest-first. limit <= 0 uses
	// DefaultJobLimit; clamped at MaxJobLimit.
	ListBackups(ctx context.Context, host, template, slug string, limit int) ([]Backup, error)
	// DeleteBackup removes the row; ErrNotFound when absent. Blob deletion is
	// the caller's job (instance.Service.DeleteBackup) — the store only holds
	// metadata.
	DeleteBackup(ctx context.Context, id string) error
}

type BackupVolume struct {
	Name      string          `json:"name"`
	SizeBytes int64           `json:"size_bytes"`
	Manifest  json.RawMessage `json:"manifest"`
}

type DB interface {
	Store
	JobStore
	TemplateStore
	BackupStore
	io.Closer
}

type Job struct {
	ID       string
	Kind     string
	Args     json.RawMessage // opaque to the store; handlers unmarshal their own shape
	State    JobState
	Steps    []JobStep
	ParentID string // "" if none
	Error    string
	Created  time.Time
	Started  time.Time // zero until claimed
	Finished time.Time // zero until done
}

type JobFilter struct {
	State    JobState
	Kind     string
	ParentID string
	Limit    int    // <=0 → DefaultJobLimit; values above MaxJobLimit are clamped
	Before   string // cursor: return jobs with id < Before
}

type JobState string

type JobStep struct {
	TS     time.Time `json:"ts"`
	Step   string    `json:"step"`
	Detail string    `json:"detail,omitempty"`
	// Count is the total number of consecutive identical occurrences of this
	// step, materialized only when coalesced (>1). 0/omitted ⇒ a single
	// occurrence. AppendStep collapses consecutive identical (Step, Detail)
	// rows so a long-looping reconcile can't grow the array unboundedly. (#117)
	Count int `json:"count,omitempty"`
}

type JobStore interface {
	// Enqueue inserts a new queued job, generating its ID. parentID is "" for
	// top-level jobs.
	Enqueue(ctx context.Context, kind string, args json.RawMessage, parentID string) (Job, error)
	// StartChild inserts a child job already in the running state (never queued),
	// owned by parentID. Because it is not queued, ClaimNext never claims it — the
	// caller (a parent job handler) drives it directly.
	StartChild(ctx context.Context, kind string, args json.RawMessage, parentID string) (Job, error)
	GetJob(ctx context.Context, id string) (Job, error) // ErrNotFound when absent
	ListJobs(ctx context.Context, f JobFilter) ([]Job, error)
	// ClaimNext atomically transitions the oldest queued job to running and
	// returns it. ok=false when there is nothing to claim.
	ClaimNext(ctx context.Context) (job Job, ok bool, err error)
	AppendStep(ctx context.Context, id string, step JobStep) error
	// Finish sets the terminal state, finished timestamp, and error (empty for
	// success). state must be JobSucceeded or JobFailed; passing any other value
	// is a programming error.
	Finish(ctx context.Context, id string, state JobState, errMsg string) error
	// FailRunning marks every job still in running as failed with reason; returns
	// the count. Called once at startup to reap crash-interrupted jobs.
	FailRunning(ctx context.Context, reason string) (int, error)
	// MarkReconciling moves every running job whose kind is in kinds to the
	// reconciling state (non-terminal); returns the count moved. Called once at
	// startup, before FailRunning, so reconcilable kinds are recovered rather than
	// failed. An empty kinds slice is a no-op returning 0.
	MarkReconciling(ctx context.Context, kinds []string) (int, error)
	// ResolveReconciling transitions a reconciling job to a terminal state
	// (succeeded or failed), setting finished + error. Compare-and-swap: it
	// affects only a row currently in reconciling, so it no-ops (returns false) if
	// an operator cancel already moved it. Passing any non-terminal state is a
	// programming error.
	ResolveReconciling(ctx context.Context, id string, state JobState, errMsg string) (bool, error)
	// CancelReconciling transitions a reconciling job to canceled, setting
	// finished. Compare-and-swap: affects only a row currently in reconciling,
	// returning false otherwise. Used by the cancel endpoint as the escape hatch.
	CancelReconciling(ctx context.Context, id string) (bool, error)
	// CancelQueued atomically transitions a still-queued job to canceled (setting
	// finished). Returns true if it transitioned; false if the job was not in the
	// queued state (already claimed, terminal, or absent).
	CancelQueued(ctx context.Context, id string) (bool, error)
	// PruneJobs deletes terminal (succeeded/failed) jobs finished before
	// olderThan, preserving parent/child integrity: a parent row is deleted only
	// when it has no surviving child. Returns the number of rows deleted.
	PruneJobs(ctx context.Context, olderThan time.Time) (int, error)
}

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

type Memory struct {
	PutErr    error
	DeleteErr error
	// contains filtered or unexported fields
}

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

type Spec struct {
	Host     string
	Template string
	Slug     string
	// Parameters is the instance's render parameters. NOTE: SQLite-backed
	// storage round-trips this through JSON, so numbers come back as float64
	// (e.g. an int 5432 becomes float64(5432)). Callers that re-render via
	// text/template are unaffected; callers must not type-assert .(int).
	Parameters map[string]any
	Secrets    map[string]string
	// Domains are the public hostnames the ingress layer routes to this
	// instance. Empty for non-web instances. Non-secret; stored in plaintext.
	Domains []string
	Created time.Time
	Updated time.Time
}

type SpecKey struct {
	Template string
	Slug     string
}

type Store interface {
	// PutSpec inserts or replaces the spec for (s.Host, s.Template, s.Slug).
	PutSpec(ctx context.Context, s Spec) error
	GetSpec(ctx context.Context, host, template, slug string) (Spec, error)
	DeleteSpec(ctx context.Context, host, template, slug string) error
	// ListSpecKeys returns the (template, slug) of every spec on host, without
	// decrypting secrets. Empty slice (no error) when the host has none.
	ListSpecKeys(ctx context.Context, host string) ([]SpecKey, error)

	// PutHostSecret inserts or replaces the sealed value of a per-host secret,
	// keyed by (host, name). Implementations seal Value at rest.
	PutHostSecret(ctx context.Context, host, name string, value []byte) error
	// GetHostSecret returns the decrypted per-host secret value, or ErrNotFound.
	GetHostSecret(ctx context.Context, host, name string) ([]byte, error)
	// DeleteHostSecret removes a per-host secret; absent is not an error.
	DeleteHostSecret(ctx context.Context, host, name string) error

	// SecretsEnabled reports whether this store can persist secrets — true only
	// when it was opened with an encryption key. Callers use it to reject a
	// secret-bearing operation BEFORE mutating any host, so a key-less store does
	// not leave orphaned host state when the later PutSpec fails with
	// ErrSecretsNeedKey.
	SecretsEnabled() bool
}

type Template struct {
	Meta    render.Meta
	Body    string
	Origin  string // "seed" | "user"
	Created time.Time
	Updated time.Time
}

type TemplateStore interface {
	ListTemplates(ctx context.Context) ([]Template, error)
	GetTemplate(ctx context.Context, id string) (Template, error)
	PutTemplate(ctx context.Context, t Template) error
	DeleteTemplate(ctx context.Context, id string) error
	CountTemplates(ctx context.Context) (int, error)
}