netwerk/protocol/http/README@deefc01c0e14 (annotated)
netwerk/protocol/http/README
Thu, 15 Jan 2015 21:03:48 +0100
- author
- Michael Schloh von Bennewitz <michael@schloh.com>
- date
- Thu, 15 Jan 2015 21:03:48 +0100
- branch
- TOR_BUG_9701
- changeset 11
- deefc01c0e14
- permissions
- -rw-r--r--
Integrate friendly tips from Tor colleagues to make (or not) 4.5 alpha 3;
This includes removal of overloaded (but unused) methods, and addition of
a overlooked call to DataStruct::SetData(nsISupports, uint32_t, bool.)
| michael@0 | 1 | Darin Fisher |
| michael@0 | 2 | darin@netscape.com |
| michael@0 | 3 | 8/8/2001 |
| michael@0 | 4 | |
| michael@0 | 5 | HTTP DESIGN NOTES |
| michael@0 | 6 | |
| michael@0 | 7 | |
| michael@0 | 8 | CLASS BREAKDOWN |
| michael@0 | 9 | |
| michael@0 | 10 | nsHttpHandler |
| michael@0 | 11 | - implements nsIProtocolHandler |
| michael@0 | 12 | - manages preferences |
| michael@0 | 13 | - owns the authentication cache |
| michael@0 | 14 | - holds references to frequently used services |
| michael@0 | 15 | |
| michael@0 | 16 | nsHttpChannel |
| michael@0 | 17 | - implements nsIHttpChannel |
| michael@0 | 18 | - talks to the cache |
| michael@0 | 19 | - initiates http transactions |
| michael@0 | 20 | - processes http response codes |
| michael@0 | 21 | - intercepts progress notifications |
| michael@0 | 22 | |
| michael@0 | 23 | nsHttpConnection |
| michael@0 | 24 | - implements nsIStreamListener & nsIStreamProvider |
| michael@0 | 25 | - talks to the socket transport service |
| michael@0 | 26 | - feeds data to its transaction object |
| michael@0 | 27 | - routes progress notifications |
| michael@0 | 28 | |
| michael@0 | 29 | nsHttpConnectionInfo |
| michael@0 | 30 | - identifies a connection |
| michael@0 | 31 | |
| michael@0 | 32 | nsHttpTransaction |
| michael@0 | 33 | - implements nsIRequest |
| michael@0 | 34 | - encapsulates a http request and response |
| michael@0 | 35 | - parses incoming data |
| michael@0 | 36 | |
| michael@0 | 37 | nsHttpChunkedDecoder |
| michael@0 | 38 | - owned by a transaction |
| michael@0 | 39 | - removes chunked decoding |
| michael@0 | 40 | |
| michael@0 | 41 | nsHttpRequestHead |
| michael@0 | 42 | - owns a nsHttpHeaderArray |
| michael@0 | 43 | - knows how to fill a request buffer |
| michael@0 | 44 | |
| michael@0 | 45 | nsHttpResponseHead |
| michael@0 | 46 | - owns a nsHttpHeaderArray |
| michael@0 | 47 | - knows how to parse response lines |
| michael@0 | 48 | - performs common header manipulations/calculations |
| michael@0 | 49 | |
| michael@0 | 50 | nsHttpHeaderArray |
| michael@0 | 51 | - stores http "<header>:<value>" pairs |
| michael@0 | 52 | |
| michael@0 | 53 | nsHttpAuthCache |
| michael@0 | 54 | - stores authentication credentials for http auth domains |
| michael@0 | 55 | |
| michael@0 | 56 | nsHttpBasicAuth |
| michael@0 | 57 | - implements nsIHttpAuthenticator |
| michael@0 | 58 | - generates BASIC auth credentials from user:pass |
| michael@0 | 59 | |
| michael@0 | 60 | |
| michael@0 | 61 | ATOMS |
| michael@0 | 62 | |
| michael@0 | 63 | nsHttp:: (header namespace) |
| michael@0 | 64 | |
| michael@0 | 65 | eg. nsHttp::Content_Length |
| michael@0 | 66 | |
| michael@0 | 67 | |
| michael@0 | 68 | TRANSACTION MODEL |
| michael@0 | 69 | |
| michael@0 | 70 | InitiateTransaction -> ActivateConnection -> AsyncWrite, AsyncRead |
| michael@0 | 71 | |
| michael@0 | 72 | The channel creates transactions, and passes them to the handler via |
| michael@0 | 73 | InitiateTransaction along with a nsHttpConnectionInfo object |
| michael@0 | 74 | identifying the requested connection. The handler either dispatches |
| michael@0 | 75 | the transaction immediately or queues it up to be dispatched later, |
| michael@0 | 76 | depending on whether or not the limit on the number of connections |
| michael@0 | 77 | to the requested server has been reached. Once the transaction can |
| michael@0 | 78 | be run, the handler looks for an idle connection or creates a new |
| michael@0 | 79 | connection, and then (re)activates the connection, assigning it the |
| michael@0 | 80 | new transaction. |
| michael@0 | 81 | |
| michael@0 | 82 | Once activated the connection ensures that it has a socket transport, |
| michael@0 | 83 | and then calls AsyncWrite and AsyncRead on the socket transport. This |
| michael@0 | 84 | begins the process of talking to the server. To minimize buffering, |
| michael@0 | 85 | socket transport thread-proxying is completely disabled (using the flags |
| michael@0 | 86 | DONT_PROXY_LISTENER | DONT_PROXY_PROVIDER | DONT_PROXY_OBSERVER with |
| michael@0 | 87 | both AsyncWrite and AsyncRead). This means that the nsHttpConnection's |
| michael@0 | 88 | OnStartRequest, OnDataAvailable, OnDataWritable, and OnStopRequest |
| michael@0 | 89 | methods will execute on the socket transport thread. |
| michael@0 | 90 | |
| michael@0 | 91 | The transaction defines (non-virtual) OnDataReadable, OnDataWritable, and |
| michael@0 | 92 | OnStopTransaction methods, which the connection calls in response to |
| michael@0 | 93 | its OnDataAvailable, OnDataWritable, and OnStopRequest methods, respectively. |
| michael@0 | 94 | The transaction owns a nsStreamListenerProxy created by the channel, which |
| michael@0 | 95 | it uses to transfer data from the socket thread over to the client's thread. |
| michael@0 | 96 | To mimize buffering, the transaction implements nsIInputStream, and passes |
| michael@0 | 97 | itself to the stream listener proxy's OnDataAvailable. In this way, we |
| michael@0 | 98 | have effectively wedged the response parsing between the socket and the |
| michael@0 | 99 | thread proxy's buffer. When read, the transaction turns around and reads |
| michael@0 | 100 | from the socket using the buffer passed to it. The transaction scans the |
| michael@0 | 101 | buffer for headers, removes them as they are detected, and copies the headers |
| michael@0 | 102 | into its nsHttpResponseHead object. The rest of the data remains in the |
| michael@0 | 103 | buffer, and is proxied over to the client's thread to be handled first by the |
| michael@0 | 104 | http channel and eventually by the client. |
| michael@0 | 105 | |
| michael@0 | 106 | There are several other major design factors, including: |
| michael@0 | 107 | |
| michael@0 | 108 | - transaction cancelation |
| michael@0 | 109 | - progress notification |
| michael@0 | 110 | - SSL tunneling |
| michael@0 | 111 | - chunked decoding |
| michael@0 | 112 | - thread safety |
| michael@0 | 113 | - premature EOF detection and transaction restarting |
| michael@0 | 114 | - pipelining (not yet implemented) |
| michael@0 | 115 | |
| michael@0 | 116 | |
| michael@0 | 117 | CACHING |
| michael@0 | 118 | |
| michael@0 | 119 | <EOF> |
