Graceful shutdown (GOAWAY NO_ERROR) currently surfaces as TransportConnectionException

[aki1770-del]

Core Request: Consider exposing a graceful shutdown (GOAWAY with NO_ERROR) in a form that callers can distinguish from a forceful close.

Current Implementation: In pkgs/http2/lib/src/connection.dart, _terminate() is the only site for constructing TransportConnectionException, and it hardcodes "Connection is being forcefully terminated" regardless of whether the cause was a peer GOAWAY-NO_ERROR or an actual fault. This issue (#1364 open since 2019) and #1380 track the same surface from different angles.

Context: We initially tried to map errorCode == 0 at the gRPC layer (grpc/grpc-dart#827), but the maintainer correctly pointed out it's the wrong layer.

Proposed Shapes: In order of least disruptive:

a. A TransportConnectionException subtype constructed when errorCode == NO_ERROR.
b. Completing connection.done cleanly (without exception) on graceful close, which would be breaking but cleaner.
c. Some other shape entirely - RFC 7540 §6.8 leaves room for distinguishing graceful shutdown from error.

Migration Shape: The package's call. Happy to defer if there's a different priority.

[brianquinlan]

Would you be interested in proposing a PR to fix this?

[aki1770-del]

Yes — happy to draft. Approach: distinguish GOAWAY NO_ERROR at the _terminate() site by introducing a gracefulShutdown boolean on TransportConnectionException (or a new GracefulShutdownException extending it if you prefer the type-distinction). Tests for both branches. Open to either shape — let me know if you have a preference.

[brianquinlan]

The next release of package:http2 will be a breaking release so I'd vote for whatever the cleanest solution is (maybe b?)

@mosuem any thoughts?

[aki1770-del]

Reading more carefully — you're voting for issue-body (b): connection.done completes cleanly without exception on graceful close. That's the breaking-cleaner shape. Will draft per that. Apologies for the option-relabeling in my prior reply.

[brianquinlan]

Yes, that was my suggestion. I have limited state here though.

[aki1770-del]

Erratum (2026-05-17): I missed that PR #1917 has been open since 2026-05-10 implementing this shape, and its body already asks the same disambiguation. Apologies for the duplicate — the better venue is #1917 directly. Original comment preserved below for thread continuity.

---

On re-reading the public TransportConnection interface, I notice connection.done isn't there — that was my own phrasing in the issue body, not an existing public member. Apologies for the imprecision.

Three possible readings for shape (b):

1. Add a Future<void> get done getter to TransportConnection, completing cleanly on graceful close and with the exception on forceful. Biggest API change; matches the "cleanest in the breaking release" framing.
2. terminate()'s returned Future — but per the doc + catchError, this already never completes with an error, so behavior is already there.
3. Suppress the broadcast of TransportConnectionException to the stream/queue/ping/settings handlers when errorCode == NO_ERROR && !causedByTransportError; uses existing API surface, no new public member.

Happy to draft per any of these — which matches your intent?