Framework for writing functions, microservices, or monoliths with Web Assembly

Tarmac is a new approach to application frameworks. Tarmac is language agnostic and offers built-in support for key/value stores like BoltDB, Redis, and Cassandra, traditional SQL databases like MySQL and Postgres, and fundamental capabilities like mutual TLS authentication and observability.

Supporting languages like Go, Rust, & Zig, you can focus on writing your functions in whatever language you like while benefiting from a robust suite of capabilities for building modern distributed services.

Quick Start

Tarmac makes it easy to get started with building complex functions. The below function (written in Go) is an excellent example of its simplicity.

To start running this function, navigate to our examples directory and run the make build command. The make build command compiles the code and generates a WebAssembly module.

Once compiled, you can run this function as a standalone microservice using the following Docker command.

With Tarmac now running, we can access our WASM function using any HTTP Client such as curl.

That's it! You can write and deploy functions in Go, Rust, AssemblyScript, Swift, or Zig with Tarmac. For more advanced functions, check out our .

Multi-Function Services

While users of Tarmac can build standalone microservices with a single function quickly, it shines with multi-function services. Tarmac's ability to run multiple functions means you can create purpose-built platforms with the developer experience of serverless functions.

To get started with multi-function services, you must provide a tarmac.json configuration file (via the WASM_FUNCTION_CONFIG configuration parameter) that lists the Functions to load and the various protocols and routes to expose as endpoints. Below is a sample tarmac.json configuration file.

Each function has its own code base but shares the same service namespace and configurations in a multi-function service configuration.

In the example above, we have a service named my-service with function1 and function2 functions. Each function has a .wasm file at /path/to/function1.wasm and /path/to/function2.wasm.

To define the routes for each function, add a route object to the routes array with the type set to http and the function set to the function's name.

In addition to the http route type, Tarmac also supports scheduled_task routes that execute a function at a specific interval. The frequency parameter specifies the interval (in seconds).

With Tarmac's support for multiple functions, you can quickly build complex, distributed services by dividing your service into smaller, more manageable pieces.

Architecture

Tarmac is a serverless platform that enables users to define and execute WebAssembly Functions. When Tarmac receives requests, it forwards them to WebAssembly Functions, which act as request handlers. The communication between Tarmac and WebAssembly Functions is via WebAssembly Procedure Calls (waPC).

By leveraging waPC, WebAssembly Functions can interact with Tarmac's core capabilities. Capabilities include performing callbacks to the Tarmac server to access key-value stores, interact with SQL databases, or make HTTP requests to downstream services.

To provide a streamlined developer experience, Tarmac offers a Go SDK that simplifies the usage of waPC. The SDK abstracts away the complexity of using waPC, allowing developers to focus on writing their functions and leveraging Tarmac's features.

Example Application Architecture

The below diagram shows the architecture of an . This application demonstrates how to build a multi-function service with Tarmac using Go.

This example application will execute WebAssembly functions on boot and via a scheduler to manage airport data. The application also includes an HTTP server that serves the airport data to clients via a WebAssembly function.

Contributing

We are thrilled that you are interested in contributing to Tarmac and helping to make it even better! To get started, please check out our contributing guide for information on how to submit bug reports, feature requests, and code contributions.

Project Contributors

Web Assembly (WASM) support is a first-class feature in Rust, making Rust an excellent language to write WASM functions for Tarmac.

This guide will walk users through creating a WASM function for Tarmac in the Rust language. This walkthrough assumes there is some familiarity with the Rust tooling and language to start.

Creating the WASM Function

We will need to begin with a new project folder, creating the src/ directory. Within that directory, we will make our main.rs file.

Tarmac internally uses a Web Assembly Procedure Calls (waPC) runtime, which means all WASM functions running within Tarmac must import and use a waPC compliant library.

Along with the waPC imports, you should also see a wapc_init() function created. This function is the primary entry point for Tarmac execution. We will register our handler function for Tarmac to execute using the register_function() function within this function.

In the example above, we have registered the handler() function. When Tarmac receives an HTTP POST request for this WASM function, it will execute the handler function as defined.

With our handler function now registered, we must create a basic version of this handler for Tarmac to call.

As we can see from the example above, the handler input a slice of 8-bit unsigned integers, which is the raw HTTP payload. And a return value of CallResult.

Adding Logic

Now that we have the basic structure of our WASM function created, we can start adding logic to the function and process our request.

Host Callbacks

One of the unique benefits of Tarmac is the ability for WASM functions to perform host callbacks to the Tarmac service itself. These Host Callbacks give users the ability to execute common framework code provided to the WASM function by Tarmac. These common framework functions can include storing data within a database, calling a remote API, or logging data.

For our example, we will use the Host Callbacks to create a Trace log entry.

For a full list of Host Callbacks checkout the documentation.

Do Work and Generate a Response

We can add our logic to the example, which in this case will just return the input payload.

Full WASM function

For quick reference, the below code is the full WASM function from this example.

Building the WASM Function

Now that our function is ready, we must compile our Rust code into a .wasm file. To do this, we will need to create our Cargo manifest and build the project.

Within the Cargo.toml file, we must specify the different packages used in our WASM function.

With our manifest defined, we can now build our module.

After the code build completes, we will copy the .wasm file into a directory Tarmac can use to run.

Running the WASM Function

We are now ready to run our WASM function via Tarmac. To make this process easier, we will be using Docker to execute Tarmac. It is not necessary to use Docker with Tarmac as it can run outside of Docker as well.

In the above command, we pass two environment variables to the container using the -e flag. These environment variables will tell Tarmac to use HTTP rather than HTTPS, which is the default. For additional configuration options, check out the documentation.

With Tarmac now running, we can access our WASM function using any HTTP Client such as curl.

Conclusion

Developers can use this guide to get started with WASM functions and using Tarmac. Some of the information in this guide is subject to change as WASM advances. However, the concepts should stay pretty consistent.

Tarmac, at its core, is powered by the Web Assembly Procedure Call (waPC) Project. The Web Assembly Procedure Call Project defines imported and exported functions between a WASM host and a guest WASM function. A WASM runtime host like Tarmac and a WASM Function running within Tarmac can communicate back and forth using these functions.

A prime example of this is the HostCall() function used by guest WASM functions. This HostCall() is a callback function that enables WASM functions to pass back data to the Tarmac host for the explicit goal of executing host-level functionality.

This ability to perform a Host Callback is what sets Tarmac apart from most other serverless runtimes. A WASM function can use the Host Callback functionality to access a full suite of standard functionality that would traditionally be too heavy for a serverless function.

Essentially, Host Callbacks allow Tarmac to provide developers the functionality of a standard Microservice Framework along with the convenience of a serverless runtime.

Using Host Callbacks

Calling a Host Callback is relatively straightforward for WASM functions. As outlined in the language guides, each WASM function must import a waPC compliant guest library. This guest library will allow users to access a HostCall() function for their language of choice.

The example below is an example of calling the Host Callback function in Go.

The HostCall() function takes three parameters. The first is the namespace which developers should always set to tarmac. The second is the capability requested, such as logger or kvstore. The third is the function to execute; for a kvstore capability, we may want to perform a get or a set.

This section of documentation outlines all of the various host-level capabilities Tarmac provides. Each unit will outline the capabilities, functions, and input/output data.

The Functions capability allows WASM functions to call other WASM functions. Unlike other callback capabilities, functions must register within the routes configuration within the tarmac.json configuration file.

Function

_, err := wapc.HostCall("tarmac", "function", "function-name", []byte("Input to Function"))

Interface Details

Configuring Multi-Function Services is a core capability of Tarmac. To do so, we will create a tarmac.json file that defines Functions and Routes to expose those functions.

By default, Tarmac looks within the /functions/ directory for a tarmac.json; however this can be overridden using the WASM_FUNCTION_CONFIG configuration parameter.

The tarmac.json file has a simple structure that consists of a single object with a services key. The services key defines each service and its corresponding functions and routes.

Configuration Options

Services

The services object contains one or more key-value pairs, with each key representing the name of a service.

Each service object should include the following properties:

• name: The name of the service (required).

• functions: An object containing the functions for the service (required).

• routes: An array of objects defining the routes for the service (required).

Functions

The functions object contains one or more key-value pairs, with each key representing the name of a function.

Each function object should include the following properties:

• filepath: The file path to the .wasm file containing the function code (required).

• pool_size: The number of instances of the function to create (optional). Defaults to 100.

Routes

The "routes" property in the tarmac.json configuration file defines the endpoints (HTTP or scheduled task) of the service and maps them to their respective functions.

HTTP Routes

The routes array in the tarmac.json configuration file defines the HTTP endpoints for your service.

Each route object contains the following properties:

• type (required): For HTTP routes, set this to http.

• path (required): The URL path for the endpoint.

• methods (required): An array of HTTP methods that the endpoint supports (i.e. GET

Here is an example of a route object that defines an HTTP endpoint that responds to GET requests on the root path and calls the default function:

You can define multiple HTTP routes in the routes array.

Scheduled Tasks

In addition to HTTP endpoints, Tarmac also supports scheduled tasks.

You can define a scheduled task route by adding a route object with the following properties to the routes array:

• type (required): For Schedule Tasks, set to scheduled_task.

• function (required): The function to call when the task is executed.

• frequency (required): The frequency in seconds to execute the function.

Here is an example of a route object that defines a scheduled task that executes the default function every 15 seconds:

You can define multiple scheduled tasks in the routes array.

Init Functions

In addition to HTTP and scheduled task routes, Tarmac also supports init functions.

You can define an init function route by adding a route object with the following properties to the routes array:

• type (required): For Init Functions, set to init.

• function (required): The function to call when the service is initialized.

• retries (optional): The number of times to retry the function if it fails. Defaults to 0.

Here is an example of a route object that defines an init function that executes the default function when the service is initialized:

You can define multiple init functions in the routes array. Functions will be executed before the server is fully started but after the WASM modules are loaded and callbacks are registered.

Functions

Tarmac supports the ability for Functions to call other Functions using the Function to Function route.

You can define a function route by adding a route object with the following properties to the route array.

• type (required): For Function to Function routes, set to function.

• function (required): The function to call when executed.

Here is an example of a route object that defines the "function1" function.

Tarmac leverages the Web Assembly System Interface (WASI), which is currently only supported by TinyGo. While TinyGo has many features, there are some limitations to its support.

However, thanks to the Go SDK, writing Tarmac functions is quick and easy. This guide will walk users through creating a simple function using Go.

Basic WASM function

We will first need to begin with a new project folder creating a main.go file within it. This file will hold all of our application logic.

Within our main.go file; we will need first to import the Tarmac Go SDK.

Once we've imported the SDK, we will need to both create our Function and register it with the SDK. We will start by initializing the SDK and registering our Function, Handler().

As Tarmac receives requests such as an HTTP POST request, the Handler() function will be called with the HTTP payload provided as the payload parameter.

We can create our Function, which returns a simple "Howdie" message.

Building the WASM Function

Now that our function is ready, we must compile our Go code into a .wasm file. To do this, we will be using TinyGo.

The first step above is using mkdir to create a functions directory, this is not required but will be helpful when running Tarmac in the next stage.

After the functions directory is created, we are using the tinygo command to build our .wasm file. The inclusion of -target wasi is important as it directs TinyGo to compile the Go code using the Web Assembly System Interface (wasi) standard. This standard is useful for running Web Assembly on the server vs. on the browser.

With this step complete, we have built our WASM function.

Running the WASM Function

We are now ready to run our WASM function via Tarmac. To make this process easier, we will be using Docker to execute Tarmac. It is not necessary to use Docker with Tarmac as it can run outside of Docker as well.

In the above command, we are passing two environment variables to the container using the -e flag. These environment variables will tell Tarmac to use HTTP rather than HTTPS, which is the default. For additional configuration options, check out the documentation.

With Tarmac now running, we can access our WASM function using any HTTP Client such as curl.

Expanding beyond Hello World

While the above Hello World example provides an excellent introduction to creating Go functions, it does not showcase the power of Tarmac.

Tarmac provides integrations with many of the capabilities required to build today's modern platforms. These capabilities include Key:Value datastores such as Redis or Cassandra. The ability to create metrics for observability and log messages via a structured logger. Or even the ability to call HTTP end-points with an HTTP Client.

These integrations are simple to call with the Go SDK; the below Function showcases several capabilities, such as calling a key:value cache and logging.

Conclusion

Developers can use this guide to get started with WASM functions and using Tarmac. Some of the information in this guide is subject to change as support for WASM in Go advances.

Currently, Tarmac leverages the Web Assembly Procedure Call (waPC) to interact and run WASM Functions. As such, Tarmac is limited to languages that support both Web Assembly and the waPC protocol.

The below table outlines languages that are fully supported.

The Metrics capability provides WASM function developers the ability to create user-defined metrics exposed as part of the Tarmac /metrics end-point. This capability supports the three predominant metrics types, Counters, Gauges, & Histograms.

Counter

The Counter function will give users the ability to create a custom counter metric. When called, this function will increment the counter by one.

Interface Details

Example JSON

This callback uses JSON messages as input and output to facilitate communications between WASM functions and the Tarmac host.

MetricsCounter

Gauge

The Gauge function will give users the ability to create a custom gauge metric. When called, this function will either increment or decrement the gauge by one.

Interface Details

Example JSON

This callback uses JSON messages as input and output to facilitate communications between WASM functions and the Tarmac host.

MetricsCounter

Valid actions are inc (Increment) and dec (Decrement).

Histogram

The Histogram function will give users the ability to create a custom histogram metric. When called, this function will observe the provided value and summarize the metric results.

Interface Details

Example JSON

This callback uses JSON messages as input and output to facilitate communications between WASM functions and the Tarmac host.

MetricsCounter

The HTTPClient capability provides WASM function developers to perform HTTP client requests to remote or local HTTP servers. While a simplistic client, Tarmac supports multiple HTTP requests, setting headers, and custom payloads.

Security and Resource Management

To prevent DoS attacks and excessive memory usage, HTTP response bodies are limited to a configurable maximum size. By default, responses are limited to 10MB. This limit can be configured service-wide using the http_client_max_response_body_size configuration parameter (see Configuration for details).

Call

The Call function provides users with the ability to make HTTP client requests to the specified URL. The body key within the request and response JSON will be base64 encoded to avoid conflicts.

Interface Details

Example JSON

This callback uses JSON messages as input and output to facilitate communications between WASM functions and the Tarmac host.

HTTPClient

HTTPClientResponse

The Status structure within the response JSON denotes the success of the database call. The status code value follows the HTTP status code standards, with anything higher than 399 is an error.

Note: Tarmac will provide a 200 status code if the HTTP request was successfully made, check the code value to validate the HTTP server return code.

Response Body Size Limiting

HTTP responses that exceed the configured maximum body size will be truncated to the limit. If the response body is larger than the configured limit, only the first bytes up to the limit will be included in the response. This behavior applies to both successful and error responses to ensure consistent resource management.

The Key:Value Store capability provides WASM function developers the ability to store and retrieve data from Key:Value datastores. At the moment, Tarmac supports multiple Key:Value stores which can be enabled/disabled in the host configuration settings.

Get

The Get function provides users with the ability to fetch data using the specified key. To avoid conflicts, the data key within the response, JSON, will be base64 encoded.

The Logger capability provides WASM functions with the ability to log arbitrary data. Much like a traditional logger framework, this capability offers multiple log levels.

By default Debug and Trace level logs are disabled. To enable these log levels to consult the configuration options for Tarmac.

Error

Critical errors within the system.

This page contains BoltDB specific configuration to utilize BoltDB with Tarmac.

Tarmac supports multiple configuration sources such as Environment Variables, JSON files, or using HashiCorp Consul. All of these configuration options can also exist together to provide both static and dynamic configurations.

When using Environment Variables, all configurations are prefixed with APP_. The list below will show both Environment and Consul/JSON format for configuration.

Consul Format

When using Consul the consul_keys_prefix should be the path to a key with a JSON string as the value. For example, a key of tarmac/config will have a value of {"from_consul":true}.

This page contains Cassandra specific configuration to utilize Cassandra with Tarmac.

Tarmac supports multiple configuration sources such as Environment Variables, JSON files, or using HashiCorp Consul. All of these configuration options can also exist together to provide both static and dynamic configurations.

When using Environment Variables, all configurations are prefixed with APP_. The list below will show both Environment and Consul/JSON format for configuration.

Tarmac has support for multiple Key:Value datastore storage systems. These datastores can change with basic configuration options within Tarmac. As a WASM Function developer, you do not need to know the underlying datastore when writing the function. Callbacks for accessing the Key:Value datastore are generic across all supported datastores.

To start using a Key:Value datastore, set the enable_kvstore configuration to true and specify which supported platform to use with the kvstore_type variable.

The below table outlines the different available options.

For more detailed configuration options, check out the documentation.

The SQL Datastore capability provides WASM function developers the ability to store and retrieve data from SQL datastores. At the moment, Tarmac supports multiple SQL stores which can be enabled/disabled in the host configuration settings.

Query

The Query function provides users with the ability to execute custom SQL queries against the database service. The returned data is in JSON format and base64 encoded to avoid format conflicts.

Interface Details

Example JSON

This callback uses JSON messages as input and output to facilitate communications between WASM functions and the Tarmac host.

SQLQuery

To avoid format and data conflicts the query itself must be base64 encoded.

SQLQueryResponse

To avoid format and data conflicts the data returned is base64 encoded.

The Status structure within the response JSON denotes the success of the database call. The status code value follows the HTTP status code standards, with anything higher than 399 is an error.

Tarmac has support for multiple SQL datastore storage systems. These datastores can change with basic configuration options within Tarmac. As a WASM Function developer, you do not need to know the underlying datastore when writing the function. Callbacks for accessing the SQL datastore are generic across all supported datastores.

To start using a SQL datastore, set the enable_sql configuration to true and specify which supported platform to use with the sqlstore_type variable.

The below table outlines the different available options.

For more detailed configuration options, check out the documentation.

This page contains Redis specific configuration to utilize Redis with Tarmac.

Tarmac supports multiple configuration sources such as Environment Variables, JSON files, or using HashiCorp Consul. All of these configuration options can also exist together to provide both static and dynamic configurations.

When using Environment Variables, all configurations are prefixed with APP_. The list below will show both Environment and Consul/JSON format for configuration.

Tarmac exposes several metrics to facilitate monitoring services. Metrics are available via the /metrics end-point in the Prometheus format.

These metrics include internal Tarmac system metrics such as the number of goroutines, memory utilization, and WASM function-specific metrics such as counters for Callbacks and WASM function execution time.

Some valuable metrics to monitor are in the below table.

Tarmac supports multiple configuration sources such as Environment Variables, JSON files, or using HashiCorp Consul. All of these configuration options can also exist together to provide both static and dynamic configurations.

When using Environment Variables, all configurations are prefixed with APP_. The list below will show both Environment and Consul/JSON format for configuration.

Consul Format

When using Consul the consul_keys_prefix should be the path to a key with a JSON string as the value. For example, a key of tarmac/config will have a value of {"from_consul":true}.

Tarmac uses structured logging to provide detailed information about system operations. By default, logs are output in JSON format, which is ideal for automated log processing and analysis tools.

Log Format

Administrators can control the format of Tarmac's logs:

• JSON Format (Default): Structured logging that's machine-readable and easily parsed by log aggregation tools

• Text Format: Human-readable plain text format that's easier to read in the console or log files

To use text format instead of JSON, set the text_log_format configuration option to true.

Controlling Log Levels

Administrators can control Tarmac's logging levels dynamically while using a distributed configuration service such as Consul. As a WASM Function developer, you can select which logging level you wish your log callbacks to use.

As an Administrator, you can choose to enable or disable dynamically certain log levels such as Debug or Trace. To do this, modify the debug and trace configuration options within Consul.

It is also possible to disable all logging by changing the disable_logging configuration option to true.

For more information on connecting Tarmac with Consul, consult our documentation.

Troubleshooting Performance Issues or Memory leaks within running services can be a complex task. Luckily, Tarmac uses the native Go tooling to create profiling snapshots of a running instance.

PProf is a Go tool for capturing and visualizing profiling data. Tarmac uses the net/http/pprof package to make PProf available via HTTP end-points.

By default, all PProf end-points are disabled, preventing unauthorized use of PProf (which itself can affect performance). To enable PProf, set the Configuration value of enable_pprof to true. Using a distributed configuration service such as Consul, users can change this value live without restarting the application instance.

Follow the Configuration guide for more details on configuring Tarmac.

Once enabled, users can use the following end-points to capture profiling data.

More information about PProf can be found via the .