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

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

@@ -1,28 +1,31 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.3
 Name: fastapi-openrpc
-Version: 0.1.4
+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
 Author-email: Ye Wenbin <yewenbin@winwin-tech.com>
 License: MIT
-Keywords: ai-agent,discover,fastapi,json-rpc,openrpc,rpc
 Classifier: Framework :: FastAPI
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
-Requires-Python: >=3.11
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Intended Audience :: Developers
 Requires-Dist: fastapi>=0.100.0
 Requires-Dist: pydantic>=2.0
 Requires-Dist: typing-extensions>=4.8
+Requires-Dist: pytest>=8.0 ; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23 ; extra == 'dev'
+Requires-Dist: ruff>=0.4 ; extra == 'dev'
+Requires-Dist: mypy>=1.10 ; extra == 'dev'
+Requires-Dist: httpx>=0.27 ; extra == 'dev'
+Requires-Dist: uvicorn[standard]>=0.51.0 ; extra == 'dev'
+Requires-Dist: fakeredis>=2.21 ; extra == 'dev'
+Requires-Dist: redis[hiredis]>=5.0 ; extra == 'redis'
+Requires-Python: >=3.11
+Project-URL: Source, https://github.com/winwin-inc/fastapi-openrpc
 Provides-Extra: dev
-Requires-Dist: fakeredis>=2.21; extra == 'dev'
-Requires-Dist: httpx>=0.27; extra == 'dev'
-Requires-Dist: mypy>=1.10; extra == 'dev'
-Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
-Requires-Dist: pytest>=8.0; extra == 'dev'
-Requires-Dist: ruff>=0.4; extra == 'dev'
 Provides-Extra: redis
-Requires-Dist: redis[hiredis]>=5.0; extra == 'redis'
 Description-Content-Type: text/markdown
 
 # fastapi-openrpc
@@ -41,6 +44,7 @@ Declarative JSON-RPC 2.0 interface and OpenRPC 1.0 service discovery for FastAPI
 - **RpcContext Propagation** — Secure caller context injection via FastAPI `Depends()`
 - **HMAC Authentication** — Built-in signature verification with Nonce replay protection
 - **Role-Based Authorization** — Method-level role declarations with composition semantics
+- **Business Errors** — Structured error codes with `errors` array in OpenRPC document
 
 ## Installation
 
@@ -108,10 +112,9 @@ auth = HMACAuthentication(
     enable_nonce=True,
     redis_url="redis://localhost:6379",
     nonce_ttl=3600,
-    redis_required=True,       # Reject requests when Redis is unavailable
-    connect_timeout=2.0,      # Redis connection timeout (seconds)
-    operation_timeout=5.0,     # Redis operation timeout (seconds)
-    cleanup_timeout=2.0,      # Redis cleanup timeout (seconds)
+    connect_timeout=2.0,
+    operation_timeout=5.0,
+    cleanup_timeout=2.0,
 )
 ```
 
@@ -142,6 +145,8 @@ async def edit_content(ctx: RpcContext) -> dict:
 
 ## Error Handling
 
+### Built-in Errors
+
 ```python
 from fastapi_openrpc import InvalidParams, MethodNotFound
 
@@ -164,6 +169,46 @@ Built-in error codes:
 | Forbidden | -32000 |
 | Replay Detected | -32002 |
 
+### Business Errors
+
+Define custom errors by subclassing `BusinessError`:
+
+```python
+from fastapi_openrpc import BusinessError
+
+# Define error codes starting from -32100
+class UserNotFoundError(BusinessError):
+    code = -32101
+    message = "User not found"
+
+    def __init__(self, user_id: str):
+        super().__init__(data={"user_id": user_id})
+```
+
+Register error classes with methods using the `errors` parameter:
+
+```python
+from examples.errors import UserNotFoundError  # Your error class
+
+@method(name="getUser", errors=[UserNotFoundError])
+async def get_user(ctx: RpcContext, user_id: str) -> dict:
+    user = db.get(user_id)
+    if not user:
+        raise UserNotFoundError(user_id=user_id)
+    return user
+```
+
+The `errors` array appears in the OpenRPC document for that method, enabling SDK auto-generation of typed exceptions:
+
+```json
+{
+  "name": "getUser",
+  "errors": [
+    {"code": -32101, "message": "User not found"}
+  ]
+}
+```
+
 Library reserves -32000 ~ -32099, application custom errors start from -32100.
 
 ## API Reference
@@ -195,6 +240,7 @@ app.include_router(openrpc_router)
     deprecated=False,
     required_roles=["admin"],  # Required roles
     require=Require.ALL,      # Role composition semantics
+    errors=[MyError],        # Business error subclasses this method may raise
 )
 async def my_handler(ctx: RpcContext, arg1: str, arg2: int = 10) -> dict:
     return {"result": arg1}

{fastapi_openrpc-0.1.4 → fastapi_openrpc-0.2.0}/README.md

@@ -14,6 +14,7 @@ Declarative JSON-RPC 2.0 interface and OpenRPC 1.0 service discovery for FastAPI
 - **RpcContext Propagation** — Secure caller context injection via FastAPI `Depends()`
 - **HMAC Authentication** — Built-in signature verification with Nonce replay protection
 - **Role-Based Authorization** — Method-level role declarations with composition semantics
+- **Business Errors** — Structured error codes with `errors` array in OpenRPC document
 
 ## Installation
 
@@ -81,10 +82,9 @@ auth = HMACAuthentication(
     enable_nonce=True,
     redis_url="redis://localhost:6379",
     nonce_ttl=3600,
-    redis_required=True,       # Reject requests when Redis is unavailable
-    connect_timeout=2.0,      # Redis connection timeout (seconds)
-    operation_timeout=5.0,     # Redis operation timeout (seconds)
-    cleanup_timeout=2.0,      # Redis cleanup timeout (seconds)
+    connect_timeout=2.0,
+    operation_timeout=5.0,
+    cleanup_timeout=2.0,
 )
 ```
 
@@ -115,6 +115,8 @@ async def edit_content(ctx: RpcContext) -> dict:
 
 ## Error Handling
 
+### Built-in Errors
+
 ```python
 from fastapi_openrpc import InvalidParams, MethodNotFound
 
@@ -137,6 +139,46 @@ Built-in error codes:
 | Forbidden | -32000 |
 | Replay Detected | -32002 |
 
+### Business Errors
+
+Define custom errors by subclassing `BusinessError`:
+
+```python
+from fastapi_openrpc import BusinessError
+
+# Define error codes starting from -32100
+class UserNotFoundError(BusinessError):
+    code = -32101
+    message = "User not found"
+
+    def __init__(self, user_id: str):
+        super().__init__(data={"user_id": user_id})
+```
+
+Register error classes with methods using the `errors` parameter:
+
+```python
+from examples.errors import UserNotFoundError  # Your error class
+
+@method(name="getUser", errors=[UserNotFoundError])
+async def get_user(ctx: RpcContext, user_id: str) -> dict:
+    user = db.get(user_id)
+    if not user:
+        raise UserNotFoundError(user_id=user_id)
+    return user
+```
+
+The `errors` array appears in the OpenRPC document for that method, enabling SDK auto-generation of typed exceptions:
+
+```json
+{
+  "name": "getUser",
+  "errors": [
+    {"code": -32101, "message": "User not found"}
+  ]
+}
+```
+
 Library reserves -32000 ~ -32099, application custom errors start from -32100.
 
 ## API Reference
@@ -168,6 +210,7 @@ app.include_router(openrpc_router)
     deprecated=False,
     required_roles=["admin"],  # Required roles
     require=Require.ALL,      # Role composition semantics
+    errors=[MyError],        # Business error subclasses this method may raise
 )
 async def my_handler(ctx: RpcContext, arg1: str, arg2: int = 10) -> dict:
     return {"result": arg1}

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

@@ -1,6 +1,6 @@
 [project]
 name = "fastapi-openrpc"
-version = "0.1.4"
+version = "0.2.0"
 description = "FastAPI JSON-RPC 2.0 + OpenRPC 1.0 service discovery plugin"
 readme = "README.md"
 license = {text = "MIT"}
@@ -17,6 +17,8 @@ classifiers = [
     "Intended Audience :: Developers",
 ]
 
+urls = { Source = "https://github.com/winwin-inc/fastapi-openrpc" }
+
 dependencies = [
     "fastapi>=0.100.0",
     "pydantic>=2.0",
@@ -30,6 +32,7 @@ dev = [
     "ruff>=0.4",
     "mypy>=1.10",
     "httpx>=0.27",
+    "uvicorn[standard]>=0.51.0",
     "fakeredis>=2.21",
 ]
 redis = [
@@ -37,11 +40,8 @@ redis = [
 ]
 
 [build-system]
-requires = ["hatchling"]
-build-backend = "hatchling.build"
-
-[tool.hatch.build.targets.wheel]
-packages = ["src/fastapi_openrpc"]
+requires = ["uv_build>=0.11.6,<0.12.0"]
+build-backend = "uv_build"
 
 [tool.ruff]
 line-length = 100

{fastapi_openrpc-0.1.4 → fastapi_openrpc-0.2.0}/src/fastapi_openrpc/__init__.py

@@ -23,12 +23,14 @@ from __future__ import annotations
 
 from fastapi_openrpc.authentication import (
     AuthenticationMiddleware,
+    HMACAuthConfig,
     HMACAuthentication,
 )
 from fastapi_openrpc.authorization import (
     AuthorizationPolicy,
     DefaultAuthorizationPolicy,
     Require,
+    RoleBasedAuthorizationPolicy,
 )
 from fastapi_openrpc.constants import (
     JSONRPC_FORBIDDEN,
@@ -44,6 +46,7 @@ from fastapi_openrpc.decorator import method
 from fastapi_openrpc.document import build_openrpc_document
 from fastapi_openrpc.errors import (
     AuthenticationError,
+    BusinessError,
     Forbidden,
     InternalError,
     InvalidParams,
@@ -58,7 +61,7 @@ from fastapi_openrpc.registry import add, clear, get, list_methods
 from fastapi_openrpc.router import OpenRpcRouter
 from fastapi_openrpc.types import MethodMeta, RpcContext
 
-__version__ = "0.1.3"
+__version__ = "0.1.4"
 
 __all__ = [
     # Version
@@ -79,7 +82,9 @@ __all__ = [
     "Require",
     "AuthorizationPolicy",
     "DefaultAuthorizationPolicy",
+    "RoleBasedAuthorizationPolicy",
     # Error Classes
+    "BusinessError",
     "JsonRpcError",
     "ParseError",
     "InvalidRequest",
@@ -101,4 +106,5 @@ __all__ = [
     "AuthenticationMiddleware",
     "AuthenticationError",
     "HMACAuthentication",
+    "HMACAuthConfig",
 ]

{fastapi_openrpc-0.1.4 → fastapi_openrpc-0.2.0}/src/fastapi_openrpc/authentication.py

@@ -8,7 +8,9 @@ import hmac
 import json
 import logging
 import re
-from typing import TYPE_CHECKING
+from dataclasses import dataclass, field, fields
+from dataclasses import replace as _replace
+from typing import TYPE_CHECKING, Any
 
 import redis.asyncio
 from typing_extensions import Protocol, runtime_checkable
@@ -38,6 +40,26 @@ class AuthenticationMiddleware(Protocol):
         ...
 
 
+@dataclass(frozen=True)
+class HMACAuthConfig:
+    """Configuration for HMACAuthentication.
+
+    Use as ``HMACAuthentication(config=HMACAuthConfig(...))`` or spread kwargs
+    directly: ``HMACAuthentication(roles_header="X-Custom", secret_key="...")``.
+    """
+
+    roles_header: str = "X-Forwarded-User-Info"
+    signature_header: str = "X-Forwarded-User-Info-Signature"
+    secret_key: str | None = None
+    secret_keys: list[str] = field(default_factory=list)
+    enable_nonce: bool = False
+    redis_url: str | None = None
+    nonce_ttl: int = 3600
+    connect_timeout: float = 2.0
+    operation_timeout: float = 5.0
+    cleanup_timeout: float = 2.0
+
+
 class HMACAuthentication:
     """HMAC-SHA256 signature verification authentication.
 
@@ -56,56 +78,84 @@ class HMACAuthentication:
     Optional Nonce replay attack protection:
     - Requires ``enable_nonce=True`` and ``redis_url`` when enabled
     - Uses Redis SETEX NX command for atomic deduplication
-    - Degrades according to ``redis_required`` config when Redis is unavailable
+    - Redis connection failures result in authentication failure (fail-close)
     """
 
     def __init__(
         self,
-        roles_header: str = "X-Forwarded-User-Info",
-        signature_header: str = "X-Forwarded-User-Info-Signature",
-        secret_key: str | None = None,
-        enable_nonce: bool = False,
-        redis_url: str | None = None,
-        nonce_ttl: int = 3600,
-        redis_required: bool = True,
-        connect_timeout: float = 2.0,
-        operation_timeout: float = 5.0,
-        cleanup_timeout: float = 2.0,
+        config: HMACAuthConfig | None = None,
+        **kwargs: Any,
     ):
+        """Construct HMACAuthentication.
+
+        Supports two construction styles::
+
+            # Config object (preferred for new code)
+            HMACAuthentication(config=HMACAuthConfig(secret_key="..."))
+
+            # Keyword arguments (backward-compatible)
+            HMACAuthentication(secret_key="...")
         """
-        Args:
-            roles_header: Header name for user info, defaults to ``X-Forwarded-User-Info``.
-                Header value can be JSON object (``{"roles": [...]}``) or JSON array.
-            signature_header: Header name for signature, defaults to
-                ``X-Forwarded-User-Info-Signature``.
-            secret_key: HMAC signature key. ``None`` skips signature verification.
-            enable_nonce: Enable Nonce replay attack protection. Defaults to ``False``.
-            redis_url: Redis connection URL (e.g., ``redis://localhost:6379``).
-                Required when ``enable_nonce=True``.
-            nonce_ttl: Nonce TTL in Redis (seconds). Defaults to 3600 (1 hour).
-            redis_required: Whether to reject requests when Redis is unavailable.
-                When True (default) or False: Redis errors always result in
-                request rejection (fail-close). This parameter is kept for
-                behavioral configuration; Redis exceptions reject regardless.
-            connect_timeout: Redis connection timeout (seconds). Defaults to 2.
-            operation_timeout: Redis operation timeout (seconds). Defaults to 5.
-            cleanup_timeout: Redis connection cleanup timeout (seconds). Defaults to 2.
-        """
-        if enable_nonce and not redis_url:
+        # ``config`` may be passed positionally or by keyword; pop it out of
+        # kwargs so it doesn't trip the unknown-kwarg check below.
+        if "config" in kwargs:
+            if config is not None:
+                raise TypeError("config specified twice (positional and keyword)")
+            config = kwargs.pop("config")
+
+        if config is None:
+            config = HMACAuthConfig()
+        elif not isinstance(config, HMACAuthConfig):
+            raise TypeError("config must be an HMACAuthConfig instance")
+
+        # Reject unknown kwargs up front with a clear error. dataclass field
+        # names are the single source of truth — adding a new HMACAuthConfig
+        # field automatically extends the accepted kwargs.
+        valid_fields = {f.name for f in fields(HMACAuthConfig)}
+        unknown = set(kwargs) - valid_fields
+        if unknown:
+            raise TypeError(
+                f"Unknown HMACAuthentication kwargs: {sorted(unknown)}. "
+                f"Valid fields: {sorted(valid_fields)}"
+            )
+
+        # Merge config defaults with explicit kwargs (kwargs override config).
+        # ``None`` means "use the config default" (preserves historical contract).
+        if kwargs:
+            cfg = _replace(config, **{k: v for k, v in kwargs.items() if v is not None})
+        else:
+            cfg = config
+
+        if cfg.enable_nonce and not cfg.redis_url:
             raise ValueError(
                 "redis_url is required when enable_nonce=True. "
                 "Example: redis_url='redis://localhost:6379'"
             )
-        self.roles_header = roles_header
-        self.signature_header = signature_header
-        self.secret_key = secret_key
-        self.enable_nonce = enable_nonce
-        self.redis_url = redis_url
-        self.nonce_ttl = nonce_ttl
-        self.redis_required = redis_required
-        self.connect_timeout = connect_timeout
-        self.operation_timeout = operation_timeout
-        self.cleanup_timeout = cleanup_timeout
+        self.roles_header = cfg.roles_header
+        self.signature_header = cfg.signature_header
+        self.secret_key = cfg.secret_key
+        self.secret_keys = cfg.secret_keys
+        self.enable_nonce = cfg.enable_nonce
+        self.redis_url = cfg.redis_url
+        self.nonce_ttl = cfg.nonce_ttl
+        self.connect_timeout = cfg.connect_timeout
+        self.operation_timeout = cfg.operation_timeout
+        self.cleanup_timeout = cfg.cleanup_timeout
+
+    def _verify_signature(self, user_info_raw: str | None, signature_raw: str) -> bool:
+        """Try keys in order; return True if any key matches."""
+        keys_to_try: list[str | None] = [self.secret_key] + self.secret_keys
+        for key in keys_to_try:
+            if not key:
+                continue
+            expected = hmac.new(
+                key.encode(),
+                (user_info_raw or "").encode(),
+                hashlib.sha256,
+            ).hexdigest()
+            if hmac.compare_digest(expected, signature_raw):
+                return True
+        return False
 
     async def authenticate(self, request: Request) -> RpcContext:
         """Verify HMAC signature and parse role list.
@@ -123,21 +173,15 @@ class HMACAuthentication:
         user_info_raw = request.headers.get(self.roles_header)
         signature_raw = request.headers.get(self.signature_header)
 
-        # Step 1: Verify signature (if secret_key is configured)
-        if self.secret_key:
+        # Verify HMAC signature before trusting header content (fail-fast on tampering)
+        if self.secret_key or self.secret_keys:
             if not signature_raw:
                 raise AuthenticationError("Missing signature")
-            # user_info_raw may be None; use empty string to avoid .encode() TypeError
-            expected = hmac.new(
-                self.secret_key.encode(),
-                (user_info_raw or "").encode(),
-                hashlib.sha256,
-            ).hexdigest()
-            if not hmac.compare_digest(expected, signature_raw):
+            if not self._verify_signature(user_info_raw, signature_raw):
                 raise AuthenticationError("Invalid signature")
 
-        # Step 2: Parse roles and user_id (runs even when secret_key=None;
-        # independent of signature verification)
+        # Parse roles from header content; runs regardless of secret_key to support
+        # trusted-network mode (secret_key=None) where headers still carry role info
         user_info_dict: dict | list | None = None
         if user_info_raw:
             try:
@@ -159,7 +203,7 @@ class HMACAuthentication:
             roles = []
             user_id = None
 
-        # Step 3: Nonce verification (if enabled)
+        # Nonce verification (if enabled)
         if self.enable_nonce:
             nonce: str | None = None
             if isinstance(user_info_dict, dict):

{fastapi_openrpc-0.1.4 → 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.
@@ -41,8 +43,8 @@ class AuthorizationPolicy(Protocol):
         ...
 
 
-class DefaultAuthorizationPolicy:
-    """Default authorization policy.
+class RoleBasedAuthorizationPolicy:
+    """Role-based authorization policy.
 
     ANY semantics: True if any required_roles match.
     ALL semantics: True only if all required_roles are present in ctx.roles.
@@ -55,6 +57,7 @@ class DefaultAuthorizationPolicy:
         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 DefaultAuthorizationPolicy:
             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)
@@ -76,4 +79,13 @@ class DefaultAuthorizationPolicy:
             return False
 
 
-__all__ = ["Require", "AuthorizationPolicy", "DefaultAuthorizationPolicy"]
+# Backward-compatible alias
+DefaultAuthorizationPolicy = RoleBasedAuthorizationPolicy
+
+
+__all__ = [
+    "Require",
+    "AuthorizationPolicy",
+    "RoleBasedAuthorizationPolicy",
+    "DefaultAuthorizationPolicy",  # noqa: E501 backward-compatible alias
+]