feat: add TcpStackAwareSocketChannel for z/OS TCP/IP stack recovery — GH#4776

[balhar-jakub]

Closes #4776

Problem

The z/OS TCP/IP stack can restart (EDC5122I / NetworkRecycledException) while Tomcat is reading from or writing to an accepted client socket. Tomcat must discard the dead connection safely.

Fix

• Refactored isTcpStackRestarted and isRecycledClass from instance methods to package-private static methods on TomcatAcceptFixConfig
• Added the opt-in apiml.tcpStackAwareSocketChannel.enabled configuration property, defaulting to false so non-z/OS deployments are unaffected
• Created ExcludedSocketOps interface for Lombok @Delegate exclusion list
• Created TcpStackAwareSocketChannel inner class:
  • Intercepts read(ByteBuffer), read(ByteBuffer[], int, int), write(ByteBuffer), write(ByteBuffer[], int, int)
  • Detects EDC5122I/NetworkRecycledException, safely closes the dead socket, and re-throws so Tomcat discards the connection
  • Delegates wrapper close and blocking-mode behavior safely to the accepted socket
• Added unit coverage for read/write variants, socket closure, configuration disabled/enabled behavior, and z/OS restart detection

Configuration

This is a z/OS-only mitigation and is disabled by default. Enable it only for affected z/OS deployments after staging validation:

apiml:
  tcpStackAwareSocketChannel:
    enabled: true

Validation

• ./gradlew :apiml-tomcat-common:clean :apiml-tomcat-common:build — BUILD SUCCESSFUL (77 tests)
• ./gradlew clean && ./gradlew build — BUILD SUCCESSFUL

[balhar-jakub]

QA + Security Review — PR #4792 (#4776)

Verdict: APPROVED

Build and Tests

• ./gradlew :apiml-tomcat-common:clean build — BUILD SUCCESSFUL, 76/76 tests pass
• 16 new tests added covering all read/write/safeClose/config scenarios

Pavel's Lens — All 8 Rules Checked

Rule	Status	Notes
1. Config Consistency	OK	apiml.tcpStackAwareSocketChannel.enabled has Spring default :true. Follows existing undocumented pattern (same as server.tomcat.retryRebindTimeoutSecs).
2. Deduplication	OK	isTcpStackRestarted/isRecycledClass properly extracted to static methods. Old instance method delegates. Minor: NETWORK_RECYCLED_EXCEPTION_CLASS constant on line 176 is now dead code — not used after refactor. Suggest removing in follow-up.
3. Null Safety	OK	isTcpStackRestarted checks getMessage() != null, getCause() != null, cause != t (cycle guard).
4. Test Parametrization	OK	Tests are varied enough (read/write, single/scatter, pass/fail, config on/off, integration) to not collapse cleanly into parameterized. 16 distinct test cases with good edge coverage.
5. Security Boundaries	OK	No auth/TLS/CORS/input validation changes. This is z/OS socket infrastructure. Config toggle safely disables. No secrets, no data exposure. safeClose is best-effort with catch-and-ignore.
6. z/OS Awareness	EXCELLENT	Purpose-built for z/OS TCP/IP stack recovery. Handles EDC5122I and com.ibm.net.NetworkRecycledException. Graceful degradation via config toggle.
7. Log Quality	OK	All log.debug with exception context. Messages identify operation type (read/scatter read/write/scatter write). safeClose silently swallows close errors — correct for best-effort.
8. TODO Tracking	OK	No TODO/FIXME/HACK comments found.

Minor Notes (non-blocking)

1. NETWORK_RECYCLED_EXCEPTION_CLASS constant (line 176) is dead code after the static refactor — can be cleaned up in a follow-up.
2. Instance isTcpStackRestarted wrapper (lines 277-279) delegates to static version — may still be referenced by pre-existing tests calling channel.isTcpStackRestarted(). Acceptable.

Security Assessment

• No new auth/authz boundaries introduced
• No input validation changes
• No secrets or credentials in code
• No data exposure via logs (debug level, exception context only)
• MethodHandle usage for implCloseSelectableChannel/implConfigureBlocking follows existing pattern in FixedServerSocketChannel
• @Delegate with ExcludedSocketOps correctly excludes final methods and manually overridden methods

APPROVED — ready for merge.

[balhar-jakub]

DCO check failed — all 3 commits are missing Signed-off-by lines.

Fix: git rebase --signoff v3.x.x && git push --force-with-lease

[sonarqubecloud]

Quality Gate failed

Failed conditions
78.6% Coverage on New Code (required ≥ 80%)
C Reliability Rating on New Code (required ≥ A)

See analysis details on SonarQube Cloud

💡 Need a hand with PR review? Try Gitar by Sonar!

[balhar-jakub]

Multi-Reviewer Review

Verdict: Approve with minor NITs.

Findings:

• ℹ️ NIT — Typo in IMPL_CLOSE_SELECTABGLE_CHANNEL_HANLE (should be HANDLE) — pre-existing, but inherited.
• ℹ️ NIT — Method counts in ExcludedSocketOps comment are slightly off (14/6 split is approximate).
• ℹ️ NIT — close() is excluded but not overridden — defense-in-depth via implCloseSelectableChannel() works.
• ℹ️ NIT — No toString() override.
• ℹ️ NIT — safeClose swallows IOException silently; consider trace-level log.
• ✅ Test coverage is excellent (every read/write variant tested, mockStatic for NetworkRecycledException).

Good:

• Feature flag apiml.tcpStackAwareSocketChannel.enabled defaults to false — safe opt-in.
• @Delegate approach correctly handles 20 excluded methods + delegates the rest.
• isTcpStackRestarted now static (was instance) — cleaner since no instance state needed.
• New tests cover both the existing isTcpStackRestarted and the new TcpStackAwareSocketChannel.

Optional follow-up:

• Update apiml-tomcat-common CHANGELOG / docs to mention the new flag.
• Consider a tenant-level integration test that toggles the flag and verifies behavior.

Required before merge: none. All findings are NIT-level polish.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
87.8% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[richard-salac]

The start.sh scripts are missing support for the new configuration property.

[richard-salac]

When the feature is enabled on z/OS, APIML is not able to accept connections and logs:

2026-08-28 15:29:24.836 <ZWEAGW1:https-jsse-nio-0.0.0.0-10010-Poller:33620144> ZWESVUSR ERROR (o.a.t.u.n.NioEndpoint) Failed to register socket with selector from poller
java.nio.channels.IllegalSelectorException
	at java.base/sun.nio.ch.SelectorImpl.register(SelectorImpl.java:253)
	at java.base/java.nio.channels.spi.AbstractSelectableChannel.register(AbstractSelectableChannel.java:236)
	at org.apache.tomcat.util.net.NioEndpoint$Poller.events(NioEndpoint.java:1004)
	at org.apache.tomcat.util.net.NioEndpoint$Poller.run(NioEndpoint.java:1066)
	at java.base/java.lang.Thread.run(Thread.java:854)
2026-08-28 15:29:26.401 <ZWEAGW1:https-jsse-nio-0.0.0.0-10010-Poller:33620144> ZWESVUSR ERROR (o.a.t.u.n.NioEndpoint) Failed to register socket with selector from poller
java.nio.channels.IllegalSelectorException
	at java.base/sun.nio.ch.SelectorImpl.register(SelectorImpl.java:253)
	at java.base/java.nio.channels.spi.AbstractSelectableChannel.register(AbstractSelectableChannel.java:236)
	at org.apache.tomcat.util.net.NioEndpoint$Poller.events(NioEndpoint.java:1004)
	at org.apache.tomcat.util.net.NioEndpoint$Poller.run(NioEndpoint.java:1089)
	at java.base/java.lang.Thread.run(Thread.java:854)