mirror of
https://github.com/Elysola/WebHooker.git
synced 2026-11-21 01:23:40 +00:00
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.
This commit is contained in:
1 parent
a8418c06d9
commit
a2ad4f699e
10 files changed
+78
-26
No files matched your search
@@ -161,7 +161,7 @@ tests/__snapshots__/ # formatter snapshot golden files (toMatchSnapshot)
|
|||||||
- Store named filter fragments (D1 `d1_fragments`, per group, `GET`/`PUT /admin/api/groups/:groupId/fragments`) as editor-side templates; inserting a fragment inlines its node into the route's `ast` — dispatch never resolves fragment references
|
- Store named filter fragments (D1 `d1_fragments`, per group, `GET`/`PUT /admin/api/groups/:groupId/fragments`) as editor-side templates; inserting a fragment inlines its node into the route's `ast` — dispatch never resolves fragment references
|
||||||
- Offer a stateless filter dry-run (`POST /admin/api/test-match`, body `{ node | filters, event?, payload }`) that evaluates in memory and returns `{ matched, explanation }` — no event payload is stored
|
- Offer a stateless filter dry-run (`POST /admin/api/test-match`, body `{ node | filters, event?, payload }`) that evaluates in memory and returns `{ matched, explanation }` — no event payload is stored
|
||||||
- Validate route/group config against valibot schemas on load (non-destructive: invalid entries log a warning but still load); `CONFIG_SCHEMA_VERSION` marks the schema version and `migrateRoutes`/`migrateGroups` migrate legacy shapes (e.g. `target` → `targets`)
|
- Validate route/group config against valibot schemas on load (non-destructive: invalid entries log a warning but still load); `CONFIG_SCHEMA_VERSION` marks the schema version and `migrateRoutes`/`migrateGroups` migrate legacy shapes (e.g. `target` → `targets`)
|
||||||
- Filter routes by group owner restriction (`Group.owners`), group source-platform restriction (`Group.providers`: github/gitea), GitHub App installation restriction (`Group.installationId`), and skip fallback routes whenever a regular route matched; stop evaluating further routes when a matched route has `stop: true`
|
- Filter routes by group owner restriction (`Group.owners`), group source-platform restriction (`Group.providers`: github/gitea), GitHub App installation restriction (`Group.installationId`), and skip a group's fallback routes whenever a regular route of that group matched; stop evaluating the group's further routes when a matched route has `stop: true` (both scoped per group, so one group's routes never silence another's)
|
||||||
- Auto-provision GitHub App installs: the App's Setup URL flow (`/auth/github/install` choice page + `POST /auth/github/install/bind`, owner-role verified for existing groups) and the `installation.created` webhook fallback both create `inst-{installationId}` groups or bind existing groups
|
- Auto-provision GitHub App installs: the App's Setup URL flow (`/auth/github/install` choice page + `POST /auth/github/install/bind`, owner-role verified for existing groups) and the `installation.created` webhook fallback both create `inst-{installationId}` groups or bind existing groups
|
||||||
- Enforce role-based access on every admin API: super admins bypass, `owner` manages the group (routes/members/invites/settings), `admin` edits routes, `viewer` is read-only; legacy `adminIds` groups resolve to `owner` members
|
- Enforce role-based access on every admin API: super admins bypass, `owner` manages the group (routes/members/invites/settings), `admin` edits routes, `viewer` is read-only; legacy `adminIds` groups resolve to `owner` members
|
||||||
- Issue single-use 7-day group invite links (`invite:{token}`); accepting joins as admin/viewer (never owner); `ALLOW_SELF_SIGNUP=1` creates a deterministic personal group (`u-{userId}`) on first login
|
- Issue single-use 7-day group invite links (`invite:{token}`); accepting joins as admin/viewer (never owner); `ALLOW_SELF_SIGNUP=1` creates a deterministic personal group (`u-{userId}`) on first login
|
||||||
|
|||||||
@@ -103,7 +103,7 @@ Routes are stored in D1 (`d1_routes`, seeded from legacy KV `config:routes` on f
|
|||||||
]
|
]
|
||||||
```
|
```
|
||||||
|
|
||||||
`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). 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](https://webhooker.docs.elysola.org/guide/routes) and [Groups & Access Control](https://webhooker.docs.elysola.org/guide/groups) guides for the full schema.
|
`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](https://webhooker.docs.elysola.org/guide/routes) and [Groups & Access Control](https://webhooker.docs.elysola.org/guide/groups) guides for the full schema.
|
||||||
|
|
||||||
### Web UI (`/admin`)
|
### Web UI (`/admin`)
|
||||||
|
|
||||||
|
|||||||
+1
-1
@@ -103,7 +103,7 @@ bunx wrangler dev # 启动本地开发服务器
|
|||||||
]
|
]
|
||||||
```
|
```
|
||||||
|
|
||||||
`target.platform` 选择推送目标:`discord`(默认)、`telegram` 或 `feishu`。Discord 目标需 `target.channelId`(可选 `threadId` 指向子区);Telegram 目标需 `target.chatId`(可选 `topicId` 指向话题);飞书目标需 `target.chatId`(可选 `topicId` 指向子话题)。路由还可设置 `stop: true`(跳过后续路由)。路由隶属于**分组**(D1 `d1_groups`,首次加载时从旧版 KV `config:groups` 同步),分组用于限定管理权限,并可限制哪些组织/用户的事件流入。完整模式见[路由与目标](https://webhooker.docs.elysola.org/zh/guide/routes)与[分组与访问控制](https://webhooker.docs.elysola.org/zh/guide/groups)指南。
|
`target.platform` 选择推送目标:`discord`(默认)、`telegram` 或 `feishu`。Discord 目标需 `target.channelId`(可选 `threadId` 指向子区);Telegram 目标需 `target.chatId`(可选 `topicId` 指向话题);飞书目标需 `target.chatId`(可选 `topicId` 指向子话题)。路由还可设置 `stop: true`(跳过本分组的后续路由)。路由隶属于**分组**(D1 `d1_groups`,首次加载时从旧版 KV `config:groups` 同步),分组用于限定管理权限,并可限制哪些组织/用户的事件流入。完整模式见[路由与目标](https://webhooker.docs.elysola.org/zh/guide/routes)与[分组与访问控制](https://webhooker.docs.elysola.org/zh/guide/groups)指南。
|
||||||
|
|
||||||
### Web 控制台(`/admin`)
|
### Web 控制台(`/admin`)
|
||||||
|
|
||||||
|
|||||||
@@ -219,9 +219,11 @@ const en: Dict = {
|
|||||||
"routeEditor.idHint": "Unique, use a-z / 0-9 / dashes",
|
"routeEditor.idHint": "Unique, use a-z / 0-9 / dashes",
|
||||||
"routeEditor.enabled": "Route enabled",
|
"routeEditor.enabled": "Route enabled",
|
||||||
"routeEditor.fallback": "Fallback route",
|
"routeEditor.fallback": "Fallback route",
|
||||||
"routeEditor.fallbackHint": "Only fires when no other route matched; filters still apply",
|
"routeEditor.fallbackHint":
|
||||||
|
"Only fires when no other route in this group matched; its filters still apply",
|
||||||
"routeEditor.stop": "Stop on match",
|
"routeEditor.stop": "Stop on match",
|
||||||
"routeEditor.stopHint": "When matched, no further routes are evaluated for this event",
|
"routeEditor.stopHint":
|
||||||
|
"When matched, later routes in this group are not evaluated for this event",
|
||||||
"routeEditor.filters": "Filters",
|
"routeEditor.filters": "Filters",
|
||||||
"routeEditor.filtersNote": "(all must match · AND)",
|
"routeEditor.filtersNote": "(all must match · AND)",
|
||||||
"routeEditor.matchPlaceholder": "match value (* ? wildcards, /regex/)",
|
"routeEditor.matchPlaceholder": "match value (* ? wildcards, /regex/)",
|
||||||
@@ -653,9 +655,9 @@ const zh: Dict = {
|
|||||||
"routeEditor.idHint": "唯一,使用 a-z / 0-9 / 短横线",
|
"routeEditor.idHint": "唯一,使用 a-z / 0-9 / 短横线",
|
||||||
"routeEditor.enabled": "启用路由",
|
"routeEditor.enabled": "启用路由",
|
||||||
"routeEditor.fallback": "兜底路由",
|
"routeEditor.fallback": "兜底路由",
|
||||||
"routeEditor.fallbackHint": "仅当没有其它路由匹配该事件时才发送,其过滤器仍会生效",
|
"routeEditor.fallbackHint": "仅当本分组没有其它路由匹配该事件时才发送,其过滤器仍会生效",
|
||||||
"routeEditor.stop": "匹配后停止",
|
"routeEditor.stop": "匹配后停止",
|
||||||
"routeEditor.stopHint": "该路由匹配后,不再评估后续路由",
|
"routeEditor.stopHint": "该路由匹配后,不再评估本分组的后续路由",
|
||||||
"routeEditor.filters": "过滤器",
|
"routeEditor.filters": "过滤器",
|
||||||
"routeEditor.filtersNote": "(全部匹配 · AND)",
|
"routeEditor.filtersNote": "(全部匹配 · AND)",
|
||||||
"routeEditor.matchPlaceholder": "匹配值(支持 * ? 通配符、/正则/)",
|
"routeEditor.matchPlaceholder": "匹配值(支持 * ? 通配符、/正则/)",
|
||||||
|
|||||||
+1
-1
@@ -106,7 +106,7 @@ routes:
|
|||||||
# - platform: telegram
|
# - platform: telegram
|
||||||
# chatId: "-1001234567890"
|
# chatId: "-1001234567890"
|
||||||
|
|
||||||
# Stop routes stop processing further routes when matched.
|
# Stop routes stop processing further routes of their group when matched.
|
||||||
# - id: exclusive-push
|
# - id: exclusive-push
|
||||||
# name: "Exclusive Push"
|
# name: "Exclusive Push"
|
||||||
# enabled: true
|
# enabled: true
|
||||||
|
|||||||
@@ -34,14 +34,14 @@ Each entry of `targets` is a push destination, so one route can forward to sever
|
|||||||
| Field | Type | Required | Description |
|
| Field | Type | Required | Description |
|
||||||
| ---------------- | -------- | -------- | ----------------------------------------------------------------------------------------------------------------- |
|
| ---------------- | -------- | -------- | ----------------------------------------------------------------------------------------------------------------- |
|
||||||
| `groupId` | string | Yes | Id of the [group](./groups) this route belongs to |
|
| `groupId` | string | Yes | Id of the [group](./groups) this route belongs to |
|
||||||
| `fallback` | boolean | No | When `true`, fires only if no non-fallback route matched the event; its own filters are ignored |
|
| `fallback` | boolean | No | When `true`, fires only if no non-fallback route of the same group matched the event; its filters still apply |
|
||||||
| `stop` | boolean | No | When `true` and this route matches, no further routes are evaluated for this event |
|
| `stop` | boolean | No | When `true` and this route matches, no further routes of the same group are evaluated for this event |
|
||||||
| `discordRoleIds` | string[] | No | Discord role ids to ping when this route fires; applied to Discord targets only |
|
| `discordRoleIds` | string[] | No | Discord role ids to ping when this route fires; applied to Discord targets only |
|
||||||
| `ast` | object | No | Boolean filter tree (`{all:[...]}` / `{any:[...]}` / `{not:{...}}`); takes precedence over `filters` when present |
|
| `ast` | object | No | Boolean filter tree (`{all:[...]}` / `{any:[...]}` / `{not:{...}}`); takes precedence over `filters` when present |
|
||||||
|
|
||||||
## Route Order
|
## Route Order
|
||||||
|
|
||||||
Routes are evaluated in the order the console shows them, group by group. To change it, click **Reorder** on the group page, drag routes by their handle (or focus a handle and press <kbd>↑</kbd> / <kbd>↓</kbd>), then **Save order**. The order is stored per group in D1 (`d1_routes.position`, migration `0012`); a database without that migration keeps loading routes in id order.
|
Routes are evaluated in the order the console shows them, group by group. `stop` and `fallback` act within a group: a matching `stop` route skips the later routes of its own group only, and a group's fallback routes stay silent only when one of that group's regular routes matched — one group never silences another. To change it, click **Reorder** on the group page, drag routes by their handle (or focus a handle and press <kbd>↑</kbd> / <kbd>↓</kbd>), then **Save order**. The order is stored per group in D1 (`d1_routes.position`, migration `0012`); a database without that migration keeps loading routes in id order.
|
||||||
|
|
||||||
## Discord Role Mentions
|
## Discord Role Mentions
|
||||||
|
|
||||||
|
|||||||
@@ -34,14 +34,14 @@
|
|||||||
| 字段 | 类型 | 必需 | 说明 |
|
| 字段 | 类型 | 必需 | 说明 |
|
||||||
| ---------------- | -------- | ---- | ------------------------------------------------------------------------------------- |
|
| ---------------- | -------- | ---- | ------------------------------------------------------------------------------------- |
|
||||||
| `groupId` | string | 是 | 路由所属[分组](./groups)的 id |
|
| `groupId` | string | 是 | 路由所属[分组](./groups)的 id |
|
||||||
| `fallback` | boolean | 否 | 为 `true` 时仅在没有其他非 fallback 路由匹配时才触发;其自身过滤器被忽略 |
|
| `fallback` | boolean | 否 | 为 `true` 时仅在本分组没有其他非 fallback 路由匹配时才触发;其过滤器仍会生效 |
|
||||||
| `stop` | boolean | 否 | 为 `true` 且该路由匹配时,不再评估后续路由 |
|
| `stop` | boolean | 否 | 为 `true` 且该路由匹配时,不再评估本分组的后续路由 |
|
||||||
| `discordRoleIds` | string[] | 否 | 路由触发时要提醒的 Discord 身份组 id;仅对 Discord 目标生效 |
|
| `discordRoleIds` | string[] | 否 | 路由触发时要提醒的 Discord 身份组 id;仅对 Discord 目标生效 |
|
||||||
| `ast` | object | 否 | 布尔过滤器树(`{all:[...]}` / `{any:[...]}` / `{not:{...}}`);存在时优先于 `filters` |
|
| `ast` | object | 否 | 布尔过滤器树(`{all:[...]}` / `{any:[...]}` / `{not:{...}}`);存在时优先于 `filters` |
|
||||||
|
|
||||||
## 路由顺序
|
## 路由顺序
|
||||||
|
|
||||||
路由按控制台中显示的顺序逐个分组评估。在分组页点击**调整顺序**,拖动路由左侧的手柄(或聚焦手柄后按 <kbd>↑</kbd> / <kbd>↓</kbd>),再点击**保存顺序**。顺序按分组保存在 D1(`d1_routes.position`,迁移 `0012`);未执行该迁移的数据库会继续按 id 顺序加载路由。
|
路由按控制台中显示的顺序逐个分组评估。`stop` 与 `fallback` 只在分组内生效:匹配的 `stop` 路由只跳过本分组的后续路由;只有本分组的普通路由匹配时,本分组的兜底路由才不发送——一个分组永远不会屏蔽另一个分组。在分组页点击**调整顺序**,拖动路由左侧的手柄(或聚焦手柄后按 <kbd>↑</kbd> / <kbd>↓</kbd>),再点击**保存顺序**。顺序按分组保存在 D1(`d1_routes.position`,迁移 `0012`);未执行该迁移的数据库会继续按 id 顺序加载路由。
|
||||||
|
|
||||||
## Discord 身份组提醒
|
## Discord 身份组提醒
|
||||||
|
|
||||||
|
|||||||
@@ -61,10 +61,15 @@ export async function dispatchEvent(
|
|||||||
if (!groupAcceptsOwners(group, owners)) return false;
|
if (!groupAcceptsOwners(group, owners)) return false;
|
||||||
return groupAcceptsProvider(group, event.provider);
|
return groupAcceptsProvider(group, event.provider);
|
||||||
};
|
};
|
||||||
const matched = config.routes.filter(
|
// `stop` and `fallback` act within a route's own group (its routing table), so
|
||||||
(route) => !route.fallback && matchRoute(route, event) && accepted(route),
|
// one group's routes can never silence another group's.
|
||||||
|
const scopeOf = (route: Route): string => route.groupId ?? "";
|
||||||
|
const regularMatched = new Set(
|
||||||
|
config.routes
|
||||||
|
.filter((route) => !route.fallback && matchRoute(route, event) && accepted(route))
|
||||||
|
.map(scopeOf),
|
||||||
);
|
);
|
||||||
const anyRegularMatched = matched.length > 0;
|
const stopped = new Set<string>();
|
||||||
|
|
||||||
const attempts: DispatchAttempt[] = [];
|
const attempts: DispatchAttempt[] = [];
|
||||||
const sendLogs: SendRecord[] = [];
|
const sendLogs: SendRecord[] = [];
|
||||||
@@ -88,16 +93,17 @@ export async function dispatchEvent(
|
|||||||
|
|
||||||
const tasks: Promise<void>[] = [];
|
const tasks: Promise<void>[] = [];
|
||||||
for (const route of config.routes) {
|
for (const route of config.routes) {
|
||||||
if (!accepted(route)) continue;
|
const scope = scopeOf(route);
|
||||||
|
if (stopped.has(scope) || !accepted(route)) continue;
|
||||||
if (route.fallback) {
|
if (route.fallback) {
|
||||||
if (!anyRegularMatched && matchRoute(route, event)) {
|
if (!regularMatched.has(scope) && matchRoute(route, event)) {
|
||||||
tasks.push(processRoute(route));
|
tasks.push(processRoute(route));
|
||||||
}
|
}
|
||||||
continue;
|
continue;
|
||||||
}
|
}
|
||||||
if (matchRoute(route, event)) {
|
if (matchRoute(route, event)) {
|
||||||
tasks.push(processRoute(route));
|
tasks.push(processRoute(route));
|
||||||
if (route.stop) break;
|
if (route.stop) stopped.add(scope);
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
await Promise.allSettled(tasks);
|
await Promise.allSettled(tasks);
|
||||||
|
|||||||
+8
-6
@@ -67,15 +67,17 @@ export interface Route {
|
|||||||
*/
|
*/
|
||||||
ast?: FilterNode;
|
ast?: FilterNode;
|
||||||
/**
|
/**
|
||||||
* Fallback route: only fires when no other (non-fallback) route matched the
|
* Fallback route: only fires when no other (non-fallback) route of the same
|
||||||
* event. Multiple fallback routes may exist; they are all skipped whenever at
|
* group matched the event. Multiple fallback routes may exist; a group's are
|
||||||
* least one regular route matches. Its own filters are ignored.
|
* all skipped whenever one of its regular routes matches. Its own filters
|
||||||
|
* still apply.
|
||||||
*/
|
*/
|
||||||
fallback?: boolean;
|
fallback?: boolean;
|
||||||
/**
|
/**
|
||||||
* Stop: when true and this route matches, no further routes are evaluated
|
* Stop: when true and this route matches, no further routes of the same
|
||||||
* for this event. Useful for exclusive routing where a match should prevent
|
* group are evaluated for this event (other groups are unaffected). Useful
|
||||||
* fallthrough to subsequent routes.
|
* for exclusive routing where a match should prevent fallthrough to the
|
||||||
|
* group's subsequent routes.
|
||||||
*/
|
*/
|
||||||
stop?: boolean;
|
stop?: boolean;
|
||||||
/**
|
/**
|
||||||
|
|||||||
@@ -215,6 +215,48 @@ describe("dispatchEvent fallback routing", () => {
|
|||||||
expect(sent.filter((u) => u.includes("/222/"))).toHaveLength(1);
|
expect(sent.filter((u) => u.includes("/222/"))).toHaveLength(1);
|
||||||
});
|
});
|
||||||
|
|
||||||
|
it("scopes stop and fallback to the route's own group", async () => {
|
||||||
|
const sent: string[] = [];
|
||||||
|
mockFetch((url) => {
|
||||||
|
sent.push(url);
|
||||||
|
return new Response("{}", { status: 200 });
|
||||||
|
});
|
||||||
|
const env = createEnv({ KV: createMockKV(), DB: createMockDB() });
|
||||||
|
const route = (
|
||||||
|
id: string,
|
||||||
|
groupId: string,
|
||||||
|
extra: Partial<Route>,
|
||||||
|
channelId: string,
|
||||||
|
): Route => ({
|
||||||
|
id,
|
||||||
|
name: id,
|
||||||
|
enabled: true,
|
||||||
|
filters: [{ type: "event", match: "push" }],
|
||||||
|
targets: [{ channelId }],
|
||||||
|
groupId,
|
||||||
|
...extra,
|
||||||
|
});
|
||||||
|
const routes: Route[] = [
|
||||||
|
route("alpha-stop", "alpha", { stop: true }, "301"),
|
||||||
|
route("alpha-later", "alpha", {}, "302"),
|
||||||
|
route("zeta-push", "zeta", {}, "303"),
|
||||||
|
route("zeta-catch-all", "zeta", { fallback: true, filters: [] }, "304"),
|
||||||
|
route("omega-catch-all", "omega", { fallback: true, filters: [] }, "305"),
|
||||||
|
route("omega-catch-all-2", "omega", { fallback: true, filters: [] }, "306"),
|
||||||
|
];
|
||||||
|
|
||||||
|
await dispatchEvent({ ...baseConfig, routes }, { event: "push", payload: {} }, env);
|
||||||
|
const hits = (channel: string): number => sent.filter((u) => u.includes(`/${channel}/`)).length;
|
||||||
|
// alpha stops after its first match without silencing zeta.
|
||||||
|
expect(hits("301")).toBe(1);
|
||||||
|
expect(hits("302")).toBe(0);
|
||||||
|
expect(hits("303")).toBe(1);
|
||||||
|
// zeta matched a regular route, omega did not: only omega's fallbacks fire.
|
||||||
|
expect(hits("304")).toBe(0);
|
||||||
|
expect(hits("305")).toBe(1);
|
||||||
|
expect(hits("306")).toBe(1);
|
||||||
|
});
|
||||||
|
|
||||||
it("prepends role mentions to the Discord message content", async () => {
|
it("prepends role mentions to the Discord message content", async () => {
|
||||||
const bodies: string[] = [];
|
const bodies: string[] = [];
|
||||||
mockFetch((url, init) => {
|
mockFetch((url, init) => {
|
||||||
|
|||||||
Reference in new issue
Block a user