Add Cloud Snapshots: Named Save/Load/List of Emulator State (#335 P1)

cmd/cloudemu/lifecycle_other.go

@@ -10,3 +10,9 @@ import "errors"
 func runLifecycle(_ string, _ []string) error {
 	return errors.New("start/stop/status/logs/delete are only supported on Unix/macOS; run `cloudemu serve` instead")
 }
+
+// runSnapshot is unavailable off Unix for the same reason as the lifecycle
+// commands: it operates on the background daemon's run directory.
+func runSnapshot(_ []string) error {
+	return errors.New("snapshot is only supported on Unix/macOS")
+}

cmd/cloudemu/main.go

@@ -20,6 +20,7 @@ Usage:
   cloudemu status            Show whether the emulator is running and its endpoints
   cloudemu logs [-f]         Print (or follow) the background emulator's log
   cloudemu delete            Stop the emulator and remove its run directory
+  cloudemu snapshot ...      Save/load/list/delete named state snapshots
   cloudemu serve [flags]     Run the server in the foreground (see: cloudemu serve -h)
   cloudemu version           Print the version
   cloudemu help              Show this message
@@ -31,11 +32,12 @@ default; override with --home <dir>. Run "cloudemu serve -h" for serve flags.
 // Lifecycle subcommand names. Defined here (not in the Unix-tagged
 // lifecycle.go) so the dispatch compiles on every platform.
 const (
-	cmdStart  = "start"
-	cmdStop   = "stop"
-	cmdStatus = "status"
-	cmdLogs   = "logs"
-	cmdDelete = "delete"
+	cmdStart    = "start"
+	cmdStop     = "stop"
+	cmdStatus   = "status"
+	cmdLogs     = "logs"
+	cmdDelete   = "delete"
+	cmdSnapshot = "snapshot"
 )
 
 // version is overridable at build time with
@@ -59,6 +61,11 @@ func main() {
 			fmt.Fprintln(os.Stderr, "cloudemu:", err)
 			os.Exit(1)
 		}
+	case cmdSnapshot:
+		if err := runSnapshot(os.Args[2:]); err != nil {
+			fmt.Fprintln(os.Stderr, "cloudemu:", err)
+			os.Exit(1)
+		}
 	case "version", "-v", "--version":
 		fmt.Println("cloudemu", version)
 	case "help", "-h", "--help":

cmd/cloudemu/serve.go

@@ -3,6 +3,7 @@
 import (
 	"context"
 	"crypto/tls"
+	"encoding/json"
 	"errors"
 	"flag"
 	"fmt"
@@ -30,6 +31,10 @@
 // errStateFileRequired is returned when --persist is set without --state-file.
 var errStateFileRequired = errors.New("--persist requires --state-file")
 
+// errUnsupportedSnapshot is returned when a posted snapshot has an unknown
+// schema version.
+var errUnsupportedSnapshot = errors.New("unsupported snapshot schema version")
+
 // serveConfig holds the resolved serve flags.
 type serveConfig struct {
 	providers       string
@@ -96,7 +101,7 @@
 		return err
 	}
 	if (c.tlsCert == "") != (c.tlsKey == "") {
 		return errors.New("--tls-cert and --tls-key must be given together")
 	}
 
 	if c.persist && c.stateFile == "" {
@@ -245,17 +250,58 @@
 	// could POST /_cloudemu/reset.
 	if c.admin && !isLoopbackHost(c.host) {
 		fmt.Fprintf(os.Stderr,
-			"warning: --admin control plane (POST /_cloudemu/reset wipes all state) is reachable on non-loopback host %q; pass --admin=false to disable it\n",
+			"warning: --admin control plane is reachable on non-loopback host %q — "+
+				"POST /_cloudemu/reset wipes all state, and GET /_cloudemu/snapshot dumps "+
+				"all emulated state (including secret values) to any caller; "+
+				"pass --admin=false to disable it\n",
 			c.host)
 	}
 
+	// snapshotFn/restoreFn back /_cloudemu/snapshot; both act on the whole
+	// emulator like reset. snapshot captures current state as JSON; restore
+	// rebuilds to empty then loads the posted state.
+	snapshotFn := func() ([]byte, error) {
+		rebuildMu.Lock()
+		cur := targets
+		rebuildMu.Unlock()
+
+		snap, err := persist.ExportAll(context.Background(), cur, persist.Options{IncludeAssets: true})
+		if err != nil {
+			return nil, err
+		}
+
+		return json.MarshalIndent(snap, "", "  ")
+	}
+	restoreFn := func(body []byte) error {
+		var snap persist.Snapshot
+		if err := json.Unmarshal(body, &snap); err != nil {
+			return fmt.Errorf("parse snapshot: %w", err)
+		}
+
+		if snap.SchemaVersion != persist.SchemaVersion {
+			return fmt.Errorf("%w: got %d, want %d", errUnsupportedSnapshot, snap.SchemaVersion, persist.SchemaVersion)
+		}
+
+		// Destructive load (reset semantics): wipe to empty, then repopulate. If
+		// RestoreAll fails partway the running state is already gone — acceptable
+		// for a local emulator, but a future hardening is to restore into a
+		// staging build and swap it in only on success.
+		rebuild() // wipe to empty before loading
+
+		rebuildMu.Lock()
+		cur := targets
+		rebuildMu.Unlock()
+
+		return persist.RestoreAll(context.Background(), &snap, cur)
+	}
+
 	// handlerFor fronts a backend with the /_cloudemu control plane. With the
 	// admin API off the backend serves directly, so control paths fall through
 	// to the wire handlers (whatever they return for an unrouted path). seedFn
 	// may be nil (e.g. the Kubernetes port), which disables the seed endpoint.
 	handlerFor := func(b *admin.Backend, seedFn func([]byte) (int, error)) http.Handler {
 		if c.admin {
-			return admin.NewControl(b, rebuild, seedFn)
+			return admin.NewControl(b, rebuild, seedFn, snapshotFn, restoreFn)
 		}
 		return b
 	}
@@ -321,7 +367,7 @@
 
 	errCh := make(chan error, len(servers))
 	for i, s := range servers {
 		s := s
 		ln := listeners[i]
 		go func() {
 			var err error
@@ -397,36 +443,15 @@
 		return nil
 	}
 
-	for name := range snap.Providers {
-		t, ok := targets[name]
-		if !ok {
-			continue
-		}
-
-		ps := snap.Providers[name]
-		if err := persist.Restore(ctx, t, &ps); err != nil {
-			return fmt.Errorf("restore %s: %w", name, err)
-		}
-	}
-
-	return nil
+	return persist.RestoreAll(ctx, &snap, targets)
 }
 
 // snapshotState exports every running provider's state and writes the snapshot
 // file. Called after Shutdown, so the providers are quiescent.
 func snapshotState(ctx context.Context, path string, includeAssets bool, targets map[string]seed.Target) error {
-	snap := persist.Snapshot{
-		SchemaVersion: persist.SchemaVersion,
-		Providers:     make(map[string]persist.ProviderState, len(targets)),
-	}
-
-	for name, t := range targets {
-		ps, err := persist.Export(ctx, t, persist.Options{IncludeAssets: includeAssets})
-		if err != nil {
-			return fmt.Errorf("export %s: %w", name, err)
-		}
-
-		snap.Providers[name] = ps
+	snap, err := persist.ExportAll(ctx, targets, persist.Options{IncludeAssets: includeAssets})
+	if err != nil {
+		return err
 	}
 
 	return snap.WriteFile(path)
@@ -459,7 +484,7 @@
 			continue
 		}
 		if p != "aws" && p != "azure" && p != "gcp" {
 			return nil, fmt.Errorf("unknown provider %q (want aws, azure, or gcp)", p)
 		}
 		if !seen[p] {
 			seen[p] = true
@@ -467,7 +492,7 @@
 		}
 	}
 	if len(out) == 0 {
 		return nil, errors.New("no providers selected")
 	}
 	return out, nil
 }