autotel 4.1.0 → 4.2.0

package/src/shutdown.test.ts

@@ -1,364 +0,0 @@
-/**
- * Tests for graceful shutdown
- */
-
-import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
-import { flush, shutdown } from './shutdown';
-import {
-  init,
-  _getEmbeddedDevtoolsCloseForTesting,
-  _resetOptionalRequireForTesting,
-  _setOptionalRequireForTesting,
-} from './init';
-import { track, getEventQueue } from './track';
-import { EventSubscriber } from './event-subscriber';
-
-// Mock adapter for testing
-class MockAdapter implements EventSubscriber {
-  name = 'mock-adapter';
-  public events: Array<{ name: string; attributes?: Record<string, unknown> }> =
-    [];
-  public shutdownCalled = false;
-
-  async trackEvent(
-    name: string,
-    attributes?: Record<string, unknown>,
-  ): Promise<void> {
-    this.events.push({ name, attributes });
-  }
-
-  async trackFunnelStep(): Promise<void> {}
-  async trackOutcome(): Promise<void> {}
-  async trackValue(): Promise<void> {}
-
-  async shutdown(): Promise<void> {
-    this.shutdownCalled = true;
-  }
-}
-
-describe('shutdown module', () => {
-  let mockAdapter: MockAdapter;
-
-  beforeEach(() => {
-    vi.clearAllMocks();
-    mockAdapter = new MockAdapter();
-    _resetOptionalRequireForTesting();
-  });
-
-  afterEach(async () => {
-    // Clean up after each test
-    const queue = getEventQueue();
-    if (queue) {
-      await queue.flush();
-    }
-    _resetOptionalRequireForTesting();
-  });
-
-  describe('flush()', () => {
-    it('should flush events queue', async () => {
-      // Initialize with adapter
-      init({
-        service: 'test-service',
-        subscribers: [mockAdapter],
-      });
-
-      // Track events
-      track('test.event1', { foo: 'bar' });
-      track('test.event2', { baz: 'qux' });
-
-      // Events should be in queue
-      const queue = getEventQueue();
-      expect(queue?.size()).toBeGreaterThan(0);
-
-      // Flush
-      await flush();
-
-      // Queue should be empty (all events sent)
-      expect(queue?.size()).toBe(0);
-    });
-
-    it('should be safe to call multiple times', async () => {
-      init({
-        service: 'test-service',
-        subscribers: [mockAdapter],
-      });
-
-      track('test.event', { data: 'value' });
-
-      await flush();
-      await flush();
-      await flush();
-
-      // Should not throw
-      expect(getEventQueue()?.size()).toBe(0);
-    });
-
-    it('should be no-op if no events queue initialized', async () => {
-      init({ service: 'test-service' }); // No adapters
-
-      await expect(flush()).resolves.toBeUndefined();
-    });
-
-    it('should flush OpenTelemetry spans', async () => {
-      // Mock tracer provider with forceFlush
-      const mockForceFlush = vi.fn();
-      const mockTracerProvider = {
-        forceFlush: mockForceFlush,
-      };
-      const mockSdk = {
-        getTracerProvider: () => mockTracerProvider,
-        shutdown: vi.fn(),
-        start: vi.fn(),
-      };
-
-      init({
-        service: 'test-service',
-        sdkFactory: () => mockSdk as any,
-        subscribers: [mockAdapter],
-      });
-
-      // Flush should call tracer provider's forceFlush
-      await flush();
-
-      expect(mockForceFlush).toHaveBeenCalledOnce();
-    });
-
-    it('should handle flush timeout', async () => {
-      // Mock tracer provider that hangs
-      const mockForceFlush = vi.fn().mockImplementation(
-        () =>
-          new Promise((resolve) => {
-            // Never resolves (simulates hanging)
-            setTimeout(resolve, 10_000);
-          }),
-      );
-      const mockTracerProvider = {
-        forceFlush: mockForceFlush,
-      };
-      const mockSdk = {
-        getTracerProvider: () => mockTracerProvider,
-        shutdown: vi.fn(),
-        start: vi.fn(),
-      };
-
-      init({
-        service: 'test-service',
-        sdkFactory: () => mockSdk as any,
-        subscribers: [mockAdapter],
-      });
-
-      // Flush should timeout and throw
-      await expect(flush({ timeout: 100 })).rejects.toThrow('Flush timeout');
-    });
-
-    it('should respect custom timeout', async () => {
-      const mockForceFlush = vi.fn();
-      const mockTracerProvider = {
-        forceFlush: mockForceFlush,
-      };
-      const mockSdk = {
-        getTracerProvider: () => mockTracerProvider,
-        shutdown: vi.fn(),
-        start: vi.fn(),
-      };
-
-      init({
-        service: 'test-service',
-        sdkFactory: () => mockSdk as any,
-      });
-
-      // Flush with custom timeout should work
-      await flush({ timeout: 5000 });
-
-      expect(mockForceFlush).toHaveBeenCalledOnce();
-    });
-
-    it('should handle SDK without forceFlush gracefully', async () => {
-      // Mock SDK without forceFlush method
-      const mockTracerProvider = {};
-      const mockSdk = {
-        getTracerProvider: () => mockTracerProvider,
-        shutdown: vi.fn(),
-        start: vi.fn(),
-      };
-
-      init({
-        service: 'test-service',
-        sdkFactory: () => mockSdk as any,
-      });
-
-      // Should not throw even if forceFlush doesn't exist
-      await expect(flush()).resolves.toBeUndefined();
-    });
-
-    it('should handle missing tracer provider gracefully', async () => {
-      // Mock SDK that returns null tracer provider
-      const mockSdk = {
-        getTracerProvider: () => null,
-        shutdown: vi.fn(),
-        start: vi.fn(),
-      };
-
-      init({
-        service: 'test-service',
-        sdkFactory: () => mockSdk as any,
-      });
-
-      // Should not throw
-      await expect(flush()).resolves.toBeUndefined();
-    });
-  });
-
-  describe('shutdown()', () => {
-    it('should flush and shutdown SDK', async () => {
-      init({
-        service: 'test-service',
-        subscribers: [mockAdapter],
-      });
-
-      track('test.event', { foo: 'bar' });
-
-      // Shutdown should flush queue and shutdown SDK
-      await shutdown();
-
-      // After shutdown, queue should be null (cleaned up to prevent memory leaks)
-      const queue = getEventQueue();
-      expect(queue).toBeNull();
-    });
-
-    it('should be safe to call multiple times', async () => {
-      init({
-        service: 'test-service',
-        subscribers: [mockAdapter],
-      });
-
-      await shutdown();
-      await shutdown(); // Should not throw
-      await shutdown();
-
-      expect(true).toBe(true); // Test passes if no errors
-    });
-
-    it('should flush before SDK shutdown', async () => {
-      init({
-        service: 'test-service',
-        subscribers: [mockAdapter],
-      });
-
-      track('test.event', { foo: 'bar' });
-
-      const queue = getEventQueue();
-      const queueSizeBefore = queue?.size() || 0;
-      expect(queueSizeBefore).toBeGreaterThan(0);
-
-      await shutdown();
-
-      // Queue should be empty after shutdown
-      const queueSizeAfter = queue?.size() || 0;
-      expect(queueSizeAfter).toBe(0);
-    });
-
-    it('should clean up event queue observables on shutdown', async () => {
-      init({
-        service: 'test-service',
-        subscribers: [mockAdapter],
-      });
-
-      track('test.event', { foo: 'bar' });
-
-      const queue = getEventQueue();
-      expect(queue).not.toBeNull();
-      if (!queue) return;
-
-      const cleanupSpy = vi.spyOn(queue, 'cleanup');
-
-      await shutdown();
-
-      expect(cleanupSpy).toHaveBeenCalledOnce();
-    });
-
-    it('should handle errors during shutdown gracefully', async () => {
-      const failingAdapter: EventSubscriber = {
-        name: 'failing-adapter',
-        trackEvent: vi.fn(),
-        trackFunnelStep: vi.fn(),
-        trackOutcome: vi.fn(),
-        trackValue: vi.fn(),
-        shutdown: vi.fn().mockRejectedValue(new Error('Shutdown failed')),
-      };
-
-      init({
-        service: 'test-service',
-        subscribers: [failingAdapter],
-      });
-
-      // Should not throw even if adapter shutdown fails
-      await expect(shutdown()).resolves.toBeUndefined();
-    });
-
-    it('should close embedded devtools during shutdown', async () => {
-      const close = vi.fn().mockResolvedValue(undefined);
-      _setOptionalRequireForTesting((id: string) => {
-        if (id === 'autotel-devtools') {
-          return {
-            createDevtools: () => ({
-              port: 4318,
-              close,
-            }),
-          } as any;
-        }
-        return undefined;
-      });
-
-      init({
-        service: 'test-service',
-        devtools: { embedded: true },
-      });
-
-      expect(_getEmbeddedDevtoolsCloseForTesting()).not.toBeNull();
-
-      await shutdown();
-
-      expect(close).toHaveBeenCalledOnce();
-      expect(_getEmbeddedDevtoolsCloseForTesting()).toBeNull();
-    });
-  });
-
-  describe('Integration', () => {
-    it('should properly shutdown in correct order', async () => {
-      init({
-        service: 'test-service',
-        subscribers: [mockAdapter],
-      });
-
-      track('user.signup', { userId: '123' });
-      track('order.completed', { orderId: '456' });
-
-      const queue = getEventQueue();
-      expect(queue?.size()).toBeGreaterThan(0);
-
-      // Shutdown should flush all pending events
-      await shutdown();
-
-      // Queue should be empty (all events flushed)
-      expect(queue?.size()).toBe(0);
-    });
-
-    it('should work with no events to flush', async () => {
-      init({
-        service: 'test-service',
-        subscribers: [mockAdapter],
-      });
-
-      // No events tracked
-      const queue = getEventQueue();
-      const queueSize = queue?.size() || 0;
-      expect(queueSize).toBe(0);
-
-      await shutdown();
-
-      // Should complete without error
-      expect(mockAdapter.events).toHaveLength(0);
-    });
-  });
-});

package/src/shutdown.ts

@@ -1,246 +0,0 @@
-/**
- * Graceful shutdown with flush and cleanup
- */
-
-import { getSdk, getLogger, _closeEmbeddedDevtools } from './init';
-import { getEventQueue, resetEventQueue } from './track';
-import { resetEvents } from './event';
-import { resetMetrics } from './metric';
-
-/**
- * Flush all pending telemetry
- *
- * Flushes both events events and OpenTelemetry spans to their destinations.
- * Includes timeout protection to prevent hanging in serverless environments.
- *
- * Safe to call multiple times.
- *
- * @param options - Optional configuration
- * @param options.timeout - Timeout in milliseconds (default: 2000ms)
- * @param options.forShutdown - If true, permanently disables the events queue after flush (used internally by shutdown())
- *
- * @example Manual flush in serverless
- * ```typescript
- * import { flush } from 'autotel';
- *
- * export const handler = async (event) => {
- *   // ... process event
- *   await flush(); // Flush before function returns
- *   return result;
- * };
- * ```
- *
- * @example With custom timeout
- * ```typescript
- * await flush({ timeout: 5000 }); // 5 second timeout
- * ```
- */
-export async function flush(options?: {
-  timeout?: number;
-  forShutdown?: boolean;
-}): Promise<void> {
-  const timeout = options?.timeout ?? 2000;
-  const forShutdown = options?.forShutdown ?? false;
-
-  const doFlush = async () => {
-    // Flush events queue (or shutdown queue when tearing down)
-    const eventsQueue = getEventQueue();
-    if (eventsQueue) {
-      if (forShutdown) {
-        await eventsQueue.shutdown();
-      } else {
-        await eventsQueue.flush();
-      }
-    }
-
-    // Flush OpenTelemetry spans
-    // This ensures spans are exported immediately, critical for serverless
-    const sdk = getSdk();
-    if (sdk) {
-      try {
-        // Type assertion needed as getTracerProvider is not in the public NodeSDK interface
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        const sdkAny = sdk as any;
-        if (typeof sdkAny.getTracerProvider === 'function') {
-          const tracerProvider = sdkAny.getTracerProvider();
-          if (
-            tracerProvider &&
-            typeof tracerProvider.forceFlush === 'function'
-          ) {
-            await tracerProvider.forceFlush();
-          }
-        }
-      } catch {
-        // Ignore errors when accessing tracer provider (may not be available in test mocks)
-      }
-    }
-  };
-
-  // Add timeout protection to prevent hanging
-  let timeoutHandle: NodeJS.Timeout | undefined;
-  try {
-    await Promise.race([
-      doFlush().finally(() => {
-        // Clear timeout as soon as flush completes
-        if (timeoutHandle) {
-          clearTimeout(timeoutHandle);
-        }
-      }),
-      new Promise<void>((_, reject) => {
-        timeoutHandle = setTimeout(
-          () => reject(new Error('Flush timeout')),
-          timeout,
-        );
-        // Use unref() to allow Node to exit if flush completes first
-        // This prevents the 2s delay in serverless when flush succeeds immediately
-        timeoutHandle.unref();
-      }),
-    ]);
-  } catch (error) {
-    // Clear timeout on error too
-    if (timeoutHandle) {
-      clearTimeout(timeoutHandle);
-    }
-    const logger = getLogger();
-    logger.error(
-      {
-        err: error instanceof Error ? error : new Error(String(error)),
-      },
-      '[autotel] Flush error',
-    );
-    throw error;
-  }
-}
-
-/**
- * Shutdown telemetry and cleanup resources
- *
- * - Flushes all pending data
- * - Shuts down OpenTelemetry SDK
- * - Cleans up resources
- *
- * Call this before process exit.
- *
- * Always performs cleanup even if flush fails, preventing resource leaks
- * in serverless handlers or tests.
- *
- * @example Express server
- * ```typescript
- * const server = app.listen(3000)
- *
- * process.on('SIGTERM', async () => {
- *   await server.close()
- *   await shutdown()
- *   process.exit(0)
- * })
- * ```
- */
-export async function shutdown(): Promise<void> {
-  const logger = getLogger();
-  let shutdownError: Error | null = null;
-
-  // Attempt to flush (with queue shutdown so new events are rejected), but continue with cleanup even if it fails
-  try {
-    await flush({ forShutdown: true });
-  } catch (error) {
-    const err = error instanceof Error ? error : new Error(String(error));
-    shutdownError = err;
-    logger.error(
-      {
-        err,
-      },
-      '[autotel] Flush failed during shutdown, continuing cleanup',
-    );
-  }
-
-  // Always shutdown SDK and clean up resources
-  try {
-    // Shutdown OpenTelemetry SDK
-    const sdk = getSdk();
-    if (sdk) {
-      await sdk.shutdown();
-    }
-  } catch (error) {
-    const err = error instanceof Error ? error : new Error(String(error));
-
-    // Ignore ECONNREFUSED errors - this happens when no OTLP endpoint was configured
-    // The SDK tries to flush exporters that don't exist, which is harmless
-    const isConnectionRefused =
-      typeof error === 'object' &&
-      error !== null &&
-      'code' in error &&
-      error.code === 'ECONNREFUSED';
-
-    if (!isConnectionRefused) {
-      // Only store/log non-connection errors
-      if (!shutdownError) {
-        shutdownError = err;
-      }
-      logger.error({ err }, '[autotel] SDK shutdown failed');
-    }
-  } finally {
-    await _closeEmbeddedDevtools();
-
-    // Clean up singleton Maps and queues to prevent memory leaks
-    // This runs even if SDK shutdown fails
-    const eventsQueue = getEventQueue();
-    if (eventsQueue && typeof eventsQueue.cleanup === 'function') {
-      eventsQueue.cleanup();
-    }
-    resetEvents();
-    resetMetrics();
-    resetEventQueue();
-  }
-
-  // Rethrow first error after cleanup completes
-  // This allows tests and CI to detect failures while still ensuring cleanup
-  if (shutdownError) {
-    throw shutdownError;
-  }
-}
-
-/**
- * Register automatic shutdown hooks for common signals
- *
- * Handles:
- * - SIGTERM (Docker/K8s graceful shutdown)
- * - SIGINT (Ctrl+C)
- *
- * @internal Called automatically on module load
- */
-function registerShutdownHooks(): void {
-  if (typeof process === 'undefined') return; // Not in Node.js
-
-  const signals: NodeJS.Signals[] = ['SIGTERM', 'SIGINT'];
-  let shuttingDown = false;
-
-  for (const signal of signals) {
-    process.on(signal, async () => {
-      if (shuttingDown) return; // Prevent double shutdown
-      shuttingDown = true;
-
-      if (process.env.NODE_ENV !== 'test') {
-        getLogger().info(
-          {},
-          `[autotel] Received ${signal}, flushing telemetry...`,
-        );
-      }
-
-      try {
-        await shutdown();
-      } catch (error) {
-        getLogger().error(
-          {
-            err: error instanceof Error ? error : undefined,
-          },
-          '[autotel] Error during shutdown',
-        );
-      } finally {
-        process.exit(0);
-      }
-    });
-  }
-}
-
-// Auto-register shutdown hooks
-registerShutdownHooks();