Ectomancer.RateLimiter (Ectomancer v1.2.1)

Copy Markdown View Source

Token bucket rate limiter backed by ETS.

Provides global and per-actor rate limiting for MCP tool calls. Designed for LLM clients that may make rapid consecutive requests.

Configuration

Configure globally in config.exs:

config :ectomancer, :rate_limit,
  max: 100,
  window_ms: 60_000,
  per_actor: false

Or inline in use Ectomancer:

use Ectomancer,
  name: "my-app",
  rate_limit: [max: 100, window_ms: 60_000]

Algorithm

Token bucket with self-refilling tokens. On each request:

  1. Read bucket state {key, tokens, last_refilled_at}
  2. Calculate new tokens based on elapsed time since last refill
  3. Cap at max (burst capacity)
  4. If >= 1 token available: consume one, write new state
  5. If no tokens: return {:error, :rate_limited, retry_after_ms}

Summary

Functions

check(opts \\ [])

Checks if a request is within configured rate limits.

init()

Initializes the ETS table. Idempotent — safe to call multiple times.

reset()

Resets all rate limit buckets. Useful for testing.

Functions

check(opts \\ [])

@spec check(keyword()) :: :ok | {:error, :rate_limited, non_neg_integer()}

Checks if a request is within configured rate limits.

Options

  • :max — Maximum token capacity (burst limit). Default: 100
  • :window_ms — Refill window in milliseconds. Default: 60_000
  • :key — Bucket identifier. Default: :global

Returns

  • :ok — Request allowed, one token consumed
  • {:error, :rate_limited, retry_after_ms} — Denied, suggests retry delay

init()

@spec init() :: :ok

Initializes the ETS table. Idempotent — safe to call multiple times.

reset()

@spec reset() :: :ok

Resets all rate limit buckets. Useful for testing.