Add documentation for implementing your own cookie validation.

Author: frank

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## [Unreleased]
 ### Changed
+- feat: added addCookieSchema option, see docs/cookieValidationHowTo.md
 
 ## [4.6.1] 14-06-2024
 ### Changed

README.md

@@ -182,6 +182,7 @@ The folder [examples/generated-javascript-project](examples/generated-javascript
 - fastify will by default coerce types, e.g when you expect a number a string like `"1"` will also pass validation, this can be reconfigured, see [Validation and Serialization](https://www.fastify.io/docs/latest/Reference/Validation-and-Serialization/).
 - fastify only supports one schema per route. So while the v3 standard allows for multiple content types per route, each with their own schema this is currently not going to work with fastify. Potential workarounds include a custom content type parser and merging schemas upfront using JSON schema `oneOf`.
 - the plugin aims to follow fastify and does not compensate for features that are possible according to the OpenApi specification but not possible in standard fastify (without plugins). This will keep the plugin lightweigth and maintainable. E.g. Fastify does not support cookie validation, while OpenApi v3 does.
+- in some cases however, the plugin may be able to provide you with data which could be used to enhance OpenApi support within your own Fastify application. Here is one possible way to perform [cookie validation](docs/cookieValidationHowTo.md)  yourself.
 - if you have special needs on querystring handling (e.g. arrays, objects etc) then fastify supports a [custom querystring parser](https://www.fastify.io/docs/latest/Server/#querystringparser). You might need to pass the AJV option `coerceTypes: 'array'` as an option to Fastify.
 - the plugin is an ECMAscript Module (aka ESM). If you are using Typescript then make sure that you have read: https://www.typescriptlang.org/docs/handbook/esm-node.html to avoid any confusion.
 - If you want to use a specification that consists of multiple files then please check out the page on [subschemas](docs/subSchemas.md) 

docs/cookieValidationHowTo.md

@@ -0,0 +1,54 @@
+### Implementing cookie validation
+
+The [OpenApi](https://www.openapis.org/) specification allows cookie validation, but Fastify itself does not validate or even parse cookies.
+
+The `fastify-openapi-glue` plugin is intentionally designed to work without requiring additional 3rd party plugins.
+However, it does provide a boolean option `addCookieSchema`  which tells it to insert JSON Schema describing OpenApi cookies into the Fastify [Routes options](https://fastify.dev/docs/latest/Reference/Routes/#routes-options).
+
+Using this `addCookieSchema` option, one possible way to implement cookie validation in your application might be:
+- Register a plugin for cookie parsing with Fastify (perhaps [fastify cookie plugin](https://github.com/fastify/fastify-cookie)).
+- Listen for Fastify's [`onRoute` Application Hook](https://fastify.dev/docs/latest/Reference/Hooks/#onroute).
+- In your `onRoute` handler:
+  - Check to see if `fastify-openapi-glue` found cookie specifications that it added to the `routeOptions`.
+  - If cookie schema is present, pre-compile it with Ajv and add the compiled schema to the `routeOptions.config` object.
+- Register a global Fastify [`preHandler`](https://fastify.dev/docs/latest/Reference/Hooks/#prehandler)
+- In your global `preHandler`:
+  - See if the invoked route has a cookie validator (pre-compiled by your `onRoute` handler).
+  - Validate the cookie (which your cookie parser should have already added to the `request`).
+- With your customizations in place, register `fastify-openapi-glue`.
+
+Example:
+```javascript
+// Register a plugin for cookie parsing
+fastify.register(cookie);
+
+// Hook into the route registration process to compile cookie schemas
+fastify.addHook('onRoute', (routeOptions) => {
+  const schema = routeOptions.schema;
+  /*
+   * schema.cookies will be added to the schema object if the
+   * 'addCookieSchema' option is passed to fastify-openapi-glue.
+   */
+  if (schema?.cookies) {
+    // Compile the cookie schema and store it in the route's context
+    routeOptions.config = routeOptions.config || {};
+    routeOptions.config.cookieValidator = ajv.compile(schema.cookies);
+  }
+});
+
+// Pre-handler hook to validate cookies using the precompiled schema
+fastify.addHook('preHandler', async (request, reply) => {
+  // See if this route has been configured with a cookie validator.
+  const cookieValidator = request.routeOptions.config?.cookieValidator;
+  if (cookieValidator) {
+    const valid = cookieValidator(request.cookies);
+    if (!valid) {
+      reply.status(400).send({error: 'Invalid cookies', details: cookieValidator.errors});
+      throw new Error('Invalid cookies');
+    }
+  }
+});
+
+// Magic!
+fastify.register(openapiGlue, options);
+```