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

package/dist/index.d.ts

@@ -4,20 +4,40 @@
  * @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 { Format } from 'logform';
+import { Handler } from 'express';
+import { HelmetOptions } from 'helmet';
+import * as http from 'http';
 import { HttpRouterService } from '@backstage/backend-plugin-api';
+import { IdentityService } from '@backstage/backend-plugin-api';
 import { LifecycleService } from '@backstage/backend-plugin-api';
+import { LoadConfigOptionsRemote } from '@backstage/config-loader';
 import { LoggerService } from '@backstage/backend-plugin-api';
+import { LogMeta } from '@backstage/backend-plugin-api';
 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 { transport } from 'winston';
 import { UrlReader } from '@backstage/backend-common';
 
 /**
@@ -30,10 +50,37 @@ export declare interface Backend {
 }
 
 /** @public */
-export declare const cacheFactory: (options?: undefined) => ServiceFactory<PluginCacheManager>;
+export declare const cacheFactory: () => ServiceFactory<PluginCacheManager>;
+
+/** @public */
+export declare const configFactory: () => ServiceFactory<ConfigService>;
+
+/** @public */
+export declare interface ConfigFactoryOptions {
+    /**
+     * Process arguments to use instead of the default `process.argv()`.
+     */
+    argv?: string[];
+    /**
+     * Enables and sets options for remote configuration loading.
+     */
+    remote?: LoadConfigOptionsRemote;
+}
 
 /** @public */
-export declare const configFactory: (options?: undefined) => ServiceFactory<Config>;
+export declare function createConfigSecretEnumerator(options: {
+    logger: LoggerService;
+    dir?: string;
+}): Promise<(config: Config) => Iterable<string>>;
+
+/**
+ * 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,14 +91,52 @@ export declare function createSpecializedBackend(options: CreateSpecializedBacke
  * @public
  */
 export declare interface CreateSpecializedBackendOptions {
-    services: (ServiceFactory | (() => ServiceFactory))[];
+    services: ServiceFactoryOrFunction[];
 }
 
 /** @public */
-export declare const databaseFactory: (options?: undefined) => ServiceFactory<PluginDatabaseManager>;
+export declare const databaseFactory: () => ServiceFactory<PluginDatabaseManager>;
+
+/**
+ * The default implementation of the {@link @backstage/backend-plugin-api#RootHttpRouterService} interface for
+ * {@link @backstage/backend-plugin-api#coreServices.rootHttpRouter}.
+ *
+ * @public
+ */
+export declare class DefaultRootHttpRouter implements RootHttpRouterService {
+    #private;
+    static create(options?: DefaultRootHttpRouterOptions): DefaultRootHttpRouter;
+    private constructor();
+    use(path: string, handler: Handler): void;
+    handler(): Handler;
+}
+
+/**
+ * Options for the {@link DefaultRootHttpRouter} class.
+ *
+ * @public
+ */
+export declare interface DefaultRootHttpRouterOptions {
+    /**
+     * The path to forward all unmatched requests to. Defaults to '/api/app' if
+     * not given. Disables index path behavior if false is given.
+     */
+    indexPath?: string | false;
+}
 
 /** @public */
-export declare const discoveryFactory: (options?: undefined) => ServiceFactory<PluginEndpointDiscovery>;
+export declare const discoveryFactory: () => 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>;
@@ -59,34 +144,286 @@ export declare const httpRouterFactory: (options?: HttpRouterFactoryOptions | un
 /**
  * @public
  */
-export declare type HttpRouterFactoryOptions = {
+export declare interface 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;
+    };
+};
+
+/** @public */
+export declare const identityFactory: (options?: IdentityFactoryOptions | undefined) => ServiceFactory<IdentityService>;
+
+/**
+ * An identity client options object which allows extra configurations
+ *
+ * @public
+ */
+export declare type IdentityFactoryOptions = {
+    issuer?: string;
+    /** JWS "alg" (Algorithm) Header Parameter values. Defaults to an array containing just ES256.
+     * More info on supported algorithms: https://github.com/panva/jose */
+    algorithms?: string[];
 };
 
 /**
  * Allows plugins to register shutdown hooks that are run when the process is about to exit.
  * @public */
-export declare const lifecycleFactory: (options?: undefined) => ServiceFactory<LifecycleService>;
+export declare const lifecycleFactory: () => ServiceFactory<LifecycleService>;
+
+/**
+ * Load configuration for a Backend.
+ *
+ * This function should only be called once, during the initialization of the backend.
+ *
+ * @public
+ */
+export declare function loadBackendConfig(options: {
+    remote?: LoadConfigOptionsRemote;
+    argv: string[];
+}): Promise<{
+    config: Config;
+}>;
 
 /** @public */
-export declare const loggerFactory: (options?: undefined) => ServiceFactory<LoggerService>;
+export declare const loggerFactory: () => 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: () => 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 permissionsFactory: (options?: undefined) => ServiceFactory<PermissionsService>;
+export declare const rootHttpRouterFactory: () => ServiceFactory<RootHttpRouterService>;
+
+/**
+ * @public
+ */
+export declare type RootHttpRouterFactoryOptions = {
+    /**
+     * The path to forward all unmatched requests to. Defaults to '/api/app' if
+     * not given. Disables index path behavior if false is given.
+     */
+    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: () => ServiceFactory<RootLifecycleService>;
 
 /** @public */
-export declare const rootLoggerFactory: (options?: undefined) => ServiceFactory<LoggerService>;
+export declare const rootLoggerFactory: () => ServiceFactory<RootLoggerService>;
 
 /** @public */
-export declare const schedulerFactory: (options?: undefined) => ServiceFactory<PluginTaskScheduler>;
+export declare const schedulerFactory: () => ServiceFactory<SchedulerService>;
 
 /**
  * @public
@@ -94,9 +431,50 @@ 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: () => ServiceFactory<TokenManagerService>;
 
 /** @public */
-export declare const urlReaderFactory: (options?: undefined) => ServiceFactory<UrlReader>;
+export declare const urlReaderFactory: () => ServiceFactory<UrlReader>;
+
+/**
+ * A {@link @backstage/backend-plugin-api#LoggerService} implementation based on winston.
+ *
+ * @public
+ */
+export declare class WinstonLogger implements RootLoggerService {
+    #private;
+    /**
+     * Creates a {@link WinstonLogger} instance.
+     */
+    static create(options: WinstonLoggerOptions): WinstonLogger;
+    /**
+     * Creates a winston log formatter for redacting secrets.
+     */
+    static redacter(): {
+        format: Format;
+        add: (redactions: Iterable<string>) => void;
+    };
+    /**
+     * Creates a pretty printed winston log formatter.
+     */
+    static colorFormat(): Format;
+    private constructor();
+    error(message: string, meta?: LogMeta): void;
+    warn(message: string, meta?: LogMeta): void;
+    info(message: string, meta?: LogMeta): void;
+    debug(message: string, meta?: LogMeta): void;
+    child(meta: LogMeta): LoggerService;
+    addRedactions(redactions: Iterable<string>): void;
+}
+
+/**
+ * @public
+ */
+export declare interface WinstonLoggerOptions {
+    meta?: LogMeta;
+    level: string;
+    format: Format;
+    transports: transport[];
+}
 
 export { }

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",
   "main": "dist/index.cjs.js",
   "types": "dist/index.d.ts",
   "publishConfig": {
@@ -33,17 +33,47 @@
     "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",
+    "@backstage/backend-plugin-api": "^0.3.0",
+    "@backstage/backend-tasks": "^0.4.1",
+    "@backstage/cli-common": "^0.1.11",
+    "@backstage/config": "^1.0.6",
+    "@backstage/config-loader": "^1.1.8",
     "@backstage/errors": "^1.1.4",
-    "@backstage/plugin-permission-node": "^0.7.3-next.0",
+    "@backstage/plugin-auth-node": "^0.2.9",
+    "@backstage/plugin-permission-node": "^0.7.3",
+    "@backstage/types": "^1.0.2",
+    "@manypkg/get-packages": "^1.1.3",
+    "@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",
-    "winston": "^3.2.1"
+    "fs-extra": "10.1.0",
+    "helmet": "^6.0.0",
+    "lodash": "^4.17.21",
+    "logform": "^2.3.2",
+    "minimatch": "^5.0.0",
+    "minimist": "^1.2.5",
+    "morgan": "^1.10.0",
+    "node-forge": "^1.3.1",
+    "selfsigned": "^2.0.0",
+    "stoppable": "^1.1.0",
+    "winston": "^3.2.1",
+    "winston-transport": "^4.5.0"
   },
   "devDependencies": {
-    "@backstage/cli": "^0.22.1-next.1"
+    "@backstage/cli": "^0.22.1",
+    "@types/compression": "^1.7.0",
+    "@types/fs-extra": "^9.0.3",
+    "@types/http-errors": "^2.0.0",
+    "@types/minimist": "^1.2.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",