Skip to content

feat: implement rateLimiterNode with fixed and sliding window strategies#49

Merged
MAlshaik merged 1 commit into
wespreadjam:mainfrom
DheerajShrivastav:feat/rate-limiter-node
Mar 27, 2026
Merged

feat: implement rateLimiterNode with fixed and sliding window strategies#49
MAlshaik merged 1 commit into
wespreadjam:mainfrom
DheerajShrivastav:feat/rate-limiter-node

Conversation

@DheerajShrivastav

Copy link
Copy Markdown
Contributor

feat: implement rateLimiterNode — fixed & sliding window rate limiting

Closes #11

What this adds

A rate_limiter primitive node that queues a list of items through a rate-limited pipeline, preventing downstream API calls from exceeding configured limits. Supports two strategies:

  • Fixed window — processes items in batches of requestsPerWindow, sleeping windowMs between each batch
  • Sliding window — tracks per-request timestamps; each item waits only until the oldest in-window request expires

Input schema

{
  items: unknown[]          // min 1 item — the payloads to rate-limit through
  requestsPerWindow: number // 1–10000
  windowMs: number          // 100–3600000 ms
  strategy: 'fixed' | 'sliding'
}

Note: items is not in the original spec but is required for the node to have anything to process. Without it the node would have no purpose as a standalone primitive.

Output schema

{
  processedItems: unknown[]   // all items in original order
  totalItems: number
  totalDurationMs: number     // actual wall-clock time (fake-time in tests)
  strategy: string
  windowMs: number
  requestsPerWindow: number
}

Design decisions

Decision Reason
category: 'logic' The spec lists "Primitives" but no such category exists in the codebase; 'logic' matches all comparable nodes (delayNode, conditionalNode)
supportsCancel: false Consistent with all other logic nodes; cancellation would require a significantly different executor pattern
supportsRerun: true Deterministic output for the same input — safe to rerun
Runtime guard for requestsPerWindow < 1 Belt-and-suspenders beyond Zod min(1); prevents an infinite loop if the executor is called directly

Tests — 28 cases covering

  • Metadata (type, category, capabilities)
  • Input schema validation (all boundary conditions)
  • Fixed window: ordering, metadata, exact-fit batches, timing assertion (totalDurationMs >= windowMs)
  • Sliding window: ordering, strategy echo, single-item no-wait, timing assertion
  • Output schema: valid shape, missing fields, negative duration rejection
  • Error handling: schema-level requestsPerWindow: 0 rejection + executor-level runtime guard

Adds a rate limiter primitive node that queues requests to stay within
API rate limits. Supports both fixed window (batch-based) and sliding
window (timestamp-based) strategies with Zod-validated I/O schemas.

- Fixed window: processes items in batches, sleeps windowMs between batches
- Sliding window: tracks per-request timestamps, waits only when window is full
- Input: items[], requestsPerWindow (1–10000), windowMs (100–3600000), strategy
- Output: processedItems, totalItems, totalDurationMs, echoed config metadata
- Runtime guard for requestsPerWindow < 1 (belt-and-suspenders beyond schema)
- 28 unit tests covering schema validation, ordering, timing assertions,
  output schema, and runtime error handling
@MAlshaik MAlshaik merged commit d987a4c into wespreadjam:main Mar 27, 2026
2 checks passed
MAlshaik added a commit that referenced this pull request Mar 30, 2026
…ngine-level rate limiting

Both PRs implemented cross-cutting concerns as standalone wrapper nodes,
contradicting the execution-engine direction established in Issue #37 and
PR #39. retryNode was non-functional (always returned on first attempt),
and rateLimiterNode was a sleep-based passthrough that didn't actually
rate-limit API calls.

Rate limiting is now a first-class ExecutionConfig option alongside retry,
cache, and timeout — configured via RateLimitConfig with a pluggable
RateLimitStore interface and MemoryRateLimitStore default implementation.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Node] rateLimiterNode - Respect API rate limits

2 participants