From d2ae1381c76f53c14fe4e6e4d9b557887cd93187 Mon Sep 17 00:00:00 2001 From: Onur Gündüz Date: Thu, 8 Oct 2026 02:47:42 +0200 Subject: Update Go module path and source imports --- README.md | 6 +++--- benchmark_test.go | 16 +++++++-------- binproto.go | 60 ------------------------------------------------------- example_test.go | 16 +++++++-------- go.mod | 2 +- message.go | 13 +++++++----- muxer.go | 59 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ reader.go | 22 ++++++++++---------- reader_test.go | 38 +++++++++++++++++------------------ writer.go | 8 +++++--- writer_test.go | 24 +++++++++++----------- 11 files changed, 135 insertions(+), 129 deletions(-) delete mode 100644 binproto.go create mode 100644 muxer.go diff --git a/README.md b/README.md index 5c055f3..8370c51 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,8 @@ -# binproto +# muxer Simple binary messaging protocol with multiplexing support. -[![Go Reference](https://pkg.go.dev/badge/github.com/tetsuo/binproto.svg)](https://pkg.go.dev/github.com/tetsuo/binproto) +[![Go Reference](https://pkg.go.dev/badge/git.onurgunduz.com/muxer.svg)](https://pkg.go.dev/git.onurgunduz.com/muxer) ## Message structure @@ -18,7 +18,7 @@ Simple binary messaging protocol with multiplexing support. ``` goos: darwin goarch: arm64 -pkg: github.com/tetsuo/binproto +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 diff --git a/benchmark_test.go b/benchmark_test.go index 8ad3303..29ad211 100644 --- a/benchmark_test.go +++ b/benchmark_test.go @@ -1,11 +1,11 @@ -package binproto_test +package muxer_test import ( "bufio" "bytes" "testing" - "github.com/tetsuo/binproto" + "git.onurgunduz.com/muxer" ) func BenchmarkWriter_64B(b *testing.B) { @@ -22,11 +22,11 @@ func BenchmarkWriter_1MB(b *testing.B) { func benchWriter(b *testing.B, payloadSize int) { payload := make([]byte, payloadSize) - msg := binproto.NewMessage(1, 'X', payload) + msg := muxer.NewMessage(1, 'X', payload) buf := new(bytes.Buffer) bw := bufio.NewWriter(buf) - w := binproto.NewWriter(bw) + w := muxer.NewWriter(bw) b.SetBytes(int64(payloadSize)) b.ReportAllocs() b.ResetTimer() @@ -54,10 +54,10 @@ func BenchmarkReader_1MB(b *testing.B) { func benchReader(b *testing.B, payloadSize int) { // Encode message once payload := make([]byte, payloadSize) - msg := binproto.NewMessage(1, 'X', payload) + msg := muxer.NewMessage(1, 'X', payload) buf := new(bytes.Buffer) bw := bufio.NewWriter(buf) - w := binproto.NewWriter(bw) + w := muxer.NewWriter(bw) w.WriteMessage(msg) bw.Flush() encoded := buf.Bytes() @@ -69,13 +69,13 @@ func benchReader(b *testing.B, payloadSize int) { } source := &repeatReader{data: encoded} - reader := binproto.NewReaderSize(source, bufSize) + reader := muxer.NewReaderSize(source, bufSize) b.SetBytes(int64(payloadSize)) b.ReportAllocs() b.ResetTimer() - m := &binproto.Message{} + m := &muxer.Message{} for i := 0; i < b.N; i++ { err := reader.ReadMessage(m) diff --git a/binproto.go b/binproto.go deleted file mode 100644 index aab7179..0000000 --- a/binproto.go +++ /dev/null @@ -1,60 +0,0 @@ -// Package binproto implements low-level support for binary-based two-way -// communication protocols. -package binproto - -import ( - "bufio" - "io" - "net" - "net/textproto" -) - -// A Conn represents a binary network protocol connection. -// It consists of a Reader and Writer to manage I/O -// and a Pipeline (which is borrowed from textproto) to sequence -// concurrent requests on the connection. -type Conn struct { - Reader - Writer - textproto.Pipeline - conn io.ReadWriteCloser -} - -// NewConn returns a new Conn using conn for I/O. -func NewConn(conn io.ReadWriteCloser) *Conn { - r, w := NewReader(bufio.NewReader(conn)), NewWriter(bufio.NewWriter(conn)) - return &Conn{ - Reader: *r, - Writer: *w, - conn: conn, - } -} - -// Send is a convenience method that sends a variable number of messages -// after waiting its turn in the pipeline. -// Send returns the id of the command, for use with StartResponse and EndResponse. -func (c *Conn) Send(m ...*Message) (id uint, err error) { - id = c.Next() - c.StartRequest(id) - err = c.WriteMessage(m...) - c.EndRequest(id) - if err != nil { - return 0, err - } - return id, nil -} - -// Close closes the connection. -func (c *Conn) Close() error { - return c.conn.Close() -} - -// Dial connects to the given address on the given network using net.Dial -// and then returns a new Conn for the connection. -func Dial(network, addr string) (*Conn, error) { - c, err := net.Dial(network, addr) - if err != nil { - return nil, err - } - return NewConn(c), nil -} diff --git a/example_test.go b/example_test.go index 0547111..7826e8f 100644 --- a/example_test.go +++ b/example_test.go @@ -1,4 +1,4 @@ -package binproto_test +package muxer_test import ( "fmt" @@ -6,20 +6,20 @@ import ( "net" "time" - "github.com/tetsuo/binproto" + "git.onurgunduz.com/muxer" ) func ExampleDial() { s := &server{} time.AfterFunc(time.Millisecond*1, func() { - c, err := binproto.Dial("tcp", ":4242") + c, err := muxer.Dial("tcp", ":4242") if err != nil { log.Fatal(err) } go func() { - msg := &binproto.Message{} + msg := &muxer.Message{} for { err := c.ReadMessage(msg) if err != nil { @@ -33,7 +33,7 @@ func ExampleDial() { } }() - _, err = c.Send(binproto.NewMessage(42, 3, []byte("hi"))) + _, err = c.Send(muxer.NewMessage(42, 3, []byte("hi"))) if err != nil { log.Fatal(err) } @@ -55,9 +55,9 @@ type server struct { func (s *server) handle(conn net.Conn) { defer conn.Close() - c := binproto.NewConn(conn) + c := muxer.NewConn(conn) - msg := &binproto.Message{} + msg := &muxer.Message{} for { err := c.ReadMessage(msg) if err != nil { @@ -67,7 +67,7 @@ func (s *server) handle(conn net.Conn) { fmt.Printf("%d %d %s\n", msg.ID, msg.Type, msg.Data) - _, err = c.Send(binproto.NewMessage(112, 5, []byte("hey"))) + _, err = c.Send(muxer.NewMessage(112, 5, []byte("hey"))) if err != nil { log.Fatal(err) } diff --git a/go.mod b/go.mod index 384e0f2..4ae1362 100644 --- a/go.mod +++ b/go.mod @@ -1,4 +1,4 @@ -module github.com/tetsuo/binproto +module git.onurgunduz.com/muxer go 1.17 diff --git a/message.go b/message.go index fad8976..bc0a6e0 100644 --- a/message.go +++ b/message.go @@ -1,10 +1,13 @@ -package binproto +package muxer -// A Message represents a single binproto message. +// Message represents a single protocol message with a channel ID, type, and payload. // -// Each message starts with an header which is a varint encoded -// unsigned 64-bit integer which consists of a channel ID (first 60-bits) and -// a message type (last 4-bits), the rest of the message is payload. +// ┌──────────────────────────────────────────────┐ +// │ length | channel ID × message type │ payload │ +// └──────────────────────────────────────────────┘ +// +// Each message starts with a varint encoded unsigned 64-bit integer which consists of +// a channel ID (first 60-bits) and a message type (last 4-bits) followed by the payload. type Message struct { ID uint64 Type uint8 diff --git a/muxer.go b/muxer.go new file mode 100644 index 0000000..0e46c01 --- /dev/null +++ b/muxer.go @@ -0,0 +1,59 @@ +// Package muxer provides buffered message multiplexing via length-prefix framing. +package muxer + +import ( + "bufio" + "io" + "net" + "net/textproto" +) + +// Conn combines a Reader and Writer to manage I/O and sequence concurrent requests +// on a connection. +type Conn struct { + Reader + Writer + textproto.Pipeline // borrowed from textproto to manage request/response sequencing + + conn io.ReadWriteCloser +} + +// NewConn returns a new Conn using conn for I/O. +func NewConn(conn io.ReadWriteCloser) *Conn { + r, w := NewReader(bufio.NewReader(conn)), NewWriter(bufio.NewWriter(conn)) + return &Conn{ + Reader: *r, + Writer: *w, + conn: conn, + } +} + +// Send sends a variable number of messages over the connection after waiting +// its turn in the pipeline. Unlike WriteMessage, it is safe to call this method +// concurrently from multiple goroutines. +// Returns the id of the command for use with StartResponse and EndResponse. +func (c *Conn) Send(m ...*Message) (id uint, err error) { + id = c.Next() + c.StartRequest(id) + err = c.WriteMessage(m...) + c.EndRequest(id) + if err != nil { + return 0, err + } + return id, nil +} + +// Close closes the underlying connection. +func (c *Conn) Close() error { + return c.conn.Close() +} + +// Dial connects to the given address on the given network using net.Dial +// and returns a new Conn for the connection. +func Dial(network, addr string) (*Conn, error) { + c, err := net.Dial(network, addr) + if err != nil { + return nil, err + } + return NewConn(c), nil +} diff --git a/reader.go b/reader.go index c862fcd..528fff1 100644 --- a/reader.go +++ b/reader.go @@ -1,12 +1,14 @@ -package binproto +package muxer import ( "errors" "io" ) -// A Reader implements convenience methods for reading requests -// or responses from a binary protocol network connection. +// Reader implements a buffered message reader for the muxer protocol. +// It reads and decodes messages from an underlying io.Reader, handling buffering, +// message framing, and varint-based length encoding. Reader is not safe for +// concurrent use by multiple goroutines. type Reader struct { rd io.Reader r, w int @@ -33,13 +35,14 @@ const ( ) var ( - ErrMessageSizeExceeded = errors.New("binproto: message too big") - ErrMessageMalformed = errors.New("binproto: message malformed") + ErrMessageSizeExceeded = errors.New("muxer: message too big") + ErrMessageMalformed = errors.New("muxer: message malformed") ) // NewReader returns a new Reader reading from r. // // By default, a Reader allocates 4096 bytes for its internal buffer. +// Use NewReaderSize to specify a different buffer size. func NewReader(rd io.Reader) *Reader { return NewReaderSize(rd, defaultBufSize) } @@ -64,13 +67,13 @@ func (b *Reader) fill() { length := len(b.buf) if b.w >= length { - panic("binproto: tried to fill full buffer") + panic("muxer: tried to fill full buffer") } for i := maxConsecutiveEmptyReads; i > 0; i-- { n, err := b.rd.Read(b.buf[b.w:]) if n < 0 { - panic("binproto: reader returned negative count from Read") + panic("muxer: reader returned negative count from Read") } b.w += n if err != nil { @@ -92,7 +95,7 @@ func (b *Reader) fill() { b.err = io.ErrNoProgress } -// ReadMessage reads a single message from r. +// ReadMessage reads a single message from r into the provided Message struct. func (b *Reader) ReadMessage(message *Message) (err error) { for { if b.err != nil { @@ -151,8 +154,7 @@ func (b *Reader) ReadMessage(message *Message) (err error) { return } -// Reset resets this Reader with the new source r, using -// the existing buffer. +// Reset resets this Reader with the new source r, using the existing buffer. func (b *Reader) Reset(r io.Reader) { if b.buf == nil { b.buf = make([]byte, defaultBufSize) diff --git a/reader_test.go b/reader_test.go index 31825a6..f313d34 100644 --- a/reader_test.go +++ b/reader_test.go @@ -1,4 +1,4 @@ -package binproto_test +package muxer_test import ( "bytes" @@ -12,7 +12,7 @@ import ( "time" "github.com/stretchr/testify/assert" - "github.com/tetsuo/binproto" + "git.onurgunduz.com/muxer" ) type testCase struct { @@ -424,12 +424,12 @@ func (r *testReader) Read(p []byte) (n int, err error) { return len(b), nil } -func reader(q [][]byte, size int) *binproto.Reader { - return binproto.NewReaderSize(&testReader{q: q}, size) +func reader(q [][]byte, size int) *muxer.Reader { + return muxer.NewReaderSize(&testReader{q: q}, size) } -func newMessage(id uint64, ch uint8, l int) *binproto.Message { - return &binproto.Message{ +func newMessage(id uint64, ch uint8, l int) *muxer.Message { + return &muxer.Message{ ID: id, Type: ch, Data: []byte(fill(l)), @@ -460,14 +460,14 @@ func runTest(t *testing.T, tt testCase) { if len(tt.expect) < 1 { panic("must expect a result") } - m := &binproto.Message{} + m := &muxer.Message{} for _, v := range tt.expect { err := r.ReadMessage(m) if expectedErr, ok := v.(error); ok { assert.EqualError(t, err, expectedErr.Error(), tt.desc) } else { assert.Nil(t, err) - if expectedMessage, ok := v.(*binproto.Message); ok { + if expectedMessage, ok := v.(*muxer.Message); ok { assert.EqualValues(t, expectedMessage, m, tt.desc) } else { t.Fail() @@ -617,7 +617,7 @@ func encodingLength(i uint64) int { func send(id uint64, ch uint8, data []byte) []byte { if id > maxID { - panic("binproto: ID too big") + panic("muxer: ID too big") } header := id<<4 | uint64(ch) length := len(data) + encodingLength(header) @@ -630,9 +630,9 @@ func send(id uint64, ch uint8, data []byte) []byte { func TestReaderReset(t *testing.T) { initialData := newBytes(42, 3, 5, 0, 0) - r := binproto.NewReaderSize(bytes.NewReader(initialData), 64) + r := muxer.NewReaderSize(bytes.NewReader(initialData), 64) - m := &binproto.Message{} + m := &muxer.Message{} err := r.ReadMessage(m) assert.NoError(t, err) assert.Equal(t, uint64(42), m.ID) @@ -648,11 +648,11 @@ func TestReaderReset(t *testing.T) { } func TestReaderResetNilBuffer(t *testing.T) { - r := &binproto.Reader{} + r := &muxer.Reader{} data := newBytes(42, 3, 5, 0, 0) r.Reset(bytes.NewReader(data)) - m := &binproto.Message{} + m := &muxer.Message{} err := r.ReadMessage(m) assert.NoError(t, err) assert.Equal(t, uint64(42), m.ID) @@ -668,10 +668,10 @@ func TestReadVarintOverflow(t *testing.T) { buf[i] = 0xFF // continuation bit set } - r := binproto.NewReaderSize(bytes.NewReader(buf), 64) - m := &binproto.Message{} + r := muxer.NewReaderSize(bytes.NewReader(buf), 64) + m := &muxer.Message{} err := r.ReadMessage(m) - assert.Equal(t, binproto.ErrMessageMalformed, err) + assert.Equal(t, muxer.ErrMessageMalformed, err) } // Test message size exceeding max @@ -683,8 +683,8 @@ func TestMessageSizeExceeded(t *testing.T) { header := uint64(42<<4 | 3) n += binary.PutUvarint(buf[n:], header) - r := binproto.NewReaderSize(bytes.NewReader(buf[:n]), 4096) - m := &binproto.Message{} + r := muxer.NewReaderSize(bytes.NewReader(buf[:n]), 4096) + m := &muxer.Message{} err := r.ReadMessage(m) - assert.Equal(t, binproto.ErrMessageSizeExceeded, err) + assert.Equal(t, muxer.ErrMessageSizeExceeded, err) } diff --git a/writer.go b/writer.go index 7e1947a..3980f03 100644 --- a/writer.go +++ b/writer.go @@ -1,12 +1,14 @@ -package binproto +package muxer import ( "bufio" "encoding/binary" ) -// A Writer implements convenience methods for writing -// requests or responses to a binary protocol network connection. +// Writer implements a buffered message writer for the muxer protocol. +// It encodes and writes messages to an underlying bufio.Writer, handling +// message framing and varint-based length encoding. Writer is not safe for +// concurrent use by multiple goroutines. type Writer struct { wd *bufio.Writer scratch [20]byte diff --git a/writer_test.go b/writer_test.go index 555743d..8fc8995 100644 --- a/writer_test.go +++ b/writer_test.go @@ -1,4 +1,4 @@ -package binproto_test +package muxer_test import ( "bufio" @@ -8,12 +8,12 @@ import ( "testing" "github.com/stretchr/testify/assert" - "github.com/tetsuo/binproto" + "git.onurgunduz.com/muxer" ) func TestSend(t *testing.T) { var buf bytes.Buffer - w := binproto.NewWriter(bufio.NewWriter(&buf)) + w := muxer.NewWriter(bufio.NewWriter(&buf)) err := w.WriteMessage(newMessage(42, 3, 2)) if s := buf.String(); s != "\x04\xa3\x05ab" || err != nil { t.Fatalf("s=%q; err=%s", s, err) @@ -22,7 +22,7 @@ func TestSend(t *testing.T) { func TestSendBatch(t *testing.T) { var buf bytes.Buffer - w := binproto.NewWriter(bufio.NewWriter(&buf)) + w := muxer.NewWriter(bufio.NewWriter(&buf)) msg := newMessage(42, 3, 2) err := w.WriteMessage(msg, msg) if s := buf.String(); s != "\x04\xa3\x05ab\x04\xa3\x05ab" || err != nil { @@ -33,14 +33,14 @@ func TestSendBatch(t *testing.T) { func TestWriteMessageNilData(t *testing.T) { buf := new(bytes.Buffer) bw := bufio.NewWriter(buf) - w := binproto.NewWriter(bw) + w := muxer.NewWriter(bw) - msg := binproto.NewMessage(100, 5, nil) + msg := muxer.NewMessage(100, 5, nil) err := w.WriteMessage(msg) assert.NoError(t, err) - r := binproto.NewReaderSize(bytes.NewReader(buf.Bytes()), 64) - m := &binproto.Message{} + r := muxer.NewReaderSize(bytes.NewReader(buf.Bytes()), 64) + m := &muxer.Message{} err = r.ReadMessage(m) assert.NoError(t, err) assert.Equal(t, uint64(100), m.ID) @@ -59,7 +59,7 @@ func TestConnClose(t *testing.T) { data := []byte{0x04, 0xa3, 0x05, 'a', 'b'} buf.Write(data) - conn := binproto.NewConn(struct { + conn := muxer.NewConn(struct { io.Reader io.Writer io.Closer @@ -92,15 +92,15 @@ func (f *failWriter) Write(p []byte) (int, error) { func TestSendWriteError(t *testing.T) { fw := &failWriter{Buffer: &bytes.Buffer{}} - conn := binproto.NewConn(fw) + conn := muxer.NewConn(fw) - msg := binproto.NewMessage(42, 3, []byte("test")) + msg := muxer.NewMessage(42, 3, []byte("test")) _, err := conn.Send(msg) assert.Error(t, err) assert.Contains(t, err.Error(), "write failed") } func TestDialError(t *testing.T) { - _, err := binproto.Dial("tcp", "invalid:99999999") + _, err := muxer.Dial("tcp", "invalid:99999999") assert.Error(t, err) } -- cgit v1.3.1