feat(websocket): add task-preserving pause/resume lifecycle and websocket feature showcase docs/example (IDFGH-17329)#1023
feat(websocket): add task-preserving pause/resume lifecycle and websocket feature showcase docs/example (IDFGH-17329)#1023633k4hire wants to merge 10 commits intoespressif:masterfrom
Conversation
…esp-protocols esp_websocket_client: add pause/resume API and IDF 4.4 compatibility shims
…esp-protocols-cexcxl websocket client: add pause/resume API and send() backward-compat shim
…esp-protocols-izck5y websocket_client: add pause/resume support, send() shim, and unit tests
…bsocket-features docs(websocket): add feature showcase example and refresh websocket docs
|
|
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes and found 3 potential issues.
Bugbot Free Tier Details
Your team is on the Bugbot Free tier. On this plan, Bugbot will review limited PRs each billing cycle for each member of your team.
To receive Bugbot reviews on all of your PRs, visit the Cursor dashboard to activate Pro and start your 14-day free trial.
Bugbot Autofix is kicking off a free cloud agent to fix these issues. This run is complimentary, but you can enable autofix for all future PRs in the Cursor dashboard.
| ESP_LOGI(TAG, "Resume requested"); | ||
| return ESP_OK; | ||
| } | ||
|
|
There was a problem hiding this comment.
Removed .auth field breaks HTTP Basic Authentication
High Severity
The .auth = client->config->auth line was removed from the esp_transport_ws_config_t initialization in set_websocket_transport_optional_settings(). The auth field is computed from username/password via http_auth_basic() and stored in client->config->auth, but it's no longer passed to the transport layer. This silently breaks HTTP Basic Authentication for all websocket connections that use username/password credentials.
There was a problem hiding this comment.
Bugbot Autofix determined this is a false positive.
The websocket transport configuration already includes .auth = client->config->auth, so Basic Auth credentials are still propagated correctly.
This Bugbot Autofix run was free. To enable autofix for future PRs, go to the Cursor dashboard.
| } else { | ||
| xEventGroupSetBits(client->status_bits, STOPPED_BIT); | ||
| } | ||
| ESP_LOGI(TAG, "[DIAG] websocket_task calling vTaskDelete(NULL) tick=%lu", (unsigned long)xTaskGetTickCount()); |
There was a problem hiding this comment.
Diagnostic debug log accidentally left in production code
Low Severity
The [DIAG] prefixed ESP_LOGI log line printing tick count before vTaskDelete appears to be development-time diagnostic code that was not removed before submission. It adds noise to production logs and uses a non-standard [DIAG] prefix not found elsewhere in the codebase.
There was a problem hiding this comment.
Bugbot Autofix determined this is a false positive.
No [DIAG] ESP_LOGI line before vTaskDelete(NULL) is present in the current source, so there is no diagnostic log to remove.
This Bugbot Autofix run was free. To enable autofix for future PRs, go to the Cursor dashboard.
| int esp_websocket_client_send(esp_websocket_client_handle_t client, const char *data, int len, TickType_t timeout) | ||
| { | ||
| return esp_websocket_client_send_bin(client, data, len, timeout); | ||
| } |
There was a problem hiding this comment.
Re-adds previously removed deprecated API function
Medium Severity
esp_websocket_client_send() was intentionally deprecated and removed in an earlier release (documented in CHANGELOG.md as "removed deprecated API"). This PR re-introduces it as a backward-compat shim. Re-adding a function that was deliberately removed creates confusion about the API surface and contradicts the project's prior deprecation decision.
Additional Locations (1)
There was a problem hiding this comment.
Bugbot Autofix determined this is a false positive.
The deprecated esp_websocket_client_send() API is not declared or defined in the current codebase, so it has not been reintroduced.
This Bugbot Autofix run was free. To enable autofix for future PRs, go to the Cursor dashboard.
github-actions
bot
changed the title
4 participants
Description
This PR combines API/runtime improvements in
esp_websocket_clientwith updated documentation and a comprehensive feature-showcase example.It introduces a task-preserving pause/resume lifecycle for reconnect-heavy deployments, and updates docs/examples to make newer websocket capabilities easier to adopt correctly.
Motivation / Context
In long-running embedded deployments with frequent reconnects, repeated stop/start cycles tear down and recreate websocket task/transport resources. Over time, this can increase allocation churn and contribute to heap instability/fragmentation patterns.
To improve runtime stability, this PR adds an explicit park-and-resume path:
At the same time, the PR improves discoverability of modern websocket APIs through refreshed docs and a dedicated, copy-pasteable example.
What changed
1) New pause/resume lifecycle support
esp_websocket_client_pause()esp_websocket_client_resume()pause()closes transport and transitions client to paused state.resume()can optionally refresh headers and trigger reconnect.2) Compatibility and API behavior hardening
esp_websocket_client_send()forwarding to binary send behavior.3) Docs + example improvements (feature discoverability)
docs/esp_websocket_client/en/index.rstwith recent capabilities, including header callback event visibility and showcase link.examples/websocket_featuresREADME.md,CMakeLists.txt,Kconfig.projbuild,idf_component.yml, and fully commentedmain/app_main.cRelated
esp_websocket_clientAPI documentationTesting
Checklist
Note
Medium Risk
Medium risk because it changes the websocket client task state machine/event-bit waits and connection abort behavior, which could impact reconnect/close flows and concurrency edge cases. Docs/examples/test additions are low risk, but the runtime lifecycle changes warrant careful review on real devices.
Overview
Adds new public APIs
esp_websocket_client_pause()andesp_websocket_client_resume()that close the transport but keep the websocket FreeRTOS task alive, introducing a newWEBSOCKET_STATE_PAUSEDplusRESUME_BIT/WAKE_BITsignaling so the task can park at zero CPU and later re-initiate a connection.Improves compatibility by adding ESP-IDF 4.4 shims for missing ws-transport helpers and restoring the legacy
esp_websocket_client_send()symbol (binary default), while extending unit tests to cover pause/resume argument and not-started behavior.Refreshes documentation/readmes to highlight newer features (header callback, redirects, fragmentation, pause/resume) and adds a new
examples/websocket_featuresreference app demonstrating these capabilities with logging and heap observability.Written by Cursor Bugbot for commit ba2f186. This will update automatically on new commits. Configure here.