Skip to content

docs: expand crate-level cancel safety section with HTTP/1 vs HTTP/2 - #4156

Open
MsfPablo wants to merge 1 commit into
hyperium:masterfrom
MsfPablo:docs/4054-cancel-safety
Open

docs: expand crate-level cancel safety section with HTTP/1 vs HTTP/2#4156
MsfPablo wants to merge 1 commit into
hyperium:masterfrom
MsfPablo:docs/4054-cancel-safety

Conversation

@MsfPablo

Copy link
Copy Markdown

Closes #4054.

The crate-level # Cancel safety section in src/lib.rs already pointed
readers at the per-future docs, but didn't itself answer the question
that an unstable_-doc reader actually has when they land on the crate
root: "what happens on the wire when I drop this?"

This change fills in the two-line stub with the protocol-specific
behavior, mirroring what SendRequest::send_request already says
downstream:

  • HTTP/1: dropping an in-flight request closes the underlying TCP
    connection (no in-protocol per-request abort), and any subsequent
    call on the same SendRequest returns Error::new_canceled().
  • HTTP/2: dropping resets the single stream with RST_STREAM
    (CANCEL error code); the shared connection stays usable for other
    in-flight and future requests.

The "see individual futures" pointer at the bottom is preserved so
the existing per-future Cancel safety docblocks remain the source of
truth for edge cases (e.g. the bidi client future or specific request
body streams).

Verified with cargo doc --no-deps — no new warnings introduced.

Disclosed: this contribution was prepared with the help of Claude (a
large language model). The human in the loop reviewed the diff against
the per-future Cancel safety paragraphs in
src/client/conn/http1.rs and src/client/conn/http2.rs and verified
the summary is faithful and not a paraphrase of anything external.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Document cancel safety

1 participant