autotel 2.1.0

package/src/shutdown.test.ts

@@ -0,0 +1,311 @@
+/**
+ * Tests for graceful shutdown
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { flush, shutdown } from './shutdown';
+import { init } 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();
+  });
+
+  afterEach(async () => {
+    // Clean up after each test
+    const queue = getEventQueue();
+    if (queue) {
+      await queue.flush();
+    }
+  });
+
+  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 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();
+    });
+  });
+
+  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

@@ -0,0 +1,222 @@
+/**
+ * Graceful shutdown with flush and cleanup
+ */
+
+import { getSdk, getLogger } 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)
+ *
+ * @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 }): Promise<void> {
+  const timeout = options?.timeout ?? 2000;
+
+  const doFlush = async () => {
+    // Flush events queue
+    const eventsQueue = getEventQueue();
+    if (eventsQueue) {
+      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(
+      '[autotel] Flush error:',
+      error instanceof Error ? error : new Error(String(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, but continue with cleanup even if it fails
+  try {
+    await flush();
+  } catch (error) {
+    const err = error instanceof Error ? error : new Error(String(error));
+    shutdownError = err;
+    logger.error(
+      '[autotel] Flush failed during shutdown, continuing cleanup',
+      err,
+    );
+  }
+
+  // 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('[autotel] SDK shutdown failed', err);
+    }
+  } finally {
+    // Clean up singleton Maps and queues to prevent memory leaks
+    // This runs even if SDK shutdown fails
+    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(
+          '[autotel] Error during shutdown',
+          error instanceof Error ? error : undefined,
+        );
+      } finally {
+        process.exit(0);
+      }
+    });
+  }
+}
+
+// Auto-register shutdown hooks
+registerShutdownHooks();