nano-web

Static file server built with Rust. Serves files from memory with pre-compressed variants.

Performance

• Axum/Hyper HTTP stack
• Files pre-compressed at startup (brotli/gzip/zstd)
• Lock-free concurrent HashMap routing
• Zero-copy serving with Bytes

Benchmark (M3 Max 36GB):

wrk -c 50 -d 10 -t 50 http://localhost:3000
Running 10s test @ http://localhost:3000
 50 threads and 50 connections
 Thread Stats   Avg      Stdev     Max   +/- Stdev
   Latency   328.63us   47.98us   2.86ms   88.05%
   Req/Sec     3.01k   103.63     3.21k    91.58%
 1513328 requests in 10.10s, 8.58GB read
Requests/sec: 149838.48
Transfer/sec:    870.24MB

I know web-server benchmarks are mostly useless, however, this server does very little, and this is it's literal use case (serve file quick!).

Based on trying other high-performance servers locally, I reckon nano-web would place in the top ten in the TechEmpower plaintext webserver benchmarks if ran on their hardware (haven't got around to submitting it yet). It beats out may-minihttp, for instance.

Features

• In-memory file serving with compression
• SPA mode with index.html fallback
• Dev mode with file watching
• Health endpoint at /_health
• Runtime environment variable injection
• JSON/console logging
• Docker image size of ~5MB

📦 Installation

Install with Mise (via ubi)

mise install ubi:radiosilence/nano-web

Install with Cargo

cargo install nano-web

Download Binary

Pre-built binaries available on GitHub Releases.

🐳 Docker

Multi-arch images available:

FROM ghcr.io/radiosilence/nano-web:latest
COPY ./dist /public/

Production example:

FROM node:lts-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npm run build

FROM ghcr.io/radiosilence/nano-web:latest
COPY --from=builder /app/dist/ /public/
EXPOSE 3000

🔧 Usage

# Serve files from ./public/ on port 3000
nano-web serve

# Custom directory and port
nano-web serve ./dist --port 8080

# SPA mode with dev reloading
nano-web serve --spa --dev --port 3000

# See all options
nano-web serve --help

⚙️ Configuration

Environment Variables

# Docker example
docker run -p 3000:3000 -e PORT=3000 -e SPA_MODE=true ghcr.io/radiosilence/nano-web:latest

⚡ Runtime Environment Injection

Inject configuration at runtime without rebuilding, so you can re-use the same image for different things quickly and easily (or distribute it).

<!-- Your index.html -->
<script type="module">
  window.ENV = JSON.parse("{{EscapedJson}}");
  // or direct injection if you don't mind the broken syntax:
  window.ENV = {{Json}};
</script>

// env.ts
import * as z from "zod";
const EnvSchema = z.object({
  API_URL: z.url(),
});
// Parse and validate environment variables
const result = EnvSchema.safeParse(window.ENV);

if (!result.success) {
  throw new Error(
    `Environment validation failed:\n${z.prettifyError(result.error)}`,
  );
}
export const { API_URL } = result.data;

# Same build, different configs
docker run -e VITE_API_URL=http://localhost:3001 my-app    # dev
docker run -e VITE_API_URL=https://api.prod.com my-app     # prod

Template Engine

Uses MiniJinja template syntax for environment variable injection. Variables available:

• {{env.VARIABLE_NAME}} - Direct variable access
• {{Json}} - Raw JSON string of all prefixed variables
• {{EscapedJson}} - JSON-escaped for inline JavaScript

Templating is run at startup and cached.

🏥 Health Checks

Built-in health endpoint at /_health:

{ "status": "ok", "timestamp": "2025-01-15T10:30:45Z" }

📊 Logging

Console format (default):

2025-08-12T18:15:00.990620Z  INFO nano_web::routes: Processing 18 files in parallel
   at src/routes.rs:70

 2025-08-12T18:15:01.207449Z  INFO nano_web::routes: Routes populated: 20 routes
   at src/routes.rs:102

 2025-08-12T18:15:01.207466Z  INFO nano_web::server: Routes loaded: 20
   at src/server.rs:46

 2025-08-12T18:15:01.207564Z  INFO nano_web::server: Starting server on 0.0.0.0:3001
   at src/server.rs:53

JSON format for log aggregation:

{"timestamp":"2025-08-12T18:16:23.667689Z","level":"INFO","fields":{"message":"Processing 18 files in parallel"},"target":"nano_web::routes"}
{"timestamp":"2025-08-12T18:16:23.878820Z","level":"INFO","fields":{"message":"Routes populated: 20 routes"},"target":"nano_web::routes"}
{"timestamp":"2025-08-12T18:16:23.878843Z","level":"INFO","fields":{"message":"Routes loaded: 20"},"target":"nano_web::server"}
{"timestamp":"2025-08-12T18:16:23.878998Z","level":"INFO","fields":{"message":"Starting server on 0.0.0.0:3001"},"target":"nano_web::server"}

🛠️ Building from Source

# Clone and build
git clone https://github.com/radiosilence/nano-web.git
cd nano-web
cargo build --release

# Run tests
cargo test

# Run benchmarks
cargo bench

Development

# Development server with hot-reload
cargo run -- serve ./public --dev --spa

# Watch for changes
cargo watch -x "run -- serve ./public --dev"

🌰 Advanced: Unikernels

Deploy as unikernels with Nanos:

{
  "Dirs": ["public"],
  "Env": {
    "SPA_MODE": "1",
    "PORT": "8080"
  },
  "RunConfig": {
    "Ports": ["8080"]
  }
}

ops image create -c config.json --package nano-web:latest -i my-website
ops instance create my-website --port 8080

Architecture

• HTTP: Axum + Hyper
• Routing: Lock-free DashMap with FxHash
• Compression: Parallel pre-compression at startup
• Memory: Zero-copy serving with Bytes
• Security: Path validation, security headers
• Runtime: Tokio async

Compared to previous Go version: 70% faster (130k vs 76k req/sec), lower latency, no GC overhead.

📄 License

Licensed under the MIT License - see LICENSE for details.

🙏 Acknowledgments

• Axum - Ergonomic async web framework
• Hyper - Fast HTTP implementation
• Tokio - Asynchronous runtime
• DashMap - Lock-free concurrent HashMap
• Brotli - Compression library