From 5d3cc66c2540aacaba5cc05d30bba81d72d78dc6 Mon Sep 17 00:00:00 2001 From: James Taylor Date: Tue, 1 Feb 2022 16:12:07 +0000 Subject: [PATCH] Convert comments to tsdoc in REST sample (#606) Signed-off-by: James Taylor --- .../rest-api-typescript/src/config.ts | 58 +++++++------- .../rest-api-typescript/src/errors.ts | 77 ++++++++++--------- .../rest-api-typescript/src/fabric.ts | 16 ++-- .../rest-api-typescript/src/jobs.ts | 16 ++-- .../rest-api-typescript/src/redis.ts | 2 +- 5 files changed, 87 insertions(+), 82 deletions(-) diff --git a/asset-transfer-basic/rest-api-typescript/src/config.ts b/asset-transfer-basic/rest-api-typescript/src/config.ts index 87b64719..c70d70f8 100644 --- a/asset-transfer-basic/rest-api-typescript/src/config.ts +++ b/asset-transfer-basic/rest-api-typescript/src/config.ts @@ -20,7 +20,7 @@ export const ORG2 = 'Org2'; export const JOB_QUEUE_NAME = 'submit'; -/* +/** * Log level for the REST server */ export const logLevel = env @@ -28,7 +28,7 @@ export const logLevel = env .default('info') .asEnum(['fatal', 'error', 'warn', 'info', 'debug', 'trace', 'silent']); -/* +/** * The port to start the REST server on */ export const port = env @@ -37,7 +37,7 @@ export const port = env .example('3000') .asPortNumber(); -/* +/** * The type of backoff to use for retrying failed submit jobs */ export const submitJobBackoffType = env @@ -45,7 +45,7 @@ export const submitJobBackoffType = env .default('fixed') .asEnum(['fixed', 'exponential']); -/* +/** * Backoff delay for retrying failed submit jobs in milliseconds */ export const submitJobBackoffDelay = env @@ -54,7 +54,7 @@ export const submitJobBackoffDelay = env .example('3000') .asIntPositive(); -/* +/** * The total number of attempts to try a submit job until it completes */ export const submitJobAttempts = env @@ -63,7 +63,7 @@ export const submitJobAttempts = env .example('5') .asIntPositive(); -/* +/** * The maximum number of submit jobs that can be processed in parallel */ export const submitJobConcurrency = env @@ -72,7 +72,7 @@ export const submitJobConcurrency = env .example('5') .asIntPositive(); -/* +/** * The number of completed submit jobs to keep */ export const maxCompletedSubmitJobs = env @@ -81,7 +81,7 @@ export const maxCompletedSubmitJobs = env .example('1000') .asIntPositive(); -/* +/** * The number of failed submit jobs to keep */ export const maxFailedSubmitJobs = env @@ -90,7 +90,7 @@ export const maxFailedSubmitJobs = env .example('1000') .asIntPositive(); -/* +/** * Whether to initialise a scheduler for the submit job queue * There must be at least on queue scheduler to handle retries and you may want * more than one for redundancy @@ -101,7 +101,7 @@ export const submitJobQueueScheduler = env .example('true') .asBoolStrict(); -/* +/** * Whether to convert discovered host addresses to be 'localhost' * This should be set to 'true' when running a docker composed fabric network on the * local system, e.g. using the test network; otherwise should it should be 'false' @@ -112,7 +112,7 @@ export const asLocalhost = env .example('true') .asBoolStrict(); -/* +/** * The Org1 MSP ID */ export const mspIdOrg1 = env @@ -121,7 +121,7 @@ export const mspIdOrg1 = env .example(`${ORG1}MSP`) .asString(); -/* +/** * The Org2 MSP ID */ export const mspIdOrg2 = env @@ -130,7 +130,7 @@ export const mspIdOrg2 = env .example(`${ORG2}MSP`) .asString(); -/* +/** * Name of the channel which the basic asset sample chaincode has been installed on */ export const channelName = env @@ -139,7 +139,7 @@ export const channelName = env .example('mychannel') .asString(); -/* +/** * Name used to install the basic asset sample */ export const chaincodeName = env @@ -148,7 +148,7 @@ export const chaincodeName = env .example('basic') .asString(); -/* +/** * The transaction submit timeout in seconds for commit notification to complete */ export const commitTimeout = env @@ -157,7 +157,7 @@ export const commitTimeout = env .example('300') .asIntPositive(); -/* +/** * The transaction submit timeout in seconds for the endorsement to complete */ export const endorseTimeout = env @@ -166,7 +166,7 @@ export const endorseTimeout = env .example('30') .asIntPositive(); -/* +/** * The transaction query timeout in seconds */ export const queryTimeout = env @@ -175,7 +175,7 @@ export const queryTimeout = env .example('3') .asIntPositive(); -/* +/** * The Org1 connection profile JSON */ export const connectionProfileOrg1 = env @@ -186,7 +186,7 @@ export const connectionProfileOrg1 = env ) .asJsonObject() as Record; -/* +/** * Certificate for an Org1 identity to evaluate and submit transactions */ export const certificateOrg1 = env @@ -195,7 +195,7 @@ export const certificateOrg1 = env .example('"-----BEGIN CERTIFICATE-----\\n...\\n-----END CERTIFICATE-----\\n"') .asString(); -/* +/** * Private key for an Org1 identity to evaluate and submit transactions */ export const privateKeyOrg1 = env @@ -204,7 +204,7 @@ export const privateKeyOrg1 = env .example('"-----BEGIN PRIVATE KEY-----\\n...\\n-----END PRIVATE KEY-----\\n"') .asString(); -/* +/** * The Org2 connection profile JSON */ export const connectionProfileOrg2 = env @@ -215,7 +215,7 @@ export const connectionProfileOrg2 = env ) .asJsonObject() as Record; -/* +/** * Certificate for an Org2 identity to evaluate and submit transactions */ export const certificateOrg2 = env @@ -224,7 +224,7 @@ export const certificateOrg2 = env .example('"-----BEGIN CERTIFICATE-----\\n...\\n-----END CERTIFICATE-----\\n"') .asString(); -/* +/** * Private key for an Org2 identity to evaluate and submit transactions */ export const privateKeyOrg2 = env @@ -233,7 +233,7 @@ export const privateKeyOrg2 = env .example('"-----BEGIN PRIVATE KEY-----\\n...\\n-----END PRIVATE KEY-----\\n"') .asString(); -/* +/** * The host the Redis server is running on */ export const redisHost = env @@ -242,7 +242,7 @@ export const redisHost = env .example('localhost') .asString(); -/* +/** * The port the Redis server is running on */ export const redisPort = env @@ -251,7 +251,7 @@ export const redisPort = env .example('6379') .asPortNumber(); -/* +/** * Username for the Redis server */ export const redisUsername = env @@ -259,12 +259,12 @@ export const redisUsername = env .example('fabric') .asString(); -/* +/** * Password for the Redis server */ export const redisPassword = env.get('REDIS_PASSWORD').asString(); -/* +/** * API key for Org1 * Specify this API key with the X-Api-Key header to use the Org1 connection profile and credentials */ @@ -274,7 +274,7 @@ export const org1ApiKey = env .example('123') .asString(); -/* +/** * API key for Org2 * Specify this API key with the X-Api-Key header to use the Org2 connection profile and credentials */ diff --git a/asset-transfer-basic/rest-api-typescript/src/errors.ts b/asset-transfer-basic/rest-api-typescript/src/errors.ts index 010db75f..cb451f9b 100644 --- a/asset-transfer-basic/rest-api-typescript/src/errors.ts +++ b/asset-transfer-basic/rest-api-typescript/src/errors.ts @@ -8,7 +8,7 @@ import { TimeoutError, TransactionError } from 'fabric-network'; import { logger } from './logger'; -/* +/** * Base type for errors from the smart contract. * * These errors will not be retried. @@ -25,7 +25,7 @@ export class ContractError extends Error { } } -/* +/** * Represents the error which occurs when the transaction being submitted or * evaluated is not implemented in a smart contract. */ @@ -38,7 +38,7 @@ export class TransactionNotFoundError extends ContractError { } } -/* +/** * Represents the error which occurs in the basic asset transfer smart contract * implementation when an asset already exists. */ @@ -51,7 +51,7 @@ export class AssetExistsError extends ContractError { } } -/* +/** * Represents the error which occurs in the basic asset transfer smart contract * implementation when an asset does not exist. */ @@ -64,26 +64,30 @@ export class AssetNotFoundError extends ContractError { } } -/* +/** * Enumeration of possible retry actions. - * - * WithExistingTransactionId - transactions should be retried using the same - * transaction ID to protect against duplicate transactions being committed if - * a timeout error occurs - * - * WithNewTransactionId - transactions which could not be committed due to - * other errors require a new transaction ID when retrying - * - * None - transactions that failed due to a duplicate transaction error, or - * errors from the smart contract, should not be retried */ export enum RetryAction { + /** + * Transactions should be retried using the same transaction ID to protect + * against duplicate transactions being committed if a timeout error occurs + */ WithExistingTransactionId, + + /** + * Transactions which could not be committed due to other errors require a + * new transaction ID when retrying + */ WithNewTransactionId, + + /** + * Transactions that failed due to a duplicate transaction error, or errors + * from the smart contract, should not be retried + */ None, } -/* +/** * Get the required transaction retry action for an error. * * For this sample transactions are considered retriable if they fail with any @@ -92,11 +96,11 @@ export enum RetryAction { * * You might decide to retry transactions which fail with specific errors * instead, for example: - * MVCC_READ_CONFLICT - * PHANTOM_READ_CONFLICT - * ENDORSEMENT_POLICY_FAILURE - * CHAINCODE_VERSION_CONFLICT - * EXPIRED_CHAINCODE + * - MVCC_READ_CONFLICT + * - PHANTOM_READ_CONFLICT + * - ENDORSEMENT_POLICY_FAILURE + * - CHAINCODE_VERSION_CONFLICT + * - EXPIRED_CHAINCODE */ export const getRetryAction = (err: unknown): RetryAction => { if (isDuplicateTransactionError(err) || err instanceof ContractError) { @@ -108,7 +112,7 @@ export const getRetryAction = (err: unknown): RetryAction => { return RetryAction.WithNewTransactionId; }; -/* +/** * Type guard to make catching unknown errors easier */ export const isErrorLike = (err: unknown): err is Error => { @@ -122,7 +126,7 @@ export const isErrorLike = (err: unknown): err is Error => { ); }; -/* +/** * Checks whether an error was caused by a duplicate transaction. * * This is ...painful. @@ -155,13 +159,13 @@ export const isDuplicateTransactionError = (err: unknown): boolean => { return isDuplicate === true; }; -/* +/** * Matches asset already exists error strings from the asset contract * * The regex needs to match the following error messages: - * "the asset %s already exists" - * "The asset ${id} already exists" - * "Asset %s already exists" + * - "the asset %s already exists" + * - "The asset ${id} already exists" + * - "Asset %s already exists" */ const matchAssetAlreadyExistsMessage = (message: string): string | null => { const assetAlreadyExistsRegex = /([tT]he )?[aA]sset \w* already exists/g; @@ -178,13 +182,13 @@ const matchAssetAlreadyExistsMessage = (message: string): string | null => { return null; }; -/* +/** * Matches asset does not exist error strings from the asset contract * * The regex needs to match the following error messages: - * "the asset %s does not exist" - * "The asset ${id} does not exist" - * "Asset %s does not exist" + * - "the asset %s does not exist" + * - "The asset ${id} does not exist" + * - "Asset %s does not exist" */ const matchAssetDoesNotExistMessage = (message: string): string | null => { const assetDoesNotExistRegex = /([tT]he )?[aA]sset \w* does not exist/g; @@ -201,12 +205,12 @@ const matchAssetDoesNotExistMessage = (message: string): string | null => { return null; }; -/* +/** * Matches transaction does not exist error strings from the contract API * * The regex needs to match the following error messages: - * "Failed to get transaction with id %s, error Entry not found in index" - * "Failed to get transaction with id %s, error no such transaction ID [%s] in index" + * - "Failed to get transaction with id %s, error Entry not found in index" + * - "Failed to get transaction with id %s, error no such transaction ID [%s] in index" */ const matchTransactionDoesNotExistMessage = ( message: string @@ -228,11 +232,12 @@ const matchTransactionDoesNotExistMessage = ( return null; }; -/* +/** * Handles errors from evaluating and submitting transactions. * - * Smart contract errors from the the basic asset transfer samples do not use + * Smart contract errors from the basic asset transfer samples do not use * error codes so matching strings is the only option, which is not ideal. + * * Note: the error message text is not the same for the Go, Java, and * Javascript implementations of the chaincode! */ diff --git a/asset-transfer-basic/rest-api-typescript/src/fabric.ts b/asset-transfer-basic/rest-api-typescript/src/fabric.ts index 1a9f8b6e..3b91b0c4 100644 --- a/asset-transfer-basic/rest-api-typescript/src/fabric.ts +++ b/asset-transfer-basic/rest-api-typescript/src/fabric.ts @@ -18,7 +18,7 @@ import { logger } from './logger'; import { handleError } from './errors'; import * as protos from 'fabric-protos'; -/* +/** * Creates an in memory wallet to hold credentials for an Org1 and Org2 user * * In this sample there is a single user for each MSP ID to demonstrate how @@ -55,7 +55,7 @@ export const createWallet = async (): Promise => { return wallet; }; -/* +/** * Create a Gateway connection * * Gateway instances can and should be reused rather than connecting to submit every transaction @@ -89,7 +89,7 @@ export const createGateway = async ( return gateway; }; -/* +/** * Get the network which the asset transfer sample chaincode is running on * * In addion to getting the contract, the network will also be used to @@ -100,7 +100,7 @@ export const getNetwork = async (gateway: Gateway): Promise => { return network; }; -/* +/** * Get the asset transfer sample contract and the qscc system contract * * The system contract is used for the liveness REST endpoint @@ -113,7 +113,7 @@ export const getContracts = async ( return { assetContract, qsccContract }; }; -/* +/** * Evaluate a transaction and handle any errors */ export const evatuateTransaction = async ( @@ -137,7 +137,7 @@ export const evatuateTransaction = async ( } }; -/* +/** * Submit a transaction and handle any errors */ export const submitTransaction = async ( @@ -159,7 +159,7 @@ export const submitTransaction = async ( } }; -/* +/** * Get the validation code of the specified transaction */ export const getTransactionValidationCode = async ( @@ -181,7 +181,7 @@ export const getTransactionValidationCode = async ( return validationCode; }; -/* +/** * Get the current block height * * This example of using a system contract is used for the liveness REST diff --git a/asset-transfer-basic/rest-api-typescript/src/jobs.ts b/asset-transfer-basic/rest-api-typescript/src/jobs.ts index 64307982..51b77b93 100644 --- a/asset-transfer-basic/rest-api-typescript/src/jobs.ts +++ b/asset-transfer-basic/rest-api-typescript/src/jobs.ts @@ -52,7 +52,7 @@ const connection: ConnectionOptions = { password: config.redisPassword, }; -/* +/** * Set up the queue for submit jobs */ export const initJobQueue = (): Queue => { @@ -72,7 +72,7 @@ export const initJobQueue = (): Queue => { return submitQueue; }; -/* +/** * Set up a worker to process submit jobs on the queue, using the * processSubmitTransactionJob function below */ @@ -104,7 +104,7 @@ export const initJobQueueWorker = (app: Application): Worker => { return worker; }; -/* +/** * Process a submit transaction request from the job queue * * The job will be retried if this function throws an error @@ -209,7 +209,7 @@ export const processSubmitTransactionJob = async ( } }; -/* +/** * Set up a scheduler for the submit job queue * * This manages stalled and delayed jobs and is required for retries with backoff @@ -226,7 +226,7 @@ export const initJobQueueScheduler = (): QueueScheduler => { return queueScheduler; }; -/* +/** * Helper to add a new submit transaction job to the queue */ export const addSubmitTransactionJob = async ( @@ -250,7 +250,7 @@ export const addSubmitTransactionJob = async ( return job.id; }; -/* +/** * Helper to update the data for an existing job */ export const updateJobData = async ( @@ -274,7 +274,7 @@ export const updateJobData = async ( await job.update(newData); }; -/* +/** * Gets a job summary * * This function is used for the jobs REST endpoint @@ -325,7 +325,7 @@ export const getJobSummary = async ( return jobSummary; }; -/* +/** * Get the current job counts * * This function is used for the liveness REST endpoint diff --git a/asset-transfer-basic/rest-api-typescript/src/redis.ts b/asset-transfer-basic/rest-api-typescript/src/redis.ts index 35865545..9dfc85bf 100644 --- a/asset-transfer-basic/rest-api-typescript/src/redis.ts +++ b/asset-transfer-basic/rest-api-typescript/src/redis.ts @@ -9,7 +9,7 @@ import IORedis, { Redis, RedisOptions } from 'ioredis'; import * as config from './config'; import { logger } from './logger'; -/* +/** * Check whether the maxmemory-policy config is set to noeviction * * BullMQ requires this setting in redis