Skip to content

Latest commit

 

History

History
147 lines (103 loc) · 5.78 KB

wasi.mdx

File metadata and controls

147 lines (103 loc) · 5.78 KB
Raw

import { Callout } from "nextra/components"

Using WASI interfaces from TypeScript

Golem implements and exports a subset of the WASI interfaces, as well as its own runtime interfaces.

The Golem TypeScript SDK provides idiomatic wrappers on a subset of these interfaces, but it is also possible to use the generated bindings directly.

WIT specifications

The full set of WIT specifications Golem implements is available in the following public repository:

https://github.com/golemcloud/golem-wit/tree/main/wit/deps

The following table lists all packages provided by Golem:

Package Description
golem:api Golem's Runtime API
golem:rpc Provides support for Worker to Worker communication
wasi:blobstore Interface for storing and retrieving large binary data
wasi:cli Interface for environment variables and standard I/O
wasi:clocks Interface for querying the system time
wasi:filesystem Interface for working with files and directories
wasi:http Interface for making HTTP requests
wasi:io Interface for working with futures and streams
wasi:keyvalue Interface for storing and retrieving key-value pairs - only partially implemented
wasi:logging Interface for logging messages
wasi:random Interface for generating random numbers
wasi:sockets Interface for working with TCP and UDP sockets (currently not supporting durable execution)

Bindings

The TypeScript bindings for the WASI and Golem-specific interfaces are provided in the golem:api/host@0.2.0 module. You can import and use these bindings in your TypeScript code.

Additional Golem runtime APIs

This section describes Golem-specific functionalities which are available through the Golem runtime API.

Generate an idempotency key

Golem provides a function to generate an idempotency key (a UUID) which can be passed to external systems to ensure that the same request is not processed multiple times.

It is guaranteed that this idempotency key will always be the same (per occurrence) even if the worker is restarted due to a crash.

To generate an idempotency key:

import { generateIdempotencyKey } from "golem:api/host@0.2.0"

const key: Uuid = generateIdempotencyKey()

Get worker metadata

It is possible to query metadata for Golem workers. This metadata is defined by the WorkerMetadata interface:

interface WorkerMetadata {
  workerId: WorkerId
  args: string[]
  env: [string, string][]
  status: WorkerStatus
  componentVersion: bigint
  retryCount: bigint
}

There are two exported functions to query worker metadata:

  • getSelfMetadata() returns the metadata for the current worker
  • getWorkerMetadata(workerId: WorkerId) returns the metadata for a specific worker given by its WorkerId

Enumerate workers

Worker enumeration is a feature of Golem available both through the public HTTP API and using the WIT interfaces.

Warning: Enumerating workers of a component is a slow operation and should not be used as part of the application logic.

The following example demonstrates how to use the worker enumeration API:

import {
  ComponentId,
  GetWorkers,
  WorkerAnyFilter,
  WorkerMetadata,
  WorkerStatusFilter,
} from "golem:api/host@0.2.0"

const filter: WorkerAnyFilter = {
  filters: [
    {
      filters: [
        {
          tag: "status",
          val: {
            comparator: "equal",
            value: "idle",
          } satisfies WorkerStatusFilter,
        },
      ],
    },
  ],
}

const componentId: ComponentId = {
  /* ... */
}
const workers: WorkerMetadata[] = []
const getter = new GetWorkers(componentId, filter, true)

let batch: WorkerMetadata[] | undefined
while ((batch = getter.getNext()) !== undefined) {
  workers.push(...batch)
}

The third parameter of the GetWorkers constructor enables precise mode. In this mode, Golem will calculate the latest metadata for each returned worker; otherwise, it uses only the last cached values.

Update a worker

To trigger an update for a given worker from one component version to another, use the updateWorker function:

import { updateWorker, WorkerId, ComponentVersion } from "golem:api/host@0.2.0"

const workerId: WorkerId = {
  /* ... */
}

const targetVersion: ComponentVersion = 1n

updateWorker(workerId, targetVersion, "automatic")

To learn more about updating workers, see the updating workers page in the documentation.

The WASI Key-Value store interface

Although Golem workers can store their state completely in their own memory, it is possible to use the wasi:keyvalue interface to store key-value pairs in a Golem managed key value storage.

This can be useful if state needs to be shared between different workers or if the size of this state is too large to be stored in memory.

The WASI Blob Store interface

The wasi:blobstore interface provides a way to store and retrieve large binary data. This can be useful for storing large files or other binary data that is too large to be stored in the worker's memory.