obsidian-mcp-server 3.6.1 → 3.7.1

package/dist/services/obsidian/obsidian-service.js

@@ -8,9 +8,54 @@ import { configurationError, conflict, forbidden, JsonRpcErrorCode, McpError, no
 import { httpStatusToErrorCode, withRetry } from '@cyanheads/mcp-ts-core/utils';
 import { Agent, fetch as undiciFetch } from 'undici';
 import { getServerConfig } from '../../config/server-config.js';
-import { canonicalContent, flattenDocumentMap, flattenHeadingTree, hasIntegerKey, inNoteOrder, isIntegerKey, patchFormatFor, relativeHeadingLevels, v1PatchHeaders, v2Instruction, } from './patch-instruction.js';
+import { assertTreeDepth, createJsonLogicEvaluation, readsContent } from './jsonlogic-evaluator.js';
+import { canonicalContent, flattenDocumentMap, flattenHeadingTree, hasIntegerKey, inNoteOrder, isIntegerKey, patchFormatFor, relativeHeadingLevels, v1HeadingBody, v1PatchHeaders, v2Instruction, } from './patch-instruction.js';
 import { PathPolicy } from './path-policy.js';
 import { atxHeadingMarkers, blockKinds, isIsolatedBlockId, listHeadingPaths, sectionBody, sectionLevel, } from './section-extractor.js';
+/**
+ * Most note-body bytes (by `stat.size`) a scoped JSONLogic search fetches and
+ * evaluates at once. Each batch costs one upstream search, during which the
+ * plugin reads every vault note's body, since the body-fetch tree names
+ * `content`; so this trades those vault-wide reads against how much of the
+ * readable vault sits in memory.
+ */
+const CONTENT_BATCH_BYTES = 32 * 1024 * 1024;
+/** Split `notes`, in order, into runs whose bodies total at most {@link CONTENT_BATCH_BYTES}; a larger note gets a run of its own. */
+function contentBatches(notes) {
+    const batches = [];
+    let current = [];
+    let bytes = 0;
+    for (const note of notes) {
+        if (current.length > 0 && bytes + note.stat.size > CONTENT_BATCH_BYTES) {
+            batches.push(current);
+            current = [];
+            bytes = 0;
+        }
+        current.push(note);
+        bytes += note.stat.size;
+    }
+    if (current.length > 0)
+        batches.push(current);
+    return batches;
+}
+/**
+ * How long a stored scoped JSONLogic walk outlives its last read. A scoped
+ * evaluation reads every readable note, so a walk's later pages are served
+ * from the hit list its first page stored rather than evaluated again.
+ */
+const WALK_TTL_MS = 5 * 60_000;
+/** Most characters all stored walks hold together, each its tree plus its serialized hits; the least recently read goes first. */
+const WALK_STORE_CHARS = 32 * 1024 * 1024;
+/** Size of a stored walk: its serialized tree plus its serialized hits, counted until it passes `limit`. */
+function walkChars(tree, hits, limit) {
+    let total = tree.length;
+    for (const hit of hits) {
+        if (total > limit)
+            break;
+        total += hit.filename.length + JSON.stringify(hit.result).length;
+    }
+    return total;
+}
 /** Per-call timeout for the startup probe — covers the 4-tuple TCP handshake + a tiny GET. */
 const OMNISEARCH_PROBE_TIMEOUT_MS = 500;
 /**
@@ -104,6 +149,9 @@ export class ObsidianService {
      * one read; a failed read is evicted so the next write tries again.
      */
     #patchFormat;
+    /** Stored scoped JSONLogic walks by id, least recently read first (`pageJsonLogic`). */
+    #walks = new Map();
+    #walkChars = 0;
     /**
      * @param config - Validated server config (api key, base URL, TLS, timeouts).
      * @param fetchImpl - Optional fetch override for tests. Defaults to undici's
@@ -125,7 +173,7 @@ export class ObsidianService {
         });
         this.#fetch = fetchImpl ?? undiciFetch;
     }
-    /** Path-policy accessor — used by `obsidian_search_notes` to filter hits. */
+    /** Path-policy accessor for tools that filter results or check scope themselves. */
     get policy() {
         return this.#policy;
     }
@@ -165,7 +213,7 @@ export class ObsidianService {
     // ── Notes ────────────────────────────────────────────────────────────────
     async getNoteContent(ctx, target) {
         if (target.type === 'path') {
-            this.#policy.assertReadable(target.path);
+            this.#policy.assertReadable(target.path, target.resolvedFrom);
             const url = this.#targetToPath(target);
             const res = await this.#request(ctx, url, {
                 method: 'GET',
@@ -193,43 +241,51 @@ export class ObsidianService {
     }
     async getNoteJson(ctx, target) {
         if (target.type === 'path') {
-            this.#policy.assertReadable(target.path);
+            this.#policy.assertReadable(target.path, target.resolvedFrom);
         }
         const note = await this.#rawGetNoteJson(ctx, target);
         if (target.type !== 'path') {
-            this.#policy.assertReadable(note.path);
+            const pinned = this.pinTarget(target, note.path);
+            this.#policy.assertReadable(pinned.path, pinned.resolvedFrom);
         }
         return note;
     }
     /**
-     * Resolve `target` to a vault-relative path. For path targets this is a
-     * no-op; for `active` and `periodic` targets we have to ask upstream which
-     * concrete file is currently in play.
+     * Pin `target` to the note it names right now. A path target comes back as
+     * sent; an `active` or `periodic` target is resolved upstream (read-gated)
+     * and comes back as a path target for that note, so every later call acts on
+     * the same file however the target moves in between.
      */
-    async resolvePath(ctx, target) {
+    async resolveTarget(ctx, target) {
         if (target.type === 'path')
-            return target.path;
-        return (await this.getNoteJson(ctx, target)).path;
+            return target;
+        return this.pinTarget(target, (await this.getNoteJson(ctx, target)).path);
     }
+    /**
+     * `target` as a path target for `path`, the note a read of `target` returned.
+     * A path target already names its note and comes back as sent. A pinned
+     * `active` / `periodic` target carries the target's label as `resolvedFrom`,
+     * the identifier `no_active_file` and `periodic_not_found` use, so a
+     * `path_forbidden` denial on it names the target rather than the note.
+     */
+    pinTarget(target, path) {
+        if (target.type === 'path')
+            return target;
+        return { type: 'path', path, resolvedFrom: displayPath(this.#targetToPath(target)) };
+    }
+    /**
+     * The note's headings, block ids, and frontmatter field names. An `active` /
+     * `periodic` target is resolved once (read-gated, a denial named by the
+     * target's label) and the map read from the resolved `/vault/` path, which
+     * the plugin's `/active/` and `/periodic/…` routes delegate to anyway, so the
+     * map describes the note the resolution returned even if the target moves.
+     */
     async getDocumentMap(ctx, target) {
-        if (target.type === 'path') {
-            this.#policy.assertReadable(target.path);
-            return this.#rawGetDocumentMap(ctx, target);
-        }
-        if (this.#policy.isUnrestricted) {
-            return this.#rawGetDocumentMap(ctx, target);
+        if (target.type !== 'path') {
+            return this.#rawGetDocumentMap(ctx, await this.resolveTarget(ctx, target));
         }
-        /**
-         * Restricted + non-path: parallel-fetch the document map and resolve the
-         * path so we can gate. If the gate denies, the parallel fetch result is
-         * discarded — acceptable cost given the rarity of this configuration.
-         */
-        const [path, map] = await Promise.all([
-            this.resolvePath(ctx, target),
-            this.#rawGetDocumentMap(ctx, target),
-        ]);
-        this.#policy.assertReadable(path);
-        return map;
+        this.#policy.assertReadable(target.path, target.resolvedFrom);
+        return this.#rawGetDocumentMap(ctx, target);
     }
     async writeNote(ctx, target, content, contentType = 'markdown') {
         const safe = await this.#gateAsWrite(ctx, target);
@@ -262,13 +318,15 @@ export class ObsidianService {
         const safe = await this.#gateAsWrite(ctx, target);
         const url = this.#targetToPath(safe);
         const format = await this.#wireFormat(ctx, safe, instruction);
-        const resolvedTarget = await this.#resolveHeadingTarget(ctx, safe, instruction, format);
+        const { target: resolvedTarget, note } = await this.#resolveHeadingTarget(ctx, safe, instruction, format);
         const resolved = { ...instruction, target: resolvedTarget };
         if (format === '1') {
             await this.#request(ctx, url, {
                 method: 'PATCH',
                 headers: v1PatchHeaders(resolved),
-                body: content,
+                body: note === undefined || resolved.contentType === 'json'
+                    ? content
+                    : v1HeadingBody(resolved, content, note),
             });
             return resolvedTarget;
         }
@@ -306,7 +364,7 @@ export class ObsidianService {
      */
     async tryGetSize(ctx, target) {
         if (target.type === 'path') {
-            this.#policy.assertReadable(target.path);
+            this.#policy.assertReadable(target.path, target.resolvedFrom);
         }
         const url = this.#targetToPath(target);
         const requestUrl = `${this.#config.baseUrl}${url}`;
@@ -316,8 +374,9 @@ export class ObsidianService {
         });
         if (res.status === 404)
             return null;
-        if (!res.ok)
-            await this.#throwForStatus(res, url, ctx, { requestedUrl: requestUrl });
+        if (!res.ok) {
+            await this.#throwForStatus(res, url, ctx, { method: 'HEAD', requestedUrl: requestUrl });
+        }
         this.#assertNotDirectory(res, url);
         return parseContentLength(res, url);
     }
@@ -346,18 +405,32 @@ export class ObsidianService {
                 url = `/vault/${encodeVaultPath(normalized)}/`;
         }
         /**
-         * Gate the directory itself when it's non-empty — root listings always
-         * pass so users can navigate into their scope. Children aren't filtered
-         * here; the per-file read gate on `getNoteContent` etc. catches access to
-         * out-of-scope individual notes.
+         * The root and folders on the way to the read scope list so a nested scope
+         * can be browsed to; any other out-of-scope folder is refused before the
+         * upstream call. Entries are filtered here rather than in callers, so every
+         * consumer of a listing — the `obsidian_list_notes` walk and the
+         * case-fallback probe alike — sees only readable entries and ancestors.
          */
         if (normalized) {
-            this.#policy.assertReadable(normalized);
+            this.#policy.assertListable(normalized);
         }
         const res = await this.#request(ctx, url, { method: 'GET', listRead: true });
-        return (await res.json());
+        const listing = (await res.json());
+        if (!this.#policy.restrictsReads)
+            return listing;
+        return { files: this.#policy.filterListing(normalized, listing.files) };
     }
+    /**
+     * Vault tags with usage counts, hierarchical parents included. Unscoped, the
+     * plugin's `/tags/` with its occurrence counts. That payload carries no
+     * per-note attribution, so under OBSIDIAN_READ_PATHS the tags are read from
+     * the readable notes' contexts instead (one upstream search, no bodies), and
+     * each one counts the readable notes carrying it or a tag nested under it.
+     */
     async listTags(ctx) {
+        if (this.#policy.restrictsReads) {
+            return countTagsPerNote(await this.#readableNoteContexts(ctx));
+        }
         const res = await this.#request(ctx, '/tags/', { method: 'GET' });
         const body = (await res.json());
         return body.tags ?? [];
@@ -409,13 +482,140 @@ export class ObsidianService {
             matches: mergeIntoLocations(h.matches.map((m) => contextRelativeSpan(m, h.filename, contextLength, tokens)), tokens.length, contextLength).map(({ context, match }) => ({ context, match })),
         }));
     }
+    /**
+     * JSONLogic search. Unscoped, the tree goes to the plugin unchanged. Under
+     * OBSIDIAN_READ_PATHS the plugin would evaluate it against every note in
+     * the vault, so the tree stays here instead: the readable notes' contexts
+     * are fetched and the tree is evaluated over those alone
+     * (`createJsonLogicEvaluation`), the way the plugin evaluates it. No hit,
+     * result, or error then reads a note outside the read scope; which note a
+     * link resolves to is still Obsidian's vault-wide resolution, so `links`,
+     * `backlinks`, and `unresolvedLinks` can change when a note outside the
+     * scope is created or removed.
+     *
+     * The plugin hands a tree note bodies only when its JSON holds the string
+     * `"content"` (`readsContent`); such a tree gets them here too, fetched
+     * and evaluated in batches of at most `CONTENT_BATCH_BYTES` so a broad
+     * scope never holds every readable body at once.
+     */
     async searchJsonLogic(ctx, logic) {
-        const res = await this.#request(ctx, '/search/', {
+        if (this.#policy.restrictsReads) {
+            assertTreeDepth(logic);
+            const evaluation = createJsonLogicEvaluation(logic, { signal: ctx.signal });
+            const notes = await this.#readableNoteContexts(ctx);
+            if (!readsContent(logic))
+                return evaluation.evaluate(notes);
+            const hits = [];
+            for (const batch of contentBatches(notes)) {
+                const bodies = await this.#noteBodies(ctx, batch);
+                const withBodies = batch.map((note) => ({ ...note, content: bodies.get(note.path) ?? '' }));
+                hits.push(...(await evaluation.evaluate(withBodies)));
+            }
+            return hits;
+        }
+        const res = await this.#postJsonLogic(ctx, logic);
+        return (await res.json());
+    }
+    /**
+     * A JSONLogic search for a caller paging through its hits `pageSize` at a
+     * time. Unscoped, it is `searchJsonLogic`. Under OBSIDIAN_READ_PATHS a call
+     * without `walk` evaluates fresh and, when the hits run past one page,
+     * stores the full ordered hit list under a new walk id, returned as `walk`;
+     * a call naming that id with the same tree is served from the stored list
+     * without evaluating. The store belongs to this service, whose read scope
+     * is fixed at construction, so a list is only read under the scope that
+     * produced it. Anything else — an expired, evicted, or unknown id, or a
+     * different tree — evaluates fresh, and a call cancelled before it answers
+     * stores nothing.
+     */
+    async pageJsonLogic(ctx, logic, walk, pageSize) {
+        if (!this.#policy.restrictsReads)
+            return { hits: await this.searchJsonLogic(ctx, logic) };
+        // Before serializing it: a tree deep enough overflows `JSON.stringify`'s stack under Bun.
+        assertTreeDepth(logic);
+        const tree = JSON.stringify(logic);
+        const stored = walk === undefined ? undefined : this.#walks.get(walk);
+        if (walk !== undefined && stored?.tree === tree && stored.expiresAt > Date.now()) {
+            // Re-inserted so the map stays in last-read order.
+            this.#walks.delete(walk);
+            this.#walks.set(walk, { ...stored, expiresAt: Date.now() + WALK_TTL_MS });
+            return { hits: stored.hits, walk };
+        }
+        const hits = await this.searchJsonLogic(ctx, logic);
+        const id = hits.length > pageSize && !ctx.signal.aborted ? this.#storeWalk(tree, hits) : undefined;
+        return id === undefined ? { hits } : { hits, walk: id };
+    }
+    /**
+     * Store a walk's hits under a fresh id, first dropping expired walks and,
+     * while the store would pass {@link WALK_STORE_CHARS}, the least recently
+     * read. A walk larger than the whole store is not kept.
+     */
+    #storeWalk(tree, hits) {
+        const chars = walkChars(tree, hits, WALK_STORE_CHARS);
+        if (chars > WALK_STORE_CHARS)
+            return;
+        const now = Date.now();
+        // Every walk lives WALK_TTL_MS past its last read, so expired walks lead the last-read order.
+        for (const [id, old] of this.#walks) {
+            if (old.expiresAt > now && this.#walkChars + chars <= WALK_STORE_CHARS)
+                break;
+            this.#walks.delete(id);
+            this.#walkChars -= old.chars;
+        }
+        const id = crypto.randomUUID();
+        this.#walks.set(id, { tree, hits, chars, expiresAt: now + WALK_TTL_MS });
+        this.#walkChars += chars;
+        return id;
+    }
+    /** One upstream JSONLogic search: `tree` posted to `/search/`. */
+    #postJsonLogic(ctx, tree) {
+        return this.#request(ctx, '/search/', {
             method: 'POST',
             headers: { 'Content-Type': JSONLOGIC_CT },
-            body: JSON.stringify(logic),
+            body: JSON.stringify(tree),
         });
-        return (await res.json());
+    }
+    /**
+     * The readable notes' JSONLogic contexts, bodies left empty as the plugin
+     * leaves them, in vault order, from one upstream search whose tree is the
+     * server's own: a `regexp` guard on the path (`PathPolicy.readScopePattern`)
+     * narrows what the plugin returns, and `filterReadable` decides what is
+     * kept. Each context carries only the fields the plugin documents, its link
+     * fields reduced to readable entries.
+     */
+    async #readableNoteContexts(ctx) {
+        const guard = {
+            if: [{ regexp: [this.#policy.readScopePattern(), { var: 'path' }] }, { var: '' }, null],
+        };
+        const res = await this.#postJsonLogic(ctx, guard);
+        const hits = (await res.json());
+        return this.#policy.filterReadable(hits).map(({ filename, result }) => ({
+            tags: result.tags,
+            frontmatter: result.frontmatter,
+            stat: result.stat,
+            path: filename,
+            content: result.content,
+            links: result.links && this.#policy.keepReadable(result.links),
+            backlinks: result.backlinks && this.#policy.keepReadable(result.backlinks),
+            unresolvedLinks: result.unresolvedLinks && this.#policy.keepReadable(result.unresolvedLinks),
+        }));
+    }
+    /**
+     * Bodies of `notes`, already-gated contexts, by path, from one upstream
+     * search for exactly those paths. A body for any other path is dropped; an
+     * empty body is absent, as the plugin's search drops a falsy result.
+     */
+    async #noteBodies(ctx, notes) {
+        const paths = notes.map((note) => note.path);
+        const guard = { if: [{ in: [{ var: 'path' }, paths] }, { var: 'content' }, null] };
+        const res = await this.#postJsonLogic(ctx, guard);
+        const wanted = new Set(paths);
+        const bodies = new Map();
+        for (const hit of (await res.json())) {
+            if (wanted.has(hit.filename))
+                bodies.set(hit.filename, hit.result);
+        }
+        return bodies;
     }
     /**
      * One-shot startup probe for the Omnisearch plugin's HTTP endpoint. Returns
@@ -524,15 +724,15 @@ export class ObsidianService {
      */
     async #gateAsWrite(ctx, target) {
         if (target.type === 'path') {
-            this.#policy.assertWritable(target.path);
+            this.#policy.assertWritable(target.path, target.resolvedFrom);
             return target;
         }
         if (this.#policy.isUnrestricted) {
             return target;
         }
-        const note = await this.#rawGetNoteJson(ctx, target);
-        this.#policy.assertWritable(note.path);
-        return { type: 'path', path: note.path };
+        const pinned = this.pinTarget(target, (await this.#rawGetNoteJson(ctx, target)).path);
+        this.#policy.assertWritable(pinned.path, pinned.resolvedFrom);
+        return pinned;
     }
     /** Raw NoteJson fetch — bypasses path-policy. Used by gate helpers to learn the resolved path. */
     async #rawGetNoteJson(ctx, target) {
@@ -735,18 +935,19 @@ export class ObsidianService {
      * on the last repeat while a section read returns the first. A write to a
      * repeated path is rejected as ambiguous. The count comes from the plugin's
      * own parse (`#headingIndex`) wherever the plugin serves one, so the map the
-     * PATCH resolves against is also the one that counts its repeats.
+     * PATCH resolves against is also the one that counts its repeats. On 1.x the
+     * note read for that count comes back as `note`, for `v1HeadingBody`.
      */
     async #resolveHeadingTarget(ctx, target, instruction, format) {
         if (instruction.targetType !== 'heading')
-            return instruction.target;
-        const { headings, occurrences } = await this.#headingIndex(ctx, target, format);
+            return { target: instruction.target, note: undefined };
+        const { headings, occurrences, note } = await this.#headingIndex(ctx, target, format);
         const resolved = instruction.target.includes(HEADING_DELIMITER)
             ? instruction.target
             : this.#expandHeadingLeaf(target, instruction.target, headings);
         const repeats = occurrences.filter((p) => p === resolved);
         if (repeats.length <= 1)
-            return resolved;
+            return { target: resolved, note };
         const display = displayPath(this.#targetToPath(target));
         const named = resolved === instruction.target ? `'${resolved}'` : `'${instruction.target}' (${resolved})`;
         throw conflict(`Heading ${named} occurs ${repeats.length} times in ${display}, so a section write cannot tell which one to edit.`, {
@@ -770,7 +971,7 @@ export class ObsidianService {
      * top-level heading tokens. Plugin v4.x serves only the 1.x array, which
      * cannot count repeats, so there the note body is fetched and scanned
      * locally (`listHeadingPaths`), which finds headings with the same `marked`
-     * lexing the map does.
+     * lexing the map does. That note text comes back as `note`.
      *
      * Both lists run in note order, as `#rawGetDocumentMap` explains, so the
      * `candidates` an ambiguity error names, and the first one its hint offers,
@@ -782,7 +983,7 @@ export class ObsidianService {
             const map = await this.#fetchDocumentMap(ctx, url, format);
             const { content } = await this.#rawGetNoteJson(ctx, target);
             const occurrences = listHeadingPaths(content);
-            return { headings: inNoteOrder(map.headings, occurrences), occurrences };
+            return { headings: inNoteOrder(map.headings, occurrences), note: content, occurrences };
         }
         const map = await this.#fetchDocumentMap(ctx, url, format);
         const flat = flattenHeadingTree(map.headings);
@@ -905,6 +1106,7 @@ export class ObsidianService {
             });
             if (!res.ok) {
                 await this.#throwForStatus(res, pathAndQuery, ctx, {
+                    method: init.method,
                     listRead: init.listRead,
                     requestedUrl: url,
                 });
@@ -1069,7 +1271,10 @@ export class ObsidianService {
      * malformed `OBSIDIAN_BASE_URL` is otherwise invisible behind a clean-looking
      * 404 (issue #122).
      *
-     * Issues #104, #116, and #122.
+     * `opts.method` is classification input only: the same upstream status and
+     * wording mean different things on a whole-file write than elsewhere.
+     *
+     * Issues #104, #116, #122, and #159.
      */
     async #throwForStatus(res, path, ctx, opts) {
         const text = await this.#readBodySafe(res);
@@ -1193,6 +1398,25 @@ export class ObsidianService {
                 if (res.status === 409 && /\balready contains the content\b/i.test(upstreamMsg)) {
                     throw contentPreexists();
                 }
+                /**
+                 * A whole-file `PUT` or `POST` creates the note through Obsidian's
+                 * `Vault.create` whenever the vault index, which is case-sensitive,
+                 * holds no file under that exact name — and `Vault.create` throws
+                 * "File already exists." when the disk does. On a case-insensitive
+                 * filesystem that is a note whose name differs only in letter case;
+                 * a file Obsidian does not index (a dot-file) refuses the same way.
+                 * The plugin relays it as a 500 whose message ends in that sentence
+                 * on a line of its own; the phrase inside other text (a filesystem
+                 * `EEXIST` naming another path) is a different failure. A `Conflict`
+                 * keeps it out of the retry loop: the next attempt meets the same
+                 * file. The tools name the existing note from the folder listing.
+                 */
+                if (res.status === 500 &&
+                    (opts.method === 'PUT' || opts.method === 'POST') &&
+                    path.startsWith('/vault/') &&
+                    /(?:^|\n)[ \t]*file already exists\.?\s*$/i.test(upstreamMsg)) {
+                    throw conflict(`Obsidian refused to create ${display}: a file already exists on disk at that path under different letter case, or one Obsidian does not index.`, data('case_variant_exists'), { cause });
+                }
                 /**
                  * Unhandled 4xx and all 5xx. `httpStatusToErrorCode` supplies the same
                  * canonical mapping `httpErrorFromResponse` would (the whole 5xx range
@@ -1230,6 +1454,30 @@ export class ObsidianService {
         }
     }
 }
+/**
+ * Count, per tag, the notes carrying it or a tag nested under it. Each note's
+ * `tags` is the plugin's per-note tag list — strings, deduplicated, `#`
+ * stripped, not parent-expanded — so one note carrying `work/a` and `work/b`
+ * adds 1 to `work`, and an untagged note adds nothing. Tags come back in
+ * order of first appearance.
+ */
+function countTagsPerNote(notes) {
+    const counts = new Map();
+    for (const { tags } of notes) {
+        const noteTags = new Set();
+        for (const tag of tags) {
+            const parts = tag.split('/');
+            for (let depth = 1; depth <= parts.length; depth++) {
+                noteTags.add(parts.slice(0, depth).join('/'));
+            }
+        }
+        for (const name of noteTags) {
+            if (name)
+                counts.set(name, (counts.get(name) ?? 0) + 1);
+        }
+    }
+    return Array.from(counts, ([name, count]) => ({ name, count }));
+}
 /**
  * Encode a vault-relative path for the URL. Splits on `/` and `\` (so
  * Windows-style separators are honored), URL-encodes each segment, and