If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/TheWaWaR/simple-http-server shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• Last commit 7w ago
• 21+ active contributors
• MIT licensed
• CI configured
• ⚠ Concentrated ownership — top contributor handles 62% of recent commits
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live TheWaWaR/simple-http-server repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/TheWaWaR/simple-http-server.

What it runs against: a local clone of TheWaWaR/simple-http-server — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in TheWaWaR/simple-http-server | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | Last commit ≤ 81 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of TheWaWaR/simple-http-server. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/TheWaWaR/simple-http-server.git
#   cd simple-http-server
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of TheWaWaR/simple-http-server and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "TheWaWaR/simple-http-server(\\.git)?\\b" \\
  && ok "origin remote is TheWaWaR/simple-http-server" \\
  || miss "origin remote is not TheWaWaR/simple-http-server (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 81 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~51d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/TheWaWaR/simple-http-server"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

A lightweight static file HTTP server written in Rust using Axum and Tokio that serves files, directories (with optional listing), and handles uploads with CSRF protection. It supports range requests, gzip/deflate compression, basic auth, CORS headers, SPA fallback routing, and optional PKCS#12 HTTPS—all compiled into a small cross-platform binary for Windows/Mac/Linux. Single Rust crate with layered architecture: src/main.rs is the entry point and CLI dispatcher (using Clap), src/config.rs holds parsed arguments and configuration logic, src/handlers.rs contains Axum HTTP handler functions (directory listing, file serving, upload), src/server.rs builds and runs the Tokio-based server, and src/util.rs provides file utilities (compression, size parsing, auth). Cargo features separate TLS support to keep default binary small.

Developers and DevOps engineers who need a minimal, fast file server for local testing, CI/CD artifacts, static sites, or quick file sharing without Docker overhead or Node.js complexity—especially those already in the Rust ecosystem or using it in embedded/minimal environments.

Actively maintained and production-ready: version 0.8.0 with CI/CD workflows in .github/workflows/build.yml, cross-platform Docker builds (aarch64 and x86_64), and a well-documented README with security guidance in SECURITY.md. Single maintainer (thewawar) but stable feature set and responsive to Rust/dependencies updates.

Low risk: minimal dependency tree (Axum, Tokio, Clap for CLI, no heavy frameworks), but single-maintainer maintenance burden and TLS feature behind optional compile flag (smaller default binary but feature parity depends on build time). Rust's memory safety eliminates large classes of server vulnerabilities, but CSRF token handling in CLI arguments could leak in process listings (noted in --csrf help text).

No specific recent changes visible in file listing, but build.yml suggests active CI/CD workflows for multi-platform release builds. The Cargo.toml shows dependencies are kept current (Axum 0.8.8, Tokio 1.50.0, Clap 4.6.0 as of this snapshot). ANALYSIS.md exists, suggesting recent codebase analysis or documentation effort.

git clone https://github.com/TheWaWaR/simple-http-server.git
cd simple-http-server
cargo build --release
./target/release/simple-http-server --help

For TLS support, rebuild with cargo build --release --features tls.

Daily commands:

# Default (no TLS):
cargo run -- --port 8000 /path/to/serve

# With directory listing and uploads:
cargo run -- -i -u --port 3000 .

# With basic auth:
cargo run -- -a user:password --port 8000 /

# With TLS (requires --features tls):
cargo run --features tls -- --cert cert.p12 --certpass password --port 443 /

# Install globally:
cargo install --path . --features tls

• src/main.rs: CLI argument parsing (Clap) and main entry point; controls the entire application flow and delegates to server.rs
• src/server.rs: Axum router and Tokio server setup; where HTTP routes are bound to handlers and the server lifecycle is managed
• src/handlers.rs: Core HTTP handler implementations for directory listing, file serving, uploads, range requests, and compression
• src/config.rs: Configuration struct that holds all parsed CLI arguments and derived settings (size limits, auth, paths)
• src/util.rs: Utility functions for file operations, MIME detection, compression, and size formatting
• Cargo.toml: Dependency manifest and feature gates (tls); controls build variants and minimum Rust edition (2024)
• .github/workflows/build.yml: CI/CD workflow defining multi-platform builds and release process for all three OS targets

Adding handlers: Extend src/handlers.rs with new Axum handler functions and add routes in src/server.rs. Config changes: Add fields to src/config.rs and parsing logic in main.rs (using Clap derive macros). Utilities: File operations and compression logic in src/util.rs. Features: Wrap new functionality behind feature gates in Cargo.toml (like tls feature). Testing: No test directory visible; tests would belong in src/ with #[cfg(test)] modules or a tests/ directory (missing).

CSRF token in CLI: The --csrf flag passes the token via command line, which is visible in ps output and shell history—security warning in help text. Rust edition 2024: Requires latest Rust toolchain (check rust-toolchain file); older Rust won't compile. TLS feature coupling: OpenSSL is vendored on Windows but system-provided on *nix; --cert and --certpass only work if compiled with --features tls, silently ignored otherwise. Upload CSRF: Uploads require CSRF token in form submission; --csrf flag sets custom token but defaults require token generation logic in handlers.rs. Base URL normalization: --base-url must be '/' or normalized; trailing slashes and leading slashes are auto-corrected in config logic.

• Range Requests (HTTP 206 Partial Content) — This server supports partial file serving via Range header (disabled via --norange flag); essential for resumable downloads and media streaming
• CSRF (Cross-Site Request Forgery) Token Protection — The upload handler requires CSRF tokens to prevent malicious form submissions; understanding token validation is critical for secure file uploads
• Content Encoding (gzip/deflate) — The -c/--compress flag enables on-the-fly compression of specified file types; understanding trade-offs between CPU and bandwidth is important for tuning
• Tokio Multi-threaded Runtime — This server uses Tokio's multi-threaded runtime (configurable via --threads); understanding async task scheduling and work-stealing queues affects concurrency behavior
• HTTP Basic Authentication — The -a/--auth flag implements Basic Auth via base64-encoded credentials; important to understand it sends plaintext over HTTPS and has security implications
• CORS (Cross-Origin Resource Sharing) Headers — The --cors flag adds Access-Control-Allow-Origin header; relevant for browsers consuming this server's resources from different origins
• Single Page Application (SPA) Fallback Routing — The --try-file flag serves a fallback file (typically index.html) for missing routes; essential for SPA deployments where client-side routing handles unknown paths

• http-rs/http-server — Minimal HTTP server in Rust; direct competitor with similar feature set but different async runtime or middleware approach
• fermyon/spin — WebAssembly-based Rust HTTP server framework; if users want to compose this server as a WASM component or serverless function
• actix/actix-web — Alternative mature Rust web framework; some users may port or compare this codebase to Actix instead of Axum
• tokio-rs/tokio — The async runtime powering this project; essential for understanding the threading model and performance tuning
• tower-rs/tower — Middleware and service abstraction used by Axum; relevant for extending request/response handling in this server

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for src/handlers.rs and src/config.rs

The repo lacks visible test coverage for core request handling and configuration parsing logic. Given the critical nature of HTTP request handlers (range requests, compression, CORS, auth) and config validation, adding unit tests in src/handlers.rs and src/config.rs would catch regressions early. This is especially important since the README documents many features (upload, basic auth, SPA fallback) that should be tested.

• [ ] Add #[cfg(test)] mod tests section to src/handlers.rs covering range request logic, compression negotiation, and CORS header injection
• [ ] Add #[cfg(test)] mod tests section to src/config.rs for CLI argument parsing with clap and validation of conflicting options
• [ ] Add integration test in tests/ directory (create if missing) that validates end-to-end behavior like file upload with CSRF token and basic auth flows
• [ ] Ensure test coverage includes both happy paths and edge cases (malformed headers, invalid ranges, oversized uploads)

Add GitHub Actions workflow for cross-platform binary releases and TLS variant testing

The repo has .github/workflows/build.yml but lacks automated testing of both the default binary and the TLS-enabled variant across all three platforms (Windows/Mac/Linux). Given that the Dockerfile and Makefile exist but TLS is optional, there's no CI validation that both feature configurations build and run correctly. This prevents breaking the optional feature.

• [ ] Extend .github/workflows/build.yml with matrix strategy for [os: ubuntu-latest, macos-latest, windows-latest] and features: [default, --features tls]
• [ ] Add cargo test and cargo build steps for each OS/feature combination to catch platform-specific or feature-specific compilation errors
• [ ] Add step to verify binary works with --help flag after build to catch runtime issues early
• [ ] Consider adding release artifact upload step to attach binaries to GitHub releases (both tls and non-tls variants)

Add missing documentation for TLS setup and PKCS#12 certificate generation in SECURITY.md or a new TLS guide

README.md mentions 'optional PKCS#12 HTTPS support' and there's a SECURITY.md file present, but the repo lacks specific instructions on how to generate/use PKCS#12 certificates, what CLI flags enable TLS, and security best practices. New contributors trying to use the TLS feature have no guidance, and SECURITY.md is likely incomplete given the sensitive nature of certificate handling.

• [ ] Review SECURITY.md and document the --tls or --cert flag (check src/config.rs for exact flag name) and expected PKCS#12 file format
• [ ] Add step-by-step guide in SECURITY.md for generating self-signed PKCS#12 certs using openssl for local testing
• [ ] Add security warnings section covering: not shipping self-signed certs in production, certificate validation, and minimum TLS versions supported
• [ ] Update README.md usage section to include a TLS example command (e.g., simple-http-server --cert mycert.p12 --cert-password mypass)

• Add unit tests to src/util.rs for the size parsing logic (K/M/G/T suffix handling) and compression detection—currently no test directory exists
• Document the CSRF token flow in SECURITY.md or README with an example HTML form showing the required token field name and header (upload feature is documented but token mechanics are implicit)
• Add a --log-level flag or structured logging integration (maybe tracing crate) so users can debug directory traversal and auth without recompiling with --verbose logic

The simple-http-server project has a reasonably secure foundation built on modern Rust frameworks (axum/tokio), but has several notable issues. The most critical is the invalid Rust edition specification (2024) that will prevent compilation. Security headers are not mentioned, CSRF token handling via CLI is risky, and OpenSSL dependency management could be improved. The project would benefit from expanded security documentation and migrating from OpenSSL to rustls. Input validation for file operations and upload handling should be verified in the source code. Overall security posture

• High · Invalid Rust Edition in Cargo.toml — Cargo.toml. The Cargo.toml specifies edition = "2024", which is not a valid Rust edition. Valid editions are 2015, 2018, and 2021. This will cause build failures and indicates a configuration error that could lead to unexpected behavior or security issues if the project falls back to unintended defaults. Fix: Change edition = "2024" to edition = "2021" (the latest stable edition). This ensures the code is compiled with the intended language features and safety guarantees.
• Medium · OpenSSL Dependency for TLS — Cargo.toml (openssl and tokio-openssl dependencies). The project uses OpenSSL for optional TLS support via the tls feature. OpenSSL has a history of critical vulnerabilities and requires careful maintenance. On Windows, the vendored feature is used, but on non-Windows systems, the system OpenSSL is relied upon, which may be outdated or missing. Fix: Consider migrating to rustls, a pure-Rust TLS implementation that doesn't rely on system libraries and has better security properties. If OpenSSL is required, ensure automated dependency updates and security monitoring are in place.
• Medium · Missing Security Headers Configuration — src/handlers.rs, src/server.rs (inferred). Based on the README, the server supports basic auth, CORS, and serves static files, but there is no indication of security headers (Content-Security-Policy, X-Frame-Options, X-Content-Type-Options, Strict-Transport-Security, etc.) being configurable or enforced by default. Fix: Implement and enforce security headers by default. Provide CLI options to customize headers if needed. At minimum, add: Content-Security-Policy, X-Content-Type-Options: nosniff, X-Frame-Options: DENY, and Strict-Transport-Security (when TLS is enabled).
• Medium · CSRF Token Passed via Command Line — README.md (Usage section), src/config.rs (inferred). The README mentions that the CSRF token can be passed via command line (--csrf option). This creates a security risk as command-line arguments are visible in process listings, shell history, and system logs, potentially exposing the token. Fix: Instead of accepting CSRF tokens via command-line arguments, load them from environment variables or configuration files with restricted permissions. Document the security implications clearly.
• Low · No Input Validation Visibility — src/handlers.rs, src/util.rs (inferred). While the codebase uses established frameworks (axum, tokio), without reviewing the actual source code, there's no evidence of explicit input validation for file paths, upload handling, or directory traversal protection. The upload feature with directory listing increases the attack surface. Fix: Ensure comprehensive input validation: sanitize file paths to prevent directory traversal attacks, validate file uploads for type/size restrictions, and implement rate limiting for upload endpoints.
• Low · Limited Security Documentation — SECURITY.md. The SECURITY.md file is minimal and only contains a contact email. There are no documented security considerations, threat models, or guidance for secure deployment. Fix: Expand SECURITY.md to include: security considerations for different features, deployment recommendations, known limitations, supported versions receiving updates, and a responsible disclosure timeline.
• Low · Docker Image Security Not Clearly Defined — docker/Dockerfile.aarch64, docker/Dockerfile.x86_64. Docker files exist but their contents are not provided. Base images, user privileges, and layer security cannot be assessed. Fix: Use minimal base images (alpine, distroless), run as non-root user, implement layer caching efficiently, scan images with tools like Trivy, and keep base images updated regularly.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.