ras-stack 0.4.0 → 0.6.0

package/README.md

@@ -14,7 +14,7 @@ The package contains independent helpers for common application infrastructure:
 
 - **Authentication:** secure defaults and utilities for sessions, rate limits, secrets, social providers, tokens, and trusted origins.
 - **Server requests:** same-origin mutation guards, error-normalizing RPC wrappers, canonical-host redirects, and health responses.
-- **Realtime:** Centrifugo token signing and a bounded publisher with retries and graceful shutdown.
+- **Realtime:** Centrifugo client lifecycle, token signing, presence synchronization, and a bounded publisher with retries and graceful shutdown.
 - **Email:** SMTP environment parsing and a small Nodemailer delivery interface.
 - **Uploads:** a promise-based wrapper around resumable `tus-js-client` uploads.
 - **Project configuration:** shared TypeScript and Oxlint bases.
@@ -35,10 +35,11 @@ The libraries underneath remain available normally. Applications still configure
 pnpm add ras-stack
 ```
 
-Nodemailer and `tus-js-client` are optional peer dependencies. Install one only when using its entrypoint:
+Nodemailer, Centrifuge, and `tus-js-client` are optional peer dependencies. Install one only when using its integration:
 
 ```sh
 pnpm add nodemailer
+pnpm add centrifuge
 pnpm add tus-js-client
 ```
 
@@ -89,10 +90,18 @@ Only enable `trustForwardedHeaders` behind a proxy that replaces incoming forwar
 
 ## Realtime updates
 
-Applications choose their channel names, authorize subscriptions, and define payloads. `ras-stack` handles Centrifugo's HTTP publication and signed tokens:
+Applications choose their channel names, authorize subscriptions, and define payloads. `ras-stack` handles Centrifugo's HTTP publication, signed tokens, and repeated browser lifecycle mechanics:
 
 ```ts
-import { CentrifugoPublisher, signRealtimeToken } from 'ras-stack/realtime'
+import {
+  CentrifugoPublisher,
+  connectRealtimeClient,
+  createSameOriginRealtimeClient,
+  openRealtimeSubscription,
+  requestRealtimeTicket,
+  signRealtimeToken,
+  watchSubscriptionPresence,
+} from 'ras-stack/realtime'
 
 const publisher = new CentrifugoPublisher({
   apiUrl,
@@ -107,9 +116,25 @@ publisher.publish(`battle:${battle.id}`, { type: 'change' })
 const token = signRealtimeToken(user.id, { channel: `battle:${battle.id}`, info: presence }, { secret })
 
 await publisher.close()
+
+const client = createSameOriginRealtimeClient({
+  getToken: () => requestRealtimeTicket('/api/realtime/token', { parse: (value) => (value as { token: string }).token }),
+})
+const channelToken = (channel: string) =>
+  requestRealtimeTicket('/api/realtime/token', {
+    init: { method: 'POST', body: JSON.stringify({ channel }) },
+    parse: (value) => (value as { token: string }).token,
+  })
+const disconnect = connectRealtimeClient(client)
+const live = openRealtimeSubscription(client, channel, { getToken: ({ channel }) => channelToken(channel) }, (subscription) =>
+  watchSubscriptionPresence(subscription, setClients),
+)
+
+live.close()
+disconnect()
 ```
 
-`publish()` returns `false` when the publisher is closed, disabled, or at capacity. `close()` rejects new work and waits for accepted publications and their bounded retries to finish.
+The client helpers return the underlying Centrifuge client and subscription. React ownership, channel conventions, ticket validation, event parsing, presence models, and query invalidation remain application code. `publish()` returns `false` when the publisher is closed, disabled, or at capacity. `close()` rejects new work and waits for accepted publications and their bounded retries to finish.
 
 ## Email and uploads
 
@@ -192,6 +217,31 @@ The workflow consumes pending changesets, commits the resulting versions and cha
 
 Pin actions and reusable workflows to a release tag and let Dependabot propose upgrades.
 
+The reusable check workflow owns checkout and toolchain setup while the repository keeps its check command:
+
+```yaml
+jobs:
+  check:
+    uses: richardsolomou/ras-stack/.github/workflows/check-js.yml@v0.6.0
+    with:
+      command: just check
+      just-version: '1.58.0'
+```
+
+Simple Playwright jobs can also share browser installation and failure artifacts:
+
+```yaml
+jobs:
+  end-to-end:
+    uses: richardsolomou/ras-stack/.github/workflows/check-browser.yml@v0.6.0
+    with:
+      prepare-command: pnpm build
+      command: pnpm test:e2e:run
+      artifact-path: test-results
+```
+
+Callers continue to own workflow triggers, concurrency, required-job dependencies, permissions, services, caches, custom setup, and release or deployment policy. Keep jobs local when they need steps beyond these stable shapes.
+
 ## Development
 
 Development requires Node 24 and pnpm 11.15.0.

package/dist/realtime/client.d.ts

@@ -0,0 +1,29 @@
+import { Centrifuge, type ClientInfo, type Options, type ServerPublicationContext, type ServerSubscribedContext, type Subscription, type SubscriptionOptions } from 'centrifuge';
+type BrowserLocation = Pick<Location, 'host' | 'protocol'>;
+export declare function sameOriginWebSocketUrl(location: BrowserLocation, path?: string): string;
+export type RealtimeTicketOptions<T> = {
+    fetch?: typeof fetch;
+    init?: RequestInit;
+    parse: (value: unknown) => T;
+    unauthorizedStatuses?: readonly number[];
+    errorMessage?: (status: number) => string;
+};
+export declare function requestRealtimeTicket<T>(input: RequestInfo | URL, options: RealtimeTicketOptions<T>): Promise<T>;
+export declare function createSameOriginRealtimeClient(options: Partial<Options>, config?: {
+    location?: BrowserLocation;
+    path?: string;
+}): Centrifuge;
+export declare function connectRealtimeClient(client: Centrifuge): () => void;
+export type RealtimeSubscription = {
+    subscription: Subscription;
+    close: () => void;
+};
+export declare function openRealtimeSubscription(client: Centrifuge, channel: string, options?: SubscriptionOptions, configure?: (subscription: Subscription) => void | (() => void)): RealtimeSubscription;
+export declare function watchServerChannel(client: Centrifuge, channel: string, handlers: {
+    publication?: (context: ServerPublicationContext) => void;
+    unrecovered?: (context: ServerSubscribedContext) => void;
+}): () => void;
+export declare function watchSubscriptionPresence(subscription: Subscription, update: (clients: Record<string, ClientInfo>) => void, options?: {
+    onError?: (error: unknown) => void;
+}): () => void;
+export {};

package/dist/realtime/client.js

@@ -0,0 +1,133 @@
+import { Centrifuge, UnauthorizedError, } from 'centrifuge';
+export function sameOriginWebSocketUrl(location, path = '/connection/websocket') {
+    if (!path.startsWith('/') || path.startsWith('//'))
+        throw new Error('WebSocket path must be same-origin');
+    const url = new URL(path, `${location.protocol}//${location.host}`);
+    url.protocol = url.protocol === 'https:' ? 'wss:' : 'ws:';
+    return url.toString();
+}
+export async function requestRealtimeTicket(input, options) {
+    const response = await (options.fetch ?? fetch)(input, options.init);
+    if ((options.unauthorizedStatuses ?? [401, 403]).includes(response.status))
+        throw new UnauthorizedError('unauthorized');
+    if (!response.ok)
+        throw new Error(options.errorMessage?.(response.status) ?? `Realtime authentication failed with status ${response.status}`);
+    return options.parse(await response.json());
+}
+export function createSameOriginRealtimeClient(options, config = {}) {
+    const location = config.location ?? window.location;
+    return new Centrifuge(sameOriginWebSocketUrl(location, config.path), options);
+}
+export function connectRealtimeClient(client) {
+    client.connect();
+    return () => client.disconnect();
+}
+export function openRealtimeSubscription(client, channel, options = {}, configure) {
+    const subscription = client.newSubscription(channel, options);
+    let cleanup;
+    try {
+        cleanup = configure?.(subscription);
+        subscription.subscribe();
+    }
+    catch (error) {
+        client.removeSubscription(subscription);
+        throw error;
+    }
+    let closed = false;
+    return {
+        subscription,
+        close: () => {
+            if (closed)
+                return;
+            closed = true;
+            try {
+                cleanup?.();
+            }
+            finally {
+                client.removeSubscription(subscription);
+            }
+        },
+    };
+}
+export function watchServerChannel(client, channel, handlers) {
+    const publication = (context) => {
+        if (context.channel === channel)
+            handlers.publication?.(context);
+    };
+    const subscribed = (context) => {
+        if (context.channel === channel && context.wasRecovering && !context.recovered)
+            handlers.unrecovered?.(context);
+    };
+    client.on('publication', publication);
+    client.on('subscribed', subscribed);
+    return () => {
+        client.off('publication', publication);
+        client.off('subscribed', subscribed);
+    };
+}
+export function watchSubscriptionPresence(subscription, update, options = {}) {
+    const clients = new Map();
+    let active = true;
+    let revision = 0;
+    let refreshing;
+    const render = () => update(Object.fromEntries(clients));
+    const sync = async () => {
+        const requestedAt = revision;
+        try {
+            const snapshot = await subscription.presence();
+            if (!active)
+                return;
+            if (revision !== requestedAt)
+                return sync();
+            clients.clear();
+            for (const [id, info] of Object.entries(snapshot.clients))
+                clients.set(id, info);
+            render();
+        }
+        catch (error) {
+            if (!active)
+                return;
+            if (revision !== requestedAt)
+                return sync();
+            clients.clear();
+            render();
+            options.onError?.(error);
+        }
+    };
+    const refresh = () => {
+        if (refreshing)
+            return refreshing;
+        refreshing = sync().finally(() => {
+            refreshing = undefined;
+        });
+        return refreshing;
+    };
+    const subscribed = () => {
+        revision++;
+        void refresh();
+    };
+    const join = ({ info }) => {
+        revision++;
+        clients.set(info.client, info);
+        render();
+    };
+    const leave = ({ info }) => {
+        revision++;
+        clients.delete(info.client);
+        render();
+    };
+    subscription.on('subscribed', subscribed);
+    subscription.on('join', join);
+    subscription.on('leave', leave);
+    return () => {
+        if (!active)
+            return;
+        active = false;
+        subscription.off('subscribed', subscribed);
+        subscription.off('join', join);
+        subscription.off('leave', leave);
+        clients.clear();
+        render();
+    };
+}
+//# sourceMappingURL=client.js.map

package/dist/realtime/client.js.map

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

package/dist/realtime/index.d.ts

@@ -1,2 +1,3 @@
+export * from './client.js';
 export * from './publisher.js';
 export * from './tokens.js';

package/dist/realtime/index.js

@@ -1,3 +1,4 @@
+export * from './client.js';
 export * from './publisher.js';
 export * from './tokens.js';
 //# sourceMappingURL=index.js.map

package/dist/realtime/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/realtime/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAA;AAC9B,cAAc,aAAa,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/realtime/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAA;AAC3B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,aAAa,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ras-stack",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Composable full-stack primitives shared across Richard Solomou's applications.",
   "keywords": [
     "authentication",
@@ -76,6 +76,7 @@
     "@tanstack/react-start": "^1.168.32",
     "@types/node": "^26.0.0",
     "@types/nodemailer": "^8.0.1",
+    "centrifuge": "5.7.0",
     "nodemailer": "^9.0.3",
     "oxfmt": "^0.59.0",
     "oxlint": "^1.74.0",
@@ -87,6 +88,7 @@
   "peerDependencies": {
     "@tanstack/react-query": ">=5 <6",
     "@tanstack/react-start": ">=1 <2",
+    "centrifuge": ">=5 <6",
     "nodemailer": ">=9 <10",
     "tus-js-client": ">=4 <5"
   },
@@ -97,6 +99,9 @@
     "@tanstack/react-start": {
       "optional": true
     },
+    "centrifuge": {
+      "optional": true
+    },
     "nodemailer": {
       "optional": true
     },