Skip to content

shoehive/store/redis

shoehive/store/redis: the Redis Store adapter (ADR 0009), on an ioredis client that you create and own (ioredis is an optional peer dependency, ADR 0002).

import { Redis } from 'ioredis';
import { createServer } from 'shoehive/server';
import { redisStore } from 'shoehive/store/redis';
const redis = new Redis(process.env.REDIS_URL);
const server = createServer({ games, secret, store: redisStore({ client: redis }) });
// On shutdown: await server.close(); then redis.quit() (the store never quits it).

Redis must run with AOF enabled (appendonly yes). The engine acks an action only after appendLog resolves ("an ack means durable", ADR 0009), and without AOF Redis keeps writes in memory until the next RDB snapshot, so a crash loses every acked action since then. The appendfsync setting decides how durable an ack is:

  • always: fsync before every reply. An ack survives a crash of Redis or of the machine. Slowest: each append waits for the disk.
  • everysec (the Redis default, recommended): fsync once a second. An ack survives a Redis crash; a power loss or kernel crash can lose up to about one second of acked actions. Throughput close to no fsync at all.
  • no: the OS decides when to flush (often every 30 seconds). Not recommended.

Replication does not replace AOF: replicas receive writes asynchronously, so a failover can drop acked entries unless you also use WAIT/min-replicas-to-write.

Key layout, for a prefix P (default shoehive:):

Key Type Holds
P log:<id> list the table's log: entry data, element index == seq
P snap:<id> string JSON of the table's latest StoredSnapshot
P open set ids of tables that have a snapshot and are not closed
P closed hash closed table id to close reason
P sessions hash player id to JSON of the SessionRecord

Table and player ids are stored as-is, with no escaping (Redis keys and members are binary safe). An id is always the last part of a key, after a fixed kind (log:, snap:), so no id can collide with another id or with the fixed keys, whatever it contains (:, spaces, quotes, non-ASCII). Prefixes must not nest: give each store its own prefix, and never one that starts with another store's prefix (app: and app:log: would overlap).

Appends, snapshot saves and closes run as Lua scripts, so each one is atomic and the invariant "open = has a snapshot and is not closed" holds between any two commands. A retried append (identical entries already stored) succeeds without writing.

Redis Cluster is not supported in v1: pass a standalone (or Sentinel) client.

Re-exports SessionRecord


Re-exports Store


Re-exports StoreConflictError


Re-exports StoredEntry


Re-exports StoredSnapshot