[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..a870f3c264cef66cfd471c6b6a62b3d5bfc28b06
--- /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)
+
+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":

[Randy Smith (Not in Mondays), 2016/02/08 23:28:42]

Hmmm.  For what it's worth, when I see an arrow between two letters, I think of
the arrow direction as the direction the data moves in, i.e. that "X <-- Y"
would be "X reads bytes from Y".

[xunjieli, 2016/03/03 23:00:08]

Done.

+
+  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):
+
+  net::Error Read(IOBuffer* dest_buffer, size_t buffer_size, size_t *bytes_read,
+                  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.