middleware

package
v0.0.0-...-84db50f Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 28, 2026 License: Apache-2.0 Imports: 60 Imported by: 0

Documentation

Overview

Package middleware provides HTTP middleware for the application.

Index

Constants

View Source 
const HTTPRequestContextKey contextKey = "http.request"

HTTPRequestContextKey is the context key for the HTTP request.

Summary: Context key used to store the original HTTP request.

View Source 
const RedisRateLimitScript = `` /* 1550-byte string literal not displayed */

RedisRateLimitScript is the Lua script executed atomically in Redis to perform token bucket updates. It handles token refill based on time elapsed, checks against burst capacity, and manages the expiration of unused keys to prevent memory leaks in Redis.

Variables

This section is empty.

Functions

func AuthMiddleware 

func AuthMiddleware(authManager *auth.Manager) mcp.Middleware

AuthMiddleware creates an MCP middleware for handling authentication.

It is intended to inspect incoming requests and use the provided `AuthManager` to verify credentials before passing the request to the next handler.

Parameters:

  • authManager (*auth.Manager): The authentication manager.

Returns:

  • mcp.Middleware: The authentication middleware function.

Side Effects:

  • Modifies the context to include authenticated user info.

func CORSMiddleware 

func CORSMiddleware() mcp.Middleware

CORSMiddleware creates an MCP middleware for handling Cross-Origin Resource Sharing (CORS). It is intended to add the necessary CORS headers to outgoing responses, allowing web browsers to securely make cross-origin requests to the MCP server.

NOTE: This middleware is currently a placeholder for MCP-level (JSON-RPC) interception and does not handle HTTP CORS headers. HTTP CORS is handled by the dedicated HTTP middleware in cors_http.go.

Summary: Creates a placeholder MCP CORS middleware.

Returns:

  • (mcp.Middleware): The middleware function.

func CalculateToolResultTokens 

func CalculateToolResultTokens(t tokenizer.Tokenizer, result any) int

CalculateToolResultTokens calculates the number of tokens in a tool result.

Parameters:

  • t: tokenizer.Tokenizer. The tokenizer to use for counting.
  • result: any. The result object to analyze (can be *mcp.CallToolResult, string, []byte, or others).

Returns:

  • int: The estimated token count.

func DLPMiddleware 

func DLPMiddleware(config *configv1.DLPConfig, log *slog.Logger) mcp.Middleware

DLPMiddleware creates a middleware that redacts PII from request arguments and result content.

Summary: Middleware for Data Loss Prevention (PII redaction).

Parameters:

  • config (*configv1.DLPConfig): The DLP configuration settings.
  • log (*slog.Logger): The logger for reporting errors.

Returns:

  • mcp.Middleware: The configured middleware function.

func DebugMiddleware 

func DebugMiddleware() mcp.Middleware

DebugMiddleware returns a middleware function that logs the full request and response of each MCP method call. This is useful for debugging and understanding the flow of data through the server.

Parameters:

  • None

Returns:

  • mcp.Middleware: The resulting mcp.Middleware.

Errors:

  • None

Side Effects:

  • None

func GetHTTPMiddlewares 

func GetHTTPMiddlewares(configs []*configv1.Middleware) []func(http.Handler) http.Handler

GetHTTPMiddlewares returns a sorted list of HTTP middlewares based on configuration.

Parameters:

  • configs ([]*configv1.Middleware): The configs.

Returns:

  • ([]func(http.Handler) http.Handler): The result.

func GetMCPMiddlewares 

func GetMCPMiddlewares(configs []*configv1.Middleware) []func(mcp.MethodHandler) mcp.MethodHandler

GetMCPMiddlewares returns a sorted list of MCP middlewares based on configuration.

Parameters:

  • configs ([]*configv1.Middleware): The configs.

Returns:

  • ([]func(mcp.MethodHandler) mcp.MethodHandler): The result.

func GetParentID 

func GetParentID(ctx context.Context) string

GetParentID returns the parent span ID from the context.

Summary: Retrieves the parent span ID from the context.

Parameters:

  • ctx: context.Context. The context to check.

Returns:

  • string: The parent ID if present, otherwise an empty string.

func GetSpanID 

func GetSpanID(ctx context.Context) string

GetSpanID returns the span ID from the context.

Summary: Retrieves the span ID from the context.

Parameters:

  • ctx: context.Context. The context to check.

Returns:

  • string: The span ID if present, otherwise an empty string.

func GetTraceID 

func GetTraceID(ctx context.Context) string

GetTraceID returns the trace ID from the context.

Summary: Retrieves the trace ID from the context.

Parameters:

  • ctx: context.Context. The context to check.

Returns:

  • string: The trace ID if present, otherwise an empty string.

func GzipCompressionMiddleware 

func GzipCompressionMiddleware(next http.Handler) http.Handler

GzipCompressionMiddleware returns a middleware that compresses HTTP responses using Gzip.

Summary: Middleware that compresses HTTP responses using Gzip if supported by the client.

Parameters:

  • next: http.Handler. The next handler in the chain.

Returns:

  • http.Handler: The wrapped handler that performs compression.

Side Effects:

  • Intercepts the response writer to buffer and compress content.
  • Modifies the Content-Encoding header.

func HTTPSecurityHeadersMiddleware 

func HTTPSecurityHeadersMiddleware(next http.Handler) http.Handler

HTTPSecurityHeadersMiddleware adds security headers to HTTP responses.

Summary: Middleware that adds standard security headers to all HTTP responses.

Parameters:

  • next: http.Handler. The next handler in the chain.

Returns:

  • http.Handler: The wrapped handler that sets security headers.

func JSONRPCComplianceMiddleware 

func JSONRPCComplianceMiddleware(next http.Handler) http.Handler

JSONRPCComplianceMiddleware ensures that errors are returned as valid JSON-RPC responses.

Summary: Wraps non-JSON error responses in a JSON-RPC error format.

Parameters:

  • next: http.Handler. The next handler in the chain.

Returns:

  • http.Handler: The wrapped handler that enforces JSON-RPC compliance for errors.

Side Effects:

  • Intercepts and rewrites HTTP response bodies for error status codes.

func LoggingMiddleware 

func LoggingMiddleware(log *slog.Logger) mcp.Middleware

LoggingMiddleware creates an MCP middleware that logs information about each incoming request. It records the start and completion of each request, including the duration of the handling.

This is useful for debugging and monitoring the flow of requests through the server.

Parameters:

  • log (*slog.Logger): The logger to be used. If `nil`, the default global logger will be used.

Returns:

  • mcp.Middleware: The logging middleware function.

Side Effects:

  • Logs request start and end.
  • Updates metrics.

func NewGuardrailsMiddleware 

func NewGuardrailsMiddleware(config GuardrailsConfig) gin.HandlerFunc

NewGuardrailsMiddleware creates a new Guardrails middleware.

Summary: Initializes the guardrails middleware for blocking malicious prompts.

Parameters:

  • config: GuardrailsConfig. The configuration for blocking patterns.

Returns:

  • gin.HandlerFunc: The Gin middleware handler.

func PrometheusMetricsMiddleware 

func PrometheusMetricsMiddleware(t tokenizer.Tokenizer) mcp.Middleware

PrometheusMetricsMiddleware provides protocol-level metrics for all MCP requests. It intercepts requests to track duration, success/failure counts, payload sizes, and token counts.

Parameters:

  • t (tokenizer.Tokenizer): The t parameter.

Returns:

  • mcp.Middleware: The resulting mcp.Middleware.

Errors:

  • None

Side Effects:

  • None

func RecoveryMiddleware 

func RecoveryMiddleware(next http.Handler) http.Handler

RecoveryMiddleware recovers from panics in the handler chain, logs the panic, and returns a generic 500 Internal Server Error response.

Summary: Middleware to recover from panics.

Parameters:

  • next (http.Handler): The next handler in the chain.

Returns:

  • http.Handler: A handler that wraps the next handler with recovery logic.

Side Effects:

  • Logs panic details if a panic occurs.
  • Writes a 500 Internal Server Error response to the client on panic.

func Register 

func Register(name string, factory Factory)

Register registers a HTTP middleware factory.

Parameters:

  • name (string): The name of the resource.
  • factory (Factory): The factory.

func RegisterMCP 

func RegisterMCP(name string, factory MCPFactory)

RegisterMCP registers an MCP middleware factory.

Parameters:

  • name (string): The name of the resource.
  • factory (MCPFactory): The factory.

func SSOMiddleware 

func SSOMiddleware(config SSOConfig) gin.HandlerFunc

SSOMiddleware creates a new SSO middleware.

Summary: Middleware that enforces SSO authentication via trusted headers or bearer tokens.

Parameters:

  • config: SSOConfig. The configuration settings for SSO.

Returns:

  • gin.HandlerFunc: The Gin middleware handler.

Side Effects:

  • Inspects headers for authentication information.
  • Aborts the request with 401 Unauthorized if authentication is missing or invalid.
  • Sets "UserID" in the context on successful authentication.

func SetRedisClientCreatorForTests 

func SetRedisClientCreatorForTests(creator func(opts *redis.Options) *redis.Client)

SetRedisClientCreatorForTests allows injecting a mock Redis client creator for testing purposes.

Summary: Replaces the default Redis client creator with a mock for unit testing.

Parameters:

  • creator: func(*redis.Options) *redis.Client. The factory function to create Redis clients.

Side Effects:

  • Modifies the global redisClientCreator variable.

func WithTraceContext 

func WithTraceContext(ctx context.Context, traceID, spanID, parentID string) context.Context

WithTraceContext returns a new context with trace information.

Summary: Injects trace, span, and parent IDs into the context.

Parameters:

  • ctx: context.Context. The parent context.
  • traceID: string. The unique identifier for the trace.
  • spanID: string. The unique identifier for the current span.
  • parentID: string. The unique identifier for the parent span (optional).

Returns:

  • context.Context: The new context with trace information attached.

Types

type AuditMiddleware 

type AuditMiddleware struct {
	// contains filtered or unexported fields
}

AuditMiddleware provides audit logging for tool executions.

Summary: Middleware for auditing tool execution.

func NewAuditMiddleware 

func NewAuditMiddleware(auditConfig *configv1.AuditConfig) (*AuditMiddleware, error)

NewAuditMiddleware creates a new AuditMiddleware.

Summary: Initializes the audit middleware with the provided configuration.

Parameters:

  • auditConfig (*configv1.AuditConfig): The configuration for audit logging.

Returns:

  • *AuditMiddleware: The initialized middleware instance.
  • error: An error if the middleware cannot be initialized.

Errors:

  • Returns error if audit store initialization fails.

Side Effects:

  • Initializes internal stores and redactor.

func (*AuditMiddleware) Close 

func (m *AuditMiddleware) Close() error

Close closes the underlying store.

Summary: Closes the audit store.

Returns:

  • error: An error if the operation fails.

Side Effects:

  • Closes the audit store connection.

func (*AuditMiddleware) Execute 

func (m *AuditMiddleware) Execute(ctx context.Context, req *tool.ExecutionRequest, next tool.ExecutionFunc) (any, error)

Execute intercepts tool execution to log audit events.

Summary: Intercepts and logs tool execution requests and results.

Parameters:

  • ctx (context.Context): The context for the request.
  • req (*tool.ExecutionRequest): The tool execution request.
  • next (tool.ExecutionFunc): The next handler in the chain.

Returns:

  • any: The result of the tool execution.
  • error: An error if the tool execution fails.

Side Effects:

  • Writes an audit log entry to the configured store.

func (*AuditMiddleware) GetHistory 

func (m *AuditMiddleware) GetHistory() []any

GetHistory returns the current broadcast history.

Summary: Retrieves the audit history from the broadcaster.

Returns:

  • []any: A slice of audit entries.

Side Effects:

  • None.

func (*AuditMiddleware) Read 

func (m *AuditMiddleware) Read(ctx context.Context, filter audit.Filter) ([]audit.Entry, error)

Read reads audit entries from the underlying store.

Summary: Reads historical audit logs from storage.

Parameters:

  • ctx (context.Context): The context for the request.
  • filter (audit.Filter): The filter criteria for querying logs.

Returns:

  • []audit.Entry: A slice of audit entries matching the filter.
  • error: An error if reading fails.

Errors:

  • Returns error if store is not initialized.

Side Effects:

  • Reads from the audit store.

func (*AuditMiddleware) SetStore 

func (m *AuditMiddleware) SetStore(store audit.Store)

SetStore sets the audit store. This is primarily used for testing.

Summary: Sets the audit store implementation.

Parameters:

  • store (audit.Store): The audit store to use.

Side Effects:

  • Replaces the current audit store.

func (*AuditMiddleware) SubscribeWithHistory 

func (m *AuditMiddleware) SubscribeWithHistory() (chan any, []any)

SubscribeWithHistory returns a channel that will receive broadcast messages, and the current history of messages.

Summary: Subscribes to audit events with history.

Returns:

  • chan any: A channel receiving new audit entries.
  • []any: A slice of historical audit entries.

Side Effects:

  • Adds a new subscriber to the broadcaster.

func (*AuditMiddleware) Unsubscribe 

func (m *AuditMiddleware) Unsubscribe(ch chan any)

Unsubscribe removes a subscriber channel.

Summary: Unsubscribes from audit events.

Parameters:

  • ch (chan any): The channel to unsubscribe.

Side Effects:

  • Removes the subscriber from the broadcaster.

func (*AuditMiddleware) UpdateConfig 

func (m *AuditMiddleware) UpdateConfig(auditConfig *configv1.AuditConfig) error

UpdateConfig updates the audit configuration safely.

Summary: Updates the middleware configuration and re-initializes the store if needed.

Parameters:

  • auditConfig (*configv1.AuditConfig): The new configuration.

Returns:

  • error: An error if the store re-initialization fails.

Errors:

  • Returns error if store re-initialization fails.

Side Effects:

  • May close existing store and open a new one.
  • Updates redactor configuration.

type CSRFMiddleware 

type CSRFMiddleware struct {
	// contains filtered or unexported fields
}

CSRFMiddleware protects against Cross-Site Request Forgery attacks.

Summary: Middleware that blocks unauthorized cross-origin requests.

func NewCSRFMiddleware 

func NewCSRFMiddleware(allowedOrigins []string) *CSRFMiddleware

NewCSRFMiddleware creates a new CSRFMiddleware.

Summary: Initializes a new CSRFMiddleware with a list of allowed origins.

Parameters:

  • allowedOrigins: []string. A list of origin strings (e.g., "https://example.com") allowed to make requests.

Returns:

  • *CSRFMiddleware: The initialized middleware.

Side Effects:

  • Populates the internal allowed origins map.

func (*CSRFMiddleware) Handler 

func (m *CSRFMiddleware) Handler(next http.Handler) http.Handler

Handler returns the HTTP handler.

Summary: Returns an HTTP handler that enforces CSRF protection checks.

Parameters:

  • next: http.Handler. The next handler in the chain.

Returns:

  • http.Handler: The wrapped handler.

Side Effects:

  • Inspects Method, Headers, Origin, and Referer of incoming requests.
  • Blocks requests with 403 Forbidden if validation fails.
  • Logs warnings for blocked requests.

func (*CSRFMiddleware) Update 

func (m *CSRFMiddleware) Update(origins []string)

Update updates the allowed origins.

Summary: Updates the list of allowed origins at runtime.

Parameters:

  • origins: []string. The new list of allowed origins.

Side Effects:

  • Replaces the existing allowed origins map in a thread-safe manner.

type CachingMiddleware 

type CachingMiddleware struct {
	// contains filtered or unexported fields
}

CachingMiddleware handles caching of tool execution results.

func NewCachingMiddleware 

func NewCachingMiddleware(toolManager tool.ManagerInterface) *CachingMiddleware

NewCachingMiddleware creates a new CachingMiddleware. toolManager is the toolManager. Returns the result.

Parameters:

  • toolManager (tool.ManagerInterface): The toolManager parameter.

Returns:

  • *CachingMiddleware: The resulting *CachingMiddleware.

Errors:

  • None

Side Effects:

  • None

func (*CachingMiddleware) Clear 

func (m *CachingMiddleware) Clear(ctx context.Context) error

Clear clears the cache. ctx is the context for the request. Returns an error if the operation fails.

Parameters:

  • ctx (context.Context): The context for the request.

Returns:

  • error: An error if the operation fails.

Errors:

  • Returns an error if the operation fails or is invalid.

Side Effects:

  • None

func (*CachingMiddleware) Execute 

func (m *CachingMiddleware) Execute(ctx context.Context, req *tool.ExecutionRequest, next tool.ExecutionFunc) (any, error)

Execute executes the caching middleware. ctx is the context for the request. req is the request object. next is the next. Returns the result. Returns an error if the operation fails.

Parameters:

  • ctx (context.Context): The context for the request.
  • req (*tool.ExecutionRequest): The request object.
  • next (tool.ExecutionFunc): The next parameter.

Returns:

  • any: The resulting any.
  • error: An error if the operation fails.

Errors:

  • Returns an error if the operation fails or is invalid.

Side Effects:

  • None

func (*CachingMiddleware) SetProviderFactory 

func (m *CachingMiddleware) SetProviderFactory(factory ProviderFactory)

SetProviderFactory allows overriding the default provider factory for testing. factory is the factory.

Parameters:

  • factory (ProviderFactory): The factory parameter.

Returns:

  • None

Errors:

  • None

Side Effects:

  • None

type CallPolicyMiddleware 

type CallPolicyMiddleware struct {
	// contains filtered or unexported fields
}

CallPolicyMiddleware is a middleware that enforces call policies (allow/deny) based on tool name and arguments.

Summary: Middleware that evaluates and enforces security policies for tool executions.

func NewCallPolicyMiddleware 

func NewCallPolicyMiddleware(toolManager tool.ManagerInterface) *CallPolicyMiddleware

NewCallPolicyMiddleware creates a new CallPolicyMiddleware.

Summary: Initializes a new CallPolicyMiddleware.

Parameters:

  • toolManager: tool.ManagerInterface. The tool manager to access tool and service information.

Returns:

  • *CallPolicyMiddleware: The initialized middleware.

func (*CallPolicyMiddleware) Execute 

func (m *CallPolicyMiddleware) Execute(ctx context.Context, req *tool.ExecutionRequest, next tool.ExecutionFunc) (any, error)

Execute enforces call policies before proceeding to the next handler.

Summary: Checks if the tool execution is allowed by the service's policies.

Parameters:

  • ctx: context.Context. The execution context.
  • req: *tool.ExecutionRequest. The tool execution request.
  • next: tool.ExecutionFunc. The next handler in the chain.

Returns:

  • any: The execution result if allowed.
  • error: An error if the policy blocks execution or policy evaluation fails.

Errors:

  • Returns error if service info is not found (fail closed).
  • Returns error if policy evaluation fails.
  • Returns "execution denied by policy" if the policy denies the request.

Side Effects:

  • Logs errors if service info is missing or policy evaluation fails.
  • Increments a metric counter when a call is blocked.

type ContextOptimizer 

type ContextOptimizer struct {
	MaxChars int
}

ContextOptimizer optimises the context size of responses.

Summary: Middleware that truncates excessively long string values in JSON responses to fit within a context window.

func NewContextOptimizer 

func NewContextOptimizer(maxChars int) *ContextOptimizer

NewContextOptimizer creates a new ContextOptimizer.

Summary: Initializes a new ContextOptimizer with a maximum character limit.

Parameters:

  • maxChars: int. The maximum allowed number of characters for string values in the JSON response.

Returns:

  • *ContextOptimizer: The initialized optimizer.

func (*ContextOptimizer) Handler 

func (co *ContextOptimizer) Handler(next http.Handler) http.Handler

Handler returns the middleware handler.

Summary: Returns an HTTP handler that intercepts and potentially truncates response bodies.

Parameters:

  • next: http.Handler. The next handler in the chain.

Returns:

  • http.Handler: The wrapped handler.

Side Effects:

  • Buffers the entire response body.
  • Modifies the response body if it contains JSON strings exceeding MaxChars.
  • Updates the Content-Length header.

type DebugEntry 

type DebugEntry struct {
	ID              string        `json:"id"`
	TraceID         string        `json:"trace_id"`
	SpanID          string        `json:"span_id"`
	ParentID        string        `json:"parent_id,omitempty"`
	Timestamp       time.Time     `json:"timestamp"`
	Method          string        `json:"method"`
	Path            string        `json:"path"`
	Status          int           `json:"status"`
	Duration        time.Duration `json:"duration"`
	RequestHeaders  http.Header   `json:"request_headers"`
	ResponseHeaders http.Header   `json:"response_headers"`
	RequestBody     string        `json:"request_body,omitempty"`
	ResponseBody    string        `json:"response_body,omitempty"`
}

DebugEntry represents a captured HTTP request/response.

Summary: Data structure holding details of a captured HTTP transaction.

type Debugger 

type Debugger struct {
	// contains filtered or unexported fields
}

Debugger monitors and records traffic for inspection.

Summary: Middleware that captures recent HTTP traffic for debugging purposes.

func NewDebugger 

func NewDebugger(size int) *Debugger

NewDebugger creates a new Debugger middleware.

Summary: Initializes the debugger with a fixed-size ring buffer.

Parameters:

  • size: int. The number of recent requests to keep in memory.

Returns:

  • *Debugger: The initialized debugger.

Side Effects:

  • Starts a background goroutine to process debug entries.

func (*Debugger) APIHandler 

func (d *Debugger) APIHandler() http.HandlerFunc

APIHandler returns a http.HandlerFunc to view entries.

Summary: Returns an HTTP handler that exposes the debug entries as JSON.

Returns:

  • http.HandlerFunc: The API handler function.

Side Effects:

  • Encodes the entries to JSON and writes to the response.

func (*Debugger) Close 

func (d *Debugger) Close()

Close stops the background processor. Summary: Shuts down the debugger and releases resources. Side Effects: - Closes the ingress channel. - Waits for the background processor to finish.

Parameters:

  • None

Returns:

  • None

Errors:

  • None

Side Effects:

  • None

func (*Debugger) Entries 

func (d *Debugger) Entries() []DebugEntry

Entries returns the last captured entries.

Summary: Retrieves the list of captured debug entries from the ring buffer.

Returns:

  • []DebugEntry: A slice of the most recent captured requests and responses.

Side Effects:

  • Acquires a read lock on the ring buffer.

func (*Debugger) Handler 

func (d *Debugger) Handler(next http.Handler) http.Handler

Handler returns the http handler.

Summary: Returns an HTTP handler that captures traffic.

Parameters:

  • next: http.Handler. The next handler in the chain.

Returns:

  • http.Handler: The wrapped handler.

Side Effects:

  • Intercepts HTTP requests and responses.
  • Generates trace and span IDs if missing.
  • Captures request and response bodies (truncated).
  • Sends debug entries to the ingress channel.

type EmbeddingProvider 

type EmbeddingProvider interface {
	// Embed generates an embedding vector for the given text.
	//
	// Parameters:
	//   - ctx: context.Context. The request context.
	//   - text: string. The text to embed.
	//
	// Returns:
	//   - []float32: The resulting embedding vector.
	//   - error: An error if generation fails.
	Embed(ctx context.Context, text string) ([]float32, error)
}

EmbeddingProvider defines the interface for fetching text embeddings.

Summary: Interface for services that can generate vector embeddings from text.

type Factory 

type Factory func(config *configv1.Middleware) func(http.Handler) http.Handler

Factory is a function that creates a HTTP middleware from configuration.

type GlobalRateLimitMiddleware 

type GlobalRateLimitMiddleware struct {
	// contains filtered or unexported fields
}

GlobalRateLimitMiddleware provides rate limiting functionality for all MCP requests.

Summary: Middleware that enforces global rate limits on MCP requests across the entire server.

func NewGlobalRateLimitMiddleware 

func NewGlobalRateLimitMiddleware(config *configv1.RateLimitConfig) *GlobalRateLimitMiddleware

NewGlobalRateLimitMiddleware creates a new GlobalRateLimitMiddleware.

Summary: Initializes the global rate limit middleware with the provided configuration.

Parameters:

  • config: *configv1.RateLimitConfig. The rate limit configuration settings.

Returns:

  • *GlobalRateLimitMiddleware: The initialized middleware instance.

Side Effects:

  • Initializes internal caches for limiters.

func (*GlobalRateLimitMiddleware) Execute 

func (m *GlobalRateLimitMiddleware) Execute(ctx context.Context, method string, req mcp.Request, next mcp.MethodHandler) (mcp.Result, error)

Execute executes the rate limiting middleware.

Summary: Intercepts requests and enforces the configured rate limits.

Parameters:

  • ctx: context.Context. The request context.
  • method: string. The MCP method being called.
  • req: mcp.Request. The request payload.
  • next: mcp.MethodHandler. The next handler in the chain.

Returns:

  • mcp.Result: The result of the next handler if allowed.
  • error: An error if the rate limit is exceeded or the next handler fails.

Errors:

  • Returns "global rate limit exceeded" if the request is blocked.

Side Effects:

  • Records metrics for allowed and blocked requests.
  • May update the state of the rate limiter (e.g., consume tokens).

func (*GlobalRateLimitMiddleware) UpdateConfig 

func (m *GlobalRateLimitMiddleware) UpdateConfig(config *configv1.RateLimitConfig)

UpdateConfig updates the rate limit configuration safely.

Summary: Updates the rate limit configuration at runtime.

Parameters:

  • config: *configv1.RateLimitConfig. The new configuration settings.

Side Effects:

  • Acquires a lock to safely update the configuration.
  • Effectively changes rate limiting behavior for subsequent requests.

type GuardrailsConfig 

type GuardrailsConfig struct {
	BlockedPhrases []string
}

GuardrailsConfig defines patterns to block.

Summary: Configuration for the guardrails middleware.

type HTTPCORSMiddleware 

type HTTPCORSMiddleware struct {
	// contains filtered or unexported fields
}

HTTPCORSMiddleware handles CORS for HTTP endpoints. It is thread-safe and supports dynamic updates.

func NewHTTPCORSMiddleware 

func NewHTTPCORSMiddleware(allowedOrigins []string) *HTTPCORSMiddleware

NewHTTPCORSMiddleware creates a new HTTPCORSMiddleware.

Summary: Initializes HTTP CORS middleware.

If allowedOrigins is empty, it defaults to allowing nothing (or behaving like standard Same-Origin). To allow all, pass []string{"*"}.

Parameters:

  • allowedOrigins ([]string): The allowed origins.

Returns:

  • (*HTTPCORSMiddleware): The initialized middleware.

func (*HTTPCORSMiddleware) Handler 

func (m *HTTPCORSMiddleware) Handler(next http.Handler) http.Handler

Handler wraps an http.Handler with CORS logic.

Summary: Middleware to handle CORS headers.

Parameters:

  • next (http.Handler): The next handler in the chain.

Returns:

  • (http.Handler): The wrapped handler.

func (*HTTPCORSMiddleware) Update 

func (m *HTTPCORSMiddleware) Update(allowedOrigins []string)

Update updates the allowed origins.

Summary: Updates the allowed origins dynamically.

Parameters:

  • allowedOrigins ([]string): The new list of allowed origins.

type HTTPEmbeddingProvider 

type HTTPEmbeddingProvider struct {
	// contains filtered or unexported fields
}

HTTPEmbeddingProvider implements a generic HTTP EmbeddingProvider.

Summary: A generic provider that fetches embeddings from an arbitrary HTTP endpoint.

func NewHTTPEmbeddingProvider 

func NewHTTPEmbeddingProvider(url string, headers map[string]string, bodyTemplateStr, responseJSONPath string) (*HTTPEmbeddingProvider, error)

NewHTTPEmbeddingProvider creates a new HTTPEmbeddingProvider.

Summary: Initializes a new HTTPEmbeddingProvider with custom request formatting.

Parameters:

  • url: string. The API endpoint URL.
  • headers: map[string]string. Custom HTTP headers to include in the request.
  • bodyTemplateStr: string. A Go template string for the request body (input text is available as {{.input}}).
  • responseJSONPath: string. The JSONPath expression to extract the embedding from the response.

Returns:

  • *HTTPEmbeddingProvider: The initialized provider.
  • error: An error if the URL is empty or the body template is invalid.

Errors:

  • Returns "url is required" if the URL is empty.
  • Returns error if template parsing fails.

Side Effects:

  • Compiles the body template.

func (*HTTPEmbeddingProvider) Embed 

func (p *HTTPEmbeddingProvider) Embed(ctx context.Context, text string) ([]float32, error)

Embed generates an embedding for the given text.

Summary: Generates an embedding by sending a templated HTTP request and extracting the result via JSONPath.

Parameters:

  • ctx: context.Context. The request context.
  • text: string. The input text to embed.

Returns:

  • []float32: The extracted embedding vector.
  • error: An error if the request fails or response parsing fails.

Errors:

  • Returns error if template execution fails.
  • Returns error if HTTP request creation or execution fails.
  • Returns error if the API returns a non-success status code.
  • Returns error if JSON unmarshaling or JSONPath extraction fails.
  • Returns error if the extracted result is not a number array or is empty.

Side Effects:

  • Makes an HTTP POST request to the configured URL.

type HTTPRateLimitMiddleware 

type HTTPRateLimitMiddleware struct {
	// contains filtered or unexported fields
}

HTTPRateLimitMiddleware provides global rate limiting for HTTP endpoints.

Summary: Middleware for rate limiting HTTP requests based on IP address.

func NewHTTPRateLimitMiddleware 

func NewHTTPRateLimitMiddleware(rps float64, burst int, opts ...HTTPRateLimitOption) *HTTPRateLimitMiddleware

NewHTTPRateLimitMiddleware creates a new HTTPRateLimitMiddleware.

Summary: Initializes a new HTTP rate limit middleware.

Parameters:

  • rps: float64. Requests per second allowed per IP.
  • burst: int. Maximum burst size allowed per IP.
  • opts: ...HTTPRateLimitOption. Optional configuration options.

Returns:

  • *HTTPRateLimitMiddleware: The initialized middleware instance.

func (*HTTPRateLimitMiddleware) Handler 

func (m *HTTPRateLimitMiddleware) Handler(next http.Handler) http.Handler

Handler wraps an http.Handler with rate limiting.

Summary: Returns a handler that enforces rate limiting.

Parameters:

  • next: http.Handler. The next handler in the chain.

Returns:

  • http.Handler: The wrapped handler.

type HTTPRateLimitOption 

type HTTPRateLimitOption func(*HTTPRateLimitMiddleware)

HTTPRateLimitOption defines a functional option for HTTPRateLimitMiddleware.

Summary: Functional option type for configuring the middleware.

func WithTrustProxy 

func WithTrustProxy(trust bool) HTTPRateLimitOption

WithTrustProxy enables trusting the X-Forwarded-For header.

Summary: Configures the middleware to trust the X-Forwarded-For header.

Parameters:

  • trust: bool. Whether to trust the proxy headers.

Returns:

  • HTTPRateLimitOption: The configuration option.

type IPAllowlistMiddleware 

type IPAllowlistMiddleware struct {
	// contains filtered or unexported fields
}

IPAllowlistMiddleware restricts access to allowed IP addresses.

Summary: Middleware that filters requests based on a list of allowed IP addresses or CIDRs.

func NewIPAllowlistMiddleware 

func NewIPAllowlistMiddleware(allowedCIDRs []string) (*IPAllowlistMiddleware, error)

NewIPAllowlistMiddleware creates a new IPAllowlistMiddleware.

Summary: Initializes the middleware with the initial list of allowed CIDRs.

Parameters:

  • allowedCIDRs: []string. A list of IP addresses or CIDR blocks to allow.

Returns:

  • *IPAllowlistMiddleware: The initialized middleware instance.
  • error: An error if any of the provided CIDRs are invalid.

func (*IPAllowlistMiddleware) Allow 

func (m *IPAllowlistMiddleware) Allow(remoteAddr string) bool

Allow checks if the given remote address is allowed.

Summary: Checks if a remote address is in the allowed list.

Parameters:

  • remoteAddr: string. The remote address (IP or IP:Port).

Returns:

  • bool: True if allowed, false otherwise.

func (*IPAllowlistMiddleware) Handler 

func (m *IPAllowlistMiddleware) Handler(next http.Handler) http.Handler

Handler returns an HTTP handler that enforces the allowlist.

Summary: Returns an HTTP handler that blocks unauthorized IPs.

Parameters:

  • next: http.Handler. The next handler in the chain.

Returns:

  • http.Handler: The wrapped handler.

func (*IPAllowlistMiddleware) Update 

func (m *IPAllowlistMiddleware) Update(allowedCIDRs []string) error

Update updates the allowlist with new CIDRs/IPs.

Summary: Dynamically updates the list of allowed IPs.

Parameters:

  • allowedCIDRs: []string. The new list of allowed IP addresses or CIDR blocks.

Returns:

  • error: An error if any of the provided CIDRs are invalid.

type JSONRPCError 

type JSONRPCError struct {
	Code    int    `json:"code"`
	Message string `json:"message"`
	Data    any    `json:"data,omitempty"`
}

JSONRPCError represents a JSON-RPC 2.0 error object.

type JSONRPCResponse 

type JSONRPCResponse struct {
	JSONRPC string        `json:"jsonrpc"`
	ID      any           `json:"id"`
	Error   *JSONRPCError `json:"error,omitempty"`
}

JSONRPCResponse represents a JSON-RPC 2.0 response object.

type Limiter 

type Limiter interface {
	// Allow checks if the request is allowed.
	//
	// ctx is the context for the request.
	//
	// Returns true if successful.
	// Returns an error if the operation fails.
	Allow(ctx context.Context) (bool, error)
	// AllowN checks if the request is allowed with a specific cost.
	//
	// ctx is the context for the request.
	// n is the n.
	//
	// Returns true if successful.
	// Returns an error if the operation fails.
	AllowN(ctx context.Context, n int) (bool, error)
	// Update updates the limiter configuration.
	//
	// rps is the rps.
	// burst is the burst.
	Update(rps float64, burst int)
}

Limiter interface defines the methods required for a rate limiter.

type LocalLimiter 

type LocalLimiter struct {
	*rate.Limiter
}

LocalLimiter is an in-memory implementation of Limiter.

Summary: Rate limiter implementation using golang.org/x/time/rate.

func (*LocalLimiter) Allow 

func (l *LocalLimiter) Allow(_ context.Context) (bool, error)

Allow checks if the request is allowed (cost 1).

Summary: Checks if a single event is allowed by the rate limiter.

Parameters:

  • _: context.Context. Unused.

Returns:

  • bool: True if allowed, false otherwise.
  • error: Always nil.

Side Effects:

  • Consumes 1 token from the bucket if allowed.

func (*LocalLimiter) AllowN 

func (l *LocalLimiter) AllowN(_ context.Context, n int) (bool, error)

AllowN checks if the request is allowed with a specific cost.

Summary: Checks if N events are allowed by the rate limiter.

Parameters:

  • _: context.Context. Unused.
  • n: int. The cost of the event.

Returns:

  • bool: True if allowed, false otherwise.
  • error: Always nil.

Side Effects:

  • Consumes n tokens from the bucket if allowed.

func (*LocalLimiter) Update 

func (l *LocalLimiter) Update(rps float64, burst int)

Update updates the limiter configuration.

Summary: Dynamically updates the rate limit and burst size.

Parameters:

  • rps: float64. The new requests per second limit.
  • burst: int. The new burst size.

Side Effects:

  • Modifies the underlying rate.Limiter state.

type LocalStrategy 

type LocalStrategy struct{}

LocalStrategy implements RateLimitStrategy for local in-memory rate limiting.

Summary: Strategy for creating local rate limiters.

func NewLocalStrategy 

func NewLocalStrategy() *LocalStrategy

NewLocalStrategy creates a new LocalStrategy.

Summary: Initializes a new LocalStrategy.

Returns:

  • *LocalStrategy: The initialized strategy.

func (*LocalStrategy) Create 

func (s *LocalStrategy) Create(_ context.Context, _, _, _ string, config *configv1.RateLimitConfig) (Limiter, error)

Create creates a new LocalLimiter.

Summary: Creates a new in-memory rate limiter based on the provided configuration.

Parameters:

  • _: context.Context. Unused.
  • _: string. Unused (serviceID).
  • _: string. Unused (limitScopeKey).
  • _: string. Unused (partitionKey).
  • config: *configv1.RateLimitConfig. The rate limit configuration.

Returns:

  • Limiter: The created LocalLimiter.
  • error: Always nil.

Side Effects:

  • Sets a minimum burst of 1 if configured lower.

type MCPFactory 

type MCPFactory func(config *configv1.Middleware) func(mcp.MethodHandler) mcp.MethodHandler

MCPFactory is a function that creates an MCP middleware from configuration.

type OllamaEmbeddingProvider 

type OllamaEmbeddingProvider struct {
	// contains filtered or unexported fields
}

OllamaEmbeddingProvider implements EmbeddingProvider for Ollama.

Summary: Provides an interface to generate text embeddings using the Ollama API.

func NewOllamaEmbeddingProvider 

func NewOllamaEmbeddingProvider(baseURL, model string) *OllamaEmbeddingProvider

NewOllamaEmbeddingProvider creates a new OllamaEmbeddingProvider.

Summary: Initializes a new provider for Ollama embeddings.

Parameters:

  • baseURL: string. The base URL of the Ollama API (defaults to "http://localhost:11434" if empty).
  • model: string. The name of the embedding model to use (defaults to "nomic-embed-text" if empty).

Returns:

  • *OllamaEmbeddingProvider: The initialized embedding provider.

Side Effects:

  • Sets default values for baseURL and model if not provided.

func (*OllamaEmbeddingProvider) Embed 

func (p *OllamaEmbeddingProvider) Embed(ctx context.Context, text string) ([]float32, error)

Embed generates an embedding for the given text using Ollama.

Summary: Calls the Ollama API to generate a vector embedding for the input text.

Parameters:

  • ctx: context.Context. The context for the HTTP request.
  • text: string. The input text to be embedded.

Returns:

  • []float32: The generated embedding vector.
  • error: An error if the API call fails or the response is invalid.

Errors:

  • Returns error if request marshaling or creation fails.
  • Returns error if the HTTP request fails.
  • Returns error if the API returns a non-200 status code.
  • Returns error if response decoding fails or no embedding data is returned.

Side Effects:

  • Makes an HTTP POST request to the configured Ollama API endpoint.

type OpenAIEmbeddingProvider 

type OpenAIEmbeddingProvider struct {
	// contains filtered or unexported fields
}

OpenAIEmbeddingProvider implements EmbeddingProvider for OpenAI.

Summary: Provides vector embeddings using the OpenAI API.

func NewOpenAIEmbeddingProvider 

func NewOpenAIEmbeddingProvider(apiKey, model string) *OpenAIEmbeddingProvider

NewOpenAIEmbeddingProvider creates a new OpenAIEmbeddingProvider.

Summary: Initializes a new OpenAIEmbeddingProvider with the given API key and model.

Parameters:

  • apiKey: string. The OpenAI API key.
  • model: string. The model ID (defaults to "text-embedding-3-small" if empty).

Returns:

  • *OpenAIEmbeddingProvider: The initialized provider.

Side Effects:

  • Sets a default model and base URL.
  • Initializes an HTTP client with a timeout.

func (*OpenAIEmbeddingProvider) Embed 

func (p *OpenAIEmbeddingProvider) Embed(ctx context.Context, text string) ([]float32, error)

Embed generates an embedding vector for the given text using the OpenAI API.

Summary: Calls the OpenAI API to generate an embedding for the input text.

Parameters:

  • ctx: context.Context. The request context.
  • text: string. The text to embed.

Returns:

  • []float32: The generated embedding vector.
  • error: An error if the API call fails.

Errors:

  • Returns error if request marshaling or creation fails.
  • Returns error if the HTTP request fails.
  • Returns error if the API returns a non-200 status code or an error object.
  • Returns error if no embedding data is found in the response.

Side Effects:

  • Makes an external HTTP POST request to the OpenAI API.

type Option 

type Option func(*RateLimitMiddleware)

Option defines a functional option for RateLimitMiddleware.

Summary: Functional option for RateLimitMiddleware.

func WithTokenizer 

func WithTokenizer(t tokenizer.Tokenizer) Option

WithTokenizer sets a custom tokenizer for the middleware.

Summary: Configures a custom tokenizer.

Parameters:

  • t (tokenizer.Tokenizer): The tokenizer to use.

Returns:

  • (Option): The configured option.

type PostgresVectorStore 

type PostgresVectorStore struct {
	// contains filtered or unexported fields
}

PostgresVectorStore implements VectorStore using PostgreSQL and pgvector.

Summary: Provides vector storage capabilities using a PostgreSQL database with the pgvector extension.

func NewPostgresVectorStore 

func NewPostgresVectorStore(dsn string) (*PostgresVectorStore, error)

NewPostgresVectorStore creates a new PostgresVectorStore.

Summary: Initializes a new PostgresVectorStore with a connection string.

Parameters:

  • dsn: string. The Data Source Name for connecting to the PostgreSQL database.

Returns:

  • *PostgresVectorStore: The initialized vector store.
  • error: An error if the DSN is empty or the connection fails.

Errors:

  • Returns "postgres dsn is required" if the dsn is empty.
  • Returns connection errors if sql.Open or NewPostgresVectorStoreWithDB fails.

Side Effects:

  • Opens a connection to the PostgreSQL database.
  • May create the 'vector' extension and 'semantic_cache_entries' table if they do not exist.

func NewPostgresVectorStoreWithDB 

func NewPostgresVectorStoreWithDB(db *sql.DB) (*PostgresVectorStore, error)

NewPostgresVectorStoreWithDB creates a new PostgresVectorStore using an existing database connection.

Summary: Initializes a new PostgresVectorStore with an existing sql.DB connection.

Parameters:

  • db: *sql.DB. The existing database connection.

Returns:

  • *PostgresVectorStore: The initialized vector store.
  • error: An error if the database is unreachable or schema initialization fails.

Errors:

  • Returns error if pinging the database fails.
  • Returns error if creating the vector extension or table fails.

Side Effects:

  • Verifies the database connection.
  • Creates the 'vector' extension if it doesn't exist.
  • Creates the 'semantic_cache_entries' table and indexes if they don't exist.

func (*PostgresVectorStore) Add 

func (s *PostgresVectorStore) Add(ctx context.Context, key string, vector []float32, result any, ttl time.Duration) error

Add adds a new entry to the vector store.

Summary: Inserts a new semantic cache entry into the database.

Parameters:

  • ctx: context.Context. The context for the database operation.
  • key: string. The unique key for the cache entry.
  • vector: []float32. The embedding vector associated with the entry.
  • result: any. The result data to be cached (marshaled to JSON).
  • ttl: time.Duration. The time-to-live for the cache entry.

Returns:

  • error: An error if marshaling fails or the database insert fails.

Errors:

  • Returns error if JSON marshaling of vector or result fails.
  • Returns error if the database execution fails.

Side Effects:

  • Writes a new row to the 'semantic_cache_entries' table.

func (*PostgresVectorStore) Close 

func (s *PostgresVectorStore) Close() error

Close closes the database connection.

Summary: Closes the underlying PostgreSQL database connection.

Returns:

  • error: An error if closing the connection fails.

Side Effects:

  • Closes the DB connection.

func (*PostgresVectorStore) Prune 

func (s *PostgresVectorStore) Prune(ctx context.Context, key string)

Prune removes expired entries.

Summary: Deletes expired cache entries from the database.

Parameters:

  • ctx: context.Context. The context for the database operation.
  • key: string. Optional key to restrict pruning to a specific cache key. If empty, prunes all expired entries.

Side Effects:

  • Deletes rows from the 'semantic_cache_entries' table.

func (*PostgresVectorStore) Search 

func (s *PostgresVectorStore) Search(ctx context.Context, key string, query []float32) (any, float32, bool)

Search searches for the most similar entry in the vector store.

Summary: Finds the nearest neighbor for the given query vector.

Parameters:

  • ctx: context.Context. The context for the database query.
  • key: string. The key to filter results by.
  • query: []float32. The query embedding vector.

Returns:

  • any: The cached result (unmarshaled from JSON).
  • float32: The similarity score (1.0 - cosine distance).
  • bool: True if a matching entry was found, false otherwise.

Errors:

  • Returns false if no matching row is found or if JSON unmarshaling fails.

Side Effects:

  • Executes a SELECT query on the database.

type ProviderFactory 

type ProviderFactory func(config *configv1.SemanticCacheConfig, apiKey string) (EmbeddingProvider, error)

ProviderFactory is a function that creates an EmbeddingProvider.

type RBACMiddleware 

type RBACMiddleware struct {
	// contains filtered or unexported fields
}

RBACMiddleware provides middleware for Role-Based Access Control.

Summary: Middleware for enforcing role-based access control policies.

func NewRBACMiddleware 

func NewRBACMiddleware() *RBACMiddleware

NewRBACMiddleware creates a new RBACMiddleware.

Summary: Initializes the RBAC middleware.

Returns:

  • *RBACMiddleware: The initialized middleware.

func (*RBACMiddleware) EnforcePolicy 

func (m *RBACMiddleware) EnforcePolicy(_ func(user *configv1.User) bool) func(http.Handler) http.Handler

EnforcePolicy allows passing a custom policy function.

Summary: Enforces a custom policy based on the user object.

Parameters:

  • policy: func(user *configv1.User) bool. The policy function to evaluate.

Returns:

  • func(http.Handler) http.Handler: The middleware function.

func (*RBACMiddleware) RequireAnyRole 

func (m *RBACMiddleware) RequireAnyRole(roles ...string) func(http.Handler) http.Handler

RequireAnyRole returns an HTTP middleware that requires the user to have at least one of the specified roles.

Summary: Enforces that the authenticated user possesses at least one of the specified roles.

Parameters:

  • roles: ...string. The list of allowed roles.

Returns:

  • func(http.Handler) http.Handler: The middleware function.

func (*RBACMiddleware) RequireRole 

func (m *RBACMiddleware) RequireRole(role string) func(http.Handler) http.Handler

RequireRole returns an HTTP middleware that requires the user to have the specified role.

Summary: Enforces that the authenticated user possesses a specific role.

Parameters:

  • role: string. The required role.

Returns:

  • func(http.Handler) http.Handler: The middleware function.

type RateLimitMiddleware 

type RateLimitMiddleware struct {
	// contains filtered or unexported fields
}

RateLimitMiddleware is a tool execution middleware that provides rate limiting functionality for upstream services.

Summary: Middleware for rate limiting tool execution.

func NewRateLimitMiddleware 

func NewRateLimitMiddleware(toolManager tool.ManagerInterface, opts ...Option) *RateLimitMiddleware

NewRateLimitMiddleware creates a new RateLimitMiddleware.

Summary: Initializes the rate limit middleware.

Parameters:

  • toolManager (tool.ManagerInterface): The tool manager.
  • opts (...Option): Optional configuration settings.

Returns:

  • (*RateLimitMiddleware): The initialized middleware.

func (*RateLimitMiddleware) Execute 

func (m *RateLimitMiddleware) Execute(ctx context.Context, req *tool.ExecutionRequest, next tool.ExecutionFunc) (any, error)

Execute executes the rate limiting middleware.

Summary: Executes rate limiting logic before passing to the next handler.

Parameters:

  • ctx (context.Context): The context for the request.
  • req (*tool.ExecutionRequest): The execution request.
  • next (tool.ExecutionFunc): The next handler.

Returns:

  • (any): The result of the execution.
  • (error): An error if the limit is exceeded or the operation fails.

Side Effects:

  • Checks against rate limits in memory or Redis.
  • Increments counters.

type RateLimitStrategy 

type RateLimitStrategy interface {
	// Create creates a new Limiter instance.
	//
	// ctx is the context for the request.
	// serviceID is the serviceID.
	// limitScopeKey is the limitScopeKey.
	// partitionKey is the partitionKey.
	// config holds the configuration settings.
	//
	// Returns the result.
	// Returns an error if the operation fails.
	Create(ctx context.Context, serviceID, limitScopeKey, partitionKey string, config *configv1.RateLimitConfig) (Limiter, error)
}

RateLimitStrategy defines the interface for creating rate limiters.

type Redactor 

type Redactor struct {
	// contains filtered or unexported fields
}

Redactor handles redaction of sensitive data based on configuration.

Summary: Component responsible for identifying and masking sensitive information (PII) in data.

func NewRedactor 

func NewRedactor(config *configv1.DLPConfig, log *slog.Logger) *Redactor

NewRedactor creates a new Redactor from the given DLP config.

Summary: Initializes a new Redactor based on Data Loss Prevention (DLP) configuration.

Parameters:

  • config: *configv1.DLPConfig. The DLP configuration containing enabled status and custom patterns.
  • log: *slog.Logger. Logger for warning about invalid patterns.

Returns:

  • *Redactor: The initialized redactor, or nil if DLP is disabled or config is nil.

Side Effects:

  • Compiles regular expressions for custom patterns.
  • Logs warnings for invalid regex patterns.

func (*Redactor) RedactJSON 

func (r *Redactor) RedactJSON(data []byte) ([]byte, error)

RedactJSON redacts sensitive information from a JSON byte slice.

Summary: Scans and redacts PII from a JSON-encoded byte slice.

Parameters:

  • data: []byte. The JSON data to redact.

Returns:

  • []byte: The redacted JSON data (or original if no redaction needed).
  • error: An error if JSON parsing fails (though often swallowed/ignored for safety).

Side Effects:

  • Walks the JSON structure.
  • Unmarshals and remarshals strings if modification is needed.

func (*Redactor) RedactString 

func (r *Redactor) RedactString(s string) string

RedactString redacts sensitive information from a string.

Summary: Applies redaction rules to a plain string.

Parameters:

  • s: string. The input string.

Returns:

  • string: The redacted string.

Side Effects:

  • Performs regex replacements for emails, credit cards, SSNs, and custom patterns.

func (*Redactor) RedactStruct 

func (r *Redactor) RedactStruct(v map[string]interface{})

RedactStruct redacts sensitive information from a map.

Summary: Recursively redacts sensitive information from a map (struct representation).

Parameters:

  • v: map[string]interface{}. The map to redact.

Side Effects:

  • Modifies the map in place.

func (*Redactor) RedactValue 

func (r *Redactor) RedactValue(val interface{}) interface{}

RedactValue redacts sensitive information from a value.

Summary: Recursively redacts sensitive information from an arbitrary value (string, map, slice).

Parameters:

  • val: interface{}. The value to redact.

Returns:

  • interface{}: The redacted value.

Side Effects:

  • Recursively processes maps and slices.

type RedisLimiter 

type RedisLimiter struct {
	// contains filtered or unexported fields
}

RedisLimiter implements a distributed rate limiter backed by Redis. It uses a token bucket algorithm to enforce rate limits across multiple service instances, ensuring that the configured Requests Per Second (RPS) and burst limits are respected regardless of how many server replicas are running.

Summary: Distributed token bucket rate limiter using Redis.

func NewRedisLimiter 

func NewRedisLimiter(serviceID string, config *configv1.RateLimitConfig) (*RedisLimiter, error)

NewRedisLimiter creates a new RedisLimiter for the specified service using the provided configuration. It initializes a connection to Redis and sets up the rate limiting parameters.

Summary: Initializes a new Redis-backed rate limiter.

Parameters:

  • serviceID: string. The unique identifier of the service to be rate-limited.
  • config: *configv1.RateLimitConfig. The configuration containing Redis connection details, RPS, and burst settings.

Returns:

  • *RedisLimiter: The initialized RedisLimiter, or nil if an error occurs.
  • error: An error if the configuration is invalid or the Redis connection fails.

Side Effects:

  • Creates a new Redis connection.

func NewRedisLimiterWithClient 

func NewRedisLimiterWithClient(client *redis.Client, serviceID, limitScopeKey, partitionKey string, config *configv1.RateLimitConfig) *RedisLimiter

NewRedisLimiterWithClient creates a new RedisLimiter using an existing Redis client. This avoids creating a new connection pool if one is already available.

Summary: Initializes a RedisLimiter reusing an existing Redis client.

Parameters:

  • client: *redis.Client. The existing Redis client instance.
  • serviceID: string. The unique identifier of the service.
  • limitScopeKey: string. An optional key to scope the limit.
  • partitionKey: string. An optional key to further partition the limit.
  • config: *configv1.RateLimitConfig. The rate limit configuration.

Returns:

  • *RedisLimiter: The initialized limiter.

func NewRedisLimiterWithPartition 

func NewRedisLimiterWithPartition(serviceID, limitScopeKey, partitionKey string, config *configv1.RateLimitConfig) (*RedisLimiter, error)

NewRedisLimiterWithPartition creates a new RedisLimiter with support for partitioned rate limiting. This is useful for more granular control, such as per-user or per-IP limits within a service.

Summary: Initializes a Redis-backed rate limiter with partitioning support.

Parameters:

  • serviceID: string. The unique identifier of the service.
  • limitScopeKey: string. An optional key to scope the limit (e.g., "user_id").
  • partitionKey: string. An optional key to further partition the limit (e.g., "12345").
  • config: *configv1.RateLimitConfig. The rate limit configuration.

Returns:

  • *RedisLimiter: The initialized limiter.
  • error: An error if Redis config is missing.

Errors:

  • Returns "redis config is missing" if config is incomplete.

Side Effects:

  • Creates a new Redis connection.

func (*RedisLimiter) Allow 

func (l *RedisLimiter) Allow(ctx context.Context) (bool, error)

Allow checks if a single request is allowed under the current rate limit policy. It decrements the token bucket by 1.

Summary: Checks if a single request is allowed.

Parameters:

  • ctx: context.Context. The context for the request.

Returns:

  • bool: true if the request is allowed.
  • error: An error if the Redis operation fails.

Side Effects:

  • Executes a Lua script on Redis to atomically consume tokens.

func (*RedisLimiter) AllowN 

func (l *RedisLimiter) AllowN(ctx context.Context, n int) (bool, error)

AllowN checks if a request with a specific cost is allowed. It attempts to consume 'n' tokens from the bucket.

Summary: Checks if a request with cost N is allowed.

Parameters:

  • ctx: context.Context. The context for the request.
  • n: int. The cost of the request.

Returns:

  • bool: true if the request is allowed.
  • error: An error if the Redis operation fails.

Side Effects:

  • Executes a Lua script on Redis to atomically consume tokens.

func (*RedisLimiter) Close 

func (l *RedisLimiter) Close() error

Close terminates the Redis client connection and releases resources.

Summary: Closes the Redis client connection.

Returns:

  • error: An error if closing the client fails.

Side Effects:

  • Closes the TCP connection to Redis.

func (*RedisLimiter) GetConfigHash 

func (l *RedisLimiter) GetConfigHash() string

GetConfigHash returns a hash string representing the underlying Redis configuration. This is used to detect configuration changes that might require a client reconnection.

Summary: Retrieves the hash of the current Redis configuration.

Returns:

  • string: The configuration hash string.

func (*RedisLimiter) Update 

func (l *RedisLimiter) Update(rps float64, burst int)

Update dynamically updates the rate limit configuration for the running limiter.

Summary: Updates the rate limit settings (RPS and burst).

Parameters:

  • rps: float64. The new requests per second limit.
  • burst: int. The new burst capacity.

Side Effects:

  • Modifies the internal state of the limiter.

type RedisStrategy 

type RedisStrategy struct {
	// contains filtered or unexported fields
}

RedisStrategy implements RateLimitStrategy for Redis-based rate limiting.

Summary: Strategy for creating Redis-backed distributed rate limiters.

func NewRedisStrategy 

func NewRedisStrategy() *RedisStrategy

NewRedisStrategy creates a new RedisStrategy.

Summary: Initializes a new RedisStrategy.

Returns:

  • *RedisStrategy: The initialized strategy.

func (*RedisStrategy) Create 

func (s *RedisStrategy) Create(_ context.Context, serviceID, limitScopeKey, partitionKey string, config *configv1.RateLimitConfig) (Limiter, error)

Create creates a new RedisLimiter.

Summary: Creates a new Redis-backed rate limiter.

Parameters:

  • _: context.Context. Unused.
  • serviceID: string. The service identifier.
  • limitScopeKey: string. The scope key for the limit.
  • partitionKey: string. The partition key for the limit.
  • config: *configv1.RateLimitConfig. The rate limit configuration.

Returns:

  • Limiter: The created RedisLimiter.
  • error: An error if the Redis configuration is missing.

Errors:

  • Returns "redis config is missing" if the config does not contain Redis settings.

Side Effects:

  • Establishes or reuses a Redis connection.

type Registry 

type Registry struct {
	// contains filtered or unexported fields
}

Registry manages available middlewares.

type ResilienceMiddleware 

type ResilienceMiddleware struct {
	// contains filtered or unexported fields
}

ResilienceMiddleware provides circuit breaker and retry functionality for tool executions.

Summary: Middleware that wraps tool executions with circuit breakers, retries, and timeouts.

func NewResilienceMiddleware 

func NewResilienceMiddleware(toolManager tool.ManagerInterface) *ResilienceMiddleware

NewResilienceMiddleware creates a new ResilienceMiddleware.

Summary: Initializes the ResilienceMiddleware with a tool manager.

Parameters:

  • toolManager: tool.ManagerInterface. The manager for retrieving tool and service information.

Returns:

  • *ResilienceMiddleware: The initialized middleware.

func (*ResilienceMiddleware) Execute 

func (m *ResilienceMiddleware) Execute(ctx context.Context, req *tool.ExecutionRequest, next tool.ExecutionFunc) (any, error)

Execute executes the resilience middleware.

Summary: Executes the tool call within a resilience wrapper (circuit breaker, retry).

Parameters:

  • ctx: context.Context. The execution context.
  • req: *tool.ExecutionRequest. The tool execution request.
  • next: tool.ExecutionFunc. The next handler in the chain.

Returns:

  • any: The execution result.
  • error: An error if the execution or resilience policy fails.

Side Effects:

  • Checks circuit breaker state.
  • May retry the execution on failure.
  • Records success/failure to update circuit breaker stats.

type SQLiteVectorStore 

type SQLiteVectorStore struct {
	// contains filtered or unexported fields
}

SQLiteVectorStore implements VectorStore using SQLite for persistence and an in-memory cache for fast search.

Summary: A hybrid vector store that uses SQLite for persistence and an in-memory structure for search.

func NewSQLiteVectorStore 

func NewSQLiteVectorStore(path string) (*SQLiteVectorStore, error)

NewSQLiteVectorStore creates a new SQLiteVectorStore.

Summary: Initializes a new SQLiteVectorStore from the specified file path.

Parameters:

  • path: string. The file path to the SQLite database.

Returns:

  • *SQLiteVectorStore: The initialized vector store.
  • error: An error if the path is empty, database cannot be opened, or schema creation fails.

Errors:

  • Returns "sqlite path is required" if the path is empty.
  • Returns error if database connection or schema initialization fails.

Side Effects:

  • Opens (and creates if missing) the SQLite database file.
  • Creates the 'semantic_cache_entries' table.
  • Sets SQLite PRAGMAs for performance optimization.
  • Loads existing unexpired entries into memory.

func (*SQLiteVectorStore) Add 

func (s *SQLiteVectorStore) Add(ctx context.Context, key string, vector []float32, result any, ttl time.Duration) error

Add adds a new entry to both memory and DB.

Summary: Inserts a cache entry into the in-memory store and the persistent SQLite database.

Parameters:

  • ctx: context.Context. The request context.
  • key: string. The cache key.
  • vector: []float32. The embedding vector.
  • result: any. The result to cache.
  • ttl: time.Duration. The time-to-live for the entry.

Returns:

  • error: An error if writing to memory or DB fails.

Errors:

  • Returns error if memory store addition fails.
  • Returns error if JSON marshaling fails.
  • Returns error if database insert fails.

Side Effects:

  • Updates in-memory cache state.
  • Writes row to SQLite database.
  • May trigger async probabilistic pruning of expired DB entries.

func (*SQLiteVectorStore) Close 

func (s *SQLiteVectorStore) Close() error

Close closes the database connection.

Summary: Closes the SQLite database connection.

Returns:

  • error: An error if closing fails.

func (*SQLiteVectorStore) Prune 

func (s *SQLiteVectorStore) Prune(ctx context.Context, key string)

Prune removes expired entries from both memory and DB.

Summary: Manually triggers removal of expired entries from memory and disk.

Parameters:

  • ctx: context.Context. The request context.
  • key: string. Optional key to restrict pruning scope.

Side Effects:

  • Removes items from memory.
  • Deletes rows from SQLite database.

func (*SQLiteVectorStore) Search 

func (s *SQLiteVectorStore) Search(ctx context.Context, key string, query []float32) (any, float32, bool)

Search searches in memory.

Summary: Searches the in-memory store for the nearest neighbor.

Parameters:

  • ctx: context.Context. The request context.
  • key: string. The key to filter results.
  • query: []float32. The query embedding vector.

Returns:

  • any: The best matching result data.
  • float32: The similarity score (0-1).
  • bool: True if a match was found.

type SSOConfig 

type SSOConfig struct {
	Enabled bool
	IDPURL  string
}

SSOConfig defines the SSO configuration.

Summary: Configuration options for Single Sign-On (SSO) middleware.

type SemanticCache 

type SemanticCache struct {
	// contains filtered or unexported fields
}

SemanticCache implements a semantic cache using embeddings and cosine similarity.

Summary: A cache implementation that uses semantic similarity rather than exact key matching.

func NewSemanticCache 

func NewSemanticCache(provider EmbeddingProvider, store VectorStore, threshold float32) *SemanticCache

NewSemanticCache creates a new SemanticCache.

Summary: Initializes a new SemanticCache.

Parameters:

  • provider: EmbeddingProvider. The service to generate embeddings.
  • store: VectorStore. The storage backend for vectors.
  • threshold: float32. The minimum similarity score (0-1) to consider a hit.

Returns:

  • *SemanticCache: The initialized semantic cache.

Side Effects:

  • Sets a default threshold of 0.9 if the provided threshold is <= 0.
  • Creates a memory-based vector store if store is nil.

func (*SemanticCache) Get 

func (c *SemanticCache) Get(ctx context.Context, key string, input string) (any, []float32, bool, error)

Get attempts to find a semantically similar cached result.

Summary: Retrieves a cached result if a semantically similar entry exists.

Parameters:

  • ctx: context.Context. The request context.
  • key: string. The semantic key or scope.
  • input: string. The query text to match against.

Returns:

  • any: The cached result if found.
  • []float32: The embedding generated for the input text (useful for subsequent Set).
  • bool: True if a cache hit occurred.
  • error: An error if embedding generation fails.

Errors:

  • Returns error if the embedding provider fails.

Side Effects:

  • calls the EmbeddingProvider to generate an embedding.
  • calls the VectorStore to search for matches.

func (*SemanticCache) Set 

func (c *SemanticCache) Set(ctx context.Context, key string, embedding []float32, result any, ttl time.Duration) error

Set adds a result to the cache using the provided embedding.

Summary: Caches a result associated with a specific embedding.

Parameters:

  • ctx: context.Context. The request context.
  • key: string. The semantic key or scope.
  • embedding: []float32. The embedding vector (usually returned from Get).
  • result: any. The result data to cache.
  • ttl: time.Duration. The expiration time for the cache entry.

Returns:

  • error: An error if the storage operation fails.

Side Effects:

  • Writes to the underlying VectorStore.

type SimpleVectorStore 

type SimpleVectorStore struct {
	// contains filtered or unexported fields
}

SimpleVectorStore is a naive in-memory vector store.

func NewSimpleVectorStore 

func NewSimpleVectorStore() *SimpleVectorStore

NewSimpleVectorStore creates a new SimpleVectorStore. It initializes the store with a default configuration.

Returns:

  • *SimpleVectorStore: A pointer to the newly created SimpleVectorStore.

func (*SimpleVectorStore) Add 

func (s *SimpleVectorStore) Add(_ context.Context, key string, vector []float32, result any, ttl time.Duration) error

Add adds a new entry to the vector store. It evicts the oldest entry if the store exceeds the maximum number of entries for the key.

Parameters:

  • key: The key associated with the entry.
  • vector: The embedding vector.
  • result: The result to cache.
  • ttl: The time-to-live for the entry.

Returns:

  • error: An error if the operation fails (currently always nil).

func (*SimpleVectorStore) Prune 

func (s *SimpleVectorStore) Prune(_ context.Context, key string)

Prune removes expired entries from the vector store for the given key.

Parameters:

  • key: The key to prune entries for.

func (*SimpleVectorStore) Search 

func (s *SimpleVectorStore) Search(_ context.Context, key string, query []float32) (any, float32, bool)

Search searches for the most similar entry in the vector store for the given key and query vector. It returns the result, the similarity score, and a boolean indicating if a match was found.

Parameters:

  • key: The key to search for.
  • query: The query vector.

Returns:

  • any: The cached result if found.
  • float32: The similarity score (cosine similarity).
  • bool: True if a match was found, false otherwise.

type SmartRecoveryMiddleware 

type SmartRecoveryMiddleware struct {
	// contains filtered or unexported fields
}

SmartRecoveryMiddleware handles automatic error recovery using LLM.

func NewSmartRecoveryMiddleware 

func NewSmartRecoveryMiddleware(config *configv1.SmartRecoveryConfig, toolManager tool.ManagerInterface) *SmartRecoveryMiddleware

NewSmartRecoveryMiddleware creates a new SmartRecoveryMiddleware.

Parameters:

  • config (*configv1.SmartRecoveryConfig): The config parameter.
  • toolManager (tool.ManagerInterface): The toolManager parameter.

Returns:

  • *SmartRecoveryMiddleware: The resulting *SmartRecoveryMiddleware.

Errors:

  • None

Side Effects:

  • None

func (*SmartRecoveryMiddleware) Execute 

func (m *SmartRecoveryMiddleware) Execute(ctx context.Context, req *tool.ExecutionRequest, next tool.ExecutionFunc) (any, error)

Execute executes the middleware logic.

Parameters:

  • ctx (context.Context): The context for the request.
  • req (*tool.ExecutionRequest): The request object.
  • next (tool.ExecutionFunc): The next parameter.

Returns:

  • any: The resulting any.
  • error: An error if the operation fails.

Errors:

  • Returns an error if the operation fails or is invalid.

Side Effects:

  • None

type StandardMiddlewares 

type StandardMiddlewares struct {
	Audit            *AuditMiddleware
	GlobalRateLimit  *GlobalRateLimitMiddleware
	ContextOptimizer *ContextOptimizer
	Debugger         *Debugger
	SmartRecovery    *SmartRecoveryMiddleware
	Cleanup          func() error
}

StandardMiddlewares holds the standard middlewares that might need to be updated.

func InitStandardMiddlewares 

func InitStandardMiddlewares(
	authManager *auth.Manager,
	toolManager tool.ManagerInterface,
	auditConfig *configv1.AuditConfig,
	cachingMiddleware *CachingMiddleware,
	globalRateLimitConfig *configv1.RateLimitConfig,
	dlpConfig *configv1.DLPConfig,
	contextOptimizerConfig *configv1.ContextOptimizerConfig,
	debuggerConfig *configv1.DebuggerConfig,
	smartRecoveryConfig *configv1.SmartRecoveryConfig,
) (*StandardMiddlewares, error)

InitStandardMiddlewares registers standard middlewares.

Parameters:

  • authManager (*auth.Manager): The authManager.
  • toolManager (tool.ManagerInterface): The toolManager.
  • auditConfig (*configv1.AuditConfig): The auditConfig.
  • cachingMiddleware (*CachingMiddleware): The cachingMiddleware.
  • globalRateLimitConfig (*configv1.RateLimitConfig): The globalRateLimitConfig.
  • dlpConfig (*configv1.DLPConfig): The dlpConfig.
  • contextOptimizerConfig (*configv1.ContextOptimizerConfig): The contextOptimizerConfig.
  • debuggerConfig (*configv1.DebuggerConfig): The debuggerConfig.
  • smartRecoveryConfig (*configv1.SmartRecoveryConfig): The smartRecoveryConfig.

Returns:

  • (*StandardMiddlewares): The result.
  • (error): An error if the operation fails.

type ToolMetricsMiddleware 

type ToolMetricsMiddleware struct {
	// contains filtered or unexported fields
}

ToolMetricsMiddleware provides detailed metrics for tool executions.

Summary: Middleware that records Prometheus metrics for tool execution calls.

func NewToolMetricsMiddleware 

func NewToolMetricsMiddleware(t tokenizer.Tokenizer) *ToolMetricsMiddleware

NewToolMetricsMiddleware creates a new ToolMetricsMiddleware.

Summary: Initializes the tool metrics middleware and registers metrics if not already registered.

Parameters:

  • t: tokenizer.Tokenizer. The tokenizer used to count tokens in tool inputs and outputs. If nil, a simple default tokenizer is used.

Returns:

  • *ToolMetricsMiddleware: A new instance of ToolMetricsMiddleware with metrics registered.

Side Effects:

  • Registers Prometheus metrics (globally, once).

func (*ToolMetricsMiddleware) Execute 

func (m *ToolMetricsMiddleware) Execute(ctx context.Context, req *tool.ExecutionRequest, next tool.ExecutionFunc) (any, error)

Execute executes the tool metrics middleware.

Summary: Wraps tool execution to record latency, size, and token metrics.

Parameters:

  • ctx: context.Context. The execution context.
  • req: *tool.ExecutionRequest. The request containing tool execution details.
  • next: tool.ExecutionFunc. The next handler in the execution chain.

Returns:

  • any: The result of the tool execution.
  • error: An error if the execution fails.

Side Effects:

  • Updates Prometheus counters, histograms, and gauges.
  • Measures execution duration.

type VectorEntry 

type VectorEntry struct {
	// Vector is the embedding vector.
	Vector []float32
	// Result is the cached result associated with the vector.
	Result any
	// ExpiresAt is the timestamp when this entry expires.
	ExpiresAt time.Time
	// Norm is the precomputed Euclidean norm of the vector.
	Norm float32
}

VectorEntry represents a single entry in the vector store.

type VectorStore 

type VectorStore interface {
	// Add adds a new entry to the vector store.
	//
	// Parameters:
	//   - ctx: context.Context. The context for the request.
	//   - key: string. The unique key for the entry.
	//   - vector: []float32. The embedding vector.
	//   - result: any. The associated result data.
	//   - ttl: time.Duration. The time-to-live for the entry.
	//
	// Returns:
	//   - error: An error if the operation fails.
	Add(ctx context.Context, key string, vector []float32, result any, ttl time.Duration) error

	// Search searches for the most similar entry in the vector store.
	//
	// Parameters:
	//   - ctx: context.Context. The context for the request.
	//   - key: string. The key to restrict the search scope.
	//   - query: []float32. The query embedding vector.
	//
	// Returns:
	//   - any: The best matching result data.
	//   - float32: The similarity score (0.0 to 1.0).
	//   - bool: True if a match was found, false otherwise.
	Search(ctx context.Context, key string, query []float32) (any, float32, bool)

	// Prune removes expired entries.
	//
	// Parameters:
	//   - ctx: context.Context. The context for the request.
	//   - key: string. Optional key to restrict pruning scope.
	Prune(ctx context.Context, key string)
}

VectorStore defines the interface for storing and searching vectors.

Summary: Interface for storage backends that support vector similarity search.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.