feat(truapi): add testing API and versioned wiring

Adds the canonical testing module (api/testing.rs) and its v01/v02/versioned
wiring used by the Rust host runtime and generated clients.

Author: pgherveou

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

@@ -86,7 +86,7 @@ describe("generated client transport", () => {
         expectedFrame.set(expectedPayload, str.enc("p:1").length + 1);
 
         expect(toHex(fixture.sent[0])).toBe(toHex(expectedFrame));
-        expect(transport.truapiVersion).toBe(1);
+        expect(transport.truapiVersion).toBe(2);
         expect(transport.codecVersion).toBe(1);
     });
 

rust/crates/truapi/src/api/mod.rs rust/crates/truapi/src/api.rsrust/crates/truapi/src/api/mod.rs renamed to rust/crates/truapi/src/api.rs

@@ -14,6 +14,8 @@ pub mod resource_allocation;
 pub mod signing;
 pub mod statement_store;
 pub mod system;
+#[cfg(debug_assertions)]
+pub mod testing;
 pub mod theme;
 
 pub use account::Account;
@@ -30,9 +32,12 @@ pub use resource_allocation::ResourceAllocation;
 pub use signing::Signing;
 pub use statement_store::StatementStore;
 pub use system::System;
+#[cfg(debug_assertions)]
+pub use testing::Testing;
 pub use theme::Theme;
 
 /// The unified TrUAPI contract.
+#[cfg(debug_assertions)]
 pub trait TrUApi:
     Account
     + Chain
@@ -48,12 +53,59 @@ pub trait TrUApi:
     + Signing
     + StatementStore
     + System
+    + Testing
     + Theme
     + Send
     + Sync
 {
 }
 
+#[cfg(not(debug_assertions))]
+pub trait TrUApi:
+    Account
+    + Chain
+    + Chat
+    + CoinPayment
+    + Entropy
+    + LocalStorage
+    + Notifications
+    + Payment
+    + Permissions
+    + Preimage
+    + ResourceAllocation
+    + Signing
+    + StatementStore
+    + System
+    + Theme
+    + Send
+    + Sync
+{
+}
+
+#[cfg(debug_assertions)]
+impl<T> TrUApi for T where
+    T: Account
+        + Chain
+        + Chat
+        + CoinPayment
+        + Entropy
+        + LocalStorage
+        + Notifications
+        + Payment
+        + Permissions
+        + Preimage
+        + ResourceAllocation
+        + Signing
+        + StatementStore
+        + System
+        + Testing
+        + Theme
+        + Send
+        + Sync
+{
+}
+
+#[cfg(not(debug_assertions))]
 impl<T> TrUApi for T where
     T: Account
         + Chain

rust/crates/truapi/src/api/statement_store.rs

@@ -6,7 +6,8 @@ use crate::versioned::statement_store::{
     RemoteStatementStoreCreateProofAuthorizedResponse, RemoteStatementStoreCreateProofError,
     RemoteStatementStoreCreateProofRequest, RemoteStatementStoreCreateProofResponse,
     RemoteStatementStoreSubmitError, RemoteStatementStoreSubmitRequest,
-    RemoteStatementStoreSubscribeItem, RemoteStatementStoreSubscribeRequest,
+    RemoteStatementStoreSubscribeError, RemoteStatementStoreSubscribeItem,
+    RemoteStatementStoreSubscribeRequest,
 };
 use crate::wire;
 use crate::{CallContext, CallError, Subscription};
@@ -56,8 +57,11 @@ pub trait StatementStore: Send + Sync {
         &self,
         _cx: &CallContext,
         _request: RemoteStatementStoreSubscribeRequest,
-    ) -> Subscription<RemoteStatementStoreSubscribeItem> {
-        Subscription::empty()
+    ) -> Result<
+        Subscription<RemoteStatementStoreSubscribeItem>,
+        CallError<RemoteStatementStoreSubscribeError>,
+    > {
+        Err(CallError::unavailable())
     }
 
     /// Create a proof for a statement.

rust/crates/truapi/src/api/testing.rs

@@ -0,0 +1,63 @@
+//! Debug-only API used to verify wire-version and framework-error handling.
+
+use crate::v01;
+use crate::v02;
+use crate::versioned::testing::{
+    TestingVersionProbeError, TestingVersionProbeRequest, TestingVersionProbeResponse,
+};
+use crate::wire;
+use crate::{CallContext, CallError};
+
+/// Development-only probes for generated client/runtime compatibility.
+pub trait Testing: Send + Sync {
+    /// Echo the request version back to the caller.
+    ///
+    /// ```ts
+    /// const result = await truapi.testing.versionProbe({
+    ///   message: "hello from V2",
+    ///   marker: 42,
+    /// });
+    /// assert(result.isOk(), "testing version probe failed:", result);
+    /// console.log("testing version probe:", result.value);
+    /// ```
+    #[wire(request_id = 164)]
+    async fn version_probe(
+        &self,
+        _cx: &CallContext,
+        request: TestingVersionProbeRequest,
+    ) -> Result<TestingVersionProbeResponse, CallError<TestingVersionProbeError>> {
+        match request {
+            TestingVersionProbeRequest::V1(inner) => Ok(TestingVersionProbeResponse::V1(
+                v01::TestingVersionProbeResponse {
+                    received_version: 1,
+                    message: inner.message,
+                },
+            )),
+            TestingVersionProbeRequest::V2(inner) => Ok(TestingVersionProbeResponse::V2(
+                v02::TestingVersionProbeResponse {
+                    received_version: 2,
+                    message: inner.message,
+                    marker: inner.marker,
+                },
+            )),
+        }
+    }
+
+    /// Echo a framework/domain error on the public response channel.
+    ///
+    /// ```ts
+    /// const result = await truapi.testing.echoError({
+    ///   error: { tag: "HostFailure", value: { reason: "forced by test" } },
+    /// });
+    /// assert(result.isErr(), "expected host failure");
+    /// console.log("echo error:", result.error);
+    /// ```
+    #[wire(request_id = 166)]
+    async fn echo_error(
+        &self,
+        _cx: &CallContext,
+        request: v01::EchoErrorRequest,
+    ) -> Result<(), CallError<v01::TestingVersionProbeError>> {
+        Err(request.error.into())
+    }
+}

rust/crates/truapi/src/lib.rs

@@ -1,30 +1,62 @@
 //! TrUAPI trait and type definitions for the host product SDK.
 //!
-//! Concrete wire types live in per-version modules (currently [`v01`]).
-//! Versioned envelopes are in [`versioned`].
+//! Concrete wire types live in per-version modules. Versioned envelopes are in
+//! [`versioned`].
 
 #![forbid(unsafe_code)]
 #![allow(async_fn_in_trait)]
 
-use std::convert::Infallible;
-use std::pin::Pin;
+use core::convert::Infallible;
+use core::pin::Pin;
+use core::task::{Context, Poll};
 use std::sync::Arc;
 use std::sync::atomic::{AtomicBool, Ordering};
-use std::task::{Context, Poll};
 
 use futures::Stream;
+use parity_scale_codec::{Decode, Encode};
 
 pub mod api;
 pub mod v01;
+#[cfg(debug_assertions)]
+pub mod v02;
 pub mod versioned;
 
+pub mod latest {
+    pub use crate::v01::{
+        AllocatableResource, GenericError, HostSignPayloadData, NotificationId, ProductAccountId,
+        RawPayload, RemotePermission, ThemeVariant,
+    };
+
+    pub type HostAccountGetAliasResponse = crate::v01::HostAccountGetAliasResponse;
+    pub type HostDevicePermissionRequest = crate::v01::HostDevicePermissionRequest;
+    pub type HostDevicePermissionResponse = crate::v01::HostDevicePermissionResponse;
+    pub type HostFeatureSupportedRequest = crate::v01::HostFeatureSupportedRequest;
+    pub type HostFeatureSupportedResponse = crate::v01::HostFeatureSupportedResponse;
+    pub type HostLocalStorageReadError = crate::v01::HostLocalStorageReadError;
+    pub type HostNavigateToError = crate::v01::HostNavigateToError;
+    pub type HostPushNotificationRequest = crate::v01::HostPushNotificationRequest;
+    pub type HostPushNotificationResponse = crate::v01::HostPushNotificationResponse;
+    pub type HostRequestResourceAllocationRequest =
+        crate::v01::HostRequestResourceAllocationRequest;
+    pub type HostSignPayloadRequest = crate::v01::HostSignPayloadRequest;
+    pub type HostSignPayloadWithLegacyAccountRequest =
+        crate::v01::HostSignPayloadWithLegacyAccountRequest;
+    pub type HostSignRawRequest = crate::v01::HostSignRawRequest;
+    pub type HostSignRawWithLegacyAccountRequest = crate::v01::HostSignRawWithLegacyAccountRequest;
+    pub type LegacyAccountTxPayload = crate::v01::LegacyAccountTxPayload;
+    pub type PreimageSubmitError = crate::v01::PreimageSubmitError;
+    pub type ProductAccountTxPayload = crate::v01::ProductAccountTxPayload;
+    pub type RemotePermissionRequest = crate::v01::RemotePermissionRequest;
+    pub type RemotePermissionResponse = crate::v01::RemotePermissionResponse;
+}
+
 pub use truapi_macros::wire;
 
 /// Per-message id carried from the transport frame.
 pub type RequestId = String;
 
 /// Framework-level outcomes shared by API methods.
-#[derive(Debug, Clone, PartialEq, Eq)]
+#[derive(Debug, Clone, PartialEq, Eq, Encode, Decode)]
 pub enum CallError<D> {
     /// Method-specific failure.
     Domain(D),

rust/crates/truapi/src/v01/mod.rs rust/crates/truapi/src/v01.rsrust/crates/truapi/src/v01/mod.rs renamed to rust/crates/truapi/src/v01.rs

@@ -15,6 +15,8 @@ mod resource_allocation;
 mod signing;
 mod statement_store;
 mod system;
+#[cfg(debug_assertions)]
+mod testing;
 mod theme;
 mod transaction;
 
@@ -33,5 +35,7 @@ pub use resource_allocation::*;
 pub use signing::*;
 pub use statement_store::*;
 pub use system::*;
+#[cfg(debug_assertions)]
+pub use testing::*;
 pub use theme::*;
 pub use transaction::*;

rust/crates/truapi/src/v01/testing.rs

@@ -0,0 +1,50 @@
+use parity_scale_codec::{Decode, Encode};
+
+use crate::CallError;
+
+/// V1 request payload for the debug-only Testing API.
+#[derive(Debug, Clone, PartialEq, Eq, Encode, Decode)]
+pub struct TestingVersionProbeRequest {
+    pub message: String,
+}
+
+/// Request payload for echoing a framework/domain error through the wire shape.
+#[derive(Debug, Clone, PartialEq, Eq, Encode, Decode)]
+pub struct EchoErrorRequest {
+    pub error: EchoError,
+}
+
+/// Debug-only mirror of [`CallError`] used as a request payload.
+#[derive(Debug, Clone, PartialEq, Eq, Encode, Decode)]
+pub enum EchoError {
+    Domain(TestingVersionProbeError),
+    Denied,
+    Unsupported,
+    MalformedFrame { reason: String },
+    HostFailure { reason: String },
+}
+
+impl From<EchoError> for CallError<TestingVersionProbeError> {
+    fn from(error: EchoError) -> Self {
+        match error {
+            EchoError::Domain(error) => Self::Domain(error),
+            EchoError::Denied => Self::Denied,
+            EchoError::Unsupported => Self::Unsupported,
+            EchoError::MalformedFrame { reason } => Self::MalformedFrame { reason },
+            EchoError::HostFailure { reason } => Self::HostFailure { reason },
+        }
+    }
+}
+
+/// V1 response payload for the debug-only Testing API.
+#[derive(Debug, Clone, PartialEq, Eq, Encode, Decode)]
+pub struct TestingVersionProbeResponse {
+    pub received_version: u8,
+    pub message: String,
+}
+
+/// Domain error for the debug-only Testing API.
+#[derive(Debug, Clone, PartialEq, Eq, Encode, Decode)]
+pub enum TestingVersionProbeError {
+    Unknown { reason: String },
+}

rust/crates/truapi/src/v02.rs

@@ -0,0 +1,5 @@
+//! TrUAPI Protocol v0.2 type definitions.
+
+mod testing;
+
+pub use testing::*;

rust/crates/truapi/src/v02/testing.rs

@@ -0,0 +1,22 @@
+use parity_scale_codec::{Decode, Encode};
+
+/// Request payload for the debug-only Testing API.
+#[derive(Debug, Clone, PartialEq, Eq, Encode, Decode)]
+pub struct TestingVersionProbeRequest {
+    pub message: String,
+    pub marker: u32,
+}
+
+/// Response payload for the debug-only Testing API.
+#[derive(Debug, Clone, PartialEq, Eq, Encode, Decode)]
+pub struct TestingVersionProbeResponse {
+    pub received_version: u8,
+    pub message: String,
+    pub marker: u32,
+}
+
+/// Domain error for the debug-only Testing API.
+#[derive(Debug, Clone, PartialEq, Eq, Encode, Decode)]
+pub enum TestingVersionProbeError {
+    Unknown { reason: String },
+}

rust/crates/truapi/src/versioned/mod.rs rust/crates/truapi/src/versioned.rsrust/crates/truapi/src/versioned/mod.rs renamed to rust/crates/truapi/src/versioned.rs

@@ -44,6 +44,8 @@ pub mod resource_allocation;
 pub mod signing;
 pub mod statement_store;
 pub mod system;
+#[cfg(debug_assertions)]
+pub mod testing;
 pub mod theme;
 
 #[cfg(test)]