Copilot instructions

1---
2applyTo: "src/libraries/System.Net.Http/**,src/libraries/System.Net.Http.Json/**,src/libraries/System.Net.Http.WinHttpHandler/**"
3---
4 
5# System.Net.Http — Folder-Specific Guidance
6 
7## Connection Pooling and Lifecycle
8 
9- SocketsHttpHandler pools connections per host/port/scheme — respect pool limits and idle timeouts when modifying connection management
10- Connection lifetime and idle timeout logic must handle races between pool cleanup and new request acquisition
11- When modifying connection pooling, ensure HTTP/1.1 and HTTP/2 paths are both updated — they have distinct pool semantics
12- Connection state transitions (idle → active → draining → disposed) must be atomic and thread-safe
13 
14## HTTP Protocol Handling
15 
16- HTTP/2 multiplexes streams over a single connection — changes to stream management must not starve other streams or deadlock flow control windows
17- HTTP/2 flow control (connection-level and stream-level) windows must be updated correctly; failing to send WINDOW_UPDATE causes hangs
18- Header parsing must handle folded headers, multiple values for the same header name, and case-insensitive comparison per RFC 9110
19- Ensure chunked transfer encoding, content-length validation, and trailer handling follow HTTP/1.1 and HTTP/2 specs exactly
20- Redirect handling must not follow redirects across security boundaries (HTTPS → HTTP) unless explicitly configured
21 
22## Request/Response Lifecycle
23 
24- HttpContent must be disposed after the response is consumed — leaking content streams holds connections open in the pool
25- HttpResponseMessage owns the response stream; disposing it before reading content causes ObjectDisposedException
26- Request headers vs content headers have distinct allowed sets — do not allow content headers on requests without a body
27- Cancellation tokens must propagate through the entire send pipeline including DNS, connect, TLS handshake, and response read
28 
29## HttpContent and Serialization
30 
31- Avoid buffering entire request/response bodies in memory — prefer streaming for large payloads
32- HttpContent.ReadAsStreamAsync should return the underlying stream without copying when possible
33- System.Net.Http.Json extensions must handle JsonSerializer cancellation and disposal correctly
34- Serialization errors must surface as HttpRequestException or JsonException, not raw IO exceptions
35 
36## WinHttpHandler
37 
38- WinHttpHandler delegates to the Windows WinHTTP API — changes must verify behavior on all supported Windows versions
39- Error codes from WinHTTP must be mapped to appropriate HttpRequestException with inner Win32Exception
40- WinHTTP callback state must be pinned for the duration of the async operation to prevent GC collection
41 
42## Performance
43 
44- Avoid allocating strings for well-known header names and values — use the static KnownHeaders table
45- Header value parsing should use Span-based APIs to avoid substring allocations
46- Pool HTTP/2 frame buffers and avoid per-frame allocations on the read/write loops
47 
48## Diagnostics
49 
50- Use NetEventSource for tracing request lifecycle events (send, redirect, retry, failure)
51- Never log request/response bodies, Authorization headers, cookies, or credentials in trace output
52