feat(truapi-codegen): emit Rust dispatcher, wire table, and host callbacks

Extends the rustdoc-JSON code generator to emit the Rust dispatcher and wire
table consumed by truapi-server, plus the TS host-callbacks adapter. Golden
tests pin the emitted shapes.

Author: pgherveou

Cargo.lock

@@ -1,6 +1,7 @@
 [workspace]
 resolver = "2"
 members = ["rust/crates/*"]
+exclude = ["rust/crates/truapi-server"]
 
 [workspace.package]
 edition = "2024"

Cargo.toml

@@ -2,12 +2,16 @@ import type { Result } from "neverthrow";
 import { describe, expect, it } from "bun:test";
 
 import { createTransport } from "./client.js";
-import { indexedTaggedUnion, Result as ScaleResult, str, _void } from "./scale.js";
+import { CallError, indexedTaggedUnion, Result as ScaleResult, str, _void } from "./scale.js";
+import type { Codec } from "./scale.js";
 import { createClient, SubscriptionError } from "./generated/client.js";
 import * as T from "./generated/types.js";
 import * as W from "./generated/wire-table.js";
 import { encodeWireMessage } from "./transport.js";
 
+/** Wrap a codec in the `{ V1: [0, codec] }` indexed-tagged-union envelope. */
+const versionedV1 = <T>(codec: Codec<T>) => indexedTaggedUnion({ V1: [0, codec] });
+
 function toHex(u: Uint8Array): string {
     return Array.from(u)
         .map((b) => b.toString(16).padStart(2, "0"))
@@ -56,9 +60,34 @@ function providerFixture() {
 
 /** Encode a V1 host-handshake response result payload. */
 function handshakeResponsePayload(value: { success: true; value: undefined }): Uint8Array {
-    return indexedTaggedUnion({
-        V1: [0, ScaleResult(_void, T.HostHandshakeError)],
-    }).enc({ tag: "V1", value });
+    return versionedV1(ScaleResult(_void, CallError(T.VersionedHostHandshakeError))).enc({
+        tag: "V1",
+        value,
+    });
+}
+
+function accountGetResponsePayload(
+    value:
+        | {
+              success: true;
+              value: T.HostAccountGetResponse;
+          }
+        | {
+              success: false;
+              value: { tag: "Domain"; value: T.VersionedHostAccountGetError };
+          },
+): Uint8Array {
+    return versionedV1(
+        ScaleResult(T.HostAccountGetResponse, CallError(T.VersionedHostAccountGetError)),
+    ).enc({ tag: "V1", value });
+}
+
+/** Encode a raw testing echo error response payload. */
+function testingEchoErrorPayload(reason: string): Uint8Array {
+    return ScaleResult(_void, CallError(T.V01TestingVersionProbeError)).enc({
+        success: false,
+        value: { tag: "HostFailure", value: { reason } },
+    });
 }
 
 describe("generated client transport", () => {
@@ -88,6 +117,29 @@ describe("generated client transport", () => {
         expect(toHex(fixture.sent[0])).toBe(toHex(expectedFrame));
     });
 
+    it("uses the latest generated request version for testing probes", () => {
+        const fixture = providerFixture();
+        const transport = createTransport(fixture.provider);
+        const client = createClient(transport);
+
+        const request = {
+            message: "hello from test",
+            marker: 42,
+        };
+        void client.testing.versionProbe(request);
+
+        const expectedPayload = T.VersionedTestingVersionProbeRequest.enc({
+            tag: "V2",
+            value: request,
+        });
+        const expectedFrame = new Uint8Array(str.enc("p:1").length + 1 + expectedPayload.length);
+        expectedFrame.set(str.enc("p:1"), 0);
+        expectedFrame[str.enc("p:1").length] = W.TESTING_VERSION_PROBE.request;
+        expectedFrame.set(expectedPayload, str.enc("p:1").length + 1);
+
+        expect(toHex(fixture.sent[0])).toBe(toHex(expectedFrame));
+    });
+
     it("uses the transport codec version for generated handshake calls", () => {
         const fixture = providerFixture();
         const transport = createTransport(fixture.provider);
@@ -129,6 +181,63 @@ describe("generated client transport", () => {
         expect(result.isOk()).toBe(true);
     });
 
+    it("decodes request domain errors from the versioned response envelope", async () => {
+        const fixture = providerFixture();
+        const transport = createTransport(fixture.provider);
+        const client = createClient(transport);
+
+        const response = client.account.getAccount({
+            productAccountId: { dotNsIdentifier: "foo", derivationIndex: 0 },
+        });
+        const reason = { tag: "V1", value: { tag: "NotConnected", value: undefined } } as const;
+        const frame = unwrap(
+            encodeWireMessage({
+                requestId: "p:1",
+                payload: {
+                    id: W.ACCOUNT_GET_ACCOUNT.response,
+                    value: accountGetResponsePayload({
+                        success: false,
+                        value: { tag: "Domain", value: reason },
+                    }),
+                },
+            }),
+            "encode account_get error response",
+        );
+        fixture.receive(frame);
+
+        const result = await response;
+        expect(result.isErr()).toBe(true);
+        expect(result._unsafeUnwrapErr()).toEqual({ tag: "Domain", value: reason });
+    });
+
+    it("returns framework call errors as typed Err values", async () => {
+        const fixture = providerFixture();
+        const transport = createTransport(fixture.provider);
+        const client = createClient(transport);
+
+        const response = client.testing.echoError({
+            error: { tag: "HostFailure", value: { reason: "forced by test" } },
+        });
+        const frame = unwrap(
+            encodeWireMessage({
+                requestId: "p:1",
+                payload: {
+                    id: W.TESTING_ECHO_ERROR.response,
+                    value: testingEchoErrorPayload("forced by test"),
+                },
+            }),
+            "encode testing framework error response",
+        );
+        fixture.receive(frame);
+
+        const result = await response;
+        expect(result.isErr()).toBe(true);
+        expect(result._unsafeUnwrapErr()).toEqual({
+            tag: "HostFailure",
+            value: { reason: "forced by test" },
+        });
+    });
+
     it("auto-responds to an inbound handshake with the versioned-result shape", () => {
         const fixture = providerFixture();
         createTransport(fixture.provider);
@@ -225,14 +334,18 @@ describe("generated client transport", () => {
         });
 
         const reason = { tag: "PermissionDenied", value: undefined } as const;
+        const callError = {
+            tag: "Domain",
+            value: { tag: "V1", value: reason },
+        } as const;
         const frame = unwrap(
             encodeWireMessage({
                 requestId: sub.subscriptionId,
                 payload: {
                     id: W.PAYMENT_BALANCE_SUBSCRIBE.interrupt,
-                    value: T.VersionedHostPaymentBalanceSubscribeError.enc({
+                    value: versionedV1(CallError(T.VersionedHostPaymentBalanceSubscribeError)).enc({
                         tag: "V1",
-                        value: reason,
+                        value: callError,
                     }),
                 },
             }),
@@ -243,7 +356,7 @@ describe("generated client transport", () => {
         expect(completions).toEqual([]);
         expect(errors).toHaveLength(1);
         expect(errors[0]).toBeInstanceOf(SubscriptionError);
-        expect((errors[0] as SubscriptionError).reason).toEqual(reason);
+        expect((errors[0] as SubscriptionError).reason).toEqual(callError);
         expect(fixture.sent).toHaveLength(1);
     });
 
@@ -258,15 +371,18 @@ describe("generated client transport", () => {
             .subscribe({ error: (error) => errors.push(error) });
 
         const reason = "Denied";
+        const callError = {
+            tag: "Domain",
+            value: { tag: "V1", value: reason },
+        } as const;
         const frame = unwrap(
             encodeWireMessage({
                 requestId: sub.subscriptionId,
                 payload: {
                     id: W.COIN_PAYMENT_REBALANCE_PURSE.interrupt,
-                    value: T.VersionedHostCoinPaymentRebalancePurseError.enc({
-                        tag: "V1",
-                        value: reason,
-                    }),
+                    value: versionedV1(
+                        CallError(T.VersionedHostCoinPaymentRebalancePurseError),
+                    ).enc({ tag: "V1", value: callError }),
                 },
             }),
             "encode typed coin payment interrupt",
@@ -275,7 +391,7 @@ describe("generated client transport", () => {
 
         expect(errors).toHaveLength(1);
         expect(errors[0]).toBeInstanceOf(SubscriptionError);
-        expect((errors[0] as SubscriptionError).reason).toEqual(reason);
+        expect((errors[0] as SubscriptionError).reason).toEqual(callError);
     });
 
     it("treats a malformed receive payload as terminal and sends _stop", () => {

js/packages/truapi/src/client.test.ts

@@ -0,0 +1,2 @@
+# Mismatch dumps written by tests/golden_rust_emit.rs for local inspection.
+tests/golden/*.actual

rust/crates/truapi-codegen/.gitignore

@@ -17,3 +17,6 @@ anyhow = "1"
 clap = { version = "4", features = ["derive"] }
 indoc = "2"
 convert_case = "0.6"
+
+[dev-dependencies]
+tempfile = "3"