felangel / felangel/web_socket_client

feat: allow disabling native WebSocket compression per client

Open
#88 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Dart
Stars
177
Forks
44
PR merge metrics
No merged PRs in 30d

Description

**Description**

Please expose a per-client option to disable WebSocket compression on native platforms while retaining this library's automatic reconnection and connection-state handling.

The native connector calls `dart:io`'s `WebSocket.connect` without a `compression` argument, which uses `CompressionOptions.compressionDefault`. The public `WebSocket` constructor has neither a compression option nor a custom connection factory, so consumers cannot pass `CompressionOptions.compressionOff` through to the underlying socket. Any automatic reconnect must also preserve that choice.

This came up in NDK: https://github.com/relaystr/ndk/issues/820. Long-running, memory-sensitive clients connecting to multiple Nostr relays need to choose between compression-related memory/CPU overhead and bandwidth. That issue includes workload-specific measurements; this request does not assume compression is a memory leak or that disabling it benefits every application. Without an upstream option, downstream libraries need to maintain a modified copy of the client to expose this setting.

**Proposed API**

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

Use `bool compressionEnabled = true` to preserve existing behavior and avoid exposing `dart:io` types through the cross-platform API. Store the flag on the client and forward it through the platform connectors on every connection attempt. The native connector maps it to `CompressionOptions.compressionDefault` or `CompressionOptions.compressionOff`.

On the web, document that the flag is ignored: the browser WebSocket API controls compression negotiation and does not expose a switch to disable it.

**Requirements**

- [ ] Existing clients retain default compression negotiation.
- [ ] Native clients can disable compression per instance, without changing other clients.
- [ ] Automatic reconnects preserve the configured setting.
- [ ] Text/binary messages, headers, and subprotocols continue to work.
- [ ] The API remains web-compatible and documents the browser limitation.
- [ ] Regression tests inspect both request and response handshake headers against a compression-capable local server, including after reconnect.

**Additional Context**

Related downstream issue: https://github.com/relaystr/ndk/issues/820

I will submit a small implementation with tests and documentation. No changes to backoff or connection lifecycle logic are needed.

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.