Repository navigation
Description
Current scope
Priority: HIGH
Effort: HIGH
Consume the existing public omnisdk.HTTPStatusError contract in StackQL. The currently pinned omnisdk v0.1.11-beta1 already exposes StatusCode(), ResponseBody() and RequestURL() through errors.As.
- Public contract: https://github.com/stackql-labs/omnisdk/blob/v0.1.11-beta1/pkg/omnisdk/http_error.go
- Public query regression that recovers a later-page HTTP failure through
errors.As: https://github.com/stackql-labs/omnisdk/blob/v0.1.11-beta1/pkg/omnisdk/pagination_error_test.go#L100 - Remaining host classifier: https://github.com/stackql/stackql/blob/main/internal/stackql/mcpbackend/mcp_service_stackql.go
This issue is not blocked on a future any-sdk release or a new SDK status-code feature. The HIGH effort rating is a planning override for the complete integration and regression work; it is not evidence of a missing SDK API. Recreate an omnisdk defect only if a concrete execution path is shown to lose the public error contract.
Acceptance
- Replace HTTP-status regex classification in
classifyBackendErrorwitherrors.As(err, &response)usingomnisdk.HTTPStatusError. - Preserve wrapped typed errors through execution, streaming/pagination, staging and MCP response handling. Formatting diagnostics must not replace the programmatic error chain.
- Preserve the established read-404 empty-result policy without suppressing authentication or mutation failures.
- Preserve MCP
http_statusandretryablebehavior: 408/429/5xx retryable; other 4xx not retryable under the existing contract. - Cover 403, 404, 408, 429 and 5xx; JSON, HTML, XML, plain-text and empty bodies; misleading body text; wrapped and late-page errors; and GraphQL HTTP failures. A 403 body mentioning "404" or "not found" must remain 403.
- Transport failures without an HTTP response must not acquire an invented HTTP status. HTTP-200 GraphQL payload errors remain separate from HTTP-status classification.
- Remove obsolete HTTP-status text fallbacks. Do not require deleted any-sdk execution classes or duplicate SDK functionality.
- Keep the existing MCP 403/429/404 robot regressions and add focused host unit coverage.
Legacy origin
Supersedes the dependency on stackql/any-sdk#115. Its requested typed-error alternative is supplied by the pinned omnisdk API. StackQL #681 stays open until host integration and acceptance pass.
Original any-sdk design (historical)
Description
The issue #670 fix (MCP tools surface upstream HTTP errors instead of empty result sets, with 404 exempted as database-semantics "zero rows") currently recovers the upstream status by parsing any-sdk's error message text, because the status code is not carried through the any-sdk invoker boundary (providerinvoker.Result is just {Body, Messages}):
internal/stackql/execution(isUpstreamNotFound): the structured fragment regex(?i)status code:?\s*(\d{3})is authoritative when present (a 403 whose body mentions "not found" is still an error); unstructured bodies (HTML / XML / plain text published verbatim) fall back to a loose, any-case match:
var upstreamNotFoundLooseRegex = regexp.MustCompile(`(?i)\b404\b|not\s+found`)internal/stackql/mcpbackend(classifyBackendError): the same fragment regex classifies MCP tool errors asupstream http error: {"http_status": N, "retryable": bool}(408/429/5xx retryable).
This works for mainstream provider error shapes but is fragile by construction: the status is only present when any-sdk happens to format it into the text, and the loose fallback trades precision for safety (a false positive restores the historical empty-result behaviour, which is the safe direction).
Proposal
Once lands and the any-sdk dependency is bumped:
- Read
StatusCodefrom the invoker result ininternal/stackql/execution(monoValentExecution.GetExecutor): exempt 404 by value, error on other 4xx/5xx under strict upstream error semantics (MCP only). - Classify by value in
internal/stackql/mcpbackend(classifyBackendError), keeping the wire contract (http_status,retryable) unchanged. - Delete
upstreamStatusCodeRegex(both copies),upstreamNotFoundLooseRegexand the text handling inisUpstreamNotFound.
The behaviour contract is already pinned by robot scenarios in test/robot/functional/mcp.robot and stays unchanged as the regression net:
MCP HTTP Upstream 403 Surfaces As Non Retryable Tool Error
MCP HTTP Upstream 429 Surfaces As Retryable Tool Error
MCP HTTP Upstream 404 Returns Empty Result Set
Activity
[-][FEATURE] Consume the naked upstream HTTP status code from any-sdk and remove response-text munging[/-][+][FEATURE] Consume typed upstream HTTP status from omnisdk and remove response-text munging[/+]