Pingap Core

Pingap Core is the foundational library for the Pingap project, providing a robust set of core components and utilities for building high-performance, extensible proxy and networking applications in Rust.

Overview

This library offers a modular toolkit designed to handle the entire lifecycle of HTTP requests and responses. It includes a powerful request context system, flexible plugin architecture, efficient HTTP header and response manipulation, background task management, and more. It is built on top of the pingora framework, extending its capabilities with specialized features.

Core Features

• Request Context (Ctx): A central struct that tracks the state of each request, including timing metrics, connection details, upstream information, caching status, and custom variables. It also provides utilities for generating detailed logs and Server-Timing headers.
• Plugin System: An extensible plugin architecture that allows developers to hook into various stages of the request/response lifecycle (PluginStep). This enables custom logic for authentication, rate-limiting, header modification, and more. A response that a plugin answers with skips the response step; a plugin that returns true from handles_plugin_response() still gets to set its headers on it.
• HTTP Helpers: A rich set of utilities for working with HTTP headers and responses:
  • Header Manipulation: Parse, create, and modify HTTP headers, with support for dynamic value substitution (e.g., $hostname, $ja4, $remote_addr, $http_user_agent).
  • Response Builders: Fluent builders (HttpResponseBuilder) for easily constructing complete HTTP responses, with helpers for common types like JSON, HTML, text, and redirects. A header given twice is the last one given, except Set-Cookie, WWW-Authenticate, Proxy-Authenticate and Link, which are sent once per value.
  • Streaming Responses: Support for chunked responses (HttpChunkResponse) to efficiently stream large bodies of data.
• Background Task Service: A generic service (BackgroundTaskService) for running periodic tasks in the background, such as health checks, data synchronization, or cleanup routines.
• Rate Limiting: An efficient, TTL-based LRU cache (TtlLruLimit) for implementing rate-limiting logic based on a maximum number of requests within a given time window.
• Notification Service: A simple, extensible trait (Notification) for sending alerts and notifications through various channels.
• High-Performance Utilities: Shared helpers for the request path — clock reads, header manipulation, constant-time comparison and duration formatting.

Modules

• ctx: Provides the central Ctx struct for request lifecycle state management. CtxLogField names the values the access log can print; a log format parses the name once and calls Ctx::append_log_field per request.
• http_header: Contains helpers for parsing and manipulating HTTP request headers. resolve_static_header_value folds $hostname and $ENV_VAR into plain values when the configuration is loaded; $http_user_agent reads User-Agent (underscores stand for dashes); get_host keeps an IPv6 literal whole.
• http_response: Provides builders and structs for creating HTTP responses.
• plugin: Defines the Plugin trait and PluginStep enum for building custom plugins.
• service: Includes the BackgroundTaskService for running background tasks. Every task of a service keeps its own time: a round starts the tasks that are free, and one that is still running from an earlier round is left out of it (and warned about, with how long it has been running) instead of holding the others up. The count a task is given is the number of its own runs, so a task that acts on every nth run does not miss its turn in a round it sat out. Routine rounds log at debug level.
• ttl_lru_limit: Implements a TTL-based LRU rate limiter. Counters are atomic, so concurrent increments on one key are all counted.
• notification: Defines the trait for sending notifications.
• identity: Who the process is, for what it says about itself: the name and the labels of the deployment (basic.name, basic.labels), set once with set_identity and read with get_identity by the webhook, the access log and the tracer. parse_labels reads the key:value entries of the configuration.
• proxy_protocol: The PROXY protocol on the connecting side. new_proxy_protocol_header builds a version 1 or 2 header for a client's addresses, and ProxyProtocolConnector is a pingora Connect that writes it as the first bytes of a connection (PeerOptions::custom_l4). Used by send_proxy_protocol of an upstream and by its health checks; the listening side is in pingap-proxy.
• util: Contains miscellaneous utilities, including time caching and hostname retrieval.

License

This project is licensed under the Apache-2.0 License.