[dart:io] Clarify CompressionOptions null window bits means default window.
CompressionOptions's clientMaxWindowBits and serverMaxWindowBits are null
by default, indicating that no particular window size is negotiated in
the protocol, instead implying that the connection can handle a default
window size of 15 (32,768 bytes) (RFC 7692 7.1.2.1 and 7.1.2.2).
This change clarifies the documentation for the clientMaxWindowBits and
serverMaxWindowBits fields by stating they can be null to request the
protocol's default window size.
The current implementation's behavior is reasonable. It could be changed
to explicitly say 15 instead of null, but it's more efficient to omit the
request for 15 bits from the protocol since it's default, and it's fine to
allow callers to explicitly request 15 bits since the code already allows
this behavior. This change simply codifies the existing behavior in the
documentation.
The co19 test LibTest/io/CompressionOptions/DEFAULT_A01_t01 was written
based off the misleading documentation. An issue to test the intended
behavior was filed at <https://github.com/dart-lang/co19/issues/364>.
Closes https://github.com/dart-lang/sdk/issues/29436
Change-Id: If7645e7d5abd59715fd1eb0bfe8cbb877d776402
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/103813
Commit-Queue: Jonas Termansen <sortie@google.com>
Reviewed-by: Lasse R.H. Nielsen <lrn@google.com>
diff --git a/sdk/lib/_http/websocket.dart b/sdk/lib/_http/websocket.dart
index 64dbeb1..5a949af 100644
--- a/sdk/lib/_http/websocket.dart
+++ b/sdk/lib/_http/websocket.dart
@@ -50,51 +50,78 @@
static const int RESERVED_1015 = reserved1015;
}
-/**
- * The [CompressionOptions] class allows you to control
- * the options of WebSocket compression.
- */
+/// Options controlling compression in a [WebSocket].
+///
+/// A [CompressionOptions] instance can be passed to [WebSocket.connect], or
+/// used in other similar places where [WebSocket] compression is configured.
+///
+/// In most cases the default [compressionDefault] is sufficient, but in some
+/// situations, it might be desirable to use different compression parameters,
+/// for example to preserve memory on small devices.
class CompressionOptions {
- /// Default WebSocket Compression options.
+ /// Default [WebSocket] compression configuration.
///
- /// Compression will be enabled with the following options:
+ /// Enables compression with default window sizes and no reuse. This is the
+ /// default options used by [WebSocket.connect] if no [CompressionOptions] is
+ /// supplied.
///
/// * `clientNoContextTakeover`: false
/// * `serverNoContextTakeover`: false
- /// * `clientMaxWindowBits`: 15
- /// * `serverMaxWindowBits`: 15
+ /// * `clientMaxWindowBits`: null (default maximal window size of 15 bits)
+ /// * `serverMaxWindowBits`: null (default maximal window size of 15 bits)
static const CompressionOptions compressionDefault =
const CompressionOptions();
@Deprecated("Use compressionDefault instead")
static const CompressionOptions DEFAULT = compressionDefault;
- /// Disables WebSocket Compression.
+ /// No-compression configuration.
+ ///
+ /// Disables compression when used as compression configuration for a
+ /// [WebSocket].
static const CompressionOptions compressionOff =
const CompressionOptions(enabled: false);
@Deprecated("Use compressionOff instead")
static const CompressionOptions OFF = compressionOff;
- /// Controls whether the client will reuse its compression instances.
+ /// Whether the client will reuse its compression instances.
final bool clientNoContextTakeover;
- /// Controls whether the server will reuse its compression instances.
+ /// Whether the server will reuse its compression instances.
final bool serverNoContextTakeover;
- /// Determines the max window bits for the client.
+ /// The maximal window size bit count requested by the client.
+ ///
+ /// The windows size for the compression is always a power of two, so the
+ /// number of bits precisely determines the window size.
+ ///
+ /// If set to `null`, the client has no preference, and the compression can
+ /// use up to its default maximum window size of 15 bits depending on the
+ /// server's preference.
final int clientMaxWindowBits;
- /// Determines the max window bits for the server.
+ /// The maximal window size bit count requested by the server.
+ ///
+ /// The windows size for the compression is always a power of two, so the
+ /// number of bits precisely determines the window size.
+ ///
+ /// If set to `null`, the server has no preference, and the compression can
+ /// use up to its default maximum window size of 15 bits depending on the
+ /// client's preference.
final int serverMaxWindowBits;
- /// Enables or disables WebSocket compression.
+ /// Whether WebSocket compression is enabled.
+ ///
+ /// If not enabled, the remaining fields have no effect, and the
+ /// [compressionOff] instance can, and should, be reused instead of creating a
+ /// new instance with compression disabled.
final bool enabled;
const CompressionOptions(
- {this.clientNoContextTakeover: false,
- this.serverNoContextTakeover: false,
+ {this.clientNoContextTakeover = false,
+ this.serverNoContextTakeover = false,
this.clientMaxWindowBits,
this.serverMaxWindowBits,
- this.enabled: true});
+ this.enabled = true});
/// Parses list of requested server headers to return server compression
/// response headers.
