Static File Serving

Overview

Toron provides native static file serving capabilities, allowing developers to host single-page or multi-page web applications (HTML, CSS, JS, images, fonts) directly alongside REST API routes without external reverse proxies.

Features

• Automatic MIME Detection: Injects accurate Content-Type response headers (text/html, text/css, application/javascript, image/png, etc.).
• Directory Index Fallback: Automatically serves index.html when a directory URL is requested (e.g. http://localhost:8080/).
• Single Page Application (SPA) HTML5 History Fallback: Transparently resolves client-side virtual routes lacking file extensions to index.html (or a custom fallback document) with HTTP 200 OK, delivering full Nginx try_files parity (TASK-056).
• Asset Masking Protection: Missing static asset requests containing file extensions (.js, .css, .png, .json) return HTTP 404 Not Found rather than HTML, preventing runtime browser syntax errors.
• Path Traversal Security: Automatically blocks directory traversal attacks (../) and symlink directory escapes, returning 403 Forbidden via the Layered Route-Aware Path Traversal Defense Architecture.

Configuration Example

In routes.yaml:

routes:
  # Standard Static Route
  - type: "static"
    prefix: "/internal/dashboard"
    dir: "./public"

  # Single Page Application (SPA) Route
  - type: "static"
    prefix: "/app"
    dir: "./frontend/dist"
    spa: true
    fallback: "index.html"

(Alternatively, legacy static file hosting can also be configured under static: in config.yaml)

Programmatic Route Registration

r := router.New()
// Standard static handler
r.Static("/", "./public")

// SPA-enabled static handler with ProxyOptions
r.RoutePrefix(router.RouteTypeStatic, "/app", "./frontend/dist", proxy.ProxyOptions{
    SPA:      true,
    Fallback: "index.html",
})

Related Pages

• Layered Route-Aware Path Traversal Defense Architecture
• Configuration Guide
• Configuration Options Reference
• Troubleshooting