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
- func Archive(dir string, w io.Writer) error
- func Extract(r io.Reader, dir string, o ExtractOptions) error
- func Hijack(w http.ResponseWriter) (net.Conn, *bufio.ReadWriter, error)
- func ParseExit(b []byte) (int, string)
- func ParseResize(b []byte) (rows, cols uint16)
- func Splice(client io.ReadWriter, server io.ReadWriteCloser)
- type Conn
- func (c *Conn) Close() error
- func (c *Conn) Exit(status int, msg string) error
- func (c *Conn) Read() (byte, []byte, error)
- func (c *Conn) ReadRequest() (Request, error)
- func (c *Conn) Resize(rows, cols uint16) error
- func (c *Conn) SendRequest(req Request) error
- func (c *Conn) Write(typ byte, payload []byte) error
- func (c *Conn) Writer(typ byte) io.Writer
- type ExtractOptions
- type Owner
- type ReadWriter
- type Request
Constants ¶
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.
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" )
const FreezeLimit = 30 * time.Second
FreezeLimit is the longest a backup may pause a volume's writes.
const Port = 1024
Port is the vsock port the guest listens on.
const Upgrade = "jokku-session"
Upgrade is the HTTP Upgrade token for a session.
Variables ¶
This section is empty.
Functions ¶
func Archive ¶
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 ¶
func Hijack(w http.ResponseWriter) (net.Conn, *bufio.ReadWriter, error)
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 ParseResize ¶
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) ReadRequest ¶
ReadRequest receives the opening frame.
func (*Conn) SendRequest ¶
SendRequest sends the opening frame.
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 ReadWriter ¶
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.