host

package
v0.0.0-...-c82e7e9 Latest Latest
Warning

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

Go to latest
Published: Oct 31, 2026 License: MPL-2.0 Imports: 37 Imported by: 0

Documentation

Overview

Package host implements the trusted Linux supervisor boundary. No module configuration, backend secret, or caller-provided host path belongs here.

Index

Constants

View Source
const GuestIPCPath = "/run/flexmodule/ipc"
View Source
const GuestPersistentPath = "/var/lib/flexmodule/data"
View Source
const GuestScratchPath = "/var/lib/flexmodule/scratch"
View Source
const ImageManifestLabel = "org.chatanium.flexmodule.manifest.v2"

Variables

View Source
var ErrCleanupIncomplete = errors.New("host cleanup incomplete")
View Source
var ErrCreateAlreadySubmitted = errors.New("Docker create was already submitted")
View Source
var ErrCreateUnresolved = errors.New("submitted Docker create remains unresolved")

Functions

This section is empty.

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client owns one epoch belonging to this actual process. Every operation opens its own authenticated packet connection so Wait cannot block kill/release.

func Dial

func Dial(ctx context.Context, c ClientConfig) (*Client, error)

func (*Client) Acquire

func (c *Client) Acquire(ctx context.Context, s LaunchSpec) (Lease, error)

func (*Client) CaptureSocket

func (c *Client) CaptureSocket(ctx context.Context, id, name string) (*os.File, error)

func (*Client) Close

func (c *Client) Close() error

func (*Client) Create

func (c *Client) Create(ctx context.Context, id string, bootstrap []string, hostSocketDir string) (*Container, error)

func (*Client) EpochID

func (c *Client) EpochID() string

func (*Client) ImageManifest

func (c *Client) ImageManifest(ctx context.Context, digest string) ([]byte, error)

ImageManifest retrieves only the declaration from one exact local image. It is untrusted requirements data, never an approval or published grant.

func (*Client) Reconcile

func (c *Client) Reconcile(ctx context.Context) error

func (*Client) Release

func (c *Client) Release(ctx context.Context, id string) error

func (*Client) SetEgress

func (c *Client) SetEgress(ctx context.Context, id string, p EgressPolicy) error

func (*Client) Start

func (c *Client) Start(ctx context.Context, id string) error

func (*Client) Terminate

func (c *Client) Terminate(ctx context.Context, id string) error

func (*Client) Timeout

func (c *Client) Timeout() time.Duration

Timeout is available to the trusted runner for independent finite teardown.

func (*Client) Wait

func (c *Client) Wait(ctx context.Context, id string) (Exit, error)

type ClientConfig

type ClientConfig struct {
	SocketPath       string
	SupervisorUID    uint32
	MaxMessageBytes  int
	OperationTimeout time.Duration
}

type Container

type Container struct {
	ID     string
	Stdout *os.File
	Stderr *os.File
}

type CreateJournal

CreateJournal commits the submission before Docker dispatch. A successful response or an exact ownership-checked observation must be durable before deleting the created object. Only an authoritative completed negative response may reject a submission; absence, deadlines and transport errors never do.

type CreateKind

type CreateKind string
const (
	CreateContainer CreateKind = "container"
	CreateNetwork   CreateKind = "network"
)

type CreateRecord

type CreateRecord struct {
	Identity  string
	State     CreateState
	ObjectID  string
	Rejection string
}

type CreateState

type CreateState string
const (
	CreateSubmitted CreateState = "SUBMITTED"
	CreateObserved  CreateState = "OBSERVED"
	CreateRejected  CreateState = "REJECTED"
)

type DockerConfig

type DockerConfig struct {
	Endpoint      string `json:"endpoint"`
	EngineVersion string `json:"engine_version"`
	RuntimeName   string `json:"runtime_name"`
	RunscPath     string `json:"runsc_path"`
	RunscVersion  string `json:"runsc_version"`
	RunscSHA256   string `json:"runsc_sha256"`
	// Exact per-file hashes of the complete release, including shim and gvisor-bin.
	RunscFiles          map[string]string `json:"runsc_files"`
	APIDeadline         time.Duration     `json:"api_deadline"`
	TerminationDeadline time.Duration     `json:"termination_deadline"`
	Network             NetworkConfig     `json:"network"`
}

type DockerPlatform

type DockerPlatform struct {
	// contains filtered or unexported fields
}

func NewDockerPlatform

func NewDockerPlatform(cfg DockerConfig) (*DockerPlatform, error)

func (*DockerPlatform) BindCreateJournal

func (p *DockerPlatform) BindCreateJournal(j CreateJournal) error

func (*DockerPlatform) Close

func (p *DockerPlatform) Close() error

func (*DockerPlatform) Create

func (p *DockerPlatform) Create(ctx context.Context, spec LaunchSpec, lease Lease, env []string, socketDir string) (*Container, error)

func (*DockerPlatform) ImageManifest

func (p *DockerPlatform) ImageManifest(ctx context.Context, digest string, maxBytes int64) ([]byte, error)

func (*DockerPlatform) Preflight

func (p *DockerPlatform) Preflight(ctx context.Context) error

func (*DockerPlatform) Reconcile

func (p *DockerPlatform) Reconcile(ctx context.Context, o Ownership) error

func (*DockerPlatform) SetEgress

func (p *DockerPlatform) SetEgress(ctx context.Context, o Ownership, policy EgressPolicy) error

func (*DockerPlatform) Start

func (p *DockerPlatform) Start(ctx context.Context, o Ownership) error

func (*DockerPlatform) Terminate

func (p *DockerPlatform) Terminate(ctx context.Context, o Ownership) error

func (*DockerPlatform) Wait

func (p *DockerPlatform) Wait(ctx context.Context, o Ownership) (Exit, error)

type EgressPolicy

type EgressPolicy string
const (
	EgressNone           EgressPolicy = "NONE"
	EgressPublicInternet EgressPolicy = "PUBLIC_INTERNET"
)

type Error

type Error struct {
	Reason  string `json:"reason"`
	Message string `json:"message"`
}

func (*Error) Error

func (e *Error) Error() string

type Exit

type Exit struct {
	Code      int64 `json:"code"`
	OOMKilled bool  `json:"oom_killed"`
}

type FailurePhase

type FailurePhase string

These finite codes are host-selected diagnostics, never module text, paths, certificates, output, or daemon error bodies.

const (
	PhaseAttach    FailurePhase = "ATTACH"
	PhasePrestart  FailurePhase = "PRESTART"
	PhaseStart     FailurePhase = "START"
	PhasePoststart FailurePhase = "POSTSTART"
	PhaseRunning   FailurePhase = "RUNNING"
	PhaseCleanup   FailurePhase = "CLEANUP"
)

type FailureReason

type FailureReason string
const (
	FailureBootstrapFormat        FailureReason = "BOOTSTRAP_FORMAT_INVALID"
	FailureBootstrapProtocol      FailureReason = "BOOTSTRAP_PROTOCOL_INVALID"
	FailureBootstrapNetwork       FailureReason = "BOOTSTRAP_NETWORK_INVALID"
	FailureBootstrapMux           FailureReason = "BOOTSTRAP_MULTIPLEX_REQUIRED"
	FailureBootstrapTLS           FailureReason = "BOOTSTRAP_CERTIFICATE_INVALID"
	FailureBootstrapSocket        FailureReason = "BOOTSTRAP_SOCKET_OUT_OF_SCOPE"
	FailureBootstrapLimit         FailureReason = "BOOTSTRAP_MESSAGE_TOO_LARGE"
	FailureBootstrapEOF           FailureReason = "BOOTSTRAP_EOF"
	FailureBootstrapForward       FailureReason = "BOOTSTRAP_FORWARD_FAILED"
	FailureAttachRead             FailureReason = "ATTACH_STREAM_READ_FAILED"
	FailureAttachFrame            FailureReason = "ATTACH_FRAME_INVALID"
	FailureAttachEOF              FailureReason = "ATTACH_EOF_WHILE_RUNNING"
	FailureLogSink                FailureReason = "LOG_SINK_IO_FAILED"
	FailureInspect                FailureReason = "CONTAINER_INSPECT_FAILED"
	FailureStartAPI               FailureReason = "CONTAINER_START_API_FAILED"
	FailureNotRunning             FailureReason = "CONTAINER_NOT_RUNNING"
	FailureIsolation              FailureReason = "CONTAINER_ISOLATION_MISMATCH"
	FailureIdentity               FailureReason = "CONTAINER_IDENTITY_MISMATCH"
	FailureImage                  FailureReason = "CONTAINER_IMAGE_PROCESS_MISMATCH"
	FailureDNS                    FailureReason = "CONTAINER_RESOLVER_MISMATCH"
	FailureMount                  FailureReason = "CONTAINER_MOUNT_MISMATCH"
	FailureNetwork                FailureReason = "CONTAINER_NETWORK_TOPOLOGY_MISMATCH"
	FailureCgroupMembership       FailureReason = "CGROUP_MEMBERSHIP_UNAVAILABLE"
	FailureCgroupMemoryRead       FailureReason = "CGROUP_MEMORY_READ_FAILED"
	FailureCgroupMemory           FailureReason = "CGROUP_MEMORY_LIMIT_MISMATCH"
	FailureCgroupSwapRead         FailureReason = "CGROUP_SWAP_READ_FAILED"
	FailureCgroupSwap             FailureReason = "CGROUP_SWAP_LIMIT_MISMATCH"
	FailureCgroupPidsRead         FailureReason = "CGROUP_PIDS_READ_FAILED"
	FailureCgroupPids             FailureReason = "CGROUP_PIDS_LIMIT_MISMATCH"
	FailureCgroupCPURead          FailureReason = "CGROUP_CPU_READ_FAILED"
	FailureCgroupCPU              FailureReason = "CGROUP_CPU_LIMIT_MISMATCH"
	FailureCleanupPlatform        FailureReason = "PLATFORM_RECONCILE_FAILED"
	FailureCleanupCreateGuard     FailureReason = "CREATE_GUARD_FAILED"
	FailureCleanupScratch         FailureReason = "SCRATCH_REMOVAL_FAILED"
	FailureCleanupIPC             FailureReason = "IPC_REMOVAL_FAILED"
	FailureCleanupLogs            FailureReason = "LOG_REMOVAL_FAILED"
	FailureCleanupSync            FailureReason = "QUOTA_SYNC_FAILED"
	FailureCleanupBarrier         FailureReason = "QUOTA_RECLAMATION_BARRIER_FAILED"
	FailureCleanupQuotaRead       FailureReason = "QUOTA_READ_FAILED"
	FailureCleanupQuotaReferences FailureReason = "QUOTA_REFERENCES_REMAIN"
	FailureCleanupJournal         FailureReason = "JOURNAL_COMPLETE_FAILED"
)

type LaunchSpec

type LaunchSpec struct {
	ModuleID         string         `json:"module_id"`
	InstanceID       string         `json:"instance_id"`
	ImageDigest      string         `json:"image_digest"`
	InitialEgress    EgressPolicy   `json:"initial_egress"`
	Entrypoint       []string       `json:"entrypoint"`
	Args             []string       `json:"args"`
	UID              uint32         `json:"uid"`
	GID              uint32         `json:"gid"`
	Resources        ResourceLimits `json:"resources"`
	ConfigRevision   string         `json:"config_revision"`
	ApprovalRevision string         `json:"approval_revision"`
}

type Lease

type Lease struct {
	Ownership         Ownership  `json:"ownership"`
	Spec              LaunchSpec `json:"spec"`
	PersistentPath    string     `json:"persistent_path"`
	ScratchPath       string     `json:"scratch_path"`
	IPCPath           string     `json:"ipc_path"`
	LogPath           string     `json:"log_path"`
	PersistentProject uint32     `json:"persistent_project"`
	ScratchProject    uint32     `json:"scratch_project"`
	SocketGID         uint32     `json:"socket_gid"`
}

type NetworkConfig

type NetworkConfig struct {
	Backend             string   `json:"backend"`
	IPTables            string   `json:"iptables"`
	IP6Tables           string   `json:"ip6tables"`
	IPTablesRestore     string   `json:"iptables_restore"`
	IP6TablesRestore    string   `json:"ip6tables_restore"`
	Conntrack           string   `json:"conntrack"`
	IPv4Pool            string   `json:"ipv4_pool"`
	IPv6Pool            string   `json:"ipv6_pool"`
	Resolvers           []string `json:"resolvers"`
	HostPublicAddresses []string `json:"host_public_addresses"`
	InternalPrefixes    []string `json:"internal_prefixes"`
	MetadataPrefixes    []string `json:"metadata_prefixes"`
	// Deployment inventory must explicitly include externally NAT-mapped host IPs.
	InventoryRevision string `json:"inventory_revision"`
}

type Ownership

type Ownership struct {
	InstallationID string `json:"installation_id"`
	EpochID        string `json:"epoch_id"`
	InstanceID     string `json:"instance_id"`
	ContainerID    string `json:"container_id"`
}

type Platform

type Platform interface {
	BindCreateJournal(CreateJournal) error
	Preflight(context.Context) error
	ImageManifest(context.Context, string, int64) ([]byte, error)
	Create(context.Context, LaunchSpec, Lease, []string, string) (*Container, error)
	Start(context.Context, Ownership) error
	Wait(context.Context, Ownership) (Exit, error)
	Terminate(context.Context, Ownership) error
	SetEgress(context.Context, Ownership, EgressPolicy) error
	Reconcile(context.Context, Ownership) error
}

Platform implementations must retain ownership after any uncertain remote outcome. Terminate/Reconcile prove all labeled resources absent before success. Create attaches bounded stdout/stderr before Start; returned files are owned by the caller. The final Create argument is the approved host socket directory.

type ResourceLimits

type ResourceLimits struct {
	NanoCPUs               int64 `json:"nano_cpus"`
	MemoryBytes            int64 `json:"memory_bytes"`
	Pids                   int64 `json:"pids"`
	PersistentBytes        int64 `json:"persistent_bytes"`
	ScratchBytes           int64 `json:"scratch_bytes"`
	PersistentInodes       int64 `json:"persistent_inodes"`
	ScratchInodes          int64 `json:"scratch_inodes"`
	ControlMessageMaxBytes int64 `json:"control_message_max_bytes"`
	LogBufferBytes         int64 `json:"log_buffer_bytes"`
	LogFileMaxBytes        int64 `json:"log_file_max_bytes"`
	LogRetainedFiles       int   `json:"log_retained_files"`
}

type RunnerFactory

type RunnerFactory struct {
	// contains filtered or unexported fields
}

NewRunnerFactory never executes cmd.Path. Only go-plugin's explicit bootstrap environment crosses the supervisor boundary; no host process environment does.

func NewRunnerFactory

func NewRunnerFactory(client *Client, lease Lease) *RunnerFactory

func (*RunnerFactory) CloseTransport

func (f *RunnerFactory) CloseTransport() error

CloseTransport MUST follow joining the primary Client()/Start attempt and Client.Kill, including its multiplex shutdown. Runner.Kill alone is too early.

func (*RunnerFactory) RunnerFunc

func (f *RunnerFactory) RunnerFunc(_ hclog.Logger, cmd *exec.Cmd, socketDir string) (runner.Runner, error)

type Supervisor

type Supervisor struct {
	// contains filtered or unexported fields
}

func NewSupervisor

func NewSupervisor(ctx context.Context, c SupervisorConfig, p Platform) (*Supervisor, error)

func (*Supervisor) Close

func (s *Supervisor) Close() error

func (*Supervisor) Serve

func (s *Supervisor) Serve(ctx context.Context) error

type SupervisorConfig

type SupervisorConfig struct {
	SocketPath          string        `json:"socket_path"`
	RuntimeUID          uint32        `json:"runtime_uid"`
	RuntimeGID          uint32        `json:"runtime_gid"`
	ManagementDirectory string        `json:"management_directory"`
	StorageRoot         string        `json:"storage_root"`
	IPCRoot             string        `json:"ipc_root"`
	MaxMessageBytes     int           `json:"max_message_bytes"`
	OperationTimeout    time.Duration `json:"operation_timeout"`
	ReconcileInterval   time.Duration `json:"reconcile_interval"`
	MaxConnections      int           `json:"max_connections"`
}

Jump to

Keyboard shortcuts

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