Henson Project Preset for MRM

This mrm preset enforces Henson node.js project template.

Configuration

• type: Type of project, can be 'lib', 'service'
• webapp: Type of web app if a web app is included in project, can be 'react', 'ejs'
• branch: Release branch, can be 'master', 'dev' or 'adp'. It must match the beginning of git branch name.
• excludeBundledDependencies: List the dependencies (in node_modules) which should be excluded from bundledDependencies, so that they won't be packed into RPM
• logFileName: By default service log file use package name. It can be override by this configuration.
• targetES: Which ES standard that Typescript will be compiled to, supported standards are es5 and es2017, by default, es2017 will be used.

Tasks

All

The alias all includes all tasks except validate.

Base

Setup project scaffold. Usually it's the first task for a new project.

• Setup project to be updatable with mrm (this tool)
• Setup test framework using mocha and chai
• Create NPM scipts: test, testall and build
• Create NPM script: cpd - Find copy-paste (duplicated) code

TypeScript

• Setup TypeScript compiler
• Setup linting
• Create NPM script: build

Native

Setup node.js native addon build step.

CI

Setup continuous integration.

• Create NPM script: ci
• Create NPM script: npm_publish - Publish package to NPM repository for project of lib type.

Dependency

Update project dependencies version to align with product FOSS list and recommendations. It requires configuration branch.

It also updates package.json to set all dependencies and optionalDependencies into bundledDependencies, except which are listed in configuration excludeBundledDependencies.

License

No License.

Docker

Setup standard docker development environment

• Create NPM script: docker

RPM

Build RPM package for project of service type.

• Create NPM script: rpm (deprecated by gitlab:rpm)

The RPM package contains:

• Compiled JavaScript files and other source files defined in .npmignore
• Bundled node modules defined in bundleDependencies property in package.json
• Non-JS project files under folder rpm/content/ (need to be copied by commands in rpm.spec)

GitLab

Setup GitLab project CI and configurations. RPM or NPM publish is included in CI pipeline.

• Create NPM script: gitlab:rpm

Document

Setup automatic document generation workflow:

• Generate table of content for markdown
• Generate UML diagram from plantuml source
• Generate API document from Swagger 2.0/OpenAPI 3.0 yaml

• Create NPM script: doc (doc:*)

Validate

Validate configuration.

Generate Source Code from API docs

Basic API Source Code

Generate 2 types of source code from the Swagger 2.0/OpenAPI 3.0 yaml files in the doc/api folder automatically.

• Typescript interfaces
• Joi schema definitions

Any other source files can import these interfaces and schemas. The API definitions and the implements will be aligned if using these source files.

The generated source code files will be located in src/generated with the similar file structure as doc/api. All of them will be IGNORED in git commits.

Warning Don't edit all the generated files and don't add any other source files in the folder src/generated as the folder will be regenerated for every compilation and build.

A directory structure example is as below.

doc/api/
├── README.md
└── pushtokenmgmt
    ├── common.json        # common.json is an reference that is used in external.yaml & internal.yaml
    ├── external.yaml
    └── internal.yaml
src/generated/
└── pushtokenmgmt
    ├── common.ts          # Typescript interfaces are generated from 'common.json'
    ├── external           # external is generated from 'external.yaml'
    │   ├── api_definitions.ts
    │   └── joi_schemas.ts
    └── internal           # internal is generated from 'internal.yaml'
        ├── api_definitions.ts
        └── joi_schemas.ts

Express Router/App Access-Layer Source Code

Access-layer source code can be generated by yarn apicode:generate for OpenAPI 3.0 yaml files with x-henson-api-info extension.

The x-henson-api-info extension defines API info as below.

• External API: A Henson service that listens HTTP/HTTPS ports of intranet-network or access-network.

x-henson-api-info:
  network: intranet-network
  basePath: /spp/token/v2

• Internal API: A Henson service that listens HTTP/HTTPS ports of internal-data-network.

x-henson-api-info:
  network: internal-data-network
  basePath: /spp/token/v2
  port: 9320

If the YAML is 'xxx.yaml', generated code include below types.

| Source Code | Type | Can Be Manually Updated? | | ------------------------------------ | ------------------------ | ------------------------ | | src/access/<xxx>router.ts | Express Router | No | | src/access/<xxx>routerprocessor.ts | Express Router Processor | Yes | | src/<xxx>app.ts | Express App | No | | src/<xxx>appprocessor.ts | Express App Processor | Yes | | src/index.ts | Main | No |

• Express Router
  • Validation Joi Schemas
  • Express Router Function including below code for each operation (organized by OpenAPI operationId)
    • Validation Function: validate<OperationID>
    • Business Function Entry defined in Express Router Processor: processor.process<OperationID>
• Express Router Processor
  • Business Function prototype: process<OperationID> (Require developer to implement and the update won't be overwritten).
• Express App
  • Express Server: server
  • Server Start Routine: start
• Express App Processor (Require developer to implement and the update won't be overwritten)
  • Customized Express Handlers
    • useCustomizedHandlerBeforeRouter
    • useCustomizedHandlerAfterRouter
  • Error Handler: errorHandler
  • Health Check Handler: healthCheck
  • Server Options (External Service Only)
    • getHttpServerOptions
    • getHttpsServerOptions
• Main
  • Main Routine Code: Start all API services.

A directory structure example is as below.

doc/api/
├── README.md
├── petstore.yaml
└── pushtokenmgmt
    ├── common.json
    ├── external.html
    ├── external.yaml
    ├── internal.html
    └── internal.yaml
src
├── access                              # Access Layer Code
│   ├── externalrouter.ts               # Express Router Source Code for external.yaml
│   ├── externalrouterprocessor.ts      # Express Router Processor Source Code for external.yaml
│   ├── internalrouter.ts
│   ├── internalrouterprocessor.ts
│   ├── petstorerouter.ts
│   └── petstorerouterprocessor.ts
├── business                            # Business Source Code that should be manully composed by developers and called by Access layer code
│   ├── external.ts
|   ├── internal.ts
|   └── petstore.ts
├── externalapp.ts                      # Express App Source Code for external.yaml
├── externalappprocessor.ts             # Express App Processor Source Code for external.yaml
├── internalapp.ts
├── internalappprocessor.ts
├── index.ts
├── petstoreapp.ts
└── petstoreappprocessor.ts

Preset Development

Check outdated dependencies version

Run ./dev_up.sh to start node.js docker container.

Inside container, run:

yarn install
yarn checkdep master

Test Preset Locally

Since there is no unit test in preset itself, when making modification to preset, you have to verify preset locally with a project before publishing the preset.

The verification requires Node.js environment has been installed on your host, not only Docker env. And also mrm needs to be installed globally:

npm install -g mrm

The procedure to verify preset:

1. Change preset version to dev in package.json of @anpingli/mrm-preset.
2. Pick a project to verify preset, suppose it's on <rootpath>/projects/helloworld and the preset is on <rootpath>/projects/henson-mrm-preset
3. On bash (not in Docker container), run

   $ cd <rootpath>/projects/helloworld
   $ mrm all --dir ../henson-mrm-preset

   Where ../henson-mrm-preset is the relative path to preset project.
4. Verify target project in Docker dev environment
5. In case preset modified GitLab CI related setting, you needs to push target project to GitLab to see if it works fine.
6. After preset is verified, update its version (from dev) and publish.
7. Apply latest preset to test project again by repeat step 3.