Mirroristas/CommunitySolidServer
2
0
Fork 0
mirror of https://github.com/CommunitySolidServer/CommunitySolidServer.git synced 2024-10-03 14:55:10 +00:00
Code Issues Packages Projects Releases Wiki Activity

refactor: Enable jsdoc/tag-lines and jsdoc/sort-tags rules

Browse Source
This commit is contained in:
Joachim Van Herwegen 2024-03-14 09:29:56 +01:00
parent 3e59aa4b55
commit 65bf2bd34e
89 changed files with 276 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
eslint/general.js
View File

@ -51,8 +51,16 @@ module.exports = {
'import/extensions': 'error',
'import/no-extraneous-dependencies': 'error',
'jsdoc/tag-lines': [ 'error', 'any', { startLines: 1 }],
'jsdoc/no-multi-asterisks': [ 'error', { allowWhitespace: true }],
'jsdoc/no-types': 'error',
'jsdoc/sort-tags': [ 'error', {
tagSequence: [
{ tags: [ 'param' ]},
{ tags: [ 'returns' ]},
{ tags: [ 'throws' ]},
],
}],
'jsdoc/valid-types': 'error',
'node/prefer-global/buffer': [ 'error', 'always' ],

2
scripts/finalizeRelease.ts
View File

@ -27,7 +27,9 @@ async function commitAndTag(): Promise<void> {
/**
* Prompts the user for input
*
* @param query - A string to prompt the user
*
* @returns Promise with the input of the user
*/
async function waitForUserInput(query: string): Promise<string> {

4
scripts/formatChangelog.ts
View File

@ -14,7 +14,9 @@ import { readFile, writeFile } from 'fs-extra';
/**
* Capitalize all list entries
*
* @param input - String to search/replace
*
* @returns Promise with output string
*/
async function capitalizeListEntries(input: string): Promise<string> {
@ -31,7 +33,9 @@ function endProcess(error: Error): never {
/**
* Main function for changelog formatting
*
* @param filePath - Path to the changelog file
*
* @returns Promise
*/
async function formatChangelog(filePath: string): Promise<void> {

3
scripts/upgradeConfig.ts
View File

@ -18,6 +18,7 @@ import { joinFilePath, readPackageJson } from '../src/util/PathUtil';
/**
* Search and replace the version of a component with given name
*
* @param filePath - File to search/replace
* @param regex - RegExp matching the component reference
* @param version - Semantic version to change to
@ -31,8 +32,10 @@ async function replaceComponentVersion(filePath: string, regex: RegExp, version:
/**
* Recursive search for files that match a given Regex
*
* @param path - Path of folder to start search in
* @param regex - A regular expression to which file names will be matched
*
* @returns Promise with all file pathss
*/
async function getFilePaths(path: string, regex: RegExp): Promise<string[]> {

1
src/authorization/AcpReader.ts
View File

@ -65,6 +65,7 @@ export class AcpReader extends PermissionReader {
/**
* Generates the allowed permissions.
*
* @param target - Target to generate permissions for.
* @param credentials - Credentials that are trying to access the resource.
* @param resourceCache - Cache used to store ACR data.

5
src/authorization/AcpUtil.ts
View File

@ -27,6 +27,7 @@ function getObjectValues(data: Store, subject: Term, predicate: NamedNode): stri
/**
* Finds the {@link IMatcher} with the given identifier in the given dataset.
*
* @param data - Dataset to look in.
* @param matcher - Identifier of the matcher.
*/
@ -42,6 +43,7 @@ export function getMatcher(data: Store, matcher: Term): IMatcher {
/**
* Finds the {@link IPolicy} with the given identifier in the given dataset.
*
* @param data - Dataset to look in.
* @param policy - Identifier of the policy.
*/
@ -58,6 +60,7 @@ export function getPolicy(data: Store, policy: Term): IPolicy {
/**
* Finds the {@link IAccessControl} with the given identifier in the given dataset.
*
* @param data - Dataset to look in.
* @param accessControl - Identifier of the access control.
*/
@ -71,6 +74,7 @@ export function getAccessControl(data: Store, accessControl: Term): IAccessContr
/**
* Finds the {@link IAccessControlResource} with the given identifier in the given dataset.
*
* @param data - Dataset to look in.
* @param acr - Identifier of the access control resource.
*/
@ -88,6 +92,7 @@ export function getAccessControlResource(data: Store, acr: Term): IAccessControl
/**
* Finds all {@link IAccessControlledResource} in the given dataset.
*
* @param data - Dataset to look in.
*/
export function* getAccessControlledResources(data: Store): Iterable<IAccessControlledResource> {

3
src/authorization/PermissionBasedAuthorizer.ts
View File

@ -24,6 +24,7 @@ export class PermissionBasedAuthorizer extends Authorizer {
/**
* The existence of the target resource determines the output status code for certain situations.
* The provided {@link ResourceSet} will be used for that.
*
* @param resourceSet - {@link ResourceSet} that can verify the target resource existence.
*/
public constructor(resourceSet: ResourceSet) {
@ -77,6 +78,7 @@ export class PermissionBasedAuthorizer extends Authorizer {
* Ensures that at least one of the credentials provides permissions for the given mode.
* Throws a {@link ForbiddenHttpError} or {@link UnauthorizedHttpError} depending on the credentials
* if access is not allowed.
*
* @param credentials - Credentials that require access.
* @param permissionSet - PermissionSet describing the available permissions of the credentials.
* @param mode - Which mode is requested.
@ -98,6 +100,7 @@ export class PermissionBasedAuthorizer extends Authorizer {
/**
* Checks whether the agent is authenticated (logged in) or not (public/anonymous).
*
* @param credentials - Credentials to check.
*/
private isAuthenticated(credentials: Credentials): boolean {

2
src/authorization/WebAclReader.ts
View File

@ -96,6 +96,7 @@ export class WebAclReader extends PermissionReader {
/**
* Determines the available permissions for the given credentials.
*
* @param acl - Store containing all relevant authorization triples.
* @param credentials - Credentials to find the permissions for.
*/
@ -223,6 +224,7 @@ export class WebAclReader extends PermissionReader {
/**
* Extracts all rules from the store that are relevant for the given target,
* based on either the `acl:accessTo` or `acl:default` predicates.
*
* @param store - Store to filter.
* @param target - The identifier of which the acl rules need to be known.
* @param directAcl - If the store contains triples from the direct acl resource of the target or not.

1
src/authorization/access/AgentGroupAccessChecker.ts
View File

@ -29,6 +29,7 @@ export class AgentGroupAccessChecker extends AccessChecker {
/**
* Checks if the given agent is member of a given vCard group.
*
* @param webId - WebID of the agent that needs access.
* @param group - URL of the vCard group that needs to be checked.
*

1
src/authorization/permissions/IntermediateCreateExtractor.ts
View File

@ -19,6 +19,7 @@ export class IntermediateCreateExtractor extends ModesExtractor {
/**
* Certain permissions depend on the existence of the target resource.
* The provided {@link ResourceSet} will be used for that.
*
* @param resourceSet - {@link ResourceSet} that can verify the target resource existence.
* @param strategy - {@link IdentifierStrategy} that will be used to determine parent containers.
* @param source - The source {@link ModesExtractor}.

1
src/authorization/permissions/MethodModesExtractor.ts
View File

@ -20,6 +20,7 @@ export class MethodModesExtractor extends ModesExtractor {
/**
* Certain permissions depend on the existence of the target resource.
* The provided {@link ResourceSet} will be used for that.
*
* @param resourceSet - {@link ResourceSet} that can verify the target resource existence.
*/
public constructor(resourceSet: ResourceSet) {

1
src/authorization/permissions/N3PatchModesExtractor.ts
View File

@ -22,6 +22,7 @@ export class N3PatchModesExtractor extends ModesExtractor {
/**
* Certain permissions depend on the existence of the target resource.
* The provided {@link ResourceSet} will be used for that.
*
* @param resourceSet - {@link ResourceSet} that can verify the target resource existence.
*/
public constructor(resourceSet: ResourceSet) {

1
src/authorization/permissions/SparqlUpdateModesExtractor.ts
View File

@ -20,6 +20,7 @@ export class SparqlUpdateModesExtractor extends ModesExtractor {
/**
* Certain permissions depend on the existence of the target resource.
* The provided {@link ResourceSet} will be used for that.
*
* @param resourceSet - {@link ResourceSet} that can verify the target resource existence.
*/
public constructor(resourceSet: ResourceSet) {

2
src/http/auxiliary/AuxiliaryIdentifierStrategy.ts
View File

@ -31,6 +31,7 @@ export interface AuxiliaryIdentifierStrategy {
* Checks if the input identifier corresponds to an auxiliary resource.
* This does not check if that auxiliary resource exists,
* only if the identifier indicates that there could be an auxiliary resource there.
*
* @param identifier - Identifier to check.
*
* @returns true if the input identifier points to an auxiliary resource.
@ -40,6 +41,7 @@ export interface AuxiliaryIdentifierStrategy {
/**
* Returns the identifier of the resource which this auxiliary resource is referring to.
* This does not guarantee that this resource exists.
*
* @param identifier - Identifier of the auxiliary resource.
*
* @returns The ResourceIdentifier of the subject resource.

3
src/http/auxiliary/AuxiliaryStrategy.ts
View File

@ -11,6 +11,7 @@ import type { AuxiliaryIdentifierStrategy } from './AuxiliaryIdentifierStrategy'
export interface AuxiliaryStrategy extends AuxiliaryIdentifierStrategy {
/**
* Whether this auxiliary resources uses its own authorization instead of the subject resource authorization.
*
* @param identifier - Identifier of the auxiliary resource.
*/
usesOwnAuthorization: (identifier: ResourceIdentifier) => boolean;
@ -18,6 +19,7 @@ export interface AuxiliaryStrategy extends AuxiliaryIdentifierStrategy {
/**
* Whether the root storage container requires this auxiliary resource to be present.
* If yes, this means they can't be deleted individually from such a container.
*
* @param identifier - Identifier of the auxiliary resource.
*/
isRequiredInRoot: (identifier: ResourceIdentifier) => boolean;
@ -42,6 +44,7 @@ export interface AuxiliaryStrategy extends AuxiliaryIdentifierStrategy {
/**
* Validates if the representation contains valid data for an auxiliary resource.
* Should throw an error in case the data is invalid.
*
* @param identifier - Identifier of the auxiliary resource.
* @param representation - Representation of the auxiliary resource.
*/

3
src/http/input/metadata/LinkRelParser.ts
View File

@ -50,7 +50,9 @@ export class LinkRelObject {
/**
* Checks whether the object can be added to the metadata
*
* @param object - The link target.
*
* @returns a boolean to indicate whether it can be added to the metadata or not
*/
private objectAllowed(object: string): boolean {
@ -59,6 +61,7 @@ export class LinkRelObject {
/**
* Adds the object to the metadata when it is allowed
*
* @param object - The link target.
* @param metadata - Metadata of the resource.
* @param logger - Logger

12
src/http/representation/RepresentationMetadata.ts
View File

@ -26,6 +26,7 @@ const cachedNamedNodes: Record<string, NamedNode> = {};
* Converts the incoming name (URI or shorthand) to a named node.
* The generated terms get cached to reduce the number of created nodes,
* so only use this for internal constants!
*
* @param name - Predicate to potentially transform.
*/
function toCachedNamedNode(name: string): NamedNode {
@ -167,6 +168,7 @@ export class RepresentationMetadata {
/**
* Helper function to import all entries from the given metadata.
* If the new metadata has a different identifier the internal one will be updated.
*
* @param metadata - Metadata to import.
*/
public setMetadata(metadata: RepresentationMetadata): this {
@ -235,6 +237,7 @@ export class RepresentationMetadata {
/**
* Adds a value linked to the identifier. Strings get converted to literals.
*
* @param predicate - Predicate linking identifier to value.
* @param object - Value(s) to add.
* @param graph - Optional graph of where to add the values to.
@ -245,6 +248,7 @@ export class RepresentationMetadata {
/**
* Removes the given value from the metadata. Strings get converted to literals.
*
* @param predicate - Predicate linking identifier to value.
* @param object - Value(s) to remove.
* @param graph - Optional graph of where to remove the values from.
@ -271,6 +275,7 @@ export class RepresentationMetadata {
/**
* Removes all values linked through the given predicate.
*
* @param predicate - Predicate to remove.
* @param graph - Optional graph where to remove from.
*/
@ -300,6 +305,7 @@ export class RepresentationMetadata {
/**
* Finds all object values matching the given predicate and/or graph.
*
* @param predicate - Optional predicate to get the values for.
* @param graph - Optional graph where to get from.
*
@ -314,10 +320,10 @@ export class RepresentationMetadata {
* @param predicate - Predicate to get the value for.
* @param graph - Optional graph where the triple should be found.
*
* @returns The corresponding value. Undefined if there is no match
*
* @throws Error
* If there are multiple matching values.
*
* @returns The corresponding value. Undefined if there is no match
*/
public get(predicate: NamedNode, graph?: MetadataGraph): Term | undefined {
const terms = this.getAll(predicate, graph);
@ -337,6 +343,7 @@ export class RepresentationMetadata {
/**
* Sets the value for the given predicate, removing all other instances.
* In case the object is undefined this is identical to `removeAll(predicate)`.
*
* @param predicate - Predicate linking to the value.
* @param object - Value(s) to set.
* @param graph - Optional graph where the triple should be stored.
@ -383,6 +390,7 @@ export class RepresentationMetadata {
/**
* Parse the internal RDF structure to retrieve the Record with ContentType Parameters.
*
* @returns A {@link ContentType} object containing the value and optional parameters if there is one.
*/
private getContentType(): ContentType | undefined {

2
src/identity/interaction/InteractionUtil.ts
View File

@ -49,6 +49,7 @@ export type AccountInteractionResults = { [ACCOUNT_PROMPT]?: string } & Interact
/**
* Updates the `oidcInteraction` object with the necessary data in case a prompt gets updated.
*
* @param oidcInteraction - Interaction to update.
* @param result - New data to add to the interaction.
* @param mergeWithLastSubmission - If this new data needs to be merged with already existing data in the interaction.
@ -72,6 +73,7 @@ export async function finishInteraction(
* Removes the WebID, the `accountId`, from the OIDC session object,
* allowing us to replace it with a new value.
* If there is no session in the Interaction, nothing will happen.
*
* @param provider - The OIDC provider.
* @param oidcInteraction - The current interaction.
*/

2
src/identity/interaction/account/util/AccountStore.ts
View File

@ -20,6 +20,7 @@ export interface AccountStore {
/**
* Finds the setting of the account with the given identifier.
*
* @param id - The account identifier.
* @param setting - The setting to find the value of.
*/
@ -27,6 +28,7 @@ export interface AccountStore {
/**
* Updates the settings for the account with the given identifier to the new values.
*
* @param id - The account identifier.
* @param setting - The setting to update.
* @param value - The new value for the setting.

4
src/identity/interaction/account/util/CookieStore.ts
View File

@ -5,6 +5,7 @@ export interface CookieStore {
/**
* Generates and stores a new cookie for the given accountId.
* This does not replace previously generated cookies.
*
* @param accountId - Account to create a cookie for.
*
* @returns The generated cookie.
@ -13,18 +14,21 @@ export interface CookieStore {
/**
* Return the accountID associated with the given cookie.
*
* @param cookie - Cookie to find the account for.
*/
get: (cookie: string) => Promise<string | undefined>;
/**
* Refreshes the cookie expiration and returns when it will expire if the cookie exists.
*
* @param cookie - Cookie to refresh.
*/
refresh: (cookie: string) => Promise<Date | undefined>;
/**
* Deletes the given cookie.
*
* @param cookie - Cookie to delete.
*/
delete: (cookie: string) => Promise<boolean>;

2
src/identity/interaction/login/ResolveLoginHandler.ts
View File

@ -82,6 +82,7 @@ export abstract class ResolveLoginHandler extends JsonInteractionHandler {
/**
* Updates the account setting that determines if the login status needs to be remembered.
*
* @param accountId - ID of the account.
* @param remember - If the account should be remembered or not. The setting will not be updated if this is undefined.
*/
@ -95,6 +96,7 @@ export abstract class ResolveLoginHandler extends JsonInteractionHandler {
/**
* Takes the necessary steps to log a user in.
*
* @param input - Same input that was passed to the handle function.
*/
public abstract login(input: JsonInteractionHandlerInput): Promise<JsonRepresentation<LoginOutputType>>;

5
src/identity/interaction/password/util/ForgotPasswordStore.ts
View File

@ -6,7 +6,9 @@ export interface ForgotPasswordStore {
* Creates a Forgot Password Confirmation Record. This will be to remember that
* a user has made a request to reset a password. Throws an error if the email doesn't
* exist.
*
* @param id - ID of the email/password login object.
*
* @returns The record id. This should be included in the reset password link.
*/
generate: (id: string) => Promise<string>;
@ -14,13 +16,16 @@ export interface ForgotPasswordStore {
/**
* Gets the email associated with the forgot password confirmation record
* or undefined if it's not present.
*
* @param recordId - The record id retrieved from the link.
*
* @returns The user's email.
*/
get: (recordId: string) => Promise<string | undefined>;
/**
* Deletes the Forgot Password Confirmation Record.
*
* @param recordId - The record id of the forgot password confirmation record.
*/
delete: (recordId: string) => Promise<boolean>;

1
src/identity/storage/ClientIdAdapterFactory.ts
View File

@ -81,6 +81,7 @@ export class ClientIdAdapter extends PassthroughAdapter {
/**
* Parses RDF data found at a Client ID.
*
* @param data - Raw data from the Client ID.
* @param id - The actual Client ID.
* @param response - Response object from the request.

1
src/init/AppRunner.ts
View File

@ -203,6 +203,7 @@ export class AppRunner {
/**
* Retrieves settings from package.json or configuration file when
* part of an npm project.
*
* @returns The settings defined in the configuration file
*/
public async getPackageSettings(): Promise<undefined | Record<string, unknown>> {

1
src/init/ConfigPodInitializer.ts
View File

@ -14,6 +14,7 @@ import { Initializer } from './Initializer';
* Part of the dynamic pod creation.
* Reads the contents from the configuration storage, uses those values to instantiate ResourceStores,
* and then adds them to the routing storage.
*
* @see {@link ConfigPodManager}, {@link TemplatedPodGenerator}, {@link BaseUrlRouterRule}
*/
export class ConfigPodInitializer extends Initializer {

5
src/init/cluster/ClusterManager.ts
View File

@ -18,7 +18,9 @@ enum ClusterMode {
/**
* Convert workers amount to {@link ClusterMode}
*
* @param workers - Amount of workers
*
* @returns ClusterMode enum value
*/
function toClusterMode(workers: number): ClusterMode {
@ -92,6 +94,7 @@ export class ClusterManager {
/**
* Check whether the CSS server was booted in single threaded mode.
*
* @returns True is single threaded.
*/
public isSingleThreaded(): boolean {
@ -100,6 +103,7 @@ export class ClusterManager {
/**
* Whether the calling process is the primary process.
*
* @returns True if primary
*/
public isPrimary(): boolean {
@ -108,6 +112,7 @@ export class ClusterManager {
/**
* Whether the calling process is a worker process.
*
* @returns True if worker
*/
public isWorker(): boolean {

3
src/init/cluster/SingleThreaded.ts
View File

@ -11,8 +11,10 @@ export interface SingleThreaded {}
/**
* Convert an exported interface name to the properly expected Components.js type URI.
*
* @param componentsManager - The currently used ComponentsManager
* @param interfaceName - An interface name
*
* @returns A Components.js type URI
*/
export async function toComponentsJsType<T>(componentsManager: ComponentsManager<T>, interfaceName: string):
@ -38,6 +40,7 @@ Promise<string> {
/**
* Will list class names of components instantiated implementing the {@link SingleThreaded}
* interface while the application is being run in multithreaded mode.
*
* @param componentsManager - The componentsManager being used to set up the application
*/
export async function listSingleThreadedComponents<T>(componentsManager: ComponentsManager<T>): Promise<string[]> {

1
src/logging/LogUtil.ts
View File

@ -42,6 +42,7 @@ export function getLoggerFor(loggable: string | Instance): Logger {
/**
* Sets the global logger factory.
* This causes loggers created by {@link getLoggerFor} to delegate to a logger from the given factory.
*
* @param loggerFactory - A logger factory.
*/
export function setGlobalLoggerFactory(loggerFactory: LoggerFactory): void {

8
src/logging/Logger.ts
View File

@ -17,6 +17,7 @@ export interface SimpleLogger {
/**
* Log the given message at the given level.
* If the internal level is higher than the given level, the message may be voided.
*
* @param level - The level to log at.
* @param message - The message to log.
* @param meta - Optional metadata to include in the log message.
@ -33,6 +34,7 @@ export interface Logger extends SimpleLogger {
/**
* Log the given message at the given level.
* If the internal level is higher than the given level, the message may be voided.
*
* @param level - The level to log at.
* @param message - The message to log.
* @param meta - Optional metadata to include in the log message.
@ -41,6 +43,7 @@ export interface Logger extends SimpleLogger {
/**
* Log a message at the 'error' level.
*
* @param message - The message to log.
* @param meta - Optional metadata to include in the log message.
*/
@ -48,6 +51,7 @@ export interface Logger extends SimpleLogger {
/**
* Log a message at the 'warn' level.
*
* @param message - The message to log.
* @param meta - Optional metadata to include in the log message.
*/
@ -55,6 +59,7 @@ export interface Logger extends SimpleLogger {
/**
* Log a message at the 'info' level.
*
* @param message - The message to log.
* @param meta - Optional metadata to include in the log message.
*/
@ -62,6 +67,7 @@ export interface Logger extends SimpleLogger {
/**
* Log a message at the 'verbose' level.
*
* @param message - The message to log.
* @param meta - Optional metadata to include in the log message.
*/
@ -69,6 +75,7 @@ export interface Logger extends SimpleLogger {
/**
* Log a message at the 'debug' level.
*
* @param message - The message to log.
* @param meta - Optional metadata to include in the log message.
*/
@ -76,6 +83,7 @@ export interface Logger extends SimpleLogger {
/**
* Log a message at the 'silly' level.
*
* @param message - The message to log.
* @param meta - Optional metadata to include in the log message.
*/

1
src/logging/LoggerFactory.ts
View File

@ -6,6 +6,7 @@ import type { Logger } from './Logger';
export interface LoggerFactory {
/**
* Create a logger instance for the given label.
*
* @param label - A label that is used to identify the given logger.
*/
createLogger: (label: string) => Logger;

1
src/pods/PodManager.ts
View File

@ -7,6 +7,7 @@ import type { PodSettings } from './settings/PodSettings';
export interface PodManager {
/**
* Creates a pod for the given settings.
*
* @param settings - Settings describing the pod.
* @param overwrite - If the creation should proceed if there already is a resource there.
*/

1
src/pods/generate/BaseComponentsJsFactory.ts
View File

@ -29,6 +29,7 @@ export class BaseComponentsJsFactory implements ComponentsJsFactory {
/**
* Calls Components.js to instantiate a new object.
*
* @param configPath - Location of the config to instantiate.
* @param componentIri - Iri of the object in the config that will be the result.
* @param variables - Variables to send to Components.js

1
src/pods/generate/ComponentsJsFactory.ts
View File

@ -4,6 +4,7 @@
export interface ComponentsJsFactory {
/**
* Instantiates a new object using Components.js.
*
* @param configPath - Location of the config to instantiate.
* @param componentIri - Iri of the object in the config that will be the result.
* @param variables - Variables to send to Components.js

1
src/pods/generate/GenerateUtil.ts
View File

@ -4,6 +4,7 @@ import type { ResourcesGenerator } from './ResourcesGenerator';
/**
* Generates resources with the given generator and adds them to the given store.
*
* @param settings - Settings from which the pod is being created.
* @param generator - Generator to be used.
* @param store - Store to be updated.

1
src/pods/generate/ResourcesGenerator.ts
View File

@ -15,6 +15,7 @@ export interface ResourcesGenerator {
/**
* Generates resources with the given options.
* The output Iterable should be sorted so that containers always appear before their contents.
*
* @param location - Base identifier.
* @param options - Options that can be used when generating resources.
*

1
src/pods/generate/TemplatedResourcesGenerator.ts
View File

@ -11,6 +11,7 @@ export interface TemplatedResourcesGenerator {
/**
* Generates resources with the given options, based on the given template folder.
* The output Iterable should be sorted so that containers always appear before their contents.
*
* @param templateFolder - Folder where the templates are located.
* @param location - Base identifier.
* @param options - Options that can be used when generating resources.

1
src/server/middleware/StaticAssetHandler.ts
View File

@ -39,6 +39,7 @@ export class StaticAssetHandler extends HttpHandler {
/**
* Creates a handler for the provided static resources.
*
* @param assets - A list of {@link StaticAssetEntry}.
* @param baseUrl - The base URL of the server.
* @param options - Specific options.

5
src/server/notifications/NotificationChannelStorage.ts
View File

@ -11,6 +11,7 @@ export interface NotificationChannelStorage {
/**
* Returns the requested channel.
* `undefined` if no match was found or if the notification channel expired.
*
* @param id - The identifier of the notification channel.
*/
get: (id: string) => Promise<NotificationChannel | undefined>;
@ -18,12 +19,14 @@ export interface NotificationChannelStorage {
/**
* Returns the identifiers of all notification channel entries that have the given identifier as their topic.
* The identifiers can potentially correspond to expired channels.
*
* @param topic - The identifier that is the topic.
*/
getAll: (topic: ResourceIdentifier) => Promise<string[]>;
/**
* Adds the given channel to the storage.
*
* @param channel - Channel to add.
*/
add: (channel: NotificationChannel) => Promise<void>;
@ -31,6 +34,7 @@ export interface NotificationChannelStorage {
/**
* Updates the given notification channel.
* The `id` and the `topic` can not be updated.
*
* @param channel - The channel to update.
*/
update: (channel: NotificationChannel) => Promise<void>;
@ -38,6 +42,7 @@ export interface NotificationChannelStorage {
/**
* Deletes the given notification channel from the storage.
* Returns true if the channel existed.
*
* @param id - The identifier of the notification channel
*/
delete: (id: string) => Promise<boolean>;

4
src/server/notifications/NotificationChannelType.ts
View File

@ -31,6 +31,7 @@ export interface NotificationChannelType {
/**
* Validate and convert the input quads into a {@link NotificationChannel}.
*
* @param data - The input quads.
* @param credentials - The credentials of the agent doing the request.
*/
@ -38,12 +39,14 @@ export interface NotificationChannelType {
/**
* Converts a {@link NotificationChannel} to a serialized JSON-LD representation.
*
* @param channel - The notification channel to serialize.
*/
toJsonLd: (channel: NotificationChannel) => Promise<Record<string, unknown>>;
/**
* Determines which modes are required to allow the given notification channel.
*
* @param channel - The notification channel to verify.
*
* @returns The required modes.
@ -53,6 +56,7 @@ export interface NotificationChannelType {
/**
* This function will be called after the serialized channel is sent back as a response,
* allowing for any final actions that need to happen.
*
* @param channel - The notification channel that is completed.
*/
completeChannel: (channel: NotificationChannel) => Promise<void>;

1
src/server/notifications/WebSocketChannel2023/WebSocket2023Util.ts
View File

@ -3,6 +3,7 @@ import { BadRequestHttpError } from '../../../util/errors/BadRequestHttpError';
/**
* Generates a WebSocket URL by converting an HTTP(S) URL into a WS(S) URL.
*
* @param id - The identifier of the channel. Needs to be a URL.
*/
export function generateWebSocketUrl(id: string): string {

1
src/server/util/RedirectingHttpHandler.ts
View File

@ -37,6 +37,7 @@ export class RedirectingHttpHandler extends HttpHandler {
/**
* Creates a handler for the provided redirects.
*
* @param redirects - A mapping between URL patterns.
* @param baseUrl - Base URL of the server.
* @param targetExtractor - To extract the target from the request.

9
src/storage/DataAccessorBasedStore.ts
View File

@ -376,6 +376,7 @@ export class DataAccessorBasedStore implements ResourceStore {
*
* First the identifier gets requested and if no result is found
* the identifier with differing trailing slash is requested.
*
* @param identifier - Identifier that needs to be checked.
*/
protected async getNormalizedMetadata(identifier: ResourceIdentifier): Promise<RepresentationMetadata> {
@ -411,6 +412,7 @@ export class DataAccessorBasedStore implements ResourceStore {
/**
* Write the given metadata resource to the DataAccessor.
*
* @param identifier - Identifier of the metadata.
* @param representation - Corresponding Representation.
*
@ -451,6 +453,7 @@ export class DataAccessorBasedStore implements ResourceStore {
/**
* Write the given resource to the DataAccessor. Metadata will be updated with necessary triples.
* In case of containers `handleContainerData` will be used to verify the data.
*
* @param identifier - Identifier of the resource.
* @param representation - Corresponding Representation.
* @param isContainer - Is the incoming resource a container?
@ -576,6 +579,7 @@ export class DataAccessorBasedStore implements ResourceStore {
/**
* Validates if the slug and headers are valid.
* Errors if slug exists, ends on slash, but ContainerType Link header is NOT present
*
* @param isContainer - Is the slug supposed to represent a container?
* @param slug - Is the requested slug (if any).
*/
@ -588,6 +592,7 @@ export class DataAccessorBasedStore implements ResourceStore {
/**
* Clean http Slug to be compatible with the server. Makes sure there are no unwanted characters
* e.g.: cleanslug('&%26') returns '%26%26'
*
* @param slug - the slug to clean
*/
protected cleanSlug(slug: string): string {
@ -633,6 +638,7 @@ export class DataAccessorBasedStore implements ResourceStore {
/**
* Checks if the given metadata represents a (potential) container,
* based on the metadata.
*
* @param metadata - Metadata of the (new) resource.
*/
protected isContainerType(metadata: RepresentationMetadata): boolean {
@ -687,6 +693,7 @@ export class DataAccessorBasedStore implements ResourceStore {
/**
* Create containers starting from the root until the given identifier corresponds to an existing container.
* Will throw errors if the identifier of the last existing "container" corresponds to an existing document.
*
* @param container - Identifier of the container which will need to exist.
*/
protected async createRecursiveContainers(container: ResourceIdentifier): Promise<ChangeMap> {
@ -719,6 +726,7 @@ export class DataAccessorBasedStore implements ResourceStore {
/**
* Generates activity metadata for a resource and adds it to the {@link ChangeMap}
*
* @param map - ChangeMap to update.
* @param id - Identifier of the resource being changed.
* @param activity - Which activity is taking place.
@ -729,6 +737,7 @@ export class DataAccessorBasedStore implements ResourceStore {
/**
* Generates activity metadata specifically for Add/Remove events on a container.
*
* @param map - ChangeMap to update.
* @param id - Identifier of the container.
* @param add - If there is a resource being added (`true`) or removed (`false`).

1
src/storage/ResourceSet.ts
View File

@ -6,6 +6,7 @@ import type { ResourceIdentifier } from '../http/representation/ResourceIdentifi
export interface ResourceSet {
/**
* Check if a resource exists in this ResourceSet.
*
* @param identifier - Identifier of resource to check.
*
* @returns A promise resolving if the resource already exists.

5
src/storage/ResourceStore.ts
View File

@ -28,6 +28,7 @@ export type ChangeMap = IdentifierMap<RepresentationMetadata>;
export interface ResourceStore extends ResourceSet {
/**
* Retrieves a representation of a resource.
*
* @param identifier - Identifier of the resource to read.
* @param preferences - Preferences indicating desired representations.
* @param conditions - Optional conditions under which to proceed.
@ -43,6 +44,7 @@ export interface ResourceStore extends ResourceSet {
/**
* Sets or replaces the representation of a resource,
* creating a new resource and intermediary containers as needed.
*
* @param identifier - Identifier of resource to update.
* @param representation - New representation of the resource.
* @param conditions - Optional conditions under which to proceed.
@ -57,6 +59,7 @@ export interface ResourceStore extends ResourceSet {
/**
* Creates a new resource in the container.
*
* @param container - Container in which to create a resource.
* @param representation - Representation of the new resource
* @param conditions - Optional conditions under which to proceed.
@ -71,6 +74,7 @@ export interface ResourceStore extends ResourceSet {
/**
* Deletes a resource.
*
* @param identifier - Identifier of resource to delete.
* @param conditions - Optional conditions under which to proceed.
*
@ -84,6 +88,7 @@ export interface ResourceStore extends ResourceSet {
/**
* Sets or updates the representation of a resource,
* creating a new resource and intermediary containers as needed.
*
* @param identifier - Identifier of resource to update.
* @param patch - Description of which parts to update.
* @param conditions - Optional conditions under which to proceed.

5
src/storage/accessors/DataAccessor.ts
View File

@ -16,6 +16,7 @@ import type { Guarded } from '../../util/GuardedStream';
export interface DataAccessor {
/**
* Should throw a NotImplementedHttpError if the DataAccessor does not support storing the given Representation.
*
* @param representation - Incoming Representation.
*
* @throws BadRequestHttpError
@ -26,6 +27,7 @@ export interface DataAccessor {
/**
* Returns a data stream stored for the given identifier.
* It can be assumed that the incoming identifier will always correspond to a document.
*
* @param identifier - Identifier for which the data is requested.
*/
getData: (identifier: ResourceIdentifier) => Promise<Guarded<Readable>>;
@ -56,6 +58,7 @@ export interface DataAccessor {
/**
* Writes data and metadata for a document.
* If any data and/or metadata exist for the given identifier, it should be overwritten.
*
* @param identifier - Identifier of the resource.
* @param data - Data to store.
* @param metadata - Metadata to store.
@ -67,6 +70,7 @@ export interface DataAccessor {
* Writes metadata for a container.
* If the container does not exist yet it should be created,
* if it does its metadata should be overwritten, except for the containment triples.
*
* @param identifier - Identifier of the container.
* @param metadata - Metadata to store.
*/
@ -75,6 +79,7 @@ export interface DataAccessor {
/**
* Writes metadata for a resource.
* It can safely be assumed that the subject resource already exists.
*
* @param identifier - Identifier of the subject resource.
* @param metadata - Metadata to store.
*/

5
src/storage/accessors/FileDataAccessor.ts
View File

@ -139,6 +139,7 @@ export class FileDataAccessor implements DataAccessor {
/**
* Gets the Stats object corresponding to the given file path,
* resolving symbolic links.
*
* @param path - File path to get info from.
*
* @throws NotFoundHttpError
@ -188,6 +189,7 @@ export class FileDataAccessor implements DataAccessor {
/**
* Writes the metadata of the resource to a meta file.
*
* @param link - Path related metadata of the resource.
* @param metadata - Metadata to write.
*
@ -226,6 +228,7 @@ export class FileDataAccessor implements DataAccessor {
/**
* Generates metadata relevant for any resources stored by this accessor.
*
* @param link - Path related metadata.
* @param stats - Stats objects of the corresponding directory.
* @param isContainer - If the path points to a container (directory) or not.
@ -319,6 +322,7 @@ export class FileDataAccessor implements DataAccessor {
/**
* Helper function to add file system related metadata.
*
* @param metadata - metadata object to add to
* @param stats - Stats of the file/directory corresponding to the resource.
*/
@ -351,6 +355,7 @@ export class FileDataAccessor implements DataAccessor {
/**
* Helper function without extra validation checking to create a data file.
*
* @param path - The filepath of the file to be created.
* @param data - The data to be put in the file.
*/

9
src/storage/accessors/SparqlDataAccessor.ts
View File

@ -174,6 +174,7 @@ export class SparqlDataAccessor implements DataAccessor {
/**
* Creates the name for the metadata of a resource.
*
* @param name - Name of the (non-metadata) resource.
*/
private getMetadataNode(name: NamedNode): NamedNode {
@ -189,6 +190,7 @@ export class SparqlDataAccessor implements DataAccessor {
/**
* Creates a CONSTRUCT query that returns all quads contained within a single resource.
*
* @param name - Name of the resource to query.
*/
private sparqlConstruct(name: NamedNode): ConstructQuery {
@ -213,6 +215,7 @@ export class SparqlDataAccessor implements DataAccessor {
/**
* Creates an update query that overwrites the data and metadata of a resource.
* If there are no triples we assume it's a container (so don't overwrite the main graph with containment triples).
*
* @param name - Name of the resource to update.
* @param metadata - New metadata of the resource.
* @param parent - Name of the parent to update the containment triples.
@ -255,6 +258,7 @@ export class SparqlDataAccessor implements DataAccessor {
/**
* Creates an update query that overwrites metadata of a resource.
*
* @param metaName - Name of the metadata resource to update.
* @param metadata - New metadata of the resource.
*/
@ -280,6 +284,7 @@ export class SparqlDataAccessor implements DataAccessor {
/**
* Creates a query that deletes everything related to the given name.
*
* @param name - Name of resource to delete.
* @param parent - Parent of the resource to delete so the containment triple can be removed (unless root).
*/
@ -306,6 +311,7 @@ export class SparqlDataAccessor implements DataAccessor {
/**
* Helper function for creating SPARQL update queries.
* Creates an operation for deleting all triples in a graph.
*
* @param name - Name of the graph to delete.
*/
private sparqlUpdateDeleteAll(name: NamedNode): InsertDeleteOperation {
@ -318,6 +324,7 @@ export class SparqlDataAccessor implements DataAccessor {
/**
* Helper function for creating SPARQL update queries.
* Creates a Graph selector with the given triples.
*
* @param name - Name of the graph.
* @param triples - Triples/triple patterns to select.
*/
@ -327,6 +334,7 @@ export class SparqlDataAccessor implements DataAccessor {
/**
* Sends a SPARQL CONSTRUCT query to the endpoint and returns a stream of quads.
*
* @param sparqlQuery - Query to execute.
*/
private async sendSparqlConstruct(sparqlQuery: ConstructQuery): Promise<Guarded<Readable>> {
@ -342,6 +350,7 @@ export class SparqlDataAccessor implements DataAccessor {
/**
* Sends a SPARQL update query to the stored endpoint.
*
* @param sparqlQuery - Query to send.
*/
private async sendSparqlUpdate(sparqlQuery: Update): Promise<void> {

1
src/storage/conditions/Conditions.ts
View File

@ -23,6 +23,7 @@ export interface Conditions {
/**
* Checks validity based on the given metadata.
*
* @param metadata - Metadata of the representation. Undefined if the resource does not exist.
* @param strict - How to compare the ETag related headers.
* If true, the comparison will happen on representation level.

1
src/storage/conditions/ETagHandler.ts
View File

@ -26,6 +26,7 @@ export interface ETagHandler {
/**
* Validates whether 2 ETags correspond to the same state of a resource,
* independent of the representation the ETags correspond to.
*
* @param eTag1 - First ETag to compare.
* @param eTag2 - Second ETag to compare.
*/

2
src/storage/conversion/ConversionUtil.ts
View File

@ -164,6 +164,7 @@ export function matchesMediaPreferences(type: string, preferred?: ValuePreferenc
/**
* Checks if the given two media types/ranges match each other.
* Takes wildcards into account.
*
* @param mediaA - Media type to match.
* @param mediaB - Media type to match.
*
@ -202,6 +203,7 @@ export function isInternalContentType(contentType?: string): boolean {
/**
* Serializes a preferences object to a string for display purposes.
*
* @param preferences - Preferences to serialize
*/
export function preferencesToString(preferences: ValuePreferences): string {

1
src/storage/keyvalue/JsonFileStorage.ts
View File

@ -61,6 +61,7 @@ export class JsonFileStorage implements KeyValueStorage<string, unknown> {
/**
* Updates the data in the JSON file while using a write lock.
*
* @param updateFn - A function that updates the JSON object.
*
* @returns The return value of `updateFn`.

4
src/storage/keyvalue/KeyValueStorage.ts
View File

@ -6,18 +6,21 @@ export interface KeyValueStorage<TKey, TValue> {
/**
* Returns the value stored for the given identifier.
* `undefined` if no value is stored.
*
* @param identifier - Identifier to get the value for.
*/
get: (key: TKey) => Promise<TValue | undefined>;
/**
* Checks if there is a value stored for the given key.
*
* @param identifier - Identifier to check.
*/
has: (key: TKey) => Promise<boolean>;
/**
* Sets the value for the given key.
*
* @param key - Key to set/update.
* @param value - Value to store.
*
@ -27,6 +30,7 @@ export interface KeyValueStorage<TKey, TValue> {
/**
* Deletes the value stored for the given key.
*
* @param key - Key to delete.
*
* @returns If there was a value to delete.

20
src/storage/mapping/BaseFileIdentifierMapper.ts
View File

@ -36,6 +36,7 @@ export class BaseFileIdentifierMapper implements FileIdentifierMapper {
* Maps the given resource identifier / URL to a file path.
* Determines the content type if none was provided.
* For containers the content-type input is ignored.
*
* @param identifier - The input identifier.
* @param isMetadata - If we need the data or metadata file path.
* @param contentType - The content-type provided with the request.
@ -59,6 +60,7 @@ export class BaseFileIdentifierMapper implements FileIdentifierMapper {
/**
* Maps the given container identifier to a file path,
* possibly making alterations to the direct translation.
*
* @param identifier - The input identifier.
* @param filePath - The direct translation of the identifier onto the file path.
*
@ -74,6 +76,7 @@ export class BaseFileIdentifierMapper implements FileIdentifierMapper {
* possibly making alterations to the direct translation
* (for instance, based on its content type)).
* Determines the content type if none was provided.
*
* @param identifier - The input identifier.
* @param filePath - The direct translation of the identifier onto the file path.
* @param contentType - The content-type provided with the request.
@ -92,6 +95,7 @@ export class BaseFileIdentifierMapper implements FileIdentifierMapper {
/**
* Determines the content type from the document identifier.
*
* @param identifier - The input identifier.
* @param contentType - The content-type provided with the request.
*
@ -103,6 +107,7 @@ export class BaseFileIdentifierMapper implements FileIdentifierMapper {
/**
* Maps the given file path to a URL and determines its content type.
*
* @param filePath - The input file path.
* @param isContainer - If the path corresponds to a file.
*
@ -134,6 +139,7 @@ export class BaseFileIdentifierMapper implements FileIdentifierMapper {
/**
* Maps the given container path to a URL and determines its content type.
*
* @param relative - The relative container path.
*
* @returns A ResourceLink with all the necessary metadata.
@ -144,6 +150,7 @@ export class BaseFileIdentifierMapper implements FileIdentifierMapper {
/**
* Maps the given document path to a URL and determines its content type.
*
* @param relative - The relative document path.
*
* @returns A ResourceLink with all the necessary metadata.
@ -154,6 +161,7 @@ export class BaseFileIdentifierMapper implements FileIdentifierMapper {
/**
* Determines the content type from the relative path.
*
* @param filePath - The file path of the document.
*
* @returns The content type of the document.
@ -165,6 +173,7 @@ export class BaseFileIdentifierMapper implements FileIdentifierMapper {
/**
* Get the absolute file path based on the rootFilepath.
*
* @param path - The relative file path.
*
* @returns Absolute path of the file.
@ -175,12 +184,13 @@ export class BaseFileIdentifierMapper implements FileIdentifierMapper {
/**
* Strips the baseRequestURI from the identifier.
*
* @param identifier - Incoming identifier.
*
* @returns A string representing the relative path.
*
* @throws NotFoundHttpError
* If the identifier does not match the baseRequestURI.
*
* @returns A string representing the relative path.
*/
protected getRelativePath(identifier: ResourceIdentifier): string {
if (!identifier.path.startsWith(this.baseRequestURI)) {
@ -193,11 +203,11 @@ export class BaseFileIdentifierMapper implements FileIdentifierMapper {
/**
* Check if the given relative path is valid.
*
* @throws BadRequestHttpError
* If the relative path is invalid.
*
* @param path - A relative path, as generated by {@link getRelativePath}.
* @param identifier - A resource identifier.
*
* @throws BadRequestHttpError
* If the relative path is invalid.
*/
protected validateRelativePath(path: string, identifier: ResourceIdentifier): void {
if (!path.startsWith('/')) {

2
src/storage/mapping/FileIdentifierMapper.ts
View File

@ -25,6 +25,7 @@ export interface ResourceLink {
export interface FileIdentifierMapper {
/**
* Maps the given file path to an URL and determines the content-type
*
* @param filePath - The input file path.
* @param isContainer - If the path corresponds to a file.
*
@ -36,6 +37,7 @@ export interface FileIdentifierMapper {
* Determines the content-type if no content-type was provided by finding the corresponding file.
* If there is no corresponding file a file path will be generated.
* For containers the content-type input gets ignored.
*
* @param identifier - The input identifier.
* @param isMetadata - If we are mapping the metadata of the resource instead of its data.
* @param contentType - The (optional) content-type of the resource.

4
src/storage/quota/QuotaStrategy.ts
View File

@ -33,6 +33,7 @@ export abstract class QuotaStrategy {
* as available space.
*
* @param identifier - the identifier of the resource of which you want the available space
*
* @returns the available space and the unit of the space as a Size object
*/
public async getAvailableSpace(identifier: ResourceIdentifier): Promise<Size> {
@ -57,6 +58,7 @@ export abstract class QuotaStrategy {
* Get the currently used/occupied space.
*
* @param identifier - the identifier that should be used to calculate the total
*
* @returns a Size object containing the requested value.
* If quota is not relevant for this identifier, Size.amount should be Number.MAX_SAFE_INTEGER
*/
@ -66,6 +68,7 @@ export abstract class QuotaStrategy {
* Get an estimated size of the resource
*
* @param metadata - the metadata that might include the size
*
* @returns a Size object containing the estimated size and unit of the resource
*/
public async estimateSize(metadata: RepresentationMetadata): Promise<Size | undefined> {
@ -79,6 +82,7 @@ export abstract class QuotaStrategy {
* Like other Passthrough instances this will simply pass on the chunks, when the quota isn't exceeded.
*
* @param identifier - the identifier of the resource in question
*
* @returns a Passthrough instance that errors when quota is exceeded
*/
public async createQuotaGuard(identifier: ResourceIdentifier): Promise<Guarded<PassThrough>> {

1
src/storage/routing/BaseUrlRouterRule.ts
View File

@ -11,6 +11,7 @@ import { RouterRule } from './RouterRule';
*
* Part of the dynamic pod creation.
* Uses the identifiers that were added to the routing storage.
*
* @see {@link TemplatedPodGenerator}, {@link ConfigPodInitializer}, {@link ConfigPodManager}
*/
export class BaseUrlRouterRule extends RouterRule {

1
src/storage/size-reporter/FileSizeReporter.ts
View File

@ -49,6 +49,7 @@ export class FileSizeReporter implements SizeReporter<string> {
* Get the total size of a resource and its children if present
*
* @param fileLocation - the resource of which you want the total size of ( on disk )
*
* @returns a number specifying how many bytes are used by the resource
*/
private async getTotalSize(fileLocation: string): Promise<number> {

3
src/storage/size-reporter/SizeReporter.ts
View File

@ -20,6 +20,7 @@ export interface SizeReporter<T> {
* Get the size of a given resource
*
* @param identifier - the resource of which you want the size
*
* @returns The size of the resource as a Size object calculated recursively
* if the identifier leads to a container
*/
@ -29,6 +30,7 @@ export interface SizeReporter<T> {
* Calculate the size of a chunk based on which SizeReporter is being used
*
* @param chunk - the chunk of which you want the size
*
* @returns the size of the passed chunk as a number
*/
calculateChunkSize: (chunk: T) => Promise<number>;
@ -37,6 +39,7 @@ export interface SizeReporter<T> {
* Estimate the size of a body / request by looking at its metadata
*
* @param metadata - the metadata of the resource you want an estimated size of
*
* @returns the estimated size of the body / request or undefined if no
* meaningful estimation can be made
*/

1
src/util/Header.ts
View File

@ -55,6 +55,7 @@ export class ContentType {
/**
* Serialize this ContentType object to a ContentType header appropriate value string.
*
* @returns The value string, including parameters, if present.
*/
public toHeaderValueString(): string {

13
src/util/HeaderUtil.ts
View File

@ -29,12 +29,13 @@ const logger = getLoggerFor('HeaderUtil');
// HELPER FUNCTIONS
/**
* Replaces all double quoted strings in the input string with `"0"`, `"1"`, etc.
*
* @param input - The Accept header string.
*
* @returns The transformed string and a map with keys `"0"`, etc. and values the original string that was there.
*
* @throws BadRequestHttpError
* Thrown if invalid characters are detected in a quoted string.
*
* @returns The transformed string and a map with keys `"0"`, etc. and values the original string that was there.
*/
export function transformQuotedStrings(input: string): { result: string; replacements: Record<string, string> } {
let idx = 0;
@ -200,6 +201,7 @@ function parseAcceptPart(part: string, replacements: Record<string, string>, str
/**
* Parses an Accept-* header where each part is only a value and a weight, so roughly /.*(q=.*)?/ separated by commas.
* The returned weights default to 1 if no q value is found or the q value is invalid.
*
* @param input - Input header string.
* @param strict - Determines if invalid values throw errors (`true`) or log warnings (`false`). Defaults to `false`.
*
@ -371,10 +373,10 @@ export function addHeader(response: HttpResponse, name: string, value: string |
*
* @param input - The Content-Type header string.
*
* @returns A {@link ContentType} object containing the value and optional parameters.
*
* @throws BadRequestHttpError
* Thrown on invalid header syntax.
*
* @returns A {@link ContentType} object containing the value and optional parameters.
*/
export function parseContentType(input: string): ContentType {
// Quoted strings could prevent split from having correct results
@ -438,6 +440,7 @@ export function parseForwarded(headers: IncomingHttpHeaders): Forwarded {
* Parses the link header(s) and returns an array of LinkEntry objects.
*
* @param link - A single link header or an array of link headers
*
* @returns A LinkEntry array, LinkEntry contains a link and a params Record&lt;string,string&gt;
*/
export function parseLinkHeader(link: string | string[] = []): LinkEntry[] {
@ -484,6 +487,7 @@ const authSchemeRegexCache: Map<string, RegExp> = new Map();
*
* @param scheme - Name of the authorization scheme (case insensitive).
* @param authorization - The value of the Authorization header (may be undefined).
*
* @returns True if the Authorization header uses the specified scheme, false otherwise.
*/
export function matchesAuthorizationScheme(scheme: string, authorization?: string): boolean {
@ -500,6 +504,7 @@ export function matchesAuthorizationScheme(scheme: string, authorization?: strin
*
* @param url - A string representing the URL.
* @param schemes - Scheme value options (the function will check if at least one matches the URL scheme).
*
* @returns True if the URL scheme matches at least one of the provided options, false otherwise.
*/
export function hasScheme(url: string, ...schemes: string[]): boolean {

1
src/util/IterableUtil.ts
View File

@ -48,6 +48,7 @@ export function* filter<T>(
/**
* Creates a new iterable that is a concatenation of all the iterables in the input.
*
* @param iterables - An iterable of which the contents will be concatenated into a new iterable.
*/
export function* concat<T>(iterables: Iterable<Iterable<T>>): Iterable<T> {

6
src/util/LockUtils.ts
View File

@ -5,8 +5,10 @@ const logger = getLoggerFor('LockUtil');
/**
* Waits a set amount of time, without consuming cpu, with a set amount of jitter.
*
* @param delay - How long to wait.
* @param jitter - A fraction of this jitter will be added to the delay.
*
* @returns A promise that resolves after the specified amount of time.
*/
export async function setJitterTimeout(delay: number, jitter = 0): Promise<void> {
@ -28,8 +30,8 @@ export interface AttemptSettings {
* Will execute the given function until one of the following cases occurs:
* * The function resolves to a value: the value is returned.
* * The function errors: the rejected error is thrown.
* * The function did not resolve after the set amount of retries:
* the rejected error is returned.
* * The function did not resolve after the set amount of retries: the rejected error is returned.
*
* @param fn - The function to retry. **This function must return a value!**
* @param settings - The options on how to retry the function
*/

9
src/util/PathUtil.ts
View File

@ -113,6 +113,7 @@ export function trimLeadingSlashes(path: string): string {
/**
* Extracts the extension (without dot) from a path.
* Custom function since `path.extname` does not work on all cases (e.g. ".acl")
*
* @param path - Input path to parse.
*/
export function getExtension(path: string): string {
@ -150,6 +151,7 @@ function transformPathComponents(path: string, transform: (part: string) => stri
* the provided path.
*
* @param path - The path to convert to its canonical URI path form.
*
* @returns The canonical URI path form of the provided path.
*/
export function toCanonicalUriPath(path: string): string {
@ -178,6 +180,7 @@ const forbiddenRegex = new RegExp(`[${Object.keys(forbiddenSymbols).join('')}]`,
* Characters that would result in an illegal file path remain percent encoded.
*
* @param path - The path to decode the URI path components of.
*
* @returns A decoded copy of the provided URI path (ignoring encoded slash characters).
*/
export function decodeUriPathComponents(path: string): string {
@ -192,6 +195,7 @@ export function decodeUriPathComponents(path: string): string {
* lead to unnecessary double encoding, resulting in a URI that differs from the expected result.
*
* @param path - The path to encode the URI path components of.
*
* @returns An encoded copy of the provided URI path (ignoring encoded slash characters).
*/
export function encodeUriPathComponents(path: string): string {
@ -200,6 +204,7 @@ export function encodeUriPathComponents(path: string): string {
/**
* Checks if the path corresponds to a container path (ending in a /).
*
* @param path - Path to check.
*/
export function isContainerPath(path: string): boolean {
@ -210,6 +215,7 @@ export function isContainerPath(path: string): boolean {
/**
* Checks if the identifier corresponds to a container identifier.
*
* @param identifier - Identifier to check.
*/
export function isContainerIdentifier(identifier: ResourceIdentifier): boolean {
@ -219,6 +225,7 @@ export function isContainerIdentifier(identifier: ResourceIdentifier): boolean {
/**
* Splits a URL (or similar) string into a part containing its scheme and one containing the rest.
* E.g., `http://test.com/` results in `{ scheme: 'http://', rest: 'test.com/' }`.
*
* @param url - String to parse.
*/
export function extractScheme(url: string): { scheme: string; rest: string } {
@ -229,6 +236,7 @@ export function extractScheme(url: string): { scheme: string; rest: string } {
/**
* Creates a relative URL by removing the base URL.
* Will throw an error in case the resulting target is not withing the base URL scope.
*
* @param baseUrl - Base URL.
* @param request - Incoming request of which the target needs to be extracted.
* @param targetExtractor - Will extract the target from the request.
@ -256,6 +264,7 @@ Promise<string> {
* - Will match `http://alice.bob.test.com/foo/bar/baz`, first match result will be `alice.bob`
* - Will not match `http://test.com/`
* - Will not match `http://alicetest.com/foo/`
*
* @param baseUrl - Base URL for the regular expression.
*/
export function createSubdomainRegexp(baseUrl: string): RegExp {

1
src/util/PromiseUtil.ts
View File

@ -5,6 +5,7 @@ export type PromiseOrValue<T> = T | Promise<T>;
/**
* Verifies if the given value is a Promise or not.
*
* @param object - Object to check.
*/
export function isPromise<T>(object: PromiseOrValue<T>): object is Promise<T> {

3
src/util/QuadUtil.ts
View File

@ -9,6 +9,7 @@ import { toNamedTerm } from './TermUtil';
/**
* Helper function for serializing an array of quads, with as result a Readable object.
*
* @param quads - The array of quads.
* @param contentType - The content-type to serialize to.
*
@ -20,6 +21,7 @@ export function serializeQuads(quads: Quad[], contentType?: string): Guarded<Rea
/**
* Helper function to convert a Readable into an array of quads.
*
* @param readable - The readable object.
* @param options - Options for the parser.
*
@ -31,6 +33,7 @@ export async function parseQuads(readable: Guarded<Readable>, options: ParserOpt
/**
* Filter out duplicate quads from an array.
*
* @param quads - Quads to filter.
*
* @returns A new array containing the unique quads.

4
src/util/ResourceUtil.ts
View File

@ -13,6 +13,7 @@ import namedNode = DataFactory.namedNode;
/**
* Helper function to generate type quads for a Container or Resource.
*
* @param metadata - Metadata to add to.
* @param isContainer - If the identifier corresponds to a container.
*/
@ -26,6 +27,7 @@ export function addResourceMetadata(metadata: RepresentationMetadata, isContaine
/**
* Updates the dc:modified time to the given time.
*
* @param metadata - Metadata to update.
* @param date - Last modified date. Defaults to current time.
*/
@ -38,6 +40,7 @@ export function updateModifiedDate(metadata: RepresentationMetadata, date = new
/**
* Links a template file with a given content-type to the metadata using the SOLID_META.template predicate.
*
* @param metadata - Metadata to update.
* @param templateFile - Path to the template.
* @param contentType - Content-type of the template after it is rendered.
@ -52,6 +55,7 @@ void {
/**
* Helper function to clone a representation, the original representation can still be used.
* This function loads the entire stream in memory.
*
* @param representation - The representation to clone.
*
* @returns The cloned representation.

7
src/util/StreamUtil.ts
View File

@ -19,6 +19,7 @@ const logger = getLoggerFor('StreamUtil');
/**
* Joins all strings of a stream.
*
* @param stream - Stream of strings.
*
* @returns The joined string.
@ -29,6 +30,7 @@ export async function readableToString(stream: Readable): Promise<string> {
/**
* Imports quads from a stream into a Store.
*
* @param stream - Stream of quads.
*
* @returns A Store containing all the quads.
@ -42,6 +44,7 @@ export async function readableToQuads(stream: Readable): Promise<Store> {
/**
* Interprets the stream as JSON and converts it to a Dict.
*
* @param stream - Stream of JSON data.
*
* @returns The parsed object.
@ -55,6 +58,7 @@ export async function readJsonStream(stream: Readable): Promise<Json> {
* Converts the stream to a single object.
* This assumes the stream is in object mode and only contains a single element,
* otherwise an error will be thrown.
*
* @param stream - Object stream with single entry.
*/
export async function getSingleItem(stream: Readable): Promise<unknown> {
@ -78,6 +82,7 @@ const safeErrors = new Set([
* Pipes one stream into another and emits errors of the first stream with the second.
* In case of an error in the first stream the second one will be destroyed with the given error.
* This will also make the stream {@link Guarded}.
*
* @param readable - Initial readable stream.
* @param destination - The destination for writing data.
* @param mapError - Optional function that takes the error and converts it to a new error.
@ -134,6 +139,7 @@ export interface AsyncTransformOptions<T = unknown> extends DuplexOptions {
/**
* Transforms a stream, ensuring that all errors are forwarded.
*
* @param source - The stream to be transformed.
* @param options - The transformation options.
* @param options.transform - The transform function to use.
@ -177,6 +183,7 @@ export function transformSafely<T = unknown>(
/**
* Converts a string or array to a stream and applies an error guard so that it is {@link Guarded}.
*
* @param contents - Data to stream.
* @param options - Options to pass to the Readable constructor. See {@link Readable.from}.
*/

4
src/util/StringUtil.ts
View File

@ -13,6 +13,7 @@ export function splitCommaSeparated(input: string): string[] {
* Sanitizes part of a URL by replacing non-word content with a '-'.
*
* @param urlPart - The URL part to sanitize.
*
* @returns The sanitized output.
*/
export function sanitizeUrlPart(urlPart: string): string {
@ -23,6 +24,7 @@ export function sanitizeUrlPart(urlPart: string): string {
* Checks the validity of a file name. A valid name consists of word characters, '-' or '.'.
*
* @param name - The name of the file to validate.
*
* @returns True if the filename is valid, false otherwise.
*/
export function isValidFileName(name: string): boolean {
@ -33,6 +35,7 @@ export function isValidFileName(name: string): boolean {
* Checks if the given string is a valid URL.
*
* @param url - String to check.
*
* @returns True if the string is a valid URL.
*/
export function isUrl(url: string): boolean {
@ -49,6 +52,7 @@ export function isUrl(url: string): boolean {
* Converts milliseconds to an ISO 8601 duration string.
* The only categories used are days, hours, minutes, and seconds,
* because months have no fixed size in milliseconds.
*
* @param ms - The duration in ms to convert.
*/
export function msToDuration(ms: number): string {

3
src/util/TermUtil.ts
View File

@ -12,6 +12,7 @@ export function isTerm(input?: unknown): input is Term {
/**
* Converts a string to a named node when needed.
*
* @param subject - Subject to potentially transform.
*/
export function toNamedTerm(subject: string): NamedNode;
@ -25,6 +26,7 @@ export const toPredicateTerm = toNamedTerm;
/**
* Converts an object term when needed.
*
* @param object - Object to potentially transform.
* @param preferLiteral - Whether strings are converted to literals or named nodes.
*/
@ -40,6 +42,7 @@ export function toObjectTerm(object: Term | string, preferLiteral = false): Term
/**
* Creates a literal by first converting the dataType string to a named node.
*
* @param object - Object value.
* @param dataType - Object data type (as string).
*/

1
src/util/Vocabularies.ts
View File

@ -88,6 +88,7 @@ string extends TLocal ? PartialVocabulary<TBase> : Vocabulary<TBase, TLocal> {
/**
* Creates a new {@link Vocabulary} that extends an existing one by adding new local names.
*
* @param vocabulary - The {@link Vocabulary} to extend.
* @param newNames - The new local names that need to be added.
*/

1
src/util/errors/BadRequestHttpError.ts
View File

@ -11,6 +11,7 @@ const BaseHttpError = generateHttpErrorClass(400, 'BadRequestHttpError');
export class BadRequestHttpError extends BaseHttpError {
/**
* Default message is 'The given input is not supported by the server configuration.'.
*
* @param message - Optional, more specific, message.
* @param options - Optional error options.
*/

1
src/util/errors/HttpError.ts
View File

@ -29,6 +29,7 @@ export class HttpError<T extends number = number> extends Error implements HttpE
/**
* Creates a new HTTP error. Subclasses should call this with their fixed status code.
*
* @param statusCode - HTTP status code needed for the HTTP response.
* @param name - Error name. Useful for logging and stack tracing.
* @param message - Error message.

1
src/util/errors/PayloadHttpError.ts
View File

@ -10,6 +10,7 @@ const BaseHttpError = generateHttpErrorClass(413, 'PayloadHttpError');
export class PayloadHttpError extends BaseHttpError {
/**
* Default message is 'Storage quota was exceeded.'.
*
* @param message - Optional, more specific, message.
* @param options - Optional error options.
*/

1
src/util/errors/RangeNotSatisfiedHttpError.ts
View File

@ -10,6 +10,7 @@ const BaseHttpError = generateHttpErrorClass(416, 'RangeNotSatisfiedHttpError');
export class RangeNotSatisfiedHttpError extends BaseHttpError {
/**
* Default message is 'The requested range is not supported.'.
*
* @param message - Optional, more specific, message.
* @param options - Optional error options.
*/

3
src/util/handlers/AsyncHandler.ts
View File

@ -9,6 +9,7 @@ export abstract class AsyncHandler<TIn = void, TOut = void> {
/**
* Checks if the input can be handled by this class.
* If it cannot handle the input, rejects with an error explaining why.
*
* @param input - Input that could potentially be handled.
*
* @returns A promise resolving if the input can be handled, rejecting with an Error if not.
@ -21,6 +22,7 @@ export abstract class AsyncHandler<TIn = void, TOut = void> {
/**
* Handles the given input. This may only be called if {@link canHandle} did not reject.
* When unconditionally calling both in sequence, consider {@link handleSafe} instead.
*
* @param input - Input that needs to be handled.
*
* @returns A promise resolving when handling is finished.
@ -31,6 +33,7 @@ export abstract class AsyncHandler<TIn = void, TOut = void> {
* Helper function that first runs {@link canHandle} followed by {@link handle}.
* Throws the error of {@link canHandle} if the data cannot be handled,
* or returns the result of {@link handle} otherwise.
*
* @param input - Input data that will be handled if it can be handled.
*
* @returns A promise resolving if the input can be handled, rejecting with an Error if not.

1
src/util/handlers/BooleanHandler.ts
View File

@ -15,6 +15,7 @@ export class BooleanHandler<TIn> extends AsyncHandler<TIn, boolean> {
/**
* Creates a new BooleanHandler that stores the given handlers.
*
* @param handlers - Handlers over which it will run.
*/
public constructor(handlers: AsyncHandler<TIn, boolean>[]) {

1
src/util/handlers/ProcessHandler.ts
View File

@ -14,6 +14,7 @@ export class ProcessHandler<TIn, TOut> extends AsyncHandler<TIn, TOut> {
/**
* Creates a new ProcessHandler
*
* @param source - The wrapped handler
* @param clusterManager - The ClusterManager in use
* @param executeOnPrimary - Whether to execute the source handler when the process is the _primary_ or a _worker_.

4
src/util/handlers/WaterfallHandler.ts
View File

@ -16,6 +16,7 @@ export class WaterfallHandler<TIn, TOut> implements AsyncHandler<TIn, TOut> {
/**
* Creates a new WaterfallHandler that stores the given handlers.
*
* @param handlers - Handlers over which it will run.
*/
public constructor(handlers: AsyncHandler<TIn, TOut>[]) {
@ -24,6 +25,7 @@ export class WaterfallHandler<TIn, TOut> implements AsyncHandler<TIn, TOut> {
/**
* Checks if any of the stored handlers can handle the given input.
*
* @param input - The data that would need to be handled.
*
* @returns A promise resolving if at least 1 handler supports to input, or rejecting if none do.
@ -34,6 +36,7 @@ export class WaterfallHandler<TIn, TOut> implements AsyncHandler<TIn, TOut> {
/**
* Finds a handler that supports the given input and then lets it handle the given data.
*
* @param input - The data that needs to be handled.
*
* @returns A promise corresponding to the handle call of a handler that supports the input.
@ -55,6 +58,7 @@ export class WaterfallHandler<TIn, TOut> implements AsyncHandler<TIn, TOut> {
/**
* Identical to {@link AsyncHandler.handleSafe} but optimized for composite
* by only needing 1 canHandle call on members.
*
* @param input - The input data.
*
* @returns A promise corresponding to the handle call of a handler that supports the input.

1
src/util/locking/BaseReadWriteLocker.ts
View File

@ -88,6 +88,7 @@ export abstract class BaseReadWriteLocker extends EqualReadWriteLocker {
/**
* Update the counter that keeps track of having open read locks there currently are.
*
* @param identifier - Identifier on which to update the number of read locks.
* @param mod - `+1` or `-1`.
*/

1
src/util/locking/EqualReadWriteLocker.ts
View File

@ -24,6 +24,7 @@ export class EqualReadWriteLocker implements ReadWriteLocker {
/**
* Acquires a new lock for the requested identifier.
* Will resolve when the input function resolves.
*
* @param identifier - Identifier of resource that needs to be locked.
* @param whileLocked - Function to resolve while the resource is locked.
*/

7
src/util/locking/FileSystemResourceLocker.ts
View File

@ -71,6 +71,7 @@ export class FileSystemResourceLocker implements ResourceLocker, Initializable,
/**
* Create a new FileSystemResourceLocker
*
* @param args - Configures the locker using the specified FileSystemResourceLockerArgs instance.
*/
public constructor(args: FileSystemResourceLockerArgs) {
@ -85,7 +86,9 @@ export class FileSystemResourceLocker implements ResourceLocker, Initializable,
* 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(fn: () => Promise<unknown>): () => Promise<unknown> {
@ -138,7 +141,9 @@ export class FileSystemResourceLocker implements ResourceLocker, Initializable,
/**
* 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(identifier: ResourceIdentifier): string {
@ -150,8 +155,10 @@ export class FileSystemResourceLocker implements ResourceLocker, Initializable,
/**
* 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<T>(identifier: ResourceIdentifier, defaults: T): T {

7
src/util/locking/RedisLocker.ts
View File

@ -67,6 +67,7 @@ export class RedisLocker implements ReadWriteLocker, ResourceLocker, Initializab
/**
* Creates a new RedisClient
*
* @param redisClient - Redis connection string of a standalone Redis node
* @param attemptSettings - Override default AttemptSettings
* @param redisSettings - Addition settings used to create the Redis client or to interact with the Redis server
@ -93,6 +94,7 @@ export class RedisLocker implements ReadWriteLocker, ResourceLocker, Initializab
/**
* Generate and return a RedisClient based on the provided string
*
* @param redisClientString - A string that contains either a host address and a
* port number like '127.0.0.1:6379' or just a port number like '6379'.
*/
@ -116,7 +118,9 @@ export class RedisLocker implements ReadWriteLocker, ResourceLocker, Initializab
/**
* Create a scoped Redis key for Read-Write locking.
*
* @param identifier - The identifier object to create a Redis key for
*
* @returns A scoped Redis key that allows cleanup afterwards without affecting other keys.
*/
private getReadWriteKey(identifier: ResourceIdentifier): string {
@ -125,7 +129,9 @@ export class RedisLocker implements ReadWriteLocker, ResourceLocker, Initializab
/**
* Create a scoped Redis key for Resource locking.
*
* @param identifier - The identifier object to create a Redis key for
*
* @returns A scoped Redis key that allows cleanup afterwards without affecting other keys.
*/
private getResourceKey(identifier: ResourceIdentifier): string {
@ -138,6 +144,7 @@ export class RedisLocker implements ReadWriteLocker, ResourceLocker, Initializab
* Wrapper function for all (un)lock operations. If the `fn()` resolves to false (after applying
* {@link fromResp2ToBool}, the result will be swallowed. When `fn()` resolves to true, this wrapper
* will return true. Any error coming from `fn()` will be thrown.
*
* @param fn - The function reference to swallow false from.
*/
private swallowFalse(fn: () => Promise<RedisAnswer>): () => Promise<unknown> {

2
src/util/locking/ResourceLocker.ts
View File

@ -9,6 +9,7 @@ export interface ResourceLocker {
/**
* Acquires a lock on the requested identifier.
* The promise will resolve when the lock has been acquired.
*
* @param identifier - Resource to acquire a lock on.
*/
acquire: (identifier: ResourceIdentifier) => Promise<void>;
@ -17,6 +18,7 @@ export interface ResourceLocker {
* Releases a lock on the requested identifier.
* The promise will resolve when the lock has been released.
* In case there is no lock on the resource an error should be thrown.
*
* @param identifier - Resource to release the lock on.
*/
release: (identifier: ResourceIdentifier) => Promise<void>;

6
src/util/locking/scripts/RedisLuaScripts.ts
View File

@ -79,10 +79,13 @@ export type RedisAnswer = 0 | 1 | null | 'OK' | string;
/**
* Convert a RESP2 response to a boolean.
*
* @param result - The Promise-wrapped result of a RESP2 Redis function.
*
* @returns * `1`, `'OK'`: return `true`
* * `0`: returns `false`
* * `-ERR`: throw error
*
* @throws On `-ERR*` `null` or any other value
*/
export async function fromResp2ToBool(result: Promise<RedisAnswer>): Promise<boolean> {
@ -123,12 +126,14 @@ export interface RedisReadWriteLock extends Redis {
/**
* Release readLock. This means decrementing the read counter with 1.
*
* @returns 1 if succeeded. '-ERR' if read count goes below 0
*/
releaseReadLock: (resourceIdentifierPath: string, callback?: Callback<string>) => Promise<RedisAnswer>;
/**
* Release writeLock. This means deleting the write lock.
*
* @returns 1 if succeeded. '-ERR' if write lock was non-existing.
*/
releaseWriteLock: (resourceIdentifierPath: string, callback?: Callback<string>) => Promise<RedisAnswer>;
@ -145,6 +150,7 @@ export interface RedisResourceLock extends Redis {
/**
* Release lock. This means deleting the lock.
*
* @returns 1 if succeeded. '-ERR' if lock was non-existing.
*/
releaseLock: (resourceIdentifierPath: string, callback?: Callback<string>) => Promise<RedisAnswer>;

5
templates/scripts/util.js
View File

@ -71,6 +71,7 @@ function addPostListener(callback, formId = 'mainForm', errorId = 'error') {
/**
* Shows or hides the given element.
*
* @param id - ID of the element.
* @param visible - If it should be visible.
*/
@ -88,6 +89,7 @@ function setVisibility(id, visible) {
/**
* Obtains all children, grandchildren, etc. of the given element.
*
* @param element - Element to get all descendants from.
*/
function getDescendants(element) {
@ -96,6 +98,7 @@ function getDescendants(element) {
/**
* Updates the inner text and href field of an element.
*
* @param id - ID of the element.
* @param text - Text to put in the field(s). If this is undefined, instead the element will be hidden.
* @param options - Indicates which fields should be updated.
@ -117,6 +120,7 @@ function updateElement(id, text, options) {
/**
* Fetches JSON from the url and converts it to an object.
*
* @param url - URL to fetch JSON from.
* @param redirectUrl - URL to redirect to in case the response code is >= 400. No redirect happens if undefined.
*/
@ -159,6 +163,7 @@ function setError(message, errorId = 'error') {
/**
* Causes the page to redirect to a specific page when a button is clicked.
*
* @param element - The id of the button.
* @param url - The URL to redirect to.
*/

4
test/deploy/createAccountCredentials.ts
View File

@ -29,6 +29,7 @@ const bob: User = {
/**
* Registers a user with the server and provides them with a pod.
*
* @param user - The user settings necessary to register a user.
*/
async function register(user: User): Promise<{ webId: string; authorization: string }> {
@ -78,8 +79,10 @@ async function register(user: User): Promise<{ webId: string; authorization: str
/**
* Requests a client credentials API token.
*
* @param webId - WebID to create credentials for.
* @param authorization - Authorization header for the account that tries to create credentials.
*
* @returns The id/secret for the client credentials request.
*/
async function createCredentials(webId: string, authorization: string): Promise<{ id: string; secret: string }> {
@ -104,6 +107,7 @@ async function createCredentials(webId: string, authorization: string): Promise<
* Generates all the necessary data and outputs the necessary lines
* that need to be added to the CTH environment file
* so it can use client credentials.
*
* @param user - User for which data needs to be generated.
*/
async function outputCredentials(user: User): Promise<void> {

1
test/integration/IdentityTestState.ts
View File

@ -28,6 +28,7 @@ export class IdentityTestState {
/**
* Performs a fetch call while keeping track of the stored cookies and preventing redirects.
*
* @param url - URL to call.
* @param method - Method to use.
* @param body - Body to send along. If this is not a string it will be JSONified.

1
test/util/AccountUtil.ts
View File

@ -10,6 +10,7 @@ export type User = {
/**
* Registers an account for the given user details and creates one or more pods.
*
* @param baseUrl - Base URL of the server.
* @param user - User details to register.
*/

2
test/util/NotificationUtil.ts
View File

@ -2,6 +2,7 @@ import { fetch } from 'cross-fetch';
/**
* Subscribes to a notification channel.
*
* @param type - The type of the notification channel, e.g., "NOTIFY.WebhookChannel2023".
* @param webId - The WebID to spoof in the authorization header. This assumes the config uses the debug auth import.
* @param subscriptionUrl - The subscription URL to which the request needs to be sent.
@ -36,6 +37,7 @@ export async function subscribe(
/**
* Verifies if a notification has the expected format.
*
* @param notification - The (parsed) notification.
* @param topic - The topic of the notification.
* @param type - What type of notification is expected.