README.md

@gasket/plugin-middleware

The @gasket/plugin-middleware plugin provides an easy way to apply middleware to Express or Fastify.

Installation

To install the plugin, run:

npm i @gasket/plugin-middleware

Then, update your gasket.js configuration file to include the plugin:

// gasket.js

+ import pluginMiddleware from '@gasket/plugin-middleware';

export default makeGasket({
  plugins: [
+   pluginMiddleware
  ]
});

Configuration

You can configure the middleware settings under either the express or fastify sections in your gasket.js file, depending on which framework you are using.

Configuration Options

• compression (default: true): Enable or disable response compression. Set to false if compression is handled elsewhere.
• excludedRoutesRegex: (deprecated) Use middlewareInclusionRegex instead.
• middlewareInclusionRegex: A regular expression to filter request URLs and determine when Gasket middleware should run. You can use this to exclude routes like static resource paths.
• trustProxy: Enable the "trust proxy" option. Refer to the Fastify trust proxy documentation or the Express trust proxy documentation for more details.
• routes: A path or glob pattern pointing to files that export route-defining functions. These functions receive the app object (Fastify or Express) to attach handlers and middleware.

Example Configuration for Express

// gasket.js

export default makeGasket({
  plugins: {
    pluginMiddleware,
    pluginExpress
  },
  express: {
    compression: false,
    routes: 'api/*.js',
    middlewareInclusionRegex: /^(?!\/_next\/)/,
    trustProxy: true
  }
});

Example Configuration for Fastify

// gasket.js

export default makeGasket({
  plugins: {
    pluginMiddleware,
    pluginFastify
  },
  fastify: {
    compression: false,
    routes: 'api/*.js',
    middlewareInclusionRegex: /^(?!\/_next\/)/,
    trustProxy: true
  }
});

Middleware paths

You can define middleware paths in your gasket.js file using the middleware property. This property is an array of objects that map plugins to specific route or path patterns, allowing you to control which middleware is triggered for specific requests.

// gasket.js

export default makeGasket({
  ...
  middleware: [
    {
      plugin: 'gasket-plugin-example', // Name of the Gasket plugin
      paths: ['/api']
    },
    {
      plugin: '@some/gasket-plugin-example',
      paths: [/\/default/]
    },
    {
      plugin: '@another/gasket-plugin-example',
      paths: ['/proxy', /\/home/]
    }
  ]
  ...
});

Lifecycles

middleware

The middleware lifecycle is executed when the Fastify or Express server is created. It applies all returned functions as middleware.

export default {
  name: 'sample-plugin',
  hooks: {
    /**
    * Add Fastify middleware
    *
    * @param {Gasket} gasket The Gasket API
    * @param {Fastify} app - Fastify app instance
    * @returns {function|function[]} middleware(s)
    */
    middleware: function (gasket, app) {
      return require('x-xss-protection')();
    }
  }
}

Logging

This plugin attaches a logger object to the request object. This object has a metadata method that allows you to attach details to any log entry related to the request. For example, you can add the user ID to each log entry. When logging within the context of a request, use the req.logger object instead of the global gasket.logger so that contextual information is included in the log entry. Here is an example of how to attach metadata to req.logger object and how to use it:

function someMiddleware(req, res, next) {
  req.logger.metadata({ userId: req.user.id });
  next();
}

function someOtherMiddleware(req, res, next) {
  req.logger.info('Some log message');
  next();
}

You can also return an array if you need to inject multiple middleware functions.