session

package
v0.8.22 Latest Latest
Warning

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

Go to latest
Published: Oct 17, 2026 License: MIT Imports: 17 Imported by: 0

Documentation

Overview

Package session is how Jokku reaches inside a running microVM: a shell or command (jokku enter), and a volume's files (storage:export, storage:import). Every VM's init listens on a vsock port; the node's agent connects through Firecracker's vsock socket and relays a session from the control node, which relays it from the CLI:

CLI <-HTTP upgrade-> API <-HTTP upgrade over the mesh-> node agent <-vsock-> guest init

All hops speak the same frames. The first is a Request; the guest answers with output frames and ends with an Exit frame. The node agent adds the VM's token to the request, so only it can open sessions with its VMs.

Index

Constants

View Source
const (
	FrameRequest byte = 'Q' // JSON Request, first, from the client
	FrameStdin   byte = 'I'
	FrameEOF     byte = 'C' // no more stdin
	FrameResize  byte = 'R' // rows and cols, uint16 each
	FrameStdout  byte = 'O'
	FrameStderr  byte = 'E'
	FrameExit    byte = 'X' // int32 status, then a message (empty on success)
)

Frame types.

View Source
const (
	OpExec   = "exec"
	OpExport = "export"
	OpImport = "import"
	// OpFreeze pauses writes to the filesystem mounted at Path (a volume)
	// while the node backs it up. The guest says "frozen" on stdout, then
	// resumes writes at the client's EOF, when the client goes away, or
	// after FreezeLimit, and exits non-zero in the last case.
	OpFreeze = "freeze"
)
View Source
const FreezeLimit = 30 * time.Second

FreezeLimit is the longest a backup may pause a volume's writes.

View Source
const Port = 1024

Port is the vsock port the guest listens on.

View Source
const Upgrade = "jokku-session"

Upgrade is the HTTP Upgrade token for a session.

Variables

This section is empty.

Functions

func Archive

func Archive(dir string, w io.Writer) error

Archive writes dir's contents as a gzipped tar, keeping owners, modes and symlinks. Sockets, devices and pipes are left out.

func Extract

func Extract(r io.Reader, dir string, o ExtractOptions) error

Extract unpacks a tar (gzipped or not) into dir, keeping modes, and owners unless o.Owner says otherwise. Entries that would land outside dir, directly or through a symlink, are refused.

func Hijack

Hijack takes over an HTTP connection that asked to upgrade to a session, answering 101 Switching Protocols. Bytes the client sent after its request are in the returned reader.

func ParseExit

func ParseExit(b []byte) (int, string)

ParseExit reads an Exit frame's payload.

func ParseResize

func ParseResize(b []byte) (rows, cols uint16)

ParseResize reads a Resize frame's payload.

func Splice

func Splice(client io.ReadWriter, server io.ReadWriteCloser)

Splice relays a session between a client and the server side (towards the guest) until the server's side ends, so its last frames, the exit status among them, always get through. Input the server no longer reads is dropped; a client that goes away closes the server's side, which ends the session.

Types

type Conn

type Conn struct {
	// contains filtered or unexported fields
}

Conn reads and writes frames. Writes are safe from several goroutines.

func New

func New(rw io.ReadWriteCloser) *Conn

func NewReader

func NewReader(r *bufio.Reader, rw io.ReadWriteCloser) *Conn

NewReader is New for a connection whose first bytes were already buffered (by an HTTP server that hijacked it).

func (*Conn) Close

func (c *Conn) Close() error

func (*Conn) Exit

func (c *Conn) Exit(status int, msg string) error

Exit ends a session with a status and, on failure, why.

func (*Conn) Read

func (c *Conn) Read() (byte, []byte, error)

Read receives one frame.

func (*Conn) ReadRequest

func (c *Conn) ReadRequest() (Request, error)

ReadRequest receives the opening frame.

func (*Conn) Resize

func (c *Conn) Resize(rows, cols uint16) error

Resize sends a terminal size.

func (*Conn) SendRequest

func (c *Conn) SendRequest(req Request) error

SendRequest sends the opening frame.

func (*Conn) Write

func (c *Conn) Write(typ byte, payload []byte) error

Write sends one frame.

func (*Conn) Writer

func (c *Conn) Writer(typ byte) io.Writer

Writer sends everything written to it as frames of typ.

type ExtractOptions

type ExtractOptions struct {
	Clear bool // empty the directory first
	// Owner, when set, owns everything extracted, instead of the numeric
	// owners in the archive (which come from wherever it was made).
	Owner *Owner
}

ExtractOptions say how Extract restores files.

type Owner

type Owner struct{ UID, GID int }

Owner is a numeric user and group.

type ReadWriter

type ReadWriter struct {
	io.Reader
	io.Writer
}

ReadWriter pairs a reader with a writer.

type Request

type Request struct {
	Op   string   `json:"op"` // exec, export or import
	Argv []string `json:"argv,omitempty"`
	TTY  bool     `json:"tty,omitempty"`
	Rows uint16   `json:"rows,omitempty"`
	Cols uint16   `json:"cols,omitempty"`
	Root bool     `json:"root,omitempty"` // exec as root rather than the image's user
	Env  []string `json:"env,omitempty"`  // extra, e.g. TERM

	Path  string `json:"path,omitempty"`  // export, import and freeze: the directory
	Live  bool   `json:"live,omitempty"`  // export without pausing the app
	Clear bool   `json:"clear,omitempty"` // import into an emptied directory
	// KeepOwners restores the archive's numeric owners on import, instead
	// of giving everything to the directory's owner.
	KeepOwners bool `json:"keep_owners,omitempty"`

	Token string `json:"token,omitempty"` // set by the node agent
}

Request is what a session does.

Jump to

Keyboard shortcuts

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