Skip to content

Agent Zero AI framework

Harden Core connector transport

Alessandro828f91901065
diff --git a/api/ws_dev_test.py b/api/ws_dev_test.py
index 12dbf33f2..9ba263b27 100644
--- a/api/ws_dev_test.py
+++ b/api/ws_dev_test.py
@@ -1,5 +1,7 @@
import asyncio
+import hashlib
from typing import Any
+import uuid
from helpers.ws import WsHandler
from helpers.ws_manager import WsResult
@@ -7,6 +9,9 @@ from helpers.print_style import PrintStyle
from helpers import runtime
+_MAX_CONNECTOR_TRANSFER_TEST_BYTES = 32 * 1024 * 1024
+
+
class WsDevTest(WsHandler):
"""Developer-only WebSocket test harness handler."""
@@ -36,6 +41,99 @@ class WsDevTest(WsHandler):
PrintStyle.info(f"Harness emit broadcasted message='{message}'")
return None
+ if event == "ws_tester_emit_to":
+ payload = {
+ "message": data.get("message", "emit"),
+ "echo": True,
+ "timestamp": data.get("timestamp"),
+ }
+ await self.emit_to(sid, "ws_tester_emit_to_result", payload)
+ return {"status": "emitted"}
+
+ if event == "ws_tester_connector_transfer":
+ try:
+ request_bytes = int(data.get("request_bytes", 0))
+ result_bytes = int(data.get("result_bytes", 0))
+ except (TypeError, ValueError):
+ request_bytes = result_bytes = -1
+ if not (
+ 0 <= request_bytes <= _MAX_CONNECTOR_TRANSFER_TEST_BYTES
+ and 0 <= result_bytes <= _MAX_CONNECTOR_TRANSFER_TEST_BYTES
+ ):
+ return WsResult.error(
+ code="INVALID_SIZE",
+ message=(
+ "request_bytes and result_bytes must be between 0 and "
+ f"{_MAX_CONNECTOR_TRANSFER_TEST_BYTES}"
+ ),
+ )
+
+ from plugins._a0_connector.helpers.ws_runtime import (
+ abort_transfers_for_context,
+ clear_pending_browser_op,
+ emit_connector_event,
+ store_pending_browser_op,
+ )
+
+ op_id = uuid.uuid4().hex
+ loop = asyncio.get_running_loop()
+ future: asyncio.Future[dict[str, Any]] = loop.create_future()
+ store_pending_browser_op(
+ op_id,
+ sid=sid,
+ future=future,
+ loop=loop,
+ context_id="ws-dev-test",
+ )
+ cancel_task: asyncio.Task[int] | None = None
+ cancelled_transfers = 0
+ if bool(data.get("cancel")):
+ async def cancel_after_start() -> int:
+ await asyncio.sleep(0)
+ return await abort_transfers_for_context(
+ "ws-dev-test",
+ reason="developer harness cancelled transfer",
+ manager=self.manager,
+ )
+
+ cancel_task = asyncio.create_task(cancel_after_start())
+ try:
+ await emit_connector_event(
+ sid,
+ "connector_browser_op",
+ {
+ "op_id": op_id,
+ "context_id": "ws-dev-test",
+ "action": "transfer_stress",
+ "request_padding": "r" * request_bytes,
+ "result_bytes": result_bytes,
+ },
+ handler_id=self.identifier,
+ manager=self.manager,
+ )
+ result = await asyncio.wait_for(future, timeout=30)
+ finally:
+ clear_pending_browser_op(op_id)
+ if cancel_task is not None:
+ cancelled_transfers = await cancel_task
+
+ result_payload = result.get("result") if isinstance(result, dict) else None
+ result_padding = (
+ str(result_payload.get("result_padding") or "")
+ if isinstance(result_payload, dict)
+ else ""
+ )
+ response = {
+ "status": "ok" if result.get("ok") is True else "error",
+ "request_bytes": request_bytes,
+ "result_bytes": len(result_padding.encode("utf-8")),
+ "result_sha256": hashlib.sha256(result_padding.encode("utf-8")).hexdigest(),
+ }
+ if cancel_task is not None:
+ response["status"] = "cancelled" if cancelled_transfers else "error"
+ response["cancelled_transfers"] = cancelled_transfers
+ return response
+
if event == "ws_tester_request":
value = data.get("value")
PrintStyle.debug("Harness request responded with echo %s", value)
diff --git a/api/ws_dev_test.py.dox.md b/api/ws_dev_test.py.dox.md
index aaad42608..aba980f5c 100644
--- a/api/ws_dev_test.py.dox.md
+++ b/api/ws_dev_test.py.dox.md
@@ -17,15 +17,28 @@
## Runtime Contracts
- HTTP handlers must derive from `helpers.api.ApiHandler`; WebSocket handlers must derive from `helpers.ws.WsHandler`.
+- `ws_tester_emit_to` echoes a caller-supplied message to that authenticated SID
+ as `ws_tester_emit_to_result`. It is the deterministic single-peer harness for
+ serialized event-boundary and negotiated-limit regression tests; it must use
+ `WsHandler.emit_to` so the shared manager guard remains in the exercised path.
+- `ws_tester_connector_transfer` sends a bounded synthetic
+ browser operation through `_a0_connector`'s negotiated sender, awaits its
+ correlated result, and returns only byte-count/hash evidence. Request and
+ result padding are independently capped at 32 MiB. This is the deterministic
+ live harness for proving the symmetric transfer protocol without creating a
+ chat, invoking an agent, or retaining the synthetic payload. Optional
+ `cancel=true` schedules the production context-cancellation path immediately
+ after transfer start and reports the number of aborted states, allowing live
+ CPU/RSS and spool-cleanup regression checks without a real chat lifecycle.
- Update this file whenever request payloads, authentication or CSRF requirements, response shapes, route side effects, or WebSocket event contracts change.
- `WsDevTest` is a `WsHandler`.
- `WsDevTest` defines `process(...)`.
- Observed side-effect areas: filesystem writes, network calls, WebSocket state.
-- Imported dependency areas include: `asyncio`, `helpers`, `helpers.print_style`, `helpers.ws`, `helpers.ws_manager`, `typing`.
+- Imported dependency areas include: `asyncio`, `hashlib`, `helpers`, `helpers.print_style`, `helpers.ws`, `helpers.ws_manager`, `typing`, `uuid`.
## Key Concepts
-- Important called helpers/classes observed in the source: `event.startswith`, `self.manager.register_diagnostic_watcher`, `self.manager.unregister_diagnostic_watcher`, `PrintStyle.info`, `PrintStyle.debug`, `PrintStyle.warning`, `runtime.is_development`, `WsResult.error`, `self.broadcast`, `asyncio.sleep`, `self.emit_to`, `self.dispatch_to_all_sids`.
+- Important called helpers/classes observed in the source: `event.startswith`, `self.manager.register_diagnostic_watcher`, `self.manager.unregister_diagnostic_watcher`, `PrintStyle.info`, `PrintStyle.debug`, `PrintStyle.warning`, `runtime.is_development`, `WsResult.error`, `self.broadcast`, `asyncio.sleep`, `self.emit_to`, `self.dispatch_to_all_sids`, `emit_connector_event`, `store_pending_browser_op`, `clear_pending_browser_op`.
- Keep request/response, tool, or helper semantics documented here at the same time as source changes.
## Work Guidance
diff --git a/helpers/server_startup.py b/helpers/server_startup.py
index 8e3a59393..c427aac82 100644
--- a/helpers/server_startup.py
+++ b/helpers/server_startup.py
@@ -14,6 +14,7 @@ import uvicorn
from helpers import process
from helpers.print_style import PrintStyle
+from helpers.ws_limits import A0_WS_MAX_PAYLOAD_BYTES
def _env_int(name: str, default: int, minimum: int = 0) -> int:
@@ -331,6 +332,7 @@ def _run_server_attempt(
log_level=log_level,
access_log=access_log,
ws=ws,
+ ws_max_size=A0_WS_MAX_PAYLOAD_BYTES,
)
with startup_monitor.stage("uvicorn.server.create"):
diff --git a/helpers/server_startup.py.dox.md b/helpers/server_startup.py.dox.md
index a8417341c..66590e967 100644
--- a/helpers/server_startup.py.dox.md
+++ b/helpers/server_startup.py.dox.md
@@ -37,6 +37,7 @@
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- Uvicorn receives the shared `A0_WS_MAX_PAYLOAD_BYTES` ceiling. The `websockets` backend enforces this transport setting; the selected `wsproto` backend is protected by connector application preflight because Uvicorn exposes no wsproto-specific message-size option.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: filesystem writes, network calls, subprocess/runtime control, settings/state persistence.
- Imported dependency areas include: `asyncio`, `collections`, `contextlib`, `dataclasses`, `faulthandler`, `helpers`, `helpers.print_style`, `os`, `sys`, `threading`, `time`, `typing`, `urllib.request`, `uvicorn`.
diff --git a/helpers/ui_server.py b/helpers/ui_server.py
index fdea68b01..cedaeddc4 100644
--- a/helpers/ui_server.py
+++ b/helpers/ui_server.py
@@ -32,6 +32,7 @@ from helpers.extension import extensible
from helpers.files import get_abs_path
from helpers.print_style import PrintStyle
from helpers.server_startup import StartupMonitor
+from helpers.ws_limits import A0_WS_MAX_PAYLOAD_BYTES
from helpers import settings as settings_helper
from helpers.ws import register_ws_namespace, validate_ws_origin
from helpers.ws_manager import WsManager, set_shared_ws_manager
@@ -107,7 +108,7 @@ class UiServerRuntime:
"A0_SOCKETIO_PING_TIMEOUT_SECONDS",
SOCKETIO_PING_TIMEOUT_SECONDS,
),
- max_http_buffer_size=50 * 1024 * 1024,
+ max_http_buffer_size=A0_WS_MAX_PAYLOAD_BYTES,
)
ws_manager = WsManager(socketio_server, lock)
diff --git a/helpers/ui_server.py.dox.md b/helpers/ui_server.py.dox.md
index ae430843f..bb63bcef2 100644
--- a/helpers/ui_server.py.dox.md
+++ b/helpers/ui_server.py.dox.md
@@ -28,13 +28,14 @@
- Top-level functions:
- `_positive_int_env(name: str, default: int) -> int`
- `configure_process_environment() -> None`
-- Notable constants/configuration names: `UPLOAD_LIMIT_BYTES`, `SOCKETIO_PING_INTERVAL_SECONDS`, `SOCKETIO_PING_TIMEOUT_SECONDS`, `A0_SOCKETIO_PING_INTERVAL_SECONDS`, `A0_SOCKETIO_PING_TIMEOUT_SECONDS`.
+- Notable constants/configuration names: `UPLOAD_LIMIT_BYTES`, `SOCKETIO_PING_INTERVAL_SECONDS`, `SOCKETIO_PING_TIMEOUT_SECONDS`, `A0_SOCKETIO_PING_INTERVAL_SECONDS`, `A0_SOCKETIO_PING_TIMEOUT_SECONDS`, and the shared `A0_WS_MAX_PAYLOAD_BYTES` import.
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Socket.IO heartbeat defaults are intentionally longer than Engine.IO's short defaults so CLI sessions survive long prompt/context work; environment overrides must remain positive integers and fall back to source defaults when invalid.
+- Engine.IO's inbound buffer ceiling uses the shared WebSocket payload limit from `helpers.ws_limits`.
- Observed side-effect areas: filesystem reads, network calls, subprocess/runtime control, WebSocket state, plugin state, settings/state persistence, secret handling.
- Imported dependency areas include: `asyncio`, `dataclasses`, `datetime`, `flask`, `helpers`, `helpers.api`, `helpers.extension`, `helpers.files`, `helpers.print_style`, `helpers.server_startup`, `helpers.ws`, `helpers.ws_manager`, `logging`, `os`, `secrets`, `socketio`.
diff --git a/helpers/ws.py b/helpers/ws.py
index 5ca1cc79c..1e589aff9 100644
--- a/helpers/ws.py
+++ b/helpers/ws.py
@@ -274,11 +274,13 @@ class WsHandler:
data: dict,
*,
correlation_id: str | None = None,
+ max_payload_bytes: int | None = None,
) -> None:
await self.manager.emit_to(
self._namespace, sid, event, data,
handler_id=self.identifier,
correlation_id=correlation_id,
+ max_payload_bytes=max_payload_bytes,
)
async def broadcast(
@@ -597,7 +599,12 @@ def register_ws_namespace(
)
if security_errors:
result["results"] = security_errors + result.get("results", [])
- return result
+ return manager.constrain_ack_response(
+ NAMESPACE,
+ sid,
+ event,
+ result,
+ )
# All handlers failed security or no manager — return collected errors
if not passing_handlers:
diff --git a/helpers/ws.py.dox.md b/helpers/ws.py.dox.md
index 5eb7279f6..692a817c9 100644
--- a/helpers/ws.py.dox.md
+++ b/helpers/ws.py.dox.md
@@ -43,6 +43,11 @@
- `WsHandler` defines `requires_csrf(...)`.
- `WsHandler` defines `requires_api_key(...)`.
- `WsHandler` defines `requires_loopback(...)`.
+- `WsHandler.emit_to(..., max_payload_bytes=...)` delegates optional serialized-size enforcement to `WsManager` so protocol handlers can apply negotiated peer ceilings without duplicating envelope logic.
+- The namespace wildcard dispatcher sends manager-produced handler responses
+ through `WsManager.constrain_ack_response(...)` after security results are
+ merged, so acknowledgements obey the same negotiated per-peer ceiling as
+ ordinary emitted events.
- Observed side-effect areas: filesystem reads, filesystem deletion, network calls, WebSocket state, plugin state, settings/state persistence, secret handling.
- Imported dependency areas include: `abc`, `dataclasses`, `flask`, `helpers`, `helpers.errors`, `helpers.network`, `helpers.print_style`, `os`, `pathlib`, `socketio`, `threading`, `typing`, `urllib.parse`, `uuid`.
diff --git a/helpers/ws_limits.py b/helpers/ws_limits.py
new file mode 100644
index 000000000..cebb92d44
--- /dev/null
+++ b/helpers/ws_limits.py
@@ -0,0 +1,35 @@
+"""Shared WebSocket payload limits for Agent Zero transports."""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+
+DEFAULT_WS_MAX_PAYLOAD_BYTES = 50 * 1024 * 1024
+LEGACY_WS_MAX_PAYLOAD_BYTES = 4 * 1024 * 1024
+
+
+def _positive_int_env(name: str, default: int) -> int:
+ try:
+ value = int(os.getenv(name, str(default)))
+ except (TypeError, ValueError):
+ return default
+ return value if value > 0 else default
+
+
+A0_WS_MAX_PAYLOAD_BYTES = _positive_int_env(
+ "A0_WS_MAX_PAYLOAD_BYTES",
+ DEFAULT_WS_MAX_PAYLOAD_BYTES,
+)
+
+
+def peer_ws_max_payload_bytes(value: Any) -> int:
+ """Return a safe outbound limit for a peer capability value."""
+ try:
+ limit = int(value)
+ except (TypeError, ValueError):
+ return min(LEGACY_WS_MAX_PAYLOAD_BYTES, A0_WS_MAX_PAYLOAD_BYTES)
+ if limit <= 0:
+ return min(LEGACY_WS_MAX_PAYLOAD_BYTES, A0_WS_MAX_PAYLOAD_BYTES)
+ return min(limit, A0_WS_MAX_PAYLOAD_BYTES)
diff --git a/helpers/ws_limits.py.dox.md b/helpers/ws_limits.py.dox.md
new file mode 100644
index 000000000..e59999b4b
--- /dev/null
+++ b/helpers/ws_limits.py.dox.md
@@ -0,0 +1,28 @@
+# ws_limits.py DOX
+
+## Purpose
+
+- Own the effective WebSocket payload ceiling shared by Uvicorn, Engine.IO, and connector protocol negotiation.
+
+## Ownership
+
+- `A0_WS_MAX_PAYLOAD_BYTES` reads the positive `A0_WS_MAX_PAYLOAD_BYTES` environment override once at process startup and otherwise defaults to 50 MiB.
+- `LEGACY_WS_MAX_PAYLOAD_BYTES` is the conservative 4 MiB receive floor used when a connector peer does not advertise a limit.
+- `peer_ws_max_payload_bytes()` validates peer declarations and never permits outbound payloads above the local transport ceiling.
+
+## Runtime Contracts
+
+- Transport configuration and connector capability responses must source their limit from this module.
+- Invalid, missing, zero, or negative peer limits degrade to the legacy floor rather than risking a transport disconnect.
+
+## Work Guidance
+
+- Keep this module dependency-light so startup and bundled plugins can import it safely.
+
+## Verification
+
+- Run `pytest tests/test_run_ui_config.py tests/test_ws_manager.py` and connector plugin protocol tests after changing these limits.
+
+## Child DOX Index
+
+No child DOX files.
diff --git a/helpers/ws_manager.py b/helpers/ws_manager.py
index 70e5d5b95..133c9d591 100644
--- a/helpers/ws_manager.py
+++ b/helpers/ws_manager.py
@@ -35,6 +35,62 @@ _RESERVED_EVENT_NAMES: set[str] = {
}
+class WsPayloadTooLargeError(ValueError):
+ """Raised before dispatch when a serialized Socket.IO event exceeds its peer limit."""
+
+ def __init__(self, event_type: str, actual_bytes: int, limit_bytes: int) -> None:
+ self.event_type = event_type
+ self.actual_bytes = actual_bytes
+ self.limit_bytes = limit_bytes
+ super().__init__(
+ f"PAYLOAD_TOO_LARGE: {event_type} serializes to {actual_bytes} bytes; "
+ f"the peer limit is {limit_bytes} bytes. Use the HTTP bulk-transfer path."
+ )
+
+ def details(self) -> dict[str, Any]:
+ return {
+ "type": "payload_too_large",
+ "event": self.event_type,
+ "actual_bytes": self.actual_bytes,
+ "limit_bytes": self.limit_bytes,
+ "alternative": "http_bulk_transfer",
+ }
+
+
+def socketio_event_size(
+ event_type: str,
+ payload: dict[str, Any],
+ *,
+ namespace: str,
+) -> int:
+ """Return the encoded Engine.IO message size for one Socket.IO event."""
+ encoded = socketio.packet.Packet(
+ socketio.packet.EVENT,
+ data=[event_type, payload],
+ namespace=namespace,
+ ).encode()
+ parts = encoded if isinstance(encoded, list) else [encoded]
+ return sum(
+ len(part.encode("utf-8")) if isinstance(part, str) else len(part)
+ for part in parts
+ ) + len(parts)
+
+
+def socketio_ack_size(payload: dict[str, Any], *, namespace: str) -> int:
+ """Return a conservative encoded Engine.IO size for one Socket.IO ACK."""
+ encoded = socketio.packet.Packet(
+ socketio.packet.ACK,
+ data=[payload],
+ namespace=namespace,
+ id=2**63 - 1,
+ ).encode()
+ parts = encoded if isinstance(encoded, list) else [encoded]
+ return sum(
+ len(part.encode("utf-8")) if isinstance(part, str) else len(part)
+ for part in parts
+ ) + len(parts)
+
+
# WsResult – standardized handler return value
class WsResult:
@@ -221,6 +277,7 @@ class ConnectionInfo:
sid: str
connected_at: datetime = field(default_factory=_utcnow)
last_activity: datetime = field(default_factory=_utcnow)
+ max_payload_bytes: int | None = None
@dataclass
@@ -617,6 +674,54 @@ class WsManager:
)
return response
+ def set_peer_max_payload_bytes(
+ self,
+ namespace: str,
+ sid: str,
+ max_payload_bytes: int,
+ ) -> None:
+ if max_payload_bytes <= 0:
+ raise ValueError("max_payload_bytes must be positive")
+ identity: ConnectionIdentity = (namespace, sid)
+ with self.lock:
+ info = self.connections.get(identity)
+ if info is None:
+ raise ConnectionNotFoundError(sid, namespace=namespace)
+ info.max_payload_bytes = max_payload_bytes
+
+ def constrain_ack_response(
+ self,
+ namespace: str,
+ sid: str,
+ event_type: str,
+ response: dict[str, Any],
+ ) -> dict[str, Any]:
+ with self.lock:
+ info = self.connections.get((namespace, sid))
+ limit = info.max_payload_bytes if info is not None else None
+ if limit is None:
+ return response
+
+ actual_bytes = socketio_ack_size(response, namespace=namespace)
+ if actual_bytes <= limit:
+ return response
+
+ exc = WsPayloadTooLargeError(event_type, actual_bytes, limit)
+ correlation_id = response.get("correlationId")
+ return {
+ "correlationId": correlation_id,
+ "results": [
+ self._build_error_result(
+ code="PAYLOAD_TOO_LARGE",
+ message=str(exc),
+ details=exc.details(),
+ correlation_id=(
+ correlation_id if isinstance(correlation_id, str) else None
+ ),
+ )
+ ],
+ }
+
def _collect_results(
self,
executions: list[_HandlerExecution],
@@ -640,6 +745,18 @@ class WsManager:
duration_ms = execution.duration_ms
if isinstance(value, Exception):
+ if isinstance(value, WsPayloadTooLargeError):
+ results.append(
+ self._build_error_result(
+ handler_id=handler.identifier,
+ code="PAYLOAD_TOO_LARGE",
+ message=str(value),
+ details=value.details(),
+ correlation_id=correlation_id,
+ duration_ms=duration_ms,
+ )
+ )
+ continue
PrintStyle.error(
f"Error in handler {handler.identifier} for '{event_type}' "
f"(correlation {correlation_id}): {value}"
@@ -1208,15 +1325,37 @@ class WsManager:
handler_id: str | None = None,
correlation_id: str | None = None,
diagnostic: bool = False,
+ max_payload_bytes: int | None = None,
) -> None:
envelope = self._wrap_envelope(
handler_id,
data,
correlation_id=correlation_id,
)
+ identity: ConnectionIdentity = (namespace, sid)
+ with self.lock:
+ info = self.connections.get(identity)
+ connection_limit = info.max_payload_bytes if info is not None else None
+ limits = [
+ limit
+ for limit in (max_payload_bytes, connection_limit)
+ if limit is not None
+ ]
+ effective_limit = min(limits) if limits else None
+ if effective_limit is not None:
+ actual_bytes = socketio_event_size(
+ event_type,
+ envelope,
+ namespace=namespace,
+ )
+ if actual_bytes > effective_limit:
+ raise WsPayloadTooLargeError(
+ event_type,
+ actual_bytes,
+ effective_limit,
+ )
delivered = False
buffered = False
- identity: ConnectionIdentity = (namespace, sid)
with self.lock:
connected = identity in self.connections
@@ -1302,27 +1441,44 @@ class WsManager:
excluded = self._normalize_sid_filter(exclude_sids)
targets: list[str] = []
+ target_limits: dict[str, int | None] = {}
with self.lock:
- current_identities = list(self.connections.keys())
- for conn_identity in current_identities:
+ current_connections = list(self.connections.items())
+ for conn_identity, info in current_connections:
if conn_identity[0] != namespace:
continue
sid = conn_identity[1]
if sid in excluded:
continue
targets.append(sid)
+ target_limits[sid] = info.max_payload_bytes
+ rejected: list[WsPayloadTooLargeError] = []
if targets:
envelope = self._wrap_envelope(
handler_id,
data,
correlation_id=correlation_id,
)
+ actual_bytes = socketio_event_size(
+ event_type,
+ envelope,
+ namespace=namespace,
+ )
+ deliverable: list[str] = []
+ for sid in targets:
+ limit = target_limits[sid]
+ if limit is not None and actual_bytes > limit:
+ rejected.append(
+ WsPayloadTooLargeError(event_type, actual_bytes, limit)
+ )
+ else:
+ deliverable.append(sid)
coros = [
self._run_on_dispatcher_loop(
self.socketio.emit(event_type, envelope, to=sid, namespace=namespace)
)
- for sid in targets
+ for sid in deliverable
]
await asyncio.gather(*coros)
@@ -1335,12 +1491,15 @@ class WsManager:
"namespace": namespace,
"targets": targets[:10],
"targetCount": len(targets),
+ "rejectedCount": len(rejected),
"correlationId": correlation_id,
"handlerId": handler_id or self._identifier,
"timestamp": self._timestamp(),
"payloadSummary": self._summarize_payload(data),
}
)
+ if rejected:
+ raise rejected[0]
async def _run_lifecycle(
self, namespace: str, fn: Callable[[WsHandler], Any]
@@ -1431,12 +1590,12 @@ class WsManager:
handler_id: str | None = None,
code: str,
message: str,
- details: str | None = None,
+ details: Any | None = None,
correlation_id: str | None = None,
duration_ms: float | None = None,
) -> dict[str, Any]:
error_payload = {"code": code, "error": message}
- if details:
+ if details is not None:
error_payload["details"] = details
result: dict[str, Any] = {
"handlerId": handler_id or self._identifier,
diff --git a/helpers/ws_manager.py.dox.md b/helpers/ws_manager.py.dox.md
index 3d8f6da61..a01bd4335 100644
--- a/helpers/ws_manager.py.dox.md
+++ b/helpers/ws_manager.py.dox.md
@@ -11,6 +11,7 @@
- `ws_manager.py` owns the runtime implementation.
- `ws_manager.py.dox.md` owns durable notes about responsibilities, contracts, side effects, and verification for that implementation.
- Classes:
+- `WsPayloadTooLargeError` carries the event name, serialized byte count, peer limit, and structured HTTP-alternative details for pre-dispatch rejection.
- `WsResult` (no explicit base class)
- `ok(cls, data: dict[str, Any] | None=..., correlation_id: str | None=..., duration_ms: float | None=...) -> 'WsResult'`
- `error(cls, code: str, message: str, details: Any | None=..., correlation_id: str | None=..., duration_ms: float | None=...) -> 'WsResult'`
@@ -28,6 +29,8 @@
- `async handle_disconnect(self, namespace: str, sid: str) -> None`
- `async route_event(self, namespace: str, event_type: str, data: dict[str, Any], sid: str, ack: Optional[Callable[[Any], None]]=..., include_handlers: Set[str] | None=..., exclude_handlers: Set[str] | None=..., allow_exclude: bool=..., handler_id: str | None=...) -> dict[str, Any]`
- Top-level functions:
+- `socketio_event_size(event_type, payload, namespace) -> int`: Measure the complete encoded Socket.IO/Engine.IO event, including the manager envelope.
+- `socketio_ack_size(payload, namespace) -> int`: Conservatively measure the complete Socket.IO/Engine.IO acknowledgement using the widest callback identifier.
- `validate_event_type(event_type: str) -> str`: Validate an event name: must be lowercase_snake_case and not reserved.
- `async send_data(event_type: str, data: dict[str, Any], endpoint_name: str=..., connection_id: str | None=...) -> None`: Convenience wrapper around :pymeth:`WsManager.send_data`.
- `_utcnow() -> datetime`
@@ -38,6 +41,16 @@
## Runtime Contracts
- Helper modules own reusable framework APIs and must preserve public callers unless all callers, tests, and docs are updated together.
+- `WsManager.emit_to(..., max_payload_bytes=...)` rejects an oversized encoded event before dispatch or buffering. Callers that negotiate peer limits should pass the peer's effective receive ceiling and turn `WsPayloadTooLargeError` into their own structured application error.
+- `WsManager.set_peer_max_payload_bytes(...)` stores an optional limit on the
+ live connection. `constrain_ack_response(...)` replaces an oversized handler
+ acknowledgement with one small structured `PAYLOAD_TOO_LARGE` error before
+ the Socket.IO adapter serializes it.
+- A live connection's stored limit applies automatically to `emit_to` and
+ `broadcast`. Broadcast still reaches capable peers, skips peers for which the
+ encoded envelope is oversized, and raises `WsPayloadTooLargeError` so an
+ acknowledged caller receives a structured failure instead of disconnecting a
+ constrained peer.
- Update this file whenever public functions, classes, persistence behavior, path/security assumptions, side effects, or cross-module contracts change.
- Observed side-effect areas: filesystem deletion, network calls, WebSocket state, settings/state persistence, scheduler state.
- Imported dependency areas include: `__future__`, `asyncio`, `collections`, `dataclasses`, `datetime`, `helpers`, `helpers.defer`, `helpers.print_style`, `helpers.ws`, `os`, `re`, `socketio`, `threading`, `time`, `typing`, `uuid`.
diff --git a/plugins/_a0_connector/api/v1/capabilities.py b/plugins/_a0_connector/api/v1/capabilities.py
index 4c9e5e035..7e219b272 100644
--- a/plugins/_a0_connector/api/v1/capabilities.py
+++ b/plugins/_a0_connector/api/v1/capabilities.py
@@ -7,6 +7,8 @@ import sys
from helpers.api import Request, Response
import plugins._a0_connector.api.v1.base as connector_base
from plugins._a0_connector.helpers.version import agent_zero_version
+from helpers.ws_limits import A0_WS_MAX_PAYLOAD_BYTES
+from plugins._a0_connector.helpers.ws_runtime import TRANSFER_PROTOCOL_VERSION
_BASE_FEATURES = [
@@ -88,6 +90,10 @@ class Capabilities(connector_base.PublicConnectorApiHandler):
"auth_required": bool(login.is_login_required()),
"transports": ["http", "websocket"],
"streaming": True,
+ "capabilities": {
+ "ws_max_payload_bytes": A0_WS_MAX_PAYLOAD_BYTES,
+ "transfer_protocol": TRANSFER_PROTOCOL_VERSION,
+ },
"websocket_namespace": "/ws",
"websocket_handlers": ["plugins/_a0_connector/ws_connector"],
"attachments": {
diff --git a/plugins/_a0_connector/api/v1/chat_delete.py b/plugins/_a0_connector/api/v1/chat_delete.py
index aef54f7f7..873ba7de3 100644
--- a/plugins/_a0_connector/api/v1/chat_delete.py
+++ b/plugins/_a0_connector/api/v1/chat_delete.py
@@ -3,6 +3,7 @@ from __future__ import annotations
from helpers.api import Request, Response
import plugins._a0_connector.api.v1.base as connector_base
+from plugins._a0_connector.helpers.ws_runtime import abort_transfers_for_context
class ChatDelete(connector_base.ProtectedConnectorApiHandler):
@@ -27,6 +28,10 @@ class ChatDelete(connector_base.ProtectedConnectorApiHandler):
)
try:
+ await abort_transfers_for_context(
+ context_id,
+ reason="chat deleted during transfer",
+ )
handler = RemoveChat(self.app, self.thread_lock)
await handler.process({"context": context_id}, request)
except Exception as exc:
diff --git a/plugins/_a0_connector/api/v1/chat_reset.py b/plugins/_a0_connector/api/v1/chat_reset.py
index 8e626775c..764398e87 100644
--- a/plugins/_a0_connector/api/v1/chat_reset.py
+++ b/plugins/_a0_connector/api/v1/chat_reset.py
@@ -3,6 +3,7 @@ from __future__ import annotations
from helpers.api import Request, Response
import plugins._a0_connector.api.v1.base as connector_base
+from plugins._a0_connector.helpers.ws_runtime import abort_transfers_for_context
class ChatReset(connector_base.ProtectedConnectorApiHandler):
@@ -26,6 +27,10 @@ class ChatReset(connector_base.ProtectedConnectorApiHandler):
mimetype="application/json",
)
+ await abort_transfers_for_context(
+ context_id,
+ reason="chat reset during transfer",
+ )
handler = Reset(self.app, self.thread_lock)
await handler.process({"context": context_id}, request)
return {"context_id": context_id, "status": "reset"}
diff --git a/plugins/_a0_connector/api/v1/launcher_gateway_control.py b/plugins/_a0_connector/api/v1/launcher_gateway_control.py
index e1e95074a..f1a6fa7bd 100644
--- a/plugins/_a0_connector/api/v1/launcher_gateway_control.py
+++ b/plugins/_a0_connector/api/v1/launcher_gateway_control.py
@@ -5,12 +5,17 @@ import asyncio
import uuid
from helpers.api import Request, Response
-from helpers.ws_manager import ConnectionNotFoundError, get_shared_ws_manager
+from helpers.ws_manager import (
+ ConnectionNotFoundError,
+ WsPayloadTooLargeError,
+ get_shared_ws_manager,
+)
import plugins._a0_connector.api.v1.base as connector_base
from plugins._a0_connector.helpers.ws_runtime import (
active_launcher_gateway_sid,
clear_pending_gateway_control,
+ emit_connector_event,
launcher_gateway_status,
store_pending_gateway_control,
)
@@ -71,14 +76,16 @@ class LauncherGatewayControl(connector_base.ProtectedConnectorApiHandler):
loop=loop,
)
try:
- await get_shared_ws_manager().emit_to(
- "/ws",
+ await emit_connector_event(
sid,
_CONTROL_EVENT,
payload,
handler_id=f"{self.__class__.__module__}.{self.__class__.__name__}",
+ manager=get_shared_ws_manager(),
)
result = await asyncio.wait_for(future, timeout=_CONTROL_TIMEOUT_SECONDS)
+ except WsPayloadTooLargeError as exc:
+ return Response(str(exc), status=413)
except ConnectionNotFoundError:
return Response("Launcher host gateway disconnected", status=409)
except asyncio.TimeoutError:
diff --git a/plugins/_a0_connector/api/v1/pause.py b/plugins/_a0_connector/api/v1/pause.py
index dae48ddfd..322cf14bf 100644
--- a/plugins/_a0_connector/api/v1/pause.py
+++ b/plugins/_a0_connector/api/v1/pause.py
@@ -3,6 +3,7 @@ from __future__ import annotations
from helpers.api import Request, Response
import plugins._a0_connector.api.v1.base as connector_base
+from plugins._a0_connector.helpers.ws_runtime import abort_transfers_for_context
class Pause(connector_base.ProtectedConnectorApiHandler):
@@ -39,6 +40,11 @@ class Pause(connector_base.ProtectedConnectorApiHandler):
)
context.paused = paused
+ if paused:
+ await abort_transfers_for_context(
+ context_id,
+ reason="chat paused during transfer",
+ )
return {
"ok": True,
"context_id": context_id,
diff --git a/plugins/_a0_connector/api/ws_connector.py b/plugins/_a0_connector/api/ws_connector.py
index 148ef5ef1..707fd436e 100644
--- a/plugins/_a0_connector/api/ws_connector.py
+++ b/plugins/_a0_connector/api/ws_connector.py
@@ -6,7 +6,8 @@ from typing import TYPE_CHECKING, Any, ClassVar
from helpers.print_style import PrintStyle
from helpers.ws import WsHandler
-from helpers.ws_manager import WsResult
+from helpers.ws_limits import A0_WS_MAX_PAYLOAD_BYTES
+from helpers.ws_manager import WsPayloadTooLargeError, WsResult
from plugins._a0_connector.helpers.exec_config import build_exec_config
from plugins._a0_connector.helpers.event_bridge import (
@@ -15,6 +16,9 @@ from plugins._a0_connector.helpers.event_bridge import (
)
from plugins._a0_connector.helpers.version import agent_zero_version
from plugins._a0_connector.helpers.ws_runtime import (
+ TRANSFER_PROTOCOL_VERSION,
+ abort_incoming_transfer,
+ append_incoming_transfer,
clear_remote_tree_snapshot,
clear_sid_launcher_gateway_metadata,
clear_sid_host_browser_metadata,
@@ -27,7 +31,9 @@ from plugins._a0_connector.helpers.ws_runtime import (
fail_pending_exec_ops_for_sid,
fail_pending_file_ops_for_sid,
fail_pending_gateway_controls_for_sid,
+ finish_incoming_transfer,
host_browser_metadata_for_sid,
+ incoming_transfer_metadata,
register_sid,
remote_exec_metadata_for_sid,
remote_file_metadata_for_sid,
@@ -37,16 +43,19 @@ from plugins._a0_connector.helpers.ws_runtime import (
resolve_pending_exec_op,
resolve_pending_file_op,
store_remote_tree_snapshot,
+ store_sid_connector_capabilities,
store_sid_launcher_gateway_metadata,
store_sid_host_browser_metadata,
store_sid_computer_use_metadata,
store_sid_remote_exec_metadata,
store_sid_remote_file_metadata,
+ start_incoming_transfer,
subscribe_sid_to_context,
subscribed_contexts_for_sid,
subscribed_sids_for_context,
unsubscribe_sid_from_context,
unregister_sid,
+ ws_max_payload_bytes_for_sid,
)
if TYPE_CHECKING:
@@ -92,6 +101,11 @@ class WsConnector(WsHandler):
async def on_connect(self, sid: str) -> None:
register_sid(sid)
+ self.manager.set_peer_max_payload_bytes(
+ self._namespace,
+ sid,
+ ws_max_payload_bytes_for_sid(sid),
+ )
PrintStyle.debug(f"[a0-connector] /ws connected: {sid}")
async def on_disconnect(self, sid: str) -> None:
@@ -126,6 +140,43 @@ class WsConnector(WsHandler):
clear_sid_launcher_gateway_metadata(sid)
PrintStyle.debug(f"[a0-connector] /ws disconnected: {sid}")
+ async def emit_to(
+ self,
+ sid: str,
+ event: str,
+ data: dict,
+ *,
+ correlation_id: str | None = None,
+ ) -> None:
+ limit = ws_max_payload_bytes_for_sid(sid)
+ try:
+ await super().emit_to(
+ sid,
+ event,
+ data,
+ correlation_id=correlation_id,
+ max_payload_bytes=limit,
+ )
+ except WsPayloadTooLargeError as exc:
+ if event == "connector_error":
+ raise
+ error_payload: dict[str, Any] = {
+ "code": "PAYLOAD_TOO_LARGE",
+ "message": str(exc),
+ "details": exc.details(),
+ "rejected_event": event,
+ }
+ context_id = str(data.get("context_id") or "").strip()
+ if context_id:
+ error_payload["context_id"] = context_id
+ await super().emit_to(
+ sid,
+ "connector_error",
+ error_payload,
+ correlation_id=correlation_id,
+ max_payload_bytes=limit,
+ )
+
async def process(
self,
event: str,
@@ -133,12 +184,18 @@ class WsConnector(WsHandler):
sid: str,
) -> dict[str, Any] | WsResult | None:
if event == "connector_hello":
+ limit = store_sid_connector_capabilities(sid, data.get("capabilities"))
+ self.manager.set_peer_max_payload_bytes(self._namespace, sid, limit)
self._store_remote_tool_metadata(data, sid)
self._associate_declared_context(data, sid)
return {
"protocol": PROTOCOL_VERSION,
"agent_zero_version": agent_zero_version(),
"features": WS_FEATURES,
+ "capabilities": {
+ "ws_max_payload_bytes": A0_WS_MAX_PAYLOAD_BYTES,
+ "transfer_protocol": TRANSFER_PROTOCOL_VERSION,
+ },
"exec_config": build_exec_config(),
"remote_tools": self._remote_tool_state(sid),
}
@@ -161,6 +218,14 @@ class WsConnector(WsHandler):
if event == "connector_message_queue_send":
return await self._handle_message_queue_send(data, sid)
+ if event in {
+ "connector_transfer_start",
+ "connector_transfer_chunk",
+ "connector_transfer_end",
+ "connector_transfer_abort",
+ }:
+ return await self._handle_transfer_event(event, data, sid)
+
if event == "connector_file_op_result":
return self._handle_file_op_result(data, sid)
@@ -188,6 +253,68 @@ class WsConnector(WsHandler):
return None
+ async def _handle_transfer_event(
+ self,
+ event: str,
+ data: dict[str, Any],
+ sid: str,
+ ) -> dict[str, Any]:
+ transfer_id = str(data.get("transfer_id") or "")
+ if event == "connector_transfer_start":
+ error = start_incoming_transfer(
+ sid,
+ data,
+ max_bytes=A0_WS_MAX_PAYLOAD_BYTES,
+ )
+ elif event == "connector_transfer_chunk":
+ error = append_incoming_transfer(sid, data)
+ elif event == "connector_transfer_abort":
+ accepted = abort_incoming_transfer(sid, data)
+ return {"transfer_id": transfer_id, "accepted": accepted}
+ else:
+ kind, result, error = finish_incoming_transfer(sid, data)
+ if not error and kind is not None and result is not None:
+ response = self._handle_transferred_result(kind, result, sid)
+ return {
+ "transfer_id": transfer_id,
+ "accepted": bool(response.get("accepted")),
+ "kind": kind,
+ }
+
+ if error:
+ transfer_metadata = incoming_transfer_metadata(sid, transfer_id)
+ abort_incoming_transfer(sid, data, reason=error)
+ await self.emit_to(
+ sid,
+ "connector_transfer_abort",
+ {
+ "transfer_id": transfer_id,
+ "op_id": transfer_metadata.get("op_id") or data.get("op_id"),
+ "kind": transfer_metadata.get("kind") or data.get("kind"),
+ "reason": error[:512],
+ },
+ )
+ return {"transfer_id": transfer_id, "accepted": False, "error": error}
+ return {"transfer_id": transfer_id, "accepted": True}
+
+ def _handle_transferred_result(
+ self,
+ kind: str,
+ data: dict[str, Any],
+ sid: str,
+ ) -> dict[str, Any]:
+ handlers = {
+ "connector_file_op_result": self._handle_file_op_result,
+ "connector_exec_op_result": self._handle_exec_op_result,
+ "connector_computer_use_op_result": self._handle_computer_use_op_result,
+ "connector_browser_op_result": self._handle_browser_op_result,
+ "connector_gateway_control_result": self._handle_gateway_control_result,
+ }
+ handler = handlers.get(kind)
+ if handler is None:
+ return {"accepted": False}
+ return handler(data, sid)
+
def _store_remote_tool_metadata(self, data: dict[str, Any], sid: str) -> None:
computer_use = data.get("computer_use")
host_browser = data.get("host_browser")
diff --git a/plugins/_a0_connector/helpers/ws_runtime.py b/plugins/_a0_connector/helpers/ws_runtime.py
index 4126c5f2d..715dcc890 100644
--- a/plugins/_a0_connector/helpers/ws_runtime.py
+++ b/plugins/_a0_connector/helpers/ws_runtime.py
@@ -3,13 +3,22 @@ from __future__ import annotations
import asyncio
import base64
import binascii
+import contextlib
import copy
+import hashlib
import json
+import os
+from pathlib import Path
+import tempfile
import threading
import time
-from dataclasses import dataclass, field
+import uuid
+from dataclasses import dataclass
from typing import Any
+from helpers.ws_limits import peer_ws_max_payload_bytes
+from helpers.ws_manager import WsPayloadTooLargeError, get_shared_ws_manager
+
@dataclass
class PendingFileOperation:
@@ -17,8 +26,51 @@ class PendingFileOperation:
loop: asyncio.AbstractEventLoop
future: asyncio.Future[dict[str, Any]]
context_id: str | None = None
- chunk_count: int | None = None
- chunks: dict[int, bytes] = field(default_factory=dict)
+
+
+TRANSFER_PROTOCOL_VERSION = 1
+TRANSFER_CHUNK_BYTES = 64 * 1024
+TRANSFER_SPOOL_THRESHOLD_BYTES = 1024 * 1024
+TRANSFER_SINGLE_FRAME_BYTES = 1024 * 1024
+TRANSFER_IDLE_TIMEOUT_SECONDS = 30.0
+MAX_INCOMING_TRANSFERS_PER_SID = 4
+_TRANSFER_ENCODED_CHUNK_MAX = ((TRANSFER_CHUNK_BYTES + 2) // 3) * 4
+_TRANSFER_RESULT_EVENTS = {
+ "connector_file_op_result",
+ "connector_exec_op_result",
+ "connector_computer_use_op_result",
+ "connector_browser_op_result",
+ "connector_gateway_control_result",
+}
+
+
+@dataclass
+class IncomingTransfer:
+ transfer_id: str
+ sid: str
+ kind: str
+ op_id: str
+ context_id: str | None
+ total_bytes: int
+ sha256: str
+ digest: Any
+ updated_at: float
+ buffer: bytearray | None = None
+ temp_path: Path | None = None
+ next_index: int = 0
+ received_bytes: int = 0
+ timeout: threading.Timer | None = None
+
+
+@dataclass
+class OutgoingTransfer:
+ transfer_id: str
+ sid: str
+ kind: str
+ op_id: str
+ context_id: str | None
+ cancel_reason: str = ""
+ abort_sent: bool = False
@dataclass
@@ -134,6 +186,10 @@ _sid_host_browser_metadata: dict[str, HostBrowserMetadata] = {}
_sid_remote_file_metadata: dict[str, RemoteFileMetadata] = {}
_sid_remote_exec_metadata: dict[str, RemoteExecMetadata] = {}
_sid_launcher_gateway_metadata: dict[str, LauncherGatewayMetadata] = {}
+_sid_ws_max_payload_bytes: dict[str, int] = {}
+_sid_transfer_protocol: dict[str, int] = {}
+_incoming_transfers: dict[str, IncomingTransfer] = {}
+_outgoing_transfers: dict[str, OutgoingTransfer] = {}
_replaced_gateway_sids: set[str] = set()
_state_lock = threading.RLock()
@@ -142,9 +198,16 @@ def register_sid(sid: str) -> None:
with _state_lock:
_replaced_gateway_sids.discard(sid)
_sid_contexts.setdefault(sid, set())
+ _sid_ws_max_payload_bytes.setdefault(
+ sid,
+ peer_ws_max_payload_bytes(None),
+ )
+ _sid_transfer_protocol.setdefault(sid, 0)
def unregister_sid(sid: str) -> set[str]:
+ transfer_ids: list[str] = []
+ outgoing: list[OutgoingTransfer] = []
with _state_lock:
contexts = _sid_contexts.pop(sid, set())
_remote_tree_snapshots.pop(sid, None)
@@ -153,6 +216,22 @@ def unregister_sid(sid: str) -> set[str]:
_sid_remote_file_metadata.pop(sid, None)
_sid_remote_exec_metadata.pop(sid, None)
_sid_launcher_gateway_metadata.pop(sid, None)
+ _sid_ws_max_payload_bytes.pop(sid, None)
+ _sid_transfer_protocol.pop(sid, None)
+ transfer_ids = [
+ transfer_id
+ for transfer_id, transfer in _incoming_transfers.items()
+ if transfer.sid == sid
+ ]
+ outgoing = [
+ transfer
+ for transfer in _outgoing_transfers.values()
+ if transfer.sid == sid
+ ]
+ for transfer in outgoing:
+ transfer.cancel_reason = "connector disconnected during transfer"
+ transfer.abort_sent = True
+ _outgoing_transfers.pop(transfer.transfer_id, None)
_replaced_gateway_sids.discard(sid)
for context_id in contexts:
subscribers = _context_subscriptions.get(context_id)
@@ -161,6 +240,19 @@ def unregister_sid(sid: str) -> set[str]:
subscribers.discard(sid)
if not subscribers:
_context_subscriptions.pop(context_id, None)
+ for transfer_id in transfer_ids:
+ abort_incoming_transfer(
+ sid,
+ {"transfer_id": transfer_id},
+ reason="connector disconnected during transfer",
+ )
+ for transfer in outgoing:
+ _fail_transfer_pending(
+ transfer.kind,
+ transfer.op_id,
+ sid=sid,
+ error=transfer.cancel_reason,
+ )
return contexts
@@ -200,6 +292,200 @@ def connected_sids() -> set[str]:
return set(_sid_contexts.keys())
+def store_sid_connector_capabilities(sid: str, payload: Any) -> int:
+ capabilities = payload if isinstance(payload, dict) else {}
+ limit = peer_ws_max_payload_bytes(capabilities.get("ws_max_payload_bytes"))
+ try:
+ transfer_protocol = int(capabilities.get("transfer_protocol") or 0)
+ except (TypeError, ValueError):
+ transfer_protocol = 0
+ if transfer_protocol != TRANSFER_PROTOCOL_VERSION:
+ transfer_protocol = 0
+ with _state_lock:
+ _sid_ws_max_payload_bytes[sid] = limit
+ _sid_transfer_protocol[sid] = transfer_protocol
+ return limit
+
+
+def ws_max_payload_bytes_for_sid(sid: str) -> int:
+ with _state_lock:
+ return _sid_ws_max_payload_bytes.get(sid, peer_ws_max_payload_bytes(None))
+
+
+def transfer_protocol_for_sid(sid: str) -> int:
+ with _state_lock:
+ return _sid_transfer_protocol.get(sid, 0)
+
+
+async def emit_connector_event(
+ sid: str,
+ event: str,
+ payload: dict[str, Any],
+ *,
+ handler_id: str,
+ manager: Any | None = None,
+) -> None:
+ ws_manager = manager or get_shared_ws_manager()
+ limit = ws_max_payload_bytes_for_sid(sid)
+ raw = json.dumps(payload, ensure_ascii=False, separators=(",", ":")).encode("utf-8")
+ if len(raw) > TRANSFER_SINGLE_FRAME_BYTES:
+ if (
+ transfer_protocol_for_sid(sid) == TRANSFER_PROTOCOL_VERSION
+ and len(raw) <= limit
+ ):
+ await _emit_connector_transfer(
+ ws_manager,
+ sid=sid,
+ kind=event,
+ payload=payload,
+ raw=raw,
+ handler_id=handler_id,
+ limit=limit,
+ )
+ return
+ raise WsPayloadTooLargeError(
+ event,
+ len(raw),
+ min(limit, TRANSFER_SINGLE_FRAME_BYTES),
+ )
+ try:
+ await ws_manager.emit_to(
+ "/ws",
+ sid,
+ event,
+ payload,
+ handler_id=handler_id,
+ max_payload_bytes=limit,
+ )
+ return
+ except WsPayloadTooLargeError:
+ if transfer_protocol_for_sid(sid) != TRANSFER_PROTOCOL_VERSION:
+ raise
+
+ if len(raw) > limit:
+ raise WsPayloadTooLargeError(event, len(raw), limit)
+ await _emit_connector_transfer(
+ ws_manager,
+ sid=sid,
+ kind=event,
+ payload=payload,
+ raw=raw,
+ handler_id=handler_id,
+ limit=limit,
+ )
+
+
+async def _emit_connector_transfer(
+ manager: Any,
+ *,
+ sid: str,
+ kind: str,
+ payload: dict[str, Any],
+ raw: bytes,
+ handler_id: str,
+ limit: int,
+) -> None:
+ transfer_id = uuid.uuid4().hex
+ op_id = str(payload.get("op_id") or payload.get("request_id") or "")
+ context_id = _transfer_context_id(payload.get("context_id"))
+ state = OutgoingTransfer(
+ transfer_id=transfer_id,
+ sid=sid,
+ kind=kind,
+ op_id=op_id,
+ context_id=context_id,
+ )
+ with _state_lock:
+ _outgoing_transfers[transfer_id] = state
+ common = {
+ "handler_id": handler_id,
+ "max_payload_bytes": limit,
+ }
+ try:
+ start = {
+ "transfer_id": transfer_id,
+ "op_id": op_id,
+ "kind": kind,
+ "total_bytes": len(raw),
+ "sha256": hashlib.sha256(raw).hexdigest(),
+ }
+ if context_id:
+ start["context_id"] = context_id
+ await manager.emit_to(
+ "/ws",
+ sid,
+ "connector_transfer_start",
+ start,
+ **common,
+ )
+ if state.cancel_reason:
+ return
+ for index, offset in enumerate(range(0, len(raw), TRANSFER_CHUNK_BYTES)):
+ if state.cancel_reason:
+ return
+ await manager.emit_to(
+ "/ws",
+ sid,
+ "connector_transfer_chunk",
+ {
+ "transfer_id": transfer_id,
+ "index": index,
+ "data": base64.b64encode(
+ raw[offset : offset + TRANSFER_CHUNK_BYTES]
+ ).decode("ascii"),
+ },
+ **common,
+ )
+ if state.cancel_reason:
+ return
+ await manager.emit_to(
+ "/ws",
+ sid,
+ "connector_transfer_end",
+ {"transfer_id": transfer_id},
+ **common,
+ )
+ except Exception as exc:
+ if not state.abort_sent:
+ state.abort_sent = True
+ with contextlib.suppress(Exception):
+ await manager.emit_to(
+ "/ws",
+ sid,
+ "connector_transfer_abort",
+ {
+ "transfer_id": transfer_id,
+ "op_id": op_id,
+ "kind": kind,
+ "reason": str(exc)[:512],
+ },
+ **common,
+ )
+ raise
+ finally:
+ with _state_lock:
+ _outgoing_transfers.pop(transfer_id, None)
+
+
+def payload_too_large_result(
+ exc: WsPayloadTooLargeError,
+ *,
+ op_id: str | None = None,
+ request_id: str | None = None,
+) -> dict[str, Any]:
+ result: dict[str, Any] = {
+ "ok": False,
+ "code": "PAYLOAD_TOO_LARGE",
+ "error": str(exc),
+ "details": exc.details(),
+ }
+ if op_id:
+ result["op_id"] = op_id
+ if request_id:
+ result["request_id"] = request_id
+ return result
+
+
_GATEWAY_STATES = {
"connecting",
"connected",
@@ -789,6 +1075,369 @@ def select_computer_use_target_sid(context_id: str) -> str | None:
return None
+def start_incoming_transfer(
+ sid: str,
+ payload: dict[str, Any],
+ *,
+ max_bytes: int,
+) -> str:
+ transfer_id = str(payload.get("transfer_id") or "")
+ kind = str(payload.get("kind") or "")
+ op_id = str(payload.get("op_id") or "")
+ raw_context_id = payload.get("context_id")
+ context_id = _transfer_context_id(raw_context_id)
+ try:
+ total_bytes = int(payload.get("total_bytes"))
+ except (TypeError, ValueError):
+ total_bytes = -1
+ sha256 = str(payload.get("sha256") or "").lower()
+
+ with _state_lock:
+ concurrent = sum(
+ 1 for transfer in _incoming_transfers.values() if transfer.sid == sid
+ )
+ duplicate = transfer_id in _incoming_transfers
+ if not transfer_id or len(transfer_id) > 128:
+ return "transfer_id must be a non-empty string up to 128 characters"
+ if duplicate:
+ return "transfer_id is already active"
+ if concurrent >= MAX_INCOMING_TRANSFERS_PER_SID:
+ return "too many concurrent transfers"
+ if kind not in _TRANSFER_RESULT_EVENTS:
+ return f"unsupported transfer kind: {kind or '<missing>'}"
+ if not op_id or len(op_id) > 256:
+ return "op_id must be a non-empty string up to 256 characters"
+ if raw_context_id is not None and (
+ not isinstance(raw_context_id, str)
+ or (str(raw_context_id).strip() and context_id is None)
+ ):
+ return "context_id must be a string up to 256 characters"
+ if total_bytes < 0:
+ return "total_bytes must be a non-negative integer"
+ if total_bytes > max_bytes:
+ return f"declared transfer size {total_bytes} exceeds the receiver limit {max_bytes}"
+ if len(sha256) != 64 or any(char not in "0123456789abcdef" for char in sha256):
+ return "sha256 must be a 64-character hexadecimal digest"
+
+ temp_path: Path | None = None
+ buffer: bytearray | None = bytearray()
+ if total_bytes > TRANSFER_SPOOL_THRESHOLD_BYTES:
+ fd, temp_name = tempfile.mkstemp(prefix="a0-transfer-")
+ os.close(fd)
+ temp_path = Path(temp_name)
+ buffer = None
+ transfer = IncomingTransfer(
+ transfer_id=transfer_id,
+ sid=sid,
+ kind=kind,
+ op_id=op_id,
+ context_id=_pending_transfer_context_id(kind, op_id, sid=sid) or context_id,
+ total_bytes=total_bytes,
+ sha256=sha256,
+ digest=hashlib.sha256(),
+ updated_at=time.monotonic(),
+ buffer=buffer,
+ temp_path=temp_path,
+ )
+ with _state_lock:
+ _incoming_transfers[transfer_id] = transfer
+ _arm_transfer_timeout(transfer)
+ return ""
+
+
+def append_incoming_transfer(
+ sid: str,
+ payload: dict[str, Any],
+) -> str:
+ transfer_id = str(payload.get("transfer_id") or "")
+ with _state_lock:
+ transfer = _incoming_transfers.get(transfer_id)
+ if transfer is None or transfer.sid != sid:
+ return "transfer is not active"
+ try:
+ index = int(payload.get("index"))
+ except (TypeError, ValueError):
+ return "chunk index must be an integer"
+ encoded = payload.get("data")
+ if not isinstance(encoded, str) or len(encoded) > _TRANSFER_ENCODED_CHUNK_MAX:
+ return "chunk data exceeds the 64 KiB limit"
+ try:
+ chunk = base64.b64decode(encoded.encode("ascii"), validate=True)
+ except (UnicodeEncodeError, binascii.Error):
+ return "chunk data is not valid base64"
+
+ with _state_lock:
+ transfer = _incoming_transfers.get(transfer_id)
+ if transfer is None or transfer.sid != sid:
+ return "transfer is not active"
+ expected_bytes = min(
+ TRANSFER_CHUNK_BYTES,
+ transfer.total_bytes - transfer.received_bytes,
+ )
+ if index != transfer.next_index:
+ return f"chunk index {index} arrived; expected {transfer.next_index}"
+ if len(chunk) != expected_bytes:
+ return f"chunk {index} has {len(chunk)} bytes; expected {expected_bytes}"
+ try:
+ if transfer.buffer is not None:
+ transfer.buffer.extend(chunk)
+ elif transfer.temp_path is not None:
+ with transfer.temp_path.open("ab") as handle:
+ handle.write(chunk)
+ except OSError as exc:
+ return f"could not spool transfer: {exc}"
+ transfer.digest.update(chunk)
+ transfer.received_bytes += len(chunk)
+ transfer.next_index += 1
+ transfer.updated_at = time.monotonic()
+ return ""
+
+
+def finish_incoming_transfer(
+ sid: str,
+ payload: dict[str, Any],
+) -> tuple[str | None, dict[str, Any] | None, str]:
+ transfer_id = str(payload.get("transfer_id") or "")
+ with _state_lock:
+ transfer = _incoming_transfers.get(transfer_id)
+ if transfer is None or transfer.sid != sid:
+ return None, None, "transfer is not active"
+ if transfer.received_bytes != transfer.total_bytes:
+ return (
+ None,
+ None,
+ f"transfer ended at {transfer.received_bytes} of {transfer.total_bytes} bytes",
+ )
+ if transfer.digest.hexdigest() != transfer.sha256:
+ return None, None, "transfer SHA-256 mismatch"
+ try:
+ raw = (
+ bytes(transfer.buffer)
+ if transfer.buffer is not None
+ else transfer.temp_path.read_bytes() if transfer.temp_path is not None else b""
+ )
+ result = json.loads(raw.decode("utf-8"))
+ if not isinstance(result, dict):
+ raise ValueError("decoded transfer is not a JSON object")
+ result_op_id = str(result.get("op_id") or result.get("request_id") or "")
+ if result_op_id != transfer.op_id:
+ raise ValueError("decoded operation id does not match transfer_start")
+ except Exception as exc:
+ return None, None, f"invalid transferred payload: {exc}"
+
+ kind = transfer.kind
+ _drop_incoming_transfer(transfer_id)
+ return kind, result, ""
+
+
+def abort_incoming_transfer(
+ sid: str,
+ payload: dict[str, Any],
+ *,
+ reason: str = "",
+) -> bool:
+ transfer_id = str(payload.get("transfer_id") or "")
+ with _state_lock:
+ transfer = _incoming_transfers.get(transfer_id)
+ outgoing = _outgoing_transfers.get(transfer_id)
+ if transfer is not None and transfer.sid != sid:
+ return False
+ if outgoing is not None and outgoing.sid != sid:
+ return False
+ active = transfer or outgoing
+ kind = active.kind if active is not None else str(payload.get("kind") or "")
+ op_id = active.op_id if active is not None else str(payload.get("op_id") or "")
+ dropped = _drop_incoming_transfer(transfer_id)
+ failure = reason or str(payload.get("reason") or "transfer aborted")
+ if outgoing is not None:
+ outgoing.cancel_reason = failure[:512]
+ outgoing.abort_sent = True
+ with _state_lock:
+ _outgoing_transfers.pop(transfer_id, None)
+ failed_pending = _fail_transfer_pending(kind, op_id, sid=sid, error=failure)
+ return dropped or outgoing is not None or failed_pending
+
+
+def incoming_transfer_metadata(
+ sid: str,
+ transfer_id: str,
+) -> dict[str, str]:
+ with _state_lock:
+ transfer = _incoming_transfers.get(transfer_id)
+ if transfer is None or transfer.sid != sid:
+ return {}
+ return {"op_id": transfer.op_id, "kind": transfer.kind}
+
+
+def abort_incoming_transfers_for_sid(sid: str, *, reason: str) -> None:
+ with _state_lock:
+ transfer_ids = [
+ transfer_id
+ for transfer_id, transfer in _incoming_transfers.items()
+ if transfer.sid == sid
+ ]
+ for transfer_id in transfer_ids:
+ abort_incoming_transfer(
+ sid,
+ {"transfer_id": transfer_id},
+ reason=reason,
+ )
+
+
+async def abort_transfers_for_context(
+ context_id: str,
+ *,
+ reason: str,
+ manager: Any | None = None,
+) -> int:
+ normalized_context_id = _transfer_context_id(context_id)
+ if normalized_context_id is None:
+ return 0
+ with _state_lock:
+ incoming = [
+ transfer
+ for transfer in _incoming_transfers.values()
+ if transfer.context_id == normalized_context_id
+ ]
+ outgoing = [
+ transfer
+ for transfer in _outgoing_transfers.values()
+ if transfer.context_id == normalized_context_id
+ ]
+ for transfer in outgoing:
+ transfer.cancel_reason = reason[:512]
+ transfer.abort_sent = True
+ _outgoing_transfers.pop(transfer.transfer_id, None)
+
+ for transfer in incoming:
+ _drop_incoming_transfer(transfer.transfer_id)
+ for transfer in [*incoming, *outgoing]:
+ _fail_transfer_pending(
+ transfer.kind,
+ transfer.op_id,
+ sid=transfer.sid,
+ error=reason,
+ )
+
+ if not incoming and not outgoing:
+ return 0
+ ws_manager = manager or get_shared_ws_manager()
+ for transfer in [*incoming, *outgoing]:
+ with contextlib.suppress(Exception):
+ await ws_manager.emit_to(
+ "/ws",
+ transfer.sid,
+ "connector_transfer_abort",
+ {
+ "transfer_id": transfer.transfer_id,
+ "op_id": transfer.op_id,
+ "kind": transfer.kind,
+ "reason": reason[:512],
+ },
+ handler_id="plugins/_a0_connector/api/ws_connector",
+ max_payload_bytes=ws_max_payload_bytes_for_sid(transfer.sid),
+ )
+ return len(incoming) + len(outgoing)
+
+
+def _transfer_context_id(value: Any) -> str | None:
+ if not isinstance(value, str):
+ return None
+ context_id = value.strip()
+ return context_id if context_id and len(context_id) <= 256 else None
+
+
+def _pending_transfer_context_id(
+ kind: str,
+ op_id: str,
+ *,
+ sid: str,
+) -> str | None:
+ pending_by_kind = {
+ "connector_file_op_result": _pending_file_ops,
+ "connector_exec_op_result": _pending_exec_ops,
+ "connector_computer_use_op_result": _pending_computer_use_ops,
+ "connector_browser_op_result": _pending_browser_ops,
+ }
+ with _state_lock:
+ pending = pending_by_kind.get(kind, {}).get(op_id)
+ if pending is None or pending.sid != sid:
+ return None
+ return _transfer_context_id(getattr(pending, "context_id", None))
+
+
+def _arm_transfer_timeout(transfer: IncomingTransfer, delay: float | None = None) -> None:
+ timeout = threading.Timer(
+ delay if delay is not None else TRANSFER_IDLE_TIMEOUT_SECONDS,
+ _expire_incoming_transfer,
+ args=(transfer.transfer_id,),
+ )
+ timeout.daemon = True
+ transfer.timeout = timeout
+ timeout.start()
+
+
+def _expire_incoming_transfer(transfer_id: str) -> None:
+ with _state_lock:
+ transfer = _incoming_transfers.get(transfer_id)
+ if transfer is None:
+ return
+ remaining = TRANSFER_IDLE_TIMEOUT_SECONDS - (
+ time.monotonic() - transfer.updated_at
+ )
+ if remaining > 0:
+ _arm_transfer_timeout(transfer, remaining)
+ return
+ sid = transfer.sid
+ kind = transfer.kind
+ op_id = transfer.op_id
+ _drop_incoming_transfer(transfer_id)
+ _fail_transfer_pending(
+ kind,
+ op_id,
+ sid=sid,
+ error=f"transfer idle timeout after {TRANSFER_IDLE_TIMEOUT_SECONDS:g} seconds",
+ )
+
+
+def _drop_incoming_transfer(transfer_id: str) -> bool:
+ with _state_lock:
+ transfer = _incoming_transfers.pop(transfer_id, None)
+ if transfer is None:
+ return False
+ if transfer.timeout is not None:
+ transfer.timeout.cancel()
+ if transfer.temp_path is not None:
+ with contextlib.suppress(FileNotFoundError):
+ transfer.temp_path.unlink()
+ return True
+
+
+def _fail_transfer_pending(
+ kind: str,
+ op_id: str,
+ *,
+ sid: str,
+ error: str,
+) -> bool:
+ pending_by_kind = {
+ "connector_file_op": _pending_file_ops,
+ "connector_file_op_result": _pending_file_ops,
+ "connector_exec_op": _pending_exec_ops,
+ "connector_exec_op_result": _pending_exec_ops,
+ "connector_computer_use_op": _pending_computer_use_ops,
+ "connector_computer_use_op_result": _pending_computer_use_ops,
+ "connector_browser_op": _pending_browser_ops,
+ "connector_browser_op_result": _pending_browser_ops,
+ "connector_gateway_control": _pending_gateway_controls,
+ "connector_gateway_control_result": _pending_gateway_controls,
+ }
+ pending = pending_by_kind.get(kind)
+ if pending is None or not op_id:
+ return False
+ return _fail_pending(pending, op_id, sid=sid, error=error)
+
+
def store_pending_file_op(
op_id: str,
*,
@@ -818,98 +1467,16 @@ def resolve_pending_file_op(
payload: dict[str, Any],
) -> bool:
if payload.get("chunked") is True:
- return _resolve_pending_file_chunk(op_id, sid=sid, payload=payload)
- return _resolve_pending(_pending_file_ops, op_id, sid=sid, payload=payload)
-
-
-def _resolve_pending_file_chunk(
- op_id: str,
- *,
- sid: str,
- payload: dict[str, Any],
-) -> bool:
- error = _validate_file_chunk_payload(payload)
- if error:
- return _fail_pending(
- _pending_file_ops,
- op_id,
- sid=sid,
- error=f"Invalid chunked file operation result: {error}",
- )
-
- chunk_index = int(payload["chunk_index"])
- chunk_count = int(payload["chunk_count"])
- encoded = str(payload.get("data") or "")
- try:
- chunk = base64.b64decode(encoded.encode("ascii"), validate=True)
- except (UnicodeEncodeError, binascii.Error) as exc:
return _fail_pending(
_pending_file_ops,
op_id,
sid=sid,
- error=f"Invalid chunked file operation result: {exc}",
+ error=(
+ "Legacy chunked file results are not supported. Upgrade the CLI so it "
+ "can negotiate transfer_protocol=1."
+ ),
)
-
- with _state_lock:
- pending = _pending_file_ops.get(op_id)
- if pending is None or pending.sid != sid:
- return False
-
- if pending.chunk_count is None:
- pending.chunk_count = chunk_count
- elif pending.chunk_count != chunk_count:
- _pending_file_ops.pop(op_id, None)
- pending.loop.call_soon_threadsafe(
- _set_future_result,
- pending.future,
- {
- "op_id": op_id,
- "ok": False,
- "error": "Invalid chunked file operation result: chunk_count changed",
- },
- )
- return True
-
- pending.chunks[chunk_index] = chunk
- if len(pending.chunks) < chunk_count:
- return True
-
- ordered = [pending.chunks[index] for index in range(chunk_count)]
- _pending_file_ops.pop(op_id, None)
-
- try:
- assembled = b"".join(ordered).decode("utf-8")
- result = json.loads(assembled)
- if not isinstance(result, dict):
- raise ValueError("decoded result is not an object")
- except Exception as exc:
- result = {
- "op_id": op_id,
- "ok": False,
- "error": f"Invalid chunked file operation result: {exc}",
- }
-
- pending.loop.call_soon_threadsafe(_set_future_result, pending.future, result)
- return True
-
-
-def _validate_file_chunk_payload(payload: dict[str, Any]) -> str:
- if payload.get("encoding") != "json+base64":
- return "encoding must be json+base64"
-
- try:
- chunk_index = int(payload.get("chunk_index"))
- chunk_count = int(payload.get("chunk_count"))
- except (TypeError, ValueError):
- return "chunk_index and chunk_count must be integers"
-
- if chunk_count <= 0:
- return "chunk_count must be positive"
- if chunk_index < 0 or chunk_index >= chunk_count:
- return "chunk_index out of range"
- if not isinstance(payload.get("data"), str):
- return "data must be a string"
- return ""
+ return _resolve_pending(_pending_file_ops, op_id, sid=sid, payload=payload)
def fail_pending_file_op(
diff --git a/tests/test_a0_connector_payload_limits.py b/tests/test_a0_connector_payload_limits.py
new file mode 100644
index 000000000..c231689ad
--- /dev/null
+++ b/tests/test_a0_connector_payload_limits.py
@@ -0,0 +1,68 @@
+import threading
+from unittest.mock import AsyncMock
+
+import pytest
+
+from helpers.ws_manager import WsManager
+from plugins._a0_connector.api.ws_connector import WsConnector
+from plugins._a0_connector.helpers.ws_runtime import (
+ store_sid_connector_capabilities,
+ ws_max_payload_bytes_for_sid,
+)
+
+
+class _FakeSocketIOServer:
+ def __init__(self) -> None:
+ self.emit = AsyncMock()
+ self.disconnect = AsyncMock()
+
+
+async def test_oversized_core_event_becomes_connector_error_without_disconnect() -> None:
+ socketio = _FakeSocketIOServer()
+ manager = WsManager(socketio, threading.RLock())
+ manager.set_server_restart_broadcast(False)
+ handler = WsConnector(socketio, threading.RLock(), manager=manager, namespace="/ws")
+ manager.register_handlers({"/ws": [handler]})
+ await manager.handle_connect("/ws", "sid-limit")
+ store_sid_connector_capabilities(
+ "sid-limit",
+ {"ws_max_payload_bytes": 2048},
+ )
+
+ await handler.emit_to(
+ "sid-limit",
+ "connector_context_event",
+ {"context_id": "ctx-1", "data": {"text": "x" * 4096}},
+ )
+
+ assert ("/ws", "sid-limit") in manager.connections
+ assert socketio.disconnect.await_count == 0
+ socketio.emit.assert_awaited_once()
+ event, envelope = socketio.emit.await_args.args[:2]
+ assert event == "connector_error"
+ assert envelope["data"]["code"] == "PAYLOAD_TOO_LARGE"
+ assert envelope["data"]["rejected_event"] == "connector_context_event"
+ assert envelope["data"]["details"]["alternative"] == "http_bulk_transfer"
+ await manager.handle_disconnect("/ws", "sid-limit")
+
+
+async def test_connector_hello_negotiates_peer_receive_limit() -> None:
+ socketio = _FakeSocketIOServer()
+ manager = WsManager(socketio, threading.RLock())
+ manager.set_server_restart_broadcast(False)
+ handler = WsConnector(socketio, threading.RLock(), manager=manager, namespace="/ws")
+ manager.register_handlers({"/ws": [handler]})
+ await manager.handle_connect("/ws", "sid-hello")
+
+ result = await handler.process(
+ "connector_hello",
+ {"capabilities": {"ws_max_payload_bytes": 16 * 1024 * 1024}},
+ "sid-hello",
+ )
+
+ assert result["capabilities"]["ws_max_payload_bytes"] == 50 * 1024 * 1024
+ assert ws_max_payload_bytes_for_sid("sid-hello") == 16 * 1024 * 1024
+ assert manager.connections[("/ws", "sid-hello")].max_payload_bytes == 16 * 1024 * 1024
+ await manager.handle_disconnect("/ws", "sid-hello")
diff --git a/tests/test_ws_manager.py b/tests/test_ws_manager.py
index 49a51fea9..f0f602c26 100644
--- a/tests/test_ws_manager.py
+++ b/tests/test_ws_manager.py
@@ -1,4 +1,5 @@
import asyncio
+import hashlib
import sys
import threading
import time
@@ -13,13 +14,18 @@ if str(PROJECT_ROOT) not in sys.path:
sys.path.insert(0, str(PROJECT_ROOT))
from helpers.ws import ConnectionNotFoundError, WsHandler
+from api.ws_dev_test import WsDevTest
from helpers.ws_manager import (
WsManager,
WsResult,
+ ConnectionInfo,
BUFFER_TTL,
DIAGNOSTIC_EVENT,
LIFECYCLE_CONNECT_EVENT,
LIFECYCLE_DISCONNECT_EVENT,
+ WsPayloadTooLargeError,
+ socketio_ack_size,
+ socketio_event_size,
)
NAMESPACE = "/test"
@@ -42,6 +48,238 @@ class DummyHandler(WsHandler):
return response
[email protected]("limit", [4 * 1024 * 1024, 16 * 1024 * 1024, 50 * 1024 * 1024])
+async def test_emit_to_enforces_exact_serialized_payload_boundary(limit: int):
+ socketio = FakeSocketIOServer()
+ manager = WsManager(socketio, threading.RLock())
+ identity = (NAMESPACE, "sid-limit")
+ manager.connections[identity] = ConnectionInfo(namespace=NAMESPACE, sid="sid-limit")
+ manager._known_sids.add(identity) # noqa: SLF001
+
+ base_envelope = manager._wrap_envelope(None, {"blob": ""}) # noqa: SLF001
+ base_size = socketio_event_size("payload_event", base_envelope, namespace=NAMESPACE)
+ padding = limit - base_size
+ assert padding > 1
+
+ calls_before = socketio.emit.await_count
+ for delta in (-1, 0):
+ await manager.emit_to(
+ NAMESPACE,
+ "sid-limit",
+ "payload_event",
+ {"blob": "x" * (padding + delta)},
+ max_payload_bytes=limit,
+ )
+
+ with pytest.raises(WsPayloadTooLargeError) as exc_info:
+ await manager.emit_to(
+ NAMESPACE,
+ "sid-limit",
+ "payload_event",
+ {"blob": "x" * (padding + 1)},
+ max_payload_bytes=limit,
+ )
+
+ assert socketio.emit.await_count == calls_before + 2
+ assert exc_info.value.actual_bytes == limit + 1
+ assert exc_info.value.limit_bytes == limit
+ assert exc_info.value.details()["alternative"] == "http_bulk_transfer"
+
+
+async def test_connection_payload_limit_applies_to_emit_and_broadcast() -> None:
+ socketio = FakeSocketIOServer()
+ manager = WsManager(socketio, threading.RLock())
+ limited = (NAMESPACE, "sid-limited")
+ unlimited = (NAMESPACE, "sid-unlimited")
+ manager.connections[limited] = ConnectionInfo(namespace=NAMESPACE, sid=limited[1])
+ manager.connections[unlimited] = ConnectionInfo(namespace=NAMESPACE, sid=unlimited[1])
+ manager.set_peer_max_payload_bytes(NAMESPACE, limited[1], 2048)
+
+ with pytest.raises(WsPayloadTooLargeError):
+ await manager.emit_to(
+ NAMESPACE,
+ limited[1],
+ "payload_event",
+ {"blob": "x" * 4096},
+ )
+
+ with pytest.raises(WsPayloadTooLargeError):
+ await manager.broadcast(
+ NAMESPACE,
+ "payload_event",
+ {"blob": "x" * 4096},
+ )
+
+ socketio.emit.assert_awaited_once()
+ assert socketio.emit.await_args.kwargs["to"] == unlimited[1]
+
+
+async def test_dev_harness_can_emit_to_requesting_sid() -> None:
+ socketio = FakeSocketIOServer()
+ manager = WsManager(socketio, threading.RLock())
+ identity = (NAMESPACE, "sid-dev-harness")
+ manager.connections[identity] = ConnectionInfo(namespace=NAMESPACE, sid=identity[1])
+ handler = WsDevTest(socketio, threading.RLock(), manager=manager, namespace=NAMESPACE)
+
+ result = await handler.process(
+ "ws_tester_emit_to",
+ {"message": "boundary probe", "timestamp": "fixed"},
+ identity[1],
+ )
+
+ assert result == {"status": "emitted"}
+ event, envelope = socketio.emit.await_args.args[:2]
+ assert event == "ws_tester_emit_to_result"
+ assert envelope["data"] == {
+ "message": "boundary probe",
+ "echo": True,
+ "timestamp": "fixed",
+ }
+ assert socketio.emit.await_args.kwargs["to"] == identity[1]
+
+
+async def test_dev_harness_round_trips_connector_transfer(monkeypatch) -> None:
+ from plugins._a0_connector.helpers import ws_runtime
+
+ socketio = FakeSocketIOServer()
+ manager = WsManager(socketio, threading.RLock())
+ handler = WsDevTest(socketio, threading.RLock(), manager=manager, namespace=NAMESPACE)
+
+ async def fake_emit_connector_event(
+ sid: str,
+ event: str,
+ payload: dict[str, Any],
+ **kwargs: Any,
+ ) -> None:
+ del event, kwargs
+ assert payload["request_padding"] == "r" * 10
+ ws_runtime.resolve_pending_browser_op(
+ str(payload["op_id"]),
+ sid=sid,
+ payload={
+ "op_id": payload["op_id"],
+ "ok": True,
+ "result": {"result_padding": "s" * int(payload["result_bytes"])},
+ },
+ )
+
+ monkeypatch.setattr(ws_runtime, "emit_connector_event", fake_emit_connector_event)
+
+ result = await handler.process(
+ "ws_tester_connector_transfer",
+ {"request_bytes": 10, "result_bytes": 12},
+ "sid-transfer-harness",
+ )
+
+ assert result == {
+ "status": "ok",
+ "request_bytes": 10,
+ "result_bytes": 12,
+ "result_sha256": hashlib.sha256(b"s" * 12).hexdigest(),
+ }
+
+
+async def test_dev_harness_can_cancel_connector_transfer(monkeypatch) -> None:
+ from plugins._a0_connector.helpers import ws_runtime
+
+ socketio = FakeSocketIOServer()
+ manager = WsManager(socketio, threading.RLock())
+ handler = WsDevTest(socketio, threading.RLock(), manager=manager, namespace=NAMESPACE)
+ pending: dict[str, str] = {}
+
+ async def fake_emit_connector_event(
+ sid: str,
+ event: str,
+ payload: dict[str, Any],
+ **kwargs: Any,
+ ) -> None:
+ del event, kwargs
+ pending["sid"] = sid
+ pending["op_id"] = str(payload["op_id"])
+ await asyncio.sleep(0.01)
+
+ async def fake_abort_transfers_for_context(
+ context_id: str,
+ **kwargs: Any,
+ ) -> int:
+ del kwargs
+ assert context_id == "ws-dev-test"
+ ws_runtime.resolve_pending_browser_op(
+ pending["op_id"],
+ sid=pending["sid"],
+ payload={"op_id": pending["op_id"], "ok": False, "error": "cancelled"},
+ )
+ return 1
+
+ monkeypatch.setattr(ws_runtime, "emit_connector_event", fake_emit_connector_event)
+ monkeypatch.setattr(
+ ws_runtime,
+ "abort_transfers_for_context",
+ fake_abort_transfers_for_context,
+ )
+
+ result = await handler.process(
+ "ws_tester_connector_transfer",
+ {"request_bytes": 10, "result_bytes": 12, "cancel": True},
+ "sid-transfer-harness",
+ )
+
+ assert result == {
+ "status": "cancelled",
+ "request_bytes": 10,
+ "result_bytes": 0,
+ "result_sha256": hashlib.sha256(b"").hexdigest(),
+ "cancelled_transfers": 1,
+ }
+
+
[email protected]("limit", [4 * 1024 * 1024, 16 * 1024 * 1024, 50 * 1024 * 1024])
+def test_ack_response_enforces_exact_serialized_payload_boundary(limit: int):
+ manager = WsManager(FakeSocketIOServer(), threading.RLock())
+ identity = (NAMESPACE, "sid-ack-limit")
+ manager.connections[identity] = ConnectionInfo(namespace=NAMESPACE, sid=identity[1])
+ manager.set_peer_max_payload_bytes(NAMESPACE, identity[1], limit)
+ base = {
+ "correlationId": "corr-limit",
+ "results": [{"ok": True, "data": {"blob": ""}}],
+ }
+ padding = limit - socketio_ack_size(base, namespace=NAMESPACE)
+ assert padding > 1
+
+ for delta in (-1, 0):
+ response = {
+ "correlationId": "corr-limit",
+ "results": [{"ok": True, "data": {"blob": "x" * (padding + delta)}}],
+ }
+ assert manager.constrain_ack_response(
+ NAMESPACE,
+ identity[1],
+ "payload_event",
+ response,
+ ) is response
+
+ oversized = {
+ "correlationId": "corr-limit",
+ "results": [{"ok": True, "data": {"blob": "x" * (padding + 1)}}],
+ }
+ response = manager.constrain_ack_response(
+ NAMESPACE,
+ identity[1],
+ "payload_event",
+ oversized,
+ )
+
+ error = response["results"][0]["error"]
+ assert error["code"] == "PAYLOAD_TOO_LARGE"
+ assert error["details"]["actual_bytes"] == limit + 1
+ assert error["details"]["limit_bytes"] == limit
+
+
@pytest.mark.asyncio
async def test_connect_disconnect_updates_registry():
socketio = FakeSocketIOServer()