reflex-perspective 0.2.0__tar.gz → 0.3.0__tar.gz

{reflex_perspective-0.2.0 → reflex_perspective-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: reflex-perspective
-Version: 0.2.0
+Version: 0.3.0
 Summary: Perspective for Reflex: a WebAssembly analytics viewer (datagrid + WebGL charts) for large and streaming datasets, with client-only, server-only and replicated modes.
 Author-email: Ernesto Crespo <ecrespo@gmail.com>
 License-Expression: Apache-2.0
@@ -185,9 +185,16 @@ ps.mount(
   verified read table, building the app raises `RuntimeError` unless you pass
   `read_variants=`.
 - With `read_only=True`, a server viewer with `edit_mode="EDIT"`, `update_rows`,
-  `remove_keys` or `rp.update/remove/replace/clear` gets its socket closed with 4409 (and
-  the viewer reconnects). Write through the hub instead. Read-only does not stop users from
+  `remove_keys` or `rp.update/remove/replace/clear` gets its socket closed with 4409; the
+  viewers stop reconnecting and the browser console says why. Write through the hub instead. Read-only does not stop users from
   exporting what they can see (`view_to_*` reads stay allowed).
+- `max_sessions=N` caps the sessions open on the hub (across all its routes). Once reached,
+  new sockets are accepted and closed with **4429** after `authorize`; the viewers keep
+  retrying with backoff and connect when a slot frees up. `hub.session_count` gives the
+  current number.
+- `on_reject=fn` is called as `fn(code, websocket)` (sync or async) before every refusal
+  (1008, `authorize`'s code, 1011, 4409 and 4429), for metrics. Its errors are logged and never
+  change the close.
 - `ps.request_variant()` and `ps.is_read_request()` are public, for apps that compose
   their own handler around `hub.serve()`.
 
@@ -283,11 +290,18 @@ Styling props (`height`, `width`, `border_radius`, ...) apply to the `<perspecti
 | `on_global_filter_update` | List of filters (workspaces) |
 | `on_layout_update` / `on_active_panel_update` | Panel ids / active panel id |
 | `on_toggle_settings` | `bool` |
-| `on_disconnect` / `on_error` | URL / message |
+| `on_disconnect` | `(url, code)`: the server URL and the WebSocket close code (`None` if unknown); one-argument handlers get the URL |
+| `on_error` | Message |
 
 A controlled loop (`config=State.cfg`, `on_config_update=State.set_cfg`) is safe: the
 component does not re-apply a config the viewer itself just emitted.
 
+Server viewers reconnect with exponential backoff (0.5 s doubling, up to 10 s) after a lost
+connection, except when the server refused it for good: a close code in 4400–4499 other than
+4429 (e.g. 4401/4403 from `authorize`, 4409 from `read_only`). Then every viewer of that URL
+stops retrying until the page is reloaded and the browser console explains the code; 4429
+("too many sessions") keeps retrying.
+
 ## Actions
 
 All return an `EventSpec`, usable in triggers (`on_click=rp.download("v")`) or returned from
@@ -325,6 +339,8 @@ uv run reflex run
 
 Run it with `PERSPECTIVE_DEMO_READ_ONLY=1 uv run reflex run` to serve the WebSocket in
 read-only mode: the "Write from the browser" button on `/server` is then refused with 4409.
+`PERSPECTIVE_DEMO_MAX_SESSIONS=1` caps the hub: a second tab gets 4429 until the first closes.
+The access card counts refusals by code through `on_reject`.
 
 | | |
 | --- | --- |

{reflex_perspective-0.2.0 → reflex_perspective-0.3.0}/README.md

@@ -151,9 +151,16 @@ ps.mount(
   verified read table, building the app raises `RuntimeError` unless you pass
   `read_variants=`.
 - With `read_only=True`, a server viewer with `edit_mode="EDIT"`, `update_rows`,
-  `remove_keys` or `rp.update/remove/replace/clear` gets its socket closed with 4409 (and
-  the viewer reconnects). Write through the hub instead. Read-only does not stop users from
+  `remove_keys` or `rp.update/remove/replace/clear` gets its socket closed with 4409; the
+  viewers stop reconnecting and the browser console says why. Write through the hub instead. Read-only does not stop users from
   exporting what they can see (`view_to_*` reads stay allowed).
+- `max_sessions=N` caps the sessions open on the hub (across all its routes). Once reached,
+  new sockets are accepted and closed with **4429** after `authorize`; the viewers keep
+  retrying with backoff and connect when a slot frees up. `hub.session_count` gives the
+  current number.
+- `on_reject=fn` is called as `fn(code, websocket)` (sync or async) before every refusal
+  (1008, `authorize`'s code, 1011, 4409 and 4429), for metrics. Its errors are logged and never
+  change the close.
 - `ps.request_variant()` and `ps.is_read_request()` are public, for apps that compose
   their own handler around `hub.serve()`.
 
@@ -249,11 +256,18 @@ Styling props (`height`, `width`, `border_radius`, ...) apply to the `<perspecti
 | `on_global_filter_update` | List of filters (workspaces) |
 | `on_layout_update` / `on_active_panel_update` | Panel ids / active panel id |
 | `on_toggle_settings` | `bool` |
-| `on_disconnect` / `on_error` | URL / message |
+| `on_disconnect` | `(url, code)`: the server URL and the WebSocket close code (`None` if unknown); one-argument handlers get the URL |
+| `on_error` | Message |
 
 A controlled loop (`config=State.cfg`, `on_config_update=State.set_cfg`) is safe: the
 component does not re-apply a config the viewer itself just emitted.
 
+Server viewers reconnect with exponential backoff (0.5 s doubling, up to 10 s) after a lost
+connection, except when the server refused it for good: a close code in 4400–4499 other than
+4429 (e.g. 4401/4403 from `authorize`, 4409 from `read_only`). Then every viewer of that URL
+stops retrying until the page is reloaded and the browser console explains the code; 4429
+("too many sessions") keeps retrying.
+
 ## Actions
 
 All return an `EventSpec`, usable in triggers (`on_click=rp.download("v")`) or returned from
@@ -291,6 +305,8 @@ uv run reflex run
 
 Run it with `PERSPECTIVE_DEMO_READ_ONLY=1 uv run reflex run` to serve the WebSocket in
 read-only mode: the "Write from the browser" button on `/server` is then refused with 4409.
+`PERSPECTIVE_DEMO_MAX_SESSIONS=1` caps the hub: a second tab gets 4429 until the first closes.
+The access card counts refusals by code through `on_reject`.
 
 | | |
 | --- | --- |

{reflex_perspective-0.2.0 → reflex_perspective-0.3.0}/custom_components/reflex_perspective/__init__.py

@@ -67,4 +67,4 @@ __all__ = [
     "update",
 ]
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"

{reflex_perspective-0.2.0 → reflex_perspective-0.3.0}/custom_components/reflex_perspective/perspective_viewer.jsx

@@ -99,6 +99,63 @@ export function resolveServerUrl(url) {
   return endpoint.toString();
 }
 
+/**
+ * WebSocket close code carried by a client error. Perspective's transport
+ * reports a close to `Client.on_error` as the text "WebSocket closed <code>"
+ * (perspective 5.5.1, `src/ts/websocket.ts`); `null` when there is none.
+ */
+export function closeCodeFromError(error) {
+  const text =
+    typeof error === "string" ? error : String(error?.message ?? error ?? "");
+  const match = /WebSocket closed (\d{4})\b/.exec(text);
+  return match ? Number(match[1]) : null;
+}
+
+/** Server refusals a retry cannot fix: 4400-4499, except 4429 (try later). */
+export function isPermanentRefusal(code) {
+  return Number.isInteger(code) && code >= 4400 && code <= 4499 && code !== 4429;
+}
+
+const REFUSAL_CAUSES = {
+  4401: "not authenticated (the app's authorize hook refused the connection)",
+  4403: "forbidden (the app's authorize hook refused the connection)",
+  4409:
+    "read-only socket: this page sent a write (a server viewer with " +
+    'edit_mode="EDIT", update_rows, remove_keys or rp.update/remove/replace/clear). ' +
+    "Write through the hub in Python instead",
+};
+
+/** Console text for a permanent refusal of `url`. */
+export function refusalMessage(code, url) {
+  const cause = REFUSAL_CAUSES[code] ?? "refused by the server";
+  return (
+    `reflex-perspective: ${url} closed with ${code}: ${cause}. ` +
+    "Not reconnecting until the page is reloaded."
+  );
+}
+
+// URL -> close code of a permanent refusal; such URLs are never retried.
+const WS_REFUSED = new Map();
+
+/** Whether `url` (resolved) was permanently refused by the server. */
+export function isRefused(url) {
+  return WS_REFUSED.has(url);
+}
+
+/**
+ * Record why the socket of `url` (resolved) dropped. A permanent refusal
+ * blocks further retries for that URL and is reported once through `warn`.
+ * Returns the close code, or `null` when the error does not carry one.
+ */
+export function noteClose(url, error, warn = console.warn) {
+  const code = closeCodeFromError(error);
+  if (isPermanentRefusal(code) && !WS_REFUSED.has(url)) {
+    WS_REFUSED.set(url, code);
+    warn(refusalMessage(code, url));
+  }
+  return code;
+}
+
 function evictWebsocketClient(url) {
   WS_CLIENTS.delete(resolveServerUrl(url));
 }
@@ -110,12 +167,13 @@ async function getWebsocketClient(url) {
       const perspective = await loadPerspective();
       const client = await perspective.websocket(resolved);
       try {
-        await client.on_error(() => {
+        await client.on_error((error) => {
+          const code = noteClose(resolved, error);
           // Evict so the next load() opens a fresh connection.
           if (WS_CLIENTS.get(resolved) === promise) WS_CLIENTS.delete(resolved);
           window.dispatchEvent(
             new CustomEvent("reflex-perspective-disconnect", {
-              detail: { url: resolved },
+              detail: { url: resolved, code },
             }),
           );
         });
@@ -503,8 +561,13 @@ export function ReflexPerspectiveViewer(props) {
   const [retryTick, setRetryTick] = useState(0);
   const retryAttempts = useRef(0);
   const retryTimer = useRef(null);
+  // A URL the server refused for good (4400-4499 but 4429) is never retried.
+  const refused = () => {
+    const url = propsRef.current.serverUrl;
+    return Boolean(url) && isRefused(resolveServerUrl(url));
+  };
   const scheduleRetry = useCallback(() => {
-    if (retryTimer.current) return;
+    if (retryTimer.current || refused()) return;
     const delay = Math.min(
       10000,
       500 * 2 ** Math.min(retryAttempts.current, 5),
@@ -512,7 +575,7 @@ export function ReflexPerspectiveViewer(props) {
     retryAttempts.current += 1;
     retryTimer.current = setTimeout(() => {
       retryTimer.current = null;
-      setRetryTick((t) => t + 1);
+      if (!refused()) setRetryTick((t) => t + 1);
     }, delay);
   }, []);
   useEffect(
@@ -869,7 +932,7 @@ export function ReflexPerspectiveViewer(props) {
     const resolved = resolveServerUrl(serverUrl);
     const handler = (e) => {
       if (e.detail?.url !== resolved) return;
-      propsRef.current.onDisconnect?.(resolved);
+      propsRef.current.onDisconnect?.(resolved, e.detail?.code ?? null);
       scheduleRetry();
     };
     window.addEventListener("reflex-perspective-disconnect", handler);

{reflex_perspective-0.2.0 → reflex_perspective-0.3.0}/custom_components/reflex_perspective/server.py

@@ -76,6 +76,12 @@ Authorize = Callable[[WebSocket], Awaitable[int | None] | int | None]
 Returns ``None`` to accept, or a close code (4000-4999, or 1008) to refuse.
 """
 
+OnReject = Callable[[int, WebSocket], Awaitable[None] | None]
+"""Hook called with the close code of every refusal (for metrics)."""
+
+# Close code for "too many sessions, try again later" (max_sessions).
+_WS_TOO_MANY_SESSIONS = 4429
+
 WRITE_CLOSE_CODE = 4409
 """Default close code for a frame refused in read-only mode."""
 
@@ -245,6 +251,28 @@ def _valid_refusal_code(code: object) -> bool:
     return type(code) is int and (4000 <= code <= 4999 or code == _WS_POLICY_VIOLATION)
 
 
+def _check_max_sessions(max_sessions: int | None) -> None:
+    if max_sessions is not None and not (
+        type(max_sessions) is int and max_sessions >= 1
+    ):
+        msg = f"max_sessions must be an int >= 1 or None, got {max_sessions!r}"
+        raise ValueError(msg)
+
+
+async def _notify_reject(
+    on_reject: OnReject | None, code: int, websocket: WebSocket
+) -> None:
+    """Report a refusal; a failing hook is logged and never changes the close."""
+    if on_reject is None:
+        return
+    try:
+        result = on_reject(code, websocket)
+        if inspect.isawaitable(result):
+            await result
+    except Exception:
+        logger.exception("Perspective on_reject hook failed")
+
+
 async def _run_authorize(authorize: Authorize, websocket: WebSocket) -> int | None:
     """``None`` to accept, else the close code to use (1011 if the hook fails)."""
     try:
@@ -306,6 +334,7 @@ class PerspectiveHub:
         self.client = self.server.new_local_client()
         self._lock = threading.RLock()
         self._tables: dict[str, Any] = {}
+        self._sessions = 0
 
     # ------------------------------------------------------------------ tables
     def table(
@@ -422,6 +451,23 @@ class PerspectiveHub:
             view.delete()
 
     # --------------------------------------------------------------- websocket
+    @property
+    def session_count(self) -> int:
+        """WebSocket sessions currently open on this hub."""
+        with self._lock:
+            return self._sessions
+
+    def _admit(self, max_sessions: int | None) -> bool:
+        with self._lock:
+            if max_sessions is not None and self._sessions >= max_sessions:
+                return False
+            self._sessions += 1
+            return True
+
+    def _release(self) -> None:
+        with self._lock:
+            self._sessions -= 1
+
     async def serve(
         self,
         websocket: WebSocket,
@@ -432,6 +478,8 @@ class PerspectiveHub:
         read_only: bool = False,
         write_close_code: int = WRITE_CLOSE_CODE,
         read_variants: Collection[int] | None = None,
+        max_sessions: int | None = None,
+        on_reject: OnReject | None = None,
     ) -> None:
         """Run a Perspective session over a Starlette WebSocket.
 
@@ -462,8 +510,16 @@ class PerspectiveHub:
                 ``None`` uses :data:`READ_VARIANTS` for the installed
                 ``perspective-python`` and raises ``RuntimeError`` if that
                 version has no verified table.
+            max_sessions: Cap on the sessions open on this hub (all its
+                routes). Once reached, new sockets are accepted and closed
+                with 4429 ("try again later") after ``authorize``.
+            on_reject: Called as ``on_reject(code, websocket)`` (sync or
+                async) before every refusal: 1008, ``authorize``'s code, 1011,
+                ``write_close_code`` and 4429. Its errors are logged and never
+                change the close.
         """
         allowed_reads = _read_only_reads(read_only, write_close_code, read_variants)
+        _check_max_sessions(max_sessions)
 
         allowed = (
             _default_allowed_origins() if allowed_origins is None else allowed_origins
@@ -471,16 +527,41 @@ class PerspectiveHub:
         origin = websocket.headers.get("origin")
         if not origin_allowed(origin, allowed):
             logger.warning("Rejected Perspective websocket from origin %r", origin)
+            await _notify_reject(on_reject, _WS_POLICY_VIOLATION, websocket)
             await websocket.close(code=_WS_POLICY_VIOLATION)
             return
 
+        refusal = None
         if authorize is not None:
             refusal = await _run_authorize(authorize, websocket)
-            if refusal is not None:
-                await websocket.accept()
-                await websocket.close(code=refusal)
-                return
+        if refusal is None and not self._admit(max_sessions):
+            logger.warning(
+                "Refused Perspective websocket: %s sessions open (max_sessions)",
+                max_sessions,
+            )
+            refusal = _WS_TOO_MANY_SESSIONS
+        if refusal is not None:
+            await _notify_reject(on_reject, refusal, websocket)
+            await websocket.accept()
+            await websocket.close(code=refusal)
+            return
+
+        try:
+            await self._run_session(
+                websocket, executor, allowed_reads, write_close_code, on_reject
+            )
+        finally:
+            self._release()
 
+    async def _run_session(
+        self,
+        websocket: WebSocket,
+        executor: Executor | None,
+        allowed_reads: frozenset[int] | None,
+        write_close_code: int,
+        on_reject: OnReject | None,
+    ) -> None:
+        """Accept the socket and relay frames to a new Perspective session."""
         loop = asyncio.get_running_loop()
         outbox: asyncio.Queue[bytes | None] = asyncio.Queue()
 
@@ -526,6 +607,7 @@ class PerspectiveHub:
                         if variant is not None
                         else "unreadable",
                     )
+                    await _notify_reject(on_reject, write_close_code, websocket)
                     await websocket.close(code=write_close_code)
                     break
                 # Requests are awaited one at a time, so ordering is preserved.
@@ -549,6 +631,8 @@ class PerspectiveHub:
         read_only: bool = False,
         write_close_code: int = WRITE_CLOSE_CODE,
         read_variants: Collection[int] | None = None,
+        max_sessions: int | None = None,
+        on_reject: OnReject | None = None,
     ) -> Starlette:
         """A Starlette app exposing this hub's WebSocket at ``path``.
 
@@ -557,11 +641,13 @@ class PerspectiveHub:
         options.
 
         Raises:
-            ValueError: ``write_close_code`` outside 4000-4999.
+            ValueError: ``write_close_code`` outside 4000-4999, or
+                ``max_sessions`` not an int >= 1.
             RuntimeError: ``read_only=True`` without ``read_variants`` on a
                 ``perspective-python`` version with no verified read table.
         """
         _read_only_reads(read_only, write_close_code, read_variants)
+        _check_max_sessions(max_sessions)
 
         async def endpoint(websocket: WebSocket) -> None:
             await self.serve(
@@ -572,6 +658,8 @@ class PerspectiveHub:
                 read_only=read_only,
                 write_close_code=write_close_code,
                 read_variants=read_variants,
+                max_sessions=max_sessions,
+                on_reject=on_reject,
             )
 
         return Starlette(routes=[WebSocketRoute(path, endpoint)])
@@ -600,6 +688,8 @@ def perspective_api(
     read_only: bool = False,
     write_close_code: int = WRITE_CLOSE_CODE,
     read_variants: Collection[int] | None = None,
+    max_sessions: int | None = None,
+    on_reject: OnReject | None = None,
 ) -> Starlette:
     """Build the ``api_transformer`` that serves Perspective at ``path``.
 
@@ -617,6 +707,8 @@ def perspective_api(
         read_only=read_only,
         write_close_code=write_close_code,
         read_variants=read_variants,
+        max_sessions=max_sessions,
+        on_reject=on_reject,
     )
 
 
@@ -631,6 +723,8 @@ def mount(
     read_only: bool = False,
     write_close_code: int = WRITE_CLOSE_CODE,
     read_variants: Collection[int] | None = None,
+    max_sessions: int | None = None,
+    on_reject: OnReject | None = None,
 ) -> PerspectiveHub:
     """Add the Perspective WebSocket to an existing ``rx.App``.
 
@@ -649,6 +743,8 @@ def mount(
         read_only=read_only,
         write_close_code=write_close_code,
         read_variants=read_variants,
+        max_sessions=max_sessions,
+        on_reject=on_reject,
     )
     current = app.api_transformer
     if current is None:

{reflex_perspective-0.2.0 → reflex_perspective-0.3.0}/custom_components/reflex_perspective/viewer.py

@@ -170,6 +170,13 @@ def _bool_spec(value: Var[bool]) -> tuple[Var[bool]]:
     return (value,)
 
 
+def _url_code_spec(
+    url: Var[str], code: Var[int | None]
+) -> tuple[Var[str], Var[int | None]]:
+    """``(url, close code)``; the code is ``None`` when the bridge cannot tell."""
+    return (url, code)
+
+
 class PerspectiveViewer(rx.Component):
     """A ``<perspective-viewer>`` bound to a Perspective ``Table``."""
 
@@ -287,8 +294,9 @@ class PerspectiveViewer(rx.Component):
     on_layout_update: rx.EventHandler[_list_spec]
     on_active_panel_update: rx.EventHandler[_str_spec]
     on_toggle_settings: rx.EventHandler[_bool_spec]
-    # The WebSocket connection to the server was lost (auto-reconnects).
-    on_disconnect: rx.EventHandler[_str_spec]
+    # The WebSocket connection to the server was lost: (url, close code or None).
+    # Reconnects unless the server refused it (4400-4499 except 4429).
+    on_disconnect: rx.EventHandler[_url_code_spec, _str_spec]
     on_error: rx.EventHandler[_str_spec]
 
     @classmethod

{reflex_perspective-0.2.0 → reflex_perspective-0.3.0}/custom_components/reflex_perspective/viewer.pyi

@@ -145,7 +145,9 @@ class PerspectiveViewer(rx.Component):
         on_click: Optional[EventType[()] | EventType[dict[str, Any]]] = None,
         on_config_update: Optional[EventType[()] | EventType[dict[str, Any]]] = None,
         on_context_menu: Optional[EventType[()] | EventType[PointerEventInfo]] = None,
-        on_disconnect: Optional[EventType[()] | EventType[str]] = None,
+        on_disconnect: Optional[
+            EventType[()] | EventType[str] | EventType[str, int | None]
+        ] = None,
         on_double_click: Optional[EventType[()] | EventType[PointerEventInfo]] = None,
         on_error: Optional[EventType[()] | EventType[str]] = None,
         on_focus: Optional[EventType[()]] = None,
@@ -236,7 +238,7 @@ class PerspectiveViewer(rx.Component):
             on_layout_update: Panels were added/removed in a multi-panel viewer.
             on_active_panel_update: no description
             on_toggle_settings: no description
-            on_disconnect: The WebSocket connection to the server was lost (auto-reconnects).
+            on_disconnect: The WebSocket connection to the server was lost: (url, close code or None). Reconnects unless the server refused it (4400-4499 except 4429).
             on_error: no description
             **props: Component props, see the class attributes.
 

{reflex_perspective-0.2.0 → reflex_perspective-0.3.0}/custom_components/reflex_perspective.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: reflex-perspective
-Version: 0.2.0
+Version: 0.3.0
 Summary: Perspective for Reflex: a WebAssembly analytics viewer (datagrid + WebGL charts) for large and streaming datasets, with client-only, server-only and replicated modes.
 Author-email: Ernesto Crespo <ecrespo@gmail.com>
 License-Expression: Apache-2.0
@@ -185,9 +185,16 @@ ps.mount(
   verified read table, building the app raises `RuntimeError` unless you pass
   `read_variants=`.
 - With `read_only=True`, a server viewer with `edit_mode="EDIT"`, `update_rows`,
-  `remove_keys` or `rp.update/remove/replace/clear` gets its socket closed with 4409 (and
-  the viewer reconnects). Write through the hub instead. Read-only does not stop users from
+  `remove_keys` or `rp.update/remove/replace/clear` gets its socket closed with 4409; the
+  viewers stop reconnecting and the browser console says why. Write through the hub instead. Read-only does not stop users from
   exporting what they can see (`view_to_*` reads stay allowed).
+- `max_sessions=N` caps the sessions open on the hub (across all its routes). Once reached,
+  new sockets are accepted and closed with **4429** after `authorize`; the viewers keep
+  retrying with backoff and connect when a slot frees up. `hub.session_count` gives the
+  current number.
+- `on_reject=fn` is called as `fn(code, websocket)` (sync or async) before every refusal
+  (1008, `authorize`'s code, 1011, 4409 and 4429), for metrics. Its errors are logged and never
+  change the close.
 - `ps.request_variant()` and `ps.is_read_request()` are public, for apps that compose
   their own handler around `hub.serve()`.
 
@@ -283,11 +290,18 @@ Styling props (`height`, `width`, `border_radius`, ...) apply to the `<perspecti
 | `on_global_filter_update` | List of filters (workspaces) |
 | `on_layout_update` / `on_active_panel_update` | Panel ids / active panel id |
 | `on_toggle_settings` | `bool` |
-| `on_disconnect` / `on_error` | URL / message |
+| `on_disconnect` | `(url, code)`: the server URL and the WebSocket close code (`None` if unknown); one-argument handlers get the URL |
+| `on_error` | Message |
 
 A controlled loop (`config=State.cfg`, `on_config_update=State.set_cfg`) is safe: the
 component does not re-apply a config the viewer itself just emitted.
 
+Server viewers reconnect with exponential backoff (0.5 s doubling, up to 10 s) after a lost
+connection, except when the server refused it for good: a close code in 4400–4499 other than
+4429 (e.g. 4401/4403 from `authorize`, 4409 from `read_only`). Then every viewer of that URL
+stops retrying until the page is reloaded and the browser console explains the code; 4429
+("too many sessions") keeps retrying.
+
 ## Actions
 
 All return an `EventSpec`, usable in triggers (`on_click=rp.download("v")`) or returned from
@@ -325,6 +339,8 @@ uv run reflex run
 
 Run it with `PERSPECTIVE_DEMO_READ_ONLY=1 uv run reflex run` to serve the WebSocket in
 read-only mode: the "Write from the browser" button on `/server` is then refused with 4409.
+`PERSPECTIVE_DEMO_MAX_SESSIONS=1` caps the hub: a second tab gets 4429 until the first closes.
+The access card counts refusals by code through `on_reject`.
 
 | | |
 | --- | --- |

{reflex_perspective-0.2.0 → reflex_perspective-0.3.0}/custom_components/reflex_perspective.egg-info/SOURCES.txt

@@ -12,6 +12,7 @@ custom_components/reflex_perspective.egg-info/SOURCES.txt
 custom_components/reflex_perspective.egg-info/dependency_links.txt
 custom_components/reflex_perspective.egg-info/requires.txt
 custom_components/reflex_perspective.egg-info/top_level.txt
+tests/test_bridge_js.py
 tests/test_demo_access.py
 tests/test_server.py
 tests/test_specs.py

{reflex_perspective-0.2.0 → reflex_perspective-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "reflex-perspective"
-version = "0.2.0"
+version = "0.3.0"
 description = "Perspective for Reflex: a WebAssembly analytics viewer (datagrid + WebGL charts) for large and streaming datasets, with client-only, server-only and replicated modes."
 readme = "README.md"
 license = "Apache-2.0"

reflex_perspective-0.3.0/tests/test_bridge_js.py

@@ -0,0 +1,57 @@
+"""Runs the JavaScript unit tests of the React bridge (tests/js, node:test).
+
+The bridge is bundled with esbuild (the same pinned version CI uses for its
+syntax check) with React and Reflex's runtime modules stubbed out; the
+Perspective packages are only imported lazily and stay external.
+"""
+
+import os
+import shutil
+import subprocess
+from pathlib import Path
+
+import pytest
+
+ROOT = Path(__file__).resolve().parents[1]
+BRIDGE = ROOT / "custom_components" / "reflex_perspective" / "perspective_viewer.jsx"
+JS = ROOT / "tests" / "js"
+ESBUILD = "esbuild@0.25"
+
+pytestmark = pytest.mark.skipif(
+    not (shutil.which("node") and shutil.which("npx")), reason="node/npx not installed"
+)
+
+
+def run(cmd: list[str], **kw) -> subprocess.CompletedProcess:
+    return subprocess.run(  # noqa: S603 - fixed argv, no shell
+        cmd, cwd=ROOT, capture_output=True, text=True, timeout=300, check=False, **kw
+    )
+
+
+def test_bridge_js_unit_tests(tmp_path):
+    """REQ-VIEW-011/012: the bridge's pure helpers pass their node:test suite."""
+    bundle = tmp_path / "bridge.mjs"
+    built = run(
+        [
+            shutil.which("npx"),
+            "--yes",
+            ESBUILD,
+            str(BRIDGE),
+            "--bundle",
+            "--format=esm",
+            "--platform=node",
+            "--loader:.jsx=jsx",
+            "--log-level=warning",
+            f"--alias:react={JS / 'stubs' / 'react.mjs'}",
+            f"--alias:$/env.json={JS / 'stubs' / 'env.json'}",
+            f"--alias:$/utils/state={JS / 'stubs' / 'state.mjs'}",
+            "--external:@perspective-dev/*",
+            f"--outfile={bundle}",
+        ]
+    )
+    assert built.returncode == 0, built.stderr
+    tested = run(
+        [shutil.which("node"), "--test", str(JS / "bridge.test.mjs")],
+        env={**os.environ, "BRIDGE_BUNDLE": bundle.as_uri()},
+    )
+    assert tested.returncode == 0, tested.stdout + tested.stderr

reflex_perspective-0.3.0/tests/test_demo_access.py

@@ -0,0 +1,82 @@
+"""Demo app WebSocket access options (T-006): authorize + read-only."""
+
+import sys
+from pathlib import Path
+
+import pytest
+
+pytest.importorskip("perspective")
+
+from starlette.testclient import TestClient
+from starlette.websockets import WebSocketDisconnect
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "perspective_demo"))
+
+from perspective_demo import access
+from reflex_perspective import server as ps
+
+
+@pytest.fixture(autouse=True)
+def fresh_access():
+    access.Access.reset()
+    yield
+    access.Access.reset()
+
+
+@pytest.mark.parametrize(
+    ("value", "expected"),
+    [("1", True), ("true", True), ("YES", True), ("0", False), ("", False)],
+)
+def test_read_only_from_env(value, expected):
+    """REQ-SRV-013 (demo): PERSPECTIVE_DEMO_READ_ONLY turns read-only on."""
+    options = access.ws_options({access.READ_ONLY_ENV: value})
+    assert options["read_only"] is expected
+    assert options["authorize"] is access.authorize
+    assert options["on_reject"] is access.on_reject
+
+
+@pytest.mark.parametrize(
+    ("value", "expected"), [("3", 3), ("1", 1), ("", None), ("0", None), ("x", None)]
+)
+def test_max_sessions_from_env(value, expected):
+    """REQ-SRV-019 (demo): PERSPECTIVE_DEMO_MAX_SESSIONS caps the hub."""
+    assert (
+        access.ws_options({access.MAX_SESSIONS_ENV: value})["max_sessions"] == expected
+    )
+
+
+def test_defaults_off():
+    """REQ-SRV-017 (demo): without variables the demo is writable and uncapped."""
+    options = access.ws_options({})
+    assert options["read_only"] is False
+    assert options["max_sessions"] is None
+
+
+def connect_and_close_code(app, frame=None):
+    with (
+        TestClient(app) as client,
+        client.websocket_connect("/perspective") as ws,
+        pytest.raises(WebSocketDisconnect) as exc,
+    ):
+        if frame is not None:
+            ws.send_bytes(frame)
+        ws.receive_bytes()
+    return exc.value.code
+
+
+def test_closed_door_refuses_and_is_counted():
+    """REQ-SRV-011/020 (demo): closing the door refuses with 4403, counted."""
+    hub = ps.PerspectiveHub()
+    app = hub.asgi_app("/perspective", **access.ws_options({}))
+    access.Access.accepting = False
+    assert connect_and_close_code(app) == 4403
+    assert access.Access.rejections == {4403: 1}
+
+
+def test_refused_writes_are_counted():
+    """REQ-SRV-014/020 (demo): each read-only refusal is counted by on_reject."""
+    hub = ps.PerspectiveHub()
+    app = hub.asgi_app("/perspective", **access.ws_options({access.READ_ONLY_ENV: "1"}))
+    assert connect_and_close_code(app, b"\x08\x80") == 4409  # malformed (Art. 2)
+    assert access.Access.rejections == {4409: 1}
+    assert access.rejection_summary() == "4409×1"

{reflex_perspective-0.2.0 → reflex_perspective-0.3.0}/tests/test_server.py

@@ -619,6 +619,8 @@ def test_defaults_unchanged(func):
         "read_only": False,
         "write_close_code": 4409,
         "read_variants": None,
+        "max_sessions": None,
+        "on_reject": None,
     }
     for name, default in new.items():
         assert params[name].kind is inspect.Parameter.KEYWORD_ONLY, name
@@ -672,3 +674,148 @@ def test_classifier_is_public():
         "request_variant",
     ]:
         assert name in ps.__all__
+
+
+# ------------------------------------------------- session cap and on_reject
+def wait_for(predicate, timeout=5.0):
+    """Server-side cleanup runs after the client closes; poll briefly."""
+    import time
+
+    deadline = time.monotonic() + timeout
+    while not predicate():
+        if time.monotonic() > deadline:
+            return False
+        time.sleep(0.02)
+    return True
+
+
+def test_session_count():
+    """REQ-SRV-022: open WebSocket sessions are counted and released."""
+    hub = seeded_hub()
+    assert hub.session_count == 0
+    with TestClient(hub.asgi_app("/perspective")) as client:
+        with client.websocket_connect("/perspective") as a:
+            live_client(a).open_table("t").size()
+            with client.websocket_connect("/perspective") as b:
+                live_client(b).open_table("t").size()
+                assert hub.session_count == 2
+        assert wait_for(lambda: hub.session_count == 0)
+
+
+def test_max_sessions_refuses_with_4429():
+    """REQ-SRV-019: a full hub refuses new sockets with 4429, without a session."""
+    hub = seeded_hub(SpyServer())
+    app = hub.asgi_app("/perspective", max_sessions=1)
+    with TestClient(app) as client:
+        with client.websocket_connect("/perspective") as first:
+            assert live_client(first).open_table("t").size() == 1
+            with client.websocket_connect("/perspective") as second:
+                assert close_code(second) == 4429
+            assert hub.server.sessions == 1
+        assert wait_for(lambda: hub.session_count == 0)
+        with client.websocket_connect("/perspective") as third:
+            assert live_client(third).open_table("t").size() == 1
+
+
+def test_cap_checked_after_authorize():
+    """REQ-SRV-019: the authorize verdict wins over a full hub."""
+    hub = seeded_hub()
+    verdict = {"code": None}
+    app = hub.asgi_app(
+        "/perspective", max_sessions=1, authorize=lambda ws: verdict["code"]
+    )
+    with TestClient(app) as client, client.websocket_connect("/perspective") as a:
+        live_client(a).open_table("t").size()
+        verdict["code"] = 4403
+        with client.websocket_connect("/perspective") as b:
+            assert close_code(b) == 4403
+
+
+@pytest.mark.parametrize("value", [0, -1, 1.5, True, "2"])
+@pytest.mark.parametrize("build", ["asgi_app", "perspective_api", "mount"])
+def test_invalid_max_sessions(build, value):
+    """REQ-SRV-023: max_sessions must be an int >= 1."""
+    hub = make_hub()
+    builders = {
+        "asgi_app": lambda: hub.asgi_app(max_sessions=value),
+        "perspective_api": lambda: ps.perspective_api(hub=hub, max_sessions=value),
+        "mount": lambda: ps.mount(FakeApp(), hub=hub, max_sessions=value),
+    }
+    with pytest.raises(ValueError, match="max_sessions"):
+        builders[build]()
+
+
+def _reject_scenario(name, hub, on_reject):
+    """Open one socket that gets refused for ``name``; return its close code."""
+    kw = {"on_reject": on_reject}
+    headers = {}
+    if name == "origin":
+        kw["allowed_origins"] = ["http://app.test"]
+        headers = {"origin": "http://evil.test"}
+    elif name == "authorize":
+        kw["authorize"] = lambda ws: 4401
+    elif name == "authorize_error":
+        kw["authorize"] = lambda ws: 1 / 0
+    elif name == "read_only":
+        kw["read_only"] = True
+    elif name == "cap":
+        kw["max_sessions"] = 1
+    app = hub.asgi_app("/perspective", **kw)
+    with TestClient(app) as client:
+        if name == "origin":
+            with (
+                pytest.raises(WebSocketDisconnect) as exc,
+                client.websocket_connect("/perspective", headers=headers),
+            ):
+                pass
+            return exc.value.code
+        if name == "cap":
+            with client.websocket_connect("/perspective") as keep:
+                live_client(keep).open_table("t").size()
+                with client.websocket_connect("/perspective") as ws:
+                    return close_code(ws)
+        with client.websocket_connect("/perspective") as ws:
+            if name == "read_only":
+                ws.send_bytes(frame("update"))
+            return close_code(ws)
+
+
+REJECTIONS = {
+    "origin": 1008,
+    "authorize": 4401,
+    "authorize_error": 1011,
+    "read_only": 4409,
+    "cap": 4429,
+}
+
+
+@pytest.mark.parametrize("asynchronous", [False, True], ids=["sync", "async"])
+@pytest.mark.parametrize("name", list(REJECTIONS))
+def test_on_reject_reports_each_code(name, asynchronous):
+    """REQ-SRV-020: every refusal reaches on_reject with its close code."""
+    calls = []
+
+    def hook(code, websocket):
+        calls.append((code, websocket))
+
+    async def hook_async(code, websocket):
+        await asyncio.sleep(0)
+        calls.append((code, websocket))
+
+    code = _reject_scenario(name, seeded_hub(), hook_async if asynchronous else hook)
+    assert code == REJECTIONS[name]
+    assert [c for c, _ in calls] == [REJECTIONS[name]]
+    assert isinstance(calls[0][1], WebSocket)
+
+
+@pytest.mark.parametrize("name", ["authorize", "read_only", "cap"])
+def test_on_reject_error_keeps_close_code(name, caplog):
+    """REQ-SRV-021: a failing on_reject is logged and the close code stands."""
+
+    def boom(code, websocket):
+        raise RuntimeError("metrics backend down")
+
+    with caplog.at_level(logging.ERROR, logger="reflex_perspective.server"):
+        code = _reject_scenario(name, seeded_hub(), boom)
+    assert code == REJECTIONS[name]
+    assert any(r.exc_info for r in caplog.records)

{reflex_perspective-0.2.0 → reflex_perspective-0.3.0}/tests/test_specs.py

@@ -81,10 +81,12 @@ def test_changelog_lists_releases():
     assert "### Security" in changelog
 
 
-FOLDED_REQS = [f"REQ-SRV-0{n}" for n in range(10, 19)] + [
+FOLDED_REQS = [f"REQ-SRV-0{n}" for n in range(10, 24)] + [
     "REQ-VER-003",
     "REQ-VER-004",
     "REQ-VER-005",
+    "REQ-VIEW-011",
+    "REQ-VIEW-012",
 ]
 
 

{reflex_perspective-0.2.0 → reflex_perspective-0.3.0}/tests/test_viewer.py

@@ -107,3 +107,35 @@ def test_constants():
     assert "Datagrid" in rp.PLUGINS and "Treemap" in rp.PLUGINS
     assert "Pro Dark" in rp.THEMES
     assert "sum" in rp.AGGREGATES
+
+
+class Conn(rx.State):
+    url: str = ""
+    code: int = 0
+
+    @rx.event
+    def lost(self, url: str):
+        self.url = url
+
+    @rx.event
+    def lost_with_code(self, url: str, code: int | None):
+        self.url, self.code = url, code or 0
+
+
+def test_on_disconnect_accepts_url_and_code():
+    """REQ-VIEW-012: on_disconnect passes (url, code); 1-arg handlers still work."""
+    for handler in (Conn.lost, Conn.lost_with_code):
+        js = render(
+            rp.perspective_viewer(
+                server_url="/perspective", server_table="t", on_disconnect=handler
+            )
+        )
+        assert "onDisconnect" in js
+    two = render(
+        rp.perspective_viewer(
+            server_url="/perspective",
+            server_table="t",
+            on_disconnect=Conn.lost_with_code,
+        )
+    )
+    assert "_code" in two

reflex_perspective-0.2.0/tests/test_demo_access.py

@@ -1,70 +0,0 @@
-"""Demo app WebSocket access options (T-006): authorize + read-only."""
-
-import sys
-from pathlib import Path
-
-import pytest
-
-pytest.importorskip("perspective")
-
-from starlette.testclient import TestClient
-from starlette.websockets import WebSocketDisconnect
-
-sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "perspective_demo"))
-
-from perspective_demo import access
-from reflex_perspective import server as ps
-
-
-@pytest.fixture(autouse=True)
-def fresh_access():
-    access.Access.reset()
-    yield
-    access.Access.reset()
-
-
-@pytest.mark.parametrize(
-    ("value", "expected"),
-    [("1", True), ("true", True), ("YES", True), ("0", False), ("", False)],
-)
-def test_read_only_from_env(value, expected):
-    """REQ-SRV-013 (demo): PERSPECTIVE_DEMO_READ_ONLY turns read-only on."""
-    options = access.ws_options({access.READ_ONLY_ENV: value})
-    assert options["read_only"] is expected
-    assert options["authorize"] is access.authorize
-
-
-def test_read_only_off_by_default():
-    """REQ-SRV-017 (demo): without the variable the demo stays writable."""
-    assert access.ws_options({})["read_only"] is False
-
-
-def test_authorize_counts_and_refuses_when_closed():
-    """REQ-SRV-011 (demo): closing the door refuses new viewers with 4403."""
-    hub = ps.PerspectiveHub()
-    app = hub.asgi_app("/perspective", **access.ws_options({}))
-    with TestClient(app) as client:
-        with client.websocket_connect("/perspective"):
-            pass
-        access.Access.accepting = False
-        with (
-            client.websocket_connect("/perspective") as ws,
-            pytest.raises(WebSocketDisconnect) as exc,
-        ):
-            ws.receive_bytes()
-    assert exc.value.code == 4403
-    assert (access.Access.accepted, access.Access.refused) == (1, 1)
-
-
-def test_refused_writes_are_counted_from_the_library_log():
-    """REQ-SRV-014 (demo): each read-only refusal bumps the counter."""
-    hub = ps.PerspectiveHub()
-    app = hub.asgi_app("/perspective", **access.ws_options({access.READ_ONLY_ENV: "1"}))
-    with (
-        TestClient(app) as client,
-        client.websocket_connect("/perspective") as ws,
-        pytest.raises(WebSocketDisconnect),
-    ):
-        ws.send_bytes(b"\x08\x80")  # malformed frame (Art. 2 allows hand-written)
-        ws.receive_bytes()
-    assert access.Access.writes_refused == 1