chattolib/docs/no-pyqwest.md

Replacing connectrpc (and its pyqwest dependency) with a hand-rolled Connect client

Exploration notes for chattolib-zo8b. Goal: determine whether chattolib can drop the connectrpc package — and with it the transitive pyqwest — by implementing the small slice of the Connect protocol it actually uses.

TL;DR recommendation

Feasible, and small. Everything chattolib needs from connectrpc reduces to one async method, execute_unary, plus a trivial binary codec and a JSON error-envelope parser. The whole thing is ~150 lines. The real cost is not the runtime — it's code generation: chattolib's 24 *_connect.py stubs are emitted by protoc-gen-connect-python, which is coupled to connectrpc's types. We either (a) keep the stubs but repoint their base class, or (b) write a tiny codegen that emits only the async client.

What chattolib actually uses from connectrpc

Of the 8 connectrpc submodules the generated stubs import (client, code, compression, errors, interceptor, method, request, server), chattolib's runtime path touches only:

connectrpc piece	Used by chattolib?	Notes
client.ConnectClient (async)	Yes — 23 *ServiceClient classes subclass it	Only the async client. The *ClientSync, *ASGIApplication, *WSGIApplication, and Protocol classes in each stub are dead weight chattolib never imports.
client.execute_unary(...)	Yes — the one method every stub calls	POSTs to /{service}/{Method}, encodes with the codec, decodes the response, maps errors.
compat.google_protobuf_binary_codec	Yes	Trivial: encode = SerializeToString, decode = cls.FromString. ~10 lines.
errors.ConnectError	Yes	Chattolib wraps it into ChattoConnectError.
code.Code	Yes	The gRPC/Connect status-code enum.
method.MethodInfo / IdempotencyLevel	Yes (data only)	Just carries name, service_name, input/output classes.
request.Headers / RequestContext	Indirectly	Chattolib passes headers= (an auth bearer) into each call.
compression, interceptor, server.*	No	Chattolib never compresses, never intercepts, never serves.

So the entire runtime surface is: one async unary call + a binary codec + an error parser.

The wire protocol (what execute_unary does)

From connectrpc/_client_async.py::_send_request_unary:

1. url = f"{address}/{service_name}/{Method}" (e.g. /api/connect/chatto.api.v1.RoomService/JoinRoom)
2. body = codec.encode(request) → request.SerializeToString()
3. POST url with headers (chattolib adds Authorization: Bearer <token>), Content-Type: application/proto
4. On 200: return codec.decode(resp.content, output_cls) → output_cls.FromString(body)
5. On non-200: parse the JSON error envelope {"code": "...", "message": "...", "details": [...]} into a ConnectError(code, message, details); fall back to an HTTP-status→code map if the body isn't JSON.
6. Timeouts → DEADLINE_EXCEEDED; network errors → UNAVAILABLE.

That's the whole protocol for unary Connect. (Chatto uses unary-only; there are no client/server/bidi streams in the Chatto API surface chattolib wraps.)

The two real decisions

1. The codec is a non-issue

ProtoBinaryCodec is SerializeToString/FromString. Trivial to copy.

2. Code generation is the actual work

The 24 stubs are generated by protoc-gen-connect-python and import connectrpc.{client,code,compression,errors,interceptor,method,request,server}. Two paths:

• (a) Repoint, don't regenerate. Keep the existing *_connect.py files but make their base class a chattolib-owned ConnectClient that also exposes execute_unary. The stubs' MethodInfo(...) calls would need our own MethodInfo/IdempotencyLevel shims. Pro: no codegen change. Con: we still carry 24 files that import names we now have to provide, and every future proto regen re-introduces connectrpc imports.

• (b) Tiny custom codegen. Write a small protoc plugin (or a Python post-processor over the .proto/_pb2 files) that emits only the async client class, importing from chattolib._connect. Pro: clean, no connectrpc anywhere, stubs shrink ~4x (drop sync/ASGI/WSGI/Protocol). Con: it's a new thing to maintain and to run on every proto regen.

Option (b) is the cleaner end state and matches "chattolib owns its transport." Option (a) is the lower-effort first step and a fine way to de-risk.

What we'd drop / keep

• Drop: connectrpc (and therefore pyqwest) from pyproject.toml.
• Keep: protobuf (the messages), websockets (realtime, unaffected).
• Net: dependency tree goes from connectrpc → {protobuf-py, pyqwest} to just protobuf. pyqwest (a Rust-backed HTTP client) disappears entirely.

Risks

• Correctness on the error path. The JSON error envelope + details (protobuf Any, base64) + HTTP-status fallback is the fiddly bit. Must be tested against real server errors, not just happy paths.
• use_get / compression / interceptors. Chattolib never uses them, so we can simply not implement them. (Confirm no stub call passes use_get=True in a way chattolib relies on — it doesn't; chattolib always POSTs.)
• Future Chatto changes. If Chatto ever adds a streaming RPC, the hand-rolled client would need a streaming path. Today: none.
• We own the protocol now. No more upstream connectrpc fixes/patches. Acceptable given how small the surface is.

Prototype plan (next step)

1. src/chattolib/_connect.py: Codec, MethodInfo, Code (re-export or minimal enum), ConnectError, and class ConnectClient with async execute_unary(...) doing the 6 steps above over httpx.
2. Point the 23 *ServiceClient base classes at it (option a) — or regenerate (option b).
3. Re-run the full test suite + a live smoke test against the preview server.
4. If green: drop connectrpc from pyproject.toml.

---

Result (spike outcome)

Feasible and done — as a working prototype in this worktree. The hand-rolled client is green against the live server with connectrpc and pyqwest physically uninstalled.

What was built (all in this worktree, throwaway until you approve)

• src/chattolib/_connect.py (~180 lines) — the whole replacement:
  • Code enum (the 16 Connect/gRPC status codes)
  • ConnectError (.code, .message, .details, .status_code; str() is the message only, matching connectrpc so translate_connect_error is unchanged)
  • MethodInfo (name, service_name, input, output, idempotency_level)
  • _BinaryCodec (SerializeToString / FromString) + google_protobuf_binary_codec()
  • ConnectClient with async execute_unary(...) over httpx: POST /{service}/{Method}, Content-Type: application/proto, 200 → decode, non-200 → parse the JSON error envelope (with an HTTP-status→code fallback).
• scripts/regen_connect.py — the tiny codegen. Reads each existing *_connect.py and rewrites it to keep only the async *ServiceClient (dropping the Protocol/*Sync/*ASGIApplication/*WSGIApplication/ *ClientSync classes chattolib never used), strip all connectrpc imports, repoint the base class + MethodInfo/IdempotencyLevel at chattolib._connect, and trim the timeout_ms/use_get params our client doesn't take.
• src/chattolib/_transport.py — Code/ConnectError/ google_protobuf_binary_codec now imported from chattolib._connect.
• src/chattolib/client.py — the ConnectError import in _rpc repointed.
• pyproject.toml — connectrpc removed from dependencies (now just protobuf; httpx is already gone from the bot-only change).

Verification

• Full suite: 64 passed, 2 skipped (the 2 are the bot-key-gated live tests).
• ruff check + mypy clean.
• Live against next.preview.chatto.run with connectrpc/pyqwest uninstalled: get_server, me, list_rooms, post_message (a write), and the error path (not_found) all work.

The real trade-off (the actual recommendation)

The runtime is small and the win is real: the dependency tree loses both connectrpc and pyqwest (a Rust-backed HTTP client), leaving just protobuf + websockets. In exchange:

1. We own the Connect protocol now. ~180 lines, well-tested here, but no more upstream patches. The surface is small (unary only) so this is low-risk — as long as Chatto stays unary-only. If Chatto ever adds a streaming RPC, this client needs a streaming path.
2. Codegen is a new maintenance item. regen_connect.py is a regex-based post-processor over the connectrpc-generated files, not a true protoc plugin. It works for the current 24 stubs, but on each proto regen you'd run generate_pb.sh (which still uses protoc-gen-connect-python to produce the stubs) then regen_connect.py to strip them down. So the connectrpc code generator is still in the build loop even though the runtime is gone. A fully clean end state would replace that generator too — a larger lift.
3. The stubs are now "DO NOT EDIT" in a new sense. They're generated, but by our script; the header says so.

Recommendation

Go, with a caveat. The runtime replacement is clearly worth it if dropping pyqwest is the goal — it's ~180 lines, fully tested, and verified live. The one thing to decide before merging: do you want to (a) ship this as-is (runtime freedom, but generate_pb.sh still shells out to the connectrpc codegen), or (b) also write a from-scratch protoc plugin so the connectrpc generator is gone from the build entirely? (a) is this worktree; (b) is a follow-on.