Files
zip/runtime/bundle_test.go
zeekayandGitHub 8d4e50c665 feat(runtime): embed goja + esbuild; ZAP-over-HTTP transport (#9)
* feat(runtime): embed goja + esbuild; add ZAP-over-HTTP transport

Establish zip as the canonical Hanzo Go web framework with embedded
in-process JS execution and a native ZAP RPC HTTP transport. One Go
binary mounts native handlers, legacy TS/JS handlers, WebSocket, and
the ZAP RPC plane — no separate runtime service, no inter-service RPC,
no container-per-service.

zip/runtime/ (new):
- jsvm.go    NewJSRuntime / Eval / RegisterHostFn / LoadModule, backed
             by a pool of *goja.Runtime (pure Go, no CGO). Pool pattern
             lifted from hanzoai/base/plugins/gojavm, slimmed to run +
             forEach so late host-fn / module registration reaches warm
             VMs.
- pool.go    fixed-size goja VM pool; saturated calls fall back to a
             fully-provisioned one-off VM.
- require.go CommonJS-style require(): per-VM module sources + memoized
             exports in a Go-side side-table (never visible to JS).
- esbuild.go TranspileToES5: TS/modern-JS -> goja-ready JS via esbuild's
             pure-Go API (ES2015 target, CommonJS format).
- handler.go JSHandler / JSModule: mount an Express-shaped (req, res) JS
             function as a fiber.Handler; req mirrors method/path/query/
             headers/body, res mirrors status/set/json/send.
- json.go    encode/decode through internal/jsonenc — one wire format.

zip/zaprpc/ (new on existing Registry seam):
- envelope.go canonical ZAP RPC frame (service/method/payload) over the
              zap-proto/go wire codec.
- http.go     HTTPHandler(reg): serves the ZAP RPC plane over HTTP POST;
              binary envelope canonical, X-ZAP-* headers are a hint only.

examples/express-in-zip/ (new): legacy app.ts -> real esbuild -> real
goja -> real Fiber -> real HTTP, with an integration test proving
GET /legacy/foo and POST /legacy/bar body echo.

README: embedded-JS migration path + single-binary (HIP-0106) sections.

go build ./... and go test ./... (incl. -race) pass.

* feat(runtime): ctx-aware Eval + multi-file BundleToES2015

Two consumer-integration follow-ups so callers (base's gojavm) stop
reaching past the runtime abstraction.

EvalContext(ctx, src): interrupt a running goja VM when ctx fires.
A watcher goroutine calls vm.Interrupt(ctx.Err()) on ctx.Done(); the
resulting *goja.InterruptedError is unwrapped back to ctx.Err(). The
watcher is joined and ClearInterrupt() is called before the VM is
returned to the pool, so a borrowed VM is never left interrupted.
Eval routes through EvalContext(context.Background()). InvokeFunc(ctx,
fnName, args...) calls a named global JS function under the same
cancellation discipline. This lets base drop the goroutine+timeout race
around Invoke.

BundleToES2015(entry, files, opts): transpile + bundle a multi-file
TS/JS tree from an in-memory files map using esbuild's pure-Go Build
API with an onResolve/onLoad plugin serving a virtual namespace — no
real FS access, no CGO. Relative imports resolve against the importer's
dir; opts.External keeps bare specifiers as require()/import calls for
goja to resolve at runtime. This replaces consumers importing esbuild's
api package directly to bundle.

Tests (go test -race clean):
- EvalContext(50ms, while(true){}) returns DeadlineExceeded in ~50ms
- successful eval returns the value; VM reusable afterwards
- two-file CommonJS bundle runs in goja, entry.run() === 42
- external dep stays require("external") and resolves via host module

* feat(runtime): unified multi-language Runner over the extruntime SPI

Add Runner — a registry of language → Engine that executes arbitrary-
language source in goroutine-scoped, context.Context-bound tasks. Each
Run spawns a worker (engine.Eval) and a watcher (ctx.Done() → engine
interrupt), joining both before return so a borrowed VM is never handed
back to its pool while still interrupted. This generalizes the settled
JSRuntime.EvalContext cancellation contract (one worker, one watcher,
joined, engine-specific interrupt) across every backend a host registers.

zip ships exactly one in-tree engine: the pure-Go goja engine, surfaced
via (*JSRuntime).Engine() and registered as "js". It self-manages ctx
inside EvalContext (per-call interrupt on the exact borrowed VM), so the
Runner's watcher is a benign no-op for it. base's backends (pyvm, v8vm,
wasmvm, starkvm) plug in through the same Engine seam via thin extruntime
adapters at app startup — the registry is the seam, not an import edge.
zip never imports base; the dependency direction stays base → zip.

Engine is the zip-side projection of base's extruntime backends: any
value implementing Eval(ctx, src, args) satisfies it. Optional
Interruptible lets the watcher abort a runaway eval out-of-band.

Wire the unified runner into examples/express-in-zip: POST /runtime/:lang
reads the body as source, dispatches to the engine for :lang, returns
{result} or 404 {error:"unknown language"}.

Tests (go test -race, all green):
  - JS happy path: Run(ctx, "js", "1+2") → int64(3)
  - JS function call: define + invoke in one eval
  - JS ctx deadline: while(true){} interrupted, DeadlineExceeded, ~50ms
  - unknown language: ErrUnknownLanguage sentinel, no panic
  - concurrent: 100 goroutines, registry RWMutex + per-call VM isolation
  - example: POST /runtime/js "40+2" → {"result":42}; cobol → 404

No cgo. No base import. README documents the Runner + SPI registration.
2026-06-16 16:05:27 -07:00

128 lines
3.5 KiB
Go

package runtime
import (
"strings"
"testing"
)
// A two-file CommonJS tree (entry.js requires ./util.js) bundles to a
// single ES2015 string that runs in goja and produces the expected value.
func TestBundleToES2015_TwoFileCommonJS(t *testing.T) {
files := map[string][]byte{
"util.js": []byte(`
module.exports.triple = function (n) { return n * 3; };
`),
"entry.js": []byte(`
const util = require("./util.js");
module.exports.run = function () { return util.triple(14); };
`),
}
out, err := BundleToES2015("entry.js", files, BundleOptions{Format: "cjs"})
if err != nil {
t.Fatal(err)
}
rt, _ := NewJSRuntime(JSOptions{PoolSize: 1})
if err := rt.LoadModule("bundle", string(out)); err != nil {
t.Fatal(err)
}
v, err := rt.Eval(`require("bundle").run()`)
if err != nil {
t.Fatal(err)
}
if got, ok := v.(int64); !ok || got != 42 {
t.Fatalf("entry.run() = %v (%T), want int64(42)", v, v)
}
t.Logf("two-file bundle: entry.run() == %d (want 42)", v)
}
// TypeScript across files bundles and strips types.
func TestBundleToES2015_TypeScriptTree(t *testing.T) {
files := map[string][]byte{
"math.ts": []byte(`export const square = (n: number): number => n * n;`),
"entry.ts": []byte(`
import { square } from "./math";
module.exports.run = (): number => square(7);
`),
}
out, err := BundleToES2015("entry.ts", files, BundleOptions{Format: "cjs"})
if err != nil {
t.Fatal(err)
}
if strings.Contains(string(out), ": number") {
t.Fatalf("types not stripped: %s", out)
}
rt, _ := NewJSRuntime(JSOptions{PoolSize: 1})
if err := rt.LoadModule("b", string(out)); err != nil {
t.Fatal(err)
}
v, err := rt.Eval(`require("b").run()`)
if err != nil {
t.Fatal(err)
}
if got := v.(int64); got != 49 {
t.Fatalf("run() = %d, want 49", got)
}
}
// An external dependency must stay as a require("external") call in the
// output rather than being inlined (it is not in the files map).
func TestBundleToES2015_ExternalStaysRequire(t *testing.T) {
files := map[string][]byte{
"entry.js": []byte(`
const ext = require("external");
module.exports.run = function () { return ext.value; };
`),
}
out, err := BundleToES2015("entry.js", files, BundleOptions{
Format: "cjs",
External: []string{"external"},
})
if err != nil {
t.Fatal(err)
}
if !strings.Contains(string(out), `require("external")`) {
t.Fatalf("external not preserved as require: %s", out)
}
t.Logf(`external preserved: output contains require("external")`)
// And it must actually resolve through goja's require() to the host
// module registered under the same name.
rt, _ := NewJSRuntime(JSOptions{
PoolSize: 1,
Modules: map[string]string{"external": `module.exports = { value: 99 };`},
})
if err := rt.LoadModule("bundle", string(out)); err != nil {
t.Fatal(err)
}
v, err := rt.Eval(`require("bundle").run()`)
if err != nil {
t.Fatal(err)
}
if got := v.(int64); got != 99 {
t.Fatalf("run() = %d, want 99 (from external module)", got)
}
}
// A missing entry is a clear error, not a panic.
func TestBundleToES2015_MissingEntry(t *testing.T) {
_, err := BundleToES2015("nope.js", map[string][]byte{"a.js": []byte("1")}, BundleOptions{})
if err == nil {
t.Fatal("expected error for missing entry, got nil")
}
}
// An unresolved relative import is reported as an error.
func TestBundleToES2015_UnresolvedImport(t *testing.T) {
files := map[string][]byte{
"entry.js": []byte(`require("./missing.js");`),
}
_, err := BundleToES2015("entry.js", files, BundleOptions{})
if err == nil {
t.Fatal("expected error for unresolved import, got nil")
}
}