Repository navigation
feat(keycardai-oauth): poll until done for the device grant - #433
Conversation
c6a3563 to
4c8abd7
Compare
4c8abd7 to
da39f13
Compare
da39f13 to
7e8c8c3
Compare
Release previewkeycardai-oauth 0.35.2 → 0.36.0 (minor)
No other package releases. This comment was automatically generated by the release preview workflow. |
7e8c8c3 to
99bc4fe
Compare
| if _is_transient_status(e.status_code): | ||
| raise DevicePollError(interval, e) from e | ||
| if isinstance(e, DeviceAuthorizationError): | ||
| if e.error == "authorization_pending": | ||
| continue |
There was a problem hiding this comment.
🟡 (optional) When a server answers slow_down with HTTP 429, callers who resume polling keep the old rate, breaking RFC 8628's MUST to add 5 seconds. The transient-status check at client.py:1487 runs before the slow_down branch. It raises DevicePollError(interval) without adding SLOW_DOWN_INCREMENT, so error.interval drops the server's request to slow down. Fix: when the error is a DeviceAuthorizationError with error == "slow_down", add SLOW_DOWN_INCREMENT before raising DevicePollError on a 429 or 5xx, while still raising DevicePollError for those statuses.
Why this was flagged
This needs a zone or a rate-limiting proxy in front of it that returns {"error":"slow_down"} with HTTP 429, a pairing this checkout cannot rule out. _json_object (operations/_device_authorization.py:152-161) turns that response into DeviceAuthorizationError(error="slow_down", status_code=429). In wait_for_device_token, _is_transient_status(e.status_code) at client.py:1487 is true, so the loop raises DevicePollError(interval, e) at client.py:1488. The interval += SLOW_DOWN_INCREMENT branch at client.py:1493 never runs. A caller that resumes with interval=error.interval, as the docstring, README and examples/device_authorization/main.py:58-59 all advise, polls at the same rate the server just asked it to slow. If the server keeps answering 429 slow_down, every resume returns the same interval until the caller gives up or the code expires. Nothing in the tests covers 429 with a slow_down body: row-17-429 at test_device_authorization.py:1102 sends a non-OAuth body.
Verification: Trigger: a zone, or a proxy in front of it, answers a poll with {"error":"slow_down"} on HTTP 429. In wait_for_device_token (client.py), _is_transient_status (exceptions.py:337-340) returns True for a 429, so the slow_down branch is never reached, and DevicePollError.interval lacks the +5. No test pins this case.
Adds AsyncClient.wait_for_device_token, which polls until the person approves or denies the request, per RFC 8628 Section 3.5 and the spec's poll-until-done rules. It waits the interval before each poll, including the first, through the client's clock. On authorization_pending it polls again, and on slow_down it adds 5 seconds to the interval for the next poll and every later one. When the next poll would start after expires_at, it raises an expired_token DeviceAuthorizationError without polling. It checks expires_at before and after each wait. A network error, a 429, or a 5xx stops the loop with DevicePollError. Its interval is the wait the loop would have used next, doubled after a network error. Its cause is the original failure, including the DeviceAuthorizationError of a 429 or 5xx with an OAuth error body. To resume, call wait_for_device_token again with interval=error.interval. Any other failure returns as is, including a credential whose client authentication fails. Task cancellation ends the wait or the request in flight. After it, the loop does not call the credential or send another request. The client's timeout applies to each poll, also under a longer caller deadline. An empty device_code, a non-positive authorization.interval, or an interval argument that is not an integer is a ConfigError. examples/device_authorization runs the flow against a zone. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Row 9 is a table. The new rows send two slow_down responses, in a row and with a pending between them, and expect the interval to rise by 5 each time (RFC 8628 Section 3.5). A loop that resets to authorization.interval + 5 fails them. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The loop stops with DevicePollError on the same 429 or 5xx rule that RefreshGrantError and DeviceAuthorizationError use for retryable. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
99bc4fe to
259e817
Compare
Larry-Osakwe
left a comment
There was a problem hiding this comment.
Loop order, slow_down, the doubling and cancellation all match the spec, and the tests ran green for me. The recheck after the wait is a good catch: Java and TS #343 don't do it, and the spec has no row for it yet. I'll take a spec row and the Java fix (SDK-119).
…xpired poll until done checks expires_at before and after each wait. The check before the wait says the code expires before the next poll. The check after the wait says it expired during the wait. Both raise expired_token. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Adds
AsyncClient.wait_for_device_token, which polls until the person approves or denies the request, per RFC 8628 §3.5 and the spec's poll-until-done rules. Linear: ECO-486.It waits the interval before each poll, including the first, through the client's clock. On
authorization_pendingit polls again. Onslow_downit adds 5 seconds to the interval for the next poll and every later one. When the next poll would start afterexpires_at, it raises anexpired_tokenDeviceAuthorizationErrorwithout polling. It checks before and after each wait, so a wait that runs long, as across a host suspend, does not send a poll afterexpires_at.Errors
DevicePollError,intervaldoubled429or5xx, with or without an OAuth error body, or with a body that does not decodeDevicePollError,intervalnot doubledaccess_denied,expired_token,invalid_grant, andinvalid_responseDeviceAuthorizationError, as is4xxwithout an OAuth error bodyOAuthHttpError, as isdevice_code, anauthorization.intervalbelow 1, or anintervalargument that is not an integer or is belowauthorization.intervalConfigError, before any requestDevicePollError.intervalis the wait the loop would have used next, with everyslow_downincrease. Its cause is the original failure.retryableis alwaysTrue. To resume, callwait_for_device_tokenagain withinterval=error.interval.examples/device_authorizationshows how.Task cancellation ends the wait or the request in flight. After it, the loop does not call the credential or send another request. asyncio delivers a cancellation only where a task suspends, so the loop awaits
asyncio.sleep(0)after each wait. The client'stimeoutis the httpx timeout of each poll, also under a longer caller deadline such asasyncio.wait_for.Example
examples/device_authorizationruns the flow with a public client or aClientSecret, resumes afterDevicePollErrorup to three times, and refreshes the token for one resource when the request named more than one. I ran it against a local fake zone that answers pending, then503, then a token. It resumed once and the refresh sent oneresource.Spec unit test rows covered
In
tests/keycardai/oauth/test_device_authorization.py.test_row_8_pending_twice_then_tokentest_row_9_slow_down_adds_five_seconds_for_every_later_polltest_rows_10_and_12_terminal_oauth_error_stops_the_looptest_row_11_clock_passes_expires_at_while_pending,test_row_11_expiry_boundary,test_row_11_expiry_is_checked_again_after_the_waittest_rows_13_17_26_29_32_failure_stops_with_interval,test_row_13_network_error_then_5xx_on_a_second_calltest_row_14_cancelled_during_waittest_row_15_persisted_authorizationtest_row_16_slow_down_then_network_errortest_row_18_resume_with_the_reported_intervaltest_row_19_interval_misconfigured,test_row_19_interval_equal_to_the_authorization_intervaltest_row_20_cancelled_while_a_poll_is_in_flighttest_row_21_interval_longer_than_time_lefttest_row_22_one_flow_with_poll_until_donetest_row_27_credential_failure_returns_as_istest_row_28_request_timeout_holds_under_a_longer_caller_deadline(a local server that never answers)test_row_31_other_failures_return_as_istest_row_33_cancelled_when_the_wait_endsI broke each of these on purpose and checked that a test fails: the yield after the wait, the doubling, the status check, the expiry check before and after the wait, and the
>and<boundaries.Stack
Replaces #427. Merge in order:
The PR workflow runs only on pull requests to
main, so #430 to #433 show no CI until their base merges.just check,just typecheck,just test-coverage,just test-release-tooling, andjust validate-commitspass locally on each branch.🤖 Generated with Claude Code