Skip to content

Commit 199e362

Browse files
feat(service-automation): the connector connection store, the connect door and the OAuth callback read and write one instance by its package and name (#33218)
<!-- claude-projects-attribution: {"github_login":"os-tesla"} --> _Requested by **Tesla** · [project thread](https://claude.ai/code/project/chan_01AXsQkLFKRdQCqQ3RTr6Jao?thread=cmsg_01AXsQkLFKRdQCqQ3RTr6Jao3aDjoEUznHeGMZJaoMEKa5)_ Part of #31699 Clause-②: yes (widening) Metadata-protocol: none ## 维护者速读 - 改了什么:连接存储、连接门(读 / 开始 / 回调 / 撤销)、OAuth 回调和派发都按「包 + 名字」读写连接。开始连接时把实例的包记进待完成授权,回调只完成那个包的实例,不再按名字重新解析。没有包的旧连接行,只在名字的持久解析指向该包时才算它的,该包重新连接时就地认领。 - 为什么改:ADR-0150 D4,#31699 PR 3a 的第二半(第一半 #33199 加宽了键)。 - 不变:每个名字只有一个持有者、每个组织一条连接的库上,所有答复照旧;一持有者兜底仍在。 - 新的拒绝(逐条列在 changeset 的 "What answers differently"):名字有两个持有者时连接门 409;同一组织有两条行回答同一实例时门 409、派发 503(不再挑一条);回调记录的包不再声明该实例时 404。 - 声明的偏离:M5(本 PR 不加 `?package=`,地址化的门随收窄兜底的 PR 一起落,不晚于它)、M6(无持有者时用条目自己的包)、S3(两个持有者时包自己的行优先)。三条都经红线审读接受。 - 先看:`packages/services/service-automation/src/connector-connections.ts`(`answering`)、`src/plugin.ts`(`connectorInstancePackage`、`connectionDoorInstance`)、`src/oauth2-grant/grant-handle.ts`。 ## What changes - **Store** (`ConnectorConnectionStore`): `connect`, `read`, `readOrRefuse`, `revoke`, `listFor` take the instance's package. One rule (`answering`) decides which rows answer: the package's own rows, plus a package-less row only where the name's durable resolution (the boot backfill's question) binds it to that package or no registry can judge; a connect adopts that row in place (M2). Two answering rows are refused, never picked. A package-less row of a name two packages hold is no package's: the read and the revoke are refused 409 naming `os migrate stored-references bind`. `listFor` still counts a conflicted organization, carrying the refusal. The post-insert take-back from #33199 now counts by package. - **Instance package** (`connectorInstancePackage`): a real stamp; none for the environment's stored entry; for an unstamped or compatibility-default entry, the durable holder's package. Door, dispatch handle, materializer and reconnect mark all use it. - **Door** (`connectionDoorInstance`): resolves the name; two holders 409; no registry or no holder serves the one declared entry (two declared entries 409). - **Pending authorization**: carries `packageId` (explicit `null` for no package). The callback completes exactly that package's entry; a record from before this change (no key, TTL ten minutes) resolves the name. - **Dispatch** (`createOAuth2GrantHandle`): reads by package; a conflict is 503 on both the selection and the refresh read; an org-less dispatch never takes a conflicted organization's row. - **Docs**: one sentence in `content/docs/automation/connectors.mdx`. ## Declared deviations from the design review - **M5**: no `?package=` on the HTTP door and no spec change here. The addressed door lands with the PR that narrows the one-holder backstop, and no later. Until then a name with two holders (a package installed after boot) is refused at every leg of the door, revoke included. - **M6**: with no registry answer or no holder, the one declared entry is served with its own package, not `null`. - **S3**: under two holders a package's own row wins over a package-less row of the name; the stray row keeps its token until bound and revoked (remedy in the changeset). ## Verification - `connector-connection-package.test.ts` (new, real ObjectQL over SQLite): 10 pins on the store rule, adoption, two holders, two rows, revoke, `listFor`. - `connector-connection-door.test.ts`: 13 new pins through the booted plugin and a real `SchemaRegistry`: stamping, the 409s, the callback completing the recorded package (including `null`) after the declarations change, refusal before the code is used, M2 adoption, two rows refused with and without the run's organization, a conflicted organization still counted (422), revoke 409 under a disabled second holder, unstamped and `__runtime__` entries keeping their row across the backfill bind. - Ablations (each reds its pins): connect stamps no package; begin records no package; callback re-resolves; refused resolution not refused; two declared entries picked; adoption not stamping; org-less takes a conflicted entry; `listFor` skips a conflicted organization; revoke answers not-connected under conflict; door fallback removed; the resolver arm of the instance package removed. - `@objectstack/service-automation` full suite, rebased on `main` after #33199: 281 files, 3871 tests passed. `tsc --noEmit`, ESLint on touched files, `tenant-audit-census`, `check-engine-double-contract` green. ## Red-line read Run in this thread by a separate review pass (maintainer's instruction: 「你自己有fable,自己审就可以了吧?」). Round 1: PASS-WITH-CHANGES, one must-fix (an org-less dispatch could take the first of two answering rows) and five should-fix (a conflicted organization skipped turning a 422 into a dispatch; the door's holder-to-entry match; revoke 404 vs read 409; revoke under two holders; the changeset's "as before"), all taken; M5, M6 and S3 accepted. Round 2: PASS-WITH-CHANGES, one should-fix (an unstamped entry must be its durable holder's instance, or the backfill bind loses its row), taken. Round 3: PASS. Carried to 3b: re-key the grant handles by `(package, name)` and evaluate the handle's package per read, before any PR lets two instances of one name live. These red-line reads ran before the 2026-11-14 04:37Z pause of seat-run contract reviews. This PR is opened as a draft and owes a contract review at **TIER_DEFAULT (widening)** from the new review agent before it is marked ready. ## Human Minimum - [x] 1. Schemas start as Zod; `packages/spec` holds no runtime logic. - [x] 2. Every name I added uses the casing for its kind. - [x] 3. No formatter ran; `pnpm lint` passes. - [x] 4. One issue, one branch off an up-to-date `main`, one pull request. - [x] 5. A change that publishes carries a changeset, and both declaration lines are filled in here and in the changeset. - [x] 6. `packages/spec` touched: its generated artifacts are regenerated and committed. - [x] 7. No hand edits to `content/docs/references/`, `packages/*/CHANGELOG.md` or `content/docs/releases/`. - [x] 8. Title, body and comments are in English. - [x] The *Before Submitting* list in CONTRIBUTING.md is done. 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_01L9qibzKCovWpJoMZD6U3NT --------- Co-authored-by: Claude <noreply@anthropic.com>
1 parent d4fbb4d commit 199e362

11 files changed

Lines changed: 947 additions & 72 deletions
Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
---
2+
'@objectstack/service-automation': patch
3+
---
4+
5+
feat(service-automation): the connector connection store, the connect door and the OAuth callback read and write one instance by its package and name (ADR-0150 D4, #31699)
6+
7+
Clause-②: yes (widening) — the connect door (`getConnectorConnection`, `beginConnectorConnection`, `completeConnectorConnection`, `revokeConnectorConnection`) and a dispatch answer new refusals, each listed under "What answers differently"; a connection row now carries its instance's package. The one-holder backstop still keeps every connector name to one package at boot, and while a name has one holder every row of the name answers its one instance, as the read by name did, so on a database where each organization keeps one connection of an instance and the name has one holder, every answer is as before, a declaration that moved to another package or to the environment included.
8+
Metadata-protocol: none
9+
Skills-docs: `content/docs/automation/connectors.mdx` says a callback completes the instance its connect was begun for and the door refuses a name two packages hold. `skills/**` teaches "connect once per organization", which still holds per instance.
10+
11+
<!-- adr-0087: not-required (no-migration-prescription) No key of any authorable schema is added, removed, renamed or re-shaped: the store, the door and the pending authorization are runtime, and `connector_package` is the column PR 3a added. -->
12+
13+
Part of #31699 (ADR-0150 child B, PR 3a-ii). PR 3a widened `sys_connector_connection`'s key to `(organization_id, connector_package, connector_name)`; this PR makes the store and its callers use it.
14+
15+
**The store: `ConnectorConnectionStore`.**
16+
17+
- `connect`, `read`, `readOrRefuse`, `revoke` and `listFor` take the instance's package (`string`: a package's instance; `null`: no package's). `revoke` and `listFor` require it; on `connect`, `read` and `readOrRefuse` an absent package still reads the bare name, for the callers that know no package. A connect writes `connector_package` on the row it inserts.
18+
- While the name has one holder (its durable resolution, the question the boot backfill asks, disabled packages included, answers one), or no registry can judge it, every row of the name answers its instance, whatever package the row names: a row naming no package, and a row a moved declaration left under its old package, are the instance's connection, as the read by name answered. A connect adopts the row and stamps it with the instance's package in place (design M2; `null` for the environment's or the platform's instance): one row, never two. A revoke removes it. While two packages hold the name, each package reads its own row; a row naming no package, or naming a package that is not one of the holders, is no package's, and with no row of its own the package's read is refused `409` naming `os migrate stored-references bind --table sys_connector_connection`.
19+
- Two rows answering one instance (a package's own row and another row of the name under one holder, or two rows a guard-less database admitted) are refused `409` by the door and `503` by a dispatch, with or without the run's organization, never one of them used; a revoke removes every row that answers. The connection list (`listFor`) still counts such an organization, carrying the refusal: a dispatch with no organization is refused `422` where another organization is connected too, as before, and the materializer does not count it as connected.
20+
- The post-insert take-back that PR 3a added now counts by `(organization, package, name)`.
21+
22+
**The door and the callback.**
23+
24+
- The connect door resolves the name to one declared instance and its package: the resolved package's entry; with no registry to ask (a code-registered instance, a composition with no ObjectQL) or no holder, the one declared entry with the package it carries; two holders, or two declared entries with no registry, `409`.
25+
- The begin records the package in the pending authorization (`packageId`, `null` for the environment's or the platform's instance). The callback completes exactly that package's entry, never the name resolved again; when that package no longer declares the instance, the callback is refused `404` before its code is exchanged. A pending record written before this change (no key, at most ten minutes old) resolves the name, as the begin did.
26+
- An instance's package is its entry's stamp when that is a real package, none for the environment's stored entry, and, for an entry with no stamp or the compatibility API's default, the package the name's durable resolution holds it under (the package the boot backfill binds a package-less row of the name to, so a row the instance connected stays its own once bound), else none. The door, the dispatch handle, the materializer and the reconnect-required mark all read by that one rule. When the name resolves to a package no declared entry is the instance of, the door serves the one declared entry with its own package, as with no registry.
27+
28+
**What answers differently.**
29+
30+
- `409` at the door where a name has two holders, and where two declared entries share a name with no registry to resolve it; before, the first declared entry was served.
31+
- `409` at the door, and `503` at a dispatch, where two rows answer one instance in one organization (above). Before, the old key kept one row per organization and name, so this needs a database where the guard was refused or a package's row beside an adopted package-less one; when the two rows are met only at the callback, the code has already been exchanged and the connect is refused after it.
32+
- `409` on the read and the revoke of a row of a name two packages hold that names no package, or a package that is not one of the holders (a disabled holder counts: the question is the boot backfill's), where the read answered the row before. Bind it with `os migrate stored-references bind --table sys_connector_connection` and revoke it as its package's, or uninstall one of the holders, after which a revoke of the one remaining instance removes it.
33+
- `404` at the callback when the package its connect recorded no longer declares the instance; before, any entry of the name completed it.
34+
35+
**Declared deviations from the design review.**
36+
37+
- M5: no `?package=` on the HTTP door and no spec change. The door addresses one instance by resolving its name; addressing a second holder's instance explicitly comes with the PR that narrows the one-holder backstop, which is the first PR under which two holders can boot, and no later. Until then a name with two holders (a package installed after boot) is refused at every leg of the door, revoke included: its connections stay stored and keep no dispatch, and the remedy is to uninstall one holder or bind the row.
38+
- M6: where the name has no holder or no registry answers, the door serves the one declared entry with the package that entry carries, not `null`: the row a code-registered package instance connects is that package's, as the backfill would bind it. That stamp is durable while the judgment is not (a later registry may resolve the name elsewhere); it never loosens: while two packages hold the name, the stamped row answers only its own package.
39+
- S3: under two holders a package's own row wins over a package-less row of the name, and the package-less row answers neither (ADR-0150 R9 refuses such a row; the store reads around it rather than refusing the package's own connection). The stray row keeps its encrypted refresh token until it is removed: the door is refused `409` at every leg while two packages hold the name (M5), so it is removed by uninstalling one of the holders, after which the name has one holder, every row of it answers that instance, and a revoke removes them all.
40+
41+
**In-process APIs.** None public: the store, the pending authorization and the grant handle are internal modules of `@objectstack/service-automation`, none exported from its entry point.

‎content/docs/automation/connectors.mdx‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -757,7 +757,10 @@ a rotating refresh token is never spent twice.
757757
encrypted in `sys_connector_connection`, one row per organization and
758758
instance, an instance being its package and name (one per organization for
759759
an instance the environment authored or a plugin registers); it is
760-
not a sign-in account, and signing in never touches it. A run dispatches
760+
not a sign-in account, and signing in never touches it. A callback
761+
completes the instance its connect was begun for, never the name read
762+
again, and the connect door refuses with `409` a name two packages hold
763+
rather than pick one. A run dispatches
761764
with its own organization's connection; a run with no organization uses the
762765
instance's only connection, and is refused when there are several. When the
763766
grant stops working, the connection is marked **reconnect required** and the

0 commit comments

Comments
 (0)