actix/actix-web
github.com/actix/actix-web ↗ · 442 files · 3.1 MB
Actix Web Actix Web is a powerful, pragmatic, and extremely fast web framework for Rust Features - Supports HTTP/1.x and HTTP/2 - Streaming and pipelining - Powerful request routing with optional macros - Full Tokio compatibility - Keep-alive and slow requests
Overview
Actix Web is a Rust framework and companion library workspace for building asynchronous HTTP services, with typed request extraction, composable middleware, ordered routing, static files, multipart uploads, and an HTTP/WebSocket client. Its implementation separates application services from HTTP protocol machinery and runs server workers on single-threaded Tokio runtimes. This brief investigates commit 30c831fce5328ccf916bea77e59ce6419b457e39 through public source, examples, tests, manifests, and all seven listed workflows; it describes source behavior without claiming executed validation or measured performance.
System map
The root workspace contains ten cooperating library crates, with local patches connecting their development builds. Application construction and routing live in actix-web, while actix-http supplies protocol services and actix-router supplies matching. Examples provide executable entrypoints; runtime and listener management cross into external Actix and Tokio crates. Storage in the inspected implementation consists of application state and filesystem services, with database integrations left to applications.
- Cargo.toml declares ten workspace members, resolver 2, Rust edition 2021, and MSRV 1.88; its crates.io patches redirect the companion packages to local paths.
- actix-web depends on actix-http, actix-router, optional actix-web-codegen, and external actix-server/service/runtime crates; these dependencies establish separate application, protocol, routing, and runtime boundaries.
- Each HTTP worker uses a single-threaded Tokio runtime; HttpServer::workers documents at least one application-factory instantiation per worker, so application construction is repeated.
- The basic executable initializes logging, builds an App with three middleware layers and several resources, binds 127.0.0.1:8080, selects one worker, and awaits HttpServer::run.
- Manifest package names are actix-http 3.18.12, actix-files 0.7.0, and actix-http-test 3.3.0; actix-http's package name is not the dependency name reported by the supplied inventory.
- Data<T> wraps Arc-backed application state, while AppInitService owns an Rc<Extensions> container; multipart TempFile writes to NamedTempFile in a configured directory or the system temporary location.
- The repository's build/check interface is justfile: check-min and check-default use cargo-hack, clippy checks workspace targets, test combines Cargo and nextest, and test-docs builds documentation before running doctests.
- The inspected deployment example embeds libraries in a Rust server executable; run delegates to ServerBuilder. Release builds enable LTO, optimization level 3, and one codegen unit, while dependency-graph documentation provides GraphViz rendering instructions.
Feature catalog
The user-facing surface is primarily Rust APIs for service authors. Routing supports manual resources, nested scopes, guards, and procedural attributes. Typed extraction, middleware, file responses, uploads, client requests, and WebSockets cover distinct HTTP application needs. Optional features control protocol, TLS, compression, cookies, and experimental route diagnostics.
- App::route and App::service register resources and scopes; routing macros cover nine standard methods, and generated registrations attach names, method guards, custom guards, wrappers, and handlers.
- Built-in extractors expose Form, Header, Json, Path, Payload, Query, Either, and Readlines; handlers accept up to twelve FromRequest arguments and return Responder outputs.
- Middleware supports request preprocessing, response postprocessing, state access, external-service access, and short-circuiting; the basic example combines DefaultHeaders, Compress, and Logger at application and resource levels.
- Cargo features expose HTTP/2 including h2c, WebSockets, OpenSSL, four Rustls versions, Brotli/gzip/deflate/zstd compression, cookies, and separately enabled secure cookies.
- Files accepts GET/HEAD by default and supports ordered roots, optional precompressed assets, directory redirects/listings, and fallback handling; NamedFile adds ETag, Last-Modified, conditional responses, and byte ranges.
- MultipartForm collects typed form-data fields with total, memory, and field limits; the /videos example combines a TempFile upload and JSON metadata, with global and per-field limits configured separately.
- awc provides body, JSON, form, and streaming request APIs, authentication header helpers, response-decompression control, timeouts, and configurable redirects; actix-http exposes WebSocket handshake verification and a 101 response builder.
- experimental-introspection inserts an IntrospectionTree into application data and offers text, route JSON, and external-resource JSON reports; finalization also applies route reachability analysis.
Data flow
Listener factories assemble a protocol service around application factories before requests enter the application pipeline. Protocol requests carry headers, payloads, connection data, and request extensions into ServiceRequest. Routing mutates match information before extractors produce typed handler arguments, and responders turn results into HTTP output. Filesystem services and outbound client requests introduce separate input/output boundaries with their own transformation and limit rules.
- HttpServer::listen copies timeout, keep-alive, half-close, buffer, and HTTP/2 window settings into HttpService, optionally adds on_connect extensions, then maps the application factory to AppConfig.
- AppInitService::call splits a protocol Request into head and payload, transfers connection/request extensions, reuses or creates an HttpRequest, resets pooled routing state, and forwards a ServiceRequest.
- Router::recognize_fn scans resources in registration order; ResourceDef matches static or dynamic patterns, checks the predicate, stores captured segments, and advances the unprocessed path.
- Data extraction resolves the closest layered Data<T> and clones its Arc-backed wrapper; absent or mismatched registration returns an internal-server-error response rather than creating replacement state.
- Json extraction retrieves JsonConfig, consumes the payload, optionally decompresses it, checks declared and accumulated sizes, and deserializes with serde_json; the default limit is 2,097,152 bytes.
- handler_service maps extractor errors directly to HttpResponse, otherwise awaits Handler::call and Responder::respond_to; Json responders serialize a successful value and emit application/json.
- MultipartForm tracks remaining limits by field name, delegates each Field to T::handle_field, and constructs T from collected state; TempFile streams chunks to disk, consumes total/field budgets, flushes, and retains filename metadata separately.
- awc's RequestSender serializes JSON or URL-encoded forms, adds Content-Type only if absent, wraps the body in ConnectRequest::Client, and invokes the connector with per-request timeout overriding client timeout.
Behavior traces
The investigation followed startup, routed handler execution, JSON extraction, multipart disk writes, static delivery, and outbound redirects through their implementation files. Startup consumes application registrations and resolves service/data factories before handling traffic. Request paths branch on guards, extractor failures, and resource defaults. Uploads end in temporary storage unless application code supplies a separate persistence step.
- Startup begins at basic::main → HttpServer::new → bind → bind_addrs → listen → run. bind_addrs attempts every resolved address and returns successful listeners if any bind succeeds, even when another address fails.
- Worker construction proceeds through listen's closure → factory().into_factory() → App::into_factory → AppInit::new_service, which installs a default 404, consumes registrations, and constructs AppRoutingFactory plus the ResourceMap.
- App initialization constructs asynchronous data futures and the endpoint future, awaits data results then endpoint initialization, populates extensions, and returns AppInitService; AppRoutingFactory initializes child services and builds the ordered Router.
- For basic's GET /resource1/{name}/index.html, AppInitService::call → AppRouting::call → ResourceService::call → handler_service → Path::from_request → index produces the greeting. Failed application matching uses 404; unmatched resource routes use the resource's 405 default.
- A JSON handler argument follows Json::from_request → JsonBody::new(...).limit(...) → JsonBody::poll → serde_json::from_slice → JsonExtractFut. Overflow or decoding errors invoke a configured error handler when present and prevent normal handler invocation.
- POST /videos follows Multipart::from_req → MultipartForm::from_request → multipart.try_next → T::handle_field → TempFile::read_field → write_all/flush → T::from_state → post_video. The example returns upload metadata and describes deletion of the temporary file; it contains no promotion to durable storage.
- A static GET follows FilesService::call → PathBufWrap::parse_path → optional path_filter → ordered root lookup → NamedFile::open → into_response. Directory and precompressed branches can return earlier; normal file responses evaluate validators and ranges before streaming.
- An outbound JSON request follows RequestSender::send_json → send_body → connector.call → SendClientRequest. Redirect middleware rebuilds Location targets while budget remains; 301/302/303 can change methods to GET, whereas 307/308 retain the method and reuse only reusable body bytes.
Testing signals
Tests and CI were inspected, not executed; no passing result or coverage percentage was established. The examined tests include synchronous Rust unit tests, Actix asynchronous tests, real HTTP integration servers, and trybuild compiler fixtures. They cover protocol framing, shutdown ownership, static traversal, uploads, and macro diagnostics. This is bounded evidence: service-only helpers omit wire encoding/decoding, and configured exclusions or gates limit what a given test run exercises.
- The test surface combines #[test], #[actix_rt::test], and #[actix_web::test]; actix_test::TestServer uses real HTTP networking, while its documentation explicitly says init_service skips HTTP encoding and decoding.
- Decoder regression tests require rejection of duplicate Content-Length, simultaneous Content-Length/chunked Transfer-Encoding in either order, and missing or duplicate HTTP/1.1 Host headers.
- test_body checks response bytes through a real client; test_slow_request expects 408 for idle and incomplete request heads. A separate shutdown regression drives a slow JSON upload, stops gracefully, and checks that application state loses all strong references.
- Static-file integration tests assert 404 for plain/encoded traversal and NUL-containing paths, and verify that Host guards select different file roots; these assertions do not establish every symlink or filesystem-race policy.
- Multipart tests check that discarded unknown/duplicate fields still consume total limits, and that both memory-backed text and disk-backed uploads reject over-budget bodies.
- Both macro trybuild harnesses are gated by rustversion_msrv::msrv; fixtures exercise accepted forms and compile failures for routing/scope syntax, duplicate methods, multipart attributes, and size-limit syntax.
- PR/main CI checks minimal/default features and just test across Linux, macOS, and Windows on MSRV/stable; post-merge adds nightly and eight partitions of feature-combination checks, whose just recipe limits powerset depth to four.
- just test excludes test_reading_deflate_encoding_large_random_rustls and separates Cargo macro tests from nextest; coverage uses nightly llvm-cov for tests/doctests. Codecov thresholds are 100% allowances with tests/benches/examples ignored, and the benchmark workflow defines a run without supplying benchmark results here.
Risk map
These risks are source observations and explicitly labeled hypotheses, not confirmed vulnerabilities. The most sensitive inspected boundaries are proxy headers, HTTP framing, filesystem paths, upload accounting, error output, and redirected client requests. Compatibility features and older TLS support also affect maintenance and validation scope. Passing CI cannot be inferred from workflow definitions, particularly where checks are disabled or advisory.
- ConnectionInfo prefers Forwarded and X-Forwarded-* values for host, scheme, and client address. realip_remote_addr explicitly warns against security use unless those headers cannot be spoofed.
- Hypothesis: a deployment expecting served roots to prohibit symlink escapes needs explicit policy review. FilesService checks canonicalization success and opens the joined path, while Files::path_filter documents a custom symlink-denial example; the inspected traversal test does not test that deployment policy. (inferred)
- HTTP/1 header construction uses unsafe HeaderValue::from_maybe_shared_unchecked based on httparse validation. The same framing code rejects duplicate lengths/hosts and unsupported transfer encodings, making parser-contract changes a sensitive review boundary.
- Multipart limit enforcement is delegated to field readers: Limits::try_consume_limits must be called for each chunk. TempFile does this before writing, and discard_field also accounts for bytes; custom FieldReader implementations must preserve that contract.
- ResponseError's default response emits the error's Display text as text/plain with a default 500 status. Custom application errors therefore control material sent to clients unless they override error_response.
- Redirects remove Cookie, Authorization, and Proxy-Authorization when host, port, or scheme changes, but a 307/308 request with a non-reusable body is resent with an empty body; streamed mutation requests require attention to this documented implementation branch.
- deny.toml explicitly ignores nine advisory IDs, primarily under an old-Rustls-support comment, with one h2 update FIXME; license clarifications also retain older ring/webpki compatibility. This records exceptions, not a verified assessment of exploitability.
- Validation has explicit gaps: external-type lint CI is disabled for a rustdoc mismatch, semver-checks captures the command status but exits zero, and just test excludes a Rustls case. These configurations do not provide blocking verification for those paths.
Extension points
Extension is built around Rust traits and service factories rather than runtime plugin loading. Applications register resources, scopes, and custom services through builders or generated HttpServiceFactory implementations. Middleware, extractors, responders, and multipart readers expose separate contracts for customization. Client connectors and filesystem filters provide narrower integration hooks.
- App::service accepts any 'static HttpServiceFactory, while App::configure accepts a ServiceConfig callback and merges its services, external resources, application data, and optional default.
- Scope::register recursively registers nested factories using cloned configuration and a root-prefix ResourceMap; ScopeService applies its own guarded router and inherited or overridden default service.
- App::wrap accepts Transform over the inner Service; middleware can initialize services, alter request/response data, and short-circuit. Registration order is observable because the last wrapper handles incoming requests first.
- Custom request types implement FromRequest with Error, Future, and from_request; extractor configuration is supplied through App/Scope/Resource data, with a single-consumer payload constraint.
- Handler output customization uses Responder, while custom failures implement ResponseError::status_code/error_response; handler_service is the integration point converting extraction and handler outcomes into ServiceResponse.
- Multipart FieldReader defines per-field asynchronous decoding, and MultipartCollect defines limit, handle_field, and from_state. DuplicateField exposes Ignore, Deny, and Replace policies for collection implementations.
- Files::path_filter accepts a closure over a root-relative Path and RequestHead before filesystem existence checks; rejection invokes the configured default handler or returns 404.
- awc ClientBuilder::connector and wrap customize connection services and Transform middleware; finish conditionally installs Redirect according to max_redirects before constructing the Client.
Contributor handoff
Start at the affected crate's manifest and follow the service or protocol boundary implicated by the task. Preserve worker-local ownership, shared-data registration, middleware order, and feature-disabled compilation when making future changes. Tests and CI were inspected, not executed, and this brief is bounded rather than exhaustive. The commands below describe available future validation; none were run during this read-only investigation.
- Read Cargo.toml, the affected package manifest, and justfile first: workspace patches ensure cross-crate edits use local implementations, and root lint/MSRV settings apply to member crates.
- For request dispatch changes, inspect AppInitService::call, AppRouting::call, ResourceService::call, and handler_service together; guard selection, request reuse, extraction failure, and response conversion span these boundaries.
- Construct shared Data outside HttpServer::new and clone it into apps; preserve nearest-layer lookup. Tokio block_in_place is incompatible with worker runtimes, and rt::spawn requires an Actix runtime or manually configured LocalSet.
- Preserve optional-feature boundaries: defaults include macros, compression, cookies, HTTP/2, unicode, compatibility, and WebSockets; secure cookies and TLS are separate, and __tls/__compress are private feature markers.
- For separately authorized validation, start with the affected crate/test filter, then use just test and just test-docs; consult just check-min/check-default/clippy for feature and lint checks. Existing scripts separate Cargo macro suites from nextest and include a named test exclusion.
- Macro edits need runtime registration tests plus compiler fixtures: trybuild suites are MSRV-gated, and routing fixtures cover malformed paths, methods, scope attributes, and runtime macros.
- Check compatibility before changing public signatures or macro visibility: compat-routing-macros-force-pub forces generated handler structs public, semver CI currently reports rather than fails, and actix-web-actors is deprecated and omitted from the root member list.
- Choose tests matching the actual boundary: init_service omits wire codecs, traversal tests exercise lexical paths, multipart tests exercise discarded-byte accounting, and shutdown tests exercise application-data lifetime during incomplete bodies.
Languages
| Language | Files | Share of source |
|---|---|---|
| Rust | 319 | 95% |
| Markdown | 35 | docs/config |
| TOML | 16 | 5% |
| YAML | 15 | docs/config |
| JavaScript | 1 | 0% |
Start reading here
Probable source entrypoint: Cargo.toml — inferred from the directory tree and manifest, not the upstream docs.
Source roots
actix-web/ (126 files)
Source layout — actix-web/
| Path | Files |
|---|---|
actix-web/benches/ | 3 |
actix-web/examples/ | 10 |
actix-web/src/ | 27 |
actix-web/tests/ | 13 |
actix-web/CHANGES.md | 1 |
actix-web/Cargo.toml | 1 |
actix-web/LICENSE-APACHE | 1 |
actix-web/LICENSE-MIT | 1 |
actix-web/MIGRATION-0.x.md | 1 |
actix-web/MIGRATION-1.0.md | 1 |
actix-web/MIGRATION-2.0.md | 1 |
actix-web/MIGRATION-3.0.md | 1 |
actix-web/MIGRATION-4.0.md | 1 |
actix-web/README.md | 1 |
Repository structure
| Top-level path | Files |
|---|---|
actix-web/ | 126 |
actix-http/ | 100 |
actix-web-codegen/ | 39 |
awc/ | 38 |
actix-multipart/ | 31 |
actix-files/ | 27 |
actix-router/ | 17 |
.github/ | 13 |
Docs found: README.mddocs/graphs/README.md
Package
Cargo.toml — , 0 declared dependencies.
CI & config entrypoints
README.md— Repository readme.github/workflows/coverage.yml— GitHub Actions workflow.github/workflows/labeler.yml— GitHub Actions workflow.github/workflows/lint.yml— GitHub Actions workflow.github/workflows/semver-checks.yml— GitHub Actions workflow.github/workflows/ci-post-merge.yml— GitHub Actions workflow.github/workflows/ci.yml— GitHub Actions workflow.github/workflows/bench.yml— GitHub Actions workflow
Structural health signals
Average score 5.8/10 across 96 analyzed source files; 65 hotspots surfaced.
actix-files/src/lib.rs— 1346 lines, score 4 (Large file, Deep nesting)actix-multipart/src/multipart.rs— 1160 lines, score 4 (Large file, Deep nesting)actix-web/src/middleware/logger.rs— 1033 lines, score 4 (Large file, Deep nesting)
These are deterministic review leads — size, churn, and structural signals — not proof of a bug in this project.
Recent history
30c831fce5322026-10-02 — ci: partition feature combination checks (#4298)0d035acf5ed02026-10-02 — ci: remove obsolete disk space cleanup (#4299)457ffd1ebc852026-10-02 — refactor(ws): replace framing and protocol magic numbers with named constants (#4292)ef1e6f3d87602026-10-02 — build(deps): bump taiki-e/install-action from 2.87.12 to 2.87.21 (#4284)b80d150db04f2026-10-02 — refactor(http): replace magic slicing with named constants for Date header buffer (#4291)