Fastify Setup

How AIWAF works: system architecture

Protect a Fastify application, confirm the adapter runs before its handler, and decide how routes and state should be managed.

1. Install the adapter and dependencies

npm install fastify@^5.12.7 aiwaf

Install the framework dependencies used by your existing application. The Node middleware package is aiwaf; source code and package scripts live in the monorepo's js/ directory.

2. Register the adapter

app.cjs

const fastify = require('fastify')();
const aiwaf = require('aiwaf');

fastify.register(aiwaf.fastify, {
  AIWAF_MIDDLEWARES: ['auto'],
  WINDOW_SEC: 10, MAX_REQ: 20, FLOOD_REQ: 40
});
fastify.get('/', async () => ({ protected: true }));
fastify.listen({ port: 3000 });

How this registration works

The plugin registers request hooks. Register it before the routes it protects; Fastify plugin encapsulation affects where hooks apply.

auto selects checks based on application signals; it is not a fixed promise that every check runs. Review the Node request lifecycle and configuration reference when choosing checks.

3. Run and verify the integration

node app.cjs

Open http://127.0.0.1:3000/ in a browser. The example handler returns {"protected": true}; existing NestJS/Adonis/Sails routes return their own handler response. This proves reachability, so also test an intended rejection on a non-exempt route before rollout.

A plain curl client can fail header checks when they are selected. Inspect the actual response and logs, route policy, and observed client address. A private client or exempt path may bypass enforcement. See the controlled allow/throttle exercise for what an enforcement test should establish.

4. Discover routes and review policy

Generate a manifest after the application's routes are registered. Express applications can call aiwaf.generateExpressManifest(app, '.aiwaf/paths.json'). Other adapters expose aiwaf.generateFrameworkManifest(framework, app, outputPath, options) with framework-specific route extraction.

For a route list stored in routes.json, use the installed CLI:

npx aiwaf manifest --framework fastify --routes routes.json --output .aiwaf/paths.json

Review the resulting manifest and repeat generation when routes change. Manifest generation complements AIWAF_MIDDLEWARES: ['auto'] and explicit AIWAF_PATH_RULES overrides.

Configuration

AIWAF loads aiwaf-wasm when available and falls back to the JavaScript implementation when WASM initialization or conversion is not worthwhile. Small, object-heavy operations can be faster in JavaScript because crossing the JS/WASM boundary and serializing objects has a fixed cost. WASM is most useful for sufficiently large feature batches and model scoring workloads.

Operate the installed package

npx aiwaf --help
npx aiwaf status
npx aiwaf list blocklist
npx aiwaf model info

For offline training from a source checkout:

cd aiwaf/js
AIWAF_ACCESS_LOG=/path/to/access.log npm run train

PowerShell users can set $env:AIWAF_ACCESS_LOG = '/path/to/access.log' before npm run train. Application installs do not inherit the package's npm scripts; use the installed CLI or the source checkout as appropriate.

Verify and deploy

Test normal routes, narrowly scoped exemptions, configured header policy, and rate-limit behavior in staging. Persist logs and model artifacts and schedule training after traffic volume thresholds are met. In-memory enforcement is process-local; use Redis or another shared cache when rate limits must span workers.

• Node.js operations
• Architecture and route policies