core: a protocol can be registered per client, and a client owns what it creates

Merged
H3
2mo ago
+604-40

Reference-implementation counterpart of typescript-utcp #52 and #54. The spec is generated from this repo's REQUIRED docstrings, so every new piece of surface carries one (checked with scripts/extract_required_docs.py).

The gap

A protocol registered in communication_protocols is one instance shared by every UtcpClient in the process, and so is any state it keeps. Right for a credential cache; wrong for connections. A caller creating a client per tenant, per user or per pooled connection was not actually isolating them — every client dialled into the same MCP session cache — and no client could tear its own connections down: the Python client had no close() at all.

The mechanism

  • New registry communication_protocol_factories, filled through register_communication_protocol_factory(type, factory). UtcpClient.create calls a factory once per client and the client records the instance as owned. A factory wins over a shared instance of the same type, so a plugin migrates by moving its registration and callers change nothing. Shared instances are still looked up live, so registering one after a client exists keeps working (existing tests rely on it).
  • Teardown scoped to what the client owns. New UtcpClient.close() (interface + implementation) closes the owned instances and leaves shared ones to the process. Every instance is closed even when one fails; the failures are then raised together as UtcpProtocolCloseError.
  • create() adopts factories inside a cleanup guard. Nothing that needs closing is created in the constructor (it can't await). A factory that raises part-way leaves the earlier instances closable; any initialization failure closes them before re-raising; a failing cleanup is logged with the original error kept as the one the caller sees.
  • CommunicationProtocol.close() joins the interface, a no-op by default, so the client can close any protocol uniformly.
  • utcp-mcp registers as a factory — sessions and stdio child processes belong to the client that opened them. utcp-http stays shared: its OAuth cache is meant to be reused.

Versions

Core → 1.2.0 (new registry + close() on the client interface), utcp-mcp → 1.2.0 requiring utcp>=1.2.0.

Tests

Ten, all through the public surface (core/tests/client/test_client_protocol_ownership.py): per-client routing, factory over shared, late shared registration, unknown type names both registries, close() scoped to the own instance, close() waits for every instance even when one fails, failed create() closes what it created, a raising factory leaves earlier instances closed, a shared instance survives a failed create(), a failing cleanup is reported. Each guard mutation-checked — every mutation fails exactly its tests. Core 51/51, MCP 48/48, http 238, cli 62, text 11.

🤖 Generated with Claude Code


Summary by cubic

Protocols can now be registered per client, so each UtcpClient owns its protocol instances and can close them. Previously one protocol instance was shared by every client, which broke per-tenant isolation and left connections unclosed.

Refactors

  • Added communication_protocol_factories; UtcpClient.create instantiates each registered factory per client, and factories registered later are adopted and owned on first use.
  • Added UtcpClient.close() to close owned protocol instances; shared instances remain process-wide.
  • Added CommunicationProtocol.close() as an interface method with a no-op default.
  • A failed create() closes any owned instances before re-raising; close failures are collected in UtcpProtocolCloseError.
  • register_manuals waits for every sibling registration to settle before raising, so a failed create() never closes a protocol another registration is still using.
  • utcp-mcp and utcp-websocket now register as factories; utcp-http stays shared.

Migration

  • Protocols whose state must not be shared between clients should switch from register_communication_protocol to register_communication_protocol_factory.
  • utcp, utcp-mcp, and utcp-websocket become 1.2.0, with the plugins requiring utcp>=1.2.0.