WASI HTTP Incoming handler

If you have a wasm component that exports the wasi:http/incoming-handler@0.2.x world, you can easily deploy your application to Golem. This tutorial will walk you through deploying such an application to Golem.

Let's assume that we have an application written in any supported language that implements the following world:

package golem:example;
 
world api {
  import wasi:http/types@0.2.3;
  export wasi:http/incoming-handler@0.2.3;
}

and we want to deploy this under the GET /api route on our domain.

The way we are going to do this using Golem is by defining an api-definition with the http handler binding type.

Building and uploading the component

The first step is to build your application into a wasm component file. The way to do this depends on your language and toolchain, but using Rust and Cargo the command might look like this:

$ cargo component build --release
 
Generating bindings for example (src/bindings.rs)
 Compiling example v0.1.0 (/Users/golem/tmp/doc-temp/example)
 Finished `release` profile [optimized] target(s) in 0.33s
 Creating component target/wasm32-wasip1/release/example.wasm

Once we have the wasm file, we need to upload it to the Golem platform. To do this using the Golem CLI, run the following command:

$ golem-cli component add --component-name example-component component.wasm
 
{"componentUrn":"urn:component:fd13822e-b8fd-4c58-a87a-909feeea63ec","componentVersion":0,"componentName":"example-component","componentSize":103873,"createdAt":"2025-01-29T19:31:53.874584665Z","exports":["wasi:http/incoming-handler@0.2.3.{handle}(request: handle<0>, response-out: handle<1>)","golem:http/incoming-handler.{handle}(request: record { method: variant { GET, HEAD, POST, PUT, DELETE, CONNECT, OPTIONS, TRACE, PATCH, custom(string) }, scheme: variant { HTTP, HTTPS, custom(string) }, authority: string, path-and-query: string, headers: list<tuple<string, list<u8>>>, body-and-trailers: option<record { content: list<u8>, trailers: option<list<tuple<string, list<u8>>>> }> }) -> record { status: u16, headers: list<tuple<string, list<u8>>>, body-and-trailers: option<record { content: list<u8>, trailers: option<list<tuple<string, list<u8>>>> }> }"],"dynamicLinking":{}}

Once the component is uploaded, we need to take note of the component id (fd13822e-b8fd-4c58-a87a-909feeea63ec) and version (0), we'll need them in the next step.

Defining the API

The next step is to define the api. This is done by writing an api definition for our api. For our example this would look like this:

id: example-api
version: "0.1.0"
draft: true
routes:
  - method: Get
    path: "/api"
    binding:
      bindingType: http-handler
      componentId:
        componentId: "fd13822e-b8fd-4c58-a87a-909feeea63ec"
        version: 0

Save the above to a file 'api.yaml'.

Uploading and deploying the API

Next the api needs to be uploaded and deployed to Golem. This can be done using the CLI with the following two commands:

This registers the api definition with Golem and makes it available for other commands:

$ golem-cli api-definition add api.yaml
 
{
  "id": "example-api",
  "version": "0.1.0",
  "routes": [
    {
      "method": "Get",
      "path": "/api",
      "security": null,
      "binding": {
        "componentId": {
          "componentId": "fd13822e-b8fd-4c58-a87a-909feeea63ec",
          "version": 0
        },
        "workerName": null,
        "idempotencyKey": null,
        "response": null,
        "bindingType": "http-handler",
        "responseMappingInput": null,
        "workerNameInput": {
          "types": {}
        },
        "idempotencyKeyInput": null,
        "corsPreflight": null,
        "responseMappingOutput": null
      }
    }
  ],
  "draft": true,
  "createdAt": "2025-01-29T19:31:54.328610228Z"
}

Now we can deploy the api to our host (localhost in this example):

$ golem-cli api-deployment deploy --definition example-api/0.1.0 --host localhost:9093
 
{
  "apiDefinitions": [
    {
      "id": "example-api",
      "version": "0.1.0"
    }
  ],
  "site": {
    "host": "localhost:9093",
    "subdomain": null
  },
  "createdAt": "2025-01-29T19:31:54.369756Z"
}

Invoking the API

This concludes the process of uploading a component that implements the wasi:http/incoming-handler to Golem. The API is now being served and will respond to http requests on the configure route.

http localhost:9093/api
 
"Hello, I'm a durable teapot."

Next Steps Deploy