Request

Request Structure

The handler function is passed one argument which has the details about the API call. After the handler returns, the same request structure is passed to the template as the template context, with Data set to the handler response. The fields in this structure are:

Property	Type	Notes
AppName	string	The app name in the config
AppPath	string	The path where the app is installed. If root, then empty string
AppUrl	string	The url for the app root
PagePath	string	The path for the current page. If root, then empty string
PageUrl	string	The url for the current page
Method	string	The HTTP method, GET/POST etc
IsDev	bool	Is the app installed in dev mode
IsPartial	bool	Is this an HTMX driven partial request
PushEvents	bool	Whether push events are enabled for this app
HtmxVersion	string	The HTMX version configured for the app
Headers	dict	The incoming HTTP headers
RemoteIP	string	The resolved client IP address, honoring forwarded headers only from configured trusted proxies
UrlParams	dict	The url parameters, if used in the url spec
Form	dict	The form data, including body and query
Query	dict	The url query data, as a string array
PostForm	dict	The form data from the body
UserId	string	The current user id for the request
UserSubject	string	The provider user id claim, when available
UserEmail	string	The provider email claim, when available
CustomPerms	string[]	The custom permissions available to the user
AppRBACEnabled	bool	Whether app RBAC is enabled for the request
Data	dict	The response from the handler function (passed to the template)

Accessing Inputs

Url Parameters

For a route defined like

app.star

ace.html("/user/{user_id}/settings", "index.go.html")

the url parameter user_id can be accessed in the handler

app.star

def handler(req)
    user_id = req.UrlParams["user_id"]

Wildcard parameters are allowed at the end of the route. These are defined as

app.star

ace.html("/path/*", "index.go.html")

and can be accessed as

app.star

def handler(req)
    user_id = req.UrlParams["*"]

Regexes are also allowed in the path, these are defined as ace.html("/articles/{aid:^[0-9]{5,6}}") and accessed as req.UrlParams["{aid}"]. The route will match only if the regex matches.

Query String Parameters

Query string parameters can be accessed as

app.star

def handler(req)
    name = req.Query.get("name")
    name = name[0] if name else None

The value for Query is an string array, since there can be multiple query parameters with the same name.

Form Data

Form data can be accessed like

app.star

def handler(req)
    name = req.Form.get("name")
    name = name[0] if name else None

The value for Form is an string array, since there can be multiple form parameters with the same name.

Client IP Resolution

req.RemoteIP is the OpenRun-resolved client IP for the request.

By default, this is the IP address of the direct peer connection.
If the direct peer is listed in security.trusted_proxies, OpenRun will honor X-Forwarded-For and X-Real-IP.
For multi-hop X-Forwarded-For values, OpenRun walks the chain from right to left and returns the first IP that is not itself a trusted proxy.

This means apps should prefer req.RemoteIP over reading X-Forwarded-For or X-Real-IP directly from req.Headers.

Routing Response