wire

package
v1.10.0 Latest Latest
Warning

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

Go to latest
Published: Nov 21, 2026 License: Apache-2.0 Imports: 5 Imported by: 0

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

View Source
const (
	CodeTimeout   = "timeout"
	CodeForbidden = "forbidden"
)

CodeTimeout and CodeForbidden are the codes only the checker socket uses.

View Source
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.

View Source
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.

View Source
const (
	CodeNotFound    = "not-found"
	CodeDisabled    = "disabled"
	CodeLimit       = "limit"
	CodeBadRequest  = "bad-request"
	CodeUnavailable = "unavailable"
	CodeBusy        = "busy"
	// CodeUnauthorized: the grant of the open request is not valid for it (signature, audience, kind, lifetime, or a field that does not
	// 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.

View Source
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.

View Source
const CheckerPath = "/v1/probe"

CheckerPath is the path of the one endpoint of the checker socket.

View Source
const (
	KindConsole = "console"
)

Kinds of a stream the service serves.

View Source
const StreamPath = "/v1/stream"

StreamPath is the path on which the service accepts a stream (a WebSocket on the pod network).

Variables

View Source
var ErrFrame = errors.New("invalid frame")

ErrFrame is returned for a message that is not a valid frame.

Functions

func Ack

func Ack(n uint32) []byte

Ack builds an acknowledgement frame.

func AckValue

func AckValue(payload []byte) uint32

AckValue reads an acknowledgement payload.

func Close

func Close(reason string) []byte

Close builds a close frame.

func CommandHash

func CommandHash(command []string) string

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.

func Data

func Data(p []byte) []byte

Data builds a data frame.

func Parse

func Parse(msg []byte) (typ byte, payload []byte, err error)

Parse splits a message into its type and payload and checks it against the rules of the type. The payload aliases msg.

func Resize

func Resize(cols, rows uint16) []byte

Resize builds a resize frame.

func Size

func Size(payload []byte) (cols, rows uint16, err error)

Size reads a resize payload and checks the bounds.

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL