Skip to content

fix(http-guzzle,abstractions,serialization): improve middleware resilience and serialization robustness - #147

Open
Hardik K (hardikkaurani) wants to merge 11 commits into
microsoft:mainfrom
hardikkaurani:fix/middleware-resilience-and-serialization-robustness
Open

Hardik K (hardikkaurani) wants to merge 11 commits into
microsoft:mainfrom
hardikkaurani:fix/middleware-resilience-and-serialization-robustness

Conversation

@hardikkaurani

@hardikkaurani Hardik K (hardikkaurani) commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Summary

This pull request addresses several reliability defects and RFC compliance edge cases across packages/http/guzzle, packages/abstractions, and packages/serialization/form:

  1. RetryHandler RFC 9110 HTTP-Date & Delay Normalization:

    • Extended parseRetryAfterToSeconds to support all three RFC 9110 § 5.6.7 HTTP-date formats: IMF-fixdate (DateTimeInterface::RFC7231), RFC 850 (l, d-M-y H:i:s \G\M\T), and ANSI C asctime (D M j H:i:s Y).
    • Implemented the rolling 50-year window interpretation rule for RFC 850 two-digit years per RFC 9110 § 5.6.7 (dates > 50 years in the future correctly map to the previous century).
    • Enforced strict GMT timezone evaluation and calendar validation across all date formats, rejecting non-existent dates (e.g. Feb 29 non-leap years, Nov 31) and relative date expressions (+1 hour, next Monday).
    • Clamped past HTTP-dates and negative numerical values to non-negative delays (max(0, ...)), preventing negative delay options and invalid negative OpenTelemetry span attributes.
    • Handled unparseable/malformed Retry-After headers gracefully by falling back to standard exponential delay rather than throwing an unhandled RuntimeException that aborts the request pipeline.
    • Capped calculated delays at RetryOption::MAX_DELAY_SEC (180s) to guard against unbounded thread sleeps when upstream servers send extreme values.
    • Added range validation to RetryOption::setDelay and RetryOption::setMaxRetries to reject negative values.
  2. HeadersInspectionHandler Response Header Capture on BadResponseException:

    • Added an onRejected callback to capture and store response headers when downstream requests reject with BadResponseException (such as 4xx/5xx responses under Guzzle's default http_errors = true), enabling inspection of error response headers (e.g., WWW-Authenticate, Retry-After, x-ms-request-id).
  3. UrlReplaceHandler Pattern Quoting:

    • Escaped replacement tokens using preg_quote(urlencode($key), '/') in UrlReplaceHandler::replaceUrlSegment, preventing unescaped dots (e.g. /v1.0/users) from matching regex wildcards (e.g. /v1X0/users).
  4. ApiClientBuilder Idempotent Backing Store Enablement:

    • Prevented redundant double-wrapping in enableBackingStoreForSerializationWriterFactory and enableBackingStoreForParseNodeFactory when factory instances are already wrapped with BackingStoreSerializationWriterProxyFactory or BackingStoreParseNodeFactory.
  5. FormSerializationWriter Zero-Key Preservation:

    • Replaced !empty($key) checks with $key !== null && $key !== '' across primitive and non-parsable writer methods so that keys with value '0' are not omitted from application/x-www-form-urlencoded payloads.
  6. End-to-End Integration Tests:

    • Added integration test coverage exercising the full default middleware pipeline (KiotaClientFactory) with HeadersInspectionHandler, RetryHandler, UrlReplaceHandler, and form serialization.

Verification

  • PHPUnit: All 506 tests (1291 assertions) passed cleanly across all packages:
    • packages/abstractions: 14 test suites, all passed
    • packages/http/guzzle: 11 test suites (168 tests, 477 assertions), all passed
    • packages/serialization/form: 3 test suites, all passed
    • packages/serialization/json: 3 test suites, all passed
    • packages/serialization/text: 3 test suites, all passed
    • packages/serialization/multipart: 2 test suites, all passed
    • packages/bundle: 3 test suites, all passed
  • PHPStan: Level 9 static analysis passed with zero errors across all 112 files ([OK] No errors).
  • Monorepo Builder: monorepo-builder validate passed cleanly ([OK] All packages "composer.json" files use same package versions.).

@hardikkaurani
Hardik K (hardikkaurani) requested a review from a team as a code owner November 17, 2026 13:20
Copilot AI balanced review requested due to automatic review settings November 17, 2026 13:20

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota. Try requesting a review at a lower effort level.

@hardikkaurani

Copy link
Copy Markdown
Contributor Author

Hi Vincent Biret (@baywet),

Following our recent updates in CompressionHandler and serialization robustness, this pull request addresses a few related reliability and RFC compliance edge cases across http-guzzle, abstractions, and serialization-form:

  • RetryHandler RFC 9110 parsing & delay safety: Aligns HTTP-date parsing with RFC 9110 (supporting IMF-fixdate, RFC 850, and ANSI C asctime), clamps past dates and negative values to non-negative delays, gracefully falls back to exponential backoff when a header is malformed (preventing unhandled RuntimeException crashes), and caps calculated delays at MAX_DELAY_SEC (180s).
  • HeadersInspectionHandler error inspection: Captures and records response headers on rejected BadResponseExceptions (4xx/5xx responses), allowing inspection of error headers such as WWW-Authenticate and Retry-After.
  • UrlReplaceHandler literal key matching: Safely escapes replacement tokens with preg_quote to avoid regex wildcard expansion on unescaped dots (e.g. /v1.0).
  • ApiClientBuilder backing store idempotency: Guards against redundant double-wrapping when factories are already wrapped with proxy factories.
  • FormSerializationWriter zero-key preservation: Replaces !empty($key) checks with $key !== null && $key !== '' so that valid '0' property names are not omitted from form-urlencoded payloads.

All 501 unit and integration tests are passing cleanly, PHPStan Level 9 analysis passed with zero errors, and monorepo dependencies are verified. Whenever you have time, please take a look!

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

🟡 Changes recommended

Retry-After parsing inherits the default timezone for some HTTP-date formats and accepts invalid relative expressions, potentially causing premature retries or unnecessary delays instead of the configured backoff.

2 open issues

Review effort: Balanced

Copilot AI balanced review requested due to automatic review settings November 17, 2026 13:43

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota. Try requesting a review at a lower effort level.

@hardikkaurani

Copy link
Copy Markdown
Contributor Author

Hi Vincent Biret (@baywet),

I have addressed both review findings from Copilot's review in 22a31c3:

  1. Explicit GMT Timezone for HTTP Dates: Passed new DateTimeZone('GMT') to all supported HTTP-date format parsers (DateTimeInterface::RFC7231, RFC 850, and asctime) in RetryHandler::parseRetryAfterToSeconds, ensuring delay calculations compute relative to GMT regardless of the application's default timezone. Added unit test coverage verifying accurate delay calculation across multiple non-UTC timezones (America/New_York, Asia/Tokyo, Pacific/Honolulu, Europe/Berlin).
  2. Rejection of Relative Expressions: Removed the permissive strtotime() fallback so that relative expressions such as +1 hour, next Monday, or now return 0, allowing calculateDelay() to cleanly fall back to the configured exponential backoff instead of scheduling an unintended delay.

All unit tests and PHPStan static analysis pass cleanly. Ready for your review.

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

🟡 Changes recommended

Invalid calendar dates can trigger a capped 180-second delay instead of backoff, and a test’s timezone-dependent GMT header can cause unintended multi-minute runs.

1 open issue
1 previously missed issue

In code that hasn't changed since last review

Medium severity Reject date parsing results with calendar warnings

packages/​http/​guzzle/​src/​Middleware/​RetryHandler.php:341

DateTime::createFromFormat() can return an object with a warning for invalid calendar dates, such as Tue Nov 31 12:00:00 2026. If the normalized date is in the future, this can schedule the capped 180-second delay instead of the configured backoff for malformed headers. Reject parsing results with warnings or errors, and add an invalid-calendar-date regression test.

2 resolved since last review

Review effort: Balanced

Copilot AI balanced review requested due to automatic review settings November 17, 2026 16:23

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota. Try requesting a review at a lower effort level.

@hardikkaurani

Copy link
Copy Markdown
Contributor Author

Hi Vincent Biret (@baywet),

I've pushed updates addressing the remaining date-handling edge cases:

  • Explicit GMT Test Header: Formatted test RFC 850 dates explicitly with new \DateTimeZone('GMT') in KiotaClientFactoryTest, preventing host timezone offsets from skewing the calculated delay.
  • Calendar Overflow Rejection: Hardened RetryHandler::parseRetryAfterToSeconds by verifying DateTime::getLastErrors() for warnings and errors on parsed dates. Invalid calendar dates (e.g. November 31) are now strictly rejected and fall back to the configured exponential backoff instead of overflowing into future delays.
  • Regression Testing: Added test coverage in RetryHandlerTest asserting that invalid calendar dates return 0 and trigger fallback delay.

All 504 tests (1,285 assertions) and PHPStan level 9 static analysis pass cleanly. When you have a moment, please review. Thank you!

@hardikkaurani

Copy link
Copy Markdown
Contributor Author

Hi Vincent Biret (@baywet),

All feedback items from the review cycle have been addressed in \ca20227:

  1. Strict calendar validation: Added \DateTime::getLastErrors()\ inspection across all HTTP-date formats (\RFC7231, \RFC850, and \�sctime) to reject date strings with calendar overflow warnings (such as non-existent dates like \31-Nov\ or invalid leap days). Any date containing errors or warnings now evaluates to \

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

🔵 Needs a closer look

Delay capping can trigger retries before the server’s requested waiting period expires, and RFC 850 year parsing can misread future deadlines as expired.

No open issues 🎉

2 previously missed issues

In code that hasn't changed since last review

Medium severity Do not cap Retry-After and retry before the server deadline

packages/​http/​guzzle/​src/​Middleware/​RetryHandler.php:249

For a 429 response with Retry-After: 1000, this cap schedules another request after 180 seconds, before the server's requested waiting period has elapsed. It can also make a retry pass retriesTimeLimit when the original delay would exceed it; the later-attempt cap on line 255 has the same issue. Reject retries whose server-requested delay exceeds the supported limit in the shared shouldRetry() decision, preserving the original response or rejection rather than retrying early.

Medium severity Apply HTTP’s rolling 50-year rule to RFC 850 dates

packages/​http/​guzzle/​src/​Middleware/​RetryHandler.php:339

PHP's y format uses a fixed 1970–2069 window rather than HTTP's rolling 50-year interpretation. In 2026, an RFC 850 date with year 70 is therefore parsed in 1970 instead of 2070, making the handler treat a future server deadline as expired and retry after ordinary backoff. Expand the two-digit year according to the HTTP rule before parsing the weekday, and add coverage around the century boundary.

1 resolved since last review

Review effort: Balanced

@github-project-automation github-project-automation Bot moved this to In Progress 🚧 in Kiota Nov 18, 2026
Copilot AI balanced review requested due to automatic review settings November 20, 2026 15:20

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota. Try requesting a review at a lower effort level.

…0 IMF-fixdate

Signed-off-by: Hardik Kaurani <hardikkaurani1@gmail.com>
@hardikkaurani

Copy link
Copy Markdown
Contributor Author

Hi Vincent Biret (@baywet),

I have pushed commit da9aed9 to address your review feedback:

  1. RetryHandler HTTP-Date Parsing:

    • Simplified parseRetryAfterToSeconds() to strictly parse canonical IMF-fixdate (DateTimeInterface::RFC7231).
    • Removed the obsolete RFC 850 and ANSI C asctime parsing fallbacks, keeping the date parsing lean and aligned with RFC 9110 expectations for modern HTTP implementations.
    • Retained explicit GMT timezone handling and strict calendar validation via DateTime::getLastErrors().
    • Updated the unit and integration tests accordingly.
  2. UrlReplaceHandler Pattern Quoting:

    • Replied to the review thread with technical details on why preg_quote() is needed: urlencode() intentionally preserves periods (.), which would otherwise act as PCRE single-character wildcards in URL version segments like /v1.0.

All 502 unit and integration tests pass cleanly and PHPStan static analysis passes with zero errors. Whenever you have time, please take another look. Thank you!

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

🟡 Changes recommended

Retry-After parsing rejects valid RFC 850 and asctime dates, causing retries to use a shorter configured backoff instead of honoring the server-requested delay.

1 open issue

Review effort: Balanced

}
$retryAfterDateTime = DateTime::createFromFormat(DateTimeInterface::RFC7231, $retryAfterValue);
$gmt = new DateTimeZone('GMT');
$retryAfterDateTime = $this->createDateTimeFromFormat(DateTimeInterface::RFC7231, $trimmed, $gmt);

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Addressed in f9e6290: Restored support for both RFC 850 and ANSI C asctime formats adhering strictly to RFC 9110 § 5.6.7:

  • RFC 850 (l, d-M-y H:i:s \G\M\T) is parsed under an explicit GMT timezone with calendar validation and the mandated rolling 50-year window rule (dates > 50 years in the future are interpreted as the previous century).
  • Asctime (D M j H:i:s Y and D M j H:i:s Y) is parsed in GMT with calendar validation, supporting single-digit and double-digit day formats.
  • Unit tests have been restored and expanded to verify delay calculation for both formats, rolling 50-year boundary handling, invalid calendar date rejection across all three formats, and non-UTC system timezone resilience.

Copilot AI balanced review requested due to automatic review settings November 20, 2026 17:55

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota. Try requesting a review at a lower effort level.

…-year rule

Signed-off-by: Hardik Kaurani <hardikkaurani1@gmail.com>
@hardikkaurani

Copy link
Copy Markdown
Contributor Author

Vincent Biret (@baywet) I've pushed an update in commit f9e6290 to align our Retry-After date handling with the recipient requirements of RFC 9110 § 5.6.7.

While senders are restricted to IMF-fixdate, RFC 9110 § 5.6.7 specifies that recipient parsers must accept all three formats (IMF-fixdate, RFC 850, and ANSI C asctime). To satisfy this while maintaining strict parsing:

  • Re-added parsing fallbacks for RFC 850 and asctime formats.
  • Implemented the rolling 50-year window rule for RFC 850 2-digit years so dates more than 50 years in the future correctly map to the previous century.
  • Preserved strict GMT timezone evaluation and calendar validation across all formats.
  • Restored and expanded unit tests covering valid parsing, rolling window boundary resolution, invalid calendar date rejection, and execution across non-UTC system timezones.

All 506 unit tests across the monorepo pass cleanly, and PHPStan level 9 reports zero errors. Ready for your review whenever convenient!

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

Labels

None yet

Projects

Status: In Progress 🚧

Development

Successfully merging this pull request may close these issues.

3 participants