aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorOnur Gündüz <ogunduz@gmail.com>2026-10-08 03:20:26 +0200
committerOnur Gündüz <ogunduz@gmail.com>2026-10-08 03:20:26 +0200
commit26306ffc42ba2c8ea3332d14f4e3379c7d855e1e (patch)
treea8c458dc13bb09e20633d986429b841cbc35fb31
parentd0aa2923afcb73a721d6ea135809d1d6ece250ad (diff)
downloadmuxer-26306ffc42ba2c8ea3332d14f4e3379c7d855e1e.tar.gz
muxer-26306ffc42ba2c8ea3332d14f4e3379c7d855e1e.zip
Fix example shutdown and document basic usage
-rw-r--r--README.md79
-rw-r--r--example_test.go111
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
}