stacklok / toolhive / 25731188325

push

github

fix(registry): surface legacy registry format as a structured API error (#5260)

* Surface legacy registry format as a structured API error

Before this change, when a configured custom registry URL served data in
the legacy ToolHive format, NewRemoteRegistryProvider returned a plain
fmt.Errorf that the API handler did not recognise. The API responded with
a generic HTTP 500 "Failed to get registry provider", and the actionable
migration hint was visible only in main.log. Desktop clients had no way
to distinguish this case from an internal error.

Add a typed *LegacyFormatError (sister of *UnavailableError) carrying the
offending source URL. Wire it through the four registry GET handlers and
the v0.1 router so the response is now HTTP 503 with a structured
"registry_legacy_format" code and the migration hint in the message body.

The upstream_parser sentinel errLegacyFormat is now an instance of
*LegacyFormatError; its Is() method preserves errors.Is(err, errLegacyFormat)
for existing callers while enabling errors.As extraction of the URL.

Fixes #5259

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* Switch registry_legacy_format status code to 502 Bad Gateway

503 was inconsistent with the existing PUT registry handler that already
returns 502 for the same legacy-format detection via ErrRegistryValidationFailed
(pkg/api/v1/registry.go updateRegistry handler). 502 is also the correct
RFC 9110 §15.6.3 code: thv serve acts as a gateway to the upstream registry
and the upstream returned a response we cannot process.

503 is reserved for "temporary overload or scheduled maintenance" which does
not match a misconfigured registry source.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* Fix stale 503 references in doc comments

Two doc comments missed the 502 update from the previous commit. The code
itself already returns 502 Bad Gateway via writeRegistryLegacyFormatError;
only the comments were inconsistent.
... (continued)

25 of 49 new or added lines in 4 files covered. (51.02%)

64039 of 98500 relevant lines covered (65.01%)

62.81 hits per line