1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
|
# muxer
Minimal binary messaging protocol.
## Installation
```sh
go get git.onurgunduz.com/muxer@latest
```
## Usage
### Writing a message
Create a writer around a `bufio.Writer`.
```go
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:
```go
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:
```go
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
```
|