fix(staking-cli): improve metadata fetching robustness and error messages

[sveitser]

Fixes metadata fetching to handle edge cases and provide clear error messages when URLs return incorrect or malformed content.

Changes:

• Ignore Content-Type headers completely (GitHub raw URLs serve JSON as text/plain)
• Parse JSON in two steps to distinguish syntax errors from schema errors
• Show clear schema-only errors for valid JSON with wrong structure
• Preserve dual-format errors for truly malformed content
• Add empty body detection with clear error message
• Refactor test infrastructure with MetadataServerBuilder pattern
• Improve MetadataServer API ergonomics (add_cli_args instead of cli_args)

Error message improvements:
Before: "failed to parse as JSON (missing field) or OpenMetrics (...)" After: "valid JSON but incorrect schema: missing field pub_key"

This fixes validator registration with GitHub-hosted metadata files while maintaining backward compatibility with all metadata sources.

[sveitser]

/gemini review

[gemini-code-assist]

Summary of Changes

Hello @sveitser, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the staking-cli's ability to reliably fetch and interpret metadata from external sources. By making the metadata parsing logic more resilient to unexpected Content-Type headers and introducing a granular two-step JSON validation process, the CLI can now provide clearer, more actionable error messages to users. The refactoring of the test infrastructure ensures that these improvements are thoroughly validated across a wider range of scenarios, ultimately leading to a more stable and user-friendly experience for validator registration and metadata management.

Highlights

• Robust Metadata Fetching: The metadata fetching mechanism now ignores Content-Type headers, always attempts JSON parsing first, and falls back to OpenMetrics if JSON parsing fails. This improves compatibility with services like GitHub raw that may serve JSON with a 'text/plain' Content-Type.
• Enhanced JSON Parsing and Error Reporting: JSON parsing is now a two-step process: first validating syntax, then validating the schema. This allows for more precise error messages, distinguishing between malformed JSON and valid JSON that doesn't conform to the expected schema. Clear error messages are also provided for empty response bodies.
• Refactored Test Infrastructure: The test suite for metadata servers has been refactored using a new MetadataServerBuilder pattern. This improves the ergonomics and flexibility of setting up test servers with various content types and formats, leading to more comprehensive testing of edge cases.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Changelog

• staking-cli/src/metadata.rs
  • Modified fetch_metadata to ignore Content-Type headers, prioritizing JSON parsing and falling back to OpenMetrics.
  • Implemented a two-step JSON parsing process to differentiate between JSON syntax errors and schema validation errors.
  • Added explicit error handling and messaging for empty response bodies.
  • Improved error messages to be more specific about the nature of parsing failures (e.g., 'valid JSON but incorrect schema').
  • Updated documentation comments to reflect the new metadata parsing logic.
  • Added new test cases for text/plain JSON, empty body responses, and valid JSON with incorrect schema.
• staking-cli/tests/cli.rs
  • Removed deprecated MetadataMockServer struct and start_metadata_server function.
  • Introduced ContentType enum for flexible content-type header testing in mock servers.
  • Refactored metadata server setup into a MetadataServerBuilder pattern for improved test ergonomics and configurability.
  • Updated MetadataServer to use add_cli_args method for appending CLI arguments, replacing the previous cli_args method.
  • Migrated all existing CLI tests that interact with metadata servers to utilize the new MetadataServerBuilder.
  • Added new CLI tests to cover scenarios with various Content-Type headers, empty responses, and invalid content, ensuring robust error reporting.

Activity

• The author sveitser initiated this pull request to address robustness issues and improve error messages in metadata fetching.
• The changes focus on making the staking-cli more resilient to edge cases in metadata retrieval, such as incorrect Content-Type headers from sources like GitHub raw.
• Key updates include a refined JSON parsing strategy and more informative error messages for users.
• The test infrastructure has been significantly refactored to support more comprehensive testing of these new robustness features.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request significantly improves the robustness of metadata fetching by ignoring Content-Type headers and attempting to parse content as JSON first, then falling back to OpenMetrics. This handles edge cases like GitHub raw URLs serving JSON as text/plain. The error messaging is also greatly improved by distinguishing between JSON syntax errors and schema errors, and by providing combined error messages when both formats fail to parse. The test infrastructure has been substantially refactored using a builder pattern, which enhances test clarity and maintainability. A comprehensive set of new tests has been added to validate the new logic and error handling. The changes are of high quality and well-executed. I have one suggestion to strengthen a test assertion.

[gemini-code-assist]

Code Review

This pull request significantly improves the robustness of metadata fetching by ignoring Content-Type headers, implementing a two-step JSON parsing process for better error diagnostics, and adding checks for empty response bodies. The refactoring of the test infrastructure to use a MetadataServerBuilder pattern is a great enhancement, making the tests cleaner and more maintainable. The new tests are comprehensive and effectively validate the new logic and error handling. Overall, this is a high-quality contribution.

[sveitser]

/gemini review

[gemini-code-assist]

Code Review

This pull request significantly improves the robustness of metadata fetching and provides much clearer error messages, which is a great enhancement for user experience and debugging. The introduction of the MetadataError enum for structured error handling is a solid improvement. The logic to ignore Content-Type and perform a two-step JSON parsing to distinguish between syntax and schema errors is well-implemented and addresses real-world issues like GitHub raw URLs.

The refactoring of the test suite is also a major highlight. The MetadataServerBuilder pattern makes test setup cleaner and more maintainable. The new tests are comprehensive, covering various success and failure scenarios, including the new error conditions and edge cases like empty responses.

Overall, this is a high-quality contribution that improves both the application logic and its testability. The code is clean, well-documented, and thoroughly tested.

[imabdulbasit]

Looks good.