dream/controllers/static

Secure static file serving

Serve files from disk with built-in security. Handles CSS, JavaScript, images, and any other static assets your application needs.

Quick Setup

import dream/controllers/static
import dream/http/transaction.{get_string_param}

pub fn serve_assets(request, ctx, svc) {
  case get_string_param(request, "path") {
    Ok(path) -> static.serve(
      request: request,
      context: ctx,
      services: svc,
      root: "./public",
      filepath: path,
      config: static.default_config(),
    )
    Error(msg) -> json_response(status.bad_request, error_json(msg))
  }
}

// In your router:
router.route(Get, "/assets/**path", serve_assets, [])

Security

Built-in protection against:

• Path traversal attacks (../../../etc/passwd)
• Absolute path access (/etc/passwd)
• Directory escaping

Files outside the root directory return 404, never errors that reveal filesystem structure.

Features

• MIME type detection - Automatic content-type headers
• Index serving - Serves index.html for directory requests
• Directory listing - Optional file browser (disabled by default)
• Custom 404s - Use your own not-found handler Control how directories and missing files are handled.
• Serves index.html for directories
• No directory listing
• Standard 404 response for missing files Shows a file browser when a directory has no index.html. Use this for development or when you want users to browse files. Don’t enable in production unless you specifically want directory browsing.

pub type Config(context, services) {
  Config(
    serve_index: Bool,
    allow_directory_listing: Bool,
    not_found_handler: option.Option(
      fn(request.Request, context, services) -> response.Response,
    ),
  )
}

pub fn default_config() -> Config(context, services)

pub fn serve(
  request request: request.Request,
  context context: context,
  services services: services,
  root root: String,
  filepath filepath: String,
  config config: Config(context, services),
) -> response.Response

pub fn serve_public(request: Request, ctx, svc) -> Response {
  case get_string_param(request, "filepath") {
    Ok(filepath) -> static.serve(
      request: request,
      context: ctx,
      services: svc,
      root: "./public",
      filepath: filepath,
      config: static.default_config(),
    )
    Error(msg) -> json_response(status.bad_request, error_json(msg))
  }
}

pub fn with_custom_404(
  config: Config(context, services),
  handler: fn(request.Request, context, services) -> response.Response,
) -> Config(context, services)

pub fn with_directory_listing(
  config: Config(context, services),
) -> Config(context, services)

pub fn without_index(
  config: Config(context, services),
) -> Config(context, services)