feat(python): expose client disconnect and shutdown - #4288

edit: add prek tests.
edit2: replace RuntimeError("Client shutdown") by RuntimeError, and run the lifecycle tests on every transport.
edit3: describe the lifecycle limits that the automated review found, and check the HTTP session in the test.

Which issue does this PR address?

Closes #4163

Rationale

The Rust Client trait has disconnect() and shutdown(), but the Python IggyClient only had connect(). Thus a Python caller cannot close a connection to connect again later, and cannot release the client without dropping it.

What changed?

Now IggyClient has the async methods disconnect() and shutdown(). Both methods call the Rust client directly, and repeated calls are safe. The behavior depends on the transport:

• disconnect() closes the connection, and the client can connect again. The sign-in from login_user() is lost, thus the caller must log in again after connect(). A client with auto-login credentials logs in again on connect().
• shutdown() closes the connection and releases the client. After shutdown(), requests fail with RuntimeError.
• Over HTTP, both methods do nothing, because HTTP has no connection to close.

The Rust SDK has lifecycle problems that also affect these methods. They are tracked in #4287, and this PR does not change the Rust SDK:

• With auto-login, the heartbeat connects the client again and signs in within one heartbeat interval after disconnect(). The disconnect() docstring describes this behavior, and the tests use clients without auto-login.
• A WebSocket client can connect again after shutdown(). The test for connect() after shutdown() marks WebSocket xfail(strict=True), thus the test fails when the fix for Rust SDK: the heartbeat undoes disconnect(), and a WebSocket client connects after shutdown() #4287 lands and the mark can go.
• disconnect() after shutdown() makes the client reusable on every transport. For this reason, the shutdown() docstring does not say that the call is terminal.

Local Execution

I used Zed in devcontainer mode. The server and the tests ran in the devcontainer, and prek ran on macOS.

• Passed: cargo fmt and cargo clippy --all-targets --all-features -- -D warnings in foreign/python.

• Passed: cargo run --bin stub_gen, then ruff format and ruff check --fix. The stub diff contains only the two new methods and their docstrings.

• Passed: the lifecycle tests against a local iggy-server built from this branch, with 18 passed and 1 expected failure:

  $ uv run --no-sync pytest tests/test_connectivity.py -v -k Lifecycle
  collected 54 items / 35 deselected / 19 selected
  
  test_disconnect_is_idempotent_and_rejects_requests[tcp] PASSED
  test_disconnect_is_idempotent_and_rejects_requests[websocket] PASSED
  test_disconnect_is_idempotent_and_rejects_requests[quic] PASSED
  test_disconnected_client_connects_again[tcp] PASSED
  test_disconnected_client_connects_again[websocket] PASSED
  test_disconnected_client_connects_again[quic] PASSED
  test_disconnected_client_reconnects_and_logs_in_again[tcp] PASSED
  test_disconnected_client_reconnects_and_logs_in_again[websocket] PASSED
  test_disconnected_client_reconnects_and_logs_in_again[quic] PASSED
  test_disconnected_client_with_auto_login_signs_in_on_reconnect[tcp] PASSED
  test_disconnected_client_with_auto_login_signs_in_on_reconnect[websocket] PASSED
  test_disconnected_client_with_auto_login_signs_in_on_reconnect[quic] PASSED
  test_shutdown_is_idempotent_and_rejects_requests[tcp] PASSED
  test_shutdown_is_idempotent_and_rejects_requests[websocket] PASSED
  test_shutdown_is_idempotent_and_rejects_requests[quic] PASSED
  test_shutdown_client_cannot_connect_again[tcp] PASSED
  test_shutdown_client_cannot_connect_again[websocket] XFAIL (WebSocketClient connects again after shutdown: #4287)
  test_shutdown_client_cannot_connect_again[quic] PASSED
  test_http_disconnect_and_shutdown_do_nothing PASSED
  
  18 passed, 35 deselected, 1 xfailed in 30.96s
  

• Passed: pre-commit hooks with SKIP=web-lint prek run --all-files. Every hook passed. I skipped web-lint because this PR does not change web/.

AI Usage

1. No ^^