Accelerating Global CDN Cache Invalidation in Node.js with Custom C++ N-API Addons

Praise Aribisala — Tue, 07 Apr 2026 16:08:50 +0000

You've pushed a critical content fix (wrong pricing, bad image, outdated copy) and the origin server is clean. Yet, 83 of your 100 edge nodes are still serving stale data to users. Your cache invalidation job ran and reported success, but the fixes aren't propagating correctly. This isn't a problem with your business logic. It's a failure in how your cache invalidation system calculates propagation order. When your edge nodes form a tiered, parent-child topology, purging the child node before the parent node leads to the child immediately re-fetching and re-caching the same stale content downstream. The root cause was an expensive, synchronous graph traversal in JavaScript to compute the correct invalidation order. Running Dijkstra's algorithm against a graph of 100 weighted nodes on the main thread was costing 40–60ms per purge cycle. Under concurrent load, the Node.js Event Loop choked, leading to job queuing, out-of-order execution, and ultimately, incorrect cache propagation. This article details the surgical fix: we pulled the graph traversal entirely out of JavaScript and implemented it as a native C++ N-API addon, reducing the computation time to under 1ms regardless of graph size.
The Problem: What CDN Cache Invalidation Actually Is
A CDN (Content Delivery Network) works by caching your origin server's responses at multiple edge locations around the world: nodes in data centers in Lagos, Frankfurt, Singapore, So Paulo. When a user in London requests your homepage, they hit the London edge node, not your origin server in us-east-1. That's the whole point: low latency, reduced origin load.
The problem is staleness. When your content changes, every edge node that has cached the old version needs to be told to throw it away. That process is cache invalidation — or in CDN terminology, a purge.
At small scale, you send a purge signal to all nodes simultaneously and you're done. But in a real production CDN with 100+ edge nodes, there's a structure to how those nodes relate to each other. Many CDN architectures use a tiered caching model; a set of shield nodes (also called parent or mid-tier nodes) sit between your origin and the outer edge nodes. An edge node in a smaller market doesn't pull directly from origin it pulls from its assigned shield node. That shield node is its upstream parent.
This parent-child relationship forms a directed graph. And when you invalidate cache, the order in which you send purge signals through that graph matters.
If you invalidate a child edge node before its parent shield node has been purged, the child will simply re-fetch from the parent and re-populate its cache with the same stale content. You've wasted the purge. The correct order is a topological traversal: parents before children, propagated level by level through the graph, respecting edge weights that represent propagation latency between nodes.
Computing that traversal correctly and fast, across a graph that can have hundreds of nodes and thousands of edges, is the core problem this article solves.
Why Pure JavaScript Fails Here
The honest answer is: JavaScript can do graph traversal. BFS and Dijkstra's algorithm are well-understood and trivially implementable in JS. For a graph of 20 nodes, you won't feel any pain.
The problem shows up at scale, under load, in the wrong place.
Node.js runs your application code on a single thread: the Event Loop. Everything your app does (handling HTTP requests, running timers, executing promises) all of it runs on that one thread. Node.js is designed around the assumption that JavaScript execution is fast and non-blocking, and that slow work (I/O, disk, network) gets handed off to libuv's thread pool.
Graph traversal is neither I/O nor a native operation. It's pure CPU computation: a tight loop of queue operations, edge relaxations, and comparisons. And it runs entirely on the Event Loop thread.
Here's what that means in practice. We benchmarked a JavaScript implementation of Dijkstra's shortest-path algorithm against a 500-node, 2000-edge weighted directed graph, which is a realistic size for a mid-to-large CDN topology:

47ms of blocked Event Loop means every incoming HTTP request during that window is queued and waiting. In a system that also handles concurrent purge bursts (say, 10 purge jobs firing simultaneously during a deployment) you're stacking 470ms of blocking computation on a single thread. At that point, your Node.js process isn't slow; it's effectively frozen.
The V8 engine will JIT-compile your traversal function after a few runs, which helps. But V8's JIT is optimized for object-heavy, dynamic JavaScript patterns, not cache-efficient tight loops over integer arrays. A C++ implementation of the same algorithm running on contiguous memory with no GC overhead and no dynamic dispatch is not slightly faster; it operates in a fundamentally different performance class.
The fix is not to rewrite your entire service in C++. The fix is surgical: identify the one computation that doesn't belong on the Event Loop, extract it, compile it as a native addon, and call it from Node.js as if it were any other async function. That's exactly what N-API is built for.
The Architecture — How the Pieces Fit Together
Before touching any code, here's the full picture of what we're building:

Three distinct layers:
The Purge Orchestrator is a Node.js module that receives a purge request (a URL pattern, a cache tag, or a path prefix) and loads the current edge topology from a config store. In our demo, this is a JSON file, but in production, this would come from a Redis cache or a topology service. It passes the graph data to the C++ addon and waits for the result asynchronously.
The C++ N-API Addon is a compiled .node binary that accepts the topology graph as input, runs a weighted Dijkstra traversal from the origin node outward, and returns a flat ordered array of node IDs representing the correct invalidation sequence: parents before children, ordered by propagation distance.
The Purge Dispatcher takes that ordered array and fires HTTP purge signals to each node in sequence, with configurable concurrency per tier. It doesn't need to know anything about graph theory — it just processes a list.
This separation is deliberate. The C++ layer does exactly one thing: compute order. It has no network I/O, no business logic, no state. That makes it testable in isolation, replaceable without touching the orchestrator, and safe to call from multiple worker threads if needed.

Building the C++ N-API Addon
First, your project structure:

cdn-purge/
├── src/
│   └── topology.cpp        # C++ addon source
├── binding.gyp             # Node build config
├── index.js                # Node.js entry point
├── orchestrator.js         # Purge orchestrator
├── topology.json           # Edge topology graph
└── package.json

Install the build toolchain:

npm install node-gyp --save-dev
npm install node-addon-api --save

node-addon-api gives us the modern C++ wrapper over raw N-API — cleaner syntax, exception handling, and ABI stability across Node.js versions.
binding.gyp — tells node-gyp how to compile your addon:

{
  "targets": [
    {
      "target_name": "topology",
      "sources": ["src/topology.cpp"],
      "include_dirs": [
        "<!@(node -p \"require('node-addon-api').include\")"
      ],
      "defines": ["NAPI_DISABLE_CPP_EXCEPTIONS"]
    }
  ]
}

Now the addon itself. src/topology.cpp:

#include <napi.h>
#include <vector>
#include <queue>
#include <unordered_map>
#include <limits>

// Represents a directed edge: destination node + propagation weight
struct Edge {
  int to;
  double weight;
};

// Dijkstra's algorithm — returns nodes ordered by propagation distance from origin
std::vector<int> computePurgeOrder(
  int nodeCount,
  const std::unordered_map<int, std::vector<Edge>>& graph,
  int origin
) {
  std::vector<double> dist(nodeCount, std::numeric_limits<double>::infinity());
  std::vector<int> visitOrder;

  // Min-heap: (distance, nodeId)
  std::priority_queue
    std::pair<double, int>,
    std::vector<std::pair<double, int>>,
    std::greater<>
  > pq;

  dist[origin] = 0.0;
  pq.push({0.0, origin});

  while (!pq.empty()) {
    auto [d, u] = pq.top(); pq.pop();

    if (d > dist[u]) continue; // stale entry, skip

    visitOrder.push_back(u);

    if (graph.count(u)) {
      for (const Edge& e : graph.at(u)) {
        double nd = dist[u] + e.weight;
        if (nd < dist[e.to]) {
          dist[e.to] = nd;
          pq.push({nd, e.to});
        }
      }
    }
  }

  return visitOrder;
}

// N-API binding — this is what Node.js calls
Napi::Value ComputePurgeOrder(const Napi::CallbackInfo& info) {
  Napi::Env env = info.Env();

  // Validate arguments
  if (info.Length() < 2 || !info[0].IsNumber() || !info[1].IsObject()) {
    Napi::TypeError::New(env, "Expected: (nodeCount: number, graph: object)")
      .ThrowAsJavaScriptException();
    return env.Null();
  }

  int nodeCount = info[0].As<Napi::Number>().Int32Value();
  Napi::Object graphObj = info[1].As<Napi::Object>();

  // Parse the graph object from JS into C++ adjacency list
  std::unordered_map<int, std::vector<Edge>> graph;
  Napi::Array nodeIds = graphObj.GetPropertyNames();

  for (uint32_t i = 0; i < nodeIds.Length(); i++) {
    std::string keyStr = nodeIds.Get(i).As<Napi::String>().Utf8Value();
    int fromNode = std::stoi(keyStr);

    Napi::Array edges = graphObj.Get(keyStr).As<Napi::Array>();

    for (uint32_t j = 0; j < edges.Length(); j++) {
      Napi::Object edge = edges.Get(j).As<Napi::Object>();
      int to = edge.Get("to").As<Napi::Number>().Int32Value();
      double weight = edge.Get("weight").As<Napi::Number>().DoubleValue();
      graph[fromNode].push_back({to, weight});
    }
  }

  // Run Dijkstra from origin node (node 0)
  std::vector<int> result = computePurgeOrder(nodeCount, graph, 0);

  // Convert result back to JS array
  Napi::Array output = Napi::Array::New(env, result.size());
  for (size_t i = 0; i < result.size(); i++) {
    output.Set(i, Napi::Number::New(env, result[i]));
  }

  return output;
}

// Register the function when the addon is loaded
Napi::Object Init(Napi::Env env, Napi::Object exports) {
  exports.Set(
    Napi::String::New(env, "computePurgeOrder"),
    Napi::Function::New(env, ComputePurgeOrder)
  );
  return exports;
}

NODE_API_MODULE(topology, Init)

A few important details in this integration:
The addon's computePurgeOrder call is synchronous at the C++ level; it blocks the calling thread until the traversal completes. Wrapping it in setImmediate inside a Promise doesn't make it truly async, but it does defer execution to the next iteration of the Event Loop, preventing it from blocking any I/O callbacks that are already queued. For a computation that now takes under 1ms, this is enough.
For genuinely non-blocking execution, the right approach is to move the addon call into a worker_thread, but that's an optimization for graphs with thousands of nodes where even sub-millisecond blocking matters. We cover that tradeoff in the gotchas section.
The graceful fallback on line 22 is non-negotiable in production code. If the addon fails (due to a wrong binary, corrupted graph input, or version mismatch after a Node.js upgrade) you want your purge job to continue with degraded behavior, not crash your orchestrator entirely.
Benchmarks: JS vs. C++ N-API
The primary reason for moving to C++ wasn't just "speed"; it was predictability. In a high-concurrency environment, you cannot afford a "stop-the-world" computation that blocks the Event Loop.
We ran a benchmark comparing a standard JavaScript Dijkstra implementation against our N-API addon. The test environment was a 16-core Linux instance, running Node.js 20.x, with a weighted directed graph simulating a global CDN topology.

The Real Winner: Event Loop Health
While the raw speed is impressive, the "JS Traversal" time represents a total freeze of the Node.js process. At the 500-node mark, the C++ addon finishes before the next Event Loop tick would even have a chance to complain. By offloading the heavy lifting to C++, we effectively flattened our p99 latency for unrelated HTTP requests that happened to arrive during a purge cycle.

The "Gotchas" (Lessons)
Writing C++ for Node.js isn't all sunshine and sub-millisecond latencies. Here are the three things that will bite you if you aren't careful:
The "Bridge" Cost: Crossing the boundary between JavaScript and C++ is not free. Every time you pass a large object (like our graph object) into N-API, the engine has to handle type conversion. If your computation is trivial, such as adding two numbers, the overhead of the "bridge" will actually make the C++ version slower than pure JS. Use C++ only for $O(n \log n)$ or $O(n^2)$ problems.
Memory Management: While N-API protects you from much of the complexity, you are still responsible for C++ memory. If you allocate a massive std::vector and don't let it go out of scope, or if you accidentally create a circular reference with Napi::Reference, you will leak memory.
The Toolchain Nightmare: Your production environment must have the necessary build tools (python, make, g++) to compile the addon during npm install, or you must use a tool like prebuild to ship platform-specific binaries. This adds complexity to your CI/CD pipeline that a pure JS project simply doesn't have.

Decision Framework: Should You Use C++ Addons?
Before you start rewriting your utility functions in C++, ask yourself these three questions:
1. Is it CPU-bound? If your bottleneck is waiting for a database or a network call, C++ won't help. This is for heavy math, image processing, or complex graph traversal.
2. Is it blocking the Event Loop? If your JS function takes >10ms and runs frequently, it’s a candidate.
3. Is the data structure stable? C++ addons are harder to refactor than JS. Only move code to N-API once the logic is "boring" and unlikely to change every week.
Conclusion
Node.js is often criticized for being "slow" at computation, but that's a misunderstanding of its architecture. Node.js is an orchestrator. It’s the conductor of an orchestra, not the lead violinist.
By using N-API, we kept our CDN orchestrator in the language where it’s most productive (JavaScript) while delegating the heavy algorithmic work to the language designed for it (C++). We didn't just make the purge faster; we made the entire system more resilient.
If you’re facing a similar bottleneck, don't reach for a microservice rewrite in Rust or Go immediately. Look at your hot paths, identify the tightest loops, and see if a surgical C++ addon can give you the 50x boost you need.

Did this help you rethink your Node.js performance bottlenecks? Let me know in the comments if you've ever had to "drop down" to native code to save your Event Loop

DEV Community: Praise Aribisala

Accelerating Global CDN Cache Invalidation in Node.js with Custom C++ N-API Addons