@openapi-typescript-infra/service 2.2.0 → 2.4.0

package/build/types.d.ts

@@ -36,6 +36,7 @@ export type ResponseFromApp<ResBody = unknown, RLocals extends RequestLocals = R
 export interface Service<SLocals extends ServiceLocals = ServiceLocals, RLocals extends RequestLocals = RequestLocals> {
     name?: string;
     configure?: (startOptions: ServiceStartOptions<SLocals, RLocals>, options: ServiceOptions) => ServiceOptions;
+    attach?: (app: ServiceExpress<SLocals>) => void | Promise<void>;
     start(app: ServiceExpress<SLocals>): void | Promise<void>;
     stop?: (app: ServiceExpress<SLocals>) => void | Promise<void>;
     healthy?: (app: ServiceExpress<SLocals>) => boolean | Promise<boolean>;

package/config/config.json

@@ -24,8 +24,9 @@
   "server": {
     "port": 8000,
     "internalPort": 3000,
+    "hostname": "localhost",
     "metrics": {
       "enabled": true
     }
   }
-}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openapi-typescript-infra/service",
-  "version": "2.2.0",
+  "version": "2.4.0",
   "description": "An opinionated framework for building configuration driven services - web, api, or  ob. Uses OpenAPI, pino logging, express, confit, Typescript and vitest.",
   "main": "build/index.js",
   "scripts": {
@@ -109,7 +109,7 @@
     "@types/glob": "^8.1.0",
     "@types/lodash": "^4.14.197",
     "@types/minimist": "^1.2.2",
-    "@types/node": "^18.17.12",
+    "@types/node": "^20.5.7",
     "@types/supertest": "^2.0.12",
     "@typescript-eslint/eslint-plugin": "^6.5.0",
     "@typescript-eslint/parser": "^6.5.0",

package/src/config/schema.ts

@@ -67,6 +67,9 @@ export interface ConfigurationSchema extends Record<string, unknown> {
     // but this is useful for dev.
     key?: string;
     certificate?: string;
+    // If you have an alternate host name (other than localhost) that
+    // should be used when referring to this service, set it here.
+    hostname?: string;
   };
   connections: Record<string, ServiceConfiguration>;
 }

package/src/development/port-finder.ts

@@ -19,7 +19,7 @@ async function isAvailable(port: number) {
     server.once('error', (err) => {
       clearTimeout(timeoutRef);
 
-      if ((err as { code?: string; }).code === 'EADDRINUSE') {
+      if ((err as { code?: string }).code === 'EADDRINUSE') {
         accept(false);
         return;
       }

package/src/error.ts

@@ -32,11 +32,7 @@ export class ServiceError extends Error {
   // take up the valuable mental space of an error log.
   public expected_error?: boolean;
 
-  constructor(
-    app: ServiceLike<ServiceLocals>,
-    message: string,
-    spec?: ServiceErrorSpec,
-  ) {
+  constructor(app: ServiceLike<ServiceLocals>, message: string, spec?: ServiceErrorSpec) {
     super(message);
     this.domain = app.locals.name;
     Object.assign(this, spec);

package/src/express-app/app.ts

@@ -152,6 +152,10 @@ export async function startApp<
     name,
   });
 
+  if (serviceImpl.attach) {
+    await serviceImpl.attach(app);
+  }
+
   try {
     await enableMetrics(app, name);
   } catch (error) {
@@ -304,10 +308,14 @@ export async function shutdownApp(app: ServiceExpress) {
   (logger as pino.Logger).flush?.();
 }
 
-function tlsServer<SLocals extends ServiceLocals = ServiceLocals>(
+function httpServer<SLocals extends ServiceLocals = ServiceLocals>(
   app: ServiceExpress<SLocals>,
   config: ConfigurationSchema['server'],
 ) {
+  if (!config.certificate) {
+    return http.createServer(app);
+  }
+
   return https.createServer(
     {
       key: config.key,
@@ -317,6 +325,13 @@ function tlsServer<SLocals extends ServiceLocals = ServiceLocals>(
   );
 }
 
+function url(config: ConfigurationSchema['server']) {
+  if (config.certificate) {
+    return `https://${config.hostname}${config.port === 443 ? '' : `:${config.port}`}`;
+  }
+  return `http://${config.hostname}${config.port === 80 ? '' : `:${config.port}`}`;
+}
+
 export async function listen<SLocals extends ServiceLocals = ServiceLocals>(
   app: ServiceExpress<SLocals>,
   shutdownHandler?: () => Promise<void>,
@@ -329,7 +344,7 @@ export async function listen<SLocals extends ServiceLocals = ServiceLocals>(
   }
 
   const { service, logger } = app.locals;
-  const server = config.certificate ? tlsServer(app, config) : http.createServer(app);
+  const server = httpServer(app, config);
   let shutdownInProgress = false;
   createTerminus(server, {
     timeout: 15000,
@@ -384,7 +399,7 @@ export async function listen<SLocals extends ServiceLocals = ServiceLocals>(
   const listenPromise = new Promise<void>((accept) => {
     server.listen(port, () => {
       const { locals } = app;
-      locals.logger.info({ port, service: locals.name }, 'express listening');
+      locals.logger.info({ url: url(config), service: locals.name }, 'express listening');
 
       const serverConfig = locals.config.get('server') as ConfigurationSchema['server'];
       // Ok now start the internal port if we have one.

package/src/service-calls/index.ts

@@ -4,11 +4,7 @@ import type { FetchConfig, FetchRequest, RestApiResponse } from 'rest-api-suppor
 import EventSource from 'eventsource';
 
 import { ServiceError, ServiceErrorSpec } from '../error';
-import type {
-  ServiceExpress,
-  ServiceLike,
-  ServiceLocals,
-} from '../types';
+import type { ServiceExpress, ServiceLike, ServiceLocals } from '../types';
 import type { ServiceConfiguration } from '../config/schema';
 
 type UntypedEventSourceHandler = Parameters<EventSource['addEventListener']>[1];
@@ -104,14 +100,10 @@ function readResponse<
     return response as Extract<ResType, { responseType: 'response' }>;
   }
   const { message, ...spec } = errorSpec || {};
-  throw new ServiceError(
-    app,
-    message || (response.body as Error).message || 'Internal Error',
-    {
-      status: response.status,
-      ...spec,
-    },
-  );
+  throw new ServiceError(app, message || (response.body as Error).message || 'Internal Error', {
+    status: response.status,
+    ...spec,
+  });
 }
 
 export async function throwOrGetResponse<

package/src/telemetry/fetchInstrumentation.ts

@@ -33,7 +33,7 @@ interface FetchRequestArguments {
   error?: Error;
 }
 
-type ErrorFetchRequestArguments = FetchRequestArguments & { error: Error; };
+type ErrorFetchRequestArguments = FetchRequestArguments & { error: Error };
 type ResponseFetchRequestArguments = FetchRequestArguments & {
   response: {
     statusCode: number;
@@ -82,7 +82,8 @@ export class FetchInstrumentation implements Instrumentation {
 
   public readonly instrumentationVersion = '1.0.0';
 
-  public readonly instrumentationDescription = 'Instrumentation for Node 18 fetch via diagnostics_channel';
+  public readonly instrumentationDescription =
+    'Instrumentation for Node 18 fetch via diagnostics_channel';
 
   private subscribeToChannel(diagnosticChannel: string, onMessage: diagch.ChannelListener) {
     const channel = diagch.channel(diagnosticChannel);
@@ -108,24 +109,26 @@ export class FetchInstrumentation implements Instrumentation {
   }
 
   enable(): void {
-    this.subscribeToChannel('undici:request:create', (args) => this.onRequest(args as FetchRequestArguments));
-    this.subscribeToChannel('undici:request:headers', (args) => this.onHeaders(args as ResponseFetchRequestArguments));
-    this.subscribeToChannel('undici:request:trailers', (args) => this.onDone(args as FetchRequestArguments));
-    this.subscribeToChannel('undici:request:error', (args) => this.onError(args as ErrorFetchRequestArguments));
+    this.subscribeToChannel('undici:request:create', (args) =>
+      this.onRequest(args as FetchRequestArguments),
+    );
+    this.subscribeToChannel('undici:request:headers', (args) =>
+      this.onHeaders(args as ResponseFetchRequestArguments),
+    );
+    this.subscribeToChannel('undici:request:trailers', (args) =>
+      this.onDone(args as FetchRequestArguments),
+    );
+    this.subscribeToChannel('undici:request:error', (args) =>
+      this.onError(args as ErrorFetchRequestArguments),
+    );
   }
 
   setTracerProvider(tracerProvider: TracerProvider): void {
-    this.tracer = tracerProvider.getTracer(
-      this.instrumentationName,
-      this.instrumentationVersion,
-    );
+    this.tracer = tracerProvider.getTracer(this.instrumentationName, this.instrumentationVersion);
   }
 
   public setMeterProvider(meterProvider: MeterProvider): void {
-    this.meter = meterProvider.getMeter(
-      this.instrumentationName,
-      this.instrumentationVersion,
-    );
+    this.meter = meterProvider.getMeter(this.instrumentationName, this.instrumentationVersion);
   }
 
   setConfig(config: InstrumentationConfig): void {

package/src/telemetry/instrumentations.ts

@@ -29,7 +29,7 @@ const InstrumentationMap = {
 // 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]>;
+  [Name in keyof typeof InstrumentationMap]?: ConfigArg<(typeof InstrumentationMap)[Name]>;
 };
 
 export function getAutoInstrumentations(

package/src/telemetry/requestLogger.ts

@@ -1,6 +1,4 @@
-import type {
-  RequestHandler, Request, Response, ErrorRequestHandler,
-} from 'express';
+import type { RequestHandler, Request, Response, ErrorRequestHandler } from 'express';
 
 import { ServiceError } from '../error';
 import type { RequestWithApp, ServiceExpress, ServiceLocals } from '../types';
@@ -25,7 +23,9 @@ interface WithIdentifiedSession {
   };
 }
 
-interface ErrorWithStatus extends Error { status?: number; }
+interface ErrorWithStatus extends Error {
+  status?: number;
+}
 
 function getBasicInfo(req: Request) {
   const url = req.originalUrl || req.url;
@@ -113,20 +113,18 @@ export function loggerMiddleware<SLocals extends ServiceLocals = ServiceLocals>(
       // data is to monkey-patch.
       const oldWrite = res.write;
       const oldEnd = res.end;
-      res.write = ((...args: Parameters<typeof res['write']>) => {
+      res.write = ((...args: Parameters<(typeof res)['write']>) => {
         if (prefs.chunks) {
           prefs.chunks.push(Buffer.isBuffer(args[0]) ? args[0] : Buffer.from(args[0]));
         }
-        return (oldWrite as typeof res['write']).apply(res, args);
-      }) as typeof res['write'];
-      res.end = ((
-        ...args: Parameters<typeof res['end']>
-      ) => {
+        return (oldWrite as (typeof res)['write']).apply(res, args);
+      }) as (typeof res)['write'];
+      res.end = ((...args: Parameters<(typeof res)['end']>) => {
         if (args[0] && prefs.chunks) {
           prefs.chunks.push(Buffer.isBuffer(args[0]) ? args[0] : Buffer.from(args[0]));
         }
         return oldEnd.apply(res, args);
-      }) as typeof res['end'];
+      }) as (typeof res)['end'];
     }
 
     const preLog: Record<string, string | string[] | number | undefined> = {

package/src/types.ts

@@ -59,7 +59,13 @@ export interface Service<
     options: ServiceOptions,
   ) => ServiceOptions;
 
+  // Run after configuration but before routes are loaded,
+  // which is often a good place to add elements to the app locals
+  // that are needed during route setup
+  attach?: (app: ServiceExpress<SLocals>) => void | Promise<void>;
+
   start(app: ServiceExpress<SLocals>): void | Promise<void>;
+
   stop?: (app: ServiceExpress<SLocals>) => void | Promise<void>;
 
   healthy?: (app: ServiceExpress<SLocals>) => boolean | Promise<boolean>;
@@ -71,11 +77,17 @@ export interface Service<
   onRequest?(req: RequestWithApp<SLocals>, res: Response<unknown, RLocals>): void | Promise<void>;
 
   // This runs after body parsing but before routing
-  authorize?(req: RequestWithApp<SLocals>, res: Response<unknown, RLocals>): boolean | Promise<boolean>;
+  authorize?(
+    req: RequestWithApp<SLocals>,
+    res: Response<unknown, RLocals>,
+  ): boolean | Promise<boolean>;
 
   // Add or redact any fields for logging. Note this will be called twice per request,
   // once at the start and once at the end. Modify the values directly.
-  getLogFields?(req: RequestWithApp<SLocals>, values: Record<string, string | string[] | number | undefined>): void;
+  getLogFields?(
+    req: RequestWithApp<SLocals>,
+    values: Record<string, string | string[] | number | undefined>,
+  ): void;
 }
 
 export type ServiceFactory<