@uphold/fastify-openapi-router-plugin 0.7.1 → 1.0.0

package/README.md

@@ -59,6 +59,7 @@ await fastify.register(import('@fastify/fastify-openapi-router-plugin'), {
 | `spec` | `string` or `object` | **REQUIRED**. A file path or object of your OpenAPI specification. |
 | `securityHandlers` | `object` | An object containing the security handlers that match [Security Schemes](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#security-scheme-object) described in your OpenAPI specification. |
 | `securityErrorMapper` | `function` | A function that allows mapping the default `UnauthorizedError` to a custom error. |
+| `notImplementedErrorMapper` | `function` | A function that allows mapping the default `NotImplementedError` to a custom error. |
 
 #### `spec`
 
@@ -146,7 +147,7 @@ Any error thrown by the security handler will be internally wrapped in a `Securi
 
 #### `securityErrorMapper`
 
-The plugin will throw an `UnauthorizedError` when none of the `security` blocks succeed. By default, this error originates a `401` reply with `{ code: 'FST_OAS_UNAUTHORIZED', 'message': 'Unauthorized' }` as the payload. You can override this behavior by leveraging the `securityErrorMapper` option:
+The plugin will throw an `UnauthorizedError` when none of the `security` blocks succeed. By default, this error originates a `401` reply with `{ code: 'FST_OAS_UNAUTHORIZED', message: 'Unauthorized' }` as the payload. You can override this behavior by leveraging the `securityErrorMapper` option:
 
 ```js
 await fastify.register(import('@fastify/fastify-openapi-router-plugin'), {
@@ -173,7 +174,8 @@ The `securityReport` property of the unauthorized error contains an array of obj
     schemes: {
       OAuth2: {
         ok: false,
-        // The error will be either be a `fastify.oas.errors.SecurityHandlerError` or a `fastify.oas.errors.ScopesMismatchError` if the scopes were not satisfied.
+        // The error will be either be a `fastify.oas.errors.SecurityHandlerError` or a
+        // `fastify.oas.errors.ScopesMismatchError` if the scopes were not satisfied.
         error: <Error>,
       }
     }
@@ -183,6 +185,21 @@ The `securityReport` property of the unauthorized error contains an array of obj
 
 If you don't define a `securityErrorMapper`, you can still catch the `UnauthorizedError` in your fastify error handler.
 
+#### `notImplementedErrorMapper`
+
+The plugin will throw an `NotImplementedError` when you install a handler for not implemented specs through `fastify.oas.installNotImplementedRoutes()` function. By default, this error originates a `501` reply with `{ code: 'FST_OAS_NOT_IMPLEMENTED', message: 'Not implemented' }` as the payload. You can override this behavior by leveraging the `notImplementedErrorMapper` option:
+
+```js
+await fastify.register(import('@fastify/fastify-openapi-router-plugin'), {
+  spec: './petstore.json',
+  notImplementedErrorMapper: (notImplementedError) => {
+    return MyNotImplementedError();
+  },
+});
+```
+
+If you don't define a `notImplementedErrorMapper`, you can still catch the `NotImplementedError` in your fastify error handler.
+
 ### Decorators
 
 #### `fastify.oas.route(options)`
@@ -204,12 +221,42 @@ fastify.oas.route({
 });
 ```
 
+#### `fastify.oas.installNotImplementedRoutes()`
+
+This function will register handlers with fastify for the routes in the spec that were not registered. You can use this, for example, when you want to give a more specific error for the consumer for operations that you still do not have an implementation.
+
+> [!IMPORTANT]
+> Make sure you `await` the calls to `fastify.register()` for your routes before calling this function to make sure that fastify executes them before the call to `fastify.oas.installNotImplementedRoutes()`.
+
+**Example**
+
+```js
+await fastify.register(import('@fastify/fastify-openapi-router-plugin'), {
+  spec: './petstore.json'
+});
+
+fastify.oas.route({
+  operationId: 'getPetById',
+  handler: (request, reply) => {}
+});
+
+// Routes in spec that were not registered through `fastify.oas.route` will get a 'not implemented' handler.
+fastify.oas.installNotImplementedRoutes();
+
+// Finish fastify setup.
+await fastify.ready();
+```
+
+> [!TIP]
+> If you need to customize the `NotImplementedError` that is thrown by default, you can use the [notImplementedErrorMapper](#notimplementederrormapper) in order to change the default behavior.
+
 #### `fastify.oas.errors`
 
-This object contains all error classes that can be thrown by the plugin:
+This object contains all error classes used by the plugin:
 
-- `UnauthorizedError`: Thrown when all security schemes verification failed.
-- `ScopesMismatchError`: Thrown when the scopes returned by the security handler do not satisfy the scopes defined in the API operation.
+- `SecurityHandlerError`: Used to wrap a security handler error.
+- `ScopesMismatchError`: Used when the scopes returned by the security handler do not satisfy the scopes defined in the API operation.
+- `UnauthorizedError`: Used to indicate that the request is unauthorized, containing a `securityReport`. Check the [`securityErrorMapper`](#securityerrormapper) section for more information.
 
 #### `request.oas`
 
@@ -217,7 +264,7 @@ For your convenience, the object `request.oas` is populated with data related to
 
 - `operation` is the raw API operation that activated the Fastify route.
 - `security` is an object where keys are security scheme names and values the returned `data` field from security handlers.
-- `securityReport`: A detailed report of the security verification process. Check the [`securityErrorMapper`](#security-error-mapper) section for more information.
+- `securityReport`: A detailed report of the security verification process. Check the [`securityErrorMapper`](#securityerrormapper) section for more information.
 
 **Example**
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uphold/fastify-openapi-router-plugin",
-  "version": "0.7.1",
+  "version": "1.0.0",
   "description": "A plugin for Fastify to connect routes with a OpenAPI 3.x specification",
   "main": "./src/index.js",
   "types": "./types/index.d.ts",

package/src/errors/index.js

@@ -1,11 +1,19 @@
+import { NotImplementedError, createNotImplementedError } from './not-implemented-error.js';
 import { ScopesMismatchError, createScopesMismatchError } from './scopes-mismatch-error.js';
 import { SecurityHandlerError, createSecurityHandlerError } from './security-handler-error.js';
 import { UnauthorizedError, createUnauthorizedError } from './unauthorized-error.js';
 
 const errors = {
+  NotImplementedError,
   ScopesMismatchError,
   SecurityHandlerError,
   UnauthorizedError
 };
 
-export { createScopesMismatchError, createUnauthorizedError, createSecurityHandlerError, errors };
+export {
+  createScopesMismatchError,
+  createUnauthorizedError,
+  createNotImplementedError,
+  createSecurityHandlerError,
+  errors
+};

package/src/errors/not-implemented-error.js

@@ -0,0 +1,11 @@
+import createError from '@fastify/error';
+
+const NotImplementedError = createError('FST_OAS_NOT_IMPLEMENTED', 'Not implemented', 501);
+
+const createNotImplementedError = () => {
+  const err = new NotImplementedError();
+
+  return err;
+};
+
+export { NotImplementedError, createNotImplementedError };

package/src/index.test.js

@@ -13,6 +13,9 @@ describe('Fastify plugin', () => {
         '/pets': {
           get: {
             operationId: 'getPets'
+          },
+          post: {
+            operationId: 'postPets'
           }
         }
       }
@@ -46,48 +49,119 @@ describe('Fastify plugin', () => {
     });
   });
 
-  it('should throw registering a route if `operationId` is not in spec', async () => {
-    const app = fastify({ logger: false });
+  describe('route()', () => {
+    it('should throw registering a route if `operationId` is not in spec', async () => {
+      const app = fastify({ logger: false });
 
-    await app.register(OpenAPIRouter, { spec });
+      await app.register(OpenAPIRouter, { spec });
 
-    expect(() =>
-      app.oas.route({
-        handler: () => {},
-        operationId: 'getUnknown'
-      })
-    ).toThrowError(`Missing 'getUnknown' in OpenAPI spec.`);
-  });
+      expect(() =>
+        app.oas.route({
+          handler: () => {},
+          operationId: 'getUnknown'
+        })
+      ).toThrowError(`Missing 'getUnknown' in OpenAPI spec.`);
+    });
 
-  it('should set a route-level onRequest hook', async () => {
-    const app = fastify({ logger: false });
-    const onRequest = vi.fn(async () => {});
+    it('should set a route-level onRequest hook', async () => {
+      const app = fastify({ logger: false });
+      const onRequest = vi.fn(async () => {});
 
-    await app.register(OpenAPIRouter, { spec });
+      await app.register(OpenAPIRouter, { spec });
 
-    app.oas.route({
-      handler: async () => {},
-      onRequest,
-      operationId: 'getPets'
+      app.oas.route({
+        handler: async () => {},
+        onRequest,
+        operationId: 'getPets'
+      });
+
+      await app.inject({ url: '/pets' });
+
+      expect(onRequest).toHaveBeenCalledTimes(1);
     });
 
-    await app.inject({ url: '/pets' });
+    it('should not override internal route options', async () => {
+      const app = fastify({ logger: false });
 
-    expect(onRequest).toHaveBeenCalledTimes(1);
+      await app.register(OpenAPIRouter, { spec });
+
+      expect(() =>
+        app.oas.route({
+          handler: async () => {},
+          method: 'PUT',
+          operationId: 'getPets',
+          url: '/pets/:id'
+        })
+      ).toThrowError(`Not allowed to override 'method', 'schema' or 'url' for operation 'getPets'.`);
+    });
   });
 
-  it('should not override internal route options', async () => {
-    const app = fastify({ logger: false });
+  describe('installNotImplementedRoutes()', () => {
+    it('should install handlers for not registered routes that will return a not implemented error', async () => {
+      const app = fastify({ logger: false });
 
-    await app.register(OpenAPIRouter, { spec });
+      await app.register(OpenAPIRouter, { spec });
 
-    expect(() =>
       app.oas.route({
-        handler: async () => {},
-        method: 'PUT',
-        operationId: 'getPets',
-        url: '/pets/:id'
-      })
-    ).toThrowError(`Not allowed to override 'method', 'schema' or 'url' for operation 'getPets'.`);
+        handler: async () => {
+          return 'pets';
+        },
+        operationId: 'getPets'
+      });
+
+      vi.spyOn(app, 'route');
+
+      app.oas.installNotImplementedRoutes();
+
+      expect(app.route).toHaveBeenCalledWith({
+        handler: expect.any(Function),
+        method: 'POST',
+        onRequest: [expect.any(Function)],
+        schema: {
+          headers: {
+            properties: {},
+            required: [],
+            type: 'object'
+          },
+          params: {
+            properties: {},
+            required: [],
+            type: 'object'
+          },
+          query: {
+            properties: {},
+            required: [],
+            type: 'object'
+          },
+          response: {}
+        },
+        url: '/pets'
+      });
+
+      const getPetsResult = await app.inject({ url: '/pets' });
+
+      expect(getPetsResult.body).toMatchInlineSnapshot('"pets"');
+
+      const postPetsResult = await app.inject({ method: 'POST', url: '/pets' });
+
+      expect(postPetsResult.body).toMatchInlineSnapshot(
+        `"{"statusCode":501,"code":"FST_OAS_NOT_IMPLEMENTED","error":"Not Implemented","message":"Not implemented"}"`
+      );
+    });
+
+    it('should call `notImplementedErrorMapper` option if provided', async () => {
+      const app = fastify({ logger: false });
+      const notImplementedErrorMapper = vi.fn(() => new Error('Foo'));
+
+      await app.register(OpenAPIRouter, { notImplementedErrorMapper, spec });
+
+      app.oas.installNotImplementedRoutes();
+
+      const postPetsResult = await app.inject({ method: 'POST', url: '/pets' });
+
+      expect(postPetsResult.body).toMatchInlineSnapshot(
+        `"{"statusCode":500,"error":"Internal Server Error","message":"Foo"}"`
+      );
+    });
   });
 });

package/src/parser/index.js

@@ -21,16 +21,20 @@ export const parse = async options => {
     for (const method in methods) {
       const operation = methods[method];
 
+      const securityFn = applySecurity(operation, spec, options.securityHandlers, options.securityErrorMapper);
+      const applyParamsCoercingFn = applyParamsCoercing(operation);
+
       // Build fastify route.
       const route = {
         method: method.toUpperCase(),
         onRequest: [
-          async function (request) {
+          async function openApiRouterOnRequestHook(request) {
             request[DECORATOR_NAME].operation = operation;
-          },
-          applySecurity(operation, spec, options.securityHandlers, options.securityErrorMapper),
-          applyParamsCoercing(operation)
-        ].filter(Boolean),
+
+            await securityFn?.(request);
+            applyParamsCoercingFn?.(request);
+          }
+        ],
         schema: {
           headers: parseParams(operation.parameters, 'header'),
           params: parseParams(operation.parameters, 'path'),

package/src/parser/params.js

@@ -87,7 +87,7 @@ export const applyParamsCoercing = operation => {
     })
     .filter(Boolean);
 
-  return async request => {
+  return request => {
     coerceArrayParametersFns.forEach(fn => fn(request));
   };
 };

package/src/parser/security.test.js

@@ -103,9 +103,9 @@ describe('applySecurity()', () => {
   });
 
   it('should return undefined if `security` is disabled in operation', async () => {
-    const onRequest = applySecurity({ security: [] }, { security: [{ OAuth2: [] }] }, {});
+    const securityFn = applySecurity({ security: [] }, { security: [{ OAuth2: [] }] }, {});
 
-    expect(onRequest).toBeUndefined();
+    expect(securityFn).toBeUndefined();
   });
 
   it('should stop at the first successful security block', async () => {
@@ -135,9 +135,9 @@ describe('applySecurity()', () => {
       OAuth2: vi.fn(async () => ({ data: 'OAuth2 data', scopes: [] }))
     };
 
-    const onRequest = applySecurity(operation, spec, securityHandlers);
+    const securityFn = applySecurity(operation, spec, securityHandlers);
 
-    await onRequest(request);
+    await securityFn(request);
 
     expect(securityHandlers.ApiKey).toHaveBeenCalledTimes(1);
     expect(securityHandlers.ApiKey).toHaveBeenCalledWith('api key', request);
@@ -190,9 +190,9 @@ describe('applySecurity()', () => {
       OAuth2: vi.fn(async () => ({ data: 'OAuth2 data', scopes: [] }))
     };
 
-    const onRequest = applySecurity(operation, spec, securityHandlers);
+    const securityFn = applySecurity(operation, spec, securityHandlers);
 
-    await onRequest(request);
+    await securityFn(request);
 
     expect(securityHandlers.ApiKey).toHaveBeenCalledTimes(1);
     expect(securityHandlers.ApiKey).toHaveBeenCalledWith('api key', request);
@@ -249,10 +249,10 @@ describe('applySecurity()', () => {
       OAuth2: vi.fn(async () => ({ data: 'OAuth2 data', scopes: [] }))
     };
 
-    const onRequest = applySecurity(operation, spec, securityHandlers);
+    const securityFn = applySecurity(operation, spec, securityHandlers);
 
     try {
-      await onRequest(request);
+      await securityFn(request);
     } catch (error) {
       expect(error).toBeInstanceOf(errors.UnauthorizedError);
       expect(error.securityReport).toMatchInlineSnapshot(`
@@ -299,12 +299,12 @@ describe('applySecurity()', () => {
       })
     };
 
-    const onRequest = applySecurity(operation, spec, securityHandlers);
+    const securityFn = applySecurity(operation, spec, securityHandlers);
 
     expect.assertions(2);
 
     try {
-      await onRequest(request);
+      await securityFn(request);
     } catch (err) {
       expect(err).toBeInstanceOf(errors.UnauthorizedError);
       expect(err.securityReport).toMatchInlineSnapshot(`
@@ -354,9 +354,9 @@ describe('applySecurity()', () => {
       OAuth2: vi.fn(async () => ({ data: 'OAuth2 data', scopes: ['write'] }))
     };
 
-    const onRequest = applySecurity(operation, spec, securityHandlers);
+    const securityFn = applySecurity(operation, spec, securityHandlers);
 
-    await onRequest(request);
+    await securityFn(request);
 
     expect(securityHandlers.OAuth2).toHaveBeenCalledTimes(1);
   });
@@ -385,12 +385,12 @@ describe('applySecurity()', () => {
       })
     };
 
-    const onRequest = applySecurity(operation, spec, securityHandlers);
+    const securityFn = applySecurity(operation, spec, securityHandlers);
 
     expect.assertions(2);
 
     try {
-      await onRequest(request);
+      await securityFn(request);
     } catch (err) {
       expect(err).toBeInstanceOf(errors.UnauthorizedError);
       expect(securityHandlers.OAuth2).toHaveBeenCalledTimes(1);
@@ -420,11 +420,11 @@ describe('applySecurity()', () => {
       OAuth2: vi.fn(async () => ({ data: 'OAuth2 data', scopes: [] }))
     };
 
-    const onRequest = applySecurity(operation, spec, securityHandlers);
+    const securityFn = applySecurity(operation, spec, securityHandlers);
 
     expect.assertions(3);
 
-    await onRequest(request);
+    await securityFn(request);
 
     expect(securityHandlers.ApiKey).not.toHaveBeenCalled();
     expect(securityHandlers.OAuth2).toHaveBeenCalledTimes(1);
@@ -468,12 +468,12 @@ describe('applySecurity()', () => {
       OAuth2: vi.fn(() => ({ data: 'OAuth2 data', scopes: ['read'] }))
     };
 
-    const onRequest = applySecurity(operation, spec, securityHandlers);
+    const securityFn = applySecurity(operation, spec, securityHandlers);
 
     expect.assertions(2);
 
     try {
-      await onRequest(request);
+      await securityFn(request);
     } catch (err) {
       expect(err).toBeInstanceOf(errors.UnauthorizedError);
       expect(err.securityReport).toMatchInlineSnapshot(`
@@ -513,9 +513,9 @@ describe('applySecurity()', () => {
       OAuth2: vi.fn(() => {})
     };
 
-    const onRequest = applySecurity(operation, spec, securityHandlers);
+    const securityFn = applySecurity(operation, spec, securityHandlers);
 
-    await onRequest(request);
+    await securityFn(request);
 
     expect(request[DECORATOR_NAME].security).toMatchObject({ OAuth2: undefined });
     expect(request[DECORATOR_NAME].securityReport).toMatchInlineSnapshot(`
@@ -554,12 +554,12 @@ describe('applySecurity()', () => {
       OAuth2: vi.fn(() => {})
     };
 
-    const onRequest = applySecurity(operation, spec, securityHandlers);
+    const securityFn = applySecurity(operation, spec, securityHandlers);
 
     expect.assertions(2);
 
     try {
-      await onRequest(request);
+      await securityFn(request);
     } catch (err) {
       expect(err).toBeInstanceOf(errors.UnauthorizedError);
       expect(err.securityReport).toMatchInlineSnapshot(`
@@ -603,12 +603,12 @@ describe('applySecurity()', () => {
     const customError = new Error('Mapped error');
     const securityErrorMapper = vi.fn(() => customError);
 
-    const onRequest = applySecurity(operation, spec, securityHandlers, securityErrorMapper);
+    const securityFn = applySecurity(operation, spec, securityHandlers, securityErrorMapper);
 
     expect.assertions(3);
 
     try {
-      await onRequest(request);
+      await securityFn(request);
     } catch (err) {
       expect(err).toBe(customError);
       expect(securityErrorMapper).toHaveBeenCalledTimes(1);

package/src/plugin.js

@@ -1,9 +1,34 @@
 import { DECORATOR_NAME } from './utils/constants.js';
-import { errors } from './errors/index.js';
+import { createNotImplementedError, errors } from './errors/index.js';
 import { parse } from './parser/index.js';
 
-const createRoute = (fastify, routes) => {
-  return ({ method, onRequest, operationId, schema, url, ...routeOptions }) => {
+const createRoute = (fastify, routes, notImplementedErrorMapper) => {
+  const missingRoutes = new Set(Object.values(routes));
+
+  const addMissingRoutes = () => {
+    missingRoutes.forEach(route => {
+      fastify.route({
+        ...route,
+        handler: () => {
+          if (typeof notImplementedErrorMapper === 'function') {
+            const error = notImplementedErrorMapper(createNotImplementedError());
+
+            if (error instanceof Error) {
+              throw error;
+            }
+
+            throw createNotImplementedError();
+          }
+
+          throw createNotImplementedError();
+        }
+      });
+    });
+
+    missingRoutes.clear();
+  };
+
+  const addRoute = ({ method, onRequest, operationId, schema, url, ...routeOptions }) => {
     const route = routes[operationId];
 
     // Throw an error if the operation is unknown.
@@ -19,6 +44,8 @@ const createRoute = (fastify, routes) => {
     // Check if there is a routeOptions.onRequest hook.
     if (typeof onRequest === 'function') {
       route.onRequest.push(onRequest);
+    } else if (Array.isArray(onRequest)) {
+      route.onRequest.push(...onRequest);
     }
 
     // Register a new route.
@@ -26,6 +53,13 @@ const createRoute = (fastify, routes) => {
       ...routes[operationId],
       ...routeOptions
     });
+
+    missingRoutes.delete(route);
+  };
+
+  return {
+    addMissingRoutes,
+    addRoute
   };
 };
 
@@ -34,10 +68,13 @@ const plugin = async (fastify, options) => {
 
   const routes = await parse(options);
 
+  const { addMissingRoutes, addRoute } = createRoute(fastify, routes, options.notImplementedErrorMapper);
+
   // Decorate fastify object.
   fastify.decorate(DECORATOR_NAME, {
     errors,
-    route: createRoute(fastify, routes)
+    installNotImplementedRoutes: addMissingRoutes,
+    route: addRoute
   });
 
   // Avoid decorating the request with reference types.
@@ -45,7 +82,7 @@ const plugin = async (fastify, options) => {
   fastify.decorateRequest(DECORATOR_NAME, null);
 
   // Instead, decorate each incoming request.
-  fastify.addHook('onRequest', async request => {
+  fastify.addHook('onRequest', async function openApiRouterGlobalOnRequestHook(request) {
     request[DECORATOR_NAME] = {
       operation: {},
       security: {},