Skip to content

Fix async event fetches sending usage as an API parameter - #1996

Open
ajaykr0905 wants to merge 1 commit into
stripe:masterfrom
ajaykr0905:fix/1948-async-raw-request-usage
Open

ajaykr0905 wants to merge 1 commit into
stripe:masterfrom
ajaykr0905:fix/1948-async-raw-request-usage

Conversation

@ajaykr0905

Copy link
Copy Markdown

Why?

StripeClient.raw_request() removes the internal usage keyword from params and reports it as request telemetry. raw_request_async() does not do this. It always reports ["raw_request", "async"] and keeps the caller's usage in params.

The async event notification helpers pass usage=[...] to raw_request_async(). Thus fetch_related_object_async() and fetch_event_async() add usage[0]=... to the query string. I ran the repro from the issue against stripe-mock. The async call for a /v1/billing/meters/... related object failed with InvalidRequestError (additional properties are not allowed). The sync call for the same object passed.

After this change, the async helpers send no usage parameter. Telemetry reports the tags that the caller passed, plus "async".

What?

  • raw_request_async() removes usage from params when the value is a list. It passes that list to telemetry. All 630 internal call sites that pass usage to raw_request() or raw_request_async() pass a list.
  • Any other usage value stays in params, as on master. For example, usage="off_session" is a real parameter of the SetupIntents API.
  • The list check is necessary. With a plain copy of the sync line, a string usage raises TypeError, because request_raw_async() runs usage + ["async"].
  • In tests/test_v2_event.py, an async stub expected the leaked usage[0]=fetch_related_object query. The stub now expects no query string. A new async test checks fetch_event_async() and fetch_related_object_async().
  • In tests/test_raw_request.py, 3 async tests replace the commented-out async test. They check the default telemetry, a list usage and a string usage.
  • The changefile is .hark/changes/2026-11-16_ajaykr0905_async-event-fetch-usage.change.md (patch).

I did not change the sync raw_request(). It still removes every usage value. Thus a sync usage="off_session" does not reach the API. That is older behavior, and this PR keeps it.

Test Plan

I ran all checks on macOS arm64. stripe-mock 0.206.0 ran in Docker with the pinned v2596 spec and fixtures, as in CI.

Revert check on Python 3.13.9, with tests/test_raw_request.py and tests/test_v2_event.py:

stripe/_stripe_client.py Tests Result
this branch this branch 43 passed
master this branch 6 failed, 37 passed
master with dae3d69 this branch 2 failed with TypeError, 41 passed
this branch only test_v2_event.py, from master 2 failed, 26 passed

On master, 3 tests fail on each anyio backend (asyncio and trio). The failing tests show the leaked query strings and the wrong telemetry. With the old stub, the stub test fails because the request now has no query string.

Full suite with pytest, as just test runs it (-n auto from pyproject.toml):

  • CPython 3.9.24, 3.10.19, 3.11.14, 3.12.12, 3.13.9 and 3.14.7: 4475 passed, 7 skipped on each version.
  • The 7 skipped tests are 6 aiohttp tests on trio and 1 Windows-only test.

Static checks from .github/actions/static-checks, on Python 3.13.9 with the pinned tool versions:

  • mypy: no issues found in 2 source files.
  • python -m flake8 --show-source stripe tests: no findings.
  • ruff format . --check: 1738 files already formatted.
  • pyright 1.1.336: 0 errors, 0 warnings.

Other checks:

  • hark validate (v1.2.0, the release that CI installs): validated 632 changefiles.
  • python -m build and twine check on Python 3.10.19: both artifacts passed.

The repro from the issue, against stripe-mock:

  • Before: fetch_related_object_async() sent GET /v1/billing/meters/mtr_123?usage[0]=fetch_related_object and failed with InvalidRequestError.
  • After: it sent GET /v1/billing/meters/mtr_123 and returned a Meter. Telemetry reported ["fetch_related_object", "async"].
  • stripe-mock returned Unrecognized request URL for GET /v2/core/events/evt_1, for the sync and the async call. For fetch_event_async(), I could only check the URL. After the fix, the URL has no query string.

I did not run these:

  • The PyPy jobs and the Windows job from the CI matrix.
  • Any job on Linux.
  • Requests to the live Stripe API.
  • just itself. I ran the commands that its recipes run.

See Also

Fixes #1948

Configuration

  • skip-changefile: This PR is not a user-facing change, so there's no changefile.

StripeClient.raw_request pops the internal `usage` kwarg and reports it
as request telemetry. raw_request_async did not: it always reported
["raw_request", "async"] and left `usage` in params. The async event
notification helpers pass usage=[...], so fetch_related_object_async()
and fetch_event_async() added usage[0]=... to the request. stripe-mock
rejects that query parameter on GET /v1/billing/meters/{id}.

Pop `usage` in raw_request_async when it is a list. The SDK's internal
callers always pass one. Any other value, such as a SetupIntent's
usage="off_session", is a real API parameter and stays in params, as it
did before. A plain copy of the sync pop would pass that string to
request_raw_async, which raises TypeError on usage + ["async"].

The async stub in test_v2_event.py expected the leaked
usage[0]=fetch_related_object query, so it now expects no query string.

Fixes stripe#1948
@ajaykr0905
ajaykr0905 requested a review from a team as a code owner November 16, 2026 14:54
@ajaykr0905
ajaykr0905 requested review from zacchua-stripe and removed request for a team November 16, 2026 14:54
Comment thread stripe/_stripe_client.py
# append "async" to it.
usage = ["raw_request"]
if isinstance(params.get("usage"), list):
usage = params.pop("usage")

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.

this discards "raw_request" from the usage array, which we need to keep for logging usage through the raw_request mechanism.

@jar-stripe

Copy link
Copy Markdown
Contributor

Hi @ajaykr0905 thanks for the PR! Can you please edit your PR description down to be more compact (I'd say no greater than a screen's height)? You can use e.g. #1972 as an example of what we typically do.

This branch has not been deployed

No deployments
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.

Async fetch_related_object_async / fetch_event_async send "usage" as an API parameter

2 participants