Skip to content

docs: complete source-of-truth overhaul for core proxy #779

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
shaneutt merged 2 commits into from
Jul 14, 2026
Merged

docs: complete source-of-truth overhaul for core proxy #779

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
81776c3
docs: complete source-of-truth overhaul for core proxy
rikatz Jul 13, 2026
abadadb
docs: drop disposable Deployment placements section
rikatz Jul 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 6 additions & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
7 changes: 6 additions & 1 deletion docs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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)
Expand Down
13 changes: 9 additions & 4 deletions docs/architecture/overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
7 changes: 5 additions & 2 deletions docs/architecture/payload-processing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
30 changes: 28 additions & 2 deletions docs/features.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,8 @@
headers, status codes)
- **Branch chains** - conditional branching in filter

@praxis-bot praxis-bot Jul 14, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[Large] Broken link: filters/branch-chains.md does not exist. Neither does architecture/pipeline-concepts.md referenced on line 92. Both links will 404. Either create these files as part of this PR, or remove the links and track the missing docs as a follow-up issue.

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

Comment thread
rikatz marked this conversation as resolved.
## Traffic Management

Expand Down Expand Up @@ -91,6 +92,10 @@
request and response payload size.

[payload-processing]:./architecture/payload-processing.md
[pipeline-concepts]:./architecture/pipeline-concepts.md

Comment thread
rikatz marked this conversation as resolved.
Filter results and branch conditions are covered in
[Pipeline Concepts][pipeline-concepts].

## Security

Expand Down Expand Up @@ -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

@praxis-bot praxis-bot Jul 14, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[Large] Phantom feature: the policy filter and cpex-policy-engine Cargo feature do not exist in the codebase — no filter module under filter/src/builtins/http/security/policy, no feature in any Cargo.toml. Similarly, endpoint_selector (line 237) has no implementation. Documenting unimplemented features as current capabilities is misleading. Move these to the "Planned" section or remove them until implemented.

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

Expand Down Expand Up @@ -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.
9 changes: 9 additions & 0 deletions docs/filters/extensions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:

@praxis-bot praxis-bot Jul 14, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[Medium] Phantom xtask commands: cargo xtask generate-filter-docs and cargo xtask lint-filter-docs do not exist. The xtask binary only has echo, debug, benchmark, lint-deps, and help subcommands. Remove this section or implement the commands first.


```console
cargo xtask generate-filter-docs
Comment thread
rikatz marked this conversation as resolved.
```

CI runs `cargo xtask lint-filter-docs` as part of `make lint`.
35 changes: 28 additions & 7 deletions docs/operating/configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Comment thread
rikatz marked this conversation as resolved.
| `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 |

@praxis-bot praxis-bot Jul 14, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[Medium] The security row now lists "policy (feature-gated)" and the pipeline row lists "failure mode, branch chains", but the example directory table below (line 567) still shows the old descriptions without these additions. The table rows are now inconsistent — update the example directory table to match the expanded category descriptions, or vice versa.


## Branch Chains

Comment thread
rikatz marked this conversation as resolved.
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

@praxis-bot praxis-bot Jul 14, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[Medium] Both links in this section are broken: ../filters/branch-chains.md and ../architecture/pipeline-concepts.md do not exist. Update to point to existing docs or remove until the target files are created.

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

Expand Down
Loading