Configuration: routing and URL processing

This page documents directives that affect HTTP request matching and configuration layering inside host blocks. The http-server module’s radix tree resolver processes these directives.

Directives⁠#

Path matching⁠#

• location <path: string>
  • This directive specifies a path prefix for request matching. /api matches /api and /api/.... Longer matches are more specific. If this block matches, Ferron automatically rewrites the URL to remove the base URL. Default: not configured

Configuration example:

example.com {
    location /api {
        # Configuration for /api paths
    }
}

Inheritance⁠#

A location block inherits directives from the enclosing host block and from global defaults. When the same directive appears at both levels, the value in the location block wins for requests in that block. The same rule applies to if and if_not blocks nested in a host or location block.

Conditional matching⁠#

• if <matcher-name: string>
  • This directive specifies a named matcher to evaluate. When the named matcher evaluates to true, Ferron applies the nested block’s directives. Default: not configured
• if_not <matcher-name: string>
  • This directive specifies a named matcher to evaluate. When the named matcher evaluates to false, Ferron applies the nested block’s directives. Default: not configured

Configuration example:

example.com {
    if api_request {
        # Applied when api_request matcher passes
    }

    if_not api_request {
        # Applied when api_request matcher fails
    }
}

Error handling⁠#

• handle_error [status: integer]
  • This directive associates a nested block with a specific error code, or with a default error case when you give no code. Default: not configured

Configuration example:

example.com {
    handle_error 404 {
        # Custom handling for 404 errors
    }
}

URL redirects⁠#

• trailing_slash_redirect [bool: boolean]
  • This directive specifies whether automatic 301 redirects from directory paths without a trailing slash to the same path with a trailing slash are enabled. When omitted, defaults to true. Default: trailing_slash_redirect true

Configuration example:

example.com {
    root /srv/www/example
    trailing_slash_redirect
}