Documentation
¶
Overview ¶
Package ratelimit provides token-bucket rate limiting for MCP servers.
The public API consists of the Limiter interface, Decision result type, and NewLimiter constructor. The token bucket implementation is internal.
Index ¶
- Constants
- func Allow(ctx context.Context, limiter Limiter, identity *auth.Identity, toolName string) error
- func CreateMiddleware(config *types.MiddlewareConfig, runner types.MiddlewareRunner) error
- func NewMiddleware(params MiddlewareParams) (types.Middleware, error)
- type Decision
- type Limiter
- type MiddlewareParams
- type RateLimitedError
Constants ¶
const ( // CodeRateLimited is the JSON-RPC error code for rate-limited requests. // Per RFC THV-0057: implementation-defined code in the -32000 to -32099 range. CodeRateLimited int64 = -32029 // MessageRateLimited is the error message for rate-limited requests. MessageRateLimited = "Rate limit exceeded" )
const (
// MiddlewareType is the type constant for the rate limit middleware.
MiddlewareType = "ratelimit"
)
Variables ¶
This section is empty.
Functions ¶
func CreateMiddleware ¶ added in v0.17.0
func CreateMiddleware(config *types.MiddlewareConfig, runner types.MiddlewareRunner) error
CreateMiddleware is the factory function for rate limit middleware.
func NewMiddleware ¶ added in v0.30.0
func NewMiddleware(params MiddlewareParams) (types.Middleware, error)
NewMiddleware creates a Redis-backed rate limit middleware from typed params.
Types ¶
type Decision ¶
type Decision struct {
// Allowed is true when the request may proceed.
Allowed bool
// RetryAfter is populated when Allowed is false.
// It indicates the minimum wait before the next request may succeed.
RetryAfter time.Duration
}
Decision holds the result of a rate limit check.
type Limiter ¶
type Limiter interface {
// Allow checks whether a request is permitted.
// toolName is the MCP tool being called (empty for non-tool requests).
// userID is the authenticated user (empty for unauthenticated requests).
Allow(ctx context.Context, toolName, userID string) (*Decision, error)
}
Limiter checks rate limits for an MCP server.
func NewLimiter ¶
func NewLimiter(client redis.Cmdable, namespace, name string, crd *v1beta1.RateLimitConfig) (Limiter, error)
NewLimiter constructs a Limiter from CRD configuration. Returns a no-op limiter (always allows) when crd is nil. namespace and name identify the MCP server for Redis key derivation.
func NewRedisLimiter ¶ added in v0.33.0
func NewRedisLimiter(params MiddlewareParams) (Limiter, io.Closer, error)
NewRedisLimiter creates a Redis-backed rate limiter from typed params.
type MiddlewareParams ¶ added in v0.17.0
type MiddlewareParams struct {
Namespace string `json:"namespace"`
ServerName string `json:"server_name"`
Config *v1beta1.RateLimitConfig `json:"config"`
RedisAddr string `json:"redis_addr,omitempty"`
RedisDB int32 `json:"redis_db,omitempty"`
}
MiddlewareParams holds the parameters for the rate limit middleware factory.
type RateLimitedError ¶ added in v0.33.0
RateLimitedError reports that a request exceeded its configured rate limit.
func (*RateLimitedError) Code ¶ added in v0.33.0
func (*RateLimitedError) Code() int64
Code returns the ToolHive JSON-RPC-compatible code for rate-limited requests.
func (*RateLimitedError) Data ¶ added in v0.33.0
func (e *RateLimitedError) Data() map[string]any
Data returns structured retry metadata for transport adapters that cannot emit a custom JSON-RPC error object from the tool-handler seam.
func (*RateLimitedError) Error ¶ added in v0.33.0
func (*RateLimitedError) Error() string
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
internal
|
|
|
bucket
Package bucket implements the token bucket algorithm backed by Redis.
|
Package bucket implements the token bucket algorithm backed by Redis. |
|
Package types defines shared rate limit configuration types.
|
Package types defines shared rate limit configuration types. |