sdk

README

Tarmac SDK (Go) 🛠️

A tiny, testable Go SDK for Tarmac WebAssembly functions.

---

🧠 What is Tarmac SDK (Go)?

A minimal Go library for building Tarmac guest functions.

A key feature of this SDK is its testability. You can use the included mock clients or create your own. You can also use the low-level hostmock to simulate hostcalls to Tarmac if you want to get really deep into testing.

---

🚀 Getting Started

Register your handler with the SDK:

package main

import (
  "github.com/tarmac-project/sdk"
)

func main() {
  _, err := sdk.New(sdk.Config{
    Namespace: "tarmac", // optional; defaults to "tarmac"
    Handler: func(b []byte) ([]byte, error) {
      // Your function logic here
      return b, nil
    },
  })
  if err != nil {
    panic(err)
  }
}

---

🧱 Structure

The project is organized into focused modules so you can depend only on what you need.

Module/Path	Description	Docs
sdk	Core runtime config and handler registration	https://pkg.go.dev/github.com/tarmac-project/sdk
sdk/http	HTTP client	https://pkg.go.dev/github.com/tarmac-project/sdk/http
sdk/http/mock	Lightweight HTTP client mock for tests	https://pkg.go.dev/github.com/tarmac-project/sdk/http/mock
sdk/hostmock	Low-level host-call simulator for assertions	https://pkg.go.dev/github.com/tarmac-project/sdk/hostmock

---

🤝 Contributing

PRs welcome! Please open an issue to discuss changes.

---

📄 License

Apache-2.0 — see LICENSE.

---

🌴 Stay Tiny, Ship Fast!

Questions, ideas, or rough edges? Open an issue or PR — we’d love to hear from you.

Documentation

Overview

Package sdk provides the core entry point and runtime configuration for building Tarmac WebAssembly functions.

The package exposes New to register a waPC handler and a RuntimeConfig that is shared by capability clients (e.g., HTTP). DefaultNamespace is used when a namespace is not explicitly provided.

Index

• Constants
• Variables
• type Config
• type RuntimeConfig
• type SDK
  • func New(config Config) (*SDK, error)
  • func (s *SDK) Config() RuntimeConfig

Constants

const DefaultNamespace = "tarmac"

DefaultNamespace is used when no explicit namespace is provided.

Variables

var (
	// ErrHandlerNil is returned when the provided function handler is nil.
	ErrHandlerNil = fmt.Errorf("function handler cannot be nil")
)

Types

type Config

type Config struct {
	// Namespace controls the function namespace to use for host callbacks.
	// If empty, DefaultNamespace is used.
	Namespace string

	// Handler is the function to be registered as the main WebAssembly entry point.
	Handler func([]byte) ([]byte, error)
}

Config provides configuration options for SDK initialization.

type RuntimeConfig

type RuntimeConfig struct {
	// Namespace is the function namespace used to scope host interactions.
	Namespace string
}

RuntimeConfig carries configuration that is used during creation of SDK components.

type SDK

type SDK struct {
	// contains filtered or unexported fields
}

SDK represents the initialized runtime with a registered waPC handler.

func New

func New(config Config) (*SDK, error)

New initializes the SDK and registers the handler with waPC.

func (*SDK) Config

func (s *SDK) Config() RuntimeConfig

Config returns the current runtime configuration snapshot.