Golem Host functions

package golem:api@1.1.6;
 
interface host {
    /// An index into the persistent log storing all performed operations of a worker
    type oplog-index = u64;
}

package golem:rpc@0.2.0;
 
interface types {
    /// Represents a Golem worker
    record worker-id {
        component-id: component-id,
        worker-name: string
    }
}

package golem:rpc@0.2.0;
 
interface types {
    /// Represents a Golem component
    record component-id {
        uuid: uuid,
    }
 
    /// UUID
    record uuid {
    high-bits: u64,
    low-bits: u64
    }
}

package golem:api@1.1.6;
 
interface host {
    /// Represents a Golem component's version
    type component-version = u64;
}

package golem:api@1.1.6;
 
interface host {
    /// A promise ID is a value that can be passed to an external Golem API to complete that promise
    /// from an arbitrary external source, while Golem workers can await for this completion.
    record promise-id {
        worker-id: worker-id,
        oplog-idx: oplog-index,
    }
}

package golem:api@1.1.6;
 
interface host {
    record worker-metadata {
        worker-id: worker-id,
        args: list<string>,
        env: list<tuple<string, string>>,
        status: worker-status,
        component-version: u64,
        retry-count: u64
    }
 
    enum worker-status {
        /// The worker is running an invoked function
        running,
        /// The worker is ready to run an invoked function
        idle,
        /// An invocation is active but waiting for something (sleeping, waiting for a promise)
        suspended,
        /// The last invocation was interrupted but will be resumed
        interrupted,
        /// The last invocation failed and a retry was scheduled
        retrying,
        /// The last invocation failed and the worker can no longer be used
        failed,
        /// The worker exited after a successful invocation and can no longer be invoked
        exited,
    }
}

package golem:api@1.1.6;
 
interface host {
    resource get-workers {
        constructor(component-id: component-id, filter: option<worker-any-filter>, precise: bool);
 
        get-next: func() -> option<list<worker-metadata>>;
    }
}

package golem:api@1.1.6;
 
interface host {
    record worker-any-filter {
        filters: list<worker-all-filter>
    }
}

package golem:api@1.1.6;
 
interface host {
    record worker-all-filter {
        filters: list<worker-property-filter>
    }
}

package golem:api@1.1.6;
 
interface host {
    variant worker-property-filter {
        name(worker-name-filter),
        status(worker-status-filter),
        version(worker-version-filter),
        created-at(worker-created-at-filter),
        env(worker-env-filter)
    }
}

package golem:api@1.1.6;
 
interface host {
    record worker-name-filter {
        comparator: string-filter-comparator,
        value: string
    }
 
    record worker-status-filter {
        comparator: filter-comparator,
        value: worker-status
    }
 
    record worker-version-filter {
        comparator: filter-comparator,
        value: u64
    }
 
    record worker-created-at-filter {
        comparator: filter-comparator,
        value: u64
    }
 
    record worker-env-filter {
        name: string,
        comparator: string-filter-comparator,
        value: string
    }
}

package golem:api@1.1.6;
 
interface host {
    enum filter-comparator {
        equal,
        not-equal,
        greater-equal,
        greater,
        less-equal,
        less
    }
 
    enum string-filter-comparator {
        equal,
        not-equal,
        like,
        not-like
    }
}

package golem:api@1.1.6;
 
interface host {
    /// Configures how the executor retries failures
    record retry-policy {
        /// The maximum number of retries before the worker becomes permanently failed
        max-attempts: u32,
        /// The minimum delay between retries (applied to the first retry)
        min-delay: duration,
        /// The maximum delay between retries
        max-delay: duration,
        /// Multiplier applied to the delay on each retry to implement exponential backoff
        multiplier: f64,
        /// The maximum amount of jitter to add to the delay
        max-jitter-factor: option<f64>
    }
}

package golem:api@1.1.6;
 
interface host {
    /// Configurable persistence level for workers
    variant persistence-level {
        persist-nothing,
        persist-remote-side-effects,
        smart
    }
}

package golem:api@1.1.6;
 
interface host {
    /// Describes how to update a worker to a different component version
    enum update-mode {
        /// Automatic update tries to recover the worker using the new component version
        /// and may fail if there is a divergence.
        automatic,
 
        /// Manual, snapshot-based update uses a user-defined implementation of the `save-snapshot` interface
        /// to store the worker's state, and a user-defined implementation of the `load-snapshot` interface to
        /// load it into the new version.
        snapshot-based
    }
}

package golem:api@1.1.6;
 
interface host {
    variant oplog-entry {
        /// The initial worker oplog entry
        create(create-parameters),
        /// The worker invoked a host function
        imported-function-invoked(imported-function-invoked-parameters),
        /// The worker has been invoked
        exported-function-invoked(exported-function-invoked-parameters),
        /// The worker has completed an invocation
        exported-function-completed(exported-function-completed-parameters),
        /// Worker suspended
        suspend(datetime),
        /// Worker failed
        error(error-parameters),
        /// Marker entry added when get-oplog-index is called from the worker, to make the jumping behavior
        /// more predictable.
        no-op(datetime),
        /// The worker needs to recover up to the given target oplog index and continue running from
        /// the source oplog index from there
        /// `jump` is an oplog region representing that from the end of that region we want to go back to the start and
        /// ignore all recorded operations in between.
        jump(jump-parameters),
        /// Indicates that the worker has been interrupted at this point.
        /// Only used to recompute the worker's (cached) status, has no effect on execution.
        interrupted(datetime),
        /// Indicates that the worker has been exited using WASI's exit function.
        exited(datetime),
        /// Overrides the worker's retry policy
        change-retry-policy(change-retry-policy-parameters),
        /// Begins an atomic region. All oplog entries after `BeginAtomicRegion` are to be ignored during
        /// recovery except if there is a corresponding `EndAtomicRegion` entry.
        begin-atomic-region(datetime),
        /// Ends an atomic region. All oplog entries between the corresponding `BeginAtomicRegion` and this
        /// entry are to be considered during recovery, and the begin/end markers can be removed during oplog
        /// compaction.
        end-atomic-region(end-atomic-region-parameters),
        /// Begins a remote write operation. Only used when idempotence mode is off. In this case each
        /// remote write must be surrounded by a `BeginRemoteWrite` and `EndRemoteWrite` log pair and
        /// unfinished remote writes cannot be recovered.
        begin-remote-write(datetime),
        /// Marks the end of a remote write operation. Only used when idempotence mode is off.
        end-remote-write(end-remote-write-parameters),
        /// An invocation request arrived while the worker was busy
        pending-worker-invocation(pending-worker-invocation-parameters),
        /// An update request arrived and will be applied as soon the worker restarts
        pending-update(pending-update-parameters),
        /// An update was successfully applied
        successful-update(successful-update-parameters),
        /// An update failed to be applied
        failed-update(failed-update-parameters),
        /// Increased total linear memory size
        grow-memory(grow-memory-parameters),
        /// Created a resource instance
        create-resource(create-resource-parameters),
        /// Dropped a resource instance
        drop-resource(drop-resource-parameters),
        /// Adds additional information for a created resource instance
        describe-resource(describe-resource-parameters),
        /// The worker emitted a log message
        log(log-parameters),
        /// The worker's has been restarted, forgetting all its history
        restart(datetime),
        /// Activates a plugin
        activate-plugin(activate-plugin-parameters),
        /// Deactivates a plugin
        deactivate-plugin(deactivate-plugin-parameters),
        /// Revert a worker to a previous state
        revert(revert-parameters),
        /// Cancel a pending invocation
        cancel-invocation(cancel-invocation-parameters),
        /// Start a new span in the invocation context
        start-span(start-span-parameters),
        /// Finish an open span in the invocation context
        finish-span(finish-span-parameters),
        /// Set an attribute on an open span in the invocation context
        set-span-attribute(set-span-attribute-parameters),
    }
}

package golem:api@1.1.6;
 
interface host {
    variant durable-function-type {
        /// The side-effect reads from the worker's local state (for example local file system,
        /// random generator, etc.)
        read-local,
        /// The side-effect writes to the worker's local state (for example local file system)
        write-local,
        /// The side-effect reads from external state (for example a key-value store)
        read-remote,
        /// The side-effect manipulates external state (for example an RPC call)
        write-remote,
        /// The side-effect manipulates external state through multiple invoked functions (for example
        /// a HTTP request where reading the response involves multiple host function calls)
        ///
        /// On the first invocation of the batch, the parameter should be `None` - this triggers
        /// writing a `BeginRemoteWrite` entry in the oplog. Followup invocations should contain
        /// this entry's index as the parameter. In batched remote writes it is the caller's responsibility
        /// to manually write an `EndRemoteWrite` entry (using `end_function`) when the operation is completed.
        write-remote-batched(option<oplog-index>)
    }
}

package golem:api@1.1.6;
 
interface host {
    record durable-execution-state {
        is-live: bool,
        persistence-level: persistence-level,
    }
}

observe-function-call("interface", "function")
state = current-durable-execution-state()
if state.is-live {
  result = perform-side-effect(input)
  persist-typed-durable-function-invocation("function", encode(input), encode(result), durable-function-type)
} else {
  // Execute the side effect
  persisted = read-persisted-durable-function-invocation()
  result = decode(persisted.response)
}

package golem:api@1.1.6;
 
/// Invocation context support
interface context {
    current-context: func() -> invocation-context;
}

package golem:api@1.1.6;
 
/// Invocation context support
interface context {
    /// Starts a new `span` with the given name, as a child of the current invocation context
    start-span: func(name: string) -> span;
}