fastify/fastify
github.com/fastify/fastify ↗ · 390 files · 2.8 MB
An efficient server implies a lower cost of the infrastructure, better responsiveness under load, and happy users.
Overview
Fastify is a Node.js HTTP framework for developers building API servers, packaged here as CommonJS with TypeScript declarations at version 6.0.0-alpha.4. Its core combines encapsulated plugins, route-specific request contexts, lifecycle hooks, compiled schema validation and serialization, and configurable HTTP transports. This brief examines the pinned commit 19d5be0daf1c0daace758efe3ea788f924ca1224 through public source inspection; it reports no executed tests or measured performance.
System map
The runtime centers on a factory exported as a CommonJS package, with separate TypeScript declarations. Fastify assembles transport, routing, request/reply behavior, and plugin boot rather than supplying a fixed application. Mutable facilities are scoped through plugin inheritance and symbol-keyed state. Database integrations belong to application plugins, while repository workflows exercise packaging and compatibility.
- package.json declares fastify.js as main, commonjs as module type, fastify.d.ts as declarations, and version 6.0.0-alpha.4.
- fastify() calls processOptions, buildRouting, build404, wrapRouting, createServer, and buildSchemaController to assemble an instance.
- The root owns symbol-keyed lifecycle state, child instances, hooks, parser configuration, and scoped Request/Reply constructors.
- Avvio is configured with autostart false and use exposed as register; Fastify installs its encapsulation override and replaces ready.
- getServerInstance selects a custom serverFactory, HTTP/2 secure or plain server, or HTTP/1 HTTPS/HTTP server.
- Default schema compiler factories are loaded from @fastify/ajv-compiler and @fastify/fast-json-stringify-compiler.
- The database guide explicitly describes Fastify as database agnostic and demonstrates separately registered database plugins.
- Repository commands separate lint, borp unit tests, TSTyche type tests, generated-code integrity, and prepublication checks.
Feature catalog
The user-facing product is a programmable server API. Developers declare routes, scope plugins, extend objects, configure parsers and schemas, and control transport and lifecycle behavior. Reply APIs support ordinary payloads as well as streams and Web API objects. Database and authentication examples show integrations supplied through plugins.
- Route shorthand methods include GET, HEAD, TRACE, DELETE, PATCH, POST, PUT, OPTIONS, QUERY, and all supported methods.
- route, hasRoute, and findRoute expose general registration and route discovery.
- The instance exposes addHook, shared schema access, compiler setters, reply serializer selection, and schema error formatting.
- Content parser APIs allow adding, inspecting, removing, and resetting parsers, including access to default JSON and text parsers.
- decorate, decorateRequest, decorateReply, and corresponding inspection APIs extend instance and per-request objects.
- inject offers simulated HTTP requests, lazily loads light-my-request, and boots an unstarted instance before dispatch.
- Reply.send recognizes Node streams, Web streams, Response objects, typed-array buffers, and ordinary strings.
- handlerTimeout starts a request deadline that aborts request.signal and sends an error if no reply has been sent.
- Custom not-found handlers, error handlers, child logger factories, and router constraint strategies are public instance features.
Data flow
Route definitions become contexts whose hooks and compiled schemas are finalized during boot. Incoming transport objects become scoped Request and Reply objects before entering the hook and parsing pipeline. Validation can transform request parts, and handler results enter the reply serializer and output hooks. State is predominantly instance and route state; documented persistence crosses into separately registered database clients.
- Route options populate Context with a bound handler, schema, configuration, compiler overrides, body limit, and handler timeout.
- router.on stores routeHandler and Context together; preReady subsequently binds inherited and route-local hooks.
- routeHandler derives a request ID and logger, then creates context.Request and context.Reply from raw transport objects and router outputs.
- runPreParsing initially stores request.raw as the payload stream and passes through a preParsing runner before handleRequest.
- For body-bearing methods, handleRequest chooses a parser using Content-Type; invalid media types produce 415.
- rawBody accumulates buffers, enforces received and encoded byte limits, checks declared content length, and decodes or copies once before parser invocation.
- Successful parsing assigns request.body and proceeds to handler; parsing failure marks the reply as an error and requests connection closure.
- validateParam passes parentData to Ajv-compatible validators and permits synchronous custom results to replace a request part through value.
- preSerializationHookEnd chooses reply-specific, instance-default, or schema-based serialization, then enters onSendHook.
- The documented Redis persistence path reads req.body.key/value, calls the plugin-provided redis.set, and replies from its completion callback.
Behavior traces
Three concrete core flows were followed through source: startup and listening, request handling and reply serialization, and shutdown. Injection provides another entry into the same handler after readiness. The database write example illustrates an application-owned persistence boundary rather than an implemented core store. These are source traces, not runtime observations.
- Startup begins fastify() → processOptions → buildRouting/build404 → wrapRouting → createServer → SchemaController construction.
- Plugin boot installs Avvio → override; override calls registerPlugin, then either reuses the parent or constructs an inherited child with copied scoped facilities.
- Promise listening follows listen → listenPromise → ready → transport server.listen; success resolves a logged address.
- For localhost, listening continues through multipleBindings → dns.lookup → additional server instances → onListenHookRunner.
- Request handling follows routeHandler → Request/Reply creation → onRequestHookRunner → runPreParsing → handleRequest.
- After parsing, handler → preValidationCallback → validateSchema → validationCompleted → preHandlerCallback → context.handler; results use wrapThenable or reply.send.
- Object reply serialization follows preSerializationHook → preSerializationHookEnd → serializer selection → onSendHook → onSendEnd.
- Error sending enters onErrorHook; handleError selects the current or next inherited error handler, invokes it, and falls back to serialized transport output.
- Shutdown marks closing, closes routes, runs preClose, handles configured forced socket closure and available HTTP/2 session cleanup, then calls server.close unless an unstarted custom serverFactory instance takes the nextTick completion branch.
- The documented persistence flow is register Redis plugin → POST /foo → redis.set(req.body.key, req.body.value) → completion reply; it is an example integration.
Testing signals
Tests and CI were inspected, not executed; no passing result is asserted. The inspected runtime tests use node:test, selected by borp, while type assertions use TSTyche. CI defines operating-system, runtime, packaging, coverage, and integration checks. Inspection is bounded and does not establish exhaustive coverage or application-plugin correctness.
- borp selects test/**/*.test.js and test/**/*.test.mjs; inspected injection tests import node:test.
- npm test combines lint, unit, and type checks; test:ci omits lint and runs unit plus types.
- Injection tests assert readiness waiting, JSON payload, status code, and content length.
- Prototype-poisoning tests use real listen/fetch requests and assert rejection, removal, and ignore-policy behavior.
- Handler-timeout tests cover option validation, lazy AbortSignal creation, and client-disconnect abortion using a TCP connection.
- TSTyche provider tests assert unknown defaults, provider remapping, explicit overrides, and TypeBox-derived typing.
- Primary unit CI defines Node 24/26 across macOS, Ubuntu, and Windows, after quality and both coverage jobs.
- The coverage command requires 100 percent lines; this is a configured threshold rather than an observed coverage result.
- Production-install integration CI starts integration/server.js and invokes a shell smoke test covering GET, POST, PUT, and DELETE responses.
- esbuild and webpack fixtures define bundle-and-test scripts; alternative-runtime packaging CI invokes both.
- CITGM tests selected external plugins by linking this Fastify checkout into each plugin's own test environment; several database entries are commented out.
Risk map
The principal trust boundaries are request bytes, forwarding headers, application-supplied schemas, and plugin code. The source includes explicit defenses and warnings at several of these boundaries. Shutdown and hijacked responses require coordinated resource cleanup across modules. These are source observations and labeled hypotheses, not confirmed vulnerabilities; no whole-repository absence or exploitability is claimed.
- Schemas are a code-execution trust boundary: documentation warns that validation and serialization use new Function and must not accept user-provided schemas.
- The guide warns against database access during initial async validation because of denial-of-service exposure, recommending preHandler instead.
- External header-schema references retain original case and cannot safely be globally normalized; compilation detects them and emits FSTSEC002.
- Async validator data is treated as pass/fail rather than unwrapped as error/value, explicitly preventing payload fields from replacing request parts or injecting validation errors.
- Body buffering checks both decoded received length and reported encoded length, with separate declared Content-Length verification.
- JSON parsing delegates prototype and constructor handling to secure-json-parse; tests demonstrate that the ignore option permits observable prototype effects through Object.assign.
- Forwarded host and protocol are consumed only when proxyFn trusts the direct socket peer, making trustProxy policy security-sensitive.
- Default error serialization includes error.message, and failed serialization constructs a fallback using both serializer and original error messages.
- Hypothesis: timeout and hijack changes have broad cleanup risk because routeHandler stores AbortController/timer/socket metadata and Reply.hijack removes associated listeners and metadata. (inferred)
- Alternative-runtime unit CI uses continue-on-error, so its configured failures do not provide the same gating signal as an ordinary mandatory job.
- Package-manager CI downloads and pipes a Yarn installer into bash; CITGM derives plugin checkout coordinates from npm registry metadata and runs external package tests.
Extension points
Plugins and encapsulation are the main composition mechanism. Public hooks, decorators, parsers, schema compilers, and constraint strategies offer narrower extension seams. Transport and error handling can also be replaced. These facilities have lifecycle and inheritance rules that extensions must preserve.
- register is Avvio's exposed use API, and override implements Fastify-specific plugin encapsulation.
- Plugin metadata is read from Symbol.for('plugin-meta'), while Symbol.for('skip-override') requests parent-scope reuse.
- registerPlugin validates async handler shape, Fastify version, required decorators, and declared plugin dependencies.
- onRegister hooks receive each new child instance and options after scope construction.
- onRoute hooks can inspect or alter route options before Context construction; lifecycle hooks combine instance and route handlers at preReady.
- schemaController accepts a bucket factory and compiler factories; child controllers seed their schema bucket from parent schemas.
- setValidatorCompiler and setSerializerCompiler clone compiler-factory configuration and adapt a supplied compiler into a reusable builder.
- addContentTypeParser supports multiple content types and inherits the instance body limit; registration is rejected after startup.
- serverFactory receives the HTTP handler and options and returns a user-supplied transport server.
- Constraint strategies, child logger factories, decorators, and error handlers are exposed through instance methods.
Contributor handoff
Start from package wiring, factory assembly, and lifecycle documentation, then trace the exact changed behavior into its modules. Preserve plugin scope boundaries and boot-time context finalization. Tests and CI were inspected, not executed; their existence is not a passing result. The inventory is bounded, and generated-code checks or runtime verification require authorization beyond this read-only investigation.
- Read package.json and fastify.js first to establish package entry, declaration entry, scripts, and runtime assembly.
- Use Lifecycle and Encapsulation references alongside implementation to understand hook ordering and parent/child visibility.
- Changes to scoped mutable facilities must account for plugin-override's copying of Request, Reply, parsers, hooks, prefixes, and schema controllers.
- Route contexts are finalized during preReady, including hook binding, constructor optimization, 404 association, and schema compilation.
- Preserve explicit undefined checks for boolean JSON schemas; false schemas must still trigger compiler setup.
- Follow neostandard with TypeScript enabled, no trailing commas, and the configured 120-character rule exceptions.
- Generated config-validator and error-serializer are excluded from lint; integrity verification rebuilds them and compares Git diffs.
- When execution is authorized, existing broad verification entrypoints are npm run unit, npm run test:types, npm run lint, and npm run test:ci; none was executed for this brief.
- Type-provider behavior has separate declaration assertions, so runtime success alone would not validate provider inference.
- Do not infer database integration correctness from the core smoke fixture: its inspected handlers return static or path-derived responses, while database operations appear in plugin examples.
- Treat CI matrices and coverage thresholds as inspected configuration, not execution evidence; broader compatibility includes external workflow implementations outside this repository.
Languages
| Language | Files | Share of source |
|---|---|---|
| JavaScript | 263 | 89% |
| Markdown | 51 | docs/config |
| TypeScript | 33 | 11% |
| YAML | 25 | docs/config |
| JSON | 6 | docs/config |
| Shell | 1 | 0% |
Start reading here
Probable source entrypoint: lib/ — inferred from the directory tree and manifest, not the upstream docs.
Source roots
lib/ (31 files)
Source layout — lib/
| Path | Files |
|---|---|
lib/content-type-parser.js | 1 |
lib/content-type.js | 1 |
lib/decorate.js | 1 |
lib/error-handler.js | 1 |
lib/error-serializer.js | 1 |
lib/error-status.js | 1 |
lib/hooks.js | 1 |
lib/initial-config-validation.js | 1 |
lib/log-controller.js | 1 |
lib/logger-factory.js | 1 |
lib/noop-set.js | 1 |
lib/plugin-override.js | 1 |
lib/reply.js | 1 |
lib/req-id-gen-factory.js | 1 |
Repository structure
| Top-level path | Files |
|---|---|
test/ | 232 |
docs/ | 44 |
lib/ | 31 |
.github/ | 24 |
examples/ | 19 |
types/ | 15 |
integration/ | 2 |
scripts/ | 1 |
Docs found: CONTRIBUTING.mdREADME.mddocs/Guides/Benchmarking.mddocs/Guides/Contributing.mddocs/Guides/Database.mddocs/Guides/Delay-Accepting-Requests.mddocs/Guides/Detecting-When-Clients-Abort.mddocs/Guides/Ecosystem.mddocs/Guides/Fluent-Schema.mddocs/Guides/Getting-Started.md
Package
package.json — fastify v6.0.0-alpha.4, 50 declared dependencies.
@fastify/ajv-compiler@fastify/error@fastify/fast-json-stringify-compiler@fastify/proxy-addr@jsumners/line-reporter@stylistic/eslint-plugin@stylistic/eslint-plugin-js@types/nodeJSONStreamabstract-loggingajvajv-errors
CI & config entrypoints
README.md— Repository readme.github/workflows/lock-threads.yml— GitHub Actions workflow.github/workflows/ci-alternative-runtime.yml— GitHub Actions workflow.github/workflows/package-manager-ci.yml— GitHub Actions workflow.github/workflows/backport.yml— GitHub Actions workflow.github/workflows/validate-ecosystem-links.yml— GitHub Actions workflow.github/workflows/labeler.yml— GitHub Actions workflow.github/workflows/citgm.yml— GitHub Actions workflow.github/workflows/md-lint.yml— GitHub Actions workflow.github/workflows/citgm-package.yml— GitHub Actions workflow
Structural health signals
Average score 7/10 across 96 analyzed source files; 29 hotspots surfaced.
test/internals/reply.test.js— 2048 lines, score 4.5 (Large file, Deep nesting)test/schema-validation.test.js— 1995 lines, score 5 (Large file, Deep nesting)test/internals/request-validate.test.js— 1402 lines, score 5 (Large file, Deep nesting)
These are deterministic review leads — size, churn, and structural signals — not proof of a bug in this project.
Recent history
19d5be0daf1c2026-09-29 — fix: resolve reply.mediaType from raw response headers (#7054)d174a98e1a542026-09-28 — docs: list fastify-mariadb as a community plugin (#7062)bc25b7499ace2026-09-27 — fix: remove error when HTTP QUERY request has empty body (#6929)c3051e5b60c02026-09-26 — fix: omit absent compileSerializationSchema metadata instead of passing null (#7001)2e3ebc5f984e2026-09-26 — perf: avoid resetting the level of request child loggers (#7056)