@openapi-typescript-infra/service 6.10.1 → 6.10.2

package/src/express-app/app.ts

@@ -1,438 +0,0 @@
-import assert from 'assert';
-import http from 'http';
-import https from 'https';
-import path from 'path';
-
-import { destination, type Logger, pino } from 'pino';
-import cookieParser from 'cookie-parser';
-import { context, metrics, trace } from '@opentelemetry/api';
-import { setupNodeMetrics } from '@sesamecare-oss/opentelemetry-node-metrics';
-import { createTerminus } from '@godaddy/terminus';
-import type { RequestHandler, Response } from 'express';
-
-import { loadConfiguration } from '../config/index.js';
-import { openApi } from '../openapi.js';
-import {
-  errorHandlerMiddleware,
-  loggerMiddleware,
-  notFoundMiddleware,
-} from '../telemetry/requestLogger.js';
-import type {
-  AnyServiceLocals,
-  RequestLocals,
-  RequestWithApp,
-  ServiceExpress,
-  ServiceLocals,
-  ServiceOptions,
-  ServiceStartOptions,
-} from '../types.js';
-import type { ConfigurationSchema } from '../config/schema.js';
-import { shortstops } from '../config/shortstops.js';
-import { getNodeEnv, isDev } from '../env.js';
-import { getGlobalPrometheusExporter } from '../telemetry/index.js';
-
-import { loadRoutes } from './route-loader.js';
-import { startInternalApp } from './internal-server.js';
-
-function isSyncLogging() {
-  if (process.env.LOG_SYNC) {
-    return true;
-  }
-  return isDev() || getNodeEnv() === 'test';
-}
-
-export async function startApp<
-  SLocals extends AnyServiceLocals = ServiceLocals<ConfigurationSchema>,
-  RLocals extends RequestLocals = RequestLocals,
->(startOptions: ServiceStartOptions<SLocals, RLocals>): Promise<ServiceExpress<SLocals>> {
-  const { service, rootDirectory, codepath = 'build', name, version } = startOptions;
-  const shouldPrettyPrint = isDev() && !process.env.NO_PRETTY_LOGS;
-  const pinoDestination = destination({
-    sync: isSyncLogging(),
-    dest: process.env.LOG_TO_FILE || process.stdout.fd,
-    minLength: process.env.LOG_BUFFER ? Number(process.env.LOG_BUFFER) : undefined,
-  });
-
-  function poorMansOtlp(mergeObject: object) {
-    if (!('trace_id' in mergeObject)) {
-      const activeSpan = trace.getSpan(context.active());
-      if (activeSpan) {
-        const ctx = activeSpan.spanContext();
-        Object.assign(mergeObject, {
-          trace_id: ctx.traceId,
-          span_id: ctx.spanId,
-          trace_flags: ctx.traceFlags,
-        });
-      }
-    }
-    return mergeObject;
-  }
-
-  const logger = shouldPrettyPrint
-    ? pino(
-        {
-          transport: {
-            target: 'pino-pretty',
-            options: {
-              colorize: true,
-            },
-          },
-          mixin: poorMansOtlp,
-        },
-        pinoDestination,
-      )
-    : pino(
-        {
-          formatters: {
-            level(label) {
-              return { level: label };
-            },
-          },
-          mixin: poorMansOtlp,
-        },
-        pinoDestination,
-      );
-
-  const serviceImpl = service();
-  assert(serviceImpl?.start, 'Service function did not return a conforming object');
-
-  const sourceDirectory = path.join(rootDirectory, codepath);
-  const codeExtension = codepath === 'src' ? '.ts' : '.js';
-
-  const baseOptions: ServiceOptions = {
-    configurationDirectories: [path.resolve(rootDirectory, './config')],
-    shortstopHandlers: shortstops({ name }, sourceDirectory),
-    codepath,
-    codeExtension,
-  };
-  const options = serviceImpl.configure?.(startOptions, baseOptions) || baseOptions;
-
-  const config = await loadConfiguration({
-    configurationDirectories: options.configurationDirectories,
-    shortstopHandlers: options.shortstopHandlers,
-  });
-
-  const logging = config.logging;
-  logger.level = logging?.level || 'info';
-
-  // Concentrate the Typescript ugliness...
-  const { default: express } = await import('express');
-  const app = express() as unknown as ServiceExpress<SLocals>;
-  const routing = config.routing;
-
-  app.disable('x-powered-by');
-  if (routing?.etag !== true) {
-    app.disable('etag');
-  }
-
-  Object.assign(app.locals, startOptions.locals, {
-    service: serviceImpl,
-    logger,
-    config,
-    name,
-    version,
-  });
-
-  if (serviceImpl.attach) {
-    await serviceImpl.attach(app);
-  }
-
-  app.locals.meter = metrics.getMeterProvider().getMeter(name);
-  setupNodeMetrics(app.locals.meter, {});
-
-  if (config.trustProxy === true) {
-    app.enable('trust proxy');
-  } else if (config.trustProxy) {
-    app.set('trust proxy', config.trustProxy);
-  }
-
-  const histogram = app.locals.meter.createHistogram('http_request_duration_seconds', {
-    description: 'Duration of HTTP requests in seconds',
-  });
-
-  app.use(loggerMiddleware(app, histogram, logging));
-
-  // Allow the service to add locals, etc. We put this before the body parsers
-  // so that the req can decide whether to save the raw request body or not.
-  const attachServiceLocals: RequestHandler = (req, res, next) => {
-    res.locals.logger = logger;
-    try {
-      const result = serviceImpl.onRequest?.(
-        req as RequestWithApp<SLocals>,
-        res as Response<unknown, RLocals>,
-      );
-      if (result !== undefined && result !== null && typeof result.then === 'function') {
-        void result.catch(next).then(next);
-      } else {
-        next();
-      }
-    } catch (error) {
-      next(error);
-    }
-  };
-  app.use(attachServiceLocals);
-
-  if (routing?.cookieParser) {
-    app.use(cookieParser());
-  }
-
-  if (routing?.bodyParsers?.json) {
-    const jsonArgs = typeof routing.bodyParsers.json === 'object' ? routing.bodyParsers.json : {};
-    app.use(
-      express.json({
-        verify(req, res, buf) {
-          const locals = (res as Response).locals as RequestLocals;
-          if (locals?.rawBody === true) {
-            locals.rawBody = buf;
-          }
-        },
-        ...jsonArgs,
-      }),
-    );
-  }
-  if (routing?.bodyParsers?.form) {
-    app.use(
-      express.urlencoded(
-        typeof routing.bodyParsers.form === 'object' ? routing.bodyParsers.form : {},
-      ),
-    );
-  }
-
-  if (serviceImpl.authorize) {
-    const authorize: RequestHandler = (req, res, next) => {
-      let maybePromise: Promise<boolean> | boolean | undefined;
-      try {
-        maybePromise = serviceImpl.authorize?.(
-          req as RequestWithApp<SLocals>,
-          res as Response<unknown, RLocals>,
-        );
-      } catch (error) {
-        next(error);
-      }
-      if (maybePromise && typeof maybePromise !== 'boolean') {
-        maybePromise
-          .then((val) => {
-            if (val === false) {
-              return;
-            }
-            next();
-          })
-          .catch(next);
-      } else if (maybePromise !== false) {
-        next();
-      }
-    };
-    app.use(authorize);
-  }
-
-  if (routing?.static?.enabled) {
-    const localdir = path.resolve(rootDirectory, routing?.static?.path || 'public');
-    if (routing.static.mountPath) {
-      app.use(routing.static.mountPath, express.static(localdir));
-    } else {
-      app.use(express.static(localdir));
-    }
-  }
-
-  if (routing?.freezeQuery) {
-    app.use(function freezeQuery(req, res, next) {
-      // Express 5 re-parses the query string every time. This causes problems with
-      // various libraries, namely the express OpenAPI parser. So we "freeze it" in place
-      // here, which runs right before the routing validation logic does. Note that this
-      // means the app middleware will see the unfrozen one, which is intentional. If the
-      // app wants to modify or freeze the query itself, this shouldn't get in the way.
-      const { query } = req;
-      if (query) {
-        Object.defineProperty(req, 'query', {
-          configurable: true,
-          enumerable: true,
-          value: query,
-        });
-      }
-      next();
-    });
-  }
-
-  const codePattern = codepath === 'src' ? '**/*.ts' : '**/*.js';
-  if (routing?.routes) {
-    await loadRoutes(
-      app,
-      path.resolve(rootDirectory, codepath, config.routing?.routes || 'routes'),
-      codePattern,
-    );
-  }
-  if (routing?.openapi) {
-    const openApiMiddleware = await openApi(
-      app,
-      rootDirectory,
-      codepath,
-      codePattern,
-      options.openApiOptions,
-    );
-    app.use(openApiMiddleware);
-  }
-
-  // Putting this here allows more flexible middleware insertion
-  await serviceImpl.start(app);
-
-  const { notFound, errors } = routing?.finalHandlers || {};
-  if (notFound) {
-    app.use(notFoundMiddleware());
-  }
-  if (errors?.enabled) {
-    app.use(errorHandlerMiddleware(app, histogram, errors?.unnest, errors?.render));
-  }
-
-  return app;
-}
-
-export type StartAppFn<
-  SLocals extends AnyServiceLocals = ServiceLocals<ConfigurationSchema>,
-  RLocals extends RequestLocals = RequestLocals,
-> = typeof startApp<SLocals, RLocals>;
-
-export async function shutdownApp<
-  SLocals extends AnyServiceLocals = ServiceLocals<ConfigurationSchema>,
->(app: ServiceExpress<SLocals>) {
-  const { logger } = app.locals;
-  try {
-    await app.locals.service.stop?.(app);
-    logger.info('App shutdown complete');
-  } catch (error) {
-    logger.warn(error, 'Shutdown failed');
-  }
-  (logger as Logger).flush?.();
-}
-
-function httpServer<
-  Config extends ConfigurationSchema = ConfigurationSchema,
-  SLocals extends ServiceLocals<Config> = ServiceLocals<Config>,
->(app: ServiceExpress<SLocals>, config: ConfigurationSchema['server']) {
-  if (!config.certificate) {
-    return http.createServer(app);
-  }
-
-  return https.createServer(
-    {
-      key: config.key ? Buffer.from(config.key as string) : undefined,
-      cert: config.certificate ? Buffer.from(config.certificate as string) : undefined,
-    },
-    app,
-  );
-}
-
-function url(config: ConfigurationSchema['server'], port?: number) {
-  if (config.certificate) {
-    return `https://${config.hostname}${port === 443 ? '' : `:${port}`}`;
-  }
-  return `http://${config.hostname}${port === 80 ? '' : `:${port}`}`;
-}
-
-export async function listen<SLocals extends AnyServiceLocals = ServiceLocals<ConfigurationSchema>>(
-  app: ServiceExpress<SLocals>,
-  shutdownHandler?: () => Promise<void>,
-) {
-  const config: ConfigurationSchema['server'] = app.locals.config.server || {};
-  const { port } = config;
-
-  const { service, logger } = app.locals;
-  const server = httpServer(app, config);
-  await app.locals.service.attachServer?.(app, server);
-
-  let shutdownInProgress = false;
-  createTerminus(server, {
-    timeout: 15000,
-    useExit0: true,
-    // https://github.com/godaddy/terminus#how-to-set-terminus-up-with-kubernetes
-    beforeShutdown() {
-      if (shutdownInProgress) {
-        return Promise.resolve();
-      }
-      shutdownInProgress = true;
-      if (app.locals.internalApp) {
-        app.locals.internalApp.locals.server?.close();
-      }
-      logger.info('Graceful shutdown beginning');
-      return new Promise((accept) => {
-        // Per docs https://www.npmjs.com/package/@godaddy/terminus in Kubernetes, wait for readiness threshold
-        setTimeout(accept, 10000);
-      });
-    },
-    onShutdown() {
-      return Promise.resolve()
-        .then(() => service.stop?.(app))
-        .then(() => {
-          logger.info('Service stop complete');
-        })
-        .then(shutdownHandler || (() => Promise.resolve()))
-        .then(() => logger.info('Graceful shutdown complete'))
-        .catch((error) => logger.error(error, 'Error terminating tracing'))
-        .then(() => (logger as Logger).flush?.());
-    },
-    logger: (msg, e) => {
-      logger.error(e, msg);
-    },
-  });
-
-  server.on('close', () => {
-    if (!shutdownInProgress) {
-      shutdownInProgress = true;
-      app.locals.logger.info('Shutdown requested');
-      if (app.locals.internalApp) {
-        if (app.locals.internalApp.locals.server?.listening) {
-          app.locals.internalApp.locals.server?.close();
-        }
-      }
-      void shutdownApp(app);
-    }
-  });
-
-  server.on('error', (error) => {
-    logger.error(error, 'Main service listener error');
-  });
-
-  // TODO handle rejection/error?
-  const listenPromise = new Promise<void>((accept) => {
-    server.listen(port, () => {
-      const { locals } = app;
-      locals.logger.info({ url: url(config, port), service: locals.name }, 'express listening');
-
-      const serverConfig = app.locals.config.server;
-      // Ok now start the internal port if we have one.
-      if (serverConfig?.internalPort || serverConfig?.internalPort === 0) {
-        startInternalApp(app, serverConfig.internalPort as number)
-          .then((internalApp) => {
-            locals.internalApp = internalApp;
-            const prometheusExporter = getGlobalPrometheusExporter();
-            if (prometheusExporter) {
-              locals.internalApp.get(
-                '/metrics',
-                prometheusExporter.getMetricsRequestHandler.bind(prometheusExporter),
-              );
-              locals.logger.info('Metrics exporter started');
-            } else {
-              locals.logger.info('No metrics will be exported');
-            }
-            if (app.locals.openApiSpecification) {
-              locals.internalApp.get('/api-docs', (req, res) => {
-                res.json(app.locals.openApiSpecification);
-              });
-            }
-            accept();
-          })
-          .catch((error) => {
-            locals.logger.warn(error, 'Failed to start internal metadata app');
-          });
-      } else {
-        accept();
-      }
-    });
-  });
-
-  await listenPromise;
-  await service.onListening?.(app, { port, protocol: config.certificate ? 'https' : 'http' });
-  return server;
-}
-
-export type ListenFn<SLocals extends AnyServiceLocals = ServiceLocals<ConfigurationSchema>> =
-  typeof listen<SLocals>;

package/src/express-app/index.ts

@@ -1,3 +0,0 @@
-export * from './app.js';
-export * from './types.js';
-export * from './modules.js';

package/src/express-app/internal-server.ts

@@ -1,43 +0,0 @@
-import express from 'express';
-import type { Application } from 'express-serve-static-core';
-
-import type { AnyServiceLocals, InternalLocals, ServiceExpress, ServiceLocals } from '../types.js';
-import { getAvailablePort } from '../development/port-finder.js';
-import type { ConfigurationSchema } from '../config/schema.js';
-
-export async function startInternalApp<
-  SLocals extends AnyServiceLocals = ServiceLocals<ConfigurationSchema>,
->(mainApp: ServiceExpress<SLocals>, port: number) {
-  const app = express() as unknown as Application<InternalLocals<SLocals>>;
-  app.locals.mainApp = mainApp;
-
-  const finalPort = port === 0 ? await getAvailablePort(3001) : port;
-
-  app.get('/health', async (req, res) => {
-    if (mainApp.locals.service?.healthy) {
-      try {
-        const ok = await mainApp.locals.service.healthy(mainApp);
-        res.sendStatus(ok ? 200 : 500);
-      } catch (error) {
-        mainApp.locals.logger.error(error, 'Health check failed');
-      }
-    } else {
-      res.sendStatus(200);
-    }
-  });
-
-  const listenPromise = new Promise<void>((accept) => {
-    app.locals.server = app.listen(finalPort, () => {
-      accept();
-    });
-    app.locals.server.on('error', (error) => {
-      mainApp.locals.logger.error(error, 'Internal app server error');
-    });
-  });
-
-  await listenPromise;
-
-  mainApp.locals.logger.info({ port: finalPort }, 'Internal metadata server started');
-
-  return app;
-}

package/src/express-app/modules.ts

@@ -1,10 +0,0 @@
-import { glob } from 'glob';
-
-export async function getFilesInDir(pattern: string, dir: string) {
-  const files = await glob(pattern, {
-    nodir: true,
-    cwd: dir,
-    ignore: ['**/*.spec.@(js|ts)', '**/*.test.@(js|ts)', '**/*.fixtures.@(js|ts)'],
-  });
-  return files;
-}

package/src/express-app/route-loader.ts

@@ -1,40 +0,0 @@
-import path from 'path';
-
-import { Router } from 'express';
-
-import type { AnyServiceLocals, ServiceExpress, ServiceLocals } from '../types.js';
-import type { ConfigurationSchema } from '../config/schema.js';
-
-import { getFilesInDir } from './modules.js';
-
-export async function loadRoutes<
-  SLocals extends AnyServiceLocals = ServiceLocals<ConfigurationSchema>,
->(app: ServiceExpress<SLocals>, routingDir: string, pattern: string) {
-  const files = await getFilesInDir(pattern, routingDir);
-
-  await Promise.all(
-    files.map(async (filename) => {
-      const routeBase = path.dirname(filename);
-      const modulePath = path.resolve(routingDir, filename);
-      const module = await import(modulePath);
-      const mounter = module.default || module.route;
-      if (typeof mounter === 'function') {
-        const childRouter = Router();
-        mounter(childRouter, app);
-        const pathParts = [''];
-        if (routeBase !== '.') {
-          pathParts.push(routeBase);
-        }
-        const fn = path.parse(path.basename(filename)).name;
-        if (fn.toLowerCase() !== 'index') {
-          pathParts.push(fn);
-        }
-        const finalPath = pathParts.join('/') || '/';
-        app.locals.logger.debug({ path: finalPath, source: filename }, 'Registering routes');
-        app.use(finalPath, childRouter);
-      } else {
-        app.locals.logger.warn({ filename }, 'Route file had no default export');
-      }
-    }),
-  );
-}

package/src/express-app/types.ts

@@ -1,32 +0,0 @@
-import type { NextFunction, Response } from 'express';
-
-import type { AnyServiceLocals, RequestLocals, RequestWithApp, ServiceLocals } from '../types.js';
-import type { ConfigurationSchema } from '../config/schema.js';
-
-export type ServiceHandler<
-  SLocals extends AnyServiceLocals = ServiceLocals<ConfigurationSchema>,
-  RLocals extends RequestLocals = RequestLocals,
-  ResBody = unknown,
-  RetType = unknown,
-> = (
-  req: RequestWithApp<SLocals>,
-  res: Response<ResBody, RLocals>,
-  next: NextFunction,
-) => RetType | Promise<RetType>;
-
-// Make it easier to declare route files. This is not an exhaustive list
-// of supported router methods, but it has the most common ones.
-export interface ServiceRouter<
-  SLocals extends AnyServiceLocals = ServiceLocals<ConfigurationSchema>,
-  RLocals extends RequestLocals = RequestLocals,
-> {
-  all(path: string | RegExp, ...handlers: ServiceHandler<SLocals, RLocals>[]): void;
-  get(path: string | RegExp, ...handlers: ServiceHandler<SLocals, RLocals>[]): void;
-  post(path: string | RegExp, ...handlers: ServiceHandler<SLocals, RLocals>[]): void;
-  put(path: string | RegExp, ...handlers: ServiceHandler<SLocals, RLocals>[]): void;
-  delete(path: string | RegExp, ...handlers: ServiceHandler<SLocals, RLocals>[]): void;
-  patch(path: string | RegExp, ...handlers: ServiceHandler<SLocals, RLocals>[]): void;
-  options(path: string | RegExp, ...handlers: ServiceHandler<SLocals, RLocals>[]): void;
-  head(path: string | RegExp, ...handlers: ServiceHandler<SLocals, RLocals>[]): void;
-  use(...handlers: ServiceHandler<SLocals, RLocals>[]): void;
-}

package/src/hook.ts

@@ -1,36 +0,0 @@
-import type { ConfigurationSchema } from './config/schema.js';
-import type { AnyServiceLocals, RequestLocals, Service, ServiceLocals } from './types.js';
-
-/**
- * Your service should call this function and then "inherit"
- * the behavior in a functional way. So,
- *
- * const myServiceFn = () => {
- *   const baseService = useService<YourService>();
- *   return {
- *     ...baseService,
- *     async start(app) {
- *       await baseService.start(app);
- *       // your start stuff goes here
- *     },
- *     async onRequest(req, res) {
- *       // This might throw (auth for example), so don't catch it
- *       await baseService?.onRequest(req, res);
- *     },
- *   }
- * }
- *
- * @returns Service<Config, SLocals, RLocals>
- */
-export function useService<
-  SLocals extends AnyServiceLocals = ServiceLocals<ConfigurationSchema>,
-  RLocals extends RequestLocals = RequestLocals,
->(baseService?: Service<SLocals, RLocals>): Service<SLocals, RLocals> {
-  return {
-    async start(app) {
-      await baseService?.start(app);
-      // Do nothing. This hook exists mainly to reduce change required
-      // to adopt your specific companies base service.
-    },
-  };
-}

package/src/index.ts

@@ -1,9 +0,0 @@
-export * from './telemetry/index.js';
-export * from './express-app/index.js';
-export * from './types.js';
-export * from './env.js';
-export * from './config/index.js';
-export * from './error.js';
-export * from './bootstrap.js';
-export * from './hook.js';
-export { repl$ } from './development/repl.js';