stacklok / toolhive / 24826193687

push

github

Classify OCI pull errors and fall back to git for skills content API (#5014)

* Surface upstream error messages for 502/503/504 in API handler

Today every 5xx response body collapses to http.StatusText(code), which is appropriate for 500 (may wrap DB drivers, container runtimes, connection strings) but hides actionable detail for 502/503/504 — which are explicitly about upstream failures the caller can act on.

Branch the 5xx path: keep 500 generic, include err.Error() in the body for 502/503/504. Server-side slog/OTel/Sentry reporting is unchanged.

* Classify OCI pull errors into sharper HTTP status codes

Registry.Pull failures in getContentFromOCI and installFromOCI were all mapped to a flat 502 Bad Gateway, so a 401 from GHCR, a missing manifest, a 429, and a network outage all looked identical to the caller.

Add classifyPullError to inspect oras-go errors: context.DeadlineExceeded/Canceled → 504; *errcode.ErrorResponse 401/403 → 401, 404 → 404, 429 → 429, other 4xx/5xx → 502; errdef.ErrNotFound → 404; fallback → 502.

Wire into content.go and install_oci.go at the Pull call sites. 4xx classifications flow through the unchanged 4xx handler path so auth/not-found errors surface verbatim without relying on the 5xx body change.

* Fall back to registry-declared git package when OCI pull fails

A content-preview request for an OCI ref that also appears in the skill registry with a git package was returned as a flat error as soon as the OCI pull failed, even though the catalog declared a perfectly good git mirror alongside the OCI artifact.

Add resolveGitFallbackForOCIRef in registry.go. It searches the catalog by the refs tail path segment, keeps entries whose OCI package identifier parses to the same repository path (tag/digest agnostic, so :0.1.0 and :latest match), and returns the single matching entry's pinned git:// URL. Ambiguous matches are deliberately skipped — refusing to guess is better than silently serving the wrong skill.

Wire into ... (continued)

105 of 118 new or added lines in 5 files covered. (88.98%)

58837 of 88735 relevant lines covered (66.31%)

63.11 hits per line