HTTP Worker Binding Types

Overview

The Worker Binding Types are a collection of different ways that a worker can be exposed to the outside world as part of an api definition.

To get a basic introduction of what api-definitions are and how bindings fit into them, please read the defining custom apis guide.

Rib Scripts

Bindings can execute code as part of various steps in the request lifecycle. All of these scripts use a scripting language called rib. You can find an introduction to the language here.

Default Binding

The default and most basic binding type that allows invoking workers in custom ways.

Example:

worker-name: '"foo"'
component-id: "{component_id}"
component-version: { component_version }
response: |
  let x = golem:it/api.{{checkout}}();
  let status: u64 = 200;
  {{headers: {{ContentType: "json", userid: "foo"}}, body: "foo", status: status}}

Parameters:

Parameter	Required	Type	Description
componentId.componentId	true	string	ID of the component to invoke
componentId.version	true	number	Version of the component to invoke
workerName	false	rib	Script used to compute the name of the worker that will be invoked. The script has access to the request input. If not provided, an ephemeral worker is used.
idempotencyKey	false	rib	Script used to compute the idempotency key. The script has access to the request input. If not provided an idempotency key will be generated.
response	true	rib	Script that is used to compute the response that will be returned to the user. The script has access to the request and worker inputs and can call worker functions. The result of the script has to be an object with status and optional headers and body fields.

Cors Binding Type

This binding type is used to add CORS support to an api. To use this binding type, install it to a separate route with the same path as your main api and an OPTIONS method. Any OPTIONS requests will be automatically answered with the configured cors headers.

Any requests to your actual api will also include the CORS response headers.

The documentation you are already familiar with CORS and what the function of each of the headers are. For more information regarding CORS, see the mdn docs (opens in a new tab).

Example:

id: users-api
version: 0.0.1
createdAt: 2024-08-21T07:42:15.696Z
routes:
  - method: Options
    path: /users/{user-id}
    binding:
      bindingType: cors-preflight
  - method: Get
    path: /users/{user-id}
    binding:
      response: |
        {status: 200u64, body: "Hello World"}

Parameters:

Parameter	Required	Type	Description
allowOrigin	false	string	Value of the Access-Control-Allow-Origin header. Defaults to "*" if not provided.
allowMethods	false	string	Value of the Access-Control-Allow-Methods header. Defaults to "GET, POST, PUT, DELETE, OPTIONS" if not provided.
allowHeaders	false	string	Value of the Access-Control-Allow-Headers header. Defaults to "Content-Type, Authorization" if not provided.
exposeHeaders	false	string	Value of the Access-Control-Expose-Headers.
maxAge	false	string	Value of the Access-Control-Max-Age header.
allowCredentials	false	string	Value of the Access-Control-Allow-Credentials header.

File Server

A binding type that is used to retrieve files from a workers filesystem. For read-write files the file is retrieved between running worker invocation, so users are guaranteed to not see any in-progress changes to files.

For read-only files the files are retrieved from a separate datastore and not directly from the worker. This makes retrieving read-only files very cheap and allows it be used for serving static content.

Example:

bindingType: file-server
componentId:
  componentId: "{component_id}"
  version: 0
workerName: 'let name: string = "{worker_name}"; name'
response: 'let file: string = request.path.file; "/files/${{file}}"'

Parameters:

Parameter	Required	Type	Description
componentId.componentId	true	string	ID of the component to invoke
componentId.version	true	number	Version of the component to invoke
workerName	false	rib	Script used to compute the name of the worker that will be invoked. The script has access to the request input. If not provided, an ephemeral worker is used.
idempotencyKey	false	rib	Script used to compute the idempotency key. The script has access to the request input. If not provided an idempotency key will be generated.
response	true	rib	Script that is used to compute the file to retrieve and the response to send to users. See the dedicatedc section for more details.

File Server Response Object

The object returned from the response rib script warrants some extra mention. There are two different structures that are supported by golem:

Returning a single string. The returned string is interepreted as an absolute path and looked up in the worker filesystem and returned with an inferred content type and a 200 status code. If the file does not exist, a 404 is returned instead.

As an object. This object can have 3 different fields that are explained below:

Field	Required	Rib Type	Description
headers	false	record	Headers that should be included in the response.
status	false	u64	Status code of the response. If not provided defaults to 200.
file-path	true	string	Path of the file that should be retrieved from the worker filesystem. If the file does not exist a 404 is returned

Http Handler

A binding type used for integrating with components that implement the wasi:http/proxy world. The binding will forward the incoming requests to the worker and return the responses back to the user.

Example:

bindingType: http-handler
componentId:
  componentId: "{component_id}"
  version: 0
workerName: 'let name: string = "{worker_name}"; name'
response: 'let file: string = request.path.file; "/files/${{file}}"'

Parameters:

Parameter	Required	Type	Description
componentId.componentId	true	string	ID of the component to invoke
componentId.version	true	number	Version of the component to invoke
workerName	false	rib	Script used to compute the name of the worker that will be invoked. The script has access to the request input. If not provided, an ephemeral worker is used.
idempotencyKey	false	rib	Script used to compute the idempotency key. The script has access to the request input. If not provided an idempotency key will be generated.

JSON-WAVE Mapping