@vrtmrz/livesync-commonlib 0.1.4 → 0.1.5

package/dist/common/models/tweak.definition.d.ts

@@ -190,4 +190,28 @@ export declare const TweakValuesTemplate: {
 };
 export type TweakValues = Partial<typeof TweakValuesTemplate>;
 export declare const DEVICE_ID_PREFERRED = "PREFERRED";
+export declare const RemotePreferredTweakStatuses: {
+    readonly AVAILABLE: "available";
+    readonly NOT_CONFIGURED: "not-configured";
+    readonly UNAVAILABLE: "unavailable";
+    readonly UNSUPPORTED: "unsupported";
+};
+export type RemotePreferredTweakStatus = (typeof RemotePreferredTweakStatuses)[keyof typeof RemotePreferredTweakStatuses];
+export declare const RemotePreferredTweakNotConfiguredReasons: {
+    readonly MILESTONE_MISSING: "milestone-missing";
+    readonly PREFERRED_VALUES_MISSING: "preferred-values-missing";
+};
+export type RemotePreferredTweakNotConfiguredReason = (typeof RemotePreferredTweakNotConfiguredReasons)[keyof typeof RemotePreferredTweakNotConfiguredReasons];
+export type RemotePreferredTweakResult = {
+    status: typeof RemotePreferredTweakStatuses.AVAILABLE;
+    values: TweakValues;
+} | {
+    status: typeof RemotePreferredTweakStatuses.NOT_CONFIGURED;
+    reason: RemotePreferredTweakNotConfiguredReason;
+} | {
+    status: typeof RemotePreferredTweakStatuses.UNAVAILABLE;
+    error: unknown;
+} | {
+    status: typeof RemotePreferredTweakStatuses.UNSUPPORTED;
+};
 export {};

package/dist/common/models/tweak.definition.js

@@ -60,11 +60,23 @@ const TweakValuesTemplate = {
   tweakModified: 0
 };
 const DEVICE_ID_PREFERRED = "PREFERRED";
+const RemotePreferredTweakStatuses = {
+  AVAILABLE: "available",
+  NOT_CONFIGURED: "not-configured",
+  UNAVAILABLE: "unavailable",
+  UNSUPPORTED: "unsupported"
+};
+const RemotePreferredTweakNotConfiguredReasons = {
+  MILESTONE_MISSING: "milestone-missing",
+  PREFERRED_VALUES_MISSING: "preferred-values-missing"
+};
 export {
   CompatibleButLossyChanges,
   DEVICE_ID_PREFERRED,
   IncompatibleChanges,
   IncompatibleChangesInSpecificPattern,
+  RemotePreferredTweakNotConfiguredReasons,
+  RemotePreferredTweakStatuses,
   TweakValuesDefault,
   TweakValuesRecommendedTemplate,
   TweakValuesShouldMatchedTemplate,

package/dist/common/types.d.ts

@@ -21,7 +21,7 @@ import { SETTING_KEY_P2P_DEVICE_NAME, configURIBase, configURIBaseQR, SuffixData
 import { configurationNames, LEVEL_ADVANCED, LEVEL_POWER_USER, LEVEL_EDGE_CASE, type ConfigLevel, type ConfigurationItem, statusDisplay, confName, confDesc } from "./models/shared.definition.configNames.js";
 import type { CustomRegExpSource, CustomRegExpSourceList, ParsedCustomRegExp, Prettify } from "./models/shared.type.util.js";
 import { ProtocolVersions, type ProtocolVersion, DOCID_SYNC_PARAMETERS, DOCID_JOURNAL_SYNC_PARAMETERS, type SyncParameters, DEFAULT_SYNC_PARAMETERS } from "./models/sync.definition.js";
-import { TweakValuesShouldMatchedTemplate, IncompatibleChanges, CompatibleButLossyChanges, IncompatibleChangesInSpecificPattern, TweakValuesRecommendedTemplate, TweakValuesDefault, TweakValuesTemplate, type TweakValues, DEVICE_ID_PREFERRED } from "./models/tweak.definition.js";
+import { TweakValuesShouldMatchedTemplate, IncompatibleChanges, CompatibleButLossyChanges, IncompatibleChangesInSpecificPattern, TweakValuesRecommendedTemplate, TweakValuesDefault, TweakValuesTemplate, type TweakValues, DEVICE_ID_PREFERRED, RemotePreferredTweakStatuses, type RemotePreferredTweakStatus, RemotePreferredTweakNotConfiguredReasons, type RemotePreferredTweakNotConfiguredReason, type RemotePreferredTweakResult } from "./models/tweak.definition.js";
 import type { diff_result_leaf, dmp_result, diff_result, DIFF_CHECK_RESULT_AUTO, diff_check_result } from "./models/diff.definition.js";
 import { PREFIXMD_LOGFILE, PREFIXMD_LOGFILE_UC, FlagFilesOriginal, FlagFilesHumanReadable, FLAGMD_REDFLAG, FLAGMD_REDFLAG2, FLAGMD_REDFLAG2_HR, FLAGMD_REDFLAG3, FLAGMD_REDFLAG3_HR } from "./models/redflag.const.js";
 import { DatabaseConnectingStatuses, type DatabaseConnectingStatus } from "./models/shared.definition.js";
@@ -68,6 +68,11 @@ export { confDesc };
 export { TweakValuesTemplate };
 export type { TweakValues };
 export { DEVICE_ID_PREFERRED };
+export { RemotePreferredTweakStatuses };
+export type { RemotePreferredTweakStatus };
+export { RemotePreferredTweakNotConfiguredReasons };
+export type { RemotePreferredTweakNotConfiguredReason };
+export type { RemotePreferredTweakResult };
 export type { NodeKey };
 export type { DeviceInfo };
 export type { NodeData };

package/dist/common/types.js

@@ -110,7 +110,9 @@ import {
   TweakValuesRecommendedTemplate,
   TweakValuesDefault,
   TweakValuesTemplate,
-  DEVICE_ID_PREFERRED
+  DEVICE_ID_PREFERRED,
+  RemotePreferredTweakStatuses,
+  RemotePreferredTweakNotConfiguredReasons
 } from "./models/tweak.definition.js";
 import {
   PREFIXMD_LOGFILE,
@@ -197,6 +199,8 @@ export {
   REPLICATION_BUSY_TIMEOUT,
   RESULT_NOT_FOUND,
   RESULT_TIMED_OUT,
+  RemotePreferredTweakNotConfiguredReasons,
+  RemotePreferredTweakStatuses,
   RemoteTypes,
   SALT_OF_ID,
   SALT_OF_PASSPHRASE,

package/dist/replication/LiveSyncAbstractReplicator.d.ts

@@ -1,4 +1,4 @@
-import { type EntryDoc, type DatabaseConnectingStatus, type RemoteDBSettings, type EntryLeaf, type TweakValues, type NodeData } from "../common/types.js";
+import { type EntryDoc, type DatabaseConnectingStatus, type RemoteDBSettings, type EntryLeaf, type TweakValues, type RemotePreferredTweakResult, type NodeData } from "../common/types.js";
 import type { RequiredServices } from "../interfaces/ServiceModule.js";
 import type { TranslationParameters } from "../services/base/MessageTranslator.js";
 import type { CommonlibMessageKey } from "../services/base/CommonlibMessages.js";
@@ -60,7 +60,7 @@ export declare abstract class LiveSyncAbstractReplicator {
     abstract setPreferredRemoteTweakSettings(setting: RemoteDBSettings): Promise<void>;
     abstract fetchRemoteChunks(missingChunks: string[], showResult: boolean): Promise<false | EntryLeaf[]>;
     abstract getRemoteStatus(setting: RemoteDBSettings): Promise<false | RemoteDBStatus>;
-    abstract getRemotePreferredTweakValues(setting: RemoteDBSettings): Promise<false | TweakValues>;
+    abstract getRemotePreferredTweakValues(setting: RemoteDBSettings): Promise<RemotePreferredTweakResult>;
     abstract countCompromisedChunks(setting?: RemoteDBSettings): Promise<number | boolean>;
     abstract getConnectedDeviceList(setting?: RemoteDBSettings): Promise<false | {
         node_info: Record<string, NodeData>;

package/dist/replication/couchdb/LiveSyncReplicator.d.ts

@@ -1,4 +1,4 @@
-import { type EntryDoc, type RemoteDBSettings, type EntryLeaf, type TweakValues, type SyncParameters, type DatabaseEntry, type NodeData } from "../../common/types.js";
+import { type EntryDoc, type RemoteDBSettings, type EntryLeaf, type SyncParameters, type DatabaseEntry, type NodeData, type RemotePreferredTweakResult } from "../../common/types.js";
 import { LiveSyncAbstractReplicator, type LiveSyncReplicatorEnv, type RemoteDBStatus } from "../LiveSyncAbstractReplicator.js";
 import type { ServiceHub } from "../../services/ServiceHub.js";
 export interface LiveSyncCouchDBReplicatorEnv extends LiveSyncReplicatorEnv {
@@ -73,7 +73,7 @@ export declare class LiveSyncCouchDBReplicator extends LiveSyncAbstractReplicato
     tryConnectRemote(setting: RemoteDBSettings, showResult?: boolean): Promise<boolean>;
     resetRemoteTweakSettings(setting: RemoteDBSettings): Promise<void>;
     setPreferredRemoteTweakSettings(setting: RemoteDBSettings): Promise<void>;
-    getRemotePreferredTweakValues(setting: RemoteDBSettings): Promise<TweakValues | false>;
+    getRemotePreferredTweakValues(setting: RemoteDBSettings): Promise<RemotePreferredTweakResult>;
     compactRemote(setting: RemoteDBSettings): Promise<boolean>;
     getRemoteStatus(setting: RemoteDBSettings): Promise<RemoteDBStatus | false>;
     countCompromisedChunks(setting?: RemoteDBSettings): Promise<number | boolean>;

package/dist/replication/couchdb/LiveSyncReplicator.js

@@ -9,7 +9,9 @@ import {
   TweakValuesTemplate,
   DOCID_SYNC_PARAMETERS,
   DEFAULT_SYNC_PARAMETERS,
-  ProtocolVersions
+  ProtocolVersions,
+  RemotePreferredTweakNotConfiguredReasons,
+  RemotePreferredTweakStatuses
 } from "../../common/types.js";
 import {
   resolveWithIgnoreKnownError,
@@ -22,6 +24,7 @@ import {
 } from "../../common/utils.js";
 import { Logger } from "../../common/logger.js";
 import { checkRemoteVersion, countCompromisedChunks } from "../../pouchdb/negotiation.js";
+import { isErrorOfMissingDoc } from "../../pouchdb/utils_couchdb.js";
 import { preprocessOutgoing } from "../../pouchdb/encryption.js";
 import { ensureDatabaseIsCompatible } from "../../pouchdb/LiveSyncDBFunctions.js";
 import {
@@ -1050,23 +1053,73 @@ ${sendingDocs}/(${sentDocsCount} done)`,
   }
   async getRemotePreferredTweakValues(setting) {
     const uri = setting.couchDB_URI.replace(/\/+$/, "") + (setting.couchDB_DBNAME == "" ? "" : "/" + setting.couchDB_DBNAME);
-    const dbRet = await this.connectRemoteCouchDBWithSetting(setting, this.isMobile(), true);
+    let dbRet;
+    try {
+      dbRet = await this.connectRemoteCouchDBWithSetting(setting, this.isMobile(), true);
+    } catch (ex) {
+      Logger(`Could not connect to the remote database`, LOG_LEVEL_NOTICE);
+      Logger(ex, LOG_LEVEL_VERBOSE);
+      return {
+        status: RemotePreferredTweakStatuses.UNAVAILABLE,
+        error: ex
+      };
+    }
     if (typeof dbRet === "string") {
       Logger(this.translate("liveSyncReplicator.couldNotConnectToURI", { uri, dbRet }), LOG_LEVEL_NOTICE);
-      return false;
+      return {
+        status: RemotePreferredTweakStatuses.UNAVAILABLE,
+        error: new Error(dbRet)
+      };
     }
-    if (!await checkRemoteVersion(dbRet.db, this.migrate.bind(this), VER)) {
-      Logger(this.translate("liveSyncReplicator.remoteDbCorrupted"), LOG_LEVEL_NOTICE);
-      return false;
+    try {
+      if (!await checkRemoteVersion(dbRet.db, this.migrate.bind(this), VER)) {
+        const error = new Error("The remote database version is not compatible");
+        Logger(this.translate("liveSyncReplicator.remoteDbCorrupted"), LOG_LEVEL_NOTICE);
+        return {
+          status: RemotePreferredTweakStatuses.UNAVAILABLE,
+          error
+        };
+      }
+    } catch (ex) {
+      Logger(`Could not check the remote database version`, LOG_LEVEL_NOTICE);
+      Logger(ex, LOG_LEVEL_VERBOSE);
+      return {
+        status: RemotePreferredTweakStatuses.UNAVAILABLE,
+        error: ex
+      };
     }
     try {
       const remoteMilestone = await dbRet.db.get(MILESTONE_DOCID);
-      if (!remoteMilestone) throw new Error("Remote milestone not found");
-      return remoteMilestone?.tweak_values?.[DEVICE_ID_PREFERRED] || false;
+      if (!remoteMilestone) {
+        return {
+          status: RemotePreferredTweakStatuses.NOT_CONFIGURED,
+          reason: RemotePreferredTweakNotConfiguredReasons.MILESTONE_MISSING
+        };
+      }
+      const preferred = remoteMilestone.tweak_values?.[DEVICE_ID_PREFERRED];
+      if (!preferred) {
+        return {
+          status: RemotePreferredTweakStatuses.NOT_CONFIGURED,
+          reason: RemotePreferredTweakNotConfiguredReasons.PREFERRED_VALUES_MISSING
+        };
+      }
+      return {
+        status: RemotePreferredTweakStatuses.AVAILABLE,
+        values: preferred
+      };
     } catch (ex) {
+      if (isErrorOfMissingDoc(ex)) {
+        return {
+          status: RemotePreferredTweakStatuses.NOT_CONFIGURED,
+          reason: RemotePreferredTweakNotConfiguredReasons.MILESTONE_MISSING
+        };
+      }
       Logger(`Could not retrieve remote milestone`, LOG_LEVEL_NOTICE);
       Logger(ex, LOG_LEVEL_VERBOSE);
-      return false;
+      return {
+        status: RemotePreferredTweakStatuses.UNAVAILABLE,
+        error: ex
+      };
     }
   }
   async compactRemote(setting) {

package/dist/replication/journal/JournalSyncCore.d.ts

@@ -3,7 +3,7 @@ import type { ReplicationCallback, ReplicationStat } from "../LiveSyncAbstractRe
 import { type SimpleStore } from "../../common/utils.js";
 import { type CheckPointInfo } from "./JournalSyncTypes.js";
 import type { LiveSyncJournalReplicatorEnv } from "./LiveSyncJournalReplicatorEnv.js";
-import type { IJournalStorage } from "./objectstore/JournalStorageAdapter.js";
+import { type IJournalStorage, type JournalStorageReadResult } from "./objectstore/JournalStorageAdapter.js";
 type ProcessingEntry = PouchDB.Core.PutDocument<EntryDoc> & PouchDB.Core.GetMeta;
 export declare class JournalSyncCore {
     _settings: BucketSyncSetting;
@@ -22,6 +22,7 @@ export declare class JournalSyncCore {
     getHash(settings: BucketSyncSetting): string;
     constructor(settings: BucketSyncSetting, store: SimpleStore<CheckPointInfo>, env: LiveSyncJournalReplicatorEnv, storage: IJournalStorage);
     downloadJson<T>(key: string): Promise<T | false>;
+    downloadJsonWithResult<T>(key: string): Promise<JournalStorageReadResult<T>>;
     uploadJson<T>(key: string, body: T): Promise<boolean>;
     applyNewConfig(settings: BucketSyncSetting, store: SimpleStore<CheckPointInfo>, env: LiveSyncJournalReplicatorEnv): void;
     updateInfo(info: Partial<ReplicationStat>): void;

package/dist/replication/journal/JournalSyncCore.js

@@ -18,6 +18,9 @@ import {
 import { shareRunningResult } from "octagonal-wheels/concurrency/lock";
 import { wrappedDeflate, wrappedInflate } from "../../pouchdb/compress.js";
 import { CheckPointInfoDefault } from "./JournalSyncTypes.js";
+import {
+  JournalStorageReadStatuses
+} from "./objectstore/JournalStorageAdapter.js";
 import {
   clearHandlers,
   createSyncParamsHanderForServer,
@@ -116,6 +119,23 @@ class JournalSyncCore {
       return false;
     }
   }
+  async downloadJsonWithResult(key) {
+    const result = await this.storage.downloadWithResult(key, true);
+    if (result.status !== JournalStorageReadStatuses.AVAILABLE) return result;
+    try {
+      return {
+        status: JournalStorageReadStatuses.AVAILABLE,
+        value: JSON.parse(new TextDecoder().decode(result.value))
+      };
+    } catch (ex) {
+      Logger(`Could not parse downloaded json ${key}`);
+      Logger(ex, LOG_LEVEL_VERBOSE);
+      return {
+        status: JournalStorageReadStatuses.UNAVAILABLE,
+        error: ex
+      };
+    }
+  }
   async uploadJson(key, body) {
     try {
       const data = new TextEncoder().encode(JSON.stringify(body));

package/dist/replication/journal/LiveSyncJournalReplicator.d.ts

@@ -1,4 +1,4 @@
-import { type RemoteDBSettings, type EntryLeaf, type ChunkVersionRange, type TweakValues, type NodeData } from "../../common/types.js";
+import { type RemoteDBSettings, type EntryLeaf, type ChunkVersionRange, type NodeData, type RemotePreferredTweakResult } from "../../common/types.js";
 import { JournalSyncCore } from "./JournalSyncCore.js";
 import { LiveSyncAbstractReplicator, type RemoteDBStatus } from "../LiveSyncAbstractReplicator.js";
 import { type ENSURE_DB_RESULT } from "../../pouchdb/LiveSyncDBFunctions.js";
@@ -29,7 +29,7 @@ export declare class LiveSyncJournalReplicator extends LiveSyncAbstractReplicato
     tryConnectRemote(setting: RemoteDBSettings, showResult?: boolean): Promise<boolean>;
     resetRemoteTweakSettings(setting: RemoteDBSettings): Promise<void>;
     setPreferredRemoteTweakSettings(setting: RemoteDBSettings): Promise<void>;
-    getRemotePreferredTweakValues(setting: RemoteDBSettings): Promise<false | TweakValues>;
+    getRemotePreferredTweakValues(_setting: RemoteDBSettings): Promise<RemotePreferredTweakResult>;
     getRemoteStatus(setting: RemoteDBSettings): Promise<false | RemoteDBStatus>;
     countCompromisedChunks(): Promise<number>;
     getConnectedDeviceList(setting?: RemoteDBSettings): Promise<false | {

package/dist/replication/journal/LiveSyncJournalReplicator.js

@@ -2,7 +2,9 @@ import {
   LOG_LEVEL_NOTICE,
   LOG_LEVEL_VERBOSE,
   DEVICE_ID_PREFERRED,
-  TweakValuesTemplate
+  TweakValuesTemplate,
+  RemotePreferredTweakNotConfiguredReasons,
+  RemotePreferredTweakStatuses
 } from "../../common/types.js";
 import { Logger } from "../../common/logger.js";
 import { JournalSyncCore } from "./JournalSyncCore.js";
@@ -11,6 +13,7 @@ import { LiveSyncAbstractReplicator } from "../LiveSyncAbstractReplicator.js";
 import { ensureRemoteIsCompatible } from "../../pouchdb/LiveSyncDBFunctions.js";
 import { extractObject } from "../../common/utils.js";
 import { clearHandlers } from "../SyncParamsHandler.js";
+import { JournalStorageReadStatuses } from "./objectstore/JournalStorageAdapter.js";
 const MILSTONE_DOCID = "_00000000-milestone.json";
 const currentVersionRange = {
   min: 0,
@@ -256,18 +259,31 @@ ${ex.message}`, LOG_LEVEL_NOTICE);
       throw ex;
     }
   }
-  async getRemotePreferredTweakValues(setting) {
-    try {
-      const remoteMilestone = await this.client.downloadJson(MILSTONE_DOCID);
-      if (!remoteMilestone) {
-        throw new Error("Missing remote milestone");
-      }
-      return remoteMilestone?.tweak_values?.[DEVICE_ID_PREFERRED] || false;
-    } catch (ex) {
-      Logger(`Could not retrieve remote milestone`, LOG_LEVEL_NOTICE);
-      Logger(ex, LOG_LEVEL_VERBOSE);
-      return false;
+  async getRemotePreferredTweakValues(_setting) {
+    const result = await this.client.downloadJsonWithResult(MILSTONE_DOCID);
+    if (result.status === JournalStorageReadStatuses.NOT_FOUND) {
+      return {
+        status: RemotePreferredTweakStatuses.NOT_CONFIGURED,
+        reason: RemotePreferredTweakNotConfiguredReasons.MILESTONE_MISSING
+      };
+    }
+    if (result.status === JournalStorageReadStatuses.UNAVAILABLE) {
+      return {
+        status: RemotePreferredTweakStatuses.UNAVAILABLE,
+        error: result.error
+      };
     }
+    const preferred = result.value.tweak_values?.[DEVICE_ID_PREFERRED];
+    if (!preferred) {
+      return {
+        status: RemotePreferredTweakStatuses.NOT_CONFIGURED,
+        reason: RemotePreferredTweakNotConfiguredReasons.PREFERRED_VALUES_MISSING
+      };
+    }
+    return {
+      status: RemotePreferredTweakStatuses.AVAILABLE,
+      values: preferred
+    };
   }
   async getRemoteStatus(setting) {
     const testClient = new MinioStorageAdapter(setting, this.env);

package/dist/replication/journal/objectstore/JournalStorageAdapter.d.ts

@@ -1,8 +1,23 @@
 import type { RemoteDBStatus } from "../../LiveSyncAbstractReplicator.js";
 import type { BucketSyncSetting } from "../../../common/types.js";
+export declare const JournalStorageReadStatuses: {
+    readonly AVAILABLE: "available";
+    readonly NOT_FOUND: "not-found";
+    readonly UNAVAILABLE: "unavailable";
+};
+export type JournalStorageReadResult<T> = {
+    status: typeof JournalStorageReadStatuses.AVAILABLE;
+    value: T;
+} | {
+    status: typeof JournalStorageReadStatuses.NOT_FOUND;
+} | {
+    status: typeof JournalStorageReadStatuses.UNAVAILABLE;
+    error: unknown;
+};
 export interface IJournalStorage {
     upload(key: string, data: Uint8Array, mime: string): Promise<boolean>;
     download(key: string, ignoreCache?: boolean): Promise<Uint8Array | false>;
+    downloadWithResult(key: string, ignoreCache?: boolean): Promise<JournalStorageReadResult<Uint8Array>>;
     listFiles(from: string, limit?: number): Promise<string[]>;
     deleteFiles(keys: string[]): Promise<boolean>;
     isAvailable(): Promise<boolean>;

package/dist/replication/journal/objectstore/JournalStorageAdapter.js

@@ -0,0 +1,8 @@
+const JournalStorageReadStatuses = {
+  AVAILABLE: "available",
+  NOT_FOUND: "not-found",
+  UNAVAILABLE: "unavailable"
+};
+export {
+  JournalStorageReadStatuses
+};

package/dist/replication/journal/objectstore/MinioStorageAdapter.d.ts

@@ -1,7 +1,7 @@
 import { S3 } from "@aws-sdk/client-s3";
 import { type BucketSyncSetting } from "../../../common/types.js";
 import type { RemoteDBStatus } from "../../LiveSyncAbstractReplicator.js";
-import type { IJournalStorage } from "./JournalStorageAdapter.js";
+import { type IJournalStorage, type JournalStorageReadResult } from "./JournalStorageAdapter.js";
 import type { LiveSyncJournalReplicatorEnv } from "../LiveSyncJournalReplicatorEnv.js";
 export declare class MinioStorageAdapter implements IJournalStorage {
     _instance?: S3;
@@ -13,6 +13,7 @@ export declare class MinioStorageAdapter implements IJournalStorage {
     get customHeaders(): [string, string][];
     _getClient(): S3;
     upload(key: string, data: Uint8Array, mime: string): Promise<boolean>;
+    downloadWithResult(key: string, ignoreCache?: boolean): Promise<JournalStorageReadResult<Uint8Array>>;
     download(key: string, ignoreCache?: boolean): Promise<Uint8Array | false>;
     listFiles(from: string, limit?: number): Promise<string[]>;
     deleteFiles(keys: string[]): Promise<boolean>;

package/dist/replication/journal/objectstore/MinioStorageAdapter.js

@@ -11,6 +11,9 @@ import { ConfiguredRetryStrategy } from "@smithy/util-retry";
 import { promiseWithResolvers } from "octagonal-wheels/promises";
 import { LOG_LEVEL_NOTICE, LOG_LEVEL_VERBOSE } from "../../../common/types.js";
 import { Logger } from "../../../common/logger.js";
+import {
+  JournalStorageReadStatuses
+} from "./JournalStorageAdapter.js";
 import { parseHeaderValues } from "../../../common/utils.js";
 import { runWithTrackedPhysicalRequest } from "../../../services/lib/remoteActivity.js";
 class MinioStorageAdapter {
@@ -110,7 +113,7 @@ class MinioStorageAdapter {
     }
     return false;
   }
-  async download(key, ignoreCache = false) {
+  async downloadWithResult(key, ignoreCache = false) {
     const client = this._getClient();
     const cmd = new GetObjectCommand({
       Bucket: this._settings.bucket,
@@ -121,15 +124,31 @@ class MinioStorageAdapter {
       return await this.runTrackedRequest(async () => {
         const r = await client.send(cmd);
         if (r.Body) {
-          return new Uint8Array(await r.Body.transformToByteArray());
+          return {
+            status: JournalStorageReadStatuses.AVAILABLE,
+            value: new Uint8Array(await r.Body.transformToByteArray())
+          };
         }
-        return false;
+        return {
+          status: JournalStorageReadStatuses.UNAVAILABLE,
+          error: new Error(`The response body for ${key} was empty`)
+        };
       });
     } catch (ex) {
+      if (isMissingObjectError(ex)) {
+        return { status: JournalStorageReadStatuses.NOT_FOUND };
+      }
       Logger(`Could not download ${key}`);
       Logger(ex, LOG_LEVEL_VERBOSE);
+      return {
+        status: JournalStorageReadStatuses.UNAVAILABLE,
+        error: ex
+      };
     }
-    return false;
+  }
+  async download(key, ignoreCache = false) {
+    const result = await this.downloadWithResult(key, ignoreCache);
+    return result.status === JournalStorageReadStatuses.AVAILABLE ? result.value : false;
   }
   async listFiles(from, limit) {
     const client = this._getClient();
@@ -199,6 +218,12 @@ class MinioStorageAdapter {
     }
   }
 }
+function isMissingObjectError(error) {
+  if (!error || typeof error !== "object") return false;
+  const { name, Code, code } = error;
+  const errorCode = Code ?? code ?? name;
+  return errorCode === "NoSuchKey" || errorCode === "NotFound";
+}
 export {
   MinioStorageAdapter
 };

package/dist/replication/trystero/LiveSyncTrysteroReplicator.d.ts

@@ -1,4 +1,4 @@
-import { type RemoteDBSettings, type EntryLeaf, type TweakValues, type LOG_LEVEL, type NodeData } from "../../common/types.js";
+import { type RemoteDBSettings, type EntryLeaf, type RemotePreferredTweakResult, type LOG_LEVEL, type NodeData } from "../../common/types.js";
 import { LiveSyncAbstractReplicator, type LiveSyncReplicatorEnv, type RemoteDBStatus } from "../LiveSyncAbstractReplicator.js";
 import { TrysteroReplicator } from "./TrysteroReplicator.js";
 import { P2PHost, type AcceptanceDecision, type RevokeAcceptanceDecision } from "./TrysteroReplicatorP2PServer.js";
@@ -81,7 +81,7 @@ export declare class LiveSyncTrysteroReplicator extends LiveSyncAbstractReplicat
     setPreferredRemoteTweakSettings(_setting: RemoteDBSettings): Promise<void>;
     fetchRemoteChunks(_missingChunks: string[], _showResult: boolean): Promise<false | EntryLeaf[]>;
     getRemoteStatus(_setting: RemoteDBSettings): Promise<false | RemoteDBStatus>;
-    getRemotePreferredTweakValues(_setting: RemoteDBSettings): Promise<false | TweakValues>;
+    getRemotePreferredTweakValues(_setting: RemoteDBSettings): Promise<RemotePreferredTweakResult>;
     countCompromisedChunks(): Promise<number>;
     getConnectedDeviceList(_setting?: RemoteDBSettings): Promise<false | {
         node_info: Record<string, NodeData>;

package/dist/replication/trystero/LiveSyncTrysteroReplicator.js

@@ -1,5 +1,6 @@
 import { Logger } from "../../common/logger.js";
 import {
+  RemotePreferredTweakStatuses,
   LOG_LEVEL_NOTICE,
   LOG_LEVEL_INFO,
   LOG_LEVEL_VERBOSE,
@@ -369,7 +370,7 @@ class LiveSyncTrysteroReplicator extends LiveSyncAbstractReplicator {
       "Trying to get tweak values but P2P replication does not support to do this. This operation has been ignored",
       LOG_LEVEL_INFO
     );
-    return Promise.resolve(false);
+    return Promise.resolve({ status: RemotePreferredTweakStatuses.UNSUPPORTED });
   }
   countCompromisedChunks() {
     Logger("P2P Replicator cannot count compromised chunks", LOG_LEVEL_VERBOSE);

package/dist/services/base/IService.d.ts

@@ -1,6 +1,6 @@
 import type { FetchHttpHandler } from "@smithy/fetch-http-handler";
 import { type LOG_LEVEL } from "octagonal-wheels/common/logger";
-import type { AnyEntry, AUTO_MERGED, CouchDBCredentials, diff_result, DocumentID, EntryDoc, EntryHasPath, FileEventItem, FilePath, FilePathWithPrefix, LoadedEntry, MetaEntry, MISSING_OR_ERROR, ObsidianLiveSyncSettings, RemoteDBSettings, SettingsMigrationState, TweakValues, UXFileInfo, UXFileInfoStub } from "../../common/types.js";
+import type { AnyEntry, AUTO_MERGED, CouchDBCredentials, diff_result, DocumentID, EntryDoc, EntryHasPath, FileEventItem, FilePath, FilePathWithPrefix, LoadedEntry, MetaEntry, MISSING_OR_ERROR, ObsidianLiveSyncSettings, RemoteDBSettings, RemotePreferredTweakResult, SettingsMigrationState, TweakValues, UXFileInfo, UXFileInfoStub } from "../../common/types.js";
 import type { LiveSyncLocalDB } from "../../pouchdb/LiveSyncLocalDB.js";
 import type { LiveSyncAbstractReplicator } from "../../replication/LiveSyncAbstractReplicator.js";
 import type { SimpleStore } from "octagonal-wheels/databases/SimpleStoreBase";
@@ -221,7 +221,7 @@ export interface ISettingService {
     deleteSmallConfig(key: string): void;
 }
 export interface ITweakValueService {
-    fetchRemotePreferred(trialSetting: RemoteDBSettings): Promise<TweakValues | false>;
+    fetchRemotePreferred(trialSetting: RemoteDBSettings): Promise<RemotePreferredTweakResult>;
     checkAndAskResolvingMismatched(preferred: Partial<TweakValues>): Promise<[TweakValues | boolean, boolean]>;
     askResolvingMismatched(preferredSource: TweakValues): Promise<"OK" | "CHECKAGAIN" | "IGNORE">;
     checkAndAskUseRemoteConfiguration(settings: RemoteDBSettings): Promise<{

package/dist/services/base/TweakValueService.d.ts

@@ -1,4 +1,4 @@
-import type { RemoteDBSettings, TweakValues } from "../../common/types.js";
+import type { RemoteDBSettings, RemotePreferredTweakResult, TweakValues } from "../../common/types.js";
 import type { ITweakValueService } from "./IService.js";
 import { ServiceBase, type ServiceContext } from "./ServiceBase.js";
 /**
@@ -9,7 +9,7 @@ export declare abstract class TweakValueService<T extends ServiceContext = Servi
      * Fetch and trial the remote database settings to determine if they are preferred.
      * @param trialSetting The remote database settings to connect.
      */
-    abstract fetchRemotePreferred(trialSetting: RemoteDBSettings): Promise<TweakValues | false>;
+    abstract fetchRemotePreferred(trialSetting: RemoteDBSettings): Promise<RemotePreferredTweakResult>;
     /**
      * Check and ask the user to resolve any mismatched tweak values.
      * @param preferred The preferred tweak values to check against.

package/dist/services/implements/injectable/InjectableTweakValueService.d.ts

@@ -1,7 +1,7 @@
 import type { ServiceContext } from "../../base/ServiceBase.js";
 import { TweakValueService } from "../../base/TweakValueService.js";
 export declare class InjectableTweakValueService<T extends ServiceContext> extends TweakValueService<T> {
-    fetchRemotePreferred: import("../../lib/HandlerUtils.js").HandlerFunction<(trialSetting: import("../../../settings.js").RemoteDBSettings) => Promise<import("../../../common/types.js").TweakValues | false>, unknown>;
+    fetchRemotePreferred: import("../../lib/HandlerUtils.js").HandlerFunction<(trialSetting: import("../../../settings.js").RemoteDBSettings) => Promise<import("../../../common/types.js").RemotePreferredTweakResult>, unknown>;
     checkAndAskResolvingMismatched: import("../../lib/HandlerUtils.js").HandlerFunction<(preferred: Partial<import("../../../common/types.js").TweakValues>) => Promise<[import("../../../common/types.js").TweakValues | boolean, boolean]>, unknown>;
     askResolvingMismatched: import("../../lib/HandlerUtils.js").HandlerFunction<(preferredSource: import("../../../common/types.js").TweakValues) => Promise<"OK" | "CHECKAGAIN" | "IGNORE">, unknown>;
     checkAndAskUseRemoteConfiguration: import("../../lib/HandlerUtils.js").HandlerFunction<(settings: import("../../../settings.js").RemoteDBSettings) => Promise<{

package/docs/proven-in-use.md

@@ -20,6 +20,8 @@ Commonlib's chunk-reachability tests use real PouchDB revision trees. They verif
 
 Commonlib's injected CouchDB tests verify that a mixed remote chunk batch preserves available documents when another requested ID is absent. Its chunk-delivery tests separately verify that available chunks reach local storage and only absent IDs are marked unavailable. Self-hosted LiveSync supplies the real CouchDB connection and start-up composition, so device-specific replication timing remains downstream integration evidence rather than Commonlib unit coverage.
 
+Commonlib's remote-preference result contract distinguishes available synchronisation settings, a remote which has not stored those settings yet, a failed read, and a remote type which does not support central preferences. Focused CouchDB and Object Storage tests cover absent milestone data separately from transport failures, while Self-hosted LiveSync owns the initialisation choices, cancellation policy, and user-facing explanation.
+
 Most replication and storage services used by the plug-in still enter through explicit `compat/*` paths. Those imports prove that the published compatibility boundary supports the current migration; they are not examples of a finished high-level client API.
 
 The plug-in's manual onboarding and Remote Databases pane use the focused `/remote-configurations` entry to create opaque profile IDs, retain user-visible names, and select main and P2P remotes. Commonlib owns the in-memory profile result contract; Self-hosted LiveSync adds dialogue, Setup URI classification, Fetch or Rebuild scheduling, persistence, restart ordering, and real-Obsidian presentation checks.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vrtmrz/livesync-commonlib",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Shared data, storage, and replication primitives for Self-hosted LiveSync clients.",
   "type": "module",
   "license": "MIT",