@ai-setting/roy-agent-core 1.0.0

package/src/env/log-trace/opentelemetry/propagation-env.test.ts

@@ -0,0 +1,181 @@
+/**
+ * @fileoverview Propagation Env 测试
+ * 
+ * 测试 propagation-env 模块：
+ * - injectToEnv: 从当前 OTelTracerProvider 获取上下文并注入环境变量
+ * - injectToEnvWithContext: 直接注入指定 SpanContext
+ */
+
+import { describe, test, expect, beforeEach, afterEach, vi } from 'bun:test';
+import { 
+  injectToEnv,
+  injectToEnvWithContext,
+  injectToEnvFromCarrier,
+} from './propagation-env';
+import { propagation } from './propagation';
+
+// Mock the tracer-provider module
+const mockInjectToEnv = vi.fn();
+const mockGetCurrentContext = vi.fn();
+
+vi.mock('./tracer-provider', () => ({
+  getTracerProvider: vi.fn().mockReturnValue({
+    getTracer: vi.fn().mockReturnValue({
+      injectToEnv: mockInjectToEnv,
+      getCurrentContext: mockGetCurrentContext,
+    }),
+    isInitialized: vi.fn().mockReturnValue(true),
+  }),
+}));
+
+describe('propagation-env', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe('injectToEnv', () => {
+    test('should inject TRACEPARENT to provided env object', async () => {
+      // Create a mock tracer with current context
+      const mockSpanContext = {
+        traceId: '0af7651916cd43dd8448eb211c80319c',
+        spanId: 'b7ad6b7169203331',
+        parentSpanId: undefined,
+      };
+
+      mockGetCurrentContext.mockReturnValue(mockSpanContext);
+      mockInjectToEnv.mockImplementation((env: Record<string, string | undefined>) => {
+        env['TRACEPARENT'] = '00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01';
+      });
+
+      const env: Record<string, string | undefined> = {};
+      injectToEnv(env);
+
+      expect(env['TRACEPARENT']).toBeDefined();
+      expect(env['TRACEPARENT']).toMatch(/^00-[0-9a-f]{32}-[0-9a-f]{16}-01$/);
+    });
+
+    test('should not inject if no current context', () => {
+      mockGetCurrentContext.mockReturnValue(undefined);
+      mockInjectToEnv.mockImplementation((_env: Record<string, string | undefined>) => {});
+
+      const env: Record<string, string | undefined> = {};
+      injectToEnv(env);
+
+      // injectToEnv should not set TRACEPARENT when no context
+      expect(mockInjectToEnv).toHaveBeenCalledWith(env);
+    });
+
+    test('should preserve existing env variables', () => {
+      const mockSpanContext = {
+        traceId: '0af7651916cd43dd8448eb211c80319c',
+        spanId: 'b7ad6b7169203331',
+        parentSpanId: undefined,
+      };
+
+      mockGetCurrentContext.mockReturnValue(mockSpanContext);
+      mockInjectToEnv.mockImplementation((env: Record<string, string | undefined>) => {
+        env['TRACEPARENT'] = '00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01';
+      });
+
+      const env: Record<string, string | undefined> = {
+        HOME: '/home/user',
+        PATH: '/usr/bin',
+        CUSTOM_VAR: 'custom-value',
+      };
+      
+      injectToEnv(env);
+
+      expect(env['HOME']).toBe('/home/user');
+      expect(env['PATH']).toBe('/usr/bin');
+      expect(env['CUSTOM_VAR']).toBe('custom-value');
+      expect(env['TRACEPARENT']).toBeDefined();
+    });
+  });
+
+  describe('injectToEnvWithContext', () => {
+    test('should inject given SpanContext to env', () => {
+      const context = {
+        traceId: '0af7651916cd43dd8448eb211c80319c',
+        spanId: 'b7ad6b7169203331',
+        parentSpanId: 'a1b2c3d4e5f67890',
+      };
+
+      const env: Record<string, string | undefined> = {};
+      injectToEnvWithContext(env, context);
+
+      // 验证 propagation.inject 被正确调用
+      expect(env['TRACEPARENT']).toBe('00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01');
+    });
+
+    test('should inject traceparent format correctly', () => {
+      const context = {
+        traceId: '0af7651916cd43dd8448eb211c80319c',
+        spanId: 'b7ad6b7169203331',
+        parentSpanId: undefined,
+      };
+
+      const env: Record<string, string | undefined> = {};
+      injectToEnvWithContext(env, context);
+
+      const traceparent = env['TRACEPARENT'];
+      expect(traceparent).toBe('00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01');
+    });
+
+    test('should overwrite existing TRACEPARENT', () => {
+      const context = {
+        traceId: '0af7651916cd43dd8448eb211c80319c',
+        spanId: 'b7ad6b7169203331',
+        parentSpanId: undefined,
+      };
+
+      const env: Record<string, string | undefined> = {
+        TRACEPARENT: '00-old-trace-old-span-old-flags',
+      };
+      
+      injectToEnvWithContext(env, context);
+
+      expect(env['TRACEPARENT']).toBe('00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01');
+    });
+  });
+
+  describe('injectToEnvFromCarrier', () => {
+    test('should inject from source carrier to target carrier', () => {
+      const sourceCarrier: Record<string, string | undefined> = {
+        TRACEPARENT: '00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01',
+      };
+
+      const targetCarrier: Record<string, string | undefined> = {};
+      injectToEnvFromCarrier(targetCarrier, sourceCarrier);
+
+      expect(targetCarrier['TRACEPARENT']).toBe('00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01');
+    });
+
+    test('should return undefined if source has no TRACEPARENT', () => {
+      const sourceCarrier: Record<string, string | undefined> = {};
+      const targetCarrier: Record<string, string | undefined> = {};
+      
+      injectToEnvFromCarrier(targetCarrier, sourceCarrier);
+
+      expect(targetCarrier['TRACEPARENT']).toBeUndefined();
+    });
+  });
+});
+
+describe('propagation-env integration', () => {
+  test('should produce valid W3C traceparent format', () => {
+    const context = {
+      traceId: '0af7651916cd43dd8448eb211c80319c',
+      spanId: 'b7ad6b7169203331',
+      parentSpanId: undefined,
+    };
+
+    const env: Record<string, string | undefined> = {};
+    injectToEnvWithContext(env, context);
+
+    // Parse and verify format
+    const parsed = propagation.extract(env);
+    expect(parsed).toBeDefined();
+    expect(parsed!.traceId).toBe('0af7651916cd43dd8448eb211c80319c');
+    expect(parsed!.spanId).toBe('b7ad6b7169203331');
+  });
+});

package/src/env/log-trace/opentelemetry/propagation-env.ts

@@ -0,0 +1,136 @@
+/**
+ * @fileoverview Propagation Env Module
+ * 
+ * 提供便捷的环境变量注入功能，用于在子进程执行时传递 trace context。
+ * 
+ * @example
+ * ```typescript
+ * import { injectToEnv, injectToEnvWithContext } from './propagation-env';
+ * 
+ * // 在 Bash 工具中执行子进程前：
+ * const traceEnv = injectToEnv();  // 从当前 OTelTracerProvider 获取并注入
+ * const options = {
+ *   env: { ...process.env, ...traceEnv, ...env },
+ * };
+ * spawn(command, args, options);
+ * ```
+ */
+
+import type { SpanContext } from "../types";
+import { propagation } from "./propagation";
+import { getTracerProvider } from "./tracer-provider";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * 环境变量对象类型
+ */
+export type EnvCarrier = Record<string, string | undefined>;
+
+// ============================================================================
+// Core Functions
+// ============================================================================
+
+/**
+ * 从当前 OTelTracerProvider 获取上下文并注入到环境变量
+ * 
+ * 这是一个便捷函数，封装了常见的注入模式：
+ * 1. 从全局 TracerProvider 获取当前 Tracer
+ * 2. 获取当前 span context
+ * 3. 注入到目标环境变量
+ * 
+ * @param env 目标环境变量对象（默认：{}）
+ * @returns 注入了 TRACEPARENT 的环境变量对象
+ * 
+ * @example
+ * ```typescript
+ * const env = injectToEnv({ PATH: '/usr/bin' });
+ * // env.TRACEPARENT = '00-{traceId}-{spanId}-01'
+ * // env.PATH = '/usr/bin'
+ * ```
+ */
+export function injectToEnv(env: EnvCarrier = {}): EnvCarrier {
+  const provider = getTracerProvider();
+  
+  // 如果 provider 未初始化，尝试获取 tracer（可能会自动初始化）
+  const tracer = provider.getTracer('roy-tracer');
+  
+  tracer.injectToEnv(env);
+  
+  return env;
+}
+
+/**
+ * 将指定的 SpanContext 直接注入到环境变量
+ * 
+ * 与 injectToEnv 不同，这个函数不需要访问全局 TracerProvider，
+ * 直接使用传入的 SpanContext 进行注入。
+ * 
+ * @param env 目标环境变量对象
+ * @param context 要注入的 SpanContext
+ * @returns 注入了 TRACEPARENT 的环境变量对象
+ * 
+ * @example
+ * ```typescript
+ * const span = tracer.startSpan('my-span');
+ * const env = injectToEnvWithContext({}, span.spanContext);
+ * ```
+ */
+export function injectToEnvWithContext(env: EnvCarrier, context: SpanContext): EnvCarrier {
+  propagation.inject(env, context);
+  return env;
+}
+
+/**
+ * 从源环境变量 carrier 复制 TRACEPARENT 到目标 carrier
+ * 
+ * 用于将一个环境变量对象中的 trace context 传递到另一个：
+ * - 从 process.env 复制到子进程的环境变量
+ * - 从父进程环境变量复制到子进程环境变量
+ * 
+ * @param target 目标 carrier（将被修改）
+ * @param source 源 carrier
+ * @returns 目标 carrier
+ * 
+ * @example
+ * ```typescript
+ * // 在 fork 子进程时继承父进程的 trace context
+ * const childEnv = injectToEnvFromCarrier({}, process.env);
+ * ```
+ */
+export function injectToEnvFromCarrier(target: EnvCarrier, source: EnvCarrier): EnvCarrier {
+  const extracted = propagation.extract(source);
+  
+  if (extracted) {
+    // 将提取的上下文重新注入到目标
+    // ExtractedContext 包含发送方的 traceId 和 spanId
+    // 需要构造新的 SpanContext 用于传播
+    const context: SpanContext = {
+      traceId: extracted.traceId,
+      spanId: extracted.spanId, // 使用发送方的 spanId
+      parentSpanId: undefined, // 新的 span 将作为根 span（但会继承 traceId）
+    };
+    propagation.inject(target, context);
+  }
+  
+  return target;
+}
+
+// ============================================================================
+// Utility Functions
+// ============================================================================
+
+/**
+ * 获取 TRACEPARENT 字段名
+ */
+export function getTraceparentHeader(): string {
+  return propagation.getTraceparentHeader();
+}
+
+// ============================================================================
+// Re-exports
+// ============================================================================
+
+export type { SpanContext } from "../types";

package/src/env/log-trace/opentelemetry/propagation.test.ts

@@ -0,0 +1,259 @@
+/**
+ * @fileoverview W3C TraceContext Propagation 测试
+ * 
+ * 测试 W3C TraceContext 标准的 traceparent 格式：
+ * - 注入 (inject): 将 SpanContext 序列化到环境变量
+ * - 提取 (extract): 从环境变量反序列化 SpanContext
+ * - 序列化 (serialize): SpanContext -> traceparent 字符串
+ * - 反序列化 (parse): traceparent 字符串 -> SpanContext
+ */
+
+import { describe, test, expect, beforeEach } from 'bun:test';
+import { 
+  propagation,
+  serialize,
+  parse,
+  type SpanContext,
+  type ExtractedContext,
+} from './propagation';
+
+describe('propagation', () => {
+  describe('serialize', () => {
+    test('should serialize basic SpanContext to traceparent format', () => {
+      const context: SpanContext = {
+        traceId: '0af7651916cd43dd8448eb211c80319c',
+        spanId: 'b7ad6b7169203331',
+        parentSpanId: undefined,
+      };
+
+      const result = serialize(context);
+      // W3C TraceContext: 使用 spanId 而非 parentSpanId
+      expect(result).toBe('00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01');
+    });
+
+    test('should serialize SpanContext with parentSpanId', () => {
+      const context: SpanContext = {
+        traceId: '0af7651916cd43dd8448eb211c80319c',
+        spanId: 'b7ad6b7169203331',
+        parentSpanId: 'a1b2c3d4e5f67890',
+      };
+
+      const result = serialize(context);
+      // W3C TraceContext: 使用 spanId 而非 parentSpanId
+      expect(result).toBe('00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01');
+    });
+
+    test('should pad traceId to 32 characters', () => {
+      const context: SpanContext = {
+        traceId: '1',
+        spanId: 'b7ad6b7169203331',
+        parentSpanId: undefined,
+      };
+
+      const result = serialize(context);
+      // traceId "1" should be padded to "00000000000000000000000000000001"
+      expect(result).toMatch(/^00-0{31}1-/);
+    });
+
+    test('should pad spanId to 16 characters', () => {
+      const context: SpanContext = {
+        traceId: '0af7651916cd43dd8448eb211c80319c',
+        spanId: '1',
+        parentSpanId: undefined,
+      };
+
+      const result = serialize(context);
+      // spanId "1" should be padded to "0000000000000001"
+      expect(result).toMatch(/-0{15}1-01$/);
+    });
+  });
+
+  describe('parse', () => {
+    test('should parse valid traceparent string', () => {
+      const traceparent = '00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01';
+
+      const result = parse(traceparent);
+      
+      expect(result).toBeDefined();
+      expect(result!.traceId).toBe('0af7651916cd43dd8448eb211c80319c');
+      // parse returns ExtractedContext: spanId is the sender's spanId
+      expect(result!.spanId).toBe('b7ad6b7169203331');
+    });
+
+    test('should parse traceparent string', () => {
+      const traceparent = '00-0af7651916cd43dd8448eb211c80319c-a1b2c3d4e5f67890-01';
+
+      const result = parse(traceparent);
+      
+      expect(result).toBeDefined();
+      expect(result!.traceId).toBe('0af7651916cd43dd8448eb211c80319c');
+      expect(result!.spanId).toBe('a1b2c3d4e5f67890');
+    });
+
+    test('should return undefined for invalid traceparent format', () => {
+      const invalidTraceparent = 'invalid-format';
+
+      const result = parse(invalidTraceparent);
+      
+      expect(result).toBeUndefined();
+    });
+
+    test('should return undefined for wrong version', () => {
+      const wrongVersion = '01-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01';
+
+      const result = parse(wrongVersion);
+      
+      expect(result).toBeUndefined();
+    });
+
+    test('should return undefined for traceId wrong length', () => {
+      const wrongLength = '00-0af7651916cd43dd8448eb211c80319-b7ad6b7169203331-01';
+
+      const result = parse(wrongLength);
+      
+      expect(result).toBeUndefined();
+    });
+
+    test('should return undefined for spanId wrong length', () => {
+      const wrongLength = '00-0af7651916cd43dd8448eb211c80319c-b7ad6b716920333-01';
+
+      const result = parse(wrongLength);
+      
+      expect(result).toBeUndefined();
+    });
+  });
+
+  describe('inject', () => {
+    test('should inject SpanContext to carrier', () => {
+      const carrier: Record<string, string> = {};
+      const context: SpanContext = {
+        traceId: '0af7651916cd43dd8448eb211c80319c',
+        spanId: 'b7ad6b7169203331',
+        parentSpanId: undefined,
+      };
+
+      propagation.inject(carrier, context);
+
+      expect(carrier['TRACEPARENT']).toBe('00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01');
+    });
+
+    test('should inject with parentSpanId', () => {
+      const carrier: Record<string, string> = {};
+      const context: SpanContext = {
+        traceId: '0af7651916cd43dd8448eb211c80319c',
+        spanId: 'b7ad6b7169203331',
+        parentSpanId: 'a1b2c3d4e5f67890',
+      };
+
+      propagation.inject(carrier, context);
+
+      // W3C TraceContext: inject uses spanId (sender's span ID)
+      expect(carrier['TRACEPARENT']).toBe('00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01');
+    });
+
+    test('should overwrite existing TRACEPARENT', () => {
+      const carrier: Record<string, string> = {
+        TRACEPARENT: '00-old-trace-old-span-old-flags',
+      };
+      const context: SpanContext = {
+        traceId: '0af7651916cd43dd8448eb211c80319c',
+        spanId: 'b7ad6b7169203331',
+      };
+
+      propagation.inject(carrier, context);
+
+      expect(carrier['TRACEPARENT']).toBe('00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01');
+    });
+  });
+
+  describe('extract', () => {
+    test('should extract SpanContext from carrier', () => {
+      const carrier: Record<string, string> = {
+        TRACEPARENT: '00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01',
+      };
+
+      const result = propagation.extract(carrier);
+
+      expect(result).toBeDefined();
+      expect(result!.traceId).toBe('0af7651916cd43dd8448eb211c80319c');
+      // extract returns ExtractedContext: spanId is sender's spanId
+      expect(result!.spanId).toBe('b7ad6b7169203331');
+    });
+
+    test('should extract with spanId', () => {
+      const carrier: Record<string, string> = {
+        TRACEPARENT: '00-0af7651916cd43dd8448eb211c80319c-a1b2c3d4e5f67890-01',
+      };
+
+      const result = propagation.extract(carrier);
+
+      expect(result).toBeDefined();
+      expect(result!.traceId).toBe('0af7651916cd43dd8448eb211c80319c');
+      expect(result!.spanId).toBe('a1b2c3d4e5f67890');
+    });
+
+    test('should return undefined when TRACEPARENT not present', () => {
+      const carrier: Record<string, string> = {};
+
+      const result = propagation.extract(carrier);
+
+      expect(result).toBeUndefined();
+    });
+
+    test('should return undefined for invalid TRACEPARENT', () => {
+      const carrier: Record<string, string> = {
+        TRACEPARENT: 'invalid-traceparent',
+      };
+
+      const result = propagation.extract(carrier);
+
+      expect(result).toBeUndefined();
+    });
+
+    test('should handle lowercase traceparent', () => {
+      const carrier: Record<string, string> = {
+        TRACEPARENT: '00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01',
+      };
+
+      const result = propagation.extract(carrier);
+
+      expect(result).toBeDefined();
+      expect(result!.traceId).toBe('0af7651916cd43dd8448eb211c80319c');
+    });
+  });
+
+  describe('roundtrip', () => {
+    test('should serialize and parse back to same values (traceId and parentSpanId)', () => {
+      const original: SpanContext = {
+        traceId: '0af7651916cd43dd8448eb211c80319c',
+        spanId: 'b7ad6b7169203331',
+        parentSpanId: 'a1b2c3d4e5f67890',
+      };
+
+      const serialized = serialize(original);
+      const parsed = parse(serialized);
+
+      // parse returns ExtractedContext: spanId is sender's spanId
+      expect(parsed).toBeDefined();
+      expect(parsed!.traceId).toBe(original.traceId);
+      expect(parsed!.spanId).toBe(original.spanId);
+    });
+
+    test('should inject and extract back to same values', () => {
+      const original: SpanContext = {
+        traceId: '0af7651916cd43dd8448eb211c80319c',
+        spanId: 'b7ad6b7169203331',
+        parentSpanId: 'a1b2c3d4e5f67890',
+      };
+
+      const carrier: Record<string, string> = {};
+      propagation.inject(carrier, original);
+      const extracted = propagation.extract(carrier);
+
+      // extract returns ExtractedContext (without spanId)
+      expect(extracted).toBeDefined();
+      expect(extracted!.traceId).toBe(original.traceId);
+      expect(extracted!.spanId).toBe(original.spanId); // injected uses spanId
+    });
+  });
+});