[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..0daaefd518aae22b3325af3135f1563947f80536
--- /dev/null
+++ b/net/docs/filter.md
@@ -0,0 +1,31 @@
+The network stack implements support for Content-Encodings using
+"source streams", which can be composed together and mutate all the incoming
+bytes from a URLRequestJob. Currently, the following streams are implemented:
+
+* gzip (handling "deflate" and "gzip" Content-Encodings)
+* sdch (handling "sdch" Content-Encoding)
+* brotli (handling "br" Content-Encoding)
+
+Source streams conceptually form a chain, with the URLRequestJob as both the
+beginning and end of the chain, meaning the URLRequestJob produces raw bytes at
+the end and consumes unencoded bytes at the beginning. For example, to support a
+hypothetical "Content-Encoding: bar,foo", streams would be arranged like so,
+with "X <-- Y" meaning "data flows from Y to X" or "X reads data from Y":
+
+  URLRequestJob <-- BarSourceStream <-- FooSourceStream <-- URLRequestJob
+                                                       (URLRequestSourceStream)
+
+Here the URLRequestJob pulls filtered bytes from BarSourceStream, which pulls
+filtered bytes from FooSourceStream, which in turn pulls raw bytes from the
+URLRequestJob.
+
+All source streams conform to the following interface (named SourceStream 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 source stream chain is "pull-based", in that data does not
+propagate through the chain until requested by the final consumer of the
+filtered data.