Module 7 — Routing Engines at Scale: Vanilla HTTP vs Radix Tree Frameworks

The Overhead Before Your Code Runs

For a payment gateway receiving a POST to /api/v2/payments/process, the framework must:

1. Parse the URL (string split, decode percent-encoding)
2. Find the matching route handler (scan routes or traverse a tree)
3. Execute middleware chain (authentication, rate limiting, body parsing)
4. Deserialize the request body (JSON.parse)
5. Validate the payload (schema check)
6. Hand control to your handler

At 100 req/sec, steps 1–5 cost microseconds and are invisible. At 50,000 req/sec, they cost milliseconds that compound into measurable throughput limits. The framework is not neutral — it has a throughput ceiling determined by its internal architecture.

Express: Linear Scan Middleware Chain

Express's routing model is a linked list of middleware functions. Every incoming request walks this list sequentially until a matching handler is found.

javascript
// What Express does internally for each request:
app.use(cors());                     // check #1
app.use(helmet());                   // check #2
app.use(express.json());             // check #3
app.use(rateLimiter);                // check #4
app.post('/api/v1/auth', handler);   // check #5 — match!
app.post('/api/v1/users', handler);  // never reached for /auth
app.post('/api/v2/payments', handler);  // never reached
// ... 200 more routes

For a request to /api/v1/auth, Express checks: is this cors? Yes, run it. Is this helmet? Yes, run it. Is this json? Yes, parse the body. Is this rateLimiter? Yes, run it. Is the method POST and path /api/v1/auth? Yes — match.

The path-matching cost: Express uses path-to-regexp for route matching. For each route, it compiles the path pattern to a RegExp and tests the incoming URL against it. The test is O(N) in the number of routes.

With 200 routes and the matching route at position 180: every request triggers 180 RegExp tests. At 50,000 req/sec, that's 9 million RegExp executions per second — a measurable CPU load before any application logic runs.

javascript
// Measure Express routing overhead directly
const start = process.hrtime.bigint();
app.handle(mockRequest, mockResponse, () => {});
const routingNs = Number(process.hrtime.bigint() - start);
console.log(`Routing overhead: ${routingNs / 1000}μs`);

Typical Express routing overhead on a 100-route app: 15–60μs per request. At 50K req/sec: 750ms–3s of CPU per second just in routing. That's 75–300% of a single CPU core dedicated to route matching.

Radix Tree Routing: O(log K) Route Matching

Fastify uses find-my-way — a Radix tree (compressed trie) router. Instead of scanning routes sequentially, it traverses a tree where common path prefixes are compressed into single nodes.

Routes registered:
  POST /api/v1/auth
  POST /api/v1/users
  POST /api/v1/users/:id
  GET  /api/v2/payments
  POST /api/v2/payments/process
  GET  /api/v2/payments/:id

Radix tree structure:
  /api/
    v1/
      auth         → POST handler
      users        → POST handler
        /:id       → POST handler
    v2/
      payments     → GET handler
        /process   → POST handler
        /:id       → GET handler

Matching /api/v2/payments/process:

1. Does the URL start with /api/? Yes → descend
2. Does the next segment start with v1 or v2? v2 → descend
3. Does the next segment start with payments? Yes → descend
4. Is the remainder /process? Yes → exact match → return handler

4 string prefix comparisons, regardless of the total number of routes. Adding 100 more routes to a different branch (/admin/...) does not change the cost of matching /api/v2/payments/process. The tree depth grows logarithmically with route count, not linearly.

Fastify: Architecture for Throughput

Fastify's design reflects a single principle: minimize overhead on the hot path.

JSON Schema Compilation via ajv

Every time Express parses and validates a request body at runtime, it interprets the validation logic dynamically. Fastify pre-compiles JSON Schema into optimized validator functions at startup using ajv:

javascript
// Fastify with compiled schema validation
const fastify = Fastify({ logger: false });

// Schema is compiled ONCE at startup — not on every request
const paymentSchema = {
  type: 'object',
  required: ['amount', 'senderId', 'recipientId'],
  properties: {
    amount: { type: 'integer', minimum: 1, maximum: 1000000000 },
    senderId: { type: 'string', pattern: '^[A-Z0-9]{32}$' },
    recipientId: { type: 'string', pattern: '^[A-Z0-9]{32}$' },
    memo: { type: 'string', maxLength: 256 },
  },
  additionalProperties: false,
};

fastify.post('/api/v2/payments', {
  schema: {
    body: paymentSchema,
    response: {
      200: {
        type: 'object',
        properties: {
          transactionId: { type: 'string' },
          status: { type: 'string' },
        }
      }
    }
  }
}, async (request, reply) => {
  // By the time this runs:
  // - Route matched via Radix tree (O(log K))
  // - Body validated via compiled ajv function (no interpretation)
  // - request.body is type-safe and validated
  const payment = request.body;
  const result = await processPayment(payment);
  return result;  // serialized via fast-json-stringify (compiled)
});

What ajv compilation produces: instead of interpreting the schema on every request, ajv generates a JavaScript function like this:

javascript
// What ajv generates at startup (conceptually):
function validatePayment(data) {
  if (typeof data.amount !== 'number') return false;
  if (data.amount < 1 || data.amount > 1000000000) return false;
  if (typeof data.senderId !== 'string') return false;
  if (!/^[A-Z0-9]{32}$/.test(data.senderId)) return false;
  // ... etc
  return true;
}
// This runs 5-10x faster than interpreting the schema on every call

fast-json-stringify: Compiled Response Serialization

Standard JSON.stringify is generic — it inspects every key and value at runtime to determine how to serialize them. fast-json-stringify pre-compiles a response schema into a serialization function:

javascript
import fastJsonStringify from 'fast-json-stringify';

// Compiled ONCE at startup
const serializePaymentResponse = fastJsonStringify({
  type: 'object',
  properties: {
    transactionId: { type: 'string' },
    status: { type: 'string' },
    amount: { type: 'integer' },
    timestamp: { type: 'integer' },
  }
});

// Per-request: 2-3x faster than JSON.stringify
const responseBody = serializePaymentResponse({
  transactionId: 'TX123',
  status: 'accepted',
  amount: 5000,
  timestamp: Date.now(),
});

Fastify wires this automatically when you provide a response schema.

Benchmarking: The Actual Numbers

Using autocannon for load testing with 100 concurrent connections:

bash
# Install autocannon
npm install -g autocannon

# Test Express
autocannon -c 100 -d 10 -m POST \
  -H "Content-Type: application/json" \
  -b '{"amount":5000,"senderId":"ABCD1234ABCD1234ABCD1234ABCD1234","recipientId":"EFGH5678EFGH5678EFGH5678EFGH5678"}' \
  http://localhost:3000/api/v2/payments

# Test Fastify
autocannon -c 100 -d 10 -m POST \
  -H "Content-Type: application/json" \
  -b '{"amount":5000,"senderId":"ABCD1234ABCD1234ABCD1234ABCD1234","recipientId":"EFGH5678EFGH5678EFGH5678EFGH5678"}' \
  http://localhost:3001/api/v2/payments

Representative results on an 8-core server (handler does no I/O — pure routing/validation overhead):

Fastify with compiled schemas is 3.7x faster than Express with typical middleware. For a 50K req/sec target: Express cannot reach it on 8 cores; Fastify can.

Fastify's Plugin Architecture: Encapsulation at Scale

For large applications with hundreds of routes, Fastify's plugin system provides scope isolation:

javascript
const fastify = Fastify();

// Each plugin is encapsulated — middleware registered inside
// only applies to routes inside that plugin
await fastify.register(async (ingestionPlugin) => {
  // Rate limiter only for ingestion routes
  ingestionPlugin.addHook('preHandler', rateLimiter);

  ingestionPlugin.post('/api/v2/payments', paymentSchema, paymentHandler);
  ingestionPlugin.post('/api/v2/transfers', transferSchema, transferHandler);

}, { prefix: '/ingestion' });

await fastify.register(async (adminPlugin) => {
  // Auth only for admin routes
  adminPlugin.addHook('preHandler', adminAuthenticator);

  adminPlugin.get('/admin/stats', statsHandler);
  adminPlugin.post('/admin/config', configHandler);

}, { prefix: '/admin' });

// Public routes: no middleware
fastify.get('/health', healthHandler);
fastify.get('/metrics', metricsHandler);

Each registered plugin creates a child scope. Hooks and decorators registered inside a plugin are invisible to routes in sibling plugins. This eliminates the "every request checks every middleware" problem of Express — middleware only runs for the routes that need it.

HTTP Keep-Alive and Connection Reuse

For persistent connections from payment terminals or blockchain full nodes, HTTP keep-alive eliminates per-request TCP handshake overhead.

javascript
// Configure keep-alive on Fastify
const fastify = Fastify({
  // Keep connections alive for 72 seconds
  // (longer than typical 60s load balancer timeout — set lower if LB timeout is 60s)
  keepAliveTimeout: 72_000,

  // Time allowed for client to send headers after connection is established
  connectionTimeout: 5_000,

  // Max requests per connection before closing (prevents memory accumulation)
  maxRequestsPerSocket: 1000,
});

javascript
// Configure keep-alive on outbound connections (e.g., to external APIs)
import { Agent } from 'node:http';

const keepAliveAgent = new Agent({
  keepAlive: true,
  maxSockets: 100,          // max connections to same host
  keepAliveMsecs: 30_000,   // send keep-alive probes every 30s
  maxFreeSockets: 20,       // keep 20 idle connections ready
});

// Use with fetch or http.request
fetch(url, { agent: keepAliveAgent });

For a blockchain indexer making thousands of outbound RPC calls to full nodes: without keep-alive, each call does a TCP handshake (~3ms). With keep-alive at 10,000 RPC calls/sec: 30 seconds of TCP handshake time saved per second of operation.

autocannon + clinic.js: The Three-Tool Profiling Stack

Throughput measurement: autocannon

bash
autocannon -c 100 -d 30 \
  --renderStatusCodes \
  --json > results.json \
  http://localhost:3000/api/v2/payments

# Key metrics from results.json:
# requests.average: mean req/sec
# latency.p99: 99th percentile latency
# errors: connection errors (indicates server saturation)

CPU profiling: clinic flame

bash
clinic flame -- node server.js &
SERVER_PID=$!

# Run load
autocannon -c 100 -d 20 http://localhost:3000/api/v2/payments

kill $SERVER_PID
# Opens flamegraph in browser — identify wide plateaus in hot paths

Event loop diagnosis: clinic doctor

bash
clinic doctor -- node server.js &
SERVER_PID=$!

autocannon -c 100 -d 20 http://localhost:3000/api/v2/payments

kill $SERVER_PID
# Reports: ELU, GC frequency, I/O wait, event loop lag
# Identifies whether bottleneck is CPU, I/O, or event loop saturation

The Production Incident: Express Middleware Saturating a Payment Gateway

Context: A UPI payment gateway using Express with 8 middleware functions and 150 registered routes. Normal throughput: 8,000 req/sec. During a bank-wide reconciliation period, traffic peaked at 32,000 req/sec.

What happened: CPU across 16 workers hit 98% utilization. Response latency climbed from 12ms to 340ms. New connections began timing out. The database was at 15% capacity — it was not the bottleneck.

Diagnosis with clinic flame:

The flamegraph showed 28% of CPU time inside path-to-regexp — Express's route matching library. For each of 32,000 req/sec, Express was running 150 RegExp tests (the matching route was near the end of the list). Total: 4.8 million RegExp tests/second, consuming 28% of all CPU across 16 cores.

The migration:

javascript
// Before: Express with 150 routes
const app = express();
app.use(cors(), helmet(), express.json(), rateLimiter, ...);
app.post('/api/v1/...', handler);
// ... 149 more routes

// After: Fastify with compiled schemas
const fastify = Fastify({ logger: false });

await fastify.register(fastifyRateLimit, { max: 1000, timeWindow: '1 minute' });

// Routes with compiled schemas — zero RegExp, compiled validation
fastify.post('/api/v1/payments', { schema: paymentSchema }, paymentHandler);
// ... etc

Result after migration: At 32,000 req/sec, CPU dropped to 42% across 16 workers (from 98%). Latency: 8ms average (from 340ms). The route matching overhead that had consumed 28% of CPU dropped to ~2%.

Summary

The routing layer gets requests to your code. Module 8 covers what to do once they're there — how to structure large ingestion systems as a Modulith to eliminate internal network overhead while maintaining clean architectural boundaries.

Next: Module 8 — The Modern Hybrid Monolith: High-Throughput Modulith Architecture →