Help us shape the future of Go! Take the 2026 Go Developer Survey

api

package
v0.6.0 Latest Latest
Warning

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

 Go to latest Published: Oct 26, 2026 License: BSD-3-Clause Imports: 13 Imported by: 0

Documentation

Overview

Package api is the engine's API, compatible with a subset of the Docker Engine API (v1.47): what wctrd serves on a unix socket, and the client wctr speaks it with. Shapes follow the v1.47 OpenAPI document (see docs/REFERENCES.md); only the fields the engine fills are present.

The client side (types, Client, stdcopy) imports neither the daemon nor wazero, so the wctr command builds for wasip1.

Index

Constants

View Source 
const (
	StreamStdin  byte = 0
	StreamStdout byte = 1
	StreamStderr byte = 2
)

Stream types of the multiplexed stream.

View Source 
const (
	APIVersion    = "1.47"
	MinAPIVersion = "1.24"
)

APIVersion is the version the server speaks; MinAPIVersion the oldest it accepts in a /vX.Y prefix.

View Source 
const DefaultSocket = "/var/run/wctr.sock"

DefaultSocket is where wctrd listens and wctr connects when neither -H nor WCTR_HOST says otherwise.

View Source 
const HostEnv = "WCTR_HOST"

HostEnv names the environment variable that overrides the daemon host.

Variables

View Source 
var ErrBadFrame = errors.New("malformed multiplexed stream")

ErrBadFrame is returned for a malformed multiplexed stream.

Functions

func DefaultHost 

func DefaultHost() string

DefaultHost is $WCTR_HOST if set, else unix:// + DefaultSocket.

func Demux 

func Demux(stdout, stderr io.Writer, r io.Reader) error

Demux copies a multiplexed stream to stdout and stderr (stdin frames, type 0, go to stdout as the format says), until EOF.

func IsNotFound 

func IsNotFound(err error) bool

IsNotFound reports a 404 from the daemon.

func WriteFrame 

func WriteFrame(w io.Writer, stream byte, p []byte) error

WriteFrame writes one frame: header [8]byte{STREAM_TYPE, 0, 0, 0, SIZE1..SIZE4 big-endian}, then the payload.

Types

type Client 

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

Client speaks the API to a daemon.

func NewClient 

func NewClient(host string) (*Client, error)

NewClient connects to host: "unix:///path/to/socket".

func NewClientWith 

func NewClientWith(hc *http.Client, base string) *Client

NewClientWith uses a caller-provided HTTP client and base URL (tests, and later the browser's own transport).

func (*Client) Attach added in v0.5.0 

func (c *Client) Attach(ctx context.Context, id string) (io.ReadCloser, error)

Attach streams a container's output from now until its next exit, multiplexed (see Demux). Attach before Start so nothing is missed.

func (*Client) Changes added in v0.4.0 

func (c *Client) Changes(ctx context.Context, id string) ([]FilesystemChange, error)

Changes lists what a container changed in its filesystem.

func (*Client) Containers 

func (c *Client) Containers(ctx context.Context, all bool) ([]ContainerSummary, error)

Containers lists containers.

func (*Client) Create 

func (c *Client) Create(ctx context.Context, name string, req ContainerCreateRequest) (ContainerCreateResponse, error)

Create creates a container.

func (*Client) DiskUsage added in v0.4.0 

func (c *Client) DiskUsage(ctx context.Context) (SystemDataUsage, error)

DiskUsage is GET /system/df.

func (*Client) Events added in v0.6.0 

func (c *Client) Events(ctx context.Context, o EventsOptions, fn func(EventMessage) error) error

Events streams events to fn until the stream ends (until reached, the context cancelled, or the daemon cutting off a slow reader).

func (*Client) ImageInspect 

func (c *Client) ImageInspect(ctx context.Context, ref string) (json.RawMessage, error)

ImageInspect inspects an image.

func (*Client) Images 

func (c *Client) Images(ctx context.Context) ([]ImageSummary, error)

Images lists images.

func (*Client) Inspect 

func (c *Client) Inspect(ctx context.Context, id string) (json.RawMessage, error)

Inspect inspects a container.

func (*Client) Kill 

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

Kill kills a running container.

func (*Client) Logs 

func (c *Client) Logs(ctx context.Context, id string, follow bool) (io.ReadCloser, error)

Logs returns the multiplexed log stream; demultiplex it with Demux.

func (*Client) Ping 

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

Ping checks the daemon answers.

func (*Client) PruneContainers added in v0.4.0 

func (c *Client) PruneContainers(ctx context.Context) (ContainerPruneResponse, error)

PruneContainers removes every stopped container.

func (*Client) PruneImages added in v0.4.0 

func (c *Client) PruneImages(ctx context.Context, all bool) (ImagePruneResponse, error)

PruneImages removes dangling images, or with all every image no container uses.

func (*Client) Pull 

func (c *Client) Pull(ctx context.Context, ref string, progress func(JSONMessage)) error

Pull pulls ref, calling progress for each message; an error message in the stream is returned as an error.

func (*Client) Remove 

func (c *Client) Remove(ctx context.Context, id string, force bool) error

Remove removes a container.

func (*Client) RemoveImage 

func (c *Client) RemoveImage(ctx context.Context, ref string, force bool) ([]ImageDeleteResponseItem, error)

RemoveImage removes an image.

func (*Client) Restart added in v0.5.0 

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

Restart stops a container if it runs, then starts it.

func (*Client) Start 

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

Start starts a container.

func (*Client) Stop added in v0.5.0 

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

Stop stops a running container and returns once it has exited; a container that is not running is not an error (the daemon answers 304).

func (*Client) Version 

func (c *Client) Version(ctx context.Context) (SystemVersion, error)

Version returns the daemon's version.

func (*Client) Wait 

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

Wait registers a wait for condition; it returns once the daemon has acknowledged it, before the container exits.

type ContainerConfig 

type ContainerConfig struct {
	Image      string            `json:"Image"`
	Cmd        StrSlice          `json:"Cmd"`
	Entrypoint StrSlice          `json:"Entrypoint"`
	Env        []string          `json:"Env"`
	WorkingDir string            `json:"WorkingDir"`
	Labels     map[string]string `json:"Labels"`
	Tty        bool              `json:"Tty"`
}

ContainerConfig is the create body's container part.

type ContainerCreateRequest 

type ContainerCreateRequest struct {
	ContainerConfig
	HostConfig HostConfig `json:"HostConfig"`
}

ContainerCreateRequest is the body of POST /containers/create.

type ContainerCreateResponse 

type ContainerCreateResponse struct {
	ID       string   `json:"Id"`
	Warnings []string `json:"Warnings"`
}

ContainerCreateResponse is the reply to POST /containers/create.

type ContainerInspect 

type ContainerInspect struct {
	ID           string          `json:"Id"`
	Created      string          `json:"Created"`
	Path         string          `json:"Path"`
	Args         []string        `json:"Args"`
	State        ContainerState  `json:"State"`
	Image        string          `json:"Image"`
	Name         string          `json:"Name"`
	RestartCount int             `json:"RestartCount"`
	Driver       string          `json:"Driver"`
	Platform     string          `json:"Platform"`
	SizeRw       int64           `json:"SizeRw"`
	Config       ContainerConfig `json:"Config"`
	HostConfig   HostConfig      `json:"HostConfig"`
}

ContainerInspect is GET /containers/{id}/json (a subset).

type ContainerPruneResponse added in v0.4.0 

type ContainerPruneResponse struct {
	ContainersDeleted []string `json:"ContainersDeleted"`
	SpaceReclaimed    int64    `json:"SpaceReclaimed"`
}

ContainerPruneResponse is POST /containers/prune.

type ContainerState 

type ContainerState struct {
	Status     string `json:"Status"`
	Running    bool   `json:"Running"`
	Paused     bool   `json:"Paused"`
	Restarting bool   `json:"Restarting"`
	OOMKilled  bool   `json:"OOMKilled"`
	Dead       bool   `json:"Dead"`
	Pid        int    `json:"Pid"`
	ExitCode   int    `json:"ExitCode"`
	Error      string `json:"Error"`
	StartedAt  string `json:"StartedAt"`
	FinishedAt string `json:"FinishedAt"`
}

ContainerState is the State of an inspect reply.

type ContainerSummary 

type ContainerSummary struct {
	ID         string            `json:"Id"`
	Names      []string          `json:"Names"`
	Image      string            `json:"Image"`
	ImageID    string            `json:"ImageID"`
	Command    string            `json:"Command"`
	Created    int64             `json:"Created"`
	Ports      []any             `json:"Ports"`
	SizeRw     int64             `json:"SizeRw,omitempty"`
	Labels     map[string]string `json:"Labels"`
	State      string            `json:"State"`
	Status     string            `json:"Status"`
	HostConfig struct {
		NetworkMode string `json:"NetworkMode"`
	} `json:"HostConfig"`
}

ContainerSummary is one entry of GET /containers/json.

type ContainerWaitExitError 

type ContainerWaitExitError struct {
	Message string `json:"Message"`
}

ContainerWaitExitError is the error part of a wait reply.

type ContainerWaitResponse 

type ContainerWaitResponse struct {
	StatusCode int64                   `json:"StatusCode"`
	Error      *ContainerWaitExitError `json:"Error"`
}

ContainerWaitResponse is the reply to POST /containers/{id}/wait.

type ErrDaemon 

type ErrDaemon struct {
	Status  int
	Message string
}

ErrDaemon is wrapped by every error reply of the daemon.

func (*ErrDaemon) Error 

func (e *ErrDaemon) Error() string

type ErrorResponse 

type ErrorResponse struct {
	Message string `json:"message"`
}

ErrorResponse is the body of every error.

type EventActor added in v0.6.0 

type EventActor struct {
	ID         string            `json:"ID"`
	Attributes map[string]string `json:"Attributes"`
}

EventActor is what emitted an event.

type EventMessage added in v0.6.0 

type EventMessage struct {
	Type     string     `json:"Type"`
	Action   string     `json:"Action"`
	Actor    EventActor `json:"Actor"`
	Scope    string     `json:"scope"`
	Time     int64      `json:"time"`
	TimeNano int64      `json:"timeNano"`
}

EventMessage is one line of GET /events.

type EventsOptions added in v0.6.0 

type EventsOptions struct {
	Since, Until string
	Filters      map[string][]string
}

EventsOptions selects events: since and until as GET /events takes them (Unix seconds, RFC 3339 or a duration back from now), filters as key → values.

type FilesystemChange added in v0.4.0 

type FilesystemChange struct {
	Path string `json:"Path"`
	Kind int    `json:"Kind"`
}

FilesystemChange is one entry of GET /containers/{id}/changes; Kind is 0 modified, 1 added, 2 deleted.

type HostConfig 

type HostConfig struct {
	Memory     int64 `json:"Memory"`
	AutoRemove bool  `json:"AutoRemove"`
}

HostConfig is the create body's host part (a subset).

type ImageDeleteResponseItem 

type ImageDeleteResponseItem struct {
	Untagged string `json:"Untagged,omitempty"`
	Deleted  string `json:"Deleted,omitempty"`
}

ImageDeleteResponseItem is one entry of DELETE /images/{name}.

type ImageInspect 

type ImageInspect struct {
	ID           string           `json:"Id"`
	RepoTags     []string         `json:"RepoTags"`
	RepoDigests  []string         `json:"RepoDigests"`
	Created      string           `json:"Created"`
	Author       string           `json:"Author"`
	Architecture string           `json:"Architecture"`
	Os           string           `json:"Os"`
	Size         int64            `json:"Size"`
	Config       ContainerConfig  `json:"Config"`
	RootFS       map[string]any   `json:"RootFS"`
	Metadata     map[string]any   `json:"Metadata,omitempty"`
	Descriptor   *json.RawMessage `json:"Descriptor,omitempty"`
}

ImageInspect is GET /images/{name}/json (a subset).

type ImagePruneResponse added in v0.4.0 

type ImagePruneResponse struct {
	ImagesDeleted  []ImageDeleteResponseItem `json:"ImagesDeleted"`
	SpaceReclaimed int64                     `json:"SpaceReclaimed"`
}

ImagePruneResponse is POST /images/prune.

type ImageSummary 

type ImageSummary struct {
	ID          string            `json:"Id"`
	ParentID    string            `json:"ParentId"`
	RepoTags    []string          `json:"RepoTags"`
	RepoDigests []string          `json:"RepoDigests"`
	Created     int64             `json:"Created"`
	Size        int64             `json:"Size"`
	SharedSize  int64             `json:"SharedSize"`
	Labels      map[string]string `json:"Labels"`
	Containers  int64             `json:"Containers"`
}

ImageSummary is one entry of GET /images/json.

type JSONMessage 

type JSONMessage struct {
	Status      string        `json:"status,omitempty"`
	ID          string        `json:"id,omitempty"`
	Error       string        `json:"error,omitempty"`
	ErrorDetail *JSONMsgError `json:"errorDetail,omitempty"`
}

JSONMessage is one line of the POST /images/create progress stream.

type JSONMsgError 

type JSONMsgError struct {
	Message string `json:"message"`
}

JSONMsgError is the error detail of a JSONMessage.

type StorageUsage added in v0.4.0 

type StorageUsage struct {
	// Kind names the store: "directory /var/lib/wctr", "IndexedDB".
	Kind string `json:"Kind"`
	// Usage and Quota are bytes (-1: unknown); a browser reports its
	// estimate for the whole origin.
	Usage int64 `json:"Usage"`
	Quota int64 `json:"Quota"`
	// Persistent says the browser will not evict it under pressure.
	Persistent bool `json:"Persistent"`
	// Error is the last failure to store the engine's state, if any.
	Error string `json:"Error,omitempty"`
}

StorageUsage describes the engine's storage (see SystemDataUsage).

type StrSlice 

type StrSlice []string

StrSlice accepts a JSON string or array of strings, as Docker's does for Cmd and Entrypoint; null stays nil ("use the image's").

func (*StrSlice) UnmarshalJSON 

func (s *StrSlice) UnmarshalJSON(b []byte) error

UnmarshalJSON implements json.Unmarshaler.

type SystemDataUsage added in v0.4.0 

type SystemDataUsage struct {
	LayersSize int64              `json:"LayersSize"`
	Images     []ImageSummary     `json:"Images"`
	Containers []ContainerSummary `json:"Containers"`
	Volumes    []any              `json:"Volumes"`
	BuildCache []any              `json:"BuildCache"`
	// Storage is this engine's own addition: where its state lives and
	// how full that is. Docker clients ignore it.
	Storage *StorageUsage `json:"Storage,omitempty"`
}

SystemDataUsage is GET /system/df.

type SystemVersion 

type SystemVersion struct {
	Platform      struct{ Name string } `json:"Platform"`
	Version       string                `json:"Version"`
	APIVersion    string                `json:"ApiVersion"`
	MinAPIVersion string                `json:"MinAPIVersion"`
	GitCommit     string                `json:"GitCommit"`
	GoVersion     string                `json:"GoVersion"`
	Os            string                `json:"Os"`
	Arch          string                `json:"Arch"`
	KernelVersion string                `json:"KernelVersion"`
	BuildTime     string                `json:"BuildTime,omitempty"`
}

SystemVersion is GET /version.

type Waiter 

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

Waiter is a registered wait: the daemon has acknowledged it, and Result blocks until the condition holds.

func (*Waiter) Result 

func (w *Waiter) Result() (ContainerWaitResponse, error)

Result blocks for the wait's answer.

Source Files

View all Source files

Directories

Path Synopsis
Package inproc carries HTTP requests to a handler in the same process, with no socket: the browser has no unix sockets, so the playground's wctr talks to its engine through this transport instead.
 Package inproc carries HTTP requests to a handler in the same process, with no socket: the browser has no unix sockets, so the playground's wctr talks to its engine through this transport instead.
Package server serves the engine's Docker Engine API subset over HTTP.
 Package server serves the engine's Docker Engine API subset over HTTP.

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.