Fastify, compiled before the first request.

The engines are importsbreakdown

Each dependency owns one mechanism and exposes it through a small interface. avvio runs the plugin graph, find-my-way answers lookups, the two compilers turn schemas into functions, and pino and light-my-request sit at the edges.

The shapes, in codebreakdown

The three objects your code touches, declared the way the shipped types declare them (types/instance.d.ts, types/request.d.ts, types/reply.d.ts), with the generics folded away. Return types are the real ones: most reply methods return the reply so they chain; most instance registration methods return the instance for the same reason.

interface FastifyInstance {  server: RawServer  log: FastifyBaseLogger  prefix: string  pluginName: string  version: string  initialConfig: Readonly<FastifyServerOptions>   register(plugin: FastifyPluginAsync | FastifyPluginCallback, opts?: object): this  after(listener?: (err: Error | null) => void): this & PromiseLike<void>  ready(listener?: (err: Error | null) => void): this & PromiseLike<void>  listen(opts?: FastifyListenOptions): Promise<string>  close(): Promise<void>  inject(opts: InjectOptions | string): Promise<LightMyRequestResponse>   route(opts: RouteOptions): this  get(url: string, opts: RouteShorthandOptions, handler: RouteHandler): this  post(url: string, opts: RouteShorthandOptions, handler: RouteHandler): this  hasRoute(opts: { method: HTTPMethods; url: string }): boolean  addHook(name: HookName, hook: HookHandler): this   decorate(name: string | symbol, value: unknown): this  decorateRequest(name: string | symbol, value: unknown): this  decorateReply(name: string | symbol, value: unknown): this  hasDecorator(name: string | symbol): boolean  hasPlugin(name: string): boolean   addSchema(schema: unknown): this  getSchema(id: string): unknown  getSchemas(): Record<string, unknown>  setValidatorCompiler(fn: FastifySchemaCompiler): this  setSerializerCompiler(fn: FastifySerializerCompiler): this  addContentTypeParser(type: string | RegExp, opts: ParserOptions, fn: Parser): void  setErrorHandler(handler: (error: FastifyError, request, reply) => unknown): this  setNotFoundHandler(handler: RouteHandler): this  addConstraintStrategy(strategy: ConstraintStrategy): void  withTypeProvider<Provider extends FastifyTypeProvider>(): FastifyInstance  printRoutes(opts?: PrintRoutesOptions): string}

1. L2server is the raw Node server after listen; prefix and pluginName are per scope — a child sees its own values through its own properties, everything else through the chain.
2. L9register, after and ready return the instance (this) and are thenable, which is what lets await app.register(x) work. Everything is queued until ready drains it.
3. L16Every route method returns the instance. The shorthand also accepts (url, handler) with no options object; both forms end in route(opts).
4. L22Three decorate methods, one existence-check rule each; hasDecorator walks the chain, so it answers for a parent's decorator too.
5. L28Schema methods write to this scope's SchemaController; the compiler setters replace the compiler for this scope's routes only.
6. L34setErrorHandler and setNotFoundHandler install per scope. printRoutes renders the radix tree — the same shape the tree figures draw.

interface FastifyRequest {  id: string  params: Params  query: Querystring  body: Body  headers: IncomingHttpHeaders & Headers  raw: IncomingMessage | Http2ServerRequest  log: FastifyBaseLogger  server: FastifyInstance  validationError?: Error & { validation: unknown; validationContext: string }   readonly url: string  readonly originalUrl: string  readonly method: string  readonly host: string  readonly hostname: string  readonly port: number | null  readonly protocol: 'http' | 'https'  readonly ip: string  readonly ips?: string[]  readonly socket: Socket  readonly signal: AbortSignal  readonly mediaType: string | undefined  readonly routeOptions: Readonly<RequestRouteOptions>   getValidationFunction(httpPart: HTTPRequestPart): ValidationFunction | undefined  compileValidationSchema(schema: object, httpPart?: HTTPRequestPart):    ValidationFunction  validateInput(input: unknown, schema: object, httpPart?: HTTPRequestPart): boolean  getDecorator<T>(name: string | symbol): T  setDecorator<T>(name: string | symbol, value: T): void}

1. L2The own properties: assigned in the constructor in this order for every request. body is undefined until parsing runs; params and query exist from routing.
2. L10validationError is only set when the route has attachValidation: true; otherwise a failed validation replies 400 before the handler.
3. L12Getters on Request.prototype: url and method read from raw; host falls back to the HTTP/2 :authority pseudo-header; ip honours trustProxy.
4. L24routeOptions is the matched route's frozen options: method, url, config, schema, constraints, handler.
5. L26The schema helpers reach the scope's compiled functions or compile ad hoc; validateInput returns a boolean and fills validationError.

interface FastifyReply {  raw: ServerResponse | Http2ServerResponse  request: FastifyRequest  log: FastifyBaseLogger  server: FastifyInstance  statusCode: number  readonly sent: boolean  readonly elapsedTime: number  readonly routeOptions: Readonly<RequestRouteOptions>   code(statusCode: number): this  status(statusCode: number): this  header(key: string, value: unknown): this  headers(values: Record<string, unknown>): this  getHeader(key: string): number | string | string[] | undefined  getHeaders(): Record<string, number | string | string[] | undefined>  hasHeader(key: string): boolean  removeHeader(key: string): this  type(contentType: string): this  trailer(key: string, fn: TrailerFunction): this   send(payload?: unknown): this  redirect(url: string, statusCode?: number): this  hijack(): this  callNotFound(): void  writeEarlyHints(hints: Record<string, string | string[]>): void   serialize(payload: unknown): string | ArrayBuffer | Buffer  serializer(fn: (payload: unknown) => string): this  getSerializationFunction(httpStatus: string, contentType?: string):    SerializationFunction  compileSerializationSchema(schema: object, httpStatus?: string):    SerializationFunction  serializeInput(input: object, httpStatus: string, contentType?: string): unknown  then(fulfilled: () => void, rejected: (err: Error) => void): void}

1. L2Three own properties (raw, request, log) — measured — and statusCode, which code() sets. sent flips when the write starts; hooks read it to stop early.
2. L11Status and header methods return the reply (this), so reply.code(201).header(...).send(...) is one expression. type() disables the content-type guessing that send does.
3. L22send is the single exit for every payload kind; redirect sets location and sends an empty body; hijack hands raw to you and skips the rest of the pipeline.
4. L28The serialisation helpers reach the compiled function for a status, or compile one on demand. serializer() sets a per-reply function that replaces the schema path.
5. L35then makes await reply resolve when the response is sent — the same mechanism that lets a handler return reply.

interface RouteOptions {  method: HTTPMethods | HTTPMethods[]  url: string  handler: (this: FastifyInstance, request: FastifyRequest,            reply: FastifyReply) => unknown  schema?: { body?: object; querystring?: object; params?: object; headers?: object;             response?: Record<number | string, object> }  config?: object  constraints?: { host?: string | RegExp; version?: string;                  [custom: string]: unknown }  bodyLimit?: number  logLevel?: string  exposeHeadRoute?: boolean  prefixTrailingSlash?: 'both' | 'slash' | 'no-slash'  attachValidation?: boolean  onRequest?: HookHandler | HookHandler[]  preParsing?: HookHandler | HookHandler[]  preValidation?: HookHandler | HookHandler[]  preHandler?: HookHandler | HookHandler[]  preSerialization?: HookHandler | HookHandler[]  onSend?: HookHandler | HookHandler[]  onResponse?: HookHandler | HookHandler[]  onError?: HookHandler | HookHandler[]  errorHandler?: (error: FastifyError, request: FastifyRequest,                  reply: FastifyReply) => unknown  validatorCompiler?: FastifySchemaCompiler  serializerCompiler?: FastifySerializerCompiler  schemaErrorFormatter?: (errors: ValidationError[], dataVar: string) => Error} type FastifyPluginAsync<Opts = object> =  (instance: FastifyInstance, opts: Opts) => Promise<void>type FastifyPluginCallback<Opts = object> =  (instance: FastifyInstance, opts: Opts, done: (err?: Error) => void) => void

1. L4The handler's this is the scope, which is why a plain function can read this.db. Its return value is what wrapThenable sends.
2. L6Five schema parts. The four incoming ones compile to validators, response to one serializer per status key (200, 2xx, default).
3. L9constraints is a second key on the same method and path; the values are matched by the router's strategies.
4. L16Route-level hooks run after the scope's hooks of the same stage. Arrays are allowed; onTimeout and onRequestAbort are route options too.
5. L24A route-level errorHandler sits before the scope's chain; the compiler and formatter options override the scope's for this route only.
6. L31A plugin is a function of (instance, opts); the async form resolves when its body is done, the callback form calls done. Either way, its registrations drain before the next sibling.

fastify.js, the factorybreakdown

fastify(options) is the only export. It validates options against a generated schema (lib/config-validator.js), creates the root instance as a plain object with 69 own methods and properties, attaches avvio to it, builds the router, the root Request and Reply classes, the Hooks object and the SchemaController, and returns the object. Nothing listens, nothing is compiled yet.

import Fastify from 'fastify' const app = Fastify({ logger: true }) app.get('/health', async () => ({ ok: true })) await app.listen({ port: 3000 })

import Fastify, { type FastifyInstance } from 'fastify' const app: FastifyInstance = Fastify({ logger: true }) app.get('/health', async () => ({ ok: true })) await app.listen({ port: 3000 })

1. L3Fastify(options) runs the factory in fastify.js: it validates the options once, builds the root instance, wires avvio to it and creates the router. Nothing listens yet.
2. L5app.get registers a route synchronously into the radix tree and creates its Context. Its hooks and schemas are resolved later, at preReady.
3. L7listen() boots first — ready() drains every plugin — then lib/server.js creates the Node server and binds the port.

1. L3FastifyInstance is the type of the root object and of every scope a plugin receives; the generic parameters carry the server, request and reply types.
2. L5app.get registers a route synchronously into the radix tree and creates its Context. Its hooks and schemas are resolved later, at preReady.
3. L7listen() boots first — ready() drains every plugin — then lib/server.js creates the Node server and binds the port.

lib/server.js, the listenerbreakdown

listen() first awaits ready(), then chooses how to build the Node server: http.createServer by default, https.createServer when https options exist, http2.createServer or http2.createSecureServer when http2: true, or whatever a serverFactory returns. The request listener it registers is the same function in every case.

import Fastify from 'fastify'import { readFileSync } from 'node:fs' const app = Fastify({  http2: true,  https: {    allowHTTP1: true,    key: readFileSync('./key.pem'),    cert: readFileSync('./cert.pem'),  },}) const factory = Fastify({  serverFactory(handler, opts) {    const server = createMyServer(opts)    server.on('request', handler)    return server  },})

import Fastify, { type FastifyServerFactory } from 'fastify'import { readFileSync } from 'node:fs' const app = Fastify({  http2: true,  https: {    allowHTTP1: true,    key: readFileSync('./key.pem'),    cert: readFileSync('./cert.pem'),  },}) const makeServer: FastifyServerFactory = (handler, opts) => {  const server = createMyServer(opts)  server.on('request', handler)  return server}const factory = Fastify({ serverFactory: makeServer })

1. L5http2: true makes lib/server.js call http2.createSecureServer when https is present, or http2.createServer for cleartext h2c.
2. L7allowHTTP1 keeps HTTP/1.1 clients working on the same port — the same handler serves both, because request and reply wrap either kind of stream.
3. L14serverFactory receives fastify's request handler and must return something with listen and close; fastify never creates a server itself in that case.

1. L5http2: true makes lib/server.js call http2.createSecureServer when https is present, or http2.createServer for cleartext h2c.
2. L7allowHTTP1 keeps HTTP/1.1 clients working on the same port — the same handler serves both, because request and reply wrap either kind of stream.
3. L13FastifyServerFactory types the (handler, opts) pair: the handler is fastify's request listener, and the return value must offer listen and close.

lib/route.js and lib/context.jsbreakdown

route(opts) normalises the URL against the scope's prefix, runs onRoute hooks, creates a Context and inserts the route into find-my-way — all synchronously. Then it registers an after() callback and an avvio preReady listener: only there are the route's hooks resolved from the scope's arrays, its schemas compiled and its 404 context chosen.

• prefix rules: / inside a prefixed plugin registers both /prefix and /prefix/; a leading slash is de-duplicated when the prefix ends with one.
• HEAD: a GET route also registers a HEAD route unless exposeHeadRoute: false; its onSend hook measures the payload for content-length and drops it.
• duplicates: the same method and path with the same constraints throws FST_ERR_DUPLICATED_ROUTE at registration.
• Context: one per route, holding handler, schema, config, the resolved hook arrays, the compiled validators and serializers, and the errorHandler link.

lib/handle-request.js and lib/hooks.jsbreakdown

lib/hooks.js holds the ten lifecycle arrays and the runners. One generator, hookRunnerGenerator, produces the runner used by most stages: call the next function, and if it returns a thenable wait for it, else expect done(). Three stages get their own runner because they pass a payload through: preParsing, preSerialization and onSend.

lib/request.js and lib/reply.jsbreakdown

Request is a class with 21 prototype members; Reply has 31. Both are subclassed per scope so decorators stay inside the scope that declared them.

function buildRegularRequest (R) {  const props = R.props.slice()  function _Request (id, params, req, query, log, context) {    this.id = id    this[kRouteContext] = context    this.params = params    this.raw = req    this.query = query    this.log = log    this.body = undefined     let prop    for (let i = 0; i < props.length; i++) {      prop = props[i]      this[prop.key] = prop.value    }  }  Object.setPrototypeOf(_Request.prototype, R.prototype)  Object.setPrototypeOf(_Request, R)  _Request.props = props  _Request.parent = R   return _Request

1. L2R.props is the list of value decorators declared with decorateRequest. It is copied when the subclass is built, which is when the scope is created.
2. L3Every request object starts with the same seven assignments in the same order — one V8 hidden class for all of them.
3. L11Value decorators become own properties here, per request. Functions and getters go on the prototype instead (see lib/decorate.js).
4. L16The subclass chains to the parent scope's class, so a method decorated in the parent is still found.

lib/plugin-override.js and lib/decorate.jsbreakdown

override(old, fn, opts) is what avvio calls before it runs a plugin. A plugin marked with Symbol.for('skip-override') — what fastify-plugin sets — gets the parent back; any other plugin gets a child built from it.

  const instance = Object.create(old)  old[kChildren].push(instance)  instance.ready = old[kAvvioBoot].bind(instance)  instance[kChildren] = []   instance[kReply] = Reply.buildReply(instance[kReply])  instance[kRequest] = Request.buildRequest(instance[kRequest])   instance[kContentTypeParser] = ContentTypeParser.helpers.buildContentTypeParser(instance[kContentTypeParser])  instance[kHooks] = buildHooks(instance[kHooks])  instance[kRoutePrefix] = buildRoutePrefix(instance[kRoutePrefix], opts.prefix)

1. L1The whole of encapsulation is this line: the child scope's prototype is the parent. Reads fall through; writes land on the child.
2. L2The parent keeps a list of its children — addHook and addSchema walk it to push additions down.
3. L6Each scope gets its own Reply and Request subclasses, so request decorators added here are invisible to sibling scopes.
4. L10buildHooks copies the parent's hook arrays with slice() — a snapshot, kept current afterwards by propagation.
5. L11The route prefix is joined once here; every route the plugin registers is stored under it.

lib/validation.js and lib/schema-controller.jsbreakdown

Schemas are plain objects until preReady. compileSchemasForValidation asks the scope's validatorCompiler (ajv by default) for one function per part — params, querystring, headers, body — and stores them on the Context. compileSchemasForSerialization does the same for each status code under response. The SchemaController holds the shared schemas added with addSchema and is copied per scope, so $refs resolve within the scope's view.

lib/four-oh-four.js, lib/error-handler.js, lib/errors.jsbreakdown

Not-found is a route: the 404 handler is stored as a wildcard context per prefix and runs through the scope's own hooks. Errors follow a chain built with Object.create, and every framework error is an instance created by @fastify/error with a stable code such as FST_ERR_VALIDATION.

function buildErrorHandler (parent = rootErrorHandler, func) {  if (!func) {    return parent  }   const errorHandler = Object.create(parent)  errorHandler.func = func  return errorHandler

1. L1A scope's error handler is an object whose prototype is the parent scope's handler object — the same trick as the scopes themselves.
2. L6When a custom handler throws, handleError moves to Object.getPrototypeOf(handler): the parent's handler, then the default at the top.

lib/content-type-parser.jsbreakdown

Body parsing is a table keyed by media type. The defaults are application/json and text/plain; addContentTypeParser adds to the scope's copy of the table. A body with no matching parser is answered 415 before preValidation runs; an empty body with a JSON content type is 400 FST_ERR_CTP_EMPTY_JSON_BODY.

The model that runs in this pagebreakdown

Every figure that steps through a boot, a lookup or a request is running a working model in your browser: a re-implementation of those three engines, small enough to read. It is checked against the installed package by building the same application twice and comparing the responses and the observed call order.

Where it stops — read this before taking a figure as the whole truth:

• No sockets: inject() is the only transport, so keep-alive, timeouts, HTTP/2 and onTimeout/onRequestAbort never fire
• Schema support covers type, required, properties, additionalProperties, enum, const, min/max, length, pattern, items, $ref and default — not the full JSON Schema draft
• Version constraints accept exact and x-wildcard forms rather than semver ranges
• No logging: request.log is a no-op; the pino child-logger lifecycle is modelled in the figures, not run
• Route-level errorHandler, schemaErrorFormatter and validatorCompiler/serializerCompiler options are not supported
• bodyLimit is recorded but not enforced, and there is no streaming body — the whole payload is a string
• Trailing-slash handling implements ignoreTrailingSlash and prefixTrailingSlash "both"; ignoreDuplicateSlashes is not modelled
• Content-type parsers receive the whole body as a string; parseAs "buffer" behaves as "string"

avvio, the boot graphbreakdown

avvio is a queue with one rule: a plugin's own registrations drain before the next sibling starts. register appends, after appends a callback that runs when everything queued before it has loaded, and ready drains the root. Every plugin start goes through override, which decides whether a new scope is created.

app.register(config)app.register(db)app.register(async function vouchers(scope, opts) {  scope.register(claimRoutes, { prefix: '/claim' })  scope.addHook('preHandler', rateLimit)})app.after(() => app.log.info('vouchers loaded'))await app.ready()

app.register(config)app.register(db)app.register(async function vouchers(scope: FastifyInstance, opts: Opts) {  scope.register(claimRoutes, { prefix: '/claim' })  scope.addHook('preHandler', rateLimit)})app.after(() => app.log.info('vouchers loaded'))await app.ready()

1. L1register only queues. Nothing inside a plugin runs until the queue is drained, so app.register calls can be read as a list of what will happen, in order.
2. L3When vouchers starts, override has just created its scope. The plugin body runs, its own registrations queue on the child, and they drain before after on line 7 runs — depth first.
3. L5addHook for a lifecycle hook is itself deferred through after(): it lands at the end of this plugin's load and is pushed into claimRoutes, which already exists by then.
4. L8ready() drains the root queue, emits preReady — hooks resolved per route, schemas compiled — then runs onReady hooks. After this, route, register and addHook throw.

find-my-way, the radix treebreakdown

Routes are inserted into a tree keyed by path characters, compressed so that a run of characters with no branch is one node. Lookup walks the tree with the request path and backtracks when a branch dead-ends. The page's model, FaLite, mirrors the priority and the backtracking; the real tree adds constraint stores, multi-parametric segments and a handler storage per method.

function walk(node, rest, params) {  if (rest.length === 0) return pick(node, method)  for (const child of node.statics) {    if (rest.startsWith(child.label)) {      const hit = walk(child, rest.slice(child.label.length), params)      if (hit) return hit    }  }  if (node.param) {    const seg = rest.slice(0, rest.indexOf('/') + 1 || rest.length)    const next = { ...params, [node.param.name]: seg }    const hit = walk(node.param, rest.slice(seg.length), next)    if (hit) return hit  }  if (node.wildcard) return pick(node.wildcard, method, { ...params, '*': rest })  return null}

1. L2A node stores handlers per method. Reaching the end of the path with no handler for this method is a miss, not a 405 — fastify answers 404 either way.
2. L3Static children first. Labels are compressed runs of characters, so /vouchers/ and /version share a /v node with two children.
3. L9One parametric child per node, tried only after every static child failed — that is the whole priority rule, and it is structural rather than sorted.
4. L14The wildcard consumes the rest of the path. The 404 contexts are stored on wildcard nodes, one per prefix.

the hook chainbreakdown

A route's Context holds ten arrays, or null when a stage has no hooks. handle-request.js calls the runner for each populated stage and the handler in between. The runner is the same generated closure for every stage that does not carry a payload.

function hookRunnerGenerator (iterator) {  return function hookRunner (functions, request, reply, cb) {    let i = 0     function next (err) {      if (err || i === functions.length) {        cb(err, request, reply)        return      }       let result      try {        result = iterator(functions[i++], request, reply, next)      } catch (error) {        cb(error, request, reply)        return      }      if (result && typeof result.then === 'function') {        result.then(handleResolve, handleReject)      }    }     function handleResolve () {      next()

1. L3The chain state is one integer. Each hook that finishes calls next(); the array index moves by one.
2. L5Any error — passed to done(err), thrown, or rejected — leaves the chain immediately and reaches cb(err), which becomes reply.send(err).
3. L12A hook that returns a thenable is awaited; a hook that returns nothing must call done. Doing both is the classic double-continue bug, and fastify does not guard against it.

How a handler answersbreakdown

There are exactly three ways for the handler to produce a response and one to opt out. Which one you use decides what wrapThenable does with the promise.

app.get('/a', async () => ({ a: 1 }))app.get('/b', (req, reply) => { reply.code(201).send({ b: 2 }) })app.get('/c', async (req, reply) => { reply.send({ c: 3 }); return reply })app.get('/d', async (req, reply) => { reply.code(204); return null })app.get('/e', async () => { throw new Error('boom') })

app.get('/a', async (): Promise<{ a: number }> => ({ a: 1 }))app.get('/b', (req, reply) => { reply.code(201).send({ b: 2 }) })app.get('/c', async (req, reply) => { reply.send({ c: 3 }); return reply })app.get('/d', async (req, reply) => { reply.code(204); return null })app.get('/e', async (): Promise<never> => { throw new Error('boom') })

1. L1Returning a value from an async handler is reply.send(value) — wrapThenable sends the resolved value. Objects go through serialisation; strings do not.
2. L2A sync handler that calls reply.send and returns undefined: nothing more happens. Returning a value here as well would send twice.
3. L3reply.send inside an async handler must be paired with return reply — otherwise the promise resolves to undefined and fastify tries to send again.
4. L4null sends an empty body; with 204 the content-length header is omitted (measured).
5. L5A rejection becomes reply.send(err): onError hooks, then the error handler chain, then the normal serialisation and onSend path.

What each payload kind skipsbreakdown

The type of the value decides how much of the send path runs. Only objects and null are serialised; strings, Buffers and streams go straight to onSend; hijack leaves the path entirely.

Leaving the chain earlybreakdown

A hook that calls reply.send() ends the request: the remaining hooks of that stage and every later stage up to onSend are skipped, and onResponse still runs. An error anywhere jumps to onError, then the error handler; whatever the handler sends goes through onSend and onResponse like any other reply.

Decorators, the DI layerbreakdown

Decorators are how a plugin publishes something — a database pool, a config object, a per-request user. Three targets, three placement rules, and one asymmetry that matters:

Reference-type values ({}, []) are refused on request and reply with FST_ERR_DEC_REFERENCE_TYPE because they would be shared across requests; use null and assign in a hook, or a getter.

What order does and does not changebreakdown

Two facts, both measured against the real package, decide most registration-order questions.

app.register(async function early(scope) {  scope.hasDecorator('db')          // false — db has not loaded yet  scope.get('/x', async function () { return this.hasDecorator('db') })})app.register(fp(async function dbPlugin(scope) { scope.decorate('db', pool) }))app.register(fp(async function lateHook(scope) {  scope.addHook('onRequest', audit) // applies to /x as well}))

app.register(async function early(scope: FastifyInstance) {  scope.hasDecorator('db')          // false — db has not loaded yet  scope.get('/x', async function () { return this.hasDecorator('db') })})app.register(fp(async function dbPlugin(scope) { scope.decorate('db', pool) }))app.register(fp(async function lateHook(scope) {  scope.addHook('onRequest', audit) // applies to /x as well}))

1. L2Read during the plugin body, before dbPlugin has loaded: false. Order matters for anything a plugin reads while it loads.
2. L3Read during a request: true. The lookup walks the prototype chain at call time, and by then every plugin has loaded. Measured in the conformance run.
3. L5fp is fastify-plugin: it marks the function so override returns the parent, and decorate lands on the root object.
4. L7A hook added to the root after early loaded still reaches /x: _addHook pushes it into every existing child. Hooks are never order-sensitive; load-time reads are.

fastify-pluginbreakdown

fastify-plugin sets Symbol.for('skip-override') on the function and optionally records a name and version. With the flag set, override returns the parent object, so everything the plugin adds — decorators, hooks, schemas — lands one level up. Use it for capabilities the whole application shares; leave it off for features that own routes.

What registration writesbreakdown

Lookup, priority and backtrackingbreakdown

At every node the order is fixed: static children, then the parametric child, then the wildcard. If a static branch matches the next characters but dead-ends further down, the walk returns and tries the parametric child from the same node — so /a/:x/c still answers /a/b/c when /a/b/d exists (measured). Route count does not change the walk: the number of nodes visited depends on the path, not on how many other routes exist.

Constraintsbreakdown

A constraint is a second key for the same method and path. find-my-way derives the value from the request with a strategy — host and version are built in, addConstraintStrategy adds your own — and keeps constrained handlers in a store beside the plain one.

app.get('/c', { constraints: { host: 'admin.example.com' } },  async () => ({ who: 'admin' }))app.get('/c', async () => ({ who: 'anyone' }))app.get('/v', { constraints: { version: '1.2.0' } }, async () => ({ v: 1 }))app.get('/v', { constraints: { version: '2.0.0' } }, async () => ({ v: 2 }))

app.get('/c', { constraints: { host: 'admin.example.com' } },  async (): Promise<Who> => ({ who: 'admin' }))app.get('/c', async (): Promise<Who> => ({ who: 'anyone' }))app.get('/v', { constraints: { version: '1.2.0' } }, async () => ({ v: 1 }))app.get('/v', { constraints: { version: '2.0.0' } }, async () => ({ v: 2 }))

1. L1Constrained handlers are tried before the unconstrained one at the same node. host matches the Host header exactly or by regex.
2. L3With an unconstrained sibling, a request from any other host still resolves. Without one, a non-matching host is a 404.
3. L4version reads Accept-Version; 1.x selects 1.2.0 (measured). A request without the header hits neither version route → 404.

Asking the router what it knowsbreakdown

Four methods read the structures back out, all of them at registration or afterwards, none of them per request.

request.getDecorator and request.setDecorator are the same idea on the request: they read and write a declared request decorator and throw the same error for an undeclared name (measured). hasPlugin(name) answers whether a named plugin registered on this scope's chain.

Not found, per prefixbreakdown

setNotFoundHandler in a plugin with a prefix installs a 404 context for that prefix: a wildcard route whose hooks are the scope's hooks and whose handler is yours. A miss under /api runs the /api handler; a miss elsewhere runs the root one, whose default payload is { message, error, statusCode } — three keys, no code (measured).

Validation: ajv with four defaultsbreakdown

The default error formatter joins the part name, the instance path and ajv's message:

The response is 400 with { statusCode, code: "FST_ERR_VALIDATION", error: "Bad Request", message }; attachValidation: true on the route puts the error on request.validationError instead and lets the handler decide.

Serialisation: a generated function per statusbreakdown

fast-json-stringify emits JavaScript source from the schema and evaluates it once. The function writes property by property, coerces to the declared type, and skips anything the schema does not name. This is the captured output for the voucher payload used in the measurements:

function anonymous0 (input) {        const obj = (input && typeof input.toJSON === 'function')    ? input.toJSON()    : input          if (obj === null) return JSON_STR_EMPTY_OBJECT        let json = ''         json += JSON_STR_BEGIN_OBJECTlet addComma_0 = false           const value_id_1 = obj["id"]          if (value_id_1 !== undefined) {            !addComma_0 && (addComma_0 = true) || (json += JSON_STR_COMMA)            json += "\"id\":"            json += asInteger(value_id_1)          }           const value_code_2 = obj["code"]          if (value_code_2 !== undefined) {            !addComma_0 && (addComma_0 = true) || (json += JSON_STR_COMMA)            json += "\"code\":"

Shared schemas and $refbreakdown

addSchema is scope-aware: the SchemaController is rebuilt per scope with the parent's store as its base, and addSchema on a parent walks kChildren so children already created still see it. getSchema(id) and getSchemas() read the scope's view. Compilers see the same store, which is how a $ref to a schema added in a parent resolves inside a plugin.

Work moved to bootbreakdown

The design decision is to spend time at preReady so that a request does not: hooks resolved to arrays, schemas compiled to functions, routes inserted into a tree, prefixes joined into paths, request classes fixed per scope.

The router does not care how many routes existbreakdown

The tree walk is bounded by the path length, so lookup stays flat from 10 to 1,000 routes. The linear scan is the mechanism a route table implemented as an ordered list of patterns uses; its cost grows with the number of routes registered before the one that matches.

What hooks costbreakdown

Ten async no-op hooks are indistinguishable from none at this resolution: each is one promise resolution on the microtask queue. What a hook does — a database call, a JSON parse — costs; the mechanism does not.

Throughput, with the caveatbreakdown

Load generator and server share the same vcpu; treat differences under ~15% as noise. All four sit within that band: on one shared core the framework is not the bottleneck, which is itself the useful reading — the request path adds no measurable overhead over a hand-written http.createServer handler for this payload.

What boot costsbreakdown

Roughly 1.0 ms per encapsulated plugin at the high end: a scope, two subclasses, a hook snapshot, a route insert and a schema controller each. It is paid once.

Capabilities as decoratorsbreakdown

Each shared capability is one file: it connects, decorates, and registers its own onClose. The dependency between them is declared, checked at load, and consumed through this.

import fp from 'fastify-plugin'import { Pool } from 'pg' export default fp(async function db(app, opts) {  const pool = new Pool({ connectionString: app.config.DATABASE_URL })  await pool.query('select 1')  app.decorate('db', pool)  app.addHook('onClose', async () => { await pool.end() })}, { name: 'db', dependencies: ['config'] })

import fp from 'fastify-plugin'import { Pool } from 'pg' declare module 'fastify' { interface FastifyInstance { db: Pool } } export default fp(async function db(app, opts) {  const pool = new Pool({ connectionString: app.config.DATABASE_URL })  await pool.query('select 1')  app.decorate('db', pool)  app.addHook('onClose', async () => { await pool.end() })}, { name: 'db', dependencies: ['config'] })

1. L4fp makes this plugin write to the root scope. dependencies is checked at load: if config has not registered, fastify throws with the plugin names.
2. L5app.config exists because config loaded first — a load-time read, so order matters here.
3. L7decorate publishes the pool. Every handler in every scope reads this.db or req.server.db through the prototype chain.
4. L8onClose hooks run in reverse registration order at close(): the pool ends after the plugins registered later have closed.

1. L4Declaration merging tells TypeScript about the decorator; without it app.db is a type error even though it exists at runtime.
2. L6fp makes this plugin write to the root scope. dependencies is checked at load: if config has not registered, fastify throws with the plugin names.
3. L9decorate publishes the pool. Every handler in every scope reads this.db or req.server.db through the prototype chain.
4. L10onClose hooks run in reverse registration order at close(): the pool ends after the plugins registered later have closed.

The claim routebreakdown

import { claimVoucher, VoucherError } from '../services/vouchers.js' export default async function vouchers(app, opts) {  app.addHook('preHandler', app.rateLimit({ max: 5, window: '1 minute' }))   app.post('/claim', {    schema: {      body: { $ref: 'claimBody#' },      response: { 201: { $ref: 'voucher#' } },    },  }, async function (req, reply) {    const voucher = await claimVoucher(this.db, req.user, req.body)    await this.whatsapp.send(req.user.phone, voucher.code)    reply.code(201)    return voucher  })   app.setErrorHandler((err, req, reply) => {    if (err instanceof VoucherError) {      return reply.code(err.status).send({ error: err.kind })    }    throw err  })}

import { claimVoucher, VoucherError } from '../services/vouchers.js'import type { FastifyPluginAsync } from 'fastify' const vouchers: FastifyPluginAsync = async (app, opts) => {  app.addHook('preHandler', app.rateLimit({ max: 5, window: '1 minute' }))   app.post<{ Body: ClaimBody; Reply: Voucher }>('/claim', {    schema: {      body: { $ref: 'claimBody#' },      response: { 201: { $ref: 'voucher#' } },    },  }, async function (req, reply) {    const voucher = await claimVoucher(this.db, req.user, req.body)    await this.whatsapp.send(req.user.phone, voucher.code)    reply.code(201)    return voucher  })   app.setErrorHandler((err, req, reply) => {    if (err instanceof VoucherError) {      return reply.code(err.status).send({ error: err.kind })    }    throw err  })}export default vouchers

1. L4A scope-level preHandler: every route in this plugin — and in any plugin registered beneath it — is rate limited. Routes outside /vouchers are not.
2. L6Both schemas are shared (addSchema in config), so the same shape validates here and serialises in the admin plugin.
3. L11A plain function so this is the scope: this.db and this.whatsapp resolve through the prototype chain to the root decorators.
4. L12claimVoucher is a plain module that takes its dependencies as arguments — the service layer never imports fastify.
5. L18The scope's error handler answers domain errors; rethrowing hands anything else to the parent handler, which is the default one here.

1. L4FastifyPluginAsync types the (app, opts) signature; an options interface can be passed as its generic.
2. L5A scope-level preHandler: every route in this plugin — and in any plugin registered beneath it — is rate limited. Routes outside /vouchers are not.
3. L7The route generic names the body and reply types; a type provider derives them from the schema instead (see below).
4. L12A plain function so this is the scope: this.db and this.whatsapp resolve through the prototype chain to the root decorators.
5. L19The scope's error handler answers domain errors; rethrowing hands anything else to the parent handler, which is the default one here.

Errors and not-found, per scopebreakdown

Domain errors are classes with a status and a kind; the scope's error handler turns them into responses and rethrows everything else. onError at the root logs every error once, before any handler runs. The 404 is answered by the closest prefix: /vouchers/nope by the vouchers scope if it set one, otherwise by the root handler in app.js.

Tests through injectbreakdown

import { test } from 'node:test'import assert from 'node:assert/strict'import { build } from '../app.js' test('claims a voucher', async () => {  const app = build({ logger: false })  app.decorate('whatsapp', { async send() {} })  await app.ready()  const res = await app.inject({    method: 'POST', url: '/vouchers/claim',    headers: { authorization: 'Bearer test' },    payload: { campaign: 'SPRING' },  })  assert.equal(res.statusCode, 201)  assert.match(res.json().code, /^[A-Z0-9]{8}$/)  await app.close()})

import { test } from 'node:test'import assert from 'node:assert/strict'import { build } from '../app.js' test('claims a voucher', async () => {  const app = build({ logger: false })  app.decorate('whatsapp', { async send(): Promise<void> {} })  await app.ready()  const res = await app.inject({    method: 'POST', url: '/vouchers/claim',    headers: { authorization: 'Bearer test' },    payload: { campaign: 'SPRING' },  })  assert.equal(res.statusCode, 201)  assert.match(res.json().code, /^[A-Z0-9]{8}$/)  await app.close()})

1. L7Decorating before ready() wins the name: the real whatsapp plugin would throw FST_ERR_DEC_ALREADY_PRESENT, so the test build registers it conditionally or the plugin checks hasDecorator first.
2. L9inject builds a request with light-my-request and runs the full pipeline — routing, hooks, validation, serialisation — without a socket.
3. L15res.json() parses the serialised payload; res.headers and res.statusCode are exactly what a client would see.

Loggingbreakdown

pino is the only logger fastify knows. logger: true creates the root logger; every request gets a child with the request id bound, and the two automatic lines — incoming and completed — are written by lib/log-controller.js.

Types from the schemabreakdown

import { Type } from '@sinclair/typebox' export const ClaimBody = Type.Object({  campaign: Type.String({ minLength: 2 }),  note: Type.Optional(Type.String()),})

import { Type, type Static } from '@sinclair/typebox'import type { TypeBoxTypeProvider } from '@fastify/type-provider-typebox' export const ClaimBody = Type.Object({  campaign: Type.String({ minLength: 2 }),  note: Type.Optional(Type.String()),})export type ClaimBody = Static<typeof ClaimBody> const app = Fastify().withTypeProvider<TypeBoxTypeProvider>()app.post('/claim', { schema: { body: ClaimBody } }, async (req) => {  req.body.campaign      // string — inferred from the schema})

1. L3Type.Object returns a plain JSON schema object; fastify compiles it exactly as a hand-written one.

1. L8Static derives the TypeScript type from the same object, so the runtime check and the compile-time type cannot drift apart.
2. L10withTypeProvider tells the route generics to read Body, Querystring, Params and Reply types off the schema.
3. L12No as, no manual generic: the handler's req.body is typed from the validated shape.

Shutdownbreakdown

app.addHook('preClose', async () => { app.log.info('draining') })app.addHook('onClose', async (instance) => { await instance.db.end() }) process.on('SIGTERM', async () => {  await app.close()  process.exit(0)})

app.addHook('preClose', async () => { app.log.info('draining') })app.addHook('onClose', async (inst: FastifyInstance) => { await inst.db.end() }) process.on('SIGTERM', async () => {  await app.close()  process.exit(0)})

1. L1preClose runs before the server stops accepting; keep-alive connections are closed by fastify between preClose and onClose.
2. L2onClose hooks run last-registered first, so a plugin that depends on db closes before db does.
3. L5close() resolves when every onClose has finished; the process exits only then.