Skip to content

Commit 30e0bd1

Browse files
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

File tree

‎content/docs/data-modeling/external-datasources.mdx‎

Lines changed: 17 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -189,7 +189,10 @@ one failed start reports *all* the misconfigured ones.
189189
in an explicitly degraded state announced by a `DEGRADED BOOT` banner. The
190190
datasource stays unconnected for the process lifetime: nothing re-runs the
191191
connect, so queries against its objects keep failing until the server is
192-
restarted. Do not set it in production.
192+
restarted. The one exception is a plugin-driver datasource whose connector
193+
instance could not lend, which recovers on its own once the instance does
194+
([Borrowing a connector instance's credential](#borrowing-a-connector-instances-credential)).
195+
Do not set it in production.
193196
</Callout>
194197

195198
<Callout type="info">
@@ -418,6 +421,19 @@ its header or query parameter. The rules:
418421
automation service (`@objectstack/service-automation` is what lends the credential),
419422
leaves the datasource unconnected with the reason, the same connect failure as an
420423
unresolvable `credentialsRef`.
424+
- **Recovery without a restart.** The connect judges the instance once, but the plugin
425+
driver stays registered and borrows again on each request. So when that failure did not
426+
stop the boot (no gate in [When auto-connect fails](#when-auto-connect-fails) refuses it,
427+
or `OS_ALLOW_DRIVER_CONNECT_FAILURE` is set), the datasource shows `error` in
428+
Setup → Datasources and its requests answer `503` only until the instance is repaired.
429+
The first borrow the lender grants for **that** instance after the repair, which the next
430+
request makes, clears the failure, and the datasource reads `ok` again with no restart.
431+
A grant for a different instance leaves it standing. A datasource reconnected or edited
432+
in between records a result of its own instead. This needs a lender that reports its
433+
grants, as `@objectstack/service-automation` does; with a lender that does not, or none,
434+
the failure stands until a restart. The `DEGRADED BOOT` banner says which applies: it
435+
names the instance whose next granted borrow clears the failure, or says the server has
436+
to be restarted.
421437
- **A credential not set yet does not fail the connect.** Each request is answered
422438
`503 ERR_DATASOURCE_UNAVAILABLE`, with the reference named in the server log, until
423439
an administrator sets it; the next request after that reads with it, with no restart.

‎content/docs/data-modeling/odata-datasources.mdx‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -263,7 +263,8 @@ plugins: [
263263
credential. An instance that cannot lend also fails the datasource's connect, so
264264
Setup → Integrations → Datasources shows why
265265
([Borrowing a connector instance's credential](/docs/data-modeling/external-datasources#borrowing-a-connector-instances-credential)
266-
has the rules the stack is validated against).
266+
has the rules the stack is validated against, and how the datasource recovers without a
267+
restart once the instance can lend).
267268

268269
## 4. What the service is asked
269270

0 commit comments

Comments
 (0)