feat(websocket): Add non-blocking stop request and bounded stop wait

[wonderdog5]

Problem

esp_websocket_client_stop() — and esp_websocket_client_destroy(), which calls it — joins the client task with portMAX_DELAY. That is fine for callers that can block, but there is a real deadlock-adjacent class it creates: a task that must not block unboundedly has no bounded way to tear a client down.

Concrete case (ESP32-S3 battery device, two websocket clients): a power-management task with a fixed sleep-readiness deadline tears down both clients back to back on the way into deep sleep. A link blip is exactly when sleep tends to get requested, so both client tasks are typically mid-reconnect — each join then waits out the full TLS/transport connect timeout before the task notices run == false, and the two unbounded joins stack. With a ~15 s connect timeout per client, the teardown can exceed a 30 s system deadline, and the caller can neither cancel nor bound it.

Change

Split the stop into the two halves it is already made of internally:

• esp_websocket_client_request_stop() — the non-blocking half: sets run = false and REQUESTED_STOP_BIT (which also wakes a WEBSOCKET_STATE_WAIT_TIMEOUT reconnect wait early, so a task idling between retries exits immediately), then returns.
• esp_websocket_client_wait_stopped(client, timeout) — a bounded wait on STOPPED_BIT. Only after it returns true is esp_websocket_client_destroy() guaranteed not to block on the task; on false the caller keeps the handle and retries later.

An application tearing down several clients can request all stops first — the task exits overlap — and then wait for each against a single shared deadline, instead of serializing every client's worst-case teardown.

esp_websocket_client_stop() is unchanged (still request + unbounded wait); no existing behavior is affected. No new state or bits are introduced — the split only exposes the existing REQUESTED_STOP_BIT / STOPPED_BIT machinery with a caller-chosen timeout.

Notes

• request_stop mirrors stop_wait_task's guard: it cannot be called from the websocket task itself, and is a no-op ESP_OK when already stopped.
• wait_stopped(portMAX_DELAY) reproduces the current unbounded join exactly.
• Field-tested in production firmware (vendored copy of this component) since 2026-08: two clients' teardowns bounded by one shared 5 s budget; an abandoned (timed-out) join is reaped by a later stop/destroy once the task exits on its own.

I'm happy to adjust naming, add a test under components/esp_websocket_client/tests, or fold this into a different API shape if the maintainers prefer.

🤖 Generated with Claude Code

[CLAassistant]

All committers have signed the CLA.