persist

Documentation

Overview

Package persist snapshots cloudemu provider state to disk and restores it, so emulated resources survive a stop/start of the standalone server.

Persistence is fully generic and full-surface: it iterates the per-provider map of services that implement internal/snapshot.Snapshottable (produced by each provider factory's SnapshotServices()), captures each service's identity-preserving self-snapshot under ProviderState.Services keyed by service name, and restores each one through the same interface. Because resource ids and id-string cross-references are serialized as-is, a snapshot/restore round-trip is transparent to clients. The on-disk file is human-readable, diffable JSON rather than an opaque binary blob, and one snapshot format spans AWS, Azure, GCP, and OCI.

Index

• Constants
• func Restore(ctx context.Context, services Services, ps *ProviderState) error
• func RestoreAll(ctx context.Context, snap *Snapshot, targets map[string]Services) error
• type Meta
• type Options
• type ProviderState
  • func Export(ctx context.Context, services Services, opts Options) (ProviderState, error)
• type Services
• type Snapshot
  • func ExportAll(ctx context.Context, targets map[string]Services, opts Options) (Snapshot, error)
  • func ReadFile(path string) (Snapshot, error)
  • func (s Snapshot) WriteFile(path string) error

Constants

const SchemaVersion = 4

SchemaVersion is the on-disk snapshot format version. Bumped to 4 for the shared Kubernetes data-plane (#868): a top-level "kubernetes" field now sits alongside the per-provider state, so a v3 snapshot (which lacks it) can no longer be read into a build that expects it. It was bumped to 3 for the full-surface generic layout: every service captures itself under ProviderState.Services and the bespoke per-kind arrays of the v2 layout are gone. Snapshots are a dev-only convenience, so a clean break with a clear error is acceptable.

Functions

func Restore

func Restore(ctx context.Context, services Services, ps *ProviderState) error

Restore writes a provider state back into what should be a freshly-built (empty) provider, restoring each captured service through its mock's Snapshottable.Restore. A service captured in the snapshot but not present in services (e.g. a snapshot from a build with a wider surface) is skipped. Sorted iteration keeps restore order deterministic.

func RestoreAll

func RestoreAll(ctx context.Context, snap *Snapshot, targets map[string]Services) error

RestoreAll restores each provider present in snap into the matching target. Providers in the snapshot with no matching running target are skipped, and targets should be freshly rebuilt (empty) before calling.

Types

type Meta

type Meta struct {
	Name            string   `json:"name,omitempty"`
	CreatedAt       string   `json:"createdAt,omitempty"`
	CloudemuVersion string   `json:"cloudemuVersion,omitempty"`
	Providers       []string `json:"providers,omitempty"`
}

Meta is optional descriptive header for a named snapshot (the auto persist-on-stop file leaves it nil). It lets tooling describe a snapshot without restoring it.

type Options

type Options struct {
	// IncludeAssets includes large object bodies (e.g. S3 object bytes). When
	// false (the default) the snapshot is metadata-only, which keeps the file
	// small. The flag is threaded to each service's Snapshot, so a service that
	// distinguishes metadata from bulk bytes honors it.
	IncludeAssets bool
}

Options controls what Export captures.

type ProviderState

type ProviderState struct {
	Services map[string]json.RawMessage `json:"services,omitempty"`
}

ProviderState is a single provider's persisted resources: the per-service identity-preserving snapshots keyed by service name.

func Export

func Export(ctx context.Context, services Services, opts Options) (ProviderState, error)

Export captures a provider's current state by calling each service's identity-preserving self-snapshot, keyed by service name under ProviderState.Services. Keys are visited in sorted order for stable output.

type Services

type Services = map[string]snapshot.Snapshottable

Services maps a stable service name to the mock that snapshots itself. It is what a provider factory's SnapshotServices() returns and what Export/Restore iterate.

type Snapshot

type Snapshot struct {
	SchemaVersion int                      `json:"schemaVersion"`
	Meta          *Meta                    `json:"meta,omitempty"`
	Providers     map[string]ProviderState `json:"providers,omitempty"`

	// Kubernetes is the serialized shared Kubernetes data-plane (APIServer
	// state keyed by cluster UID). It is NOT part of any single provider —
	// AWS/Azure/GCP all register clusters into the same data plane — so it lives
	// at the top level rather than under Providers. It is populated and consumed
	// by the caller (server/serverkit), NOT by the generic ExportAll/RestoreAll,
	// which stay strictly provider-only: a direct ExportAll caller therefore gets
	// a k8s-less snapshot and must attach/restore this field itself if it wires a
	// data plane. Left nil (omitted) when no Kubernetes data plane is running.
	Kubernetes json.RawMessage `json:"kubernetes,omitempty"`
}

Snapshot is a multi-cloud, point-in-time capture of provider state, written as one JSON document.

func ExportAll

func ExportAll(ctx context.Context, targets map[string]Services, opts Options) (Snapshot, error)

ExportAll captures the state of every provider in targets into one Snapshot. It is the whole-emulator core shared by the persist-on-stop path and the snapshot admin endpoint. Each provider's value is its SnapshotServices() map.

func ReadFile

func ReadFile(path string) (Snapshot, error)

ReadFile loads a snapshot from disk, rejecting an incompatible schema version with a clear error rather than silently mis-restoring a stale layout.

func (Snapshot) WriteFile

func (s Snapshot) WriteFile(path string) error

WriteFile writes the snapshot as indented JSON, creating parent directories.