rpc-python-toolkit 0.1.0__tar.gz → 0.2.1__tar.gz

{rpc_python_toolkit-0.1.0/src/rpc_python_toolkit.egg-info → rpc_python_toolkit-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rpc-python-toolkit
-Version: 0.1.0
+Version: 0.2.1
 Summary: Framework-agnostic Python JSON-RPC 2.0 toolkit with Safe Mode interoperability.
 Author: Nicola Carpanese
 License-Expression: MIT
@@ -25,19 +25,34 @@ Dynamic: license-file
 
 # RPC Python Toolkit
 
+[![CI](https://github.com/n-car/rpc-python-toolkit/actions/workflows/ci.yml/badge.svg)](https://github.com/n-car/rpc-python-toolkit/actions/workflows/ci.yml)
+[![PyPI Version](https://img.shields.io/pypi/v/rpc-python-toolkit.svg)](https://pypi.org/project/rpc-python-toolkit/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/rpc-python-toolkit.svg)](https://pypi.org/project/rpc-python-toolkit/)
+[![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Status](https://img.shields.io/badge/status-alpha-orange.svg)](https://pypi.org/project/rpc-python-toolkit/)
+
 Framework-agnostic JSON-RPC 2.0 toolkit for Python.
 
 Use this package when you need a small Python JSON-RPC 2.0 client/server core that can be embedded directly or adapted to HTTP frameworks. It follows the same protocol conventions used across the RPC Toolkit ecosystem.
 
 ## Project Status
 
-Small early package with the core JSON-RPC behavior implemented.
+Alpha package with the core JSON-RPC behavior implemented.
 
 - Published on PyPI as `rpc-python-toolkit`.
 - Standard JSON-RPC 2.0 remains the default behavior.
 - Safe Mode follows the same `X-RPC-Safe-Enabled` and value marker conventions used by `rpc-express-toolkit`.
 - The public API may still change before a stable Python release.
 
+## Release Notes
+
+### 0.2.1 - 2026-10-12
+
+- Sanitize unexpected errors and `RpcError(-32603)` by default, removing internal messages and data while preserving explicit application errors.
+- Validate request envelopes and reject non-JSON numeric constants, scalar/null parameters, boolean IDs, and non-finite IDs.
+- Return errors for invalid batch elements, distinguish explicit null IDs from notifications, and preserve JSON payload shapes.
+- Add error-handling and protocol regression tests, and document the tightened wire contract and trusted handler context.
+
 ## Installation
 
 Install from PyPI:
@@ -80,7 +95,11 @@ python -m unittest discover
 ```python
 from rpc_python_toolkit import RpcEndpoint
 
-rpc = RpcEndpoint(enable_introspection=True)
+rpc = RpcEndpoint(
+    enable_introspection=True,
+    enable_batch=True,
+    max_batch_size=100,
+)
 
 def test(request, context, params):
     return {"ok": True, "params": params}
@@ -97,6 +116,28 @@ response = rpc.handle_payload({
 print(response.body)
 ```
 
+Batch can be disabled with `enable_batch=False`. Introspection remains opt-in.
+Unexpected errors and `RpcError` instances with code `-32603` return only
+`Internal error` by default, without internal messages or data. Other explicit
+`RpcError` codes, messages, and data are preserved. Parse errors omit diagnostic
+data. Use `sanitize_errors=False` only for local debugging to restore details.
+
+Only valid requests without an `id` are notifications. An explicit `id: null`
+receives a response; malformed envelopes (including scalar/null `params` or
+boolean/non-finite IDs) return `-32600` with `id: null`. Method parameter schema
+errors remain `-32602`.
+Malformed JSON, including the non-JSON constants `NaN`, `Infinity`, and `-Infinity`,
+returns `-32700`. Invalid elements in a batch produce individual error responses;
+valid notifications remain silent even when their method fails. Objects, arrays,
+and null results retain their JSON shapes.
+
+When both application and request contexts are dictionaries, handlers receive a
+merged dictionary and request values take precedence. For a non-dictionary
+application context plus request data, handlers receive `RpcCallContext` with
+separate `application` and `request` attributes.
+These contexts are supplied by application/adapter code. Client `params` remain a
+separate third handler argument and cannot replace trusted context.
+
 Result:
 
 ```json
@@ -131,6 +172,10 @@ Safe Mode enables `X-RPC-Safe-Enabled` negotiation and recursive value encoding/
 
 Python exposes arbitrary precision integers as `int`. BigInt marker strings from other RPC Toolkit implementations are decoded to Python `int` values when they are real markers, while literal marker-like strings are protected by the `S:` prefix in Safe Mode.
 
+Safe Mode transforms payload values, not method names, request IDs, error codes,
+or error messages. Application `RpcError.data` is encoded like a result; sanitized
+internal errors expose neither their original message nor their data.
+
 ## Examples
 
 Runnable examples are available in [`examples/`](examples/):

{rpc_python_toolkit-0.1.0 → rpc_python_toolkit-0.2.1}/README.md

@@ -1,18 +1,33 @@
 # RPC Python Toolkit
 
+[![CI](https://github.com/n-car/rpc-python-toolkit/actions/workflows/ci.yml/badge.svg)](https://github.com/n-car/rpc-python-toolkit/actions/workflows/ci.yml)
+[![PyPI Version](https://img.shields.io/pypi/v/rpc-python-toolkit.svg)](https://pypi.org/project/rpc-python-toolkit/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/rpc-python-toolkit.svg)](https://pypi.org/project/rpc-python-toolkit/)
+[![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Status](https://img.shields.io/badge/status-alpha-orange.svg)](https://pypi.org/project/rpc-python-toolkit/)
+
 Framework-agnostic JSON-RPC 2.0 toolkit for Python.
 
 Use this package when you need a small Python JSON-RPC 2.0 client/server core that can be embedded directly or adapted to HTTP frameworks. It follows the same protocol conventions used across the RPC Toolkit ecosystem.
 
 ## Project Status
 
-Small early package with the core JSON-RPC behavior implemented.
+Alpha package with the core JSON-RPC behavior implemented.
 
 - Published on PyPI as `rpc-python-toolkit`.
 - Standard JSON-RPC 2.0 remains the default behavior.
 - Safe Mode follows the same `X-RPC-Safe-Enabled` and value marker conventions used by `rpc-express-toolkit`.
 - The public API may still change before a stable Python release.
 
+## Release Notes
+
+### 0.2.1 - 2026-10-12
+
+- Sanitize unexpected errors and `RpcError(-32603)` by default, removing internal messages and data while preserving explicit application errors.
+- Validate request envelopes and reject non-JSON numeric constants, scalar/null parameters, boolean IDs, and non-finite IDs.
+- Return errors for invalid batch elements, distinguish explicit null IDs from notifications, and preserve JSON payload shapes.
+- Add error-handling and protocol regression tests, and document the tightened wire contract and trusted handler context.
+
 ## Installation
 
 Install from PyPI:
@@ -55,7 +70,11 @@ python -m unittest discover
 ```python
 from rpc_python_toolkit import RpcEndpoint
 
-rpc = RpcEndpoint(enable_introspection=True)
+rpc = RpcEndpoint(
+    enable_introspection=True,
+    enable_batch=True,
+    max_batch_size=100,
+)
 
 def test(request, context, params):
     return {"ok": True, "params": params}
@@ -72,6 +91,28 @@ response = rpc.handle_payload({
 print(response.body)
 ```
 
+Batch can be disabled with `enable_batch=False`. Introspection remains opt-in.
+Unexpected errors and `RpcError` instances with code `-32603` return only
+`Internal error` by default, without internal messages or data. Other explicit
+`RpcError` codes, messages, and data are preserved. Parse errors omit diagnostic
+data. Use `sanitize_errors=False` only for local debugging to restore details.
+
+Only valid requests without an `id` are notifications. An explicit `id: null`
+receives a response; malformed envelopes (including scalar/null `params` or
+boolean/non-finite IDs) return `-32600` with `id: null`. Method parameter schema
+errors remain `-32602`.
+Malformed JSON, including the non-JSON constants `NaN`, `Infinity`, and `-Infinity`,
+returns `-32700`. Invalid elements in a batch produce individual error responses;
+valid notifications remain silent even when their method fails. Objects, arrays,
+and null results retain their JSON shapes.
+
+When both application and request contexts are dictionaries, handlers receive a
+merged dictionary and request values take precedence. For a non-dictionary
+application context plus request data, handlers receive `RpcCallContext` with
+separate `application` and `request` attributes.
+These contexts are supplied by application/adapter code. Client `params` remain a
+separate third handler argument and cannot replace trusted context.
+
 Result:
 
 ```json
@@ -106,6 +147,10 @@ Safe Mode enables `X-RPC-Safe-Enabled` negotiation and recursive value encoding/
 
 Python exposes arbitrary precision integers as `int`. BigInt marker strings from other RPC Toolkit implementations are decoded to Python `int` values when they are real markers, while literal marker-like strings are protected by the `S:` prefix in Safe Mode.
 
+Safe Mode transforms payload values, not method names, request IDs, error codes,
+or error messages. Application `RpcError.data` is encoded like a result; sanitized
+internal errors expose neither their original message nor their data.
+
 ## Examples
 
 Runnable examples are available in [`examples/`](examples/):

{rpc_python_toolkit-0.1.0 → rpc_python_toolkit-0.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "rpc-python-toolkit"
-version = "0.1.0"
+version = "0.2.1"
 description = "Framework-agnostic Python JSON-RPC 2.0 toolkit with Safe Mode interoperability."
 readme = "README.md"
 requires-python = ">=3.10"

{rpc_python_toolkit-0.1.0 → rpc_python_toolkit-0.2.1}/src/rpc_python_toolkit/__init__.py

@@ -1,5 +1,5 @@
 from .client import RpcClient, RpcSafeClient
-from .endpoint import RpcEndpoint, RpcHttpResponse, RpcSafeEndpoint
+from .endpoint import RpcCallContext, RpcEndpoint, RpcHttpResponse, RpcSafeEndpoint
 from .errors import RpcError, RpcRemoteError
 from .serialization import deserialize_value, serialize_value
 from .version import __version__
@@ -10,10 +10,10 @@ __all__ = [
     "serialize_value",
     "RpcClient",
     "RpcEndpoint",
+    "RpcCallContext",
     "RpcError",
     "RpcHttpResponse",
     "RpcRemoteError",
     "RpcSafeClient",
     "RpcSafeEndpoint",
 ]
-

{rpc_python_toolkit-0.1.0 → rpc_python_toolkit-0.2.1}/src/rpc_python_toolkit/endpoint.py

@@ -23,6 +23,19 @@ class RpcHttpResponse:
     body: Any | None = None
 
 
+@dataclass(frozen=True)
+class RpcCallContext:
+    """Context used when application state is not a mapping.
+
+    Mapping application contexts are merged with request data for backward
+    compatibility. For other application context types, this wrapper keeps
+    application and request scopes explicit.
+    """
+
+    application: Any
+    request: dict[str, Any]
+
+
 @dataclass
 class MethodConfig:
     handler: Handler
@@ -40,8 +53,11 @@ class RpcEndpoint:
         strict_mode: bool = True,
         enable_introspection: bool = False,
         introspection_prefix: str = "__rpc",
+        enable_batch: bool = True,
+        max_batch_size: int = 100,
         max_serialization_depth: int = 100,
         max_deserialization_depth: int = 100,
+        sanitize_errors: bool = True,
     ):
         self.context = context
         self.methods: dict[str, MethodConfig] = {}
@@ -49,8 +65,11 @@ class RpcEndpoint:
         self.strict_mode = strict_mode
         self.enable_introspection = enable_introspection
         self.introspection_prefix = introspection_prefix
+        self.enable_batch = enable_batch
+        self.max_batch_size = max_batch_size
         self.max_serialization_depth = max_serialization_depth
         self.max_deserialization_depth = max_deserialization_depth
+        self.sanitize_errors = sanitize_errors
         self.validator = SchemaValidator()
 
         if self.enable_introspection:
@@ -100,17 +119,13 @@ class RpcEndpoint:
         try:
             request = self._decode_payload(payload)
         except Exception as exc:
+            error = {"code": -32700, "message": "Parse error"}
+            if not self.sanitize_errors:
+                error["data"] = {"message": str(exc)}
             return RpcHttpResponse(
                 200,
                 headers,
-                make_response(
-                    None,
-                    error={
-                        "code": -32700,
-                        "message": "Parse error",
-                        "data": {"message": str(exc)},
-                    },
-                ),
+                make_response(None, error=error),
             )
 
         request_context = context or {}
@@ -159,6 +174,29 @@ class RpcEndpoint:
                 make_response(None, error={"code": -32600, "message": "Invalid Request"}),
             )
 
+        if not self.enable_batch:
+            return RpcHttpResponse(
+                200,
+                headers,
+                make_response(
+                    None,
+                    error={"code": -32600, "message": "Batch requests are not enabled"},
+                ),
+            )
+
+        if self.max_batch_size > 0 and len(batch) > self.max_batch_size:
+            return RpcHttpResponse(
+                200,
+                headers,
+                make_response(
+                    None,
+                    error={
+                        "code": -32600,
+                        "message": f"Batch size exceeds maximum of {self.max_batch_size}",
+                    },
+                ),
+            )
+
         responses = []
         for item in batch:
             result = self._process_single(item, context)
@@ -171,8 +209,12 @@ class RpcEndpoint:
         return RpcHttpResponse(200, headers, responses)
 
     def _process_single(self, request: Any, context: dict[str, Any]) -> dict[str, Any] | None:
+        # An invalid envelope is not a notification, even when it has no id.
+        # Do not echo an untrusted id until the complete envelope is validated.
+        valid_request = False
         try:
             validate_request_envelope(request)
+            valid_request = True
             client_safe_enabled = self._client_safe_enabled(context)
 
             if self.safe_enabled and self.strict_mode and not self._has_safe_header(context):
@@ -198,23 +240,24 @@ class RpcEndpoint:
                 result=self.serialize_bigints_and_dates(result),
             )
         except RpcError as exc:
-            if isinstance(request, dict) and not has_id(request):
+            if valid_request and not has_id(request):
                 return None
-            request_id = request.get("id") if isinstance(request, dict) else None
+            request_id = request.get("id") if valid_request else None
             return self._make_error_response(request_id, exc)
         except Exception as exc:
-            if isinstance(request, dict) and not has_id(request):
+            if valid_request and not has_id(request):
                 return None
-            request_id = request.get("id") if isinstance(request, dict) else None
+            request_id = request.get("id") if valid_request else None
             return self._make_error_response(request_id, RpcError(str(exc), -32603))
 
     def _make_error_response(self, request_id: Any, error: RpcError) -> dict[str, Any]:
+        internal_error = self.sanitize_errors and error.code == -32603
         body = {
             "code": error.code,
-            "message": str(error),
+            "message": "Internal error" if internal_error else str(error),
         }
 
-        if error.data is not None:
+        if not internal_error and error.data is not None:
             body["data"] = self.serialize_bigints_and_dates(error.data)
 
         return make_response(request_id, error=body)
@@ -226,11 +269,23 @@ class RpcEndpoint:
         context: dict[str, Any],
         params: Any,
     ) -> Any:
-        result = handler(request, self.context if self.context is not None else context, params)
+        result = handler(request, self._resolve_handler_context(context), params)
         if inspect.isawaitable(result):
             raise RpcError("Async handlers require an async adapter", -32603)
         return result
 
+    def _resolve_handler_context(self, request_context: dict[str, Any]) -> Any:
+        if self.context is None:
+            return request_context
+
+        if isinstance(self.context, dict):
+            return {**self.context, **request_context}
+
+        if request_context:
+            return RpcCallContext(application=self.context, request=request_context)
+
+        return self.context
+
     def _register_introspection_methods(self) -> None:
         prefix = self.introspection_prefix
 
@@ -255,7 +310,7 @@ class RpcEndpoint:
             f"{prefix}.capabilities",
             lambda _request, _context, _params: {
                 "jsonrpc": "2.0",
-                "batch": True,
+                "batch": self.enable_batch,
                 "notifications": True,
                 "introspection": True,
                 "safeMode": self.safe_enabled,
@@ -287,7 +342,10 @@ class RpcEndpoint:
             payload = payload.decode("utf-8")
 
         if isinstance(payload, str):
-            return json.loads(payload)
+            def reject_non_json_constant(value: str) -> None:
+                raise ValueError(f"Invalid JSON constant: {value}")
+
+            return json.loads(payload, parse_constant=reject_non_json_constant)
 
         return payload
 
@@ -311,4 +369,3 @@ class RpcSafeEndpoint(RpcEndpoint):
         options.setdefault("safe_enabled", True)
         options.setdefault("strict_mode", True)
         super().__init__(context, **options)
-

{rpc_python_toolkit-0.1.0 → rpc_python_toolkit-0.2.1}/src/rpc_python_toolkit/protocol.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import math
 from typing import Any
 
 from .errors import RpcError
@@ -35,8 +36,14 @@ def validate_request_envelope(request: Any) -> None:
         raise RpcError("Method not specified or invalid", -32600)
 
     if "params" in request and not isinstance(request["params"], (dict, list)):
-        raise RpcError("Invalid params", -32602)
-
-    if "id" in request and not isinstance(request["id"], (str, int, float, type(None))):
-        raise RpcError("Invalid request id", -32600)
+        raise RpcError("Invalid params container", -32600)
+
+    if "id" in request:
+        request_id = request["id"]
+        if (
+            isinstance(request_id, bool)
+            or not isinstance(request_id, (str, int, float, type(None)))
+            or (isinstance(request_id, float) and not math.isfinite(request_id))
+        ):
+            raise RpcError("Invalid request id", -32600)
 

rpc_python_toolkit-0.2.1/src/rpc_python_toolkit/version.py

@@ -0,0 +1 @@
+__version__ = "0.2.1"

{rpc_python_toolkit-0.1.0 → rpc_python_toolkit-0.2.1/src/rpc_python_toolkit.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rpc-python-toolkit
-Version: 0.1.0
+Version: 0.2.1
 Summary: Framework-agnostic Python JSON-RPC 2.0 toolkit with Safe Mode interoperability.
 Author: Nicola Carpanese
 License-Expression: MIT
@@ -25,19 +25,34 @@ Dynamic: license-file
 
 # RPC Python Toolkit
 
+[![CI](https://github.com/n-car/rpc-python-toolkit/actions/workflows/ci.yml/badge.svg)](https://github.com/n-car/rpc-python-toolkit/actions/workflows/ci.yml)
+[![PyPI Version](https://img.shields.io/pypi/v/rpc-python-toolkit.svg)](https://pypi.org/project/rpc-python-toolkit/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/rpc-python-toolkit.svg)](https://pypi.org/project/rpc-python-toolkit/)
+[![License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Status](https://img.shields.io/badge/status-alpha-orange.svg)](https://pypi.org/project/rpc-python-toolkit/)
+
 Framework-agnostic JSON-RPC 2.0 toolkit for Python.
 
 Use this package when you need a small Python JSON-RPC 2.0 client/server core that can be embedded directly or adapted to HTTP frameworks. It follows the same protocol conventions used across the RPC Toolkit ecosystem.
 
 ## Project Status
 
-Small early package with the core JSON-RPC behavior implemented.
+Alpha package with the core JSON-RPC behavior implemented.
 
 - Published on PyPI as `rpc-python-toolkit`.
 - Standard JSON-RPC 2.0 remains the default behavior.
 - Safe Mode follows the same `X-RPC-Safe-Enabled` and value marker conventions used by `rpc-express-toolkit`.
 - The public API may still change before a stable Python release.
 
+## Release Notes
+
+### 0.2.1 - 2026-10-12
+
+- Sanitize unexpected errors and `RpcError(-32603)` by default, removing internal messages and data while preserving explicit application errors.
+- Validate request envelopes and reject non-JSON numeric constants, scalar/null parameters, boolean IDs, and non-finite IDs.
+- Return errors for invalid batch elements, distinguish explicit null IDs from notifications, and preserve JSON payload shapes.
+- Add error-handling and protocol regression tests, and document the tightened wire contract and trusted handler context.
+
 ## Installation
 
 Install from PyPI:
@@ -80,7 +95,11 @@ python -m unittest discover
 ```python
 from rpc_python_toolkit import RpcEndpoint
 
-rpc = RpcEndpoint(enable_introspection=True)
+rpc = RpcEndpoint(
+    enable_introspection=True,
+    enable_batch=True,
+    max_batch_size=100,
+)
 
 def test(request, context, params):
     return {"ok": True, "params": params}
@@ -97,6 +116,28 @@ response = rpc.handle_payload({
 print(response.body)
 ```
 
+Batch can be disabled with `enable_batch=False`. Introspection remains opt-in.
+Unexpected errors and `RpcError` instances with code `-32603` return only
+`Internal error` by default, without internal messages or data. Other explicit
+`RpcError` codes, messages, and data are preserved. Parse errors omit diagnostic
+data. Use `sanitize_errors=False` only for local debugging to restore details.
+
+Only valid requests without an `id` are notifications. An explicit `id: null`
+receives a response; malformed envelopes (including scalar/null `params` or
+boolean/non-finite IDs) return `-32600` with `id: null`. Method parameter schema
+errors remain `-32602`.
+Malformed JSON, including the non-JSON constants `NaN`, `Infinity`, and `-Infinity`,
+returns `-32700`. Invalid elements in a batch produce individual error responses;
+valid notifications remain silent even when their method fails. Objects, arrays,
+and null results retain their JSON shapes.
+
+When both application and request contexts are dictionaries, handlers receive a
+merged dictionary and request values take precedence. For a non-dictionary
+application context plus request data, handlers receive `RpcCallContext` with
+separate `application` and `request` attributes.
+These contexts are supplied by application/adapter code. Client `params` remain a
+separate third handler argument and cannot replace trusted context.
+
 Result:
 
 ```json
@@ -131,6 +172,10 @@ Safe Mode enables `X-RPC-Safe-Enabled` negotiation and recursive value encoding/
 
 Python exposes arbitrary precision integers as `int`. BigInt marker strings from other RPC Toolkit implementations are decoded to Python `int` values when they are real markers, while literal marker-like strings are protected by the `S:` prefix in Safe Mode.
 
+Safe Mode transforms payload values, not method names, request IDs, error codes,
+or error messages. Application `RpcError.data` is encoded like a result; sanitized
+internal errors expose neither their original message nor their data.
+
 ## Examples
 
 Runnable examples are available in [`examples/`](examples/):

{rpc_python_toolkit-0.1.0 → rpc_python_toolkit-0.2.1}/src/rpc_python_toolkit.egg-info/SOURCES.txt

@@ -14,4 +14,6 @@ src/rpc_python_toolkit.egg-info/SOURCES.txt
 src/rpc_python_toolkit.egg-info/dependency_links.txt
 src/rpc_python_toolkit.egg-info/requires.txt
 src/rpc_python_toolkit.egg-info/top_level.txt
-tests/test_core.py
+tests/test_core.py
+tests/test_errors.py
+tests/test_protocol.py

{rpc_python_toolkit-0.1.0 → rpc_python_toolkit-0.2.1}/tests/test_core.py

@@ -8,6 +8,7 @@ from http.server import BaseHTTPRequestHandler, HTTPServer
 
 from rpc_python_toolkit import (
     RpcClient,
+    RpcCallContext,
     RpcEndpoint,
     RpcRemoteError,
     RpcSafeClient,
@@ -68,6 +69,67 @@ class CoreTests(unittest.TestCase):
             [{"jsonrpc": "2.0", "id": "a", "result": {"value": 1}}],
         )
 
+    def test_can_disable_batch_requests(self):
+        rpc = RpcEndpoint(enable_batch=False)
+        rpc.add_method("echo", lambda _request, _context, params: params)
+
+        response = rpc.handle_payload(
+            [{"jsonrpc": "2.0", "method": "echo", "id": 1}]
+        )
+
+        self.assertEqual(response.body["error"]["code"], -32600)
+        self.assertIn("not enabled", response.body["error"]["message"])
+
+    def test_enforces_maximum_batch_size(self):
+        rpc = RpcEndpoint(max_batch_size=1)
+        rpc.add_method("echo", lambda _request, _context, params: params)
+
+        response = rpc.handle_payload(
+            [
+                {"jsonrpc": "2.0", "method": "echo", "id": 1},
+                {"jsonrpc": "2.0", "method": "echo", "id": 2},
+            ]
+        )
+
+        self.assertEqual(response.body["error"]["code"], -32600)
+        self.assertIn("maximum of 1", response.body["error"]["message"])
+
+    def test_merges_application_and_request_mapping_contexts(self):
+        rpc = RpcEndpoint({"service": "orders", "user": "application"})
+        rpc.add_method("context", lambda _request, context, _params: context)
+
+        response = rpc.handle_payload(
+            {"jsonrpc": "2.0", "method": "context", "id": 1},
+            {"user": "request", "request_id": "abc"},
+        )
+
+        self.assertEqual(
+            response.body["result"],
+            {"service": "orders", "user": "request", "request_id": "abc"},
+        )
+
+    def test_preserves_both_context_scopes_for_non_mapping_application_context(self):
+        application = object()
+        rpc = RpcEndpoint(application)
+        captured = []
+
+        def capture_context(_request, context, _params):
+            captured.append(context)
+            return "ok"
+
+        rpc.add_method("context", capture_context)
+
+        response = rpc.handle_payload(
+            {"jsonrpc": "2.0", "method": "context", "id": 1},
+            {"request_id": "abc"},
+        )
+        context = captured[0]
+
+        self.assertEqual(response.body["result"], "ok")
+        self.assertIsInstance(context, RpcCallContext)
+        self.assertIs(context.application, application)
+        self.assertEqual(context.request["request_id"], "abc")
+
     def test_enforces_safe_mode_header_in_strict_mode(self):
         rpc = RpcSafeEndpoint()
         rpc.add_method("echo", lambda _request, _context, params: params)

rpc_python_toolkit-0.2.1/tests/test_errors.py

@@ -0,0 +1,159 @@
+from __future__ import annotations
+
+import unittest
+from unittest.mock import patch
+
+from rpc_python_toolkit import RpcEndpoint, RpcError, RpcSafeEndpoint
+
+
+class ErrorSanitizationTests(unittest.TestCase):
+    def test_unexpected_handler_error_is_generic_even_with_code_and_data(self):
+        rpc = RpcEndpoint()
+        failure = RuntimeError("Synthetic private configuration detail")
+        failure.code = -32042
+        failure.data = {"path": "/private/example/config.ini"}
+
+        def fail(_request, _context, _params):
+            raise failure
+
+        rpc.add_method("fail", fail)
+
+        response = rpc.handle_payload({"jsonrpc": "2.0", "method": "fail", "id": 1})
+
+        self.assertEqual(response.status, 200)
+        self.assertEqual(
+            response.body,
+            {
+                "jsonrpc": "2.0",
+                "id": 1,
+                "error": {"code": -32603, "message": "Internal error"},
+            },
+        )
+
+    def test_explicit_internal_error_also_hides_message_and_data(self):
+        rpc = RpcEndpoint()
+
+        def fail(_request, _context, _params):
+            raise RpcError("Synthetic database detail", -32603, {"path": "/private/example"})
+
+        rpc.add_method("fail", fail)
+
+        response = rpc.handle_payload({"jsonrpc": "2.0", "method": "fail", "id": 2})
+
+        self.assertEqual(response.body["error"], {"code": -32603, "message": "Internal error"})
+
+    def test_explicit_application_error_preserves_code_message_and_data(self):
+        rpc = RpcEndpoint()
+
+        def fail(_request, _context, _params):
+            raise RpcError("Quota exceeded", -32042, {"limit": 10})
+
+        rpc.add_method("fail", fail)
+
+        response = rpc.handle_payload({"jsonrpc": "2.0", "method": "fail", "id": 3})
+
+        self.assertEqual(
+            response.body["error"],
+            {"code": -32042, "message": "Quota exceeded", "data": {"limit": 10}},
+        )
+
+    def test_batch_sanitizes_errors_without_responding_to_failed_notifications(self):
+        rpc = RpcEndpoint()
+
+        def fail(_request, _context, _params):
+            raise RuntimeError("Synthetic batch detail")
+
+        rpc.add_method("fail", fail)
+        rpc.add_method("echo", lambda _request, _context, params: params)
+
+        response = rpc.handle_payload(
+            [
+                {"jsonrpc": "2.0", "method": "fail", "id": 1},
+                {"jsonrpc": "2.0", "method": "fail"},
+                {"jsonrpc": "2.0", "method": "echo", "params": [1, 2], "id": 2},
+            ]
+        )
+
+        self.assertEqual(
+            response.body,
+            [
+                {"jsonrpc": "2.0", "id": 1, "error": {"code": -32603, "message": "Internal error"}},
+                {"jsonrpc": "2.0", "id": 2, "result": [1, 2]},
+            ],
+        )
+
+    def test_unexpected_outer_error_is_sanitized(self):
+        rpc = RpcEndpoint()
+
+        with patch.object(rpc, "_process_batch", side_effect=RuntimeError("Synthetic adapter detail")):
+            response = rpc.handle_payload([{"jsonrpc": "2.0", "method": "echo", "id": 1}])
+
+        self.assertEqual(
+            response.body,
+            {"jsonrpc": "2.0", "id": None, "error": {"code": -32603, "message": "Internal error"}},
+        )
+
+    def test_unexpected_validation_error_is_sanitized(self):
+        rpc = RpcEndpoint()
+        rpc.add_method("echo", lambda _request, _context, params: params)
+
+        with patch.object(rpc.validator, "validate", side_effect=RuntimeError("Synthetic validator detail")):
+            response = rpc.handle_payload({"jsonrpc": "2.0", "method": "echo", "id": 1})
+
+        self.assertEqual(response.body["error"], {"code": -32603, "message": "Internal error"})
+
+    def test_parse_error_omits_diagnostic_data_by_default(self):
+        response = RpcEndpoint().handle_payload("{")
+
+        self.assertEqual(response.body["error"], {"code": -32700, "message": "Parse error"})
+
+        debug_response = RpcEndpoint(sanitize_errors=False).handle_payload("{")
+        self.assertEqual(debug_response.body["error"]["code"], -32700)
+        self.assertTrue(debug_response.body["error"]["data"]["message"])
+
+    def test_debug_option_preserves_internal_details(self):
+        for failure, expected in [
+            (RuntimeError("Synthetic debug detail"), {"code": -32603, "message": "Synthetic debug detail"}),
+            (
+                RpcError("Synthetic debug detail", -32603, {"path": "/private/example"}),
+                {"code": -32603, "message": "Synthetic debug detail", "data": {"path": "/private/example"}},
+            ),
+        ]:
+            with self.subTest(error_type=type(failure).__name__):
+                rpc = RpcEndpoint(sanitize_errors=False)
+
+                def fail(_request, _context, _params):
+                    raise failure
+
+                rpc.add_method("fail", fail)
+                response = rpc.handle_payload({"jsonrpc": "2.0", "method": "fail", "id": 1})
+
+                self.assertEqual(response.body["error"], expected)
+
+    def test_safe_mode_preserves_application_data_and_sanitizes_internal_errors(self):
+        rpc = RpcSafeEndpoint()
+
+        def fail(_request, _context, params):
+            if params["internal"]:
+                raise RuntimeError("Synthetic Safe Mode detail")
+            raise RpcError("Quota exceeded", -32042, {"reason": "limit"})
+
+        rpc.add_method("fail", fail)
+
+        response = rpc.handle_payload(
+            [
+                {"jsonrpc": "2.0", "method": "fail", "params": {"internal": False}, "id": 1},
+                {"jsonrpc": "2.0", "method": "fail", "params": {"internal": True}, "id": 2},
+            ],
+            {"headers": {"x-rpc-safe-enabled": "true"}},
+        )
+
+        self.assertEqual(
+            response.body[0]["error"],
+            {"code": -32042, "message": "Quota exceeded", "data": {"reason": "S:limit"}},
+        )
+        self.assertEqual(response.body[1]["error"], {"code": -32603, "message": "Internal error"})
+
+
+if __name__ == "__main__":
+    unittest.main()

rpc_python_toolkit-0.2.1/tests/test_protocol.py

@@ -0,0 +1,111 @@
+from __future__ import annotations
+
+import unittest
+
+from rpc_python_toolkit import RpcEndpoint, RpcSafeEndpoint
+
+
+class ProtocolTests(unittest.TestCase):
+    def setUp(self):
+        self.rpc = RpcEndpoint()
+        self.calls = []
+        self.rpc.add_method("echo", self.echo)
+
+    def echo(self, _request, _context, params):
+        self.calls.append(params)
+        return params
+
+    def test_invalid_envelopes_are_errors_not_notifications(self):
+        for request in [None, 1, True, "echo", {}, {"method": "echo"},
+                        {"jsonrpc": "1.0", "method": "echo"},
+                        {"jsonrpc": "2.0", "method": True}]:
+            with self.subTest(request=request):
+                response = self.rpc.handle_payload(request)
+                self.assertEqual(response.status, 200)
+                # A bare string is decoded as JSON; exercise structured invalid
+                # envelopes separately from JSON parse failures.
+                expected_code = -32700 if request == "echo" else -32600
+                self.assertEqual(response.body["error"]["code"], expected_code)
+                self.assertIsNone(response.body["id"])
+        self.assertEqual(self.calls, [])
+
+    def test_rejects_invalid_ids_without_echoing_them(self):
+        for request_id in [True, False, {}, [], float("nan"), float("inf"), -float("inf")]:
+            with self.subTest(request_id=request_id):
+                response = self.rpc.handle_payload(
+                    {"jsonrpc": "2.0", "method": "echo", "id": request_id}
+                )
+                self.assertEqual(response.body["error"]["code"], -32600)
+                self.assertIsNone(response.body["id"])
+        self.assertEqual(self.calls, [])
+
+    def test_non_json_constants_on_wire_are_parse_errors(self):
+        for token in ["NaN", "Infinity", "-Infinity"]:
+            for member in ['"params":{"value":' + token + '}', '"id":' + token]:
+                with self.subTest(token=token, member=member):
+                    response = self.rpc.handle_payload(
+                        '{"jsonrpc":"2.0","method":"echo",' + member + '}'
+                    )
+                    self.assertEqual(response.body,
+                                     {"jsonrpc": "2.0", "id": None,
+                                      "error": {"code": -32700, "message": "Parse error"}})
+        self.assertEqual(self.calls, [])
+
+    def test_valid_json_number_overflow_in_id_is_invalid_request(self):
+        response = self.rpc.handle_payload('{"jsonrpc":"2.0","method":"echo","id":1e999}')
+        self.assertEqual(response.body["error"]["code"], -32600)
+        self.assertIsNone(response.body["id"])
+        self.assertEqual(self.calls, [])
+
+    def test_explicit_null_and_other_valid_ids_receive_responses(self):
+        for request_id in [None, 0, 1.5, "", "S:literal", "D:2026-01-01", "123n"]:
+            with self.subTest(request_id=request_id):
+                response = self.rpc.handle_payload(
+                    {"jsonrpc": "2.0", "method": "echo", "params": {}, "id": request_id}
+                )
+                self.assertEqual(response.body, {"jsonrpc": "2.0", "id": request_id, "result": {}})
+
+    def test_params_must_be_object_or_array_when_present(self):
+        for params in [None, True, 1, "text"]:
+            for with_id in [True, False]:
+                with self.subTest(params=params, with_id=with_id):
+                    request = {"jsonrpc": "2.0", "method": "echo", "params": params}
+                    if with_id:
+                        request["id"] = 7
+                    response = self.rpc.handle_payload(request)
+                    self.assertEqual(response.body["error"]["code"], -32600)
+                    self.assertIsNone(response.body["id"])
+        self.assertEqual(self.calls, [])
+
+    def test_mixed_batch_retains_invalid_elements_and_explicit_null_calls(self):
+        response = self.rpc.handle_payload([
+            {},
+            {"jsonrpc": "2.0", "method": "echo"},
+            {"jsonrpc": "2.0", "method": "echo", "params": [], "id": None},
+            {"jsonrpc": "2.0", "method": "missing"},
+        ])
+        self.assertEqual(len(response.body), 2)
+        self.assertEqual(response.body[0]["error"]["code"], -32600)
+        self.assertEqual(response.body[1], {"jsonrpc": "2.0", "id": None, "result": []})
+
+    def test_all_valid_notifications_have_no_response(self):
+        response = self.rpc.handle_payload([
+            {"jsonrpc": "2.0", "method": "echo"},
+            {"jsonrpc": "2.0", "method": "missing"},
+        ])
+        self.assertEqual(response.status, 204)
+        self.assertIsNone(response.body)
+
+    def test_safe_mode_keeps_envelope_literals_and_nested_empty_containers(self):
+        rpc = RpcSafeEndpoint()
+        rpc.add_method("S:echo", self.echo)
+        response = rpc.handle_payload(
+            {"jsonrpc": "2.0", "method": "S:echo", "params": {"object": {}, "array": []}, "id": "123n"},
+            {"headers": {"x-rpc-safe-enabled": "true"}},
+        )
+        self.assertEqual(response.body,
+                         {"jsonrpc": "2.0", "id": "123n", "result": {"object": {}, "array": []}})
+
+
+if __name__ == "__main__":
+    unittest.main()

rpc_python_toolkit-0.1.0/src/rpc_python_toolkit/version.py

@@ -1,2 +0,0 @@
-__version__ = "0.1.0"
-