fastify 5.7.1 → 5.7.3

package/AGENTS.md

@@ -0,0 +1,290 @@
+# AGENTS.md - Guide for AI Agents Working with Fastify
+
+This document provides information and guidelines for AI agents (such as GitHub Copilot, Cursor, pi, or other AI coding assistants) working with the Fastify codebase.
+
+## Project Overview
+
+Fastify is a high-performance web framework for Node.js focused on:
+- **Speed**: One of the fastest Node.js web frameworks
+- **Extensibility**: Powerful plugin architecture with hooks and decorators
+- **Schema-based**: JSON Schema validation and serialization
+- **Developer experience**: Expressive API with minimal overhead
+- **TypeScript support**: Full type definitions included
+
+**Current Version**: 5.7.1 (main branch)
+**Repository**: https://github.com/fastify/fastify
+
+## Repository Structure
+
+```
+fastify/
+├── docs/                 # Documentation (Guides and Reference)
+│   ├── Guides/          # Tutorials and how-to guides
+│   └── Reference/       # API documentation
+├── examples/            # Example applications and benchmarks
+├── lib/                 # Core library code
+├── test/                # Test files
+├── types/               # TypeScript type definitions
+├── build/               # Build scripts
+├── integration/         # Integration tests
+├── fastify.js           # Main entry point
+├── fastify.d.ts         # Main TypeScript definitions
+└── package.json         # Dependencies and scripts
+```
+
+## Key Files for Agents
+
+### Core Files
+- **`fastify.js`** - Main Fastify class and entry point
+- **`fastify.d.ts`** - TypeScript type definitions (keep these in sync)
+- **`lib/`** - All core functionality:
+  - `route.js` - Route handling
+  - `req-res.js` - Request and Reply objects
+  - `hooks.js` - Lifecycle hooks
+  - `plugin.js` - Plugin system
+  - `validation.js` - Schema validation
+  - `content-type-parser.js` - Body parsing
+  - `logger.js` - Pino logger integration
+
+### Configuration Files
+- **`package.json`** - Scripts, dependencies, and contributors
+- **`eslint.config.js`** - Linting configuration (uses neostandard)
+- **`.markdownlint-cli2.yaml`** - Markdown linting rules
+
+### Documentation Files
+- **`README.md`** - Project overview and quick start
+- **`CONTRIBUTING.md`** - Contribution guidelines
+- **`GOVERNANCE.md`** - Links to organization governance
+- **`SECURITY.md`** - Security policy
+- **`docs/Guides/Contributing.md`** - Detailed contributing guide
+- **`docs/Guides/Style-Guide.md`** - Coding style conventions
+
+## Testing Conventions
+
+### Test Framework
+Fastify uses **Borp** (a custom test runner) for testing.
+
+### Test Structure
+- Tests are in the **`test/`** directory
+- Test files follow the pattern: `test/<module>.test.js`
+- Integration tests are in **`integration/`** directory
+
+### Running Tests
+
+```bash
+# Run all tests
+npm test
+
+# Run unit tests only
+npm run unit
+
+# Run tests with coverage
+npm run coverage
+
+# Run tests in watch mode
+npm run test:watch
+
+# Run TypeScript type tests
+npm run test:typescript
+
+# Run CI tests (minimal)
+npm run test:ci
+```
+
+### Test Requirements
+- **100% line coverage** is required for all changes (enforced by CI)
+- Tests must pass on all supported Node.js versions
+- TypeScript types must be tested (using `tsd`)
+
+## Code Style and Conventions
+
+### Linting
+- Uses **Neostandard** JavaScript style guide
+- ESLint is configured in `eslint.config.js`
+- Run `npm run lint` to check code style
+- Run `npm run lint:fix` to auto-fix issues
+
+### Key Style Rules (from Style-Guide.md)
+- Use `const` and `let`, never `var`
+- Use arrow functions for callbacks
+- Use async/await instead of promises
+- Follow semicolon usage (neostandard enforces this)
+- Use template literals for string interpolation
+- Prefer functional methods (`map`, `filter`, `reduce`) over loops
+- Error-first callback pattern for async operations where needed
+
+### Naming Conventions
+- **Files**: kebab-case (`content-type-parser.js`)
+- **Variables**: camelCase
+- **Constants**: UPPER_SNAKE_CASE
+- **Classes**: PascalCase
+- **Private methods**: prefixed with `_`
+
+## Common Tasks
+
+### Adding a New Feature
+1. Implement the feature in `lib/`
+2. Add tests in `test/`
+3. Update TypeScript types in `fastify.d.ts` or `types/`
+4. Update documentation in `docs/`
+5. Run `npm test` to ensure all tests pass
+6. Run `npm run lint` to check code style
+7. Add changelog entry for release
+
+### Fixing a Bug
+1. Add a failing test case in `test/`
+2. Fix the bug in `lib/`
+3. Ensure all tests pass
+4. Check if TypeScript types need updating
+5. Update documentation if behavior changes
+
+### Working with Plugins
+- See `docs/Guides/Write-Plugin.md` for plugin authoring
+- See `docs/Guides/Plugins-Guide.md` for plugin usage
+- Plugin example: `lib/plugin.js`
+
+## Architecture Highlights
+
+### Core Components
+
+1. **Server (`fastify.js`)**
+   - Main Fastify class
+   - Server initialization and configuration
+   - Plugin system integration (via `avvio`)
+
+2. **Routing (`lib/route.js`)**
+   - Uses `find-my-way` for fast route matching
+   - Route registration and lookup
+   - Shorthand methods (get, post, put, delete, etc.)
+
+3. **Request/Response (`lib/req-res.js`)**
+   - Request object extensions
+   - Reply object with fluent API
+   - Decorator support
+
+4. **Hooks (`lib/hooks.js`)**
+   - Lifecycle hooks (onRequest, preHandler, etc.)
+   - Hook execution order and timing
+
+5. **Validation (`lib/validation.js`)**
+   - JSON Schema validation via AJV
+   - Response serialization
+   - Built-in error serializer
+
+6. **Content Type Parser (`lib/content-type-parser.js`)**
+   - Request body parsing
+   - Custom parser support
+   - JSON and other formats
+
+### Plugin System
+- Plugins are loaded asynchronously via `avvio`
+- Supports encapsulation (scoped plugins)
+- Hooks and decorators can be scoped
+- See `lib/plugin.js` for implementation
+
+## TypeScript Integration
+
+- TypeScript definitions are in `fastify.d.ts` and `types/`
+- Types must be tested with `tsd`
+- Run `npm run test:typescript` to verify types
+- Keep types in sync with JavaScript implementation
+
+## Performance Considerations
+
+Fastify prioritizes performance:
+- **Routes**: Pre-compiled functions for fast matching
+- **Validation**: Compiled JSON Schema validators
+- **Serialization**: Compiled serializers (fast-json-stringify)
+- **Logging**: Low-overhead Pino logger
+- **Caching**: Route context caching with `toad-cache`
+
+When making changes:
+- Profile performance impact for hot paths
+- Use benchmarks in `examples/benchmark/`
+- Run `npm run benchmark` to measure
+
+## Documentation Updates
+
+Documentation is critical for Fastify. When changing behavior:
+
+1. Update relevant docs in `docs/Reference/` for API changes
+2. Update `docs/Guides/` for usage pattern changes
+3. Check for broken links (CI validates this)
+4. Update examples in `examples/` if needed
+5. Run `npm run lint:markdown` to check docs
+
+## Pre-commit Checks
+
+Before submitting changes, ensure:
+
+1. ✅ All tests pass: `npm test`
+2. ✅ 100% coverage: `npm run coverage`
+3. ✅ Linting passes: `npm run lint`
+4. ✅ TypeScript types pass: `npm run test:typescript`
+5. ✅ Markdown linting passes: `npm run lint:markdown`
+6. ✅ Documentation is updated
+7. ✅ Examples still work if affected
+
+## Working with CI
+
+Fastify uses GitHub Actions for CI. Workflows are in `.github/workflows/`:
+- **`ci.yml`** - Main CI pipeline
+- **`package-manager-ci.yml`** - Tests multiple package managers
+- **`website.yml`** - Website deployment
+
+## Agent-Specific Tips
+
+### When Generating Code
+1. Check existing patterns in `lib/` before creating new patterns
+2. Follow the established error handling patterns
+3. Use async/await consistently
+4. Add appropriate hooks if extending lifecycle
+5. Consider TypeScript types from the start
+
+### When Refactoring
+1. Ensure all tests still pass
+2. Don't change public APIs without semver consideration
+3. Update TypeScript definitions if signatures change
+4. Check for deprecation needs
+5. Update documentation for changed behavior
+
+### When Analyzing Issues
+1. Check `test/` for usage examples
+2. Review relevant `docs/Reference/` files
+3. Look at similar implementations in `lib/`
+4. Consider the plugin system and encapsulation
+5. Check hook timing and order
+
+### Common Gotchas
+- **Encapsulation**: Plugins are isolated - decorators don't leak
+- **Hook order**: Hooks run in specific order (see docs/Reference/Hooks.md)
+- **Async boot**: Server starts asynchronously - use `ready()` or `after()`
+- **Error handling**: Use Fastify error classes from `@fastify/error`
+- **Validation**: Schemas are compiled - changes require recompilation
+
+## Key Dependencies
+
+- **`avvio`** - Plugin loading and boot
+- **`find-my-way`** - Fast HTTP router
+- **`fast-json-stringify`** - Response serialization
+- **`pino`** - Logging
+- **`@fastify/ajv-compiler`** - JSON Schema validation
+- **`light-my-request`** - HTTP injection for testing
+
+## Contact and Resources
+
+- **Documentation**: https://fastify.dev/
+- **Discord**: https://discord.gg/fastify
+- **GitHub Issues**: https://github.com/fastify/fastify/issues
+- **GitHub Discussions**: https://github.com/fastify/fastify/discussions
+- **Help**: https://github.com/fastify/help
+
+## Version Information
+
+- **Main branch**: Fastify v5
+- **v4 branch**: https://github.com/fastify/fastify/tree/4.x
+- **LTS Policy**: See `docs/Reference/LTS.md`
+
+---
+
+This document is maintained by the Fastify team. For questions or suggestions, please open an issue or discussion.

package/LICENSE

@@ -1,9 +1,6 @@
 MIT License
 
-Copyright (c) 2016-present The Fastify Team
-
-The Fastify team members are listed at https://github.com/fastify/fastify#team
-and in the README file.
+Copyright (c) 2016-present The Fastify Team (members are listed in the README file)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/SECURITY.md

@@ -46,10 +46,11 @@ explicitly enabled via configuration options
 ## Reporting vulnerabilities
 
 Individuals who find potential vulnerabilities in Fastify are invited to
-complete a vulnerability report via the dedicated pages:
+complete a vulnerability report via the GitHub Security page:
 
-1. [HackerOne](https://hackerone.com/fastify)
-2. [GitHub Security Advisory](https://github.com/fastify/fastify/security/advisories/new)
+https://github.com/fastify/fastify/security/advisories/new
+
+Note: Our [HackerOne](https://hackerone.com/fastify) program is now closed.
 
 ### Strict measures when reporting vulnerabilities
 

package/SPONSORS.md

@@ -9,7 +9,7 @@ or [GitHub Sponsors](https://github.com/sponsors/fastify)!
 
 ## Tier 4
 
-- [SerpApi](http://serpapi.com/)
+- [SerpApi](https://serpapi.com/?utm_source=fastify)
 
 ## Tier 3
 
@@ -17,7 +17,7 @@ or [GitHub Sponsors](https://github.com/sponsors/fastify)!
 - [Val Town, Inc.](https://opencollective.com/valtown)
 - [Handsontable - JavaScript Data Grid](https://handsontable.com/docs/react-data-grid/?utm_source=Fastify_GH&utm_medium=sponsorship&utm_campaign=library_sponsorship_2024)
 - [Lokalise - A Localization and Translation Software Tool](https://lokalise.com/?utm_source=Fastify_GH&utm_medium=sponsorship)
-- [Lambdatest](https://www.lambdatest.com/)
+- [TestMu AI](https://www.testmu.ai/)
 
 ## Tier 2
 

package/docs/Guides/Ecosystem.md

@@ -427,6 +427,8 @@ section.
   context to take place per API call within the Fastify lifecycle of calls.
 - [`fastify-http-errors-enhanced`](https://github.com/ShogunPanda/fastify-http-errors-enhanced)
   An error handling plugin for Fastify that uses enhanced HTTP errors.
+- [`fastify-http-exceptions`](https://github.com/bhouston/fastify-http-exceptions)
+  Typed HTTP status exceptions which are automatically converted into Fastify responses.
 - [`fastify-http2https`](https://github.com/lolo32/fastify-http2https) Redirect
   HTTP requests to HTTPS, both using the same port number, or different response
   on HTTP and HTTPS.
@@ -746,7 +748,6 @@ middlewares into Fastify plugins
 - [`typeorm-fastify-plugin`](https://github.com/jclemens24/fastify-typeorm) A simple
   and updated Typeorm plugin for use with Fastify.
 
-
 #### [Community Tools](#community-tools)
 
 - [`@fastify-userland/workflows`](https://github.com/fastify-userland/workflows)

package/docs/Guides/Plugins-Guide.md

@@ -204,12 +204,12 @@ of an *arrow function expression*.
 
 You can do the same for the `request` object:
 ```js
-fastify.decorate('getHeader', (req, header) => {
-  return req.headers[header]
+fastify.decorate('getBoolHeader', (req, name) => {
+  return req.headers[name] ?? false // We return `false` if header is missing
 })
 
 fastify.addHook('preHandler', (request, reply, done) => {
-  request.isHappy = fastify.getHeader(request.raw, 'happy')
+  request.isHappy = fastify.getBoolHeader(request, 'happy')
   done()
 })
 
@@ -219,14 +219,14 @@ fastify.get('/happiness', (request, reply) => {
 ```
 Again, it works, but it can be much better!
 ```js
-fastify.decorateRequest('setHeader', function (header) {
-  this.isHappy = this.headers[header]
+fastify.decorateRequest('setBoolHeader', function (name) {
+  this.isHappy = this.headers[name] ?? false
 })
 
 fastify.decorateRequest('isHappy', false) // This will be added to the Request object prototype, yay speed!
 
 fastify.addHook('preHandler', (request, reply, done) => {
-  request.setHeader('happy')
+  request.setBoolHeader('happy')
   done()
 })
 
@@ -337,11 +337,11 @@ fastify.register((instance, opts, done) => {
     }
   })
 
-  fastify.get('/plugin1', {config: {useUtil: true}}, (request, reply) => {
+  instance.get('/plugin1', {config: {useUtil: true}}, (request, reply) => {
     reply.send(request)
   })
 
-  fastify.get('/plugin2', (request, reply) => {
+  instance.get('/plugin2', (request, reply) => {
     reply.send(request)
   })
 

package/docs/Reference/Reply.md

@@ -671,9 +671,20 @@ fastify.get('/json', options, function (request, reply) {
 If you pass a string to `send` without a `Content-Type`, it will be sent as
 `text/plain; charset=utf-8`. If you set the `Content-Type` header and pass a
 string to `send`, it will be serialized with the custom serializer if one is
-set, otherwise, it will be sent unmodified (unless the `Content-Type` header is
-set to `application/json; charset=utf-8`, in which case it will be
-JSON-serialized like an object — see the section above).
+set, otherwise, it will be sent unmodified.
+
+> **Note:** Even when the `Content-Type` header is set to `application/json`,
+> strings are sent unmodified by default. To serialize a string as JSON, you
+> must set a custom serializer:
+
+```js
+fastify.get('/json-string', async function (request, reply) {
+  reply
+    .type('application/json; charset=utf-8')
+    .serializer(JSON.stringify)
+    .send('Hello') // Returns "Hello" (JSON-encoded string)
+})
+```
 ```js
 fastify.get('/json', options, function (request, reply) {
   reply.send('plain string')

package/docs/Reference/Server.md

@@ -534,7 +534,9 @@ recommend using a custom parser to convert only the keys to lowercase.
 ```js
 const qs = require('qs')
 const fastify = require('fastify')({
-  querystringParser: str => qs.parse(str)
+  routerOptions: {
+    querystringParser: str => qs.parse(str)
+  }
 })
 ```
 
@@ -544,7 +546,9 @@ like the example below for case insensitive keys and values:
 ```js
 const querystring = require('fast-querystring')
 const fastify = require('fastify')({
-  querystringParser: str => querystring.parse(str.toLowerCase())
+  routerOptions: {
+    querystringParser: str => querystring.parse(str.toLowerCase())
+  }
 })
 ```
 

package/docs/Reference/Validation-and-Serialization.md

@@ -675,9 +675,12 @@ const schema = {
       content: {
         'application/json': {
           schema: {
-            name: { type: 'string' },
-            image: { type: 'string' },
-            address: { type: 'string' }
+            type: 'object',
+            properties: {
+              name: { type: 'string' },
+              image: { type: 'string' },
+              address: { type: 'string' }
+            }
           }
         },
         'application/vnd.v1+json': {
@@ -692,8 +695,11 @@ const schema = {
       content: {
         'application/vnd.v2+json': {
           schema: {
-            fullName: { type: 'string' },
-            phone: { type: 'string' }
+            type: 'object',
+            properties: {
+              fullName: { type: 'string' },
+              phone: { type: 'string' }
+            }
           }
         }
       }
@@ -703,7 +709,10 @@ const schema = {
         // */* is match-all content-type
         '*/*': {
           schema: {
-            desc: { type: 'string' }
+            type: 'object',
+            properties: {
+              desc: { type: 'string' }
+            }
           }
         }
       }

package/fastify.js

@@ -1,6 +1,6 @@
 'use strict'
 
-const VERSION = '5.7.1'
+const VERSION = '5.7.2'
 
 const Avvio = require('avvio')
 const http = require('node:http')

package/lib/content-type-parser.js

@@ -3,6 +3,7 @@
 const { AsyncResource } = require('node:async_hooks')
 const { FifoMap: Fifo } = require('toad-cache')
 const { parse: secureJsonParse } = require('secure-json-parse')
+const ContentType = require('./content-type')
 const {
   kDefaultJsonParse,
   kContentTypeParser,
@@ -75,8 +76,13 @@ ContentTypeParser.prototype.add = function (contentType, opts, parserFn) {
     this.customParsers.set('', parser)
   } else {
     if (contentTypeIsString) {
-      this.parserList.unshift(contentType)
-      this.customParsers.set(contentType, parser)
+      const ct = new ContentType(contentType)
+      if (ct.isValid === false) {
+        throw new FST_ERR_CTP_INVALID_TYPE()
+      }
+      const normalizedContentType = ct.toString()
+      this.parserList.unshift(normalizedContentType)
+      this.customParsers.set(normalizedContentType, parser)
     } else {
       validateRegExp(contentType)
       this.parserRegExpList.unshift(contentType)
@@ -87,7 +93,7 @@ ContentTypeParser.prototype.add = function (contentType, opts, parserFn) {
 
 ContentTypeParser.prototype.hasParser = function (contentType) {
   if (typeof contentType === 'string') {
-    contentType = contentType.trim().toLowerCase()
+    contentType = new ContentType(contentType).toString()
   } else {
     if (!(contentType instanceof RegExp)) throw new FST_ERR_CTP_INVALID_TYPE()
     contentType = contentType.toString()
@@ -97,45 +103,49 @@ ContentTypeParser.prototype.hasParser = function (contentType) {
 }
 
 ContentTypeParser.prototype.existingParser = function (contentType) {
-  if (contentType === 'application/json' && this.customParsers.has(contentType)) {
-    return this.customParsers.get(contentType).fn !== this[kDefaultJsonParse]
-  }
-  if (contentType === 'text/plain' && this.customParsers.has(contentType)) {
-    return this.customParsers.get(contentType).fn !== defaultPlainTextParser
+  if (typeof contentType === 'string') {
+    const ct = new ContentType(contentType).toString()
+    if (contentType === 'application/json' && this.customParsers.has(contentType)) {
+      return this.customParsers.get(ct).fn !== this[kDefaultJsonParse]
+    }
+    if (contentType === 'text/plain' && this.customParsers.has(contentType)) {
+      return this.customParsers.get(ct).fn !== defaultPlainTextParser
+    }
   }
 
   return this.hasParser(contentType)
 }
 
 ContentTypeParser.prototype.getParser = function (contentType) {
-  let parser = this.customParsers.get(contentType)
-  if (parser !== undefined) return parser
-  parser = this.cache.get(contentType)
+  if (typeof contentType === 'string') {
+    contentType = new ContentType(contentType)
+  }
+  const ct = contentType.toString()
+
+  let parser = this.cache.get(ct)
   if (parser !== undefined) return parser
+  parser = this.customParsers.get(ct)
+  if (parser !== undefined) {
+    this.cache.set(ct, parser)
+    return parser
+  }
 
-  const caseInsensitiveContentType = contentType.toLowerCase()
-  for (let i = 0; i !== this.parserList.length; ++i) {
-    const parserListItem = this.parserList[i]
-    if (
-      caseInsensitiveContentType.slice(0, parserListItem.length) === parserListItem &&
-      (
-        caseInsensitiveContentType.length === parserListItem.length ||
-        caseInsensitiveContentType.charCodeAt(parserListItem.length) === 59 /* `;` */ ||
-        caseInsensitiveContentType.charCodeAt(parserListItem.length) === 32 /* ` ` */ ||
-        caseInsensitiveContentType.charCodeAt(parserListItem.length) === 9  /* `\t` */
-      )
-    ) {
-      parser = this.customParsers.get(parserListItem)
-      this.cache.set(contentType, parser)
-      return parser
-    }
+  // We have conflicting desires across our test suite. In some cases, we
+  // expect to get a parser by just passing the media-type. In others, we expect
+  // to get a parser registered under the media-type while also providing
+  // parameters. And in yet others, we expect to register a parser under the
+  // media-type and have it apply to any request with a header that starts
+  // with that type.
+  parser = this.customParsers.get(contentType.mediaType)
+  if (parser !== undefined) {
+    return parser
   }
 
   for (let j = 0; j !== this.parserRegExpList.length; ++j) {
     const parserRegExp = this.parserRegExpList[j]
-    if (parserRegExp.test(contentType)) {
+    if (parserRegExp.test(ct)) {
       parser = this.customParsers.get(parserRegExp.toString())
-      this.cache.set(contentType, parser)
+      this.cache.set(ct, parser)
       return parser
     }
   }
@@ -154,7 +164,7 @@ ContentTypeParser.prototype.remove = function (contentType) {
   let parsers
 
   if (typeof contentType === 'string') {
-    contentType = contentType.trim().toLowerCase()
+    contentType = new ContentType(contentType).toString()
     parsers = this.parserList
   } else {
     if (!(contentType instanceof RegExp)) throw new FST_ERR_CTP_INVALID_TYPE()