Azure / Azure/azure-sdk-for-cpp
[azure-core-amqp] Preserve structured CBS failures through token refresh retries
- Dominant language
- C++
- Stars
- 205
- Forks
- 172
- Avg merge
- 1d 3h
- Merged PRs (30d)
- 37
Description
## Summary
`RefreshTokenForAudience` catches every standard exception and retains only `what()`. The refresh scheduler therefore cannot distinguish credential acquisition, CBS open, put-token refusal, transport failure, timeout, and shutdown cancellation. It can only retry every failure with the same policy and write an unstructured warning.
Issue #7330 covers the low-level ambiguity where `PutTokenForAudience` raises `AuthenticationException` for every non-`Ok` CBS result. This issue carries structured failure information through the refresh worker after the low-level result has been classified. Rust transport parity is outside this issue.
## Proposal
Introduce an internal refresh outcome that records:
- The failed stage: credential acquisition, CBS open, put-token, or cleanup.
- The CBS operation result and service status when available.
- Whether the failure is retryable on the same connection.
- Whether a fresh connection is required.
- Whether the operation ended because of caller cancellation or connection shutdown.
Use the outcome rather than exception text to select the next refresh action. Transport errors, timeouts, throttling, and retryable service failures may retain the current authorization and schedule another attempt. An explicit credential or claim rejection remains a permanent authentication result after the bounded fresh-connection probe in the Event Hubs layer.
Preserve exception text for diagnostics, but do not parse it to make a retry decision. Logs may include the audience, connection instance, failure stage, attempt number, remaining token lifetime, and next delay. They must never include the token.
## Validation
- [ ] Each credential and CBS failure stage produces a distinct internal outcome.
- [ ] Cancellation and shutdown are not logged or scheduled as ordinary retryable failures.
- [ ] CBS service status and description survive to the final actionable exception when available.
- [ ] Retry decisions do not inspect exception text.
- [ ] Logs state the retry decision and next delay without exposing token material.
- [ ] Tests cover transient transport failure, explicit authorization refusal, timeout, cancellation, and unknown exception paths.
This issue changes authentication failure handling and requires explicit security-focused review.
Contributor guide
Research direction
Start by tracing RefreshTokenForAudience through credential acquisition, CBS open, PutTokenForAudience, and cleanup, then inspect how the Event Hubs layer consumes the result. Use the validation checklist to define completion: distinct outcomes, preserved CBS status, non-text-based retry decisions, correct cancellation handling, and tests for each listed failure path without logging token material.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- azure, cpp
- Domain
- authentication, security
- Issue type
- Refactor
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 32/100