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