diff --git a/README.md b/README.md index 8d456217..4e2ff129 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,12 @@ [![MSRV: 1.96](https://img.shields.io/badge/MSRV-1.96-brightgreen.svg)](https://blog.rust-lang.org/) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) -Praxis is a high-performance and security-first proxy server and framework for AI and cloud-native workloads. +Praxis is a high-performance, security-first **proxy framework** +built on a composable filter pipeline. Use it for ingress or +egress traffic with routing, load balancing, and security +filters. AI Gateway capabilities ship in +[praxis-ai](https://github.com/praxis-proxy/ai); see +[AI Gateway overview](https://github.com/praxis-proxy/ai/blob/main/docs/overview.md). ## Getting Started diff --git a/docs/README.md b/docs/README.md index d32df47c..38dacd61 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,6 +1,11 @@ # Praxis Documentation -## Getting Started +Praxis is a high-performance, security-first **proxy framework** +with a composable filter pipeline for routing, load balancing, +and security. AI Gateway docs live in +[praxis-ai overview](https://github.com/praxis-proxy/ai/blob/main/docs/overview.md). + +## Getting started - [Quickstart](quickstart.md) - [Features](features.md) diff --git a/docs/architecture/overview.md b/docs/architecture/overview.md index caeb3d67..af14c601 100644 --- a/docs/architecture/overview.md +++ b/docs/architecture/overview.md @@ -24,10 +24,15 @@ compose a bespoke proxy server from the same primitives. ## Primary Use-Cases -- **Ingress**: Reverse proxy, API gateway, edge proxy -- **Egress**: Outbound proxy, service-to-service -- **East/West**: Sidecar or converged proxy for service mesh -- **Security Gateway**: Guardrails, Network Policy +- **Ingress**: API gateway, edge proxy, traffic ingestion +- **Egress**: Workloads call Praxis; Praxis reaches configured + upstreams +- **East/West**: Sidecar or colocated proxy next to a workload +- **Security gateway**: Guardrails, network policy +- **AI inference and agents**: [AI Gateway][ai-overview] on + `praxis-ai` (not the core `praxis` binary) + +[ai-overview]: https://github.com/praxis-proxy/ai/blob/main/docs/overview.md ## System Architecture diff --git a/docs/architecture/payload-processing.md b/docs/architecture/payload-processing.md index 663fea78..8e4b9dee 100644 --- a/docs/architecture/payload-processing.md +++ b/docs/architecture/payload-processing.md @@ -30,8 +30,11 @@ Two delivery modes: limit by default; an optional `max_bytes` returns 413 when exceeded. Enables streaming inspection with deferred forwarding for protocol parsing, body-based routing, and - security use cases including content scanning, - payload inspection, and body-based routing. + security use cases including content scanning and payload + inspection. [praxis-ai][ai-overview] builds on the same + StreamBuffer model for AI request classification. + +[ai-overview]: https://github.com/praxis-proxy/ai/blob/main/docs/overview.md When StreamBuffer mode is active, the protocol layer pre-reads the body during the request phase (before diff --git a/docs/features.md b/docs/features.md index a6069c08..2b4321ab 100644 --- a/docs/features.md +++ b/docs/features.md @@ -15,7 +15,8 @@ headers, status codes) - **Branch chains** - conditional branching in filter pipelines based on filter results, with skip-forward, - terminal short-circuit, and re-entrance loops + terminal short-circuit, and re-entrance loops. + See [Branch Chains](filters/branch-chains.md). ## Traffic Management @@ -91,6 +92,10 @@ request and response payload size. [payload-processing]:./architecture/payload-processing.md +[pipeline-concepts]:./architecture/pipeline-concepts.md + +Filter results and branch conditions are covered in +[Pipeline Concepts][pipeline-concepts]. ## Security @@ -136,7 +141,10 @@ deployment guidance. injection with trusted proxy CIDR support - **Credential injection**: per-cluster API key injection into upstream request headers with environment variable - or inline values + or inline values; client credential stripping +- **Policy engine** (`policy`, experimental, feature + `cpex-policy-engine`): JWT identity, route policy, PII + scanning, audit ## Observability @@ -229,3 +237,21 @@ deployment guidance. - **External processing** (`ext_proc`): Envoy-compatible gRPC external processing filter (opt-in, separate crate) +- **Endpoint selector**: pin upstream endpoints from + trusted mutation sources (e.g. `ext_proc`). +- **Failure mode**: per-filter `failure_mode: open` for + non-security filters when runtime errors should not + block traffic. + +## AI gateway + +An **AI Gateway** (AI API Gateway) routes, manages, enriches, +and parses inference and agentic traffic between workloads and +model or agent backends. Full definitions: +[praxis-ai overview](https://github.com/praxis-proxy/ai/blob/main/docs/overview.md). + +LLM provider filters, MCP/A2A, response storage, and token +metadata ship in [praxis-ai](https://github.com/praxis-proxy/ai), +not the core `praxis` binary. Core filters such as +`json_rpc`, `credential_injection`, and `router` compose +with AI filters in `praxis-ai` pipelines. diff --git a/docs/filters/extensions.md b/docs/filters/extensions.md index c700de41..904ad5a0 100644 --- a/docs/filters/extensions.md +++ b/docs/filters/extensions.md @@ -560,3 +560,12 @@ filter with `FilterFactory::Http(Arc::new(factory))`, build a minimal YAML config, and assert on status codes and response bodies. See `tests/integration/` for examples. + +Built-in filter reference pages are generated from source. +After changing a filter config struct, run: + +```console +cargo xtask generate-filter-docs +``` + +CI runs `cargo xtask lint-filter-docs` as part of `make lint`. diff --git a/docs/operating/configuration.md b/docs/operating/configuration.md index 3513cf70..0bbce5ab 100644 --- a/docs/operating/configuration.md +++ b/docs/operating/configuration.md @@ -607,14 +607,35 @@ by category: | Directory | Contents | | ----------- | ---------- | -| `traffic-management` | Router, load balancer, timeouts, static responses, redirects, rate limiting, health checks | -| `payload-processing` | Body processing: compression, field extraction, stream buffering, size limits | -| `security` | Forwarded headers, IP ACL, guardrails, CORS, downstream read timeout | -| `observability` | Access logs, request IDs | -| `transformation` | Header manipulation, path rewriting, URL rewriting | +| `branching` | Branch chains: conditional skip, terminal, reentrance, cross-chain | +| `traffic-management` | Router, load balancing, timeouts, redirects, rate limiting, static responses, P2C, canary, circuit breaker, health checks, gRPC detection | +| `payload-processing` | Compression, JSON field extraction, stream buffering, size limits | +| `security` | CORS, CSRF, IP ACL, guardrails, policy (feature-gated), forwarded headers, downstream read timeout | +| `observability` | Access logs, request IDs, TCP access logs | +| `transformation` | Headers, path rewrite, URL rewrite | | `protocols` | TCP, TLS, mixed protocol configs | -| `pipeline` | Filter chain composition and conditions | -| `operations` | Production gateway, multi-listener, admin | +| `pipeline` | Chain composition, conditions, failure mode, branch chains | +| `operations` | Hot reload, admin, multi-listener, max connections, production gateway | + +## Branch Chains + +Conditional sub-pipelines based on filter results: +short-circuit responses, skip filters, retry loops, and +cross-chain routing. See [Branch Chains](../filters/branch-chains.md) +and [Pipeline Concepts](../architecture/pipeline-concepts.md). + +## Health Checks + +Per-cluster active HTTP/TCP probes and passive inline +failure tracking remove unhealthy endpoints from rotation. +See [health-checks.yaml](../../examples/configs/traffic-management/health-checks.yaml). + +## Failure Mode + +Filters declare `failure_mode: open` (continue on error) +or `closed` (reject the request). Security-critical +filters reject open mode by default. See +[failure-mode.yaml](../../examples/configs/pipeline/failure-mode.yaml). ## Validation and Security