fix(sync): 修复云同步冲突安全性并接入 provider 条件写入

Author: cyfung1031

packages/filesystem/baidu/baidu.test.ts

@@ -32,4 +32,23 @@ describe("BaiduFileSystem", () => {
     );
     expect(updateDynamicRulesMock).not.toHaveBeenCalled();
   });
+
+  it("create should reject conditional write options as unsupported", async () => {
+    const fs = new BaiduFileSystem("/apps", "token");
+
+    await expect(fs.create("test.txt", { expectedDigest: "md5" })).rejects.toMatchObject({
+      provider: "baidu",
+      unsupported: true,
+    });
+  });
+
+  it("delete should be idempotent when Baidu reports file missing", async () => {
+    const fetchMock = vi.fn().mockResolvedValue({
+      json: async () => ({ errno: -9 }),
+    });
+    vi.stubGlobal("fetch", fetchMock);
+    const fs = new BaiduFileSystem("/apps", "token");
+
+    await expect(fs.delete("missing.txt")).resolves.toMatchObject({ errno: -9 });
+  });
 });

packages/filesystem/baidu/baidu.ts

@@ -1,4 +1,5 @@
 import { AuthVerify } from "../auth";
+import { FileSystemError } from "../error";
 import type FileSystem from "../filesystem";
 import type { FileInfo, FileCreateOptions, FileReader, FileWriter } from "../filesystem";
 import { joinPath } from "../utils";
@@ -29,7 +30,15 @@ export default class BaiduFileSystem implements FileSystem {
     return new BaiduFileSystem(joinPath(this.path, path), this.accessToken);
   }
 
-  async create(path: string, _opts?: FileCreateOptions): Promise<FileWriter> {
+  async create(path: string, opts?: FileCreateOptions): Promise<FileWriter> {
+    if (opts?.expectedDigest || opts?.expectedVersion || opts?.createOnly || opts?.overwrite === false) {
+      throw new FileSystemError({
+        provider: "baidu",
+        message: "Baidu filesystem does not support conditional writes",
+        code: "unsupported_conditional_write",
+        unsupported: true,
+      });
+    }
     return new BaiduFileWriter(this, joinPath(this.path, path));
   }
 
@@ -95,6 +104,9 @@ export default class BaiduFileSystem implements FileSystem {
       }
     ).then((data) => {
       if (data.errno) {
+        if (data.errno === -9 || data.errno === 12) {
+          return data;
+        }
         throw new Error(JSON.stringify(data));
       }
       return data;

packages/filesystem/dropbox/dropbox.test.ts

@@ -30,4 +30,71 @@ describe("DropboxFileSystem", () => {
 
     await expect(fs.exists("/test.txt")).rejects.toThrow("invalid_access_token");
   });
+
+  it("list should expose Dropbox rev as version", async () => {
+    const fs = new DropboxFileSystem("/", "token");
+    vi.spyOn(fs, "request").mockResolvedValue({
+      entries: [
+        {
+          ".tag": "file",
+          name: "test.user.js",
+          size: 1,
+          content_hash: "hash-1",
+          rev: "rev-1",
+          client_modified: "2024-01-01T00:00:00.000Z",
+          server_modified: "2024-01-02T00:00:00.000Z",
+        },
+      ],
+      has_more: false,
+    });
+
+    await expect(fs.list()).resolves.toMatchObject([
+      {
+        name: "test.user.js",
+        digest: "hash-1",
+        version: "rev-1",
+      },
+    ]);
+  });
+
+  it("writer should use Dropbox update mode when expectedVersion is provided", async () => {
+    const fs = new DropboxFileSystem("/", "token");
+    const requestSpy = vi.spyOn(fs, "request").mockResolvedValue({});
+
+    const writer = await fs.create("test.txt", { expectedVersion: "rev-1" });
+    await writer.write("content");
+
+    const headers = (requestSpy.mock.calls[0][1] as RequestInit).headers as Headers;
+    expect(JSON.parse(headers.get("Dropbox-API-Arg")!)).toEqual({
+      path: "/test.txt",
+      mode: { ".tag": "update", update: "rev-1" },
+      autorename: false,
+    });
+  });
+
+  it("writer should use add mode for createOnly without metadata preflight", async () => {
+    const fs = new DropboxFileSystem("/", "token");
+    const existsSpy = vi.spyOn(fs, "exists");
+    const requestSpy = vi.spyOn(fs, "request").mockResolvedValue({});
+
+    const writer = await fs.create("test.txt", { createOnly: true });
+    await writer.write("content");
+
+    expect(existsSpy).not.toHaveBeenCalled();
+    const headers = (requestSpy.mock.calls[0][1] as RequestInit).headers as Headers;
+    expect(JSON.parse(headers.get("Dropbox-API-Arg")!)).toMatchObject({
+      path: "/test.txt",
+      mode: "add",
+    });
+  });
+
+  it("writer should reject expectedDigest without Dropbox rev", async () => {
+    const fs = new DropboxFileSystem("/", "token");
+    const writer = await fs.create("test.txt", { expectedDigest: "content-hash" });
+
+    await expect(writer.write("content")).rejects.toMatchObject({
+      provider: "dropbox",
+      unsupported: true,
+    });
+  });
 });

packages/filesystem/dropbox/dropbox.ts

@@ -37,8 +37,8 @@ export default class DropboxFileSystem implements FileSystem {
     return Promise.resolve(new DropboxFileSystem(joinPath(this.path, path), this.accessToken));
   }
 
-  create(path: string, _opts?: FileCreateOptions): Promise<FileWriter> {
-    return Promise.resolve(new DropboxFileWriter(this, joinPath(this.path, path)));
+  create(path: string, opts?: FileCreateOptions): Promise<FileWriter> {
+    return Promise.resolve(new DropboxFileWriter(this, joinPath(this.path, path), opts));
   }
 
   async createDir(dir: string, _opts?: FileCreateOptions): Promise<void> {
@@ -207,6 +207,7 @@ export default class DropboxFileSystem implements FileSystem {
               path: this.path,
               size: item.size || 0,
               digest: item.content_hash || "",
+              version: item.rev || "",
               createtime: new Date(item.client_modified).getTime(),
               updatetime: new Date(item.server_modified).getTime(),
             });

packages/filesystem/dropbox/rw.ts

@@ -1,4 +1,6 @@
+import { FileSystemError } from "../error";
 import type { FileInfo, FileReader, FileWriter } from "../filesystem";
+import type { FileCreateOptions } from "../filesystem";
 import { joinPath } from "../utils";
 import type DropboxFileSystem from "./dropbox";
 
@@ -53,12 +55,30 @@ export class DropboxFileWriter implements FileWriter {
 
   fs: DropboxFileSystem;
 
-  constructor(fs: DropboxFileSystem, path: string) {
+  opts?: FileCreateOptions;
+
+  constructor(fs: DropboxFileSystem, path: string, opts?: FileCreateOptions) {
     this.fs = fs;
     this.path = path;
+    this.opts = opts;
   }
 
   async write(content: string | Blob): Promise<void> {
+    if (this.opts?.expectedDigest && !this.opts.expectedVersion) {
+      throw new FileSystemError({
+        provider: "dropbox",
+        message: "Dropbox conditional writes require expectedVersion (rev), not expectedDigest",
+        code: "unsupported_conditional_write",
+        unsupported: true,
+      });
+    }
+    if (this.opts?.createOnly || this.opts?.overwrite === false) {
+      return this.createNewFile(content);
+    }
+    if (this.opts?.expectedVersion) {
+      return this.updateFile(content, this.opts.expectedVersion);
+    }
+
     // 检查文件是否存在
     const exists = await this.fs.exists(this.path);
 
@@ -71,23 +91,19 @@ export class DropboxFileWriter implements FileWriter {
     }
   }
 
-  private async updateFile(content: string | Blob): Promise<void> {
+  private async updateFile(content: string | Blob, rev?: string): Promise<void> {
     const myHeaders = new Headers();
     myHeaders.append("Content-Type", "application/octet-stream");
     myHeaders.append(
       "Dropbox-API-Arg",
       JSON.stringify({
         path: this.path,
-        mode: "overwrite",
+        mode: rev ? { ".tag": "update", update: rev } : "overwrite",
         autorename: false,
       })
     );
 
-    await this.fs.request("https://content.dropboxapi.com/2/files/upload", {
-      method: "POST",
-      headers: myHeaders,
-      body: content instanceof Blob ? content : new Blob([content]),
-    });
+    await this.upload(myHeaders, content);
 
     return Promise.resolve();
   }
@@ -104,12 +120,30 @@ export class DropboxFileWriter implements FileWriter {
       })
     );
 
-    await this.fs.request("https://content.dropboxapi.com/2/files/upload", {
-      method: "POST",
-      headers: myHeaders,
-      body: content instanceof Blob ? content : new Blob([content]),
-    });
+    await this.upload(myHeaders, content);
 
     return Promise.resolve();
   }
+
+  private async upload(headers: Headers, content: string | Blob): Promise<void> {
+    try {
+      await this.fs.request("https://content.dropboxapi.com/2/files/upload", {
+        method: "POST",
+        headers,
+        body: content instanceof Blob ? content : new Blob([content]),
+      });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      if (message.includes("409") || message.includes("conflict") || message.includes("incorrect_offset")) {
+        throw new FileSystemError({
+          provider: "dropbox",
+          message,
+          status: message.includes("409") ? 409 : undefined,
+          conflict: true,
+          raw: error,
+        });
+      }
+      throw error;
+    }
+  }
 }

packages/filesystem/error.ts

@@ -34,6 +34,7 @@ export type FileSystemErrorOptions = {
   auth?: boolean;
   notFound?: boolean;
   rateLimit?: boolean;
+  unsupported?: boolean;
   raw?: unknown;
 };
 
@@ -54,6 +55,8 @@ export class FileSystemError extends Error {
 
   rateLimit: boolean;
 
+  unsupported: boolean;
+
   raw?: unknown;
 
   constructor(options: FileSystemErrorOptions) {
@@ -67,6 +70,7 @@ export class FileSystemError extends Error {
     this.auth = options.auth ?? false;
     this.notFound = options.notFound ?? false;
     this.rateLimit = options.rateLimit ?? false;
+    this.unsupported = options.unsupported ?? false;
     this.raw = options.raw;
   }
 }
@@ -86,3 +90,7 @@ export function isRateLimitError(error: unknown): error is FileSystemError {
 export function isAuthError(error: unknown): error is FileSystemError | WarpTokenError {
   return error instanceof FileSystemError ? error.auth : isWarpTokenError(error);
 }
+
+export function isUnsupportedError(error: unknown): error is FileSystemError {
+  return error instanceof FileSystemError && error.unsupported;
+}

packages/filesystem/filesystem.ts

@@ -8,6 +8,8 @@ export interface FileInfo {
   size: number;
   // 文件摘要
   digest: string;
+  // Provider-specific write precondition token, such as rev/etag/version.
+  version?: string;
   // 文件创建时间
   createtime: number;
   // 文件修改时间
@@ -29,6 +31,10 @@ export type FileReadWriter = FileReader & FileWriter;
 
 export type FileCreateOptions = {
   modifiedDate?: number;
+  expectedDigest?: string;
+  expectedVersion?: string;
+  createOnly?: boolean;
+  overwrite?: boolean;
 };
 
 // 文件读取

packages/filesystem/googledrive/googledrive.test.ts

@@ -135,6 +135,34 @@ describe("GoogleDriveFileSystem", () => {
     expect(findFileSpy).toHaveBeenCalledTimes(1);
   });
 
+  it("writer should update expected Google Drive file id with If-Match token", async () => {
+    const fs = new GoogleDriveFileSystem("/", "token");
+    const writer = await fs.create("file.txt", { expectedVersion: "file-1:version-7" });
+    const findSpy = vi.spyOn(fs, "findFileInDirectory");
+    const requestSpy = vi.spyOn(fs, "request").mockResolvedValue({});
+
+    await expect(writer.write("content")).resolves.toBeUndefined();
+
+    expect(findSpy).not.toHaveBeenCalled();
+    expect(requestSpy).toHaveBeenCalledTimes(1);
+    expect(requestSpy.mock.calls[0][0]).toBe(
+      "https://www.googleapis.com/upload/drive/v3/files/file-1?uploadType=multipart&spaces=appDataFolder"
+    );
+    const headers = (requestSpy.mock.calls[0][1] as RequestInit).headers as Headers;
+    expect(headers.get("If-Match")).toBe("version-7");
+  });
+
+  it("writer should reject createOnly when target already exists", async () => {
+    const fs = new GoogleDriveFileSystem("/", "token");
+    const writer = await fs.create("file.txt", { createOnly: true });
+    vi.spyOn(fs, "findFileInDirectory").mockResolvedValue("file-1");
+
+    await expect(writer.write("content")).rejects.toMatchObject({
+      provider: "googledrive",
+      conflict: true,
+    });
+  });
+
   it("list should clear stale path cache and retry once on provider 404", async () => {
     const fs = new GoogleDriveFileSystem("/Base", "token");
     const notFoundError = new FileSystemError({
@@ -351,4 +379,29 @@ describe("GoogleDriveFileSystem", () => {
       });
     }
   });
+
+  it("list should expose opaque Google Drive version token", async () => {
+    const fs = new GoogleDriveFileSystem("/", "token");
+    vi.spyOn(fs, "request").mockResolvedValue({
+      files: [
+        {
+          id: "file-1",
+          name: "test.user.js",
+          size: "12",
+          md5Checksum: "md5",
+          createdTime: "2024-01-01T00:00:00.000Z",
+          modifiedTime: "2024-01-02T00:00:00.000Z",
+          version: "7",
+        },
+      ],
+    });
+
+    await expect(fs.list()).resolves.toMatchObject([
+      {
+        name: "test.user.js",
+        digest: "md5",
+        version: "file-1:7",
+      },
+    ]);
+  });
 });