@openknot-ts/redis-replication
v0.0.6-preview
Published
Redis implementation of the OpenKnot replica store and replication channel over consumer-owned clients.
Readme
@openknot-ts/redis-replication
Implements the replicaStore and replicationChannel contracts of @openknot-ts/replication over node-redis clients the application already manages.
Usage
import { redisReplicaStore, redisReplicationChannel } from "@openknot-ts/redis-replication/wire";
export const replicaStorage = redisReplicaStore({
requirements: { redis },
commands: ({ redis }) => redis.commands,
connection: ({ redis }) => redis.connection.commands,
});
export const replicaChannel = redisReplicationChannel({
requirements: { redis },
connections: ({ redis }) => redis,
connection: ({ redis }) => redis.connection.subscriber,
});API
| Entry | Export | Description |
| --- | --- | --- |
| /wire | redisReplicaStore({ requirements?, commands, connection?, options? }) | The store. options(dependencies) returns ReplicaStoreOptions: { prefix, tombstoneTtl, encode, decode }. |
| /wire | redisReplicationChannel({ requirements?, connections, connection, channel? }) | The channel; connection watches the subscriber client, channel is a string or (dependencies) => string. |
| root | redisReplicationChannelOf(connections, { connection, channel? }) | The channel over clients directly. |
| root | redisReplicaStoreOf(commands, options?) | The store over a client directly. |
Pass connection (such as redis.connection.commands from @openknot-ts/redis-client) so the replication learns of an outage at once; without it, commits, shared reads and stop() can wait for a held command. See the replication README.
Store
- One Lua script applies a batch atomically: a state is stored when newer than the stored state and tombstone, a delete when at least as new.
- Deletes leave tombstones that expire after
tombstoneTtl(one hour by default). - Orders are non-negative integers below 10^20, or strings, which sort after integers.
- A keyspace shares one hash tag, so it stays in one cluster slot. The marker is a hash;
runIdis the server'srun_id. - States are JSON unless
encode/decodeare given. - Fenced
apply,markand everyclearcompare the marker'sholderinside their script and reject withReplicaFenced. An unfencedmarkis oneHSET, keeping the stored holder. - Scripts run through
EVALSHAand fall back toEVALonNOSCRIPT. clearanddropwalk the keyspace withSCANandUNLINK;clearkeeps the marker,dropremoves it.
Channel
- JSON messages on
openknot:replication, orchannel. Bigint keys and orders keep their type. - Invalid payloads are dropped. The subscriber client's
connectionreports the subscription lost and restored.
Example and tests
pnpm --filter @openknot-ts/redis-replication example runs two instances sharing roles; pnpm --filter @openknot-ts/redis-replication test:redis runs the integration tests against REDIS_URL. Both use the clients from examples/native.ts.
