zenoh-go

Pure Go implementation of the zenoh protocol. Zero cgo.

Status

Wire-compatible with Rust zenoh 1.x. Verified against zenohd 1.8.0.

Features

Transport

• Wire-compatible codec verified against Rust zenoh-codec (17 golden vectors)
• Init/Open handshake with version validation, QoS negotiation, compression negotiation, patch extension
• 16 QoS conduits (8 priorities x 2 reliability modes) with per-conduit sequence numbers
• Frame ext_qos extension carries priority on the wire, matching Rust
• RX sequence number validation with gap detection and uint32 wraparound
• LZ4 batch compression with AND-negotiated handshake (both sides must support)
• Message batching (multiple NetworkMessages per frame, 1ms flush interval)
• Fragmentation TX/RX with per-conduit reassembly buffers
• Auto-reconnection with exponential backoff and SN reset
• KeepAlive at lease/4 interval, lease timeout detection

Link Types

• TCP with 2-byte little-endian length-prefix framing
• TLS with mutual auth (client certs), custom CA, self-signed support
• QUIC over quic-go with stream-based framing
• WebSocket with binary messages via golang.org/x/net/websocket
• UDP unicast
• UDP multicast for peer-to-peer
• Multilink priority-to-link routing with narrowest-range-wins selection

Scouting

• Scout/Hello UDP multicast protocol (224.0.0.224:7446)
• Scout responder for router/peer advertisement
• Join message (MID 0x07) codec

Session

• Pub/sub through zenoh router (callback and channel APIs)
• Query/reply with SHM payload support on queries
• Admin space queries (@/**)
• Delete, DeclareKeyExpr, DeclareQuerier
• Liveliness tokens, attachments

Key Expressions

• Intersection and inclusion matching (150+ Rust test vectors)
• Canonization with validation (transforms and rejects, matching Rust autocanonize)
• Compiled key expressions via NewValidated() (Rust TryFrom equivalent)
• DSL wildcards ($*), verbatim chunks (@), multi-level wildcards (**)
• RelationTo returning Disjoint/Intersects/Includes/Equals
• NonWildPrefixLen matching Rust get_nonwild_prefix

Shared Memory

• Byte-exact ChunkHeaderType layout matching Rust stabby (32 bytes, 7 fields)
• Refcount protocol — sender increments before send, receiver inherits, decrement on release
• Watchdog confirmator (50ms) — confirms watchdog bits for held buffers
• Watchdog validator (100ms) — invalidates unconfirmed buffers
• Metadata storage with generation tracking and pooled reclaim
• Auth challenge handshake (InitSyn/InitAck/OpenSyn/OpenAck with nonce verification)
• Sliced codec (kind=0 raw, kind=1 shm_ptr) in Put, Reply, Error, and Query
• Orphan segment cleanup scans /dev/shm/*.zenoh on startup
• Three allocator backends: BumpAllocator, BuddyAllocator (power-of-2 split/merge), HeapAllocator (largest-fit with defragment)
• POSIX SHM: macOS via raw syscalls (no cgo), Linux via /dev/shm

Build

• Pure Go — zero cgo, zero C dependencies
• Debug asserts with build-tag gating (-tags release strips them)

Quick Start

Subscriber

package main

import (
    "fmt"
    "git.mere.cloud/bngreer/zenoh-go/zenoh"
)

func main() {
    sess, _ := zenoh.Open(zenoh.Config{
        Connect: []string{"tcp/localhost:7447"},
    })
    defer sess.Close()

    sess.DeclareSubscriber("demo/**", func(s zenoh.Sample) {
        fmt.Printf("%s: %s\n", s.KeyExpr, string(s.Payload))
    })

    select {} // block forever
}

Publisher

sess, _ := zenoh.Open(zenoh.Config{
    Connect: []string{"tcp/localhost:7447"},
})
defer sess.Close()

pub, _ := sess.DeclarePublisher("demo/hello")
pub.Put([]byte("hello from go"))

Query/Reply

// Queryable side
sess.DeclareQueryable("demo/query", func(q zenoh.Query) {
    q.Reply([]byte("response data"))
})

// Querier side
samples, _ := sess.Get("demo/query", "")
for _, s := range samples {
    fmt.Println(string(s.Payload))
}

Building

go test ./...                          # all tests (asserts active)
go test -tags release ./...            # release mode (asserts stripped)
go test -tags integration ./integration/ # requires zenohd on localhost:7447

Requires zenohd for integration tests:

cargo install zenohd
zenohd --no-multicast-scouting

# For SHM support:
cargo install zenohd --features shared-memory

Package Structure

zenoh/          Public API (Open, Config)
session/        Pub/sub routing, queryables, resource mapping, SHM resolution
transport/      Handshake, TX/RX loops, 16-conduit QoS, batching, compression, multilink
codec/          Wire protocol encode/decode (all transport + network + scouting messages)
keyexpr/        Key expression matching (*, **, $*, @) with Rust test vectors
link/           TCP, TLS, QUIC, WebSocket, UDP, multicast links + scouting
shm/            Shared memory (auth, watchdog, metadata, reader, 3 allocators, cleanup)
bytes/          Byte containers, readers, writers
collections/    Ring, FIFO, LIFO, maps
datastruct/     String vectors, lists, arrays
encoding/       Encoding types and schemas
endpoint/       Locator/endpoint parsing
iobuf/          I/O buffer primitives
integration/    Integration tests against zenohd
testdata/       Golden test vectors (Rust-generated)

License

This project is licensed under:

-- Mine -- MINE MINE MINE MINE MINE -- ABSOLUTELY NO AI TRAINING -

** Free for personal use **

if your a real human being and want a license please contact ben@mere.dev