Copilot instructions

1---
2applyTo: "src/libraries/System.Net.Sockets/**"
3---
4 
5# System.Net.Sockets — Folder-Specific Guidance
6 
7## Async Socket Operations
8 
9- Prefer SocketAsyncEventArgs-based operations over Task-based wrappers on hot paths to avoid allocations
10- SocketAsyncEventArgs instances must be reused — allocating a new one per operation defeats the purpose
11- When an async socket operation completes synchronously (returns false), invoke the continuation inline without posting to the thread pool
12- Cancellation must close the socket to unblock pending operations — there is no other reliable mechanism to cancel in-flight I/O
13 
14## Buffer Management
15 
16- Pin buffers for the duration of the native I/O operation — use GCHandle or fixed statements, not just Memory<T>
17- Prefer ArrayPool<byte> for receive and send buffers; return buffers in finally blocks even on exception paths
18- Multi-buffer (scatter/gather) send and receive must handle partial completions — the OS may transfer fewer bytes than requested
19 
20## Dual-Stack and Address Families
21 
22- Support dual-stack sockets (IPv6 with IPv4-mapped addresses) as the default where the OS supports it
23- When creating sockets, handle AddressFamily.InterNetworkV6 with DualMode=true rather than creating separate IPv4/IPv6 sockets
24- Test with both IPv4-only and IPv6-only endpoints — do not assume dual-stack availability
25 
26## Platform-Specific Behavior
27 
28- Socket option names and behaviors differ between Windows (Winsock) and Unix (POSIX) — guard platform-specific options with runtime checks
29- Linux uses epoll, macOS uses kqueue, and Windows uses IO completion ports — async completion models differ per platform
30- Connection reset behavior varies: Windows returns WSAECONNRESET immediately, Linux may return it on the next read
31- SO_REUSEADDR semantics differ between platforms — document expected behavior clearly
32 
33## Connection and State Management
34 
35- Socket disposal must cancel all pending operations and release the native handle
36- Track socket state (created → bound → listening/connected → shutdown → disposed) explicitly to prevent invalid operations
37- Do not issue concurrent reads or concurrent writes on the same socket unless the protocol explicitly requires it
38- LingerOption and shutdown sequences must be tested on all platforms — graceful close behavior varies
39 
40## Error Handling
41 
42- Map platform-specific error codes (WSA* on Windows, errno on Unix) to SocketException with the correct SocketError
43- Distinguish between transient errors (EWOULDBLOCK, EINTR) and fatal errors (ECONNREFUSED, ENETUNREACH) in retry logic
44- SocketException.SocketErrorCode must be set correctly — callers depend on it for error classification
45