Basic C Application

Prerequisites

Language-specific tools - Install Heim Prerequisites
Heim cli and runtime - Install Heim
Text Editor - VsCode is a great option with language-specific plugins
Terminal - Heim is accessed through its command-line interface

Guide

Start by running heim new to create a project from a template.

Use the up/down arrow keys to select the template and press enter:

heim@system:~/repos$ heim new
? Select template:  ›
csharp-http
csharp-http-async
python-http
rust-http
...
❯  c-http
...
typescript-http

Next, we will choose the HTTP method that the application will respond on.

For this we will choose the default value of GET:

✔ Select template:  · c-http
? Http trigger method POST/GET, Default (GET) ›

Next, we need to choose the path that the application will listen on.

Once the trigger path is set, we’ll be able to go to the trigger path, and use the HTTP method we set to trigger the application.

✔ Select template:  · C-http
✔ Http trigger method POST/GET, Default · GET
? Http trigger path /??? , Default (/hello) › /myapp

Last, we will need to set the name of the application.

✔ Select template:  · c-http
✔ Http trigger method POST/GET, Default · GET
✔ Http trigger path /??? , Default · /myapp
? Package name, (Required) › myapp

Rendered Template: ""\\Temp\\heimMUhSs7\\myapp\\wit\\deps\\clocks\\world.wit""
Rendered Template: ""\\Temp\\heimMUhSs7\\myapp\\app.c""
Rendered Template: ""\\Temp\\heimMUhSs7\\myapp\\wit\\deps\\cli\\run.wit""
Rendered Template: ""\\Temp\\heimMUhSs7\\myapp\\wit\\deps\\io\\error.wit""
Rendered Template: ""\\Temp\\heimMUhSs7\\myapp\\component.toml""
Rendered Template: ""\\Temp\\heimMUhSs7\\myapp\\wit\\deps\\sockets\\instance-network.wit""
Rendered Template: ""\\Temp\\heimMUhSs7\\myapp\\wit\\deps\\io\\poll.wit""
Rendered Template: ""\\Temp\\heimMUhSs7\\myapp\\wit\\handler.wit""
Rendered Template: ""\\Temp\\heimMUhSs7\\myapp\\wit\\deps\\sockets\\ip-name-lookup.wit""
Rendered Template: ""\\Temp\\heimMUhSs7\\myapp\\wit\\deps\\random\\world.wit""
Rendered Template: ""\\Temp\\heimMUhSs7\\myapp\\application.toml""
Rendered Template: ""\\Temp\\heimMUhSs7\\myapp\\wit\\deps\\sockets\\udp.wit""
Rendered Template: ""\\Temp\\heimMUhSs7\\myapp\\wit\\deps\\io\\streams.wit""
Rendered Template: ""\\Temp\\heimMUhSs7\\myapp\\wit\\deps\\filesystem\\types.wit""
Rendered Template: ""\\Temp\\heimMUhSs7\\myapp\\wit\\deps\\sockets\\world.wit""
Rendered Template: ""\\Temp\\heimMUhSs7\\myapp\\wit\\deps\\cli\\command.wit""
Rendered Template: ""\\Temp\\heimMUhSs7\\myapp\\wit\\deps\\cli\\environment.wit""
Rendered Template: ""\\Temp\\heimMUhSs7\\myapp\\wit\\deps\\random\\insecure.wit""
Rendered Template: ""\\Temp\\heimMUhSs7\\myapp\\bindings\\proxy.h""
Rendered Template: ""\\Temp\\heimMUhSs7\\myapp\\wit\\deps\\clocks\\wall-clock.wit""
Rendered Template: ""\\Temp\\heimMUhSs7\\myapp\\wit\\deps\\cli\\imports.wit""
Rendered Template: ""\\Temp\\heimMUhSs7\\myapp\\wit\\deps\\clocks\\monotonic-clock.wit""
Rendered Template: ""\\Temp\\heimMUhSs7\\myapp\\wit\\deps\\sockets\\tcp.wit""
Rendered Template: ""\\Temp\\heimMUhSs7\\myapp\\wit\\deps\\sockets\\udp-create-socket.wit""
Rendered Template: ""\\Temp\\heimMUhSs7\\myapp\\wit\\deps\\cli\\exit.wit""
Rendered Template: ""\\Temp\\heimMUhSs7\\myapp\\wit\\deps.lock""
Rendered Template: ""\\Temp\\heimMUhSs7\\myapp\\wit\\deps\\cli\\terminal.wit""
Rendered Template: ""\\Temp\\heimMUhSs7\\myapp\\wit\\deps\\filesystem\\preopens.wit""
Rendered Template: ""\\Temp\\heimMUhSs7\\myapp\\wit\\deps\\sockets\\tcp-create-socket.wit""
Rendered Template: ""\\Temp\\heimMUhSs7\\myapp\\wit\\deps\\clocks\\timezone.wit""
Rendered Template: ""\\Temp\\heimMUhSs7\\myapp\\wit\\deps\\random\\random.wit""
Rendered Template: ""\\Temp\\heimMUhSs7\\myapp\\wit\\deps\\cli\\stdio.wit""
Rendered Template: ""\\Temp\\heimMUhSs7\\myapp\\wit\\deps\\filesystem\\world.wit""
Rendered Template: ""\\Temp\\heimMUhSs7\\myapp\\wit\\types.wit""
Rendered Template: ""\\Temp\\heimMUhSs7\\myapp\\wit\\deps\\sockets\\network.wit""
Rendered Template: ""\\Temp\\heimMUhSs7\\myapp\\wit\\deps\\random\\insecure-seed.wit""
Rendered Template: ""\\Temp\\heimMUhSs7\\myapp\\wit\\proxy.wit""
Rendered Template: ""\\Temp\\heimMUhSs7\\myapp\\wit\\deps.toml""
Rendered Template: ""\\Temp\\heimMUhSs7\\myapp\\wit\\deps\\io\\world.wit""
[00:00:00] ########################################      39/39      Success
INFO [ Heim new ] New component created: Some("/home/heim/myapp")

Once we’ve gone through all the previous steps, we’ll have a project ready to go.

Let’s open the project in your text editor to check on what our new application looks like…

Now, you will have an application folder with this structure:
- Directorybindings/
  - proxy.h
- Directorywit/
  - Directorydeps/
    …
  - deps.lock
  - deps.toml
  - handler.wit
  - proxy.wit
  - types.wit
- app.c
- component.toml
- application.toml
Take note of the marked configuration files. Let’s take a look at these files, next.

component.toml
Section titled “component.toml”
The component.toml file, defines a component, and one or more components make up an application in Heim.

component.toml
```
name = "myapp"
version = "0.1.0"

[build.dev]
build = "wit-bindgen c wit/ --world proxy --out-dir bindings && clang --target=wasm32-wasip2 -nostdlib '-Wl,--no-entry' '-Wl,--export-all' -o myapp.wasm app.c bindings/proxy.c bindings/proxy_component_type.o %%WASI_SDK_PATH%%/share/wasi-sysroot/lib/wasm32-wasip2/libc.a"
wasm_path = "myapp.wasm"

[build.prod]
build = "wit-bindgen c wit/ --world proxy --out-dir bindings && clang --target=wasm32-wasip2 -nostdlib -g0 '-Wl,--strip-all' '-Wl,--no-entry' '-Wl,--export-all' -o myapp.wasm app.c bindings/proxy.c bindings/proxy_component_type.o %%WASI_SDK_PATH%%/share/wasi-sysroot/lib/wasm32-wasip2/libc.a"
wasm_path = "myapp.wasm"
```
a simple component.toml, with explanatory comments

Read more about component.toml

application.toml
Section titled “application.toml”
The application.toml is what defines an application. A application.toml is required for deploying an application to Heim.

application.toml
```
name = "myapp"
component_target = 'myapp:0.1.0'

[[trigger]]
type = 'http'
path = '/myapp'
method = 'GET'
```
a simple application.toml, with explanatory comments

Read more about application.toml

Open app.c and take a look at the code we have:

app.c

#include "bindings/proxy.h"
#include <stdbool.h>
#include <stdint.h>
#include <stdlib.h>
#include <string.h>

void set_string(proxy_string_t *ret, const char *str) {
ret->ptr = (uint8_t *)str;
ret->len = strlen(str);
}
void set_string_field(wasi_http_types_field_value_t *ret, const char *str) {
ret->ptr = (uint8_t *)str;
ret->len = strlen(str);
}
void set_bytes(proxy_list_u8_t *ret, const char *data) {
ret->ptr = (uint8_t *)data;
ret->len = strlen(data);
}

void exports_wasi_http_incoming_handler_handle(
    wasi_http_types_own_incoming_request_t request,
    wasi_http_types_own_response_outparam_t response_out) {

wasi_http_types_own_fields_t headers;
wasi_http_types_header_error_t headers_err;

proxy_list_tuple2_field_name_field_value_t entries;
entries.ptr = malloc(1 * sizeof(proxy_tuple2_field_name_field_value_t));
entries.len = 1;
set_string(&entries.ptr[0].f0, "Content-Type");
set_string_field(&entries.ptr[0].f1, "text/plain");

if (!wasi_http_types_static_fields_from_list(&entries, &headers,
                                            &headers_err)) {
    wasi_http_types_result_own_outgoing_response_error_code_t result = {
        .is_err = true, .val.err = headers_err.tag};
    wasi_http_types_static_response_outparam_set(response_out, &result);
    wasi_http_types_fields_drop_own(headers);
    free(entries.ptr);
    return;
}

wasi_http_types_own_outgoing_response_t res =
    wasi_http_types_constructor_outgoing_response(headers);

wasi_http_types_status_code_t status_code = 200;
wasi_http_types_method_outgoing_response_set_status_code(
    wasi_http_types_borrow_outgoing_response(res), status_code);

wasi_http_types_own_outgoing_body_t body;
if (!wasi_http_types_method_outgoing_response_body(
        wasi_http_types_borrow_outgoing_response(res), &body)) {
    wasi_http_types_result_own_outgoing_response_error_code_t result = {
        .is_err = true, .val.err = WASI_HTTP_TYPES_ERROR_CODE_INTERNAL_ERROR};
    wasi_http_types_static_response_outparam_set(response_out, &result);
    wasi_http_types_outgoing_response_drop_own(res);
    free(entries.ptr);
    return;
}

wasi_http_types_own_output_stream_t out_body_stream;
if (!wasi_http_types_method_outgoing_body_write(
        wasi_http_types_borrow_outgoing_body(body), &out_body_stream)) {
    wasi_http_types_result_own_outgoing_response_error_code_t result = {
        .is_err = true, .val.err = WASI_HTTP_TYPES_ERROR_CODE_INTERNAL_ERROR};
    wasi_http_types_static_response_outparam_set(response_out, &result);
    wasi_http_types_outgoing_body_drop_own(body);
    wasi_http_types_outgoing_response_drop_own(res);
    free(entries.ptr);
    return;
}

wasi_io_streams_stream_error_t stream_err;
proxy_list_u8_t body_contents;
set_bytes(&body_contents, "Hello world!");

if (!wasi_io_streams_method_output_stream_blocking_write_and_flush(
        wasi_io_streams_borrow_output_stream(out_body_stream), &body_contents,
        &stream_err)) {
    wasi_http_types_result_own_outgoing_response_error_code_t result = {
        .is_err = true, .val.err = stream_err.tag};
    wasi_http_types_static_response_outparam_set(response_out, &result);
    wasi_io_streams_output_stream_drop_own(out_body_stream);
    wasi_http_types_outgoing_body_drop_own(body);
    wasi_http_types_outgoing_response_drop_own(res);
    free(entries.ptr);
    return;
}

wasi_io_streams_output_stream_drop_own(out_body_stream);

wasi_http_types_error_code_t err;
if (!wasi_http_types_static_outgoing_body_finish(body, NULL, &err)) {
    wasi_http_types_result_own_outgoing_response_error_code_t result = {
        .is_err = true, .val.err = err.tag};
    wasi_http_types_static_response_outparam_set(response_out, &result);
    wasi_http_types_outgoing_body_drop_own(body);
    wasi_http_types_outgoing_response_drop_own(res);
    free(entries.ptr);
    return;
}

wasi_http_types_result_own_outgoing_response_error_code_t result = {
    .is_err = false, .val.ok = res};
wasi_http_types_static_response_outparam_set(response_out, &result);

free(entries.ptr);
return;
}

The app.c file contains boilerplate source code.

Now, we want to start the application. Read on to learn the steps needed to start an application.

Run heim start, to start the heim runtime:
heim runtime
```
heim@system:~/repos$ heim start

Starting Runtime with Config:
...

Http server listening on: http://127.0.0.1:3000
Heim portal: http://127.0.0.1:3000/heim/portal/
```
Note that the Heim portal comes included with any Heim installation, and that it will be available on http://127.0.0.1:3000/heim/portal/ once you’ve installed Heim.

To build the application and deploy it to our local-instance, we will run heim deploy. By default, this will create a debug build, but we can change it to a release build with the --release flag:

heim@system:~/repos$ heim deploy
INFO [ Heim::Deploy ] Building Component: myapp
Generating "bindings\\proxy.c"
Generating "bindings\\proxy.h"
Generating "bindings\\proxy_component_type.o"
INFO [ heim_registry::registry ] "myapp":"0.1.0":8e90af84ad0d12d3215358f67ca250122e321012720d80649497b0d94e2ec425
INFO [ Heim::Deploy ] Heim application `myapp` is now built and written to registry.
INFO [ Heim::Pipeline ] Starting pipeline 'Deploy application'
INFO [ Heim::Pipeline ] Storing unoptimized component state
INFO [ Heim::Pipeline ] Checking if defined regions in app definition is valid
INFO [ Heim::Pipeline ] Continuing with localhost region heim-localhost
INFO [ Heim::Pipeline ] Getting region specific application environment values
INFO [ Heim::Pipeline ] Set environment values for region 'heim-localhost'
INFO [ Heim::Pipeline ] Getting region specific application scaling values
INFO [ Heim::Pipeline ] Set scaling values for region 'heim-localhost'
INFO [ Heim::Pipeline ] Getting capabilities
INFO [ Heim::Pipeline ] Set capabilities values for region 'heim-localhost'
INFO [ Heim::Pipeline ] Getting triggers
INFO [ Heim::Pipeline ] Set trigger values for region 'heim-localhost'
INFO [ Heim::Pipeline ] Component environment values are valid for all regions
INFO [ Heim::Pipeline ] Checking for region with changes to build
INFO [ Heim::Pipeline ] Region "heim-localhost" has been changed and will be built
INFO [ Heim::Pipeline ] Storing component and optimized component
INFO [ Heim::Pipeline ] Stored component at ''
INFO [ Heim::Pipeline ] Stored optimized component at ''
INFO [ Heim::Pipeline ] Storing region states
INFO [ Heim::Pipeline ] Stored state for region(s) heim-localhost successfully
INFO [ Heim::Pipeline ] Creating and caching application(s)
INFO [ Heim::Pipeline ] Creating and caching application(s) for region(s) heim-localhost
INFO [ Heim::Pipeline ] Created application with hash 898b1bf62034a0cd7285519a9d4e9e7bab524c96f56ce184b7030cb8ab0739e2 for region(s) heim-localhost
INFO [ Heim::Pipeline ] Application has been deployed for region(s) heim-localhost
INFO [ Heim::Pipeline ] Pipeline 'Deploy application' finished with status 'Success'
INFO [ Heim::Deploy ] Heim deploy pipeline was successful
INFO [ Heim::Deploy ] Application is accaccessible at:
INFO [ Heim::Deploy ] [GET] http://127.0.0.1:3000/myapp
INFO [ Heim::Deploy ] Written and deployed application `myapp`.

From here, you can see that we are able to access the application on http://127.0.0.1:3000/myapp:

heim@system:~/repos$ curl http://127.0.0.1:3000/myapp
Hello World!

To deploy the application to the cloud instance, we will run heim deploy with the --cloud flag. This will generate a release build as default, but it can be changed to a debug with the the --dev flag.

This will deploy the application to your subdomain at my-subdomain.cloud.heim.dev

heim@system:~/repos$ heim deploy --cloud
INFO [ Heim::Deploy ] Building Component: myapp
Generating "bindings\\proxy.c"
Generating "bindings\\proxy.h"
Generating "bindings\\proxy_component_type.o"
INFO [ heim_registry::registry ] "myapp":"0.1.0":7b3424653cada2229a501bcac181a687aaaebf4c4180e66ced0fea17b7af56d1
INFO [ Heim::Deploy ] Heim application `myapp` is now built and written to registry.
INFO [ Heim::Pipeline ] Starting pipeline 'Deploy application'
INFO [ Heim::Pipeline ] Storing unoptimized component state
INFO [ Heim::Pipeline ] Checking if defined regions in app definition is valid
INFO [ Heim::Pipeline ] Continuing with localhost region heim-localhost
INFO [ Heim::Pipeline ] Getting region specific application environment values
INFO [ Heim::Pipeline ] Set environment values for region 'heim-localhost'
INFO [ Heim::Pipeline ] Getting region specific application scaling values
INFO [ Heim::Pipeline ] Set scaling values for region 'heim-localhost'
INFO [ Heim::Pipeline ] Getting capabilities
INFO [ Heim::Pipeline ] Set capabilities values for region 'heim-localhost'
INFO [ Heim::Pipeline ] Getting triggers
INFO [ Heim::Pipeline ] Set trigger values for region 'heim-localhost'
INFO [ Heim::Pipeline ] Component environment values are valid for all regions
INFO [ Heim::Pipeline ] Checking for region with changes to build
INFO [ Heim::Pipeline ] Region "heim-localhost" has been changed and will be built
INFO [ Heim::Pipeline ] Optimizing base component
INFO [ Heim::Pipeline ] Optimized base component, size before optimization: 191274 bytes, size after optimization: 122810 bytes
INFO [ Heim::Pipeline ] Storing component and optimized component
INFO [ Heim::Pipeline ] Stored component at ''
INFO [ Heim::Pipeline ] Stored optimized component at ''
INFO [ Heim::Pipeline ] Storing region states
INFO [ Heim::Pipeline ] Stored state for region(s) heim-localhost successfully
INFO [ Heim::Pipeline ] Creating and caching application(s)
INFO [ Heim::Pipeline ] Creating and caching application(s) for region(s) heim-localhost
INFO [ Heim::Pipeline ] Created application with hash 5f8a5ccbb4350bd081649d0db47521e98abf5c921c0e7fc1da1a24ac4df4ca14 for region(s) heim-localhost
INFO [ Heim::Pipeline ] Application has been deployed for region(s) heim-localhost
INFO [ Heim::Pipeline ] Pipeline 'Deploy application' finished with status 'Success'
INFO [ Heim::Deploy ] Heim deploy pipeline was successful
INFO [ Heim::Deploy ] Application is accaccessible at:
INFO [ Heim::Deploy ] [GET] https://my-subdomain.cloud.heim.dev/myapp
INFO [ Heim::Deploy ] Written and deployed application `myapp`.

And, in the heim runtime you will see something like this, if you started the runtime with the --verbose flag:

INFO WasmComponentHandler{
    app_id="localhost:00000000-0000-0000-0000-000000000000:00000000-0000-0000-0000-000000000000:myapp:bbcb756cbf72e572fd47f3c299f44e1d083522aaa2696c3b0b24653deb884d3c"
    uri=/myapp
}:
heim_runtime::services::handlers::wasm_component_handler: 48:
app_id="localhost:00000000-0000-0000-0000-000000000000:00000000-0000-0000-0000-000000000000:myapp:bbcb756cbf72e572fd47f3c299f44e1d083522aaa2696c3b0b24653deb884d3c"
uri=/myapp method=GET
trigger=Trigger {
    app_id: AppId("localhost:00000000-0000-0000-0000-000000000000:00000000-0000-0000-0000-000000000000:myapp:bbcb756cbf72e572fd47f3c299f44e1d083522aaa2696c3b0b24653deb884d3c"),
    path: "/myapp",
    method: "GET",
    function_target: None,
    hash: "",
    domain: "127.0.0.1"
}

The Heim runtime output above summarizes all the basic information about your application.

Now, we can make our specific C application a little bit easier to work with.

Let’s add an environment variable to our component.toml, while we’re at it:

component.toml

name = "myapp"
version = "0.1.0"

[build.dev]
build = "wit-bindgen c wit/ --world proxy --out-dir bindings && clang --target=wasm32-wasip2 -nostdlib '-Wl,--no-entry' '-Wl,--export-all' -o ctest.wasm app.c bindings/proxy.c bindings/proxy_component_type.o %%WASI_SDK_PATH%%/share/wasi-sysroot/lib/wasm32-wasip2/libc.a"
wasm_path = "ctest.wasm"

[build.prod]
build = "wit-bindgen c wit/ --world proxy --out-dir bindings && clang --target=wasm32-wasip2 -nostdlib -g0 '-Wl,--strip-all' '-Wl,--no-entry' '-Wl,--export-all' -o ctest.wasm app.c bindings/proxy.c bindings/proxy_component_type.o %%WASI_SDK_PATH%%/share/wasi-sysroot/lib/wasm32-wasip2/libc.a"
wasm_path = "ctest.wasm"

[input.env]
HELLO_MESSAGE = { type = "String" }

While we’re at it we can change the HTTP method to POST, and set the path to a new value. Furthermore, we’ll set a value to the HELLO_MESSAGE environment variable:

application.toml

name = "myapp"
component_target = 'myapp:0.1.0'

[trigger.http]
type = 'http'
path = '/mypath'
path = '/myapp'
method = 'POST'
method = 'GET'

[env]
HELLO_MESSAGE = "Hi"

Finally, we’ll update the code to use the new environment variable, and modify our code to expect a JSON body, and return the combined value of the environment variable with the name passed in as plaintext. In this example we use jsmn.c for parsing json, use the library that suits your needs best:

app.c

#pragma warning(                                                               \
    disable : 4996) // getenv is unsafe but getenv_s is msvc specific
#include "bindings/proxy.h"
#include "jsmn.h"
#include <stdbool.h>
#include <stdint.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>

#define MAX_TOKENS 128

void set_string(proxy_string_t *ret, const char *str) {
ret->ptr = (uint8_t *)str;
ret->len = strlen(str);
}
void set_string_field(wasi_http_types_field_value_t *ret, const char *str) {
ret->ptr = (uint8_t *)str;
ret->len = strlen(str);
}
void set_bytes(proxy_list_u8_t *ret, const char *data) {
ret->ptr = (uint8_t *)data;
ret->len = strlen(data);
}

// Sends a response with the supplied status code, content type and message
// CAUTION! Do not malloc() the message, if it is malloc():ed it needs to be
// freed here which it is not
void send_response(wasi_http_types_own_response_outparam_t *response_out,
                int response_status_code, const char *content_type,
                const char *message) {

wasi_http_types_own_fields_t headers;
wasi_http_types_header_error_t headers_err;

proxy_list_tuple2_field_name_field_value_t entries;
entries.ptr = malloc(1 * sizeof(proxy_tuple2_field_name_field_value_t));
entries.len = 1;
set_string(&entries.ptr[0].f0, "Content-Type");
set_string_field(&entries.ptr[0].f1, content_type);

if (!wasi_http_types_static_fields_from_list(&entries, &headers,
                                            &headers_err)) {
    wasi_http_types_result_own_outgoing_response_error_code_t result = {
        .is_err = true, .val.err = headers_err.tag};
    wasi_http_types_static_response_outparam_set(*response_out, &result);
    wasi_http_types_fields_drop_own(headers);
    free(entries.ptr);
    return;
}

wasi_http_types_own_outgoing_response_t res =
    wasi_http_types_constructor_outgoing_response(headers);

wasi_http_types_status_code_t status_code = response_status_code;
wasi_http_types_method_outgoing_response_set_status_code(
    wasi_http_types_borrow_outgoing_response(res), status_code);

wasi_http_types_own_outgoing_body_t body;
if (!wasi_http_types_method_outgoing_response_body(
        wasi_http_types_borrow_outgoing_response(res), &body)) {
    wasi_http_types_result_own_outgoing_response_error_code_t result = {
        .is_err = true, .val.err = WASI_HTTP_TYPES_ERROR_CODE_INTERNAL_ERROR};
    wasi_http_types_static_response_outparam_set(*response_out, &result);
    wasi_http_types_outgoing_response_drop_own(res);
    free(entries.ptr);
    return;
}

wasi_http_types_own_output_stream_t out_body_stream;
if (!wasi_http_types_method_outgoing_body_write(
        wasi_http_types_borrow_outgoing_body(body), &out_body_stream)) {
    wasi_http_types_result_own_outgoing_response_error_code_t result = {
        .is_err = true, .val.err = WASI_HTTP_TYPES_ERROR_CODE_INTERNAL_ERROR};
    wasi_http_types_static_response_outparam_set(*response_out, &result);
    wasi_http_types_outgoing_body_drop_own(body);
    wasi_http_types_outgoing_response_drop_own(res);
    free(entries.ptr);
    return;
}

wasi_io_streams_stream_error_t stream_err;
proxy_list_u8_t body_contents;
set_bytes(&body_contents, message);

if (!wasi_io_streams_method_output_stream_blocking_write_and_flush(
        wasi_io_streams_borrow_output_stream(out_body_stream), &body_contents,
        &stream_err)) {
    wasi_http_types_result_own_outgoing_response_error_code_t result = {
        .is_err = true, .val.err = stream_err.tag};
    wasi_http_types_static_response_outparam_set(*response_out, &result);
    wasi_io_streams_output_stream_drop_own(out_body_stream);
    wasi_http_types_outgoing_body_drop_own(body);
    wasi_http_types_outgoing_response_drop_own(res);
    free(entries.ptr);
    return;
}

wasi_io_streams_output_stream_drop_own(out_body_stream);

wasi_http_types_error_code_t err;
if (!wasi_http_types_static_outgoing_body_finish(body, NULL, &err)) {
    wasi_http_types_result_own_outgoing_response_error_code_t result = {
        .is_err = true, .val.err = err.tag};
    wasi_http_types_static_response_outparam_set(*response_out, &result);
    wasi_http_types_outgoing_body_drop_own(body);
    wasi_http_types_outgoing_response_drop_own(res);
    free(entries.ptr);
    return;
}

wasi_http_types_result_own_outgoing_response_error_code_t result = {
    .is_err = false, .val.ok = res};
wasi_http_types_static_response_outparam_set(*response_out, &result);

free(entries.ptr);
return;
}

void exports_wasi_http_incoming_handler_handle(
    wasi_http_types_own_incoming_request_t request,
    wasi_http_types_own_response_outparam_t response_out) {

wasi_http_types_own_headers_t incoming_header =
    wasi_http_types_method_incoming_request_headers(
        wasi_http_types_borrow_incoming_request(request));
wasi_http_types_borrow_fields_t borrowed_headers =
    wasi_http_types_borrow_fields(incoming_header);

proxy_list_field_value_t content_type_header;
wasi_http_types_field_name_t content_type;
set_string(&content_type, "Content-Type");

wasi_http_types_method_fields_get(borrowed_headers, &content_type,
                                    &content_type_header);

const char *json_mime = "application/json";
size_t json_mime_len = strlen(json_mime);

bool found_application_json = false;

for (size_t i = 0; i < content_type_header.len; i++) {
    wasi_http_types_field_value_t val = content_type_header.ptr[i];
    if (val.len == json_mime_len &&
        memcmp(val.ptr, json_mime, json_mime_len) == 0) {
    found_application_json = true;
    break;
    }
}

if (!found_application_json) {
    send_response(&response_out, 500, "text/plain",
                "Missing header Content-Type: application/json");
    return;
}

wasi_http_types_own_incoming_body_t incoming_raw_body;
if (!wasi_http_types_method_incoming_request_consume(
        wasi_http_types_borrow_incoming_request(request),
        &incoming_raw_body)) {
    send_response(&response_out, 500, "text/plain",
                "wasi_http_types_method_incoming_request_consume was called "
                "multiple times");
    return;
}

wasi_http_types_own_input_stream_t incoming_body_stream;
if (!wasi_http_types_method_incoming_body_stream(
        wasi_http_types_borrow_incoming_body(incoming_raw_body),
        &incoming_body_stream)) {

    send_response(&response_out, 500, "text/plain",
                "wasi_http_types_method_incoming_body_stream was called "
                "multiple times");
    return;
}

bool eof = false;
uint8_t *incoming_body = NULL;
uint64_t len = 0;
size_t capacity = 1024;

while (!eof) {
    if (len >= capacity) {
    capacity *= 2;
    incoming_body = realloc(incoming_body, capacity);
    if (!incoming_body) {
        send_response(&response_out, 500, "text/plain", "realloc failed");
        return;
    }
    }
    proxy_list_u8_t chunk;
    wasi_io_streams_stream_error_t stream_err;
    if (wasi_io_streams_method_input_stream_blocking_read(
            wasi_io_streams_borrow_input_stream(incoming_body_stream), 1024,
            &chunk, &stream_err)) {
    len += chunk.len;
    uint8_t *buf = realloc(incoming_body, len);

    if (!buf) {
        proxy_list_u8_free(&chunk);
        wasi_io_streams_input_stream_drop_own(incoming_body_stream);
        wasi_http_types_incoming_body_drop_own(incoming_raw_body);
        send_response(&response_out, 500, "text/plain", "realloc failed");
        return;
    }

    incoming_body = buf;

    memcpy(incoming_body + len - chunk.len, chunk.ptr, chunk.len);
    } else {
    if (stream_err.tag == WASI_IO_STREAMS_STREAM_ERROR_CLOSED) {
        eof = true;
    } else {
        wasi_io_streams_input_stream_drop_own(incoming_body_stream);
        wasi_http_types_incoming_body_drop_own(incoming_raw_body);
        send_response(&response_out, 500, "text/plain",
                    "failed to read body stream");

        return;
    }
    }
    proxy_list_u8_free(&chunk);
}

if (len == 0) {
    wasi_io_streams_input_stream_drop_own(incoming_body_stream);
    wasi_http_types_incoming_body_drop_own(incoming_raw_body);
    send_response(&response_out, 400, "text/plain", "Empty body received");
    free(incoming_body);
    return;
}

char *json_string = malloc(len + 1);
memcpy(json_string, incoming_body, len);
json_string[len] = '\0';

jsmn_parser parser;
jsmn_init(&parser);

jsmntok_t tokens[MAX_TOKENS];

// Parse JSON
int token_count =
    jsmn_parse(&parser, json_string, strlen(json_string), tokens, MAX_TOKENS);

if (token_count <= 0) {
    wasi_io_streams_input_stream_drop_own(incoming_body_stream);
    wasi_http_types_incoming_body_drop_own(incoming_raw_body);
    send_response(&response_out, 500, "text/plain",
                "No json was found in body");
    free(incoming_body);
    free(json_string);
    return;
}

char name[64] = {0};
for (int i = 1; i < token_count - 1; i++) {
    if (tokens[i].type == JSMN_STRING && tokens[i].end - tokens[i].start == 4 &&
        strncmp(json_string + tokens[i].start, "name", 4) == 0) {

    jsmntok_t val = tokens[i + 1];
    int len = val.end - val.start;

    if (len >= sizeof(name))
        len = sizeof(name) - 1;

    memcpy(name, json_string + val.start, len);
    name[len] = '\0';
    break;
    }

    i++;
}

char dest[64];
const char *raw = getenv("HELLO_MESSAGE");
if (raw) {
    strncpy(dest, raw, sizeof(dest) - 1);
    dest[sizeof(dest) - 1] = '\0';
} else {
    send_response(&response_out, 400, "text/plain",
                "No environment variable 'HELLO_MESSAGE' was found");
    return;
}

size_t response_length = strlen(dest) + 1 + strlen(name) + 1;
char *response = malloc(response_length);
snprintf(response, response_length, "%s %s", dest, name);

size_t dest_len = strlen(dest);
char *dest_compacted = malloc(dest_len + 1);

if (dest_compacted) {
    memcpy(dest_compacted, dest, dest_len + 1);
}

send_response(&response_out, 200, "text/plain", response);
free(response);
free(dest_compacted);
free(json_string);
return;
}

Since the runtime is already running, we just need to build and deploy the application again, for our changes to take effect.

heim@system:~/repos$ heim deploy
INFO [ Heim::Deploy ] Building Component: myapp
Generating "bindings\\proxy.c"
Generating "bindings\\proxy.h"
Generating "bindings\\proxy_component_type.o"
INFO [ heim_registry::registry ] "myapp":"0.1.0":c1e2ecbd72a7da32df056ef07e9e23448ee7c58022c07f8d14f5d98577f1615f
INFO [ Heim::Deploy ] Heim application `myapp` is now built and written to registry.
INFO [ Heim::Pipeline ] Starting pipeline 'Deploy application'
INFO [ Heim::Pipeline ] Storing unoptimized component state
INFO [ Heim::Pipeline ] Checking if defined regions in app definition is valid
INFO [ Heim::Pipeline ] Continuing with localhost region heim-localhost
INFO [ Heim::Pipeline ] Getting region specific application environment values
INFO [ Heim::Pipeline ] Set environment values for region 'heim-localhost'
INFO [ Heim::Pipeline ] Getting region specific application scaling values
INFO [ Heim::Pipeline ] Set scaling values for region 'heim-localhost'
INFO [ Heim::Pipeline ] Getting capabilities
INFO [ Heim::Pipeline ] Set capabilities values for region 'heim-localhost'
INFO [ Heim::Pipeline ] Getting triggers
INFO [ Heim::Pipeline ] Set trigger values for region 'heim-localhost'
INFO [ Heim::Pipeline ] Component environment values are valid for all regions
INFO [ Heim::Pipeline ] Checking for region with changes to build
INFO [ Heim::Pipeline ] Region "heim-localhost" has been changed and will be built
INFO [ Heim::Pipeline ] Storing component and optimized component
INFO [ Heim::Pipeline ] Stored component at ''
INFO [ Heim::Pipeline ] Stored optimized component at ''
INFO [ Heim::Pipeline ] Storing region states
INFO [ Heim::Pipeline ] Stored state for region(s) heim-localhost successfully
INFO [ Heim::Pipeline ] Creating and caching application(s)
INFO [ Heim::Pipeline ] Creating and caching application(s) for region(s) heim-localhost
INFO [ Heim::Pipeline ] Created application with hash d318a4a431b1376c9a729f3968ae0a303e1d27a89f1dcaf49c7c761e42852c6a for region(s) heim-localhost
INFO [ Heim::Pipeline ] Application has been deployed for region(s) heim-localhost
INFO [ Heim::Pipeline ] Pipeline 'Deploy application' finished with status 'Success'
INFO [ Heim::Deploy ] Heim deploy pipeline was successful
INFO [ Heim::Deploy ] Application is accaccessible at:
INFO [ Heim::Deploy ] [POST] http://127.0.0.1:3000/mypath
INFO [ Heim::Deploy ] Written and deployed application `myapp`.

heim@system:~/repos$ curl.exe http://127.0.0.1:3000/mypath -X POST
Missing header Content-Type: application/json
heim@system:~/repos$ curl.exe -X POST "http://127.0.0.1:3000/mypath" -H "Content-Type: application/json"
Empty body received
heim@system:~/repos$ curl.exe -X POST "http://127.0.0.1:3000/mypath" -H "Content-Type: application/json" -d '{\"name\":\"Heim\"}'
Hi Heim

When we are done, we can use the shortcut Ctrl+C to shut down the runtime.

To clean up any resources from the guide you can run heim clear. This will remove all data from the cache.

You will need to redeploy the application the next time you want to run it, if you use the heim clear command.
The full code is available in our Github repository here

Summary

- run heim new
- select the c-http template
- choose HTTP method
- choose trigger path
- set application name
- open the created application folder/project in your text editor
Take note of the configuration files:

component.toml defines a component.
An application is made up by one or more components.

application.toml defines an application.
- open app.c:
app.c contains boilerplate source code for your application.
- run heim start to start the Heim runtime
The Heim portal comes included with a Heim installation.
Once the Heim runtime is started, the Heim portal is available on http://127.0.0.1:3000/heim/portal/.
- run heim deploy to build and deploy the application.
The heim deploy --release creates a release build.
Just type heim deploy to create a development build.
- run heim deploy --cloud to deploy the application to the cloud instance.
The application is accessible on:
http://127.0.0.1:3000/${application_path}

The Heim runtime will print out relevant information about the application.
- edit the component.toml file to add environment variables
- edit the application.toml file to change the HTTP method
- edit the application.toml file to change the trigger path
- edit the application.toml file to set environment variable values
- edit the app.c file to use new environment variables
- edit the app.c file to set up return and accept values
- deploy the application again to see your changes
- use the Ctrl+C shortcut to shut down the Heim runtime
- use the heim clear command to remove all data from cache
You will need to redeploy the application the next time you want to run it, if you use the heim clear command.

Basic C Application

Prerequisites

Guide

component.toml

application.toml

Summary

References