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

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # @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

package/alpha/package.json

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

package/dist/index.alpha.d.ts

@@ -13,11 +13,16 @@ 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';
@@ -32,6 +37,7 @@ import { ServiceFactory } from '@backstage/backend-plugin-api';
 import { ServiceFactoryOrFunction } from '@backstage/backend-plugin-api';
 import { ServiceRef } from '@backstage/backend-plugin-api';
 import { TokenManagerService } from '@backstage/backend-plugin-api';
+import { transport } from 'winston';
 import { UrlReader } from '@backstage/backend-common';
 
 /**
@@ -44,10 +50,28 @@ export declare interface Backend {
 }
 
 /** @public */
-export declare const cacheFactory: (options?: undefined) => ServiceFactory<PluginCacheManager>;
+export declare const cacheFactory: () => ServiceFactory<PluginCacheManager>;
 
 /** @public */
-export declare const configFactory: (options?: undefined) => ServiceFactory<ConfigService>;
+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 function createConfigSecretEnumerator(options: {
+    logger: LoggerService;
+    dir?: string;
+}): Promise<(config: Config) => Iterable<string>>;
 
 /**
  * Creates a Node.js HTTP or HTTPS server instance.
@@ -71,10 +95,37 @@ export declare interface CreateSpecializedBackendOptions {
 }
 
 /** @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.
@@ -93,12 +144,12 @@ export declare const httpRouterFactory: (options?: HttpRouterFactoryOptions | un
 /**
  * @public
  */
-export declare type HttpRouterFactoryOptions = {
+export declare interface HttpRouterFactoryOptions {
     /**
      * A callback used to generate the path for each plugin, defaults to `/api/{pluginId}`.
      */
     getPath(pluginId: string): string;
-};
+}
 
 /**
  * Options for configuring HTTPS for an HTTP server.
@@ -129,13 +180,42 @@ export declare type HttpServerOptions = {
     };
 };
 
+/** @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.
@@ -261,7 +341,7 @@ export declare interface MiddlewareFactoryOptions {
 }
 
 /** @public */
-export declare const permissionsFactory: (options?: undefined) => ServiceFactory<PermissionsService>;
+export declare const permissionsFactory: () => ServiceFactory<PermissionsService>;
 
 /**
  * Attempts to read a CORS options object from the backend configuration object.
@@ -320,14 +400,15 @@ export declare interface RootHttpRouterConfigureOptions {
 }
 
 /** @public */
-export declare const rootHttpRouterFactory: (options?: RootHttpRouterFactoryOptions | undefined) => ServiceFactory<RootHttpRouterService>;
+export declare const rootHttpRouterFactory: () => ServiceFactory<RootHttpRouterService>;
 
 /**
  * @public
  */
 export declare type RootHttpRouterFactoryOptions = {
     /**
-     * The path to forward all unmatched requests to. Defaults to '/api/app'
+     * 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;
@@ -336,13 +417,13 @@ export declare type RootHttpRouterFactoryOptions = {
 /**
  * Allows plugins to register shutdown hooks that are run when the process is about to exit.
  * @public */
-export declare const rootLifecycleFactory: (options?: undefined) => ServiceFactory<RootLifecycleService>;
+export declare const rootLifecycleFactory: () => ServiceFactory<RootLifecycleService>;
 
 /** @public */
-export declare const rootLoggerFactory: (options?: undefined) => ServiceFactory<RootLoggerService>;
+export declare const rootLoggerFactory: () => ServiceFactory<RootLoggerService>;
 
 /** @public */
-export declare const schedulerFactory: (options?: undefined) => ServiceFactory<SchedulerService>;
+export declare const schedulerFactory: () => ServiceFactory<SchedulerService>;
 
 /**
  * @public
@@ -350,9 +431,50 @@ export declare const schedulerFactory: (options?: undefined) => ServiceFactory<S
 export declare type ServiceOrExtensionPoint<T = unknown> = ExtensionPoint<T> | ServiceRef<T>;
 
 /** @public */
-export declare const tokenManagerFactory: (options?: undefined) => ServiceFactory<TokenManagerService>;
+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/dist/index.beta.d.ts

@@ -13,11 +13,16 @@ 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';
@@ -32,6 +37,7 @@ import { ServiceFactory } from '@backstage/backend-plugin-api';
 import { ServiceFactoryOrFunction } from '@backstage/backend-plugin-api';
 import { ServiceRef } from '@backstage/backend-plugin-api';
 import { TokenManagerService } from '@backstage/backend-plugin-api';
+import { transport } from 'winston';
 import { UrlReader } from '@backstage/backend-common';
 
 /**
@@ -44,10 +50,28 @@ export declare interface Backend {
 }
 
 /** @public */
-export declare const cacheFactory: (options?: undefined) => ServiceFactory<PluginCacheManager>;
+export declare const cacheFactory: () => ServiceFactory<PluginCacheManager>;
 
 /** @public */
-export declare const configFactory: (options?: undefined) => ServiceFactory<ConfigService>;
+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 function createConfigSecretEnumerator(options: {
+    logger: LoggerService;
+    dir?: string;
+}): Promise<(config: Config) => Iterable<string>>;
 
 /**
  * Creates a Node.js HTTP or HTTPS server instance.
@@ -71,10 +95,37 @@ export declare interface CreateSpecializedBackendOptions {
 }
 
 /** @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.
@@ -93,12 +144,12 @@ export declare const httpRouterFactory: (options?: HttpRouterFactoryOptions | un
 /**
  * @public
  */
-export declare type HttpRouterFactoryOptions = {
+export declare interface HttpRouterFactoryOptions {
     /**
      * A callback used to generate the path for each plugin, defaults to `/api/{pluginId}`.
      */
     getPath(pluginId: string): string;
-};
+}
 
 /**
  * Options for configuring HTTPS for an HTTP server.
@@ -129,13 +180,42 @@ export declare type HttpServerOptions = {
     };
 };
 
+/** @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.
@@ -261,7 +341,7 @@ export declare interface MiddlewareFactoryOptions {
 }
 
 /** @public */
-export declare const permissionsFactory: (options?: undefined) => ServiceFactory<PermissionsService>;
+export declare const permissionsFactory: () => ServiceFactory<PermissionsService>;
 
 /**
  * Attempts to read a CORS options object from the backend configuration object.
@@ -320,14 +400,15 @@ export declare interface RootHttpRouterConfigureOptions {
 }
 
 /** @public */
-export declare const rootHttpRouterFactory: (options?: RootHttpRouterFactoryOptions | undefined) => ServiceFactory<RootHttpRouterService>;
+export declare const rootHttpRouterFactory: () => ServiceFactory<RootHttpRouterService>;
 
 /**
  * @public
  */
 export declare type RootHttpRouterFactoryOptions = {
     /**
-     * The path to forward all unmatched requests to. Defaults to '/api/app'
+     * 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;
@@ -336,13 +417,13 @@ export declare type RootHttpRouterFactoryOptions = {
 /**
  * Allows plugins to register shutdown hooks that are run when the process is about to exit.
  * @public */
-export declare const rootLifecycleFactory: (options?: undefined) => ServiceFactory<RootLifecycleService>;
+export declare const rootLifecycleFactory: () => ServiceFactory<RootLifecycleService>;
 
 /** @public */
-export declare const rootLoggerFactory: (options?: undefined) => ServiceFactory<RootLoggerService>;
+export declare const rootLoggerFactory: () => ServiceFactory<RootLoggerService>;
 
 /** @public */
-export declare const schedulerFactory: (options?: undefined) => ServiceFactory<SchedulerService>;
+export declare const schedulerFactory: () => ServiceFactory<SchedulerService>;
 
 /**
  * @public
@@ -350,9 +431,50 @@ export declare const schedulerFactory: (options?: undefined) => ServiceFactory<S
 export declare type ServiceOrExtensionPoint<T = unknown> = ExtensionPoint<T> | ServiceRef<T>;
 
 /** @public */
-export declare const tokenManagerFactory: (options?: undefined) => ServiceFactory<TokenManagerService>;
+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 { }