Routing

The request routing layer in Clace is built on top of the chi routing library. API requests (JSON or text), HTML requests and proxied requests are supported. For HTML requests, the routing is built for hypermedia exchange, so all routes are defined in terms of pages and fragments within the pages. This grouping of requests helps make it clear which API does what and provide an easy mechanism to deal with partial HTMX driven requests and full page refreshes. Simpler application might have one page with some interactions within that. Larger applications can be composed of multiple pages, each page having some interactive fragments.

Routes

The app contains an routes array, which defines all the routes for the app. For example, the app definition

app = ace.app("hello1",
              routes = [
                 ace.html("/"),
                 ace.html("/help", "help.go.html")
              ]
             )

defines two routes. / routes to the default index page, /help routes to the help page. Routes can be of three types: HTML, API and Proxy.

HTML Route

An HTML route defined using ace.html defines the properties for a HTML page. The response is HTML text. The data returned by the handler function is passed to the template. If the handler returns a ace.response or ace.redirect, then that takes effect, otherwise the template is rendered.

An HTML route can have fragments defined within it. These are sub-apis which used for hypermedia driven interactions from the main page.

The parameters for ace.html are:

Fragment

The fragments array in the html page definition defines the API interactions within the page. The parameters for ace.Fragment are:

For example, in this page definition

ace.html("/game/{game_id}", full="game.go.html", partial="game_info_tmpl", handler=game_handler,
    fragments=[
        ace.fragment(
            "submit", method=ace.POST, handler=lambda req: post_game_update(req, "submit")),
        ace.fragment(
            "refresh", partial="refresh_tmpl")
    ]
)

there are three API’s defined:

• GET /game/{game_id} : game_handler is the handler function, full page request returns game.go.html, partial HTMX request returns game_info_tmpl template.
• POST /game/{game_id}/submit : The handler is a lambda function. The game_info_tmpl template partial is inherited from the page as the response for the POST.
• GET /game/{game_id}/refresh : game_handler is inherited from the page. For full page, it returns the game.go.html response. For partial HTMX requests, refresh_tmpl template is returned.

API Route

An API route defines a route which returns JSON (default) or plain text response. The handler response is converted to the desired format and returned. The parameters for ace.api are:

For example

def handler(req):
    return {"a": 1}

app = ace.app("api",
              routes = [
                 ace.api("/myapi")
              ]
             )

A GET request to /myapi endpoint will return JSON {"a": 1}.

Proxy Route

A Proxy route defines a route which has to be proxied to another service. All API calls under that route are proxied (all methods and all sub-routes). Websocket connections are also proxied. Proxy uses a plugin based config, the app has to be authorized to do the proxying. The parameters for ace.Proxy are:

The proxy configuration proxy.config has the options:

For example, an app which forwards requests to www.google.com is

load("proxy.in", "proxy")

app = ace.app("Proxy",
              routes=[
                ace.proxy("/", proxy.config("https://www.google.com")),
              ],
              permissions=[
                  ace.permission("proxy.in", "config", ["https://www.google.com"]),
              ],
      )

The plugin is authorized to allow proxying to https://www.google.com. Any request to the app will be forwarded after stripping the app path. So if app is installed at /test, a request to /test/abc/def will be forwarded to /abc/def. In addition, if the proxy is configured with strip_path="/abc", then the request will be sent to /def.

If proxying is enabled for / route, then /static file serving is disabled for the app since requests to static path are also forwarded to the upstream service. /static_root serving is available and overrides the proxy config.

See proxy plugin for details about the proxy config.

Request Flow

The API flow is

• The API is first sent to the matching app
• Within the app, the API is routed based on the routes defined
• If there is a handler defined for the matched route, the handler function is called with the request as argument
• The response template is invoked, with an input map containing a Data property as returned by the handler function
• If the API type is set to json, the handler response is directly returned, with no template being used
• If automatic error handling is enabled (error_handler is defined), then the error handler function is called if there is a error during the handler invocation. The error handler does the response processing, the templates defined in the route are not used.

Notes

• For HTMX requests, the partial template is used. For regular requests, the page level full template is used
• If there is a function called handler defined, that is the default handler function for all API’s
• For non-HTMX update requests (POST/PUT/DELETE), the Post-Redirect-Get pattern is automatically implemented by redirecting to the location pointed to by the Referer header.