From ec763b014ee76e519569463279b30b0decb94400 Mon Sep 17 00:00:00 2001 From: Anne van Kesteren Date: Mon, 21 Oct 2024 07:58:39 -0700 Subject: [PATCH] Review Draft Publication: October 2024 --- index.bs | 1 + review-drafts/2024-10.bs | 207 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 208 insertions(+) create mode 100644 review-drafts/2024-10.bs diff --git a/index.bs b/index.bs index 1992e20..4e45c3b 100644 --- a/index.bs +++ b/index.bs @@ -3,6 +3,7 @@ Group: WHATWG H1: Compression Shortname: compression Text Macro: TWITTER compressionapi +Text Macro: LATESTRD 2024-10 Abstract: This document defines a set of JavaScript APIs to compress and decompress streams of binary data. Indent: 2 Markup Shorthands: markdown yes diff --git a/review-drafts/2024-10.bs b/review-drafts/2024-10.bs new file mode 100644 index 0000000..f4b887e --- /dev/null +++ b/review-drafts/2024-10.bs @@ -0,0 +1,207 @@ +
+Group: WHATWG
+Status: RD
+Date: 2024-10-21
+H1: Compression
+Shortname: compression
+Text Macro: TWITTER compressionapi
+Text Macro: LATESTRD 2024-10
+Abstract: This document defines a set of JavaScript APIs to compress and decompress streams of binary data.
+Indent: 2
+Markup Shorthands: markdown yes
+
+ +# Introduction # {#introduction} + +*This section is non-normative.* + +The APIs specified in this specification are used to compress and decompress streams of data. They support "deflate", "deflate-raw" and "gzip" as compression algorithms. They are widely used by web developers. + +# Infrastructure # {#infrastructure} + +This specification depends on Infra. [[!INFRA]] + +A chunk is a piece of data. In the case of CompressionStream and DecompressionStream, the output chunk type is Uint8Array. They accept any {{BufferSource}} type as input. + +A stream represents an ordered sequence of chunks. The terms {{ReadableStream}} and {{WritableStream}} are defined in Streams. [[!STREAMS]] + +A compression context is the internal state maintained by a compression or decompression algorithm. The contents of a compression context depend on the format, algorithm and implementation in use. From the point of view of this specification, it is an opaque object. A compression context is initially in a start state such that it anticipates the first byte of input. + +# Supported formats # {#supported-formats} + +: {{CompressionFormat/deflate}} +:: "ZLIB Compressed Data Format" [[!RFC1950]] + + Note: This format is referred to as "deflate" for consistency with HTTP Content-Encodings. See [[RFC7230 obsolete]] section 4.2.2. + + * Implementations must be "compliant" as described in [[!RFC1950]] section 2.3. + * Field values described as invalid in [[!RFC1950]] must not be created by CompressionStream, and are errors for DecompressionStream. + * The only valid value of the `CM` (Compression method) part of the `CMF` field is 8. + * The `FDICT` flag is not supported by these APIs, and will error the stream if set. + * The `FLEVEL` flag is ignored by DecompressionStream. + * It is an error for DecompressionStream if the `ADLER32` checksum is not correct. + * It is an error if there is additional input data after the `ADLER32` checksum. + +: {{CompressionFormat/deflate-raw}} +:: "The DEFLATE algorithm" [[!RFC1951]] + + * Implementations must be "compliant" as described in [[!RFC1951]] section 1.4. + * Non-[[!RFC1951]]-conforming blocks must not be created by CompressionStream, and are errors for DecompressionStream. + * It is an error if there is additional input data after the final block indicated by the `BFINAL` flag. + +: {{CompressionFormat/gzip}} +:: "GZIP file format" [[!RFC1952]] + + * Implementations must be "compliant" as described in [[!RFC1952]] section 2.3.1.2. + * Field values described as invalid in [[!RFC1952]] must not be created by CompressionStream, and are errors for DecompressionStream. + * The only valid value of the `CM` (Compression Method) field is 8. + * The `FTEXT` flag must be ignored by DecompressionStream. + * If the `FHCRC` field is present, it is an error for it to be incorrect. + * The contents of any `FEXTRA`, `FNAME` and `FCOMMENT` fields must be ignored by DecompressionStream, except to verify that they are terminated correctly. + * The contents of the `MTIME`, `XFL` and `OS` fields must be ignored by DecompressionStream. + * It is an error if `CRC32` or `ISIZE` do not match the decompressed data. + * A `gzip` stream may only contain one "member". + * It is an error if there is additional input data after the end of the "member". + +# Interface `CompressionStream` # {#compression-stream} + +
+enum CompressionFormat {
+  "deflate",
+  "deflate-raw",
+  "gzip",
+};
+
+[Exposed=*]
+interface CompressionStream {
+  constructor(CompressionFormat format);
+};
+CompressionStream includes GenericTransformStream;
+
+ +A {{CompressionStream}} has an associated format and compression context context. + +The new CompressionStream(|format|) steps are: + 1. If *format* is unsupported in {{CompressionStream}}, then throw a {{TypeError}}. + 1. Set [=this=]'s format to *format*. + 1. Let *transformAlgorithm* be an algorithm which takes a *chunk* argument and runs the compress and enqueue a chunk algorithm with [=this=] and *chunk*. + 1. Let *flushAlgorithm* be an algorithm which takes no argument and runs the compress flush and enqueue algorithm with [=this=]. + 1. Set [=this=]'s [=GenericTransformStream/transform=] to a [=new=] {{TransformStream}}. + 1. [=TransformStream/Set up=] [=this=]'s [=GenericTransformStream/transform=] with [=TransformStream/set up/transformAlgorithm=] set to *transformAlgorithm* and [=TransformStream/set up/flushAlgorithm=] set to *flushAlgorithm*. + +The compress and enqueue a chunk algorithm, given a {{CompressionStream}} object *cs* and a *chunk*, runs these steps: + 1. If *chunk* is not a {{BufferSource}} type, then throw a {{TypeError}}. + 1. Let *buffer* be the result of compressing *chunk* with *cs*'s format and context. + 1. If *buffer* is empty, return. + 1. Split *buffer* into one or more non-empty pieces and convert them into {{Uint8Array}}s. + 1. For each {{Uint8Array}} *array*, [=TransformStream/enqueue=] *array* in *cs*'s [=GenericTransformStream/transform=]. + +The compress flush and enqueue algorithm, which handles the end of data from the input {{ReadableStream}} object, given a {{CompressionStream}} object *cs*, runs these steps: + + 1. Let *buffer* be the result of compressing an empty input with *cs*'s format and context, with the finish flag. + 1. If *buffer* is empty, return. + 1. Split *buffer* into one or more non-empty pieces and convert them into {{Uint8Array}}s. + 1. For each {{Uint8Array}} *array*, [=TransformStream/enqueue=] *array* in *cs*'s [=GenericTransformStream/transform=]. + + +# Interface `DecompressionStream` # {#decompression-stream} + +
+[Exposed=*]
+interface DecompressionStream {
+  constructor(CompressionFormat format);
+};
+DecompressionStream includes GenericTransformStream;
+
+ +A {{DecompressionStream}} has an associated format and compression context context. + +The new DecompressionStream(|format|) steps are: + 1. If *format* is unsupported in {{DecompressionStream}}, then throw a {{TypeError}}. + 1. Set [=this=]'s format to *format*. + 1. Let *transformAlgorithm* be an algorithm which takes a *chunk* argument and runs the decompress and enqueue a chunk algorithm with [=this=] and *chunk*. + 1. Let *flushAlgorithm* be an algorithm which takes no argument and runs the decompress flush and enqueue algorithm with [=this=]. + 1. Set [=this=]'s [=GenericTransformStream/transform=] to a [=new=] {{TransformStream}}. + 1. [=TransformStream/Set up=] [=this=]'s [=GenericTransformStream/transform=] with [=TransformStream/set up/transformAlgorithm=] set to *transformAlgorithm* and [=TransformStream/set up/flushAlgorithm=] set to *flushAlgorithm*. + +The decompress and enqueue a chunk algorithm, given a {{DecompressionStream}} object *ds* and a *chunk*, runs these steps: + 1. If *chunk* is not a {{BufferSource}} type, then throw a {{TypeError}}. + 1. Let *buffer* be the result of decompressing *chunk* with *ds*'s format and context. If this results in an error, then throw a {{TypeError}}. + 1. If *buffer* is empty, return. + 1. Split *buffer* into one or more non-empty pieces and convert them into {{Uint8Array}}s. + 1. For each {{Uint8Array}} *array*, [=TransformStream/enqueue=] *array* in *ds*'s [=GenericTransformStream/transform=]. + +The decompress flush and enqueue algorithm, which handles the end of data from the input {{ReadableStream}} object, given a {{DecompressionStream}} object *ds*, runs these steps: + + 1. Let *buffer* be the result of decompressing an empty input with *ds*'s format and context, with the finish flag. + 1. If the end of the compressed input has not been reached, then throw a {{TypeError}}. + 1. If *buffer* is empty, return. + 1. Split *buffer* into one or more non-empty pieces and convert them into {{Uint8Array}}s. + 1. For each {{Uint8Array}} *array*, [=TransformStream/enqueue=] *array* in *ds*'s [=GenericTransformStream/transform=]. + + +# Privacy and security considerations # {#privacy-security} + +The API doesn't add any new privileges to the web platform. + +However, web developers have to pay attention to the situation when attackers can get the length of the data. If so, they may be able to guess the contents of the data. + +# Examples # {#examples} + +## Gzip-compress a stream ## {#example-gzip-compress-stream} + +
+
+const compressedReadableStream
+    = inputReadableStream.pipeThrough(new CompressionStream('gzip'));
+
+
+ +## Deflate-compress an ArrayBuffer to a Uint8Array ## {#example-deflate-compress} + +
+
+async function compressArrayBuffer(input) {
+  const cs = new CompressionStream('deflate');
+
+  const writer = cs.writable.getWriter();
+  writer.write(input);
+  writer.close();
+
+  const output = [];
+  let totalSize = 0;
+  for (const chunk of cs.readable) {
+    output.push(value);
+    totalSize += value.byteLength;
+  }
+
+  const concatenated = new Uint8Array(totalSize);
+  let offset = 0;
+  for (const array of output) {
+    concatenated.set(array, offset);
+    offset += array.byteLength;
+  }
+
+  return concatenated;
+}
+
+
+ +## Gzip-decompress a Blob to Blob ## {#example-gzip-decompress} + +
+
+function decompressBlob(blob) {
+  const ds = new DecompressionStream('gzip');
+  const decompressionStream = blob.stream().pipeThrough(ds);
+  return new Response(decompressionStream).blob();
+}
+
+
+ +

Acknowledgments

+Thanks to Canon Mukai, Domenic Denicola, and Yutaka Hirano, for their support. + +This standard is written by Adam Rice (Google, ricea@chromium.org). + +

This Living Standard was originally developed in the W3C WICG, where it was available under the [W3C Software and Document License](https://www.w3.org/Consortium/Legal/2015/copyright-software-and-document).