How mufeedvh/binserve works
Project Type and Purpose
• Type: CLI-driven, full-feature static web server.
• Purpose: Serve static files (and templates) over HTTP/HTTPS with fast in-memory caching, file-system hot-reload, custom routing, and basic security measures.
File Structure
• Top-level files:
• Cargo.toml (Rust dependency manifest)
• Dockerfile (containerization)
• binserve.json (default config)
• BENCHMARKS.md, README.md
• Directories:
• .github/ (CI pipeline)
• assets/ (logo, images)
• src/cli/ (CLI interface, banners, messages)
• src/core/: core engine modules—config loader, server, router, caching, filesystem watcher, TLS, templating
• src/starter/: boilerplate HTML, assets, Handlebars templates
• Key modules:
• main.rs launches CLI → config → core
• core/server.rs wires up Actix-Web HTTP/TLS server
• core/engine.rs initializes cache, router, watcher
• core/watcher.rs watches FS events, triggers cache updates
• core/templates.rs integrates Handlebars
• core/files.rs reads files and metadata
• core/routes.rs maps URIs to resources
• core/tls.rs configures Rustls for HTTPS
• core/config.rs parses binserve.json + CLI args
Extract Insights from the README
• Stack: Rust, Actix-Web, DashMap, Handlebars-Rust, notify, rustls
• Features: Routing, Caching (fast_mem_cache), Hot-Reload, Templating, TLS, Security (directory traversal prevention), Configuration via JSON + CLI flags
• Runtime flow: load config → build route index → preload files into in-memory DashMap → start HTTP/TLS listeners → on request, consult cache & router → serve file/template with correct headers → watcher thread listens for changes → update cache atomically
Main Components & Interactions
a. CLI & Config Loader
• Reads binserve.json and CLI flags → produces a Config object
b. Core Engine
• Router Module: builds URI→resource map
• Cache Module: DashMap storing preloaded file content + metadata
• Filesystem Reader: reads files, MIME types, generates ETags/Last-Modified
• Template Engine: Handlebars runtime for .hbs files + partials
• Watcher: background thread using notify to detect FS changes → triggers cache update
• TLS Module: configures Rustls server if enabled
c. HTTP/TLS Server
• Actix-Web application with routes wired to handler functions
• Handlers consult Router + Cache + Template Engine → build HTTP response
d. External Services & Tools
• CI/CD (GitHub Actions)
• Docker containerization (via Dockerfile)
Architectural Patterns & Principles
• Modular layering: clear separation between CLI, core logic, HTTP layer
• Event-driven concurrency: Actix event loop + file watcher thread
• In-memory cache: DashMap for thread-safe, concurrent reads/writes
• Configuration via Data: JSON + CLI flags → no hard-coded behavior
• Single-binary deployment: static linking, zero external dependencies