@voltro/plugin-broadcast 0.85.0 → 0.87.0

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 import { ChangeEvent } from '@voltro/database';
+import { ConnectionPubSub } from '@voltro/kv/connection';
+import { ConnectionRef } from '@voltro/kv/connection';
 import { Effect } from 'effect';
 import { Schema } from 'effect';
 import { VoltroPlugin } from '@voltro/protocol';
@@ -72,6 +74,12 @@ export declare interface BroadcastBusLogger {
  *  `voltro start` WEB process rather than an api replica. */
 export declare type BroadcastChannelKind = 'changes' | 'events' | 'members' | 'presence' | 'revalidate';
 
+export declare interface BroadcastConnectionSelection {
+    readonly role: string;
+    readonly kind: 'redis' | 'nats';
+    readonly reference?: BrokerReference;
+}
+
 /**
  * What rides the wire on the `voltro:changes` channel. `origin` is the
  * publishing replica's id; subscribers skip their OWN origin (the writer
@@ -193,7 +201,6 @@ export declare interface BroadcastHealth {
 export declare interface BroadcastPlugin extends VoltroPlugin {
     readonly broadcast: {
         readonly provider: BroadcastProvider;
-        readonly url: string | null;
         readonly crossReplica: boolean;
         /**
          * The namespace as DECLARED here, before the app name or env is consulted.
@@ -208,18 +215,14 @@ export declare const broadcastPlugin: (options?: BroadcastPluginOptions) => Broa
 
 export declare interface BroadcastPluginOptions {
     /** Provider name (`'redis' | 'nats' | 'memory'`) or a pre-built
-     *  `BroadcastProvider`. Default: inferred from `BROADCAST_URL` /
-     *  `BROADCAST_PROVIDER` / `REDIS_URL` env, else `'memory'`. */
+     *  `BroadcastProvider`. Default: reference kind, provider Env or registry endpoint Env, else memory. */
     readonly provider?: BroadcastProviderName | BroadcastProvider;
-    /** Broker URL — a broker-agnostic override (redis:// or nats://). Takes
-     *  precedence over the named-connection env. Default `BROADCAST_URL` env. */
-    readonly url?: string;
-    /** Named connection for the redis provider — resolves the broker URL via the
-     *  shared convention `<NAME>_REDIS_URL` → `REDIS_URL` (like cache / kv /
-     *  ratelimit). Default `'broadcast'` (→ `BROADCAST_REDIS_URL`, then
-     *  `REDIS_URL`). Point broadcast at its own server or the shared one purely
-     *  by which env var you set. */
-    readonly connection?: string;
+    /** Default broker reference. Endpoints and credentials belong in app connections. */
+    readonly connection?: ConnectionRef<'redis' | 'nats'>;
+    readonly events?: ConnectionRef<'redis' | 'nats'>;
+    readonly members?: ConnectionRef<'redis' | 'nats'>;
+    readonly presence?: ConnectionRef<'redis' | 'nats'>;
+    readonly revalidate?: ConnectionRef<'redis' | 'nats'>;
     /**
      * Namespace for EVERY framework channel on this broker — changes, events,
      * membership and presence alike.
@@ -299,6 +302,8 @@ export declare interface BroadcastTransportEvent {
     readonly detail?: string;
 }
 
+declare type BrokerReference = ConnectionRef<'redis' | 'nats'>;
+
 /**
  * One framework channel inside a namespace.
  *
@@ -362,63 +367,17 @@ export declare const getBroadcastPlugin: (plugins: ReadonlyArray<VoltroPlugin>)
  */
 export declare const memoryProvider: (bus?: string) => BroadcastProvider;
 
-declare interface NatsLike {
-    publish: (subject: string, data: Uint8Array) => void;
-    subscribe: (subject: string) => NatsSubscription;
-    drain: () => Promise<void>;
-    /** nats.js' connection events. Read for two reasons: to report a reconnect as
-     *  the hole it is, and to notice a connection that gave up. */
-    status: () => AsyncIterable<{
-        type: string;
-        data?: unknown;
-    }>;
-}
-
 export declare const natsProvider: (options: NatsProviderOptions) => BroadcastProvider;
 
-export declare interface NatsProviderOptions {
-    /** `nats://host:port` (comma-separated for a cluster). Required. */
-    readonly url: string;
-    /** Bring your own connected NATS connection (e.g. for shared creds). */
-    readonly connection?: NatsLike;
-}
-
-declare interface NatsSubscription extends AsyncIterable<{
-    data: Uint8Array;
-}> {
-    unsubscribe: () => void;
-}
-
-/** The slice of ioredis the provider touches — keeps the optional dep out
- *  of the type surface. */
-declare interface RedisLike {
-    publish: (channel: string, message: string) => Promise<number>;
-    subscribe: (channel: string) => Promise<unknown>;
-    unsubscribe: (channel: string) => Promise<unknown>;
-    on(event: 'message', listener: (channel: string, message: string) => void): void;
-    /** ioredis' connection lifecycle. The subscriber re-subscribes its channels
-     *  itself on `ready`; what it does NOT do is tell anyone that the messages
-     *  sent while it was away are gone. That is what these are read for. */
-    on(event: 'ready' | 'reconnecting' | 'end' | 'close', listener: () => void): void;
-    /** `error` is REQUIRED, not optional decoration: an `EventEmitter` with no
-     *  `error` listener turns the event into an uncaught exception. See the
-     *  registration below. */
-    on(event: 'error', listener: (err: unknown) => void): void;
-    off(event: 'message', listener: (channel: string, message: string) => void): void;
-    off(event: 'ready' | 'reconnecting' | 'end' | 'close', listener: () => void): void;
-    duplicate: () => RedisLike;
-    quit: () => Promise<unknown>;
+export declare interface NatsProviderOptions extends RedisProviderOptions {
 }
 
+/** Both adapters borrow the same consumer contract; neither owns a broker. */
 export declare const redisProvider: (options: RedisProviderOptions) => BroadcastProvider;
 
 export declare interface RedisProviderOptions {
-    /** `redis://[:pass@]host:port[/db]`. Required. */
-    readonly url: string;
-    /** Bring your own ioredis client (publisher). A `subscriber` is
-     *  `client.duplicate()`d internally — a RESP connection in subscribe
-     *  mode can't issue normal commands. */
-    readonly client?: RedisLike;
+    /** Acquire a consumer from the app's ConnectionRegistry, never a raw socket. */
+    readonly pubsub: Effect.Effect<ConnectionPubSub, unknown>;
 }
 
 /* Excluded from this release type: resetMemoryBus */
@@ -435,31 +394,18 @@ export declare interface ResolveBroadcastNamespaceInput {
 }
 
 export declare interface ResolveBroadcastOptions {
-    /** Explicit provider name or a pre-built `BroadcastProvider`. */
     readonly provider?: BroadcastProviderName | BroadcastProvider;
-    /** Broker URL — a broker-agnostic override (redis:// or nats://). Takes
-     *  precedence over the named-connection env. Default `BROADCAST_URL` env. */
-    readonly url?: string;
-    /** Named connection for the redis provider. The broker URL resolves via the
-     *  shared convention `<NAME>_REDIS_URL` → `REDIS_URL` (like cache / kv /
-     *  ratelimit), so a deployment points broadcast at the same server or its own
-     *  purely by env. Default `'broadcast'` (→ `BROADCAST_REDIS_URL`). */
-    readonly connection?: string;
+    readonly connection?: BrokerReference;
+    readonly events?: BrokerReference;
+    readonly members?: BrokerReference;
+    readonly presence?: BrokerReference;
+    readonly revalidate?: BrokerReference;
 }
 
-/**
- * Resolve the bus backend. Order: an object provider is used verbatim; a
- * named provider builds from `url`/env; absent → `BROADCAST_PROVIDER` env,
- * else inferred from a `redis://` / `nats://` URL, else `memory`.
- *
- * Returns the provider plus the URL it resolved (for the boot banner) and
- * whether the choice is a real cross-replica bus or the single-process
- * memory fallback.
- */
-export declare const resolveBroadcastProvider: (options: ResolveBroadcastOptions, env: NodeJS.ProcessEnv) => {
+export declare const resolveBroadcastProvider: (options: ResolveBroadcastOptions, environment: NodeJS.ProcessEnv, pubsub?: (role: string) => Effect.Effect<ConnectionPubSub, unknown>) => {
     provider: BroadcastProvider;
-    url: string | null;
     crossReplica: boolean;
+    selections: ReadonlyArray<BroadcastConnectionSelection>;
 };
 
 /** Retry cadence for a subscribe that could not land: 500ms doubling to a 10s