DEV Community: Mindinu Ariyawansha

Why Your Production API Needs Idempotency Keys (And How to Build an Engine in Node.js & Redis)

Mindinu Ariyawansha — Sun, 20 Sep 2026 09:02:45 +0000

In a perfect network, every HTTP request arrives exactly once. In the real world, mobile clients drop connection mid-flight, timeouts hit load balancers, and frontend retry logic triggers duplicate operations.

If a user clicks "Pay Now" on a $100 checkout, their connection drops, and their app automatically retries the request 3 seconds later, what happens?

Without an Idempotency Engine, your API risks processing two charges for a single intent.

While GET, PUT, and DELETE methods are naturally idempotent by HTTP spec, POST endpoints (creating charges, generating invoices, triggering AI workflows) are inherently non-idempotent.

Here is how production systems guarantee exact-once execution semantics using Idempotency Keys.

How an Idempotency Engine Works

An idempotency key is a unique, client-generated identifier (usually a v4 UUID) sent in the HTTP header:

Idempotency-Key: 7b9e1d84-2a3c-4e89-9102-1a4f52e39a01

When the server receives a request with an idempotency key, it enters a state machine execution loop:

                  +-----------------------------------+
                  |   Incoming Request + Header Key   |
                  +-----------------------------------+
                                    |
                                    v
                       [ Check Redis Cache for Key ]
                                    |
                     +--------------+--------------+
                     |                             |
             (Key Exists?)                   (Key Missing?)
                     |                             |
          +----------+----------+                  v
          |                     |       [ Set Key State: "PROCESSING" ]
   (State: COMPLETE)   (State: PROCESSING)         |
          |                     |                  v
          v                     v       [ Execute Business Logic ]
   [ Return Saved ]      [ Return 409 ]            |
   [ HTTP Response ]     [ Conflict ]              v
                                        [ Save Response + State: "COMPLETE" ]

First Request: The server checks Redis for the key. Missing. It stores key: "PROCESSING" with a short TTL (e.g., 30 seconds) and executes the logic.
Concurrent Duplicate: If a second request arrives with the same key while the first is still processing, the server immediately rejects it with 409 Conflict or 429 Too Many Requests.
Completed Duplicate: Once the first request succeeds, the server caches the HTTP status code and response body in Redis under that key. Subsequent retries return the cached response instantly without re-executing any logic.

Production Middleware Implementation (Express + Redis)

Here is a clean, dependency-light middleware implementation in Node.js using Redis:

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

const redis = new Redis(process.env.REDIS_URL);
const IDEMPOTENCY_TTL = 86400; // 24 Hours in seconds

export const idempotencyMiddleware = async (
  req: Request, 
  res: Response, 
  next: NextFunction
) => {
  const key = req.header('Idempotency-Key');

  // Skip if client didn't supply a key (or enforce it for critical routes)
  if (!key) return next();

  const redisKey = `idempotency:${key}`;

  try {
    // Atomically set key if it doesn't exist (NX) with a lock timeout
    const acquired = await redis.set(redisKey, JSON.stringify({ state: 'PROCESSING' }), 'EX', 30, 'NX');

    if (!acquired) {
      const cachedData = await redis.get(redisKey);

      if (cachedData) {
        const parsed = JSON.parse(cachedData);
        if (parsed.state === 'PROCESSING') {
          return res.status(409).json({ error: 'Concurrent request in progress. Please wait.' });
        }
        // Return previously cached execution response
        return res.status(parsed.statusCode).json(parsed.body);
      }
    }

    // Intercept res.json to capture response payload before sending to client
    const originalJson = res.json.bind(res);
    res.json = (body: any) => {
      // Save execution result to Redis for future retries
      redis.set(
        redisKey, 
        JSON.stringify({ state: 'COMPLETE', statusCode: res.statusCode, body }), 
        'EX', 
        IDEMPOTENCY_TTL
      );
      return originalJson(body);
    };

    next();
  } catch (err) {
    next(err);
  }
};

Crucial Edge Cases to Consider

1. Request Payload Validation

What if a malicious actor sends the same Idempotency-Key with a completely different JSON payload?

Solution: Hash the request body alongside the key (SHA256(Key + Payload)). If the key matches but the payload hash differs, return 400 Bad Request.

2. Handling Hard Failures (5xx Server Errors)

If your database or downstream service crashes while processing a request, do not save a 500 error as a permanent idempotent response.

Delete the Redis key if the request throws an unhandled exception so the client can safely retry after your system recovers.

3. Distributed Lock Leaks

Always set an expiration TTL (e.g., 30 seconds) on the initial PROCESSING lock. If your API worker dies mid-execution, the key will naturally expire rather than permanently locking out the user from retrying.

Summary

Handling retries cleanly is the difference between a brittle prototype and enterprise-ready API infrastructure. By pushing idempotency tracking to a fast Redis layer, you protect your database from duplicate writes and give your client applications a bulletproof retry strategy.

How Eventual Consistency Breaks System Logic (And How to Handle It in Distributed Systems)

Mindinu Ariyawansha — Sat, 19 Sep 2026 12:31:59 +0000

When building distributed microservices, moving away from monolithic ACID transactions to eventual consistency is often touted as the ultimate cure for scalability bottlenecks. But eventual consistency introduces a silent killer: race conditions between data propagation and business rules.

In a single, unified database, a standard transaction guarantees immediate consistency. Once a write commits, every subsequent read sees that data.

In an eventually consistent, asynchronous architecture (e.g., using Kafka, DynamoDB, or PostgreSQL logical replication), there is a time window where different parts of your system hold conflicting truths.

Here is how eventual consistency breaks application logic—and the patterns senior engineers use to prevent data corruption.

The Phantom Inventory Problem (When Consistency Delays Kill UX)

Consider an e-commerce checkout pipeline split into two services:

Order Service: Creates a pending order.
Inventory Service: Decrements stock and confirms availability.

+---------------+     1. Write Order     +----------------------+
| Order Service | ---------------------> | Primary DB (Master)  |
+---------------+                        +----------------------+
        |                                           |
        | 2. Emit "OrderCreated" Event              | Async Replication
        v                                           v
+------------------+                     +----------------------+
| Event Message Bus|                     | Read Replica DB      |
+------------------+                     +----------------------+
        |                                           ^
        | 3. Process Async                          | 4. User refreshes
        v                                           |    page (Reads old state!)
+-------------------+                       +------------------+
| Inventory Service |                       | Web Client / App |
+-------------------+                       +------------------+

What Goes Wrong:

A user buys the last remaining item in stock.
The Order Service writes to the primary database and emits an OrderCreated event to a message queue.
The user is redirected to their "Order Confirmation" page.
The web client queries a Read Replica for order status.
The Trap: Because database replication has a 200ms lag, the Read Replica still shows $0$ orders and stock available. The UI shows "Order Failed" or allows a second user to purchase the same item.

This isn't a database crash—it's a consistency window failure.

3 Design Patterns to Fix Eventual Consistency Bugs

1. Read-Your-Own-Writes Consistency (Client-Side State Tracking)

Instead of relying on the backend read replicas immediately after a write operation, the host application maintains a short-lived local state or passes a session token (like a monotonic sequence ID or vector clock).

How it works: When the client performs a write, the API returns a version marker (version_id: 1042).
When fetching data, the client sends If-Match-Version: 1042.
If the read replica hasn't caught up to version 1042 yet, the API gateway routes the read request directly to the Primary/Leader Database instead of the lagging replica.

2. The Saga Pattern (Orchestration vs. Choreography)

Because you cannot execute a distributed transaction spanning multiple databases using traditional 2-Phase Commit (2PC) without crippling performance, you use a Saga.

A Saga executes a sequence of local transactions:

Transaction 1: Reserve inventory.
Transaction 2: Process payment.
Transaction 3: Confirm order.

If Transaction 2 (Payment) fails, the Saga Orchestrator triggers explicit Compensating Transactions in reverse order (e.g., executing Unreserve Inventory) to return the system to a clean, balanced state.

3. Idempotent Event Handlers

In asynchronous networks, messages get delayed, retried, and delivered out of order. An eventual consistency pipeline MUST assume every event will be delivered at least once and potentially out of sequence.

-- Bad: Non-idempotent update (Running twice doubles the discount)
UPDATE user_balances SET balance = balance - 10 WHERE user_id = 42;

-- Good: Idempotent state machine with explicit event tracking
INSERT INTO processed_events (event_id, processed_at) VALUES ('evt_9921', NOW());
UPDATE user_balances SET balance = balance - 10 WHERE user_id = 42 AND last_event_id != 'evt_9921';

Summary Checklist for Distributed System State

When designing async or multi-database features, ask these three questions before hitting production:

What happens if this message arrives 5 seconds late? (Will it overwrite newer data?)
What happens if this event executes twice? (Is the consumer strictly idempotent?)
Does the UI reflect speculative execution or read-replica lag? (Are you shielding the user from replica latency windows?)

Eventual consistency is necessary for high scale, but treating it like immediate consistency is the root cause of subtle, hard-to-reproduce production bugs!

Why Your Production Microservices Should Use Circuit Breakers (And How to Implement One in 50 Lines)

Mindinu Ariyawansha — Sat, 19 Sep 2026 05:59:46 +0000

If you are building distributed systems, network calls will fail. It’s not a matter of if, but when.

Whether it's an API rate limit, a transient database spike, or a downstream service deploying buggy code, external network calls are non-deterministic. The real problem isn't the single failed request—it's cascading failures.

When Service A synchronously calls Service B, and Service B begins hanging due to high latency, Service A runs out of available threads or memory waiting for responses. Suddenly, Service A crashes, taking down Service C, and dragging your entire infrastructure into a full outage.

This is where the Circuit Breaker Pattern becomes vital.

What is a Circuit Breaker?

Inspired by the electrical circuit breaker in your home that cuts power during a current overload, a software circuit breaker wraps an expensive or network-bound call and monitors for failures.

A circuit breaker operates in three distinct states:

         +--------------------------------------------+
         |                                            |
         v                                            |
   +-----------+   Failures > Threshold   +----------+ |
---|   CLOSED  |------------------------->|   OPEN   | | Success
   +-----------+                          +----------+ |
         ^                                     |       |
         |         Timeout Expired             |       |
         |      +-------------------+          |       |
         +------|     HALF-OPEN     |<---------+       |
                +-------------------+                  |
                          |                            |
                          +----------------------------+
                                   Failure

CLOSED (Normal Operation): All requests pass through to the downstream service. The breaker records successes and failures.
OPEN (Failing Fast): If the failure rate crosses a specified threshold within a time window, the circuit trips OPEN. All incoming requests immediately return a fallback error or cached data without actually making a network call.
HALF-OPEN (Testing the Waters): After a cooldown period, the breaker allows a limited number of test requests through. If they succeed, the circuit resets to CLOSED. If they fail, it trips back to OPEN.

Implementing a Minimal Circuit Breaker

Here is a lightweight, dependency-free implementation of a Circuit Breaker in Go (the exact same pattern applies in TypeScript, Python, or Java).


go
package main

import (
    "errors"
    "sync"
    "time"
)

type State int

const (
    StateClosed State = iota
    StateOpen
    StateHalfOpen
)

type CircuitBreaker struct {
    mu               sync.Mutex
    state            State
    failureThreshold int
    cooldown         time.Duration
    failures         int
    lastFailureTime  time.Time
}

func NewCircuitBreaker(threshold int, cooldown time.Duration) *CircuitBreaker {
    return &CircuitBreaker{
        state:            StateClosed,
        failureThreshold: threshold,
        cooldown:         cooldown,
    }
}

func (cb *CircuitBreaker) Execute(req func() error) error {
    cb.mu.Lock()

    // Check if OPEN circuit cooldown period has expired
    if cb.state == StateOpen {
        if time.Since(cb.lastFailureTime) > cb.cooldown {
            cb.state = StateHalfOpen
        } else {
            cb.mu.Unlock()
            return errors.New("circuit breaker is OPEN: fast-failing request")
        }
    }

    cb.mu.Unlock()

    // Execute actual network request
    err := req()

    cb.mu.Lock()
    defer cb.mu.Unlock()

    if err != nil {
        cb.failures++
        cb.lastFailureTime = time.Now()

        if cb.failures >= cb.failureThreshold {
            cb.state = StateOpen
        }
        return err
    }

    // Reset state on successful request
    if cb.state == StateHalfOpen || cb.state == StateClosed {
        cb.failures = 0
        cb.state = StateClosed
    }

    return nil
}

WebAssembly Beyond the Browser: Building a Sandboxed Plugin System in Node.js & Go

Mindinu Ariyawansha — Fri, 18 Sep 2026 16:35:15 +0000

For years, WebAssembly (WASM) was pitched primarily as a way to bring high-performance C++ or Rust graphics to the web browser. But in modern backend engineering, WASM’s most compelling application has shifted entirely: safe, near-native sandboxed plugin execution.

If you are building a system where third-party developers (or internal teams) need to execute custom logic—like webhook transformers, custom authorization rules, or pipeline data formatters—running untrusted code safely is a nightmare.

Traditional approaches come with heavy trade-offs:

eval() or Node vm module: Insecure. Process isolation is weak, memory leak-prone, and susceptible to prototype pollution or host system access.
Docker Containers / Micro-VMs (Firecracker): Maximum isolation, but massive overhead. Spin-up latency takes tens to hundreds of milliseconds, and memory consumption scales poorly.
Embedded JS Interpreters (V8 Isolate / QuickJS): Better, but locks your plugin authors into a single language ecosystem.

Enter WebAssembly on the Server. By embedding a lightweight WASM runtime (like Wasmtime or Extism) into your host application, you get isolated execution with near-zero cold starts (< 1ms) and predictable memory boundaries.

Here is a practical look at how server-side WASM sandboxing works and how to design a safe plugin host.

The WASM Sandbox Architecture

When executing a WASM plugin inside a host process, the WASM runtime creates an isolated instance with explicit memory bounds:

+-------------------------------------------------------------+
| HOST APPLICATION (Node.js / Go / Rust)                      |
|                                                             |
|   +-----------------------------------------------------+   |
|   | WASM RUNTIME INSTANCE (e.g., Wasmtime / Extism)     |   |
|   |                                                     |   |
|   |   - Linear Memory: Fixed Max Allocation (e.g. 16MB) |   |
|   |   - System Calls: DENIED by default                 |   |
|   |   - Disk / Network: Isolated / Whitelisted Host ABI |   |
|   |                                                     |   |
|   |   [ Plugin Code (Compiled from Rust/Go/Zig) ]       |   |
|   +-----------------------------------------------------+   |
|                                                             |
+-------------------------------------------------------------+

By default, a WASM module is deny-by-default:

It cannot read or write to the host file system.
It cannot open network sockets.
It cannot access the host machine’s memory outside its allocated linear memory block.

Designing the Host-Plugin Contract (ABI)

Because WASM natively only understands basic numeric types (i32, i64, f32, f64), passing complex data (like JSON strings or binary payloads) across the host-guest boundary requires an Application Binary Interface (ABI) convention.

Here is how data flows across the boundary:

Host Allocates Memory: The host writes the input payload (e.g., JSON bytes) directly into a segment of the WASM instance's linear memory.
Host Passes Pointers: The host calls the WASM exported function, passing the memory pointer and length as integer arguments.
Guest Processes Data: The plugin reads the memory segment, executes its transformation logic, and writes the output payload to another memory segment.
Guest Returns Pointer: The WASM function returns an integer pointer pointing to the result location in memory for the host to consume.

Practical Example: Embedding a WASM Plugin Host in Go

Using open-source frameworks like Extism or Wazero, setting up a host runtime takes less than 20 lines of code:

package main

import (
    "context"
    "fmt"
    "[github.com/extism/go-sdk](https://github.com/extism/go-sdk)"
)

func main() {
    ctx := context.Background()

    // 1. Configure memory bounds and plugin source
    manifest := extism.Manifest{
        Wasm: []extism.Wasm{
            extism.WasmFile{Path: "./plugins/transform_user_payload.wasm"},
        },
        Memory: &extism.ManifestMemory{
            MaxPages: 32, // Cap total memory at 2MB (64KB per page)
        },
    }

    // 2. Instantiate the sandboxed plugin
    plugin, err := extism.NewPlugin(ctx, manifest, extism.PluginConfig{}, nil)
    if err != nil {
        panic(err)
    }

    // 3. Call exported function with raw JSON payload
    inputJSON := []byte(`{"user_id": 1042, "raw_role": "admin_v2"}`)
    exitCode, output, err := plugin.Call("transform_data", inputJSON)

    if err != nil || exitCode != 0 {
        fmt.Printf("Plugin execution failed with exit code: %d\n", exitCode)
        return
    }

    fmt.Printf("Plugin Output: %s\n", string(output))
}

The Trade-Offs You Must Consider

While WASM-based plugin systems offer incredible performance and security benefits, they aren't a silver bullet:

1. The Garbage Collection Boundary

Languages with runtime GC (like Go or AssemblyScript) embed their GC engine into the compiled .wasm binary, increasing binary size. Languages like Rust, Zig, or C compile down to minimal WASM binaries (often under 100KB) and are far better suited for writing lightweight plugins.

2. Fuel & Execution Limits

A malicious or buggy plugin could contain an infinite loop: while(true) {}. To prevent CPU starvation, WASM runtimes use Fuel Consumption algorithms. The host assigns a fixed number of "fuel units" to a invocation. Every WASM instruction consumes fuel—when fuel runs out, the runtime instantly terminates the instance.

Key Takeaways

Sandboxing: WASM provides hardware-level memory boundaries without requiring full containerization.
Cold Start Speed: Instantiating a compiled WASM module takes microseconds compared to milliseconds/seconds for containers or V8 isolates.
Language Flexibility: Plugin authors can write in Rust, C, Go, Zig, or TypeScript (via AssemblyScript) as long as it targets wasm32-unknown-unknown or wasm32-wasi.

If you're architecting developer tools, workflow automation engines, or multi-tenant API gateways, embedding a WASM engine is one of the cleanest patterns available today for safe, high-throughput extensibility.

The Anatomy of a Slow Database Query: How to Diagnose, Deconstruct, and Fix It

Mindinu Ariyawansha — Mon, 14 Sep 2026 10:53:56 +0000

Every backend developer has experienced that sinking feeling: a user reports that a dashboard is loading slowly, you check the application logs, and you find a database query taking upwards of 3,000 milliseconds.

In a local environment with three rows of test data, everything ran instantaneously. But in production, with millions of rows, that single unoptimized query brings the entire application to its knees.

In this deep dive, we are going to dissect the anatomy of a slow database query. We will look at how relational databases process queries, how to read an execution plan, spot missing indexes, and optimize JOIN operations to get your response times back into the single-digit milliseconds.

1. The Lifecycle of a Query

When your application sends a SQL query to a database, it doesn't just scan the hard drive blindly. The database engine goes through a rigorous pipeline:

Parser & Translator: Validates syntax and checks if the tables and columns exist.
Rewriter: Optimizes the query structure logically (e.g., rewriting subqueries into joins).
Query Optimizer (The Brain): This is where the magic (or tragedy) happens. The optimizer analyzes statistical data about your tables and indexes to generate the Execution Plan—the cheapest, fastest path to retrieve the requested data.
Execution Engine: Executes the plan, fetching data from disk or buffer pool memory.

When a query is slow, 99% of the time it’s because the Query Optimizer chose a suboptimal execution plan, usually forced into doing so by missing indexes, outdated statistics, or poor query design.

2. Reading the Execution Plan (`EXPLAIN ANALYZE`)

Never guess why a query is slow. Always ask the database.

In PostgreSQL, MySQL, and SQLite, prefixing your query with EXPLAIN ANALYZE (or EXPLAIN depending on the flavor) tells the database to run the query and output the execution steps it took along with actual timing.

EXPLAIN ANALYZE 
SELECT users.id, users.email, orders.total 
FROM users 
JOIN orders ON users.id = orders.user_id 
WHERE orders.status = 'completed' AND orders.created_at > '2026-01-01';

When you look at the output, you want to hunt down two major red flags:

Red Flag A: The Sequential Scan (`Seq Scan`)

If you see a Seq Scan on a massive table, the database is reading every single row from disk from start to finish to check if it matches your WHERE clause. If your users table has 10 million rows, a sequential scan means reading 10 million rows, regardless of whether you only wanted 5 of them.

Red Flag B: High Cost and Actual Time Discrepancies

Execution plans show estimated costs and actual time. If the optimizer estimated 5 rows and got 500,000 rows, your table statistics are stale, leading the optimizer to choose a disastrously bad execution strategy (like a Nested Loop join instead of a Hash join).

3. The Culprit: Missing or Inefficient Indexes

Indexes are the primary weapon against slow queries. Think of an index like the index at the back of a textbook: instead of reading every page to find a keyword, you look up the word alphabetically and jump straight to the correct page.

The B-Tree Index Structure

Most databases use B-Trees by default. A B-Tree keeps data sorted and allows logarithmic time searches (O(log n)) rather than linear searches (O(n)).

The Trap: Leftmost Prefix Rule

Composite indexes (indexes on multiple columns) require care. If you create an index on (status, created_at, user_id), the database can use it if you query by status, or status AND created_at. However, if you query only by created_at, the index is completely ignored because the B-Tree requires the leftmost column to navigate.

-- GOOD: Uses the composite index on (status, created_at)
SELECT * FROM orders WHERE status = 'completed' AND created_at > '2026-01-01';

-- BAD: Bypasses the index because 'status' is skipped
SELECT * FROM orders WHERE created_at > '2026-01-01';

4. The Trap of Hidden Operations (Functions on Columns)

Look at this seemingly harmless query:

SELECT * FROM users WHERE EXTRACT(YEAR FROM created_at) = 2025;

Why is this slow? Because you wrapped the column created_at in a function (EXTRACT). The database can no longer use a standard B-Tree index built on created_at because it doesn't store the extracted year value—it stores the raw timestamp. To evaluate this, the database must evaluate the function on every single row (causing a Sequential Scan).

The Fix: SARGable Queries

Make your queries SARGable (Search Argument Able) by keeping columns bare:

-- GOOD: Allows the database to use an index on created_at
SELECT * FROM users 
WHERE created_at >= '2025-01-01 00:00:00' 
  AND created_at < '2026-01-01 00:00:00';

5. Anatomy of a Bad JOIN

Joins are notorious for performance bottlenecks when scaling. Consider this query connecting orders, items, and customers:

SELECT c.name, o.id, i.product_name 
FROM customers c
LEFT JOIN orders o ON c.id = o.customer_id
LEFT JOIN order_items oi ON o.id = oi.order_id
LEFT JOIN items i ON oi.item_id = i.id
WHERE c.country = 'Canada';

How Databases Handle Joins

Databases typically choose between three join algorithms:

Nested Loop: Good for small datasets or when the inner table is indexed on the join key. Terrible when both tables are massive.
Hash Join: The database builds an in-memory hash table of the smaller relation and probes it with the larger relation. Highly efficient for large unindexed sets.
Merge Join: Sorts both relations on the join key and merges them. Requires sorted inputs.

If your query is slow here, check:

Foreign Key Indexes: Are customer_id, order_id, and item_id indexed on their respective child tables? If not, the database may resort to nested loops with full table scans for every single row matched.
Filter Placement: Are you filtering (WHERE) after the join, or can you filter the dataset before performing the join to minimize rows flowing through memory?

Summary Checklist for Optimizing Queries

When you encounter a slow query in production, run through this quick mental checklist:

Run EXPLAIN ANALYZE to see what the database is actually doing (look for Seq Scan and high execution times).
Check for missing indexes on columns used in WHERE, JOIN ON, and ORDER BY clauses.
Ensure queries are SARGable—avoid wrapping columns in functions or operations.
Inspect table statistics (ANALYZE in Postgres/MySQL) to ensure the query optimizer isn't working with outdated assumptions.
Limit payload size—never use SELECT * if you only need two columns; reducing data width reduces disk I/O and network overhead.

Database performance optimization is an iterative engineering discipline. Master your execution plans, understand your indexes, and treat your database engine as a cooperative partner rather than a black box!

⚡ Stop Defaulting to WebSockets: Why Server-Sent Events (SSE) are Usually Better

Mindinu Ariyawansha — Fri, 04 Sep 2026 04:56:51 +0000

There is a moment in every web developer's career when a client asks: "Can we make this update in real time?"

Your mind immediately jumps to WebSockets. It is the industry buzzword. It sounds fast. You spin up socket.io or Reverb, spend two days fighting with your load balancer, and finally get it working.

But here is the harsh truth: for about 90% of modern web applications—including AI chat streaming, live dashboards, and notification feeds—WebSockets are massive overkill.

Instead, you should probably be using Server-Sent Events (SSE). Here is why SSE is often the cleaner, cheaper, and more pragmatic choice.

The Core Difference

Both WebSockets and SSE exist to push data from the server to the client without the client needing to constantly poll the server.

WebSockets create a full-duplex, persistent TCP connection. Both the client and the server can shout at each other simultaneously.
SSE is a unidirectional, HTTP-based stream. The server keeps a standard HTTP connection open and pushes text-based events down to the client.

Why WebSockets Are a Headache in Production

WebSockets are amazing for multiplayer games or collaborative tools like Google Docs where clients are constantly sending high-frequency data back to the server. But that power comes with a heavy infrastructure tax.

Stateful Scaling: WebSockets are stateful. If you scale horizontally, your load balancer needs connection-aware routing (sticky sessions) to ensure a client's subsequent messages go to the specific server holding their connection.
Proxy Nightmares: Aggressive corporate proxies and firewalls frequently drop WebSocket protocol upgrades, leaving connections in failure modes that are notoriously hard to debug.
Memory Hogs: Maintaining bidirectional frame buffers and tracking protocol state means every single WebSocket connection consumes significantly more server memory than an equivalent HTTP connection.
No Native Reconnect: If a WebSocket connection drops (and it will), the browser does not care. You have to write all the custom logic to detect the drop, backoff, retry, and resynchronize state.

Why SSE is the Underdog You Need

SSE leans on the mature, battle-tested HTTP ecosystem. It doesn't require a protocol upgrade, it doesn't need a custom server, and it works flawlessly with standard load balancers.

Native Auto-Reconnect: The EventSource API in the browser is brilliant. If the connection drops, the browser automatically attempts to reconnect on its own. It even sends a Last-Event-ID header so your server knows exactly where to resume the stream.
Standard HTTP Routing: Because SSE is just a long-lived HTTP request, it scales like any other HTTP endpoint.
Perfect for AI and Dashboards: If you are streaming an LLM response or pushing live price feeds to a dashboard, the client isn't sending data back through that channel (they just make a standard POST request to trigger the event). SSE perfectly models this server-push architecture.

Talk is Cheap. Look at the Code.

Here is how simple it is to implement SSE. No massive libraries, no custom protocols.

Backend (Node/Express):

app.get('/stream', (req, res) => {
  // 1. Set the headers to keep the connection open
  res.setHeader('Content-Type', 'text/event-stream');
  res.setHeader('Cache-Control', 'no-cache');
  res.setHeader('Connection', 'keep-alive');

  // 2. Push data whenever you want
  const intervalId = setInterval(() => {
    res.write(`data: ${JSON.stringify({ status: 'Processing...', time: Date.now() })}\n\n`);
  }, 1000);

  // 3. Clean up on disconnect
  req.on('close', () => {
    clearInterval(intervalId);
  });
});

Frontend (Vanilla JS):

// The browser handles connection, streaming, and auto-reconnecting!
const source = new EventSource('/stream');

source.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log("New update:", data);
};

The Decision Framework

WebSockets and SSE aren't competitors; they solve different shapes of problems.

Choose WebSockets if:

You are building a chat app, multiplayer game, or real-time collaborative canvas.
The client needs to push data to the server at high frequencies (10+ times per second).

Choose SSE if:

You are streaming AI responses, live notifications, news feeds, or financial tickers.
The communication is primarily one-way (Server → Client).
You want to avoid managing custom reconnections and complex load balancing.

Next time someone asks for real-time updates, don't immediately reach for the heaviest tool in the box. Give SSE a try.

Have you struggled with WebSocket scaling in production? Let's talk about it in the comments! 👇

🚨 3 PostgreSQL Anti-Patterns That Are Silently Killing Your App's Performance

Mindinu Ariyawansha — Thu, 03 Sep 2026 17:40:23 +0000

PostgreSQL is one of the most powerful relational databases on the planet. Out of the box, it can handle massive workloads. But as your application scales, the way you write queries and structure your schema matters more than the database engine itself.

If your app is starting to feel sluggish, it might not be a lack of resources. You might be falling into one of these three common PostgreSQL anti-patterns.

Here is how to spot them and how to fix them.

1. The `SELECT *` Trap (and why it ruins memory)

When we are iterating quickly, it is incredibly tempting to just write SELECT * FROM users and let the backend filter out the fields it doesn't need.

Why it’s an anti-pattern:
PostgreSQL has to read the data from the disk, load it into memory, and send it over the network to your application. If your users table has 30 columns (including heavy JSONB blobs or large TEXT fields) and you only need the id and email, you are forcing the database to do 10x the I/O work for no reason.

Furthermore, SELECT * breaks index-only scans. If you have an index on email, a query like SELECT email FROM users WHERE email = 'x' can be resolved purely from the index without even touching the main table. SELECT * forces Postgres to fetch the whole row.

The Fix:
Always explicitly define your columns, even if you are using an ORM.

-- ❌ Bad
SELECT * FROM orders WHERE status = 'pending';

-- ✅ Good
SELECT id, customer_id, total_amount FROM orders WHERE status = 'pending';

2. Over-Indexing (The "Just Add an Index" Fallacy)

When a query is slow, the immediate reaction is usually: "Let's just throw an index on that column!"

Why it’s an anti-pattern:
Indexes are not free. Every time you INSERT, UPDATE, or DELETE a row, PostgreSQL has to update the main table and every single index associated with that table. If you have a write-heavy table (like an event logger or analytics tracker) with 10 different indexes, your write latency will skyrocket.

Additionally, Postgres query planners are smart. If an index isn't highly selective (e.g., a boolean column like is_active where 95% of users are active), Postgres will likely ignore the index entirely and do a sequential scan anyway. You are paying the write penalty for an index that never gets used!

The Fix:

Periodically check for unused indexes. Postgres tracks this for you! You can run this query to find indexes that the database is ignoring:

SELECT relname, indexrelname, idx_scan 
FROM pg_catalog.pg_stat_user_indexes 
WHERE idx_scan = 0;

Drop unused indexes and lean into composite indexes for queries that frequently filter by the same multiple columns.

3. The ORM N+1 Query Disaster

If you are using Prisma, TypeORM, Hibernate, or Eloquent, you have probably written this exact bug without realizing it.

Why it’s an anti-pattern:
The N+1 problem occurs when your code fetches a list of records, and then loops through that list to fetch related data for each record.

// ❌ The N+1 Disaster in action
const users = await db.users.findMany(); // 1 query
for (const user of users) {
  // This runs a NEW query for every single user! (N queries)
  const posts = await db.posts.find({ authorId: user.id }); 
}

If you have 1,000 users, you just hit your database 1,001 times over the network for something that should have been a single round trip. This is the #1 cause of API latency.

The Fix:
Use JOINs or rely on your ORM's eager-loading capabilities to fetch everything in a single optimized query.

// ✅ Good: Fetches users and their posts in a single round trip
const usersWithPosts = await db.users.findMany({
  include: { posts: true }
});

Note: Under the hood, this translates to either a LEFT JOIN or exactly two queries (one for users, one for all posts matching those user IDs via an IN clause).

Summary

Scaling a database isn't just about throwing more RAM and CPU at your cloud provider. It is about respecting the network boundary, understanding your indexes, and keeping a close eye on the SQL your ORM is actually generating.

What is the worst database performance bug you've ever had to debug? Let me know in the comments! 👇

🛑 Stop Wasting API Calls: How to Build a Dead-Simple Caching Layer for AI Apps

Mindinu Ariyawansha — Thu, 03 Sep 2026 07:02:59 +0000

Building AI applications is incredibly fun right up until you check your API dashboard and realize you've been burning through credits by sending the exact same prompts during development and testing.

Whether you are using Claude, Gemini, or OpenAI, rate limits and latency are real bottlenecks. If you are building wrappers, agents, or generation tools, you need a caching layer.

Here is a highly effective, zero-dependency caching wrapper in TypeScript that you can drop into any project today.

The Concept

Instead of calling the LLM directly, we pass the prompt through a caching function. We hash the prompt (or use it as a key) and check if we already have a response stored. If yes, we return the cached string instantly. If no, we make the expensive network call, save the result, and return it.

The Code (TypeScript)

This uses a simple in-memory Map, which is perfect for local development or single-instance edge functions.


typescript
// Define an in-memory cache
const responseCache = new Map<string, string>();

async function fetchWithCache(prompt: string): Promise<string> {
  // 1. Check if we already have the exact prompt cached
  if (responseCache.has(prompt)) {
    console.log("⚡ Returning from Cache (0ms)");
    return responseCache.get(prompt)!;
  }

  // 2. If not, make the actual API call (using a generic fetch as an example)
  console.log("☁️ Fetching from API...");
  const response = await fetch("[https://api.your-llm-provider.com/v1/generate](https://api.your-llm-provider.com/v1/generate)", {
    method: "POST",
    headers: { "Authorization": `Bearer ${process.env.API_KEY}` },
    body: JSON.stringify({ prompt })
  });

  const data = await response.json();
  const textResult = data.choices[0].text;

  // 3. Store the result in the cache for next time
  responseCache.set(prompt, textResult);

  return textResult;
}

🔌 The 'USB-C of AI': Make Your Own MCP

Mindinu Ariyawansha — Wed, 02 Sep 2026 14:41:48 +0000

If you've been building AI-integrated apps recently, you know the pain: every single LLM, agent, and coding assistant needs a custom integration to read your database, check your GitHub repo, or pull Jira tickets. It's an endless cycle of writing custom API glue code.

Enter the Model Context Protocol (MCP).

Originally open-sourced by Anthropic, MCP is rapidly becoming the universal standard for how AI agents talk to data sources. It is quite literally the USB-C of the AI world.

Here is why MCP is completely changing the modern developer stack—and how you can start using it to turbocharge your workflow today.

🤔 What exactly is MCP?

In simple terms, MCP is an open standard that standardizes how AI models access external context. Instead of building a custom plugin for Claude, a different one for Cursor, and another for your custom Python agent, you build one MCP Server.

Any MCP-compatible client (like Claude Desktop, Cursor, or your own app) can instantly connect to that server and understand what tools and data are available.

The Architecture is simple:

MCP Hosts: The application the user interacts with (e.g., Claude Desktop, Cursor IDE).
MCP Clients: The protocol layer inside the host application that manages connections.
MCP Servers: Lightweight programs you run locally or in the cloud that expose your data (e.g., a local SQLite database, a GitHub repo, a Slack workspace).

🛠️ The 3 Core Primitives of MCP

When an AI connects to an MCP server, it gets access to three core primitives:

1. Resources (Read-only data)

Resources are like file systems for AI. They allow the LLM to read data without modifying it.

Example: Giving the AI read access to your local API documentation, system logs, or a Notion workspace.

2. Tools (Executable actions)

Tools are functions the LLM can call to actually do things. The server defines the required arguments, and the client prompts the user for permission before executing.

Example: execute_sql_query, create_github_issue, or restart_docker_container.

3. Prompts (Reusable templates)

Pre-defined prompt templates that help users get the most out of the connected data.

Example: A "Code Review" prompt that automatically pulls the current git diff and asks the LLM to review it against your company's style guide.

🚀 Why this matters for your workflow right now

You don't need to be building an AI startup to benefit from MCP. You can use it today to make your local dev environment incredibly powerful.

Imagine this workflow:
You are debugging an issue in Cursor. Instead of copying and pasting logs from your terminal, you spin up a local Postgres MCP Server and a Datadog MCP Server.

You simply ask your AI:

"Look at the recent 500 errors in Datadog, query the users table in my local Postgres to see if their accounts are active, and find the bug in my codebase."

Because the AI is connected to those MCP servers, it can autonomously fetch the logs, run the SQL query, and fix the code in one seamless interaction.

💻 Building your first MCP Server

Building a server is surprisingly easy. You can write them in TypeScript or Python. Here is the conceptual skeleton of exposing a simple database tool in TypeScript:


typescript
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

// 1. Initialize the server
const server = new McpServer({
  name: "Local-DB-Server",
  version: "1.0.0"
});

// 2. Add a Tool for the AI to use
server.tool(
  "query_users",
  "Run a search query against the local users database",
  { searchTerm: z.string() },
  async ({ searchTerm }) => {
    // Run your actual DB logic here
    const results = await mockDbSearch(searchTerm);
    return {
      content: [{ type: "text", text: JSON.stringify(results) }]
    };
  }
);

// 3. Start listening over standard I/O
const transport = new StdioServerTransport();
await server.connect(transport);

Scaling Multi-Agent Systems: Why Your Docker Container Keeps Crashing

Mindinu Ariyawansha — Wed, 02 Sep 2026 14:22:02 +0000

If you are building autonomous AI agents, you eventually hit a scaling wall. While developing Saturn AI, I noticed that pushing past five or six simultaneous agents caused the entire X11 Docker container to choke, API requests to time out, and the system to crash.

The issue was not the LLM API latency. It was OS process thrashing.

The Root Cause: Process Overhead and Disk I/O

When prototyping, it is common to rely on CLI wrappers to orchestrate agents. However, this introduces massive overhead. If six agents take a turn simultaneously, the backend spawns six heavy Node or Rust processes. If those agents invoke tools, they spawn additional child processes.

The container rapidly runs out of memory, IPC pipe bandwidth, and CPU threads. Furthermore, if these wrappers maintain state by constantly reading and writing JSON session files, the disk I/O locks up completely.

Three Architectural Fixes for Multi-Agent Stability

To resolve this and scale efficiently, you have to treat agent turns like asynchronous network requests rather than OS shell processes.

1. Implement Concurrency Queuing
If you cannot rewrite your engine immediately, introduce an asynchronous job queue using a library like p-queue. Cap the concurrency to two or three active processes at a time. When a trigger wakes up six agents, the queue allows the first few to execute while the others wait in memory. This eliminates CPU thrashing and keeps response times stable.

2. Shift to In-Process SDK Calls
The long-term fix is removing the CLI middleman entirely. Build a custom ReAct loop using a native framework directly inside your main event loop. By executing agent turns as standard asynchronous network calls to the LLM provider, you can run dozens of concurrent agents in a single instance without spawning external processes.

3. Use a Shared "Blackboard" Memory Model
Isolated JSON files for state management will bottleneck your disk. Transition to a shared state model stored directly in memory or a local Redis instance. All agents can instantly read and write their context, tasks, and tool outputs from this shared space. Additionally, boot a single persistent tool server on startup, and have all agents route through it via internal WebSockets, rather than each agent booting its own tool instances.

By shifting away from process-heavy wrappers toward lightweight, async architecture, you can scale multi-agent environments reliably without burning through compute resources.

I got into Batch0

Mindinu Ariyawansha — Tue, 01 Sep 2026 16:32:51 +0000

Hey DEV community! 👋

My name is Mindinu. I am 14 years old, based in Sri Lanka, and I am the founder of Luveo Technologies.

Today, I am super excited to announce a massive milestone for my journey: Luveo Technologies just got accepted into Batch 0!

For those who might not know, being part of a "Batch 0" cohort means you are in the inaugural, foundational group of an accelerator or incubator program. It’s the launchpad cohort. It means the mentors and organizers saw enough raw potential in the vision to take a bet on it from the very beginning.

And the product that got us here? Saturn AI.

🪐 What is Saturn AI?

Saturn AI is an autonomous AI employee.

You might have seen tools like OpenClaw or Viktor, but Saturn AI is being built to be better, faster, and much more deeply integrated into actual developer and business workflows. It’s not just a chatbot; it’s a self-improving AI environment that executes tasks natively.

Under the hood, here is what I am building:

Infrastructure: The entire platform is hosted on a Contabo private VPS, allowing us to manage our own cloud container orchestration without insane cloud fees.
Authentication: Seamless OAuth integration for secure and frictionless user onboarding.
Monetization: A fully custom tiered subscription model currently transitioning to Dodo Payments.
Tech Stack: I'm utilizing tools like ClaudeCode, Gemini CLI, OpenCode, Vite, Bun, and Cloudflare tunnels to build out a robust, scalable backend and a lightning-fast frontend.

🛠️ How I Will Participate in Batch 0

I am treating Batch 0 as a high-speed sprint. Over the course of the program, my goals are strictly technical and growth-focused:

Ship the MVP: Move Saturn AI from a complex local/cloud environment into a stable, user-ready product.
Stress-Test the AI: Push the autonomous agent capabilities to ensure it actually outperforms existing AI employee models in real-world coding and operational tasks.
Build in Public: I am going to document the entire process right here on DEV. Expect deep dives into my Docker configurations, how I manage my VPS, and how I handle the payment gateway architecture.

🚀 The Road Ahead

Building a SaaS product and running a startup at 14 isn't easy. I have to balance school, table tennis training, robotics competitions, and coding late into the night. But getting accepted into Batch 0 validates that the late nights are worth it.

I can't wait to share this journey with you all.

What is the hardest technical challenge you faced when building your first SaaS? Drop some advice for a young founder in the comments! 👇

If you want to follow the journey of Saturn AI, keep an eye on luveo.net and my personal portfolio mindinu.luveo.net.

DEV Community: Mindinu Ariyawansha

Why Your Production API Needs Idempotency Keys (And How to Build an Engine in Node.js & Redis)

How an Idempotency Engine Works

Production Middleware Implementation (Express + Redis)

Crucial Edge Cases to Consider

1. Request Payload Validation

2. Handling Hard Failures (5xx Server Errors)

3. Distributed Lock Leaks

Summary

How Eventual Consistency Breaks System Logic (And How to Handle It in Distributed Systems)

The Phantom Inventory Problem (When Consistency Delays Kill UX)

What Goes Wrong:

3 Design Patterns to Fix Eventual Consistency Bugs

1. Read-Your-Own-Writes Consistency (Client-Side State Tracking)

2. The Saga Pattern (Orchestration vs. Choreography)

3. Idempotent Event Handlers

Summary Checklist for Distributed System State

Why Your Production Microservices Should Use Circuit Breakers (And How to Implement One in 50 Lines)

What is a Circuit Breaker?

Implementing a Minimal Circuit Breaker

WebAssembly Beyond the Browser: Building a Sandboxed Plugin System in Node.js & Go

The WASM Sandbox Architecture

Designing the Host-Plugin Contract (ABI)

Practical Example: Embedding a WASM Plugin Host in Go

The Trade-Offs You Must Consider

1. The Garbage Collection Boundary

2. Fuel & Execution Limits

Key Takeaways

The Anatomy of a Slow Database Query: How to Diagnose, Deconstruct, and Fix It

1. The Lifecycle of a Query

2. Reading the Execution Plan (EXPLAIN ANALYZE)

Red Flag A: The Sequential Scan (Seq Scan)

Red Flag B: High Cost and Actual Time Discrepancies

3. The Culprit: Missing or Inefficient Indexes

The B-Tree Index Structure

The Trap: Leftmost Prefix Rule

4. The Trap of Hidden Operations (Functions on Columns)

The Fix: SARGable Queries

5. Anatomy of a Bad JOIN

How Databases Handle Joins

Summary Checklist for Optimizing Queries

⚡ Stop Defaulting to WebSockets: Why Server-Sent Events (SSE) are Usually Better

The Core Difference

Why WebSockets Are a Headache in Production

Why SSE is the Underdog You Need

Talk is Cheap. Look at the Code.

The Decision Framework

🚨 3 PostgreSQL Anti-Patterns That Are Silently Killing Your App's Performance

1. The SELECT * Trap (and why it ruins memory)

2. Over-Indexing (The "Just Add an Index" Fallacy)

3. The ORM N+1 Query Disaster

Summary

🛑 Stop Wasting API Calls: How to Build a Dead-Simple Caching Layer for AI Apps

The Concept

The Code (TypeScript)

🔌 The 'USB-C of AI': Make Your Own MCP

🤔 What exactly is MCP?

The Architecture is simple:

🛠️ The 3 Core Primitives of MCP

1. Resources (Read-only data)

2. Tools (Executable actions)

3. Prompts (Reusable templates)

🚀 Why this matters for your workflow right now

💻 Building your first MCP Server

Scaling Multi-Agent Systems: Why Your Docker Container Keeps Crashing

The Root Cause: Process Overhead and Disk I/O

Three Architectural Fixes for Multi-Agent Stability

I got into Batch0

🪐 What is Saturn AI?

🛠️ How I Will Participate in Batch 0

🚀 The Road Ahead

2. Reading the Execution Plan (`EXPLAIN ANALYZE`)

Red Flag A: The Sequential Scan (`Seq Scan`)

1. The `SELECT *` Trap (and why it ruins memory)