deployment-help.toml

## Common executor settings
## Applies to `[[activity_wasm]]`, `[[activity_js]]`, `[[workflow_wasm]]`, and `[[workflow_js]]`.
## Not applicable to webhook endpoints, stubs, or external activities.
# exec.batch_size = 5 # Number of executions to lock for every event loop tick.
# exec.lock_expiry.seconds = 1 # Each execution is locked for 1s by default.
# exec.tick_sleep.milliseconds = 200 # Sleep between event loop ticks.
### Locking strategy
## There are three strategies how components can select and lock executions to be worked on:
## - "by_ffqns": select pending executions by function FFQN, meaning a new component version will continue working on executions started by a previous version without replay/upgrade gating.
## - "by_component_digest": select pending executions by component hash digest. Since every component code change triggers a new digest, old pending executions must be explicitly upgraded to the current digest first.
## - "auto": workflows select pending executions by FFQN. When an execution's stored digest differs from the current component digest, the workflow is replayed against the current component, compatible executions are upgraded automatically, and executions already known to be incompatible with the current digest are skipped.
## The default strategy for activities (both JS and WASM) is "by_ffqns", for workflows it is "auto".
# exec.locking_strategy = "auto" # One of "by_ffqns"|"by_component_digest"|"auto"


### WASM Activity components configuration
# [[activity_wasm]]
# name = "name" # Required. Each component must be named.
## Location can be a file path or an OCI registry reference.
# location = "path/to/wasm"
# location = "oci://docker.io/repo/image:tag"
## Common executor settings - see above.
## Database storage setting for logs emitted by the component
# logs_store_min_level = "debug" # One of "off"|"trace"|"debug"|"info"|"warn"|"error"
## Specific settings for activity_wasm:
## Retry customization: All activities are retried on trap (panic), on error variants and timeouts until `max_retries` condition is met.
# max_retries = 5
# retry_exp_backoff.milliseconds = 100 # First retry is scheduled after 100ms after the failure, the next one after 200ms, then after 400ms...
# Activities are retried when a function returns the error variant,
# unless the error is a variant whose name contains `permanent`, e.g. `permanent-failure` or `my-permanent-error(string)`.
## Guest std stream forwarding to host: one of "none","stdout","stderr","db". Default is "db".
# forward_stdout="db" # Persist guest's stdout to the database.
# forward_stderr="db" # Persist guest's stderr to the database.
## Environment variables: Set to a specific value, use ${VAR} interpolation, or forward from the host. Default is empty.
## Bash-style defaults are supported: ${VAR:-default} uses default when VAR is unset or empty, ${VAR-default} when unset only.
## Defaults can themselves contain ${...} interpolations.
## Note: only `${VAR}` triggers interpolation; `$VAR` (no braces) is treated as a literal string.
## Forwarded vars ("ENV1") fail startup if missing; value strings with unresolved `${VAR}` also fail.
# env_vars = ["ENV1", {key = "ENV2", value = "somevalue"}, {key = "ENV3", value = "${HOST_VAR}"}, {key = "ENV4", value = "prefix ${HOST_VAR}"}, {key = "ENV5", value = "${OPTIONAL:-fallback}"}]

## Outgoing HTTP host allowlist.
## Each `[[activity_wasm.allowed_host]]` entry permits outbound requests to a host.
## If no entries are defined, all outbound HTTP connections are blocked.
## The server operator must also allow the request with a matching
## `[[outbound_http.allowed_host]]` entry in server.toml. Neither side can widen
## the other. On upgrade, copy the deployment entries into server.toml, then narrow
## the operator-owned copies as needed.
##
## `pattern` matches the request origin: scheme, host, and port. It uses the
## limited wildcard syntax below, not regular expressions, and must not contain
## a URL path. A pattern without a scheme uses HTTPS; one without a port uses
## the scheme's default port (80 for HTTP, 443 for HTTPS).
##
## Supported patterns:
## - "*" matches all HTTPS hosts on port 443
## - "*://*" matches http://host:80 and https://host:443 (any host, default ports)
## - "*://*:*" matches any scheme, any host, any port
## - "*.example.com" matches subdomains
## - "http://192.168.1.*" matches a /24 range
## - "http://localhost:*" matches localhost on any HTTP port
##
## Method restrictions:
## - `methods = "*"` allows all methods
## - `methods = ["GET", "POST"]` restricts to specific methods
## - `methods = []` allows nothing (config warning)
## - Omitting `methods` entirely allows nothing (config warning)
##
## Optional request URL regex restriction:
## - Checked after host and method matching.
## - The request is matched as `METHOD URL` with query params removed,
##   for example `GET https://api.example.com/v1/items`.
## - Supports `${VAR}` and `${VAR:-default}` env var interpolation.
## - Env var values are regex syntax; use regex-escaped values when precision matters.
## - Omit `request_url_regex` to allow all paths accepted by host and method restrictions.
##
## Multiple entries can match the same request; they form a union (secrets are merged).
## The `pattern` field supports `${VAR}` and `${VAR:-default}` env var interpolation.
# [[activity_wasm.allowed_host]]
# pattern = "api.github.com"
# methods = "*"
# request_url_regex = "^GET https://api\\.github\\.com/repos/"
## Optional secrets: injected via placeholder replacement in outgoing HTTP requests.
## `secrets` lists operator-owned secret names from the server.toml `[secrets]` table.
## Each logical secret name is exposed to WASM as an env var containing an opaque
## placeholder instead of the real value; the runtime replaces placeholders with
## real values only for requests to this host.
## A replacement occurs only when matching server.toml and deployment.toml entries
## both list the same secret and `replace_in` replacement target.
## `replace_in` controls where substitution happens:
## - "headers" searches textual header values and replaces every placeholder occurrence,
##   including placeholders embedded in a larger value such as `Bearer <placeholder>`.
## - "params" searches URL query parameter values and replaces every placeholder occurrence.
## - "body" replaces every placeholder occurrence only when the body is valid UTF-8 and
##   `Content-Type` is textual: `text/*`, JSON, or `application/x-www-form-urlencoded`.
## Default is empty (no replacement).
# secrets = ["OPENAI_API_KEY"]
# replace_in = ["headers"]

### JavaScript Activity components configuration
# [[activity_js]]
# name = "name"                              # Optional. Component name. Defaults to `{ifc_name}.{function_name}` from `ffqn`.
## Source specification: exactly one of `location` or `content`.
## `content`: JavaScript source embedded directly in the TOML.
# content = '''
# export default function hello(name) {
#   return `Hello, ${name}!`;
# }
# '''
## `location`: local path or OCI reference for the JavaScript source file.
## Supports local file paths and `oci://...` references.
# location = "path/to/source.js"
# location = "oci://docker.io/repo/image:tag"
# ffqn = "namespace:package/interface@version.function" # Required. Fully qualified function name.
## Custom parameters. If omitted, defaults to no parameters.
## Each entry has a `name` and a WIT `type` (e.g. `string`, `u32`, `list<string>`, `option<u64>`).
# params = [
#   { name = "name", type = "string" },
#   { name = "count", type = "u32" },
# ]
## WIT return type. Defaults to `result`.
## Must be `result`, `result<T>`, `result<T, string>`, or `result<T, variant { execution-failed, ... }>`.
## `T` can be `_` to indicate no ok value (e.g. `result<_, string>`).
## JS serialization convention: return/throw a JSON-compatible value matching T.
## For variant error types, e.g. `result<_, variant { not-found, with-data(string) }>`:
##   throw a plain string for no-payload cases (e.g. `throw "not_found"`)
##   and an object for payload cases (e.g. `throw { "with-data": "hello" }`).
# return_type = "result"
## Common executor settings - see above.
## Retry customization: same as activity_wasm.
# max_retries = 5
# retry_exp_backoff.milliseconds = 100
## Guest std stream forwarding to host: one of "none","stdout","stderr","db". Default is "db".
# forward_stdout="db"
# forward_stderr="db"
# logs_store_min_level = "debug"             # One of "off"|"trace"|"debug"|"info"|"warn"|"error"
## Outgoing HTTP host allowlist - same syntax as activity_wasm.allowed_host.
# [[activity_js.allowed_host]]
# pattern = "api.example.com"
# methods = ["GET", "POST"]
# request_url_regex = "^(GET|POST) https://api\\.example\\.com/v1/"
# secrets = ["API_KEY"]
# replace_in = ["headers"]

### Exec Activity components configuration — run native executables as activities
### Exec activities spawn a native child process (shell script, Node.js, Docker, etc.)
### instead of a WASM component. Parameters are passed as JSON-encoded CLI args,
### and the result is read from stdout (exit 0 → ok, non-zero → err).
# [[activity_exec]]
# name = "name"                              # Optional. Component name. Defaults to `{ifc_name}.{function_name}` from `ffqn`.
## Source specification: exactly one of `location` or `content`.
## `content`: script content embedded in the TOML. Written to a temp file at each execution.
# content = '''#!/usr/bin/env bash
# echo "\"hello\""
# '''
## `location`: local file path or OCI registry reference. Local files are read at deploy time and converted to `content`, making deployment self-contained.
# location = "scripts/my-script.sh"
## `location` may also be an OCI reference. Script is pulled from the exec layer and resolved at deploy time. Written by `obelisk component add`.
# location = "oci://docker.io/repo/image:tag@sha256:..."
## Optional content digest of the exec script. Useful for verifying OCI-backed or local script contents.
# content_digest = "sha256:..."
# ffqn = "namespace:package/interface.function" # Required. Fully qualified function name.
## Custom parameters. If omitted, defaults to no parameters.
## Each entry has a `name` and a WIT `type` (e.g. `string`, `u32`, `list<string>`).
# params = [
#   { name = "a", type = "u32" },
#   { name = "b", type = "u32" },
# ]
## WIT return type. Defaults to `result`.
## Must be `result`, `result<T>`, `result<T, string>`, or `result<T, variant { execution-failed, ... }>` (T can be unit type _).
# return_type = "result<u32, string>"
## Common executor settings - see above.
# exec.lock_expiry.seconds = 1 # Child process will be killed afterwards, execution will be retried or marked as permanently timed out.
## Retry customization: same as activity_wasm.
# max_retries = 5
# retry_exp_backoff.milliseconds = 100
## Guest std stream forwarding to host: one of "none","stdout","stderr","db". Default is "db".
# forward_stdout="db"
# forward_stderr="db"
# logs_store_min_level = "debug"             # One of "off"|"trace"|"debug"|"info"|"warn"|"error"
## Environment variables: same syntax as activity_wasm. Default is empty, not even `PATH` is exposed from the host.
## When explicitly set, only the listed vars are exposed (env is cleared first).
# env_vars = ["PATH", {key = "MY_VAR", value = "my_value"}] # Values support interpolation.
## Maximum bytes collected from stdout to form the response.
## Exceeding the limit fails the execution.
## Not used when return_type is result (default), since the response carries no data.
## Default: 4096.
# max_output_bytes = 4096
## Pass parameters via the stdin JSON `params` array instead of argv.
## Use for large payloads that would exceed the `execve` argument-size limit.
## The child receives `{"params":[...]}` on stdin (alongside `secrets`, if configured).
## Default: false.
# params_via_stdin = false
## Secrets: operator-owned secret names from the server.toml `[secrets]` table, piped to the child's stdin as JSON.
## The child receives `{"secrets":{"NAME":"value",...}}` on stdin. Use `jq .secrets.NAME /dev/stdin` or equivalent to parse.
# secrets = ["MY_SECRET"]

### External Activity components configuration - only WIT schema is loaded
### An external activity declares callable activity functions whose implementation
### is provided outside this deployment.
### Two modes are supported: file mode (WASM binary for the WIT schema) and inline mode (no WASM file needed).
##
## File mode: load WIT schema from an existing WASM binary.
# [[activity_external]]
# name = "name" # Required. Each component must be named.
# location = "path/to/external-activity.wasm"
# location = "oci://docker.io/repo/image:tag"
##
## Inline mode: define the function schema directly in TOML (no WASM file required).
# [[activity_external]]
# name = "my-external-activity"              # Optional. Defaults to `{ifc_name}.{function_name}` from `ffqn`.
# ffqn = "namespace:package/interface.function"
# params = [{ name = "id", type = "u64" }]
## WIT return type. Defaults to `result<string, string>`.
## Must be `result`, `result<T>`, `result<T, string>`, or
## `result<T, variant { execution-failed, ... }>`.
# return_type = "result<string, string>"
## Note: `location` and `ffqn` are mutually exclusive; exactly one must be present.

### Stub Activity components configuration
### A stub activity is a placeholder function that never executes on its own.
### Instead of running WASM, the return value is supplied externally — either by the
### calling workflow itself (via the stub host function) or by an outside actor via
### the "stub response" RPC (PUT /v1/executions/{id}/stub).
### Typical use cases:
###   - Human-in-the-loop: pause a workflow until a person approves or provides input.
###   - External system integration: wait for a third-party callback or webhook result.
###   - Inter-workflow coordination: let another workflow supply the return value.
###   - Testing/simulation: inject controlled responses without real implementations.
### Two modes are supported: file mode (WASM binary for the WIT schema) and inline mode (no WASM file needed).
##
## File mode: load WIT schema from an existing WASM binary.
# [[activity_stub]]
# name = "name" # Required. Each component must be named.
# location = "path/to/stub.wasm"
# location = "oci://docker.io/repo/image:tag"
##
## Inline mode: define the function schema directly in TOML (no WASM file required).
# [[activity_stub]]
# name = "my-stub"                           # Optional. Defaults to `{ifc_name}.{function_name}` from `ffqn`.
# ffqn = "namespace:package/interface.function"
# params = [{ name = "id", type = "u64" }]
## WIT return type. Defaults to `result<string, string>`.
## Must be `result`, `result<T>`, `result<T, string>`, or
## `result<T, variant { execution-failed, ... }>`.
# return_type = "result<string, string>"
## Note: `location` and `ffqn` are mutually exclusive; exactly one must be present.

### Workflow components configuration
# [[workflow_wasm]]
# name = "name" # Required. Each component must be named.
# location = "path/to/wasm"
# location = "oci://docker.io/repo/image:tag"
## Common executor settings - see above.
# logs_store_min_level = "debug" # One of "off"|"trace"|"debug"|"info"|"warn"|"error"

## Retry customization: All workflows are retried on timeouts forever. Therefore, `retry_exp_backoff` must not be zero.
# retry_exp_backoff.milliseconds = 100 # First retry is scheduled after 100ms after the failure, the next one after 200ms, then after 400ms...

## Automatic lock extension, enabled by default
# lock_extension = true

## Blocking strategy: When workflow requests a child execution result, it can either be interrupted, or kept in the memory until its execution lock expires or the response arrives.
## When "interrupt" is selected, after every child execution result the whole event history must be replayed.
# blocking_strategy = "await" # Default blocking strategy is "await"
# blocking_strategy = { kind = "await", non_blocking_event_batching = 100 } # Number of non-blocking events that can be cached and written in a batch.

## Map from frame symbol file names to corresponding file paths on local filesystem. Supports path prefixes on both sides.
## If frame symbol path starts with `...`, only the suffix will be used to find the matching source file.
## During manifest preparation, relative paths are rewritten to `{ path = "...", content_digest = "sha256:..." }`.
# backtrace.sources = {"frame symbol file path" = "path to the source file", ".../src/lib.rs" = "path to source file"}

# Stub WASI CLI world imports. Only needed for workflows authored in TinyGo.
# stub_wasi = false # Default is false.


### JavaScript Workflow components configuration
# [[workflow_js]]
# name = "name"                              # Optional. Component name. Defaults to `{ifc_name}.{function_name}` from `ffqn`.
## Source specification: exactly one of `location` or `content`.
## `content`: JavaScript source embedded directly in the TOML.
# content = '''
# export default function run() {
#   return "ok";
# }
# '''
## `location`: local path or OCI reference for the JavaScript source file.
## Supports local file paths and `oci://...` references.
# location = "path/to/workflow.js"
# location = "oci://docker.io/repo/image:tag"
# ffqn = "namespace:package/interface@version.function" # Required. Fully qualified function name.
## Custom parameters. If omitted, defaults to no parameters.
## Each entry has a `name` and a WIT `type` (e.g. `string`, `u32`, `list<string>`, `option<u64>`).
# params = [
#   { name = "name", type = "string" },
#   { name = "count", type = "u32" },
# ]
## WIT return type. Defaults to `result`.
## Must be `result`, `result<T>`, `result<T, string>`, or `result<T, variant { execution-failed, ... }>`.
## `T` can be `_` to indicate no ok value (e.g. `result<_, string>`).
## JS serialization convention: return/throw a JSON-compatible value matching T.
## For variant error types, e.g. `result<_, variant { not-found, with-data(string) }>`:
##   throw a plain string for no-payload cases (e.g. `throw "not_found"`)
##   and an object for payload cases (e.g. `throw { "with-data": "hello" }`).
# return_type = "result"
## Common executor settings - see above.
## Retry customization: same as workflow_wasm.
# retry_exp_backoff.milliseconds = 100
# lock_extension = true
# blocking_strategy = "await"
# logs_store_min_level = "debug"             # One of "off"|"trace"|"debug"|"info"|"warn"|"error"

### Webhook Endpoint section
## The built-in "external" HTTP server (127.0.0.1:9090) is available by default.
## Additional named HTTP servers are defined in server.toml via `[[http_server]]`.
# [[webhook_endpoint_wasm]]
# name = "name" # Required. Each component must be named.
# location = "path/to/wasm"
# location = "oci://docker.io/repo/image:tag"
# http_server = "external" # link to a `http_server`'s name (built-in default, or one defined in server.toml)
### Routes section
## An array of routes that will be matched against incoming requests.
## Only the path portion of a URL is taken into consideration, the query part
## ("?param_name=value") is ignored by the matcher.
## Syntax of a route:
## "/"                                          # Only the root URL path is matched.
## "/path"                                      # All methods are matched, URL path must be exactly '/path'.
## "/path/*"                                    # All methods are matched, URL path must start with '/path/'.
## { methods = ["GET"], route = "/some/path" }  # Method must be GET and path '/some/path'.
## "/status/:param1/:param2"                    # When URL matches, `param1` and `param2` values will be exposed as env vars.
## ""                                           # Matches every possible URL, same as `/*`
## For details about the matching engine please see https://docs.rs/route-recognizer/latest/route_recognizer/
# routes = [{ methods = [ "GET" ], route = "/some"}, "/other"]
## Guest std stream forwarding to host: one of "none","stdout","stderr","db". Default is "none".
# forward_stdout="stderr" # forwards stdout to host's stderr
# forward_stderr="stderr" # forwards stderr to host's stderr
# logs_store_min_level = "debug" # One of "off"|"trace"|"debug"|"info"|"warn"|"error"
## Environment variables: Set to a specific value, use ${VAR} interpolation, or forward from the host. Default is empty.
## Bash-style defaults are supported: ${VAR:-default} uses default when VAR is unset or empty, ${VAR-default} when unset only.
## Defaults can themselves contain ${...} interpolations.
## Note: only `${VAR}` triggers interpolation; `$VAR` (no braces) is treated as a literal string.
## Forwarded vars ("ENV1") fail startup if missing; value strings with unresolved `${VAR}` also fail.
# env_vars = ["ENV1", {key = "ENV2", value = "somevalue"}, {key = "ENV3", value = "${HOST_VAR}"}, {key = "ENV4", value = "prefix ${HOST_VAR}"}, {key = "ENV5", value = "${OPTIONAL:-fallback}"}]
## During manifest preparation, relative paths are rewritten to `{ path = "...", content_digest = "sha256:..." }`.
# backtrace.sources = {"frame symbol file path" = "path to the source file", ".../src/lib.rs" = "path to source file"}
## Capture and persist call-site backtraces for this webhook. Default is false.
# backtrace_persist = false
## Outgoing HTTP host allowlist - same syntax as activity_wasm.allowed_host.
# [[webhook_endpoint_wasm.allowed_host]]
# pattern = "api.example.com"
# methods = ["GET", "POST"]
# request_url_regex = "^(GET|POST) https://api\\.example\\.com/v1/"
# secrets = ["API_KEY"]
# replace_in = ["headers"]

### JavaScript Webhook Endpoint components configuration
# [[webhook_endpoint_js]]
# name = "name"                              # Required. Component name.
## Source specification: exactly one of `location` or `content`.
## `content`: JavaScript source embedded directly in the TOML.
# content = '''
# export default function handle() {
#   return new Response("ok");
# }
# '''
## `location`: local path or OCI reference for the JavaScript source file.
## Supports local file paths and `oci://...` references.
# location = "path/to/webhook.js"
# location = "oci://docker.io/repo/image:tag"
# http_server = "external"                   # link to a `http_server`'s name (built-in default, or one defined in server.toml)
# routes = [{ methods = [ "GET" ], route = "/some"}, "/other"]  # Required. See Routes section above.
## Guest std stream forwarding to host: one of "none","stdout","stderr","db". Default is "none".
# forward_stdout="stderr"
# forward_stderr="stderr"
# logs_store_min_level = "debug"             # One of "off"|"trace"|"debug"|"info"|"warn"|"error"
## Environment variables: Set to a specific value, use ${VAR} interpolation, or forward from the host. Default is empty.
## Bash-style defaults are supported: ${VAR:-default} uses default when VAR is unset or empty, ${VAR-default} when unset only.
## Defaults can themselves contain ${...} interpolations.
## Note: only `${VAR}` triggers interpolation; `$VAR` (no braces) is treated as a literal string.
## Forwarded vars ("ENV1") fail startup if missing; value strings with unresolved `${VAR}` also fail.
# env_vars = ["ENV1", {key = "ENV2", value = "somevalue"}, {key = "ENV3", value = "${HOST_VAR}"}, {key = "ENV4", value = "prefix ${HOST_VAR}"}, {key = "ENV5", value = "${OPTIONAL:-fallback}"}]
## Capture and persist JavaScript call-site backtraces for this webhook. Default is false.
# backtrace_persist = false
## Outgoing HTTP host allowlist - same syntax as activity_wasm.allowed_host.
# [[webhook_endpoint_js.allowed_host]]
# pattern = "api.example.com"
# methods = ["GET", "POST"]
# request_url_regex = "^(GET|POST) https://api\\.example\\.com/v1/"
# secrets = ["API_KEY"]
# replace_in = ["headers"]

### Cron components configuration
### Schedules trigger a target function on a cron-like schedule.
## On redeployment: if the schedule config is unchanged, the existing pending execution continues uninterrupted.
# [[cron]]
# name = "my-daily-job"                                       # Required. Each schedule must be named.
# ffqn = "myapp:tasks/jobs@1.0.0.daily-cleanup"               # Required. Fully qualified function name of the target to invoke on each tick.
# params = '["arg1", 42]'                                     # Optional. JSON-encoded parameters (default: "[]").
# schedule = "@daily"                                         # Required. Cron expression, or one of "@once", "@daily", "@hourly", "@weekly", "@monthly", "@yearly".

## Appendix: Path resolution
## Every local file path in this file (component `location`, `backtrace.sources` values) is resolved the same way:
##   - A relative path (e.g. "components/a.wasm", "scripts/x.js") is relative to the directory
##     containing this deployment.toml. It must stay within that directory ("../" escapes are rejected).
##   - An absolute path (e.g. "/opt/wasm/a.wasm") is rejected.
## For JS/exec components, deployment-relative sources are read and inlined at deploy time so the deployment is
## self-contained. `obelisk deployment get` recreates the deployment-relative files (mirroring subfolders) but
## cannot recreate WASM bytes.
##
## For backwards compatibility a relative path may be prefixed with `${DEPLOYMENT_DIR}/`; this is
## equivalent to a bare relative path (the directory containing this deployment.toml) and is no longer needed.