client

Documentation

Index

• Variables
• func ListOfflineImages() ([]string, error)
• func ValidateMounts(mounts []Mount) error
• func ValidateNetworkConfig(cfg *NetworkConfig) error
• type Box
  • func (b *Box) Close()
  • func (b *Box) Exec(command string, opts *ExecOptions) (*ExecResult, error)
  • func (b *Box) ExecStream(command string, opts *ExecOptions, cb ExecStreamCallbacks) (*ExecResult, error)
  • func (b *Box) ID() string
  • func (b *Box) Info() (BoxInfo, error)
  • func (b *Box) Name() string
  • func (b *Box) Start() error
  • func (b *Box) Stop() error
• type BoxInfo
• type BoxOptions
• type CIDRRule
• type DNSConfig
• type DomainRule
• type ExecOptions
• type ExecResult
• type ExecStreamCallbacks
• type Mount
• type NetworkConfig
  • func BalancedNetworkProfile() *NetworkConfig
  • func OpenNetworkProfile() *NetworkConfig
  • func StrictNetworkProfile() *NetworkConfig
• type NetworkMode
• type NetworkPolicy
• type OfflineImageMetadata
  • func ListOfflineImageMetadata() ([]OfflineImageMetadata, error)
• type PolicyMode
• type PortForward
• type Protocol
• type ProxyConfig
• type Runtime
  • func NewRuntime(opts *RuntimeOptions) (*Runtime, error)
  • func (r *Runtime) Close()
  • func (r *Runtime) CreateBox(ctx context.Context, name string, opts BoxOptions) (*Box, error)
  • func (r *Runtime) GetBox(ctx context.Context, idOrName string) (*Box, error)
  • func (r *Runtime) ListBoxes(ctx context.Context) ([]BoxInfo, error)
  • func (r *Runtime) RemoveBox(ctx context.Context, idOrName string, force bool) error
• type RuntimeNetworkDefaults
• type RuntimeOptions
• type TrafficLimits

Variables

var (
	ErrNetworkUnsupportedPlatform = errors.New("network unsupported on this platform")
	ErrNetworkInvalidConfig       = errors.New("invalid network config")
)

var ErrMountInvalidConfig = errors.New("invalid mount config")

var (
	// ErrNativeUnavailable means govm is running with the non-native stub binding.
	ErrNativeUnavailable = errors.New("govm native bridge unavailable: rebuild with -tags govm_native and bundled native libs")
)

Functions

func ListOfflineImages

func ListOfflineImages() ([]string, error)

ListOfflineImages returns embedded offline image names.

func ValidateMounts

func ValidateMounts(mounts []Mount) error

func ValidateNetworkConfig

func ValidateNetworkConfig(cfg *NetworkConfig) error

Types

type Box

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

Box is a handle to one sandbox VM.

func (*Box) Close

func (b *Box) Close()

Close only frees the handle; it does not remove the underlying box.

func (*Box) Exec

func (b *Box) Exec(command string, opts *ExecOptions) (*ExecResult, error)

func (*Box) ExecStream

func (b *Box) ExecStream(command string, opts *ExecOptions, cb ExecStreamCallbacks) (*ExecResult, error)

func (*Box) ID

func (b *Box) ID() string

func (*Box) Info

func (b *Box) Info() (BoxInfo, error)

func (*Box) Name

func (b *Box) Name() string

func (*Box) Start

func (b *Box) Start() error

func (*Box) Stop

func (b *Box) Stop() error

type BoxInfo

type BoxInfo struct {
	ID        string    `json:"id"`
	Name      string    `json:"name,omitempty"`
	Image     string    `json:"image"`
	State     string    `json:"state"`
	CreatedAt time.Time `json:"created_at"`
}

BoxInfo contains metadata and state of a box.

type BoxOptions

type BoxOptions struct {
	Image string `json:"image"`
	// LocalBundlePath points to a local OCI image layout directory.
	// When set, it takes precedence over Image.
	LocalBundlePath string `json:"local_bundle_path,omitempty"`
	// RootfsPath is kept for backward compatibility and aliases LocalBundlePath.
	// Deprecated: use LocalBundlePath.
	RootfsPath string `json:"rootfs_path,omitempty"`
	// OfflineImage references an embedded offline image bundle shipped in this repo.
	// Runtime.CreateBox will extract it and fill RootfsPath automatically.
	OfflineImage string            `json:"offline_image,omitempty"`
	CPUs         int               `json:"cpus,omitempty"`
	MemoryMB     int               `json:"memory_mb,omitempty"`
	Env          map[string]string `json:"env,omitempty"`
	WorkingDir   string            `json:"working_dir,omitempty"`
	Mounts       []Mount           `json:"mounts,omitempty"`
	Network      *NetworkConfig    `json:"network,omitempty"`
}

BoxOptions configures a new box.

type CIDRRule

type CIDRRule struct {
	CIDR      string   `json:"cidr"`
	Protocol  Protocol `json:"protocol,omitempty"`
	PortStart uint16   `json:"port_start,omitempty"`
	PortEnd   uint16   `json:"port_end,omitempty"`
}

type DNSConfig

type DNSConfig struct {
	Servers       []string `json:"servers,omitempty"`
	SearchDomains []string `json:"search_domains,omitempty"`
	BlockPrivate  bool     `json:"block_private,omitempty"`
}

type DomainRule

type DomainRule struct {
	Domain   string   `json:"domain"`
	Port     uint16   `json:"port,omitempty"`
	Protocol Protocol `json:"protocol,omitempty"`
}

type ExecOptions

type ExecOptions struct {
	Args       []string
	Env        map[string]string
	TTY        bool
	User       string
	Timeout    time.Duration
	WorkingDir string
}

ExecOptions controls execution behavior for a command.

type ExecResult

type ExecResult struct {
	ExitCode int
	Stdout   []string
	Stderr   []string
}

ExecResult is the final result of command execution.

type ExecStreamCallbacks

type ExecStreamCallbacks struct {
	OnStdout func(string)
	OnStderr func(string)
}

ExecStreamCallbacks receives incremental stdout/stderr from guest command execution.

type Mount

type Mount struct {
	HostPath  string `json:"host_path,omitempty"`
	GuestPath string `json:"guest_path,omitempty"`
	ReadOnly  bool   `json:"read_only,omitempty"`
}

type NetworkConfig

type NetworkConfig struct {
	Enabled            bool           `json:"enabled"`
	Mode               NetworkMode    `json:"mode,omitempty"`
	Policy             *NetworkPolicy `json:"policy,omitempty"`
	PortForwards       []PortForward  `json:"port_forwards,omitempty"`
	IsolateFromHostLAN bool           `json:"isolate_from_host_lan,omitempty"`
}

func BalancedNetworkProfile

func BalancedNetworkProfile() *NetworkConfig

func OpenNetworkProfile

func OpenNetworkProfile() *NetworkConfig

func StrictNetworkProfile

func StrictNetworkProfile() *NetworkConfig

type NetworkMode

type NetworkMode string

const (
	NetworkDisabled NetworkMode = "disabled"
	NetworkNAT      NetworkMode = "nat"
	NetworkBridged  NetworkMode = "bridged"
)

type NetworkPolicy

type NetworkPolicy struct {
	Mode        PolicyMode     `json:"mode,omitempty"`
	AllowCIDR   []CIDRRule     `json:"allow_cidr,omitempty"`
	DenyCIDR    []CIDRRule     `json:"deny_cidr,omitempty"`
	AllowDomain []DomainRule   `json:"allow_domain,omitempty"`
	DenyDomain  []DomainRule   `json:"deny_domain,omitempty"`
	DNS         *DNSConfig     `json:"dns,omitempty"`
	Proxy       *ProxyConfig   `json:"proxy,omitempty"`
	Limits      *TrafficLimits `json:"limits,omitempty"`
}

type OfflineImageMetadata

type OfflineImageMetadata struct {
	Name      string
	Archive   string
	SHA256    string
	SizeBytes int64
}

func ListOfflineImageMetadata

func ListOfflineImageMetadata() ([]OfflineImageMetadata, error)

ListOfflineImageMetadata returns metadata for embedded offline image bundles.

type PolicyMode

type PolicyMode string

const (
	PolicyBlockAll PolicyMode = "block_all"
	PolicyAllowAll PolicyMode = "allow_all"
)

type PortForward

type PortForward struct {
	HostIP    string   `json:"host_ip,omitempty"`
	HostPort  uint16   `json:"host_port"`
	GuestPort uint16   `json:"guest_port"`
	Protocol  Protocol `json:"protocol,omitempty"`
}

type Protocol

type Protocol string

const (
	ProtoTCP Protocol = "tcp"
	ProtoUDP Protocol = "udp"
	ProtoAny Protocol = "any"
)

type ProxyConfig

type ProxyConfig struct {
	HTTPProxy  string   `json:"http_proxy,omitempty"`
	HTTPSProxy string   `json:"https_proxy,omitempty"`
	NoProxy    []string `json:"no_proxy,omitempty"`
	Enforce    bool     `json:"enforce,omitempty"`
}

type Runtime

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

Runtime is the high-level client entry point.

func NewRuntime

func NewRuntime(opts *RuntimeOptions) (*Runtime, error)

NewRuntime creates a new runtime.

func (*Runtime) Close

func (r *Runtime) Close()

Close releases runtime resources.

func (*Runtime) CreateBox

func (r *Runtime) CreateBox(ctx context.Context, name string, opts BoxOptions) (*Box, error)

CreateBox creates and returns a box handle.

func (*Runtime) GetBox

func (r *Runtime) GetBox(ctx context.Context, idOrName string) (*Box, error)

GetBox returns nil,nil when the box does not exist.

func (*Runtime) ListBoxes

func (r *Runtime) ListBoxes(ctx context.Context) ([]BoxInfo, error)

ListBoxes returns all boxes in this runtime.

func (*Runtime) RemoveBox

func (r *Runtime) RemoveBox(ctx context.Context, idOrName string, force bool) error

RemoveBox removes a box by id or name.

type RuntimeNetworkDefaults

type RuntimeNetworkDefaults struct {
	Profile string         `json:"profile,omitempty"`
	Config  *NetworkConfig `json:"config,omitempty"`
}

type RuntimeOptions

type RuntimeOptions struct {
	HomeDir         string
	ImageRegistries []string
	NetworkDefaults *RuntimeNetworkDefaults
}

RuntimeOptions configures Runtime creation.

type TrafficLimits

type TrafficLimits struct {
	MaxEgressBytesPerSec  int64 `json:"max_egress_bps,omitempty"`
	MaxIngressBytesPerSec int64 `json:"max_ingress_bps,omitempty"`
	MaxConnections        int   `json:"max_connections,omitempty"`
}