Type class for types that can be converted to URL paths.

This is used by IHP's routing system to generate URLs for controller actions.

Example:

>>> pathTo UsersAction
"/Users"

>>> pathTo ShowUserAction { userId = "a32913dd-ef80-4f3e-9a91-7879e17b2ece" }
"/ShowUser?userId=a32913dd-ef80-4f3e-9a91-7879e17b2ece"

Routes a given path to an action when requested via GET.

Example:

instance FrontController WebApplication where
    controllers = [
            get "/my-custom-page" NewSessionAction
        ]

The request GET /my-custom-page is now executing NewSessionAction

Also see post.

Routes a given path to an action when requested via POST.

Example:

instance FrontController WebApplication where
    controllers = [
            post "/do-something" DoSomethingAction
        ]

The request POST /do-something is now executing DoSomethingAction

Also see get.

Defines the start page for a router (when / is requested).

Create a route entry for a controller.

Automatically uses the HashMap fast path when AutoRoute is available (via the overlappable CanRoute instance), or falls back to Attoparsec for controllers with custom CanRoute instances.

No user code changes needed — parseRoute @PostsController picks the optimal strategy at compile time.

Returns the create action for a given controller. Example: `createAction @UsersController == Just CreateUserAction`

Returns the update action when given a controller and id. Example: `updateAction @UsersController == Just (id -> UpdateUserAction id)`

Returns the url to a given action.

Uses the baseUrl configured in Config/Config.hs. When no baseUrl is configured in development mode, it will automatically detect the correct baseUrl value.

>>> urlTo UsersAction
"http://localhost:8000/Users"

>>> urlTo ShowUserAction { userId = "a32913dd-ef80-4f3e-9a91-7879e17b2ece" }
"http://localhost:8000/ShowUser?userId=a32913dd-ef80-4f3e-9a91-7879e17b2ece"

Parses and returns an UUID

Parses an UUID, afterwards wraps it in an Id

Returns all the remaining text until the end of the input

Parses until the next /

Routes to a given WebSocket app if the path matches the WebSocket app name

Example:

instance FrontController WebApplication where
    controllers = [
            webSocketApp @AutoRefreshWSApp
        ]

The request /AutoRefreshWSApp will call the AutoRefreshWSApp

Routes to a given WebSocket app if the path matches

Example:

instance FrontController WebApplication where
    controllers = [
            webSocketAppWithCustomPath @AutoRefreshWSApp "my-ws-app"
        ]

The request /my-ws-app will call the AutoRefreshWSApp

Filter methods when writing a custom routing parser

Example:

instance CanRoute ApiController where
   parseRoute' = do
       string "/api/"
       let
           createRecordAction = do
               onlyAllowMethods [POST]

               table <- parseText
               endOfInput
               pure CreateRecordAction { table }

           updateRecordAction = do
               onlyAllowMethods [PATCH]

               table <- parseText
               string "/"
               id <- parseUUID
               pure UpdateRecordAction { table, id }

createRecordAction <|> updateRecordAction

Parses the HTTP Method from the request and returns it.

Parses and returns an integer parseRational :: (Integral a) => Parser a parseRational = Attoparsec.decimal

Parses a route query parameter

Example:

let showPost = do
    string "/post"
    let postId = routeParam "postId"
    pure ShowPostAction { .. }

Will parse the postId query in `/post?postId=09b545dd-9744-4ef8-87b8-8d227f4faa1e`

Binds ?request and ?respond from WAI arguments, then runs the given action.

This avoids repeating let ?request = waiRequest; let ?respond = waiRespond at each call site.

Given a constructor and a parsed query string, attempt to construct a value of the constructor's type. For example, given the controller

data MyController = MyAction { textArg :: Text, intArg :: Int }

this function will receive a representation of the MyAction constructor as well as some query string [("textArg", "some text"), ("intArg", "123")].

By iterating through the query and attempting to match the type of each constructor argument with some transformation of the query string, we attempt to call MyAction.

A controller route entry — either a pre-built HashMap for O(1) dispatch, or a custom Attoparsec parser for dynamic URL patterns.

ControllerRouteMap carries both an auto-route HashMap and a fallback parser for custom routes. ControllerRouteParser wraps standalone parsers like get, post, webSocketApp, startPage, etc.

frontControllerToWAIApp scans all ControllerRouteMap HashMaps directly (no Attoparsec) for O(1) dispatch, and only falls back to Attoparsec for custom/dynamic route parsers.

Scan ControllerRouteMap entries for a matching path. Returns as soon as a HashMap contains the path. Skips ControllerRouteParser entries.

Build a HashMap from full paths (prefix + action name) to Application closures. The Application closures take the application value explicitly and handle query string parsing, method validation, and controller execution. Computed once per (controller, application) type pair (NOINLINE CAF).