Migrating OpenClaw Rating API Token Bucket from Redis to Cloudflare Durable Objects

3.1 Prerequisites and Environment Setup

1. Ensure you have a Cloudflare account with Workers and Durable Objects enabled.
2. Install the latest wrangler CLI (v2+).
3. Clone the OpenClaw repository and create a new branch feature/durable-objects.
4. Verify existing Redis connection strings are stored in wrangler.toml under [vars].

3.2 Refactor Token‑Bucket Logic to Use Durable Objects API

Replace the Redis client calls with a Durable Object class that encapsulates the bucket state.

// tokenBucket.do.ts – Durable Object definition
export class TokenBucket {
  state: DurableObjectState;
  bucket: { tokens: number; lastRefill: number };
  static readonly CAPACITY = 100; // max tokens
  static readonly REFILL_RATE = 10; // tokens per second

  constructor(state: DurableObjectState, env: any) {
    this.state = state;
    this.bucket = state.storage.get('bucket').then(v => v ?? { tokens: TokenBucket.CAPACITY, lastRefill: Date.now() });
  }

  async fetch(request: Request) {
    const now = Date.now();
    const elapsed = (now - this.bucket.lastRefill) / 1000;
    const refill = Math.floor(elapsed * TokenBucket.REFILL_RATE);
    this.bucket.tokens = Math.min(TokenBucket.CAPACITY, this.bucket.tokens + refill);
    this.bucket.lastRefill = now;

    if (this.bucket.tokens > 0) {
      this.bucket.tokens--;
      await this.state.storage.put('bucket', this.bucket);
      return new Response('OK', { status: 200 });
    } else {
      return new Response('Rate limit exceeded', { status: 429 });
    }
  }
}

In your worker, bind the Durable Object:

// worker.ts – binding
export default {
  async fetch(request, env) {
    const id = env.TOKEN_BUCKET.idFromName('global');
    const obj = env.TOKEN_BUCKET.get(id);
    return obj.fetch(request);
  }
};

Update wrangler.toml to declare the object:

[[durable_objects]]
name = "TOKEN_BUCKET"
class_name = "TokenBucket"

3.3 Data Migration Strategy (Warm‑up, Fallback, Verification)

• Warm‑up phase: Deploy the Durable Object alongside Redis. For the first 24 h, route 10 % of traffic to the new object while keeping Redis as the source of truth.
• Fallback handling: If the Durable Object fails to load state (e.g., cold start), gracefully fall back to Redis for that request and log the incident.
• Verification: Compare token consumption metrics from both stores. Use a simple dashboard that aggregates GET /metrics from each backend.

3.4 Testing and Validation

Automated tests should cover:

1. Correct token refill calculation under varying request rates.
2. State persistence across worker restarts (cold starts).
3. Graceful degradation to Redis when the Durable Object is unavailable.

Run the test suite locally with wrangler dev and in CI using wrangler publish --dry-run.

3.5 Deployment and Roll‑back Procedures

• Deploy the new worker to a staging environment first; verify that the Durable Object receives traffic.
• Promote to production using a canary release (5 % traffic). Monitor latency and error rates via Cloudflare Analytics.
• If error rates exceed < 0.5 %, instantly roll back by disabling the Durable Object route in wrangler.toml and re‑enabling the Redis fallback.