aboutsummaryrefslogtreecommitdiff

muxer

Minimal binary messaging protocol.

Installation

go get git.onurgunduz.com/muxer@latest

Usage

Writing a message

Create a writer around a bufio.Writer.

var output bytes.Buffer
writer := muxer.NewWriter(bufio.NewWriter(&output))
message := muxer.NewMessage(42, 3, []byte("hello"))

if err := writer.WriteMessage(message); err != nil {
    log.Fatal(err)
}

WriteMessage flushes the buffer before returning. Pass multiple messages to write a batch.

Reading a message

Create a reader around any io.Reader. This reads the message written above:

reader := muxer.NewReader(&output)
var received muxer.Message

if err := reader.ReadMessage(&received); err != nil {
    log.Fatal(err)
}
fmt.Printf("%d %d %s\n", received.ID, received.Type, received.Data)

ReadMessage returns io.EOF when the source ends. The default buffer size is 4096 bytes; use NewReaderSize when messages need a larger buffer.

The returned Data slice shares the reader's storage. Process it before the next read.

Using a TCP connection

For a server listening on 127.0.0.1:4242 that speaks the muxer protocol and replies to each message:

conn, err := muxer.Dial("tcp", "127.0.0.1:4242")
if err != nil {
    log.Fatal(err)
}
defer conn.Close()

if _, err := conn.Send(muxer.NewMessage(42, 3, []byte("hello"))); err != nil {
    log.Fatal(err)
}

var response muxer.Message
if err := conn.ReadMessage(&response); err != nil {
    log.Fatal(err)
}
fmt.Printf("%d %d %s\n", response.ID, response.Type, response.Data)

NewConn wraps an accepted connection or another io.ReadWriteCloser.

Send can write several messages at once and can be called concurrently. Use one reading goroutine per connection; direct Reader and Writer calls are not safe for concurrent use.

Message structure

┌──────────────────────────────────────────────┐
│ length | channel ID × message type │ payload │
└──────────────────────────────────────────────┘
           └─ 60-bits   └─ 4-bits

Benchmarks

goos: darwin
goarch: arm64
pkg: git.onurgunduz.com/muxer
cpu: Apple M4 Pro
BenchmarkWriter_64B-12          98590449                12.05 ns/op     5309.66 MB/s           0 B/op          0 allocs/op
BenchmarkWriter_4KB-12          14346594                80.00 ns/op     51198.63 MB/s          0 B/op          0 allocs/op
BenchmarkWriter_1MB-12             74955             15931 ns/op        65819.47 MB/s         14 B/op          0 allocs/op
BenchmarkReader_64B-12          70582526                16.24 ns/op     3941.01 MB/s           0 B/op          0 allocs/op
BenchmarkReader_4KB-12          15629764                78.92 ns/op     51903.93 MB/s          0 B/op          0 allocs/op
BenchmarkReader_1MB-12             38365             31480 ns/op        33309.32 MB/s          0 B/op          0 allocs/op