h2: retry streams reset with REFUSED_STREAM or rejected by GOAWAY (RFC 9113 8.7)

A stream reset with REFUSED_STREAM, or rejected by GOAWAY
(stream_id > last_stream_id), is guaranteed unprocessed by the server and is
safe to retry even for non-idempotent requests (RFC 9113 section 8.7). The
client previously surfaced these as ProtocolError("HTTP/2 stream reset by
peer") / H2GoAwayError after a single attempt, with the RST_STREAM error code
discarded.

- New H2StreamResetError carries the RFC 9113 section 7 error code; the
  RSTStreamFrame handler stores it instead of a generic ProtocolError, and
  showerror names the code (REFUSED_STREAM, CANCEL, ENHANCE_YOUR_CALM, ...).
- _retryable_request_error classifies REFUSED_STREAM resets and H2GoAwayError
  as retryable; _h2_guaranteed_unprocessed lifts the idempotent-method gate
  for them (the replayable-body gate still applies).
- The existing _drop_h2_conn! on error already makes the retry use a fresh
  connection.

Greens the tests added in the previous commit.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: 2 people

src/http2_client.jl

@@ -38,6 +38,37 @@ function Base.showerror(io::IO, err::H2GoAwayError)
     return nothing
 end
 
+# RFC 9113 §7 error codes (0x0–0xd).
+const _H2_ERROR_CODE_NAMES = (
+    "NO_ERROR", "PROTOCOL_ERROR", "INTERNAL_ERROR", "FLOW_CONTROL_ERROR",
+    "SETTINGS_TIMEOUT", "STREAM_CLOSED", "FRAME_SIZE_ERROR", "REFUSED_STREAM",
+    "CANCEL", "COMPRESSION_ERROR", "CONNECT_ERROR", "ENHANCE_YOUR_CALM",
+    "INADEQUATE_SECURITY", "HTTP_1_1_REQUIRED",
+)
+const _H2_REFUSED_STREAM = UInt32(0x7)
+
+function _h2_error_code_name(code::UInt32)::String
+    code < UInt32(length(_H2_ERROR_CODE_NAMES)) && return _H2_ERROR_CODE_NAMES[Int(code) + 1]
+    return string("0x", string(code; base = 16))
+end
+
+"""
+    H2StreamResetError
+
+Raised when the peer resets an HTTP/2 stream with `RST_STREAM`. Carries the
+RFC 9113 §7 `error_code`. `REFUSED_STREAM` guarantees the stream was closed
+prior to any processing (RFC 9113 §8.7), so such requests are retried when
+retries are enabled.
+"""
+struct H2StreamResetError <: HTTPError
+    error_code::UInt32
+end
+
+function Base.showerror(io::IO, err::H2StreamResetError)
+    print(io, "HTTP/2 stream reset by peer: ", _h2_error_code_name(err.error_code))
+    return nothing
+end
+
 """
     H2StreamState
 
@@ -762,7 +793,7 @@ function _process_incoming_frame!(conn::H2Connection, frame::AbstractFrame)
         rst = frame::RSTStreamFrame
         state = _stream_state(conn, rst.stream_id)
         state === nothing && return nothing
-        _set_stream_error!(state::H2StreamState, ProtocolError("HTTP/2 stream reset by peer"))
+        _set_stream_error!(state::H2StreamState, H2StreamResetError(rst.error_code))
         return nothing
     elseif frame isa WindowUpdateFrame
         update = frame::WindowUpdateFrame

src/http_client_retry.jl

@@ -48,6 +48,10 @@ end
 function _retryable_request_error(err::Exception)::Bool
     current = err
     while true
+        # RFC 9113 §8.7: a stream reset with REFUSED_STREAM, or rejected by
+        # GOAWAY (stream_id > last_stream_id), was not processed by the server.
+        current isa H2StreamResetError && return (current::H2StreamResetError).error_code == _H2_REFUSED_STREAM
+        current isa H2GoAwayError && return true
         current isa EOFError && return true
         current isa SystemError && return true
         current isa ParseError && return true
@@ -72,6 +76,22 @@ end
 
 _retryable_request_error(err::RequestRetryError)::Bool = _retryable_request_error(err.err)
 
+# RFC 9113 §8.7: requests on streams reset with REFUSED_STREAM or rejected by
+# GOAWAY are guaranteed unprocessed, hence safe to retry regardless of method
+# idempotency. The replayable-body gate in `_should_retry_request_attempt`
+# still applies.
+function _h2_guaranteed_unprocessed(err)::Bool
+    current = err
+    while true
+        if current isa RequestRetryError
+            current = (current::RequestRetryError).err
+            continue
+        end
+        current isa H2StreamResetError && return (current::H2StreamResetError).error_code == _H2_REFUSED_STREAM
+        return current isa H2GoAwayError
+    end
+end
+
 function _retry_hook_decision(controller::_RetryController, attempt::Int, err, req::Request, resp)
     hook = controller.retry_if
     hook === nothing && return nothing
@@ -86,7 +106,8 @@ function _should_retry_request_attempt(controller::_RetryController, attempt::In
     _retryable_request_body(req) || return false
     built_in = false
     if err !== nothing
-        built_in = _retryable_policy_request(req, controller.retry_non_idempotent) && _retryable_request_error(err)
+        policy_ok = _retryable_policy_request(req, controller.retry_non_idempotent) || _h2_guaranteed_unprocessed(err)
+        built_in = policy_ok && _retryable_request_error(err)
     elseif resp !== nothing
         built_in = _retryable_policy_request(req, controller.retry_non_idempotent) && _retryable_status((resp::Response).status)
     end