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/.gitignoreindex 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 / packagingleaderboard/diff --git a/bindings/go/README.md b/bindings/go/README.mdindex 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. Yourapplication 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 isa 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:```shcargo 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 pathbelow with its absolute location:@@ -26,6 +36,10 @@ Native builds link `target/release/libswitchyard_ffi.a` into the Go host artifacThe 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:```shcd 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 notmake it a recommended production toolchain.diff --git a/bindings/go/backend_native.go b/bindings/go/backend_native.gonew file mode 100644index 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.gonew file mode 100644index 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.goindex 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 syGoNextfunc 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.modindex 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 // indirectdiff --git a/bindings/go/go.sum b/bindings/go/go.sumnew file mode 100644index 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.goindex 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.statestate.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.goindex 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.goindex 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.gonew file mode 100644index 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.gonew file mode 100644index 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.gonew file mode 100644index 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)+ }+}