[8.19] [Feature Flags] Client-side bootstrapping (#224258) (#224833)

# Backport

This will backport the following commits from `main` to `8.19`:
- [[Feature Flags] Client-side bootstrapping
(#224258)](#224258)

<!--- Backport version: 9.6.6 -->

### Questions ?
Please refer to the [Backport tool
documentation](https://github.com/sorenlouv/backport)

<!--BACKPORT [{"author":{"name":"Alejandro Fernández
Haro","email":"[email protected]"},"sourceCommit":{"committedDate":"2025-06-23T10:28:06Z","message":"[Feature
Flags] Client-side bootstrapping
(#224258)","sha":"fd7f85149cecdcd7f73d1b914f2c7b83fbd01781","branchLabelMapping":{"^v9.1.0$":"main","^v(\\d+).(\\d+).\\d+$":"$1.$2"}},"sourcePullRequest":{"labels":["Team:Core","Team:Security","enhancement","release_note:skip","backport:version","v9.1.0","v8.19.0"],"title":"[Feature
Flags] Client-side
bootstrapping","number":224258,"url":"https://github.com/elastic/kibana/pull/224258","mergeCommit":{"message":"[Feature
Flags] Client-side bootstrapping
(#224258)","sha":"fd7f85149cecdcd7f73d1b914f2c7b83fbd01781"}},"sourceBranch":"main","suggestedTargetBranches":["8.19"],"targetPullRequestStates":[{"branch":"main","label":"v9.1.0","branchLabelMappingKey":"^v9.1.0$","isSourceBranch":true,"state":"MERGED","url":"https://github.com/elastic/kibana/pull/224258","number":224258,"mergeCommit":{"message":"[Feature
Flags] Client-side bootstrapping
(#224258)","sha":"fd7f85149cecdcd7f73d1b914f2c7b83fbd01781"}},{"branch":"8.19","label":"v8.19.0","branchLabelMappingKey":"^v(\\d+).(\\d+).\\d+$","isSourceBranch":false,"state":"NOT_CREATED"}]}]
BACKPORT-->

---------

Co-authored-by: Alejandro Fernández Haro <[email protected]>

Author: kibanamachine

src/core/packages/feature-flags/browser-internal/src/feature_flags_service.test.ts

@@ -249,6 +249,7 @@ describe('FeatureFlagsService Browser', () => {
           'myPlugin.myOverriddenFlag': true,
           myDestructuredObjPlugin: { myOverriddenFlag: true },
         },
+        initialFeatureFlags: {},
       });
       featureFlagsService.setup({ injectedMetadata });
       startContract = await featureFlagsService.start();

src/core/packages/feature-flags/browser-internal/src/feature_flags_service.ts

@@ -24,7 +24,7 @@ import { get } from 'lodash';
 
 /**
  * setup method dependencies
- * @private
+ * @internal
  */
 export interface FeatureFlagsSetupDeps {
   /**
@@ -35,7 +35,7 @@ export interface FeatureFlagsSetupDeps {
 
 /**
  * The browser-side Feature Flags Service
- * @private
+ * @internal
  */
 export class FeatureFlagsService {
   private readonly featureFlagsClient: Client;
@@ -64,6 +64,7 @@ export class FeatureFlagsService {
       this.overrides = featureFlagsInjectedMetadata.overrides;
     }
     return {
+      getInitialFeatureFlags: () => featureFlagsInjectedMetadata?.initialFeatureFlags ?? {},
       setProvider: (provider) => {
         if (this.isProviderReadyPromise) {
           throw new Error('A provider has already been set. This API cannot be called twice.');
@@ -159,7 +160,7 @@ export class FeatureFlagsService {
 
   /**
    * Waits for the provider initialization with a timeout to avoid holding the page load for too long
-   * @private
+   * @internal
    */
   private async waitForProviderInitialization() {
     // Adding a timeout here to avoid hanging the start for too long if the provider is unresponsive
@@ -185,7 +186,7 @@ export class FeatureFlagsService {
    * @param evaluationFn The actual evaluation API
    * @param flagName The name of the flag to evaluate
    * @param fallbackValue The fallback value
-   * @private
+   * @internal
    */
   private evaluateFlag<T extends string | boolean | number>(
     evaluationFn: (flagName: string, fallbackValue: T) => T,
@@ -206,7 +207,7 @@ export class FeatureFlagsService {
   /**
    * Formats the provided context to fulfill the expected multi-context structure.
    * @param contextToAppend The {@link EvaluationContext} to append.
-   * @private
+   * @internal
    */
   private async appendContext(contextToAppend: EvaluationContext): Promise<void> {
     // If no kind provided, default to the project|deployment level.

src/core/packages/feature-flags/browser-mocks/index.ts

@@ -14,6 +14,7 @@ import { of } from 'rxjs';
 
 const createFeatureFlagsSetup = (): jest.Mocked<FeatureFlagsSetup> => {
   return {
+    getInitialFeatureFlags: jest.fn().mockImplementation(() => ({})),
     setProvider: jest.fn(),
     appendContext: jest.fn().mockImplementation(Promise.resolve),
   };

src/core/packages/feature-flags/browser/src/types.ts

@@ -87,6 +87,12 @@ export type SingleContextEvaluationContext = OpenFeatureEvaluationContext & {
  * @public
  */
 export interface FeatureFlagsSetup {
+  /**
+   * Used for bootstrapping the browser-side client with a seed of the feature flags for faster load-times.
+   * @remarks It shouldn't be used to evaluate the feature flags because it won't report usage.
+   */
+  getInitialFeatureFlags: () => Record<string, unknown>;
+
   /**
    * Registers an OpenFeature provider to talk to the
    * 3rd-party service that manages the Feature Flags.

src/core/packages/feature-flags/server-internal/src/feature_flags_config.ts

@@ -12,23 +12,23 @@ import { schema } from '@kbn/config-schema';
 
 /**
  * The definition of the validation config schema
- * @private
+ * @internal
  */
 const configSchema = schema.object({
   overrides: schema.maybe(schema.recordOf(schema.string(), schema.any())),
 });
 
 /**
  * Type definition of the Feature Flags configuration
- * @private
+ * @internal
  */
 export interface FeatureFlagsConfig {
   overrides?: Record<string, unknown>;
 }
 
 /**
  * Config descriptor for the feature flags service
- * @private
+ * @internal
  */
 export const featureFlagsConfig: ServiceConfigDescriptor<FeatureFlagsConfig> = {
   /**

src/core/packages/feature-flags/server-internal/src/feature_flags_service.test.ts

@@ -320,4 +320,19 @@ describe('FeatureFlagsService Server', () => {
       'myDestructuredObjPlugin.myOverriddenFlag': true,
     });
   });
+
+  describe('bootstrapping helpers', () => {
+    test('return empty initial feature flags if no getter registered', async () => {
+      const { getInitialFeatureFlags } = featureFlagsService.setup();
+      await expect(getInitialFeatureFlags()).resolves.toEqual({});
+    });
+
+    test('calls the getter when registered', async () => {
+      const { setInitialFeatureFlagsGetter, getInitialFeatureFlags } = featureFlagsService.setup();
+      const mockGetter = jest.fn().mockResolvedValue({ myFlag: true });
+      setInitialFeatureFlagsGetter(mockGetter);
+      await expect(getInitialFeatureFlags()).resolves.toEqual({ myFlag: true });
+      expect(mockGetter).toHaveBeenCalledTimes(1);
+    });
+  });
 });

src/core/packages/feature-flags/server-internal/src/feature_flags_service.ts

@@ -26,31 +26,38 @@ import {
 import deepMerge from 'deepmerge';
 import { filter, switchMap, startWith, Subject, BehaviorSubject, pairwise, takeUntil } from 'rxjs';
 import { get } from 'lodash';
+import type { InitialFeatureFlagsGetter } from '@kbn/core-feature-flags-server/src/contracts';
 import { createOpenFeatureLogger } from './create_open_feature_logger';
 import { setProviderWithRetries } from './set_provider_with_retries';
 import { type FeatureFlagsConfig, featureFlagsConfig } from './feature_flags_config';
 
 /**
  * Core-internal contract for the setup lifecycle step.
- * @private
+ * @internal
  */
 export interface InternalFeatureFlagsSetup extends FeatureFlagsSetup {
   /**
    * Used by the rendering service to share the overrides with the service on the browser side.
    */
   getOverrides: () => Record<string, unknown>;
+  /**
+   * Required to bootstrap the browser-side OpenFeature client with a seed of the feature flags for faster load-times
+   * and to work-around air-gapped environments.
+   */
+  getInitialFeatureFlags: () => Promise<Record<string, unknown>>;
 }
 
 /**
  * The server-side Feature Flags Service
- * @private
+ * @internal
  */
 export class FeatureFlagsService {
   private readonly featureFlagsClient: Client;
   private readonly logger: Logger;
   private readonly stop$ = new Subject<void>();
   private readonly overrides$ = new BehaviorSubject<Record<string, unknown>>({});
   private context: MultiContextEvaluationContext = { kind: 'multi' };
+  private initialFeatureFlagsGetter: InitialFeatureFlagsGetter = async () => ({});
 
   /**
    * The core service's constructor
@@ -77,6 +84,10 @@ export class FeatureFlagsService {
 
     return {
       getOverrides: () => this.overrides$.value,
+      getInitialFeatureFlags: () => this.initialFeatureFlagsGetter(),
+      setInitialFeatureFlagsGetter: (getter: InitialFeatureFlagsGetter) => {
+        this.initialFeatureFlagsGetter = getter;
+      },
       setProvider: (provider) => {
         if (OpenFeature.providerMetadata !== NOOP_PROVIDER.metadata) {
           throw new Error('A provider has already been set. This API cannot be called twice.');
@@ -175,7 +186,7 @@ export class FeatureFlagsService {
    * @param evaluationFn The actual evaluation API
    * @param flagName The name of the flag to evaluate
    * @param fallbackValue The fallback value
-   * @private
+   * @internal
    */
   private async evaluateFlag<T extends string | boolean | number>(
     evaluationFn: (flagName: string, fallbackValue: T) => Promise<T>,
@@ -196,7 +207,7 @@ export class FeatureFlagsService {
   /**
    * Formats the provided context to fulfill the expected multi-context structure.
    * @param contextToAppend The {@link EvaluationContext} to append.
-   * @private
+   * @internal
    */
   private appendContext(contextToAppend: EvaluationContext): void {
     // If no kind provided, default to the project|deployment level.

src/core/packages/feature-flags/server-mocks/index.ts

@@ -23,11 +23,13 @@ const createFeatureFlagsInternalSetup = (): jest.Mocked<InternalFeatureFlagsSetu
   return {
     ...createFeatureFlagsSetup(),
     getOverrides: jest.fn().mockReturnValue({}),
+    getInitialFeatureFlags: jest.fn().mockImplementation(async () => ({})),
   };
 };
 
 const createFeatureFlagsSetup = (): jest.Mocked<FeatureFlagsSetup> => {
   return {
+    setInitialFeatureFlagsGetter: jest.fn(),
     setProvider: jest.fn(),
     appendContext: jest.fn(),
   };

src/core/packages/feature-flags/server/index.ts

@@ -13,6 +13,7 @@ export type {
   SingleContextEvaluationContext,
   FeatureFlagsSetup,
   FeatureFlagsStart,
+  InitialFeatureFlagsGetter,
 } from './src/contracts';
 export type { FeatureFlagDefinition, FeatureFlagDefinitions } from './src/feature_flag_definition';
 export type { FeatureFlagsRequestHandlerContext } from './src/request_handler_context';

src/core/packages/feature-flags/server/src/contracts.ts

@@ -82,6 +82,12 @@ export type SingleContextEvaluationContext = OpenFeatureEvaluationContext & {
   kind?: 'organization' | 'kibana';
 };
 
+/**
+ * Getter function type to retrieve the initial feature flags.
+ * @internal
+ */
+export type InitialFeatureFlagsGetter = () => Promise<Record<string, unknown>>;
+
 /**
  * Setup contract of the Feature Flags Service
  * @public
@@ -101,6 +107,15 @@ export interface FeatureFlagsSetup {
    * @public
    */
   appendContext(contextToAppend: EvaluationContext): void;
+
+  /**
+   * Registers a getter function that will be used to retrieve the initial feature flags to be injected into the
+   * browser for faster bootstrapping.
+   * @param getter A function that returns all the feature flags and their values for this context.
+   * Ideally, using the underlying API shouldn't track them as actual evaluations.
+   * @internal
+   */
+  setInitialFeatureFlagsGetter(getter: InitialFeatureFlagsGetter): void;
 }
 
 /**