Crate pingora_core

Expand description

§Pingora

Pingora is a collection of service frameworks and network libraries battle-tested by the Internet. It is to build robust, scalable and secure network infrastructures and services at Internet scale.

§Features

Http 1.x and Http 2
Modern TLS with OpenSSL or BoringSSL (FIPS compatible)
Zero downtime upgrade

§Usage

This crate provides low level service and protocol implementation and abstraction.

If looking to build a (reverse) proxy, see pingora-proxy crate.

§Optional features

§TLS backends (mutually exclusive)

openssl: Use OpenSSL as the TLS library (default if no TLS feature is specified)
boringssl: Use BoringSSL as the TLS library (FIPS compatible)
rustls: Use Rustls as the TLS library

§Additional features

connection_filter: Enable early TCP connection filtering before TLS handshake. This allows implementing custom logic to accept/reject connections based on peer address with zero overhead when disabled.
sentry: Enable Sentry error reporting integration
patched_http1: Enable patched HTTP/1 parser

§Connection Filtering

With the connection_filter feature enabled, you can implement early connection filtering at the TCP level, before any TLS handshake or HTTP processing occurs. This is useful for:

IP-based access control
Rate limiting at the connection level
Geographic restrictions
DDoS mitigation

§Example

use async_trait::async_trait;
use pingora_core::listeners::ConnectionFilter;
use std::net::SocketAddr;
use std::sync::Arc;

#[derive(Debug)]
struct MyFilter;

#[async_trait]
impl ConnectionFilter for MyFilter {
    async fn should_accept(&self, addr: &SocketAddr) -> bool {
        // Custom logic to filter connections
        !is_blocked_ip(addr.ip())
    }
}

// Apply the filter to a service
let mut service = my_service();
service.set_connection_filter(Arc::new(MyFilter));

When the connection_filter feature is disabled, the filter API remains available but becomes a no-op, ensuring zero overhead for users who don’t need this functionality.

Re-exports§

pub use protocols::tls::noop_tls as tls;Non-any_tls
pub use pingora_error::ErrorType::*;

Modules§

apps: The abstraction and implementation interface for service application logic
connectors: Connecting to servers
listeners: The listening endpoints (TCP and TLS) and their configurations.
modules: Modules to extend the functionalities of pingora services.
prelude
protocols: Abstractions and implementations for protocols including TCP, TLS and HTTP
server: Server process and configuration management
services: The service interface
upstreams: The interface to connect to a remote server
utils: This module contains various types that make it easier to work with bytes and X509 certificates.

Macros§

custom_session

Structs§

Error: The struct that represents an error

Enums§

ErrorSource: The source of the error
ErrorType: Predefined type of errors
ImmutStr: A data struct that holds either immutable string or reference to static str. Compared to String or Box<str>, it avoids memory allocation on static str.
RetryType: Whether the request can be retried after encountering this error

Traits§

Context: Helper trait to add more context to a given error
ErrorTrait: Error is a trait representing the basic expectations for error values, i.e., values of type E in Result<T, E>.
OkOrErr: Helper trait to convert an Option to an Error with context.
OrErr: Helper trait to chain errors with context

Type Aliases§

BError: The boxed Error, the desired way to pass Error
Result: Syntax sugar for std::Result<T, BError>