Skip to content

fix: diagnose unavailable MySQL runtime providers#2116

Merged
chubes4 merged 3 commits into
mainfrom
fix-2006-mysql-provider-diagnostics
Jul 27, 2026
Merged

fix: diagnose unavailable MySQL runtime providers#2116
chubes4 merged 3 commits into
mainfrom
fix-2006-mysql-provider-diagnostics

Conversation

@chubes4

@chubes4 chubes4 commented Jul 27, 2026

Copy link
Copy Markdown
Collaborator

Summary

  • classify runtime-service process spawn ENOENT as a generic provider-unavailable diagnostic
  • identify the missing provider command while emitting only synthesized, bounded cause evidence
  • clean up the generic process executor's timeout immediately on spawn errors so unavailable commands cannot retain the CLI process
  • preserve provider unavailability when the command disappears during MySQL readiness while retaining ordinary Docker retry and failure classifications

Root cause

provisionMysqlDockerService caught the process spawn error from the Docker image/start path but discarded it, reducing every pre-start failure to { code: \"provision-failed\" }. When the docker executable was absent, the actionable ENOENT cause therefore never reached managed runtime-service evidence.

Two related lifecycle paths also needed correction:

  • Node's built-in child-process timeout remained referenced after spawn ENOENT, keeping the CLI alive until the Docker pull timeout elapsed.
  • waitForMysqlDatabase treated all Docker execution failures as retryable, so readiness-time ENOENT was eventually collapsed to readiness-failed.

The resulting structured diagnostic is:

{
  "code": "provider-unavailable",
  "command": "docker",
  "cause": {
    "code": "ENOENT",
    "message": "Provider command executable was not found"
  }
}

The evidence is provider-neutral and bounded: it does not forward raw stderr, process environment values, or an unbounded host error message. The generic process executor now owns an unref'd timeout and clears it on both spawn errors and process close. Readiness retries ordinary command failures but immediately preserves provider-command ENOENT.

Tests

  • timeout 20s npx tsx tests/runtime-services.test.ts
    • includes a child-process regression proving a missing command with a nominal 300-second timeout exits within 5 seconds
    • covers provider loss during docker exec
    • confirms ordinary Docker readiness command failures remain retryable
    • confirms ordinary start/readiness failures retain their existing classifications
  • npx tsx tests/external-mysql-runtime-service.test.ts
  • npx tsx tests/native-mariadb-runtime-service.test.ts
  • npm run build
  • git diff --check

The repository does not define a lint script; the workspace TypeScript build provides package typechecking.

MySQL remains fail-closed: an unavailable Docker provider still throws RuntimeServiceProvisionError, and no SQLite substitution or fallback was added.

Fixes #2006

@chubes4
chubes4 merged commit c2c6fe3 into main Jul 27, 2026
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.

Improve disposable MySQL diagnostics when Docker is unavailable

1 participant