Redis#

The usual first step out of one process. Membership, the distributed actor directory and actor storage — all on one ioredis client.

v0.1.0 MIT

Installation#

pnpm add @sigx/actors-redis ioredis

npm install @sigx/actors-redis ioredis

yarn add @sigx/actors-redis ioredis

bun add @sigx/actors-redis ioredis

Requires Redis ≥ 7 — the directory claim uses SET NX GET. ioredis ≥ 5 is a peer dependency.

What it provides#

import { defineActorApp } from '@sigx/actors/host';
import { cluster } from '@sigx/actors/cluster';
import { redisCluster, redisStorage } from '@sigx/actors-redis';

export const app = defineActorApp({
    actors,
    storage: redisStorage({ url: process.env.REDIS_URL }),
}).use(cluster({
    providers: redisCluster({ url: process.env.REDIS_URL }),
    advertise: 'http://10.0.4.7:7311',
    secret: process.env.HOST_SECRET,
}));

Pass an existing client instead of url to share the app's connection — redisCluster({ client }). Sharing one ioredis client across redisCluster() and redisStorage() is safe and saves connections.

Call redisCluster() once per host. Each call returns that host's own membership handle. The directory is safely shared.

Fencing#

A host that cannot heartbeat past ttlMs self-fences: it stops claiming actors and deactivates what it holds. Directory entries belonging to dead hosts are evicted lazily on lookup.

State integrity never rests on any of this. The runtime's storage etag CAS is the floor — a briefly wrong directory entry costs a rejected save and a fault-and-reload, never corruption.

Reminders#

Reminders ride the same storage automatically. If your reminder table grows large enough that scanning it becomes the problem, @sigx/actors-pg has a SKIP LOCKED implementation designed for exactly that.

Next steps#

• Installation — setup and the options table.
• API reference — exports and the key layout.
• Clustering — where the providers plug in.