feat(channels): multipart fallback for private URLs on sendDocument/Voice/Audio

Federico Liva · Federico Liva · commit 4b5d24594d3c · 2026-04-16T22:22:33.000+02:00
Follow-up to d912f93 (silent-success fix). Even with proper error propagation, agents sending media via `file_url` pointing at an internal container IP still see deliveries fail because Telegram's cloud cannot reach private addresses — the agent just gets a clearer error instead. This commit makes that path actually work without requiring a public tunnel. - New `is_private_url(url)` helper detects loopback, RFC1918 private ranges, link-local (IPv4 + IPv6), and `localhost`. - New `fetch_url_bytes(client, url)` downloads the body + `Content-Type` from inside the container (where the private IP is routable). - New `url_filename(url, fallback)` derives a reasonable filename from the URL's last path segment. - `api_send_document_upload` is now a thin wrapper over a generalised `api_send_media_upload(endpoint, field_name, ..., extra, thread_id)` that supports any Telegram `send{Media}` endpoint. - `api_send_document`, `api_send_voice`, `api_send_audio` each check their URL argument: public URLs continue to pass through to `api_send_media_request` (Telegram's CDN fetches them); private URLs are downloaded locally and re-uploaded via multipart, preserving the caption / title / performer metadata. Result: an agent running inside the container can point `file_url` at its own HTTP server on `127.0.0.1` or a container-internal IP (`172.28.x.x`) and the file reaches the user, no external tunnel required. Scope still excludes: - Loosening the sandbox requirement on the `file_path` branch — that belongs to the manifest / config layer, not the adapter. - Photo / video / animation multipart fallback — trivial follow-up once the pattern is validated on document / voice / audio, which are the paths agents actually hit for voice notes and file delivery.
diff --git a/crates/librefang-channels/src/telegram.rs b/crates/librefang-channels/src/telegram.rs
@@ -53,6 +53,67 @@ fn extract_retry_after(body: &str, default: u64) -> u64 {
 /// Telegram `parse_mode` for HTML formatting.
 const PARSE_MODE_HTML: &str = "HTML";
 
+/// Returns `true` when `url_str` points at a host that Telegram's public
+/// cloud cannot reach — loopback, RFC1918 private ranges, link-local,
+/// `localhost`, or an unparseable URL. Used to short-circuit URL-based
+/// Bot API calls and fall back to multipart upload from inside the
+/// container, where these addresses are actually routable.
+fn is_private_url(url_str: &str) -> bool {
+    let Ok(parsed) = url::Url::parse(url_str) else {
+        return false;
+    };
+    match parsed.host() {
+        Some(url::Host::Domain(d)) => d.eq_ignore_ascii_case("localhost"),
+        Some(url::Host::Ipv4(addr)) => {
+            addr.is_loopback() || addr.is_private() || addr.is_link_local()
+        }
+        Some(url::Host::Ipv6(addr)) => {
+            addr.is_loopback()
+                || (addr.segments()[0] & 0xfe00) == 0xfc00  // fc00::/7 unique-local
+                || (addr.segments()[0] & 0xffc0) == 0xfe80 // fe80::/10 link-local
+        }
+        None => false,
+    }
+}
+
+/// Best-effort filename extracted from the last path segment of `url_str`,
+/// falling back to a generic name if the URL has no usable path.
+fn url_filename(url_str: &str, fallback: &str) -> String {
+    url::Url::parse(url_str)
+        .ok()
+        .and_then(|u| {
+            u.path_segments()
+                .and_then(|segs| segs.last().map(|s| s.to_string()))
+                .filter(|s| !s.is_empty())
+        })
+        .unwrap_or_else(|| fallback.to_string())
+}
+
+/// Fetch bytes from an internal-network URL for re-upload via multipart.
+/// Returns the body plus the `Content-Type` header (falling back to
+/// `application/octet-stream` when the origin doesn't announce one).
+async fn fetch_url_bytes(
+    client: &reqwest::Client,
+    url_str: &str,
+) -> Result<(Vec<u8>, String), Box<dyn std::error::Error + Send + Sync>> {
+    let resp = client.get(url_str).send().await?;
+    if !resp.status().is_success() {
+        return Err(format!(
+            "Failed to fetch {url_str} for multipart fallback: HTTP {}",
+            resp.status()
+        )
+        .into());
+    }
+    let mime = resp
+        .headers()
+        .get(reqwest::header::CONTENT_TYPE)
+        .and_then(|v| v.to_str().ok())
+        .unwrap_or("application/octet-stream")
+        .to_string();
+    let bytes = resp.bytes().await?.to_vec();
+    Ok((bytes, mime))
+}
+
 /// A Telegram bot command definition for the command menu.
 #[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
 pub struct BotCommand {
@@ -477,6 +538,29 @@ impl TelegramAdapter {
         filename: &str,
         thread_id: Option<i64>,
     ) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
+        // Private-network URLs can't be fetched by Telegram's cloud. We
+        // download them from inside the container (where the address is
+        // routable) and re-upload via multipart, so the agent doesn't need
+        // a public tunnel just to deliver a locally-served file.
+        if is_private_url(document_url) {
+            info!(
+                url = document_url,
+                "Private URL detected on sendDocument, falling back to multipart upload"
+            );
+            let (bytes, mime) = fetch_url_bytes(&self.client, document_url).await?;
+            return self
+                .api_send_media_upload(
+                    "sendDocument",
+                    "document",
+                    chat_id,
+                    bytes,
+                    filename,
+                    &mime,
+                    Some(&[("caption", filename.to_string())]),
+                    thread_id,
+                )
+                .await;
+        }
         let body = serde_json::json!({
             "document": document_url,
             "caption": filename,
@@ -497,64 +581,98 @@ impl TelegramAdapter {
         filename: &str,
         mime_type: &str,
         thread_id: Option<i64>,
+    ) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
+        self.api_send_media_upload(
+            "sendDocument",
+            "document",
+            chat_id,
+            data,
+            filename,
+            mime_type,
+            None,
+            thread_id,
+        )
+        .await
+    }
+
+    /// Generic multipart upload for any Telegram `send{Media}` endpoint.
+    ///
+    /// `field_name` is the form field the API expects for the payload
+    /// (`document`, `voice`, `audio`, `photo`, `video`, …). `extra` merges
+    /// optional text fields (captions, title, performer) into the form.
+    /// Retries once on HTTP 429 like the URL path.
+    #[allow(clippy::too_many_arguments)]
+    async fn api_send_media_upload(
+        &self,
+        endpoint: &'static str,
+        field_name: &'static str,
+        chat_id: i64,
+        data: Vec<u8>,
+        filename: &str,
+        mime_type: &str,
+        extra: Option<&[(&str, String)]>,
+        thread_id: Option<i64>,
     ) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
         let url = format!(
-            "{}/bot{}/sendDocument",
+            "{}/bot{}/{endpoint}",
             self.api_base_url,
             self.token.as_str()
         );
 
-        // Convert to ref-counted Bytes so cloning is O(1) (atomic ref-count bump)
-        // instead of O(n) Vec deep-copy. Part::stream() accepts Bytes directly
-        // (Into<Body>), unlike Part::bytes() which requires Into<Cow<'static, [u8]>>.
         let data_bytes = bytes::Bytes::from(data);
 
-        let file_part = reqwest::multipart::Part::stream(data_bytes.clone())
-            .file_name(filename.to_string())
-            .mime_str(mime_type)?;
-
-        let mut form = reqwest::multipart::Form::new()
-            .text("chat_id", chat_id.to_string())
-            .part("document", file_part);
-
-        if let Some(tid) = thread_id {
-            form = form.text("message_thread_id", tid.to_string());
-        }
+        let build_form =
+            || -> Result<reqwest::multipart::Form, Box<dyn std::error::Error + Send + Sync>> {
+                let part = reqwest::multipart::Part::stream(data_bytes.clone())
+                    .file_name(filename.to_string())
+                    .mime_str(mime_type)?;
+                let mut form = reqwest::multipart::Form::new()
+                    .text("chat_id", chat_id.to_string())
+                    .part(field_name, part);
+                if let Some(tid) = thread_id {
+                    form = form.text("message_thread_id", tid.to_string());
+                }
+                if let Some(kv) = extra {
+                    for (k, v) in kv {
+                        form = form.text(k.to_string(), v.clone());
+                    }
+                }
+                Ok(form)
+            };
 
-        let resp = self.client.post(&url).multipart(form).send().await?;
+        let resp = self
+            .client
+            .post(&url)
+            .multipart(build_form()?)
+            .send()
+            .await?;
         if !resp.status().is_success() {
             let status = resp.status();
             let body_text = resp.text().await.unwrap_or_default();
 
             if status.as_u16() == 429 {
                 let retry_after = extract_retry_after(&body_text, RETRY_AFTER_DEFAULT_SECS);
-                warn!("Telegram sendDocument upload rate limited, retrying after {retry_after}s");
+                warn!("Telegram {endpoint} upload rate limited, retrying after {retry_after}s");
                 tokio::time::sleep(Duration::from_secs(retry_after)).await;
 
-                // Rebuild the multipart form — Bytes::clone() is O(1)
-                let file_part = reqwest::multipart::Part::stream(data_bytes.clone())
-                    .file_name(filename.to_string())
-                    .mime_str(mime_type)?;
-                let mut retry_form = reqwest::multipart::Form::new()
-                    .text("chat_id", chat_id.to_string())
-                    .part("document", file_part);
-                if let Some(tid) = thread_id {
-                    retry_form = retry_form.text("message_thread_id", tid.to_string());
-                }
-
-                let resp2 = self.client.post(&url).multipart(retry_form).send().await?;
+                let resp2 = self
+                    .client
+                    .post(&url)
+                    .multipart(build_form()?)
+                    .send()
+                    .await?;
                 if !resp2.status().is_success() {
                     let body_text2 = resp2.text().await.unwrap_or_default();
                     return Err(format!(
-                        "Telegram sendDocument upload failed after retry: {body_text2}"
+                        "Telegram {endpoint} upload failed after retry: {body_text2}"
                     )
                     .into());
                 }
                 return Ok(());
             }
 
             return Err(
-                format!("Telegram sendDocument upload failed ({status}): {body_text}").into(),
+                format!("Telegram {endpoint} upload failed ({status}): {body_text}").into(),
             );
         }
         Ok(())
@@ -568,6 +686,31 @@ impl TelegramAdapter {
         caption: Option<&str>,
         thread_id: Option<i64>,
     ) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
+        if is_private_url(voice_url) {
+            info!(
+                url = voice_url,
+                "Private URL detected on sendVoice, falling back to multipart upload"
+            );
+            let (bytes, mime) = fetch_url_bytes(&self.client, voice_url).await?;
+            let filename = url_filename(voice_url, "voice.ogg");
+            let mut extra: Vec<(&str, String)> = Vec::new();
+            if let Some(cap) = caption {
+                extra.push(("caption", cap.to_string()));
+                extra.push(("parse_mode", PARSE_MODE_HTML.to_string()));
+            }
+            return self
+                .api_send_media_upload(
+                    "sendVoice",
+                    "voice",
+                    chat_id,
+                    bytes,
+                    &filename,
+                    &mime,
+                    Some(&extra),
+                    thread_id,
+                )
+                .await;
+        }
         let mut body = serde_json::json!({ "voice": voice_url });
         if let Some(cap) = caption {
             body["caption"] = serde_json::Value::String(cap.to_string());
@@ -590,6 +733,37 @@ impl TelegramAdapter {
         performer: Option<&str>,
         thread_id: Option<i64>,
     ) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
+        if is_private_url(audio_url) {
+            info!(
+                url = audio_url,
+                "Private URL detected on sendAudio, falling back to multipart upload"
+            );
+            let (bytes, mime) = fetch_url_bytes(&self.client, audio_url).await?;
+            let filename = url_filename(audio_url, "audio.mp3");
+            let mut extra: Vec<(&str, String)> = Vec::new();
+            if let Some(cap) = caption {
+                extra.push(("caption", cap.to_string()));
+                extra.push(("parse_mode", PARSE_MODE_HTML.to_string()));
+            }
+            if let Some(t) = title {
+                extra.push(("title", t.to_string()));
+            }
+            if let Some(p) = performer {
+                extra.push(("performer", p.to_string()));
+            }
+            return self
+                .api_send_media_upload(
+                    "sendAudio",
+                    "audio",
+                    chat_id,
+                    bytes,
+                    &filename,
+                    &mime,
+                    Some(&extra),
+                    thread_id,
+                )
+                .await;
+        }
         let mut body = serde_json::json!({ "audio": audio_url });
         if let Some(cap) = caption {
             body["caption"] = serde_json::Value::String(cap.to_string());
