@vrtmrz/livesync-commonlib 0.1.19-rc.0 → 0.1.20

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

@@ -0,0 +1,61 @@
+import type { LiveSyncReplicatorEnv } from "../LiveSyncAbstractReplicator.js";
+import { P2PRoomSession } from "./P2PRoomSession.js";
+import type { ReplicatorHostEnv } from "./types.js";
+import { type P2PConnectionProbeAdmissionResult, type P2PConnectionProbeSettings } from "./P2PConnectionProbeAdmission.js";
+type P2PRoomSessionFactory = (env: ReplicatorHostEnv) => P2PRoomSession;
+/** Session operations shared by the stable service and its compatibility facade. */
+export interface P2PRoomSessionAccess {
+    readonly currentSession: P2PRoomSession | undefined;
+    readonly isConnected: boolean;
+    cancelActiveTransfers(): void;
+    open(): Promise<void>;
+    close(): Promise<void>;
+}
+/** Persistent reasons for which the service keeps a P2P room available. */
+export type P2PPersistentRoomDemand = "explicit" | "automatic" | "rebuild-continuation";
+/**
+ * Owns the one published P2P room session used by a stable P2P service.
+ *
+ * Compatibility facades may observe and operate on the published session, but
+ * they do not own its construction, replacement, or retirement.
+ */
+export declare class P2PRoomSessionOwner implements P2PRoomSessionAccess {
+    private readonly env;
+    private readonly createSession;
+    private current?;
+    private lifecycleOperation;
+    private readonly persistentDemands;
+    private readonly finiteDemands;
+    private readonly automationCoordinator;
+    private activeBinding?;
+    constructor(env: LiveSyncReplicatorEnv, createSession?: P2PRoomSessionFactory);
+    get currentSession(): P2PRoomSession | undefined;
+    get isConnected(): boolean;
+    cancelActiveTransfers(): void;
+    /** Retire automatic baseline history owned by the previous app lifecycle. */
+    beginAutomationLifecycle(): void;
+    open(): Promise<void>;
+    /** Reconcile one long-lived reason for keeping the room available. */
+    setPersistentDemand(demand: P2PPersistentRoomDemand, active: boolean): Promise<void>;
+    /**
+     * Keep the room available only for the lifetime of one finite operation.
+     *
+     * The token is internal to the owner. Releasing it cannot close a room
+     * retained by another finite operation or by a persistent policy demand.
+     */
+    runWithFiniteDemand<T>(task: (session: P2PRoomSession) => T | PromiseLike<T>): Promise<T>;
+    /** Arbitrate a complete signalling probe on the room lifecycle queue. */
+    runConnectionProbe<T>(trialSettings: P2PConnectionProbeSettings, runOwnedTrial: () => Promise<T>): Promise<P2PConnectionProbeAdmissionResult<T>>;
+    private reconcileTransport;
+    close(): Promise<void>;
+    private hasRoomDemand;
+    private enqueueLifecycleOperation;
+    private closeTransport;
+    private bindingsMatch;
+    /** Capture immutable session inputs while keeping policy live. */
+    private getEffectiveBinding;
+    /** Apply policy which can change without retiring the room session. */
+    private reconcileCurrentSessionPolicy;
+    private buildSessionEnv;
+}
+export {};

package/dist/replication/trystero/P2PRoomSessionOwner.js

@@ -0,0 +1,249 @@
+import { Logger } from "../../common/logger.js";
+import {
+  LOG_LEVEL_NOTICE,
+  LOG_LEVEL_VERBOSE,
+  SETTING_KEY_P2P_DEVICE_NAME
+} from "../../common/types.js";
+import { P2PRoomSession } from "./P2PRoomSession.js";
+import { P2PAutomationCoordinator } from "./P2PAutomationCoordinator.js";
+import { PEER_REPLICATION_READINESS } from "../ReplicatorProvider.js";
+import { getP2PReplicatorConfigurationIdentity } from "./p2pReplicatorConfigurationIdentity.js";
+import {
+  ACTIVE_P2P_RELAY_BINDING_CONFLICT,
+  activeP2PRelayBindingCovers
+} from "./P2PConnectionProbeAdmission.js";
+class P2PRoomSessionOwner {
+  constructor(env, createSession = (sessionEnv) => new P2PRoomSession(sessionEnv)) {
+    this.env = env;
+    this.createSession = createSession;
+  }
+  env;
+  createSession;
+  current;
+  lifecycleOperation = Promise.resolve();
+  persistentDemands = /* @__PURE__ */ new Set();
+  finiteDemands = /* @__PURE__ */ new Set();
+  automationCoordinator = new P2PAutomationCoordinator();
+  activeBinding;
+  get currentSession() {
+    return this.current;
+  }
+  get isConnected() {
+    return this.current?.host.isServing ?? false;
+  }
+  cancelActiveTransfers() {
+    this.current?.cancelActiveTransfers();
+  }
+  /** Retire automatic baseline history owned by the previous app lifecycle. */
+  beginAutomationLifecycle() {
+    this.automationCoordinator.beginLifecycle();
+  }
+  async open() {
+    await this.setPersistentDemand("explicit", true);
+  }
+  /** Reconcile one long-lived reason for keeping the room available. */
+  async setPersistentDemand(demand, active) {
+    const enabled = this.env.services.setting.currentSettings().P2P_Enabled;
+    if (active && enabled) {
+      this.persistentDemands.add(demand);
+    } else {
+      this.persistentDemands.delete(demand);
+    }
+    if (active && !enabled) {
+      Logger(this.env.services.context.translate("P2P.NotEnabled"), LOG_LEVEL_NOTICE);
+    }
+    await this.reconcileTransport();
+  }
+  /**
+   * Keep the room available only for the lifetime of one finite operation.
+   *
+   * The token is internal to the owner. Releasing it cannot close a room
+   * retained by another finite operation or by a persistent policy demand.
+   */
+  async runWithFiniteDemand(task) {
+    if (!this.env.services.setting.currentSettings().P2P_Enabled) {
+      throw new Error("P2P is not enabled.");
+    }
+    const demand = /* @__PURE__ */ Symbol("p2p-finite-room-demand");
+    this.finiteDemands.add(demand);
+    try {
+      await this.reconcileTransport();
+      if (!this.finiteDemands.has(demand)) {
+        throw new Error("The P2P room demand was retired before the operation started.");
+      }
+      const session = this.current;
+      if (!session?.host.isServing) {
+        throw new Error("The P2P room could not be opened for the finite operation.");
+      }
+      return await task(session);
+    } finally {
+      if (this.finiteDemands.delete(demand)) {
+        await this.reconcileTransport();
+      }
+    }
+  }
+  /** Arbitrate a complete signalling probe on the room lifecycle queue. */
+  runConnectionProbe(trialSettings, runOwnedTrial) {
+    return this.enqueueLifecycleOperation(async () => {
+      const current = this.current;
+      const activeBinding = this.activeBinding;
+      if (current?.host.isServing && activeBinding) {
+        if (activeP2PRelayBindingCovers(activeBinding.settings, trialSettings)) {
+          return { status: "observed-active" };
+        }
+        return {
+          status: "blocked",
+          reason: ACTIVE_P2P_RELAY_BINDING_CONFLICT
+        };
+      }
+      if (current) {
+        await this.closeTransport();
+      }
+      return {
+        status: "trial",
+        result: await runOwnedTrial()
+      };
+    });
+  }
+  async reconcileTransport() {
+    await this.enqueueLifecycleOperation(async () => {
+      if (!this.env.services.setting.currentSettings().P2P_Enabled) {
+        this.persistentDemands.clear();
+        this.finiteDemands.clear();
+      }
+      if (!this.hasRoomDemand()) {
+        await this.closeTransport();
+        return;
+      }
+      const binding = this.getEffectiveBinding();
+      if (this.current?.host.isServing && this.bindingsMatch(this.activeBinding, binding)) {
+        this.reconcileCurrentSessionPolicy(this.current);
+        Logger("P2P replicator is already open.");
+        return;
+      }
+      if (this.current) {
+        await this.closeTransport();
+      }
+      let candidate;
+      try {
+        candidate = this.createSession(this.buildSessionEnv(binding));
+        await candidate.open();
+        if (!candidate.host.isServing) {
+          throw new Error("The P2P room did not start serving.");
+        }
+        const currentBinding = this.getEffectiveBinding();
+        if (!currentBinding.enabled || !this.hasRoomDemand() || !this.bindingsMatch(binding, currentBinding)) {
+          await candidate.retire();
+          return;
+        }
+        this.current = candidate;
+        this.activeBinding = binding;
+        this.reconcileCurrentSessionPolicy(candidate);
+      } catch (error) {
+        await candidate?.retire(error).catch((retirementError) => {
+          Logger(retirementError, LOG_LEVEL_VERBOSE);
+        });
+        Logger(error instanceof Error ? error.message : "Error while opening P2P connection", LOG_LEVEL_NOTICE);
+        Logger(error, LOG_LEVEL_VERBOSE);
+        this.current = void 0;
+        this.activeBinding = void 0;
+      }
+    });
+  }
+  async close() {
+    this.persistentDemands.clear();
+    this.finiteDemands.clear();
+    await this.enqueueLifecycleOperation(async () => {
+      await this.closeTransport();
+    });
+  }
+  hasRoomDemand() {
+    return this.persistentDemands.size > 0 || this.finiteDemands.size > 0;
+  }
+  enqueueLifecycleOperation(operation) {
+    const queued = this.lifecycleOperation.catch(() => void 0).then(operation);
+    this.lifecycleOperation = queued.then(
+      () => void 0,
+      () => void 0
+    );
+    return queued;
+  }
+  async closeTransport() {
+    const session = this.current;
+    this.current = void 0;
+    this.activeBinding = void 0;
+    if (session) {
+      await session.retire();
+    }
+  }
+  bindingsMatch(current, candidate) {
+    return current?.database === candidate.database && current.signature === candidate.signature;
+  }
+  /** Capture immutable session inputs while keeping policy live. */
+  getEffectiveBinding() {
+    const settings = {
+      ...this.env.services.setting.currentSettings()
+    };
+    const deviceName = this.env.services.config.getSmallConfig(SETTING_KEY_P2P_DEVICE_NAME) || this.env.services.vault.getVaultName();
+    const database = this.env.services.database.localDatabase.localDatabase;
+    this.automationCoordinator.reconcileIdentity(
+      JSON.stringify([
+        settings.P2P_AppID || "self-hosted-livesync",
+        settings.P2P_roomID,
+        settings.P2P_passphrase
+      ]),
+      database
+    );
+    return {
+      database,
+      enabled: settings.P2P_Enabled,
+      settings,
+      deviceName,
+      signature: JSON.stringify([getP2PReplicatorConfigurationIdentity(settings), deviceName])
+    };
+  }
+  /** Apply policy which can change without retiring the room session. */
+  reconcileCurrentSessionPolicy(session) {
+    session.replicator.reconcileAutoBroadcast(this.env.services.setting.currentSettings().P2P_AutoBroadcast);
+  }
+  buildSessionEnv(binding) {
+    const services = this.env.services;
+    return {
+      events: services.context.events,
+      translate: services.context.translate,
+      settings: binding.settings,
+      currentSettings: () => services.setting.currentSettings(),
+      db: binding.database,
+      get simpleStore() {
+        return services.keyValueDB.openSimpleStore("p2p-sync");
+      },
+      deviceName: binding.deviceName,
+      get platform() {
+        return services.API.getPlatform();
+      },
+      get confirm() {
+        return services.API.confirm;
+      },
+      runFiniteReplicationActivity: (task, options) => services.replicator.runFiniteReplicationActivity(task, options),
+      canStartOrdinaryReplication: (showMessage = false) => services.replication.isReplicationReady(showMessage, PEER_REPLICATION_READINESS),
+      automationCoordinator: this.automationCoordinator,
+      processReplicatedDocs: async (docs) => {
+        const currentSettings = services.setting.currentSettings();
+        if (currentSettings.suspendParseReplicationResult) {
+          const docLength = docs.length;
+          if (docLength > 0) {
+            Logger(
+              `P2P sync, but parseReplicationResult is suspended. Ignoring ${docLength} documents.`,
+              LOG_LEVEL_VERBOSE
+            );
+          }
+          return;
+        }
+        await services.replication.parseSynchroniseResult(docs);
+      }
+    };
+  }
+}
+export {
+  P2PRoomSessionOwner
+};

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

@@ -1,8 +1,11 @@
 import { type EntryDoc, type ObsidianLiveSyncSettings } from "../../common/types.js";
+import { type LOG_LEVEL } from "octagonal-wheels/common/logger";
 import { type ProgressInfo } from "../../pouchdb/ReplicatorShim.js";
 import type { Confirm } from "../../interfaces/Confirm.js";
 import { type Advertisement, type ReplicatorHostEnv } from "./types.js";
 import { EVENT_P2P_REPLICATOR_PROGRESS, EVENT_P2P_REPLICATOR_STATUS, P2PHost } from "./TrysteroReplicatorP2PServer.js";
+import type { P2PFiniteOperationOwner } from "./P2PRoomSession.js";
+import { type P2PReplicationWireResult } from "./P2PReplicationWire.js";
 export type P2PReplicatorStatus = {
     isBroadcasting: boolean;
     replicatingTo: string[];
@@ -39,6 +42,58 @@ export type P2PReplicationReport = {
         isActive: boolean;
     };
 });
+/**
+ * In-process outcome of one P2P replication request.
+ *
+ * The failed variant deliberately retains an `Error`-compatible value for
+ * local callers. RPC handlers must convert it to `P2PReplicationWireResult`,
+ * because native `Error` properties do not survive JSON serialisation.
+ */
+export type P2PReplicationResult = {
+    readonly status: "completed";
+    readonly ok: true;
+    readonly error?: never;
+} | {
+    readonly status: "cancelled";
+    readonly ok?: false;
+    readonly error?: never;
+} | {
+    readonly status: "failed";
+    readonly ok?: false;
+    readonly error: unknown;
+};
+export type P2PConfiguredTargetResult = {
+    readonly name: string;
+    readonly peerId?: string;
+} & ({
+    readonly status: "completed";
+} | {
+    readonly status: "cancelled";
+} | {
+    readonly status: "missing";
+} | {
+    readonly status: "rejected";
+} | {
+    readonly status: "undecided";
+} | {
+    readonly status: "failed";
+    readonly error: unknown;
+});
+/** Explicit result of configured, unattended P2P target synchronisation. */
+export type P2PConfiguredReplicationResult = {
+    readonly status: "completed";
+    readonly targets: readonly P2PConfiguredTargetResult[];
+} | {
+    readonly status: "cancelled";
+    readonly targets: readonly P2PConfiguredTargetResult[];
+} | {
+    readonly status: "blocked";
+    readonly reason: "no-targets";
+    readonly targets: readonly [];
+} | {
+    readonly status: "partial";
+    readonly targets: readonly P2PConfiguredTargetResult[];
+};
 declare global {
     interface LSEvents {
         [EVENT_P2P_REPLICATOR_STATUS]: P2PReplicatorStatus;
@@ -55,18 +110,27 @@ export type AllReplicationClientStatus = {
 };
 export declare class TrysteroReplicator {
     _env: ReplicatorHostEnv;
+    private readonly finiteOperationOwner?;
+    private disposed;
+    private readonly fallbackAutomationCoordinator;
     server?: P2PHost;
     replicationStatus(): {};
     get settings(): import("../../common/types.js").P2PSyncSetting;
+    /** Latest room-local policy settings supplied by the owning host. */
+    get currentSettings(): import("../../common/types.js").P2PSyncSetting;
     get db(): PouchDB.Database<EntryDoc>;
     get deviceName(): string;
     get platform(): string;
     get confirm(): Confirm;
     get translate(): import("../../context.js").MessageTranslator;
+    private get automationCoordinator();
     private runFiniteReplicationActivity;
     private canStartOrdinaryReplication;
-    constructor(env: ReplicatorHostEnv, server?: P2PHost);
+    constructor(env: ReplicatorHostEnv, server?: P2PHost, finiteOperationOwner?: P2PFiniteOperationOwner);
+    private runSessionFiniteOperation;
     close(): Promise<void>;
+    /** Close the transport and release resources owned for this object's lifetime. */
+    dispose(): Promise<void>;
     open(): Promise<void>;
     makeSureOpened(): Promise<void>;
     get autoSyncPeers(): RegExp[];
@@ -77,31 +141,27 @@ export declare class TrysteroReplicator {
     setOnSetup(): void;
     clearOnSetup(): void;
     getTweakSettings(fromPeerId: string): Promise<Partial<ObsidianLiveSyncSettings>>;
+    private handleSynchronisationRequest;
     getCommands(): {
-        reqSync: (fromPeerId: string) => Promise<{
-            error: any;
-            ok?: undefined;
-        } | {
-            ok: boolean;
-            error?: undefined;
-        }>;
+        reqSync: (fromPeerId: string) => Promise<P2PReplicationWireResult>;
         "!reqAuth": (fromPeerId: string) => Promise<boolean>;
         getTweakSettings: (fromPeerId: string) => Promise<Partial<ObsidianLiveSyncSettings>>;
         onProgress: (fromPeerId: string) => Promise<{
-            error: Error;
+            error: import("../../rpc/index.js").RpcErrorShape;
         }>;
         getAllConfig: (fromPeerId: string) => Promise<string | {
-            error: Error;
+            error: import("../../rpc/index.js").RpcErrorShape;
         }>;
         onProgressAcknowledged: (fromPeerId: string, info: ProgressInfo) => Promise<void>;
         getIsBroadcasting: () => Promise<boolean>;
         requestBroadcasting: (peerId: string) => Promise<true | {
-            error: Error;
+            error: import("../../rpc/index.js").RpcErrorShape;
         }>;
     };
-    requestAuthenticate(peerId: string): Promise<boolean>;
+    requestAuthenticate(peerId: string, signal?: AbortSignal): Promise<boolean>;
     lastSeq: string | number;
-    requestSynchroniseToPeer(peerId: string): Promise<Awaited<ReturnType<ReturnType<typeof this.getCommands>["reqSync"]>>>;
+    requestSynchroniseToPeer(peerId: string, callerSignal?: AbortSignal): Promise<P2PReplicationResult>;
+    private requestSynchroniseToPeerWithinSession;
     requestSynchroniseToAllAvailablePeers(): Promise<void>;
     dispatchStatus(): void;
     requestStatus(): void;
@@ -109,44 +169,36 @@ export declare class TrysteroReplicator {
     _isBroadcasting: boolean;
     disableBroadcastChanges(): void;
     enableBroadcastChanges(): void;
+    /** Apply automatic broadcast policy without restarting this room. */
+    reconcileAutoBroadcast(enabled: boolean): void;
     get knownAdvertisements(): Advertisement[];
     availableReplicationPairs: Set<string>;
-    sync(remotePeer: string, showNotice?: boolean): Promise<{
-        error: any;
-        ok?: undefined;
-    } | {
-        ok: boolean;
-        error?: undefined;
-    }>;
+    sync(remotePeer: string, showNotice?: boolean, callerSignal?: AbortSignal): Promise<P2PReplicationResult>;
+    private syncWithinSession;
     _replicateToPeers: Set<string>;
     _replicateFromPeers: Set<string>;
     dispatchReplicationProgress(peerId: string, info?: ProgressInfo): void;
     onReplicationProgress(peerId: string, info?: ProgressInfo): boolean;
     onProgressAcknowledged(peerId: string, info?: ProgressInfo): boolean;
     acknowledgeProgress(remotePeerId: string, info?: ProgressInfo): void;
-    replicateFrom(remotePeer: string, showNotice?: boolean, fromStart?: boolean, skipOrdinaryReplicationPolicy?: boolean): Promise<{
-        error: any;
-        ok?: undefined;
-    } | {
-        ok: boolean;
-        error?: undefined;
-    }>;
+    replicateFrom(remotePeer: string, showNotice?: boolean, fromStart?: boolean, skipOrdinaryReplicationPolicy?: boolean, callerSignal?: AbortSignal): Promise<P2PReplicationResult>;
+    private replicateFromWithinSession;
     notifyProgress(excludePeerId?: string): Promise<void>;
     requestBroadcastChanges(peerId: string): Promise<unknown>;
     getRemoteIsBroadcasting(peerId: string): Promise<unknown>;
     _watchingPeers: Set<string>;
     watchPeer(peerId: string): void;
     unwatchPeer(peerId: string): void;
-    onUpdateDatabase(fromPeerId: string): Promise<false | {
-        error: any;
-        ok?: undefined;
-    } | {
-        ok: boolean;
-        error?: undefined;
-    }>;
+    onUpdateDatabase(fromPeerId: string): Promise<false | P2PReplicationResult>;
     getRemoteConfig(peerId: string): Promise<false | ObsidianLiveSyncSettings>;
-    checkTweakValues(peerId: string): Promise<boolean>;
-    replicateFromCommand(showResult?: boolean): Promise<void>;
+    /** Compare peer settings without exceeding the presentation authority of the initiating call. */
+    checkTweakValues(peerId: string, signal?: AbortSignal, logLevel?: LOG_LEVEL): Promise<boolean>;
+    private configuredPeerNames;
+    private findAdvertisement;
+    private waitForConfiguredAdvertisements;
+    private configuredTargetResult;
+    /** Synchronise configured peer targets without opening peer-selection UI. */
+    replicateFromCommand(showResult?: boolean, discoveryTimeoutMs?: number, callerSignal?: AbortSignal): Promise<P2PConfiguredReplicationResult>;
     disconnectFromServer(): void;
     pauseServe(): Promise<void>;
     allowReconnection(): void;