Worker API

Get metadata of multiple workers

Path	Method	Protected
`/v1/components/{component_id}/workers`	GET	Yes

Filters

Property	Comparator	Description	Example
name	StringFilterComparator	Name of worker	`name = worker-name`
version	FilterComparator	Version of worker	`version >= 0`
status	FilterComparator	Status of worker	`status = Running`
env.[key]	StringFilterComparator	Environment variable of worker	`env.var1 = value`
createdAt	FilterComparator	Creation time of worker	`createdAt > 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

Name	Type	Required	Description
filter	array	No	Filter for worker metadata in form of `property op value`. Can be used multiple times (AND condition is applied between them)
cursor	string	No	Count of listed values, default: 50
count	integer	No	Position 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
precise	boolean	No	Precision 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": "616ccd92-d666-4180-8349-8d125b269fac",
        "workerName": "string"
      },
      "accountId": "string",
      "args": ["string"],
      "env": {
        "property1": "string",
        "property2": "string"
      },
      "status": "Running",
      "componentVersion": 0,
      "retryCount": 0,
      "pendingInvocationCount": 0,
      "updates": [
        {
          "type": "pendingUpdate",
          "timestamp": "2019-08-24T14:15:22Z",
          "targetVersion": 0
        }
      ],
      "createdAt": "2019-08-24T14:15:22Z",
      "lastError": "string",
      "componentSize": 0,
      "totalLinearMemorySize": 0,
      "ownedResources": {
        "property1": {
          "createdAt": "2019-08-24T14:15:22Z",
          "indexed": {
            "resourceName": "string",
            "resourceParams": ["string"]
          }
        },
        "property2": {
          "createdAt": "2019-08-24T14:15:22Z",
          "indexed": {
            "resourceName": "string",
            "resourceParams": ["string"]
          }
        }
      },
      "activePlugins": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"]
    }
  ],
  "cursor": {
    "cursor": 0,
    "layer": 0
  }
}

Launch a new worker.

Path	Method	Protected
`/v1/components/{component_id}/workers`	POST	Yes

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": "616ccd92-d666-4180-8349-8d125b269fac",
    "workerName": "string"
  },
  "componentVersion": 0
}

Get metadata of a worker

Path	Method	Protected
`/v1/components/{component_id}/workers/{worker_name}`	GET	Yes

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": "616ccd92-d666-4180-8349-8d125b269fac",
    "workerName": "string"
  },
  "accountId": "string",
  "args": ["string"],
  "env": {
    "property1": "string",
    "property2": "string"
  },
  "status": "Running",
  "componentVersion": 0,
  "retryCount": 0,
  "pendingInvocationCount": 0,
  "updates": [
    {
      "type": "pendingUpdate",
      "timestamp": "2019-08-24T14:15:22Z",
      "targetVersion": 0
    }
  ],
  "createdAt": "2019-08-24T14:15:22Z",
  "lastError": "string",
  "componentSize": 0,
  "totalLinearMemorySize": 0,
  "ownedResources": {
    "property1": {
      "createdAt": "2019-08-24T14:15:22Z",
      "indexed": {
        "resourceName": "string",
        "resourceParams": ["string"]
      }
    },
    "property2": {
      "createdAt": "2019-08-24T14:15:22Z",
      "indexed": {
        "resourceName": "string",
        "resourceParams": ["string"]
      }
    }
  },
  "activePlugins": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"]
}

Delete a worker

Path	Method	Protected
`/v1/components/{component_id}/workers/{worker_name}`	DELETE	Yes

Interrupts and deletes an existing worker.

Example Response JSON

{}

Invoke a function and await its resolution

Path	Method	Protected
`/v1/components/{component_id}/workers/{worker_name}/invoke-and-await`	POST	Yes

Supply the parameters in the request body as JSON.

Query Parameters

Name	Type	Required	Description
function	string	Yes	-

Example Request JSON

{
  "params": [
    {
      "typ": {
        "type": "Variant",
        "cases": [
          {
            "name": "string",
            "typ": {}
          }
        ]
      },
      "value": null
    }
  ]
}

Example Response JSON

{
  "result": {
    "typ": {
      "type": "Variant",
      "cases": [
        {
          "name": "string",
          "typ": {}
        }
      ]
    },
    "value": null
  }
}

Invoke a function and await its resolution on a new worker with a random generated name

Path	Method	Protected
`/v1/components/{component_id}/invoke-and-await`	POST	Yes

Ideal for invoking ephemeral components, but works with durable ones as well. Supply the parameters in the request body as JSON.

Query Parameters

Name	Type	Required	Description
function	string	Yes	-

Example Request JSON

{
  "params": [
    {
      "typ": {
        "type": "Variant",
        "cases": [
          {
            "name": "string",
            "typ": {}
          }
        ]
      },
      "value": null
    }
  ]
}

Example Response JSON

{
  "result": {
    "typ": {
      "type": "Variant",
      "cases": [
        {
          "name": "string",
          "typ": {}
        }
      ]
    },
    "value": null
  }
}

Invoke a function

Path	Method	Protected
`/v1/components/{component_id}/workers/{worker_name}/invoke`	POST	Yes

A simpler version of the previously defined invoke and await endpoint just triggers the execution of a function and immediately returns.

Query Parameters

Name	Type	Required	Description
function	string	Yes	name of the exported function to be invoked

Example Request JSON

{
  "params": [
    {
      "typ": {
        "type": "Variant",
        "cases": [
          {
            "name": "string",
            "typ": {}
          }
        ]
      },
      "value": null
    }
  ]
}

Example Response JSON

{}

Invoke a function on a new worker with a random generated name

Path	Method	Protected
`/v1/components/{component_id}/invoke`	POST	Yes

Ideal for invoking ephemeral components, but works with durable ones as well. A simpler version of the previously defined invoke and await endpoint just triggers the execution of a function and immediately returns.

Query Parameters

Name	Type	Required	Description
function	string	Yes	name of the exported function to be invoked

Example Request JSON

{
  "params": [
    {
      "typ": {
        "type": "Variant",
        "cases": [
          {
            "name": "string",
            "typ": {}
          }
        ]
      },
      "value": null
    }
  ]
}

Example Response JSON

{}

Complete a promise

Path	Method	Protected
`/v1/components/{component_id}/workers/{worker_name}/complete`	POST	Yes

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

Path	Method	Protected
`/v1/components/{component_id}/workers/{worker_name}/interrupt`	POST	Yes

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

Name	Type	Required	Description
recovery-immediately	boolean	No	if true will simulate a worker recovery. Defaults to false.

Example Response JSON

{}

Advanced search for workers

Path	Method	Protected
`/v1/components/{component_id}/workers/find`	POST	Yes

Filter types

Type	Comparator	Description	Example
Name	StringFilterComparator	Name of worker	`{ "type": "Name", "comparator": "Equal", "value": "worker-name" }`
Version	FilterComparator	Version of worker	`{ "type": "Version", "comparator": "GreaterEqual", "value": 0 }`
Status	FilterComparator	Status of worker	`{ "type": "Status", "comparator": "Equal", "value": "Running" }`
Env	StringFilterComparator	Environment variable of worker	`{ "type": "Env", "name": "var1", "comparator": "Equal", "value": "value" }`
CreatedAt	FilterComparator	Creation time of worker	`{ "type": "CreatedAt", "comparator": "Greater", "value": "2024-04-01T12:10:00Z" }`
And		And filter combinator	`{ "type": "And", "filters": [ ... ] }`
Or		Or filter combinator	`{ "type": "Or", "filters": [ ... ] }`
Not		Negates 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": {
    "cursor": 0,
    "layer": 0
  },
  "count": 0,
  "precise": true
}

Example Response JSON

{
  "workers": [
    {
      "workerId": {
        "componentId": "616ccd92-d666-4180-8349-8d125b269fac",
        "workerName": "string"
      },
      "accountId": "string",
      "args": ["string"],
      "env": {
        "property1": "string",
        "property2": "string"
      },
      "status": "Running",
      "componentVersion": 0,
      "retryCount": 0,
      "pendingInvocationCount": 0,
      "updates": [
        {
          "type": "pendingUpdate",
          "timestamp": "2019-08-24T14:15:22Z",
          "targetVersion": 0
        }
      ],
      "createdAt": "2019-08-24T14:15:22Z",
      "lastError": "string",
      "componentSize": 0,
      "totalLinearMemorySize": 0,
      "ownedResources": {
        "property1": {
          "createdAt": "2019-08-24T14:15:22Z",
          "indexed": {
            "resourceName": "string",
            "resourceParams": ["string"]
          }
        },
        "property2": {
          "createdAt": "2019-08-24T14:15:22Z",
          "indexed": {
            "resourceName": "string",
            "resourceParams": ["string"]
          }
        }
      },
      "activePlugins": ["497f6eca-6276-4993-bfeb-53cbbbba6f08"]
    }
  ],
  "cursor": {
    "cursor": 0,
    "layer": 0
  }
}

Resume a worker

Path	Method	Protected
`/v1/components/{component_id}/workers/{worker_name}/resume`	POST	Yes

Example Response JSON

{}

Update a worker

Path	Method	Protected
`/v1/components/{component_id}/workers/{worker_name}/update`	POST	Yes

Example Request JSON

{
  "mode": "Automatic",
  "targetVersion": 0
}

Example Response JSON

{}

Get the oplog of a worker

Path	Method	Protected
`/v1/components/{component_id}/workers/{worker_name}/oplog`	GET	Yes

Query Parameters

Name	Type	Required	Description
from	integer	No	-
count	integer	Yes	-
cursor	#/components/schemas/OplogCursor	No	-
query	string	No	-

Example Response JSON

{
  "entries": [
    {
      "oplogIndex": 0,
      "entry": {
        "type": "Create",
        "timestamp": "2019-08-24T14:15:22Z",
        "worker_id": {
          "componentId": "616ccd92-d666-4180-8349-8d125b269fac",
          "workerName": "string"
        },
        "component_version": 0,
        "args": ["string"],
        "env": {
          "property1": "string",
          "property2": "string"
        },
        "account_id": "string",
        "parent": {
          "componentId": "616ccd92-d666-4180-8349-8d125b269fac",
          "workerName": "string"
        },
        "component_size": 0,
        "initial_total_linear_memory_size": 0,
        "initial_active_plugins": [
          {
            "installation_id": "91166175-c6a9-4caf-88e9-3147ffc9c934",
            "plugin_name": "string",
            "plugin_version": "string",
            "parameters": {
              "property1": "string",
              "property2": "string"
            }
          }
        ]
      }
    }
  ],
  "next": {
    "next_oplog_index": 0,
    "current_component_version": 0
  },
  "firstIndexInChunk": 0,
  "lastIndex": 0
}

Worker API Errors

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

Token Open Source