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

package/CHANGELOG.md

@@ -1,5 +1,65 @@
 # @backstage/backend-app-api
 
+## 0.3.0
+
+### Minor Changes
+
+- 02b119ff93: **BREAKING**: The `httpRouterFactory` now accepts a `getPath` option rather than `indexPlugin`. To set up custom index path, configure the new `rootHttpRouterFactory` with a custom `indexPath` instead.
+
+  Added an implementation for the new `rootHttpRouterServiceRef`.
+
+### Patch Changes
+
+- ecc6bfe4c9: Use new `ServiceFactoryOrFunction` type.
+- b99c030f1b: Moved over implementation of the root HTTP service from `@backstage/backend-common`, and replaced the `middleware` option with a `configure` callback option.
+- 170282ece6: Fixed a bug in the default token manager factory where it created multiple incompatible instances.
+- 843a0a158c: Added service factory for the new core identity service.
+- 150a7dd790: An error will now be thrown if attempting to override the plugin metadata service.
+- 483e907eaf: Internal updates of `createServiceFactory` from `@backstage/backend-plugin-api`.
+- 015a6dced6: The `createSpecializedBackend` function will now throw an error if duplicate service implementations are provided.
+- e3fca10038: Tweaked the plugin logger to use `plugin` as the label for the plugin ID, rather than `pluginId`.
+- ecbec4ec4c: Internal refactor to match new options pattern in the experimental backend system.
+- 51b7a7ed07: Exported the default root HTTP router implementation as `DefaultRootHttpRouter`. It only implements the routing layer and needs to be exposed via an HTTP server similar to the built-in setup in the `rootHttpRouterFactory`.
+- 0e63aab311: Moved over logging and configuration loading implementations from `@backstage/backend-common`. There is a now `WinstonLogger` which implements the `RootLoggerService` through Winston with accompanying utilities. For configuration the `loadBackendConfig` function has been moved over, but it now instead returns an object with a `config` property.
+- 8e06f3cf00: Switched imports of `loggerToWinstonLogger` to `@backstage/backend-common`.
+- 3b8fd4169b: Internal folder structure refactor.
+- 6cfd4d7073: Updated implementations for the new `RootLifecycleService`.
+- Updated dependencies
+  - @backstage/backend-plugin-api@0.3.0
+  - @backstage/backend-common@0.18.0
+  - @backstage/backend-tasks@0.4.1
+  - @backstage/config@1.0.6
+  - @backstage/cli-common@0.1.11
+  - @backstage/config-loader@1.1.8
+  - @backstage/errors@1.1.4
+  - @backstage/types@1.0.2
+  - @backstage/plugin-auth-node@0.2.9
+  - @backstage/plugin-permission-node@0.7.3
+
+## 0.3.0-next.1
+
+### Minor Changes
+
+- 02b119ff93: **BREAKING**: The `httpRouterFactory` now accepts a `getPath` option rather than `indexPlugin`. To set up custom index path, configure the new `rootHttpRouterFactory` with a custom `indexPath` instead.
+
+  Added an implementation for the new `rootHttpRouterServiceRef`.
+
+### Patch Changes
+
+- ecc6bfe4c9: Use new `ServiceFactoryOrFunction` type.
+- b99c030f1b: Moved over implementation of the root HTTP service from `@backstage/backend-common`, and replaced the `middleware` option with a `configure` callback option.
+- 150a7dd790: An error will now be thrown if attempting to override the plugin metadata service.
+- 015a6dced6: The `createSpecializedBackend` function will now throw an error if duplicate service implementations are provided.
+- e3fca10038: Tweaked the plugin logger to use `plugin` as the label for the plugin ID, rather than `pluginId`.
+- 8e06f3cf00: Switched imports of `loggerToWinstonLogger` to `@backstage/backend-common`.
+- Updated dependencies
+  - @backstage/backend-plugin-api@0.3.0-next.1
+  - @backstage/backend-common@0.18.0-next.1
+  - @backstage/backend-tasks@0.4.1-next.1
+  - @backstage/plugin-permission-node@0.7.3-next.1
+  - @backstage/config@1.0.6-next.0
+  - @backstage/errors@1.1.4
+
 ## 0.2.5-next.0
 
 ### Patch Changes

package/alpha/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backstage/backend-app-api",
-  "version": "0.2.5-next.0",
+  "version": "0.3.0",
   "main": "../dist/index.cjs.js",
   "types": "../dist/index.alpha.d.ts"
 }

package/dist/index.alpha.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 { }