Copilot instructions

1---
2applyTo: "src/libraries/System.Net.Quic/**"
3---
4 
5# System.Net.Quic — Folder-Specific Guidance
6 
7## MsQuic Interop
8 
9- All MsQuic API calls go through the MsQuicApi function table — never call native exports directly
10- MsQuic callbacks execute on MsQuic worker threads — minimize work in callbacks and avoid blocking
11- Native callback delegates must be prevented from being garbage collected (pin or store a reference) for the lifetime of the registration
12- MsQuic configuration handles are reference-counted — pair every open with a close and verify no leaks
13- Check MsQuic version compatibility at startup — API surface differs between MsQuic releases
14 
15## QuicConnection Lifecycle
16 
17- Connection state transitions (connecting → connected → shutting down → closed) must be guarded with proper synchronization
18- Connection close must first shut down all streams, then close the connection handle — skipping stream cleanup causes native assertions
19- Handle connection migration events correctly — the remote address may change mid-connection
20- Graceful shutdown requires sending CONNECTION_CLOSE frames — abortive close should be the fallback, not the default
21 
22## QuicStream Lifecycle
23 
24- Streams are unidirectional or bidirectional — enforce directionality at the API level (no reads on send-only, no writes on receive-only)
25- Stream disposal must abort the stream if it has not been gracefully closed — leaking open streams blocks connection shutdown
26- Handle QUIC flow control (MAX_STREAM_DATA, MAX_STREAMS) correctly — exceeding limits is a protocol violation
27- Reading from a stream may return 0 bytes when the peer has sent FIN — distinguish FIN from flow control blocking
28 
29## Error Handling
30 
31- Map MsQuic status codes (QUIC_STATUS_*) to appropriate .NET exceptions (QuicException with transport error codes)
32- Connection errors must propagate to all open streams — a single stream should not silently orphan after connection failure
33- Application error codes (set via stream abort) must round-trip correctly between peers
34 
35## Async Patterns
36 
37- Use ValueTask for stream read/write operations — they frequently complete synchronously when data is already buffered
38- Completion sources for MsQuic callbacks must use RunContinuationsAsynchronously to avoid executing user code on the MsQuic thread
39- Cancellation must trigger QUIC stream or connection abort with an appropriate error code — not just abandon the Task
40 
41## Performance
42 
43- Avoid per-operation allocations on the stream read/write path — pool buffers and reuse completion sources
44- QuicStream send and receive buffers should be sized to match QUIC packet sizes to minimize fragmentation
45- Minimize managed-to-native transitions in the data transfer hot path by batching operations where possible
46 
47## Testing
48 
49- QUIC tests require MsQuic to be available — use ConditionalFact/ConditionalTheory with appropriate platform checks
50- Test stream multiplexing under concurrency — verify that multiple streams on a single connection do not interfere
51- Verify behavior when the peer resets a stream or closes the connection unexpectedly
52