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
TypeScript aianthropicartifactsawsazurechatgptchatgpt-cloneclaudeclonedeepseekgeminigooglegpt-5librechatmcpo1openairesponses-apivisionwebui
🔭 feat: Recover Stale Chunks Without the Error Page and Ship Client Logs to RUM (#16701)
Danny Avila741978c95451
diff --git a/.env.example b/.env.exampleindex 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.jsindex 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.jsindex 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.jsindex 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.jsindex 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.jsindex 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.jsindex 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.htmlindex 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.tsxindex 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.tsxindex 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.tsxindex 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.tsxindex 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.tsxindex 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.tsxindex 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.tsxindex 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.tsxnew file mode 100644index 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.tsxindex 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/useKeyboardShortcutimport { 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.tsxindex 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 closediff --git a/client/src/components/Web/SourcesErrorBoundary.tsx b/client/src/components/Web/SourcesErrorBoundary.tsxindex 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><Buttonvariant="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.tsxindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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';// Constantsconst 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.tsxnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsxindex 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.tsindex 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.jsonindex 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.jsxindex 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.tsxindex 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 (<divrole="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.tsxnew file mode 100644index 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.tsxindex 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.tsindex 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.tsindex 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.tsindex 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.mjsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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';