From 54cb147beeb9ff90ad059dbbe9c68963bf9adb7b Mon Sep 17 00:00:00 2001 From: Taku Shimosawa Date: Fri, 24 Aug 2018 14:24:19 -0700 Subject: [PATCH] [FABN-891] Make documentation and types consistent This CR fixes inconsistency between documentation and type definitions. This includes: - Fix for the name of some objects (e.g. "Options" -> "Opts") - Add some missing fields in the objects in doc or type - Fix types of some fields in the documentation (e.g. "Peer[]" -> "Peer[] | string[]") - Remove duplicated documentation (ChaincodeInfo) - Remove excess fields from type (and test) FABN-891 #done Change-Id: Id73ee7e5507da5a4c2411445490152cfbe1ed86e Signed-off-by: Taku Shimosawa --- fabric-client/lib/Channel.js | 27 +++++++--------- fabric-client/lib/Client.js | 17 +++++----- fabric-client/lib/Orderer.js | 1 + fabric-client/types/base.d.ts | 10 ++++-- fabric-client/types/index.d.ts | 59 +++++++++++++++++----------------- test/typescript/test.ts | 3 +- 6 files changed, 61 insertions(+), 56 deletions(-) diff --git a/fabric-client/lib/Channel.js b/fabric-client/lib/Channel.js index ddff8bc6da..274b830b6e 100755 --- a/fabric-client/lib/Channel.js +++ b/fabric-client/lib/Channel.js @@ -358,13 +358,6 @@ const Channel = class { return this._name; } - /** - * @typedef {Object} ChaincodeInfo Object used internally to store chaincodes - * names and versions found on this channel. - * @property {string} name - The name of the chaincode - * @property {string} version - The version of the chaincode - */ - /** * @typedef {Object} DiscoveryResultMSPConfig * @property {string} rootCerts List of root certificates trusted by this MSP. @@ -1304,7 +1297,7 @@ const Channel = class { /** * @typedef {Object} JoinChannelRequest - * @property {Peer[]} targets - Optional. An array of Peer objects or Peer names that will + * @property {Peer[] | string[]} targets - Optional. An array of Peer objects or Peer names that will * be asked to join this channel. When using Peer names or left * empty (use default targets) there must be a loaded network * configuration. @@ -2046,9 +2039,9 @@ const Channel = class { /** * @typedef {Object} ChaincodeInstantiateUpgradeRequest - * @property {Peer[]} targets - Optional. An array of endorsing - * {@link Peer} objects as the targets of the request. When this - * parameter is omitted the target list will include peers assigned + * @property {Peer[] | string[]} targets - Optional. An array of endorsing + * {@link Peer} objects or peer names as the targets of the request. + * When this parameter is omitted the target list will include peers assigned * to this channel instance that are in the endorsing role. * @property {string} chaincodeType - Optional. Type of chaincode. One of * 'golang', 'car', 'java' or 'node'. Default is 'golang'. Note that 'java' @@ -2247,7 +2240,7 @@ const Channel = class { /** * @typedef {Object} ChaincodeInvokeRequest - * @property {Peer[]} targets - Optional. The peers that will receive this request, + * @property {Peer[] | string[]} targets - Optional. The peers that will receive this request, * when not provided the list of peers added to this channel object will * be used. When this channel has been initialized using the discovery * service the proposal will be sent to the peers on the list provided @@ -2412,12 +2405,12 @@ const Channel = class { /** * @typedef {Object} TransactionRequest - * @property {array} proposalResponses - An array of or a single + * @property {ProposalResponse[]} proposalResponses - An array of or a single * {@link ProposalResponse} object containing the response from the * [endorsement]{@link Channel#sendTransactionProposal} call - * @property {Object} proposal - A Proposal object containing the original + * @property {Proposal} proposal - A Proposal object containing the original * request for endorsement(s) - * @property {Object} txID - Optional. - Must be the transaction ID object + * @property {TransactionId} txID - Optional. - Must be the transaction ID object * used in the proposal endorsement. The transactionID will * only be used to determine if the signing of the request * should be done by the admin identity or the user assigned @@ -3147,6 +3140,10 @@ function loadConfigValue(config_items, versions, config_value, group_name, org, * event listener registration? All peers can produce events, but the * appliatiion typically only needs to connect to one. * Default: true + * + * @property {boolean} discover - Optional. This peer may be the target of service + * discovery. + * Default: true */ /** diff --git a/fabric-client/lib/Client.js b/fabric-client/lib/Client.js index 3433a8b9f5..88f36e83a6 100644 --- a/fabric-client/lib/Client.js +++ b/fabric-client/lib/Client.js @@ -624,7 +624,7 @@ const Client = class extends BaseClient { /** * @typedef {Object} ChannelRequest * @property {string} name - Required. The name of the new channel - * @property {Orderer} orderer - Required. An Orderer object representing the + * @property {Orderer | string} orderer - Required. An Orderer object or an orderer name representing the * orderer node to send the channel create request * @property {byte[]} envelope - Optional. Bytes of the envelope object containing all * required settings and signatures to initialize this channel. This envelope @@ -634,8 +634,8 @@ const Client = class extends BaseClient { * @property {byte[]} config - Optional. Protobuf ConfigUpdate object extracted from a ConfigEnvelope * created by the configtxgen tool. See [extractChannelConfig()]{@link Client#extractChannelConfig}. * The ConfigUpdate object may also be created by the configtxlator tool. - * @property {ConfigSignature[]} signatures - Required. The list of signatures required by the - * channel creation or update policy when using the `config` parameter. + * @property {ConfigSignature[] | string[]} signatures - Required. The list of signatures required by the + * channel creation or update policy when using the `config` parameter. * @property {TransactionID} txId - Required. TransactionID object with the transaction id and nonce */ @@ -895,8 +895,8 @@ const Client = class extends BaseClient { /** * @typedef {Object} ChaincodeInstallRequest - * @property {Peer[]} targets - Optional. An array of Peer objects where the - * chaincode will be installed. When excluded, the peers assigned + * @property {Peer[] | string[]} targets - Optional. An array of Peer objects or peer names + * where the chaincode will be installed. When excluded, the peers assigned * to this client's organization will be used as defined in the * network configuration. If the 'channelNames' property is included, * the target peers will be based the peers defined in the channels. @@ -926,6 +926,7 @@ const Client = class extends BaseClient { * by this property and in this client's organization and that are * in the endorsing or chain code query role on the named channel * will be selected. + * @property {TransactionID} txId - Optional. TransactionID object for this request. */ /** @@ -933,7 +934,7 @@ const Client = class extends BaseClient { * standard array of objects. * * @typedef {array} ProposalResponseObject - * @property {array} index:0 - Array of ProposalResponse objects from the + * @property {ProposalResponse[]} index:0 - Array of ProposalResponse objects from the * endorsing peers * @property {Object} index:1 - The original Proposal object needed when * sending the transaction request to the orderer @@ -1450,8 +1451,8 @@ const Client = class extends BaseClient { /** * @typedef {Object} UserOpts - * @property {string} username {string} - the user name used for enrollment - * @property {string} mspid {string} - the MSP id + * @property {string} username - the user name used for enrollment + * @property {string} mspid - the MSP id * @property {CryptoContent} cryptoContent - the private key and certificate * @property {boolean} skipPersistence - whether to save this new user object into persistence. */ diff --git a/fabric-client/lib/Orderer.js b/fabric-client/lib/Orderer.js index e7ed2cc7b1..d576fc60a6 100644 --- a/fabric-client/lib/Orderer.js +++ b/fabric-client/lib/Orderer.js @@ -97,6 +97,7 @@ class Orderer extends Remote { /** * @typedef {Object} BroadcastResponse * @property {string} status - Value is 'SUCCESS' or a descriptive error string + * @property {string} info - Optional. Additional information about the status */ /** diff --git a/fabric-client/types/base.d.ts b/fabric-client/types/base.d.ts index 5080ef53d9..2451d6371b 100644 --- a/fabric-client/types/base.d.ts +++ b/fabric-client/types/base.d.ts @@ -1,4 +1,10 @@ -import { ICryptoSuite, ICryptoKeyStore, IKeyValueStore } from 'fabric-client'; +/** + * Copyright 2018 Zhao Chaoyi, All Rights Reserved. + * + * SPDX-License-Identifier: Apache-2.0 + */ + +import { CryptoSetting, ICryptoSuite, ICryptoKeyStore, IKeyValueStore } from 'fabric-client'; export abstract class BaseClient { constructor(); @@ -6,7 +12,7 @@ export abstract class BaseClient { static addConfigFile(path: string): void; static getConfigSetting(name: string, default_value?: any): any; static setConfigSetting(name: string, value: any): void; - static newCryptoSuite(): ICryptoSuite; + static newCryptoSuite(setting?: CryptoSetting): ICryptoSuite; static newCryptoKeyStore(obj?: { path: string }): ICryptoKeyStore; static newDefaultKeyValueStore(obj?: { path: string }): Promise; static normalizeX509(raw: string): string; diff --git a/fabric-client/types/index.d.ts b/fabric-client/types/index.d.ts index 142b8db317..065fb2958f 100644 --- a/fabric-client/types/index.d.ts +++ b/fabric-client/types/index.d.ts @@ -1,17 +1,7 @@ /** * Copyright 2017 Kapil Sachdeva All Rights Reserved. * - * Licensed under the Apache License, Version 2.0 (the "License"); - * you may not use this file except in compliance with the License. - * You may obtain a copy of the License at - * - * http://www.apache.org/licenses/LICENSE-2.0 - * - * Unless required by applicable law or agreed to in writing, software - * distributed under the License is distributed on an "AS IS" BASIS, - * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - * See the License for the specific language governing permissions and - * limitations under the License. + * SPDX-License-Identifier: Apache-2.0 */ import FabricCAServices = require('fabric-ca-client'); @@ -26,7 +16,7 @@ declare class ChaincodeChannelEventHandle { } declare class Remote { - constructor(url: string, opts?: Client.ConnectionOptions); + constructor(url: string, opts?: Client.ConnectionOpts); getName(): string; setName(name: string): void; getUrl(): string; @@ -42,10 +32,10 @@ declare class Client extends BaseClient { setDevMode(mode: boolean): void; newChannel(name: string): Client.Channel; getChannel(name?: string, throwError?: boolean): Client.Channel; - newPeer(url: string, opts?: Client.ConnectionOptions): Client.Peer; + newPeer(url: string, opts?: Client.ConnectionOpts): Client.Peer; getPeer(name: string): Client.Peer; getPeersForOrg(mspid?: string): Client.Peer[]; - newOrderer(url: string, opts?: Client.ConnectionOptions): Client.Orderer; + newOrderer(url: string, opts?: Client.ConnectionOpts): Client.Orderer; getOrderer(name: string): Client.Orderer; getPeersForOrgOnChannel(channel_names: string | string[]): Client.ChannelPeer[]; getCertificateAuthority(): FabricCAServices; @@ -67,7 +57,7 @@ declare class Client extends BaseClient { getUserContext(name: string, checkPersistence?: boolean): Promise | Client.User; loadUserFromStateStore(name: string): Promise; getStateStore(): Client.IKeyValueStore; - createUser(opts: Client.UserOptions): Promise; + createUser(opts: Client.UserOpts): Promise; getTargetPeers(request_targets: string | string[] | Client.Peer | Client.Peer[]): Client.Peer[]; getTargetOrderers(request_orderer: string | Client.Orderer): Client.Orderer; @@ -116,6 +106,13 @@ declare namespace Client { setCryptoKeyStore(cryptoKeyStore: ICryptoKeyStore): void; } + export interface CryptoSetting { + software: boolean; + keysize: number; + algorithm: string; + hash: string; + } + export interface UserConfig { enrollmentID: string; name: string @@ -123,7 +120,7 @@ declare namespace Client { affiliation?: string; } - export interface ConnectionOptions { + export interface ConnectionOpts { pem?: string; clientKey?: string; clientCert?: string; @@ -221,6 +218,7 @@ declare namespace Client { chaincodeQuery?: boolean; ledgerQuery?: boolean; eventSource?: boolean; + discover?: boolean; } export class ChannelPeer { @@ -269,20 +267,19 @@ declare namespace Client { export interface TransactionRequest { proposalResponses: ProposalResponse[]; proposal: Proposal; - admin?: boolean; txId?: TransactionId; orderer?: string | Orderer; } export interface BroadcastResponse { status: string; - info: string; + info?: string; } export type ProposalResponseObject = [Array, Client.Proposal]; export interface OrdererRequest { - txId: TransactionId; + txId?: TransactionId; orderer?: string | Orderer; } @@ -316,7 +313,7 @@ declare namespace Client { export interface ProposalResponse { version: number; timestamp: Date; - response: ResponseObject; + response: Response; payload: Buffer; endorsement: any; } @@ -332,11 +329,11 @@ declare namespace Client { close(): void; checkConnection(force_reconnect: boolean): string; registerChaincodeEvent(ccid: string, eventname: string, onEvent: (event: ChaincodeEvent, block_number?: number, tx_id?: string, tx_status?: string) => void, - onError?: (err: Error) => void, options?: RegistrationOptions): ChaincodeChannelEventHandle; + onError?: (err: Error) => void, options?: RegistrationOpts): ChaincodeChannelEventHandle; unregisterChaincodeEvent(handle: ChaincodeChannelEventHandle, throwError?: boolean): void; - registerBlockEvent(onEvent: (block: Block) => void, onError?: (err: Error) => void, options?: RegistrationOptions): number; + registerBlockEvent(onEvent: (block: Block) => void, onError?: (err: Error) => void, options?: RegistrationOpts): number; unregisterBlockEvent(block_registration_number: number, throwError: boolean): void; - registerTxEvent(txId: string, onEvent: (txId: string, code: string, block_number: number) => void, onError?: (err: Error) => void, options?: RegistrationOptions): string; + registerTxEvent(txId: string, onEvent: (txId: string, code: string, block_number: number) => void, onError?: (err: Error) => void, options?: RegistrationOpts): string; unregisterTxEvent(txId: string, throwError?: boolean): void; } @@ -346,7 +343,7 @@ declare namespace Client { } export class Peer extends Remote { - constructor(url: string, opts?: ConnectionOptions); + constructor(url: string, opts?: ConnectionOpts); close(): void; setRole(role: string, isIn: boolean): void; isInRole(role: string): boolean; @@ -355,7 +352,7 @@ declare namespace Client { } export class Orderer extends Remote { - constructor(url: string, opts?: ConnectionOptions); + constructor(url: string, opts?: ConnectionOpts); close(): void; sendBroadcast(envelope: Buffer): Promise; sendDeliver(envelope: Buffer): Promise; @@ -394,6 +391,7 @@ declare namespace Client { export interface ChaincodeInstallRequest { targets?: Peer[] | string[]; chaincodePath: string; + metadataPath?: string; chaincodeId: string; chaincodeVersion: string; chaincodePackage?: Buffer; @@ -408,6 +406,7 @@ declare namespace Client { chaincodeId: string; chaincodeVersion: string; txId: TransactionId; + 'collections-config'?: string; transientMap?: any; fcn?: string; args?: string[]; @@ -421,6 +420,8 @@ declare namespace Client { transientMap?: any; fcn?: string; args: string[]; + ignore?: string[]; + preferred?: string[]; } export interface ChaincodeQueryRequest { @@ -448,7 +449,7 @@ declare namespace Client { password?: string; } - export interface UserOptions { + export interface UserOpts { username: string; mspid: string; cryptoContent: CryptoContent; @@ -488,7 +489,7 @@ declare namespace Client { channels: ChannelInfo[]; } - export interface ResponseObject { + export interface Response { status: Client.Status; message: string; payload: Buffer; @@ -505,9 +506,9 @@ declare namespace Client { signature_header: ByteBuffer; } - export interface RegistrationOptions { + export interface RegistrationOpts { startBlock?: number; - endBlock?: number; + endBlock?: number | "newest"; unregister?: boolean; disconnect?: boolean; } diff --git a/test/typescript/test.ts b/test/typescript/test.ts index eb6e1cf999..da5fd1243b 100644 --- a/test/typescript/test.ts +++ b/test/typescript/test.ts @@ -433,8 +433,7 @@ test('use the connection profile file', (t) => { } let request: TransactionRequest = { proposalResponses: proposalResponses, - proposal: proposal, - admin: true + proposal: proposal }; let promises = [];