Add iOS/MAUI cookie handling docs

[amirhmd]

Closes #2387

Adds a new "iOS / MAUI Cookie Handling" page under Advanced topics, explaining why Set-Cookie headers are missing on iOS/Mac Catalyst and how to fix it.

Description

• New page: docs/docs/advanced/ios-maui-cookies.md
  • Symptom, root cause (NSURLSession intercepts Set-Cookie into NSHTTPCookieStorage before .NET sees it), and the fix via ConfigureMessageHandler
  • Multi-tenant safety rationale for disabling the native cookie store
  • Anti-pattern warning against UseCookies = true with a shared CookieContainer
• Linked from docs/docs/advanced/configuration.md (CookieContainer option row)
• Linked from docs/docs/usage/request.md (Cookies section)

The recipe code block matches the one provided in the issue.
This is a docs-only change — no source or test files were touched.

Purpose

This pull request is a:

• Bugfix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)

Checklist

• I have added tests that prove my fix is effective or that my feature works
• I have added necessary documentation (if appropriate)

[qodo-free-for-open-source-projects]

PR Summary by Qodo

Document iOS/MAUI cookie handling workaround for missing Set-Cookie headers

📝 Documentation 🕐 10-20 Minutes

AI Description

• Add a dedicated guide explaining iOS/Mac Catalyst Set-Cookie header interception.
• Cross-link cookie docs and configuration docs to the new platform-specific workaround.
• Warn against unsafe shared cookie container patterns in multi-tenant clients.

Diagram

graph TD
  cfg["advanced/configuration.md"] --> ios["advanced/ios-maui-cookies.md"]; req["usage/request.md"] --> ios

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Inline the iOS/Mac Catalyst workaround into existing cookie docs

• ➕ Keeps all cookie guidance in one place
• ➕ Fewer documentation pages to maintain
• ➖ Makes the main cookie page longer and easier to miss for non-iOS readers
• ➖ Harder to expand with platform nuance (multi-tenant considerations, anti-patterns) without clutter

2. Provide a reusable helper/factory for NSUrlSessionHandler configuration (code-side)

• ➕ Reduces copy/paste of the handler configuration snippet
• ➕ Encapsulates platform-specific configuration for consumers
• ➖ Requires product/API changes and release coordination beyond documentation scope
• ➖ May not fit all app architectures (DI, custom handlers, multiple clients)

Recommendation: The chosen approach (a dedicated iOS/MAUI cookie-handling doc plus cross-links from the relevant pages) is the best fit for a docs-only PR: it keeps platform-specific details discoverable without cluttering general guidance, and it provides a clear root-cause explanation, a concrete workaround, and a security note on multi-tenant safety.

Files changed (3) +45 / -1

Documentation (3) +45 / -1

configuration.mdLink CookieContainer option docs to iOS/MAUI cookie workaround +1/-1

Link CookieContainer option docs to iOS/MAUI cookie workaround

• Updates the 'CookieContainer' client option description to reference the new iOS/Mac Catalyst cookie-handling guide. Clarifies that platform-specific setup may be required to receive 'Set-Cookie' headers.

docs/docs/advanced/configuration.md

ios-maui-cookies.mdAdd iOS/Mac Catalyst guide for missing Set-Cookie headers +40/-0

Add iOS/Mac Catalyst guide for missing Set-Cookie headers

• Introduces a new page explaining why 'Set-Cookie' headers do not appear on iOS/Mac Catalyst due to 'NSURLSession' cookie interception. Provides a 'ConfigureMessageHandler' snippet to disable system cookie storage, plus guidance on multi-tenant safety and an explicit anti-pattern warning.

docs/docs/advanced/ios-maui-cookies.md

request.mdAdd iOS/Mac Catalyst note for empty RestResponse.Cookies +4/-0

Add iOS/Mac Catalyst note for empty RestResponse.Cookies

• Adds a platform note warning that 'RestResponse.Cookies' may be empty on iOS/Mac Catalyst even for successful requests. Links readers to the new iOS/MAUI cookie-handling workaround page.

docs/docs/usage/request.md

[qodo-free-for-open-source-projects]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0) 🎨 UX issues (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

1. Workaround drops handler options ✓ Resolved 🐞 Bug ≡ Correctness

Description

The iOS/MAUI workaround example replaces the internally configured HttpClientHandler via
ConfigureMessageHandler, so handler-scoped RestClientOptions (proxy, credentials, decompression,
certificate validation callback, client certificates, etc.) will no longer apply. Users following
the snippet can get unexpected runtime behavior because RestSharp configures the original handler
before invoking ConfigureMessageHandler, and any returned new handler bypasses that configuration.

Code

docs/docs/advanced/ios-maui-cookies.md[R19-25]

+var options = new RestClientOptions(baseUrl) {
+    ConfigureMessageHandler = _ => {
+        var config = NSUrlSessionConfiguration.DefaultSessionConfiguration;
+        config.HttpCookieStorage      = null;
+        config.HttpCookieAcceptPolicy = NSHttpCookieAcceptPolicy.Never;
+        return new NSUrlSessionHandler(config);
+    }

Evidence

The new doc returns a brand-new handler, but RestSharp only applies handler-level options to the
initially created HttpClientHandler and then swaps it out if ConfigureMessageHandler returns
something else, which means those options don’t carry over to the replacement handler.

docs/docs/advanced/ios-maui-cookies.md[13-27]
src/RestSharp/RestClient.cs[91-96]
src/RestSharp/RestClient.cs[226-256]
docs/docs/advanced/configuration.md[121-126]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The iOS/MAUI cookie workaround doc recommends returning a new `NSUrlSessionHandler` from `RestClientOptions.ConfigureMessageHandler`. Doing so replaces the `HttpClientHandler` that RestSharp already configured from `RestClientOptions`, which can silently drop important handler-level settings (proxy, credentials, decompression, cert validation callbacks, client certificates, etc.).
### Issue Context
- RestSharp constructs a `HttpClientHandler`, configures it from `RestClientOptions`, then calls `ConfigureMessageHandler` and uses the returned handler for `HttpClient`.
- If the callback returns a different handler instance, the earlier configuration is not applied to the new handler.
### Fix Focus Areas
- docs/docs/advanced/ios-maui-cookies.md[13-31]
### Suggested change
1. Keep the workaround, but add an explicit note immediately after the snippet explaining that this *replaces* RestSharp’s configured handler.
2. List the key impacted options (Proxy, Credentials/UseDefaultCredentials, AutomaticDecompression, RemoteCertificateValidationCallback, ClientCertificates, etc.).
3. Provide guidance: users who rely on those settings must re-apply equivalent configuration to the new `NSUrlSessionHandler` (or alternatively build and pass a fully configured `HttpClient`/handler chain themselves).

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

[amirhmd]

@dotnet-policy-service agree

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud