Introduction

Welcome to Sentinel, a high-performance reverse proxy platform built on Cloudflare’s Pingora framework. Sentinel extends Pingora’s robust foundation with enterprise-grade features designed for modern web infrastructure.

What is Sentinel?

Sentinel is a next-generation reverse proxy that combines the performance and reliability of Pingora with advanced routing capabilities, service-type awareness, and comprehensive error handling. Whether you’re serving static files, proxying REST APIs, or managing complex web applications, Sentinel provides the tools and flexibility you need for production deployments.

Key Features

High Performance

• Built on Pingora’s async Rust foundation
• Memory-safe architecture with zero-copy operations
• Efficient connection pooling and keep-alive management
• Optimized for both throughput and latency

Service-Type Awareness

Sentinel understands different service types and optimizes behavior accordingly:

• Web Applications: HTML error pages, session handling, SPA support
• REST APIs: JSON schema validation, structured error responses, OpenAPI integration
• Static Files: Direct file serving, automatic MIME types, caching headers

Advanced Routing

• Flexible path-based and host-based routing
• Route priorities and groups
• Path variables and pattern matching
• Per-route configuration overrides

Comprehensive Error Handling

• Service-type-specific error formats (HTML, JSON, XML, Text)
• Custom error page templates with variable substitution
• Graceful fallbacks for connection failures
• Detailed error tracking with request IDs

Observability

• Structured logging with configurable levels
• Prometheus-compatible metrics
• Distributed tracing support
• Health check endpoints

Security Features

• Path traversal protection for static files
• Request validation and sanitization
• Rate limiting capabilities
• TLS/SSL with modern cipher suites
• HTTP/3 preparation with QUIC support (ready for activation)

Configuration

• Human-friendly KDL configuration format
• Hot reload without downtime
• Environment variable substitution
• Comprehensive validation on startup

Why Sentinel?

Production-Ready

Sentinel is designed for production use from the ground up. Every feature is implemented with reliability, performance, and operational excellence in mind.

Type-Safe and Memory-Safe

Written in Rust, Sentinel eliminates entire classes of bugs common in traditional proxies, including buffer overflows, use-after-free errors, and data races.

Cloud-Native

Built for modern cloud environments with support for:

• Container deployments (Docker, Kubernetes)
• Horizontal scaling
• Service mesh integration
• Dynamic configuration

Developer-Friendly

• Clear, expressive configuration
• Comprehensive error messages
• Extensive documentation
• Example configurations for common use cases

Use Cases

Sentinel excels in various deployment scenarios:

• API Gateway: Validate requests, transform responses, implement rate limiting
• Static Content Delivery: Serve files directly with optimal caching headers
• Load Balancer: Distribute traffic across multiple upstream servers
• Web Application Proxy: Handle sessions, provide custom error pages, support SPAs
• Microservices Router: Route requests to different services based on paths
• Edge Proxy: Terminate SSL, implement security policies, cache responses

Architecture Highlights

Sentinel leverages Pingora’s battle-tested architecture while adding its own innovations:

Client Request
     ↓
[TLS Termination]
     ↓
[Route Matching] ← Service Type Detection
     ↓
[Request Processing]
     ├─→ Static File Serving (no upstream)
     ├─→ API Validation → Upstream
     └─→ Web App Processing → Upstream
     ↓
[Response Processing]
     ├─→ Error Page Generation
     ├─→ Header Manipulation
     └─→ Caching Headers
     ↓
Client Response

Getting Started

This documentation will guide you through:

1. Installation - Get Sentinel up and running
2. Quick Start - Your first proxy configuration
3. Core Concepts - Understand how Sentinel works
4. Configuration - Master the configuration system
5. Service Types - Leverage service-specific features
6. Deployment - Deploy to production

Documentation Structure

• Getting Started: Installation and basic setup
• Core Concepts: Fundamental architecture and design principles
• Configuration: Detailed configuration reference
• Service Types: Service-specific features and optimizations
• Features: Advanced capabilities and integrations
• Operations: Production deployment and management
• Examples: Real-world configuration examples
• Reference: API documentation and specifications

Community and Support

• GitHub Repository: github.com/raskell-io/sentinel
• Issue Tracker: Report bugs and request features
• Discussions: Ask questions and share experiences
• Contributing: We welcome contributions! See our Contributing Guide

Version Information

This documentation covers Sentinel version 0.1.0 and later. For the latest updates and changes, see the Changelog.

License

Sentinel is open-source software licensed under the Apache License, Version 2.0. See the License page for details.

Ready to get started? Head to the Installation Guide to begin your journey with Sentinel!