How to create a 'common package' to share common logic in convector packages? - hyperledger-fabric

Question

I want to create a common package to share common login in convector chain code...this is useful has the project grows and we want to share common blocks of code, utils and other useful code to don't dry the project, or hard-code strings
but how can we do it if convector currently don't support it?

Answer 1

Currently convector can't use common vanilla packages (yet), only controllers,
to work we need to hack some stuff, like create a package that implement a controller, like a fake controller. and follow some steps
thanks to Diego and Walter of Covalent and a few hours
this post belongs to a github project that have a nest.js server, but currently is not created, when I have the link I update this post
first we start to create a lerna package for typescript, by hand
Create lerna common package #convector-rest-sample/common
packages/common/tsconfig.json
{
"extends": "../../tsconfig.json",
"compilerOptions": {
"outDir": "./dist",
"rootDir": "."
},
"include": [
"./src/**/*"
]
}
packages/common/package.json
{
"name": "#convector-rest-sample/common",
"version": "0.1.0",
"main": "dist/src/index",
"types": "dist/src/index",
"files": [
"dist"
],
"scripts": {
"build": "npm run clean && tsc",
"clean": "rm -rf ./dist",
"prepublishOnly": "npm run build"
},
"devDependencies": {
"typescript": "3.4.3"
}
}
Note: the paths "main": "dist/src/index" and "types": "dist/src/index" are important and must point to location of the index file, if we use a wrong path, we get errors using the package
create the index to export package files
packages/common/src/index.ts
export * from './constants';
packages/common/src/constants.ts
// convector model
const CONVECTOR_MODEL_PATH_PREFIX: string = 'io.worldsibu.examples';
const CONVECTOR_MODEL_PATH_PARTICIPANT: string = `${CONVECTOR_MODEL_PATH_PREFIX}.participant`;
const CONVECTOR_MODEL_PATH_PERSON: string = `${CONVECTOR_MODEL_PATH_PREFIX}.person`;
const CONVECTOR_MODEL_PATH_ATTRIBUTE: string = `${CONVECTOR_MODEL_PATH_PREFIX}.attribute`;
const CONVECTOR_MODEL_PATH_X509IDENTITY: string = `${CONVECTOR_MODEL_PATH_PREFIX}.x509identity`;
export const appConstants = {
CONVECTOR_MODEL_PATH_PARTICIPANT,
CONVECTOR_MODEL_PATH_PERSON,
CONVECTOR_MODEL_PATH_ATTRIBUTE,
CONVECTOR_MODEL_PATH_X509IDENTITY,
};
now add the common package to all packages in monorepo
# add to all packages (without scope)
$ npx lerna add #convector-rest-sample/common#0.1.0
# to prevent some problems always use same version has in local package
# clean and bootstrap
$ npx lerna clean -y && npx lerna bootstrap
optional can use --scope to add only to desired packages
# add to all packages (with scope)
$ npx lerna add #convector-rest-sample/common#0.1.0 --scope server --no-bootstrap
$ npx lerna add #convector-rest-sample/common#0.1.0 --scope participant-cc --no-bootstrap
$ npx lerna add #convector-rest-sample/common#0.1.0 --scope person-cc --no-bootstrap
# clean and bootstrap
$ npx lerna clean -y && npx lerna bootstrap --hoist
now test #convector-rest-sample/common in server, add this lines to top of packages/server/src/app.ts
to confirm that everything is working has expected
Note: if don't have a server, skip this step right to Use common package inside ChainCode section
import { appConstants as c } from '#convector-rest-sample/common';
debugger;
Logger.log(JSON.stringify(c, undefined, 2));
now launch server with debugger, and inspect c object or view log result
$ npx lerna run start:debug --scope server --stream
if outputs appConstants we are ready to go, and common package works has expected
Use common package inside ChainCode
To use common package inside chaincode, is very tricky, and I lost a few hours to get it work, thanks to Walter and Diego from WorldSibu I get it.
The problem is that currently, in convector there is no easy way to use packages, that are not controllers, for this to work we must create a fake controller in #convector-rest-sample/common to put it to work
first install required controller dependency in our #convector-rest-sample/common, this is required ut use { Controller, Invokable }
# install dependency
$ npx lerna add #worldsibu/convector-core --scope #convector-rest-sample/common
next we must create a fake controller in packages/common/src/common.controller.ts
import { Controller, Invokable } from '#worldsibu/convector-core';
#Controller('common')
export class CommonController {
#Invokable()
public async greeting() {
return 'Hello from CommonController';
}
}
don't forget to add export * from './common.controller'; to packages/common/src/index.ts to export controller
export * from './constants';
export * from './common.controller';
after that we must change chaincode.config.json to add the fake controller, this is a hell of a hack, we use a fake controller to force the #convector-rest-sample/common to be copied inside chaincode-person dir, without this, the #convector-rest-sample/common is not copied and we have a broken chain code when we try deploy it with cc:start or cc:upgrade it always show the annoying error npm ERR! 404 Not Found: #convector-rest-sample/common#0.1.0
first change chaincode.config.json
Tip: if don't have it in project, copy org1.person.config.json to chaincode.config.json and move on....
in my case I have only the legacy files org1.participant.config.json, org1.person.config.json, org2.participant.config.json and org2.person.config.json
this files can be deleted (Diego tip)
ok let's change chaincode.config.json and add another controller above person-cc
"controllers": [
{
"name": "participant-cc",
"version": "file:./packages/participant-cc",
"controller": "ParticipantController"
},
{
"name": "person-cc",
"version": "file:./packages/person-cc",
"controller": "PersonController"
},
// BO : ADD THIS
{
"name": "#convector-rest-sample/common",
"version": "file:./packages/common",
"controller": "CommonController"
}
// EO : ADD THIS
],
Note: this is another clever tricky part, the name is the package name, like the one we use in imports, version is the path location inside of our build chaincode-person
before build chaincode we must change our models to use the new common constants from #convector-rest-sample/common ex c.CONVECTOR_MODEL_PATH_X509IDENTITY, currently this common package only use simple constants, to keep it simple, the point is created common logic for all the packages, rest-server, front-end, packages-cc, cli-tools, etc
packages/participant-cc/src/participant.model.ts
import { appConstants as c } from '#convector-rest-sample/common';
...
export class x509Identities extends ConvectorModel<x509Identities>{
#ReadOnly()
public readonly type = c.CONVECTOR_MODEL_PATH_X509IDENTITY;
...
export class Participant extends ConvectorModel<Participant> {
#ReadOnly()
public readonly type = c.CONVECTOR_MODEL_PATH_PARTICIPANT;
...
packages/person-cc/src/person.model.ts
import { appConstants as c } from '#convector-rest-sample/common';
...
export class Attribute extends ConvectorModel<Attribute>{
#ReadOnly()
#Required()
public readonly type = c.CONVECTOR_MODEL_PATH_ATTRIBUTE;
...
export class Person extends ConvectorModel<Person> {
#ReadOnly()
#Required()
public readonly type = 'io.worldsibu.example.person';
...
now we can cc:package the chaincode chaincode-person, this will package the chaincode with our #convector-rest-sample/common inside it with packages person-cc and participant-cc using our #convector-rest-sample/common constants
# first remove chaincode (optional)
$ rm chaincode-person -r
# now manually invoke package command
$ npm run cc:package -- person org1
after package our chaincode is advised to check if common package is copied to chaincode-person folder to the right path
$ ls -la chaincode-person/packages
chaincode-person/packages/#convector-rest-sample
chaincode-person/packages/participant-cc
chaincode-person/packages/person-cc
another good practice is check if inside chaincode-person folder, in file chaincode-person/package.json, if our #convector-rest-sample/common was added to dependencies, in above json block we can see cc:package script add line "#convector-rest-sample/common": "file:./package/#convector-rest-sample/common", this is created based on our changes in chaincode.config.json remember, when we add the fake controller
"dependencies": {
"#theledger/fabric-chaincode-utils": "^4.0.1",
"#worldsibu/convector-core": "^1.3.3",
"#worldsibu/convector-storage-stub": "^1.3.3",
"reflect-metadata": "^0.1.12",
"tslib": "^1.9.0",
"participant-cc": "file:./packages/participant-cc",
"person-cc": "file:./packages/person-cc",
// BO: magic line here
"#convector-rest-sample/common": "file:./packages/#convector-rest-sample/common"
// EO: magic line here
},
done now we can deploy our chaincode with cc:start or cc:upgrade
Tip: if is first time use cc:start, if not use cc:package
to check that everything is fine from start, we restart our hyperledger stack, and start from the beginning, warning it destroy all data, if don't want to destroy data don't fire npm run env:restart and use cc:upgrade, more above
# this recreate environment and destroy all data
$ npm run env:restart
$ npm run cc:start -- person
# seed ledger
$ npm run seed
# create couchdb views
$ ./views/install.sh
# invoke person_create
$ npx hurl invoke person person_create "{ \"id\": \"1-100-103\", \"firstname\": \"Pete\", \"lastname\": \"Doe\", \"username\": \"pete\", \"password\": \"12345678\", \"email\": \"pete.doe#example.com\"}" -u admin
# invoke some stuff (wait for first invoke finish)
$ npx hurl invoke person person_getAll
done, everything is working has expected and we have a #convector-rest-sample/common package implemented.
if we check couchdb 1-100-103 person, we can check that is using type "type": "io.worldsibu.examples.person" that comes from our constants in our #convector-rest-sample/common, proving that it gets its value from #convector-rest-sample/common, believe me, if it won't wont find #convector-rest-sample/common it crash.....simple
for future changes in chaincode, upgrade it with above command
# upgrade chaincode
$ npm run cc:upgrade -- person 1.1
we are done........
Use scripts to copy other files to chaincode
another thing that I tried to hack before find the solution, is using npm scripts but it won't work because we need the modified chaincode-person/package.json with "#convector-rest-sample/common": "file:./packages/#convector-rest-sample/common" in the dependencies, but I try it......
leave it here, maybe can be useful for other kind of stuff, like copy other type of stuff
{
"scripts": {
...
"cc:package": "f() { npm run lerna:build; chaincode-manager --update --config ./$2.$1.config.json --output ./chaincode-$1 package; npm run copy:indexes -- $1; npm run copy:package:common -- $1; }; f",
...
"copy:package:common": "f () { mkdir -p ./chaincode-$1/node_modules/#convector-rest-sample/; cp -r ./packages/common/ ./chaincode-$1/node_modules/#convector-rest-sample/; }; f"
...
note for npm run copy:package:common -- $1; in "cc:package", and cp -r ./packages/common/ ./chaincode-$1/node_modules/#convector-rest-sample/; }; in "copy:package:common", it works, but won't modify chaincode-person/package.json with lines
"dependencies": {
"#theledger/fabric-chaincode-utils": "^4.0.1",
"#worldsibu/convector-core": "^1.3.3",
"#worldsibu/convector-storage-stub": "^1.3.3",
"reflect-metadata": "^0.1.12",
"tslib": "^1.9.0",
"participant-cc": "file:./packages/participant-cc",
"person-cc": "file:./packages/person-cc",
// BO: magic line here
"#convector-rest-sample/common": "file:./packages/#convector-rest-sample/common"
// EO: magic line here
}
Clean Up
to finish we can remove the legacy files org1.participant.config.json org1.person.config.json org2.person.config.json org2.participant.config.json, now we use the config file chaincode.config.json (thanks for the tip Diego)
# remove legacy files
rm org1.participant.config.json org1.person.config.json org2.person.config.json org2.participant.config.json
Note: don't forget to update packages.json "cc:package" with new ./chaincode.config.json file
package.json
"cc:package": "f() { npm run lerna:build; chaincode-manager --update --config ./chaincode.config.json --output ./chaincode-$1 package; npm run copy:indexes -- $1; }; f",
to finish thanks to all the kindly people of Covalent
UPDATE: in a fresh project/clone if I try to lerna bootstrap I get the below error
$ lerna bootstrap
src/participant.controller.ts:1:35 - error TS2307: Cannot find module '#convector-sample/common'.
1 import { appConstants as c } from '#convector-sample/common';
this is because the package require build before it's used
# build common library: this is required on fresh clones before lerna boostrap
$ npx lerna run build --scope #convector-sample/common --stream
now it works
$ lerna bootstrap
...
lerna success Bootstrapped 6 packages