Relay Server

7. Relay Server

7.1 Responsibilities

Do	Don’t
Accept iroh connections (QUIC)	Store data long-term
Noise handshake	Decrypt payloads
Route messages by group_id	Know what’s in blobs
Buffer for offline devices (temp)	Require accounts
Assign monotonic cursors	Process application logic
Clean up expired blobs

7.2 Storage Schema (Temporary Buffer)

-- SQLite with WAL mode for concurrent access
PRAGMA journal_mode=WAL;
PRAGMA synchronous=NORMAL;
PRAGMA busy_timeout=5000;

-- Cursor sequence per group
CREATE TABLE group_cursors (
    group_id BLOB PRIMARY KEY,
    next_cursor INTEGER NOT NULL DEFAULT 1
);

-- Temporary blob buffer
CREATE TABLE blobs (
    blob_id BLOB PRIMARY KEY,
    group_id BLOB NOT NULL,
    cursor INTEGER NOT NULL,
    sender_id BLOB NOT NULL,
    payload BLOB NOT NULL,         -- Still encrypted
    timestamp INTEGER,
    expires_at INTEGER NOT NULL,   -- Auto-delete time
    created_at INTEGER,
    UNIQUE(group_id, cursor)
);

-- Track delivery status
CREATE TABLE deliveries (
    blob_id BLOB,
    device_id BLOB,
    delivered_at INTEGER,
    PRIMARY KEY (blob_id, device_id)
);

-- Indexes
CREATE INDEX idx_blobs_group_cursor ON blobs(group_id, cursor);
CREATE INDEX idx_blobs_expires ON blobs(expires_at);

7.3 Relay Behavior

On Connection (HELLO):

Complete Noise handshake
Validate HELLO message
Register device for group
Send WELCOME with max_cursor, pending_count
Send NOTIFY for each pending blob

On PUSH:

Begin transaction

Increment cursor atomically:

INSERT INTO group_cursors (group_id, next_cursor) VALUES (?, 1)
ON CONFLICT(group_id) DO UPDATE SET next_cursor = next_cursor + 1
RETURNING next_cursor - 1 AS assigned_cursor;

Store blob with cursor and TTL
Commit
Send PUSH_ACK to sender
Send NOTIFY to all other online devices in group

On PULL:

Query blobs where cursor > after_cursor
Order by cursor ASC
Limit results
Return blobs with has_more flag
Mark as delivered for this device

On DELETE:

Check if all devices have ACKed
If yes, delete blob
If no, mark pending delete

Cleanup (hourly):

Delete expired blobs (past TTL)
Delete blobs where all devices ACKed
Run PRAGMA incremental_vacuum

7.4 Rate Limits

Resource	Limit	Window
Connections per IP	10	Concurrent
Messages per device	100	Per minute
Blob size	1 MB	Per blob
Buffer per group	100 MB	Total
Default TTL	7 days	Per blob

7.5 Health Endpoints

GET /health

{
  "status": "ok",
  "version": "1.0.0",
  "connections": 42,
  "groups": 15,
  "blobs_buffered": 127,
  "uptime_seconds": 86400
}

GET /metrics (Prometheus format)

sync_relay_connections_total 1567
sync_relay_connections_active 42
sync_relay_blobs_buffered 127
sync_relay_blobs_delivered 45892
sync_relay_bytes_transferred 157286400