Documentation
¶
Overview ¶
Package brokerapi holds the wire types openbloxd speaks and brokerclient consumes. It deliberately mirrors pkg/sandbox rather than re-modelling it: the broker exposes the library's surface and nothing more.
Index ¶
Constants ¶
const ( KindNotFound = "not_found" KindInvalid = "invalid" KindConflict = "conflict" KindStopped = "stopped" KindTimeout = "timeout" KindAtCapacity = "at_capacity" KindInternal = "internal" )
Error kinds. The status code alone cannot distinguish every sentinel — two map to 503 — so the kind is what the client maps back from.
const UpgradeProto = "openblox-stream"
UpgradeProto names the raw stream the dial endpoint switches to. It is not a WebSocket: there is no framing, because the payload is an arbitrary byte stream both sides already know how to interpret.
Variables ¶
var ErrAtCapacity = errors.New("profile is at its concurrent sandbox limit")
ErrAtCapacity means the profile already holds as many sandboxes as its max_sandboxes allows. It is deliberately distinct from ErrInvalid: the request is well formed and may well succeed later, once the reaper or an explicit Destroy frees a slot. A caller that cannot tell those apart either retries a malformed request forever or gives up on a temporary refusal.
var ErrInternal = errors.New("openbloxd: internal error")
ErrInternal is what an unrecognised server-side failure becomes on the client. The daemon's own message is logged, not returned: it would describe the host's internals to the caller.
var ErrProfileConflict = errors.New("sandbox exists under a different profile")
ErrProfileConflict means the named sandbox exists under a different profile. Returning the live sandbox instead would hand the caller a policy it did not ask for, which is exactly the confusion the broker exists to prevent.
Functions ¶
Types ¶
type CreateRequest ¶
type CreateRequest struct {
Name string `json:"name"`
Profile string `json:"profile"`
Env []string `json:"env,omitempty"`
Labels map[string]string `json:"labels,omitempty"`
}
CreateRequest is the whole of what a caller may ask for. Every field that could weaken isolation is absent by design and is daemon configuration instead — see the profile config. Adding a field here is a security change.
type ExecRequest ¶
type ExecRequest struct {
Argv []string `json:"argv"`
Env []string `json:"env,omitempty"`
Dir string `json:"dir,omitempty"`
Timeout string `json:"timeout,omitempty"`
}
ExecRequest runs one command. Timeout is a Go duration string; the daemon clamps it to the profile's maximum, so it can only narrow.
type ExecResponse ¶
type ExecResponse struct {
Stdout []byte `json:"stdout"`
Stderr []byte `json:"stderr"`
ExitCode int `json:"exit_code"`
// Truncated mirrors sandbox.Result.Truncated.
Truncated bool `json:"truncated,omitempty"`
}
ExecResponse carries raw bytes: a sandbox runs arbitrary programs and its output is not guaranteed to be valid UTF-8.
type Info ¶
type Info struct {
Name string `json:"name"`
ID string `json:"id"`
Image string `json:"image"`
State string `json:"state"`
CreatedAt time.Time `json:"created_at"`
Profile string `json:"profile"`
Labels map[string]string `json:"labels,omitempty"`
}
Info describes a sandbox. Profile is reported so a caller can tell which policy a pre-existing sandbox was created under. Labels are exactly the caller's own labels from Create — the daemon's own bookkeeping (which profile a sandbox belongs to) is never mixed in here, because it is already reported separately as Profile.
type ProcessRequest ¶
type ProcessRequest struct {
Name string `json:"name"`
Argv []string `json:"argv"`
Env []string `json:"env,omitempty"`
Dir string `json:"dir,omitempty"`
}
ProcessRequest starts a detached background process.
type ProfileInfo ¶
type ProfileInfo struct {
Name string `json:"name"`
IdleTimeout string `json:"idle_timeout"`
MaxAge string `json:"max_age"`
}
ProfileInfo reports a profile's lifetime bounds. A caller running its own reaper needs these to stay ordered behind the daemon's.
Source Files