Skip to content

ANALYSIS.md

Latest commit

 

History

History
126 lines (84 loc) · 3.64 KB

ANALYSIS.md

File metadata and controls

126 lines (84 loc) · 3.64 KB
Raw

Axum Version Analysis

Goal

The goal of this rewrite was not to mechanically translate the old iron code, but to replace it with an axum implementation while keeping the CLI and the main runtime behavior aligned as closely as practical, with a smaller direct dependency surface.

The default direct dependencies are:

  • axum 0.8.8
  • clap 4.6.0
  • tokio 1.50.0
  • flate2 1.1.9
  • mime_guess 2.0.5
  • httpdate 1.0.3
  • base64 0.22.1
  • time 0.3.47

When the tls feature is enabled, it additionally pulls in:

  • openssl 0.10.76
  • tokio-openssl 0.6.5

clap intentionally does not use derive, and TLS is intentionally behind a single tls feature that is disabled by default.

Benefits

  • The server now sits on a maintained async stack instead of the old iron ecosystem.
  • The direct dependency surface is smaller and easier to reason about.
  • TLS uses axum::serve with a custom listener instead of adding axum-server.
  • The codebase is split into focused modules for config, server setup, handlers, and utilities.
  • The default build does not carry OpenSSL or TLS glue code.

Tradeoffs and Pitfalls

1. TLS is optional, but when enabled it uses system OpenSSL

To keep the default build smaller, TLS is disabled unless tls is enabled.

Impact:

  • Default builds are smaller and compile faster.
  • TLS-capable builds depend on system OpenSSL compatibility.
  • --cert still uses PKCS#12, which keeps CLI behavior aligned but keeps TLS on the OpenSSL path.

2. File responses are streamed

Regular file responses and compressed file responses are streamed instead of buffering the entire file.

Impact:

  • Memory usage is much lower for large files.
  • Compressed responses still use a background thread per streamed file response.

3. Uploads are streamed to temporary files

Uploads are written to temporary files first, then moved into place after CSRF validation succeeds.

Impact:

  • Large uploads do not need to sit fully in memory.
  • Failed CSRF validation cleans up temporary files.

4. base-url is normalized

--base-url is normalized to start with /, and to end with / when it is not root.

Impact:

  • Inputs like prefix, /prefix, and /prefix/ all normalize to /prefix/.

5. --try-file semantics are explicit

  • Relative paths are resolved against the server root.
  • Absolute paths are used as-is.

This is more explicit than the old behavior and matches the current help text.

6. HEAD + compression is cleaner, not identical

The old middleware-based compression path had some inconsistent historical behavior for HEAD.

The current implementation does not preserve those quirks:

  • HEAD does not read and compress the whole file just to compute a compressed length.
  • The result is cleaner HTTP behavior, but not byte-for-byte historical parity in that edge case.

Compatibility Summary

Kept aligned

  • CLI flags and short options
  • Directory listing
  • --index
  • --upload / --csrf
  • --auth
  • --redirect
  • --nocache
  • --norange
  • --cors
  • --coop / --coep
  • --compress
  • --try-file
  • --base-url
  • --cert / --certpass with PKCS#12

Intentional fixes

  • --open uses https:// when TLS is enabled
  • Error pages escape injected text
  • --cors responds to OPTIONS preflight requests
  • --upload-size-limit supports human-readable values such as 30K, 50M, and 1G, interpreted with powers of 1024

Verification

The current replacement is covered by black-box HTTP tests for:

  • directory listing
  • try-file
  • basic auth
  • range requests
  • cache revalidation
  • CORS preflight
  • upload with CSRF
  • gzip compression

Both default and tls builds pass cargo test and cargo clippy.