Interface McpRateLimiter

Functional Interface:
This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.
@ThreadSafe @FunctionalInterface public interface McpRateLimiter
Thread-safe application rate limiter for MCP requests or tool invocations.

Soklet invokes the configured request limiter once for each admitted request or notification. It additionally invokes the resolved tool limiter for a tool call when one is configured. A null result or exception fails closed. Successful acquisitions are never refunded after later denial, failure, cancelation, timeout, or response-write failure. Small, valid, owner-verified 2025 session ping, unsubscribe, initialized and cancellation messages instead use independent bounded framework control quotas. Their bodies must be at most 16 KiB; fresh admission and session verification still apply. See McpServer.Builder.requestRateLimiter(McpRateLimiter).

Implementations may keep state in-process or delegate to a distributed service. Soklet does not own or close application-supplied limiters.

Author:
Mark Allen

  • Method Details

    • acquire

      @NonNull McpRateLimitDecision acquire(@NonNull McpRateLimitContext rateLimitContext) throws Exception
      Attempts to acquire permission for one request or tool invocation.
      Parameters:
      rateLimitContext - immutable rate-limit context
      Returns:
      a non-null allowed or denied decision
      Throws:
      Exception - if the backing rate-limit service fails

    • fromInMemoryTokenBucket

      static @NonNull McpRateLimiter fromInMemoryTokenBucket(@NonNull McpTokenBucketConfig tokenBucketConfig)
      Creates Soklet's built-in in-memory token-bucket limiter.

      The returned limiter partitions state by normalized endpoint path, the accepted admission identity's stable rate-limit partition key, and the context target. Retained partition state is bounded. At capacity, one acquisition examines a bounded rotating sample of retained partitions and reclaims the first fully replenished one it finds. A new partition fails closed when that sample contains none, even if another reclaimable partition exists outside the current sample. The limiter is local to this JVM and provides no cross-instance coordination.

      Parameters:
      tokenBucketConfig - finite token-bucket configuration
      Returns:
      a new independent in-memory limiter