@squide/firefly 15.0.5 → 16.0.1

package/src/FireflyRuntime.tsx

@@ -1,110 +1,127 @@
 import type { RegisterRouteOptions, RuntimeMethodOptions, RuntimeOptions } from "@squide/core";
-import { MswPlugin, MswPluginName } from "@squide/msw";
+import { EnvironmentVariableKey, EnvironmentVariables, EnvironmentVariableValue, getEnvironmentVariablesPlugin } from "@squide/env-vars";
+import { getMswPlugin, MswPluginName, MswState } from "@squide/msw";
 import { type IReactRouterRuntime, ReactRouterRuntime, ReactRouterRuntimeScope, type Route } from "@squide/react-router";
 import type { HoneycombInstrumentationPartialClient } from "@workleap-telemetry/core";
 import type { Logger } from "@workleap/logging";
 import type { RequestHandler } from "msw";
-import { getAreModulesRegistered } from "./AppRouterReducer.ts";
 import { type AppRouterStore, createAppRouterStore } from "./AppRouterStore.ts";
 
-export interface FireflyRuntimeOptions extends RuntimeOptions {
-    useMsw?: boolean;
+export interface FireflyRuntimeOptions<TRuntime extends FireflyRuntime = FireflyRuntime> extends RuntimeOptions<TRuntime> {
     honeycombInstrumentationClient?: HoneycombInstrumentationPartialClient;
 }
 
 export interface RegisterRequestHandlersOptions extends RuntimeMethodOptions {}
 
 export interface IFireflyRuntime extends IReactRouterRuntime {
+    getMswState(): MswState;
     registerRequestHandlers: (handlers: RequestHandler[]) => void;
     get requestHandlers(): RequestHandler[];
-    get appRouterStore(): AppRouterStore;
     get isMswEnabled(): boolean;
+    registerEnvironmentVariable(key: EnvironmentVariableKey, value: EnvironmentVariableValue): void;
+    registerEnvironmentVariables(variables: Partial<EnvironmentVariables>): void;
+    getEnvironmentVariable(key: EnvironmentVariableKey): EnvironmentVariableValue;
+    getEnvironmentVariables(): EnvironmentVariables;
+    get appRouterStore(): AppRouterStore;
     get honeycombInstrumentationClient(): HoneycombInstrumentationPartialClient | undefined;
 }
 
-export class FireflyRuntime extends ReactRouterRuntime implements IFireflyRuntime {
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export class FireflyRuntime<TRuntime extends FireflyRuntime = any> extends ReactRouterRuntime<TRuntime> implements IFireflyRuntime {
     protected _appRouterStore: AppRouterStore;
-    protected _useMsw: boolean;
     protected _honeycombInstrumentationClient: HoneycombInstrumentationPartialClient | undefined;
 
-    constructor({ plugins, useMsw, honeycombInstrumentationClient, ...options }: FireflyRuntimeOptions = {}) {
-        if (useMsw) {
-            super({
-                plugins: [
-                    ...(plugins ?? []),
-                    runtime => new MswPlugin(runtime)
-                ],
-                ...options
-            });
-
-            this._useMsw = true;
-        } else {
-            super({
-                plugins,
-                ...options
-            });
-
-            this._useMsw = false;
-        }
+    constructor(options: FireflyRuntimeOptions = {}) {
+        const {
+            honeycombInstrumentationClient
+        } = options;
+
+        super(options);
 
         this._appRouterStore = createAppRouterStore(this._logger);
         this._honeycombInstrumentationClient = honeycombInstrumentationClient;
     }
 
+    registerRoute(route: Route, options: RegisterRouteOptions = {}) {
+        if (this.moduleManager.getAreModulesRegistered()) {
+            throw new Error("[squide] Cannot register a route once the modules are registered. Are you trying to register a route in a deferred registration function? Only navigation items can be registered in a deferred registration function.");
+        }
+
+        super.registerRoute(route, options);
+    }
+
+    getMswState() {
+        const plugin = getMswPlugin(this);
+
+        return plugin.mswState;
+    }
+
     registerRequestHandlers(handlers: RequestHandler[], options: RegisterRequestHandlersOptions = {}) {
         const logger = this._getLogger(options);
-        const mswPlugin = this.getPlugin(MswPluginName) as MswPlugin;
-
-        if (!mswPlugin) {
-            throw new Error("[squide] Cannot register the provided MSW request handlers because the runtime hasn't been initialized with MSW. Did you instanciate the FireflyRuntime with the \"useMsw\" option?");
-        }
+        const plugin = getMswPlugin(this);
 
-        if (getAreModulesRegistered()) {
+        if (this.moduleManager.getAreModulesRegistered()) {
             throw new Error("[squide] Cannot register an MSW request handlers once the modules are registered. Are you trying to register an MSW request handler in a deferred registration function? Only navigation items can be registered in a deferred registration function.");
         }
 
-        mswPlugin.registerRequestHandlers(handlers, {
+        plugin.registerRequestHandlers(handlers, {
             logger
         });
     }
 
     // Must define a return type otherwise we get an "error TS2742: The inferred type of 'requestHandlers' cannot be named" error.
     get requestHandlers(): RequestHandler[] {
-        const mswPlugin = this.getPlugin(MswPluginName) as MswPlugin;
+        const plugin = getMswPlugin(this);
 
-        if (!mswPlugin) {
-            throw new Error("[squide] Cannot retrieve MSW request handlers because the runtime hasn't been initialized with MSW. Did you instanciate the FireflyRuntime with the \"useMsw\" option?");
-        }
+        return plugin.requestHandlers;
+    }
 
-        return mswPlugin.requestHandlers;
+    get isMswEnabled() {
+        return this._plugins.some(x => x.name === MswPluginName);
     }
 
-    registerRoute(route: Route, options: RegisterRouteOptions = {}) {
-        if (getAreModulesRegistered()) {
-            throw new Error("[squide] Cannot register a route once the modules are registered. Are you trying to register a route in a deferred registration function? Only navigation items can be registered in a deferred registration function.");
-        }
+    getEnvironmentVariable(key: EnvironmentVariableKey) {
+        const plugin = getEnvironmentVariablesPlugin(this);
 
-        super.registerRoute(route, options);
+        return plugin.getVariable(key);
     }
 
-    get appRouterStore() {
-        return this._appRouterStore;
+    getEnvironmentVariables() {
+        const plugin = getEnvironmentVariablesPlugin(this);
+
+        return plugin.getVariables();
     }
 
-    get isMswEnabled() {
-        return this._useMsw;
+    registerEnvironmentVariable(key: EnvironmentVariableKey, value: EnvironmentVariableValue) {
+        const plugin = getEnvironmentVariablesPlugin(this);
+
+        return plugin.registerVariable(key, value);
+    }
+
+    registerEnvironmentVariables(variables: Partial<EnvironmentVariables>) {
+        const plugin = getEnvironmentVariablesPlugin(this);
+
+        return plugin.registerVariables(variables);
+    }
+
+    get appRouterStore() {
+        return this._appRouterStore;
     }
 
     get honeycombInstrumentationClient() {
         return this._honeycombInstrumentationClient;
     }
 
-    startScope(logger: Logger): FireflyRuntime {
-        return (new FireflyRuntimeScope(this, logger) as unknown) as FireflyRuntime;
+    startScope(logger: Logger): TRuntime {
+        return (new FireflyRuntimeScope(this, logger) as unknown) as TRuntime;
     }
 }
 
 export class FireflyRuntimeScope<TRuntime extends FireflyRuntime = FireflyRuntime> extends ReactRouterRuntimeScope<TRuntime> implements IFireflyRuntime {
+    getMswState() {
+        return this._runtime.getMswState();
+    }
+
     registerRequestHandlers(handlers: RequestHandler[], options: RegisterRequestHandlersOptions = {}) {
         this._runtime.registerRequestHandlers(handlers, {
             ...options,
@@ -112,19 +129,36 @@ export class FireflyRuntimeScope<TRuntime extends FireflyRuntime = FireflyRuntim
         });
     }
 
+    // Must define a return type otherwise we get an "error TS2742: The inferred type of 'requestHandlers' cannot be named" error.
     get requestHandlers(): RequestHandler[] {
         return this._runtime.requestHandlers;
     }
 
-    get appRouterStore() {
-        return this._runtime.appRouterStore;
-    }
-
     get isMswEnabled() {
         return this._runtime.isMswEnabled;
     }
 
-    get honeycombInstrumentationClient() {
-        return this._runtime.honeycombInstrumentationClient;
+    getEnvironmentVariables() {
+        return this._runtime.getEnvironmentVariables();
+    }
+
+    getEnvironmentVariable(key: EnvironmentVariableKey) {
+        return this._runtime.getEnvironmentVariable(key);
+    }
+
+    registerEnvironmentVariable(key: EnvironmentVariableKey, value: EnvironmentVariableValue) {
+        this._runtime.registerEnvironmentVariable(key, value);
+    }
+
+    registerEnvironmentVariables(variables: Partial<EnvironmentVariables>) {
+        this._runtime.registerEnvironmentVariables(variables);
+    }
+
+    get appRouterStore(): AppRouterStore {
+        throw new Error("[squide] Cannot retrieve the app router store from a runtime scope instance.");
+    }
+
+    get honeycombInstrumentationClient(): HoneycombInstrumentationPartialClient {
+        throw new Error("[squide] Cannot retrieve the Honeycomb instrumentation client from a runtime scope instance.");
     }
 }

package/src/honeycomb/registerHoneycombInstrumentation.ts

@@ -20,43 +20,27 @@ import {
     type LocalModulesRegistrationStartedEventPayload,
     type ModuleRegistrationError
 } from "@squide/core";
-import {
-    DeferredRegistrationsUpdateCompletedEvent,
-    DeferredRegistrationsUpdateStartedEvent,
-    RemoteModuleDeferredRegistrationFailedEvent,
-    RemoteModuleDeferredRegistrationUpdateFailedEvent,
-    type RemoteModuleRegistrationError,
-    RemoteModuleRegistrationFailedEvent,
-    RemoteModulesDeferredRegistrationCompletedEvent,
-    type RemoteModulesDeferredRegistrationCompletedEventPayload,
-    RemoteModulesDeferredRegistrationStartedEvent,
-    type RemoteModulesDeferredRegistrationStartedEventPayload,
-    RemoteModulesDeferredRegistrationsUpdateCompletedEvent,
-    type RemoteModulesDeferredRegistrationsUpdateCompletedEventPayload,
-    RemoteModulesDeferredRegistrationsUpdateStartedEvent,
-    type RemoteModulesDeferredRegistrationsUpdateStartedEventPayload,
-    RemoteModulesRegistrationCompletedEvent,
-    type RemoteModulesRegistrationCompletedEventPayload,
-    RemoteModulesRegistrationStartedEvent,
-    type RemoteModulesRegistrationStartedEventPayload
-} from "@squide/module-federation";
 import { ApplicationBoostrappedEvent, type AppRouterWaitState, ModulesReadyEvent, ModulesRegisteredEvent, MswReadyEvent, ProtectedDataReadyEvent, PublicDataReadyEvent } from "../AppRouterReducer.ts";
+import { FireflyPlugin } from "../FireflyPlugin.ts";
 import type { FireflyRuntime } from "../FireflyRuntime.tsx";
 import { ApplicationBootstrappingStartedEvent } from "../initializeFirefly.ts";
 import { ProtectedDataFetchFailedEvent, ProtectedDataFetchStartedEvent } from "../useProtectedDataQueries.ts";
 import { PublicDataFetchFailedEvent, PublicDataFetchStartedEvent } from "../usePublicDataQueries.ts";
+import { DeferredRegistrationsUpdateCompletedEvent, DeferredRegistrationsUpdateStartedEvent } from "../useUpdateDeferredRegistrations.ts";
 import { type ActiveSpan, createOverrideFetchRequestSpanWithActiveSpanContext, registerActiveSpanStack } from "./activeSpan.ts";
 import { getTracer } from "./tracer.ts";
 import { endActiveSpan, startActiveChildSpan, startChildSpan, startSpan, traceError } from "./utils.ts";
 
 // TIPS:
-// To query those traces in Honeycomb, use the following query filter: "root.name = squide-bootstrapping".
+// To query those traces in Honeycomb, use the following query filter:
+// "root.name = squide-bootstrapping" and
+// "root.name = squide-deferred-registrations-update".
 
-interface AddProtectedListenerOptions extends AddListenerOptions {
+export interface AddProtectedListenerOptions extends AddListenerOptions {
     onError?: (error: unknown) => void;
 }
 
-function addProtectedListener(runtime: FireflyRuntime, eventName: EventName, callback: EventCallbackFunction, options?: AddProtectedListenerOptions) {
+export function addProtectedListener(runtime: FireflyRuntime, eventName: EventName, callback: EventCallbackFunction, options?: AddProtectedListenerOptions) {
     const protectedCallback = (...args: unknown[]) => {
         try {
             callback(...args);
@@ -71,6 +55,9 @@ function addProtectedListener(runtime: FireflyRuntime, eventName: EventName, cal
     runtime.eventBus.addListener(eventName, protectedCallback, options);
 }
 
+export type GetSpanFunction = () => Span;
+export type HoneycombTrackingUnmanagedErrorHandler = (error: unknown) => void;
+
 type DataFetchState = "none" | "fetching-data" | "public-data-ready" | "protected-data-ready" | "data-ready" | "data-fetch-failed";
 
 export function reduceDataFetchEvents(
@@ -172,12 +159,11 @@ function registerTrackingListeners(runtime: FireflyRuntime) {
     let bootstrappingSpanHasEnded: boolean = false;
     let localModuleRegistrationSpan: Span;
     let localModuleDeferredRegistrationSpan: Span;
-    let remoteModuleRegistrationSpan: Span;
-    let remoteModuleDeferredRegistrationSpan: Span;
     let dataFetchSpan: ActiveSpan;
     let deferredRegistrationsUpdateSpan: Span;
     let localModuleDeferredRegistrationsUpdateSpan: ActiveSpan;
-    let remoteModuleDeferredRegistrationsUpdateSpan: ActiveSpan;
+
+    const pluginsUnmanagedErrorHandlers: HoneycombTrackingUnmanagedErrorHandler[] = [];
 
     const handleUnmanagedError = (error: unknown) => {
         if (bootstrappingSpan && !bootstrappingSpanHasEnded) {
@@ -195,14 +181,6 @@ function registerTrackingListeners(runtime: FireflyRuntime) {
             localModuleDeferredRegistrationSpan.end();
         }
 
-        if (remoteModuleRegistrationSpan) {
-            remoteModuleRegistrationSpan.end();
-        }
-
-        if (remoteModuleDeferredRegistrationSpan) {
-            remoteModuleDeferredRegistrationSpan.end();
-        }
-
         if (dataFetchSpan) {
             dataFetchSpan.instance.end();
         }
@@ -215,9 +193,9 @@ function registerTrackingListeners(runtime: FireflyRuntime) {
             localModuleDeferredRegistrationsUpdateSpan.instance.end();
         }
 
-        if (remoteModuleDeferredRegistrationsUpdateSpan) {
-            remoteModuleDeferredRegistrationsUpdateSpan.instance.end();
-        }
+        pluginsUnmanagedErrorHandlers.forEach(x => {
+            x(error);
+        });
     };
 
     addProtectedListener(runtime, ApplicationBootstrappingStartedEvent, () => {
@@ -332,92 +310,6 @@ function registerTrackingListeners(runtime: FireflyRuntime) {
         onError: handleUnmanagedError
     });
 
-    addProtectedListener(runtime, RemoteModulesRegistrationStartedEvent, (payload: unknown) => {
-        const attributes = {
-            "app.squide.remote_count": (payload as RemoteModulesRegistrationStartedEventPayload).remoteCount
-        };
-
-        if (bootstrappingSpan) {
-            bootstrappingSpan.addEvent("remote-module-registration-started", attributes);
-        }
-
-        remoteModuleRegistrationSpan = startChildSpan(bootstrappingSpan, (options, context) => {
-            return getTracer().startSpan("remote-module-registration", { ...options, attributes }, context);
-        });
-    }, {
-        once: true,
-        onError: handleUnmanagedError
-    });
-
-    addProtectedListener(runtime, RemoteModulesRegistrationCompletedEvent, (payload: unknown) => {
-        if (bootstrappingSpan) {
-            bootstrappingSpan.addEvent("remote-module-registration-completed", {
-                "app.squide.remote_count": (payload as RemoteModulesRegistrationCompletedEventPayload).remoteCount
-            });
-        }
-
-        if (remoteModuleRegistrationSpan) {
-            remoteModuleRegistrationSpan.end();
-        }
-    }, {
-        once: true,
-        onError: handleUnmanagedError
-    });
-
-    // Can occur multiple times.
-    addProtectedListener(runtime, RemoteModuleRegistrationFailedEvent, (payload: unknown) => {
-        const registrationError = payload as RemoteModuleRegistrationError;
-
-        if (remoteModuleRegistrationSpan) {
-            traceError(remoteModuleRegistrationSpan, registrationError);
-        }
-    }, {
-        onError: handleUnmanagedError
-    });
-
-    addProtectedListener(runtime, RemoteModulesDeferredRegistrationStartedEvent, (payload: unknown) => {
-        const attributes = {
-            "app.squide.registration_count": (payload as RemoteModulesDeferredRegistrationStartedEventPayload).registrationCount
-        };
-
-        if (bootstrappingSpan) {
-            bootstrappingSpan.addEvent("remote-module-deferred-registration-started", attributes);
-        }
-
-        remoteModuleDeferredRegistrationSpan = startChildSpan(bootstrappingSpan, (options, context) => {
-            return getTracer().startSpan("remote-module-deferred-registration", { ...options, attributes }, context);
-        });
-    }, {
-        once: true,
-        onError: handleUnmanagedError
-    });
-
-    addProtectedListener(runtime, RemoteModulesDeferredRegistrationCompletedEvent, (payload: unknown) => {
-        if (bootstrappingSpan) {
-            bootstrappingSpan.addEvent("remote-module-deferred-registration-completed", {
-                "app.squide.registration_count": (payload as RemoteModulesDeferredRegistrationCompletedEventPayload).registrationCount
-            });
-        }
-
-        if (remoteModuleDeferredRegistrationSpan) {
-            remoteModuleDeferredRegistrationSpan.end();
-        }
-    }, {
-        once: true,
-        onError: handleUnmanagedError
-    });
-
-    // Can occur multiple times.
-    addProtectedListener(runtime, RemoteModuleDeferredRegistrationFailedEvent, (payload: unknown) => {
-        const registrationError = payload as RemoteModuleRegistrationError;
-
-        if (remoteModuleDeferredRegistrationSpan) {
-            traceError(remoteModuleDeferredRegistrationSpan, registrationError);
-        }
-    }, {
-        onError: handleUnmanagedError
-    });
-
     const handleFetchDataStarted = () => {
         dataFetchSpan = startActiveChildSpan(bootstrappingSpan, (options, context) => {
             const name = "data-fetch";
@@ -576,57 +468,26 @@ function registerTrackingListeners(runtime: FireflyRuntime) {
         onError: handleUnmanagedError
     });
 
-    // Can occur multiple times.
-    addProtectedListener(runtime, RemoteModulesDeferredRegistrationsUpdateStartedEvent, (payload: unknown) => {
-        const attributes = {
-            "app.squide.registration_count": (payload as RemoteModulesDeferredRegistrationsUpdateStartedEventPayload).registrationCount
-        };
-
-        if (deferredRegistrationsUpdateSpan) {
-            deferredRegistrationsUpdateSpan.addEvent("remote-module-deferred-registrations-update-started", attributes);
-        }
-
-        remoteModuleDeferredRegistrationsUpdateSpan = startActiveChildSpan(deferredRegistrationsUpdateSpan, (options, context) => {
-            const name = "remote-module-deferred-registrations-update";
-
-            const span = getTracer().startSpan(name, {
-                attributes,
-                ...options
-            }, context);
-
-            return {
-                name,
-                span
-            };
-        });
-    }, {
-        onError: handleUnmanagedError
-    });
+    const getBootstrappingSpan: GetSpanFunction = () => bootstrappingSpan;
+    const getDeferredRegistrationsUpdateSpan: GetSpanFunction = () => deferredRegistrationsUpdateSpan;
 
-    // Can occur multiple times.
-    addProtectedListener(runtime, RemoteModulesDeferredRegistrationsUpdateCompletedEvent, (payload: unknown) => {
-        if (deferredRegistrationsUpdateSpan) {
-            deferredRegistrationsUpdateSpan.addEvent("remote-module-deferred-registrations-update-completed", {
-                "app.squide.registration_count": (payload as RemoteModulesDeferredRegistrationsUpdateCompletedEventPayload).registrationCount
-            });
-        }
+    const handlePluginUnmanagedError: HoneycombTrackingUnmanagedErrorHandler = (error: unknown) => {
+        handleUnmanagedError(error);
+    };
 
-        if (remoteModuleDeferredRegistrationsUpdateSpan) {
-            endActiveSpan(remoteModuleDeferredRegistrationsUpdateSpan);
-        }
-    }, {
-        onError: handleUnmanagedError
-    });
+    // Register plugins specific handlers for Honeycomb telemetry.
+    runtime.plugins.forEach(x => {
+        const plugin = x as FireflyPlugin;
 
-    // Can occur multiple times.
-    addProtectedListener(runtime, RemoteModuleDeferredRegistrationUpdateFailedEvent, (payload: unknown) => {
-        const registrationError = payload as RemoteModuleRegistrationError;
+        if (plugin.registerHoneycombTrackingListeners) {
+            const unmanagedErrorHandler = plugin.registerHoneycombTrackingListeners(
+                getBootstrappingSpan,
+                getDeferredRegistrationsUpdateSpan,
+                handlePluginUnmanagedError
+            );
 
-        if (remoteModuleDeferredRegistrationsUpdateSpan) {
-            traceError(remoteModuleDeferredRegistrationsUpdateSpan.instance, registrationError);
+            pluginsUnmanagedErrorHandlers.push(unmanagedErrorHandler);
         }
-    }, {
-        onError: handleUnmanagedError
     });
 }
 

package/src/index.ts

@@ -1,14 +1,41 @@
 export * from "@squide/core";
-export * from "@squide/module-federation";
-export * from "@squide/msw";
+export {
+    EnvironmentVariablesPlugin,
+    useEnvironmentVariable,
+    useEnvironmentVariables,
+    type EnvironmentVariableKey,
+    type EnvironmentVariables,
+    type EnvironmentVariablesPluginOptions,
+    type EnvironmentVariableValue
+} from "@squide/env-vars";
+export {
+    MswPlugin,
+    MswState,
+    type MswPluginOptions,
+    type MswPluginRegisterRequestHandlersOptions,
+    type MswReadyListener,
+    type MswStateOptions
+} from "@squide/msw";
 export * from "@squide/react-router";
 
+export type { FireflyPlugin } from "./FireflyPlugin.ts";
 export * from "./FireflyProvider.tsx";
 export * from "./FireflyRuntime.tsx";
 
 export * from "./AppRouter.tsx";
-export * from "./AppRouterContext.ts";
-export * from "./AppRouterReducer.ts";
+export {
+    ActiveRouteIsProtectedEvent,
+    ActiveRouteIsPublicEvent,
+    ApplicationBoostrappedEvent,
+    DeferredRegistrationsUpdatedEvent,
+    ModulesReadyEvent,
+    ModulesRegisteredEvent,
+    MswReadyEvent,
+    ProtectedDataReadyEvent,
+    ProtectedDataUpdatedEvent,
+    PublicDataReadyEvent,
+    PublicDataUpdatedEvent
+} from "./AppRouterReducer.ts";
 
 export * from "./AppRouterStore.ts";
 export * from "./GlobalDataQueriesError.ts";