author Ehsan Akhgari <>
Sat, 05 Jun 2010 21:23:26 -0400
changeset 43173 ac1ed3f6b2e71637e562866867c9ac571d2cb283
parent 43144 2d90590dabe63ad9d6323376e6a1138add81e1cb
parent 43113 d8dc49d5bd609668b3c4fadd6c1df12d5da20547
child 132081 c87ddaff7aa4c8c432093fecb807b6b5e9cf5fc1
permissions -rw-r--r--
Merge resolving the bad rename changeset landed as part of bug 542222

                                                        Darin Fisher

                            HTTP DESIGN NOTES


    - implements nsIProtocolHandler
    - manages preferences
    - owns the authentication cache
    - holds references to frequently used services

    - implements nsIHttpChannel
    - talks to the cache
    - initiates http transactions
    - processes http response codes
    - intercepts progress notifications
    - implements nsIStreamListener & nsIStreamProvider
    - talks to the socket transport service
    - feeds data to its transaction object
    - routes progress notifications

    - identifies a connection

    - implements nsIRequest
    - encapsulates a http request and response
    - parses incoming data

    - owned by a transaction
    - removes chunked decoding
    - owns a nsHttpHeaderArray
    - knows how to fill a request buffer

    - owns a nsHttpHeaderArray
    - knows how to parse response lines
    - performs common header manipulations/calculations

    - stores http "<header>:<value>" pairs

    - stores authentication credentials for http auth domains

    - implements nsIHttpAuthenticator
    - generates BASIC auth credentials from user:pass


  nsHttp:: (header namespace)

  eg. nsHttp::Content_Length


  InitiateTransaction -> ActivateConnection -> AsyncWrite, AsyncRead

  The channel creates transactions, and passes them to the handler via
  InitiateTransaction along with a nsHttpConnectionInfo object 
  identifying the requested connection.  The handler either dispatches
  the transaction immediately or queues it up to be dispatched later,
  depending on whether or not the limit on the number of connections
  to the requested server has been reached.  Once the transaction can
  be run, the handler looks for an idle connection or creates a new
  connection, and then (re)activates the connection, assigning it the
  new transaction.

  Once activated the connection ensures that it has a socket transport,
  and then calls AsyncWrite and AsyncRead on the socket transport.  This
  begins the process of talking to the server.  To minimize buffering,
  socket transport thread-proxying is completely disabled (using the flags
  both AsyncWrite and AsyncRead).  This means that the nsHttpConnection's
  OnStartRequest, OnDataAvailable, OnDataWritable, and OnStopRequest
  methods will execute on the socket transport thread.

  The transaction defines (non-virtual) OnDataReadable, OnDataWritable, and
  OnStopTransaction methods, which the connection calls in response to
  its OnDataAvailable, OnDataWritable, and OnStopRequest methods, respectively.
  The transaction owns a nsStreamListenerProxy created by the channel, which
  it uses to transfer data from the socket thread over to the client's thread.
  To mimize buffering, the transaction implements nsIInputStream, and passes
  itself to the stream listener proxy's OnDataAvailable.  In this way, we
  have effectively wedged the response parsing between the socket and the
  thread proxy's buffer.  When read, the transaction turns around and reads
  from the socket using the buffer passed to it.  The transaction scans the
  buffer for headers, removes them as they are detected, and copies the headers
  into its nsHttpResponseHead object.  The rest of the data remains in the
  buffer, and is proxied over to the client's thread to be handled first by the
  http channel and eventually by the client.

  There are several other major design factors, including:

    - transaction cancelation
    - progress notification
    - SSL tunneling
    - chunked decoding
    - thread safety
    - premature EOF detection and transaction restarting
    - pipelining (not yet implemented)