feat(tunnel-native): embedded relay-tunnel receiver via napi-rs (WIP)

[slinkydeveloper]

WIP / draft. TypeScript/napi-rs sibling of the Java embedded relay-tunnel receiver. Reuses the same Rust engine as restatedev/sdk-shared-core#94 (branch relay, tunnel feature), consumed as a git dependency; swap to a crates.io release once that ships.

What

A new, separate package @restatedev/restate-sdk-tunnel-native that serves a Restate SDK deployment as a relay receiver using the embedded native engine (restate-sdk-shared-core, tunnel feature) via napi-rs — the same Rust engine the Java SDK drives over FFM. The engine dials the relay on its own tokio runtime and bridges each forwarded request over a loopback socket into a local node:http2 server, so SDK request dispatch — and therefore both the codegen SDK and the default promise API — is untouched. The napi boundary is control-plane only (start/status/stop); no per-request data crosses it.

This is not the pure-JS @restatedev/restate-sdk-tunnel package — the two are complementary and will be reconciled later.

Layout (packages/libs/restate-sdk-tunnel-native)

• Cargo.toml + build.rs + src/lib.rs: a napi crate exposing a #[napi] RelayTunnel class (start(configJson) / status() / stop()) over the engine's relay::{Config, Engine, Handle}. Depends on the shared-core relay branch with features = ["tunnel"] (same git dep as the sdk-java cdylib).
• src/index.ts: serveTunnel({ services, relay }) — wires at the shared createEndpointHandler({ services }) layer (accepts services from either programming model, exactly like serve()), boots a loopback-private node:http2 server on 127.0.0.1:0, and points the native engine at that port. Returns { localPort, status(), stop() }.
• Dual ESM/CJS via tsdown; the napi .cjs loader + .node stay external and gitignored (built locally via napi build).

napi-rs is set up from scratch here (the repo previously only had wasm-pack for the VM).

Verification

• napi build → a loadable host .node; RelayTunnel.start/status/stop work across the FFI (start→running, fast graceful stop, idempotent, bad-config throws).
• The wrapper type-checks against the real SDK + binding types and builds (dual ESM/CJS).
• Full round-trip smoke test passes: a fake relay (Node h2 client via role-flip) → native engine → serveTunnel's http2 server running a real restate.service (promise API) → forwarded /health → 200 "OK" → back, with the /whoami handshake (env/tunnel/api_key + auto instance_id) confirmed.

Deferred ("later" — packaging)

• Multi-platform prebuild matrix + optionalDependencies publishing + CI cross-compile (the standard napi-rs release flow).
• Restate Cloud /_/start-tunnel mode (the engine is /whoami-only, same as Java).
• Reconciliation with the pure-JS restate-sdk-tunnel package.
• Swapping the shared-core git dependency for a crates.io release.

Design/rationale: development/relay-receiver-napi-plan.md.

🤖 Generated with Claude Code