StreamHive is a Go library and CLI for experimenting with distributed, content-addressed storage. It ships a production-minded TCP transport (context-aware listen/dial, TLS hooks, framing, metrics, limits), a length-prefixed wire format (SHV1), a typed blob replication protocol, memory and file-backed blob stores, and operational endpoints (/livez, /readyz, /peers, /metrics, /metrics/prometheus).
Semver: public API versions are tracked in CHANGELOG.md and internal/version/version.go (currently v0.6.0, pre-1.0).
Status: networking, framing, local storage, content-addressed blob keys, static-peer replication, startup and periodic anti-entropy sync, durable stores, self-repair demos, and Prometheus metrics are implemented. storage.FileStore provides durable local blobs for library users and CLI receivers via -store-dir. Conflict resolution and global discovery are not implemented. See docs/ARCHITECTURE.md.
- Go 1.22 or newer
- Optional: golangci-lint for
make lint - Optional: Docker for docs/DEPLOYMENT.md
go test ./...
go run . -version
make run
./bin/fs -listen :7070 -dial 127.0.0.1:8080
./bin/fs -listen 127.0.0.1:0 -health 127.0.0.1:8080 # HTTP live/ready/peers/metricsTerminal 1: start a receiver with framed replication and metrics.
go run . -listen 127.0.0.1:7070 -replicate -health 127.0.0.1:8080Terminal 2: dial the receiver and send one blob.
go run . -listen 127.0.0.1:0 -dial 127.0.0.1:7070 -put-content-key -put-data "hello streamhive" -exit-after-putInspect counters:
curl -s http://127.0.0.1:8080/metricsInspect connected peers:
curl -s http://127.0.0.1:8080/peersLook for replication_blobs_stored, replication_bytes_stored, duplicate counters, and transport frame counters. The sender derives the blob key from SHA-256(put-data) when -put-content-key is set; receivers verify SHA-256-shaped keys before storing. Use /metrics for JSON counters, /metrics/prometheus for Prometheus text format, and /peers for sorted peer metadata including remote address, local address, direction, connection timestamp, and connection age.
Or run the whole flow:
make demo-replicationFor a 3-node Docker Compose demo with durable stores and node restart rehydration:
make demo-composeTo inspect a running Compose cluster:
make demo-statusFor a 3-node corruption repair demo that deletes node3's durable blob and waits for periodic anti-entropy to restore it:
make demo-repairFor a reconnect/failure demo that stops node2, deletes its durable blob while down, restarts it, and waits for peer reconnect plus repair:
make demo-failureFor a longer-lived node with static peers, use -peers and reconnect backoff:
go run . -listen 127.0.0.1:7071 -peers 127.0.0.1:7070,127.0.0.1:7072 -peer-reconnect-peer-reconnect retries only -peers targets. -dial stays a one-shot connection attempt for scripts and tests.
When both sides run with -replicate, peers advertise local keys on connect and send missing blobs to each other. This startup anti-entropy path works with memory storage and durable -store-dir receivers.
For long-running nodes, add periodic inventory sync:
go run . -listen 127.0.0.1:7071 -replicate -store-dir ./streamhive-data -peers 127.0.0.1:7070 -peer-reconnect -sync-interval 30sTo persist replicated blobs on the receiver, add -store-dir:
go run . -listen 127.0.0.1:7070 -replicate -store-dir ./streamhive-data| Import | Purpose |
|---|---|
github.com/AliSinaDevelo/StreamHive/p2p |
TCPTransport, framing (ReadFrame / WriteFrame), peer snapshots, metrics |
github.com/AliSinaDevelo/StreamHive/replication |
Blob replication messages (blob.put, blob.has, blob.get, blob.missing) and store apply helper |
github.com/AliSinaDevelo/StreamHive/storage |
BlobStore, BlobKeyLister, MemoryStore, FileStore, SHA-256 content key helpers |
Wire handshake string constant: p2p.HandshakeVersionV1 (carry inside application frames).
| Flag | Meaning |
|---|---|
-listen |
TCP listen address |
-dial |
Optional peer to dial after listen |
-peers |
Optional comma-separated peers to dial after listen |
-peer-reconnect |
Retry -peers with exponential backoff |
-peer-reconnect-min / -peer-reconnect-max |
Reconnect backoff bounds |
-sync-interval |
Periodically advertise local blob keys to connected peers (0 = startup only) |
-health |
HTTP host:port for /livez, /readyz, /peers, /metrics |
-max-peers |
Cap simultaneous peers (0 = unlimited) |
-dial-timeout |
Outbound dial timeout |
-read-idle-timeout |
Peer read deadline refresh |
-tls-cert / -tls-key |
Server TLS |
-tls-ca / -tls-server-name / -tls-insecure-skip-verify |
Client TLS |
-replicate |
Enable blob replication from framed peers |
-store-dir |
Persist replicated blobs with storage.FileStore |
-list-keys |
Print durable -store-dir keys as hex and exit |
-put-key / -put-data |
Send one manually keyed blob to outbound peers |
-put-content-key |
Derive the outbound blob key from SHA-256(-put-data) |
-exit-after-put |
Exit after the outbound blob frame is written |
-max-blob-bytes |
Cap replicated blob payload size |
See the Makefile for test-race, vet, cover, lint, and demos.
flowchart TB
subgraph app [Process]
CLI[CLI / run]
T[TCPTransport]
F[SHV1 frames]
S[BlobStore]
R[replication blob.put / blob.has]
CLI --> T
T --> F
F --> R
R --> S
end
T <-->|TCP/TLS| remote[Remote peers]
- CI pins third-party GitHub Actions to immutable commit SHAs and uploads coverage plus a CycloneDX SBOM (
sbomjob). - docs/WORKFLOWS.md — local and CI expectations.
- docs/GOVERNANCE.md — branch protection and release hygiene.
- docs/DEPLOYMENT.md — Docker and Kubernetes sketch.
- docs/PROTOCOL.md — frame format, replication messages, limits, and repair behavior.
- docs/RELEASE.md — release checklist.
See CONTRIBUTING.md. Security: SECURITY.md.
MIT — see LICENSE.