[dart:io] Clarify CompressionOptions null window bits means default window.

sortie · commit-bot@chromium.org · commit 9ff2c109bb40 · 2019-06-07T15:03:30.000Z
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 <dart-lang/co19#364>. Closes #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
@@ -50,51 +50,78 @@ abstract class WebSocketStatus {
   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.
