runtime

type ContainerCommand struct {
	// Entrypoint container entrypoint
	Entrypoint []string `json:"entrypoint" validate:"required,gte=1" jsonschema:"container entrypoint; required and must contain at least one element"`
	// Commands ran by the entry point
	Commands []string `json:"commands,omitempty" validate:"-" jsonschema:"the arguments passed to the entrypoint"`
}

type ContainerEnvVar struct {
	// Name the environment variable name
	Name string `json:"name" validate:"required" jsonschema:"the environment variable name; required"`
	// Value the environment variable value
	Value string `json:"value" jsonschema:"the environment variable value; may be an empty string"`
}

type ContainerExtraHost struct {
	// Hosts the hostname to map
	Hosts []string `` /* 129-byte string literal not displayed */
	// Address the IP address the hostname resolves to
	Address string `` /* 131-byte string literal not displayed */
}

type ContainerHostMount struct {
	// Path host path to mount
	Path string `json:"path" validate:"required" jsonschema:"the host path to mount; required and must be an absolute path"`
	// ReadOnly whether to mount the path read-only; defaults to true when nil
	ReadOnly *bool `json:"read_only,omitempty" jsonschema:"whether to mount the path read-only; defaults to true when omitted"`
	// MountPath path within the container to mount the host path. The mount path will
	// mirror the host path if this is not specified.
	MountPath *string `` /* 137-byte string literal not displayed */
}

type ContainerRuntimeParams struct {
	// Image container image reference to run
	Image string `json:"image" validate:"required" jsonschema:"container image reference to run; required"`

	// Streaming when streaming STDIN, STDERR, and STDOUT to and from the container,
	// additional configurations needed for streaming.
	Streaming *StreamIOParams `` /* 197-byte string literal not displayed */

	// MemReservation soft memory reservation (e.g. "32m"); defaults when empty
	MemReservation string `json:"mem_reservation,omitempty" jsonschema:"soft memory reservation (e.g. '32m'); defaults to '32m' when omitted"`
	// MemLimit hard memory limit (e.g. "128m"); defaults when empty
	MemLimit string `json:"mem_limit,omitempty" jsonschema:"hard memory limit (e.g. '128m'); defaults to '128m' when omitted"`

	// WorkingDir working directory for the container process; defaults to DefaultContainerWorkingDir
	WorkingDir string `json:"working_dir,omitempty" jsonschema:"working directory for the container process; defaults to '/tmp' when omitted"`

	// WritableDirs memory-backed writable directories overlaid on the read-only rootfs
	WritableDirs []InMemoryWritableDir `` /* 137-byte string literal not displayed */
	// HostMounts host paths bind-mounted into the container
	HostMounts []ContainerHostMount `json:"host_mounts,omitempty" validate:"omitempty,dive" jsonschema:"host paths bind-mounted into the container"`
	// VolumeMounts named persistent volumes / PVCs mounted into the container. The volumes
	// themselves are provisioned by the runtime's controller client, not by this spec.
	VolumeMounts []ContainerVolumeMount `` /* 221-byte string literal not displayed */

	// AddCapabilities Linux capabilities to add back on top of the dropped-by-default set
	// (e.g. NET_BIND_SERVICE to bind ports below 1024)
	AddCapabilities []string `` /* 155-byte string literal not displayed */

	// ExtraHosts additional host-to-IP mappings for the container
	ExtraHosts []ContainerExtraHost `json:"extra_hosts,omitempty" validate:"omitempty,dive" jsonschema:"additional host-to-IP mappings for the container"`
	// Environment additional environment variables for the container process
	Environment []ContainerEnvVar `` /* 126-byte string literal not displayed */

	// StopSignal signal sent to request the container process stop during teardown;
	// defaults to DefaultContainerStopSignal when empty
	StopSignal goutils.ContainerStopSignalENUMType `` /* 183-byte string literal not displayed */

	// TimeoutSecs wall-clock timeout in seconds; clamped to the server ceiling. 0 (unset)
	// means clamp to the server ceiling (treated as +infinity before the min).
	TimeoutSecs int `` /* 192-byte string literal not displayed */
	// TimeoutPolicy how a timeout is packaged into the result; defaults to
	// DefaultContainerTimeoutPolicy when empty
	TimeoutPolicy goutils.ContainerTimeoutPolicyENUMType `` /* 192-byte string literal not displayed */

	// ReadOnlyRootFS mount the container root filesystem read-only; defaults to true when nil
	ReadOnlyRootFS *bool `json:"read_only_rootfs,omitempty" jsonschema:"mount the container root filesystem read-only; defaults to true when omitted"`
	// DropAllCapabilities drop all Linux capabilities; defaults to true when nil
	DropAllCapabilities *bool `json:"drop_all_caps,omitempty" jsonschema:"drop all Linux capabilities; defaults to true when omitted"`
	// NoNewPrivileges set the no-new-privileges security option; defaults to true when nil
	NoNewPrivileges *bool `json:"no_new_privileges,omitempty" jsonschema:"set the no-new-privileges security option; defaults to true when omitted"`
}

type ContainerVolume struct {
	// Name identity of the volume / PVC
	Name string `json:"name" validate:"required" jsonschema:"identity of the volume / PVC; required"`
	// Size requested capacity in bytes. Honored by Kubernetes (storage request) and by
	// capacity-aware Docker volume drivers; the default Docker "local" driver treats it as
	// advisory.
	Size int64 `` /* 249-byte string literal not displayed */
}

type ContainerVolumeMount struct {
	// Name the ContainerVolume / PVC name to mount
	Name string `json:"name" validate:"required" jsonschema:"the ContainerVolume / PVC name to mount; required"`
	// MountPath path within the container to mount at
	MountPath string `` /* 140-byte string literal not displayed */
	// ReadOnly whether to mount read-only; defaults to false when nil. Unlike a host mount,
	// a persistent volume exists to be written to, so read-write is the sensible default.
	ReadOnly *bool `` /* 203-byte string literal not displayed */
}

type DockerPortPublish struct {
	// ContainerPort the port the session command listens on inside the container
	ContainerPort uint16 `` /* 148-byte string literal not displayed */
	// Protocol the port protocol; defaults to DefaultContainerPortProtocol when empty
	Protocol string `` /* 154-byte string literal not displayed */
	// HostPort the host port to bind; 0 requests an ephemeral host port
	HostPort uint16 `json:"host_port,omitempty" jsonschema:"the host port to bind, in 1-65535; omit (0) to request an ephemeral host port"`
	// HostIP the host interface to bind to; defaults to DefaultContainerPublishHostIP when empty
	HostIP string `` /* 166-byte string literal not displayed */
}

type DockerRuntimeParams struct {
	ContainerRuntimeParams

	// RunAsUser user to run the container process as; defaults to DefaultContainerRunAsUser
	RunAsUser string `json:"run_as_user,omitempty" jsonschema:"user to run the container process as; defaults to 'nobody' when omitted"`
	// RunAsGroup group to run the container process as; defaults to DefaultContainerRunAsGroup
	RunAsGroup string `json:"run_as_group,omitempty" jsonschema:"group to run the container process as; defaults to 'nogroup' when omitted"`

	// NetworkMode the container network mode (e.g. "none", "bridge"); defaults to
	// DefaultDockerNetworkMode. Must be routable when PublishPorts is set.
	NetworkMode string `` /* 183-byte string literal not displayed */
	// PublishPorts container ports published to the host for inbound connections
	PublishPorts []DockerPortPublish `` /* 165-byte string literal not displayed */

	// RemoveOnExit remove the container on teardown; defaults to true when nil
	RemoveOnExit *bool `json:"remove_on_exit,omitempty" jsonschema:"remove the container on teardown; defaults to true when omitted"`
}

type DockerVolumeMetadata struct {
	// Driver the volume driver to provision with (e.g. "local"); defaults to the daemon's
	// default driver when empty
	Driver string `json:"driver,omitempty"`
	// DriverOpts driver-specific options (e.g. "type", "device", "o" for the local driver)
	DriverOpts map[string]string `json:"driver_opts,omitempty"`
	// Labels user-defined key/value metadata applied to the volume
	Labels map[string]string `json:"labels,omitempty"`
}

type InMemoryWritableDir struct {
	// Path the directory within the container to back with the memory-backed writable mount
	Path string `` /* 178-byte string literal not displayed */
	// SizeLimit size of the mount in bytes; defaults to DefaultInMemoryWritableDirSize when 0
	SizeLimit int64 `` /* 159-byte string literal not displayed */
}

type StreamIOParams struct {
	// DisplayRows TTY number of rows (in cells).
	DisplayRows uint16 `json:"display_rows" validate:"gte=30" jsonschema:"TTY number of rows (in cells); must be >= 30"`
	// DisplayCols TTY number of columns (in cells).
	DisplayCols uint16 `json:"display_cols" validate:"gte=80" jsonschema:"TTY number of columns (in cells); must be >= 80"`
}

type SystemCallResp struct {
	// ExitCode the wrapped program's exit code.
	ExitCode int `json:"exit_code"`
	// Output the combined STDOUT+STDERR captured from the program in execution order
	Output string `json:"output"`
}

type SystemCallRuntime interface {
	/*
		Start launch the runtime and begin executing the system cll

			@param ctx context.Context - execution context
	*/
	Start(ctx context.Context) error

	/*
		PipeInput only usable on runtimes configured with streaming, stream data from `input`
		into the runtime's STDIN until EOF.

			@param ctx context.Context - execution context
	*/
	PipeInput(input io.Reader) error

	/*
		PipeOutput only usable on runtimes configured with streaming, stream data from runtime
		STDERR and STDOUT to `output` until EOF

			@param ctx context.Context - execution context
	*/
	PipeOutput(output io.Writer) error

	/*
		Wait for the runtime to finish or time out, then collect the exit code and combined output.

			@param ctx context.Context - execution context
			@returns the execution result process status code and combined output
	*/
	Wait(ctx context.Context) (SystemCallResp, error)

	/*
		Cleanup tear down the runtime. For container backed runtimes that are configured with
		RemoveOnExit, the container associated with this runtime is removed; otherwise this
		is a NOOP beyond releasing internal resources.

			@param ctx context.Context - execution context
			@returns error if cleanup failed
	*/
	Cleanup(ctx context.Context) error
}

type VolumeManager interface {
	/*
		Start perform any initialization the manager needs before serving volume operations
		(e.g. establishing the Docker client connection).

			@param ctxt context.Context - the operational context
	*/
	Start(ctxt context.Context) error

	/*
		Cleanup release any resources the manager acquired in Start (e.g. closing the Docker
		client connection).

			@param ctxt context.Context - the operational context
	*/
	Cleanup(ctxt context.Context) error

	/*
		ListVolumes list the managed volumes, optionally restricted to those whose name
		carries a given prefix.

			@param ctxt context.Context - the operational context
			@param namePrefix *string - only volumes whose name starts with this prefix are
			    returned; an empty string returns all volumes
			@returns the matching volumes
	*/
	ListVolumes(ctxt context.Context, namePrefix *string) ([]ContainerVolume, error)

	/*
		GetVolume find a specific volume by name, returning it along with the identities of the
		entities that currently mount it (container names/IDs for Docker, pod names for
		Kubernetes). Returns a not-found error when no volume by that name exists.

			@param ctxt context.Context - the operational context
			@param name string - the volume name
			@returns the volume, and the identities of the entities currently mounting it
	*/
	GetVolume(ctxt context.Context, name string) (ContainerVolume, []string, error)

	/*
		DefineVolume create a new volume.

			@param ctxt context.Context - the operational context
			@param volume ContainerVolume - the volume to create
			@param metadata any - manager-specific provisioning parameters (e.g. Docker driver
			    and driver options); the concrete type is defined by the implementation
			@returns the created volume
	*/
	DefineVolume(ctxt context.Context, volume ContainerVolume, metadata any) (ContainerVolume, error)

	/*
		DeleteVolume delete a volume by name. Deleting a volume that does not exist is a
		no-op success (idempotent).

			@param ctxt context.Context - the operational context
			@param name string - the volume name
	*/
	DeleteVolume(ctxt context.Context, name string) error
}