[chipkent]

Preview only. This is a draft in the fork showing the exact text of the PR planned for massive-com/client-python. It will be closed, not merged, once the upstream PR is opened.

Stacked on the WebSocket subscriptions PR (F1), which is itself stacked on the free-threaded CI PR (F7, for the fake test server). Please review those first; this PR only adds the five commits below.

Summary

Five changes to how WebSocketClient.connect() handles disconnects, one commit each. The last
commit is separable.

1. Reconnect after a clean server close.
   • Problem: connect() returned on ConnectionClosedOK. The server closes cleanly after
     statuses such as slow_consumer or max_connections, so the client ended for good.
   • Fix: it reconnects unless close() or request_close() was called. The desired
     subscriptions are kept across the reconnect. If connect() gives up (see 3), it re-raises
     the error that ended the last connection.
2. Backoff, and retrying only what can succeed.
   • Problem: reconnects were immediate. Massive's documentation asks clients to wait at least
     15 seconds before reconnecting
     (knowledge base).
     The websockets iterator also retried every error, including ones that can never succeed,
     such as HTTP 401/403/404 or an unverifiable certificate.
   • Fix: connect() makes each attempt itself, with a new websockets connection object per
     attempt; one is built up front so that invalid arguments raise immediately. Only transient
     failures are retried: OSError (including DNS and TLS errors other than certificate
     verification), the connection closing before a response (as reported by websockets 14 and
     15), and HTTP 408, 429 and 5xx. Each retry logs a WARNING with the delay. The wait after the
     n-th consecutive failure is uniform(b, min(1.2·b, max)) with
     b = min(reconnect_backoff·2ⁿ, max_reconnect_backoff), so every wait lies within the
     configured bounds. process_exception, which only the iterator used, is rejected with
     TypeError.
   • New parameters: reconnect_backoff=15.0 and max_reconnect_backoff=120.0.
3. max_reconnects counts consecutive failures.
   • Problem: the limit was a lifetime total, so with the default of 5 a long-running client
     raised on its sixth outage, even if every reconnect had succeeded.
   • Fix: it counts consecutive failures and resets after a successful authentication. The
     default becomes None, retrying forever. Because non-transient errors raise at once (2),
     run() is safe for long-lived processes.
4. request_close().
   • Problem: close() is a coroutine and is not thread-safe.
   • Fix: request_close() can be called from any thread. It stops connect() promptly,
     including while it is connecting or waiting to reconnect, and no further attempt starts.
     Cancelling connect() also closes a connection opened in the meantime.
5. Surface max_connections received during the handshake (separable).
   • Problem: the status was only logged.
   • Fix: max_connections_reached is set, and in raw mode the frame is passed to the
     processor, so callers can tell a full connection slot from a network drop.

Breaking changes

Commits 1–3 are marked fix!: with BREAKING CHANGE: footers:

• Clean close: connect() no longer returns when the server closes the connection cleanly;
  it reconnects until close()/request_close() is called or max_reconnects is exceeded.
• Backoff: reconnects wait at least 15 s by default instead of happening immediately. Errors
  that cannot pass (HTTP 4xx other than 408/429, certificate failures, invalid arguments) are
  raised at once instead of being retried forever.
• max_reconnects: defaults to None (retry forever) instead of 5, and counts consecutive
  failed attempts rather than all reconnects.

Test plan

• New test_websocket/test_reconnect.py, covering:
  • subscription changes made during an outage;
  • a clean close, then reconnect;
  • backoff bounds (pure tests of the delay function with random.uniform patched, plus measured
    waits against the fake server with tolerances for Windows timer resolution);
  • transient and fatal classification, including the websockets 14 and 15 forms;
  • consecutive versus lifetime counting;
  • request_close() from another thread, while waiting to reconnect, during a stuck handshake,
    before connect(), and as a handshake completes (no further attempt);
  • cancellation cleanup;
  • handshake max_connections.
• make test passes on 3.10 to 3.14 (ubuntu and windows), and on 3.13t and 3.14t with
  PYTHON_GIL=0; the suite also passes with websockets 14.0.
• make lint passes.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

_{Comment @coderabbitai help to get the list of available commands.}

[chipkent]

Assessment: not ready to merge — one likely blocker and a few medium-risk edge concerns.

PR summary

• The design direction is strong: reconnect on clean close, preserve desired subscriptions, transient/fatal retry split, thread-safe shutdown path, and substantial test expansion.
• Test coverage is materially improved (especially reconnect and fake-server behavior).
• Main risk is in reconnect-loop mechanics and close/cancel races.

Blocking issue

• _open() likely reuses a single-shot awaitable across reconnect attempts.
  In connect(), connector = connect(...) is created once and reused in the loop via _open(connector). _open() wraps it with asyncio.ensure_future(connector). If connector is coroutine-like/single-use, later attempts can fail or become undefined.
  Why this is blocking: reconnect reliability depends on this path; failure here breaks core semantics in production outages.
  What to change: create a fresh connect awaitable each attempt (factory per loop iteration), rather than storing one reusable awaitable.

Other adversarial findings (non-blocking but important)

• Class-level mutable _late_closes can cross-contaminate instances.
  Make it instance state (self._late_closes) to avoid shared global task bookkeeping across multiple clients/loops.

• Exception taxonomy may be brittle across websockets versions.
  _is_transient() treats InvalidMessage as transient only when __cause__ is EOFError. Equivalent transient handshake failures can surface differently by version/platform. Consider broadening classification or pinning/version-gating behavior with tests.

• close()/request_close() contract needs one explicit invariant in docs/tests:
  “After close request, no further reconnect attempts occur, even if handshake completes concurrently.”
  You test many races already; add a direct assertion on attempt-count stability after close request.

Design correctness check

• Subscription persistence logic: looks correct (scheduled_subs preserved, subs reset).
• Reconnect after clean close: correctly implemented.
• Backoff bounds and defaults: coherent and well-tested.
• max_reconnects as consecutive failures: semantics are improved and match long-lived process expectations.
• max_connections surfacing: good improvement and tested.

Conventions / project fit

• Overall style and test structure match repo conventions (unittest + isolated async tests).
• Docs updated for request_close(): good.
• Minor cleanup nit: duplicated import logging in websocket module area.

Merge readiness

• Status: Changes requested
• Risk: Medium-high until reconnect awaitable lifecycle is fixed
• Decision: Fix blocker, rerun websocket suite + matrix, then re-review

[Copilot]

🟡 Changes recommended

Initial handshake rejection handling and overlapping shutdown cancellation still have correctness gaps.

2 open issues

• Process initial rejection frame before sending auth · New
• Shield connection cleanup during cancellation · New

What changed in this PR

This PR revises the Massive Python client’s WebSocket reconnect behavior for long-running connections, with supporting tests, documentation, and CI updates.

Changes:

• Reconnects after clean closes, adds bounded backoff, and counts consecutive failures.
• Adds thread-safe request_close() and exposes handshake connection-limit statuses.
• Expands local-server tests and Python coverage, including free-threaded builds.

File	Description
test_websocket/​test_status.py	Updates clean-close expectations.
test_websocket/​test_reconnect.py	Tests retries, backoff, shutdown, and handshake statuses.
test_websocket/​test_fake_server.py	Tests client behavior against the fake server.
test_websocket/​fake_server.py	Adds a scriptable local WebSocket server.
test_rest/​test_concurrency.py	Tests a REST client shared across threads.
pyproject.toml	Separates test and development dependencies.
poetry.lock	Synchronizes dependency groups and resolution.
massive/​websocket/​__init__.py	Implements reconnect and shutdown semantics.
docs/​source/​WebSocket.rst	Documents request_close().
.github/​workflows/​test.yml	Expands Python and free-threaded test coverage.

_{Review effort: Balanced}

[chipkent]

Superseded by smaller PRs split by content: #19, #23, #24. Closing this preview; the replacements carry the same changes, opt-in where behaviour changes.