@backstage/backend-app-api 0.2.5-next.0 → 0.3.0-next.1

package/dist/index.d.ts

@@ -4,9 +4,17 @@
  * @packageDocumentation
  */
 
+/// <reference types="node" />
+
 import { BackendFeature } from '@backstage/backend-plugin-api';
 import { Config } from '@backstage/config';
+import { ConfigService } from '@backstage/backend-plugin-api';
+import { CorsOptions } from 'cors';
+import { ErrorRequestHandler } from 'express';
+import { Express as Express_2 } from 'express';
 import { ExtensionPoint } from '@backstage/backend-plugin-api';
+import { HelmetOptions } from 'helmet';
+import * as http from 'http';
 import { HttpRouterService } from '@backstage/backend-plugin-api';
 import { LifecycleService } from '@backstage/backend-plugin-api';
 import { LoggerService } from '@backstage/backend-plugin-api';
@@ -14,10 +22,16 @@ import { PermissionsService } from '@backstage/backend-plugin-api';
 import { PluginCacheManager } from '@backstage/backend-common';
 import { PluginDatabaseManager } from '@backstage/backend-common';
 import { PluginEndpointDiscovery } from '@backstage/backend-common';
-import { PluginTaskScheduler } from '@backstage/backend-tasks';
+import { RequestHandler } from 'express';
+import { RequestListener } from 'http';
+import { RootHttpRouterService } from '@backstage/backend-plugin-api';
+import { RootLifecycleService } from '@backstage/backend-plugin-api';
+import { RootLoggerService } from '@backstage/backend-plugin-api';
+import { SchedulerService } from '@backstage/backend-plugin-api';
 import { ServiceFactory } from '@backstage/backend-plugin-api';
+import { ServiceFactoryOrFunction } from '@backstage/backend-plugin-api';
 import { ServiceRef } from '@backstage/backend-plugin-api';
-import { TokenManager } from '@backstage/backend-common';
+import { TokenManagerService } from '@backstage/backend-plugin-api';
 import { UrlReader } from '@backstage/backend-common';
 
 /**
@@ -33,7 +47,16 @@ export declare interface Backend {
 export declare const cacheFactory: (options?: undefined) => ServiceFactory<PluginCacheManager>;
 
 /** @public */
-export declare const configFactory: (options?: undefined) => ServiceFactory<Config>;
+export declare const configFactory: (options?: undefined) => ServiceFactory<ConfigService>;
+
+/**
+ * Creates a Node.js HTTP or HTTPS server instance.
+ *
+ * @public
+ */
+export declare function createHttpServer(listener: RequestListener, options: HttpServerOptions, deps: {
+    logger: LoggerService;
+}): Promise<ExtendedHttpServer>;
 
 /**
  * @public
@@ -44,7 +67,7 @@ export declare function createSpecializedBackend(options: CreateSpecializedBacke
  * @public
  */
 export declare interface CreateSpecializedBackendOptions {
-    services: (ServiceFactory | (() => ServiceFactory))[];
+    services: ServiceFactoryOrFunction[];
 }
 
 /** @public */
@@ -53,6 +76,17 @@ export declare const databaseFactory: (options?: undefined) => ServiceFactory<Pl
 /** @public */
 export declare const discoveryFactory: (options?: undefined) => ServiceFactory<PluginEndpointDiscovery>;
 
+/**
+ * An HTTP server extended with utility methods.
+ *
+ * @public
+ */
+export declare interface ExtendedHttpServer extends http.Server {
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    port(): number;
+}
+
 /** @public */
 export declare const httpRouterFactory: (options?: HttpRouterFactoryOptions | undefined) => ServiceFactory<HttpRouterService>;
 
@@ -61,9 +95,38 @@ export declare const httpRouterFactory: (options?: HttpRouterFactoryOptions | un
  */
 export declare type HttpRouterFactoryOptions = {
     /**
-     * The plugin ID used for the index route. Defaults to 'app'
+     * A callback used to generate the path for each plugin, defaults to `/api/{pluginId}`.
      */
-    indexPlugin?: string;
+    getPath(pluginId: string): string;
+};
+
+/**
+ * Options for configuring HTTPS for an HTTP server.
+ *
+ * @public
+ */
+export declare type HttpServerCertificateOptions = {
+    type: 'plain';
+    key: string;
+    cert: string;
+} | {
+    type: 'generated';
+    hostname: string;
+};
+
+/**
+ * Options for starting up an HTTP server.
+ *
+ * @public
+ */
+export declare type HttpServerOptions = {
+    listen: {
+        port: number;
+        host: string;
+    };
+    https?: {
+        certificate: HttpServerCertificateOptions;
+    };
 };
 
 /**
@@ -74,19 +137,212 @@ export declare const lifecycleFactory: (options?: undefined) => ServiceFactory<L
 /** @public */
 export declare const loggerFactory: (options?: undefined) => ServiceFactory<LoggerService>;
 
+/**
+ * A utility to configure common middleware.
+ *
+ * @public
+ */
+export declare class MiddlewareFactory {
+    #private;
+    /**
+     * Creates a new {@link MiddlewareFactory}.
+     */
+    static create(options: MiddlewareFactoryOptions): MiddlewareFactory;
+    private constructor();
+    /**
+     * Returns a middleware that unconditionally produces a 404 error response.
+     *
+     * @remarks
+     *
+     * Typically you want to place this middleware at the end of the chain, such
+     * that it's the last one attempted after no other routes matched.
+     *
+     * @returns An Express request handler
+     */
+    notFound(): RequestHandler;
+    /**
+     * Returns the compression middleware.
+     *
+     * @remarks
+     *
+     * The middleware will attempt to compress response bodies for all requests
+     * that traverse through the middleware.
+     */
+    compression(): RequestHandler;
+    /**
+     * Returns a request logging middleware.
+     *
+     * @remarks
+     *
+     * Typically you want to place this middleware at the start of the chain, such
+     * that it always logs requests whether they are "caught" by handlers farther
+     * down or not.
+     *
+     * @returns An Express request handler
+     */
+    logging(): RequestHandler;
+    /**
+     * Returns a middleware that implements the helmet library.
+     *
+     * @remarks
+     *
+     * This middleware applies security policies to incoming requests and outgoing
+     * responses. It is configured using config keys such as `backend.csp`.
+     *
+     * @see {@link https://helmetjs.github.io/}
+     *
+     * @returns An Express request handler
+     */
+    helmet(): RequestHandler;
+    /**
+     * Returns a middleware that implements the cors library.
+     *
+     * @remarks
+     *
+     * This middleware handles CORS. It is configured using the config key
+     * `backend.cors`.
+     *
+     * @see {@link https://github.com/expressjs/cors}
+     *
+     * @returns An Express request handler
+     */
+    cors(): RequestHandler;
+    /**
+     * Express middleware to handle errors during request processing.
+     *
+     * @remarks
+     *
+     * This is commonly the very last middleware in the chain.
+     *
+     * Its primary purpose is not to do translation of business logic exceptions,
+     * but rather to be a global catch-all for uncaught "fatal" errors that are
+     * expected to result in a 500 error. However, it also does handle some common
+     * error types (such as http-error exceptions, and the well-known error types
+     * in the `@backstage/errors` package) and returns the enclosed status code
+     * accordingly.
+     *
+     * It will also produce a response body with a serialized form of the error,
+     * unless a previous handler already did send a body. See
+     * {@link @backstage/errors#ErrorResponseBody} for the response shape used.
+     *
+     * @returns An Express error request handler
+     */
+    error(options?: MiddlewareFactoryErrorOptions): ErrorRequestHandler;
+}
+
+/**
+ * Options passed to the {@link MiddlewareFactory.error} middleware.
+ *
+ * @public
+ */
+export declare interface MiddlewareFactoryErrorOptions {
+    /**
+     * Whether error response bodies should show error stack traces or not.
+     *
+     * If not specified, by default shows stack traces only in development mode.
+     */
+    showStackTraces?: boolean;
+    /**
+     * Whether any 4xx errors should be logged or not.
+     *
+     * If not specified, default to only logging 5xx errors.
+     */
+    logAllErrors?: boolean;
+}
+
+/**
+ * Options used to create a {@link MiddlewareFactory}.
+ *
+ * @public
+ */
+export declare interface MiddlewareFactoryOptions {
+    config: ConfigService;
+    logger: LoggerService;
+}
+
 /** @public */
 export declare const permissionsFactory: (options?: undefined) => ServiceFactory<PermissionsService>;
 
+/**
+ * Attempts to read a CORS options object from the backend configuration object.
+ *
+ * @public
+ * @param config - The backend configuration object.
+ * @returns A CORS options object, or undefined if no cors configuration is present.
+ *
+ * @example
+ * ```ts
+ * const corsOptions = readCorsOptions(config.getConfig('backend'));
+ * ```
+ */
+export declare function readCorsOptions(config?: Config): CorsOptions;
+
+/**
+ * Attempts to read Helmet options from the backend configuration object.
+ *
+ * @public
+ * @param config - The backend configuration object.
+ * @returns A Helmet options object, or undefined if no Helmet configuration is present.
+ *
+ * @example
+ * ```ts
+ * const helmetOptions = readHelmetOptions(config.getConfig('backend'));
+ * ```
+ */
+export declare function readHelmetOptions(config?: Config): HelmetOptions;
+
+/**
+ * Reads {@link HttpServerOptions} from a {@link @backstage/config#Config} object.
+ *
+ * @public
+ * @remarks
+ *
+ * The provided configuration object should contain the `listen` and
+ * additional keys directly.
+ *
+ * @example
+ * ```ts
+ * const opts = readHttpServerOptions(config.getConfig('backend'));
+ * ```
+ */
+export declare function readHttpServerOptions(config?: Config): HttpServerOptions;
+
+/**
+ * @public
+ */
+export declare interface RootHttpRouterConfigureOptions {
+    app: Express_2;
+    middleware: MiddlewareFactory;
+    routes: RequestHandler;
+    config: ConfigService;
+    logger: LoggerService;
+    lifecycle: LifecycleService;
+}
+
+/** @public */
+export declare const rootHttpRouterFactory: (options?: RootHttpRouterFactoryOptions | undefined) => ServiceFactory<RootHttpRouterService>;
+
+/**
+ * @public
+ */
+export declare type RootHttpRouterFactoryOptions = {
+    /**
+     * The path to forward all unmatched requests to. Defaults to '/api/app'
+     */
+    indexPath?: string | false;
+    configure?(options: RootHttpRouterConfigureOptions): void;
+};
+
 /**
  * Allows plugins to register shutdown hooks that are run when the process is about to exit.
  * @public */
-export declare const rootLifecycleFactory: (options?: undefined) => ServiceFactory<LifecycleService>;
+export declare const rootLifecycleFactory: (options?: undefined) => ServiceFactory<RootLifecycleService>;
 
 /** @public */
-export declare const rootLoggerFactory: (options?: undefined) => ServiceFactory<LoggerService>;
+export declare const rootLoggerFactory: (options?: undefined) => ServiceFactory<RootLoggerService>;
 
 /** @public */
-export declare const schedulerFactory: (options?: undefined) => ServiceFactory<PluginTaskScheduler>;
+export declare const schedulerFactory: (options?: undefined) => ServiceFactory<SchedulerService>;
 
 /**
  * @public
@@ -94,7 +350,7 @@ export declare const schedulerFactory: (options?: undefined) => ServiceFactory<P
 export declare type ServiceOrExtensionPoint<T = unknown> = ExtensionPoint<T> | ServiceRef<T>;
 
 /** @public */
-export declare const tokenManagerFactory: (options?: undefined) => ServiceFactory<TokenManager>;
+export declare const tokenManagerFactory: (options?: undefined) => ServiceFactory<TokenManagerService>;
 
 /** @public */
 export declare const urlReaderFactory: (options?: undefined) => ServiceFactory<UrlReader>;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@backstage/backend-app-api",
   "description": "Core API used by Backstage backend apps",
-  "version": "0.2.5-next.0",
+  "version": "0.3.0-next.1",
   "main": "dist/index.cjs.js",
   "types": "dist/index.d.ts",
   "publishConfig": {
@@ -33,17 +33,37 @@
     "start": "backstage-cli package start"
   },
   "dependencies": {
-    "@backstage/backend-common": "^0.18.0-next.0",
-    "@backstage/backend-plugin-api": "^0.2.1-next.0",
-    "@backstage/backend-tasks": "^0.4.1-next.0",
+    "@backstage/backend-common": "^0.18.0-next.1",
+    "@backstage/backend-plugin-api": "^0.3.0-next.1",
+    "@backstage/backend-tasks": "^0.4.1-next.1",
+    "@backstage/config": "^1.0.6-next.0",
     "@backstage/errors": "^1.1.4",
-    "@backstage/plugin-permission-node": "^0.7.3-next.0",
+    "@backstage/plugin-permission-node": "^0.7.3-next.1",
+    "@types/cors": "^2.8.6",
+    "@types/express": "^4.17.6",
+    "compression": "^1.7.4",
+    "cors": "^2.8.5",
     "express": "^4.17.1",
     "express-promise-router": "^4.1.0",
+    "fs-extra": "10.1.0",
+    "helmet": "^6.0.0",
+    "minimatch": "^5.0.0",
+    "morgan": "^1.10.0",
+    "node-forge": "^1.3.1",
+    "selfsigned": "^2.0.0",
+    "stoppable": "^1.1.0",
     "winston": "^3.2.1"
   },
   "devDependencies": {
-    "@backstage/cli": "^0.22.1-next.1"
+    "@backstage/cli": "^0.22.1-next.2",
+    "@types/compression": "^1.7.0",
+    "@types/fs-extra": "^9.0.3",
+    "@types/http-errors": "^2.0.0",
+    "@types/morgan": "^1.9.0",
+    "@types/node-forge": "^1.3.0",
+    "@types/stoppable": "^1.1.0",
+    "http-errors": "^2.0.0",
+    "supertest": "^6.1.3"
   },
   "files": [
     "dist",