# 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.