fork: share template mem-file via symlink for firecracker fan-out

When a Firecracker fork descends from a Standby or Template source, skip
copying the snapshot mem-file and symlink it to the source's instead.
Firecracker mmaps the mem-file MAP_PRIVATE on restore, so all forks COW
from the same backing file — no per-fork copy required.

Gated to Firecracker only because other hypervisors (cloud-hypervisor,
qemu, vz) don't share MAP_PRIVATE semantics on their snapshot layouts.
Skipped for the running-fork path: the source restores afterward, which
would mutate the shared file out from under the fork.

Stacked on hypeship/template-as-state so the Template state both gates
"this snapshot is safe to fan out from" and refcounts living forks.

Author: sjmiller609

lib/forkvm/copy.go

@@ -33,12 +33,30 @@ type copyState struct {
 	reflinkDead bool
 }
 
+// CopyOptions tunes CopyGuestDirectory behavior. The zero value reproduces
+// the original full-copy semantics; callers can opt into skipping specific
+// paths when the consumer arranges its own substitute (e.g. a symlink to a
+// template-shared mem-file).
+type CopyOptions struct {
+	// SkipRelPaths lists relative paths under srcDir that should not be
+	// materialized in dstDir. Comparison is exact and uses forward-slash
+	// separators on all platforms.
+	SkipRelPaths []string
+}
+
 // CopyGuestDirectory recursively copies a guest directory to a new destination.
 // Regular files are cloned via reflink (FICLONE) when the underlying filesystem
 // supports it; otherwise we fall back to a sparse extent copy
 // (SEEK_DATA/SEEK_HOLE). Runtime sockets and logs are skipped because they are
 // host-runtime artifacts.
 func CopyGuestDirectory(srcDir, dstDir string) error {
+	return CopyGuestDirectoryWithOptions(srcDir, dstDir, CopyOptions{})
+}
+
+// CopyGuestDirectoryWithOptions is the option-taking variant of
+// CopyGuestDirectory. Use this when forking with template-shared assets, so
+// the caller can install a symlink in place of a heavy copied file.
+func CopyGuestDirectoryWithOptions(srcDir, dstDir string, opts CopyOptions) error {
 	srcInfo, err := os.Stat(srcDir)
 	if err != nil {
 		return fmt.Errorf("stat source directory: %w", err)
@@ -56,6 +74,11 @@ func CopyGuestDirectory(srcDir, dstDir string) error {
 		state.reflinkDead = true
 	}
 
+	skipSet := make(map[string]struct{}, len(opts.SkipRelPaths))
+	for _, p := range opts.SkipRelPaths {
+		skipSet[filepath.ToSlash(p)] = struct{}{}
+	}
+
 	return filepath.WalkDir(srcDir, func(path string, d fs.DirEntry, walkErr error) error {
 		if walkErr != nil {
 			return walkErr
@@ -68,6 +91,12 @@ func CopyGuestDirectory(srcDir, dstDir string) error {
 		if relPath == "." {
 			return nil
 		}
+		if _, skip := skipSet[filepath.ToSlash(relPath)]; skip {
+			if d.IsDir() {
+				return filepath.SkipDir
+			}
+			return nil
+		}
 		if d.IsDir() && shouldSkipDirectory(relPath) {
 			return filepath.SkipDir
 		}

lib/forkvm/copy_test.go

@@ -44,6 +44,25 @@ func TestCopyGuestDirectory(t *testing.T) {
 	assert.Equal(t, "metadata.json", linkTarget)
 }
 
+func TestCopyGuestDirectory_SkipRelPaths(t *testing.T) {
+	src := filepath.Join(t.TempDir(), "src")
+	dst := filepath.Join(t.TempDir(), "dst")
+
+	require.NoError(t, os.MkdirAll(filepath.Join(src, "snapshots", "snapshot-latest"), 0755))
+	require.NoError(t, os.WriteFile(filepath.Join(src, "snapshots", "snapshot-latest", "config.json"), []byte(`{}`), 0644))
+	require.NoError(t, os.WriteFile(filepath.Join(src, "snapshots", "snapshot-latest", "memory"), []byte("the heavy mem-file"), 0644))
+	require.NoError(t, os.WriteFile(filepath.Join(src, "snapshots", "snapshot-latest", "state"), []byte("device state"), 0644))
+
+	err := CopyGuestDirectoryWithOptions(src, dst, CopyOptions{
+		SkipRelPaths: []string{"snapshots/snapshot-latest/memory"},
+	})
+	require.NoError(t, err)
+
+	assert.NoFileExists(t, filepath.Join(dst, "snapshots", "snapshot-latest", "memory"))
+	assert.FileExists(t, filepath.Join(dst, "snapshots", "snapshot-latest", "config.json"))
+	assert.FileExists(t, filepath.Join(dst, "snapshots", "snapshot-latest", "state"))
+}
+
 func TestCopyGuestDirectory_DoesNotSkipTmpSuffixedDirectories(t *testing.T) {
 	src := filepath.Join(t.TempDir(), "src")
 	dst := filepath.Join(t.TempDir(), "dst")

lib/instances/fork.go

@@ -255,19 +255,39 @@ func (m *manager) forkInstanceFromStoppedOrStandby(ctx context.Context, id strin
 
 	fromSnapshot := source.State == StateStandby || source.State == StateTemplate
 
+	// shareMemFile gates mem-file fan-out from the source's standby snapshot.
+	// Firecracker only: it mmaps the snapshot mem-file MAP_PRIVATE on restore,
+	// so all forks safely COW from the same backing file. Cloud-hypervisor and
+	// other hypervisors take a copy-mode path and don't benefit. Restricted to
+	// Template sources because they are explicitly promoted as fork-only and
+	// can never be restored — sharing the mem-file with a non-Template source
+	// would let a later RestoreInstance mutate the file out from under live
+	// forks.
+	shareMemFile := source.State == StateTemplate && stored.HypervisorType == hypervisor.TypeFirecracker
+
 	if fromSnapshot {
 		if err := m.ensureSnapshotMemoryReady(ctx, m.paths.InstanceSnapshotLatest(id), m.snapshotJobKeyForInstance(id), stored.HypervisorType); err != nil {
 			return nil, fmt.Errorf("prepare standby snapshot for fork: %w", err)
 		}
 	}
 
-	if err := forkvm.CopyGuestDirectory(srcDir, dstDir); err != nil {
+	copyOpts := forkvm.CopyOptions{}
+	if shareMemFile {
+		copyOpts.SkipRelPaths = []string{templateSharedMemFileRelPath}
+	}
+	if err := forkvm.CopyGuestDirectoryWithOptions(srcDir, dstDir, copyOpts); err != nil {
 		if errors.Is(err, forkvm.ErrSparseCopyUnsupported) {
 			return nil, fmt.Errorf("fork requires sparse-capable filesystem (SEEK_DATA/SEEK_HOLE unsupported): %w", err)
 		}
 		return nil, fmt.Errorf("clone guest directory: %w", err)
 	}
 
+	if shareMemFile {
+		if err := m.installForkSharedMemFile(dstDir, id); err != nil {
+			return nil, fmt.Errorf("install shared mem-file: %w", err)
+		}
+	}
+
 	starter, err := m.getVMStarter(stored.HypervisorType)
 	if err != nil {
 		return nil, fmt.Errorf("get vm starter: %w", err)

lib/instances/templates.go

@@ -0,0 +1,38 @@
+package instances
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+)
+
+const (
+	templateSharedMemFileName    = "memory"
+	templateSharedMemFileRelPath = "snapshots/snapshot-latest/memory"
+)
+
+// installForkSharedMemFile arranges the fork's snapshot directory so the
+// guest mem-file is a symlink into the source template instance's snapshot
+// directory instead of a per-fork copy. firecracker mmaps the mem-file
+// MAP_PRIVATE during restore, so all forks COW from the same backing file.
+//
+// Layout: forkDataDir is the fork's data dir. The snapshot dir is at
+// <forkDataDir>/snapshots/snapshot-latest, and the mem-file lives at
+// <snapshot dir>/memory. The symlink target is the source instance's
+// standby snapshot mem-file.
+func (m *manager) installForkSharedMemFile(forkDataDir, sourceInstanceID string) error {
+	srcMem := filepath.Join(m.paths.InstanceSnapshotLatest(sourceInstanceID), templateSharedMemFileName)
+	if _, err := os.Stat(srcMem); err != nil {
+		return fmt.Errorf("stat template mem-file: %w", err)
+	}
+	dstSnapshotDir := filepath.Join(forkDataDir, "snapshots", "snapshot-latest")
+	if err := os.MkdirAll(dstSnapshotDir, 0o755); err != nil {
+		return fmt.Errorf("ensure fork snapshot dir: %w", err)
+	}
+	dstMem := filepath.Join(dstSnapshotDir, templateSharedMemFileName)
+	_ = os.Remove(dstMem)
+	if err := os.Symlink(srcMem, dstMem); err != nil {
+		return fmt.Errorf("symlink shared mem-file: %w", err)
+	}
+	return nil
+}

lib/instances/templates_shared_memfile_test.go

@@ -0,0 +1,136 @@
+package instances
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/kernel/hypeman/lib/hypervisor"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// TestInstallForkSharedMemFile_SymlinksSourceMemFile verifies that the helper
+// creates a symlink at the fork's snapshot mem-file path pointing back to the
+// source instance's mem-file.
+func TestInstallForkSharedMemFile_SymlinksSourceMemFile(t *testing.T) {
+	t.Parallel()
+
+	mgr, _ := newStorageOnlyManager(t)
+	sourceID := "shared-memfile-source"
+
+	srcSnapshotDir := mgr.paths.InstanceSnapshotLatest(sourceID)
+	require.NoError(t, os.MkdirAll(srcSnapshotDir, 0o755))
+	srcMem := filepath.Join(srcSnapshotDir, templateSharedMemFileName)
+	require.NoError(t, os.WriteFile(srcMem, []byte("guest memory bytes"), 0o644))
+
+	forkDir := filepath.Join(t.TempDir(), "fork-data")
+
+	require.NoError(t, mgr.installForkSharedMemFile(forkDir, sourceID))
+
+	forkMem := filepath.Join(forkDir, "snapshots", "snapshot-latest", templateSharedMemFileName)
+	info, err := os.Lstat(forkMem)
+	require.NoError(t, err)
+	assert.NotZero(t, info.Mode()&os.ModeSymlink, "fork mem-file must be a symlink, not a regular file")
+
+	target, err := os.Readlink(forkMem)
+	require.NoError(t, err)
+	assert.Equal(t, srcMem, target)
+}
+
+// TestInstallForkSharedMemFile_ErrorsWhenSourceMissing makes sure the helper
+// refuses to silently create a dangling symlink when the source mem-file does
+// not exist.
+func TestInstallForkSharedMemFile_ErrorsWhenSourceMissing(t *testing.T) {
+	t.Parallel()
+
+	mgr, _ := newStorageOnlyManager(t)
+	forkDir := filepath.Join(t.TempDir(), "fork-data")
+
+	err := mgr.installForkSharedMemFile(forkDir, "no-such-source")
+	require.Error(t, err)
+}
+
+// TestForkFirecrackerSharesMemFile_FromTemplate verifies the end-to-end fork
+// path: when the source is a Firecracker Template instance, the fork's
+// mem-file is a symlink to the source's mem-file instead of a copy. This
+// preserves the firecracker MAP_PRIVATE COW semantics that let multiple forks
+// share the heavy backing file.
+func TestForkFirecrackerSharesMemFile_FromTemplate(t *testing.T) {
+	t.Parallel()
+
+	mgr, _ := setupTestManager(t)
+	ctx := context.Background()
+
+	sourceID := "shared-memfile-fc-src"
+	createStandbySnapshotSourceFixture(t, mgr, sourceID, "shared-memfile-fc-src", hypervisor.TypeFirecracker)
+	promoteFixtureToTemplate(t, mgr, sourceID)
+
+	srcSnapshotDir := mgr.paths.InstanceSnapshotLatest(sourceID)
+	srcMem := filepath.Join(srcSnapshotDir, templateSharedMemFileName)
+	require.NoError(t, os.WriteFile(srcMem, []byte("firecracker mem-file contents"), 0o644))
+	snapshotConfigPath := mgr.paths.InstanceSnapshotConfig(sourceID)
+	require.NoError(t, os.MkdirAll(filepath.Dir(snapshotConfigPath), 0o755))
+	require.NoError(t, os.WriteFile(snapshotConfigPath, []byte(`{}`), 0o644))
+
+	forked, err := mgr.forkInstanceFromStoppedOrStandby(ctx, sourceID, ForkInstanceRequest{
+		Name:        "shared-memfile-fc-fork",
+		TargetState: StateStopped,
+	}, true)
+	require.NoError(t, err)
+	require.NotNil(t, forked)
+
+	forkMem := filepath.Join(mgr.paths.InstanceSnapshotLatest(forked.Id), templateSharedMemFileName)
+	info, err := os.Lstat(forkMem)
+	require.NoError(t, err)
+	assert.NotZero(t, info.Mode()&os.ModeSymlink, "fork mem-file must be a symlink for firecracker fan-out")
+
+	target, err := os.Readlink(forkMem)
+	require.NoError(t, err)
+	assert.Equal(t, srcMem, target)
+}
+
+// TestForkFirecrackerStandbySourceDoesNotShareMemFile guards the
+// non-Template carve-out: forking a plain Standby source must copy the
+// mem-file outright. Sharing would let a later RestoreInstance on the source
+// mutate the file out from under live forks.
+func TestForkFirecrackerStandbySourceDoesNotShareMemFile(t *testing.T) {
+	t.Parallel()
+
+	mgr, _ := setupTestManager(t)
+	ctx := context.Background()
+
+	sourceID := "standby-fork-fc-src"
+	createStandbySnapshotSourceFixture(t, mgr, sourceID, "standby-fork-fc-src", hypervisor.TypeFirecracker)
+
+	srcSnapshotDir := mgr.paths.InstanceSnapshotLatest(sourceID)
+	srcMem := filepath.Join(srcSnapshotDir, templateSharedMemFileName)
+	require.NoError(t, os.WriteFile(srcMem, []byte("firecracker mem-file contents"), 0o644))
+	snapshotConfigPath := mgr.paths.InstanceSnapshotConfig(sourceID)
+	require.NoError(t, os.MkdirAll(filepath.Dir(snapshotConfigPath), 0o755))
+	require.NoError(t, os.WriteFile(snapshotConfigPath, []byte(`{}`), 0o644))
+
+	forked, err := mgr.forkInstanceFromStoppedOrStandby(ctx, sourceID, ForkInstanceRequest{
+		Name:        "standby-fork-fc-fork",
+		TargetState: StateStopped,
+	}, true)
+	require.NoError(t, err)
+	require.NotNil(t, forked)
+
+	forkMem := filepath.Join(mgr.paths.InstanceSnapshotLatest(forked.Id), templateSharedMemFileName)
+	info, err := os.Lstat(forkMem)
+	require.NoError(t, err)
+	assert.Zero(t, info.Mode()&os.ModeSymlink, "standby-source fork mem-file must be a regular file copy, not a symlink")
+}
+
+// promoteFixtureToTemplate marks the source's stored metadata as a Template
+// without invoking the full PromoteToTemplate lifecycle (which would require
+// a live VM). Test-only shortcut.
+func promoteFixtureToTemplate(t *testing.T, mgr *manager, id string) {
+	t.Helper()
+	meta, err := mgr.loadMetadata(id)
+	require.NoError(t, err)
+	meta.IsTemplate = true
+	require.NoError(t, mgr.saveMetadata(meta))
+}