Skip to content

Connector healthcheckPath + classified test errors (#3)#165

Merged
keysersoft merged 1 commit into
mainfrom
keysersoft/healthcheck-path
May 12, 2026
Merged

Connector healthcheckPath + classified test errors (#3)#165
keysersoft merged 1 commit into
mainfrom
keysersoft/healthcheck-path

Conversation

@keysersoft
Copy link
Copy Markdown
Contributor

Problem

`POST /api/connectors/:id/test` always hit `baseUrl + '/'`. APIs without a root handler returned 404 and the UI flashed red even when the connector was fine. We also couldn't distinguish:

  • wrong path (404)
  • wrong credentials (401/403)
  • network unreachable (DNS/SSRF/timeout)

They all surfaced as the same generic failure.

Changes

Schema (additive migration)

  • `Connector.healthcheckPath String?` — the path used by Test Connection. Defaults to `/` when null.

Parser

  • New `OpenApiParser.parseSpec` / `parseSpecFromUrl` return `{ tools, healthcheckPath? }`. The legacy `parse()` / `parseFromUrl()` are now thin wrappers preserving their old shape for any external callers.
  • `detectHealthcheckPath` priority: `/health`, `/healthz`, `/_health`, `/ping`, `/status` → first non-parametric GET with no required params → `undefined`.

Service

  • `testConnection()` uses `connector.healthcheckPath` when set and returns a `kind` classification:
    • `ok` — 2xx
    • `auth_failed` — 401/403 (handshake reached the API)
    • `not_found` — 404 (path doesn't exist; hint to set healthcheckPath)
    • `unreachable` — DNS, ECONNREFUSED, SSRF guard, timeout
    • `unsupported` — connector type with no test impl
    • `error` — anything else (5xx, parse error)

Controller

  • Both import flows (`POST /import-spec` and `POST /import` with `source: 'openapi'`) write the auto-detected `healthcheckPath` when the user hasn't already set one. Re-import preserves a user's explicit setting.
  • `CreateConnectorDto` / `UpdateConnectorDto` expose the field.

Frontend

  • Connector detail page: edit form gets a "Healthcheck path" input with explanatory hint (REST connectors only).
  • Test result banner colours/labels by kind: yellow `Auth rejected:` for 401/403; red `Not found:`/`Unreachable:`/`Error:` otherwise. Successful tests stay green.
  • `api.ts` client typed for the new response shape.

Test plan

  • 4 new unit tests for `detectHealthcheckPath` (preferred path, fallback chain, first GET, no eligible GET).
  • `tsc --noEmit` exit 0 (backend + frontend).
  • `npm test` → 624 passed across 25 suites.
  • After deploy: import a spec with `/health` → check Connector.healthcheckPath populated. Hit Test → expect `kind: 'ok'`.
  • After deploy: change healthcheckPath to `/does-not-exist` → Test should return `kind: 'not_found'` with the hint.

…t errors

Before this, POST /api/connectors/:id/test always hit baseUrl + '/'.
APIs without a root handler returned 404 and the UI flashed red even
though the connector was fine. We also couldn't tell 'wrong path' from
'wrong credentials' or 'network down' — they all looked the same.

Schema:
- new Connector.healthcheckPath String? column (additive migration)

Parser:
- new OpenApiParser.parseSpec / parseSpecFromUrl return { tools,
  healthcheckPath? }. parse() / parseFromUrl() keep their old shape
  for back-compat.
- detectHealthcheckPath: tries /health, /healthz, /_health, /ping,
  /status first; falls back to the first non-parametric GET with no
  required params.

Service:
- testConnection() now uses connector.healthcheckPath when set and
  returns a 'kind' classification: ok | auth_failed (401/403) |
  not_found (404, with hint to set healthcheckPath) | unreachable
  (DNS/SSRF/timeout) | unsupported | error.

Controller:
- both import flows (import-spec, import) write the detected
  healthcheckPath when the user hasn't already set one.
- CreateConnectorDto / UpdateConnectorDto expose the new field.

Frontend:
- connector detail page: edit form has a Healthcheck path input with
  hint; the test result banner colours and labels by kind (auth
  rejected, not found, unreachable, error).
- api.ts client typed for the new response shape.
@keysersoft keysersoft requested a review from mirkopoloni as a code owner May 11, 2026 23:53
@keysersoft keysersoft merged commit 377d52f into main May 12, 2026
11 checks passed
@keysersoft keysersoft deleted the keysersoft/healthcheck-path branch May 12, 2026 00:33
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant