Merge pull request #21380 from backstage/mob/ff

frontend-*-api: add initial support for feature flags

packages/frontend-plugin-api/api-report.md

@@ -218,15 +218,13 @@ export interface BackstagePlugin<
   ExternalRoutes extends AnyExternalRoutes = AnyExternalRoutes,
 > {
   // (undocumented)
-  $$type: '@backstage/BackstagePlugin';
+  readonly $$type: '@backstage/BackstagePlugin';
   // (undocumented)
-  extensions: Extension<unknown>[];
+  readonly externalRoutes: ExternalRoutes;
   // (undocumented)
-  externalRoutes: ExternalRoutes;
+  readonly id: string;
   // (undocumented)
-  id: string;
-  // (undocumented)
-  routes: Routes;
+  readonly routes: Routes;
 }
 
 export { BackstageUserIdentity };
@@ -606,13 +604,15 @@ export type ExtensionInputValues<
 // @public (undocumented)
 export interface ExtensionOverrides {
   // (undocumented)
-  $$type: '@backstage/ExtensionOverrides';
+  readonly $$type: '@backstage/ExtensionOverrides';
 }
 
 // @public (undocumented)
 export interface ExtensionOverridesOptions {
   // (undocumented)
   extensions: Extension<unknown>[];
+  // (undocumented)
+  featureFlags?: FeatureFlagConfig[];
 }
 
 // @public
@@ -630,6 +630,11 @@ export interface ExternalRouteRef<
 
 export { FeatureFlag };
 
+// @public
+export type FeatureFlagConfig = {
+  name: string;
+};
+
 export { FeatureFlagsApi };
 
 export { featureFlagsApiRef };
@@ -707,6 +712,8 @@ export interface PluginOptions<
   // (undocumented)
   externalRoutes?: ExternalRoutes;
   // (undocumented)
+  featureFlags?: FeatureFlagConfig[];
+  // (undocumented)
   id: string;
   // (undocumented)
   routes?: Routes;

packages/frontend-plugin-api/src/wiring/createExtensionOverrides.test.ts

@@ -26,6 +26,7 @@ describe('createExtensionOverrides', () => {
       {
         "$$type": "@backstage/ExtensionOverrides",
         "extensions": [],
+        "featureFlags": [],
         "version": "v1",
       }
     `);
@@ -60,6 +61,7 @@ describe('createExtensionOverrides', () => {
             "output": {},
           },
         ],
+        "featureFlags": [],
         "version": "v1",
       }
     `);

packages/frontend-plugin-api/src/wiring/createExtensionOverrides.ts

@@ -15,21 +15,24 @@
  */
 
 import { Extension } from './createExtension';
+import { FeatureFlagConfig } from './types';
 
 /** @public */
 export interface ExtensionOverridesOptions {
   extensions: Extension<unknown>[];
+  featureFlags?: FeatureFlagConfig[];
 }
 
 /** @public */
 export interface ExtensionOverrides {
-  $$type: '@backstage/ExtensionOverrides';
+  readonly $$type: '@backstage/ExtensionOverrides';
 }
 
 /** @internal */
 export interface InternalExtensionOverrides extends ExtensionOverrides {
-  version: string;
-  extensions: Extension<unknown>[];
+  readonly version: 'v1';
+  readonly extensions: Extension<unknown>[];
+  readonly featureFlags: FeatureFlagConfig[];
 }
 
 /** @public */
@@ -40,6 +43,7 @@ export function createExtensionOverrides(
     $$type: '@backstage/ExtensionOverrides',
     version: 'v1',
     extensions: options.extensions,
+    featureFlags: options.featureFlags ?? [],
   } as InternalExtensionOverrides;
 }
 
@@ -50,12 +54,12 @@ export function toInternalExtensionOverrides(
   const internal = overrides as InternalExtensionOverrides;
   if (internal.$$type !== '@backstage/ExtensionOverrides') {
     throw new Error(
-      `Invalid translation resource, bad type '${internal.$$type}'`,
+      `Invalid extension overrides instance, bad type '${internal.$$type}'`,
     );
   }
   if (internal.version !== 'v1') {
     throw new Error(
-      `Invalid translation resource, bad version '${internal.version}'`,
+      `Invalid extension overrides instance, bad version '${internal.version}'`,
     );
   }
   return internal;

packages/frontend-plugin-api/src/wiring/createPlugin.ts

@@ -16,6 +16,7 @@
 
 import { Extension } from './createExtension';
 import { ExternalRouteRef, RouteRef } from '../routing';
+import { FeatureFlagConfig } from './types';
 
 /** @public */
 export type AnyRoutes = { [name in string]: RouteRef };
@@ -32,6 +33,7 @@ export interface PluginOptions<
   routes?: Routes;
   externalRoutes?: ExternalRoutes;
   extensions?: Extension<unknown>[];
+  featureFlags?: FeatureFlagConfig[];
 }
 
 /** @public */
@@ -39,11 +41,20 @@ export interface BackstagePlugin<
   Routes extends AnyRoutes = AnyRoutes,
   ExternalRoutes extends AnyExternalRoutes = AnyExternalRoutes,
 > {
-  $$type: '@backstage/BackstagePlugin';
-  id: string;
-  extensions: Extension<unknown>[];
-  routes: Routes;
-  externalRoutes: ExternalRoutes;
+  readonly $$type: '@backstage/BackstagePlugin';
+  readonly id: string;
+  readonly routes: Routes;
+  readonly externalRoutes: ExternalRoutes;
+}
+
+/** @public */
+export interface InternalBackstagePlugin<
+  Routes extends AnyRoutes = AnyRoutes,
+  ExternalRoutes extends AnyExternalRoutes = AnyExternalRoutes,
+> extends BackstagePlugin<Routes, ExternalRoutes> {
+  readonly version: 'v1';
+  readonly extensions: Extension<unknown>[];
+  readonly featureFlags: FeatureFlagConfig[];
 }
 
 /** @public */
@@ -54,10 +65,28 @@ export function createPlugin<
   options: PluginOptions<Routes, ExternalRoutes>,
 ): BackstagePlugin<Routes, ExternalRoutes> {
   return {
-    ...options,
+    $$type: '@backstage/BackstagePlugin',
+    version: 'v1',
+    id: options.id,
     routes: options.routes ?? ({} as Routes),
     externalRoutes: options.externalRoutes ?? ({} as ExternalRoutes),
     extensions: options.extensions ?? [],
-    $$type: '@backstage/BackstagePlugin',
-  };
+    featureFlags: options.featureFlags ?? [],
+  } as InternalBackstagePlugin<Routes, ExternalRoutes>;
+}
+
+/** @internal */
+export function toInternalBackstagePlugin(
+  plugin: BackstagePlugin,
+): InternalBackstagePlugin {
+  const internal = plugin as InternalBackstagePlugin;
+  if (internal.$$type !== '@backstage/BackstagePlugin') {
+    throw new Error(`Invalid plugin instance, bad type '${internal.$$type}'`);
+  }
+  if (internal.version !== 'v1') {
+    throw new Error(
+      `Invalid plugin instance, bad version '${internal.version}'`,
+    );
+  }
+  return internal;
 }

packages/frontend-plugin-api/src/wiring/index.ts

@@ -49,3 +49,4 @@ export {
   type ExtensionOverrides,
   type ExtensionOverridesOptions,
 } from './createExtensionOverrides';
+export type { FeatureFlagConfig } from './types';

packages/frontend-plugin-api/src/wiring/types.ts

@@ -0,0 +1,25 @@
+/*
+ * Copyright 2023 The Backstage Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * Feature flag configuration.
+ *
+ * @public
+ */
+export type FeatureFlagConfig = {
+  /** Feature flag name */
+  name: string;
+};