Skip to content

README.md

Latest commit

 

History

History
273 lines (205 loc) · 9.48 KB

README.md

File metadata and controls

273 lines (205 loc) · 9.48 KB

PureSimpleHTTPServer

A fast, single-binary HTTP/1.1 static file server with middleware architecture, HTTPS, and dynamic gzip compression — written in PureBasic.

Reference model: Caddy file-server

Quick Start

# 1. Build
pbcompiler -cl -t -o PureSimpleHTTPServer src/main.pb

# 2. Run
./PureSimpleHTTPServer --root ./wwwroot --port 8080

# 3. Verify
curl -I http://localhost:8080/

Features

Serving

  • HTTP/1.1 static file serving with Content-Type, ETag, Last-Modified
  • 304 Not Modified via If-None-Match
  • 206 Partial Content via Range header
  • Directory listing (opt-in via --browse)
  • SPA fallback (opt-in via --spa)
  • Hidden path blocking (.git, .env, .DS_Store by default)
  • Embedded asset serving via IncludeBinary + CatchPack (opt-in at build time)
  • Thread-per-connection for concurrent request handling

Middleware Architecture (v2.0.0+)

  • 15-stage ordered middleware chain (Rewrite → HealthCheck → IndexFile → CleanUrls → SpaFallback → HiddenPath → Cors → BasicAuth → SecurityHeaders → ETag304 → GzipSidecar → GzipCompress → EmbeddedAssets → FileServer → DirectoryListing)
  • Post-processing middleware pattern (GzipCompress, SecurityHeaders, Cors wrap downstream)
  • ResponseWriter abstraction for pluggable body output

Security & API (v2.5.0+)

  • Health check endpoint (--health PATH) for load balancers
  • CORS support (--cors, --cors-origin ORIGIN) with OPTIONS preflight
  • Security headers (--security-headers): X-Content-Type-Options, X-Frame-Options, X-XSS-Protection, Referrer-Policy, Cross-Origin-Opener-Policy
  • Custom error pages (--error-pages DIR) for branded 403/404/500 responses
  • HTTP Basic Authentication (--basic-auth USER:PASS) for all requests
  • Configurable Cache-Control headers (--cache-max-age N)

TLS / HTTPS (v2.1.0+)

  • Manual certificate support (--tls-cert, --tls-key)
  • Automatic HTTPS via acme.sh (--auto-tls DOMAIN)
  • Background certificate renewal (12-hour check interval)
  • HTTP→HTTPS redirect with ACME challenge serving on port 80

Compression (v2.3.0+)

  • Dynamic gzip compression for text, JSON, JS, XML, SVG responses
  • Pre-compressed .gz sidecar support (Content-Encoding: gzip)
  • Disable with --no-gzip

URL Processing

  • URL rewriting and redirecting via rewrite.conf (exact, glob, regex patterns)
  • Per-directory rewrite rules (auto-reloaded on change)
  • Clean URLs (--clean-urls: /page → /page.html)

Logging

  • Access log in Apache Combined Log Format (CLF)
  • Error log with level filtering (none/error/warn/info)
  • Size-based and daily log rotation
  • SIGHUP log reopen for logrotate integration

Windows

  • Native Windows Service support with Event Log integration
  • Professional NSIS installer with service installation
  • Portable ZIP package

CLI Flags

Server:

Flag Default Description
--port N 8080 Listening port
--root DIR wwwroot/ next to binary Document root directory
--browse off Enable directory listing
--spa off SPA mode: serve index.html for all 404s

TLS:

Flag Default Description
--tls-cert FILE (disabled) Path to PEM certificate file
--tls-key FILE (disabled) Path to PEM private key file
--auto-tls DOMAIN (disabled) Enable automatic HTTPS via acme.sh for DOMAIN

Compression:

Flag Default Description
--no-gzip off Disable dynamic gzip compression

Security & API:

Flag Default Description
--health PATH (disabled) Health check endpoint returning {"status":"ok"}
--cors off Enable permissive CORS (Access-Control-Allow-Origin: *)
--cors-origin ORIGIN (disabled) Enable CORS restricted to a specific origin
--security-headers off Add security headers (nosniff, X-Frame-Options, etc.)
--error-pages DIR (disabled) Serve custom HTML error pages from DIR (e.g., 404.html)
--basic-auth USER:PASS (disabled) HTTP Basic Authentication for all requests
--cache-max-age N 0 Cache-Control max-age in seconds

Logging:

Flag Default Description
--log FILE (disabled) Write access log (Apache Combined Log Format)
--error-log FILE (disabled) Write error log
--log-level LEVEL warn Error log threshold: none, error, warn, info
--log-size MB 100 Rotate log when it exceeds MB (0 = disabled)
--log-keep N 30 Max rotated archive files to keep
--no-log-daily off Disable daily midnight log rotation
--pid-file FILE (disabled) Write process ID to FILE at startup

URL:

Flag Default Description
--clean-urls off Serve /page.html when /page is requested
--rewrite FILE (disabled) Load URL rewrite/redirect rules from FILE

Windows Service (Windows only):

Flag Description
--install Install as Windows service (requires Administrator)
--uninstall Uninstall Windows service
--start Start Windows service
--stop Stop Windows service
--service Run as Windows service (called by SCM)
--service-name NAME Custom service name (default: "PureSimpleHTTPServer")

Deployment Modes

Mode When to use
Standalone Development, low-traffic sites
HTTPS Direct Single-server production with TLS
Reverse Proxy Production behind Caddy/nginx (recommended)

See docs/deployment.md for configuration details, capacity estimates, and multi-instance management.

Testing

cd tests
./run_tests.sh

148 unit tests across 13 test files. All tests pass.

Architecture

Every HTTP request flows through an ordered middleware chain:

Client → TCP → RunRequest() → [chain] → send → free → log

Chain:  Rewrite → HealthCheck → IndexFile → CleanUrls → SpaFallback
        → HiddenPath → Cors → BasicAuth → SecurityHeaders → ETag304
        → GzipSidecar → GzipCompress → EmbeddedAssets → FileServer
        → DirectoryListing

See docs/developer-guide.md for the full middleware architecture documentation.

Documentation

User Guides (docs/user/)

Developer Guides (docs/developer/)

Deployment & Operations

Windows Deployment

Windows Installer

PureSimpleHTTPServer includes a professional Windows installer with:

  • GUI installer with license agreement
  • Optional Windows Service installation
  • Start Menu & Desktop shortcuts
  • Automatic uninstaller
  • Silent installation support

Download PureSimpleHTTPServer-{version}-windows-setup.exe and run the installer.

Portable Version

A portable ZIP package is available for Windows - no installation required:

  • Download PureSimpleHTTPServer-{version}-windows-portable.zip
  • Extract to any directory
  • Run PureSimpleHTTPServer.exe

Windows Service

Run PureSimpleHTTPServer as a native Windows service:

# Install service (requires Administrator)
PureSimpleHTTPServer.exe --install

# Start service
net start PureSimpleHTTPServer

# Stop service
net stop PureSimpleHTTPServer

# Uninstall service
PureSimpleHTTPServer.exe --uninstall

Service features:

  • Automatic startup on boot (if configured)
  • Runs in background without console window
  • Integrated with Windows Event Log
  • Graceful shutdown on system shutdown
  • Full Service Control Manager integration

Building on Windows

build.bat          # Build executable
package.bat        # Create installer and portable package
verify_build.bat   # Verify build

Requirements: PureBasic 6.x compiler, NSIS (for installer creation)

Build

Requires PureBasic 6.x. Compile as a console application with thread-safe mode:

pbcompiler -cl -t -o PureSimpleHTTPServer src/main.pb

Load Testing

Verified with Apache Bench on macOS ARM64 (Apple M4 Pro):

ab -n 1000 -c 10 http://127.0.0.1:8080/
Metric Result
Requests 1000 / 1000 (no failures)
Concurrency 10 simultaneous connections
Mean response time 2 ms
Transfer rate ~38 MB/s
Crashes None