@vrtmrz/livesync-commonlib 0.1.0-rc.0

package/dist/rpc/types.d.ts

@@ -0,0 +1,75 @@
+export declare const RPC_VERSION_MAJOR = 1;
+export declare const RPC_VERSION_MINOR = 0;
+export type JsonLike = null | boolean | number | string | JsonLike[] | {
+    [key: string]: JsonLike;
+};
+export type RpcErrorCode = "TIMEOUT" | "NOT_CONNECTED" | "REMOTE_ERROR" | "CANCELLED" | "PROTOCOL_ERROR";
+export type RpcErrorShape = {
+    code: RpcErrorCode;
+    message: string;
+    details?: JsonLike;
+};
+export type RpcRequestEnvelope = {
+    kind: "request";
+    requestId: string;
+    method: string;
+    args: JsonLike[];
+};
+export type RpcResponseEnvelope = {
+    kind: "response";
+    requestId: string;
+    ok: true;
+    data: JsonLike;
+};
+export type RpcResponseErrorEnvelope = {
+    kind: "response";
+    requestId: string;
+    ok: false;
+    error: RpcErrorShape;
+};
+export type RpcCancelEnvelope = {
+    kind: "cancel";
+    requestId: string;
+};
+export type RpcHandshakeEnvelope = {
+    kind: "handshake";
+    versionMajor: number;
+    versionMinor: number;
+};
+export type RpcEnvelope = RpcRequestEnvelope | RpcResponseEnvelope | RpcResponseErrorEnvelope | RpcCancelEnvelope | RpcHandshakeEnvelope;
+export type RpcWireMessageRaw = {
+    wire: "raw";
+    payload: string;
+};
+export type RpcWireMessageChunk = {
+    wire: "chunk";
+    streamId: string;
+    index: number;
+    total: number;
+    payload: string;
+};
+export type RpcWireMessageChunkAck = {
+    wire: "chunk-ack";
+    streamId: string;
+    missing: number[];
+};
+export type RpcWireMessage = RpcWireMessageRaw | RpcWireMessageChunk | RpcWireMessageChunkAck;
+export type TransportOnMessage = (message: RpcWireMessage, peerId: string) => void;
+export type TransportOnPeer = (peerId: string) => void;
+export interface TransportAdapter {
+    send(message: RpcWireMessage, peerId: string): void | Promise<void>;
+    onMessage(handler: TransportOnMessage): () => void;
+    onPeerJoin?(handler: TransportOnPeer): () => void;
+    onPeerLeave?(handler: TransportOnPeer): () => void;
+}
+export type RpcRoomOptions = {
+    transport: TransportAdapter;
+    maxWirePayloadBytes?: number;
+    chunkMissingRetryMs?: number;
+    canAcceptRequest?: (peerId: string, method: string) => boolean | Promise<boolean>;
+    onProtocolWarning?: (message: string, peerId?: string) => void;
+};
+export type RpcMethodHandler<T extends JsonLike[], U> = (peerId: string, ...args: T) => U | Promise<U>;
+export type RpcRegisterOptions = {
+    serial?: boolean;
+};

package/dist/rpc/types.js

@@ -0,0 +1,6 @@
+const RPC_VERSION_MAJOR = 1;
+const RPC_VERSION_MINOR = 0;
+export {
+  RPC_VERSION_MAJOR,
+  RPC_VERSION_MINOR
+};

package/dist/serviceFeatures/checkRemoteSize.d.ts

@@ -0,0 +1,28 @@
+import { createInstanceLogFunction, type LogFunction } from "../services/lib/logUtils.js";
+import type { NecessaryServices } from "../interfaces/ServiceModule.js";
+/**
+ * Notify when checking remote storage size is not configured.
+ * @returns true if the check is passed or user has configured the notification, false to block subsequent processes. (always true).
+ */
+export declare function onNotifyRemoteSizeNotConfiguredFactory(host: NecessaryServices<"appLifecycle" | "API" | "setting", never>, log: ReturnType<typeof createInstanceLogFunction>): () => Promise<boolean>;
+/**
+ * Notify when the remote storage size exceed the threshold.
+ * @returns true if the check is passed or user has chosen to ignore the warning, false to block subsequent processes.
+ * @param host
+ * @param log
+ * @returns
+ */
+export declare function onNotifyRemoteSizeExceedFactory(host: NecessaryServices<"API" | "setting" | "replicator", "rebuilder">, log: ReturnType<typeof createInstanceLogFunction>): () => Promise<boolean>;
+/**
+ * Scan the remote storage size and notify if it is not configured or exceed the threshold.
+ * @param host The necessary services required for the operation.
+ * @param log The logging function to use for logging messages.
+ * @param resetThreshold Whether to reset the notification threshold before scanning. This is useful when you want to force the notification to show up again.
+ * @returns A promise that resolves to true if all checks pass or user has configured the notification.
+ */
+export declare function scanAllStat(host: NecessaryServices<"API" | "setting" | "replicator" | "appLifecycle", "rebuilder">, log: LogFunction, resetThreshold?: boolean): Promise<boolean>;
+/**
+ * Associate the remote storage size check feature with the app lifecycle events.
+ * @param host
+ */
+export declare function useCheckRemoteSize(host: NecessaryServices<"API" | "setting" | "replicator" | "appLifecycle", "rebuilder">): void;

package/dist/serviceFeatures/checkRemoteSize.js

@@ -0,0 +1,178 @@
+import { sizeToHumanReadable } from "octagonal-wheels/number";
+import { LOG_LEVEL_INFO, LOG_LEVEL_NOTICE, LOG_LEVEL_VERBOSE } from "../common/types.js";
+import { createInstanceLogFunction } from "../services/lib/logUtils.js";
+import { EVENT_REQUEST_CHECK_REMOTE_SIZE } from "../events/coreEvents.js";
+function onNotifyRemoteSizeNotConfiguredFactory(host, log) {
+  return async () => {
+    const translate = host.services.context.translate;
+    log(translate("moduleCheckRemoteSize.logCheckingStorageSizes"), LOG_LEVEL_VERBOSE);
+    const settings = host.services.setting.currentSettings();
+    if (settings.notifyThresholdOfRemoteStorageSize >= 0) {
+      return true;
+    }
+    const message = translate("moduleCheckRemoteSize.msgSetDBCapacity");
+    const ANSWER_0 = translate("moduleCheckRemoteSize.optionNoWarn");
+    const ANSWER_800 = translate("moduleCheckRemoteSize.option800MB");
+    const ANSWER_2000 = translate("moduleCheckRemoteSize.option2GB");
+    const ASK_ME_NEXT_TIME = translate("moduleCheckRemoteSize.optionAskMeLater");
+    const ret = await host.services.API.confirm.askSelectStringDialogue(
+      message,
+      [ANSWER_0, ANSWER_800, ANSWER_2000, ASK_ME_NEXT_TIME],
+      {
+        defaultAction: ASK_ME_NEXT_TIME,
+        title: translate("moduleCheckRemoteSize.titleDatabaseSizeNotify"),
+        timeout: 40
+      }
+    );
+    if (ret == ANSWER_0) {
+      await host.services.setting.applyPartial(
+        {
+          notifyThresholdOfRemoteStorageSize: 0
+        },
+        true
+      );
+    } else if (ret == ANSWER_800) {
+      await host.services.setting.applyPartial(
+        {
+          notifyThresholdOfRemoteStorageSize: 800
+        },
+        true
+      );
+    } else if (ret == ANSWER_2000) {
+      await host.services.setting.applyPartial(
+        {
+          notifyThresholdOfRemoteStorageSize: 2e3
+        },
+        true
+      );
+    }
+    return true;
+  };
+}
+function onNotifyRemoteSizeExceedFactory(host, log) {
+  return async () => {
+    const translate = host.services.context.translate;
+    const settings = host.services.setting.currentSettings();
+    if (settings.notifyThresholdOfRemoteStorageSize <= 0) {
+      log("User has chosen to not receive remote storage size exceed notification.", LOG_LEVEL_INFO);
+      return true;
+    }
+    if (host.services.API.isOnline === false) {
+      log("Network is offline, skipping remote size exceed check.", LOG_LEVEL_INFO);
+      return true;
+    }
+    const replicator = host.services.replicator.getActiveReplicator();
+    const remoteStat = await replicator?.getRemoteStatus(host.services.setting.currentSettings());
+    if (!remoteStat) {
+      log("Failed to get remote status, skipping remote size exceed check.", LOG_LEVEL_INFO);
+      return true;
+    }
+    const estimatedSize = remoteStat.estimatedSize;
+    if (estimatedSize) {
+      const maxSize = settings.notifyThresholdOfRemoteStorageSize * 1024 * 1024;
+      if (estimatedSize <= maxSize) {
+        log(
+          translate("moduleCheckRemoteSize.logCurrentStorageSize", {
+            measuredSize: sizeToHumanReadable(estimatedSize)
+          }),
+          LOG_LEVEL_INFO
+        );
+        return true;
+      }
+      const message = translate("moduleCheckRemoteSize.msgDatabaseGrowing", {
+        estimatedSize: sizeToHumanReadable(estimatedSize),
+        maxSize: sizeToHumanReadable(maxSize)
+      });
+      const newMax = ~~(estimatedSize / 1024 / 1024) + 100;
+      const ANSWER_ENLARGE_LIMIT = translate("moduleCheckRemoteSize.optionIncreaseLimit", {
+        newMax: newMax.toString()
+      });
+      const ANSWER_REBUILD = translate("moduleCheckRemoteSize.optionRebuildAll");
+      const ANSWER_IGNORE = translate("moduleCheckRemoteSize.optionDismiss");
+      const ret = await host.services.API.confirm.askSelectStringDialogue(
+        message,
+        [ANSWER_ENLARGE_LIMIT, ANSWER_REBUILD, ANSWER_IGNORE],
+        {
+          defaultAction: ANSWER_IGNORE,
+          title: translate("moduleCheckRemoteSize.titleDatabaseSizeLimitExceeded"),
+          timeout: 60
+        }
+      );
+      if (ret == ANSWER_REBUILD) {
+        const ret2 = await host.services.API.confirm.askYesNoDialog(
+          translate("moduleCheckRemoteSize.msgConfirmRebuild"),
+          { defaultOption: "No" }
+        );
+        if (ret2 == "yes") {
+          await host.services.setting.applyPartial(
+            {
+              notifyThresholdOfRemoteStorageSize: -1
+            },
+            true
+          );
+          await host.serviceModules.rebuilder.scheduleRebuild();
+          return false;
+        }
+        return true;
+      }
+      if (ret == ANSWER_ENLARGE_LIMIT) {
+        const newThreshold = ~~(estimatedSize / 1024 / 1024) + 100;
+        log(
+          translate("moduleCheckRemoteSize.logThresholdEnlarged", {
+            size: newThreshold.toString()
+          }),
+          LOG_LEVEL_NOTICE
+        );
+        await host.services.setting.applyPartial(
+          {
+            notifyThresholdOfRemoteStorageSize: newThreshold
+          },
+          true
+        );
+        return true;
+      }
+      log(
+        translate("moduleCheckRemoteSize.logExceededWarning", {
+          measuredSize: sizeToHumanReadable(estimatedSize),
+          notifySize: sizeToHumanReadable(settings.notifyThresholdOfRemoteStorageSize * 1024 * 1024)
+        }),
+        LOG_LEVEL_INFO
+      );
+    }
+    return true;
+  };
+}
+async function scanAllStat(host, log, resetThreshold = false) {
+  if (resetThreshold) {
+    await host.services.setting.applyPartial(
+      {
+        notifyThresholdOfRemoteStorageSize: -1
+      },
+      true
+    );
+  }
+  const onNotifyNotConfigured = onNotifyRemoteSizeNotConfiguredFactory(host, log);
+  const onNotifyExceed = onNotifyRemoteSizeExceedFactory(host, log);
+  return await onNotifyNotConfigured() && await onNotifyExceed();
+}
+function useCheckRemoteSize(host) {
+  const log = createInstanceLogFunction("SFCheckRemoteSize", host.services.API);
+  host.services.appLifecycle.onScanningStartupIssues.addHandler(() => scanAllStat(host, log, false));
+  host.services.appLifecycle.onInitialise.addHandler(() => {
+    host.services.API.addCommand({
+      id: "livesync-reset-remote-size-threshold-and-check",
+      name: "Reset notification threshold and check the remote database usage",
+      callback: async () => {
+        await scanAllStat(host, log, true);
+      }
+    });
+    host.services.context.events.onEvent(EVENT_REQUEST_CHECK_REMOTE_SIZE, () => scanAllStat(host, log, true));
+    return Promise.resolve(true);
+  });
+}
+export {
+  onNotifyRemoteSizeExceedFactory,
+  onNotifyRemoteSizeNotConfiguredFactory,
+  scanAllStat,
+  useCheckRemoteSize
+};

package/dist/serviceFeatures/offlineScanner.d.ts

@@ -0,0 +1,128 @@
+import { type FilePathWithPrefix, type FilePathWithPrefixLC, type MetaEntry, type UXFileInfoStub, type ObsidianLiveSyncSettings, type LOG_LEVEL } from "../common/types.js";
+import { type LogFunction } from "../services/lib/logUtils.js";
+import type { NecessaryServices } from "../interfaces/ServiceModule.js";
+import { UnresolvedErrorManager } from "../services/base/UnresolvedErrorManager.js";
+/**
+ * Collect deleted files that have expired according to retention policy.
+ * @param host Services container
+ * @param log Logging function
+ * @returns Array of expired deletion history
+ */
+export declare function collectDeletedFiles(host: NecessaryServices<"setting" | "database", never>, log: LogFunction): Promise<void>;
+/**
+ * Get the file path from a meta entry.
+ * This is a helper function to extract path from various document types.
+ * @param doc Meta entry document
+ * @returns Path string
+ */
+export declare function getPathFromEntry(host: NecessaryServices<"path", never>, doc: MetaEntry): FilePathWithPrefix;
+/**
+ * Synchronise a single file between database and storage based on freshness comparison.
+ * @param host Services container
+ * @param log Logging function
+ * @param file Storage file information
+ * @param doc Database entry
+ */
+export declare function syncFileBetweenDBandStorage(host: NecessaryServices<"setting" | "vault" | "path", "storageAccess" | "fileHandler">, log: LogFunction, file: UXFileInfoStub, doc: MetaEntry): Promise<void>;
+export declare function canProceedScan(host: NecessaryServices<"keyValueDB" | "setting", never>, errorManager: UnresolvedErrorManager, log: LogFunction, showingNotice?: boolean, ignoreSuspending?: boolean): boolean;
+/**
+ * Convert file path to lower case if the settings indicate that filename case should be handled insensitively.
+ * @param settings
+ * @param path
+ * @returns
+ */
+export declare function convertCase<T extends FilePathWithPrefix>(settings: ObsidianLiveSyncSettings, path: T): FilePathWithPrefixLC;
+export declare function collectFilesOnStorage(host: NecessaryServices<"vault", "storageAccess">, settings: ObsidianLiveSyncSettings, log: LogFunction): Promise<{
+    storageFileNameMap: {
+        [k: string]: UXFileInfoStub;
+    };
+    storageFileNames: FilePathWithPrefix[];
+    storageFileNameCI2CS: Record<FilePathWithPrefixLC, FilePathWithPrefix>;
+}>;
+export declare function collectDatabaseFiles(host: NecessaryServices<"database" | "vault" | "path", never>, settings: ObsidianLiveSyncSettings, log: LogFunction, showingNotice: boolean): Promise<{
+    databaseFileNameMap: {
+        [k: string]: MetaEntry;
+    };
+    databaseFileNames: FilePathWithPrefix[];
+    databaseFileNameCI2CS: Record<FilePathWithPrefix, FilePathWithPrefixLC>;
+}>;
+export declare function updateToDatabase(host: NecessaryServices<"vault", "fileHandler">, log: LogFunction, logLevel: LOG_LEVEL, file: UXFileInfoStub): Promise<void>;
+export declare function updateToStorage(host: NecessaryServices<"vault" | "path", "fileHandler">, log: LogFunction, logLevel: LOG_LEVEL, w: MetaEntry): Promise<void>;
+export declare function syncStorageAndDatabase(host: NecessaryServices<"setting" | "vault" | "path", "storageAccess" | "fileHandler">, log: LogFunction, file: UXFileInfoStub, logLevel: LOG_LEVEL, doc: MetaEntry): Promise<void>;
+export declare const FullScanModes: {
+    readonly DB_APPLY: "db-apply";
+    readonly NEWER_WINS: "newer-wins";
+};
+export declare const ExtraOnRemote: {
+    /**
+     * Delete database entries if they are missing on storage.
+     */
+    readonly DELETE_LOCAL_MISSING: "delete-local-missing";
+};
+export declare const ExtraOnLocal: {
+    /**
+     * Delete local files if they were deleted on database.
+     */
+    readonly DELETE_DB_DELETED: "delete-db-deleted";
+    /**
+     * Delete local files if they are missing on database or were deleted on database.
+     */
+    readonly DELETE_DB_MISSING: "delete-db-missing";
+    /**
+     * Merge local files to database
+     */
+    readonly APPEND_STORAGE_ONLY: "append-storage-only";
+};
+export interface FullScanOptions {
+    mode: FullScanMode;
+    extraOnLocal?: (typeof ExtraOnLocal)[keyof typeof ExtraOnLocal];
+    extraOnRemote?: (typeof ExtraOnRemote)[keyof typeof ExtraOnRemote];
+    omitEvents?: boolean;
+    showingNotice?: boolean;
+    ignoreSuspending?: boolean;
+}
+export type FullScanMode = (typeof FullScanModes)[keyof typeof FullScanModes];
+type FilePair = {
+    file: UXFileInfoStub;
+    doc: MetaEntry;
+} | {
+    file: undefined;
+    doc: MetaEntry;
+} | {
+    file: UXFileInfoStub;
+    doc: undefined;
+};
+type FilePairState = "storage-only" | "db-only" | "db-only-deleted" | "both" | "both-db-deleted";
+type FilePairAction = "update-db" | "update-storage" | "sync-newer" | "delete-local" | "delete-db" | "skip";
+export declare function getFilePairState(pair: FilePair): FilePairState;
+/**
+ * Determine the action to be taken for a file pair based on its state and the selected scan options.
+ */
+export declare function resolveFilePairAction(state: FilePairState, options: FullScanOptions): FilePairAction;
+/**
+ * Synchronise all files between database and storage based on the selected mode and options.
+ * @param host Core
+ * @param log Logging function
+ * @param errorManager Error manager
+ * @param options Full scan options
+ */
+export declare function synchroniseAllFilesBetweenDBandStorage(host: NecessaryServices<"setting" | "vault" | "path" | "fileProcessing" | "database" | "keyValueDB", "storageAccess" | "fileHandler">, log: LogFunction, errorManager: UnresolvedErrorManager, options: FullScanOptions): Promise<boolean>;
+export declare function normaliseFullScanOptions(showingNoticeOrOptions: Partial<FullScanOptions> | boolean | undefined, ignoreSuspending?: boolean): FullScanOptions;
+/**
+ * Perform a full scan and synchronisation between database and storage.
+ * @param host Services container
+ * @param log Logging function
+ * @param errorManager Error manager
+ * @param showingNotice Whether to show notices during scanning
+ * @param ignoreSuspending Whether to ignore suspension settings
+ * @returns True if scan completed successfully
+ */
+export declare function performFullScan(host: NecessaryServices<"setting" | "vault" | "path" | "fileProcessing" | "database" | "keyValueDB", "storageAccess" | "fileHandler">, log: LogFunction, errorManager: UnresolvedErrorManager, options?: Partial<FullScanOptions>): Promise<boolean>;
+export declare function performFullScan(host: NecessaryServices<"setting" | "vault" | "path" | "fileProcessing" | "database" | "keyValueDB", "storageAccess" | "fileHandler">, log: LogFunction, errorManager: UnresolvedErrorManager, showingNotice?: boolean, ignoreSuspending?: boolean): Promise<boolean>;
+/**
+ * Associate the initialiser file feature with the app lifecycle events.
+ * This function binds initialization handlers to the appropriate lifecycle events.
+ * @param host Services container with required dependencies
+ */
+export declare function useOfflineScanner(host: NecessaryServices<"API" | "appLifecycle" | "setting" | "vault" | "path" | "database" | "databaseEvents" | "fileProcessing" | "keyValueDB" | "replicator", "storageAccess" | "fileHandler">): void;
+export {};