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 (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
Constants ¶
const DefaultPreviewTTL = 10 * time.Minute
DefaultPreviewTTL applies when Expose is asked for no particular lifetime.
Variables ¶
This section is empty.
Functions ¶
func IsDigestPinned ¶
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 ¶
New connects to the Docker daemon using the standard environment (DOCKER_HOST, DOCKER_CERT_PATH, DOCKER_API_VERSION).
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) DialPort ¶
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) PreviewHandler ¶
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 ¶
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 ¶
Option configures a Backend at construction.
func WithPreviews ¶
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.
Source Files