feat: add native WebSocket compression opt-out

[frnandu]

Status

READY

Description

Closes #88.

Related downstream request: relaystr/ndk#820

Add an optional compressionEnabled constructor parameter, defaulting to true, so native clients can disable compression without giving up this library's automatic reconnection:

final socket = WebSocket(
  Uri.parse('wss://relay.example.com'),
  compressionEnabled: false,
);

The current native connector does not expose the compression parameter of dart:io's WebSocket.connect. This prevents downstream clients from opting out without maintaining a modified copy of the library. NDK's linked issue describes the motivation and workload-specific memory measurements for long-running clients with multiple relay connections. This is a configurable tradeoff, not a claim that compression is a leak or should be disabled by default: disabling compression can increase bandwidth for compressible messages.

Implementation

• Capture the flag per client and forward it on every connection attempt, including automatic reconnects.
• Map true to CompressionOptions.compressionDefault and false to CompressionOptions.compressionOff in the native connector.
• Accept and ignore the flag on the web, where the browser controls compression negotiation. Document this explicitly.
• Keep the public API free of dart:io types and preserve existing defaults, backoff, and lifecycle behavior.
• Add README/API documentation and an unreleased changelog entry.

Verification

• dart test: all 33 tests pass.
• dart analyze --fatal-infos: no issues.
• dart format on changed Dart implementation/test files: no remaining changes.
• JavaScript compilation of a small consumer using compressionEnabled: false: passes. This checks web compilation, not browser runtime behavior.

The new loopback integration test runs default and compression-disabled clients together against a compression-capable server. It checks both request extension offers and response negotiation headers on initial connection and forced reconnect. It also checks custom headers, subprotocol selection, and text/binary round trips across reconnects, including continuity of an existing message subscription.

Type of Change

• ✨ New feature (non-breaking change which adds functionality)
• 🛠️ Bug fix (non-breaking change which fixes an issue)
• ❌ Breaking change (fix or feature that would cause existing functionality to change)
• 🧹 Code refactor
• ✅ Build configuration change
• 📝 Documentation
• 🗑️ Chore