dsh-webdav-sync 1.0.0 → 1.0.2

package/lib/index.js

@@ -13,19 +13,21 @@
  * be uploaded by the next sync. It lives in the profile's
  * `.dsh-webdav-sync/sync.json`, mode 0600, beside the state and the cache.
  */
+import { isAbsolute } from 'node:path';
 import z from '@deepseek-ai/schemastery';
-import { AUTO_CHOICES, ROUTE_CHECK, ROUTE_CONFIG, ROUTE_DISMISS, ROUTE_INSTALL, ROUTE_OFF, ROUTE_PREVIEW, ROUTE_RESTORE, ROUTE_STATUS, ROUTE_SYNC, ROUTE_UNDO, ROUTE_UPLOAD, } from './wire.js';
+import { AUTO_CHOICES, DIRS_MAX, ROUTE_CHECK, ROUTE_CONFIG, ROUTE_DISMISS, ROUTE_INSTALL, ROUTE_OFF, ROUTE_PREVIEW, ROUTE_RESTORE, ROUTE_STATUS, ROUTE_SYNC, ROUTE_UNDO, ROUTE_UPLOAD, } from './wire.js';
 import { validateProfileDir, resolveFromEnv } from './paths.js';
-import { check, dismiss, engineFor, loadConfig, preview, restore, sameAccount, saveConfig, status, sync, turnOff, undo, upload, usable, } from './engine.js';
+import { RelayServer, makeRelayPassword, makeRelayUser } from './relay.js';
+import { check, dismiss, engineFor, loadConfig, preview, restore, sameAccount, status, sync, turnOff, undo, upload, usable, } from './engine.js';
 import { installPlugins } from './install.js';
 import { sameSecret } from './crypto.js';
-import { defaultConfig, normaliseConfig, heldPassword, holdPassword, releasePassword } from './state.js';
+import { normaliseDirs } from './dirs.js';
+import { parseHeaders } from './dav.js';
+import { defaultConfig, ensureStateDir, heldPassword, normaliseConfig, persistConfig } from './state.js';
 export const name = 'dsh-webdav-sync';
 export const inject = [];
 /** Largest accepted request body (bytes) — these payloads are a few strings. */
 const BODY_LIMIT = 64 * 1024;
-/** The settings namespace this plugin serves; its browser card spells the same string. */
-export const WEBDAV_SYNC_NS = 'dsh-webdav-sync';
 /** How long the auto-sync timer waits before its first attempt. */
 const FIRST_DELAY_MS = 20_000;
 function readVolatile(value) {
@@ -59,14 +61,9 @@ export function validateConfig(config) {
         throw new Error(`WebdavSyncConfig：「autoEvery」只能是 ${AUTO_CHOICES.join('、')} 之一`);
     }
 }
-/** The section-shaped view of a config: absent keys stay absent. */
-export function sectionOf(config) {
-    const profileDir = readVolatile(config.profileDir);
-    const autoEvery = readVolatile(config.autoEvery);
-    return {
-        ...(profileDir === undefined || profileDir === '' ? {} : { profileDir }),
-        autoEvery: autoEvery ?? -1,
-    };
+/** An example of the shape the directory field wants, in this platform's spelling. */
+function exampleDir() {
+    return process.platform === 'win32' ? 'D:\\dsh-extra' : '/home/you/dsh-extra';
 }
 /**
  * Apply one configuration change from the card.
@@ -101,9 +98,53 @@ export async function configure(engine, body) {
         next.patch = body.patch;
     if (typeof body.rememberPassword === 'boolean')
         next.rememberPassword = body.rememberPassword;
+    if (typeof body.headers === 'string') {
+        // Refused here rather than at the first request: the card can then show the
+        // line it is unhappy about while the user is still looking at it.
+        parseHeaders(body.headers);
+        next.headers = body.headers;
+    }
     if (typeof body.autoEvery === 'number' && AUTO_CHOICES.includes(body.autoEvery)) {
         next.autoEvery = body.autoEvery;
     }
+    if (typeof body.dirsEnabled === 'boolean')
+        next.dirsEnabled = body.dirsEnabled;
+    if (typeof body.relayEnabled === 'boolean')
+        next.relayEnabled = body.relayEnabled;
+    if (typeof body.relayPort === 'number') {
+        if (!Number.isInteger(body.relayPort) || body.relayPort < 1 || body.relayPort > 65_535) {
+            throw new Error(`转发端口要填 1 到 65535 之间的整数：「${body.relayPort}」不是`);
+        }
+        next.relayPort = body.relayPort;
+    }
+    // The account other programs sign in with, minted the first time the switch is
+    // turned on. It is minted once and then left alone: it exists to be written
+    // into those programs, and one that changed under them would be one they could
+    // no longer sign in with — so turning the switch off and on again keeps the
+    // same pair, as does any later save. A half-emptied pair (only reachable by
+    // editing `sync.json` by hand) is completed rather than left unusable.
+    if (next.relayEnabled && (next.relayUser === '' || next.relayPassword === '')) {
+        next.relayUser = makeRelayUser();
+        next.relayPassword = makeRelayPassword();
+    }
+    if (Array.isArray(body.dirs)) {
+        // What the card sends is what was typed, one line per directory. What is
+        // stored is one absolute path each in a fixed order — the part is hashed whole,
+        // so two computers that name the same set in a different order must still
+        // agree — and a relative path is refused here, while the person is still
+        // looking at the field, rather than left to fail as an unreadable directory
+        // on every later sync.
+        next.dirs = normaliseDirs(body.dirs);
+        const relative = next.dirs.find((path) => !isAbsolute(path));
+        if (relative !== undefined) {
+            throw new Error(`目录要填绝对路径，像 ${exampleDir()} 这样：「${relative}」不是`);
+        }
+        // Five at most: each one is walked on every card open and carried whole on
+        // every push, and a sixth would be a person pointing at a whole disk.
+        if (next.dirs.length > DIRS_MAX) {
+            throw new Error(`最多同步 ${DIRS_MAX} 个目录，现在填了 ${next.dirs.length} 个`);
+        }
+    }
     // The password this computer would actually send: one typed into this submit, or
     // the one already in hand for this account. What is written down is only part of
     // that — a password the user chose not to remember is held in memory for the run
@@ -130,30 +171,22 @@ export async function configure(engine, body) {
     // be one no request could ever carry, leaving sync unable to sign in until the
     // process restarts and the user retypes it. It stays in the engine — which is
     // what the running half talks to the server with — and is left out of what is
-    // written down.
-    if (next.rememberPassword) {
-        await saveConfig(engine.paths, next);
-        releasePassword(engine.paths);
-    }
-    else {
-        await saveConfig(engine.paths, { ...next, password: '' });
-        holdPassword(engine.paths, next.password);
-    }
+    // written down. That split lives in one place, {@link persistConfig}, because
+    // this is no longer the only writer of the configuration.
+    await persistConfig(engine.paths, next);
     engine.config = next;
 }
 /**
  * Plugin apply: mount the settings presentation policy, the HTTP routes and the
  * auto-sync timer on any webServer that comes and goes.
- */
-/**
- * Passwords that are in use but deliberately not on disk.
  *
- * "Remember the password" off means it must not be written to `sync.json`, and
- * it does not mean it should stop working: every route rebuilds its engine from
- * that file, so a password emptied there would be one no request could carry and
- * sync would be unable to sign in until the process restarted. It is held for as
- * long as the host runs, keyed by the state directory so two profiles do not
- * share one, and put back into the configuration each time it is read.
+ * Passwords that are in use but deliberately not on disk are read back here:
+ * "remember the password" off means it must not be written to `sync.json`, and it
+ * does not mean it should stop working. Every route rebuilds its engine from that
+ * file, so a password emptied there would be one no request could carry and sync
+ * would be unable to sign in until the process restarted. It is held for as long
+ * as the host runs, keyed by the state directory so two profiles do not share
+ * one, and put back into the configuration each time it is read.
  */
 export function apply(ctx, config = {}) {
     validateConfig(config);
@@ -171,6 +204,22 @@ export function apply(ctx, config = {}) {
     ctx.inject(['settings'], (settingsCtx) => {
         settingsCtx.effect(() => settingsCtx.settings.configure({ auto: false }, ctx.fiber), 'webdav-sync: settings presentation policy');
     });
+    // The forwarder for other programs on this computer. It is a switch on the
+    // configuration above rather than a second one, so it is handed that
+    // configuration and nothing else: the address it forwards to, the account it
+    // signs in with and the extra headers it adds are the ones the sync is already
+    // set up with. What it adds is a door — an address on loopback, and an account
+    // of its own, because the programs that come in by it hold that account and the
+    // WebDAV password itself is never handed out to them.
+    const relay = new RelayServer();
+    let relayStopped = false;
+    void engine()
+        .then((current) => relayStopped ? undefined : relay.apply(current.config, current.paths.stateDir))
+        .catch(() => undefined);
+    ctx.effect(() => () => {
+        relayStopped = true;
+        void relay.stop();
+    }, 'webdav-sync: relay forwarder');
     ctx.inject(['webServer'], (webCtx) => {
         const send = (res, status, body) => {
             res.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' });
@@ -224,21 +273,29 @@ export function apply(ctx, config = {}) {
             }), `webdav-sync: ${label} route`);
         };
         route(ROUTE_STATUS, 'status', async (_req, res) => {
-            const result = await status(await engine());
-            send(res, 200, result);
+            const current = await engine();
+            // The forwarder is a switch on this configuration, so this is where it is
+            // brought in line with it: the card asks for this when it opens and every
+            // fifteen seconds after, which is what makes a switch turned on in another
+            // window, or a `sync.json` edited by hand, take effect.
+            await relay.apply(current.config, current.paths.stateDir);
+            send(res, 200, { ...(await status(current)), relay: relay.view() });
         });
         route(ROUTE_CONFIG, 'config', async (_req, res, body) => {
             const current = await engine();
             await configure(current, (body ?? {}));
             await saveStateIfUsable(current);
+            // Saved and applied in the same breath: the card reloads the status right
+            // after this, and that read must not be the thing that makes the switch
+            // real — a port the user cannot see the result of until later reads as one
+            // that did not take.
+            await relay.apply(current.config, current.paths.stateDir);
             send(res, 200, { message: '已保存' });
         });
         route(ROUTE_CHECK, 'check', async (_req, res) => {
-            const current = await engine();
-            if (!usable(current.config) && current.config.url.trim() === '') {
-                throw new Error('请先填写同步地址');
-            }
-            send(res, 200, await check(current));
+            // An address that is not filled in is refused by `check` itself, in the one
+            // sentence the card shows for it.
+            send(res, 200, await check(await engine()));
         });
         route(ROUTE_SYNC, 'sync', async (req, res, body) => {
             const current = await engine();
@@ -263,6 +320,8 @@ export function apply(ctx, config = {}) {
         });
         route(ROUTE_OFF, 'off', async (_req, res) => {
             await turnOff(await engine());
+            const updated = await engine();
+            await relay.apply(updated.config, updated.paths.stateDir);
             send(res, 200, { message: '已关闭 WebDAV 同步；服务器上的文件保持原样' });
         });
         route(ROUTE_INSTALL, 'install', async (_req, res) => {
@@ -272,10 +331,9 @@ export function apply(ctx, config = {}) {
     });
     startTimer(ctx, currentConfig);
 }
-/** Write a state file that records the new configuration's key, if it can be written. */
+/** Make sure the state directory exists, so the first sync has somewhere to write. */
 async function saveStateIfUsable(engine) {
     try {
-        const { ensureStateDir } = await import('./state.js');
         await ensureStateDir(engine.paths);
     }
     catch {

package/lib/relay.d.ts

@@ -0,0 +1,119 @@
+/**
+ * The forwarder for other WebDAV clients on this computer.
+ *
+ * It is a switch on the sync's own configuration, not a second one. There is
+ * nothing here to fill in: the address it forwards to, the account it signs in
+ * with and the extra headers it adds are the ones the sync is already configured
+ * with, and it reads them per request from the configuration the host is holding.
+ * What it adds is a door a local client can come in by — an address on loopback,
+ * and an account of its own to knock with, because those clients hold that
+ * account and must not be handed the real WebDAV password as well.
+ *
+ * What it does is a byte pipe for request bodies. It preserves client paths except
+ * for the `.prop` compatibility suffix, and reverses only suffixes the relay added
+ * when returning PROPFIND hrefs. The `location` header of a redirect is pointed
+ * back here too.
+ */
+import { type RelayView, type SyncConfig } from './wire.js';
+/** The name half of a fresh account: short, hex, and easy to type again. */
+export declare function makeRelayUser(): string;
+/** The password half of a fresh account. Minted once and then kept. */
+export declare function makeRelayPassword(): string;
+/**
+ * The forwarder itself.
+ *
+ * One instance lives for as long as the host runs. The host hands it the
+ * configuration it is holding — at startup, after every save, and on every card
+ * read — and it brings its listening socket in line with it. The configuration
+ * is kept rather than looked up per request, so a request never waits on a file
+ * read, and the account, the target and the headers it uses are all from one
+ * single version of the configuration.
+ */
+export declare class RelayServer {
+    private config;
+    private server;
+    private failure;
+    private aliasFile;
+    private aliases;
+    private aliasWrites;
+    /** The port the socket in hand is bound to, so a change of port rebuilds it. */
+    private bound;
+    /** Socket changes cannot overlap a startup read, a save, or a status poll. */
+    private pending;
+    private enqueue;
+    /**
+     * Bring the socket in line with a configuration.
+     *
+     * Off, or on with something missing, closes it rather than leaving a listener
+     * that answers every request with a complaint: a client that reaches a door
+     * gets a straight answer from the server behind it, or no door at all. A port
+     * that is merely taken is not a refusal — the configuration is good, the socket
+     * is not, and {@link view} says which.
+     */
+    apply(config: SyncConfig, stateDir?: string): Promise<void>;
+    private applyNow;
+    private loadAliases;
+    private saveAliases;
+    private changeAlias;
+    /** What the card shows. Never throws: a failure is a field, not an exception. */
+    view(): RelayView;
+    /** Stop listening. Called when the plugin is disposed. */
+    stop(): Promise<void>;
+    /** The target address, parsed, or the complaint the card shows. */
+    private targetOf;
+    /** The account a client has to sign in with, or the complaint the card shows. */
+    private accountOf;
+    /** Rebuild the socket for one port. Failures are recorded, never thrown. */
+    private listen;
+    /** Close the socket and anything still talking on it. */
+    private close;
+    /**
+     * One forwarded request.
+     *
+     * The caller signs in with the relay's account, and only then is anything sent
+     * on: an address on loopback is not a boundary — any program on this computer
+     * can reach it — so the account is the whole of what decides who may spend the
+     * sync's credentials, and a caller that does not have it learns nothing.
+     */
+    private handle;
+    /** Whether a caller signed in with the relay's own account. */
+    private authorised;
+    /**
+     * Where a request the client made goes on the real server.
+     *
+     * The address the client was given carries the target's own base path, and
+     * clients differ in what they do with it: one joins its paths onto the host
+     * alone, another keeps the base path it was handed and appends to it. Both are
+     * made to work — a path that already begins with the base path is taken as it
+     * stands, and one that does not is given it — so the same address is correct
+     * for either habit rather than only for the one the author happened to test.
+     */
+    private upstreamPath;
+    /** Map a same-relay Destination to the configured upstream and return its alias. */
+    private rewriteDestination;
+    /**
+     * The headers the forwarded request carries.
+     *
+     * The configured ones are the reason the forwarder exists, and the client's own
+     * are the protocol headers its request is made of, so a collision goes to the
+     * client. `authorization` is the one header that never comes from the client:
+     * it was addressed to this forwarder, not to the server, and the server is given
+     * the sync's own credential — or, when the configuration names an
+     * `Authorization` line of its own, exactly that line, since a hand-written one
+     * is the more specific instruction.
+     */
+    /** Configuration headers obey the same connection boundary as client headers. */
+    private configuredHeaders;
+    private forwardHeaders;
+    /** The headers a response carries back: connection-level ones out, location mapped. */
+    private responseHeaders;
+    /**
+     * A redirect that points at the real server is pointed back at this forwarder,
+     * path and query untouched. Left alone, the client would follow it straight to
+     * the server and from then on talk around the forwarder — losing the account
+     * and the headers this exists for.
+     */
+    private rewriteLocation;
+    /** Answer with a short plain-text refusal, unless the answer already started. */
+    private refuse;
+}