docker

Documentation

Overview

Package docker implements the openblox sandbox contract on Docker with the gVisor (runsc) runtime.

It holds no state of its own. Container labels are the sandbox registry, so sandboxes survive the process that created them and several processes may manage the same set without coordinating.

Index

• Constants
• func IsDigestPinned(ref string) bool
• type Backend
  • func New(opts ...Option) (*Backend, error)
  • func (b *Backend) Close() error
  • func (b *Backend) Create(ctx context.Context, name string, opts ...sandbox.CreateOption) (sandbox.Sandbox, error)
  • func (b *Backend) Destroy(ctx context.Context, name string) error
  • func (b *Backend) DialPort(ctx context.Context, name string, port int) (net.Conn, error)
  • func (b *Backend) List(ctx context.Context) ([]sandbox.Info, error)
  • func (b *Backend) Open(ctx context.Context, name string) (sandbox.Sandbox, error)
  • func (b *Backend) PreviewHandler() *preview.Handler
  • func (b *Backend) Reap(ctx context.Context) ([]string, error)
• type Option
  • func WithPreviews(key []byte, baseURL string) Option

Constants

const DefaultPreviewTTL = 10 * time.Minute

DefaultPreviewTTL applies when Expose is asked for no particular lifetime.

Functions

func IsDigestPinned

func IsDigestPinned(ref string) bool

IsDigestPinned reports whether ref names an image by digest rather than by a tag. A tag can be repointed by whoever controls the registry; a digest cannot.

Types

type Backend

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

Backend creates sandboxes as Docker containers.

func New

func New(opts ...Option) (*Backend, error)

New connects to the Docker daemon using the standard environment (DOCKER_HOST, DOCKER_CERT_PATH, DOCKER_API_VERSION).

func (*Backend) Close

func (b *Backend) Close() error

Close releases the Docker client. Running sandboxes are left alone.

func (*Backend) Create

func (b *Backend) Create(ctx context.Context, name string, opts ...sandbox.CreateOption) (sandbox.Sandbox, error)

Create returns a running sandbox for name, creating it if absent.

func (*Backend) Destroy

func (b *Backend) Destroy(ctx context.Context, name string) error

Destroy removes a sandbox. Destroying an absent sandbox is not an error.

func (*Backend) DialPort

func (b *Backend) DialPort(ctx context.Context, name string, port int) (net.Conn, error)

DialPort opens a byte stream to a port on the sandbox's loopback interface.

The sandbox has no network interface, so there is no address to connect to from outside. Instead the connection is carried over the runtime's exec channel: a relay runs inside the sandbox, dials 127.0.0.1:port there, and its stdin and stdout become the two directions of this connection.

This is the only way to reach a sandbox port without giving the sandbox a network, and giving it one would undo the containment openblox exists for. An interface — even on a Docker network marked internal — restores a DNS resolver to abuse as a covert channel and makes sandboxes reachable from one another. Routing through the control channel keeps the default posture intact: nothing in, nothing out, except what openblox carries itself.

The cost is one exec per connection, and a dependency on the image providing a relay. Both are acceptable for previews, which are few and long-lived.

func (*Backend) List

func (b *Backend) List(ctx context.Context) ([]sandbox.Info, error)

List returns every sandbox this backend manages.

func (*Backend) Open

func (b *Backend) Open(ctx context.Context, name string) (sandbox.Sandbox, error)

Open returns an existing sandbox, or ErrNotFound.

func (*Backend) PreviewHandler

func (b *Backend) PreviewHandler() *preview.Handler

PreviewHandler returns the HTTP handler that serves this backend's previews, or nil if previews were not configured. Mount it at preview.RoutePrefix.

openblox does not run a server. Which address it listens on, behind what TLS, and who can reach it are deployment decisions.

func (*Backend) Reap

func (b *Backend) Reap(ctx context.Context) ([]string, error)

Reap destroys sandboxes that have outlived their bounds and returns the names it destroyed. Call it from a ticker; it holds no state and several processes may run it concurrently against the same daemon.

Each sandbox carries its own bounds, recorded as labels when it was created, so a reaper reclaims sandboxes it knows nothing about — including ones created before it started. A bound recorded as zero or negative is disabled.

Two bounds, and they are not redundant. Idle reclaims the common case: a sandbox nobody came back to. MaxAge catches what idle cannot — a sandbox kept permanently warm by a wedged or deliberately busy background process is never idle, and without MaxAge it would live forever.

Errors reaping one sandbox do not stop the sweep; they are joined and returned once every sandbox has been considered.

type Option

type Option func(*Backend) error

Option configures a Backend at construction.

func WithPreviews

func WithPreviews(key []byte, baseURL string) Option

WithPreviews enables Expose, signing credentials with key and serving them under baseURL — the address, including scheme, that the returned Handler is reachable on from wherever the preview will be opened.

The key must be at least preview.MinKeyBytes of CSPRNG output, and the same key everywhere previews are minted or served.