Release beta to production

packages/express-wrapper/src/index.ts

@@ -6,9 +6,22 @@
 import express from 'express';
 
 import { ApiSpec, HttpRoute, Method as HttpMethod } from '@api-ts/io-ts-http';
-import { createRouter } from '@api-ts/typed-express-router';
+import {
+  createRouter,
+  DecodeErrorFormatterFn,
+  EncodeErrorFormatterFn,
+  GetDecodeErrorStatusCodeFn,
+  GetEncodeErrorStatusCodeFn,
+} from '@api-ts/typed-express-router';
 
-import { handleRequest, onDecodeError, onEncodeError, RouteHandler } from './request';
+import {
+  handleRequest,
+  defaultDecodeErrorFormatter,
+  defaultEncodeErrorFormatter,
+  defaultGetDecodeErrorStatusCode,
+  defaultGetEncodeErrorStatusCode,
+  RouteHandler,
+} from './request';
 import { defaultResponseEncoder, ResponseEncoder } from './response';
 
 export { middlewareFn, MiddlewareChain, MiddlewareChainOutput } from './middleware';
@@ -25,16 +38,26 @@ type CreateRouterProps<Spec extends ApiSpec> = {
     };
   };
   encoder?: ResponseEncoder;
+  decodeErrorFormatter?: DecodeErrorFormatterFn;
+  encodeErrorFormatter?: EncodeErrorFormatterFn;
+  getDecodeErrorStatusCode?: GetDecodeErrorStatusCodeFn;
+  getEncodeErrorStatusCode?: GetEncodeErrorStatusCodeFn;
 };
 
 export function routerForApiSpec<Spec extends ApiSpec>({
   spec,
   routeHandlers,
   encoder = defaultResponseEncoder,
+  decodeErrorFormatter = defaultDecodeErrorFormatter,
+  encodeErrorFormatter = defaultEncodeErrorFormatter,
+  getDecodeErrorStatusCode = defaultGetDecodeErrorStatusCode,
+  getEncodeErrorStatusCode = defaultGetEncodeErrorStatusCode,
 }: CreateRouterProps<Spec>) {
   const router = createRouter(spec, {
-    onDecodeError,
-    onEncodeError,
+    decodeErrorFormatter,
+    encodeErrorFormatter,
+    getDecodeErrorStatusCode,
+    getEncodeErrorStatusCode,
   });
   for (const apiName of Object.keys(spec)) {
     const resource = spec[apiName] as Spec[string];

packages/express-wrapper/src/request.ts

@@ -8,8 +8,10 @@ import * as PathReporter from 'io-ts/lib/PathReporter';
 
 import { ApiSpec, HttpRoute, RequestType, ResponseType } from '@api-ts/io-ts-http';
 import {
-  OnDecodeErrorFn,
-  OnEncodeErrorFn,
+  type DecodeErrorFormatterFn,
+  type EncodeErrorFormatterFn,
+  type GetDecodeErrorStatusCodeFn,
+  type GetEncodeErrorStatusCodeFn,
   TypedRequestHandler,
 } from '@api-ts/typed-express-router';
 
@@ -94,17 +96,28 @@ const createNamedFunction = <F extends (...args: any) => void>(
   fn: F,
 ): F => Object.defineProperty(fn, 'name', { value: name });
 
-export const onDecodeError: OnDecodeErrorFn = (errs, _req, res) => {
+export const defaultDecodeErrorFormatter: DecodeErrorFormatterFn = (errs, _req) => {
   const validationErrors = PathReporter.failure(errs);
-  const validationErrorMessage = validationErrors.join('\n');
-  res.writeHead(400, { 'Content-Type': 'application/json' });
-  res.write(JSON.stringify({ error: validationErrorMessage }));
-  res.end();
+  return { error: validationErrors.join('\n') };
 };
 
-export const onEncodeError: OnEncodeErrorFn = (err, _req, res) => {
+export const defaultEncodeErrorFormatter: EncodeErrorFormatterFn = (_err, _req) => {
+  return {};
+};
+
+export const defaultGetDecodeErrorStatusCode: GetDecodeErrorStatusCodeFn = (
+  _errs,
+  _req,
+) => {
+  return 400;
+};
+
+export const defaultGetEncodeErrorStatusCode: GetEncodeErrorStatusCodeFn = (
+  err,
+  _req,
+) => {
   console.warn('Error in route handler:', err);
-  res.status(500).end();
+  return 500;
 };
 
 export const handleRequest = (

packages/typed-express-router/README.md

@@ -76,13 +76,19 @@ logging.
 
 ```ts
 const typedRouter = createRouter(MyApi, {
-  onDecodeError: (errs, req, res) => {
+  decodeErrorFormatter: (errs, req) => {
     // Format `errs` however you want
-    res.send(400).json({ message: 'Bad request' }).end();
+    return { message: 'Bad request' };
   },
-  onEncodeError: (err, req, res) => {
+  getDecodeErrorStatusCode: (errs, req) => {
+    return 400;
+  },
+  encodeErrorFormatter: (err, req) => {
+    return { message: 'Internal server error' };
+  },
+  getEncodeErrorStatusCode: (err, req) => {
     // Ideally won't happen unless type safety is violated, so it's a 500
-    res.send(500).json({ message: 'Internal server error' }).end();
+    return 500;
   },
   afterEncodedResponseSent: (status, payload, req, res) => {
     // Perform side effects or other things, `res` should be ended by this point
@@ -92,17 +98,18 @@ const typedRouter = createRouter(MyApi, {
 
 // Override the decode error handler on one route
 typedRouter.get('hello.world', [HelloWorldHandler], {
-  onDecodeError: customHelloDecodeErrorHandler,
+  decodeErrorFormatter: customHelloDecodeErrorFormatter,
 });
 ```
 
 ### Unchecked routes
 
 If you need custom behavior on decode errors that is more involved than just sending an
 error response, then the unchecked variant of the router functions can be used. They do
-not fail and call `onDecodeError` when a request is invalid. Instead, they will still
-populate `req.decoded`, except this time it'll contain the
-`Either<Errors, DecodedRequest>` type for route handlers to inspect.
+not fail and send a http response using `decodeErrorFormatter` and
+`getDecodeErrorStatusCode` when a request is invalid. Instead, they will still populate
+`req.decoded`, except this time it'll contain the `Either<Errors, DecodedRequest>` type
+for route handlers to inspect.
 
 ```ts
 // Just a normal express route

packages/typed-express-router/package.json

@@ -23,11 +23,22 @@
     "fp-ts": "^2.0.0",
     "io-ts": "2.1.3"
   },
+  "peerDependencies": {
+    "@opentelemetry/api": "^1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@opentelemetry/api": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@api-ts/superagent-wrapper": "0.0.0-semantically-released",
     "@swc-node/register": "1.10.9",
     "c8": "10.1.3",
-    "typescript": "4.7.4"
+    "typescript": "4.7.4",
+    "@opentelemetry/sdk-trace-base": "1.30.1",
+    "@opentelemetry/sdk-trace-node": "1.30.1",
+    "@opentelemetry/api": "1.9.0"
   },
   "publishConfig": {
     "access": "public"

packages/typed-express-router/src/errors.ts

@@ -1,22 +1,22 @@
-import express from 'express';
-import { Errors } from 'io-ts';
 import * as PathReporter from 'io-ts/lib/PathReporter';
 
-export function defaultOnDecodeError(
-  errs: Errors,
-  _req: express.Request,
-  res: express.Response,
-) {
-  const validationErrors = PathReporter.failure(errs);
-  const validationErrorMessage = validationErrors.join('\n');
-  res.status(400).json({ error: validationErrorMessage }).end();
-}
+import type {
+  DecodeErrorFormatterFn,
+  EncodeErrorFormatterFn,
+  GetDecodeErrorStatusCodeFn,
+  GetEncodeErrorStatusCodeFn,
+} from './types';
 
-export function defaultOnEncodeError(
-  err: unknown,
-  _req: express.Request,
-  res: express.Response,
-) {
-  res.status(500).end();
-  console.warn(`Error in route handler: ${err}`);
-}
+export const defaultDecodeErrorFormatter: DecodeErrorFormatterFn = PathReporter.failure;
+
+export const defaultGetDecodeErrorStatusCode: GetDecodeErrorStatusCodeFn = (
+  _err,
+  _req,
+) => 400;
+
+export const defaultEncodeErrorFormatter: EncodeErrorFormatterFn = () => ({});
+
+export const defaultGetEncodeErrorStatusCode: GetEncodeErrorStatusCodeFn = (
+  _err,
+  _req,
+) => 500;

packages/typed-express-router/src/index.ts

@@ -3,11 +3,27 @@
  */
 
 import { ApiSpec, HttpRoute, KeyToHttpStatus } from '@api-ts/io-ts-http';
+import type { Span } from '@opentelemetry/api';
 import express from 'express';
 import * as E from 'fp-ts/Either';
 import { pipe } from 'fp-ts/pipeable';
-import { defaultOnDecodeError, defaultOnEncodeError } from './errors';
+
+import {
+  defaultDecodeErrorFormatter,
+  defaultEncodeErrorFormatter,
+  defaultGetDecodeErrorStatusCode,
+  defaultGetEncodeErrorStatusCode,
+} from './errors';
 import { apiTsPathToExpress } from './path';
+import {
+  ApiTsAttributes,
+  createDecodeSpan,
+  createSendEncodedSpan,
+  endSpan,
+  recordSpanDecodeError,
+  recordSpanEncodeError,
+  setSpanAttributes,
+} from './telemetry';
 import {
   AddRouteHandler,
   AddUncheckedRouteHandler,
@@ -22,8 +38,10 @@ import {
 
 export type {
   AfterEncodedResponseSentFn,
-  OnDecodeErrorFn,
-  OnEncodeErrorFn,
+  DecodeErrorFormatterFn,
+  EncodeErrorFormatterFn,
+  GetDecodeErrorStatusCodeFn,
+  GetEncodeErrorStatusCodeFn,
   TypedRequestHandler,
   UncheckedRequestHandler,
   WrappedRouter,
@@ -43,17 +61,21 @@ export type {
 export function createRouter<Spec extends ApiSpec>(
   spec: Spec,
   {
-    onDecodeError,
-    onEncodeError,
+    encodeErrorFormatter,
+    getEncodeErrorStatusCode,
     afterEncodedResponseSent,
+    decodeErrorFormatter,
+    getDecodeErrorStatusCode,
     ...options
   }: WrappedRouterOptions = {},
 ): WrappedRouter<Spec> {
   const router = express.Router(options);
   return wrapRouter(router, spec, {
-    onDecodeError,
-    onEncodeError,
+    encodeErrorFormatter,
+    getEncodeErrorStatusCode,
     afterEncodedResponseSent,
+    decodeErrorFormatter,
+    getDecodeErrorStatusCode,
   });
 }
 
@@ -69,9 +91,11 @@ export function wrapRouter<Spec extends ApiSpec>(
   router: express.Router,
   spec: Spec,
   {
-    onDecodeError = defaultOnDecodeError,
-    onEncodeError = defaultOnEncodeError,
+    encodeErrorFormatter = defaultEncodeErrorFormatter,
+    getEncodeErrorStatusCode = defaultGetEncodeErrorStatusCode,
     afterEncodedResponseSent = () => {},
+    decodeErrorFormatter = defaultDecodeErrorFormatter,
+    getDecodeErrorStatusCode = defaultGetDecodeErrorStatusCode,
   }: WrappedRouteOptions,
 ): WrappedRouter<Spec> {
   const routerMiddleware: UncheckedRequestHandler[] = [];
@@ -81,12 +105,14 @@ export function wrapRouter<Spec extends ApiSpec>(
   ): AddUncheckedRouteHandler<Spec, Method> {
     return (apiName, handlers, options) => {
       const route: HttpRoute | undefined = spec[apiName]?.[method];
+      let decodeSpan: Span | undefined;
       if (route === undefined) {
         // Should only happen with an explicit undefined property, which we can only prevent at the
         // type level with the `exactOptionalPropertyTypes` tsconfig option
         throw Error(`Method "${method}" at "${apiName}" must not be "undefined"'`);
       }
       const wrapReqAndRes: UncheckedRequestHandler = (req, res, next) => {
+        decodeSpan = createDecodeSpan({ apiName, httpRoute: route });
         // Intentionally passing explicit arguments here instead of decoding
         // req by itself because of issues that arise while using Node 16
         // See https://github.com/BitGo/api-ts/pull/394 for more information.
@@ -103,6 +129,10 @@ export function wrapRouter<Spec extends ApiSpec>(
           status: keyof (typeof route)['response'],
           payload: unknown,
         ) => {
+          const encodeSpan = createSendEncodedSpan({
+            apiName,
+            httpRoute: route,
+          });
           try {
             const codec = route.response[status];
             if (!codec) {
@@ -112,6 +142,9 @@ export function wrapRouter<Spec extends ApiSpec>(
               typeof status === 'number'
                 ? status
                 : KeyToHttpStatus[status as keyof KeyToHttpStatus];
+            setSpanAttributes(encodeSpan, {
+              [ApiTsAttributes.API_TS_STATUS_CODE]: statusCode,
+            });
             if (statusCode === undefined) {
               throw new Error(`unknown HTTP status code for key ${status}`);
             } else if (!codec.is(payload)) {
@@ -126,18 +159,42 @@ export function wrapRouter<Spec extends ApiSpec>(
               res as WrappedResponse,
             );
           } catch (err) {
-            (options?.onEncodeError ?? onEncodeError)(
-              err,
-              req as WrappedRequest,
-              res as WrappedResponse,
-            );
+            const statusCode = (
+              options?.getEncodeErrorStatusCode ?? getEncodeErrorStatusCode
+            )(err, req);
+            const encodeErrorMessage = (
+              options?.encodeErrorFormatter ?? encodeErrorFormatter
+            )(err, req);
+
+            recordSpanEncodeError(encodeSpan, err, statusCode);
+            res.status(statusCode).json(encodeErrorMessage);
+          } finally {
+            endSpan(encodeSpan);
           }
         };
         next();
       };
 
+      const endDecodeSpanMiddleware: UncheckedRequestHandler = (req, _res, next) => {
+        pipe(
+          req.decoded,
+          E.getOrElseW((errs) => {
+            const decodeErrorMessage = (
+              options?.decodeErrorFormatter ?? decodeErrorFormatter
+            )(errs, req);
+            const statusCode = (
+              options?.getDecodeErrorStatusCode ?? getDecodeErrorStatusCode
+            )(errs, req);
+            recordSpanDecodeError(decodeSpan, decodeErrorMessage, statusCode);
+          }),
+        );
+        endSpan(decodeSpan);
+        next();
+      };
+
       const middlewareChain = [
         wrapReqAndRes,
+        endDecodeSpanMiddleware,
         ...routerMiddleware,
         ...handlers,
       ] as express.RequestHandler[];
@@ -164,7 +221,13 @@ export function wrapRouter<Spec extends ApiSpec>(
           req.decoded,
           E.matchW(
             (errs) => {
-              (options?.onDecodeError ?? onDecodeError)(errs, req, res);
+              const statusCode = (
+                options?.getDecodeErrorStatusCode ?? getDecodeErrorStatusCode
+              )(errs, req);
+              const decodeErrorMessage = (
+                options?.decodeErrorFormatter ?? decodeErrorFormatter
+              )(errs, req);
+              res.status(statusCode).json(decodeErrorMessage);
             },
             (value) => {
               req.decoded = value;