[live-migration] adds the snapshot proto for the shim state

As part of live migration workflow, we need to snapshot the current state of the shim and then restore the same at the destination side. This change adds the proto which is a well-typed structure for the shim state used during Save/Restore.

Signed-off-by: Harsh Rawat <harshrawat@microsoft.com>

Author: rawahars

Protobuild.toml

@@ -19,6 +19,7 @@ prefixes = [
   "github.com/Microsoft/hcsshim/internal/shimdiag",
   "github.com/Microsoft/hcsshim/internal/extendedtask",
   "github.com/Microsoft/hcsshim/internal/computeagent",
+  "github.com/Microsoft/hcsshim/internal/controller/migration/snapshot",
   "github.com/Microsoft/hcsshim/internal/ncproxyttrpc",
   "github.com/Microsoft/hcsshim/internal/vmservice",
   "github.com/Microsoft/hcsshim/pkg/migration",

internal/controller/migration/snapshot/constants.go

@@ -0,0 +1,13 @@
+//go:build windows
+
+package snapshot
+
+// SchemaVersion is the on-the-wire compatibility version for
+// [SandboxSnapshot]. Bump on any breaking change to snapshot.proto.
+const SchemaVersion uint32 = 1
+
+// TypeURL is the type URL used when wrapping the migration snapshot
+// payload in an [google.golang.org/protobuf/types/known/anypb.Any]. It is
+// opaque to clients and only meaningful between two shims that agree on
+// [SchemaVersion].
+const TypeURL = "type.microsoft.com/hcsshim.migration.snapshot.v1.SandboxSnapshot"

internal/controller/migration/snapshot/doc.go

@@ -0,0 +1,27 @@
+// Package snapshot defines the wire format used to hand off a running LCOW
+// sandbox from one shim to another during live migration.
+//
+// A snapshot is a self-contained, point-in-time description of everything the
+// destination shim needs in order to resume ownership of an existing utility
+// VM and the workloads running inside it: the VM itself, the device
+// sub-controllers attached to it (storage, PCI passthrough, file shares),
+// the per-pod network configuration, and the containers and processes
+// currently executing in the guest.
+//
+// The format is intentionally controller-oriented rather than API-oriented:
+// each controller on the source serializes its own bookkeeping into the
+// snapshot, and the corresponding controller on the destination rebuilds its
+// in-memory state from that section. This keeps the migration boundary
+// aligned with the existing ownership boundaries in the shim, so adding new
+// migratable state is a localized change to the controller that owns it.
+//
+// Callers on the source side produce a snapshot once the sandbox has been
+// quiesced and transmit it to the destination over the migration channel.
+// Callers on the destination side validate the snapshot, reconstruct the
+// controller tree, and then resume the workload. Snapshots are versioned so
+// that incompatible producers and consumers fail fast instead of silently
+// corrupting sandbox state.
+//
+// The Go bindings in this package are generated from the accompanying .proto
+// file; see Protobuild.toml for the generation pipeline.
+package snapshot