Installation#

Add the package and its ioredis peer, then hand the providers to the cluster() plugin.

Install#

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 and ioredis ≥ 5.

Wire it up#

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

const client = new Redis(process.env.REDIS_URL!);

export const app = defineActorApp({
    actors,
    storage: redisStorage({ client }),
}).use(cluster({
    providers: redisCluster({ client }),
    advertise: `http://${process.env.POD_IP}:7311`,
    secret: process.env.HOST_SECRET,
}));

One client for both is safe and saves connections. Share the namespace between them.

Options#

Both redisCluster() and redisStorage() take client or url.

redisStorage() takes client/url and namespace only.

Tuning guidance: ttlMs is how long a dead host's actors stay unclaimable, so lowering it speeds recovery and raises the risk of fencing a host that merely paused — a long GC, a throttled container. Three missed heartbeats is a reasonable floor.

Splitting the providers#

Membership and the directory are independent. Kubernetes Leases for liveness with a Redis directory is a common shape:

cluster({
    providers: { membership: k8sMembership(), directory: redisDirectory(client) },
    advertise, secret,
});

Verify#

const report = await clusterStats(placement);
console.log(report.hosts.length, report.partial);

Or from a terminal, once ops() is mounted:

sigx actors health --url http://localhost:7311

Testing#

The provider suite is gated on REDIS_URL:

REDIS_URL=redis://localhost:6379 pnpm test -- actors-redis

For unit tests that need a cluster but not a server, memoryClusterHub() from @sigx/actors/cluster gives an N-host in-process cluster with no external store.

Next steps#

• API reference — exports and key layout.
• Clustering — the plugin options.
• Storage — choosing a provider.