Golem Host functions

/// An index into the persistent log storing all performed operations of a worker
type oplog-index = u64;

/// Represents a Golem worker
record worker-id {
    component-id: component-id,
    worker-name: string
}

/// Represents a Golem component
record component-id {
    uuid: uuid,
}
 
/// UUID
record uuid {
  high-bits: u64,
  low-bits: u64
}

/// Represents a Golem component's version
type component-version = u64;

/// 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,
}

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,
}

resource get-workers {
    constructor(component-id: component-id, filter: option<worker-any-filter>, precise: bool);
 
    get-next: func() -> option<list<worker-metadata>>;
}

record worker-any-filter {
    filters: list<worker-all-filter>
}

record worker-all-filter {
    filters: list<worker-property-filter>
}

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)
}

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
}

enum filter-comparator {
    equal,
    not-equal,
    greater-equal,
    greater,
    less-equal,
    less
}
 
enum string-filter-comparator {
    equal,
    not-equal,
    like,
    not-like
}

/// 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>
}

/// Configurable persistence level for workers
variant persistence-level {
    persist-nothing,
    persist-remote-side-effects,
    smart
}

/// 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
}

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)
}