trillium_http/h2/acceptor/close.rs
1use super::{
2 H2Driver,
3 types::{CloseOutcome, DriverState},
4};
5use crate::{
6 Conn,
7 graceful_close::GracefulClose,
8 h2::{H2Error, H2ErrorCode, stream_state::StreamEvent, transport::H2Transport},
9};
10use futures_lite::io::{AsyncRead, AsyncWrite};
11use std::{
12 io,
13 pin::Pin,
14 task::{Context, Poll},
15};
16
17impl<T> H2Driver<T>
18where
19 T: AsyncRead + AsyncWrite + Unpin + Send,
20{
21 /// Convert the current `close_outcome` into the terminal return of [`Self::drive`]. Must
22 /// only be called after outbound bytes have been flushed. Graceful closes return `None`;
23 /// errors surface as a final `Some(Err(...))` before subsequent polls return `None`.
24 pub(super) fn finish_with_current_outcome(
25 &mut self,
26 ) -> Option<Result<Conn<H2Transport>, H2Error>> {
27 self.finished = true;
28 // Shut the connection swansong down on every exit path, not just peer GOAWAY:
29 // it is the signal reuse decisions key on (`open_stream`, `can_open_stream`, and
30 // pooling clients' classify). A driver that dies on an I/O error or peer FIN while
31 // leaving the swansong running turns the connection into a landmine — a pool hands
32 // it out as available, `open_stream` publishes a stream no driver will ever
33 // service, and the response waiter parks forever. Must happen *before* the shared-
34 // map walk below: `open_stream` checks the swansong under the streams lock, so any
35 // stream that slips in concurrently either observes the shutdown and is refused,
36 // or was published before we take the lock and gets reset by the walk.
37 self.connection.shut_down();
38 // Complete every outstanding `H2Connection::send_ping` future with an error so
39 // awaiting callers don't block forever. Safe to call regardless of outcome —
40 // a no-op if no pings are in flight.
41 self.connection.fail_pending_pings(
42 io::ErrorKind::ConnectionAborted,
43 "h2 connection closed before PING ACK",
44 );
45 // Wake any `PeerSettings` waiters so a peer that disconnects without ever sending
46 // SETTINGS doesn't strand them. Their `poll` rechecks swansong state and returns
47 // Ready; the caller's follow-up operation surfaces the connection-closed error.
48 self.connection.wake_peer_settings_waiters();
49 // Resolve every still-live stream's recv-side waiters. A connection that dies with
50 // an in-flight stream (server GOAWAY + close, peer FIN, I/O error) leaves any task
51 // parked on the response — `response_headers`, a body `poll_read`, an upgrade
52 // `poll_write` — with no other wake source. Without this a client request hangs
53 // forever on a graceful server shutdown. Mirror the per-stream RST teardown:
54 // terminal `Reset` (recv reports eof → `ResponseHeaders` yields `ConnectionAborted`,
55 // reads return EOF, writes `BrokenPipe`) + the same waker fan-out.
56 let reset_code = match &self.close_outcome {
57 Some(CloseOutcome::Protocol(code)) => *code,
58 _ => H2ErrorCode::NoError,
59 };
60 // Walk the *shared* map, not the driver-private mirror: a client stream published
61 // between the driver's last pickup pass and this teardown exists only in the shared
62 // map, and every conn-task waiter (`response_headers`, body reads, `SubmitSend`)
63 // reaches its stream through the shared map — so this walk covers all of them.
64 for state in self.connection.streams_lock().values() {
65 // Move each still-live stream to `Closed{Reset}` (a no-op on streams already closed, so
66 // an existing reason isn't clobbered), then fan out every recv/send waker so parked
67 // tasks observe the close instead of hanging.
68 let _ = state.apply_event(StreamEvent::RecvReset(reset_code));
69 state.recv.waker.wake();
70 state.recv.response_headers_waker.wake();
71 state.send.outbound_write_waker.wake();
72 // A handler already parked in `SubmitSend` (response staged, awaiting the driver to
73 // frame it) needs this wake to re-poll and observe the now-reset stream — the recv
74 // fan-out above doesn't reach the send-completion waiter.
75 state.send.completion_waker.wake();
76 }
77 match self.close_outcome.take() {
78 None | Some(CloseOutcome::Graceful) => None,
79 Some(CloseOutcome::Protocol(code)) => Some(Err(H2Error::Protocol(code))),
80 Some(CloseOutcome::Io(e)) => Some(Err(H2Error::Io(e))),
81 }
82 }
83
84 /// Enter the closing state: record the outcome and queue a GOAWAY (only for outcomes
85 /// that warrant one). The main loop will drain `write_buf` and then finish.
86 pub(super) fn begin_close(&mut self, outcome: CloseOutcome) {
87 // Idempotent: with the recv pump now running in Closing (so we keep
88 // decoding inbound frames for in-flight streams across GOAWAY), a peer
89 // GOAWAY arriving after we've already begun closing would otherwise
90 // re-queue our own GOAWAY and re-enter Closing, ping-ponging forever
91 // with a peer that mirrors the behavior.
92 if self.state == DriverState::Closing || self.state == DriverState::Drained {
93 // A connection error during a graceful close still owes the peer its error GOAWAY.
94 if let CloseOutcome::Protocol(code) = outcome
95 && !matches!(self.close_outcome, Some(CloseOutcome::Protocol(_)))
96 {
97 self.close_outcome = Some(outcome);
98 self.queue_goaway(self.last_peer_stream_id, code);
99 return;
100 }
101 log::trace!(
102 "h2 driver: begin_close({outcome:?}) — already in {:?}, ignoring",
103 self.state,
104 );
105 return;
106 }
107 // Don't overwrite a prior outcome (e.g. if an error fires in the middle of a
108 // graceful shutdown, keep the error).
109 let code = match &outcome {
110 CloseOutcome::Graceful => Some(H2ErrorCode::NoError),
111 CloseOutcome::Protocol(code) => Some(*code),
112 CloseOutcome::Io(_) => None,
113 };
114 let reason = match &outcome {
115 CloseOutcome::Graceful => "graceful close",
116 CloseOutcome::Protocol(_) => "protocol error",
117 CloseOutcome::Io(_) => "i/o error",
118 };
119 if self.close_outcome.is_none() {
120 self.close_outcome = Some(outcome);
121 }
122 if let Some(code) = code {
123 self.queue_goaway(self.last_peer_stream_id, code);
124 }
125 self.set_state(DriverState::Closing, reason);
126 }
127
128 /// Log which in-flight streams are blocking the `Closing → Drained` transition.
129 /// Called from the closing-state check when at least one predicate (`has_active_send_cursors`
130 /// or `has_pending_recv`) is still true, so a trace log shows exactly which streams the
131 /// driver is waiting on.
132 pub(super) fn log_closing_blockers(&self) {
133 if !log::log_enabled!(log::Level::Trace) {
134 return;
135 }
136 for (id, entry) in &self.streams {
137 let lifecycle = *entry.shared.lifecycle_lock();
138 let queued = !entry
139 .shared
140 .send
141 .queue
142 .lock()
143 .expect("send queue mutex poisoned")
144 .is_empty();
145 if entry.send.is_some() || queued || !lifecycle.recv_closed() {
146 log::trace!(
147 "h2 driver: Closing — stream {id} blocking drain (lifecycle={lifecycle:?}, \
148 cursor_present={}, queued={queued})",
149 entry.send.is_some(),
150 );
151 }
152 }
153 }
154
155 /// Post-GOAWAY, drain whatever inbound bytes are *immediately* available from the
156 /// peer so our Drop sends a clean FIN (no unread data → no TCP RST) while the peer
157 /// sees the GOAWAY we just emitted. Read loops internally: consume each Ready chunk,
158 /// discard it, ask for more. Exits as soon as the transport returns `Pending` (no
159 /// bytes available right now) OR `Ready(0)` (peer FIN already arrived) OR any error.
160 ///
161 /// Does **not** register the waker on `Pending` — we're actively closing, not
162 /// observing the peer. Bytes the peer sends after this returns are [`Self::close`]'s to
163 /// wait out; dropping the transport instead answers them with a TCP reset.
164 ///
165 /// Returning `Ready(())` unconditionally (no `Pending` case) lets the caller finalize
166 /// immediately. The `Poll` wrapper is kept for symmetry with the rest of the driver's
167 /// poll-style methods.
168 pub(super) fn poll_drain_peer(&mut self, cx: &mut Context<'_>) -> Poll<()> {
169 // A peer flooding us with bytes could keep this loop going a long time. Cap it
170 // so a pathological client can't pin our close-out forever.
171 const MAX_DISCARD_ITERATIONS: usize = 256;
172 // Lightweight scratch — we're throwing it away. 512 balances "drain in few
173 // iterations" against "don't hold a large buffer for a rare path."
174 let mut scratch = [0u8; 512];
175 for _ in 0..MAX_DISCARD_ITERATIONS {
176 // We pass `cx` through for the benefit of the transport's `poll_read` contract,
177 // but we *interpret* `Pending` as "done draining" rather than parking on it —
178 // we're actively closing, not observing.
179 match Pin::new(&mut self.transport).poll_read(cx, &mut scratch) {
180 Poll::Ready(Ok(0) | Err(_)) | Poll::Pending => {
181 return Poll::Ready(());
182 }
183 Poll::Ready(Ok(_)) => {}
184 }
185 }
186 Poll::Ready(())
187 }
188
189 /// Close the connection: shut down our sending side of the transport, then read and discard
190 /// whatever the peer still sends until it closes its side.
191 ///
192 /// If the transport is dropped while the peer is still sending, the operating system answers
193 /// the peer's data with a TCP reset, which can destroy data the peer hasn't read yet — our
194 /// final GOAWAY, or the end of a response. Waiting for the peer to close avoids that. A peer
195 /// that never closes keeps this waiting indefinitely, so bound it with a timeout.
196 ///
197 /// Call this once [`Self::next`] returns `None` or an error. Closing a driver that hasn't
198 /// finished ends the connection without a GOAWAY, resetting any streams still in flight.
199 pub async fn close(mut self) {
200 if !self.finished {
201 self.finish_with_current_outcome();
202 }
203
204 let reads_per_yield = self.config.copy_loops_per_yield();
205 GracefulClose::new(self.transport, self.read_buf, reads_per_yield).await;
206 }
207}