portal-mojo 0.2.9 → 0.2.11

package/docs/auth.md

@@ -28,6 +28,12 @@ onAuth('rotated', () => queryClient.invalidateQueries());  // same user, re-issu
 - JWT pair (`access_token`/`refresh_token`); single-flight refresh (3
   concurrent 401s → ONE refresh POST); pre-request gate throws a synthetic
   `AuthRequiredError` instead of firing doomed requests.
+- A temporary refresh failure (network, timeout or server unavailable) blocks
+  the protected request and rejects with the original transport error. It
+  keeps the session and emits `refresh-failed`, so cached workspaces can stay
+  open. Only expired/unusable credentials or confirmed refresh 401/403 emit
+  `unauthorized` and become `AuthRequiredError`. `refreshTokens()` still
+  resolves a boolean, and concurrent gated calls share one refresh POST.
 - `useAuthSnapshot()` → `{authenticated, uid, email}` — live, cross-tab.
 - `logout()` is client-side (django-mojo has no logout endpoint) and emits
   `'logout'`.

package/docs/realtime.md

@@ -17,7 +17,8 @@ disable this shared provider.
 - An open socket is not ready. The client waits for `auth_required`, then sends
   `{type:'authenticate',token,prefix:'bearer'}` and becomes ready only after
   `auth_success`. An auth error closes and suspends the connection until the
-  token value changes.
+  token value changes. The exact direct admission-capacity error described
+  below is a transport refusal, not an authentication failure.
 - Heartbeat is a `ping` every 20 seconds with a 10-second `pong` deadline.
   A server-initiated `{type:'ping'}` (django-mojo 1.32+ sends one every 20
   seconds and culls a socket silent for 90) is answered at once with
@@ -25,7 +26,11 @@ disable this shared provider.
   dispatched to consumers. Answering from the message handler keeps the socket
   alive while a background tab throttles the client's own ping timer.
   Reconnect uses capped jittered backoff. Pre-accept close code 4429 enforces at
-  least 60 seconds, and focus/visibility cannot bypass that deadline.
+  least 60 seconds. The direct `{type:'error',message:'Too many connections'}`
+  admission refusal while authenticating or ready uses the same delay, even
+  when followed by a normal server close. Focus/visibility, token replacement,
+  and provider remount cannot bypass the deadline on that client. Queued frames
+  from the refused socket are ignored; recovery still requires authentication.
 - Desired topics are refcounted and replay after authentication. Operations are
   serialized because acknowledgements carry only the topic and denial is a
   generic uncorrelated `error`. Denial yields topic status `denied`; it does not
@@ -42,6 +47,12 @@ disable this shared provider.
 
 A top-level `{type:'error'}` frame is attributed in order:
 
+0. **Exact admission capacity refusal** — `message === 'Too many connections'`
+   while authenticating or ready: close and enter bounded `backoff`, without
+   dispatching an application error or declaring account access revoked.
+   Substrings, the `error` field, and wrapped application events do not match.
+   Consumers retain their independent HTTP authorization checks.
+
 1. **During authentication** — auth failure: the client closes and suspends
    until the token value changes. Surfaces through the lifecycle status only;
    no `error` event is dispatched.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "portal-mojo",
-    "version": "0.2.9",
+    "version": "0.2.11",
     "description": "React portal toolkit for django-mojo — typed client + params store, mission-control UI, dependency-free SVG charts, admin section bundles.",
     "type": "module",
     "license": "Apache-2.0",

package/src/client/auth.ts

@@ -10,8 +10,8 @@
 //     10 min, or older than 60 min, with a valid refresh token → refresh)
 //   · pre-request gate: bypass /api/token/refresh exactly (recursion guard)
 //     and requests made with no stored token (pre-login / public); otherwise
-//     ensureValidToken() — throws AuthRequiredError, which the transport
-//     turns into a synthetic 401 REJECT without calling fetch
+//     ensureValidToken() — blocks fetch on any refresh failure; only a
+//     confirmed denial becomes AuthRequiredError (synthetic 401)
 //   · auth-code / magic-token URL handoff: the param is scrubbed from the URL
 //     *synchronously, before any network call*, so a slow exchange cannot
 //     leak the one-time code to third-party scripts reading location.search
@@ -174,13 +174,18 @@ export function checkTokenStatus(): { action: TokenAction; reason: string } {
     return { action: 'none', reason: 'All tokens valid and not expiring soon' };
 }
 
-let refreshPromise: Promise<boolean> | null = null;
+type RefreshOutcome = { ok: true } | { ok: false; error?: unknown };
+let refreshPromise: Promise<RefreshOutcome> | null = null;
 
 /**
  * Refresh the access token. Single-flight: concurrent callers share one
  * in-flight POST. Always resolves to a boolean; never throws.
  */
 export function refreshTokens(): Promise<boolean> {
+    return refreshOutcome().then(result => result.ok);
+}
+
+function refreshOutcome(): Promise<RefreshOutcome> {
     if (!refreshPromise) {
         refreshPromise = doRefresh().finally(() => {
             refreshPromise = null;
@@ -189,13 +194,13 @@ export function refreshTokens(): Promise<boolean> {
     return refreshPromise;
 }
 
-async function doRefresh(): Promise<boolean> {
+async function doRefresh(): Promise<RefreshOutcome> {
     const refresh = getRefreshToken();
     const info = tokenInfo(refresh);
     if (!refresh || !info?.isValid || info.isExpired) {
         emitAuth('unauthorized');
         stopAutoRefresh();
-        return false;
+        return { ok: false };
     }
     const persistent = sessionIsPersistent();
     // The answer is for the session whose refresh token was sent. When the
@@ -208,30 +213,31 @@ async function doRefresh(): Promise<boolean> {
     const sessionUsable = (): boolean => checkTokenStatus().action !== 'logout';
     try {
         const body = await mojoCall(REFRESH_PATH, { method: 'POST', body: { refresh_token: refresh } });
-        if (superseded()) return sessionUsable();
+        if (superseded()) return { ok: sessionUsable() };
         const pkg = body.data as { access_token: string; refresh_token?: string };
         setTokens(pkg.access_token, pkg.refresh_token, persistent);
         emitAuth('refreshed');
-        return true;
+        return { ok: true };
     } catch (error) {
-        if (superseded()) return sessionUsable();
+        if (superseded()) return { ok: sessionUsable() };
         const status = error instanceof Error && 'status' in error ? (error as { status: number }).status : 0;
         if (status === 401 || status === 403) {
             emitAuth('unauthorized');
             stopAutoRefresh();
+            return { ok: false };
         } else {
             // Transient (network/5xx): keep the session, report, let the
             // watcher or the next gated request retry.
             emitAuth('refresh-failed', error);
+            return { ok: false, error };
         }
-        return false;
     }
 }
 
 /**
  * Pre-request gate (TokenManager.ensureValidToken). Throws AuthRequiredError
- * when the request must not be sent; the transport short-circuits it to a
- * synthetic-401 reject without touching the network.
+ * on confirmed denial. A temporary refresh failure preserves its original
+ * error; both failures block the protected request without touching fetch.
  */
 export async function ensureValidToken(): Promise<void> {
     const status = checkTokenStatus();
@@ -241,8 +247,11 @@ export async function ensureValidToken(): Promise<void> {
         throw new AuthRequiredError('Both access and refresh tokens are invalid');
     }
     if (status.action === 'refresh') {
-        const ok = await refreshTokens();
-        if (!ok) throw new AuthRequiredError('Token refresh failed');
+        const result = await refreshOutcome();
+        if (!result.ok) {
+            if ('error' in result) throw result.error;
+            throw new AuthRequiredError('Token refresh failed');
+        }
     }
 }
 

package/src/client/realtime.ts

@@ -241,6 +241,12 @@ export class RealtimeClient {
     private open(): void {
         if (!this.enabled || !this.token || this.suspended || this.socket) return;
         const run = this.generation;
+        // Token refresh and provider remount use this same entry point; neither
+        // may bypass a server admission deadline.
+        if (this.clock.now() < this.extendedBackoffUntil) {
+            this.scheduleReconnect(run, 0);
+            return;
+        }
         this.setLifecycle('connecting');
         let socket: RealtimeSocket;
         try {
@@ -312,6 +318,21 @@ export class RealtimeClient {
             if (typeof frame.topic === 'string') this.completeTopic(frame.type, frame.topic);
             return;
         }
+        if (frame.type === 'error' && frame.message === 'Too many connections'
+            && (this.lifecycle === 'authenticating' || this.lifecycle === 'ready')) {
+            // django-mojo's admission refusal also arrives after the challenge
+            // (or a ready-state capacity check), followed by a normal close.
+            // Fence queued frames before closing: late auth_success must not
+            // clear the deadline or make this refused socket ready.
+            this.extendedBackoffUntil = this.clock.now() + 60_000;
+            this.socket = null;
+            this.clearHeartbeat();
+            this.resetTopicConnectionState();
+            this.automaticUserTopic = null;
+            this.scheduleReconnect(run, 4429);
+            socket.close(4429, 'Connection limit');
+            return;
+        }
         if (frame.type === 'error') {
             if (this.lifecycle === 'authenticating') {
                 this.suspend('auth-failed', 4003, 'Authentication failed');