feat(websocket): add WEBSOCKET_EVENT_HEADER_RECEIVED (IDFGH-16539)

[bryghtlabs-richard]

Description

Send a new event for each HTTP header-line received, so that the caller may extract interesting headers and cookies. In my case, this is needed for supporting F5 and Amazon ALB cookie-based load-balancers.

Related

Depends on espressif/esp-idf#16119
Closes #715

Testing

Confirmed I can print out the needed header-lines.

Checklist

Before submitting a Pull Request, please ensure the following:

• 🚨 This PR does not introduce breaking changes.
• All CI checks (GH Actions) pass.
• Documentation is updated as needed.
• Tests are updated or added as necessary.
• Code is well-commented, especially in complex areas.
• Git history is clean — commits are squashed to the minimum necessary.

---

Note

Emit WEBSOCKET_EVENT_HEADER_RECEIVED for each pre-upgrade HTTP header via a transport header callback (IDF ≥ 6), and update examples to handle it.

• Core (websocket client):
  • Add pre-upgrade HTTP header callback: define websocket_header_hook() and, when supported, pass .header_hook and .header_user_context to esp_transport_ws_config_t, dispatching WEBSOCKET_EVENT_HEADER_RECEIVED for each header line.
• API:
  • Introduce WS_TRANSPORT_HEADER_CALLBACK_SUPPORT (enabled for ESP_IDF_VERSION >= 6.0.0).
  • Add WEBSOCKET_EVENT_HEADER_RECEIVED to esp_websocket_event_id_t (behind the feature flag).
• Examples:
  • Update examples/linux and examples/target event handlers to log WEBSOCKET_EVENT_HEADER_RECEIVED when available.

^{Written by Cursor Bugbot for commit 3a9529b. This will update automatically on new commits. Configure here.}

[glmfe]

Hi @bryghtlabs-richard,

we merged the dependencies for this PR, (espressif/esp-idf#16199, espressif/esp-idf#16119).
Please, use the current head of IDF and also add:

#if ESP_IDF_VERSION >= ESP_IDF_VERSION_VAL(6, 0, 0)
// Features supported in 6.0.0
#define WS_TRANSPORT_HEADER_CALLBACK_SUPPORT    1
#endif

then guard all the codes using:

#if WS_TRANSPORT_REDIRECT_HEADER_SUPPORT
`... code section...`
#endif // WS_TRANSPORT_REDIRECT_HEADER_SUPPORT

Thanks!

[bryghtlabs-richard]

then guard all the codes using:

It is done and ready for your review.

@glmfe , should ESP-IDF keep both APIs (including 1d71a9e8114fba8d22e96694 API), or only support the per-header callback one going forward? I think once 6.0.0 is released, we'll need to support everything in it going forward.

[glmfe]

then guard all the codes using:

It is done and ready for your review.

@glmfe , should ESP-IDF keep both APIs (including 1d71a9e8114fba8d22e96694 API), or only support the per-header callback one going forward? I think once 6.0.0 is released, we'll need to support everything in it going forward.

Thanks for the updates, LGTM

about the other API, my guess is that we are going to deprecate it later on since we already entered the code freeze for IDF 6.0. But I'll have to allign internally

[glmfe]

Hi @bryghtlabs-richard,

we just merged a fix for the pipeline issue, please, rebase your brach.

BR

[cursor]

This PR is being reviewed by Cursor Bugbot

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.