feat: add loggers package

packages-backend/express/README.md

@@ -51,7 +51,7 @@ app.use((request, response, next) => {
 
 - `inferIssuer` (_boolean_): Determines whether the issuer should be inferred from the custom request HTTP header `x-mc-api-cloud-identifier` which is sent by the Merchant Center API Gateway when forwarding the request. This might be useful in case the server is used in multiple regions.
 
-- `jwks` (_object_): see options of `jwks-rsa`.
+- `jwks` (_object_): See options of `jwks-rsa`.
 
 ### Usage in Serverless Functions
 

packages-backend/loggers/.gitignore

@@ -0,0 +1 @@
+build

packages-backend/loggers/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 commercetools GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

packages-backend/loggers/README.md

@@ -0,0 +1,94 @@
+# @commercetools-backend/loggers
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@commercetools-backend/loggers"><img src="https://badgen.net/npm/v/@commercetools-backend/loggers" alt="Latest release (latest dist-tag)" /></a> <a href="https://www.npmjs.com/package/@commercetools-backend/loggers"><img src="https://badgen.net/npm/v/@commercetools-backend/loggers/next" alt="Latest release (next dist-tag)" /></a> <a href="https://bundlephobia.com/result?p=@commercetools-backend/loggers"><img src="https://badgen.net/bundlephobia/minzip/@commercetools-backend/loggers" alt="Minified + GZipped size" /></a> <a href="https://github.com/commercetools/merchant-center-application-kit/blob/master/LICENSE"><img src="https://badgen.net/github/license/commercetools/merchant-center-application-kit" alt="GitHub license" /></a>
+</p>
+
+Opinionated JSON loggers for HTTP server applications.
+
+## Install
+
+```bash
+$ npm install --save @commercetools-backend/loggers
+```
+
+## Middlewares
+
+### Access logger
+
+Creates a logger to be used for HTTP requests access logs.
+
+```js
+const {
+  createAccessLoggerMiddleware,
+} = require('@commercetools-backend/loggers');
+
+app.use(createAccessLoggerMiddleware());
+```
+
+**Options**
+
+- `level` (_string_): The log level to be used. **Default: `info`**
+- `silent` (_boolean_): In case logs should be skipped. **Default: `false`**
+- `json` (_boolean_): To use the JSON formatter, otherwise falls back to CLI format. It's recommended to use the JSON formatter on production.
+- `formatters` (_Array of Winston formatters_): In case you want to pass additional Winston formatters.
+- `ignoreUrls` (_Array of string_): A list of URL paths to be ignored from being logged.
+
+## Application logger
+
+Creates a logger to be used programmatically in the application code.
+
+```js
+const { createApplicationLogger } = require('@commercetools-backend/loggers');
+
+const app = createApplicationLogger();
+
+app.info('Hey there', { meta: { name: 'Tom' } });
+```
+
+**Options**
+
+- `level` (_string_): The log level to be used. **Default: `info`**
+- `silent` (_boolean_): In case logs should be skipped. **Default: `false`**
+- `json` (_boolean_): To use the JSON formatter, otherwise falls back to CLI format. It's recommended to use the JSON formatter on production.
+- `formatters` (_Array of Winston formatters_): In case you want to pass additional Winston formatters.
+
+## Formatters
+
+The package provides some come Winston formatters that can be passed to the given loggers.
+
+### Rewrite fields
+
+This formatter allows to rewrite fields from the JSON logger. It can be useful for redacting insecure information, or to map certain fields to a specific format (for example for Kibana).
+
+```js
+const {
+  createAccessLoggerMiddleware,
+  rewriteFieldsFormatter,
+} = require('@commercetools-backend/loggers');
+
+app.use(
+  createAccessLoggerMiddleware({
+    formatters: [
+      rewriteFieldsFormatter({
+        fields: [
+          { from: 'level', to: 'logLevel' },
+          { from: 'meta.error.message', to: 'meta.errorMessage' },
+          {
+            from: 'meta.error',
+            to: 'meta.errorJsonString',
+            replaceValue: (value) => JSON.stringify(value),
+          },
+        ],
+      }),
+    ],
+  })
+);
+```
+
+**Options**
+
+- `fields` (_Array of RewriteField_): A `RewriteField` is an object with the following properties:
+  - `from` (_string_): A JSON path to one of the fields of the log information that needs to be rewritten. The field will be deleted.
+  - `to` (_string_): A JSON path to the new field that should be created.
+  - `replaceValue` (_function_): An optional function that takes the value from the original field and returns a new value for the field. It can be used for example to serialize the value with `JSON.stringify`.

packages-backend/loggers/index.ts

@@ -0,0 +1,5 @@
+// This file exists  because we want jest to use our non-compiled code to run tests
+// if this file is missing, and you have a `module` or `main` that points to a non-existing file
+// (ie, a bundle that hasn't been built yet) then jest will fail if the bundle is not yet built.
+// all apps should export all their named exports from their root index.js
+export * from './src';

packages-backend/loggers/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@commercetools-backend/loggers",
+  "version": "1.0.0",
+  "description": "Opinionated JSON loggers for HTTP server applications",
+  "bugs": "https://github.com/commercetools/merchant-center-application-kit/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/commercetools/merchant-center-application-kit.git",
+    "directory": "packages-backend/loggers"
+  },
+  "homepage": "https://docs.commercetools.com/custom-applications",
+  "keywords": ["javascript", "nodejs", "express", "logger", "server", "toolkit"],
+  "license": "MIT",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./build/index.js",
+  "typings": "./build/index.d.ts",
+  "types": "./build/index.d.ts",
+  "files": ["build", "package.json", "LICENSE", "README.md"],
+  "scripts": {
+    "prebuild": "rimraf build/**",
+    "build": "tsc -p tsconfig.build.json"
+  },
+  "dependencies": {
+    "@sentry/node": "5.15.5",
+    "@types/triple-beam": "1.3.0",
+    "express-winston": "4.0.3",
+    "fast-safe-stringify": "2.0.7",
+    "lodash": "4.17.15",
+    "logform": "2.1.2",
+    "triple-beam": "1.3.0",
+    "winston": "3.2.1"
+  },
+  "devDependencies": {
+    "express": "4.17.1"
+  }
+}

packages-backend/loggers/src/create-application-logger.ts

@@ -0,0 +1,21 @@
+import type { TLoggerOptions } from './types';
+
+import * as winston from 'winston';
+
+const createApplicationLogger = (options: TLoggerOptions = {}) => {
+  const shouldLog = Boolean(options.silent);
+  const formatters = winston.format.combine(
+    ...(options.formatters ?? []),
+    options.json
+      ? winston.format.json()
+      : winston.format.combine(winston.format.cli(), winston.format.simple())
+  );
+
+  return winston.createLogger({
+    level: options.level ?? 'info',
+    format: formatters,
+    transports: [new winston.transports.Console({ silent: !shouldLog })],
+  });
+};
+
+export default createApplicationLogger;

packages-backend/loggers/src/formatters/rewrite-fields.ts

@@ -0,0 +1,39 @@
+import type { TransformableInfo } from 'logform';
+
+import { format } from 'logform';
+import getIn from 'lodash/get';
+import setIn from 'lodash/set';
+import unsetIn from 'lodash/unset';
+
+type TRewriteField = {
+  from: string;
+  to: string;
+  replaceValue?: (value: string) => unknown;
+};
+type TRewriteFieldsFormatterOption = {
+  fields: TRewriteField[];
+};
+
+function rewriteField(
+  info: TransformableInfo,
+  jsonPath: string,
+  newJsonPath: string,
+  replaceValue?: (value: string) => unknown
+) {
+  const val: string | undefined = getIn(info, jsonPath);
+  if (val) {
+    unsetIn(info, jsonPath);
+    setIn(info, newJsonPath, replaceValue ? replaceValue(val) : val);
+  }
+}
+
+const rewriteFieldsFormatter = format(
+  (info, options: TRewriteFieldsFormatterOption) => {
+    options.fields.forEach((field) => {
+      rewriteField(info, field.from, field.to, field.replaceValue);
+    });
+    return info;
+  }
+);
+
+export default rewriteFieldsFormatter;

packages-backend/loggers/src/index.ts

@@ -0,0 +1,11 @@
+// Middlewares
+export { default as createAccessLoggerMiddleware } from './middlewares/create-access-logger';
+
+// Loggers
+export { default as createApplicationLogger } from './create-application-logger';
+
+// Formatters
+export { default as rewriteFieldsFormatter } from './formatters/rewrite-fields';
+
+// Re-export winston for convenience
+export * as winston from 'winston';

packages-backend/loggers/src/middlewares/create-access-logger.ts

@@ -0,0 +1,34 @@
+import type { TAccessLoggerOptions } from '../types';
+
+import winston from 'winston';
+import expressWinston from 'express-winston';
+
+const createAccessLoggerMiddleware = (options: TAccessLoggerOptions = {}) => {
+  const shouldLog = Boolean(options.silent);
+  const ignoreUrls = options.ignoreUrls ?? [];
+  const formatters = winston.format.combine(
+    winston.format.timestamp(),
+    ...(options.formatters ?? []),
+    options.json ? winston.format.json() : winston.format.cli()
+  );
+
+  return expressWinston.logger({
+    level: options.level ?? 'info',
+    transports: [new winston.transports.Console()],
+    format: formatters,
+    meta: true,
+    expressFormat: true, // Use default morgan access log formatting
+    colorize: !options.json,
+    skip: (req) => !shouldLog || ignoreUrls.includes(req.originalUrl),
+    dynamicMeta: (req) => ({
+      ip: req.ip,
+      ips: req.ips,
+      hostname: req.hostname,
+      ...(req.connection.remoteAddress
+        ? { remoteAddress: req.connection.remoteAddress }
+        : {}),
+    }),
+  });
+};
+
+export default createAccessLoggerMiddleware;

packages-backend/loggers/src/types.ts

@@ -0,0 +1,12 @@
+import type { Format } from 'logform';
+
+export type TLoggerOptions = {
+  level?: string;
+  silent?: boolean;
+  json?: boolean;
+  formatters?: Format[];
+};
+
+export type TAccessLoggerOptions = TLoggerOptions & {
+  ignoreUrls?: string[];
+};

packages-backend/loggers/tsconfig.build.json

@@ -0,0 +1,11 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "declaration": true,
+    "declarationDir": "build",
+    "outDir": "build"
+  },
+  "exclude": [
+    "**/*.spec.ts"
+  ],
+}

packages-backend/loggers/tsconfig.json

@@ -0,0 +1,3 @@
+{
+  "extends": "../tsconfig.json",
+}