Building, Deploying, and Testing the OpenClaw Rating API Edge CRDT Token‑Bucket Operator

2. Recap of the Earlier High‑Level Guide

In the previous article we introduced the architecture of the Rating API Edge CRDT operator:

• CRDT (Conflict‑Free Replicated Data Type) ensures eventual consistency across distributed nodes.
• The token‑bucket algorithm enforces a configurable request‑per‑second limit.
• Edge deployment reduces latency by processing rating requests close to the client.

That guide also highlighted the three logical layers—API gateway, CRDT state store, and token‑bucket limiter—and showed a simplified YAML manifest for OpenClaw. This tutorial expands each layer with concrete code, Dockerfile, and verification scripts.

For a quick visual reference, see the UBOS platform overview which illustrates how custom operators plug into the OpenClaw runtime.

4. Building the Operator

4.1 Clone the Repository

git clone https://github.com/openclaw/rating-api-operator.git
cd rating-api-operator

4.2 Initialise Go Modules

go mod tidy

4.3 Implement the Token‑Bucket Logic

The core limiter lives in pkg/limiter/limiter.go. Below is a minimal, production‑ready implementation that uses a sliding‑window counter and persists state to a local badger DB (which OpenClaw mounts as a persistent volume):

package limiter

import (
    "sync"
    "time"

    "github.com/dgraph-io/badger/v4"
)

type Bucket struct {
    mu        sync.Mutex
    capacity  int
    refill    int           // tokens added per interval
    interval  time.Duration // refill interval
    tokens    int
    lastCheck time.Time
    db        *badger.DB
}

// NewBucket creates a token bucket backed by Badger.
func NewBucket(capacity, refill int, interval time.Duration, dbPath string) (*Bucket, error) {
    opts := badger.DefaultOptions(dbPath).WithLogger(nil)
    db, err := badger.Open(opts)
    if err != nil {
        return nil, err
    }
    return &Bucket{
        capacity:  capacity,
        refill:    refill,
        interval:  interval,
        tokens:    capacity,
        lastCheck: time.Now(),
        db:        db,
    }, nil
}

// Allow returns true if a request can proceed.
func (b *Bucket) Allow() bool {
    b.mu.Lock()
    defer b.mu.Unlock()

    now := time.Now()
    elapsed := now.Sub(b.lastCheck)

    // Refill tokens based on elapsed time.
    if elapsed >= b.interval {
        refillCount := int(elapsed / b.interval)
        b.tokens += refillCount * b.refill
        if b.tokens > b.capacity {
            b.tokens = b.capacity
        }
        b.lastCheck = now
    }

    if b.tokens > 0 {
        b.tokens--
        return true
    }
    return false
}

// Close releases Badger resources.
func (b *Bucket) Close() error {
    return b.db.Close()
}

The Allow method is called by the HTTP handler defined in pkg/api/handler.go. The handler checks the bucket before forwarding the request to the underlying rating service.

4.4 Write Unit Tests

Tests live in pkg/limiter/limiter_test.go. They verify refill behaviour, capacity limits, and persistence across restarts.

func TestBucketAllow(t *testing.T) {
    b, err := NewBucket(5, 1, time.Second, "./tmpdb")
    if err != nil { t.Fatalf("init error: %v", err) }
    defer os.RemoveAll("./tmpdb")
    defer b.Close()

    // Consume all tokens.
    for i := 0; i < 5; i++ {
        if !b.Allow() {
            t.Fatalf("expected token %d to be allowed", i)
        }
    }
    // Next request should be blocked.
    if b.Allow() {
        t.Fatalf("expected request to be blocked")
    }

    // Wait for refill.
    time.Sleep(1100 * time.Millisecond)
    if !b.Allow() {
        t.Fatalf("expected token after refill")
    }
}

4.5 Build the Docker Image

The Dockerfile uses a multi‑stage build to keep the final image lightweight (≈30 MB):

# syntax=docker/dockerfile:1.4
FROM golang:1.22-alpine AS builder
WORKDIR /src
COPY . .
RUN go build -ldflags="-s -w" -o /app/operator ./cmd/operator

FROM alpine:3.19
RUN addgroup -S app && adduser -S -G app app
COPY --from=builder /app/operator /usr/local/bin/operator
USER app
EXPOSE 8080
ENTRYPOINT ["operator"]

Build and push the image to your private registry (replace REGISTRY with your actual repo):

docker build -t REGISTRY/openclaw/rating-operator:latest .
docker push REGISTRY/openclaw/rating-operator:latest

If you prefer a hosted registry, UBOS offers a built‑in container registry—see the UBOS pricing plans for details.

6. Testing and Verification

6.1 Smoke Test with curl

After the Ingress is live, obtain the HTTPS URL from the UBOS dashboard (e.g., https://rating.example.com/rating) and run a quick curl request:

curl -X POST https://rating.example.com/rating \
  -H "Content-Type: application/json" \
  -d '{"user_id":"123","item_id":"456","rating":5}' -w "\nHTTP %{http_code}\n"

You should receive a 200 OK response with a JSON payload confirming the rating was accepted. If the token bucket is exhausted, the service returns 429 Too Many Requests.

6.2 Load Test with k6

To verify rate‑limiting under load, use k6:

import http from 'k6/http';
import { check, sleep } from 'k6';

export const options = {
  stages: [
    { duration: '30s', target: 50 }, // ramp‑up to 50 VUs
    { duration: '1m', target: 50 },
    { duration: '30s', target: 0 },
  ],
};

export default function () {
  const res = http.post('https://rating.example.com/rating', JSON.stringify({
    user_id: Math.random().toString(36).substring(2, 10),
    item_id: 'item-42',
    rating: Math.floor(Math.random() * 5) + 1,
  }), { headers: { 'Content-Type': 'application/json' } });

  check(res, {
    'status is 200 or 429': (r) => r.status === 200 || r.status === 429,
  });
  sleep(0.2);
}

The test should show a steady proportion of 429 responses that matches the bucket capacity (100 requests per second in the example). Adjust CAPACITY, REFILL, and INTERVAL in the ConfigMap to tune the limits.

6.3 End‑to‑End Integration Test

OpenClaw’s Web app editor lets you compose a workflow that calls the rating operator, stores the result in a CRDT map, and sends a confirmation message via Telegram. The following minimal JSON workflow demonstrates the integration:

{
  "steps": [
    {
      "name": "rate-item",
      "type": "http",
      "method": "POST",
      "url": "https://rating.example.com/rating",
      "body": {
        "user_id": "{{user.id}}",
        "item_id": "{{item.id}}",
        "rating": "{{rating}}"
      }
    },
    {
      "name": "store-result",
      "type": "crdt",
      "operation": "put",
      "key": "ratings/{{user.id}}/{{item.id}}",
      "value": "{{rate-item.response}}"
    },
    {
      "name": "notify-telegram",
      "type": "telegram",
      "chat_id": "{{user.telegram_id}}",
      "text": "Your rating has been recorded ✅"
    }
  ]
}

Deploy the workflow via the UBOS UI, trigger it from a test client, and verify that:

• The rating is persisted in the CRDT store.
• The Telegram message arrives (requires the Telegram integration on UBOS).
• No rate‑limit errors appear unless you intentionally overload the operator.

6.4 Monitoring with UBOS Dashboard

UBOS automatically collects Prometheus metrics from every container. Open the UBOS partner program dashboard and add a graph for operator_requests_total and operator_rate_limited_total. Alerts can be configured to fire when the rate‑limit exceeds a threshold, ensuring you never miss a spike.