@mfeflow/runtime 0.5.0 → 0.6.0

package/dist/beacon.d.ts

@@ -0,0 +1,45 @@
+import { type RegistrySources } from './registry.js';
+import { type RuntimeConfigValues } from './runtime-config.js';
+/** The registry server's endpoint for these index URLs, and the env they name. */
+export interface BeaconTarget {
+    url: string;
+    env: string;
+}
+export declare const CLIENT_ID_KEY = "mfeflow:client";
+/** The first index URL that is a registry server's `/v1/index/<env>`. A static host has no beacon. */
+export declare function beaconTarget(urls: readonly string[]): BeaconTarget | undefined;
+/** A stable id for this browser, so the server keeps giving it the same rollout side. Not tied to a person. */
+export declare function clientId(): string;
+/** The server index URLs get `?u=<client id>`; any other URL is returned as it came. */
+export declare function withClientId(url: string, id?: string): string;
+export type Send = (url: string, body: string) => boolean;
+export interface BeaconReporter {
+    load(remote: string, version: string): void;
+    error(remote: string, version: string): void;
+    /** Sends what has been counted since the last flush as one request. Nothing counted, nothing sent. */
+    flush(): void;
+    stop(): void;
+}
+/**
+ * Counts, per remote@version, whether this page loaded it and whether it failed, and sends the
+ * page's counts as one request: `{ env, u, entries }`. A page is one load and at most one error
+ * for a remote, so the error rate reads as "page views that hit an error". What was sent is
+ * remembered, so a flush on `visibilitychange` followed by more loads never reports the same load
+ * again. An error that comes after a clean report is sent once more.
+ */
+export declare function createBeaconReporter(target: BeaconTarget, send: Send, client?: string): BeaconReporter;
+/** Stops the running reporter so the next start is a fresh one. For tests. */
+export declare function resetRegistryBeaconForTests(): void;
+/**
+ * Starts the reporter when the runtime config has `registryBeacon: true` and one of the index URLs
+ * is a registry server's. Otherwise does nothing. Calling it again returns the reporter already
+ * running, so the Module Federation plugin is registered once.
+ */
+export declare function startRegistryBeacon(config: RuntimeConfigValues, urls: readonly string[], send?: Send): BeaconReporter | undefined;
+/**
+ * `registrySources()` for a shell that wants the beacon. With `registryBeacon: true` in the runtime
+ * config it adds this browser's id to the registry server's index URLs and starts the reporter;
+ * without it, the sources come back untouched. Import it on demand
+ * (`await import('@mfeflow/runtime/beacon')`) so a shell with the option off never downloads it.
+ */
+export declare function registrySourcesWithBeacon(waitMs?: number): Promise<RegistrySources>;

package/dist/beacon.js

@@ -0,0 +1,169 @@
+import { registerPlugins } from "@module-federation/enhanced/runtime";
+import { REMOTE_ERROR_EVENT, remoteVersion } from "./report.js";
+import { registrySources } from "./registry.js";
+import { RUNTIME_CONFIG_KEY } from "./runtime-config.js";
+const SERVER_INDEX = /\/v1\/index\/([a-z][a-z0-9-]*)$/;
+const PARSE_BASE = 'https://page.invalid';
+const MAX_ENTRIES = 20;
+const MAX_BYTES = 4096;
+const MAX_PENDING = 200;
+const CLIENT_ID_KEY = 'mfeflow:client';
+function beaconTarget(urls) {
+    for (const raw of urls){
+        if (!URL.canParse(raw, PARSE_BASE)) continue;
+        const url = new URL(raw, PARSE_BASE);
+        const env = SERVER_INDEX.exec(url.pathname)?.[1];
+        if (void 0 === env) continue;
+        const beacon = new URL(raw, "u" < typeof location ? PARSE_BASE : location.href);
+        beacon.pathname = beacon.pathname.replace(SERVER_INDEX, '/v1/beacon');
+        beacon.search = '';
+        beacon.hash = '';
+        return {
+            url: beacon.href,
+            env
+        };
+    }
+}
+const randomId = ()=>Array.from(crypto.getRandomValues(new Uint8Array(16)), (b)=>b.toString(16).padStart(2, '0')).join('');
+let memoryId;
+function clientId() {
+    try {
+        const stored = localStorage.getItem(CLIENT_ID_KEY);
+        if (null !== stored && /^[\w.:-]{1,128}$/.test(stored)) return stored;
+        const fresh = randomId();
+        localStorage.setItem(CLIENT_ID_KEY, fresh);
+        return fresh;
+    } catch  {
+        memoryId ??= randomId();
+        return memoryId;
+    }
+}
+function withClientId(url, id = clientId()) {
+    if (!URL.canParse(url, PARSE_BASE)) return url;
+    const parsed = new URL(url, PARSE_BASE);
+    if (!SERVER_INDEX.test(parsed.pathname)) return url;
+    const absolute = URL.canParse(url);
+    const target = absolute ? new URL(url) : parsed;
+    target.searchParams.set('u', id);
+    return absolute ? target.href : `${target.pathname}${target.search}${target.hash}`;
+}
+const byteLength = (text)=>new TextEncoder().encode(text).length;
+function createBeaconReporter(target, send, client = clientId()) {
+    const pending = new Map();
+    const sent = new Map();
+    const note = (remote, version, failed)=>{
+        const key = `${remote}@${version}`;
+        const before = sent.get(key);
+        if (void 0 !== before && (before || !failed)) return;
+        const known = pending.get(key);
+        if (void 0 !== known) known.failed ||= failed;
+        else if (pending.size < MAX_PENDING) pending.set(key, {
+            remote,
+            version,
+            failed
+        });
+    };
+    const flush = ()=>{
+        if (0 === pending.size) return;
+        const batch = [
+            ...pending.entries()
+        ];
+        pending.clear();
+        for (const [key, { failed }] of batch)sent.set(key, failed);
+        const head = JSON.stringify({
+            env: target.env,
+            u: client,
+            entries: []
+        });
+        let chunk = [];
+        let size = head.length;
+        const emit = ()=>{
+            if (chunk.length > 0) send(target.url, JSON.stringify({
+                env: target.env,
+                u: client,
+                entries: chunk
+            }));
+            chunk = [];
+            size = head.length;
+        };
+        for (const [, { remote, version, failed }] of batch){
+            const entry = {
+                remote,
+                version,
+                loads: 1,
+                errors: failed ? 1 : 0
+            };
+            const extra = byteLength(JSON.stringify(entry)) + 1;
+            if (chunk.length === MAX_ENTRIES || size + extra > MAX_BYTES) emit();
+            chunk.push(entry);
+            size += extra;
+        }
+        emit();
+    };
+    const onError = (event)=>{
+        const detail = event instanceof CustomEvent ? event.detail : void 0;
+        const mfe = 'object' == typeof detail && null !== detail ? Reflect.get(detail, 'mfe') : void 0;
+        const version = 'object' == typeof detail && null !== detail ? Reflect.get(detail, 'version') : void 0;
+        if ('string' == typeof mfe && 'string' == typeof version) note(mfe, version, true);
+    };
+    const onHide = ()=>{
+        if ("u" < typeof document || 'hidden' === document.visibilityState) flush();
+    };
+    window.addEventListener(REMOTE_ERROR_EVENT, onError);
+    window.addEventListener('pagehide', flush);
+    document.addEventListener('visibilitychange', onHide);
+    return {
+        load: (remote, version)=>note(remote, version, false),
+        error: (remote, version)=>note(remote, version, true),
+        flush,
+        stop () {
+            window.removeEventListener(REMOTE_ERROR_EVENT, onError);
+            window.removeEventListener('pagehide', flush);
+            document.removeEventListener('visibilitychange', onHide);
+            pending.clear();
+            sent.clear();
+        }
+    };
+}
+const sendWithBeacon = (url, body)=>"u" > typeof navigator && 'function' == typeof navigator.sendBeacon ? navigator.sendBeacon(url, body) : false;
+let active;
+function resetRegistryBeaconForTests() {
+    active?.stop();
+    active = void 0;
+}
+function startRegistryBeacon(config, urls, send = sendWithBeacon) {
+    if (true !== config.registryBeacon) return;
+    if (void 0 !== active) return active;
+    const target = beaconTarget(urls);
+    if (void 0 === target) return;
+    const reporter = createBeaconReporter(target, send);
+    active = reporter;
+    registerPlugins([
+        {
+            name: 'mfeflow-beacon',
+            onLoad (args) {
+                const remote = args.id.split('/')[0] ?? args.id;
+                const version = remoteVersion(remote);
+                if (void 0 !== version) reporter.load(remote, version);
+            }
+        }
+    ]);
+    return reporter;
+}
+const isConfig = (value)=>'object' == typeof value && null !== value && !Array.isArray(value);
+async function registrySourcesWithBeacon(waitMs) {
+    const sources = await registrySources(waitMs);
+    const config = Reflect.get(globalThis, RUNTIME_CONFIG_KEY);
+    if (!isConfig(config) || true !== config.registryBeacon) return sources;
+    try {
+        const urls = sources.urls.map((url)=>withClientId(url));
+        startRegistryBeacon(config, urls);
+        return {
+            ...sources,
+            urls
+        };
+    } catch  {
+        return sources;
+    }
+}
+export { CLIENT_ID_KEY, beaconTarget, clientId, createBeaconReporter, registrySourcesWithBeacon, resetRegistryBeaconForTests, startRegistryBeacon, withClientId };

package/dist/report.d.ts

@@ -8,6 +8,8 @@ export interface RemoteErrorReport {
     /** The registered version of the remote, when the registry gave one. */
     version?: string;
 }
+/** The version the registry gave this remote on this page, if any. */
+export declare const remoteVersion: (mfe: string) => string | undefined;
 /** Remembers each remote's version so its reports say `cart@1.2.3`. Replaces what was remembered before. */
 export declare function rememberRemoteVersions(remotes: readonly {
     name: string;

package/dist/report.js

@@ -7,6 +7,7 @@ function versionMap() {
     Reflect.set(globalThis, VERSIONS, created);
     return created;
 }
+const remoteVersion = (mfe)=>versionMap().get(mfe);
 function rememberRemoteVersions(remotes) {
     const versions = versionMap();
     versions.clear();
@@ -31,4 +32,4 @@ function reportRemoteError(mfe, where, error) {
     console.error(`[mfeflow] ${void 0 === version ? mfe : `${mfe}@${version}`} ${where}: ${report.message}`);
     return report;
 }
-export { REMOTE_ERROR_EVENT, rememberRemoteVersions, reportRemoteError };
+export { REMOTE_ERROR_EVENT, rememberRemoteVersions, remoteVersion, reportRemoteError };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mfeflow/runtime",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Runtime for mfeflow micro-frontends: remotes from a registry index, RemoteBoundary with timeout and fallback, error reporting, singleton checks, composeProviders.",
   "keywords": [
     "micro-frontend",
@@ -33,6 +33,11 @@
       "import": "./dist/providers.js",
       "default": "./dist/providers.js"
     },
+    "./beacon": {
+      "types": "./dist/beacon.d.ts",
+      "import": "./dist/beacon.js",
+      "default": "./dist/beacon.js"
+    },
     "./plugins/report": {
       "types": "./dist/plugins/report.d.ts",
       "import": "./dist/plugins/report.js",
@@ -55,7 +60,7 @@
     "provenance": true
   },
   "dependencies": {
-    "@mfeflow/contracts": "0.5.0"
+    "@mfeflow/contracts": "0.6.0"
   },
   "peerDependencies": {
     "@module-federation/enhanced": "^2.9.0",