@inversifyjs/http-instrumentation-core 5.8.0 → 5.9.0

package/eslint.config.mjs

@@ -1,23 +0,0 @@
-import { buildDefaultConfig } from '@inversifyjs/foundation-eslint-config';
-
-import plugin from '@inversifyjs/eslint-plugin-require-extensions';
-
-export default [
-  ...buildDefaultConfig(
-    {
-      '@typescript-eslint/consistent-type-imports': [
-        'error',
-        {
-          disallowTypeAnnotations: true,
-          fixStyle: 'inline-type-imports',
-          prefer: 'type-imports',
-        },
-      ],
-      'require-extensions/require-extensions': 'error',
-      'require-extensions/require-index': 'error',
-    },
-    {
-      'require-extensions': plugin,
-    },
-  ),
-];

package/prettier.config.mjs

@@ -1,3 +0,0 @@
-import config from '@inversifyjs/foundation-prettier-config';
-
-export default config;

package/src/actions/emitHttpInstrumentationEvent.spec.ts

@@ -1,130 +0,0 @@
-import {
-  afterAll,
-  beforeAll,
-  describe,
-  expect,
-  it,
-  type Mock,
-  vitest,
-} from 'vitest';
-
-import { type EventSink } from '../models/EventSink.js';
-import { type HttpInstrumentationEvent } from '../models/HttpInstrumentationEvent.js';
-import { emitHttpInstrumentationEvent } from './emitHttpInstrumentationEvent.js';
-
-describe(emitHttpInstrumentationEvent, () => {
-  describe('having three sinks and a middle sink that throws', () => {
-    let events: HttpInstrumentationEvent[];
-    let reportSinkError: Mock<(error: unknown) => void>;
-    let eventFixture: HttpInstrumentationEvent;
-
-    beforeAll(() => {
-      events = [];
-      reportSinkError = vitest.fn<(error: unknown) => void>();
-      eventFixture = {
-        executionId: 'execution-1',
-        headers: {},
-        method: 'GET',
-        requestId: 'request-1',
-        timestamp: 1,
-        type: 'http.request.started',
-        url: '/orders',
-      };
-
-      const sinks: EventSink<HttpInstrumentationEvent>[] = [
-        {
-          emit: (event: HttpInstrumentationEvent): void => {
-            events.push(event);
-          },
-        },
-        {
-          emit: (): void => {
-            throw new Error('sink failed');
-          },
-        },
-        {
-          emit: (event: HttpInstrumentationEvent): void => {
-            events.push(event);
-          },
-        },
-      ];
-
-      emitHttpInstrumentationEvent(sinks, eventFixture, reportSinkError);
-    });
-
-    afterAll(() => {
-      vitest.clearAllMocks();
-    });
-
-    it('should deliver the event to the sinks that do not throw', () => {
-      expect(events).toStrictEqual([eventFixture, eventFixture]);
-    });
-
-    it('should freeze the event', () => {
-      expect(Object.isFrozen(eventFixture)).toBe(true);
-    });
-
-    it('should report the sink failure', () => {
-      expect(reportSinkError).toHaveBeenCalledExactlyOnceWith(
-        expect.any(Error),
-      );
-    });
-  });
-
-  describe('having a sink that returns a rejected promise', () => {
-    let events: HttpInstrumentationEvent[];
-    let reportSinkError: Mock<(error: unknown) => void>;
-    let eventFixture: HttpInstrumentationEvent;
-    let sinkError: Error;
-
-    beforeAll(async () => {
-      events = [];
-      reportSinkError = vitest.fn<(error: unknown) => void>();
-      sinkError = new Error('async sink');
-      eventFixture = {
-        executionId: 'execution-1',
-        headers: {},
-        method: 'GET',
-        requestId: 'request-1',
-        timestamp: 1,
-        type: 'http.request.started',
-        url: '/orders',
-      };
-
-      const fulfilledSink: {
-        emit: (event: HttpInstrumentationEvent) => Promise<void>;
-      } = {
-        emit: async (event: HttpInstrumentationEvent): Promise<void> => {
-          events.push(event);
-        },
-      };
-      const rejectedSink: { emit: () => Promise<void> } = {
-        emit: async (): Promise<void> => Promise.reject(sinkError),
-      };
-      const sinks: EventSink<HttpInstrumentationEvent>[] = [
-        fulfilledSink,
-        rejectedSink,
-        {
-          emit: (event: HttpInstrumentationEvent): void => {
-            events.push(event);
-          },
-        },
-      ];
-
-      emitHttpInstrumentationEvent(sinks, eventFixture, reportSinkError);
-      await Promise.resolve();
-    });
-
-    afterAll(() => {
-      vitest.clearAllMocks();
-    });
-
-    it('should deliver the event to the other sinks', () => {
-      expect(events).toStrictEqual([eventFixture, eventFixture]);
-    });
-
-    it('should report the rejection', () => {
-      expect(reportSinkError).toHaveBeenCalledExactlyOnceWith(sinkError);
-    });
-  });
-});

package/src/actions/emitHttpInstrumentationEvent.ts

@@ -1,28 +0,0 @@
-import { isPromise } from '@inversifyjs/common';
-
-import { type EventSink } from '../models/EventSink.js';
-import { type HttpInstrumentationEvent } from '../models/HttpInstrumentationEvent.js';
-
-export function emitHttpInstrumentationEvent(
-  sinks: readonly EventSink<HttpInstrumentationEvent>[],
-  event: HttpInstrumentationEvent,
-  reportSinkError: (error: unknown) => void,
-): void {
-  const publishedEvent: HttpInstrumentationEvent = Object.freeze(event);
-
-  for (const sink of sinks) {
-    try {
-      // EventSink.emit is typed as void, and an async implementation still type-checks.
-      // eslint-disable-next-line @typescript-eslint/no-confusing-void-expression
-      const result: unknown = sink.emit(publishedEvent);
-
-      if (isPromise(result)) {
-        void result.then(undefined, (error: unknown): void => {
-          reportSinkError(error);
-        });
-      }
-    } catch (error: unknown) {
-      reportSinkError(error);
-    }
-  }
-}

package/src/actions/httpInstrumentationState.spec.ts

@@ -1,49 +0,0 @@
-import { describe, expect, it } from 'vitest';
-
-import { type HttpInstrumentationScope } from '../models/HttpInstrumentationScope.js';
-import {
-  closeHttpInstrumentationScope,
-  initializeHttpInstrumentationRequest,
-  openHttpInstrumentationScope,
-} from './httpInstrumentationState.js';
-
-describe(openHttpInstrumentationScope, () => {
-  describe('having a request with a nested execution', () => {
-    describe('when called', () => {
-      it('should parent the inner scope to the outer execution', () => {
-        const request: object = {};
-
-        initializeHttpInstrumentationRequest(request, 'request-1');
-
-        const outer: HttpInstrumentationScope = openHttpInstrumentationScope(
-          request,
-          'execution-outer',
-        );
-        const inner: HttpInstrumentationScope = openHttpInstrumentationScope(
-          request,
-          'execution-inner',
-        );
-
-        expect(outer).toStrictEqual({
-          executionId: 'execution-outer',
-          parentExecutionId: undefined,
-          requestId: 'request-1',
-        });
-        expect(inner).toStrictEqual({
-          executionId: 'execution-inner',
-          parentExecutionId: 'execution-outer',
-          requestId: 'request-1',
-        });
-
-        closeHttpInstrumentationScope(request, inner.executionId);
-
-        const sibling: HttpInstrumentationScope = openHttpInstrumentationScope(
-          request,
-          'execution-sibling',
-        );
-
-        expect(sibling.parentExecutionId).toBe('execution-outer');
-      });
-    });
-  });
-});

package/src/actions/httpInstrumentationState.ts

@@ -1,93 +0,0 @@
-import { randomUUID } from 'node:crypto';
-
-import { type HttpInstrumentationScope } from '../models/HttpInstrumentationScope.js';
-import {
-  type HttpInstrumentationState,
-  httpInstrumentationStateSymbol,
-} from '../models/httpInstrumentationStateSymbol.js';
-
-interface HttpInstrumentationStateCarrier {
-  [httpInstrumentationStateSymbol]?: HttpInstrumentationState | undefined;
-}
-
-export function initializeHttpInstrumentationRequest(
-  request: object,
-  requestId: string,
-): void {
-  const carrier: HttpInstrumentationStateCarrier = request;
-
-  if (carrier[httpInstrumentationStateSymbol] !== undefined) {
-    return;
-  }
-
-  carrier[httpInstrumentationStateSymbol] = {
-    executionStack: [],
-    requestId,
-  };
-}
-
-export function openHttpInstrumentationScope(
-  request: object,
-  executionId: string,
-): HttpInstrumentationScope {
-  const state: HttpInstrumentationState =
-    getOrCreateHttpInstrumentationState(request);
-  const parentExecutionId: string | undefined = state.executionStack.at(-1);
-
-  state.executionStack.push(executionId);
-
-  return {
-    executionId,
-    parentExecutionId,
-    requestId: state.requestId,
-  };
-}
-
-export function closeHttpInstrumentationScope(
-  request: object,
-  executionId: string,
-): void {
-  const state: HttpInstrumentationState | undefined =
-    readHttpInstrumentationState(request);
-
-  if (state === undefined) {
-    return;
-  }
-
-  const executionIndex: number = state.executionStack.lastIndexOf(executionId);
-
-  if (executionIndex === -1) {
-    return;
-  }
-
-  state.executionStack.splice(executionIndex, 1);
-}
-
-function getOrCreateHttpInstrumentationState(
-  request: object,
-): HttpInstrumentationState {
-  const carrier: HttpInstrumentationStateCarrier = request;
-  const state: HttpInstrumentationState | undefined =
-    carrier[httpInstrumentationStateSymbol];
-
-  if (state !== undefined) {
-    return state;
-  }
-
-  const createdState: HttpInstrumentationState = {
-    executionStack: [],
-    requestId: randomUUID(),
-  };
-
-  carrier[httpInstrumentationStateSymbol] = createdState;
-
-  return createdState;
-}
-
-function readHttpInstrumentationState(
-  request: object,
-): HttpInstrumentationState | undefined {
-  return (request as HttpInstrumentationStateCarrier)[
-    httpInstrumentationStateSymbol
-  ];
-}

package/src/actions/markHttpInstrumentedHandler.ts

@@ -1,16 +0,0 @@
-import { httpInstrumentedHandlerSymbol } from '../models/httpInstrumentedHandlerSymbol.js';
-
-export function markHttpInstrumentedHandler(handler: object): void {
-  Object.defineProperty(handler, httpInstrumentedHandlerSymbol, {
-    configurable: false,
-    enumerable: false,
-    value: true,
-    writable: false,
-  });
-}
-
-export function isHttpInstrumentedHandler(handler: object): boolean {
-  const record: Record<symbol, unknown> = handler as Record<symbol, unknown>;
-
-  return record[httpInstrumentedHandlerSymbol] === true;
-}

package/src/actions/runInstrumentedHttpStage.ts

@@ -1,76 +0,0 @@
-import { randomUUID } from 'node:crypto';
-
-import { startHttpStage } from '../calculations/startHttpStage.js';
-import { type HttpInstrumentationContext } from '../models/HttpInstrumentationContext.js';
-import { type HttpInstrumentationEvent } from '../models/HttpInstrumentationEvent.js';
-import { type HttpInstrumentationScope } from '../models/HttpInstrumentationScope.js';
-import { type HttpStageClock } from '../models/HttpStageClock.js';
-import { emitHttpInstrumentationEvent } from './emitHttpInstrumentationEvent.js';
-import {
-  closeHttpInstrumentationScope,
-  openHttpInstrumentationScope,
-} from './httpInstrumentationState.js';
-
-export type HttpStageOutcome<TResult> =
-  | {
-      readonly error: unknown;
-    }
-  | {
-      readonly result: TResult;
-    };
-
-export async function runInstrumentedHttpStage<TResult>(
-  instrumentation: HttpInstrumentationContext,
-  request: object,
-  createStartedEvent: (
-    scope: HttpInstrumentationScope,
-    stage: HttpStageClock,
-  ) => HttpInstrumentationEvent,
-  operation: () => Promise<TResult>,
-  createExecutedEvent: (
-    scope: HttpInstrumentationScope,
-    stage: HttpStageClock,
-    outcome: HttpStageOutcome<TResult>,
-  ) => HttpInstrumentationEvent,
-  recover: (error: unknown) => Promise<TResult>,
-): Promise<TResult> {
-  const scope: HttpInstrumentationScope = openHttpInstrumentationScope(
-    request,
-    randomUUID(),
-  );
-  const stage: HttpStageClock = startHttpStage();
-
-  try {
-    emitHttpInstrumentationEvent(
-      instrumentation.sinks,
-      createStartedEvent(scope, stage),
-      instrumentation.reportSinkError,
-    );
-
-    try {
-      const result: TResult = await operation();
-
-      emitHttpInstrumentationEvent(
-        instrumentation.sinks,
-        createExecutedEvent(scope, stage, {
-          result,
-        }),
-        instrumentation.reportSinkError,
-      );
-
-      return result;
-    } catch (error: unknown) {
-      emitHttpInstrumentationEvent(
-        instrumentation.sinks,
-        createExecutedEvent(scope, stage, {
-          error,
-        }),
-        instrumentation.reportSinkError,
-      );
-
-      return await recover(error);
-    }
-  } finally {
-    closeHttpInstrumentationScope(request, scope.executionId);
-  }
-}

package/src/calculations/buildHttpInstrumentationContext.spec.ts

@@ -1,37 +0,0 @@
-import { describe, expect, it } from 'vitest';
-
-import { type EventSink } from '../models/EventSink.js';
-import { type HttpInstrumentationEvent } from '../models/HttpInstrumentationEvent.js';
-import { buildHttpInstrumentationContext } from './buildHttpInstrumentationContext.js';
-
-describe(buildHttpInstrumentationContext, () => {
-  describe('having no sinks', () => {
-    describe('when called', () => {
-      it('should leave instrumentation disabled', () => {
-        expect(
-          buildHttpInstrumentationContext(undefined, (): void => undefined),
-        ).toBeUndefined();
-        expect(
-          buildHttpInstrumentationContext([], (): void => undefined),
-        ).toBeUndefined();
-      });
-    });
-  });
-
-  describe('having sinks', () => {
-    describe('when called', () => {
-      it('should keep the sinks', () => {
-        const sink: EventSink<HttpInstrumentationEvent> = {
-          emit: (): void => undefined,
-        };
-
-        expect(
-          buildHttpInstrumentationContext([sink], (): void => undefined),
-        ).toStrictEqual({
-          reportSinkError: expect.any(Function),
-          sinks: [sink],
-        });
-      });
-    });
-  });
-});

package/src/calculations/buildHttpInstrumentationContext.ts

@@ -1,17 +0,0 @@
-import { type EventSink } from '../models/EventSink.js';
-import { type HttpInstrumentationContext } from '../models/HttpInstrumentationContext.js';
-import { type HttpInstrumentationEvent } from '../models/HttpInstrumentationEvent.js';
-
-export function buildHttpInstrumentationContext(
-  sinks: readonly EventSink<HttpInstrumentationEvent>[] | undefined,
-  reportSinkError: (error: unknown) => void,
-): HttpInstrumentationContext | undefined {
-  if (sinks === undefined || sinks.length === 0) {
-    return undefined;
-  }
-
-  return {
-    reportSinkError,
-    sinks,
-  };
-}

package/src/calculations/redactHttpHeaders.spec.ts

@@ -1,36 +0,0 @@
-import { describe, expect, it } from 'vitest';
-
-import { redactHttpHeaders } from './redactHttpHeaders.js';
-
-describe(redactHttpHeaders, () => {
-  describe('having credential headers', () => {
-    describe('when called', () => {
-      it('should redact credential headers and keep the others', () => {
-        const headers: Readonly<Record<string, string | readonly string[]>> =
-          redactHttpHeaders({
-            authorization: 'secret',
-            'content-length': 12,
-            cookie: 'session=1',
-            'proxy-authorization': 'basic secret',
-            'set-cookie': ['a=1', 'b=2'],
-            'x-api-key': 'key-1',
-            'x-auth-token': 'token-1',
-            'x-empty': undefined,
-            'x-request-id': 'req-1',
-          });
-
-        expect(Object.isFrozen(headers)).toBe(true);
-        expect(headers).toStrictEqual({
-          authorization: '[redacted]',
-          'content-length': '12',
-          cookie: '[redacted]',
-          'proxy-authorization': '[redacted]',
-          'set-cookie': '[redacted]',
-          'x-api-key': '[redacted]',
-          'x-auth-token': '[redacted]',
-          'x-request-id': 'req-1',
-        });
-      });
-    });
-  });
-});

package/src/calculations/redactHttpHeaders.ts

@@ -1,38 +0,0 @@
-const REDACTED_HEADER_VALUE: string = '[redacted]';
-
-const REDACTED_HTTP_HEADER_NAMES: ReadonlySet<string> = new Set([
-  'authorization',
-  'cookie',
-  'proxy-authorization',
-  'set-cookie',
-  'x-api-key',
-  'x-auth-token',
-]);
-
-export function redactHttpHeaders(
-  headers: Readonly<
-    Record<string, number | string | readonly string[] | undefined>
-  >,
-): Record<string, string | readonly string[]> {
-  const redactedHeaders: Record<string, string | readonly string[]> = {};
-
-  for (const key in headers) {
-    if (!Object.hasOwn(headers, key)) {
-      continue;
-    }
-
-    const value: number | string | readonly string[] | undefined = headers[key];
-
-    if (value === undefined) {
-      continue;
-    }
-
-    redactedHeaders[key] = REDACTED_HTTP_HEADER_NAMES.has(key.toLowerCase())
-      ? REDACTED_HEADER_VALUE
-      : typeof value === 'number'
-        ? value.toString()
-        : value;
-  }
-
-  return Object.freeze(redactedHeaders);
-}

package/src/calculations/startHttpStage.ts

@@ -1,12 +0,0 @@
-import { type HttpStageClock } from '../models/HttpStageClock.js';
-
-export function startHttpStage(): HttpStageClock {
-  return {
-    startedAt: Date.now(),
-    startTick: performance.now(),
-  };
-}
-
-export function readHttpStageDuration(stage: HttpStageClock): number {
-  return performance.now() - stage.startTick;
-}

package/src/index.ts

@@ -1,26 +0,0 @@
-export { emitHttpInstrumentationEvent } from './actions/emitHttpInstrumentationEvent.js';
-export {
-  closeHttpInstrumentationScope,
-  initializeHttpInstrumentationRequest,
-  openHttpInstrumentationScope,
-} from './actions/httpInstrumentationState.js';
-export {
-  isHttpInstrumentedHandler,
-  markHttpInstrumentedHandler,
-} from './actions/markHttpInstrumentedHandler.js';
-export {
-  type HttpStageOutcome,
-  runInstrumentedHttpStage,
-} from './actions/runInstrumentedHttpStage.js';
-export { buildHttpInstrumentationContext } from './calculations/buildHttpInstrumentationContext.js';
-export { redactHttpHeaders } from './calculations/redactHttpHeaders.js';
-export {
-  readHttpStageDuration,
-  startHttpStage,
-} from './calculations/startHttpStage.js';
-export { type EventSink } from './models/EventSink.js';
-export { type HttpInstrumentationContext } from './models/HttpInstrumentationContext.js';
-export { type HttpInstrumentationEvent } from './models/HttpInstrumentationEvent.js';
-export { type HttpInstrumentationScope } from './models/HttpInstrumentationScope.js';
-export { httpInstrumentedHandlerSymbol } from './models/httpInstrumentedHandlerSymbol.js';
-export { type HttpStageClock } from './models/HttpStageClock.js';

package/src/models/EventSink.ts

@@ -1,3 +0,0 @@
-export interface EventSink<TEvent> {
-  emit(event: TEvent): void;
-}

package/src/models/HttpInstrumentationContext.ts

@@ -1,7 +0,0 @@
-import { type EventSink } from './EventSink.js';
-import { type HttpInstrumentationEvent } from './HttpInstrumentationEvent.js';
-
-export interface HttpInstrumentationContext {
-  readonly reportSinkError: (error: unknown) => void;
-  readonly sinks: readonly EventSink<HttpInstrumentationEvent>[];
-}