Runtime Suppport

Obelisk provides built-in runtime support functions that can be accessed by workflows and activities.

These functions offer essential capabilities like logging, random number generation, creating join sets, and, others. Activities and webhook endpoints have access to logging support functions, but not to the other workflow-specific functions.

The runtime support functions are defined using WIT (WebAssembly Interface Type) files.

Available Support Types

Used by other Obelisk WIT interfaces as well as the generated extension, contains time and execution interfaces with types like execution-id and others.

obelisk:types/types@4.2.0

Available Support Functions

Here's a breakdown of the available functions, grouped by their WIT interface:

obelisk:log/log@1.0.0

Available to:

• activities
• workflows
• webhook endpoints

This interface provides standard logging functions. All messages are strings.

Example (Rust):

use obelisk::log::log;

log::info("This is an informational message.");
log::error("This is an error message!");

obelisk:workflow/workflow-support@5.1.0

Available to:

• workflows

Some of these functions act like host-based activities - they avoid the need to spawn a WASM activity to obtain e.g. a random number. Other functions are related to persistent sleep and join set construction.

• random-u64(min: u64, max-exclusive: u64) -> u64: Generates a pseudo-random unsigned 64-bit integer within the specified range [min, max-exclusive). The max-exclusive value is not included in the possible results.

• random-u64-inclusive(min: u64, max-inclusive: u64) -> u64: Generates a pseudo-random unsigned 64-bit integer within the specified inclusive range [min, max-inclusive]. The max-inclusive value is included in the possible results.

• random-string(min-length: u16, max-length-exclusive: u16) -> string: Generates a pseudo-random alphanumeric string (containing uppercase and lowercase letters, and digits) with a length between min-length (inclusive) and max-length-exclusive (exclusive).

• sleep: func(schedule-at: schedule-at) -> result<datetime>: Persistently pauses the workflow's execution for the specified duration. The sleep duration can be specified in milliseconds, seconds, minutes, hours, or days. The successful returned value represents the time when the durable sleep expires, error indicates the delay was cancelled.

• join-set-create: func() -> join-set: Creates a new join set with an automatically generated, unique name.

• join-set-create-named: func(name: string) -> result<join-set, join-set-create-error>: Creates a new join set with a user-provided name.

• join-set-close: func(join-set: join-set): Closes the join set.

• submit-delay: func(join-set: borrow<join-set>, timeout: schedule-at) -> delay-id: Submit a delay request to the join set. The delay can be later polled using join-next.

• join-next: func(join-set: borrow<join-set>) -> result<tuple<response-id, result>, join-next-error>: Block the workflow execution until next response associated with the join set arrives. The response is marked as processed. Child execution result can be obtained using -get extension function using the returned execution ID. Return join-next-error::all-processed if the join set has all requests matched with responses already processed.

• join-next-try: func(join-set: borrow<join-set>) -> result<tuple<response-id, result>, join-next-try-error>: Non-blocking variant of join-next. Attempts to process the next response without blocking. Return join-next-try-error::pending if no response is available yet but there are pending requests. Return join-next-try-error::all-processed if all requests have been matched with responses already processed.

• submit-json: func(join-set: borrow<join-set>, function: function, params: string, config: option<submit-config>) -> result<execution-id, submit-json-error>: Submit a child execution request with its parameters serialized as a JSON array. This enables dynamic function dispatch without compile-time bindings. The optional submit-config record can override activity timeout.

• get-result-json: func(execution-id: execution-id) -> result<result<option<string>, option<string>>, get-result-json-error>: Obtain a child execution result as JSON after it has been awaited using -await-next extension or join-next.

Join set resource functions

• id: func() -> string: Get the join set identifier in the form of:

  • o:NAME in case of a one-off join set, where NAME is generally an auto-incremented index optionally followed by underscode and a supplied name,
  • g:NAME in case of a generated join set where NAME is generally an auto-incremented index,
  • n:NAME in case of a named join

• submit-delay: func(timeout: schedule-at) -> delay-id: Deprecated in 4.1.0, moved to a standalone function in workflow-support. Submit a delay request to the join set.

• join-next: func() -> result<tuple<response-id, result>, join-next-error>: Deprecated in 4.1.0, moved to a standalone function in workflow-support. Block the workflow execution until next response arrives.