tactus 0.34.0__py3-none-any.whl → 0.35.0__py3-none-any.whl

tactus/adapters/plugins.py

@@ -85,25 +85,25 @@ class PluginLoader:
         all_tools = []
 
         for path_str in paths:
-            path = Path(path_str).resolve()
+            resolved_path = Path(path_str).resolve()
 
-            if not path.exists():
-                logger.warning(f"Tool path does not exist: {path}")
+            if not resolved_path.exists():
+                logger.warning(f"Tool path does not exist: {resolved_path}")
                 continue
 
-            if path.is_file():
+            if resolved_path.is_file():
                 # Load tools from single file
-                if path.suffix == ".py":
-                    tools = self._load_tools_from_file(path)
+                if resolved_path.suffix == ".py":
+                    tools = self._load_tools_from_file(resolved_path)
                     all_tools.extend(tools)
                 else:
-                    logger.warning(f"Skipping non-Python file: {path}")
-            elif path.is_dir():
+                    logger.warning(f"Skipping non-Python file: {resolved_path}")
+            elif resolved_path.is_dir():
                 # Scan directory for Python files
-                tools = self._load_tools_from_directory(path)
+                tools = self._load_tools_from_directory(resolved_path)
                 all_tools.extend(tools)
             else:
-                logger.warning(f"Path is neither file nor directory: {path}")
+                logger.warning(f"Path is neither file nor directory: {resolved_path}")
 
         logger.info(f"Loaded {len(all_tools)} tools from {len(paths)} path(s)")
         return all_tools
@@ -121,23 +121,23 @@ class PluginLoader:
         all_functions = []
 
         for path_str in paths:
-            path = Path(path_str).resolve()
+            resolved_path = Path(path_str).resolve()
 
-            if not path.exists():
-                logger.warning(f"Tool path does not exist: {path}")
+            if not resolved_path.exists():
+                logger.warning(f"Tool path does not exist: {resolved_path}")
                 continue
 
-            if path.is_file():
-                if path.suffix == ".py":
-                    functions = self._load_functions_from_file(path)
+            if resolved_path.is_file():
+                if resolved_path.suffix == ".py":
+                    functions = self._load_functions_from_file(resolved_path)
                     all_functions.extend(functions)
                 else:
-                    logger.warning(f"Skipping non-Python file: {path}")
-            elif path.is_dir():
-                functions = self._load_functions_from_directory(path)
+                    logger.warning(f"Skipping non-Python file: {resolved_path}")
+            elif resolved_path.is_dir():
+                functions = self._load_functions_from_directory(resolved_path)
                 all_functions.extend(functions)
             else:
-                logger.warning(f"Path is neither file nor directory: {path}")
+                logger.warning(f"Path is neither file nor directory: {resolved_path}")
 
         logger.debug(f"Loaded {len(all_functions)} function(s) from {len(paths)} path(s)")
         return all_functions
@@ -200,8 +200,8 @@ class PluginLoader:
                     functions.append(obj)
                     logger.debug(f"Found function '{name}' in {file_path.name}")
 
-        except Exception as e:
-            logger.error(f"Failed to load functions from {file_path}: {e}", exc_info=True)
+        except Exception as error:
+            logger.error(f"Failed to load functions from {file_path}: {error}", exc_info=True)
 
         return functions
 
@@ -216,14 +216,14 @@ class PluginLoader:
             Async callback function for process_tool_call
         """
 
-        async def trace_tool_call(ctx, next_call, tool_name, tool_args):
+        async def trace_tool_call(execution_context, invoke_next, tool_name, tool_args):
             """Middleware to record tool calls in Tactus ToolPrimitive."""
             logger.debug(
                 f"Toolset '{toolset_name}' calling tool '{tool_name}' with args: {tool_args}"
             )
 
             try:
-                result = await next_call(tool_name, tool_args)
+                result = await invoke_next(tool_name, tool_args)
 
                 # Record in ToolPrimitive if available
                 if self.tool_primitive:
@@ -232,11 +232,11 @@ class PluginLoader:
 
                 logger.debug(f"Tool '{tool_name}' completed successfully")
                 return result
-            except Exception as e:
-                logger.error(f"Tool '{tool_name}' failed: {e}", exc_info=True)
+            except Exception as error:
+                logger.error(f"Tool '{tool_name}' failed: {error}", exc_info=True)
                 # Still record the failed call
                 if self.tool_primitive:
-                    error_msg = f"Error: {str(e)}"
+                    error_msg = f"Error: {str(error)}"
                     self.tool_primitive.record_call(tool_name, tool_args, error_msg)
                 raise
 
@@ -308,8 +308,8 @@ class PluginLoader:
                         tools.append(tool)
                         logger.info(f"Loaded tool '{name}' from {file_path.name}")
 
-        except Exception as e:
-            logger.error(f"Failed to load tools from {file_path}: {e}", exc_info=True)
+        except Exception as error:
+            logger.error(f"Failed to load tools from {file_path}: {error}", exc_info=True)
 
         return tools
 
@@ -352,8 +352,8 @@ class PluginLoader:
         """
         try:
             # Get function signature and docstring
-            sig = inspect.signature(func)
-            doc = inspect.getdoc(func) or f"Tool: {name}"
+            signature = inspect.signature(func)
+            docstring = inspect.getdoc(func) or f"Tool: {name}"
 
             # Check if function is async
             is_async = inspect.iscoroutinefunction(func)
@@ -371,9 +371,9 @@ class PluginLoader:
                             self.tool_primitive.record_call(name, kwargs, str(result))
 
                         return result
-                    except Exception as e:
-                        logger.error(f"Tool '{name}' execution failed: {e}", exc_info=True)
-                        error_msg = f"Error executing tool '{name}': {str(e)}"
+                    except Exception as error:
+                        logger.error(f"Tool '{name}' execution failed: {error}", exc_info=True)
+                        error_msg = f"Error executing tool '{name}': {str(error)}"
 
                         # Record failed call
                         if self.tool_primitive:
@@ -393,9 +393,9 @@ class PluginLoader:
                             self.tool_primitive.record_call(name, kwargs, str(result))
 
                         return result
-                    except Exception as e:
-                        logger.error(f"Tool '{name}' execution failed: {e}", exc_info=True)
-                        error_msg = f"Error executing tool '{name}': {str(e)}"
+                    except Exception as error:
+                        logger.error(f"Tool '{name}' execution failed: {error}", exc_info=True)
+                        error_msg = f"Error executing tool '{name}': {str(error)}"
 
                         # Record failed call
                         if self.tool_primitive:
@@ -404,16 +404,16 @@ class PluginLoader:
                         raise
 
             # Copy signature and docstring to wrapper
-            tool_wrapper.__signature__ = sig
-            tool_wrapper.__doc__ = doc
+            tool_wrapper.__signature__ = signature
+            tool_wrapper.__doc__ = docstring
             tool_wrapper.__name__ = name
             tool_wrapper.__annotations__ = func.__annotations__
 
             # Create Pydantic AI Tool
-            tool = Tool(tool_wrapper, name=name, description=doc)
+            tool = Tool(tool_wrapper, name=name, description=docstring)
 
             return tool
 
-        except Exception as e:
-            logger.error(f"Failed to create tool from function '{name}': {e}", exc_info=True)
+        except Exception as error:
+            logger.error(f"Failed to create tool from function '{name}': {error}", exc_info=True)
             return None

tactus/broker/client.py

@@ -31,12 +31,16 @@ def _json_dumps(obj: Any) -> str:
 class _StdioBrokerTransport:
     def __init__(self):
         self._write_lock = threading.Lock()
-        self._pending: dict[
+        self._pending_requests: dict[
             str, tuple[asyncio.AbstractEventLoop, asyncio.Queue[dict[str, Any]]]
         ] = {}
+        # Backward-compatible alias used in tests and older code paths.
+        self._pending = self._pending_requests
         self._pending_lock = threading.Lock()
         self._reader_thread: Optional[threading.Thread] = None
-        self._stop = threading.Event()
+        self._shutdown_event = threading.Event()
+        # Backward-compatible alias used in tests and older code paths.
+        self._stop = self._shutdown_event
 
     def _ensure_reader_thread(self) -> None:
         if self._reader_thread is not None and self._reader_thread.is_alive():
@@ -50,33 +54,33 @@ class _StdioBrokerTransport:
         self._reader_thread.start()
 
     def _read_loop(self) -> None:
-        while not self._stop.is_set():
-            line = sys.stdin.buffer.readline()
-            if not line:
+        while not self._shutdown_event.is_set():
+            input_line = sys.stdin.buffer.readline()
+            if not input_line:
                 return
             try:
-                event = json.loads(line.decode("utf-8"))
+                event_payload = json.loads(input_line.decode("utf-8"))
             except json.JSONDecodeError:
                 continue
 
-            req_id = event.get("id")
-            if not isinstance(req_id, str):
+            request_id_value = event_payload.get("id")
+            if not isinstance(request_id_value, str):
                 continue
 
             with self._pending_lock:
-                pending = self._pending.get(req_id)
-            if pending is None:
+                pending_request = self._pending_requests.get(request_id_value)
+            if pending_request is None:
                 continue
 
-            loop, queue = pending
+            event_loop, response_queue = pending_request
             try:
-                loop.call_soon_threadsafe(queue.put_nowait, event)
+                event_loop.call_soon_threadsafe(response_queue.put_nowait, event_payload)
             except RuntimeError:
                 # Loop is closed or unavailable; ignore.
                 continue
 
     async def aclose(self) -> None:
-        self._stop.set()
+        self._shutdown_event.set()
         thread = self._reader_thread
         if thread is None or not thread.is_alive():
             return
@@ -86,28 +90,28 @@ class _StdioBrokerTransport:
             return
 
     async def request(
-        self, req_id: str, method: str, params: dict[str, Any]
+        self, request_id: str, method: str, params: dict[str, Any]
     ) -> AsyncIterator[dict[str, Any]]:
         self._ensure_reader_thread()
-        loop = asyncio.get_running_loop()
-        queue: asyncio.Queue[dict[str, Any]] = asyncio.Queue()
+        event_loop = asyncio.get_running_loop()
+        response_queue: asyncio.Queue[dict[str, Any]] = asyncio.Queue()
         with self._pending_lock:
-            self._pending[req_id] = (loop, queue)
+            self._pending_requests[request_id] = (event_loop, response_queue)
 
         try:
-            payload = _json_dumps({"id": req_id, "method": method, "params": params})
+            request_payload = _json_dumps({"id": request_id, "method": method, "params": params})
             with self._write_lock:
-                sys.stderr.write(f"{STDIO_REQUEST_PREFIX}{payload}\n")
+                sys.stderr.write(f"{STDIO_REQUEST_PREFIX}{request_payload}\n")
                 sys.stderr.flush()
 
             while True:
-                event = await queue.get()
-                yield event
-                if event.get("event") in ("done", "error"):
+                event_payload = await response_queue.get()
+                yield event_payload
+                if event_payload.get("event") in ("done", "error"):
                     return
         finally:
             with self._pending_lock:
-                self._pending.pop(req_id, None)
+                self._pending_requests.pop(request_id, None)
 
 
 _STDIO_TRANSPORT = _StdioBrokerTransport()
@@ -129,59 +133,61 @@ class BrokerClient:
         return cls(socket_path)
 
     async def _request(self, method: str, params: dict[str, Any]) -> AsyncIterator[dict[str, Any]]:
-        req_id = uuid.uuid4().hex
+        request_id = uuid.uuid4().hex
 
         if self.socket_path == STDIO_TRANSPORT_VALUE:
-            async for event in _STDIO_TRANSPORT.request(req_id, method, params):
+            async for event_payload in _STDIO_TRANSPORT.request(request_id, method, params):
                 # Responses are already correlated by req_id; add a defensive filter anyway.
-                if event.get("id") == req_id:
-                    yield event
+                if event_payload.get("id") == request_id:
+                    yield event_payload
             return
 
         if self.socket_path.startswith(("tcp://", "tls://")):
             use_tls = self.socket_path.startswith("tls://")
-            host_port = self.socket_path.split("://", 1)[1]
-            if "/" in host_port:
-                host_port = host_port.split("/", 1)[0]
-            if ":" not in host_port:
+            host_and_port = self.socket_path.split("://", 1)[1]
+            if "/" in host_and_port:
+                host_and_port = host_and_port.split("/", 1)[0]
+            if ":" not in host_and_port:
                 raise ValueError(
-                    f"Invalid broker endpoint: {self.socket_path}. Expected tcp://host:port or tls://host:port"
+                    "Invalid broker endpoint: "
+                    f"{self.socket_path}. Expected tcp://host:port or tls://host:port"
                 )
-            host, port_str = host_port.rsplit(":", 1)
+            host, port_text = host_and_port.rsplit(":", 1)
             try:
-                port = int(port_str)
-            except ValueError as e:
-                raise ValueError(f"Invalid broker port in endpoint: {self.socket_path}") from e
+                port = int(port_text)
+            except ValueError as error:
+                raise ValueError(f"Invalid broker port in endpoint: {self.socket_path}") from error
 
-            ssl_ctx: ssl.SSLContext | None = None
+            ssl_context: ssl.SSLContext | None = None
             if use_tls:
-                ssl_ctx = ssl.create_default_context()
+                ssl_context = ssl.create_default_context()
                 cafile = os.environ.get("TACTUS_BROKER_TLS_CA_FILE")
                 if cafile:
-                    ssl_ctx.load_verify_locations(cafile=cafile)
+                    ssl_context.load_verify_locations(cafile=cafile)
 
                 if os.environ.get("TACTUS_BROKER_TLS_INSECURE") in ("1", "true", "yes"):
-                    ssl_ctx.check_hostname = False
-                    ssl_ctx.verify_mode = ssl.CERT_NONE
+                    ssl_context.check_hostname = False
+                    ssl_context.verify_mode = ssl.CERT_NONE
 
-            reader, writer = await asyncio.open_connection(host, port, ssl=ssl_ctx)
+            reader, writer = await asyncio.open_connection(host, port, ssl=ssl_context)
             logger.info(
-                f"[BROKER_CLIENT] Writing message to broker, params keys: {list(params.keys())}"
+                "[BROKER_CLIENT] Writing message to broker, params keys: %s",
+                list(params.keys()),
             )
             try:
-                await write_message(writer, {"id": req_id, "method": method, "params": params})
-            except TypeError as e:
-                logger.error(f"[BROKER_CLIENT] JSON serialization error: {e}")
-                logger.error(f"[BROKER_CLIENT] Params: {params}")
+                await write_message(writer, {"id": request_id, "method": method, "params": params})
+            except TypeError as error:
+                logger.error("[BROKER_CLIENT] JSON serialization error: %s", error)
+                logger.error("[BROKER_CLIENT] Params: %s", params)
                 raise
 
             try:
                 while True:
-                    event = await read_message(reader)
-                    if event.get("id") != req_id:
+                    event_payload = await read_message(reader)
+                    if event_payload.get("id") != request_id:
                         continue
-                    yield event
-                    if event.get("event") in ("done", "error"):
+                    yield event_payload
+                    if event_payload.get("event") in ("done", "error"):
                         return
             finally:
                 try:
@@ -191,16 +197,16 @@ class BrokerClient:
                     pass
 
         reader, writer = await asyncio.open_unix_connection(self.socket_path)
-        await write_message(writer, {"id": req_id, "method": method, "params": params})
+        await write_message(writer, {"id": request_id, "method": method, "params": params})
 
         try:
             while True:
-                event = await read_message(reader)
+                event_payload = await read_message(reader)
                 # Ignore unrelated messages (defensive; current server is 1-req/conn).
-                if event.get("id") != req_id:
+                if event_payload.get("id") != request_id:
                     continue
-                yield event
-                if event.get("event") in ("done", "error"):
+                yield event_payload
+                if event_payload.get("event") in ("done", "error"):
                     return
         finally:
             try:
@@ -221,34 +227,25 @@ class BrokerClient:
         tools: Optional[list[dict[str, Any]]] = None,
         tool_choice: Optional[str] = None,
     ) -> AsyncIterator[dict[str, Any]]:
-        params: dict[str, Any] = {
+        request_params: dict[str, Any] = {
             "provider": provider,
             "model": model,
             "messages": messages,
             "stream": stream,
         }
         if temperature is not None:
-            params["temperature"] = temperature
+            request_params["temperature"] = temperature
         if max_tokens is not None:
-            params["max_tokens"] = max_tokens
+            request_params["max_tokens"] = max_tokens
         if tools is not None:
-            params["tools"] = tools
-            import logging
-
-            logger = logging.getLogger(__name__)
-            logger.info(f"[BROKER_CLIENT] Adding {len(tools)} tools to params")
+            request_params["tools"] = tools
+            logger.info("[BROKER_CLIENT] Adding %s tools to params", len(tools))
         else:
-            import logging
-
-            logger = logging.getLogger(__name__)
             logger.warning("[BROKER_CLIENT] No tools to add to params")
         if tool_choice is not None:
-            params["tool_choice"] = tool_choice
-            import logging
-
-            logger = logging.getLogger(__name__)
-            logger.info(f"[BROKER_CLIENT] Adding tool_choice={tool_choice} to params")
-        return self._request("llm.chat", params)
+            request_params["tool_choice"] = tool_choice
+            logger.info("[BROKER_CLIENT] Adding tool_choice=%s to params", tool_choice)
+        return self._request("llm.chat", request_params)
 
     async def call_tool(self, *, name: str, args: dict[str, Any]) -> Any:
         """
@@ -261,14 +258,14 @@ class BrokerClient:
         if not isinstance(args, dict):
             raise ValueError("tool args must be an object")
 
-        async for event in self._request("tool.call", {"name": name, "args": args}):
-            event_type = event.get("event")
+        async for event_payload in self._request("tool.call", {"name": name, "args": args}):
+            event_type = event_payload.get("event")
             if event_type == "done":
-                data = event.get("data") or {}
+                data = event_payload.get("data") or {}
                 return data.get("result")
             if event_type == "error":
-                err = event.get("error") or {}
-                raise RuntimeError(err.get("message") or "Broker tool error")
+                error_payload = event_payload.get("error") or {}
+                raise RuntimeError(error_payload.get("message") or "Broker tool error")
 
         raise RuntimeError("Broker tool call ended without a response")
 

tactus/broker/protocol.py

@@ -12,10 +12,10 @@ Example:
     {"id":"abc","method":"llm.chat","params":{...}}
 """
 
-import json
 import asyncio
 import logging
-from typing import Any, Dict, AsyncIterator
+import json
+from typing import Any, AsyncIterator
 
 import anyio
 from anyio.streams.buffered import BufferedByteReceiveStream
@@ -27,7 +27,33 @@ LENGTH_PREFIX_SIZE = 11  # "0000000123\n"
 MAX_MESSAGE_SIZE = 100 * 1024 * 1024  # 100MB safety limit
 
 
-async def write_message(writer: asyncio.StreamWriter, message: Dict[str, Any]) -> None:
+def _parse_length_prefix(length_prefix_bytes: bytes) -> int:
+    try:
+        length_text = length_prefix_bytes[:10].decode("ascii")
+        payload_length = int(length_text)
+    except (ValueError, UnicodeDecodeError) as error:
+        raise ValueError(f"Invalid length prefix: {length_prefix_bytes!r}") from error
+
+    if payload_length > MAX_MESSAGE_SIZE:
+        raise ValueError(f"Message size {payload_length} exceeds maximum {MAX_MESSAGE_SIZE}")
+
+    if payload_length == 0:
+        raise ValueError("Zero-length message not allowed")
+
+    return payload_length
+
+
+def _serialize_json_payload(message: dict[str, Any]) -> bytes:
+    json_payload_bytes = json.dumps(message).encode("utf-8")
+    payload_length = len(json_payload_bytes)
+
+    if payload_length > MAX_MESSAGE_SIZE:
+        raise ValueError(f"Message size {payload_length} exceeds maximum {MAX_MESSAGE_SIZE}")
+
+    return json_payload_bytes
+
+
+async def write_message(writer: asyncio.StreamWriter, message: dict[str, Any]) -> None:
     """
     Write a JSON message with length prefix.
 
@@ -38,20 +64,17 @@ async def write_message(writer: asyncio.StreamWriter, message: Dict[str, Any]) -
     Raises:
         ValueError: If message is too large
     """
-    json_bytes = json.dumps(message).encode("utf-8")
-    length = len(json_bytes)
-
-    if length > MAX_MESSAGE_SIZE:
-        raise ValueError(f"Message size {length} exceeds maximum {MAX_MESSAGE_SIZE}")
+    json_payload_bytes = _serialize_json_payload(message)
+    payload_length = len(json_payload_bytes)
 
     # Write 10-digit length prefix + newline
-    length_prefix = f"{length:010d}\n".encode("ascii")
+    length_prefix = f"{payload_length:010d}\n".encode("ascii")
     writer.write(length_prefix)
-    writer.write(json_bytes)
+    writer.write(json_payload_bytes)
     await writer.drain()
 
 
-async def read_message(reader: asyncio.StreamReader) -> Dict[str, Any]:
+async def read_message(reader: asyncio.StreamReader) -> dict[str, Any]:
     """
     Read a JSON message with length prefix.
 
@@ -66,35 +89,25 @@ async def read_message(reader: asyncio.StreamReader) -> Dict[str, Any]:
         ValueError: If message is invalid or too large
     """
     # Read exactly 11 bytes for length prefix
-    length_bytes = await reader.readexactly(LENGTH_PREFIX_SIZE)
+    length_prefix_bytes = await reader.readexactly(LENGTH_PREFIX_SIZE)
 
-    if not length_bytes:
+    if not length_prefix_bytes:
         raise EOFError("Connection closed")
 
-    try:
-        length_str = length_bytes[:10].decode("ascii")
-        length = int(length_str)
-    except (ValueError, UnicodeDecodeError) as e:
-        raise ValueError(f"Invalid length prefix: {length_bytes!r}") from e
-
-    if length > MAX_MESSAGE_SIZE:
-        raise ValueError(f"Message size {length} exceeds maximum {MAX_MESSAGE_SIZE}")
-
-    if length == 0:
-        raise ValueError("Zero-length message not allowed")
+    payload_length = _parse_length_prefix(length_prefix_bytes)
 
     # Read exactly that many bytes for the JSON payload
-    json_bytes = await reader.readexactly(length)
+    json_payload_bytes = await reader.readexactly(payload_length)
 
     try:
-        message = json.loads(json_bytes.decode("utf-8"))
-    except (json.JSONDecodeError, UnicodeDecodeError) as e:
-        raise ValueError("Invalid JSON payload") from e
+        message = json.loads(json_payload_bytes.decode("utf-8"))
+    except (json.JSONDecodeError, UnicodeDecodeError) as error:
+        raise ValueError("Invalid JSON payload") from error
 
     return message
 
 
-async def read_messages(reader: asyncio.StreamReader) -> AsyncIterator[Dict[str, Any]]:
+async def read_messages(reader: asyncio.StreamReader) -> AsyncIterator[dict[str, Any]]:
     """
     Read a stream of length-prefixed JSON messages.
 
@@ -110,14 +123,14 @@ async def read_messages(reader: asyncio.StreamReader) -> AsyncIterator[Dict[str,
         while True:
             message = await read_message(reader)
             yield message
-    except EOFError:
-        return
     except asyncio.IncompleteReadError:
         return
+    except EOFError:
+        return
 
 
 # AnyIO-compatible versions for broker server
-async def write_message_anyio(stream: anyio.abc.ByteStream, message: Dict[str, Any]) -> None:
+async def write_message_anyio(stream: anyio.abc.ByteStream, message: dict[str, Any]) -> None:
     """
     Write a JSON message with length prefix using AnyIO streams.
 
@@ -128,19 +141,16 @@ async def write_message_anyio(stream: anyio.abc.ByteStream, message: Dict[str, A
     Raises:
         ValueError: If message is too large
     """
-    json_bytes = json.dumps(message).encode("utf-8")
-    length = len(json_bytes)
-
-    if length > MAX_MESSAGE_SIZE:
-        raise ValueError(f"Message size {length} exceeds maximum {MAX_MESSAGE_SIZE}")
+    json_payload_bytes = _serialize_json_payload(message)
+    payload_length = len(json_payload_bytes)
 
     # Write 10-digit length prefix + newline
-    length_prefix = f"{length:010d}\n".encode("ascii")
+    length_prefix = f"{payload_length:010d}\n".encode("ascii")
     await stream.send(length_prefix)
-    await stream.send(json_bytes)
+    await stream.send(json_payload_bytes)
 
 
-async def read_message_anyio(stream: BufferedByteReceiveStream) -> Dict[str, Any]:
+async def read_message_anyio(stream: BufferedByteReceiveStream) -> dict[str, Any]:
     """
     Read a JSON message with length prefix using AnyIO streams.
 
@@ -155,29 +165,19 @@ async def read_message_anyio(stream: BufferedByteReceiveStream) -> Dict[str, Any
         ValueError: If message is invalid or too large
     """
     # Read exactly 11 bytes for length prefix
-    length_bytes = await stream.receive_exactly(LENGTH_PREFIX_SIZE)
+    length_prefix_bytes = await stream.receive_exactly(LENGTH_PREFIX_SIZE)
 
-    if not length_bytes:
+    if not length_prefix_bytes:
         raise EOFError("Connection closed")
 
-    try:
-        length_str = length_bytes[:10].decode("ascii")
-        length = int(length_str)
-    except (ValueError, UnicodeDecodeError) as e:
-        raise ValueError(f"Invalid length prefix: {length_bytes!r}") from e
-
-    if length > MAX_MESSAGE_SIZE:
-        raise ValueError(f"Message size {length} exceeds maximum {MAX_MESSAGE_SIZE}")
-
-    if length == 0:
-        raise ValueError("Zero-length message not allowed")
+    payload_length = _parse_length_prefix(length_prefix_bytes)
 
     # Read exactly that many bytes for the JSON payload
-    json_bytes = await stream.receive_exactly(length)
+    json_payload_bytes = await stream.receive_exactly(payload_length)
 
     try:
-        message = json.loads(json_bytes.decode("utf-8"))
-    except (json.JSONDecodeError, UnicodeDecodeError) as e:
-        raise ValueError("Invalid JSON payload") from e
+        message = json.loads(json_payload_bytes.decode("utf-8"))
+    except (json.JSONDecodeError, UnicodeDecodeError) as error:
+        raise ValueError("Invalid JSON payload") from error
 
     return message