Documentation
¶
Overview ¶
Package wire is the framing of a console stream. The browser and the L7 proxy speak it over a WebSocket, and so do the proxy and the device access service: the proxy checks every frame it relays, so neither side ever hands a raw, unchecked message to the other. The package has no dependencies, so the proxy can import it without pulling in the container runtime.
A connection starts with one text message (JSON): the open request towards the service, the ready message towards the browser. Everything after is a binary message: one type byte followed by the payload of that type.
Index ¶
- Constants
- Variables
- func Ack(n uint32) []byte
- func AckValue(payload []byte) uint32
- func Close(reason string) []byte
- func CommandHash(command []string) string
- func Data(p []byte) []byte
- func Parse(msg []byte) (typ byte, payload []byte, err error)
- func Resize(cols, rows uint16) []byte
- func Size(payload []byte) (cols, rows uint16, err error)
- type OpenReply
- type OpenRequest
- type ProbeRequest
- type ProbeResponse
Constants ¶
const ( CodeTimeout = "timeout" CodeForbidden = "forbidden" )
CodeTimeout and CodeForbidden are the codes only the checker socket uses.
const ( // TypeData carries terminal bytes in either direction (stdin to the device, output from it). Opaque to the platform. TypeData byte = 1 // TypeResize carries the new size of the terminal: columns and rows, two big-endian uint16. Browser to device only. TypeResize byte = 2 // TypeClose ends the stream. The payload is a short reason (one of the Reason constants), for the log only. TypeClose byte = 3 // TypeAck tells the sender how many output bytes the browser has finished drawing (a big-endian uint32). It is the flow control of // the terminal and is spoken between the browser and the proxy only; the service never sees it. TypeAck byte = 4 )
Frame types.
const ( // MaxData is the largest data payload. MaxData = 32 << 10 // MaxFrame is the largest whole message (type byte included) that either side accepts. MaxFrame = MaxData + 16 // MaxOpen is the largest open or ready message. MaxOpen = 8 << 10 // MinSize and MaxSize bound the terminal size. MinSize, MaxSize = 1, 500 )
Limits of a frame. A frame is never larger than this, so a peer cannot make the other side allocate more.
const ( CodeNotFound = "not-found" CodeDisabled = "disabled" CodeLimit = "limit" CodeBadRequest = "bad-request" CodeBusy = "busy" // agree with it). Nothing says which. CodeUnauthorized = "unauthorized" )
Codes of a refusal: the short words in OpenReply.Error and in the error message the browser gets. They name what went wrong in the platform's terms and never carry text of the device.
const ( ReasonExit = "exit" ReasonClient = "client" ReasonIdle = "idle" ReasonLifetime = "lifetime" ReasonAccess = "access-lost" ReasonLimit = "limit" ReasonError = "error" ReasonShutdown = "shutdown" ReasonStalled = "stalled" ReasonRefused = "refused" )
Close reasons. They are for the log and the metric label, never for the participant's eyes beyond a short word.
const CheckerPath = "/v1/probe"
CheckerPath is the path of the one endpoint of the checker socket.
const (
KindConsole = "console"
)
Kinds of a stream the service serves.
const StreamPath = "/v1/stream"
StreamPath is the path on which the service accepts a stream (a WebSocket on the pod network).
Variables ¶
var ErrFrame = errors.New("invalid frame")
ErrFrame is returned for a message that is not a valid frame.
Functions ¶
func CommandHash ¶
CommandHash is a short fingerprint of a command line for the session log: a wrong value stays visible after the fact without the log holding the command itself.
Types ¶
type OpenReply ¶
type OpenReply struct {
OK bool `json:"ok"`
// Error is a short code (one of the Code constants) when OK is false.
Error string `json:"error,omitempty"`
}
OpenReply answers an open request.
type OpenRequest ¶
type OpenRequest struct {
Kind string `json:"kind"`
Namespace string `json:"namespace"`
Lab string `json:"lab"`
Device string `json:"device"`
// Command and User are the terminal settings of the device, as the lab author set them (empty: /bin/sh, and the user of the
// image). They are checked again in the service.
Command []string `json:"command,omitempty"`
User string `json:"user,omitempty"`
// Cols and Rows are the initial size of the terminal (console only).
Cols uint16 `json:"cols,omitempty"`
Rows uint16 `json:"rows,omitempty"`
// Client and Group are the identifiers the proxy knows the participant by (a pseudonym, never an address). The service logs them and
// counts consoles per client; it does not interpret them.
Client string `json:"client,omitempty"`
Group string `json:"group,omitempty"`
// Grant is the console grant the browser presented to the proxy, forwarded unchanged: a JWS the tenant's platform signed (see
// internal/grant). The service verifies it with the tenant's access key and requires every other field of the request to agree with it
// (client with sub, group with group_id, lab, device with dev); nothing else authenticates the request, and the proxy signs nothing.
Grant string `json:"grant"`
}
OpenRequest is the first message the proxy sends to the service. The caller names a device and nothing else about the container: the service finds the container itself and accepts no container id, pod name or program path.
type ProbeRequest ¶
type ProbeRequest struct {
Namespace string `json:"namespace"`
Lab string `json:"lab"`
Device string `json:"device"`
// Command is one of the check subcommands of the probe (check-exec, check-file, check-observe); Arg is its one JSON argument.
Command string `json:"command"`
Arg string `json:"arg"`
// TimeoutMs is how long the probe may run before it is killed; the service lowers it to its own ceiling.
TimeoutMs int64 `json:"timeoutMs"`
}
ProbeRequest is one run of the probe in a device.
type ProbeResponse ¶
type ProbeResponse struct {
Error string `json:"error,omitempty"`
Exit int `json:"exit"`
Stdout []byte `json:"stdout,omitempty"`
}
ProbeResponse is what the probe printed. Error is a short code (the Code constants, or "timeout"/"busy"); Stdout is the probe's one JSON document, which the checker judges and never publishes.