[shimV2] add plan9 device controller

internal/controller/device/plan9/doc.go

@@ -0,0 +1,21 @@
+//go:build windows && !wcow
+
+// Package plan9 provides a controller for managing Plan9 file-share devices
+// attached to a Utility VM (UVM).
+//
+// It handles attaching and detaching Plan9 shares to the VM via HCS modify
+// calls. Guest-side mount operations (mapped-directory requests) are handled
+// separately by the mount controller.
+//
+// The [Controller] interface is the primary entry point, with [Manager] as its
+// concrete implementation. A single [Manager] manages all Plan9 shares for a UVM.
+//
+// # Lifecycle
+//
+// [Manager] tracks active shares by name in an internal map.
+//
+//   - [Controller.AddToVM] adds a share and records its name in the map.
+//     If the HCS call fails, the share is not recorded.
+//   - [Controller.RemoveFromVM] removes a share and deletes its name from the map.
+//     If the share is not in the map, the call is a no-op.
+package plan9

internal/controller/device/plan9/interface.go

@@ -0,0 +1,44 @@
+//go:build windows && !wcow
+
+package plan9
+
+import (
+	"context"
+
+	hcsschema "github.com/Microsoft/hcsshim/internal/hcs/schema2"
+)
+
+// Controller manages the lifecycle of Plan9 shares attached to a UVM.
+type Controller interface {
+	// AddToVM adds a Plan9 share to the host VM and returns the generated share name.
+	// Guest-side mount is handled separately by the mount controller.
+	AddToVM(ctx context.Context, opts *AddOptions) (string, error)
+
+	// RemoveFromVM removes a Plan9 share identified by shareName from the host VM.
+	RemoveFromVM(ctx context.Context, shareName string) error
+}
+
+// AddOptions holds the configuration required to add a Plan9 share to the VM.
+type AddOptions struct {
+	// HostPath is the path on the host to share into the VM.
+	HostPath string
+
+	// ReadOnly indicates whether the share should be mounted read-only.
+	ReadOnly bool
+
+	// Restrict enables single-file mapping mode for the share.
+	Restrict bool
+
+	// AllowedNames is the list of file names allowed when Restrict is true.
+	AllowedNames []string
+}
+
+// vmPlan9Manager manages adding and removing Plan9 shares on the host VM.
+// Implemented by [vmmanager.UtilityVM].
+type vmPlan9Manager interface {
+	// AddPlan9 adds a plan 9 share to a running Utility VM.
+	AddPlan9(ctx context.Context, settings hcsschema.Plan9Share) error
+
+	// RemovePlan9 removes a plan 9 share from a running Utility VM.
+	RemovePlan9(ctx context.Context, settings hcsschema.Plan9Share) error
+}

internal/controller/device/plan9/plan9.go

@@ -0,0 +1,142 @@
+//go:build windows && !wcow
+
+package plan9
+
+import (
+	"context"
+	"fmt"
+	"strconv"
+	"sync"
+
+	"github.com/Microsoft/hcsshim/internal/hcs"
+	hcsschema "github.com/Microsoft/hcsshim/internal/hcs/schema2"
+	"github.com/Microsoft/hcsshim/internal/log"
+	"github.com/Microsoft/hcsshim/internal/logfields"
+	"github.com/Microsoft/hcsshim/internal/vm/vmutils"
+
+	"github.com/sirupsen/logrus"
+)
+
+// share-flag constants used in Plan9 HCS requests.
+//
+// These are marked private in the HCS schema. When public variants become
+// available, we should replace these.
+const (
+	shareFlagsReadOnly           int32 = 0x00000001
+	shareFlagsLinuxMetadata      int32 = 0x00000004
+	shareFlagsRestrictFileAccess int32 = 0x00000080
+)
+
+// Manager is the concrete implementation of [Controller].
+type Manager struct {
+	mu sync.Mutex
+
+	// shares is the set of currently configured Plan9 share names.
+	// Guarded by mu.
+	shares map[string]struct{}
+
+	// noWritableFileShares disallows adding writable Plan9 shares.
+	noWritableFileShares bool
+
+	// vmPlan9Mgr performs host-side Plan9 add/remove on the VM.
+	vmPlan9Mgr vmPlan9Manager
+
+	// nameCounter is the monotonically increasing index used to
+	// generate unique share names. Guarded by mu.
+	nameCounter uint64
+}
+
+var _ Controller = (*Manager)(nil)
+
+// New creates a ready-to-use [Manager].
+func New(
+	vmPlan9Mgr vmPlan9Manager,
+	noWritableFileShares bool,
+) *Manager {
+	return &Manager{
+		vmPlan9Mgr:           vmPlan9Mgr,
+		noWritableFileShares: noWritableFileShares,
+		shares:               make(map[string]struct{}),
+	}
+}
+
+// AddToVM adds a Plan9 share to the host VM and returns the generated share name.
+func (m *Manager) AddToVM(ctx context.Context, opts *AddOptions) (_ string, err error) {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+
+	// Ensure that adding the share is allowed.
+	if !opts.ReadOnly && m.noWritableFileShares {
+		return "", fmt.Errorf("adding writable shares is denied: %w", hcs.ErrOperationDenied)
+	}
+
+	// Build the Plan9 share flags bitmask from the caller-provided options.
+	flags := shareFlagsLinuxMetadata
+	if opts.ReadOnly {
+		flags |= shareFlagsReadOnly
+	}
+	if opts.Restrict {
+		flags |= shareFlagsRestrictFileAccess
+	}
+
+	// Generate a unique share name from the nameCounter.
+	name := strconv.FormatUint(m.nameCounter, 10)
+	m.nameCounter++
+
+	ctx, _ = log.WithContext(ctx, logrus.WithField("shareName", name))
+
+	log.G(ctx).WithFields(logrus.Fields{
+		logfields.HostPath:   opts.HostPath,
+		logfields.ReadOnly:   opts.ReadOnly,
+		"RestrictFileAccess": opts.Restrict,
+		"AllowedFiles":       opts.AllowedNames,
+	}).Tracef("adding plan9 share to host VM")
+
+	// Call into HCS to add the Plan9 share to the VM.
+	if err := m.vmPlan9Mgr.AddPlan9(ctx, hcsschema.Plan9Share{
+		Name:         name,
+		AccessName:   name,
+		Path:         opts.HostPath,
+		Port:         vmutils.Plan9Port,
+		Flags:        flags,
+		AllowedFiles: opts.AllowedNames,
+	}); err != nil {
+		return "", fmt.Errorf("add plan9 share %s to host: %w", name, err)
+	}
+
+	m.shares[name] = struct{}{}
+
+	log.G(ctx).Info("plan9 share added to host VM")
+
+	return name, nil
+}
+
+// RemoveFromVM removes the Plan9 share identified by shareName from the host VM.
+func (m *Manager) RemoveFromVM(ctx context.Context, shareName string) error {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+
+	ctx, _ = log.WithContext(ctx, logrus.WithField("shareName", shareName))
+
+	if _, ok := m.shares[shareName]; !ok {
+		log.G(ctx).Debug("plan9 share not found, skipping removal")
+		return nil
+	}
+
+	log.G(ctx).Debug("starting plan9 share removal")
+
+	// Call into HCS to remove the share from the VM.
+	if err := m.vmPlan9Mgr.RemovePlan9(ctx, hcsschema.Plan9Share{
+		Name:       shareName,
+		AccessName: shareName,
+		Port:       vmutils.Plan9Port,
+	}); err != nil {
+		return fmt.Errorf("remove plan9 share %s from host: %w", shareName, err)
+	}
+
+	delete(m.shares, shareName)
+
+	log.G(ctx).Info("plan9 share removed from host VM")
+
+	return nil
+}

internal/vm/vmmanager/plan9.go

@@ -11,17 +11,6 @@ import (
 	"github.com/Microsoft/hcsshim/internal/protocol/guestrequest"
 )
 
-// Plan9Manager manages adding plan 9 shares to a Utility VM.
-type Plan9Manager interface {
-	// AddPlan9 adds a plan 9 share to a running Utility VM.
-	AddPlan9(ctx context.Context, settings hcsschema.Plan9Share) error
-
-	// RemovePlan9 removes a plan 9 share from a running Utility VM.
-	RemovePlan9(ctx context.Context, settings hcsschema.Plan9Share) error
-}
-
-var _ Plan9Manager = (*UtilityVM)(nil)
-
 func (uvm *UtilityVM) AddPlan9(ctx context.Context, settings hcsschema.Plan9Share) error {
 	modification := &hcsschema.ModifySettingRequest{
 		RequestType:  guestrequest.RequestTypeAdd,