@backstage/core-app-api 1.3.1-next.0 → 1.4.0

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # @backstage/core-app-api
 
+## 1.4.0
+
+### Minor Changes
+
+- bca8e8b393: Allow defining application level feature flags. See [Feature Flags documentation](https://backstage.io/docs/plugins/feature-flags#in-the-application) for reference.
+
+### Patch Changes
+
+- Updated dependencies
+  - @backstage/core-plugin-api@1.3.0
+  - @backstage/config@1.0.6
+  - @backstage/types@1.0.2
+  - @backstage/version-bridge@1.0.3
+
+## 1.4.0-next.1
+
+### Minor Changes
+
+- bca8e8b393: Allow defining application level feature flags. See [Feature Flags documentation](https://backstage.io/docs/plugins/feature-flags#in-the-application) for reference.
+
+### Patch Changes
+
+- Updated dependencies
+  - @backstage/core-plugin-api@1.3.0-next.1
+  - @backstage/config@1.0.6-next.0
+  - @backstage/types@1.0.2
+  - @backstage/version-bridge@1.0.3
+
 ## 1.3.1-next.0
 
 ### Patch Changes

package/dist/index.d.ts

@@ -739,6 +739,10 @@ declare type AppOptions = {
             type: string;
         }>;
     }>;
+    /**
+     * Application level feature flags.
+     */
+    featureFlags?: (FeatureFlag & Omit<FeatureFlag, 'pluginId'>)[];
     /**
      * Supply components to the app to override the default ones.
      */

package/dist/index.esm.js

@@ -49,6 +49,10 @@ class ApiResolver {
     this.factories = factories;
     this.apis = /* @__PURE__ */ new Map();
   }
+  /**
+   * Validate factories by making sure that each of the apis can be created
+   * without hitting any circular dependencies.
+   */
   static validateFactories(factories, apis) {
     for (const api of apis) {
       const heap = [api];
@@ -119,6 +123,13 @@ class ApiFactoryRegistry {
   constructor() {
     this.factories = /* @__PURE__ */ new Map();
   }
+  /**
+   * Register a new API factory. Returns true if the factory was added
+   * to the registry.
+   *
+   * A factory will not be added to the registry if there is already
+   * an existing factory with the same or higher priority.
+   */
   register(scope, factory) {
     const priority = ScopePriority[scope];
     const existing = this.factories.get(factory.api.id);
@@ -645,6 +656,12 @@ class StaticAuthSessionManager {
     this.stateTracker.setIsSignedIn(true);
     return this.currentSession;
   }
+  /**
+   * We don't call this.connector.removeSession here, since this session manager
+   * is intended to be static. As such there's no need to hit the remote logout
+   * endpoint - simply discarding the local session state when signing out is
+   * enough.
+   */
   async removeSession() {
     this.currentSession = void 0;
     this.stateTracker.setIsSignedIn(false);
@@ -1179,9 +1196,25 @@ class MultipleAnalyticsApi {
   constructor(actualApis) {
     this.actualApis = actualApis;
   }
+  /**
+   * Create an AnalyticsApi implementation from an array of concrete
+   * implementations.
+   *
+   * @example
+   *
+   * ```jsx
+   * MultipleAnalyticsApi.fromApis([
+   *   SomeAnalyticsApi.fromConfig(configApi),
+   *   new CustomAnalyticsApi(),
+   * ]);
+   * ```
+   */
   static fromApis(actualApis) {
     return new MultipleAnalyticsApi(actualApis);
   }
+  /**
+   * Forward the event to all configured analytics API implementations.
+   */
   captureEvent(event) {
     this.actualApis.forEach((analyticsApi) => {
       try {
@@ -1247,6 +1280,13 @@ class UrlPatternDiscovery {
   constructor(parts) {
     this.parts = parts;
   }
+  /**
+   * Creates a new UrlPatternDiscovery given a template. The the only
+   * interpolation done for the template is to replace instances of `{{pluginId}}`
+   * with the ID of the plugin being requested.
+   *
+   * Example pattern: `http://localhost:7007/api/{{ pluginId }}`
+   */
   static compile(pattern) {
     const parts = pattern.split(/\{\{\s*pluginId\s*\}\}/);
     const urlStr = parts.join("pluginId");
@@ -1301,6 +1341,9 @@ class ErrorApiForwarder {
 }
 
 class UnhandledErrorForwarder {
+  /**
+   * Add event listener, such that unhandled errors can be forwarded using an given `ErrorApi` instance
+   */
   static forward(errorApi, errorContext) {
     window.addEventListener(
       "unhandledrejection",
@@ -1483,9 +1526,38 @@ function isUrl(a) {
 }
 
 class FetchMiddlewares {
+  /**
+   * Handles translation from `plugin://` URLs to concrete http(s) URLs based on
+   * the discovery API.
+   *
+   * @remarks
+   *
+   * If the request is for `plugin://catalog/entities?filter=x=y`, the discovery
+   * API will be queried for `'catalog'`. If it returned
+   * `https://backstage.example.net/api/catalog`, the resulting query would be
+   * `https://backstage.example.net/api/catalog/entities?filter=x=y`.
+   *
+   * If the incoming URL protocol was not `plugin`, the request is just passed
+   * through verbatim to the underlying implementation.
+   */
   static resolvePluginProtocol(options) {
     return new PluginProtocolResolverFetchMiddleware(options.discoveryApi);
   }
+  /**
+   * Injects a Backstage token header when the user is signed in.
+   *
+   * @remarks
+   *
+   * Per default, an `Authorization: Bearer <token>` is generated. This can be
+   * customized using the `header` option.
+   *
+   * The header injection only happens on allowlisted URLs. Per default, if the
+   * `config` option is passed in, the `backend.baseUrl` is allowlisted, unless
+   * the `urlPrefixAllowlist` or `allowUrl` options are passed in, in which case
+   * they take precedence. If you pass in neither config nor an
+   * allowlist/callback, the middleware will have no effect since effectively no
+   * request will match the (nonexistent) rules.
+   */
   static injectIdentityAuth(options) {
     return IdentityAuthInjectorFetchMiddleware.create(options);
   }
@@ -1589,6 +1661,7 @@ class OAuthRequestManager {
       return handler.request(scopes);
     };
   }
+  // Converts the pending request and popup options into a popup request that we can forward to subscribers.
   makeAuthRequest(request, options) {
     const { scopes } = request;
     if (!scopes) {
@@ -1767,6 +1840,7 @@ function readBasePath(configApi) {
   let { pathname } = new URL(
     (_a = configApi.getOptionalString("app.baseUrl")) != null ? _a : "/",
     "http://sample.dev"
+    // baseUrl can be specified as just a path
   );
   pathname = pathname.replace(/\/*$/, "");
   return pathname;
@@ -1931,6 +2005,7 @@ const MATCH_ALL_ROUTE = {
   caseSensitive: false,
   path: "*",
   element: "match-all",
+  // These elements aren't used, so we add in a bit of debug information
   routeRefs: /* @__PURE__ */ new Set()
 };
 function stringifyNode(node) {
@@ -2416,6 +2491,7 @@ class AppIdentityProxy {
       this.resolveTarget = resolve;
     });
   }
+  // This is called by the app manager once the sign-in page provides us with an implementation
   setTarget(identityApi, targetOptions) {
     this.target = identityApi;
     this.signOutTargetUrl = targetOptions.signOutTargetUrl;
@@ -2577,12 +2653,29 @@ class ApiRegistry {
   static builder() {
     return new ApiRegistryBuilder();
   }
+  /**
+   * Creates a new ApiRegistry with a list of API implementations.
+   *
+   * @param apis - A list of pairs mapping an ApiRef to its respective implementation
+   */
   static from(apis) {
     return new ApiRegistry(new Map(apis.map(([api, impl]) => [api.id, impl])));
   }
+  /**
+   * Creates a new ApiRegistry with a single API implementation.
+   *
+   * @param api - ApiRef for the API to add
+   * @param impl - Implementation of the API to add
+   */
   static with(api, impl) {
     return new ApiRegistry(/* @__PURE__ */ new Map([[api.id, impl]]));
   }
+  /**
+   * Returns a new ApiRegistry with the provided API added to the existing ones.
+   *
+   * @param api - ApiRef for the API to add
+   * @param impl - Implementation of the API to add
+   */
   with(api, impl) {
     return new ApiRegistry(new Map([...this.apis, [api.id, impl]]));
   }
@@ -2715,14 +2808,15 @@ class AppManager {
   constructor(options) {
     this.appIdentityProxy = new AppIdentityProxy();
     __privateAdd(this, _getProviderCalled, false);
-    var _a, _b, _c, _d;
+    var _a, _b, _c, _d, _e;
     this.apis = (_a = options.apis) != null ? _a : [];
     this.icons = options.icons;
     this.plugins = new Set((_b = options.plugins) != null ? _b : []);
+    this.featureFlags = (_c = options.featureFlags) != null ? _c : [];
     this.components = options.components;
     this.themes = options.themes;
-    this.configLoader = (_c = options.configLoader) != null ? _c : defaultConfigLoader;
-    this.defaultApis = (_d = options.defaultApis) != null ? _d : [];
+    this.configLoader = (_d = options.configLoader) != null ? _d : defaultConfigLoader;
+    this.defaultApis = (_e = options.defaultApis) != null ? _e : [];
     this.bindRoutes = options.bindRoutes;
     this.apiFactoryRegistry = new ApiFactoryRegistry();
   }
@@ -2803,6 +2897,12 @@ class AppManager {
         needsFeatureFlagRegistrationRef.current = false;
         const featureFlagsApi = this.getApiHolder().get(featureFlagsApiRef);
         if (featureFlagsApi) {
+          for (const flag of this.featureFlags) {
+            featureFlagsApi.registerFlag({
+              ...flag,
+              pluginId: ""
+            });
+          }
           for (const plugin of this.plugins.values()) {
             if ("getFeatureFlags" in plugin) {
               for (const flag of plugin.getFeatureFlags()) {
@@ -2969,11 +3069,15 @@ const FlatRoutes = (props) => {
       }
       return [
         {
+          // Each route matches any sub route, except for the explicit root path
           path,
           element,
           children: child.props.children ? [
+            // These are the children of each route, which we all add in under a catch-all
+            // subroute in order to make them available to `useOutlet`
             {
               path: path === "/" ? "/" : "*",
+              // The root path must require an exact match
               element: child.props.children
             }
           ] : void 0