=== Problems with `twisted.web.client` ===

  1. Poorly implemented and tested
  1. Inflexible API:
    1. can't get headers (without mucking around with url parsing and custom factories)
    1. can't stream request/response
    1. can't override protocol behavior without duplicating lots of code
  1. doesn't support lots of http features, eg:
    1. caching
    1. pipelining
    1. connection reuse
    1. chunked (or any other) encoding
    1. byte ranges
    1. AND SO ON FOR EVER
  1. hard to test (doesn't parameterize reactor, messes around with global state)

=== Replacement API ===

  * Introduce a low-level implementation of a good generic request/response interface
  * the interface will have a single method for submitting a request and getting back a response (or an error)
    * errors can indicate:
      * request could not be sent at all (eg, connection does not exist)
      * maybe some other stuff (dns?)
    * response includes all aspects of the http response
      * status
      * headers
      * streaming data/response body
      * trailers hahahahahahahahahahahahahahahaha
  * First implementation will be a very simple HTTP protocol implementation without support for features such as persistent connections or pipelining
    * the class can be improved later to add these features without changing the basic request/response api
  * Higher level wrappers (with the same request/response API) will add features like:
    * transparent redirect handling
    * authentication
    * caching/etags/if-modified-since/etc
    * connection management (pools, reconnect, etc)
    * ssl something?  certificate/hostname verification etc
    * etc

=== Plan ===

  1. [ticket:886 Implement minimal, good, well-tested (etc) HTTP client protocol and the basic request/response API from above (maybe based on `twisted.web2.client`)]
  1. Support timeouts: #3450, #4330, probably others
  1. [ticket:3987 Implement a high-level API with minimal additional functionality]
    1. [ticket:4017 Provide a file-based message body producer]
  1. Allow binding to a particular local interface (handled in #3450)
  1. Make requests over IPv6 when necessary/appropriate
  1. [ticket:1774 Support HTTP proxies]
  1. Implement other HTTP protocol and high-level features
    1. Provide a ''multipart/form-data'' body producer
    1. [ticket:4023 Support HTTPS URLs and certificate verification]
    1. [ticket:4922 Implement a cookie-aware `Agent` wrapper]
    1. Implement a gzip-aware `Agent` wrapper (sending and [ticket:5053 receiving]?)
    1. [ticket:5148 Implement an authentication wrapper]
    1. [ticket:5126 Implement a caching wrapper]
    1. [ticket:3420 high-level access to persistent connections]
      1. [ticket:4223 low-level protocol support for controlling whether the connection is re-used or not]
    1. Support pipelined requests in the high-level API
    1. [ticket:5192 ''100 Continue'' support]
    1. [ticket:5157 Redirect following (perhaps multiple policies, dealing with POST/PUT/etc redirects)]
  1. Implement HTTP header parsing to provide access to structured header values (based on `twisted.web2.http_headers`)