Merge pull request #1 from ukitgroup/http-client

feat(http client): http client module based on got lib

Author: Goodluckhf

.eslintrc.js

@@ -0,0 +1,60 @@
+module.exports = {
+  parser: "@typescript-eslint/parser",
+  extends: [
+    "eslint-config-airbnb-base",
+    "plugin:@typescript-eslint/recommended",
+    "prettier/@typescript-eslint",
+    "plugin:prettier/recommended",
+    "plugin:import/typescript"
+  ],
+  parserOptions: {
+    ecmaVersion: 2018,
+    sourceType: "module"
+  },
+  rules: {
+    "@typescript-eslint/no-parameter-properties": [
+      "error",
+      {
+        allows: ["private readonly"]
+      }
+    ],
+    "@typescript-eslint/explicit-function-return-type": "off",
+    "@typescript-eslint/interface-name-prefix": "off",
+    "@typescript-eslint/no-unused-vars": "error",
+    "import/prefer-default-export": "off",
+    "no-useless-constructor": "off",
+    "no-empty-function": "off",
+    "class-methods-use-this": "off",
+    "new-cap": "off",
+    "@typescript-eslint/camelcase": "off",
+    "no-underscore-dangle": "off",
+    "import/extensions": [
+      "error",
+      "ignorePackages",
+      {
+        js: "never",
+        jsx: "never",
+        ts: "never",
+        tsx: "never",
+        mjs: "never"
+      }
+    ]
+  },
+  overrides: [
+    {
+      files: ["*.test.{ts,js}", "*.spec.{ts,js}", "test/**/*.{ts,js}"],
+      env: {
+        jest: true
+      },
+      rules: {
+        "no-console": "off",
+        "import/no-extraneous-dependencies": "off",
+        "@typescript-eslint/no-var-requires": "off",
+        "no-underscore-dangle": "off",
+        "no-restricted-syntax": "off",
+        "no-await-in-loop": "off",
+        "max-classes-per-file": "off"
+      }
+    }
+  ]
+};

.prettierrc

@@ -0,0 +1,4 @@
+{
+  "singleQuote": true,
+  "trailingComma": "all"
+}

.travis.yml

@@ -0,0 +1,47 @@
+language: node_js
+
+cache:
+  directories:
+    - node_modules
+
+notifications:
+  email:
+    recipients:
+      - [email protected]
+      - [email protected]
+    on_success: never
+    on_failure: always
+
+stages:
+  - lints
+  - test
+  - name: release
+    if: branch = master
+jobs:
+  include:
+    - stage: lints
+      name: 'linting and type checking'
+      node_js:
+        - '12'
+      before_script:
+        - npm prune
+      script:
+        - npm run lint
+        - npm run build
+    - stage: test
+      node_js:
+        - '12'
+      before_script:
+        - npm prune
+      script:
+        - npm run test:cov
+        - npm run test:e2e
+      after_success:
+        - npm run report-coverage
+    - stage: release
+      node_js: '12'
+      before_script:
+        - npm prune
+      script:
+        - npm run build
+        - npm run semantic-release

README.md

@@ -1,10 +1,226 @@
 # nestjs-http
 
-### Rich featured HttpClient for `nestjs` applications
+![Travis](https://img.shields.io/travis/ukitgroup/nestjs-http/master.svg?style=flat-square)
+![Coverage Status](https://coveralls.io/repos/github/ukitgroup/nestjs-http/badge.svg?branch=master)
+![node](https://img.shields.io/node/v/@ukitgroup/nestjs-http.svg?style=flat-square)
+![npm](https://img.shields.io/npm/v/@ukitgroup/nestjs-http.svg?style=flat-square)
 
-It implements wrapper around [Got](https://www.npmjs.com/package/got) lib instead of native nest HttpModule
+![GitHub top language](https://img.shields.io/github/languages/top/ukitgroup/nestjs-http.svg?style=flat-square)
+![GitHub code size in bytes](https://img.shields.io/github/languages/code-size/ukitgroup/nestjs-http.svg?style=flat-square)
+![David](https://img.shields.io/david/ukitgroup/nestjs-http.svg?style=flat-square)
+![David](https://img.shields.io/david/dev/ukitgroup/nestjs-http.svg?style=flat-square)
 
-It provides:
+![license](https://img.shields.io/github/license/ukitgroup/nestjs-http.svg?style=flat-square)
+![GitHub last commit](https://img.shields.io/github/last-commit/ukitgroup/nestjs-http.svg?style=flat-square)
+![semantic-release](https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg?style=flat-square)
 
-1. [Got](https://www.npmjs.com/package/got) integration for [nestjs](https://nestjs.com/)
-2. Accept external Tracing Service for attaching specific http-headers across your microservice architecture
+## Description
+
+### Rich featured HttpClient for [nestjs](https://nestjs.com/) applications
+
+- [Got](https://www.npmjs.com/package/got) integration for `nestjs`;
+- Retries and all `Got` functions out of the box
+- Transparent `Got` usage (you will work with Got interface)
+- Accept external `Tracing Service` via DI for attaching specific http-headers across your microservice architecture;
+- Modularity - create instances for your modules with different configurations;
+- Default keep-alive http/https agent.
+
+## Requirements
+
+1. @nestjs/common ^7.2.0
+2. @nestjs/core ^7.2.0
+
+## Installation
+
+```bash
+npm install --save @ukitgroup/nestjs-http
+```
+
+or
+
+```bash
+yarn add @ukitgroup/nestjs-http
+```
+
+## Short example
+
+**cat.service.ts**
+
+```typescript
+@Injectable()
+export class CatService {
+  constructor(@Inject(HttpClientService) private readonly httpClient: Got) {}
+
+  meow(): string {
+    // httpClient is an instance of Got
+    // configuration from AppModule and CatModule
+    // set built-in headers
+    this.httpClient.post('/meow');
+    return `meows..`;
+  }
+}
+```
+
+**cat.module.ts**
+
+```typescript
+@Module({
+  imports: [
+    HttpClient.forInstance({
+      imports: [YourConfigModule],
+      providers: [
+        {
+          // override got configuration
+          provide: HTTP_CLIENT_INSTANCE_GOT_OPTS,
+          inject: [YourConfig],
+          useFactory: config => {
+            return {
+              retry: config.retry,
+            };
+          },
+        },
+      ],
+    }),
+  ],
+  providers: [CatService],
+})
+export class CatModule {}
+```
+
+**app.module.ts**
+
+```typescript
+@Module({
+  imports: [HttpClient.forRoot({}), CatModule],
+})
+export class AppModule {}
+```
+
+## API
+
+Define root configuration for Got in AppModule with:
+
+```
+HttpClient.forRoot(options: HttpClientForRootType)
+```
+
+```
+HttpClientForRootType: {
+  imports?: [],
+  providers?: [],
+}
+```
+
+Provide configuration with tokens:
+
+- `HTTP_SERVICE_CONFIG` - ServiceConfigType for HttpClientService
+- `TRACE_DATA_SERVICE` - should implements TraceDataServiceInterface
+- `GOT_CONFIG` - got configuration
+
+Provided configuration will be merged:
+defaultConfig -> forRoot() -> forInstance() -> execution
+
+default config for httpService:
+
+```typescript
+const defaultConfig = {
+  enableTraceService: false,
+  headersMap: {
+    traceId: 'x-trace-id',
+    ip: 'x-real-ip',
+    userAgent: 'user-agent',
+    referrer: 'referrer',
+  },
+  excludeHeaders: [],
+};
+```
+
+default config for got extends default config from [got documentation](https://github.com/sindresorhus/got)
+
+```typescript
+const defaultConfig = {
+  agent: {
+    http: new http.Agent({ keepAlive: true }),
+    https: new https.Agent({ keepAlive: true }),
+  },
+};
+```
+
+Define instance configuration, trace service and http client service config in your module with:
+
+```
+HttpClient.forInstance(options: HttpClientForRootType)
+```
+
+# Trace service injection
+
+Usually you pass some headers across your microservices such as: `trace-id`, `ip`, `user-agent` etc.
+To make it convenient you can inject traceService via `dependency injection` and `HTTPClient` will pass this data with headers
+
+You just have to implement TraceServiceInterface:
+
+```typescript
+export interface TraceDataServiceInterface {
+  getRequestData(): TraceDataType;
+}
+
+// and TraceDataType
+export type TraceDataType = {
+  [key: string]: string;
+};
+```
+
+Headers mapping to values:
+
+```typescript
+const headersMap = {
+  traceId: 'x-trace-id',
+  ip: 'x-real-ip',
+  userAgent: 'user-agent',
+  referrer: 'referrer',
+};
+```
+
+Sou you can just define your service which should return these fields. For example, you can use `cls-hooked` for retrieving request data
+
+```typescript
+export class TraceService implements TraceDataServiceInterface {
+  getRequestData() {
+    return {
+      traceId: 'unique-id',
+      ip: '127.0.0.1',
+    };
+  }
+}
+```
+
+And then just define configuration:
+
+```typescript
+@Module({
+  imports: [
+    HttpClient.forInstance({
+      providers: [
+        {
+          provide: HTTP_SERVICE_CONFIG,
+          useValue: {
+            enableTraceService: true,
+          },
+        },
+        { provide: TRACE_DATA_SERVICE, useClass: TraceService },
+      ],
+    }),
+  ],
+})
+class AwesomeModule {}
+```
+
+### TODO
+
+- Injection of `MetricService` for exports requests metrics such as: statuses, errors, retries, timing
+- Client balancing for servers with several `ip`s or endpoints in different AZ which don't support server's LB.
+- ... Feature/Pull requests are welcome!😅
+
+## License
+
+@ukitgroup/nestjs-http is [MIT licensed](LICENSE).

commitlint.config.js

@@ -0,0 +1 @@
+module.exports = { extends: ['@commitlint/config-conventional'] };