Post-GA blog: Skip the Plugin — Building a Rate-Limited API in Wheels 4.0

[bpamiri]

Now that 4.0 is out, the post-GA blog series shifts from "what shipped" to "how do you actually use it?" First in the series is the middleware stack — specifically rate limiting, which used to be the most common "I need a plugin for this" request.

Read: https://blog.wheels.dev/posts/skip-the-plugin-rate-limited-api

The post is a guided tour of wheels.middleware.RateLimiter, Cors, and SecurityHeaders composed via the new pipeline. It walks through:

• Three strategies — fixedWindow (default, cheap), slidingWindow (accurate), tokenBucket (allows bursts). Picked by behavior, not by name.
• The keyFunction hero example — a small closure that buckets authenticated traffic per X-Api-Key and falls back to IP for anonymous. Same office NAT, different buckets for different keys.
• trustProxy and proxyStrategy — why it's off by default (X-Forwarded-For spoofing), why "last" is right behind nginx with proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;, and where Cloudflare's CF-Connecting-IP fits.
• Canonical stack order — RequestId → SecurityHeaders → Cors → RateLimiter → app. Why 429s still need CORS so browsers can read them, why SecurityHeaders wraps everything on the way out.
• In-memory vs database storage — when to flip to storage="database" for multi-instance, and the auto-created wheels_rate_limits table.
• failOpen vs fail-closed — secure default, when to override.

Side note: a small framework fix surfaced while writing this

While probing edge cases for the post, windowSeconds = 0 turned out to leak a generic CFML You cannot divide by zero out of the fixedWindow and tokenBucket strategy math — accurate but useless for debugging. That's #2693, fixed in the same week the article landed. The constructor now refuses windowSeconds <= 0 and negative maxRequests at init time and throws Wheels.RateLimiter.InvalidConfiguration with a message naming the bad parameter, matching the pattern already used for strategy, storage, and proxyStrategy. maxRequests = 0 is still legal — it's the kill-switch idiom for "block everything," useful in incident response.

What's next in the post-GA series

The remaining four titles from the second batch:

1. Anatomy of a Wheels Package — authoring, mixins, the registry
2. Wheels + Claude — building a feature via the stdio MCP
3. Beyond findAll — scopes, enums, the chainable query builder
4. From Empty Directory to Deployed SaaS — end-to-end with generators, multi-tenancy, jobs, browser tests, wheels deploy

Feedback on the rate-limiting post — what worked, what didn't, what you'd want covered next — welcome in this thread.