aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authortetsuo <ogunduz@gmail.com>2025-08-19 00:59:28 +0200
committertetsuo <ogunduz@gmail.com>2025-08-19 00:59:41 +0200
commitdcbed031c632426444df6403ee48899f7ed104d4 (patch)
treec6bd1bc15d7f25750bc6144c51d7235b5a48d3de
parentcac67d6ca1e144ef12607794622a6710a395a2b0 (diff)
downloadmuxer-dcbed031c632426444df6403ee48899f7ed104d4.tar.gz
muxer-dcbed031c632426444df6403ee48899f7ed104d4.zip
Update README
-rw-r--r--README.md153
1 files changed, 110 insertions, 43 deletions
diff --git a/README.md b/README.md
index 99833a9..f1961b2 100644
--- a/README.md
+++ b/README.md
@@ -1,10 +1,8 @@
# binproto
-`binproto` is a lightweight Go library designed to facilitate low-level binary protocol communication. It enables efficient, multiplexed messaging, making it well-suited for network applications requiring reliable and fast binary data exchange.
+`binproto` provides binary message framing using a length-prefixed format and supports multiplexed streams.
-## Installation
-
-Install `binproto` by running:
+## Install
```sh
go get github.com/tetsuo/binproto
@@ -12,78 +10,147 @@ go get github.com/tetsuo/binproto
## Usage
-Here’s a basic example of how to use `binproto` for a simple client-server communication setup:
+To start exchanging messages with binproto, simply wrap a `net.Conn` with a `binproto.Conn` instance.
+
+Then, once connected, use `ReadMessage()` to read incoming messages and `Send()` to send new ones over the network.
+
+#### Server:
```go
package main
import (
+ "fmt"
"log"
"net"
+
"github.com/tetsuo/binproto"
)
func main() {
- // Create a new server instance
- server := &Server{}
-
- // Start the server
- go func() {
- if err := server.Start(":4242"); err != nil {
- log.Fatal(err)
- }
- }()
-
- // Connect a client
- client, err := binproto.Dial("tcp", ":4242")
- if err != nil {
+ s := &server{}
+ if err := s.serve("tcp", ":4242"); err != nil {
log.Fatal(err)
}
+}
- // Send a message from the client
- client.Send(binproto.NewMessage(1, 1, []byte("Hello Server")))
-
- // Close the client
- client.Close()
+type server struct {
+ listener net.Listener
}
-```
-### Server Code
+// handle manages an individual client connection.
+// It reads each message, prints its content, and responds with a simple reply.
+func (s *server) handle(conn net.Conn) {
+ defer conn.Close()
+ c := binproto.NewConn(conn)
-To set up a server using `binproto`, create a handler to process incoming messages.
+ for {
+ msg, err := c.ReadMessage()
+ if err != nil {
+ fmt.Printf("error: %v", err)
+ return
+ }
+ fmt.Printf("%d %d %s\n", msg.ID, msg.Channel, msg.Data)
-```go
-type Server struct {
- listener net.Listener
+ _, err = c.Send(binproto.NewMessage(112, 5, []byte("hello")))
+ if err != nil {
+ log.Fatal(err)
+ }
+ }
}
-func (s *Server) Start(addr string) error {
- l, err := net.Listen("tcp", addr)
+// serve starts listening for incoming TCP connections.
+// For each new connection, it launches handle in a separate goroutine.
+func (s *server) serve(network, address string) error {
+ l, err := net.Listen(network, address)
if err != nil {
return err
}
s.listener = l
+
for {
- conn, err := s.listener.Accept()
+ if s.listener == nil {
+ break
+ }
+ c, err := l.Accept()
if err != nil {
- return err
+ continue
}
- go s.handleConnection(conn)
+ go s.handle(c)
}
+ return nil
}
-func (s *Server) handleConnection(conn net.Conn) {
- c := binproto.NewConn(conn)
- for {
- msg, err := c.ReadMessage()
- if err != nil {
- return
+// close cleanly shuts down the server listener.
+func (s *server) close() error {
+ err := s.listener.Close()
+ s.listener = nil
+ return err
+}
+```
+
+#### Client:
+
+```go
+package main
+
+import (
+ "fmt"
+ "log"
+
+ "github.com/tetsuo/binproto"
+)
+
+func main() {
+ // Connect to the server on localhost:4242 using binproto
+ c, err := binproto.Dial("tcp", ":4242")
+ if err != nil {
+ log.Fatal(err)
+ }
+
+ // Start a goroutine to read and print incoming messages from the server
+ go func() {
+ for {
+ msg, err := c.ReadMessage()
+ if err != nil {
+ log.Fatal(err)
+ return
+ }
+
+ fmt.Printf("%d %d %s\n", msg.ID, msg.Channel, msg.Data)
}
- log.Printf("Received message: %s", msg.Data)
+ }()
+
+ // Send a message to the server: ID=42, Channel=3, Data="hi"
+ _, err = c.Send(binproto.NewMessage(42, 3, []byte("hi")))
+ if err != nil {
+ log.Fatal(err)
}
+
+ select {} // Keeps main from exiting immediately
}
```
-## License
+## Message structure
+
+Every message is encoded with a 64-bit header: a length prefix followed by a channel ID and type.
+
+```
+╔──────────────────────────────────────────────╗
+│ length | channel ID × channel type │ payload │
+╚──────────────────────────────────────────────╝
+ └─ 60-bits └─ 4-bits
+```
+
+* **Channel ID (first 60 bits)**: Identifies the specific channel for the message.
+* **Channel Type (last 4 bits)**: Specifies the type of data in the message.
+
+## Encryption
+
+binproto itself doesn't provide encryption. However, encryption can be added by using Go libraries that act as drop-in replacements for `net`, for example by wrapping your connections with an implementation of the [NOISE protocol](http://www.noiseprotocol.org/).
+
+## Configure buffer size
+
+binproto operates with a default internal buffer size of 4096 bytes, meaning data is processed as long as it meets or exceeds this buffer size, which is an effective default for many applications. This value can be adjusted to better suit protocols that use larger or smaller data chunks, optimizing performance as needed.
-MIT License. See [LICENSE](LICENSE) for details.
+> 📄 **For more details, see the API documentation at [pkg.go.dev](https://pkg.go.dev/github.com/tetsuo/binproto).**