Module serve 

HTTP server for exposing Hexz snapshots over network protocols.

This command starts a server that exposes Hexz snapshot data over various network protocols (HTTP, NBD, S3), enabling remote access without local snapshot files. Supports daemon mode for background operation and is designed for high-performance remote snapshot access.

Server Modes

HTTP Mode (Default)

Protocol: HTTP/1.1 with Range request support Port: Configurable (default: varies by invocation) Endpoints:

• GET /disk - Serves disk image stream
• GET /memory - Serves memory dump stream (if present)
• GET /info - Returns snapshot metadata (JSON)

Range Request Support:

• Supports Range: bytes=start-end header
• Enables efficient random access and partial reads
• Used by HTTP storage backend for transparent remote mounting

Use Cases:

• Remote snapshot access over networks
• HTTP storage backend testing
• Web-based snapshot browsing
• Container registry-like snapshot distribution

Performance:

• Sequential reads: ~100-500 MB/s (network-bound)
• Random reads: ~1000-5000 IOPS (depends on network latency)
• Concurrent connections: Handled via Tokio async runtime

NBD Mode (--nbd)

Protocol: NBD (Network Block Device) protocol Port: Configurable Features:

• Block device semantics (read-only currently)
• Compatible with standard NBD clients (nbd-client)
• Lower overhead than HTTP for sequential access

Use Cases:

• Remote block device mounting
• Performance testing and benchmarking
• Integration with NBD-aware tools

Client Usage:

# Start NBD server
hexz serve snapshot.hxz --nbd --port 10809

# Connect from client
sudo nbd-client server-ip 10809 /dev/nbd0
sudo mount /dev/nbd0 /mnt

S3 Gateway Mode (--s3)

Protocol: S3-compatible REST API Status: Not yet implemented Planned Features:

• S3 GetObject with range support
• Bucket/object listing
• Compatible with S3 storage backend

Server Configuration

Port Binding:

• Binds to 127.0.0.1:<port> (localhost only)
• Default ports vary by mode (consult CLI help)
• Ensure firewall rules allow inbound connections

Daemon Mode:

• Detaches from terminal and runs in background
• Logs redirected to /tmp/hexz-serve.log and /tmp/hexz-serve.err
• Working directory: Current directory (not /)
• No PID file created (use systemd or similar for management)

Snapshot Loading:

• Opens snapshot read-only
• Loads compression dictionary if present
• Initializes appropriate decompressor (LZ4 or Zstd)
• No caching configured (each request decompresses on-demand)

Security Considerations

WARNING: This server has no authentication or encryption.

• Do not expose to untrusted networks
• Use behind a reverse proxy (nginx, haproxy) for production
• Consider TLS termination at proxy level
• Implement authentication at proxy layer

Recommendations:

• Bind to localhost (127.0.0.1) for local access
• Use SSH tunneling for remote access: ssh -L 8080:localhost:8080 server
• Deploy behind VPN for internal network access
• Use firewall rules to restrict access

Performance Tuning

Concurrency:

• Uses Tokio multi-threaded runtime (all CPU cores)
• Each connection handled concurrently
• No per-connection memory overhead beyond request buffers

Compression:

• Decompression happens on-demand for each request
• No server-side caching (stateless design)
• LZ4: ~800-2000 MB/s decompression per core
• Zstd: ~400-800 MB/s decompression per core

Network:

• Performance limited by network bandwidth and latency
• Use 10 GbE or faster for multi-GB snapshots
• Consider proximity to clients (same datacenter/region)

Common Usage Patterns

# Start HTTP server on port 8080
hexz serve snapshot.hxz --port 8080

# Start as daemon (background process)
hexz serve snapshot.hxz --port 8080 --daemon

# Start NBD server
hexz serve snapshot.hxz --nbd --port 10809

# Access from remote client
curl -H "Range: bytes=0-1024" http://server:8080/disk

# Mount via HTTP backend
hexz mount http://server:8080 /mnt

Functions

run

Executes the serve command to start a network server.