prot

package
v0.12.0-rc.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 2, 2023 License: MIT Imports: 9 Imported by: 0

Documentation

Overview

Package prot defines any structures used in the communication between the HCS and the GCS. Some of these structures are also used outside the bridge as good ways of packaging parameters to core calls.

Index

Constants

View Source
const (
	// MtNone is the default MessageType.
	MtNone = 0
	// MtRequest is the MessageType when a request is received.
	MtRequest = 0x10000000
	// MtResponse is the MessageType used to send a response.
	MtResponse = 0x20000000
	// MtNotification is the MessageType used to send a notification not
	// initiated by a request.
	MtNotification = 0x30000000
)
View Source
const (
	// McNone is the default category.
	McNone = 0
	// McComputeSystem is the category to define message types for compute
	// systems.
	McComputeSystem = 0x00100000
)
View Source
const (
	// MiNone is the unknown identifier.
	MiNone = 0

	// ComputeSystemCreateV1 is the create container request.
	ComputeSystemCreateV1 = 0x10100101
	// ComputeSystemStartV1 is the start container request.
	ComputeSystemStartV1 = 0x10100201
	// ComputeSystemShutdownGracefulV1 is the graceful shutdown container
	// request.
	ComputeSystemShutdownGracefulV1 = 0x10100301
	// ComputeSystemShutdownForcedV1 is the forceful shutdown container request.
	ComputeSystemShutdownForcedV1 = 0x10100401
	// ComputeSystemExecuteProcessV1 is the execute process request.
	ComputeSystemExecuteProcessV1 = 0x10100501
	// ComputeSystemWaitForProcessV1 is the wait for process exit request.
	ComputeSystemWaitForProcessV1 = 0x10100601
	// ComputeSystemSignalProcessV1 is the signal process request.
	ComputeSystemSignalProcessV1 = 0x10100701
	// ComputeSystemResizeConsoleV1 is the resize console tty request.
	ComputeSystemResizeConsoleV1 = 0x10100801
	// ComputeSystemGetPropertiesV1 is the list process properties request.
	ComputeSystemGetPropertiesV1 = 0x10100901
	// ComputeSystemModifySettingsV1 is the modify container request.
	ComputeSystemModifySettingsV1 = 0x10100a01
	// ComputeSystemNegotiateProtocolV1 is the protocol negotiation request.
	ComputeSystemNegotiateProtocolV1 = 0x10100b01
	// ComputeSystemDumpStacksV1 is the dump stack request
	ComputeSystemDumpStacksV1 = 0x10100c01
	// ComputeSystemDeleteContainerStateV1 is the delete container request.
	ComputeSystemDeleteContainerStateV1 = 0x10100d01

	// ComputeSystemResponseCreateV1 is the create container response.
	ComputeSystemResponseCreateV1 = 0x20100101
	// ComputeSystemResponseStartV1 is the start container response.
	ComputeSystemResponseStartV1 = 0x20100201
	// ComputeSystemResponseShutdownGracefulV1 is the graceful shutdown
	// container response.
	ComputeSystemResponseShutdownGracefulV1 = 0x20100301
	// ComputeSystemResponseShutdownForcedV1 is the forceful shutdown container
	// response.
	ComputeSystemResponseShutdownForcedV1 = 0x20100401
	// ComputeSystemResponseExecuteProcessV1 is the execute process response.
	ComputeSystemResponseExecuteProcessV1 = 0x20100501
	// ComputeSystemResponseWaitForProcessV1 is the wait for process exit
	// response.
	ComputeSystemResponseWaitForProcessV1 = 0x20100601
	// ComputeSystemResponseSignalProcessV1 is the signal process response.
	ComputeSystemResponseSignalProcessV1 = 0x20100701
	// ComputeSystemResponseResizeConsoleV1 is the resize console tty response.
	ComputeSystemResponseResizeConsoleV1 = 0x20100801
	// ComputeSystemResponseGetPropertiesV1 is the list process properties
	// response.
	ComputeSystemResponseGetPropertiesV1 = 0x20100901
	// ComputeSystemResponseModifySettingsV1 is the modify container response.
	ComputeSystemResponseModifySettingsV1 = 0x20100a01
	// ComputeSystemResponseNegotiateProtocolV1 is the protocol negotiation
	// response.
	ComputeSystemResponseNegotiateProtocolV1 = 0x20100b01
	// ComputeSystemResponseDumpStacksV1 is the dump stack response
	ComputeSystemResponseDumpStacksV1 = 0x20100c01

	// ComputeSystemNotificationV1 is the notification identifier.
	ComputeSystemNotificationV1 = 0x30100101
)
View Source
const (
	// NtNone indicates nothing to be sent back to the HCS
	NtNone = NotificationType("None")
	// NtGracefulExit indicates a graceful exit notification to be sent back to
	// the HCS
	NtGracefulExit = NotificationType("GracefulExit")
	// NtForcedExit indicates a forced exit notification to be sent back to the
	// HCS
	NtForcedExit = NotificationType("ForcedExit")
	// NtUnexpectedExit indicates an unexpected exit notification to be sent
	// back to the HCS
	NtUnexpectedExit = NotificationType("UnexpectedExit")
	// NtReboot indicates a reboot notification to be sent back to the HCS
	NtReboot = NotificationType("Reboot")
	// NtConstructed indicates a constructed notification to be sent back to the
	// HCS
	NtConstructed = NotificationType("Constructed")
	// NtStarted indicates a started notification to be sent back to the HCS
	NtStarted = NotificationType("Started")
	// NtPaused indicates a paused notification to be sent back to the HCS
	NtPaused = NotificationType("Paused")
	// NtUnknown indicates an unknown notification to be sent back to the HCS
	NtUnknown = NotificationType("Unknown")
)
View Source
const (
	// AoNone indicates no active operation
	AoNone = ActiveOperation("None")
	// AoConstruct indicates a construct active operation
	AoConstruct = ActiveOperation("Construct")
	// AoStart indicates a start active operation
	AoStart = ActiveOperation("Start")
	// AoPause indicates a pause active operation
	AoPause = ActiveOperation("Pause")
	// AoResume indicates a resume active operation
	AoResume = ActiveOperation("Resume")
	// AoShutdown indicates a shutdown active operation
	AoShutdown = ActiveOperation("Shutdown")
	// AoTerminate indicates a terminate active operation
	AoTerminate = ActiveOperation("Terminate")
)
View Source
const (
	// PtMemory is the property type for memory
	PtMemory = PropertyType("Memory")
	// PtCPUGroup is the property type for CPU group
	PtCPUGroup = PropertyType("CpuGroup")
	// PtStatistics is the property type for statistics
	PtStatistics = PropertyType("Statistics")
	// PtProcessList is the property type for a process list
	PtProcessList = PropertyType("ProcessList")
	// PtPendingUpdates is the property type for determining if there are
	// pending updates
	PtPendingUpdates = PropertyType("PendingUpdates")
	// PtTerminateOnLastHandleClosed is the property type for exiting when the
	// last handle is closed
	PtTerminateOnLastHandleClosed = PropertyType("TerminateOnLastHandleClosed")
	// PtMappedDirectory is the property type for mapped directories
	PtMappedDirectory = PropertyType("MappedDirectory")
	// PtSystemGUID is the property type for the system GUID
	PtSystemGUID = PropertyType("SystemGUID")
	// PtNetwork is the property type for networking
	PtNetwork = PropertyType("Network")
	// PtMappedPipe is the property type for mapped pipes
	PtMappedPipe = PropertyType("MappedPipe")
	// PtMappedVirtualDisk is the property type for mapped virtual disks
	PtMappedVirtualDisk = PropertyType("MappedVirtualDisk")
)
View Source
const (
	// RtAdd is the "Add" request type of operation
	RtAdd = RequestType("Add")
	// RtRemove is the "Remove" request type of operation
	RtRemove = RequestType("Remove")
	// RtUpdate is the "Update" request type of operation
	RtUpdate = RequestType("Update")
)
View Source
const InfiniteWaitTimeout = 0xffffffff

InfiniteWaitTimeout is the value for ContainerWaitForProcess.TimeoutInMs that indicates that no timeout should be in effect.

View Source
const MessageHeaderSize = 16

MessageHeaderSize is the size in bytes of the MessageHeader struct.

Variables

This section is empty.

Functions

This section is empty.

Types

type ActiveOperation

type ActiveOperation string

ActiveOperation defines an operation to be associated with a notification sent back to the HCS.

type ContainerCreate

type ContainerCreate struct {
	MessageBase
	ContainerConfig   string
	SupportedVersions ProtocolSupport `json:",omitempty"`
}

ContainerCreate is the message from the HCS specifying to create a container in the utility VM. This message won't actually create a Linux container inside the utility VM, but will set up the infrustructure needed to start one once the container's initial process is executed.

type ContainerCreateResponse

type ContainerCreateResponse struct {
	MessageResponseBase
	SelectedVersion         string `json:",omitempty"`
	SelectedProtocolVersion uint32
}

ContainerCreateResponse is the message to the HCS responding to a ContainerCreate message. It serves a protocol negotiation function as well for protocol versions 3 and lower, returning protocol version information to the HCS.

type ContainerExecuteProcess

type ContainerExecuteProcess struct {
	MessageBase
	Settings ExecuteProcessSettings
}

ContainerExecuteProcess is the message from the HCS specifying to execute a process either inside or outside the container namespace.

type ContainerExecuteProcessResponse

type ContainerExecuteProcessResponse struct {
	MessageResponseBase
	ProcessID uint32 `json:"ProcessId"`
}

ContainerExecuteProcessResponse is the message to the HCS responding to a ContainerExecuteProcess message. It provides back the process's pid.

type ContainerGetProperties

type ContainerGetProperties struct {
	MessageBase
	Query string
}

ContainerGetProperties is the message from the HCS requesting certain properties of the container, such as a list of its processes.

type ContainerGetPropertiesResponse

type ContainerGetPropertiesResponse struct {
	MessageResponseBase
	Properties string
}

ContainerGetPropertiesResponse is the message to the HCS responding to a ContainerGetProperties message. It contains a string representing the properties requested.

type ContainerModifySettings

type ContainerModifySettings struct {
	MessageBase
	Request interface{}
}

ContainerModifySettings is the message from the HCS specifying how a certain container resource should be modified.

func UnmarshalContainerModifySettings

func UnmarshalContainerModifySettings(b []byte) (*ContainerModifySettings, error)

UnmarshalContainerModifySettings unmarshals the given bytes into a ContainerModifySettings message. This function is required because properties such as `Settings` can be of many types identified by the `ResourceType` and require dynamic unmarshalling.

type ContainerNotification

type ContainerNotification struct {
	MessageBase
	Type       NotificationType
	Operation  ActiveOperation
	Result     int32
	ResultInfo string `json:",omitempty"`
}

ContainerNotification is a message sent from the GCS to the HCS to indicate some kind of event. At the moment, it is only used for container exit notifications.

type ContainerResizeConsole

type ContainerResizeConsole struct {
	MessageBase
	ProcessID uint32 `json:"ProcessId"`
	Height    uint16
	Width     uint16
}

ContainerResizeConsole is the message from the HCS specifying to change the console size for the given process.

type ContainerSignalProcess

type ContainerSignalProcess struct {
	MessageBase
	ProcessID uint32               `json:"ProcessId"`
	Options   SignalProcessOptions `json:",omitempty"`
}

ContainerSignalProcess is the message from the HCS specifying to send a signal to the given process.

type ContainerWaitForProcess

type ContainerWaitForProcess struct {
	MessageBase
	ProcessID   uint32 `json:"ProcessId"`
	TimeoutInMs uint32
}

ContainerWaitForProcess is the message from the HCS specifying to wait until the given process exits. After receiving this message, the corresponding response should not be sent until the process has exited.

type ContainerWaitForProcessResponse

type ContainerWaitForProcessResponse struct {
	MessageResponseBase
	ExitCode uint32
}

ContainerWaitForProcessResponse is the message to the HCS responding to a ContainerWaitForProcess message. It is only sent when the process has exited.

type DumpStacksResponse

type DumpStacksResponse struct {
	MessageResponseBase
	GuestStacks string
}

type ErrorRecord

type ErrorRecord struct {
	Result       int32
	Message      string
	StackTrace   string `json:",omitempty"`
	ModuleName   string
	FileName     string
	Line         uint32
	FunctionName string `json:",omitempty"`
}

ErrorRecord represents a single error to be reported back to the HCS. It allows for specifying information about the source of the error, as well as an error message and stack trace.

type ExecuteProcessSettings

type ExecuteProcessSettings struct {
	ProcessParameters       string
	VsockStdioRelaySettings ExecuteProcessVsockStdioRelaySettings
}

ExecuteProcessSettings defines the settings for a single process to be executed either inside or outside the container namespace.

type ExecuteProcessVsockStdioRelaySettings

type ExecuteProcessVsockStdioRelaySettings struct {
	StdIn  uint32 `json:",omitempty"`
	StdOut uint32 `json:",omitempty"`
	StdErr uint32 `json:",omitempty"`
}

ExecuteProcessVsockStdioRelaySettings defines the port numbers for each stdio socket for a process.

type GcsCapabilities

type GcsCapabilities struct {
	// True if a create message should be sent for the hosting system itself.
	SendHostCreateMessage bool `json:",omitempty"`
	// True if a start message should be sent for the hosting system itself. If
	// SendHostCreateMessage is false, a start message will not be sent either.
	SendHostStartMessage bool `json:",omitempty"`
	// True if an HVSocket ModifySettings request should be sent immediately
	// after the create/start messages are sent (if they're sent at all). This
	// ModifySettings request would be to configure the local and parent
	// Hyper-V socket addresses of the VM, and would have a RequestType of
	// Update.
	HVSocketConfigOnStartup bool            `json:"HvSocketConfigOnStartup,omitempty"`
	SupportedSchemaVersions []SchemaVersion `json:",omitempty"`
	RuntimeOsType           OsType          `json:",omitempty"`
	// GuestDefinedCapabilities define any JSON object that will be directly
	// passed to a client of the HCS. This can be useful to pass runtime
	// specific capabilities not tied to the platform itself.
	GuestDefinedCapabilities GcsGuestCapabilities `json:",omitempty"`
}

GcsCapabilities specifies the abilities and scenarios supported by this GCS.

type GcsGuestCapabilities

type GcsGuestCapabilities struct {
	NamespaceAddRequestSupported  bool `json:",omitempty"`
	SignalProcessSupported        bool `json:",omitempty"`
	DumpStacksSupported           bool `json:",omitempty"`
	DeleteContainerStateSupported bool `json:",omitempty"`
}

GcsGuestCapabilities represents the customized guest capabilities supported by this GCS.

type MappedDirectory

type MappedDirectory struct {
	ContainerPath     string
	CreateInUtilityVM bool   `json:",omitempty"`
	ReadOnly          bool   `json:",omitempty"`
	Port              uint32 `json:",omitempty"`
}

MappedDirectory represents a directory on the host which is mapped to a directory on the guest through a technology such as Plan9.

type MappedVirtualDisk

type MappedVirtualDisk struct {
	ContainerPath     string
	Lun               uint8 `json:",omitempty"`
	CreateInUtilityVM bool  `json:",omitempty"`
	ReadOnly          bool  `json:",omitempty"`
	AttachOnly        bool  `json:",omitempty"`
}

MappedVirtualDisk represents a disk on the host which is mapped into a directory in the guest.

type MessageBase

type MessageBase struct {
	ContainerID string `json:"ContainerId"`
	ActivityID  string `json:"ActivityId"`

	// OpenCensusSpanContext is the encoded OpenCensus `trace.SpanContext` if
	// set when making the request.
	//
	// NOTE: This is not a part of the protocol but because its a JSON protocol
	// adding fields is a non-breaking change. If the guest supports it this is
	// just additive context.
	OpenCensusSpanContext *ocspancontext `json:"ocsc,omitempty"`
}

MessageBase is the base type embedded in all messages sent from the HCS to the GCS, as well as ContainerNotification which is sent from GCS to HCS.

type MessageCategory

type MessageCategory uint32

MessageCategory allows splitting the identifier namespace to easily route similar messages for common processing.

type MessageHeader

type MessageHeader struct {
	Type MessageIdentifier
	Size uint32
	ID   SequenceID
}

MessageHeader is the common header present in all communications messages.

type MessageIdentifier

type MessageIdentifier uint32

MessageIdentifier describes the Type field of a MessageHeader struct.

func GetResponseIdentifier

func GetResponseIdentifier(identifier MessageIdentifier) MessageIdentifier

GetResponseIdentifier returns the response version of the given request identifier. So, for example, an input of ComputeSystemCreateV1 would result in an output of ComputeSystemResponseCreateV1.

func (MessageIdentifier) String

func (mi MessageIdentifier) String() string

String returns the string representation of the message identifier.

type MessageResponseBase

type MessageResponseBase struct {
	Result       int32
	ActivityID   string        `json:"ActivityId,omitempty"`
	ErrorMessage string        `json:",omitempty"` // Only used by hcsshim external bridge
	ErrorRecords []ErrorRecord `json:",omitempty"`
}

MessageResponseBase is the base type embedded in all messages sent from the GCS to the HCS except for ContainerNotification.

func (*MessageResponseBase) Base

Base returns the response base by reference.

type MessageType

type MessageType uint32

MessageType is the type of the message.

type NegotiateProtocol

type NegotiateProtocol struct {
	MessageBase
	MinimumVersion uint32
	MaximumVersion uint32
}

NegotiateProtocol is the message from the HCS used to determine the protocol version that will be used for future communication.

type NegotiateProtocolResponse

type NegotiateProtocolResponse struct {
	MessageResponseBase
	Version      uint32
	Capabilities GcsCapabilities
}

NegotiateProtocolResponse is the message to the HCS responding to a NegotiateProtocol message. It specifies the preferred protocol version and available capabilities of the GCS.

type NetworkAdapter

type NetworkAdapter struct {
	AdapterInstanceID    string `json:"AdapterInstanceId"`
	FirewallEnabled      bool
	NatEnabled           bool
	MacAddress           string `json:",omitempty"`
	AllocatedIPAddress   string `json:"AllocatedIpAddress,omitempty"`
	HostIPAddress        string `json:"HostIpAddress,omitempty"`
	HostIPPrefixLength   uint8  `json:"HostIpPrefixLength,omitempty"`
	AllocatedIPv6Address string `json:"AllocatedIpv6Address,omitempty"`
	HostIPv6Address      string `json:"HostIpv6Address,omitempty"`
	HostIPv6PrefixLength uint8  `json:"HostIpv6PrefixLength,omitempty"`
	HostDNSServerList    string `json:"HostDnsServerList,omitempty"`
	HostDNSSuffix        string `json:"HostDnsSuffix,omitempty"`
	EnableLowMetric      bool   `json:",omitempty"`
	EncapOverhead        uint16 `json:",omitempty"`
}

NetworkAdapter represents a network interface and its associated configuration.

type NotificationType

type NotificationType string

NotificationType defines a type of notification to be sent back to the HCS.

type OsType

type OsType string

OsType defines the operating system type identifier of the guest hosting the GCS.

const OsTypeLinux OsType = "Linux"

OsTypeLinux is the OS type the HCS expects for a Linux GCS

type ProcessDetails

type ProcessDetails struct {
	ProcessID uint32 `json:"ProcessId"`
}

ProcessDetails represents information about a given process.

type ProcessParameters

type ProcessParameters struct {
	// CommandLine is a space separated list of command line parameters. For
	// example, the command which sleeps for 100 seconds would be represented by
	// the CommandLine string "sleep 100".
	CommandLine string `json:",omitempty"`
	// CommandArgs is a list of strings representing the command to execute. If
	// it is not empty, it will be used by the GCS. If it is empty, CommandLine
	// will be used instead.
	CommandArgs      []string          `json:",omitempty"`
	WorkingDirectory string            `json:",omitempty"`
	Environment      map[string]string `json:",omitempty"`
	EmulateConsole   bool              `json:",omitempty"`
	CreateStdInPipe  bool              `json:",omitempty"`
	CreateStdOutPipe bool              `json:",omitempty"`
	CreateStdErrPipe bool              `json:",omitempty"`
	// If IsExternal is false, the process will be created inside a container.
	// If true, it will be created external to any container. The latter is
	// useful if, for example, you want to start up a shell in the utility VM
	// for debugging/diagnostic purposes.
	IsExternal bool `json:"CreateInUtilityVM,omitempty"`
	// If this is the first process created for this container, this field must
	// be specified. Otherwise, it must be left blank and the other fields must
	// be specified.
	OCISpecification *oci.Spec `json:"OciSpecification,omitempty"`

	OCIProcess *oci.Process `json:"OciProcess,omitempty"`
}

ProcessParameters represents any process which may be started in the utility VM. This covers three cases: 1.) It is an external process, i.e. a process running inside the utility VM but not inside any container. In this case, don't specify the OCISpecification field, but specify all other fields. 2.) It is the first process in a container. In this case, specify only the OCISpecification field, and not the other fields. 3.) It is a container process, but not the first process in that container. In this case, don't specify the OCISpecification field, but specify all other fields. This is the same as if it were an external process.

type Properties

type Properties struct {
	ProcessList []ProcessDetails `json:",omitempty"`
}

Properties represents the properties of a compute system.

type PropertiesV2

type PropertiesV2 struct {
	ProcessList []ProcessDetails `json:"ProcessList,omitempty"`
	Metrics     *v1.Metrics      `json:"LCOWMetrics,omitempty"`
}

type PropertyQuery

type PropertyQuery struct {
	PropertyTypes []PropertyType `json:",omitempty"`
}

PropertyQuery is a query to specify which properties are requested.

type PropertyType

type PropertyType string

PropertyType is the type of property, such as memory or virtual disk, which is to be modified for the container.

type ProtocolSupport

type ProtocolSupport struct {
	MinimumVersion         string `json:",omitempty"`
	MaximumVersion         string `json:",omitempty"`
	MinimumProtocolVersion uint32
	MaximumProtocolVersion uint32
}

ProtocolSupport specifies the protocol versions to be used for HCS-GCS communication.

type ProtocolVersion

type ProtocolVersion uint32

ProtocolVersion is a type for the selected HCS<->GCS protocol version of messages

const (
	PvInvalid ProtocolVersion = 0
	PvV4      ProtocolVersion = 4
	PvMax     ProtocolVersion = PvV4
)

Protocol versions.

type RequestType

type RequestType string

RequestType is the type of operation to perform on a given property type.

type ResourceModificationRequestResponse

type ResourceModificationRequestResponse struct {
	ResourceType PropertyType
	RequestType  RequestType `json:",omitempty"`
	Settings     interface{} `json:",omitempty"`
}

ResourceModificationRequestResponse details a container resource which should be modified, how, and with what parameters.

type SchemaVersion

type SchemaVersion struct {
	Major uint32 `json:",omitempty"`
	Minor uint32 `json:",omitempty"`
}

SchemaVersion defines the version of the schema that should be deserialized.

func (*SchemaVersion) Cmp

func (s *SchemaVersion) Cmp(v SchemaVersion) int

Cmp compares s and v and returns:

-1 if s <  v
0 if s == v
1 if s >  v

type SequenceID

type SequenceID uint64

SequenceID is used to correlate requests and responses.

type SignalProcessOptions

type SignalProcessOptions struct {
	Signal int32
}

SignalProcessOptions represents the options for signaling a process.

type VMHostedContainerSettings

type VMHostedContainerSettings struct {
	Layers []hcsschema.Layer
	// SandboxDataPath is in this case the identifier (such as the SCSI number)
	// of the sandbox device.
	SandboxDataPath    string
	MappedVirtualDisks []MappedVirtualDisk
	MappedDirectories  []MappedDirectory
	NetworkAdapters    []NetworkAdapter `json:",omitempty"`
}

VMHostedContainerSettings is the set of settings used to specify the initial configuration of a container.

type VMHostedContainerSettingsV2

type VMHostedContainerSettingsV2 struct {
	SchemaVersion    SchemaVersion
	OCIBundlePath    string    `json:"OciBundlePath,omitempty"`
	OCISpecification *oci.Spec `json:"OciSpecification,omitempty"`
	// ScratchDirPath represents the path inside the UVM at which the container scratch
	// directory is present.  Usually, this is the path at which the container scratch
	// VHD is mounted inside the UVM. But in case of scratch sharing this is a
	// directory under the UVM scratch directory.
	ScratchDirPath string
}

VMHostedContainerSettingsV2 defines the portion of the ContainerCreate.ContainerConfig that is sent via a V2 call. This correlates to the 'HostedSystem' on the HCS side but rather than sending the 'Container' field the Linux GCS accepts an oci.Spec directly.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL