package obelisk:workflow@6.0.0;
@since(version = 4.0.0)
interface workflow-support {
use obelisk:types/time@5.0.0.{schedule-at, datetime};
use obelisk:types/execution@5.0.0.{delay-id, execution-id, response-id, function, schedule-json-error, execution-failure-kind};
use obelisk:types/join-set@5.0.0.{join-set};
/// Error variants that may occur on named join set creation.
/// The name may only contain alphanumeric characters and the following extra characters:
/// * dash `-`
/// * forward slash `/`
@since(version = 3.0.0)
variant join-set-create-error {
conflict,
invalid-name(string),
}
@since(version = 4.1.0)
variant get-result-json-error {
execution-id-parsing-error(string),
/// Processed responses do not contain the specified execution ID.
/// Execution was not awaited using `-await-next` extension or `join-set.join-next`.
not-found-in-processed-responses,
}
@since(version = 5.0.0)
variant submit-json-error {
/// See `Function` definition
ffqn-parsing-error(string),
function-not-found,
type-check-error(string),
}
/// Error variants that may occur when calling `join-next` function.
@since(version = 4.1.0)
variant join-next-error {
/// All submitted requests and their responses were already processed.
all-processed,
}
/// Error variants that may occur when calling `join-next-try` function.
@since(version = 4.1.0)
variant join-next-try-error {
/// All submitted requests and their responses were already processed.
all-processed,
/// No response is available yet, but there are pending requests.
pending,
}
/// Error variants that may occur when calling `stub-json`.
@since(version = 5.0.0)
variant stub-json-error {
/// Cannot parse the execution ID.
execution-id-parsing-error(string),
/// The target execution was not found.
execution-not-found,
/// supplied return value does not type check.
type-check-error(string),
/// Write conflict — a different result was already stubbed.
conflict,
}
/// Get the execution ID of the current workflow invocation.
/// Returns the ID assigned to this workflow execution.
@since(version = 5.1.0)
execution-id-current: func() -> execution-id;
/// Returns a random u64 in the range [min, max).
@since(version = 6.0.0)
random-u64: func(min: u64, max-exclusive: u64) -> u64;
/// Returns a random u64 in the range [min, max].
@since(version = 6.0.0)
random-u64-inclusive: func(min: u64, max-inclusive: u64) -> u64;
/// Returns a random string with a length in the range [min_length, max_length).
/// The string consists only of alphanumeric characters (lowercase and uppercase letters, digits).
@since(version = 6.0.0)
random-string: func(min-length: u16, max-length-exclusive: u16) -> string;
/// Block execution for given time, return the time when the durable sleep expires.
/// Returns error if the delay is cancelled.
/// `name` optionally names the one-off join set.
@since(version = 6.0.0)
sleep: func(schedule-at: schedule-at, name: option<string>) -> result<datetime>;
/// Create a new join set with a generated name.
@since(version = 6.0.0)
join-set-create: func() -> join-set;
/// Create a new join set with the specified name.
/// The name may only contain alphanumeric characters and the following extra characters:
/// * dash `-`
/// * forward slash `/`
@since(version = 6.0.0)
join-set-create-named: func(name: string) -> result<join-set, join-set-create-error>;
/// Explicitly close join set. Unawaited delay requests,
/// activities and cancellable workflows are cancelled, unawaited non-cancellable workflows are awaited,
/// as mandated by structured concurrency pattern.
/// Function `get-result-json`, `get-execution-failure-kind` or `-get` extension
/// can be later used to lookup the execution result of each submitted child execution.
@since(version = 6.0.0)
join-set-close: func(self: join-set);
/// Submit a child execution request with its parameters serialized as JSON array to a join set.
@since(version = 6.0.0)
submit-json: func(join-set: borrow<join-set>, function: function, params: string) -> result<execution-id, submit-json-error>;
/// Obtain child execution result after it has been awaited using `-await-next` extension or `join-set.join-next`.
@since(version = 6.0.0)
get-result-json: func(execution-id: execution-id) -> result<result<option<string>, option<string>>, get-result-json-error>;
/// The kind of platform-level execution failure for a previously *processed*
/// child response, or `none` if it finished with an ok / business `err` result.
/// Like `get-result-json`, only responses already awaited via `join-next` /
/// `-await-next` can be queried; unprocessed or unknown IDs error the same way.
/// This is additive to the err value, which keeps carrying the failure sentinel.
@since(version = 6.0.0)
get-execution-failure-kind: func(execution-id: execution-id) -> result<option<execution-failure-kind>, get-result-json-error>;
/// The execution ID of the last direct call (`call-json`), or `none` if there
/// was none. Unlike `last-oneoff-id`, it is never a delay and is not clobbered
/// by an intervening `sleep`. Pair with `get-execution-failure-kind` to resolve
/// the failure kind of the last direct call.
@since(version = 6.0.0)
last-direct-call-id: func() -> option<execution-id>;
/// The `response-id` of the last one-off operation of any kind, including
/// `sleep` (in which case it is a `delay-id`), or `none` if there was none.
@since(version = 6.0.0)
last-oneoff-id: func() -> option<response-id>;
/// Submit a delay request to the join set. The delay can be later polled using `join-next`.
@since(version = 6.0.0)
submit-delay: func(join-set: borrow<join-set>, timeout: schedule-at) -> delay-id;
/// Block the workflow execution until next response associated with the join set arrives.
/// The response is marked as processed and its value is returned directly.
/// Use `join-set.last-id` for the id of the processed response and
/// `get-execution-failure-kind` for a child's failure kind.
/// Returns Ok(Some(json)) / Ok(None) for an ok result (Ok(None) also for an expired delay),
/// Err(Some(json)) / Err(None) for an err result (Err(None) also for a cancelled delay).
/// Return `join-next-error::all-processed` if the join set has all requests matched with responses already processed.
@since(version = 6.0.0)
join-next: func(join-set: borrow<join-set>) -> result<result<option<string>, option<string>>, join-next-error>;
/// Attempt to process next response without blocking.
/// Return `join-next-try-error::all-processed` if the join set has all requests matched with responses already processed.
/// Return `join-next-try-error::pending` if no response is available yet, but there are pending requests.
@since(version = 6.0.0)
join-next-try: func(join-set: borrow<join-set>) -> result<result<option<string>, option<string>>, join-next-try-error>;
/// Generate a new top-level execution ID.
@since(version = 5.0.0)
execution-id-generate: func() -> execution-id;
/// Schedule a new top-level execution with its parameters serialized as JSON array.
/// Use the execution ID returned by `execution-id-generate`.
@since(version = 5.0.0)
schedule-json: func(execution-id: execution-id, schedule-at: schedule-at, function: function, params: string) -> result<_, schedule-json-error>;
/// Call a function and block until the result is available. Equivalent to
/// join-set-create + submit-json + join-next + join-set-close.
/// Returns Ok(Some(json)) for successful result with value,
/// Ok(None) for successful result with no value,
/// Err(Some(json)) for error result with value,
/// Err(None) for error result with no value.
@since(version = 5.0.0)
call-json: func(function: function, params: string) -> result<result<option<string>, option<string>>, schedule-json-error>;
/// Write a stub response with a JSON-serialized result for an activity_stub or activity_external execution.
/// The `execution-id` must be a derived (child) execution ID.
/// The `result-json` is the JSON-serialized return value.
@since(version = 5.0.0)
stub-json: func(execution-id: execution-id, result-json: string) -> result<_, stub-json-error>;
}
/// Backtrace-carrying variants of the event-persisting `workflow-support` functions.
/// Only interpreted runtimes (the JS runtime) supply a source-level `backtrace`;
/// native components import the plain `workflow-support` interface instead.
@since(version = 6.0.0)
interface workflow-support-backtrace {
use obelisk:types/time@5.0.0.{schedule-at, datetime};
use obelisk:types/execution@5.0.0.{delay-id, execution-id, function, schedule-json-error};
use obelisk:types/backtrace@5.0.0.{wasm-backtrace};
use obelisk:types/join-set@5.0.0.{join-set};
use workflow-support.{join-set-create-error, submit-json-error, join-next-error, join-next-try-error, stub-json-error};
/// See `workflow-support.random-u64`.
@since(version = 6.0.0)
random-u64: func(min: u64, max-exclusive: u64, backtrace: option<wasm-backtrace>) -> u64;
/// See `workflow-support.random-u64-inclusive`.
@since(version = 6.0.0)
random-u64-inclusive: func(min: u64, max-inclusive: u64, backtrace: option<wasm-backtrace>) -> u64;
/// See `workflow-support.random-string`.
@since(version = 6.0.0)
random-string: func(min-length: u16, max-length-exclusive: u16, backtrace: option<wasm-backtrace>) -> string;
/// See `workflow-support.sleep`.
@since(version = 6.0.0)
sleep: func(schedule-at: schedule-at, name: option<string>, backtrace: option<wasm-backtrace>) -> result<datetime>;
/// See `workflow-support.join-set-create`.
@since(version = 6.0.0)
join-set-create: func(backtrace: option<wasm-backtrace>) -> join-set;
/// See `workflow-support.join-set-create-named`.
@since(version = 6.0.0)
join-set-create-named: func(name: string, backtrace: option<wasm-backtrace>) -> result<join-set, join-set-create-error>;
/// See `workflow-support.join-set-close`.
@since(version = 6.0.0)
join-set-close: func(self: join-set, backtrace: option<wasm-backtrace>);
/// See `workflow-support.submit-json`.
@since(version = 6.0.0)
submit-json: func(join-set: borrow<join-set>, function: function, params: string, backtrace: option<wasm-backtrace>) -> result<execution-id, submit-json-error>;
/// See `workflow-support.submit-delay`.
@since(version = 6.0.0)
submit-delay: func(join-set: borrow<join-set>, timeout: schedule-at, backtrace: option<wasm-backtrace>) -> delay-id;
/// See `workflow-support.join-next`.
@since(version = 6.0.0)
join-next: func(join-set: borrow<join-set>, backtrace: option<wasm-backtrace>) -> result<result<option<string>, option<string>>, join-next-error>;
/// See `workflow-support.join-next-try`.
@since(version = 6.0.0)
join-next-try: func(join-set: borrow<join-set>, backtrace: option<wasm-backtrace>) -> result<result<option<string>, option<string>>, join-next-try-error>;
/// See `workflow-support.execution-id-generate`.
@since(version = 6.0.0)
execution-id-generate: func(backtrace: option<wasm-backtrace>) -> execution-id;
/// See `workflow-support.schedule-json`.
@since(version = 6.0.0)
schedule-json: func(execution-id: execution-id, schedule-at: schedule-at, function: function, params: string, backtrace: option<wasm-backtrace>) -> result<_, schedule-json-error>;
/// See `workflow-support.call-json`.
@since(version = 6.0.0)
call-json: func(function: function, params: string, backtrace: option<wasm-backtrace>) -> result<result<option<string>, option<string>>, schedule-json-error>;
/// See `workflow-support.stub-json`.
@since(version = 6.0.0)
stub-json: func(execution-id: execution-id, result-json: string, backtrace: option<wasm-backtrace>) -> result<_, stub-json-error>;
}