chore: Coordinate PR merge order and integration dependencies #158

Context

Several open PRs introduce related fixes and features across the WAMP transport, connection lifecycle, observability, and security layers.

Some PRs are explicitly stacked on others, while independent changes modify the same components and may introduce integration conflicts or regressions.

This tracking issue proposes a coherent merge sequence to:

• Make reviews easier by keeping related changes together.
• Respect actual Git dependencies.
• Reduce repeated rebases and merge conflicts.
• Stabilize concurrency-sensitive code before extending it.
• Preserve existing behavior when combining independent changes.

The sequence below is a proposal, not a strict requirement. Independent PRs can progress in parallel.

Proposed merge batches

Batch 1 — Stabilize the WAMP client

• fix(ocpp-wamp): fix the client races behind the flaky ocpp-wamp tests #147 — Fix client races and flaky tests
• fix(ocpp-wamp): report a failed connection as a connection failure #151 — Correct connection failure notifications
• fix(ocpp-wamp): run client call handlers on Dispatchers.IO #146 — Run blocking client handlers on Dispatchers.IO

Rationale: Establish reliable client behavior before integrating additional client-side features.

Integration notes:

• fix(ocpp-wamp): fix the client races behind the flaky ocpp-wamp tests #147 and fix(ocpp-wamp): run client call handlers on Dispatchers.IO #146 both modify OkHttpOcppWampClient.onMessage.
• Preserve the connection snapshot introduced in fix(ocpp-wamp): fix the client races behind the flaky ocpp-wamp tests #147 when applying the execution changes from fix(ocpp-wamp): run client call handlers on Dispatchers.IO #146.
• Re-run concurrency and shutdown tests after integration.

Batch 2 — Stabilize WebSocket endpoints and connection lifecycle

• fix(ocpp-wamp): refuse a websocket upgrade outside the endpoint path #145 — Fix endpoint path matching
• fix(ocpp-wamp): serialize the connection lifecycle of each station #150 — Serialize the connection lifecycle per station
• fix(ocpp-wamp): keep a station connected when its connection listener fails #153 — Isolate failing connection listeners
• Close fix(ocpp-wamp): register a reconnecting station atomically #143 as superseded by fix(ocpp-wamp): serialize the connection lifecycle of each station #150

Dependencies:

• fix(ocpp-wamp): keep a station connected when its connection listener fails #153 is stacked on fix(ocpp-wamp): serialize the connection lifecycle of each station #150.
• fix(ocpp-wamp): serialize the connection lifecycle of each station #150 supersedes fix(ocpp-wamp): register a reconnecting station atomically #143.

Rationale: Ensure endpoint routing, connection registration, reconnection, and event notifications are reliable before introducing additional admission and security mechanisms.

Integration notes:

• Preserve per-station event ordering.
• Ensure listener exceptions cannot leave registered connections unusable.
• Check that per-station locks are eventually released.
• Validate concurrent connections and shutdown behavior.

Batch 3 — Server observability and security

• feat(observability): report OCPP processing errors to an optional listener #128 — Introduce server-side OCPP error reporting
• fix(ocpp-wamp): refuse the WebSocket handshake when every handler refuses #134 — Refuse handshakes when no handler accepts
• feat(ocpp-wamp)!: admit a charging station from its upgrade request headers #154 — Introduce request-header-based connection authorization
• feat(ocpp-wamp): enforce the Basic authentication of each charging station #157 — Enforce per-station Basic authentication

Confirmed dependency chain:

#128 → #134 → #154 → #157

These are stacked PRs and should be merged in this order.

Integration notes:

• fix(ocpp-wamp): refuse a websocket upgrade outside the endpoint path #145 should be integrated before feat(ocpp-wamp)!: admit a charging station from its upgrade request headers #154 to ensure correct routing with multiple WebSocket endpoints.
• Preserve the exactly-once error reporting guarantees of feat(observability): report OCPP processing errors to an optional listener #128.
• Validate HTTP handshake outcomes (101, 401, 404).
• Check that credentials never appear in logs.
• Test both BLOCK and REPORT authentication enforcement.
• feat(ocpp-wamp): enforce the Basic authentication of each charging station #157 covers Basic authentication only; TLS and client certificate enforcement remain separate follow-up work.

Batch 4 — Client observability and configuration

• feat(observability): report client-side processing errors to a listener #139 — Add client-side OCPP error reporting
• feat(transport-websocket): expose the OcppWampClient tuning on WebsocketClient #144 — Expose WAMP client configuration
• feat(websocket): choose per station the zone of timestamps without timezone #138 — Support per-station fallback timezones

Dependencies and interactions:

• feat(observability): report client-side processing errors to a listener #139 is stacked on feat(observability): report OCPP processing errors to an optional listener #128.
• feat(observability): report client-side processing errors to a listener #139 and feat(transport-websocket): expose the OcppWampClient tuning on WebsocketClient #144 both modify the WAMP client construction API.
• feat(websocket): choose per station the zone of timestamps without timezone #138 and feat(observability): report client-side processing errors to a listener #139 both modify WebsocketServer, including inbound call processing.

Integration notes:

• Preserve errorListener propagation through the settings-based client constructor introduced by feat(transport-websocket): expose the OcppWampClient tuning on WebsocketClient #144.
• Re-run WebsocketClientErrorListenerTest.
• Ensure the shared answerCall logic introduced by feat(observability): report client-side processing errors to a listener #139 retains the per-station timestamp parsing behavior of feat(websocket): choose per station the zone of timestamps without timezone #138.
• Add or verify a regression test combining both features. This interaction could otherwise silently restore UTC parsing instead of the configured station timezone.

CI and merge readiness

At the time of this proposal, the latest builds of these PRs were failing:

• feat(transport-websocket): expose the OcppWampClient tuning on WebsocketClient #144 — WampIntegrationTest, shutdown with an in-flight call
• fix(ocpp-wamp): run client call handlers on Dispatchers.IO #146 — CSMSStopTest, pending call during shutdown
• fix(ocpp-wamp): serialize the connection lifecycle of each station #150 — WampIntegrationTest, inbound call during draining
• feat(ocpp-wamp): enforce the Basic authentication of each charging station #157 — CSMSStopTest, pending call during shutdown

These failures may be related to existing concurrency issues, particularly those addressed by #147, but that has not been demonstrated for every case.

Before merging the affected PRs:

• Rebase on the updated dev branch.
• Re-run the full build.
• Investigate any remaining failures rather than assuming they are flaky.
• Repeat concurrency-sensitive tests where appropriate.
• Verify that the final integration retains the regression tests from each PR.

Merge strategy

Suggested workflow:

1. Review and merge each PR independently.
2. Rebase stacked descendants after their parent PR merges.
3. Review the resulting reduced diff rather than the original stacked diff.
4. Run CI after each integration.
5. Review combined behavior wherever independently developed PRs modify the same execution path.
6. Keep this issue updated as dependencies or priorities evolve.

The batches represent logical integration milestones, not release boundaries.

Maintainer feedback

@pbourseau — Does this grouping and order make sense from a maintainer's perspective?

In particular, feedback would be useful on:

• Whether fix(ocpp-wamp): serialize the connection lifecycle of each station #150/fix(ocpp-wamp): keep a station connected when its connection listener fails #153 should be integrated before the observability/security stack.
• Whether the remaining client changes should follow fix(ocpp-wamp): fix the client races behind the flaky ocpp-wamp tests #147 to reduce CI instability.
• Whether feat(websocket): choose per station the zone of timestamps without timezone #138/feat(observability): report client-side processing errors to a listener #139 should receive an explicit combined regression test before merging.
• Whether any batch should be split further to keep the review scope manageable.

The goal is to make the remaining PRs easier to review and integrate without introducing unnecessary process overhead.