{"id":13412650,"url":"https://github.com/tarmac-project/tarmac","last_synced_at":"2025-04-05T19:11:40.955Z","repository":{"id":38344518,"uuid":"370855322","full_name":"tarmac-project/tarmac","owner":"tarmac-project","description":"Write as Functions, Deploy as a Monolith or Microservice with WebAssembly","archived":false,"fork":false,"pushed_at":"2024-07-26T15:38:57.000Z","size":7441,"stargazers_count":324,"open_issues_count":4,"forks_count":16,"subscribers_count":9,"default_branch":"main","last_synced_at":"2024-07-31T20:51:14.433Z","etag":null,"topics":["functions-as-a-service","golang","microservice-framework","serverless","wasi","wasm"],"latest_commit_sha":null,"homepage":"https://tarmac.gitbook.io/tarmac-framework/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tarmac-project.png","metadata":{"files":{"readme":"docs/README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-05-25T23:45:12.000Z","updated_at":"2024-07-30T07:24:50.000Z","dependencies_parsed_at":"2023-11-01T04:22:49.785Z","dependency_job_id":"c9b3d86a-2a80-4a25-9453-ebe552fda455","html_url":"https://github.com/tarmac-project/tarmac","commit_stats":null,"previous_names":["tarmac-project/tarmac","madflojo/tarmac"],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tarmac-project%2Ftarmac","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tarmac-project%2Ftarmac/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tarmac-project%2Ftarmac/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tarmac-project%2Ftarmac/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tarmac-project","download_url":"https://codeload.github.com/tarmac-project/tarmac/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247386265,"owners_count":20930619,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["functions-as-a-service","golang","microservice-framework","serverless","wasi","wasm"],"created_at":"2024-07-30T20:01:27.307Z","updated_at":"2025-04-05T19:11:40.931Z","avatar_url":"https://github.com/tarmac-project.png","language":"Go","funding_links":[],"categories":["Go","Distributed Systems","分布式系统"],"sub_categories":["Search and Analytic Databases","检索及分析资料库"],"readme":"# Tarmac\n\n![Tarmac Banner](tarmac-banner.png)\n\n[![PkgGoDev](https://pkg.go.dev/badge/github.com/tarmac-project/tarmac/pkg/sdk)](https://pkg.go.dev/github.com/tarmac-project/tarmac/pkg/sdk)\n[![Documentation](https://img.shields.io/badge/docs-latest-blue)](https://tarmac.gitbook.io/tarmac/)\n[![Build Status](https://github.com/tarmac-project/tarmac/actions/workflows/build.yml/badge.svg)](https://github.com/tarmac-project/tarmac/actions/workflows/build.yml)\n[![Go Report Card](https://goreportcard.com/badge/github.com/tarmac-project/tarmac)](https://goreportcard.com/report/github.com/tarmac-project/tarmac)\n[![codecov](https://codecov.io/gh/tarmac-project/tarmac/graph/badge.svg?token=15WYYOWVCE)](https://codecov.io/gh/tarmac-project/tarmac)\n\n## Framework for writing functions, microservices, or monoliths with Web Assembly\n\nTarmac 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.\n\nSupporting languages like Go, Rust, \u0026 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.\n\n## Quick Start\n\nTarmac makes it easy to get started with building complex functions. The below function (written in Go) is an excellent example of its simplicity.\n\n```go\n// Tac is a small, simple Go program that is an example WASM module for Tarmac. This program will accept a Tarmac\n// server request, log it, and echo back the payload in reverse.\npackage main\n\nimport (\n\t\"fmt\"\n\t\"github.com/tarmac-project/tarmac/pkg/sdk\"\n)\n\nvar tarmac *sdk.Tarmac\n\nfunc main() {\n\tvar err error\n\n\t// Initialize the Tarmac SDK\n\ttarmac, err = sdk.New(sdk.Config{Handler: Handler})\n\tif err != nil {\n\t\treturn\n\t}\n}\n\n// Handler is the custom Tarmac Handler function that will receive a payload and\n// must return a payload along with a nil error.\nfunc Handler(payload []byte) ([]byte, error) {\n\tvar err error\n\n\t// Log it\n\ttarmac.Logger.Trace(fmt.Sprintf(\"Reversing Payload: %s\", payload))\n\n\t// Check Cache\n\tkey := string(payload)\n\trsp, err := tarmac.KV.Get(key)\n\tif err != nil || len(payload) \u003c 1 {\n\t\t// Flip it and reverse\n\t\tif len(payload) \u003e 0 {\n\t\t\tfor i, n := 0, len(payload)-1; i \u003c n; i, n = i+1, n-1 {\n\t\t\t\tpayload[i], payload[n] = payload[n], payload[i]\n\t\t\t}\n\t\t}\n\t\trsp = payload\n\n\t\t// Store in Cache\n\t\terr = tarmac.KV.Set(key, payload)\n\t\tif err != nil {\n\t\t\ttarmac.Logger.Error(fmt.Sprintf(\"Unable to cache reversed payload: %s\", err))\n\t\t\treturn rsp, nil\n\t\t}\n\t}\n\n\t// Return the payload\n\treturn rsp, nil\n}\n```\n\nTo 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.\n\n```text\n$ cd example/tac/go\n$ make build\n```\n\nOnce compiled, you can run this function as a standalone microservice using the following Docker command.\n\n```text\n$ docker run -p 8080:8080 \\\n  -e \"APP_ENABLE_TLS=false\" -e \"APP_LISTEN_ADDR=0.0.0.0:8080\" \\\n  -v `pwd`/functions:/functions madflojo/tarmac\n```\n\nWith Tarmac now running, we can access our WASM function using any HTTP Client such as `curl`.\n\n```text\n$ curl -v --data \"Tarmac Example\" http://localhost:8080\n```\n\nThat's it! You can write and deploy functions in Go, Rust, AssemblyScript, Swift, or Zig with Tarmac. For more advanced functions, check out our [developer guides](https://tarmac.gitbook.io/tarmac/wasm-functions/go).\n\n## Multi-Function Services\n\nWhile 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.\n\nTo 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.\n\n```json\n{\n  \"services\": {\n    \"my-service\": {\n      \"name\": \"my-service\",\n      \"functions\": {\n        \"function1\": {\n          \"filepath\": \"/path/to/function1.wasm\"\n        },\n        \"function2\": {\n          \"filepath\": \"/path/to/function2.wasm\"\n        }\n      },\n      \"routes\": [\n        {\n          \"type\": \"http\",\n          \"path\": \"/function1\",\n          \"methods\": [\"GET\"],\n          \"function\": \"function1\"\n        },\n        {\n          \"type\": \"http\",\n          \"path\": \"/function2\",\n          \"methods\": [\"POST\"],\n          \"function\": \"function2\"\n        }\n      ]\n    }\n  }\n}\n```\n\nEach function has its own code base but shares the same service namespace and configurations in a multi-function service configuration.\n\nIn 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`.\n\nTo 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.\n\nIn 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).\n\n```json\n{\n  \"type\": \"scheduled_task\",\n  \"function\": \"function1\",\n  \"frequency\": 10\n}\n```\n\nWith Tarmac's support for multiple functions, you can quickly build complex, distributed services by dividing your service into smaller, more manageable pieces.\n\n## Architecture\n\nTarmac 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).\n\nBy 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.\n\nTo 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.\n\n### Example Application Architecture\n\nThe below diagram shows the architecture of an [example application](https://github.com/tarmac-project/example-airport-lookup-go/tree/main). This application demonstrates how to build a multi-function service with Tarmac using Go.\n\nThis 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.\n\n```text\n          +-------------------------------------------------------------------------------------------------------+                                 \n          | Tarmac Host                                                                                           |                                 \n          |                                       +------------------------------------------------------------+  |                                 \n          |                                       | WebAssembly Engine                                         |  |                                 \n          |                                       |                                                            |  |                                 \n          |  +------------------------+           |  +-----------------------------------+                     |  |                                 \n          |  |On Boot Function Trigger+-----------+--\u003eInit: Creates DB Tables, Calls Load|                     |  |                                 \n          |  +------------------------+           |  +--+--------------------------------+                     |  |                                 \n          |                                       |     |                                                      |  |                                 \n          |  +--------------------------+         |  +--v---------------------------------------------------+  |  |                                 \n          |  |Scheduled Function Trigger+---------+--\u003e Load: Calls Fetch, then loads results to SQL Database|  |  |                                 \n          |  +--------------------------+         |  +--+---------------------------------------------------+  |  |                                 \n          |                                       |     |                                                      |  |                                 \n          |                                       |  +--v-----------------------------+                        |  |  +-----------------------------+\n          |                                       |  | Fetch: Download AirportData.csv+------------------------+--+--\u003eHTTP Server: AirportData.csv |\n          |                                       |  +--------------------------------+                        |  |  +-----------------------------+\n          |                                       |                                                            |  |                                 \n+------+  |  +--------------------+               |  +----------------------------------+                      |  |                                 \n|Client+--+--\u003eHTTP Request Handler+---------------+--\u003eLookup: Fetches Data from Cache/DB|                      |  |                                 \n+------+  |  +--------------------+               |  +----------------------------------+                      |  |                                 \n          |                                       |                                                            |  |                                 \n          |                                       +----------------------------+-------------------------------+  |                                 \n          |                                                                    |                                  |                                 \n          |                                                                    |                                  |                                 \n          |                                                                    |                                  |                                 \n          |                                       +----------------------------v-------------------------------+  |                                 \n          |                                       | Tarmac Capabilities                                        |  |                                 \n          |                                       |                                                            |  |                                 \n          |                                       | +--------+ +------------+ +-------+ +------+               |  |                                 \n          |                                       | |KV Store| |SQL Database| |Metrics| |Logger|               |  |                                 \n          |                                       | +--------+ +------------+ +-------+ +------+               |  |                                 \n          |                                       |                                                            |  |                                 \n          |                                       +------------------------------------------------------------+  |                                 \n          |                                                                                                       |                                 \n          +-------------------------------------------------+-----------------------------------------------------+                                 \n                                                            |                                                                                       \n          +-------------------------------------------------v-----------------------------------------------------+                                 \n          | External Services (Not all used in Example Application)                                               |                                 \n          |                                                                                                       |                                 \n          | +------+ +----------+ +-----+ +-----+ +----------+ +---------+                                        |                                 \n          | |Consul| |Prometheus| |Redis| |MySQL| |PostgreSQL| |Cassandra|                                        |                                 \n          | +------+ +----------+ +-----+ +-----+ +----------+ +---------+                                        |                                 \n          |                                                                                                       |                                 \n          +-------------------------------------------------------------------------------------------------------+                                 \n```\n\n\n| Language | waPC Client | Tarmac SDK |\n| :--- | :--- | :--- |\n| AssemblyScript | ✅ | |\n| Go | ✅ | ✅ |\n| Rust | ✅ | |\n| Swift | ✅ | |\n| Zig | ✅ | |\n\n## Contributing\n\nWe 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.\n\n### Project Contributors\n\n\u003ca href=\"https://github.com/tarmac-project/tarmac/graphs/contributors\"\u003e\n  \u003cimg src=\"https://contrib.rocks/image?repo=tarmac-project/tarmac\" /\u003e\n\u003c/a\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftarmac-project%2Ftarmac","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftarmac-project%2Ftarmac","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftarmac-project%2Ftarmac/lists"}