@farm.js/sentry 0.1.0-beta.68

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024 Farm.js Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,133 @@
+# @farm.js/sentry
+
+Sentry error reporting and tracing for Farm.js applications. It maps Farm's request, render and
+build lifecycles onto Sentry, so errors arrive with route context and requests are traced.
+
+Farm.js is currently in beta.
+
+## Install
+
+```bash
+pnpm add @farm.js/sentry @sentry/node
+```
+
+`@sentry/node` is an optional peer dependency. If a `dsn` is configured and it is not installed,
+the plugin logs a clear error and continues without reporting rather than preventing the
+application from starting.
+
+## Configure
+
+```ts
+import { defineConfig } from "@farm.js/core";
+import { sentryPlugin } from "@farm.js/sentry";
+
+export default defineConfig({
+  plugins: [
+    sentryPlugin({
+      dsn: process.env.SENTRY_DSN,
+      tracesSampleRate: 0.1,
+      sourceMaps: true,
+    }),
+  ],
+});
+```
+
+## Initialize early
+
+The Node SDK patches other modules as they load, so it has to run before the rest of the
+application. Add an instrumentation file for that:
+
+```ts
+// src/instrumentation.ts
+import { registerSentry } from "@farm.js/sentry";
+
+export const register = registerSentry({
+  dsn: process.env.SENTRY_DSN,
+  tracesSampleRate: 0.1,
+});
+```
+
+Without this the plugin still reports errors, but the SDK's automatic database and HTTP
+instrumentation will not attach.
+
+## What it does
+
+| Hook              | Behavior                                                                 |
+| ----------------- | ------------------------------------------------------------------------ |
+| `runtime.start`   | initializes the SDK if nothing has already, and listens for error events |
+| `runtime.context` | names the request span by route pattern                                  |
+| `runtime.after`   | sets the span status from the response                                   |
+| `runtime.error`   | captures the exception with route, kind and request context              |
+| `runtime.close`   | flushes pending events on shutdown                                       |
+| `build.configure` | enables source maps when `sourceMaps` is set                             |
+
+Spans are named by route pattern rather than pathname, so `/users/[id]` stays one span name
+instead of one per user.
+
+Where the SDK's own HTTP instrumentation has already opened a span for the request, the plugin
+renames that one rather than starting another, so automatic HTTP and database spans stay nested
+under the request. It only creates a span when nothing is active.
+
+## Serverless
+
+Hosts that can terminate a process without a shutdown signal never run `runtime.close`, so
+pending events are lost. Flush inside the request instead:
+
+```ts
+sentryPlugin({
+  dsn: process.env.SENTRY_DSN,
+  flushOnResponse: true,
+});
+```
+
+The flush is handed to `waitUntil`, so the host keeps the invocation alive until it completes.
+
+## Options
+
+| Option             | Default              | Description                                                                    |
+| ------------------ | -------------------- | ------------------------------------------------------------------------------ |
+| `dsn`              |                      | Sentry project DSN.                                                            |
+| `environment`      | instrumentation mode | Environment name.                                                              |
+| `release`          |                      | Release identifier for the deploy.                                             |
+| `tracesSampleRate` |                      | Fraction of requests traced. Errors are always sent.                           |
+| `sendDefaultPii`   | `false`              | Include request headers and user data.                                         |
+| `enabled`          | `true`               | Set false to register the hooks but report nothing.                            |
+| `sdk`              | `@sentry/node`       | An SDK module to use instead of importing it.                                  |
+| `flushOnResponse`  | `false`              | Flush after every response and after a failed request.                         |
+| `flushTimeoutMs`   | `2000`               | Flush timeout.                                                                 |
+| `sourceMaps`       | `false`              | Generate source maps in the production build. Does not upload them, see below. |
+
+`sendDefaultPii` stays off by default because error events can carry request headers and user
+data.
+
+## Source maps
+
+`sourceMaps: true` only generates source maps during the production build. It does not upload
+them to Sentry, so production stack traces stay minified until the maps are uploaded separately,
+for example with `sentry-cli`. Uploading from the build is not implemented yet.
+
+Farm only uses its fast esbuild minifier while source maps are off, so enabling them moves
+minification to Nitro's terser:
+
+```bash
+pnpm add -D @rollup/plugin-terser
+```
+
+Without it the production build fails with `Cannot find module '@rollup/plugin-terser'`.
+
+## Runtime support
+
+Node presets. `@sentry/node` does not run on Cloudflare Workers, which need `@sentry/cloudflare`
+instead, so `registerSentry` is a no-op on `edge` and `bun` runtimes. Edge support is tracked
+separately.
+
+## Bring your own SDK
+
+`sdk` accepts anything matching the small structural interface the plugin uses, which is also
+how the package is unit tested:
+
+```ts
+import * as Sentry from "@sentry/node";
+
+sentryPlugin({ sdk: Sentry });
+```

package/dist/index.d.ts

@@ -0,0 +1,158 @@
+import type { FarmInstrumentationCleanup, FarmInstrumentationContext } from "@farm.js/core/instrumentation";
+import { type FarmEvent } from "@farm.js/core/observability";
+/** Minimal span surface used by the plugin, satisfied by `@sentry/node`. */
+export interface SentrySpanLike {
+    end(): void;
+    setStatus?(status: {
+        code: number;
+        message?: string;
+    }): void;
+    setAttribute?(key: string, value: unknown): void;
+}
+/** Minimal scope surface used by the plugin, satisfied by `@sentry/node`. */
+export interface SentryScopeLike {
+    setTag(key: string, value: string): void;
+    setContext(key: string, value: Record<string, unknown> | null): void;
+}
+/**
+ * The parts of the Sentry SDK this plugin uses. Declared structurally so the
+ * plugin can be unit tested and so an application can pass an SDK it already
+ * initialized, the way `@farm.js/cache-redis` accepts any Redis client.
+ */
+export interface SentrySdkLike {
+    init?(options: Record<string, unknown>): void;
+    /** Returns the active client, or undefined before `init`. */
+    getClient?(): unknown;
+    captureException(error: unknown, hint?: {
+        captureContext?: unknown;
+    }): string;
+    withScope?<T>(callback: (scope: SentryScopeLike) => T): T;
+    /** The span the SDK's own instrumentation opened for this request. */
+    getActiveSpan?(): SentrySpanLike | undefined;
+    getRootSpan?(span: SentrySpanLike): SentrySpanLike | undefined;
+    updateSpanName?(span: SentrySpanLike, name: string): void;
+    startInactiveSpan?(options: {
+        name: string;
+        op?: string;
+        /** Send the span as a transaction root rather than a child. */
+        forceTransaction?: boolean;
+        attributes?: Record<string, unknown>;
+    }): SentrySpanLike | undefined;
+    flush?(timeout?: number): Promise<boolean>;
+}
+export interface SentryPluginOptions {
+    dsn?: string;
+    environment?: string;
+    release?: string;
+    tracesSampleRate?: number;
+    /**
+     * Error events can carry request headers and user data, so this stays off
+     * unless the application opts in.
+     */
+    sendDefaultPii?: boolean;
+    /** Set false to register the hooks but do no reporting. */
+    enabled?: boolean;
+    /** An SDK module to use instead of importing `@sentry/node`. */
+    sdk?: SentrySdkLike;
+    /**
+     * Flush after every response and after a failed request. Required on hosts
+     * that can terminate a process without a shutdown signal, where
+     * `runtime.close` never runs.
+     */
+    flushOnResponse?: boolean;
+    flushTimeoutMs?: number;
+    /**
+     * Extra options merged into `Sentry.init`, for anything this plugin does not
+     * model directly such as `debug`, `beforeSend`, `ignoreErrors` or
+     * `integrations`. Explicit options above win over keys repeated here.
+     */
+    sentryOptions?: Record<string, unknown>;
+    /**
+     * Emit source maps in the production build. This only generates them, it does
+     * not upload anything to Sentry, so stack traces stay minified until the maps
+     * are uploaded separately.
+     *
+     * Farm only uses its fast esbuild minifier while `sourceMap` is false, so
+     * turning this on moves minification to Nitro's terser. Install
+     * `@rollup/plugin-terser` alongside it, otherwise the build fails with
+     * `Cannot find module '@rollup/plugin-terser'`.
+     */
+    sourceMaps?: boolean;
+}
+/** Per-request state stored under the `sentry` context key. */
+export interface SentryRequestContext {
+    span?: SentrySpanLike;
+    /** True when the plugin created the span and therefore has to end it. */
+    ownsSpan: boolean;
+    startedAt: number;
+    ended: boolean;
+}
+/**
+ * Returns false when the same error is already being delivered through another
+ * Farm error path. The claim expires so reusing an error in a later request is
+ * still reported.
+ */
+export declare function claimError(error: unknown): boolean;
+export declare function resolveSentrySdk(options: SentryPluginOptions): Promise<SentrySdkLike | undefined>;
+/**
+ * Report loudly when a DSN was configured but no SDK resolved. Silently doing
+ * nothing hides a missing or broken install until errors are already lost.
+ *
+ * This logs rather than throws. It runs during instrumentation, before the
+ * application loads, so throwing takes the whole process down. Monitoring must
+ * never do that to the application it observes.
+ */
+export declare function assertSentrySdk(sdk: SentrySdkLike | undefined, options: SentryPluginOptions): SentrySdkLike | undefined;
+export declare function requireSentrySdk(options: SentryPluginOptions): Promise<SentrySdkLike | undefined>;
+export declare function buildSentryInitOptions(options: SentryPluginOptions, context?: Pick<FarmInstrumentationContext, "mode">): Record<string, unknown>;
+/** Initialize once. A second `init` would replace a working client. */
+export declare function initSentryOnce(sdk: SentrySdkLike, options: SentryPluginOptions, context?: Pick<FarmInstrumentationContext, "mode">): boolean;
+/**
+ * True for observability events that carry a reportable error.
+ *
+ * Farm handles many failures internally rather than letting them reach the
+ * plugin's `runtime.error` hook. A page that throws during render becomes a
+ * `render.error` event and a 500 response, and the request pipeline never
+ * throws, so the event stream is the only place those are visible.
+ */
+export declare function isErrorEvent(event: FarmEvent): event is FarmEvent & {
+    error: unknown;
+};
+/** Route hint carried by the error-bearing events, where one is present. */
+export declare function errorEventRoute(event: FarmEvent): string | undefined;
+/**
+ * Name spans by route pattern rather than pathname. `/users/[id]` keeps one
+ * span name, where `/users/1` and `/users/2` would create one per user.
+ */
+export declare function spanNameFor(method: string, route: {
+    pathname: string;
+    pattern?: string | null;
+} | undefined, fallbackPathname: string): string;
+/**
+ * Early Sentry initialization for `src/instrumentation.ts`.
+ *
+ * The Node SDK patches other modules as they load, so it has to run before the
+ * rest of the application. A plugin `setup` cannot guarantee that ordering.
+ *
+ * ```ts
+ * // src/instrumentation.ts
+ * export const register = registerSentry({ dsn: process.env.SENTRY_DSN });
+ * ```
+ */
+export declare function registerSentry(options?: SentryPluginOptions): (context: FarmInstrumentationContext) => Promise<FarmInstrumentationCleanup>;
+/**
+ * Maps Farm's request, render and build lifecycles onto Sentry.
+ *
+ * Pair with `registerSentry` in `src/instrumentation.ts` when using the Node
+ * SDK, so initialization happens before the application loads.
+ */
+export declare function sentryPlugin(options?: SentryPluginOptions): import("@farm.js/core/plugin").FarmPlugin<{
+    enabled: boolean;
+    options: SentryPluginOptions;
+    flushTimeoutMs: number;
+    sdk: SentrySdkLike | undefined;
+    unsubscribe: (() => void) | undefined;
+}, {
+    sentry: SentryRequestContext;
+}, unknown, undefined, unknown, false>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,0BAA0B,EAC1B,0BAA0B,EAC3B,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAe,KAAK,SAAS,EAAE,MAAM,6BAA6B,CAAC;AAG1E,4EAA4E;AAC5E,MAAM,WAAW,cAAc;IAC7B,GAAG,IAAI,IAAI,CAAC;IACZ,SAAS,CAAC,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAC7D,YAAY,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;CAClD;AAED,6EAA6E;AAC7E,MAAM,WAAW,eAAe;IAC9B,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACzC,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC;CACtE;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC9C,6DAA6D;IAC7D,SAAS,CAAC,IAAI,OAAO,CAAC;IACtB,gBAAgB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE;QAAE,cAAc,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,MAAM,CAAC;IAC9E,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,CAAC,GAAG,CAAC,CAAC;IAC1D,sEAAsE;IACtE,aAAa,CAAC,IAAI,cAAc,GAAG,SAAS,CAAC;IAC7C,WAAW,CAAC,CAAC,IAAI,EAAE,cAAc,GAAG,cAAc,GAAG,SAAS,CAAC;IAC/D,cAAc,CAAC,CAAC,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1D,iBAAiB,CAAC,CAAC,OAAO,EAAE;QAC1B,IAAI,EAAE,MAAM,CAAC;QACb,EAAE,CAAC,EAAE,MAAM,CAAC;QACZ,+DAA+D;QAC/D,gBAAgB,CAAC,EAAE,OAAO,CAAC;QAC3B,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACtC,GAAG,cAAc,GAAG,SAAS,CAAC;IAC/B,KAAK,CAAC,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC5C;AAED,MAAM,WAAW,mBAAmB;IAClC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,2DAA2D;IAC3D,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,gEAAgE;IAChE,GAAG,CAAC,EAAE,aAAa,CAAC;IACpB;;;;OAIG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC;;;;;;;;;OASG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,+DAA+D;AAC/D,MAAM,WAAW,oBAAoB;IACnC,IAAI,CAAC,EAAE,cAAc,CAAC;IACtB,yEAAyE;IACzE,QAAQ,EAAE,OAAO,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,OAAO,CAAC;CAChB;AAsBD;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAYlD;AAMD,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAYpC;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,aAAa,GAAG,SAAS,EAC9B,OAAO,EAAE,mBAAmB,GAC3B,aAAa,GAAG,SAAS,CAI3B;AAED,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAEpC;AAED,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,mBAAmB,EAC5B,OAAO,CAAC,EAAE,IAAI,CAAC,0BAA0B,EAAE,MAAM,CAAC,GACjD,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAezB;AAED,uEAAuE;AACvE,wBAAgB,cAAc,CAC5B,GAAG,EAAE,aAAa,EAClB,OAAO,EAAE,mBAAmB,EAC5B,OAAO,CAAC,EAAE,IAAI,CAAC,0BAA0B,EAAE,MAAM,CAAC,GACjD,OAAO,CAKT;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,SAAS,GAAG,KAAK,IAAI,SAAS,GAAG;IAAE,KAAK,EAAE,OAAO,CAAA;CAAE,CAGtF;AAED,4EAA4E;AAC5E,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,GAAG,SAAS,CAGpE;AAED;;;GAGG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,MAAM,EACd,KAAK,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GAAG,SAAS,EAChE,gBAAgB,EAAE,MAAM,GACvB,MAAM,CAER;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAC5B,OAAO,GAAE,mBAAwB,GAChC,CAAC,OAAO,EAAE,0BAA0B,KAAK,OAAO,CAAC,0BAA0B,CAAC,CA2B9E;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,OAAO,GAAE,mBAAwB;;;;;iBAiB5B,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS;;;uCAuJzD"}

package/dist/index.js

@@ -0,0 +1,336 @@
+import { onFarmEvent } from "@farm.js/core/observability";
+import { definePlugin } from "@farm.js/core/plugin";
+const DEFAULT_FLUSH_TIMEOUT_MS = 2_000;
+/** Sentry status codes: 1 is ok, 2 is error. */
+const SPAN_STATUS_OK = 1;
+const SPAN_STATUS_ERROR = 2;
+/** Errors reported during the current event-loop turn. */
+const recentlyReportedErrors = new WeakSet();
+/**
+ * Thrown primitives reported during the current event-loop turn.
+ *
+ * A WeakSet cannot hold a string or a number, so these are tracked separately.
+ * The claim is by value rather than identity, so two requests throwing the
+ * identical primitive within one turn report once. That is the better trade
+ * against reporting every primitive twice, since a value carries no stack and
+ * Sentry groups the events together regardless.
+ */
+const recentlyReportedValues = new Set();
+/**
+ * Returns false when the same error is already being delivered through another
+ * Farm error path. The claim expires so reusing an error in a later request is
+ * still reported.
+ */
+export function claimError(error) {
+    if (typeof error === "object" && error !== null) {
+        if (recentlyReportedErrors.has(error))
+            return false;
+        recentlyReportedErrors.add(error);
+        setTimeout(() => recentlyReportedErrors.delete(error), 0);
+        return true;
+    }
+    if (recentlyReportedValues.has(error))
+        return false;
+    recentlyReportedValues.add(error);
+    setTimeout(() => recentlyReportedValues.delete(error), 0);
+    return true;
+}
+const MISSING_SDK_MESSAGE = "@farm.js/sentry needs @sentry/node. Install it with `pnpm add @sentry/node`, " +
+    "or pass an SDK through the `sdk` option.";
+export async function resolveSentrySdk(options) {
+    if (options.sdk)
+        return options.sdk;
+    try {
+        // The specifier has to be a literal. A variable is invisible to bundlers,
+        // so the dependency is never traced into serverless output and the import
+        // fails at runtime. That is what happened on Vercel, where the plugin
+        // reported a missing SDK even though the package was installed.
+        return (await import("@sentry/node"));
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Report loudly when a DSN was configured but no SDK resolved. Silently doing
+ * nothing hides a missing or broken install until errors are already lost.
+ *
+ * This logs rather than throws. It runs during instrumentation, before the
+ * application loads, so throwing takes the whole process down. Monitoring must
+ * never do that to the application it observes.
+ */
+export function assertSentrySdk(sdk, options) {
+    if (sdk)
+        return sdk;
+    if (options.dsn)
+        console.error(`[farm:sentry] ${MISSING_SDK_MESSAGE}`);
+    return undefined;
+}
+export async function requireSentrySdk(options) {
+    return assertSentrySdk(await resolveSentrySdk(options), options);
+}
+export function buildSentryInitOptions(options, context) {
+    const explicit = {
+        dsn: options.dsn,
+        environment: options.environment ?? context?.mode,
+        release: options.release,
+        tracesSampleRate: options.tracesSampleRate,
+        sendDefaultPii: options.sendDefaultPii ?? false,
+    };
+    // Drop undefined so a passthrough key is not overwritten by an unset option.
+    for (const key of Object.keys(explicit)) {
+        if (explicit[key] === undefined)
+            delete explicit[key];
+    }
+    return { ...options.sentryOptions, ...explicit };
+}
+/** Initialize once. A second `init` would replace a working client. */
+export function initSentryOnce(sdk, options, context) {
+    if (!options.dsn)
+        return false;
+    if (sdk.getClient?.())
+        return false;
+    sdk.init?.(buildSentryInitOptions(options, context));
+    return true;
+}
+/**
+ * True for observability events that carry a reportable error.
+ *
+ * Farm handles many failures internally rather than letting them reach the
+ * plugin's `runtime.error` hook. A page that throws during render becomes a
+ * `render.error` event and a 500 response, and the request pipeline never
+ * throws, so the event stream is the only place those are visible.
+ */
+export function isErrorEvent(event) {
+    if (!("error" in event) || event.error === undefined)
+        return false;
+    return event.type === "error" || event.type.endsWith(".error");
+}
+/** Route hint carried by the error-bearing events, where one is present. */
+export function errorEventRoute(event) {
+    const route = event.route;
+    return typeof route === "string" ? route : undefined;
+}
+/**
+ * Name spans by route pattern rather than pathname. `/users/[id]` keeps one
+ * span name, where `/users/1` and `/users/2` would create one per user.
+ */
+export function spanNameFor(method, route, fallbackPathname) {
+    return `${method} ${route?.pattern || route?.pathname || fallbackPathname}`;
+}
+/**
+ * Early Sentry initialization for `src/instrumentation.ts`.
+ *
+ * The Node SDK patches other modules as they load, so it has to run before the
+ * rest of the application. A plugin `setup` cannot guarantee that ordering.
+ *
+ * ```ts
+ * // src/instrumentation.ts
+ * export const register = registerSentry({ dsn: process.env.SENTRY_DSN });
+ * ```
+ */
+export function registerSentry(options = {}) {
+    return async function register(context) {
+        if (options.enabled === false)
+            return;
+        // Node only for now. `@sentry/node` does not run on Workers, which need
+        // `@sentry/cloudflare` instead.
+        if (context.runtime !== "nodejs")
+            return;
+        // Instrumentation runs before the application loads, so anything thrown
+        // here stops the process from booting. Losing telemetry is acceptable,
+        // taking the application down with it is not.
+        try {
+            const sdk = await requireSentrySdk(options);
+            if (!sdk)
+                return;
+            initSentryOnce(sdk, options, context);
+            return () => flushSentrySafely(sdk, options.flushTimeoutMs ?? DEFAULT_FLUSH_TIMEOUT_MS, "[farm:sentry] instrumentation flush failed:");
+        }
+        catch (error) {
+            console.error("[farm:sentry] failed to initialize, continuing without it:", error);
+            return;
+        }
+    };
+}
+/**
+ * Maps Farm's request, render and build lifecycles onto Sentry.
+ *
+ * Pair with `registerSentry` in `src/instrumentation.ts` when using the Node
+ * SDK, so initialization happens before the application loads.
+ */
+export function sentryPlugin(options = {}) {
+    const enabled = options.enabled !== false;
+    const flushTimeoutMs = options.flushTimeoutMs ?? DEFAULT_FLUSH_TIMEOUT_MS;
+    return definePlugin({
+        name: "farm:sentry",
+        // Wrap as much of the request as possible.
+        enforce: "pre",
+        setup() {
+            // No SDK work here. `setup` can run in a build manager and again in a
+            // deployed runtime, so it has to stay deterministic.
+            return {
+                enabled,
+                options,
+                flushTimeoutMs,
+                sdk: options.sdk,
+                unsubscribe: undefined,
+            };
+        },
+        runtime: {
+            async start({ state }) {
+                if (!state.enabled)
+                    return;
+                try {
+                    state.sdk ??= await requireSentrySdk(state.options);
+                    // `registerSentry` usually initialized already, and `initSentryOnce`
+                    // checks for a live client so this does not replace it.
+                    if (state.sdk)
+                        initSentryOnce(state.sdk, state.options);
+                }
+                catch (error) {
+                    // Server startup must not fail because reporting could not start.
+                    console.error("[farm:sentry] failed to initialize, continuing without it:", error);
+                    return;
+                }
+                if (state.unsubscribe || !state.sdk)
+                    return;
+                state.unsubscribe = onFarmEvent((event) => {
+                    if (!isErrorEvent(event))
+                        return;
+                    if (!claimError(event.error))
+                        return;
+                    const route = errorEventRoute(event);
+                    const capture = () => state.sdk?.captureException(event.error);
+                    if (state.sdk?.withScope) {
+                        state.sdk.withScope((scope) => {
+                            scope.setTag("farm.event", event.type);
+                            if (route)
+                                scope.setTag("farm.route", route);
+                            capture();
+                        });
+                        return;
+                    }
+                    capture();
+                }, { unfiltered: true });
+            },
+            context({ request, route, state }) {
+                const empty = { ownsSpan: false, startedAt: Date.now(), ended: true };
+                if (!state.enabled || !state.sdk)
+                    return { sentry: empty };
+                const url = new URL(request.url);
+                const name = spanNameFor(request.method, route, url.pathname);
+                // Prefer the span the SDK's own HTTP instrumentation already opened.
+                // It is the active span, so automatic HTTP and database spans nest
+                // under it. Creating our own would leave those siblings of the request.
+                const active = state.sdk.getActiveSpan?.();
+                if (active) {
+                    const root = state.sdk.getRootSpan?.(active) ?? active;
+                    state.sdk.updateSpanName?.(root, name);
+                    if (route?.pattern)
+                        root.setAttribute?.("farm.route", route.pattern);
+                    return { sentry: { span: root, ownsSpan: false, startedAt: Date.now(), ended: false } };
+                }
+                // No automatic instrumentation attached, so record the request itself.
+                // `forceTransaction` is required, an orphan span is never sent.
+                const span = state.sdk.startInactiveSpan?.({
+                    name,
+                    op: "http.server",
+                    forceTransaction: true,
+                    attributes: {
+                        "http.request.method": request.method,
+                        "url.path": url.pathname,
+                        ...(route?.pattern ? { "farm.route": route.pattern } : {}),
+                    },
+                });
+                return { sentry: { span, ownsSpan: true, startedAt: Date.now(), ended: false } };
+            },
+            after({ ctx, response, state, waitUntil }) {
+                const sentry = ctx.sentry;
+                if (sentry && !sentry.ended) {
+                    sentry.span?.setStatus?.({
+                        code: response.status >= 500 ? SPAN_STATUS_ERROR : SPAN_STATUS_OK,
+                    });
+                    // Only end a span this plugin created. The SDK owns the lifecycle of
+                    // its own request span.
+                    if (sentry.ownsSpan)
+                        sentry.span?.end();
+                    sentry.ended = true;
+                }
+                flushWithinRequest(state, waitUntil);
+            },
+            error({ ctx, error, request, route, kind, state, waitUntil }) {
+                const sentry = ctx.sentry;
+                if (sentry && !sentry.ended) {
+                    sentry.span?.setStatus?.({ code: SPAN_STATUS_ERROR });
+                    if (sentry.ownsSpan)
+                        sentry.span?.end();
+                    sentry.ended = true;
+                }
+                if (!state.enabled || !state.sdk)
+                    return;
+                // The event stream may already have reported this one.
+                if (!claimError(error)) {
+                    flushWithinRequest(state, waitUntil);
+                    return;
+                }
+                const url = new URL(request.url);
+                const capture = () => state.sdk?.captureException(error);
+                if (state.sdk.withScope) {
+                    state.sdk.withScope((scope) => {
+                        scope.setTag("farm.kind", String(kind));
+                        if (route?.pattern)
+                            scope.setTag("farm.route", route.pattern);
+                        scope.setContext("request", {
+                            method: request.method,
+                            path: url.pathname,
+                        });
+                        capture();
+                    });
+                }
+                else {
+                    capture();
+                }
+                // A failing request never reaches `runtime.after`, so without this the
+                // exception is lost on hosts that stop the process straight after.
+                flushWithinRequest(state, waitUntil);
+            },
+            async close({ state }) {
+                state.unsubscribe?.();
+                state.unsubscribe = undefined;
+                if (!state.enabled)
+                    return;
+                await flushSentrySafely(state.sdk, state.flushTimeoutMs, "[farm:sentry] flush on shutdown failed:");
+            },
+        },
+        build: {
+            configure(buildConfig, { state }) {
+                if (!state.options.sourceMaps)
+                    return;
+                // Generating maps moves minification from Farm's esbuild pass to
+                // Nitro's terser, so the application needs `@rollup/plugin-terser`.
+                return { ...buildConfig, sourceMap: true };
+            },
+        },
+    });
+}
+/** Monitoring failures must never escape into the application lifecycle. */
+async function flushSentrySafely(sdk, timeoutMs, failureMessage) {
+    try {
+        await sdk?.flush?.(timeoutMs);
+    }
+    catch (error) {
+        console.error(failureMessage, error);
+    }
+}
+/** Flush inside the request for hosts that may not run `runtime.close`. */
+function flushWithinRequest(state, waitUntil) {
+    if (!state.enabled || !state.options.flushOnResponse)
+        return;
+    if (!state.sdk?.flush)
+        return;
+    // The host owns this promise once handed over, and Farm passes it through
+    // untouched when the host supplies waitUntil. An unhandled rejection there
+    // can terminate the process, so a failed flush has to stay contained.
+    waitUntil(flushSentrySafely(state.sdk, state.flushTimeoutMs, "[farm:sentry] flush failed:"));
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@farm.js/sentry",
+  "version": "0.1.0-beta.68",
+  "description": "Sentry error reporting and tracing for Farm.js",
+  "keywords": [
+    "error-tracking",
+    "farm.js",
+    "monitoring",
+    "observability",
+    "sentry",
+    "tracing"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/farming-labs/farm.js",
+    "directory": "packages/farm-sentry"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@farm.js/core": "0.1.0-beta.68"
+  },
+  "devDependencies": {
+    "@sentry/node": "^10.71.0",
+    "typescript": "^5.3.3",
+    "vitest": "^3.2.7"
+  },
+  "peerDependencies": {
+    "@sentry/node": ">=8.47.0"
+  },
+  "peerDependenciesMeta": {
+    "@sentry/node": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc",
+    "dev": "tsc --watch",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}