Skip to content

Fix CacheControl caching of consumed mock responses - #846

Open
Aschenbath wants to merge 1 commit into
getsentry:masterfrom
Aschenbath:fix/cachecontrol-consumed-body-780
Open

Aschenbath wants to merge 1 commit into
getsentry:masterfrom
Aschenbath:fix/cachecontrol-consumed-body-780

Conversation

@Aschenbath

@Aschenbath Aschenbath commented Nov 7, 2026 •

Copy link
Copy Markdown

What type of PR is this?

  • Bug Fix

Description

The bug is in the byte-buffer lifetime created by responses._handle_body(). The old implementation attached an is_closed() function to a plain BytesIO: reaching EOF in read() left data.closed == False, and the buffer closed only when urllib3 subsequently called isclosed().

That timing misses CacheControl's cache-write callback. CacheControlAdapter.build_response() wraps the mocked response's _fp in CallbackFileWrapper. Its read() reads the underlying body, copies the bytes into its own buffer, then checks fp is None or closed and calls _close() to commit the cache entry. A BytesIO has no fp attribute, so this check sees its still-false closed property. urllib3's later isclosed() probe closes the original buffer after that opportunity has passed. The adapter does run; the body-completion signal arrives too late.

_BodyBuffer.read() now closes the mock before returning from an unbounded read, or from a nonzero sized read that returns EOF. CacheControl consequently sees closure during its own read() and invokes its existing callback. isclosed() only reports state. Positive sized reads that return bytes, zero-byte reads, partial consumption, and caller-provided BufferedReader objects retain their previous handling. CacheControl is a test-only dependency; production code has no CacheControl-specific branch.

The boundary is deliberate: a positive sized read returning the last bytes does not close early. urllib3 must get the subsequent empty read while checking a remaining Content-Length; closing as soon as the cursor reaches the buffer length can bypass its truncated-body error path. The added streaming tests verify that ChunkedEncodingError still occurs. This change does not expand the existing unbounded-read behavior for a truncated Content-Length.

Alternatives considered:

  • Changing only the old isclosed() return value still leaves closure after CacheControl's post-read check.
  • Closing on the final nonempty sized read avoids the extra EOF read but risks the Content-Length behavior above.
  • Eagerly consuming/caching the body changes streaming and partial-consumption semantics. The response should become cacheable only after consumption, under CacheControl's own cache policy.
  • Special-casing or patching CacheControl's wrapper adds dependency-specific coupling when the mock can provide the expected file lifecycle itself.

The reproduction supplies Date and Cache-Control so the response is eligible for caching; the simplified issue example omits them. This identifies the failure mechanism, without claiming which release between 0.12.1 and 0.25.8 introduced it.

This review update changes the explanation only. The validation below was recorded for the unchanged code head 7b9749c8; it is not a claim that the full matrix was rerun for this description edit.

Related Issues

Fixes #780.

PR checklist

  • Read the contributing guidelines.
  • Ran the complete tox matrix locally.
    Full pytest on Python 3.12.12: 289 passed, 18 existing deprecation warnings, 99% coverage. All-files pre-commit and all changed-file hooks pass. Both configured mypy commands report the same three existing errors on the exact base and candidate, with no new diagnostic.
  • Added the change to CHANGES.

Added/updated tests?

  • Yes: 28 cases cover ordinary/callback responses, empty/nonempty bodies, content/stream/raw reads, optional Content-Length, incomplete consumption, no-store and truncated bodies. On the unchanged base: 25 fail and 3 pass; its uncached temporary files additionally cause teardown resource warnings.

Independent Codex review exercised 68 real CacheControl scenarios per environment, including gzip, zero-byte reads, readinto and partial close. All 32 expected cache hits now occur; the unchanged base has none. Existing urllib3 read/read1/stream traces remain unchanged for the checked journeys.

Compatibility checks include requests 2.32.4 / CacheControl 0.14.2 with urllib3 1.26.20 and 2.8.0 on Python 3.12, plus requests 2.30.0 / urllib3 1.25.10 / CacheControl 0.13.0 on Python 3.11. Each of these three cells passes 42 related tests. The minimum-library cell explicitly pins a yanked CacheControl version and needs its legacy six ImportWarnings reported normally instead of treated as errors. Python 3.8 and macOS were not run locally.

Sdist/wheel builds pass. The installed wheel passes all 28 new tests and the independent 68 cache scenarios; all five packaged source/resource files match the checkout. Existing unbounded-read behavior for a truncated Content-Length is not expanded by this change.

AI assistance: OpenAI Codex investigated, implemented and tested the change. A separate Codex agent reviewed the code and independently verified real HTTP-response behavior, compatibility cells and the installed wheel. No human review is claimed.

@Aschenbath
Aschenbath requested a review from markstory as a code owner November 7, 2026 23:02

@pbhandari pbhandari left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Where specifically in the code is the bug? What specifically does this change do to fix it? What other options were considered?

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.

How to use responses with cachecontrol?

2 participants