#q2316367743/webdav

#安装

moon add q2316367743/webdav

#快速上手

async fn main {
  let client = @webdav.create_webdav_client({
    base_url: "http://127.0.0.1:8080/dav/",
    username: Some("user"),
    password: Some("pass"),
    timeout_ms: None,
  })
  // 递归建目录（mkdir -p 语义：逐级 MKCOL，父级 / 本级已存在都跳过）
  client.mkdir_all(path="/demo/相册/2024")
  // 上传 · 全量字节（进度按 64 KiB 分块节奏回调；返回值带 ETag 等元数据）
  let put = client.put_file(
    path="/demo/hello.txt",
    data=@utf8.encode("你好，WebDAV！"),
    content_type="text/plain; charset=utf-8",
    conditions=@webdav.Conditions::new(if_none_match="*"), // 仅当不存在时创建
    on_progress=fn(p) { println("上传 (\{p.loaded}/\{p.total})") },
  )
  println("已创建：\{put.created}，ETag：\{put.etag}")
  // 上传 · 本地文件（内部边读边发，内容不整份读进内存）
  ignore(
    client.put_file_from_path(
      path="/demo/big.bin",
      local_path="/Users/me/big.bin",
      content_type="application/octet-stream",
      on_progress=fn(p) { println("上传 big.bin \{p.loaded}/\{p.total}") },
    ),
  )
  // 上传 · 任意读取流（@fs.File / @io.pipe() 读端 / MemoryReader 都能接；
  // 传 content_length 走定长，不传走 chunked）
  // client.put_file_stream(path="/demo/stream.bin", reader=some_reader)
  // 列目录
  let items = client.list(path="/demo")
  for item in items {
    println("\{if item.is_dir { "[目录]" } else { "[文件]" }} \{item.name}")
  }
  // 流式下载 · 分块回调（内存消费）
  client.download_file(
    path="/demo/hello.txt",
    on_chunk=fn(chunk) { /* 逐块处理，如拼 Buffer / 算哈希 */ },
    on_progress=fn(p) { println("下载 \{p.loaded} 字节") },
  )
  // 流式下载 · 直接写本地文件（写盘是 async，客户端内部完成）
  client.download_to_path(path="/demo/big.bin", local_path="/Users/me/big.copy")
  // 断点续传：中断残留的本地文件从断点继续（只拉剩余部分）；
  // 带 ETag 发 If-Range，服务端文件已变时自动回退全文重写
  client.download_to_path_resume(
    path="/demo/big.bin",
    local_path="/Users/me/big.copy",
    etag=put.etag.unwrap_or(""),
  )
  // 区间下载：只取前 8 字节（服务端支持时回 206）
  let head = client.get_file(path="/demo/hello.txt",
    range=@webdav.ByteRange::from(end=7))
}

#功能一览

#已知限制

• mkdir 单级创建（父目录不存在得 409）；递归用 mkdir_all：逐级 MKCOL， 405（已存在）跳过，409 先 PROPFIND Depth:0 复核再决定跳过或抛出， 中途失败不回滚已建层级。
• 锁做独占与共享写锁、完整 If（多令牌 / Not / [etag] / 带标签列表）、 lock-null 清理与可选的 423 自动补令牌重试；Depth: 1 的 LOCK 按 RFC 4918 §9.10.3 本地拦 400，不做 5xx / 断线退避重试，锁注册表只是进程内缓存（不跨进程）； 锁发现依赖服务端实现 lockdiscovery（hacdias/webdav 只回空元素）。
• 路径形态的传输只覆盖单文件；目录镜像 / 同步、push 型（Writer）上传仍是路线图。
• Range / 断点续传只做单区间（无多区间 / multipart），区间端点与进度受 Int32 上限约束（>2GB 资源不支持）；If-Range 仅支持 ETag；不带 etag 的裸续传在 服务端文件被整体替换时可能拼出损坏内容。详见 docs/06-range-resume.md 的已知限制。
• 更多缺口与 P1 / P2 路线图见 docs/03-gap-analysis.md。

#文档

• docs/01-architecture.md —— 架构与协议映射
• docs/02-api.md —— API 参考
• docs/03-gap-analysis.md —— 缺口分析与路线图
• docs/04-ci-cd.md —— CI / CD：测试与发布工作流
• docs/05-lock-extensions.md —— 锁能力扩展：共享锁、If 头、lock-null 清理与 423 重试
• docs/06-range-resume.md —— Range 区间下载与断点续传

#开发

bash src/main/run_tests.sh  # 一键测试：起 WebDAV 服务端 → moon test → 真实全流程 → 关闭并汇总
moon test                   # 仅单元 / 黑盒测试（Mock 传输层，不触网）
moon run src/main           # 单独跑真实全流程演示（环境变量见 src/main/moon.pkg 头注释）
moon info && moon fmt