Crate grapsus_proxy 

Grapsus Proxy Library

A security-first reverse proxy built on Pingora with sleepable ops at the edge.

This library provides the core components for building a production-grade reverse proxy with:

• Routing: Flexible path-based and header-based routing
• Upstream Management: Load balancing, health checking, circuit breakers
• Static File Serving: Compression, caching, range requests
• Validation: JSON Schema validation for API requests/responses
• Error Handling: Customizable error pages per service type
• Hot Reload: Configuration changes without restarts

Example

use grapsus_proxy::{StaticFileServer, ErrorHandler, SchemaValidator};
use grapsus_config::{StaticFileConfig, ServiceType};

// Create a static file server
let config = StaticFileConfig::default();
let server = StaticFileServer::new(config);

// Create an error handler for API responses
let handler = ErrorHandler::new(ServiceType::Api, None);

Re-exports

pub use errors::ErrorHandler;

pub use static_files::CacheStats;

pub use static_files::CachedFile;

pub use static_files::FileCache;

pub use static_files::StaticFileServer;

pub use validation::SchemaValidator;

pub use routing::RequestInfo;

pub use routing::RouteMatch;

pub use routing::RouteMatcher;

pub use scoped_routing::ScopedRouteMatch;

pub use scoped_routing::ScopedRouteMatcher;

pub use upstream::LoadBalancer;

pub use upstream::PoolConfigSnapshot;

pub use upstream::PoolStats;

pub use upstream::RequestContext;

pub use upstream::ShadowTarget;

pub use upstream::TargetSelection;

pub use upstream::UpstreamPool;

pub use upstream::UpstreamTarget;

pub use health::ActiveHealthChecker;

pub use health::PassiveHealthChecker;

pub use health::TargetHealthInfo;

pub use agents::AgentAction;

pub use agents::AgentCallContext;

pub use agents::AgentDecision;

pub use agents::AgentManager;

pub use reload::ConfigManager;

pub use reload::ReloadEvent;

pub use reload::ReloadTrigger;

pub use reload::SignalManager;

pub use reload::SignalType;

pub use app::AppState;

pub use proxy::GrapsusProxy;

pub use builtin_handlers::execute_handler;

pub use builtin_handlers::BuiltinHandlerState;

pub use builtin_handlers::CachePurgeRequest;

pub use builtin_handlers::TargetHealthStatus;

pub use builtin_handlers::TargetStatus;

pub use builtin_handlers::UpstreamHealthSnapshot;

pub use builtin_handlers::UpstreamStatus;

pub use http_helpers::extract_request_info;

pub use http_helpers::get_or_create_trace_id;

pub use http_helpers::write_error;

pub use http_helpers::write_json_error;

pub use http_helpers::write_response;

pub use http_helpers::write_text_error;

pub use http_helpers::OwnedRequestInfo;

pub use trace_id::generate_for_format;

pub use trace_id::generate_tinyflake;

pub use trace_id::generate_uuid;

pub use trace_id::TINYFLAKE_LENGTH;

pub use otel::create_traceparent;

pub use otel::generate_span_id;

pub use otel::generate_trace_id;

pub use otel::get_tracer;

pub use otel::init_tracer;

pub use otel::shutdown_tracer;

pub use otel::OtelError;

pub use otel::OtelTracer;

pub use otel::RequestSpan;

pub use otel::TraceContext;

pub use otel::TRACEPARENT_HEADER;

pub use otel::TRACESTATE_HEADER;

pub use tls::build_server_config;

pub use tls::build_upstream_tls_config;

pub use tls::load_client_ca;

pub use tls::validate_tls_config;

pub use tls::validate_upstream_tls_config;

pub use tls::CertificateReloader;

pub use tls::HotReloadableSniResolver;

pub use tls::OcspCacheEntry;

pub use tls::OcspStapler;

pub use tls::SniResolver;

pub use tls::TlsError;

pub use logging::AccessLogEntry;

pub use logging::AccessLogFormat;

pub use logging::AuditEventType;

pub use logging::AuditLogEntry;

pub use logging::ErrorLogEntry;

pub use logging::LogManager;

pub use logging::SharedLogManager;

pub use rate_limit::RateLimitConfig;

pub use rate_limit::RateLimitManager;

pub use rate_limit::RateLimitOutcome;

pub use rate_limit::RateLimitResult;

pub use rate_limit::RateLimiterPool;

pub use scoped_rate_limit::ScopedRateLimitManager;

pub use scoped_rate_limit::ScopedRateLimitResult;

pub use scoped_circuit_breaker::ScopedBreakerStatus;

pub use scoped_circuit_breaker::ScopedCircuitBreakerManager;

pub use shadow::buffer_request_body;

pub use shadow::clone_body_for_shadow;

pub use shadow::should_buffer_method;

pub use shadow::ShadowManager;

pub use geo_filter::GeoDatabaseWatcher;

pub use geo_filter::GeoFilterManager;

pub use geo_filter::GeoFilterPool;

pub use geo_filter::GeoFilterResult;

pub use geo_filter::GeoLookupError;

pub use decompression::decompress_body;

pub use decompression::decompress_body_with_stats;

pub use decompression::is_supported_encoding;

pub use decompression::parse_content_encoding;

pub use decompression::DecompressionConfig;

pub use decompression::DecompressionError;

pub use decompression::DecompressionResult;

pub use decompression::DecompressionStats;

pub use cache::configure_cache;

pub use cache::get_cache_eviction;

pub use cache::get_cache_lock;

pub use cache::get_cache_storage;

pub use cache::init_disk_cache_state;

pub use cache::is_cache_enabled;

pub use cache::save_disk_cache_state;

pub use cache::CacheConfig;

pub use cache::CacheManager;

pub use cache::HttpCacheStats;

pub use memory_cache::MemoryCacheConfig;

pub use memory_cache::MemoryCacheManager;

pub use memory_cache::MemoryCacheStats;

pub use memory_cache::RouteMatchEntry;

pub use memory_cache::TypedCache;

pub use metrics::MetricsManager;

pub use metrics::MetricsResponse;

pub use discovery::ConsulDiscovery;

pub use discovery::DiscoveryConfig;

pub use discovery::DiscoveryManager;

pub use discovery::DnsDiscovery;

pub use discovery::KubernetesDiscovery;

Modules

acme

ACME automatic certificate management

agents

Agent integration module for Grapsus proxy.

app

Application module for Grapsus proxy

builtin_handlers

Built-in handlers for Grapsus proxy

bundle

Bundle command module

cache

HTTP caching infrastructure for Grapsus

decompression

Request body decompression with ratio limits

discovery

Service Discovery Module

disk_cache

Disk-based cache storage backend

distributed_rate_limit

Distributed rate limiting with Redis backend

errors

Error handling module for Grapsus proxy

geo_filter

GeoIP filtering for Grapsus proxy

grpc_health

gRPC Health Checking Protocol implementation

health

Health checking module for Grapsus proxy

http_helpers

HTTP request and response helpers for Grapsus proxy

hybrid_cache

Hybrid cache storage backend

inference

Inference routing module for LLM/AI traffic patterns

logging

Logging infrastructure for Grapsus proxy

memcached_rate_limit

Distributed rate limiting with Memcached backend

memory_cache

In-memory caching module using pingora-memory-cache

metrics

Prometheus metrics endpoint for Grapsus proxy.

otel

OpenTelemetry integration for distributed tracing

proxy

Grapsus Proxy Core Implementation

rate_limit

Rate limiting using pingora-limits

reload

Configuration hot reload module for Grapsus proxy.

routing

Route matching and selection module for Grapsus proxy

scoped_circuit_breaker

Scope-aware circuit breakers for namespaced configurations.

scoped_rate_limit

Scope-aware rate limiting for namespaced configurations.

scoped_routing

Scope-aware route matching for namespaced configurations.

shadow

Traffic mirroring / shadowing for safe canary testing

static_files

Static file serving module for Grapsus proxy

tls

TLS Configuration and SNI Support

trace_id

TinyFlake: Operator-friendly Trace ID Generation

upstream

Upstream pool management module for Grapsus proxy

validation

API schema validation module for Grapsus proxy

websocket

WebSocket frame handling for frame-level inspection.

Enums

GrapsusError

Main error type for Grapsus operations

LimitType

Types of limits that can be exceeded

TraceIdFormat

Trace ID format selection.

Type Aliases

GrapsusResult

Result type alias for Grapsus operations