api

package
v0.51.0 Latest Latest
Warning

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

 Go to latest Published: Jun 30, 2026 License: Apache-2.0 Imports: 11 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Listen 

func Listen(endpoint string) (net.Listener, error)

Listen binds a net.Listener for the given endpoint, clearing a stale Unix socket file first. Used by the server to accept connections.

func NewFrameReader 

func NewFrameReader(r io.Reader) *frameReader

func NewFrameWriter 

func NewFrameWriter(w io.Writer) *frameWriter

Types

type AuthParams 

type AuthParams struct {
	Token string `json:"token"`
}

AuthParams is the payload of the Auth.Hello handshake. When the daemon is configured with a token, the first request on every connection must be Auth.Hello carrying the matching token before any other method is accepted.

type BuildParams 

type BuildParams struct {
	Name string `json:"name"`
	Tag  string `json:"tag,omitempty"`
	// Program is the guest path (within the context tar) of the main ELF
	// binary. All other tar entries are treated as additional image files.
	Program string `json:"program"`
	// ProgramPath, when set, is the in-image guest path at which the program is
	// placed and executed (e.g. "usr/local/postgresql/bin/postgres"). Empty runs
	// the program flat at /program. Used by lang="raw" builds so binaries
	// resolve their installation prefix and $ORIGIN-relative libraries.
	ProgramPath string            `json:"program_path,omitempty"`
	Memory      string            `json:"memory,omitempty"`
	CPUs        int               `json:"cpus,omitempty"`
	Entrypoint  string            `json:"entrypoint,omitempty"`
	Args        []string          `json:"args,omitempty"`
	Env         map[string]string `json:"env,omitempty"`
	Port        int               `json:"port,omitempty"`
	// Ports holds default host:guest port-publish specs (from [run] ports in
	// unikernel.toml), baked into the image manifest for run-time inheritance.
	Ports []string `json:"ports,omitempty"`
	// DiskSize sets the minimum image size passed to mkfs (e.g. "512M", "1G").
	// Use when the default content-based size leaves insufficient free space
	// for runtime writes (e.g. database temp tablespaces, log files).
	DiskSize string `json:"disk_size,omitempty"`
}

BuildParams are the parameters for Image.Build. Immediately after sending this request the client streams the build context — a tar archive of the program binary plus any package/source files — as length-prefixed frames terminated by a zero-length frame. The daemon unpacks it into its own Linux filesystem, runs mkfs there, and stores the resulting image in its store.

type Client 

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

Client connects to a jerboad server over a Unix socket or TCP.

func Dial 

func Dial(endpoint string) (*Client, error)

Dial connects to the jerboad server at endpoint. The endpoint may carry a scheme (unix:// or tcp://); a bare value is treated as a Unix socket path. The auth token is read from the JERBOA_AUTH_TOKEN environment variable.

func DialWithToken 

func DialWithToken(endpoint, token string) (*Client, error)

DialWithToken connects like Dial and, when token is non-empty, performs the Auth.Hello handshake before returning. The same token is reused for any secondary connection the client opens (e.g. ImageBuild).

func (*Client) Attach 

func (c *Client) Attach(_ context.Context, id string, out io.Writer) error

Attach connects to a VM's serial console and streams output to stdout. It blocks until the VM stops or the connection is closed. This method takes over the connection for raw reading; do not use the client for other calls after Attach.

func (*Client) Close 

func (c *Client) Close() error

Close closes the underlying connection.

func (*Client) DNSList 

func (c *Client) DNSList(_ context.Context, network string) ([]DNSRecord, error)

DNSList lists resolvable VM records, optionally filtered by network.

func (*Client) DNSResolve 

func (c *Client) DNSResolve(_ context.Context, name, network string) (DNSRecord, error)

DNSResolve resolves a VM name to an IP address inside an optional network.

func (*Client) DNSResolveAll 

func (c *Client) DNSResolveAll(_ context.Context, name, network string) ([]DNSRecord, error)

DNSResolveAll resolves all DNS records matching a name (round-robin).

func (*Client) DaemonVersion 

func (c *Client) DaemonVersion(_ context.Context) (string, error)

DaemonVersion returns the version string reported by the running daemon.

func (*Client) Get 

func (c *Client) Get(_ context.Context, id string) (VMInfo, error)

Get returns the VM with the given id.

func (*Client) ImageBuild 

func (c *Client) ImageBuild(_ context.Context, p BuildParams, contextTar io.Reader) (ImageManifestResult, error)

ImageBuild sends an Image.Build request and streams the build context to the daemon, which assembles the disk image with mkfs on its own filesystem and stores it. contextTar is an uncompressed tar archive containing the program binary (at p.Program) plus any package or source files.

Build uses a dedicated connection (the daemon consumes the streamed context and closes that connection), leaving the client's persistent connection free for concurrent calls.

func (*Client) ImageGet 

func (c *Client) ImageGet(_ context.Context, ref string) (ImageManifestResult, error)

ImageGet returns the manifest for a single name:tag (or sha) reference.

func (*Client) ImageList 

func (c *Client) ImageList(_ context.Context) ([]ImageManifestResult, error)

ImageList returns the images held in the daemon's store.

func (*Client) ImageRemove 

func (c *Client) ImageRemove(_ context.Context, ref string) error

ImageRemove deletes a name:tag (or sha) reference from the daemon's store.

func (*Client) Inspect 

func (c *Client) Inspect(_ context.Context, id string) (VMDetail, error)

Inspect returns full details for the VM.

func (*Client) Kill 

func (c *Client) Kill(_ context.Context, id string) error

Kill sends an immediate SIGKILL to the VM.

func (*Client) List 

func (c *Client) List(_ context.Context) ([]VMInfo, error)

List returns all VMs known to the daemon.

func (*Client) Logs 

func (c *Client) Logs(_ context.Context, id string) (LogsResponse, error)

Logs returns captured serial console output for the VM.

func (*Client) NetworkAllocateIP 

func (c *Client) NetworkAllocateIP(_ context.Context, networkName string) (string, error)

NetworkAllocateIP allocates an IP address from the network's subnet.

func (*Client) NetworkCreate 

func (c *Client) NetworkCreate(_ context.Context, name, subnet, driver string) (NetworkInfo, error)

NetworkCreate creates a new network.

func (*Client) NetworkGet 

func (c *Client) NetworkGet(_ context.Context, name string) (NetworkInfo, error)

NetworkGet returns a single network by name.

func (*Client) NetworkList 

func (c *Client) NetworkList(_ context.Context) ([]NetworkInfo, error)

NetworkList returns all networks.

func (*Client) NetworkReleaseIP 

func (c *Client) NetworkReleaseIP(_ context.Context, networkName, ip string) error

NetworkReleaseIP releases an allocated IP address back to the network.

func (*Client) NetworkRemove 

func (c *Client) NetworkRemove(_ context.Context, name string) error

NetworkRemove deletes a network by name.

func (*Client) NodeList 

func (c *Client) NodeList(_ context.Context) (NodeListResponse, error)

NodeList returns cluster member information.

func (*Client) Remove 

func (c *Client) Remove(_ context.Context, id string) error

Remove removes the VM with the given id.

func (*Client) Run 

func (c *Client) Run(_ context.Context, p RunParams) (VMInfo, error)

Run creates and starts a VM, returning its info.

func (*Client) ServiceGet 

func (c *Client) ServiceGet(_ context.Context, name string) (ServiceInfoResult, error)

ServiceGet returns a single service by name.

func (*Client) ServiceList 

func (c *Client) ServiceList(_ context.Context) ([]ServiceInfoResult, error)

ServiceList returns all services.

func (*Client) ServiceRemove 

func (c *Client) ServiceRemove(_ context.Context, name string) error

ServiceRemove stops all replicas of a service and deletes it.

func (*Client) ServiceRun 

func (c *Client) ServiceRun(_ context.Context, p ServiceRunParams) (ServiceInfoResult, error)

ServiceRun creates and starts a service with the given parameters.

func (*Client) ServiceScale 

func (c *Client) ServiceScale(_ context.Context, name string, desiredReplicas int) (ServiceInfoResult, error)

ServiceScale adjusts the number of replicas for a service.

func (*Client) ServiceUpdate 

func (c *Client) ServiceUpdate(_ context.Context, name, image string, healthTimeout int) (ServiceInfoResult, error)

ServiceUpdate performs a rolling update of a service to a new image. healthTimeout is the maximum seconds to wait for new replicas to become healthy before removing old ones. Zero means no waiting.

func (*Client) Shutdown 

func (c *Client) Shutdown(_ context.Context) error

Shutdown asks the daemon to exit cleanly.

func (*Client) Signal 

func (c *Client) Signal(_ context.Context, id, sig string) error

Signal sends the named signal to the VM process.

func (*Client) Stats 

func (c *Client) Stats(_ context.Context, id string) (VMStatsResponse, error)

Stats returns runtime resource usage for the VM.

func (*Client) Stop 

func (c *Client) Stop(_ context.Context, id string, force bool) error

Stop sends a graceful stop request. Set force=true for immediate SIGKILL.

type DNSRecord 

type DNSRecord struct {
	Name    string `json:"name"`
	Network string `json:"network"`
	IP      string `json:"ip"`
	VMID    string `json:"vm_id"`
}

DNSRecord is the serialisable representation of an internal DNS record.

type DNSResolveParams 

type DNSResolveParams struct {
	Name    string `json:"name"`
	Network string `json:"network,omitempty"`
}

DNSResolveParams are the parameters for DNS.Resolve.

type HealthCheckSpec 

type HealthCheckSpec struct {
	Type     string `json:"type"`
	Port     int    `json:"port,omitempty"`
	Path     string `json:"path,omitempty"`
	Interval int    `json:"interval_seconds,omitempty"`
	Timeout  int    `json:"timeout_seconds,omitempty"`
	Retries  int    `json:"retries,omitempty"`
}

HealthCheckSpec is the wire representation of a health check configuration.

type IDParams 

type IDParams struct {
	ID string `json:"id"`
}

IDParams carries a single VM identifier.

type ImageManifestResult 

type ImageManifestResult struct {
	Name       string `json:"name"`
	Tag        string `json:"tag"`
	DiskDigest string `json:"disk_digest"`
	DiskSize   int64  `json:"disk_size"`
	Created    string `json:"created"`
}

ImageManifestResult is the wire representation of a built image manifest.

type LogsResponse 

type LogsResponse struct {
	ID   string `json:"id"`
	Logs string `json:"logs"`
}

LogsResponse carries the captured serial console output for a VM.

type NetworkConnectParams 

type NetworkConnectParams struct {
	Network string `json:"network"`
	VMID    string `json:"vm_id"`
	IP      string `json:"ip,omitempty"`
}

NetworkConnectParams connects a VM to a network.

type NetworkCreateParams 

type NetworkCreateParams struct {
	Name   string `json:"name"`
	Subnet string `json:"subnet,omitempty"`
	Driver string `json:"driver,omitempty"`
}

NetworkCreateParams are the parameters for Network.Create.

type NetworkInfo 

type NetworkInfo struct {
	Name      string `json:"name"`
	Driver    string `json:"driver"`
	Subnet    string `json:"subnet"`
	Gateway   string `json:"gateway"`
	Bridge    string `json:"bridge"`
	CreatedAt string `json:"created_at"`
}

NetworkInfo is the serialisable representation of a network.

type NodeListResponse 

type NodeListResponse struct {
	Nodes []NodeRow `json:"nodes"`
}

NodeListResponse carries cluster member information.

type NodeRow 

type NodeRow struct {
	ID       string `json:"id"`
	Addr     string `json:"addr"`
	Status   string `json:"status"`
	VMCount  int    `json:"vm_count"`
	CPUCap   int    `json:"cpu_capacity"`
	MemCap   int64  `json:"mem_capacity_bytes"`
	LastSeen string `json:"last_seen"`
}

NodeRow is the wire representation of a cluster member.

type PortMapSpec 

type PortMapSpec struct {
	HostPort  uint16 `json:"host_port"`
	GuestPort uint16 `json:"guest_port"`
	Protocol  string `json:"protocol"`
}

PortMapSpec is the wire representation of a host-to-guest port mapping.

func ParsePortMap 

func ParsePortMap(s string) (PortMapSpec, error)

ParsePortMap parses a single "host:guest[/tcp|udp]" port spec. The protocol defaults to tcp.

func ParsePortMaps 

func ParsePortMaps(specs []string) ([]PortMapSpec, error)

ParsePortMaps parses a list of "host:guest[/tcp|udp]" specs into wire port maps. It is a client-side helper so the CLI can build RunParams without importing the daemon's vm package.

type RPCError 

type RPCError struct {
	Code    int    `json:"code"`
	Message string `json:"message"`
}

RPCError carries a JSON-RPC error code and message.

type Request 

type Request struct {
	JSONRPC string          `json:"jsonrpc"`
	ID      int64           `json:"id"`
	Method  string          `json:"method"`
	Params  json.RawMessage `json:"params,omitempty"`
}

Request is a JSON-RPC 2.0 request envelope.

type Response 

type Response struct {
	JSONRPC string          `json:"jsonrpc"`
	ID      int64           `json:"id"`
	Result  json.RawMessage `json:"result,omitempty"`
	Error   *RPCError       `json:"error,omitempty"`
}

Response is a JSON-RPC 2.0 response envelope.

type RestartSpec 

type RestartSpec struct {
	Policy     string `json:"policy"`
	MaxRetries int    `json:"max_retries,omitempty"`
}

RestartSpec is the wire representation of a restart policy.

type RunParams 

type RunParams struct {
	// Image is a name:tag (or sha) reference resolved against the daemon's
	// image store. When set it takes precedence over ImagePath.
	Image string `json:"image,omitempty"`
	// ImagePath is a direct path to a bootable disk image on the daemon's
	// filesystem. Used for file-based runs when Image is empty.
	ImagePath   string            `json:"image_path"`
	Memory      string            `json:"memory"`
	CPUs        int               `json:"cpus"`
	NetworkName string            `json:"network_name,omitempty"`
	PortMaps    []PortMapSpec     `json:"port_maps,omitempty"`
	Env         []string          `json:"env,omitempty"`
	Name        string            `json:"name,omitempty"`
	AutoRemove  bool              `json:"auto_remove,omitempty"`
	Volumes     []VolumeMountSpec `json:"volumes,omitempty"`
	Attach      bool              `json:"attach,omitempty"`
	IPAddress   string            `json:"ip_address,omitempty"`
	GatewayIP   string            `json:"gateway_ip,omitempty"`
	BridgeName  string            `json:"bridge_name,omitempty"`
	SubnetMask  string            `json:"subnet_mask,omitempty"`
	HealthCheck *HealthCheckSpec  `json:"health_check,omitempty"`
	Restart     *RestartSpec      `json:"restart,omitempty"`
	CPUShares   uint64            `json:"cpu_shares,omitempty"`
	MemoryMax   int64             `json:"memory_max,omitempty"`
	DiskIOPS    uint64            `json:"disk_iops,omitempty"`
	DiskBPS     int64             `json:"disk_bps,omitempty"`
}

RunParams are the parameters for the VM.Run method.

type ServiceInfoResult 

type ServiceInfoResult struct {
	Name            string   `json:"name"`
	Image           string   `json:"image"`
	DesiredReplicas int      `json:"desired_replicas"`
	ReadyReplicas   int      `json:"ready_replicas"`
	Strategy        string   `json:"strategy"`
	Health          string   `json:"health"`
	Env             []string `json:"env,omitempty"`
	CreatedAt       string   `json:"created_at"`
	UpdatedAt       string   `json:"updated_at"`
	ReplicaIDs      []string `json:"replica_ids"`
}

ServiceInfoResult is the result for Service.Get and Service.List.

type ServiceRunParams 

type ServiceRunParams struct {
	Name          string           `json:"name"`
	Image         string           `json:"image"`
	Replicas      int              `json:"replicas"`
	Memory        string           `json:"memory,omitempty"`
	CPUs          int              `json:"cpus,omitempty"`
	Env           []string         `json:"env,omitempty"`
	NetworkName   string           `json:"network_name,omitempty"`
	PortMaps      []PortMapSpec    `json:"port_maps,omitempty"`
	HealthCheck   *HealthCheckSpec `json:"health_check,omitempty"`
	Restart       *RestartSpec     `json:"restart,omitempty"`
	Strategy      string           `json:"strategy,omitempty"`
	HealthTimeout int              `json:"health_timeout,omitempty"`
}

ServiceRunParams are the parameters for Service.Run.

type ServiceScaleParams 

type ServiceScaleParams struct {
	Name            string `json:"name"`
	DesiredReplicas int    `json:"desired_replicas"`
}

ServiceScaleParams are the parameters for Service.Scale.

type ServiceUpdateParams 

type ServiceUpdateParams struct {
	Name          string `json:"name"`
	Image         string `json:"image"`
	HealthTimeout int    `json:"health_timeout,omitempty"`
}

ServiceUpdateParams are the parameters for Service.Update (rolling update).

type SignalParams 

type SignalParams struct {
	// ID is the VM identifier.
	ID string `json:"id"`
	// Signal is the signal name (e.g. "SIGTERM") or number string (e.g. "15").
	Signal string `json:"signal"`
}

SignalParams are the parameters for VM.Signal.

type StopParams 

type StopParams struct {
	// ID is the VM identifier.
	ID string `json:"id"`
	// Force skips graceful shutdown and sends SIGKILL immediately.
	Force bool `json:"force,omitempty"`
}

StopParams are the parameters for VM.Stop.

type VMDetail 

type VMDetail struct {
	ID              string            `json:"id"`
	State           string            `json:"state"`
	Image           string            `json:"image"`
	Name            string            `json:"name,omitempty"`
	Memory          string            `json:"memory"`
	CPUs            int               `json:"cpus"`
	Ports           []PortMapSpec     `json:"ports,omitempty"`
	Env             []string          `json:"env,omitempty"`
	Volumes         []VolumeMountSpec `json:"volumes,omitempty"`
	IPAddress       string            `json:"ip_address,omitempty"`
	GatewayIP       string            `json:"gateway_ip,omitempty"`
	CreatedAt       string            `json:"created_at"`
	StartedAt       *string           `json:"started_at,omitempty"`
	StoppedAt       *string           `json:"stopped_at,omitempty"`
	DaemonRecovered bool              `json:"daemon_recovered,omitempty"`
	Health          string            `json:"health,omitempty"`
	RestartCount    int               `json:"restart_count,omitempty"`
	RestartPolicy   string            `json:"restart_policy,omitempty"`
	DiskIOPS        uint64            `json:"disk_iops,omitempty"`
	DiskBPS         int64             `json:"disk_bps,omitempty"`
}

VMDetail is the full serialisable representation of a VM.

type VMInfo 

type VMInfo struct {
	ID     string `json:"id"`
	State  string `json:"state"`
	Image  string `json:"image"`
	Name   string `json:"name,omitempty"`
	Health string `json:"health,omitempty"`
}

VMInfo is the compact serialisable representation of a VM.

type VMStatsResponse 

type VMStatsResponse struct {
	ID         string  `json:"id"`
	State      string  `json:"state"`
	CPUPct     float64 `json:"cpu_pct"`
	MemBytes   int64   `json:"mem_bytes"`
	DiskBytes  int64   `json:"disk_bytes,omitempty"`
	NetRxBytes int64   `json:"net_rx_bytes"`
	NetTxBytes int64   `json:"net_tx_bytes"`
	Timestamp  string  `json:"timestamp"`
	Source     string  `json:"source"`
}

VMStatsResponse carries runtime resource usage for a VM.

type VolumeMountSpec 

type VolumeMountSpec struct {
	DiskPath  string `json:"disk_path"`
	GuestPath string `json:"guest_path"`
	ReadOnly  bool   `json:"read_only,omitempty"`
	// Label is the volume's TFS filesystem label (its name). The daemon formats
	// the volume with this label and injects "Label:GuestPath" into the guest's
	// mount config (QEMU fw_cfg opt/uni/mounts or Firecracker boot args) so the
	// kernel mounts the matching volume at GuestPath.
	Label string `json:"label,omitempty"`
}

VolumeMountSpec is the wire representation of a volume mount.

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.