Add HCS v2 bindings for creating compute systems.

go.mod

@@ -37,6 +37,7 @@ require (
 	go.uber.org/mock v0.4.0
 	golang.org/x/sync v0.8.0
 	golang.org/x/sys v0.25.0
+	golang.org/x/tools v0.24.0
 	google.golang.org/grpc v1.66.0
 	google.golang.org/grpc/cmd/protoc-gen-go-grpc v1.5.1
 	google.golang.org/protobuf v1.34.2
@@ -111,10 +112,9 @@ require (
 	go.opentelemetry.io/otel/sdk v1.28.0 // indirect
 	go.opentelemetry.io/otel/trace v1.28.0 // indirect
 	golang.org/x/crypto v0.26.0 // indirect
-	golang.org/x/mod v0.17.0 // indirect
+	golang.org/x/mod v0.20.0 // indirect
 	golang.org/x/net v0.28.0 // indirect
 	golang.org/x/text v0.17.0 // indirect
-	golang.org/x/tools v0.21.1-0.20240508182429-e35e4ccd0d2d // indirect
 	google.golang.org/genproto v0.0.0-20240227224415-6ceb2ff114de // indirect
 	google.golang.org/genproto/googleapis/rpc v0.0.0-20240701130421-f6361c86f094 // indirect
 	gopkg.in/yaml.v2 v2.4.0 // indirect

go.sum

@@ -328,8 +328,8 @@ golang.org/x/mod v0.3.0/go.mod h1:s0Qsj1ACt9ePp/hMypM3fl4fZqREWJwdYDEqhRiZZUA=
 golang.org/x/mod v0.5.1/go.mod h1:5OXOZSfqPIIbmVBIIKWRFfZjPR0E5r58TLhUjH0a2Ro=
 golang.org/x/mod v0.6.0-dev.0.20220419223038-86c51ed26bb4/go.mod h1:jJ57K6gSWd91VN4djpZkiMVwK6gcyfeH4XE8wZrZaV4=
 golang.org/x/mod v0.8.0/go.mod h1:iBbtSCu2XBx23ZKBPSOrRkjjQPZFPuis4dIYUhu/chs=
-golang.org/x/mod v0.17.0 h1:zY54UmvipHiNd+pm+m0x9KhZ9hl1/7QNMyxXbc6ICqA=
-golang.org/x/mod v0.17.0/go.mod h1:hTbmBsO62+eylJbnUtE2MGJUyE7QWk4xUqPFrRgJ+7c=
+golang.org/x/mod v0.20.0 h1:utOm6MM3R3dnawAiJgn0y+xvuYRsm1RKM/4giyfDgV0=
+golang.org/x/mod v0.20.0/go.mod h1:hTbmBsO62+eylJbnUtE2MGJUyE7QWk4xUqPFrRgJ+7c=
 golang.org/x/net v0.0.0-20180724234803-3673e40ba225/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4=
 golang.org/x/net v0.0.0-20180826012351-8a410e7b638d/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4=
 golang.org/x/net v0.0.0-20190213061140-3a22650c66bd/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4=
@@ -410,8 +410,8 @@ golang.org/x/tools v0.0.0-20210106214847-113979e3529a/go.mod h1:emZCQorbCU4vsT4f
 golang.org/x/tools v0.1.9/go.mod h1:nABZi5QlRsZVlzPpHl034qft6wpY4eDcsTt5AaioBiU=
 golang.org/x/tools v0.1.12/go.mod h1:hNGJHUnrk76NpqgfD5Aqm5Crs+Hm0VOH/i9J2+nxYbc=
 golang.org/x/tools v0.6.0/go.mod h1:Xwgl3UAJ/d3gWutnCtw505GrjyAbvKui8lOU390QaIU=
-golang.org/x/tools v0.21.1-0.20240508182429-e35e4ccd0d2d h1:vU5i/LfpvrRCpgM/VPfJLg5KjxD3E+hfT1SH+d9zLwg=
-golang.org/x/tools v0.21.1-0.20240508182429-e35e4ccd0d2d/go.mod h1:aiJjzUbINMkxbQROHiO6hDPo2LHcIPhhQsa9DLh0yGk=
+golang.org/x/tools v0.24.0 h1:J1shsA93PJUEVaUSaay7UXAyE8aimq3GW0pjlolpa24=
+golang.org/x/tools v0.24.0/go.mod h1:YhNqVBIfWHdzvTLs0d8LCuMhkKUgSUKldakyV7W/WDQ=
 golang.org/x/xerrors v0.0.0-20190717185122-a985d3407aa7/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
 golang.org/x/xerrors v0.0.0-20191011141410-1b5146add898/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
 golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=

internal/computecore/callback.go

@@ -0,0 +1,65 @@
+//go:build windows
+
+package computecore
+
+import "golang.org/x/sys/windows"
+
+// Callback functions must be converted to a uintptr via [windows.NewCallback] before being
+// passed to a syscall.
+//
+// Additionally, [windows.NewCallback] expects functions to return a uintptr result,
+// so callbacks must be modified ahead of time.
+//
+// Create a dedicated type uintptr for each callback to ensure type safety.
+
+// The `void* context` parameter is for an arbitrary payload to passed into the callback,
+// allowing for operation-specific data to be provided to a more generic callback.
+
+type (
+	// Function type for the completion callback of an operation.
+	//
+	//	typedef void (CALLBACK *HCS_OPERATION_COMPLETION)(
+	//	    _In_ HCS_OPERATION operation,
+	//	    _In_opt_ void* context
+	//	    );
+	HCSOperationCompletion func(op HCSOperation, hcsContext uintptr)
+
+	hcsOperationCompletionUintptr uintptr
+)
+
+func (f HCSOperationCompletion) asCallback() hcsOperationCompletionUintptr {
+	if f == nil {
+		return hcsOperationCompletionUintptr(0)
+	}
+	return hcsOperationCompletionUintptr(windows.NewCallback(
+		func(op HCSOperation, hcsContext uintptr) uintptr {
+			f(op, hcsContext)
+			return 0
+		},
+	))
+}
+
+type (
+	// Function type for compute system event callbacks.
+	//
+	//	typedef void (CALLBACK *HCS_EVENT_CALLBACK)(
+	//	    _In_ HCS_EVENT* event,
+	//	    _In_opt_ void* context
+	//	    );
+	HCSEventCallback func(event *HCSEvent, hcsContext uintptr)
+
+	hcsEventCallbackUintptr uintptr
+)
+
+func (f HCSEventCallback) asCallback() hcsEventCallbackUintptr {
+	if f == nil {
+		return hcsEventCallbackUintptr(0)
+	}
+	return hcsEventCallbackUintptr(windows.NewCallback(
+		// NewCallback expects a function with one uintptr-sized result
+		func(event *HCSEvent, hcsContext uintptr) uintptr {
+			f(event, hcsContext)
+			return 0
+		},
+	))
+}

internal/computecore/computecore.go

@@ -0,0 +1,127 @@
+//go:build windows
+
+package computecore
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"strings"
+	"syscall"
+	"time"
+
+	"github.com/Microsoft/hcsshim/internal/interop"
+	"github.com/Microsoft/hcsshim/internal/log"
+	"github.com/Microsoft/hcsshim/internal/logfields"
+	"github.com/Microsoft/hcsshim/internal/oc"
+	"github.com/Microsoft/hcsshim/internal/timeout"
+
+	"github.com/sirupsen/logrus"
+	"go.opencensus.io/trace"
+	"golang.org/x/sys/windows"
+)
+
+//go:generate go run github.com/Microsoft/go-winio/tools/mkwinsyscall -output zsyscall_windows.go ./*.go
+
+//sys hcsCreateComputeSystem(id string, configuration string, operation HCSOperation, security_descriptor *uint32, computeSystem *HCSSystem) (hr error) = computecore.HcsCreateComputeSystem?
+
+type (
+	HCSSystem syscall.Handle
+)
+
+func HcsCreateComputeSystem(ctx context.Context, id string, configuration string, operation HCSOperation, securityDescriptor *uint32) (computeSystem HCSSystem, result string, hr error) {
+	ctx, span := oc.StartSpan(ctx, "computecore::HcsCreateComputeSystem")
+	defer span.End()
+	defer func() {
+		if result != "" {
+			span.AddAttributes(trace.StringAttribute("resultDocument", result))
+		}
+		if !errors.Is(hr, windows.ERROR_VMCOMPUTE_OPERATION_PENDING) {
+			oc.SetSpanStatus(span, hr)
+		}
+	}()
+	span.AddAttributes(
+		trace.StringAttribute("id", id),
+		trace.StringAttribute("configuration", configuration),
+	)
+
+	return computeSystem, result, execute(ctx, timeout.SystemCreate, func() error {
+		var resultp *uint16
+		err := hcsCreateComputeSystem(id, configuration, operation, securityDescriptor, &computeSystem)
+		if resultp != nil {
+			result = interop.ConvertAndFreeCoTaskMemString(resultp)
+		}
+
+		// FIXME: here we synchronously wait for operation result, but in the future we should probably switch
+		//   to notification model.
+		if opResult, opErr := operation.WaitForResult(ctx); opErr != nil {
+			log.G(ctx).WithError(opErr).Error("Failed to wait for operation result")
+			return opErr
+		} else {
+			log.G(ctx).WithField("result", opResult).Debug("operation completed")
+		}
+		return err
+	})
+}
+
+func bufferToString(buffer *uint16) string {
+	if buffer == nil {
+		return ""
+	}
+	return interop.ConvertAndFreeCoTaskMemString(buffer)
+}
+
+func encode(v any) (string, error) {
+	// TODO: pool of encoders/buffers
+	buf := &bytes.Buffer{}
+	enc := json.NewEncoder(buf)
+	enc.SetEscapeHTML(false)
+	enc.SetIndent("", "")
+
+	if err := enc.Encode(v); err != nil {
+		return "", fmt.Errorf("json encoding: %w", err)
+	}
+
+	// encoder.Encode appends a newline to the end
+	return strings.TrimSpace(buf.String()), nil
+}
+
+func execute(ctx context.Context, timeout time.Duration, f func() error) error {
+	now := time.Now()
+	if timeout > 0 {
+		var cancel context.CancelFunc
+		ctx, cancel = context.WithTimeout(ctx, timeout)
+		defer cancel()
+	}
+
+	deadline, ok := ctx.Deadline()
+	trueTimeout := timeout
+	if ok {
+		trueTimeout = deadline.Sub(now)
+		log.G(ctx).WithFields(logrus.Fields{
+			logfields.Timeout: trueTimeout,
+			"desiredTimeout":  timeout,
+		}).Trace("Executing syscall with deadline")
+	}
+
+	done := make(chan error, 1)
+	go func() {
+		done <- f()
+	}()
+
+	select {
+	case <-ctx.Done():
+		if errors.Is(ctx.Err(), context.DeadlineExceeded) {
+			log.G(ctx).WithField(logfields.Timeout, trueTimeout).
+				Warning("Syscall did not complete within operation timeout. This may indicate a platform issue. " +
+					"If it appears to be making no forward progress, obtain the stacks and see if there is a syscall " +
+					"stuck in the platform API for a significant length of time.")
+		}
+		return ctx.Err()
+	case err := <-done:
+		return err
+	}
+
+}

internal/computecore/doc.go

@@ -0,0 +1 @@
+package computecore

internal/computecore/errors.go

@@ -0,0 +1,111 @@
+//go:build windows
+
+package computecore
+
+import "golang.org/x/sys/windows"
+
+// HCS specific error codes.
+//
+// See [documentation] for more info.
+//
+// [documentation]: https://learn.microsoft.com/en-us/virtualization/api/hcs/reference/hcshresult
+const (
+	// The virtual machine or container exited unexpectedly while starting.
+	HCS_E_TERMINATED_DURING_START windows.Errno = 0x80370100
+
+	// The container operating system does not match the host operating system.
+	HCS_E_IMAGE_MISMATCH windows.Errno = 0x80370101
+
+	// The virtual machine could not be started because a required feature is not installed.
+	HCS_E_HYPERV_NOT_INSTALLED windows.Errno = 0x80370102
+
+	// The requested virtual machine or container operation is not valid in the current state.
+	HCS_E_INVALID_STATE windows.Errno = 0x80370105
+
+	// The virtual machine or container exited unexpectedly.
+	HCS_E_UNEXPECTED_EXIT windows.Errno = 0x80370106
+
+	// The virtual machine or container was forcefully exited.
+	HCS_E_TERMINATED windows.Errno = 0x80370107
+
+	// A connection could not be established with the container or virtual machine.
+	HCS_E_CONNECT_FAILED windows.Errno = 0x80370108
+
+	// The operation timed out because a response was not received from the virtual machine or container.
+	HCS_E_CONNECTION_TIMEOUT windows.Errno = 0x80370109
+
+	// The connection with the virtual machine or container was closed.
+	HCS_E_CONNECTION_CLOSED windows.Errno = 0x8037010A
+
+	// An unknown internal message was received by the virtual machine or container.
+	HCS_E_UNKNOWN_MESSAGE windows.Errno = 0x8037010B
+
+	// The virtual machine or container does not support an available version of the communication protocol with the host.
+	HCS_E_UNSUPPORTED_PROTOCOL_VERSION windows.Errno = 0x8037010C
+
+	// The virtual machine or container JSON document is invalid.
+	HCS_E_INVALID_JSON windows.Errno = 0x8037010D
+
+	// A virtual machine or container with the specified identifier does not exist.
+	HCS_E_SYSTEM_NOT_FOUND windows.Errno = 0x8037010E
+
+	// A virtual machine or container with the specified identifier already exists.
+	HCS_E_SYSTEM_ALREADY_EXISTS windows.Errno = 0x8037010F
+
+	// The virtual machine or container with the specified identifier is not running.
+	HCS_E_SYSTEM_ALREADY_STOPPED windows.Errno = 0x80370110
+
+	// A communication protocol error has occurred between the virtual machine or container and the host.
+	HCS_E_PROTOCOL_ERROR windows.Errno = 0x80370111
+
+	// The container image contains a layer with an unrecognized format.
+	HCS_E_INVALID_LAYER windows.Errno = 0x80370112
+
+	// To use this container image, you must join the Windows Insider Program.
+	// Please see https://go.microsoft.com/fwlink/?linkid=850659 for more information.
+	HCS_E_WINDOWS_INSIDER_REQUIRED windows.Errno = 0x80370113
+
+	// The operation could not be started because a required feature is not installed.
+	HCS_E_SERVICE_NOT_AVAILABLE windows.Errno = 0x80370114
+
+	// The operation has not started.
+	HCS_E_OPERATION_NOT_STARTED windows.Errno = 0x80370115
+
+	// The operation is already running.
+	HCS_E_OPERATION_ALREADY_STARTED windows.Errno = 0x80370116
+
+	// The operation is still running.
+	HCS_E_OPERATION_PENDING windows.Errno = 0x80370117
+
+	// The operation did not complete in time.
+	HCS_E_OPERATION_TIMEOUT windows.Errno = 0x80370118
+
+	// An event callback has already been registered on this handle.
+	HCS_E_OPERATION_SYSTEM_CALLBACK_ALREADY_SET windows.Errno = 0x80370119
+
+	// Not enough memory available to return the result of the operation.
+	HCS_E_OPERATION_RESULT_ALLOCATION_FAILED windows.Errno = 0x8037011A
+
+	// Insufficient privileges.
+	// Only administrators or users that are members of the Hyper-V Administrators user group are permitted to access virtual machines or containers.
+	// To add yourself to the Hyper-V Administrators user group, please see https://aka.ms/hcsadmin for more information.
+	HCS_E_ACCESS_DENIED windows.Errno = 0x8037011B
+
+	// The virtual machine or container reported a critical error and was stopped or restarted.
+	HCS_E_GUEST_CRITICAL_ERROR windows.Errno = 0x8037011C
+
+	// The process information is not available.
+	HCS_E_PROCESS_INFO_NOT_AVAILABLE windows.Errno = 0x8037011D
+
+	// The host compute system service has disconnected unexpectedly.
+	HCS_E_SERVICE_DISCONNECT windows.Errno = 0x8037011E
+
+	// The process has already exited.
+	HCS_E_PROCESS_ALREADY_STOPPED windows.Errno = 0x8037011F
+
+	// The virtual machine or container is not configured to perform the operation.
+	HCS_E_SYSTEM_NOT_CONFIGURED_FOR_OPERATION windows.Errno = 0x80370120
+
+	// The operation has already been cancelled.
+	HCS_E_OPERATION_ALREADY_CANCELLED windows.Errno = 0x80370121
+)