Simple Stream Multiplexing for golang
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.

README.md

smux

GoDoc MIT licensed Build Status Go Report Card Coverage Statusd

smux

Introduction

Smux ( Simple MUltipleXing) is a multiplexing library for Golang. It relies on an underlying connection to provide reliability and ordering, such as TCP or KCP, and provides stream-oriented multiplexing. The original intention of this library is to power the connection management for kcp-go.

Features

  1. Tiny, less than 600 LOC.
  2. Token bucket controlled receiving, which provides smoother bandwidth graph(see picture below).
  3. Session-wide receive buffer, shared among streams, tightly controlled overall memory usage.
  4. Minimized header(8Bytes), maximized payload.
  5. Well-tested on millions of devices in kcptun.

smooth bandwidth curve

Documentation

For complete documentation, see the associated Godoc.

Specification

VERSION(1B) | CMD(1B) | LENGTH(2B) | STREAMID(4B) | DATA(LENGTH)  

Usage

The API of smux are mostly taken from yamux

func client() {
    // Get a TCP connection
    conn, err := net.Dial(...)
    if err != nil {
        panic(err)
    }

    // Setup client side of smux
    session, err := smux.Client(conn, nil)
    if err != nil {
        panic(err)
    }

    // Open a new stream
    stream, err := session.OpenStream()
    if err != nil {
        panic(err)
    }

    // Stream implements io.ReadWriteCloser
    stream.Write([]byte("ping"))
}

func server() {
    // Accept a TCP connection
    conn, err := listener.Accept()
    if err != nil {
        panic(err)
    }

    // Setup server side of smux
    session, err := smux.Server(conn, nil)
    if err != nil {
        panic(err)
    }

    // Accept a stream
    stream, err := session.AcceptStream()
    if err != nil {
        panic(err)
    }

    // Listen for a message
    buf := make([]byte, 4)
    stream.Read(buf)
}

Status

Stable