Repository navigation
Commit 4fae0be
feat(service-messaging): serve the notification topics and channels a preference or template can name (#31004)
<!-- claude-projects-attribution: {"github_login":"os-tesla"} -->
_Requested by **Tesla** · [project
thread](https://claude.ai/code/project/chan_01AXsQkLFKRdQCqQ3RTr6Jao?thread=cmsg_01AXsQkLFKRdQCqQ3RTr6Jao43VDBgUgyKRgCUkw33nkQN)_
Clause-②: yes (widening)
Metadata-protocol: none
Refs #30208 (row 6, server half). Ruling E on #30527 (record
6670386759), execution step 1 of comment 6670396132. The card stays
open: the ui dropdowns (step 2) follow after this merges, quiet hours
(step 3) is its own ui card, and row 5 is not in this PR.
## 维护者速读
- 改了什么:新增只读接口 `GET
/api/v1/messaging/preference-options`,返回通知偏好与通知模板可选的「主题」和「渠道」清单(`*`
排第一;主题来自平台固定主题、本环境流程通知步骤里写明的主题、本组织已发过的通知主题;渠道列出所有已知渠道,未配置服务的标「未配置」);三个字段声明下拉控件提示;渠道帮助文字补上
push(十一种语言)。
- 为什么改:管理员在 通知偏好 里只能凭记忆手打主题和渠道的机器名,打错一个字母就静默失效;按 #30527 裁决
E,服务端先给出清单,控制台下一张卡据此画「可选可填」的下拉。
- 风险与回滚:字段仍是文本、`*`
照存、不新增任何拒绝,已存数据不动;新接口只读、仅限已登录成员,且每个组织只看得到自己组织的已存主题。回滚即撤销本
PR,控件提示在控制台注册前本来就退化为文本框。
-
先看:`packages/services/service-messaging/src/preference-options.ts`(三个主题来源与组织边界的
`organization_id`
条件)、`src/preference-options-routes.ts`(拒绝顺序:身份→受限登录→匿名→查询参数)、`src/messaging-service-plugin.ts`
的挂载段。
- 两分钟验证:`pnpm --filter @objectstack/service-messaging exec vitest run
src/preference-options-routes.integration.test.ts`,预期 8 个用例全过(含「B
组织的主题不会出现在 A 组织」)。
- 需要你做的:无,席位落地。
## What changes
- **A read-only list route, mounted by service-messaging itself** (route
B in the seat's claim 6688765720): `registerPreferenceOptionsRoutes`
(`src/preference-options-routes.ts`) mounts `GET
/api/v1/messaging/preference-options` on `http-server` at
`kernel:ready`, as service-settings / service-print / service-storage
mount theirs. The sibling `/api/v1/notifications` routes live in
`packages/runtime` behind `INotificationService` (a spec contract), so a
runtime face would have needed a spec card; this PR touches neither
`packages/runtime` nor `packages/spec`. A kernel with no HTTP server
logs one `warn` naming what is not mounted.
- **Who may ask** (the posture of `/api/v1/notifications`): any
signed-in member. The caller is resolved by the one composition
(`resolveRequestExecutionContext`, session or API key); an
authorization-store outage and an API key lifecycle refusal are relayed
as declared; a held sign-in is `403` with the policy's code; anonymous
is `401 UNAUTHENTICATED`; the closed query set is empty, so any query
parameter is `400 VALIDATION_ERROR` naming it. All of these answer
before any source is read.
- **What it serves** (`src/preference-options.ts`), response `{ success:
true, data: { topics, channels } }`:
- `topics: Array<{ value: string; wildcard: boolean; sources:
Array<'platform' | 'flow' | 'stored'> }>`: `{ value: '*', wildcard:
true, sources: [] }` first, then sorted and de-duplicated, each with
every source naming it: `PLATFORM_NOTIFICATION_TOPICS` (15 fixed topics
measured from their send/template sites in plugin-approvals,
plugin-audit, plugin-security, plugin-auth); every `notify` step's own
string `topic` in this environment's flows (`protocol.getMetaItems({
type: 'flow' })`), and `notify` for a step that names none (the node's
own default); the distinct `sys_notification.topic` values of the
caller's organization (one `aggregate` grouped by `topic`, `where: {
organization_id }`, under a named system context
`PREFERENCE_OPTIONS_SYSTEM_CONTEXT`; a caller with no organization gets
no stored topic).
- `channels: Array<{ value: string; wildcard: boolean; configured:
boolean }>`: `*` first, then `MessagingService.getKnownChannels()`
(new): directly registered channels, then each lazy provider,
`configured: false` when its transport is absent ("not configured").
- A source that cannot be read answers `500 INTERNAL_ERROR` with the
door's sentence and the error in the fault log, never a partial list.
- **The fields**: `sys_notification_preference.topic` declares `widget:
'notification-topic'`, `.channel` declares `widget:
'notification-channel'`, `sys_notification_template.topic` declares
`widget: 'notification-topic'`. `FieldSchema.widget` is an existing free
`z.string()`, so no spec value is added; an unregistered widget degrades
to the text box. The template's `channel` keeps
`channel_renders_template` and declares nothing.
- **The help**: the preference channel help names `push` (registered as
a lazy provider since #29041), in the English source and all ten
translated bundles; `en` regenerated by `check-i18n-bundles --write`.
- **Ledger**: `src/messaging-route-ledger.ts` (one `server-only` row)
with its package-local conformance test, and the three wiring lines the
claim names: the live-mount parity dogfood test imports the ledger, and
`scripts/cross-package-test-inputs.mjs` / `turbo.json` declare it as
that test's input.
- **Envelope guard**: `scripts/check-route-envelope.mjs` declares the
new door in `MODULES` at `{ responses: 0, ok: 0, err: 0 }` beside the
print door (every body goes through the shared `sendOk` / `sendError` /
`sendServerFault`). The claim was widened to this path for it.
## Tests
- `src/preference-options-routes.integration.test.ts` (new, 8 cases),
real resolver over a fake auth service, real `ObjectQL` over `SqlDriver`
(better-sqlite3) holding `org_a` and `org_b` on the `isolated` posture:
the full list and its sources; cross-organization isolation (a topic
stored in `org_b` never listed for `org_a`, and the reverse); no
protocol means no flow topic; anonymous `401`, held sign-in `403
PASSWORD_EXPIRED`, query parameter `400` naming it, each asserting by
envelope (ApiError parse + code + status) and that no source was read; a
failing source `500`, no data.
- `src/messaging-route-ledger.conformance.test.ts` (new): registrar
enumeration against the ledger, both directions.
- `src/objects/notification-preference-topic-channel-help.test.ts`
re-pinned: the built channel ids are `['inbox', 'email', 'sms', 'push']`
(push factory added to the enumeration) and the help names exactly
those; `push` left the "named but not implemented" list; a new case pins
the three widget hints, the template topic's `text` type, and no widget
on the template channel.
## Acceptance notes
- **Flows are the environment's, not an organization's** (ADR-0131 D6:
the list serves the environment's rows and no organization's), so every
organization of one environment is offered the same flow topics; the
organization boundary applies to the stored topics, which is what the
isolation pin holds.
- **`PLATFORM_NOTIFICATION_TOPICS` is a measured constant**, since
nothing registers topics (ADR-0030's `defineTopic()` was never built). A
feature that starts sending a new fixed topic must add it there; no gate
catches a miss. `auth.phone_otp` / `auth.phone_invite` are template
topics (the SMS goes out without `emit()`), listed because the template
form reads the same list; on a preference they match nothing.
- The stored-topic read is unbounded in the number of distinct topics
(one grouped `aggregate`, no limit in `EngineAggregateOptions`); the
event table's 90-day lifecycle window bounds it in practice.
- The anonymous floor test first stayed green under a narrower mutation
(`shouldDenyAnonymous` removed, `!context` kept), because the
fail-closed composition already answers no context for an
unauthenticated request; the second mutation removed the whole branch
and went red (below). Both runs are recorded.
- **A derived-gate blind spot**: `node scripts/pm/dispatch-gates.mjs
--commands` did not derive `pnpm check:route-envelope` for this diff's
paths, so the 86 local gates were green while CI's `Lint · docs & code
guards` went red on `Response-envelope guard` (run 42254020926, `NOT
DECLARED`) at `d4930694`. Fixed in `581fce5c`; a new `*-routes.ts`
module outside the derivation's reach needs that command run by hand.
- No `skills/**`, `content/docs/**` or ADR edit: no published sentence
states these fields have no list. The ui half (registering
`field:notification-topic` / `field:notification-channel`) is the next
card.
## Verification
All readings on head `d4930694` unless a line says otherwise (`d4930694`
= `00bd47c0` + merge of `origin/main`, 8 commits, only `turbo.json`
overlapping; head `581fce5c` adds only the envelope-guard declaration).
<details><summary>Package suite, typecheck, lint (on 00bd47c, before
the main merge)</summary>
- `pnpm --filter @objectstack/service-messaging test && pnpm --filter
@objectstack/service-messaging typecheck` under the verify lock: Test
Files 69 passed (69), Tests 874 passed (874); VERDICT command-exit 0.
- `npx eslint --no-inline-config packages/services/service-messaging/src
packages/qa/dogfood/test/route-ledger-live-mount-parity.dogfood.test.ts
scripts/cross-package-test-inputs.mjs`: exit 0.
- `pnpm --filter @objectstack/dogfood exec vitest run
test/route-ledger-live-mount-parity.dogfood.test.ts`: 8/8 passed on the
showcase boot, which logged `[messaging] preference options list mounted
at GET /api/v1/messaging/preference-options`; VERDICT command-exit 0.
</details>
<details><summary>Negative-pin ablations (each through
scripts/ablation-replace.mjs, restored blob == HEAD, git diff HEAD
empty)</summary>
- Organization term deleted (`where: { organization_id: organizationId
},`, anchor 1 -> 0): `a topic stored in one organization never appears
for another` failed, `AssertionError: expected [ '*',
'approval.comment', …(18) ] to not include 'org_b.secret_topic'`.
- Anonymous branch replaced by `if (false as boolean) {`: `refuses an
anonymous caller 401 UNAUTHENTICATED` failed, `expected [
'INTERNAL_ERROR', 500 ] to deeply equal [ 'UNAUTHENTICATED', 401 ]`.
(First mutation, `if (!context) {`, stayed green: see Acceptance notes.)
- Held sign-in gate disabled: `refuses a held sign-in 403 ...` failed.
- Query refusal disabled: `refuses a query parameter 400
VALIDATION_ERROR naming it, never ignoring it` failed.
- Notify-type filter disabled (every node read as a notify step): the
list case failed on `not.a.notify.topic`.
</details>
<details><summary>Derived gates</summary>
- `node scripts/pm/dispatch-gates.mjs --commands --repo
objectstack-ai/objectstack` on `00bd47c0` (25 paths): 86 commands, every
one run with stdin from /dev/null, all `:: exit 0`.
- `--ran`: `86 derived, 86 run, 0 NOT-MEASURED, 0 UNRUN`.
- After the main merge, on `d4930694`: `pnpm check:turbo-task-graph`,
`pnpm check:cross-package-test-inputs`, `pnpm check:ci-filter-parity`,
`pnpm check:i18n`: exit 0 each.
- On `581fce5c`: `pnpm check:route-envelope` exit 0 (`--self-test` then
the audit; was `NOT DECLARED` for `preference-options-routes.ts`
before), `npx eslint --no-inline-config
scripts/check-route-envelope.mjs` exit 0.
- Changeset: `.changeset/30208-messaging-preference-options.md`,
`@objectstack/service-messaging: patch`, carrying both declaration lines
at line start.
- Dogfood battery: n/a (no `!` in the title, no `(narrowing)` arm).
</details>
🤖 Generated with [Claude Code](https://claude.com/claude-code)
https://claude.ai/code/session_01L9qibwBQRERS1JhPWT48RW
---
_Generated by [Claude
Code](https://claude.ai/code/session_01L9qibwBQRERS1JhPWT48RW)_
<!-- signed: domain:server#2 · os-tesla ·
session_01L9qibwBQRERS1JhPWT48RW -->
---------
Co-authored-by: Claude <noreply@anthropic.com>1 parent adab62a commit 4fae0be
26 files changed
Lines changed: 927 additions & 35 deletions
File tree
- .changeset
- packages
- qa/dogfood/test
- services/service-messaging/src
- objects
- translations
- scripts
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
72 | 72 | | |
73 | 73 | | |
74 | 74 | | |
| 75 | + | |
75 | 76 | | |
76 | 77 | | |
77 | 78 | | |
| |||
109 | 110 | | |
110 | 111 | | |
111 | 112 | | |
| 113 | + | |
112 | 114 | | |
113 | 115 | | |
114 | 116 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| 15 | + | |
| 16 | + | |
| 17 | + | |
| 18 | + | |
| 19 | + | |
| 20 | + | |
| 21 | + | |
| 22 | + | |
| 23 | + | |
| 24 | + | |
| 25 | + | |
| 26 | + | |
| 27 | + | |
| 28 | + | |
| 29 | + | |
| 30 | + | |
| 31 | + | |
| 32 | + | |
| 33 | + | |
| 34 | + | |
| 35 | + | |
| 36 | + | |
| 37 | + | |
| 38 | + | |
| 39 | + | |
| 40 | + | |
| 41 | + | |
| 42 | + | |
| 43 | + | |
| 44 | + | |
| 45 | + | |
| 46 | + | |
| 47 | + | |
| 48 | + | |
| 49 | + | |
| 50 | + | |
| 51 | + | |
| 52 | + | |
| 53 | + | |
| 54 | + | |
| 55 | + | |
| 56 | + | |
| 57 | + | |
| 58 | + | |
| 59 | + | |
| 60 | + | |
| 61 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| 15 | + | |
| 16 | + | |
| 17 | + | |
| 18 | + | |
| 19 | + | |
| 20 | + | |
| 21 | + | |
| 22 | + | |
| 23 | + | |
| 24 | + | |
| 25 | + | |
| 26 | + | |
| 27 | + | |
| 28 | + | |
| 29 | + | |
| 30 | + | |
| 31 | + | |
| 32 | + | |
| 33 | + | |
| 34 | + | |
| 35 | + | |
| 36 | + | |
| 37 | + | |
| 38 | + | |
| 39 | + | |
| 40 | + | |
| 41 | + | |
| 42 | + | |
| 43 | + | |
| 44 | + | |
| 45 | + | |
| 46 | + | |
| 47 | + | |
| 48 | + | |
| 49 | + | |
| 50 | + | |
| 51 | + | |
| 52 | + | |
| 53 | + | |
| 54 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
1 | 1 | | |
2 | 2 | | |
3 | 3 | | |
4 | | - | |
| 4 | + | |
5 | 5 | | |
6 | | - | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
7 | 9 | | |
8 | 10 | | |
9 | 11 | | |
| |||
548 | 550 | | |
549 | 551 | | |
550 | 552 | | |
| 553 | + | |
| 554 | + | |
| 555 | + | |
| 556 | + | |
| 557 | + | |
| 558 | + | |
| 559 | + | |
| 560 | + | |
| 561 | + | |
551 | 562 | | |
552 | 563 | | |
553 | 564 | | |
| |||
624 | 635 | | |
625 | 636 | | |
626 | 637 | | |
| 638 | + | |
| 639 | + | |
| 640 | + | |
| 641 | + | |
| 642 | + | |
| 643 | + | |
| 644 | + | |
| 645 | + | |
| 646 | + | |
| 647 | + | |
| 648 | + | |
| 649 | + | |
| 650 | + | |
| 651 | + | |
| 652 | + | |
| 653 | + | |
| 654 | + | |
| 655 | + | |
| 656 | + | |
| 657 | + | |
| 658 | + | |
| 659 | + | |
| 660 | + | |
| 661 | + | |
| 662 | + | |
| 663 | + | |
| 664 | + | |
| 665 | + | |
| 666 | + | |
| 667 | + | |
| 668 | + | |
| 669 | + | |
| 670 | + | |
| 671 | + | |
| 672 | + | |
| 673 | + | |
| 674 | + | |
| 675 | + | |
| 676 | + | |
| 677 | + | |
| 678 | + | |
| 679 | + | |
| 680 | + | |
| 681 | + | |
| 682 | + | |
| 683 | + | |
627 | 684 | | |
628 | 685 | | |
629 | 686 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
596 | 596 | | |
597 | 597 | | |
598 | 598 | | |
| 599 | + | |
| 600 | + | |
| 601 | + | |
| 602 | + | |
| 603 | + | |
| 604 | + | |
| 605 | + | |
| 606 | + | |
| 607 | + | |
| 608 | + | |
| 609 | + | |
| 610 | + | |
| 611 | + | |
| 612 | + | |
| 613 | + | |
| 614 | + | |
| 615 | + | |
| 616 | + | |
| 617 | + | |
599 | 618 | | |
600 | 619 | | |
601 | 620 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
2 | 2 | | |
3 | 3 | | |
4 | 4 | | |
5 | | - | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
6 | 8 | | |
7 | 9 | | |
8 | 10 | | |
| |||
15 | 17 | | |
16 | 18 | | |
17 | 19 | | |
18 | | - | |
19 | | - | |
20 | | - | |
| 20 | + | |
| 21 | + | |
| 22 | + | |
| 23 | + | |
| 24 | + | |
| 25 | + | |
21 | 26 | | |
22 | 27 | | |
23 | 28 | | |
24 | 29 | | |
| 30 | + | |
25 | 31 | | |
26 | 32 | | |
27 | 33 | | |
| 34 | + | |
28 | 35 | | |
29 | 36 | | |
30 | | - | |
| 37 | + | |
| 38 | + | |
| 39 | + | |
31 | 40 | | |
32 | 41 | | |
33 | 42 | | |
| |||
37 | 46 | | |
38 | 47 | | |
39 | 48 | | |
| 49 | + | |
40 | 50 | | |
41 | 51 | | |
42 | 52 | | |
| |||
57 | 67 | | |
58 | 68 | | |
59 | 69 | | |
60 | | - | |
| 70 | + | |
61 | 71 | | |
62 | 72 | | |
63 | | - | |
| 73 | + | |
64 | 74 | | |
65 | 75 | | |
66 | 76 | | |
| |||
70 | 80 | | |
71 | 81 | | |
72 | 82 | | |
| 83 | + | |
| 84 | + | |
| 85 | + | |
| 86 | + | |
| 87 | + | |
| 88 | + | |
| 89 | + | |
| 90 | + | |
| 91 | + | |
| 92 | + | |
73 | 93 | | |
0 commit comments