@chidchanun/bcp 0.2.12 → 0.2.14

package/docs/realtime-platform.md

@@ -0,0 +1,447 @@
+# Realtime Platform
+
+BCP Framework `0.2.13` adds the server-only `bcp/realtime` entrypoint for application realtime delivery without forcing one WebSocket or pub/sub provider.
+
+The platform separates four concerns:
+
+```text
+connection/session
+      |
+      +--> channel membership
+      +--> authentication / authorization
+      +--> heartbeat
+      |
+      v
+RealtimeHub
+      |
+      +--> RealtimeBroker
+      |       -> cross-hub delivery
+      |
+      +--> RealtimePresenceStore
+      |       -> room/channel presence
+      |
+      +--> RealtimeSocket adapter
+      |       -> WebSocket provider integration
+      |
+      +--> SSE Response
+              -> built-in HTTP streaming
+```
+
+## Create a hub
+
+```ts
+import {
+    createRealtime,
+} from "bcp/realtime";
+
+export const realtime =
+    createRealtime();
+```
+
+The default broker and presence store are process-local and intended for development, tests and single-process deployments.
+
+## Channels and rooms
+
+BCP treats rooms as named channels.
+
+```ts
+const connection =
+    await realtime.connect();
+
+await connection.join(
+    "orders:42"
+);
+```
+
+Broadcast to everyone currently joined:
+
+```ts
+await realtime.broadcast(
+    "orders:42",
+    "order.updated",
+    {
+        status: "paid",
+    }
+);
+```
+
+You can exclude one connection when echo suppression is needed:
+
+```ts
+await realtime.broadcast(
+    "chat:general",
+    "chat.message",
+    message,
+    {
+        excludeConnectionId:
+            sender.id,
+    }
+);
+```
+
+## Presence
+
+Presence is stored separately from message delivery.
+
+```ts
+await connection.join(
+    "project:7",
+    {
+        presence: {
+            status: "online",
+        },
+    }
+);
+
+const members =
+    await realtime.members(
+        "project:7"
+    );
+```
+
+The default `createMemoryRealtimePresenceStore()` is local-only. Multi-instance deployments should use a shared store whose `join`, `leave`, `leaveConnection`, `touch` and `list` operations are visible to every instance.
+
+## Authentication
+
+A realtime connection may be authenticated when it is created:
+
+```ts
+const realtime =
+    createRealtime({
+        authenticate:
+            async ({ request }) => {
+                if (!request) {
+                    return null;
+                }
+
+                return loadRealtimeUser(
+                    request
+                );
+            },
+
+        getUserId:
+            user => user.id,
+    });
+```
+
+The authenticated value is available as:
+
+```ts
+connection.user
+```
+
+BCP does not automatically turn a failed authentication callback into a rejected connection. Applications that require authentication should enforce that policy in their authentication callback/adapter or channel authorization policy.
+
+## Channel authorization
+
+```ts
+const realtime =
+    createRealtime({
+        authorizeChannel:
+            async ({
+                connection,
+                channel,
+            }) => {
+                if (
+                    channel.startsWith(
+                        "private:"
+                    )
+                ) {
+                    return Boolean(
+                        connection.user
+                    );
+                }
+
+                return true;
+            },
+    });
+```
+
+Authorization is evaluated before a connection joins a channel.
+
+## Client-originated events
+
+Register a server event handler:
+
+```ts
+realtime.on(
+    "chat.message",
+    async ({
+        connection,
+        channel,
+        payload,
+    }) => {
+        await saveMessage(
+            payload
+        );
+
+        await realtime.broadcast(
+            channel,
+            "chat.message",
+            payload,
+            {
+                excludeConnectionId:
+                    connection.id,
+            }
+        );
+    }
+);
+```
+
+Calling `connection.emit()` runs registered server handlers. It does not automatically broadcast the message. This keeps application authorization and mutation logic explicit.
+
+## WebSocket adapter contract
+
+BCP does not install `ws`, Socket.IO, uWebSockets.js or another WebSocket server package.
+
+Adapt your selected provider to this shape:
+
+```ts
+interface RealtimeSocket {
+    send(
+        data: string
+    ): void | Promise<void>;
+
+    close?(
+        code?: number,
+        reason?: string
+    ): void | Promise<void>;
+
+    onMessage(
+        listener: (
+            data: string
+        ) => void | Promise<void>
+    ): () => void;
+
+    onClose(
+        listener: () =>
+            void | Promise<void>
+    ): () => void;
+
+    onError?(
+        listener: (
+            error: unknown
+        ) => void | Promise<void>
+    ): () => void;
+}
+```
+
+Attach it:
+
+```ts
+const connection =
+    await realtime.attachSocket(
+        socketAdapter,
+        {
+            request,
+        }
+    );
+```
+
+### Socket message protocol
+
+Inbound JSON messages use these shapes:
+
+```json
+{
+  "type": "join",
+  "channel": "chat:general",
+  "presence": {
+    "status": "online"
+  }
+}
+```
+
+```json
+{
+  "type": "leave",
+  "channel": "chat:general"
+}
+```
+
+```json
+{
+  "type": "event",
+  "channel": "chat:general",
+  "event": "chat.message",
+  "payload": {
+    "text": "hello"
+  }
+}
+```
+
+Heartbeat input:
+
+```json
+{
+  "type": "ping"
+}
+```
+
+The server answers with a `realtime.pong` event.
+
+## Server-Sent Events
+
+SSE does not require a WebSocket provider.
+
+```ts
+export function GET(
+    request: Request
+) {
+    return realtime.sse(
+        "jobs:42",
+        {
+            signal:
+                request.signal,
+        }
+    );
+}
+```
+
+Equivalent standalone helper:
+
+```ts
+import {
+    createRealtimeSseResponse,
+} from "bcp/realtime";
+
+return createRealtimeSseResponse(
+    realtime,
+    "jobs:42",
+    {
+        signal:
+            request.signal,
+    }
+);
+```
+
+The response includes:
+
+```text
+Content-Type: text/event-stream
+Cache-Control: no-cache, no-transform
+Connection: keep-alive
+X-Accel-Buffering: no
+```
+
+Optional settings include `retryMs`, `keepAliveMs`, an event-name filter and additional response headers.
+
+## Heartbeat and stale connections
+
+```ts
+const realtime =
+    createRealtime({
+        heartbeatTimeoutMs:
+            60_000,
+    });
+
+const heartbeat =
+    realtime.startHeartbeat({
+        intervalMs: 20_000,
+    });
+```
+
+The heartbeat runner sends `realtime.ping` and calls `sweepStale()` periodically.
+
+A client `ping` message or any valid socket message updates the connection's `lastSeenAt` timestamp.
+
+Shutdown:
+
+```ts
+await heartbeat.stop();
+await realtime.close();
+```
+
+## Cross-instance broker
+
+`RealtimeBroker` is the pub/sub boundary:
+
+```ts
+interface RealtimeBroker {
+    publish(
+        message: RealtimeEnvelope
+    ): Promise<void>;
+
+    subscribe(
+        listener: (
+            message: RealtimeEnvelope
+        ) => void | Promise<void>
+    ): () => void;
+}
+```
+
+The built-in memory broker can be shared by multiple hubs in one process and is useful for tests.
+
+For multiple Node processes or containers, implement the broker using shared infrastructure such as Redis Pub/Sub, NATS or another application-selected service.
+
+A production topology may look like:
+
+```text
+Browser A -> App A ----\
+                       Shared Broker
+Browser B -> App B ----/
+          |             |
+          +---- Shared Presence Store
+```
+
+BCP intentionally does not install or own a Redis/NATS connection.
+
+## Jobs, workflows and events
+
+Realtime is designed to be the delivery edge for existing backend systems.
+
+Job progress:
+
+```ts
+await realtime.broadcast(
+    `jobs:${job.id}`,
+    "job.progress",
+    {
+        progress: 60,
+    }
+);
+```
+
+Workflow progress:
+
+```ts
+await realtime.broadcast(
+    `workflow:${run.id}`,
+    "workflow.updated",
+    run
+);
+```
+
+Outbox/event delivery can broadcast after durable publication/consumption according to application semantics.
+
+Do not treat a transient realtime broadcast as a durable event store. Important business events should continue to use the transactional outbox/durable queue path.
+
+## Delivery semantics
+
+Realtime delivery is transient. A disconnected client can miss a broadcast.
+
+Use:
+
+- database/outbox for durable business facts,
+- jobs/workflows for durable background execution,
+- realtime for live client delivery.
+
+For reconnect catch-up, expose application state or an event history endpoint and let the client refetch after reconnecting.
+
+## Security
+
+`bcp/realtime` is server-only.
+
+Applications should:
+
+- authenticate connections where required,
+- authorize every private channel join,
+- validate client event payloads,
+- rate-limit untrusted client messages when appropriate,
+- avoid placing secrets in broadcast payloads,
+- use TLS (`wss:` / HTTPS) in production,
+- apply origin checks at the WebSocket upgrade boundary when browser-origin restrictions are required.
+
+## 0.2.13 scope
+
+`0.2.13` provides the provider-neutral realtime runtime contract. It does not add a built-in Redis broker, WebSocket server dependency, durable message replay or browser client SDK.

package/docs/releases/0.2.13.md

@@ -0,0 +1,122 @@
+# BCP Framework 0.2.13
+
+Status: unreleased development target.
+
+## Realtime Platform
+
+`0.2.13` introduces `bcp/realtime`, a server-only provider-neutral realtime layer for channels/rooms, presence, cross-hub broker delivery, WebSocket adapter integration, SSE responses and heartbeat lifecycle.
+
+## Public API
+
+New entrypoint:
+
+```ts
+import {
+    createMemoryRealtimeBroker,
+    createMemoryRealtimePresenceStore,
+    createRealtime,
+    createRealtimeSseResponse,
+} from "bcp/realtime";
+```
+
+Key contracts:
+
+- `RealtimeHub`
+- `RealtimeConnection`
+- `RealtimeBroker`
+- `RealtimePresenceStore`
+- `RealtimeSocket`
+- `RealtimeEnvelope`
+- `RealtimeEventHandler`
+- `RealtimeAuthenticate`
+- `RealtimeAuthorizeChannel`
+
+## Channels and presence
+
+Connections can join/leave named channels and attach typed presence metadata. Hub broadcasts deliver only to local connections that joined the channel, while `RealtimeBroker` distributes envelopes across hubs.
+
+`createMemoryRealtimeBroker()` and `createMemoryRealtimePresenceStore()` provide deterministic local/test implementations.
+
+## Authentication and authorization
+
+`createRealtime()` accepts:
+
+- `authenticate` for request/data-based connection identity,
+- `getUserId` for presence identity,
+- `authorizeChannel` for private-channel join checks.
+
+Authentication policy remains application-owned so public and authenticated realtime endpoints can share the same runtime primitives.
+
+## WebSocket integration
+
+BCP does not add a mandatory WebSocket dependency. `RealtimeSocket` defines the minimal transport surface required by `attachSocket()`.
+
+The built-in JSON protocol supports:
+
+- `join`
+- `leave`
+- `event`
+- `ping`
+
+Valid client messages refresh connection liveness. Ping receives `realtime.pong`.
+
+## Server-Sent Events
+
+`RealtimeHub.sse()` and `createRealtimeSseResponse()` produce Web-standard streaming `Response` objects with event-stream headers, optional retry hints, event filtering and keep-alive comments.
+
+## Heartbeat lifecycle
+
+`startHeartbeat()` periodically sends `realtime.ping` and sweeps stale connections. `sweepStale()` can also be invoked manually for deterministic infrastructure loops and tests.
+
+## Multi-instance contract
+
+The memory broker and presence store are process-local.
+
+Production multi-instance applications can implement shared `RealtimeBroker` and `RealtimePresenceStore` adapters using infrastructure such as Redis, NATS or another service without coupling BCP to one provider/client library.
+
+## Integration model
+
+Realtime complements, but does not replace, durable platform primitives:
+
+```text
+Database / Transactional Outbox
+            |
+            v
+     Durable Jobs / Workflow
+            |
+            v
+       Realtime Hub
+            |
+      WebSocket / SSE
+```
+
+Realtime broadcasts are transient. Applications that require reconnect catch-up should refetch durable state/history after reconnect.
+
+## Package/runtime
+
+- `bcp/realtime` is server-only.
+- Client page/island graphs reject direct realtime imports.
+- publish preparation compiles `packages/client/src/realtime.ts` to `realtime.mjs`.
+- no new runtime dependency is required.
+
+## Validation
+
+The release adds unit/package coverage for:
+
+- cross-hub broker broadcasts,
+- channel membership,
+- presence metadata,
+- authentication identity,
+- channel authorization,
+- socket join/event/ping protocol,
+- stale heartbeat cleanup,
+- SSE streaming,
+- server-only boundary enforcement,
+- compiled package runtime execution,
+- public-entrypoint manifest parity.
+
+## Compatibility
+
+Previous baseline: `0.2.12`.
+
+There are no intentional breaking changes from `0.2.12`.