DEV Community: Ali

Kubernetes + Node.js: Health Checks and Graceful Shutdown Done Right

Ali — Fri, 06 Feb 2026 13:11:37 +0000

TL;DR: Kubernetes sends SIGTERM and waits 30 seconds. If your Node.js app doesn't handle it properly, requests fail during deployments. This guide covers liveness/readiness probes, graceful shutdown, and the keep-alive problem.

You deploy a new version. Kubernetes starts rolling out pods. Users start seeing 502 errors.

Sound familiar?

The problem isn't Kubernetes. It's how your Node.js app handles the shutdown sequence. Get it right, and you get zero-downtime deployments. Get it wrong, and every deploy causes errors.

How Kubernetes Terminates Pods

When Kubernetes decides to kill a pod (deployment, scale-down, node drain), this happens:

1. Pod marked for termination
2. Pod removed from Service endpoints (no new traffic)
3. PreStop hook runs (if configured)
4. SIGTERM sent to container
5. Grace period countdown starts (default: 30s)
6. If still running: SIGKILL sent (forced kill)

Your app has 30 seconds to:

Stop accepting new connections
Finish in-flight requests
Close database/cache connections
Exit cleanly

If you don't exit in time, Kubernetes sends SIGKILL. That's an immediate, non-graceful termination. Connections drop. Transactions fail.

The SIGTERM Problem

By default, Node.js does nothing special with SIGTERM:

// Default behavior: exit immediately
const server = app.listen(3000)

// When SIGTERM arrives:
// - Active requests get ECONNRESET
// - Database connections drop
// - No cleanup runs

You need to handle it explicitly:

process.on('SIGTERM', () => {
  console.log('SIGTERM received. Shutting down gracefully...')
  server.close(() => {
    console.log('HTTP server closed')
    process.exit(0)
  })
})

But server.close() alone isn't enough. Keep reading.

Liveness vs Readiness Probes

Kubernetes uses two probes to manage traffic:

Liveness Probe

Question: "Is this container alive?"

If it fails: Kubernetes restarts the container.

Implementation:

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

app.get('/health/live', (req, res) => {
  // If the process is running, it's alive
  res.status(200).json({ status: 'alive' })
})

Liveness should almost always return 200. The only time it should fail is if your app is in a broken state that requires a restart (deadlock, memory corruption).

Common mistake: Making liveness depend on database connectivity. If your database goes down, Kubernetes restarts all your pods. Now you have no pods AND no database. Bad.

Readiness Probe

Question: "Can this container handle traffic?"

If it fails: Kubernetes stops routing traffic to this pod.

Implementation:

readinessProbe:
  httpGet:
    path: /health/ready
    port: 3000
  initialDelaySeconds: 5
  periodSeconds: 5

let isShuttingDown = false

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

process.on('SIGTERM', () => {
  isShuttingDown = true
  // Continue with shutdown...
})

During shutdown: Return 503. Kubernetes stops sending new traffic. Existing requests finish.

The Keep-Alive Problem

HTTP keep-alive connections are the silent killer of graceful shutdown.

Here's what happens:

1. Client opens connection to your pod
2. Client sends request
3. Your pod responds
4. Connection stays open (keep-alive)
5. Kubernetes sends SIGTERM to your pod
6. You call server.close()
7. server.close() waits for all connections to close
8. Keep-alive connections are idle but open
9. server.close() waits... and waits...
10. 30 seconds pass
11. SIGKILL
12. Client's next request on that connection fails

The problem: server.close() doesn't close idle connections. It just stops accepting new ones.

Solution: Track and terminate connections

const connections = new Set()

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

process.on('SIGTERM', () => {
  // Stop new connections
  server.close()

  // Close idle keep-alive connections
  for (const socket of connections) {
    socket.end()  // Graceful close
  }

  // Force-close after timeout
  setTimeout(() => {
    for (const socket of connections) {
      socket.destroy()  // Force close
    }
  }, 10000)
})

The Race Condition

There's a race between:

Kubernetes removing your pod from endpoints
Your app receiving SIGTERM

Sometimes, requests arrive AFTER SIGTERM but BEFORE the pod is removed from the load balancer.

Solution: Shutdown delay

process.on('SIGTERM', async () => {
  console.log('SIGTERM received')

  // 1. Mark as not ready (stop new requests)
  isShuttingDown = true

  // 2. Wait for load balancer to catch up
  await new Promise(resolve => setTimeout(resolve, 5000))

  // 3. Now close the server
  server.close()
})

Or configure it in your Kubernetes spec:

spec:
  terminationGracePeriodSeconds: 60
  containers:
  - name: app
    lifecycle:
      preStop:
        exec:
          command: ["sleep", "5"]

The preStop hook runs before SIGTERM, giving the load balancer time to update.

Complete Manual Implementation

Here's everything together:

import express from 'express'
import { PrismaClient } from '@prisma/client'

const prisma = new PrismaClient()
const app = express()
let isShuttingDown = false
const connections = new Set()

// Health checks
app.get('/health/live', (req, res) => {
  res.status(200).json({ status: 'alive' })
})

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

// Your routes
app.get('/api/data', async (req, res) => {
  const data = await prisma.user.findMany()
  res.json(data)
})

const server = app.listen(3000)

// Track connections
server.on('connection', (socket) => {
  connections.add(socket)
  socket.on('close', () => connections.delete(socket))
})

// Graceful shutdown
async function shutdown(signal) {
  console.log(`${signal} received. Starting graceful shutdown...`)

  // 1. Stop accepting new work
  isShuttingDown = true

  // 2. Wait for load balancer (if in Kubernetes)
  await new Promise(resolve => setTimeout(resolve, 5000))

  // 3. Stop HTTP server
  server.close()

  // 4. Close idle connections
  for (const socket of connections) {
    socket.end()
  }

  // 5. Wait for active requests (max 25 seconds)
  await new Promise(resolve => setTimeout(resolve, 25000))

  // 6. Force close remaining connections
  for (const socket of connections) {
    socket.destroy()
  }

  // 7. Close database
  await prisma.$disconnect()

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

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

That's 60+ lines just for proper Kubernetes shutdown. Every app needs this.

The Zero-Config Way

Kaput handles all of this automatically:

import express from 'express'
import '@joint-ops/kaput'
import { expressHealthMiddleware } from '@joint-ops/kaput'
import { PrismaClient } from '@prisma/client'

const prisma = new PrismaClient()
const app = express()

// Kubernetes-ready health checks
app.use(expressHealthMiddleware())

app.get('/api/data', async (req, res) => {
  const data = await prisma.user.findMany()
  res.json(data)
})

app.listen(3000)

That's it. Kaput:

Handles SIGTERM
Tracks connections
Returns 503 on readiness during shutdown
Closes Prisma in the right order
Manages timeouts

Kubernetes Manifest

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  replicas: 3
  template:
    spec:
      terminationGracePeriodSeconds: 60
      containers:
      - name: app
        image: my-app:latest
        ports:
        - containerPort: 3000
        livenessProbe:
          httpGet:
            path: /health/live
            port: 3000
          initialDelaySeconds: 10
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /health/ready
            port: 3000
          initialDelaySeconds: 5
          periodSeconds: 5
        lifecycle:
          preStop:
            exec:
              command: ["sleep", "5"]

Kaput's expressHealthMiddleware() provides:

/health - General health status
/health/live - Liveness probe (always 200)
/health/ready - Readiness probe (503 during shutdown)

Common Kubernetes + Node.js Mistakes

1. No SIGTERM Handler

// Bad: Process exits immediately, connections drop
app.listen(3000)

2. Liveness Depends on External Services

# Bad: If DB is down, pods restart forever
livenessProbe:
  httpGet:
    path: /health  # Returns 500 if DB is down

# Good: Separate liveness from dependencies
livenessProbe:
  httpGet:
    path: /health/live  # Always 200 if process is running

3. Readiness Doesn't Change on Shutdown

// Bad: Keeps accepting traffic after SIGTERM
app.get('/health/ready', (req, res) => {
  res.status(200).json({ status: 'ready' })
})

4. terminationGracePeriodSeconds Too Short

# Bad: Only 10 seconds to shutdown
terminationGracePeriodSeconds: 10

# Good: Enough time for requests to complete
terminationGracePeriodSeconds: 60

5. No preStop Hook

# Bad: Race between endpoint removal and SIGTERM
containers:
- name: app
  # No preStop hook

# Good: Delay to let load balancer update
lifecycle:
  preStop:
    exec:
      command: ["sleep", "5"]

6. Using npm start in Dockerfile

# Bad: npm intercepts SIGTERM
CMD npm start

# Good: Node receives SIGTERM
CMD ["node", "dist/server.js"]

Testing Graceful Shutdown

Local Testing

# Terminal 1: Start your app
node server.js

# Terminal 2: Send requests
while true; do curl -s http://localhost:3000/api/data; sleep 0.1; done

# Terminal 3: Send SIGTERM
kill -SIGTERM $(pgrep -f "node server.js")

# Watch Terminal 1 for shutdown logs
# Watch Terminal 2 - requests should complete without errors

Kubernetes Testing

# Watch pod status
kubectl get pods -w

# In another terminal, trigger a rollout
kubectl rollout restart deployment/my-app

# Monitor for 5xx errors
kubectl logs -f deployment/my-app | grep -E "(error|Error|ERROR)"

Quick Start with Kaput

npm install @joint-ops/kaput

// server.js
import express from 'express'
import '@joint-ops/kaput'
import { expressHealthMiddleware } from '@joint-ops/kaput'

const app = express()
app.use(expressHealthMiddleware())

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

app.listen(3000, () => {
  console.log('Server running on port 3000')
})

Deploy to Kubernetes with the manifest above. Zero-downtime deployments. No boilerplate.

Summary

Kubernetes graceful shutdown requires:

SIGTERM handler - Stop accepting work, clean up
Readiness probe - Return 503 during shutdown
Liveness probe - Always 200 (process alive)
Connection tracking - Close keep-alive connections
Shutdown delay - Wait for load balancer to update
Resource ordering - HTTP before databases

Kaput handles all of this with one import. Add health middleware, deploy, done.

Building a REST API with bunWay in 10 Minutes

Ali — Mon, 02 Feb 2026 15:31:46 +0000

TL;DR: Let's build a complete REST API with bunWay—CRUD operations, middleware, error handling, and database integration. If you know Express, you'll feel right at home.

bunWay is an Express-compatible web framework for Bun. Same familiar API, but running on Bun's fast runtime.

Let's build a real API from scratch.

Prerequisites

Bun installed (curl -fsSL https://bun.sh/install | bash)
Basic JavaScript/TypeScript knowledge
10 minutes

Step 1: Project Setup

# Create project directory
mkdir bunway-api && cd bunway-api

# Initialize project
bun init -y

# Install bunWay
bun add bunway

Step 2: Basic Server

Create index.ts:

import { bunway, json, cors, logger } from 'bunway'

const app = bunway()

// Middleware
app.use(logger('dev'))
app.use(cors())
app.use(json())

// Health check
app.get('/health', (req, res) => {
  res.json({ status: 'ok', timestamp: Date.now() })
})

// Start server
app.listen(3000, () => {
  console.log('API running at http://localhost:3000')
})

Run it:

bun run index.ts

Test it:

curl http://localhost:3000/health
# {"status":"ok","timestamp":1706547200000}

You have a running API.

Step 3: In-Memory Data Store

For this tutorial, we'll use an in-memory store. Replace with your database of choice in production.

Add to index.ts:

// Types
interface User {
  id: string
  name: string
  email: string
  createdAt: number
}

// In-memory store
const users: Map<string, User> = new Map()

// Helper to generate IDs
const generateId = () => Math.random().toString(36).substring(2, 9)

Step 4: CRUD Routes

Now let's add the user routes:

// GET all users
app.get('/api/users', (req, res) => {
  const allUsers = Array.from(users.values())
  res.json(allUsers)
})

// GET single user
app.get('/api/users/:id', (req, res) => {
  const user = users.get(req.params.id)

  if (!user) {
    return res.status(404).json({ error: 'User not found' })
  }

  res.json(user)
})

// POST create user
app.post('/api/users', (req, res) => {
  const { name, email } = req.body

  // Validation
  if (!name || !email) {
    return res.status(400).json({ error: 'Name and email are required' })
  }

  // Check for duplicate email
  const existingUser = Array.from(users.values()).find(u => u.email === email)
  if (existingUser) {
    return res.status(409).json({ error: 'Email already exists' })
  }

  // Create user
  const user: User = {
    id: generateId(),
    name,
    email,
    createdAt: Date.now()
  }

  users.set(user.id, user)
  res.status(201).json(user)
})

// PUT update user
app.put('/api/users/:id', (req, res) => {
  const user = users.get(req.params.id)

  if (!user) {
    return res.status(404).json({ error: 'User not found' })
  }

  const { name, email } = req.body

  // Update fields if provided
  if (name) user.name = name
  if (email) user.email = email

  users.set(user.id, user)
  res.json(user)
})

// DELETE user
app.delete('/api/users/:id', (req, res) => {
  const user = users.get(req.params.id)

  if (!user) {
    return res.status(404).json({ error: 'User not found' })
  }

  users.delete(req.params.id)
  res.status(204).send('')
})

Step 5: Error Handling

Add a global error handler:

import { bunway, json, cors, logger, errorHandler } from 'bunway'

// ... your routes ...

// 404 handler (add after all routes)
app.use((req, res) => {
  res.status(404).json({ error: 'Not found' })
})

// Error handler (add last)
app.use(errorHandler())

Complete Code

Here's the full index.ts:

import { bunway, json, cors, logger, errorHandler } from 'bunway'

const app = bunway()

// Types
interface User {
  id: string
  name: string
  email: string
  createdAt: number
}

// In-memory store
const users: Map<string, User> = new Map()
const generateId = () => Math.random().toString(36).substring(2, 9)

// Middleware
app.use(logger('dev'))
app.use(cors())
app.use(json())

// Health check
app.get('/health', (req, res) => {
  res.json({ status: 'ok', timestamp: Date.now() })
})

// GET all users
app.get('/api/users', (req, res) => {
  const allUsers = Array.from(users.values())
  res.json(allUsers)
})

// GET single user
app.get('/api/users/:id', (req, res) => {
  const user = users.get(req.params.id)
  if (!user) {
    return res.status(404).json({ error: 'User not found' })
  }
  res.json(user)
})

// POST create user
app.post('/api/users', (req, res) => {
  const { name, email } = req.body

  if (!name || !email) {
    return res.status(400).json({ error: 'Name and email are required' })
  }

  const existingUser = Array.from(users.values()).find(u => u.email === email)
  if (existingUser) {
    return res.status(409).json({ error: 'Email already exists' })
  }

  const user: User = {
    id: generateId(),
    name,
    email,
    createdAt: Date.now()
  }

  users.set(user.id, user)
  res.status(201).json(user)
})

// PUT update user
app.put('/api/users/:id', (req, res) => {
  const user = users.get(req.params.id)
  if (!user) {
    return res.status(404).json({ error: 'User not found' })
  }

  const { name, email } = req.body
  if (name) user.name = name
  if (email) user.email = email

  users.set(user.id, user)
  res.json(user)
})

// DELETE user
app.delete('/api/users/:id', (req, res) => {
  const user = users.get(req.params.id)
  if (!user) {
    return res.status(404).json({ error: 'User not found' })
  }

  users.delete(req.params.id)
  res.status(204).send('')
})

// 404 handler
app.use((req, res) => {
  res.status(404).json({ error: 'Not found' })
})

// Error handler
app.use(errorHandler())

// Start server
app.listen(3000, () => {
  console.log('API running at http://localhost:3000')
})

Testing the API

Start the server:

bun run index.ts

Test with curl:

# Create a user
curl -X POST http://localhost:3000/api/users \
  -H "Content-Type: application/json" \
  -d '{"name": "Alice", "email": "alice@example.com"}'

# Response: {"id":"abc123","name":"Alice","email":"alice@example.com","createdAt":1706547200000}

# Get all users
curl http://localhost:3000/api/users

# Get single user
curl http://localhost:3000/api/users/abc123

# Update user
curl -X PUT http://localhost:3000/api/users/abc123 \
  -H "Content-Type: application/json" \
  -d '{"name": "Alice Smith"}'

# Delete user
curl -X DELETE http://localhost:3000/api/users/abc123

Bonus: Adding Authentication Middleware

Here's a simple JWT-style auth middleware:

// Auth middleware
const authMiddleware = (req, res, next) => {
  const token = req.headers.authorization?.split(' ')[1]

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

  // In production, verify the token properly
  if (token !== 'secret-token') {
    return res.status(403).json({ error: 'Invalid token' })
  }

  // Attach user info to request
  req.user = { id: '1', role: 'admin' }
  next()
}

// Protected route
app.get('/api/protected', authMiddleware, (req, res) => {
  res.json({ message: 'Secret data', user: req.user })
})

Bonus: Rate Limiting

import { bunway, json, cors, logger, rateLimit } from 'bunway'

// Apply to all routes
app.use(rateLimit({
  windowMs: 60 * 1000, // 1 minute
  max: 100 // 100 requests per minute
}))

// Or apply to specific routes
app.post('/api/users', rateLimit({ windowMs: 60000, max: 10 }), (req, res) => {
  // Max 10 user creations per minute
})

Bonus: Database Integration

Replace the in-memory store with a real database. Here's a Prisma example:

import { PrismaClient } from '@prisma/client'

const prisma = new PrismaClient()

app.get('/api/users', async (req, res) => {
  const users = await prisma.user.findMany()
  res.json(users)
})

app.post('/api/users', async (req, res) => {
  const { name, email } = req.body
  const user = await prisma.user.create({
    data: { name, email }
  })
  res.status(201).json(user)
})

Project Structure for Larger Apps

bunway-api/
├── src/
│   ├── index.ts          # Entry point
│   ├── routes/
│   │   ├── users.ts      # User routes
│   │   └── posts.ts      # Post routes
│   ├── middleware/
│   │   ├── auth.ts       # Auth middleware
│   │   └── validate.ts   # Validation middleware
│   ├── services/
│   │   └── user.ts       # Business logic
│   └── types/
│       └── index.ts      # TypeScript types
├── package.json
└── tsconfig.json

Example route file (src/routes/users.ts):

import { bunway } from 'bunway'

const router = bunway.Router()

router.get('/', (req, res) => {
  // Get all users
})

router.get('/:id', (req, res) => {
  // Get user by ID
})

export default router

Mount in index.ts:

import userRoutes from './routes/users'

app.use('/api/users', userRoutes)

What's Next?

You now have a working REST API with:

CRUD operations
Request logging
CORS support
JSON parsing
Error handling

To go further:

Add a real database (Prisma, Drizzle, etc.)
Implement JWT authentication
Add request validation (Zod, etc.)
Write tests with bun test
Deploy to a server or serverless platform

Resources

bunWay Docs: bunway.jointops.dev
GitHub: github.com/JointOps/bunway
Bun Docs: bun.sh/docs

Questions? Drop a comment or open an issue on GitHub.

Tags: #bun #javascript #typescript #api #tutorial #backend #webdev #beginners

Rate Limiting in Node.js: The Complete Guide for Production APIs (2026)

Ali — Fri, 30 Jan 2026 17:26:03 +0000

TL;DR: Rate limiting protects your API from abuse and ensures fair usage. This guide covers algorithms, implementation patterns, distributed systems, and common pitfalls—with practical code examples.

Every production API needs rate limiting. Without it, a single bad actor (or a bug in a client) can take down your entire service. This guide covers everything you need to implement rate limiting correctly in Node.js.

Why Rate Limiting Matters

Rate limiting serves three purposes:

1. Protection Against Abuse

Bots, scrapers, and attackers can flood your API with requests. Rate limiting caps how much damage they can do.

2. Fair Resource Allocation

Without limits, one aggressive client can starve others. Rate limiting ensures everyone gets a fair share.

3. API Monetization

SaaS products use tiered rate limits to differentiate pricing tiers. Free users get 100 req/hour, paid users get 10,000.

Real Examples of What Goes Wrong

Twitter (2013): API abuse caused widespread outages. They introduced aggressive rate limiting.
GitHub: Rate limits all API calls. Unauthenticated: 60 req/hour. Authenticated: 5,000 req/hour.
Stripe: 100 read operations/sec, 25 write operations/sec per API key.

If these companies need rate limiting, so do you.

Rate Limiting Algorithms Explained

Three main algorithms power rate limiters. Each has tradeoffs.

Fixed Window

Divide time into fixed slots (0:00-1:00, 1:00-2:00). Count requests per slot. Reset count at slot boundary.

Window 1 (0:00-1:00): ████████░░ 80/100 ✓
Window 2 (1:00-2:00): ██████████ 100/100 ✓
Window 3 (2:00-3:00): ███░░░░░░░ 30/100 ✓

Pros:

Simple to implement
O(1) time and space complexity
Easy to understand and debug

Cons:

Burst at boundaries (100 at 0:59 + 100 at 1:01 = 200 in 2 seconds)

Best for: Most general-purpose APIs where exact precision isn't critical.

Sliding Window Log

Store the timestamp of every request. Count requests in the last N seconds.

Requests: [0:15, 0:22, 0:45, 0:58, 1:03, 1:15]
Window (last 60s at 1:20): [0:22, 0:45, 0:58, 1:03, 1:15] = 5 requests

Pros:

Precise rate limiting
No burst at boundaries
Smooth traffic shaping

Cons:

Memory grows with traffic (store every timestamp)
O(n) lookups
Not practical for high-traffic APIs

Best for: Low-traffic, precision-critical scenarios (billing, security).

Sliding Window Counter

Hybrid approach. Use weighted average of current and previous window counts.

Previous window (0:00-1:00): 80 requests
Current window (1:00-2:00): 30 requests so far
Time into current window: 20 seconds (33%)

Estimated count = (80 * 0.67) + 30 = 83.6 requests

Pros:

Smooths the burst problem
O(1) operations
Good accuracy without storing every timestamp

Cons:

Approximation, not exact
Slightly more complex to implement

Best for: High-traffic APIs needing smoother limiting than fixed window.

Token Bucket

Tokens added at fixed rate. Each request consumes one token. Requests denied when bucket empty.

Bucket capacity: 100 tokens
Refill rate: 10 tokens/second

Time 0: 100 tokens
Burst of 100 requests: 0 tokens
After 5 seconds: 50 tokens (refilled)

Pros:

Allows controlled bursts
Smooth rate limiting
Flexible configuration

Cons:

More complex to implement
Requires tracking token count and last refill time

Best for: APIs that want to allow short bursts while limiting sustained traffic.

Decision Tree

Need precision? → Sliding Window Log
High traffic + allow bursts? → Token Bucket
High traffic + simple? → Fixed Window
High traffic + smooth? → Sliding Window Counter

Most APIs? Start with Fixed Window. It's simple, fast, and good enough.

Implementing Rate Limiting in Node.js

The Naive Approach (Don't Do This)

// Don't do this in production
const requests = {}

app.use((req, res, next) => {
  const ip = req.ip
  const now = Date.now()

  if (!requests[ip]) {
    requests[ip] = { count: 1, startTime: now }
  } else if (now - requests[ip].startTime > 60000) {
    requests[ip] = { count: 1, startTime: now }
  } else {
    requests[ip].count++
  }

  if (requests[ip].count > 100) {
    return res.status(429).json({ error: 'Too many requests' })
  }

  next()
})

Problems:

Memory leak (entries never cleaned up)
No headers (clients don't know their limits)
No persistence (resets on server restart)
Race conditions in production

Using HitLimit (Recommended)

HitLimit handles all the edge cases:

import express from 'express'
import { hitlimit } from '@joint-ops/hitlimit'

const app = express()

// Zero-config: 100 requests per minute per IP
app.use(hitlimit())

// Or with custom limits
app.use(hitlimit({
  limit: 100,
  window: '15m',   // 15 minutes
  // Adds these headers to responses:
  // RateLimit-Limit: 100
  // RateLimit-Remaining: 95
  // RateLimit-Reset: 1706547600
}))

app.listen(3000)

Protecting Specific Routes

Don't rate limit everything equally. Health checks and static assets don't need limits. Auth endpoints need strict limits.

// Global default
app.use(hitlimit({ limit: 1000, window: '1h' }))

// Strict limit on login
app.use('/auth/login', hitlimit({
  limit: 5,
  window: '15m',
  // After 5 failed logins, wait 15 minutes
}))

// Strict limit on registration
app.use('/auth/register', hitlimit({
  limit: 3,
  window: '1h'
}))

// Skip health checks entirely
app.use(hitlimit({
  skip: (req) => req.path === '/health'
}))

Handling 429 Responses

When rate limited, return useful information:

app.use(hitlimit({
  limit: 100,
  window: '1h',
  response: (info) => ({
    error: 'RATE_LIMITED',
    message: 'Too many requests. Please slow down.',
    limit: info.limit,
    remaining: 0,
    resetAt: new Date(info.resetAt).toISOString(),
    retryAfter: info.resetIn  // seconds until reset
  })
}))

Clients receive:

{
  "error": "RATE_LIMITED",
  "message": "Too many requests. Please slow down.",
  "limit": 100,
  "remaining": 0,
  "resetAt": "2026-01-30T15:00:00.000Z",
  "retryAfter": 1847
}

Tiered Rate Limits

SaaS products need different limits for different users. HitLimit has this built-in:

app.use(hitlimit({
  tiers: {
    anonymous: { limit: 10, window: '1h' },
    free: { limit: 100, window: '1h' },
    pro: { limit: 5000, window: '1h' },
    enterprise: { limit: Infinity }
  },
  tier: (req) => {
    if (!req.user) return 'anonymous'
    return req.user.plan || 'free'
  }
}))

Now your API automatically applies the right limits based on user context.

Custom Rate Limit Keys

By default, rate limiting uses IP address. But IPs aren't always the right key:

Shared IPs: Corporate networks might share one IP for thousands of users
API keys: You want to limit by API key, not IP
User accounts: Logged-in users should be limited by user ID

app.use(hitlimit({
  key: (req) => {
    // 1. API key takes precedence
    if (req.headers['x-api-key']) {
      return `api:${req.headers['x-api-key']}`
    }

    // 2. Logged-in user ID
    if (req.user?.id) {
      return `user:${req.user.id}`
    }

    // 3. Fall back to IP
    return `ip:${req.ip}`
  }
}))

Distributed Rate Limiting

Single-server rate limiting is easy. Multiple servers is hard.

The Problem

You have 5 servers. Each has its own in-memory rate limiter set to 100 req/min.

Result? Users can make 500 req/min (100 per server).

Solution: Shared Store

Use Redis as a shared counter:

import { hitlimit } from '@joint-ops/hitlimit'
import { redisStore } from '@joint-ops/hitlimit/stores/redis'

app.use(hitlimit({
  limit: 100,
  window: '1m',
  store: redisStore({
    url: 'redis://localhost:6379',
    prefix: 'rl:'  // Key prefix in Redis
  })
}))

All servers increment the same counter. True distributed rate limiting.

Handling Redis Failures

Redis goes down. What happens?

Fail-closed: Reject all requests. Safe but your API stops working.

Fail-open: Allow all requests. Risky but service continues.

HitLimit lets you decide:

app.use(hitlimit({
  store: redisStore({ url: 'redis://localhost:6379' }),
  onStoreError: (error, req) => {
    console.error('Redis error:', error)

    // Protect critical routes even if Redis is down
    if (req.path.startsWith('/admin')) return 'deny'

    // Allow other traffic to continue
    return 'allow'
  }
}))

SQLite: Persistence Without Redis

Don't want to run Redis? SQLite gives you persistence without the ops overhead:

import { hitlimit } from '@joint-ops/hitlimit'
import { sqliteStore } from '@joint-ops/hitlimit/stores/sqlite'

app.use(hitlimit({
  store: sqliteStore({
    path: './rate-limits.db'  // File-based persistence
  })
}))

Good for single-server deployments where you want limits to survive restarts.

Common Pitfalls

1. Trusting X-Forwarded-For Blindly

Behind a proxy, req.ip might be wrong. But don't blindly trust X-Forwarded-For—it can be spoofed.

// Configure Express to trust your proxy
app.set('trust proxy', 1)  // Trust first proxy

// Or be specific about which proxies to trust
app.set('trust proxy', 'loopback, 10.0.0.0/8')

Only trust headers from proxies you control.

2. Not Handling Proxy Chains

Multiple proxies? The header looks like:

X-Forwarded-For: client, proxy1, proxy2

The leftmost IP is the client. But if you trust the wrong number of proxies, you'll rate limit the wrong IP.

3. Overly Strict Limits

Too strict = frustrated legitimate users. Start generous and tighten based on data:

// Start here
{ limit: 1000, window: '1h' }

// Tighten if you see abuse
{ limit: 500, window: '1h' }

// But monitor for false positives

4. Memory Leaks from Unbounded Stores

Custom in-memory stores must clean up old entries. Otherwise, memory grows forever.

HitLimit handles this automatically with setTimeout-based cleanup.

5. Not Rate Limiting Before Authentication

Attackers can brute-force login endpoints. Rate limit BEFORE authentication middleware:

// Good: Rate limit hits before auth check
app.use('/auth/login', hitlimit({ limit: 5, window: '15m' }))
app.post('/auth/login', authenticateUser)

// Bad: Auth runs first, then rate limit (attacker already hit your DB)
app.post('/auth/login', authenticateUser, hitlimit(...))

Testing Your Rate Limiter

Verify Limits Work

// test/rate-limit.test.js
import request from 'supertest'
import app from '../app.js'

it('blocks after limit exceeded', async () => {
  // Make 100 requests (the limit)
  for (let i = 0; i < 100; i++) {
    await request(app).get('/api/test')
  }

  // Request 101 should be blocked
  const response = await request(app).get('/api/test')
  expect(response.status).toBe(429)
})

Load Testing

Use tools like autocannon or k6:

npx autocannon -c 100 -d 30 http://localhost:3000/api/test

Watch for:

429 responses appearing at expected rates
Memory not growing unbounded
Response times staying consistent

Monitor in Production

Track these metrics:

429 response rate
Rate limit header values
Store latency (if using Redis)
Memory usage of rate limit store

Quick Start with HitLimit

Installation

npm install @joint-ops/hitlimit

Basic Setup

import express from 'express'
import { hitlimit } from '@joint-ops/hitlimit'

const app = express()

// Zero-config default: 100 req/min per IP
app.use(hitlimit())

// Your routes
app.get('/api/data', (req, res) => {
  res.json({ message: 'Hello!' })
})

app.listen(3000)

That's it. Your API is now rate limited with sensible defaults.

Summary

Rate limiting is essential for production APIs. The key decisions:

Algorithm: Start with fixed window. It's simple and works.
Limits: Start generous, tighten based on data.
Keys: IP for anonymous, user ID or API key for authenticated.
Distribution: Use Redis for multi-server. SQLite for single-server persistence.
Failures: Usually fail-open. Your API working matters more than perfect rate limiting.

HitLimit handles all of this in 7KB with zero configuration required.

DEV Community: Ali

Kubernetes + Node.js: Health Checks and Graceful Shutdown Done Right

How Kubernetes Terminates Pods

The SIGTERM Problem

Liveness vs Readiness Probes

Liveness Probe

Readiness Probe

The Keep-Alive Problem

The Race Condition

Complete Manual Implementation

The Zero-Config Way

Kubernetes Manifest

Common Kubernetes + Node.js Mistakes

1. No SIGTERM Handler

2. Liveness Depends on External Services

3. Readiness Doesn't Change on Shutdown

4. terminationGracePeriodSeconds Too Short

5. No preStop Hook

6. Using npm start in Dockerfile

Testing Graceful Shutdown

Local Testing

Kubernetes Testing

Quick Start with Kaput

Summary

Links

Building a REST API with bunWay in 10 Minutes

Prerequisites

Step 1: Project Setup

Step 2: Basic Server

Step 3: In-Memory Data Store

Step 4: CRUD Routes

Step 5: Error Handling

Complete Code

Testing the API

Bonus: Adding Authentication Middleware

Bonus: Rate Limiting

Bonus: Database Integration

Project Structure for Larger Apps

What's Next?

Resources

Rate Limiting in Node.js: The Complete Guide for Production APIs (2026)

Why Rate Limiting Matters

1. Protection Against Abuse

2. Fair Resource Allocation

3. API Monetization

Real Examples of What Goes Wrong

Rate Limiting Algorithms Explained

Fixed Window

Sliding Window Log

Sliding Window Counter

Token Bucket

Decision Tree

Implementing Rate Limiting in Node.js

The Naive Approach (Don't Do This)

Using HitLimit (Recommended)

Protecting Specific Routes

Handling 429 Responses

Tiered Rate Limits

Custom Rate Limit Keys

Distributed Rate Limiting

The Problem

Solution: Shared Store

Handling Redis Failures

SQLite: Persistence Without Redis

Common Pitfalls

1. Trusting X-Forwarded-For Blindly

2. Not Handling Proxy Chains

3. Overly Strict Limits

4. Memory Leaks from Unbounded Stores

5. Not Rate Limiting Before Authentication

Testing Your Rate Limiter

Verify Limits Work

Load Testing

Monitor in Production

Quick Start with HitLimit

Installation

Basic Setup

Summary

Links