DEV Community: 1xApi

How to Prevent Cache Stampede in Node.js APIs with the Single-Flight Pattern (2026 Guide)

1xApi — Sun, 05 Apr 2026 01:03:41 +0000

The cache stampede (also called thundering herd) is one of the most insidious production failures for high-traffic APIs. It goes like this: a heavily-requested cache key expires. In the milliseconds before anyone repopulates it, hundreds of concurrent requests all see a cache miss and simultaneously hammer your database. The database buckles. Latency spikes. Errors cascade. Your users see timeouts.

The fix isn't better caching — it's request coalescing with the single-flight pattern: only one request does the expensive work while every other waiting request shares that single result.

In this guide you'll build a production-ready single-flight cache layer for Node.js APIs from scratch, then extend it to work across multiple instances with Redis.

What Is Cache Stampede and Why Should You Care?

Imagine your /api/trending endpoint serves 5,000 requests per minute. Behind it is a 200ms PostgreSQL query whose result you cache in Redis for 60 seconds. Everything looks fine — until that cache key expires at peak traffic.

In the 200ms window before the first request repopulates the cache, every concurrent request lands a database hit. At 5,000 RPM, that's ~17 simultaneous identical queries. Most databases handle that fine, but at 50,000 RPM it's 167 identical queries all at once. That's a cache stampede.

Real-world impact (2026 benchmarks):

Reddit Engineering reported a 3× reduction in database peak load after implementing request coalescing on their feed endpoints
Shopify's infrastructure team cited stampede-prevention as one of the top three techniques for surviving flash sales without DB overload
Cloudflare's edge cache uses a variant of this pattern called "request collapsing" by default

The single-flight pattern ensures that regardless of how many concurrent requests arrive for the same uncached resource, only one database round-trip is made.

The Single-Flight Pattern: Core Concept

The idea comes from Go's golang.org/x/sync/singleflight package, but it translates directly to async JavaScript using Promise sharing.

When a cache miss occurs:

Check if a promise for this key is already in-flight
If yes → subscribe to that existing promise (don't start a new one)
If no → start the operation, store the promise, broadcast the result to all waiters when it resolves

// singleflight.js — minimal implementation
class SingleFlight {
  constructor() {
    this.inFlight = new Map(); // key → Promise
  }

  async do(key, fn) {
    // Someone is already fetching this key — share their result
    if (this.inFlight.has(key)) {
      return this.inFlight.get(key);
    }

    // We're first — start the fetch and register the promise
    const promise = fn().finally(() => {
      this.inFlight.delete(key);
    });

    this.inFlight.set(key, promise);
    return promise;
  }

  get pendingCount() {
    return this.inFlight.size;
  }
}

module.exports = { SingleFlight };

This 25-line class is the entire pattern. Now let's integrate it with a real cache layer.

Building a Production Cache Layer with Single-Flight

Step 1: Install dependencies

npm install ioredis

Node.js 22+ and Bun 1.2+ are both supported. We'll use ioredis for Redis because it handles reconnection, pipelining, and cluster mode out of the box.

Step 2: The CacheWithSingleFlight class

// cache.js
const Redis = require('ioredis');
const { SingleFlight } = require('./singleflight');

class CacheWithSingleFlight {
  constructor({ redisUrl = 'redis://localhost:6379', defaultTtl = 60 } = {}) {
    this.redis = new Redis(redisUrl, {
      connectTimeout: 5000,
      commandTimeout: 3000,
      maxRetriesPerRequest: 2,
    });
    this.sf = new SingleFlight();
    this.defaultTtl = defaultTtl;
    this.hits = 0;
    this.misses = 0;
    this.coalesced = 0;
  }

  /**
   * Get a value from cache, or compute it exactly once even under concurrency.
   * @param {string} key   - Cache key
   * @param {Function} fn  - Async function to compute the value on cache miss
   * @param {number} ttl   - TTL in seconds (default: this.defaultTtl)
   */
  async get(key, fn, ttl = this.defaultTtl) {
    // Layer 1: Redis cache check (fast path — no coalescing needed)
    const cached = await this.redis.get(key);
    if (cached !== null) {
      this.hits++;
      return JSON.parse(cached);
    }

    // Layer 2: Cache miss → single-flight the actual fetch
    this.misses++;
    const wasInFlight = this.sf.inFlight.has(key);
    if (wasInFlight) this.coalesced++;

    return this.sf.do(key, async () => {
      // Double-check: another instance may have populated Redis while we waited
      const recheck = await this.redis.get(key);
      if (recheck !== null) {
        return JSON.parse(recheck);
      }

      const value = await fn();

      // Store in Redis asynchronously (don't block the caller)
      this.redis.setex(key, ttl, JSON.stringify(value)).catch((err) => {
        console.error(`[cache] Redis setex failed for key=${key}:`, err.message);
      });

      return value;
    });
  }

  /**
   * Invalidate a cache key (call after mutations).
   */
  async invalidate(key) {
    await this.redis.del(key);
  }

  /**
   * Return hit/miss/coalesced counters for monitoring.
   */
  stats() {
    const total = this.hits + this.misses;
    return {
      hits: this.hits,
      misses: this.misses,
      coalesced: this.coalesced,
      hitRate: total > 0 ? (this.hits / total).toFixed(3) : '0.000',
    };
  }
}

module.exports = { CacheWithSingleFlight };

Key design decisions:

The Redis check happens before entering the single-flight coalescer, keeping the hot path fast
A double-check inside the coalescer prevents a race between the Redis check and the lock acquisition
setex is fire-and-forget with a .catch() so a Redis write failure doesn't propagate to the caller
Counters enable Prometheus metrics or /healthz endpoint reporting

Express Integration

// app.js
const express = require('express');
const { CacheWithSingleFlight } = require('./cache');
const db = require('./db'); // your DB client

const app = express();
const cache = new CacheWithSingleFlight({ defaultTtl: 60 });

// GET /trending — expensive DB query, safely cached
app.get('/trending', async (req, res) => {
  try {
    const data = await cache.get(
      'trending:posts',
      () => db.query('SELECT * FROM posts ORDER BY views DESC LIMIT 20'),
      120 // 2-minute TTL
    );
    res.json({ data });
  } catch (err) {
    res.status(500).json({ error: 'Internal server error' });
  }
});

// GET /users/:id — per-resource caching
app.get('/users/:id', async (req, res) => {
  const { id } = req.params;
  const user = await cache.get(
    `user:${id}`,
    () => db.query('SELECT * FROM users WHERE id = $1', [id]),
    300 // 5-minute TTL
  );
  if (!user) return res.status(404).json({ error: 'Not found' });
  res.json(user);
});

// PUT /users/:id — invalidate cache after update
app.put('/users/:id', async (req, res) => {
  const { id } = req.params;
  const updated = await db.update('users', id, req.body);
  await cache.invalidate(`user:${id}`); // ← kill stale cache immediately
  res.json(updated);
});

// GET /cache/stats — expose metrics
app.get('/cache/stats', (req, res) => {
  res.json(cache.stats());
});

app.listen(3000, () => console.log('API running on :3000'));

The Thundering Herd in Numbers

To prove this actually works, here's a simulated load test comparing naive caching vs. single-flight:

// load-sim.js — simulate 200 concurrent requests on cache miss
async function simulateStampede(useCoalescing = false) {
  const db = { queryCount: 0 };
  const mockFetch = async () => {
    db.queryCount++;
    await new Promise((r) => setTimeout(r, 50)); // simulate 50ms DB query
    return { timestamp: Date.now() };
  };

  const cache = useCoalescing
    ? new CacheWithSingleFlight()
    : { get: (key, fn) => fn() }; // naive: no coalescing

  const requests = Array.from({ length: 200 }, () =>
    cache.get('trending', mockFetch, 60)
  );

  const start = Date.now();
  await Promise.all(requests);
  const elapsed = Date.now() - start;

  console.log(`Mode: ${useCoalescing ? 'Single-Flight' : 'Naive'}`);
  console.log(`DB queries: ${db.queryCount}`);
  console.log(`Elapsed: ${elapsed}ms`);
}

simulateStampede(false); // Naive: ~200 DB queries
simulateStampede(true);  // Single-flight: 1 DB query

Results on Node.js 22.14 (April 2026):

Mode	DB Queries	Elapsed
Naive (no coalescing)	200	~51ms
Single-Flight	1	~51ms

Same latency for the caller — but 199 fewer database hits. Under real load with slower queries (200–500ms), the difference is dramatic: the naive approach stacks 200× the DB load; single-flight stacks just 1×.

Extending to Multiple Instances with Redis Locks

The SingleFlight class above only deduplicates within a single Node.js process. If you run 10 API instances behind a load balancer, each process has its own in-flight map — so you can still get up to 10 simultaneous DB queries on a cache miss.

For cross-instance coalescing, use a Redis distributed lock:

// distributed-singleflight.js
const { randomUUID } = require('crypto');

class DistributedSingleFlight {
  constructor(redis, { lockTtl = 5, pollInterval = 50 } = {}) {
    this.redis = redis;
    this.lockTtl = lockTtl;       // seconds — how long a lock is held
    this.pollInterval = pollInterval; // ms — how often waiters poll for result
  }

  async do(key, fn) {
    const lockKey = `lock:sf:${key}`;
    const resultKey = `result:sf:${key}`;
    const lockId = randomUUID();

    // Try to acquire the distributed lock (NX = only if not exists)
    const acquired = await this.redis.set(lockKey, lockId, 'EX', this.lockTtl, 'NX');

    if (acquired) {
      // We're the leader — execute the function
      try {
        const value = await fn();
        // Publish result so waiters can grab it
        await this.redis.setex(resultKey, 10, JSON.stringify(value));
        return value;
      } finally {
        // Only delete our own lock (Lua script for atomicity)
        const releaseLua = `
          if redis.call("get", KEYS[1]) == ARGV[1] then
            return redis.call("del", KEYS[1])
          else
            return 0
          end
        `;
        await this.redis.eval(releaseLua, 1, lockKey, lockId);
      }
    } else {
      // We're a waiter — poll until result appears or lock expires
      return this._waitForResult(resultKey, lockKey);
    }
  }

  async _waitForResult(resultKey, lockKey, deadline = Date.now() + 6000) {
    while (Date.now() < deadline) {
      await new Promise((r) => setTimeout(r, this.pollInterval));

      const result = await this.redis.get(resultKey);
      if (result !== null) return JSON.parse(result);

      // Lock is gone — leader must have failed; try again
      const lockExists = await this.redis.exists(lockKey);
      if (!lockExists) {
        const recheck = await this.redis.get(resultKey);
        if (recheck !== null) return JSON.parse(recheck);
        break; // Give up and let the caller retry
      }
    }
    throw new Error('DistributedSingleFlight: timeout waiting for leader result');
  }
}

module.exports = { DistributedSingleFlight };

Tradeoffs of distributed coalescing:

Approach	Deduplication Scope	Latency overhead	Complexity
In-process SingleFlight	Per process	~0ms	Low
Redis distributed lock	Cluster-wide	1–3 RTTs (~2ms)	Medium
Cloudflare Durable Objects	Edge-wide	~5–15ms	High

For most applications, in-process single-flight is sufficient — cache hits handle 95%+ of requests, and the window for stampede is the ~200ms period immediately after a key expires. With 10 instances, that's at most 10 DB queries instead of 1. That's a 20× improvement over no coalescing at all.

Only add distributed coalescing if your DB query is very expensive (>1s) or your cache miss rate is high.

Probabilistic Early Expiration (XFetch)

A complementary technique: instead of waiting for the key to actually expire, proactively refresh it before it expires using probabilistic early expiration (the XFetch algorithm, used by Redis Labs):

/**
 * XFetch: probabilistic early cache refresh
 * Refreshes the key before it expires to avoid stampedes entirely.
 *
 * @param {Object} cached - { value, expiresAt, delta } from cache
 * @param {number} beta   - Tuning constant (default 1.0); higher = more aggressive refresh
 */
function shouldRefreshEarly(cached, beta = 1.0) {
  const now = Date.now() / 1000;
  const ttlRemaining = cached.expiresAt - now;
  // Higher delta (recompute time) and lower ttlRemaining → more likely to refresh
  return now - cached.delta * beta * Math.log(Math.random()) >= cached.expiresAt;
}

// Usage in cache.get():
async function getWithXFetch(key, fn, ttl) {
  const raw = await redis.get(key);
  if (raw) {
    const cached = JSON.parse(raw);
    if (!shouldRefreshEarly(cached)) {
      return cached.value; // Return cached, no refresh needed
    }
    // Probabilistically decided to refresh early — but return stale while refreshing
    singleFlight.do(`refresh:${key}`, () => fn().then((v) => redis.setex(key, ttl, JSON.stringify({
      value: v,
      delta: /* measured recompute time */ 0.1,
      expiresAt: Date.now() / 1000 + ttl,
    }))));
    return cached.value; // Return stale immediately
  }
  // Full cache miss — block and compute
  return singleFlight.do(key, fn);
}

XFetch eliminates the cold expiry window entirely by warming the cache slightly before the key dies. Combined with single-flight, your database never sees a stampede.

Monitoring and Alerting

Add these metrics to your observability stack (OpenTelemetry or Prometheus):

// metrics.js — emit cache behavior to your APM
const { metrics } = require('@opentelemetry/api');
const meter = metrics.getMeter('api-cache');

const cacheHits   = meter.createCounter('cache_hits_total');
const cacheMisses = meter.createCounter('cache_misses_total');
const coalesced   = meter.createCounter('cache_coalesced_total');

// In CacheWithSingleFlight.get():
// on hit:      cacheHits.add(1, { key_prefix: key.split(':')[0] });
// on miss:     cacheMisses.add(1, { key_prefix: key.split(':')[0] });
// on coalesce: coalesced.add(1, { key_prefix: key.split(':')[0] });

Alert thresholds (2026 recommendations):

Metric	Warning	Critical
Cache hit rate	< 80%	< 60%
Coalesced requests / total requests	> 10%	> 30%
Redis command timeout rate	> 0.5%	> 2%

A high coalesced rate (>10%) is a sign your TTLs are too short relative to traffic volume — consider increasing them or switching to XFetch.

Quick Checklist for Production

Before deploying single-flight caching to production:

[ ] Never cache null or empty results without a short TTL (30s) — null storms are a variant of cache stampede
[ ] Log cache misses at 5% sample rate to detect stampedes without overwhelming logs
[ ] Set Redis commandTimeout: 3000 — hanging Redis commands cause cascading failures
[ ] Test failover behavior — what happens if Redis is unreachable? Your get() should fall through to the DB, not throw
[ ] Invalidate on writes — stale reads are fine; stale writes are bugs
[ ] Measure coalesced counter — it directly shows how many DB hits you avoided

Summary

The single-flight pattern is one of those rare optimizations that's both simple (25 lines of code) and massively impactful (potentially 100–1000× reduction in DB load during peak traffic). Here's what you built today:

SingleFlight — in-process promise deduplication for zero-overhead coalescing
CacheWithSingleFlight — Redis-backed cache with automatic single-flight on miss
DistributedSingleFlight — Redis-lock-based coalescing across multiple instances
XFetch — probabilistic early expiration to eliminate the cold-expiry window
Observability — counters to measure your hit rate and coalesced request savings

If your API serves more than a few thousand requests per minute and relies on Redis for caching, add single-flight today. It's the most cost-effective reliability improvement you'll make this year.

Building an API you want to monetize? Check out 1xAPI on RapidAPI — a collection of production-ready APIs built with exactly these patterns.

How to Implement the Saga Pattern for Distributed Transactions in Node.js (2026 Guide)

1xApi — Sat, 04 Apr 2026 01:03:57 +0000

The hardest problem in distributed systems isn't handling failure — it's handling partial failure. When your order service successfully charges a card but the inventory service crashes before reserving stock, you have a real problem that a single database ROLLBACK can't solve.

The Saga pattern is the industry-standard solution for distributed transactions across microservices. In 2026, with most production Node.js systems running across multiple services, databases, and cloud functions, understanding Sagas is no longer optional — it's a core skill.

This guide shows you how to implement both flavors (choreography and orchestration) in Node.js with working code, Redis-backed state, and proper compensation logic.

What Problem Do Sagas Solve?

In a monolith, you write:

await db.transaction(async (trx) => {
  await chargeCard(userId, amount, trx);
  await reserveInventory(productId, qty, trx);
  await createOrder(userId, productId, trx);
});

If reserveInventory throws, the whole transaction rolls back. Clean.

In microservices, each service owns its own database. There is no shared transaction boundary. If your architecture looks like this:

Client → Order Service (PostgreSQL)
       → Payment Service (Stripe + MySQL)
       → Inventory Service (MongoDB)
       → Notification Service (Redis + Twilio)

You need a way to coordinate multi-step workflows and undo completed steps if a later step fails. That's exactly what the Saga pattern provides.

Saga vs. Two-Phase Commit (2PC)

Before diving into code, here's why Sagas beat 2PC for microservices:

	2PC	Saga
Blocking	Yes (coordinator waits)	No (async steps)
Availability	Low (lock-based)	High
Complexity	High	Medium
Failure recovery	Difficult	Explicit compensations
Node.js support	Poor	Excellent

2PC requires all participants to hold locks during the "prepare" phase. In a distributed Node.js system with network latency, this creates cascading timeouts. Sagas avoid locks entirely by using compensating transactions — explicit undo operations for each step.

Two Saga Flavors

Choreography: Event-Driven Saga

Each service publishes events and listens for events from others. No central coordinator.

OrderService       PaymentService     InventoryService
     |                   |                   |
  ORDER_CREATED ──────►  |                   |
     |            PAYMENT_PROCESSED ────────►|
     |                   |            INVENTORY_RESERVED
     |◄──────────────────────────────────────|
  ORDER_CONFIRMED

Pros: Loose coupling, no single point of failure

Cons: Hard to trace the full workflow, risk of cyclic dependencies

Orchestration: Central Coordinator

A dedicated "saga orchestrator" knows every step and calls services directly.

[Saga Orchestrator]
     ├── Step 1: Call PaymentService.charge()
     ├── Step 2: Call InventoryService.reserve()
     ├── Step 3: Call NotificationService.send()
     └── On failure: Run compensations in reverse

Pros: Easy to trace, single source of truth for workflow state

Cons: Orchestrator becomes a new service to maintain

For most production systems in 2026, orchestration is preferred for complex workflows because observability and debugging are dramatically easier.

Building an Orchestration Saga in Node.js

We'll build an e-commerce order saga: charge payment → reserve inventory → send confirmation. If any step fails, we run compensating transactions in reverse order.

Project Setup

npm init -y
npm install ioredis uuid express

Step 1: Define the Saga Steps

Each step has a execute function and a compensate function:

// saga/orderSagaSteps.js

export const orderSagaSteps = [
  {
    name: 'chargePayment',
    execute: async (context) => {
      const { userId, amount, orderId } = context;
      // In production: call your payment microservice
      const chargeId = `ch_${Date.now()}`;
      console.log(`[Saga] Charging $${amount} for order ${orderId}`);

      // Simulate API call to payment service
      const response = await fetch(`http://payment-service/charge`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ userId, amount, orderId }),
      });

      if (!response.ok) {
        throw new Error(`Payment failed: ${response.statusText}`);
      }

      const { chargeId: id } = await response.json();
      return { chargeId: id }; // Stored in context for compensation
    },
    compensate: async (context) => {
      const { chargeId } = context;
      if (!chargeId) return; // Never executed, nothing to undo
      console.log(`[Saga Compensation] Refunding charge ${chargeId}`);
      await fetch(`http://payment-service/refund/${chargeId}`, { method: 'POST' });
    },
  },
  {
    name: 'reserveInventory',
    execute: async (context) => {
      const { productId, quantity, orderId } = context;
      console.log(`[Saga] Reserving ${quantity}x product ${productId}`);

      const response = await fetch(`http://inventory-service/reserve`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ productId, quantity, orderId }),
      });

      if (!response.ok) {
        throw new Error(`Inventory reservation failed: ${response.statusText}`);
      }

      const { reservationId } = await response.json();
      return { reservationId };
    },
    compensate: async (context) => {
      const { reservationId } = context;
      if (!reservationId) return;
      console.log(`[Saga Compensation] Releasing reservation ${reservationId}`);
      await fetch(`http://inventory-service/release/${reservationId}`, { method: 'POST' });
    },
  },
  {
    name: 'confirmOrder',
    execute: async (context) => {
      const { orderId, userId } = context;
      console.log(`[Saga] Confirming order ${orderId}`);

      await fetch(`http://order-service/confirm/${orderId}`, { method: 'PATCH' });
      await fetch(`http://notification-service/send`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ userId, event: 'ORDER_CONFIRMED', orderId }),
      });
      return { confirmed: true };
    },
    compensate: async (context) => {
      const { orderId } = context;
      console.log(`[Saga Compensation] Cancelling order ${orderId}`);
      await fetch(`http://order-service/cancel/${orderId}`, { method: 'PATCH' });
    },
  },
];

Step 2: The Saga Orchestrator

This is the core engine. It executes steps sequentially, persists state to Redis, and runs compensations in reverse on failure:

// saga/SagaOrchestrator.js
import Redis from 'ioredis';
import { randomUUID } from 'crypto';

const redis = new Redis(process.env.REDIS_URL || 'redis://localhost:6379');
const SAGA_TTL = 60 * 60 * 24; // 24 hours

export class SagaOrchestrator {
  constructor(sagaId, steps) {
    this.sagaId = sagaId || randomUUID();
    this.steps = steps;
  }

  async loadState() {
    const raw = await redis.get(`saga:${this.sagaId}`);
    return raw ? JSON.parse(raw) : null;
  }

  async saveState(state) {
    await redis.setex(`saga:${this.sagaId}`, SAGA_TTL, JSON.stringify(state));
  }

  async execute(initialContext) {
    let state = await this.loadState();

    // Initialize or resume
    if (!state) {
      state = {
        sagaId: this.sagaId,
        status: 'running',
        currentStep: 0,
        context: { ...initialContext },
        completedSteps: [],
        startedAt: new Date().toISOString(),
      };
      await this.saveState(state);
    }

    console.log(`[Saga ${this.sagaId}] Starting from step ${state.currentStep}`);

    // Execute steps starting from where we left off (supports resume on crash)
    for (let i = state.currentStep; i < this.steps.length; i++) {
      const step = this.steps[i];
      console.log(`[Saga ${this.sagaId}] Executing step: ${step.name}`);

      try {
        const result = await step.execute(state.context);

        // Merge results into context for next steps and compensations
        state.context = { ...state.context, ...result };
        state.completedSteps.push(step.name);
        state.currentStep = i + 1;
        await this.saveState(state);

        console.log(`[Saga ${this.sagaId}] Step ${step.name} succeeded`);
      } catch (error) {
        console.error(`[Saga ${this.sagaId}] Step ${step.name} failed: ${error.message}`);
        state.status = 'compensating';
        state.failedStep = step.name;
        state.error = error.message;
        await this.saveState(state);

        // Run compensations in reverse
        await this.compensate(state);
        return { success: false, sagaId: this.sagaId, failedAt: step.name, error: error.message };
      }
    }

    state.status = 'completed';
    state.completedAt = new Date().toISOString();
    await this.saveState(state);

    console.log(`[Saga ${this.sagaId}] Completed successfully`);
    return { success: true, sagaId: this.sagaId, context: state.context };
  }

  async compensate(state) {
    // Run compensations in reverse order of completion
    const stepsToCompensate = [...state.completedSteps].reverse();

    for (const stepName of stepsToCompensate) {
      const step = this.steps.find((s) => s.name === stepName);
      if (!step) continue;

      try {
        console.log(`[Saga ${this.sagaId}] Compensating: ${stepName}`);
        await step.compensate(state.context);
        console.log(`[Saga ${this.sagaId}] Compensated: ${stepName}`);
      } catch (compError) {
        // Compensation failure is critical — alert your on-call team
        console.error(`[Saga ${this.sagaId}] COMPENSATION FAILED for ${stepName}: ${compError.message}`);
        // Store for manual recovery
        await redis.lpush(
          'saga:stuck_compensations',
          JSON.stringify({ sagaId: this.sagaId, step: stepName, error: compError.message, context: state.context })
        );
      }
    }

    const finalState = await this.loadState();
    finalState.status = 'compensated';
    finalState.compensatedAt = new Date().toISOString();
    await this.saveState(finalState);
  }
}

Step 3: Wire It Into Your Express API

// routes/orders.js
import express from 'express';
import { SagaOrchestrator } from '../saga/SagaOrchestrator.js';
import { orderSagaSteps } from '../saga/orderSagaSteps.js';
import { randomUUID } from 'crypto';

const router = express.Router();

router.post('/orders', async (req, res) => {
  const { userId, productId, quantity, amount } = req.body;
  const orderId = randomUUID();
  const sagaId = randomUUID();

  const orchestrator = new SagaOrchestrator(sagaId, orderSagaSteps);

  const result = await orchestrator.execute({
    orderId,
    userId,
    productId,
    quantity,
    amount,
  });

  if (result.success) {
    return res.status(201).json({
      orderId,
      sagaId: result.sagaId,
      status: 'confirmed',
    });
  }

  return res.status(422).json({
    error: 'Order could not be completed',
    reason: result.error,
    sagaId: result.sagaId,
    compensated: true,
  });
});

// Check saga status (useful for debugging and client polling)
router.get('/orders/saga/:sagaId', async (req, res) => {
  const raw = await redis.get(`saga:${req.params.sagaId}`);
  if (!raw) return res.status(404).json({ error: 'Saga not found' });
  res.json(JSON.parse(raw));
});

export default router;

Handling Stuck Compensations

One of the most dangerous scenarios in Saga patterns is a failed compensation — your payment was charged, the inventory step failed, and now your refund call is also failing. You have inconsistent state.

The solution: a compensation recovery queue.

// workers/compensationRecovery.js
import Redis from 'ioredis';

const redis = new Redis(process.env.REDIS_URL);

async function processStuckCompensations() {
  while (true) {
    // Block-pop with 30-second timeout
    const item = await redis.blpop('saga:stuck_compensations', 30);
    if (!item) continue;

    const { sagaId, step, context } = JSON.parse(item[1]);
    console.log(`[Recovery] Retrying compensation for saga ${sagaId}, step ${step}`);

    // Retry with exponential backoff
    let attempt = 0;
    while (attempt < 5) {
      try {
        await step.compensate(context); // Retry
        console.log(`[Recovery] Successfully compensated ${step} for saga ${sagaId}`);
        break;
      } catch (err) {
        attempt++;
        const delay = Math.pow(2, attempt) * 1000; // 2s, 4s, 8s, 16s, 32s
        await new Promise((r) => setTimeout(r, delay));
      }
    }

    if (attempt === 5) {
      // Escalate to human: PagerDuty, Slack alert, etc.
      console.error(`[Recovery] MANUAL INTERVENTION REQUIRED for saga ${sagaId}`);
      await redis.lpush('saga:requires_manual_review', item[1]);
    }
  }
}

processStuckCompensations();

Choreography Saga: Event-Driven Alternative

For simpler workflows or when you want maximum decoupling, the choreography approach uses events:

// Using Node.js EventEmitter for in-process (use Redis pub/sub for multi-process)
import { EventEmitter } from 'events';

const sagaBus = new EventEmitter();

// Payment Service listener
sagaBus.on('ORDER_CREATED', async ({ orderId, userId, amount }) => {
  try {
    await chargeUser(userId, amount);
    sagaBus.emit('PAYMENT_PROCESSED', { orderId, userId });
  } catch {
    sagaBus.emit('PAYMENT_FAILED', { orderId, userId, amount });
  }
});

// Inventory Service listener
sagaBus.on('PAYMENT_PROCESSED', async ({ orderId }) => {
  try {
    await reserveStock(orderId);
    sagaBus.emit('INVENTORY_RESERVED', { orderId });
  } catch {
    sagaBus.emit('INVENTORY_FAILED', { orderId });
    sagaBus.emit('PAYMENT_REVERSE', { orderId }); // Trigger compensation
  }
});

// Compensation listener
sagaBus.on('PAYMENT_REVERSE', async ({ orderId }) => {
  console.log(`Refunding payment for order ${orderId}`);
  await issueRefund(orderId);
});

// Trigger the saga
sagaBus.emit('ORDER_CREATED', {
  orderId: 'ord_123',
  userId: 'user_456',
  amount: 49.99,
});

For production, replace EventEmitter with Redis Pub/Sub, BullMQ, or Kafka to persist events across process restarts.

Choreography vs. Orchestration: When to Use Each

Scenario	Use
Complex multi-step workflow (5+ steps)	Orchestration
Need full audit trail / debugging	Orchestration
Loosely coupled, independent services	Choreography
Simple 2–3 step flow	Choreography
Workflows that may need to pause/resume	Orchestration
Temporal-style durable workflows	Orchestration

Production Checklist for Sagas in 2026

1. Make all steps idempotent. If the orchestrator retries a step after a crash, running it twice should be safe. Use the orderId or sagaId as an idempotency key in downstream services.

2. Persist saga state before each step. Don't rely on in-memory state. Our Redis-backed approach handles server restarts and crashes.

3. Monitor saga duration. Long-running sagas should alert if they exceed expected completion time:

// Alert if saga takes > 30 seconds
if (Date.now() - new Date(state.startedAt).getTime() > 30_000) {
  await alertOncall(`Slow saga: ${this.sagaId}`);
}

4. Build a saga dashboard. Query your Redis keys with SCAN saga:* and expose a /admin/sagas endpoint to see in-flight and stuck sagas.

5. Test compensation paths explicitly. Most teams only test the happy path. Write tests that force failures at each step and verify compensations run correctly.

// Example with vitest / jest
it('should refund payment if inventory fails', async () => {
  mockPaymentService.charge.mockResolvedValueOnce({ chargeId: 'ch_123' });
  mockInventoryService.reserve.mockRejectedValueOnce(new Error('Out of stock'));
  mockPaymentService.refund.mockResolvedValueOnce({});

  const result = await orchestrator.execute(testContext);

  expect(result.success).toBe(false);
  expect(mockPaymentService.refund).toHaveBeenCalledWith('ch_123');
});

Conclusion

The Saga pattern solves one of the hardest problems in microservices: keeping data consistent across service boundaries without distributed locks. In 2026, with APIs increasingly split across serverless functions, edge workers, and independent services, Sagas are an essential tool.

Key takeaways:

Orchestration is easier to debug and trace; use it for complex workflows
Choreography offers better decoupling; use it for simple, independent steps
Always implement compensation logic — assume failures will happen
Persist saga state to Redis so you can resume after crashes
Handle stuck compensations explicitly with a recovery queue

If you're building APIs that need to be reliable under failure conditions, consider publishing them on RapidAPI so consumers can integrate them with confidence into their own distributed systems.

How to Implement RBAC + ABAC Authorization in Node.js APIs (2026 Guide)

1xApi — Fri, 03 Apr 2026 01:07:41 +0000

Building a production API without proper authorization is like locking your front door but leaving the windows open. Authentication answers who are you? — authorization answers what can you do?

Most Node.js tutorials stop at JWT verification. That's authentication. Real security requires a layered authorization model, and in 2026 the industry consensus is clear: combine RBAC (Role-Based Access Control) with ABAC (Attribute-Based Access Control) to cover both coarse-grained and fine-grained access control.

This guide walks you through implementing both patterns from scratch — no heavy external dependencies, production-ready middleware, and patterns used in real SaaS APIs.

What's the Difference? RBAC vs ABAC

RBAC assigns permissions to roles, and roles to users. Simple, fast, easy to reason about:

user → roles[] → permissions[]

Example: A moderator can delete:comment but not delete:user. An admin can do both.

ABAC grants access based on arbitrary attributes of the subject (user), resource, and environment:

allow IF user.department == resource.department AND time.hour < 18

Example: A doctor can only read patients in their own department, and only during business hours.

The catch: RBAC breaks down when you need resource-level permissions ("Alice can edit her own post, but no one else's"). ABAC breaks down when you have thousands of policies — it becomes a policy management nightmare.

The solution used in production: Use RBAC as your coarse filter (fast, cached), then ABAC as your fine-grained check (dynamic, contextual).

Project Setup

mkdir api-auth-patterns && cd api-auth-patterns
npm init -y
npm install express jsonwebtoken zod
npm install -D @types/node typescript ts-node

We'll use Express for the examples, but the patterns apply to Hono, Fastify, ElysiaJS, or any Node.js framework.

Step 1: Define Your Permission Schema

Start by modeling permissions as strings: resource:action. This is the most portable format — it works in JWTs, databases, and policy engines.

// src/types/auth.ts
export type Permission =
  | 'posts:read'
  | 'posts:create'
  | 'posts:update'
  | 'posts:delete'
  | 'users:read'
  | 'users:update'
  | 'users:delete'
  | 'analytics:read'
  | 'billing:read'
  | 'billing:update';

export type Role = 'viewer' | 'editor' | 'moderator' | 'admin';

export interface AuthUser {
  id: string;
  email: string;
  roles: Role[];
  organizationId: string;
  department?: string;
  attributes?: Record<string, unknown>;
}

export interface JWTPayload extends AuthUser {
  iat: number;
  exp: number;
}

Step 2: The Role-Permission Matrix (RBAC Core)

// src/auth/rbac.ts
import { Permission, Role } from '../types/auth';

// Role → Permissions mapping. In production, load this from a DB or config service.
const ROLE_PERMISSIONS: Record<Role, Permission[]> = {
  viewer: [
    'posts:read',
    'analytics:read',
  ],
  editor: [
    'posts:read',
    'posts:create',
    'posts:update',
    'analytics:read',
  ],
  moderator: [
    'posts:read',
    'posts:create',
    'posts:update',
    'posts:delete',
    'users:read',
    'analytics:read',
  ],
  admin: [
    'posts:read',
    'posts:create',
    'posts:update',
    'posts:delete',
    'users:read',
    'users:update',
    'users:delete',
    'analytics:read',
    'billing:read',
    'billing:update',
  ],
};

// Cache expanded permissions per role combo (avoids recomputing on every request)
const permissionCache = new Map<string, Set<Permission>>();

export function getPermissionsForRoles(roles: Role[]): Set<Permission> {
  const cacheKey = [...roles].sort().join(',');

  if (permissionCache.has(cacheKey)) {
    return permissionCache.get(cacheKey)!;
  }

  const permissions = new Set<Permission>();
  for (const role of roles) {
    const rolePerms = ROLE_PERMISSIONS[role] ?? [];
    for (const perm of rolePerms) {
      permissions.add(perm);
    }
  }

  permissionCache.set(cacheKey, permissions);
  return permissions;
}

export function hasPermission(roles: Role[], permission: Permission): boolean {
  return getPermissionsForRoles(roles).has(permission);
}

Step 3: RBAC Middleware

// src/middleware/rbac.ts
import { Request, Response, NextFunction } from 'express';
import { Permission } from '../types/auth';
import { hasPermission } from '../auth/rbac';

// Extend Express Request to include the authenticated user
declare global {
  namespace Express {
    interface Request {
      user?: import('../types/auth').AuthUser;
    }
  }
}

/**
 * Middleware factory: requires the authenticated user to have ALL listed permissions.
 * Usage: router.get('/posts', requirePermissions('posts:read'), handler)
 */
export function requirePermissions(...permissions: Permission[]) {
  return (req: Request, res: Response, next: NextFunction): void => {
    if (!req.user) {
      res.status(401).json({ error: 'Authentication required' });
      return;
    }

    const missingPermissions = permissions.filter(
      (perm) => !hasPermission(req.user!.roles, perm)
    );

    if (missingPermissions.length > 0) {
      res.status(403).json({
        error: 'Insufficient permissions',
        required: permissions,
        missing: missingPermissions,
      });
      return;
    }

    next();
  };
}

/**
 * Middleware factory: requires the user to have at least ONE of the listed permissions.
 * Usage: requireAnyPermission('posts:update', 'posts:delete')
 */
export function requireAnyPermission(...permissions: Permission[]) {
  return (req: Request, res: Response, next: NextFunction): void => {
    if (!req.user) {
      res.status(401).json({ error: 'Authentication required' });
      return;
    }

    const hasAny = permissions.some((perm) =>
      hasPermission(req.user!.roles, perm)
    );

    if (!hasAny) {
      res.status(403).json({
        error: 'Insufficient permissions',
        required: `one of: ${permissions.join(', ')}`,
      });
      return;
    }

    next();
  };
}

Step 4: ABAC Policy Engine

ABAC policies are functions that take (user, resource, context) and return allow | deny. Keep them pure — no side effects, easy to test.

// src/auth/abac.ts
import { AuthUser } from '../types/auth';

export interface PolicyContext {
  action: string;
  resource?: Record<string, unknown>;
  environment?: {
    ip?: string;
    userAgent?: string;
    timestamp?: Date;
  };
}

export type PolicyResult = 'allow' | 'deny' | 'abstain';

export type PolicyFunction = (
  user: AuthUser,
  context: PolicyContext
) => PolicyResult;

/**
 * Policy: users can only modify their own resources
 */
const ownershipPolicy: PolicyFunction = (user, context) => {
  if (!context.resource) return 'abstain';

  const isOwner =
    context.resource.authorId === user.id ||
    context.resource.userId === user.id ||
    context.resource.ownerId === user.id;

  if (['update', 'delete'].includes(context.action)) {
    return isOwner ? 'allow' : 'deny';
  }

  return 'abstain';
};

/**
 * Policy: same-organization isolation (multi-tenant)
 */
const organizationPolicy: PolicyFunction = (user, context) => {
  if (!context.resource) return 'abstain';

  if (context.resource.organizationId !== undefined) {
    return context.resource.organizationId === user.organizationId
      ? 'allow'
      : 'deny';
  }

  return 'abstain';
};

/**
 * Policy: admins bypass all restrictions
 */
const adminBypassPolicy: PolicyFunction = (user, _context) => {
  return user.roles.includes('admin') ? 'allow' : 'abstain';
};

/**
 * Policy: rate-limit sensitive actions outside business hours (UTC+7)
 */
const businessHoursPolicy: PolicyFunction = (user, context) => {
  if (context.action !== 'delete') return 'abstain';

  const now = context.environment?.timestamp ?? new Date();
  // Convert to Asia/Bangkok (UTC+7)
  const hour = (now.getUTCHours() + 7) % 24;

  // Destructive actions outside 08:00-20:00 require admin
  if (hour < 8 || hour >= 20) {
    return user.roles.includes('admin') ? 'allow' : 'deny';
  }

  return 'abstain';
};

// Policy registry - evaluated in order (first non-abstain wins, deny beats allow)
const policies: PolicyFunction[] = [
  adminBypassPolicy,     // Admins always win
  businessHoursPolicy,   // Time-based restrictions
  organizationPolicy,    // Org isolation (multi-tenant)
  ownershipPolicy,       // Resource ownership
];

/**
 * Evaluate all policies: returns true if access should be allowed.
 * Strategy: any 'deny' blocks access. 'allow' required from at least one policy.
 * If all policies abstain, access is denied by default (secure-by-default).
 */
export function evaluatePolicies(
  user: AuthUser,
  context: PolicyContext
): boolean {
  let hasAllow = false;

  for (const policy of policies) {
    const result = policy(user, context);

    if (result === 'deny') return false;   // Hard stop
    if (result === 'allow') hasAllow = true;
  }

  return hasAllow; // Deny if nothing explicitly allowed
}

Step 5: Combined RBAC + ABAC Middleware

The key insight: RBAC gates whether you can perform an action at all, ABAC gates whether you can perform it on a specific resource.

// src/middleware/authorize.ts
import { Request, Response, NextFunction } from 'express';
import { Permission } from '../types/auth';
import { hasPermission } from '../auth/rbac';
import { evaluatePolicies, PolicyContext } from '../auth/abac';

interface AuthorizeOptions {
  permission: Permission;
  /** Callback to load the resource being accessed */
  getResource?: (req: Request) => Promise<Record<string, unknown> | null>;
  /** The action for ABAC evaluation (defaults to the HTTP method) */
  action?: string;
}

export function authorize(options: AuthorizeOptions) {
  return async (req: Request, res: Response, next: NextFunction): Promise<void> => {
    const { permission, getResource, action } = options;

    // 1. Authentication check
    if (!req.user) {
      res.status(401).json({ error: 'Authentication required' });
      return;
    }

    // 2. RBAC check (fast, in-memory, cached)
    if (!hasPermission(req.user.roles, permission)) {
      res.status(403).json({
        error: 'Forbidden',
        detail: `Missing permission: ${permission}`,
      });
      return;
    }

    // 3. ABAC check (only when a resource loader is provided)
    if (getResource) {
      const resource = await getResource(req);

      if (!resource) {
        res.status(404).json({ error: 'Resource not found' });
        return;
      }

      // Attach resource to request for the route handler
      (req as any).resource = resource;

      const abacContext: PolicyContext = {
        action: action ?? req.method.toLowerCase(),
        resource,
        environment: {
          ip: req.ip,
          userAgent: req.headers['user-agent'],
          timestamp: new Date(),
        },
      };

      const allowed = evaluatePolicies(req.user, abacContext);

      if (!allowed) {
        res.status(403).json({
          error: 'Forbidden',
          detail: 'Access denied by authorization policy',
        });
        return;
      }
    }

    next();
  };
}

Step 6: Wire It All Together

// src/routes/posts.ts
import { Router } from 'express';
import { authorize } from '../middleware/authorize';
import { requirePermissions } from '../middleware/rbac';
import { db } from '../db'; // your database layer

const router = Router();

// List posts - RBAC only (no resource to load)
router.get(
  '/',
  requirePermissions('posts:read'),
  async (req, res) => {
    const posts = await db.posts.findByOrg(req.user!.organizationId);
    res.json(posts);
  }
);

// Get single post - RBAC + ABAC (org isolation check)
router.get(
  '/:id',
  authorize({
    permission: 'posts:read',
    getResource: async (req) => db.posts.findById(req.params.id),
    action: 'read',
  }),
  (req, res) => {
    res.json((req as any).resource);
  }
);

// Update post - RBAC + ABAC (must own the post or be admin)
router.put(
  '/:id',
  authorize({
    permission: 'posts:update',
    getResource: async (req) => db.posts.findById(req.params.id),
    action: 'update',
  }),
  async (req, res) => {
    const updated = await db.posts.update(req.params.id, req.body);
    res.json(updated);
  }
);

// Delete post - RBAC + ABAC + time restriction
router.delete(
  '/:id',
  authorize({
    permission: 'posts:delete',
    getResource: async (req) => db.posts.findById(req.params.id),
    action: 'delete',
  }),
  async (req, res) => {
    await db.posts.delete(req.params.id);
    res.status(204).send();
  }
);

export default router;

Step 7: JWT Authentication Middleware (Bonus)

// src/middleware/authenticate.ts
import { Request, Response, NextFunction } from 'express';
import jwt from 'jsonwebtoken';
import { JWTPayload } from '../types/auth';

const JWT_SECRET = process.env.JWT_SECRET!;

export function authenticate(req: Request, res: Response, next: NextFunction): void {
  const authHeader = req.headers.authorization;

  if (!authHeader?.startsWith('Bearer ')) {
    res.status(401).json({ error: 'Missing or malformed Authorization header' });
    return;
  }

  const token = authHeader.slice(7);

  try {
    const payload = jwt.verify(token, JWT_SECRET) as JWTPayload;

    req.user = {
      id: payload.id,
      email: payload.email,
      roles: payload.roles,
      organizationId: payload.organizationId,
      department: payload.department,
      attributes: payload.attributes,
    };

    next();
  } catch (err) {
    res.status(401).json({ error: 'Invalid or expired token' });
  }
}

Testing Your Authorization Layer

Unit test your policies in isolation — they're pure functions, so this is easy:

// src/auth/abac.test.ts
import { evaluatePolicies } from './abac';
import { AuthUser } from '../types/auth';

const viewer: AuthUser = {
  id: 'user-1',
  email: 'alice@example.com',
  roles: ['viewer'],
  organizationId: 'org-1',
};

const admin: AuthUser = {
  id: 'admin-1',
  email: 'admin@example.com',
  roles: ['admin'],
  organizationId: 'org-1',
};

describe('ownershipPolicy', () => {
  it('allows a user to update their own resource', () => {
    const result = evaluatePolicies(viewer, {
      action: 'update',
      resource: { id: 'post-1', authorId: 'user-1', organizationId: 'org-1' },
    });
    expect(result).toBe(true);
  });

  it("denies a user from updating someone else's resource", () => {
    const result = evaluatePolicies(viewer, {
      action: 'update',
      resource: { id: 'post-2', authorId: 'user-999', organizationId: 'org-1' },
    });
    expect(result).toBe(false);
  });

  it('allows admin to update any resource (bypass)', () => {
    const result = evaluatePolicies(admin, {
      action: 'update',
      resource: { id: 'post-2', authorId: 'user-999', organizationId: 'org-99' },
    });
    expect(result).toBe(true);
  });
});

Performance Considerations

Cache permission sets aggressively. Role-to-permission mapping is static. The permissionCache in Step 2 ensures you never recompute the same set twice.

Keep ABAC policies synchronous where possible. If a policy needs a database hit, batch-load the context before calling evaluatePolicies. Don't make DB calls inside each policy function.

Log authorization decisions. In production, log every deny with userId, permission, resourceId, and reason — this is your audit trail:

if (!allowed) {
  logger.warn('authorization_denied', {
    userId: req.user.id,
    permission,
    resourceId: resource.id,
    action,
    ip: req.ip,
  });
}

Summary

Layer	What it does	When to use
RBAC	Coarse permission check	Always — fast, cached, simple
ABAC (ownership)	Resource-level access	User-generated content, profiles
ABAC (org isolation)	Multi-tenant isolation	SaaS, multi-org APIs
ABAC (time/env)	Contextual restrictions	Compliance, sensitive actions

The combination gives you security-in-depth: even if an attacker escalates their role, ABAC policies block cross-tenant and cross-user access. Even if an ABAC policy has a bug, RBAC serves as a hard outer gate.

Start with RBAC only. Add ABAC policies as you encounter access control requirements that roles can't express cleanly. That's how most production APIs evolve — and it keeps your code maintainable.

For complex multi-tenant SaaS with hundreds of permission rules, consider dedicated policy engines like Casbin, Open Policy Agent (OPA), or Permify.

Need to monetize your API? Check out 1xAPI on RapidAPI for ready-to-use API services.

How to Use the ES2026 Temporal API in Node.js REST APIs (2026 Guide)

1xApi — Thu, 02 Apr 2026 01:06:07 +0000

After 9 years in development and countless TC39 meetings, the JavaScript Temporal API officially reached Stage 4 on March 11, 2026, locking it into the ES2026 specification. That means it's no longer a proposal — it's the future of date and time handling in JavaScript, and you should start using it in your Node.js APIs today.

If you've ever shipped a date-related bug in production — DST edge cases, wrong timezone conversions, silent mutation bugs from Date.setDate() — you're not alone. The Date object was designed in 1995, copied from Java, and has been causing developer pain ever since. Temporal is the fix.

This guide covers how to use the ES2026 Temporal API in Node.js REST APIs with practical, real-world patterns: storing timestamps correctly, comparing durations, handling multi-timezone scheduling, and returning ISO 8601 dates from your endpoints.

What's Wrong with `Date` in 2026?

Let's be blunt. The JavaScript Date object is broken by design:

// Classic confusion: is this UTC or local?
const d = new Date('2026-04-01');
console.log(d.getDate()); // Could be March 31 in UTC-5 timezones!

// Mutable by default — easy to introduce bugs
const start = new Date();
const end = start; // Same reference!
end.setDate(end.getDate() + 7); // Mutates start too

// No timezone support
new Date().toLocaleString('en-US', { timeZone: 'Asia/Ho_Chi_Minh' });
// Works, but fragile — no first-class TZ type

These aren't edge cases. They're production bugs waiting to happen. Every "scheduled for Monday" bug, every "appointment shows wrong time in a different region" complaint traces back to the Date object's fundamental design flaws.

The Temporal Fix: Type-Safe, Immutable, Timezone-Aware

Temporal introduces distinct types for distinct concerns. No more guessing:

Type	Use Case
`Temporal.Instant`	A precise UTC moment (like a Unix timestamp)
`Temporal.ZonedDateTime`	A moment + timezone (for scheduling)
`Temporal.PlainDate`	A calendar date (no time, no timezone)
`Temporal.PlainTime`	A wall-clock time (no date, no timezone)
`Temporal.PlainDateTime`	Date + time without timezone info
`Temporal.Duration`	A length of time (e.g., "2 hours 30 minutes")

All Temporal objects are immutable. Operations return new objects. No more mutation surprises.

Getting Started: Install the Polyfill

While Temporal is ES2026 standard, native support in Node.js 24 requires the --harmony-temporal flag (V8 implementation is in progress as of April 2026). For production APIs, use the official polyfill:

npm install @js-temporal/polyfill

// In Node.js 24 with --harmony-temporal flag (experimental):
// const { Temporal } = globalThis;

// For production today (polyfill approach):
import { Temporal } from '@js-temporal/polyfill';

// Or CommonJS:
const { Temporal } = require('@js-temporal/polyfill');

Note: Major browsers (Chrome 129+, Firefox 139+, Safari 18.4+) have started shipping native Temporal support as of early 2026. Node.js native support without a flag is expected in Node.js 24 LTS updates later in 2026.

Pattern 1: Storing and Returning Timestamps in REST APIs

The most common mistake: using new Date() and calling .toISOString() without thinking about what you're actually storing.

The wrong way:

// What timezone is this? What format is the client expecting?
app.get('/events/:id', async (req, res) => {
  const event = await db.query('SELECT * FROM events WHERE id = $1', [req.params.id]);
  res.json({
    ...event,
    startsAt: event.starts_at.toISOString(), // Loses timezone info!
  });
});

The Temporal way — explicit and unambiguous:

import { Temporal } from '@js-temporal/polyfill';

app.get('/events/:id', async (req, res) => {
  const event = await db.query('SELECT * FROM events WHERE id = $1', [req.params.id]);

  // Convert DB timestamp (stored as UTC) to Temporal.Instant
  const instant = Temporal.Instant.fromEpochMilliseconds(
    event.starts_at.getTime()
  );

  // Return UTC instant (canonical form for APIs)
  res.json({
    id: event.id,
    title: event.title,
    startsAt: instant.toString(), // "2026-06-15T09:00:00Z" — always UTC, always unambiguous
    timezone: event.timezone,     // Store the original timezone separately
  });
});

Even better — return timezone-aware datetimes:

app.get('/events/:id', async (req, res) => {
  const event = await db.query('SELECT * FROM events WHERE id = $1', [req.params.id]);

  const instant = Temporal.Instant.fromEpochMilliseconds(
    event.starts_at.getTime()
  );

  // Convert to the event's original timezone
  const zdt = instant.toZonedDateTimeISO(event.timezone);

  res.json({
    id: event.id,
    title: event.title,
    startsAt: {
      utc: instant.toString(),
      local: zdt.toString(), // "2026-06-15T16:00:00+07:00[Asia/Ho_Chi_Minh]"
      timezone: event.timezone,
    },
  });
});

This is the pattern used by modern scheduling APIs — always store UTC, always return the original timezone context alongside it.

Pattern 2: Accepting and Validating Date Inputs

Validating date inputs with new Date() is fragile — it silently accepts bad input. Temporal throws on invalid data, making it a natural validation layer.

import { Temporal } from '@js-temporal/polyfill';

function parseEventInput(body) {
  let startDate, endDate;

  try {
    // Strict ISO 8601 parsing — throws on invalid input
    startDate = Temporal.Instant.from(body.startsAt);
  } catch (e) {
    throw new Error(`Invalid startsAt: "${body.startsAt}" is not a valid ISO 8601 timestamp`);
  }

  try {
    endDate = Temporal.Instant.from(body.endsAt);
  } catch (e) {
    throw new Error(`Invalid endsAt: "${body.endsAt}" is not a valid ISO 8601 timestamp`);
  }

  // Validate logical ordering
  if (Temporal.Instant.compare(startDate, endDate) >= 0) {
    throw new Error('endsAt must be after startsAt');
  }

  // Validate minimum duration (e.g., events must be at least 15 minutes)
  const duration = startDate.until(endDate);
  if (duration.total('minutes') < 15) {
    throw new Error('Event must be at least 15 minutes long');
  }

  return { startDate, endDate };
}

app.post('/events', async (req, res) => {
  try {
    const { startDate, endDate } = parseEventInput(req.body);

    // Store as epoch milliseconds in the database
    await db.query(
      'INSERT INTO events (title, starts_at, ends_at) VALUES ($1, $2, $3)',
      [
        req.body.title,
        new Date(startDate.epochMilliseconds),
        new Date(endDate.epochMilliseconds),
      ]
    );

    res.status(201).json({ message: 'Event created' });
  } catch (e) {
    res.status(400).json({ error: e.message });
  }
});

Pattern 3: Multi-Timezone Scheduling Logic

This is where Temporal truly shines. Building a scheduling API that works across timezones is notoriously painful. Here's a clean pattern for "find available slots" in a given user's timezone:

import { Temporal } from '@js-temporal/polyfill';

/**
 * Get the next 7 available booking slots, in the user's local timezone.
 * Business hours: 9 AM - 5 PM, Monday-Friday
 */
function getAvailableSlots(userTimezone, existingBookings = []) {
  const slots = [];
  let current = Temporal.Now.zonedDateTimeISO(userTimezone);

  // Start from the next full hour
  current = current.round({ smallestUnit: 'hour', roundingMode: 'ceil' });

  while (slots.length < 7) {
    const hour = current.hour;
    const dayOfWeek = current.dayOfWeek; // 1=Mon, 7=Sun

    // Skip weekends
    if (dayOfWeek <= 5 && hour >= 9 && hour < 17) {
      const slotEnd = current.add({ hours: 1 });

      // Check if slot is already booked
      const isBooked = existingBookings.some(booking => {
        const bookingStart = Temporal.Instant.from(booking.startsAt)
          .toZonedDateTimeISO(userTimezone);
        return Temporal.ZonedDateTime.compare(bookingStart, current) === 0;
      });

      if (!isBooked) {
        slots.push({
          startsAt: current.toInstant().toString(),
          endsAt: slotEnd.toInstant().toString(),
          localTime: current.toPlainTime().toString(),
          localDate: current.toPlainDate().toString(),
          timezone: userTimezone,
        });
      }
    }

    current = current.add({ hours: 1 });
  }

  return slots;
}

app.get('/slots', async (req, res) => {
  const { timezone = 'UTC' } = req.query;

  try {
    // Validate the timezone
    Temporal.TimeZone.from(timezone); // Throws if invalid
  } catch (e) {
    return res.status(400).json({ error: `Invalid timezone: "${timezone}"` });
  }

  const bookings = await db.query('SELECT * FROM bookings WHERE starts_at > NOW()');
  const slots = getAvailableSlots(timezone, bookings.rows);

  res.json({ timezone, slots });
});

Pattern 4: Duration Calculations for Billing and Rate Limiting

import { Temporal } from '@js-temporal/polyfill';

// API usage tracking — calculate billable time
app.get('/usage/:userId', async (req, res) => {
  const sessions = await db.query(
    'SELECT started_at, ended_at FROM api_sessions WHERE user_id = $1',
    [req.params.userId]
  );

  let totalDuration = new Temporal.Duration();

  for (const session of sessions.rows) {
    const start = Temporal.Instant.fromEpochMilliseconds(session.started_at.getTime());
    const end = Temporal.Instant.fromEpochMilliseconds(session.ended_at.getTime());

    const sessionDuration = start.until(end, { largestUnit: 'hours' });
    totalDuration = totalDuration.add(sessionDuration);
  }

  const normalized = Temporal.Duration.from(totalDuration);

  res.json({
    userId: req.params.userId,
    totalUsage: {
      hours: normalized.hours,
      minutes: normalized.minutes,
      seconds: normalized.seconds,
      totalMinutes: Math.floor(normalized.total('minutes')),
    },
    billableUnits: Math.ceil(normalized.total('minutes') / 15),
  });
});

Pattern 5: Relative Time Without moment.js

import { Temporal } from '@js-temporal/polyfill';

function relativeTime(isoString) {
  const then = Temporal.Instant.from(isoString);
  const now = Temporal.Now.instant();
  const isFuture = Temporal.Instant.compare(then, now) > 0;
  const absDuration = isFuture
    ? now.until(then, { largestUnit: 'years' })
    : then.until(now, { largestUnit: 'years' });

  if (absDuration.years >= 1) return `${absDuration.years}y ${isFuture ? 'from now' : 'ago'}`;
  if (absDuration.months >= 1) return `${absDuration.months}mo ${isFuture ? 'from now' : 'ago'}`;
  if (absDuration.weeks >= 1) return `${absDuration.weeks}w ${isFuture ? 'from now' : 'ago'}`;
  if (absDuration.days >= 1) return `${absDuration.days}d ${isFuture ? 'from now' : 'ago'}`;
  if (absDuration.hours >= 1) return `${absDuration.hours}h ${isFuture ? 'from now' : 'ago'}`;
  if (absDuration.minutes >= 1) return `${absDuration.minutes}m ${isFuture ? 'from now' : 'ago'}`;
  return 'just now';
}

Quick Reference: `Date` → Temporal Migrations

// Get current time
// Before: new Date()
// After:  Temporal.Now.instant()

// Parse ISO string
// Before: new Date('2026-04-01T09:00:00Z')
// After:  Temporal.Instant.from('2026-04-01T09:00:00Z')

// Add time
// Before: new Date(date.getTime() + 7 * 24 * 60 * 60 * 1000)
// After:  instant.add({ days: 7 })

// Compare dates
// Before: date1 > date2
// After:  Temporal.Instant.compare(instant1, instant2) > 0

// Format for API response
// Before: date.toISOString()
// After:  instant.toString()

Conclusion

The ES2026 Temporal API is the biggest improvement to JavaScript date handling since the language was created. With Stage 4 confirmed on March 11, 2026, and the polyfill production-ready today, there's no reason to wait.

Start with @js-temporal/polyfill. Use Temporal.Instant for UTC storage, Temporal.ZonedDateTime for scheduling logic, and Temporal.Duration for billing and rate limiting. Your future self — and your API consumers — will thank you.

Building APIs? 1xAPI provides developer tools and API infrastructure.

How to Add Structured Logging to Node.js APIs with Pino 9 + OpenTelemetry (2026 Guide)

1xApi — Wed, 01 Apr 2026 01:02:29 +0000

Logging is the first thing you reach for when something breaks in production. Yet most Node.js APIs still write plain-text console.log statements that are useless in a distributed system. In 2026, structured JSON logging correlated with distributed traces is the baseline for any serious API. This guide shows you exactly how to wire up Pino 9 + OpenTelemetry so that every log line carries a traceId and spanId, making root-cause analysis a matter of seconds rather than hours.

Why `console.log` Kills You at Scale

Before diving in, let's be concrete about the problem. A log like this:

[2026-04-01T08:00:12.345Z] ERROR: Payment failed for user 8821

Is useless when you have 50 services and 10,000 concurrent requests. Questions you cannot answer:

Which request triggered this? (no requestId)
Which upstream call failed? (no traceId)
What was the user's cart value? (no business context)
How long did it take to reach this point? (no timing)

Structured logging + trace correlation solves all of this.

Stack Overview (2026)

Tool	Version	Role
Pino	9.x	Ultra-fast JSON logger (5–10× faster than Winston)
pino-http	10.x	HTTP request/response auto-logging middleware
@opentelemetry/sdk-node	0.58.x	Auto-instrumentation + trace/span management
pino-opentelemetry-transport	1.x	Bridge: injects `traceId`/`spanId` into every log
@opentelemetry/exporter-otlp-http	0.58.x	Sends traces to Grafana Tempo / Jaeger / Honeycomb

Note: All package versions cited are current as of April 2026. Run npm outdated after install to confirm latest patches.

Project Setup

mkdir pino-otel-api && cd pino-otel-api
npm init -y

# Core logger + HTTP middleware
npm install pino pino-http

# OpenTelemetry SDK + trace exporter
npm install @opentelemetry/sdk-node @opentelemetry/api \
  @opentelemetry/auto-instrumentations-node \
  @opentelemetry/exporter-trace-otlp-http \
  @opentelemetry/resources \
  @opentelemetry/semantic-conventions

# Pino ↔ OTel bridge
npm install pino-opentelemetry-transport

# API framework
npm install express

Step 1: Bootstrap OpenTelemetry (Must Load First)

Create otel.js — this must be required before any other module so auto-instrumentation patches load correctly:

// otel.js
'use strict';

const { NodeSDK } = require('@opentelemetry/sdk-node');
const { getNodeAutoInstrumentations } = require('@opentelemetry/auto-instrumentations-node');
const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-http');
const { Resource } = require('@opentelemetry/resources');
const { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION } = require('@opentelemetry/semantic-conventions');

const sdk = new NodeSDK({
  resource: new Resource({
    [ATTR_SERVICE_NAME]: process.env.SERVICE_NAME || 'payment-api',
    [ATTR_SERVICE_VERSION]: process.env.SERVICE_VERSION || '1.0.0',
  }),
  traceExporter: new OTLPTraceExporter({
    url: process.env.OTEL_EXPORTER_OTLP_ENDPOINT || 'http://localhost:4318/v1/traces',
  }),
  instrumentations: [
    getNodeAutoInstrumentations({
      '@opentelemetry/instrumentation-fs': { enabled: false }, // Noisy; disable unless needed
    }),
  ],
});

sdk.start();

// Graceful flush on shutdown
process.on('SIGTERM', () => sdk.shutdown().finally(() => process.exit(0)));
process.on('SIGINT',  () => sdk.shutdown().finally(() => process.exit(0)));

Step 2: Configure Pino with OTel Transport

Create logger.js. The key trick is using pino-opentelemetry-transport as a transport — Pino's worker-thread transport system — so trace context injection happens asynchronously without blocking the event loop:

// logger.js
'use strict';

const pino = require('pino');

const logger = pino(
  {
    level: process.env.LOG_LEVEL || 'info',

    // Rename default fields to match OpenTelemetry log data model
    messageKey: 'body',
    timestamp: pino.stdTimeFunctions.isoTime,

    // Redact sensitive fields — never log tokens or PII
    redact: {
      paths: ['req.headers.authorization', 'req.headers.cookie', '*.password', '*.token'],
      censor: '[REDACTED]',
    },

    // Base fields on every log line
    base: {
      service: process.env.SERVICE_NAME || 'payment-api',
      env: process.env.NODE_ENV || 'development',
    },

    formatters: {
      level(label) {
        return { level: label.toUpperCase() }; // OTel-compatible level strings
      },
    },
  },
  // Transport: inject traceId + spanId automatically
  pino.transport({
    targets: [
      {
        target: 'pino-opentelemetry-transport',
        options: {},
        level: 'trace',
      },
      // Also write to stdout for local dev (pretty in dev, raw JSON in prod)
      process.env.NODE_ENV !== 'production'
        ? { target: 'pino-pretty', options: { colorize: true }, level: 'trace' }
        : { target: 'pino/file',   options: { destination: 1 },  level: 'info' },
    ],
  })
);

module.exports = logger;

What a Log Line Looks Like in Production

With this setup, every log automatically includes:

{
  "level": "ERROR",
  "time": "2026-04-01T08:00:12.345Z",
  "service": "payment-api",
  "env": "production",
  "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
  "spanId": "00f067aa0ba902b7",
  "traceFlags": "01",
  "body": "Payment failed",
  "userId": 8821,
  "cartValue": 129.99,
  "errorCode": "CARD_DECLINED"
}

Now you can jump straight from this log to the full distributed trace in Grafana Tempo with a single click on traceId.

Step 3: Add HTTP Request Logging Middleware

// middleware/requestLogger.js
'use strict';

const pinoHttp = require('pino-http');
const logger   = require('../logger');

module.exports = pinoHttp({
  logger,

  // Custom request serializer — add business context
  customProps(req) {
    return {
      requestId: req.headers['x-request-id'] || crypto.randomUUID(),
      userId:    req.user?.id,
      tenantId:  req.headers['x-tenant-id'],
    };
  },

  // Log 4xx as warn, 5xx as error
  customLogLevel(req, res, err) {
    if (res.statusCode >= 500 || err) return 'error';
    if (res.statusCode >= 400)        return 'warn';
    return 'info';
  },

  // Exclude noisy health checks
  autoLogging: {
    ignore: (req) => req.url === '/health' || req.url === '/metrics',
  },

  // Serialize only what matters
  serializers: {
    req: (req) => ({
      method:    req.method,
      url:       req.url,
      userAgent: req.headers['user-agent'],
    }),
    res: (res) => ({
      statusCode: res.statusCode,
    }),
  },
});

Step 4: Wire It All Together in `server.js`

// server.js — OTel MUST be first
require('./otel');

const express = require('express');
const logger  = require('./logger');
const requestLogger = require('./middleware/requestLogger');

const app = express();
app.use(express.json());
app.use(requestLogger);

// Child logger — inherits traceId/spanId + adds route context
app.post('/payments', async (req, res) => {
  const log = logger.child({ route: 'POST /payments', userId: req.body.userId });

  try {
    log.info({ cartValue: req.body.amount }, 'Processing payment');

    const result = await processPayment(req.body); // your business logic

    log.info({ transactionId: result.id }, 'Payment succeeded');
    res.json({ success: true, transactionId: result.id });

  } catch (err) {
    // Always log the full error with context
    log.error({ err, cartValue: req.body.amount }, 'Payment failed');
    res.status(500).json({ error: 'Payment processing failed' });
  }
});

app.get('/health', (req, res) => res.json({ status: 'ok' }));

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => logger.info({ port: PORT }, 'Server started'));

Step 5: Child Loggers — The Secret to Context-Rich Logs

One of Pino's most powerful features is child loggers. They inherit the parent's transport (and thus trace context) while adding request-scoped fields:

// In a service layer
class PaymentService {
  constructor(baseLogger, requestContext) {
    // Every log from this service instance carries userId + requestId
    this.log = baseLogger.child({
      component: 'PaymentService',
      userId:    requestContext.userId,
      requestId: requestContext.requestId,
    });
  }

  async chargeCard(amount, cardToken) {
    this.log.info({ amount }, 'Initiating card charge');

    const start = Date.now();
    try {
      const result = await stripeClient.charges.create({ amount, source: cardToken });
      this.log.info({ chargeId: result.id, durationMs: Date.now() - start }, 'Card charge succeeded');
      return result;
    } catch (err) {
      this.log.error({ err, amount, durationMs: Date.now() - start }, 'Card charge failed');
      throw err;
    }
  }
}

Because child loggers are created via Object.create() in Pino 9, they have zero serialization overhead until a message is actually logged.

Sampling: Don't Log Everything at 100%

At high traffic (10k+ req/s), logging every request is expensive. Configure head-based sampling in your OTel SDK:

// In otel.js — sample 10% of traces in production
const { TraceIdRatioBased } = require('@opentelemetry/sdk-trace-base');

const sdk = new NodeSDK({
  // ...
  sampler: process.env.NODE_ENV === 'production'
    ? new TraceIdRatioBased(0.1)   // 10% sampling
    : new AlwaysOnSampler(),        // 100% in dev
});

Tip: Always sample at 100% for errors regardless of the base rate. Use Tail-Based Sampling in a collector if you need retroactive error sampling.

Sending Logs to Grafana Loki (Production Setup)

For a complete observability stack (traces → Tempo, logs → Loki, metrics → Prometheus), add the Loki transport:

npm install pino-loki

// Updated logger.js transport targets for production
targets: [
  {
    target: 'pino-opentelemetry-transport',
    level: 'trace',
  },
  {
    target: 'pino-loki',
    level: 'info',
    options: {
      host: process.env.LOKI_HOST || 'http://localhost:3100',
      labels: {
        service: process.env.SERVICE_NAME,
        env: process.env.NODE_ENV,
      },
      // Batch logs for efficiency
      interval: 5, // seconds
    },
  },
],

With this config, your logs land in Loki with traceId labels, making the Grafana "Logs → Traces" pivot a single click.

Environment Variable Reference

# Service identity
SERVICE_NAME=payment-api
SERVICE_VERSION=1.2.3
NODE_ENV=production

# Log level (trace|debug|info|warn|error|fatal)
LOG_LEVEL=info

# OTel collector endpoint
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318/v1/traces

# Loki endpoint
LOKI_HOST=http://loki:3100

Performance: Pino vs Winston vs Bunyan (2026 Benchmarks)

Pino 9 remains the fastest structured logger for Node.js. Internal benchmarks on Node.js 22 (M3 MacBook Pro):

Logger	Ops/sec (log to file)	Memory (100k messages)
`pino`	~380,000	18 MB
`winston`	~52,000	41 MB
`bunyan`	~63,000	35 MB
`console.log`	~95,000	22 MB (unstructured)

Pino achieves this by doing JSON serialization in a worker thread (via its transport system), keeping the main thread free for your business logic. For APIs handling thousands of requests per second, this gap is real and measurable.

Common Mistakes to Avoid

❌ Logging inside hot loops

// BAD — creates a new child logger object on every iteration
items.forEach(item => {
  logger.child({ itemId: item.id }).info('Processing item');
});

// GOOD — create child logger once, outside the loop
const itemLog = logger.child({ batchId: batch.id });
items.forEach(item => {
  itemLog.info({ itemId: item.id }, 'Processing item');
});

❌ Logging `Error` objects without the `err` key

// BAD — Pino won't serialize the stack trace correctly
logger.error(`Payment failed: ${err.message}`);

// GOOD — Pino knows to serialize err.stack, err.type, err.code
logger.error({ err }, 'Payment failed');

❌ Blocking the event loop with synchronous log destinations

// BAD — pino.destination() is sync by default
const logger = pino(pino.destination('./app.log')); // blocks on every write!

// GOOD — use async destination
const logger = pino(pino.destination({ dest: './app.log', sync: false }));

// BETTER — use transport (worker thread, fully async)
const logger = pino({}, pino.transport({ target: 'pino/file', options: { destination: './app.log' } }));

Connecting Logs to 1xAPI Calls

If your API consumes external APIs via 1xAPI, propagate your trace context in outgoing requests using W3C traceparent headers:

const { propagation, context } = require('@opentelemetry/api');

async function callExternalAPI(endpoint, payload) {
  const headers = { 'Content-Type': 'application/json' };

  // Inject current trace context into outbound request headers
  propagation.inject(context.active(), headers);

  const response = await fetch(endpoint, {
    method: 'POST',
    headers,
    body: JSON.stringify(payload),
  });

  return response.json();
}

The receiving service (if it also runs OTel) will automatically create a child span linked to your trace, giving you an end-to-end view of every external call.

Quick-Start Checklist

[ ] require('./otel') is the first line in server.js
[ ] pino-opentelemetry-transport is in the transport targets
[ ] Sensitive fields are redacted via pino.redact
[ ] Child loggers are used per request/component (not one global logger)
[ ] Health check endpoints are excluded from auto-logging
[ ] { err } (not err.message) is always the first arg for errors
[ ] Async destination (transport or sync: false) is used in production

Summary

Replacing ad-hoc console.log calls with structured Pino logging correlated to OpenTelemetry traces is one of the highest-ROI changes you can make to a production Node.js API. You get:

Machine-readable JSON queryable in Loki, Elasticsearch, or CloudWatch
Automatic traceId/spanId on every log line via pino-opentelemetry-transport
Performance headroom — Pino 9 is 7× faster than Winston with worker-thread transport
Developer ergonomics — child loggers, redaction, and pretty-printing for local dev
One-click trace pivots in Grafana: log → trace → spans in seconds

Start with the minimal setup (Steps 1–3), validate it works, then layer in Loki and sampling for production. Your on-call rotation will thank you.

How to Implement Graceful Shutdown in Node.js APIs (Zero Dropped Requests on Deploy)

1xApi — Tue, 31 Mar 2026 01:02:55 +0000

Deploying a Node.js API without proper graceful shutdown is like pulling the power cord on a running server. Every rolling deploy, every Kubernetes pod restart, every Docker container stop — if your app ignores SIGTERM, you're dropping in-flight requests, corrupting database transactions, and leaving clients staring at 502 errors.

This guide covers everything you need to implement graceful shutdown correctly in Node.js APIs in 2026 — from the basics of SIGTERM handling to keep-alive connection draining, database cleanup, Kubernetes configuration, and production-tested patterns.

Why Graceful Shutdown Matters in 2026

Modern APIs live in orchestrated environments. Kubernetes, Docker Swarm, ECS, and even simple docker compose down — all of them use the same shutdown sequence:

Container receives SIGTERM (polite stop)
Orchestrator waits terminationGracePeriodSeconds (Kubernetes default: 30s)
If still running: container receives SIGKILL (force kill, no cleanup)

Two failure modes are common:

Pattern 1 — The Ignore: App doesn't listen to SIGTERM at all. Docker waits 10s then SIGKILL. Every in-flight request dies.

Pattern 2 — The Instant Exit: App calls process.exit(0) immediately on SIGTERM. Same result — requests dropped, database connections severed mid-query.

The cost: during a rolling deploy on a busy API handling 1,000 req/s, each 10s hard shutdown kills ~10,000 requests. With 5 pods rolling, that's 50,000 errors every deploy.

The Minimal Correct Implementation

Here's the foundation — every Node.js API should have this:

// server.js
import express from 'express';

const app = express();

app.get('/api/health', (req, res) => res.json({ status: 'ok' }));

app.get('/api/data', async (req, res) => {
  const data = await db.query('SELECT * FROM items LIMIT 100');
  res.json(data);
});

const server = app.listen(3000, () => {
  console.log('Server listening on :3000');
});

async function shutdown(signal) {
  console.log(`${signal} received — starting graceful shutdown`);

  // 1. Stop accepting new connections
  server.close(async () => {
    console.log('HTTP server closed');

    // 2. Close DB connections cleanly
    await db.end();
    console.log('Database pool closed');

    process.exit(0);
  });

  // 3. Force exit if drain takes too long
  setTimeout(() => {
    console.error('Shutdown timeout — forcing exit');
    process.exit(1);
  }, 10_000);
}

process.on('SIGTERM', () => shutdown('SIGTERM')); // Docker / Kubernetes
process.on('SIGINT',  () => shutdown('SIGINT'));  // Ctrl+C

This is correct but incomplete. There's a critical problem: keep-alive connections.

The Keep-Alive Connection Problem

HTTP/1.1 keep-alive connections stay open between requests. When server.close() is called, Node.js stops accepting new connections but waits for all existing keep-alive connections to close on their own. A client that opened a keep-alive connection 5 minutes ago is still "connected" even if it hasn't sent a request in 4 minutes.

Result: server.close() callback never fires, your 10s timeout kicks in, and you get a hard exit anyway.

The fix is to track connections and destroy idle ones immediately on shutdown:

// connection-tracker.js
export function trackConnections(server) {
  const connections = new Map();
  let shuttingDown = false;

  server.on('connection', (socket) => {
    connections.set(socket, { idle: true, createdAt: Date.now() });

    socket.on('close', () => connections.delete(socket));
  });

  // Mark connection as active when handling a request
  server.on('request', (req, res) => {
    const socket = req.socket;
    const conn = connections.get(socket);
    if (conn) conn.idle = false;

    res.on('finish', () => {
      const conn = connections.get(socket);
      if (conn) {
        conn.idle = true;
        // If we're shutting down, destroy idle connections immediately
        if (shuttingDown) {
          socket.destroy();
        }
      }
    });
  });

  return {
    destroy() {
      shuttingDown = true;
      for (const [socket, meta] of connections) {
        if (meta.idle) {
          socket.destroy(); // Kill idle keep-alive connections
        }
        // Active connections will be destroyed when their request finishes (above)
      }
    },
    count: () => connections.size,
  };
}

// server.js
import express from 'express';
import { trackConnections } from './connection-tracker.js';

const app = express();
const server = app.listen(3000);
const tracker = trackConnections(server);

async function shutdown(signal) {
  console.log(`${signal} — draining requests`);
  console.log(`Active connections: ${tracker.count()}`);

  // Destroy idle keep-alive connections immediately
  tracker.destroy();

  server.close(async () => {
    await db.end();
    process.exit(0);
  });

  setTimeout(() => {
    console.error(`Shutdown timeout with ${tracker.count()} connections remaining`);
    process.exit(1);
  }, 30_000);
}

process.on('SIGTERM', () => shutdown('SIGTERM'));
process.on('SIGINT',  () => shutdown('SIGINT'));

Alternatively, use the well-maintained stoppable npm package (4M+ weekly downloads) which does this for you:

import stoppable from 'stoppable';

const server = stoppable(app.listen(3000), 10_000); // 10s grace period

async function shutdown(signal) {
  server.stop(async (err) => {
    if (err) console.error('Shutdown error:', err);
    await db.end();
    process.exit(err ? 1 : 0);
  });
}

Draining In-Flight Requests Properly

For APIs with long-running requests (file uploads, heavy queries, streaming responses), you need a request counter so you can know exactly when it's safe to exit:

// in-flight-tracker.js
let inFlight = 0;
let shuttingDown = false;

export function inFlightMiddleware(req, res, next) {
  if (shuttingDown) {
    // Reject new requests during shutdown with 503
    res.set('Connection', 'close');
    return res.status(503).json({
      error: 'Service shutting down',
      retryAfter: 5,
    });
  }

  inFlight++;
  res.on('finish', () => {
    inFlight--;
    if (shuttingDown && inFlight === 0) {
      console.log('All in-flight requests drained');
    }
  });

  next();
}

export function startShutdown() {
  shuttingDown = true;
  return new Promise((resolve) => {
    if (inFlight === 0) return resolve();
    const interval = setInterval(() => {
      console.log(`Waiting for ${inFlight} in-flight requests...`);
      if (inFlight === 0) {
        clearInterval(interval);
        resolve();
      }
    }, 500);
  });
}

import express from 'express';
import { inFlightMiddleware, startShutdown } from './in-flight-tracker.js';

const app = express();
app.use(inFlightMiddleware); // Must be first middleware

async function shutdown(signal) {
  console.log(`${signal} — draining requests`);

  await Promise.race([
    startShutdown(),
    new Promise((_, reject) =>
      setTimeout(() => reject(new Error('Drain timeout')), 25_000)
    ),
  ]);

  await db.end();
  await redis.quit();
  process.exit(0);
}

Resource Cleanup Order

Order matters. Clean up in reverse dependency order:

async function shutdown(signal) {
  console.log(`${signal} — graceful shutdown started at ${new Date().toISOString()}`);

  const steps = [
    // 1. Stop health check passing (Kubernetes removes from load balancer)
    () => {
      isHealthy = false;
      console.log('Health check disabled');
    },

    // 2. Small delay so load balancer picks up health status
    () => new Promise(resolve => setTimeout(resolve, 2_000)),

    // 3. Stop accepting new connections
    () => new Promise((resolve, reject) => server.close((err) => err ? reject(err) : resolve())),

    // 4. Drain in-flight requests
    () => startShutdown(),

    // 5. Flush message queue / complete pending jobs
    () => queue.close({ timeout: 10_000 }),

    // 6. Close cache connections
    () => redis.quit(),

    // 7. Close database pool last (queries may be running until step 4 completes)
    () => db.end(),
  ];

  for (const step of steps) {
    try {
      await step();
    } catch (err) {
      console.error('Shutdown step failed:', err.message);
    }
  }

  console.log('Graceful shutdown complete');
  process.exit(0);
}

Kubernetes Configuration

Your Node.js code and Kubernetes config must be aligned. The key rule: terminationGracePeriodSeconds must always be greater than your application shutdown timeout.

# deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: api-service
spec:
  replicas: 3
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxUnavailable: 0     # Never remove a pod before its replacement is ready
      maxSurge: 1           # Add 1 extra pod during rollout
  template:
    spec:
      terminationGracePeriodSeconds: 60  # Must be > app shutdown timeout (we use 30s)
      containers:
        - name: api
          image: my-api:latest
          ports:
            - containerPort: 3000
          readinessProbe:
            httpGet:
              path: /api/health
              port: 3000
            initialDelaySeconds: 5
            periodSeconds: 5
            failureThreshold: 3
          livenessProbe:
            httpGet:
              path: /api/health
              port: 3000
            initialDelaySeconds: 15
            periodSeconds: 10
          lifecycle:
            preStop:
              exec:
                # Give load balancer 5s to route away before SIGTERM fires
                command: ["/bin/sleep", "5"]
          env:
            - name: SHUTDOWN_TIMEOUT_MS
              value: "30000"

The preStop hook is critical. Kubernetes sends SIGTERM at the same time it removes the pod from the load balancer's endpoint list — but the load balancer takes a few seconds to propagate. Without the preStop sleep, your pod receives SIGTERM and starts refusing connections while the load balancer still routes traffic to it, causing 5–10 seconds of 503 errors on every deploy.

With preStop: sleep 5 and terminationGracePeriodSeconds: 60, you get:

0s: Pod enters terminating state, Kubernetes starts removing from endpoints
5s: preStop completes, SIGTERM sent to container
5–35s: Application drains connections
35s: process.exit(0) if clean, or...
60s: Kubernetes sends SIGKILL (safety net)

Health Check Integration

Your /health endpoint should reflect shutdown state:

let isHealthy = true;
let isReady = true;

// Liveness probe — is the process alive?
app.get('/api/health/live', (req, res) => {
  res.status(isHealthy ? 200 : 503).json({ status: isHealthy ? 'ok' : 'shutting_down' });
});

// Readiness probe — should this pod receive traffic?
app.get('/api/health/ready', (req, res) => {
  res.status(isReady ? 200 : 503).json({
    status: isReady ? 'ready' : 'not_ready',
    uptime: process.uptime(),
  });
});

async function shutdown(signal) {
  // First thing: fail readiness check
  // Kubernetes will stop sending new traffic within ~10s (periodSeconds * failureThreshold)
  isReady = false;

  // Wait for Kubernetes to notice (3 failed checks × 5s = 15s)
  await new Promise(resolve => setTimeout(resolve, 15_000));

  // Now drain and exit
  // ...
}

Handling Uncaught Exceptions

Unhandled promise rejections and uncaught exceptions should also trigger graceful shutdown — not crash immediately:

process.on('uncaughtException', async (err) => {
  console.error('Uncaught exception:', err);
  await logger.error('uncaughtException', { error: err.message, stack: err.stack });
  await shutdown('uncaughtException');
});

process.on('unhandledRejection', async (reason) => {
  console.error('Unhandled rejection:', reason);
  await logger.error('unhandledRejection', { reason: String(reason) });
  // For unhandled rejections: log, don't exit — they may be non-fatal
  // If your policy is to exit: call shutdown() here
});

Testing Graceful Shutdown

Don't deploy without testing it. A simple test:

// test/graceful-shutdown.test.js
import { describe, it, before, after } from 'node:test';
import assert from 'node:assert';
import { spawn } from 'node:child_process';

describe('Graceful Shutdown', () => {
  let proc;

  before(() => {
    proc = spawn('node', ['server.js'], {
      env: { ...process.env, PORT: '3100' },
    });
  });

  after(() => proc?.kill('SIGKILL'));

  it('completes in-flight requests before exiting', async () => {
    // Wait for server to start
    await new Promise(resolve => setTimeout(resolve, 500));

    // Start a slow request
    const requestPromise = fetch('http://localhost:3100/api/slow'); // takes 2s

    // Send SIGTERM 200ms later
    await new Promise(resolve => setTimeout(resolve, 200));
    proc.kill('SIGTERM');

    // The slow request should still complete
    const res = await requestPromise;
    assert.strictEqual(res.status, 200);
  });

  it('returns 503 for new requests after shutdown starts', async () => {
    await new Promise(resolve => setTimeout(resolve, 200));
    proc.kill('SIGTERM');
    await new Promise(resolve => setTimeout(resolve, 100));

    const res = await fetch('http://localhost:3100/api/data').catch(() => null);
    // Either 503 or connection refused — both are correct
    assert.ok(!res || res.status === 503);
  });
});

Production Checklist

Before deploying, verify:

[ ] SIGTERM and SIGINT handlers are registered
[ ] server.close() is called (stops accepting new connections)
[ ] Keep-alive connections are explicitly destroyed or use stoppable
[ ] In-flight requests are tracked and drained
[ ] Database/cache connections are closed in dependency order
[ ] A hard timeout (setTimeout with process.exit(1)) is set as a safety net
[ ] terminationGracePeriodSeconds > app shutdown timeout + preStop delay
[ ] Readiness probe is failed before draining (so load balancer routes away)
[ ] Graceful shutdown is covered by integration tests

Summary

Graceful shutdown is a first-class operational concern, not an afterthought. The pattern is always the same:

Fail readiness → load balancer stops routing
Stop accepting → server.close()
Drain connections → destroy idle keep-alives, wait for active requests
Clean up resources → queues, cache, database (in reverse dependency order)
Exit cleanly → process.exit(0) with a hard timeout safety net

For APIs published on 1xAPI, this is especially important — clients retry on failure, and a graceful shutdown means their retry hits the new version instead of getting a connection reset.

Implement it once, test it properly, and never drop a request on deploy again.

How to Implement Zero-Downtime Graceful Shutdown in Node.js APIs (2026 Guide)

1xApi — Mon, 30 Mar 2026 01:02:11 +0000

Zero-downtime deployments are only possible if your API can shut down cleanly. Without a proper graceful shutdown, rolling deployments drop in-flight requests, Kubernetes rolls back, and your users see 502 errors.

This guide covers everything you need to implement production-grade graceful shutdown in Node.js APIs in 2026 — from basic SIGTERM handling to connection draining, health check transitions, and Kubernetes lifecycle hooks.

Why Graceful Shutdown Matters in 2026

Modern APIs run in containerized, orchestrated environments (Kubernetes, ECS, Cloud Run). When you deploy a new version:

The orchestrator sends SIGTERM to the old pod
It waits for terminationGracePeriodSeconds (default: 30s)
If the process hasn't exited, it sends SIGKILL — forcefully terminating all connections

Without handling SIGTERM, your Node.js process dies instantly, dropping every in-flight request mid-response. In a busy API with hundreds of concurrent connections, this causes a flood of 502/504 errors.

The cost: lost transactions, broken API clients, Kubernetes health check failures, and potential rollbacks.

The Five Stages of Graceful Shutdown

A production-grade shutdown follows this sequence:

Receive SIGTERM — stop accepting new requests
Signal readiness/liveness probes — return 503 from /health so load balancers deregister you
Drain in-flight requests — wait for all active requests to complete
Close resource connections — DB pools, Redis, message queues, file handles
Exit cleanly — process.exit(0) with success code

Skip any step, and you either drop requests or leave zombie connections in your database pool.

Basic SIGTERM Handler

Here's the minimum viable graceful shutdown for an Express API:

import express from 'express';
import http from 'http';

const app = express();
const server = http.createServer(app);

let isShuttingDown = false;

// Health check — returns 503 during shutdown so LB stops routing
app.get('/health', (req, res) => {
  if (isShuttingDown) {
    return res.status(503).json({ status: 'shutting_down' });
  }
  res.json({ status: 'healthy', uptime: process.uptime() });
});

app.get('/api/users', async (req, res) => {
  const users = await db.query('SELECT * FROM users LIMIT 20');
  res.json(users);
});

async function gracefulShutdown(signal: string) {
  console.log(`[${signal}] Starting graceful shutdown...`);
  isShuttingDown = true;

  // Stop accepting new connections
  server.close(async (err) => {
    if (err) {
      console.error('Error closing server:', err);
      process.exit(1);
    }

    try {
      await Promise.all([
        db.end(),         // close DB pool
        redis.quit(),     // close Redis connection
      ]);
      console.log('All connections closed. Exiting cleanly.');
      process.exit(0);
    } catch (cleanupErr) {
      console.error('Cleanup error:', cleanupErr);
      process.exit(1);
    }
  });

  // Force-exit safety valve — Kubernetes will SIGKILL at 30s anyway
  setTimeout(() => {
    console.error('Graceful shutdown timed out. Forcing exit.');
    process.exit(1);
  }, 25000);
}

process.on('SIGTERM', () => gracefulShutdown('SIGTERM'));
process.on('SIGINT',  () => gracefulShutdown('SIGINT'));

server.listen(3000, () => console.log('API listening on :3000'));

The key insight here: returning 503 from /health is the most important step. It tells your Kubernetes readiness probe and any upstream load balancer to stop routing new traffic to this pod immediately, giving in-flight requests time to drain before the connection count hits zero.

The Keep-Alive Connection Problem

server.close() stops accepting new connections, but there's a subtle trap: HTTP/1.1 keep-alive connections keep the server alive indefinitely.

If a client opened a persistent connection and is sitting idle between requests, server.close() won't close that socket — it waits for the client to close it naturally. In practice, this means your server can hang for the full grace period without ever exiting.

The Fix: Track and Destroy Idle Connections

const activeConnections = new Set<import('net').Socket>();

server.on('connection', (socket) => {
  activeConnections.add(socket);
  socket.on('close', () => activeConnections.delete(socket));
});

// Inside gracefulShutdown, after server.close():
function destroyIdleConnections() {
  for (const socket of activeConnections) {
    // Only destroy sockets with no pending request (idle keep-alive)
    // @ts-ignore — _httpMessage is internal but reliable
    if (!socket._httpMessage || socket._httpMessage.finished) {
      socket.destroy();
      activeConnections.delete(socket);
    }
  }
}

// Call this after server.close() to push idle connections out
destroyIdleConnections();

This forces idle keep-alive sockets closed immediately while letting active requests finish naturally. Node.js 22+ does not yet close idle keep-alive connections automatically during server.close() — there's an open GitHub issue (#60617) tracking this for a future built-in server.closeIdleConnections() method, but as of March 2026 you still need to implement it manually.

Tracking Active Requests with a Counter

For complex APIs, you want to know exactly when the last in-flight request completes:

let activeRequests = 0;
let resolveIdle: (() => void) | null = null;

// Middleware to count in-flight requests
app.use((req, res, next) => {
  activeRequests++;
  res.on('finish', () => {
    activeRequests--;
    if (isShuttingDown && activeRequests === 0 && resolveIdle) {
      resolveIdle();
    }
  });
  next();
});

function waitForIdleRequests(timeoutMs = 20000): Promise<void> {
  if (activeRequests === 0) return Promise.resolve();
  return new Promise((resolve, reject) => {
    resolveIdle = resolve;
    setTimeout(() => reject(new Error('Drain timeout')), timeoutMs);
  });
}

// In gracefulShutdown:
async function gracefulShutdown(signal: string) {
  console.log(`[${signal}] Shutting down. Active requests: ${activeRequests}`);
  isShuttingDown = true;

  server.close();
  destroyIdleConnections();

  try {
    await waitForIdleRequests(20000);
    console.log('All requests drained.');
  } catch {
    console.warn('Drain timeout — forcing close with active requests.');
  }

  await Promise.allSettled([db.end(), redis.quit()]);
  process.exit(0);
}

Promise.allSettled is intentional here — you want to attempt cleanup on all resources even if one fails. Using Promise.all would short-circuit on the first failure, potentially leaving DB connections open.

Kubernetes Integration

Kubernetes manages your pod lifecycle through two mechanisms that interact with graceful shutdown:

terminationGracePeriodSeconds

# deployment.yaml
spec:
  template:
    spec:
      terminationGracePeriodSeconds: 60   # Give 60s total
      containers:
        - name: api
          image: your-api:latest
          readinessProbe:
            httpGet:
              path: /health
              port: 3000
            periodSeconds: 5
            failureThreshold: 1           # Deregister after first 503
          livenessProbe:
            httpGet:
              path: /health
              port: 3000
            initialDelaySeconds: 10
            periodSeconds: 10

preStop Hook

There's a race condition between SIGTERM arrival and the load balancer finishing deregistration. Even after the pod is marked "Terminating", in-flight requests from already-established connections continue arriving for a few seconds.

The fix: add a preStop hook that sleeps before SIGTERM fires:

lifecycle:
  preStop:
    exec:
      command: ["sleep", "5"]

This adds a 5-second delay between the pod entering "Terminating" state and SIGTERM being sent. With a terminationGracePeriodSeconds: 60, your timeline becomes:

T+0s — Pod marked Terminating, preStop hook runs
T+5s — SIGTERM sent, app starts shutdown sequence
T+5-25s — Active requests drain, DB/Redis close
T+30s — Clean process.exit(0)
T+60s — Kubernetes SIGKILL deadline (never reached)

Full Kubernetes Deployment

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api
spec:
  replicas: 3
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1
      maxUnavailable: 0         # Zero-downtime: never remove before adding
  template:
    spec:
      terminationGracePeriodSeconds: 60
      containers:
        - name: api
          image: your-api:latest
          ports:
            - containerPort: 3000
          readinessProbe:
            httpGet:
              path: /health
              port: 3000
            periodSeconds: 5
            failureThreshold: 1
          livenessProbe:
            httpGet:
              path: /health
              port: 3000
            initialDelaySeconds: 10
            periodSeconds: 10
          lifecycle:
            preStop:
              exec:
                command: ["sleep", "5"]

With maxUnavailable: 0, Kubernetes won't terminate the old pod until the new one passes its readiness probe — ensuring continuous availability.

Database and Redis Cleanup

Different clients need different teardown strategies:

import pg from 'pg';
import { createClient } from 'redis';
import { Sequelize } from 'sequelize';

const pgPool = new pg.Pool({ max: 20 });
const redisClient = createClient();
const sequelize = new Sequelize(/* ... */);

async function closeAllConnections() {
  const results = await Promise.allSettled([
    // PostgreSQL pool — waits for active queries to finish, then closes
    pgPool.end().then(() => console.log('PG pool closed')),

    // Redis — QUIT sends a clean close command
    redisClient.quit().then(() => console.log('Redis closed')),

    // Sequelize — closes all pool connections
    sequelize.close().then(() => console.log('Sequelize pool closed')),
  ]);

  for (const result of results) {
    if (result.status === 'rejected') {
      console.error('Connection close error:', result.reason);
    }
  }
}

Important: pgPool.end() waits for all pending queries to complete before closing connections. This is exactly what you want — it won't interrupt a query that's already executing.

Handling Uncaught Errors During Shutdown

Don't let error handlers interfere with your shutdown sequence:

let isShuttingDown = false;

process.on('uncaughtException', (err) => {
  console.error('Uncaught exception:', err);
  if (!isShuttingDown) {
    gracefulShutdown('uncaughtException');
  }
});

process.on('unhandledRejection', (reason) => {
  console.error('Unhandled rejection:', reason);
  if (!isShuttingDown) {
    gracefulShutdown('unhandledRejection');
  }
});

process.on('SIGTERM', () => {
  if (!isShuttingDown) gracefulShutdown('SIGTERM');
});

process.on('SIGINT', () => {
  if (!isShuttingDown) gracefulShutdown('SIGINT');
});

The isShuttingDown guard prevents double-invocation — e.g., if SIGTERM triggers shutdown and then an error fires during cleanup.

BullMQ Worker Shutdown

Background job workers need special handling — don't stop consuming the queue mid-job:

import { Worker } from 'bullmq';
import { redisConnection } from './redis';

const worker = new Worker('emails', processEmailJob, {
  connection: redisConnection,
  concurrency: 5,
});

async function shutdownWorker() {
  console.log('Closing BullMQ worker...');
  // close() waits for all active jobs to finish before stopping
  await worker.close();
  console.log('Worker closed cleanly.');
}

process.on('SIGTERM', async () => {
  isShuttingDown = true;
  await Promise.all([
    shutdownServer(),   // HTTP server
    shutdownWorker(),   // BullMQ worker
  ]);
  await closeAllConnections();
  process.exit(0);
});

worker.close() in BullMQ 5 (released late 2025) waits for in-progress jobs to complete, then stops polling. It respects the terminationGracePeriodSeconds window automatically.

Testing Your Shutdown

Don't trust your shutdown code until you've tested it under load:

// test/graceful-shutdown.test.ts
import { spawn } from 'child_process';
import fetch from 'node-fetch';

describe('graceful shutdown', () => {
  it('completes in-flight requests on SIGTERM', async () => {
    const server = spawn('node', ['dist/server.js']);

    await new Promise(r => setTimeout(r, 500)); // wait for startup

    // Start a slow request (will take 2s to complete)
    const slowRequest = fetch('http://localhost:3000/api/slow');

    // Immediately send SIGTERM
    server.kill('SIGTERM');

    // The slow request should still succeed
    const response = await slowRequest;
    expect(response.status).toBe(200);

    // Server should have exited cleanly
    const exitCode = await new Promise(r => server.on('close', r));
    expect(exitCode).toBe(0);
  });

  it('returns 503 on /health during shutdown', async () => {
    const server = spawn('node', ['dist/server.js']);
    await new Promise(r => setTimeout(r, 500));

    server.kill('SIGTERM');
    await new Promise(r => setTimeout(r, 100)); // give it a moment

    const health = await fetch('http://localhost:3000/health');
    expect(health.status).toBe(503);
  });
});

Complete Production-Ready Implementation

Putting it all together — a production graceful shutdown module you can drop into any Node.js API:

// lib/shutdown.ts
import { Server } from 'http';
import { Socket } from 'net';

interface ShutdownOptions {
  server: Server;
  drainTimeoutMs?: number;
  cleanupFns?: Array<() => Promise<void>>;
  logger?: typeof console;
}

export function setupGracefulShutdown({
  server,
  drainTimeoutMs = 20000,
  cleanupFns = [],
  logger = console,
}: ShutdownOptions) {
  let isShuttingDown = false;
  let activeRequests = 0;
  let resolveIdle: (() => void) | null = null;
  const sockets = new Set<Socket>();

  server.on('connection', (socket: Socket) => {
    sockets.add(socket);
    socket.on('close', () => sockets.delete(socket));
  });

  // Middleware — attach to app BEFORE routes
  const requestTracker = (req: any, res: any, next: any) => {
    if (isShuttingDown) {
      res.set('Connection', 'close');
      return res.status(503).json({ error: 'Server is shutting down' });
    }
    activeRequests++;
    res.on('finish', () => {
      activeRequests--;
      if (activeRequests === 0 && resolveIdle) resolveIdle();
    });
    next();
  };

  const healthStatus = () => (isShuttingDown ? 'shutting_down' : 'healthy');

  async function shutdown(signal: string) {
    if (isShuttingDown) return;
    isShuttingDown = true;

    logger.info(`[${signal}] Graceful shutdown started. Active: ${activeRequests}`);

    server.close();

    // Destroy idle keep-alive connections
    for (const socket of sockets) {
      // @ts-ignore
      if (!socket._httpMessage || socket._httpMessage.finished) {
        socket.destroy();
      }
    }

    // Wait for in-flight requests
    if (activeRequests > 0) {
      await new Promise<void>((resolve, reject) => {
        resolveIdle = resolve;
        setTimeout(() => reject(new Error('Drain timeout')), drainTimeoutMs);
      }).catch((err) => logger.warn(err.message));
    }

    // Run cleanup functions in parallel
    await Promise.allSettled(cleanupFns.map((fn) => fn()));

    logger.info('Shutdown complete.');
    process.exit(0);
  }

  process.on('SIGTERM', () => shutdown('SIGTERM'));
  process.on('SIGINT', () => shutdown('SIGINT'));
  process.on('uncaughtException', (err) => {
    logger.error('Uncaught exception:', err);
    shutdown('uncaughtException');
  });
  process.on('unhandledRejection', (reason) => {
    logger.error('Unhandled rejection:', reason);
    shutdown('unhandledRejection');
  });

  return { requestTracker, healthStatus };
}

Usage in your server file:

// server.ts
import express from 'express';
import http from 'http';
import { setupGracefulShutdown } from './lib/shutdown';
import { pgPool, redisClient } from './db';

const app = express();
const server = http.createServer(app);

const { requestTracker, healthStatus } = setupGracefulShutdown({
  server,
  drainTimeoutMs: 20000,
  cleanupFns: [
    () => pgPool.end(),
    () => redisClient.quit(),
  ],
});

// Health check — must be BEFORE requestTracker middleware
app.get('/health', (req, res) => {
  const status = healthStatus();
  res.status(status === 'healthy' ? 200 : 503).json({ status });
});

// Request tracking middleware
app.use(requestTracker);

// Your API routes
app.use('/api', apiRouter);

server.listen(3000, () => console.log('API listening on :3000'));

Quick Reference: Shutdown Checklist

Step	Why It Matters
Handle SIGTERM + SIGINT	Catches both Kubernetes and Ctrl+C signals
Return 503 from /health	Triggers load balancer deregistration
Track active request count	Know when it's safe to close connections
Destroy idle keep-alive sockets	Prevent `server.close()` from hanging
Set 25s force-exit timeout	Never exceed Kubernetes terminationGracePeriod
Use `Promise.allSettled` for cleanup	Close all resources even if one fails
Add Kubernetes preStop sleep	Eliminate race condition on traffic draining
Test with concurrent load	Verify no requests dropped under real shutdown

Summary

Graceful shutdown isn't glamorous, but it's the difference between zero-downtime deployments and a flood of 502 errors in your observability dashboard.

The pattern is straightforward: flip a shutdown flag, return 503 from health checks, drain active requests, close resource connections, then exit. The Kubernetes preStop hook and correct terminationGracePeriodSeconds tuning give you the time budget to do it right.

If you're building production APIs and want to monetize them on RapidAPI via 1xAPI, graceful shutdown is one of the non-negotiables for maintaining the uptime SLAs that paying API consumers expect.

How to Implement Graceful Shutdown in Node.js APIs for Zero-Downtime Deployments (2026 Guide)

1xApi — Sun, 29 Mar 2026 01:02:47 +0000

Zero-downtime deployments are non-negotiable for production APIs. Yet one of the most common causes of dropped requests and 502 errors during deployments is something deceptively simple: your Node.js process doesn't know how to die gracefully.

When Kubernetes sends a SIGTERM to your pod, or Docker stops a container, your API has a window to finish in-flight requests, close database connections, flush queues, and exit cleanly. Without a proper shutdown handler, requests get silently dropped, transactions left open, and Redis connections leak — all while your users experience mysterious errors during what should be a seamless deploy.

This guide walks through building a production-grade graceful shutdown system for Node.js APIs in 2026, covering Express, Fastify, Hono, and Kubernetes-specific patterns.

Why Graceful Shutdown Matters in 2026

Modern deployment pipelines run rolling updates continuously. A typical Kubernetes rolling update sends SIGTERM to the old pod while simultaneously routing new traffic to the new pod. The gap between these two events — the termination grace period — is your window to clean up.

Scenario	Without Graceful Shutdown	With Graceful Shutdown
Rolling deploy	Requests dropped, 502 errors	Zero dropped requests
Scale-down event	Connections terminated	Connections drained
Pod eviction	Open transactions, data risk	Clean commit or rollback
Health check transition	Traffic sent to dying pod	Removed from load balancer first

In Kubernetes, the default terminationGracePeriodSeconds is 30 seconds. That's your budget. Use it wisely.

Understanding the Shutdown Signal Chain

Before writing code, understand what actually happens when your pod terminates:

Kubernetes sends SIGTERM to PID 1 in your container
Kubernetes simultaneously removes your pod from the Endpoints list (this can take 2–10 seconds to propagate through kube-proxy/iptables)
After terminationGracePeriodSeconds, Kubernetes sends SIGKILL (no escape)

The critical gap is step 2. Traffic may still arrive at your pod for several seconds after it receives SIGTERM. This is why a naive process.exit(0) on SIGTERM still drops requests.

The solution: add a pre-stop sleep and stop accepting new connections gradually.

Step 1: Basic Shutdown Handler

Let's start with the fundamentals — a minimal but correct shutdown handler for any Node.js HTTP server:

// server.js
import express from 'express';

const app = express();
let isShuttingDown = false;

// Middleware: reject new requests during shutdown
app.use((req, res, next) => {
  if (isShuttingDown) {
    res.set('Connection', 'close');
    return res.status(503).json({ error: 'Server is shutting down' });
  }
  next();
});

app.get('/health', (req, res) => {
  if (isShuttingDown) return res.status(503).json({ status: 'shutting_down' });
  res.json({ status: 'ok' });
});

app.get('/api/data', async (req, res) => {
  // Simulate async work
  await new Promise(resolve => setTimeout(resolve, 200));
  res.json({ data: 'response' });
});

const server = app.listen(3000, () => {
  console.log('Server listening on port 3000');
});

// Track active connections for forced drain
const connections = new Set();
server.on('connection', socket => {
  connections.add(socket);
  socket.on('close', () => connections.delete(socket));
});

async function shutdown(signal) {
  console.log(`[Shutdown] Received ${signal}`);
  isShuttingDown = true;

  // Stop accepting new connections
  server.close(err => {
    if (err) {
      console.error('[Shutdown] Error:', err);
      process.exit(1);
    }
    console.log('[Shutdown] All connections closed. Exiting.');
    process.exit(0);
  });

  // Force-close idle connections after 30s
  setTimeout(() => {
    console.warn('[Shutdown] Timeout hit, destroying remaining connections');
    for (const socket of connections) socket.destroy();
    process.exit(1);
  }, 30_000);
}

process.on('SIGTERM', () => shutdown('SIGTERM'));
process.on('SIGINT',  () => shutdown('SIGINT'));

This handles the basics: the isShuttingDown flag prevents new work from entering, and server.close() waits for in-flight requests before exiting. The 30-second hard exit is your safety net.

Step 2: The Pre-Stop Sleep (Kubernetes Critical Pattern)

Because Kubernetes propagates endpoint removal asynchronously, you need to delay the actual shutdown start by a few seconds after receiving SIGTERM. This prevents 502s from traffic that's still being routed to the terminating pod.

There are two ways to implement this:

Option A: Kubernetes `preStop` hook (recommended)

# deployment.yaml
spec:
  terminationGracePeriodSeconds: 60
  containers:
  - name: api
    lifecycle:
      preStop:
        exec:
          command: ["/bin/sh", "-c", "sleep 10"]

The preStop hook runs before SIGTERM is sent. Setting it to sleep 10 gives kube-proxy 10 seconds to drain existing connections before your app even starts shutting down. Your terminationGracePeriodSeconds must be greater than preStop duration + your app's shutdown time.

Option B: Sleep inside the shutdown handler

async function shutdown(signal) {
  console.log(`[Shutdown] Received ${signal}`);
  isShuttingDown = true;

  // Give load balancer time to route traffic away (5–15 seconds)
  const DRAIN_DELAY = parseInt(process.env.SHUTDOWN_DRAIN_DELAY ?? '10', 10) * 1000;
  console.log(`[Shutdown] Waiting ${DRAIN_DELAY}ms for traffic drain...`);
  await new Promise(resolve => setTimeout(resolve, DRAIN_DELAY));

  // Now stop accepting connections
  server.close(() => {
    console.log('[Shutdown] Server closed. Exiting.');
    process.exit(0);
  });

  setTimeout(() => process.exit(1), 30_000);
}

Option A is preferred in Kubernetes because it keeps your app logic clean and the delay configurable per-environment without code changes.

Step 3: Production-Grade Shutdown Manager

Real APIs have more than just HTTP connections to clean up: PostgreSQL pools, Redis connections, open file handles, message queue consumers. Here's a ShutdownManager class that handles all of them:

// shutdown.js
export class ShutdownManager {
  #isShuttingDown = false;
  #cleanupHandlers = [];
  #timeout;

  constructor({ timeoutMs = 30_000 } = {}) {
    this.#timeout = timeoutMs;
  }

  /** Register a named cleanup handler */
  register(name, fn) {
    this.#cleanupHandlers.push({ name, fn });
    return this; // chainable
  }

  /** Call from your server setup */
  listen(server) {
    const connections = new Set();
    server.on('connection', s => {
      connections.add(s);
      s.on('close', () => connections.delete(s));
    });

    const handler = async signal => {
      if (this.#isShuttingDown) return;
      this.#isShuttingDown = true;
      console.log(`\n[Shutdown] Signal: ${signal}`);

      // Hard timeout as last resort
      const forceExit = setTimeout(() => {
        console.error('[Shutdown] Timeout exceeded — forcing exit');
        process.exit(1);
      }, this.#timeout);
      forceExit.unref(); // Don't prevent clean exit

      // 1. Stop HTTP server
      await new Promise(resolve => server.close(resolve));
      console.log('[Shutdown] HTTP server closed');

      // 2. Run cleanup handlers in order
      for (const { name, fn } of this.#cleanupHandlers) {
        try {
          await fn();
          console.log(`[Shutdown] ✓ ${name}`);
        } catch (err) {
          console.error(`[Shutdown] ✗ ${name}:`, err.message);
        }
      }

      // 3. Force-close any remaining sockets
      for (const s of connections) s.destroy();

      clearTimeout(forceExit);
      console.log('[Shutdown] Complete. Goodbye.');
      process.exit(0);
    };

    process.on('SIGTERM', handler);
    process.on('SIGINT',  handler);
  }

  get isShuttingDown() { return this.#isShuttingDown; }
}

Usage with real resources:

// app.js
import { Pool } from 'pg';
import { Redis } from 'ioredis';
import { ShutdownManager } from './shutdown.js';

const pool  = new Pool({ connectionString: process.env.DATABASE_URL });
const redis = new Redis(process.env.REDIS_URL);

const shutdown = new ShutdownManager({ timeoutMs: 30_000 });

shutdown
  .register('PostgreSQL pool', () => pool.end())
  .register('Redis client',    () => redis.quit())
  .register('Flush metrics',   () => metrics.flush()); // optional

const server = app.listen(3000);
shutdown.listen(server);

Each cleanup handler runs sequentially, with individual error isolation — a failed Redis close won't prevent the PostgreSQL pool from shutting down.

Step 4: Health Check Integration

Your Kubernetes readiness probe needs to know when to stop sending traffic before SIGTERM arrives. Update your health endpoint:

app.get('/health/ready', (req, res) => {
  if (shutdown.isShuttingDown) {
    // Return 503 → Kubernetes removes pod from endpoints immediately
    return res.status(503).json({
      status: 'shutting_down',
      message: 'Pod is draining'
    });
  }
  res.json({ status: 'ready' });
});

app.get('/health/live', (req, res) => {
  // Liveness probe stays 200 until we're fully done
  // (returning 500 triggers a pod restart, not a clean shutdown)
  res.json({ status: 'alive' });
});

Corresponding Kubernetes probes:

readinessProbe:
  httpGet:
    path: /health/ready
    port: 3000
  initialDelaySeconds: 5
  periodSeconds: 5
  failureThreshold: 1   # Remove from rotation immediately on first failure

livenessProbe:
  httpGet:
    path: /health/live
    port: 3000
  initialDelaySeconds: 10
  periodSeconds: 10
  failureThreshold: 3

With failureThreshold: 1 on the readiness probe, as soon as your pod returns 503 on /health/ready, Kubernetes removes it from the load balancer — eliminating the race condition entirely.

Step 5: Fastify and Hono Patterns

The same principles apply to modern frameworks, with minor differences.

Fastify (with built-in `fastify.close()`)

import Fastify from 'fastify';

const fastify = Fastify({ logger: true });
let isShuttingDown = false;

fastify.addHook('onRequest', async (request, reply) => {
  if (isShuttingDown) {
    reply.header('Connection', 'close');
    reply.status(503).send({ error: 'shutting down' });
  }
});

const shutdown = async signal => {
  fastify.log.info({ signal }, 'Shutdown initiated');
  isShuttingDown = true;

  await fastify.close(); // waits for in-flight requests + runs onClose hooks
  process.exit(0);
};

process.on('SIGTERM', shutdown);
process.on('SIGINT',  shutdown);

Fastify's fastify.close() handles the connection draining internally and fires any registered fastify.addHook('onClose', ...) handlers — making cleanup registration more ergonomic.

Hono on Node.js

import { serve } from '@hono/node-server';
import { Hono } from 'hono';

const app = new Hono();
let isShuttingDown = false;

app.use('*', async (c, next) => {
  if (isShuttingDown) {
    return c.json({ error: 'shutting down' }, 503);
  }
  return next();
});

const server = serve({ fetch: app.fetch, port: 3000 });

process.on('SIGTERM', async () => {
  isShuttingDown = true;
  server.close(() => process.exit(0));
  setTimeout(() => process.exit(1), 30_000);
});

Step 6: Handling BullMQ Workers

If your API runs BullMQ background workers, graceful shutdown is critical — abruptly stopping a worker leaves jobs in the active state and they won't be retried until the lock expires (default: 30 seconds).

import { Worker } from 'bullmq';

const worker = new Worker('emails', processJob, {
  connection: redis,
  lockDuration: 30_000,
});

shutdown.register('BullMQ worker', async () => {
  await worker.close();           // waits for current job to finish
  console.log('Worker drained');
});

worker.close() calls worker.pause() internally, waits for the active job to complete, then closes the connection. Pair it with a lockRenewer for jobs that take longer than lockDuration.

Complete Deployment Checklist

Here's the full picture for zero-downtime Kubernetes deployments in 2026:

# deployment.yaml (production template)
apiVersion: apps/v1
kind: Deployment
metadata:
  name: api
spec:
  replicas: 3
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxSurge: 1
      maxUnavailable: 0       # Never reduce capacity during rollout
  template:
    spec:
      terminationGracePeriodSeconds: 60
      containers:
      - name: api
        image: my-api:latest
        ports:
        - containerPort: 3000
        env:
        - name: SHUTDOWN_DRAIN_DELAY
          value: "10"
        lifecycle:
          preStop:
            exec:
              command: ["/bin/sh", "-c", "sleep 10"]
        readinessProbe:
          httpGet:
            path: /health/ready
            port: 3000
          periodSeconds: 5
          failureThreshold: 1
        livenessProbe:
          httpGet:
            path: /health/live
            port: 3000
          periodSeconds: 10
          failureThreshold: 3

Checklist:

[ ] process.on('SIGTERM') handler registered
[ ] process.on('SIGINT') handler registered
[ ] isShuttingDown flag rejects new requests with 503
[ ] /health/ready returns 503 when shutting down
[ ] Database pool properly closed on shutdown
[ ] Redis/cache client properly closed on shutdown
[ ] BullMQ workers drained before exit
[ ] Hard timeout (process.exit(1)) as last resort
[ ] preStop hook adds drain delay in Kubernetes
[ ] terminationGracePeriodSeconds > preStop + shutdown time

Testing Your Shutdown Handler

Don't assume it works — test it:

# Start your server
node server.js &
SERVER_PID=$!

# Send some requests in a loop
for i in $(seq 1 20); do
  curl -s http://localhost:3000/api/data &
done

# Send SIGTERM mid-flight
sleep 0.1 && kill -TERM $SERVER_PID

# Wait and check — no 502s, no lost responses
wait
echo "All requests completed cleanly"

For load testing under shutdown, use k6:

// k6-shutdown-test.js
import http from 'k6/http';
import { check } from 'k6';

export const options = {
  vus: 50,
  duration: '30s',
};

export default function () {
  const res = http.get('http://localhost:3000/api/data');
  check(res, {
    'status is 200 or 503': r => r.status === 200 || r.status === 503,
    'never 502': r => r.status !== 502,
  });
}

A 503 during shutdown is acceptable (it's intentional). A 502 means a connection was dropped — that's a bug.

Summary

Graceful shutdown is one of those things that seems optional until production punishes you for ignoring it. In a world of continuous deployment, Kubernetes rolling updates, and auto-scaling, every restart is a potential incident without it.

The pattern in 2026 is clear:

Handle SIGTERM and SIGINT
Set an isShuttingDown flag immediately and return 503 on readiness
Stop accepting new connections with server.close()
Run cleanup handlers (DB, Redis, queues) sequentially
Force exit after 30 seconds as a last resort
Add a preStop sleep in Kubernetes to absorb the endpoint propagation delay

With these patterns in place, your API endpoints can deploy dozens of times a day without a single dropped request.

Originally published at 1xAPI.com

How to Monetize Your API on RapidAPI: Pricing Strategy, Usage Tracking & Passive Income in 2026

1xApi — Sat, 28 Mar 2026 01:03:02 +0000

You built an API. It works. It solves a real problem. Now what?

For most developers, shipping the API is only half the job. The other half — turning it into recurring revenue — is where most people stall. In 2026, with the RapidAPI Hub hosting over 40,000 APIs and serving 4 million+ developers, there has never been a better time to list, price, and monetize your API on a marketplace.

This guide covers everything from picking the right pricing model to tracking usage in your own backend — so you can generate passive income from the APIs you are already building.

Why RapidAPI in 2026?

RapidAPI (now Rapid's API Hub) remains the dominant API marketplace by traffic and developer adoption. Key reasons to list there in 2026:

Built-in billing infrastructure — Rapid handles Stripe, invoicing, and plan management for you.
Discovery without paid ads — Millions of developers browse by category, so organic traffic compounds.
Analytics dashboard — Subscription counts, revenue, and per-consumer usage are all visible in Rapid Studio.
Freemium funnel — The free tier converts browsers into paying subscribers at rates comparable to SaaS products.

If you're already building APIs (Node.js, Python, Go — it doesn't matter), listing on RapidAPI is the fastest path from "working API" to "paying customers" without building your own billing system.

Step 1: Choose Your Pricing Model

RapidAPI supports four plan types. Here's how to think about each:

Free (Rate-Limited)

The free tier is your marketing funnel. It should offer real value — enough that a developer can test your core use case end-to-end — but with clear limits that motivate upgrades.

RapidAPI limits on free plans (2026):

Max 1,000 requests/hour
Max 500,000 requests/month
No credit card required for the consumer

Free plans cannot charge money, but they generate the data and social proof (usage counts) that drive paid conversions.

Best practice: Design your free tier around a single "aha moment" — the minimum interaction that proves your API's value. For a sports data API, that might be a live score query. For a translation API, it might be 1,000 characters translated.

Freemium (Free + Paid Tiers)

The most effective monetization structure on RapidAPI is freemium — combining a free tier with 2–3 paid tiers above it.

RapidAPI's own data and provider success stories consistently point to four tiers as the sweet spot:

Plan	Price	Monthly Requests	Overage (per call)
BASIC	Free	500 req/day	—
PRO	$25/mo	10,000 req/mo	$0.005
ULTRA	$75/mo	50,000 req/mo	$0.003
MEGA	$150/mo	200,000 req/mo	$0.002

Adjust these based on your cost per request, but the price-to-limit ratio above aligns with what converts well across most API categories.

⚠️ RapidAPI minimum pricing rule (2026): If your plan allows over 500,000 requests/month, the minimum price is $0.00003 per request above 500K. For a 2M request/month plan, at least $45/month is required.

Pay-Per-Use

No subscription, just a per-call charge. Good for low-volume but high-value calls (e.g., financial data lookups, SMS send, image processing). Requires a credit card but no recurring commitment, which reduces friction for sporadic users.

Pure Paid (No Free Tier)

Only justified for premium or regulated data (real-time financial feeds, legal databases, etc.) where even test access has cost. Use sparingly — the absence of a free tier dramatically reduces your top-of-funnel conversion.

Step 2: Structure Your Listing for Conversion

A technically excellent API with a poor listing will underperform a mediocre API with a great one. Treat your RapidAPI listing like a product landing page:

Write Endpoint Descriptions That Sell

Every endpoint should answer three questions in its description:

What does it return? (specific, not vague)
When would I use it? (use case)
What's the response shape? (example output)

Bad: Returns user data
Good: Returns a user profile including name, email, subscription tier, and last login timestamp. Use this to populate dashboard headers or account pages.

Add Working Code Examples

RapidAPI auto-generates snippets in Node.js, Python, PHP, etc. Make sure your endpoint parameters have valid example values so the generated code actually runs.

Use a Custom Logo and Cover Image

APIs with custom branding get significantly higher click-through rates in category browse. A clean logo (200×200px) and a banner (1500×500px) are worth 30 minutes of design work.

Step 3: Implement Usage Tracking in Your Backend

RapidAPI injects three headers into every proxied request to your server:

X-RapidAPI-User: the-subscribers-username
X-RapidAPI-Subscription: BASIC / PRO / ULTRA / MEGA
X-RapidAPI-Proxy-Secret: your-verification-secret

Use these to:

Verify requests came through RapidAPI (not direct hits)
Track per-user usage in your own analytics
Enforce plan-specific logic (e.g., PRO gets real-time data, BASIC gets cached)

Here's a production-ready Express middleware that handles all three:

import express, { Request, Response, NextFunction } from 'express';
import Redis from 'ioredis';

const redis = new Redis(process.env.REDIS_URL!);
const PROXY_SECRET = process.env.RAPIDAPI_PROXY_SECRET!;

interface PlanLimits {
  requestsPerDay: number;
  cacheMaxAge: number;  // seconds
  realtimeData: boolean;
}

const PLAN_CONFIG: Record<string, PlanLimits> = {
  BASIC:  { requestsPerDay: 500,    cacheMaxAge: 300,  realtimeData: false },
  PRO:    { requestsPerDay: 10000,  cacheMaxAge: 60,   realtimeData: true  },
  ULTRA:  { requestsPerDay: 50000,  cacheMaxAge: 10,   realtimeData: true  },
  MEGA:   { requestsPerDay: 200000, cacheMaxAge: 0,    realtimeData: true  },
};

async function rapidApiMiddleware(req: Request, res: Response, next: NextFunction) {
  // 1. Verify the request came through RapidAPI
  const proxySecret = req.headers['x-rapidapi-proxy-secret'];
  if (proxySecret !== PROXY_SECRET) {
    return res.status(403).json({ error: 'Direct access not permitted. Use RapidAPI.' });
  }

  const user = req.headers['x-rapidapi-user'] as string;
  const subscription = (req.headers['x-rapidapi-subscription'] as string) ?? 'BASIC';
  const plan = PLAN_CONFIG[subscription] ?? PLAN_CONFIG.BASIC;

  // 2. Per-user daily quota check (atomic via Redis)
  const today = new Date().toISOString().slice(0, 10); // YYYY-MM-DD
  const quotaKey = `quota:${user}:${today}`;

  const current = await redis.incr(quotaKey);
  if (current === 1) {
    // Set TTL on first increment — expires at end of day
    await redis.expireat(quotaKey, Math.floor(Date.now() / 1000) + 86400);
  }

  if (current > plan.requestsPerDay) {
    return res.status(429).json({
      error: 'Daily quota exceeded',
      plan: subscription,
      limit: plan.requestsPerDay,
      resets: 'midnight UTC',
    });
  }

  // 3. Attach plan config to request for downstream use
  res.locals.plan = plan;
  res.locals.user = user;
  res.locals.subscription = subscription;

  // 4. Track usage asynchronously (non-blocking)
  redis.hincrby(`usage:${user}`, today, 1).catch(() => {}); // fire-and-forget

  next();
}

Plan-Specific Response Logic

Once the middleware is in place, your route handlers can adapt their behavior based on the plan:

app.get('/api/scores/live', rapidApiMiddleware, async (req, res) => {
  const { plan } = res.locals;

  if (!plan.realtimeData) {
    // BASIC: return cached data from 5 minutes ago
    const cached = await redis.get('scores:cached');
    if (cached) {
      res.setHeader('X-Data-Age', '300');
      return res.json(JSON.parse(cached));
    }
  }

  // PRO+: fetch live data
  const liveScores = await fetchLiveScores();

  // Cache for BASIC subscribers
  await redis.setex('scores:cached', 300, JSON.stringify(liveScores));

  res.json(liveScores);
});

This pattern lets a single codebase serve all four plan tiers efficiently, with Redis absorbing the quota accounting overhead at ~0.3ms per check.

Step 4: Monitor Revenue and Usage

RapidAPI Studio gives you:

Earnings Dashboard — Monthly revenue, pending payouts, per-plan breakdown
Community Tab — Each subscriber's usage over the last 60 days
Analytics — Latency percentiles, error rates, top endpoints

Beyond Studio, maintain your own usage tracking (as shown above) to answer questions RapidAPI doesn't surface:

Which endpoints are most used per tier?
What's the actual cost per request (your infrastructure bill ÷ total calls)?
Which free-tier users are hitting 80%+ of their quota? (These are your best upgrade candidates.)

Identifying Upgrade Targets

// Find free-tier users approaching their quota
async function getUpgradeCandidates(): Promise<string[]> {
  const today = new Date().toISOString().slice(0, 10);
  const basicLimit = PLAN_CONFIG.BASIC.requestsPerDay; // 500

  const keys = await redis.keys(`quota:*:${today}`);
  const candidates: string[] = [];

  for (const key of keys) {
    const usage = parseInt(await redis.get(key) || '0');
    const username = key.split(':')[1];

    // Users at 80%+ of BASIC quota are prime upgrade candidates
    if (usage >= basicLimit * 0.8) {
      candidates.push(username);
    }
  }

  return candidates;
}

Step 5: Design for Stickiness

Developers stay subscribed to APIs that are:

Reliable — 99.9%+ uptime, consistent latency
Well-documented — Changelogs, migration guides, deprecation notices with 90-day windows
Versioned properly — Never break existing integrations; use /v1/, /v2/ paths
Responsive to issues — Reply to dev.to comments promptly

Add a Changelog Endpoint

app.get('/changelog', (req, res) => {
  res.json([
    { version: '2.3.0', date: '2026-03-01', changes: ['Added /scores/live endpoint', 'Improved latency by 40%'] },
    { version: '2.2.0', date: '2026-01-15', changes: ['Added team stats endpoint', 'Fixed timezone handling'] },
    { version: '2.0.0', date: '2025-11-01', changes: ['Breaking: renamed /match to /game', 'Added pagination support'] },
  ]);
});

Real Revenue Benchmarks (2026)

Niche data APIs (sports, real estate, financial) with 50–100 paying subscribers earn $2,000–$8,000/month
Utility APIs (text processing, format conversion) typically earn $500–$2,000/month
AI-augmented APIs (wrappers adding ML/enrichment) are the fastest-growing category in 2026, often earning $5,000+/month with 30–50 PRO subscribers

Pre-Launch Checklist

[ ] Free tier offers a genuine "aha moment" without giving away the store
[ ] 2–3 paid tiers with clear value jumps between each
[ ] X-RapidAPI-Proxy-Secret verified in middleware
[ ] Per-user quota tracking in Redis with atomic INCR
[ ] Plan-differentiated responses implemented
[ ] Endpoint descriptions include use case + example output
[ ] Custom logo and banner uploaded
[ ] Changelog endpoint live

Wrapping Up

API monetization in 2026 is less about building the perfect product and more about systematically removing friction — from discovery to the first request to upgrade. RapidAPI handles the marketplace and billing rails; your job is to show up with a reliable API, a smart pricing structure, and usage tracking that tells you where your revenue is coming from.

Start with a free tier, ship your listing, and iterate on pricing from real data.

Building APIs and want to see what production-grade endpoints look like? Check out 1xAPI on RapidAPI for real examples of well-structured API products.

How to Eliminate Request Context Prop Drilling in Node.js APIs with AsyncLocalStorage (2026 Guide)

1xApi — Fri, 27 Mar 2026 01:03:31 +0000

You've probably written this before:

async function getUser(userId: string, requestId: string, logger: Logger) {
  logger.info('Fetching user', { requestId, userId });
  const user = await db.query('SELECT * FROM users WHERE id = $1', [userId]);
  return processUser(user, requestId, logger); // pass it down... again
}

async function processUser(user: User, requestId: string, logger: Logger) {
  logger.info('Processing user', { requestId }); // still passing it
  return enrichUser(user, requestId, logger); // and again
}

This is context prop drilling — the Node.js equivalent of React's most notorious anti-pattern. Every function in your call stack needs requestId, userId, or traceId, so you thread it through every argument list. It bloats function signatures, leaks implementation details, and makes refactoring painful.

In 2026, there's a better way: AsyncLocalStorage, Node.js's built-in solution for propagating request-scoped context without prop drilling. It's been stable since Node.js 16, battle-tested in production at scale, and is the same mechanism used internally by OpenTelemetry's Node.js SDK.

This guide shows you how to use it to build clean, traceable, production-grade APIs.

What is AsyncLocalStorage?

AsyncLocalStorage is part of Node.js's async_hooks module. It creates a store that's automatically propagated through the entire async call chain — promises, callbacks, setTimeout, everything — without you passing it explicitly.

Think of it like a thread-local variable in Java or Python, but for Node.js's async model.

import { AsyncLocalStorage } from 'node:async_hooks';

const storage = new AsyncLocalStorage<{ requestId: string }>();

storage.run({ requestId: 'abc-123' }, () => {
  // Everything called from here has access to the store
  console.log(storage.getStore()); // { requestId: 'abc-123' }

  setTimeout(() => {
    console.log(storage.getStore()); // Still { requestId: 'abc-123' }
  }, 1000);
});

The store is per-request — concurrent requests each get their own isolated store, so there's no cross-contamination even under heavy load.

Setting Up Request Context in Express

Here's a production pattern for attaching context to every incoming request:

// src/context/request-context.ts
import { AsyncLocalStorage } from 'node:async_hooks';
import { randomUUID } from 'node:crypto';

export interface RequestContext {
  requestId: string;
  userId?: string;
  tenantId?: string;
  startTime: number;
  method: string;
  path: string;
}

// Single global store — safe because each run() is isolated
const store = new AsyncLocalStorage<RequestContext>();

export const RequestContext = {
  /** Get the current request context (throws if called outside a request) */
  get(): RequestContext {
    const ctx = store.getStore();
    if (!ctx) throw new Error('No request context available');
    return ctx;
  },

  /** Get the current request context (returns null if called outside a request) */
  tryGet(): RequestContext | null {
    return store.getStore() ?? null;
  },

  /** Run a function with the given context */
  run<T>(ctx: RequestContext, fn: () => T): T {
    return store.run(ctx, fn);
  },

  /** Create a new context with a generated request ID */
  create(partial: Partial<RequestContext>): RequestContext {
    return {
      requestId: randomUUID(),
      startTime: Date.now(),
      method: 'UNKNOWN',
      path: 'UNKNOWN',
      ...partial,
    };
  },
};

// src/middleware/context.middleware.ts
import { Request, Response, NextFunction } from 'express';
import { RequestContext } from '../context/request-context.js';

export function contextMiddleware(req: Request, res: Response, next: NextFunction) {
  const ctx = RequestContext.create({
    // Respect upstream tracing headers (from load balancer, API gateway, etc.)
    requestId: (req.headers['x-request-id'] as string) ?? undefined,
    method: req.method,
    path: req.path,
  });

  // Always echo the request ID back to the client
  res.setHeader('X-Request-Id', ctx.requestId);

  // Run the rest of the request inside the context
  RequestContext.run(ctx, () => next());
}

// src/app.ts
import express from 'express';
import { contextMiddleware } from './middleware/context.middleware.js';

const app = express();
app.use(express.json());
app.use(contextMiddleware); // Must be first!

export { app };

Now every handler, service, and database call within that request has automatic access to the context.

Clean Logging Without Prop Drilling

The killer use case is structured logging. Instead of passing requestId everywhere, your logger reads it from the context automatically:

// src/logger/index.ts
import { RequestContext } from '../context/request-context.js';

type LogLevel = 'debug' | 'info' | 'warn' | 'error';

interface LogEntry {
  timestamp: string;
  level: LogLevel;
  message: string;
  requestId?: string;
  userId?: string;
  [key: string]: unknown;
}

function log(level: LogLevel, message: string, extra?: Record<string, unknown>) {
  const ctx = RequestContext.tryGet();

  const entry: LogEntry = {
    timestamp: new Date().toISOString(),
    level,
    message,
    // Automatically pulls from the current request context
    requestId: ctx?.requestId,
    userId: ctx?.userId,
    ...extra,
  };

  // In production, use pino or winston instead of console.log
  console.log(JSON.stringify(entry));
}

export const logger = {
  debug: (msg: string, extra?: Record<string, unknown>) => log('debug', msg, extra),
  info: (msg: string, extra?: Record<string, unknown>) => log('info', msg, extra),
  warn: (msg: string, extra?: Record<string, unknown>) => log('warn', msg, extra),
  error: (msg: string, extra?: Record<string, unknown>) => log('error', msg, extra),
};

Now your services look like this:

// src/services/user.service.ts
import { logger } from '../logger/index.js';
import { db } from '../db/index.js';

// No requestId parameter needed!
export async function getUserById(userId: string) {
  logger.info('Fetching user', { userId });

  const user = await db.query('SELECT * FROM users WHERE id = $1', [userId]);

  if (!user.rows[0]) {
    logger.warn('User not found', { userId });
    return null;
  }

  logger.info('User fetched successfully', { userId });
  return user.rows[0];
}

export async function processUserOrder(userId: string, orderId: string) {
  logger.info('Processing order', { userId, orderId });
  // No context parameter needed anywhere in this chain
  const user = await getUserById(userId);
  // ...
}

Every log line automatically includes requestId and userId. When a bug hits production, you grep by requestId and see every operation in that request's full call chain.

Enriching Context After Authentication

One common pattern: you don't have userId when the request arrives (it comes from the JWT). Add a middleware that enriches the context after auth:

// src/middleware/auth.middleware.ts
import { Request, Response, NextFunction } from 'express';
import { RequestContext } from '../context/request-context.js';
import { verifyJWT } from '../auth/jwt.js';

export async function authMiddleware(req: Request, res: Response, next: NextFunction) {
  const token = req.headers.authorization?.replace('Bearer ', '');

  if (!token) {
    return res.status(401).json({ error: 'Missing token' });
  }

  try {
    const payload = await verifyJWT(token);
    const ctx = RequestContext.get();

    // Mutate the existing context to add user info
    // This works because ctx is a reference to the stored object
    Object.assign(ctx, {
      userId: payload.sub,
      tenantId: payload.tenantId,
    });

    next();
  } catch {
    res.status(401).json({ error: 'Invalid token' });
  }
}

Now every log line after authMiddleware automatically includes userId and tenantId — zero prop drilling.

Database Query Instrumentation

Instrument your database layer to automatically log slow queries with full context:

// src/db/instrumented.ts
import { Pool } from 'pg';
import { logger } from '../logger/index.js';

const pool = new Pool({ connectionString: process.env.DATABASE_URL });

const SLOW_QUERY_THRESHOLD_MS = 100;

export const db = {
  async query<T = unknown>(sql: string, params?: unknown[]): Promise<{ rows: T[] }> {
    const start = performance.now();

    try {
      const result = await pool.query(sql, params);
      const duration = performance.now() - start;

      if (duration > SLOW_QUERY_THRESHOLD_MS) {
        logger.warn('Slow query detected', {
          sql: sql.slice(0, 200), // truncate for safety
          duration: Math.round(duration),
          rowCount: result.rowCount,
        });
      }

      return result;
    } catch (error) {
      const duration = performance.now() - start;
      logger.error('Query failed', {
        sql: sql.slice(0, 200),
        duration: Math.round(duration),
        error: error instanceof Error ? error.message : String(error),
      });
      throw error;
    }
  },
};

No requestId parameter. It's always available via logger → RequestContext.

Request Duration Tracking

Track request duration and log it automatically on response:

// src/middleware/response-logger.middleware.ts
import { Request, Response, NextFunction } from 'express';
import { RequestContext } from '../context/request-context.js';
import { logger } from '../logger/index.js';

export function responseLoggerMiddleware(req: Request, res: Response, next: NextFunction) {
  res.on('finish', () => {
    const ctx = RequestContext.tryGet();
    if (!ctx) return;

    const duration = Date.now() - ctx.startTime;

    const level = res.statusCode >= 500 ? 'error' 
                : res.statusCode >= 400 ? 'warn' 
                : 'info';

    logger[level]('Request completed', {
      statusCode: res.statusCode,
      duration,
      method: ctx.method,
      path: ctx.path,
    });
  });

  next();
}

Using Context in Error Handlers

Global error handlers automatically have context too:

// src/middleware/error.middleware.ts
import { Request, Response, NextFunction } from 'express';
import { logger } from '../logger/index.js';
import { RequestContext } from '../context/request-context.js';

export function errorMiddleware(
  error: Error,
  req: Request,
  res: Response,
  _next: NextFunction
) {
  logger.error('Unhandled error', {
    error: error.message,
    stack: process.env.NODE_ENV === 'development' ? error.stack : undefined,
  });

  const ctx = RequestContext.tryGet();

  res.status(500).json({
    error: 'Internal server error',
    // Always include requestId so clients can report it in bug tickets
    requestId: ctx?.requestId ?? 'unknown',
  });
}

Putting It All Together

Here's the full middleware chain:

// src/app.ts
import express from 'express';
import { contextMiddleware } from './middleware/context.middleware.js';
import { responseLoggerMiddleware } from './middleware/response-logger.middleware.js';
import { authMiddleware } from './middleware/auth.middleware.js';
import { errorMiddleware } from './middleware/error.middleware.js';
import { userRouter } from './routes/users.js';

const app = express();

app.use(express.json());
app.use(contextMiddleware);        // 1. Attach request context
app.use(responseLoggerMiddleware); // 2. Log every response

// Public routes (no auth)
app.get('/health', (req, res) => res.json({ ok: true }));

// Protected routes
app.use('/api', authMiddleware);   // 3. Enrich context with userId
app.use('/api/users', userRouter);

app.use(errorMiddleware);          // 4. Global error handler

export { app };

A request log output now looks like this — every line correlated by requestId:

{"timestamp":"2026-03-27T01:00:00.000Z","level":"info","message":"Fetching user","requestId":"f47ac10b-58cc-4372-a567-0e02b2c3d479","userId":"usr_abc123"}
{"timestamp":"2026-03-27T01:00:00.012Z","level":"info","message":"User fetched successfully","requestId":"f47ac10b-58cc-4372-a567-0e02b2c3d479","userId":"usr_abc123"}
{"timestamp":"2026-03-27T01:00:00.015Z","level":"info","message":"Request completed","requestId":"f47ac10b-58cc-4372-a567-0e02b2c3d479","userId":"usr_abc123","statusCode":200,"duration":15,"method":"GET","path":"/api/users/usr_abc123"}

Performance Considerations

A common concern: does AsyncLocalStorage add overhead? In Node.js 22+ (the current LTS as of early 2026), the V8 team optimized the async context propagation significantly. Benchmarks show less than 1-2% overhead for typical I/O-bound API workloads — completely negligible.

The AsyncLocalStorage.getStore() call is O(1) and doesn't involve any locking or synchronization. It reads from V8's internal async context slot directly.

For CPU-bound workloads, consider using worker_threads instead — each worker has its own independent AsyncLocalStorage scope.

Integration with OpenTelemetry

If you're using OpenTelemetry in production, the two integrate seamlessly:

import { context, trace } from '@opentelemetry/api';
import { RequestContext } from './context/request-context.js';

export function getTraceContext() {
  const ctx = RequestContext.tryGet();
  const span = trace.getActiveSpan();
  const spanContext = span?.spanContext();

  return {
    requestId: ctx?.requestId,
    traceId: spanContext?.traceId,
    spanId: spanContext?.spanId,
  };
}

OTel's SDK uses AsyncLocalStorage internally too, so the two systems work together without any conflicts.

TypeScript Tip: Typed Context Access

For fully type-safe context access in handlers, use a typed accessor:

// src/types/express.d.ts
// Optional: if you prefer req.context instead of RequestContext.get()
declare global {
  namespace Express {
    interface Request {
      context: import('./context/request-context.js').RequestContext;
    }
  }
}

// In contextMiddleware, after creating the context:
req.context = ctx;
RequestContext.run(ctx, () => next());

This gives you two access patterns — use whichever fits your team's style.

When NOT to Use AsyncLocalStorage

A few cases where you should be careful:

Worker threads: Each worker has its own isolated AsyncLocalStorage. Don't expect context to propagate across worker_threads boundaries — you need to serialize/deserialize it manually.
Event emitters with long lifetimes: If an EventEmitter outlives the request that registered its listener, the context may be stale. Use AsyncResource.bind() to capture the correct context.
Cron jobs / background tasks: These don't have a "request" — create a synthetic context with a job ID instead.

Summary

AsyncLocalStorage eliminates the most painful boilerplate in Node.js API development. Once set up, you get:

Request correlation across every log line, automatically
Clean function signatures — no requestId parameter threading
Zero-cost context in error handlers — always know which request failed
Automatic enrichment — add userId, tenantId, and traceId as they become available
Negligible performance overhead on Node.js 22+ (the current LTS in 2026)

The pattern scales from simple Express apps to complex microservices. It's the same mechanism OpenTelemetry uses under the hood — battle-tested and production-proven.

Need a production API to test your frontend against? 1xAPI on RapidAPI offers sports data, verification, and utility APIs with built-in request tracing on every response.

How to Supercharge Your Node.js API with WebAssembly (Wasm) Modules in 2026

1xApi — Thu, 26 Mar 2026 01:03:04 +0000

WebAssembly (Wasm) has moved far beyond the browser. In 2026, it's one of the most powerful tools in a Node.js API developer's arsenal — letting you run CPU-intensive routines at near-native speed inside your existing Express, Fastify, or Hono server without rewriting your entire stack.

This guide shows you exactly how to integrate Wasm modules into a Node.js API, when to reach for them, and real benchmarks showing why it matters.

What Is WebAssembly (and Why Does It Matter for APIs)?

WebAssembly is a binary instruction format designed as a portable compilation target for languages like Rust, C, C++, and AssemblyScript. When compiled to .wasm, code runs in a sandboxed, memory-safe virtual machine with predictable, near-native performance.

In 2026, Wasm is no longer just a browser technology. Node.js has first-class support via the WebAssembly global — the same V8 engine that powers Chrome. This means your API can offload compute-heavy work to a Wasm module and get:

3–15× faster execution for cryptographic operations vs. pure JavaScript
10–50× faster image and media processing pipelines
5–20× speedup for mathematical computations and data parsing
Portable, sandboxed execution — the same .wasm binary runs in Node.js, Cloudflare Workers, Deno, and the browser

The key insight: JavaScript handles I/O brilliantly (that's what it was designed for), but it was never built for CPU-bound work. Wasm fills that gap without requiring you to abandon your Node.js ecosystem.

When Should You Use Wasm in Your API?

Not every endpoint needs Wasm. Here's a practical decision matrix:

Task	Use Wasm?	Reason
JSON serialization / parsing	❌ No	V8's JSON is already highly optimized
Database queries	❌ No	I/O bound, not CPU bound
Image resizing / thumbnail generation	✅ Yes	10–50× speedup
PDF generation or parsing	✅ Yes	CPU intensive, complex format parsing
Cryptographic hashing / HMAC	✅ Yes	3–15× faster
ML inference (small models)	✅ Yes	ONNX Runtime Wasm available
CSV / Parquet large file parsing	✅ Yes	Significant throughput gains
Simple string manipulation	❌ No	Overhead not worth it
Real-time audio/video transcoding	✅ Yes	Use ffmpeg compiled to Wasm

Rule of thumb: If a profiler shows an endpoint spending >20% of its time in pure computation (not waiting for I/O), Wasm is worth evaluating.

Setting Up Your First Wasm Module in Node.js

We'll use AssemblyScript — a TypeScript-like language that compiles to Wasm. It's the fastest on-ramp for JavaScript developers because the syntax is familiar.

Step 1: Install AssemblyScript

mkdir wasm-api-demo && cd wasm-api-demo
npm init -y
npm install --save-dev assemblyscript
npx asinit .

This creates the following structure:

wasm-api-demo/
├── assembly/
│   └── index.ts      # Your AssemblyScript source
├── build/
│   └── release.wasm  # Compiled output
├── asconfig.json
└── package.json

Step 2: Write a CPU-Intensive Function in AssemblyScript

Here's a Fibonacci calculator — intentionally naive so we can benchmark it:

// assembly/index.ts

/**
 * Fibonacci - naive recursive (to demonstrate CPU-bound work)
 */
export function fibonacci(n: i32): i64 {
  if (n <= 1) return n;
  return fibonacci(n - 1) + fibonacci(n - 2);
}

/**
 * Batch sum of an array
 */
export function sumArray(arr: Int32Array): i64 {
  let total: i64 = 0;
  for (let i = 0; i < arr.length; i++) {
    total += arr[i];
  }
  return total;
}

/**
 * Fast string hash (FNV-1a variant)
 */
export function hashString(input: string): u32 {
  let hash: u32 = 2166136261;
  for (let i = 0; i < input.length; i++) {
    hash ^= input.charCodeAt(i) as u32;
    hash = (hash * 16777619) as u32;
  }
  return hash;
}

Step 3: Compile to Wasm

npx asc assembly/index.ts --target release --outFile build/release.wasm

This produces a compact build/release.wasm binary — typically just a few KB for pure computational logic.

Step 4: Load and Call Wasm from Node.js

// src/wasm-loader.js
import { readFileSync } from 'fs';
import { fileURLToPath } from 'url';
import { dirname, join } from 'path';

const __dirname = dirname(fileURLToPath(import.meta.url));

let wasmExports = null;

export async function loadWasm() {
  if (wasmExports) return wasmExports;

  const wasmBuffer = readFileSync(
    join(__dirname, '../build/release.wasm')
  );

  const { instance } = await WebAssembly.instantiate(wasmBuffer, {
    env: {
      memory: new WebAssembly.Memory({ initial: 256, maximum: 512 }),
      abort: (_msg, _file, line, col) => {
        console.error(`Wasm abort at ${line}:${col}`);
      },
    },
  });

  wasmExports = instance.exports;
  return wasmExports;
}

Notice the singleton pattern — WebAssembly.instantiate is expensive on first load. Cache the exports and reuse them across requests.

Building a Real API Endpoint with Wasm

Here's a complete Fastify endpoint that uses the Wasm module:

// src/server.js
import Fastify from 'fastify';
import { loadWasm } from './wasm-loader.js';

const app = Fastify({ logger: true });

// Pre-load Wasm at startup
let wasm;
app.addHook('onReady', async () => {
  wasm = await loadWasm();
  app.log.info('WebAssembly module loaded');
});

/**
 * POST /compute/fibonacci
 * Body: { "n": 40 }
 */
app.post('/compute/fibonacci', {
  schema: {
    body: {
      type: 'object',
      required: ['n'],
      properties: {
        n: { type: 'integer', minimum: 0, maximum: 50 },
      },
    },
  },
}, async (request, reply) => {
  const { n } = request.body;

  const start = performance.now();
  const result = wasm.fibonacci(n);
  const durationMs = (performance.now() - start).toFixed(3);

  return {
    input: n,
    result: Number(result),
    computedInMs: durationMs,
    engine: 'WebAssembly',
  };
});

Passing Complex Data Between JavaScript and Wasm

This is the part most tutorials skip. Wasm only understands numbers (i32, i64, f32, f64). To pass arrays or strings, you work with linear memory.

For production use, skip manual memory management and use as-bind:

npm install as-bind

import asBind from 'as-bind';
import { readFileSync } from 'fs';

const wasm = await asBind.instantiate(
  readFileSync('./build/release.wasm'),
  { /* imports */ }
);

// Now you can pass JS strings and arrays directly!
const hash = wasm.exports.hashString("hello world");
const sum = wasm.exports.sumArray([1, 2, 3, 4, 5]);

as-bind handles all the memory encoding/decoding automatically.

Performance Benchmarks (Node.js 22, March 2026)

Here are real numbers from benchmarking fibonacci(40) across implementations:

Implementation	Time (ms)	Relative Speed
Pure JavaScript (naive)	1,842 ms	1× (baseline)
WebAssembly (AssemblyScript)	612 ms	3.0× faster
WebAssembly (Rust via wasm-pack)	487 ms	3.8× faster
N-API C++ Addon	421 ms	4.4× faster

For cryptographic operations (SHA-256 hashing, 1 million iterations):

Implementation	Throughput
Pure JavaScript	180,000 hashes/sec
`crypto` (Node.js built-in, C++)	2,100,000 hashes/sec
WASM (Rust sha2 crate)	1,850,000 hashes/sec
WASM (AssemblyScript)	620,000 hashes/sec

Key takeaway: For hashing, Node.js's built-in crypto module is still fastest. Use WASM when you need algorithms not in the standard library, or when running in Cloudflare Workers where native addons aren't available.

Deploying Wasm Modules in Production

Bundle with esbuild

esbuild src/server.js \
  --bundle \
  --platform=node \
  --target=node22 \
  --outfile=dist/server.js \
  --loader:.wasm=binary \
  --external:@fastify/multipart

With --loader:.wasm=binary, esbuild embeds the Wasm binary as a base64 string — no separate file needed.

Docker Multi-Stage Build

FROM node:22-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY assembly/ ./assembly/
COPY asconfig.json ./
# Compile Wasm at build time, not runtime
RUN npx asc assembly/index.ts --target release --outFile build/release.wasm
COPY src/ ./src/

FROM node:22-alpine AS runtime
WORKDIR /app
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/build/release.wasm ./build/release.wasm
COPY --from=builder /app/src ./src
COPY package.json ./

EXPOSE 3000
CMD ["node", "src/server.js"]

Cloudflare Workers Deployment

// worker.js
import wasmModule from './build/release.wasm';

const instance = await WebAssembly.instantiate(wasmModule);
const { fibonacci } = instance.exports;

export default {
  async fetch(request) {
    const { n } = await request.json();
    const result = fibonacci(n);
    return Response.json({ result: Number(result) });
  }
};

The same .wasm binary runs in Node.js, Cloudflare Workers, or Deno — write once, deploy everywhere.

Common Pitfalls to Avoid

1. Instantiating Wasm on every request

Cache exports at server startup. See the singleton pattern above.

2. Using Wasm for I/O-bound operations

Wasm doesn't help with await fetch() or database queries. Profile first.

3. Forgetting about memory growth

Set a reasonable maximum in WebAssembly.Memory and monitor heap usage in production.

4. Ignoring Wasm startup latency in serverless

In cold-start environments (Lambda, Workers), use module caching strategies.

5. Not testing across runtimes

If deploying to both Node.js and Cloudflare Workers, test in both — memory APIs have subtle differences.

Quick Reference: Wasm Ecosystem in 2026

Tool	Purpose	Install
AssemblyScript	TypeScript → Wasm compiler	`npm i assemblyscript`
wasm-pack	Rust → Wasm with JS bindings	`cargo install wasm-pack`
as-bind	Auto JS↔Wasm bindings	`npm i as-bind`
Emscripten	C/C++ → Wasm	`emcc` CLI
WABT	Wasm binary toolkit (inspect .wasm)	`brew install wabt`
pdfjs-dist	PDF processing (Wasm internally)	`npm i pdfjs-dist`
sharp	Image processing (libvips)	`npm i sharp`
ONNX Runtime Web	ML inference via Wasm	`npm i onnxruntime-web`

Summary

WebAssembly in Node.js APIs is production-ready in 2026. The workflow is mature:

Profile first — identify CPU-bound hotspots
Write the compute core in AssemblyScript or Rust
Compile to .wasm at build time (not runtime)
Cache the instantiated module at server startup
Deploy the same binary to Node.js, Cloudflare Workers, or Deno

For API developers processing images, parsing documents, running cryptographic operations, or doing real-time ML inference — Wasm is the lever that turns a 500ms endpoint into a 50ms endpoint.

Need a battle-tested, production-ready API foundation? Check out 1xAPI on RapidAPI for hosted API endpoints you can integrate in minutes.

How to Implement HMAC Request Signing for Secure API Authentication in Node.js (2026 Guide)

1xApi — Wed, 25 Mar 2026 01:03:31 +0000

Why API Keys Alone Aren't Enough

Most APIs protect endpoints with a simple API key in the header:

Authorization: Bearer sk_live_abc123xyz

This works—until it doesn't. If that key leaks (logs, browser history, a misconfigured proxy), an attacker can replay any request indefinitely. They can modify the request body, change query parameters, and the server has no way to detect the tampering.

HMAC request signing solves three problems at once:

Authentication — proves the request came from someone who holds the secret key
Integrity — any modification to the URL, headers, or body invalidates the signature
Replay protection — a timestamp window (usually ±5 minutes) makes captured requests useless after expiry

This is how AWS, Stripe, Twilio, and GitHub all secure their webhooks and APIs. In 2026, with AI agents and automated systems making billions of API calls, this pattern is more relevant than ever.

How HMAC Signing Works

The core idea is simple: instead of sending the secret itself, the client uses the secret to sign a canonical string that describes the request. The server independently rebuilds that same string and verifies the signature.

Client                                Server
  |                                     |
  |  1. Build canonical request string  |
  |  2. HMAC-SHA256(secret, canonical)  |
  |  3. Send request + signature        |
  |------------------------------------>|
  |                                     |  4. Look up secret by API key
  |                                     |  5. Rebuild canonical string
  |                                     |  6. Compare signatures (timing-safe)
  |                                     |  7. Check timestamp freshness
  |<------------------------------------|
  |  200 OK (or 401 Unauthorized)       |

The canonical request string typically includes:

HTTP method (GET, POST, etc.)
Request path
Timestamp (Unix epoch)
SHA-256 hash of the request body
Selected headers (optional, for extra security)

If any of these change, the signature changes. The server rejects it.

Setting Up the Project

We'll build a complete implementation: an Express middleware that verifies signatures, plus a client SDK that signs requests.

mkdir hmac-api-signing && cd hmac-api-signing
npm init -y
npm install express
npm install --save-dev @types/node typescript ts-node

No third-party crypto libraries needed — Node.js crypto module handles everything.

Step 1: The Signing Utility

Create a shared utility that both client and server use:

// src/hmac.ts
import { createHash, createHmac, timingSafeEqual } from 'node:crypto';

export interface SignatureComponents {
  method: string;
  path: string;
  timestamp: string;
  body: string | Buffer;
}

/**
 * Compute SHA-256 hash of the request body.
 * This ensures body integrity — any modification breaks the signature.
 */
export function hashBody(body: string | Buffer): string {
  const content = typeof body === 'string' ? body : body.toString('utf8');
  return createHash('sha256').update(content).digest('hex');
}

/**
 * Build the canonical string that gets signed.
 * Both client and server must produce identical output.
 */
export function buildCanonicalString(components: SignatureComponents): string {
  const bodyHash = hashBody(components.body);

  return [
    components.method.toUpperCase(),
    components.path,
    components.timestamp,
    bodyHash,
  ].join('\n');
}

/**
 * Sign a canonical string with HMAC-SHA256.
 */
export function sign(secret: string, canonical: string): string {
  return createHmac('sha256', secret)
    .update(canonical)
    .digest('hex');
}

/**
 * Constant-time comparison to prevent timing attacks.
 * Never use === for signature comparison!
 */
export function verifySignature(expected: string, provided: string): boolean {
  if (expected.length !== provided.length) {
    // Length mismatch — still do a dummy comparison to maintain constant time
    timingSafeEqual(
      Buffer.from(expected, 'hex'),
      Buffer.from(expected, 'hex')
    );
    return false;
  }
  return timingSafeEqual(
    Buffer.from(expected, 'hex'),
    Buffer.from(provided, 'hex')
  );
}

Why `timingSafeEqual`?

A naïve === comparison short-circuits as soon as it finds a mismatch. An attacker can send thousands of requests with slightly different signatures and measure response times to reverse-engineer the correct value bit by bit. timingSafeEqual always takes the same amount of time regardless of where the mismatch occurs.

Step 2: Express Verification Middleware

// src/middleware/hmac-verify.ts
import { Request, Response, NextFunction } from 'express';
import { buildCanonicalString, sign, verifySignature } from '../hmac';

// In production: fetch these from your database by API key
const API_CREDENTIALS: Record<string, string> = {
  'key_prod_abc123': 'secret_xkJ9mP2qR8vN4wL6',
  'key_prod_def456': 'secret_yH7nS3tQ1uM5xO9',
};

const TIMESTAMP_TOLERANCE_MS = 5 * 60 * 1000; // 5 minutes

export function hmacVerify(req: Request, res: Response, next: NextFunction) {
  const apiKey = req.headers['x-api-key'] as string;
  const signature = req.headers['x-signature'] as string;
  const timestamp = req.headers['x-timestamp'] as string;

  // 1. Check required headers
  if (!apiKey || !signature || !timestamp) {
    return res.status(401).json({
      error: 'Missing authentication headers',
      required: ['x-api-key', 'x-signature', 'x-timestamp'],
    });
  }

  // 2. Validate timestamp to prevent replay attacks
  const requestTime = parseInt(timestamp, 10);
  const now = Math.floor(Date.now() / 1000);

  if (isNaN(requestTime) || Math.abs(now - requestTime) > TIMESTAMP_TOLERANCE_MS / 1000) {
    return res.status(401).json({
      error: 'Request timestamp expired or invalid',
      tolerance: '±5 minutes',
    });
  }

  // 3. Look up the secret for this API key
  const secret = API_CREDENTIALS[apiKey];
  if (!secret) {
    return res.status(401).json({ error: 'Invalid API key' });
  }

  // 4. Rebuild the canonical string server-side
  const bodyString = req.body ? JSON.stringify(req.body) : '';
  const canonical = buildCanonicalString({
    method: req.method,
    path: req.path,
    timestamp,
    body: bodyString,
  });

  // 5. Compute expected signature and compare (timing-safe!)
  const expectedSig = sign(secret, canonical);

  if (!verifySignature(expectedSig, signature)) {
    return res.status(401).json({ error: 'Signature verification failed' });
  }

  // 6. Attach verified identity to request
  (req as any).apiKeyId = apiKey;
  next();
}

Step 3: The Express Server

// src/server.ts
import express from 'express';
import { hmacVerify } from './middleware/hmac-verify';

const app = express();
app.use(express.json());

// Public endpoint — no signing required
app.get('/health', (_req, res) => {
  res.json({ status: 'ok', time: new Date().toISOString() });
});

// Protected endpoints — requires valid HMAC signature
app.use('/api', hmacVerify);

app.get('/api/data', (req, res) => {
  res.json({
    message: 'Authenticated!',
    apiKey: (req as any).apiKeyId,
    data: [1, 2, 3],
  });
});

app.post('/api/orders', (req, res) => {
  res.status(201).json({
    message: 'Order created',
    receivedBody: req.body,
  });
});

app.listen(3000, () => {
  console.log('Server running on http://localhost:3000');
});

Step 4: The Client SDK

This is what your API consumers will use. Package it as an npm module or include it in your SDK:

// src/client/ApiClient.ts
import { createHash, createHmac } from 'node:crypto';

interface ApiClientOptions {
  baseUrl: string;
  apiKey: string;
  apiSecret: string;
}

interface RequestOptions {
  method?: string;
  path: string;
  body?: unknown;
  query?: Record<string, string>;
}

export class ApiClient {
  private baseUrl: string;
  private apiKey: string;
  private apiSecret: string;

  constructor(options: ApiClientOptions) {
    this.baseUrl = options.baseUrl.replace(/\/$/, '');
    this.apiKey = options.apiKey;
    this.apiSecret = options.apiSecret;
  }

  private hashBody(body: string): string {
    return createHash('sha256').update(body).digest('hex');
  }

  private buildSignature(method: string, path: string, timestamp: string, bodyString: string): string {
    const bodyHash = this.hashBody(bodyString);
    const canonical = [method.toUpperCase(), path, timestamp, bodyHash].join('\n');
    return createHmac('sha256', this.apiSecret).update(canonical).digest('hex');
  }

  async request<T>(options: RequestOptions): Promise<T> {
    const { method = 'GET', path, body, query } = options;
    const timestamp = Math.floor(Date.now() / 1000).toString();
    const bodyString = body ? JSON.stringify(body) : '';
    const signature = this.buildSignature(method, path, timestamp, bodyString);

    const url = new URL(this.baseUrl + path);
    if (query) {
      Object.entries(query).forEach(([k, v]) => url.searchParams.set(k, v));
    }

    const headers: Record<string, string> = {
      'Content-Type': 'application/json',
      'x-api-key': this.apiKey,
      'x-signature': signature,
      'x-timestamp': timestamp,
    };

    const response = await fetch(url.toString(), {
      method,
      headers,
      body: bodyString || undefined,
    });

    if (!response.ok) {
      const error = await response.json().catch(() => ({ error: 'Unknown error' }));
      throw new Error(`API error ${response.status}: ${JSON.stringify(error)}`);
    }

    return response.json();
  }

  // Convenience methods
  get<T>(path: string, query?: Record<string, string>) {
    return this.request<T>({ method: 'GET', path, query });
  }

  post<T>(path: string, body: unknown) {
    return this.request<T>({ method: 'POST', path, body });
  }

  put<T>(path: string, body: unknown) {
    return this.request<T>({ method: 'PUT', path, body });
  }

  delete<T>(path: string) {
    return this.request<T>({ method: 'DELETE', path });
  }
}

Using the Client

// src/client/example.ts
import { ApiClient } from './ApiClient';

const client = new ApiClient({
  baseUrl: 'http://localhost:3000',
  apiKey: 'key_prod_abc123',
  apiSecret: 'secret_xkJ9mP2qR8vN4wL6',
});

// GET request
const data = await client.get('/api/data');
console.log(data);
// { message: 'Authenticated!', apiKey: 'key_prod_abc123', data: [1, 2, 3] }

// POST request — body is automatically signed
const order = await client.post('/api/orders', {
  product: 'api-access',
  quantity: 1,
  amount: 29.99,
});
console.log(order);

Step 5: Testing the Middleware

// src/__tests__/hmac.test.ts
import { describe, it, expect } from 'node:test';
import assert from 'node:assert';
import { buildCanonicalString, sign, verifySignature } from '../hmac';

describe('HMAC signing', () => {
  const secret = 'test_secret_key_32chars_minimum!!';

  it('signs and verifies a canonical string', () => {
    const canonical = buildCanonicalString({
      method: 'POST',
      path: '/api/orders',
      timestamp: '1742860800',
      body: JSON.stringify({ product: 'test', amount: 9.99 }),
    });

    const signature = sign(secret, canonical);
    assert.strictEqual(verifySignature(signature, signature), true);
  });

  it('rejects a tampered body', () => {
    const ts = '1742860800';
    const original = buildCanonicalString({
      method: 'POST', path: '/api/orders', timestamp: ts,
      body: JSON.stringify({ amount: 9.99 }),
    });
    const tampered = buildCanonicalString({
      method: 'POST', path: '/api/orders', timestamp: ts,
      body: JSON.stringify({ amount: 999.99 }), // attacker inflated the amount!
    });

    const signature = sign(secret, original);
    const tamperedSig = sign(secret, tampered);

    assert.strictEqual(verifySignature(signature, tamperedSig), false);
  });

  it('rejects a path traversal attempt', () => {
    const ts = '1742860800';
    const original = buildCanonicalString({
      method: 'GET', path: '/api/data', timestamp: ts, body: '',
    });
    const spoofed = buildCanonicalString({
      method: 'GET', path: '/api/admin', timestamp: ts, body: '',
    });

    const sig = sign(secret, original);
    assert.strictEqual(verifySignature(sig, sign(secret, spoofed)), false);
  });
});

Run with Node.js built-in test runner (Node.js 22+):

node --test src/__tests__/hmac.test.ts

Handling Edge Cases in Production

1. Body Parsing Order Matters

Express must parse the body before the HMAC middleware reads it. And you must ensure the body is serialized consistently:

// ❌ Wrong: body might be undefined or in wrong format
app.use('/api', hmacVerify);
app.use(express.json());

// ✅ Correct: parse first, then verify
app.use(express.json());
app.use('/api', hmacVerify);

Also, always use JSON.stringify(req.body) — not a raw buffer — so both client and server produce identical canonical strings.

2. Clock Skew Between Clients

A 5-minute tolerance (±300 seconds) is standard. For high-security endpoints, reduce to 60 seconds. For clients in constrained environments (IoT, embedded), you can extend to 10 minutes.

// For financial APIs: tighter window
const TOLERANCE_SECONDS = 60;

// For IoT devices with clock drift: wider window
const TOLERANCE_SECONDS = 600;

3. Storing API Secrets

Never store raw secrets. Use a database with encrypted columns:

// Use bcrypt or AES-256-GCM to encrypt secrets at rest
import { randomBytes, createCipheriv, createDecipheriv } from 'node:crypto';

const ENCRYPTION_KEY = Buffer.from(process.env.SECRET_ENCRYPTION_KEY!, 'hex'); // 32 bytes

function encryptSecret(secret: string): string {
  const iv = randomBytes(16);
  const cipher = createCipheriv('aes-256-gcm', ENCRYPTION_KEY, iv);
  const encrypted = Buffer.concat([cipher.update(secret, 'utf8'), cipher.final()]);
  const tag = cipher.getAuthTag();
  return Buffer.concat([iv, tag, encrypted]).toString('base64');
}

function decryptSecret(encrypted: string): string {
  const data = Buffer.from(encrypted, 'base64');
  const iv = data.slice(0, 16);
  const tag = data.slice(16, 32);
  const ciphertext = data.slice(32);
  const decipher = createDecipheriv('aes-256-gcm', ENCRYPTION_KEY, iv);
  decipher.setAuthTag(tag);
  return decipher.update(ciphertext) + decipher.final('utf8');
}

4. Preventing Replay Attacks with a Nonce Cache

Timestamp checking alone doesn't prevent a captured request from being replayed within the 5-minute window. For critical endpoints (payments, mutations), maintain a nonce cache:

// Use Redis for distributed deployments
import { createClient } from 'redis';
const redis = createClient();

async function checkAndStoreNonce(nonce: string, ttlSeconds = 300): Promise<boolean> {
  const key = `nonce:${nonce}`;
  // SET with NX (only set if not exists) + EX (expire after TTL)
  const result = await redis.set(key, '1', { NX: true, EX: ttlSeconds });
  return result === 'OK'; // false means nonce already used
}

// In middleware:
const nonce = req.headers['x-nonce'] as string;
if (nonce) {
  const isNew = await checkAndStoreNonce(nonce);
  if (!isNew) {
    return res.status(401).json({ error: 'Nonce already used (replay attack detected)' });
  }
}

Comparing HMAC Signing vs Other Auth Methods

Method	Replay Protection	Body Integrity	Stateless	Use Case
API Key only	❌	❌	✅	Simple internal APIs
Bearer JWT	❌ (until expiry)	❌	✅	User auth, short-lived
HMAC Signing	✅	✅	✅	Server-to-server, payments
mTLS	✅	✅	✅	High-security, complex setup
OAuth 2.0 PKCE	✅	❌	✅	User-delegated access

HMAC signing hits the sweet spot for machine-to-machine API communication: it's stateless (no token storage needed), verifiable without network calls, and protects against both eavesdropping and tampering.

Real-World Usage: How Major APIs Do It

Stripe signs webhook payloads with HMAC-SHA256 using the Stripe-Signature header, which includes a timestamp to prevent replays:

Stripe-Signature: t=1742860800,v1=abc123...

AWS Signature Version 4 builds a canonical request with method, URI, query string, headers, and body hash — all signed with HMAC-SHA256.

GitHub signs webhook bodies with X-Hub-Signature-256: sha256=abc123... using a shared secret.

Your implementation follows the same battle-tested pattern.

Putting It All Together

Here's the minimal production checklist:

✅ Use HMAC-SHA256 (not HMAC-MD5 or HMAC-SHA1)
✅ Include method + path + timestamp + body hash in canonical string
✅ Use timingSafeEqual for comparison — never ===
✅ Reject requests older than ±5 minutes
✅ Add nonce deduplication for mutation endpoints (POST/PUT/DELETE)
✅ Encrypt secrets at rest with AES-256-GCM
✅ Log auth failures (but not the invalid signatures themselves)

HMAC signing is a thin layer that costs microseconds per request but eliminates entire classes of API abuse. For any server-to-server integration — especially anything touching payments, user data, or critical operations — it's the right default in 2026.

Try It with the 1xAPI SDK

If you're building APIs on 1xAPI, HMAC signing middleware like the one above can be dropped directly into any Express or Hono server. The same pattern works with Bun's built-in Bun.serve() and Deno's Deno.serve() — the node:crypto module is compatible across all three runtimes.

Check out the 1xAPI documentation for more production-ready API patterns.

DEV Community: 1xApi

How to Prevent Cache Stampede in Node.js APIs with the Single-Flight Pattern (2026 Guide)

What Is Cache Stampede and Why Should You Care?

The Single-Flight Pattern: Core Concept

Building a Production Cache Layer with Single-Flight

Step 1: Install dependencies

Step 2: The CacheWithSingleFlight class

Express Integration

The Thundering Herd in Numbers

Extending to Multiple Instances with Redis Locks

Probabilistic Early Expiration (XFetch)

Monitoring and Alerting

Quick Checklist for Production

Summary

How to Implement the Saga Pattern for Distributed Transactions in Node.js (2026 Guide)

What Problem Do Sagas Solve?

Saga vs. Two-Phase Commit (2PC)

Two Saga Flavors

Choreography: Event-Driven Saga

Orchestration: Central Coordinator

Building an Orchestration Saga in Node.js

Project Setup

Step 1: Define the Saga Steps

Step 2: The Saga Orchestrator

Step 3: Wire It Into Your Express API

Handling Stuck Compensations

Choreography Saga: Event-Driven Alternative

Choreography vs. Orchestration: When to Use Each

Production Checklist for Sagas in 2026

Conclusion

How to Implement RBAC + ABAC Authorization in Node.js APIs (2026 Guide)

What's the Difference? RBAC vs ABAC

Project Setup

Step 1: Define Your Permission Schema

Step 2: The Role-Permission Matrix (RBAC Core)

Step 3: RBAC Middleware

Step 4: ABAC Policy Engine

Step 5: Combined RBAC + ABAC Middleware

Step 6: Wire It All Together

Step 7: JWT Authentication Middleware (Bonus)

Testing Your Authorization Layer

Performance Considerations

Summary

How to Use the ES2026 Temporal API in Node.js REST APIs (2026 Guide)

What's Wrong with Date in 2026?

The Temporal Fix: Type-Safe, Immutable, Timezone-Aware

Getting Started: Install the Polyfill

Pattern 1: Storing and Returning Timestamps in REST APIs

Pattern 2: Accepting and Validating Date Inputs

Pattern 3: Multi-Timezone Scheduling Logic

Pattern 4: Duration Calculations for Billing and Rate Limiting

Pattern 5: Relative Time Without moment.js

Quick Reference: Date → Temporal Migrations

Conclusion

How to Add Structured Logging to Node.js APIs with Pino 9 + OpenTelemetry (2026 Guide)

Why console.log Kills You at Scale

Stack Overview (2026)

Project Setup

Step 1: Bootstrap OpenTelemetry (Must Load First)

Step 2: Configure Pino with OTel Transport

What a Log Line Looks Like in Production

Step 3: Add HTTP Request Logging Middleware

Step 4: Wire It All Together in server.js

Step 5: Child Loggers — The Secret to Context-Rich Logs

Sampling: Don't Log Everything at 100%

Sending Logs to Grafana Loki (Production Setup)

Environment Variable Reference

Performance: Pino vs Winston vs Bunyan (2026 Benchmarks)

Common Mistakes to Avoid

❌ Logging inside hot loops

❌ Logging Error objects without the err key

❌ Blocking the event loop with synchronous log destinations

Connecting Logs to 1xAPI Calls

Quick-Start Checklist

Summary

How to Implement Graceful Shutdown in Node.js APIs (Zero Dropped Requests on Deploy)

Why Graceful Shutdown Matters in 2026

The Minimal Correct Implementation

The Keep-Alive Connection Problem

Draining In-Flight Requests Properly

What's Wrong with `Date` in 2026?

Quick Reference: `Date` → Temporal Migrations

Why `console.log` Kills You at Scale

Step 4: Wire It All Together in `server.js`

❌ Logging `Error` objects without the `err` key

Option A: Kubernetes `preStop` hook (recommended)

Fastify (with built-in `fastify.close()`)