DEV Community: Rahul Mehta

Stop Defaulting to WebSockets: Why I Switched to SSE for Live Dashboards

Rahul Mehta — Mon, 26 Oct 2026 16:01:56 +0000

Stop Defaulting to WebSockets: Why I Switched to SSE for Live Dashboards

While building a dashboard with a Node.js backend, I needed to push live updates to the browser without requiring users to refresh the page. My initial assumption was that WebSockets were the obvious choice. In web development, WebSockets have practically become the default reflex whenever the term "real-time" comes up.

Once I started mapping out the actual requirements, that assumption fell apart. The dashboard was passive: the browser only needed to consume live metric updates from the server. It never needed to push messages back over that same stream. WebSockets introduced a stateful, bidirectional protocol when the underlying problem was strictly unidirectional.

Stepping back to compare WebSockets with Server-Sent Events (SSE) changed how I view real-time architecture: choosing a protocol depends on how data flows through your system, not merely on how often that data changes.

The Default Reflex: When Two-Way Communication Is Overkill

WebSockets establish a persistent, bidirectional TCP connection. Following an HTTP handshake, the connection upgrades to ws:// or wss://, allowing both the client and server to exchange data frames freely at any time.

That full-duplex setup makes sense for interactive applications like chat tools, shared whiteboards, or multiplayer games. But for a monitoring dashboard, the client is almost entirely a consumer. When a user changes a filter, shifts a date range, or adjusts a display setting, that interaction is standard request/response work that belongs in ordinary REST or GraphQL POST/PUT endpoints.

Using WebSockets solely for server-to-client streaming introduces maintenance trade-offs without leveraging the protocol's core feature:

You have to manage connection lifecycle events for both directions manually.
You leave the standard HTTP request/response paradigm, bypassing native caching, standard headers, and conventional status codes.
You often need custom ping/pong heartbeats to detect dead TCP connections.

If the browser never sends messages back over the socket, paying the operational and architectural cost of a bidirectional channel is unnecessary.

Protocol Mechanics: Unidirectional EventSource vs. WebSockets

Server-Sent Events (SSE) run on top of regular HTTP. The browser opens a standard HTTP request using the native EventSource API, specifying the text/event-stream MIME type. The server holds this connection open indefinitely and streams plain-text events using simple field prefixes (data:, event:, id:, and retry:).

event: metric-update
id: 1042
data: {"cpu": 42.1, "memory": 68.4}

Because SSE is standard HTTP, it fits cleanly into existing infrastructure:

Standard Infrastructure: It works out of the box with standard reverse proxies, load balancers, and API gateways without requiring protocol upgrade configurations (though proxy response buffering must be disabled, which is worth verifying in your deployment setup).
HTTP/2 Multiplexing: Under HTTP/1.1, browsers limit concurrent connections to six per domain. Over HTTP/2, an SSE stream shares a single TCP connection with normal API traffic, preventing connection starvation.
Native Browser Support: The browser's native EventSource interface manages disconnections, backoff timers, and reconnection attempts without external libraries.

Handling Disconnections, Reconnects, and Duplicate Updates

Handling edge cases during network drops is where SSE shows its practical advantages over bare WebSockets.

Automatic Reconnection

With raw WebSockets, if a connection drops due to a network hiccup or a server restart, you must write custom logic to detect the disconnect, instantiate a new connection, and implement exponential backoff so your backend doesn't get flooded.

With SSE, reconnection is part of the browser specification. If the stream closes unexpectedly, EventSource automatically attempts to reconnect. You can even tune the reconnect delay directly from the server by emitting a retry: <milliseconds> line in the stream.

Duplicate Message Prevention

A major challenge in any real-time stream is ensuring clients do not drop events or process duplicates when reconnecting.

SSE provides a built-in mechanism for this through event IDs:

The server tags each outgoing event with an id: value.
When the connection drops, the browser retains the last ID it processed.
Upon reconnecting, the browser automatically sends that ID in the Last-Event-ID HTTP header.
The server inspects req.headers['last-event-id'], retrieves any events that occurred after that ID, and streams the missed backlog before continuing with live data.

To achieve this over WebSockets, you have to design and maintain your own message sequence tracking, acknowledgment handshakes, and replay buffers on both client and server.

Implementation Comparison in Node.js

Here is how minimal implementations compare when pushing periodic dashboard metrics to a browser.

Server-Sent Events (Native Node.js HTTP)

SSE requires no third-party socket packages on either the server or client.

// server.js
import http from 'node:http';

const server = http.createServer((req, res) => {
  if (req.url === '/api/metrics-stream') {
    // SSE headers
    res.writeHead(200, {
      'Content-Type': 'text/event-stream',
      'Cache-Control': 'no-cache',
      'Connection': 'keep-alive',
    });

    // Read the client's last seen event ID to prevent duplicate/missed data
    const lastEventId = req.headers['last-event-id'];
    if (lastEventId) {
      // In production: fetch and write missing items starting after lastEventId
    }

    // Send an update every 3 seconds
    const interval = setInterval(() => {
      const id = Date.now();
      const data = JSON.stringify({ memoryUsage: process.memoryUsage().heapUsed });

      res.write(`id: ${id}\n`);
      res.write(`event: dashboard-metrics\n`);
      res.write(`data: ${data}\n\n`);
    }, 3000);

    // Clean up when client disconnects
    req.on('close', () => {
      clearInterval(interval);
      res.end();
    });
  } else {
    res.writeHead(404);
    res.end();
  }
});

server.listen(3000);

On the frontend, the native browser API handles everything:

// client.js
const stream = new EventSource('/api/metrics-stream');

stream.addEventListener('dashboard-metrics', (event) => {
  const metrics = JSON.parse(event.data);
  console.log('Received live metrics:', metrics);
});

stream.onerror = (err) => {
  // EventSource will automatically retry connecting;
  // log errors here if needed for monitoring.
  console.error('SSE connection error:', err);
};

The WebSocket Equivalent

To achieve the same passive dashboard feed with WebSockets, you typically bring in a library like ws and manage the handshake and reconnection yourself:

// server-ws.js
import { WebSocketServer } from 'ws';

const wss = new WebSocketServer({ port: 3001 });

wss.on('connection', (ws) => {
  const interval = setInterval(() => {
    if (ws.readyState === ws.OPEN) {
      ws.send(JSON.stringify({
        type: 'dashboard-metrics',
        data: { memoryUsage: process.memoryUsage().heapUsed },
        timestamp: Date.now()
      }));
    }
  }, 3000);

  ws.on('close', () => {
    clearInterval(interval);
  });
});

And on the client:

// client-ws.js
let socket;

function connect() {
  socket = new WebSocket('ws://localhost:3001');

  socket.onmessage = (event) => {
    const payload = JSON.parse(event.data);
    console.log('Received live metrics:', payload.data);
  };

  socket.onclose = () => {
    // WebSockets do not auto-reconnect. You must implement backoff manually.
    setTimeout(connect, 3000);
  };

  socket.onerror = (err) => {
    socket.close();
  };
}

connect();

Even in a basic implementation, the WebSocket client must supply its own reconnection flow, and neither side has a standardized convention for synchronizing dropped messages.

Practical Decision Matrix: Choosing Based on Data Flow

Choosing a real-time transport is an architectural decision about communication direction, not raw speed.

Requirement	Recommended Protocol	Why
Passive metrics / live dashboards	SSE	One-way streaming, native HTTP, built-in reconnection, standard proxy traversal.
Notifications & alert feeds	SSE	Server-to-client events with native `Last-Event-ID` tracking for delivery recovery.
Collaborative editing (Docs, Canvas)	WebSockets	Continuous, low-latency bidirectional message passing between clients and server.
Chat applications	WebSockets	High-frequency client-to-server messaging where framing overhead matters.
Binary streaming (Audio/Video calls)	WebSockets / WebRTC	SSE is text-based (UTF-8). Binary payloads must be Base64-encoded, causing size overhead.

Conclusion

Real-time web applications do not always need bidirectional pipes. If your application's data flow is one-directional from the server down to the browser defaulting to WebSockets adds connection maintenance and custom reconnection logic without delivering extra utility.

Before wiring up a WebSocket server for your next live feed or dashboard, evaluate the direction of your data. If the client is only listening, Server-Sent Events offer a simpler, HTTP-native alternative that solves reconnection and recovery right out of the box.

Designing Idempotent Payment Jobs: Preventing Double Charges Across Worker Retries

Rahul Mehta — Sun, 11 Oct 2026 18:55:21 +0000

Designing Idempotent Payment Jobs: Preventing Double Charges Across Worker Retries

A background worker dispatches a charge request to a payment gateway. The gateway processes the transaction, debits the customer's card, and prepares the response. Just before the HTTP 200 payload reaches the application server, a transient socket timeout cuts the connection.

The worker catches a connection reset error. From the application's perspective, the operation failed. Because background processing systems like BullMQ, Sidekiq, and Celery make retries as simple as setting attempts: 3, the job re-queues. Thirty seconds later, a second worker picks up the job, sends a brand-new charge request, and bills the customer a second time.

Turning on default retry policies for jobs that execute network calls against external financial APIs creates immediate liability. Database transactions cannot roll back operations across an HTTP boundary. Preventing duplicate charges requires explicit state modeling, deterministic idempotency keys, and defensive retry logic.

The In-Flight Failure: Why ACID Guarantees Stop at the Network Boundary

In a local relational database, atomicity is guaranteed:

BEGIN;
UPDATE accounts SET balance = balance - 100 WHERE id = 1;
UPDATE accounts SET balance = balance + 100 WHERE id = 2;
COMMIT;

If the server crashes midway, the transaction aborts and state rolls back cleanly.

When communicating with external third-party APIs (Stripe, Adyen, PayPal), this boundary disappears. An HTTP request has three distinct failure modes:

Pre-flight failure: The request drops before reaching the gateway. No charge occurs.
Mid-flight failure: The gateway receives the request, charges the payment method, but crashes before replying.
Post-flight failure: The gateway succeeds and replies, but a network hop drops the response packet, or the client worker crashes before writing the success state to the local database.

Because modes 1, 2, and 3 often produce identical client-side errors (such as ECONNRESET, ETIMEDOUT, or 504 Gateway Timeout), the worker cannot infer what happened on the provider's side from the network exception alone.

Generating Deterministic Idempotency Keys at the Domain Layer

Most modern payment APIs support an Idempotency-Key header. If the gateway receives two requests bearing the exact same key within a specific window (usually 24 hours), it executes the charge once and returns the cached response for any subsequent calls.

A common pitfall is generating this key inside the worker handler:

// ANTI-PATTERN: Generates a new key on every retry attempt
async function processPayment(job: Job) {
  const idempotencyKey = crypto.randomUUID();
  await paymentGateway.charge({
    amount: job.data.amount,
    idempotencyKey,
  });
}

If the worker times out and retries, crypto.randomUUID() generates a new key. The gateway treats the retry as an intentional secondary payment, rendering the gateway's duplicate protection useless.

Idempotency keys must be deterministic or pre-generated during the domain event that initiated the checkout.

Option 1: Persisted Key

Create the key when inserting the initial order or payment record into the primary database:

CREATE TABLE payments (
    id UUID PRIMARY KEY,
    order_id UUID NOT NULL REFERENCES orders(id),
    amount_cents INT NOT NULL,
    status VARCHAR(32) NOT NULL,
    idempotency_key UUID NOT NULL UNIQUE,
    provider_charge_id VARCHAR(255),
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

Option 2: Deterministic Derivation

Derive the key deterministically using immutable business identifiers:

import { createHash } from 'node:crypto';

function generatePaymentKey(orderId: string, attemptNumber: number): string {
  return createHash('sha256')
    .update(`checkout:${orderId}:attempt:${attemptNumber}`)
    .digest('hex');
}

If the job retries, it passes the identical idempotency key to the provider.

Modeling Payment States: Explicit Transitions

Boolean flags like is_paid: false provide insufficient context during asynchronous processing. A payment record requires explicit lifecycle states to ensure workers do not double-process records that are already in flight.

[ PENDING ] ---> [ PROCESSING ] ---> [ SUCCEEDED ]
                        |
                        +-----------> [ REQUIRES_ACTION / FAILED ]

PENDING: The intent is saved. No outgoing network request has succeeded or timed out.
PROCESSING: A worker has claimed the record. An HTTP request is either in-flight or awaiting reconciliation.
SUCCEEDED: The provider confirmed the funds were captured, and the external identifier is safely stored.
FAILED: The card was declined or definitively rejected by the provider.

When a worker starts, it must acquire the job by transitioning the row from PENDING to PROCESSING atomically.

UPDATE payments
SET status = 'PROCESSING'
WHERE id = $1 AND status = 'PENDING'
RETURNING id;

If the query returns zero rows, another worker is either actively handling the payment or it has already finished. The current worker should exit immediately.

Handling Unclear Timeout Responses: Verify Before Resubmission

When a network timeout occurs, the worker should not immediately throw an error and let the queue hammer the endpoint again. Instead, it must confirm the state with the gateway.

Many providers offer a retrieval endpoint where transactions can be looked up by their idempotency key or client reference ID:

Catch the timeout exception.
Query the provider: gateway.payments.retrieve({ idempotencyKey }).
If the payment exists and succeeded, update the local database to SUCCEEDED and exit cleanly.
If the provider has no record of the transaction, safe re-dispatch can proceed.
If the provider also returns a 5xx or times out on lookup, mark the local payment record as REQUIRES_RECONCILIATION and defer the job to an exponential backoff queue.

Structuring the Worker Handler

Below is a complete implementation of a worker handler using Node.js, an SQL client, and an external payment gateway.

import { Job } from 'bullmq';
import { db } from './database';
import { paymentGateway, GatewayTimeoutError } from './paymentGateway';

interface PaymentJobData {
  paymentId: string;
}

export async function paymentWorkerHandler(job: Job<PaymentJobData>) {
  const { paymentId } = job.data;

  // 1. Fetch the payment record
  const payment = await db.query(
    'SELECT id, amount_cents, status, idempotency_key FROM payments WHERE id = $1',
    [paymentId]
  );

  if (!payment) {
    throw new Error(`Payment ${paymentId} not found`);
  }

  // 2. Short-circuit if already processed (Idempotent locally)
  if (payment.status === 'SUCCEEDED') {
    return { status: 'already_completed' };
  }

  // 3. Prevent duplicate concurrent execution
  if (payment.status === 'PENDING') {
    const updated = await db.query(
      `UPDATE payments 
       SET status = 'PROCESSING' 
       WHERE id = $1 AND status = 'PENDING' 
       RETURNING id`,
      [paymentId]
    );

    if (updated.rowCount === 0) {
      // Another worker claimed the record
      return { status: 'concurrent_lock_miss' };
    }
  }

  // 4. Dispatch to external gateway using the persisted idempotency key
  try {
    const result = await paymentGateway.createCharge({
      amount: payment.amount_cents,
      currency: 'usd',
      idempotencyKey: payment.idempotency_key,
    });

    // 5. Update local state to SUCCEEDED inside a local transaction
    await db.query(
      `UPDATE payments 
       SET status = 'SUCCEEDED', 
           provider_charge_id = $1, 
           updated_at = NOW() 
       WHERE id = $2`,
      [result.chargeId, paymentId]
    );

    return { status: 'success', chargeId: result.chargeId };
  } catch (error) {
    if (error instanceof GatewayTimeoutError) {
      // 6. Ambiguous state: Reconcile before blindly failing
      const existingCharge = await paymentGateway.lookupByIdempotencyKey(
        payment.idempotency_key
      );

      if (existingCharge && existingCharge.status === 'paid') {
        await db.query(
          `UPDATE payments 
           SET status = 'SUCCEEDED', 
               provider_charge_id = $1 
           WHERE id = $2`,
          [existingCharge.id, paymentId]
        );
        return { status: 'reconciled_after_timeout' };
      }
    }

    // Allow BullMQ/Sidekiq to retry using configured backoff
    throw error;
  }
}

Safe Retry Checklist

Before turning on worker retries for any transactional integration:

Stable Keys: Ensure the idempotency key is tied to the persistent entity, not the individual worker lifecycle.
State Pre-Checks: Always check whether the job has already been fulfilled prior to issuing an API call.
Atomic State Transitions: Guard worker execution using conditional database updates to ensure only one worker processes an intent at any given time.
Structured Error Handling: Treat network timeouts as ambiguous states requiring inquiry, rather than automatic failures.

Why Your Next.js Route Handlers Exhaust Postgres Connections (and How to Fix It)

Rahul Mehta — Wed, 07 Oct 2026 23:10:21 +0000

Why Your Next.js Route Handlers Exhaust Postgres Connections (and How to Fix It)

Everything worked in local development. When I built out my Next.js API routes, I initialized the PostgreSQL connection directly inside the route handler, tested it against my local database, and saw fast, clean responses. There was no indication that anything was wrong.

Then I deployed the application to a serverless environment. Under relatively low traffic, the logs started lighting up with intermittent database connection errors. The queries were simple, the data volume was modest, and the traffic was far from a spike. Yet the database was repeatedly refusing connections.

Here is why instantiating connections inside your Route Handlers breaks down in serverless environments, and how to restructure your database client to handle ephemeral execution.

The Localhost Trap: Why In-Handler Connections Pass in Dev

When running Next.js locally via next dev, you are operating inside a single long-lived Node.js runtime. When you write something like this inside an API route:

// app/api/data/route.ts (Anti-pattern)
import { NextResponse } from 'next/server';
import { Pool } from 'pg';

export async function GET() {
  // Initializing the pool inside the handler scope
  const pool = new Pool({
    connectionString: process.env.DATABASE_URL,
  });

  const client = await pool.connect();
  try {
    const result = await client.query('SELECT NOW()');
    return NextResponse.json(result.rows);
  } finally {
    client.release();
    // Even if you call pool.end() here, each call incurs handshake latency
  }
}

Locally, your requests arrive sequentially from a single browser session. Even if you spin up connections inside the request handler, the low volume rarely reaches the connection cap of a local Postgres instance (which typically defaults to 100 connections).

Because the local runtime masks connection pressure, the code looks production-ready. In reality, it leaks connections or churns through TLS and TCP handshakes on every single invocation.

Tracing the Failure: Serverless Execution Contexts

Serverless platforms (such as Vercel or AWS Lambda) do not run a single persistent Node.js server. Instead, they spin up multiple isolated container instances based on incoming request spikes.

When an API route is invoked:

Cold Start: The platform launches an execution container, boots the Node.js runtime, and runs your handler code.
Execution: Your handler opens a pool or client, binds to a Postgres socket, runs the query, and returns the response.
Pause/Freeze: After the handler returns, the runtime environment may be immediately frozen. If the connection pool has active background sockets or idle connections, they remain open on the database server until Postgres times them out.
Concurrent Requests: If multiple requests arrive concurrently, the serverless platform spins up sibling containers. Each container executes the route handler and initializes its own brand-new set of connections.

Because PostgreSQL allocates a separate OS process for every incoming client connection, connections are expensive. If 20 concurrent serverless containers spin up, and each handler instantiates a pool or fails to clean up active connections, you can burn through your database connection budget almost instantly—even with small traffic numbers.

Fixing the Client: Implementing a Shared Connection Singleton

To prevent handlers from creating new connection pools on every call, move the database initialization out of the route handler's function body and into module scope.

When a serverless container stays "warm" to serve consecutive requests, module-level variables are preserved across invocations. To handle local development hot-reloading (which can repeatedly evaluate modules and spawn stray pools), attach the instance to globalThis.

// lib/db.ts
import { Pool } from 'pg';

const globalForDb = globalThis as unknown as {
  connPool: Pool | undefined;
};

export const pool =
  globalForDb.connPool ??
  new Pool({
    connectionString: process.env.DATABASE_URL,
    // Restrict the maximum connections per serverless container
    max: 1,
    idleTimeoutMillis: 10000,
    connectionTimeoutMillis: 5000,
  });

if (process.env.NODE_ENV !== 'production') {
  globalForDb.connPool = pool;
}

Now, consume the singleton in your Route Handler:

// app/api/data/route.ts
import { NextResponse } from 'next/server';
import { pool } from '@/lib/db';

export async function GET() {
  const client = await pool.connect();
  try {
    const result = await client.query('SELECT NOW()');
    return NextResponse.json(result.rows);
  } finally {
    client.release();
  }
}

With this pattern, warm serverless containers reuse existing database sockets instead of performing a fresh handshake on every single request.

Setting Connection Pool Limits for Serverless Concurrency

In a traditional Express or Fastify server, setting a pool size of 10 or 20 connections per server instance makes sense because you only run a few long-lived instances.

In a serverless environment, that math inverts. If you configure max: 10, and your platform scales to 15 concurrent container instances, your app will attempt to open up to 150 connections to PostgreSQL. If your database tier has a limit of 100 connections, requests will start failing immediately with connection refused or timeout errors.

When running Postgres drivers directly inside serverless functions:

Keep the pool size small: Set max: 1 or max: 2 per function instance. Because a single serverless Node.js instance usually handles requests sequentially or with very low intra-container concurrency, a single connection is usually sufficient.
Lower the idle timeout: Set idleTimeoutMillis low (such as 10 to 15 seconds) so that Postgres closes connections when a container goes idle rather than holding them open indefinitely.

Scaling Past Node Memory: Introducing PgBouncer

Limiting each container to one connection helps, but it does not solve high concurrency. If 200 users hit your endpoint at the exact same moment, the serverless provider will spin up 200 instances, immediately demanding 200 distinct Postgres connections.

Traditional relational databases are not designed to handle thousands of short-lived connections. This is where external connection poolers—most commonly PgBouncer—become necessary.

[ Next.js Serverless Container 1 ] --\
[ Next.js Serverless Container 2 ] ---> [ PgBouncer (Pooler) ] ---> [ PostgreSQL ]
[ Next.js Serverless Container N ] --/

PgBouncer sits between your serverless functions and PostgreSQL. It maintains a small, fixed pool of actual connections to Postgres while accepting hundreds or thousands of incoming connections from ephemeral clients.

When configuring a pooler for serverless functions, ensure you use Transaction Pooling: connections are returned to the pool the millisecond a query or transaction finishes, allowing a tiny pool of database connections to serve a massive fleet of serverless handlers.

(Note: If your database provider offers a managed connection pooling endpoint, verify whether it uses transaction pooling or session pooling before pointing your DATABASE_URL to it).

Production Checklist for Serverless Relational Connections

Check handler scopes: Ensure no database clients (Client or Pool) are instantiated inside the body of GET, POST, or other route methods.
Use global singletons: Cache the database client across warm serverless invocations and dev hot-reloads using module scope or globalThis.
Cap client pool size: Lower max connection settings to 1 or 2 per container to avoid accidental connection multiplication during sudden bursts.
Adopt external pooling: Use an intermediate pooler like PgBouncer or a hosted connection pooler to shield Postgres from container scaling spikes.
Tune timeouts: Ensure connection timeouts fail fast rather than hanging the serverless function until it hits the runtime execution limit.