hyprstream_rpc/transport/traits.rs
1//! Transport and Signer traits for unified RPC communication.
2//!
3//! These traits abstract over the wire transport (ZMQ vs WebTransport) and
4//! signing mechanism (local key vs external callback), enabling a single
5//! `RpcClient<S, T>` implementation that compiles to both native and wasm32.
6
7use anyhow::Result;
8use async_trait::async_trait;
9use futures::Stream;
10
11/// Signing abstraction for Ed25519 envelope signatures.
12///
13/// Native: `LocalSigner` owns the `SigningKey` and signs synchronously.
14/// WASM: `JsSigner` delegates to a JS callback (aegis-vault) and awaits the result.
15///
16/// # Safety (wasm32)
17///
18/// `JsSigner` holds `js_sys::Function` which is `!Send`. We use
19/// `unsafe impl Send + Sync` on it because wasm32 is single-threaded.
20/// The `Send + Sync` bounds on this trait are required so that `RpcClient<S, T>`
21/// can be used with `Arc` and `tokio::spawn` on native.
22#[allow(dead_code)]
23#[async_trait]
24pub trait Signer: Send + Sync {
25 /// Ed25519 public key (32 bytes).
26 fn pubkey(&self) -> [u8; 32];
27
28 /// Sign canonical envelope bytes. Returns 64-byte Ed25519 signature.
29 async fn sign(&self, canonical_bytes: &[u8]) -> Result<[u8; 64]>;
30
31 /// ML-DSA-65 verifying key bytes (1952 bytes) when PQ hybrid is available.
32 fn pq_pubkey(&self) -> Option<Vec<u8>> {
33 None
34 }
35
36 /// ML-DSA-65 signature over canonical envelope bytes.
37 async fn pq_sign(&self, _canonical_bytes: &[u8]) -> Result<Option<Vec<u8>>> {
38 Ok(None)
39 }
40}
41
42/// Wire transport abstraction.
43///
44/// Native: `ZmqConnection` wraps ZMQ REQ sockets with auto-reconnect.
45/// WASM: `WtConnection` wraps WebTransport bidi streams with ZMTP framing.
46///
47/// Both transports carry ZMTP-framed messages. The `Sub` and `Pub` associated
48/// types provide streaming (server→client) and control (client→server) channels.
49///
50/// `Sub` must implement `futures::Stream` yielding frames as `Vec<Vec<u8>>`,
51/// matching the ZMTP multipart format `[topic, capnp_data, mac]`.
52#[allow(dead_code)]
53#[async_trait]
54pub trait Transport: Send + Sync {
55 /// Subscriber type for data streams (server→client).
56 /// Must yield ZMTP multipart frames as `Vec<Vec<u8>>`.
57 type Sub: Stream<Item = Result<Vec<Vec<u8>>>> + Unpin + Send;
58
59 /// Publisher type for control channel (client→server).
60 type Pub: Send;
61
62 /// Send a request and receive a response (REQ/REP pattern).
63 ///
64 /// `timeout_ms`: Optional timeout in milliseconds. Implementations should
65 /// use a default (e.g., 30s) when `None`. On native, this caps the ZMQ
66 /// recv timeout. On WASM, WebTransport stream lifetime handles this.
67 async fn send(&self, payload: Vec<u8>, timeout_ms: Option<i32>) -> Result<Vec<u8>>;
68
69 /// Subscribe to a topic (SUB pattern). Returns a stream of multipart frames.
70 async fn subscribe(&self, topic: &[u8]) -> Result<Self::Sub>;
71
72 /// Open a publish channel to a topic (PUB/PUSH pattern for ctrl messages).
73 async fn publish(&self, topic: &[u8]) -> Result<Self::Pub>;
74}
75
76/// Trait for sending frames on a publish/control channel.
77///
78/// Abstracted because native and WASM use different async send primitives.
79#[allow(dead_code)]
80#[async_trait]
81pub trait PublishSink: Send {
82 /// Send ZMTP multipart frames (e.g., `[ctrl_topic, capnp, mac]`).
83 async fn send_frames(&self, frames: &[&[u8]]) -> Result<()>;
84}