extension

type BackupController ¶ added in v1.0.11

type BackupController interface {
	// ListBackupInstances returns every live instance (across all known hosts)
	// that has at least one backup-marked volume, with those markers attached.
	ListBackupInstances(ctx context.Context) ([]BackupInstance, error)

	// LastBackupAt returns the finish time of the newest successful (complete)
	// backup for an instance, or the zero time if none exists. A scheduler uses
	// this for its interval gate.
	LastBackupAt(ctx context.Context, host, template, slug string) (time.Time, error)

	// EnqueueBackup enqueues a backup job for one instance (snapshotting all of
	// its backup-marked volumes) over the same path the HTTP POST /backups
	// handler uses, returning the new job id.
	//
	// It is authoritative for in-flight dedupe: if a backup job for this
	// instance is already queued, running, or reconciling, it enqueues nothing
	// and returns an empty jobID with a nil error. This lets a scheduler re-tick
	// freely without flooding the job store while a backup is still in progress
	// (a queued backup does not update LastBackupAt until it finishes).
	EnqueueBackup(ctx context.Context, host, template, slug string) (jobID string, err error)
}

BackupController is handed to a registered BackupScheduler so it can drive scheduled backups without reaching into internal/ packages. It exposes only the three capabilities a scheduler needs: discover backup-eligible instances, learn when each last succeeded, and enqueue a backup job.

type BackupInstance ¶ added in v1.0.11

type BackupInstance struct {
	Host     string
	Template string
	Slug     string
	Volumes  []BackupVolumeMarker
}

BackupInstance is one live instance that has at least one backup-marked volume, projected for a commercial BackupScheduler to act on. Volumes carries only the backup-marked volumes, each with its raw marker string. The marker grammar (e.g. cadence, mode) is owned by the commercial layer — the core projects the string verbatim and ascribes no meaning to it beyond "non-empty == marked for backup".

type BackupScheduler ¶ added in v1.0.11

type BackupScheduler interface {
	Run(ctx context.Context, c BackupController) error
}

BackupScheduler is the commercial hook for scheduled volume backups. When one is registered via server.WithBackupScheduler, the server starts it after wiring and runs it until the server's run context is cancelled, passing a BackupController. The implementation owns all timing, interval, and marker-grammar policy; the core ships no scheduling behavior of its own.

type BackupVolumeMarker ¶ added in v1.0.11

type BackupVolumeMarker struct {
	Name   string
	Backup string // raw marker, e.g. "s3; interval=6h"; never empty here
}

BackupVolumeMarker pairs a volume name with its raw backup marker.

type BlobStore ¶

type BlobStore interface {
	Put(ctx context.Context, key string) (BlobWriter, error)
	Get(ctx context.Context, key string) (io.ReadCloser, error)
	// DeleteAll removes every blob under the directory-like key prefix.
	// Removing an absent prefix is a no-op.
	DeleteAll(ctx context.Context, prefix string) error
}

BlobStore is where backup artifacts rest. The OSS implementation is a local directory (internal/backup.LocalDir); the commercial S3 backend implements the same seam. Keys are slash-separated relative paths (fs.ValidPath); Get returns an error satisfying errors.Is(err, fs.ErrNotExist) for a missing blob.

type BlobWriter ¶

type BlobWriter interface {
	io.Writer
	Commit() error
	Abort() error
}

BlobWriter is one streamed blob write. Exactly one of Commit or Abort must be called; only Commit makes the blob visible to Get. This is the temp-file+rename contract: a failed backup never leaves a partial blob that looks complete.

type InjectedSecret ¶ added in v1.0.9

type InjectedSecret struct {
	// Name is the short secret name (e.g. "litestream-s3-key"). The core
	// namespaces it to the instance as it does for template-declared secrets.
	Name string
	// Key is the data key within the Kubernetes Secret. The injected sidecar's
	// secretKeyRef.key references this value.
	Key string
	// Value is the plaintext secret value. The caller MUST NOT log or retain it.
	Value string
}

InjectedSecret is a secret declared by a SidecarInjector. The core creates it as a podman secret (using the same SecretCreate / wrapAsKubeSecret path used for template-declared secrets) before PlayKube and reaps it on instance Delete, so the injected sidecar can reference it via secretKeyRef instead of inlining a plaintext value.

Declaring a secret here is also what keeps it out of the instance API's env_summary: the core redacts any env value matching a secret it records for this instance — the values here plus any template-declared secrets in the stored spec — including env an injector added via secretKeyRef, which the template body cannot reveal (#198). That boundary is "values the core records for this instance", not "anything referenced via secretKeyRef": a secretKeyRef pointing at a pre-existing per-host secret (not part of the instance's stored spec) or an `envFrom: [{secretRef: …}]` bulk import (not parsed by the name pass at all) is NOT covered and will have its value returned in cleartext from GET /hosts/{host}/instances/{template}/{slug}. Prefer InjectedSecret for anything an injector needs redacted.

type RestoreIntent ¶ added in v1.0.12

type RestoreIntent struct {
	// Timestamp is the opaque point-in-time selector, interpreted by the injector.
	Timestamp string
	// Volumes restricts the restore to these volume names; empty means all of the
	// instance's backup-marked volumes.
	Volumes []string
}

RestoreIntent expresses a one-shot point-in-time restore for an instance. It is supplied on a single Apply (via ApplyOptions.RestoreIntent) and is NEVER persisted into the stored spec — so the reconcile/boot-converge path always passes nil and never replays the restore. That non-persistence is what makes a point-in-time rollback fire exactly once instead of repeating on every pod restart.

The core ascribes no meaning to Timestamp: it projects the value verbatim to the injector, which owns the interpretation (the Litestream injector uses RFC3339). An empty Timestamp is rejected by the restore trigger, not here.

type SidecarInjection ¶ added in v1.0.9

type SidecarInjection struct {
	// YAML is the (possibly modified) pod manifest. Return the input unchanged
	// to pass through.
	YAML string
	// Secrets is an optional list of secrets the injector needs the core to
	// create as podman secrets (referenced via secretKeyRef in YAML). Nil/empty
	// means no extra secrets.
	Secrets []InjectedSecret
}

SidecarInjection is the return type of SidecarInjector.InjectSidecars.

type SidecarInjector ¶ added in v1.0.8

type SidecarInjector interface {
	InjectSidecars(ctx context.Context, renderedYAML string, meta TemplateMeta, params map[string]any, slug string, restore *RestoreIntent) (SidecarInjection, error)
}

SidecarInjector is a commercial extension point that injects sidecar containers into an instance's pod YAML after the template body has been rendered but before it is applied.

The implementation receives the rendered pod YAML, the projected template metadata, the resolved template parameters, the instance slug, and an optional one-shot RestoreIntent (nil on a normal apply and on every reconcile; non-nil only on an explicit point-in-time restore). It returns the (possibly modified) YAML plus any secrets the core must create before PlayKube and prune on delete. Return SidecarInjection{YAML: renderedYAML} to pass through without injection.

type TemplateMeta ¶ added in v1.0.8

type TemplateMeta struct {
	// ID is the template identifier (render.Meta.ID).
	ID string
	// Volumes lists the template's declared volumes and their backup targets.
	// The Backup marker is meta-only — it is not present in the rendered pod
	// YAML — so a backup/PITR sidecar needs it from here.
	Volumes []TemplateVolume
}

TemplateMeta is a read-only projection of a template's metadata, handed to a SidecarInjector. It is a public type so the commercial module can consume it: the internal render.Meta cannot cross the module boundary (it lives under internal/), so the OSS core projects the fields an injector needs into this stable struct. New fields are added here as injectors come to need them.

type TemplateVolume ¶ added in v1.0.8

type TemplateVolume struct {
	Name   string // volume name as referenced in the pod spec
	Backup string // backup target/identifier; empty when not marked for backup
}

TemplateVolume is one volume declared by a template.