@squide/firefly 12.0.4 → 13.0.1

package/dist/initializeFirefly.js.map

@@ -1 +1 @@
-{"version":3,"file":"initializeFirefly.js","sources":["webpack://@squide/firefly/./src/initializeFirefly.ts"],"sourcesContent":["import { isFunction, registerLocalModules, type ModuleRegisterFunction, type RegisterModulesOptions } from \"@squide/core\";\nimport { registerRemoteModules, type RemoteDefinition } from \"@squide/module-federation\";\nimport { setMswAsReady } from \"@squide/msw\";\nimport { FireflyRuntime, type FireflyRuntimeOptions } from \"./FireflyRuntime.tsx\";\n\nexport const ApplicationBootstrappingStartedEvent = \"squide-app-bootstrapping-started\";\n\nexport type OnInitializationErrorFunction = (error: unknown) => void;\n\nexport type StartMswFunction<TRuntime = FireflyRuntime> = (runtime: TRuntime) => Promise<void>;\n\nexport interface InitializeFireflyOptions<TRuntime extends FireflyRuntime, TContext = unknown, TData = unknown> extends RegisterModulesOptions<TContext>, FireflyRuntimeOptions {\n    localModules?: ModuleRegisterFunction<TRuntime, TContext, TData>[];\n    remotes?: RemoteDefinition[];\n    startMsw?: StartMswFunction<FireflyRuntime>;\n    onError?: OnInitializationErrorFunction;\n}\n\nfunction propagateRegistrationErrors(results: PromiseSettledResult<unknown[]>, onError: OnInitializationErrorFunction) {\n    if (results) {\n        if (results.status === \"fulfilled\") {\n            results.value.forEach(x => {\n                onError(x);\n            });\n        }\n    }\n}\n\nexport function bootstrap<TRuntime extends FireflyRuntime = FireflyRuntime, TContext = unknown, TData = unknown>(runtime: TRuntime, options: InitializeFireflyOptions<TRuntime, TContext, TData> = {}) {\n    const {\n        localModules = [],\n        remotes = [],\n        startMsw,\n        onError,\n        context\n    } = options;\n\n    runtime.eventBus.dispatch(ApplicationBootstrappingStartedEvent);\n\n    Promise.allSettled([\n        registerLocalModules<TRuntime, TContext, TData>(localModules, runtime, { context }),\n        registerRemoteModules(remotes, runtime, { context })\n    ]).then(results => {\n        if (runtime.isMswEnabled) {\n            if (!isFunction(startMsw)) {\n                throw new Error(\"[squide] When MSW is enabled, the \\\"startMsw\\\" function must be provided.\");\n            }\n\n            startMsw(runtime)\n                .then(() => {\n                    setMswAsReady();\n                })\n                .catch((error: unknown) => {\n                    runtime.logger.debug(\"[squide] An error occured while starting MSW.\", error);\n                });\n        }\n\n        if (onError) {\n            propagateRegistrationErrors(results[0], onError);\n            propagateRegistrationErrors(results[1], onError);\n        }\n    });\n}\n\nlet hasExecuted = false;\n\nexport function initializeFirefly<TContext = unknown, TData = unknown>(options: InitializeFireflyOptions<FireflyRuntime, TContext, TData> = {}) {\n    const {\n        mode,\n        useMsw,\n        loggers,\n        plugins\n    } = options;\n\n    if (hasExecuted) {\n        throw new Error(\"[squide] A squide application can only be initialized once. Did you call the \\\"initializeSquide\\\" function twice?\");\n    }\n\n    hasExecuted = true;\n\n    const runtime = new FireflyRuntime({\n        mode,\n        useMsw,\n        loggers,\n        plugins\n    });\n\n    bootstrap(runtime, options);\n\n    return runtime;\n}\n\nexport function __resetHasExecuteGuard() {\n    hasExecuted = false;\n}\n"],"names":["isFunction","registerLocalModules","registerRemoteModules","setMswAsReady","FireflyRuntime","ApplicationBootstrappingStartedEvent","propagateRegistrationErrors","results","onError","x","bootstrap","runtime","options","localModules","remotes","startMsw","context","Promise","Error","error","hasExecuted","initializeFirefly","mode","useMsw","loggers","plugins","__resetHasExecuteGuard"],"mappings":";;;;;;;;;;;;;;AAA0H;AACjC;AAC7C;AACsC;AAE3E,MAAMK,uCAAuC,mCAAmC;AAavF,SAASC,4BAA4BC,OAAwC,EAAEC,OAAsC;IACjH,IAAID,SAAS;QACT,IAAIA,QAAQ,MAAM,KAAK,aAAa;YAChCA,QAAQ,KAAK,CAAC,OAAO,CAACE,CAAAA;gBAClBD,QAAQC;YACZ;QACJ;IACJ;AACJ;AAEO,SAASC,UAAiGC,OAAiB,EAAEC,UAA+D,CAAC,CAAC;IACjM,MAAM,EACFC,eAAe,EAAE,EACjBC,UAAU,EAAE,EACZC,QAAQ,EACRP,OAAO,EACPQ,OAAO,EACV,GAAGJ;IAEJD,QAAQ,QAAQ,CAAC,QAAQ,CAACN;IAE1BY,QAAQ,UAAU,CAAC;QACfhB,0EAAoBA,CAA4BY,cAAcF,SAAS;YAAEK;QAAQ;QACjFd,wFAAqBA,CAACY,SAASH,SAAS;YAAEK;QAAQ;KACrD,EAAE,IAAI,CAACT,CAAAA;QACJ,IAAII,QAAQ,YAAY,EAAE;YACtB,IAAI,CAACX,gEAAUA,CAACe,WAAW;gBACvB,MAAM,IAAIG,MAAM;YACpB;YAEAH,SAASJ,SACJ,IAAI,CAAC;gBACFR,kEAAaA;YACjB,GACC,KAAK,CAAC,CAACgB;gBACJR,QAAQ,MAAM,CAAC,KAAK,CAAC,iDAAiDQ;YAC1E;QACR;QAEA,IAAIX,SAAS;YACTF,4BAA4BC,OAAO,CAAC,EAAE,EAAEC;YACxCF,4BAA4BC,OAAO,CAAC,EAAE,EAAEC;QAC5C;IACJ;AACJ;AAEA,IAAIY,cAAc;AAEX,SAASC,kBAAuDT,UAAqE,CAAC,CAAC;IAC1I,MAAM,EACFU,IAAI,EACJC,MAAM,EACNC,OAAO,EACPC,OAAO,EACV,GAAGb;IAEJ,IAAIQ,aAAa;QACb,MAAM,IAAIF,MAAM;IACpB;IAEAE,cAAc;IAEd,MAAMT,UAAU,IAAIP,sEAAcA,CAAC;QAC/BkB;QACAC;QACAC;QACAC;IACJ;IAEAf,UAAUC,SAASC;IAEnB,OAAOD;AACX;AAEO,SAASe;IACZN,cAAc;AAClB"}
+{"version":3,"file":"initializeFirefly.js","sources":["webpack://@squide/firefly/./src/initializeFirefly.ts"],"sourcesContent":["import { isFunction, registerLocalModules, type ModuleRegisterFunction, type RegisterModulesOptions } from \"@squide/core\";\nimport { registerRemoteModules, type RemoteDefinition } from \"@squide/module-federation\";\nimport { setMswAsReady } from \"@squide/msw\";\nimport { FireflyRuntime, type FireflyRuntimeOptions } from \"./FireflyRuntime.tsx\";\nimport { initializeHoneycomb } from \"./honeycomb/initializeHoneycomb.ts\";\n\nexport const ApplicationBootstrappingStartedEvent = \"squide-app-bootstrapping-started\";\n\nexport type OnInitializationErrorFunction = (error: unknown) => void;\n\nexport type StartMswFunction<TRuntime = FireflyRuntime> = (runtime: TRuntime) => Promise<void>;\n\nexport interface InitializeFireflyOptions<TRuntime extends FireflyRuntime, TContext = unknown, TData = unknown> extends RegisterModulesOptions<TContext>, FireflyRuntimeOptions {\n    localModules?: ModuleRegisterFunction<TRuntime, TContext, TData>[];\n    remotes?: RemoteDefinition[];\n    startMsw?: StartMswFunction<FireflyRuntime>;\n    onError?: OnInitializationErrorFunction;\n}\n\nfunction propagateRegistrationErrors(results: PromiseSettledResult<unknown[]>, onError: OnInitializationErrorFunction) {\n    if (results) {\n        if (results.status === \"fulfilled\") {\n            results.value.forEach(x => {\n                onError(x);\n            });\n        }\n    }\n}\n\nexport function bootstrap<TRuntime extends FireflyRuntime = FireflyRuntime, TContext = unknown, TData = unknown>(runtime: TRuntime, options: InitializeFireflyOptions<TRuntime, TContext, TData> = {}) {\n    const {\n        localModules = [],\n        remotes = [],\n        startMsw,\n        onError,\n        context\n    } = options;\n\n    runtime.eventBus.dispatch(ApplicationBootstrappingStartedEvent);\n\n    Promise.allSettled([\n        registerLocalModules<TRuntime, TContext, TData>(localModules, runtime, { context }),\n        registerRemoteModules(remotes, runtime, { context })\n    ]).then(results => {\n        if (runtime.isMswEnabled) {\n            if (!isFunction(startMsw)) {\n                throw new Error(\"[squide] When MSW is enabled, the \\\"startMsw\\\" function must be provided.\");\n            }\n\n            startMsw(runtime)\n                .then(() => {\n                    setMswAsReady();\n                })\n                .catch((error: unknown) => {\n                    runtime.logger.debug(\"[squide] An error occured while starting MSW.\", error);\n                });\n        }\n\n        if (onError) {\n            propagateRegistrationErrors(results[0], onError);\n            propagateRegistrationErrors(results[1], onError);\n        }\n    });\n}\n\nlet hasExecuted = false;\n\nexport function initializeFirefly<TContext = unknown, TData = unknown>(options: InitializeFireflyOptions<FireflyRuntime, TContext, TData> = {}) {\n    const {\n        mode,\n        useMsw,\n        loggers,\n        plugins,\n        onError\n    } = options;\n\n    if (hasExecuted) {\n        throw new Error(\"[squide] A squide application can only be initialized once. Did you call the \\\"initializeSquide\\\" function twice?\");\n    }\n\n    hasExecuted = true;\n\n    const runtime = new FireflyRuntime({\n        mode,\n        useMsw,\n        loggers,\n        plugins\n    });\n\n    initializeHoneycomb(runtime)\n        .catch((error: unknown) => {\n            if (onError) {\n                onError(error);\n            }\n        })\n        .finally(() => {\n            bootstrap(runtime, options);\n        });\n\n    return runtime;\n}\n\nexport function __resetHasExecuteGuard() {\n    hasExecuted = false;\n}\n"],"names":["isFunction","registerLocalModules","registerRemoteModules","setMswAsReady","FireflyRuntime","initializeHoneycomb","ApplicationBootstrappingStartedEvent","propagateRegistrationErrors","results","onError","x","bootstrap","runtime","options","localModules","remotes","startMsw","context","Promise","Error","error","hasExecuted","initializeFirefly","mode","useMsw","loggers","plugins","__resetHasExecuteGuard"],"mappings":";;;;;;;;;;;;;;;;;AAA0H;AACjC;AAC7C;AACsC;AACT;AAElE,MAAMM,uCAAuC,mCAAmC;AAavF,SAASC,4BAA4BC,OAAwC,EAAEC,OAAsC;IACjH,IAAID,SAAS;QACT,IAAIA,QAAQ,MAAM,KAAK,aAAa;YAChCA,QAAQ,KAAK,CAAC,OAAO,CAACE,CAAAA;gBAClBD,QAAQC;YACZ;QACJ;IACJ;AACJ;AAEO,SAASC,UAAiGC,OAAiB,EAAEC,UAA+D,CAAC,CAAC;IACjM,MAAM,EACFC,eAAe,EAAE,EACjBC,UAAU,EAAE,EACZC,QAAQ,EACRP,OAAO,EACPQ,OAAO,EACV,GAAGJ;IAEJD,QAAQ,QAAQ,CAAC,QAAQ,CAACN;IAE1BY,QAAQ,UAAU,CAAC;QACfjB,0EAAoBA,CAA4Ba,cAAcF,SAAS;YAAEK;QAAQ;QACjFf,wFAAqBA,CAACa,SAASH,SAAS;YAAEK;QAAQ;KACrD,EAAE,IAAI,CAACT,CAAAA;QACJ,IAAII,QAAQ,YAAY,EAAE;YACtB,IAAI,CAACZ,gEAAUA,CAACgB,WAAW;gBACvB,MAAM,IAAIG,MAAM;YACpB;YAEAH,SAASJ,SACJ,IAAI,CAAC;gBACFT,kEAAaA;YACjB,GACC,KAAK,CAAC,CAACiB;gBACJR,QAAQ,MAAM,CAAC,KAAK,CAAC,iDAAiDQ;YAC1E;QACR;QAEA,IAAIX,SAAS;YACTF,4BAA4BC,OAAO,CAAC,EAAE,EAAEC;YACxCF,4BAA4BC,OAAO,CAAC,EAAE,EAAEC;QAC5C;IACJ;AACJ;AAEA,IAAIY,cAAc;AAEX,SAASC,kBAAuDT,UAAqE,CAAC,CAAC;IAC1I,MAAM,EACFU,IAAI,EACJC,MAAM,EACNC,OAAO,EACPC,OAAO,EACPjB,OAAO,EACV,GAAGI;IAEJ,IAAIQ,aAAa;QACb,MAAM,IAAIF,MAAM;IACpB;IAEAE,cAAc;IAEd,MAAMT,UAAU,IAAIR,sEAAcA,CAAC;QAC/BmB;QACAC;QACAC;QACAC;IACJ;IAEArB,8FAAmBA,CAACO,SACf,KAAK,CAAC,CAACQ;QACJ,IAAIX,SAAS;YACTA,QAAQW;QACZ;IACJ,GACC,OAAO,CAAC;QACLT,UAAUC,SAASC;IACvB;IAEJ,OAAOD;AACX;AAEO,SAASe;IACZN,cAAc;AAClB"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@squide/firefly",
   "author": "Workleap",
-  "version": "12.0.4",
+  "version": "13.0.1",
   "description": "Helpers to facilitate the creation of an application with the Squide firefly technology stack.",
   "license": "Apache-2.0",
   "repository": {
@@ -28,6 +28,7 @@
     "README.md"
   ],
   "peerDependencies": {
+    "@opentelemetry/api": "^1.9.0",
     "@tanstack/react-query": "^5.77.2",
     "msw": "^2.8.4",
     "react": "^18.0.0 || ^19.0.0",
@@ -35,6 +36,7 @@
     "react-router": "^7.6.1"
   },
   "dependencies": {
+    "uuid": "^11.1.0",
     "@squide/core": "5.4.8",
     "@squide/module-federation": "6.2.8",
     "@squide/msw": "3.2.8",

package/src/honeycomb/activeSpan.ts

@@ -0,0 +1,131 @@
+import type { Span } from "@opentelemetry/api";
+import { isPlainObject, type RuntimeLogger } from "@squide/core";
+import { v4 as uuidv4 } from "uuid";
+import { createTraceContextId } from "./createTraceContextId.ts";
+
+export type ActiveSpanId = string;
+
+export interface ActiveSpan {
+    id: ActiveSpanId;
+    name: string;
+    instance: Span;
+}
+
+// Using a stack because we want a Last In First Out implementation for this.
+// https://github.com/open-telemetry/opentelemetry-js/issues/5084
+// https://github.com/open-telemetry/opentelemetry-js/issues/3558#issuecomment-1760680244
+class ActiveSpanStack {
+    readonly #stack: ActiveSpan[] = [];
+
+    push(span: ActiveSpan) {
+        this.#stack.push(span);
+    }
+
+    pop(span: ActiveSpan) {
+        const head = this.#stack.pop();
+
+        if (!head) {
+            throw new Error("[squide] Unexpected pop, the active Honeycomb span stack is empty.");
+        }
+
+        if (head.id !== span.id) {
+            throw new Error(`[squide] The active Honeycomb span is not the expected span. Expected to pop span with name and id "${span.name} / ${span.id}" but found "${head.name} / ${head.id}". Did you forget to end an active span?`);
+        }
+
+        return head;
+    }
+
+    peek() {
+        if (this.#stack.length === 0) {
+            return undefined;
+        }
+
+        return this.#stack[this.#stack.length - 1];
+    }
+}
+
+const GlobalActiveSpanStackVariableName = "__SQUIDE_HONEYCOMB_ACTIVE_SPAN_STACK__";
+
+export function registerActiveSpanStack() {
+    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+    // @ts-ignore
+    if (globalThis[GlobalActiveSpanStackVariableName]) {
+        throw new Error(`[squide] An ActiveSpanStack instance has already been registered to globalThis.${GlobalActiveSpanStackVariableName}. Did you register the Honeycomb instrumentation twice?`);
+    }
+
+    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+    // @ts-ignore
+    globalThis[GlobalActiveSpanStackVariableName] = new ActiveSpanStack();
+}
+
+function getActiveSpanStack() {
+    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+    // @ts-ignore
+    return globalThis[GlobalActiveSpanStackVariableName] as ActiveSpanStack;
+}
+
+function getActiveSpan() {
+    const stack = getActiveSpanStack();
+
+    if (stack) {
+        return stack.peek();
+    }
+}
+
+export function setActiveSpan(name: string, span: Span) {
+    const activeSpan: ActiveSpan = {
+        id: uuidv4(),
+        name: name,
+        instance: span
+    };
+
+    const stack = getActiveSpanStack();
+
+    if (stack) {
+        stack.push(activeSpan);
+    }
+
+    return activeSpan;
+}
+
+export function popActiveSpan(span: ActiveSpan) {
+    const stack = getActiveSpanStack();
+
+    if (stack) {
+        stack.pop(span);
+    }
+}
+
+export function createOverrideFetchRequestSpanWithActiveSpanContext(logger: RuntimeLogger) {
+    return (span: Span, request: Request | RequestInit) => {
+        const activeSpan = getActiveSpan();
+
+        if (activeSpan) {
+            const activeSpanContext = activeSpan.instance.spanContext();
+            const requestSpanContext = span.spanContext();
+
+            if (activeSpanContext) {
+                logger.debug(
+                    "[squide] Found a Honeycomb active context to apply to the following fetch request: \r\n",
+                    "Request span context: ", requestSpanContext, "\r\n",
+                    "Active span context: ", activeSpanContext, "\r\n",
+                    "Request: ", request, "\r\n"
+                );
+
+                span.setAttribute("trace.trace_id", activeSpanContext.traceId);
+                span.setAttribute("trace.parent_id", activeSpanContext.spanId);
+
+                const traceParent = createTraceContextId(activeSpanContext.traceId, requestSpanContext.spanId, requestSpanContext.traceFlags);
+
+                if (request instanceof Request) {
+                    request.headers.set("traceparent", traceParent);
+                } else if (isPlainObject(request.headers)) {
+                    request.headers["traceparent"] = traceParent;
+                }
+
+                // Indicates to not propagate the requests to the subsequent hooks.
+                return true;
+            }
+        }
+    };
+}

package/src/honeycomb/canRegisterHoneycombInstrumentation.ts

@@ -0,0 +1,5 @@
+export function canRegisterHoneycombInstrumentation() {
+    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+    // @ts-ignore
+    return globalThis.__WLP_HONEYCOMB_INSTRUMENTATION_IS_REGISTERED__ === true;
+}

package/src/honeycomb/createTraceContextId.ts

@@ -0,0 +1,12 @@
+// Creates the trace context id based on the following opentelemetry-js implementation: https://github.com/open-telemetry/opentelemetry-js/blob/main/packages/opentelemetry-core/src/trace/W3CTraceContextPropagator.ts
+
+const VERSION = "00";
+
+enum TraceFlags {
+    NONE = 0x0,
+    SAMPLED = 0x1 << 0
+}
+
+export function createTraceContextId(traceId: string, spanId: string, traceFlags: number) {
+    return `${VERSION}-${traceId}-${spanId}-0${Number(traceFlags || TraceFlags.NONE).toString(16)}`;
+}

package/src/honeycomb/initializeHoneycomb.ts

@@ -0,0 +1,22 @@
+import type { FireflyRuntime } from "../FireflyRuntime.tsx";
+import { canRegisterHoneycombInstrumentation } from "./canRegisterHoneycombInstrumentation.ts";
+
+export async function initializeHoneycomb(runtime: FireflyRuntime) {
+    if (canRegisterHoneycombInstrumentation()) {
+        try {
+            // Dynamically import the Honeycomb instrumentation to prevent loading all the Honeycomb libraries
+            // if Honeycomb instrumentation is not registered by the hosting application.
+            const mod = await import("./registerHoneycombInstrumentation.ts");
+
+            mod.registerHoneycombInstrumentation(runtime);
+        } catch (error: unknown) {
+            runtime.logger.error("[squide] Failed to register Honeycomb instrumentation. The \"./registerHoneycombInstrumentation.ts\" cannot be imported.");
+
+            throw error;
+        }
+    } else {
+        runtime.logger.debug("[squide] Cannot register Honeycomb instrumentation because the host application is not using the \"@workleap/honeycomb\" package.");
+    }
+}
+
+