dsh-webdav-sync 1.0.0 → 1.0.2

package/lib/dav.d.ts

@@ -1,5 +1,5 @@
 /**
- * The WebDAV client. One file lives at `<address>/dsh-webdav/dsh-profile.dshsync`,
+ * The WebDAV client. One file lives at `<address>/dsh-webdav/dsh-profile.prop`,
  * and the whole protocol between this computer and that file is:
  *
  *   - read it, with the version last seen so an unchanged file costs one request;
@@ -18,10 +18,6 @@ import { type ServerVersion } from './wire.js';
 export declare class ChangedError extends Error {
     constructor();
 }
-/** The file is still the version last read; the server did not send it again. */
-export declare class NotModifiedError extends Error {
-    constructor();
-}
 /** The server refused the account. */
 export declare class LoginError extends Error {
     constructor();
@@ -42,6 +38,14 @@ export interface DavOptions {
     url: string;
     user: string;
     password: string;
+    /**
+     * Extra headers sent with every request, one `Name: value` pair each. They go
+     * on before this client's own headers, so a header the protocol depends on —
+     * `If-Match`, `If-None-Match`, `Depth`, `Accept-Encoding` — cannot be broken
+     * by one configured here; and they go on before the Basic credential too, so
+     * a configured `Authorization` replaces it.
+     */
+    headers?: Record<string, string>;
 }
 /**
  * What one read found. `data` is absent when the server holds no file yet — which
@@ -68,6 +72,7 @@ export declare class Dav {
     private readonly basePath;
     private readonly user;
     private readonly password;
+    private readonly extraHeaders;
     constructor(options: DavOptions);
     /** The address, without any credentials that may have ridden in on it. */
     get address(): string;
@@ -79,10 +84,18 @@ export declare class Dav {
      * Read the backup.
      *
      * Returns `undefined` when the server holds none yet — which several servers
-     * say in several ways. Throws {@link NotModifiedError} when `have` is still
-     * current, {@link LoginError}, {@link RateLimitedError} or {@link ForbiddenError}.
+     * say in several ways. Returns `{ notModified: true }` when `have` is still
+     * current. Throws {@link LoginError}, {@link RateLimitedError} or
+     * {@link ForbiddenError}.
      */
     get(have?: ServerVersion): Promise<DavRead>;
+    /**
+     * One read of one address: the parsed answer, or `undefined` when nothing is
+     * there — 404, 410, 409 (how 坚果云 answers a read of a folder that is not there
+     * yet), and a Synology's 403 for a file in a folder that is not there, which is
+     * the state before the first sync.
+     */
+    private readAt;
     /**
      * Write the backup, only over the version that was read when there was one.
      *
@@ -135,3 +148,10 @@ export declare class Dav {
     /** The rate-limit error for an answer, carrying the server's own wait when it named one. */
     private limited;
 }
+/**
+ * Parse the configured extra headers: one `Name: value` per line, blank lines
+ * and lines starting with `#` ignored. A line that cannot be a header is
+ * refused with the line number rather than dropped, so a typo shows up while it
+ * is being saved instead of surfacing as a puzzling failure on the next sync.
+ */
+export declare function parseHeaders(text: string): Record<string, string>;

package/lib/dav.js

@@ -1,5 +1,5 @@
 /**
- * The WebDAV client. One file lives at `<address>/dsh-webdav/dsh-profile.dshsync`,
+ * The WebDAV client. One file lives at `<address>/dsh-webdav/dsh-profile.prop`,
  * and the whole protocol between this computer and that file is:
  *
  *   - read it, with the version last seen so an unchanged file costs one request;
@@ -13,7 +13,7 @@
  * it hands back, which then never matches in `If-Match`. Every one of those is
  * handled where it happens, with the reason it exists written beside it.
  */
-import { REMOTE_FILE, REMOTE_FOLDER } from './wire.js';
+import { LEGACY_REMOTE_FILE, REMOTE_FILE, REMOTE_FOLDER } from './wire.js';
 /** The file was not written because it changed on the server since it was read. */
 export class ChangedError extends Error {
     constructor() {
@@ -21,13 +21,6 @@ export class ChangedError extends Error {
         this.name = 'ChangedError';
     }
 }
-/** The file is still the version last read; the server did not send it again. */
-export class NotModifiedError extends Error {
-    constructor() {
-        super('服务器上的文件没有变化');
-        this.name = 'NotModifiedError';
-    }
-}
 /** The server refused the account. */
 export class LoginError extends Error {
     constructor() {
@@ -73,6 +66,7 @@ export class Dav {
     basePath;
     user;
     password;
+    extraHeaders;
     constructor(options) {
         const trimmed = (options.url ?? '').trim();
         let parsed;
@@ -93,6 +87,7 @@ export class Dav {
         this.basePath = path;
         this.user = options.user ?? '';
         this.password = options.password ?? '';
+        this.extraHeaders = options.headers ?? {};
     }
     /** The address, without any credentials that may have ridden in on it. */
     get address() {
@@ -115,8 +110,9 @@ export class Dav {
      * Read the backup.
      *
      * Returns `undefined` when the server holds none yet — which several servers
-     * say in several ways. Throws {@link NotModifiedError} when `have` is still
-     * current, {@link LoginError}, {@link RateLimitedError} or {@link ForbiddenError}.
+     * say in several ways. Returns `{ notModified: true }` when `have` is still
+     * current. Throws {@link LoginError}, {@link RateLimitedError} or
+     * {@link ForbiddenError}.
      */
     async get(have) {
         const headers = { 'accept-encoding': 'identity' };
@@ -127,30 +123,46 @@ export class Dav {
             headers['if-none-match'] = have.etag;
         else if (have?.modified !== undefined && have.modified !== '')
             headers['if-modified-since'] = have.modified;
+        const read = await this.readAt(this.fileUrl, headers, have);
+        if (read !== undefined)
+            return read;
+        // A folder this plugin filled under its earlier name still holds the same
+        // backup under that name. Reading it makes this run an ordinary sync; calling
+        // the server empty instead would have this computer push its own setup up
+        // over whatever the other computer left there, silently.
+        //
+        // Its version is dropped rather than carried: the write that follows names
+        // the new file, which the server has no ETag for, and an `If-Match` against a
+        // file that does not exist yet would be refused. The merge still runs against
+        // the bytes just read, so nothing is written blind that was not merged first.
+        const legacy = await this.readAt(this.url(REMOTE_FOLDER, LEGACY_REMOTE_FILE), headers, have);
+        return legacy === undefined ? { version: {} } : { ...legacy, version: {} };
+    }
+    /**
+     * One read of one address: the parsed answer, or `undefined` when nothing is
+     * there — 404, 410, 409 (how 坚果云 answers a read of a folder that is not there
+     * yet), and a Synology's 403 for a file in a folder that is not there, which is
+     * the state before the first sync.
+     */
+    async readAt(url, headers, have) {
         const conditional = headers['if-none-match'] !== undefined || headers['if-modified-since'] !== undefined;
-        const response = await this.send('GET', this.fileUrl, undefined, headers);
+        const response = await this.send('GET', url, undefined, headers);
         if (response.status === 304 && conditional) {
             return { version: have ?? {}, notModified: true };
         }
         if (response.status === 403) {
-            // A Synology answers 403, not 404, for a file in a folder that is not
-            // there — which is the state before the first sync.
             if (!(await this.there(`${this.url(REMOTE_FOLDER)}/`)))
-                return { version: {} };
+                return undefined;
             throw await this.forbiddenMessage();
         }
         if (response.status === 404 || response.status === 410 || response.status === 409) {
-            // 409 is how 坚果云 answers a read of a folder that is not there yet.
-            return { version: {} };
+            return undefined;
         }
         if (response.status !== 200) {
             await drain(response);
             throw new Error(`从 WebDAV 服务器读取 ${REMOTE_FILE} 失败：HTTP ${response.status}`);
         }
-        const buffer = new Uint8Array(await response.arrayBuffer());
-        if (buffer.byteLength > MAX_BYTES) {
-            throw new Error(`WebDAV 服务器上的文件超过 ${MAX_BYTES} 字节，没有读取`);
-        }
+        const buffer = await readLimited(response, MAX_BYTES);
         const data = await unpacked(buffer, response.headers.get('content-encoding'));
         // A redirect that ended somewhere other than the file — a web app's sign-in
         // or files page — is carried out with where it went, so the caller can say
@@ -273,7 +285,12 @@ export class Dav {
         // 405: the server does not do HEAD, so the size is asked of PROPFIND instead.
         // 403/404/409/410: no file yet, which is not an error here.
         const found = await this.length(this.fileUrl);
-        return found === undefined ? { exists: false } : { exists: true, size: found };
+        if (found !== undefined)
+            return { exists: true, size: found };
+        // A backup still under the earlier name is one this plugin wrote, and the
+        // question the card asks — "is there one on the server" — means that one too.
+        const legacy = await this.length(this.url(REMOTE_FOLDER, LEGACY_REMOTE_FILE));
+        return legacy === undefined ? { exists: false } : { exists: true, size: legacy };
     }
     /**
      * Make the folder, tolerating the several ways servers say it is already
@@ -430,9 +447,18 @@ export class Dav {
     /** One request, with auth, redirect and rate-limit handling applied. */
     async send(method, url, body, headers = {}) {
         const requestHeaders = new Headers();
+        // Configured headers go on first, so a header this client computes per
+        // request wins a name collision: a configured `If-Match` would turn the
+        // conditional write into a blind one, and a configured `Depth` would make
+        // the folder probe answer for the wrong level.
+        for (const [key, value] of Object.entries(this.extraHeaders))
+            requestHeaders.set(key, value);
         for (const [key, value] of Object.entries(headers))
             requestHeaders.set(key, value);
-        if (this.user !== '' || this.password !== '') {
+        // The credential is the fallback, not the winner: a configured
+        // `Authorization` (a bearer token for a proxy in front of the server, say)
+        // is left in place.
+        if ((this.user !== '' || this.password !== '') && !requestHeaders.has('authorization')) {
             requestHeaders.set('authorization', `Basic ${Buffer.from(`${this.user}:${this.password}`, 'utf8').toString('base64')}`);
         }
         let response;
@@ -465,6 +491,28 @@ export class Dav {
         return new RateLimitedError(response.status, retryAfter(response.headers.get('retry-after')));
     }
 }
+/**
+ * Parse the configured extra headers: one `Name: value` per line, blank lines
+ * and lines starting with `#` ignored. A line that cannot be a header is
+ * refused with the line number rather than dropped, so a typo shows up while it
+ * is being saved instead of surfacing as a puzzling failure on the next sync.
+ */
+export function parseHeaders(text) {
+    const out = {};
+    const lines = (text ?? '').split(/\r?\n/);
+    lines.forEach((raw, index) => {
+        const line = raw.trim();
+        if (line === '' || line.startsWith('#'))
+            return;
+        const at = line.indexOf(':');
+        const name = at < 0 ? '' : line.slice(0, at).trim();
+        if (at < 1 || !/^[\w!#$%&'*+\-.^`|~]+$/i.test(name)) {
+            throw new Error(`第 ${index + 1} 行「${line}」不是请求头：请写成「名字: 值」，一行一个`);
+        }
+        out[name] = line.slice(at + 1).trim();
+    });
+    return out;
+}
 /** The version an answer's headers name; empty when nothing can be asked about again. */
 function versionOf(headers) {
     const etag = headers.get('etag');
@@ -510,17 +558,75 @@ async function unpacked(data, encoding) {
     }
     const { gunzipSync, inflateSync } = await import('node:zlib');
     const buffer = Buffer.from(data);
-    const plain = word === 'deflate' ? inflateSync(buffer) : gunzipSync(buffer);
-    return new Uint8Array(plain);
+    // The cap is on what the read accepts, so it applies to the bytes that come out
+    // of here too: a small compressed body that unpacks to gigabytes would otherwise
+    // be the one way left to make this process hold more than it agreed to.
+    try {
+        const plain = (word === 'deflate' ? inflateSync : gunzipSync)(buffer, { maxOutputLength: MAX_BYTES });
+        return new Uint8Array(plain);
+    }
+    catch (cause) {
+        if (cause.code === 'ERR_BUFFER_TOO_LARGE') {
+            throw new Error(`WebDAV 服务器上的文件解压后超过 ${MAX_BYTES} 字节，没有读取`);
+        }
+        throw cause;
+    }
 }
-/** Read and discard a body, so the connection can be reused. */
+/**
+ * Read and discard a body, so the connection can be reused.
+ *
+ * Only the first slice of it, and only up to a bound: an error page this plugin
+ * is about to throw away is not worth holding a whole answer for, and a server
+ * that answers with something enormous must not be able to make it.
+ */
 async function drain(response) {
     try {
-        await response.arrayBuffer();
+        await readLimited(response, MAX_BYTES);
     }
     catch {
-        // A body that cannot be read is of no use to anybody.
+        // A body that cannot be read is of no use to anybody, and neither is its
+        // size: the caller is already on the way to reporting the status.
+    }
+}
+/**
+ * Read a body, refusing it the moment it grows past `limit`.
+ *
+ * The count is taken as the bytes arrive rather than after the fact: a server
+ * that sends no length, or sends a length that is not true, would otherwise have
+ * this process hold the whole answer in memory before the check that rejects it
+ * gets to run.
+ */
+async function readLimited(response, limit) {
+    const body = response.body;
+    if (body === null) {
+        const whole = new Uint8Array(await response.arrayBuffer());
+        if (whole.byteLength > limit)
+            throw new Error(`WebDAV 服务器上的文件超过 ${limit} 字节，没有读取`);
+        return whole;
+    }
+    const reader = body.getReader();
+    const chunks = [];
+    let total = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        if (value === undefined)
+            continue;
+        total += value.byteLength;
+        if (total > limit) {
+            await reader.cancel().catch(() => undefined);
+            throw new Error(`WebDAV 服务器上的文件超过 ${limit} 字节，没有读取`);
+        }
+        chunks.push(value);
+    }
+    const out = new Uint8Array(total);
+    let at = 0;
+    for (const chunk of chunks) {
+        out.set(chunk, at);
+        at += chunk.byteLength;
     }
+    return out;
 }
 /** The path an address names, for messages. */
 function displayPath(url) {

package/lib/dirs.d.ts

@@ -0,0 +1,114 @@
+/**
+ * The extra directories: reading them into the `dirs` part, and writing that
+ * part back out.
+ *
+ * The four profile parts are read from two files whose shape this plugin already
+ * knows. This one is different in three ways, and each of them shapes the code
+ * below:
+ *
+ * - **It is a whole tree, not a file.** Reading means walking, so it is capped:
+ *   a directory over the cap is refused as a whole rather than half-carried,
+ *   because half a directory that then gets pushed would delete the rest for
+ *   everybody else.
+ * - **Its path is part of the data.** The user names a directory; the path
+ *   travels so a restore writes back into the same directory instead of inventing
+ *   one. A path this computer cannot make sense of is therefore not an error to
+ *   shout about — it is a directory to leave exactly as the server has it.
+ * - **Writing is additive.** A sync writes and overwrites files here; it never
+ *   removes one. Mirrored deletion inside a person's own directory is the one
+ *   accident this feature could cause that no notice could undo, and a union is
+ *   the safe half of the trade: a file deleted on one computer comes back from the
+ *   others, and deleting it everywhere is done by hand — the same bargain the
+ *   plugin already makes for the plugin list (see
+ *   `docs/decisions/0005-four-parts-and-plugin-exception.md`).
+ */
+import type { DirProblem, DirSpec, DirsPart } from './wire.js';
+/**
+ * Names never descended into. `node_modules` because a plugin's own dependencies
+ * are installed on each computer rather than carried, `.git` because a repository
+ * there has an owner of its own. Both are skipped in silence: a skipped name is
+ * not a directory that failed to read.
+ */
+export declare const DIRS_SKIP: ReadonlySet<string>;
+/** Most files one configured directory may carry. */
+export declare const DIRS_MAX_FILES = 2000;
+/** Most bytes one configured directory may carry, before base64 and sealing. */
+export declare const DIRS_MAX_BYTES: number;
+/** What reading the configured directories produced. */
+export interface DirsRead {
+    /** The directories that could be read, in the configured order. */
+    entries: DirSpec[];
+    /** Newest modification time among every file read; 0 when nothing was read. */
+    mtimeMs: number;
+    /** Directories that could not be read, and why. */
+    problems: DirProblem[];
+}
+/** Writing reported back to the caller, for the run's own bookkeeping. */
+export interface DirsWrite {
+    /** True when at least one file's bytes were written. */
+    changed: boolean;
+    /** The absolute paths the part carried, in order, for the configuration to record. */
+    paths: string[];
+}
+/**
+ * The stored list of directories: strings only, trimmed, no blanks, no repeats,
+ * in a fixed order.
+ *
+ * The order is by path rather than by when each was added, so the same set of
+ * directories hashes the same on every computer — the part is hashed whole, and
+ * two computers that name the same directories in a different order would
+ * otherwise see a change that is not one.
+ */
+export declare function normaliseDirs(value: unknown): string[];
+/** Path order, used wherever the set of directories is put in canonical order. */
+export declare function comparePath(a: string, b: string): number;
+/**
+ * Read every configured directory.
+ *
+ * Nothing throws: this runs on every status call, and a card that cannot be
+ * opened because a directory on a disconnected drive is not there would be worse
+ * than a card that says so. What cannot be read is reported in `problems`, and
+ * {@link dirsPartOf} decides what to do about it.
+ */
+export declare function readDirs(dirs: readonly string[]): Promise<DirsRead>;
+/**
+ * The `dirs` part this computer holds, given what the server holds.
+ *
+ * Without a problem this is simply what is on disk — and `undefined` when there is
+ * nothing on disk, which keeps a computer that syncs no directories from putting an
+ * empty `dirs` part on the server and quietly emptying it for the computers that do.
+ *
+ * With a problem it is still what is on disk, except for the directories that could
+ * not be read: those take the server's copy verbatim. That is the whole reason this
+ * function exists. Reading a directory that is not there as "a directory with no
+ * files in it" would make the next push announce that every file in it was deleted,
+ * and a disconnected drive would quietly empty everybody else's copy of it. Carrying
+ * the server's copy instead means such a directory is neither read nor written this
+ * run, and the card says which one it was.
+ */
+export declare function dirsPartOf(read: DirsRead, carried: DirsPart | undefined): DirsPart | undefined;
+/**
+ * Put one `dirs` part on disk.
+ *
+ * Only directories that are absolute *on this computer* are touched: the list
+ * travels, so a path another computer named may not be a path here, and writing
+ * into a made-up relative one would scatter files around the working directory.
+ * Those paths stay in the list — the part is carried whole, and dropping one here
+ * would delete it for the computers that can use it — and are simply not read or
+ * written on this machine.
+ *
+ * `skip` holds the directories this run could not read. They are left alone for
+ * the same reason {@link dirsPartOf} carries them: whatever is at that path now is
+ * not this sync's business to replace, and it may well be nothing at all.
+ */
+export declare function writeDirs(part: DirsPart, skip: ReadonlySet<string>): Promise<DirsWrite>;
+/**
+ * Whether writing the part would change anything on disk.
+ *
+ * Asked before the copy kept for Undo is taken. That copy carries the directories
+ * when they are about to be written to, and a tree can run to megabytes — sealing one
+ * on every sync whose server copy of this part merely *existed* would cost a
+ * profile-size file per sync for a write that changes no file, which is exactly what
+ * happens on a computer that syncs no directories of its own and is sent somebody's.
+ */
+export declare function dirsDiffer(part: DirsPart, skip: ReadonlySet<string>): Promise<boolean>;