Skip to content
📌 OpenRun 1.0 is released, read the announcement
Reference

Reference

This page is an index of all the Starlark functions and constants available in OpenRun, with links to the documentation for each. Entries are grouped by where they can be used:

App Declaration (apps.star)

App declaration files (any name, apps.star or apps.ace by convention) declare the apps and service bindings to deploy. They are used with the openrun apply and openrun sync commands. The functions available are:

FunctionDescriptionDocumentation
appDeclares one app: install path, source url, params, config, bindingsApp Configuration
bindingDeclares one service binding: path, source, grants, configDeclarative Apply
configReads a value from the server [node_config] in openrun.toml, with a defaultConfig Access from Code
sidecarDeclares one sidecar container for an app, passed in app(sidecars=[...])Sidecar Containers
jobDeclares one job (command, image, trigger, params) for an app, passed in app(jobs=[...])Jobs and Deploy Hooks
cron, before_deploy, manualJob triggers, passed as the trigger of jobJobs and Deploy Hooks

Sidecars and jobs are also accepted as dict literals or JSON strings with the same fields. The config function supports the special keys _branch (the git branch the declaration file was loaded from) and _dev (whether the apply is running in dev mode).

App Definition (app.star)

The app.star file defines the app and its handler functions. The predefined builtins are available under the ace namespace. See Developing Apps for the app structure.

Functions

FunctionDescriptionDocumentation
ace.appCreates the app definition, assigned to the app globalApp Definition
ace.htmlDefines an HTML page route with fragmentsHTML Route
ace.fragmentDefines a partial page interaction within an HTML routeFragment
ace.apiDefines a JSON or plain text routeAPI Route
ace.proxyDefines a route which proxies to another URL or containerProxy Route
ace.redirectReturns a redirect response from a handlerRedirect Response
ace.responseReturns a custom response: template, status code, HTMX retarget/reswapCustom Response
ace.permissionDeclares a plugin call the app needs approval forApp Permissions
ace.styleConfigures the CSS library and themes for the appStyling
ace.libraryImports a JavaScript library as an ECMAScript moduleJavaScript Modules
ace.actionDefines an action with an auto-generated form UIAction Definition
ace.jobDefines a job: a command run in a container from the app image, or a Starlark run functionJobs and Deploy Hooks
ace.cron, ace.before_deploy, ace.manualJob triggers, passed as the trigger of ace.jobJobs and Deploy Hooks
ace.resultReturns the result from an action run handlerAction Result
ace.auditSets the audit event details from a handlerCustom Events
ace.outputWraps a value or error returned by a Starlark functionReturning Errors
ace.configReads a value from the server [node_config], with a defaultConfig Access from Code
ace.evalWraps a template string built in app code, resolved for secrets when passed to a pluginSecrets in Plugin Arguments

In app.star, ace.config supports the special key _app_url, which resolves to the url the app is served at.

Handler Functions

Handler functions are plain Starlark functions defined in app.star (or in files it loads). Two global function names are special, the OpenRun runtime looks them up by name:

FunctionDescriptionDocumentation
handler(req)The default request handler, used when a route defines no handlerStructure
error_handler(req, ret)Defining this enables automatic error handling for plugin callsAutomatic Error Handling

All other handlers are regular functions with no special name, referenced from the definition:

HandlerReferenced through
Route handlerThe handler property of ace.html/ace.api/ace.fragment
Action run handler, called as run(dry_run, args)The run property of ace.action
Action suggest handlerThe suggest property of ace.action
Starlark job function, the same run(dry_run, args) shapeThe run property of ace.job

Plugins

Plugins are loaded with load("<plugin>.in", "<plugin>") and called from handler functions. Plugin calls need permissions approved for the app. The builtin plugins are:

PluginDescriptionDocumentation
store.inDocument store APIs, using the types defined in schema.starStore Plugin
http.inHTTP client APIs: get, post, put, delete etc.HTTP Plugin
exec.inRuns external commands as processesExec Plugin
fs.inLocal file system accessFS Plugin
container.inConfigures the app container, sidecars and runs commandsContainer Plugin
proxy.inConfigures proxying for proxy routesProxy Plugin
  • System plugins: the privileged openrun.in (read-only server information, like list_apps), openrun_admin.in (management operations) and build.in (the AI app builder) are used by the management console; see System Plugin Access.
  • External plugins: additional plugins can be added as external plugins.
  • param namespace: app parameters are available in app.star as param.port and so on, as defined in params.star.
  • doc and table namespaces: when the app has a schema.star, doc has a constructor for each type (like doc.bookmark(url=...)) and table has the table name for each type (like table.bookmark), see Store Types.

Constants

The ace namespace also defines the following constants:

ConstantUsage
ace.GET, ace.POST, ace.PUT, ace.DELETEHTTP method for routes, like ace.html(method=ace.POST)
ace.JSON, ace.TEXTResponse type for ace.api and ace.response; ace.response also accepts the string "HTML"
ace.READ, ace.WRITECall type for ace.permission
ace.AUTO, ace.TABLE, ace.DOWNLOAD, ace.IMAGEReport types for action results
ace.CONTAINER_URLThe app container URL placeholder, same as container.URL

App Parameters (params.star)

The params.star file defines the parameters for an app, set during app creation with --param and shown as form fields for actions. The functions available are:

FunctionDescriptionDocumentation
paramDefines one parameter: name, type, default, description, display typeApp Parameters
configReads a value from the server [node_config], with a defaultConfig Access from Code

options_ is a special param name prefix: a LIST param named options_<name> holds the dropdown options for the param <name> in the action form UI, and is itself hidden from the form. See Param Value Selector.

The constants available in params.star are:

ConstantUsage
STRING, INT, BOOLEAN, LIST, DICTThe type property for a param, STRING is the default
FILE, PASSWORD, TEXTAREA, COMBOThe display_type property for string params, see Display Types

Spec App Actions (actions.star, action_params.star)

An app built from a spec has no app.star of its own. It can add actions with two optional files:

FileContents
actions.starSets the actions global to a list of ace.action entries (and optionally permissions to a list of ace.permission entries), using the same ace builtins and plugin loads as app.star
action_params.starDeclares the params shown on the action form with the same param function and constants as params.star. When it exists, only its params are shown for the actions, instead of the params.star params

Store Schema (schema.star)

The schema.star file defines the types for the store plugin, the document store backed by SQLite or PostgreSQL. The functions available are:

FunctionDescriptionDocumentation
typeDefines one document type: name, fields, indexesSchema Definition
fieldDefines one field: name, type, defaultSchema Definition
indexDefines an index on a list of fields, optionally uniqueSchema Definition

The constants available in schema.star are STRING, INT, BOOLEAN, LIST and DICT, used as the field types.