Writing a store adapter
Shoehive ships stores for memory, SQLite, Postgres and Redis. If you use another database, you can write an adapter in an afternoon. A store is deliberately thin: it keeps opaque JSON strings and append-only logs, and never reads game state.
The interface lives in packages/shoehive/src/store/types.ts and is exported from
shoehive/server. Start from the SQLite adapter
as a model. Then read the contract below and run the conformance suite.
The interface
Section titled “The interface”| Method | What it does |
|---|---|
appendLog(tableId, entries) |
Appends log entries, all or nothing. |
saveSnapshot(tableId, snapshot) |
Replaces the table's snapshot. |
loadTable(tableId) |
The snapshot and every entry after it, or null for an unknown table. |
readLog(tableId, fromSeq, toSeq?) |
Entries from fromSeq to toSeq inclusive (devtools replay). |
listOpenTables() |
Ids of the tables to recover on startup. |
closeTable(tableId, reason) |
Keeps the table but stops recovering it. |
sessions.get / put / delete |
Guest session records, by player id. |
close() |
Releases what the adapter itself opened. |
Entries and snapshots carry their payload as a JSON string in data. Store it byte for byte
and hand it back unchanged.
The contract
Section titled “The contract”- A log starts at seq 0 and has no gaps. Each entry must have the seq after the last stored
one. Anything else rejects with
StoreConflictError(tableId, expected, got). This is how Shoehive catches two servers writing to one table. - Batches are atomic. If any entry in a batch conflicts, nothing is written.
- Exact retries succeed. A batch whose entries are all already stored with identical
dataresolves without writing. Some drivers resend a command after a lost reply, and that must not fault the table. Any other overlap is a conflict. An empty batch does nothing. - Concurrent writers: exactly one wins. Two appends of the same seq must not both succeed,
even from another process. Use a transaction, a unique key on
(table, seq)or a script. - Closed tables stay closed. The engine saves a snapshot as a table ends, after
closeTable. That snapshot must not bring the table back intolistOpenTables(). - Return rejected promises. Make methods
asyncso a conflict is a rejection, not a throw. - Durable means durable. The server acks an action after
appendLogresolves, so flush to disk before you resolve, or document the trade-off. - Take clients, do not own them. Accept a pool or client from the caller and leave it open
in
close(), as the Postgres and Redis adapters do. Close only what you opened yourself.
export function mapStore(shelf: Shelf): Store { return { // async, so a conflict is a rejected promise rather than a thrown error async appendLog(tableId, entries) { const log = shelf.logs.get(tableId) ?? []; // An exact retry (every entry already stored, same data) succeeds without writing. // A batch that is empty also lands here. if (entries.every((e) => log[e.seq] !== undefined)) { const bad = entries.find((e) => log[e.seq]?.data !== e.data); if (bad) throw new StoreConflictError(tableId, log.length, bad.seq); return; } // Otherwise every entry must follow the last stored one, in order, from seq 0. let next = log.length; for (const entry of entries) { if (entry.seq !== next) throw new StoreConflictError(tableId, next, entry.seq); next += 1; } shelf.logs.set(tableId, [...log, ...entries]); // all or nothing }, saveSnapshot(tableId, snapshot) { shelf.snapshots.set(tableId, snapshot); return Promise.resolve(); }, loadTable(tableId) { const snapshot = shelf.snapshots.get(tableId); if (!snapshot) return Promise.resolve(null); const tail = (shelf.logs.get(tableId) ?? []).filter((e) => e.seq > snapshot.seq); return Promise.resolve({ snapshot, tail }); }, readLog(tableId, fromSeq, toSeq = Infinity) { const log = shelf.logs.get(tableId) ?? []; return Promise.resolve(log.filter((e) => e.seq >= fromSeq && e.seq <= toSeq)); }, listOpenTables() { const open = [...shelf.snapshots.keys()].filter((id) => !shelf.closed.has(id)); return Promise.resolve(open); }, closeTable(tableId) { shelf.closed.add(tableId); // saveSnapshot never removes it from this set return Promise.resolve(); }, sessions: { get: (playerId) => Promise.resolve(shelf.sessions.get(playerId) ?? null), put(record) { shelf.sessions.set(record.playerId, record); return Promise.resolve(); }, delete(playerId) { shelf.sessions.delete(playerId); return Promise.resolve(); }, }, close: () => Promise.resolve(), // release your own connections here, not the caller's };}Prove it with the conformance suite
Section titled “Prove it with the conformance suite”runStoreConformance from shoehive/testing registers the tests for you. It takes your test
runner's describe, it and expect, so it works with Vitest, Jest or node:test.
Pass a backend with open and destroy. The suite calls open() again after close(), and
the new store must see everything the old one wrote: that is what a restart does.
runStoreConformance( () => { const shelf = newShelf(); // fresh, empty storage for each test return { open: () => mapStore(shelf), // called again after close(): must see the old data destroy: () => { // drop the test's data here (a temp file, a schema, a key prefix) }, }; }, { describe, it, expect },);Return fresh, empty storage from each call (a new temp file, schema or key prefix), because
the suite runs many independent tests. destroy removes it afterwards.
The suite checks ordering and conflicts (including the fields of StoreConflictError),
atomic batches, concurrent writers, idempotent retries, snapshots and tails, open and closed
tables, sessions, 1 MiB payloads, exact round trips of unusual JSON and ids, and data
surviving close and reopen.
Use it
Section titled “Use it”import { createServer } from 'shoehive/server';
const shoehive = createServer({ games, store });Then try restart recovery end to end against your database.
Related
Section titled “Related”- Stores reference: the shipped adapters and their settings.
- Persistence and restart recovery.
