Static Files — Aquilia Documentation
Comprehensive guide and documentation for Static Files in the Aquilia framework. View API reference, examples, and implementation patterns.
MIDDLEWARE / STATIC FILES Static Files Middleware The StaticMiddleware provides production-grade static asset serving directly at the ASGI level. It employs a custom radix trie prefix matcher for ultra-fast lookups, verifies canonical paths to prevent traversal exploits, and offloads file serving with conditional HTTP caching. Radix Trie Routing Unlike naive string-matching algorithms, StaticMiddleware constructs a compressed radix trie mapping URL prefixes to folder destinations. This ensures route matching operates in O(k) time complexity, where k is the length of the requested path. It easily supports multiple mount points: from aquilia.middleware_ext import StaticMiddleware # Configure multiple directories server.middleware( StaticMiddleware( directories= , cache_max_age=31536000, # 1 year immutable=True ) ) Security Hardening To block malicious directory traversal requests (e.g. /static/../../etc/passwd), the middleware performs canonicalization: It resolves target paths using Python's os.path.realpath and compares them against the canonicalized base directory. If a path escapes the base directory, the middleware immediately raises a SecurityFault and blocks execution. Asset Optimization Pre-compressed Assets (.br, .gz) If a client sends an Accept-Encoding header containing brotli or gzip, the middleware checks if a pre-compiled .br or .gz version of the file exists on disk. If found, it serves the compressed file directly, avoiding dynamic CPU overhead. HTTP Range Requests Supports partial content requests (HTTP 206), enabling clients to stream video and audio files or resume interrupted file downloads efficiently. In-memory Cache Equipped with an LRU (Least Recently Used) cache for small, hot static files. Commonly accessed scripts or icons are served directly from RAM without disk I/O. Constructor Options Parameter Type Default Description directories dict[str, str] None Mapping of URL prefix to folders cache_max_age int 86400 Cache-Control max-age in seconds immutable bool False Adds Cache-Control: immutable directive brotli / gzip bool True Enable pre-compressed file checks index_file str | None "index.html" Default file returned for folder paths html5_history bool False Fall back to index_file on 404s (for SPA routing) Built-in Middleware CORS )
Go to Homepage