feat(connector-openapi): degrade + retry on an unreachable remote spec URL (#3049 follow-up)#3179
Merged
Merged
Conversation
…c URL (#3049 follow-up) The openapi provider fetches providerConfig.spec when it is an http(s) URL. That fetch threw plain on any failure, so a momentarily-unreachable spec endpoint aborted the whole app boot — the exact fail-loud-on-operational-fault problem #3049 fixed for connector-mcp. Apply the same classification here: - fetch rejection (DNS / connection refused / timeout / network error) or a transient HTTP status (408/429/5xx, mirroring the retryableStatusCodes convention) throws ConnectorUpstreamUnavailableError, so the materializer degrades the instance (state:'degraded' on GET /connectors) and retries with backoff plus on every metadata:reloaded — symmetric with mcp's connect path; - a wrong URL (non-retryable 4xx) or an unparseable/non-object body stays a plain, fatal configuration fault; - inline and file-path (#3016) specs do no boot I/O and are unaffected. No service-automation change: the reconcile already routes any CONNECTOR_UPSTREAM_UNAVAILABLE throw to the degrade path (provider-agnostic, proven generically in #3049). Classification is tested at the provider layer (matching mcp): +14 cases — network reject keeps cause, each of 408/429/5xx degrades, each of 400/401/403/404/410 stays fatal, unparseable + array bodies stay fatal. ADR-0097 scope-boundary list updated: the openapi-fetch caveat is resolved, and the stale 'live mcp demo deferred' bullet is trued up to as-built (#3062). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Pbmw3pMqNJfPbkvwh9Fkjs
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
github-actions
Bot
added
documentation
Contributor
📓 Docs Drift CheckNo hand-written docs reference the 1 changed package(s). ✅ |
os-zhuang
marked this pull request as ready for review
July 18, 2026 06:42
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
把 #3049 为
connector-mcp建立的「操作性故障 → 降级+重试」机制,对称地应用到openapiprovider 的远程 URL spec 拉取,补齐 ADR-0097 里记为延后的一条(现已删掉那句 caveat)。问题
openapiprovider 在providerConfig.spec为 http(s) URL 时于启动拉取文档。此前任何失败都普通抛出,于是 spec 端点一次瞬时不可达就拖垮整个应用启动——正是 #3049 为 mcp 修掉的「把操作性故障当致命」的形态,只是换了个 provider。方案:同一套分类,provider 无关
loadOpenApiDocument的远程分支现在区分:fetch拒绝(DNS/连接拒绝/超时/网络错误)ConnectorUpstreamUnavailableError→ 降级+退避重试408/429/5xx(对齐retryableStatusCodes约定)4xx:400/401/403/404/410…)内联文档与 file-path spec(#3016)启动时无 I/O,不受影响。
无需改 service-automation:#3049 的 reconcile 已经对任何带
CONNECTOR_UPSTREAM_UNAVAILABLE标记的抛出走降级路径(provider 无关,已用 fake provider 通用证明)。因此降级态、GET /connectors的state: 'degraded'、退避重试、metadata:reloaded立即重试、恢复时原子替换——全部自动适用,与 mcp 同一条路径。测试(provider 层,与 mcp 分类测试同一层次;+14 例,套件 32/32 绿)
cause;408/429/500/502/503/504各自 → 降级(参数化);400/401/403/404/410各自 → 保持致命(参数化);res.json()抛错 / 返回数组 → 保持致命(内容错误)。文档
本地:connector-openapi 构建绿、
vitest32/32、eslint 干净。Refs #3049(降级+重试机制)、#3017、ADR-0097 §Upstream availability、ADR-0023。
🤖 Generated with Claude Code
https://claude.ai/code/session_01Pbmw3pMqNJfPbkvwh9Fkjs
Generated by Claude Code