github.com/Paca-AI/plugin-sdk-go — Backend
Go SDK for building Paca backend plugins compiled to WebAssembly (WASM).
Installation
go get github.com/Paca-AI/plugin-sdk-go
Quick Start
Every backend plugin must implement the Plugin interface and call plugin.Run in its main function.
//go:build wasip1
package main
import (
"fmt"
plugin "github.com/Paca-AI/plugin-sdk-go"
)
type myPlugin struct {
db *plugin.DB
log *plugin.Logger
}
func (p *myPlugin) Init(ctx *plugin.Context) error {
p.db = ctx.DB()
p.log = ctx.Log()
// Register HTTP routes
ctx.Route("GET", "/hello", p.sayHello)
// Subscribe to platform events
ctx.On("task.created", p.onTaskCreated)
return nil
}
func (p *myPlugin) Shutdown() {}
func (p *myPlugin) sayHello(req *plugin.Request, res *plugin.Response) {
name := req.QueryParam("name")
if name == "" {
name = "World"
}
res.JSON(200, map[string]string{"message": fmt.Sprintf("Hello, %s!", name)})
}
func (p *myPlugin) onTaskCreated(evt *plugin.Event) {
p.log.Info("A new task was created!")
}
func main() {
plugin.Run(&myPlugin{})
}
Building for Paca
Paca backend plugins must be compiled to WebAssembly using the WASI preview 1 target (wasip1), with TinyGo:
tinygo build -target=wasip1 -buildmode=c-shared -o plugin.wasm main.go
-buildmode=c-shared is required, not optional: without it, TinyGo doesn't
wire up the WASI reactor entry point (_initialize) that this SDK's
runtime depends on, and every call into the plugin panics at runtime with
"//go:wasmexport function called before runtime initialization" — it
still compiles fine without the flag, so this only surfaces once the
plugin is actually loaded by the host.
TinyGo is strongly recommended over the standard Go compiler: it doesn't
statically link Go's full runtime (GC, scheduler, reflection), so a typical
plugin binary is well under 1MB versus several MB with standard Go — and
since every loaded plugin gets its own independent copy of that runtime on
the host, this is a real difference in the host's memory use per plugin,
not just download size.
Standard Go 1.24+ also works (GOARCH=wasm GOOS=wasip1 go build -buildmode=c-shared -o plugin.wasm main.go) and is the right fallback if
your plugin hits a TinyGo compatibility limitation — TinyGo implements a
subset of the stdlib, notably around reflect. One TinyGo-specific
constraint either way: if your plugin declares its own //go:wasmimport
host function beyond what this SDK provides (see CallHostFunction),
call it directly by name rather than passing it as a value — TinyGo
doesn't support taking the address of a go:wasmimport function, only
calling it. If you use CallHostFunction, wrap your import in a small
closure:
// Works under both standard Go and TinyGo:
err := plugin.CallHostFunction(func(a, b, c, d int64) { hostMyImport(a, b, c, d) }, req, &res)
// Compiles under standard Go, but fails to build under TinyGo:
err := plugin.CallHostFunction(hostMyImport, req, &res)
API Reference
Context
The bridge between your plugin and the Paca host. Available via Init(ctx):
ctx.DB() — access the scoped database (PostgreSQL)
ctx.KV() — access the plugin-private key-value store (JSONB), durable with no expiry
ctx.Cache() — access the plugin's TTL-based cache (Valkey/Redis), for derived data that can tolerate being briefly stale
ctx.Log() — write structured logs to the host
ctx.Config() — read plugin configuration and secrets
ctx.Route(method, path, handler) — register an HTTP endpoint
ctx.On(event, handler) — subscribe to a core platform event
Route-level host middleware (for example authn, requireFreshPassword,
requirePermissions) is configured in plugin.json under
backend.routes[].middlewares.
DB
Typed SQL execution. The host enforces row-level scoping; you can only see data for the project where the plugin is enabled.
db.Query(sql, args...) — execute a read query; returns []map[string]any
db.Exec(sql, args...) — execute an insert/update/delete
db.Begin() — start a database transaction
Request & Response
Idiomatic HTTP handling inside your route handlers:
req.PathParam(name) — get a URL path parameter (e.g., :taskId)
req.QueryParam(name) — get a URL query parameter
plugin.JSONBody[T](req) — parse the JSON request body into a struct
res.JSON(code, data) — write a JSON response
res.Error(code, message) — write a standard error response: {"error": "..."}
res.NoContent() — return a 204 No Content response
Unit Testing
The SDK includes the plugintest package for testing your plugin logic without a running Paca instance.
import (
"testing"
"github.com/Paca-AI/plugin-sdk-go/plugintest"
)
func TestHello(t *testing.T) {
tc := plugintest.NewContext(t)
var p myPlugin
p.Init(tc.PluginContext())
res := tc.Call("GET", "/hello", plugintest.Request{
Query: map[string]string{"name": "Paca"},
})
if res.StatusCode != 200 {
t.Fatalf("expected 200, got %d: %s", res.StatusCode, res.BodyString())
}
}
License
MIT