@solid/community-server
Version:
Community Solid Server: an open and modular implementation of the Solid specifications
96 lines (95 loc) • 4.39 kB
TypeScript
import type { ResourceIdentifier } from '../../http/representation/ResourceIdentifier';
import type { Finalizable } from '../../init/final/Finalizable';
import type { Initializable } from '../../init/Initializable';
import type { AttemptSettings } from '../LockUtils';
import type { ResourceLocker } from './ResourceLocker';
/**
* Argument interface of the FileSystemResourceLocker constructor.
*/
interface FileSystemResourceLockerArgs {
/** The root filepath of where the server is allowed to write files */
rootFilePath: string;
/**
* The path to the directory where locks will be stored (relative to rootFilePath)
* _[default is `/.internal/locks`]_
*/
lockDirectory?: string;
/** Custom settings concerning retrying locks */
attemptSettings?: AttemptSettings;
/**
* Throws an error when a lock is compromised, instead of logging an error.
*/
throwOnCompromise?: boolean;
}
/**
* A resource locker making use of the [proper-lockfile](https://www.npmjs.com/package/proper-lockfile) library.
* Note that no locks are kept in memory, thus this is considered thread- and process-safe.
* While it stores the actual locks on disk, it also tracks them in memory for when they need to be released.
* This means only the worker thread that acquired a lock can release it again,
* making this implementation unusable in combination with a wrapping read/write lock implementation.
*
* This **proper-lockfile** library has its own retry mechanism for the operations, since a lock/unlock call will
* either resolve successfully or reject immediately with the causing error. The retry function of the library
* however will be ignored and replaced by our own LockUtils' {@link retryFunction} function.
*/
export declare class FileSystemResourceLocker implements ResourceLocker, Initializable, Finalizable {
protected readonly logger: import("global-logger-factory").Logger<unknown>;
private readonly attemptSettings;
private readonly lockOptions;
private readonly throwOnCompromise?;
/** Folder that stores the locks */
private readonly lockFolder;
private finalized;
/**
* Create a new FileSystemResourceLocker
*
* @param args - Configures the locker using the specified FileSystemResourceLockerArgs instance.
*/
constructor(args: FileSystemResourceLockerArgs);
/**
* Wrapper function for all (un)lock operations. Any errors coming from the `fn()` will be swallowed.
* Only `ENOTACQUIRED` errors wills be thrown (trying to release lock that didn't exist).
* This wrapper returns undefined because {@link retryFunction} expects that when a retry needs to happen.
*
* @param fn - The function reference to swallow errors from.
*
* @returns Boolean or undefined.
*/
private swallowErrors;
acquire(identifier: ResourceIdentifier): Promise<void>;
release(identifier: ResourceIdentifier): Promise<void>;
/**
* Map the identifier path to a unique path inside the {@link lockFolder}.
*
* @param identifier - ResourceIdentifier to generate (Un)LockOptions for.
*
* @returns Full path.
*/
private toLockfilePath;
/**
* Generate LockOptions or UnlockOptions depending on the type of defauls given.
* A custom lockFilePath mapping strategy will be used.
*
* @param identifier - ResourceIdentifier to generate (Un)LockOptions for
* @param defaults - The default options. (lockFilePath will get overwritten)
*
* @returns LockOptions or UnlockOptions
*/
private generateOptions;
/**
* Initializer method to be executed on server start. This makes sure that no pre-existing (dangling) locks
* remain on disk, so that request will not be blocked because a lock was acquired in the previous server instance.
*
* NOTE: this also removes locks created by the GreedyReadWriteLocker.
* (See issue: https://github.com/CommunitySolidServer/CommunitySolidServer/issues/1358)
*/
initialize(): Promise<void>;
finalize(): Promise<void>;
/**
* This function is used to override the proper-lock onCompromised function.
* Once the locker was finalized, it will log the provided error instead of throwing it
* This allows for a clean shutdown procedure.
*/
private customOnCompromised;
}
export {};