feat(ws): add public Client.stop() for graceful shutdown

[ChangjunZhao]

Problem

The WebSocket Client exposes no public way to gracefully shut down. The only lifecycle method is start(), which blocks forever on loop.run_until_complete(_select()) (where _select is while True: sleep(3600)).

Downstream apps that need to stop a running client (e.g. on app shutdown, on config change, on plugin lifecycle hook) currently have to reach for private attributes — _disconnect(), _conn, _auto_reconnect — and on top of that, start() never returns even after the underlying WS is closed, so the worker thread leaks.

Even worse, auto_reconnect=True means the SDK reconnects on its own after any external close attempt, so callers can't "stop" by just closing the connection.

Symptoms we hit downstream:

• Task was destroyed but it is pending! for the leaked _ping_loop task
• Task exception was never retrieved for the receive loop
• WS thread accumulating across reconnect cycles
• Brand new WebSocket connections appearing after we tried to stop

Solution

Add a public async def stop() method that:

1. Sets _auto_reconnect = False — prevents the receive loop's exception handler from re-establishing the connection after we close it
2. Cancels three internal background tasks (_ping_task, _receive_message_task, the new _main_task) — prevents pending-task warnings on loop close
3. Calls _disconnect() — closes the underlying WebSocket
4. Cancels _main_task — releases the blocking start() so its worker thread can exit
5. Is idempotent — safe to call multiple times (e.g. from signal handlers, finally blocks)

Designed for the typical cross-thread pattern via asyncio.run_coroutine_threadsafe:

# In worker thread:
client = Client(app_id, app_secret)
client.start()   # blocks until stop() is called from another thread

# In main thread (or signal handler):
future = asyncio.run_coroutine_threadsafe(client.stop(), client_loop)
future.result(timeout=5)
# Now the worker thread's start() returns, thread can be joined.

Changes

• Client.__init__: 3 new task handle fields (_ping_task, _receive_message_task, _main_task)
• Client.start(): stores the ping/main task handles so stop() can cancel them; still blocks on the main task; wraps the block in try/except CancelledError for graceful exit
• Client._connect(): stores the receive_message_task handle
• Client.stop(): new public method — see docstring for full semantics
• Module-level _select() is kept unchanged for backward compat (some downstream callers monkeypatch it in tests)

Tests

lark_oapi/ws/tests/test_stop.py (new file, 6 tests):

• test_stop_disables_auto_reconnect
• test_stop_closes_websocket
• test_stop_cancels_background_tasks
• test_stop_is_idempotent
• test_stop_handles_already_done_tasks
• test_stop_from_another_thread — real-world run_coroutine_threadsafe pattern

All existing test_websockets_compat.py tests still pass.

$ python -m pytest lark_oapi/ws/tests/ -v
========================= 10 passed in 5.22s =========================

Backward compatibility

✅ All existing behavior preserved when stop() is not called.
✅ start() still blocks on run_until_complete of the main task (same observable behavior as before).
✅ Module-level _select() retained.
✅ No changes to public method signatures, no breaking changes to private attributes used in existing patches.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}