gombus

README

gombus

A NATS-style distributed message queue built on gosocketio, with a Raft (hashicorp/raft) control plane for cluster mode.

Features

• Subject-based pub/sub with wildcards (orders.>, orders.eu.*) and queue groups (loadbalance / broadcast group delivery modes).
• Request/reply over the same socket.
• Streams (JetStream-style): durable per-subject storage with pull/push consumers, explicit acks, and cursor replication.
• Clustering: subscriptions, group-delivery rules, stream metadata, and consumer cursors replicated across nodes via a single Raft control-plane group; messages are forwarded node-to-node in real time.

Layout

cmd/broker        broker binary (single node or raft cluster)
internal/protocol wire protocol: events, messages, cluster state/commands
internal/broker   connection registry, dispatcher, cluster FSM application
internal/cluster  raft control plane (FSM), peer forwarding, leader forwarding
internal/stream   streams, consumers, cursors, segment storage
internal/client   Go client library
docs/             technical design

Quickstart (single node)

make build
./bin/broker -node-id=node-1 -addr=:8080 -data=./data -control-token=secret

The broker listens for Socket.IO on /socket.io; the control namespace /control is protected by the token. Run an example:

go run ./examples/pubsub &
go run ./examples/queue-group &

Cluster mode (3 nodes)

Control state (subscriptions, rules, stream/consumer metadata, cursors) is replicated through a single global Raft group; the FSM image is applied to every node's local registry, so a publish on any node is delivered to consumers on every node. A subscribe on a follower is proposed to the leader via a node-to-node cluster.command; delivery of a message to a remote socket travels over a cluster.forward peer connection.

# n1
./bin/broker -node-id=n1 -addr=:8081 -raft-addr=:9091 \
  -raft-peers=n1=127.0.0.1:9091,n2=127.0.0.1:9092,n3=127.0.0.1:9093 \
  -cluster=n1=http://127.0.0.1:8081/socket.io,n2=http://127.0.0.1:8082/socket.io,n3=http://127.0.0.1:8083/socket.io \
  -control-token=secret -data=./data/n1 -bootstrap &

# n2, n3: same -raft-peers / -cluster / -control-token, own -raft-addr/-addr/-data, also -bootstrap

Or with docker compose:

GOMBUS_CONTROL_TOKEN=secret make cluster
# n1: http://localhost:8081, n2: 8082, n3: 8083

Flags:

Flag	Meaning
-addr	HTTP listen address (default :8080)
-node-id	broker node id (default: hostname)
-data	stream storage directory
-control-token	token required on /control (empty = open)
-raft-addr	raft transport bind address (may be :port); the address advertised to peers is this node's -raft-peers entry. Empty = single node
-raft-peers	nodeID=raftAddr pairs of the fixed cluster
-cluster	nodeID=brokerURL pairs used for node-to-node forwarding
-bootstrap	seed the raft voter configuration from -raft-peers (all nodes of a new cluster)

Every node of a new fixed cluster must start with -bootstrap; the cluster writes the identical voter configuration on all nodes, so the redundant writes are benign.

Current milestone limits (M4)

• Streams are node-local. Stream data lives on the node that created it; stream/consumer metadata and cursors are replicated via the control plane. Cross-node stream access (each stream backed by its own raft group, dragonboat) is the next milestone. Test and operate streams on the node where they are created.
• Control state is in-memory raft. Raft logs/snapshots use in-memory stores: a full cluster restart re-bootstraps control state from -raft-peers. Durable raft stores (BoltDB) are planned.
• Fixed membership. Membership changes (joint consensus) are not implemented; a cluster is fixed at first start.

Testing

make test    # go test ./...
make race    # full suite under the race detector

The 3-node consistency suite (internal/cluster/cluster_test.go) covers subscription replication and cross-node delivery, queue-group load balancing across nodes, cursor replication, and leader failover.

Design

See docs/TECHNICAL_DESIGN.md for the full design and the milestone roadmap.