Improve Engine.IO v4 polling compatibility and modernize internal typing and transport handling

[reinbeumer]

Summary

This PR improves Engine.IO v4 polling compatibility and also includes a broader internal modernization of socket.io-dart.

The original goal was to fix polling interoperability issues with newer Engine.IO / Socket.IO clients. While implementing and validating those fixes, I also cleaned up related transport/server internals, introduced stronger internal typing, and expanded test coverage in the same areas.

Main functional fixes

1. Polling payload decoding

The polling transport now handles both of the payload formats that were relevant during testing:

• Engine.IO v4 record-separator delimited payloads (\x1e)
• concatenated fallback payloads in edge cases

Packets are decoded individually, and close packets are handled consistently.

2. CORS preflight handling

Browser polling clients can issue OPTIONS preflight requests before polling GET / POST requests.

This branch updates request verification and polling/XHR handling so those preflight requests are accepted and answered correctly.

3. HTTP response lifecycle handling

Some error and edge-case response paths now close responses more explicitly to avoid hanging clients.

Where response closing is intentionally fire-and-forget, the code uses unawaited(...).

Additional internal improvements

In addition to the polling fixes, this branch also includes a broader set of related internal improvements:

• refactoring of transport and server code paths
• additional typed models and value objects
• utility/extension cleanup and consolidation
• expanded test coverage around transport, models, and related behavior
• example and documentation updates

These changes were made in the same branch because the polling fixes touched areas that were also being actively cleaned up and made more type-safe.

What reviewers should expect

This is a larger PR than an ideal narrowly scoped bugfix PR.

It includes both:

• concrete polling compatibility fixes, and
• a broader internal refactor / modernization of the surrounding code

If preferred, I can split out the polling-specific changes into a smaller follow-up PR with a reduced review surface.

Testing

Polling-related behavior was covered with integration-style tests for:

• separator-delimited Engine.IO v4 payloads
• concatenated polling payload fallback
• polling CORS preflight handling

Also verified with:

• full test suite pass
• polling smoke checks
• polling-only connectivity checks

Compatibility

• No intentional breaking API changes are included for normal supported usage.
• Existing WebSocket behavior is intended to remain unchanged.
• Polling support is improved for newer Engine.IO clients.

Notes

I understand this PR may still be broader than what you would ideally want for review. If you prefer a smaller change set, I am happy to prepare a reduced PR focused only on the polling compatibility fixes.

[Copilot]

Copilot wasn't able to review this pull request because it exceeds the maximum number of lines (20,000). Try reducing the number of changed lines and requesting a review from Copilot again.