gomux

README

Gomux

Gomux is a high-performance stream multiplexer inspired from SiaMux. It allows you to operate many distinct bidirectional streams on top of a single underlying connection. It transparently encrypts all data using XChaCha20-Poly1305 with a pre-shared key.

Specification

A gomux session is an exchange of frames between two peers over a shared connection.

Frames

All integers in this spec are little-endian.

A frame consists of a frame header followed by a payload. A header is 8 bytes and defined as:

Bits	Type	Name	Description
32	uint32	ID	The ID specifies which stream a frame belongs to. Streams are numbered sequentially, starting at 0. To prevent collisions, streams initiated by the client peer use even IDs, while the server peer uses odd IDs.
32	uint32	Length	The length specifies the length of the payload or window update.
32	uint32	Flags	Determines the type of frame and how it should be processed.

The flags are defined as:

Value	Name	Description
0	Data	Indicates a payload of size length follows the frame.
1	Keepalive	Indicates a keepalive frame. Contain no payload and merely serve to keep the underlying connection open.
2	OpenStream	Indicates to the accepting peer the creation of a new stream.
3	CloseRead	Closes the stream for reading.
4	CloseWrite	Closes the stream for writing.
5	CloseStream	Indicates that the stream has been closed by the peer.
6	WindowUpdate	Indicates to the peer that length bytes have been read from the stream ID read buffer.
7	CloseMux	Indicates the shutdown of the stream multiplexer.

Documentation

Index

• Variables
• type Mux
  • func Client(conn net.Conn, psk string) *Mux
  • func Server(conn net.Conn, psk string) *Mux
  • func (m *Mux) AcceptStream() (*Stream, error)
  • func (m *Mux) Close() error
  • func (m *Mux) OpenStream() (*Stream, error)
• type Stream
  • func (s *Stream) Close() error
  • func (s *Stream) CloseRead() error
  • func (s *Stream) CloseWrite() error
  • func (s *Stream) LocalAddr() net.Addr
  • func (s *Stream) Read(p []byte) (n int, err error)
  • func (s *Stream) RemoteAddr() net.Addr
  • func (s *Stream) SetDeadline(t time.Time) error
  • func (s *Stream) SetReadDeadline(t time.Time) error
  • func (s *Stream) SetWriteDeadline(t time.Time) error
  • func (s *Stream) Write(p []byte) (int, error)

Variables

var (
	ErrClosedConn       = errors.New("underlying connection was closed")
	ErrClosedStream     = errors.New("stream was gracefully closed")
	ErrPeerClosedStream = errors.New("peer closed stream gracefully")
	ErrPeerClosedConn   = errors.New("peer closed mux gracefully")
	ErrWriteClosed      = errors.New("write end of stream closed")
)

Errors relating to stream or mux shutdown.

Types

type Mux

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

A Mux multiplexes multiple duplex Streams onto a single net.Conn.

func Client

func Client(conn net.Conn, psk string) *Mux

Client creates and initializes a new client-side Mux on the provided conn. Client takes overship of the conn.

func Server

func Server(conn net.Conn, psk string) *Mux

Server creates and initializes a new server-side Mux on the provided conn. Server takes overship of the conn.

func (*Mux) AcceptStream

func (m *Mux) AcceptStream() (*Stream, error)

AcceptStream waits for and returns the next peer-initiated Stream.

func (*Mux) Close

func (m *Mux) Close() error

Close closes the underlying net.Conn.

func (*Mux) OpenStream

func (m *Mux) OpenStream() (*Stream, error)

OpenStream creates a new Stream.

type Stream

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

A Stream is a duplex connection multiplexed over a net.Conn. It implements the net.Conn interface.

func (*Stream) Close

func (s *Stream) Close() error

Close closes the Stream. The underlying connection is not closed.

func (*Stream) CloseRead

func (s *Stream) CloseRead() error

CloseRead shuts down the reading side of the stream. Most callers should just use Close.

func (*Stream) CloseWrite

func (s *Stream) CloseWrite() error

CloseWrite shuts down the writing side of the stream. Most callers should just use Close.

func (*Stream) LocalAddr

func (s *Stream) LocalAddr() net.Addr

LocalAddr returns the underlying connection's LocalAddr.

func (*Stream) Read

func (s *Stream) Read(p []byte) (n int, err error)

Read reads data from the Stream.

func (*Stream) RemoteAddr

func (s *Stream) RemoteAddr() net.Addr

RemoteAddr returns the underlying connection's RemoteAddr.

func (*Stream) SetDeadline

func (s *Stream) SetDeadline(t time.Time) error

SetDeadline sets the read and write deadlines associated with the Stream. It is equivalent to calling both SetReadDeadline and SetWriteDeadline.

This implementation does not entirely conform to the net.Conn interface: setting a new deadline does not affect pending Read or Write calls, only future calls.

func (*Stream) SetReadDeadline

func (s *Stream) SetReadDeadline(t time.Time) error

SetReadDeadline sets the read deadline associated with the Stream.

This implementation does not entirely conform to the net.Conn interface: setting a new deadline does not affect pending Read calls, only future calls.

func (*Stream) SetWriteDeadline

func (s *Stream) SetWriteDeadline(t time.Time) error

SetWriteDeadline sets the write deadline associated with the Stream.

This implementation does not entirely conform to the net.Conn interface: setting a new deadline does not affect pending Write calls, only future calls.

func (*Stream) Write

func (s *Stream) Write(p []byte) (int, error)

Write writes data to the Stream.