@belvador/core 0.1.0 → 0.3.0

package/dist/trace.js

@@ -0,0 +1,184 @@
+// Trace propagation (build observability-1.0 spec 06 §5, SEC-ING-22): off by default.
+// Requests to the app's own targets get `traceparent` (W3C, flags 00 — nothing sampled)
+// and `sentry-trace`; `baggage` only when asked for. Errors-only: no spans, no
+// transactions. Incoming `traceparent` is read on the server so one trace id links
+// the browser error, the server error and the job's check-ins.
+import { addFetchInstrumentationHandler, dynamicSamplingContextToSentryBaggageHeader, generateSpanId, getActiveSpan, getClient, getCurrentScope, getDynamicSamplingContextFromScope, isMatchingPattern, spanToTraceContext, } from "@sentry/core";
+import { reportDiagnostic } from "./diagnostics.js";
+/** Engine-options key carrying the checked config of one client. */
+export const TRACE_OPTION = "_belvadorTrace";
+/** Valid targets only (others reported once a minute); null = propagation off. */
+export function traceConfigOf(opts) {
+    try {
+        if (!opts || !Array.isArray(opts.targets))
+            return null;
+        const targets = [];
+        for (const t of opts.targets) {
+            if ((typeof t === "string" && t.length > 0) || t instanceof RegExp)
+                targets.push(t);
+            else
+                reportDiagnostic("BLV_TRACE_TARGET_INVALID");
+        }
+        return targets.length ? { targets, baggage: opts.baggage === true } : null;
+    }
+    catch {
+        return null;
+    }
+}
+const TRACEPARENT = /^00-([0-9a-f]{32})-([0-9a-f]{16})-[0-9a-f]{2}$/;
+const SENTRY_TRACE = /^[0-9a-f]{32}-[0-9a-f]{16}(-[01])?$/;
+/** W3C `traceparent` → `sentry-trace` (sampling left to the receiver), or null when invalid. */
+export function sentryTraceFromTraceparent(value) {
+    if (typeof value !== "string")
+        return null;
+    const m = TRACEPARENT.exec(value.trim().toLowerCase());
+    if (!m || /^0+$/.test(m[1]) || /^0+$/.test(m[2]))
+        return null;
+    return `${m[1]}-${m[2]}`;
+}
+/**
+ * Server side: a request carrying a valid `traceparent` but no `sentry-trace` gets the
+ * equivalent `sentry-trace`, so the engine continues the same trace. Anything else is
+ * returned unchanged (same object).
+ */
+export function withIncomingTraceparent(request) {
+    try {
+        if (!request || typeof request.headers?.get !== "function")
+            return request;
+        const existing = request.headers.get("sentry-trace");
+        if (existing && SENTRY_TRACE.test(existing.trim()))
+            return request;
+        const converted = sentryTraceFromTraceparent(request.headers.get("traceparent"));
+        if (!converted)
+            return request;
+        const headers = new Headers(request.headers);
+        headers.set("sentry-trace", converted);
+        // Never trust an incoming baggage without its sentry-trace (it would set sampling).
+        headers.delete("baggage");
+        return new Request(request, { headers });
+    }
+    catch {
+        return request;
+    }
+}
+function originOf() {
+    try {
+        const loc = globalThis.location;
+        return typeof loc?.href === "string" ? loc.href : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Sentry's rule: the whole URL, or (browsers) the path of a same-origin URL. */
+export function urlMatches(url, targets) {
+    const test = (s) => targets.some((t) => isMatchingPattern(s, t, false));
+    if (test(url))
+        return true;
+    const base = originOf();
+    if (!base)
+        return false;
+    try {
+        const resolved = new URL(url, base);
+        const page = new URL(base);
+        if (resolved.origin !== page.origin)
+            return false;
+        return test(resolved.href) || test(resolved.pathname);
+    }
+    catch {
+        return false;
+    }
+}
+function clientConfig() {
+    try {
+        const client = getClient();
+        const cfg = client?.getOptions()?.[TRACE_OPTION];
+        if (!client || !cfg)
+            return null;
+        const dsn = client.getDsn();
+        const ingestOrigin = dsn ? `${dsn.protocol}://${dsn.host}${dsn.port ? `:${dsn.port}` : ""}` : "";
+        return { cfg, ingestOrigin };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The current trace as headers: the active span's ids when there is one (a server request),
+ * else the scope's trace with a fresh span id. Errors-only, so the sampling flag is never set
+ * (`traceparent` flags 00, `sentry-trace` without the third part): the receiver decides.
+ */
+export function traceHeaders(baggage) {
+    const scope = getCurrentScope();
+    const span = getActiveSpan();
+    const ctx = span ? spanToTraceContext(span) : null;
+    const pc = scope.getPropagationContext();
+    const traceId = ctx?.trace_id ?? pc.traceId;
+    const spanId = ctx?.span_id ?? pc.propagationSpanId ?? generateSpanId();
+    if (!/^[0-9a-f]{32}$/.test(traceId) || !/^[0-9a-f]{16}$/.test(spanId))
+        return null;
+    const out = {
+        "sentry-trace": `${traceId}-${spanId}`,
+        traceparent: `00-${traceId}-${spanId}-00`,
+    };
+    if (baggage) {
+        const client = getClient();
+        const header = client
+            ? dynamicSamplingContextToSentryBaggageHeader(getDynamicSamplingContextFromScope(client, scope))
+            : undefined;
+        if (header)
+            out["baggage"] = header;
+    }
+    return out;
+}
+function addHeaders(data, cfg) {
+    const trace = traceHeaders(cfg.baggage);
+    const sentryTrace = trace?.["sentry-trace"];
+    if (!trace || !sentryTrace)
+        return;
+    const input = data.args[0];
+    const init = { ...(data.args[1] ?? {}) };
+    const from = init["headers"] ??
+        (typeof Request !== "undefined" && input instanceof Request ? input.headers : undefined);
+    const headers = new Headers(from);
+    if (!headers.has("sentry-trace"))
+        headers.set("sentry-trace", sentryTrace);
+    if (trace["traceparent"] && !headers.has("traceparent"))
+        headers.set("traceparent", trace["traceparent"]);
+    if (cfg.baggage && trace["baggage"] && !headers.has("baggage"))
+        headers.set("baggage", trace["baggage"]);
+    init["headers"] = headers;
+    data.args[1] = init;
+}
+let installed = false;
+/** Installs the fetch hook once per process; each client decides with its own config. */
+export function installTracePropagation() {
+    if (installed)
+        return;
+    installed = true;
+    try {
+        addFetchInstrumentationHandler((data) => {
+            try {
+                const d = data;
+                if (d.endTimestamp || !d.fetchData)
+                    return;
+                const c = clientConfig();
+                if (!c)
+                    return;
+                const url = d.fetchData.url;
+                // Never on the SDK's own sends.
+                if (c.ingestOrigin && url.startsWith(c.ingestOrigin))
+                    return;
+                if (!urlMatches(url, c.cfg.targets))
+                    return;
+                addHeaders(d, c.cfg);
+            }
+            catch {
+                /* a request is never broken by tracing */
+            }
+        });
+    }
+    catch {
+        installed = false;
+    }
+}

package/dist/transport.d.ts

@@ -1,4 +1,5 @@
 import type { BaseTransportOptions, Envelope, Transport } from "@sentry/core";
+import { type DiagnosticCode } from "./diagnostics.js";
 /** The numbers of `docs/build-sdk-1.0/rules.md` §2. */
 export declare const SEND_LIMITS: {
     readonly maxQueue: 30;
@@ -13,6 +14,8 @@ export declare const SEND_LIMITS: {
 };
 /** Item types the node stores (audit §2); everything else never leaves the app. */
 export declare const SENT_ITEM_TYPES: readonly string[];
+/** Of the 30 queued sends, check-ins take at most this many (spec 06 §4): neither storm starves the other. */
+export declare const MAX_QUEUED_CHECK_INS = 10;
 export type FetchLike = (url: string, init: RequestInit) => Promise<Response>;
 export type SendPolicy = {
     attachments: boolean;
@@ -28,7 +31,13 @@ export type SendState = {
     queuedBytes: number;
     keepaliveBytes: number;
     keepaliveCount: number;
+    /** Epoch ms until which the edge asked us to wait (429), for diagnostics. */
+    rateLimitedUntil?: number;
+    /** Check-in envelopes waiting or in flight (≤ MAX_QUEUED_CHECK_INS). */
+    checkIns?: number;
 };
+/** Integration health spec 02 §2.1: what one HTTP answer means for the app. */
+export declare function diagnosticForStatus(status: number): DiagnosticCode | null;
 /**
  * One request with the retry policy: network errors and 500/502/503/504 are
  * retried up to 5 attempts (1/2/4/8 s; a 503 Retry-After ≤ 60 s is honoured),

package/dist/transport.js

@@ -3,6 +3,8 @@
 // One transport for every runtime, built on the engine's `createTransport`
 // (rate limits per category, client reports) with our own request executor.
 import { createEnvelope, createTransport, envelopeItemTypeToDataCategory, forEachEnvelopeItem, makePromiseBuffer, serializeEnvelope, suppressTracing, } from "@sentry/core";
+import { noteSend, reportDiagnostic } from "./diagnostics.js";
+import { noteVerificationOutcome, verificationOfEvent } from "./verification.js";
 /** The numbers of `docs/build-sdk-1.0/rules.md` §2. */
 export const SEND_LIMITS = {
     maxQueue: 30,
@@ -16,12 +18,39 @@ export const SEND_LIMITS = {
     maxRetryAfterMs: 60000,
 };
 /** Item types the node stores (audit §2); everything else never leaves the app. */
-export const SENT_ITEM_TYPES = ["event", "client_report", "attachment"];
+export const SENT_ITEM_TYPES = ["event", "client_report", "attachment", "check_in"];
+/** Of the 30 queued sends, check-ins take at most this many (spec 06 §4): neither storm starves the other. */
+export const MAX_QUEUED_CHECK_INS = 10;
 const RETRY_STATUS = new Set([500, 502, 503, 504]);
 const STOP_STATUS = new Set([401, 403]);
 // Browsers cap keepalive bodies at 64 KiB in flight (fetch spec); stay below it.
 const KEEPALIVE_MAX_BYTES = 60000;
 const KEEPALIVE_MAX_COUNT = 15;
+/** Integration health spec 02 §2.1: what one HTTP answer means for the app. */
+export function diagnosticForStatus(status) {
+    if (status >= 200 && status < 300)
+        return null;
+    if (status === 401 || status === 403)
+        return "BLV_SEND_UNAUTHORIZED";
+    if (status === 429)
+        return "BLV_SEND_RATE_LIMITED";
+    if (status >= 500)
+        return "BLV_SEND_SERVER";
+    return "BLV_SEND_REJECTED";
+}
+/** Verification events in an envelope (id + check), read from tags and context. */
+function verificationsIn(envelope) {
+    const out = [];
+    forEachEnvelopeItem(envelope, (item, type) => {
+        if (type !== "event")
+            return;
+        const payload = item[1];
+        const v = payload && typeof payload === "object" ? verificationOfEvent(payload) : null;
+        if (v)
+            out.push(v);
+    });
+    return out;
+}
 function utf8Length(s) {
     let n = 0;
     for (let i = 0; i < s.length; i++) {
@@ -152,6 +181,14 @@ export async function sendWithRetry(fetchImpl, url, init, state, sleep = default
             throw new Error("aborted");
     }
 }
+function isCheckInEnvelope(envelope) {
+    let found = false;
+    forEachEnvelopeItem(envelope, (_item, type) => {
+        if (type === "check_in")
+            found = true;
+    });
+    return found;
+}
 /** Keeps only item types the node stores; reports the rest as dropped. */
 export function filterEnvelope(envelope, policy, record) {
     const kept = [];
@@ -185,6 +222,8 @@ export function makeBelvadorTransport(policy) {
             queuedBytes: 0,
             keepaliveBytes: 0,
             keepaliveCount: 0,
+            rateLimitedUntil: 0,
+            checkIns: 0,
         };
         const fetchImpl = policy.fetch ?? globalThis.fetch.bind(globalThis);
         const maxEnvelope = policy.attachments
@@ -209,11 +248,29 @@ export function makeBelvadorTransport(policy) {
                     ...(options.headers ? { headers: options.headers } : {}),
                     ...(policy.browser ? { referrerPolicy: "strict-origin", keepalive } : {}),
                 };
-                const res = await suppressTracing(() => sendWithRetry(fetchImpl, options.url, init, state, policy.sleep));
+                let res;
+                try {
+                    res = await suppressTracing(() => sendWithRetry(fetchImpl, options.url, init, state, policy.sleep));
+                }
+                catch (e) {
+                    noteSend("network");
+                    reportDiagnostic("BLV_SEND_NETWORK");
+                    throw e;
+                }
                 const headers = {
                     "x-sentry-rate-limits": res.headers.get("X-Sentry-Rate-Limits"),
                     "retry-after": res.headers.get("Retry-After"),
                 };
+                noteSend(res.status);
+                const code = diagnosticForStatus(res.status);
+                if (code === "BLV_SEND_RATE_LIMITED") {
+                    const after = retryAfterMs(res);
+                    const seconds = Math.round((after ?? 60000) / 1000);
+                    state.rateLimitedUntil = Date.now() + seconds * 1000;
+                    reportDiagnostic(code, { status: res.status, retryAfterS: seconds });
+                }
+                else if (code)
+                    reportDiagnostic(code, { status: res.status });
                 await discard(res);
                 return { statusCode: res.status, headers };
             }
@@ -228,29 +285,75 @@ export function makeBelvadorTransport(policy) {
         return {
             send(envelope) {
                 try {
-                    if (state.stopped)
+                    const verifications = verificationsIn(envelope);
+                    const fail = (code, status) => {
+                        for (const v of verifications)
+                            noteVerificationOutcome(v.id, v.check, {
+                                kind: "failed",
+                                code,
+                                ...(status !== undefined ? { status } : {}),
+                            });
+                    };
+                    if (state.stopped) {
+                        fail("BLV_SEND_UNAUTHORIZED");
                         return Promise.resolve({});
+                    }
                     const kept = filterEnvelope(envelope, policy, options.recordDroppedEvent);
                     if (!kept)
                         return Promise.resolve({});
                     const size = byteLength(serializeEnvelope(kept));
                     if (size > maxEnvelope) {
                         recordAll(kept, "send_error", options.recordDroppedEvent);
+                        reportDiagnostic("BLV_EVENT_TOO_LARGE");
+                        fail("BLV_EVENT_TOO_LARGE");
+                        return Promise.resolve({});
+                    }
+                    const checkIn = isCheckInEnvelope(kept);
+                    if (checkIn && (state.checkIns ?? 0) >= MAX_QUEUED_CHECK_INS) {
+                        recordAll(kept, "queue_overflow", options.recordDroppedEvent);
+                        reportDiagnostic("BLV_CHECK_IN_DROPPED");
                         return Promise.resolve({});
                     }
                     if (state.queuedBytes + size > maxQueued) {
                         recordAll(kept, "queue_overflow", options.recordDroppedEvent);
+                        reportDiagnostic(checkIn ? "BLV_CHECK_IN_DROPPED" : "BLV_QUEUE_FULL");
+                        fail("BLV_QUEUE_FULL");
                         return Promise.resolve({});
                     }
                     state.queuedBytes += size;
+                    if (checkIn)
+                        state.checkIns = (state.checkIns ?? 0) + 1;
                     const release = () => {
                         state.queuedBytes -= size;
+                        if (checkIn)
+                            state.checkIns = Math.max(0, (state.checkIns ?? 1) - 1);
+                    };
+                    const settle = (r) => {
+                        if (verifications.length === 0)
+                            return;
+                        const status = r.statusCode;
+                        if (typeof status !== "number") {
+                            // Dropped by the engine's rate limiter or lost on the network.
+                            fail(Date.now() < (state.rateLimitedUntil ?? 0) ? "BLV_SEND_RATE_LIMITED" : "BLV_SEND_NETWORK");
+                            return;
+                        }
+                        const code = diagnosticForStatus(status);
+                        if (code)
+                            fail(code, status);
+                        else
+                            for (const v of verifications)
+                                noteVerificationOutcome(v.id, v.check, { kind: "sent", status });
                     };
                     return Promise.resolve(inner.send(kept)).then((r) => {
                         release();
+                        settle(r);
+                        // Rate limited (category `monitor`) or lost: the job is fine, the check-in is not.
+                        if (checkIn && (typeof r.statusCode !== "number" || r.statusCode >= 400))
+                            reportDiagnostic("BLV_CHECK_IN_DROPPED");
                         return r;
                     }, () => {
                         release();
+                        settle({});
                         return {};
                     });
                 }

package/dist/verification.d.ts

@@ -0,0 +1,51 @@
+import { VERIFICATION_CONTEXT, VERIFICATION_ERROR_TYPE, VERIFICATION_ID_RE, VERIFICATION_TAG } from "./constants.js";
+export { VERIFICATION_CONTEXT, VERIFICATION_ERROR_TYPE, VERIFICATION_ID_RE, VERIFICATION_TAG };
+export type VerificationSurface = "browser" | "server";
+export type VerificationCheck = "delivery" | "uncaught";
+export type VerificationContext = {
+    v: 1;
+    surface: VerificationSurface;
+    check: VerificationCheck;
+    hook?: "ok" | "missing" | "unknown";
+    uncaught_expected?: boolean;
+};
+declare const MARK = "__belvadorVerification";
+/** The error a verification captures or throws; carries its id and context. */
+export declare class BelvadorVerificationError extends Error {
+    readonly [MARK]: {
+        id: string;
+        context: VerificationContext;
+    };
+    constructor(id: string, context: VerificationContext);
+}
+export declare function newVerificationId(): string;
+/** The marker of a verification error, if `value` is one. */
+export declare function verificationOf(value: unknown): {
+    id: string;
+    context: VerificationContext;
+} | null;
+export type SendOutcome = {
+    kind: "sent";
+    status: number;
+} | {
+    kind: "failed";
+    code: string;
+    status?: number;
+} | {
+    kind: "dropped";
+};
+export declare function noteVerificationOutcome(id: string, check: string, outcome: SendOutcome): void;
+export declare function verificationOutcome(id: string, check: string): SendOutcome | undefined;
+/** The verification id/check of an event, read from its tags and Belvador context. */
+export declare function verificationOfEvent(event: {
+    tags?: Record<string, unknown>;
+    contexts?: Record<string, unknown>;
+}): {
+    id: string;
+    check: string;
+} | null;
+export type HookKind = "middleware" | "wrapper";
+/** Called by Belvador's request/function middleware and Worker wrapper. Never throws. */
+export declare function markHooked(kind: HookKind): void;
+/** Hooks around the code running now (the current request). */
+export declare function currentHooks(): ReadonlySet<HookKind>;

package/dist/verification.js

@@ -0,0 +1,87 @@
+// Verification marker and per-request hook marks (build integration-health-1.0
+// spec 02 §3). A verification is an ordinary error event with a reserved tag; the
+// SDK attaches the tag and context in beforeSend from the thrown error itself, so
+// captured and uncaught verifications take the same path as real errors.
+import { getIsolationScope } from "@sentry/core";
+import { VERIFICATION_CONTEXT, VERIFICATION_ERROR_TYPE, VERIFICATION_ID_RE, VERIFICATION_TAG, } from "./constants.js";
+export { VERIFICATION_CONTEXT, VERIFICATION_ERROR_TYPE, VERIFICATION_ID_RE, VERIFICATION_TAG };
+const MARK = "__belvadorVerification";
+/** The error a verification captures or throws; carries its id and context. */
+export class BelvadorVerificationError extends Error {
+    constructor(id, context) {
+        super(context.check === "uncaught"
+            ? "Belvador verification (uncaught, expected) — safe to ignore"
+            : "Belvador verification (delivery) — safe to ignore");
+        this.name = VERIFICATION_ERROR_TYPE;
+        this[MARK] = { id, context };
+    }
+}
+export function newVerificationId() {
+    const bytes = new Uint8Array(16);
+    crypto.getRandomValues(bytes);
+    let hex = "";
+    for (const b of bytes)
+        hex += b.toString(16).padStart(2, "0");
+    return `bv1_${hex}`;
+}
+/** The marker of a verification error, if `value` is one. */
+export function verificationOf(value) {
+    try {
+        if (value === null || typeof value !== "object")
+            return null;
+        const m = value[MARK];
+        if (!m || typeof m.id !== "string" || !VERIFICATION_ID_RE.test(m.id))
+            return null;
+        if (!m.context || typeof m.context !== "object")
+            return null;
+        return m;
+    }
+    catch {
+        return null;
+    }
+}
+const outcomes = new Map();
+const key = (id, check) => `${id}:${check}`;
+export function noteVerificationOutcome(id, check, outcome) {
+    if (outcomes.size > 50)
+        outcomes.clear();
+    outcomes.set(key(id, check), outcome);
+}
+export function verificationOutcome(id, check) {
+    return outcomes.get(key(id, check));
+}
+/** The verification id/check of an event, read from its tags and Belvador context. */
+export function verificationOfEvent(event) {
+    try {
+        const id = event.tags?.[VERIFICATION_TAG];
+        const ctx = event.contexts?.[VERIFICATION_CONTEXT];
+        if (typeof id !== "string" || !VERIFICATION_ID_RE.test(id))
+            return null;
+        return { id, check: typeof ctx?.check === "string" ? ctx.check : "delivery" };
+    }
+    catch {
+        return null;
+    }
+}
+const hooked = new WeakMap();
+/** Called by Belvador's request/function middleware and Worker wrapper. Never throws. */
+export function markHooked(kind) {
+    try {
+        const scope = getIsolationScope();
+        const set = hooked.get(scope) ?? new Set();
+        set.add(kind);
+        hooked.set(scope, set);
+    }
+    catch {
+        /* no scope */
+    }
+}
+/** Hooks around the code running now (the current request). */
+export function currentHooks() {
+    try {
+        return hooked.get(getIsolationScope()) ?? new Set();
+    }
+    catch {
+        return new Set();
+    }
+}

package/dist/verify.d.ts

@@ -0,0 +1,47 @@
+import { VERIFY_LIMITS } from "./constants.js";
+import { type HookKind, type VerificationSurface } from "./verification.js";
+export { VERIFY_LIMITS };
+export type VerifyOptions = {
+    /** Whole run, default 20 000 ms, at most 30 000. */
+    timeoutMs?: number;
+    /** Browser: also prove that uncaught errors are reported (default true). */
+    uncaught?: boolean;
+    /** Ask Belvador whether the events arrived (default true). */
+    readback?: boolean;
+};
+export type CheckName = "init" | "hook" | "delivery" | "uncaught";
+export type CheckStatus = "confirmed" | "accepted" | "missing" | "failed" | "skipped";
+export type VerificationResult = {
+    verificationId: string;
+    surface: VerificationSurface;
+    sdk: {
+        name: string;
+        version: string;
+    };
+    /** Project id from the DSN, or null when there is none. */
+    project: number | null;
+    checks: Array<{
+        check: CheckName;
+        status: CheckStatus;
+        code?: string;
+    }>;
+    outcome: "verified" | "problem" | "unconfirmed";
+    node?: "connected" | "offline";
+    docsUrl: string;
+};
+/** What a runtime package tells the runner. */
+export type VerifyRuntime = {
+    surface: VerificationSurface;
+    /** Browser: global handlers installed. Server: hooks around the current request. */
+    hook: () => {
+        ok: boolean;
+    };
+    /** Server: which hook kinds count (TanStack Start: middleware; Workers: wrapper or middleware). */
+    serverHooks?: readonly HookKind[];
+    /** Test seams. */
+    fetch?: (url: string, init: RequestInit) => Promise<Response>;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+};
+/** Runs the verification for one runtime. Concurrent calls share one run. */
+export declare function runVerification(runtime: VerifyRuntime, options?: VerifyOptions): Promise<VerificationResult>;