Files
WebHooker/README.md
T
翅膀喵 dbf162bf74 feat(admin-console): improve route and filter management (#10)
* fix(nuxt): pre-bundle the CommonJS deps of the markdown stack

`debug` and `extend` are imported by micromark and unified through
@elysola/ui. Served unbundled by the dev server they have no default
export, so the console page failed with a 500 in `nuxt dev`.

* docs(deployment): list the fragments and feishu link migrations

The manual `d1 execute` fallback stopped at 0008, and AGENTS.md named
0001..0010 although 0011 already exists.

* feat(storage): persist the per-group route order

Routes used to load in id order, so the order saved from the console
was lost on the next read. Migration 0012 adds `d1_routes.position`:
saving writes each route's index within its own group (saving one group
never shifts another), and routes load by `group_id, position, id`.

A database without the column keeps working: only a "no such column" /
"has no column named" error falls back to the legacy statements, and
nothing is cached, so a later migration is picked up on the next call.

* feat(console): add in-app destructive-action confirmation

Deleting a route or a group used `window.confirm`, which blocks the page
and ignores the console theme. A promise-based `useConfirm()` now drives
one <ConfirmDialog /> built on the reka-ui AlertDialog that
@elysola/ui ships; reka-ui is pre-bundled so dev keeps a single copy and
the dialog stacks with the Rc dialogs.

A request never outlives its asker: one made after the asking component
unmounted resolves false, and one still open when it unmounts is
cancelled.

* feat(console): confirm member and webhook removal

Removing a member, revoking an invite link and disabling a group's
webhook endpoint took effect on the first click. They now ask first;
disabling the webhook explains that senders still using the secret will
be rejected, and its button is styled as destructive.

* feat(console): confirm removing filled editor rows

Filter conditions and groups, delivery targets, saved fragments and forge
hosts vanished on a single click, taking whatever had been typed with
them. Rows holding content now ask first, while empty, never-filled
rows (`isBlankNode`: default operator, no path, no values, not negated)
are still removed directly.

* fix(i18n): remove duplicate button glyphs

"New Route", "New Group" and the group cards' "Open" link render a Plus
or ArrowRight icon next to their label, so the "+" and "→" baked into
the strings appeared twice.

* style(console): redesign route cards for narrow screens

The card was one flex row whose badges, filter chips, targets and five
hand-drawn icon buttons squeezed the route name on small screens. It is
now a grid driven by a container query: name and actions share the top
line, the filter summary (clamped to two lines) and targets follow, and
the tags wrap below; from 40rem the tags move up beside the title.

Targets of the same platform collapse into one tag with a count, long
ids truncate instead of widening the page, and the actions use lucide
icons with accessible labels.

* feat(console): reorder a group's routes by drag or keyboard

The per-card up/down arrows saved after every single step, so moving a
route five places took five writes. A Reorder mode on the group page now
swaps each card's switch for a drag handle: pointer drags (mouse and
touch) slide the neighbours out of the way and auto-scroll near the
viewport edges, Arrow Up/Down on a focused handle moves a card by one
and is announced to screen readers, and nothing is written until Save
order. Cancel or Escape (unless a dialog or list owns it) drops the
draft.

The cards move into a new RouteList component that owns the drag state.

* style(members): align member cards and invite actions

* style(group-editor): size forge and log target controls

Keep source hosts, platform selectors and remove actions aligned without stretching short controls across the dialog. Wrap component roots explicitly so their internal markup cannot break the grid.

* style(route-editor): group options and delivery target fields

Give each target labeled fields and a compact platform header, widen the filter workspace, and align fragment controls. Scroll failed validation into view when the footer is far from the affected section.

* feat(filters): add bilingual suggestions and value validation

Catalog forge events, actions, payload paths and known values with searchable English and Chinese descriptions. Match-value validation mirrors the server and only rejects inputs that cannot match.

* feat(filters): add searchable creatable value inputs

Build a theme-aligned combobox on the shared reka-ui primitives. Rank stored keys before bilingual descriptions, allow validated custom values, and preserve unconfirmed multi-value drafts instead of silently committing them.

* feat(filter-editor): integrate searchable condition inputs

Replace chip-only values with context-aware bilingual inputs and a compact condition grid. Preserve drafts across tree changes, block saves and tests until drafts are resolved, and keep keyword filters free of hidden operators.

* feat(filters): split pasted values without breaking regexes

Accept multiple values separated by commas or lines while retaining commas inside wrapped expressions and raw regex patterns. Pasting replaces the selected range and keeps rejected values as an explicit draft.

* fix(filters): adapt suggestions to the selected operator

Offer literal prefixes and suffixes for substring operators, escaped anchored patterns for regex, and numeric suggestions only for comparisons. Suggestion syntax must mean what the selected matcher actually reads.

* fix(filters): preserve regex meaning when changing operators

Swap wrapped and raw regex sources only when both compile identically after saving. Leave literal, glob, multiline and Unicode-sensitive comparisons unchanged rather than inventing non-equivalent conversions.

* a11y(filter-editor): label type and operator controls

Associate each fixed select with a stable per-condition label while keeping the compact visual layout unchanged.

* fix(editors): ignore accidental backdrop dismissal

Do not discard unsaved route or group edits when the user clicks outside the dialog. Preserve Escape, Cancel and explicit close, including popovers and confirmation dialogs stacked above the editor.

* feat(dispatch)!: scope stop and fallback to each group

A match in one group must not suppress delivery in another group. Track regular matches and stopped scopes independently, and document the routing-table boundary.

BREAKING CHANGE: stop and fallback no longer apply globally across
groups. Put mutually exclusive routes in the same group and define
fallback routes in each group that needs its own catch-all.

* fix(dispatch): honor stop on a matching fallback route

Once a fallback matches with stop enabled, skip later routes of the same group without affecting other groups. Cover multiple fallback routes in the group-isolation regression test.

* style(console): pin theme and language controls to the right

Separate utility controls from page actions so narrow screens retain a readable title column and right-aligned actions below. Wrap long headings without letting them push controls out of view.

* style(groups): place creation beside the aligned group count

Keep the new-group action inside the group list at every width and align the label and count on one baseline with a consistent type scale.

* style(groups): align card footers and keep role badges intact

Give long names two lines, show the current role in its own non-wrapping row, and anchor every card footer to the grid-row bottom regardless of optional source metadata.

* style(logs): prevent filter labels and metadata overflow

Keep filter labels on one line and allow long channel, thread and repository identifiers to wrap instead of widening the page.

* style(console): scale the sidebar and hide mobile tab tracks

Narrow the sidebar proportionally while retaining enough room for both locales. Keep mobile navigation swipeable without a visible horizontal scrollbar.

* feat(console): give each group its own routes URL

Resolve the selected group from /admin/groups/{groupId}, validate console paths, and use browser history for back navigation. Keep Groups active and let an active mobile-tab tap return to the list. Scope pending route loads to their group and retain the count beside long headings.

* feat(console): confirm leaving unsaved page work

Guard route changes when an editor or changed order draft is open. Cancel superseded questions and restore the shown history entry when repeated Back or Forward navigation is refused; only completed navigation resets page work.

* feat(console): confirm sign-out from desktop and mobile

Expose sign-out in the mobile topbar when the sidebar is hidden. Both entry points use the in-app confirmation before navigating to the server logout endpoint.

* fix(console): keep topbar tools clear of very narrow headings

Below 360px, place the full-width heading beneath the breadcrumb and utility row so the three top-right buttons cannot overlap it.

* feat(console): prioritize group titles over actions

Place New Route after Reorder in the group bar. Measure available space and remove the reorder label first, then the creation label, before truncating the group title; remeasure on resize, locale and font changes.

* fix(editors): focus the dialog without selecting its name field

Cancel the non-bubbling FocusScope mount event in the capture phase and focus the dialog itself. Keep keyboard navigation working without highlighting the name or opening the touch keyboard automatically.

* perf(console): preserve one instance across admin navigation

Use a fixed page key instead of remounting the whole console for each URL. Refresh each view when shown and isolate overview metrics and logs so page filters cannot leak into the dashboard.

* fix(console-data): discard superseded load responses

Only the latest request may update a list, its error or loading state. Invalidate pending group loads after a save so an older response cannot restore stale configuration during persistent-console navigation.

* fix(routes): serialize writes and reject unloaded route lists

Whole-list saves must start from loaded data and wait for other route writes. Lock switches and actions during saves, recheck deletion after confirmation, and rebuild saved ordering from the newest route objects.

* fix(editors): scope async results and fragment writes to sessions

A completed save or dry run must not close or overwrite a newer editor. Keep fragment state scoped by group, reject writes until the real list is ready, and retain in-flight fragment locks across navigation.

* fix(groups): serialize edits and isolate group detail panels

Prevent overlapping whole-list writes, avoid duplicate ids after rename, and discard delete confirmations prepared on a page that has since been left. Key member and webhook panels by group so local state cannot cross tenants.

* fix(console): omit the empty action row outside overview

Render the refresh-action container only where it has content so narrow layouts do not reserve a blank row after creation controls move into their page bars.

* perf(metrics): send all seven queries in one D1 batch

Avoid seven sequential network round trips and read totals, breakdowns and recent failures in one consistent transaction. Reuse the failed-send statement and row mapping while retaining group scoping.

* fix(admin-api): bypass browser cache locks for live requests

Use no-store on both client requests and admin responses. Personalized live data must not be reused, and one stalled same-URL cache entry must not block later log requests behind the browser cache lock.

* docs(routes): Clarify fallback hints and document group-scoped stop and fallback upgrade behavior
2026-10-17 21:13:20 +08:00

17 KiB
Raw Blame History

WebHooker

GitHub / Gitea webhook → Discord / Telegram / Feishu dispatcher. Receives webhook events via Cloudflare Workers, applies filters, and routes formatted messages to Discord channels/threads, Telegram chats/topics, and Feishu chat cards. Forge-specific adapters live under server/lib/providers/ (GitHub + Gitea today; GitLab etc. can be added later).

Features

  • 28 event formatters — push, pull_request, issues, issue_comment, workflow_run, workflow_job, status, deployment, deployment_status, check_run, check_suite, ping, release, create, delete, star, fork, pull_request_review, pull_request_review_comment, commit_comment, member, label, milestone, discussion, discussion_comment, repository, code_scanning_alert, dependabot_alert (+ generic fallback, + custom webhooks)
  • Multi-provider webhooks — GitHub (X-Hub-Signature-256) and Gitea (X-Gitea-Signature) share one /webhook endpoint; the provider is auto-detected from headers
  • Per-group webhook ingress — every group can get its own POST /webhook/{groupId} URL + secret (Gitea, classic GitHub webhooks, and arbitrary custom JSON posts signed with X-WebHooker-Signature, with optional timestamp+nonce replay protection)
  • GitHub App tenant isolation — bind a group to a GitHub App installation id so only that org/user's events enter it
  • HMAC-SHA256 signature verification (Web Crypto API)
  • Filter by event type, repo, actor, action, branch, keyword, or any payload field (field with a JSONPath path, e.g. pull_request.user.login); supports */? globs and /regex/ patterns plus 12 comparison operators (eq/ne/contains/startsWith/endsWith/regex/gt/gte/lt/lte/in/exists)
  • Combine filters into a boolean AST (all / any / not nodes) via the route editor's visual builder; reuse named filter fragments and dry-run any filter against a pasted JSON payload without storing it
  • Rich messages with color coding, author avatars, fields, and timestamps — rendered as Discord embeds and Telegram HTML
  • Route to Discord channels/threads, Telegram chats/topics, and Feishu group chats (multi-target routes)
  • workflow_run / check_run progress is edited in place (single message updated as the run advances) on Discord, Telegram, and Feishu — check_run tracks by check name + commit SHA so deployments that issue a fresh run id per phase (e.g. Cloudflare Pages) still edit the same message; workflow_run embeds a colored per-job code block (🟢 success, 🔴 failure, running/queued inline)
  • Per-group webhook log channel — point a group at a Discord channel/thread, Telegram chat/topic, or Feishu chat and every webhook the group's routes dispatch is summarized there (✅/❌ per route × target)
  • GitHub OAuth for user actions (comment, edit comment, delete comment, merge, close, react)
  • 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
  • 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)

Architecture

GitHub Webhook → Cloudflare Worker (Nuxt 4 / Nitro)
                  ├── POST /webhook → verify → dedup → enqueue (Queue) → dispatch → Discord (REST) / Telegram (Bot API) / Feishu (Bot API)
                 ├── POST /discord/interactions → verify (Ed25519) → handle command/button/modal
                 ├── POST /telegram/webhook → verify (secret token) → handle /gh commands
                 ├── GET  /auth/github → OAuth flow
                 ├── GET  /api/richheader → Telegram avatar link-preview card
                 ├── POST /api/* → user actions (Bearer token auth)
                 ├── /admin → routes, groups & send logs Web UI
                 └── GET  /health → status check
  • 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}), per-group webhook secrets (tenant:{groupId}), invites, config cache, delivery dedup/state/message-tracking fallback (delivery:*, delivery-state:*, msg:* used only when D1 is unavailable) and message-update locks (msg:lock:*)
  • D1 — source of truth for routes/groups (d1_routes/d1_groups), 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:*)

Quick Start

bun install          # package manager is bun (lockfile: bun.lock)
cp .env.example .dev.vars   # Fill in secrets for local dev
bun run build        # Production build first (wrangler dev serves the built worker)
bunx wrangler dev    # Start local dev server

Configuration

Secrets (.dev.vars for local, Worker Secrets for production)

Variable Description
GITHUB_WEBHOOK_SECRET Webhook secret from GitHub
GITEA_WEBHOOK_SECRET Webhook secret from Gitea (required only to receive Gitea webhooks)
GITHUB_APP_ID GitHub App ID (used by the App install flow to resolve the installing account)
GITHUB_PRIVATE_KEY App private key (PKCS#8 PEM; used by the App install flow; optional)
GITHUB_CLIENT_ID OAuth client ID
GITHUB_CLIENT_SECRET OAuth client secret
DISCORD_TOKEN Bot token
DISCORD_PUBLIC_KEY Discord application public key (from the Developer Portal) — required for interactions
DISCORD_APPLICATION_ID Discord application id (optional; auto-resolved via GET /oauth2/applications/@me if omitted)
TELEGRAM_TOKEN Telegram bot token (from BotFather) — required for Telegram routes
TELEGRAM_WEBHOOK_SECRET Optional secret token for POST /telegram/webhook verification
TELEGRAM_RICH_HEADER_HOST Optional base URL overriding the built-in GET /api/richheader for Telegram avatar cards
FEISHU_APP_ID Feishu app ID (from the app Credentials page) — required for Feishu routes
FEISHU_APP_SECRET Feishu app secret — required for Feishu routes
BASE_URL Public URL for OAuth callbacks and the Telegram webhook sync
ADMIN_USER_IDS Comma-separated GitHub user IDs (or logins) allowed to access /admin
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)
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

Routes

Routes are stored in D1 (d1_routes, seeded from legacy KV config:routes on first load). There are no default routes — every route (including its target) must be defined explicitly, either via the Web UI (/admin) or by storing a JSON array in D1. A route may carry multiple targets, so one rule can forward to several channels at once:

[
  {
    "id": "all-push",
    "name": "Push Events",
    "enabled": true,
    "groupId": "default",
    "filters": [{ "type": "event", "match": "push" }],
    "stop": true,
    "targets": [
      { "platform": "discord", "channelId": "CHANNEL_ID" },
      { "platform": "telegram", "chatId": "-1001234567890" },
      { "platform": "feishu", "chatId": "oc_xxx" }
    ]
  }
]

target.platform selects the push target: discord (default), telegram, or feishu. Discord targets require target.channelId (optional threadId for a thread); Telegram targets require target.chatId (optional topicId for a topic); Feishu targets require target.chatId (optional topicId for a topic). A route may also set stop: true (skip later routes of its group). Routes belong to groups (D1 d1_groups, seeded from legacy KV config:groups) that scope admin access and can restrict which org/user events flow in. See the Routes & Targets and Groups & Access Control guides for the full schema.

Web UI (/admin)

The built-in config console lets you manage routes and groups in the browser (add / edit / delete / toggle / drag to reorder — the saved order is the evaluation order), inspect send logs, manage group members and invite links, and read the audit log — no KV access needed:

  1. Set ADMIN_USER_IDS to the GitHub user IDs (or logins) allowed to manage the console, e.g. ADMIN_USER_IDS=12345,RhenCloud.
  2. Visit /admin and sign in with GitHub. Users with no access get 403 — unless ALLOW_SELF_SIGNUP=1 (they receive a personal group) or they follow a group invite link.
  3. Changes are written to D1 immediately, the config cache is invalidated, and the webhook pipeline picks them up on the next run.

For local-only debugging, DEBUG_MODE=true bypasses GitHub OAuth and grants full console access. Never set it in a deployed environment.

Sign out at /admin/logout. Every group has members with a role (owner / admin / viewer); all admin operations are recorded in the D1 audit_logs table.

Filter Types

Every filter supports plain text, */? globs, and /regex/ patterns (case-insensitive); set exclude: true to invert. A field filter reads any payload value by JSONPath (arrays expand so any element matches) and accepts an op operator (default eq); op: "exists" checks presence without a match. Filters can also be grouped into an AST via an optional ast on a route (all / any / not nodes) to express boolean combinations beyond the default AND-list — when present, ast takes precedence over filters. The route editor provides a visual AST builder, chip multi-value input, a stateless match tester, and named filter fragments (stored in D1 d1_fragments). See the Filter Tutorial for the pattern syntax and the full filter reference.

API

Health

  • GET /health — Returns {"status": "ok"}

OAuth

  • GET /auth/github — Start GitHub OAuth flow (redirects to GitHub)
  • GET /auth/github/callback — OAuth callback (exchanges code for token; admin session / Discord link / Telegram link)
  • DELETE /auth/token/:userId — Revoke user token

Actions (require Authorization: Bearer <token> header)

  • POST /api/comment — Create issue comment
  • POST /api/merge — Merge pull request
  • POST /api/close — Close pull request
  • POST /api/react — Add reaction to issue

Admin (require admin OAuth session)

  • GET /admin — Config console UI
  • GET /admin/login — Start admin sign-in (GitHub OAuth)
  • GET /admin/logout — Sign out
  • GET /admin/invite?token=… — Accept a group invite (browser page)
  • GET /admin/api/routes — List routes
  • PUT /admin/api/routes — Replace routes (owner/admin per group)
  • GET /admin/api/groups — List groups + your role in each
  • PUT /admin/api/groups — Replace groups (super: all; owner: own groups only)
  • GET /admin/api/groups/:groupId/routes — List a group's routes
  • PUT /admin/api/groups/:groupId/routes — Replace a group's routes
  • POST /admin/api/groups/:groupId/invites — Create invite link (owner)
  • GET /admin/api/groups/:groupId/invites — List pending invites (owner)
  • DELETE /admin/api/invites/:token — Revoke an invite (owner)
  • GET /admin/api/audit — Audit log (scoped)
  • GET /admin/api/me — Current session / scope / roles
  • GET /admin/api/logs — Send logs (scoped)
  • GET /admin/api/logs/:id — Single send-log entry
  • GET /admin/api/metrics — Delivery stats (totals, failure rate, per-platform/event/status, recent failures); optional ?groupId= scope
  • GET /admin/api/delivery/:deliveryId — All send-log attempts for one delivery

Setup Guides

  • GitHub App — create the app, subscribe to events, configure OAuth, and set the Setup URL for tenant isolation: see GitHub App Setup
  • Discord bot — create the bot, invite it with applications.commands (combined permission integer 274877910016), and configure the Interactions Endpoint: see Discord Bot Setup. The bot never connects to the Discord Gateway, so it shows as offline — messaging is unaffected (always REST).
  • Telegram bot — create the bot with @BotFather, set TELEGRAM_TOKEN (optional TELEGRAM_WEBHOOK_SECRET); the webhook is synced automatically by the scheduled trigger: see Telegram Bot Setup
  • Feishu bot — create a custom app, enable the bot, add it to the target group, and set FEISHU_APP_ID + FEISHU_APP_SECRET: see Feishu Bot Setup
  • Deployment — KV namespace, D1 database + migrations, optional Queues, secrets, and deploy: see the Deployment guide

Bot Commands (comment on GitHub as yourself)

The bot registers native slash and message context-menu commands, synced by the scheduled trigger (every 5 minutes): per-guild for instant availability, and globally (24h dedup, ~1h propagation). After /gh login you can comment on issues/PRs as yourself, edit/delete your comments, and merge/close PRs via buttons — all replies are ephemeral and GitHub enforces permission.

/gh login  /gh logout
/gh comment add|edit|del  link:<url>      (or right-click a notification → Apps → GitHub: 添加/编辑/删除评论)

See the full reference in the Bot Commands guide.

Development

bun run dev           # Nuxt dev server (HMR)
bun run typecheck     # Type checking
bun run lint          # ESLint
bun test              # Unit tests

Supported Events

28 event formatters (push, pull_request, issues, workflow_run, release, ...) plus custom webhooks; unsupported events fall back to a generic formatter. See the full table with embed highlights in Supported Events.

License

MIT