Skip to content

Lua API

Generated from src/lua by make gen-docs-lua. Do not edit this file by hand.

Lua scripts run in a sandbox with a fixed set of globals. Lifecycle hooks, named actions, and domain hooks get the full surface: document, notification, util, date, and math.clamp. Computed fields get util and date plus a read-only document table. They get no notification and no query-backed util gates. Scripts also receive the ctx object and an error(msg) collector; see lifecycle scripts and guards.

Reads accept a qualified domain.Doctype first argument. A foreign read needs an active domain grant; the returned content is reduced to the covered fields.

Function Signature Purpose
document.create doc_type, content_json Creates a new document of the given doctype in the same domain.
document.get doc_type, doc_id Fetches a document by doctype and ID.
document.update doc_type, doc_id, content_json Partially updates a document.
document.delete doc_type, doc_id Soft-deletes a document.
document.list doc_type, [filters], [sort], [page], [per_page] Lists documents of the given doctype.
Function Signature Purpose
notification.send account_id, doc_ref, kind, title, [options] Produces one notification for an account.
Function Signature Purpose
util.clamp x, min, max Clamp a number between min and max.
util.coalesce ... Returns the first non-nil, non-empty value, or nil if none.
util.facet_hosts () The host set Facet itself answers at — what the app.App host field must never claim.
util.insecure_urls_allowed () allow_insecure_urls — when false (default), the dispatcher rejects non-https target URLs.
util.is_empty v Returns true for nil, empty string, empty array, empty hash.
util.json_decode json_str Parses a JSON string and returns a Lua table/array/value. Not available in transient contexts.
util.json_encode value Serialises any Lua value (table, string, number, boolean, nil) to a JSON string. Not available in transient contexts.
util.oidc_name_tombstoned s True when a tombstoned iam.OIDCProvider still holds name. Lifecycle contexts only.
util.role_has_channel role_id, channel True when the named role’s connectivity array carries the channel. Lifecycle contexts only.
util.safe_webhook_url s The host half of the webhook target rule: true when the URL’s host resolves and every resolved address is public or on webhook.allowed_hosts; a host that does not resolve answers false.
util.sha256 s SHA-256 hex digest.
util.ulid () Generates a ULID (26-char, Crockford Base32, time-sortable).
util.valid_hostname s True for a bare lowercase hostname — no scheme, port, path, or wildcard — at most 253 characters; the app.App host shape rule.
util.valid_https_url s Shape rule for the iam.OIDCProvider issuer field: an absolute https URL with a host.
util.valid_issuer_url s Shape rule for the iam.OIDCProvider issuer field (B-329): an absolute https URL, or plain http on a loopback host — the same scheme-follows-host carve-out as the redirect-URI rule (B-154).
util.valid_redirect_uri s Shape rule for one entry of the app.App redirect_uris field — the shared Util::RedirectUri rule (the single source of truth; OAuth::RedirectUri and the register endpoint use it too): absolute https on any host, or absolute http on a loopback host (localhost, any *.localhost subdomain, 127.0.0.1, ::1); no fragment, no userinfo, no query, host required.
util.webhook_event_names () The closed event-name vocabulary for the core.Webhook events field.
Function Signature Purpose
date.diff a, b, unit Returns the difference between two ISO 8601 dates in the given unit.
date.now () Returns the current UTC time as ISO 8601.
Function Signature Purpose
math.clamp x, min, max Clamp a number between min and max.