Redis Notify Adapter
Wake workers with Redis pub/sub on standalone Redis or Redis Cluster: node-redis, ioredis and Bun.
createRedisNotifyAdapter uses Redis pub/sub for broadcasting job notifications to workers, publishing each batch from one Lua script. The notify adapter stores no job state; job storage is handled by a separate state adapter, which can also be the experimental Redis state adapter.
Install
Terminal
npm install @queuert/redisRequires Redis 6 or later, standalone or Redis Cluster.
Setup
Each example's notify provider and adapter:
src/provider.ts
import type { RedisNotifyProvider } from "@queuert/redis";
import type { RedisClientType } from "redis";
export const createNodeRedisNotifyProvider = ({
client,
subscribeClient,
}: {
client: RedisClientType;
subscribeClient: RedisClientType;
}): RedisNotifyProvider => ({
subscribe: async (channel, onMessage) => {
await subscribeClient.subscribe(channel, onMessage);
return async () => {
await subscribeClient.unsubscribe(channel);
};
},
eval: async (script, keys, args) => {
return client.eval(script, { keys, arguments: args });
},
});src/index.ts
await using drivers = new AsyncDisposableStack();
// Create Redis connections
const redis = drivers.adopt(createRedisClient({ url: redisUrl }), async (redis) => {
await redis.quit();
});
await redis.connect();
const redisSubscription = drivers.adopt(
createRedisClient({ url: redisUrl }),
async (redisSubscription) => {
await redisSubscription.quit();
},
);
await redisSubscription.connect();
// Create the notify provider using node-redis
const notifyProvider = createNodeRedisNotifyProvider({
client: redis,
subscribeClient: redisSubscription,
});
// Create the notify adapter
await using notifyAdapter = createRedisNotifyAdapter({ notifyProvider });src/provider.ts
import type { RedisNotifyProvider } from "@queuert/redis";
import type { Redis } from "ioredis";
export const createIoredisNotifyProvider = ({
client,
subscribeClient,
}: {
client: Redis;
subscribeClient: Redis;
}): RedisNotifyProvider => {
const handlers = new Map<string, (message: string) => void>();
const dispatchMessage = (channel: string, message: string) => {
handlers.get(channel)?.(message);
};
subscribeClient.on("message", dispatchMessage);
return {
subscribe: async (channel, onMessage) => {
handlers.set(channel, onMessage);
await subscribeClient.subscribe(channel);
return async () => {
await subscribeClient.unsubscribe(channel);
handlers.delete(channel);
};
},
eval: async (script, keys, args) => {
return client.eval(script, keys.length, ...keys, ...args);
},
close: async () => {
subscribeClient.off("message", dispatchMessage);
handlers.clear();
},
};
};src/index.ts
await using drivers = new AsyncDisposableStack();
// Create Redis connections
const redis = drivers.adopt(new Redis(redisUrl), async (redis) => {
await redis.quit();
});
const redisSubscription = drivers.adopt(new Redis(redisUrl), async (redisSubscription) => {
await redisSubscription.quit();
});
// Create the notify provider using ioredis
const notifyProvider = createIoredisNotifyProvider({
client: redis,
subscribeClient: redisSubscription,
});
// Create the notify adapter
await using notifyAdapter = createRedisNotifyAdapter({ notifyProvider });src/provider.ts
import type { RedisNotifyProvider } from "@queuert/redis";
import type { RedisClient } from "bun";
export const createBunRedisNotifyProvider = ({
client,
subscribeClient,
}: {
client: RedisClient;
subscribeClient: RedisClient;
}): RedisNotifyProvider => ({
subscribe: async (channel, onMessage) => {
const listener = (message: string) => {
onMessage(message);
};
await subscribeClient.subscribe(channel, listener);
return async () => {
await subscribeClient.unsubscribe(channel, listener);
};
},
eval: async (script, keys, args) => {
return client.send("EVAL", [script, String(keys.length), ...keys, ...args]);
},
});src/index.ts
// Create Redis connections (pub/sub needs a dedicated connection)
await using drivers = new AsyncDisposableStack();
const redis = drivers.adopt(new RedisClient(redisUrl), (redis) => {
redis.close();
});
await redis.connect();
const redisSubscription = drivers.adopt(new RedisClient(redisUrl), (redisSubscription) => {
redisSubscription.close();
});
await redisSubscription.connect();
// Create the notify provider using Bun Redis
const notifyProvider = createBunRedisNotifyProvider({
client: redis,
subscribeClient: redisSubscription,
});
// Create the notify adapter
await using notifyAdapter = createRedisNotifyAdapter({ notifyProvider });src/provider.ts
import type { RedisNotifyProvider } from "@queuert/redis";
import type { RedisClusterType } from "redis";
export const createNodeRedisClusterNotifyProvider = ({
cluster,
subscribeCluster,
}: {
cluster: RedisClusterType;
subscribeCluster: RedisClusterType;
}): RedisNotifyProvider => {
// Workaround for duplicate deliveries. Redis Cluster forwards PUBLISH to every node over the
// cluster bus, but Redis does not set TCP_NODELAY on the bus connections a node opens, so
// back-to-back messages can reach some nodes ~40ms late (Nagle + delayed ACK; fixed in Valkey by
// https://github.com/valkey-io/valkey/pull/1763, still present in Redis 8). node-redis closes its
// pub/sub connection when the last channel is unsubscribed and reopens it on a random node, so a
// resubscribe can land on a node that delivers a late copy of a message already received. A
// subscription that is never removed keeps the connection, and its node, for the provider's
// lifetime.
const pinChannel = "queuert:pubsub-pin";
const pinListener = (): void => {};
let pinned: Promise<void> | undefined;
const pinPubSubConnection = async (): Promise<void> => {
pinned ??= subscribeCluster.subscribe(pinChannel, pinListener).catch((error: unknown) => {
pinned = undefined;
throw error;
});
await pinned;
};
return {
subscribe: async (channel, onMessage) => {
await pinPubSubConnection();
await subscribeCluster.subscribe(channel, onMessage);
return async () => {
await subscribeCluster.unsubscribe(channel);
};
},
eval: async (script, keys, args) => {
return cluster.eval(script, { keys, arguments: args });
},
close: async () => {
if (!pinned) return;
const pin = pinned;
pinned = undefined;
const wasPinned = await pin.then(
() => true,
() => false,
);
if (wasPinned) await subscribeCluster.unsubscribe(pinChannel, pinListener);
},
};
};src/index.ts
await using drivers = new AsyncDisposableStack();
// Create Redis Cluster connections
const cluster = drivers.adopt(createCluster({ rootNodes: rc.rootNodes }), async (cluster) =>
cluster.close(),
);
await cluster.connect();
const subscribeCluster = drivers.adopt(
createCluster({ rootNodes: rc.rootNodes }),
async (subscribeCluster) => subscribeCluster.close(),
);
await subscribeCluster.connect();
// Create the notify provider using node-redis cluster
const notifyProvider = createNodeRedisClusterNotifyProvider({
cluster,
subscribeCluster,
});
// Create the notify adapter
await using notifyAdapter = createRedisNotifyAdapter({ notifyProvider });src/provider.ts
import type { RedisNotifyProvider } from "@queuert/redis";
import type { Cluster } from "ioredis";
export const createIoredisClusterNotifyProvider = ({
cluster,
subscribeCluster,
}: {
cluster: Cluster;
subscribeCluster: Cluster;
}): RedisNotifyProvider => {
const handlers = new Map<string, Set<(message: string) => void>>();
const dispatchMessage = (channel: string, message: string) => {
const listeners = handlers.get(channel);
if (!listeners) return;
for (const listener of listeners) listener(message);
};
subscribeCluster.on("message", dispatchMessage);
return {
subscribe: async (channel, onMessage) => {
let listeners = handlers.get(channel);
if (!listeners) {
listeners = new Set();
handlers.set(channel, listeners);
}
listeners.add(onMessage);
await subscribeCluster.subscribe(channel);
return async () => {
const set = handlers.get(channel);
if (!set) return;
set.delete(onMessage);
if (set.size === 0) {
handlers.delete(channel);
await subscribeCluster.unsubscribe(channel);
}
};
},
eval: async (script, keys, args) => {
return cluster.eval(script, keys.length, ...keys, ...args);
},
close: async () => {
subscribeCluster.off("message", dispatchMessage);
handlers.clear();
},
};
};src/index.ts
await using drivers = new AsyncDisposableStack();
const startupNodes = rc.rootNodes.map((node) => node.url);
// Create Redis Cluster connections
const cluster = drivers.adopt(new Cluster(startupNodes), async (cluster) => {
await cluster.quit();
});
const subscribeCluster = drivers.adopt(new Cluster(startupNodes), async (subscribeCluster) => {
await subscribeCluster.quit();
});
// Create the notify provider using ioredis cluster
const notifyProvider = createIoredisClusterNotifyProvider({
cluster,
subscribeCluster,
});
// Create the notify adapter
await using notifyAdapter = createRedisNotifyAdapter({ notifyProvider });The notify adapter and your clients are held with await using. A client that is not disposable itself is adopted by a drivers AsyncDisposableStack. Disposal runs in reverse order, so when the scope ends the notify adapter closes before your clients, in the shutdown order.
Configuration
createRedisNotifyAdapter options
- notifyProvider requiredRedisNotifyProviderSee Notify provider.
- string · default "queuert"Prefix for the three channel names.
Notify provider
A RedisNotifyProvider bridges your Redis client with the adapter. Each Setup tab is a complete provider for its client; to use another one, implement the same members:
RedisNotifyProvider
Testing your provider
redisNotifyProviderConformanceCases from @queuert/redis/conformance check a provider you write: they are every case a notify adapter must pass, run against the context createRedisNotifyProviderConformanceContext({ createNotifyProvider }) returns: each case builds its own notify adapter over a new provider from your factory and closes both when it ends. The suite drives no test runner: your test file owns the connections in its own hooks and registers one test per case. Every example's src/provider.spec.ts is a working template:
src/provider.spec.ts
describe("notify-redis-redis provider conformance", () => {
let redis: AcquiredRedis;
let client: RedisClientType;
let subscribeClient: RedisClientType;
let context: NotifyAdapterConformanceContext;
beforeAll(async () => {
redis = await acquireRedis("redis:8");
client = createClient({ url: redis.connectionUrl });
subscribeClient = createClient({ url: redis.connectionUrl });
await client.connect();
await subscribeClient.connect();
context = createRedisNotifyProviderConformanceContext({
createNotifyProvider: async () => createNodeRedisNotifyProvider({ client, subscribeClient }),
});
}, 60_000);
afterAll(async () => {
await client.close();
await subscribeClient.close();
await redis[Symbol.asyncDispose]();
});
for (const conformanceCase of redisNotifyProviderConformanceCases) {
test(conformanceCase.title, async () => {
await conformanceCase.run(context);
});
}
});src/provider.spec.ts
describe("notify-redis-ioredis provider conformance", () => {
let redis: AcquiredRedis;
let client: Redis;
let subscribeClient: Redis;
let context: NotifyAdapterConformanceContext;
beforeAll(async () => {
redis = await acquireRedis("redis:8");
client = new Redis(redis.connectionUrl);
subscribeClient = new Redis(redis.connectionUrl);
context = createRedisNotifyProviderConformanceContext({
createNotifyProvider: async () => createIoredisNotifyProvider({ client, subscribeClient }),
});
}, 60_000);
afterAll(async () => {
await client.quit();
await subscribeClient.quit();
await redis[Symbol.asyncDispose]();
});
for (const conformanceCase of redisNotifyProviderConformanceCases) {
test(conformanceCase.title, async () => {
await conformanceCase.run(context);
});
}
});src/provider.spec.ts
describe("notify-redis-bun provider conformance", () => {
let redis: AcquiredRedis;
let client: RedisClient;
let subscribeClient: RedisClient;
let context: NotifyAdapterConformanceContext;
beforeAll(async () => {
redis = await acquireRedis("redis:8");
client = new RedisClient(redis.connectionUrl);
subscribeClient = new RedisClient(redis.connectionUrl);
await client.connect();
await subscribeClient.connect();
context = createRedisNotifyProviderConformanceContext({
createNotifyProvider: async () => createBunRedisNotifyProvider({ client, subscribeClient }),
});
}, 60_000);
afterAll(async () => {
client.close();
subscribeClient.close();
await redis[Symbol.asyncDispose]();
});
for (const conformanceCase of redisNotifyProviderConformanceCases) {
test(conformanceCase.title, async () => {
await conformanceCase.run(context);
});
}
});src/provider.spec.ts
describe("notify-redis-cluster-node-redis provider conformance", () => {
let rc: AcquiredRedisCluster;
let cluster: RedisClusterType;
let subscribeCluster: RedisClusterType;
let context: NotifyAdapterConformanceContext;
beforeAll(async () => {
rc = await acquireRedisCluster("redis:8");
cluster = createCluster({ rootNodes: rc.rootNodes });
subscribeCluster = createCluster({ rootNodes: rc.rootNodes });
await cluster.connect();
await subscribeCluster.connect();
context = createRedisNotifyProviderConformanceContext({
createNotifyProvider: async () =>
createNodeRedisClusterNotifyProvider({ cluster, subscribeCluster }),
});
}, 60_000);
afterAll(async () => {
await cluster.close();
await subscribeCluster.close();
await rc[Symbol.asyncDispose]();
});
for (const conformanceCase of redisNotifyProviderConformanceCases) {
test(conformanceCase.title, async () => {
await conformanceCase.run(context);
});
}
});src/provider.spec.ts
describe("notify-redis-cluster-ioredis provider conformance", () => {
let rc: AcquiredRedisCluster;
let cluster: Cluster;
let subscribeCluster: Cluster;
let context: NotifyAdapterConformanceContext;
beforeAll(async () => {
rc = await acquireRedisCluster("redis:8");
const startupNodes = rc.rootNodes.map((node) => node.url);
cluster = new Cluster(startupNodes);
subscribeCluster = new Cluster(startupNodes);
context = createRedisNotifyProviderConformanceContext({
createNotifyProvider: async () =>
createIoredisClusterNotifyProvider({ cluster, subscribeCluster }),
});
}, 60_000);
afterAll(async () => {
await cluster.quit();
await subscribeCluster.quit();
await rc[Symbol.asyncDispose]();
});
for (const conformanceCase of redisNotifyProviderConformanceCases) {
test(conformanceCase.title, async () => {
await conformanceCase.run(context);
});
}
});The full API is in the conformance reference.
Channels
Three channels carry notifications between processes (configurable prefix, default queuert). Channels use Redis Pub/Sub — messages are fire-and-forget with no persistence. If no subscriber is listening when a message is published, it is lost. This is acceptable because workers fall back to polling when notifications are missed.
- {prefix}:sched job scheduledpayload · job type namePublished when jobs become pending. Wakes idle workers.
- {prefix}:chainc chain completedpayload · chain idPublished when a chain completes. Wakes clients awaiting results.
- {prefix}:atls attempt lostpayload · job idPublished when a running job's attempt is lost. Notifies attempt loss.
Connection model
Redis Pub/Sub requires two separate connections. The RedisNotifyProvider interface abstracts this — you manage the two connections in your provider implementation.
- Command connectionRuns EVAL for the publish script, which issues the PUBLISH calls. It cannot be in subscribe mode.
- Subscription connectionRuns SUBSCRIBE and UNSUBSCRIBE. In subscribe mode it cannot execute regular commands.
Examples
@queuert/redis
- GitHub Redis pub/sub notifications via @queuert/redis with the node-redis client.
$ pnpm --filter example-postgresql-notify-redis-redis startsrc/provider.tssrc/index.ts - GitHub Redis pub/sub notifications via @queuert/redis with the ioredis client.
$ pnpm --filter example-postgresql-notify-redis-ioredis startsrc/provider.tssrc/index.ts - GitHub Redis pub/sub notifications via @queuert/redis using Bun's built-in RedisClient — no external Redis dependencies.
$ pnpm --filter example-postgresql-notify-redis-bun startsrc/provider.tssrc/index.ts - postgresql/notify-redis-cluster-node-redis Redis Cluster · node-redis Docker · PostgreSQL Docker · Redis ClusterGitHubRedis notifications against a Redis Cluster through a node-redis cluster client.
$ pnpm --filter example-postgresql-notify-redis-cluster-node-redis startsrc/provider.tssrc/index.ts - postgresql/notify-redis-cluster-ioredis Redis Cluster · ioredis Docker · PostgreSQL Docker · Redis ClusterGitHubRedis notifications against a Redis Cluster through an ioredis cluster client.
$ pnpm --filter example-postgresql-notify-redis-cluster-ioredis startsrc/provider.tssrc/index.ts