Skip to content

World's first open-source enterprise world model.

30.5 KB
Raw Blame
//! WebDAV 来源:Nextcloud、ownCloud、坚果云、群晖、Apache mod_dav、
//! rclone serve webdav,以及一切说这套协议的网盘。
//!
//! 按 [0013](../../docs/decisions/0013-a-source-should-hand-over-its-history.md)
//! 的四条判据,它跟对象存储是同一档:有 `getlastmodified`、身份是路径、
//! 企业里确实有一堆文档住在网盘上;而「会不会自我推翻」只能靠两次同步的
//! 差异看出来——WebDAV 的版本控制扩展(RFC 3253)几乎没有服务端实现。
//!
//! **不引 WebDAV 客户端库。** 这套协议要的东西很窄:一个 `PROPFIND` 拿列表、
//! 一个 `GET` 取内容,响应是 XML。`reqwest` 与 `quick-xml` 都已经在树里,
//! 加起来零新增依赖;而现有的 dav 客户端 crate 要么裹着自己的 HTTP 栈,
//! 要么把整套 RFC 4918(锁、属性写、版本)都拖进来,而那些我们一条都不用。

use anyhow::Context as _;
use chrono::{DateTime, Utc};
use quick_xml::events::Event;
use quick_xml::Reader;

/// 一次同步最多摄入多少个文件。理由与对象存储那边相同:网盘也能装下
/// 十万个文件,而摄入不可逆。
const MAX_FILES_PER_SYNC: usize = 2_000;

/// 单个文件的大小上限。
const MAX_FILE_BYTES: u64 = 32 * 1024 * 1024;

/// 目录递归的层数上限。**不是怕深,是怕环**:有些服务端会把符号链接
/// 或共享目录暴露成可以自己指向自己的路径,`Depth: infinity` 在那种目录上
/// 永远回不来。逐层走并且封顶,比信任服务端安全。
const MAX_DEPTH: usize = 8;

/// 一个远端文件。
pub struct RemoteFile {
    /// `webdav://host/path`——`ingest_item` 的 external_key 约定是 URI 形态
    pub external_key: String,
    pub filename: String,
    pub bytes: Vec<u8>,
    pub last_modified: Option<DateTime<Utc>>,
}

/// `PROPFIND` 回来的一条。
#[derive(Debug, PartialEq)]
struct Entry {
    /// XML references are decoded, but URL percent escapes remain intact.
    href: String,
    is_dir: bool,
    len: u64,
    modified: Option<DateTime<Utc>>,
}

/// 解析 `multistatus` 响应。
///
/// **只认本地名,不认前缀。** 服务端可能用 `D:`、`d:`、`ns0:`,也可能干脆
/// 不加前缀——RFC 允许任意前缀绑到 `DAV:` 命名空间上。按 `d:response` 这样
/// 硬匹配的解析器,换一台服务端就一条都读不出来,而症状是「同步成功,
/// 零个文件」。
///
/// **目录判据是 `<collection/>` 存在,不是 href 以 `/` 结尾。** 后者是约定
/// 不是规范,而 rclone 与 Nextcloud 在这一点上就不一致。
fn parse_multistatus(xml: &str) -> anyhow::Result<Vec<Entry>> {
    let mut r = Reader::from_str(xml);

    let mut out = Vec::new();
    let mut cur: Option<Entry> = None;
    let mut field = String::new();
    let mut text = String::new();
    let mut buf = Vec::new();

    loop {
        match r.read_event_into(&mut buf) {
            Ok(Event::Start(e)) => {
                let name = local_name(e.name().into_inner());
                match name.as_str() {
                    "response" => {
                        cur = Some(Entry {
                            href: String::new(),
                            is_dir: false,
                            len: 0,
                            modified: None,
                        });
                    }
                    "collection" => {
                        if let Some(c) = cur.as_mut() {
                            c.is_dir = true;
                        }
                    }
                    other => {
                        field = other.to_string();
                        text.clear();
                    }
                }
            }
            // `<collection/>` 通常是自闭合标签,走 Empty 而不是 Start——
            // 少了这一条,所有目录都会被当成文件去 GET
            Ok(Event::Empty(e)) => {
                if local_name(e.name().into_inner()) == "collection" {
                    if let Some(c) = cur.as_mut() {
                        c.is_dir = true;
                    }
                }
            }
            // XML references and CDATA arrive as separate events. Replacing the
            // field at each Text event truncates an href such as A&amp;B.txt to B.txt.
            Ok(Event::Text(t)) => {
                text.push_str(&t.xml_content(quick_xml::XmlVersion::Implicit1_0));
            }
            Ok(Event::CData(t)) => {
                text.push_str(&t.xml_content(quick_xml::XmlVersion::Implicit1_0));
            }
            Ok(Event::GeneralRef(e))
                if matches!(
                    field.as_str(),
                    "href" | "getcontentlength" | "getlastmodified"
                ) =>
            {
                let reference = format!("&{};", e.into_inner());
                // 认不出的实体只影响它自己那一条:照原样留着。整张 PROPFIND 因为一个
                // `&nbsp;` 就报错的话,一个目录里所有文件都同步不了
                match quick_xml::escape::unescape(&reference) {
                    Ok(v) => text.push_str(&v),
                    Err(_) => text.push_str(&reference),
                }
            }
            Ok(Event::End(e)) => {
                let name = local_name(e.name().into_inner());
                // **空的不回写**:Nextcloud / SabreDAV 一条 response 常带两块 propstat,
                // 200 那块给值、404 那块把没找到的属性再列一遍。成对写法
                // (`<getcontentlength></getcontentlength>`)会开一次 field 再关一次,
                // 照写就把好值盖成空——而 `fetch` 跳过长度为 0 的条目,文件照样掉出同步,
                // 正是这一刀要修的症状换了个门
                if name == field && !text.trim().is_empty() {
                    if let Some(c) = cur.as_mut() {
                        match field.as_str() {
                            "href" => c.href = text.trim().to_string(),
                            "getcontentlength" => c.len = text.trim().parse().unwrap_or(0),
                            "getlastmodified" => {
                                // RFC 1123,`Wed, 02 Sep 2026 15:04:05 GMT`
                                c.modified = DateTime::parse_from_rfc2822(text.trim())
                                    .ok()
                                    .map(|d| d.with_timezone(&Utc));
                            }
                            _ => {}
                        }
                    }
                }
                if name == "response" {
                    if let Some(c) = cur.take() {
                        out.push(c);
                    }
                }
                field.clear();
                text.clear();
            }
            Ok(Event::Eof) => break,
            Err(e) => return Err(anyhow::anyhow!("PROPFIND 响应解析失败: {e}")),
            _ => {}
        }
        buf.clear();
    }
    Ok(out)
}

/// 取标签的本地名,丢掉命名空间前缀并转小写。
///
/// 规范说元素名区分大小写,但实测有服务端写 `getLastModified`。
/// 前缀也自己切:`D:`、`d:`、`ns0:` 都合法,RFC 允许任意前缀绑到 `DAV:`。
fn local_name(raw: &str) -> String {
    raw.rsplit(':').next().unwrap_or(raw).to_ascii_lowercase()
}

/// href 里的百分号转义。
///
/// 自己解而不是引 `percent-encoding`:这里只需要解码,而解码是十来行。
/// 非法序列原样留下,不猜;解码只用于既有文档身份与文件名。
fn percent_decode(s: &str) -> String {
    let b = s.as_bytes();
    let mut out = Vec::with_capacity(b.len());
    let mut i = 0;
    while i < b.len() {
        if b[i] == b'%' && i + 2 < b.len() {
            let hex = std::str::from_utf8(&b[i + 1..i + 3]).ok();
            if let Some(v) = hex.and_then(|h| u8::from_str_radix(h, 16).ok()) {
                out.push(v);
                i += 3;
                continue;
            }
        }
        out.push(b[i]);
        i += 1;
    }
    String::from_utf8_lossy(&out).into_owned()
}

/// 逐层走目录,取回所有文件。
///
/// **不用 `Depth: infinity`。** 规范允许服务端拒绝它(`403 Propfind-Finite-Depth`),
/// 而 Nextcloud 与 Apache mod_dav 默认就是拒绝的;能接受它的服务端在大目录上
/// 又会一次性吐出几十兆 XML。逐层加封顶,两头的问题都没有。
pub async fn fetch(
    http: &reqwest::Client,
    base: &str,
    root: &str,
    auth: Option<(&str, &str)>,
) -> anyhow::Result<(Vec<RemoteFile>, bool)> {
    let host = reqwest::Url::parse(base)
        .ok()
        .and_then(|u| u.host_str().map(str::to_string))
        .unwrap_or_else(|| "webdav".into());
    let base = base.trim_end_matches('/').to_string();

    let mut out = Vec::new();
    let mut truncated = false;
    let root = normalize(root);
    let mut queue = vec![(root.clone(), root, 0usize)];
    let mut unreadable = 0usize;

    while let Some((dir, request_dir, depth)) = queue.pop() {
        if depth > MAX_DEPTH {
            tracing::warn!(%dir, "目录太深,不再往下");
            continue;
        }
        let url = format!("{base}{request_dir}");
        let mut req = http
            .request(reqwest::Method::from_bytes(b"PROPFIND").unwrap(), &url)
            .header("Depth", "1")
            .header("Content-Type", "application/xml");
        if let Some((u, p)) = auth {
            req = req.basic_auth(u, Some(p));
        }
        let resp = req
            .send()
            .await
            .with_context(|| format!("PROPFIND {url}"))?;
        if !resp.status().is_success() {
            anyhow::bail!("PROPFIND {url} 回了 {}", resp.status());
        }
        let xml = resp.text().await.context("读取 PROPFIND 响应")?;

        for e in parse_multistatus(&xml)? {
            // Send the original escaped path: decoding %23/%3F turns filename
            // bytes into URL syntax, and %2523 would fetch a file named with '#'.
            let path = document_path(&e.href, &base);
            let request_path = normalize(&strip_base(&e.href, &base));
            // 服务端会把被查询的目录自己也列进来,跳过它否则会无限打转
            if path == dir || request_path == request_dir {
                continue;
            }
            if e.is_dir {
                queue.push((path, request_path, depth + 1));
                continue;
            }
            if e.len == 0 || e.len > MAX_FILE_BYTES {
                continue;
            }
            if out.len() >= MAX_FILES_PER_SYNC {
                truncated = true;
                break;
            }

            // 一个文件取不回来不该带走整次同步——与对象存储那边同一个判断
            let mut g = http.get(format!("{base}{request_path}"));
            if let Some((u, p)) = auth {
                g = g.basic_auth(u, Some(p));
            }
            let got = async {
                let r = g.send().await?;
                if !r.status().is_success() {
                    anyhow::bail!("{}", r.status());
                }
                Ok::<_, anyhow::Error>(r.bytes().await?)
            }
            .await;
            let bytes = match got {
                Ok(b) => b,
                Err(err) => {
                    unreadable += 1;
                    tracing::warn!(%path, error = %err, "文件取不回来,跳过");
                    continue;
                }
            };

            out.push(RemoteFile {
                external_key: format!("webdav://{host}{path}"),
                filename: path.rsplit('/').next().unwrap_or(&path).to_string(),
                bytes: bytes.to_vec(),
                last_modified: e.modified,
            });
        }
        if truncated {
            break;
        }
    }
    if unreadable > 0 {
        tracing::warn!(unreadable, "有文件没能取回");
    }
    Ok((out, truncated))
}

/// 路径统一成 `/a/b` 的形状:前有斜杠、后无斜杠(根除外)。
fn normalize(p: &str) -> String {
    let t = p.trim();
    let t = t.strip_suffix('/').unwrap_or(t);
    if t.is_empty() {
        "/".into()
    } else if t.starts_with('/') {
        t.into()
    } else {
        format!("/{t}")
    }
}

fn document_path(href: &str, base: &str) -> String {
    let decoded = percent_decode(href);
    if !decoded.starts_with(base) && (href.starts_with("http://") || href.starts_with("https://")) {
        if let Ok(mut url) = reqwest::Url::parse(href) {
            // Proxy-rewritten absolute hrefs historically produce URL-serialized
            // keys. Keep that shape, but decode after parsing and re-encode each
            // segment so '#'/'?' cannot truncate keys and literal '%' stays distinct.
            if let Some(segments) = url
                .path_segments()
                .map(|parts| parts.map(percent_decode).collect::<Vec<_>>())
            {
                if let Ok(mut path) = url.path_segments_mut() {
                    path.clear().extend(segments);
                }
                return normalize(url.path());
            }
        }
    }
    normalize(&strip_base(&decoded, base))
}

/// href 可能是绝对 URL 也可能只是路径——两种都合法,服务端各写各的。
fn strip_base(href: &str, base: &str) -> String {
    if let Some(rest) = href
        .strip_prefix(base)
        .filter(|rest| rest.is_empty() || rest.starts_with('/'))
    {
        return rest.to_string();
    }
    let path = reqwest::Url::parse(href)
        .ok()
        .filter(|url| matches!(url.scheme(), "http" | "https"))
        .map(|url| url.path().to_string())
        .unwrap_or_else(|| href.to_string());
    // Nextcloud returns origin-relative hrefs that already include the base's
    // path. Strip whole path segments before fetch appends the configured base.
    if let Ok(url) = reqwest::Url::parse(base) {
        if let Some(rest) = path
            .strip_prefix(url.path().trim_end_matches('/'))
            .filter(|rest| rest.is_empty() || rest.starts_with('/'))
        {
            return rest.to_string();
        }
    }
    path
}

#[cfg(test)]
mod tests {
    use super::*;

    /// 同一个属性被声明两次:200 那块给值,404 那块把没找到的再列一遍。
    /// 空的那次不许盖掉好值——盖掉之后长度是 0,`fetch` 会把这个文件跳过去
    #[test]
    fn an_empty_redeclaration_does_not_clobber_a_property() {
        let paired = r#"<multistatus xmlns="DAV:"><response>
            <href>/docs/a.txt</href>
            <propstat><prop><getcontentlength>5</getcontentlength>
              <getlastmodified>Wed, 02 Sep 2026 15:04:05 GMT</getlastmodified></prop>
              <status>HTTP/1.1 200 OK</status></propstat>
            <propstat><prop><getcontentlength></getcontentlength>
              <getlastmodified></getlastmodified></prop>
              <status>HTTP/1.1 404 Not Found</status></propstat>
            </response></multistatus>"#;
        for xml in [
            paired.to_string(),
            // 自闭合的那种写法走 Event::Empty,本来就不开 field;两种都要过
            paired
                .replace(
                    "<getcontentlength></getcontentlength>",
                    "<getcontentlength/>",
                )
                .replace("<getlastmodified></getlastmodified>", "<getlastmodified/>"),
        ] {
            let e = parse_multistatus(&xml).unwrap();
            assert_eq!(e.len(), 1);
            assert_eq!(e[0].len, 5, "空的那次把长度盖成了 0:{xml}");
            assert!(e[0].modified.is_some(), "空的那次把时间盖没了");
        }
    }

    /// 认不出的实体只影响它自己那一条,不掀掉整张列表
    #[test]
    fn an_unknown_entity_does_not_abort_the_listing() {
        let xml = r#"<multistatus xmlns="DAV:">
            <response><href>/docs/a&nbsp;b.txt</href><propstat><prop>
              <getcontentlength>5</getcontentlength></prop></propstat></response>
            <response><href>/docs/c.txt</href><propstat><prop>
              <getcontentlength>7</getcontentlength></prop></propstat></response>
            </multistatus>"#;
        let e = parse_multistatus(xml).expect("一个怪实体不该让整张列表失败");
        assert_eq!(e.len(), 2, "另一条也跟着没了");
        assert_eq!(e[1].href, "/docs/c.txt");
    }

    #[test]
    fn xml_text_fragments_keep_the_complete_href_and_properties() {
        for href in [
            "/docs/A&amp;B.txt",
            "/docs/A&#38;B.txt",
            "/docs/A&#x26;B.txt",
            "<![CDATA[/docs/A&B.txt]]>",
            "/docs/A<![CDATA[&]]>B.txt",
        ] {
            let xml = format!(
                r#"<multistatus xmlns="DAV:"><response>
                <href>{href}</href><propstat><prop>
                <getcontentlength>&#53;</getcontentlength>
                <getlastmodified>Wed, 02 Sep 2026 15:04:05 GMT</getlastmodified>
                </prop></propstat></response></multistatus>"#
            );
            let entries = parse_multistatus(&xml).unwrap();
            assert_eq!(entries[0].href, "/docs/A&B.txt", "{href}");
            assert_eq!(entries[0].len, 5);
            assert!(entries[0].modified.is_some());
        }
    }

    #[tokio::test]
    async fn an_xml_escaped_filename_is_fetched_from_its_full_path() {
        use axum::{
            routing::{any, get},
            Router,
        };
        const XML: &str = r#"<multistatus xmlns="DAV:"><response>
            <href>/docs/A&amp;B.txt</href><propstat><prop>
            <getcontentlength>5</getcontentlength>
            </prop></propstat></response></multistatus>"#;
        let app = Router::new()
            .route(
                "/docs",
                any(|| async { (axum::http::StatusCode::MULTI_STATUS, XML) }),
            )
            .route("/docs/A&B.txt", get(|| async { "hello" }));
        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
        let base = format!("http://{}", listener.local_addr().unwrap());
        let server = tokio::spawn(async move { axum::serve(listener, app).await.unwrap() });
        let result = fetch(&reqwest::Client::new(), &base, "/docs", None).await;
        server.abort();
        let (files, truncated) = result.unwrap();
        assert!(!truncated);
        assert_eq!(
            files.len(),
            1,
            "the escaped href must not be silently skipped"
        );
        assert_eq!(files[0].filename, "A&B.txt");
        assert_eq!(files[0].bytes, b"hello");
        assert!(files[0].external_key.ends_with("/docs/A&B.txt"));
    }

    #[tokio::test]
    async fn percent_encoded_filenames_use_the_original_request_path() {
        use axum::{
            http::{Method, StatusCode, Uri},
            Router,
        };

        const FILES: &[(&str, &str, &str)] = &[
            ("/docs/ordinary.txt", "ordinary.txt", "ordinary.txt"),
            ("/docs/%61lpha.txt", "alpha.txt", "alpha.txt"),
            ("/docs/plan%23a.txt", "plan#a.txt", "plan%23a.txt"),
            ("/docs/plan%23b.txt", "plan#b.txt", "plan%23b.txt"),
            ("/docs/what%3Fa.txt", "what?a.txt", "what%3Fa.txt"),
            ("/docs/what%3Fb.txt", "what?b.txt", "what%3Fb.txt"),
            ("/docs/literal%23.txt", "literal#.txt", "literal%23.txt"),
            (
                "/docs/literal%2523.txt",
                "literal%23.txt",
                "literal%2523.txt",
            ),
            (
                "/docs/%E4%B8%AD%E6%96%87%20notes.txt",
                "中文 notes.txt",
                "%E4%B8%AD%E6%96%87%20notes.txt",
            ),
        ];
        for href_kind in ["relative", "absolute", "proxy"] {
            let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
            let base = format!("http://{}", listener.local_addr().unwrap());
            let prefix = match href_kind {
                "absolute" => base.as_str(),
                "proxy" => "https://reverse-proxy.example",
                _ => "",
            };
            let entries = FILES.iter().map(|(path, _, _)| format!(
                "<response><href>{prefix}{path}</href><propstat><prop><getcontentlength>5</getcontentlength></prop></propstat></response>"
            )).collect::<String>();
            let xml = format!("<multistatus xmlns=\"DAV:\">{entries}</multistatus>");
            let app = Router::new().fallback(move |method: Method, uri: Uri| {
                let xml = xml.clone();
                async move {
                    let target = uri.path_and_query().unwrap().as_str();
                    if method.as_str() == "PROPFIND" && target == "/docs" {
                        (StatusCode::MULTI_STATUS, xml)
                    } else if method == Method::GET
                        && FILES.iter().any(|(path, _, _)| *path == target)
                    {
                        (StatusCode::OK, target.to_string())
                    } else {
                        (StatusCode::NOT_FOUND, String::new())
                    }
                }
            });
            let server = tokio::spawn(async move { axum::serve(listener, app).await.unwrap() });
            let result = fetch(&reqwest::Client::new(), &base, "/docs", None).await;
            server.abort();
            let (files, truncated) = result.unwrap();
            assert!(!truncated);
            assert_eq!(files.len(), FILES.len(), "href kind: {href_kind}");
            let keys = files
                .iter()
                .map(|file| file.external_key.as_str())
                .collect::<std::collections::HashSet<_>>();
            assert_eq!(
                keys.len(),
                FILES.len(),
                "distinct files must keep distinct identities: {href_kind}"
            );
            for (file, (request_path, decoded_name, proxy_name)) in files.iter().zip(FILES) {
                let filename = if href_kind == "proxy" {
                    proxy_name
                } else {
                    decoded_name
                };
                assert_eq!(file.bytes, request_path.as_bytes());
                assert_eq!(&file.filename, filename);
                assert_eq!(
                    file.external_key,
                    format!("webdav://127.0.0.1/docs/{filename}")
                );
            }
        }
    }

    #[tokio::test]
    async fn percent_encoded_directories_keep_their_request_path_when_traversed() {
        use axum::{
            http::{Method, StatusCode, Uri},
            Router,
        };
        use std::sync::{Arc, Mutex};

        const PREFIX: &str = "/remote.php/dav/files/alice";
        const DIR: &str = "/docs/folder%23%3F%2520";
        const FILE: &str = "/docs/folder%23%3F%2520/note%23one.txt";
        for (href_kind, prefix) in [
            ("origin-root", ""),
            ("path", PREFIX),
            ("absolute", PREFIX),
            ("proxy", PREFIX),
        ] {
            let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
            let origin = format!("http://{}", listener.local_addr().unwrap());
            let href_origin = match href_kind {
                "absolute" => origin.as_str(),
                "proxy" => "https://cloud.example.com",
                _ => "",
            };
            let collection = |dir: &str| {
                format!(
                "<response><href>{href_origin}{prefix}{dir}/</href><propstat><prop><resourcetype><collection/></resourcetype></prop></propstat></response>"
            )
            };
            let root = format!(
                "<multistatus xmlns=\"DAV:\">{}{}</multistatus>",
                collection("/docs"),
                collection(DIR)
            );
            let nested = format!(
                "<multistatus xmlns=\"DAV:\">{}<response><href>{href_origin}{prefix}{FILE}</href><propstat><prop><getcontentlength>5</getcontentlength></prop></propstat></response></multistatus>", collection(DIR)
            );
            let requests = Arc::new(Mutex::new(Vec::new()));
            let seen = requests.clone();
            let app = Router::new().fallback(move |method: Method, uri: Uri| {
                let (root, nested, seen) = (root.clone(), nested.clone(), seen.clone());
                async move {
                    seen.lock().unwrap().push(format!("{method} {uri}"));
                    let path = uri.path_and_query().unwrap().as_str();
                    match (method.as_str(), path.strip_prefix(prefix).unwrap_or("")) {
                        ("PROPFIND", "/docs") => (StatusCode::MULTI_STATUS, root),
                        ("PROPFIND", DIR) => (StatusCode::MULTI_STATUS, nested),
                        ("GET", FILE) => (StatusCode::OK, "hello".to_string()),
                        _ => (StatusCode::NOT_FOUND, String::new()),
                    }
                }
            });
            let server = tokio::spawn(async move { axum::serve(listener, app).await.unwrap() });
            let base = format!("{origin}{prefix}");
            let result = fetch(&reqwest::Client::new(), &base, "/docs", None).await;
            server.abort();
            let (files, truncated) = result.unwrap_or_else(|err| panic!("{href_kind}: {err:#}"));
            assert!(!truncated);
            assert_eq!(files.len(), 1, "{href_kind}");
            assert_eq!(files[0].bytes, b"hello");
            let (filename, key) = if href_kind == "proxy" {
                (
                    "note%23one.txt",
                    format!("webdav://127.0.0.1{prefix}{FILE}"),
                )
            } else {
                (
                    "note#one.txt",
                    "webdav://127.0.0.1/docs/folder#?%20/note#one.txt".to_string(),
                )
            };
            assert_eq!(files[0].filename, filename);
            assert_eq!(files[0].external_key, key);
            assert_eq!(
                *requests.lock().unwrap(),
                [
                    format!("PROPFIND {prefix}/docs"),
                    format!("PROPFIND {prefix}{DIR}"),
                    format!("GET {prefix}{FILE}")
                ],
                "{href_kind}"
            );
        }
    }

    /// **命名空间前缀是任意的。** 同一份响应换个前缀必须解出同样的东西,
    /// 否则换一台服务端就「同步成功,零个文件」——最难查的那种失败。
    #[test]
    fn any_namespace_prefix_parses_the_same() {
        let with_d = r#"<?xml version="1.0"?>
<D:multistatus xmlns:D="DAV:"><D:response>
  <D:href>/docs/a.txt</D:href>
  <D:propstat><D:prop>
    <D:getcontentlength>5</D:getcontentlength>
    <D:getlastmodified>Wed, 02 Sep 2026 15:04:05 GMT</D:getlastmodified>
    <D:resourcetype/>
  </D:prop></D:propstat>
</D:response></D:multistatus>"#;
        // 前缀换掉,命名空间声明本身不受影响(`xmlns:D="DAV:"` 里没有 `D:` 这个子串)
        let with_ns0 = with_d.replace("D:", "ns0:");
        let a = parse_multistatus(with_d).unwrap();
        let b = parse_multistatus(&with_ns0).unwrap();
        assert_eq!(a, b, "换个前缀就解不出来了");
        assert_eq!(a.len(), 1);
        assert_eq!(a[0].href, "/docs/a.txt");
        assert_eq!(a[0].len, 5);
        assert!(!a[0].is_dir);
        assert!(
            a[0].modified.is_some(),
            "getlastmodified 是 doc_time 的来源"
        );
    }

    /// **目录判据是 `<collection/>`,而它通常是自闭合标签。**
    /// 只处理 `Event::Start` 的解析器会把每个目录都当成文件去 GET。
    #[test]
    fn a_self_closing_collection_is_still_a_directory() {
        let xml = r#"<multistatus xmlns="DAV:"><response>
  <href>/docs/</href>
  <propstat><prop><resourcetype><collection/></resourcetype></prop></propstat>
</response></multistatus>"#;
        let e = parse_multistatus(xml).unwrap();
        assert!(e[0].is_dir, "自闭合的 collection 没被认出来");
    }

    /// href 是百分号转义过的,中文路径直接拼 URL 会 404。
    #[test]
    fn a_percent_encoded_href_is_decoded() {
        assert_eq!(
            percent_decode("/docs/%E4%B8%AD%E6%96%87.txt"),
            "/docs/中文.txt"
        );
        // 非法序列原样留着,不猜
        assert_eq!(percent_decode("/a%ZZb"), "/a%ZZb");
    }

    /// 路径统一:前有斜杠、后无斜杠。两端不一致会让同一个目录被走两遍。
    #[test]
    fn paths_normalise_to_one_shape() {
        for (raw, want) in [
            ("docs", "/docs"),
            ("/docs/", "/docs"),
            ("/", "/"),
            ("", "/"),
        ] {
            assert_eq!(normalize(raw), want, "{raw}");
        }
    }

    #[test]
    fn a_base_path_is_stripped_only_at_a_segment_boundary() {
        let base = "https://cloud.example.com/dav/alice";
        for (href, want) in [
            ("/dav/alice", ""),
            ("/dav/alice/docs/a.txt", "/docs/a.txt"),
            ("/dav/alice2/a.txt", "/dav/alice2/a.txt"),
            (
                "https://cloud.example.com/dav/alice2/a.txt",
                "/dav/alice2/a.txt",
            ),
        ] {
            assert_eq!(strip_base(href, base), want, "{href}");
        }
    }

    /// 真连一个 WebDAV 服务端。没有 `UTOPIA_DAV_TEST_URL` 就跳过。
    ///
    /// 用 rclone 起一个最省事,它和 Nextcloud 在 href 形态上不一样,
    /// 正好能验解析不挑服务端:
    /// ```text
    /// mkdir -p /tmp/dav/docs && echo hello > /tmp/dav/docs/a.txt
    /// rclone serve webdav /tmp/dav --addr 127.0.0.1:18081 --user u --pass p
    /// UTOPIA_DAV_TEST_URL=http://127.0.0.1:18081 UTOPIA_DAV_TEST_USER=u     ///   UTOPIA_DAV_TEST_PASS=p cargo test -p utopia-server webdav
    /// ```
    #[tokio::test]
    async fn it_reads_from_a_real_webdav_server() -> anyhow::Result<()> {
        let Ok(base) = std::env::var("UTOPIA_DAV_TEST_URL") else {
            eprintln!("跳过:未设 UTOPIA_DAV_TEST_URL");
            return Ok(());
        };
        let user = std::env::var("UTOPIA_DAV_TEST_USER").unwrap_or_default();
        let pass = std::env::var("UTOPIA_DAV_TEST_PASS").unwrap_or_default();
        let auth = (!user.is_empty()).then_some((user.as_str(), pass.as_str()));

        let http = reqwest::Client::builder()
            .timeout(std::time::Duration::from_secs(30))
            .build()?;
        let (files, truncated) = fetch(&http, &base, "/docs", auth).await?;
        assert!(!truncated);

        let a = files.iter().find(|f| f.filename == "a.txt").expect("a.txt");
        assert_eq!(a.bytes, b"hello from webdav");
        assert!(
            a.external_key.starts_with("webdav://"),
            "{}",
            a.external_key
        );
        assert!(a.last_modified.is_some());
        // 目录本身不该混进来
        assert!(files.iter().all(|f| !f.filename.is_empty()));
        Ok(())
    }
}