ttyd

README

ttyd-go

A go implementation of tsl0922/ttyd.

Features

Most of the features of the ttyd are supported.

• Built on top of WebGL2 for speed
• Fully-featured terminal with CJK and IME support
• ZMODEM (lrzsz) / trzsz file transfer support
• Sixel image output support (img2sixel / lsix)
• Run any custom command with options
• Cross-platform: macOS, Linux, FreeBSD/OpenBSD, OpenWrt. Windows is not supported yet.

Library Usage

Under construction 🚧.

Command Usage

Under construction 🚧.

Documentation

Index

• Variables
• func DefaultTokenHandlerFunc(w http.ResponseWriter, r *http.Request)
• type Handler
  • func NewHandler(cmd *exec.Cmd, options ...HandlerOption) *Handler
  • func (h *Handler) HandleTTYD(conn net.Conn, brw *bufio.ReadWriter, hs ws.Handshake)
  • func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type HandlerOption
  • func EnableClientInput() HandlerOption
  • func EnableCompressionWithContextTakeover() HandlerOption
  • func EnableCompressionWithExtension(extension *wsflate.Extension) HandlerOption
  • func EnableCompressionWithNoContextTakeover() HandlerOption
  • func WithClientOptions(options map[string]any) HandlerOption
  • func WithCompressionLevel(level int) HandlerOption
  • func WithMessageSizeLimit(limit int64) HandlerOption
  • func WithPingInterval(interval time.Duration) HandlerOption
  • func WithTitle(title string) HandlerOption

Variables

var DefaultHTML string

DefaultHTML is used to serve the default HTML page for the ttyd server. Advanced users may choose a different HTML page that implements ttyd protocol.

Functions

func DefaultTokenHandlerFunc

func DefaultTokenHandlerFunc(w http.ResponseWriter, r *http.Request)

DefaultTokenHandlerFunc is used to serve the default token for the ttyd server. ttyd protocol requires a token to be sent in the first message, but there are other ways to authenticate the client, such as using the URL query parameters and standard HTTP authentications.

Types

type Handler

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

Handler handles each ttyd session.

func NewHandler

func NewHandler(cmd *exec.Cmd, options ...HandlerOption) *Handler

NewHandler returns a new Handler with specified options applied. cmd mustn't be nil. By default, client input is not forwarded to the tty, no compression is negotiated, message has the size limit of 4096, and no ping is sent by the server.

func (*Handler) HandleTTYD

func (h *Handler) HandleTTYD(conn net.Conn, brw *bufio.ReadWriter, hs ws.Handshake)

HandleTTYD handles a WebSocket connection upgraded through other means. Normally NewHandler should be used instead. Provided bufio.ReadReadWriter should have buffers with the size of at least 512. The writer buffer size will also impact how much data is read from the process per read operation.

func (*Handler) ServeHTTP

func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP upgrades the HTTP connection to a WebSocket connection and serve ttyd protocol on it.

type HandlerOption

type HandlerOption func(*Handler)

A HandlerOption sets an option on a handler.

func EnableClientInput

func EnableClientInput() HandlerOption

EnableClientInput enables client inputs to the tty.

func EnableCompressionWithContextTakeover

func EnableCompressionWithContextTakeover() HandlerOption

EnableCompressionWithContextTakeover enables compression with context takeover.

func EnableCompressionWithExtension

func EnableCompressionWithExtension(extension *wsflate.Extension) HandlerOption

EnableCompressionWithExtension enables compression with the specified extension.

func EnableCompressionWithNoContextTakeover

func EnableCompressionWithNoContextTakeover() HandlerOption

EnableCompressionWithNoContextTakeover enables compression with no context takeover.

func WithClientOptions

func WithClientOptions(options map[string]any) HandlerOption

WithClientOptions sets the client options to be sent to the client. These options can also be set by the client using the URL query parameters, and they have a higher priority than these options. Caller should make sure the options can be serialized to JSON.

func WithCompressionLevel

func WithCompressionLevel(level int) HandlerOption

WithCompressionLevel sets the compression level for the flate writer if compression is negotiated with the peer. Invalid levels or NoCompression will be treated as default compression level.

func WithMessageSizeLimit

func WithMessageSizeLimit(limit int64) HandlerOption

WithMessageSizeLimit sets the maximum size of messages that can be sent to the server. Zero or negative value means no limit.

func WithPingInterval

func WithPingInterval(interval time.Duration) HandlerOption

WithPingInterval sets the interval at which ping frames are sent to clients. Zero or negative value disables the sending of pings. It's used to keep the connection alive when ttyd is used over a proxy.

func WithTitle

func WithTitle(title string) HandlerOption

WithTitle sets the title of the terminal. By default, the title is set to the command being run joined with the hostname.