@backstage/backend-defaults 0.4.4 → 0.5.0-next.0

package/CHANGELOG.md

@@ -1,23 +1,115 @@
 # @backstage/backend-defaults
 
-## 0.4.4
+## 0.5.0-next.0
 
-### Patch Changes
+### Minor Changes
 
-- Updated dependencies
-  - @backstage/backend-common@0.24.1
-  - @backstage/backend-app-api@0.9.3
-  - @backstage/plugin-auth-node@0.5.1
-  - @backstage/plugin-events-node@0.3.10
-  - @backstage/plugin-permission-node@0.8.2
-  - @backstage/backend-plugin-api@0.8.1
-  - @backstage/config-loader@1.9.0
+- 359fcd7: **BREAKING**: The backwards compatibility with plugins using legacy auth through the token manager service has been removed. This means that instead of falling back to using the old token manager, requests towards plugins that don't support the new auth system will simply fail. Please make sure that all plugins in your deployment are hosted within a backend instance from the new backend system.
+- d425fc4: **BREAKING**: The return values from `createBackendPlugin`, `createBackendModule`, and `createServiceFactory` are now simply `BackendFeature` and `ServiceFactory`, instead of the previously deprecated form of a function that returns them. For this reason, `createServiceFactory` also no longer accepts the callback form where you provide direct options to the service. This also affects all `coreServices.*` service refs.
+
+  This may in particular affect tests; if you were effectively doing `createBackendModule({...})()` (note the parentheses), you can now remove those extra parentheses at the end. You may encounter cases of this in your `packages/backend/src/index.ts` too, where you add plugins, modules, and services. If you were using `createServiceFactory` with a function as its argument for the purpose of passing in options, this pattern has been deprecated for a while and is no longer supported. You may want to explore the new multiton patterns to achieve your goals, or moving settings to app-config.
+
+  As part of this change, the `IdentityFactoryOptions` type was removed, and can no longer be used to tweak that service. The identity service was also deprecated some time ago, and you will want to [migrate to the new auth system](https://backstage.io/docs/tutorials/auth-service-migration) if you still rely on it.
+
+- 19ff127: **BREAKING**: The default backend instance no longer provides implementations for the identity and token manager services, which have been removed from `@backstage/backend-plugin-api`.
+
+  If you rely on plugins that still require these services, you can add them to your own backend by re-creating the service reference and factory.
 
-## 0.4.3
+  The following can be used to implement the identity service:
+
+  ```ts
+  import {
+    coreServices,
+    createServiceFactory,
+    createServiceRef,
+  } from '@backstage/backend-plugin-api';
+  import {
+    DefaultIdentityClient,
+    IdentityApi,
+  } from '@backstage/plugin-auth-node';
+
+  backend.add(
+    createServiceFactory({
+      service: createServiceRef<IdentityApi>({ id: 'core.identity' }),
+      deps: {
+        discovery: coreServices.discovery,
+      },
+      async factory({ discovery }) {
+        return DefaultIdentityClient.create({ discovery });
+      },
+    }),
+  );
+  ```
+
+  The following can be used to implement the token manager service:
+
+  ```ts
+  import { ServerTokenManager, TokenManager } from '@backstage/backend-common';
+  import { createBackend } from '@backstage/backend-defaults';
+  import {
+    coreServices,
+    createServiceFactory,
+    createServiceRef,
+  } from '@backstage/backend-plugin-api';
+
+  backend.add(
+    createServiceFactory({
+      service: createServiceRef<TokenManager>({ id: 'core.tokenManager' }),
+      deps: {
+        config: coreServices.rootConfig,
+        logger: coreServices.rootLogger,
+      },
+      createRootContext({ config, logger }) {
+        return ServerTokenManager.fromConfig(config, {
+          logger,
+          allowDisabledTokenManager: true,
+        });
+      },
+      async factory(_deps, tokenManager) {
+        return tokenManager;
+      },
+    }),
+  );
+  ```
 
 ### Patch Changes
 
-- 91e78c3: `auth.externalAccess` should be optional in the config schema
+- 7f779c7: `auth.externalAccess` should be optional in the config schema
+- 7a72ec8: Exports the `discoveryFeatureLoader` as a replacement for the deprecated `featureDiscoveryService`.
+  The `discoveryFeatureLoader` is a new backend system [feature loader](https://backstage.io/docs/backend-system/architecture/feature-loaders/) that discovers backend features from the current `package.json` and its dependencies.
+  Here is an example using the `discoveryFeatureLoader` loader in a new backend instance:
+
+  ```ts
+  import { createBackend } from '@backstage/backend-defaults';
+  import { discoveryFeatureLoader } from '@backstage/backend-defaults';
+  //...
+
+  const backend = createBackend();
+  //...
+  backend.add(discoveryFeatureLoader);
+  //...
+  backend.start();
+  ```
+
+- 66dbf0a: Allow the cache service to accept the human duration format for TTL
+- 5a8fcb4: Added the option to skip database migrations by setting `skipMigrations: true` in config. This can be done globally in the database config or by plugin id.
+- 0b2a402: Updates to the config schema to match reality
+- Updated dependencies
+  - @backstage/backend-app-api@0.10.0-next.0
+  - @backstage/backend-plugin-api@0.9.0-next.0
+  - @backstage/plugin-permission-node@0.8.3-next.0
+  - @backstage/backend-common@0.25.0-next.0
+  - @backstage/plugin-events-node@0.4.0-next.0
+  - @backstage/plugin-auth-node@0.5.2-next.0
+  - @backstage/backend-dev-utils@0.1.5
+  - @backstage/cli-common@0.1.14
+  - @backstage/cli-node@0.2.7
+  - @backstage/config@1.2.0
+  - @backstage/config-loader@1.9.0
+  - @backstage/errors@1.2.4
+  - @backstage/integration@1.14.0
+  - @backstage/integration-aws-node@0.1.12
+  - @backstage/types@1.1.1
 
 ## 0.4.2
 

package/auth/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backstage/backend-defaults__auth",
-  "version": "0.4.4",
+  "version": "0.5.0-next.0",
   "main": "../dist/auth.cjs.js",
   "types": "../dist/auth.d.ts"
 }

package/cache/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backstage/backend-defaults__cache",
-  "version": "0.4.4",
+  "version": "0.5.0-next.0",
   "main": "../dist/cache.cjs.js",
   "types": "../dist/cache.d.ts"
 }

package/config.d.ts

@@ -14,8 +14,51 @@
  * limitations under the License.
  */
 
+import { HumanDuration } from '@backstage/types';
+
 export interface Config {
+  app: {
+    baseUrl: string; // defined in core, but repeated here without doc
+  };
+
   backend?: {
+    /**
+     * The full base URL of the backend, as seen from the browser's point of
+     * view as it makes calls to the backend.
+     */
+    baseUrl: string;
+
+    /** Address that the backend should listen to. */
+    listen?:
+      | string
+      | {
+          /** Address of the interface that the backend should bind to. */
+          host?: string;
+          /** Port that the backend should listen to. */
+          port?: string | number;
+        };
+
+    /**
+     * HTTPS configuration for the backend. If omitted the backend will serve HTTP.
+     *
+     * Setting this to `true` will cause self-signed certificates to be generated, which
+     * can be useful for local development or other non-production scenarios.
+     */
+    https?:
+      | true
+      | {
+          /** Certificate configuration */
+          certificate?: {
+            /** PEM encoded certificate. Use $file to load in a file */
+            cert: string;
+            /**
+             * PEM encoded certificate key. Use $file to load in a file.
+             * @visibility secret
+             */
+            key: string;
+          };
+        };
+
     /**
      * Options used by the default auth, httpAuth and userInfo services.
      */
@@ -353,4 +396,182 @@ export interface Config {
       plugins: string[];
     }>;
   };
+
+  /** Database connection configuration, select base database type using the `client` field */
+  database: {
+    /** Default database client to use */
+    client: 'better-sqlite3' | 'sqlite3' | 'pg';
+    /**
+     * Base database connection string, or object with individual connection properties
+     * @visibility secret
+     */
+    connection:
+      | string
+      | {
+          /**
+           * Password that belongs to the client User
+           * @visibility secret
+           */
+          password?: string;
+          /**
+           * Other connection settings
+           */
+          [key: string]: unknown;
+        };
+    /** Database name prefix override */
+    prefix?: string;
+    /**
+     * Whether to ensure the given database exists by creating it if it does not.
+     * Defaults to true if unspecified.
+     */
+    ensureExists?: boolean;
+    /**
+     * Whether to ensure the given database schema exists by creating it if it does not.
+     * Defaults to false if unspecified.
+     *
+     * NOTE: Currently only supported by the `pg` client when pluginDivisionMode: schema
+     */
+    ensureSchemaExists?: boolean;
+    /**
+     * How plugins databases are managed/divided in the provided database instance.
+     *
+     * `database` -> Plugins are each given their own database to manage their schemas/tables.
+     *
+     * `schema` -> Plugins will be given their own schema (in the specified/default database)
+     *             to manage their tables.
+     *
+     * NOTE: Currently only supported by the `pg` client.
+     *
+     * @default database
+     */
+    pluginDivisionMode?: 'database' | 'schema';
+    /** Configures the ownership of newly created schemas in pg databases. */
+    role?: string;
+    /**
+     * Arbitrary config object to pass to knex when initializing
+     * (https://knexjs.org/#Installation-client). Most notable is the debug
+     * and asyncStackTraces booleans
+     */
+    knexConfig?: object;
+    /** Skip running database migrations. */
+    skipMigrations?: boolean;
+    /** Plugin specific database configuration and client override */
+    plugin?: {
+      [pluginId: string]: {
+        /** Database client override */
+        client?: 'better-sqlite3' | 'sqlite3' | 'pg';
+        /**
+         * Database connection string or Knex object override
+         * @visibility secret
+         */
+        connection?: string | object;
+        /**
+         * Whether to ensure the given database exists by creating it if it does not.
+         * Defaults to base config if unspecified.
+         */
+        ensureExists?: boolean;
+        /**
+         * Whether to ensure the given database schema exists by creating it if it does not.
+         * Defaults to false if unspecified.
+         *
+         * NOTE: Currently only supported by the `pg` client when pluginDivisionMode: schema
+         */
+        ensureSchemaExists?: boolean;
+        /**
+         * Arbitrary config object to pass to knex when initializing
+         * (https://knexjs.org/#Installation-client). Most notable is the
+         * debug and asyncStackTraces booleans.
+         *
+         * This is merged recursively into the base knexConfig
+         */
+        knexConfig?: object;
+        /** Configures the ownership of newly created schemas in pg databases. */
+        role?: string;
+        /** Skip running database migrations. */
+        skipMigrations?: boolean;
+      };
+    };
+  };
+
+  /** Cache connection configuration, select cache type using the `store` field */
+  cache?:
+    | {
+        store: 'memory';
+        /** An optional default TTL (in milliseconds). */
+        defaultTtl?: number | HumanDuration;
+      }
+    | {
+        store: 'redis';
+        /**
+         * A redis connection string in the form `redis://user:pass@host:port`.
+         * @visibility secret
+         */
+        connection: string;
+        /** An optional default TTL (in milliseconds). */
+        defaultTtl?: number | HumanDuration;
+        /**
+         * Whether or not [useRedisSets](https://github.com/jaredwray/keyv/tree/main/packages/redis#useredissets) should be configured to this redis cache.
+         * Defaults to true if unspecified.
+         */
+        useRedisSets?: boolean;
+      }
+    | {
+        store: 'memcache';
+        /**
+         * A memcache connection string in the form `user:pass@host:port`.
+         * @visibility secret
+         */
+        connection: string;
+        /** An optional default TTL (in milliseconds). */
+        defaultTtl?: number | HumanDuration;
+      };
+
+  cors?: {
+    origin?: string | string[];
+    methods?: string | string[];
+    allowedHeaders?: string | string[];
+    exposedHeaders?: string | string[];
+    credentials?: boolean;
+    maxAge?: number;
+    preflightContinue?: boolean;
+    optionsSuccessStatus?: number;
+  };
+
+  /**
+   * Content Security Policy options.
+   *
+   * The keys are the plain policy ID, e.g. "upgrade-insecure-requests". The
+   * values are on the format that the helmet library expects them, as an
+   * array of strings. There is also the special value false, which means to
+   * remove the default value that Backstage puts in place for that policy.
+   */
+  csp?: { [policyId: string]: string[] | false };
+
+  /**
+   * Configuration related to URL reading, used for example for reading catalog info
+   * files, scaffolder templates, and techdocs content.
+   */
+  reading?: {
+    /**
+     * A list of targets to allow outgoing requests to. Users will be able to make
+     * requests on behalf of the backend to the targets that are allowed by this list.
+     */
+    allow?: Array<{
+      /**
+       * A host to allow outgoing requests to, being either a full host or
+       * a subdomain wildcard pattern with a leading `*`. For example `example.com`
+       * and `*.example.com` are valid values, `prod.*.example.com` is not.
+       * The host may also contain a port, for example `example.com:8080`.
+       */
+      host: string;
+
+      /**
+       * An optional list of paths. In case they are present only targets matching
+       * any of them will are allowed. You can use trailing slashes to make sure only
+       * subdirectories are allowed, for example `/mydir/` will allow targets with
+       * paths like `/mydir/a` but will block paths like `/mydir2`.
+       */
+      paths?: string[];
+    }>;
+  };
 }

package/database/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backstage/backend-defaults__database",
-  "version": "0.4.4",
+  "version": "0.5.0-next.0",
   "main": "../dist/database.cjs.js",
   "types": "../dist/database.d.ts"
 }

package/discovery/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@backstage/backend-defaults__discovery",
-  "version": "0.4.4",
+  "version": "0.5.0-next.0",
   "main": "../dist/discovery.cjs.js",
   "types": "../dist/discovery.d.ts"
 }

package/dist/auth.cjs.js

@@ -11,15 +11,13 @@ var luxon = require('luxon');
 var fs = require('fs');
 
 class DefaultAuthService {
-  constructor(userTokenHandler, pluginTokenHandler, externalTokenHandler, tokenManager, pluginId, disableDefaultAuthPolicy, pluginKeySource, logger) {
+  constructor(userTokenHandler, pluginTokenHandler, externalTokenHandler, pluginId, disableDefaultAuthPolicy, pluginKeySource) {
     this.userTokenHandler = userTokenHandler;
     this.pluginTokenHandler = pluginTokenHandler;
     this.externalTokenHandler = externalTokenHandler;
-    this.tokenManager = tokenManager;
     this.pluginId = pluginId;
     this.disableDefaultAuthPolicy = disableDefaultAuthPolicy;
     this.pluginKeySource = pluginKeySource;
-    this.logger = logger;
   }
   async authenticate(token, options) {
     const pluginResult = await this.pluginTokenHandler.verifyToken(token);
@@ -85,45 +83,25 @@ class DefaultAuthService {
     if (type === "none" && this.disableDefaultAuthPolicy) {
       return { token: "" };
     }
-    const targetSupportsNewAuth = await this.pluginTokenHandler.isTargetPluginSupported(targetPluginId);
     switch (type) {
       case "service":
-        if (targetSupportsNewAuth) {
-          return this.pluginTokenHandler.issueToken({
-            pluginId: this.pluginId,
-            targetPluginId
-          });
-        }
-        this.logger.warn(
-          `DEPRECATION WARNING: A call to the '${targetPluginId}' plugin had to fall back to using deprecated auth via the token manager service. Please migrate all plugins to the new auth service, see https://backstage.io/docs/tutorials/auth-service-migration for more information`
-        );
-        return this.tokenManager.getToken().catch((error) => {
-          throw new errors.ForwardedError(
-            `Unable to generate legacy token for communication with the '${targetPluginId}' plugin. You will typically encounter this error when attempting to call a plugin that does not exist, or is deployed with an old version of Backstage`,
-            error
-          );
+        return this.pluginTokenHandler.issueToken({
+          pluginId: this.pluginId,
+          targetPluginId
         });
       case "user": {
         const { token } = internalForward;
         if (!token) {
           throw new Error("User credentials is unexpectedly missing token");
         }
-        if (targetSupportsNewAuth) {
-          const onBehalfOf = await this.userTokenHandler.createLimitedUserToken(
-            token
-          );
-          return this.pluginTokenHandler.issueToken({
-            pluginId: this.pluginId,
-            targetPluginId,
-            onBehalfOf
-          });
-        }
-        if (this.userTokenHandler.isLimitedUserToken(token)) {
-          throw new errors.AuthenticationError(
-            `Unable to call '${targetPluginId}' plugin on behalf of user, because the target plugin does not support on-behalf-of tokens or the plugin doesn't exist`
-          );
-        }
-        return { token };
+        const onBehalfOf = await this.userTokenHandler.createLimitedUserToken(
+          token
+        );
+        return this.pluginTokenHandler.issueToken({
+          pluginId: this.pluginId,
+          targetPluginId,
+          onBehalfOf
+        });
       }
       default:
         throw new errors.AuthenticationError(
@@ -622,7 +600,7 @@ class PluginTokenHandler {
     }
     if (!await this.isTargetPluginSupported(pluginId)) {
       throw new errors.AuthenticationError(
-        `Received a plugin token where the source '${pluginId}' plugin unexpectedly does not have a JWKS endpoint`
+        `Received a plugin token where the source '${pluginId}' plugin unexpectedly does not have a JWKS endpoint. The target plugin needs to be migrated to be installed in an app using the new backend system.`
       );
     }
     const newClient = new JwksClient(async () => {
@@ -980,14 +958,9 @@ const authServiceFactory = backendPluginApi.createServiceFactory({
     logger: backendPluginApi.coreServices.rootLogger,
     discovery: backendPluginApi.coreServices.discovery,
     plugin: backendPluginApi.coreServices.pluginMetadata,
-    database: backendPluginApi.coreServices.database,
-    // Re-using the token manager makes sure that we use the same generated keys for
-    // development as plugins that have not yet been migrated. It's important that this
-    // keeps working as long as there are plugins that have not been migrated to the
-    // new auth services in the new backend system.
-    tokenManager: backendPluginApi.coreServices.tokenManager
+    database: backendPluginApi.coreServices.database
   },
-  async factory({ config, discovery, plugin, tokenManager, logger, database }) {
+  async factory({ config, discovery, plugin, logger, database }) {
     const disableDefaultAuthPolicy = config.getOptionalBoolean(
       "backend.auth.dangerouslyDisableDefaultAuthPolicy"
     ) ?? false;
@@ -1017,11 +990,9 @@ const authServiceFactory = backendPluginApi.createServiceFactory({
       userTokens,
       pluginTokens,
       externalTokens,
-      tokenManager,
       plugin.getId(),
       disableDefaultAuthPolicy,
-      keySource,
-      logger
+      keySource
     );
   }
 });