@parity/product-sdk-host 0.16.0 → 0.18.0

package/src/index.ts

@@ -57,6 +57,11 @@ export type {
 export { getHostChainInfo } from "./chain-discovery.js";
 export type { HostChainDiscovery, HostChainIdentifier } from "./chain-discovery.js";
 
+// Host-channel connection status — the transport's own signal. Distinct from
+// @parity/product-sdk-signer's ConnectionStatus, which tracks a signer provider.
+export { subscribeConnectionStatus } from "./transport.js";
+export type { HostConnectionStatus } from "./transport.js";
+
 // Result type + typed host errors (the throw→Result boundary)
 export { ok, err } from "./result.js";
 export type { Result } from "./result.js";
@@ -65,6 +70,7 @@ export {
     HostError,
     HostUnavailableError,
     HostCallFailedError,
+    HostResponseDecodeError,
     isHostError,
     formatHostError,
 } from "./errors.js";
@@ -74,6 +80,7 @@ export type { HostErrorPayload } from "./errors.js";
 export { getAccountsProvider, findRingVrfKeyHandle } from "./accounts.js";
 export type {
     AccountsProvider,
+    WithDecodeError,
     DerivationIndex,
     HostAccount,
     ProductAccount,

package/src/papi-provider.ts

@@ -61,6 +61,38 @@ const JSON_RPC_METHOD_NOT_FOUND = -32601;
 /** A `chainHead_v1_followEvent` payload (loosely typed — consumed by PAPI's substrate-client). */
 type FollowEvent = { event: string } & Record<string, unknown>;
 
+type BufferedOperation = {
+    announced: boolean;
+    items: RemoteChainHeadFollowItem[];
+};
+
+/** Return the operation id carried by an operation follow item. */
+function followOperationId(item: RemoteChainHeadFollowItem): string | undefined {
+    switch (item.tag) {
+        case "OperationBodyDone":
+        case "OperationCallDone":
+        case "OperationStorageItems":
+        case "OperationStorageDone":
+        case "OperationWaitingForContinue":
+        case "OperationInaccessible":
+        case "OperationError":
+            return item.value.operationId;
+        default:
+            return undefined;
+    }
+}
+
+/** Whether this item closes its operation. */
+function isTerminalOperationItem(item: RemoteChainHeadFollowItem): boolean {
+    return (
+        item.tag === "OperationBodyDone" ||
+        item.tag === "OperationCallDone" ||
+        item.tag === "OperationStorageDone" ||
+        item.tag === "OperationInaccessible" ||
+        item.tag === "OperationError"
+    );
+}
+
 /** Map a JSON-RPC storage query-type string to the truapi `StorageQueryType` tag. */
 const STORAGE_TYPE_MAP: Record<string, StorageQueryType> = {
     value: "Value",
@@ -194,6 +226,8 @@ export function createHostPapiProvider(
     return (onMessage: (message: JsonRpcMessage) => void): JsonRpcConnection => {
         const activeFollows = new Map<string, TransportSubscription>();
         const activeBroadcasts = new Set<string>();
+        const followOperations = new Map<string, Map<string, BufferedOperation>>();
+        const pendingOperationStarts = new Map<string, number>();
 
         function sendJsonRpcResponse(id: JsonRpcRequest["id"], result: unknown): void {
             onMessage({ jsonrpc: "2.0", id, result } as JsonRpcMessage);
@@ -209,6 +243,96 @@ export function createHostPapiProvider(
             } as JsonRpcMessage);
         }
 
+        function forwardFollowItem(
+            followSubscriptionId: string,
+            item: RemoteChainHeadFollowItem,
+        ): void {
+            const operationId = followOperationId(item);
+            if (operationId === undefined) {
+                sendFollowEvent(followSubscriptionId, convertFollowEventToJsonRpc(item));
+                return;
+            }
+
+            const operations = followOperations.get(followSubscriptionId);
+            if (!operations) return;
+
+            let operation = operations.get(operationId);
+            if (!operation) {
+                // A missing entry also means the operation already ended — the spec and
+                // PAPI's cancel path still emit then. With no start outstanding nothing
+                // can announce those, so buffering would strand them until unfollow.
+                if ((pendingOperationStarts.get(followSubscriptionId) ?? 0) === 0) {
+                    sendFollowEvent(followSubscriptionId, convertFollowEventToJsonRpc(item));
+                    return;
+                }
+                operation = { announced: false, items: [] };
+                operations.set(operationId, operation);
+            }
+            if (!operation.announced) {
+                operation.items.push(item);
+                return;
+            }
+
+            sendFollowEvent(followSubscriptionId, convertFollowEventToJsonRpc(item));
+            if (isTerminalOperationItem(item)) {
+                operations.delete(operationId);
+            }
+        }
+
+        function sendOperationStartedResponse(
+            id: JsonRpcRequest["id"],
+            followSubscriptionId: string,
+            result: OperationStartedResult,
+        ): void {
+            // The JSON-RPC response must be observable before any event naming its
+            // operation. TrUAPI request and subscription frames are independent,
+            // so a fast operation can complete before this request resolves.
+            sendJsonRpcResponse(id, convertOperationResultToJsonRpc(result));
+            if (result.tag !== "Started") return;
+
+            const operations = followOperations.get(followSubscriptionId);
+            if (!operations) return;
+
+            const operationId = result.value.operationId;
+            let operation = operations.get(operationId);
+            if (!operation) {
+                operation = { announced: true, items: [] };
+                operations.set(operationId, operation);
+                return;
+            }
+
+            operation.announced = true;
+            const pendingItems = operation.items;
+            operation.items = [];
+            for (const item of pendingItems) {
+                forwardFollowItem(followSubscriptionId, item);
+            }
+        }
+
+        // Both arms must clear the count: a failed start never sends `Started`, and a
+        // stuck count buffers forever.
+        function startOperationRequest(id: JsonRpcRequest["id"], followSubscriptionId: string) {
+            const pending = pendingOperationStarts.get(followSubscriptionId);
+            if (pending !== undefined) {
+                pendingOperationStarts.set(followSubscriptionId, pending + 1);
+            }
+            const settle = () => {
+                const outstanding = pendingOperationStarts.get(followSubscriptionId);
+                if (outstanding === undefined) return;
+                pendingOperationStarts.set(followSubscriptionId, Math.max(0, outstanding - 1));
+            };
+            return {
+                ok: (response: { operation: OperationStartedResult }) => {
+                    settle();
+                    sendOperationStartedResponse(id, followSubscriptionId, response.operation);
+                },
+                err: (error: unknown) => {
+                    settle();
+                    hostError(id)(error);
+                },
+            };
+        }
+
         /** Reject an inbound request with the host's error reason as the JSON-RPC message. */
         const hostError = (id: JsonRpcRequest["id"]) => (error: unknown) =>
             sendJsonRpcError(id, JSON_RPC_INTERNAL_ERROR, formatHostError(error));
@@ -234,8 +358,10 @@ export function createHostPapiProvider(
                     ) => {
                         if (item.tag === "Stop" && activeFollows.delete(followSubscriptionId)) {
                             ref.handle?.unsubscribe();
+                            followOperations.delete(followSubscriptionId);
+                            pendingOperationStarts.delete(followSubscriptionId);
                         }
-                        sendFollowEvent(followSubscriptionId, convertFollowEventToJsonRpc(item));
+                        forwardFollowItem(followSubscriptionId, item);
                     };
                     ref.handle = subscribeWithInterrupt(
                         chain.followHeadSubscribe({ request: { genesisHash, withRuntime } }),
@@ -261,11 +387,15 @@ export function createHostPapiProvider(
                     // A transport interrupt/close ends the stream without a Stop
                     // item; synthesize one so the consumer refollows.
                     ref.handle.onInterrupt(() => {
+                        followOperations.delete(followSubscriptionId);
+                        pendingOperationStarts.delete(followSubscriptionId);
                         if (activeFollows.delete(followSubscriptionId)) {
                             sendFollowEvent(followSubscriptionId, { event: "stop" });
                         }
                     });
                     activeFollows.set(followSubscriptionId, ref.handle);
+                    followOperations.set(followSubscriptionId, new Map());
+                    pendingOperationStarts.set(followSubscriptionId, 0);
                     sendJsonRpcResponse(id, followSubscriptionId);
                     for (const item of pendingItems) {
                         forwardItem(followSubscriptionId, item);
@@ -279,6 +409,8 @@ export function createHostPapiProvider(
                         follow.unsubscribe();
                         activeFollows.delete(followSubId);
                     }
+                    followOperations.delete(followSubId);
+                    pendingOperationStarts.delete(followSubId);
                     sendJsonRpcResponse(id, null);
                     break;
                 }
@@ -294,16 +426,10 @@ export function createHostPapiProvider(
                 }
                 case "chainHead_v1_body": {
                     const [followSubscriptionId, hash] = params as [string, HexString];
+                    const bodyStart = startOperationRequest(id, followSubscriptionId);
                     chain
                         .getHeadBody({ genesisHash, followSubscriptionId, hash })
-                        .match(
-                            (response) =>
-                                sendJsonRpcResponse(
-                                    id,
-                                    convertOperationResultToJsonRpc(response.operation),
-                                ),
-                            hostError(id),
-                        );
+                        .match(bodyStart.ok, bodyStart.err);
                     break;
                 }
                 case "chainHead_v1_storage": {
@@ -317,6 +443,7 @@ export function createHostPapiProvider(
                         key: item.key,
                         queryType: convertStorageType(item.type),
                     }));
+                    const storageStart = startOperationRequest(id, followSubscriptionId);
                     chain
                         .getHeadStorage({
                             genesisHash,
@@ -330,14 +457,7 @@ export function createHostPapiProvider(
                             // (`null.startsWith`). Coerce `null` → `undefined`.
                             childTrie: childTrie ?? undefined,
                         })
-                        .match(
-                            (response) =>
-                                sendJsonRpcResponse(
-                                    id,
-                                    convertOperationResultToJsonRpc(response.operation),
-                                ),
-                            hostError(id),
-                        );
+                        .match(storageStart.ok, storageStart.err);
                     break;
                 }
                 case "chainHead_v1_call": {
@@ -347,6 +467,7 @@ export function createHostPapiProvider(
                         string,
                         HexString,
                     ];
+                    const callStart = startOperationRequest(id, followSubscriptionId);
                     chain
                         .callHead({
                             genesisHash,
@@ -355,14 +476,7 @@ export function createHostPapiProvider(
                             function: fn,
                             callParameters,
                         })
-                        .match(
-                            (response) =>
-                                sendJsonRpcResponse(
-                                    id,
-                                    convertOperationResultToJsonRpc(response.operation),
-                                ),
-                            hostError(id),
-                        );
+                        .match(callStart.ok, callStart.err);
                     break;
                 }
                 case "chainHead_v1_unpin": {
@@ -387,7 +501,10 @@ export function createHostPapiProvider(
                     const [followSubscriptionId, operationId] = params as [string, string];
                     chain
                         .stopHeadOperation({ genesisHash, followSubscriptionId, operationId })
-                        .match(() => sendJsonRpcResponse(id, null), hostError(id));
+                        .match(() => {
+                            followOperations.get(followSubscriptionId)?.delete(operationId);
+                            sendJsonRpcResponse(id, null);
+                        }, hostError(id));
                     break;
                 }
                 case "chainSpec_v1_genesisHash": {
@@ -467,6 +584,8 @@ export function createHostPapiProvider(
                     handle.unsubscribe();
                 }
                 activeFollows.clear();
+                followOperations.clear();
+                pendingOperationStarts.clear();
                 for (const operationId of activeBroadcasts) {
                     // Fire-and-forget: the transport may already be torn down.
                     chain.stopTransaction({ genesisHash, operationId }).match(
@@ -491,6 +610,8 @@ if (import.meta.vitest) {
         responses?: Record<string, unknown>;
         /** Methods named here resolve to their `.match` error arm carrying the given value. */
         errors?: Record<string, unknown>;
+        /** Capture selected successful matches so tests can resolve them after follow events. */
+        deferMatch?: (method: string, resolve: () => unknown) => boolean;
         /** Unsubscribe spy used by the follow subscription (defaults to a fresh `vi.fn()`). */
         unsubscribe?: () => void;
         /** Item emitted synchronously while the transport subscription starts. */
@@ -503,16 +624,20 @@ if (import.meta.vitest) {
         /** Transport request id assigned to the follow subscription. */
         subscriptionId?: string;
     }) {
-        const okMatch = (value: unknown) => ({
-            match: (ok: (v: unknown) => unknown, _err: (e: unknown) => unknown) => ok(value),
-        });
         const errMatch = (error: unknown) => ({
             match: (_ok: (v: unknown) => unknown, err: (e: unknown) => unknown) => err(error),
         });
         const method = (name: string, response: unknown) => (args: unknown) => {
             opts.onCall?.(name, args);
             const errors = opts.errors ?? {};
-            return name in errors ? errMatch(errors[name]) : okMatch(response);
+            if (name in errors) return errMatch(errors[name]);
+            return {
+                match: (ok: (value: unknown) => unknown, _err: (error: unknown) => unknown) => {
+                    const resolve = () => ok(response);
+                    if (opts.deferMatch?.(name, resolve)) return undefined;
+                    return resolve();
+                },
+            };
         };
         return {
             chain: {
@@ -539,13 +664,22 @@ if (import.meta.vitest) {
                     "getHeadHeader",
                     opts.responses?.getHeadHeader ?? { header: "0x01" },
                 ),
-                getHeadBody: method("getHeadBody", {
-                    operation: { tag: "Started", value: { operationId: "op1" } },
-                }),
-                getHeadStorage: method("getHeadStorage", { operation: { tag: "LimitReached" } }),
-                callHead: method("callHead", {
-                    operation: { tag: "Started", value: { operationId: "op2" } },
-                }),
+                getHeadBody: method(
+                    "getHeadBody",
+                    opts.responses?.getHeadBody ?? {
+                        operation: { tag: "Started", value: { operationId: "op1" } },
+                    },
+                ),
+                getHeadStorage: method(
+                    "getHeadStorage",
+                    opts.responses?.getHeadStorage ?? { operation: { tag: "LimitReached" } },
+                ),
+                callHead: method(
+                    "callHead",
+                    opts.responses?.callHead ?? {
+                        operation: { tag: "Started", value: { operationId: "op2" } },
+                    },
+                ),
                 unpinHead: method("unpinHead", undefined),
                 continueHead: method("continueHead", undefined),
                 stopHeadOperation: method("stopHeadOperation", undefined),
@@ -628,6 +762,205 @@ if (import.meta.vitest) {
         ]);
     });
 
+    test("buffers a call completion until after its operation-start response", () => {
+        let observer:
+            | { next: (i: unknown) => void; error: (e: unknown) => void; complete: () => void }
+            | undefined;
+        let resolveCall: (() => unknown) | undefined;
+        const client = makeFakeClient({
+            responses: {
+                callHead: { operation: { tag: "Started", value: { operationId: "op-call" } } },
+            },
+            captureObserver: (value) => {
+                observer = value;
+            },
+            deferMatch: (method, resolve) => {
+                if (method !== "callHead") return false;
+                resolveCall = resolve;
+                return true;
+            },
+        });
+        const messages: JsonRpcMessage[] = [];
+        const conn = createHostPapiProvider(client, "0xfeed")((message) => messages.push(message));
+        conn.send({ jsonrpc: "2.0", id: 1, method: "chainHead_v1_follow", params: [false] });
+        messages.length = 0;
+
+        conn.send({
+            jsonrpc: "2.0",
+            id: 2,
+            method: "chainHead_v1_call",
+            params: ["p:41", "0xhash", "Test_call", "0x"],
+        });
+        observer?.next({
+            tag: "OperationCallDone",
+            value: { operationId: "op-call", output: "0x1234" },
+        });
+        expect(messages).toEqual([]);
+
+        resolveCall?.();
+        expect(messages).toEqual([
+            {
+                jsonrpc: "2.0",
+                id: 2,
+                result: { result: "started", operationId: "op-call" },
+            },
+            {
+                jsonrpc: "2.0",
+                method: "chainHead_v1_followEvent",
+                params: {
+                    subscription: "p:41",
+                    result: {
+                        event: "operationCallDone",
+                        operationId: "op-call",
+                        output: "0x1234",
+                    },
+                },
+            },
+        ]);
+    });
+
+    test("preserves buffered storage item order after announcing the operation", () => {
+        let observer:
+            | { next: (i: unknown) => void; error: (e: unknown) => void; complete: () => void }
+            | undefined;
+        let resolveStorage: (() => unknown) | undefined;
+        const client = makeFakeClient({
+            responses: {
+                getHeadStorage: {
+                    operation: { tag: "Started", value: { operationId: "op-storage" } },
+                },
+            },
+            captureObserver: (value) => {
+                observer = value;
+            },
+            deferMatch: (method, resolve) => {
+                if (method !== "getHeadStorage") return false;
+                resolveStorage = resolve;
+                return true;
+            },
+        });
+        const messages: JsonRpcMessage[] = [];
+        const conn = createHostPapiProvider(client, "0xfeed")((message) => messages.push(message));
+        conn.send({ jsonrpc: "2.0", id: 1, method: "chainHead_v1_follow", params: [false] });
+        messages.length = 0;
+
+        conn.send({
+            jsonrpc: "2.0",
+            id: 3,
+            method: "chainHead_v1_storage",
+            params: ["p:41", "0xhash", [{ key: "0x01", type: "value" }], null],
+        });
+        observer?.next({
+            tag: "OperationStorageItems",
+            value: {
+                operationId: "op-storage",
+                items: [{ key: "0x01", value: "0xabcd" }],
+            },
+        });
+        observer?.next({
+            tag: "OperationStorageDone",
+            value: { operationId: "op-storage" },
+        });
+        expect(messages).toEqual([]);
+
+        resolveStorage?.();
+        expect(
+            messages.map((message) => ("id" in message ? message.id : message.params.result.event)),
+        ).toEqual([3, "operationStorageItems", "operationStorageDone"]);
+    });
+
+    test("forwards an operation event that arrives after the operation ended", () => {
+        let observer:
+            | { next: (i: unknown) => void; error: (e: unknown) => void; complete: () => void }
+            | undefined;
+        const client = makeFakeClient({
+            responses: {
+                callHead: { operation: { tag: "Started", value: { operationId: "op-late" } } },
+            },
+            captureObserver: (value) => {
+                observer = value;
+            },
+        });
+        const messages: JsonRpcMessage[] = [];
+        const conn = createHostPapiProvider(client, "0xfeed")((message) => messages.push(message));
+        conn.send({ jsonrpc: "2.0", id: 1, method: "chainHead_v1_follow", params: [false] });
+        conn.send({
+            jsonrpc: "2.0",
+            id: 2,
+            method: "chainHead_v1_call",
+            params: ["p:41", "0xhash", "Test_call", "0x"],
+        });
+        observer?.next({
+            tag: "OperationCallDone",
+            value: { operationId: "op-late", output: "0x1" },
+        });
+        messages.length = 0;
+
+        observer?.next({
+            tag: "OperationStorageItems",
+            value: { operationId: "op-late", items: [{ key: "0x01", value: "0xabcd" }] },
+        });
+
+        expect(messages).toEqual([
+            {
+                jsonrpc: "2.0",
+                method: "chainHead_v1_followEvent",
+                params: {
+                    subscription: "p:41",
+                    result: {
+                        event: "operationStorageItems",
+                        operationId: "op-late",
+                        items: [{ key: "0x01", value: "0xabcd" }],
+                    },
+                },
+            },
+        ]);
+    });
+
+    test("a failed operation start releases the follow's buffering", () => {
+        let observer:
+            | { next: (i: unknown) => void; error: (e: unknown) => void; complete: () => void }
+            | undefined;
+        const client = makeFakeClient({
+            errors: { callHead: { reason: "host unavailable" } },
+            captureObserver: (value) => {
+                observer = value;
+            },
+        });
+        const messages: JsonRpcMessage[] = [];
+        const conn = createHostPapiProvider(client, "0xfeed")((message) => messages.push(message));
+        conn.send({ jsonrpc: "2.0", id: 1, method: "chainHead_v1_follow", params: [false] });
+        conn.send({
+            jsonrpc: "2.0",
+            id: 2,
+            method: "chainHead_v1_call",
+            params: ["p:41", "0xhash", "Test_call", "0x"],
+        });
+        messages.length = 0;
+
+        // A failed start never sends `Started`. If it left the count raised, every
+        // later event for an unknown operation would buffer for the life of the follow.
+        observer?.next({
+            tag: "OperationStorageItems",
+            value: { operationId: "op-unknown", items: [{ key: "0x01", value: "0xabcd" }] },
+        });
+
+        expect(messages).toEqual([
+            {
+                jsonrpc: "2.0",
+                method: "chainHead_v1_followEvent",
+                params: {
+                    subscription: "p:41",
+                    result: {
+                        event: "operationStorageItems",
+                        operationId: "op-unknown",
+                        items: [{ key: "0x01", value: "0xabcd" }],
+                    },
+                },
+            },
+        ]);
+    });
+
     test("chainSpec_v1_properties parses the JSON-encoded properties string", () => {
         const client = makeFakeClient({});
         const provider = createHostPapiProvider(client, "0xfeed");

package/src/testing.ts

@@ -26,9 +26,9 @@ import { errAsync, okAsync } from "neverthrow";
 
 import type { HostChainIdentifier } from "./chain-discovery.js";
 
-import { setTruApiClient } from "./transport.js";
+import { type HostConnectionStatus, emitConnectionStatus, setTruApiClient } from "./transport.js";
 
-export { setTruApiClient };
+export { setTruApiClient, emitConnectionStatus };
 
 /**
  * The public surface of a generated truapi domain client. `keyof` skips private
@@ -304,6 +304,12 @@ type TestFinishedHook = (fn: () => void) => void;
 export interface FakeHost extends Disposable {
     /** The injected fake client (also what `getTruApi()` returns). */
     client: TrUApiClient;
+    /**
+     * Push a status to `subscribeConnectionStatus` subscribers, so a product's
+     * reconnecting / offline UI can be exercised. `dispose()` already reports
+     * `"disconnected"`; use this to drive the states in between.
+     */
+    emitConnectionStatus(status: HostConnectionStatus): void;
     /** Clear the override. Idempotent; safe to call more than once. */
     dispose(): void;
     /** `using host = createFakeHost()` restores the real client at scope end. */
@@ -355,6 +361,7 @@ export function createFakeHost(options?: CreateFakeTruApiClientOptions): FakeHos
 
     return {
         client,
+        emitConnectionStatus,
         dispose,
         [Symbol.dispose]: dispose,
     };