@openapi-typescript-infra/service 6.10.1 → 6.10.2

package/src/openapi.ts

@@ -1,184 +0,0 @@
-import path from 'path';
-
-import { merge } from 'moderndash';
-import * as OpenApiValidator from 'express-openapi-validator';
-import { OpenAPIFramework } from 'express-openapi-validator/dist/framework/index.js';
-import type { Handler, Request, RequestHandler } from 'express';
-
-import type { AnyServiceLocals, ServiceExpress, ServiceLocals } from './types.js';
-import { getNodeEnv, isProd, isStaging } from './env.js';
-import { getFilesInDir } from './express-app/modules.js';
-import type { ConfigurationSchema } from './config/schema.js';
-
-const notImplementedHandler: Handler = (req, res) => {
-  res.status(501).json({
-    code: 'NotImplemented',
-    domain: 'http',
-    message: 'This method is not yet implemented',
-  });
-};
-
-type OAPIOpts = Parameters<typeof OpenApiValidator.middleware>[0];
-
-function stripExtension(filename: string) {
-  return filename.slice(0, filename.lastIndexOf('.'));
-}
-
-export async function openApi<
-  SLocals extends AnyServiceLocals = ServiceLocals<ConfigurationSchema>,
->(
-  app: ServiceExpress<SLocals>,
-  rootDirectory: string,
-  codepath: string,
-  pattern: string,
-  openApiOptions?: Partial<OAPIOpts>,
-) {
-  const apiSpec = openApiOptions?.apiSpec
-    ? undefined
-    : path.resolve(rootDirectory, `./api/${app.locals.name}.yaml`);
-  if (apiSpec) {
-    app.locals.logger.debug({ apiSpec, codepath }, 'Serving OpenAPI');
-  } else if (openApiOptions?.apiSpec) {
-    app.locals.logger.debug({ codepath }, 'Serving OpenAPI');
-  }
-
-  const basePath = path.resolve(rootDirectory, `${codepath}/handlers`);
-  // Because of the weirdness of ESM/CJS interop, and the synchronous nature of
-  // the OpenAPI resolver, we need to preload all the modules we might need
-  const moduleFiles = await getFilesInDir(
-    pattern,
-    path.resolve(rootDirectory, `${codepath}/handlers`),
-  );
-  const preloadedModules = await Promise.all(
-    moduleFiles.map((file) => {
-      const fullPath = path.join(basePath, file);
-      return import(fullPath).catch((error) => {
-        if (isStaging() || isProd()) {
-          app.locals.logger.fatal(
-            { file: fullPath, message: error.message },
-            'Could not load potential API handler',
-          );
-          process.exit(1);
-        }
-        app.locals.logger.warn(
-          { file: fullPath, message: error.message },
-          'Could not load potential API handler',
-        );
-        return undefined;
-      });
-    }),
-  );
-  const modulesByPath = moduleFiles.reduce<Record<string, Record<string, unknown>>>(
-    (acc, file, index) => {
-      const m = preloadedModules[index];
-      if (m) {
-        acc[`/${stripExtension(file)}`] = m;
-      }
-      return acc;
-    },
-    {},
-  );
-
-  // This is nuts, but there are testing frameworks or some other things
-  // that seem to set window in Node. The OpenAPI infra will fail under that
-  // circumstance.
-  const _window = global.window;
-  if (_window) {
-    delete (global as { window: unknown }).window;
-  }
-
-  try {
-    app.locals.openApiSpecification = await new OpenAPIFramework({
-      apiDoc: (openApiOptions?.apiSpec ?? apiSpec) as string,
-    })
-      .initialize({ visitApi() {} })
-      .then((docs) => docs.apiDoc)
-      .catch((error) => {
-        app.locals.logger.error(error, 'Failed to parse and load OpenAPI spec');
-      });
-
-    const defaultOptions: OAPIOpts = {
-      apiSpec: app.locals.openApiSpecification,
-      // We force full dereferencing of the OpenAPI spec so that all `$ref` schemas are
-      // inlined before express-openapi-validator builds its request coercion rules.
-      // Without this, the coercer sees `schema: { $ref: ... }` for query parameters and
-      // cannot resolve the underlying type, so it falls back to treating the parameter
-      // as a potentially repeated value (i.e., an array). That causes AJV to reject
-      // valid requests with “should be array” errors. Dereferencing ensures the
-      // coercer sees the real primitive type/enum and stops misclassifying params.
-      //
-      // The one downside is that circular references are not supported, so if you
-      // need that, you need to be very careful with enums, and override this option.
-      //
-      // See https://github.com/cdimascio/express-openapi-validator/issues/1119
-      $refParser: {
-        mode: 'dereference',
-      },
-      ignoreUndocumented: true,
-      validateRequests: {
-        allowUnknownQueryParameters: true,
-        coerceTypes: 'array',
-      },
-      operationHandlers: {
-        basePath,
-        resolver(
-          basePath: string,
-          route: Parameters<typeof OpenApiValidator.resolvers.defaultResolver>[1],
-        ) {
-          const pathKey = route.openApiRoute.substring(route.basePath.length);
-          const modulePath = path.join(basePath, pathKey);
-
-          try {
-            const module = modulesByPath[pathKey];
-            const method = module
-              ? Object.keys(module).find((m) => m.toUpperCase() === route.method)
-              : undefined;
-            if (!module || !method) {
-              throw new Error(
-                `Could not find a [${route.method}] function in ${modulePath} when trying to route [${route.method} ${route.expressRoute}].`,
-              );
-            }
-            return module[method] as RequestHandler;
-          } catch (error) {
-            app.locals.logger.error(
-              {
-                error: (error as Error).message,
-                pathKey,
-                modulePath: path.relative(rootDirectory, modulePath),
-              },
-              'Failed to load API method handler',
-            );
-            return notImplementedHandler;
-          }
-        },
-      },
-    };
-
-    const { routing } = app.locals.config;
-    const combinedOptions = {
-      // In test mode, validate returned swagger responses. This can easily be disabled
-      // by setting validateResponses to false in the config.
-      ...(getNodeEnv() === 'test'
-        ? {
-            validateResponses: {
-              onError(error: Error, body: unknown, req: Request) {
-                console.log('Response body fails validation: ', error);
-                console.log('Emitted from:', req.originalUrl);
-                // eslint-disable-next-line no-console
-                console.debug(body);
-                throw error;
-              },
-            },
-          }
-        : {}),
-      ...(typeof routing.openapi === 'object' ? routing.openapi : {}),
-      ...openApiOptions,
-    };
-
-    return OpenApiValidator.middleware(merge(defaultOptions, combinedOptions));
-  } finally {
-    if (_window) {
-      (global as { window: unknown }).window = _window;
-    }
-  }
-}

package/src/telemetry/DummyExporter.ts

@@ -1,17 +0,0 @@
-import type { ExportResult } from '@opentelemetry/core';
-import { ExportResultCode } from '@opentelemetry/core';
-import type { ReadableSpan, SpanExporter } from '@opentelemetry/sdk-trace-base';
-
-export class DummySpanExporter implements SpanExporter {
-  export(spans: ReadableSpan[], resultCallback: (r: ExportResult) => void) {
-    setImmediate(() =>
-      resultCallback({
-        code: ExportResultCode.SUCCESS,
-      }),
-    );
-  }
-
-  async shutdown() {
-    // Nothing to do
-  }
-}

package/src/telemetry/hook-modules.ts

@@ -1,8 +0,0 @@
-import module from 'node:module';
-
-module.register('import-in-the-middle/hook.mjs', import.meta.url, {
-  parentURL: import.meta.url,
-  data: {
-    include: ['express', 'pino', 'http', 'dns', 'net', 'pg', 'redis', 'undici', 'generic-pool'],
-  },
-});

package/src/telemetry/index.ts

@@ -1,168 +0,0 @@
-import { OTLPLogExporter } from '@opentelemetry/exporter-logs-otlp-proto';
-import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-proto';
-import {
-  detectResources,
-  envDetector,
-  hostDetector,
-  osDetector,
-  processDetector,
-} from '@opentelemetry/resources';
-import { containerDetector } from '@opentelemetry/resource-detector-container';
-import { gcpDetector } from '@opentelemetry/resource-detector-gcp';
-import * as opentelemetry from '@opentelemetry/sdk-node';
-import { PrometheusExporter } from '@opentelemetry/exporter-prometheus';
-
-import type {
-  AnyServiceLocals,
-  DelayLoadServiceStartOptions,
-  RequestLocals,
-  ServiceLocals,
-  ServiceStartOptions,
-} from '../types.js';
-import type { ListenFn, StartAppFn } from '../express-app/index.js';
-import type { ConfigurationSchema } from '../config/schema.js';
-
-import { getAutoInstrumentations } from './instrumentations.js';
-import { DummySpanExporter } from './DummyExporter.js';
-
-// OTLP seems to only support http, and this is a default on the local network so I'm keeping it.
-// NOSONAR
-const baseDefaultOtlpUrl = new URL('http://otlp-exporter:4318/v1').toString();
-
-function getSpanExporter() {
-  if (
-    !process.env.DISABLE_OLTP_EXPORTER &&
-    (['production', 'staging'].includes(process.env.APP_ENV || process.env.NODE_ENV || '') ||
-      process.env.OTLP_EXPORTER)
-  ) {
-    return new OTLPTraceExporter({
-      url: process.env.OTLP_EXPORTER || `${baseDefaultOtlpUrl}/traces`,
-    });
-  }
-  if (process.env.ENABLE_CONSOLE_OLTP_EXPORTER) {
-    return new opentelemetry.tracing.ConsoleSpanExporter();
-  }
-  return new DummySpanExporter();
-}
-
-function getLogExporter() {
-  if (
-    !process.env.DISABLE_OLTP_EXPORTER &&
-    (['production', 'staging'].includes(process.env.APP_ENV || process.env.NODE_ENV || '') ||
-      process.env.OTLP_EXPORTER)
-  ) {
-    return new OTLPLogExporter({
-      url: process.env.OTLP_EXPORTER || `${baseDefaultOtlpUrl}/logs`,
-    });
-  }
-  if (process.env.ENABLE_CONSOLE_OLTP_EXPORTER) {
-    return new opentelemetry.logs.ConsoleLogRecordExporter();
-  }
-  return undefined;
-}
-
-let prometheusExporter: PrometheusExporter | undefined;
-let telemetrySdk: opentelemetry.NodeSDK | undefined;
-
-/**
- * OpenTelemetry is not friendly to the idea of stopping
- * and starting itself, it seems. So we can only keep a global
- * instance of the infrastructure no matter how many times
- * you start/stop your service (this is mostly only relevant for testing).
- * In addition, since we have to load it right away before configuration
- * is available, we can't use configuration to decide anything.
- */
-export async function startGlobalTelemetry(
-  serviceName: string,
-  customizer?:
-    | ((
-        options: Partial<opentelemetry.NodeSDKConfiguration>,
-      ) => Partial<opentelemetry.NodeSDKConfiguration>)
-    | undefined,
-) {
-  if (!prometheusExporter) {
-    const { metrics, logs, NodeSDK } = opentelemetry;
-
-    const resource = detectResources({
-      detectors: [
-        envDetector,
-        hostDetector,
-        osDetector,
-        processDetector,
-        containerDetector,
-        gcpDetector,
-      ],
-    });
-
-    prometheusExporter = new PrometheusExporter({ preventServerStart: true });
-    const instrumentations = getAutoInstrumentations();
-    const logExporter = getLogExporter();
-    const options: Partial<opentelemetry.NodeSDKConfiguration> = {
-      serviceName,
-      autoDetectResources: false,
-      resource,
-      traceExporter: getSpanExporter(),
-      metricReader: prometheusExporter,
-      instrumentations,
-      logRecordProcessors: logExporter ? [new logs.BatchLogRecordProcessor(logExporter)] : [],
-      views: [
-        {
-          instrumentName: 'http_request_duration_seconds',
-          instrumentType: metrics.InstrumentType.HISTOGRAM,
-          aggregation: {
-            type: metrics.AggregationType.EXPLICIT_BUCKET_HISTOGRAM,
-            options: {
-              boundaries: [0.003, 0.03, 0.1, 0.3, 1.5, 10],
-              recordMinMax: true,
-            },
-          },
-        },
-      ],
-    };
-    telemetrySdk = new NodeSDK(customizer ? customizer(options) : options);
-    telemetrySdk.start();
-  }
-}
-
-export function getNodeTelemetrySdk() {
-  return telemetrySdk;
-}
-
-export function getGlobalPrometheusExporter() {
-  return prometheusExporter;
-}
-
-export async function shutdownGlobalTelemetry() {
-  await telemetrySdk?.shutdown();
-  telemetrySdk = undefined;
-  prometheusExporter = undefined;
-}
-
-export async function startWithTelemetry<
-  SLocals extends AnyServiceLocals = ServiceLocals<ConfigurationSchema>,
-  RLocals extends RequestLocals = RequestLocals,
->(options: DelayLoadServiceStartOptions) {
-  await startGlobalTelemetry(options.name, options.customizer);
-
-  const { startApp, listen } = (await import('../express-app/app.js')) as {
-    startApp: StartAppFn<SLocals, RLocals>;
-    listen: ListenFn<SLocals>;
-  };
-  const serviceModule = await import(options.service);
-  const service = serviceModule.default || serviceModule.service;
-  const startOptions: ServiceStartOptions<SLocals> = {
-    ...options,
-    service,
-    locals: { ...options.locals } as unknown as Partial<SLocals>,
-  };
-  const app = await startApp(startOptions);
-  app.locals.logger.info('OpenTelemetry enabled');
-
-  const server = await listen(app, async () => {
-    await shutdownGlobalTelemetry();
-    app.locals.logger.info('OpenTelemetry shut down');
-  });
-  return { app, codepath: options.codepath, server };
-}
-
-export { setTelemetryHooks } from './instrumentations.js';

package/src/telemetry/instrumentations.ts

@@ -1,103 +0,0 @@
-import type { Instrumentation } from '@opentelemetry/instrumentation';
-import { DnsInstrumentation } from '@opentelemetry/instrumentation-dns';
-import type { SpanNameHook } from '@opentelemetry/instrumentation-express';
-import { ExpressInstrumentation } from '@opentelemetry/instrumentation-express';
-import { UndiciInstrumentation } from '@opentelemetry/instrumentation-undici';
-import { GenericPoolInstrumentation } from '@opentelemetry/instrumentation-generic-pool';
-import type { IgnoreIncomingRequestFunction } from '@opentelemetry/instrumentation-http';
-import { HttpInstrumentation } from '@opentelemetry/instrumentation-http';
-import { RedisInstrumentation } from '@opentelemetry/instrumentation-redis';
-import { NetInstrumentation } from '@opentelemetry/instrumentation-net';
-import { GraphQLInstrumentation } from '@opentelemetry/instrumentation-graphql';
-import { PgInstrumentation } from '@opentelemetry/instrumentation-pg';
-import { PinoInstrumentation } from '@opentelemetry/instrumentation-pino';
-
-const InstrumentationMap = {
-  '@opentelemetry/instrumentation-http': HttpInstrumentation,
-  '@opentelemetry/instrumentation-dns': DnsInstrumentation,
-  '@opentelemetry/instrumentation-express': ExpressInstrumentation,
-  '@opentelemetry/instrumentation-graphql': GraphQLInstrumentation,
-  '@opentelemetry/instrumentation-undici': UndiciInstrumentation,
-  '@opentelemetry/instrumentation-generic-pool': GenericPoolInstrumentation,
-  '@opentelemetry/instrumentation-redis': RedisInstrumentation,
-  '@opentelemetry/instrumentation-net': NetInstrumentation,
-  '@opentelemetry/instrumentation-pg': PgInstrumentation,
-  '@opentelemetry/instrumentation-pino': PinoInstrumentation,
-};
-
-// Config types inferred automatically from the first argument of the constructor
-type ConfigArg<T> = T extends new (...args: infer U) => unknown ? U[0] : never;
-export type InstrumentationConfigMap = {
-  [Name in keyof typeof InstrumentationMap]?: ConfigArg<(typeof InstrumentationMap)[Name]>;
-};
-
-let ignoreIncomingRequestHook: IgnoreIncomingRequestFunction | undefined = (req) => {
-  return req.url === '/health' || req.url === '/metrics';
-};
-
-let spanNameHook: SpanNameHook | undefined;
-
-export function setTelemetryHooks(hooks: {
-  ignoreIncomingRequestHook?: IgnoreIncomingRequestFunction;
-  spanNameHook?: SpanNameHook;
-}) {
-  if ('ignoreIncomingRequestHook' in hooks) {
-    ignoreIncomingRequestHook = hooks.ignoreIncomingRequestHook;
-  }
-  if ('spanNameHook' in hooks) {
-    spanNameHook = hooks.spanNameHook;
-  }
-}
-
-const defaultConfigs: InstrumentationConfigMap = {
-  '@opentelemetry/instrumentation-http': {
-    ignoreIncomingRequestHook(req) {
-      if (ignoreIncomingRequestHook) {
-        return ignoreIncomingRequestHook(req);
-      }
-      return false;
-    },
-  },
-  '@opentelemetry/instrumentation-express': {
-    spanNameHook(info, defaultName) {
-      if (spanNameHook) {
-        return spanNameHook(info, defaultName);
-      }
-      return defaultName;
-    },
-    ignoreLayers: [
-      'middleware - serviceLogger',
-      'middleware - jsonParser',
-      'middleware - attachServiceLocals',
-      'middleware - cookieParser',
-      'middleware - corsMiddleware',
-      'middleware - addReturnHeaders',
-      'middleware - freezeQuery',
-      'middleware - pathParamsMiddleware',
-      'middleware - metadataMiddleware',
-      'middleware - multipartMiddleware',
-      'middleware - securityMiddleware',
-    ],
-  },
-};
-
-export function getAutoInstrumentations(
-  inputConfigs: InstrumentationConfigMap = defaultConfigs,
-): Instrumentation[] {
-  const keys = Object.keys(InstrumentationMap) as (keyof typeof InstrumentationMap)[];
-  return keys
-    .map((name) => {
-      const Instance = InstrumentationMap[name];
-      // Defaults are defined by the instrumentation itself
-      const userConfig = inputConfigs[name] ?? {};
-
-      try {
-        return new Instance(userConfig);
-      } catch (e) {
-        // eslint-disable-next-line no-console
-        console.error(`Failed to load ${name}`, e);
-        return null;
-      }
-    })
-    .filter((i) => !!i) as Instrumentation[];
-}