autotel-tanstack 1.13.35 → 1.13.36

package/src/testing.ts

@@ -1,430 +0,0 @@
-import { type ReadableSpan } from '@opentelemetry/sdk-trace-base';
-import { InMemorySpanExporter } from 'autotel/exporters';
-import { SimpleSpanProcessor } from 'autotel/processors';
-import { init } from 'autotel';
-
-/**
- * Test harness for TanStack instrumentation testing
- *
- * Provides utilities for testing TanStack Start applications
- * with autotel-tanstack instrumentation.
- */
-export interface TestHarness {
-  /**
-   * The in-memory span exporter
-   */
-  exporter: {
-    getFinishedSpans(): ReadableSpan[];
-    reset(): void;
-  };
-
-  /**
-   * Get all finished spans
-   */
-  getSpans(): ReadableSpan[];
-
-  /**
-   * Get spans by name (exact match or regex)
-   */
-  getSpansByName(name: string | RegExp): ReadableSpan[];
-
-  /**
-   * Get spans by TanStack type
-   */
-  getSpansByType(
-    type: 'request' | 'serverFn' | 'loader' | 'beforeLoad',
-  ): ReadableSpan[];
-
-  /**
-   * Reset collected spans
-   */
-  reset(): void;
-
-  /**
-   * Assert a span exists
-   */
-  assertSpanExists(name: string | RegExp): void;
-
-  /**
-   * Assert a span has a specific attribute
-   */
-  assertSpanHasAttribute(
-    name: string | RegExp,
-    attr: string,
-    value?: unknown,
-  ): void;
-
-  /**
-   * Assert a server function was traced
-   */
-  assertServerFnTraced(name: string): void;
-
-  /**
-   * Assert a loader was traced
-   */
-  assertLoaderTraced(routeId: string): void;
-
-  /**
-   * Assert a beforeLoad was traced
-   */
-  assertBeforeLoadTraced(routeId: string): void;
-
-  /**
-   * Assert an HTTP request was traced
-   */
-  assertRequestTraced(method: string, path: string): void;
-}
-
-/**
- * Create a test harness for TanStack instrumentation testing
- *
- * This sets up autotel with an in-memory exporter for testing.
- * Call this in your test setup to capture and assert on spans.
- *
- * @returns Test harness with assertion helpers
- *
- * @example
- * ```typescript
- * import { describe, it, beforeEach } from 'vitest';
- * import { createTestHarness } from 'autotel-tanstack/testing';
- *
- * describe('MyServerFunction', () => {
- *   let harness: ReturnType<typeof createTestHarness>;
- *
- *   beforeEach(() => {
- *     harness = createTestHarness();
- *   });
- *
- *   afterEach(() => {
- *     harness.reset();
- *   });
- *
- *   it('should trace the server function', async () => {
- *     await myServerFunction({ id: '123' });
- *
- *     harness.assertServerFnTraced('myServerFunction');
- *     harness.assertSpanHasAttribute(
- *       /tanstack\.serverFn/,
- *       'tanstack.server_function.name',
- *       'myServerFunction'
- *     );
- *   });
- * });
- * ```
- */
-export function createTestHarness(): TestHarness {
-  const exporter = new InMemorySpanExporter();
-
-  init({
-    service: 'test',
-    spanProcessors: [new SimpleSpanProcessor(exporter)],
-  });
-
-  function getSpans(): ReadableSpan[] {
-    return exporter.getFinishedSpans() as ReadableSpan[];
-  }
-
-  function getSpansByName(name: string | RegExp): ReadableSpan[] {
-    const spans = getSpans();
-    if (typeof name === 'string') {
-      return spans.filter((s) => s.name === name);
-    }
-    return spans.filter((s) => name.test(s.name));
-  }
-
-  function getSpansByType(
-    type: 'request' | 'serverFn' | 'loader' | 'beforeLoad',
-  ): ReadableSpan[] {
-    return getSpans().filter((s) => s.attributes['tanstack.type'] === type);
-  }
-
-  function reset(): void {
-    exporter.reset();
-  }
-
-  function assertSpanExists(name: string | RegExp): void {
-    const spans = getSpansByName(name);
-    if (spans.length === 0) {
-      const allSpanNames = getSpans().map((s) => s.name);
-      throw new Error(
-        `Expected span "${name}" to exist. Found spans: ${JSON.stringify(allSpanNames)}`,
-      );
-    }
-  }
-
-  function assertSpanHasAttribute(
-    name: string | RegExp,
-    attr: string,
-    value?: unknown,
-  ): void {
-    const spans = getSpansByName(name);
-    if (spans.length === 0) {
-      throw new Error(`Span "${name}" not found`);
-    }
-
-    const span = spans[0];
-    const attrValue = span.attributes[attr];
-
-    if (attrValue === undefined) {
-      throw new Error(
-        `Attribute "${attr}" not found on span "${span.name}". ` +
-          `Available attributes: ${JSON.stringify(Object.keys(span.attributes))}`,
-      );
-    }
-
-    if (value !== undefined && attrValue !== value) {
-      throw new Error(
-        `Expected attribute "${attr}" to be "${value}", got "${attrValue}"`,
-      );
-    }
-  }
-
-  function assertServerFnTraced(name: string): void {
-    assertSpanExists(`tanstack.serverFn.${name}`);
-  }
-
-  function assertLoaderTraced(routeId: string): void {
-    assertSpanExists(`tanstack.loader.${routeId}`);
-  }
-
-  function assertBeforeLoadTraced(routeId: string): void {
-    assertSpanExists(`tanstack.beforeLoad.${routeId}`);
-  }
-
-  function assertRequestTraced(method: string, path: string): void {
-    assertSpanExists(`${method} ${path}`);
-  }
-
-  return {
-    exporter,
-    getSpans,
-    getSpansByName,
-    getSpansByType,
-    reset,
-    assertSpanExists,
-    assertSpanHasAttribute,
-    assertServerFnTraced,
-    assertLoaderTraced,
-    assertBeforeLoadTraced,
-    assertRequestTraced,
-  };
-}
-
-/**
- * Mock request factory for testing
- *
- * Creates mock Request objects for testing middleware and handlers.
- *
- * @example
- * ```typescript
- * const request = createMockRequest('GET', '/api/users', {
- *   headers: { 'x-request-id': 'test-123' },
- * });
- * ```
- */
-export function createMockRequest(
-  method: string,
-  path: string,
-  options: {
-    headers?: Record<string, string>;
-    body?: string;
-    traceparent?: string;
-  } = {},
-): Request {
-  const headers = new Headers(options.headers);
-
-  if (options.traceparent) {
-    headers.set('traceparent', options.traceparent);
-  }
-
-  return new Request(`http://localhost${path}`, {
-    method,
-    headers,
-    body: options.body,
-  });
-}
-
-/**
- * Generate a valid W3C traceparent header for testing
- *
- * @param traceId - Optional 32-char hex trace ID
- * @param spanId - Optional 16-char hex span ID
- * @returns Valid traceparent header string
- *
- * @example
- * ```typescript
- * const traceparent = generateTraceparent();
- * const request = createMockRequest('GET', '/api/users', { traceparent });
- * ```
- */
-export function generateTraceparent(traceId?: string, spanId?: string): string {
-  const version = '00';
-  const trace = traceId || generateHex(32);
-  const span = spanId || generateHex(16);
-  const flags = '01'; // Sampled
-
-  return `${version}-${trace}-${span}-${flags}`;
-}
-
-function generateHex(length: number): string {
-  const chars = '0123456789abcdef';
-  let result = '';
-  for (let i = 0; i < length; i++) {
-    result += chars[Math.floor(Math.random() * 16)];
-  }
-  return result;
-}
-
-/**
- * Serialized span shape returned by the test-spans HTTP endpoint.
- * Mirrors the fields the Playwright side needs for assertions.
- *
- * Defined as a `type` (not `interface`) so it is assignable to
- * `Record<string, unknown>` in TypeScript 6+ strict mode.
- */
-export type SerializedSpan = {
-  name: string;
-  spanId: string;
-  traceId: string;
-  parentSpanId?: string;
-  attributes?: Record<string, unknown>;
-  status: { code: number; message?: string };
-  durationMs: number;
-};
-
-interface TestSpanExporter {
-  getFinishedSpans(): Array<{
-    name: string;
-    spanContext(): { spanId: string; traceId: string };
-    parentSpanContext?: { spanId: string };
-    attributes: Record<string, unknown>;
-    status: { code: number; message?: string };
-    duration: [number, number];
-  }>;
-  reset(): void;
-}
-
-function getExporter(): TestSpanExporter | undefined {
-  return (globalThis as Record<string, unknown>).__testSpanExporter as
-    | TestSpanExporter
-    | undefined;
-}
-
-function e2eGuard(): Response | null {
-  if (process.env.E2E !== '1') {
-    return Response.json(
-      { error: 'test-spans endpoint only available in E2E mode' },
-      { status: 404 },
-    );
-  }
-  return null;
-}
-
-function exporterGuard(): Response | null {
-  if (!getExporter()) {
-    return Response.json(
-      { error: 'in-memory span exporter not initialized' },
-      { status: 500 },
-    );
-  }
-  return null;
-}
-
-/**
- * Accepts either a raw `Request` (legacy) or a TanStack Router context
- * object containing `{ request: Request }` (Router 1.168+).
- */
-type HandlerInput = Request | { request: Request };
-
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-type CreateFileRoute = (path: string) => (options: any) => any;
-
-/**
- * Creates GET and DELETE handlers for a test-spans HTTP endpoint.
- *
- * Use in a TanStack Start route to expose in-memory spans for Playwright assertions.
- * Only works when E2E=1 (set in webServer command).
- *
- * Handlers accept either a raw `Request` or a TanStack Router context
- * object `{ request: Request }`, so they work with both Router < 1.168
- * and Router >= 1.168.
- *
- * @example
- * ```typescript
- * // src/routes/api/test-spans.ts
- * import { createFileRoute } from "@tanstack/react-router";
- * import { createTestSpansHandlers } from 'autotel-tanstack/testing';
- * const { GET, DELETE } = createTestSpansHandlers();
- * export const Route = createFileRoute('/api/test-spans')({
- *   server: { handlers: { GET, DELETE } },
- * });
- * ```
- */
-/**
- * Creates a pre-built TanStack Start route for the test-spans endpoint.
- *
- * Reduces E2E boilerplate to three lines. The handlers accept both
- * `Request` and `{ request: Request }` so they work with any Router version.
- *
- * @param createFileRoute - Pass `createFileRoute` from `@tanstack/react-router`
- * @param path - Route path (default: `/api/test-spans`)
- *
- * @example
- * ```typescript
- * // src/routes/api/test-spans.ts
- * import { createFileRoute } from "@tanstack/react-router";
- * import { createTestSpansRoute } from "autotel-tanstack/testing";
- *
- * export const Route = createTestSpansRoute(createFileRoute);
- * ```
- */
-export function createTestSpansRoute(
-  createFileRoute: CreateFileRoute,
-  path = '/api/test-spans',
-) {
-  const { GET, DELETE } = createTestSpansHandlers();
-  return createFileRoute(path)({
-    server: {
-      handlers: { GET, DELETE },
-    },
-  });
-}
-
-export function createTestSpansHandlers(): {
-  GET: (input: HandlerInput) => Response;
-  DELETE: (input: HandlerInput) => Response;
-} {
-  return {
-    GET(_input: HandlerInput): Response {
-      const guard = e2eGuard() ?? exporterGuard();
-      if (guard) return guard;
-
-      const spans: SerializedSpan[] = getExporter()!
-        .getFinishedSpans()
-        .map((span) => {
-          const { spanId, traceId } = span.spanContext();
-          const serialized: SerializedSpan = {
-            name: span.name,
-            spanId,
-            traceId,
-            attributes: span.attributes,
-            status: span.status,
-            durationMs: span.duration[0] * 1000 + span.duration[1] / 1_000_000,
-          };
-          if (span.parentSpanContext?.spanId) {
-            serialized.parentSpanId = span.parentSpanContext.spanId;
-          }
-          return serialized;
-        });
-
-      return Response.json({ spans });
-    },
-
-    DELETE(_input: HandlerInput): Response {
-      const guard = e2eGuard() ?? exporterGuard();
-      if (guard) return guard;
-      getExporter()!.reset();
-      return Response.json({ ok: true });
-    },
-  };
-}

package/src/types.test.ts

@@ -1,46 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { DEFAULT_CONFIG, SPAN_ATTRIBUTES } from './types';
-
-describe('types', () => {
-  describe('DEFAULT_CONFIG', () => {
-    it('should have sensible defaults', () => {
-      expect(DEFAULT_CONFIG.captureArgs).toBe(true);
-      expect(DEFAULT_CONFIG.captureResults).toBe(false);
-      expect(DEFAULT_CONFIG.captureErrors).toBe(true);
-      expect(DEFAULT_CONFIG.sampling).toBe('adaptive');
-    });
-
-    it('should capture x-request-id by default', () => {
-      expect(DEFAULT_CONFIG.captureHeaders).toContain('x-request-id');
-    });
-
-    it('should not exclude any paths by default', () => {
-      expect(DEFAULT_CONFIG.excludePaths).toEqual([]);
-    });
-  });
-
-  describe('SPAN_ATTRIBUTES', () => {
-    it('should have HTTP semantic convention attributes', () => {
-      expect(SPAN_ATTRIBUTES.HTTP_REQUEST_METHOD).toBe('http.request.method');
-      expect(SPAN_ATTRIBUTES.HTTP_RESPONSE_STATUS_CODE).toBe(
-        'http.response.status_code',
-      );
-      expect(SPAN_ATTRIBUTES.URL_PATH).toBe('url.path');
-    });
-
-    it('should have RPC semantic convention attributes', () => {
-      expect(SPAN_ATTRIBUTES.RPC_SYSTEM).toBe('rpc.system');
-      expect(SPAN_ATTRIBUTES.RPC_METHOD).toBe('rpc.method');
-    });
-
-    it('should have TanStack-specific attributes', () => {
-      expect(SPAN_ATTRIBUTES.TANSTACK_TYPE).toBe('tanstack.type');
-      expect(SPAN_ATTRIBUTES.TANSTACK_SERVER_FN_NAME).toBe(
-        'tanstack.server_function.name',
-      );
-      expect(SPAN_ATTRIBUTES.TANSTACK_LOADER_ROUTE_ID).toBe(
-        'tanstack.loader.route_id',
-      );
-    });
-  });
-});

package/src/types.ts

@@ -1,182 +0,0 @@
-import type { Attributes } from '@opentelemetry/api';
-
-/**
- * Configuration options for TanStack Start instrumentation
- */
-export interface TanStackInstrumentationConfig {
-  /**
-   * Service name for spans
-   * @default process.env.OTEL_SERVICE_NAME || 'tanstack-start'
-   */
-  service?: string;
-
-  /**
-   * Whether to capture function arguments as span attributes
-   * Warning: May contain PII, review before enabling in production
-   * @default true
-   */
-  captureArgs?: boolean;
-
-  /**
-   * Whether to capture function results as span attributes
-   * Warning: May contain PII, disable in production
-   * @default false
-   */
-  captureResults?: boolean;
-
-  /**
-   * Whether to capture errors and record exceptions
-   * @default true
-   */
-  captureErrors?: boolean;
-
-  /**
-   * HTTP headers to capture as span attributes
-   * @default ['x-request-id']
-   */
-  captureHeaders?: string[];
-
-  /**
-   * URL paths to exclude from tracing (glob patterns)
-   * @default []
-   */
-  excludePaths?: (string | RegExp)[];
-
-  /**
-   * Sampling strategy
-   * - 'always': Sample all requests (100%)
-   * - 'adaptive': Use autotel's adaptive sampling (errors + slow = 100%, baseline 10%)
-   * - 'never': Disable sampling (for testing/debugging)
-   * @default 'adaptive'
-   */
-  sampling?: 'always' | 'adaptive' | 'never';
-
-  /**
-   * Custom function to extract additional span attributes
-   */
-  customAttributes?: (context: {
-    type: 'request' | 'serverFn' | 'loader' | 'beforeLoad' | 'middleware';
-    name: string;
-    request?: Request;
-    args?: unknown;
-    result?: unknown;
-  }) => Attributes;
-}
-
-/**
- * Configuration specific to tracing middleware
- */
-export interface TracingMiddlewareConfig extends TanStackInstrumentationConfig {
-  /**
-   * Type of middleware
-   * - 'request': For global request middleware (routes, SSR)
-   * - 'function': For server function middleware
-   * @default 'request'
-   */
-  type?: 'request' | 'function';
-}
-
-/**
- * Configuration for server function tracing
- */
-export interface TraceServerFnConfig {
-  /**
-   * Explicit name for the span
-   * If not provided, will attempt to infer from function name
-   */
-  name?: string;
-
-  /**
-   * Whether to capture function arguments
-   * @default true
-   */
-  captureArgs?: boolean;
-
-  /**
-   * Whether to capture function results
-   * @default false
-   */
-  captureResults?: boolean;
-}
-
-/**
- * Configuration for loader tracing
- */
-export interface TraceLoaderConfig {
-  /**
-   * Explicit name for the span
-   * If not provided, will use route ID
-   */
-  name?: string;
-
-  /**
-   * Whether to capture route params
-   * @default true
-   */
-  captureParams?: boolean;
-
-  /**
-   * Whether to capture loader result
-   * @default false
-   */
-  captureResult?: boolean;
-}
-
-/**
- * Configuration for handler wrapper
- */
-export interface WrapStartHandlerConfig extends TanStackInstrumentationConfig {
-  /**
-   * OTLP endpoint URL
-   * @default process.env.OTEL_EXPORTER_OTLP_ENDPOINT
-   */
-  endpoint?: string;
-
-  /**
-   * OTLP headers (e.g., for authentication)
-   * @default parsed from process.env.OTEL_EXPORTER_OTLP_HEADERS
-   */
-  headers?: Record<string, string>;
-}
-
-/**
- * Default configuration values
- */
-export const DEFAULT_CONFIG: Required<
-  Omit<TanStackInstrumentationConfig, 'customAttributes' | 'service'>
-> = {
-  captureArgs: true,
-  captureResults: false,
-  captureErrors: true,
-  captureHeaders: ['x-request-id'],
-  excludePaths: [],
-  sampling: 'adaptive',
-};
-
-/**
- * Span attribute keys following OpenTelemetry semantic conventions
- */
-export const SPAN_ATTRIBUTES = {
-  // HTTP semantic conventions
-  HTTP_REQUEST_METHOD: 'http.request.method',
-  HTTP_RESPONSE_STATUS_CODE: 'http.response.status_code',
-  URL_PATH: 'url.path',
-  URL_QUERY: 'url.query',
-  URL_FULL: 'url.full',
-
-  // RPC semantic conventions (for server functions)
-  RPC_SYSTEM: 'rpc.system',
-  RPC_METHOD: 'rpc.method',
-
-  // TanStack-specific attributes
-  TANSTACK_TYPE: 'tanstack.type',
-  TANSTACK_SERVER_FN_NAME: 'tanstack.server_function.name',
-  TANSTACK_SERVER_FN_METHOD: 'tanstack.server_function.method',
-  TANSTACK_SERVER_FN_ARGS: 'tanstack.server_function.args',
-  TANSTACK_SERVER_FN_RESULT: 'tanstack.server_function.result',
-  TANSTACK_LOADER_ROUTE_ID: 'tanstack.loader.route_id',
-  TANSTACK_LOADER_TYPE: 'tanstack.loader.type',
-  TANSTACK_LOADER_PARAMS: 'tanstack.loader.params',
-  TANSTACK_MIDDLEWARE_NAME: 'tanstack.middleware.name',
-  TANSTACK_REQUEST_DURATION_MS: 'tanstack.request.duration_ms',
-} as const;