feat: add height stream example and enhance hypersync-client with streaming capabilities

Cargo.toml

@@ -2,14 +2,15 @@
 resolver = "2"
 
 members = [
-    "hypersync-client",
-    "hypersync-format",
-    "hypersync-net-types",
-    "hypersync-schema",
-    "examples/all_erc20",
-    "examples/wallet",
-    "examples/watch",
-    "examples/reverse_wallet",
-    "examples/call_watch",
-    "examples/call_decode_output",
+  "hypersync-client",
+  "hypersync-format",
+  "hypersync-net-types",
+  "hypersync-schema",
+  "examples/all_erc20",
+  "examples/wallet",
+  "examples/watch",
+  "examples/reverse_wallet",
+  "examples/call_watch",
+  "examples/call_decode_output",
+  "examples/height_stream",
 ]

examples/height_stream/Cargo.toml

@@ -0,0 +1,10 @@
+[package]
+name = "height_stream"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+hypersync-client = { path = "../../hypersync-client" }
+tokio = { version = "1", features = ["full"] }
+env_logger = "0.11"
+anyhow = "1"

examples/height_stream/README.md

@@ -0,0 +1,24 @@
+# Height Stream Example
+
+This example demonstrates using the `stream_height()` API to receive real-time height updates from a HyperSync server.
+
+## Running the Example
+
+```bash
+# With connection events visible (no env_logger needed)
+cargo run -p height_stream
+
+# With debug logs (shows keepalive pings, etc)
+RUST_LOG=debug cargo run -p height_stream
+
+# With trace logs (shows all SSE bytes received)
+RUST_LOG=trace cargo run -p height_stream
+```
+
+## API Design
+
+The stream emits `HeightStreamEvent` enum variants:
+
+- **`Connected`**: Emitted when successfully connected/reconnected to the server
+- **`Height(u64)`**: Emitted for each height update received
+- **`Reconnecting { delay }`**: Emitted when connection is lost, before waiting to reconnect

examples/height_stream/src/main.rs

@@ -0,0 +1,30 @@
+use std::sync::Arc;
+
+use anyhow::Result;
+use hypersync_client::{Client, ClientConfig, HeightStreamEvent};
+
+#[tokio::main]
+async fn main() -> Result<()> {
+    env_logger::init();
+
+    let client = Arc::new(Client::new(ClientConfig {
+        url: Some("https://arbitrum-sepolia.hypersync.xyz".parse().unwrap()),
+        ..Default::default()
+    })?);
+
+    let mut rx = client.clone().stream_height();
+
+    println!("listening for height updates... (Ctrl+C to quit)");
+
+    while let Some(event) = rx.recv().await {
+        match event {
+            HeightStreamEvent::Connected => println!("✓ Connected to stream"),
+            HeightStreamEvent::Height(height) => println!("height: {}", height),
+            HeightStreamEvent::Reconnecting { delay } => {
+                println!("⟳ Reconnecting in {:?}...", delay)
+            }
+        }
+    }
+
+    Ok(())
+}

hypersync-client/Cargo.toml

@@ -30,6 +30,7 @@ tokio = { version = "1", default-features = false, features = [
   "test-util",
   "rt",
   "macros",
+  "sync",
 ] }
 log = "0.4"
 fastrange-rs = "0.1"
@@ -50,11 +51,12 @@ alloy-primitives = "1.1"
 hypersync-net-types = { path = "../hypersync-net-types", version = "0.11.0-rc.3" }
 hypersync-format = { path = "../hypersync-format", version = "0.5.8" }
 hypersync-schema = { path = "../hypersync-schema", version = "0.3" }
+reqwest-eventsource = "0.6"
 
 [dependencies.reqwest]
 version = "0.12"
 default-features = false
-features = ["json", "rustls-tls"]
+features = ["json", "rustls-tls", "stream"]
 
 [dev-dependencies]
 maplit = "1"