Repository navigation
Commit 30e0bd1
docs(external-datasources): a borrowed-credential connect failure recovers without a restart (#31331)
<!-- claude-projects-attribution: {"github_login":"marchtian"} -->
_Requested by **田騏** · [project
thread](https://claude.ai/code/project/chan_01VmuUhXU9SSUzqJYyXSmYSi?thread=cmsg_01VmuUhXU9SSUzqJYyXSmYSiPizEZatw36sCQ3zgD5Ehd8)_
Fixes #31325
Clause-②: no
Metadata-protocol: none
## 维护者速读
- 改了什么:只改文档。`external-datasources.mdx` §4「借用连接器凭据」在 "Fail-closed at
connect" 下面加一条 "Recovery without a
restart":插件驱动的数据源开机借不到连接器实例的凭据会记为失败,实例修好后,下一个请求借用成功就自动撤销失败,不用重启。§3 的
`OS_ALLOW_DRIVER_CONNECT_FAILURE`
提示里补一句「这是唯一的例外」;`odata-datasources.mdx` 原有的指向 §4
的链接说明里加上「也讲了怎么恢复」,不重复规则。
- 为什么改:这是 #27990
合入的行为(`DatasourceConnectionService.retractOnLend`),指南只写了连接失败,没写会自动恢复。
- 风险与回滚:纯文档,不发布任何包,无 changeset。回滚即还原这两个文件。
- 先看:`content/docs/data-modeling/external-datasources.mdx` 新加的 "Recovery
without a restart" 一条。
- 需要你做的:无,席位落地。
## What changes
- **external-datasources §4, "Borrowing a connector instance's
credential"**: a new rule, "Recovery without a restart", right after
"Fail-closed at connect". Each sentence and the code it holds against,
in
`packages/services/service-datasource/src/datasource-connection-service.ts`
at origin/main 604a2b3:
- The connect judges the instance once; the plugin driver stays
registered and borrows again on each request: the already-registered
guard in `attemptConnect` records `failed-credentials` without evicting
the driver, and driver-odata drops a refused borrow and borrows again on
the next request (`packages/drivers/driver-odata/src/plugin.ts`).
- It applies when the failure did not stop the boot (no gate refuses it,
or `OS_ALLOW_DRIVER_CONNECT_FAILURE` is set): `handleFailure` throws in
the other cases, so there is no process to recover.
- `error` in Setup and `503` until the repair: `failed-credentials` maps
to availability `failed`; a refused borrow on a read is answered `503`
(the odata guide's fail-closed rule).
- The first borrow granted for that instance clears it and the
datasource reads `ok`: `retractOnLend` re-records `already-registered`
(availability `available`), which clears the engine's unavailable mark
through `recordState`.
- A grant for a different instance leaves it standing: `retractOnLend`
skips entries whose `connector` differs.
- A reconnect or edit in between records its own result:
`attemptConnect` and `disconnect` drop the `awaitingLend` entry, and
`retractOnLend` also checks the retained state is still the recorded
verdict and the driver is still registered.
- It needs a lender that reports grants (`onLent`), which
`@objectstack/service-automation`'s source does (`announceLent` in
`borrow`); otherwise `subscribeToLends` answers false and the verdict
stands until a restart.
- The `DEGRADED BOOT` banner says which: the `recovery` sentence names
the instance when retractable, else the default "until it is reachable
AND the server is restarted".
- **external-datasources §3, the `OS_ALLOW_DRIVER_CONNECT_FAILURE`
callout**: its "nothing re-runs the connect ... until the server is
restarted" now names this case as the one exception and links to §4.
- **odata-datasources §3**: the fail-closed bullet already pointed at §4
for the rules; the pointer now says §4 also covers the recovery. The
rule is not restated there.
## Why
#27990 made the retraction, and the guide still described a
borrowed-credential connect failure as lasting for the process. A reader
who repairs the connector instance had no way to know a restart is not
needed, or when it still is.
## Verification
- `node scripts/check-doc-authoring.mjs`: exit 0.
- `node scripts/check-doc-anchors.mjs`: exit 0, 945 internal fragment
links resolve (the two new links included).
- Every sentence read against the code named above at 604a2b3, and
against `datasource-connector-credential.test.ts` (the retraction and
banner cases).
## Acceptance notes
- The claim names §4 only; the diff also adds one sentence to the §3
callout, because it said a failed datasource stays failed until a
restart with no exception. #31327 and #31328 add driver sections
elsewhere in this file, so the two edits do not overlap.
- Edited on the card thread's own checkout of
`claude/project-thread-9xq009`, not a separate `objectstack-issue-31325`
worktree: no other agent shares this container.
## Human Minimum
- [x] 1. Schemas start as Zod; `packages/spec` holds no runtime logic.
(not touched)
- [x] 2. Every name I added uses the casing for its kind. (no names)
- [x] 3. No formatter ran; `pnpm lint` passes. (docs only)
- [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. (publishes
nothing)
- [x] 6. `packages/spec` touched: its generated artifacts are
regenerated and committed. (not touched)
- [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.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
https://claude.ai/code/session_017ihL2fHTwitn43z5tu7gTt
Co-authored-by: Claude <noreply@anthropic.com>1 parent a2826a1 commit 30e0bd1
2 files changed
Lines changed: 19 additions & 2 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
189 | 189 | | |
190 | 190 | | |
191 | 191 | | |
192 | | - | |
| 192 | + | |
| 193 | + | |
| 194 | + | |
| 195 | + | |
193 | 196 | | |
194 | 197 | | |
195 | 198 | | |
| |||
418 | 421 | | |
419 | 422 | | |
420 | 423 | | |
| 424 | + | |
| 425 | + | |
| 426 | + | |
| 427 | + | |
| 428 | + | |
| 429 | + | |
| 430 | + | |
| 431 | + | |
| 432 | + | |
| 433 | + | |
| 434 | + | |
| 435 | + | |
| 436 | + | |
421 | 437 | | |
422 | 438 | | |
423 | 439 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
263 | 263 | | |
264 | 264 | | |
265 | 265 | | |
266 | | - | |
| 266 | + | |
| 267 | + | |
267 | 268 | | |
268 | 269 | | |
269 | 270 | | |
| |||
0 commit comments