[ON HOLD] Implement pull-based design for content decoding

net/docs/filter.md

Index: net/docs/filter.md
diff --git a/net/docs/filter.md b/net/docs/filter.md
new file mode 100644
index 0000000000000000000000000000000000000000..6e497329d88fead6e5dd9bdf6c83e70a534b7b06
--- /dev/null
+++ b/net/docs/filter.md
@@ -0,0 +1,28 @@
+The network stack implements support for Content-Encodings using "filters",
+which can be composed together and mutate all the incoming bytes from a
+URLRequestJob. Currently, the following filters are implemented:
+
+* gzip (handling "deflate" and "gzip" Content-Encodings)
+* sdch (handling "sdch" Content-Encoding)
+* brotili (handling "br" Content-Encoding)

[eustas, 2016/07/22 12:29:19]

s/brotili/brotli

[xunjieli, 2016/07/27 20:32:03]

Done.

+
+Filters conceptually form a chain, with the URLRequestJob as both the beginning
+and end of the chain, meaning the URLRequestJob produces raw bytes at the
+beginning and consumes filtered bytes at the end. For example, to support a
+hypothetical "Content-Encoding: bar,foo", filters would be arranged like so,
+with "X --> Y" meaning "Y reads bytes from X":
+
+  URLRequestJob --> FooFilter --> BarFilter --> URLRequestJob
+
+Here the URLRequestJob pulls filtered bytes from BarFilter, which pulls filtered
+bytes from FooFilter, which in turn pulls raw bytes from the URLRequestJob.
+
+All filters conform to the following interface (named StreamSource in the tree):
+
+  int Read(IOBuffer* dest_buffer, size_t buffer_size,
+           const OnReadCompleteCallback& callback);
+
+This function can return either synchronously or asynchronously via the supplied
+callback. The filter chain is "pull-based", in that data does not propagate
+through the filter chain until requested by the final consumer of the filtered
+data.