Static File Hosting

The FileHandler serves static files from a configured root directory. This is the most common use case for hosting websites.

Configuration

A static site is defined in config.yml with the dir: key:

sites:
  - domain: "example.com"
    dir: "site/main-site"

The folder path is relative to plugins/ZyveraWeb/. The above example serves files from plugins/ZyveraWeb/site/main-site/.

File Resolution

When a request arrives, the handler resolves files in this order:

1. Directory → index.html — If the path maps to a directory, index.html inside that directory is served.

2. Extension-less → .html — If no file is found and the path has no extension, .html is appended. For example, /about becomes /about.html.

3. Exact match — If the file exists as-is, it is served directly.

Path Traversal Protection

The handler prevents directory traversal attacks by:

1. Resolving the requested path relative to the web root.
2. Normalizing the result (removing .. and . segments).
3. Verifying the resolved path still starts with the web root.

If a traversal attempt is detected, the server returns HTTP 403 Forbidden.

MIME Types

The handler maps file extensions to Content-Type headers:

Example

plugins/ZyveraWeb/site/main-site/:

index.html
about.html
css/style.css
js/app.js
images/logo.png