@belvador/cloudflare 0.1.0 → 0.3.0

package/README.md

@@ -30,8 +30,9 @@ response (status, headers, streamed body) is returned unchanged and sending fini
 
 ## What it sends
 
-Errors only (exceptions, messages, breadcrumbs you turn on, attachments if you enable them).
-No tracing, session replay, logs or profiling — those items are dropped inside your app.
+Errors (exceptions, messages, breadcrumbs you turn on, attachments if you enable them) and
+the job check-ins you send with `withMonitor`. No spans, session replay, logs or profiling —
+those items are dropped inside your app.
 
 Before anything leaves your app the SDK removes `Authorization`, `Cookie` and `Set-Cookie`
 headers, request bodies and cookies, client IP headers, and masks credentials in URLs, query
@@ -44,6 +45,48 @@ each attempt times out after 10 s, failed sends retry at most 5 times, `429` rat
 respected, and a revoked key (`401`/`403`) stops sending for the life of the page or isolate.
 Every public function catches its own errors.
 
+## Monitor background work
+
+Errors alone cannot tell you that a job never ran. Wrap scheduled and queued work in
+`withMonitor` (Sentry-compatible check-ins): Belvador sees each run start and finish, and
+opens an incident when a run fails, times out or never happens.
+
+```ts
+import { withMonitor } from "@belvador/cloudflare";
+
+export default withBelvador((env) => ({ release: env.BELVADOR_RELEASE }), {
+  async scheduled(controller, env, ctx) {
+    await withMonitor("nightly-invoices", async (run) => {
+      const due = await loadDueInvoices(env);
+      if (due.length === 0) return run.skip("nothing_due");
+      await sendInvoices(env, due);
+    }, { schedule: { type: "crontab", value: "0 2 * * *" }, timezone: "Europe/Berlin" });
+  },
+});
+```
+
+Your function's result and errors come back unchanged (a synchronous function stays
+synchronous); an error is also reported as a normal issue with the monitor's slug. For queue
+consumers pass `runId` (your message id), `attempt` and `willRetry` so retries count as one
+run. `captureCheckIn()` and `heartbeat()` cover manual start/finish and "still alive" checks.
+Check-ins are sent only from server code. See https://belvador.dev/docs/monitors/setup
+
+## Link requests with one trace
+
+Off by default. `tracePropagation: { targets: ["https://api.example.com"] }` adds
+`traceparent` and `sentry-trace` headers to `fetch` calls to those URLs, so an error in the
+called service and its job check-ins show up with the same trace id. An incoming
+`traceparent` (or `sentry-trace`) is continued. No spans or transactions are sent; `baggage`
+only with `baggage: true`. See https://belvador.dev/docs/sdk/tracing
+
+## Check the connection
+
+"No errors" is not proof that errors arrive. Call `verifyIntegration()` from `@belvador/cloudflare` inside a request handled by `withBelvador`:
+it sends one marked test error (never an issue), reads it back and resolves to
+`{ outcome: "verified" | "problem" | "unconfirmed", checks, docsUrl, … }`. It never throws.
+Requests the visitor cancelled (`AbortError`) are not reported unless you set `captureAborted: true`.
+See https://belvador.dev/docs/sdk/verify
+
 ## Status
 
 `0.x` — used by Belvador's own apps first. The API may still change before `1.0`.

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import type { CloudflareOptions as EngineCloudflareOptions } from "@sentry/cloudflare";
-import { type BelvadorOptions } from "@belvador/core";
-export { SDK_VERSION, addBreadcrumb, captureException, captureMessage, close, flush, lastEventId, setContext, setTag, setTags, setUser, withScope, type BelvadorBreadcrumb, type BelvadorEvent, type BelvadorEventHint, type Scope, type SeverityLevel, } from "@belvador/core";
+import { type BelvadorOptions, type VerificationResult, type VerifyOptions } from "@belvador/core";
+export { SDK_VERSION, addBreadcrumb, captureCheckIn, captureException, captureMessage, close, flush, heartbeat, withMonitor, getDiagnostics, lastEventId, setContext, setTag, setTags, setUser, withScope, type BelvadorBreadcrumb, type BelvadorEvent, type BelvadorEventHint, type CheckInInput, type Diagnostic, type DiagnosticCode, type DiagnosticsSnapshot, type MonitorConfigInput, type MonitorSchedule, type RunHandle, type Scope, type SeverityLevel, type TracePropagationOptions, type VerificationResult, type VerifyOptions, type WithMonitorOptions, } from "@belvador/core";
 export type WorkerOptions = Omit<BelvadorOptions, "dsn"> & {
     /** Defaults to the BELVADOR_DSN binding. */
     dsn?: string;
@@ -27,3 +27,9 @@ export declare function wrapHandler<Env, H>(optionsCallback: (env: Env) => Worke
  * untouched, sending finished in waitUntil after the response.
  */
 export declare function withBelvador<Env, H>(optionsCallback: (env: Env) => WorkerOptions | undefined, handler: H): H;
+/**
+ * Proves this Worker reports to Belvador. Call it inside a request handled by
+ * withBelvador (for example a temporary `/verify-belvador` path): it checks the wrapper,
+ * sends one verification error and reads it back. Never automatic; always resolves.
+ */
+export declare function verifyIntegration(options?: VerifyOptions): Promise<VerificationResult>;

package/dist/index.js

@@ -3,8 +3,8 @@
 // privacy and sending rules. Needs the `nodejs_compat` (or `nodejs_als`)
 // compatibility flag so every request gets its own scope.
 import { consoleIntegration, dedupeIntegration, eventFiltersIntegration, fetchIntegration, linkedErrorsIntegration, requestDataIntegration, withSentry, } from "@sentry/cloudflare";
-import { buildEngineOptions } from "@belvador/core";
-export { SDK_VERSION, addBreadcrumb, captureException, captureMessage, close, flush, lastEventId, setContext, setTag, setTags, setUser, withScope, } from "@belvador/core";
+import { TRACE_OPTION, buildEngineOptions, currentHooks, installTracePropagation, markHooked, noteClientAbort, runVerification, withIncomingTraceparent, } from "@belvador/core";
+export { SDK_VERSION, addBreadcrumb, captureCheckIn, captureException, captureMessage, close, flush, heartbeat, withMonitor, getDiagnostics, lastEventId, setContext, setTag, setTags, setUser, withScope, } from "@belvador/core";
 function binding(env, name) {
     if (env === null || typeof env !== "object")
         return undefined;
@@ -76,8 +76,11 @@ export function workerEngineOptions(options, env, runtime = "cloudflare") {
         ];
         if (o.instrument?.console === true)
             integrations.push(consoleIntegration());
+        // Breadcrumbs only: trace headers come from Belvador's own hook, never the engine's.
         if (o.instrument?.fetch === true)
-            integrations.push(fetchIntegration({ breadcrumbs: true }));
+            integrations.push(fetchIntegration({ breadcrumbs: true, shouldCreateSpanForRequest: () => false }));
+        if (base[TRACE_OPTION])
+            installTracePropagation();
         return {
             ...base,
             // 0, not undefined: an undefined value would let SENTRY_TRACES_SAMPLE_RATE turn tracing on.
@@ -89,9 +92,58 @@ export function workerEngineOptions(options, env, runtime = "cloudflare") {
         return OFF;
     }
 }
+const HANDLER_METHODS = ["fetch", "scheduled", "queue", "email", "tail"];
+/**
+ * Marks each invocation of an object handler as running inside the wrapper (integration
+ * health: `verifyIntegration` can tell), and notes a fetch that failed after its client
+ * disconnected so the error counts as a cancellation. Class handlers pass through unchanged.
+ */
+function marked(handler) {
+    if (handler === null || typeof handler !== "object")
+        return handler;
+    const out = { ...handler };
+    for (const name of HANDLER_METHODS) {
+        const fn = handler[name];
+        if (typeof fn !== "function")
+            continue;
+        out[name] = function (...args) {
+            markHooked("wrapper");
+            const signal = name === "fetch" ? signalOf(args[0]) : undefined;
+            if (!signal)
+                return fn.apply(handler, args);
+            const failed = (error) => {
+                noteClientAbort(error, signal);
+                throw error;
+            };
+            let result;
+            try {
+                result = fn.apply(handler, args);
+            }
+            catch (error) {
+                return failed(error);
+            }
+            return isThenable(result) ? Promise.resolve(result).then(undefined, failed) : result;
+        };
+    }
+    return out;
+}
+function signalOf(request) {
+    try {
+        const signal = request?.signal;
+        return typeof AbortSignal !== "undefined" && signal instanceof AbortSignal ? signal : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function isThenable(value) {
+    return (value !== null &&
+        (typeof value === "object" || typeof value === "function") &&
+        typeof value.then === "function");
+}
 /** Shared with @belvador/tanstack-start so its server events carry its own SDK name. */
 export function wrapHandler(optionsCallback, handler, runtime) {
-    return withSentry((env) => {
+    const wrapped = withSentry((env) => {
         let options;
         try {
             options = optionsCallback(env);
@@ -100,7 +152,25 @@ export function wrapHandler(optionsCallback, handler, runtime) {
             return OFF;
         }
         return workerEngineOptions(options, env, runtime);
-    }, handler);
+    }, marked(handler));
+    return incomingTrace(wrapped);
+}
+/**
+ * Spec 06 §5: an incoming W3C `traceparent` (without `sentry-trace`) continues the same
+ * trace; the request is otherwise passed through untouched.
+ */
+function incomingTrace(handler) {
+    if (handler === null || typeof handler !== "object")
+        return handler;
+    const fetch = handler["fetch"];
+    if (typeof fetch !== "function")
+        return handler;
+    return {
+        ...handler,
+        fetch(request, ...rest) {
+            return fetch.call(handler, withIncomingTraceparent(request), ...rest);
+        },
+    };
 }
 /**
  * Wraps a Worker's exported handler (fetch, scheduled, queue, email, tail):
@@ -110,3 +180,17 @@ export function wrapHandler(optionsCallback, handler, runtime) {
 export function withBelvador(optionsCallback, handler) {
     return wrapHandler(optionsCallback, handler, "cloudflare");
 }
+/**
+ * Proves this Worker reports to Belvador. Call it inside a request handled by
+ * withBelvador (for example a temporary `/verify-belvador` path): it checks the wrapper,
+ * sends one verification error and reads it back. Never automatic; always resolves.
+ */
+export function verifyIntegration(options) {
+    return runVerification({
+        surface: "server",
+        hook: () => {
+            const hooks = currentHooks();
+            return { ok: hooks.has("wrapper") || hooks.has("middleware") };
+        },
+    }, options);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@belvador/cloudflare",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Belvador error tracking for Cloudflare Workers: per-request scope, errors only, private by default.",
   "license": "MIT",
   "author": "Belvador (https://belvador.dev)",
@@ -32,7 +32,7 @@
     "node": ">=18"
   },
   "dependencies": {
-    "@belvador/core": "0.1.0",
+    "@belvador/core": "0.3.0",
     "@sentry/cloudflare": "10.76.2"
   },
   "publishConfig": {