storage-node-v2: Add code comments.

storage-node-v2/src/command-base/ApiCommandBase.ts

@@ -11,6 +11,9 @@ import ExitCodes from './ExitCodes'
 import { CLIError } from '@oclif/errors'
 import { Input } from '@oclif/parser'
 
+/**
+ * Parent class for all runtime-based commands. Defines common functions.
+ */
 export default abstract class ApiCommandBase extends Command {
   private api: ApiPromise | null = null
 
@@ -33,6 +36,11 @@ export default abstract class ApiCommandBase extends Command {
     }),
   }
 
+  /**
+   * Returns the runtime API promise.
+   *
+   * @returns void promise.
+   */
   async finally(err: Error | undefined): Promise<void> {
     // called after run and catch regardless of whether or not the command errored
     // We'll force exit here, in case there is no error, to prevent console.log from hanging the process
@@ -40,6 +48,9 @@ export default abstract class ApiCommandBase extends Command {
     super.finally(err)
   }
 
+  /**
+   * Returns the runtime API promise.
+   */
   protected async getApi(): Promise<ApiPromise> {
     if (this.api === null) {
       throw new CLIError('Runtime Api is uninitialized.', {
@@ -50,6 +61,10 @@ export default abstract class ApiCommandBase extends Command {
     return this.api
   }
 
+  /**
+   * Initilizes the runtime API using the URL from the command line or the
+   * default value (ws://localhost:9944)
+   */
   async init(): Promise<void> {
     // Oclif hack: https://github.com/oclif/oclif/issues/225#issuecomment-490555119
     /* eslint-disable @typescript-eslint/no-explicit-any */
@@ -62,6 +77,10 @@ export default abstract class ApiCommandBase extends Command {
     await this.getApi()
   }
 
+  /**
+   * Read the chain name from the runtime and throws an error if it's
+   * not 'Development' chain.
+   */
   async ensureDevelopmentChain(): Promise<void> {
     const api = await this.getApi()
 
@@ -78,6 +97,15 @@ export default abstract class ApiCommandBase extends Command {
     logger.info('Development mode is ON.')
   }
 
+  /**
+   * Returns the intialized account KeyringPair instance. Loads the account
+   * JSON-file or loads 'Alice' Keypair when in the development mode.
+   *
+   * @param dev - indicates the development mode (optional).
+   * @param keyfile - key file path (optional).
+   * @param password - password for the key file (optional).
+   * @returns KeyringPair instance.
+   */
   getAccount(flags: {
     dev?: boolean
     keyfile?: string
@@ -101,6 +129,12 @@ export default abstract class ApiCommandBase extends Command {
     return account
   }
 
+  /**
+   * Helper-function for exit after the CLI command. It changes the exit code
+   * depending on the previous extrinsic call success.
+   *
+   * @returns never returns.
+   */
   exitAfterRuntimeCall(success: boolean): never {
     let exitCode = ExitCodes.OK
     if (!success) {

storage-node-v2/src/commands/dev/init.ts

@@ -1,6 +1,14 @@
 import { hireStorageWorkingGroupLead } from '../../services/runtime/hireLead'
 import ApiCommandBase from '../../command-base/ApiCommandBase'
-
+/**
+ * CLI command:
+ * Initialize development environment. Sets Alice as storage working group
+ * leader.
+ *
+ * @remarks
+ * Should be run only during the development.
+ * Shell command: "dev:init"
+ */
 export default class DevInit extends ApiCommandBase {
   static description =
     'Initialize development environment. Sets Alice as storage working group leader.'

storage-node-v2/src/commands/dev/multihash.ts

@@ -2,6 +2,15 @@ import { Command, flags } from '@oclif/command'
 import { hashFile } from '../../services/helpers/hashing'
 import logger from '../../services/logger'
 
+/**
+ * CLI command:
+ * Hashes the file using blake3 algorithm, convert the hash in the multihash
+ * format.
+ *
+ * @remarks
+ * Should be run only during the development.
+ * Shell command: "dev:multihash"
+ */
 export default class DevMultihash extends Command {
   static description = 'Creates a multihash (blake3) for a file.'
 

storage-node-v2/src/commands/dev/upload.ts

@@ -3,6 +3,14 @@ import { uploadDataObjects } from '../../services/runtime/extrinsics'
 import ApiCommandBase from '../../command-base/ApiCommandBase'
 import logger from '../../services/logger'
 
+/**
+ * CLI command:
+ * Registers the data object (content ID and its size) in the runtime.
+ *
+ * @remarks
+ * Should be run only during the development.
+ * Shell command: "dev:upload"
+ */
 export default class DevUpload extends ApiCommandBase {
   static description = 'Upload data object (development mode only).'
 

storage-node-v2/src/commands/dev/verify-bag-id.ts

@@ -3,6 +3,14 @@ import ApiCommandBase from '../../command-base/ApiCommandBase'
 import { parseBagId } from '../../services/helpers/bagTypes'
 import logger from '../../services/logger'
 
+/**
+ * CLI command:
+ * Verifies supported bag ID types in the string format.
+ *
+ * @remarks
+ * Should be run only during the development.
+ * Shell command: "dev:verify-bag-id"
+ */
 export default class DevVerifyBagId extends ApiCommandBase {
   static description =
     'The command verifies bag id supported by the storage node. Requires chain connection.'

storage-node-v2/src/commands/leader/cancel-invite.ts

@@ -3,6 +3,14 @@ import { flags } from '@oclif/command'
 import ApiCommandBase from '../../command-base/ApiCommandBase'
 import logger from '../../services/logger'
 
+/**
+ * CLI command:
+ * Updates the storage bucket status (accept new bags).
+ *
+ * @remarks
+ * Storage working group leader command. Requires storage WG leader priviliges.
+ * Shell command: "leader:cancel-invite"
+ */
 export default class LeaderCancelInvite extends ApiCommandBase {
   static description = `Cancel a storage bucket operator invite. Requires storage working group leader permissions.`
 

storage-node-v2/src/commands/leader/create-bucket.ts

@@ -3,6 +3,14 @@ import { flags } from '@oclif/command'
 import ApiCommandBase from '../../command-base/ApiCommandBase'
 import logger from '../../services/logger'
 
+/**
+ * CLI command:
+ * Creates a storage bucket.
+ *
+ * @remarks
+ * Storage working group leader command. Requires storage WG leader priviliges.
+ * Shell command: "leader:create-bucket"
+ */
 export default class LeaderCreateBucket extends ApiCommandBase {
   static description = `Create new storage bucket. Requires storage working group leader permissions.`
 

storage-node-v2/src/commands/leader/delete-bucket.ts

@@ -3,6 +3,14 @@ import { flags } from '@oclif/command'
 import ApiCommandBase from '../../command-base/ApiCommandBase'
 import logger from '../../services/logger'
 
+/**
+ * CLI command:
+ * Deletes a storage bucket.
+ *
+ * @remarks
+ * Storage working group leader command. Requires storage WG leader priviliges.
+ * Shell command: "leader:delete-bucket"
+ */
 export default class LeaderDeleteBucket extends ApiCommandBase {
   static description = `Delete a storage bucket. Requires storage working group leader permissions.`
 

storage-node-v2/src/commands/leader/invite-operator.ts

@@ -3,6 +3,14 @@ import { flags } from '@oclif/command'
 import ApiCommandBase from '../../command-base/ApiCommandBase'
 import logger from '../../services/logger'
 
+/**
+ * CLI command:
+ * Invites a storage bucket operator.
+ *
+ * @remarks
+ * Storage working group leader command. Requires storage WG leader priviliges.
+ * Shell command: "leader:invite-operator"
+ */
 export default class LeaderInviteOperator extends ApiCommandBase {
   static description = `Invite a storage bucket operator. Requires storage working group leader permissions.`
 

storage-node-v2/src/commands/leader/remove-operator.ts

@@ -3,6 +3,14 @@ import { flags } from '@oclif/command'
 import ApiCommandBase from '../../command-base/ApiCommandBase'
 import logger from '../../services/logger'
 
+/**
+ * CLI command:
+ * Removes invited storage bucket operator.
+ *
+ * @remarks
+ * Storage working group leader command. Requires storage WG leader priviliges.
+ * Shell command: "leader:remove-operator"
+ */
 export default class LeaderRemoveOperator extends ApiCommandBase {
   static description = `Remove a storage bucket operator. Requires storage working group leader permissions.`
 

storage-node-v2/src/commands/leader/set-uploading-block.ts

@@ -3,6 +3,14 @@ import { flags } from '@oclif/command'
 import ApiCommandBase from '../../command-base/ApiCommandBase'
 import logger from '../../services/logger'
 
+/**
+ * CLI command:
+ * Manages global uploading block in the runtime.
+ *
+ * @remarks
+ * Storage working group leader command. Requires storage WG leader priviliges.
+ * Shell command: "leader:set-uploading-block"
+ */
 export default class LeaderSetUploadingBlock extends ApiCommandBase {
   static description = `Set global uploading block. Requires storage working group leader permissions.`
 

storage-node-v2/src/commands/leader/update-bag-limit.ts

@@ -3,6 +3,14 @@ import { updateStorageBucketsPerBagLimit } from '../../services/runtime/extrinsi
 import { flags } from '@oclif/command'
 import logger from '../../services/logger'
 
+/**
+ * CLI command:
+ * Sets new storage-buckets-per-bag limit.
+ *
+ * @remarks
+ * Storage working group leader command. Requires storage WG leader priviliges.
+ * Shell command: "leader:update-bag-limit"
+ */
 export default class LeaderUpdateBagLimit extends ApiCommandBase {
   static description =
     'Update StorageBucketsPerBagLimit variable in the Joystream node storage.'

storage-node-v2/src/commands/leader/update-bag.ts

@@ -4,6 +4,14 @@ import ApiCommandBase from '../../command-base/ApiCommandBase'
 import { parseBagId } from '../../services/helpers/bagTypes'
 import logger from '../../services/logger'
 
+/**
+ * CLI command:
+ * Updates bags-to-buckets relationships.
+ *
+ * @remarks
+ * Storage working group leader command. Requires storage WG leader priviliges.
+ * Shell command: "leader:update-bag"
+ */
 export default class LeaderUpdateBag extends ApiCommandBase {
   static description =
     'Add/remove a storage bucket from a bag (adds by default).'

storage-node-v2/src/commands/leader/update-blacklist.ts

@@ -3,6 +3,15 @@ import { updateBlacklist } from '../../services/runtime/extrinsics'
 import ApiCommandBase from '../../command-base/ApiCommandBase'
 import logger from '../../services/logger'
 
+/**
+ * CLI command:
+ * Updates content ID blacklist. The CID blacklist block data object
+ * runtim registration.
+ *
+ * @remarks
+ * Storage working group leader command. Requires storage WG leader priviliges.
+ * Shell command: "leader:update-blacklist"
+ */
 export default class LeaderUpdateBlacklist extends ApiCommandBase {
   static description =
     'Add/remove a content ID from the blacklist (adds by default).'

storage-node-v2/src/commands/leader/update-data-fee.ts

@@ -3,6 +3,14 @@ import { flags } from '@oclif/command'
 import ApiCommandBase from '../../command-base/ApiCommandBase'
 import logger from '../../services/logger'
 
+/**
+ * CLI command:
+ * Updates storage data fee in the runtime.
+ *
+ * @remarks
+ * Storage working group leader command. Requires storage WG leader priviliges.
+ * Shell command: "leader:update-data-fee"
+ */
 export default class LeaderUpdateDataFee extends ApiCommandBase {
   static description = `Update data size fee. Requires storage working group leader permissions.`
 

storage-node-v2/src/commands/leader/update-dynamic-bag-policy.ts

@@ -4,6 +4,15 @@ import { flags } from '@oclif/command'
 import logger from '../../services/logger'
 import { parseDynamicBagType } from '../../services/helpers/bagTypes'
 
+/**
+ * CLI command:
+ * Updates dynamic bag creation policy - storage bucket number for new dynamic
+ * bag.
+ *
+ * @remarks
+ * Storage working group leader command. Requires storage WG leader priviliges.
+ * Shell command: "leader:update-dynamic-bag-policy"
+ */
 export default class LeaderUpdateDynamicBagPolicy extends ApiCommandBase {
   static description =
     'Update number of storage buckets used in the dynamic bag creation policy.'

storage-node-v2/src/commands/leader/update-voucher-limits.ts

@@ -3,6 +3,14 @@ import { updateStorageBucketsVoucherMaxLimits } from '../../services/runtime/ext
 import { flags } from '@oclif/command'
 import logger from '../../services/logger'
 
+/**
+ * CLI command:
+ * Updates maximum values for storage bucket voucher limits.
+ *
+ * @remarks
+ * Storage working group leader command. Requires storage WG leader priviliges.
+ * Shell command: "leader:update-voucher-limits"
+ */
 export default class LeaderUpdateVoucherLimits extends ApiCommandBase {
   static description =
     'Update VoucherMaxObjectsSizeLimit and VoucherMaxObjectsNumberLimit for the Joystream node storage.'

storage-node-v2/src/commands/operator/accept-invitation.ts

@@ -3,6 +3,15 @@ import { acceptStorageBucketInvitation } from '../../services/runtime/extrinsics
 import ApiCommandBase from '../../command-base/ApiCommandBase'
 import logger from '../../services/logger'
 
+/**
+ * CLI command:
+ * Accepts pending invitation for the storage bucket.
+ *
+ * @remarks
+ * Storage provider (operator) command. Requires an additional worker ID for
+ * runtime verification.
+ * Shell command: "operator:accept-invitation"
+ */
 export default class OperatorAcceptInvitation extends ApiCommandBase {
   static description = 'Accept pending storage bucket invitation.'
 

storage-node-v2/src/commands/operator/set-bucket-limits.ts

@@ -3,6 +3,15 @@ import { setStorageBucketVoucherLimits } from '../../services/runtime/extrinsics
 import { flags } from '@oclif/command'
 import logger from '../../services/logger'
 
+/**
+ * CLI command:
+ * Sets voucher limits for the storage bucket.
+ *
+ * @remarks
+ * Storage provider (operator) command. Requires an additional worker ID for
+ * runtime verification.
+ * Shell command: "operator:set-bucket-limits"
+ */
 export default class LeaderSetBucketLimits extends ApiCommandBase {
   static description =
     'Set VoucherObjectsSizeLimit and VoucherObjectsNumberLimit for the storage bucket.'

storage-node-v2/src/commands/operator/set-metadata.ts

@@ -3,6 +3,15 @@ import { setStorageOperatorMetadata } from '../../services/runtime/extrinsics'
 import ApiCommandBase from '../../command-base/ApiCommandBase'
 import logger from '../../services/logger'
 
+/**
+ * CLI command:
+ * Sets metadata for the storage bucket.
+ *
+ * @remarks
+ * Storage provider (operator) command. Requires an additional worker ID for
+ * runtime verification.
+ * Shell command: "operator:set-metadata"
+ */
 export default class OperatorSetMetadata extends ApiCommandBase {
   static description = 'Accept pending storage bucket invitation.'
 

storage-node-v2/src/commands/operator/update-bucket-status.ts

@@ -3,6 +3,15 @@ import { updateStorageBucketStatus } from '../../services/runtime/extrinsics'
 import ApiCommandBase from '../../command-base/ApiCommandBase'
 import logger from '../../services/logger'
 
+/**
+ * CLI command:
+ * Updates the storage bucket status (accept new bags).
+ *
+ * @remarks
+ * Storage provider (operator) command. Requires an additional worker ID for
+ * runtime verification.
+ * Shell command: "operator:set-metadata"
+ */
 export default class OperatorUpdateStorageBucketStatus extends ApiCommandBase {
   static description = 'Update storage bucket status (accepting new bags).'
 

storage-node-v2/src/commands/server.ts

@@ -3,6 +3,13 @@ import { createApp } from '../services/webApi/app'
 import ApiCommandBase from '../command-base/ApiCommandBase'
 import logger from '../services/logger'
 
+/**
+ * CLI command:
+ * Starts the storage node server.
+ *
+ * @remarks
+ * Shell command: "server"
+ */
 export default class Server extends ApiCommandBase {
   static description = 'Starts the storage node server.'
 

storage-node-v2/src/services/webApi/app.ts

@@ -18,7 +18,15 @@ import {
 import { checkRemoveNonce } from '../../services/helpers/tokenNonceKeeper'
 import { httpLogger } from '../../services/logger'
 
-// Creates web API application.
+/**
+ * Creates Express web application. Uses the OAS spec file for the API.
+ *
+ * @param api - runtime API promise
+ * @param account - KeyringPair instance
+ * @param workerId - storage provider ID (worker ID)
+ * @param uploadsDir - directory for the file uploading
+ * @returns Express promise.
+ */
 export async function createApp(
   api: ApiPromise,
   account: KeyringPair,
@@ -89,7 +97,13 @@ type ValidateUploadFunction = (
   schema: OpenAPIV3.SecuritySchemeObject
 ) => boolean | Promise<boolean>
 
-// Creates upload validation function.
+/**
+ * Creates upload validation function with captured parameters from the request.
+ *
+ * @param api - runtime API promise
+ * @param account - KeyringPair instance
+ * @returns ValidateUploadFunction.
+ */
 function validateUpload(
   api: ApiPromise,
   account: KeyringPair
@@ -116,7 +130,13 @@ function validateUpload(
   }
 }
 
-// Throws exceptions on errors.
+/**
+ * Verifies upload request token. Throws exceptions on errors.
+ *
+ * @param accountAddress - account address (public key)
+ * @param token - token object
+ * @param request - data from the request to validate token
+ */
 function verifyUploadTokenData(
   accountAddress: string,
   token: UploadToken,