mirror of
https://github.com/Elysola/WebHooker.git
synced 2026-11-20 17:13:49 +00:00
feat(storage): Add delivery state store switch (D1 by default or KV) (#12)
This commit is contained in:
21 files changed
+655
-83
No files matched your search
@@ -31,6 +31,8 @@ ADMIN_USER_IDS=your-github-id
|
||||
# DEBUG_MODE=true # local development only: bypasses all admin authentication
|
||||
# ALLOW_SELF_SIGNUP=1 # non-admin GitHub users get a personal group on first login (default off)
|
||||
# AUDIT_RETENTION_DAYS=90 # audit log retention for the scheduled cleanup (default 90)
|
||||
# DELIVERY_STATE_STORE=kv # keep webhook delivery state in KV instead of D1: faster at the edge,
|
||||
# # but the free plan allows only ~1,000 KV writes/day (default d1)
|
||||
|
||||
# Server / public URL (OAuth callbacks + Telegram webhook sync)
|
||||
BASE_URL=http://localhost:8787
|
||||
|
||||
@@ -25,8 +25,9 @@ Core pipeline: GitHub Webhook → Worker (verify + filter + format) → Discord
|
||||
- Audit log: every admin operation (logins, group/route/member/invite changes) recorded in D1 `audit_logs`; pruned by the scheduled trigger after `AUDIT_RETENTION_DAYS` (default 90)
|
||||
- Group webhook log channel: optional `Group.logTarget` (Discord channel/thread or Telegram chat/topic) receives one summary message per webhook the group's routes dispatched (event, repo, delivery id, per route×target ✅/❌ outcome, green/red color); best-effort, not recorded in `send_logs`
|
||||
- Per-group forge branding: optional `Group.forgeSources` (a list of `{ host, type: "github" | "gitea", name? }` the group defines itself) labels each message's footer with the first entry whose type matches the event's provider and whose host matches the repository URL's hostname (GitHub matches `github.com`, so two Gitea instances can be `git1.example.com`/`git2.example.com`); the label is the entry's optional `name` (fallback: host); links are derived from the repo URL and footer icons use raster PNGs Discord renders (GitHub's `fluidicon.png`, Gitea's `/assets/img/favicon.png` — `.ico` favicons are silently ignored); Discord shows the footer icon + name, Telegram a linked name
|
||||
- Delivery queue: when the `QUEUE` binding is present, webhook ingress enqueues one message per event (not per target) to a Cloudflare Queue (`webhooker-delivery`) and answers `200` only after the send succeeded (`503` + dedup claim released otherwise); a Nitro `cloudflare:queue` plugin consumes batches, takes each delivery with a 5-minute lease (`acquireDelivery`, conditional UPSERT on `delivery_state`), dispatches, and retries when any target failed transiently (5xx/429/network/rate-limit/`FEISHU_TOKEN`, a crashed route, an unreadable ledger, a busy update lock) with exponential backoff (5s/30s/2m/10m) up to the queue `max_retries`, after which the DLQ (`webhooker-delivery-dlq`) marks the delivery dead. Targets that succeeded or failed permanently are recorded (`delivery-target:*` in the idempotency store, keyed by the group's instance, written right after each target and read with one range query) and skipped on retries, so retries never duplicate and one bad target never cancels the others; a permanent failure is remembered (`delivery-failed:*`) so the delivery ends `failed`, not `delivered`. A message whose storage calls fail is retried on its own (the batch is never failed whole); pre-upgrade `delivery-state:{provider}:{groupId}:*` rows are honored only for the group that owned the id (`legacyId`), never for the global endpoint. The consumer runs `max_batch_size: 3` with one per-batch budget (12 minutes, 20 sends — the D1 query / subrequest limits are per invocation): a message left unstarted is retried (copied instead on its last retry if it was never started), and one that made progress continues in a new message. Oversized payloads (queue message over 120,000 UTF-8 bytes) are parked in R2 (`webhooks/YYYY/MM/DD/*.json`, falling back to KV `queue:payload:*` without the R2 binding, 4-day TTL; kept when the queue send fails, since the queue may have accepted it; orphans pruned by `storage-prune`) and resolved by the consumer — a missing/corrupt parked payload never dispatches `{}`: the delivery stays `retrying` with a `PAYLOAD_MISSING` send-log entry asking for a redelivery; delivery state is tracked as the D1 `delivery_state` table (KV `delivery-state:*` fallback). Without the `QUEUE` binding, dispatch stays inline (existing behavior)
|
||||
- Delivery queue: when the `QUEUE` binding is present, webhook ingress enqueues one message per event (not per target) to a Cloudflare Queue (`webhooker-delivery`) and answers `200` only after the send succeeded (`503` + dedup claim released otherwise); a Nitro `cloudflare:queue` plugin consumes batches, takes each delivery with a 5-minute lease (`acquireDelivery`, conditional UPSERT on `delivery_state`), dispatches, and retries when any target failed transiently (5xx/429/network/rate-limit/`FEISHU_TOKEN`, a crashed route, an unreadable ledger, a busy update lock) with exponential backoff (5s/30s/2m/10m) up to the queue `max_retries`, after which the DLQ (`webhooker-delivery-dlq`) marks the delivery dead. Targets that succeeded or failed permanently are recorded (`delivery-target:*` in the idempotency store, keyed by the group's instance, written right after each target and read with one range query) and skipped on retries, so retries never duplicate and one bad target never cancels the others; a permanent failure is remembered (`delivery-failed:*`) so the delivery ends `failed`, not `delivered`. A message whose storage calls fail is retried on its own (the batch is never failed whole); pre-upgrade `delivery-state:{provider}:{groupId}:*` rows are honored only for the group that owned the id (`legacyId`), never for the global endpoint. The consumer runs `max_batch_size: 3` with one per-batch budget (12 minutes, 20 sends — the D1 query / subrequest limits are per invocation): a message left unstarted is retried (copied instead on its last retry if it was never started), and one that made progress continues in a new message. Oversized payloads (queue message over 120,000 UTF-8 bytes) are parked in R2 (`webhooks/YYYY/MM/DD/*.json`, falling back to KV `queue:payload:*` without the R2 binding, 4-day TTL; kept when the queue send fails, since the queue may have accepted it; orphans pruned by `storage-prune`) and resolved by the consumer — a missing/corrupt parked payload never dispatches `{}`: the delivery stays `retrying` with a `PAYLOAD_MISSING` send-log entry asking for a redelivery; delivery state is tracked as the D1 `delivery_state` table (KV `delivery-state:*` fallback, and the store itself when `DELIVERY_STATE_STORE=kv`). Without the `QUEUE` binding, dispatch stays inline (existing behavior)
|
||||
- Storage quotas: the design avoids KV write pressure (Workers Free KV allows ~1,000 writes/day) by keeping high-frequency ephemeral writes in D1 instead — webhook dedup and every other one-time claim (`dedup_keys`, atomic `ON CONFLICT` UPSERT via `idempotencyStore` with `has`/`claim`/`release`), delivery state and message tracking all use D1 rows via `canUseD1` (prepare+batch probe) with automatic KV fallback when D1 is unavailable or a table is missing (`isMissingTable`, unmigrated); other D1 errors propagate so one claim never splits across D1 and KV. D1 Free allows 100,000 rows written/day, so the per-event KV write cost drops to ~0; config is cached in memory only, with D1 authoritative. In-flight work shared across concurrent requests (setup, fallback marker, Feishu / App tokens, translations) goes through `sharedFlight`, which waits on another request's run only for a bounded time (a canceled request's promise may never settle)
|
||||
- Delivery state store (`DELIVERY_STATE_STORE`, `d1` default, `kv` opt-in via `server/lib/storage/state-store.ts`): the delivery hot path — ingress dedup claims and replay nonces (`deliveryClaimStore`), `delivery_state` leases, the `delivery-target:*`/`delivery-failed:*` ledger, `message_tracking` and the chain lock, and group-log summary claims — follows the switch; KV answers at the edge and keeps a live lease off a second consumer with its stamp, but allows ~1,000 writes/day on Workers Free and has no compare-and-set: a lease taken over after its holder vanished, or a claim raced, can still be duplicated. State written in KV mode is marked (`storage:kv-fallback`) and still honored after switching back to D1; the other direction does not read D1, so the D1 rows of the last days (claims and their confirmations, delivery states, the target ledger, message tracking for 30 days) are invisible — an already-finished event redelivered is sent again, already-sent targets are sent again, an in-progress edit chain posts a new message. Draining the queue only keeps in-flight deliveries from overlapping; those rows stay invisible either way, so carry the state over or accept the repeats. Configuration, logs, audit, metrics and the claims tied to a D1 transaction of their own (invites, sessions, tokens, bot interactions, group ids, installation provisioning) stay in D1 in both modes; an unrecognized value is logged and treated as `d1`
|
||||
- Filter DSL: a route's flat `filters` can be replaced by a nested `ast` (`all`/`any`/`not` nodes, `server/lib/events/filter-ast.ts`) that takes precedence when present; the `field` filter type reads any payload value by JSONPath (`path`, arrays expand so any element matches) and 12 comparison operators (`op`: `eq`/`ne`/`contains`/`startsWith`/`endsWith`/`regex`/`gt`/`gte`/`lt`/`lte`/`in`/`exists`) extend the legacy glob/regex/case-insensitive-exact semantics; named filter fragments (D1 `d1_fragments` via `server/lib/fragments.ts`, per-group) are editor-side templates inlined into the route's `ast` on insert — the matcher never resolves fragment references; the route editor (`RouteEditor.vue`) exposes a recursive AST builder (`FilterNodeEditor.vue`: plain selects for filter type/operator, an all/any segmented toggle, NOT toggle + delete pinned per condition), searchable multi-value / path inputs (`FilterCombobox.vue`) fed by a bilingual suggestion catalog (`app/utils/filter-catalog.ts`: GitHub events/actions from `@octokit/webhooks` plus Gitea extras, common payload paths and their known values, English keys searchable in either language) where custom values are allowed but rejected when the matcher could never match them (`validateFilterValue`), a live explanation and a stateless `POST /admin/api/test-match` dry-run
|
||||
- Local dev: wrangler + Miniflare
|
||||
|
||||
@@ -143,17 +144,21 @@ server/ # Nitro server
|
||||
│ └── richheader.ts # GET /api/richheader: Open Graph page for Telegram avatar link-preview card
|
||||
├── observability/ # delivery metrics aggregation
|
||||
│ └── metrics.ts # DeliveryMetrics + getDeliveryMetrics (SQL GROUP BY over send_logs in one D1 batch: totals, per platform/event/status, duration, attempts, recent failures)
|
||||
├── storage/ # storage primitives: canUseD1 probe, D1 config store (memory cache ≤60 s → D1), R2 payload store
|
||||
├── storage/ # storage primitives: canUseD1 probe, D1 config store (memory cache ≤60 s → D1), R2 payload store,
|
||||
│ # state-store.ts (DELIVERY_STATE_STORE: deliveryStateStore/deliveryStateUsesD1/deliveryClaimStore)
|
||||
│ ├── d1.ts # canUseD1(db) — prepare+batch probe for D1 availability (falls back to KV)
|
||||
│ ├── config-store.ts # ConfigStore: d1ConfigStore (per-group writes, CAS updateGroup, atomic rename/delete, one-time KV seed, one-time identity migration, unreadable-row isolation)
|
||||
│ │ # and kvConfigStore (no D1); `position` order when migrated; ConfigConflictError
|
||||
│ ├── state-store.ts # DELIVERY_STATE_STORE: deliveryStateStore (d1|kv), deliveryStateUsesD1, deliveryClaimStore (delivery-path idempotency store)
|
||||
│ └── payload.ts # PayloadStore backed by R2 (webhooks/YYYY/MM/DD/*.json), no-binding stub throws
|
||||
└── lib/ # shared infra
|
||||
├── i18n.ts # loadTranslations (KV i18n:{lang} overrides), t() with param interpolation
|
||||
├── idempotency.ts # IdempotencyStore (has/claim/release) + kv/d1 stores (D1 atomic UPSERT, KV fallback only for a missing table) + tenantScope (`@global`) + deliveryKey
|
||||
├── idempotency.ts # IdempotencyStore (has/claim/release) + kv/d1 stores (D1 atomic UPSERT, KV fallback only for a missing table) + tenantScope (`@global`) + deliveryKey;
|
||||
│ # the D1 argument is optional (undefined = KV only, used by the delivery store switch)
|
||||
├── correlation.ts # newCorrelationId() — per-request/delivery correlation id for logs + responses
|
||||
├── shared-flight.ts # sharedFlight: in-flight work shared by concurrent requests, waited on for a bounded time
|
||||
├── message-tracker.ts # MessageTracker (versioned { messageId, version } entries, legacy bare ids read as version 0) + kv/d1 trackers with KV fallback
|
||||
├── message-tracker.ts # MessageTracker (versioned { messageId, version } entries, legacy bare ids read as version 0) + kv/d1 trackers with KV fallback;
|
||||
│ # messageTracker/chainLock take an explicit useD1 (the delivery store switch)
|
||||
├── send-log.ts # SendRecord, recordSend/getSendLog/getSendLogById/getSendLogByDelivery/getFailedSendLog (D1 send_logs)
|
||||
├── send-log-batch.ts # recordSendBatch (D1 batch INSERT for send_logs)
|
||||
├── audit.ts # recordAudit/getAuditLog/pruneAuditLogs (D1 audit_logs, best-effort writes)
|
||||
@@ -161,7 +166,7 @@ server/ # Nitro server
|
||||
└── locales/ # en.ts, zh.ts translation dictionaries
|
||||
|
||||
tests/ # bun test unit tests (webhook, formatter, discord, telegram, admin, groups, invites, audit, send-log, token-store,
|
||||
# data-integrity, ingress-dispatch, discord-interactions, telegram-webhook, ...)
|
||||
# data-integrity, ingress-dispatch, discord-interactions, telegram-webhook, delivery-state-store, ...)
|
||||
tests/d1-sqlite.ts # in-memory SQLite behind the D1 API (all migrations applied, FKs on) + a Map-backed KV, for real-SQL tests
|
||||
tests/fixtures/ # provider payload fixtures (github/gitea/custom) feeding provider + formatter tests
|
||||
tests/__snapshots__/ # formatter snapshot golden files (toMatchSnapshot)
|
||||
@@ -284,6 +289,7 @@ Rule: no functional change ships without its documentation; docs and code must n
|
||||
- **Queue**: optional `QUEUE` producer binding plus consumers `webhooker-delivery` and its DLQ `webhooker-delivery-dlq` (declared in `wrangler.jsonc`); when absent, webhook dispatch stays inline
|
||||
- **R2**: optional `PAYLOAD` binding (bucket `webhooker-payloads`) for oversized queue payloads; without it, oversized payloads fall back to KV `queue:payload:*`
|
||||
- **Access control**: `ADMIN_USER_IDS` (super admins), `DEBUG_MODE=true` (local-only authentication bypass), `ALLOW_SELF_SIGNUP` (optional personal group on first login), `AUDIT_RETENTION_DAYS` (default 90) — all plain env vars, not secrets
|
||||
- **Delivery state store**: `DELIVERY_STATE_STORE` (`d1` default; `kv` moves the delivery hot path — ingress dedup and replay nonces, delivery leases and state, the target ledger, message tracking and chain locks, group-log summary claims — to KV) — a plain env var, not a secret
|
||||
- **Discord**: `DISCORD_PUBLIC_KEY` (Interactions Endpoint signature verification, from Discord Developer Portal) and `DISCORD_APPLICATION_ID` (optional, auto-resolved via `GET /oauth2/applications/@me` when omitted) are required for interactions
|
||||
- **Telegram**: `TELEGRAM_TOKEN` (Bot API token from BotFather) required for Telegram routes; `TELEGRAM_WEBHOOK_SECRET` (optional secret token for `POST /telegram/webhook` verification — derived from `TELEGRAM_TOKEN` when unset, never disabled); avatars are sent as a link-preview card via the built-in `GET /api/richheader` (overridable with `TELEGRAM_RICH_HEADER_HOST`)
|
||||
- **Feishu**: `FEISHU_APP_ID` / `FEISHU_APP_SECRET` for sending; inbound commands/buttons need `FEISHU_ENCRYPT_KEY` and/or `FEISHU_VERIFICATION_TOKEN`
|
||||
|
||||
@@ -19,7 +19,7 @@ GitHub / Gitea webhook → Discord / Telegram / Feishu dispatcher. Receives webh
|
||||
- **Web UI config console** (`/admin`) — Elysola UI-based console with centered route/group dialogs; manage routes and groups with GitHub OAuth + admin whitelist, view send logs
|
||||
- **Discord Interactions Endpoint** (Ed25519-verified) for `/gh` slash commands, message context-menu commands, PR merge/close buttons, and comment modals
|
||||
- **Telegram `/gh` commands** (login/logout/comment/merge/close) via the Telegram webhook, with avatar link-preview cards
|
||||
- Cloudflare D1 for config (routes/groups), send logs, platform account links, dedup, delivery state and message tracking + KV for ephemeral state/cache/security tokens, + optional R2 for oversized payloads
|
||||
- Cloudflare D1 for config (routes/groups), send logs, platform account links, dedup, delivery state and message tracking (or KV for the delivery state, with `DELIVERY_STATE_STORE=kv`) + KV for ephemeral state/cache/security tokens, + optional R2 for oversized payloads
|
||||
- **Async delivery via Cloudflare Queues** — when the `QUEUE` binding is present, verified webhooks are enqueued to `webhooker-delivery` and dispatched by a consumer with exponential retry backoff (5s/30s/2m/10m) and a dead-letter queue (`webhooker-delivery-dlq`); oversized payloads are parked in R2 (`PAYLOAD` binding, falling back to KV `queue:payload:*`). Without the binding, dispatch stays inline
|
||||
- Graceful degradation (webhook-only mode if Discord unavailable)
|
||||
|
||||
@@ -39,7 +39,7 @@ GitHub Webhook → Cloudflare Worker (Nuxt 4 / Nitro)
|
||||
|
||||
- **Cloudflare Worker** — HTTP ingress, signature verification, routing, platform dispatch
|
||||
- **Interactions Endpoint** — HTTPS callback (no Discord Gateway connection, no Durable Object); the bot stays offline and commands are registered via the API
|
||||
- **KV** — cache + ephemeral state: token storage (`token:{userId}`), OAuth state (`state:{hex}`), admin sessions (`session:{id}`), invites, delivery dedup/state/message-tracking **fallback** (`delivery:*`, `delivery-state:*`, `msg:*` used only when D1 is unavailable) and message-update locks (`msg:lock:*`)
|
||||
- **KV** — cache + ephemeral state: token storage (`token:{userId}`), OAuth state (`state:{hex}`), admin sessions (`session:{id}`), invites, delivery dedup/state/message-tracking (`delivery:*`, `delivery-state:*`, `msg:*`, used when D1 is unavailable or `DELIVERY_STATE_STORE=kv`) and message-update locks (`msg:lock:*`)
|
||||
- **D1** — source of truth for routes/groups (`d1_routes`/`d1_groups`, including each group's webhook secret), named filter fragments (`d1_fragments`), send logs (`send_logs`), audit logs (`audit_logs`), dedup (`dedup_keys`), delivery state (`delivery_state`), message-update tracking (`message_tracking`), Discord↔GitHub links (`discord_links`), Telegram↔GitHub links (`telegram_links`)
|
||||
- **Queue** — async delivery when `QUEUE` is bound: `webhooker-delivery` (exponential retry) + DLQ `webhooker-delivery-dlq`; oversized payloads parked in R2 (`PAYLOAD` binding, `webhooks/YYYY/MM/DD/*.json`, falling back to KV `queue:payload:*`)
|
||||
|
||||
@@ -79,6 +79,7 @@ bun run cf:dev # Build, then serve the worker locally with wrangler dev
|
||||
| `DEBUG_MODE` | Local development only: set to exact `true` to bypass all `/admin` authentication |
|
||||
| `ALLOW_SELF_SIGNUP` | `1` to give access-less GitHub users a personal group on first login (default off) |
|
||||
| `AUDIT_RETENTION_DAYS` | Audit-log retention in days for the scheduled cleanup (default 90) |
|
||||
| `DELIVERY_STATE_STORE` | `kv` keeps webhook delivery state (dedup, leases, target ledger, message tracking) in KV instead of D1 (default `d1`) |
|
||||
| `NUXT_PUBLIC_DOCS_URL` | Optional docs site URL used by the landing page |
|
||||
| `NUXT_PUBLIC_REPO_URL` | Optional GitHub repo URL used by the landing page |
|
||||
| `NUXT_PUBLIC_LEGAL_CONTACT` | Optional contact shown on `/terms` and `/privacy` |
|
||||
|
||||
+4
-3
@@ -19,7 +19,7 @@ GitHub / Gitea webhook → Discord / Telegram / 飞书 分发服务。通过 Clo
|
||||
- **Web 配置控制台**(`/admin`)— 基于 Elysola UI,使用居中路由/分组对话框;通过 GitHub OAuth + 管理员白名单管理路由与分组、查看发送日志
|
||||
- **Discord Interactions Endpoint**(Ed25519 验签)支持 `/gh` 斜杠命令、消息右键菜单命令、PR 合并/关闭按钮与评论 modal
|
||||
- **Telegram `/gh` 命令**(login/logout/comment/merge/close),通过 Telegram webhook 接收,头像以链接预览卡片呈现
|
||||
- Cloudflare D1 存储配置(路由/分组)、发送日志、平台账号绑定、去重、投递状态与消息更新追踪 + KV 存储临时状态/缓存/安全令牌 + 可选 R2 存储超大负载
|
||||
- Cloudflare D1 存储配置(路由/分组)、发送日志、平台账号绑定、去重、投递状态与消息更新追踪(投递状态可用 `DELIVERY_STATE_STORE=kv` 存于 KV)+ KV 存储临时状态/缓存/安全令牌 + 可选 R2 存储超大负载
|
||||
- **Cloudflare Queues 异步投递** —— 绑定 `QUEUE` 时,已验签的 webhook 会入队到 `webhooker-delivery`,由消费者分发,带指数退避重试(5s/30s/2m/10m)与死信队列(`webhooker-delivery-dlq`);超大负载暂存于 R2(`PAYLOAD` 绑定,回退 KV `queue:payload:*`)。未绑定则保持同步分发
|
||||
- 优雅降级(Discord 不可用时仅 webhook 模式)
|
||||
|
||||
@@ -39,7 +39,7 @@ GitHub Webhook → Cloudflare Worker (Nuxt 4 / Nitro)
|
||||
|
||||
- **Cloudflare Worker** — HTTP 入口、签名验证、路由分发
|
||||
- **Interactions Endpoint** — HTTPS 回调(无 Discord Gateway 连接、无 Durable Object);bot 保持离线,命令通过 API 注册
|
||||
- **KV** — 缓存 + 临时状态:Token 存储(`token:{userId}`)、OAuth state(`state:{hex}`)、管理员会话(`session:{id}`)、邀请、投递去重/投递状态/消息更新追踪的回退(`delivery:*`、`delivery-state:*`、`msg:*` 仅在 D1 不可用时使用)与消息更新锁(`msg:lock:*`)
|
||||
- **KV** — 缓存 + 临时状态:Token 存储(`token:{userId}`)、OAuth state(`state:{hex}`)、管理员会话(`session:{id}`)、邀请、投递去重/投递状态/消息更新追踪(`delivery:*`、`delivery-state:*`、`msg:*`,在 D1 不可用或 `DELIVERY_STATE_STORE=kv` 时使用)与消息更新锁(`msg:lock:*`)
|
||||
- **D1** — 路由/分组(`d1_routes`/`d1_groups`,含各分组的 webhook 密钥)、命名过滤器片段(`d1_fragments`)、发送日志(`send_logs`)、审计日志(`audit_logs`)、去重(`dedup_keys`)、投递状态(`delivery_state`)、消息更新追踪(`message_tracking`)、Discord↔GitHub 绑定(`discord_links`)、Telegram↔GitHub 绑定(`telegram_links`)
|
||||
- **Queue** — 绑定 `QUEUE` 时异步投递:`webhooker-delivery`(指数退避重试)+ 死信队列 `webhooker-delivery-dlq`;超大负载暂存于 R2(`PAYLOAD` 绑定,`webhooks/YYYY/MM/DD/*.json`,回退 KV `queue:payload:*`)
|
||||
|
||||
@@ -57,7 +57,7 @@ bun run cf:dev # 先构建,再用 wrangler dev 在本地运行 worker
|
||||
### 密钥(本地用 `.dev.vars`,生产用 Worker Secrets)
|
||||
|
||||
| 变量 | 说明 |
|
||||
| --------------------------- | ----------------------------------------------------------------------------- |
|
||||
| --------------------------- | --------------------------------------------------------------------------------------------- |
|
||||
| `GITHUB_WEBHOOK_SECRET` | GitHub webhook 密钥 |
|
||||
| `GITEA_WEBHOOK_SECRET` | Gitea webhook 密钥(仅接收 Gitea webhook 时需要) |
|
||||
| `GITHUB_APP_ID` | GitHub App ID——App 安装流程需要它核实安装者(没有时只有超级管理员能绑定安装) |
|
||||
@@ -79,6 +79,7 @@ bun run cf:dev # 先构建,再用 wrangler dev 在本地运行 worker
|
||||
| `DEBUG_MODE` | 仅本地开发:精确设为 `true` 时跳过全部 `/admin` 身份验证 |
|
||||
| `ALLOW_SELF_SIGNUP` | 设为 `1` 时,无权限的 GitHub 用户首次登录自动获得个人分组(默认关闭) |
|
||||
| `AUDIT_RETENTION_DAYS` | 定时清理时审计日志的保留天数(默认 90) |
|
||||
| `DELIVERY_STATE_STORE` | 设为 `kv` 时 webhook 投递状态(去重、租约、目标台账、消息追踪)存放于 KV 而非 D1(默认 `d1`) |
|
||||
| `NUXT_PUBLIC_DOCS_URL` | 可选;落地页使用的文档站点 URL |
|
||||
| `NUXT_PUBLIC_REPO_URL` | 可选;落地页使用的 GitHub 仓库 URL |
|
||||
| `NUXT_PUBLIC_LEGAL_CONTACT` | 可选;`/terms` 与 `/privacy` 页面展示的联系方式 |
|
||||
|
||||
@@ -46,7 +46,7 @@ WebHooker requires several secrets to function. For local development, store the
|
||||
### Optional Secrets
|
||||
|
||||
| Variable | Description | Default |
|
||||
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- |
|
||||
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- |
|
||||
| `DISCORD_PUBLIC_KEY` | Discord application public key (Developer Portal) — required for interactions | Unset → interactions return `401` |
|
||||
| `DISCORD_APPLICATION_ID` | Discord application id; auto-resolved when omitted | Auto-resolved |
|
||||
| `TELEGRAM_WEBHOOK_SECRET` | Secret token for `POST /telegram/webhook` verification (X-Telegram-Bot-Api-Secret-Token) | Derived from `TELEGRAM_TOKEN` |
|
||||
@@ -58,6 +58,7 @@ WebHooker requires several secrets to function. For local development, store the
|
||||
| `DEBUG_MODE` | Local development only: exact `true` bypasses all `/admin` authentication and grants full access | Disabled |
|
||||
| `ALLOW_SELF_SIGNUP` | When enabled (`1`/`true`), GitHub users without any group access get an isolated personal group on first login instead of `403` | Disabled |
|
||||
| `AUDIT_RETENTION_DAYS` | Audit-log retention in days for the scheduled cleanup | `90` |
|
||||
| `DELIVERY_STATE_STORE` | Where webhook delivery state lives: `d1` (default) or `kv`. KV answers at the edge but the free plan allows only ~1,000 writes/day — see [Storage decisions](./storage#storage-decisions) | `d1` |
|
||||
| `NUXT_PUBLIC_DOCS_URL` | Docs site URL used by the landing page (client-side runtime config) | Landing page defaults |
|
||||
| `NUXT_PUBLIC_REPO_URL` | GitHub repo URL used by the landing page | Landing page defaults |
|
||||
| `NUXT_PUBLIC_LEGAL_CONTACT` | Contact shown on `/terms` and `/privacy` | Unset → placeholder text |
|
||||
|
||||
+1
-1
@@ -38,4 +38,4 @@ No — the worker requires the KV and D1 bindings declared in `wrangler.jsonc` a
|
||||
|
||||
## Where is data stored?
|
||||
|
||||
Configuration lives in D1 (`d1_routes`/`d1_groups`, cached in memory for at most 60 seconds); webhook dedup, delivery state and message-update tracking also live in D1 with KV fallback; send/audit logs and platform↔GitHub links live in D1. R2 optionally parks oversized payloads. See [Storage Layout](./storage#storage-decisions).
|
||||
Configuration lives in D1 (`d1_routes`/`d1_groups`, cached in memory for at most 60 seconds); webhook dedup, delivery state and message-update tracking live in D1 too, with KV fallback and an opt-in `DELIVERY_STATE_STORE=kv`; send/audit logs and platform↔GitHub links live in D1. R2 optionally parks oversized payloads. See [Storage Layout](./storage#storage-decisions).
|
||||
@@ -22,7 +22,7 @@ GitHub / Gitea Webhook → Cloudflare Worker (Nuxt 4 / Nitro)
|
||||
| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| **Cloudflare Worker** | HTTP ingress, signature verification, delivery dedup, event parsing, route matching, platform dispatch |
|
||||
| **Interactions Endpoint** | Verifies Ed25519 signatures and handles `/gh` interactions (slash commands, context-menu commands, buttons, modals) |
|
||||
| **KV** | Token storage (`token:{userId}`), OAuth state (`state:{hex}`), admin sessions, invites, delivery dedup/state/message-tracking fallback when D1 is unavailable (`delivery:*`, `delivery-state:*`, `msg:*`), message-update locks (`msg:lock:*`) |
|
||||
| **KV** | Token storage (`token:{userId}`), OAuth state (`state:{hex}`), admin sessions, invites, delivery dedup/state/message-tracking when D1 is unavailable or `DELIVERY_STATE_STORE=kv` (`delivery:*`, `delivery-state:*`, `msg:*`), message-update locks (`msg:lock:*`) |
|
||||
| **D1** | Routes/groups (`d1_routes`/`d1_groups`), send logs (`send_logs`), audit logs (`audit_logs`), dedup (`dedup_keys`), delivery state (`delivery_state`), message tracking (`message_tracking`), Discord↔GitHub links (`discord_links`), Telegram↔GitHub links (`telegram_links`), with R2 optionally parking oversized payloads |
|
||||
|
||||
### Data Flow
|
||||
|
||||
+10
-9
@@ -2,10 +2,10 @@
|
||||
|
||||
## KV Storage Layout
|
||||
|
||||
KV keeps only cache data and short-lived/ephemeral state. High-frequency writes (webhook dedup, delivery state, message tracking) live in D1 and only fall back to KV when D1 is unavailable or not yet migrated (see [Storage decisions](./storage#storage-decisions)).
|
||||
KV keeps only cache data and short-lived/ephemeral state. High-frequency writes (webhook dedup, delivery state, message tracking) live in D1 and only fall back to KV when D1 is unavailable or not yet migrated (see [Storage decisions](./storage#storage-decisions)). Setting `DELIVERY_STATE_STORE=kv` keeps that delivery state in KV instead.
|
||||
|
||||
| Key Pattern | Value | TTL |
|
||||
| ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
|
||||
| ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
|
||||
| `config:routes` / `config:groups` | Legacy (pre-D1) configuration, read once to seed empty D1 tables | Permanent |
|
||||
| `config:d1-seeded` | Marks that D1 was seeded (an emptied D1 is never re-seeded) | Permanent |
|
||||
| `session:{id}` | Admin session `{ userId, login, loginTrusted }` | 1 day |
|
||||
@@ -17,14 +17,14 @@ KV keeps only cache data and short-lived/ephemeral state. High-frequency writes
|
||||
| `invite:group:{id}` | Token index per group (keeps invite listing consistent) | 7 days |
|
||||
| `invite:by-group:{id}:{token}` / `invite:by-instance:{instance}:{token}` | Per-invite listing markers (by group id and by the issuing group's instance), so concurrent creates or a half-finished rename never hide an invite | Invite lifetime |
|
||||
| `login-owner:{login}` | GitHub user id of the first account seen with this login; another account using the login later is matched by user id only | Permanent |
|
||||
| `delivery:{provider}:{scope}:{id}` | Webhook delivery dedup fallback (D1 `dedup_keys` is primary); `scope` is `@global` for the global endpoint or `@i:{instance}` (the receiving group's immutable instance) for a group endpoint | 2–10 minutes |
|
||||
| `delivery-state:{provider}:{scope}:{id}` | Queue delivery state fallback (D1 `delivery_state` is primary) | 7 days |
|
||||
| `delivery:{provider}:{scope}:{id}` | Webhook delivery dedup (D1 `dedup_keys` by default; used while `DELIVERY_STATE_STORE=kv` or when D1 is unavailable); `scope` is `@global` for the global endpoint or `@i:{instance}` (the receiving group's immutable instance) for a group endpoint | 2–10 minutes |
|
||||
| `delivery-state:{provider}:{scope}:{id}` | Queue delivery state (D1 `delivery_state` by default; used while `DELIVERY_STATE_STORE=kv` or when D1 is unavailable) | 7 days |
|
||||
| `queue:payload:{provider}:{scope}:{id}:{uuid}` | Oversized webhook payload parked for the queue consumer when there is no R2 binding (one key per enqueue) | 4 days |
|
||||
| `tenant:{groupId}` / `tenant:i:{instance}` | Legacy per-group webhook secrets, read only for groups whose secret was never moved into their D1 row; removed on rotate/delete | Permanent |
|
||||
| `group:renamed:{oldId}` | KV-only deployments: where a renamed group went (with D1 this alias is a `dedup_keys` row written in the rename transaction) | 4 days |
|
||||
| `msg:{chain}:{platform}:{target}` | Message tracking fallback (D1 `message_tracking` is primary) | 30 days |
|
||||
| `msg:lock:…` | Lock serializing updates of one message chain when D1 is unavailable (with D1 it is a `dedup_keys` row) | 240 seconds |
|
||||
| `storage:kv-fallback` | Marks that state was written to KV while a D1 table was missing; while it lives, D1 misses are also looked up in KV | 35 days |
|
||||
| `msg:{chain}:{platform}:{target}` | Message tracking (D1 `message_tracking` by default; used while `DELIVERY_STATE_STORE=kv` or when D1 is unavailable) | 30 days |
|
||||
| `msg:lock:…` | Lock serializing updates of one message chain (D1 `dedup_keys` by default; used while `DELIVERY_STATE_STORE=kv` or when D1 is unavailable) | 240 seconds |
|
||||
| `storage:kv-fallback` | Marks that state was written to KV instead of D1 (missing table, or `DELIVERY_STATE_STORE=kv`); while it lives, D1 misses are also looked up in KV | 35 days |
|
||||
| `cmd:guilds:{appId}` | Per Discord application: each guild's registered command hash and the sync cursor | Permanent |
|
||||
| `cmd:registered:global:{appId}` | Hash of the commands last registered globally (re-registered when it changes, and daily) | 1 day |
|
||||
| `config:discord-app-id:{tokenHash}` | Discord application id resolved for a bot token | Permanent |
|
||||
@@ -45,7 +45,7 @@ The D1 database (`DB` binding, database `webhooker`) holds the source of truth f
|
||||
| `send_logs` | One row per dispatch attempt (route id, event, target, ok/error, duration, error code, detail) |
|
||||
| `audit_logs` | One row per admin operation (login/logout, group/route/member/invite changes) |
|
||||
| `dedup_keys` | Atomic one-time claims and records (`INSERT ... ON CONFLICT` UPSERT, key + expiry): webhook delivery dedup and its confirmations (`accepted:*`), custom-webhook nonces (`nonce:{secret-scope}:{nonce}`), single-use and revoked invites (`invite-used:*`, `invite-revoked:*`), bot command/event dedup (`bot:{platform}:…`), revoked sessions and tokens and each user's live token (`session-revoked:*`, `token-revoked:*`, `token-live:*`), used account-link confirmations (`link-used:*`), retired group ids (`group-retired:*`) and rename aliases (`group-alias:*`), installation provisioning records (`installation-provisioned:*`, `installation-bound:*`), route × targets already finished or failed for good by a queued delivery (`delivery-target:*`, `delivery-failed:*`), group log summaries already sent, message-chain locks (`msg:lock:*`) and one-time setup markers |
|
||||
| `delivery_state` | Queue delivery state (`pending`/`processing`/`delivered`/`retrying`/`failed`/`dead`); taking a delivery is a conditional UPSERT (a lease), so two consumers never dispatch it at once |
|
||||
| `delivery_state` | Queue delivery state (`pending`/`processing`/`delivered`/`retrying`/`failed`/`dead`); taking a delivery is a conditional UPSERT (a lease), so two consumers never dispatch it at once in D1 mode (with `DELIVERY_STATE_STORE=kv` the state lives in KV, where a fresh lease stamp plays the same role without fencing) |
|
||||
| `message_tracking` | Message tracking for in-place updates (`event_id` + `target_id` → message id and the version it shows); chains are keyed by the group's instance, so a group created later under the same id never edits its messages |
|
||||
| `d1_fragments` | Named filter fragments per group |
|
||||
| `feishu_links` | Maps `feishu_user_id` → `github_user_id` for `/gh` Feishu commands |
|
||||
@@ -69,9 +69,10 @@ A payload is parked when the queue message would exceed 120,000 bytes (UTF-8). W
|
||||
## Storage Decisions
|
||||
|
||||
- **D1 is authoritative** for config and delivery metadata; KV holds only caches and short-lived state.
|
||||
- The `canUseD1` probe (`server/lib/storage/d1.ts`, checks for `prepare` + `batch`) gates every D1 store. The high-frequency stores (dedup and other one-time claims, delivery state, message tracking) also fall back to KV while their D1 table does not exist yet (an unmigrated database). Any other D1 failure propagates — the request answers with an error and the sender or queue retries — because switching stores per call would split a claim between D1 and KV.
|
||||
- The `canUseD1` probe (`server/lib/storage/d1.ts`, checks for `prepare` + `batch`) gates every D1 store except the delivery ones, which follow `DELIVERY_STATE_STORE` (`server/lib/storage/state-store.ts`). The high-frequency stores (dedup and other one-time claims, delivery state, message tracking) also fall back to KV while their D1 table does not exist yet (an unmigrated database). Any other D1 failure propagates — the request answers with an error and the sender or queue retries — because switching stores per call would split a claim between D1 and KV.
|
||||
- When D1 configuration reads fail, the request answers with an error and the sender or queue retries; there is no KV copy of the configuration, and dispatch never treats unreadable configuration as empty. A stored route or group row that cannot be read only makes its own group's deliveries fail visibly (and retry) — see [Routes → Unreadable routes](./routes#unreadable-routes).
|
||||
- Configuration writes never fall back: with a D1 binding, a failed write is reported as an error instead of being parked in KV. Writes are per group (one row, or one group's routes/fragments in one transaction) with compare-and-swap on the group row, so concurrent edits of different groups never overwrite each other. Reads for access checks, read-modify-write paths, webhook ingress and the queue consumer bypass every cache (a revoked route or target stops at once); other reads are cached in memory for at most 60 seconds per isolate.
|
||||
- Legacy KV configuration is copied into D1 once, only while both D1 tables are empty, and never over existing rows; a marker prevents an emptied configuration from being resurrected.
|
||||
- This keeps per-event KV writes near zero on the Workers Free plan (1,000 writes/day): dedup, delivery state and message tracking now write D1 rows instead (D1 Free allows 100,000 rows written/day).
|
||||
- `DELIVERY_STATE_STORE=kv` moves the delivery hot path back to KV: ingress dedup and replay nonces, delivery state and leases, the finished-target ledger and permanent-failure markers, message tracking and chain locks, and group-log summary claims. It trades D1's generous write quota for edge latency; on the free plan KV allows about 1,000 writes/day, so low-volume deployments fit and busy ones do not. A fresh lease stamp still keeps a second consumer off a delivery that is being sent, but KV has no compare-and-set: a lease taken over after its holder vanished, or a raced claim, can still be duplicated. Claims and states written in KV mode are marked (`storage:kv-fallback`) and still honored after switching back to D1; the other direction does not read D1, so the D1 rows of the last days (claims and their confirmations, delivery states, the finished-target ledger, message tracking for 30 days) are invisible — an already-finished event redelivered is sent, already-sent targets are sent, and an in-progress edit chain posts a new message. Draining the queue only keeps in-flight deliveries from overlapping; those rows stay invisible either way, so carry the state over (migrate it, or accept the repeats). While the marker lives, the D1 claims that stay in D1 (invites, sessions, tokens, bot interactions, group ids) also read KV once per claim to honor copies written in KV mode; KV reads are far cheaper than writes. Everything else — configuration, send logs, audit, metrics, and the claims tied to a D1 transaction of their own (invites, sessions, tokens, bot interactions, group ids, installation provisioning) — stays in D1 in either mode. An unrecognized value is reported and treated as `d1`.
|
||||
- R2's free tier (10 GB-month storage, 1M Class A ops/month) comfortably absorbs payload parking without touching the KV write quota.
|
||||
@@ -44,7 +44,7 @@ WebHooker 的运行需要若干密钥。本地开发时放入 `.dev.vars`,生
|
||||
### 可选密钥
|
||||
|
||||
| 变量 | 说明 | 默认值 |
|
||||
| --------------------------- | --------------------------------------------------------------------------------------------------------- | ------------------------ |
|
||||
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
|
||||
| `DISCORD_PUBLIC_KEY` | Discord 应用的公钥(开发者门户获取),交互功能必需 | 未设置时交互返回 401 |
|
||||
| `DISCORD_APPLICATION_ID` | Discord 应用 ID;省略时自动获取 | 自动获取 |
|
||||
| `TELEGRAM_WEBHOOK_SECRET` | `POST /telegram/webhook` 验签密钥(X-Telegram-Bot-Api-Secret-Token) | 由 `TELEGRAM_TOKEN` 派生 |
|
||||
@@ -56,6 +56,7 @@ WebHooker 的运行需要若干密钥。本地开发时放入 `.dev.vars`,生
|
||||
| `DEBUG_MODE` | 仅本地开发:精确设为 `true` 时跳过全部 `/admin` 身份验证并授予完整权限 | 关闭 |
|
||||
| `ALLOW_SELF_SIGNUP` | 开启(`1`/`true`)后,没有任何分组权限的 GitHub 用户首次登录会自动获得隔离的个人分组而非 403 | 关闭 |
|
||||
| `AUDIT_RETENTION_DAYS` | 定时清理时审计日志的保留天数 | `90` |
|
||||
| `DELIVERY_STATE_STORE` | webhook 投递状态存放位置:`d1`(默认)或 `kv`。KV 在边缘响应,但免费版每日仅约 1000 次写——见[存储决策](./storage#存储决策) | `d1` |
|
||||
| `NUXT_PUBLIC_DOCS_URL` | 落地页使用的文档站 URL(客户端运行时配置) | 落地页默认值 |
|
||||
| `NUXT_PUBLIC_REPO_URL` | 落地页使用的 GitHub 仓库 URL | 落地页默认值 |
|
||||
| `NUXT_PUBLIC_LEGAL_CONTACT` | `/terms` 与 `/privacy` 页面展示的联系方式 | 未设置时显示占位文本 |
|
||||
|
||||
@@ -38,4 +38,4 @@
|
||||
|
||||
## 数据存储在哪里?
|
||||
|
||||
配置存于 D1(`d1_routes`/`d1_groups`,在内存中最多缓存 60 秒);webhook 去重、投递状态与消息更新追踪同样存于 D1(KV 回退);发送/审计日志与平台↔GitHub 绑定存于 D1;超大负载可选存于 R2。见[存储布局](./storage#存储决策)。
|
||||
配置存于 D1(`d1_routes`/`d1_groups`,在内存中最多缓存 60 秒);webhook 去重、投递状态与消息更新追踪同样存于 D1(KV 回退,可选 `DELIVERY_STATE_STORE=kv` 切换到 KV);发送/审计日志与平台↔GitHub 绑定存于 D1;超大负载可选存于 R2。见[存储布局](./storage#存储决策)。
|
||||
@@ -22,7 +22,7 @@ GitHub / Gitea Webhook → Cloudflare Worker (Nuxt 4 / Nitro)
|
||||
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| **Cloudflare Worker** | HTTP 入口、签名验证、投递去重、事件解析、路由匹配、平台分发 |
|
||||
| **Interactions Endpoint** | 验证 Ed25519 签名并处理 `/gh` 交互(斜杠命令、右键菜单、按钮、modal) |
|
||||
| **KV** | Token 存储 (`token:{userId}`)、OAuth 状态 (`state:{hex}`)、管理员会话、邀请、投递去重/投递状态/消息更新追踪的回退(`delivery:*`、`delivery-state:*`、`msg:*`,仅在 D1 不可用时使用)、消息更新锁 (`msg:lock:*`) |
|
||||
| **KV** | Token 存储 (`token:{userId}`)、OAuth 状态 (`state:{hex}`)、管理员会话、邀请、D1 不可用或 `DELIVERY_STATE_STORE=kv` 时的投递去重/投递状态/消息更新追踪(`delivery:*`、`delivery-state:*`、`msg:*`)、消息更新锁 (`msg:lock:*`) |
|
||||
| **D1** | 路由/分组 (`d1_routes`/`d1_groups`)、发送日志 (`send_logs`)、审计日志 (`audit_logs`)、去重 (`dedup_keys`)、投递状态 (`delivery_state`)、消息追踪 (`message_tracking`)、Discord↔GitHub 绑定 (`discord_links`)、Telegram↔GitHub 绑定 (`telegram_links`),超大负载可选的 R2 存储 |
|
||||
|
||||
### 数据流
|
||||
|
||||
@@ -2,10 +2,10 @@
|
||||
|
||||
## KV 存储布局
|
||||
|
||||
KV 只保留缓存数据和短期/临时状态。高频写入(webhook 去重、投递状态、消息追踪)存放在 D1,仅在 D1 不可用或未迁移时才回退到 KV(见[存储决策](#存储决策))。
|
||||
KV 只保留缓存数据和短期/临时状态。高频写入(webhook 去重、投递状态、消息追踪)存放在 D1,仅在 D1 不可用或未迁移时才回退到 KV(见[存储决策](#存储决策))。设置 `DELIVERY_STATE_STORE=kv` 时这些投递状态改为存放在 KV。
|
||||
|
||||
| 键模式 | 值 | TTL |
|
||||
| ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- | --------------------- |
|
||||
| ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- |
|
||||
| `config:routes` / `config:groups` | 旧版(D1 之前)配置,仅在 D1 表为空时读取一次用于播种 | 永久 |
|
||||
| `config:d1-seeded` | 标记 D1 已播种(已清空的 D1 不会被再次播种) | 永久 |
|
||||
| `session:{id}` | 管理员会话 `{ userId, login, loginTrusted }` | 1 天 |
|
||||
@@ -17,14 +17,14 @@ KV 只保留缓存数据和短期/临时状态。高频写入(webhook 去重
|
||||
| `invite:group:{id}` | 每组的 Token 索引(保证邀请列表一致性) | 7 天 |
|
||||
| `invite:by-group:{id}:{token}` / `invite:by-instance:{instance}:{token}` | 每个邀请的列表标记(按分组 id 与签发分组的 instance),并发创建或改名中断时邀请也不会从列表中消失 | 邀请有效期 |
|
||||
| `login-owner:{login}` | 第一个使用该登录名的 GitHub 账号 id;之后用同名登录的其他账号只按 user id 匹配 | 永久 |
|
||||
| `delivery:{provider}:{scope}:{id}` | Webhook 投递去重回退(D1 `dedup_keys` 为主);全局入口的 `scope` 为 `@global`,分组入口为 `@i:{instance}`(接收分组不可变的 instance) | 2~10 分钟 |
|
||||
| `delivery-state:{provider}:{scope}:{id}` | 队列投递状态回退(D1 `delivery_state` 为主) | 7 天 |
|
||||
| `delivery:{provider}:{scope}:{id}` | Webhook 投递去重(默认 D1 `dedup_keys`;`DELIVERY_STATE_STORE=kv` 或 D1 不可用时使用);全局入口的 `scope` 为 `@global`,分组入口为 `@i:{instance}`(接收分组不可变的 instance) | 2~10 分钟 |
|
||||
| `delivery-state:{provider}:{scope}:{id}` | 队列投递状态(默认 D1 `delivery_state`;`DELIVERY_STATE_STORE=kv` 或 D1 不可用时使用) | 7 天 |
|
||||
| `queue:payload:{provider}:{scope}:{id}:{uuid}` | 未绑定 R2 时暂存供队列消费者读取的超大 webhook 负载(每次入队一个键) | 4 天 |
|
||||
| `tenant:{groupId}` / `tenant:i:{instance}` | 旧版分组 webhook secret,仅在密钥尚未存入 D1 分组行时作为回退读取;轮换或删除时清除 | 永久 |
|
||||
| `group:renamed:{oldId}` | 仅 KV 部署:分组改名后的新 id(有 D1 时该别名是改名事务中写入的 `dedup_keys` 行) | 4 天 |
|
||||
| `msg:{chain}:{platform}:{target}` | 消息追踪回退(D1 `message_tracking` 为主) | 30 天 |
|
||||
| `msg:lock:…` | D1 不可用时串行化同一消息链更新的锁(有 D1 时是 `dedup_keys` 行) | 240 秒 |
|
||||
| `storage:kv-fallback` | 标记曾在 D1 表缺失时把状态写入 KV;有效期内 D1 未命中时也会查 KV | 35 天 |
|
||||
| `msg:{chain}:{platform}:{target}` | 消息追踪(默认 D1 `message_tracking`;`DELIVERY_STATE_STORE=kv` 或 D1 不可用时使用) | 30 天 |
|
||||
| `msg:lock:…` | 串行化同一消息链更新的锁(默认 D1 `dedup_keys`;`DELIVERY_STATE_STORE=kv` 或 D1 不可用时使用) | 240 秒 |
|
||||
| `storage:kv-fallback` | 标记状态写在了 KV 而非 D1(表缺失,或 `DELIVERY_STATE_STORE=kv`);有效期内 D1 未命中时也会查 KV | 35 天 |
|
||||
| `cmd:guilds:{appId}` | 每个 Discord 应用一条:各服务器已注册命令的哈希与同步游标 | 永久 |
|
||||
| `cmd:registered:global:{appId}` | 最近一次全局注册的命令哈希(变化时重新注册,并每天一次) | 1 天 |
|
||||
| `config:discord-app-id:{tokenHash}` | 按 bot token 解析出的 Discord 应用 id | 永久 |
|
||||
@@ -45,7 +45,7 @@ D1 数据库(`DB` 绑定,数据库 `webhooker`)保存配置、投递日志
|
||||
| `send_logs` | 每次分发尝试一行(路由 id、事件、目标、ok/error、耗时、错误码、详情) |
|
||||
| `audit_logs` | 每次管理员操作一行(登录/登出、分组/路由/成员/邀请变更) |
|
||||
| `dedup_keys` | 原子的一次性占用与记录(`INSERT ... ON CONFLICT` UPSERT,键 + 过期时间):webhook 投递去重及其确认(`accepted:*`)、自定义 webhook nonce(`nonce:{secret 作用域}:{nonce}`)、已使用与已撤销的邀请(`invite-used:*`、`invite-revoked:*`)、机器人命令/事件去重(`bot:{platform}:…`)、已撤销的会话与 token 及每个用户当前有效的 token(`session-revoked:*`、`token-revoked:*`、`token-live:*`)、已使用的账号绑定确认(`link-used:*`)、已退役的分组 id(`group-retired:*`)与改名别名(`group-alias:*`)、安装自动配置记录(`installation-provisioned:*`、`installation-bound:*`)、排队投递中已完成或已永久失败的路由 × 目标(`delivery-target:*`、`delivery-failed:*`)、已发送的分组日志摘要、消息链锁(`msg:lock:*`)以及一次性初始化标记 |
|
||||
| `delivery_state` | 队列投递状态(`pending`/`processing`/`delivered`/`retrying`/`failed`/`dead`);领取投递是一次条件 UPSERT(租约),两个消费者不会同时分发同一投递 |
|
||||
| `delivery_state` | 队列投递状态(`pending`/`processing`/`delivered`/`retrying`/`failed`/`dead`);领取投递是一次条件 UPSERT(租约),D1 模式下两个消费者不会同时分发同一投递(`DELIVERY_STATE_STORE=kv` 时状态存于 KV,由新鲜的租约时间戳承担同样职责,但没有 fencing) |
|
||||
| `message_tracking` | 原地更新用消息追踪(`event_id` + `target_id` → 消息 id 及其所显示的版本);消息链按分组 instance 建键,之后以同一 id 新建的分组不会编辑这些消息 |
|
||||
| `d1_fragments` | 每个分组的命名过滤器片段 |
|
||||
| `feishu_links` | 映射 `feishu_user_id` → `github_user_id`,供 `/gh` 飞书命令使用 |
|
||||
@@ -69,9 +69,10 @@ R2(`PAYLOAD` 绑定,bucket `webhooker-payloads`)存储对队列消息或 K
|
||||
## 存储决策
|
||||
|
||||
- **D1 是配置与投递元数据的权威数据源**;KV 只保存缓存和短期状态。
|
||||
- `canUseD1` 探测(`server/lib/storage/d1.ts`,检查 `prepare` + `batch`)为每个 D1 存储做门槛判定。高频存储(去重及其他一次性占用、投递状态、消息追踪)在其 D1 表尚不存在时(数据库未迁移)回退到 KV。其他 D1 故障会直接抛出——请求返回错误,由发送方或队列重试——因为按调用切换存储会让同一占用分散在 D1 与 KV 两处。
|
||||
- `canUseD1` 探测(`server/lib/storage/d1.ts`,检查 `prepare` + `batch`)为除投递相关之外的每个 D1 存储做门槛判定;投递存储跟随 `DELIVERY_STATE_STORE`(`server/lib/storage/state-store.ts`)。高频存储(去重及其他一次性占用、投递状态、消息追踪)在其 D1 表尚不存在时(数据库未迁移)回退到 KV。其他 D1 故障会直接抛出——请求返回错误,由发送方或队列重试——因为按调用切换存储会让同一占用分散在 D1 与 KV 两处。
|
||||
- D1 配置读取失败时,请求返回错误,由发送方或队列重试;配置没有 KV 副本,分发也绝不会把不可读的配置当作空配置。存储中无法读取的路由或分组行只会让所属分组的投递可见地失败并重试——见[路由 → 不可读的路由](./routes#不可读的路由)。
|
||||
- 配置写入从不回退:存在 D1 绑定时,写入失败会作为错误返回,而不是暂存到 KV。写入按分组进行(单行,或单个分组的路由/片段在一个事务中),分组行使用比较并交换,不同分组的并发编辑互不覆盖。权限检查、读改写路径、webhook 入口与队列消费者的读取绕过所有缓存(撤销的路由或目标立即停止投递);其他读取在每个 isolate 的内存中最多缓存 60 秒。
|
||||
- 旧版 KV 配置只在两张 D1 表都为空时复制一次,且从不覆盖已有行;标记位保证被清空的配置不会复活。
|
||||
- 这让 Workers 免费版的每事件 KV 写入趋近于零(每日 1000 次写):去重、投递状态和消息追踪改为写 D1 行(D1 免费版每日可写 10 万行)。
|
||||
- `DELIVERY_STATE_STORE=kv` 把投递热路径移回 KV:入口去重与重放 nonce、投递状态与租约、已完成目标台账与永久失败标记、消息追踪与消息链锁、分组日志摘要占用。它用 D1 宽松的写入额度换取边缘延迟;免费版 KV 每日约 1000 次写,低流量部署够用,繁忙部署不够。新鲜的租约时间戳仍能挡住第二个消费者接手正在发送的投递,但 KV 没有比较并交换:持有者消失后租约被接手、或并发抢占,仍可能重复投递。KV 模式下写入的占用与状态会打上 `storage:kv-fallback` 标记,切回 D1 后仍被认可;反方向不读取 D1,最近几天写入的 D1 行(占用及其确认、投递状态、已完成目标台账、30 天的消息追踪)都不可见——已完成的投递重投会再次发送、已发送的目标会再次发送、进行中的更新链会新发一条消息——排空队列只能减少在途任务重叠,这些 D1 行仍然不可见;要保留它们需要迁移状态,或接受重复发送。标记有效期内,仍留在 D1 的占用(邀请、会话、Token、机器人交互、分组 id)每次 claim 也会多读一次 KV,以认可 KV 模式下写入的副本;KV 读取远比写入便宜。其余部分——配置、发送日志、审计、指标,以及依附于各自 D1 事务的占用(邀请、会话、Token、机器人交互、分组 id、安装绑定)——在两种模式下都留在 D1。无法识别的取值会被记录并当作 `d1` 处理。
|
||||
- R2 免费额度(10 GB-月存储、每月 100 万次 A 类操作)可以轻松承载负载暂存,不占用 KV 写配额。
|
||||
@@ -16,7 +16,8 @@ import type { SendRecord } from "../lib/send-log";
|
||||
import { recordSendBatch } from "../lib/send-log-batch";
|
||||
import { explainRoute } from "../config/schema";
|
||||
import { chainLock, messageTracker, type MessageTracker } from "../lib/message-tracker";
|
||||
import { idempotencyStore, instanceScope, tenantScope } from "../lib/idempotency";
|
||||
import { instanceScope, tenantScope } from "../lib/idempotency";
|
||||
import { deliveryClaimStore, deliveryStateUsesD1 } from "../storage/state-store";
|
||||
import {
|
||||
loadGroups,
|
||||
groupAcceptsOwners,
|
||||
@@ -254,7 +255,7 @@ async function deliverUpdate(
|
||||
const chainId = chain.id;
|
||||
const trackTarget = chain.target;
|
||||
const lockKey = `msg:lock:${chainId}:${trackTarget}`;
|
||||
const lock = chainLock(env.DB, env.KV);
|
||||
const lock = chainLock(env.DB, env.KV, deliveryStateUsesD1(env));
|
||||
let token: string | null = null;
|
||||
for (let attempt = 0; attempt < LOCK_ATTEMPTS && !token; attempt++) {
|
||||
token = await lock.acquire(lockKey, LOCK_TTL_SECONDS);
|
||||
@@ -394,7 +395,7 @@ export async function dispatchEvent(
|
||||
const { tenantId, skipTarget, beforeTarget, afterTarget } = options;
|
||||
const loadedGroups = groups ?? (await loadGroups(env.KV));
|
||||
const groupById = new Map(loadedGroups.map((g) => [g.id, g]));
|
||||
const tracker = messageTracker(env.DB, env.KV);
|
||||
const tracker = messageTracker(env.DB, env.KV, deliveryStateUsesD1(env));
|
||||
|
||||
// Message language is configured per group (Group.lang), not per route;
|
||||
// loaded when a message is built in it (a group nothing is sent to costs
|
||||
@@ -677,7 +678,7 @@ export async function dispatchEvent(
|
||||
)}|${event.deliveryId}|${group.instance ?? groupId}|${outcome}`,
|
||||
)}`
|
||||
: null;
|
||||
if (summaryKey && !(await idempotencyStore(env.DB, env.KV).claim(summaryKey, 86400))) {
|
||||
if (summaryKey && !(await deliveryClaimStore(env).claim(summaryKey, 86400))) {
|
||||
continue;
|
||||
}
|
||||
claimed = summaryKey;
|
||||
@@ -692,7 +693,7 @@ export async function dispatchEvent(
|
||||
}
|
||||
// Not posted (a failed or thrown send): a retry may try again.
|
||||
if (claimed) {
|
||||
await idempotencyStore(env.DB, env.KV)
|
||||
await deliveryClaimStore(env)
|
||||
.release(claimed)
|
||||
.catch(() => undefined);
|
||||
}
|
||||
|
||||
@@ -118,10 +118,14 @@ function withKvFallback(
|
||||
};
|
||||
}
|
||||
|
||||
export function idempotencyStore(db: D1Database, kv: KVNamespace): IdempotencyStore {
|
||||
if (canUseD1(db)) return withKvFallback(d1IdempotencyStore(db), kvIdempotencyStore(kv), kv);
|
||||
// Without D1, claims live in KV: marked, so a D1 binding added later still
|
||||
// honors the ones not expired yet.
|
||||
/** D1 when the binding can take it, else KV (no binding, or a caller that wants KV). */
|
||||
export function idempotencyStore(
|
||||
db: D1Database | undefined | null,
|
||||
kv: KVNamespace,
|
||||
): IdempotencyStore {
|
||||
if (canUseD1(db)) return withKvFallback(d1IdempotencyStore(db!), kvIdempotencyStore(kv), kv);
|
||||
// Without D1, or with a caller that wants KV: claims live in KV, marked, so
|
||||
// D1 still honors the ones not expired yet.
|
||||
const store = kvIdempotencyStore(kv);
|
||||
return {
|
||||
...store,
|
||||
|
||||
@@ -209,10 +209,19 @@ function withKvFallback(
|
||||
};
|
||||
}
|
||||
|
||||
export function messageTracker(db: D1Database, kv: KVNamespace): MessageTracker {
|
||||
if (canUseD1(db)) return withKvFallback(d1MessageTracker(db), kvMessageTracker(kv), kv, db);
|
||||
// Without D1, tracking lives in KV: marked, so a D1 binding added later
|
||||
// still finds the messages to edit.
|
||||
/**
|
||||
* Message tracking of the delivery pipeline. `useD1` is the configured store
|
||||
* (`DELIVERY_STATE_STORE`): KV when it is off, marked so a deployment switched
|
||||
* back to D1 still finds the messages to edit.
|
||||
*/
|
||||
export function messageTracker(
|
||||
db: D1Database,
|
||||
kv: KVNamespace,
|
||||
useD1: boolean = canUseD1(db),
|
||||
): MessageTracker {
|
||||
if (useD1) return withKvFallback(d1MessageTracker(db), kvMessageTracker(kv), kv, db);
|
||||
// Without D1 — or with the delivery store set to KV — tracking lives in KV:
|
||||
// marked, so D1 still finds the messages to edit.
|
||||
const tracker = kvMessageTracker(kv);
|
||||
return {
|
||||
...tracker,
|
||||
@@ -231,7 +240,8 @@ export function messageTracker(db: D1Database, kv: KVNamespace): MessageTracker
|
||||
* Serializes the updates of one message chain. With D1 the lock is a
|
||||
* `dedup_keys` row taken by an atomic conditional UPSERT (taken over only once
|
||||
* expired) and released only by its holder, identified by the claim time it
|
||||
* wrote. Without D1 it degrades to a best-effort KV marker.
|
||||
* wrote. Without D1 — or with the delivery store set to KV — it degrades to a
|
||||
* best-effort KV marker.
|
||||
*/
|
||||
export interface ChainLock {
|
||||
/** A holder token, or null while someone else holds the lock. */
|
||||
@@ -239,7 +249,11 @@ export interface ChainLock {
|
||||
release(key: string, token: string): Promise<void>;
|
||||
}
|
||||
|
||||
export function chainLock(db: D1Database, kv: KVNamespace): ChainLock {
|
||||
export function chainLock(
|
||||
db: D1Database,
|
||||
kv: KVNamespace,
|
||||
useD1: boolean = canUseD1(db),
|
||||
): ChainLock {
|
||||
const kvLock: ChainLock = {
|
||||
async acquire(key, ttlSeconds) {
|
||||
if (await kv.get(key)) return null;
|
||||
@@ -251,9 +265,12 @@ export function chainLock(db: D1Database, kv: KVNamespace): ChainLock {
|
||||
if ((await kv.get(key)) === token) await kv.delete(key);
|
||||
},
|
||||
};
|
||||
if (!canUseD1(db)) return kvLock;
|
||||
if (!useD1) return kvLock;
|
||||
return {
|
||||
async acquire(key, ttlSeconds): Promise<string | null> {
|
||||
// A lock taken while delivering through KV (before switching back) is
|
||||
// honored too: another holder would edit the same message chain.
|
||||
if ((await kvFallbackActive(kv)) && (await kv.get(key))) return null;
|
||||
const now = Date.now();
|
||||
try {
|
||||
const result = await db
|
||||
|
||||
@@ -2,7 +2,8 @@ import type { Env, WebhookEvent } from "../../types";
|
||||
import type { Provider } from "../types";
|
||||
import { hmacSha256Hex, timingSafeEqual } from "../hmac";
|
||||
import { verifySignature } from "../github/verify";
|
||||
import { claimOnce, idempotencyStore } from "../../lib/idempotency";
|
||||
import { claimOnce } from "../../lib/idempotency";
|
||||
import { deliveryClaimStore } from "../../storage/state-store";
|
||||
|
||||
const REPLAY_WINDOW_SECONDS = 300;
|
||||
/** How long an accepted nonce is remembered (longer than the signature window). */
|
||||
@@ -63,7 +64,7 @@ async function verifyReplayProtected(
|
||||
const key = await replayNonceKey(secret, nonce);
|
||||
let state;
|
||||
try {
|
||||
state = await claimOnce(idempotencyStore(env.DB, env.KV), key, NONCE_CLAIM_SECONDS);
|
||||
state = await claimOnce(deliveryClaimStore(env), key, NONCE_CLAIM_SECONDS);
|
||||
} catch {
|
||||
// A storage failure says nothing about the signature.
|
||||
throw new ReplayPendingError("Replay protection is temporarily unavailable");
|
||||
|
||||
@@ -1,7 +1,8 @@
|
||||
import type { Env } from "../types";
|
||||
import { r2PayloadStore } from "../storage/payload";
|
||||
import { canUseD1, isMissingTable, kvFallbackActive, noteKvFallback } from "../storage/d1";
|
||||
import { idempotencyStore, kvIdempotencyStore, tenantScope } from "../lib/idempotency";
|
||||
import { isMissingTable, kvFallbackActive, noteKvFallback } from "../storage/d1";
|
||||
import { deliveryClaimStore, deliveryStateUsesD1 } from "../storage/state-store";
|
||||
import { kvIdempotencyStore, tenantScope } from "../lib/idempotency";
|
||||
import { log } from "../lib/log";
|
||||
|
||||
export type DeliveryStatus =
|
||||
@@ -162,7 +163,7 @@ export async function setDeliveryState(
|
||||
status: DeliveryStatus,
|
||||
): Promise<void> {
|
||||
const db = env.DB;
|
||||
if (canUseD1(db)) {
|
||||
if (deliveryStateUsesD1(env)) {
|
||||
try {
|
||||
await db
|
||||
.prepare(
|
||||
@@ -188,7 +189,7 @@ export async function setDeliveryState(
|
||||
|
||||
export async function getDeliveryState(env: Env, key: string): Promise<DeliveryStatus | null> {
|
||||
const db = env.DB;
|
||||
if (canUseD1(db)) {
|
||||
if (deliveryStateUsesD1(env)) {
|
||||
try {
|
||||
const row = await db
|
||||
.prepare("SELECT status FROM delivery_state WHERE key = ?")
|
||||
@@ -201,10 +202,23 @@ export async function getDeliveryState(env: Env, key: string): Promise<DeliveryS
|
||||
await noteKvFallback(env.KV);
|
||||
}
|
||||
}
|
||||
return (await readKvDeliveryState(env, key))?.status ?? null;
|
||||
}
|
||||
|
||||
/**
|
||||
* The KV-stored state of a delivery, with the time it was written (the lease
|
||||
* stamp). Null when absent or unreadable.
|
||||
*/
|
||||
async function readKvDeliveryState(
|
||||
env: Env,
|
||||
key: string,
|
||||
): Promise<{ status: DeliveryStatus; at: number } | null> {
|
||||
const raw = await env.KV.get(key);
|
||||
if (!raw) return null;
|
||||
try {
|
||||
return (JSON.parse(raw) as { status?: DeliveryStatus }).status ?? null;
|
||||
const parsed = JSON.parse(raw) as { status?: DeliveryStatus; at?: unknown };
|
||||
if (!parsed.status) return null;
|
||||
return { status: parsed.status, at: Number(parsed.at) || 0 };
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
@@ -217,7 +231,8 @@ export type LeaseResult = "acquired" | "finished" | "busy";
|
||||
* `updated_at` the holder wrote). Renewals and terminal writes only apply
|
||||
* while the row still carries the holder's token, so a consumer whose lease
|
||||
* was taken over can neither overwrite the new holder's state nor go on as if
|
||||
* it still owned the delivery. Null token: KV fallback (no fencing).
|
||||
* it still owned the delivery. Null token: KV (configured store or fallback),
|
||||
* where a fresh lease stamp plays the same role without fencing.
|
||||
*/
|
||||
export interface Lease {
|
||||
status: LeaseResult;
|
||||
@@ -231,21 +246,25 @@ const FINISHED: ReadonlySet<DeliveryStatus | null> = new Set(["delivered", "dead
|
||||
* succeeds only for a new delivery, one waiting for a retry, or one whose
|
||||
* previous holder's lease expired — so two consumers can never dispatch the
|
||||
* same delivery at the same time. `finished` deliveries are done for good;
|
||||
* `busy` ones are being processed elsewhere right now.
|
||||
* `busy` ones are being processed elsewhere right now. With KV the same stamp
|
||||
* keeps a second consumer off a live lease, but there is no fencing token: a
|
||||
* holder whose lease expired cannot tell that another one took over.
|
||||
*/
|
||||
export async function acquireDelivery(env: Env, key: string): Promise<Lease> {
|
||||
const db = env.DB;
|
||||
if (canUseD1(db)) {
|
||||
if (deliveryStateUsesD1(env)) {
|
||||
try {
|
||||
// Finished while the table was missing (state lives in KV then).
|
||||
if (await kvFallbackActive(env.KV)) {
|
||||
const kvState = await env.KV.get(key);
|
||||
if (
|
||||
kvState &&
|
||||
FINISHED.has((JSON.parse(kvState) as { status?: DeliveryStatus }).status ?? null)
|
||||
) {
|
||||
const kvState = await readKvDeliveryState(env, key);
|
||||
if (kvState && FINISHED.has(kvState.status)) {
|
||||
return { status: "finished", token: null };
|
||||
}
|
||||
// A holder delivering through KV (before switching back) keeps its
|
||||
// delivery for the rest of its lease.
|
||||
if (kvState?.status === "processing" && kvState.at > Date.now() - LEASE_MS) {
|
||||
return { status: "busy", token: null };
|
||||
}
|
||||
}
|
||||
const now = Date.now();
|
||||
const result = await db
|
||||
@@ -266,9 +285,13 @@ export async function acquireDelivery(env: Env, key: string): Promise<Lease> {
|
||||
await noteKvFallback(env.KV);
|
||||
}
|
||||
}
|
||||
// KV: best effort (no atomic compare-and-set).
|
||||
const prior = await getDeliveryState(env, key);
|
||||
if (FINISHED.has(prior)) return { status: "finished", token: null };
|
||||
// KV: no compare-and-set, but the lease stamp still keeps a second consumer
|
||||
// off a delivery that is being sent right now.
|
||||
const prior = await readKvDeliveryState(env, key);
|
||||
if (prior && FINISHED.has(prior.status)) return { status: "finished", token: null };
|
||||
if (prior?.status === "processing" && prior.at > Date.now() - LEASE_MS) {
|
||||
return { status: "busy", token: null };
|
||||
}
|
||||
await setDeliveryState(env, key, "processing");
|
||||
return { status: "acquired", token: null };
|
||||
}
|
||||
@@ -276,15 +299,21 @@ export async function acquireDelivery(env: Env, key: string): Promise<Lease> {
|
||||
/**
|
||||
* Mark a delivery dead (its message left the DLQ) — atomically, and only
|
||||
* while it is neither finished nor held by a live lease: a copy of the same
|
||||
* delivery that finished or is still sending keeps its state. Without D1:
|
||||
* delivery that finished or is still sending keeps its state. With KV:
|
||||
* best effort.
|
||||
*/
|
||||
export async function markDeliveryDead(
|
||||
env: Env,
|
||||
key: string,
|
||||
): Promise<"dead" | "finished" | "busy"> {
|
||||
if (canUseD1(env.DB)) {
|
||||
if (deliveryStateUsesD1(env)) {
|
||||
try {
|
||||
// A holder delivering through KV (before switching back) keeps its
|
||||
// delivery: the DLQ copy must not close it under that holder.
|
||||
if (await kvFallbackActive(env.KV)) {
|
||||
const kvState = await readKvDeliveryState(env, key);
|
||||
if (kvState?.status === "processing" && kvState.at > Date.now() - LEASE_MS) return "busy";
|
||||
}
|
||||
const now = Date.now();
|
||||
const result = await env.DB.prepare(
|
||||
`INSERT INTO delivery_state (key, status, updated_at) VALUES (?, 'dead', ?)
|
||||
@@ -300,21 +329,37 @@ export async function markDeliveryDead(
|
||||
if (!isMissingTable(err)) throw err;
|
||||
}
|
||||
}
|
||||
if (FINISHED.has(await getDeliveryState(env, key))) return "finished";
|
||||
const prior = await readKvDeliveryState(env, key);
|
||||
if (prior && FINISHED.has(prior.status)) return "finished";
|
||||
// Same lease stamp as `acquireDelivery`: a live sender keeps its delivery.
|
||||
if (prior?.status === "processing" && prior.at > Date.now() - LEASE_MS) return "busy";
|
||||
await setDeliveryState(env, key, "dead");
|
||||
return "dead";
|
||||
}
|
||||
|
||||
/**
|
||||
* Extend a held lease; the new token, or null when the lease was lost (taken
|
||||
* over after expiry). Without D1 the lease cannot be fenced and stays valid.
|
||||
* over after expiry). In KV there is no fencing token to renew: the lease
|
||||
* stamp is refreshed instead, so another consumer does not take a delivery
|
||||
* that is still being sent.
|
||||
*/
|
||||
export async function renewLease(
|
||||
env: Env,
|
||||
key: string,
|
||||
token: number | null,
|
||||
): Promise<number | null> {
|
||||
if (token == null || !canUseD1(env.DB)) return token;
|
||||
if (!deliveryStateUsesD1(env)) {
|
||||
if (token == null) {
|
||||
const prior = await readKvDeliveryState(env, key);
|
||||
// At most every half lease: the stamp stays fresh with a read per
|
||||
// renewal and a write per half lease, sparing the KV write quota.
|
||||
if (prior?.status === "processing" && Date.now() - prior.at > LEASE_MS / 2) {
|
||||
await setDeliveryState(env, key, "processing");
|
||||
}
|
||||
}
|
||||
return token;
|
||||
}
|
||||
if (token == null) return token;
|
||||
const now = Math.max(Date.now(), token + 1);
|
||||
const result = await env.DB.prepare(
|
||||
`UPDATE delivery_state SET updated_at = ?
|
||||
@@ -335,7 +380,7 @@ export async function finishLease(
|
||||
token: number | null,
|
||||
status: DeliveryStatus,
|
||||
): Promise<boolean> {
|
||||
if (token == null || !canUseD1(env.DB)) {
|
||||
if (token == null || !deliveryStateUsesD1(env)) {
|
||||
await setDeliveryState(env, key, status);
|
||||
return true;
|
||||
}
|
||||
@@ -354,7 +399,8 @@ function targetDoneKey(stateKey: string, targetKey: string): string {
|
||||
|
||||
/**
|
||||
* Remember route × targets that need no further attempt for this delivery —
|
||||
* one D1 transaction for all of them (KV claims without D1 or its table).
|
||||
* one D1 transaction for all of them (KV claims when the store is KV or D1
|
||||
* lacks the table).
|
||||
* With `permanentFailure`, the delivery's permanent-failure marker is written
|
||||
* in the same transaction: a target is never skipped as finished while the
|
||||
* failure that finished it is forgotten (which would let the delivery end
|
||||
@@ -371,7 +417,7 @@ export async function markTargetsDone(
|
||||
// at worst a marker without its target (the target is simply retried).
|
||||
if (opts.permanentFailure) keys.unshift(permanentFailureKey(stateKey));
|
||||
if (keys.length === 0) return;
|
||||
if (canUseD1(env.DB)) {
|
||||
if (deliveryStateUsesD1(env)) {
|
||||
const now = Date.now();
|
||||
const expires = now + LEDGER_TTL_SECONDS * 1000;
|
||||
try {
|
||||
@@ -405,7 +451,7 @@ export function targetDoneChecker(
|
||||
env: Env,
|
||||
stateKey: string,
|
||||
): (targetKey: string) => Promise<boolean> {
|
||||
const store = idempotencyStore(env.DB, env.KV);
|
||||
const store = deliveryClaimStore(env);
|
||||
let finished: Promise<Set<string> | null> | null = null;
|
||||
return async (targetKey) => {
|
||||
const key = targetDoneKey(stateKey, targetKey);
|
||||
@@ -421,7 +467,7 @@ export function targetDoneChecker(
|
||||
|
||||
/** The delivery's finished-target keys, or null where they are read one by one. */
|
||||
async function finishedTargets(env: Env, stateKey: string): Promise<Set<string> | null> {
|
||||
if (!canUseD1(env.DB)) return null;
|
||||
if (!deliveryStateUsesD1(env)) return null;
|
||||
const prefix = targetDoneKey(stateKey, "");
|
||||
try {
|
||||
const { results } = await env.DB.prepare(
|
||||
@@ -442,7 +488,7 @@ function permanentFailureKey(stateKey: string): string {
|
||||
|
||||
/** Whether an earlier attempt of this delivery left a target failed for good. */
|
||||
export function hadPermanentFailure(env: Env, stateKey: string): Promise<boolean> {
|
||||
return idempotencyStore(env.DB, env.KV).has(permanentFailureKey(stateKey));
|
||||
return deliveryClaimStore(env).has(permanentFailureKey(stateKey));
|
||||
}
|
||||
|
||||
function byteLength(text: string): number {
|
||||
|
||||
@@ -0,0 +1,57 @@
|
||||
import type { Env } from "../types";
|
||||
import { idempotencyStore, type IdempotencyStore } from "../lib/idempotency";
|
||||
import { log } from "../lib/log";
|
||||
import { canUseD1 } from "./d1";
|
||||
|
||||
/**
|
||||
* Where the state of a webhook delivery lives: its dedup claim and replay
|
||||
* nonce at ingress, its lease and status, the finished-target ledger and the
|
||||
* messages it edits. D1 is the default: Workers Free allows 100,000 row
|
||||
* writes/day there, while each write is a round trip to the database. KV
|
||||
* answers from the edge, but allows only ~1,000 writes/day on the free plan
|
||||
* and has no compare-and-set, so a lease or a claim can be taken twice in a
|
||||
* race — the deliberate trade for latency at low volume.
|
||||
*/
|
||||
export type DeliveryStateStore = "d1" | "kv";
|
||||
|
||||
/** Unknown values already reported (the binding is fixed per deployment). */
|
||||
const warned = new Set<string>();
|
||||
|
||||
/** The configured store: `DELIVERY_STATE_STORE=kv` switches, anything else is D1. */
|
||||
export function deliveryStateStore(env: Pick<Env, "DELIVERY_STATE_STORE">): DeliveryStateStore {
|
||||
const value = (env.DELIVERY_STATE_STORE ?? "").trim().toLowerCase();
|
||||
if (value === "kv") return "kv";
|
||||
if (value !== "" && value !== "d1" && !warned.has(value)) {
|
||||
warned.add(value);
|
||||
log.warn({ value }, "Unknown DELIVERY_STATE_STORE, using d1");
|
||||
}
|
||||
return "d1";
|
||||
}
|
||||
|
||||
/**
|
||||
* Whether delivery state is written to D1: the configured store, when the
|
||||
* binding can take it. State written to KV is marked, so a deployment
|
||||
* switched back to D1 still honors its claims and leases. The other direction
|
||||
* is not read: with `kv` set, the D1 rows of the past days — dedup claims and
|
||||
* their confirmations, delivery states, the finished-target ledger, message
|
||||
* tracking (30 days) — are invisible, so a redelivery of an event that already
|
||||
* finished is sent again, targets already sent are sent again, and an
|
||||
* in-progress `workflow_run`/`check_run` chain posts a new message. Draining
|
||||
* the queue only keeps in-flight deliveries from overlapping; the D1 rows stay
|
||||
* invisible either way, so carry the state over (or accept the repeats).
|
||||
*/
|
||||
export function deliveryStateUsesD1(env: Pick<Env, "DB" | "DELIVERY_STATE_STORE">): boolean {
|
||||
return deliveryStateStore(env) === "d1" && canUseD1(env.DB);
|
||||
}
|
||||
|
||||
/**
|
||||
* The claim store of the delivery pipeline (ingress dedup, replay nonces, the
|
||||
* delivery target ledger). Out of scope: claims tied to a D1 transaction of
|
||||
* their own (invites, sessions, tokens, bot interactions, group ids), which
|
||||
* stay in D1 whichever store deliveries use.
|
||||
*/
|
||||
export function deliveryClaimStore(
|
||||
env: Pick<Env, "DB" | "KV" | "DELIVERY_STATE_STORE">,
|
||||
): IdempotencyStore {
|
||||
return idempotencyStore(deliveryStateUsesD1(env) ? env.DB : undefined, env.KV);
|
||||
}
|
||||
@@ -31,6 +31,12 @@ export interface Env {
|
||||
ALLOW_SELF_SIGNUP?: string;
|
||||
/** Audit log retention in days (default 90). */
|
||||
AUDIT_RETENTION_DAYS?: string;
|
||||
/**
|
||||
* Where webhook delivery state is kept: `d1` (default) or `kv`. D1 allows
|
||||
* far more free writes but each one is a database round trip; KV answers at
|
||||
* the edge and is best effort (no compare-and-set).
|
||||
*/
|
||||
DELIVERY_STATE_STORE?: string;
|
||||
ASSETS?: Fetcher;
|
||||
KV: KVNamespace;
|
||||
DB: D1Database;
|
||||
|
||||
@@ -11,6 +11,7 @@ import { recordAudit } from "./lib/audit";
|
||||
import { cfEnv, cfWaitUntil, headersFrom } from "./cf";
|
||||
import { log } from "./lib/log";
|
||||
import { claimOnce, confirmClaim, deliveryKey, idempotencyStore } from "./lib/idempotency";
|
||||
import { deliveryClaimStore } from "./storage/state-store";
|
||||
import { newCorrelationId } from "./lib/correlation";
|
||||
import {
|
||||
deliveryStateKey,
|
||||
@@ -131,7 +132,7 @@ export async function processWebhook(
|
||||
// otherwise they are given back, so the sender's retry is not refused. A
|
||||
// claim that could not be given back is never mistaken for an accepted
|
||||
// event: a retry finds it unconfirmed and is asked to come back later.
|
||||
const claims = idempotencyStore(env.DB, env.KV);
|
||||
const claims = deliveryClaimStore(env);
|
||||
const held: { key: string; ttl: number }[] = [];
|
||||
const nonce = headers["x-webhooker-nonce"];
|
||||
if (provider.id === "custom" && nonce && headers["x-webhooker-timestamp"]) {
|
||||
@@ -217,17 +218,19 @@ export async function processWebhook(
|
||||
// Done once per installation, on record as long as delivery state is
|
||||
// kept: a redelivery after the dedup claim lapsed (minutes) must not
|
||||
// redo a binding an admin undid since. Recorded only once it succeeded,
|
||||
// so a provisioning that failed midway is completed by the retry.
|
||||
// so a provisioning that failed midway is completed by the retry. Kept
|
||||
// in D1 with the bindings it guards, whichever store deliveries use.
|
||||
const doneKey = `installation-provisioned:${event.installationId}`;
|
||||
const records = idempotencyStore(env.DB, env.KV);
|
||||
try {
|
||||
if (!(await claims.has(doneKey))) {
|
||||
if (!(await records.has(doneKey))) {
|
||||
const group = await ensureInstallationGroup(
|
||||
env.KV,
|
||||
event.installationId,
|
||||
account,
|
||||
env.DB,
|
||||
);
|
||||
await claims.claim(doneKey, PROVISIONED_TTL_SECONDS);
|
||||
await records.claim(doneKey, PROVISIONED_TTL_SECONDS);
|
||||
if (group) {
|
||||
await recordAudit(env.DB, {
|
||||
ts: Date.now(),
|
||||
|
||||
@@ -0,0 +1,423 @@
|
||||
import { describe, it, expect } from "bun:test";
|
||||
import type { Database } from "bun:sqlite";
|
||||
import {
|
||||
deliveryClaimStore,
|
||||
deliveryStateStore,
|
||||
deliveryStateUsesD1,
|
||||
} from "../server/lib/storage/state-store";
|
||||
import {
|
||||
acquireDelivery,
|
||||
deliveryStateKey,
|
||||
finishLease,
|
||||
getDeliveryState,
|
||||
hadPermanentFailure,
|
||||
markDeliveryDead,
|
||||
markTargetsDone,
|
||||
renewLease,
|
||||
setDeliveryState,
|
||||
targetDoneChecker,
|
||||
} from "../server/lib/queue/delivery";
|
||||
import { chainLock, messageTracker } from "../server/lib/lib/message-tracker";
|
||||
import { createMemoryKV, createSqliteD1 } from "./d1-sqlite";
|
||||
import type { Env } from "../server/lib/types";
|
||||
|
||||
function storeEnv(options: { mode?: string; db?: D1Database; kv?: KVNamespace } = {}): {
|
||||
env: Env;
|
||||
sqlite: Database;
|
||||
store: Map<string, string>;
|
||||
} {
|
||||
const { db, sqlite } = createSqliteD1();
|
||||
const memory = createMemoryKV();
|
||||
return {
|
||||
env: {
|
||||
GITHUB_WEBHOOK_SECRET: "secret",
|
||||
DB: options.db ?? db,
|
||||
KV: options.kv ?? memory.kv,
|
||||
DELIVERY_STATE_STORE: options.mode,
|
||||
} as Env,
|
||||
sqlite,
|
||||
store: memory.store,
|
||||
};
|
||||
}
|
||||
|
||||
function rows(sqlite: Database, table: string): number {
|
||||
return (sqlite.query(`SELECT COUNT(*) AS n FROM ${table}`).get() as { n: number }).n;
|
||||
}
|
||||
|
||||
describe("deliveryStateStore", () => {
|
||||
it("defaults to D1 when the variable is absent or empty", () => {
|
||||
expect(deliveryStateStore({})).toBe("d1");
|
||||
expect(deliveryStateStore({ DELIVERY_STATE_STORE: "" })).toBe("d1");
|
||||
expect(deliveryStateStore({ DELIVERY_STATE_STORE: " " })).toBe("d1");
|
||||
});
|
||||
|
||||
it("reads d1 explicitly", () => {
|
||||
expect(deliveryStateStore({ DELIVERY_STATE_STORE: "d1" })).toBe("d1");
|
||||
expect(deliveryStateStore({ DELIVERY_STATE_STORE: " D1 " })).toBe("d1");
|
||||
});
|
||||
|
||||
it("switches to kv, ignoring case and surrounding spaces", () => {
|
||||
expect(deliveryStateStore({ DELIVERY_STATE_STORE: "kv" })).toBe("kv");
|
||||
expect(deliveryStateStore({ DELIVERY_STATE_STORE: "KV" })).toBe("kv");
|
||||
expect(deliveryStateStore({ DELIVERY_STATE_STORE: " Kv " })).toBe("kv");
|
||||
});
|
||||
|
||||
it("treats an unknown value as d1", () => {
|
||||
expect(deliveryStateStore({ DELIVERY_STATE_STORE: "d1x" })).toBe("d1");
|
||||
expect(deliveryStateStore({ DELIVERY_STATE_STORE: "kv2" })).toBe("d1");
|
||||
expect(deliveryStateStore({ DELIVERY_STATE_STORE: "redis" })).toBe("d1");
|
||||
});
|
||||
});
|
||||
|
||||
describe("deliveryStateUsesD1", () => {
|
||||
it("is true for the default and d1 while D1 is usable", () => {
|
||||
const { env } = storeEnv();
|
||||
expect(deliveryStateUsesD1(env)).toBe(true);
|
||||
expect(deliveryStateUsesD1({ ...env, DELIVERY_STATE_STORE: "d1" })).toBe(true);
|
||||
expect(deliveryStateUsesD1({ ...env, DELIVERY_STATE_STORE: "d1x" })).toBe(true);
|
||||
});
|
||||
|
||||
it("is false in kv mode even when D1 is usable", () => {
|
||||
const { env } = storeEnv({ mode: "kv" });
|
||||
expect(deliveryStateUsesD1(env)).toBe(false);
|
||||
});
|
||||
|
||||
it("is false without a usable D1 binding", () => {
|
||||
const { env } = storeEnv({ db: {} as D1Database });
|
||||
expect(deliveryStateUsesD1(env)).toBe(false);
|
||||
expect(deliveryStateUsesD1({ ...env, DELIVERY_STATE_STORE: "kv" })).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
describe("delivery state in d1 mode", () => {
|
||||
it("writes the delivery_state row and nothing to KV", async () => {
|
||||
const { env, sqlite, store } = storeEnv();
|
||||
const key = deliveryStateKey("github", "g1", "d1");
|
||||
await setDeliveryState(env, key, "processing");
|
||||
expect(rows(sqlite, "delivery_state")).toBe(1);
|
||||
expect(store.has(key)).toBe(false);
|
||||
expect(store.has("storage:kv-fallback")).toBe(false);
|
||||
expect(await getDeliveryState(env, key)).toBe("processing");
|
||||
});
|
||||
|
||||
it("writes claims and the target ledger to dedup_keys", async () => {
|
||||
const { env, sqlite, store } = storeEnv();
|
||||
const claims = deliveryClaimStore(env);
|
||||
expect(await claims.claim("delivery:github:g1:d1", 600)).toBe(true);
|
||||
expect(rows(sqlite, "dedup_keys")).toBe(1);
|
||||
expect(store.has("delivery:github:g1:d1")).toBe(false);
|
||||
expect(store.has("storage:kv-fallback")).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
describe("delivery state in kv mode", () => {
|
||||
it("writes only the KV state key while D1 stays empty", async () => {
|
||||
const { env, sqlite, store } = storeEnv({ mode: "kv" });
|
||||
const key = deliveryStateKey("github", "g1", "d1");
|
||||
await setDeliveryState(env, key, "processing");
|
||||
expect(store.has(key)).toBe(true);
|
||||
expect(JSON.parse(store.get(key) as string)).toMatchObject({ status: "processing" });
|
||||
expect(rows(sqlite, "delivery_state")).toBe(0);
|
||||
expect(await getDeliveryState(env, key)).toBe("processing");
|
||||
});
|
||||
|
||||
it("acquires without a fencing token and holds the delivery for one lease", async () => {
|
||||
const { env, sqlite, store } = storeEnv({ mode: "kv" });
|
||||
const key = deliveryStateKey("github", "g1", "d1");
|
||||
const first = await acquireDelivery(env, key);
|
||||
expect(first).toEqual({ status: "acquired", token: null });
|
||||
expect(JSON.parse(store.get(key) as string)).toMatchObject({ status: "processing" });
|
||||
// The stamp keeps a second consumer off a delivery that is still sending.
|
||||
expect(await acquireDelivery(env, key)).toEqual({ status: "busy", token: null });
|
||||
// Once the holder vanished (stamp older than the lease), it is taken over.
|
||||
store.set(key, JSON.stringify({ status: "processing", at: Date.now() - 6 * 60_000 }));
|
||||
expect(await acquireDelivery(env, key)).toEqual({ status: "acquired", token: null });
|
||||
expect(rows(sqlite, "delivery_state")).toBe(0);
|
||||
});
|
||||
|
||||
it("refreshes the lease stamp on renewal", async () => {
|
||||
const { env, store } = storeEnv({ mode: "kv" });
|
||||
const key = deliveryStateKey("github", "g1", "d1");
|
||||
await acquireDelivery(env, key);
|
||||
store.set(key, JSON.stringify({ status: "processing", at: Date.now() - 4 * 60_000 }));
|
||||
expect(await renewLease(env, key, null)).toBeNull();
|
||||
const refreshed = JSON.parse(store.get(key) as string) as { at: number };
|
||||
expect(Date.now() - refreshed.at).toBeLessThan(10_000);
|
||||
// A stamp that is still fresh is left alone (no KV write).
|
||||
await renewLease(env, key, null);
|
||||
expect(JSON.parse(store.get(key) as string)).toMatchObject({ at: refreshed.at });
|
||||
});
|
||||
|
||||
it("reports finished deliveries as finished", async () => {
|
||||
const { env, sqlite, store } = storeEnv({ mode: "kv" });
|
||||
const key = deliveryStateKey("github", "g1", "done");
|
||||
await setDeliveryState(env, key, "delivered");
|
||||
expect(await acquireDelivery(env, key)).toEqual({ status: "finished", token: null });
|
||||
expect(JSON.parse(store.get(key) as string)).toMatchObject({ status: "delivered" });
|
||||
expect(rows(sqlite, "delivery_state")).toBe(0);
|
||||
});
|
||||
|
||||
it("finishes and renews a lease without a token", async () => {
|
||||
const { env, sqlite, store } = storeEnv({ mode: "kv" });
|
||||
const key = deliveryStateKey("github", "g1", "d1");
|
||||
const lease = await acquireDelivery(env, key);
|
||||
expect(await renewLease(env, key, lease.token)).toBeNull();
|
||||
expect(await renewLease(env, key, 12345)).toBe(12345);
|
||||
expect(await finishLease(env, key, lease.token, "delivered")).toBe(true);
|
||||
expect(await getDeliveryState(env, key)).toBe("delivered");
|
||||
expect(JSON.parse(store.get(key) as string)).toMatchObject({ status: "delivered" });
|
||||
expect(await acquireDelivery(env, key)).toEqual({ status: "finished", token: null });
|
||||
expect(rows(sqlite, "delivery_state")).toBe(0);
|
||||
});
|
||||
|
||||
it("writes a retrying outcome that the next consumer may take", async () => {
|
||||
const { env } = storeEnv({ mode: "kv" });
|
||||
const key = deliveryStateKey("github", "g1", "d1");
|
||||
await acquireDelivery(env, key);
|
||||
expect(await finishLease(env, key, null, "retrying")).toBe(true);
|
||||
expect(await getDeliveryState(env, key)).toBe("retrying");
|
||||
expect((await acquireDelivery(env, key)).status).toBe("acquired");
|
||||
});
|
||||
|
||||
it("marks a delivery dead without touching D1", async () => {
|
||||
const { env, sqlite, store } = storeEnv({ mode: "kv" });
|
||||
const waiting = deliveryStateKey("github", "g1", "waiting");
|
||||
const done = deliveryStateKey("github", "g1", "done");
|
||||
const live = deliveryStateKey("github", "g1", "live");
|
||||
const stale = deliveryStateKey("github", "g1", "stale");
|
||||
await setDeliveryState(env, waiting, "retrying");
|
||||
await setDeliveryState(env, done, "delivered");
|
||||
await setDeliveryState(env, live, "processing");
|
||||
await setDeliveryState(env, stale, "processing");
|
||||
store.set(stale, JSON.stringify({ status: "processing", at: Date.now() - 6 * 60_000 }));
|
||||
expect(await markDeliveryDead(env, waiting)).toBe("dead");
|
||||
expect(await getDeliveryState(env, waiting)).toBe("dead");
|
||||
expect(await markDeliveryDead(env, done)).toBe("finished");
|
||||
expect(await getDeliveryState(env, done)).toBe("delivered");
|
||||
// A live lease is respected: its holder is still sending.
|
||||
expect(await markDeliveryDead(env, live)).toBe("busy");
|
||||
expect(await getDeliveryState(env, live)).toBe("processing");
|
||||
expect(await markDeliveryDead(env, stale)).toBe("dead");
|
||||
expect(rows(sqlite, "delivery_state")).toBe(0);
|
||||
expect(store.has(waiting)).toBe(true);
|
||||
});
|
||||
|
||||
it("records and reads finished targets and permanent failures from KV", async () => {
|
||||
const { env, sqlite, store } = storeEnv({ mode: "kv" });
|
||||
const stateKey = deliveryStateKey("github", "g1", "d1");
|
||||
const done = targetDoneChecker(env, stateKey);
|
||||
expect(await done("discord:1")).toBe(false);
|
||||
expect(await hadPermanentFailure(env, stateKey)).toBe(false);
|
||||
|
||||
await markTargetsDone(env, stateKey, ["discord:1", "telegram:2"]);
|
||||
expect(await done("discord:1")).toBe(true);
|
||||
expect(await done("telegram:2")).toBe(true);
|
||||
expect(await done("feishu:3")).toBe(false);
|
||||
expect(store.has(`delivery-target:${stateKey}:discord:1`)).toBe(true);
|
||||
expect(rows(sqlite, "dedup_keys")).toBe(0);
|
||||
expect(await hadPermanentFailure(env, stateKey)).toBe(false);
|
||||
|
||||
await markTargetsDone(env, stateKey, ["feishu:3"], { permanentFailure: true });
|
||||
expect(await hadPermanentFailure(env, stateKey)).toBe(true);
|
||||
expect(await done("feishu:3")).toBe(true);
|
||||
expect(store.has(`delivery-failed:${stateKey}`)).toBe(true);
|
||||
expect(rows(sqlite, "dedup_keys")).toBe(0);
|
||||
});
|
||||
});
|
||||
|
||||
describe("switching back to d1", () => {
|
||||
it("still honors a claim written in kv mode", async () => {
|
||||
const { env, store, sqlite } = storeEnv({ mode: "kv" });
|
||||
const key = "delivery:github:g1:d1";
|
||||
expect(await deliveryClaimStore(env).claim(key, 600)).toBe(true);
|
||||
expect(store.has("storage:kv-fallback")).toBe(true);
|
||||
expect(rows(sqlite, "dedup_keys")).toBe(0);
|
||||
|
||||
const switched = { ...env, DELIVERY_STATE_STORE: "d1" } as Env;
|
||||
const claims = deliveryClaimStore(switched);
|
||||
expect(await claims.has(key)).toBe(true);
|
||||
expect(await claims.claim(key, 600)).toBe(false);
|
||||
await claims.release(key);
|
||||
expect(await claims.has(key)).toBe(false);
|
||||
expect(await claims.claim(key, 600)).toBe(true);
|
||||
expect(rows(sqlite, "dedup_keys")).toBe(1);
|
||||
});
|
||||
|
||||
it("still honors a delivery state written in kv mode", async () => {
|
||||
const { env, sqlite, store } = storeEnv({ mode: "kv" });
|
||||
const key = deliveryStateKey("github", "g1", "d1");
|
||||
await setDeliveryState(env, key, "delivered");
|
||||
|
||||
const switched = { ...env, DELIVERY_STATE_STORE: "d1" } as Env;
|
||||
expect(await getDeliveryState(switched, key)).toBe("delivered");
|
||||
expect(await acquireDelivery(switched, key)).toEqual({ status: "finished", token: null });
|
||||
expect(rows(sqlite, "delivery_state")).toBe(0);
|
||||
expect(store.has(key)).toBe(true);
|
||||
});
|
||||
|
||||
it("lets a delivery left retrying in kv mode be acquired again", async () => {
|
||||
const { env } = storeEnv({ mode: "kv" });
|
||||
const key = deliveryStateKey("github", "g1", "d1");
|
||||
await setDeliveryState(env, key, "retrying");
|
||||
|
||||
const switched = { ...env, DELIVERY_STATE_STORE: "d1" } as Env;
|
||||
const lease = await acquireDelivery(switched, key);
|
||||
expect(lease.status).toBe("acquired");
|
||||
expect(lease.token).not.toBeNull();
|
||||
expect(await finishLease(switched, key, lease.token, "delivered")).toBe(true);
|
||||
expect(await getDeliveryState(switched, key)).toBe("delivered");
|
||||
});
|
||||
|
||||
it("still honors the target ledger and permanent failures written in kv mode", async () => {
|
||||
const { env } = storeEnv({ mode: "kv" });
|
||||
const stateKey = deliveryStateKey("github", "g1", "d1");
|
||||
await markTargetsDone(env, stateKey, ["discord:1"], { permanentFailure: true });
|
||||
|
||||
const switched = { ...env, DELIVERY_STATE_STORE: "d1" } as Env;
|
||||
expect(await targetDoneChecker(switched, stateKey)("discord:1")).toBe(true);
|
||||
expect(await hadPermanentFailure(switched, stateKey)).toBe(true);
|
||||
});
|
||||
|
||||
it("keeps a live kv lease off a d1 acquisition", async () => {
|
||||
const { env, sqlite, store } = storeEnv();
|
||||
const key = deliveryStateKey("github", "g1", "d1");
|
||||
store.set("storage:kv-fallback", String(Date.now() + 86_400_000));
|
||||
store.set(key, JSON.stringify({ status: "processing", at: Date.now() }));
|
||||
expect(await acquireDelivery(env, key)).toEqual({ status: "busy", token: null });
|
||||
expect(rows(sqlite, "delivery_state")).toBe(0);
|
||||
|
||||
store.set(key, JSON.stringify({ status: "processing", at: Date.now() - 6 * 60_000 }));
|
||||
const lease = await acquireDelivery(env, key);
|
||||
expect(lease.status).toBe("acquired");
|
||||
expect(lease.token).not.toBeNull();
|
||||
expect(rows(sqlite, "delivery_state")).toBe(1);
|
||||
});
|
||||
|
||||
it("keeps a live kv lease from being marked dead by the d1 path", async () => {
|
||||
const { env, sqlite, store } = storeEnv();
|
||||
const key = deliveryStateKey("github", "g1", "d1");
|
||||
store.set("storage:kv-fallback", String(Date.now() + 86_400_000));
|
||||
store.set(key, JSON.stringify({ status: "processing", at: Date.now() }));
|
||||
expect(await markDeliveryDead(env, key)).toBe("busy");
|
||||
expect(rows(sqlite, "delivery_state")).toBe(0);
|
||||
|
||||
store.set(key, JSON.stringify({ status: "processing", at: Date.now() - 6 * 60_000 }));
|
||||
expect(await markDeliveryDead(env, key)).toBe("dead");
|
||||
expect(rows(sqlite, "delivery_state")).toBe(1);
|
||||
});
|
||||
});
|
||||
|
||||
describe("deliveryClaimStore", () => {
|
||||
it("claims in KV and reads the claim back from KV in kv mode", async () => {
|
||||
const { env, sqlite, store } = storeEnv({ mode: "kv" });
|
||||
const claims = deliveryClaimStore(env);
|
||||
expect(await claims.has("nonce:abc")).toBe(false);
|
||||
expect(await claims.claim("nonce:abc", 300)).toBe(true);
|
||||
expect(store.has("storage:kv-fallback")).toBe(true);
|
||||
expect(await env.KV.get("nonce:abc")).not.toBeNull();
|
||||
expect(await claims.claim("nonce:abc", 300)).toBe(false);
|
||||
expect(await claims.has("nonce:abc")).toBe(true);
|
||||
expect(rows(sqlite, "dedup_keys")).toBe(0);
|
||||
await claims.release("nonce:abc");
|
||||
expect(await env.KV.get("nonce:abc")).toBeNull();
|
||||
expect(await claims.claim("nonce:abc", 300)).toBe(true);
|
||||
expect(rows(sqlite, "dedup_keys")).toBe(0);
|
||||
});
|
||||
|
||||
it("claims in D1 when the store is d1", async () => {
|
||||
const { env, sqlite, store } = storeEnv();
|
||||
const claims = deliveryClaimStore(env);
|
||||
expect(await claims.claim("nonce:abc", 300)).toBe(true);
|
||||
expect(await claims.claim("nonce:abc", 300)).toBe(false);
|
||||
expect(rows(sqlite, "dedup_keys")).toBe(1);
|
||||
expect(store.has("nonce:abc")).toBe(false);
|
||||
});
|
||||
});
|
||||
|
||||
describe("messageTracker with an explicit store", () => {
|
||||
it("tracks messages in KV without a D1 row when useD1 is false", async () => {
|
||||
const { env, sqlite, store } = storeEnv({ mode: "kv" });
|
||||
const tracker = messageTracker(env.DB, env.KV, false);
|
||||
await tracker.set("evt-1", "discord:1", { messageId: "m1", version: 3 });
|
||||
expect(await tracker.get("evt-1", "discord:1")).toEqual({ messageId: "m1", version: 3 });
|
||||
expect(store.has("msg:evt-1:discord:1")).toBe(true);
|
||||
expect(store.has("storage:kv-fallback")).toBe(true);
|
||||
expect(rows(sqlite, "message_tracking")).toBe(0);
|
||||
|
||||
await tracker.move(
|
||||
{ eventId: "evt-1", targetId: "discord:1" },
|
||||
{ eventId: "evt-2", targetId: "discord:1" },
|
||||
{ messageId: "m1", version: 3 },
|
||||
);
|
||||
expect(store.has("msg:evt-1:discord:1")).toBe(false);
|
||||
expect(await tracker.get("evt-2", "discord:1")).toEqual({ messageId: "m1", version: 3 });
|
||||
|
||||
await tracker.delete("evt-2", "discord:1");
|
||||
expect(await tracker.get("evt-2", "discord:1")).toBeNull();
|
||||
expect(rows(sqlite, "message_tracking")).toBe(0);
|
||||
});
|
||||
|
||||
it("tracks messages in D1 when the store argument is omitted", async () => {
|
||||
const { env, sqlite, store } = storeEnv();
|
||||
const tracker = messageTracker(env.DB, env.KV);
|
||||
await tracker.set("evt-1", "discord:1", { messageId: "m1", version: 3 });
|
||||
expect(await tracker.get("evt-1", "discord:1")).toEqual({ messageId: "m1", version: 3 });
|
||||
expect(rows(sqlite, "message_tracking")).toBe(1);
|
||||
expect(store.has("msg:evt-1:discord:1")).toBe(false);
|
||||
expect(store.has("storage:kv-fallback")).toBe(false);
|
||||
});
|
||||
|
||||
it("falls back to KV when no D1 binding is given", async () => {
|
||||
const { env, store } = storeEnv({ db: {} as D1Database });
|
||||
const tracker = messageTracker(env.DB, env.KV);
|
||||
await tracker.set("evt-1", "discord:1", { messageId: "m1", version: 1 });
|
||||
expect(await tracker.get("evt-1", "discord:1")).toEqual({ messageId: "m1", version: 1 });
|
||||
expect(store.has("msg:evt-1:discord:1")).toBe(true);
|
||||
});
|
||||
});
|
||||
|
||||
describe("chainLock with an explicit store", () => {
|
||||
it("uses a KV marker without a D1 row when useD1 is false", async () => {
|
||||
const { env, sqlite, store } = storeEnv({ mode: "kv" });
|
||||
const lock = chainLock(env.DB, env.KV, false);
|
||||
const token = await lock.acquire("chain:1", 60);
|
||||
expect(token).not.toBeNull();
|
||||
expect(store.has("chain:1")).toBe(true);
|
||||
expect(await lock.acquire("chain:1", 60)).toBeNull();
|
||||
await lock.release("chain:1", "not-the-holder");
|
||||
expect(await lock.acquire("chain:1", 60)).toBeNull();
|
||||
await lock.release("chain:1", token as string);
|
||||
expect(store.has("chain:1")).toBe(false);
|
||||
expect(await lock.acquire("chain:1", 60)).not.toBeNull();
|
||||
expect(rows(sqlite, "dedup_keys")).toBe(0);
|
||||
});
|
||||
|
||||
it("uses a dedup_keys row when the store argument is omitted", async () => {
|
||||
const { env, sqlite, store } = storeEnv();
|
||||
const lock = chainLock(env.DB, env.KV);
|
||||
const token = await lock.acquire("chain:1", 60);
|
||||
expect(token).not.toBeNull();
|
||||
expect(rows(sqlite, "dedup_keys")).toBe(1);
|
||||
expect(store.has("chain:1")).toBe(false);
|
||||
expect(await lock.acquire("chain:1", 60)).toBeNull();
|
||||
await lock.release("chain:1", token as string);
|
||||
expect(rows(sqlite, "dedup_keys")).toBe(0);
|
||||
expect(await lock.acquire("chain:1", 60)).not.toBeNull();
|
||||
});
|
||||
|
||||
it("waits for a lock a kv-mode holder still has, in d1 mode", async () => {
|
||||
const { env, sqlite, store } = storeEnv();
|
||||
const lock = chainLock(env.DB, env.KV);
|
||||
store.set("storage:kv-fallback", String(Date.now() + 86_400_000));
|
||||
store.set("chain:1", "held-in-kv");
|
||||
expect(await lock.acquire("chain:1", 60)).toBeNull();
|
||||
expect(rows(sqlite, "dedup_keys")).toBe(0);
|
||||
|
||||
store.delete("chain:1");
|
||||
const token = await lock.acquire("chain:1", 60);
|
||||
expect(token).not.toBeNull();
|
||||
expect(rows(sqlite, "dedup_keys")).toBe(1);
|
||||
await lock.release("chain:1", token as string);
|
||||
expect(rows(sqlite, "dedup_keys")).toBe(0);
|
||||
});
|
||||
});
|
||||
Reference in new issue
Block a user