feat: add WebSocket transport support

.github/workflows/ci.yml

@@ -52,10 +52,10 @@ jobs:
       - run: cargo update -p native-tls
       - uses: taiki-e/install-action@cargo-hack
       - name: Tests
-        run: cargo test --features tempo,stripe,server,client,axum,middleware,tower,utils,integration-stripe
+        run: cargo test --features tempo,stripe,ws,server,client,axum,middleware,tower,utils,integration-stripe,integration-ws
         env:
           STRIPE_SECRET_KEY: ${{ secrets.STRIPE_SECRET_KEY }}
-      - run: cargo hack check --each-feature --no-dev-deps --skip integration
+      - run: cargo hack check --each-feature --no-dev-deps --skip integration,integration-stripe,integration-ws
       - name: Check examples
         run: find examples -name Cargo.toml -exec cargo check --manifest-path {} \;
 

Cargo.toml

@@ -16,7 +16,7 @@ default = ["reqwest-default-tls"]
 
 # Side selection
 client = ["dep:reqwest"]
-server = ["tokio", "futures-core", "async-stream"]
+server = ["tokio", "futures-core", "async-stream", "http-types"]
 
 # Method implementations
 evm = ["alloy", "hex", "rand"]
@@ -35,12 +35,16 @@ tower = ["dep:tower-layer", "dep:tower-service", "http-types", "dep:http-body",
 # Axum middleware support (server-side convenience)
 axum = ["dep:axum-core", "server", "http-types"]
 
+# WebSocket support
+ws = ["server", "client", "dep:tokio-tungstenite", "dep:futures-util"]
+
 reqwest-default-tls = ["reqwest?/default-tls"]
 reqwest-native-tls = ["reqwest?/native-tls"]
 reqwest-rustls-tls = ["reqwest?/rustls-tls"]
 
 # Integration tests (requires a running Tempo localnet)
 integration = ["tempo", "server", "client", "axum"]
+integration-ws = ["ws", "tempo", "server", "client", "axum"]
 integration-stripe = ["stripe", "server", "client", "axum"]
 
 [dependencies]
@@ -82,9 +86,15 @@ http-body = { version = "1", optional = true }
 # Axum dependencies (optional)
 axum-core = { version = "0.5", optional = true }
 
+# WebSocket dependencies (optional)
+tokio-tungstenite = { version = "0.26", optional = true }
+futures-util = { version = "0.3", optional = true }
+
 [dev-dependencies]
 tokio = { version = "1", features = ["rt-multi-thread", "macros", "net"] }
-axum = { version = "0.8" }
+axum = { version = "0.8", features = ["ws"] }
 reqwest = { version = "0.12", default-features = false, features = ["json", "rustls-tls"] }
 hex = "0.4"
+tokio-tungstenite = "0.26"
+futures-util = "0.3"
 

README.md

@@ -102,6 +102,39 @@ let resp = reqwest::Client::new()
     .await?;
 ```
 
+### WebSocket
+
+```rust
+use mpp::server::ws::{WsMessage, WsResponse};
+
+// Server: parse incoming WS message, send challenge/receipt
+let msg: WsMessage = serde_json::from_str(&text)?;
+if let WsMessage::Credential { credential } = msg {
+    let parsed = mpp::parse_authorization(&credential)?;
+    let receipt = mpp.verify_credential(&parsed).await?;
+    let resp = WsResponse::Receipt {
+        receipt: serde_json::to_value(&receipt)?,
+    };
+    socket.send(resp.to_text()).await;
+}
+
+// Client: detect challenge, send credential
+let msg: mpp::client::ws::WsServerMessage = serde_json::from_str(&text)?;
+if let WsServerMessage::Challenge { challenge, .. } = msg {
+    let cred_msg = serde_json::json!({
+        "type": "credential",
+        "credential": auth_string,
+    });
+    ws.send(cred_msg.to_string()).await;
+}
+```
+
+WSS (WebSocket Secure) is handled at the connection layer — the transport itself is protocol-agnostic. On the server, terminate TLS via a reverse proxy (nginx, Cloudflare) or use `axum-server` with rustls. On the client, `tokio-tungstenite` supports `wss://` URLs via its `native-tls` or `rustls` features:
+
+```toml
+tokio-tungstenite = { version = "0.26", features = ["rustls-tls-webpki-roots"] }
+```
+
 ## Feature Flags
 
 | Feature | Description |
@@ -114,6 +147,7 @@ let resp = reqwest::Client::new()
 | `middleware` | reqwest-middleware support with `PaymentMiddleware` (implies `client`) |
 | `tower` | Tower middleware for server-side integration |
 | `axum` | Axum extractor support for server-side convenience |
+| `ws` | WebSocket transport for bidirectional session payments |
 | `utils` | Hex/random utilities for development and testing |
 
 ## Payment Methods

examples/ws/Cargo.toml

@@ -0,0 +1,21 @@
+[package]
+name = "ws-example"
+version = "0.1.0"
+edition = "2021"
+publish = false
+
+[[bin]]
+name = "ws-server"
+path = "src/server.rs"
+
+[[bin]]
+name = "ws-client"
+path = "src/client.rs"
+
+[dependencies]
+mpp = { path = "../..", features = ["server", "client", "ws", "tempo"] }
+axum = { version = "0.8", features = ["ws"] }
+tokio = { version = "1", features = ["full"] }
+tokio-tungstenite = "0.26"
+futures-util = "0.3"
+serde_json = "1"

examples/ws/README.md

@@ -0,0 +1,25 @@
+# WebSocket Payment Example
+
+Demonstrates the MPP WebSocket payment flow with a server that streams
+fortunes after payment verification.
+
+## Running
+
+```bash
+# Start the server
+cargo run --bin ws-server
+
+# In another terminal, start the client
+cargo run --bin ws-client
+```
+
+## Protocol
+
+1. Client connects via WebSocket
+2. Server sends `{ "type": "challenge", ... }`
+3. Client responds with `{ "type": "credential", "credential": "Payment ..." }`
+4. Server verifies payment and streams data as `{ "type": "message", "data": "..." }`
+5. Server sends final `{ "type": "receipt", ... }` and closes
+
+**Note:** This example uses a mock credential. In production, use
+`TempoProvider` to sign real transactions.

examples/ws/src/client.rs

@@ -0,0 +1,111 @@
+//! # WebSocket Payment Client
+//!
+//! Connects to the WS payment server, handles the challenge/credential
+//! flow, and prints received fortunes.
+//!
+//! ## Running
+//!
+//! ```bash
+//! # First start the server:
+//! cargo run --bin ws-server
+//!
+//! # Then in another terminal:
+//! cargo run --bin ws-client
+//! ```
+
+use futures_util::{SinkExt, StreamExt};
+use mpp::client::ws::WsServerMessage;
+use mpp::protocol::core::{format_authorization, PaymentPayload};
+use tokio_tungstenite::tungstenite;
+
+#[tokio::main]
+async fn main() {
+    let url = std::env::args()
+        .nth(1)
+        .unwrap_or_else(|| "ws://127.0.0.1:3000/ws".to_string());
+
+    println!("Connecting to {url} ...");
+
+    let (mut ws, _) = tokio_tungstenite::connect_async(&url)
+        .await
+        .expect("failed to connect");
+
+    println!("Connected!");
+
+    while let Some(msg) = ws.next().await {
+        let msg = match msg {
+            Ok(tungstenite::Message::Text(text)) => text,
+            Ok(tungstenite::Message::Close(_)) => {
+                println!("Server closed connection");
+                break;
+            }
+            Err(e) => {
+                eprintln!("WS error: {e}");
+                break;
+            }
+            _ => continue,
+        };
+
+        let server_msg: WsServerMessage = match serde_json::from_str(&msg) {
+            Ok(m) => m,
+            Err(e) => {
+                eprintln!("Failed to parse server message: {e}");
+                continue;
+            }
+        };
+
+        match server_msg {
+            WsServerMessage::Challenge { challenge, .. } => {
+                println!("Received payment challenge");
+
+                // Parse the challenge
+                let parsed: mpp::PaymentChallenge =
+                    serde_json::from_value(challenge).expect("parse challenge");
+
+                // Create a mock credential (in real use, sign a transaction)
+                let credential = mpp::PaymentCredential::new(
+                    parsed.to_echo(),
+                    PaymentPayload::hash(
+                        "0xdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef",
+                    ),
+                );
+                let auth_str = format_authorization(&credential).unwrap();
+
+                // Send credential
+                let cred_msg = serde_json::json!({
+                    "type": "credential",
+                    "credential": auth_str,
+                });
+                ws.send(tungstenite::Message::Text(cred_msg.to_string().into()))
+                    .await
+                    .unwrap();
+                println!("Sent credential");
+            }
+            WsServerMessage::Data { data } => {
+                println!("  {data}");
+            }
+            WsServerMessage::NeedVoucher {
+                channel_id,
+                required_cumulative,
+                ..
+            } => {
+                println!(
+                    "Server needs voucher for channel {channel_id} (required: {required_cumulative})"
+                );
+                // In real use: sign and send a new voucher
+            }
+            WsServerMessage::Receipt { receipt } => {
+                println!("\nPayment receipt:");
+                println!("  Status: {}", receipt["status"]);
+                println!("  Reference: {}", receipt["reference"]);
+                break;
+            }
+            WsServerMessage::Error { error } => {
+                eprintln!("Server error: {error}");
+                // In this demo, the mock credential will fail verification.
+                // A real client would use TempoProvider to sign a transaction.
+                break;
+            }
+        }
+    }
+}