Crate rust_web_server 

rust-web-server

An HTTP/1.1, HTTP/2, and HTTP/3 (QUIC) server, reverse proxy, and application framework in one crate. HTTP/1.1 parsing, routing, middleware, JSON, WebSocket, and SSE are implemented in-crate; HTTP/2 and HTTP/3 framing use the h2 and quinn/h3 crates, and TLS uses rustls.

Use as a library

Add to Cargo.toml:

[dependencies]
rust-web-server = "17"

Quick start

use rust_web_server::prelude::*;

fn hello(_: &Request, _: &PathParams, _: &ConnectionInfo, _: &()) -> Response {
    Response::text(STATUS_CODE_REASON_PHRASE.n200_ok, "Hello, world!")
}

fn main() {
    let app = App::with_state(()).get("/hello", hello);
    let (listener, pool) = Server::setup().unwrap();
    Server::run(listener, pool, app);
}

See DEVELOPER.md for the full building blocks reference and use case examples.

Modules

a2a

A2A (Agent2Agent) 1.0 server, JSON-RPC binding (18.17.0, #65): other agents discover this one by its Agent Card at /.well-known/agent-card.json and talk to it with SendMessage, GetTask, ListTasks, CancelTask.

admin

The admin API (18.10.0, #29): change and inspect a running server on a listener of its own, never on the public routes.

app

application

Application: the type a server runs for every request.

async_state

Async-capable state-aware application — requires the http2 feature (tokio).

authz

Authorization (18.14.0, #32): who the caller is (Identity), and — from later tranches — what they may do, as relationship-based access control (Zanzibar-style tuples and a schema).

blocklist

Runtime IP blocklist middleware.

body

Request and response bodies.

cache

In-memory response cache middleware.

canary

Weighted canary / A-B traffic splitting middleware.

circuit_breaker

Circuit breaker state machine and retry middleware.

client_hint

cluster

Runtime state shared across replicas through Redis (18.22.0). Runtime state shared across replicas (18.22.0, #76).

compression

config_binding

Typed configuration binding — read environment variables into strongly-typed structs.

config_check

rws --check: validate rws.config.toml without starting the server — the counterpart of nginx -t / caddy validate.

config_reload

Hot configuration reload.

config_watch

Reload when the config file or a certificate changes (watch = true, #10).

controller

Controllers: one unit of request handling for App.

cookie

core

Small shared utilities: base64, sha256 (SHA-256, HMAC-SHA256) and the New trait (a constructor used across the crate, much like Default).

cors

ctl

rws ctl / rwsctl: the admin API from the command line (18.20.0). rws ctl (18.20.0, #70): the admin API from the command line.

di

Lightweight type-keyed dependency injection container.

disk_guard

Keep rws from filling a disk (18.15.0): before writing to a file it keeps growing — the access log, the disk cache — rws asks has_room. Below RWS_CONFIG_MIN_FREE_DISK free on that file’s filesystem the write is skipped (and counted) until space comes back: a full disk costs log lines and cache entries, never the server or whatever shares the disk with it.

early_hints

103 Early Hints (RFC 8297, 18.12.0, #38): Link headers a client can act on — preload a stylesheet, preconnect to an origin — while the response is still being made.

entry_point

error

ext

extract

fastcgi

FastCGI client: PHP through php-fpm (18.21.0). FastCGI (18.21.0, #72): PHP through php-fpm, and any other FastCGI responder, without FrankenPHP or a second web server.

feature

Runtime feature toggles.

header

HTTP header fields.

http

http_client

Outbound HTTP/1.1 client.

i18n

Translations (18.16.0, #33): message catalogs, one per language, and the language each request asks for.

ingress

Kubernetes Ingress watcher and router.

ip_filter

IP address allowlist and denylist middleware.

json

A dependency-free JSON parser and serializer.

language

llm

An LLM proxy (18.9.0, #41): one endpoint in front of OpenAI-compatible and Anthropic providers that counts tokens, enforces budgets and fails over between providers.

log

macros

Declarative routing macro.

maintenance

Maintenance mode middleware.

mcp

Model Context Protocol (MCP) server — HTTP Streamable HTTP transport.

metrics

Server-wide and per-route Prometheus metrics.

middleware

Composable middleware pipeline.

mime_type

null

Null: a value representing JSON null, with FromStr (failing with ParseNullError), Display, Clone, Debug, PartialEq and New.

otel

OpenTelemetry-compatible distributed tracing.

pagination

Pagination result types (Page<T>, CursorPage<T>) and an RFC 8288 Link header builder.

prelude

Convenience re-exports for writing handlers and running the server.

proxy

Reverse proxy middleware with round-robin load balancing.

proxy_config

Config-driven proxy application.

range

Byte ranges (RFC 9110 §14) and response bodies.

rate_limit

request

HTTP requests: Request and its parser.

request_id

Request ID / correlation ID middleware.

request_log

In-memory ring buffer of recent HTTP requests.

response

HTTP responses: Response, its writers and the upstream-response parser.

rewrite

Request and response rewriting middleware.

router

scheduler

Background task scheduler — a @Scheduled-style runner for fixed-rate, fixed-delay, and cron-expression tasks.

schema

JSON Schema for Rust types, for MCP tool inputSchema/outputSchema.

server

The listeners and connection loops.

server_config

Typed server configuration.

service_discovery

Dynamic backend pool with pluggable discovery sources.

session

Server-side session management.

sse

Server-Sent Events (SSE).

state

Shared application state and state-aware routing.

symbol

systemd

systemd integration (18.20.0, #67), without libsystemd.

tcp_proxy

Layer-4 TCP proxy.

test_client

thread_pool

timeout

Per-route request timeouts.

traffic

Traffic insights (18.15.0): who visits — people, AI agents, bots — worked out by rws from each request, for the admin UI’s Traffic page.

udp_proxy

Layer-4 UDP proxy.

url

URL helpers: percent encoding (URL::percent_encode / percent_decode), query strings (URL::build_query / parse_query) and whole URLs (URL::build / parse, a panic-free RFC 3986 parser). URL::parse_request_target gives a request’s path and query without inventing a scheme and host. Percent encoding is what lets a query value carry a space (%20), = (%3D) or & (%26). Examples: src/url/example/.

validate

virtual_host

waf

Web application firewall: rws’s own rules (18.22.0). Web application firewall (18.22.0, #77): rws’s own rules, no rule language to learn and no external engine.

websocket

WebSocket protocol support — RFC 6455.

ws_proxy

WebSocket reverse proxy.

Macros

routes

Build a routing app from a declarative table.