Virtual Hosting

The virtual host handler is the router that sits in front of all site-specific handlers. It matches incoming requests to the appropriate handler based on the Host header.

Matching Logic

Request →  Extract Host header
                |
        Domain + Port (host:port)
                |
        Split on ":" → take domain part
                |
        Lookup domain in site handlers map
                |
        ├── Found → Route to site-specific handler
        │
        └── Not found → Route to default (catch-all) handler

Domain Extraction

The handler takes the Host header value, lowercases it, and strips the port number:

• "Example.COM:8080" → "example.com"
• "my.site.com" → "my.site.com"

Catch-all Domain

A site with domain: "" (empty string) serves as the default handler for any unrecognized domain. If no catch-all is defined, unknown domains receive an HTTP 404 Not Found.

Site Types

Each site type creates the appropriate handler automatically:

Handler creation happens once at startup.

Example: Complete Multi-Site Setup

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

  - domain: "api.example.com"
    proxy: "http://localhost:4000"

  - domain: "blog.example.com"
    dir: "site/blog"

  - domain: "docs.example.com"
    dir: "site/docs"

  - domain: ""
    dir: "site/fallback"