midline-agent 0.3.0 → 0.4.1

package/dist/esm/browser/instrument.js

@@ -0,0 +1,210 @@
+const noop = () => { };
+/** Instrumentation runs inside the page's own calls; a bug here must never become the page's bug. */
+function safely(fn) {
+    try {
+        fn();
+    }
+    catch {
+        // swallowed on purpose
+    }
+}
+const now = () => typeof performance !== "undefined" && typeof performance.now === "function" ? performance.now() : Date.now();
+export function instrumentErrors(win, hooks) {
+    // Registered in the bubble phase: resource load failures (img, script) don't
+    // bubble to window, so only script errors arrive here.
+    const onError = (event) => safely(() => {
+        const e = event;
+        hooks.onError(e.error ?? e.message, "onerror", {
+            message: e.message,
+            filename: e.filename,
+            lineno: e.lineno,
+            colno: e.colno,
+        });
+    });
+    const onRejection = (event) => safely(() => hooks.onError(event.reason, "unhandledrejection"));
+    win.addEventListener("error", onError);
+    win.addEventListener("unhandledrejection", onRejection);
+    return () => {
+        win.removeEventListener("error", onError);
+        win.removeEventListener("unhandledrejection", onRejection);
+    };
+}
+export function instrumentFetch(win, original, hooks) {
+    if (typeof original !== "function")
+        return noop;
+    const RequestCtor = typeof Request === "function" ? Request : undefined;
+    const wrapped = function fetch(input, init) {
+        let url;
+        let method = "GET";
+        let nextInit = init;
+        let spanId;
+        try {
+            const isRequest = RequestCtor !== undefined && input instanceof RequestCtor;
+            url = new URL(isRequest ? input.url : String(input), win.location.href);
+            method = String(init?.method ?? (isRequest ? input.method : "GET")).toUpperCase();
+            if (hooks.isOwnRequest(url)) {
+                url = undefined;
+            }
+            else {
+                const propagation = hooks.propagation(url);
+                if (propagation) {
+                    // fetch(request, init) replaces the request's headers with init's, so
+                    // start from whichever the caller actually supplied.
+                    const headers = new Headers(init?.headers ?? (isRequest ? input.headers : undefined));
+                    for (const [name, value] of Object.entries(propagation.headers)) {
+                        if (!headers.has(name))
+                            headers.set(name, value);
+                    }
+                    nextInit = { ...init, headers };
+                    spanId = propagation.spanId;
+                }
+            }
+        }
+        catch {
+            url = undefined;
+            nextInit = init;
+        }
+        const startedAt = now();
+        const promise = original.call(win, input, nextInit);
+        if (url) {
+            const target = url;
+            promise.then((response) => safely(() => hooks.onRequest({ kind: "fetch", method, url: target, status: response.status || undefined, durationMs: now() - startedAt, spanId })), (error) => safely(() => hooks.onRequest({
+                kind: "fetch",
+                method,
+                url: target,
+                durationMs: now() - startedAt,
+                aborted: error?.name === "AbortError",
+                spanId,
+            })));
+        }
+        return promise;
+    };
+    win.fetch = wrapped;
+    return () => {
+        if (win.fetch === wrapped)
+            win.fetch = original;
+    };
+}
+export function instrumentXhr(win, hooks) {
+    const Xhr = win.XMLHttpRequest;
+    if (typeof Xhr !== "function")
+        return noop;
+    const proto = Xhr.prototype;
+    const originalOpen = proto.open;
+    const originalSend = proto.send;
+    const originalSetRequestHeader = proto.setRequestHeader;
+    const states = new WeakMap();
+    const open = function (method, url, ...rest) {
+        safely(() => {
+            states.set(this, {
+                method: String(method || "GET").toUpperCase(),
+                url: new URL(String(url), win.location.href),
+                headerNames: new Set(),
+            });
+        });
+        return originalOpen.apply(this, [method, url, ...rest]);
+    };
+    const setRequestHeader = function (name, value) {
+        safely(() => states.get(this)?.headerNames.add(String(name).toLowerCase()));
+        return originalSetRequestHeader.call(this, name, value);
+    };
+    const send = function (body) {
+        const state = states.get(this);
+        if (state?.url && !hooks.isOwnRequest(state.url)) {
+            const url = state.url;
+            let spanId;
+            safely(() => {
+                const propagation = hooks.propagation(url);
+                if (!propagation)
+                    return;
+                for (const [name, value] of Object.entries(propagation.headers)) {
+                    // setRequestHeader appends, so a caller's own traceparent would become "a, b".
+                    if (!state.headerNames.has(name))
+                        originalSetRequestHeader.call(this, name, value);
+                }
+                spanId = propagation.spanId;
+            });
+            const startedAt = now();
+            let aborted = false;
+            this.addEventListener("abort", () => {
+                aborted = true;
+            });
+            this.addEventListener("loadend", () => safely(() => hooks.onRequest({
+                kind: "xhr",
+                method: state.method,
+                url,
+                status: this.status || undefined,
+                durationMs: now() - startedAt,
+                aborted,
+                spanId,
+            })));
+        }
+        return originalSend.call(this, body);
+    };
+    proto.open = open;
+    proto.setRequestHeader = setRequestHeader;
+    proto.send = send;
+    return () => {
+        if (proto.open === open)
+            proto.open = originalOpen;
+        if (proto.setRequestHeader === setRequestHeader)
+            proto.setRequestHeader = originalSetRequestHeader;
+        if (proto.send === send)
+            proto.send = originalSend;
+    };
+}
+export function instrumentConsole(target, levels, hooks) {
+    const restores = [];
+    for (const level of levels) {
+        const original = target[level];
+        if (typeof original !== "function")
+            continue;
+        const wrapped = function (...args) {
+            safely(() => hooks.onConsole(level, args));
+            return original.apply(target, args);
+        };
+        target[level] = wrapped;
+        restores.push(() => {
+            if (target[level] === wrapped)
+                target[level] = original;
+        });
+    }
+    return () => restores.forEach((restore) => restore());
+}
+/** Single-page-app route changes, for breadcrumbs and to start a fresh trace per view. */
+export function instrumentHistory(win, hooks) {
+    const history = win.history;
+    if (!history || typeof history.pushState !== "function")
+        return noop;
+    let last = win.location.href;
+    const changed = () => safely(() => {
+        const next = win.location.href;
+        if (next === last)
+            return;
+        const previous = last;
+        last = next;
+        hooks.onNavigation(previous, next);
+    });
+    const originalPush = history.pushState;
+    const originalReplace = history.replaceState;
+    const push = function (...args) {
+        const result = originalPush.apply(this, args);
+        changed();
+        return result;
+    };
+    const replace = function (...args) {
+        const result = originalReplace.apply(this, args);
+        changed();
+        return result;
+    };
+    history.pushState = push;
+    history.replaceState = replace;
+    win.addEventListener("popstate", changed);
+    return () => {
+        if (history.pushState === push)
+            history.pushState = originalPush;
+        if (history.replaceState === replace)
+            history.replaceState = originalReplace;
+        win.removeEventListener("popstate", changed);
+    };
+}

package/dist/esm/browser/transport.js

@@ -0,0 +1,164 @@
+/** Browsers cap the combined body of in-flight keepalive requests at 64 KiB. */
+const KEEPALIVE_BYTES = 60000;
+const MAX_RETRY_DELAY_MS = 300000;
+/**
+ * Batches events and posts them to the ingest API. It never throws into the page
+ * and never blocks it: a Midline outage costs queued telemetry, not the app.
+ */
+export class BrowserTransport {
+    constructor(options) {
+        this.options = options;
+        this.queue = [];
+        this.sending = false;
+        this.stopped = false;
+        this.retryAt = 0;
+        this.backoffMs = 0;
+        this.dropped = 0;
+    }
+    start() {
+        if (this.timer || this.stopped)
+            return;
+        this.timer = setInterval(() => void this.flush(), this.options.flushIntervalMs);
+    }
+    enqueue(event) {
+        if (this.stopped)
+            return;
+        this.queue.push(event);
+        this.trim();
+        if (this.queue.length >= this.options.maxBatchSize && Date.now() >= this.retryAt) {
+            void this.flush();
+        }
+    }
+    get size() {
+        return this.queue.length;
+    }
+    /** Sends everything queued, one batch at a time, unless Midline asked us to back off. */
+    async flush() {
+        if (this.stopped || this.sending || !this.queue.length || Date.now() < this.retryAt)
+            return;
+        this.sending = true;
+        try {
+            while (this.queue.length && !this.stopped) {
+                const batch = this.queue.splice(0, this.options.maxBatchSize);
+                const outcome = await this.send(batch, false);
+                if (outcome === "retry") {
+                    this.queue.unshift(...batch);
+                    this.trim();
+                    return;
+                }
+                if (outcome === "stop")
+                    return;
+            }
+        }
+        finally {
+            this.sending = false;
+        }
+    }
+    /**
+     * The page is being hidden and may never come back. Hands whatever is queued to
+     * keepalive requests without waiting on them; an in-flight regular flush is left
+     * alone, since its batch already left the queue.
+     */
+    flushOnHide() {
+        if (this.stopped || !this.queue.length)
+            return;
+        let budget = KEEPALIVE_BYTES;
+        while (this.queue.length) {
+            const batch = [];
+            let bytes = 12;
+            while (this.queue.length && batch.length < this.options.maxBatchSize) {
+                const size = JSON.stringify(this.queue[0]).length + 1;
+                if (batch.length && bytes + size > budget)
+                    break;
+                batch.push(this.queue.shift());
+                bytes += size;
+            }
+            budget -= bytes;
+            void this.send(batch, budget > 0);
+            if (budget <= 0)
+                break;
+        }
+    }
+    stop() {
+        this.stopped = true;
+        this.queue = [];
+        if (this.timer)
+            clearInterval(this.timer);
+        this.timer = undefined;
+    }
+    trim() {
+        const excess = this.queue.length - this.options.maxQueueSize;
+        if (excess > 0) {
+            this.queue.splice(0, excess);
+            this.dropped += excess;
+        }
+    }
+    async send(batch, keepalive) {
+        let response;
+        try {
+            response = await this.options.fetch(this.options.batchUrl, {
+                method: "POST",
+                headers: { "Content-Type": "application/json", "X-API-Key": this.options.apiKey },
+                body: JSON.stringify({ events: batch }),
+                keepalive,
+                credentials: "omit",
+                mode: "cors",
+            });
+        }
+        catch (error) {
+            // Offline, blocked by an extension, or a server that doesn't answer CORS.
+            this.options.debug(`midline: could not reach Midline (${describe(error)}); will retry.`);
+            this.backOff();
+            return "retry";
+        }
+        const { status } = response;
+        if (status >= 200 && status < 300) {
+            this.backoffMs = 0;
+            this.retryAt = 0;
+            return "ok";
+        }
+        if (status === 401 || status === 403) {
+            const detail = await serverMessage(response);
+            this.stop();
+            this.options.onStop(`midline: the Midline server refused this key (HTTP ${status}${detail ? `: ${detail}` : ""}). ` +
+                "Browser monitoring is now off.");
+            return "stop";
+        }
+        if (status === 408 || status === 429 || status >= 500) {
+            this.backOff(parseRetryAfter(response.headers.get("retry-after")));
+            this.options.debug(`midline: Midline answered HTTP ${status}; events are kept and retried.`);
+            return "retry";
+        }
+        this.dropped += batch.length;
+        const detail = await serverMessage(response);
+        this.options.debug(`midline: Midline rejected ${batch.length} events (HTTP ${status}${detail ? `: ${detail}` : ""}).`);
+        return "drop";
+    }
+    backOff(retryAfterMs = 0) {
+        this.backoffMs = Math.min(Math.max(this.backoffMs * 2, 1000), MAX_RETRY_DELAY_MS);
+        this.retryAt = Date.now() + Math.max(this.backoffMs, Math.min(retryAfterMs, MAX_RETRY_DELAY_MS));
+    }
+}
+function parseRetryAfter(value) {
+    if (!value)
+        return 0;
+    const seconds = Number(value);
+    if (Number.isFinite(seconds))
+        return Math.max(0, seconds * 1000);
+    const date = Date.parse(value);
+    return Number.isFinite(date) ? Math.max(0, date - Date.now()) : 0;
+}
+async function serverMessage(response) {
+    try {
+        const text = await response.text();
+        const parsed = JSON.parse(text);
+        const message = Array.isArray(parsed?.message) ? parsed.message.join("; ") : parsed?.message;
+        return typeof message === "string" ? message.slice(0, 300) : "";
+    }
+    catch {
+        return "";
+    }
+}
+function describe(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/esm/browser/types.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/browser/version.js

@@ -0,0 +1,2 @@
+/** Kept in step with package.json by test/browser.test.js; a browser bundle can't read package.json. */
+export const BROWSER_SDK_VERSION = "0.4.0";

package/dist/esm/browser/vitals.js

@@ -0,0 +1,132 @@
+/** web.dev thresholds: at or under the first is good, over the second is poor. */
+const THRESHOLDS = {
+    LCP: [2500, 4000],
+    INP: [200, 500],
+    CLS: [0.1, 0.25],
+    FCP: [1800, 3000],
+    TTFB: [800, 1800],
+};
+const rate = (name, value) => value <= THRESHOLDS[name][0] ? "good" : value <= THRESHOLDS[name][1] ? "needs-improvement" : "poor";
+/**
+ * Core Web Vitals without a dependency, measured the way the web-vitals library
+ * does and reported once, when the page is first hidden (the last moment a
+ * report reliably gets out). Browsers that don't expose an entry type simply
+ * omit that metric: Safari has no LCP, INP or CLS.
+ */
+export function observeVitals(win, onReport) {
+    const Observer = win.PerformanceObserver;
+    const supported = Observer?.supportedEntryTypes ?? [];
+    const perf = win.performance;
+    const doc = win.document;
+    const values = {};
+    const observers = [];
+    let activationStart = 0;
+    let navigationType;
+    try {
+        const navigation = perf?.getEntriesByType?.("navigation")?.[0];
+        if (navigation) {
+            activationStart = navigation.activationStart ?? 0;
+            navigationType = navigation.type;
+            if (typeof navigation.responseStart === "number" && navigation.responseStart > 0) {
+                values.TTFB = Math.max(0, navigation.responseStart - activationStart);
+            }
+        }
+    }
+    catch {
+        // no navigation timing
+    }
+    const observe = (type, handle, extra = {}) => {
+        if (!Observer || !supported.includes(type))
+            return;
+        try {
+            const observer = new Observer((list) => handle(list.getEntries()));
+            observer.observe({ type, buffered: true, ...extra });
+            observers.push({ observer, handle });
+        }
+        catch {
+            // unsupported option in this browser
+        }
+    };
+    observe("paint", (entries) => {
+        for (const entry of entries) {
+            if (entry.name === "first-contentful-paint")
+                values.FCP = Math.max(0, entry.startTime - activationStart);
+        }
+    });
+    observe("largest-contentful-paint", (entries) => {
+        const last = entries[entries.length - 1];
+        if (last)
+            values.LCP = Math.max(0, last.startTime - activationStart);
+    });
+    // CLS is the largest session window: shifts less than 1s apart, at most 5s long.
+    let windowValue = 0;
+    let windowStart = 0;
+    let windowLast = 0;
+    observe("layout-shift", (entries) => {
+        for (const entry of entries) {
+            if (entry.hadRecentInput || typeof entry.value !== "number")
+                continue;
+            if (windowValue && entry.startTime - windowLast < 1000 && entry.startTime - windowStart < 5000) {
+                windowValue += entry.value;
+            }
+            else {
+                windowValue = entry.value;
+                windowStart = entry.startTime;
+            }
+            windowLast = entry.startTime;
+            values.CLS = Math.max(values.CLS ?? 0, windowValue);
+        }
+    });
+    // INP: the slowest interaction, or near the 98th percentile on busy pages.
+    const interactions = new Map();
+    const recordInteractions = (entries) => {
+        for (const entry of entries) {
+            if (!entry.interactionId)
+                continue;
+            interactions.set(entry.interactionId, Math.max(interactions.get(entry.interactionId) ?? 0, entry.duration));
+        }
+    };
+    observe("event", recordInteractions, { durationThreshold: 40 });
+    observe("first-input", recordInteractions);
+    let reported = false;
+    const report = () => {
+        if (reported)
+            return;
+        reported = true;
+        for (const { observer, handle } of observers) {
+            try {
+                handle(observer.takeRecords());
+                observer.disconnect();
+            }
+            catch {
+                // already disconnected
+            }
+        }
+        if (interactions.size) {
+            const durations = [...interactions.values()].sort((a, b) => b - a);
+            values.INP = durations[Math.min(durations.length - 1, Math.floor(durations.length / 50))];
+        }
+        const vitals = {};
+        for (const name of Object.keys(values)) {
+            const raw = values[name];
+            if (typeof raw !== "number" || !Number.isFinite(raw))
+                continue;
+            const value = name === "CLS" ? Math.round(raw * 10000) / 10000 : Math.round(raw);
+            vitals[name] = { value, rating: rate(name, value) };
+        }
+        if (Object.keys(vitals).length)
+            onReport({ vitals, navigationType });
+    };
+    const onVisibility = () => {
+        if (doc?.visibilityState === "hidden")
+            report();
+    };
+    doc?.addEventListener("visibilitychange", onVisibility, true);
+    win.addEventListener("pagehide", report, true);
+    return () => {
+        doc?.removeEventListener("visibilitychange", onVisibility, true);
+        win.removeEventListener("pagehide", report, true);
+        for (const { observer } of observers)
+            observer.disconnect();
+    };
+}

package/dist/esm/package.json

@@ -0,0 +1 @@
+{ "type": "module" }