feat(workspace): add text editing and image previews

2026-10-15 23:10:13 +08:00
parent d380e18db0
commit a8ba3d74dc
19 changed files with 1188 additions and 7 deletions
@@ -79,6 +79,17 @@ GET /api/orphans 返回可回收的完整容器ID数组。DELETE /api/orphans?id
 - POST /api/ws/rename {path,new_path}
 - DELETE /api/ws/delete?path=...
 - POST /api/ws/upload multipart file,path
+- GET /api/ws/image?instance=...&path=...：只读图片预览，沿用工作区认证、实例归属检查和实例读租约；仅支持 GET。
+  - path 与 text 接口一致：保留空白和反斜杠，必须是非空、规范的相对文件路径。Linux openat2 限制在实例 home 内，拒绝符号链接、跨挂载点、多硬链接及特殊文件；不写入文件。
+  - 有界读取最多 16 MiB 的内存快照，读取期间检测到文件变化返回 409，超限返回 413。PNG/JPEG/GIF/WebP 按 magic 识别；SVG 必须有 .svg 扩展名（不区分大小写），完整 XML 的唯一根元素必须是 SVG 命名空间的 svg，拒绝 HTML、XML directives/DOCTYPE 和未知实体，不加载外部实体。其他格式或目录返回 415，缺失/不安全文件返回 404，非法路径返回 400。
+  - 返回原始图片字节及 image MIME；固定 `X-Content-Type-Options: nosniff`、`Content-Security-Policy: sandbox; default-src 'none'; style-src 'unsafe-inline'`、`Content-Disposition: attachment`、`Cache-Control: no-store`。SVG 不做内容改写，依靠图片上下文和 CSP 限制脚本及外部资源；直接导航下载附件。
+- GET /api/ws/text?instance=...&path=... → {content:string,version:string}
+- PUT /api/ws/text?instance=...&path=... JSON {content:string,version:string} → {version:string}
+  - 仅编辑已有普通文件；沿用工作区认证、实例归属和恢复保护。必须提交 GET 返回的不透明 version；缺少 content/version 返回 400，版本不匹配或保存前文件已删除返回 409，不创建新文件。GET 不存在/不安全路径返回 404；非法相对路径返回 400。
+  - 内容最多 1 MiB（UTF-8 字节数，含边界），超限 413；无效 UTF-8、二进制/控制字符返回 415（仅允许 tab、LF、CR 控制字符）。JSON 请求上限为 6 MiB + 4096 字节以容纳转义，超限 413。
+  - Linux openat2 限定访问工作区内路径，拒绝符号链接、跨挂载点和多硬链接文件；不支持 openat2 时安全失败。固定父目录描述符，在同目录写临时文件、保留原文件 mode/UID/GID、同步文件，再原子 rename 替换；不保留扩展属性/ACL。审计仅记录操作和路径，不记录内容。
+  - 用户锁串行化面板保存；锁内读取当前配额和用量，要求现有用量 + 新内容大小不超配额（包括临时文件开销，否则 413）。因此接近配额时即使缩小文件也可能无法保存。外部进程不受该锁和配额检查约束。
+  - rename 前立即重新读取目标并核对最新内容/版本，但检查与 rename 不是文件系统 CAS：外部写入者仍可能在两者之间写入或删除目标，不能保证绝不覆盖外部修改。父目录被外部重命名时操作仍针对固定目录。需严格避免丢失修改时，先停止外部写入；不承诺断电后的目录项持久性。
 - GET /api/ws/download?path=...：普通文件保持原始流与 Range 支持；目录返回 `application/zip` 附件（目录名.zip），空 path 或 `.` 下载整个工作区（workspace.zip）。ZIP 条目相对所选目录，保留空目录，不额外包裹顶层目录，使用 Store 模式（不压缩），不支持 ZIP Range。
  - ZIP 先校验有界文件清单，再逐文件流式输出，不生成临时归档，不持 workspace/global 锁跨网络传输。每次最多 10,000 个文件/目录条目、64 层、10 GiB 文件总大小；进程最多同时 4 个目录下载，超出分别返回 413 / 429；扫描和传输合计限时 2 分钟。
  - 路径必须位于工作区内；下载拒绝任意路径分量的符号链接、跨挂载点、特殊文件和多硬链接普通文件。目录含上述条目或含反斜杠/冒号的不安全 ZIP 文件名时整体拒绝（400），不静默漏文件。依赖 Linux openat2，内核不支持时安全失败。