@vrtmrz/livesync-commonlib 0.1.43 → 0.1.44

package/README.md

@@ -122,7 +122,9 @@ The focused Setup URI entry offers an Ephemeral mode bound to the current fixed
 
 ## Database diagnostics
 
-The focused `/diagnostics` entry provides read-only Usage and integrity reports, with original names or temporary pseudonyms selected by the host for each run. Integrity inspection covers normal-file Metadata, current conflict branches, and content comparisons for suspect groups in the local database and CouchDB. See [Database diagnostics](docs/database-diagnostics.md) for coverage, cancellation, and privacy boundaries.
+The focused `/diagnostics` entry provides read-only Usage and integrity reports, with original names or temporary pseudonyms selected by the host for each run. Integrity inspection covers normal-file Metadata, current conflict branches, and content comparisons for suspect groups in the local database and, by default, CouchDB; the host can exclude the remote source for one run. See [Database diagnostics](docs/database-diagnostics.md) for coverage, progress, cancellation, pseudonym lookup, and privacy boundaries.
+
+Integrity Markdown places a compact state summary and review index before all findings, while retaining each observation and its follow-up references. This formatting does not change the projected JSON data or schema; see [the Markdown field guide](docs/database-diagnostics.md#compact-integrity-markdown-report) for the meaning and limits of its review index.
 
 ```typescript
 import {
@@ -130,17 +132,33 @@ import {
     createDiagnosticNameMapper,
     createLocalDiagnosticSource,
     formatUsageTSV,
+    parseDiagnosticPathToken,
     projectUsageReport,
 } from '@vrtmrz/livesync-commonlib/diagnostics';
 
 const result = await analyseDatabaseUsage({ source: createLocalDiagnosticSource(localPouchDB) });
-const report = projectUsageReport(result, createDiagnosticNameMapper('pseudonym'));
+const mapper = createDiagnosticNameMapper('pseudonym');
+const report = projectUsageReport(result, mapper);
 if (report.status === 'complete') {
     const tsv = formatUsageTSV(report);
     // Present the report through the host's own UI or output stream.
 }
 ```
 
+Path pseudonyms include the report salt. A consumer can parse that token and supply its salt to a new mapper for a targeted follow-up against exact local Metadata paths:
+
+```typescript
+const pathToken = report.rows[0]?.path;
+const parsed = pathToken === undefined ? undefined : parseDiagnosticPathToken(pathToken);
+if (parsed) {
+    const followUpMapper = createDiagnosticNameMapper('pseudonym', parsed.salt);
+    const candidateToken = followUpMapper.path(storedVaultRelativePath);
+    // Compare this token with the path pseudonym on this device.
+}
+```
+
+The parser accepts only complete path tokens; it does not reverse them to recover a path. The salt is public, so a guessed path can be checked. Older ordinal pseudonyms have no corresponding lookup.
+
 ## Chunk ID calculation
 
 The `/hashing` entry exports `HashManager` and its `HashManagerCoreOptions` type. It uses the same implementation as database writes, including legacy algorithms and independent ID keys. Hosts supply their settings service and await `initialise()` before calling `computeHash(piece)`.

package/dist/diagnostics/couchdb.js

@@ -6,6 +6,8 @@ import { decompressDoc } from "../pouchdb/compress.js";
 import { AuthorizationHeaderGenerator, generateCredentialObject } from "../replication/httplib.js";
 import { base64ToArrayBuffer } from "../string_and_binary/convert.js";
 import { DiagnosticReadError } from "./types.js";
+const MAX_BULK_DOCUMENTS = 64;
+const MAX_BULK_URL_LENGTH = 6e3;
 function createCouchDBDiagnosticSource({
   settings: originalSettings,
   fetch,
@@ -30,13 +32,16 @@ function createCouchDBDiagnosticSource({
   const checkCancelled = () => {
     if (controller.signal.aborted) throw new DOMException("Diagnostic cancelled", "AbortError");
   };
+  const requestURL = (path, parameters = {}) => {
+    const requestURL2 = new URL(`${root}${path}`);
+    for (const [key, value] of Object.entries(parameters)) requestURL2.searchParams.set(key, value);
+    return requestURL2.toString();
+  };
   const readJSON = async (path, parameters = {}) => {
     checkCancelled();
-    const requestURL = new URL(`${root}${path}`);
-    for (const [key, value] of Object.entries(parameters)) requestURL.searchParams.set(key, value);
     headers.set("authorization", await auth.getAuthorizationHeader(credentials));
     checkCancelled();
-    const response = await fetch(requestURL.toString(), {
+    const response = await fetch(requestURL(path, parameters), {
       method: "GET",
       headers,
       cache: "no-store",
@@ -73,10 +78,20 @@ function createCouchDBDiagnosticSource({
     () => {
     }
   ).outgoing : async (doc) => doc;
-  return {
+  const decode = async (id, value) => {
+    if (!value || typeof value !== "object" || !("_id" in value) || value._id !== id || !("_rev" in value) || typeof value._rev !== "string") {
+      throw new DiagnosticReadError("document-unreadable");
+    }
+    const decoded = await decompressDoc(await decrypt(value));
+    if ("e_" in decoded && decoded.e_ === true || "path" in decoded && typeof decoded.path === "string" && (isEncryptedMeta(decoded) || isObfuscatedEntry(decoded) && isPathProbablyObfuscated(decoded.path)))
+      throw new DiagnosticReadError("document-unreadable");
+    checkCancelled();
+    return decoded;
+  };
+  const source = {
     async info() {
       const info = await readJSON("");
-      return { update_seq: info.update_seq };
+      return { update_seq: info.update_seq, doc_count: info.doc_count };
     },
     async *enumerateIds() {
       let previous;
@@ -106,16 +121,73 @@ function createCouchDBDiagnosticSource({
       if (options.conflicts) parameters.conflicts = "true";
       if (options.revs) parameters.revs = "true";
       if (options.revs_info) parameters.revs_info = "true";
-      const raw = await readJSON(`/${encodeURIComponent(id)}`, parameters);
-      if (raw._id !== id || typeof raw._rev !== "string") {
-        throw new DiagnosticReadError("document-unreadable");
-      }
-      const decoded = await decompressDoc(await decrypt(raw));
-      if ("e_" in decoded && decoded.e_ === true || "path" in decoded && typeof decoded.path === "string" && (isEncryptedMeta(decoded) || isObfuscatedEntry(decoded) && isPathProbablyObfuscated(decoded.path))) {
-        throw new DiagnosticReadError("document-unreadable");
+      return await decode(id, await readJSON(`/${encodeURIComponent(id)}`, parameters));
+    },
+    async getMany(ids, options = {}) {
+      const result = [];
+      const parameters = (keys) => ({
+        keys: JSON.stringify(keys),
+        include_docs: "true",
+        ...options.conflicts ? { conflicts: "true" } : {}
+      });
+      const readBatch = async (keys) => {
+        if (!keys.length) return;
+        let rows;
+        try {
+          const page = await readJSON("/_all_docs", parameters(keys));
+          if (!Array.isArray(page.rows)) throw new DiagnosticReadError("document-unreadable");
+          rows = page.rows;
+        } catch {
+          checkCancelled();
+          result.push(...keys.map((id) => ({ id, error: new DiagnosticReadError("document-unreadable") })));
+          return;
+        }
+        for (let offset = 0; offset < keys.length; offset += 4) {
+          checkCancelled();
+          const decoded = await Promise.allSettled(
+            keys.slice(offset, offset + 4).map(async (id, index) => {
+              try {
+                const row = rows[offset + index];
+                if (!row || row.key !== id) throw new DiagnosticReadError("document-unreadable");
+                if (row.error === "not_found" || row.value?.deleted)
+                  throw new DiagnosticReadError("document-unreadable", true);
+                if (row.error || row.id !== id) throw new DiagnosticReadError("document-unreadable");
+                return { id, document: await decode(id, row.doc) };
+              } catch (error) {
+                checkCancelled();
+                return {
+                  id,
+                  error: error instanceof DiagnosticReadError ? error : new DiagnosticReadError("document-unreadable")
+                };
+              }
+            })
+          );
+          checkCancelled();
+          for (const outcome of decoded) {
+            if (outcome.status === "rejected") throw outcome.reason;
+            result.push(outcome.value);
+          }
+        }
+      };
+      let pending = [];
+      for (const id of ids) {
+        checkCancelled();
+        if (pending.length >= MAX_BULK_DOCUMENTS || requestURL("/_all_docs", parameters([...pending, id])).length > MAX_BULK_URL_LENGTH) {
+          await readBatch(pending);
+          pending = [];
+        }
+        if (requestURL("/_all_docs", parameters([id])).length > MAX_BULK_URL_LENGTH) {
+          try {
+            result.push({ id, document: await source.get(id, options) });
+          } catch (error) {
+            checkCancelled();
+            result.push({ id, error });
+          }
+        } else pending.push(id);
       }
+      await readBatch(pending);
       checkCancelled();
-      return decoded;
+      return result;
     },
     close() {
       signal?.removeEventListener("abort", abort);
@@ -123,6 +195,7 @@ function createCouchDBDiagnosticSource({
       return Promise.resolve();
     }
   };
+  return source;
 }
 export {
   createCouchDBDiagnosticSource

package/dist/diagnostics/index.d.ts

@@ -4,7 +4,7 @@ export { analyseDatabaseIntegrity } from "./integrity.js";
 export { createLocalDiagnosticSource } from "./local.js";
 export { createCouchDBDiagnosticSource } from "./couchdb.js";
 export type { CouchDBDiagnosticSourceOptions } from "./couchdb.js";
-export { createDiagnosticNameMapper, projectIntegrityReport, projectUsageReport, formatDiagnosticJSON, formatIntegrityMarkdown, formatUsageTSV, } from "./reports.js";
+export { createDiagnosticNameMapper, parseDiagnosticPathToken, projectIntegrityReport, projectUsageReport, formatDiagnosticJSON, formatIntegrityMarkdown, formatUsageTSV, } from "./reports.js";
 export type { DiagnosticNameMapper, DiagnosticReportVersions, ProjectedDiagnosticReport, ProjectedDatabaseIntegrityReport, ProjectedDatabaseUsageReport, } from "./reports.js";
 export { DiagnosticReadError } from "./types.js";
-export type { DiagnosticStatus, DiagnosticNameMode, DiagnosticSourceName, DiagnosticReason, DiagnosticReadOptions, DiagnosticDatabaseSource, DiagnosticError, DiagnosticContent, DiagnosticCoverage, DiagnosticObservation, DiagnosticIdentitySettings, DatabaseIntegrityResult, DatabaseIntegrityOptions, } from "./types.js";
+export type { DiagnosticStatus, DiagnosticNameMode, DiagnosticSourceName, DiagnosticReason, DiagnosticReadOptions, DiagnosticDocumentReadResult, DiagnosticDatabaseSource, DiagnosticError, DiagnosticContent, DiagnosticCoverage, DiagnosticObservation, DiagnosticPathEquivalenceGroup, DiagnosticIdentitySettings, DatabaseIntegrityResult, DatabaseIntegrityOptions, DatabaseIntegrityProgress, DatabaseIntegrityLog, } from "./types.js";

package/dist/diagnostics/index.js

@@ -4,6 +4,7 @@ import { createLocalDiagnosticSource } from "./local.js";
 import { createCouchDBDiagnosticSource } from "./couchdb.js";
 import {
   createDiagnosticNameMapper,
+  parseDiagnosticPathToken,
   projectIntegrityReport,
   projectUsageReport,
   formatDiagnosticJSON,
@@ -21,6 +22,7 @@ export {
   formatDiagnosticJSON,
   formatIntegrityMarkdown,
   formatUsageTSV,
+  parseDiagnosticPathToken,
   projectIntegrityReport,
   projectUsageReport
 };