@gasket/plugin-fastify 8.0.0-next.1 → 8.0.0-next.3

package/README.md

@@ -24,12 +24,22 @@ export default makeGasket({
 });
 ```
 
+## Fastify Version Support
+
+This plugin supports both Fastify v4 and v5 through an internal adapter pattern. The appropriate version-specific adapter is automatically selected based on your installed Fastify version.
+
+### Fastify v4
+- **Installation**: `npm install fastify@^4`
+
+### Fastify v5
+- **Installation**: `npm install fastify@^5`
+
+The plugin automatically detects your Fastify version and applies the correct configuration. No manual configuration is required.
+
 ## Configuration
 
 All the configurations for the plugin are added under `fastify` in the config:
 
-- `compression`: true by default. Can be set to false if applying compression
-  differently.
 - `trustProxy`: Enable trust proxy option, [see Fastify documentation for possible values](https://fastify.dev/docs/latest/Reference/Server/#trustproxy)
 - `disableRequestLogging`: Turn off request logging, true by default
 
@@ -41,8 +51,6 @@ export default makeGasket({
     pluginFastify
   ],
   fastify: {
-    compression: false,
-    excludedRoutesRegex: /^(?!\/_next\/)/,
     trustProxy: true
   }
 });
@@ -70,8 +78,7 @@ export default {
 
 ### fastify
 
-Executed **after** the `middleware` event for when you need full control over
-the `fastify` instance.
+Used to add routes and middleware directly to the `fastify` instance.
 
 ```js
 export default {
@@ -82,7 +89,6 @@ export default {
     *
     * @param {Gasket} gasket The Gasket API
     * @param {Fastify} fastify Fastify app instance
-    * @returns {function|function[]} middleware(s)
     */
     fastify: async function (gasket, fastify) {
     }
@@ -92,20 +98,24 @@ export default {
 
 ### errorMiddleware
 
-Executed after the `fastify` event. All middleware functions returned from this
-hook will be applied to Fastify.
+Executed after the `fastify` event. All error handler functions returned from this
+hook will be applied to Fastify in order.
 
 ```js
 export default {
   name: 'sample-plugin',
   hooks: {
     /**
-    * Add Fastify error middlewares
+    * Add error handling for Fastify
     *
     * @param {Gasket} gasket The Gasket API
-    * @returns {function|function[]} error middleware(s)
+    * @returns {function|function[]} error handler(s)
     */
     errorMiddleware: function (gasket) {
+      return function (err, req, res, next) {
+        // handle error or pass to next handler
+        next(err);
+      };
     }
   }
 };

package/lib/adapters/adapter-factory.js

@@ -0,0 +1,46 @@
+import { createRequire } from 'module';
+import { FastifyV4Adapter } from './fastify-v4-adapter.js';
+import { FastifyV5Adapter } from './fastify-v5-adapter.js';
+
+const require = createRequire(import.meta.url);
+
+/**
+ * Detect the installed Fastify version.
+ * Reads the version from fastify/package.json in node_modules.
+ * This works reliably with npm, pnpm, yarn, and bun.
+ * @returns {string} - Version string (e.g., '5.2.1')
+ */
+export function detectFastifyVersion() {
+  try {
+    const fastifyModule = require('fastify/package.json');
+    return fastifyModule.version;
+  } catch (err) {
+    throw new Error(
+      'Could not detect Fastify version. Ensure fastify is installed.\n' +
+      `Error: ${err.message}`
+    );
+  }
+}
+
+/**
+ * Create the appropriate Fastify adapter based on the installed Fastify version.
+ * Automatically detects the version from fastify/package.json.
+ * @returns {import('./base-adapter.js').FastifyAdapter} - Adapter instance
+ */
+export function createFastifyAdapter() {
+  const version = detectFastifyVersion();
+  const majorVersion = parseInt(version.split('.')[0], 10);
+
+  switch (majorVersion) {
+    case 4:
+      return new FastifyV4Adapter();
+    case 5:
+      return new FastifyV5Adapter();
+    default:
+      throw new Error(
+        `Unsupported Fastify version: ${version}\n` +
+        'Gasket supports Fastify v4 and v5. Please upgrade or downgrade Fastify, ' +
+        'or open an issue at https://github.com/godaddy/gasket'
+      );
+  }
+}

package/lib/adapters/base-adapter.js

@@ -0,0 +1,30 @@
+/**
+ * Base abstract class for Fastify version adapters.
+ * Provides a common interface for creating and configuring Fastify instances
+ * across different major versions.
+ * @abstract
+ */
+export class FastifyAdapter {
+  constructor() {
+    if (new.target === FastifyAdapter) {
+      throw new Error('FastifyAdapter is an abstract class and cannot be instantiated directly');
+    }
+  }
+
+  /**
+   * Create a Fastify instance with version-specific configuration.
+   * Subclasses must implement this method to handle version-specific options.
+   * @abstract
+   * @param {object} config - Fastify configuration options
+   * @param {boolean} [config.trustProxy] - Trust proxy headers
+   * @param {object} [config.https] - HTTPS configuration
+   * @param {boolean} [config.http2] - Enable HTTP/2
+   * @param {boolean} [config.disableRequestLogging] - Disable request logging
+   * @param {object} logger - Gasket logger instance
+   * @returns {ReturnType<typeof import('fastify').default>} - Configured Fastify instance
+   */
+  // eslint-disable-next-line no-unused-vars
+  createInstance(config, logger) {
+    throw new Error('createInstance() must be implemented by subclass');
+  }
+}

package/lib/adapters/fastify-v4-adapter.js

@@ -0,0 +1,55 @@
+import fastify from 'fastify';
+import { FastifyAdapter } from './base-adapter.js';
+
+const fallbackMap = {
+  fatal: 'error',
+  trace: 'debug'
+};
+
+/**
+ * Adapter for Fastify v4.x
+ *
+ * Key differences from v5:
+ * - Uses 'logger' option (not 'loggerInstance')
+ * - No 'useSemicolonDelimiter' option
+ * - Supports Node.js v14+
+ */
+export class FastifyV4Adapter extends FastifyAdapter {
+  /**
+   * Align Gasket logger with Fastify v4 requirements.
+   * Ensures 'fatal' and 'trace' log levels exist.
+   * @param {object} logger - Gasket logger instance
+   * @returns {object} - Fastify-compatible logger
+   */
+  alignLogger(logger) {
+    const fastifyLogger = logger;
+    ['fatal', 'trace'].forEach(level => {
+      if (!logger[level]) {
+        fastifyLogger[level] = logger[fallbackMap[level]];
+      }
+    });
+    return fastifyLogger;
+  }
+
+  /**
+   * Create a Fastify v4 instance.
+   * @param {object} config - Fastify configuration
+   * @param {object} logger - Gasket logger
+   * @returns {ReturnType<typeof import('fastify').default>} - Configured Fastify v4 instance
+   */
+  createInstance(config, logger) {
+    const { trustProxy = false, disableRequestLogging = true, https, http2, ...restConfig } = config;
+
+    const fastifyLogger = this.alignLogger(logger);
+
+    // Fastify v4 uses 'logger' option
+    return fastify({
+      logger: fastifyLogger,
+      trustProxy,
+      disableRequestLogging,
+      https,
+      http2,
+      ...restConfig
+    });
+  }
+}

package/lib/adapters/fastify-v5-adapter.js

@@ -0,0 +1,67 @@
+import fastify from 'fastify';
+import { FastifyAdapter } from './base-adapter.js';
+
+const fallbackMap = {
+  fatal: 'error',
+  trace: 'debug'
+};
+
+/**
+ * Adapter for Fastify v5.x
+ *
+ * Key differences from v4:
+ * - Uses 'loggerInstance' option (not 'logger')
+ * - Adds 'useSemicolonDelimiter' option (defaults to true)
+ * - Requires Node.js v20+
+ * - Stricter JSON Schema validation
+ */
+export class FastifyV5Adapter extends FastifyAdapter {
+  /**
+   * Align Gasket logger with Fastify v5 requirements.
+   * Ensures 'fatal' and 'trace' log levels exist.
+   * @param {object} logger - Gasket logger instance
+   * @returns {object} - Fastify-compatible logger
+   */
+  alignLogger(logger) {
+    const fastifyLogger = logger;
+    ['fatal', 'trace'].forEach(level => {
+      if (!logger[level]) {
+        fastifyLogger[level] = logger[fallbackMap[level]];
+      }
+    });
+    return fastifyLogger;
+  }
+
+  /**
+   * Create a Fastify v5 instance.
+   * @param {object} config - Fastify configuration
+   * @param {object} logger - Gasket logger
+   * @returns {ReturnType<typeof import('fastify').default>} - Configured Fastify v5 instance
+   */
+  createInstance(config, logger) {
+    const {
+      trustProxy = false,
+      disableRequestLogging = true,
+      https,
+      http2,
+      useSemicolonDelimiter = true,
+      ...restConfig
+    } = config;
+
+    const fastifyLogger = this.alignLogger(logger);
+
+    // Fastify v5 uses 'loggerInstance' instead of 'logger'
+    // Router options are nested under 'routerOptions' to avoid deprecation warnings
+    return fastify({
+      loggerInstance: fastifyLogger,
+      trustProxy,
+      disableRequestLogging,
+      https,
+      http2,
+      routerOptions: {
+        useSemicolonDelimiter
+      },
+      ...restConfig
+    });
+  }
+}

package/lib/adapters/index.js

@@ -0,0 +1,4 @@
+export { FastifyAdapter } from './base-adapter.js';
+export { FastifyV4Adapter } from './fastify-v4-adapter.js';
+export { FastifyV5Adapter } from './fastify-v5-adapter.js';
+export { createFastifyAdapter, detectFastifyVersion } from './adapter-factory.js';

package/lib/create-servers.js

@@ -5,23 +5,33 @@ import { getAppInstance } from './utils.js';
 
 /**
  * Create the Fastify instance and setup the lifecycle hooks.
- * Fastify is compatible with express middleware out of the box, so we can
- * use the same middleware lifecycles.
  * @type {import('@gasket/core').HookHandler<'createServers'>}
  */
 export default async function createServers(gasket, serverOpts) {
-  /** Cast to Fastify + Express hybrid because Gasket adds `.use()` via @fastify/express plugin */
-  const app = /** @type {import('fastify').FastifyInstance & { use: Function }} */ (getAppInstance(gasket));
+  const app = getAppInstance(gasket);
 
   // allow consuming apps to directly append options to their server
   await gasket.exec('fastify', app);
 
   const postRenderingStacks = (await gasket.exec('errorMiddleware')).filter(Boolean);
-  postRenderingStacks.forEach((stack) => {
-    /** @type {import('connect').NextHandleFunction} */
-    const middleware = stack;
-    app.use(middleware);
-  });
+  if (postRenderingStacks.length) {
+    // Fastify only supports one setErrorHandler per scope, so all Express-style
+    // error handlers (err, req, res, next) are chained manually through a single
+    // handler. request.raw and reply.raw expose the underlying Node.js
+    // IncomingMessage and ServerResponse that Express-style handlers expect.
+    app.setErrorHandler((error, request, reply) => {
+      let index = 0;
+      const next = (err) => {
+        const current = err || error;
+        if (index < postRenderingStacks.length) {
+          postRenderingStacks[index++](current, request.raw, reply.raw, next);
+        } else if (!reply.sent) {
+          reply.send(current);
+        }
+      };
+      next(error);
+    });
+  }
 
   return {
     ...serverOpts,

package/lib/index.d.ts

@@ -2,8 +2,6 @@ import type { MaybeAsync, MaybeMultiple, Plugin } from '@gasket/core';
 import type { Logger } from '@gasket/plugin-logger';
 import type {
   FastifyInstance,
-  FastifyRequest,
-  FastifyReply,
   FastifyServerOptions,
   FastifyBaseLogger,
   FastifyTypeProviderDefault,
@@ -12,8 +10,6 @@ import type {
 import type { IncomingMessage, ServerResponse } from 'http';
 
 export interface FastifyConfig {
-  /** Enable compression */
-  compression?: boolean;
   /** Trust proxy configuration */
   trustProxy?: FastifyServerOptions['trustProxy'];
   /** Fastify request logging per route */
@@ -36,11 +32,11 @@ declare module '@gasket/core' {
   }
 
 
-  /** Error handler function type */
+  /** Error handler function type (Express-style, receives raw Node.js req/res) */
   type ErrorHandler = (
     error: Error,
-    req: FastifyRequest,
-    res: FastifyReply,
+    req: IncomingMessage,
+    res: ServerResponse,
     next: (error?: Error) => void
   ) => void;
 

package/lib/index.js

@@ -31,8 +31,7 @@ const plugin = {
             method: 'exec',
             description: 'Modify the Fastify instance to for adding endpoints',
             link: 'README.md#express',
-            parent: 'createServers',
-            after: 'middleware'
+            parent: 'createServers'
           },
           {
             name: 'errorMiddleware',
@@ -50,19 +49,6 @@ const plugin = {
             link: 'README.md#configuration',
             description: 'Fastify configuration object',
             type: 'object'
-          },
-          {
-            name: 'fastify.compression',
-            link: 'README.md#configuration',
-            description: 'Automatic compression',
-            type: 'boolean',
-            default: true
-          },
-          {
-            name: 'fastify.excludedRoutesRegex',
-            link: 'README.md#configuration',
-            description: 'Routes to be excluded based on a regex',
-            type: 'RegExp'
           }
         ]
       };

package/lib/utils.js

@@ -1,29 +1,9 @@
 // @ts-nocheck
 
-import fastify from 'fastify';
-
-const fallbackMap = {
-  fatal: 'error',
-  trace: 'debug'
-};
-
-/**
- * A helper function to ensure that all the required log levels
- * for a Fastify server are present.
- * @type {import('@gasket/plugin-fastify').alignLogger}
- */
-function alignLogger(logger) {
-  const fastifyLogger = logger;
-  ['fatal', 'trace'].map(level => {
-    if (!logger[level]) {
-      fastifyLogger[level] = logger[fallbackMap[level]];
-    }
-  });
-
-  return fastifyLogger;
-}
+import { createFastifyAdapter } from './adapters/index.js';
 
 let instance = null;
+let adapter = null;
 
 /**
  * Get the Fastify instance.
@@ -33,21 +13,29 @@ let instance = null;
 export function getAppInstance(gasket) {
   if (!instance) {
     const { fastify: fastifyConfig = {}, http2, https } = gasket.config;
-    const { trustProxy = false, disableRequestLogging = true } = fastifyConfig;
-    const fastifyLogger = alignLogger(gasket.logger);
 
-    instance = fastify({ logger: fastifyLogger, trustProxy, https, http2, disableRequestLogging });
+    // Create the appropriate adapter for the installed Fastify version
+    adapter = createFastifyAdapter();
+
+    // Use the adapter to create the Fastify instance
+    instance = adapter.createInstance(
+      {
+        ...fastifyConfig,
+        https,
+        http2
+      },
+      gasket.logger
+    );
   }
 
   return instance;
 }
 
-export { alignLogger };
-
 /**
  * Clear the Fastify app instance (for testing only)
  * @returns {void}
  */
 export function testClearAppInstance() {
   instance = null;
+  adapter = null;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gasket/plugin-fastify",
-  "version": "8.0.0-next.1",
+  "version": "8.0.0-next.3",
   "description": "Adds fastify support to your application",
   "type": "module",
   "types": "./lib/index.d.ts",
@@ -16,7 +16,10 @@
     },
     "./package.json": "./package.json"
   },
-  "repository": "godaddy/gasket.git",
+  "repository": {
+    "type": "git",
+    "url": "godaddy/gasket.git"
+  },
   "publishConfig": {
     "access": "public"
   },
@@ -29,22 +32,18 @@
   "license": "MIT",
   "bugs": "https://github.com/godaddy/gasket/issues",
   "homepage": "https://github.com/godaddy/gasket/tree/main/packages/gasket-plugin-fastify",
-  "dependencies": {
-    "@fastify/express": "^3.0.0",
-    "fastify": "^4.29.1"
-  },
   "devDependencies": {
     "@types/connect": "^3.4.38",
-    "fastify": "^4.29.1",
+    "fastify": "^5.0.0",
     "vitest": "^3.2.0",
-    "@gasket/core": "^8.0.0-next.1",
+    "@gasket/core": "^8.0.0-next.2",
     "@gasket/plugin-https": "^8.0.0-next.1",
     "@gasket/plugin-logger": "^8.0.0-next.1",
     "@gasket/plugin-metadata": "^8.0.0-next.1",
-    "create-gasket-app": "^8.0.0-next.1"
+    "create-gasket-app": "^8.0.0-next.2"
   },
   "peerDependencies": {
-    "fastify": "^4.29.1"
+    "fastify": "^4.29.1 || ^5.0.0"
   },
   "scripts": {
     "lint": "eslint .",