In this article, we’ll build a working HTTP rate limiter. You’ll learn:

• How to track request usage per client
• The differences between fixed-window and token-bucket algorithms
• How to implement a Durable Object in TypeScript
• How to integrate the limiter into Worker middleware
• How to test and benchmark your limiter at the edge

By the end, you’ll have a foundation for building your own edge middleware that’s robust, efficient, and globally scalable.

What is HTTP Rate Limiting?

Rate limiting is the process of controlling how often clients can access an API. This is a common practice to throttle traffic, protect backend workloads, and prevent abuse. For rate-limiting to work, clients must be distinguishable; therefore, a unique identifier is often issued to the client (e.g., API key, Client key), or the identifier should be automatically extracted from the client's request (e.g., IP Address).

There are diverse rate-limiting strategies, but for the scope of this article, we'll be exploring two (most common) strategies:

1. Fixed-Window Limiting

The fixed-window algorithm counts requests in discrete time intervals, like 1-minute blocks. For example, if a client is allowed 10 requests per minute, the counter resets at the start of each minute.

Pros:

• Simple to implement
• Easy to understand

Cons:

• “Burstiness” at the window boundary: a client could make 20 requests in quick succession if two windows overlap
• Less smooth distribution of requests

2. Token-Bucket Limiting

The token-bucket algorithm is more flexible. Each client has a “bucket” of tokens. Every request consumes one token. Tokens are replenished at a fixed rate. If client's bucket is empty, then the client is blocked.

Pros:

• Smooth request flow
• Handles bursts gracefully
• Easy to tune for limits and refill rates

Cons:

• Slightly more complex than fixed-window

For edge deployments, token-bucket is usually preferable because it balances fairness and responsiveness. Think of your favourite rate-limited API service; there's a high chance that Token-Bucket Limiting (or its variant) is being used.

Setting Up the Worker and Durable Objects

To build a reliable rate limiter at the edge, we need a component that can hold state for each client; Cloudflare Durable Objects are perfect for this. They provide a single, consistent state instance per identifier, and all requests for that identifier are routed to the same object, no matter which Cloudflare data center handles them.

In this section, we’ll create a complete Durable Object–based rate limiting system with three different tiers: Free, Premium, and Ultimate. Each tier behaves differently, allowing you to enforce limits based on a client’s subscription level.

Before diving into the object classes, it’s important to keep TypeScript aware of your Worker bindings.

Note: Run wrangler types After Adding Durable Objects

Whenever you define new Durable Object classes or update your wrangler.jsonc bindings, regenerate your type definitions:

wrangler types

This keeps your editor and TypeScript compiler aligned with your Worker’s actual environment. It’s important after adding new Durable Object namespaces or changing class names, because the types govern autocompletion and type checking.

The Worker: Routing Requests with the Correct Rate Limiter

Here is the Worker entrypoint that receives incoming API requests, determines which rate tier the client belongs to, and asks the appropriate Durable Object whether the request should be allowed or not.

// src/index.ts

import { DurableObject } from "cloudflare:workers";

export interface Env {
  FREE_LIMITER: DurableObjectNamespace<FreeRequestLimiter>;
  PREMIUM_LIMITER: DurableObjectNamespace<PremiumRequestLimiter>;
  ULTIMATE_LIMITER: DurableObjectNamespace<UltimateRequestLimiter>;
}

// Worker logic
export default {
  async fetch(request, env, _ctx): Promise<Response> {
    // extract Client API_KEY
    const key = request.headers.get("API_KEY");
    if (key === null) {
      return new Response("Could not determine client key", { status: 400 });
    }

    // determine rate limit tier
    try {
      // in a production system, you would look up the key in a database for the tier
      const rateLimiter = key.startsWith("ult_")
        ? env.ULTIMATE_LIMITER
        : key.startsWith("pre_")
        ? env.PREMIUM_LIMITER
        : env.FREE_LIMITER;

      const stub = rateLimiter.getByName(key);
      const milliseconds_to_next_request =
        await stub.getMillisecondsToNextRequest();

      if (milliseconds_to_next_request > 0) {
        return new Response("Rate limit exceeded", { status: 429 });
      }
    } catch (error) {
      return new Response("Could not connect to rate limiter", { status: 502 });
    }

    // proceed with normal request handling, e.g. proxy to origin
    return new Response("Request successful", { status: 200 });
  },
} satisfies ExportedHandler<Env>;

The Worker does three things:

• Extracts the unique identifier, in this case, the API key.
• Determines the appropriate rate tier using a simple prefix-based rule (in a real system, this would come from a database).
• Sends the unique identifier to the Durable Object for that tier. If the limiter reports that the request should wait, the Worker immediately returns a 429.

This structure separates the request logic from the rate-limiting logic, keeping everything clean and modular.

Building the Rate Limiter Durable Objects

The Durable Object itself implements the token-bucket style behaviour. To keep things maintainable, we define a BaseRateLimiter class that encapsulates the shared logic, and then three concrete classes that specify the performance characteristics for each tier.

// src/index.ts

// Durable Object
abstract class BaseRateLimiter extends DurableObject {
  abstract milliseconds_per_request: number;
  abstract milliseconds_for_updates: number;
  abstract capacity: number;

  abstract tokens: number;

  async getMillisecondsToNextRequest(): Promise<number> {
    await this.checkAndSetAlarm();

    let delay = this.milliseconds_per_request;
    if (this.tokens > 0) {
      this.tokens -= 1;
      delay = 0;
    }

    return delay;
  }

  private async checkAndSetAlarm() {
    const currentAlarm = await this.ctx.storage.getAlarm();
    if (currentAlarm == null) {
      await this.ctx.storage.setAlarm(
        Date.now() + this.milliseconds_for_updates
      );
    }
  }

  async alarm() {
    if (this.tokens < this.capacity) {
      this.tokens = Math.min(
        this.capacity,
        this.tokens + this.milliseconds_for_updates
      );
      await this.checkAndSetAlarm();
    }
  }
}

This base class gives each tier its own “bucket” size, refill rate, and request cost.

When getMillisecondsToNextRequest() is called, the object does the following:

• Ensures an alarm is scheduled to refill tokens.
• If tokens are available, it decrements one and returns 0, meaning the request is allowed immediately.
• If tokens have run out, it returns a delay value indicating how long the client should wait.

The refill logic runs inside the alarm() method, which Cloudflare triggers based on the alarm schedule. This is an efficient way of replenishing tokens at the edge without needing to calculate elapsed time for every request.

Defining Each Tier

Each tier extends the base class, sets its own performance characteristics, and initializes the bucket with the corresponding capacity.

// src/index.ts

export class UltimateRequestLimiter extends BaseRateLimiter {
  milliseconds_per_request = 100; // 1 request / 100ms = 10 req/sec
  milliseconds_for_updates = 5000; // refill every 5s
  capacity = 80; // burst capacity
  tokens: number;

  constructor(ctx: DurableObjectState, env: Env) {
    super(ctx, env);
    this.tokens = this.capacity;
  }
}

export class PremiumRequestLimiter extends BaseRateLimiter {
  milliseconds_per_request = 200; // 1 request / 200ms = 5 req/sec
  milliseconds_for_updates = 5000; // refill every 5s
  capacity = 30; // burst capacity
  tokens: number;

  constructor(ctx: DurableObjectState, env: Env) {
    super(ctx, env);
    this.tokens = this.capacity;
  }
}

export class FreeRequestLimiter extends BaseRateLimiter {
  milliseconds_per_request = 500; // 1 request / 500ms = 2 req/sec
  milliseconds_for_updates = 5000; // refill every 5s
  capacity = 10; // burst capacity
  tokens: number;

  constructor(ctx: DurableObjectState, env: Env) {
    super(ctx, env);
    this.tokens = this.capacity;
  }
}

Each tier defines three important parameters:

• milliseconds_per_request: how frequently a client is allowed to make a request
• milliseconds_for_updates: how often to refill tokens
• capacity: how many requests can be made in a burst before throttling begins

Because everything is based on an abstract parent class, defining new tiers becomes straightforward.

Binding the Durable Objects in wrangler.jsonc

Finally, all the three-tiered limiters binding should be created in the configuration:

// wrangler.jsonc

"durable_objects": {
  "bindings": [
    {
      "name": "FREE_LIMITER",
      "class_name": "FreeRequestLimiter"
    },
    {
      "name": "PREMIUM_LIMITER",
      "class_name": "PremiumRequestLimiter"
    },
    {
      "name": "ULTIMATE_LIMITER",
      "class_name": "UltimateRequestLimiter"
    }
  ]
}

Each binding points to its corresponding class, allowing the Worker entrypoint to retrieve the right limiter when processing requests. Then run wrangler types to generate the type definitions for the durable objects.

Deployment: Local and Cloudflare

Once your Worker and Durable Objects are ready, the final step is to run them locally and then publish them to Cloudflare. The process is simple, and it’s the same whether you’re building a rate limiter or a larger edge application.

Running Locally

Cloudflare’s local environment is started with:

wrangler dev

This runs your Worker on localhost:8787 and also spins up local Durable Objects automatically. Nothing extra needs to be configured. Every API key you use will create or reuse its corresponding Durable Object instance exactly as it would when deployed to Cloudflare (production).

You can test requests immediately:

curl -H "API_KEY: pre_test123" http://localhost:8787

Deploying to Cloudflare

When everything works locally, deploy globally:

wrangler deploy

Wrangler builds your Worker, uploads it to Cloudflare’s edge network, creates Durable Object classes if needed, and returns a production URL.

You can test the deployed version the same way:

curl -H "API_KEY: pre_test123" https://your-worker.your-subdomain.workers.dev

When deployed to Cloudflare, you can confirm that your rate-limiter durable objects are active by going to:

Cloudflare Dashboard → Workers → Durable Objects

This page shows all instances created by your Worker, along with their current storage and activity.

Fixed-Window Implementation

Here's a code snippet of fixed-window implemetation for comparism:

const windowSize = 60 * 1000; // 1 minute
let counter = 0;
let windowStart = Date.now();

if (Date.now() - windowStart > windowSize) {
  counter = 0;
  windowStart = Date.now();
}

if (counter >= limit) {
  return new Response("Too Many Requests", { status: 429 });
}

counter++;

• Simple, but can cause bursts at window boundaries.

Testing and Benchmarking at the Edge

Once the Worker and Durable Object are deployed, you can test with:

# Single request
curl -i https://your-worker.your-subdomain.workers.dev/api/test

# Burst test
for i in {1..30}; do curl -s -o /dev/null -w "%{http_code}\n" https://your-worker.your-subdomain.workers.dev/api/test; done

Metrics to monitor include:

• Number of requests blocked (429)
• Average latency of Durable Object calls
• Token refill consistency
• Error rate

Edge deployments generally have sub-millisecond response times for token checks. Using wrangler dev locally is great for functional tests, but benchmarking in production ensures you capture global latency patterns.

Observations and Best Practices

• Keep state lightweight: Store only what’s necessary, like token counts and last refill timestamps. This ensures fast execution and minimal storage overhead.

• Avoid heavy computations in Durable Objects: CPU time is limited per execution. Complex logic can slow down requests and increase costs.

• Plan object keys carefully: Use one unique key per client to prevent race conditions and ensure accurate rate tracking.

• Provide client feedback: Return headers such as X-RateLimit-Remaining and Retry-After so clients know when to retry.

• Test for edge cases: Simulate bursts, multi-client traffic, and slow refill scenarios to ensure limits behave as expected.

By following these practices, your rate limiter stays predictable, efficient, and ready to handle traffic at the edge.

Closing Thoughts

In this part, we moved from theory to practice by implementing an HTTP rate limiter on Cloudflare Workers using Durable Objects. We explored how to track client requests, enforce limits per tier, and handle bursts efficiently at the edge.

You also learned the difference between fixed-window and token-bucket strategies, why token-bucket is often better for edge deployments, and how to benchmark and tune your limiter for real-world traffic.

In Part 3, we’ll take these concepts further by extending rate limiting to WebSockets, building a modular middleware pipeline, and covering best practices for deploying, monitoring, and scaling edge traffic. By the end, you’ll have a foundation for production-ready, globally distributed request control.

Next: [Part 3: Building a WebSocket Rate Limiter with Cloudflare Workers]

In the last decade, we’ve witnessed a massive shift from monoliths → microservices → serverless. Each step moved compute closer to flexibility, but not necessarily closer to users.

Edge computing changes that. It allows you to run code within the CDN network itself, milliseconds from the user. Cloudflare Workers make this possible by letting developers run JavaScript and TypeScript code in more than 300 data centers globally.

Running logic at the edge improves latency, enhances security, reduces costs, and scales automatically without traditional server provisioning. In this series, we will build production-ready middleware for HTTP and WebSocket traffic. The focus will be on rate limiting, but the patterns we discuss will apply to caching, authentication, and logging.

What Are Cloudflare Workers?

Cloudflare Workers are small JavaScript or TypeScript programs that run inside V8 isolates the same sandbox used by Chrome and Node.js, but stripped down and optimized for edge execution.

When a request hits your domain, it passes through Cloudflare’s network. Your Worker can then inspect or modify the request, authenticate or rate-limit the client, cache responses, transform data, or proxy WebSocket connections before reaching your origin servers.

Workers start in less than one millisecond and can handle millions of requests concurrently. They are ideal for ultra-fast, high-scale logic that runs close to the user.

How Workers Differ from Lambda and Friends

Workers are designed for short-lived, high-performance workloads. They are not suitable for long-running tasks or heavy compute operations.

The V8 Isolate Runtime ⚙️ - Browser DNA at the Edge

Because Cloudflare Workers run inside a V8 isolate, the environment is more like a browser than Node.js.

What Works:

• Standard Web APIs such as fetch, Request, Response, URL, Headers, FormData, ReadableStream, and Crypto.

• Modern ECMAScript syntax including async/await and modules.

• Cloudflare bindings such as KV, R2, Durable Objects, D1, Queues, and AI integrations.

What Does Not Work:

Node.js-specific APIs such as fs, net, tls, dgram, path, os, cluster, and child_process are not available. Packages that depend on these will fail.

This means not all npm packages will work. Any library that depends on Node internals will break.

Alternatives and Patterns

A quick check: if the code runs in Chrome’s DevTools console, it probably runs in a Cloudflare Worker.

Why This Matters for Middleware Design

Building middleware on Workers means embracing Web APIs and message-based architecture, not Node servers.

Instead of spinning up a Redis client, you might use a Durable Object that acts as a distributed counter. Instead of file I/O, you rely on Cloudflare KV for persistence. Instead of Express middleware, you define lightweight fetch handlers.

These constraints lead to simpler, safer, and globally scalable patterns, but they also force you to design differently.

The Idea of Edge Middleware

Think of middleware as the logic between a user’s request and your origin response.

         ┌────────────────────┐
Client → │   Edge Middleware  │ → Backend API
         └────────────────────┘
                  ▲
            Logging, Auth,
            Rate Limiting

At the edge, middleware can decide within milliseconds whether a request deserves to reach your backend or not.

Some of the benefits of this approach are:

• Better Security: Bad actors can be dropped early, even before reaching your back-end service.

• Improved Performance: Reduce round-trips to origin.

• Cost: Save bandwidth and compute.

• Observability: Capture metrics closer to users, which can be further exported to Loki/Grafana/Mimir.

When to Use Edge Middleware

Below are some real, production-ready workloads handled daily by Cloudflare Workers.

Why Edge Rate Limiting Beats Traditional Approaches

Traditional rate limiting relies on in-memory counters or Redis. This introduces latency and single points of failure.

Edge rate limiting solves this by:

• Storing counters in Durable Objects, automatically sharded by user key.

• Evaluating requests close to the user.

• Providing consistent global enforcement per client.

This results in sub-millisecond enforcement with minimal backend dependency.

Durable Objects (DO)

Durable Objects are stateful actors that maintain consistent state across requests.

A Durable Object can:

• Store data in memory.

• Persist data between requests.

• Receive messages via fetch().

• Guarantee one instance per ID worldwide.

Each API key or client can have a dedicated Durable Object instance. This is ideal for token buckets, request counters, or WebSocket hubs.

      +---------------------------+
      | Durable Object: user_123  |
      | tokens = 5 of 10          |
      | lastRefill = 1699999999   |
      +---------------------------+

Architecture Vision for This Series

                ┌────────────────────────────┐
                │        Cloudflare Edge     │
                │ ┌────────────────────────┐ │
Client → → → →  │ │ Worker (Middleware)    │ │ → Backend
                │ │ - Auth & Rate Limit    │ │
                │ │ - WS Proxy Gateway     │ │
                │ └────────────────────────┘ │
                │ ┌────────────────────────┐ │
                │ │ Durable Object(s)      │ │
                │ │ - Per-user counters    │ │
                │ │ - Token buckets        │ │
                │ └────────────────────────┘ │
                └────────────────────────────┘

The beauty of this design is that it scales automatically — no central Redis, no replication nightmares, no cold starts.

Setting Up the Environment

1. Install Wrangler

npm install -g wrangler

Confirm:

npx wrangler --version

Note: At the time of writing, Wrangler requires at least Node.js v20.0.0. Consider using a Node.js version manager such as nvm to switch node versions.

2. Login to Cloudflare

npx wrangler login

3. Initialize a Worker Project

npx wrangler init edge-middleware

Response to all prompts are shared in the screenshot above. Your file/folder structure should be similar to this:

.
├── node_modules\
├── package-lock.json
├── package.json
├── src
│   └── index.ts
├── test
│   ├── env.d.ts
│   ├── index.spec.ts
│   └── tsconfig.json
├── tsconfig.json
├── vitest.config.mts
├── worker-configuration.d.ts
└── wrangler.jsonc

We’ll define the RateLimiter Durable Object class in Part 2.

Your First Hello-World Worker

Try a simple fetch handler:

//src/index.ts
export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
    return new Response("Hello from Cloudflare worker", {
      headers: { "content-type": "text/plain" },
    });
  },
} satisfies ExportedHandler<Env>;

Run locally:

npx wrangler dev

Visit http://localhost:8787 → you’ll see the response instantly.

Practice: Simple Edge Middleware

Let’s add basic validation before proxying to a backend:

//src/index.ts
export default {
  async fetch(req: Request) {
    const url = new URL(req.url);

    if (!url.pathname.startsWith("/api")) {
      return new Response("Forbidden", { status: 403 });
    }

    const backend = await fetch("https://api.yourbackend.com" + url.pathname, {
      headers: req.headers,
      method: req.method,
      body: req.body,
    });

    const res = new Response(backend.body, backend);
    res.headers.set("x-edge-checked", "true");
    return res;
  },
};

You’ve now written an edge gateway that can inspect, block, and modify traffic before it reaches your origin. For local testing, I’ll run a basic HTTP server locally and use that as my backend endpoint.

python3 -m http.server 8001

You can replace https://api.yourbackend.com in the src/index.ts with http://localhost:8001 if testing locally too.

Debugging and Local Testing

Wrangler provides a powerful local runtime which simulates the Cloudflare environment, including Durable Objects and bindings. You can get it started by running:

npx wrangler dev

Simulate requests:

for i in {1..10}; do curl -s -o /dev/null -w "%{http_code}\n" http://localhost:8787/api/test; done

Deployment

Deploying your worker to Cloudflare makes it globally accessible, and can be achieved by running:

npx wrangler deploy

Your Worker is instantly available and the link is displayed in the terminal, something like this: https://<your-project-id>.workers.dev. You can also add a custom domain to the worker via the Cloudflare worker dashboard.

Observability and Metrics

Cloudflare gives built-in analytics, but you can push custom metrics too:

• Workers Logs API: stream structured logs.

• Durable Object storage: aggregate usage per key.

• Integrations: send logs to Grafana/Loki/Mimir (LGTM stack).

• Wrangler tail: live-view logs during dev.

Since we interested in the live-view logs of the deployed worker, we can run:

npx wrangler tail

Closing Thoughts

Cloudflare Workers change how we think about deploying logic on the internet. Instead of running code on a single server or region, the platform pushes your logic to the edge, closer to every user. This makes Workers feel fast in practice, even when doing simple tasks like modifying headers, validating requests, or shaping traffic before it reaches your backend.

Because Workers run inside a V8 isolate, they follow a “browser-style” environment. This means you won’t have access to traditional Node.js modules, but you do get lightweight execution, instant cold starts, and a highly secure sandbox. Once you work within those boundaries, the platform becomes surprisingly flexible and powerful.

Part 1 focused on building an intuition for Workers and the concept of middleware at the edge. In Part 2, we move from ideas to implementation. We’ll build a practical HTTP rate limiter using Durable Objects, compare popular algorithms, and walk through how they behave in real-world workloads.

Next Up: [Part 2: Building an HTTP Rate Limiter with Durable Objects]

I was saddled with the responsibility of setting this up, and that won't be much of a problem (at least I thought). Everything was going pretty well until I can't access the deployed application externally. All walkthrough I could find online require me to use FastCGI, but I was quite unlucky installing it.

Then I found another way around...

Open port for TCP access

To allow HTTP traffic to your application's port, we need to open a static port in the Windows firewall for TCP access. There are many ways this could be done (e.g CMD, control panel etc) but I used the CMD. Simply run to open port 8001

netsh advfirewall firewall add rule name="TCP Port 8001" dir=in action=allow protocol=TCP localport=8001

In case you need to close the port, run the command below

netsh advfirewall firewall delete rule name="TCP Port 8001" protocol=TCP localport=8001

Set Flask server host to 0.0.0.0

The default host used by Flask server is 127.0.0.1, this make the server accessible only by the network serving Flask, i.e your local computer. The last piece is to make the server publicly available; set the Flask host to 0.0.0.0.

To change the port, simply run your Flask project using

flask run --host=0.0.0.0

Access the application over the internet

Your application is now published and can be accessed outside your server. Use your machine IP/domain name and port. e.g http://192.168.28.20:8001

Thanks for your time!