Fastify 5 Schema Compilers & Encapsulation Production Standard

Fastify relies on lexical encapsulation contexts to sandbox decorators, hooks, and compiled validation/serialization schemas without memory leaks or cross-tenant bleed. In Fastify 5, misuse of global compilers or failing to encapsulate plugin boundaries causes compiled `fast-json-stringify` serializers and Ajv validators to either crash on duplicate IDs, leak private data across sibling scopes, or bypass JIT compilation optimizations. Production services must enforce strict encapsulation hierarchies and type-safe schema compilation across every routing subtree.

--- description: Fastify 5 Schema Compilers & Encapsulation Production Standard - Fastify relies on lexical encapsulation contexts to sandbox decorators, hooks, and compiled validation/serialization schemas without memory leaks or cross-tenant bleed. In Fastify 5, misuse of global compilers or failing to encapsulate plugin boundaries causes compiled `fast-json-stringify` serializers and Ajv validators to either crash on duplicate IDs, leak private data across sibling scopes, or bypass JIT compilation optimizations. Production services must enforce strict encapsulation hierarchies and type-safe schema compilation across every routing subtree. globs: src/routes/**/*.ts, src/plugins/**/*.ts, src/app.ts, src/server.ts alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/fastify-5-schema-compilers-encapsulation-production-standard" --- # Fastify 5 Schema Compilers & Encapsulation Production Standard > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Mutating global AJV/fast-json-stringify compilers or exposing route-level decorators and hooks across sibling plugin contexts without encapsulation boundaries. ## System Constraints You are a Principal Backend Architect enforcing Fastify 5 architecture. You MUST strictly preserve Fastify's encapsulation tree using standard plugins and fastify-plugin wrappers only when cross-boundary promotion is required. You MUST ensure schema compilers and response serialization are scope-isolated and type-safe. ## Strict Guidelines - Developers MUST NOT use `fastify-plugin` (fp) on route-defining plugins; route modules MUST remain encapsulated sub-contexts to isolate request hooks and local schema definitions. - Custom validator and serializer compilers set via `setValidatorCompiler` or `setSerializerCompiler` MUST be configured at the appropriate encapsulation boundary and MUST NOT mutate global compiler registries dynamically during request execution. - Shared JSON Schemas with `$id` properties MUST be registered using `fastify.addSchema()` within a common ancestor scope rather than redefining raw schema objects inline across multiple routes. - Route hooks (`onRequest`, `preHandler`, etc.) declared inside a plugin MUST remain local to that encapsulation scope unless explicitly intended to affect sibling routes via a top-level `fp`-wrapped plugin. - Serialization schemas MUST ALWAYS specify explicit status codes under `response` to prevent `fast-json-stringify` from falling back to non-optimized `JSON.stringify` or leaking sensitive entity properties. ## Bad vs Good Implementations ### Encapsulated Plugin Routes with Scoped AJV Validation and fast-json-stringify Serialization #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using `fastify-plugin` (`fp`) on route collections breaches Fastify's encapsulation context, causing the `onRequest` audit hook to fire for every route in the entire service. Furthermore, omitting an explicit response schema causes Fastify to bypass `fast-json-stringify` compilation, degrading throughput and risking data exposure (leaking `passwordHash` and `salt` directly to the client). ```typescript import { FastifyInstance, FastifyPluginAsync } from 'fastify'; import fp from 'fastify-plugin'; // ANTI-PATTERN: Wrapping routes in `fastify-plugin` breaks encapsulation. // Hooks and local schemas bleed into sibling/parent scopes. const userRoutes: FastifyPluginAsync = async (fastify: FastifyInstance) => { // Leaks onRequest to ALL routes in the application! fastify.addHook('onRequest', async (req) => { req.log.info({ path: req.url }, 'Auditing request'); }); // Missing response schema leaks internal database fields in production fastify.get('/users/:id', async (req, reply) => { const user = { id: '123', name: 'Alice', passwordHash: 'secret_hash', salt: 'xyz' }; return user; }); }; export default fp(userRoutes); ``` #### Production Standard (Correct) > **Standard**: The route plugin remains naturally encapsulated, restricting the `onRequest` hook strictly to user-scoped routes. Defining explicit TypeBox schemas compiles deterministic serializers via `fast-json-stringify`, stripping internal fields (`passwordHash`, `salt`) and ensuring maximum JIT serialization performance. ```typescript import { FastifyInstance, FastifyPluginAsync } from 'fastify'; import { Type, Static } from '@sinclair/typebox'; const UserParamsSchema = Type.Object({ id: Type.String({ format: 'uuid' }), }); type UserParams = Static<typeof UserParamsSchema>; const UserResponseSchema = Type.Object({ id: Type.String(), name: Type.String(), }); type UserResponse = Static<typeof UserResponseSchema>; // PROD PATTERN: Standard encapsulated plugin (no fp wrapper) export const userRoutes: FastifyPluginAsync = async (fastify: FastifyInstance): Promise<void> => { // Hook is strictly scoped to routes defined within this plugin subtree fastify.addHook('onRequest', async (req) => { req.log.info({ path: req.url }, 'Auditing user route access'); }); fastify.get<{ Params: UserParams; Reply: UserResponse }>( '/users/:id', { schema: { params: UserParamsSchema, response: { 200: UserResponseSchema, }, }, }, async (req, reply) => { const dbUser = { id: req.params.id, name: 'Alice', passwordHash: 'secret_hash', salt: 'xyz', }; // fast-json-stringify automatically strips passwordHash and salt return reply.code(200).send({ id: dbUser.id, name: dbUser.name, }); } ); }; ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Fastify 5 Schema Compilers & Encapsulation Production Standard

Fastify 5 Schema Compilers & Encapsulation Production Standard defines an industrial-grade behavioral standard for backend engineering. Fastify relies on lexical encapsulation contexts to sandbox decorators, hooks, and compiled validation/serialization schemas without memory leaks or cross-tenant bleed. In Fastify 5, misuse of global compilers or failing to encapsulate plugin boundaries causes compiled `fast-json-stringify` serializers and Ajv validators to either crash on duplicate IDs, leak private data across sibling scopes, or bypass JIT compilation optimizations. Production services must enforce strict encapsulation hierarchies and type-safe schema compilation across every routing subtree. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: Mutating global AJV/fast-json-stringify compilers or exposing route-level decorators and hooks across sibling plugin contexts without encapsulation boundaries. Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	Mutating global AJV/fast-json-stringify compilers or exposing route-level decorators and hooks across sibling plugin contexts without encapsulation boundaries.	Critical	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

Developers MUST NOT use `fastify-plugin` (fp) on route-defining plugins

Developers MUST NOT use `fastify-plugin` (fp) on route-defining plugins; route modules MUST remain encapsulated sub-contexts to isolate request hooks and local schema definitions.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.