proto

README

Protocol

Each message is represented as a single WebSocket message. A newline character separates a JSON header from the binary body.

Some messages may omit the body.

The overhead of the additional frame is 2 to 6 bytes. In high throughput cases, messages contain ~32KB of data, so this overhead is negligible.

Client Messages

Start

This must be the first Client message.

{
  "type": "start",
  "command": {
    "command": "cat",
    "args": ["/dev/urandom"],
    "tty": false,
    "stdin": false
  }
}

Stdin

{ "type": "stdin" }

and a body follows after a newline character.

Resize

{ "type": "resize", "cols": 80, "rows": 80 }

Only valid on tty messages.

CloseStdin

No more Stdin messages may be sent after this.

{ "type": "close_stdin" }

Server Messages

Pid

This is sent immediately after the command starts.

{ "type": "pid", "pid": 0 }

Stdout

{ "type": "stdout" }

and a body follows after a newline character.

Stderr

{ "type": "stderr" }

and a body follows after a newline character.

ExitCode

This is the last message sent by the server.

{ "type": "exit_code", "exit_code": 255 }

A normal closure follows.

Documentation

Index

• Constants
• func SplitMessage(b []byte) (header []byte, body []byte)
• func WithHeader(w io.Writer, header []byte) io.Writer
• type ClientResizeHeader
• type ClientStartHeader
• type Command
• type Header
• type ServerExitCodeHeader
• type ServerPidHeader

Constants

const (
	TypeStart      = "start"
	TypeResize     = "resize"
	TypeStdin      = "stdin"
	TypeCloseStdin = "close_stdin"
)

Client message header type

const (
	TypePid      = "pid"
	TypeStdout   = "stdout"
	TypeStderr   = "stderr"
	TypeExitCode = "exit_code"
)

Server message header type

Functions

func SplitMessage

func SplitMessage(b []byte) (header []byte, body []byte)

SplitMessage into header and body components all messages must have a header. body returns as nil if no delimiter is found

func WithHeader

func WithHeader(w io.Writer, header []byte) io.Writer

WithHeader adds the given header to all writes

Types

type ClientResizeHeader

type ClientResizeHeader struct {
	Type string `json:"type"`
	Rows uint16 `json:"rows"`
	Cols uint16 `json:"cols"`
}

ClientResizeHeader specifies a terminal window resize request

type ClientStartHeader

type ClientStartHeader struct {
	Type    string  `json:"type"`
	ID      string  `json:"id"`
	Command Command `json:"command"`
}

ClientStartHeader specifies a request to start command

type Command

type Command struct {
	Command    string   `json:"command"`
	Args       []string `json:"args"`
	Stdin      bool     `json:"stdin"`
	TTY        bool     `json:"tty"`
	Rows       uint16   `json:"rows"`
	Cols       uint16   `json:"cols"`
	UID        uint32   `json:"uid"`
	GID        uint32   `json:"gid"`
	Env        []string `json:"env"`
	WorkingDir string   `json:"working_dir"`
}

Command represents a runnable command.

type Header

type Header struct {
	Type string `json:"type"`
}

Header is a generic JSON header.

type ServerExitCodeHeader

type ServerExitCodeHeader struct {
	Type     string `json:"type"`
	ExitCode int    `json:"exit_code"`
	Error    string `json:"error"`
}

ServerExitCodeHeader specifies the final message from the server after the command exits

type ServerPidHeader

type ServerPidHeader struct {
	Type string `json:"type"`
	Pid  int    `json:"pid"`
}

ServerPidHeader specifies the message send immediately after the request command starts