Skip to content

Switchyard lets LLM applications route traffic across models and providers while preserving native OpenAI and Anthropic API compatibility - enabling flexible model selection, benchmarking, and cost/performance optimization.

Rust

refactor(go): separate native backend and WASM runtime (#1129)

Alex Fournier3a2a50e815af
diff --git a/.gitignore b/.gitignore
index bc9410dc7..9123d24b6 100644
--- a/.gitignore
+++ b/.gitignore
@@ -11,6 +11,7 @@ node_modules/
*.node
/bindings/typescript/LICENSE
/bindings/typescript/NOTICE
+/bindings/go/internal/wasm/switchyard.wasm
# Distribution / packaging
leaderboard/
diff --git a/bindings/go/README.md b/bindings/go/README.md
index 267ffe5db..56b4ec179 100644
--- a/bindings/go/README.md
+++ b/bindings/go/README.md
@@ -4,16 +4,26 @@ NVIDIA NeMo Switchyard is a library for routing LLM requests between models.
These Go bindings run Switchyard algorithms inside your application. Your
application owns model eligibility, credentials, provider calls, and retries.
+A private WebAssembly runtime exercises translation codecs through wazero.
+Routing and public translation functions still use the native library.
+
## Installation
-Requires Go 1.22+, cgo, a C compiler, and the repository's Rust toolchain. This is
+Requires Go 1.25+, cgo, a C compiler, and the repository's Rust toolchain. This is
a source-only module. From a checkout of this repository, build the native
-library for the same platform as your Go application:
+library for the same platform as your Go application, then build the WASM guest:
```sh
cargo build -p switchyard-ffi --release --locked
+rustup target add wasm32-wasip1
+cargo build -p switchyard-ffi --target wasm32-wasip1 --release --locked --lib
+mkdir -p bindings/go/internal/wasm
+cp target/wasm32-wasip1/release/switchyard_ffi.wasm bindings/go/internal/wasm/switchyard.wasm
```
+These commands use the repository's pinned Rust toolchain. The generated binary
+is not checked in. Rebuild it after changing Rust code.
+
From your application's Go module, point Go at that checkout. Replace the path
below with its absolute location:
@@ -26,6 +36,10 @@ Native builds link `target/release/libswitchyard_ffi.a` into the Go host artifac
The native path still requires cgo and platform system libraries.
Native artifacts are not downloaded or published by this package.
+The `switchyard_native` build tag excludes the private WASM runtime and its
+tests, so that build needs only the native library. The package still requires
+cgo; the private runtime is not a complete WASM routing backend.
+
## Use
```go
@@ -92,13 +106,22 @@ IDs to the host's tenant and conversation. `Input.Metadata` and
## Test
-From the repository root, after building the native library:
+From the repository root, after building the native library and WASM guest:
+
+```sh
+cd bindings/go
+CGO_ENABLED=1 go test -race ./...
+CGO_ENABLED=1 GOEXPERIMENT=cgocheck2 go test -race ./...
+CGO_ENABLED=1 go vet ./...
+```
+
+For a native-only build, skip the guest build and use the build tag:
```sh
cd bindings/go
-go test -race ./...
-GOEXPERIMENT=cgocheck2 go test -race ./...
-go vet ./...
+CGO_ENABLED=1 go test -tags switchyard_native -race ./...
+CGO_ENABLED=1 GOEXPERIMENT=cgocheck2 go test -tags switchyard_native -race ./...
+CGO_ENABLED=1 go vet -tags switchyard_native ./...
```
Rebuild Go with `go test -a` after changing the C header or native library; Go's
@@ -106,8 +129,8 @@ cache does not track headers outside the package directory.
### Go versions
-`go 1.22` in `go.mod` is the compatibility minimum, not a compiler pin. Use the
-latest patch of a [supported Go release](https://go.dev/doc/devel/release#policy)
+`go 1.25.0` in `go.mod` is the compatibility minimum required by wazero, not a
+compiler pin. Use the latest patch of a [supported Go release](https://go.dev/doc/devel/release#policy)
for development and production; compatibility with an older release does not
make it a recommended production toolchain.
diff --git a/bindings/go/backend_native.go b/bindings/go/backend_native.go
new file mode 100644
index 000000000..2864c70e1
--- /dev/null
+++ b/bindings/go/backend_native.go
@@ -0,0 +1,186 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+//go:build cgo
+
+package switchyard
+
+/*
+#cgo CFLAGS: -I${SRCDIR}/../../crates/switchyard-ffi/include
+#cgo LDFLAGS: ${SRCDIR}/../../target/release/libswitchyard_ffi.a
+#cgo linux LDFLAGS: -ldl -lpthread -lm
+#cgo darwin LDFLAGS: -framework Security -framework CoreFoundation -liconv
+#include <stdlib.h>
+#include "switchyard.h"
+extern void syGoNext(uintptr_t user_data, char *error, char *step_json);
+*/
+import "C"
+
+import (
+ "context"
+ "encoding/json"
+ "errors"
+ "fmt"
+ "runtime/cgo"
+ "sync"
+ "unsafe"
+)
+
+type nativeBackend struct {
+ mu sync.RWMutex
+ ptr *C.SyRouter
+}
+
+func newBackend(config json.RawMessage) (engineBackend, error) {
+ if version := C.sy_abi_version(); version != C.SY_ABI_VERSION {
+ return nil, fmt.Errorf("Switchyard ABI version mismatch: library=%d, binding=%d", version, C.SY_ABI_VERSION)
+ }
+ value := C.CString(string(config))
+ defer C.free(unsafe.Pointer(value))
+ var ptr *C.SyRouter
+ if err := nativeError(C.sy_router_new(value, &ptr)); err != nil {
+ return nil, err
+ }
+ return &nativeBackend{ptr: ptr}, nil
+}
+
+func (backend *nativeBackend) close() {
+ backend.mu.Lock()
+ defer backend.mu.Unlock()
+ if backend.ptr != nil {
+ C.sy_router_free(backend.ptr)
+ backend.ptr = nil
+ }
+}
+
+func (backend *nativeBackend) newRun(input Input) (*C.SyRun, error) {
+ data, err := json.Marshal(input)
+ if err != nil {
+ return nil, err
+ }
+ value := C.CString(string(data))
+ defer C.free(unsafe.Pointer(value))
+ backend.mu.RLock()
+ defer backend.mu.RUnlock()
+ if backend.ptr == nil {
+ return nil, errors.New("Switchyard router is closed")
+ }
+ var run *C.SyRun
+ err = nativeError(C.sy_run_new(backend.ptr, value, &run))
+ return run, err
+}
+
+type nativeNextResult struct {
+ data json.RawMessage
+ err error
+}
+
+type nativeHostReply struct {
+ id uint64
+ reply Reply
+ err error
+}
+
+func (backend *nativeBackend) route(ctx context.Context, input Input, call HostCall) (Outcome, error) {
+ if err := ctx.Err(); err != nil {
+ return Outcome{}, err
+ }
+ run, err := backend.newRun(input)
+ if err != nil {
+ return Outcome{}, err
+ }
+ ctx, cancel := context.WithCancel(ctx)
+ next := make(chan nativeNextResult, 1)
+ handle := cgo.NewHandle(next)
+ defer func() {
+ cancel()
+ C.sy_run_cancel(run)
+ C.sy_run_free(run)
+ handle.Delete()
+ }()
+ readNext := func() error {
+ return nativeError(C.sy_run_next_async(run, C.SyNextCallback(C.syGoNext), C.uintptr_t(handle)))
+ }
+ if err := readNext(); err != nil {
+ return Outcome{}, err
+ }
+ replies := make(chan nativeHostReply)
+ for {
+ select {
+ case <-ctx.Done():
+ return Outcome{}, ctx.Err()
+ case result := <-next:
+ if err := ctx.Err(); err != nil {
+ return Outcome{}, err
+ }
+ if result.err != nil {
+ return Outcome{}, result.err
+ }
+ var work Work
+ if err := json.Unmarshal(result.data, &work); err != nil {
+ return Outcome{}, err
+ }
+ if work.Type == "done" {
+ var outcome Outcome
+ if err := json.Unmarshal(result.data, &outcome); err != nil {
+ return Outcome{}, err
+ }
+ if err := ctx.Err(); err != nil {
+ return Outcome{}, err
+ }
+ return outcome, nil
+ }
+ if work.Type != "call_model" && work.Type != "call_decision" {
+ return Outcome{}, errors.New("unknown Switchyard step: " + work.Type)
+ }
+ if call == nil {
+ return Outcome{}, errors.New("Switchyard algorithm requires a host model client")
+ }
+ go func(work Work) {
+ if ctx.Err() != nil {
+ return
+ }
+ reply, err := call(ctx, work)
+ select {
+ case replies <- nativeHostReply{work.ID, reply, err}:
+ case <-ctx.Done():
+ }
+ }(work)
+ if err := readNext(); err != nil {
+ return Outcome{}, err
+ }
+ case reply := <-replies:
+ envelope := struct {
+ Response json.RawMessage `json:"response,omitempty"`
+ ServedModel string `json:"served_model,omitempty"`
+ Error *string `json:"error,omitempty"`
+ }{Response: reply.reply.Response, ServedModel: reply.reply.ServedModel}
+ if reply.err != nil {
+ envelope.Response = nil
+ message := reply.err.Error()
+ envelope.Error = &message
+ }
+ data, err := json.Marshal(envelope)
+ if err != nil {
+ return Outcome{}, err
+ }
+ if err := ctx.Err(); err != nil {
+ return Outcome{}, err
+ }
+ value := C.CString(string(data))
+ err = nativeError(C.sy_run_respond(run, C.uint64_t(reply.id), value))
+ C.free(unsafe.Pointer(value))
+ if err != nil {
+ return Outcome{}, err
+ }
+ }
+ }
+}
+
+func nativeError(value *C.char) error {
+ if value == nil {
+ return nil
+ }
+ defer C.sy_string_free(value)
+ return errors.New(C.GoString(value))
+}
diff --git a/bindings/go/backend_test.go b/bindings/go/backend_test.go
new file mode 100644
index 000000000..324c8a272
--- /dev/null
+++ b/bindings/go/backend_test.go
@@ -0,0 +1,130 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+package switchyard
+
+import (
+ "context"
+ "encoding/json"
+ "fmt"
+ "strings"
+ "testing"
+ "time"
+)
+
+func testConfig(algorithm string) json.RawMessage {
+ return json.RawMessage(`{"algorithm":` + algorithm + `,"targets":{"weak":"weak-model","strong":"strong-model","judge":"judge-model"}}`)
+}
+
+// Message-key fallback retains a verdict, including children without an agent ID.
+func TestMessageRetention(t *testing.T) {
+ algorithm := strings.Replace(composite, `"classify_trigger":"user_turn"`, `"classify_trigger":"new_session","message_hash_fallback":true`, 1)
+ for _, child := range []bool{false, true} {
+ router := newRouter(t, algorithm)
+ request := input()
+ if child {
+ request.Metadata = &RequestMetadata{SessionID: "parent", IsSubagent: true}
+ }
+ calls := 0
+ for range 8 {
+ _, err := router.Route(context.Background(), request, func(context.Context, Work) (Reply, error) {
+ calls++
+ return Reply{Response: json.RawMessage(judgeAnswer)}, nil
+ })
+ if err != nil {
+ t.Fatal(err)
+ }
+ }
+ if calls != 1 {
+ t.Errorf("subagent=%t made %d judge calls, want 1", child, calls)
+ }
+ }
+}
+
+// A routing deadline must expire while its host call is still pending.
+func TestRoutingDeadline(t *testing.T) {
+ router := newRouter(t, `{"type":"vgr","efficient_target":"weak","capable_target":"strong","mode":"evaluate","deadline_seconds":0.02,"task_typing":false}`)
+ for range 4 {
+ t.Run("request", func(t *testing.T) {
+ t.Parallel()
+ testRoutingDeadline(t, router)
+ })
+ }
+}
+
+func testRoutingDeadline(t *testing.T, router *Router) {
+ t.Helper()
+ ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
+ defer cancel()
+ hostFinished := make(chan struct{})
+ started := time.Now()
+ outcome, err := router.Route(ctx, input(), func(ctx context.Context, _ Work) (Reply, error) {
+ defer close(hostFinished)
+ delay := time.NewTimer(400 * time.Millisecond)
+ defer delay.Stop()
+ select {
+ case <-delay.C:
+ return Reply{Response: json.RawMessage(judgeAnswer)}, nil
+ case <-ctx.Done():
+ return Reply{}, ctx.Err()
+ }
+ })
+ elapsed := time.Since(started)
+ t.Logf("routing deadline=20ms, host delay=400ms, route duration=%v", elapsed)
+ select {
+ case <-hostFinished:
+ case <-time.After(time.Second):
+ t.Fatal("host callback did not stop after routing finished")
+ }
+ if err != nil || len(outcome.SelectedModelIDs) == 0 || outcome.SelectedModelIDs[0] != "strong-model" {
+ t.Fatalf("outcome=%+v err=%v", outcome, err)
+ }
+ if elapsed >= 200*time.Millisecond {
+ t.Fatal("routing waited for the host instead of its configured deadline")
+ }
+}
+
+// Host calls must overlap without blocking other requests.
+func TestConcurrentHostCalls(t *testing.T) {
+ router := newRouter(t, composite)
+ ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
+ defer cancel()
+ started := make(chan struct{}, 2)
+ release := make(chan struct{})
+ results := make(chan error, 2)
+ for range 2 {
+ go func() {
+ outcome, err := router.Route(ctx, input(), func(ctx context.Context, _ Work) (Reply, error) {
+ started <- struct{}{}
+ select {
+ case <-release:
+ return Reply{Response: json.RawMessage(judgeAnswer)}, nil
+ case <-ctx.Done():
+ return Reply{}, ctx.Err()
+ }
+ })
+ if err == nil && (len(outcome.SelectedModelIDs) == 0 || outcome.SelectedModelIDs[0] != "weak-model") {
+ err = fmt.Errorf("unexpected outcome: %+v", outcome)
+ }
+ results <- err
+ }()
+ }
+ for range 2 {
+ select {
+ case <-started:
+ case <-ctx.Done():
+ t.Fatal("host calls did not overlap")
+ }
+ }
+ close(release)
+ for range 2 {
+ select {
+ case err := <-results:
+ if err != nil {
+ t.Fatal(err)
+ }
+ case <-ctx.Done():
+ t.Fatal("concurrent routes did not finish")
+ }
+ }
+}
diff --git a/bindings/go/callbacks.go b/bindings/go/callbacks.go
index f299fd5c9..31eb61678 100644
--- a/bindings/go/callbacks.go
+++ b/bindings/go/callbacks.go
@@ -1,6 +1,8 @@
// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
// SPDX-License-Identifier: Apache-2.0
+//go:build cgo
+
package switchyard
/*
@@ -14,10 +16,10 @@ import "runtime/cgo"
//
//export syGoNext
func syGoNext(token C.uintptr_t, failure *C.char, output *C.char) {
- result := nextResult{err: nativeError(failure)}
+ result := nativeNextResult{err: nativeError(failure)}
if output != nil {
result.data = []byte(C.GoString(output))
C.sy_string_free(output)
}
- cgo.Handle(token).Value().(chan nextResult) <- result
+ cgo.Handle(token).Value().(chan nativeNextResult) <- result
}
diff --git a/bindings/go/go.mod b/bindings/go/go.mod
index deb11ad65..95092974e 100644
--- a/bindings/go/go.mod
+++ b/bindings/go/go.mod
@@ -1,3 +1,7 @@
module github.com/NVIDIA-NeMo/Switchyard/bindings/go
-go 1.22
+go 1.25.0
+
+require github.com/tetratelabs/wazero v1.12.0
+
+require golang.org/x/sys v0.44.0 // indirect
diff --git a/bindings/go/go.sum b/bindings/go/go.sum
new file mode 100644
index 000000000..a10a279ad
--- /dev/null
+++ b/bindings/go/go.sum
@@ -0,0 +1,4 @@
+github.com/tetratelabs/wazero v1.12.0 h1:DuWcpNu/FzgEXgGBDp8J1Spc+CWOvvtvVyjKlaZopYU=
+github.com/tetratelabs/wazero v1.12.0/go.mod h1:LvKtzl2RqO4gyF27BiXU+nKAjcV8f38U+kP/q2vgxh0=
+golang.org/x/sys v0.44.0 h1:ildZl3J4uzeKP07r2F++Op7E9B29JRUy+a27EibtBTQ=
+golang.org/x/sys v0.44.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
diff --git a/bindings/go/switchyard.go b/bindings/go/switchyard.go
index 7c2e47d4c..18b0c82a5 100644
--- a/bindings/go/switchyard.go
+++ b/bindings/go/switchyard.go
@@ -4,35 +4,26 @@
// Package switchyard runs embedded routing algorithms with host-owned model calls.
package switchyard
-/*
-#cgo CFLAGS: -I${SRCDIR}/../../crates/switchyard-ffi/include
-#cgo LDFLAGS: ${SRCDIR}/../../target/release/libswitchyard_ffi.a
-#cgo linux LDFLAGS: -ldl -lpthread -lm
-#cgo darwin LDFLAGS: -framework Security -framework CoreFoundation -liconv
-#include <stdlib.h>
-#include "switchyard.h"
-extern void syGoNext(uintptr_t user_data, char *error, char *step_json);
-*/
-import "C"
-
import (
"context"
"encoding/json"
"errors"
- "fmt"
- "runtime/cgo"
"sync"
- "unsafe"
)
+type engineBackend interface {
+ route(context.Context, Input, HostCall) (Outcome, error)
+ close()
+}
+
// Router shares an algorithm across concurrent requests and value copies. Its zero value is closed.
type Router struct {
state *routerState
}
type routerState struct {
- mu sync.RWMutex
- ptr *C.SyRouter
+ mu sync.RWMutex
+ backend engineBackend
}
// Input supplies a normalized request and the host-approved model groups for this run.
@@ -61,14 +52,13 @@ type Work struct {
Request json.RawMessage `json:"request"`
}
-// Reply contains a normalized response and, for model calls, the target that actually answered.
+// Reply contains a normalized response and, for model calls, the target that answered.
type Reply struct {
Response json.RawMessage `json:"response"`
ServedModel string `json:"served_model,omitempty"`
}
// HostCall executes model or decision work. It must honor ctx and may run concurrently.
-// A call that ignores cancellation may outlive Route, but cannot access the native run.
type HostCall func(context.Context, Work) (Reply, error)
// Outcome retains the ordered candidates, prepared requests, and any routing-produced answer.
@@ -82,168 +72,45 @@ type Outcome struct {
// New constructs an algorithm from {"algorithm": AlgorithmSpec, "targets": {alias: modelID}}.
func New(config json.RawMessage) (*Router, error) {
- if version := C.sy_abi_version(); version != C.SY_ABI_VERSION {
- return nil, fmt.Errorf("Switchyard ABI version mismatch: library=%d, binding=%d", version, C.SY_ABI_VERSION)
+ if !json.Valid(config) {
+ return nil, errors.New("Switchyard config must be valid JSON")
}
- value := C.CString(string(config))
- defer C.free(unsafe.Pointer(value))
- var ptr *C.SyRouter
- if err := nativeError(C.sy_router_new(value, &ptr)); err != nil {
+ backend, err := newBackend(config)
+ if err != nil {
return nil, err
}
- return &Router{state: &routerState{ptr: ptr}}, nil
+ return &Router{state: &routerState{backend: backend}}, nil
}
-// Close prevents new runs and releases the router. Active runs retain their algorithm.
-// Repeated calls, including through Router value copies, are safe.
+// Close prevents new runs and releases this Router's backend. Repeated calls and value copies are safe.
func (router *Router) Close() {
- state := router.state
- if state == nil {
+ if router == nil || router.state == nil {
return
}
+ state := router.state
state.mu.Lock()
defer state.mu.Unlock()
- if state.ptr != nil {
- C.sy_router_free(state.ptr)
- state.ptr = nil
+ if state.backend != nil {
+ state.backend.close()
+ state.backend = nil
}
}
-// Limit the router borrow to construction; each native run retains its own engine reference.
-func (router *Router) newRun(input Input) (*C.SyRun, error) {
- data, err := json.Marshal(input)
- if err != nil {
- return nil, err
+// Route waits for an outcome while the host services model and decision calls.
+// Host errors follow the algorithm's configured error policy.
+func (router *Router) Route(ctx context.Context, input Input, call HostCall) (Outcome, error) {
+ if router == nil || router.state == nil {
+ return Outcome{}, errors.New("Switchyard router is closed")
}
- value := C.CString(string(data))
- defer C.free(unsafe.Pointer(value))
state := router.state
- if state == nil {
- return nil, errors.New("Switchyard router is closed")
- }
state.mu.RLock()
- defer state.mu.RUnlock()
- if state.ptr == nil {
- return nil, errors.New("Switchyard router is closed")
+ backend := state.backend
+ state.mu.RUnlock()
+ if backend == nil {
+ return Outcome{}, errors.New("Switchyard router is closed")
}
- var run *C.SyRun
- err = nativeError(C.sy_run_new(state.ptr, value, &run))
- return run, err
-}
-
-type nextResult struct {
- data json.RawMessage
- err error
-}
-
-type hostReply struct {
- id uint64
- reply Reply
- err error
-}
-
-// Route waits for an outcome while the host services calls with its own clients.
-// Cancellation stops routing without waiting for host calls that ignore their context.
-func (router *Router) Route(ctx context.Context, input Input, call HostCall) (Outcome, error) {
if err := ctx.Err(); err != nil {
return Outcome{}, err
}
- run, err := router.newRun(input)
- if err != nil {
- return Outcome{}, err
- }
- ctx, cancel := context.WithCancel(ctx)
- // At most one read is outstanding; consume its result before requesting another.
- next := make(chan nextResult, 1)
- handle := cgo.NewHandle(next)
- defer func() {
- cancel()
- C.sy_run_cancel(run)
- C.sy_run_free(run)
- handle.Delete()
- }()
- readNext := func() error {
- return nativeError(C.sy_run_next_async(run, C.SyNextCallback(C.syGoNext), C.uintptr_t(handle)))
- }
- if err := readNext(); err != nil {
- return Outcome{}, err
- }
- replies := make(chan hostReply)
- for {
- select {
- case <-ctx.Done():
- return Outcome{}, ctx.Err()
- case result := <-next:
- if err := ctx.Err(); err != nil {
- return Outcome{}, err
- }
- if result.err != nil {
- return Outcome{}, result.err
- }
- var work Work
- if err := json.Unmarshal(result.data, &work); err != nil {
- return Outcome{}, err
- }
- if work.Type == "done" {
- var outcome Outcome
- err := json.Unmarshal(result.data, &outcome)
- if cancelErr := ctx.Err(); cancelErr != nil {
- return Outcome{}, cancelErr
- }
- return outcome, err
- }
- if work.Type != "call_model" && work.Type != "call_decision" {
- return Outcome{}, errors.New("unknown Switchyard step: " + work.Type)
- }
- if call == nil {
- return Outcome{}, errors.New("Switchyard algorithm requires a host model client")
- }
- // Workers own Go data only; late results cannot call into a freed native run.
- go func(work Work) {
- if ctx.Err() != nil {
- return
- }
- reply, err := call(ctx, work)
- select {
- case replies <- hostReply{work.ID, reply, err}:
- case <-ctx.Done():
- }
- }(work)
- if err := readNext(); err != nil {
- return Outcome{}, err
- }
- case reply := <-replies:
- envelope := struct {
- Response json.RawMessage `json:"response,omitempty"`
- ServedModel string `json:"served_model,omitempty"`
- Error *string `json:"error,omitempty"`
- }{Response: reply.reply.Response, ServedModel: reply.reply.ServedModel}
- if reply.err != nil {
- envelope.Response = nil
- message := reply.err.Error()
- envelope.Error = &message
- }
- data, err := json.Marshal(envelope)
- if err != nil {
- return Outcome{}, err
- }
- if err := ctx.Err(); err != nil {
- return Outcome{}, err
- }
- value := C.CString(string(data))
- err = nativeError(C.sy_run_respond(run, C.uint64_t(reply.id), value))
- C.free(unsafe.Pointer(value))
- if err != nil {
- return Outcome{}, err
- }
- }
- }
-}
-
-func nativeError(value *C.char) error {
- if value == nil {
- return nil
- }
- defer C.sy_string_free(value)
- return errors.New(C.GoString(value))
+ return backend.route(ctx, input, call)
}
diff --git a/bindings/go/switchyard_test.go b/bindings/go/switchyard_test.go
index 36125245c..c1d91a142 100644
--- a/bindings/go/switchyard_test.go
+++ b/bindings/go/switchyard_test.go
@@ -18,11 +18,12 @@ import (
const stage = `"capable_target":"strong","efficient_target":"weak","confidence_threshold":0.5`
const composite = `{"type":"composite","classifier":{"target":"judge","base_threshold":0.5,"classify_trigger":"user_turn","fail_open":false},"stage":{` + stage + `}}`
+const decision = `{"type":"composite","classifier":{"target":"judge","classify_trigger":"user_turn","fail_open":false,"decision":{"cutoff":0.5,"candidates":{"a":"strong","b":"weak"},"evidence":{}}},"stage":{` + stage + `}}`
const judgeAnswer = `{"model":"provider-model","outputs":[{"role":"assistant","content":[{"type":"text","text":"{\"crux\":\"bounded task\",\"primary_rule\":\"SUP-1\",\"capability_boundary\":\"supported\",\"p_solve\":0.9}"}],"stop_reason":"end_turn"}]}`
func newRouter(t *testing.T, algorithm string) *Router {
t.Helper()
- router, err := New(json.RawMessage(`{"algorithm":` + algorithm + `,"targets":{"weak":"weak-model","strong":"strong-model","judge":"judge-model"}}`))
+ router, err := New(testConfig(algorithm))
if err != nil {
t.Fatal(err)
}
@@ -142,7 +143,6 @@ func TestSelectionAndTranslation(t *testing.T) {
// Both judge protocols use Go's client; missing clients and host failures remain errors.
func TestCompositeHostCalls(t *testing.T) {
- decision := `{"type":"composite","classifier":{"target":"judge","classify_trigger":"user_turn","fail_open":false,"decision":{"cutoff":0.5,"candidates":{"a":"strong","b":"weak"},"evidence":{}}},"stage":{` + stage + `}}`
for _, tc := range []struct {
name, algorithm, kind, selected, response, invalidResponse string
}{
@@ -187,19 +187,20 @@ func TestCompositeHostCalls(t *testing.T) {
// Host failures remain subject to the algorithm's configured recovery policy.
func TestHostFailureUsesAlgorithmPolicy(t *testing.T) {
- algorithm := strings.Replace(composite, `"fail_open":false`, `"fail_open":true`, 1)
- router := newRouter(t, algorithm)
- calls := 0
- outcome, err := router.Route(context.Background(), input(), func(context.Context, Work) (Reply, error) {
- calls++
- return Reply{}, errors.New("judge unavailable")
- })
- if err != nil || calls != 1 || !slices.Equal(outcome.SelectedModelIDs, []string{"weak-model", "strong-model"}) {
- t.Fatalf("calls=%d outcome=%+v err=%v", calls, outcome, err)
+ for _, algorithm := range []string{composite, decision} {
+ router := newRouter(t, strings.Replace(algorithm, `"fail_open":false`, `"fail_open":true`, 1))
+ calls := 0
+ outcome, err := router.Route(context.Background(), input(), func(context.Context, Work) (Reply, error) {
+ calls++
+ return Reply{}, errors.New("judge unavailable")
+ })
+ if err != nil || calls != 1 || !slices.Equal(outcome.SelectedModelIDs, []string{"weak-model", "strong-model"}) {
+ t.Fatalf("calls=%d outcome=%+v err=%v", calls, outcome, err)
+ }
}
}
-// Cancellation releases native work even if a host ignores its context and replies later.
+// Cancellation releases routing work even if a host ignores its context and replies later.
func TestCancellationAndLateHostReply(t *testing.T) {
router := newRouter(t, composite)
ctx, cancel := context.WithCancel(context.Background())
@@ -234,7 +235,7 @@ func TestCancellationAndLateHostReply(t *testing.T) {
t.Fatal("cancellation waited for host code")
}
runtime.GC()
- // Release after Route has freed its native run, then let the late Go reply drain.
+ // Release after Route has freed its run, then let the late Go reply drain.
releaseHost()
select {
case <-returned:
diff --git a/bindings/go/translation.go b/bindings/go/translation.go
index a322a06a2..cc8f44feb 100644
--- a/bindings/go/translation.go
+++ b/bindings/go/translation.go
@@ -3,59 +3,39 @@
package switchyard
-/*
-#include <stdlib.h>
-#include "switchyard.h"
-*/
-import "C"
-
import (
"encoding/json"
- "unsafe"
)
// DecodeRequest converts a provider wire body to Switchyard's normalized request.
func DecodeRequest(format string, body json.RawMessage) (json.RawMessage, error) {
- return translated(struct {
+ return translated("sy_decode_request", struct {
Format string `json:"format"`
Body json.RawMessage `json:"body"`
- }{format, body}, func(input *C.char, output **C.char) *C.char {
- return C.sy_decode_request(input, output)
- })
+ }{format, body})
}
// EncodeRequest stamps the target model and encodes the prepared normalized request.
func EncodeRequest(format string, request json.RawMessage, model string) (json.RawMessage, error) {
- return translated(struct {
+ return translated("sy_encode_request", struct {
Format string `json:"format"`
Request json.RawMessage `json:"request"`
Model string `json:"model"`
- }{format, request, model}, func(input *C.char, output **C.char) *C.char {
- return C.sy_encode_request(input, output)
- })
+ }{format, request, model})
}
// DecodeResponse converts a buffered provider response to Switchyard's normalized aggregate.
func DecodeResponse(format string, body json.RawMessage) (json.RawMessage, error) {
- return translated(struct {
+ return translated("sy_decode_response", struct {
Format string `json:"format"`
Body json.RawMessage `json:"body"`
- }{format, body}, func(input *C.char, output **C.char) *C.char {
- return C.sy_decode_response(input, output)
- })
+ }{format, body})
}
-func translated(input any, call func(*C.char, **C.char) *C.char) (json.RawMessage, error) {
+func translated(export string, input any) (json.RawMessage, error) {
data, err := json.Marshal(input)
if err != nil {
return nil, err
}
- value := C.CString(string(data))
- defer C.free(unsafe.Pointer(value))
- var output *C.char
- if err := nativeError(call(value, &output)); err != nil {
- return nil, err
- }
- defer C.sy_string_free(output)
- return json.RawMessage(C.GoString(output)), nil
+ return translate(export, data)
}
diff --git a/bindings/go/translation_native.go b/bindings/go/translation_native.go
new file mode 100644
index 000000000..b4a4df02f
--- /dev/null
+++ b/bindings/go/translation_native.go
@@ -0,0 +1,39 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+//go:build cgo
+
+package switchyard
+
+/*
+#include <stdlib.h>
+#include "switchyard.h"
+*/
+import "C"
+
+import (
+ "encoding/json"
+ "unsafe"
+)
+
+func translate(export string, input []byte) (json.RawMessage, error) {
+ value := C.CString(string(input))
+ defer C.free(unsafe.Pointer(value))
+ var output *C.char
+ var failure *C.char
+ switch export {
+ case "sy_decode_request":
+ failure = C.sy_decode_request(value, &output)
+ case "sy_encode_request":
+ failure = C.sy_encode_request(value, &output)
+ case "sy_decode_response":
+ failure = C.sy_decode_response(value, &output)
+ default:
+ panic("unknown Switchyard translation export " + export)
+ }
+ if err := nativeError(failure); err != nil {
+ return nil, err
+ }
+ defer C.sy_string_free(output)
+ return json.RawMessage(C.GoString(output)), nil
+}
diff --git a/bindings/go/wasm_runtime.go b/bindings/go/wasm_runtime.go
new file mode 100644
index 000000000..5da91cac5
--- /dev/null
+++ b/bindings/go/wasm_runtime.go
@@ -0,0 +1,300 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+//go:build !cgo || !switchyard_native
+
+package switchyard
+
+import (
+ "bytes"
+ "context"
+ cryptorand "crypto/rand"
+ _ "embed"
+ "encoding/json"
+ "errors"
+ "fmt"
+ "strings"
+ "sync"
+
+ "github.com/tetratelabs/wazero"
+ "github.com/tetratelabs/wazero/api"
+ "github.com/tetratelabs/wazero/imports/wasi_snapshot_preview1"
+)
+
+//go:embed internal/wasm/switchyard.wasm
+var switchyardWasm []byte
+
+const wasmABIVersion = 1
+
+type wasmRuntime struct {
+ runtime wazero.Runtime
+ compiled wazero.CompiledModule
+ close sync.Once
+}
+
+var wasmCompilationCache = wazero.NewCompilationCache()
+
+type wasmTrapError struct {
+ function string
+ err error
+ stderr string
+}
+
+func (err *wasmTrapError) Error() string {
+ if err.stderr != "" {
+ return fmt.Sprintf("Switchyard wasm %s trapped: %v: %s", err.function, err.err, err.stderr)
+ }
+ return fmt.Sprintf("Switchyard wasm %s trapped: %v", err.function, err.err)
+}
+func (err *wasmTrapError) Unwrap() error { return err.err }
+
+type wasmGuestError struct{ message string }
+
+func (err *wasmGuestError) Error() string { return err.message }
+
+func isWasmTrap(err error) bool {
+ var target *wasmTrapError
+ return errors.As(err, &target)
+}
+
+func newWasmRuntime() (*wasmRuntime, error) {
+ config := wazero.NewRuntimeConfigCompiler().
+ WithCompilationCache(wasmCompilationCache).
+ WithMemoryLimitPages(16384).
+ WithCloseOnContextDone(true)
+ runtime := wazero.NewRuntimeWithConfig(context.Background(), config)
+ if _, err := wasi_snapshot_preview1.Instantiate(context.Background(), runtime); err != nil {
+ _ = runtime.Close(context.Background())
+ return nil, fmt.Errorf("instantiate WASI: %w", err)
+ }
+ compiled, err := runtime.CompileModule(context.Background(), switchyardWasm)
+ if err != nil {
+ _ = runtime.Close(context.Background())
+ return nil, fmt.Errorf("compile Switchyard wasm: %w", err)
+ }
+ return &wasmRuntime{runtime: runtime, compiled: compiled}, nil
+}
+
+// guestStderr keeps the guest's latest stderr output, such as a Rust panic message.
+type guestStderr struct {
+ mu sync.Mutex
+ buf bytes.Buffer
+}
+
+const guestStderrLimit = 4096
+
+func (stderr *guestStderr) Write(data []byte) (int, error) {
+ stderr.mu.Lock()
+ defer stderr.mu.Unlock()
+ stderr.buf.Write(data)
+ if extra := stderr.buf.Len() - guestStderrLimit; extra > 0 {
+ stderr.buf.Next(extra)
+ }
+ return len(data), nil
+}
+
+func (stderr *guestStderr) take() string {
+ stderr.mu.Lock()
+ defer stderr.mu.Unlock()
+ text := strings.TrimSpace(stderr.buf.String())
+ stderr.buf.Reset()
+ return text
+}
+
+func (runtime *wasmRuntime) newModule(ctx context.Context) (*guestModule, error) {
+ stderr := &guestStderr{}
+ config := wazero.NewModuleConfig().
+ WithStderr(stderr).
+ WithStartFunctions().
+ WithSysWalltime().
+ WithSysNanotime().
+ WithRandSource(cryptorand.Reader).
+ WithName("")
+ module, err := runtime.runtime.InstantiateModule(ctx, runtime.compiled, config)
+ if err != nil {
+ return nil, err
+ }
+ guest := &guestModule{module: module, stderr: stderr}
+ if _, err := guest.call(ctx, "_initialize"); err != nil {
+ _ = module.Close(context.Background())
+ return nil, fmt.Errorf("initialize Switchyard wasm: %w", err)
+ }
+ version, err := guest.call(ctx, "sy_abi_version")
+ if err != nil {
+ _ = module.Close(context.Background())
+ return nil, fmt.Errorf("read Switchyard wasm ABI: %w", err)
+ }
+ if len(version) != 1 || uint32(version[0]) != wasmABIVersion {
+ _ = module.Close(context.Background())
+ return nil, fmt.Errorf("Switchyard wasm ABI version mismatch: module=%v, binding=%d", version, wasmABIVersion)
+ }
+ return guest, nil
+}
+
+func (runtime *wasmRuntime) closeAll() {
+ runtime.close.Do(func() {
+ _ = runtime.runtime.Close(context.Background())
+ })
+}
+
+type guestModule struct {
+ module api.Module
+ stderr *guestStderr
+}
+
+func (guest *guestModule) call(ctx context.Context, name string, args ...uint64) ([]uint64, error) {
+ function := guest.module.ExportedFunction(name)
+ if function == nil {
+ return nil, fmt.Errorf("Switchyard wasm export %q is missing", name)
+ }
+ values, err := function.Call(ctx, args...)
+ if err != nil {
+ return nil, &wasmTrapError{function: name, err: err, stderr: guest.stderr.take()}
+ }
+ return values, nil
+}
+
+func (guest *guestModule) alloc(ctx context.Context, data []byte) (uint32, error) {
+ if uint64(len(data)) > uint64(^uint32(0)) {
+ return 0, errors.New("Switchyard wasm buffer exceeds wasm32 memory")
+ }
+ values, err := guest.call(ctx, "sy_alloc", uint64(uint32(len(data))))
+ if err != nil {
+ return 0, err
+ }
+ if len(values) != 1 || uint32(values[0]) == 0 {
+ return 0, errors.New("Switchyard wasm allocation failed")
+ }
+ ptr := uint32(values[0])
+ if !guest.module.Memory().Write(ptr, data) {
+ _, _ = guest.call(context.Background(), "sy_free", uint64(ptr), uint64(uint32(len(data))))
+ return 0, errors.New("Switchyard wasm allocation is outside guest memory")
+ }
+ return ptr, nil
+}
+
+func (guest *guestModule) free(ctx context.Context, ptr uint32, length uint32) error {
+ _, err := guest.call(ctx, "sy_free", uint64(ptr), uint64(length))
+ return err
+}
+
+func (guest *guestModule) cstring(ctx context.Context, data []byte) (uint32, uint32, error) {
+ data = append(bytes.Clone(data), 0)
+ ptr, err := guest.alloc(ctx, data)
+ return ptr, uint32(len(data)), err
+}
+
+func (guest *guestModule) readCString(ptr uint32) ([]byte, error) {
+ if ptr == 0 {
+ return nil, errors.New("Switchyard wasm returned a null string")
+ }
+ memory := guest.module.Memory()
+ size := memory.Size()
+ if size == 0 || ptr >= size {
+ return nil, errors.New("Switchyard wasm string pointer is outside guest memory")
+ }
+ const chunkSize = uint32(16 * 1024)
+ output := make([]byte, 0, chunkSize)
+ for offset := ptr; offset < size; {
+ count := min(chunkSize, size-offset)
+ chunk, ok := memory.Read(offset, count)
+ if !ok {
+ return nil, errors.New("Switchyard wasm string is outside guest memory")
+ }
+ if end := bytes.IndexByte(chunk, 0); end >= 0 {
+ output = append(output, chunk[:end]...)
+ return output, nil
+ }
+ output = append(output, chunk...)
+ offset += count
+ }
+ return nil, errors.New("Switchyard wasm returned an unterminated string")
+}
+
+func (guest *guestModule) guestError(ptr uint32) error {
+ if ptr == 0 {
+ return nil
+ }
+ message, err := guest.readCString(ptr)
+ _, freeErr := guest.call(context.Background(), "sy_string_free", uint64(ptr))
+ if err != nil {
+ return err
+ }
+ if freeErr != nil {
+ return freeErr
+ }
+ return &wasmGuestError{message: string(message)}
+}
+
+func (guest *guestModule) callJSON(ctx context.Context, export string, input []byte) ([]byte, error) {
+ inputPtr, inputLen, err := guest.cstring(ctx, input)
+ if err != nil {
+ return nil, err
+ }
+ defer guest.free(context.Background(), inputPtr, inputLen)
+ outPtr, err := guest.alloc(ctx, make([]byte, 4))
+ if err != nil {
+ return nil, err
+ }
+ defer guest.free(context.Background(), outPtr, 4)
+ values, err := guest.call(ctx, export, uint64(inputPtr), uint64(outPtr))
+ if err != nil {
+ return nil, err
+ }
+ if len(values) != 1 {
+ return nil, fmt.Errorf("Switchyard wasm %s returned %d values", export, len(values))
+ }
+ if err := guest.guestError(uint32(values[0])); err != nil {
+ return nil, err
+ }
+ outputPtr, ok := guest.module.Memory().ReadUint32Le(outPtr)
+ if !ok || outputPtr == 0 {
+ return nil, errors.New("Switchyard wasm returned no JSON output")
+ }
+ output, err := guest.readCString(outputPtr)
+ if err != nil {
+ return nil, err
+ }
+ if _, err := guest.call(context.Background(), "sy_string_free", uint64(outputPtr)); err != nil {
+ return nil, err
+ }
+ return output, nil
+}
+
+type wasmTranslator struct {
+ runtime *wasmRuntime
+ guest *guestModule
+ err error
+ mu sync.Mutex
+}
+
+var defaultWasmTranslator struct {
+ once sync.Once
+ value *wasmTranslator
+}
+
+func wasmTranslate(export string, input []byte) (json.RawMessage, error) {
+ defaultWasmTranslator.once.Do(func() {
+ runtime, err := newWasmRuntime()
+ defaultWasmTranslator.value = &wasmTranslator{runtime: runtime, err: err}
+ })
+ translator := defaultWasmTranslator.value
+ if translator.err != nil {
+ return nil, translator.err
+ }
+ translator.mu.Lock()
+ defer translator.mu.Unlock()
+ if translator.guest == nil {
+ guest, err := translator.runtime.newModule(context.Background())
+ if err != nil {
+ return nil, err
+ }
+ translator.guest = guest
+ }
+ output, err := translator.guest.callJSON(context.Background(), export, input)
+ if err != nil && (isWasmTrap(err) || translator.guest.module.IsClosed()) {
+ _ = translator.guest.module.Close(context.Background())
+ translator.guest = nil
+ }
+ return json.RawMessage(output), err
+}
diff --git a/bindings/go/wasm_test.go b/bindings/go/wasm_test.go
new file mode 100644
index 000000000..1c8d6db3a
--- /dev/null
+++ b/bindings/go/wasm_test.go
@@ -0,0 +1,91 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+//go:build !cgo || !switchyard_native
+
+package switchyard
+
+import (
+ "context"
+ "encoding/json"
+ "strings"
+ "testing"
+)
+
+// Missing startup exports must return errors instead of panicking.
+func TestWasmMissingStartupExport(t *testing.T) {
+ runtime, err := newWasmRuntime()
+ if err != nil {
+ t.Fatal(err)
+ }
+ defer runtime.closeAll()
+ ctx := context.Background()
+ // Minimal modules with no exports, or only a no-op _initialize export.
+ for name, wasm := range map[string]string{
+ "_initialize": "\x00asm\x01\x00\x00\x00",
+ "sy_abi_version": "\x00asm\x01\x00\x00\x00\x01\x04\x01\x60\x00\x00\x03\x02\x01\x00\x07\x0f\x01\x0b_initialize\x00\x00\x0a\x04\x01\x02\x00\x0b",
+ } {
+ t.Run(name, func(t *testing.T) {
+ runtime.compiled, err = runtime.runtime.CompileModule(ctx, []byte(wasm))
+ if err != nil {
+ t.Fatal(err)
+ }
+ if guest, err := runtime.newModule(ctx); guest != nil || err == nil || !strings.Contains(err.Error(), "export \""+name+"\" is missing") {
+ t.Fatalf("missing %s returned %v", name, err)
+ }
+ })
+ }
+}
+
+// The private runtime uses the same JSON codec ABI as the native backend.
+func TestWasmTranslation(t *testing.T) {
+ request, err := wasmTranslate("sy_decode_request", []byte(`{"format":"openai_chat","body":{"messages":[{"role":"user","content":"hi"}]}}`))
+ if err != nil {
+ t.Fatal(err)
+ }
+ var decoded struct {
+ Messages []struct {
+ Role string
+ Content []struct{ Text string }
+ }
+ }
+ if err := json.Unmarshal(request, &decoded); err != nil || len(decoded.Messages) != 1 || decoded.Messages[0].Role != "user" || len(decoded.Messages[0].Content) != 1 || decoded.Messages[0].Content[0].Text != "hi" {
+ t.Fatalf("request=%s err=%v", request, err)
+ }
+}
+
+func TestWasmTrapIncludesGuestPanicMessage(t *testing.T) {
+ runtime, err := newWasmRuntime()
+ if err != nil {
+ t.Fatal(err)
+ }
+ defer runtime.closeAll()
+ guest, err := runtime.newModule(context.Background())
+ if err != nil {
+ t.Fatal(err)
+ }
+ _, err = guest.call(context.Background(), "sy_alloc", uint64(^uint32(0)))
+ if !isWasmTrap(err) || !strings.Contains(err.Error(), "panicked") {
+ t.Fatalf("guest panic returned %v", err)
+ }
+}
+
+func TestWasmTranslatorIsReplacedAfterFailure(t *testing.T) {
+ input := []byte(`{"format":"openai_chat","body":{"messages":[{"role":"user","content":"hi"}]}}`)
+ if _, err := wasmTranslate("sy_decode_request", input); err != nil {
+ t.Fatal(err)
+ }
+ translator := defaultWasmTranslator.value
+ translator.mu.Lock()
+ err := translator.guest.module.Close(context.Background())
+ translator.mu.Unlock()
+ if err != nil {
+ t.Fatal(err)
+ }
+ if _, err := wasmTranslate("sy_decode_request", input); err == nil {
+ t.Fatal("translation on a closed instance succeeded")
+ }
+ if _, err := wasmTranslate("sy_decode_request", input); err != nil {
+ t.Fatalf("translator was not replaced: %v", err)
+ }
+}