From 115a402ac2079c1a1b4550885f4f828894dfc927 Mon Sep 17 00:00:00 2001 From: Matthew Wolter Date: Sat, 11 Apr 2026 19:46:50 -0700 Subject: [PATCH] =?UTF-8?q?G3:=20N11=20=E2=80=94=20document=20transport=20?= =?UTF-8?q?connect()=20return=20contract?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The three transports had inconsistent connect() return contracts: TCP returned an asyncio.Future (fixed by F01), serial returned self.port (always truthy), BLE returned self.address or None. ConnectionManager's success check `if result is not None:` was tautological for TCP and serial. With F01 fixed, the check is now meaningful for all three. Add a comprehensive docstring to ConnectionProtocol documenting the contract: return truthy on success (included in CONNECTED event payload), return None for soft failure (retry), or raise for hard failure (also retry, logged). Also import Awaitable for the F02 reconnect_callback type hint that follows. Refs: Forensics report finding N11 --- src/meshcore/connection_manager.py | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/src/meshcore/connection_manager.py b/src/meshcore/connection_manager.py index c95ec37..ba8d928 100644 --- a/src/meshcore/connection_manager.py +++ b/src/meshcore/connection_manager.py @@ -4,14 +4,23 @@ Connection manager that orchestrates reconnection logic for any connection type. import asyncio import logging -from typing import Optional, Any, Callable, Protocol +from typing import Optional, Any, Awaitable, Callable, Protocol from .events import Event, EventType logger = logging.getLogger("meshcore") class ConnectionProtocol(Protocol): - """Protocol defining the interface that connection classes must implement.""" + """Protocol defining the interface that connection classes must implement. + + Return contract for connect(): + - On success: return a truthy value (typically an address string) + that identifies the connection. This value is included in the + CONNECTED event payload as ``connection_info``. + - On failure: return ``None`` (soft failure — triggers a retry in + ``_attempt_reconnect``) **or** raise an exception (hard failure — + also triggers a retry, logged as an error). + """ async def connect(self) -> Optional[Any]: """Connect and return connection info, or None if failed."""