WIP: Socket.IO protocol on top of Engine.IO

[Redouane64]

WIP. Sending works end to end against a real Socket.IO server; receiving is not implemented yet. Opening early so the packet model and the Engine.IO changes underneath it can be reviewed before the parser is built on top.

This supersedes the earlier features/socketio branch, which forked ~40 commits back and predates the .NET 10 migration, the protocol-compliance pass and the test-coverage pass. Its concepts and structures are carried over here, rebuilt on current main and on the API it actually has. That branch's tip was b513982 if any of it is wanted back.

Done

Engine.IO, to make room for a protocol on top of it

• ClientOptions.Path — both transports hardcoded /engine.io, which is not where a Socket.IO server carries the protocol. The normalized form keeps a trailing slash: a server normalizes its own path the same way and matches it against the start of the request, so a real Socket.IO server answers /socket.io/?EIO=4 and 404s /socket.io?EIO=4. The bundled Engine.IO sample accepted the slashless form only because it forwards every request past engine.io's own path check, which is why nothing caught this before.
• Engine.SendAsync(Packet) and a plain-text Packet.CreateMessagePacket(ReadOnlyMemory<byte>) — a layered protocol encodes its own bytes and has to say which Engine.IO packet carries them.
• Engine.Connected answers before there is a transport instead of throwing, and Engine.ConnectionError records why an attempt failed. ConnectAsync reports failure by completing the packet stream with the reason, which suits a listener but leaves a caller that only ever sends — IO — with nothing to check.
• A failed WebSocket upgrade falls back to long-polling instead of tearing the session down, which is what the protocol calls for. _transport is repointed only once the socket has taken over.
• Connecting again after a connection has ended replaces the packet channel and the polling cancellation source. Both are one-shot, so a retry used to handshake successfully and hand back a connection whose receive loop had already exited.
• A base address ending in / no longer doubles the slash in the upgrade URI. Polling was immune — it resolves a relative Uri against HttpClient.BaseAddress, which normalizes — so this showed up as "polling works, the upgrade silently doesn't".

Socket.IO

• src/SocketIO.Client — packet type, packet model, payload arguments (text, Json, binary placeholder), and the client surface.
• Serialization writes into a caller-owned buffer and keeps no state, so a packet — the shared ConnectPacket included — encodes identically every time it is sent.
• Namespaces are normalized to their leading-slash form on construction, so admin and /admin cannot encode two different ways.
• Acknowledgement payloads carry no event name; ack ids are allowed on events, so an event can request one.
• Binary attachments are real: each leaves a {"_placeholder":true,"num":N} behind, and IO sends the header as a plain-text Engine.IO message followed by one binary message per attachment, under a lock so the run cannot be broken into. Text and binary arguments can be mixed in a single payload.
• Byte arrays have their own overloads on AddItem and SendAsync. Without them an array binds to the generic Json overload and ships as a base64 string with no complaint — worth keeping in mind when adding overloads here.
• A failed handshake is raised as IOConnectionException carrying the engine's reason, rather than being reported as a connection.
• A Socket.IO test server as a second npm workspace (npm run start:socket-server, port 9855).

Protocol compliance. The encoder was checked against socket.io-parser — the reference decoder, in node_modules — rather than against the spec prose. Five shapes encoded cleanly here and were refused by the server, and a decode error is not a dropped message: socket.io answers one by closing the connection.

Shape	Encoded as	Server
binary packet with no attachment	5["a","b"]	Illegal attachments — the count must be ≥ 1
negative ack id	2-1[…]	invalid payload — the sign starts the payload
namespace containing ,	2/a,b,[…]	invalid payload — the comma ends the namespace
Ack with no id	3[…]	silently discarded, no callback to match
reserved event name	2["disconnect",…]	invalid payload

All are refused at construction now, bar the attachment rule, which is checked when the packet is serialized because its attachments arrive after it is built. Two client-level defects went with them: IO latched a failed handshake as a connection and stayed unusable even once the server came back, and a header and its attachments were not held together, so two concurrent binary sends could interleave and cost the connection.

Tests. 67 Socket.IO and 86 Engine.IO, 153 in all and green; every commit builds and tests green on its own. IO now has the same internal HttpClient seam Engine and the transports use, so the client is under test and not only the encoder; its stub is hand-rolled, since this project takes no Moq dependency.

Verified against socket.io@4.8, not only in unit tests: handshake on /socket.io/ from a base address written with a trailing slash, upgrade to WebSocket, 40 CONNECT accepted into the namespace, a text event, a Json event, and eight concurrent binary events the server reassembled one by one, then 41 DISCONNECT.

Remaining, roughly in order

1. Parsing. Nothing decodes an inbound packet yet, which is what everything below waits on. Header first, then payload, mirroring where Packet.TryParse sits on the Engine.IO side.
2. Attachment reassembly. Hold a binary header back until its N attachments have arrived, then substitute the placeholders.
3. ListenAsync. Currently throws. Should drain the Engine.IO message stream into per-namespace IAsyncEnumerable<Packet>, in the shape Engine.ListenAsync already established.
4. Namespace multiplexing. Record the per-namespace sid from the server's 0{"sid":"..."} reply, route inbound packets to the right listener, and reject sends to a namespace that was refused.
5. Acknowledgements. Correlate an ack id back to a Task<T>, and answer server-initiated acks.
6. CONNECT auth payload. 0{"token":"..."} — currently no payload is allowed on a Connect packet.
7. CONNECT_ERROR. Surface it to the caller rather than letting a namespace connect hang.
8. Reconnection. A retry after a connection has failed or been closed works now, but backoff, rejoining namespaces and resuming a session do not exist.
9. The Json seam. JsonPacketData<T> uses reflection-based System.Text.Json, which throws outright in a trimmed or AOT app. Taking a JsonTypeInfo<T> would let callers pass a source-generated context, as the Engine.IO handshake already does.

🤖 Generated with Claude Code

https://claude.ai/code/session_01CsxPBM9F82FBXVQDV1jFmN