shell

README

Noisy Sockets Shell

A WebSockets based remote shell written in Go.

Why?

Because I wanted something akin to OpenSSH but with a simpler protocol that could be used directly in the browser.

Design

• WebSockets (to support browser clients, with relatively low overhead for native clients).
• JSON-RPC 2.0 inspired bidirectional messaging protocol (with message versioning).
• Single channel per connection (multiplexing over TCP isn't worth it due to head-of-line blocking).
• Only supports remote terminals (no port-forwarding, exec, etc).

Usage

Go

go get github.com/noisysocks/shell

TypeScript

A TypeScript client is available on npm as @noisysocks/shell.

npm install @noisysocks/shell

Documentation

Index

• type Client
  • func NewClient(ctx context.Context, logger *slog.Logger, ws *websocket.Conn) (*Client, error)
  • func (c *Client) Close() error
  • func (c *Client) OpenTerminal(columns, rows int, env []string, input io.DeadlineReader, ...) error
  • func (c *Client) ResizeTerminal(columns, rows int) error
  • func (c *Client) Wait() error
• type ExitHandler
• type Handler
  • func NewHandler(ctx context.Context, logger *slog.Logger, ws *websocket.Conn) (*Handler, error)
  • func (h *Handler) Close() error
  • func (h *Handler) Wait() error

Types

type Client

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

Client is a remote shell client.

func NewClient

func NewClient(ctx context.Context, logger *slog.Logger, ws *websocket.Conn) (*Client, error)

NewClient creates a new remote shell client and starts the session.

func (*Client) Close

func (c *Client) Close() error

Close closes the client.

func (*Client) OpenTerminal

func (c *Client) OpenTerminal(columns, rows int, env []string,
	input io.DeadlineReader, output io.DeadlineWriter, onExit ExitHandler) error

OpenTerminal opens a new terminal.

func (*Client) ResizeTerminal

func (c *Client) ResizeTerminal(columns, rows int) error

ResizeTerminal resizes the terminal window.

func (*Client) Wait

func (c *Client) Wait() error

Wait waits for the client to complete (including all background tasks).

type ExitHandler

type ExitHandler func(exitStatus int) error

ExitHandler is a callback function that is called when the remote shell process exits.

type Handler

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

Handler handles a shell session.

func NewHandler

func NewHandler(ctx context.Context, logger *slog.Logger, ws *websocket.Conn) (*Handler, error)

NewHandler creates a new shell handler and starts the session.

func (*Handler) Close

func (h *Handler) Close() error

Close closes the handler.

func (*Handler) Wait

func (h *Handler) Wait() error

Wait waits for the handler to complete (including all background tasks).