[pjfanning]

Motivation

#3727 made the GraphStage TLS engine (pekko.stream.materializer.tls.engine = graph-stage) drain plaintext it has already accepted when the plaintext output is cancelled. If a TLS 1.3 peer sends close_notify during that drain, unwrap returns CLOSED, completeOrFlush completes the stage and pumpFinished cancels the user input. The accepted plaintext is discarded, and our own close_notify is never sent. In TLS 1.3, close_notify only closes the peer's sending direction, so the response could still have been delivered.

Modification

• In doUnwrap, when unwrap returns CLOSED while the stage is in the inbound-closed drain, accepted plaintext remains and the engine's outbound side is still open, stay in the drain instead of completing. The drain then finishes through the existing path: closeOutbound, send close_notify, complete.
• Document in the stream IO guide and both TLS DSL scaladocs that a TLS 1.3 close_notify does not end the drain, while a TLS 1.2 close_notify (which closes both SSLEngine directions) does.
• Add tests in TlsGraphStageCancellationSpec that drive a real client SSLEngine against the operator. The server accepts a response larger than its remaining ciphertext demand, its plaintext output is cancelled, and the client then sends close_notify. These run for IgnoreComplete and EagerClose, on TLS 1.3 (full response expected) and TLS 1.2 (prompt termination with a partial prefix expected).

Result

A TLS 1.3 peer that half-closes receives the accepted response followed by the server's close_notify. TLS 1.2 behaviour is unchanged and still terminates promptly. The legacy actor engine is unaffected.

Tests

• sbt "stream-tests / Test / testOnly org.apache.pekko.stream.io.TlsGraphStageCancellationSpec": the two TLS 1.3 tests failed before the fix (partial response) and pass after it; 6/6 pass.
• sbt "stream-tests / Test / testOnly org.apache.pekko.stream.io.Tls*": 281/281 passed.
• Native scalafmt and git diff --check passed.

References

Refs #3727

[He-Pin]

LGTM. Traced the state machine: in InboundClosedPhase the peer close_notify makes transportInput non-empty, so drainBeforeInboundClose goes false and doInbound reaches doUnwrap. Skipping completeOrFlush() there is safe because engine.isInboundDone then forces inboundHalfClosedReady/inboundHalfClosedCompleted, so the pump exits and the drain finishes via doOutbound -> closeOutbound -> FlushingOutboundPhase. No spin: phaseExecutable is false without transport demand, and OutputSlot.onPull re-runs the pump. The phase.toInt != InboundClosedPhase guard keeps AwaitingClosePhase and the bidirectional/outbound-closed paths unchanged. Extracting drainingAcceptedUserInput is the right call since drainBeforeInboundClose cannot express this state. Docs and both DSL scaladocs match the tested TLS 1.2 vs 1.3 behaviour.