Documentation
¶
Overview ¶
Package host implements the trusted Linux supervisor boundary. No module configuration, backend secret, or caller-provided host path belongs here.
Index ¶
- Constants
- Variables
- type Client
- func (c *Client) Acquire(ctx context.Context, s LaunchSpec) (Lease, error)
- func (c *Client) CaptureSocket(ctx context.Context, id, name string) (*os.File, error)
- func (c *Client) Close() error
- func (c *Client) Create(ctx context.Context, id string, bootstrap []string, hostSocketDir string) (*Container, error)
- func (c *Client) EpochID() string
- func (c *Client) ImageManifest(ctx context.Context, digest string) ([]byte, error)
- func (c *Client) Reconcile(ctx context.Context) error
- func (c *Client) Release(ctx context.Context, id string) error
- func (c *Client) SetEgress(ctx context.Context, id string, p EgressPolicy) error
- func (c *Client) Start(ctx context.Context, id string) error
- func (c *Client) Terminate(ctx context.Context, id string) error
- func (c *Client) Timeout() time.Duration
- func (c *Client) Wait(ctx context.Context, id string) (Exit, error)
- type ClientConfig
- type Container
- type CreateJournal
- type CreateKind
- type CreateRecord
- type CreateState
- type DockerConfig
- type DockerPlatform
- func (p *DockerPlatform) BindCreateJournal(j CreateJournal) error
- func (p *DockerPlatform) Close() error
- func (p *DockerPlatform) Create(ctx context.Context, spec LaunchSpec, lease Lease, env []string, ...) (*Container, error)
- func (p *DockerPlatform) ImageManifest(ctx context.Context, digest string, maxBytes int64) ([]byte, error)
- func (p *DockerPlatform) Preflight(ctx context.Context) error
- func (p *DockerPlatform) Reconcile(ctx context.Context, o Ownership) error
- func (p *DockerPlatform) SetEgress(ctx context.Context, o Ownership, policy EgressPolicy) error
- func (p *DockerPlatform) Start(ctx context.Context, o Ownership) error
- func (p *DockerPlatform) Terminate(ctx context.Context, o Ownership) error
- func (p *DockerPlatform) Wait(ctx context.Context, o Ownership) (Exit, error)
- type EgressPolicy
- type Error
- type Exit
- type FailurePhase
- type FailureReason
- type LaunchSpec
- type Lease
- type NetworkConfig
- type Ownership
- type Platform
- type ResourceLimits
- type RunnerFactory
- type Supervisor
- type SupervisorConfig
Constants ¶
const GuestIPCPath = "/run/flexmodule/ipc"
const GuestPersistentPath = "/var/lib/flexmodule/data"
const GuestScratchPath = "/var/lib/flexmodule/scratch"
const ImageManifestLabel = "org.chatanium.flexmodule.manifest.v2"
Variables ¶
var ErrCleanupIncomplete = errors.New("host cleanup incomplete")
var ErrCreateAlreadySubmitted = errors.New("Docker create was already submitted")
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 (*Client) CaptureSocket ¶
func (*Client) ImageManifest ¶
ImageManifest retrieves only the declaration from one exact local image. It is untrusted requirements data, never an approval or published grant.
type ClientConfig ¶
type CreateJournal ¶
type CreateJournal interface {
SubmitCreate(context.Context, Ownership, CreateKind, string) error
ObserveCreated(context.Context, Ownership, CreateKind, string, string) error
RejectCreate(context.Context, Ownership, CreateKind, string, string) error
LookupCreate(context.Context, Ownership, CreateKind) (CreateRecord, bool, error)
RecordFailure(context.Context, Ownership, FailurePhase, FailureReason) error
}
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 (*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
type EgressPolicy ¶
type EgressPolicy string
const ( EgressNone EgressPolicy = "NONE" EgressPublicInternet EgressPolicy = "PUBLIC_INTERNET" )
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 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.
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
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"`
}