Add a backend-common package with common concerns such as logging

2020-04-29 09:28:50 +02:00
parent a92f662d88
commit 77d48d8794
19 changed files with 722 additions and 13 deletions
@@ -0,0 +1,3 @@
+module.exports = {
+  extends: [require.resolve('@backstage/cli/config/eslint.backend')],
+};
@@ -0,0 +1,36 @@
+# @backstage/backend-common
+
+Common functionality library for Backstage backends, implementing logging,
+error handling and similar.
+
+## Usage
+
+Add the library to your backend package:
+
+```sh
+yarn add @backstage/backend-common
+```
+
+then make use of the handlers and logger as necessary:
+
+```typescript
+import {
+  logger,
+  errorHandler,
+  notFoundHandler,
+} from '@backstage/backend-common';
+
+const app = express();
+app.use('/home', myHomeRouter);
+app.use(errorHandler());
+app.use(notFoundHandler());
+
+app.listen(PORT, () => {
+  logger.info(`Listening on port ${PORT}`);
+});
+```
+
+## Documentation
+
+- [Backstage Readme](https://github.com/spotify/backstage/blob/master/README.md)
+- [Backstage Documentation](https://github.com/spotify/backstage/blob/master/docs/README.md)
@@ -0,0 +1,45 @@
+{
+  "name": "@backstage/backend-common",
+  "description": "Common functionality library for Backstage backends",
+  "version": "0.1.1-alpha.4",
+  "main": "dist",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "homepage": "https://backstage.io",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/spotify/backstage",
+    "directory": "packages/backend-common"
+  },
+  "keywords": [
+    "backstage"
+  ],
+  "license": "Apache-2.0",
+  "scripts": {
+    "build": "backstage-cli build-cache -- tsc",
+    "lint": "backstage-cli lint",
+    "test": "backstage-cli test",
+    "clean": "backstage-cli clean"
+  },
+  "dependencies": {
+    "express": "^4.17.1",
+    "morgan": "^1.10.0",
+    "winston": "^3.2.1"
+  },
+  "devDependencies": {
+    "@backstage/cli": "^0.1.1-alpha.4",
+    "@types/express": "^4.17.6",
+    "@types/morgan": "^1.9.0",
+    "@types/supertest": "^2.0.8",
+    "get-port": "^5.1.1",
+    "jest": "^25.1.0",
+    "jest-fetch-mock": "^3.0.3",
+    "supertest": "^4.0.2",
+    "typescript": "^3.8.3"
+  },
+  "files": [
+    "dist"
+  ]
+}
@@ -0,0 +1,36 @@
+/*
+ * Copyright 2020 Spotify AB
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export class StatusCodeError extends Error {
+  public statusCode: number;
+
+  constructor(statusCode: number, message?: string) {
+    super(message);
+    this.statusCode = statusCode;
+  }
+}
+
+export class InvalidRequestError extends StatusCodeError {
+  constructor(message?: string) {
+    super(400, message || 'Invalid Request');
+  }
+}
+
+export class NotFoundError extends StatusCodeError {
+  constructor(message?: string) {
+    super(404, message || 'Not Found');
+  }
+}
@@ -0,0 +1,19 @@
+/*
+ * Copyright 2020 Spotify AB
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export * from './errors';
+export * from './logging';
+export * from './middleware';
@@ -0,0 +1,17 @@
+/*
+ * Copyright 2020 Spotify AB
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export * from './logger';
@@ -0,0 +1,40 @@
+/*
+ * Copyright 2020 Spotify AB
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import winston, { Logger } from 'winston';
+
+export let logger: Logger = winston.createLogger({
+  level: process.env.LOG_LEVEL || 'info',
+  format:
+    process.env.NODE_ENV === 'production'
+      ? winston.format.json()
+      : winston.format.combine(
+          winston.format.colorize(),
+          winston.format.timestamp(),
+          winston.format.simple(),
+        ),
+  defaultMeta: { service: 'backstage' },
+  transports: [
+    new winston.transports.Console({
+      silent:
+        process.env.JEST_WORKER_ID !== undefined && !process.env.LOG_LEVEL,
+    }),
+  ],
+});
+
+export function setLogger(newLogger: Logger) {
+  logger = newLogger;
+}
@@ -0,0 +1,48 @@
+/*
+ * Copyright 2020 Spotify AB
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import express from 'express';
+import request from 'supertest';
+import { errorHandler } from './errorHandler';
+import { StatusCodeError } from '../errors';
+
+describe('errorHandler', () => {
+  it('gives default code and message', async () => {
+    const app = express();
+    app.use('/breaks', () => {
+      throw new Error('some message');
+    });
+    app.use(errorHandler());
+
+    const response = await request(app).get('/breaks');
+
+    expect(response.status).toBe(500);
+    expect(response.text).toBe('some message');
+  });
+
+  it('takes code from StatusCodeError', async () => {
+    const app = express();
+    app.use('/breaks', () => {
+      throw new StatusCodeError(432, 'Some Message');
+    });
+    app.use(errorHandler());
+
+    const response = await request(app).get('/breaks');
+
+    expect(response.status).toBe(432);
+    expect(response.text).toContain('Some Message');
+  });
+});
@@ -0,0 +1,53 @@
+/*
+ * Copyright 2020 Spotify AB
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { ErrorRequestHandler, NextFunction, Request, Response } from 'express';
+
+/**
+ * Express middleware to handle errors during request processing.
+ *
+ * This is commonly the second to last middleware in the chain (before the
+ * notFoundHandler). It special cases StatusCodeError errors to expose their
+ * embedded status codes.
+ *
+ *
+ */
+export function errorHandler(): ErrorRequestHandler {
+  /* eslint-disable @typescript-eslint/no-unused-vars */
+  return (
+    error: Error,
+    _request: Request,
+    response: Response,
+    _next: NextFunction,
+  ) => {
+    const status = getStatusCode(error);
+    const message = error.message || 'Internal Server Error';
+    response.status(status).send(message);
+  };
+}
+
+function getStatusCode(error: Error): number {
+  const errorStatusCode = (error as any).statusCode;
+  if (
+    typeof errorStatusCode === 'number' &&
+    errorStatusCode >= 100 &&
+    errorStatusCode <= 599
+  ) {
+    return errorStatusCode;
+  }
+
+  return 500;
+}
@@ -0,0 +1,19 @@
+/*
+ * Copyright 2020 Spotify AB
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export * from './errorHandler';
+export * from './notFoundHandler';
+export * from './requestLoggingHandler';
@@ -0,0 +1,33 @@
+/*
+ * Copyright 2020 Spotify AB
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import express from 'express';
+import request from 'supertest';
+import { notFoundHandler } from './notFoundHandler';
+
+describe('notFoundHandler', () => {
+  it('handles only missing routes', async () => {
+    const app = express();
+    app.use('/exists', (_, res) => res.status(200).send());
+    app.use(notFoundHandler());
+
+    const existsResponse = await request(app).get('/exists');
+    const doesNotExistResponse = await request(app).get('/doesNotExist');
+
+    expect(existsResponse.status).toBe(200);
+    expect(doesNotExistResponse.status).toBe(404);
+  });
+});
@@ -0,0 +1,32 @@
+/*
+ * Copyright 2020 Spotify AB
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { NextFunction, Request, RequestHandler, Response } from 'express';
+
+/**
+ * Express middleware to handle requests for missing routes.
+ *
+ * Should be used as the very last handler in the chain, as it unconditionally
+ * returns a 404 status.
+ *
+ * @returns An Apollo request handler
+ */
+export function notFoundHandler(): RequestHandler {
+  /* eslint-disable @typescript-eslint/no-unused-vars */
+  return (_request: Request, response: Response, _next: NextFunction) => {
+    response.status(404).send('Not Found');
+  };
+}
@@ -0,0 +1,38 @@
+/*
+ * Copyright 2020 Spotify AB
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import express from 'express';
+import request from 'supertest';
+import { requestLoggingHandler } from './requestLoggingHandler';
+
+describe('requestLoggingHandler', () => {
+  it('emits logs for each request', async () => {
+    const logger = jest.fn();
+
+    const app = express();
+    app.use(requestLoggingHandler(logger));
+    app.use('/exists1', (_, res) => res.status(200).send());
+    app.use('/exists2', (_, res) => res.status(201).send());
+
+    const r = request(app);
+    await r.get('/exists1');
+    await r.get('/exists2');
+
+    expect(logger).toHaveBeenCalledTimes(2);
+    expect(logger).toHaveBeenNthCalledWith(1, expect.stringContaining('200'));
+    expect(logger).toHaveBeenNthCalledWith(2, expect.stringContaining('201'));
+  });
+});
@@ -0,0 +1,38 @@
+/*
+ * Copyright 2020 Spotify AB
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { RequestHandler } from 'express';
+import morgan from 'morgan';
+import { logger as commonLogger } from '../logging';
+
+/**
+ * Logs incoming requests.
+ *
+ * @param logger An optional logger to use. If not specified, the default logger is used.
+ * @returns An Apollo request handler
+ */
+export function requestLoggingHandler(
+  logger?: (message: String) => void,
+): RequestHandler {
+  const actualLogger = logger || commonLogger.info;
+  return morgan('combined', {
+    stream: {
+      write(message: String) {
+        actualLogger(message);
+      },
+    },
+  });
+}
@@ -0,0 +1,17 @@
+/*
+ * Copyright 2020 Spotify AB
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+require('jest-fetch-mock').enableMocks();
@@ -0,0 +1,15 @@
+{
+  "include": ["src"],
+  "compilerOptions": {
+    "baseUrl": "src",
+    "outDir": "dist",
+    "incremental": true,
+    "sourceMap": true,
+    "declaration": true,
+    "strict": true,
+    "target": "es5",
+    "module": "commonjs",
+    "esModuleInterop": true,
+    "types": ["node", "jest"]
+  }
+}