feat: add stream subcommand for live terminal session broadcasting (#278)

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: ibigbug <543405+ibigbug@users.noreply.github.com>
Co-authored-by: openai-code-agent[bot] <242516109+Codex@users.noreply.github.com>
Co-authored-by: Yuwei Ba <dev@watfaq.com>
Co-authored-by: anthropic-code-agent[bot] <242468646+Claude@users.noreply.github.com>

Author: 4 people

Cargo.lock

@@ -28,7 +28,9 @@ uuid = { version = "1.22.0", features = [
     "macro-diagnostics", # Enable better diagnostics for compile-time UUIDs
 ] }
 
-reqwest = { version = "0.13", features = ["blocking", "multipart"] }
+reqwest = { version = "0.13", features = ["blocking", "multipart", "json"] }
+
+tungstenite = { version = "0.28", features = ["rustls-tls-webpki-roots"] }
 
 rustc_version_runtime = "0.3.0"
 os_info = "3"

Cargo.toml

@@ -1,4 +1,4 @@
-use super::ApiService;
+use super::{ApiService, StreamInfo};
 
 use base64::Engine;
 use base64::prelude::BASE64_STANDARD;
@@ -193,11 +193,73 @@ impl ApiService for Asciinema {
             None
         }
     }
+
+    fn create_stream(&self, cols: u16, rows: u16) -> Option<StreamInfo> {
+        #[derive(Deserialize)]
+        struct CreateStreamResponse {
+            id: String,
+            url: String,
+            ws_producer_url: String,
+        }
+
+        let stream_url = format!("{}/api/streams", &self.config.api_server);
+        let body = serde_json::json!({ "cols": cols, "rows": rows });
+        let res = match self
+            .http_client
+            .post(stream_url)
+            .json(&body)
+            .send()
+        {
+            Ok(r) => r,
+            Err(e) => {
+                println!("Failed to reach stream server: {}", e);
+                return None;
+            }
+        };
+
+        if res.status().is_success() {
+            match res.json::<CreateStreamResponse>() {
+                Ok(resp) => Some(StreamInfo {
+                    id: resp.id,
+                    url: resp.url,
+                    ws_producer_url: resp.ws_producer_url,
+                }),
+                Err(e) => {
+                    println!("Failed to parse stream response: {}", e);
+                    None
+                }
+            }
+        } else {
+            println!("Failed to create stream:");
+            println!("{}", res.text().unwrap_or_default());
+            None
+        }
+    }
+
+    fn get_stream_ws_url(&self, stream_id: &str) -> String {
+        // Derive the producer WebSocket URL from the server base URL and stream ID.
+        // The path follows the asciinema server convention: /ws/S/<stream_id>
+        let base = self
+            .config
+            .api_server
+            .trim_end_matches('/')
+            .replace("https://", "wss://")
+            .replace("http://", "ws://");
+        format!("{}/ws/S/{}", base, stream_id)
+    }
+
+    fn get_auth_header(&self) -> String {
+        let cred = format!("user:{}", self.config.install_id);
+        format!("Basic {}", BASE64_STANDARD.encode(&cred))
+    }
 }
 
 #[cfg(test)]
 mod tests {
+    use base64::prelude::BASE64_STANDARD;
+    use base64::Engine;
     use crate::commands::api::asciinema::Config;
+    use crate::commands::api::ApiService;
 
     use uuid::{Uuid, Version};
 
@@ -207,4 +269,50 @@ mod tests {
         let uuid = Uuid::parse_str(&c.install_id);
         assert_eq!(uuid.unwrap().get_version(), Some(Version::Random)); // uuid4
     }
+
+    #[test]
+    fn test_get_stream_ws_url_https_and_http() {
+        let client = reqwest::blocking::Client::new();
+
+        let asc_https = super::Asciinema {
+            config: Config {
+                install_id: "install".to_string(),
+                api_server: "https://demo.asciinema.org/".to_string(),
+                location: String::new(),
+            },
+            http_client: client.clone(),
+        };
+        assert_eq!(
+            asc_https.get_stream_ws_url("abc123"),
+            "wss://demo.asciinema.org/ws/S/abc123"
+        );
+
+        let asc_http = super::Asciinema {
+            config: Config {
+                install_id: "install".to_string(),
+                api_server: "http://asciinema.test".to_string(),
+                location: String::new(),
+            },
+            http_client: client,
+        };
+        assert_eq!(
+            asc_http.get_stream_ws_url("xyz"),
+            "ws://asciinema.test/ws/S/xyz"
+        );
+    }
+
+    #[test]
+    fn test_get_auth_header_format() {
+        let asc = super::Asciinema {
+            config: Config {
+                install_id: "token-123".to_string(),
+                api_server: "https://example".to_string(),
+                location: String::new(),
+            },
+            http_client: reqwest::blocking::Client::new(),
+        };
+
+        let expected = format!("Basic {}", BASE64_STANDARD.encode("user:token-123"));
+        assert_eq!(asc.get_auth_header(), expected);
+    }
 }

src/commands/api/asciinema.rs

@@ -1,8 +1,21 @@
 mod asciinema;
 
+pub struct StreamInfo {
+    pub id: String,
+    pub url: String,
+    pub ws_producer_url: String,
+}
+
 pub trait ApiService {
     fn auth(&self);
     fn upload(&self, filepath: &str) -> Option<String>;
+    /// Create a new live stream on the server. Returns `StreamInfo` with the public viewer
+    /// URL and the WebSocket producer URL to push events to.
+    fn create_stream(&self, cols: u16, rows: u16) -> Option<StreamInfo>;
+    /// Build the WebSocket producer URL for an *existing* stream identified by `stream_id`.
+    fn get_stream_ws_url(&self, stream_id: &str) -> String;
+    /// Return the `Authorization` header value to authenticate WebSocket connections.
+    fn get_auth_header(&self) -> String;
 }
 
 pub use asciinema::Asciinema;