BlazeServe

BlazeServe started because I needed something more reliable than python -m http.server.

Quick ad-hoc servers work fine for simple files, but fall short under realistic workloads. Large file transfers eat up memory, range headers are missing, there is no bandwidth throttling, and when something fails you have zero visibility into socket health or throughput.

I built BlazeServe as a high-throughput HTTP edge tool that treats local file serving like a real systems problem.

¶Core architecture and I/O paths

To move files quickly without exhausting RAM, BlazeServe uses three distinct I/O paths depending on the request type and operating system:

¶1. Zero-copy kernel transfers (sendfile)

For full file downloads on Linux and macOS, BlazeServe bypasses user-space memory buffers with sendfile(2). The kernel transfers data directly from the filesystem cache to the network socket descriptor, cutting down CPU cycles and context switches when transferring multi-gigabyte archives.

¶2. Windowed memory-mapped files (mmap)

For range requests or constrained environments, BlazeServe uses windowed mmap reads with 256MB sliding windows. It manages pointers directly with memoryview and explicitly calls .release() on every slice after transmission. This avoids holding active page references, preventing Windows file-locking bugs and virtual memory leaks.

¶3. Buffered streaming fallback

When serving dynamic synthetic streams or environments where kernel zero-copy is disabled, BlazeServe falls back to bounded buffer chunks (configurable up to 128MB) to keep memory usage flat regardless of client connection speeds.

¶Low-level socket and network tuning

The server tunes low-level socket options automatically:

• Linux SO_REUSEPORT: balances incoming connections across worker threads on multi-core machines.
• Linux TCP_QUICKACK: sends immediate ACKs to speed up initial TCP window growth.
• TCP_NODELAY: disables Nagle's algorithm across all platforms so small chunks and headers ship without artificial latency.
• Configurable socket send buffers (--sock-sndbuf-mb, default 128MB) and a connection backlog of 8192.

¶Protocol compliance

Rather than skipping edge cases, BlazeServe implements proper HTTP standards:

• RFC 7232 and RFC 9110 conditional caching: validates ETag, Last-Modified, and If-None-Match headers, returning 304 Not Modified without re-reading file bodies from disk.
• RFC 7233 range requests: handles single and multipart byte-ranges (206 Partial Content) with valid Content-Range headers so broken downloads can resume cleanly.
• Token bucket rate limiting: thread-safe per-IP bandwidth throttling (--rate-mbps) with standard RFC 6585 headers (X-RateLimit-Limit, X-RateLimit-Remaining) and 429 Too Many Requests backoff responses.
• Dynamic streaming: generates uncompressed ZIP archives on the fly (/__zip__) for full directories and accepts chunked file uploads (/__upload__) with strict path-traversal sanitization.

¶Production observability and SRE endpoints

You cannot tune what you cannot measure. BlazeServe includes built-in operational endpoints that do not collide with served files:

• GET /__metrics__: Prometheus text exposition covering latency, requests, error counts, active connections, and egress bandwidth.
• GET /__perf__: JSON payload of active socket buffers, memory consumption, and transfer stats.
• GET /__live__ and GET /__ready__: health probes for container setups, checking process responsiveness and filesystem mount availability.
• GET /__speed__: synthetic zero-byte stream to benchmark network capacity independent of disk read speeds.

¶Production deployment assets

The project includes complete production infrastructure templates under its deployment directory:

• Hardened multi-stage Docker container based on python:3.13-slim running as an unprivileged user (UID 10001) with a read-only root filesystem.
• Sandboxed systemd service file with kernel protections (ProtectSystem=strict, ProtectHome=true, PrivateTmp=true, LimitNOFILE=1048576).
• Streaming-tuned reverse proxy blueprints for Nginx, Caddy, and Traefik v3.
• Linux kernel tuning script setting somaxconn=65535, 16MB TCP window limits, and 1M open file descriptors.
• Production Grafana dashboard and Prometheus alert rules for error spikes and connection saturation.

¶Why it stayed

BlazeServe reflects the kind of backend work I enjoy: network protocol details, practical reliability, and command-line tools that work as expected after you install them.

It is published on PyPI as blazeserve with a CLI built using Click and Rich (blaze serve, blaze doctor, blaze benchmark). It takes a routine developer task and treats it with production-grade rigor.