webtty

Documentation

Overview

Package webtty provides a protocol and an implementation to control terminals thorough networks.

Index

• Constants
• Variables
• type Master
• type Option
  • func WithFixedColumns(columns int) Option
  • func WithFixedRows(rows int) Option
  • func WithMasterPreferences(preferences interface{}) Option
  • func WithPermitWrite() Option
  • func WithReconnect(timeInSeconds int) Option
  • func WithWindowTitle(windowTitle []byte) Option
• type Slave
• type WebTTY
  • func New(masterConn Master, slave Slave, options ...Option) (*WebTTY, error)
  • func (wt *WebTTY) Run(ctx context.Context) error

Constants

const (
	// Unknown message type, maybe sent by a bug
	UnknownInput = '0'
	// User input typically from a keyboard
	Input = '1'
	// Ping to the server
	Ping = '2'
	// Notify that the browser size has been changed
	ResizeTerminal = '3'
)

const (
	// Unknown message type, maybe set by a bug
	UnknownOutput = '0'
	// Normal output to the terminal
	Output = '1'
	// Pong to the browser
	Pong = '2'
	// Set window title of the terminal
	SetWindowTitle = '3'
	// Set terminal preference
	SetPreferences = '4'
	// Make terminal to reconnect
	SetReconnect = '5'
)

const (
	MaxBufferSize = 1024 * 1024 * 1
)

Variables

var (
	// ErrSlaveClosed indicates the function has exited by the slave
	ErrSlaveClosed = errors.New("slave closed")

	// ErrSlaveClosed is returned when the slave connection is closed.
	ErrMasterClosed = errors.New("master closed")

	// ErrConnectionLostPing is returned if no ping within a duration
	ErrConnectionLostPing = errors.New("connection lost ping")
)

var Protocols = []string{"webtty"}

Protocols defines the name of this protocol, which is supposed to be used to the subprotocol of Websockt streams.

Types

type Master

type Master io.ReadWriter

Master represents a PTY master, usually it's a websocket connection.

type Option

type Option func(*WebTTY) error

Option is an option for WebTTY.

func WithFixedColumns

func WithFixedColumns(columns int) Option

WithFixedColumns sets a fixed width to TTY master.

func WithFixedRows

func WithFixedRows(rows int) Option

WithFixedRows sets a fixed height to TTY master.

func WithMasterPreferences

func WithMasterPreferences(preferences interface{}) Option

WithMasterPreferences sets an optional configuration of master.

func WithPermitWrite

func WithPermitWrite() Option

WithPermitWrite sets a WebTTY to accept input from slaves.

func WithReconnect

func WithReconnect(timeInSeconds int) Option

WithReconnect enables reconnection on the master side.

func WithWindowTitle

func WithWindowTitle(windowTitle []byte) Option

WithWindowTitle sets the default window title of the session

type Slave

type Slave interface {
	io.ReadWriter

	// WindowTitleVariables returns any values that can be used to fill out
	// the title of a terminal.
	WindowTitleVariables() map[string]interface{}

	// ResizeTerminal sets a new size of the terminal.
	ResizeTerminal(columns int, rows int) error
}

Slave represents a PTY slave, typically it's a local command.

type WebTTY

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

WebTTY bridges a PTY slave and its PTY master. To support text-based streams and side channel commands such as terminal resizing, WebTTY uses an original protocol.

func New

func New(masterConn Master, slave Slave, options ...Option) (*WebTTY, error)

New creates a new instance of WebTTY. masterConn is a connection to the PTY master, typically it's a websocket connection to a client. slave is a PTY slave such as a local command with a PTY.

func (*WebTTY) Run

func (wt *WebTTY) Run(ctx context.Context) error

Run starts the main process of the WebTTY. This method blocks until the context is canceled. Note that the master and slave are left intact even after the context is canceled. Closing them is caller's responsibility. If the connection to one end gets closed, returns ErrSlaveClosed or ErrMasterClosed.