Skip to content

Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active

🔭 feat: Recover Stale Chunks Without the Error Page and Ship Client Logs to RUM (#16701)

Danny Avila741978c95451
diff --git a/.env.example b/.env.example
index c3cd93f18b..0e771a7d94 100644
--- a/.env.example
+++ b/.env.example
@@ -384,6 +384,26 @@ NODE_MAX_OLD_SPACE_SIZE=6144
# RUM_PROXY_AUTHORIZATION=
# Use an HTTPS RUM_PROXY_TARGET_URL across trust boundaries. With authorization set,
# redirects are rejected; configure the final OTLP base URL, not a UI URL or /v1/traces.
+# The proxy accepts only OTLP JSON/protobuf content types. Both encodings are capped by
+# RUM_PROXY_BODY_LIMIT and parsed only after authentication and rate limiting.
+# RUM_PROXY_BODY_LIMIT=3mb
+# Per-user request budget for the proxy (traces and logs combined), per RUM_PROXY_USER_WINDOW
+# minutes. Over budget, requests get 429 and never reach the collector.
+# RUM_PROXY_USER_MAX=240
+# RUM_PROXY_USER_WINDOW=1
+
+# Client logs (opt-in, proxy mode only). Browsers export the client logger's
+# warn/error calls, error-boundary catches and stale-asset recovery events as OTLP log records
+# through /api/rum/v1/logs, with service.name=RUM_SERVICE_NAME and
+# deployment.environment=RUM_ENVIRONMENT. Records carry allowlisted fields only (logger message
+# template, error type, error message only for engine/browser/library-generated errors, stack
+# frames reduced to paths, route template, build id, browser/OS family, a random session id and
+# the active trace/span ids) and are scrubbed of emails, tokens, keys, JWTs, long ids/secrets,
+# quoted fragments and query strings. Message, prompt and response content, request/response
+# bodies and storage are never sent. Sessions follow RUM_SAMPLE_RATE; each page dedupes repeats
+# and caps volume (30 records/min, 300 per page load). While client logs, console capture and
+# replay are all off, the proxy refuses /api/rum/v1/logs, even from tabs on an older config.
+# RUM_CLIENT_LOGS=false
# Optional comma-separated first-party HTTPS origins/URLs that should receive traceparent headers.
# Wildcards and non-HTTPS targets are ignored.
diff --git a/api/server/index.js b/api/server/index.js
index 4ceba2caff..9d28fc7a17 100644
--- a/api/server/index.js
+++ b/api/server/index.js
@@ -27,6 +27,7 @@ const {
createSecurityHeaders,
performStartupChecks,
handleJsonParseError,
+ excludeRumBodyParser,
GenerationJobManager,
QUERY_DEVTOOLS_HEADER,
createStreamServices,
@@ -338,8 +339,8 @@ const startServer = async () => {
app.use('/api/agents/chat', agentStartupIngressMiddleware);
app.use(metricsMiddleware);
app.use(noIndex);
- app.use(express.json({ limit: '3mb' }));
- app.use(express.urlencoded({ extended: true, limit: '3mb' }));
+ app.use(excludeRumBodyParser(express.json({ limit: '3mb' })));
+ app.use(excludeRumBodyParser(express.urlencoded({ extended: true, limit: '3mb' })));
app.use(handleJsonParseError);
/**
diff --git a/api/server/index.spec.js b/api/server/index.spec.js
index 6b8f76543e..429a548bf0 100644
--- a/api/server/index.spec.js
+++ b/api/server/index.spec.js
@@ -102,7 +102,9 @@ describe('Telemetry wiring', () => {
const ingressIndex = source.indexOf(
"app.use('/api/agents/chat', agentStartupIngressMiddleware);",
);
- const jsonParserIndex = source.indexOf("app.use(express.json({ limit: '3mb' }));");
+ const jsonParserIndex = source.indexOf(
+ "app.use(excludeRumBodyParser(express.json({ limit: '3mb' })));",
+ );
const recorderIndex = source.indexOf(
"app.use('/api/agents/chat', agentStartupTelemetryMiddleware);",
);
@@ -111,6 +113,7 @@ describe('Telemetry wiring', () => {
expect(ingressIndex).toBeGreaterThan(-1);
expect(recorderIndex).toBeGreaterThan(-1);
+ expect(jsonParserIndex).toBeGreaterThan(-1);
expect(ingressIndex).toBeLessThan(jsonParserIndex);
expect(tracingIndex).toBeLessThan(recorderIndex);
expect(recorderIndex).toBeLessThan(agentsRouteIndex);
diff --git a/api/server/routes/__tests__/config.rum.spec.js b/api/server/routes/__tests__/config.rum.spec.js
index 4400888ac2..3cebde9ae2 100644
--- a/api/server/routes/__tests__/config.rum.spec.js
+++ b/api/server/routes/__tests__/config.rum.spec.js
@@ -69,6 +69,7 @@ afterEach(() => {
delete process.env.RUM_ADVANCED_NETWORK_CAPTURE;
delete process.env.RUM_SAMPLE_RATE;
delete process.env.RUM_ENVIRONMENT;
+ delete process.env.RUM_CLIENT_LOGS;
});
describe('GET /api/config RUM config', () => {
@@ -98,6 +99,7 @@ describe('GET /api/config RUM config', () => {
advancedNetworkCapture: false,
sampleRate: 0.25,
environment: 'test',
+ clientLogs: false,
});
});
@@ -136,10 +138,23 @@ describe('GET /api/config RUM config', () => {
consoleCapture: false,
disableReplay: true,
advancedNetworkCapture: false,
+ clientLogs: false,
});
},
);
+ it('turns client logs on in proxy mode only when RUM_CLIENT_LOGS=true', async () => {
+ mockGetAppConfig.mockResolvedValue(baseAppConfig);
+ process.env.RUM_ENABLED = 'true';
+ process.env.RUM_AUTH_MODE = 'proxy';
+ process.env.RUM_PROXY_TARGET_URL = 'http://otel-collector:4318';
+ process.env.RUM_CLIENT_LOGS = 'true';
+
+ const response = await request(createApp(mockUser)).get('/api/config');
+
+ expect(response.body.rum).toEqual(expect.objectContaining({ clientLogs: true }));
+ });
+
it('omits proxy RUM config without a target collector URL', async () => {
mockGetAppConfig.mockResolvedValue(baseAppConfig);
process.env.RUM_ENABLED = 'true';
diff --git a/api/server/routes/__tests__/rum.spec.js b/api/server/routes/__tests__/rum.spec.js
index 39acf89008..318f62e113 100644
--- a/api/server/routes/__tests__/rum.spec.js
+++ b/api/server/routes/__tests__/rum.spec.js
@@ -3,7 +3,18 @@ const request = require('supertest');
const mockRequireRumProxyAuth = jest.fn((_req, _res, next) => next());
const mockIsRumProxyEnabled = jest.fn();
+const mockIsRumLogsEndpointEnabled = jest.fn(() => true);
const mockProxyRumRequest = jest.fn((_req, res) => res.status(202).send());
+const mockRumProxyLimiter = jest.fn((_req, _res, next) => next());
+const mockLimiterSetup = [];
+const mockCreateRumProxyLimiter = jest.fn((options) => {
+ mockLimiterSetup.push(['createRumProxyLimiter', options]);
+ return mockRumProxyLimiter;
+});
+const mockLimiterCache = jest.fn((prefix) => {
+ mockLimiterSetup.push(['limiterCache', prefix]);
+ return 'limiter-store';
+});
jest.mock('~/server/middleware', () => ({
requireRumProxyAuth: (...args) => mockRequireRumProxyAuth(...args),
@@ -11,7 +22,18 @@ jest.mock('~/server/middleware', () => ({
jest.mock('@librechat/api', () => ({
getRumProxyBodyLimit: jest.fn(() => '3mb'),
- isRumProxyEnabled: (...args) => mockIsRumProxyEnabled(...args),
+ limiterCache: (...args) => mockLimiterCache(...args),
+ createRumProxyLimiter: (...args) => mockCreateRumProxyLimiter(...args),
+ requireRumProxyEnabled: (_req, res, next) =>
+ mockIsRumProxyEnabled()
+ ? next()
+ : res.status(404).json({ message: 'RUM proxy is not configured' }),
+ requireRumLogsEnabled: (_req, res, next) =>
+ mockIsRumLogsEndpointEnabled()
+ ? next()
+ : res.status(404).json({ message: 'RUM logs are not enabled' }),
+ handleJsonParseError: (err, _req, res, next) =>
+ err.type === 'entity.parse.failed' ? res.status(400).end() : next(err),
proxyRumRequest: (...args) => mockProxyRumRequest(...args),
}));
@@ -29,6 +51,27 @@ describe('RUM proxy routes', () => {
mockRequireRumProxyAuth.mockClear();
mockIsRumProxyEnabled.mockReset();
mockProxyRumRequest.mockClear();
+ mockRumProxyLimiter.mockClear();
+ mockIsRumLogsEndpointEnabled.mockReset();
+ mockIsRumLogsEndpointEnabled.mockReturnValue(true);
+ });
+
+ it('refuses logs, but not traces, when no browser log source is enabled', async () => {
+ mockIsRumProxyEnabled.mockReturnValue(true);
+ mockIsRumLogsEndpointEnabled.mockReturnValue(false);
+
+ const logs = await request(app)
+ .post('/api/rum/v1/logs')
+ .set('Content-Type', 'application/json')
+ .send({ resourceLogs: [] });
+ const traces = await request(app)
+ .post('/api/rum/v1/traces')
+ .set('Content-Type', 'application/json')
+ .send({ resourceSpans: [] });
+
+ expect(logs.status).toBe(404);
+ expect(traces.status).toBe(202);
+ expect(mockProxyRumRequest).toHaveBeenCalledTimes(1);
});
afterEach(() => {
@@ -100,4 +143,46 @@ describe('RUM proxy routes', () => {
expect(mockRequireRumProxyAuth).toHaveBeenCalledTimes(1);
expect(mockProxyRumRequest).toHaveBeenCalledTimes(1);
});
+
+ it('builds the per-user limiter on the shared limiter store', () => {
+ expect(mockLimiterSetup).toEqual([
+ ['limiterCache', 'rum_proxy_user_limiter'],
+ ['createRumProxyLimiter', { store: 'limiter-store' }],
+ ]);
+ });
+
+ it.each(['traces', 'logs'])('rate limits %s after auth and before proxying', async (signal) => {
+ mockIsRumProxyEnabled.mockReturnValue(true);
+ const order = [];
+ mockRequireRumProxyAuth.mockImplementationOnce((_req, _res, next) => {
+ order.push('auth');
+ next();
+ });
+ mockRumProxyLimiter.mockImplementationOnce((_req, res) => {
+ order.push('limit');
+ res.status(429).json({ message: 'Too many RUM telemetry requests' });
+ });
+
+ const response = await request(app)
+ .post(`/api/rum/v1/${signal}`)
+ .set('Content-Type', 'application/json')
+ .send({ resourceLogs: [] });
+
+ expect(response.status).toBe(429);
+ expect(order).toEqual(['auth', 'limit']);
+ expect(mockProxyRumRequest).not.toHaveBeenCalled();
+ });
+
+ it('skips the limiter when session authentication drops the request', async () => {
+ mockIsRumProxyEnabled.mockReturnValue(true);
+ mockRequireRumProxyAuth.mockImplementationOnce((_req, res) => res.status(204).end());
+
+ const response = await request(app)
+ .post('/api/rum/v1/logs')
+ .set('Content-Type', 'application/json')
+ .send({ resourceLogs: [] });
+
+ expect(response.status).toBe(204);
+ expect(mockRumProxyLimiter).not.toHaveBeenCalled();
+ });
});
diff --git a/api/server/routes/rum.js b/api/server/routes/rum.js
index 08c78939b8..fd6ed4ca40 100644
--- a/api/server/routes/rum.js
+++ b/api/server/routes/rum.js
@@ -1,5 +1,13 @@
const express = require('express');
-const { getRumProxyBodyLimit, isRumProxyEnabled, proxyRumRequest } = require('@librechat/api');
+const {
+ limiterCache,
+ proxyRumRequest,
+ requireRumProxyEnabled,
+ getRumProxyBodyLimit,
+ requireRumLogsEnabled,
+ handleJsonParseError,
+ createRumProxyLimiter,
+} = require('@librechat/api');
const { requireRumProxyAuth } = require('~/server/middleware');
const router = express.Router();
@@ -8,17 +16,19 @@ const rawOtlpBody = express.raw({
type: ['application/x-protobuf', 'application/octet-stream'],
});
-function requireRumProxyEnabled(_req, res, next) {
- if (!isRumProxyEnabled()) {
- return res.status(404).json({ message: 'RUM proxy is not configured' });
- }
-
- return next();
-}
-
+const rumProxyLimiter = createRumProxyLimiter({ store: limiterCache('rum_proxy_user_limiter') });
const proxyTelemetry = (req, res) => proxyRumRequest(req, res, process.env.RUM_PROXY_AUTHORIZATION);
+const telemetryPipeline = [
+ requireRumProxyEnabled,
+ requireRumProxyAuth,
+ rumProxyLimiter,
+ express.json({ limit: getRumProxyBodyLimit() }),
+ rawOtlpBody,
+ handleJsonParseError,
+ proxyTelemetry,
+];
-router.post('/v1/traces', requireRumProxyEnabled, requireRumProxyAuth, rawOtlpBody, proxyTelemetry);
-router.post('/v1/logs', requireRumProxyEnabled, requireRumProxyAuth, rawOtlpBody, proxyTelemetry);
+router.post('/v1/traces', ...telemetryPipeline);
+router.post('/v1/logs', requireRumLogsEnabled, ...telemetryPipeline);
module.exports = router;
diff --git a/api/server/services/Config/rum.js b/api/server/services/Config/rum.js
index c9f36ea80b..4d8eca2de9 100644
--- a/api/server/services/Config/rum.js
+++ b/api/server/services/Config/rum.js
@@ -1,4 +1,9 @@
-const { getRumProxyClientUrl, isEnabled, isRumProxyEnabled } = require('@librechat/api');
+const {
+ isEnabled,
+ isRumProxyEnabled,
+ getRumProxyClientUrl,
+ isRumClientLogsEnabled,
+} = require('@librechat/api');
const { logger } = require('@librechat/data-schemas');
const DEFAULT_RUM_SERVICE_NAME = 'librechat-web';
@@ -145,6 +150,7 @@ function getRumConfig() {
advancedNetworkCapture,
...(sampleRate != null ? { sampleRate } : {}),
...(process.env.RUM_ENVIRONMENT ? { environment: process.env.RUM_ENVIRONMENT } : {}),
+ clientLogs: isRumClientLogsEnabled(),
};
}
diff --git a/client/index.html b/client/index.html
index 3c083790ae..4757942db6 100644
--- a/client/index.html
+++ b/client/index.html
@@ -206,10 +206,18 @@
return false;
}
}
+ /* Every caller in this page shares one recovery: once a reload is underway, later
+ * chunk failures (Vite preload, unhandled rejection, error boundary) join it instead
+ * of tripping the loop guard and painting the error page before the reload lands. */
window.__lcRecoverStaleAssets = function () {
+ if (window.__lcStaleAssetRecoveryPending === true) {
+ return true;
+ }
if (!shouldRecover()) {
+ window.__lcRumPush('stale-asset-recovery-declined');
return false;
}
+ window.__lcStaleAssetRecoveryPending = true;
window.__lcRumPush('stale-asset-recovery-start');
var reload = function () {
window.__lcRumPush('stale-asset-recovery-reload');
@@ -264,7 +272,9 @@
assetUrl: el.src || el.href,
optional: isRumBootstrap,
});
- if (isRumBootstrap) {
+ /* Caught optional imports must not reload the app. Required lazy imports
+ * recover at their own boundary; preload links only report diagnostics. */
+ if (isRumBootstrap || failedPreload) {
return;
}
window.__lcRecoverStaleAssets();
diff --git a/client/src/components/Artifacts/ArtifactTabs.tsx b/client/src/components/Artifacts/ArtifactTabs.tsx
index c1461f86ff..956dcdcf28 100644
--- a/client/src/components/Artifacts/ArtifactTabs.tsx
+++ b/client/src/components/Artifacts/ArtifactTabs.tsx
@@ -1,4 +1,4 @@
-import { lazy, Suspense, useRef } from 'react';
+import { Suspense, useRef } from 'react';
import { Spinner } from '@librechat/client';
import * as Tabs from '@radix-ui/react-tabs';
import type { SandpackPreviewRef } from '@codesandbox/sandpack-react/unstyled';
@@ -8,9 +8,10 @@ import { MermaidRenderer } from '~/components/Messages/Content/Mermaid/Mermaid';
import { MERMAID_ARTIFACT_TYPE, type Artifact } from '~/common/artifacts';
import { useArtifactCode } from '~/Providers/EditorContext';
import { ArtifactCodeEditor } from './ArtifactCodeEditor';
+import { lazyWithRecovery } from '~/lib/assets/lazy';
import { useLocalize } from '~/hooks';
-const SandboxArtifactTabs = lazy(() => import('./SandboxArtifactTabs'));
+const SandboxArtifactTabs = lazyWithRecovery(() => import('./SandboxArtifactTabs'));
interface ArtifactTabsProps {
artifact: Artifact;
diff --git a/client/src/components/Chat/Messages/Content/MarkdownErrorBoundary.tsx b/client/src/components/Chat/Messages/Content/MarkdownErrorBoundary.tsx
index ee90039c7f..d3e6f8bf17 100644
--- a/client/src/components/Chat/Messages/Content/MarkdownErrorBoundary.tsx
+++ b/client/src/components/Chat/Messages/Content/MarkdownErrorBoundary.tsx
@@ -6,6 +6,7 @@ import rehypeHighlight from 'rehype-highlight';
import type { PluggableList } from 'unified';
import { code, codeNoExecution, a, p, img, table } from './MarkdownComponents';
import { langSubset, remarkApproxTilde } from '~/utils';
+import { reportBoundaryError } from '~/lib/rum/logs';
import { CodeBlockProvider } from '~/Providers';
interface ErrorBoundaryState {
@@ -34,6 +35,7 @@ class MarkdownErrorBoundary extends React.Component<
componentDidCatch(error: Error, errorInfo: React.ErrorInfo) {
console.error('Markdown rendering error:', error, errorInfo);
+ reportBoundaryError('markdown', error);
}
componentDidUpdate(prevProps: MarkdownErrorBoundaryProps) {
diff --git a/client/src/components/Chat/Messages/PrivateText.tsx b/client/src/components/Chat/Messages/PrivateText.tsx
index 95e3fee300..16f4160aaa 100644
--- a/client/src/components/Chat/Messages/PrivateText.tsx
+++ b/client/src/components/Chat/Messages/PrivateText.tsx
@@ -1,4 +1,4 @@
-import { createContext, lazy, Suspense, useContext } from 'react';
+import { createContext, Suspense, useContext } from 'react';
import { QueryClientProvider, useQueryClient } from '@tanstack/react-query';
import type { TMessage } from 'librechat-data-provider';
import type { ReactNode } from 'react';
@@ -7,11 +7,15 @@ import {
getOwnerQueryClient,
useOwnerMessageTexts,
} from '~/data-provider/Messages/private';
+import { importWithRecovery, lazyWithRecovery } from '~/lib/assets/lazy';
import { useAuthContext } from '~/hooks/AuthContext';
import { useLocalize } from '~/hooks';
-const DisplayMessage = lazy(async () => ({
- default: (await import('./Content/MessageContent')).DisplayMessage,
-}));
+
+const DisplayMessage = lazyWithRecovery(() =>
+ importWithRecovery(() => import('./Content/MessageContent')).then((m) => ({
+ default: m.DisplayMessage,
+ })),
+);
interface Original {
canonicalText: string;
diff --git a/client/src/components/Chat/Presentation.tsx b/client/src/components/Chat/Presentation.tsx
index 7fe4c32b35..c2de6ef799 100644
--- a/client/src/components/Chat/Presentation.tsx
+++ b/client/src/components/Chat/Presentation.tsx
@@ -1,4 +1,4 @@
-import { lazy, Suspense, useCallback, useEffect, useMemo, useRef } from 'react';
+import { Suspense, useCallback, useEffect, useMemo, useRef } from 'react';
import { useRecoilValue } from 'recoil';
import { useAtomValue, useSetAtom } from 'jotai';
import { EModelEndpoint, FileSources, LocalStorageKeys } from 'librechat-data-provider';
@@ -13,12 +13,15 @@ import { artifactsUndocked } from '~/components/Artifacts/state';
import { EditorProvider, ArtifactsProvider } from '~/Providers';
import { SidePanelGroup } from '~/components/SidePanel';
import AppChatSurface from '~/components/Chat/Surface';
+import { lazyWithRecovery } from '~/lib/assets/lazy';
import { useSetFilesToDelete } from '~/hooks';
import { failedFileIdsFrom } from '~/utils';
import store from '~/store';
-const Artifacts = lazy(() => import('~/components/Artifacts/Artifacts'));
-const SubagentThreadPanel = lazy(() => import('~/components/Chat/Subagents/SubagentThreadPanel'));
+const Artifacts = lazyWithRecovery(() => import('~/components/Artifacts/Artifacts'));
+const SubagentThreadPanel = lazyWithRecovery(
+ () => import('~/components/Chat/Subagents/SubagentThreadPanel'),
+);
export default function Presentation({
children,
diff --git a/client/src/components/Messages/Content/Mermaid/MermaidErrorBoundary.tsx b/client/src/components/Messages/Content/Mermaid/MermaidErrorBoundary.tsx
index 1d71b927ad..d6d783d7b0 100644
--- a/client/src/components/Messages/Content/Mermaid/MermaidErrorBoundary.tsx
+++ b/client/src/components/Messages/Content/Mermaid/MermaidErrorBoundary.tsx
@@ -1,4 +1,5 @@
import React from 'react';
+import { reportBoundaryError } from '~/lib/rum/logs';
interface MermaidErrorBoundaryProps {
children: React.ReactNode;
@@ -24,6 +25,7 @@ class MermaidErrorBoundary extends React.Component<
componentDidCatch(error: Error, errorInfo: React.ErrorInfo) {
console.error('Mermaid rendering error:', error, errorInfo);
+ reportBoundaryError('mermaid', error);
}
componentDidUpdate(prevProps: MermaidErrorBoundaryProps) {
@@ -35,11 +37,11 @@ class MermaidErrorBoundary extends React.Component<
render() {
if (this.state.hasError) {
return (
- <div className="w-full overflow-hidden rounded-md border border-border-light">
- <div className="rounded-t-md bg-surface-secondary px-4 py-2 font-sans text-xs text-text-secondary">
+ <div className="border-border-light w-full overflow-hidden rounded-md border">
+ <div className="bg-surface-secondary text-text-secondary rounded-t-md px-4 py-2 font-sans text-xs">
{'mermaid'}
</div>
- <pre className="overflow-auto whitespace-pre-wrap rounded-b-md bg-surface-primary-alt p-4 font-mono text-xs text-text-secondary">
+ <pre className="bg-surface-primary-alt text-text-secondary overflow-auto rounded-b-md p-4 font-mono text-xs whitespace-pre-wrap">
{this.props.code}
</pre>
</div>
diff --git a/client/src/components/QueryDevtoolsGate.tsx b/client/src/components/QueryDevtoolsGate.tsx
index ad794aca6f..2e8eb50810 100644
--- a/client/src/components/QueryDevtoolsGate.tsx
+++ b/client/src/components/QueryDevtoolsGate.tsx
@@ -1,4 +1,5 @@
-import { lazy, Suspense } from 'react';
+import { Suspense } from 'react';
+import { importWithRecovery, lazyWithRecovery } from '~/lib/assets/lazy';
interface QueryDevtoolsConfig {
enableQueryDevtools?: boolean;
@@ -9,10 +10,10 @@ interface QueryDevtoolsGateProps {
isDevelopment?: boolean;
}
-const LazyReactQueryDevtools = lazy(() =>
- import('@tanstack/react-query-devtools/production').then(({ ReactQueryDevtools }) => ({
- default: ReactQueryDevtools,
- })),
+const LazyReactQueryDevtools = lazyWithRecovery(() =>
+ importWithRecovery(() => import('@tanstack/react-query-devtools/production')).then(
+ ({ ReactQueryDevtools }) => ({ default: ReactQueryDevtools }),
+ ),
);
export const shouldEnableQueryDevtools = ({
diff --git a/client/src/components/Share/ShareArtifacts.tsx b/client/src/components/Share/ShareArtifacts.tsx
index 0dc3fa131d..f52ec8e52c 100644
--- a/client/src/components/Share/ShareArtifacts.tsx
+++ b/client/src/components/Share/ShareArtifacts.tsx
@@ -1,4 +1,4 @@
-import { lazy, Suspense, useState, useMemo } from 'react';
+import { Suspense, useState, useMemo } from 'react';
import { useAtomValue } from 'jotai';
import { useRecoilValue } from 'recoil';
import {
@@ -15,11 +15,12 @@ import { artifactsUndocked } from '~/components/Artifacts/state';
import { ArtifactsProvider, EditorProvider } from '~/Providers';
import { useGetSharedStartupConfig } from '~/data-provider';
import { isCodeOnlyArtifact } from '~/utils/artifacts';
+import { lazyWithRecovery } from '~/lib/assets/lazy';
import { useShareContext } from '~/Providers';
import { getLatestText } from '~/utils';
import store from '~/store';
-const Artifacts = lazy(() => import('~/components/Artifacts/Artifacts'));
+const Artifacts = lazyWithRecovery(() => import('~/components/Artifacts/Artifacts'));
const DEFAULT_ARTIFACT_PANEL_SIZE = 40;
const SHARE_ARTIFACT_PANEL_STORAGE_KEY = 'share:artifacts-panel-size';
diff --git a/client/src/components/System/Updating.tsx b/client/src/components/System/Updating.tsx
new file mode 100644
index 0000000000..084f2e87dc
--- /dev/null
+++ b/client/src/components/System/Updating.tsx
@@ -0,0 +1,18 @@
+import { Spinner } from '@librechat/client';
+import { useLocalize } from '~/hooks';
+
+/** Shown in place of an error page while the app reloads onto a newer deploy. */
+export default function Updating() {
+ const localize = useLocalize();
+
+ return (
+ <div
+ role="status"
+ aria-live="polite"
+ className="bg-surface-primary text-text-secondary flex min-h-screen items-center justify-center gap-3 text-sm"
+ >
+ <Spinner />
+ <span>{localize('com_ui_updating_latest_version')}</span>
+ </div>
+ );
+}
diff --git a/client/src/components/UnifiedSidebar/ExpandedPanel.tsx b/client/src/components/UnifiedSidebar/ExpandedPanel.tsx
index 82c85291db..4c11217685 100644
--- a/client/src/components/UnifiedSidebar/ExpandedPanel.tsx
+++ b/client/src/components/UnifiedSidebar/ExpandedPanel.tsx
@@ -1,4 +1,4 @@
-import { memo, useCallback, lazy, Suspense } from 'react';
+import { memo, useCallback, Suspense } from 'react';
import { SquarePen } from 'lucide-react';
import { useLocation } from 'react-router-dom';
import { Skeleton, Sidebar, Button, TooltipAnchor } from '@librechat/client';
@@ -7,11 +7,12 @@ import { useShortcutAriaKey, useShortcutHint } from '~/hooks/useKeyboardShortcut
import { useActivePanel, resolveActivePanel, DEFAULT_PANEL } from '~/Providers';
import AgentMarketplaceButton from '~/components/Nav/AgentMarketplaceButton';
import { CLOSE_SIDEBAR_ID } from '~/components/Chat/Menus/OpenSidebar';
+import { lazyWithRecovery } from '~/lib/assets/lazy';
import useNewChat from '~/hooks/Chat/useNewChat';
import { useLocalize } from '~/hooks';
import { cn } from '~/utils';
-const AccountSettings = lazy(() => import('~/components/Nav/AccountSettings'));
+const AccountSettings = lazyWithRecovery(() => import('~/components/Nav/AccountSettings'));
const NewChatButton = memo(function NewChatButton({
setActive,
diff --git a/client/src/components/UnifiedSidebar/mobile/Header.tsx b/client/src/components/UnifiedSidebar/mobile/Header.tsx
index 8def10b126..fb25648eb4 100644
--- a/client/src/components/UnifiedSidebar/mobile/Header.tsx
+++ b/client/src/components/UnifiedSidebar/mobile/Header.tsx
@@ -1,13 +1,14 @@
-import { memo, lazy, Suspense, useEffect, useRef } from 'react';
+import { memo, Suspense, useEffect, useRef } from 'react';
import { Button, Sidebar, Skeleton } from '@librechat/client';
import type { NavLink } from '~/common';
import { CLOSE_SIDEBAR_ID } from '~/components/Chat/Menus/OpenSidebar';
import { useShortcutAriaKey } from '~/hooks/useKeyboardShortcuts';
+import { lazyWithRecovery } from '~/lib/assets/lazy';
import { useLocalize } from '~/hooks';
import Switcher from './Switcher';
import NewChat from './NewChat';
-const AccountSettings = lazy(() => import('~/components/Nav/AccountSettings'));
+const AccountSettings = lazyWithRecovery(() => import('~/components/Nav/AccountSettings'));
/**
* At full width there is nothing beside the drawer left to tap, so this close
diff --git a/client/src/components/Web/SourcesErrorBoundary.tsx b/client/src/components/Web/SourcesErrorBoundary.tsx
index 3abb7c8c85..aeef3bb6e3 100644
--- a/client/src/components/Web/SourcesErrorBoundary.tsx
+++ b/client/src/components/Web/SourcesErrorBoundary.tsx
@@ -1,5 +1,6 @@
import React, { Component, ReactNode } from 'react';
import { Button } from '@librechat/client';
+import { reportBoundaryError } from '~/lib/rum/logs';
import { useLocalize } from '~/hooks';
interface Props {
@@ -17,12 +18,12 @@ function DefaultFallback() {
const localize = useLocalize();
return (
<div
- className="flex flex-col items-center justify-center rounded-lg border border-border-medium bg-surface-secondary p-4 text-center"
+ className="border-border-medium bg-surface-secondary flex flex-col items-center justify-center rounded-lg border p-4 text-center"
role="alert"
aria-live="polite"
>
{/* eslint-disable-next-line i18next/no-literal-string */}
- <div className="mb-2 text-sm text-text-secondary">Sources temporarily unavailable</div>
+ <div className="text-text-secondary mb-2 text-sm">Sources temporarily unavailable</div>
<Button
variant="outline"
size="sm"
@@ -44,6 +45,7 @@ class SourcesErrorBoundary extends Component<Props, State> {
componentDidCatch(error: Error, errorInfo: React.ErrorInfo) {
console.error('Sources error:', error);
+ reportBoundaryError('sources', error);
this.props.onError?.(error, errorInfo);
}
diff --git a/client/src/hooks/Auth/__tests__/usePasskey.spec.tsx b/client/src/hooks/Auth/__tests__/usePasskey.spec.tsx
index 62ae019165..5498fce55b 100644
--- a/client/src/hooks/Auth/__tests__/usePasskey.spec.tsx
+++ b/client/src/hooks/Auth/__tests__/usePasskey.spec.tsx
@@ -15,6 +15,7 @@ function deferred(): Deferred {
return { promise, reject };
}
+let mockWebAuthnImportError: Error | undefined;
const mockStartAuthentication = jest.fn();
const mockGetPasskeyLoginOptions = jest.fn();
const mockVerifyPasskeyLogin = jest.fn();
@@ -23,11 +24,16 @@ const mockNavigate = jest.fn();
const mockLocalize = (key: string) => key;
const mockToastContext = { showToast: mockShowToast };
-jest.mock('@simplewebauthn/browser', () => ({
- startAuthentication: (...args: unknown[]) => mockStartAuthentication(...args),
- browserSupportsWebAuthn: () => true,
- browserSupportsWebAuthnAutofill: async () => true,
-}));
+jest.mock('@simplewebauthn/browser', () => {
+ if (mockWebAuthnImportError) {
+ throw mockWebAuthnImportError;
+ }
+ return {
+ startAuthentication: (...args: unknown[]) => mockStartAuthentication(...args),
+ browserSupportsWebAuthn: () => true,
+ browserSupportsWebAuthnAutofill: async () => true,
+ };
+});
jest.mock('librechat-data-provider', () => ({
...jest.requireActual('librechat-data-provider'),
@@ -56,6 +62,11 @@ jest.mock('~/data-provider', () => ({
}));
describe('usePasskeySignIn', () => {
+ afterEach(() => {
+ mockWebAuthnImportError = undefined;
+ delete window.__lcRecoverStaleAssets;
+ delete window.__lcStaleAssetRecoveryPending;
+ });
beforeEach(() => {
jest.clearAllMocks();
Object.defineProperty(window, 'PublicKeyCredential', {
@@ -65,6 +76,26 @@ describe('usePasskeySignIn', () => {
mockGetPasskeyLoginOptions.mockResolvedValue({ options: {}, sessionId: 'session' });
});
+ it('recovers a missing WebAuthn chunk before its local sign-in catch', async () => {
+ mockWebAuthnImportError = new TypeError(
+ 'Failed to fetch dynamically imported module: /assets/webauthn-old.js',
+ );
+ const recover = jest.fn(() => false);
+ window.__lcRecoverStaleAssets = recover;
+ const { result } = renderHook(() => usePasskeySignIn({ enabled: true }));
+ await waitFor(() => expect(recover).toHaveBeenCalledTimes(1));
+ await act(async () => {
+ await result.current.signIn();
+ });
+ expect(recover).toHaveBeenCalledTimes(1);
+ expect(mockStartAuthentication).not.toHaveBeenCalled();
+ expect(mockGetPasskeyLoginOptions).not.toHaveBeenCalled();
+ expect(mockShowToast).toHaveBeenCalledWith({
+ message: 'com_auth_passkey_error',
+ status: 'error',
+ });
+ });
+
it('keeps the manual ceremony locked when it aborts the pending autofill ceremony', async () => {
const autofill = deferred();
const manual = deferred();
diff --git a/client/src/hooks/Auth/usePasskey.ts b/client/src/hooks/Auth/usePasskey.ts
index 29d1345b00..7752d996f3 100644
--- a/client/src/hooks/Auth/usePasskey.ts
+++ b/client/src/hooks/Auth/usePasskey.ts
@@ -25,10 +25,11 @@ import {
persistRedirectToSession,
} from '~/utils/redirect';
import { useRegisterPasskeyMutation } from '~/data-provider';
+import { importWithRecovery } from '~/lib/assets/lazy';
import useLocalize from '~/hooks/useLocalize';
async function loadWebAuthn() {
- return import('@simplewebauthn/browser');
+ return importWithRecovery(() => import('@simplewebauthn/browser'));
}
/** Thrown by the browser when the user dismisses or times out the native prompt. */
diff --git a/client/src/hooks/Files/__tests__/useFileHandling.test.ts b/client/src/hooks/Files/__tests__/useFileHandling.test.ts
index d5c0525230..a49b0956d8 100644
--- a/client/src/hooks/Files/__tests__/useFileHandling.test.ts
+++ b/client/src/hooks/Files/__tests__/useFileHandling.test.ts
@@ -47,6 +47,7 @@ beforeAll(() => {
});
});
+let mockHeicModuleError: Error | undefined;
const mockShowToast = jest.fn();
const mockSetFilesLoading = jest.fn();
const mockMutate = jest.fn();
@@ -137,9 +138,12 @@ jest.mock('../useDelayedUploadToast', () => ({
})),
}));
-jest.mock('~/utils/heicConverter', () => ({
- processFileForUpload: mockProcessFileForUpload,
-}));
+jest.mock('~/utils/heicConverter', () => {
+ if (mockHeicModuleError) {
+ throw mockHeicModuleError;
+ }
+ return { processFileForUpload: mockProcessFileForUpload };
+});
jest.mock('../useClientResize', () => ({
__esModule: true,
@@ -188,6 +192,11 @@ const mockValidateFileLimit = jest.requireMock('~/utils').validateFileLimit;
const mockValidateFileDuplicates = jest.requireMock('~/utils').validateFileDuplicates;
describe('useFileHandling', () => {
+ afterEach(() => {
+ mockHeicModuleError = undefined;
+ delete window.__lcRecoverStaleAssets;
+ delete window.__lcStaleAssetRecoveryPending;
+ });
beforeEach(() => {
jest.clearAllMocks();
mockValidateFiles.mockImplementation(() => true);
@@ -213,6 +222,23 @@ describe('useFileHandling', () => {
const loadHook = async () => (await import('../useFileHandling')).default;
+ it('requests recovery for the caught HEIC helper import failure without starting an upload', async () => {
+ mockHeicModuleError = new TypeError(
+ 'Failed to fetch dynamically imported module: /assets/heicConverter-old.js',
+ );
+ const recover = jest.fn(() => false);
+ window.__lcRecoverStaleAssets = recover;
+ jest.spyOn(console, 'log').mockImplementation(() => undefined);
+ const useFileHandling = await loadHook();
+ const { result } = renderHook(() => useFileHandling());
+ await act(async () => {
+ await result.current.handleFiles([new File(['heic'], 'photo.heic', { type: 'image/heic' })]);
+ });
+ expect(recover).toHaveBeenCalledTimes(1);
+ expect(mockMutate).not.toHaveBeenCalled();
+ expect(mockDeleteFileById).toHaveBeenCalledTimes(1);
+ });
+
it('removes rejected provider audio and localizes the upload error before retry', async () => {
const consoleLog = jest.spyOn(console, 'log').mockImplementation(() => undefined);
const useFileHandling = await loadHook();
diff --git a/client/src/hooks/Files/useFileHandling.ts b/client/src/hooks/Files/useFileHandling.ts
index ed76e2494a..08bb3c44ed 100644
--- a/client/src/hooks/Files/useFileHandling.ts
+++ b/client/src/hooks/Files/useFileHandling.ts
@@ -40,6 +40,7 @@ import useLocalize, { TranslationKeys } from '~/hooks/useLocalize';
import { useChatSettings } from '~/Providers/ChatSettingsContext';
import { useDelayedUploadToast } from './useDelayedUploadToast';
import { useChatContext } from '~/Providers/ChatContext';
+import { importWithRecovery } from '~/lib/assets/lazy';
import { ephemeralAgentByConvoId } from '~/store';
import useClientResize from './useClientResize';
import useUpdateFiles from './useUpdateFiles';
@@ -617,14 +618,15 @@ const useFileHandlingCore = (params: UseFileHandling | undefined, fileState: Fil
}
const heicProcessedFile = isHEIC
- ? await import('~/utils/heicConverter').then(({ processFileForUpload }) =>
- processFileForUpload(originalFile, 0.9, (conversionProgress) => {
- const adjustedProgress = 0.1 + conversionProgress * 0.4;
- replaceFile({
- ...initialExtendedFile,
- progress: adjustedProgress,
- });
- }),
+ ? await importWithRecovery(() => import('~/utils/heicConverter')).then(
+ ({ processFileForUpload }) =>
+ processFileForUpload(originalFile, 0.9, (conversionProgress) => {
+ const adjustedProgress = 0.1 + conversionProgress * 0.4;
+ replaceFile({
+ ...initialExtendedFile,
+ progress: adjustedProgress,
+ });
+ }),
)
: originalFile;
diff --git a/client/src/hooks/Mermaid/useMermaid.ts b/client/src/hooks/Mermaid/useMermaid.ts
index fc267fccb6..38698d3477 100644
--- a/client/src/hooks/Mermaid/useMermaid.ts
+++ b/client/src/hooks/Mermaid/useMermaid.ts
@@ -8,6 +8,7 @@ import {
inlineFlowchartConfig,
sanitizeMermaidSvg,
} from '~/utils/mermaid';
+import { importWithRecovery } from '~/lib/assets/lazy';
// Constants
const MD5_LENGTH_THRESHOLD = 10_000;
@@ -22,7 +23,7 @@ const loadMermaid = () => {
}
if (!mermaidPromise) {
- mermaidPromise = import('mermaid').then((mod) => mod.default);
+ mermaidPromise = importWithRecovery(() => import('mermaid')).then((mod) => mod.default);
}
return mermaidPromise;
diff --git a/client/src/lib/assets/__tests__/recovery.spec.tsx b/client/src/lib/assets/__tests__/recovery.spec.tsx
new file mode 100644
index 0000000000..8f28e1a767
--- /dev/null
+++ b/client/src/lib/assets/__tests__/recovery.spec.tsx
@@ -0,0 +1,167 @@
+import { Suspense } from 'react';
+import { resolve } from 'path';
+import { readFileSync } from 'fs';
+import { render, screen } from '@testing-library/react';
+import { createMemoryRouter, RouterProvider } from 'react-router-dom';
+import {
+ ChunkLoadError,
+ isChunkLoadError,
+ requestStaleAssetRecovery,
+ isStaleAssetRecoveryPending,
+} from '../recovery';
+import { importWithRecovery, lazyWithRecovery } from '../lazy';
+import RouteErrorBoundary from '~/routes/RouteErrorBoundary';
+
+jest.mock('~/hooks', () => {
+ const translations: Record<string, string> = jest.requireActual('~/locales/en/translation.json');
+ return { useLocalize: () => (key: string) => translations[key] ?? key };
+});
+
+const RECOVERY_KEY = 'lc-asset-recovery-at';
+
+function loadRecoveryScript(): void {
+ const html = readFileSync(resolve(__dirname, '../../../../index.html'), 'utf8');
+ const scripts = Array.from(html.matchAll(/<script>([\s\S]*?)<\/script>/g), (m) => m[1]);
+ const recoveryScript = scripts.find((script) => script.includes(RECOVERY_KEY));
+ if (!recoveryScript) {
+ throw new Error('Stale-asset recovery script not found in index.html');
+ }
+ new Function(recoveryScript)();
+}
+
+afterEach(() => {
+ delete window.__lcRecoverStaleAssets;
+ delete window.__lcStaleAssetRecoveryPending;
+ sessionStorage.clear();
+});
+
+describe('isChunkLoadError', () => {
+ it.each([
+ new TypeError('Failed to fetch dynamically imported module: https://x.test/assets/a.js'),
+ new TypeError('Importing a module script failed.'),
+ new TypeError('error loading dynamically imported module: /assets/a.js'),
+ new Error('Unable to preload CSS for /assets/a.css'),
+ Object.assign(new Error('Loading chunk 42 failed.'), { name: 'ChunkLoadError' }),
+ new ChunkLoadError(),
+ new Error('wrapped', { cause: new TypeError('Importing a module script failed.') }),
+ ])('recognizes %p', (error) => {
+ expect(isChunkLoadError(error)).toBe(true);
+ });
+
+ it.each([
+ new TypeError("Cannot read properties of undefined (reading 'default')"),
+ new Error('Network Error'),
+ 'Failed to fetch dynamically imported module',
+ null,
+ undefined,
+ ])('ignores %p', (error) => {
+ expect(isChunkLoadError(error)).toBe(false);
+ });
+});
+
+describe('requestStaleAssetRecovery', () => {
+ it('asks the page recovery once per error object', () => {
+ const recover = jest.fn(() => true);
+ window.__lcRecoverStaleAssets = recover;
+ const error = new ChunkLoadError();
+
+ expect(requestStaleAssetRecovery(error)).toBe(true);
+ expect(requestStaleAssetRecovery(error)).toBe(true);
+ expect(recover).toHaveBeenCalledTimes(1);
+ });
+
+ it('reports a declined recovery and never throws when the page script is missing', () => {
+ window.__lcRecoverStaleAssets = jest.fn(() => false);
+ expect(requestStaleAssetRecovery(new ChunkLoadError())).toBe(false);
+
+ delete window.__lcRecoverStaleAssets;
+ expect(requestStaleAssetRecovery(new ChunkLoadError())).toBe(false);
+ });
+});
+
+describe('importWithRecovery', () => {
+ it('turns a module the preload helper resolved to undefined into a ChunkLoadError', async () => {
+ await expect(importWithRecovery(() => Promise.resolve(undefined))).rejects.toBeInstanceOf(
+ ChunkLoadError,
+ );
+ });
+
+ it('recovers required imports without claiming unrelated optional preload failures', async () => {
+ const recover = jest.fn(() => true);
+ window.__lcRecoverStaleAssets = recover;
+ const optionalFailure = new Event('vite:preloadError', { cancelable: true });
+ window.dispatchEvent(optionalFailure);
+ expect(optionalFailure.defaultPrevented).toBe(false);
+ expect(recover).not.toHaveBeenCalled();
+ const requiredFailure = new TypeError('Importing a module script failed.');
+ await expect(importWithRecovery(() => Promise.reject(requiredFailure))).rejects.toBe(
+ requiredFailure,
+ );
+ expect(recover).toHaveBeenCalledTimes(1);
+ });
+
+ it('passes loaded modules and original failures through', async () => {
+ const module = { default: 'value' };
+ await expect(importWithRecovery(() => Promise.resolve(module))).resolves.toBe(module);
+ const failure = new TypeError('Failed to fetch dynamically imported module');
+ await expect(importWithRecovery(() => Promise.reject(failure))).rejects.toBe(failure);
+ });
+});
+
+describe('index.html recovery script', () => {
+ it('starts one recovery, joins later callers, and declines within the loop guard', () => {
+ /* jsdom reports `location.reload()` as an unimplemented navigation. */
+ const consoleError = jest.spyOn(console, 'error').mockImplementation(() => undefined);
+ window.__lcRumQueue = [];
+ loadRecoveryScript();
+ const recover = window.__lcRecoverStaleAssets;
+ if (!recover) {
+ throw new Error('recovery not installed');
+ }
+
+ expect(recover()).toBe(true);
+ expect(isStaleAssetRecoveryPending()).toBe(true);
+ expect(recover()).toBe(true);
+ expect(Number(sessionStorage.getItem(RECOVERY_KEY))).toBeGreaterThan(0);
+
+ delete window.__lcStaleAssetRecoveryPending;
+ window.__lcRumQueue = [];
+ loadRecoveryScript();
+ expect(window.__lcRecoverStaleAssets?.()).toBe(false);
+ expect(isStaleAssetRecoveryPending()).toBe(false);
+ expect(window.__lcRumQueue?.map((event) => event.type)).toEqual([
+ 'stale-asset-recovery-start',
+ 'stale-asset-recovery-reload',
+ 'stale-asset-recovery-declined',
+ ]);
+ consoleError.mockRestore();
+ });
+});
+
+describe('lazyWithRecovery under the route boundary', () => {
+ it('shows the updating state when the recovery claimed the failed chunk import', async () => {
+ const consoleError = jest.spyOn(console, 'error').mockImplementation(() => undefined);
+ window.__lcStaleAssetRecoveryPending = true;
+ window.__lcRecoverStaleAssets = jest.fn(() => true);
+ const Panel = lazyWithRecovery(() =>
+ Promise.resolve(undefined as unknown as { default: () => null }),
+ );
+ const router = createMemoryRouter([
+ {
+ path: '/',
+ element: (
+ <Suspense fallback={null}>
+ <Panel />
+ </Suspense>
+ ),
+ errorElement: <RouteErrorBoundary />,
+ },
+ ]);
+
+ render(<RouterProvider router={router} />);
+
+ expect(await screen.findByRole('status')).toHaveTextContent('Updating to the latest version');
+ expect(screen.queryByRole('alert')).not.toBeInTheDocument();
+ consoleError.mockRestore();
+ });
+});
diff --git a/client/src/lib/assets/lazy.ts b/client/src/lib/assets/lazy.ts
new file mode 100644
index 0000000000..68c8ad9dfd
--- /dev/null
+++ b/client/src/lib/assets/lazy.ts
@@ -0,0 +1,36 @@
+import { lazy } from 'react';
+import type { LazyExoticComponent } from 'react';
+import { ChunkLoadError, isChunkLoadError, requestStaleAssetRecovery } from './recovery';
+
+/** Whatever component type `React.lazy` itself accepts. */
+type LazyComponent = Awaited<ReturnType<Parameters<typeof lazy>[0]>>['default'];
+
+/**
+ * Required imports opt into recovery here, not in the global Vite handler. Optional imports
+ * keep their own failure policy. A missing module becomes a recognizable `ChunkLoadError`.
+ */
+export function importWithRecovery<M>(load: () => Promise<M>): Promise<M> {
+ return load()
+ .then((module) => {
+ if (module == null) {
+ throw new ChunkLoadError();
+ }
+ return module;
+ })
+ .catch((error: unknown) => {
+ if (isChunkLoadError(error)) {
+ requestStaleAssetRecovery(error);
+ }
+ throw error;
+ });
+}
+
+/**
+ * `React.lazy` for a code-split component whose load failures surface as `ChunkLoadError`.
+ * For a named export, map inside `importWithRecovery` so the module is checked first.
+ */
+export function lazyWithRecovery<T extends LazyComponent>(
+ load: () => Promise<{ default: T }>,
+): LazyExoticComponent<T> {
+ return lazy(() => importWithRecovery(load));
+}
diff --git a/client/src/lib/assets/recovery.ts b/client/src/lib/assets/recovery.ts
new file mode 100644
index 0000000000..5a73139664
--- /dev/null
+++ b/client/src/lib/assets/recovery.ts
@@ -0,0 +1,92 @@
+declare global {
+ interface Window {
+ /** Defined in `index.html`: unregisters the service worker and reloads, guarded against loops. */
+ __lcRecoverStaleAssets?: () => boolean;
+ /** Set by `index.html` once a recovery reload is underway in this page. */
+ __lcStaleAssetRecoveryPending?: boolean;
+ }
+}
+
+export const CHUNK_LOAD_ERROR_NAME = 'ChunkLoadError';
+
+const CHUNK_ERROR_MESSAGES = [
+ 'failed to fetch dynamically imported module',
+ 'importing a module script failed',
+ 'error loading dynamically imported module',
+ 'unable to preload css',
+ 'loading chunk',
+ 'loading css chunk',
+];
+
+type ErrorShape = {
+ name?: unknown;
+ message?: unknown;
+ cause?: unknown;
+};
+
+/**
+ * A code-split module that could not be loaded. Thrown when Vite's preload helper resolves a
+ * dynamic import to `undefined` after the stale-asset recovery claimed the failure, so the
+ * error boundary sees a recognizable chunk failure instead of a `TypeError` from `module.default`.
+ */
+export class ChunkLoadError extends Error {
+ constructor(message = 'Failed to load a code-split module') {
+ super(message);
+ this.name = CHUNK_LOAD_ERROR_NAME;
+ }
+}
+
+function matchesChunkError(error: ErrorShape): boolean {
+ if (error.name === CHUNK_LOAD_ERROR_NAME) {
+ return true;
+ }
+ if (typeof error.message !== 'string') {
+ return false;
+ }
+ const message = error.message.toLowerCase();
+ return CHUNK_ERROR_MESSAGES.some((pattern) => message.includes(pattern));
+}
+
+/** True for dynamic-import, chunk and CSS-preload failures, including one wrapped as `cause`. */
+export function isChunkLoadError(error: unknown): boolean {
+ if (typeof error !== 'object' || error === null) {
+ return false;
+ }
+ const shape: ErrorShape = error;
+ if (matchesChunkError(shape)) {
+ return true;
+ }
+ return typeof shape.cause === 'object' && shape.cause !== null && matchesChunkError(shape.cause);
+}
+
+export function isStaleAssetRecoveryPending(): boolean {
+ return typeof window !== 'undefined' && window.__lcStaleAssetRecoveryPending === true;
+}
+
+const outcomes = new WeakMap<object, boolean>();
+
+function startRecovery(): boolean {
+ try {
+ return window.__lcRecoverStaleAssets?.() === true;
+ } catch {
+ return false;
+ }
+}
+
+/**
+ * Asks the page-level recovery to reload onto the current build. Returns `false` when its loop
+ * guard declines (a recovery already ran moments ago), so callers fall back to the error UI.
+ * The outcome is cached per error so re-renders and strict-mode effects ask only once.
+ */
+export function requestStaleAssetRecovery(error?: unknown): boolean {
+ const key = typeof error === 'object' && error !== null ? error : undefined;
+ const cached = key ? outcomes.get(key) : undefined;
+ if (cached != null) {
+ return cached;
+ }
+ const started = isStaleAssetRecoveryPending() || startRecovery();
+ if (key) {
+ outcomes.set(key, started);
+ }
+ return started;
+}
diff --git a/client/src/lib/assets/useRecovery.ts b/client/src/lib/assets/useRecovery.ts
new file mode 100644
index 0000000000..cc8cf5b6cd
--- /dev/null
+++ b/client/src/lib/assets/useRecovery.ts
@@ -0,0 +1,28 @@
+import { useEffect, useState } from 'react';
+import {
+ isChunkLoadError,
+ requestStaleAssetRecovery,
+ isStaleAssetRecoveryPending,
+} from './recovery';
+
+/**
+ * For an error caught by a boundary, decides whether to show the "updating" state: a chunk
+ * failure from a stale build (or any error while a recovery reload is already underway) asks the
+ * page-level recovery to reload. When its loop guard declines, this returns `false` so the
+ * boundary renders its normal error UI with a manual reload instead of looping.
+ */
+export default function useStaleAssetRecovery(error: unknown): boolean {
+ const eligible = isChunkLoadError(error) || isStaleAssetRecoveryPending();
+ const [declinedError, setDeclinedError] = useState<unknown>(undefined);
+
+ useEffect(() => {
+ if (!eligible) {
+ return;
+ }
+ if (!requestStaleAssetRecovery(error)) {
+ setDeclinedError(error);
+ }
+ }, [eligible, error]);
+
+ return eligible && declinedError !== error;
+}
diff --git a/client/src/lib/rum/diagnostics.spec.ts b/client/src/lib/rum/diagnostics.spec.ts
index d7e2f1b4e2..a7976802c9 100644
--- a/client/src/lib/rum/diagnostics.spec.ts
+++ b/client/src/lib/rum/diagnostics.spec.ts
@@ -6,7 +6,14 @@ import {
registerFcpAttribution,
restoreRumEmitter,
testExports,
+ forwardQueuedAssetEvents,
} from './diagnostics';
+import {
+ startClientLogs,
+ stopClientLogs,
+ reportBoundaryError,
+ testExports as logTestExports,
+} from './logs';
const mockOnFCP = jest.fn();
@@ -239,3 +246,224 @@ describe('rum diagnostics', () => {
expect(mockOnFCP).toHaveBeenCalledTimes(2);
});
});
+
+describe('forwardQueuedAssetEvents', () => {
+ const fetchMock = jest.fn((_url: string, _init: RequestInit) => Promise.resolve({ status: 200 }));
+
+ beforeEach(() => {
+ jest.useFakeTimers();
+ logTestExports.resetPageState();
+ testExports.resetDiagnosticsState();
+ fetchMock.mockReset();
+ fetchMock.mockImplementation(() => Promise.resolve({ status: 200 }));
+ sessionStorage.clear();
+ window.__lcRumQueue = [
+ {
+ type: 'stale-asset-recovery-start',
+ at: 10,
+ attributes: { clientBuildId: 'index-Old1.js' },
+ },
+ { type: 'pageshow', at: 11, attributes: { persisted: false } },
+ ];
+ });
+
+ afterEach(() => {
+ stopClientLogs();
+ jest.useRealTimers();
+ });
+
+ const loggedEventNames = () =>
+ fetchMock.mock.calls.flatMap(([, init]) =>
+ JSON.parse(String(init.body)).resourceLogs[0].scopeLogs[0].logRecords.map(
+ (record: { body: { stringValue: string } }) => record.body.stringValue,
+ ),
+ );
+
+ it('delivers queued stale-asset events without the RUM SDK and never twice', async () => {
+ startClientLogs({
+ endpoint: '/api/rum/v1/logs',
+ serviceName: 'librechat-web',
+ buildId: 'index-New2.js',
+ getToken: () => 'session-jwt',
+ fetch: fetchMock,
+ });
+
+ forwardQueuedAssetEvents();
+ forwardQueuedAssetEvents();
+ expect(window.__lcRumQueue?.[0]).not.toHaveProperty('logged');
+
+ await jest.advanceTimersByTimeAsync(5_000);
+
+ expect(window.__lcRumQueue?.[0]).toEqual(expect.objectContaining({ logged: true }));
+ expect(window.__lcRumQueue?.[1]).not.toHaveProperty('logged');
+ expect(JSON.parse(sessionStorage.getItem('lc-rum-queue') ?? '[]')[0].logged).toBe(true);
+
+ flushEarlyRumQueue({ addAction: jest.fn() });
+ await jest.advanceTimersByTimeAsync(5_000);
+
+ expect(loggedEventNames()).toEqual(['stale_asset.recovery_start']);
+ });
+
+ it('keeps an event persisted across the RUM SDK flush until its log record is acknowledged', async () => {
+ const addAction = jest.fn();
+ startClientLogs({
+ endpoint: '/api/rum/v1/logs',
+ serviceName: 'librechat-web',
+ buildId: 'index-New2.js',
+ getToken: () => 'session-jwt',
+ fetch: fetchMock,
+ });
+
+ forwardQueuedAssetEvents();
+ flushEarlyRumQueue({ addAction });
+
+ const persisted = JSON.parse(sessionStorage.getItem('lc-rum-queue') ?? '[]');
+ expect(persisted).toEqual([
+ expect.objectContaining({ type: 'stale-asset-recovery-start', actionSent: true }),
+ ]);
+ expect(addAction).toHaveBeenCalledWith('early-stale-asset-recovery-start', expect.any(Object));
+
+ await jest.advanceTimersByTimeAsync(5_000);
+
+ expect(window.__lcRumQueue).toEqual([]);
+ expect(sessionStorage.getItem('lc-rum-queue')).toBeNull();
+ expect(loggedEventNames()).toEqual(['stale_asset.recovery_start']);
+ });
+
+ it('replays a persisted event after reload without repeating its RUM action', () => {
+ const addAction = jest.fn();
+ window.__lcRumQueue = [
+ { type: 'stale-asset-recovery-start', at: 10, attributes: {}, actionSent: true },
+ ];
+
+ flushEarlyRumQueue({ addAction });
+
+ expect(addAction).not.toHaveBeenCalledWith(
+ 'early-stale-asset-recovery-start',
+ expect.anything(),
+ );
+ });
+
+ it('keeps an undelivered event eligible for replay on the next page', async () => {
+ fetchMock.mockImplementation(() => Promise.resolve({ status: 503 }));
+ startClientLogs({
+ endpoint: '/api/rum/v1/logs',
+ serviceName: 'librechat-web',
+ buildId: 'index-New2.js',
+ getToken: () => 'session-jwt',
+ fetch: fetchMock,
+ });
+
+ forwardQueuedAssetEvents();
+ await jest.advanceTimersByTimeAsync(5_000);
+ stopClientLogs();
+
+ expect(fetchMock).toHaveBeenCalled();
+ expect(window.__lcRumQueue?.[0]).not.toHaveProperty('logged');
+ expect(sessionStorage.getItem('lc-rum-queue')).toBeNull();
+ });
+
+ it.each(['queued', 'sending'])(
+ 'retries an unacknowledged %s event after stop/start in the same page',
+ async (state) => {
+ if (state === 'sending') {
+ fetchMock.mockImplementationOnce(() => new Promise(() => undefined));
+ }
+ const config = {
+ endpoint: '/api/rum/v1/logs',
+ serviceName: 'librechat-web',
+ buildId: 'index-New2.js',
+ getToken: () => 'session-jwt',
+ fetch: fetchMock,
+ };
+ startClientLogs(config);
+ forwardQueuedAssetEvents();
+ flushEarlyRumQueue({ addAction: jest.fn() });
+ if (state === 'sending') {
+ await jest.advanceTimersByTimeAsync(5_000);
+ }
+ stopClientLogs();
+ expect(JSON.parse(sessionStorage.getItem('lc-rum-queue') ?? '[]')).toHaveLength(1);
+ fetchMock.mockImplementation(() => Promise.resolve({ status: 200 }));
+ startClientLogs(config);
+ forwardQueuedAssetEvents();
+ await jest.advanceTimersByTimeAsync(5_000);
+ expect(window.__lcRumQueue).toEqual([]);
+ expect(sessionStorage.getItem('lc-rum-queue')).toBeNull();
+ },
+ );
+
+ it('persists live asset events after the SDK emitter has replaced the early queue', async () => {
+ startClientLogs({
+ endpoint: '/api/rum/v1/logs',
+ serviceName: 'librechat-web',
+ buildId: 'index-New2.js',
+ getToken: () => 'session-jwt',
+ fetch: fetchMock,
+ });
+ window.__lcRumQueue = [];
+ restoreRumEmitter({ addAction: jest.fn() });
+ window.__lcRumPush?.('stale-asset-recovery-reload');
+ expect(JSON.parse(sessionStorage.getItem('lc-rum-queue') ?? '[]')).toEqual([
+ expect.objectContaining({ type: 'stale-asset-recovery-reload', actionSent: true }),
+ ]);
+ await jest.advanceTimersByTimeAsync(5_000);
+ expect(sessionStorage.getItem('lc-rum-queue')).toBeNull();
+ });
+
+ it('retains budget-rejected asset events across the SDK flush without false in-flight markers', async () => {
+ startClientLogs({
+ endpoint: '/api/rum/v1/logs',
+ serviceName: 'librechat-web',
+ buildId: 'index-New2.js',
+ getToken: () => 'session-jwt',
+ fetch: fetchMock,
+ });
+ for (let i = 0; i < 30; i += 1) {
+ reportBoundaryError(`boundary-${i}`, new Error('failed'));
+ }
+ forwardQueuedAssetEvents();
+ flushEarlyRumQueue({ addAction: jest.fn() });
+ expect(JSON.parse(sessionStorage.getItem('lc-rum-queue') ?? '[]')).toHaveLength(1);
+ await jest.advanceTimersByTimeAsync(60_000);
+ forwardQueuedAssetEvents();
+ await jest.advanceTimersByTimeAsync(5_000);
+ expect(loggedEventNames()).toContain('stale_asset.recovery_start');
+ expect(sessionStorage.getItem('lc-rum-queue')).toBeNull();
+ });
+
+ it('keeps an auth-dropped asset event persisted and eligible after token renewal', async () => {
+ fetchMock.mockImplementationOnce(() => Promise.resolve({ status: 204 }));
+ startClientLogs({
+ endpoint: '/api/rum/v1/logs',
+ serviceName: 'librechat-web',
+ buildId: 'index-New2.js',
+ getToken: () => 'expired-jwt',
+ fetch: fetchMock,
+ });
+ forwardQueuedAssetEvents();
+ flushEarlyRumQueue({ addAction: jest.fn() });
+ await jest.advanceTimersByTimeAsync(5_000);
+ expect(window.__lcRumQueue?.[0]).not.toHaveProperty('logged');
+ expect(JSON.parse(sessionStorage.getItem('lc-rum-queue') ?? '[]')).toHaveLength(1);
+ stopClientLogs();
+ startClientLogs({
+ endpoint: '/api/rum/v1/logs',
+ serviceName: 'librechat-web',
+ buildId: 'index-New2.js',
+ getToken: () => 'renewed-jwt',
+ fetch: fetchMock,
+ });
+ forwardQueuedAssetEvents();
+ await jest.advanceTimersByTimeAsync(5_000);
+ expect(window.__lcRumQueue).toEqual([]);
+ expect(sessionStorage.getItem('lc-rum-queue')).toBeNull();
+ });
+
+ it('leaves events unmarked when client logs are off', () => {
+ forwardQueuedAssetEvents();
+
+ expect(window.__lcRumQueue?.[0]).not.toHaveProperty('logged');
+ expect(sessionStorage.getItem('lc-rum-queue')).toBeNull();
+ });
+});
diff --git a/client/src/lib/rum/diagnostics.ts b/client/src/lib/rum/diagnostics.ts
index a5dc8eed48..829b686746 100644
--- a/client/src/lib/rum/diagnostics.ts
+++ b/client/src/lib/rum/diagnostics.ts
@@ -1,4 +1,5 @@
import type { FCPMetricWithAttribution } from 'web-vitals/attribution';
+import { isClientEventType, isClientLogsActive, recordClientEvent } from './logs';
import { normalizeRumPath } from './routes';
import { getClientBuildId } from './build';
@@ -13,6 +14,10 @@ type RumQueuedEvent = {
at?: unknown;
visibilityState?: unknown;
attributes?: Record<string, unknown>;
+ /** Already delivered as a client log record; persisted so a later page does not resend it. */
+ logged?: unknown;
+ /** Already sent to the RUM SDK; kept queued only until its client log record is acknowledged. */
+ actionSent?: unknown;
};
type NavigationTimingLike = {
@@ -60,6 +65,8 @@ declare global {
}
}
+/** Queued events handed to the log exporter and not yet acknowledged by the collector. */
+const forwardingEvents = new WeakSet<RumQueuedEvent>();
let fcpAttributionRegistered = false;
let earlyQueueFlushed = false;
@@ -169,18 +176,33 @@ export function flushEarlyRumQueue(HyperDX: HyperDXActionClient): void {
earlyQueueFlushed = true;
const queuedEvents = window.__lcRumQueue?.splice(0) ?? [];
+ queuedEvents.forEach((event) => {
+ emitEarlyRumEvent(HyperDX, event);
+ });
+ const awaitingDelivery = queuedEvents.filter(shouldRetainEvent);
+ awaitingDelivery.forEach((event) => {
+ event.actionSent = true;
+ });
+ window.__lcRumQueue?.unshift(...awaitingDelivery);
try {
- sessionStorage.removeItem(EARLY_RUM_QUEUE_STORAGE_KEY);
+ persistEarlyQueue();
} catch {
HyperDX.addAction('early-rum-queue-storage-error', { operation: 'clear' });
}
- queuedEvents.forEach((event) => {
- emitEarlyRumEvent(HyperDX, event);
- });
installRumEmitter(HyperDX);
}
+/** Persists what is still queued, or clears the stored copy once nothing is left. */
+function persistEarlyQueue(): void {
+ const queue = window.__lcRumQueue ?? [];
+ if (queue.length === 0) {
+ sessionStorage.removeItem(EARLY_RUM_QUEUE_STORAGE_KEY);
+ return;
+ }
+ sessionStorage.setItem(EARLY_RUM_QUEUE_STORAGE_KEY, JSON.stringify(queue));
+}
+
export function restoreRumEmitter(HyperDX: HyperDXActionClient): void {
installRumEmitter(HyperDX);
}
@@ -188,12 +210,24 @@ export function restoreRumEmitter(HyperDX: HyperDXActionClient): void {
function installRumEmitter(HyperDX: HyperDXActionClient): void {
const clientBuildId = getClientBuildId();
window.__lcRumPush = (type, attributes) => {
- emitEarlyRumEvent(HyperDX, {
+ const event: RumQueuedEvent = {
type,
at: performance.now(),
visibilityState: document.visibilityState,
attributes: { ...attributes, clientBuildId },
- });
+ };
+ emitEarlyRumEvent(HyperDX, event);
+ if (shouldRetainEvent(event)) {
+ event.actionSent = true;
+ const queue = (window.__lcRumQueue ??= []);
+ queue.push(event);
+ queue.splice(0, Math.max(0, queue.length - 20));
+ try {
+ persistEarlyQueue();
+ } catch {
+ /* Diagnostics should never affect app behavior. */
+ }
+ }
};
}
@@ -212,7 +246,14 @@ function emitEarlyRumEvent(HyperDX: HyperDXActionClient, event: RumQueuedEvent):
return;
}
- const actionName = event.type === 'spa-route-change' ? event.type : `early-${event.type}`;
+ if (event.actionSent !== true) {
+ sendRumAction(HyperDX, event.type, event);
+ }
+ forwardEvent(event);
+}
+
+function sendRumAction(HyperDX: HyperDXActionClient, type: string, event: RumQueuedEvent): void {
+ const actionName = type === 'spa-route-change' ? type : `early-${type}`;
try {
HyperDX.addAction(
actionName,
@@ -228,6 +269,64 @@ function emitEarlyRumEvent(HyperDX: HyperDXActionClient, event: RumQueuedEvent):
}
}
+function markEventLogged(event: RumQueuedEvent): void {
+ forwardingEvents.delete(event);
+ event.logged = true;
+ const queue = window.__lcRumQueue;
+ const index = queue?.indexOf(event) ?? -1;
+ if (!queue || index === -1) {
+ return;
+ }
+ if (event.actionSent === true) {
+ queue.splice(index, 1);
+ }
+ try {
+ persistEarlyQueue();
+ } catch {
+ /* Diagnostics should never affect app behavior. */
+ }
+}
+
+function shouldRetainEvent(event: RumQueuedEvent): boolean {
+ return isClientLogsActive() && isClientEventType(event.type) && event.logged !== true;
+}
+
+/** Hands one queued asset event to the log exporter, tracking it until the collector acks it. */
+function forwardEvent(event: RumQueuedEvent): void {
+ if (
+ event.logged === true ||
+ forwardingEvents.has(event) ||
+ typeof event.type !== 'string' ||
+ !isClientEventType(event.type)
+ ) {
+ return;
+ }
+ forwardingEvents.add(event);
+ const accepted = recordClientEvent(
+ event.type,
+ sanitizeQueuedAttributes(event.attributes),
+ () => markEventLogged(event),
+ () => forwardingEvents.delete(event),
+ );
+ if (!accepted) {
+ forwardingEvents.delete(event);
+ }
+}
+
+/**
+ * Delivers queued stale-asset events as client log records as soon as the log exporter runs,
+ * independent of the RUM SDK loading. An event in flight is skipped by the SDK path; once the
+ * collector accepts it, it is marked in memory and in the persisted copy so no later page logs
+ * it again. An event that is never delivered stays unmarked and replays on the next load.
+ */
+export function forwardQueuedAssetEvents(): void {
+ const queue = window.__lcRumQueue;
+ if (!queue) {
+ return;
+ }
+ queue.forEach(forwardEvent);
+}
+
export function queueSpaRouteChange(
fromPath: string,
toPath: string,
diff --git a/client/src/lib/rum/logs.spec.ts b/client/src/lib/rum/logs.spec.ts
new file mode 100644
index 0000000000..9e39beb420
--- /dev/null
+++ b/client/src/lib/rum/logs.spec.ts
@@ -0,0 +1,582 @@
+import type { ClientLogsOptions } from './logs';
+import {
+ testExports,
+ stopClientLogs,
+ startClientLogs,
+ CLIENT_LOG_LIMITS,
+ recordClientEvent,
+ reportBoundaryError,
+ createClientLogExporter,
+} from './logs';
+import logger from '~/utils/logger';
+
+type KeyValue = {
+ key: string;
+ value: { stringValue?: string; intValue?: string; boolValue?: boolean };
+};
+type SentRecord = {
+ severityText: string;
+ body: { stringValue: string };
+ attributes: KeyValue[];
+ traceId?: string;
+ spanId?: string;
+};
+type SentPayload = {
+ resourceLogs: Array<{
+ resource: { attributes: KeyValue[] };
+ scopeLogs: Array<{ logRecords: SentRecord[] }>;
+ }>;
+};
+
+const fetchMock = jest.fn<Promise<{ status: number }>, [string, RequestInit]>();
+
+function respond(status: number) {
+ return Promise.resolve({ status });
+}
+
+function options(overrides: Partial<ClientLogsOptions> = {}): ClientLogsOptions {
+ return {
+ endpoint: '/api/rum/v1/logs',
+ serviceName: 'librechat-web',
+ environment: 'demo',
+ buildId: 'index-Ab12Cd.js',
+ getToken: () => 'session-jwt',
+ getSessionId: () => 'hdx-session-1',
+ fetch: fetchMock,
+ ...overrides,
+ };
+}
+
+function payloadAt(index: number): SentPayload {
+ const init = fetchMock.mock.calls[index]?.[1];
+ return JSON.parse(String(init?.body));
+}
+
+function recordsAt(index: number): SentRecord[] {
+ return payloadAt(index).resourceLogs[0].scopeLogs[0].logRecords;
+}
+
+function allRecords(): SentRecord[] {
+ return fetchMock.mock.calls.flatMap((_call, index) => recordsAt(index));
+}
+
+function attributesOf(entries: KeyValue[]): Record<string, string | boolean | undefined> {
+ return Object.fromEntries(
+ entries.map(({ key, value }) => [key, value.stringValue ?? value.intValue ?? value.boolValue]),
+ );
+}
+
+async function flushInterval() {
+ await jest.advanceTimersByTimeAsync(CLIENT_LOG_LIMITS.flushIntervalMs);
+}
+
+beforeEach(() => {
+ jest.useFakeTimers();
+ testExports.resetPageState();
+ fetchMock.mockReset();
+ fetchMock.mockImplementation(() => respond(200));
+});
+
+afterEach(() => {
+ stopClientLogs();
+ jest.useRealTimers();
+});
+
+describe('createClientLogExporter', () => {
+ it('batches records as OTLP/JSON to the proxy with session auth and resource attributes', async () => {
+ const exporter = createClientLogExporter(options());
+
+ exporter.log('error', [
+ 'conversation',
+ 'Error fetching conversation',
+ new TypeError("Cannot read properties of undefined (reading 'id')"),
+ ]);
+ exporter.log('warn', ['[useChatFunctions] Refusing to send']);
+ await flushInterval();
+
+ expect(fetchMock).toHaveBeenCalledTimes(1);
+ const [url, init] = fetchMock.mock.calls[0];
+ expect(url).toBe('/api/rum/v1/logs');
+ expect(init?.method).toBe('POST');
+ expect(init?.keepalive).toBe(false);
+ expect(init?.headers).toEqual({
+ 'content-type': 'application/json',
+ authorization: 'Bearer session-jwt',
+ });
+
+ const payload = payloadAt(0);
+ expect(attributesOf(payload.resourceLogs[0].resource.attributes)).toEqual(
+ expect.objectContaining({
+ 'service.name': 'librechat-web',
+ 'service.version': 'index-Ab12Cd.js',
+ 'deployment.environment': 'demo',
+ }),
+ );
+ const [first, second] = recordsAt(0);
+ expect(first.severityText).toBe('ERROR');
+ expect(first.body.stringValue).toBe('Error fetching conversation');
+ expect(attributesOf(first.attributes)).toEqual(
+ expect.objectContaining({
+ 'log.source': 'logger',
+ 'logger.name': 'conversation',
+ 'exception.type': 'TypeError',
+ 'exception.message': "Cannot read properties of undefined (reading 'id')",
+ 'session.id': 'hdx-session-1',
+ 'url.template': '/',
+ }),
+ );
+ expect(second.severityText).toBe('WARN');
+ exporter.dispose();
+ });
+
+ it('never sends non-error arguments and scrubs free text', async () => {
+ const exporter = createClientLogExporter(options());
+
+ exporter.log('warn', [
+ 'Saving failed for [email protected]',
+ { prompt: 'my secret prompt', headers: { authorization: 'Bearer abc' } },
+ 'second string with response text',
+ ]);
+ exporter.log('error', [
+ Object.assign(new TypeError('token=abcdef123456 rejected'), { config: { data: 'body' } }),
+ ]);
+ exporter.log('error', [new Error('Model rejected prompt: my medical history')]);
+ await flushInterval();
+
+ const body = String(fetchMock.mock.calls[0]?.[1]?.body);
+ expect(body).toContain('Saving failed for [email]');
+ expect(body).not.toMatch(
+ /jane@example\.com|my secret prompt|response text|abcdef123456|medical history/,
+ );
+ const [, , applicationError] = recordsAt(0);
+ expect(applicationError.body.stringValue).toBe('Error');
+ exporter.dispose();
+ });
+
+ it('collapses duplicates into one record with a repeat count, then summarizes later repeats', async () => {
+ const exporter = createClientLogExporter(options());
+ const failUpload = () => exporter.log('error', ['Upload failed', new Error('Network Error')]);
+
+ for (let i = 0; i < 5; i += 1) {
+ failUpload();
+ }
+ await flushInterval();
+
+ expect(recordsAt(0)).toHaveLength(1);
+ expect(attributesOf(recordsAt(0)[0].attributes)['log.repeat_count']).toBe('5');
+
+ for (let i = 0; i < 3; i += 1) {
+ failUpload();
+ }
+ await flushInterval();
+ expect(fetchMock).toHaveBeenCalledTimes(1);
+
+ await jest.advanceTimersByTimeAsync(CLIENT_LOG_LIMITS.dedupeWindowMs);
+ expect(fetchMock).toHaveBeenCalledTimes(2);
+ const summary = attributesOf(recordsAt(1)[0].attributes);
+ expect(summary['log.repeat_count']).toBe('3');
+ expect(summary['log.deduplicated']).toBe(true);
+ exporter.dispose();
+ });
+
+ it('caps distinct records per minute', async () => {
+ const exporter = createClientLogExporter(options());
+
+ for (let i = 0; i < 50; i += 1) {
+ exporter.log('error', [`Distinct failure ${i}`]);
+ }
+ await flushInterval();
+ await flushInterval();
+ await flushInterval();
+
+ expect(allRecords()).toHaveLength(CLIENT_LOG_LIMITS.recordsPerMinute);
+ exporter.dispose();
+ });
+
+ it('retries retryable failures with backoff and drops the batch after the attempt limit', async () => {
+ fetchMock.mockImplementation(() => respond(503));
+ const exporter = createClientLogExporter(options());
+
+ exporter.log('error', ['Transient failure']);
+ await flushInterval();
+ expect(fetchMock).toHaveBeenCalledTimes(1);
+
+ await jest.advanceTimersByTimeAsync(CLIENT_LOG_LIMITS.maxBackoffMs * 4);
+ expect(fetchMock).toHaveBeenCalledTimes(CLIENT_LOG_LIMITS.maxAttempts);
+
+ await jest.advanceTimersByTimeAsync(CLIENT_LOG_LIMITS.maxBackoffMs * 4);
+ expect(fetchMock).toHaveBeenCalledTimes(CLIENT_LOG_LIMITS.maxAttempts);
+ exporter.dispose();
+ });
+
+ it('stops exporting for the page after a fatal proxy status', async () => {
+ fetchMock.mockImplementation(() => respond(404));
+ const exporter = createClientLogExporter(options());
+
+ exporter.log('error', ['First']);
+ await flushInterval();
+ exporter.log('error', ['Second']);
+ await flushInterval();
+
+ expect(fetchMock).toHaveBeenCalledTimes(1);
+ exporter.dispose();
+ });
+
+ it('turns itself off after repeated network failures instead of retrying forever', async () => {
+ fetchMock.mockImplementation(() => Promise.reject(new TypeError('Failed to fetch')));
+ const exporter = createClientLogExporter(options());
+
+ for (let i = 0; i < 20; i += 1) {
+ exporter.log('error', [`Offline ${i}`]);
+ await jest.advanceTimersByTimeAsync(CLIENT_LOG_LIMITS.maxBackoffMs);
+ }
+
+ expect(fetchMock.mock.calls.length).toBeLessThanOrEqual(
+ CLIENT_LOG_LIMITS.maxConsecutiveFailures,
+ );
+ exporter.dispose();
+ });
+
+ it('reports admission failure when the budget is exhausted or export is disabled', async () => {
+ const exporter = createClientLogExporter(options());
+ for (let i = 0; i < CLIENT_LOG_LIMITS.recordsPerMinute; i += 1) {
+ exporter.log('error', [`Budget ${i}`]);
+ }
+ const dropped = jest.fn();
+ expect(exporter.event('stale-asset-recovery-start', {}, jest.fn(), dropped)).toBe(false);
+ expect(dropped).toHaveBeenCalledTimes(1);
+ exporter.dispose();
+ expect(exporter.event('stale-asset-recovery-reload')).toBe(false);
+ });
+
+ it.each(['queued', 'sending', 'suppressed'])(
+ 'settles %s deliveries on dispose and ignores late responses',
+ async (state) => {
+ let answer: (value: { status: number }) => void = () => undefined;
+ fetchMock.mockImplementation(
+ () =>
+ new Promise((resolve) => {
+ answer = resolve;
+ }),
+ );
+ const exporter = createClientLogExporter(options());
+ const delivered = jest.fn();
+ const dropped = jest.fn();
+ exporter.event('stale-asset-recovery-start', {}, delivered, dropped);
+ if (state !== 'queued') {
+ await flushInterval();
+ }
+ if (state === 'suppressed') {
+ exporter.event('stale-asset-recovery-start', {}, delivered, dropped);
+ }
+ exporter.dispose();
+ expect(dropped).toHaveBeenCalledTimes(state === 'suppressed' ? 2 : 1);
+ answer({ status: 200 });
+ await flushInterval();
+ expect(delivered).not.toHaveBeenCalled();
+ expect(dropped).toHaveBeenCalledTimes(state === 'suppressed' ? 2 : 1);
+ },
+ );
+
+ it('settles dropped deliveries when retries are exhausted', async () => {
+ fetchMock.mockImplementation(() => respond(503));
+ const exporter = createClientLogExporter(options());
+ const dropped = jest.fn();
+ exporter.event('stale-asset-recovery-start', {}, jest.fn(), dropped);
+ await jest.advanceTimersByTimeAsync(CLIENT_LOG_LIMITS.maxBackoffMs * 4);
+ expect(dropped).toHaveBeenCalledTimes(1);
+ exporter.dispose();
+ expect(dropped).toHaveBeenCalledTimes(1);
+ });
+
+ it('drops silent auth responses without acknowledging delivery, but accepts collector 204s', async () => {
+ fetchMock.mockImplementationOnce(() => respond(204));
+ const exporter = createClientLogExporter(options());
+ const delivered = jest.fn();
+ const dropped = jest.fn();
+ exporter.event('stale-asset-recovery-start', {}, delivered, dropped);
+ await flushInterval();
+ expect(delivered).not.toHaveBeenCalled();
+ expect(dropped).toHaveBeenCalledTimes(1);
+ exporter.dispose();
+ const accepted = createClientLogExporter({
+ ...options(),
+ fetch: () => Promise.resolve({ status: 204, headers: { get: () => 'true' } }),
+ });
+ accepted.event('stale-asset-recovery-reload', {}, delivered, dropped);
+ await flushInterval();
+ expect(delivered).toHaveBeenCalledTimes(1);
+ expect(dropped).toHaveBeenCalledTimes(1);
+ accepted.dispose();
+ });
+
+ it('attaches the active trace and span ids from the RUM SDK context', async () => {
+ const spanKey = Symbol.for('OpenTelemetry Context Key SPAN');
+ const apiKey = Symbol.for('opentelemetry.js.api.1');
+ const span = {
+ spanContext: () => ({ traceId: 'a'.repeat(32), spanId: 'b'.repeat(16) }),
+ };
+ Reflect.set(globalThis, apiKey, {
+ context: {
+ active: () => ({ getValue: (key: symbol) => (key === spanKey ? span : undefined) }),
+ },
+ });
+ const exporter = createClientLogExporter(options());
+
+ exporter.log('error', ['Traced failure']);
+ await flushInterval();
+
+ expect(recordsAt(0)[0]).toEqual(
+ expect.objectContaining({ traceId: 'a'.repeat(32), spanId: 'b'.repeat(16) }),
+ );
+ Reflect.deleteProperty(globalThis, apiKey);
+ exporter.dispose();
+ });
+});
+
+describe('client log lifecycle', () => {
+ it('sends nothing when exporting was never started or has been stopped', async () => {
+ logger.error('Not exported', new Error('boom'));
+ reportBoundaryError('route', new Error('boom'));
+ recordClientEvent('stale-asset-recovery-start');
+ await flushInterval();
+ expect(fetchMock).not.toHaveBeenCalled();
+
+ startClientLogs(options());
+ stopClientLogs();
+ logger.error('Still not exported');
+ await flushInterval();
+ expect(fetchMock).not.toHaveBeenCalled();
+ });
+
+ it('routes logger warn/error, boundary catches and stale-asset events once started', async () => {
+ startClientLogs(options());
+ const boundaryError = new TypeError('Failed to fetch dynamically imported module');
+
+ logger.warn('[Example] Something degraded');
+ logger.info('info is not exported');
+ reportBoundaryError('route', boundaryError, true);
+ reportBoundaryError('route', boundaryError, true);
+ recordClientEvent('stale-asset-recovery-declined', {
+ assetPath: '/assets/SubagentThreadPanel-x.js',
+ clientBuildId: 'index-Old1.js',
+ });
+ recordClientEvent('spa-route-change', { assetPath: '/c/new' });
+ await flushInterval();
+
+ const records = allRecords();
+ expect(records.map((record) => attributesOf(record.attributes)['log.source'])).toEqual([
+ 'logger',
+ 'boundary',
+ 'asset',
+ ]);
+ expect(attributesOf(records[1].attributes)).toEqual(
+ expect.objectContaining({ 'error.boundary': 'route', 'error.chunk_load': true }),
+ );
+ expect(records[1].severityText).toBe('WARN');
+ expect(attributesOf(records[2].attributes)).toEqual(
+ expect.objectContaining({
+ 'event.name': 'stale_asset.recovery_declined',
+ 'asset.path': '/assets/SubagentThreadPanel-x.js',
+ 'event.build_id': 'index-Old1.js',
+ }),
+ );
+ });
+
+ it('flushes with keepalive when the page is hidden', async () => {
+ startClientLogs(options());
+
+ logger.error('Pending at unload');
+ window.dispatchEvent(new Event('pagehide'));
+ await jest.advanceTimersByTimeAsync(0);
+
+ expect(fetchMock).toHaveBeenCalledTimes(1);
+ expect(fetchMock.mock.calls[0]?.[1]?.keepalive).toBe(true);
+ });
+
+ it('drains every queued record that fits the keepalive quota on page hide', async () => {
+ startClientLogs(options());
+
+ for (let i = 0; i < 25; i += 1) {
+ logger.error(`Queued before unload ${i}`);
+ }
+ window.dispatchEvent(new Event('pagehide'));
+ await jest.advanceTimersByTimeAsync(0);
+
+ expect(fetchMock).toHaveBeenCalledTimes(1);
+ expect(recordsAt(0)).toHaveLength(25);
+ });
+
+ it('measures batches in encoded bytes so multibyte text stays under the keepalive quota', async () => {
+ startClientLogs(options());
+
+ for (let i = 0; i < CLIENT_LOG_LIMITS.recordsPerMinute; i += 1) {
+ logger.error(`${'界'.repeat(60)}${i}`, `${i} ${'界'.repeat(500)}`, new Error('x'));
+ }
+ window.dispatchEvent(new Event('pagehide'));
+ await jest.advanceTimersByTimeAsync(0);
+ window.dispatchEvent(new Event('pagehide'));
+ await jest.advanceTimersByTimeAsync(0);
+
+ const sizes = fetchMock.mock.calls.map(
+ ([, init]) => new TextEncoder().encode(String(init.body)).length,
+ );
+ expect(sizes.length).toBeGreaterThan(1);
+ sizes.forEach((size) => expect(size).toBeLessThanOrEqual(CLIENT_LOG_LIMITS.maxPayloadBytes));
+ expect(allRecords()).toHaveLength(CLIENT_LOG_LIMITS.recordsPerMinute);
+ });
+
+ it('re-sends an unanswered in-flight batch with keepalive when the page is hidden', async () => {
+ let answer: (value: { status: number }) => void = () => undefined;
+ fetchMock.mockImplementationOnce(
+ () =>
+ new Promise((resolve) => {
+ answer = resolve;
+ }),
+ );
+ startClientLogs(options());
+
+ logger.error('In flight at unload');
+ await flushInterval();
+ expect(fetchMock).toHaveBeenCalledTimes(1);
+
+ window.dispatchEvent(new Event('pagehide'));
+ await jest.advanceTimersByTimeAsync(0);
+
+ expect(fetchMock).toHaveBeenCalledTimes(2);
+ expect(fetchMock.mock.calls[1]?.[1]?.keepalive).toBe(true);
+ expect(recordsAt(1).map((record) => record.body.stringValue)).toEqual(['In flight at unload']);
+
+ answer({ status: 503 });
+ await flushInterval();
+ await flushInterval();
+ expect(fetchMock).toHaveBeenCalledTimes(2);
+ });
+
+ it('hands the active batch to keepalive only once across visibilitychange and pagehide', async () => {
+ fetchMock.mockImplementation(() => new Promise(() => undefined));
+ startClientLogs(options());
+ logger.error('In flight during both unload signals');
+ await flushInterval();
+ const visibility = jest.spyOn(document, 'visibilityState', 'get').mockReturnValue('hidden');
+ document.dispatchEvent(new Event('visibilitychange'));
+ window.dispatchEvent(new Event('pagehide'));
+ await jest.advanceTimersByTimeAsync(0);
+ expect(fetchMock).toHaveBeenCalledTimes(2);
+ expect(fetchMock.mock.calls[1][1].keepalive).toBe(true);
+ visibility.mockRestore();
+ });
+
+ it.each(['fulfilled', 'rejected'])(
+ 'reserves keepalive bytes across restarts until the old request is %s',
+ async (outcome) => {
+ let resolve: (value: { status: number }) => void = () => undefined;
+ let reject: (error: Error) => void = () => undefined;
+ fetchMock.mockImplementationOnce(
+ () =>
+ new Promise((res, rej) => {
+ resolve = res;
+ reject = rej;
+ }),
+ );
+ startClientLogs(options());
+ const logLargeRecord = (i: number) =>
+ logger.error(
+ `Large record ${i}`,
+ `${i} ${'界'.repeat(500)}`,
+ Object.assign(new Error('x'), {
+ stack: [
+ 'Error: x',
+ ...Array.from(
+ { length: 12 },
+ (_, frame) => ` at frame${frame} (/assets/${'a'.repeat(170)}.js:1:2)`,
+ ),
+ ].join('\n'),
+ }),
+ );
+ for (let i = 0; i < 20; i += 1) {
+ logLargeRecord(i);
+ }
+ window.dispatchEvent(new Event('pagehide'));
+ await jest.advanceTimersByTimeAsync(0);
+ expect(recordsAt(0)).toHaveLength(20);
+ stopClientLogs();
+ startClientLogs(options());
+ for (let i = 20; i < 30; i += 1) {
+ logLargeRecord(i);
+ }
+ window.dispatchEvent(new Event('pagehide'));
+ const encodedBytes = () =>
+ fetchMock.mock.calls.reduce(
+ (bytes, [, init]) => bytes + new TextEncoder().encode(String(init.body)).length,
+ 0,
+ );
+ expect(encodedBytes()).toBeLessThanOrEqual(CLIENT_LOG_LIMITS.maxPayloadBytes);
+ await jest.advanceTimersByTimeAsync(0);
+ expect(allRecords().length).toBeLessThan(30);
+ if (outcome === 'fulfilled') {
+ resolve({ status: 200 });
+ } else {
+ reject(new Error('cancelled'));
+ }
+ await jest.advanceTimersByTimeAsync(0);
+ window.dispatchEvent(new Event('pagehide'));
+ await jest.advanceTimersByTimeAsync(0);
+ expect(allRecords()).toHaveLength(30);
+ expect(
+ fetchMock.mock.calls
+ .slice(1)
+ .reduce(
+ (bytes, [, init]) => bytes + new TextEncoder().encode(String(init.body)).length,
+ 0,
+ ),
+ ).toBeLessThanOrEqual(CLIENT_LOG_LIMITS.maxPayloadBytes);
+ },
+ );
+
+ it('preserves the minute and page record budgets across exporter restarts', async () => {
+ for (let pageWindow = 0; pageWindow < 10; pageWindow += 1) {
+ if (pageWindow > 0) {
+ await jest.advanceTimersByTimeAsync(60_000);
+ }
+ startClientLogs(options());
+ for (let i = 0; i < 30; i += 1) {
+ logger.error(`Budget window ${pageWindow} record ${i}`);
+ }
+ await flushInterval();
+ await flushInterval();
+ stopClientLogs();
+ startClientLogs(options());
+ logger.error(`Restart bypass ${pageWindow}`);
+ await flushInterval();
+ stopClientLogs();
+ }
+ expect(allRecords()).toHaveLength(CLIENT_LOG_LIMITS.recordsPerPage);
+ await jest.advanceTimersByTimeAsync(60_000);
+ startClientLogs(options());
+ logger.error('Page budget must remain exhausted');
+ await flushInterval();
+ expect(allRecords()).toHaveLength(CLIENT_LOG_LIMITS.recordsPerPage);
+ });
+
+ it('does not resume after a fatal page shutdown when the exporter is restarted', async () => {
+ fetchMock.mockImplementation(() => respond(404));
+ startClientLogs(options());
+ logger.error('Proxy has been revoked');
+ await flushInterval();
+ stopClientLogs();
+ startClientLogs(options());
+ logger.error('Restart must not bypass revocation');
+ await flushInterval();
+ expect(fetchMock).toHaveBeenCalledTimes(1);
+ });
+
+ it('refuses a cross-origin endpoint', async () => {
+ startClientLogs(options({ endpoint: 'https://collector.example.com/v1/logs' }));
+
+ logger.error('Should not leave');
+ await flushInterval();
+
+ expect(fetchMock).not.toHaveBeenCalled();
+ });
+});
diff --git a/client/src/lib/rum/logs.ts b/client/src/lib/rum/logs.ts
new file mode 100644
index 0000000000..a56d810816
--- /dev/null
+++ b/client/src/lib/rum/logs.ts
@@ -0,0 +1,860 @@
+import { RUM_COLLECTOR_ACK_HEADER } from 'librechat-data-provider';
+import type { TraceContext } from './trace';
+import {
+ truncate,
+ scrubField,
+ isErrorLike,
+ summarizeError,
+ MAX_NAME_LENGTH,
+ getClientPlatform,
+ MAX_MESSAGE_LENGTH,
+} from './redact';
+import { setRemoteLogSink } from '~/utils/logger';
+import { getActiveTraceContext } from './trace';
+import { normalizeRumPath } from './routes';
+
+export type ClientLogLevel = 'info' | 'warn' | 'error';
+type AttributeValue = string | number | boolean;
+type DeliveryCallback = (delivered: boolean) => void;
+
+/** The only attribute keys a client log record may carry; anything else is dropped. */
+const ATTRIBUTE_KEYS = [
+ 'log.source',
+ 'logger.name',
+ 'event.name',
+ 'exception.type',
+ 'exception.message',
+ 'exception.stacktrace',
+ 'http.response.status_code',
+ 'error.boundary',
+ 'error.chunk_load',
+ 'asset.path',
+ 'asset.tag',
+ 'asset.optional',
+ 'event.build_id',
+ 'url.template',
+ 'session.id',
+ 'log.repeat_count',
+ 'log.deduplicated',
+] as const;
+type AttributeKey = (typeof ATTRIBUTE_KEYS)[number];
+type LogAttributes = Partial<Record<AttributeKey, AttributeValue>>;
+
+export const CLIENT_LOG_LIMITS = {
+ flushIntervalMs: 5_000,
+ maxBatchRecords: 20,
+ maxQueuedRecords: 100,
+ /** Below the 64 KiB in-flight cap browsers enforce on `keepalive` requests. */
+ maxPayloadBytes: 60_000,
+ maxStringLength: 2_048,
+ recordsPerMinute: 30,
+ recordsPerPage: 300,
+ dedupeWindowMs: 60_000,
+ maxDedupeKeys: 200,
+ maxAttempts: 3,
+ baseBackoffMs: 5_000,
+ maxBackoffMs: 60_000,
+ maxConsecutiveFailures: 5,
+} as const;
+
+function createPageState() {
+ return {
+ windowStart: 0,
+ windowCount: 0,
+ pageCount: 0,
+ shutdown: false,
+ backoffUntil: 0,
+ consecutiveFailures: 0,
+ keepaliveBytes: 0,
+ };
+}
+
+/** Document budgets and fatal shutdown outlive authenticated-layout mounts and exporters. */
+const pageState = createPageState();
+
+export const testExports = {
+ resetPageState: () => Object.assign(pageState, createPageState()),
+};
+
+const SEVERITY: Record<ClientLogLevel, { number: number; text: string }> = {
+ info: { number: 9, text: 'INFO' },
+ warn: { number: 13, text: 'WARN' },
+ error: { number: 17, text: 'ERROR' },
+};
+
+const ASSET_EVENTS = new Map<string, { name: string; level: ClientLogLevel }>([
+ ['stale-asset-recovery-start', { name: 'stale_asset.recovery_start', level: 'info' }],
+ ['stale-asset-recovery-reload', { name: 'stale_asset.recovery_reload', level: 'info' }],
+ ['stale-asset-recovery-declined', { name: 'stale_asset.recovery_declined', level: 'warn' }],
+ ['asset-load-error', { name: 'asset.load_error', level: 'warn' }],
+ ['dynamic-import-error', { name: 'asset.dynamic_import_error', level: 'warn' }],
+]);
+
+const RECORDS_PLACEHOLDER = '__librechat_log_records__';
+const encoder = new TextEncoder();
+
+function byteLength(text: string): number {
+ return encoder.encode(text).length;
+}
+
+/** Statuses that drop the batch and stop exporting for this page (proxy off or not allowed). */
+const FATAL_STATUSES = new Set([401, 403, 404, 405]);
+
+type LogEntry = {
+ key: string;
+ level: ClientLogLevel;
+ body: string;
+ attributes: LogAttributes;
+ timeMs: number;
+ count: number;
+ attempts: number;
+ state: 'queued' | 'sending' | 'done';
+ /** The request currently carrying this record; responses to older requests ignore it. */
+ sendId: number;
+ trace?: TraceContext;
+ onSettled: DeliveryCallback[];
+};
+
+type Batch = { entries: LogEntry[]; body: string };
+
+type DedupeEntry = {
+ expiresAt: number;
+ entry: LogEntry;
+ suppressed: number;
+ suppressedCallbacks: DeliveryCallback[];
+};
+
+type OtlpAnyValue = { stringValue: string } | { boolValue: boolean } | { intValue: string };
+type OtlpKeyValue = { key: string; value: OtlpAnyValue };
+type LogTransport = (
+ url: string,
+ init: RequestInit,
+) => Promise<Pick<Response, 'status'> & { headers?: Pick<Headers, 'get'> }>;
+type OtlpLogRecord = {
+ timeUnixNano: string;
+ observedTimeUnixNano: string;
+ severityNumber: number;
+ severityText: string;
+ body: { stringValue: string };
+ attributes: OtlpKeyValue[];
+ traceId?: string;
+ spanId?: string;
+};
+
+/** Fields read from a queued diagnostic event; everything else on it is ignored. */
+type ClientEventAttributes = {
+ assetPath?: unknown;
+ tagName?: unknown;
+ optional?: unknown;
+ clientBuildId?: unknown;
+};
+
+export type ClientLogsOptions = {
+ /** Same-origin authenticated proxy path, e.g. `/api/rum/v1/logs`. */
+ endpoint: string;
+ serviceName: string;
+ environment?: string;
+ buildId: string;
+ getToken: () => string | undefined;
+ getSessionId?: () => string | undefined;
+ /** Defaults to `window.fetch`; only the response status is read. */
+ fetch?: LogTransport;
+};
+
+export type ClientLogExporter = {
+ log: (level: 'warn' | 'error', args: unknown[]) => void;
+ event: (
+ type: string,
+ attributes?: ClientEventAttributes,
+ onDelivered?: () => void,
+ onDropped?: () => void,
+ ) => boolean;
+ boundary: (boundary: string, error: unknown, chunkLoad: boolean) => void;
+ flush: (keepalive: boolean) => void;
+ dispose: () => void;
+};
+
+function randomSessionId(): string {
+ try {
+ return crypto.randomUUID().replace(/-/g, '');
+ } catch {
+ return `${Date.now().toString(16)}${Math.random().toString(16).slice(2)}`;
+ }
+}
+
+function toAnyValue(value: AttributeValue): OtlpAnyValue {
+ if (typeof value === 'boolean') {
+ return { boolValue: value };
+ }
+ if (typeof value === 'number' && Number.isInteger(value)) {
+ return { intValue: String(value) };
+ }
+ return { stringValue: truncate(String(value), CLIENT_LOG_LIMITS.maxStringLength) };
+}
+
+function toKeyValues(attributes: Record<string, AttributeValue | undefined>): OtlpKeyValue[] {
+ return Object.entries(attributes).flatMap(([key, value]) =>
+ value === undefined || value === '' ? [] : [{ key, value: toAnyValue(value) }],
+ );
+}
+
+function pickAttributes(attributes: LogAttributes): LogAttributes {
+ return ATTRIBUTE_KEYS.reduce<LogAttributes>((picked, key) => {
+ const value = attributes[key];
+ if (value !== undefined && value !== '') {
+ picked[key] = value;
+ }
+ return picked;
+ }, {});
+}
+
+function toOtlpRecord(entry: LogEntry): OtlpLogRecord {
+ const attributes = pickAttributes({
+ ...entry.attributes,
+ ...(entry.count > 1 ? { 'log.repeat_count': entry.count } : {}),
+ });
+ return {
+ timeUnixNano: `${entry.timeMs}000000`,
+ observedTimeUnixNano: `${entry.timeMs}000000`,
+ severityNumber: SEVERITY[entry.level].number,
+ severityText: SEVERITY[entry.level].text,
+ body: { stringValue: entry.body },
+ attributes: toKeyValues(attributes),
+ ...(entry.trace ? { traceId: entry.trace.traceId, spanId: entry.trace.spanId } : {}),
+ };
+}
+
+function isSameOriginPath(endpoint: string): boolean {
+ try {
+ return new URL(endpoint, window.location.origin).origin === window.location.origin;
+ } catch {
+ return false;
+ }
+}
+
+function currentRouteTemplate(): string {
+ try {
+ return normalizeRumPath(window.location.pathname);
+ } catch {
+ return '/';
+ }
+}
+
+function stringAttribute(value: unknown, maxLength: number): string | undefined {
+ return typeof value === 'string' && value !== '' ? scrubField(value, maxLength) : undefined;
+}
+
+function errorAttributes(error: unknown): LogAttributes {
+ const summary = summarizeError(error);
+ if (!summary) {
+ return {};
+ }
+ return {
+ 'exception.type': summary.type,
+ 'exception.message': summary.message,
+ 'exception.stacktrace': summary.stacktrace,
+ 'http.response.status_code': summary.statusCode,
+ };
+}
+
+/**
+ * Batches client log records and ships them as OTLP/JSON to the authenticated RUM proxy.
+ * Records are allowlisted and scrubbed at creation, duplicates within a window collapse into a
+ * count, a per-minute and per-page budget caps volume, failed sends back off and are dropped
+ * after a few attempts, and repeated failures turn the exporter off for the rest of the page.
+ */
+export function createClientLogExporter(options: ClientLogsOptions): ClientLogExporter {
+ const limits = CLIENT_LOG_LIMITS;
+ const send = options.fetch ?? window.fetch.bind(window);
+ const fallbackSessionId = randomSessionId();
+ const platform = getClientPlatform(navigator.userAgent);
+ const resource = {
+ resource: {
+ attributes: toKeyValues({
+ 'service.name': options.serviceName,
+ 'service.version': options.buildId,
+ 'deployment.environment': options.environment,
+ 'browser.name': platform.browser,
+ 'os.type': platform.os,
+ 'telemetry.sdk.name': 'librechat-client-logs',
+ 'telemetry.sdk.language': 'webjs',
+ }),
+ },
+ };
+
+ const [envelopeHead, envelopeTail] = JSON.stringify({
+ resourceLogs: [
+ {
+ ...resource,
+ scopeLogs: [
+ {
+ scope: { name: 'librechat.client', version: '1' },
+ logRecords: [RECORDS_PLACEHOLDER],
+ },
+ ],
+ },
+ ],
+ }).split(JSON.stringify(RECORDS_PLACEHOLDER));
+ const envelopeBytes = byteLength(envelopeHead) + byteLength(envelopeTail);
+
+ let queue: LogEntry[] = [];
+ const pendingDeliveries = new Set<DeliveryCallback>();
+ const dedupe = new Map<string, DedupeEntry>();
+ let timer: ReturnType<typeof setTimeout> | undefined;
+ let timerAt = Number.POSITIVE_INFINITY;
+ let inFlight = false;
+ /** Records of the regular request in flight, re-sent by the page-hide flush if unanswered. */
+ let activeBatch: LogEntry[] = [];
+ let sendSeq = 0;
+ let disabled = pageState.shutdown;
+
+ const sessionId = (): string => {
+ try {
+ return options.getSessionId?.() || fallbackSessionId;
+ } catch {
+ return fallbackSessionId;
+ }
+ };
+
+ const consumeBudget = (now: number): boolean => {
+ if (pageState.pageCount >= limits.recordsPerPage) {
+ return false;
+ }
+ if (now - pageState.windowStart >= 60_000) {
+ pageState.windowStart = now;
+ pageState.windowCount = 0;
+ }
+ if (pageState.windowCount >= limits.recordsPerMinute) {
+ return false;
+ }
+ pageState.windowCount += 1;
+ pageState.pageCount += 1;
+ return true;
+ };
+
+ const clearTimer = () => {
+ if (timer !== undefined) {
+ clearTimeout(timer);
+ }
+ timer = undefined;
+ timerAt = Number.POSITIVE_INFINITY;
+ };
+
+ const schedule = (at: number) => {
+ if (disabled || pageState.shutdown || (timer !== undefined && timerAt <= at)) {
+ return;
+ }
+ clearTimer();
+ timerAt = at;
+ timer = setTimeout(tick, Math.max(0, at - Date.now()));
+ };
+
+ const settle = (entry: LogEntry, delivered: boolean) => {
+ entry.state = 'done';
+ entry.sendId = 0;
+ entry.onSettled.splice(0).forEach((callback) => callback(delivered));
+ };
+
+ const enqueue = (entry: LogEntry, now: number) => {
+ queue.push(entry);
+ while (queue.length > limits.maxQueuedRecords) {
+ const dropped = queue.shift();
+ if (dropped) {
+ settle(dropped, false);
+ }
+ }
+ schedule(queue.length >= limits.maxBatchRecords ? now : now + limits.flushIntervalMs);
+ };
+
+ const collectExpiredDuplicates = (now: number) => {
+ for (const [key, item] of dedupe) {
+ if (item.expiresAt > now) {
+ continue;
+ }
+ dedupe.delete(key);
+ if (item.suppressed > 0 && consumeBudget(now)) {
+ enqueue(
+ {
+ ...item.entry,
+ attributes: { ...item.entry.attributes, 'log.deduplicated': true },
+ timeMs: now,
+ count: item.suppressed,
+ attempts: 0,
+ state: 'queued',
+ sendId: 0,
+ onSettled: item.suppressedCallbacks,
+ },
+ now,
+ );
+ } else {
+ item.suppressedCallbacks.forEach((callback) => callback(false));
+ }
+ }
+ };
+
+ const nextDedupeExpiry = (): number => {
+ let next = Number.POSITIVE_INFINITY;
+ for (const item of dedupe.values()) {
+ if (item.suppressed > 0 && item.expiresAt < next) {
+ next = item.expiresAt;
+ }
+ }
+ return next;
+ };
+
+ const add = (entry: LogEntry): boolean => {
+ if (disabled || pageState.shutdown) {
+ settle(entry, false);
+ return false;
+ }
+ const now = entry.timeMs;
+ collectExpiredDuplicates(now);
+ const existing = dedupe.get(entry.key);
+ if (existing) {
+ if (existing.entry.state === 'queued') {
+ existing.entry.count += 1;
+ existing.entry.onSettled.push(...entry.onSettled);
+ } else {
+ existing.suppressed += 1;
+ existing.suppressedCallbacks.push(...entry.onSettled);
+ schedule(existing.expiresAt);
+ }
+ return true;
+ }
+ if (!consumeBudget(now)) {
+ settle(entry, false);
+ return false;
+ }
+ if (dedupe.size >= limits.maxDedupeKeys) {
+ const oldest = dedupe.keys().next().value;
+ if (oldest !== undefined) {
+ dedupe.get(oldest)?.suppressedCallbacks.forEach((callback) => callback(false));
+ dedupe.delete(oldest);
+ }
+ }
+ dedupe.set(entry.key, {
+ expiresAt: now + limits.dedupeWindowMs,
+ entry,
+ suppressed: 0,
+ suppressedCallbacks: [],
+ });
+ enqueue(entry, now);
+ return true;
+ };
+
+ /**
+ * Takes the queued records that fit one request, measured in encoded UTF-8 bytes of the exact
+ * body that will be sent, so a `keepalive` request never exceeds the browser's quota.
+ */
+ const takeBatch = (maxRecords: number, maxBytes: number = limits.maxPayloadBytes): Batch => {
+ const entries: LogEntry[] = [];
+ const records: string[] = [];
+ let bytes = envelopeBytes;
+ let taken = 0;
+ for (const entry of queue) {
+ if (entries.length >= maxRecords) {
+ break;
+ }
+ const record = JSON.stringify(toOtlpRecord(entry));
+ const size = byteLength(record) + (records.length > 0 ? 1 : 0);
+ if (bytes + size > maxBytes) {
+ if (entries.length > 0 || envelopeBytes + size <= limits.maxPayloadBytes) {
+ break;
+ }
+ settle(entry, false);
+ taken += 1;
+ continue;
+ }
+ bytes += size;
+ taken += 1;
+ entry.state = 'sending';
+ entries.push(entry);
+ records.push(record);
+ }
+ queue = queue.slice(taken);
+ return { entries, body: `${envelopeHead}${records.join(',')}${envelopeTail}` };
+ };
+
+ const discard = () => {
+ disabled = true;
+ pendingDeliveries.forEach((callback) => callback(false));
+ activeBatch.forEach((entry) => settle(entry, false));
+ activeBatch = [];
+ queue = [];
+ dedupe.clear();
+ clearTimer();
+ };
+
+ const onFailure = (batch: LogEntry[], retryable: boolean) => {
+ pageState.consecutiveFailures += 1;
+ if (pageState.consecutiveFailures >= limits.maxConsecutiveFailures) {
+ pageState.shutdown = true;
+ discard();
+ return;
+ }
+ const retry = batch.filter((entry) => {
+ entry.attempts += 1;
+ if (!retryable || entry.attempts >= limits.maxAttempts) {
+ settle(entry, false);
+ return false;
+ }
+ entry.state = 'queued';
+ return true;
+ });
+ queue = [...retry, ...queue];
+ queue.splice(limits.maxQueuedRecords).forEach((entry) => settle(entry, false));
+ const delay = Math.min(
+ limits.baseBackoffMs * 2 ** (pageState.consecutiveFailures - 1),
+ limits.maxBackoffMs,
+ );
+ pageState.backoffUntil = Date.now() + delay;
+ };
+
+ const handleStatus = (batch: LogEntry[], status: number) => {
+ if (status >= 200 && status < 300) {
+ pageState.consecutiveFailures = 0;
+ batch.forEach((entry) => settle(entry, true));
+ return;
+ }
+ if (FATAL_STATUSES.has(status)) {
+ pageState.shutdown = true;
+ discard();
+ return;
+ }
+ onFailure(batch, status === 408 || status === 429 || status >= 500);
+ };
+
+ const transmit = async ({ entries, body }: Batch, keepalive: boolean): Promise<void> => {
+ const token = options.getToken();
+ if (!token || entries.length === 0) {
+ entries.forEach((entry) => {
+ settle(entry, false);
+ });
+ return Promise.resolve();
+ }
+ sendSeq += 1;
+ const sendId = sendSeq;
+ entries.forEach((entry) => {
+ entry.sendId = sendId;
+ });
+ /** A record re-sent by a later request (the page-hide flush) belongs to that request. */
+ const owned = () =>
+ entries.filter((entry) => !disabled && !pageState.shutdown && entry.sendId === sendId);
+ const handleResponse = (status?: number) => {
+ const batch = owned();
+ if (batch.length === 0) {
+ return;
+ }
+ if (status === undefined) {
+ onFailure(batch, true);
+ } else {
+ handleStatus(batch, status);
+ }
+ };
+ const requestBytes = keepalive ? byteLength(body) : 0;
+ pageState.keepaliveBytes += requestBytes;
+ try {
+ const response = await send(options.endpoint, {
+ method: 'POST',
+ headers: { 'content-type': 'application/json', authorization: `Bearer ${token}` },
+ body,
+ keepalive,
+ credentials: 'same-origin',
+ });
+ if (response.status === 204 && response.headers?.get(RUM_COLLECTOR_ACK_HEADER) !== 'true') {
+ owned().forEach((entry) => settle(entry, false));
+ } else {
+ handleResponse(response.status);
+ }
+ } catch {
+ handleResponse();
+ } finally {
+ pageState.keepaliveBytes -= requestBytes;
+ if (keepalive && queue.length > 0) {
+ schedule(Math.max(Date.now() + limits.flushIntervalMs, pageState.backoffUntil));
+ }
+ }
+ };
+
+ const flush = (keepalive: boolean) => {
+ if (disabled || pageState.shutdown) {
+ return;
+ }
+ const now = Date.now();
+ collectExpiredDuplicates(now);
+ if (keepalive) {
+ const unacknowledged = activeBatch.filter((entry) => entry.state === 'sending');
+ activeBatch = [];
+ inFlight = false;
+ unacknowledged.forEach((entry) => {
+ entry.state = 'queued';
+ entry.sendId = 0;
+ });
+ queue = [...unacknowledged, ...queue];
+ void transmit(
+ takeBatch(Number.POSITIVE_INFINITY, limits.maxPayloadBytes - pageState.keepaliveBytes),
+ true,
+ ).catch(() => undefined);
+ return;
+ }
+ if (inFlight || queue.length === 0) {
+ return;
+ }
+ if (pageState.backoffUntil > now) {
+ schedule(pageState.backoffUntil);
+ return;
+ }
+ inFlight = true;
+ const batch = takeBatch(limits.maxBatchRecords);
+ activeBatch = batch.entries;
+ transmit(batch, false)
+ .catch(() => undefined)
+ .finally(() => {
+ if (activeBatch !== batch.entries) {
+ return;
+ }
+ inFlight = false;
+ activeBatch = [];
+ if (queue.length > 0) {
+ schedule(Math.max(Date.now() + limits.flushIntervalMs, pageState.backoffUntil));
+ }
+ });
+ };
+
+ function tick() {
+ timer = undefined;
+ timerAt = Number.POSITIVE_INFINITY;
+ flush(false);
+ const next = nextDedupeExpiry();
+ if (next !== Number.POSITIVE_INFINITY) {
+ schedule(next);
+ }
+ }
+
+ const baseAttributes = (source: string): LogAttributes => ({
+ 'log.source': source,
+ 'url.template': currentRouteTemplate(),
+ 'session.id': sessionId(),
+ });
+
+ const createEntry = (
+ level: ClientLogLevel,
+ body: string,
+ attributes: LogAttributes,
+ ): LogEntry => {
+ const firstFrame = String(attributes['exception.stacktrace'] ?? '').split('\n', 1)[0];
+ return {
+ key: [
+ level,
+ attributes['log.source'],
+ attributes['logger.name'],
+ attributes['event.name'],
+ attributes['error.boundary'],
+ body,
+ attributes['exception.type'],
+ attributes['exception.message'],
+ firstFrame,
+ ].join('|'),
+ level,
+ body,
+ attributes: pickAttributes(attributes),
+ timeMs: Date.now(),
+ count: 1,
+ attempts: 0,
+ state: 'queued',
+ sendId: 0,
+ trace: getActiveTraceContext(),
+ onSettled: [],
+ };
+ };
+
+ const log = (level: 'warn' | 'error', args: unknown[]) => {
+ const [first, second] = args;
+ const name = typeof first === 'string' && typeof second === 'string' ? first : undefined;
+ const message = name != null ? second : first;
+ const error = args.find(isErrorLike);
+ const attributes: LogAttributes = {
+ ...baseAttributes('logger'),
+ 'logger.name': stringAttribute(name, MAX_NAME_LENGTH),
+ ...errorAttributes(error),
+ };
+ const body =
+ stringAttribute(message, MAX_MESSAGE_LENGTH) ??
+ attributes['exception.message'] ??
+ attributes['exception.type'] ??
+ 'Client log';
+ add(createEntry(level, String(body), attributes));
+ };
+
+ const event = (
+ type: string,
+ attributes: ClientEventAttributes = {},
+ onDelivered?: () => void,
+ onDropped?: () => void,
+ ): boolean => {
+ const definition = ASSET_EVENTS.get(type);
+ if (!definition) {
+ return false;
+ }
+ const entry = createEntry(definition.level, definition.name, {
+ ...baseAttributes('asset'),
+ 'event.name': definition.name,
+ 'asset.path': stringAttribute(attributes.assetPath, MAX_MESSAGE_LENGTH),
+ 'asset.tag': stringAttribute(attributes.tagName, MAX_NAME_LENGTH),
+ 'asset.optional': typeof attributes.optional === 'boolean' ? attributes.optional : undefined,
+ 'event.build_id': stringAttribute(attributes.clientBuildId, MAX_NAME_LENGTH),
+ });
+ if (onDelivered || onDropped) {
+ const callback: DeliveryCallback = (delivered) => {
+ if (!pendingDeliveries.delete(callback)) {
+ return;
+ }
+ try {
+ (delivered ? onDelivered : onDropped)?.();
+ } catch {
+ /* Telemetry must never affect the caller. */
+ }
+ };
+ pendingDeliveries.add(callback);
+ entry.onSettled.push(callback);
+ }
+ return add(entry);
+ };
+
+ const boundary = (name: string, error: unknown, chunkLoad: boolean) => {
+ const attributes: LogAttributes = {
+ ...baseAttributes('boundary'),
+ 'error.boundary': scrubField(name, MAX_NAME_LENGTH),
+ 'error.chunk_load': chunkLoad,
+ ...errorAttributes(error),
+ };
+ const body = attributes['exception.message'] ?? attributes['exception.type'] ?? 'Unknown error';
+ add(createEntry(chunkLoad ? 'warn' : 'error', String(body), attributes));
+ };
+
+ const dispose = () => {
+ discard();
+ };
+
+ return { log, event, boundary, flush, dispose };
+}
+
+let exporter: ClientLogExporter | undefined;
+let exporterKey: string | undefined;
+const startedListeners = new Set<() => void>();
+const reportedErrors = new WeakSet<object>();
+
+function onVisibilityChange() {
+ if (document.visibilityState === 'hidden') {
+ exporter?.flush(true);
+ }
+}
+
+function onPageHide() {
+ exporter?.flush(true);
+}
+
+function forwardLog(level: 'warn' | 'error', args: unknown[]) {
+ try {
+ exporter?.log(level, args);
+ } catch {
+ /* Telemetry must never affect the caller. */
+ }
+}
+
+/** Starts exporting client logs for this page; a repeat call with the same settings is a no-op. */
+export function startClientLogs(options: ClientLogsOptions): void {
+ const key = [options.endpoint, options.serviceName, options.environment, options.buildId].join(
+ '|',
+ );
+ if (exporter && exporterKey === key) {
+ return;
+ }
+ stopClientLogs();
+ if (!isSameOriginPath(options.endpoint)) {
+ return;
+ }
+ try {
+ exporter = createClientLogExporter(options);
+ } catch {
+ return;
+ }
+ exporterKey = key;
+ setRemoteLogSink(forwardLog);
+ document.addEventListener('visibilitychange', onVisibilityChange);
+ window.addEventListener('pagehide', onPageHide);
+ startedListeners.forEach((callback) => {
+ try {
+ callback();
+ } catch {
+ /* Reporting must never affect startup. */
+ }
+ });
+}
+
+/** Stops exporting and drops anything still queued (e.g. on sign-out or when RUM is disabled). */
+export function stopClientLogs(): void {
+ if (!exporter) {
+ return;
+ }
+ exporter.dispose();
+ exporter = undefined;
+ exporterKey = undefined;
+ setRemoteLogSink(undefined);
+ document.removeEventListener('visibilitychange', onVisibilityChange);
+ window.removeEventListener('pagehide', onPageHide);
+}
+
+/** Mounted boundaries can report after startup config and authentication enable the sink. */
+export function onClientLogsStarted(callback: () => void): () => void {
+ startedListeners.add(callback);
+ return () => {
+ startedListeners.delete(callback);
+ };
+}
+
+export function isClientLogsActive(): boolean {
+ return exporter !== undefined;
+}
+
+export function isClientEventType(type: unknown): boolean {
+ return typeof type === 'string' && ASSET_EVENTS.has(type);
+}
+
+/**
+ * Forwards an allowlisted stale-asset diagnostic event. Returns `true` when an active exporter
+ * took it; `onDelivered` runs only after the collector accepted the record that carries it.
+ */
+export function recordClientEvent(
+ type: string,
+ attributes?: ClientEventAttributes,
+ onDelivered?: () => void,
+ onDropped?: () => void,
+): boolean {
+ if (!exporter || !isClientEventType(type)) {
+ return false;
+ }
+ try {
+ return exporter.event(type, attributes, onDelivered, onDropped);
+ } catch {
+ return false;
+ }
+}
+
+/** Reports an error caught by an error boundary, once per error object. */
+export function reportBoundaryError(boundary: string, error: unknown, chunkLoad = false): void {
+ if (!exporter) {
+ return;
+ }
+ if (typeof error === 'object' && error !== null) {
+ if (reportedErrors.has(error)) {
+ return;
+ }
+ reportedErrors.add(error);
+ }
+ try {
+ exporter.boundary(boundary, error, chunkLoad);
+ } catch {
+ /* Telemetry must never affect the caller. */
+ }
+}
diff --git a/client/src/lib/rum/redact.spec.ts b/client/src/lib/rum/redact.spec.ts
new file mode 100644
index 0000000000..47b6efdcdc
--- /dev/null
+++ b/client/src/lib/rum/redact.spec.ts
@@ -0,0 +1,185 @@
+import { getClientPlatform, reduceStack, scrubText, summarizeError } from './redact';
+
+describe('scrubText', () => {
+ it.each([
+ ['user [email protected] failed', 'user [email] failed'],
+ ['Authorization: Bearer abcDEF123456.token', 'Authorization: [redacted]'],
+ ['sent Bearer abcdef0123456789xyz', 'sent Bearer [redacted]'],
+ [
+ 'jwt eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxMjM0NTY3ODkwIn0.dozjgNryP4J3jVmNHl0w5N_XgL0n3I9PlFUP0THsR8U',
+ 'jwt [jwt]',
+ ],
+ ['key sk-proj-abcdefghijklmnop1234 rejected', 'key [key] rejected'],
+ ['aws AKIAIOSFODNN7EXAMPLE', 'aws [key]'],
+ ['api_key=supersecretvalue&next=1', 'api_key=[redacted]&next=1'],
+ ['password: "hunter2 hunter2"', 'password: [redacted]'],
+ ['{"password":"hunter2"}', '{password:[redacted]}'],
+ ["{'token':'hunter2'}", '{token:[redacted]}'],
+ ['{"access_token": "secret value"}', '{access_token: [redacted]}'],
+ ['convo 65f1c2a9b8e4d3f2a1b0c9d8 missing', 'convo [hex] missing'],
+ ['file 123e4567-e89b-12d3-a456-426614174000 gone', 'file :id gone'],
+ ['secret Zm9vYmFyYmF6cXV4MTIzNDU2Nzg5MGFiY2RlZmdo end', 'secret [redacted] end'],
+ [
+ 'GET https://chat.example.com/c/abc123?token=xyz#frag failed',
+ 'GET /c/:conversationId failed',
+ ],
+ ['GET /api/files/download?id=42&sig=abc failed', 'GET /api/files/download failed'],
+ [
+ 'Unexpected token, "my private prompt text" is not valid JSON',
+ 'Unexpected token, "[redacted]" is not valid JSON',
+ ],
+ ])('scrubs %p', (input, expected) => {
+ expect(scrubText(input)).toBe(expected);
+ });
+
+ it('keeps ordinary diagnostic text and identifiers intact', () => {
+ const text = "Cannot read properties of undefined (reading 'default') in SubagentThreadPanel";
+ expect(scrubText(text)).toBe(text);
+ });
+});
+
+describe('reduceStack', () => {
+ it('drops the message line, reduces URLs to paths and caps frame count', () => {
+ const stack = [
+ 'TypeError: leaked [email protected] content',
+ ' at Panel (https://chat.example.com/assets/index-Ab12Cd.js:10:20)',
+ ' at https://chat.example.com/c/65f1c2a9b8e4d3f2a1b0c9d8?x=1:3:4',
+ 'render@https://chat.example.com/assets/vendor-Xy.js:5:6',
+ ...Array.from({ length: 20 }, (_, i) => ` at frame${i} (/assets/a.js:${i}:1)`),
+ ].join('\n');
+
+ const frames = reduceStack(stack)?.split('\n') ?? [];
+
+ expect(frames[0]).toBe('at Panel (/assets/index-Ab12Cd.js:10:20)');
+ expect(frames[1]).toBe('at /c/:conversationId');
+ expect(frames[2]).toBe('render@/assets/vendor-Xy.js:5:6');
+ expect(frames).toHaveLength(12);
+ expect(frames.join('\n')).not.toContain('example.com');
+ expect(frames.join('\n')).not.toContain('user@');
+ });
+});
+
+describe('summarizeError', () => {
+ it.each([
+ ['my medical history:123'],
+ ['first line\nat home with my medical history:12'],
+ ['history@/notes/medical:4:2'],
+ ])('never exports message text through the stack (%p)', (message) => {
+ const error = new Error(message);
+ error.stack = [
+ `Error: ${message}`,
+ ' at Panel (https://chat.example.com/assets/index-Ab12Cd.js:10:20)',
+ ].join('\n');
+
+ const stacktrace = summarizeError(error)?.stacktrace ?? '';
+
+ expect(stacktrace).toBe('at Panel (/assets/index-Ab12Cd.js:10:20)');
+ expect(stacktrace).not.toMatch(/medical|home/);
+ });
+
+ it('keeps V8, Gecko and WebKit frames but not header-like lines', () => {
+ const stack = [
+ 'my medical history:123',
+ 'at home with my medical history:12',
+ 'render@https://chat.example.com/assets/vendor-Xy.js:5:6',
+ 'global code@https://chat.example.com/assets/index-Ab.js:1:2',
+ ' at async Promise.all (index 0)',
+ ' at new Thing (/assets/a.js:3:4)',
+ ' at <anonymous>',
+ ].join('\n');
+
+ expect(reduceStack(stack)?.split('\n')).toEqual([
+ 'render@/assets/vendor-Xy.js:5:6',
+ 'global code@/assets/index-Ab.js:1:2',
+ 'at new Thing (/assets/a.js:3:4)',
+ 'at <anonymous>',
+ ]);
+ });
+
+ it('reads only name, generated message, stack and status from errors', () => {
+ const error = Object.assign(new Error('Request failed with status code 503'), {
+ name: 'AxiosError',
+ response: { status: 503, data: { prompt: 'secret prompt' } },
+ config: { headers: { Authorization: 'Bearer abcdefghijklmnop' } },
+ });
+
+ const summary = summarizeError(error);
+
+ expect(summary).toEqual({
+ type: 'AxiosError',
+ message: 'Request failed with status code 503',
+ stacktrace: expect.any(String),
+ statusCode: 503,
+ });
+ expect(JSON.stringify(summary)).not.toMatch(/secret prompt|abcdefghijklmnop/);
+ });
+
+ it('classifies arbitrary error names rather than exporting user-derived text', () => {
+ const error = new Error('Model rejected prompt');
+ error.name = 'my medical history';
+ expect(summarizeError(error)?.type).toBe('Error');
+ expect(JSON.stringify(summarizeError(error))).not.toContain('medical history');
+ });
+
+ it('drops application error messages, which can echo prompt or response content', () => {
+ const summary = summarizeError(new Error('Model rejected prompt: my medical history'));
+
+ expect(summary?.type).toBe('Error');
+ expect(summary?.message).toBeUndefined();
+ expect(JSON.stringify(summary)).not.toContain('medical history');
+ });
+
+ it.each([
+ [new TypeError("Cannot read properties of undefined (reading 'default')"), true],
+ [new TypeError('e.map is not a function'), true],
+ [new TypeError("undefined is not an object (evaluating 'n.default')"), true],
+ [new TypeError('Failed to fetch dynamically imported module: /assets/Panel-x.js'), true],
+ [new Error('Unable to preload CSS for /assets/panel.css'), true],
+ [new DOMException('The operation was aborted.', 'AbortError'), true],
+ [new TypeError('Failed to fetch'), true],
+ [new SyntaxError(`Unexpected token 'h', "hello there" is not valid JSON`), false],
+ [new TypeError('my medical history is not a function'), false],
+ [new TypeError('Model rejected prompt: hello there'), false],
+ [Object.assign(new Error('Prompt too long'), { name: 'ProviderError' }), false],
+ ])('keeps only known generated message shapes (%p)', (error, kept) => {
+ const message = summarizeError(error)?.message;
+ expect(message !== undefined).toBe(kept);
+ expect(message ?? '').not.toContain('hello there');
+ });
+
+ it('truncates long messages', () => {
+ const summary = summarizeError(
+ new TypeError(`Failed to fetch dynamically imported module: /assets/${'x'.repeat(800)}.js`),
+ );
+ expect(summary?.message).toBeDefined();
+ expect(summary?.message?.length).toBeLessThanOrEqual(512);
+ });
+
+ it('ignores non-error values', () => {
+ expect(summarizeError({ text: 'message body' })).toBeUndefined();
+ expect(summarizeError('plain string')).toBeUndefined();
+ });
+});
+
+describe('getClientPlatform', () => {
+ it.each([
+ [
+ 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/128.0 Safari/537.36 Edg/128.0',
+ { browser: 'Edge', os: 'Windows' },
+ ],
+ [
+ 'Mozilla/5.0 (Macintosh; Intel Mac OS X 14_5) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.5 Safari/605.1.15',
+ { browser: 'Safari', os: 'macOS' },
+ ],
+ [
+ 'Mozilla/5.0 (iPhone; CPU iPhone OS 17_5 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) CriOS/128.0 Mobile/15E148 Safari/604.1',
+ { browser: 'Chrome', os: 'iOS' },
+ ],
+ [
+ 'Mozilla/5.0 (X11; Linux x86_64; rv:130.0) Gecko/20100101 Firefox/130.0',
+ { browser: 'Firefox', os: 'Linux' },
+ ],
+ ])('maps %p to coarse families', (userAgent, expected) => {
+ expect(getClientPlatform(userAgent)).toEqual(expected);
+ });
+});
diff --git a/client/src/lib/rum/redact.ts b/client/src/lib/rum/redact.ts
new file mode 100644
index 0000000000..fec3b5a7b1
--- /dev/null
+++ b/client/src/lib/rum/redact.ts
@@ -0,0 +1,247 @@
+import { normalizeRumPath } from './routes';
+
+export const MAX_MESSAGE_LENGTH = 512;
+export const MAX_NAME_LENGTH = 64;
+const MAX_FRAME_LENGTH = 200;
+const MAX_FRAMES = 12;
+
+const URL_PATTERN =
+ /\b(?:https?|wss?|chrome-extension|moz-extension|safari-web-extension):\/\/[^\s"'<>()]+/gi;
+const QUERY_PATTERN = /\?[\w.~%-]+=[^\s"'<>()]*/g;
+const JWT_PATTERN = /\beyJ[\w-]{4,}\.[\w-]{4,}\.[\w-]*/g;
+const AUTH_SCHEME_PATTERN = /\b(Bearer|Basic|Token)\s+[\w~+/.=-]{6,}/gi;
+const ASSIGNMENT_PATTERN =
+ /["']?\b(api[_-]?key|access[_-]?token|refresh[_-]?token|id[_-]?token|token|secret|password|passwd|authorization|cookie|session[_-]?id|signature)\b["']?(\s*[:=]\s*)((?:Bearer|Basic|Token)\s+[^\s,;&]+|"[^"]*"|'[^']*'|[^\s,;&]+)/gi;
+const EMAIL_PATTERN = /[\w.%+-]+@[\w-]+(?:\.[\w-]+)+/g;
+const PROVIDER_KEY_PATTERN = /\b(?:sk|pk|rk|xox[abprs]|gh[pousr]|glpat)[-_][\w-]{8,}/gi;
+const AWS_KEY_PATTERN = /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/g;
+const UUID_PATTERN = /\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b/gi;
+const HEX_PATTERN = /\b[0-9a-f]{16,}\b/gi;
+const TOKEN_LIKE_PATTERN = /[A-Za-z0-9+_-]{32,}={0,2}/g;
+const DOUBLE_QUOTED_PATTERN = /"[^"\n]+"/g;
+const LONG_SINGLE_QUOTED_PATTERN = /'[^'\n]{24,}'/g;
+const FRAME_LOCATION = String.raw`(?:[a-z][\w+.-]*:\/\/|\/|[a-z]:\\)[^\s()]*?(?::\d+){1,2}`;
+/**
+ * Complete frame shapes only, each ending in a URL or absolute path with a line number:
+ * V8 (`at fn (https://…/a.js:1:2)`, `at https://…/a.js:1:2`) and Gecko/WebKit
+ * (`fn@https://…/a.js:1:2`). A message line that merely ends in `:123` matches neither.
+ */
+const STACK_FRAME_PATTERNS: readonly RegExp[] = [
+ new RegExp(String.raw`^at (?:[^()]{1,300} \()?${FRAME_LOCATION}\)?$`, 'i'),
+ /^at (?:[^()]{1,300} \()?(?:native|<anonymous>)\)?$/,
+ new RegExp(String.raw`^[\w$.<>/*[\] -]{0,300}@${FRAME_LOCATION}$`, 'i'),
+];
+const IDENTIFIER = String.raw`(?:\(intermediate value\))?[\w$.[\]]{1,120}`;
+/**
+ * Message shapes the JS engine, the browser or a library generates from code identifiers.
+ * An error class proves nothing about provenance (any code can throw `new TypeError(text)`), so
+ * a message is exported only when its whole text matches one of these; every other error keeps
+ * its type, status and stack but never its message, which can echo prompt or response text.
+ */
+const SAFE_MESSAGE_PATTERNS: readonly RegExp[] = [
+ /^Cannot (?:read|set) propert(?:y|ies) of (?:undefined|null)(?: \((?:reading|setting) '[\w$-]{1,80}'\))?$/,
+ /^Cannot (?:read|set) property '[\w$-]{1,80}' of (?:undefined|null)$/,
+ new RegExp(`^${IDENTIFIER} is not (?:a function|a constructor|iterable|defined|an object)$`),
+ new RegExp(`^(?:undefined|null) is not an object \\(evaluating '${IDENTIFIER}'\\)$`),
+ /^Can't find variable: [\w$]{1,80}$/,
+ /^Assignment to constant variable\.$/,
+ /^Maximum call stack size exceeded\.?$/,
+ /^Too much recursion$/i,
+ /^Invalid array length$/,
+ /^Failed to fetch$/,
+ /^Load failed$/,
+ /^NetworkError when attempting to fetch resource\.?$/,
+ /^Network Error$/,
+ /^Request failed with status code \d{3}$/,
+ /^timeout of \d+ms exceeded$/,
+ /^(?:The operation was aborted|The user aborted a request|signal is aborted without reason)\.?$/,
+ /^Unexpected end of JSON input$/,
+ /^ResizeObserver loop (?:limit exceeded|completed with undelivered notifications)\.?$/,
+ /^Failed to fetch dynamically imported module: \S+$/,
+ /^Importing a module script failed\.?$/,
+ /^error loading dynamically imported module(?:: \S+)?$/,
+ /^Unable to preload CSS for \S+$/,
+ /^Loading (?:CSS )?chunk [\w-]+ failed\.?(?: \(\S+\))?$/,
+ /^Failed to load a code-split module$/,
+];
+
+/** Error names are writable too; unknown names must not become a free-text channel. */
+const ERROR_TYPES = new Set([
+ 'Error',
+ 'TypeError',
+ 'ReferenceError',
+ 'RangeError',
+ 'SyntaxError',
+ 'EvalError',
+ 'URIError',
+ 'AggregateError',
+ 'AxiosError',
+ 'ChunkLoadError',
+ 'DOMException',
+ 'AbortError',
+ 'NetworkError',
+ 'NotAllowedError',
+ 'NotFoundError',
+ 'SecurityError',
+ 'TimeoutError',
+ 'DataError',
+ 'InvalidStateError',
+ 'QuotaExceededError',
+ 'NotSupportedError',
+ 'OperationError',
+]);
+
+type ErrorShape = {
+ name?: unknown;
+ message?: unknown;
+ stack?: unknown;
+ status?: unknown;
+ response?: { status?: unknown } | null;
+};
+
+export type ErrorSummary = {
+ type?: string;
+ message?: string;
+ stacktrace?: string;
+ statusCode?: number;
+};
+
+export function truncate(value: string, maxLength: number): string {
+ return value.length > maxLength ? `${value.slice(0, maxLength - 1)}…` : value;
+}
+
+function urlToPath(rawUrl: string): string {
+ try {
+ const url = new URL(rawUrl);
+ return normalizeRumPath(url.pathname);
+ } catch {
+ return '[url]';
+ }
+}
+
+function redactTokenLike(match: string): string {
+ return /\d/.test(match) && /[A-Za-z]/.test(match) ? '[redacted]' : match;
+}
+
+/**
+ * Removes values that can identify a user or grant access: URLs collapse to their route
+ * template, and emails, credentials, JWTs, ids, long secrets and quoted payload fragments are
+ * replaced with placeholders. Applied to every free-text field before it leaves the browser.
+ */
+export function scrubText(value: string): string {
+ return value
+ .replace(URL_PATTERN, urlToPath)
+ .replace(QUERY_PATTERN, '')
+ .replace(JWT_PATTERN, '[jwt]')
+ .replace(ASSIGNMENT_PATTERN, '$1$2[redacted]')
+ .replace(AUTH_SCHEME_PATTERN, '$1 [redacted]')
+ .replace(EMAIL_PATTERN, '[email]')
+ .replace(PROVIDER_KEY_PATTERN, '[key]')
+ .replace(AWS_KEY_PATTERN, '[key]')
+ .replace(UUID_PATTERN, ':id')
+ .replace(HEX_PATTERN, '[hex]')
+ .replace(TOKEN_LIKE_PATTERN, redactTokenLike)
+ .replace(DOUBLE_QUOTED_PATTERN, '"[redacted]"')
+ .replace(LONG_SINGLE_QUOTED_PATTERN, "'[redacted]'");
+}
+
+export function scrubField(value: string, maxLength: number): string {
+ return truncate(scrubText(value), maxLength);
+}
+
+/** V8 prefixes the stack with `name: message`, which can span lines; it is never a frame. */
+function stripStackHeader(stack: string, header?: string): string {
+ return header && stack.startsWith(header) ? stack.slice(header.length) : stack;
+}
+
+/**
+ * Keeps only complete stack frames, with URLs reduced to paths. The `name: message` header is
+ * removed first, so neither it nor any line of a multi-line message can pass as a frame.
+ */
+export function reduceStack(stack: string, header?: string): string | undefined {
+ const frames = stripStackHeader(stack, header)
+ .split('\n')
+ .map((line) => line.trim())
+ .filter((line) => STACK_FRAME_PATTERNS.some((pattern) => pattern.test(line)))
+ .slice(0, MAX_FRAMES)
+ .map((line) => scrubField(line, MAX_FRAME_LENGTH));
+ return frames.length > 0 ? frames.join('\n') : undefined;
+}
+
+function statusCodeOf(error: ErrorShape): number | undefined {
+ const status = error.response?.status ?? error.status;
+ return typeof status === 'number' && Number.isInteger(status) ? status : undefined;
+}
+
+function stackHeader(error: ErrorShape): string | undefined {
+ const name = typeof error.name === 'string' ? error.name : 'Error';
+ const message = typeof error.message === 'string' ? error.message : '';
+ return message ? `${name}: ${message}` : name;
+}
+
+export function isErrorLike(value: unknown): value is ErrorShape {
+ if (value instanceof Error) {
+ return true;
+ }
+ if (typeof value !== 'object' || value === null) {
+ return false;
+ }
+ const shape: ErrorShape = value;
+ return typeof shape.message === 'string' && typeof shape.name === 'string';
+}
+
+export function isSafeErrorMessage(message: string): boolean {
+ const trimmed = message.trim();
+ return SAFE_MESSAGE_PATTERNS.some((pattern) => pattern.test(trimmed));
+}
+
+/**
+ * Allowlisted, scrubbed view of an error: request config, headers and bodies are never read, and
+ * the message is kept only when it matches a known engine-, browser- or library-generated shape.
+ */
+export function summarizeError(error: unknown): ErrorSummary | undefined {
+ if (!isErrorLike(error)) {
+ return undefined;
+ }
+ const message =
+ typeof error.message === 'string' && isSafeErrorMessage(error.message)
+ ? scrubField(error.message.trim(), MAX_MESSAGE_LENGTH)
+ : undefined;
+ return {
+ type: typeof error.name === 'string' && ERROR_TYPES.has(error.name) ? error.name : 'Error',
+ message,
+ stacktrace:
+ typeof error.stack === 'string' ? reduceStack(error.stack, stackHeader(error)) : undefined,
+ statusCode: statusCodeOf(error),
+ };
+}
+
+const BROWSER_FAMILIES: ReadonlyArray<[RegExp, string]> = [
+ [/\bEdg(?:e|A|iOS)?\//, 'Edge'],
+ [/\b(?:OPR|Opera)\//, 'Opera'],
+ [/\bSamsungBrowser\//, 'Samsung Internet'],
+ [/\bFirefox\/|\bFxiOS\//, 'Firefox'],
+ [/\bChrome\/|\bCriOS\//, 'Chrome'],
+ [/\bSafari\//, 'Safari'],
+];
+
+const OS_FAMILIES: ReadonlyArray<[RegExp, string]> = [
+ [/\b(?:iPhone|iPad|iPod)\b/, 'iOS'],
+ [/\bAndroid\b/, 'Android'],
+ [/\bCrOS\b/, 'ChromeOS'],
+ [/\bWindows\b/, 'Windows'],
+ [/\bMac OS X\b|\bMacintosh\b/, 'macOS'],
+ [/\bLinux\b/, 'Linux'],
+];
+
+function matchFamily(userAgent: string, families: ReadonlyArray<[RegExp, string]>): string {
+ return families.find(([pattern]) => pattern.test(userAgent))?.[1] ?? 'Other';
+}
+
+/** Coarse browser and OS families only; the full user agent never leaves the browser. */
+export function getClientPlatform(userAgent: string): { browser: string; os: string } {
+ return {
+ browser: matchFamily(userAgent, BROWSER_FAMILIES),
+ os: matchFamily(userAgent, OS_FAMILIES),
+ };
+}
diff --git a/client/src/lib/rum/trace.ts b/client/src/lib/rum/trace.ts
new file mode 100644
index 0000000000..fda6cb84df
--- /dev/null
+++ b/client/src/lib/rum/trace.ts
@@ -0,0 +1,40 @@
+export type TraceContext = {
+ traceId: string;
+ spanId: string;
+};
+
+type SpanContextShape = { traceId?: unknown; spanId?: unknown };
+type SpanShape = { spanContext?: () => SpanContextShape };
+type ContextShape = { getValue?: (key: symbol) => unknown };
+type OtelGlobalShape = { context?: { active?: () => ContextShape } };
+
+/** Registry key and span context key defined by `@opentelemetry/api` 1.x, which the RUM SDK registers. */
+const OTEL_API_KEY = Symbol.for('opentelemetry.js.api.1');
+const SPAN_KEY = Symbol.for('OpenTelemetry Context Key SPAN');
+const TRACE_ID = /^(?!0+$)[0-9a-f]{32}$/;
+const SPAN_ID = /^(?!0+$)[0-9a-f]{16}$/;
+
+function isSpan(value: unknown): value is SpanShape {
+ return typeof value === 'object' && value !== null && 'spanContext' in value;
+}
+
+/**
+ * Reads the active trace/span ids from the OpenTelemetry context the RUM SDK registered, without
+ * bundling a second copy of the API. Returns `undefined` when no SDK or no span is active.
+ */
+export function getActiveTraceContext(): TraceContext | undefined {
+ try {
+ const api: OtelGlobalShape | undefined = Reflect.get(globalThis, OTEL_API_KEY);
+ const span = api?.context?.active?.()?.getValue?.(SPAN_KEY);
+ if (!isSpan(span) || typeof span.spanContext !== 'function') {
+ return undefined;
+ }
+ const { traceId, spanId } = span.spanContext();
+ if (typeof traceId !== 'string' || typeof spanId !== 'string') {
+ return undefined;
+ }
+ return TRACE_ID.test(traceId) && SPAN_ID.test(spanId) ? { traceId, spanId } : undefined;
+ } catch {
+ return undefined;
+ }
+}
diff --git a/client/src/lib/rum/useRum.spec.tsx b/client/src/lib/rum/useRum.spec.tsx
index 69aaecd3c2..d05966952a 100644
--- a/client/src/lib/rum/useRum.spec.tsx
+++ b/client/src/lib/rum/useRum.spec.tsx
@@ -1,6 +1,7 @@
-import { renderHook, waitFor } from '@testing-library/react';
+import { act, renderHook, waitFor } from '@testing-library/react';
import useRum from './useRum';
+const mockGetSessionId = jest.fn<string | undefined, []>();
const mockInit = jest.fn();
const mockAddAction = jest.fn();
const mockSetGlobalAttributes = jest.fn();
@@ -13,6 +14,7 @@ jest.mock('@hyperdx/browser', () => ({
default: {
addAction: (...args: unknown[]) => mockAddAction(...args),
init: (...args: unknown[]) => mockInit(...args),
+ getSessionId: () => mockGetSessionId(),
setGlobalAttributes: (...args: unknown[]) => mockSetGlobalAttributes(...args),
},
}));
@@ -20,6 +22,7 @@ jest.mock('@hyperdx/browser', () => ({
jest.mock('./diagnostics', () => ({
discardEarlyRumQueue: jest.fn(),
queueSpaRouteChange: jest.fn(),
+ forwardQueuedAssetEvents: jest.fn(),
restoreRumEmitter: jest.fn(),
startRumDiagnostics: jest.fn(),
}));
@@ -27,6 +30,13 @@ jest.mock('./diagnostics', () => ({
const { discardEarlyRumQueue, queueSpaRouteChange, restoreRumEmitter, startRumDiagnostics } =
jest.requireMock('./diagnostics');
+jest.mock('./logs', () => ({
+ startClientLogs: jest.fn(),
+ stopClientLogs: jest.fn(),
+}));
+
+const { startClientLogs, stopClientLogs } = jest.requireMock('./logs');
+
jest.mock('~/data-provider', () => ({
useGetStartupConfig: () => mockUseGetStartupConfig(),
}));
@@ -43,6 +53,8 @@ jest.mock('react-router-dom', () => ({
describe('useRum', () => {
beforeEach(() => {
jest.clearAllMocks();
+ mockGetSessionId.mockReset();
+ mockInit.mockReset();
mockUseGetStartupConfig.mockReturnValue({ data: undefined, isFetched: false });
mockUseLocation.mockReturnValue({ pathname: '/c/conversation-123' });
mockUseAuthContext.mockReturnValue({
@@ -313,4 +325,197 @@ describe('useRum', () => {
expect(queueSpaRouteChange).toHaveBeenCalledWith('/c/:conversationId', '/login');
});
+ describe('client logs', () => {
+ const proxyRum = {
+ provider: 'hyperdx',
+ enabled: true,
+ url: '/api/rum',
+ serviceName: 'librechat-web',
+ authMode: 'proxy',
+ environment: 'demo',
+ clientLogs: true,
+ };
+
+ it('starts proxy-mode client logs on the same-origin logs path with the session token', () => {
+ mockUseGetStartupConfig.mockReturnValue({ isFetched: true, data: { rum: proxyRum } });
+
+ renderHook(() => useRum());
+
+ expect(startClientLogs).toHaveBeenCalledWith(
+ expect.objectContaining({
+ endpoint: '/api/rum/v1/logs',
+ serviceName: 'librechat-web',
+ environment: 'demo',
+ }),
+ );
+ const [{ getToken }] = startClientLogs.mock.calls[0];
+ expect(getToken()).toBe('jwt-token');
+ });
+
+ const currentSessionReader = (): (() => string | undefined) =>
+ startClientLogs.mock.calls.at(-1)[0].getSessionId;
+
+ const signInAsNextUser = () => {
+ mockUseAuthContext.mockReturnValue({
+ isAuthenticated: true,
+ token: 'next-user-token',
+ user: { id: 'user-456', role: 'USER', tenantId: 'org-456' },
+ });
+ mockInit.mockImplementationOnce(() => mockGetSessionId.mockReturnValue('sdk-session-next'));
+ };
+
+ it('never reads a retired hook SDK session when a new authenticated layout mounts', async () => {
+ mockUseGetStartupConfig.mockReturnValue({ isFetched: true, data: { rum: proxyRum } });
+ mockGetSessionId.mockReturnValue('sdk-session-prior');
+ const first = renderHook(() => useRum());
+ await waitFor(() => expect(mockInit).toHaveBeenCalledTimes(1));
+ const retiredReader = currentSessionReader();
+ expect(retiredReader()).toBe('sdk-session-prior');
+ first.unmount();
+ signInAsNextUser();
+ renderHook(() => useRum());
+ expect(retiredReader()).toBeUndefined();
+ expect(currentSessionReader()()).toBeUndefined();
+ await waitFor(() => expect(mockInit).toHaveBeenCalledTimes(2));
+ expect(currentSessionReader()()).toBe('sdk-session-next');
+ });
+
+ it('clears SDK correlation on logout and waits for the new login initialization', async () => {
+ mockUseGetStartupConfig.mockReturnValue({ isFetched: true, data: { rum: proxyRum } });
+ mockGetSessionId.mockReturnValue('sdk-session-prior');
+ const { rerender } = renderHook(() => useRum());
+ await waitFor(() => expect(mockInit).toHaveBeenCalledTimes(1));
+ const priorReader = currentSessionReader();
+ mockUseAuthContext.mockReturnValue({ token: undefined, user: undefined });
+ rerender();
+ expect(priorReader()).toBeUndefined();
+ signInAsNextUser();
+ rerender();
+ expect(currentSessionReader()()).toBeUndefined();
+ await waitFor(() => expect(mockInit).toHaveBeenCalledTimes(2));
+ expect(currentSessionReader()()).toBe('sdk-session-next');
+ });
+
+ it('replaces the exporter before correlating a direct account or tenant switch', async () => {
+ mockUseGetStartupConfig.mockReturnValue({ isFetched: true, data: { rum: proxyRum } });
+ mockGetSessionId.mockReturnValue('sdk-session-prior');
+ const { rerender } = renderHook(() => useRum());
+ await waitFor(() => expect(mockInit).toHaveBeenCalledTimes(1));
+ const stopCount = stopClientLogs.mock.calls.length;
+ signInAsNextUser();
+ rerender();
+ expect(stopClientLogs.mock.calls.length).toBeGreaterThan(stopCount);
+ expect(currentSessionReader()()).toBeUndefined();
+ await waitFor(() => expect(mockInit).toHaveBeenCalledTimes(2));
+ expect(currentSessionReader()()).toBe('sdk-session-next');
+ });
+
+ it('keeps SDK correlation on a same-account token refresh without reinitialization', async () => {
+ mockUseGetStartupConfig.mockReturnValue({ isFetched: true, data: { rum: proxyRum } });
+ mockGetSessionId.mockReturnValue('sdk-session-current');
+ const { rerender } = renderHook(() => useRum());
+ await waitFor(() => expect(mockInit).toHaveBeenCalledTimes(1));
+ mockUseAuthContext.mockReturnValue({
+ token: 'refreshed-token',
+ user: { id: 'user-123', role: 'USER', tenantId: 'org-123' },
+ });
+ rerender();
+ expect(currentSessionReader()()).toBe('sdk-session-current');
+ expect(startClientLogs.mock.calls.at(-1)[0].getToken()).toBe('refreshed-token');
+ await act(async () => undefined);
+ expect(mockInit).toHaveBeenCalledTimes(1);
+ });
+
+ it('keeps new-login logs on fallback correlation if SDK initialization fails', async () => {
+ mockUseGetStartupConfig.mockReturnValue({ isFetched: true, data: { rum: proxyRum } });
+ mockGetSessionId.mockReturnValue('sdk-session-prior');
+ const first = renderHook(() => useRum());
+ await waitFor(() => expect(mockInit).toHaveBeenCalledTimes(1));
+ first.unmount();
+ mockUseAuthContext.mockReturnValue({ token: 'next-user-token', user: { id: 'user-456' } });
+ mockInit.mockImplementationOnce(() => {
+ throw new Error('SDK unavailable');
+ });
+ renderHook(() => useRum());
+ await waitFor(() => expect(mockInit).toHaveBeenCalledTimes(2));
+ expect(currentSessionReader()()).toBeUndefined();
+ expect(startClientLogs.mock.calls.at(-1)[0].getToken()).toBe('next-user-token');
+ });
+
+ it('keeps client logs off when the server leaves them disabled', () => {
+ mockUseGetStartupConfig.mockReturnValue({
+ isFetched: true,
+ data: { rum: { ...proxyRum, clientLogs: false } },
+ });
+
+ renderHook(() => useRum());
+
+ expect(startClientLogs).not.toHaveBeenCalled();
+ expect(stopClientLogs).toHaveBeenCalled();
+ });
+
+ it('never starts client logs in public-token mode', () => {
+ mockUseGetStartupConfig.mockReturnValue({
+ isFetched: true,
+ data: {
+ rum: {
+ ...proxyRum,
+ url: 'https://rum.example.com',
+ authMode: 'publicToken',
+ publicToken: 'public-token',
+ },
+ },
+ });
+
+ renderHook(() => useRum());
+
+ expect(startClientLogs).not.toHaveBeenCalled();
+ });
+
+ it('follows RUM session sampling', () => {
+ mockUseGetStartupConfig.mockReturnValue({
+ isFetched: true,
+ data: { rum: { ...proxyRum, sampleRate: 0 } },
+ });
+
+ renderHook(() => useRum());
+
+ expect(startClientLogs).not.toHaveBeenCalled();
+ expect(stopClientLogs).toHaveBeenCalled();
+ });
+
+ it('stops client logs when the session token goes away', () => {
+ mockUseGetStartupConfig.mockReturnValue({ isFetched: true, data: { rum: proxyRum } });
+ const { rerender } = renderHook(() => useRum());
+ expect(startClientLogs).toHaveBeenCalledTimes(1);
+
+ mockUseAuthContext.mockReturnValue({
+ isAuthenticated: false,
+ token: undefined,
+ user: undefined,
+ });
+ rerender();
+
+ expect(stopClientLogs).toHaveBeenCalled();
+ });
+
+ it('stops client logs when the authenticated layout unmounts', () => {
+ mockUseGetStartupConfig.mockReturnValue({ isFetched: true, data: { rum: proxyRum } });
+ const { unmount } = renderHook(() => useRum());
+ stopClientLogs.mockClear();
+
+ unmount();
+
+ expect(stopClientLogs).toHaveBeenCalledTimes(1);
+ });
+
+ it('stops client logs when startup config has no RUM config', () => {
+ mockUseGetStartupConfig.mockReturnValue({ isFetched: true, data: {} });
+
+ renderHook(() => useRum());
+
+ expect(startClientLogs).not.toHaveBeenCalled();
+ expect(stopClientLogs).toHaveBeenCalled();
+ });
+ });
});
diff --git a/client/src/lib/rum/useRum.ts b/client/src/lib/rum/useRum.ts
index 62e96ddba4..9e77697904 100644
--- a/client/src/lib/rum/useRum.ts
+++ b/client/src/lib/rum/useRum.ts
@@ -5,9 +5,11 @@ import type { HyperDXActionClient } from './diagnostics';
import {
discardEarlyRumQueue,
queueSpaRouteChange,
+ forwardQueuedAssetEvents,
restoreRumEmitter,
startRumDiagnostics,
} from './diagnostics';
+import { startClientLogs, stopClientLogs } from './logs';
import { useGetStartupConfig } from '~/data-provider';
import { useAuthContext } from '~/hooks/AuthContext';
import { normalizeRumPath } from './routes';
@@ -29,6 +31,7 @@ type HyperDXBrowser = HyperDXActionClient & {
url: string;
}) => void;
setGlobalAttributes: (attributes: Record<string, string>) => void;
+ getSessionId?: () => string | undefined;
};
function shouldInitializeRum(config: TRumConfig | undefined, token: string | undefined): boolean {
@@ -58,6 +61,27 @@ function isProxyRumWaitingForToken(
);
}
+/**
+ * Client logs ride the authenticated proxy only: the browser never holds a collector URL or
+ * ingestion key for them, so public-token deployments keep just the RUM SDK's own signals.
+ */
+function syncClientLogs(config: TRumConfig, getSessionId: () => string | undefined): void {
+ if (config.authMode !== 'proxy' || !config.clientLogs) {
+ stopClientLogs();
+ return;
+ }
+
+ startClientLogs({
+ endpoint: `${config.url}/v1/logs`,
+ serviceName: config.serviceName,
+ environment: config.environment,
+ buildId: getClientBuildId() ?? 'unknown',
+ getToken: () => rumProxyToken,
+ getSessionId,
+ });
+ forwardQueuedAssetEvents();
+}
+
function getApiKey(config: TRumConfig, token: string | undefined): string {
if (config.authMode === 'proxy') {
return token ? PROXY_API_KEY : '';
@@ -158,17 +182,31 @@ export default function useRum(): void {
routeRef.current = route;
}, [route, shouldBufferRoutes]);
+ /** Leaving the authenticated layout (e.g. for a share link) ends this session's log export. */
+ useEffect(
+ () => () => {
+ stopClientLogs();
+ hyperDxRef.current = undefined;
+ initializedKeyRef.current = undefined;
+ },
+ [],
+ );
+
useEffect(() => {
if (!rumConfig) {
if (startupConfigFetched) {
discardEarlyRumQueue();
+ stopClientLogs();
}
return;
}
if (!shouldInitializeRum(rumConfig, token)) {
+ stopClientLogs();
if (rumConfig?.authMode === 'proxy') {
rumProxyToken = undefined;
+ hyperDxRef.current = undefined;
+ initializedKeyRef.current = undefined;
}
if (!isProxyRumWaitingForToken(rumConfig, token)) {
discardEarlyRumQueue();
@@ -183,16 +221,23 @@ export default function useRum(): void {
ensureRumProxyAuth(config.url);
}
- const initKey = [config.url, config.serviceName, config.authMode, apiKey].join(':');
+ const identity = config.authMode === 'proxy' ? JSON.stringify([user?.tenantId, user?.id]) : '';
+ const initKey = [config.url, config.serviceName, config.authMode, apiKey, identity].join(':');
+ const getSessionId = () => hyperDxRef.current?.getSessionId?.();
if (initializedKeyRef.current === initKey) {
if (hyperDxRef.current) {
restoreRumEmitter(hyperDxRef.current);
}
+ syncClientLogs(config, getSessionId);
return;
}
if (sampledInitKeyRef.current !== initKey) {
+ /* Retire the previous account's queue and correlation before accepting new records. */
+ stopClientLogs();
+ hyperDxRef.current = undefined;
+ initializedKeyRef.current = undefined;
sampledInitKeyRef.current = initKey;
sampledInRef.current =
typeof config.sampleRate === 'number' ? Math.random() < config.sampleRate : true;
@@ -200,9 +245,12 @@ export default function useRum(): void {
if (!sampledInRef.current) {
discardEarlyRumQueue();
+ stopClientLogs();
return;
}
+ syncClientLogs(config, getSessionId);
+
let cancelled = false;
loadHyperDX()
diff --git a/client/src/locales/en/translation.json b/client/src/locales/en/translation.json
index 8ae9110b93..63c48ddc59 100644
--- a/client/src/locales/en/translation.json
+++ b/client/src/locales/en/translation.json
@@ -3167,6 +3167,7 @@
"com_ui_updated_file": "Updated {{0}}",
"com_ui_updates": "Updates",
"com_ui_updating": "Updating...",
+ "com_ui_updating_latest_version": "Updating to the latest version…",
"com_ui_upload": "Upload",
"com_ui_upload_agent_avatar": "Successfully updated agent avatar",
"com_ui_upload_agent_avatar_label": "Upload agent avatar image",
diff --git a/client/src/main.jsx b/client/src/main.jsx
index 945b89f166..b719fde74c 100644
--- a/client/src/main.jsx
+++ b/client/src/main.jsx
@@ -10,12 +10,6 @@ import { ApiErrorBoundaryProvider } from './hooks/ApiErrorBoundaryContext';
import 'katex/dist/katex.min.css';
import 'katex/dist/contrib/copy-tex.js';
-window.addEventListener('vite:preloadError', (event) => {
- if (window.__lcRecoverStaleAssets?.()) {
- event.preventDefault();
- }
-});
-
const container = document.getElementById('root');
const root = createRoot(container);
diff --git a/client/src/routes/RouteErrorBoundary.tsx b/client/src/routes/RouteErrorBoundary.tsx
index 28a875511c..3ea25fdc25 100644
--- a/client/src/routes/RouteErrorBoundary.tsx
+++ b/client/src/routes/RouteErrorBoundary.tsx
@@ -1,5 +1,10 @@
+import { useEffect } from 'react';
import { Button } from '@librechat/client';
import { useRouteError } from 'react-router-dom';
+import { onClientLogsStarted, reportBoundaryError } from '~/lib/rum/logs';
+import useStaleAssetRecovery from '~/lib/assets/useRecovery';
+import { isChunkLoadError } from '~/lib/assets/recovery';
+import Updating from '~/components/System/Updating';
import { useLocalize } from '~/hooks';
import logger from '~/utils/logger';
@@ -72,7 +77,9 @@ const getBrowserInfo = async () => {
export default function RouteErrorBoundary() {
const localize = useLocalize();
- const typedError = useRouteError() as {
+ const routeError = useRouteError();
+ const updating = useStaleAssetRecovery(routeError);
+ const typedError = (routeError ?? {}) as {
message?: string;
stack?: string;
status?: number;
@@ -80,6 +87,12 @@ export default function RouteErrorBoundary() {
data?: unknown;
};
+ useEffect(() => {
+ const report = () => reportBoundaryError('route', routeError, isChunkLoadError(routeError));
+ report();
+ return onClientLogsStarted(report);
+ }, [routeError]);
+
const errorDetails = {
message: typedError.message ?? 'An unexpected error occurred',
stack: typedError.stack,
@@ -124,20 +137,24 @@ export default function RouteErrorBoundary() {
}
};
+ if (updating) {
+ return <Updating />;
+ }
+
return (
<div
role="alert"
- className="flex min-h-screen flex-col items-center justify-center bg-surface-primary bg-gradient-to-br"
+ className="bg-surface-primary flex min-h-screen flex-col items-center justify-center bg-gradient-to-br"
>
- <div className="mx-4 w-11/12 max-w-4xl rounded-2xl border border-border-light bg-surface-primary/60 p-8 shadow-2xl backdrop-blur-xl">
- <h2 className="mb-6 text-center text-3xl font-medium tracking-tight text-text-primary">
+ <div className="border-border-light bg-surface-primary/60 mx-4 w-11/12 max-w-4xl rounded-2xl border p-8 shadow-2xl backdrop-blur-xl">
+ <h2 className="text-text-primary mb-6 text-center text-3xl font-medium tracking-tight">
{localize('com_ui_error_unexpected')}
</h2>
{/* Error Message */}
- <div className="mb-4 rounded-xl border border-status-error-border bg-status-error-subtle p-4 text-sm text-text-secondary">
+ <div className="border-status-error-border bg-status-error-subtle text-text-secondary mb-4 rounded-xl border p-4 text-sm">
<h3 className="mb-2 font-medium">{localize('com_ui_error_message_prefix')}</h3>
- <pre className="whitespace-pre-wrap text-sm font-light leading-relaxed text-text-primary">
+ <pre className="text-text-primary text-sm leading-relaxed font-light whitespace-pre-wrap">
{errorDetails.message}
</pre>
</div>
@@ -145,7 +162,7 @@ export default function RouteErrorBoundary() {
{/* Status Information */}
{(typeof errorDetails.status === 'number' ||
typeof errorDetails.statusText === 'string') && (
- <div className="mb-4 rounded-xl border border-status-warning-border bg-status-warning-subtle p-4 text-sm text-text-primary">
+ <div className="border-status-warning-border bg-status-warning-subtle text-text-primary mb-4 rounded-xl border p-4 text-sm">
<h3 className="mb-2 font-medium">{localize('com_ui_status_prefix')}:</h3>
<p className="text-text-primary">
{typeof errorDetails.status === 'number' && `${errorDetails.status} `}
@@ -156,8 +173,8 @@ export default function RouteErrorBoundary() {
{/* Stack Trace - Collapsible */}
{errorDetails.stack != null && errorDetails.stack.trim() !== '' && (
- <details className="group mb-4 rounded-xl border border-border-light p-4">
- <summary className="mb-2 flex cursor-pointer items-center justify-between text-sm font-medium text-text-primary">
+ <details className="group border-border-light mb-4 rounded-xl border p-4">
+ <summary className="text-text-primary mb-2 flex cursor-pointer items-center justify-between text-sm font-medium">
<span>{localize('com_ui_stack_trace')}</span>
<div className="flex items-center">
<Button
@@ -171,13 +188,13 @@ export default function RouteErrorBoundary() {
</Button>
</div>
</summary>
- <div className="overflow-x-auto rounded-lg bg-surface-tertiary p-4">
+ <div className="bg-surface-tertiary overflow-x-auto rounded-lg p-4">
{formatStackTrace(errorDetails.stack).map(({ number, content }) => (
<div key={number} className="flex">
- <span className="select-none pr-4 font-mono text-xs text-text-secondary">
+ <span className="text-text-secondary pr-4 font-mono text-xs select-none">
{String(number).padStart(3, '0')}
</span>
- <pre className="flex-1 font-mono text-xs leading-relaxed text-text-primary">
+ <pre className="text-text-primary flex-1 font-mono text-xs leading-relaxed">
{content}
</pre>
</div>
@@ -188,22 +205,22 @@ export default function RouteErrorBoundary() {
{/* Additional Error Data */}
{errorDetails.data != null && (
- <details className="group mb-4 rounded-xl border border-border-light p-4">
- <summary className="mb-2 flex cursor-pointer items-center justify-between text-sm font-medium text-text-primary">
+ <details className="group border-border-light mb-4 rounded-xl border p-4">
+ <summary className="text-text-primary mb-2 flex cursor-pointer items-center justify-between text-sm font-medium">
<span>{localize('com_ui_additional_details')}</span>
<span className="transition-transform group-open:rotate-90">{'>'}</span>
</summary>
- <pre className="whitespace-pre-wrap text-xs font-light leading-relaxed text-text-primary">
+ <pre className="text-text-primary text-xs leading-relaxed font-light whitespace-pre-wrap">
{JSON.stringify(errorDetails.data, null, 2)}
</pre>
</details>
)}
<div className="mt-6 flex flex-col gap-4">
- <p className="text-sm font-light text-text-secondary">
+ <p className="text-text-secondary text-sm font-light">
{localize('com_ui_error_try_following_prefix')}:
</p>
- <ul className="list-inside list-disc text-sm text-text-secondary">
+ <ul className="text-text-secondary list-inside list-disc text-sm">
<li>{localize('com_ui_refresh_page')}</li>
<li>{localize('com_ui_clear_browser_cache')}</li>
<li>{localize('com_ui_check_internet')}</li>
diff --git a/client/src/routes/__tests__/RouteErrorBoundary.spec.tsx b/client/src/routes/__tests__/RouteErrorBoundary.spec.tsx
new file mode 100644
index 0000000000..24f3caa1e6
--- /dev/null
+++ b/client/src/routes/__tests__/RouteErrorBoundary.spec.tsx
@@ -0,0 +1,219 @@
+import { useState } from 'react';
+import { createMemoryRouter, RouterProvider, Outlet } from 'react-router-dom';
+import { render, screen, waitFor, fireEvent, act } from '@testing-library/react';
+import { stopClientLogs, testExports as logTestExports } from '~/lib/rum/logs';
+import { ChunkLoadError } from '~/lib/assets/recovery';
+import RouteErrorBoundary from '../RouteErrorBoundary';
+import en from '~/locales/en/translation.json';
+import WithRum from '~/lib/rum/WithRum';
+
+jest.mock('~/hooks', () => {
+ const translations: Record<string, string> = jest.requireActual('~/locales/en/translation.json');
+ return { useLocalize: () => (key: string) => translations[key] ?? key };
+});
+
+jest.mock('~/data-provider', () => ({
+ useGetStartupConfig: () => ({
+ isFetched: true,
+ data: {
+ rum: {
+ provider: 'hyperdx',
+ enabled: true,
+ authMode: 'proxy',
+ url: '/api/rum',
+ serviceName: 'test',
+ clientLogs: true,
+ },
+ },
+ }),
+}));
+jest.mock('~/hooks/AuthContext', () => ({
+ useAuthContext: () => ({ token: 'session-jwt', user: { id: 'user-1' } }),
+}));
+jest.mock('@hyperdx/browser', () => ({
+ __esModule: true,
+ default: { init: jest.fn(), addAction: jest.fn(), setGlobalAttributes: jest.fn() },
+}));
+
+type ErrorFactory = () => unknown;
+
+function renderRouteThatThrows(createError: ErrorFactory) {
+ const error = createError();
+ const Thrower = () => {
+ throw error;
+ };
+ const router = createMemoryRouter([
+ { path: '/', element: <Thrower />, errorElement: <RouteErrorBoundary /> },
+ ]);
+ return render(<RouterProvider router={router} />);
+}
+
+describe('RouteErrorBoundary stale-asset recovery', () => {
+ let consoleError: jest.SpyInstance;
+
+ beforeEach(() => {
+ consoleError = jest.spyOn(console, 'error').mockImplementation(() => undefined);
+ delete window.__lcStaleAssetRecoveryPending;
+ });
+
+ afterEach(() => {
+ consoleError.mockRestore();
+ delete window.__lcRecoverStaleAssets;
+ delete window.__lcStaleAssetRecoveryPending;
+ });
+
+ it.each([
+ ['Chromium', () => new TypeError('Failed to fetch dynamically imported module: /assets/x.js')],
+ ['Safari', () => new TypeError('Importing a module script failed.')],
+ ['Firefox', () => new TypeError('error loading dynamically imported module')],
+ ['CSS preload', () => new Error('Unable to preload CSS for /assets/panel.css')],
+ ['ChunkLoadError', () => new ChunkLoadError()],
+ ])('shows the updating state and recovers once for a %s chunk failure', async (_label, make) => {
+ const recover = jest.fn(() => true);
+ window.__lcRecoverStaleAssets = recover;
+
+ renderRouteThatThrows(make);
+
+ const status = await screen.findByRole('status');
+ expect(status).toHaveTextContent('Updating to the latest version…');
+ expect(screen.queryByRole('alert')).not.toBeInTheDocument();
+ await waitFor(() => expect(recover).toHaveBeenCalledTimes(1));
+ });
+
+ it('falls back to the error UI with a reload action when recovery declines', async () => {
+ const recover = jest.fn(() => false);
+ window.__lcRecoverStaleAssets = recover;
+
+ renderRouteThatThrows(() => new TypeError('Failed to fetch dynamically imported module'));
+
+ expect(await screen.findByRole('alert')).toBeInTheDocument();
+ expect(screen.queryByRole('status')).not.toBeInTheDocument();
+ expect(screen.getAllByRole('button', { name: en.com_ui_refresh_page }).length).toBeGreaterThan(
+ 0,
+ );
+ expect(recover).toHaveBeenCalledTimes(1);
+ });
+
+ it('keeps the error page for ordinary errors without asking for recovery', async () => {
+ const recover = jest.fn(() => true);
+ window.__lcRecoverStaleAssets = recover;
+
+ renderRouteThatThrows(() => new TypeError("Cannot read properties of undefined (reading 'x')"));
+
+ expect(await screen.findByRole('alert')).toBeInTheDocument();
+ expect(screen.getByText(en.com_ui_error_unexpected)).toBeInTheDocument();
+ expect(screen.queryByRole('status')).not.toBeInTheDocument();
+ expect(recover).not.toHaveBeenCalled();
+ });
+
+ it('shows the updating state for any error while a recovery reload is already underway', async () => {
+ const recover = jest.fn(() => true);
+ window.__lcRecoverStaleAssets = recover;
+ window.__lcStaleAssetRecoveryPending = true;
+
+ renderRouteThatThrows(
+ () => new TypeError("Cannot read properties of undefined (reading 'default')"),
+ );
+
+ expect(await screen.findByRole('status')).toBeInTheDocument();
+ expect(screen.queryByRole('alert')).not.toBeInTheDocument();
+ });
+});
+
+describe('authenticated route reporting lifetime', () => {
+ const failRouteText = 'Fail route';
+ const publicShareText = 'Public share';
+ let originalFetch: typeof window.fetch;
+ beforeEach(() => {
+ originalFetch = window.fetch;
+ jest.useFakeTimers();
+ logTestExports.resetPageState();
+ });
+ afterEach(() => {
+ stopClientLogs();
+ Object.defineProperty(window, 'fetch', {
+ configurable: true,
+ writable: true,
+ value: originalFetch,
+ });
+ jest.useRealTimers();
+ delete window.__lcRecoverStaleAssets;
+ delete window.__lcStaleAssetRecoveryPending;
+ });
+
+ it.each([
+ [false, false],
+ [true, false],
+ [false, true],
+ [true, true],
+ ])(
+ 'reports a route failure (chunk=%s, initial=%s), then stops on a public route',
+ async (chunk, initial) => {
+ jest.spyOn(console, 'error').mockImplementation(() => undefined);
+ window.__lcRecoverStaleAssets = jest.fn(() => false);
+ const transport = jest.fn<Promise<Response>, [RequestInfo | URL, RequestInit?]>(() =>
+ Promise.resolve({ status: 200 } as Response),
+ );
+ Object.defineProperty(window, 'fetch', {
+ configurable: true,
+ writable: true,
+ value: transport,
+ });
+ function Chat() {
+ const [failed, setFailed] = useState(initial);
+ if (failed) {
+ throw chunk ? new ChunkLoadError() : new Error('application failure');
+ }
+ return <button onClick={() => setFailed(true)}>{failRouteText}</button>;
+ }
+ const router = createMemoryRouter(
+ [
+ {
+ element: (
+ <WithRum>
+ <Outlet />
+ </WithRum>
+ ),
+ children: [
+ {
+ errorElement: <RouteErrorBoundary />,
+ children: [{ path: '/c/new', element: <Chat /> }],
+ },
+ ],
+ },
+ { path: '/share/example', element: <div>{publicShareText}</div> },
+ ],
+ { initialEntries: ['/c/new'] },
+ );
+ render(<RouterProvider router={router} />);
+ if (!initial) {
+ fireEvent.click(screen.getByRole('button', { name: 'Fail route' }));
+ }
+ expect(await screen.findByRole('alert')).toBeInTheDocument();
+ await act(async () => {
+ await jest.advanceTimersByTimeAsync(5_000);
+ });
+ const records = transport.mock.calls.flatMap(
+ (call) => JSON.parse(String(call[1]?.body)).resourceLogs[0].scopeLogs[0].logRecords,
+ );
+ expect(records).toEqual(
+ expect.arrayContaining([
+ expect.objectContaining({
+ attributes: expect.arrayContaining([
+ { key: 'error.boundary', value: { stringValue: 'route' } },
+ ]),
+ }),
+ ]),
+ );
+ await act(async () => {
+ await router.navigate('/share/example');
+ });
+ expect(screen.getByText('Public share')).toBeInTheDocument();
+ const count = transport.mock.calls.length;
+ await act(async () => {
+ await jest.advanceTimersByTimeAsync(10_000);
+ });
+ expect(transport).toHaveBeenCalledTimes(count);
+ },
+ );
+});
diff --git a/client/src/routes/index.tsx b/client/src/routes/index.tsx
index 90106aa84d..58364a2d91 100644
--- a/client/src/routes/index.tsx
+++ b/client/src/routes/index.tsx
@@ -11,6 +11,7 @@ import {
} from '~/components/Auth';
import { OAuthSuccess, OAuthError } from '~/components/OAuth';
import { AuthContextProvider } from '~/hooks/AuthContext';
+import { importWithRecovery } from '~/lib/assets/lazy';
import RouteErrorBoundary from './RouteErrorBoundary';
import StartupLayout from './Layouts/Startup';
import MarketplaceRoute from './Marketplace';
@@ -32,27 +33,27 @@ const AuthLayout = () => (
);
const loadInlinePromptsView = () =>
- import('~/components/Prompts/layouts/InlinePromptsView').then((m) => ({
+ importWithRecovery(() => import('~/components/Prompts/layouts/InlinePromptsView')).then((m) => ({
Component: m.default,
}));
const loadSkillsView = () =>
- import('~/components/Skills/layouts/SkillsView').then((m) => ({
+ importWithRecovery(() => import('~/components/Skills/layouts/SkillsView')).then((m) => ({
Component: m.default,
}));
const loadInsightsView = () =>
- import('~/components/Insights').then((m) => ({
+ importWithRecovery(() => import('~/components/Insights')).then((m) => ({
Component: m.default,
}));
const loadProjectsView = () =>
- import('~/components/Projects').then((m) => ({
+ importWithRecovery(() => import('~/components/Projects')).then((m) => ({
Component: m.ProjectsView,
}));
const loadProjectWorkspace = () =>
- import('~/components/Projects').then((m) => ({
+ importWithRecovery(() => import('~/components/Projects')).then((m) => ({
Component: m.ProjectWorkspace,
}));
@@ -109,88 +110,93 @@ export const router = createBrowserRouter(
errorElement: <RouteErrorBoundary />,
children: [
{
- path: '/',
- element: <LoginLayout />,
+ errorElement: <RouteErrorBoundary />,
children: [
{
- path: 'login',
- element: <Login />,
- },
- {
- path: 'login/2fa',
- element: <TwoFactorScreen />,
- },
- {
- path: 'login/2fa/setup',
- element: <TwoFactorSetupScreen />,
- },
- ],
- },
- dashboardRoutes,
- {
- path: '/',
- element: <Root />,
- children: [
- {
- index: true,
- element: <Navigate to="/c/new" replace={true} />,
- },
- {
- path: 'c/:conversationId?',
- element: <ChatRoute />,
- },
- {
- path: 'search',
- element: <Search />,
- },
- {
- path: 'prompts',
- element: <Navigate to="/c/new" replace={true} />,
- },
- {
- /** Prompts are created from a dialog, so there is no "new" page to land on */
- path: 'prompts/new',
- element: <Navigate to="/c/new" replace={true} />,
- },
- {
- path: 'prompts/:promptId',
- lazy: loadInlinePromptsView,
- },
- {
- path: 'skills',
- lazy: loadSkillsView,
- },
- {
- path: 'insights',
- lazy: loadInsightsView,
- },
- {
- path: 'skills/new',
- lazy: loadSkillsView,
- },
- {
- path: 'skills/:skillId',
- lazy: loadSkillsView,
- },
- {
- path: 'skills/:skillId/edit',
- lazy: loadSkillsView,
- },
- {
- path: 'projects',
- lazy: loadProjectsView,
- },
- {
- path: 'projects/:projectId',
- lazy: loadProjectWorkspace,
- },
- {
- path: 'agents',
- element: <MarketplaceRoute />,
- },
- {
- path: 'agents/:category',
- element: <MarketplaceRoute />,
+ path: '/',
+ element: <LoginLayout />,
+ children: [
+ {
+ path: 'login',
+ element: <Login />,
+ },
+ {
+ path: 'login/2fa',
+ element: <TwoFactorScreen />,
+ },
+ {
+ path: 'login/2fa/setup',
+ element: <TwoFactorSetupScreen />,
+ },
+ ],
+ },
+ dashboardRoutes,
+ {
+ path: '/',
+ element: <Root />,
+ children: [
+ {
+ index: true,
+ element: <Navigate to="/c/new" replace={true} />,
+ },
+ {
+ path: 'c/:conversationId?',
+ element: <ChatRoute />,
+ },
+ {
+ path: 'search',
+ element: <Search />,
+ },
+ {
+ path: 'prompts',
+ element: <Navigate to="/c/new" replace={true} />,
+ },
+ {
+ /** Prompts are created from a dialog, so there is no "new" page to land on */
+ path: 'prompts/new',
+ element: <Navigate to="/c/new" replace={true} />,
+ },
+ {
+ path: 'prompts/:promptId',
+ lazy: loadInlinePromptsView,
+ },
+ {
+ path: 'skills',
+ lazy: loadSkillsView,
+ },
+ {
+ path: 'insights',
+ lazy: loadInsightsView,
+ },
+ {
+ path: 'skills/new',
+ lazy: loadSkillsView,
+ },
+ {
+ path: 'skills/:skillId',
+ lazy: loadSkillsView,
+ },
+ {
+ path: 'skills/:skillId/edit',
+ lazy: loadSkillsView,
+ },
+ {
+ path: 'projects',
+ lazy: loadProjectsView,
+ },
+ {
+ path: 'projects/:projectId',
+ lazy: loadProjectWorkspace,
+ },
+ {
+ path: 'agents',
+ element: <MarketplaceRoute />,
+ },
+ {
+ path: 'agents/:category',
+ element: <MarketplaceRoute />,
+ },
+ ],
},
],
},
diff --git a/client/src/utils/heicConverter.spec.ts b/client/src/utils/heicConverter.spec.ts
index 59b30b2306..f3f886fd8d 100644
--- a/client/src/utils/heicConverter.spec.ts
+++ b/client/src/utils/heicConverter.spec.ts
@@ -1,4 +1,9 @@
describe('heicConverter', () => {
+ afterEach(() => {
+ delete window.__lcRecoverStaleAssets;
+ delete window.__lcStaleAssetRecoveryPending;
+ });
+
beforeEach(() => {
jest.resetModules();
});
@@ -18,6 +23,48 @@ describe('heicConverter', () => {
await expect(processFileForUpload(file)).resolves.toBe(file);
});
+ it('requests stale-asset recovery when the required decoder import fails', async () => {
+ const failure = new TypeError(
+ 'Failed to fetch dynamically imported module: /assets/heic-to-old.js',
+ );
+ jest.doMock(
+ 'heic-to',
+ () => {
+ throw failure;
+ },
+ { virtual: true },
+ );
+ const recover = jest.fn(() => false);
+ window.__lcRecoverStaleAssets = recover;
+ jest.spyOn(console, 'error').mockImplementation(() => undefined);
+ const { convertHEICToJPEG } = await import('./heicConverter');
+ await expect(
+ convertHEICToJPEG(new File(['heic'], 'photo.heic', { type: 'image/heic' })),
+ ).rejects.toThrow('Failed to convert');
+ expect(recover).toHaveBeenCalledTimes(1);
+ });
+
+ it('does not recover for a decoder error after its chunk loaded', async () => {
+ jest.doMock(
+ 'heic-to',
+ () => ({
+ isHeic: async () => true,
+ heicTo: async () => {
+ throw new Error('invalid HEIC data');
+ },
+ }),
+ { virtual: true },
+ );
+ const recover = jest.fn(() => false);
+ window.__lcRecoverStaleAssets = recover;
+ jest.spyOn(console, 'error').mockImplementation(() => undefined);
+ const { convertHEICToJPEG } = await import('./heicConverter');
+ await expect(
+ convertHEICToJPEG(new File(['bad'], 'photo.heic', { type: 'image/heic' })),
+ ).rejects.toThrow('Failed to convert');
+ expect(recover).not.toHaveBeenCalled();
+ });
+
it('detects and converts HEIC files after lazily loading heic-to', async () => {
const isHeic = jest.fn(async () => true);
const heicTo = jest.fn(async () => new Blob(['jpeg'], { type: 'image/jpeg' }));
diff --git a/client/src/utils/heicConverter.ts b/client/src/utils/heicConverter.ts
index 46dc7d929a..3b5d097b75 100644
--- a/client/src/utils/heicConverter.ts
+++ b/client/src/utils/heicConverter.ts
@@ -1,3 +1,4 @@
+import { importWithRecovery } from '~/lib/assets/lazy';
const HEIC_MIME_TYPES = new Set(['image/heic', 'image/heif']);
const HEIC_EXTENSION_REGEX = /\.(heic|heif)$/i;
type HeicToModule = typeof import('heic-to');
@@ -5,7 +6,7 @@ type HeicToModule = typeof import('heic-to');
let heicConverterPromise: Promise<HeicToModule> | null = null;
const loadHeicConverter = async (): Promise<HeicToModule> => {
- heicConverterPromise ??= import('heic-to').catch((error) => {
+ heicConverterPromise ??= importWithRecovery(() => import('heic-to')).catch((error) => {
heicConverterPromise = null;
throw error;
});
diff --git a/client/src/utils/logger.ts b/client/src/utils/logger.ts
index b025f4926c..ed412e0936 100644
--- a/client/src/utils/logger.ts
+++ b/client/src/utils/logger.ts
@@ -3,12 +3,36 @@ const isLoggerEnabled = import.meta.env.VITE_ENABLE_LOGGER === 'true';
const loggerFilter = import.meta.env.VITE_LOGGER_FILTER || '';
type LogFunction = (...args: unknown[]) => void;
+type RemoteLogLevel = 'warn' | 'error';
+export type RemoteLogSink = (level: RemoteLogLevel, args: unknown[]) => void;
+
+let remoteLogSink: RemoteLogSink | undefined;
+
+/**
+ * Routes `warn`/`error` calls to a telemetry sink (RUM client logs) independently of console
+ * output. The sink owns redaction; it receives the raw arguments and must never throw.
+ */
+export function setRemoteLogSink(sink: RemoteLogSink | undefined): void {
+ remoteLogSink = sink;
+}
+
+function forwardToRemote(type: string | undefined, args: unknown[]): void {
+ if (!remoteLogSink || (type !== 'warn' && type !== 'error')) {
+ return;
+ }
+ try {
+ remoteLogSink(type, args);
+ } catch {
+ /* Telemetry must never affect the caller. */
+ }
+}
const createLogFunction = (
consoleMethod: LogFunction,
type?: 'log' | 'warn' | 'error' | 'info' | 'debug' | 'dir',
): LogFunction => {
return (...args: unknown[]) => {
+ forwardToRemote(type, args);
if (isLoggerEnabled || (import.meta.env.VITE_ENABLE_LOGGER == null && isDevelopment)) {
const tag = typeof args[0] === 'string' ? args[0] : '';
if (shouldLog(tag)) {
diff --git a/e2e/client-build.test.mjs b/e2e/client-build.test.mjs
index dd4c6f058d..0ac93e31b0 100644
--- a/e2e/client-build.test.mjs
+++ b/e2e/client-build.test.mjs
@@ -168,3 +168,82 @@ test(
}
},
);
+
+// Optional diagnostics catch their own failures. Only an explicitly required import heals the page.
+test(
+ 'optional preload failures do not reload or consume recovery for a required chunk',
+ { timeout: 60000 },
+ async () => {
+ const temporary = await mkdtemp(path.join(tmpdir(), 'librechat-import-policy-'));
+ const appHtml = await readFile(path.join(root, 'client/index.html'), 'utf8');
+ const guards = [...appHtml.matchAll(/<script>([\s\S]*?)<\/script>/g)]
+ .map((match) => match[0])
+ .join('\n');
+ let browser;
+ const server = createServer(async (req, res) => {
+ const pathname = new URL(req.url, 'http://localhost').pathname;
+ try {
+ const file = pathname.startsWith('/assets/') ? pathname.slice(1) : 'index.html';
+ if (file.includes('..')) {
+ res.writeHead(400).end();
+ return;
+ }
+ const content = await readFile(path.join(temporary, 'dist', file));
+ res.setHeader('Content-Type', file.endsWith('.js') ? 'text/javascript' : 'text/html');
+ res.end(content);
+ } catch {
+ res.writeHead(404).end();
+ }
+ });
+ try {
+ await writeFile(
+ path.join(temporary, 'index.html'),
+ `<html><head>${guards}</head><body><input aria-label="Draft"><script type="module" src="/entry.js"></script></body></html>`,
+ );
+ await writeFile(
+ path.join(temporary, 'entry.js'),
+ `
+ import { importWithRecovery } from ${JSON.stringify(path.join(root, 'client/src/lib/assets/lazy.ts'))};
+ window.optional = () => import('./optional.js').catch(() => { window.optionalFailed = true; });
+ window.required = () => importWithRecovery(() => import('./required.js')).catch(() => {});
+ `,
+ );
+ await writeFile(
+ path.join(temporary, 'optional.js'),
+ "import './optional.css'; export const value = 1;",
+ );
+ await writeFile(path.join(temporary, 'optional.css'), 'body { color: inherit; }');
+ await writeFile(path.join(temporary, 'required.js'), 'export const value = 2;');
+ await build({ root: temporary, configFile: false, logLevel: 'silent' });
+ await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+ browser = await chromium.launch({
+ headless: true,
+ channel: process.env.PLAYWRIGHT_CHANNEL,
+ timeout: 30000,
+ });
+ const page = await browser.newPage();
+ page.setDefaultTimeout(10000);
+ await page.route(/\/(?:optional|required)-[^/]+\.(?:js|css)$/, (route) => route.abort());
+ await page.goto(`http://127.0.0.1:${server.address().port}`);
+ await page.waitForFunction(() => typeof window.optional === 'function');
+ await page.getByLabel('Draft').fill('Keep my unsent text');
+ await page.evaluate(() => window.optional());
+ assert.equal(await page.evaluate(() => window.optionalFailed), true);
+ assert.equal(await page.getByLabel('Draft').inputValue(), 'Keep my unsent text');
+ assert.equal(await page.evaluate(() => sessionStorage.getItem('lc-asset-recovery-at')), null);
+ const reloaded = page.waitForEvent('load');
+ await page.evaluate(() => {
+ window.required();
+ });
+ await reloaded;
+ await page.waitForFunction(() => typeof window.required === 'function');
+ assert.ok(
+ (await page.evaluate(() => Number(sessionStorage.getItem('lc-asset-recovery-at')))) > 0,
+ );
+ } finally {
+ await browser?.close();
+ await new Promise((resolve) => server.close(resolve));
+ await rm(temporary, { recursive: true, force: true });
+ }
+ },
+);
diff --git a/packages/api/src/app/metrics.ts b/packages/api/src/app/metrics.ts
index dc7bcc1da8..5bdb33d3a4 100644
--- a/packages/api/src/app/metrics.ts
+++ b/packages/api/src/app/metrics.ts
@@ -171,6 +171,8 @@ export type RumProxyResult =
| 'auth_drop'
| 'auth_error'
| 'bad_request'
+ | 'rate_limited'
+ | 'unsupported_media_type'
| 'not_configured'
| 'collector_4xx'
| 'collector_5xx'
diff --git a/packages/api/src/index.ts b/packages/api/src/index.ts
index f230e48588..9b6508025c 100644
--- a/packages/api/src/index.ts
+++ b/packages/api/src/index.ts
@@ -129,6 +129,7 @@ export * from './stream';
export { memoryDiagnostics } from './utils/memory';
/* RUM */
export * from './rum/proxy';
+export * from './rum/limiter';
/* OpenAPI */
export { createOpenApiRouter } from './openapi/router';
export type { OpenApiRouterDeps } from './openapi/router';
diff --git a/packages/api/src/rum/limiter.spec.ts b/packages/api/src/rum/limiter.spec.ts
new file mode 100644
index 0000000000..eb147b3719
--- /dev/null
+++ b/packages/api/src/rum/limiter.spec.ts
@@ -0,0 +1,96 @@
+jest.mock('~/app/metrics', () => ({
+ recordRumProxyRequest: jest.fn(),
+}));
+
+import express from 'express';
+import request from 'supertest';
+import type { NextFunction, Request, Response } from 'express';
+import type { ServerRequest } from '~/types/http';
+import { createRumProxyLimiter, getRumProxyUserMax, getRumProxyUserWindowMs } from './limiter';
+import { recordRumProxyRequest } from '~/app/metrics';
+
+type TestUser = { id: string; tenantId?: string };
+
+function authenticateFromHeaders(req: Request, _res: Response, next: NextFunction) {
+ const user: TestUser = {
+ id: String(req.headers['x-user'] ?? ''),
+ tenantId: req.headers['x-tenant'] ? String(req.headers['x-tenant']) : undefined,
+ };
+ (req as ServerRequest).user = user as ServerRequest['user'];
+ next();
+}
+
+function createApp() {
+ const app = express();
+ const forwarded = jest.fn((_req: Request, res: Response) => {
+ res.status(200).json({});
+ });
+ app.post('/v1/:signal', authenticateFromHeaders, createRumProxyLimiter(), forwarded);
+ return { app, forwarded };
+}
+
+describe('RUM proxy per-user limiter', () => {
+ const originalEnv = process.env;
+
+ beforeEach(() => {
+ process.env = { ...originalEnv };
+ jest.mocked(recordRumProxyRequest).mockClear();
+ });
+
+ afterEach(() => {
+ process.env = originalEnv;
+ });
+
+ it('defaults to 240 requests per user per minute and ignores invalid overrides', () => {
+ delete process.env.RUM_PROXY_USER_MAX;
+ delete process.env.RUM_PROXY_USER_WINDOW;
+ expect(getRumProxyUserMax()).toBe(240);
+ expect(getRumProxyUserWindowMs()).toBe(60_000);
+
+ process.env.RUM_PROXY_USER_MAX = '0';
+ process.env.RUM_PROXY_USER_WINDOW = 'soon';
+ expect(getRumProxyUserMax()).toBe(240);
+ expect(getRumProxyUserWindowMs()).toBe(60_000);
+
+ process.env.RUM_PROXY_USER_MAX = '0.5';
+ expect(getRumProxyUserMax()).toBe(240);
+
+ process.env.RUM_PROXY_USER_MAX = '30';
+ process.env.RUM_PROXY_USER_WINDOW = '5';
+ expect(getRumProxyUserMax()).toBe(30);
+ expect(getRumProxyUserWindowMs()).toBe(300_000);
+ });
+
+ it('answers 429 once a user exceeds the budget, without reaching the collector', async () => {
+ process.env.RUM_PROXY_USER_MAX = '2';
+ const { app, forwarded } = createApp();
+
+ const send = (signal: string) =>
+ request(app).post(`/v1/${signal}`).set('x-user', 'user-a').send();
+
+ expect((await send('traces')).status).toBe(200);
+ expect((await send('logs')).status).toBe(200);
+ const limited = await send('logs');
+
+ expect(limited.status).toBe(429);
+ expect(limited.headers['retry-after']).toBeDefined();
+ expect(forwarded).toHaveBeenCalledTimes(2);
+ expect(recordRumProxyRequest).toHaveBeenCalledWith('logs', 'rate_limited');
+ });
+
+ it('keeps separate buckets per user and per tenant', async () => {
+ process.env.RUM_PROXY_USER_MAX = '1';
+ const { app } = createApp();
+
+ const send = (user: string, tenant?: string) => {
+ const req = request(app).post('/v1/logs').set('x-user', user);
+ return (tenant ? req.set('x-tenant', tenant) : req).send();
+ };
+
+ expect((await send('user-a', 'tenant-1')).status).toBe(200);
+ expect((await send('user-a', 'tenant-1')).status).toBe(429);
+ expect((await send('user-a', 'tenant-2')).status).toBe(200);
+ expect((await send('user-b', 'tenant-1')).status).toBe(200);
+ expect((await send('user-a')).status).toBe(200);
+ });
+});
diff --git a/packages/api/src/rum/limiter.ts b/packages/api/src/rum/limiter.ts
new file mode 100644
index 0000000000..fd7378f48a
--- /dev/null
+++ b/packages/api/src/rum/limiter.ts
@@ -0,0 +1,56 @@
+import { rateLimit } from 'express-rate-limit';
+import type { Store } from 'express-rate-limit';
+import type { RequestHandler } from 'express';
+import type { ServerRequest } from '~/types/http';
+import { recordRumProxyRequest } from '~/app/metrics';
+import { getRumProxyEndpoint } from './proxy';
+
+const DEFAULT_USER_MAX = 240;
+const DEFAULT_USER_WINDOW_MINUTES = 1;
+const TENANTLESS = '~tenantless';
+
+function positiveNumber(value: string | undefined, fallback: number): number {
+ const parsed = Number(value);
+ return value != null && value.trim() !== '' && Number.isFinite(parsed) && parsed > 0
+ ? parsed
+ : fallback;
+}
+
+export function getRumProxyUserMax(): number {
+ const max = Math.floor(positiveNumber(process.env.RUM_PROXY_USER_MAX, DEFAULT_USER_MAX));
+ return max >= 1 ? max : DEFAULT_USER_MAX;
+}
+
+export function getRumProxyUserWindowMs(): number {
+ return positiveNumber(process.env.RUM_PROXY_USER_WINDOW, DEFAULT_USER_WINDOW_MINUTES) * 60 * 1000;
+}
+
+/**
+ * Per-user budget for browser telemetry sent through the RUM proxy, shared by traces and logs.
+ * Runs after session auth so every bucket belongs to an authenticated user; over budget the
+ * request is answered 429 (OTLP clients back off) without reaching the collector.
+ */
+export function createRumProxyLimiter({
+ store,
+}: {
+ /** Shared counter store (e.g. Redis) from the caller; omitted, counts stay in this process. */
+ store?: Store;
+} = {}): RequestHandler {
+ return rateLimit({
+ windowMs: getRumProxyUserWindowMs(),
+ limit: getRumProxyUserMax(),
+ standardHeaders: 'draft-7',
+ legacyHeaders: false,
+ handler: (req, res) => {
+ recordRumProxyRequest(getRumProxyEndpoint(req.path), 'rate_limited');
+ res.status(429).json({ message: 'Too many RUM telemetry requests' });
+ },
+ /** Tenants can share one store, so a user's bucket is named within their tenant. */
+ keyGenerator: (req) => {
+ const user = (req as ServerRequest).user;
+ const userId = String(user?.id ?? user?._id?.toString() ?? '');
+ return `${user?.tenantId || TENANTLESS}:${userId}`;
+ },
+ store,
+ });
+}
diff --git a/packages/api/src/rum/proxy.spec.ts b/packages/api/src/rum/proxy.spec.ts
index 9d04d7e927..c9bdd2c067 100644
--- a/packages/api/src/rum/proxy.spec.ts
+++ b/packages/api/src/rum/proxy.spec.ts
@@ -1,3 +1,4 @@
+import { RUM_COLLECTOR_ACK_HEADER } from 'librechat-data-provider';
jest.mock('~/app/metrics', () => ({
recordRumProxyRequest: jest.fn(),
}));
@@ -16,8 +17,15 @@ import {
isRumProxyEnabled,
proxyRumRequest,
resolveRumProxyTarget,
+ isRumClientLogsEnabled,
+ isRumLogsEndpointEnabled,
+ requireRumLogsEnabled,
+ requireRumProxyEnabled,
+ excludeRumBodyParser,
} from './proxy';
+const PROTOBUF_HEADERS = { 'content-type': 'application/x-protobuf' };
+
const makeResponse = () => {
const res = {
set: jest.fn(),
@@ -80,6 +88,73 @@ describe('RUM proxy configuration', () => {
expect(isRumProxyEnabled()).toBe(false);
});
+ it('keeps client logs opt-in and limited to proxy mode', () => {
+ process.env.RUM_ENABLED = 'true';
+ process.env.RUM_AUTH_MODE = 'proxy';
+ process.env.RUM_PROXY_TARGET_URL = 'http://otel-collector:4318';
+ delete process.env.RUM_CLIENT_LOGS;
+ expect(isRumClientLogsEnabled()).toBe(false);
+
+ process.env.RUM_CLIENT_LOGS = '';
+ expect(isRumClientLogsEnabled()).toBe(false);
+
+ process.env.RUM_CLIENT_LOGS = 'false';
+ expect(isRumClientLogsEnabled()).toBe(false);
+
+ process.env.RUM_CLIENT_LOGS = 'true';
+ expect(isRumClientLogsEnabled()).toBe(true);
+
+ process.env.RUM_CLIENT_LOGS = 'true';
+ process.env.RUM_AUTH_MODE = 'publicToken';
+ expect(isRumClientLogsEnabled()).toBe(false);
+ });
+
+ it.each([
+ [{}, false],
+ [{ RUM_CLIENT_LOGS: 'true' }, true],
+ [{ RUM_CONSOLE_CAPTURE: 'true' }, true],
+ [{ RUM_DISABLE_REPLAY: 'false' }, true],
+ [{ RUM_DISABLE_REPLAY: 'true', RUM_CLIENT_LOGS: 'false' }, false],
+ ])('accepts OTLP logs only when a browser log source is enabled (%p)', (env, expected) => {
+ process.env.RUM_ENABLED = 'true';
+ process.env.RUM_AUTH_MODE = 'proxy';
+ process.env.RUM_PROXY_TARGET_URL = 'http://otel-collector:4318';
+ delete process.env.RUM_CLIENT_LOGS;
+ delete process.env.RUM_CONSOLE_CAPTURE;
+ delete process.env.RUM_DISABLE_REPLAY;
+ Object.assign(process.env, env);
+
+ expect(isRumLogsEndpointEnabled()).toBe(expected);
+
+ process.env.RUM_AUTH_MODE = 'publicToken';
+ expect(isRumLogsEndpointEnabled()).toBe(false);
+ });
+
+ it.each([undefined, 'text/plain', 'multipart/form-data; boundary=x', 'application/xml'])(
+ 'refuses %p payloads with 415 before contacting the collector',
+ async (contentType) => {
+ process.env.RUM_ENABLED = 'true';
+ process.env.RUM_AUTH_MODE = 'proxy';
+ process.env.RUM_PROXY_TARGET_URL = 'http://otel-collector:4318';
+ const fetchMock = jest.spyOn(global, 'fetch');
+ const res = makeResponse();
+
+ await proxyRumRequest(
+ {
+ path: '/v1/logs',
+ body: Buffer.from('payload'),
+ headers: contentType ? { 'content-type': contentType } : {},
+ } as never,
+ res as never,
+ );
+
+ expect(res.status).toHaveBeenCalledWith(415);
+ expect(fetchMock).not.toHaveBeenCalled();
+ expect(recordRumProxyRequest).toHaveBeenCalledWith('logs', 'unsupported_media_type');
+ fetchMock.mockRestore();
+ },
+ );
+
it('rejects unsafe collector target URLs', () => {
process.env.RUM_PROXY_TARGET_URL = 'https://user:[email protected]';
expect(getRumProxyTargetBaseUrl()).toBeUndefined();
@@ -138,7 +213,10 @@ describe('RUM proxy configuration', () => {
const missingBodyRes = makeResponse();
const unsupportedPathRes = makeResponse();
- await proxyRumRequest({ path: '/v1/traces', headers: {} } as never, missingBodyRes as never);
+ await proxyRumRequest(
+ { path: '/v1/traces', headers: { 'content-type': 'application/x-protobuf' } } as never,
+ missingBodyRes as never,
+ );
await proxyRumRequest(
{ path: '/v1/metrics', body: Buffer.from('payload'), headers: {} } as never,
unsupportedPathRes as never,
@@ -158,7 +236,7 @@ describe('RUM proxy configuration', () => {
const res = makeResponse();
await proxyRumRequest(
- { path: '/v1/traces', body: Buffer.from('payload'), headers: {} } as never,
+ { path: '/v1/traces', body: Buffer.from('payload'), headers: PROTOBUF_HEADERS } as never,
res as never,
);
@@ -177,7 +255,7 @@ describe('RUM proxy configuration', () => {
const res = makeResponse();
await proxyRumRequest(
- { path: '/v1/logs', body: Buffer.from('payload'), headers: {} } as never,
+ { path: '/v1/logs', body: Buffer.from('payload'), headers: PROTOBUF_HEADERS } as never,
res as never,
);
@@ -187,6 +265,125 @@ describe('RUM proxy configuration', () => {
});
});
+describe('RUM HTTP boundary', () => {
+ const originalEnv = process.env;
+ beforeEach(() => {
+ process.env = {
+ ...originalEnv,
+ RUM_ENABLED: 'true',
+ RUM_AUTH_MODE: 'proxy',
+ RUM_PROXY_TARGET_URL: 'http://otel-collector:4318',
+ };
+ });
+ afterEach(() => {
+ process.env = originalEnv;
+ });
+
+ it('maps disabled proxy and log-source policy to 404 in typed middleware', async () => {
+ delete process.env.RUM_CLIENT_LOGS;
+ delete process.env.RUM_CONSOLE_CAPTURE;
+ delete process.env.RUM_DISABLE_REPLAY;
+ const app = express();
+ app.post('/traces', requireRumProxyEnabled, (_req, res) => {
+ res.status(202).end();
+ });
+ app.post('/logs', requireRumLogsEnabled, requireRumProxyEnabled, (_req, res) => {
+ res.status(202).end();
+ });
+ expect((await request(app).post('/traces')).status).toBe(202);
+ expect((await request(app).post('/logs')).status).toBe(404);
+ process.env.RUM_CLIENT_LOGS = 'true';
+ expect((await request(app).post('/logs')).status).toBe(202);
+ process.env.RUM_ENABLED = 'false';
+ expect((await request(app).post('/traces')).status).toBe(404);
+ });
+
+ it('defers JSON parsing to the authenticated, rate-limited RUM route without changing other routes', async () => {
+ const parser = jest.fn(express.json({ limit: '3mb' }));
+ const app = express();
+ app.use(excludeRumBodyParser(parser));
+ app.post(
+ '/api/rum/v1/logs',
+ (req, res, next) => {
+ expect(req.body).toBeUndefined();
+ if (!req.headers.authorization) {
+ res.status(204).end();
+ return;
+ }
+ if (req.headers['x-budget'] === 'exhausted') {
+ res.status(429).end();
+ return;
+ }
+ next();
+ },
+ express.json({ limit: '1kb' }),
+ (req, res) => {
+ res.json(req.body);
+ },
+ );
+ app.post('/api/rumor', (req, res) => {
+ res.json(req.body);
+ });
+ const body = 'not valid JSON';
+ expect(
+ (
+ await request(app)
+ .post('/api/rum/v1/logs')
+ .set('Content-Type', 'application/json')
+ .send(body)
+ ).status,
+ ).toBe(204);
+ expect(
+ (
+ await request(app)
+ .post('/api/rum/v1/logs')
+ .set('authorization', 'Bearer test')
+ .set('x-budget', 'exhausted')
+ .set('Content-Type', 'application/json')
+ .send(body.repeat(1000))
+ ).status,
+ ).toBe(429);
+ expect(
+ (
+ await request(app)
+ .post('/API/RUM/v1/logs')
+ .set('Content-Type', 'application/json')
+ .send(body)
+ ).status,
+ ).toBe(204);
+ expect(parser).not.toHaveBeenCalled();
+ expect(
+ (
+ await request(app)
+ .post('/api/rum/v1/logs')
+ .set('authorization', 'Bearer test')
+ .set('Content-Type', 'application/json')
+ .send(body)
+ ).status,
+ ).toBe(400);
+ expect(
+ (
+ await request(app)
+ .post('/api/rum/v1/logs')
+ .set('authorization', 'Bearer test')
+ .send({ records: [] })
+ ).body,
+ ).toEqual({ records: [] });
+ expect(
+ (
+ await request(app)
+ .post('/api/rum/v1/logs')
+ .set('authorization', 'Bearer test')
+ .send({ text: 'x'.repeat(2000) })
+ ).status,
+ ).toBe(413);
+ expect((await request(app).post('/api/rumor').send({ parsed: true })).body).toEqual({
+ parsed: true,
+ });
+ expect(parser).toHaveBeenCalledTimes(1);
+ });
+});
+
describe('RUM proxy upstream HTTP contract', () => {
const originalEnv = process.env;
let collector: Server;
@@ -267,6 +464,74 @@ describe('RUM proxy upstream HTTP contract', () => {
},
);
+ it('marks a successful collector 204 so clients can distinguish it from an auth drop', async () => {
+ collector.on('request', (_req, res) => {
+ res.writeHead(204);
+ res.end();
+ });
+ const app = express();
+ app.use(express.json());
+ app.post('/v1/logs', (req, res) => proxyRumRequest(req, res));
+ const response = await request(app).post('/v1/logs').send({ resourceLogs: [] });
+ expect(response.status).toBe(204);
+ expect(response.headers[RUM_COLLECTOR_ACK_HEADER]).toBe('true');
+ });
+
+ it('forwards OTLP/JSON log records unchanged after the app JSON parser and never logs them', async () => {
+ const records = {
+ resourceLogs: [
+ {
+ resource: {
+ attributes: [{ key: 'service.name', value: { stringValue: 'librechat-web' } }],
+ },
+ scopeLogs: [
+ {
+ scope: { name: 'librechat.client', version: '1' },
+ logRecords: [
+ {
+ timeUnixNano: '1790000000000000000',
+ severityNumber: 17,
+ severityText: 'ERROR',
+ body: { stringValue: 'payload-marker' },
+ attributes: [{ key: 'log.repeat_count', value: { intValue: '3' } }],
+ traceId: 'a'.repeat(32),
+ spanId: 'b'.repeat(16),
+ },
+ ],
+ },
+ ],
+ },
+ ],
+ };
+ let receivedBody = '';
+ let receivedType: string | undefined;
+ collector.on('request', (req, res) => {
+ receivedType = req.headers['content-type'];
+ req.on('data', (chunk: Buffer) => {
+ receivedBody += chunk.toString();
+ });
+ req.on('end', () => {
+ res.writeHead(200, { 'content-type': 'application/json' });
+ res.end('{}');
+ });
+ });
+ const logSpy = jest.spyOn(logger, 'warn');
+ const app = express();
+ app.use(express.json({ limit: '3mb' }));
+ app.post('/v1/:signal', (req, res) => proxyRumRequest(req, res));
+
+ const response = await request(app)
+ .post('/v1/logs')
+ .set('Content-Type', 'application/json')
+ .send(JSON.stringify(records));
+
+ expect(response.status).toBe(200);
+ expect(receivedType).toBe('application/json');
+ expect(JSON.parse(receivedBody)).toEqual(records);
+ expect(JSON.stringify(logSpy.mock.calls)).not.toContain('payload-marker');
+ logSpy.mockRestore();
+ });
+
it.each([undefined, '', ' '])(
'preserves unauthenticated collectors with authorization %p',
async (authorization) => {
diff --git a/packages/api/src/rum/proxy.ts b/packages/api/src/rum/proxy.ts
index 2b68805478..00197e10b9 100644
--- a/packages/api/src/rum/proxy.ts
+++ b/packages/api/src/rum/proxy.ts
@@ -1,6 +1,7 @@
import { validateHeaderValue } from 'node:http';
import { logger } from '@librechat/data-schemas';
-import type { Request, Response } from 'express';
+import { RUM_COLLECTOR_ACK_HEADER } from 'librechat-data-provider';
+import type { Request, Response, RequestHandler } from 'express';
import type { RumProxyEndpoint, RumProxyResult } from '~/app/metrics';
import { recordRumProxyRequest } from '~/app/metrics';
import { isEnabled } from '~/utils';
@@ -9,6 +10,12 @@ const DEFAULT_PROXY_PATH = '/api/rum';
const DEFAULT_BODY_LIMIT = '3mb';
const DEFAULT_TIMEOUT_MS = 10_000;
const OTLP_PATHS = new Set(['/v1/traces', '/v1/logs']);
+/** OTLP/HTTP encodings; anything else is refused before a body is forwarded. */
+const OTLP_CONTENT_TYPES = new Set([
+ 'application/json',
+ 'application/x-protobuf',
+ 'application/octet-stream',
+]);
function normalizeBasePath(pathname: string): string {
if (pathname === '/') {
@@ -63,6 +70,63 @@ export function isRumProxyEnabled(): boolean {
);
}
+/**
+ * Whether browsers export client logger warnings/errors as OTLP logs. Opt-in with
+ * `RUM_CLIENT_LOGS=true`, like console capture, so enabling RUM never starts a new log stream on
+ * its own; proxy mode only, so the logs reach the collector through session auth and never with
+ * a browser-held ingestion key.
+ */
+export function isRumClientLogsEnabled(): boolean {
+ return isRumProxyEnabled() && isEnabled(process.env.RUM_CLIENT_LOGS);
+}
+
+/**
+ * Whether the proxy accepts OTLP logs at all. Only client logs, SDK console capture and SDK
+ * session replay produce browser logs, so with all three off the logs route refuses even tabs
+ * still holding an older startup config, which makes turning `RUM_CLIENT_LOGS` off authoritative.
+ */
+export function isRumLogsEndpointEnabled(): boolean {
+ if (!isRumProxyEnabled()) {
+ return false;
+ }
+ const replaySetting = process.env.RUM_DISABLE_REPLAY?.trim();
+ const replayEnabled = !!replaySetting && !isEnabled(replaySetting);
+ return (
+ isEnabled(process.env.RUM_CLIENT_LOGS) ||
+ isEnabled(process.env.RUM_CONSOLE_CAPTURE) ||
+ replayEnabled
+ );
+}
+
+/** HTTP gates stay with the proxy policy rather than the CJS route wiring. */
+export const requireRumProxyEnabled: RequestHandler = (_req, res, next) => {
+ if (!isRumProxyEnabled()) {
+ res.status(404).json({ message: 'RUM proxy is not configured' });
+ return;
+ }
+ next();
+};
+
+export const requireRumLogsEnabled: RequestHandler = (_req, res, next) => {
+ if (!isRumLogsEndpointEnabled()) {
+ res.status(404).json({ message: 'RUM logs are not enabled' });
+ return;
+ }
+ next();
+};
+
+/** Defer RUM parsing until the authenticated route has applied its request budget. */
+export function excludeRumBodyParser(parser: RequestHandler): RequestHandler {
+ return (req, res, next) => {
+ const path = req.path.toLowerCase();
+ if (path === DEFAULT_PROXY_PATH || path.startsWith(`${DEFAULT_PROXY_PATH}/`)) {
+ next();
+ return;
+ }
+ parser(req, res, next);
+ };
+}
+
export function resolveRumProxyTarget(path: string): string | undefined {
if (!OTLP_PATHS.has(path)) {
return undefined;
@@ -79,7 +143,7 @@ export function resolveRumProxyTarget(path: string): string | undefined {
}
// Keep in sync with api/server/middleware/requireJwtAuth.js; auth drops are recorded there.
-function getRumProxyEndpoint(path: string): RumProxyEndpoint {
+export function getRumProxyEndpoint(path: string): RumProxyEndpoint {
if (path === '/v1/traces') {
return 'traces';
}
@@ -122,6 +186,11 @@ function getHeader(req: Request, name: string): string | undefined {
return typeof value === 'string' ? value : undefined;
}
+function isOtlpContentType(req: Request): boolean {
+ const mediaType = getHeader(req, 'content-type')?.split(';', 1)[0]?.trim().toLowerCase();
+ return mediaType != null && OTLP_CONTENT_TYPES.has(mediaType);
+}
+
function getProxyHeaders(
req: Request,
body: Buffer | string,
@@ -159,6 +228,12 @@ export async function proxyRumRequest(
return;
}
+ if (!isOtlpContentType(req)) {
+ recordRumProxyRequest(endpoint, 'unsupported_media_type');
+ res.status(415).json({ message: 'Unsupported RUM payload content type' });
+ return;
+ }
+
const body = getRequestBody(req);
if (!body) {
recordRumProxyRequest(endpoint, 'bad_request');
@@ -186,6 +261,9 @@ export async function proxyRumRequest(
const responseBody = Buffer.from(await response.arrayBuffer());
recordRumProxyRequest(endpoint, getRumCollectorResult(response.status));
+ if (response.status >= 200 && response.status < 300) {
+ res.set(RUM_COLLECTOR_ACK_HEADER, 'true');
+ }
res.status(response.status).send(responseBody);
} catch (error) {
recordRumProxyRequest(
diff --git a/packages/data-provider/src/config.ts b/packages/data-provider/src/config.ts
index 6b983c6ea9..9c9961c8b9 100644
--- a/packages/data-provider/src/config.ts
+++ b/packages/data-provider/src/config.ts
@@ -2873,6 +2873,9 @@ export const turnstileSchema = z.object({
export type TTurnstileConfig = z.infer<typeof turnstileSchema>;
+/** Distinguishes collector acceptance from the proxy's silent 204 authentication drop. */
+export const RUM_COLLECTOR_ACK_HEADER = 'x-librechat-rum-accepted';
+
export type TRumConfig = {
provider: 'hyperdx';
enabled: boolean;
@@ -2886,6 +2889,8 @@ export type TRumConfig = {
advancedNetworkCapture?: boolean;
sampleRate?: number;
environment?: string;
+ /** Opt-in, proxy mode only: export client logger warnings/errors as OTLP logs via the RUM proxy. */
+ clientLogs?: boolean;
};
export type StartupConfigContext = 'share';