Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript

fix(control-ui): follow the session in capability consumers and keep shared recovery alive

Alfredo Lopez26d7e281a58a
diff --git a/control-ui/lib/__tests__/readRequestCache.test.ts b/control-ui/lib/__tests__/readRequestCache.test.ts
index 59e40a054..ff28a887f 100644
--- a/control-ui/lib/__tests__/readRequestCache.test.ts
+++ b/control-ui/lib/__tests__/readRequestCache.test.ts
@@ -466,6 +466,75 @@ describe('bounded metadata read reuse', () => {
expect(fetchMock).toHaveBeenCalledTimes(4)
})
+ describe('consumers refused by the family cooldown', () => {
+ const connections = '/api/v1/admin/connections'
+ const models = '/api/v1/admin/models'
+
+ async function denyFirstConsumer(signal: AbortSignal) {
+ fetchMock.mockResolvedValueOnce(throttled(2))
+ await expect(
+ apiGet(connections, {}, { metadataRead: 'subscription-connections', signal })
+ ).rejects.toMatchObject({ status: 429 })
+ }
+
+ it.each([
+ ['the same URL', connections],
+ ['a different URL in the same family', models],
+ ])(
+ 'keep the recovery alive after the first consumer leaves (%s)',
+ async (_label, joinedPath) => {
+ const first = new AbortController()
+ const second = new AbortController()
+ await denyFirstConsumer(first.signal)
+ await vi.advanceTimersByTimeAsync(1_000)
+ await expect(
+ apiGet(
+ joinedPath,
+ {},
+ { metadataRead: 'subscription-model-catalog', signal: second.signal }
+ )
+ ).rejects.toMatchObject({ status: 429 })
+ // Joining sends nothing.
+ expect(fetchMock).toHaveBeenCalledOnce()
+
+ first.abort()
+ fetchMock.mockResolvedValueOnce(success({ connections: ['recovered'] }))
+ // The original deadline (t = 2 s) still applies: joining at t = 1 s
+ // neither extended it nor added a second attempt.
+ await vi.advanceTimersByTimeAsync(1_000)
+ expect(fetchMock).toHaveBeenCalledTimes(2)
+ expect(String(fetchMock.mock.calls[1][0])).toMatch(/\/api\/v1\/admin\/connections$/)
+ await vi.advanceTimersByTimeAsync(60_000)
+ expect(fetchMock).toHaveBeenCalledTimes(2)
+ }
+ )
+
+ it('cancel the recovery once every registered consumer has left', async () => {
+ const first = new AbortController()
+ const second = new AbortController()
+ await denyFirstConsumer(first.signal)
+ await expect(
+ apiGet(models, {}, { metadataRead: 'subscription-model-catalog', signal: second.signal })
+ ).rejects.toMatchObject({ status: 429 })
+ first.abort()
+ second.abort()
+ await vi.advanceTimersByTimeAsync(60_000)
+ expect(fetchMock).toHaveBeenCalledOnce()
+ })
+
+ it('do not hold the recovery alive when they have no signal to observe', async () => {
+ const first = new AbortController()
+ await denyFirstConsumer(first.signal)
+ await expect(
+ apiGet(models, {}, { metadataRead: 'subscription-model-catalog' })
+ ).rejects.toMatchObject({ status: 429 })
+ expect(fetchMock).toHaveBeenCalledOnce()
+ first.abort()
+ await vi.advanceTimersByTimeAsync(60_000)
+ expect(fetchMock).toHaveBeenCalledOnce()
+ })
+ })
+
it('schedules a recovery for a remount after every earlier subscriber left', async () => {
const path = '/api/v1/admin/connections'
const firstMount = new AbortController()
diff --git a/control-ui/lib/api.ts b/control-ui/lib/api.ts
index 811d8ac15..56cd02993 100644
--- a/control-ui/lib/api.ts
+++ b/control-ui/lib/api.ts
@@ -21,6 +21,7 @@ import {
getReadRequestPrincipal,
getReadRequestRecovery,
invalidateReadRequestCacheEntry,
+ joinReadRequestRecovery,
reserveReadRequestRecovery,
setReadRequestCacheEntry,
setReadRequestCooldown,
@@ -449,7 +450,10 @@ async function apiRead(
}
if (familyKey) {
const cooldown = getReadRequestCooldown(familyKey)
- if (cooldown) throw cooldown
+ if (cooldown) {
+ joinReadRequestRecovery(familyKey, options.signal)
+ throw cooldown
+ }
if (!recoveringFamily) {
const recovery = getReadRequestRecovery(familyKey)
if (recovery) {
diff --git a/control-ui/lib/hooks/__tests__/useSubscriptionCapabilities.cache.test.tsx b/control-ui/lib/hooks/__tests__/useSubscriptionCapabilities.cache.test.tsx
index 4736c75ce..9f5df0421 100644
--- a/control-ui/lib/hooks/__tests__/useSubscriptionCapabilities.cache.test.tsx
+++ b/control-ui/lib/hooks/__tests__/useSubscriptionCapabilities.cache.test.tsx
@@ -1,6 +1,6 @@
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import { act, cleanup, renderHook, waitFor } from '@testing-library/react'
-import { setControlUIReadPrincipal } from '../../api'
+import { clearAdminAuthToken, setControlUIReadPrincipal } from '../../api'
import { __resetReadRequestCacheForTests } from '../../readRequestCache'
import { SUBSCRIPTION_CAPABILITIES_API_PATH } from '../../subscriptionCapabilities'
import { useSubscriptionCapabilities } from '../useSubscriptionCapabilities'
@@ -60,4 +60,88 @@ describe('useSubscriptionCapabilities with the real read cache', () => {
expect(failed.result.current.error).toBeNull()
expect(capabilityReads(fetchMock)).toBe(2)
})
+
+ describe('when the confirmed principal changes while the consumer stays mounted', () => {
+ const sessionOneBody = {
+ providers: {
+ 'codex-subscription': { enabled: true },
+ 'grok-subscription': { enabled: false },
+ },
+ }
+ const sessionTwoBody = {
+ providers: {
+ 'codex-subscription': { enabled: false },
+ 'grok-subscription': { enabled: true },
+ },
+ }
+
+ function capabilitiesResponse(body: unknown): Response {
+ return new Response(JSON.stringify(body), {
+ status: 200,
+ headers: { 'content-type': 'application/json' },
+ })
+ }
+
+ function deferredResponse() {
+ let resolve!: (response: Response) => void
+ const promise = new Promise<Response>(onResolve => {
+ resolve = onResolve
+ })
+ return { promise, resolve }
+ }
+
+ it('drops the completed result of the previous session and loads for the new one', async () => {
+ fetchMock.mockResolvedValueOnce(capabilitiesResponse(sessionOneBody))
+ const consumer = renderHook(() => useSubscriptionCapabilities())
+ await waitFor(() => expect(consumer.result.current.capabilities).toEqual(sessionOneBody))
+
+ const sessionTwoRead = deferredResponse()
+ fetchMock.mockReturnValueOnce(sessionTwoRead.promise)
+ act(() => setControlUIReadPrincipal('admin-two', 'admin'))
+ // Until the new session's read answers, nothing from the old one shows.
+ await waitFor(() => expect(capabilityReads(fetchMock)).toBe(2))
+ expect(consumer.result.current.capabilities).toBeNull()
+ expect(consumer.result.current.loading).toBe(true)
+
+ await act(async () => sessionTwoRead.resolve(capabilitiesResponse(sessionTwoBody)))
+ await waitFor(() => expect(consumer.result.current.capabilities).toEqual(sessionTwoBody))
+ expect(consumer.result.current.loading).toBe(false)
+ expect(consumer.result.current.error).toBeNull()
+ })
+
+ it('replaces a read still pending for the previous session', async () => {
+ const sessionOneRead = deferredResponse()
+ fetchMock.mockReturnValueOnce(sessionOneRead.promise)
+ const consumer = renderHook(() => useSubscriptionCapabilities())
+ await waitFor(() => expect(capabilityReads(fetchMock)).toBe(1))
+
+ fetchMock.mockResolvedValueOnce(capabilitiesResponse(sessionTwoBody))
+ act(() => setControlUIReadPrincipal('admin-two', 'admin'))
+ await act(async () => sessionOneRead.resolve(capabilitiesResponse(sessionOneBody)))
+
+ // A replacement read for the new session runs and settles the consumer;
+ // it never ends with unknown capabilities and no load or error.
+ await waitFor(() => expect(consumer.result.current.capabilities).toEqual(sessionTwoBody))
+ expect(capabilityReads(fetchMock)).toBe(2)
+ expect(consumer.result.current.loading).toBe(false)
+ expect(consumer.result.current.error).toBeNull()
+ })
+
+ it('waits for a confirmed session after the principal is cleared', async () => {
+ fetchMock.mockResolvedValueOnce(capabilitiesResponse(sessionOneBody))
+ const consumer = renderHook(() => useSubscriptionCapabilities())
+ await waitFor(() => expect(consumer.result.current.capabilities).toEqual(sessionOneBody))
+
+ act(() => clearAdminAuthToken())
+ expect(consumer.result.current.capabilities).toBeNull()
+ expect(consumer.result.current.loading).toBe(true)
+ act(() => consumer.result.current.retry())
+ expect(capabilityReads(fetchMock)).toBe(1)
+
+ fetchMock.mockResolvedValueOnce(capabilitiesResponse(sessionTwoBody))
+ act(() => setControlUIReadPrincipal('admin-two', 'admin'))
+ await waitFor(() => expect(consumer.result.current.capabilities).toEqual(sessionTwoBody))
+ expect(capabilityReads(fetchMock)).toBe(2)
+ })
+ })
})
diff --git a/control-ui/lib/hooks/useSubscriptionCapabilities.ts b/control-ui/lib/hooks/useSubscriptionCapabilities.ts
index 9005adbdd..f04de85e2 100644
--- a/control-ui/lib/hooks/useSubscriptionCapabilities.ts
+++ b/control-ui/lib/hooks/useSubscriptionCapabilities.ts
@@ -1,11 +1,16 @@
'use client'
-import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
+import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore } from 'react'
import {
METADATA_READ_MAX_RECOVERY_ATTEMPTS,
METADATA_READ_UNTIMED_COOLDOWN_MS,
} from '@constants/readRequests'
import type { ApiRequestError } from '../api.types'
+import {
+ getReadRequestPrincipal,
+ getReadRequestSessionIdentity,
+ subscribeReadRequestSessionIdentity,
+} from '../readRequestCache'
import {
type SubscriptionCapabilities,
loadSubscriptionCapabilities,
@@ -59,19 +64,45 @@ export function useSubscriptionCapabilities(
}
}, [])
+ // The confirmed principal. When it changes, the previous session's result,
+ // error and recovery budget are dropped and the new session loads its own;
+ // with no confirmed principal the hook waits, loading, for /me to confirm one.
+ const sessionIdentity = useSyncExternalStore(
+ subscribeReadRequestSessionIdentity,
+ getReadRequestSessionIdentity,
+ () => 0
+ )
+ const sessionIdentityRef = useRef(sessionIdentity)
+ // Set when the session this consumer loaded for ended without a successor;
+ // Retry cannot load for an unconfirmed session, only /me can end the wait.
+ const sessionEndedRef = useRef(false)
+
useEffect(() => {
+ if (sessionIdentityRef.current !== sessionIdentity) {
+ sessionIdentityRef.current = sessionIdentity
+ setCapabilities(null)
+ setError(null)
+ recoveryAttemptsRef.current = 0
+ sessionEndedRef.current = getReadRequestPrincipal() === null
+ }
if (!enabled) {
requestRef.current += 1
controllerRef.current?.abort()
setLoading(false)
return
}
+ if (sessionEndedRef.current) {
+ requestRef.current += 1
+ controllerRef.current?.abort()
+ setLoading(true)
+ return
+ }
void load()
return () => {
requestRef.current += 1
controllerRef.current?.abort()
}
- }, [enabled, load, retryNonce])
+ }, [enabled, load, retryNonce, sessionIdentity])
useEffect(() => {
if (
diff --git a/control-ui/lib/readRequestCache.ts b/control-ui/lib/readRequestCache.ts
index 3722830a1..ca3820164 100644
--- a/control-ui/lib/readRequestCache.ts
+++ b/control-ui/lib/readRequestCache.ts
@@ -43,11 +43,32 @@ let principal: PrincipalContext | null = null
let invalidationChannel: BroadcastChannel | null = null
let invalidationHandler: ((remote?: boolean) => void) | null = null
let generation = 0
+// Changes only when the confirmed principal changes (A -> B, A -> none,
+// none -> A). Unlike `generation`, unrelated metadata mutations leave it alone,
+// so mounted consumers can use it to drop the previous session's state.
+let sessionIdentity = 0
+const sessionIdentityListeners = new Set<() => void>()
function isBrowser(): boolean {
return typeof window !== 'undefined'
}
+function announceSessionIdentityChange(): void {
+ sessionIdentity += 1
+ for (const listener of Array.from(sessionIdentityListeners)) listener()
+}
+
+export function getReadRequestSessionIdentity(): number {
+ return sessionIdentity
+}
+
+export function subscribeReadRequestSessionIdentity(listener: () => void): () => void {
+ sessionIdentityListeners.add(listener)
+ return () => {
+ sessionIdentityListeners.delete(listener)
+ }
+}
+
function ensureChannel(): BroadcastChannel | null {
if (!isBrowser() || typeof BroadcastChannel === 'undefined') return null
if (!invalidationChannel) {
@@ -56,9 +77,11 @@ function ensureChannel(): BroadcastChannel | null {
if ((event.data as { type?: unknown } | null)?.type === 'session-invalidation') {
// Another tab may have replaced the shared cookie. A fresh authenticated
// /me read must confirm the principal before this tab can cache again.
+ const wasVerified = principal !== null
principal = null
clearReadRequestCache()
invalidationHandler?.(true)
+ if (wasVerified) announceSessionIdentityChange()
}
}
}
@@ -90,6 +113,7 @@ export function setReadRequestPrincipal(principalId: string, scope: string): voi
// Initial /me confirmation is local; rebroadcasting it would make two tabs
// invalidate one another indefinitely. Actual identity/scope changes propagate.
if (wasVerified) channel?.postMessage({ type: 'session-invalidation' })
+ announceSessionIdentityChange()
}
export function clearReadRequestPrincipal(options: { sessionChanged?: boolean } = {}): void {
@@ -106,6 +130,7 @@ export function clearReadRequestPrincipal(options: { sessionChanged?: boolean }
if (wasVerified || options.sessionChanged) {
channel?.postMessage({ type: 'session-invalidation' })
}
+ if (wasVerified) announceSessionIdentityChange()
}
export function clearReadRequestCache(): void {
@@ -201,6 +226,20 @@ function disposeRecovery(entry: RecoveryEntry): void {
entry.reject(new DOMException('The read was cancelled', 'AbortError'))
}
+/**
+ * Register a consumer that the family cooldown refused as an interest in the
+ * scheduled recovery, so another consumer unmounting cannot cancel it while
+ * this one is still mounted. It sends nothing and leaves the deadline, the
+ * reread members and the attempt budget unchanged. A consumer without a
+ * signal has no lifecycle to observe and is not registered, so it can never
+ * hold a recovery alive on its own.
+ */
+export function joinReadRequestRecovery(key: string, signal: AbortSignal | undefined): void {
+ if (!signal || signal.aborted) return
+ const recovery = recoveries.get(key)
+ if (recovery?.state === 'scheduled') recovery.addSubscribers([signal])
+}
+
export function getReadRequestRecovery(key: string): Promise<void> | undefined {
const recovery = recoveries.get(key)
return recovery && recovery.deadlineMs <= Date.now() ? recovery.pending : undefined
diff --git a/control-ui/package-lock.json b/control-ui/package-lock.json
index bbe61f2ce..c82016381 100644
--- a/control-ui/package-lock.json
+++ b/control-ui/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "clerum-control-ui",
- "version": "0.1.714",
+ "version": "0.1.715",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "clerum-control-ui",
- "version": "0.1.714",
+ "version": "0.1.715",
"dependencies": {
"@clerum/display-field": "file:../packages/display-field",
"@clerum/frontend-components": "file:../packages/frontend-components",
diff --git a/control-ui/package.json b/control-ui/package.json
index 215b5cce3..0dc0b151f 100644
--- a/control-ui/package.json
+++ b/control-ui/package.json
@@ -1,6 +1,6 @@
{
"name": "clerum-control-ui",
- "version": "0.1.714",
+ "version": "0.1.715",
"private": true,
"scripts": {
"dev": "NEXT_IGNORE_INCORRECT_LOCKFILE=1 next dev",
diff --git a/docs/architecture/administrative-rate-limits.md b/docs/architecture/administrative-rate-limits.md
index 563870ece..c2dfd8242 100644
--- a/docs/architecture/administrative-rate-limits.md
+++ b/docs/architecture/administrative-rate-limits.md
@@ -155,7 +155,13 @@ once each and one at a time, every URL the server denied while it was
scheduled (for example the Codex and Grok inventories loaded together), and
stops at the first reread that is denied again. A denied recovery schedules no
further attempt, but it releases its reservation, so the next denial in that
-read family schedules its own. Forced refresh respects the same pause. Authentication changes, 401 and
+read family schedules its own. A consumer refused by the cooldown joins the
+scheduled recovery as an interest without sending a request or changing its
+deadline, members or budget, so the recovery is cancelled only when every
+registered consumer has left; a consumer without an abort signal is not
+registered. Capability consumers follow the confirmed principal: when it
+changes they drop the previous session's result and error and load for the
+new session, and with no confirmed principal they wait for one. Forced refresh respects the same pause. Authentication changes, 401 and
cross-tab invalidation fence old awaits and clear identity-bound state.
Aborting one subscriber does not cancel another subscriber’s shared request.
SSR does not retain cached/deduplicated results across requests.