Get Workers API

The get workers API allows you to get information about the workers for given component.

To use the get workers API, first make sure to add the contents of the wit/deps folders from https://github.com/golemcloud/golem-wit (opens in a new tab) to your own wit/deps folder. You can then interact with the get workers interface from your own code in whatever language you are working in.

Our WIT file will look like this:

package golem:it;
 
interface api {
  use golem:api/host@0.2.0.{
           component-id,
           worker-metadata
  };
  get-idle-workers: func(component-id: component-id) -> list<worker-metadata>;
}
 
world workers {
  import golem:api/host@0.2.0;
 
  export api;
}

Now that we have our interface we are ready to implement it. Let's take a look at how we would do that:

mod bindings;
 
use crate::bindings::exports::golem::it::api::Guest;
use crate::bindings::golem::api::host::*;
 
struct Component;
 
impl Guest for Component {
 
    fn get_idle_workers(
        component_id: ComponentId
    ) -> Vec<WorkerMetadata> {
        println!(
            "Get idle workers of component: {component_id:?}"
        );
        let filter = Some(WorkerAnyFilter {
            filters: vec![WorkerAllFilter {
                filters: vec![WorkerPropertyFilter::Status(WorkerStatusFilter {
                    comparator: FilterComparator::Equal,
                    value: WorkerStatus::Idle,
                })],
            }]
        });
        let mut workers: Vec<WorkerMetadata> = Vec::new();
        let getter = GetWorkers::new(component_id, filter.as_ref(), true);
        loop {
            match getter.get_next() {
                Some(values) => {
                    workers.extend(values);
                }
                None => break,
            }
        }
        workers
    }
}

The get-idle-workers function is using the get-workers golem-wit resource, which is defined as follows:

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

  get-next: func() -> option<list<worker-metadata>>;
}

With get-workers resource, our component is able to get workers of provided component with matching filters, get-next function will return next chunk of workers, or will return none if there is no more workers.

Filter types

Type	Comparator	Description
worker-name-filter	string-filter-comparator	Name of worker, rust example: `WorkerNameFilter { comparator: StringFilterComparator::Equal, value: "worker-name".to_string() }`
worker-version-filter	filter-comparator	Version of worker, rust example: `WorkerVersionFilter { comparator: FilterComparator::Greater, value: 0 }`
worker-status-filter	filter-comparator	Status of worker, rust example: `WorkerStatusFilter { comparator: FilterComparator::Equal, value: WorkerStatus::Idle }`
worker-env-filter	string-filter-comparator	Environment variable of worker, rust example: `WorkerEnvFilter { name: "var1".to_string(), comparator: StringFilterComparator::Equal, value: "val".to_string() }`
worker-create-at-filter	filter-comparator	Creation time of worker, rust example: `WorkerCreatedAtFilter { comparator: FilterComparator::Greater, value: 1713207300140 }`
worker-any-filter		Or filter combinator
worker-all-filter		And filter combinator

Comparators

string-filter-comparator: equal, not-equal, like, not-like
filter-comparator: equal, not-equal, greater-equal, greater, less-equal, less

Runtime API Key Value API