wsmux

Documentation

Overview

wsmux multiplexes multiple bidirectional streams over a single websocket.

It presents an Session API similar to the TCP socket API.

This is a low-level part of websocktunnel; users should instead use the github.com/taskcluster/client class.

Index

• Constants
• Variables
• type Config
• type Session
  • func Client(conn *websocket.Conn, conf Config) *Session
  • func Server(conn *websocket.Conn, conf Config) *Session
  • func (s *Session) Accept() (net.Conn, error)
  • func (s *Session) Addr() net.Addr
  • func (s *Session) Close() error
  • func (s *Session) IsClosed() bool
  • func (s *Session) Open() (net.Conn, error)

Constants

const (
	// DefaultCapacity of read buffer.
	DefaultCapacity = 1024
)

const HEADER_SIZE = 5

Variables

var (

	// ErrAcceptTimeout is returned when the Accept operation times out
	ErrAcceptTimeout = errors.New("accept timed out")

	// ErrBrokenPipe is returned when data cannot be written to or read from a stream
	ErrBrokenPipe = errors.New("broken pipe")

	// ErrWriteTimeout if the write operation on a stream times out
	ErrWriteTimeout = errors.New("wsmux: write operation timed out")

	// ErrReadTimeout if the read operation on a stream times out
	ErrReadTimeout = errors.New("wsmux: read operation timed out")

	// ErrNoCapacity is returns if the read buffer is full and a session attempts to load
	// more data into the buffer
	ErrNoCapacity = errors.New("buffer does not have capacity to accomodate extra data")

	// ErrDuplicateStream is returned when a duplicate stream is found
	ErrDuplicateStream = errors.New("duplicate stream")

	//ErrSessionClosed is returned when a closed session tries to create a new stream
	ErrSessionClosed = errors.New("session closed")

	//ErrInvalidDeadline is returned when the time is before the current time
	ErrInvalidDeadline = errors.New("invalid deadline")

	//ErrKeepAliveExpired is returned when the keep alive timer expired
	ErrKeepAliveExpired = errors.New("keep alive timer expired")

	// ErrMalformedHeader indicate a websocket frame header was invalid.
	ErrMalformedHeader = errors.New("malformed header")

	// ErrTooManySyns indicates too many un-accepted new incoming streams
	ErrTooManySyns = errors.New("too many un-accepted new incoming streams")
)

Types

type Config

type Config struct {
	// KeepAliveInterval is the interval between keepAlives.  The session will send websocket
	// ping frames at this interval. Default: 10 seconds
	KeepAliveInterval time.Duration

	// StreamAcceptDeadline is the time after which opening a new stream will time out.
	// Default: 30 seconds
	StreamAcceptDeadline time.Duration

	// CloseCallback is a callback function which is invoked when the session is closed.
	// This can be updated later with `session.SetCloseCallback(..)`.
	CloseCallback func()

	// Log must implement util.Logger. This defaults to NilLogger.
	Log util.Logger

	// StreamBufferSize sets the maximum buffer size of streams created by the session.
	// Default: 1024 bytes
	StreamBufferSize int
}

Config contains configuration for a new session, as created with `Server` or `Client`. All of the fields are optional.

type Session

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

Session allows creating and accepting wsmux streams over a websocket connection. It is created with the `wsmux.Server` or `wsmux.Client` functions.

Session implements net.Listener

func Client

func Client(conn *websocket.Conn, conf Config) *Session

Client instantiates a new client session over a websocket connection.

This function takes ownership of `conn`; nothing else should use the connection.

func Server

func Server(conn *websocket.Conn, conf Config) *Session

Server instantiates a new server session over a websocket connection.

This function takes ownership of `conn`; nothing else should use the connection.

func (*Session) Accept

func (s *Session) Accept() (net.Conn, error)

Accept an incoming stream, as specified for the net.Listener interface.

func (*Session) Addr

func (s *Session) Addr() net.Addr

Addr returns the address of this listener. This is required for implementing net.Listener, but its return value here is not very useful.

func (*Session) Close

func (s *Session) Close() error

Close closes the current session and underlying websocket connection. All pending Accept calls will fail with ErrSessionClosed, and all existing streams will be killed.

func (*Session) IsClosed

func (s *Session) IsClosed() bool

IsClosed returns true if the session is closed.

func (*Session) Open

func (s *Session) Open() (net.Conn, error)

Open a new stream to the remote end, returning a `net.Conn` as well as a stream ID. The remote end must call Accept to accept the connection. If this does not occur within the deadline, this function will fail.

Opening a connection creates a fresh new stream ID and sends a msgSYN frame containing that ID to the remote side. The stream is considered accepted when a msgACK frame arrives with the same stream ID.