feat(cactus-plugin-ledger-connector-cdl): add new connector plugin

- Add new plugin for connecting with CDL service. - It supports as `cactus-plugin-ledger-connector-cdl-socketio` which is now depracated and will be removed shortly. - There are still no automatic tests for this package, only manual script that user can run against CDL instance to see if everything is working. - Fix minor formatting issue in cbdc example (issue from lint) Signed-off-by: Michal Bajer <[email protected]>
hyperledger-cacti · Jan 25, 2024 · 6efd8de · 6efd8de
1 parent a33f30c
commit 6efd8de
Show file tree

Hide file tree

Showing 30 changed files with 3,371 additions and 0 deletions.
diff --git a/.cspell.json b/.cspell.json
@@ -12,6 +12,7 @@
         "anoncreds",
         "ANYFORTX",
         "APIV",
+        "Apim",
         "approveformyorg",
         "Askar",
         "askar",

diff --git a/.../integration/cdl-connector-manual.test.ts → ...ion/cdl-connector-socketio-manual.test.ts b/.../integration/cdl-connector-manual.test.ts → ...ion/cdl-connector-socketio-manual.test.ts
diff --git a/packages/cactus-plugin-ledger-connector-cdl/Dockerfile b/packages/cactus-plugin-ledger-connector-cdl/Dockerfile
@@ -0,0 +1,5 @@
+FROM ghcr.io/hyperledger/cactus-cmd-api-server:v1.0.0
+
+ARG NPM_PKG_VERSION=latest
+
+RUN npm i @hyperledger/cactus-plugin-ledger-connector-cdl@${NPM_PKG_VERSION} --production
diff --git a/packages/cactus-plugin-ledger-connector-cdl/README.md b/packages/cactus-plugin-ledger-connector-cdl/README.md
@@ -0,0 +1,147 @@
+# `@hyperledger/cactus-plugin-ledger-connector-cdl`
+
+This plugin provides `Cacti` a way to interact with Fujitsu CDL networks. Using this you can:
+
+- Register new data trail.
+- Get events.
+- Search for events using header / global data fields as a query.
+
+## Summary
+
+- [Getting Started](#getting-started)
+- [Usage](#usage)
+- [ApiClient](#apiclient)
+- [Runing the tests](#running-the-tests)
+- [Contributing](#contributing)
+- [License](#license)
+- [Acknowledgments](#acknowledgments)
+
+## Getting Started
+
+Clone the git repository on your local machine. Follow these instructions that will get you a copy of the project up and running on
+your local machine for development and testing purposes.
+
+### Prerequisites
+
+In the root of the project to install the dependencies execute the command:
+
+```sh
+npm run configure
+```
+
+## Usage
+
+To use this plugin, import public-api, create new **PluginLedgerConnectorCDL** and initialize it.
+
+```typescript
+const connector = new PluginLedgerConnectorCDL({
+  instanceId: uuidV4(),
+  logLevel,
+  cdlApiGateway: {
+    url: cdlUrl,
+  },
+  cdlApiSubscriptionGateway: {
+    url: cdlSubscriptionUrl,
+  },
+});
+
+// Register endpoints
+await connector.getOrCreateWebServices();
+await connector.registerWebServices(expressApp);
+```
+
+### Configuration
+
+#### Connector Setup
+
+- `logLevel` - connector log level
+- `cdlApiGateway` - configuration of regular CDL endpoint (use it if you want to use access token to authenticate)
+- `cdlApiSubscriptionGateway` - configuration of CDL endpoint for applications (use it if you want to use subscriptionId to authenticate).
+
+#### Gateway Setup
+
+- `url`: Gateway URL
+- `userAgent`: Value of User-Agent header sent to CDL (to identify this client).
+- `skipCertCheck`: Set to true to ignore self-signed and other rejected certificates.
+- `caPath`: CA of CDL API gateway server in PEM format to use.
+- `serverName`: Overwrite server name from cdlApiGateway.url to match one specified in CA.
+
+### Connector Methods
+
+- Connector can be used directly through it's public methods.
+
+#### Methods
+
+```typescript
+async registerHistoryData(args: RegisterHistoryDataRequestV1): Promise<RegisterHistoryDataV1Response>
+async getLineage(args: GetLineageRequestV1): Promise<GetLineageResponseV1>
+async searchLineageByHeader(args: SearchLineageRequestV1): Promise<SearchLineageResponseV1>
+async searchLineageByGlobalData(args: SearchLineageRequestV1): Promise<SearchLineageResponseV1>
+```
+
+## ApiClient
+
+All connector API endpoints are defined in [open-api specification](./src/main/json/openapi.json).
+See [DefaultApi](./src/main/typescript/generated/openapi/typescript-axios/api.ts) for up-to-date listing of supported endpoints.
+
+### REST Functions
+
+- `registerHistoryDataV1`
+- `getLineageV1`
+- `searchLineageByHeaderV1`
+- `searchLineageByGlobalDataV1`
+
+## Running the tests
+
+To check that all has been installed correctly and that the plugin has no errors run jest test suites.
+
+- Run this command at the project's root:
+
+```sh
+npx jest cactus-plugin-ledger-connector-cdl
+```
+
+### Manual Tests
+
+- There are no automatic tests for this plugin because there's no private instance of CDL available at a time.
+- `./src/test/typescript/manual/cdl-connector-manual.test.ts` contains a Jest test script that will check every implemented operation on a running CDL service.
+- **You need access to a running instance of CDL in order to run this script.**
+  - You can check https://en-portal.research.global.fujitsu.com/ for free test access to a service.
+  - Please note that rate limiting set on a service may cause some tests to fail.
+- Before running the script you must update the following variables in it:
+  - `authInfo` - either `accessToken` or `subscriptionKey` based configuration.
+  - `cdlUrl / cdlSubscriptionUrl` - URL to CDL service (only base path)
+- Script can be used as a quick reference for using this connector plugin.
+- Since script is not part of project jest suite, to run in execute the following commands from a package dir:
+  - `npx tsc`
+  - `npx jest dist/lib/test/typescript/manual/cdl-connector-manual.test.js`
+
+### Building/running the container image locally
+
+In the Cactus project root say:
+
+```sh
+DOCKER_BUILDKIT=1 docker build -f ./packages/cactus-plugin-ledger-connector-cdl/Dockerfile . -t CDL_connector
+```
+
+Build with a specific version of the npm package:
+
+```sh
+DOCKER_BUILDKIT=1 docker build --build-arg NPM_PKG_VERSION=0.4.1 -f ./packages/cactus-plugin-ledger-connector-cdl/Dockerfile . -t CDL_connector
+```
+
+## Contributing
+
+We welcome contributions to Hyperledger Cactus in many forms, and there’s always plenty to do!
+
+Please review [CONTIRBUTING.md](../../CONTRIBUTING.md) to get started.
+
+## License
+
+This distribution is published under the Apache License Version 2.0 found in the [LICENSE](../../LICENSE) file.
+
+## Acknowledgments
+
+```
+
+```
diff --git a/packages/cactus-plugin-ledger-connector-cdl/openapitools.json b/packages/cactus-plugin-ledger-connector-cdl/openapitools.json
@@ -0,0 +1,7 @@
+{
+  "$schema": "node_modules/@openapitools/openapi-generator-cli/config.schema.json",
+  "spaces": 2,
+  "generator-cli": {
+    "version": "6.3.0"
+  }
+}
diff --git a/packages/cactus-plugin-ledger-connector-cdl/package.json b/packages/cactus-plugin-ledger-connector-cdl/package.json
@@ -0,0 +1,82 @@
+{
+  "name": "@hyperledger/cactus-plugin-ledger-connector-cdl",
+  "version": "2.0.0-alpha.2",
+  "description": "Allows Cacti nodes to connect to Fujitsu CDL.",
+  "keywords": [
+    "Hyperledger",
+    "Cacti",
+    "Cactus",
+    "Integration",
+    "Blockchain",
+    "Distributed Ledger Technology"
+  ],
+  "homepage": "https://github.com/hyperledger/cacti#readme",
+  "bugs": {
+    "url": "https://github.com/hyperledger/cacti/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hyperledger/cacti.git"
+  },
+  "license": "Apache-2.0",
+  "author": {
+    "name": "Hyperledger Cacti Contributors",
+    "email": "[email protected]",
+    "url": "https://www.hyperledger.org/use/cacti"
+  },
+  "contributors": [
+    {
+      "name": "Please add yourself to the list of contributors",
+      "email": "[email protected]",
+      "url": "https://example.com"
+    },
+    {
+      "name": "Michal Bajer",
+      "email": "[email protected]",
+      "url": "https://www.fujitsu.com/global/"
+    }
+  ],
+  "main": "dist/lib/main/typescript/index.js",
+  "module": "dist/lib/main/typescript/index.js",
+  "browser": "dist/cactus-plugin-ledger-connector-cdl.web.umd.js",
+  "types": "dist/lib/main/typescript/index.d.ts",
+  "files": [
+    "dist/*"
+  ],
+  "scripts": {
+    "codegen": "run-p 'codegen:*'",
+    "codegen:openapi": "npm run generate-sdk",
+    "generate-sdk": "run-p 'generate-sdk:*'",
+    "generate-sdk:typescript-axios": "openapi-generator-cli generate -i ./src/main/json/openapi.json -g typescript-axios -o ./src/main/typescript/generated/openapi/typescript-axios/ --reserved-words-mappings protected=protected --ignore-file-override ../../openapi-generator-ignore",
+    "webpack": "npm-run-all webpack:dev",
+    "webpack:dev": "npm-run-all webpack:dev:node webpack:dev:web",
+    "webpack:dev:node": "webpack --env=dev --target=node --config ../../webpack.config.js",
+    "webpack:dev:web": "webpack --env=dev --target=web --config ../../webpack.config.js"
+  },
+  "dependencies": {
+    "@hyperledger/cactus-common": "2.0.0-alpha.2",
+    "@hyperledger/cactus-core": "2.0.0-alpha.2",
+    "@hyperledger/cactus-core-api": "2.0.0-alpha.2",
+    "axios": "1.6.0",
+    "sanitize-html": "2.7.0"
+  },
+  "devDependencies": {
+    "@types/express": "4.17.19",
+    "@types/node": "18.11.9",
+    "@types/sanitize-html": "2.6.2",
+    "body-parser": "1.20.2",
+    "express": "4.18.2",
+    "jest-extended": "4.0.1",
+    "uuid": "8.3.2"
+  },
+  "engines": {
+    "node": ">=18",
+    "npm": ">=8"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "browserMinified": "dist/cactus-plugin-ledger-connector-cdl.web.umd.min.js",
+  "mainMinified": "dist/cactus-plugin-ledger-connector-cdl.node.umd.min.js",
+  "watch": {}
+}