spec-3nweb-server 1.8.4 → 1.8.6

package/ts-code/3nstorage/resources/users.ts

@@ -0,0 +1,258 @@
+/*
+ Copyright (C) 2015 - 2017, 2020, 2025 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
+ Foundation, either version 3 of the License, or (at your option) any later
+ version.
+ 
+ This program is distributed in the hope that it will be useful, but
+ WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+ See the GNU General Public License for more details.
+ 
+ You should have received a copy of the GNU General Public License along with
+ this program. If not, see <http://www.gnu.org/licenses/>.
+*/
+
+/**
+ * This module produces users object, which managers users, and manages
+ * storage. The whole storage reliance set is located behind user's factory,
+ * which is created by this module.
+ */
+
+import { Readable as ReadableStream } from 'stream';
+import { Store, SC, ObjReader, StorageEventsSink, StorageParams } from './store';
+import { PutObjFirstQueryOpts, PutObjSecondQueryOpts, DiffInfo, ObjStatus } from '../../lib-common/service-api/3nstorage/owner';
+import { userDataInRootFolder } from '../../lib-server/resources/server-data-folders';
+
+export { SC, ObjReader, MismatchedObjVerException } from './store';
+
+export type UserExists = (userId: string) => Promise<boolean>;
+
+export type GetCurrentObj = (
+	userId: string, objId: string|null,
+	header: boolean, segsOffset: number, segsLimit: number|undefined
+) => Promise<{ version: number; reader: ObjReader; }>;
+
+export type SaveNewObjVersion = (
+	userId: string, objId: string|null,
+	fstReq: PutObjFirstQueryOpts|undefined, diff: DiffInfo|undefined,
+	sndReq: PutObjSecondQueryOpts|undefined,
+	bytesLen: number, bytes: ReadableStream
+) => Promise<string|undefined>;
+
+export type GetArchivedObjVersion = (
+	userId: string, objId: string|null, version: number,
+	header: boolean, segsOffset: number, segsLimit: number|undefined
+) => Promise<ObjReader>;
+
+export type CancelTransaction = (
+	userId: string, objId: string, transactionId?: string
+) => Promise<void>;
+
+export type ArchiveObjCurrentVersion = (
+	userId: string, objId: string, version: number
+) => Promise<void>;
+
+export type GetObjStatus = (
+	userId: string, objId: string
+) => Promise<ObjStatus>;
+
+export type DeleteCurrentObjVersion = (
+	userId: string, objId: string, version?: number
+) => Promise<void>;
+
+export type DeleteArchivedObjVersion = (
+	userId: string, objId: string|null, version: number
+) => Promise<void>;
+
+export type GetSpaceQuota = (userId: string) => Promise<number>;
+
+type GetParam<P extends keyof StorageParams> = (
+	userId: string
+) => Promise<StorageParams[P]>;
+type SetParam<P extends keyof StorageParams> = (
+	userId: string, param: StorageParams[P]
+) => Promise<boolean>;
+
+export type GetKeyDerivParams = GetParam<'key-deriv'>;
+export type SetKeyDerivParams = SetParam<'key-deriv'>;
+
+export type EventsSink = StorageEventsSink;
+
+/**
+ * This is an external interface, behind which all storage machinery is hidding.
+ */
+export interface Factory {
+	exists: UserExists;
+	getKeyDerivParams: GetKeyDerivParams;
+	setKeyDerivParams: SetKeyDerivParams;
+	getSpaceQuota: GetSpaceQuota;
+	cancelTransaction: CancelTransaction;
+	getCurrentObj: GetCurrentObj;
+	saveNewObjVersion: SaveNewObjVersion;
+	saveNewRootVersion: SaveNewObjVersion;
+	getCurrentRootObj: GetCurrentObj;
+	getObjStatus: GetObjStatus;
+	archiveObjVersion: ArchiveObjCurrentVersion;
+	getArchivedRootVersion: GetArchivedObjVersion;
+	getArchivedObjVersion: GetArchivedObjVersion;
+	deleteCurrentObjVersion: DeleteCurrentObjVersion;
+	deleteArchivedObjVersion: DeleteArchivedObjVersion;
+	setStorageEventsSink(sink: EventsSink): void;
+}
+
+export function makeFactory(
+	rootFolder: string,
+	writeBufferSize?: string|number, readBufferSize?: string|number
+): Factory {
+
+	const stores = new Map<string, Store>();
+
+	let storageEventsSink: StorageEventsSink|undefined = undefined;
+
+	async function getStore(userId: string): Promise<Store> {
+		if (!storageEventsSink) {
+			throw new Error(`Storage events sink is not set`);
+		}
+		const store = stores.get(userId);
+		if (store) {
+			try {
+				await store.ensureUserExistsOnDisk();
+				return store;
+			} catch (err) {
+				stores.delete(userId);
+				throw err;
+			}
+		} else {
+			const userFolder = userDataInRootFolder(rootFolder, userId);
+			const store = await Store.make(
+				userFolder, userId, storageEventsSink,
+				writeBufferSize, readBufferSize
+			);
+			stores.set(userId, store);
+			return store;
+		}
+	}
+
+	function makeCurrentObjGetter(isRoot?: boolean): GetCurrentObj {
+		return async (userId: string, objId: string|null, header: boolean,
+				segsOffset: number, segsLimit: number|undefined) => {
+			if ((isRoot && objId) || (!isRoot && !objId)) {
+				throw new Error("Mixed object types' functions.");
+			}
+			const store = await getStore(userId);
+			return store.getCurrentObj(objId, header, segsOffset, segsLimit);
+		}
+	}
+
+	function makeArchivedObjGetter(isRoot?: boolean): GetArchivedObjVersion {
+		return async (userId: string, objId: string|null, version: number,
+				header: boolean, segsOffset: number,
+				segsLimit: number|undefined) => {
+			if ((isRoot && objId) || (!isRoot && !objId)) {
+				throw new Error("Mixed object types' functions.");
+			}
+			const store = await getStore(userId);
+			return store.getArchivedObjVersion(objId, version, header, segsOffset, segsLimit);
+		}
+	}
+
+	function makeObjSaver(isRoot: boolean): SaveNewObjVersion {
+		return async (userId: string, objId: string|null,
+				fstReq: PutObjFirstQueryOpts|undefined, diff: DiffInfo|undefined,
+				sndReq: PutObjSecondQueryOpts|undefined, bytesLen: number,
+				bytes: ReadableStream): Promise<string|undefined> => {
+			if ((isRoot && objId) || (!isRoot && !objId)) {
+				throw new Error("Mixed object types' functions.");
+			}
+			const store = await getStore(userId);
+			if (fstReq) {
+				return store.startSavingObjNewVersion(objId, diff,
+					bytes, bytesLen, fstReq);
+			} else if (sndReq) {
+				return store.continueSavingObjNewVersion(objId,
+					bytes, bytesLen, sndReq);
+			} else {
+				throw new Error(`Missing both request options`);
+			}
+		};
+	}
+
+	function makeTransactionCanceller(): CancelTransaction {
+		return async (userId: string, objId: string, transactionId?: string) => {
+			const store = await getStore(userId);
+			await store.cancelTransaction(objId, transactionId);
+		};
+	}
+
+	const factory: Factory = {
+
+		exists: async userId => {
+			try {
+				const store = await getStore(userId);
+				return true;
+			} catch (err) {
+				if (err !== SC.USER_UNKNOWN) { throw err; }
+				return false;
+			}
+		},
+
+		getSpaceQuota: async userId => {
+			const store = await getStore(userId);
+			return await store.getSpaceQuota();
+		},
+
+		getKeyDerivParams: async userId => {
+			const store = await getStore(userId);
+			return await store.getParam('key-deriv');
+		},
+		setKeyDerivParams: async (userId, keyParams) => {
+			const store = await getStore(userId);
+			return await store.setKeyDerivParams(keyParams, false);
+		},
+
+		getCurrentRootObj: makeCurrentObjGetter(true),
+		getCurrentObj: makeCurrentObjGetter(false),
+
+		getArchivedRootVersion: makeArchivedObjGetter(true),
+		getArchivedObjVersion: makeArchivedObjGetter(false),
+
+		saveNewRootVersion: makeObjSaver(true),
+		saveNewObjVersion: makeObjSaver(false),
+
+		cancelTransaction: makeTransactionCanceller(),
+
+		deleteCurrentObjVersion: async (userId, objId, version) => {
+			const store = await getStore(userId);
+			await store.deleteCurrentObjVer(objId, version);
+		},
+
+		archiveObjVersion: async (userId, objId, version) => {
+			const store = await getStore(userId);
+			await store.archiveCurrentObjVersion(objId, version);
+		},
+
+		getObjStatus: async (userId, objId) => {
+			const store = await getStore(userId);
+			return store.getObjStatus(objId);
+		},
+
+		deleteArchivedObjVersion: async (userId, objId, version) => {
+			const store = await getStore(userId);
+			await store.deleteArchivedObjVer(objId, version);
+		},
+
+		setStorageEventsSink(sink: EventsSink): void {
+			if (storageEventsSink) { throw new Error(
+				`Storage events sink is already set`); }
+			storageEventsSink = sink;
+		}
+
+	};
+	Object.freeze(factory);
+	return factory;
+}
+
+Object.freeze(exports);

package/ts-code/3nstorage/routes/owner/archive-obj-version.ts

@@ -0,0 +1,73 @@
+/*
+ Copyright (C) 2022, 2026 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
+ Foundation, either version 3 of the License, or (at your option) any later
+ version.
+ 
+ This program is distributed in the hope that it will be useful, but
+ WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+ See the GNU General Public License for more details.
+ 
+ You should have received a copy of the GNU General Public License along with
+ this program. If not, see <http://www.gnu.org/licenses/>.
+*/
+
+import { RequestHandler } from 'express';
+import { ArchiveObjCurrentVersion, MismatchedObjVerException, SC as storeSC } from '../../resources/users';
+import { archiveObj as api, ERR_SC, HTTP_HEADER } from '../../../lib-common/service-api/3nstorage/owner';
+import { Request } from '../../resources/sessions';
+
+const SC = api.SC;
+
+export function archiveCurrentObjVersion(
+	root: boolean, archiveObjVerFunc: ArchiveObjCurrentVersion
+): RequestHandler {
+	if ('function' !== typeof archiveObjVerFunc) { throw new TypeError(
+			"Given argument 'archiveObjVerFunc' must be function, but is not."); }
+
+	return async (req: Request, res, next) => {
+
+		const userId = req.session.params.userId;
+		const objId: string = (root ? null as any : req.params.objId);
+
+		const version = parseInt(req.query.ver as any);
+		if (isNaN(version) || (version < 1)) {
+			res.status(ERR_SC.malformed).send("Bad query parameters");
+			return;
+		}
+
+		try {
+			await archiveObjVerFunc(userId, objId, version);
+			res.status(SC.okPost).send();
+		} catch (err) {
+			if ("string" !== typeof err) {
+				if ((err as MismatchedObjVerException).type === 'mismatched-obj-ver') {
+					const rep: api.MismatchedObjVerReply = {
+						error: "Current object version doesn't match assumed one.",
+						current_version: (err as MismatchedObjVerException).current_version
+					};
+					res.set(HTTP_HEADER.objVersion, `${(err as MismatchedObjVerException).current_version}`);
+					res.status(api.SC.mismatchedObjVer).json(rep);
+				} else {
+					next(err);
+				}
+			} else if (err === storeSC.OBJ_UNKNOWN) {
+				res.status(SC.unknownObj).send(root ?
+					`Root object is not set.` :
+					`Object ${objId} is unknown.`);
+			} else if (err === storeSC.USER_UNKNOWN) {
+				res.status(ERR_SC.server).send(
+					"Recipient disappeared from the system.");
+				req.session.close();
+			} else {
+				next(new Error("Unhandled storage error code: "+err));
+			}
+		}
+
+	};
+};
+
+Object.freeze(exports);

package/ts-code/3nstorage/routes/owner/cancel-trans.ts

@@ -0,0 +1,58 @@
+/*
+ Copyright (C) 2015 - 2017, 2020, 2026 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
+ Foundation, either version 3 of the License, or (at your option) any later
+ version.
+ 
+ This program is distributed in the hope that it will be useful, but
+ WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+ See the GNU General Public License for more details.
+ 
+ You should have received a copy of the GNU General Public License along with
+ this program. If not, see <http://www.gnu.org/licenses/>.
+*/
+
+import { RequestHandler } from 'express';
+import { CancelTransaction, SC as storeSC } from '../../resources/users';
+import { cancelTransaction as api, ERR_SC } from '../../../lib-common/service-api/3nstorage/owner';
+import { Request } from '../../resources/sessions';
+
+export function cancelTransaction(
+	root: boolean, cancelTransFunc: CancelTransaction
+): RequestHandler {
+	if ('function' !== typeof cancelTransFunc) { throw new TypeError(
+			"Given argument 'cancelTransFunc' must be function, but is not."); }
+
+	return async (req: Request, res, next) => {
+
+		const userId = req.session.params.userId;
+		const objId: string = (root ? null as any : req.params.objId);
+		const transactionId: string = req.params.transactionId;
+
+		try {
+			await cancelTransFunc(userId, objId, ((transactionId === '-') ? undefined : transactionId));
+			res.status(api.SC.ok).send();
+		} catch (err) {
+			if ("string" !== typeof err) {
+				next(err);
+			} else if ((err === storeSC.TRANSACTION_UNKNOWN)
+			|| (err === storeSC.OBJ_UNKNOWN)
+			|| (err === storeSC.OBJ_VER_UNKNOWN)) {
+				res.status(api.SC.missing).send(
+					"Unknown transaction or object.");
+			} else if (err === storeSC.USER_UNKNOWN) {
+				res.status(ERR_SC.server).send(
+					"Recipient disappeared from the system.");
+				req.session.close();
+			} else {
+				next(new Error("Unhandled storage error code: "+err));
+			}
+		}
+
+	};
+};
+
+Object.freeze(exports);

package/ts-code/3nstorage/routes/owner/delete-obj.ts

@@ -0,0 +1,103 @@
+/*
+ Copyright (C) 2016, 2020, 2022, 2026 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
+ Foundation, either version 3 of the License, or (at your option) any later
+ version.
+ 
+ This program is distributed in the hope that it will be useful, but
+ WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+ See the GNU General Public License for more details.
+ 
+ You should have received a copy of the GNU General Public License along with
+ this program. If not, see <http://www.gnu.org/licenses/>.
+*/
+
+import { RequestHandler } from 'express';
+import { DeleteArchivedObjVersion, DeleteCurrentObjVersion, SC as storeSC } from '../../resources/users';
+import { ERR_SC, currentObj as api } from '../../../lib-common/service-api/3nstorage/owner';
+import { Request } from '../../resources/sessions';
+import { assert } from '../../../lib-common/assert';
+
+function deleteObj(
+	root: boolean, delCurrent: boolean,
+	deleteObjFunc: DeleteArchivedObjVersion|DeleteCurrentObjVersion
+): RequestHandler {
+	if ('function' !== typeof deleteObjFunc) { throw new TypeError(
+			"Given argument 'deleteObjFunc' must be function, but is not."); }
+	if (delCurrent) {
+		assert(!root);
+	}
+
+	return async (req: Request, res, next) => {
+
+		const userId = req.session.params.userId;
+		const objId: string|null = (root ? null : req.params.objId);
+
+		const ver = parseInt(req.query.ver as string);
+		let version: number|undefined;
+		if (isNaN(ver)) {
+			if (delCurrent) {
+				version = undefined
+			} else {
+				res.status(ERR_SC.malformed).send("Bad query parameters");
+				return;
+			}
+		} else {
+			if (ver < 1) {
+				res.status(ERR_SC.malformed).send("Bad query parameters");
+				return;
+			}
+			version = ver;
+		}
+
+		try {
+			if (delCurrent) {
+				await (deleteObjFunc as DeleteCurrentObjVersion)(
+					userId, objId!, version
+				);
+			} else {
+				await (deleteObjFunc as DeleteArchivedObjVersion)(
+					userId, objId, version!
+				);
+			}
+			res.status(api.SC.okDelete).send();
+		} catch (err) {
+			if ("string" !== typeof err) {
+				next(err);
+			} else if (err === storeSC.CONCURRENT_TRANSACTION) {
+				res.status(api.SC.concurrentTransaction).send(
+					`Object ${objId} is currently under a transaction.`);
+			} else if (err === storeSC.OBJ_UNKNOWN) {
+				res.status(api.SC.unknownObj).send(`Object ${objId} is unknown.`);
+			} else if (err === storeSC.OBJ_VER_UNKNOWN) {
+				res.status(api.SC.unknownObjVer).send(
+					`Object version ${version} is unknown.`);
+			} else if (err === storeSC.USER_UNKNOWN) {
+				res.status(ERR_SC.server).send(
+					"Recipient disappeared from the system.");
+				req.session.close();
+			} else {
+				next(new Error("Unhandled storage error code: "+err));
+			}
+		}
+		
+	};
+}
+
+export function deleteCurrentObjVer(
+	deleteObjFunc: DeleteCurrentObjVersion
+): RequestHandler {
+	return deleteObj(false, true, deleteObjFunc);
+}
+
+export function deleteArchivedObjVer(
+	root: boolean, deleteObjFunc: DeleteArchivedObjVersion
+): RequestHandler {
+	return deleteObj(root, false, deleteObjFunc);
+}
+
+
+Object.freeze(exports);

package/ts-code/3nstorage/routes/owner/get-archived-obj-ver.ts

@@ -0,0 +1,111 @@
+/*
+ Copyright (C) 2017, 2020 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
+ Foundation, either version 3 of the License, or (at your option) any later
+ version.
+ 
+ This program is distributed in the hope that it will be useful, but
+ WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+ See the GNU General Public License for more details.
+ 
+ You should have received a copy of the GNU General Public License along with
+ this program. If not, see <http://www.gnu.org/licenses/>.
+*/
+
+import { RequestHandler } from 'express';
+import { GetArchivedObjVersion, SC as storeSC } from '../../resources/users';
+import { GetObjQueryOpts, ERR_SC, HTTP_HEADER, BIN_TYPE, archivedObjVersion as api } from '../../../lib-common/service-api/3nstorage/owner';
+import { Request } from '../../resources/sessions';
+import { errWithCause } from '../../../lib-common/exceptions/error';
+import { EMPTY_BUFFER } from '../../../lib-common/buffer-utils';
+
+function extractQueryOptions(req: Request): undefined|{
+	header: boolean; limit: number|undefined; ofs: number; ver: number
+} {
+	// query fields are string or undefined, yet, type info helps the show
+	const query: GetObjQueryOpts = req.query;
+
+	const header = ((query.header as any) === 'true');
+
+	const ofs = (query.ofs ? parseInt(query.ofs as any) : 0);
+	if (isNaN(ofs) ||
+			(ofs < 0) ||
+			(header && (ofs > 0))) { return; }
+
+	const limit = (query.limit ? parseInt(query.limit as any) : undefined);
+	if (limit !== undefined) {
+		if (isNaN(limit) ||
+				(limit < 0) ||
+				(!header && (limit === 0))) { return; }
+	}
+
+	let ver = parseInt(query.ver as any);
+	if (isNaN(ver) || (ver < 1)) { return; }
+
+	return { header, limit, ofs, ver };
+}
+
+export function getArchivedObjVersion(
+	root: boolean, getArchivedObjFunc: GetArchivedObjVersion
+): RequestHandler {
+	if ('function' !== typeof getArchivedObjFunc) { throw new TypeError(
+			"Given argument 'getArchivedObjFunc' must be function, but is not."); }
+
+	return async (req: Request, res, next) => {
+		
+		const userId = req.session.params.userId;
+		const objId: string = (root ? null as any : req.params.objId);
+		
+		const opts = extractQueryOptions(req);
+		if (!opts) {
+			res.status(ERR_SC.malformed).send("Bad query parameters");
+			return;
+		}
+		
+		try {
+			const reader = await getArchivedObjFunc(userId, objId, opts.ver,
+				opts.header, opts.ofs, opts.limit);
+			res.status(api.SC.okGet);
+			res.set(HTTP_HEADER.contentType, BIN_TYPE);
+			res.set(HTTP_HEADER.contentLength, `${reader.len}`);
+			if (opts.header) {
+				res.set(HTTP_HEADER.objHeaderLength, `${reader.headerLen}`);
+			}
+			res.set(HTTP_HEADER.objSegmentsLength, `${reader.segsLen}`);
+			if (reader.len > 0) {
+				try {
+					await reader.pipe!(res);
+				} catch (err) {
+					console.error(errWithCause(err, `Wasn't able to complete sending segments due to error in piping`));
+				} finally {
+					res.end();
+				}
+			} else {
+				res.send(EMPTY_BUFFER);
+			}
+		} catch (err) {
+			if ("string" !== typeof err) {
+				next(err);
+			} else if (err === storeSC.OBJ_UNKNOWN) {
+				res.status(api.SC.unknownObj).send(objId ?
+					`Object ${objId}is unknown.` : `Root object is not set`);
+			} else if (err === storeSC.OBJ_VER_UNKNOWN) {
+				res.status(api.SC.unknownObjVer).send(objId ?
+					`Object ${objId}, version ${opts.ver} is unknown.` :
+					`Root object version ${opts.ver} is not known.`);
+			} else if (err === storeSC.USER_UNKNOWN) {
+				res.status(ERR_SC.server).send(
+					`Recipient disappeared from the system.`);
+				req.session.close();
+			} else {
+				next(new Error(`Unhandled storage error code: ${err}`));
+			}
+		}
+		
+	};
+};
+
+Object.freeze(exports);