feat(openapi): Harden @api_endpoint decorator and OpenAPI generator

[msbrogli]

Motivation

The @api_endpoint decorator and OpenAPI generator introduced in the pydantic migration PR had several gaps identified during code review: unhandled HathorError exceptions would propagate as 500s, Pydantic ValidationError messages leaked model internals to API consumers, there was no request body size limit, duplicate endpoint registrations were silently accepted, and the OpenAPI generator could crash on Optional response models or silently overwrite conflicting $defs. This PR addresses all approved findings from that review.

Acceptance Criteria

• @api_endpoint catches HathorError raised in handlers and returns a structured ErrorResponse with HTTP 400 (or the exception's status_code attribute). This behavior can be disabled per-endpoint with catch_hathor_exceptions=False
• Pydantic ValidationError messages are sanitized to only include field paths and messages (e.g., age: Input should be a valid integer), not raw model internals
• Malformed JSON request bodies return "Request body is not valid JSON" instead of the raw JSONDecodeError message
• Request body size is enforced with a configurable max_body_size parameter (default 1MB), returning HTTP 413 when exceeded
• Duplicate endpoint registrations (same path + method) are detected at decoration time and raise ValueError immediately
• The OpenAPI generator skips NoneType from Optional[...] unions and raises TypeError for any other non-BaseModel type in a response model union
• $defs name collisions in the OpenAPI generator raise ValueError instead of silently overwriting
• Healthcheck endpoint's response_model includes HealthcheckStrictFailResponse so the OpenAPI spec documents the strict_status_code=1 behavior
• validate_address error responses use a stable 'invalid_address' error code instead of leaking Python exception class names (e.g., 'ScriptError', 'InvalidAddress')
• Unused RequestModel base class removed
• Minor nits: docstring fix (POST -> GET) in VersionResource, typo fix (OpenSPI -> OpenAPI) in CLI help, type annotation added to validate_address.render_GET

Checklist

• If you are requesting a merge into master, confirm this code is production-ready and can be included in future releases as soon as it gets merged
• Breaking API change: validate_address error responses now return error: 'invalid_address' instead of the Python exception class name — clients matching on specific error strings will need updating

[github-actions]

Bencher Report

Branch	feat/openapi-improvements
Testbed	ubuntu-22.04

Click to view all benchmark results

Benchmark	Latency	Benchmark Result minutes (m) (Result Δ%)	Lower Boundary minutes (m) (Limit %)	Upper Boundary minutes (m) (Limit %)
sync-v2 (up to 20000 blocks)	📈 view plot 🚷 view threshold	1.60 m (-6.44%) Baseline: 1.71 m	1.54 m (96.19%)	2.05 m (77.97%)

🐰 View full continuous benchmarking report in Bencher

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 85.40%. Comparing base (f0c17ad) to head (199c42b).
⚠️ Report is 1 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1617      +/-   ##
==========================================
+ Coverage   85.38%   85.40%   +0.02%     
==========================================
  Files         462      462              
  Lines       31135    31166      +31     
  Branches     4720     4730      +10     
==========================================
+ Hits        26584    26617      +33     
- Misses       3639     3641       +2     
+ Partials      912      908       -4     

Flag	Coverage Δ
test-lib	85.39% <100.00%> (+0.01%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ 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.