Configuration Reference

English | 中文

Complete configuration field reference for FileHunter.

📋 Overview

FileHunter uses a single TOML configuration file (typically config.toml) to define server behavior, URL routing, and file search paths. The configuration is divided into three sections:

• [server] — Global server settings (bind address, limits, timeouts)
• [server.cors] — Cross-Origin Resource Sharing (CORS) settings
• [server.rate_limit] — Per-IP rate limiting settings
• [server.compression] — Response compression settings
• [server.basic_auth] — HTTP Basic Authentication settings
• [[locations]] — URL prefix routing rules and search modes
• [[locations.paths]] — File system roots and extension filters for each location

🖥️ Server Configuration ([server])

All fields in the [server] section are optional and have sensible defaults.

Field	Type	Default	Description
bind	String	"0.0.0.0:8080"	Address and port the server listens on.
keepalive	Boolean	true	Enable HTTP keep-alive connections.
connection_timeout	Integer	300	Connection timeout in seconds. Set to 0 for unlimited.
max_header_size	ByteSize	8192 (8KB)	Maximum size of a single HTTP header. Must be >= 8KB.
max_headers	Integer	64	Maximum number of HTTP headers per request.
max_body_size	ByteSize	1048576 (1MB)	Maximum HTTP request body size.
http2_max_streams	Integer	128	Maximum concurrent HTTP/2 streams per connection.
max_file_size	ByteSize	10485760 (10MB)	Global maximum file size for responses. Set to 0 for no limit. Can be overridden per-location.
stream_buffer_size	ByteSize	65536 (64KB)	Buffer size for streaming file responses. Must be > 0.

🌐 CORS Configuration ([server.cors])

Controls Cross-Origin Resource Sharing headers. All fields are optional and have sensible defaults. CORS is disabled by default.

Field	Type	Default	Description
enabled	Boolean	false	Enable CORS header injection. When false, no CORS headers are added.
allow_origins	Array of Strings	["*"]	Allowed origins. Use ["*"] to allow any origin, or list specific origins like ["https://example.com"].
allow_methods	Array of Strings	["GET", "HEAD", "OPTIONS"]	HTTP methods allowed in CORS requests. Use ["*"] to allow all methods.
allow_headers	Array of Strings	["*"]	Request headers allowed in CORS requests. Use ["*"] to allow all headers.
expose_headers	Array of Strings	["Content-Length", "Content-Type"]	Response headers exposed to the browser. Use ["*"] to expose all headers.
max_age	Integer	86400	How long (in seconds) browsers should cache preflight responses.
allow_credentials	Boolean	false	Whether to include Access-Control-Allow-Credentials: true. Cannot be used with allow_origins = ["*"].

Validation rules:

• allow_credentials = true with allow_origins = ["*"] is rejected at startup (per the CORS specification, credentials require explicit origins).

⚡ Rate Limit Configuration ([server.rate_limit])

Controls per-IP rate limiting using the GCRA (Generic Cell Rate Algorithm). All fields are optional and have sensible defaults. Rate limiting is disabled by default.

Field	Type	Default	Description
enabled	Boolean	false	Enable per-IP rate limiting. When false, all requests are allowed without throttling.
requests_per_second	Integer	10	Sustained request rate allowed per IP address. Must be > 0 when enabled.
burst_size	Integer	30	Maximum burst of requests allowed above the sustained rate. Must be > 0 when enabled. Should be >= requests_per_second.
cleanup_interval	Integer	600	Interval in seconds between background cleanup sweeps that remove expired rate limiter entries.

Validation rules:

• requests_per_second must be > 0 when rate limiting is enabled.
• burst_size must be > 0 when rate limiting is enabled.

Behavior:

• Throttled requests receive a 429 Too Many Requests response with a Retry-After header.
• Rate limiting is checked before all other request processing.

📦 Compression Configuration ([server.compression])

Controls optional response compression. All fields are optional and have sensible defaults. Compression is disabled by default.

Field	Type	Default	Description
enabled	Boolean	false	Enable response compression. When false, responses are never compressed.
algorithms	Array of Strings	["gzip", "br"]	Compression algorithms to offer. Valid values: "gzip", "deflate", "br" (Brotli), "zstd".
min_size	ByteSize	1024 (1KB)	Minimum response body size before compression is applied. Files smaller than this threshold are sent uncompressed.

Validation rules:

• algorithms must only contain valid values: gzip, deflate, br, zstd. Unknown algorithms are rejected at startup.
• algorithms must not be empty when compression is enabled.

Behavior:

• The server reads the client's Accept-Encoding header and selects the best matching algorithm from the configured list.
• Already-compressed formats (images, videos, archives) are automatically skipped based on their MIME type.
• When compression is applied, the Content-Length header is removed and the response uses chunked transfer encoding instead.

🔐 Basic Auth Configuration ([server.basic_auth])

Controls optional global HTTP Basic Authentication. All fields are optional and have sensible defaults. Basic Auth is disabled by default.

Field	Type	Default	Description
enabled	Boolean	false	Enable HTTP Basic Authentication. When false, all requests are allowed without credentials.
username	String	""	Required username for authentication. Must be non-empty when enabled.
password	String	""	Required password for authentication. Must be non-empty when enabled.
realm	String	"filehunter"	The authentication realm sent in the WWW-Authenticate header.

Validation rules:

• username must not be empty when Basic Auth is enabled.
• password must not be empty when Basic Auth is enabled.

Behavior:

• Unauthenticated requests receive a 401 Unauthorized response with WWW-Authenticate: Basic realm="<realm>".
• Health check endpoints (/health, /ready) are exempt from authentication.
• Password comparison uses constant-time XOR-fold to prevent timing attacks.
• Authentication is checked after health endpoints but before rate limiting.

📍 Location Configuration ([[locations]])

Each [[locations]] block defines a URL prefix and how files are searched under that prefix. The server uses longest-prefix matching — more specific prefixes take priority over shorter ones.

Field	Type	Default	Description
prefix	String	(required)	URL path prefix for this location (e.g. "/imgs"). "/" acts as a catch-all. Must start with /. Cannot contain null bytes or ... Trailing slashes are stripped during normalization. Duplicate prefixes are rejected.
mode	String	"sequential"	Search mode: "sequential" checks paths in order, "concurrent" searches all paths in parallel, "latest_modified" returns the most recently modified match across all paths.
max_file_size	ByteSize	(inherits from [server])	Per-location override for the maximum file size. Falls back to the global [server].max_file_size if omitted.
paths	Array	(required)	One or more [[locations.paths]] entries defining where to search for files. At least one path is required.

📂 Search Path Configuration ([[locations.paths]])

Each [[locations.paths]] block specifies a root directory and an optional extension filter.

Field	Type	Default	Description
root	String	(required)	Absolute path to the root directory for file searches.
extensions	Array of Strings	(all files)	List of allowed file extensions without the leading dot (e.g. ["jpg", "png"]). If omitted or empty, all file types are allowed.

📏 ByteSize Format

Fields of type ByteSize accept either a raw integer (in bytes) or a human-readable string with a unit suffix.

Format	Example	Bytes
Raw integer	65536	65,536
Bytes	"8192B"	8,192
Kilobytes	"64KB" or "64K"	65,536
Megabytes	"10MB" or "10M"	10,485,760
Gigabytes	"2GB" or "2G"	2,147,483,648

Unit suffixes are case insensitive — "10mb", "10MB", and "10Mb" are all equivalent.

✅ Validation Rules

The following rules are enforced when loading the configuration:

• max_header_size must be >= 8KB (8192 bytes) — this is the minimum value that hyper accepts.
• stream_buffer_size must be > 0.
• allow_credentials = true is incompatible with allow_origins = ["*"] in [server.cors].
• requests_per_second and burst_size must be > 0 when [server.rate_limit] is enabled.
• algorithms must only contain valid values (gzip, deflate, br, zstd) in [server.compression].
• algorithms must not be empty when [server.compression] is enabled.
• username and password must not be empty when [server.basic_auth] is enabled.
• At least one [[locations]] block is required.
• Each location must have at least one [[locations.paths]] entry.
• prefix cannot contain null bytes or .. path traversal sequences.
• Duplicate prefixes (after normalization) are rejected.
• Prefix normalization: ensures the prefix starts with "/" and removes any trailing "/".

📄 Complete Example

A fully-annotated config.toml with all fields specified explicitly:

[server]
bind = "0.0.0.0:8080"            # Listen address and port
keepalive = true                  # Enable HTTP keep-alive
connection_timeout = 300          # Connection timeout in seconds (0 = unlimited)
max_header_size = "8KB"           # Minimum 8KB required by hyper
max_headers = 64                  # Max number of HTTP headers
max_body_size = "1MB"             # Max request body size
http2_max_streams = 128           # Max concurrent HTTP/2 streams
max_file_size = "10MB"            # Global max file size (0 = no limit)
stream_buffer_size = "64KB"       # Streaming response buffer size (must be > 0)

# CORS — allow specific origins with credentials
[server.cors]
enabled = true
allow_origins = ["https://example.com", "https://app.example.com"]
allow_methods = ["GET", "HEAD", "OPTIONS"]
allow_headers = ["*"]
expose_headers = ["Content-Length", "Content-Type"]
max_age = 86400
allow_credentials = true

# Per-IP rate limiting
[server.rate_limit]
enabled = true
requests_per_second = 10
burst_size = 30
cleanup_interval = 600

# Response compression — compress text-based responses
[server.compression]
enabled = true
algorithms = ["gzip", "br"]      # gzip for compatibility, Brotli for efficiency
min_size = "1KB"                  # skip compression for small files

# Basic Authentication — protect with username/password
[server.basic_auth]
enabled = true
username = "admin"
password = "s3cr3t"
realm = "filehunter"              # shown in browser login dialog

# Static image files — sequential search across two directories
[[locations]]
prefix = "/imgs"                  # Longest prefix match wins
mode = "sequential"               # Check paths in declared order
max_file_size = "50MB"            # Override: allow larger images

[[locations.paths]]
root = "/data/images/primary"     # First directory to search
extensions = ["jpg", "jpeg", "png", "webp"]

[[locations.paths]]
root = "/data/images/archive"     # Searched second if not found above
extensions = ["jpg", "jpeg", "png", "webp"]

# Video files — return the latest version across all paths
[[locations]]
prefix = "/videos"
mode = "latest_modified"          # Return most recently modified match
max_file_size = "0"               # No file size limit for videos

[[locations.paths]]
root = "/data/videos/current"
extensions = ["mp4", "mkv"]

[[locations.paths]]
root = "/data/videos/staging"
extensions = ["mp4", "mkv"]

# Catch-all — concurrent search, no extension filter
[[locations]]
prefix = "/"                      # Matches any path not matched above
mode = "concurrent"               # Search all paths in parallel

[[locations.paths]]
root = "/data/general"
# extensions omitted — all file types allowed