@ultimat3/realtime 27.4.0 → 27.5.0

package/README.md

@@ -72,7 +72,7 @@ class — stay on `.`.
 
 | Concern | Entry | Export |
 |---|---|---|
-| tier 1 | `./server` | `ChannelHub`, `PresenceRegistry`, `SyncSocket`, `SocketRegistry` |
+| tier 1 | `./server` | `ChannelHub`, `PresenceRegistry`, `SyncSocket`, `SocketRegistry`; `publishChannelEvent` — a channel event from a job or an action — with the boot's `setChannelTransport` and the test seam `resetChannelTransport` |
 | tier 2 | `./server` | `LiveQueryRegistry`, `memoryChangeFeed()`, `postgresChangeFeed()`, `selectChangeFeed`, `changeFeedReplicator`, `postgresAdvisoryLock()`, `matcherFor` |
 | replication | `./server` | `parsePgUrl`, `bunPgStream`, `entityRow`, `changeLsn`, `commitPositionOf` |
 | the in-process change source | `./server` | `startLiveReplicator` — a repository's own writes as `ChangeEvent`s, for the embedded database `x dev` runs on (PGlite has no walsender). `ChangeEvent.table` is the entity's TABLE on it as on the WAL decoder and `recordPublisher`, so an `entity(name, { table })` reaches channels and live windows (25.0.0). Moved from `@ultimat3/testing`, which no longer re-exports it |
@@ -137,6 +137,40 @@ leaves `joining` on the node's first answer; nothing waits for app traffic.
 A channel declared with **neither** `records` nor `events` carries nothing, so nothing answers its
 join and it reads `joining` for as long as it is held.
 
+## Channel events from a job or an action
+
+The `ChannelHub` lives in the `sync` role. Everything else publishes an event with
+`publishChannelEvent` (`./server`), on the bus the boot installed for the process — every role's
+`startServices` calls `setChannelTransport` with the transport `selectTransport` chose.
+
+```ts
+import { allow } from '@ultimat3/policy';
+import { channel } from '@ultimat3/realtime';
+import { publishChannelEvent } from '@ultimat3/realtime/server';
+
+// Events only: no `records`, so nothing here reads the change feed and no replicator is needed.
+export const orgFeed = channel('org-feed', {
+  params: ['orgId'],
+  catchUp: { name: 'orgFeed' },
+  events: true,
+  policy: allow('public'),
+});
+
+// In a job step or an action handler, after the write committed.
+export const announce = (orgId: string, id: string): Promise<void> =>
+  publishChannelEvent(orgFeed, { orgId }, { kind: 'changed', id });
+```
+
+| Fact | Rule |
+|---|---|
+| who delivers | every `sync` node bridged to that topic, to its members' `onEvent`. Under `x dev` the node is in this process and shares the bus; across processes the bus is NATS (`realtime.transport: 'nats'`) |
+| after COMMIT | nothing here can see a transaction: an event sent from inside one is on every page before a rollback |
+| at-most-once | never stored, never replayed — a member that was offline does not get it. Send "re-read", never state. A bus that refuses the send rejects (`X_TRANSPORT_UNAVAILABLE`); catch it where an event is not worth failing the write for |
+| nothing booted | a unit test or a bare script publishes onto a heap bus nobody hears, and does not throw. A test that wants delivery calls `setChannelTransport(bus)` with the bus its `ChannelHub` holds, and `resetChannelTransport()` after |
+| `realtime.enabled: false` | still safe to call: the bus exists, no node subscribes |
+| refusals | `X_CHANNEL_DECLARATION_INVALID` on a channel declared without `events: true`; `X_TOPIC_FORBIDDEN` for a param that is no topic segment |
+| no replicator | a node that serves no `live: true` query and no `records` channel reads no change, boots `live=none` on a real database, and is never `X_REALTIME_TOPOLOGY` |
+
 ## Channel records with no replicator
 
 A channel's `records` come off the change bus every sync node reads. The WAL replicator fills it

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/realtime",
-  "version": "27.4.0",
+  "version": "27.5.0",
   "description": "Three-tier realtime: channels, live queries, local-first sync — one protocol, one mutator shape",
   "license": "MIT",
   "type": "module",
@@ -40,10 +40,10 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "27.4.0",
-    "@ultimat3/entity": "27.4.0",
-    "@ultimat3/policy": "27.4.0",
-    "@ultimat3/query": "27.4.0",
+    "@ultimat3/core": "27.5.0",
+    "@ultimat3/entity": "27.5.0",
+    "@ultimat3/policy": "27.5.0",
+    "@ultimat3/query": "27.5.0",
     "nats": "2.29.3"
   }
 }

package/src/channel-publish.ts

@@ -0,0 +1,75 @@
+// A channel `events` frame on the bus, from a process that serves no socket: `publishChannelEvent`
+// is what a job or an action calls. The `ChannelHub` lives in the `sync` role alone, so until this
+// seam a worker had no way to reach one, and an events-only channel could be fed only by a socket.
+// The frame and its subject are spelled here once; the hub's own `emit` publishes through them.
+
+import { assertCoded } from '@ultimat3/core';
+import type { Channel, Topic } from './channel-decl';
+import type { ChannelEventsFrame } from './channel-wire';
+import { InProcessTransport, type Transport } from './fanout';
+import type { JsonObject } from './json';
+import { PROTOCOL_VERSION } from './sync-protocol';
+
+const CHANNEL_SUBJECT_PREFIX = 'x.channel';
+
+/** The transport subject one topic's `events` frames ride — what a node's bridge subscribes to. */
+export const channelSubject = (name: Topic): string => `${CHANNEL_SUBJECT_PREFIX}.${name}`;
+
+/** One `events` frame onto `transport`: the single encoding, for the hub and for a publisher. */
+export async function sendChannelEvent(
+  transport: Transport,
+  name: Topic,
+  event: JsonObject,
+): Promise<void> {
+  const frame: ChannelEventsFrame = { type: 'events', v: PROTOCOL_VERSION, channel: name, event };
+  await transport.publish(channelSubject(name), JSON.stringify(frame));
+}
+
+/**
+ * The bus this process publishes on. A heap bus nobody subscribes to until a boot installs the
+ * real one — `jobs`' `setEventBus` arrangement — so a unit test, or a script that booted nothing,
+ * publishes to nobody instead of throwing in the middle of the write it follows.
+ */
+let ambient: Transport = new InProcessTransport();
+
+/**
+ * Called by the boot (`startServices`) with the transport `selectTransport` chose, in EVERY role:
+ * the same object the `sync` role's hub subscribes on, so under `x dev` a publish reaches this
+ * process's own sockets and under NATS every node's. Answers the release, which puts a fresh heap
+ * bus back only while this install is still the current one.
+ */
+export function setChannelTransport(transport: Transport): () => void {
+  ambient = transport;
+  return () => {
+    if (ambient === transport) resetChannelTransport();
+  };
+}
+
+/** Test seam: back to a fresh heap bus, the state a process boots in. */
+export function resetChannelTransport(): void {
+  ambient = new InProcessTransport();
+}
+
+/**
+ * An ephemeral event to every member of `declared`'s topic for `params`, on every node — from any
+ * process the framework booted. Never stored and never replayed: a member that was offline does not
+ * get it, so an event says "re-read", never "here is the state".
+ *
+ * **Call it after the transaction commits.** Nothing here can see a transaction: an event sent
+ * from inside one is on every page before a rollback. At-most-once — a bus that refuses the send
+ * rejects (`X_TRANSPORT_UNAVAILABLE` from NATS), and the caller decides whether that is worth
+ * failing for.
+ */
+export async function publishChannelEvent<K extends string>(
+  declared: Channel<K>,
+  params: Readonly<Record<K, string>>,
+  event: JsonObject,
+): Promise<void> {
+  assertCoded(
+    declared.events,
+    'X_CHANNEL_DECLARATION_INVALID',
+    `channel("${declared.name}") declares no events, so nothing may publish one on it`,
+    `declare it with events: true: channel('${declared.name}', { …, events: true })`,
+  );
+  await sendChannelEvent(ambient, declared.topic(params), event);
+}

package/src/channel.ts

@@ -18,8 +18,9 @@ import { type Bridge, unsubscribeWhenOpen } from './channel-bridge';
 import type { Channel, Topic } from './channel-decl';
 import { DenialLatch } from './channel-latch';
 import { ChannelLogs, type ChannelTopic } from './channel-logs';
+import { channelSubject, sendChannelEvent } from './channel-publish';
 import { getChannel, registeredChannels } from './channel-registry';
-import type { ChannelEventsFrame, ChannelSubscribeTarget } from './channel-wire';
+import type { ChannelSubscribeTarget } from './channel-wire';
 import {
   isPolicyDenial,
   SubscriptionLimitError,
@@ -29,12 +30,10 @@ import {
 import type { Transport } from './fanout';
 import type { JsonObject } from './json';
 import type { SocketRegistry, SyncSocket } from './socket';
-import { decode, PROTOCOL_VERSION } from './sync-protocol';
+import { decode } from './sync-protocol';
 
 export { type Topic, topic } from './channel-decl';
 
-const CHANNEL_SUBJECT_PREFIX = 'x.channel';
-
 export interface ChannelHubOptions {
   readonly transport: Transport;
   readonly sockets: SocketRegistry;
@@ -253,8 +252,7 @@ export class ChannelHub {
     // A topic this node holds open on a channel declared without `events` carries none: a
     // presence leave for it was an event on a channel whose members were promised records only.
     if (this.#logs.target(name)?.channel.events === false) return;
-    const frame: ChannelEventsFrame = { type: 'events', v: PROTOCOL_VERSION, channel: name, event };
-    await this.#transport.publish(`${CHANNEL_SUBJECT_PREFIX}.${name}`, JSON.stringify(frame));
+    await sendChannelEvent(this.#transport, name, event);
   }
 
   /** The declaration and params a topic joined on this node resolves to — `undefined` if none. */
@@ -448,7 +446,7 @@ export class ChannelHub {
   async #open(name: Topic, bridge: Bridge): Promise<void> {
     // Published into the bridge before it is awaited: that is what makes a second subscriber join
     // this open instead of starting a second one the table can never reach again.
-    bridge.sub ??= this.#transport.subscribe(`${CHANNEL_SUBJECT_PREFIX}.${name}`, (payload) => {
+    bridge.sub ??= this.#transport.subscribe(channelSubject(name), (payload) => {
       this.#sockets.deliver(name, decode(payload));
     });
     await bridge.sub;

package/src/server.ts

@@ -44,6 +44,12 @@ export {
   DEFAULT_MAX_TOPICS_PER_NODE,
 } from './channel';
 export { type ChannelDescription, describeChannels } from './channel-describe';
+// What a job or an action publishes an event with: the process's own bus, no hub needed.
+export {
+  publishChannelEvent,
+  resetChannelTransport,
+  setChannelTransport,
+} from './channel-publish';
 export { RealtimeTopologyError } from './errors';
 export {
   InProcessTransport,