feat: file transfer system (avatar/icon download with cacache) (#40)

* docs(architecture): add file transfer design, research, and implementation plan * feat(cache): add chanora_cache crate with cacache-backed blob cache - New chanora_cache crate: content-addressed blob store wrapping cacache - BlobCache API: async put/get/remove/clear/total_size/evict - Key validation: av_ prefix (32 hex chars), ic_ prefix (decimal digits) - Cacache provides crash safety, SSRI integrity, content dedup - Mtime-based eviction via cacache::list_sync + sort by timestamp - 7 unit tests all passing - Added to workspace members * feat(protocol): add file download support for avatars and icons - Add Request::DownloadFile variant with oneshot reply - Add ProtocolClient::download_avatar(client_uid) and download_icon(icon_id) - Track pending file downloads by FiletransferHandle - Handle StreamItem::FileDownload: read bytes from TCP stream - Handle StreamItem::FiletransferFailed: map to ProtocolError - Add ProtocolError::FileTransfer(String) variant - Add path helper tests for avatar/icon download paths - No tsclientlib types leak across the adapter boundary * feat(core): add blob cache wiring and avatar download orchestration - Add chanora_cache dependency to Cargo.toml - Add blob_cache field to ChanoraSession (Arc<Mutex<Option<BlobCache>>>) - Add init_cache() method: creates BlobCache, runs eviction - Add get_avatar() method: cache-first, download on miss, store in cache - Add clear_cache() and cache_size() methods for cache management - Add CoreError::Cache variant for BlobCacheError conversion - Add avatar_cache integration test * feat(bridge): add init_cache, download_avatar, and cache management functions - Add init_cache(dir) bridge function - Add download_avatar(avatar_hash, client_uid) bridge function - Add clear_file_cache() and file_cache_size() bridge functions - Map CoreError::Cache and ProtocolError::FileTransfer in BridgeError * feat(flutter): add cache initialization wiring and avatar download shims - Add wireCache() to app_bootstrap using getApplicationCacheDirectory() - Call wireCache() after wireStorage() in main bootstrap flow - Add Dart-side initCache and downloadAvatar wrapper shims in api.dart - Update Cargo.lock for new chanora_cache dependency * feat(core): FileTransferService with coalescing, throttling, negative cache - New file_transfer module with FileTransferService struct - Semaphore(2) throttles concurrent downloads - In-flight HashMap coalesces duplicate avatar requests - 5-min negative cache short-circuits ServerRejected misses - ChanoraSession delegates get_avatar through the service - connect/disconnect update shared protocol handle - clear_cache/cache_size delegate to service - 2 new unit tests (cached hit, negative cache) * feat(core,bridge): add get_icon with coalescing and negative cache - FileTransferService::get_icon() mirrors get_avatar pattern - ChanoraSession::get_icon() delegates through FileTransferService - Bridge download_icon() exposed for Flutter - Dart downloadIcon() shim added - Uses PREFIX_ICON (ic_<crc32u>) cache key format - 1 new unit test (cached icon hit) * fix(core,protocol): simplify store_protocol and add download size cap - store_protocol: always write to shared Arc<Mutex<Option<ProtocolClient>>>; the FileTransferService holds the same Arc so it sees updates automatically - read_download_bytes: reject downloads exceeding 10 MB to prevent malicious servers from causing OOM
2026-06-10 11:45:14 +09:00
parent 08d7ace25d
commit aa796d7395
18 changed files with 4376 additions and 58 deletions
@@ -24,6 +24,7 @@ use base64::prelude::*;
 use chanora_resolver::ChanoraResolver;
 use futures::prelude::*;
 use std::collections::HashMap;
+use tokio::io::AsyncReadExt;
 use tokio::sync::{mpsc, oneshot};
 use tracing::{info, warn};

@@ -32,7 +33,8 @@ use tsclientlib::messages::s2c::{InClientDbInfoPart, InMessage};
 use tsclientlib::prelude::*;
 use tsclientlib::{
    ChannelId as TsChannelId, ClientId as TsClientId, Connection, ConnectionStats,
-    DisconnectOptions, Identity, MessageHandle, OutCommandExt, StreamItem, Version,
+    DisconnectOptions, FileDownloadResult, FiletransferHandle, Identity, MessageHandle,
+    OutCommandExt, StreamItem, Version,
 };
 use tsproto_packets::packets::{Direction, Flags, InAudioBuf, OutCommand, OutPacket, PacketType};
 use tsproto_types::ClientType;
@@ -60,6 +62,9 @@ type PendingMoves = HashMap<
    ),
 >;

+type PendingDownloads =
+    HashMap<FiletransferHandle, oneshot::Sender<Result<Vec<u8>, ProtocolError>>>;
+
 struct EventChannels {
    voice_in: mpsc::Sender<InboundVoice>,
    chat: mpsc::Sender<ChatMessage>,
@@ -207,6 +212,10 @@ enum Request {
        client_id: u64,
        reply: oneshot::Sender<Result<ClientProfile, ProtocolError>>,
    },
+    DownloadFile {
+        path: String,
+        reply: oneshot::Sender<Result<Vec<u8>, ProtocolError>>,
+    },
 }

 /// Why a [`ProtocolClient`] task ended. Distinguishes a user-driven
@@ -366,6 +375,26 @@ impl ProtocolClient {
            .map_err(|_| ProtocolError::Lost("client_profile reply dropped".to_string()))?
    }

+    async fn download_file(&self, path: String) -> Result<Vec<u8>, ProtocolError> {
+        let (tx, rx) = oneshot::channel();
+        self.tx
+            .send(Request::DownloadFile { path, reply: tx })
+            .await
+            .map_err(|_| ProtocolError::Lost("connection task is gone".to_string()))?;
+        rx.await
+            .map_err(|_| ProtocolError::Lost("download_file reply dropped".to_string()))?
+    }
+
+    /// Download the current avatar bytes for a TeamSpeak client UID.
+    pub async fn download_avatar(&self, client_uid: &str) -> Result<Vec<u8>, ProtocolError> {
+        self.download_file(avatar_download_path(client_uid)).await
+    }
+
+    /// Download the current channel/server icon bytes for an icon id.
+    pub async fn download_icon(&self, icon_id: u64) -> Result<Vec<u8>, ProtocolError> {
+        self.download_file(icon_download_path(icon_id)).await
+    }
+
    /// Disconnect cleanly. Blocks until the task exits.
    pub async fn disconnect(self) {
        let (tx, rx) = oneshot::channel();
@@ -713,6 +742,7 @@ async fn connection_task(
    // deadline so a server that never replies doesn't leak the
    // reply channel — at most 3 s of pending state per move.
    let mut pending_moves: PendingMoves = HashMap::new();
+    let mut pending_downloads: PendingDownloads = HashMap::new();
    let mut voice_activity: HashMap<u64, Instant> = HashMap::new();
    let mut poke_limiter = PokeLimiter::new();

@@ -737,6 +767,12 @@ async fn connection_task(
                StreamItem::Audio(buf) => {
                    handle_audio_stream_item(&channels.voice_in, &mut voice_activity, buf).await;
                }
+                StreamItem::FileDownload(handle, result) => {
+                    handle_download_stream_item(&mut pending_downloads, handle, result).await;
+                }
+                StreamItem::FiletransferFailed(handle, error) => {
+                    handle_download_failure(&mut pending_downloads, handle, error);
+                }
                other => handle_non_audio_stream_item(
                    &con,
                    other,
@@ -843,12 +879,25 @@ async fn connection_task(
                    client_id,
                    &channels,
                    &mut pending_moves,
+                    &mut pending_downloads,
                    &mut voice_activity,
                    &mut poke_limiter,
                )
                .await;
                let _ = reply.send(r);
            }
+            Ok(Request::DownloadFile { path, reply }) => {
+                match con.download_file(TsChannelId(0), &path, None, None) {
+                    Ok(handle) => {
+                        pending_downloads.insert(handle, reply);
+                    }
+                    Err(e) => {
+                        let _ = reply.send(Err(ProtocolError::FileTransfer(format!(
+                            "start download {path}: {e}"
+                        ))));
+                    }
+                }
+            }
            Ok(Request::Disconnect(reply)) => {
                let _ = con.disconnect(DisconnectOptions::new());
                bounded_drain_stream(con.events(), DISCONNECT_EVENT_DRAIN_TIMEOUT).await;
@@ -1024,6 +1073,47 @@ fn handle_non_audio_stream_item(
    }
 }

+async fn handle_download_stream_item(
+    pending_downloads: &mut PendingDownloads,
+    handle: FiletransferHandle,
+    result: FileDownloadResult,
+) {
+    if let Some(reply) = pending_downloads.remove(&handle) {
+        let _ = reply.send(read_download_bytes(result).await);
+    }
+}
+
+fn handle_download_failure(
+    pending_downloads: &mut PendingDownloads,
+    handle: FiletransferHandle,
+    error: tsclientlib::Error,
+) {
+    if let Some(reply) = pending_downloads.remove(&handle) {
+        let _ = reply.send(Err(ProtocolError::FileTransfer(error.to_string())));
+    }
+}
+
+const MAX_DOWNLOAD_SIZE: u64 = 10 * 1024 * 1024;
+
+async fn read_download_bytes(result: FileDownloadResult) -> Result<Vec<u8>, ProtocolError> {
+    if result.size > MAX_DOWNLOAD_SIZE {
+        return Err(ProtocolError::FileTransfer(format!(
+            "download too large: {} bytes (max {})",
+            result.size, MAX_DOWNLOAD_SIZE
+        )));
+    }
+    let size = usize::try_from(result.size).map_err(|_| {
+        ProtocolError::FileTransfer(format!("download too large to buffer: {} bytes", result.size))
+    })?;
+    let mut stream = result.stream;
+    let mut bytes = vec![0_u8; size];
+    stream
+        .read_exact(&mut bytes)
+        .await
+        .map_err(|e| ProtocolError::FileTransfer(e.to_string()))?;
+    Ok(bytes)
+}
+
 async fn resolve_server_socket(address: &str) -> Result<SocketAddr, ProtocolError> {
    let resolver = ChanoraResolver::new().map_err(|err| ProtocolError::DnsFailed {
        host: address.to_string(),
@@ -1174,6 +1264,7 @@ async fn fetch_client_profile(
    client_id: u64,
    channels: &EventChannels,
    pending_moves: &mut PendingMoves,
+    pending_downloads: &mut PendingDownloads,
    voice_activity: &mut HashMap<u64, Instant>,
    poke_limiter: &mut PokeLimiter,
 ) -> Result<ClientProfile, ProtocolError> {
@@ -1220,6 +1311,7 @@ async fn fetch_client_profile(
            build_command("servergrouplist", &[], &[]),
            channels,
            pending_moves,
+            pending_downloads,
            voice_activity,
            poke_limiter,
        )
@@ -1231,6 +1323,7 @@ async fn fetch_client_profile(
            build_command("channelgrouplist", &[], &[]),
            channels,
            pending_moves,
+            pending_downloads,
            voice_activity,
            poke_limiter,
        )
@@ -1246,6 +1339,7 @@ async fn fetch_client_profile(
            ),
            channels,
            pending_moves,
+            pending_downloads,
            voice_activity,
            poke_limiter,
        )
@@ -1265,6 +1359,7 @@ async fn fetch_client_profile(
            build_command("getconnectioninfo", &[("clid", client_id.to_string())], &[]),
            channels,
            pending_moves,
+            pending_downloads,
            voice_activity,
            poke_limiter,
        )
@@ -1285,6 +1380,7 @@ async fn fetch_client_profile(
            database_id,
            channels,
            pending_moves,
+            pending_downloads,
            voice_activity,
            poke_limiter,
        )
@@ -1448,6 +1544,7 @@ async fn request_messages(
    command: OutCommand,
    channels: &EventChannels,
    pending_moves: &mut PendingMoves,
+    pending_downloads: &mut PendingDownloads,
    voice_activity: &mut HashMap<u64, Instant>,
    poke_limiter: &mut PokeLimiter,
 ) -> Result<Vec<InMessage>, ProtocolError> {
@@ -1485,6 +1582,12 @@ async fn request_messages(
            StreamItem::Audio(buf) => {
                handle_audio_stream_item(&channels.voice_in, voice_activity, buf).await;
            }
+            StreamItem::FileDownload(handle, result) => {
+                handle_download_stream_item(pending_downloads, handle, result).await;
+            }
+            StreamItem::FiletransferFailed(handle, error) => {
+                handle_download_failure(pending_downloads, handle, error);
+            }
            other => handle_non_audio_stream_item(
                con,
                other,
@@ -1503,6 +1606,7 @@ async fn request_client_db_info(
    dbid: tsclientlib::ClientDbId,
    channels: &EventChannels,
    pending_moves: &mut PendingMoves,
+    pending_downloads: &mut PendingDownloads,
    voice_activity: &mut HashMap<u64, Instant>,
    poke_limiter: &mut PokeLimiter,
 ) -> Result<InClientDbInfoPart, ProtocolError> {
@@ -1511,6 +1615,7 @@ async fn request_client_db_info(
        build_command("clientdbinfo", &[("cldbid", dbid.0.to_string())], &[]),
        channels,
        pending_moves,
+        pending_downloads,
        voice_activity,
        poke_limiter,
    )
@@ -1568,6 +1673,14 @@ fn uid_to_avatar_path(uid_b64: &str) -> String {
    rendered
 }

+fn avatar_download_path(client_uid: &str) -> String {
+    format!("/avatar_{}", uid_to_avatar_path(client_uid))
+}
+
+fn icon_download_path(icon_id: u64) -> String {
+    format!("/icon_{icon_id}")
+}
+
 fn find_client_by_id<'a>(
    clients: impl IntoIterator<Item = &'a Client>,
    client_id: u64,
@@ -1951,10 +2064,11 @@ const _: () = {
 #[cfg(test)]
 mod tests {
    use super::{
-        bounded_drain_stream, client_profile_refresh_plan, drain_voice_packets_for_tick,
-        is_server_query_client_type, send_with_timeout, server_socket_from_config,
-        sort_channels_tree_by, std_duration_millis, ConnectConfig, ProtocolClient, Request,
-        SendTimeoutError, DISCONNECT_REPLY_TIMEOUT,
+        avatar_download_path, bounded_drain_stream, client_profile_refresh_plan,
+        drain_voice_packets_for_tick, icon_download_path, is_server_query_client_type,
+        send_with_timeout, server_socket_from_config, sort_channels_tree_by,
+        std_duration_millis, ConnectConfig, ProtocolClient, Request, SendTimeoutError,
+        DISCONNECT_REPLY_TIMEOUT,
    };
    use futures::stream;
    use std::time::Duration;
@@ -2052,6 +2166,16 @@ mod tests {
        assert!(plan.needs_channel_groups);
    }

+    #[test]
+    fn avatar_download_path_uses_uid_hex_encoding() {
+        assert_eq!(avatar_download_path("AQID"), "/avatar_abacad");
+    }
+
+    #[test]
+    fn icon_download_path_uses_unsigned_icon_id() {
+        assert_eq!(icon_download_path(42), "/icon_42");
+    }
+
    #[test]
    fn channel_sort_linked_list_under_one_parent() {
        // Server emits four root-level channels in arbitrary HashMap
@@ -115,4 +115,8 @@ pub enum ProtocolError {
    /// should never see this; if they do, it is a mapping bug here.
    #[error("protocol backend: {0}")]
    Backend(String),
+
+    /// A file transfer failed while downloading protocol-owned assets.
+    #[error("file transfer failed: {0}")]
+    FileTransfer(String),
 }