Universe

Real-time replicator for SpacetimeDB, inspired by Litestream.

Universe watches a SpacetimeDB data directory (commit logs, snapshots, module logs) and continuously streams new bytes to a remote receiver over TCP. On reconnection, the receiver reports its current offsets and the sender resumes from those points — no data is re-sent unnecessarily.

Install

go install github.com/kidandcat/universe@latest

Or build from source:

git clone https://github.com/kidandcat/universe.git
cd universe
go build -o universe .

Usage

Receiver (on the replica machine)

Start the receiver first. It listens on a TCP port and writes incoming data to a local mirror directory:

universe receive --port 9876 --dir /data/spacetime-replica

Sender (on the SpacetimeDB machine)

Point the sender at your SpacetimeDB data directory and the receiver's address:

# Watch for new changes only
universe send --dir ~/.local/share/spacetime/data --to replica.example.com:9876

# Full sync first, then watch
universe send --dir ~/.local/share/spacetime/data --to replica.example.com:9876 --initial-sync

The --initial-sync flag walks the entire data directory and sends all existing bytes before switching to watch mode. Use it on the first run or when setting up a new replica.

How it works

┌─────────────────────┐        TCP         ┌─────────────────────┐
│   SpacetimeDB Host  │  ──────────────>   │   Replica Host      │
│                     │                     │                     │
│  clog/*.stdb.log    │   framed stream     │  mirror/clog/...    │
│  clog/*.stdb.ofs    │   with CRC32        │  mirror/snapshots/  │
│  snapshots/...      │  <──────────────    │  mirror/module_logs/│
│  module_logs/...    │   offset ACKs       │                     │
└─────────────────────┘                     └─────────────────────┘

1. Connect: Sender dials the receiver. Receiver sends an ACK with its current byte offsets per file.
2. Initial sync (optional): Sender walks the data directory and sends all bytes from each file, starting from the receiver's last known offset.
3. Watch: Sender uses fsnotify to watch for file changes (writes, creates). New bytes are read and sent as frames.
4. Frames: Each frame contains [magic 4B][path len 2B][path][offset 8B][data len 4B][crc32 4B][data]. CRC32 ensures integrity.
5. ACKs: Receiver periodically sends ACK messages with its confirmed offsets. On reconnection, the sender resumes from these offsets.

SpacetimeDB data directory structure

Universe replicates the following files from a SpacetimeDB data directory:

data/
├── replicas/<id>/
│   ├── clog/
│   │   ├── *.stdb.log    # Commit log (BSATN-encoded transactions)
│   │   └── *.stdb.ofs    # Offset index for random access
│   ├── snapshots/
│   │   └── *.snapshot_dir/
│   │       ├── *.snapshot_bsatn
│   │       └── objects/<hash>
│   └── module_logs/
│       └── YYYY-MM-DD.log
├── control-db/
└── program-bytes/

Configuration

Flag	Default	Description
--dir	(required)	SpacetimeDB data directory (sender) or mirror directory (receiver)
--to	(required)	Receiver address as host:port (sender only)
--port	9876	TCP port to listen on (receiver only)
--initial-sync	false	Send all existing data before watching (sender only)

License

MIT