rate-limit Package Skill

Package: @epicdm/rate-limit Repository: flowstate-platform Path: packages/shared/rate-limit Version: 0.1.0

Use this published Dojo skill as the package-level entrypoint. For detailed workflows, use the package-local skills listed below.

Primary Package Workflow

KV Rate Limiting

Status: Active Purpose: Apply the shared KV limiter without changing its availability or response contract. Scope: packages/shared/rate-limit Trigger: A route or middleware needs lightweight request throttling. Input: Request, optional KVNamespace, identifier, limit, and window seconds. Output: Allow/deny decision and optional standard 429 response.

Workflow

1. Choose an identifier that is scoped to the endpoint, user, publisher, or IP.
2. Resolve IP-based identifiers with getRateLimitId(request) when no better authenticated ID exists.
3. Call checkRateLimit(kv, identifier, limit, windowSeconds).
4. If allowed is false, return rateLimitResponse(windowSeconds).
5. Preserve fail-open behavior unless the product explicitly requires fail-closed security semantics.

Contracts

Example

const id = `publish:${getRateLimitId(request)}`
const result = await checkRateLimit(env.RATE_LIMIT_KV, id, 5, 3600)
if (!result.allowed) return rateLimitResponse(3600)

Verification

• Run yarn workspace @epicdm/rate-limit test.
• Add a test when changing headers, KV keys, fail-open behavior, or response shape.

Package Skill Inventory

Skill Inventory: @epicdm/rate-limit

Package Role

@epicdm/rate-limit provides a small Cloudflare KV rate-limit helper and a standard 429 response for FlowState route code.

Skills

Composition Notes

• Compose with API worker route skills when a route needs throttling.
• Use service-specific middleware first when present, such as Dojo publish/install rate-limit modules.
• Do not use as a quota, billing, or abuse-proof counter without stronger atomicity.

Review Gate

Review Gate: @epicdm/rate-limit Skills

Result

Pass.

Checks

• Skill content is backed by src/index.ts and tests.
• It calls out fail-open behavior and the non-atomic KV counter limitation.
• Verification commands are package-local.
• No generated Dojo files or unrelated source files were changed.

Start with this skill to understand the package purpose, then use the package-local focused skills for specific workflows. Keep this Dojo version aligned with packages/shared/rate-limit/package.json. Do not treat generated feature lists as lessons; use workflow evidence from CODE-REVIEW.md, SKILL-INVENTORY.md, and REVIEW.md.