feat: add customize content type parsers for api plugin

docs/docs/docker.md

@@ -531,8 +531,9 @@ That means you can swap the `CMD` instruction in the api server stage:
 
 ### Configuring the server
 
-There's two ways you can configure the server.
+There are three ways you may wish to configure the server.
 
+#### Underlying Fastify server
 First, you can configure how the underlying Fastify server is instantiated via the`fastifyServerOptions` passed to the `createServer` function:
 
 ```ts title="api/src/server.ts"
@@ -548,18 +549,10 @@ const server = await createServer({
 
 For the complete list of options, see [Fastify's documentation](https://fastify.dev/docs/latest/Reference/Server/#factory).
 
-Second, you can register Fastify plugins on the server instance:
+#### Configure the redwood API plugin
+Second, you may want to alter the behavior of redwood's API plugin itself. To do this we provide a `configureApiServer(server)` option where you can do anything you wish to the fastify instance before the API plugin is registered. Two examples are given below.
 
-```ts title="api/src/server.ts"
-const server = await createServer({
-  logger,
-})
-
-// highlight-next-line
-server.register(myFastifyPlugin)
-``` 
-
-#### Example: Compressing Payloads and Rate Limiting
+##### Example: Compressing Payloads and Rate Limiting
 
 Let's say that we want to compress payloads and add rate limiting.
 We want to compress payloads only if they're larger than 1KB, preferring deflate to gzip,
@@ -577,21 +570,23 @@ Then register them with the appropriate config:
 ```ts title="api/src/server.ts"
 const server = await createServer({
   logger,
+  async configureApiServer(server) {
+    await server.register(import('@fastify/compress'), {
+      global: true,
+      threshold: 1024,
+      encodings: ['deflate', 'gzip'],
+    })
+
+    await server.register(import('@fastify/rate-limit'), {
+      max: 100,
+      timeWindow: '5 minutes',
+    })
+  }
 })
 
-await server.register(import('@fastify/compress'), {
-  global: true,
-  threshold: 1024,
-  encodings: ['deflate', 'gzip'],
-})
-
-await server.register(import('@fastify/rate-limit'), {
-  max: 100,
-  timeWindow: '5 minutes',
-})
 ```
 
-#### Example: File Uploads
+##### Example: File Uploads
 
 If you try to POST file content to the api server such as images or PDFs, you may see the following error from Fastify:
 
@@ -613,19 +608,38 @@ For example, to support image file uploads you'd tell Fastify to allow `/^image\
 ```ts title="api/src/server.ts"
 const server = await createServer({
   logger,
-})
-
-server.addContentTypeParser(/^image\/.*/, (req, payload, done) => {
-  payload.on('end', () => {
-    done()
-  })
+  configureApiServer(server){
+    server.addContentTypeParser(/^image\/.*/, (req, payload, done) => {
+      payload.on('end', () => {
+        done()
+      })
+    })
+  }
 })
 ```
 
 The regular expression (`/^image\/.*/`) above allows all image content or MIME types because [they start with "image"](https://developer.mozilla.org/en-US/docs/Web/Media/Formats/Image_types).
 
 Now, when you POST those content types to a function served by the api server, you can access the file content on `event.body`.
 
+#### Additional Fastify plugins
+Finally, you can register additional Fastify plugins on the server instance:
+
+```ts title="api/src/server.ts"
+const server = await createServer({
+  logger,
+})
+
+// highlight-next-line
+server.register(myFastifyPlugin)
+``` 
+
+:::note Fastify encapsulation
+
+Fastify is built around the concept of [encapsulation](https://fastify.dev/docs/latest/Reference/Encapsulation/). It is important to note that redwood's API plugin cannot be mutated after it is registered, see [here](https://fastify.dev/docs/latest/Reference/Plugins/#asyncawait). This is why you must use the `configureApiServer` option to do as shown above. 
+
+:::
+
 ### The `start` method
 
 Since there's a few different ways to configure the host and port the server listens at, the server instance returned by `createServer` has a special `start` method:

packages/api-server/src/__tests__/createServer.test.ts

@@ -234,6 +234,7 @@ describe('resolveOptions', () => {
 
     expect(resolvedOptions).toEqual({
       apiRootPath: DEFAULT_CREATE_SERVER_OPTIONS.apiRootPath,
+      configureApiServer: DEFAULT_CREATE_SERVER_OPTIONS.configureApiServer,
       fastifyServerOptions: {
         requestTimeout:
           DEFAULT_CREATE_SERVER_OPTIONS.fastifyServerOptions.requestTimeout,

packages/api-server/src/createServer.ts

@@ -5,22 +5,19 @@ import chalk from 'chalk'
 import { config } from 'dotenv-defaults'
 import fg from 'fast-glob'
 import fastify from 'fastify'
-import type { FastifyListenOptions, FastifyInstance } from 'fastify'
 
 import type { GlobalContext } from '@redwoodjs/context'
 import { getAsyncStoreInstance } from '@redwoodjs/context/dist/store'
 import { getConfig, getPaths } from '@redwoodjs/project-config'
 
 import { resolveOptions } from './createServerHelpers'
-import type { CreateServerOptions } from './createServerHelpers'
+import type {
+  CreateServerOptions,
+  Server,
+  StartOptions,
+} from './createServerHelpers'
 import { redwoodFastifyAPI } from './plugins/api'
 
-type StartOptions = Omit<FastifyListenOptions, 'port' | 'host'>
-
-interface Server extends FastifyInstance {
-  start: (options?: StartOptions) => Promise<string>
-}
-
 // Load .env files if they haven't already been loaded. This makes importing this file effectful:
 //
 // ```js
@@ -51,6 +48,9 @@ if (!process.env.REDWOOD_ENV_FILES_LOADED) {
  *   const server = await createServer({
  *     logger,
  *     apiRootPath: 'api'
+ *     configureApiServer: (server) => {
+ *       // Configure the API server fastify instance, e.g. add content type parsers
+ *     },
  *   })
  *
  *   // Configure the returned fastify instance:
@@ -64,8 +64,13 @@ if (!process.env.REDWOOD_ENV_FILES_LOADED) {
  * ```
  */
 export async function createServer(options: CreateServerOptions = {}) {
-  const { apiRootPath, fastifyServerOptions, apiPort, apiHost } =
-    resolveOptions(options)
+  const {
+    apiRootPath,
+    fastifyServerOptions,
+    configureApiServer,
+    apiPort,
+    apiHost,
+  } = resolveOptions(options)
 
   // Warn about `api/server.config.js`
   const serverConfigPath = path.join(
@@ -114,6 +119,7 @@ export async function createServer(options: CreateServerOptions = {}) {
       fastGlobOptions: {
         ignore: ['**/dist/functions/graphql.js'],
       },
+      configureServer: configureApiServer,
     },
   })
 

packages/api-server/src/createServerHelpers.ts

@@ -1,11 +1,21 @@
 import { parseArgs } from 'util'
 
-import type { FastifyServerOptions } from 'fastify'
+import type {
+  FastifyListenOptions,
+  FastifyServerOptions,
+  FastifyInstance,
+} from 'fastify'
 
 import { coerceRootPath } from '@redwoodjs/fastify-web/dist/helpers'
 
 import { getAPIHost, getAPIPort } from './cliHelpers'
 
+export type StartOptions = Omit<FastifyListenOptions, 'port' | 'host'>
+
+export interface Server extends FastifyInstance {
+  start: (options?: StartOptions) => Promise<string>
+}
+
 export interface CreateServerOptions {
   /**
    * The prefix for all routes. Defaults to `/`.
@@ -23,6 +33,11 @@ export interface CreateServerOptions {
    */
   fastifyServerOptions?: Omit<FastifyServerOptions, 'logger'>
 
+  /**
+   * Customise the API server fastify plugin before it is registered
+   */
+  configureApiServer?: (server: Server) => void | Promise<void>
+
   /**
    * Whether to parse args or not. Defaults to `true`.
    */
@@ -45,6 +60,7 @@ export const DEFAULT_CREATE_SERVER_OPTIONS: DefaultCreateServerOptions = {
   fastifyServerOptions: {
     requestTimeout: 15_000,
   },
+  configureApiServer: () => {},
   parseArgs: true,
 }
 
@@ -74,7 +90,9 @@ export function resolveOptions(
         DEFAULT_CREATE_SERVER_OPTIONS.fastifyServerOptions.requestTimeout,
       logger: options.logger ?? DEFAULT_CREATE_SERVER_OPTIONS.logger,
     },
-
+    configureApiServer:
+      options.configureApiServer ??
+      DEFAULT_CREATE_SERVER_OPTIONS.configureApiServer,
     apiHost: getAPIHost(),
     apiPort: getAPIPort(),
   }

packages/api-server/src/plugins/api.ts

@@ -7,6 +7,7 @@ import type { GlobalContext } from '@redwoodjs/context'
 import { getAsyncStoreInstance } from '@redwoodjs/context/dist/store'
 import { coerceRootPath } from '@redwoodjs/fastify-web/dist/helpers'
 
+import type { Server } from '../createServerHelpers'
 import { loadFastifyConfig } from '../fastify'
 
 import { lambdaRequestHandler, loadFunctionsFromDist } from './lambdaLoader'
@@ -16,6 +17,7 @@ export interface RedwoodFastifyAPIOptions {
     apiRootPath?: string
     fastGlobOptions?: FastGlobOptions
     loadUserConfig?: boolean
+    configureServer?: (server: Server) => void | Promise<void>
   }
 }
 
@@ -59,4 +61,8 @@ export async function redwoodFastifyAPI(
   await loadFunctionsFromDist({
     fastGlobOptions: redwoodOptions.fastGlobOptions,
   })
+
+  if (redwoodOptions.configureServer) {
+    await redwoodOptions.configureServer(fastify as Server)
+  }
 }