mirror of
https://github.com/Elysola/WebHooker.git
synced 2026-11-20 17:13:49 +00:00
docs(worker): align guides with runtime behavior
Synchronize both language guides, API references and examples with the implemented authorization, storage and delivery behavior. Document migration requirements and accepted operational limits.
This commit is contained in:
1 parent
a62044f359
commit
5fcb129170
47 files changed
+938
-660
No files matched your search
+42
-32
@@ -6,41 +6,51 @@ The console itself is served at `/admin`; its tabs are deep-linkable via the URL
|
||||
|
||||
## Endpoints
|
||||
|
||||
| Endpoint | Description |
|
||||
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `GET /admin` | Config console UI |
|
||||
| `GET /admin/login` | Start admin sign-in (GitHub OAuth) |
|
||||
| `GET /admin/logout` | Sign out and destroy the session |
|
||||
| `GET /admin/invite?token=…` | Accept a group invite (browser page) |
|
||||
| `GET /admin/api/me` | Current session, scope, groups, and roles |
|
||||
| `GET /admin/api/routes` | List routes (scoped to access) |
|
||||
| `PUT /admin/api/routes` | Replace routes (owner/admin per group) |
|
||||
| `GET /admin/api/groups` | List groups + the signed-in user's role in each |
|
||||
| `PUT /admin/api/groups` | Replace groups (super: all; owner: own only) |
|
||||
| `GET /admin/api/groups/:id/routes` | List a group's routes |
|
||||
| `PUT /admin/api/groups/:id/routes` | Replace a group's routes (owner/admin) |
|
||||
| `GET /admin/api/groups/:id/fragments` | List a group's named filter fragments |
|
||||
| `PUT /admin/api/groups/:id/fragments` | Replace a group's named filter fragments (owner/admin) |
|
||||
| `PUT /admin/api/groups/:id/rename` | Rename a group (owner); routes, webhook secret and invites follow (routes are moved before the group record is updated) |
|
||||
| `GET /admin/api/groups/:id/invites` | List pending invites (owner) |
|
||||
| `POST /admin/api/groups/:id/invites` | Create an invite link (owner) |
|
||||
| `DELETE /admin/api/invites/:token` | Revoke an invite (owner) |
|
||||
| `GET /admin/api/groups/:id/webhook` | Group webhook endpoint info (owner) |
|
||||
| `POST /admin/api/groups/:id/webhook/regenerate` | Generate/regenerate the group webhook secret (owner) |
|
||||
| `DELETE /admin/api/groups/:id/webhook` | Disable the group webhook ingress (owner) |
|
||||
| `GET /admin/api/logs` | Send logs (scoped to accessible routes) |
|
||||
| `GET /admin/api/logs/:id` | Single send-log entry (scoped) |
|
||||
| `GET /admin/api/audit` | Audit log (scoped to accessible groups) |
|
||||
| `GET /admin/api/metrics` | Delivery stats (totals, failure rate, per platform/event/status, recent failures); optional `?groupId=` scope; recent failures scoped to accessible groups for non-super |
|
||||
| `GET /admin/api/delivery/:deliveryId` | All send-log attempts for one delivery (group-scoped) |
|
||||
| `POST /admin/api/test-match` | Stateless filter dry-run — evaluate a filter node against a pasted JSON payload (no event is stored) |
|
||||
| Endpoint | Description |
|
||||
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `GET /admin` | Config console UI |
|
||||
| `GET /admin/login` | Start admin sign-in (GitHub OAuth) |
|
||||
| `GET /admin/logout` | Sign out and destroy the session |
|
||||
| `GET /admin/invite?token=…` | Accept a group invite (browser page) |
|
||||
| `GET /admin/api/me` | Current session, scope, groups, and roles |
|
||||
| `GET /admin/api/routes` | List routes (scoped to access) |
|
||||
| `PUT /admin/api/routes` | Replace routes (owner/admin per group) |
|
||||
| `GET /admin/api/groups` | List groups (each with its `revision`) + the signed-in user's role in each, plus the list `revision` |
|
||||
| `PUT /admin/api/groups` | Bulk write (legacy): super admins replace all groups, owners change/delete their own; only groups that differ are written |
|
||||
| `POST /admin/api/groups` | Create one group (super admins) — body `{ group }`; `409` when the id exists or was used recently |
|
||||
| `PUT /admin/api/groups/:id` | Update one group (owner) — body `{ group }`; `409` when its `revision` is stale |
|
||||
| `DELETE /admin/api/groups/:id` | Delete one group with its routes and fragments (owner) — query `revision`, `routesRevision` and `version` from the confirmation; `409` when anything changed since |
|
||||
| `GET /admin/api/groups/:id/routes` | List a group's routes, with the list's `revision`, the group `version` and `unreadable` |
|
||||
| `PUT /admin/api/groups/:id/routes` | Replace a group's routes (owner/admin) — `409` when the sent `revision` is stale |
|
||||
| `GET /admin/api/groups/:id/fragments` | List a group's named filter fragments, with the list's `revision` |
|
||||
| `PUT /admin/api/groups/:id/fragments` | Replace a group's named filter fragments (owner/admin) — body `{ fragments, revision? }`; `409` when the `revision` is stale |
|
||||
| `PUT /admin/api/groups/:id/rename` | Rename a group (owner) — body `{ newId, revision? }`; routes, fragments and history move in one transaction, the secret and invites stay with the group; the old id stays retired for a few days |
|
||||
| `GET /admin/api/groups/:id/invites` | List pending invites (owner) |
|
||||
| `POST /admin/api/groups/:id/invites` | Create an invite link (owner) — body `{ role, note? }` (`role` is `admin` or `viewer`) |
|
||||
| `DELETE /admin/api/invites/:token` | Revoke an invite (owner) |
|
||||
| `GET /admin/api/groups/:id/webhook` | Group webhook endpoint info (owner) |
|
||||
| `POST /admin/api/groups/:id/webhook/regenerate` | Generate/regenerate the group webhook secret (owner) |
|
||||
| `DELETE /admin/api/groups/:id/webhook` | Disable the group webhook ingress (owner) |
|
||||
| `GET /admin/api/logs` | Send logs of the accessible groups (filtered in SQL before the limit) |
|
||||
| `GET /admin/api/logs/:id` | Single send-log entry (scoped) |
|
||||
| `GET /admin/api/audit` | Audit log of the accessible groups (filtered in SQL before the limit) |
|
||||
| `GET /admin/api/metrics` | Delivery stats (totals, failure rate, per platform/event/status, recent failures); optional `?groupId=` scope; every aggregate is limited to the accessible groups |
|
||||
| `GET /admin/api/delivery/:deliveryId` | The attempts of one delivery that belong to the accessible groups; optional `?groupId=` (two groups' senders may use the same delivery id) |
|
||||
| `POST /admin/api/test-match` | Stateless filter dry-run — evaluate a filter node against a pasted JSON payload (no event is stored) |
|
||||
|
||||
## Validation
|
||||
|
||||
- `PUT /admin/api/routes` — Body `{ "routes": Route[] }`; validates each route (id pattern, unique id within its group, name, enabled, `groupId`, filters — empty only allowed for `fallback` routes — optional `discordRoleIds` (list of role id strings), and platform-aware targets: `target.channelId` for Discord, `target.chatId` for Telegram) and persists to D1 `d1_routes`. Returns `200 { ok, count }` or `400 { error }` / `401 { error }` / `403 { error }`. Unchanged routes skip the full validation. Route filters support the `field` type (a JSONPath `path` into `payload`, arrays expand so any element matches) and 12 `op` operators (`eq` default / `ne` / `contains` / `startsWith` / `endsWith` / `regex` / `gt` / `gte` / `lt` / `lte` / `in` / `exists`); a nested `ast` (`all` / `any` / `not`) takes precedence over `filters` when present.
|
||||
- `PUT /admin/api/groups` — Validates group ids, member roles (at least one `owner`), `providers` (`github` / `gitea`), and `installationId`.
|
||||
- `PUT /admin/api/routes` — Body `{ "routes": Route[] }`; validates each route (id pattern, unique id within its group, name, enabled, `groupId`, filters — an array, empty only for `fallback` routes or when a valid `ast` is present; patterns the matcher cannot compile — longer than 200 characters, or RE2-unsupported syntax such as backreferences or lookaround — are rejected; flat `filters` hold leaf conditions only (`all`/`any`/`not` belong in `ast`); `keyword` only supports the default `eq`; `exists` may omit `match` — optional `discordRoleIds` (at most 50 numeric Discord role ids), and platform-aware targets: `target.channelId` for Discord, `target.chatId` for Telegram/Feishu, with the id rules and duplicate-destination check in [Routes & Targets](../guide/routes)) and persists to D1 `d1_routes`, rewriting only the groups whose routes changed. A non-super admin pointing a target at a channel another group uses gets `403`. Returns `200 { ok, count }` or `400 { error }` / `401 { error }` / `403 { error }`. Unchanged routes skip the full validation. Route filters support the `field` type (a JSONPath `path` into `payload`, arrays expand so any element matches) and 12 `op` operators (`eq` default / `ne` / `contains` / `startsWith` / `endsWith` / `regex` / `gt` / `gte` / `lt` / `lte` / `in` / `exists`); a nested `ast` (`all` / `any` / `not`) takes precedence over `filters` when present.
|
||||
- `PUT /admin/api/groups` / `POST /admin/api/groups` / `PUT /admin/api/groups/:id` — Validate group ids, `members` (or legacy `adminIds`; a non-empty `members` list needs at least one `owner`), `forgeSources` (at most 20, `name` up to 50 characters, unique type + host), `providers` (`github` / `gitea` / `custom`), and `installationId`; unknown fields are dropped. The source-isolation fields `owners`, `installationId` and `isolated` are super-admin only: an owner's write keeps their stored values. New members' logins are resolved to GitHub user ids with the writer's token; the server-only fields (`instance`, the webhook secret, member user ids) can never be set by the client.
|
||||
- Every write re-checks the writer's role inside its transaction: a request authorized before the role was revoked is refused (`409` for route/fragment writes, `403` for group writes).
|
||||
- Optimistic concurrency — every list or group the API returns carries a `revision`. Send it back with the write (`group.revision`, or `revision` next to `routes` / `fragments` / `newId`, or the list `revision` of the bulk groups write) and the server refuses the write with `409` if the stored data changed since it was loaded, instead of overwriting the newer change. Writes without a `revision` are applied as before. In the bulk groups write, a group echoed back unedited is never written.
|
||||
- `PUT /admin/api/groups/:id/routes` — Optional `discardUnreadable: true` replaces stored routes that cannot be read (otherwise the save is refused while the group has any).
|
||||
- `PUT /admin/api/routes` — Optionally send `revisions` (the per-group map returned by `GET /admin/api/routes`): groups whose list comes back unedited are not written, groups the client never loaded are not touched, and edited groups must still be at their loaded revision (`409` otherwise). Each group is written in its own guarded transaction.
|
||||
- `PUT /admin/api/groups/:id/rename` — Optional `revision`; returns `{ ok, id, group, revision }` (the renamed group and its new revision). Ids starting with `inst-` or `u-` are reserved for super admins.
|
||||
- `DELETE /admin/api/groups/:id` — Requires `revision`, `routesRevision` and `version` as seen at confirmation (`400` when missing, `409` when the group, its routes or fragments changed, or when it has routes that cannot be read). Also revokes the group's invites and webhook secret, detaches its send logs and audit entries (they stay visible to super admins only), and retires the id for a few days so queued deliveries cannot reach a new group that reuses it.
|
||||
- `POST /admin/api/groups/:id/webhook/regenerate` — Returns `{ ok, url, secret, hasSecret }`; the secret is shown only in this response.
|
||||
- `POST /admin/api/test-match` — Body `{ "node": FilterNode | "filters": Filter[], "event"?: string, "payload": object }`; evaluates in memory and returns `{ matched, explanation }`. Nothing is persisted.
|
||||
- `GET/PUT /admin/api/groups/:id/fragments` — Named filter fragments (`{ id, groupId, name, node }`) stored in D1 `d1_fragments`; the editor inlines a fragment's `node` into a route's `ast` on insert (the matcher never resolves fragment references). `PUT` replaces the group's fragments and returns `200 { ok, count }`.
|
||||
- Limits: at most 200 routes and 100 groups per instance.
|
||||
- `GET/PUT /admin/api/groups/:id/fragments` — Named filter fragments (`{ id, groupId, name, node }`) stored in D1 `d1_fragments`; the editor inlines a fragment's `node` into a route's `ast` on insert (the matcher never resolves fragment references). `PUT` replaces the group's fragments (at most 200) and returns `200 { ok, count }`.
|
||||
- Limits: one save accepts at most 200 routes, 200 fragments per group, and 100 groups in the bulk groups write.
|
||||
|
||||
Schemas: [Routes & Targets](../guide/routes), [Groups & Access Control](../guide/groups).
|
||||
Reference in new issue
Block a user