Skip to content

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.

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.

  • 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 data resolves 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 into listOpenTables().
  • Return rejected promises. Make methods async so a conflict is a rejection, not a throw.
  • Durable means durable. The server acks an action after appendLog resolves, 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.
src/map-store.ts
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
};
}

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.

test/map-store.test.ts
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.

import { createServer } from 'shoehive/server';
const shoehive = createServer({ games, store });

Then try restart recovery end to end against your database.