Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure
TypeScript
fix(control-api): map discovery transport failures to 424 instead of 502
Diego Zacarias66da8017d4c4
diff --git a/control-api/package-lock.json b/control-api/package-lock.jsonindex a23a003e7..da592a3cd 100644--- a/control-api/package-lock.json+++ b/control-api/package-lock.json@@ -1,12 +1,12 @@{"name": "clerum-control-api",- "version": "0.1.799",+ "version": "0.1.800","lockfileVersion": 3,"requires": true,"packages": {"": {"name": "clerum-control-api",- "version": "0.1.799",+ "version": "0.1.800","dependencies": {"@clerum/display-field": "file:../packages/display-field","@clerum/grok-provider-attempt-contract": "file:../packages/grok-provider-attempt-contract",diff --git a/control-api/package.json b/control-api/package.jsonindex b5f61f66e..4fba5c351 100644--- a/control-api/package.json+++ b/control-api/package.json@@ -1,6 +1,6 @@{"name": "clerum-control-api",- "version": "0.1.799",+ "version": "0.1.800","description": "Internal Clerum control plane REST API + UI for managing CRDs and secrets","main": "dist/main.js","engines": {diff --git a/control-api/src/oauth/discoveryHttpStatus.ts b/control-api/src/oauth/discoveryHttpStatus.tsindex 4a17a79ab..2a24ed5e0 100644--- a/control-api/src/oauth/discoveryHttpStatus.ts+++ b/control-api/src/oauth/discoveryHttpStatus.ts@@ -3,22 +3,24 @@ import type { DiscoveryError } from './discovery.js'/*** Map a discovery failure to an HTTP status for the OAuth discovery admin endpoints* (remote `POST /admin/mcp-servers/remote/discover` and generic- * `POST /admin/oauth/discover`). Extracted here (H-5) so both share ONE mapping.+ * `POST /admin/oauth/discover`) and for the remote install's own discovery. Extracted+ * here (H-5) so all of them share ONE mapping.*- * `fetch_failed` and `content_encoding_rejected` are upstream transport failures —- * the AS never returned a usable HTTP response — so they surface as 502, the same- * way the callback maps provider fetch failures (`provider_token_exchange_failed` /- * `provider_response_invalid` → 502). Every other kind is either bad operator input- * (`kernel_rejected`) or a reachable-but-incompatible/misconfigured AS: retrying will- * not help, and the returned `detail.kind` tells the operator what to fix, so 400 is- * the operator-actionable signal. The switch is exhaustive over `DiscoveryError` so a- * newly added kind fails to compile until its status is decided here.+ * `fetch_failed` and `content_encoding_rejected` mean a dependency failed — the AS or+ * the remote server never returned a usable response (an unknown Entra tenant answers+ * its well-known with a 400, for instance) — so they surface as 424 Failed Dependency.+ * Not a 5xx: the edge proxy (Cloudflare) replaces an origin 5xx with its own page, and+ * the wizard would lose the typed `detail` that says which dependency failed. Every+ * other kind is either bad operator input (`kernel_rejected`) or a reachable but+ * incompatible/misconfigured AS: retrying will not help, and `detail.kind` tells the+ * operator what to fix, so 400. No kind maps to a 5xx. The switch is exhaustive over+ * `DiscoveryError` so a newly added kind fails to compile until its status is decided here.*/export function discoveryHttpStatus(error: DiscoveryError): number {switch (error.kind) {case 'fetch_failed':case 'content_encoding_rejected':- return 502+ return 424case 'kernel_rejected':case 'invalid_metadata':case 'no_s256':diff --git a/control-api/src/routes/admin/__tests__/remoteMcpDiscoverErrorMapping.test.ts b/control-api/src/routes/admin/__tests__/remoteMcpDiscoverErrorMapping.test.tsindex 9ed7d9300..f2c14e96b 100644--- a/control-api/src/routes/admin/__tests__/remoteMcpDiscoverErrorMapping.test.ts+++ b/control-api/src/routes/admin/__tests__/remoteMcpDiscoverErrorMapping.test.ts@@ -62,13 +62,13 @@ function buildApp(discover: ReturnType<typeof fetchFailedDiscover>) {}describe('discoveryHttpStatus — DiscoveryError → HTTP status decision table', () => {- // One entry per DiscoveryError.kind. 502 = upstream transport failure (AS gave no- // usable HTTP response); 400 = operator-actionable (bad input or reachable-but-- // incompatible AS).+ // One entry per DiscoveryError.kind. 424 = a dependency failed (the AS or the remote+ // server gave no usable response); 400 = operator-actionable (bad input or reachable-+ // but-incompatible AS). Never a 5xx: the edge proxy would replace the typed body.const cases: Array<{ error: DiscoveryError; status: number }> = [{error: { kind: 'fetch_failed', url: 'https://as.example.test/x', detail: 'ECONNREFUSED' },- status: 502,+ status: 424,},{error: {@@ -76,7 +76,7 @@ describe('discoveryHttpStatus — DiscoveryError → HTTP status decision table'url: 'https://as.example.test/x',encoding: 'br',},- status: 502,+ status: 424,},{ error: { kind: 'kernel_rejected', field: 'baseUrl', errors: [] }, status: 400 },{@@ -129,6 +129,33 @@ describe('discoveryHttpStatus — DiscoveryError → HTTP status decision table'expect(discoveryHttpStatus(error)).toBe(status)})}++ it('the table lists every DiscoveryError kind exactly once', () => {+ const kinds = cases.map(c => c.error.kind)+ expect(new Set(kinds).size).toBe(kinds.length)+ expect([...kinds].sort()).toEqual(+ [+ 'as_endpoints_cross_site',+ 'authorization_server_override_rejected',+ 'content_encoding_rejected',+ 'fetch_failed',+ 'invalid_metadata',+ 'issuer_mismatch',+ 'kernel_rejected',+ 'no_authorization_server',+ 'no_s256',+ 'prm_resource_mismatch',+ 'redirect_blocked',+ 'tenant_required',+ ].sort()+ )+ })++ it('I8: no DiscoveryError kind maps to a 5xx', () => {+ for (const { error } of cases) {+ expect(discoveryHttpStatus(error)).toBeLessThan(500)+ }+ })})describe('POST /admin/mcp-servers/remote/discover — discovery error mapping', () => {@@ -136,7 +163,7 @@ describe('POST /admin/mcp-servers/remote/discover — discovery error mapping',vi.clearAllMocks()})- it('returns 502 (not 400) when discovery fails with fetch_failed (upstream transport)', async () => {+ it('returns 424 (not 400, not 5xx) when discovery fails with fetch_failed (upstream transport)', async () => {const discover = fetchFailedDiscover()const app = buildApp(discover)@@ -144,7 +171,7 @@ describe('POST /admin/mcp-servers/remote/discover — discovery error mapping',.post('/api/v1/admin/mcp-servers/remote/discover').send({ baseUrl: BASE_URL })- expect(res.status).toBe(502)+ expect(res.status).toBe(424)expect(res.body.error).toBe('discovery_failed')expect(res.body.detail.kind).toBe('fetch_failed')// Never hit the real network: the discovery seam was the only source of the outcome.diff --git a/control-api/test/routes.adminRemoteMcp.test.ts b/control-api/test/routes.adminRemoteMcp.test.tsindex f5364f91d..342c35fa8 100644--- a/control-api/test/routes.adminRemoteMcp.test.ts+++ b/control-api/test/routes.adminRemoteMcp.test.ts@@ -2687,6 +2687,19 @@ describe('Microsoft Entra ID — authorizationServer override on /discover and iexpect(res.body.detected.issForCallback).toBeUndefined()})+ it("row 4: an unknown tenant → 424 fetch_failed carrying Entra's 400 and its URL", async () => {+ const unknownTenant =+ 'https://login.microsoftonline.com/00000000-0000-0000-0000-000000000001/v2.0'+ const res = await request(await entraApp(ENTRA_WORKIQ_PILOT, gatewayWithContext()))+ .post('/admin/mcp-servers/remote/discover')+ .send({ baseUrl: ENTRA_WORKIQ_PILOT.mcpUrl, authorizationServer: unknownTenant })+ expect(res.status).toBe(424)+ expect(res.body.error).toBe('discovery_failed')+ expect(res.body.detail.kind).toBe('fetch_failed')+ expect(res.body.detail.status).toBe(400)+ expect(res.body.detail.url.startsWith('https://login.microsoftonline.com/')).toBe(true)+ })+it('Agent 365 Mail: offline_access, already in its PRM, is not added twice', async () => {const res = await request(await entraApp(ENTRA_AGENT365_MAIL_PILOT, gatewayWithContext())).post('/admin/mcp-servers/remote/discover')diff --git a/control-api/test/routes.oauthProviders.test.ts b/control-api/test/routes.oauthProviders.test.tsindex 48efd9554..a369f9aea 100644--- a/control-api/test/routes.oauthProviders.test.ts+++ b/control-api/test/routes.oauthProviders.test.ts@@ -114,7 +114,7 @@ describe('POST /admin/oauth/discover (E-19.5)', () => {expect(res.body.suggested.supportsRefresh).toBe(true)})- it('maps a transport failure to 502 (discoveryHttpStatus)', async () => {+ it('maps a transport failure to 424 (discoveryHttpStatus)', async () => {const discover: AdminOauthProvidersDeps['discover'] = async () => ({ok: false,error: { kind: 'fetch_failed', url: 'https://mcp.notion.com', detail: 'boom' },@@ -122,7 +122,7 @@ describe('POST /admin/oauth/discover (E-19.5)', () => {const res = await request(makeApp({ discover })).post('/admin/oauth/discover').send({ url: 'https://mcp.notion.com' })- .expect(502)+ .expect(424)expect(res.body.error).toBe('discovery_failed')expect(res.body.detail.kind).toBe('fetch_failed')})