Introduce service layer and improve API/CLI error handling

[dmjb]

Summary

This PR consolidates registry configuration logic into a service layer and improves error handling in both the API and CLI with proper HTTP status codes and user-friendly messages.

This is part 2 of 3 PRs that improve registry API error handling:

1. ✅ Add registry validation and structured errors #3479 - Add validation infrastructure and error types
2. This PR: Introduce service layer and improve API/CLI error handling
3. Update E2E tests

Depends on: #3479 (builds on structured error types)

Changes

Service Layer

• New: RegistryConfigService interface (pkg/config/registry_service.go)
  • Consolidates registry configuration operations
  • SetRegistryFromInput(): Auto-detects registry type (URL/API/File)
  • UnsetRegistry(): Resets to default registry
  • GetRegistryInfo(): Returns current registry configuration
• Add comprehensive service tests (pkg/config/registry_service_test.go)
• Generate mocks for testing (pkg/config/mocks/mock_registry_service.go)

API Layer (pkg/api/v1/registry.go)

• Map errors to proper HTTP status codes:
  • 502 Bad Gateway: Validation errors (invalid JSON, missing servers)
  • 504 Gateway Timeout: Connectivity/timeout errors (unreachable hosts)
  • 400 Bad Request: Invalid request format
• Add isConnectivityError() and isValidationError() helpers
• Refactor updateRegistry() to use RegistryConfigService
• Add timeout integration tests (pkg/api/v1/registry_timeout_test.go)

CLI Layer (cmd/thv/app/config.go)

• Use RegistryConfigService for cleaner, more maintainable code
• Add enhanceRegistryError() for user-friendly error messages with actionable hints
• Map error types to match API behavior (504 for timeout, 502 for validation)
• Provide helpful troubleshooting steps for common failures

Benefits

1. Single source of truth: Registry logic consolidated in service layer
2. Proper HTTP semantics: Correct status codes for different error types
3. Better UX: Users get actionable error messages with hints
4. Easier testing: Service abstraction enables better unit testing
5. Consistency: API and CLI handle errors the same way

Example Error Messages

Before

Error: failed to set registry: invalid registry format

After

Error: validation failed
The registry at https://example.com/registry.json returned an invalid response or does not appear to be a valid registry.
Please verify:
  - The URL points to a valid MCP registry
  - The registry format is correct
  - The registry contains at least one server
Original error: registry validation failed: registry contains no servers

Testing

• Added comprehensive service layer tests
• Added API timeout integration tests
• Updated existing tests to use service layer
• All tests pass with new error handling

🤖 Generated with Claude Code

Fixes: #3464

[codecov]

Codecov Report

❌ Patch coverage is 66.66667% with 39 lines in your changes missing coverage. Please review.
✅ Project coverage is 65.25%. Comparing base (ebf0f55) to head (8694a6c).

Files with missing lines	Patch %	Lines
pkg/api/v1/registry.go	66.10%	13 Missing and 7 partials ⚠️
pkg/registry/service.go	67.24%	15 Missing and 4 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3480      +/-   ##
==========================================
+ Coverage   65.23%   65.25%   +0.01%     
==========================================
  Files         398      399       +1     
  Lines       38793    38865      +72     
==========================================
+ Hits        25308    25362      +54     
- Misses      11525    11538      +13     
- Partials     1960     1965       +5     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.