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

Author: msbrogli

hathor/api/openapi/decorators.py

@@ -58,6 +58,8 @@ class EndpointMetadata:
     deprecated: bool
     path_params_regex: dict[str, str]
     path_params_descriptions: dict[str, str]
+    catch_hathor_exceptions: bool
+    max_body_size: int
 
 
 # Global registry of endpoint metadata
@@ -152,6 +154,17 @@ def _parse_rate_limit(rl: dict[str, Any]) -> RateLimitConfig:
     return RateLimitConfig(rate=rl['rate'], burst=rl['burst'], delay=rl['delay'])
 
 
+def _sanitize_validation_error(e: Any) -> str:
+    """Format a Pydantic ValidationError into a safe, user-facing message.
+
+    Strips model internals and only includes field paths and messages.
+    """
+    return '; '.join(
+        f"{'.'.join(str(loc) for loc in err['loc'])}: {err['msg']}"
+        for err in e.errors()
+    )
+
+
 def api_endpoint(
     *,
     path: str,
@@ -169,6 +182,8 @@ def api_endpoint(
     deprecated: bool = False,
     path_params_regex: dict[str, str] | None = None,
     path_params_descriptions: dict[str, str] | None = None,
+    catch_hathor_exceptions: bool = True,
+    max_body_size: int = 1_000_000,
 ) -> Callable[[F], F]:
     """Decorator to register an endpoint with OpenAPI metadata and auto-validate/serialize.
 
@@ -204,6 +219,8 @@ def api_endpoint(
         deprecated: Whether this endpoint is deprecated
         path_params_regex: Regex patterns for path parameters
         path_params_descriptions: Descriptions for path parameters
+        catch_hathor_exceptions: Whether to catch HathorError and return ErrorResponse (default True)
+        max_body_size: Maximum request body size in bytes (default 1MB)
     """
     def decorator(func: F) -> F:
         # Parse rate limit configs
@@ -226,8 +243,21 @@ def decorator(func: F) -> F:
             deprecated=deprecated,
             path_params_regex=path_params_regex or {},
             path_params_descriptions=path_params_descriptions or {},
+            catch_hathor_exceptions=catch_hathor_exceptions,
+            max_body_size=max_body_size,
         )
 
+        # Check for duplicate registrations
+        key = (metadata.path, metadata.method)
+        for existing in _endpoint_registry:
+            if (existing.path, existing.method) == key:
+                if existing.operation_id == metadata.operation_id:
+                    # Same endpoint decorated again (e.g. module re-executed by pytest --doctest-modules)
+                    return func
+                raise ValueError(
+                    f"Duplicate endpoint registration: {metadata.method} {metadata.path}"
+                )
+
         # Resolve imports once per decorated function, not per request
         import json as _json
 
@@ -236,6 +266,7 @@ def decorator(func: F) -> F:
         from twisted.web.server import NOT_DONE_YET as _NOT_DONE_YET
 
         from hathor.api_util import set_cors
+        from hathor.exception import HathorError
         from hathor.utils.api import ErrorResponse as _LegacyErrorResponse
 
         @functools.wraps(func)
@@ -262,16 +293,31 @@ def wrapper(self: Any, request: Request, *args: Any, **kwargs: Any) -> Any:
                         request.setResponseCode(400)
                         return error.json_dumpb()
                     body_bytes = request.content.read()
+                    if len(body_bytes) > max_body_size:
+                        error = ErrorResponse(error=f'Request body too large (max {max_body_size} bytes)')
+                        request.setResponseCode(413)
+                        return error.json_dumpb()
                     body_data = _json.loads(body_bytes)
                     body = request_model.model_validate(body_data)
-                except (ValidationError, _json.JSONDecodeError, UnicodeDecodeError) as e:
-                    error = ErrorResponse(error=str(e))
+                except ValidationError as e:
+                    error = ErrorResponse(error=_sanitize_validation_error(e))
+                    request.setResponseCode(400)
+                    return error.json_dumpb()
+                except (_json.JSONDecodeError, UnicodeDecodeError):
+                    error = ErrorResponse(error='Request body is not valid JSON')
                     request.setResponseCode(400)
                     return error.json_dumpb()
                 kwargs['body'] = body
 
             # Call the actual handler
-            result = func(self, request, *args, **kwargs)
+            try:
+                result = func(self, request, *args, **kwargs)
+            except HathorError as e:
+                if not catch_hathor_exceptions:
+                    raise
+                error = ErrorResponse(error=str(e))
+                request.setResponseCode(getattr(e, 'status_code', 400))
+                return error.json_dumpb()
 
             # Auto-serialize response
             if isinstance(result, Deferred):

hathor/api/openapi/generator.py

@@ -121,7 +121,14 @@ def _get_response_models(self, metadata: EndpointMetadata) -> list[type[BaseMode
         # Check if it's a Union type
         args = typing.get_args(metadata.response_model)
         if args:
-            return list(args)
+            models = []
+            for a in args:
+                if a is type(None):
+                    continue
+                if not (isinstance(a, type) and issubclass(a, BaseModel)):
+                    raise TypeError(f"response_model Union contains non-BaseModel type: {a}")
+                models.append(a)
+            return models
 
         # Single model
         return [metadata.response_model]
@@ -311,4 +318,8 @@ def _extract_defs(self, schema: dict[str, Any], target: dict[str, Any]) -> None:
         if '$defs' in schema:
             for def_name, def_schema in schema.pop('$defs').items():
                 self._extract_defs(def_schema, target)
+                if def_name in target and target[def_name] != def_schema:
+                    raise ValueError(
+                        f"$defs collision for '{def_name}': different schemas share the same name"
+                    )
                 target[def_name] = def_schema

hathor/api/schemas/__init__.py

@@ -14,20 +14,12 @@
 
 """Pydantic schemas for API request/response validation and OpenAPI generation."""
 
-from hathor.api.schemas.base import (
-    ErrorResponse,
-    ErrorResponseModel,
-    OpenAPIExample,
-    RequestModel,
-    ResponseModel,
-    SuccessResponse,
-)
+from hathor.api.schemas.base import ErrorResponse, ErrorResponseModel, OpenAPIExample, ResponseModel, SuccessResponse
 
 __all__ = [
     'ErrorResponse',
     'ErrorResponseModel',
     'OpenAPIExample',
-    'RequestModel',
     'ResponseModel',
     'SuccessResponse',
 ]

hathor/api/schemas/base.py

@@ -33,14 +33,6 @@ class OpenAPIExample:
     value: BaseModel
 
 
-class RequestModel(BaseModel):
-    """Base class for POST/PUT request bodies.
-
-    Inherits from BaseModel with extra='forbid' and frozen=True.
-    """
-    pass
-
-
 class ResponseModel(BaseModel):
     """Base class for all API responses.
 

hathor/healthcheck/resources/healthcheck.py

@@ -189,7 +189,7 @@ def __init__(self, manager: HathorManager):
         rate_limit_global=[{'rate': '10r/s', 'burst': 10, 'delay': 5}],
         rate_limit_per_ip=[{'rate': '1r/s', 'burst': 3, 'delay': 2}],
         query_params_model=HealthcheckParams,
-        response_model=Union[HealthcheckSuccessResponse, HealthcheckFailResponse],
+        response_model=Union[HealthcheckSuccessResponse, HealthcheckFailResponse, HealthcheckStrictFailResponse],
     )
     def render_GET(self, request: Request, *, params: HealthcheckParams) -> Deferred:
         """ GET request /health/

hathor/transaction/resources/validate_address.py

@@ -77,7 +77,7 @@ class _ValidateAddressResource(Resource):
     """
     isLeaf = True
 
-    def __init__(self, manager: HathorManager, address: Union[str, bytes]):
+    def __init__(self, manager: HathorManager, address: Union[str, bytes]) -> None:
         super().__init__()
         # Important to have the manager so we can know the tx_storage
         self.manager = manager
@@ -108,7 +108,7 @@ def render_GET(self, request):
         except Exception as e:
             return ValidateAddressErrorResponse(
                 valid=False,
-                error=type(e).__name__,
+                error='invalid_address',
                 msg=str(e),
             )
 

hathor/version_resource.py

@@ -80,7 +80,7 @@ class VersionResponse(ResponseModel):
 
 @register_resource
 class VersionResource(Resource):
-    """ Implements a web server API with POST to return the api version and some configuration
+    """ Implements a web server API with GET to return the api version and some configuration
 
     You must run with option `--status <PORT>`.
     """

hathor_cli/openapi_json.py

@@ -94,7 +94,7 @@ def main():
     parser = create_parser()
     parser.add_argument('--indent', type=int, default=None, help='Number of spaces to use for indentation')
     parser.add_argument('out', type=argparse.FileType('w', encoding='UTF-8'), default=get_default_output_path(),
-                        nargs='?', help='Output file where OpenSPI json will be written')
+                        nargs='?', help='Output file where OpenAPI json will be written')
     args = parser.parse_args()
 
     openapi = get_openapi_dict()