@ah-monica/cloudflare 0.2.1 → 0.4.0

package/README.md

@@ -1,8 +1,20 @@
 # @ah-monica/cloudflare
 
-Cloudflare WorkersからMONICAへ、捕捉した例外をbest effortで送るadapter。
-Node.js APIへ依存せず、Module Workerの`ExecutionContext.waitUntil()`へ渡せる
-Promiseを提供する。
+Cloudflare Workers から MONICA へ、捕捉した例外を送る adapter。
+Node.js API に依存しないので `nodejs_compat` フラグは要らない。
+
+共通の使い方・オプション・制約は [ルートの README](../README.md) にある。
+
+## インストール
+
+```bash
+npm install @ah-monica/cloudflare
+```
+
+## 初期化
+
+DSN には secret key（`msk_...`）を使い、Cloudflare の secret に保存する（`vars` には置かない）。
+staging と production では project・鍵・`environment` を分ける。
 
 ```ts
 import { createCloudflareClient } from "@ah-monica/cloudflare";
@@ -13,26 +25,72 @@ interface Env {
   MONICA_RELEASE?: string;
 }
 
+function createClient(env: Env) {
+  return createCloudflareClient({
+    dsn: env.MONICA_DSN,
+    environment: env.MONICA_ENVIRONMENT,
+    release: env.MONICA_RELEASE,
+    beforeSend(item) {
+      // どの値が個人情報かはアプリケーション固有。送ってよい値だけを残す。
+      delete item.user;
+      if (item.request) delete item.request.headers;
+      return item;
+    },
+  });
+}
+```
+
+`MONICA_RELEASE` には deploy する git の commit sha を入れる（例: `wrangler deploy --var MONICA_RELEASE:$(git rev-parse HEAD)`）。
+ブラウザ側の SDK にも同じ値を渡すと、Worker とブラウザの event が同じ release に揃う。
+
+DSN を Secrets Store に置く場合、binding の値は `get()` で非同期に読むので、client は
+request の入口で作る（[制約](#制約) のとおり request ごとに作ってよい）。`get()` は secret が
+無いと例外を投げるので、`undefined` に落として何も送らない client にする。
+
+```ts
+interface Env {
+  MONICA_DSN: SecretsStoreSecret;
+  MONICA_ENVIRONMENT: string;
+  MONICA_RELEASE?: string;
+}
+
 export default {
   async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
+    const monica = createCloudflareClient({
+      dsn: await env.MONICA_DSN.get().catch(() => undefined),
+      environment: env.MONICA_ENVIRONMENT,
+      release: env.MONICA_RELEASE,
+    });
+    ctx.waitUntil(monica.flush());
     try {
       return await handleRequest(request, env);
     } catch (error) {
-      const monica = createCloudflareClient({
-        dsn: env.MONICA_DSN,
-        environment: env.MONICA_ENVIRONMENT,
-        release: env.MONICA_RELEASE,
-        beforeSend(item) {
-          // PIIの定義はアプリケーション固有。送信可能な値だけを残す。
-          delete item.user;
-          if (item.request) delete item.request.headers;
-          return item;
-        },
-      });
+      monica.captureExceptionInBackground(ctx, error);
+      return new Response("Internal Server Error", { status: 500 });
+    }
+  },
+};
+```
+
+## 使い方
 
+request の入口で client を作り、`ctx.waitUntil(monica.flush())` を呼ぶ（[稼働確認](#稼働確認)）。
+
+`captureException()` は capture と flush の両方を終えてから解決する Promise を返す。
+handler の応答を待たせたくない場合は `captureExceptionInBackground(ctx, ...)` で
+`ExecutionContext.waitUntil()` に載せる。
+
+```ts
+export default {
+  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
+    const monica = createClient(env);
+    ctx.waitUntil(monica.flush());
+    try {
+      return await handleRequest(request, env);
+    } catch (error) {
       monica.captureExceptionInBackground(ctx, error, {
         tags: { operation: "handle-request" },
-        // URL pathにもPIIが入り得るため、利用側で安全と判断した値だけを渡す。
+        // URL の path にも個人情報が入り得るので、安全と判断した値だけを渡す。
         request: { method: request.method, url: new URL(request.url).origin },
       });
       return new Response("Internal Server Error", { status: 500 });
@@ -41,53 +99,60 @@ export default {
 };
 ```
 
-`captureException()`はcaptureとflushを完了するPromiseを返す。レスポンスを待たせたく
-ないHTTP handlerでは`captureExceptionInBackground(ctx, ...)`を使う。CronやQueueの
-handlerで送信完了を処理結果に含めたい場合は、直接`await`してよい。
+Cron や Queue の handler のように送信完了を処理結果に含めたい場合は、直接 `await` する。
 
 ```ts
+const monica = createClient(env);
 await monica.captureException(error, { tags: { trigger: "scheduled" } });
 ```
 
-## 送信が拒否されたとき
+`captureMessage()` も同じく capture と flush を終えてから解決するので、`flush()` を
+別途呼ぶ必要は無い。scope（`setUser` / `addBreadcrumb` / `withScope`）は持たず、
+文脈は capture の第 2 引数で渡す。
 
-`422`（envelope schema 不正）のとき、既定で`console.warn`へ1行出す（Workersのログに出る）。
+Worker の外側で起きた未捕捉例外まで集めたい場合は Tail Worker も検討する。この adapter は、
+アプリケーションが捕捉して業務上の文脈を選んで送る例外を対象にする。
 
-```
-monica: ingest rejected the envelope with 422 (invalid_envelope): 1 issue(s); $.items[0].request.method: Invalid type: Expected string
-```
+## 稼働確認
 
-出力先を変える場合は`onDiagnostic`を渡す。`null`を渡すと何も出さない。
-`flush()`の戻り値の`status` / `issues` / `error`からも取得できる。
+共通の仕組みは [ルートの README](../README.md#稼働確認) にある。
 
-`401`（鍵の失効・種別違い）を受けると、そのclientからは以後1回もPOSTしない。
-`flush()`の戻り値の`stopped: true`と次の1行で分かる。
+- isolate で最初の `flush()` / `captureException()` / `captureMessage()` の呼び出しが
+  `trigger: "start"` を 1 通送る。client を作っただけでは送らない。`dsn` と `environment` の組ごとに数える
+- request の入口で `ctx.waitUntil(monica.flush())` を呼ぶ。`waitUntil` が無いと handler の終了で送信が打ち切られる
+- Workers にはタイマーが無いので `trigger: "interval"` は送らない。isolate が作り直されるたびに `start` を送る
+- 状態は isolate のメモリに持ち、ストレージには書かない
 
-```
-monica: ingest rejected the envelope with 401 (invalid_key); no further envelopes will be sent
-```
+## オプション
 
-`413`（body上限超過）を受けると`items`を半分に割って送り直す。SDKは契約（gzip後
-1 MiB）を下回るサイズしか送らないので、返るのは経路上のproxyやgatewayが契約より
-低い上限を持っているとき。分割して受理されても`flush()`の戻り値の`status`は`413`に
-なり、次の1行をtransportにつき1回だけ出す。
+| option | 型 | default | 説明 |
+| --- | --- | --- | --- |
+| `dsn` | `string \| null` | なし | `https://msk_...@<ingest-host>`。未指定・空文字なら何も送らない |
+| `environment` | `string` | 必須 | 1〜128 文字 |
+| `release` | `string` | なし | item の `release` に載る |
+| `sampleRate` | `number` | `1` | 0〜1 |
+| `requestTimeoutMs` | `number` | `2000` | 1 回の HTTP request の上限 |
+| `flushTimeoutMs` | `number` | `2000` | `captureException` / `captureMessage` が内部で待つ flush の上限 |
+| `maxRetries` | `number` | `0` | `429` / `5xx` / network 障害の再送回数 |
+| `maxCauseDepth` | `number` | `10` | 辿る `cause` の段数 |
+| `maxStackFrames` | `number` | `200` | 送る stack frame 数 |
+| `onDiagnostic` | `(diagnostic) => void \| null` | `console.warn` に 1 行 | 拒否されたときの診断の受け取り先。`null` で無効 |
+| `beforeSend` | `(item, hint) => item \| null \| Promise<...>` | なし | `null` を返すと破棄 |
+| `fetch` | `typeof fetch` | `globalThis.fetch` | 送信に使う fetch |
 
-```
-monica: ingest rejected the envelope with 413 (unknown); splitting and resending. A size limit on the path may be below the 1 MiB (gzip) contract
-```
+## 送信結果と診断
 
-## PII方針
+拒否されたときは既定で `console.warn` に 1 行出る（Workers のログに出る。`422` / `401` / `413`）。
+`flush()` の戻り値の `status` / `issues` / `error` / `stopped` からも取れる。
+詳しくは [TROUBLESHOOTING.md](../TROUBLESHOOTING.md)。
 
-SDKは、例外message、stack、request、contextがPIIかどうかを推測せず、自動除去も
-しない。送信値の選択と`beforeSend`での除去は利用アプリケーションの責任。
-MONICAサーバの既知credentialフィルターは防御層であり、任意のPIIが除去される保証
-ではない。
+## 制約
 
-## API keyと環境
+- `captureExceptionInBackground` を使わず、`waitUntil()` にも載せずに handler を返すと、
+  送信は途中で打ち切られる。
+- client は request ごとに作ってよい。`401` で止まるのはその client だけなので、
+  鍵が失効しても次の request で再び 1 回 POST する。
 
-`dsn`にはCloudflare secretへ保存したsecret project key（`msk_...`）を使う。
-stagingとproductionではproject、key、`environment`を分離し、package versionは共通で
-よい。secretを`vars`、ソースコード、ログへ置かない。
+## ライセンス
 
-未捕捉例外をWorkerの外側から網羅的に収集する用途にはTail Workerも検討する。この
-adapterは、アプリケーションが捕捉し、業務contextを選んで送る例外を対象にする。
+[Apache-2.0](LICENSE)

package/dist/client.js

@@ -3,6 +3,10 @@ import { SDK_VERSION } from "./version.js";
 const DEFAULT_FLUSH_TIMEOUT_MS = 2_000;
 const DEFAULT_MAX_CAUSE_DEPTH = 10;
 const DEFAULT_MAX_STACK_FRAMES = 200;
+// client は request ごとに作られるので、start を送ったかは isolate に 1 つ持つ。
+// 判定の前に印を付けるので、並行する request でも isolate ごとに 1 回になる
+// （dsn と environment が違えば別に数える）
+const startedInIsolate = new Set();
 export function createCloudflareClient(options) {
     assertPositiveInteger("flushTimeoutMs", options.flushTimeoutMs);
     assertPositiveInteger("maxCauseDepth", options.maxCauseDepth);
@@ -10,6 +14,7 @@ export function createCloudflareClient(options) {
     const flushTimeoutMs = options.flushTimeoutMs ?? DEFAULT_FLUSH_TIMEOUT_MS;
     const maxCauseDepth = options.maxCauseDepth ?? DEFAULT_MAX_CAUSE_DEPTH;
     const maxStackFrames = options.maxStackFrames ?? DEFAULT_MAX_STACK_FRAMES;
+    const presenceKey = `${options.dsn ?? ""}\n${options.environment}`;
     const core = createCoreClient({
         transport: createFetchTransport({
             dsn: options.dsn,
@@ -24,12 +29,28 @@ export function createCloudflareClient(options) {
         sampleRate: options.sampleRate,
         beforeSend: options.beforeSend,
         sdk: { name: "@ah-monica/cloudflare", version: SDK_VERSION },
+        presence: { platform: "javascript" },
     });
+    /**
+     * Workers にはタイマーが無く、global scope では fetch できない。生成時ではなく最初の
+     * flush / capture の呼び出し（request の中）で start を送る。送信中の分は flush() が
+     * 待つので、それを waitUntil に載せれば handler の後まで生きる。
+     */
+    function startOnce() {
+        if (startedInIsolate.has(presenceKey))
+            return;
+        startedInIsolate.add(presenceKey);
+        void core.checkPresence("start");
+    }
+    function flush(timeoutMs) {
+        startOnce();
+        return core.flush(timeoutMs);
+    }
     async function captureAndFlush(input, hint) {
         try {
+            startOnce();
             const eventId = await core.capture(input, hint);
-            if (eventId === null)
-                return null;
+            // 捨てた event でも、送信中の start は待つ
             await core.flush(flushTimeoutMs);
             return eventId;
         }
@@ -75,7 +96,7 @@ export function createCloudflareClient(options) {
         captureException,
         captureMessage,
         captureExceptionInBackground,
-        flush: core.flush,
+        flush,
         close: core.close,
     };
 }

package/dist/types.d.ts

@@ -1,6 +1,7 @@
 import type { BeforeSend, FetchLike, FlushResult, MonicaBreadcrumb, MonicaLevel, MonicaRequest, MonicaUser, TransportDiagnosticHandler } from "@ah-monica/core";
 export interface CloudflareClientOptions {
-    dsn: string;
+    /** 未指定・空文字・空白だけなら何も送らない */
+    dsn?: string | null;
     environment: string;
     release?: string;
     sampleRate?: number;

package/dist/version.d.ts

@@ -1,2 +1,2 @@
 /** package.json の version と同じ値。bun run version X.Y.Z が書き換える */
-export declare const SDK_VERSION = "0.2.1";
+export declare const SDK_VERSION = "0.4.0";

package/dist/version.js

@@ -1,2 +1,2 @@
 /** package.json の version と同じ値。bun run version X.Y.Z が書き換える */
-export const SDK_VERSION = "0.2.1";
+export const SDK_VERSION = "0.4.0";

package/package.json

@@ -1,11 +1,13 @@
 {
   "name": "@ah-monica/cloudflare",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "description": "Cloudflare Workers adapter for sending application errors to MONICA",
   "license": "Apache-2.0",
   "type": "module",
   "sideEffects": false,
   "files": ["dist", "README.md"],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -30,7 +32,7 @@
     "directory": "cloudflare"
   },
   "dependencies": {
-    "@ah-monica/core": "0.2.1"
+    "@ah-monica/core": "0.4.0"
   },
   "devDependencies": {
     "@types/bun": "^1.2.21",