Complete the authentication section, and flesh out the proxy and DAV

sections.

pep-0268.txt

@@ -7,7 +7,7 @@ Status: Draft
 Type: Standards Track
 Created: 20-Aug-2001
 Python-Version: 2.2
-Post-History:
+Post-History: 21-Aug-2001
 
 
 Abstract
@@ -62,7 +62,7 @@ HTTP Authentication
     The httpx module will provide a mixin for performing HTTP
     authentication (for both proxy and origin server
     authentication). This mixin (httpx.HandleAuthentication) can be
-    combined with the HTTPConnection or the HTTPSConnection classes
+    combined with the HTTPConnection and the HTTPSConnection classes
     (the mixin may possibly work with the HTTP and HTTPS compatibility
     classes, but that is not a requirement).
 
@@ -70,14 +70,13 @@ HTTP Authentication
     "authenticator" objects, allowing multiple connections to share
     authenticators. The use of a separate object allows for a long
     term connection to an authentication system (e.g. LDAP). An
-    authenticator for the Basic mechanism (see RFC 2617) will be
-    provided. Digest would be great, but we need to find some code for
-    it (or a motivated developer). User-supplied authenticator
-    subclasses can be registered and used by the connections.
+    authenticator for the Basic and Digest mechanisms (see RFC 2617)
+    will be provided. User-supplied authenticator subclasses can be
+    registered and used by the connections.
 
-    A "credentials" object is also associated with the mixin, and
-    stores the credentials (e.g. username and password) needed by the
-    authenticators. Subclasses of the credentials object can be
+    A "credentials" object (httpx.Credentials) is also associated with
+    the mixin, and stores the credentials (e.g. username and password)
+    needed by the authenticators. Subclasses of Credentials can be
     created to hold additional information (e.g. NT domain).
 
     The mixin overrides the getresponse() method to detect 401
@@ -89,7 +88,8 @@ HTTP Authentication
     security if multiple schemes are in the response). Each
     authenticator can examine the response headers and decide whether
     and how to resend the request with the correct authentication
-    headers.
+    headers. If no authenticator can successfully handle the
+    authentication, then an exception is raised.
 
     Resending a request, with the appropriate credentials, is one of
     the more difficult portions of the authentication system. The
@@ -104,26 +104,77 @@ HTTP Authentication
     can resend the request with the appropriate authentication
     information.
 
-    [ what to do when the body is too big: raise an error? special
-    return value? ... ]
+    If the body is too large to be stored, then the getresponse()
+    simply returns the response object, indicating the 401 or 407
+    error. Since the authentication information has been computed and
+    cached (into the Credentials object; see below), the caller can
+    simply regenerate the request. The mixin will attach the
+    appropriate credentials.
 
-    [ need more info here about storing realms/headers in the
-    credentials object (keyed by host, port) ... resending those
-    automatically when making requests ... persisting the credentials
-    object to have the info next time ... ]
+    A "protection space" (see RFC 2617, section 1.2) is defined as a
+    tuple of the host, port, and authentication realm. When a request
+    is initially sent to an HTTP server, we do not know the
+    authentication realm (the realm is only returned when
+    authentication fails). However, we do have the path from the URL,
+    and that can be useful in determining the credentials to send to
+    the server.  The Basic authentication scheme is typically set up
+    hierarchically: the credentials for /path can be tried for
+    /path/subpath. The Digest authentication scheme has explicit
+    support for the hierarchical setup. The httpx.Credentials object
+    will store credentials for multiple protection spaces, and can be
+    looked up in two differents ways:
 
-    [ two sets of credentials: one for proxy, one for origin ... ]
+    1) looked up using (host, port, path) -- this lookup scheme is
+    used when generating a request for a path where we don't know the
+    authentication realm.
+
+    2) looked up using (host, port, realm) -- this mechanism is used
+    during the authentication process when the server has specified
+    that the Request-URI resides within a specific realm.
+
+    The mixin will override endheaders() to automatically insert
+    credentials, if available.
+
+    It is also important to note that two sets of credentials are
+    important, and stored by the mixin. One set for any proxy that may
+    be used, and one used for the target origin server.
 
 
 Proxy Handling
 
-    ... info about proxy handling ... note that proxy auth is handled
-    above ...
+    The httpx module will provide a mixin for using a proxy to perform
+    HTTP(S) operations. This mixin (httpx.UseProxy) can be combined
+    with the HTTPConnection and the HTTPSConnection classes (the mixin
+    may possibly work with the HTTP and HTTPS compatibility classes,
+    but that is not a requirement).
+
+    The mixin will record the (host, port) of the proxy to use. XXX
+    will be overridden to use this host/port combination for
+    connections and to rewrite request URLs into the absoluteURIs
+    referring to the origin server (these URIs are passed to the proxy
+    server).
+
+    Proxy authentication is handled by the httpx.HandleAuthentication
+    class since a user may directly use HTTP(S)Connection to speak
+    with proxies.
 
 
 WebDAV Features
 
-    ... info about the dav module ...
+    The davlib module will provide a mixin for sending WebDAV requests
+    to a WebDAV-enabled server. This mixin (davlib.DAVClient) can be
+    combined with the HTTPConnection and the HTTPSConnection classes
+    (the mixin may possibly work with the HTTP and HTTPS compatibility
+    classes, but that is not a requirement).
+
+    The mixin provides methods to perform the various HTTP methods
+    defined by HTTP in RFC 2616, and by WebDAV in RFC 2518.
+
+    A custom response object is used to decode 207 (Multi-Status)
+    responses. The response object will use the standard library's xml
+    package to parse the multistatus XML information, producing a
+    simple structure of objects to hold the multistatus data. Multiple
+    parsing schemes will be tried/used, in order of decreasing speed.
 
 
 Reference Implementation