types

Documentation

Overview

Package types defines shared rate limit configuration types.

+kubebuilder:object:generate=true +groupName=toolhive.stacklok.dev +versionName=ratelimit

Index

• type RateLimitBucket
  • func (in *RateLimitBucket) DeepCopy() *RateLimitBucket
  • func (in *RateLimitBucket) DeepCopyInto(out *RateLimitBucket)
• type RateLimitConfig
  • func (in *RateLimitConfig) DeepCopy() *RateLimitConfig
  • func (in *RateLimitConfig) DeepCopyInto(out *RateLimitConfig)
• type ToolRateLimitConfig
  • func (in *ToolRateLimitConfig) DeepCopy() *ToolRateLimitConfig
  • func (in *ToolRateLimitConfig) DeepCopyInto(out *ToolRateLimitConfig)

Types

type RateLimitBucket

type RateLimitBucket struct {
	// MaxTokens is the maximum number of tokens (bucket capacity).
	// This is also the burst size: the maximum number of requests that can be served
	// instantaneously before the bucket is depleted.
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:Minimum=1
	MaxTokens int32 `json:"maxTokens" yaml:"maxTokens"`

	// RefillPeriod is the duration to fully refill the bucket from zero to maxTokens.
	// The effective refill rate is maxTokens / refillPeriod tokens per second.
	// Format: Go duration string (e.g., "1m0s", "30s", "1h0m0s").
	// +kubebuilder:validation:Required
	RefillPeriod metav1.Duration `json:"refillPeriod" yaml:"refillPeriod"`
}

RateLimitBucket defines a token bucket configuration with a maximum capacity and a refill period. Used by both shared and per-user rate limits. +gendoc

func (*RateLimitBucket) DeepCopy

func (in *RateLimitBucket) DeepCopy() *RateLimitBucket

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new RateLimitBucket.

func (*RateLimitBucket) DeepCopyInto

func (in *RateLimitBucket) DeepCopyInto(out *RateLimitBucket)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type RateLimitConfig

type RateLimitConfig struct {
	// Shared is a token bucket shared across all users for the entire server.
	// +optional
	Shared *RateLimitBucket `json:"shared,omitempty" yaml:"shared,omitempty"`

	// PerUser is a token bucket applied independently to each authenticated user
	// at the server level. Requires authentication to be enabled.
	// Each unique userID creates Redis keys that expire after 2x refillPeriod.
	// Memory formula: unique_users_per_TTL_window * (1 + num_tools_with_per_user_limits) keys.
	// +optional
	PerUser *RateLimitBucket `json:"perUser,omitempty" yaml:"perUser,omitempty"`

	// Tools defines per-tool rate limit overrides.
	// Each entry applies additional rate limits to calls targeting a specific tool name.
	// A request must pass both the server-level limit and the per-tool limit.
	// +listType=map
	// +listMapKey=name
	// +optional
	Tools []ToolRateLimitConfig `json:"tools,omitempty" yaml:"tools,omitempty"`
}

RateLimitConfig defines rate limiting configuration for an MCP server. At least one of shared, perUser, or tools must be configured.

+kubebuilder:validation:XValidation:rule="has(self.shared) || has(self.perUser) || (has(self.tools) && size(self.tools) > 0)",message="at least one of shared, perUser, or tools must be configured" +gendoc

func (*RateLimitConfig) DeepCopy

func (in *RateLimitConfig) DeepCopy() *RateLimitConfig

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new RateLimitConfig.

func (*RateLimitConfig) DeepCopyInto

func (in *RateLimitConfig) DeepCopyInto(out *RateLimitConfig)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.

type ToolRateLimitConfig

type ToolRateLimitConfig struct {
	// Name is the MCP tool name this limit applies to.
	// +kubebuilder:validation:Required
	// +kubebuilder:validation:MinLength=1
	Name string `json:"name" yaml:"name"`

	// Shared token bucket for this specific tool.
	// +optional
	Shared *RateLimitBucket `json:"shared,omitempty" yaml:"shared,omitempty"`

	// PerUser token bucket configuration for this tool.
	// +optional
	PerUser *RateLimitBucket `json:"perUser,omitempty" yaml:"perUser,omitempty"`
}

ToolRateLimitConfig defines rate limits for a specific tool. At least one of shared or perUser must be configured.

+kubebuilder:validation:XValidation:rule="has(self.shared) || has(self.perUser)",message="at least one of shared or perUser must be configured" +gendoc

func (*ToolRateLimitConfig) DeepCopy

func (in *ToolRateLimitConfig) DeepCopy() *ToolRateLimitConfig

DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new ToolRateLimitConfig.

func (*ToolRateLimitConfig) DeepCopyInto

func (in *ToolRateLimitConfig) DeepCopyInto(out *ToolRateLimitConfig)

DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil.