Capy-Bearer Documentation

TASK:NAME is a handler that runs outside a request, in a process of its own, once. task_execute() starts it with a timeout, and shell_exec() with on_done calls it when a command has finished. A task handler is always named, and one unit can hold several.

The handler receives its input as props, a serialized copy of the caller's input. It binds request implicitly as a synthetic request with no session, body, or form. It does not see the caller's request, connections, or unit variables; the task's own unit variables are initialized when its workspace comes up and are gone when the process ends.

Both props and request are available even when their declarations are omitted. Their names and any types are fixed. If both are declared, props comes first. function TASK:STORE(request : any) still has an implicit props binding.

A task and its caller

function TASK:STORE(props : any)
{
	var key := string(props.key)
	kv_set(key, props.value, 86400)
}

function RENDER()
{
	var started := task_execute("/jobs/store.capy:STORE", 30, key: "report-42", value: request.form)
	print(string(started.error, fallback: "started"), "\n")
}

task_execute() returns as soon as the process is started, with {ok: true, value: {pid}}, or {ok: false, error} when it could not start. Nothing reports the handler's result back; the task writes what it produces to storage the application owns. Its printed output is not returned to the caller. The runner logs failures. Use log() for operator records and application storage for results.

Timeout

The timeout is mandatory and measured in seconds. It includes unit compilation and handler execution. Bearer accepts rounded millisecond budgets from 1 through 86400000. The runner exits after the handler returns, or ends it when the deadline expires. Bearer does not retry failed tasks.

Use a service for persistent state, ports, or repeated events. A task can publish a result to storage without becoming a service.

After a command

With on_done, shell_exec() runs the command in a detached runner and calls the named task when it has finished. The props are the command result: command, exit_code, stdout, stderr, timed_out, and output_truncated.

function TASK:FINISHED(props : any)
{
	if s64(props.exit_code) != 0
	{
		file_append("/var/log/site/report.log", string(props.stderr))
	}
}

function RENDER()
{
	shell_exec("printf 'report ready\\n'", timeout_ms: 60000, on_done: "/jobs/report.capy:FINISHED")
}

Target paths

Save the first complete example as /jobs/store.capy under the site root. Its RENDER handler starts TASK:STORE. Direct HTTP or CLI routing does not invoke a TASK handler. Use a request handler or CLI handler that calls task_execute().

A target is a unit path followed by :NAME. Use :STORE, not :TASK:STORE. Relative paths try the request's entry directory, then the site root. A nested component's directory does not become the base. Use a leading / for an unambiguous site-root path.

var key := string(props.key)
if key == ""
{
	trap()
}
kv_set(key, props.value, 86400)

if bool(props.timed_out)
{
	print("report timed out after ", props.command, "\n")
}