ipc

package
v0.0.2 Latest Latest
Warning

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

 Go to latest Published: Feb 10, 2026 License: GPL-3.0 Imports: 13 Imported by: 0

Documentation

Overview

Package ipc provides the inter-process communication protocol for the cc-helper out-of-process architecture. This allows the C bindings library (libcc) to communicate with codesigned helper processes that run VMs.

Index

Constants

View Source 
const (
	// Instance lifecycle (0x01xx)
	MsgInstanceNew        uint16 = 0x0100
	MsgInstanceClose      uint16 = 0x0101
	MsgInstanceWait       uint16 = 0x0102
	MsgInstanceID         uint16 = 0x0103
	MsgInstanceIsRunning  uint16 = 0x0104
	MsgInstanceSetConsole uint16 = 0x0105
	MsgInstanceSetNetwork uint16 = 0x0106
	MsgInstanceExec       uint16 = 0x0107

	// Filesystem operations (0x02xx)
	MsgFsOpen      uint16 = 0x0200
	MsgFsCreate    uint16 = 0x0201
	MsgFsOpenFile  uint16 = 0x0202
	MsgFsReadFile  uint16 = 0x0203
	MsgFsWriteFile uint16 = 0x0204
	MsgFsStat      uint16 = 0x0205
	MsgFsLstat     uint16 = 0x0206
	MsgFsRemove    uint16 = 0x0207
	MsgFsRemoveAll uint16 = 0x0208
	MsgFsMkdir     uint16 = 0x0209
	MsgFsMkdirAll  uint16 = 0x020A
	MsgFsRename    uint16 = 0x020B
	MsgFsSymlink   uint16 = 0x020C
	MsgFsReadlink  uint16 = 0x020D
	MsgFsReadDir   uint16 = 0x020E
	MsgFsChmod     uint16 = 0x020F
	MsgFsChown     uint16 = 0x0210
	MsgFsChtimes   uint16 = 0x0211
	MsgFsSnapshot  uint16 = 0x0212

	// File operations (0x03xx)
	MsgFileClose    uint16 = 0x0300
	MsgFileRead     uint16 = 0x0301
	MsgFileWrite    uint16 = 0x0302
	MsgFileSeek     uint16 = 0x0303
	MsgFileSync     uint16 = 0x0304
	MsgFileTruncate uint16 = 0x0305
	MsgFileStat     uint16 = 0x0306
	MsgFileName     uint16 = 0x0307

	// Command operations (0x04xx)
	MsgCmdNew            uint16 = 0x0400
	MsgCmdEntrypoint     uint16 = 0x0401
	MsgCmdFree           uint16 = 0x0402
	MsgCmdSetDir         uint16 = 0x0403
	MsgCmdSetEnv         uint16 = 0x0404
	MsgCmdGetEnv         uint16 = 0x0405
	MsgCmdEnviron        uint16 = 0x0406
	MsgCmdStart          uint16 = 0x0407
	MsgCmdWait           uint16 = 0x0408
	MsgCmdRun            uint16 = 0x0409
	MsgCmdOutput         uint16 = 0x040A
	MsgCmdCombinedOutput uint16 = 0x040B
	MsgCmdExitCode       uint16 = 0x040C
	MsgCmdKill           uint16 = 0x040D

	// Network operations (0x05xx)
	MsgNetListen      uint16 = 0x0500
	MsgListenerAccept uint16 = 0x0501
	MsgListenerClose  uint16 = 0x0502
	MsgListenerAddr   uint16 = 0x0503
	MsgConnRead       uint16 = 0x0504
	MsgConnWrite      uint16 = 0x0505
	MsgConnClose      uint16 = 0x0506
	MsgConnLocalAddr  uint16 = 0x0507
	MsgConnRemoteAddr uint16 = 0x0508

	// Snapshot operations (0x06xx)
	MsgSnapshotCacheKey uint16 = 0x0600
	MsgSnapshotParent   uint16 = 0x0601
	MsgSnapshotClose    uint16 = 0x0602
	MsgSnapshotAsSource uint16 = 0x0603

	// Dockerfile operations (0x07xx)
	MsgBuildDockerfile uint16 = 0x0700

	// Response types (0xFFxx)
	MsgResponse uint16 = 0xFF00
	MsgError    uint16 = 0xFF01
)

Message types for the IPC protocol. Organized by category with a prefix byte.

View Source 
const (
	ErrCodeOK                    = 0
	ErrCodeInvalidHandle         = 1
	ErrCodeInvalidArgument       = 2
	ErrCodeNotRunning            = 3
	ErrCodeAlreadyClosed         = 4
	ErrCodeTimeout               = 5
	ErrCodeHypervisorUnavailable = 6
	ErrCodeIO                    = 7
	ErrCodeNetwork               = 8
	ErrCodeCancelled             = 9
	ErrCodeUnknown               = 99
)

Error codes for IPC errors (matches C error codes).

View Source 
const HeaderSize = 6

HeaderSize is the size of the header in bytes.

Variables

This section is empty.

Functions

func EncodeDirEntry 

func EncodeDirEntry(enc *Encoder, de DirEntry)

EncodeDirEntry encodes a directory entry.

func EncodeDockerfileOptions 

func EncodeDockerfileOptions(enc *Encoder, opts DockerfileOptions)

EncodeDockerfileOptions encodes Dockerfile build options.

func EncodeError 

func EncodeError(enc *Encoder, code uint8, message, op, path string)

EncodeError encodes an error response.

func EncodeFileInfo 

func EncodeFileInfo(enc *Encoder, fi FileInfo)

EncodeFileInfo encodes file info.

func EncodeInstanceOptions 

func EncodeInstanceOptions(enc *Encoder, opts InstanceOptions)

EncodeInstanceOptions encodes instance options.

func EncodeMountConfig 

func EncodeMountConfig(enc *Encoder, mc MountConfig)

EncodeMountConfig encodes mount configuration.

func EncodeSnapshotOptions 

func EncodeSnapshotOptions(enc *Encoder, opts SnapshotOptions)

EncodeSnapshotOptions encodes snapshot options.

func ResetUseHelper 

func ResetUseHelper()

ResetUseHelper resets the cached UseHelper value. This is only for testing.

func SocketPath 

func SocketPath() string

SocketPath returns a platform-appropriate Unix domain socket path. On Windows, this produces a shorter path to stay within the 108-char sun_path limit.

func UseHelper 

func UseHelper() bool

UseHelper returns true if the IPC helper should be used for instance operations. By default: - macOS: true (codesigning required for hypervisor access) - Windows: true (Go c-archive crashes with hypervisor APIs in-process) - Other platforms: false (library can access hypervisor directly)

This can be overridden by environment variables: - CC_USE_HELPER=1 or CC_USE_HELPER=true: Force helper usage - CC_USE_HELPER=0 or CC_USE_HELPER=false: Force direct execution

func WriteHeader 

func WriteHeader(w io.Writer, h Header) error

WriteHeader writes a message header to the writer.

Types

type Client 

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

Client manages a connection to a cc-helper process.

func ConnectTo 

func ConnectTo(socketPath string) (*Client, error)

ConnectTo connects to an existing cc-helper process at the given socket path.

func SpawnHelper 

func SpawnHelper(libPath string) (*Client, error)

SpawnHelper starts a new cc-helper process and connects to it. libPath should be the path to libcc.so/.dylib for locating cc-helper.

func (*Client) Call 

func (c *Client) Call(msgType uint16, payload []byte) ([]byte, error)

Call sends a request and waits for a response. This is a synchronous RPC call.

func (*Client) CallWithEncoder 

func (c *Client) CallWithEncoder(msgType uint16, encode func(*Encoder)) ([]byte, error)

CallWithEncoder is a convenience method that uses an encoder for the request.

func (*Client) Close 

func (c *Client) Close() error

Close shuts down the client connection and helper process.

func (*Client) IsAlive 

func (c *Client) IsAlive() bool

IsAlive checks if the helper process is still running.

type Decoder 

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

Decoder reads IPC messages.

func NewDecoder 

func NewDecoder(buf []byte) *Decoder

NewDecoder creates a new decoder for the given bytes.

func (*Decoder) Bool 

func (d *Decoder) Bool() (bool, error)

Bool reads a bool (1 byte).

func (*Decoder) Bytes 

func (d *Decoder) Bytes() ([]byte, error)

Bytes reads a length-prefixed byte slice.

func (*Decoder) Int32 

func (d *Decoder) Int32() (int32, error)

Int32 reads an int32 (big endian).

func (*Decoder) Int64 

func (d *Decoder) Int64() (int64, error)

Int64 reads an int64 (big endian).

func (*Decoder) Remaining 

func (d *Decoder) Remaining() int

Remaining returns the number of unread bytes.

func (*Decoder) String 

func (d *Decoder) String() (string, error)

String reads a length-prefixed string.

func (*Decoder) StringSlice 

func (d *Decoder) StringSlice() ([]string, error)

StringSlice reads a string slice.

func (*Decoder) Uint8 

func (d *Decoder) Uint8() (uint8, error)

Uint8 reads a uint8.

func (*Decoder) Uint16 

func (d *Decoder) Uint16() (uint16, error)

Uint16 reads a uint16 (big endian).

func (*Decoder) Uint32 

func (d *Decoder) Uint32() (uint32, error)

Uint32 reads a uint32 (big endian).

func (*Decoder) Uint64 

func (d *Decoder) Uint64() (uint64, error)

Uint64 reads a uint64 (big endian).

type DirEntry 

type DirEntry struct {
	Name  string
	IsDir bool
	Mode  fs.FileMode
}

DirEntry holds directory entry data for IPC transfer.

func DecodeDirEntry 

func DecodeDirEntry(dec *Decoder) (DirEntry, error)

DecodeDirEntry decodes a directory entry.

type DockerfileOptions 

type DockerfileOptions struct {
	Dockerfile []byte            // Dockerfile content
	ContextDir string            // Directory for COPY/ADD (optional)
	CacheDir   string            // Cache directory (required)
	BuildArgs  map[string]string // Build arguments (optional)
}

DockerfileOptions holds Dockerfile build options for IPC transfer.

func DecodeDockerfileOptions 

func DecodeDockerfileOptions(dec *Decoder) (DockerfileOptions, error)

DecodeDockerfileOptions decodes Dockerfile build options.

type Encoder 

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

Encoder writes IPC messages.

func NewEncoder 

func NewEncoder() *Encoder

NewEncoder creates a new encoder.

func (*Encoder) Bool 

func (e *Encoder) Bool(v bool)

Bool appends a bool (1 byte).

func (*Encoder) Bytes 

func (e *Encoder) Bytes() []byte

Bytes returns the encoded bytes.

func (*Encoder) Int32 

func (e *Encoder) Int32(v int32)

Int32 appends an int32 (big endian).

func (*Encoder) Int64 

func (e *Encoder) Int64(v int64)

Int64 appends an int64 (big endian).

func (*Encoder) Reset 

func (e *Encoder) Reset()

Reset clears the buffer for reuse.

func (*Encoder) String 

func (e *Encoder) String(s string)

String appends a length-prefixed string (4 bytes length + data).

func (*Encoder) StringSlice 

func (e *Encoder) StringSlice(ss []string)

StringSlice appends a string slice (4 bytes count + strings).

func (*Encoder) Uint8 

func (e *Encoder) Uint8(v uint8)

Uint8 appends a uint8.

func (*Encoder) Uint16 

func (e *Encoder) Uint16(v uint16)

Uint16 appends a uint16 (big endian).

func (*Encoder) Uint32 

func (e *Encoder) Uint32(v uint32)

Uint32 appends a uint32 (big endian).

func (*Encoder) Uint64 

func (e *Encoder) Uint64(v uint64)

Uint64 appends a uint64 (big endian).

func (*Encoder) WriteBytes 

func (e *Encoder) WriteBytes(b []byte)

WriteBytes appends a length-prefixed byte slice (4 bytes length + data).

type FileInfo 

type FileInfo struct {
	Name      string
	Size      int64
	Mode      fs.FileMode
	ModTime   int64 // Unix timestamp
	IsDir     bool
	IsSymlink bool
}

FileInfo holds file metadata for IPC transfer.

func DecodeFileInfo 

func DecodeFileInfo(dec *Decoder) (FileInfo, error)

DecodeFileInfo decodes file info.

type Handler 

type Handler func(msgType uint16, payload []byte) ([]byte, error)

Handler is a function that handles a request and returns a response. 

type Header struct {
	Type   uint16
	Length uint32
}

Header represents a message header.

func ReadHeader 

func ReadHeader(r io.Reader) (Header, error)

ReadHeader reads a message header from the reader.

type HelperNotFoundError 

type HelperNotFoundError struct {
	SearchedPaths []string
}

HelperNotFoundError is returned when the cc-helper binary cannot be found.

func (*HelperNotFoundError) Error 

func (e *HelperNotFoundError) Error() string

type IPCError 

type IPCError struct {
	Code    uint8
	Message string
	Op      string
	Path    string
}

IPCError represents an error in the IPC protocol.

func DecodeError 

func DecodeError(dec *Decoder) (*IPCError, error)

DecodeError decodes an error response.

func (*IPCError) Error 

func (e *IPCError) Error() string

type InstanceOptions 

type InstanceOptions struct {
	MemoryMB    uint64
	CPUs        int
	TimeoutSecs float64
	User        string
	EnableDmesg bool
	Mounts      []MountConfig
}

InstanceOptions holds instance options for IPC transfer.

func DecodeInstanceOptions 

func DecodeInstanceOptions(dec *Decoder) (InstanceOptions, error)

DecodeInstanceOptions decodes instance options.

type MountConfig 

type MountConfig struct {
	Tag      string
	HostPath string
	Writable bool
}

MountConfig holds mount configuration for IPC transfer.

func DecodeMountConfig 

func DecodeMountConfig(dec *Decoder) (MountConfig, error)

DecodeMountConfig decodes mount configuration.

type Mux 

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

Mux is a message type multiplexer for the server.

func NewMux 

func NewMux() *Mux

NewMux creates a new message multiplexer.

func (*Mux) Handle 

func (m *Mux) Handle(msgType uint16, handler MuxHandler)

Handle registers a handler for a message type.

func (*Mux) Handler 

func (m *Mux) Handler() Handler

Handler returns a Handler function for use with Server.

type MuxHandler 

type MuxHandler func(dec *Decoder) ([]byte, error)

MuxHandler handles a specific message type.

type ResponseBuilder 

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

ResponseBuilder helps build response payloads.

func NewResponseBuilder 

func NewResponseBuilder() *ResponseBuilder

NewResponseBuilder creates a new response builder.

func (*ResponseBuilder) Bool 

func (r *ResponseBuilder) Bool(v bool) *ResponseBuilder

Bool appends a bool.

func (*ResponseBuilder) Build 

func (r *ResponseBuilder) Build() []byte

Build returns the encoded response bytes.

func (*ResponseBuilder) Bytes 

func (r *ResponseBuilder) Bytes(b []byte) *ResponseBuilder

Bytes appends bytes.

func (*ResponseBuilder) FileInfo 

func (r *ResponseBuilder) FileInfo(fi FileInfo) *ResponseBuilder

FileInfo appends file info.

func (*ResponseBuilder) Int32 

func (r *ResponseBuilder) Int32(v int32) *ResponseBuilder

Int32 appends an int32.

func (*ResponseBuilder) Int64 

func (r *ResponseBuilder) Int64(v int64) *ResponseBuilder

Int64 appends an int64.

func (*ResponseBuilder) String 

func (r *ResponseBuilder) String(s string) *ResponseBuilder

String appends a string.

func (*ResponseBuilder) Success 

func (r *ResponseBuilder) Success() *ResponseBuilder

Success marks the response as successful (error code 0).

func (*ResponseBuilder) Uint8 

func (r *ResponseBuilder) Uint8(v uint8) *ResponseBuilder

Uint8 appends a uint8.

func (*ResponseBuilder) Uint16 

func (r *ResponseBuilder) Uint16(v uint16) *ResponseBuilder

Uint16 appends a uint16.

func (*ResponseBuilder) Uint32 

func (r *ResponseBuilder) Uint32(v uint32) *ResponseBuilder

Uint32 appends a uint32.

func (*ResponseBuilder) Uint64 

func (r *ResponseBuilder) Uint64(v uint64) *ResponseBuilder

Uint64 appends a uint64.

type Server 

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

Server accepts connections from libcc clients.

func NewServer 

func NewServer(socketPath string, handler Handler) (*Server, error)

NewServer creates a new IPC server listening on the given Unix socket path.

func (*Server) Close 

func (s *Server) Close() error

Close shuts down the server.

func (*Server) Serve 

func (s *Server) Serve() error

Serve accepts connections and handles requests. This blocks until Close is called.

func (*Server) ServeOne 

func (s *Server) ServeOne() error

ServeOne accepts a single connection and handles requests on it. This is useful for the one-process-per-instance model. Returns when the connection is closed.

func (*Server) SocketPath 

func (s *Server) SocketPath() string

SocketPath returns the path to the Unix socket.

type SnapshotOptions 

type SnapshotOptions struct {
	Excludes []string
	CacheDir string
}

SnapshotOptions holds snapshot options for IPC transfer.

func DecodeSnapshotOptions 

func DecodeSnapshotOptions(dec *Decoder) (SnapshotOptions, error)

DecodeSnapshotOptions decodes snapshot options.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.