CAMEL-23588: camel-undertow - extend UndertowHeaderFilterStrategy to filter the legacy websocket.* exchange-header prefix

[oscerd]

Summary

Adds "websocket." to both setOutFilterStartsWith and setInFilterStartsWith
on UndertowHeaderFilterStrategy, in addition to the existing Camel* /
camel* prefixes inherited from HttpHeaderFilterStrategy. This follows the
dedicated-HeaderFilterStrategy fix shape used by CAMEL-23532 for
camel-vertx-websocket / camel-atmosphere-websocket / camel-iggy and is
the camel-undertow follow-on called out by CAMEL-23577.

Why not rename the constants

The constants in UndertowConstants (CONNECTION_KEY, CONNECTION_KEY_LIST,
SEND_TO_ALL, EVENT_TYPE, EVENT_TYPE_ENUM, CHANNEL, EXCHANGE) keep
their existing string values (websocket.connectionKey,
websocket.connectionKey.list, websocket.sendToAll, ...) because they are
part of undertow's externally-visible API contract — they appear in the
component docs and route examples. The CAMEL-23577 epic explicitly cites
websocket.connectionKey as the canonical case for the
dedicated-filter-strategy shape rather than the rename shape.

Behaviour change (transport-boundary only)

• Outbound (exchange → wire): exchange headers whose name starts with
  websocket. are no longer propagated onto the outbound HTTP/websocket
  request as wire-level headers.
• Inbound (wire → exchange): wire-level headers whose name starts with
  websocket. are no longer mapped into the resulting Camel exchange.

The undertow consumer's programmatic setHeader(CONNECTION_KEY, ...) and the
producer's in.getHeader(CONNECTION_KEY, ...) operate on the exchange
directly and are unaffected by the filter strategy.

Residual gap and defence-in-depth recommendation

The HeaderFilterStrategy only governs the transport boundary; it does not
prevent cross-component header injection (for example,
from("jetty:...").to("undertow:ws://...") — an attacker-supplied
websocket.connectionKey HTTP header is mapped into the exchange by jetty and
then read by the undertow producer to target a specific peer). The
upgrade-guide entry documents the residual gap and recommends
.removeHeaders("websocket.*") at trust boundaries as the
defence-in-depth pattern:

from("jetty:http://0.0.0.0:8080/api")
    .removeHeaders("websocket.*")
    .to("undertow:ws://internal-broker/notifications");

Opt-out

Routes that intentionally relied on undertow mapping websocket.* wire
headers in or out can supply a custom headerFilterStrategy endpoint option
to restore the previous behaviour.

Backports

• camel-4.18.x — UndertowHeaderFilterStrategy has the same shape (extends
  HttpHeaderFilterStrategy); backport applies cleanly.
• camel-4.14.x — UndertowHeaderFilterStrategy extends
  DefaultHeaderFilterStrategy (not HttpHeaderFilterStrategy) and already
  sets CAMEL_FILTER_STARTS_WITH explicitly; backport needs a small
  adaptation. Will be filed as follow-up PR.

Test plan

• mvn test in components/camel-undertow — 161 tests pass (1 skipped)
• Diff vs origin/main is purely additive (65 insertions, 0 deletions)
• Upgrade guide entry added under === camel-undertow - potential breaking change documenting the behaviour change, the cross-component-injection
  residual gap, and the recommended .removeHeaders("websocket.*")
  mitigation

Tracker: CAMEL-23577

Reported by Claude Code on behalf of Andrea Cosentino

[github-actions]

🌟 Thank you for your contribution to the Apache Camel project! 🌟
🤖 CI automation will test this PR automatically.

🐫 Apache Camel Committers, please review the following items:

• First-time contributors require MANUAL approval for the GitHub Actions to run
• You can use the command /component-test (camel-)component-name1 (camel-)component-name2.. to request a test from the test bot although they are normally detected and executed by CI.
• You can label PRs using skip-tests and test-dependents to fine-tune the checks executed by this PR.
• Build and test logs are available in the summary page. Only Apache Camel committers have access to the summary.

⚠️ Be careful when sharing logs. Review their contents before sharing them publicly.

[github-actions]

🧪 CI tested the following changed modules:

• components/camel-undertow
• docs

ℹ️ Dependent modules were not tested because the total number of affected modules exceeded the threshold (50). Use the test-dependents label to force testing all dependents.

Build reactor — dependencies compiled but only changed modules were tested (2 modules)

• Camel :: Docs
• Camel :: Undertow

---

⚙️ View full build and test results

[apupier]

ERROR] Tests run: 1, Failures: 1, Errors: 0, Skipped: 0, Time elapsed: 10.03 s <<< FAILURE! -- in org.apache.camel.component.undertow.ws.UndertowWsConsumerRouteTest
[ERROR] org.apache.camel.component.undertow.ws.UndertowWsConsumerRouteTest.echo -- Time elapsed: 10.03 s <<< FAILURE!
org.opentest4j.AssertionFailedError: expected: <true> but was: <false>
	at org.junit.jupiter.api.Assertions.assertTrue(Assertions.java:190)
	at org.apache.camel.component.undertow.ws.UndertowWsConsumerRouteTest.echo(UndertowWsConsumerRouteTest.java:173)

[apupier]

Be careful, the test jobs failed to be queued and so the PR check seems green but the last build was red and there is no new build for trying the test

[oscerd]

CI failure (build (17, false)) appears unrelated to this PR

The UndertowWsConsumerRouteTest.echo failure in run 26442254234 (3/3 surefire reruns, all expected: <true> but was: <false> at exactly 10.02 s — the wsclient1.await(10) timeout) does not appear to be caused by this PR's WEBSOCKET_FILTER_STARTS_WITH change.

Why the change is not in the failure path

• UndertowConsumer.sendMessage sets CONNECTION_KEY via exchange.getIn().setHeader(...) (direct Message API).
• UndertowProducer.processWebSocket reads CONNECTION_KEY via in.getHeader(...) (direct Message API).
• The peer match uses peer.getAttribute(CONNECTION_KEY) on the WebSocketChannel, not a wire header.

None of these go through HeaderFilterStrategy, so adding "websocket." to setIn/OutFilterStartsWith cannot affect the echo flow at the transport boundary.

Likely root cause

The test was previously skipped on GitHub Actions via @DisabledIfSystemProperty(named = "ci.env.name", matches = ".*", disabledReason = "Flaky on GitHub Actions"). The annotation was removed by 685e1a4eca3 (CAMEL-22539, 2026-05-07) without other hardening of this specific test. This PR's CI run is among the first to actually exercise it on GHA, and the 10 s await timeout under a contended runner is the same failure shape that motivated the original disablement.

Local repro on fix/CAMEL-23588

Run against the PR branch with -Dci.env.name=github.com -Dsurefire.rerunFailingTestsCount=2:

• 5/5 isolated UndertowWsConsumerRouteTest#echo runs PASS (~1.1 s each)
• 3/3 full-class UndertowWsConsumerRouteTest runs PASS (~1.7 s each)

Suggested follow-ups (independent of this PR):

• Rerun the build (17, false) job to confirm the flake.
• Open a CAMEL Jira against camel-undertow for follow-up to CAMEL-22539 — either Awaitility-harden the test for slow GHA runners or restore @DisabledIfSystemProperty until it can be properly stabilized.

[gnodet]

Good defense-in-depth: extending UndertowHeaderFilterStrategy to filter the websocket.* prefix on both inbound and outbound. This prevents untrusted WebSocket clients from injecting headers that could be interpreted as configuration by downstream processors.

Adding WEBSOCKET_FILTER_STARTS_WITH = "websocket." to both in-filter and out-filter prefix lists is consistent with the existing pattern for Camel* and org.apache.camel.* prefixes. Upgrade guide with defense-in-depth guidance is well written.

LGTM.

Fully automatic review from Claude Code

[oscerd]

@apupier — rebased onto current main and force-pushed to refresh CI: the previous Build and test workflow was stuck in queued since 2026-05-26 (never picked up by a runner), which masked the underlying stale-red build state you flagged. The new push (892b30639) should trigger a fresh workflow run.

Will re-request your review once the new Build and test reports a result.

Claude Code on behalf of Andrea Cosentino

[davsclaus]

LGTM

[apupier]

so the new push retriggered a build (which is passing) but now there is a conflict to resolve

the old job is still stuck in the queue. I tried to cancel it but there is an error and i cannot. I hope this will be cleared when the PR will be merged