core-3nweb-client-lib 0.25.6 → 0.27.0

package/README.md

@@ -10,9 +10,9 @@ After repository clone, bring down all NodeJS modules, by running in project's f
 npm ci
 ```
 
-Tests have some unit and integrated components. Integration test uses 3NWeb spec server. `spec-server` folder with server's code should be present either near this project's folder, or inside of it. Cloned spec server code repository should also be `npm ci`
+Tests have some unit and integrated components. Integration test uses 3NWeb spec server. Integrated tests use server and dns mocking from `spec-3nweb-server`.
 
-Just build is done with
+Build is done with
 ```
 npm run build
 ```

package/build/api-defs/asmail.d.ts

@@ -1,5 +1,5 @@
 /*
- Copyright (C) 2016, 2020 3NSoft Inc.
+ Copyright (C) 2016, 2020, 2022 3NSoft Inc.
 
  This program is free software: you can redistribute it and/or modify it under
  the terms of the GNU General Public License as published by the Free Software

package/build/api-defs/files.d.ts

@@ -40,6 +40,7 @@ declare namespace web3n.files {
 		attrsNotEnabledInFS?: true;
 		versionMismatch?: true;
 		isEndless?: true;
+		storageClosed?: true;
 	}
 
 	interface exceptionCode {
@@ -58,6 +59,25 @@ declare namespace web3n.files {
 		parsingError: 'parsing-error';
 		notImplemented: 'ENOSYS';
 		isEndless: 'is-endless';
+		storageClosed: 'storage-closed';
+		versionMismatch: 'version-mismatch';
+	}
+
+	interface FSSyncException extends RuntimeException {
+		type: 'fs-sync';
+		path: string;
+		localVersion?: number;
+		remoteVersion?: number;
+		alreadyUploading?: true;
+		versionNotFound?: true;
+		childNeverUploaded?: true;
+		childName?: string;
+		removedOnServer?: true;
+		versionMismatch?: true;
+		conflict?: true;
+		notSynced?: true;
+		remoteIsArchived?: true;
+		remoteFolderItemNotFound?: true;
 	}
 
 	/**
@@ -126,6 +146,41 @@ declare namespace web3n.files {
 
 	}
 
+	/**
+	 * Sync status contains info about possible version branches with possible
+	 * states:
+	 * 1. unsynced - have local branch, and possibly synced one.
+	 *    Local version(s) should be uploaded to get into synced state.
+	 * 2. synced - have only synced branch.
+	 * 3. behind - have both synced and remote branches.
+	 *    Should explicitly advance to newer version to get into synced state.
+	 * 4. conflicting - have conflicting local and remote branches, with possible
+	 *    common synced history branch.
+	 *    Conflict gets fixed by uploading some local version with value greater
+	 *    than remote's latest. Making this version is a custom magic of
+	 *    conflict resolution that you do for your app.
+	 */
+	interface SyncStatus {
+		state: SyncState;
+		synced?: SyncVersionsBranch;
+		local?: LocalVersion;
+		remote?: SyncVersionsBranch;
+		existsInSyncedParent?: boolean;
+	}
+
+	interface LocalVersion {
+		latest?: number;
+		isArchived?: boolean;
+	}
+
+	interface SyncVersionsBranch {
+		latest?: number;
+		archived?: number[];
+		isArchived?: boolean;
+	}
+
+	type SyncState = 'synced' | 'behind' | 'unsynced' | 'conflicting';
+
 	interface FileByteSource {
 
 		/**
@@ -312,7 +367,7 @@ declare namespace web3n.files {
 		 */
 		getByteSource(): Promise<FileByteSource>;
 
-		watch(observer: Observer<FileEvent>): () => void;
+		watch(observer: Observer<FileEvent|RemoteEvent>): () => void;
 
 	}
 
@@ -382,8 +437,9 @@ declare namespace web3n.files {
 		 * greater than file length, all available bytes are read. If parameter
 		 * is missing, read will be done to file's end.
 		 */
-		readBytes(start?: number, end?: number):
-			Promise<{ bytes: Uint8Array|undefined; version: number; }>;
+		readBytes(
+			start?: number, end?: number
+		): Promise<{ bytes: Uint8Array|undefined; version: number; }>;
 
 		/**
 		 * This returns a promise, resolvable to text, read from file, assuming
@@ -402,6 +458,10 @@ declare namespace web3n.files {
 		 */
 		getByteSource(): Promise<{ src: FileByteSource; version: number; }>;
 
+		listVersions(): Promise<{ current?: number; archived?: number[]; }>;
+
+		sync?: ReadonlyFileSyncAPI;
+
 	}
 
 	interface WritableFileVersionedAPI extends ReadonlyFileVersionedAPI {
@@ -444,8 +504,9 @@ declare namespace web3n.files {
 		 * When current version is given, an error is thrown, if file version at
 		 * the moment of writing is different.
 		 */
-		getByteSink(truncateFile?: boolean, currentVersion?: number):
-			Promise<{ sink: FileByteSink; version: number; }>;
+		getByteSink(
+			truncateFile?: boolean, currentVersion?: number
+		): Promise<{ sink: FileByteSink; version: number; }>;
 
 		/**
 		 * This returns a promise, resolvable to new file's version when copying
@@ -453,7 +514,48 @@ declare namespace web3n.files {
 		 * @param file which content will be copied into this file
 		 */
 		copy(file: File): Promise<number>;
-		
+
+		archiveCurrent(version?: number): Promise<number>;
+
+		sync?: WritableFileSyncAPI;
+
+	}
+
+	interface ReadonlyFileSyncAPI {
+
+		/**
+		 * Returns synchronization status of this object, as is currently known
+		 * here without checking remote server.
+		 */
+		status(): Promise<SyncStatus>;
+
+		updateStatusInfo(): Promise<SyncStatus>;
+
+		isRemoteVersionOnDisk(
+			version: number
+		): Promise<'partial'|'complete'|'none'>;
+
+		download(version: number): Promise<void>;
+
+		adoptRemote(opts?: OptionsToAdopteRemote): Promise<void>;
+
+	}
+
+	interface OptionsToAdopteRemote {
+		dropLocalVer?: boolean;
+		remoteVersion?: number;
+		download?: boolean;
+	}
+
+	interface WritableFileSyncAPI extends ReadonlyFileSyncAPI {
+
+		upload(opts?: OptionsToUploadLocal): Promise<void>;
+
+	}
+
+	interface OptionsToUploadLocal {
+		localVersion?: number;
+		uploadVersion?: number;
 	}
 
 	type FSType = 'device' | 'synced' | 'local' | 'share' | 'asmail-msg';
@@ -482,8 +584,9 @@ declare namespace web3n.files {
 		 * throwing of an exception, when folder does not exist. Default value is
 		 * false.
 		 */
-		checkFolderPresence(path: string, throwIfMissing?: boolean):
-			Promise<boolean>;
+		checkFolderPresence(
+			path: string, throwIfMissing?: boolean
+		): Promise<boolean>;
 		
 		/**
 		 * This returns a promise, resolvable to true, if file exists, and to
@@ -493,8 +596,9 @@ declare namespace web3n.files {
 		 * throwing of an exception, when file does not exist. Default value is
 		 * false.
 		 */
-		checkFilePresence(path: string, throwIfMissing?: boolean):
-			Promise<boolean>;
+		checkFilePresence(
+			path: string, throwIfMissing?: boolean
+		): Promise<boolean>;
 		
 		/**
 		 * This returns a promise, resolvable to true, if link exists, and to
@@ -504,8 +608,9 @@ declare namespace web3n.files {
 		 * throwing of an exception, when link does not exist. Default value is
 		 * false.
 		 */
-		checkLinkPresence(path: string, throwIfMissing?: boolean):
-			Promise<boolean>;
+		checkLinkPresence(
+			path: string, throwIfMissing?: boolean
+		): Promise<boolean>;
 		
 		/**
 		 * This returns a promise, resolvable to stats of an entity at a given
@@ -530,12 +635,18 @@ declare namespace web3n.files {
 
 		readLink(path: string): Promise<SymLink>;
 
-		watchFolder(path: string, observer: Observer<FolderEvent>): () => void;
+		watchFolder(
+			path: string, observer: Observer<FolderEvent|RemoteEvent>
+		): () => void;
 
-		watchFile(path: string, observer: Observer<FileEvent>): () => void;
+		watchFile(
+			path: string, observer: Observer<FileEvent|RemoteEvent>
+		): () => void;
 
-		watchTree(path: string, observer: Observer<FolderEvent|FileEvent>):
-			() => void;
+		watchTree(
+			path: string, depth: number|undefined,
+			observer: Observer<FolderEvent|FileEvent|RemoteEvent>
+		): () => void;
 
 		close(): Promise<void>;
 
@@ -577,8 +688,9 @@ declare namespace web3n.files {
 		 * greater than file length, all available bytes are read. If parameter
 		 * is missing, read will be done to file's end.
 		 */
-		readBytes(path: string, start?: number, end?: number):
-			Promise<Uint8Array|undefined>;
+		readBytes(
+			path: string, start?: number, end?: number
+		): Promise<Uint8Array|undefined>;
 
 		/**
 		 * This returns a promise, resolvable to bytes source with seek, which
@@ -603,8 +715,9 @@ declare namespace web3n.files {
 		 * @param path 
 		 * @param criteria 
 		 */
-		select(path: string, criteria: SelectCriteria):
-			Promise<{ items: FSCollection; completion: Promise<void>; }>;
+		select(
+			path: string, criteria: SelectCriteria
+		): Promise<{ items: FSCollection; completion: Promise<void>; }>;
 
 	}
 
@@ -736,8 +849,9 @@ declare namespace web3n.files {
 		 * @param overwrite is a flag that with a true value allows
 		 * overwrite of existing dst file. Default value is false.
 		 */
-		copyFile(src: string, dst: string, overwrite?: boolean):
-			Promise<void>;
+		copyFile(
+			src: string, dst: string, overwrite?: boolean
+		): Promise<void>;
 
 		/**
 		 * This returns a promise, resolvable when folder has been recursively
@@ -748,8 +862,9 @@ declare namespace web3n.files {
 		 * merge into existing folder and files overwriting inside. Default
 		 * value is false.
 		 */
-		copyFolder(src: string, dst: string, mergeAndOverwrite?: boolean):
-			Promise<void>;
+		copyFolder(
+			src: string, dst: string, mergeAndOverwrite?: boolean
+		): Promise<void>;
 
 		/**
 		 * This returns a promise, resolvable when file has been saved.
@@ -769,8 +884,9 @@ declare namespace web3n.files {
 		 * merge into existing folder and files overwriting inside. Default
 		 * value is false.
 		 */
-		saveFolder(folder: FS, dst: string, mergeAndOverwrite?: boolean):
-			Promise<void>;
+		saveFolder(
+			folder: FS, dst: string, mergeAndOverwrite?: boolean
+		): Promise<void>;
 
 		/**
 		 * This returns a promise, resolvable when file has been removed
@@ -814,8 +930,9 @@ declare namespace web3n.files {
 		 * @param flags are optional flags. Default flags are create=true,
 		 * exclusive=false.
 		 */
-		writeBytes(path: string, bytes: Uint8Array, flags?: FileFlags):
-			Promise<void>;
+		writeBytes(
+			path: string, bytes: Uint8Array, flags?: FileFlags
+		): Promise<void>;
 
 		/**
 		 * This returns a promise, resolvable to byte sink with seek
@@ -871,8 +988,9 @@ declare namespace web3n.files {
 
 	interface ReadonlyFSVersionedAPI {
 
-		getXAttr(path: string, xaName: string):
-			Promise<{ attr: any; version: number; }>;
+		getXAttr(
+			path: string, xaName: string
+		): Promise<{ attr: any; version: number; }>;
 	
 		listXAttrs(path: string): Promise<{ lst: string[]; version: number; }>;
 
@@ -881,8 +999,9 @@ declare namespace web3n.files {
 		 * for entries in the folder, and a folder's version.
 		 * @param path of a folder that should be listed
 		 */
-		listFolder(path: string):
-			Promise<{ lst: ListingEntry[]; version: number; }>;
+		listFolder(
+			path: string
+		): Promise<{ lst: ListingEntry[]; version: number; }>;
 
 		/**
 		 * This returns a promise, resolvable to json, read from file, and a
@@ -909,16 +1028,24 @@ declare namespace web3n.files {
 		 * greater than file length, all available bytes are read. If parameter
 		 * is missing, read will be done to file's end.
 		 */
-		readBytes(path: string, start?: number, end?: number):
-			Promise<{ bytes: Uint8Array|undefined; version: number; }>;
+		readBytes(
+			path: string, start?: number, end?: number
+		): Promise<{ bytes: Uint8Array|undefined; version: number; }>;
 
 		/**
 		 * This returns a promise, resolvable to bytes source with seek, which
 		 * allows random reads, and a file version
 		 * @param path of a file from which to read bytes
 		 */
-		getByteSource(path: string):
-			Promise<{ src: FileByteSource; version: number; }>;
+		getByteSource(
+			path: string
+		): Promise<{ src: FileByteSource; version: number; }>;
+
+		listVersions(
+			path: string
+		): Promise<{ current?: number; archived?: number[]; }>;
+
+		sync?: ReadonlyFSSyncAPI;
 
 	}
 
@@ -940,8 +1067,9 @@ declare namespace web3n.files {
 		 * @param flags are optional flags. Default flags are create=true,
 		 * exclusive=false.
 		 */
-		writeJSONFile(path: string, json: any, flags?: VersionedFileFlags):
-			Promise<number>;
+		writeJSONFile(
+			path: string, json: any, flags?: VersionedFileFlags
+		): Promise<number>;
 
 		/**
 		 * This returns a promise, resolvable to new file's version when file is
@@ -951,8 +1079,9 @@ declare namespace web3n.files {
 		 * @param flags are optional flags. Default flags are create=true,
 		 * exclusive=false.
 		 */
-		writeTxtFile(path: string, txt: string, flags?: VersionedFileFlags):
-			Promise<number>;
+		writeTxtFile(
+			path: string, txt: string, flags?: VersionedFileFlags
+		): Promise<number>;
 
 		/**
 		 * This returns a promise, resolvable to new file's version when file is
@@ -962,8 +1091,9 @@ declare namespace web3n.files {
 		 * @param flags are optional flags. Default flags are create=true,
 		 * exclusive=false.
 		 */
-		writeBytes(path: string, bytes: Uint8Array, flags?: VersionedFileFlags):
-			Promise<number>;
+		writeBytes(
+			path: string, bytes: Uint8Array, flags?: VersionedFileFlags
+		): Promise<number>;
 
 		/**
 		 * This returns a promise, resolvable to byte sink with seek, and a file
@@ -972,66 +1102,148 @@ declare namespace web3n.files {
 		 * @param flags are optional flags. Default flags are create=true,
 		 * exclusive=false, truncate=true.
 		 */
-		getByteSink(path: string, flags?: VersionedFileFlags):
-			Promise<{ sink: FileByteSink; version: number; }>;
+		getByteSink(
+			path: string, flags?: VersionedFileFlags
+		): Promise<{ sink: FileByteSink; version: number; }>;
+
+		archiveCurrent(path: string, version?: number): Promise<number>;
+
+		sync?: WritableFSSyncAPI;
 
 	}
 
-	interface FSEvent {
-		type: string;
-		path: string;
-		isRemote?: boolean;
-		newVersion?: number;
+	interface ReadonlyFSSyncAPI {
+
+		/**
+		 * Returns synchronization status of this object, as is currently known
+		 * here without checking remote server.
+		 */
+		status(path: string): Promise<SyncStatus>;
+
+		updateStatusInfo(path: string): Promise<SyncStatus>;
+
+		isRemoteVersionOnDisk(
+			path: string, version: number
+		): Promise<'partial'|'complete'|'none'>;
+
+		download(path: string, version: number): Promise<void>;
+
+		adoptRemote(path: string, opts?: OptionsToAdopteRemote): Promise<void>;
+
+		diffCurrentAndRemoteFolderVersions(
+			path: string, remoteVersion?: number
+		): Promise<FolderDiff|undefined>;
+
 	}
 
-	interface RemovedEvent extends FSEvent {
-		type: 'removed';
+	interface FolderDiff {
+		currentVersion: number;
+		isCurrentLocal: boolean;
+		remoteVersion?: number;
+		isRemoteArchived: boolean;
+		inCurrent?: ListingEntry[];
+		inRemote?: ListingEntry[];
+		nameOverlaps?: string[];
+		ctime: {
+			remote?: Date;
+			current: Date;
+		};
+		mtime: {
+			remote?: Date;
+			current: Date;
+		};
+		xattrs?: {
+			inCurrent?: { name: string; value: any; }[];
+			inRemote?: { name: string; value: any; }[];
+			nameOverlaps?: string[];
+		};
+	}
+
+	interface WritableFSSyncAPI extends ReadonlyFSSyncAPI {
+
+		upload(path: string, opts?: OptionsToUploadLocal): Promise<void>;
+
+		adoptRemoteFolderItem(
+			path: string, itemName: string, opts?: OptionsToAdoptRemoteItem
+		): Promise<number>;
+
+	}
+
+	interface OptionsToAdoptRemoteItem {
+		localVersion?: number;
+		remoteVersion?: number;
 	}
 
-	interface MovedEvent extends FSEvent {
-		type: 'moved';
+	interface FSEvent {
+		path: string;
 	}
 
-	interface SyncedEvent extends FSEvent {
-		type: 'synced';
-		current: number;
+	interface FSChangeEvent {
+		path: string;
+		src: 'local'|'sync';
 	}
 
-	interface UnsyncedEvent extends FSEvent {
-		type: 'unsynced';
-		lastSynced: number;
+	interface RemovedEvent extends FSChangeEvent {
+		type: 'removed';
 	}
 
-	interface ConflictEvent extends FSEvent {
-		type: 'conflicting';
-		remoteVersion: number;
+	interface VersionChangeOnUpload extends FSChangeEvent {
+		type: 'version-change-on-upload';
+		src: 'sync';
+		newVersion: number;
 	}
 
 	type FolderEvent = EntryRemovalEvent | EntryAdditionEvent |
-		EntryRenamingEvent | RemovedEvent | MovedEvent |
-		SyncedEvent | UnsyncedEvent | ConflictEvent;
+		EntryRenamingEvent | RemovedEvent | VersionChangeOnUpload;
 
-	interface EntryRemovalEvent extends FSEvent {
+	interface EntryRemovalEvent extends FSChangeEvent {
 		type: 'entry-removal';
 		name: string;
+		moveLabel?: number;
+		newVersion?: number;
 	}
 
-	interface EntryAdditionEvent extends FSEvent {
+	interface EntryAdditionEvent extends FSChangeEvent {
 		type: 'entry-addition';
 		entry: ListingEntry;
+		moveLabel?: number;
+		newVersion?: number;
 	}
 
-	interface EntryRenamingEvent extends FSEvent {
+	interface EntryRenamingEvent extends FSChangeEvent {
 		type: 'entry-renaming';
 		oldName: string;
 		newName: string;
+		newVersion?: number;
 	}
 
-	type FileEvent = FileChangeEvent | RemovedEvent | MovedEvent |
-		SyncedEvent | UnsyncedEvent | ConflictEvent;
+	type FileEvent = FileChangeEvent | RemovedEvent | VersionChangeOnUpload;
 
-	interface FileChangeEvent extends FSEvent {
+	interface FileChangeEvent extends FSChangeEvent {
 		type: 'file-change';
+		newVersion?: number;
+	}
+
+	type RemoteEvent = RemoteVersionArchivalEvent | RemoteArchVerRemovalEvent |
+		RemoteRemovalEvent | RemoteChangeEvent;
+
+	interface RemoteVersionArchivalEvent extends FSEvent {
+		type: 'remote-version-archival';
+		archivedVersion: number;
+	}
+
+	interface RemoteArchVerRemovalEvent extends FSEvent {
+		type: 'remote-arch-ver-removal';
+		removedArchVer: number;
+	}
+
+	interface RemoteRemovalEvent extends FSEvent {
+		type: 'remote-removal';
+	}
+
+	interface RemoteChangeEvent extends FSEvent {
+		type: 'remote-change';
+		newVersion: number;
 	}
 
 }

package/build/core/app-files.js

@@ -33,32 +33,32 @@ const INBOX_DIR = 'inbox';
 const STORAGE_DIR = 'storage';
 function appDirs(appDir) {
     function userDataPath(user) {
-        return path_1.join(appDir, userIdToFolderName(user));
+        return (0, path_1.join)(appDir, userIdToFolderName(user));
     }
     ;
     async function appFS() {
-        await async_fs_node_1.stat(appDir).catch(async (e) => {
+        await (0, async_fs_node_1.stat)(appDir).catch(async (e) => {
             if (!e.notFound) {
                 throw e;
             }
-            await async_fs_node_1.mkdir(appDir).catch((e) => {
+            await (0, async_fs_node_1.mkdir)(appDir).catch((e) => {
                 if (e.alreadyExists) {
                     return;
                 }
-                throw error_1.errWithCause(e, `Cannot create app folder on the disk`);
+                throw (0, error_1.errWithCause)(e, `Cannot create app folder on the disk`);
             });
         });
         return device_fs_1.DeviceFS.makeWritable(appDir);
     }
     return Object.freeze({
         getUtilFS() {
-            return path_1.join(appDir, exports.UTIL_DIR);
+            return (0, path_1.join)(appDir, exports.UTIL_DIR);
         },
         storagePathFor(user) {
-            return path_1.join(userDataPath(user), STORAGE_DIR);
+            return (0, path_1.join)(userDataPath(user), STORAGE_DIR);
         },
         inboxPathFor(user) {
-            return path_1.join(userDataPath(user), INBOX_DIR);
+            return (0, path_1.join)(userDataPath(user), INBOX_DIR);
         },
         async getUsersOnDisk() {
             const rootFS = await appFS();

package/build/core/asmail/config/common.js

@@ -18,7 +18,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ParamOnFileAndServer = void 0;
 const json_utils_1 = require("../../../lib-common/json-utils");
 const file_based_json_1 = require("../../../lib-client/3nstorage/util/file-based-json");
-const processes_1 = require("../../../lib-common/processes");
+const synced_1 = require("../../../lib-common/processes/synced");
 class ParamOnFileAndServer extends file_based_json_1.JsonFileProc {
     constructor(paramPath, serviceConf) {
         super();
@@ -27,7 +27,7 @@ class ParamOnFileAndServer extends file_based_json_1.JsonFileProc {
         // XXX This should be done in a transactional style, with set on server
         // first. FolderNode with its base class is an example of transactional
         // mechanism implementation.
-        this.changesProc = new processes_1.SingleProc();
+        this.changesProc = new synced_1.SingleProc();
     }
     async start(file) {
         await super.start(file, async () => {
@@ -55,12 +55,12 @@ class ParamOnFileAndServer extends file_based_json_1.JsonFileProc {
             throw exc;
         });
         const currentVal = this.toServiceJSON();
-        if (!json_utils_1.deepEqual(infoOnServer, currentVal)) {
+        if (!(0, json_utils_1.deepEqual)(infoOnServer, currentVal)) {
             await this.serviceConf.setParam(this.paramPath, currentVal);
         }
     }
     async onFileEvent(ev) {
-        if (!ev.isRemote) {
+        if (ev.src === 'local') {
             return;
         }
         if (ev.type === 'removed') {

package/build/core/asmail/config/index.js

@@ -47,7 +47,7 @@ class ConfigOfASMailServer {
     }
     static async makeAndStart(address, getSigner, resolver, net, fs) {
         try {
-            file_1.ensureCorrectFS(fs, 'synced', true);
+            (0, file_1.ensureCorrectFS)(fs, 'synced', true);
             const conf = new ConfigOfASMailServer(address, getSigner, resolver, net);
             await Promise.all([
                 fs.writableFile(ANON_SENDER_INVITES_FILE)
@@ -59,7 +59,7 @@ class ConfigOfASMailServer {
             return conf;
         }
         catch (err) {
-            throw error_1.errWithCause(err, 'Failed to initialize ConfigOfASMailServer');
+            throw (0, error_1.errWithCause)(err, 'Failed to initialize ConfigOfASMailServer');
         }
     }
 }

package/build/core/asmail/config/published-intro-key.js

@@ -80,7 +80,7 @@ class PublishedIntroKey extends common_2.ParamOnFileAndServer {
     }
     async makeNewIntroKey() {
         const signer = await this.getSigner();
-        const pair = await common_1.generateKeyPair();
+        const pair = await (0, common_1.generateKeyPair)();
         const certs = {
             pkeyCert: signer.certifyPublicKey(pair.pkey, INTRO_KEY_VALIDITY),
             userCert: signer.userCert,