@braidlabs/gateway 0.1.1

package/src/telemetry.js

@@ -0,0 +1,177 @@
+/**
+ * Optional telemetry: what the gateway did on the server, and what the user experienced in the
+ * browser — both attributed to the fragment responsible.
+ *
+ * **The attribution is the point.** Server-side timings per fragment are ordinary; a reverse proxy
+ * gives you those. Web vitals per *fragment* are not, because in a composed page the page-level
+ * number is an average over apps owned by different teams. "The page has a CLS of 0.31" starts an
+ * argument. "Ninety percent of the layout shift happened inside `reviews`" ends it.
+ *
+ * Off unless configured, and configured as one hook rather than a sink: what to do with an event —
+ * OpenTelemetry, a log line, a counter, nothing — is the deployment's decision, and a gateway that
+ * picked for you would be a dependency you did not ask for.
+ */
+/** Thresholds from web.dev. Kept here so the gateway and the collector cannot disagree. */
+const THRESHOLDS = {
+    LCP: [2500, 4000],
+    CLS: [0.1, 0.25],
+    INP: [200, 500],
+    FCP: [1800, 3000],
+    TTFB: [800, 1800],
+};
+export function rateVital(name, value) {
+    const [good, poor] = THRESHOLDS[name];
+    return value <= good ? 'good' : value <= poor ? 'needs-improvement' : 'poor';
+}
+/**
+ * Parses a beacon body into events.
+ *
+ * **Everything here arrives from a browser, so none of it is trusted.** A metric name that is not
+ * one of the five, a value that is not finite, or a fragment id that is not registered is dropped
+ * rather than forwarded — a telemetry endpoint that relays whatever it is posted is an open
+ * ingestion API for anyone who can reach it, and the sink downstream would be the thing paying for
+ * that. `known` is the registry's fragment ids; pass an empty set to accept none.
+ */
+export function parseVitalsBeacon(body, known, now = Date.now()) {
+    if (!body || typeof body !== 'object')
+        return [];
+    const { pathname, metrics } = body;
+    if (typeof pathname !== 'string' || !Array.isArray(metrics))
+        return [];
+    // A pathname is echoed back into whatever the sink writes to, so it is length-capped and
+    // stripped of its query here rather than trusted to be a URL this gateway ever served.
+    const safePath = pathname.split('?')[0].slice(0, 512);
+    const events = [];
+    for (const metric of metrics.slice(0, 32)) {
+        if (!metric || typeof metric !== 'object')
+            continue;
+        const { name, value, fragmentId } = metric;
+        if (typeof name !== 'string' || !(name in THRESHOLDS))
+            continue;
+        if (typeof value !== 'number' || !Number.isFinite(value) || value < 0)
+            continue;
+        const vital = name;
+        events.push({
+            kind: 'web-vital',
+            name: vital,
+            value,
+            rating: rateVital(vital, value),
+            // An unregistered id means the page was tampered with or the registry changed under it.
+            // Either way the honest attribution is "not a fragment we know", which is null.
+            fragmentId: typeof fragmentId === 'string' && known.has(fragmentId) ? fragmentId : null,
+            pathname: safePath,
+            at: now,
+        });
+    }
+    return events;
+}
+/**
+ * The browser-side collector, as a source string.
+ *
+ * Hand-written rather than pulling in `web-vitals`: the library is excellent and mostly solves a
+ * problem this does not have — cross-browser normalization for metrics whose polyfills matter on
+ * browsers that cannot run Braid's realms anyway. What is left is four `PerformanceObserver`
+ * registrations, and shipping them inline keeps this dependency-free and keeps the injected script
+ * small enough that measuring a page does not measurably change it.
+ *
+ * The part that is not boilerplate is {@link ownerOf}: attributing an element to the fragment that
+ * rendered it means climbing *out of shadow roots*, since a pierced fragment's DOM lives inside a
+ * declarative shadow root and `closest()` stops at that boundary.
+ */
+export function vitalsCollectorScript(endpoint, sampleRate) {
+    return `// Generated by @braidlabs/gateway. Reports web vitals, attributed per fragment.
+(function () {
+  if (Math.random() >= ${JSON.stringify(sampleRate)}) return;
+  if (typeof PerformanceObserver !== 'function') return;
+
+  var metrics = new Map();
+  var sent = false;
+
+  // Climbs out of shadow roots, which closest() will not do: a pierced fragment's content lives
+  // in a declarative shadow root, so every node inside one is invisible to an ordinary ancestor
+  // walk from the document.
+  function ownerOf(node) {
+    var current = node;
+    while (current) {
+      if (current.nodeType === 1 && current.tagName === 'FRAGMENT-SLOT') {
+        return current.getAttribute('name');
+      }
+      var next = current.parentNode;
+      if (!next) {
+        var root = current.getRootNode && current.getRootNode();
+        next = root && root.host ? root.host : null;
+      }
+      current = next;
+    }
+    return null;
+  }
+
+  // Last value wins for the cumulative and "largest" metrics; that is what the final report means.
+  function record(name, value, node) {
+    metrics.set(name, { name: name, value: value, fragmentId: node ? ownerOf(node) : null });
+  }
+
+  function observe(type, handler, options) {
+    try {
+      var observer = new PerformanceObserver(function (list) { list.getEntries().forEach(handler); });
+      observer.observe(Object.assign({ type: type, buffered: true }, options || {}));
+    } catch (error) {
+      // An unsupported entry type is not an error worth surfacing to the page; it just means this
+      // browser does not report that metric.
+    }
+  }
+
+  observe('largest-contentful-paint', function (entry) {
+    record('LCP', entry.startTime, entry.element);
+  });
+
+  observe('paint', function (entry) {
+    if (entry.name === 'first-contentful-paint') record('FCP', entry.startTime, null);
+  });
+
+  observe('navigation', function (entry) {
+    record('TTFB', entry.responseStart, null);
+  });
+
+  // CLS is cumulative, and the interesting question is which fragment moved the most — so the
+  // score is accumulated per owner and the worst offender is what gets reported.
+  var shiftByOwner = new Map();
+  observe('layout-shift', function (entry) {
+    if (entry.hadRecentInput) return;
+    var sources = entry.sources || [];
+    var owner = null;
+    for (var i = 0; i < sources.length && owner === null; i++) {
+      if (sources[i].node) owner = ownerOf(sources[i].node);
+    }
+    var key = owner === null ? '' : owner;
+    shiftByOwner.set(key, (shiftByOwner.get(key) || 0) + entry.value);
+
+    var worstKey = '';
+    var total = 0;
+    shiftByOwner.forEach(function (score, candidate) {
+      total += score;
+      if (score > (shiftByOwner.get(worstKey) || 0)) worstKey = candidate;
+    });
+    metrics.set('CLS', { name: 'CLS', value: total, fragmentId: worstKey || null });
+  });
+
+  observe('event', function (entry) {
+    var current = metrics.get('INP');
+    if (!current || entry.duration > current.value) record('INP', entry.duration, entry.target);
+  }, { durationThreshold: 40 });
+
+  // Reported when the page goes away, which is the only moment the numbers are final. pagehide
+  // covers the bfcache path that visibilitychange alone misses on iOS.
+  function flush() {
+    if (sent || metrics.size === 0) return;
+    sent = true;
+    var body = JSON.stringify({ pathname: location.pathname, metrics: Array.from(metrics.values()) });
+    if (navigator.sendBeacon) navigator.sendBeacon(${JSON.stringify(endpoint)}, new Blob([body], { type: 'application/json' }));
+  }
+
+  addEventListener('visibilitychange', function () { if (document.visibilityState === 'hidden') flush(); });
+  addEventListener('pagehide', flush);
+})();
+`;
+}
+//# sourceMappingURL=telemetry.js.map

package/src/telemetry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.js","sourceRoot":"","sources":["../../../../libs/braid-gateway/src/telemetry.ts"],"names":[],"mappings":"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"}