[lhoward]

Stacked on #244. This branch is based on #244, which this follows up. Until #244 is merged, the diff here includes its commit (SocketPool: keep a descriptor's registration when a closed socket's is reused); after that, only this PR's own commit remains.

Summary

This addresses the hazard #244 leaves open: a socket closed while it's suspended on a SocketPool is never woken. AsyncSocket.close() closes the descriptor without telling the pool. The kernel then drops the descriptor from the kqueue or epoll set without reporting an event, so a task waiting to read, write or accept on that socket waits for good.

In practice this bites whenever one task closes a connection that another task is reading. For example, a writer finds the peer gone and closes the connection, and the reader never returns. We hit it in SwiftEmberPlus, and it applies to SwiftOCA's device endpoints too.

Changes

• AsyncSocketPool.close(_ socket:) is a new requirement. It closes a socket after first resuming each of its suspensions with SocketError.disconnected. A default implementation just closes the socket, so existing pools still compile and behave as before.
• SocketPool.close(_:) resumes the socket's suspensions on the actor, which removes their events from the queue while the descriptor is still open, and then closes it. Because all of this happens on the actor, no other socket can be given the descriptor while its suspensions are still recorded, so this path never leaves stale registrations behind.
• AsyncSocket.disconnect() closes the socket through its pool. close() is unchanged, and its documentation now points to disconnect() for a socket another task may be using.

I named it disconnect() because an async overload of close() would be preferred in async contexts. It would then make every existing try socket.close() there fail to compile without await. I'm happy to rename it.

Tests

The SocketPoolTests use the platform's real pool, as #244's do:

• close_ResumesTheSocketsSuspensions: two reads suspended on a socket both throw SocketError.disconnected when the pool closes it.
• close_LeavesOtherSocketsSuspended: another socket's suspension is untouched, and is still woken when it becomes readable.

In AsyncSocketTests:

• disconnect_WakesASuspendedRead: the suspended read throws SocketError.disconnected, and the peer sees the end of the stream.
• disconnect_Closes_WhenThePoolDoesNotTrackSuspensions: with a pool that relies on the default implementation, the socket is still closed.

The full suite passes on macOS (Swift 6.3.3): 478 tests, three runs. The change touches only the generic SocketPool, not the platform queues, but I couldn't build or run it on Linux, so Linux CI is its first run there.

Not changed here

HTTPServer.stop() closes its listening socket while accept is suspended on it, and relies on cancelling the server task after the timeout. Closing through config.pool.close(_:) would end the accept loop at once. That changes how run() ends, though, so it's better proposed separately.

🤖 Generated with Claude Code