@beignet/provider-event-bus-redis 0.0.48 → 0.0.50

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @beignet/provider-event-bus-redis
 
+## 0.0.50
+
+### Patch Changes
+
+- 6fe026a: Expose event-subscription readiness and asynchronous cleanup, await listener
+  registries during provider startup with bounded rollback, diagnose unsafe app
+  wiring, and make Redis subscription lifecycle failures observable with bounded
+  provider shutdown and recoverable channel state.
+
+## 0.0.49
+
+### Patch Changes
+
+- e597d53: Require Node.js 22.12 or newer across every Beignet package, generated app,
+  and documented workflow.
+
 ## 0.0.48
 
 ## 0.0.47

package/README.md

@@ -1,5 +1,8 @@
 # @beignet/provider-event-bus-redis
 
+> **Runtime:** Beignet requires Node.js 22.12 or newer. Bun 1.3.14 or newer is
+> supported for Beignet commands.
+
 > [!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.
@@ -65,6 +68,7 @@ The provider reads environment variables with the `REDIS_EVENT_BUS_` prefix:
 | `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_CLEANUP_TIMEOUT_MS` | No | Shutdown deadline for subscription cleanup in milliseconds. Defaults to `10000`. | `5000` |
 | `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` |
 
@@ -80,6 +84,7 @@ import { createRedisEventBusProvider } from "@beignet/provider-event-bus-redis";
 const provider = createRedisEventBusProvider({
   channelPrefix: "my-app:events:",
   connectTimeoutMs: 2000,
+  cleanupTimeoutMs: 5000,
   maxRetriesPerRequest: 1,
   db: 1,
   retryStrategy: (times) => Math.min(times * 100, 1000),
@@ -128,7 +133,17 @@ Use `createRedisEventBus(...)` when your app owns Redis clients:
 
 ```typescript
 import Redis from "ioredis";
+import { defineEvent } from "@beignet/core/events";
 import { createRedisEventBus } from "@beignet/provider-event-bus-redis";
+import { z } from "zod";
+
+const UserRegistered = defineEvent("user.registered", {
+  payload: z.object({ userId: z.string() }),
+});
+
+function handleUserRegistered(payload: { userId: string }) {
+  console.log(`Registered ${payload.userId}`);
+}
 
 const publisher = new Redis(process.env.REDIS_EVENT_BUS_URL);
 const subscriber = new Redis(process.env.REDIS_EVENT_BUS_URL);
@@ -138,25 +153,47 @@ const eventBus = createRedisEventBus({
   channelPrefix: "my-app:events:",
 });
 
+const subscription = eventBus.subscribe(UserRegistered, handleUserRegistered);
+await subscription.ready;
+
 // During app shutdown:
-await eventBus.stop();
-await Promise.all([publisher.quit(), subscriber.quit()]);
+try {
+  await eventBus.stop();
+  await Promise.all([publisher.quit(), subscriber.quit()]);
+} catch (error) {
+  subscriber.disconnect();
+  publisher.disconnect();
+  throw error;
+}
 ```
 
-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. Await `stop()` to detach Beignet's message
-listener, cancel pending subscription retries, and best-effort unsubscribe the
-channels registered through that adapter. It does not close the caller-owned
-Redis clients. Stopping is terminal for that adapter: later subscription
-attempts reject instead of creating handlers that cannot receive messages.
+Register listeners during startup before handling traffic and await each
+subscription's `ready` promise. It resolves after Redis acknowledges the
+channel subscription. Failed subscription commands retry with capped backoff
+while a local handler remains; callers can own a deadline, and
+`registerListeners(...)` applies one 10-second deadline to a complete registry
+by default. Readiness proves initial registration only and does not change
+Pub/Sub's online-only delivery semantics.
+
+Await `unsubscribe()` when removing an individual handler. During adapter
+shutdown, `stop()` closes all remaining subscriptions, detaches local delivery,
+cancels pending retries, and awaits channel cleanup. Cleanup errors reject and
+are instrumented; `stop()` retries channels left dirty by an earlier
+unsubscribe before reporting any remaining failure. To keep lifecycle rollback
+bounded, `stop()` rejects after `cleanupTimeoutMs` (10 seconds by default) even
+if an ioredis command never settles. The adapter does not close caller-owned
+Redis clients, so force-disconnect them when cleanup rejects. Stopping is
+terminal: later subscription attempts reject instead of creating handlers that
+cannot receive messages.
 
 ## Delivery semantics
 
 - `publish(...)` publishes one Redis Pub/Sub message on
   `<channelPrefix><event.name>`.
 - Only subscribers that are online and currently subscribed receive the event.
+- A subscription's `ready` promise resolves only after the initial Redis
+  subscription acknowledgement. Cancelling before acknowledgement rejects that
+  promise and prevents future local delivery.
 - ioredis resubscribes after a transient reconnect, but messages published
   during the disconnected interval are not recovered.
 - Payloads are JSON encoded and delivered to handlers without persisting the

package/dist/index.d.ts

@@ -14,6 +14,7 @@ export interface RedisEventBusConfig {
     DB?: number;
     CHANNEL_PREFIX: string;
     CONNECT_TIMEOUT_MS: number;
+    CLEANUP_TIMEOUT_MS: number;
     MAX_RETRIES_PER_REQUEST: number;
     CONNECT_MAX_ATTEMPTS: number;
 }
@@ -57,6 +58,8 @@ export interface CreateRedisEventBusOptions {
     publisher: RedisEventBusPublisherClient;
     subscriber: RedisEventBusSubscriberClient;
     channelPrefix?: string;
+    /** Maximum time to await subscription cleanup before `stop()` rejects. */
+    cleanupTimeoutMs?: number;
     instrumentation?: ProviderInstrumentationTarget;
     onHandlerError?: (error: unknown, eventName: string, payload: unknown) => void;
     onSubscriberError?: (error: unknown) => void;
@@ -64,6 +67,8 @@ export interface CreateRedisEventBusOptions {
 export interface CreateRedisEventBusProviderOptions {
     channelPrefix?: string;
     connectTimeoutMs?: number;
+    /** Maximum time to await subscription cleanup before forcing disconnect. */
+    cleanupTimeoutMs?: number;
     maxRetriesPerRequest?: number;
     retryStrategy?: (times: number) => number | null;
     db?: number;
@@ -77,8 +82,8 @@ export interface CreateRedisEventBusProviderOptions {
  */
 export interface RedisEventBus extends EventBusPort {
     /**
-     * Stop local delivery and best-effort unsubscribe the adapter's channels
-     * without closing the caller-owned Redis clients.
+     * Stop local delivery and await cleanup of the adapter's channels without
+     * closing the caller-owned Redis clients.
      */
     stop(): Promise<void>;
 }

package/dist/index.d.ts.map

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