@pylonsync/react 0.22.39 → 0.22.41

package/dist/index.d.ts

@@ -20,7 +20,8 @@ export type { QueryOptions, QueryFilter, IncludeSpec, UseQueryReturn, UseQueryOn
 export { useAgentRun } from "./useAgentRun";
 export type { AgentRunRow, AgentMessageRow, UseAgentRunReturn, } from "./useAgentRun";
 export { useRoom, useRoomMessages } from "./useRoom";
-export type { RoomPeer, RoomSnapshot, UseRoomOptions, UseRoomReturn, } from "./useRoom";
+export { rowRoom } from "@pylonsync/sync";
+export type { RoomPeer, RoomSnapshot, UseRoomOptions, UseRoomReturn, RowRoomRef, } from "./useRoom";
 export type { RoomMessage } from "@pylonsync/sync";
 export { MutationRejectedError } from "@pylonsync/sync";
 export { useShard, connectShard } from "./useShard";

package/dist/useRoom.d.ts

@@ -36,6 +36,17 @@ export interface UseRoomReturn {
     leave: () => void;
     /** Error message, if any. */
     error: string | null;
+    /**
+     * True when the server refused this room or revoked access to it: a room
+     * tied to a row (`useRoom({ entity, id })`) the user may not read, or no
+     * longer may. The hook stops rejoining; peers are empty.
+     */
+    denied: boolean;
+}
+/** A room tied to a row (see {@link rowRoom}). */
+export interface RowRoomRef {
+    entity: string;
+    id: string;
 }
 interface SharedRoom {
     /** Number of live React hooks holding this room. */
@@ -87,6 +98,8 @@ interface SharedRoom {
     rejoinAttempts: number;
     /** The caller left with `leave()`: no keepalive, no rejoin. */
     left: boolean;
+    /** The server refused the room or revoked access: no keepalive, no rejoin. */
+    denied: boolean;
 }
 declare function releaseRoom(room: SharedRoom): void;
 export declare const __roomRegistryInternals: {
@@ -107,7 +120,12 @@ export declare const __roomRegistryInternals: {
     /** Diagnostic: is the polling timer running for this room? */
     isPolling(room: SharedRoom): boolean;
 };
-export declare function useRoom(roomId: string, userId: string, options?: UseRoomOptions): UseRoomReturn;
+/**
+ * Join a presence room. Pass `{ entity, id }` for the room tied to a row:
+ * only people who may read the row get in, and someone who loses access is
+ * removed (`denied` turns true).
+ */
+export declare function useRoom(room: string | RowRoomRef, userId: string, options?: UseRoomOptions): UseRoomReturn;
 /**
  * Subscribe to broadcasts on a room — both from other members
  * (`useRoom(...).broadcast`) and from the server

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.22.39",
+  "version": "0.22.41",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./dist/index.d.ts",
@@ -14,9 +14,9 @@
     "prepack": "bun run build"
   },
   "dependencies": {
-    "@pylonsync/realtime": "0.22.39",
-    "@pylonsync/sdk": "0.22.39",
-    "@pylonsync/sync": "0.22.39"
+    "@pylonsync/realtime": "0.22.41",
+    "@pylonsync/sdk": "0.22.41",
+    "@pylonsync/sync": "0.22.41"
   },
   "peerDependencies": {
     "react": ">=19.0.0"

package/src/index.ts

@@ -129,11 +129,13 @@ export type {
 
 // Room hook
 export { useRoom, useRoomMessages } from "./useRoom";
+export { rowRoom } from "@pylonsync/sync";
 export type {
   RoomPeer,
   RoomSnapshot,
   UseRoomOptions,
   UseRoomReturn,
+  RowRoomRef,
 } from "./useRoom";
 export type { RoomMessage } from "@pylonsync/sync";
 // Thrown by db.insert / update / delete (and useEntity's) when the server

package/src/useRoom.test.ts

@@ -214,3 +214,53 @@ describe("useRoom shared registry", () => {
     expect(count(isLeave)).toBe(1);
   });
 });
+
+// Rooms tied to a row: the server refuses callers who may not read the row
+// (403 ROOM_FORBIDDEN on join) and removes members who lose access (a
+// heartbeat answers alive:false, reason ROOM_FORBIDDEN). Retrying cannot
+// help, so the room stops instead of rejoining.
+describe("useRoom access denied", () => {
+  function stubFetch(answer: (url: string) => { status: number; body: unknown }): void {
+    globalThis.fetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
+      const url = typeof input === "string" ? input : input.toString();
+      recorded.push({ url, method: (init?.method ?? "GET").toUpperCase(), body: null });
+      const { status, body } = answer(url);
+      return new Response(JSON.stringify(body), {
+        status,
+        headers: { "content-type": "application/json" },
+      });
+    }) as typeof fetch;
+  }
+
+  test("a refused join does not retry", async () => {
+    __roomRegistryInternals.setTimings({ rejoinBaseMs: 5, keepaliveMs: 10 });
+    stubFetch(() => ({
+      status: 403,
+      body: { error: { code: "ROOM_FORBIDDEN", message: "You cannot use this room" } },
+    }));
+    const room = __roomRegistryInternals.acquire(BASE, "@Document/d1", USER, TOKEN, {}, 1000);
+    await new Promise((res) => setTimeout(res, 60));
+    expect(room.denied).toBe(true);
+    expect(room.error).toBe("You cannot use this room.");
+    expect(count(isJoin)).toBe(1);
+  });
+
+  test("a heartbeat that reports lost access stops the room", async () => {
+    __roomRegistryInternals.setTimings({ rejoinBaseMs: 5, keepaliveMs: 10 });
+    stubFetch((url) =>
+      url.endsWith("/api/rooms/heartbeat")
+        ? { status: 200, body: { alive: false, reason: "ROOM_FORBIDDEN" } }
+        : { status: 200, body: { snapshot: { peers: [{ user_id: "u2", data: {} }] } } },
+    );
+    const room = __roomRegistryInternals.acquire(BASE, "@Document/d1", USER, TOKEN, {}, 1000);
+    await new Promise((res) => setTimeout(res, 60));
+    expect(room.denied).toBe(true);
+    expect(room.peers).toEqual([]);
+    expect(room.error).toBe("You no longer have access to this room.");
+    const joins = count(isJoin);
+    const beats = count((r) => r.url.endsWith("/api/rooms/heartbeat"));
+    await new Promise((res) => setTimeout(res, 50));
+    expect(count(isJoin)).toBe(joins);
+    expect(count((r) => r.url.endsWith("/api/rooms/heartbeat"))).toBe(beats);
+  });
+});

package/src/useRoom.ts

@@ -6,6 +6,7 @@ import {
   type RoomMember,
   type RoomMessage,
   type SyncEngine,
+  rowRoom,
 } from '@pylonsync/sync';
 import { getBaseUrl, getReactStorage, storageKey } from './index';
 import { getSync } from './db';
@@ -65,6 +66,18 @@ export interface UseRoomReturn {
   leave: () => void;
   /** Error message, if any. */
   error: string | null;
+  /**
+   * True when the server refused this room or revoked access to it: a room
+   * tied to a row (`useRoom({ entity, id })`) the user may not read, or no
+   * longer may. The hook stops rejoining; peers are empty.
+   */
+  denied: boolean;
+}
+
+/** A room tied to a row (see {@link rowRoom}). */
+export interface RowRoomRef {
+  entity: string;
+  id: string;
 }
 
 // ---------------------------------------------------------------------------
@@ -175,6 +188,8 @@ interface SharedRoom {
   rejoinAttempts: number;
   /** The caller left with `leave()`: no keepalive, no rejoin. */
   left: boolean;
+  /** The server refused the room or revoked access: no keepalive, no rejoin. */
+  denied: boolean;
 }
 
 const rooms = new Map<string, SharedRoom>();
@@ -188,6 +203,20 @@ function roomKey(
   return `${baseUrl}|${roomId}|${userId}|${token ?? ''}`;
 }
 
+/** Error codes that end the room for this user: retrying cannot help. */
+const DENIED_CODES = new Set(["ROOM_FORBIDDEN", "ROOM_REVOKED", "INVALID_ROOM"]);
+
+/** The server refused the room, or revoked access: stop, clear, and say so. */
+function deny(room: SharedRoom, code: string): void {
+  room.denied = true;
+  stopKeepalive(room);
+  room.peers = [];
+  room.isConnected = false;
+  room.error =
+    code === "ROOM_REVOKED" ? "You no longer have access to this room." : "You cannot use this room.";
+  notify(room);
+}
+
 function notify(room: SharedRoom): void {
   for (const cb of room.subs) cb();
 }
@@ -256,9 +285,14 @@ function startWsPush(room: SharedRoom): void {
       // (reconnect), the idle sweep dropped us, or the subscribe beat the
       // join. Rejoin over HTTP, then resubscribe. Surface the error only
       // when rejoining keeps failing.
+      if (DENIED_CODES.has(err.code)) {
+        deny(room, err.code);
+        return;
+      }
       if (
         err.code === 'NOT_IN_ROOM' &&
         !room.left &&
+        !room.denied &&
         room.rejoinAttempts < MAX_REJOIN_ATTEMPTS
       ) {
         if (room.isConnected) {
@@ -365,7 +399,7 @@ function joinRoom(room: SharedRoom): void {
   // and notifies all subscribers. Late subscribers either pick up the
   // already-resolved snapshot from `room.peers` or the next push /
   // heartbeat.
-  if (room.joining || room.left) return;
+  if (room.joining || room.left || room.denied) return;
   room.joining = true;
   pylonFetch<{ snapshot?: { peers?: RoomPeer[] } }>(
     transportFor(room),
@@ -400,6 +434,10 @@ function joinRoom(room: SharedRoom): void {
     .catch((e: any) => {
       room.joining = false;
       if (!rooms.has(roomKeyFor(room))) return;
+      if (typeof e?.code === 'string' && DENIED_CODES.has(e.code)) {
+        deny(room, e.code);
+        return;
+      }
       if (room.rejoinAttempts < MAX_REJOIN_ATTEMPTS && !room.left) {
         scheduleRejoin(room);
         return;
@@ -412,7 +450,7 @@ function joinRoom(room: SharedRoom): void {
 /** Rejoin with backoff: at once for the first attempt, then 1 s, 2 s, 4 s,
  *  ... capped at 30 s. One pending rejoin at a time. */
 function scheduleRejoin(room: SharedRoom): void {
-  if (room.rejoinTimer || room.joining || room.left) return;
+  if (room.rejoinTimer || room.joining || room.left || room.denied) return;
   const attempt = room.rejoinAttempts;
   room.rejoinAttempts += 1;
   const delay =
@@ -431,11 +469,15 @@ function startKeepalive(room: SharedRoom): void {
   if (room.keepalive || room.left) return;
   room.keepalive = setInterval(() => {
     if (!rooms.has(roomKeyFor(room)) || room.left) return;
-    pylonFetch<{ alive?: boolean }>(transportFor(room), '/api/rooms/heartbeat', {
+    pylonFetch<{ alive?: boolean; reason?: string }>(transportFor(room), '/api/rooms/heartbeat', {
       method: 'POST',
       json: { room: room.roomId, user_id: room.userId },
     })
       .then((body) => {
+        if (body?.alive === false && body.reason && DENIED_CODES.has(body.reason)) {
+          if (rooms.has(roomKeyFor(room))) deny(room, "ROOM_REVOKED");
+          return;
+        }
         if (body?.alive === false && rooms.has(roomKeyFor(room))) {
           if (room.isConnected) {
             room.isConnected = false;
@@ -520,6 +562,7 @@ function acquireRoom(
     rejoinTimer: null,
     rejoinAttempts: 0,
     left: false,
+    denied: false,
   };
   rooms.set(key, room);
   joinRoom(room);
@@ -706,11 +749,17 @@ function tryGetSync(): SyncEngine | null {
   }
 }
 
+/**
+ * Join a presence room. Pass `{ entity, id }` for the room tied to a row:
+ * only people who may read the row get in, and someone who loses access is
+ * removed (`denied` turns true).
+ */
 export function useRoom(
-  roomId: string,
+  room: string | RowRoomRef,
   userId: string,
   options: UseRoomOptions = {},
 ): UseRoomReturn {
+  const roomId = typeof room === 'string' ? room : rowRoom(room.entity, room.id);
   const {
     // Fall back to the globally configured baseUrl so room requests don't
     // land on the Vite dev origin (localhost:5173) and 404 when the caller
@@ -727,6 +776,7 @@ export function useRoom(
   const [peers, setPeers] = useState<RoomPeer[]>([]);
   const [isConnected, setIsConnected] = useState(false);
   const [error, setError] = useState<string | null>(null);
+  const [denied, setDenied] = useState(false);
 
   // Remember the most recent shared room this hook is attached to so
   // setPresence / broadcast / leave can route through it without
@@ -751,11 +801,13 @@ export function useRoom(
     setPeers(room.peers);
     setIsConnected(room.isConnected);
     setError(room.error);
+    setDenied(room.denied);
 
     const sub = () => {
       setPeers(room.peers);
       setIsConnected(room.isConnected);
       setError(room.error);
+      setDenied(room.denied);
     };
     room.subs.add(sub);
 
@@ -828,7 +880,7 @@ export function useRoom(
     setPeers([]);
   }, [roomId, userId, baseUrl, token]);
 
-  return { peers, isConnected, setPresence, broadcast, leave, error };
+  return { peers, isConnected, setPresence, broadcast, leave, error, denied };
 }
 
 /**