@beignet/provider-event-bus-redis 0.0.33

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# @beignet/provider-event-bus-redis
+
+## 0.0.33
+
+### Patch Changes
+
+- 308770a: Add opt-in live Redis integration coverage for cross-instance event delivery, unsubscribe behavior, readiness, instrumentation, and failure callbacks.
+- 92af951: Add a Redis Pub/Sub event bus provider and `event-bus-redis` provider preset for cross-process best-effort event delivery.
+
+## 0.0.32
+
+### Patch Changes
+
+- Initial Redis Pub/Sub event bus provider for cross-process best-effort
+  `EventBusPort` delivery.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Taylor Bryant
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,173 @@
+# @beignet/provider-event-bus-redis
+
+> [!CAUTION]
+> Beignet is experimental alpha software. The `0.0.x` package line is for early
+> evaluation, and APIs may change between releases while the framework settles.
+
+Redis Pub/Sub `EventBusPort` provider for Beignet applications.
+
+Use it when a multi-process app needs domain events published by one process to
+reach listeners registered in another process. Delivery is best-effort:
+subscribers must be online, Redis does not persist messages for later replay,
+and the provider does not acknowledge, retry, or dead-letter failed handlers.
+Use Beignet outbox and jobs for durable side effects that need retry,
+idempotency, or recovery after downtime.
+
+## Install
+
+```bash
+bun add @beignet/provider-event-bus-redis @beignet/core ioredis
+```
+
+You can also wire it into an existing app with the CLI:
+
+```bash
+beignet providers add event-bus-redis
+```
+
+## Setup
+
+```typescript
+import { createNextServer, createNextServerLoader } from "@beignet/next";
+import { redisEventBusProvider } from "@beignet/provider-event-bus-redis";
+import { appPorts } from "@/infra/app-ports";
+import { routes } from "@/server/routes";
+
+// Set environment variables:
+// REDIS_EVENT_BUS_URL=redis://localhost:6379
+// REDIS_EVENT_BUS_DB=0 (optional)
+
+export const getServer = createNextServerLoader(() =>
+  createNextServer({
+    ports: appPorts,
+    providers: [redisEventBusProvider],
+    context: ({ ports }) => ({
+      ports,
+    }),
+    routes,
+  }),
+);
+```
+
+The provider contributes `ctx.ports.eventBus`, the standard Beignet event bus
+port, and `ctx.ports.redisEventBus` as a Redis-specific escape hatch.
+
+## Configuration
+
+The provider reads environment variables with the `REDIS_EVENT_BUS_` prefix:
+
+| Variable | Required | Description | Example |
+| --- | --- | --- | --- |
+| `REDIS_EVENT_BUS_URL` | Yes | Redis connection URL. | `redis://localhost:6379` |
+| `REDIS_EVENT_BUS_DB` | No | Redis database number. Defaults to `0`. | `0` |
+| `REDIS_EVENT_BUS_CHANNEL_PREFIX` | No | Prefix for Pub/Sub channels. Defaults to `beignet:event-bus:`. | `my-app:events:` |
+| `REDIS_EVENT_BUS_CONNECT_TIMEOUT_MS` | No | Initial connection timeout in milliseconds. Defaults to `5000`. | `2000` |
+| `REDIS_EVENT_BUS_MAX_RETRIES_PER_REQUEST` | No | Per-command retry limit before a command rejects. Defaults to `2`. | `1` |
+| `REDIS_EVENT_BUS_CONNECT_MAX_ATTEMPTS` | No | Connection attempts before startup fails. Defaults to `3`. | `5` |
+
+### Factory options
+
+Use `createRedisEventBusProvider(options)` when the app should own connection
+settings. Defined options override matching `REDIS_EVENT_BUS_*` environment
+variables:
+
+```typescript
+import { createRedisEventBusProvider } from "@beignet/provider-event-bus-redis";
+
+const redisEventBusProvider = createRedisEventBusProvider({
+  channelPrefix: "my-app:events:",
+  connectTimeoutMs: 2000,
+  maxRetriesPerRequest: 1,
+  db: 1,
+  retryStrategy: (times) => Math.min(times * 100, 1000),
+});
+```
+
+The default `redisEventBusProvider` export is
+`createRedisEventBusProvider()` with no options.
+
+### Connection behavior
+
+During startup the provider creates separate publisher and subscriber clients,
+connects both eagerly, and fails boot with a redacted connection error when
+Redis is unreachable. The default initial connection retry strategy stops
+after `REDIS_EVENT_BUS_CONNECT_MAX_ATTEMPTS`; after a successful connection,
+ioredis reconnects with capped exponential backoff.
+
+## Direct adapter
+
+Use `createRedisEventBus(...)` when your app owns Redis clients:
+
+```typescript
+import Redis from "ioredis";
+import { createRedisEventBus } from "@beignet/provider-event-bus-redis";
+
+const eventBus = createRedisEventBus({
+  publisher: new Redis(process.env.REDIS_EVENT_BUS_URL),
+  subscriber: new Redis(process.env.REDIS_EVENT_BUS_URL),
+  channelPrefix: "my-app:events:",
+});
+```
+
+Register listeners during startup before handling traffic. The `EventBusPort`
+subscription API is synchronous, while Redis subscription acknowledgement is
+asynchronous, so messages published immediately after a new subscription may be
+missed during startup races.
+
+## Delivery semantics
+
+- `publish(...)` publishes one Redis Pub/Sub message on
+  `<channelPrefix><event.name>`.
+- Only subscribers that are online and currently subscribed receive the event.
+- Payloads are JSON encoded and delivered to handlers without persisting the
+  message.
+- Handler errors are reported through `onHandlerError` when provided and are
+  also recorded as provider instrumentation events; they do not reject the
+  original publisher.
+- Invalid messages and subscription errors are reported through
+  `onSubscriberError` when provided.
+- The provider does not retry handlers, store attempts, replay missed events,
+  or dead-letter failures.
+
+When side effects must survive process restarts or dependency outages, record
+the domain event through the Unit of Work outbox and drain it through jobs or
+outbox-backed listeners.
+
+## Escape hatch and health
+
+`ctx.ports.redisEventBus` exposes:
+
+```typescript
+const health = await ctx.ports.redisEventBus.checkHealth();
+
+ctx.ports.redisEventBus.publisher;
+ctx.ports.redisEventBus.subscriber;
+ctx.ports.redisEventBus.channelPrefix;
+```
+
+`checkHealth()` sends cheap `PING` commands to both Redis clients and returns
+metadata suitable for app-owned readiness endpoints.
+
+## Instrumentation
+
+The provider records publish events under the `eventBus` watcher. Received
+messages and handler failures are recorded as custom provider events. Payloads
+are not recorded.
+
+## Testing
+
+Use `@beignet/provider-event-bus-memory` for deterministic unit tests and
+single-process local tests. Use this Redis provider in integration tests when
+the behavior under test specifically depends on cross-process delivery or
+Redis connection behavior.
+
+This package includes opt-in live Redis integration tests for cross-instance
+delivery, unsubscribe behavior, readiness, instrumentation, and failure
+callbacks. The default `bun run test` command runs the hermetic unit suite only
+so the live tests cannot share process state with the mocked `ioredis` tests.
+Set `REDIS_EVENT_BUS_TEST_URL` or the shared `REDIS_TEST_URL` before running
+the dedicated live test command:
+
+```bash
+REDIS_EVENT_BUS_TEST_URL=redis://localhost:6379 bun run test:live
+```

package/dist/index.d.ts

@@ -0,0 +1,101 @@
+/**
+ * @beignet/provider-event-bus-redis
+ *
+ * Redis Pub/Sub event bus provider that implements EventBusPort for
+ * cross-process, best-effort domain event delivery.
+ */
+import type { EventBusPort } from "@beignet/core/ports";
+import { type ProviderInstrumentationTarget } from "@beignet/core/providers";
+import { Redis } from "ioredis";
+import { z } from "zod";
+declare const RedisEventBusConfigSchema: z.ZodObject<{
+    URL: z.ZodString;
+    DB: z.ZodOptional<z.ZodUnion<readonly [z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>, z.ZodNumber]>>;
+    CHANNEL_PREFIX: z.ZodDefault<z.ZodString>;
+    CONNECT_TIMEOUT_MS: z.ZodDefault<z.ZodUnion<readonly [z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>, z.ZodNumber]>>;
+    MAX_RETRIES_PER_REQUEST: z.ZodDefault<z.ZodUnion<readonly [z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>, z.ZodNumber]>>;
+    CONNECT_MAX_ATTEMPTS: z.ZodDefault<z.ZodUnion<readonly [z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>, z.ZodNumber]>>;
+}, z.core.$strip>;
+export type RedisEventBusConfig = z.infer<typeof RedisEventBusConfigSchema>;
+export interface RedisEventBusPublisherClient {
+    publish(channel: string, message: string): Promise<number> | number;
+    ping?(): Promise<string> | string;
+}
+export interface RedisEventBusSubscriberClient {
+    subscribe(...channels: string[]): Promise<unknown> | unknown;
+    unsubscribe(...channels: string[]): Promise<unknown> | unknown;
+    on(event: "message", handler: (channel: string, message: string) => void): unknown;
+    off?(event: "message", handler: (channel: string, message: string) => void): unknown;
+    removeListener?(event: "message", handler: (channel: string, message: string) => void): unknown;
+    ping?(): Promise<string> | string;
+}
+export interface RedisEventBusHealth {
+    ok: boolean;
+    message?: string;
+    metadata: {
+        adapter: "redis-event-bus";
+        channelPrefix: string;
+        publisherResponse?: string;
+        subscriberResponse?: string;
+    };
+}
+export interface RedisEventBusEscapeHatch {
+    publisher: RedisEventBusPublisherClient;
+    subscriber: RedisEventBusSubscriberClient;
+    channelPrefix: string;
+    checkHealth(): Promise<RedisEventBusHealth>;
+}
+export interface RedisEventBusProviderPorts {
+    eventBus: EventBusPort;
+    redisEventBus: RedisEventBusEscapeHatch;
+}
+export interface CreateRedisEventBusOptions {
+    publisher: RedisEventBusPublisherClient;
+    subscriber: RedisEventBusSubscriberClient;
+    channelPrefix?: string;
+    instrumentation?: ProviderInstrumentationTarget;
+    onHandlerError?: (error: unknown, eventName: string, payload: unknown) => void;
+    onSubscriberError?: (error: unknown) => void;
+}
+export interface CreateRedisEventBusProviderOptions {
+    channelPrefix?: string;
+    connectTimeoutMs?: number;
+    maxRetriesPerRequest?: number;
+    retryStrategy?: (times: number) => number | null;
+    db?: number;
+}
+export declare function createRedisEventBus(options: CreateRedisEventBusOptions): EventBusPort;
+export declare function createRedisEventBusProvider(options?: CreateRedisEventBusProviderOptions): import("@beignet/core/providers").ServiceProvider<unknown, z.ZodObject<{
+    URL: z.ZodString;
+    DB: z.ZodOptional<z.ZodUnion<readonly [z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>, z.ZodNumber]>>;
+    CHANNEL_PREFIX: z.ZodDefault<z.ZodString>;
+    CONNECT_TIMEOUT_MS: z.ZodDefault<z.ZodUnion<readonly [z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>, z.ZodNumber]>>;
+    MAX_RETRIES_PER_REQUEST: z.ZodDefault<z.ZodUnion<readonly [z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>, z.ZodNumber]>>;
+    CONNECT_MAX_ATTEMPTS: z.ZodDefault<z.ZodUnion<readonly [z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>, z.ZodNumber]>>;
+}, z.core.$strip>, {
+    eventBus: EventBusPort;
+    redisEventBus: {
+        publisher: Redis;
+        subscriber: Redis;
+        channelPrefix: string;
+        checkHealth: () => Promise<RedisEventBusHealth>;
+    };
+}, unknown, void>;
+export declare const redisEventBusProvider: import("@beignet/core/providers").ServiceProvider<unknown, z.ZodObject<{
+    URL: z.ZodString;
+    DB: z.ZodOptional<z.ZodUnion<readonly [z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>, z.ZodNumber]>>;
+    CHANNEL_PREFIX: z.ZodDefault<z.ZodString>;
+    CONNECT_TIMEOUT_MS: z.ZodDefault<z.ZodUnion<readonly [z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>, z.ZodNumber]>>;
+    MAX_RETRIES_PER_REQUEST: z.ZodDefault<z.ZodUnion<readonly [z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>, z.ZodNumber]>>;
+    CONNECT_MAX_ATTEMPTS: z.ZodDefault<z.ZodUnion<readonly [z.ZodPipe<z.ZodString, z.ZodTransform<number, string>>, z.ZodNumber]>>;
+}, z.core.$strip>, {
+    eventBus: EventBusPort;
+    redisEventBus: {
+        publisher: Redis;
+        subscriber: Redis;
+        channelPrefix: string;
+        checkHealth: () => Promise<RedisEventBusHealth>;
+    };
+}, unknown, void>;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,328 @@
+/**
+ * @beignet/provider-event-bus-redis
+ *
+ * Redis Pub/Sub event bus provider that implements EventBusPort for
+ * cross-process, best-effort domain event delivery.
+ */
+import { createProvider, createProviderInstrumentation, } from "@beignet/core/providers";
+import { Redis } from "ioredis";
+import { z } from "zod";
+const DEFAULT_CONNECT_TIMEOUT_MS = 5000;
+const DEFAULT_MAX_RETRIES_PER_REQUEST = 2;
+const DEFAULT_CONNECT_MAX_ATTEMPTS = 3;
+const DEFAULT_CHANNEL_PREFIX = "beignet:event-bus:";
+const RECONNECT_BACKOFF_CAP_MS = 2000;
+const NumberString = z.union([
+    z
+        .string()
+        .regex(/^\d+$/, "Expected a non-negative integer string")
+        .transform((value) => Number.parseInt(value, 10)),
+    z.number().int().nonnegative(),
+]);
+const RedisEventBusConfigSchema = z.object({
+    URL: z.string().url(),
+    DB: NumberString.optional(),
+    CHANNEL_PREFIX: z.string().default(DEFAULT_CHANNEL_PREFIX),
+    CONNECT_TIMEOUT_MS: NumberString.default(DEFAULT_CONNECT_TIMEOUT_MS),
+    MAX_RETRIES_PER_REQUEST: NumberString.default(DEFAULT_MAX_RETRIES_PER_REQUEST),
+    CONNECT_MAX_ATTEMPTS: NumberString.default(DEFAULT_CONNECT_MAX_ATTEMPTS),
+});
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function redactConnectionUrl(url) {
+    try {
+        const parsed = new URL(url);
+        if (parsed.username)
+            parsed.username = "redacted";
+        if (parsed.password)
+            parsed.password = "redacted";
+        if (parsed.search)
+            parsed.search = "?redacted";
+        parsed.hash = "";
+        return parsed.toString();
+    }
+    catch {
+        return "[invalid URL]";
+    }
+}
+function reconnectBackoff(attempt) {
+    return Math.min(2 ** attempt * 100, RECONNECT_BACKOFF_CAP_MS);
+}
+function createRetryStrategy(connectMaxAttempts) {
+    let connectedOnce = false;
+    return {
+        strategy(attempt) {
+            if (!connectedOnce && attempt >= connectMaxAttempts) {
+                return null;
+            }
+            return reconnectBackoff(attempt);
+        },
+        markConnected() {
+            connectedOnce = true;
+        },
+    };
+}
+function channelForEvent(channelPrefix, eventName) {
+    return `${channelPrefix}${eventName}`;
+}
+function eventNameForChannel(channelPrefix, channel) {
+    if (channelPrefix === "")
+        return channel;
+    if (!channel.startsWith(channelPrefix))
+        return undefined;
+    return channel.slice(channelPrefix.length);
+}
+function safeJsonParse(input) {
+    return JSON.parse(input);
+}
+async function checkRedisEventBusHealth(publisher, subscriber, channelPrefix) {
+    try {
+        const [publisherResponse, subscriberResponse] = await Promise.all([
+            publisher.ping ? Promise.resolve(publisher.ping()) : Promise.resolve(""),
+            subscriber.ping
+                ? Promise.resolve(subscriber.ping())
+                : Promise.resolve(""),
+        ]);
+        return {
+            ok: true,
+            metadata: {
+                adapter: "redis-event-bus",
+                channelPrefix,
+                ...(publisherResponse ? { publisherResponse } : {}),
+                ...(subscriberResponse ? { subscriberResponse } : {}),
+            },
+        };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            message: errorMessage(error),
+            metadata: {
+                adapter: "redis-event-bus",
+                channelPrefix,
+            },
+        };
+    }
+}
+export function createRedisEventBus(options) {
+    const channelPrefix = options.channelPrefix ?? DEFAULT_CHANNEL_PREFIX;
+    const handlers = new Map();
+    const subscribedChannels = new Set();
+    const instrumentation = createProviderInstrumentation(options.instrumentation, {
+        providerName: "event-bus-redis",
+        watcher: "eventBus",
+    });
+    const reportSubscriberError = (error) => {
+        try {
+            options.onSubscriberError?.(error);
+        }
+        catch {
+            // Error callbacks should not create unhandled rejections.
+        }
+    };
+    const reportHandlerError = (error, eventName, payload) => {
+        instrumentation.custom({
+            name: "eventBus.handler.failed",
+            label: "Event handler failed",
+            summary: `Handler failed for "${eventName}"`,
+            details: {
+                eventName,
+                error: errorMessage(error),
+            },
+        });
+        try {
+            options.onHandlerError?.(error, eventName, payload);
+        }
+        catch {
+            // Error callbacks should not create unhandled rejections.
+        }
+    };
+    const messageHandler = (channel, message) => {
+        const eventName = eventNameForChannel(channelPrefix, channel);
+        if (!eventName)
+            return;
+        const eventHandlers = handlers.get(eventName);
+        if (!eventHandlers || eventHandlers.size === 0)
+            return;
+        let payload;
+        try {
+            const parsed = safeJsonParse(message);
+            if (typeof parsed !== "object" ||
+                parsed === null ||
+                !("payload" in parsed)) {
+                throw new Error("Redis event bus message is missing a payload field.");
+            }
+            payload = parsed.payload;
+        }
+        catch (error) {
+            reportSubscriberError(error);
+            return;
+        }
+        instrumentation.custom({
+            name: "eventBus.received",
+            label: "Event received",
+            summary: `Received "${eventName}"`,
+            details: { eventName },
+        });
+        for (const handler of [...eventHandlers]) {
+            try {
+                Promise.resolve(handler(payload)).catch((error) => {
+                    reportHandlerError(error, eventName, payload);
+                });
+            }
+            catch (error) {
+                reportHandlerError(error, eventName, payload);
+            }
+        }
+    };
+    options.subscriber.on("message", messageHandler);
+    const ensureSubscribed = (eventName) => {
+        const channel = channelForEvent(channelPrefix, eventName);
+        if (subscribedChannels.has(channel))
+            return;
+        subscribedChannels.add(channel);
+        Promise.resolve(options.subscriber.subscribe(channel)).catch((error) => {
+            subscribedChannels.delete(channel);
+            reportSubscriberError(error);
+        });
+    };
+    const unsubscribeChannel = (eventName) => {
+        const channel = channelForEvent(channelPrefix, eventName);
+        if (!subscribedChannels.delete(channel))
+            return;
+        Promise.resolve(options.subscriber.unsubscribe(channel)).catch(reportSubscriberError);
+    };
+    return {
+        async publish(event, payload) {
+            instrumentation.record({
+                type: "eventBus",
+                eventName: event.name,
+            });
+            await options.publisher.publish(channelForEvent(channelPrefix, event.name), JSON.stringify({ eventName: event.name, payload }));
+        },
+        subscribe(event, handler) {
+            let eventHandlers = handlers.get(event.name);
+            if (!eventHandlers) {
+                eventHandlers = new Set();
+                handlers.set(event.name, eventHandlers);
+            }
+            eventHandlers.add(handler);
+            ensureSubscribed(event.name);
+            return () => {
+                const currentHandlers = handlers.get(event.name);
+                if (!currentHandlers)
+                    return;
+                currentHandlers.delete(handler);
+                if (currentHandlers.size === 0) {
+                    handlers.delete(event.name);
+                    unsubscribeChannel(event.name);
+                }
+            };
+        },
+    };
+}
+export function createRedisEventBusProvider(options = {}) {
+    const providerMetadata = {
+        packageName: "@beignet/provider-event-bus-redis",
+        ports: ["eventBus", "redisEventBus"],
+        env: [
+            "REDIS_EVENT_BUS_URL",
+            "REDIS_EVENT_BUS_DB",
+            "REDIS_EVENT_BUS_CHANNEL_PREFIX",
+            "REDIS_EVENT_BUS_CONNECT_TIMEOUT_MS",
+            "REDIS_EVENT_BUS_MAX_RETRIES_PER_REQUEST",
+            "REDIS_EVENT_BUS_CONNECT_MAX_ATTEMPTS",
+        ],
+        watchers: ["eventBus"],
+    };
+    return createProvider({
+        name: "event-bus-redis",
+        metadata: providerMetadata,
+        config: {
+            schema: RedisEventBusConfigSchema,
+            envPrefix: "REDIS_EVENT_BUS_",
+            // Defined options win over env-derived values at config load time.
+            overrides: {
+                DB: options.db,
+                CHANNEL_PREFIX: options.channelPrefix,
+                CONNECT_TIMEOUT_MS: options.connectTimeoutMs,
+                MAX_RETRIES_PER_REQUEST: options.maxRetriesPerRequest,
+            },
+        },
+        async setup({ config, ports }) {
+            if (!config) {
+                throw new Error("[redisEventBusProvider] Missing Redis event bus config. " +
+                    "Please set REDIS_EVENT_BUS_URL.");
+            }
+            const configuredChannelPrefix = config.CHANNEL_PREFIX ??
+                options.channelPrefix ??
+                DEFAULT_CHANNEL_PREFIX;
+            const connectMaxAttempts = config.CONNECT_MAX_ATTEMPTS ?? DEFAULT_CONNECT_MAX_ATTEMPTS;
+            const publisherRetry = createRetryStrategy(connectMaxAttempts);
+            const subscriberRetry = createRetryStrategy(connectMaxAttempts);
+            const redisOptions = {
+                db: config.DB ?? options.db ?? 0,
+                lazyConnect: true,
+                connectTimeout: config.CONNECT_TIMEOUT_MS ??
+                    options.connectTimeoutMs ??
+                    DEFAULT_CONNECT_TIMEOUT_MS,
+                maxRetriesPerRequest: config.MAX_RETRIES_PER_REQUEST ??
+                    options.maxRetriesPerRequest ??
+                    DEFAULT_MAX_RETRIES_PER_REQUEST,
+            };
+            const publisher = new Redis(config.URL, {
+                ...redisOptions,
+                retryStrategy: options.retryStrategy ?? publisherRetry.strategy,
+            });
+            const subscriber = new Redis(config.URL, {
+                ...redisOptions,
+                retryStrategy: options.retryStrategy ?? subscriberRetry.strategy,
+            });
+            try {
+                await publisher.connect();
+                publisherRetry.markConnected();
+                await subscriber.connect();
+                subscriberRetry.markConnected();
+            }
+            catch (error) {
+                publisher.disconnect();
+                subscriber.disconnect();
+                throw new Error(`[redisEventBusProvider] Failed to connect to Redis at ${redactConnectionUrl(config.URL)}: ${errorMessage(error)}`);
+            }
+            const eventBus = createRedisEventBus({
+                publisher,
+                subscriber,
+                channelPrefix: configuredChannelPrefix,
+                instrumentation: ports,
+            });
+            return {
+                ports: {
+                    eventBus,
+                    redisEventBus: {
+                        publisher,
+                        subscriber,
+                        channelPrefix: configuredChannelPrefix,
+                        checkHealth: () => checkRedisEventBusHealth(publisher, subscriber, configuredChannelPrefix),
+                    },
+                },
+                async stop() {
+                    try {
+                        await subscriber.quit();
+                    }
+                    catch {
+                        subscriber.disconnect();
+                    }
+                    try {
+                        await publisher.quit();
+                    }
+                    catch {
+                        publisher.disconnect();
+                    }
+                },
+            };
+        },
+    });
+}
+export const redisEventBusProvider = createRedisEventBusProvider();
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,107 @@
+{
+  "name": "@beignet/provider-event-bus-redis",
+  "version": "0.0.33",
+  "type": "module",
+  "description": "Redis Pub/Sub event bus provider for Beignet - implements EventBusPort for cross-process best-effort delivery",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/*.test-d.ts",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepack": "bun run build",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist coverage .turbo",
+    "test": "bun test src/index.test.ts",
+    "test:live": "bun test src/redis-live.test.ts",
+    "test:coverage": "bun test --coverage src/index.test.ts",
+    "lint": "biome check ."
+  },
+  "keywords": [
+    "beignet",
+    "event-bus",
+    "redis",
+    "provider",
+    "pubsub",
+    "ports"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/taylorbryant/beignet.git",
+    "directory": "packages/provider-event-bus-redis"
+  },
+  "author": "Taylor Bryant",
+  "homepage": "https://github.com/taylorbryant/beignet#readme",
+  "bugs": "https://github.com/taylorbryant/beignet/issues",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "peerDependencies": {
+    "@beignet/core": ">=0.0.3 <1.0.0",
+    "ioredis": "^5.0.0"
+  },
+  "dependencies": {
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@beignet/devtools": "*",
+    "@types/bun": "^1.3.13",
+    "@types/node": "^20.10.0",
+    "ioredis": "^5.0.0",
+    "typescript": "^5.3.0"
+  },
+  "beignet": {
+    "provider": {
+      "displayName": "Redis event bus provider",
+      "ports": [
+        "eventBus",
+        "redisEventBus"
+      ],
+      "appPorts": [
+        {
+          "name": "eventBus",
+          "type": "EventBusPort"
+        }
+      ],
+      "env": [
+        "REDIS_EVENT_BUS_URL",
+        "REDIS_EVENT_BUS_DB",
+        "REDIS_EVENT_BUS_CHANNEL_PREFIX",
+        "REDIS_EVENT_BUS_CONNECT_TIMEOUT_MS",
+        "REDIS_EVENT_BUS_MAX_RETRIES_PER_REQUEST",
+        "REDIS_EVENT_BUS_CONNECT_MAX_ATTEMPTS"
+      ],
+      "requiredEnv": [
+        "REDIS_EVENT_BUS_URL"
+      ],
+      "watchers": [
+        "eventBus"
+      ],
+      "registration": {
+        "required": true,
+        "tokens": [
+          "redisEventBusProvider",
+          "createRedisEventBusProvider"
+        ]
+      }
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,480 @@
+/**
+ * @beignet/provider-event-bus-redis
+ *
+ * Redis Pub/Sub event bus provider that implements EventBusPort for
+ * cross-process, best-effort domain event delivery.
+ */
+
+import type {
+  DomainEventDef,
+  EventBusPort,
+  InferEventPayload,
+} from "@beignet/core/ports";
+import {
+  createProvider,
+  createProviderInstrumentation,
+  type ProviderInstrumentationTarget,
+} from "@beignet/core/providers";
+import { Redis } from "ioredis";
+import { z } from "zod";
+
+const DEFAULT_CONNECT_TIMEOUT_MS = 5000;
+const DEFAULT_MAX_RETRIES_PER_REQUEST = 2;
+const DEFAULT_CONNECT_MAX_ATTEMPTS = 3;
+const DEFAULT_CHANNEL_PREFIX = "beignet:event-bus:";
+const RECONNECT_BACKOFF_CAP_MS = 2000;
+
+const NumberString = z.union([
+  z
+    .string()
+    .regex(/^\d+$/, "Expected a non-negative integer string")
+    .transform((value) => Number.parseInt(value, 10)),
+  z.number().int().nonnegative(),
+]);
+
+const RedisEventBusConfigSchema = z.object({
+  URL: z.string().url(),
+  DB: NumberString.optional(),
+  CHANNEL_PREFIX: z.string().default(DEFAULT_CHANNEL_PREFIX),
+  CONNECT_TIMEOUT_MS: NumberString.default(DEFAULT_CONNECT_TIMEOUT_MS),
+  MAX_RETRIES_PER_REQUEST: NumberString.default(
+    DEFAULT_MAX_RETRIES_PER_REQUEST,
+  ),
+  CONNECT_MAX_ATTEMPTS: NumberString.default(DEFAULT_CONNECT_MAX_ATTEMPTS),
+});
+
+export type RedisEventBusConfig = z.infer<typeof RedisEventBusConfigSchema>;
+
+export interface RedisEventBusPublisherClient {
+  publish(channel: string, message: string): Promise<number> | number;
+  ping?(): Promise<string> | string;
+}
+
+export interface RedisEventBusSubscriberClient {
+  subscribe(...channels: string[]): Promise<unknown> | unknown;
+  unsubscribe(...channels: string[]): Promise<unknown> | unknown;
+  on(
+    event: "message",
+    handler: (channel: string, message: string) => void,
+  ): unknown;
+  off?(
+    event: "message",
+    handler: (channel: string, message: string) => void,
+  ): unknown;
+  removeListener?(
+    event: "message",
+    handler: (channel: string, message: string) => void,
+  ): unknown;
+  ping?(): Promise<string> | string;
+}
+
+export interface RedisEventBusHealth {
+  ok: boolean;
+  message?: string;
+  metadata: {
+    adapter: "redis-event-bus";
+    channelPrefix: string;
+    publisherResponse?: string;
+    subscriberResponse?: string;
+  };
+}
+
+export interface RedisEventBusEscapeHatch {
+  publisher: RedisEventBusPublisherClient;
+  subscriber: RedisEventBusSubscriberClient;
+  channelPrefix: string;
+  checkHealth(): Promise<RedisEventBusHealth>;
+}
+
+export interface RedisEventBusProviderPorts {
+  eventBus: EventBusPort;
+  redisEventBus: RedisEventBusEscapeHatch;
+}
+
+export interface CreateRedisEventBusOptions {
+  publisher: RedisEventBusPublisherClient;
+  subscriber: RedisEventBusSubscriberClient;
+  channelPrefix?: string;
+  instrumentation?: ProviderInstrumentationTarget;
+  onHandlerError?: (
+    error: unknown,
+    eventName: string,
+    payload: unknown,
+  ) => void;
+  onSubscriberError?: (error: unknown) => void;
+}
+
+export interface CreateRedisEventBusProviderOptions {
+  channelPrefix?: string;
+  connectTimeoutMs?: number;
+  maxRetriesPerRequest?: number;
+  retryStrategy?: (times: number) => number | null;
+  db?: number;
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function redactConnectionUrl(url: string): string {
+  try {
+    const parsed = new URL(url);
+    if (parsed.username) parsed.username = "redacted";
+    if (parsed.password) parsed.password = "redacted";
+    if (parsed.search) parsed.search = "?redacted";
+    parsed.hash = "";
+    return parsed.toString();
+  } catch {
+    return "[invalid URL]";
+  }
+}
+
+function reconnectBackoff(attempt: number): number {
+  return Math.min(2 ** attempt * 100, RECONNECT_BACKOFF_CAP_MS);
+}
+
+function createRetryStrategy(connectMaxAttempts: number): {
+  strategy: (attempt: number) => number | null;
+  markConnected: () => void;
+} {
+  let connectedOnce = false;
+
+  return {
+    strategy(attempt) {
+      if (!connectedOnce && attempt >= connectMaxAttempts) {
+        return null;
+      }
+      return reconnectBackoff(attempt);
+    },
+    markConnected() {
+      connectedOnce = true;
+    },
+  };
+}
+
+function channelForEvent(channelPrefix: string, eventName: string): string {
+  return `${channelPrefix}${eventName}`;
+}
+
+function eventNameForChannel(
+  channelPrefix: string,
+  channel: string,
+): string | undefined {
+  if (channelPrefix === "") return channel;
+  if (!channel.startsWith(channelPrefix)) return undefined;
+  return channel.slice(channelPrefix.length);
+}
+
+function safeJsonParse(input: string): unknown {
+  return JSON.parse(input) as unknown;
+}
+
+async function checkRedisEventBusHealth(
+  publisher: RedisEventBusPublisherClient,
+  subscriber: RedisEventBusSubscriberClient,
+  channelPrefix: string,
+): Promise<RedisEventBusHealth> {
+  try {
+    const [publisherResponse, subscriberResponse] = await Promise.all([
+      publisher.ping ? Promise.resolve(publisher.ping()) : Promise.resolve(""),
+      subscriber.ping
+        ? Promise.resolve(subscriber.ping())
+        : Promise.resolve(""),
+    ]);
+
+    return {
+      ok: true,
+      metadata: {
+        adapter: "redis-event-bus",
+        channelPrefix,
+        ...(publisherResponse ? { publisherResponse } : {}),
+        ...(subscriberResponse ? { subscriberResponse } : {}),
+      },
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      message: errorMessage(error),
+      metadata: {
+        adapter: "redis-event-bus",
+        channelPrefix,
+      },
+    };
+  }
+}
+
+export function createRedisEventBus(
+  options: CreateRedisEventBusOptions,
+): EventBusPort {
+  const channelPrefix = options.channelPrefix ?? DEFAULT_CHANNEL_PREFIX;
+  const handlers = new Map<
+    string,
+    Set<(payload: unknown) => void | Promise<void>>
+  >();
+  const subscribedChannels = new Set<string>();
+  const instrumentation = createProviderInstrumentation(
+    options.instrumentation,
+    {
+      providerName: "event-bus-redis",
+      watcher: "eventBus",
+    },
+  );
+
+  const reportSubscriberError = (error: unknown) => {
+    try {
+      options.onSubscriberError?.(error);
+    } catch {
+      // Error callbacks should not create unhandled rejections.
+    }
+  };
+
+  const reportHandlerError = (
+    error: unknown,
+    eventName: string,
+    payload: unknown,
+  ) => {
+    instrumentation.custom({
+      name: "eventBus.handler.failed",
+      label: "Event handler failed",
+      summary: `Handler failed for "${eventName}"`,
+      details: {
+        eventName,
+        error: errorMessage(error),
+      },
+    });
+
+    try {
+      options.onHandlerError?.(error, eventName, payload);
+    } catch {
+      // Error callbacks should not create unhandled rejections.
+    }
+  };
+
+  const messageHandler = (channel: string, message: string) => {
+    const eventName = eventNameForChannel(channelPrefix, channel);
+    if (!eventName) return;
+
+    const eventHandlers = handlers.get(eventName);
+    if (!eventHandlers || eventHandlers.size === 0) return;
+
+    let payload: unknown;
+    try {
+      const parsed = safeJsonParse(message);
+      if (
+        typeof parsed !== "object" ||
+        parsed === null ||
+        !("payload" in parsed)
+      ) {
+        throw new Error("Redis event bus message is missing a payload field.");
+      }
+      payload = (parsed as { payload: unknown }).payload;
+    } catch (error) {
+      reportSubscriberError(error);
+      return;
+    }
+
+    instrumentation.custom({
+      name: "eventBus.received",
+      label: "Event received",
+      summary: `Received "${eventName}"`,
+      details: { eventName },
+    });
+
+    for (const handler of [...eventHandlers]) {
+      try {
+        Promise.resolve(handler(payload)).catch((error: unknown) => {
+          reportHandlerError(error, eventName, payload);
+        });
+      } catch (error) {
+        reportHandlerError(error, eventName, payload);
+      }
+    }
+  };
+
+  options.subscriber.on("message", messageHandler);
+
+  const ensureSubscribed = (eventName: string) => {
+    const channel = channelForEvent(channelPrefix, eventName);
+    if (subscribedChannels.has(channel)) return;
+    subscribedChannels.add(channel);
+    Promise.resolve(options.subscriber.subscribe(channel)).catch((error) => {
+      subscribedChannels.delete(channel);
+      reportSubscriberError(error);
+    });
+  };
+
+  const unsubscribeChannel = (eventName: string) => {
+    const channel = channelForEvent(channelPrefix, eventName);
+    if (!subscribedChannels.delete(channel)) return;
+    Promise.resolve(options.subscriber.unsubscribe(channel)).catch(
+      reportSubscriberError,
+    );
+  };
+
+  return {
+    async publish(event, payload) {
+      instrumentation.record({
+        type: "eventBus",
+        eventName: event.name,
+      });
+
+      await options.publisher.publish(
+        channelForEvent(channelPrefix, event.name),
+        JSON.stringify({ eventName: event.name, payload }),
+      );
+    },
+
+    subscribe<E extends DomainEventDef>(
+      event: E,
+      handler: (payload: InferEventPayload<E>) => void | Promise<void>,
+    ) {
+      let eventHandlers = handlers.get(event.name);
+      if (!eventHandlers) {
+        eventHandlers = new Set();
+        handlers.set(event.name, eventHandlers);
+      }
+
+      eventHandlers.add(handler as (payload: unknown) => void | Promise<void>);
+      ensureSubscribed(event.name);
+
+      return () => {
+        const currentHandlers = handlers.get(event.name);
+        if (!currentHandlers) return;
+        currentHandlers.delete(
+          handler as (payload: unknown) => void | Promise<void>,
+        );
+        if (currentHandlers.size === 0) {
+          handlers.delete(event.name);
+          unsubscribeChannel(event.name);
+        }
+      };
+    },
+  };
+}
+
+export function createRedisEventBusProvider(
+  options: CreateRedisEventBusProviderOptions = {},
+) {
+  const providerMetadata = {
+    packageName: "@beignet/provider-event-bus-redis",
+    ports: ["eventBus", "redisEventBus"],
+    env: [
+      "REDIS_EVENT_BUS_URL",
+      "REDIS_EVENT_BUS_DB",
+      "REDIS_EVENT_BUS_CHANNEL_PREFIX",
+      "REDIS_EVENT_BUS_CONNECT_TIMEOUT_MS",
+      "REDIS_EVENT_BUS_MAX_RETRIES_PER_REQUEST",
+      "REDIS_EVENT_BUS_CONNECT_MAX_ATTEMPTS",
+    ],
+    watchers: ["eventBus"],
+  } as const;
+
+  return createProvider({
+    name: "event-bus-redis",
+    metadata: providerMetadata,
+
+    config: {
+      schema: RedisEventBusConfigSchema,
+      envPrefix: "REDIS_EVENT_BUS_",
+      // Defined options win over env-derived values at config load time.
+      overrides: {
+        DB: options.db,
+        CHANNEL_PREFIX: options.channelPrefix,
+        CONNECT_TIMEOUT_MS: options.connectTimeoutMs,
+        MAX_RETRIES_PER_REQUEST: options.maxRetriesPerRequest,
+      },
+    },
+
+    async setup({ config, ports }) {
+      if (!config) {
+        throw new Error(
+          "[redisEventBusProvider] Missing Redis event bus config. " +
+            "Please set REDIS_EVENT_BUS_URL.",
+        );
+      }
+
+      const configuredChannelPrefix =
+        config.CHANNEL_PREFIX ??
+        options.channelPrefix ??
+        DEFAULT_CHANNEL_PREFIX;
+      const connectMaxAttempts =
+        config.CONNECT_MAX_ATTEMPTS ?? DEFAULT_CONNECT_MAX_ATTEMPTS;
+      const publisherRetry = createRetryStrategy(connectMaxAttempts);
+      const subscriberRetry = createRetryStrategy(connectMaxAttempts);
+      const redisOptions = {
+        db: config.DB ?? options.db ?? 0,
+        lazyConnect: true,
+        connectTimeout:
+          config.CONNECT_TIMEOUT_MS ??
+          options.connectTimeoutMs ??
+          DEFAULT_CONNECT_TIMEOUT_MS,
+        maxRetriesPerRequest:
+          config.MAX_RETRIES_PER_REQUEST ??
+          options.maxRetriesPerRequest ??
+          DEFAULT_MAX_RETRIES_PER_REQUEST,
+      };
+
+      const publisher = new Redis(config.URL, {
+        ...redisOptions,
+        retryStrategy: options.retryStrategy ?? publisherRetry.strategy,
+      });
+      const subscriber = new Redis(config.URL, {
+        ...redisOptions,
+        retryStrategy: options.retryStrategy ?? subscriberRetry.strategy,
+      });
+
+      try {
+        await publisher.connect();
+        publisherRetry.markConnected();
+        await subscriber.connect();
+        subscriberRetry.markConnected();
+      } catch (error) {
+        publisher.disconnect();
+        subscriber.disconnect();
+        throw new Error(
+          `[redisEventBusProvider] Failed to connect to Redis at ${redactConnectionUrl(
+            config.URL,
+          )}: ${errorMessage(error)}`,
+        );
+      }
+
+      const eventBus = createRedisEventBus({
+        publisher,
+        subscriber,
+        channelPrefix: configuredChannelPrefix,
+        instrumentation: ports,
+      });
+
+      return {
+        ports: {
+          eventBus,
+          redisEventBus: {
+            publisher,
+            subscriber,
+            channelPrefix: configuredChannelPrefix,
+            checkHealth: () =>
+              checkRedisEventBusHealth(
+                publisher,
+                subscriber,
+                configuredChannelPrefix,
+              ),
+          },
+        } satisfies RedisEventBusProviderPorts,
+        async stop() {
+          try {
+            await subscriber.quit();
+          } catch {
+            subscriber.disconnect();
+          }
+          try {
+            await publisher.quit();
+          } catch {
+            publisher.disconnect();
+          }
+        },
+      };
+    },
+  });
+}
+
+export const redisEventBusProvider = createRedisEventBusProvider();