| Index: net/sdch/README.md
|
| diff --git a/net/sdch/README.md b/net/sdch/README.md
|
| deleted file mode 100644
|
| index 8200ee50528128417ca44e0269df9adb78cb9f47..0000000000000000000000000000000000000000
|
| --- a/net/sdch/README.md
|
| +++ /dev/null
|
| @@ -1,119 +0,0 @@
|
| -# SDCH
|
| -
|
| -"SDCH" stands for "Shared Dictionary Compression over HTTP". It is a
|
| -protocol for compressing URL responses used when the server and
|
| -the client share a dictionary that can be referred to for
|
| -compression/encoding and decompression/decoding. The details of the
|
| -SDCH protocol are specified in
|
| -[the spec](https://docs.google.com/a/chromium.org/document/d/1REMkwjXY5yFOkJwtJPjCMwZ4Shx3D9vfdAytV_KQCUo/edit?pli=1)
|
| -(soon to be moved to github) but in brief:
|
| -
|
| -1. If the client supports SDCH decoding, it advertises "sdch" in the
|
| - "Accept-Encoding" header.
|
| -2. If the server could have encoded a response with a dictionary (but
|
| - didn't, because the client didn't have the dictionary), it includes
|
| - an advisory "Get-Dictionary: <url>" header in its response.
|
| -3. If the client has a dictionary that the server has previously
|
| - advertised as being usable for encoding a particular requests, it
|
| - advertises that dictionary as being available via an
|
| - "Avail-Dictionary: <hash>" header in the request.
|
| -4. If the server chooses to encode a response with a dictionary, it
|
| - includes "sdch" in a "Content-Encoding" header, in which case the
|
| - body will reference the dictionary to be used for decoding (which
|
| - must be one the client advertised in the original request).
|
| - Encodings may be chained; often responses are SDCH encoded, and then
|
| - gzip encoded.
|
| -
|
| -## SDCH in Chromium: Overview
|
| -
|
| -The SDCH implementation in Chromium is spread across several classes
|
| -in several different directories:
|
| -
|
| -* SdchManager (in net/base): This class contains all
|
| - dictionaries currently known to Chromium. Each URLRequestContext
|
| - points to an SdchManager; at the chrome/ level, there is one
|
| - SdchManager per profile. URLRequestHttpJob consults the SdchManager
|
| - for what dictionaries should be advertised with a URLRequest, and
|
| - notifies the SdchManager whenever it sees a "Get-Dictionary"
|
| - header. The SdchManager does *not* mediate fetching of
|
| - dictionaries; it is conceptually layered underneath URLRequest and
|
| - has no knowledge of URLRequests. There are several nested classes of
|
| - SdchManager (Dictionary, DictionarySet) used in the SDCH
|
| - implementation; see sdch_manager.h for details.
|
| -* SdchObserver (in net/base). This is an Abstract Base
|
| - Class which other classes may implement if those classes wish to
|
| - receive notifications about SDCH events. Such classes should also
|
| - register as observers with the SdchManager.
|
| -* SdchFilter (int net/filter). This class is derived from net::Filter
|
| - that is used for decoding the SDCH response; it cooperates with
|
| - SdchManager and the URLRequestJob to decode SDCH encoded responses.
|
| -* SdchDictionaryFetcher (int net/url_request):
|
| - This class implements the nuts&bolts of fetching an SDCH
|
| - dictionary.
|
| -* SdchOwner (in net/sdch): This class is an SdchObserver.
|
| - It contains policy for the SDCH implementation, including mediation
|
| - of fetching dictionaries, prioritization and eviction of
|
| - dictionaries in response to new fetches, and constraints on the
|
| - amount of memory that is usable by SDCH dictionaries. It initiates
|
| - dictionary fetches as appropriate when it receives notification of
|
| - a "Get-Dictionary" header from the SdchManager.
|
| -
|
| -A net/ embedder should instantiate an SdchManager and an SdchOwner,
|
| -and guarantee that the SdchManager outlive the SdchOwner.
|
| -
|
| -Note the layering of the above classes:
|
| -
|
| -1. The SdchManager and SdchOwner classes have no knowledge of
|
| - URLRequests. URLRequest is dependent on those classes, not the
|
| - reverse.
|
| -2. SdchDictionaryFetcher is dependent on URLRequest, but is still a
|
| - utility class exported by the net/ library for use by higher levels.
|
| -3. SdchOwner manages the entire system on behalf of the embedder. The
|
| - intent is that the embedder can change policies through methods on
|
| - SdchOwner, while letting the SdchOwner class take care of policy
|
| - implementation.
|
| -
|
| -## SDCH in Chromium: Debugging
|
| -
|
| -Data that is useful in debugging SDCH problems:
|
| -
|
| -* The SDCH UMA prefix is "Sdch3", and histograms that have been found
|
| - useful for debugging include
|
| - * ProblemCodes_* (though this requires trawling the source for each bucket).
|
| - * ResponseCorruptionDetection.{Cached,Uncached}: An attempt to make
|
| - sense of the twisted mess in SdchFilter::ReadFilteredData mentioned
|
| - above.
|
| - * BlacklistReason: Why requests avoid using SDCH when they could use
|
| - it.
|
| -* about:net-internals has an SDCH tab, showing loaded dictionaries and
|
| - other information. Searching in net-internals for "Get-Dictionary",
|
| - the URLRequest that actually fetches that dictionary, and then the
|
| - hash of that dictionary (often used as the file name) can also be
|
| - useful.
|
| -
|
| -## SDCH in Chromium: Gotchas and corner cases
|
| -
|
| -There are a couple of known issues in SDCH in Chromium that developers
|
| -in this space should be aware of:
|
| -
|
| -* As noted in the spec above, there have historically been problems
|
| - with middleboxes stripping or corrupting SDCH encoded responses.
|
| - For this reason, the protocol requires that if a server is not using
|
| - SDCH encoding when it has previously advertised the availability of
|
| - doing such, it includes an "X-SDCH-Encode: 0" header in the
|
| - response. Servers don't always do this (especially multi-servers),
|
| - and that can result in failed decodings and requests being dropped
|
| - on the floor. The code to handle this is a twisted mess (see
|
| - SdchFilter::ReadFilteredData()) and problems have often been seen
|
| - from or associated with it.
|
| -* If the decoding logic trips over a problem, it will often blacklist
|
| - the server in question, temporarily (if it can recover that request)
|
| - or permanently (if it can't). This can lead to a mysterious lack of
|
| - SDCH encoding when it's expected to be present.
|
| -* The network cache currently stores the response precisely as received from
|
| - the network. This means that requests that don't advertise SDCH
|
| - may get a cached value that is SDCH encoded, and requests that do
|
| - advertise SDCH may get a cached value that is not SDCH encoded.
|
| - The second case is handled transparently, but the first case may
|
| - lead to request failure.
|
| -
|
|
|