netwerk/protocol/http/src/README

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