From 26306ffc42ba2c8ea3332d14f4e3379c7d855e1e Mon Sep 17 00:00:00 2001 From: Onur Gündüz Date: Thu, 8 Oct 2026 03:20:26 +0200 Subject: Fix example shutdown and document basic usage --- README.md | 79 +++++++++++++++++++++++++++++++++++++++- example_test.go | 111 +++++++++++++++++--------------------------------------- 2 files changed, 112 insertions(+), 78 deletions(-) diff --git a/README.md b/README.md index 8370c51..c4c22bd 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,84 @@ Simple binary messaging protocol with multiplexing support. -[![Go Reference](https://pkg.go.dev/badge/git.onurgunduz.com/muxer.svg)](https://pkg.go.dev/git.onurgunduz.com/muxer) +## Installation + +```sh +go get git.onurgunduz.com/muxer@latest +``` + +## Usage + +Go 1.25 or later is required. The examples below use these imports: + +```go +import ( + "bufio" + "bytes" + "fmt" + "log" + + "git.onurgunduz.com/muxer" +) +``` + +### Writing a message + +Create a writer around a `bufio.Writer`. This example writes to an in-memory buffer: + +```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, or copy it with `append([]byte(nil), received.Data...)` if it needs to be kept. + +### 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 diff --git a/example_test.go b/example_test.go index 7826e8f..fb9e9d0 100644 --- a/example_test.go +++ b/example_test.go @@ -4,102 +4,59 @@ import ( "fmt" "log" "net" - "time" "git.onurgunduz.com/muxer" ) func ExampleDial() { - s := &server{} - - time.AfterFunc(time.Millisecond*1, func() { - c, err := muxer.Dial("tcp", ":4242") - if err != nil { - log.Fatal(err) - } - - go func() { - msg := &muxer.Message{} - for { - err := c.ReadMessage(msg) - if err != nil { - log.Fatal(err) - return - } - - fmt.Printf("%d %d %s\n", msg.ID, msg.Type, msg.Data) - - s.close() - } - }() - - _, err = c.Send(muxer.NewMessage(42, 3, []byte("hi"))) - if err != nil { - log.Fatal(err) - } - }) - - if err := s.serve("tcp", ":4242"); err != nil { + listener, err := net.Listen("tcp", "127.0.0.1:0") + if err != nil { log.Fatal(err) } + defer listener.Close() - // output: - // 42 3 hi - // 112 5 hey -} - -type server struct { - listener net.Listener -} - -func (s *server) handle(conn net.Conn) { - defer conn.Close() - - c := muxer.NewConn(conn) - - msg := &muxer.Message{} - for { - err := c.ReadMessage(msg) + serverDone := make(chan error) + go func() { + conn, err := listener.Accept() if err != nil { - fmt.Printf("error: %v", err) + serverDone <- err return } - fmt.Printf("%d %d %s\n", msg.ID, msg.Type, msg.Data) - - _, err = c.Send(muxer.NewMessage(112, 5, []byte("hey"))) - if err != nil { - log.Fatal(err) + server := muxer.NewConn(conn) + var message muxer.Message + err = server.ReadMessage(&message) + if err == nil { + fmt.Printf("%d %d %s\n", message.ID, message.Type, message.Data) + _, err = server.Send(muxer.NewMessage(112, 5, []byte("hey"))) } - } -} + if closeErr := server.Close(); err == nil { + err = closeErr + } + serverDone <- err + }() -func (s *server) serve(network, address string) error { - l, err := net.Listen(network, address) + conn, err := muxer.Dial("tcp", listener.Addr().String()) if err != nil { - return err + log.Fatal(err) } + defer conn.Close() - s.listener = l - - for { - if s.listener == nil { - break - } - - c, err := l.Accept() - if err != nil { - continue - } + if _, err := conn.Send(muxer.NewMessage(42, 3, []byte("hi"))); err != nil { + log.Fatal(err) + } - go s.handle(c) + 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) - return nil -} + if err := <-serverDone; err != nil { + log.Fatal(err) + } -func (s *server) close() error { - err := s.listener.Close() - s.listener = nil - return err + // output: + // 42 3 hi + // 112 5 hey } -- cgit v1.3.1