@lobehub/lobehub 2.0.0-next.41 → 2.0.0-next.42

package/packages/utils/src/clientIP.ts

@@ -1,16 +1,16 @@
 /**
- * 获取客户端 IP
- * @param headers HTTP 请求头
+ * Get client IP address
+ * @param headers HTTP request headers
  */
 export const getClientIP = (headers: Headers): string => {
-  // 按优先级顺序检查各种 IP 头
+  // Check various IP headers in priority order
   const ipHeaders = [
     'cf-connecting-ip', // Cloudflare
     'x-real-ip', // Nginx proxy
-    'x-forwarded-for', // 标准代理头
+    'x-forwarded-for', // Standard proxy header
     'x-client-ip', // Apache
     'true-client-ip', // Akamai and Cloudflare
-    'x-cluster-client-ip', // 负载均衡
+    'x-cluster-client-ip', // Load balancer
     'forwarded', // RFC 7239
     'fastly-client-ip', // Fastly CDN
     'x-forwarded', // General forward
@@ -21,7 +21,7 @@ export const getClientIP = (headers: Headers): string => {
     const value = headers.get(header);
     if (!value) continue;
 
-    // 处理可能包含多个 IP 的情况（比如 x-forwarded-for）
+    // Handle cases where multiple IPs may be present (e.g., x-forwarded-for)
     if (header.toLowerCase() === 'x-forwarded-for') {
       const firstIP = value.split(',')[0].trim();
       if (firstIP) return firstIP;

package/packages/utils/src/compressImage.ts

@@ -1,16 +1,16 @@
 const compressImage = ({ img, type = 'image/webp' }: { img: HTMLImageElement; type?: string }) => {
-  // 设置最大宽高
+  // Set maximum width and height
   const maxWidth = 2160;
   const maxHeight = 2160;
   let width = img.width;
   let height = img.height;
 
   if (width > height && width > maxWidth) {
-    // 如果图片宽度大于高度且大于最大宽度限制
+    // If image width is greater than height and exceeds maximum width limit
     width = maxWidth;
     height = Math.round((maxWidth / img.width) * img.height);
   } else if (height > width && height > maxHeight) {
-    // 如果图片高度大于宽度且大于最大高度限制
+    // If image height is greater than width and exceeds maximum height limit
     height = maxHeight;
     width = Math.round((maxHeight / img.height) * img.width);
   }

package/packages/utils/src/fetch/fetchSSE.ts

@@ -91,7 +91,7 @@ export interface FetchSSEOptions {
   responseAnimation?: ResponseAnimation;
 }
 
-const START_ANIMATION_SPEED = 10; // 默认起始速度
+const START_ANIMATION_SPEED = 10; // Default starting speed
 
 const createSmoothMessage = (params: {
   onTextUpdate: (delta: string, text: string) => void;
@@ -106,7 +106,7 @@ const createSmoothMessage = (params: {
   let lastFrameTime = 0;
   let accumulatedTime = 0;
   let currentSpeed = startSpeed;
-  let lastQueueLength = 0; // 记录上一帧的队列长度
+  let lastQueueLength = 0; // Record the queue length from the previous frame
 
   const stopAnimation = () => {
     isAnimationActive = false;
@@ -127,7 +127,7 @@ const createSmoothMessage = (params: {
       lastFrameTime = performance.now();
       accumulatedTime = 0;
       currentSpeed = speed;
-      lastQueueLength = 0; // 重置上一帧队列长度
+      lastQueueLength = 0; // Reset previous frame queue length
 
       const updateText = (timestamp: number) => {
         if (!isAnimationActive) {
@@ -144,9 +144,9 @@ const createSmoothMessage = (params: {
 
         let charsToProcess = 0;
         if (outputQueue.length > 0) {
-          // 更平滑的速度调整
+          // Smoother speed adjustment
           const targetSpeed = Math.max(speed, outputQueue.length);
-          // 根据队列长度变化调整速度变化率
+          // Adjust speed change rate based on queue length changes
           const speedChangeRate = Math.abs(outputQueue.length - lastQueueLength) * 0.0008 + 0.005;
           currentSpeed += (targetSpeed - currentSpeed) * speedChangeRate;
 
@@ -157,7 +157,7 @@ const createSmoothMessage = (params: {
           accumulatedTime -= (charsToProcess * 1000) / currentSpeed;
 
           let actualChars = Math.min(charsToProcess, outputQueue.length);
-          // actualChars = Math.min(speed, actualChars); // 速度上限
+          // actualChars = Math.min(speed, actualChars); // Speed upper limit
 
           // if (actualChars * 2 < outputQueue.length && /[\dA-Za-z]/.test(outputQueue[actualChars])) {
           //   actualChars *= 2;
@@ -168,7 +168,7 @@ const createSmoothMessage = (params: {
           params.onTextUpdate(charsToAdd, buffer);
         }
 
-        lastQueueLength = outputQueue.length; // 更新上一帧的队列长度
+        lastQueueLength = outputQueue.length; // Update previous frame queue length
 
         if (outputQueue.length > 0 && isAnimationActive) {
           animationFrameId = requestAnimationFrame(updateText);
@@ -219,7 +219,7 @@ export const fetchSSE = async (url: string, options: RequestInit & FetchSSEOptio
   const shouldSkipTextProcessing = text === 'none';
   const textSmoothing = text === 'smooth';
 
-  // 添加文本buffer和计时器相关变量
+  // Add text buffer and timer related variables
   let textBuffer = '';
   let bufferTimer: ReturnType<typeof setTimeout> | null = null;
   const BUFFER_INTERVAL = 300; // 300ms
@@ -254,7 +254,7 @@ export const fetchSSE = async (url: string, options: RequestInit & FetchSSEOptio
   let thinkingBuffer = '';
   let thinkingBufferTimer: ReturnType<typeof setTimeout> | null = null;
 
-  // 创建一个函数来处理buffer的刷新
+  // Create a function to handle buffer flushing
   const flushThinkingBuffer = () => {
     if (thinkingBuffer) {
       options.onMessageHandle?.({ text: thinkingBuffer, type: 'reasoning' });
@@ -349,10 +349,10 @@ export const fetchSSE = async (url: string, options: RequestInit & FetchSSEOptio
           } else {
             output += data;
 
-            // 使用buffer机制
+            // Use buffer mechanism
             textBuffer += data;
 
-            // 如果还没有设置计时器，创建一个
+            // If timer not set yet, create one
             if (!bufferTimer) {
               bufferTimer = setTimeout(() => {
                 flushTextBuffer();
@@ -395,10 +395,10 @@ export const fetchSSE = async (url: string, options: RequestInit & FetchSSEOptio
           } else {
             thinking += data;
 
-            // 使用buffer机制
+            // Use buffer mechanism
             thinkingBuffer += data;
 
-            // 如果还没有设置计时器，创建一个
+            // If timer not set yet, create one
             if (!thinkingBufferTimer) {
               thinkingBufferTimer = setTimeout(() => {
                 flushThinkingBuffer();
@@ -421,7 +421,7 @@ export const fetchSSE = async (url: string, options: RequestInit & FetchSSEOptio
     },
     onopen: async (res) => {
       response = res.clone();
-      // 如果不 ok 说明有请求错误
+      // If not ok, it means there is a request error
       if (!response.ok) {
         throw await getMessageError(res);
       }
@@ -434,7 +434,7 @@ export const fetchSSE = async (url: string, options: RequestInit & FetchSSEOptio
   if (response) {
     textController.stopAnimation();
 
-    // 确保所有缓冲区数据都被处理
+    // Ensure all buffered data is processed
     if (bufferTimer) {
       clearTimeout(bufferTimer);
       flushTextBuffer();

package/packages/utils/src/format.ts

@@ -64,10 +64,10 @@ export const formatShortenNumber = (num: any) => {
   if (!num && num !== 0) return '--';
   if (!isNumber(num)) return num;
 
-  // 使用Intl.NumberFormat来添加千分号
+  // Use Intl.NumberFormat to add thousand separators
   const formattedWithComma = new Intl.NumberFormat('en-US').format(num);
 
-  // 格式化为 K 或 M
+  // Format as K or M
   if (num >= 1_000_000) {
     return (num / 1_000_000).toFixed(1) + 'M';
   } else if (num >= 10_000) {

package/packages/utils/src/merge.ts

@@ -1,7 +1,7 @@
 import { merge as _merge, isEmpty, mergeWith } from 'lodash-es';
 
 /**
- * 用于合并对象，如果是数组则直接替换
+ * Merge objects, directly replace if it's an array
  * @param target
  * @param source
  */
@@ -24,7 +24,7 @@ export const mergeArrayById = <T extends MergeableItem>(defaultItems: T[], userI
   // Create a map of default items for faster lookup
   const defaultItemsMap = new Map(defaultItems.map((item) => [item.id, item]));
 
-  // 使用 Map 存储合并结果，这样重复 ID 的后项会自然覆盖前项
+  // Use Map to store merged results, so duplicate IDs naturally overwrite previous entries
   const mergedItemsMap = new Map<string, T>();
 
   // Process user items with default metadata
@@ -51,7 +51,7 @@ export const mergeArrayById = <T extends MergeableItem>(defaultItems: T[], userI
     mergedItemsMap.set(userItem.id, mergedItem);
   });
 
-  // 添加只在默认配置中存在的项
+  // Add items that only exist in default configuration
   defaultItems.forEach((item) => {
     if (!mergedItemsMap.has(item.id)) {
       mergedItemsMap.set(item.id, item);

package/packages/utils/src/parseModels.ts

@@ -138,16 +138,16 @@ export const transformToAiModelList = async ({
   const modelConfig = await parseModelString(providerId, modelString, withDeploymentName);
   let chatModels = modelConfig.removeAll ? [] : defaultModels;
 
-  // 处理移除逻辑
+  // Handle removal logic
   if (!modelConfig.removeAll) {
     chatModels = chatModels.filter((m) => !modelConfig.removed.includes(m.id));
   }
 
-  // 异步获取配置
+  // Asynchronously load configuration
   const { LOBE_DEFAULT_MODEL_LIST } = await import('model-bank');
 
   return produce(chatModels, (draft) => {
-    // 处理添加或替换逻辑
+    // Handle add or replace logic
     for (const toAddModel of modelConfig.add) {
       // first try to find the model in LOBE_DEFAULT_MODEL_LIST to confirm if it is a known model
       let knownModel = LOBE_DEFAULT_MODEL_LIST.find(

package/packages/utils/src/sanitizeUTF8.ts

@@ -3,12 +3,12 @@
  * @param str
  */
 export const sanitizeUTF8 = (str: string) => {
-  // 移除替换字符 (0xFFFD) 和其他非法字符
+  // Remove replacement character (0xFFFD) and other illegal characters
   return (
     str
-      .replaceAll('�', '') // 移除 Unicode 替换字符
+      .replaceAll('�', '') // Remove Unicode replacement character
       // eslint-disable-next-line no-control-regex
-      .replaceAll(/[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F-\u009F]/g, '') // 移除控制字符
+      .replaceAll(/[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F-\u009F]/g, '') // Remove control characters
       .replaceAll(/[\uD800-\uDFFF]/g, '')
-  ); // 移除未配对的代理项码点
+  ); // Remove unpaired surrogate code points
 };

package/packages/utils/src/toolManifest.ts

@@ -4,7 +4,7 @@ import { LobeChatPluginManifest, pluginManifestSchema } from '@lobehub/chat-plug
 import { API_ENDPOINTS } from '@/services/_url';
 
 const fetchJSON = async <T = any>(url: string, proxy = false): Promise<T> => {
-  // 2. 发送请求
+  // 2. Send request
   let res: Response;
   try {
     res = await (proxy ? fetch(API_ENDPOINTS.proxy, { body: url, method: 'POST' }) : fetch(url));
@@ -80,12 +80,12 @@ export const getToolManifest = async (
   url?: string,
   useProxy: boolean = false,
 ): Promise<LobeChatPluginManifest> => {
-  // 1. valid plugin
+  // 1. Validate plugin
   if (!url) {
     throw new TypeError('noManifest');
   }
 
-  // 2. 发送请求
+  // 2. Send request
   let data = await fetchJSON<LobeChatPluginManifest>(url, useProxy);
 
   // @ts-ignore
@@ -94,7 +94,7 @@ export const getToolManifest = async (
   if (data['description_for_model']) {
     data = convertOpenAIManifestToLobeManifest(data as any);
   }
-  // 3. 校验插件文件格式规范
+  // 3. Validate plugin file format specification
   const parser = pluginManifestSchema.safeParse(data);
 
   if (!parser.success) {

package/packages/utils/src/trace.test.ts

@@ -0,0 +1,359 @@
+import { LOBE_CHAT_TRACE_HEADER, LOBE_CHAT_TRACE_ID } from '@lobechat/const';
+import { describe, expect, it } from 'vitest';
+
+import { createTraceHeader, getTraceId, getTracePayload } from './trace';
+
+describe('trace utilities', () => {
+  describe('getTracePayload', () => {
+    it('should extract and decode trace payload from request headers', () => {
+      const payload = {
+        traceId: '123-456-789',
+        sessionId: 'session-abc',
+        timestamp: 1234567890,
+      };
+
+      const encoded = Buffer.from(JSON.stringify(payload)).toString('base64');
+      const mockRequest = new Request('http://localhost', {
+        headers: {
+          [LOBE_CHAT_TRACE_HEADER]: encoded,
+        },
+      });
+
+      const result = getTracePayload(mockRequest);
+
+      expect(result).toEqual(payload);
+    });
+
+    it('should return undefined when trace header is not present', () => {
+      const mockRequest = new Request('http://localhost');
+
+      const result = getTracePayload(mockRequest);
+
+      expect(result).toBeUndefined();
+    });
+
+    it('should handle empty trace header', () => {
+      const mockRequest = new Request('http://localhost', {
+        headers: {
+          [LOBE_CHAT_TRACE_HEADER]: '',
+        },
+      });
+
+      const result = getTracePayload(mockRequest);
+
+      expect(result).toBeUndefined();
+    });
+
+    it('should decode complex payload with nested objects', () => {
+      const payload = {
+        traceId: 'trace-123',
+        metadata: {
+          user: { id: 'user-1', role: 'admin' },
+          context: { env: 'production', region: 'us-west-2' },
+        },
+        tags: ['important', 'production'],
+      };
+
+      const encoded = Buffer.from(JSON.stringify(payload)).toString('base64');
+      const mockRequest = new Request('http://localhost', {
+        headers: {
+          [LOBE_CHAT_TRACE_HEADER]: encoded,
+        },
+      });
+
+      const result = getTracePayload(mockRequest);
+
+      expect(result).toEqual(payload);
+    });
+
+    it('should handle payload with special characters', () => {
+      const payload = {
+        traceId: 'trace-with-特殊字符-🔥',
+        message: 'Test with émojis 😀',
+      };
+
+      const encoded = Buffer.from(JSON.stringify(payload)).toString('base64');
+      const mockRequest = new Request('http://localhost', {
+        headers: {
+          [LOBE_CHAT_TRACE_HEADER]: encoded,
+        },
+      });
+
+      const result = getTracePayload(mockRequest);
+
+      expect(result).toEqual(payload);
+    });
+
+    it('should handle payload with null values', () => {
+      const payload = {
+        traceId: 'trace-123',
+        optionalField: null,
+        anotherField: undefined,
+      };
+
+      const encoded = Buffer.from(JSON.stringify(payload)).toString('base64');
+      const mockRequest = new Request('http://localhost', {
+        headers: {
+          [LOBE_CHAT_TRACE_HEADER]: encoded,
+        },
+      });
+
+      const result = getTracePayload(mockRequest);
+
+      // Note: undefined values are removed during JSON.stringify
+      expect(result).toEqual({
+        traceId: 'trace-123',
+        optionalField: null,
+      });
+    });
+
+    it('should handle numeric and boolean values in payload', () => {
+      const payload = {
+        traceId: 'trace-123',
+        count: 42,
+        isActive: true,
+        ratio: 3.14159,
+        isDisabled: false,
+      };
+
+      const encoded = Buffer.from(JSON.stringify(payload)).toString('base64');
+      const mockRequest = new Request('http://localhost', {
+        headers: {
+          [LOBE_CHAT_TRACE_HEADER]: encoded,
+        },
+      });
+
+      const result = getTracePayload(mockRequest);
+
+      expect(result).toEqual(payload);
+    });
+  });
+
+  describe('getTraceId', () => {
+    it('should extract trace ID from response headers', () => {
+      const traceId = 'trace-xyz-789';
+      const mockResponse = new Response(null, {
+        headers: {
+          [LOBE_CHAT_TRACE_ID]: traceId,
+        },
+      });
+
+      const result = getTraceId(mockResponse);
+
+      expect(result).toBe(traceId);
+    });
+
+    it('should return null when trace ID header is not present', () => {
+      const mockResponse = new Response(null);
+
+      const result = getTraceId(mockResponse);
+
+      expect(result).toBeNull();
+    });
+
+    it('should handle empty trace ID', () => {
+      const mockResponse = new Response(null, {
+        headers: {
+          [LOBE_CHAT_TRACE_ID]: '',
+        },
+      });
+
+      const result = getTraceId(mockResponse);
+
+      expect(result).toBe('');
+    });
+
+    it('should handle trace ID with special characters', () => {
+      const traceId = 'trace-123-abc-特殊-🔥';
+      const mockResponse = new Response(null, {
+        headers: {
+          [LOBE_CHAT_TRACE_ID]: traceId,
+        },
+      });
+
+      const result = getTraceId(mockResponse);
+
+      expect(result).toBe(traceId);
+    });
+
+    it('should handle UUID-formatted trace IDs', () => {
+      const traceId = '550e8400-e29b-41d4-a716-446655440000';
+      const mockResponse = new Response(null, {
+        headers: {
+          [LOBE_CHAT_TRACE_ID]: traceId,
+        },
+      });
+
+      const result = getTraceId(mockResponse);
+
+      expect(result).toBe(traceId);
+    });
+  });
+
+  describe('createTraceHeader', () => {
+    it('should create a base64-encoded trace header from payload', () => {
+      const payload = {
+        traceId: 'trace-123',
+        sessionId: 'session-456',
+        timestamp: 1234567890,
+      };
+
+      const result = createTraceHeader(payload);
+
+      expect(result).toHaveProperty(LOBE_CHAT_TRACE_HEADER);
+      expect(typeof result[LOBE_CHAT_TRACE_HEADER]).toBe('string');
+
+      // Verify it's valid base64
+      const decoded = Buffer.from(result[LOBE_CHAT_TRACE_HEADER], 'base64').toString('utf8');
+      expect(JSON.parse(decoded)).toEqual(payload);
+    });
+
+    it('should create header for empty payload object', () => {
+      const payload = {};
+
+      const result = createTraceHeader(payload);
+
+      expect(result).toHaveProperty(LOBE_CHAT_TRACE_HEADER);
+
+      const decoded = Buffer.from(result[LOBE_CHAT_TRACE_HEADER], 'base64').toString('utf8');
+      expect(JSON.parse(decoded)).toEqual({});
+    });
+
+    it('should handle payload with nested objects', () => {
+      const payload = {
+        traceId: 'trace-123',
+        metadata: {
+          user: { id: 'user-1', name: 'John' },
+          context: { env: 'prod' },
+        },
+      };
+
+      const result = createTraceHeader(payload);
+
+      const decoded = Buffer.from(result[LOBE_CHAT_TRACE_HEADER], 'base64').toString('utf8');
+      expect(JSON.parse(decoded)).toEqual(payload);
+    });
+
+    it('should handle payload with arrays', () => {
+      const payload = {
+        traceId: 'trace-123',
+        tags: ['tag1', 'tag2', 'tag3'],
+        values: [1, 2, 3, 4, 5],
+      };
+
+      const result = createTraceHeader(payload);
+
+      const decoded = Buffer.from(result[LOBE_CHAT_TRACE_HEADER], 'base64').toString('utf8');
+      expect(JSON.parse(decoded)).toEqual(payload);
+    });
+
+    it('should handle payload with Unicode characters', () => {
+      const payload = {
+        traceId: 'trace-特殊-🔥',
+        message: 'Hello 世界 😀',
+        description: 'Тест тест',
+      };
+
+      const result = createTraceHeader(payload);
+
+      const decoded = Buffer.from(result[LOBE_CHAT_TRACE_HEADER], 'base64').toString('utf8');
+      expect(JSON.parse(decoded)).toEqual(payload);
+    });
+
+    it('should handle payload with null values', () => {
+      const payload = {
+        traceId: 'trace-123',
+        optionalField: null,
+      };
+
+      const result = createTraceHeader(payload);
+
+      const decoded = Buffer.from(result[LOBE_CHAT_TRACE_HEADER], 'base64').toString('utf8');
+      expect(JSON.parse(decoded)).toEqual(payload);
+    });
+
+    it('should handle payload with boolean and numeric values', () => {
+      const payload = {
+        traceId: 'trace-123',
+        count: 42,
+        isActive: true,
+        ratio: 3.14,
+        isDisabled: false,
+      };
+
+      const result = createTraceHeader(payload);
+
+      const decoded = Buffer.from(result[LOBE_CHAT_TRACE_HEADER], 'base64').toString('utf8');
+      expect(JSON.parse(decoded)).toEqual(payload);
+    });
+
+    it('should create header that works with getTracePayload', () => {
+      const payload = {
+        traceId: 'trace-round-trip',
+        sessionId: 'session-test',
+        timestamp: Date.now(),
+      };
+
+      const header = createTraceHeader(payload);
+      const mockRequest = new Request('http://localhost', {
+        headers: header,
+      });
+
+      const extractedPayload = getTracePayload(mockRequest);
+
+      expect(extractedPayload).toEqual(payload);
+    });
+  });
+
+  describe('round-trip encoding and decoding', () => {
+    it('should correctly encode and decode simple payload', () => {
+      const originalPayload = {
+        traceId: 'test-123',
+        data: 'test-data',
+      };
+
+      const header = createTraceHeader(originalPayload);
+      const mockRequest = new Request('http://localhost', { headers: header });
+      const decodedPayload = getTracePayload(mockRequest);
+
+      expect(decodedPayload).toEqual(originalPayload);
+    });
+
+    it('should correctly encode and decode complex payload', () => {
+      const originalPayload = {
+        traceId: 'complex-trace',
+        metadata: {
+          user: { id: 'usr-123', roles: ['admin', 'user'] },
+          timestamps: { created: 1234567890, updated: 1234567900 },
+        },
+        tags: ['production', 'critical'],
+        metrics: { duration: 123.45, count: 10 },
+        flags: { enabled: true, debug: false },
+      };
+
+      const header = createTraceHeader(originalPayload);
+      const mockRequest = new Request('http://localhost', { headers: header });
+      const decodedPayload = getTracePayload(mockRequest);
+
+      expect(decodedPayload).toEqual(originalPayload);
+    });
+
+    it('should preserve data types through encoding and decoding', () => {
+      const originalPayload = {
+        traceId: 'trace-types-test',
+        sessionId: 'session-123',
+        userId: 'user-456',
+        topicId: 'topic-789',
+        observationId: 'obs-abc',
+        enabled: true,
+        tags: ['tag1', 'tag2', 'tag3'],
+      };
+
+      const header = createTraceHeader(originalPayload);
+      const mockRequest = new Request('http://localhost', { headers: header });
+      const decodedPayload = getTracePayload(mockRequest);
+
+      expect(decodedPayload).toEqual(originalPayload);
+    });
+  });
+});

package/packages/utils/src/uriParser.ts

@@ -5,20 +5,20 @@ interface UriParserResult {
 }
 
 export const parseDataUri = (dataUri: string): UriParserResult => {
-  // 正则表达式匹配整个 Data URI 结构
+  // Regular expression to match the entire Data URI structure
   const dataUriMatch = dataUri.match(/^data:([^;]+);base64,(.+)$/);
 
   if (dataUriMatch) {
-    // 如果是合法的 Data URI
+    // If it's a valid Data URI
     return { base64: dataUriMatch[2], mimeType: dataUriMatch[1], type: 'base64' };
   }
 
   try {
     new URL(dataUri);
-    // 如果是合法的 URL
+    // If it's a valid URL
     return { base64: null, mimeType: null, type: 'url' };
   } catch {
-    // 既不是 Data URI 也不是合法 URL
+    // Neither a Data URI nor a valid URL
     return { base64: null, mimeType: null, type: null };
   }
 };