fastapi-openrpc 0.1.7__tar.gz → 0.2.0__tar.gz

{fastapi_openrpc-0.1.7 → fastapi_openrpc-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: fastapi-openrpc
-Version: 0.1.7
+Version: 0.2.0
 Summary: FastAPI JSON-RPC 2.0 + OpenRPC 1.0 service discovery plugin
 Keywords: fastapi,json-rpc,openrpc,rpc,discover,ai-agent
 Author: Ye Wenbin

{fastapi_openrpc-0.1.7 → fastapi_openrpc-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fastapi-openrpc"
-version = "0.1.7"
+version = "0.2.0"
 description = "FastAPI JSON-RPC 2.0 + OpenRPC 1.0 service discovery plugin"
 readme = "README.md"
 license = {text = "MIT"}

{fastapi_openrpc-0.1.7 → fastapi_openrpc-0.2.0}/src/fastapi_openrpc/authorization.py

@@ -26,6 +26,7 @@ class AuthorizationPolicy(Protocol):
         self,
         method_name: str,
         required_roles: list[str],
+        require: Require,
         ctx: RpcContext,
     ) -> bool:
         """Determine whether the caller is authorized to invoke the specified method.
@@ -33,7 +34,8 @@ class AuthorizationPolicy(Protocol):
         Args:
             method_name: The name of the RPC method being invoked.
             required_roles: List of roles required by the method.
-            ctx: Caller context containing roles and require fields.
+            require: Role combination semantics (ANY/ALL) declared by the method.
+            ctx: Caller context containing roles and user_id fields.
 
         Returns:
             True if authorization is granted, False otherwise.
@@ -55,6 +57,7 @@ class RoleBasedAuthorizationPolicy:
         self,
         method_name: str,
         required_roles: list[str],
+        require: Require,
         ctx: RpcContext,
     ) -> bool:
         # Empty role list -> skip check (backward compatible, R3)
@@ -65,7 +68,7 @@ class RoleBasedAuthorizationPolicy:
             ctx_roles = {r.lower() for r in ctx.roles}
             needed = {r.lower() for r in required_roles}
 
-            if ctx.require == Require.ALL:
+            if require == Require.ALL:
                 return needed <= ctx_roles  # All required_roles present in ctx.roles
             else:
                 # Require.ANY (default)

{fastapi_openrpc-0.1.7 → fastapi_openrpc-0.2.0}/src/fastapi_openrpc/decorator.py

@@ -400,6 +400,53 @@ def _resolve_result_model(
     return resolved, schema
 
 
+# JSON-native types allowed as (parts of) return annotations
+_JSON_NATIVE_RETURN_TYPES = (dict, list, str, int, float, bool)
+
+
+def _is_json_serializable_annotation(annotation: Any) -> bool:
+    """Recursively check that an annotation only contains JSON-native types
+    or Pydantic models: dict/list/str/int/float/bool/None/Any, BaseModel
+    subclasses, and unions/generics thereof."""
+    if annotation is None or annotation is type(None) or annotation is typing.Any:
+        return True
+    if _is_pydantic_model(annotation):
+        return True
+    if isinstance(annotation, type) and issubclass(annotation, _JSON_NATIVE_RETURN_TYPES):
+        return True
+    origin = typing.get_origin(annotation)
+    args = typing.get_args(annotation)
+    if origin is typing.Union or origin is types.UnionType:
+        return all(_is_json_serializable_annotation(a) for a in args)
+    if origin in (dict, list):
+        # dict[str, X], list[X], typing.Dict/list aliases — get_origin returns builtin
+        return all(_is_json_serializable_annotation(a) for a in args)
+    return False
+
+
+def _validate_return_annotation(func: Callable[..., Any], name: str) -> None:
+    """Reject return annotations that json.dumps cannot serialize.
+
+    Results flow into JSONResponse's json.dumps; a datetime/custom-class
+    annotation guarantees a runtime TypeError. Failing at registration
+    surfaces the misconfiguration at startup instead.
+    """
+    try:
+        hints = typing.get_type_hints(func)
+    except (TypeError, AttributeError, NameError):
+        return
+    return_type = hints.get("return")
+    if return_type is None:
+        return
+    if not _is_json_serializable_annotation(return_type):
+        raise TypeError(
+            f"RPC method {name!r}: return annotation {return_type!r} is not "
+            f"JSON-serializable. Allowed: Pydantic BaseModel, "
+            f"dict/list/str/int/float/bool/None/Any (and unions/generics "
+            f"thereof). Wrap custom types in a Pydantic model."
+        )
+
+
 def _infer_params_model(func: Callable[..., Any]) -> type | None:
     """Infer params_model from the first Pydantic BaseModel parameter in a handler.
 
@@ -482,6 +529,7 @@ def _build_method_meta(
     resolved_result_model, final_result_schema = _resolve_result_model(
         func, result_schema, result_model
     )
+    _validate_return_annotation(func, final_name)
     resolved_params_model = params_model if params_model is not None else _infer_params_model(func)
 
     final_required_roles: list[str] = []

{fastapi_openrpc-0.1.7 → fastapi_openrpc-0.2.0}/src/fastapi_openrpc/router.py

@@ -14,6 +14,7 @@ from typing import Annotated, Any, cast, get_args, get_origin, get_type_hints
 from uuid import uuid4
 
 from fastapi import APIRouter, Depends, HTTPException, Request
+from fastapi.encoders import jsonable_encoder
 from fastapi.responses import JSONResponse, Response
 
 from fastapi_openrpc.authentication import AuthenticationError, AuthenticationMiddleware
@@ -121,16 +122,13 @@ def _validate_pydantic_params(
         # Check if all required fields are present in kwargs (flat parameter structure).
         # Optional fields (with defaults) may be absent — model_validate will use defaults.
         if required_fields <= kwargs.keys():
-            # Extract kwargs fields that match model field names
             subdict = {f: kwargs[f] for f in kwargs.keys() if f in all_fields}
-            try:
-                validated = model_cls.model_validate(subdict)
-                # Remove extracted fields from kwargs and add the model instance
-                for f in subdict:
-                    del kwargs[f]
-                kwargs[param_name] = validated
-            except _pydantic_validation_error():
-                raise
+            # ValidationError is intentionally not caught: it surfaces as
+            # JSONRPC_INVALID_PARAMS in _dispatch_handler.
+            validated = model_cls.model_validate(subdict)
+            for f in subdict:
+                del kwargs[f]
+            kwargs[param_name] = validated
         elif param_name in kwargs and isinstance(kwargs[param_name], dict):
             # dict passed directly as parameter value (theoretically shouldn't happen,
             # but handle for compatibility)
@@ -225,24 +223,9 @@ class RpcDispatcher:
         if (err := self._validate_request_structure(request)) is not None:
             return err
 
+        method_name = request["method"]
         request_id = request.get("id")
         params = request.get("params")
-        if params is not None and not isinstance(params, dict | list):
-            return self._error(
-                JSONRPC_INVALID_PARAMS,
-                "Invalid params",
-                "params must be a JSON object, an array or omitted",
-                request_id=request_id,
-            )
-
-        method_name = request.get("method")
-        if not isinstance(method_name, str):
-            return self._error(
-                JSONRPC_INVALID_REQUEST,
-                "Invalid Request",
-                "method must be a string",
-                request_id=request_id,
-            )
         meta = get(method_name)
         if meta is None:
             return self._error(
@@ -292,7 +275,7 @@ class RpcDispatcher:
             )
 
         method_name = request.get("method")
-        if method_name is None:
+        if not isinstance(method_name, str):
             return self._error(
                 JSONRPC_INVALID_REQUEST,
                 "Invalid Request",
@@ -347,8 +330,7 @@ class RpcDispatcher:
         if not meta.required_roles:
             return None
 
-        self.context.require = meta.require
-        if not self.policy.authorize(meta.name, meta.required_roles, self.context):
+        if not self.policy.authorize(meta.name, meta.required_roles, meta.require, self.context):
             return self._error(
                 JSONRPC_FORBIDDEN,
                 "Insufficient role",
@@ -400,10 +382,28 @@ class RpcDispatcher:
 
         if request_id is None:
             return None
+        # Auto-convert escaped non-JSON-native types (datetime, UUID, ...) so
+        # JSONResponse's json.dumps never sees them. A conversion failure here
+        # must surface as a per-item JSON-RPC error, never an HTTP 500.
+        try:
+            encoded_result = jsonable_encoder(result)
+        except (TypeError, ValueError):
+            logger.exception(
+                "Result of RPC handler %s is not JSON serializable (type: %s)",
+                meta.name,
+                type(result).__name__,
+            )
+            return self._error(
+                JSONRPC_INTERNAL_ERROR,
+                "Internal error",
+                f"Result of method {meta.name!r} is not JSON serializable "
+                f"(type: {type(result).__name__})",
+                request_id=request_id,
+            )
         return {
             "jsonrpc": "2.0",
             "id": request_id,
-            "result": result,
+            "result": encoded_result,
         }
 
     async def _call_handler(self, func, params: dict, result_model: type | None = None) -> Any:
@@ -412,8 +412,8 @@ class RpcDispatcher:
         Args:
             func: RPC handler function.
             params: JSON-RPC params dict.
-            result_model: Pydantic BaseModel subclass; return value is automatically
-                serialized via .model_dump().
+            result_model: Pydantic BaseModel subclass; return value (single instance
+                or list of instances) is automatically serialized via .model_dump().
         """
         sig = inspect.signature(func)
 
@@ -455,9 +455,18 @@ class RpcDispatcher:
                 lambda _k=_kwargs: func(**_k),
             )
 
-        # Pydantic BaseModel serialization
-        if result_model is not None and _is_pydantic_model_instance(result):
-            return result.model_dump()
+        if result_model is not None:
+            if _is_pydantic_model_instance(result):
+                # mode="json": python-mode dumps leave nested datetime/UUID as
+                # objects that break json.dumps in JSONResponse.
+                return result.model_dump(mode="json")
+            # Also serialize list[BaseModel]: a single BaseModel check fails for the
+            # wrapping list, leaving Pydantic instances inside un-dumped.
+            if isinstance(result, list):
+                return [
+                    item.model_dump(mode="json") if _is_pydantic_model_instance(item) else item
+                    for item in result
+                ]
 
         return result
 
@@ -486,10 +495,30 @@ def _python_type_to_json_type(value: Any) -> str | None:
 
 
 def _elapsed_ms(start_time: float) -> float:
-    """Return milliseconds since ``start_time`` as a float, rounded to 0.01ms."""
+    """Return milliseconds since ``start_time`` as an unrounded float.
+
+    Callers that need a fixed-precision value must round themselves
+    (e.g. ``_log_rpc`` rounds to 0.01ms before emitting the log record).
+    """
     return (time.perf_counter() - start_time) * 1000
 
 
+def _summarize_results(
+    results: list[dict | None],
+) -> tuple[str, int | None, str | None]:
+    """Reduce a dispatch-result list to (status, error_code, error_message) for logging.
+
+    - If any non-None result carries an ``"error"`` key, return
+      ``("error", first_error_code, first_error_message)``.
+    - Otherwise return ``("ok", None, None)``.
+    """
+    first_error = next((r for r in results if r is not None and "error" in r), None)
+    if first_error is not None:
+        err = first_error["error"]
+        return ("error", err.get("code"), err.get("message"))
+    return ("ok", None, None)
+
+
 def _log_rpc(
     method: str | None,
     request_id: Any,
@@ -546,7 +575,6 @@ def _build_rpc_discover_response(
     config: dict[str, Any],
 ) -> dict[str, Any]:
     """Build rpc.discover response using the specified OpenRPC document configuration."""
-    # Lazy import to avoid circular dependency
     from fastapi_openrpc.document import build_openrpc_document
 
     doc = build_openrpc_document(
@@ -621,44 +649,41 @@ async def _handle_batch(
 ) -> JSONResponse | Response:
     """Handle a batch JSON-RPC request."""
     if len(data) > MAX_BATCH_SIZE:
+        msg = f"Batch size {len(data)} exceeds limit of {MAX_BATCH_SIZE}"
         _log_rpc(
             None,
             None,
             "error",
             _elapsed_ms(start_time),
             error_code=JSONRPC_INVALID_PARAMS,
-            error_message=f"Batch size {len(data)} exceeds limit of {MAX_BATCH_SIZE}",
-        )
-        return _json_error(
-            JSONRPC_INVALID_PARAMS,
-            "Invalid params",
-            f"Batch size {len(data)} exceeds limit of {MAX_BATCH_SIZE}",
+            error_message=msg,
         )
+        return _json_error(JSONRPC_INVALID_PARAMS, "Invalid params", msg)
     if not data:
+        msg = "Batch array must not be empty"
         _log_rpc(
             None,
             None,
             "error",
             _elapsed_ms(start_time),
             error_code=JSONRPC_INVALID_REQUEST,
-            error_message="Batch array must not be empty",
-        )
-        return _json_error(
-            JSONRPC_INVALID_REQUEST,
-            "Invalid Request",
-            "Batch array must not be empty",
+            error_message=msg,
         )
+        return _json_error(JSONRPC_INVALID_REQUEST, "Invalid Request", msg)
 
     results = await asyncio.gather(
         *[dispatch_one(item, dispatcher, openrpc_doc_config) for item in data]
     )
     if all(r is None for r in results):
         return Response(status_code=204)
+    status, error_code, error_message = _summarize_results(results)
     _log_rpc(
         None,
         None,
-        "ok",
+        status,
         _elapsed_ms(start_time),
+        error_code=error_code,
+        error_message=error_message,
     )
     return JSONResponse(
         status_code=200,
@@ -704,22 +729,28 @@ async def _handle_single(
         resp = await dispatcher.dispatch(data)
         if resp is None:
             return Response(status_code=204)
+        status, error_code, error_message = _summarize_results([resp])
         _log_rpc(
             data.get("method"),
             resp.get("id"),
-            "ok",
+            status,
             _elapsed_ms(start_time),
+            error_code=error_code,
+            error_message=error_message,
         )
         return _json_ok(resp)
 
     resp = await dispatcher.dispatch(data)
     if resp is None:
         return Response(status_code=204)
+    status, error_code, error_message = _summarize_results([resp])
     _log_rpc(
         data.get("method"),
         resp.get("id"),
-        "ok",
+        status,
         _elapsed_ms(start_time),
+        error_code=error_code,
+        error_message=error_message,
     )
     return _json_ok(resp)
 
@@ -875,7 +906,6 @@ class OpenRpcRouter(APIRouter):
 
         super().__init__(dependencies=dependencies, lifespan=cast(Any, _lifespan))
 
-        # Register routes
         self.add_api_route(
             "/openrpc.json",
             self._openrpc_doc_handler,
@@ -931,7 +961,6 @@ class OpenRpcRouter(APIRouter):
 
     async def _openrpc_doc_handler(self) -> JSONResponse:
         """Return OpenRPC document."""
-        # Lazy import to avoid circular dependency
         from fastapi_openrpc.document import build_openrpc_document
 
         doc = build_openrpc_document(
@@ -944,7 +973,7 @@ class OpenRpcRouter(APIRouter):
             terms_of_service=self.terms_of_service,
             openrpc_version=self.openrpc_version,
         )
-        return JSONResponse(content=doc)
+        return JSONResponse(status_code=200, content=doc)
 
     async def _inject_openrpc_doc(self, request: Request) -> None:
         """FastAPI dependency: inject this router's OpenRPC document config and

{fastapi_openrpc-0.1.7 → fastapi_openrpc-0.2.0}/src/fastapi_openrpc/types.py

@@ -64,7 +64,6 @@ class RpcContext:
     """
 
     roles: list[str] = field(default_factory=list)
-    require: Require = Require.ANY
     user_id: str | None = None