cloudreve_api/api/v3/

file.rs

//! File-related API endpoints for Cloudreve API v3

use crate::Error;
use crate::api::v3::ApiV3Client;
use crate::api::v3::models::*;

impl ApiV3Client {
    /// Search for files by keyword, scoped to `path`.
    ///
    /// Pass "/" as `path` to search the entire drive. The response reuses the
    /// directory listing shape, so the matches arrive in `objects`.
    pub async fn search_files(&self, keyword: &str, path: &str) -> Result<DirectoryList, Error> {
        let scope = if path.is_empty() { "/" } else { path };
        let endpoint = format!(
            "/file/search/keywords/{}?path={}",
            urlencoding::encode(keyword),
            urlencoding::encode(scope)
        );
        let response: ApiResponse<DirectoryList> = self.get(&endpoint).await?;
        match response.data {
            Some(list) => Ok(list),
            None => Err(Error::Api {
                code: response.code,
                message: response.msg,
            }),
        }
    }

    pub async fn upload_file(
        &self,
        request: &UploadFileRequest<'_>,
    ) -> Result<UploadSession, Error> {
        let response: ApiResponse<UploadSession> = self.put("/file/upload", request).await?;
        match response.data {
            Some(session) => Ok(session),
            None => Err(Error::Api {
                code: response.code,
                message: response.msg,
            }),
        }
    }

    pub async fn upload_chunk(
        &self,
        session_id: &str,
        chunk_index: u32,
        data: Vec<u8>,
    ) -> Result<(), Error> {
        let url = self.get_url(&format!("/file/upload/{}/{}", session_id, chunk_index));
        let mut request = self.http_client.post(&url).body(data);

        if let Some(cookie) = &self.session_cookie {
            request = request.header("Cookie", format!("cloudreve-session={}", cookie));
        }

        let response = request.send().await?;
        let status = response.status();
        let raw_text = response.text().await.unwrap_or_default();

        if let Ok(api_response) = serde_json::from_str::<ApiResponse<serde_json::Value>>(&raw_text)
        {
            return match api_response.code {
                0 => Ok(()),
                code => Err(Error::Api {
                    code,
                    message: api_response.msg,
                }),
            };
        }

        if status.is_success() {
            Ok(())
        } else {
            Err(Error::Api {
                code: status.as_u16() as i32,
                message: format!("Upload failed with status: {}", status),
            })
        }
    }

    /// 原地覆盖一个已存在文件的内容（`PUT /file/update/{id}`）。
    ///
    /// V3 的上传会话没有 overwrite 语义：同名文件已存在时，建会话会被
    /// GenericAfterUpload 挡回 40004 Object existed。网页端的文本编辑器保存走的
    /// 就是这个接口，服务端以 fsctx.Overwrite 模式写回原文件，id 和路径都不变。
    ///
    /// 服务端从 Content-Length 取长度，所以这里显式带上；响应仍是 HTTP 200 +
    /// body 里的 code。
    pub async fn update_file_content(&self, id: &str, content: Vec<u8>) -> Result<(), Error> {
        let url = self.get_url(&format!("/file/update/{}", urlencoding::encode(id)));
        let mut request = self
            .http_client
            .put(&url)
            .header("Content-Type", "application/octet-stream")
            .header("Content-Length", content.len().to_string())
            .body(content);

        if let Some(cookie) = &self.session_cookie {
            request = request.header("Cookie", format!("cloudreve-session={}", cookie));
        }

        let response = request.send().await?;
        let status = response.status();
        let raw_text = response.text().await.unwrap_or_default();

        if let Ok(api_response) = serde_json::from_str::<ApiResponse<serde_json::Value>>(&raw_text)
        {
            return match api_response.code {
                0 => Ok(()),
                code => Err(Error::Api {
                    code,
                    message: api_response.msg,
                }),
            };
        }

        Err(Error::Api {
            code: status.as_u16() as i32,
            message: raw_text.trim().to_string(),
        })
    }

    /// Delete one upload session by id (`DELETE /file/upload/{sessionId}`).
    ///
    /// Opening a session makes V3 insert a placeholder file row that keeps the
    /// name taken. If the upload never finishes, every later `upload_file` for
    /// the same path fails with 40054 "Upload session existed" until the
    /// server-side GC runs (`upload_session_timeout`, 24h by default). Deleting
    /// the session drops that placeholder and is the only way a client can clear
    /// the conflict itself.
    ///
    /// A session the server no longer knows returns `CodeUploadSessionExpired`;
    /// callers that are only cleaning up can treat that as already done.
    pub async fn delete_upload_session(&self, session_id: &str) -> Result<(), Error> {
        let response: ApiResponse<()> = self
            .delete(&format!("/file/upload/{}", urlencoding::encode(session_id)))
            .await?;
        match response.code {
            0 => Ok(()),
            code => Err(Error::Api {
                code,
                message: response.msg,
            }),
        }
    }

    /// Delete every upload placeholder the current user owns
    /// (`DELETE /file/upload`).
    ///
    /// This is the recovery path for orphan sessions whose ids the client lost
    /// (killed mid-upload, local store wiped, session created but the response
    /// never arrived). It is account-wide, so any upload still in flight loses
    /// its placeholder too — only call it when nothing else is uploading.
    pub async fn delete_all_upload_sessions(&self) -> Result<(), Error> {
        let response: ApiResponse<()> = self.delete("/file/upload").await?;
        match response.code {
            0 => Ok(()),
            code => Err(Error::Api {
                code,
                message: response.msg,
            }),
        }
    }

    pub async fn download_file(&self, id: &str) -> Result<DownloadUrl, Error> {
        // V3 returns ApiResponse with data as string (download URL path)
        let response: ApiResponse<String> = self
            .put(&format!("/file/download/{}", id), &serde_json::json!({}))
            .await?;
        match response.data {
            Some(url_path) => Ok(DownloadUrl { url: url_path }),
            None => Err(Error::Api {
                code: response.code,
                message: response.msg,
            }),
        }
    }

    pub async fn get_file_source(
        &self,
        request: &FileSourceRequest,
    ) -> Result<Vec<FileSource>, Error> {
        let response: ApiResponse<Vec<FileSource>> = self.post("/file/source", request).await?;
        match response.data {
            Some(sources) => Ok(sources),
            None => Err(Error::Api {
                code: response.code,
                message: response.msg,
            }),
        }
    }

    /// 拉取文件预览内容（`GET /file/preview/{id}`）。
    ///
    /// 这个端点要么 302 跳到直链、要么直接把内容写进响应体，**从不返回 JSON**
    /// ——早先这里按 `ApiResponse<DirectoryList>` 解，任何一种成功路径都会解析失败。
    /// reqwest 默认跟随重定向，所以直接拿字节即可；出错时 V3 会回 200 + JSON 错误体，
    /// 由 [`Self::fetch_binary`] 识别。
    pub async fn preview_file(&self, id: &str) -> Result<Vec<u8>, Error> {
        self.fetch_binary(&format!("/file/preview/{}", urlencoding::encode(id)))
            .await
    }

    /// 拉取缩略图（`GET /file/thumb/{id}`）。
    ///
    /// 和 [`Self::preview_file`] 一样：301 跳转或原始图片字节，不是 JSON。
    pub async fn get_thumbnail(&self, id: &str) -> Result<Vec<u8>, Error> {
        self.fetch_binary(&format!("/file/thumb/{}", urlencoding::encode(id)))
            .await
    }

    /// 拉一个"正常情况下返回二进制、出错才返回 JSON"的端点。
    ///
    /// V3 的错误一律是 HTTP 200 + body 里的 code，所以状态码判断不够；这里先按
    /// JSON 试解一次，解出来且 code != 0 才算错误，否则整个 body 就是内容本身。
    async fn fetch_binary(&self, endpoint: &str) -> Result<Vec<u8>, Error> {
        let url = self.get_url(endpoint);
        let mut request = self.http_client.get(&url);
        if let Some(cookie) = &self.session_cookie {
            request = request.header("Cookie", format!("cloudreve-session={}", cookie));
        }

        let response = request.send().await?;
        let status = response.status();
        let bytes = response.bytes().await?.to_vec();

        if let Ok(api_response) = serde_json::from_slice::<ApiResponse<serde_json::Value>>(&bytes)
            && api_response.code != 0
        {
            return Err(Error::Api {
                code: api_response.code,
                message: api_response.msg,
            });
        }

        if !status.is_success() {
            return Err(Error::Api {
                code: status.as_u16() as i32,
                message: String::from_utf8_lossy(&bytes).trim().to_string(),
            });
        }

        Ok(bytes)
    }

    pub async fn create_file(&self, request: &CreateFileRequest<'_>) -> Result<(), Error> {
        let response: ApiResponse<()> = self.post("/file/create", request).await?;
        if response.code == 0 {
            Ok(())
        } else {
            Err(Error::Api {
                code: response.code,
                message: response.msg,
            })
        }
    }
}