Welcome to the new Golem Cloud Docs! 👋
Documentation
Worker

Worker API

The worker API allows to launch new workers, query and manipulate their status, and invoke their exported functions.

Launch a new worker.

PathMethodProtected
/v2/components/{component_id}/workersPOSTYes

Creates a new worker. The worker initially is in `Idle`` status, waiting to be invoked.

The parameters in the request are the following:

  • name is the name of the created worker. This has to be unique, but only for a given component
  • args is a list of strings which appear as command line arguments for the worker
  • env is a list of key-value pairs (represented by arrays) which appear as environment variables for the worker

Example Request JSON

{
  "name": "string",
  "args": ["string"],
  "env": {
    "property1": "string",
    "property2": "string"
  }
}

Example Response JSON

{
  "workerId": {
    "componentId": "196100ac-4eec-4fb6-a7f7-86c8b584771d",
    "workerName": "string"
  },
  "componentVersionUsed": 0
}

Get metadata of multiple workers

PathMethodProtected
/v2/components/{component_id}/workersGETYes

Filters

PropertyComparatorDescriptionExample
nameStringFilterComparatorName of workername = worker-name
versionFilterComparatorVersion of workerversion >= 0
statusFilterComparatorStatus of workerstatus = Running
env.[key]StringFilterComparatorEnvironment variable of workerenv.var1 = value
createdAtFilterComparatorCreation time of workercreatedAt > 2024-04-01T12:10:00Z

Comparators

  • StringFilterComparator: eq|equal|=|==, ne|notequal|!=, like, notlike
  • FilterComparator: eq|equal|=|==, ne|notequal|!=, ge|greaterequal|>=, gt|greater|>, le|lessequal|<=, lt|less|<

Returns metadata about an existing component workers:

  • workers list of workers metadata
  • cursor cursor for next request, if cursor is empty/null, there are no other values

Query Parameters

NameTypeRequiredDescription
filterarrayNoFilter for worker metadata in form of property op value. Can be used multiple times (AND condition is applied between them)
cursorintegerNoCount of listed values, default: 50
countintegerNoPosition where to start listing, if not provided, starts from the beginning. It is used to get the next page of results. To get next page, use the cursor returned in the response
precisebooleanNoPrecision in relation to worker status, if true, calculate the most up-to-date status for each worker, default is false

Example Response JSON

{
  "workers": [
    {
      "workerId": {
        "componentId": "196100ac-4eec-4fb6-a7f7-86c8b584771d",
        "workerName": "string"
      },
      "accountId": "string",
      "args": ["string"],
      "env": {
        "property1": "string",
        "property2": "string"
      },
      "status": "Running",
      "componentVersion": 0,
      "retryCount": 0
    }
  ],
  "cursor": 0
}

Delete a worker

PathMethodProtected
/v2/components/{component_id}/workers/{worker_name}DELETEYes

Interrupts and deletes an existing worker.

Example Response JSON

{}

Get metadata of a worker

PathMethodProtected
/v2/components/{component_id}/workers/{worker_name}GETYes

Returns metadata about an existing worker:

  • workerId is a combination of the used component and the worker's user specified name
  • accountId the account the worker is created by
  • args is the provided command line arguments passed to the worker
  • env is the provided map of environment variables passed to the worker
  • componentVersion is the version of the component used by the worker
  • retryCount is the number of retries the worker did in case of a failure
  • status is the worker's current status, one of the following:
  • Running if the worker is currently executing
  • Idle if the worker is waiting for an invocation
  • Suspended if the worker was running but is now waiting to be resumed by an event (such as end of a sleep, a promise, etc)
  • Interrupted if the worker was interrupted by the user
  • Retrying if the worker failed, and an automatic retry was scheduled for it
  • Failed if the worker failed and there are no more retries scheduled for it
  • Exited if the worker explicitly exited using the exit WASI function

Example Response JSON

{
  "workerId": {
    "componentId": "196100ac-4eec-4fb6-a7f7-86c8b584771d",
    "workerName": "string"
  },
  "accountId": "string",
  "args": ["string"],
  "env": {
    "property1": "string",
    "property2": "string"
  },
  "status": "Running",
  "componentVersion": 0,
  "retryCount": 0
}

Get an invocation key

PathMethodProtected
/v2/components/{component_id}/workers/{worker_name}/keyPOSTYes

Creates an invocation key for a given worker. An invocation key is passed to the below defined invoke APIs to guarantee that retrying those invocations only performs the operation on the worker once.

Example Response JSON

{
  "value": "string"
}

Invoke a function and await it's resolution

PathMethodProtected
/v2/components/{component_id}/workers/{worker_name}/invoke-and-awaitPOSTYes

Supply the parameters in the request body as JSON.

Query Parameters

NameTypeRequiredDescription
invocation-keystringYesmust be created with the create invokation key endpoint
functionstringYesname of the exported function to be invoked
calling-convention#/components/schemas/CallingConventionNoOne of component, stdio, stdio-event-loop. Defaults to component.

Example Request JSON

{
  "params": null
}

Example Response JSON

{
  "result": null
}

Invoke a function

PathMethodProtected
/v2/components/{component_id}/workers/{worker_name}/invokePOSTYes

A simpler version of the previously defined invoke and await endpoint just triggers the execution of a function and immediately returns. Custom calling convention and invocation key is not supported. To understand how to get the function name and how to encode the function parameters check Component interface

Query Parameters

NameTypeRequiredDescription
functionstringYesname of the exported function to be invoked

Example Request JSON

{
  "params": null
}

Example Response JSON

{}

Complete a promise

PathMethodProtected
/v2/components/{component_id}/workers/{worker_name}/completePOSTYes

Completes a promise with a given custom array of bytes. The promise must be previously created from within the worker, and it's identifier (a combination of a worker identifier and an oplogIdx ) must be sent out to an external caller so it can use this endpoint to mark the promise completed. The data field is sent back to the worker and it has no predefined meaning.

Example Request JSON

{
  "oplogIdx": 0,
  "data": [0]
}

Example Response JSON

true

Interrupt a worker

PathMethodProtected
/v2/components/{component_id}/workers/{worker_name}/interruptPOSTYes

Interrupts the execution of a worker. The worker's status will be Interrupted unless the recover-immediately parameter was used, in which case it remains as it was. An interrupted worker can be still used, and it is going to be automatically resumed the first time it is used. For example in case of a new invocation, the previously interrupted invocation is continued before the new one gets processed.

Query Parameters

NameTypeRequiredDescription
recovery-immediatelybooleanNoif true will simulate a worker recovery. Defaults to false.

Example Response JSON

{}

Advanced search for workers

PathMethodProtected
/v2/components/{component_id}/workers/findPOSTYes

Filter types

TypeComparatorDescriptionExample
NameStringFilterComparatorName of worker{ "type": "Name", "comparator": "Equal", "value": "worker-name" }
VersionFilterComparatorVersion of worker{ "type": "Version", "comparator": "GreaterEqual", "value": 0 }
StatusFilterComparatorStatus of worker{ "type": "Status", "comparator": "Equal", "value": "Running" }
EnvStringFilterComparatorEnvironment variable of worker{ "type": "Env", "name": "var1", "comparator": "Equal", "value": "value" }
CreatedAtFilterComparatorCreation time of worker{ "type": "CreatedAt", "comparator": "Greater", "value": "2024-04-01T12:10:00Z" }
AndAnd filter combinator{ "type": "And", "filters": [ ... ] }
OrOr filter combinator{ "type": "Or", "filters": [ ... ] }
NotNegates the specified filter{ "type": "Not", "filter": { "type": "Version", "comparator": "GreaterEqual", "value": 0 } }

Comparators

  • StringFilterComparator: Equal, NotEqual, Like, NotLike
  • FilterComparator: Equal, NotEqual, GreaterEqual, Greater, LessEqual, Less

Returns metadata about an existing component workers:

  • workers list of workers metadata
  • cursor cursor for next request, if cursor is empty/null, there are no other values

Example Request JSON

{
  "filter": {
    "type": "Name",
    "comparator": "Equal",
    "value": "string"
  },
  "cursor": 0,
  "count": 0,
  "precise": true
}

Example Response JSON

{
  "workers": [
    {
      "workerId": {
        "componentId": "196100ac-4eec-4fb6-a7f7-86c8b584771d",
        "workerName": "string"
      },
      "accountId": "string",
      "args": ["string"],
      "env": {
        "property1": "string",
        "property2": "string"
      },
      "status": "Running",
      "componentVersion": 0,
      "retryCount": 0
    }
  ],
  "cursor": 0
}

Resume a worker

PathMethodProtected
/v2/components/{component_id}/workers/{worker_name}/resumePOSTYes

Example Response JSON

{}

Worker API Errors

Status CodeDescriptionBody
400Invalid request, returning with a list of issues detected in the request{"errors":["string"]}
401Unauthorized{"error":"string"}
403Maximum number of workers exceeded{"error":"string"}
404Component / Worker / Promise not found{"error":"string"}
409Worker already exists{"error":"string"}
500Internal server error{"golemError":{"type":"InvalidRequest","details":"string"}}