twisted/web/iweb.py

   1 # -*- test-case-name: twisted.web.test -*-
   2 # Copyright (c) Twisted Matrix Laboratories.
   3 # See LICENSE for details.
   4
   5 """
   6 Interface definitions for L{twisted.web}.
   7
   8 @var UNKNOWN_LENGTH: An opaque object which may be used as the value of
   9     L{IBodyProducer.length} to indicate that the length of the entity
  10     body is not known in advance.
  11 """
  12
  13 from zope.interface import Interface, Attribute
  14
  15 from twisted.internet.interfaces import IPushProducer
  16 from twisted.cred.credentials import IUsernameDigestHash
  17
  18
  19 class IRequest(Interface):
  20     """
  21     An HTTP request.
  22
  23     @since: 9.0
  24     """
  25
  26     method = Attribute("A C{str} giving the HTTP method that was used.")
  27     uri = Attribute(
  28         "A C{str} giving the full encoded URI which was requested (including "
  29         "query arguments).")
  30     path = Attribute(
  31         "A C{str} giving the encoded query path of the request URI.")
  32     args = Attribute(
  33         "A mapping of decoded query argument names as C{str} to "
  34         "corresponding query argument values as C{list}s of C{str}.  "
  35         "For example, for a URI with C{'foo=bar&foo=baz&quux=spam'} "
  36         "for its query part, C{args} will be C{{'foo': ['bar', 'baz'], "
  37         "'quux': ['spam']}}.")
  38
  39     received_headers = Attribute(
  40         "Backwards-compatibility access to C{requestHeaders}.  Use "
  41         "C{requestHeaders} instead.  C{received_headers} behaves mostly "
  42         "like a C{dict} and does not provide access to all header values.")
  43
  44     requestHeaders = Attribute(
  45         "A L{http_headers.Headers} instance giving all received HTTP request "
  46         "headers.")
  47
  48     headers = Attribute(
  49         "Backwards-compatibility access to C{responseHeaders}.  Use"
  50         "C{responseHeaders} instead.  C{headers} behaves mostly like a "
  51         "C{dict} and does not provide access to all header values nor "
  52         "does it allow multiple values for one header to be set.")
  53
  54     responseHeaders = Attribute(
  55         "A L{http_headers.Headers} instance holding all HTTP response "
  56         "headers to be sent.")
  57
  58     def getHeader(key):
  59         """
  60         Get an HTTP request header.
  61
  62         @type key: C{str}
  63         @param key: The name of the header to get the value of.
  64
  65         @rtype: C{str} or C{NoneType}
  66         @return: The value of the specified header, or C{None} if that header
  67             was not present in the request.
  68         """
  69
  70
  71     def getCookie(key):
  72         """
  73         Get a cookie that was sent from the network.
  74         """
  75
  76
  77     def getAllHeaders():
  78         """
  79         Return dictionary mapping the names of all received headers to the last
  80         value received for each.
  81
  82         Since this method does not return all header information,
  83         C{requestHeaders.getAllRawHeaders()} may be preferred.
  84         """
  85
  86
  87     def getRequestHostname():
  88         """
  89         Get the hostname that the user passed in to the request.
  90
  91         This will either use the Host: header (if it is available) or the
  92         host we are listening on if the header is unavailable.
  93
  94         @returns: the requested hostname
  95         @rtype: C{str}
  96         """
  97
  98
  99     def getHost():
 100         """
 101         Get my originally requesting transport's host.
 102
 103         @return: An L{IAddress}.
 104         """
 105
 106
 107     def getClientIP():
 108         """
 109         Return the IP address of the client who submitted this request.
 110
 111         @returns: the client IP address or C{None} if the request was submitted
 112             over a transport where IP addresses do not make sense.
 113         @rtype: C{str} or L{NoneType}
 114         """
 115
 116
 117     def getClient():
 118         """
 119         Return the hostname of the IP address of the client who submitted this
 120         request, if possible.
 121
 122         This method is B{deprecated}.  See L{getClientIP} instead.
 123
 124         @rtype: L{NoneType} or L{str}
 125         @return: The canonical hostname of the client, as determined by
 126             performing a name lookup on the IP address of the client.
 127         """
 128
 129
 130     def getUser():
 131         """
 132         Return the HTTP user sent with this request, if any.
 133
 134         If no user was supplied, return the empty string.
 135
 136         @returns: the HTTP user, if any
 137         @rtype: C{str}
 138         """
 139
 140
 141     def getPassword():
 142         """
 143         Return the HTTP password sent with this request, if any.
 144
 145         If no password was supplied, return the empty string.
 146
 147         @returns: the HTTP password, if any
 148         @rtype: C{str}
 149         """
 150
 151
 152     def isSecure():
 153         """
 154         Return True if this request is using a secure transport.
 155
 156         Normally this method returns True if this request's HTTPChannel
 157         instance is using a transport that implements ISSLTransport.
 158
 159         This will also return True if setHost() has been called
 160         with ssl=True.
 161
 162         @returns: True if this request is secure
 163         @rtype: C{bool}
 164         """
 165
 166
 167     def getSession(sessionInterface=None):
 168         """
 169         Look up the session associated with this request or create a new one if
 170         there is not one.
 171
 172         @return: The L{Session} instance identified by the session cookie in
 173             the request, or the C{sessionInterface} component of that session
 174             if C{sessionInterface} is specified.
 175         """
 176
 177
 178     def URLPath():
 179         """
 180         @return: A L{URLPath} instance which identifies the URL for which this
 181             request is.
 182         """
 183
 184
 185     def prePathURL():
 186         """
 187         @return: At any time during resource traversal, a L{str} giving an
 188             absolute URL to the most nested resource which has yet been
 189             reached.
 190         """
 191
 192
 193     def rememberRootURL():
 194         """
 195         Remember the currently-processed part of the URL for later
 196         recalling.
 197         """
 198
 199
 200     def getRootURL():
 201         """
 202         Get a previously-remembered URL.
 203         """
 204
 205
 206     # Methods for outgoing response
 207     def finish():
 208         """
 209         Indicate that the response to this request is complete.
 210         """
 211
 212
 213     def write(data):
 214         """
 215         Write some data to the body of the response to this request.  Response
 216         headers are written the first time this method is called, after which
 217         new response headers may not be added.
 218         """
 219
 220
 221     def addCookie(k, v, expires=None, domain=None, path=None, max_age=None, comment=None, secure=None):
 222         """
 223         Set an outgoing HTTP cookie.
 224
 225         In general, you should consider using sessions instead of cookies, see
 226         L{twisted.web.server.Request.getSession} and the
 227         L{twisted.web.server.Session} class for details.
 228         """
 229
 230
 231     def setResponseCode(code, message=None):
 232         """
 233         Set the HTTP response code.
 234         """
 235
 236
 237     def setHeader(k, v):
 238         """
 239         Set an HTTP response header.  Overrides any previously set values for
 240         this header.
 241
 242         @type name: C{str}
 243         @param name: The name of the header for which to set the value.
 244
 245         @type value: C{str}
 246         @param value: The value to set for the named header.
 247         """
 248
 249
 250     def redirect(url):
 251         """
 252         Utility function that does a redirect.
 253
 254         The request should have finish() called after this.
 255         """
 256
 257
 258     def setLastModified(when):
 259         """
 260         Set the C{Last-Modified} time for the response to this request.
 261
 262         If I am called more than once, I ignore attempts to set Last-Modified
 263         earlier, only replacing the Last-Modified time if it is to a later
 264         value.
 265
 266         If I am a conditional request, I may modify my response code to
 267         L{NOT_MODIFIED} if appropriate for the time given.
 268
 269         @param when: The last time the resource being returned was modified, in
 270             seconds since the epoch.
 271         @type when: C{int}, C{long} or C{float}
 272
 273         @return: If I am a C{If-Modified-Since} conditional request and the
 274             time given is not newer than the condition, I return
 275             L{http.CACHED<CACHED>} to indicate that you should write no body.
 276             Otherwise, I return a false value.
 277         """
 278
 279
 280     def setETag(etag):
 281         """
 282         Set an C{entity tag} for the outgoing response.
 283
 284         That's "entity tag" as in the HTTP/1.1 C{ETag} header, "used for
 285         comparing two or more entities from the same requested resource."
 286
 287         If I am a conditional request, I may modify my response code to
 288         L{NOT_MODIFIED} or L{PRECONDITION_FAILED}, if appropriate for the tag
 289         given.
 290
 291         @param etag: The entity tag for the resource being returned.
 292         @type etag: C{str}
 293         @return: If I am a C{If-None-Match} conditional request and the tag
 294             matches one in the request, I return L{http.CACHED<CACHED>} to
 295             indicate that you should write no body.  Otherwise, I return a
 296             false value.
 297         """
 298
 299
 300     def setHost(host, port, ssl=0):
 301         """
 302         Change the host and port the request thinks it's using.
 303
 304         This method is useful for working with reverse HTTP proxies (e.g.  both
 305         Squid and Apache's mod_proxy can do this), when the address the HTTP
 306         client is using is different than the one we're listening on.
 307
 308         For example, Apache may be listening on https://www.example.com, and
 309         then forwarding requests to http://localhost:8080, but we don't want
 310         HTML produced by Twisted to say 'http://localhost:8080', they should
 311         say 'https://www.example.com', so we do::
 312
 313            request.setHost('www.example.com', 443, ssl=1)
 314         """
 315
 316
 317
 318 class ICredentialFactory(Interface):
 319     """
 320     A credential factory defines a way to generate a particular kind of
 321     authentication challenge and a way to interpret the responses to these
 322     challenges.  It creates L{ICredentials} providers from responses.  These
 323     objects will be used with L{twisted.cred} to authenticate an authorize
 324     requests.
 325     """
 326     scheme = Attribute(
 327         "A C{str} giving the name of the authentication scheme with which "
 328         "this factory is associated.  For example, C{'basic'} or C{'digest'}.")
 329
 330
 331     def getChallenge(request):
 332         """
 333         Generate a new challenge to be sent to a client.
 334
 335         @type peer: L{twisted.web.http.Request}
 336         @param peer: The request the response to which this challenge will be
 337             included.
 338
 339         @rtype: C{dict}
 340         @return: A mapping from C{str} challenge fields to associated C{str}
 341             values.
 342         """
 343
 344
 345     def decode(response, request):
 346         """
 347         Create a credentials object from the given response.
 348
 349         @type response: C{str}
 350         @param response: scheme specific response string
 351
 352         @type request: L{twisted.web.http.Request}
 353         @param request: The request being processed (from which the response
 354             was taken).
 355
 356         @raise twisted.cred.error.LoginFailed: If the response is invalid.
 357
 358         @rtype: L{twisted.cred.credentials.ICredentials} provider
 359         @return: The credentials represented by the given response.
 360         """
 361
 362
 363
 364 class IBodyProducer(IPushProducer):
 365     """
 366     Objects which provide L{IBodyProducer} write bytes to an object which
 367     provides L{IConsumer} by calling its C{write} method repeatedly.
 368
 369     L{IBodyProducer} providers may start producing as soon as they have
 370     an L{IConsumer} provider.  That is, they should not wait for a
 371     C{resumeProducing} call to begin writing data.
 372
 373     L{IConsumer.unregisterProducer} must not be called.  Instead, the
 374     L{Deferred} returned from C{startProducing} must be fired when all bytes
 375     have been written.
 376
 377     L{IConsumer.write} may synchronously invoke any of C{pauseProducing},
 378     C{resumeProducing}, or C{stopProducing}.  These methods must be implemented
 379     with this in mind.
 380
 381     @since: 9.0
 382     """
 383
 384     # Despite the restrictions above and the additional requirements of
 385     # stopProducing documented below, this interface still needs to be an
 386     # IPushProducer subclass.  Providers of it will be passed to IConsumer
 387     # providers which only know about IPushProducer and IPullProducer, not
 388     # about this interface.  This interface needs to remain close enough to one
 389     # of those interfaces for consumers to work with it.
 390
 391     length = Attribute(
 392         """
 393         C{length} is a C{int} indicating how many bytes in total this
 394         L{IBodyProducer} will write to the consumer or L{UNKNOWN_LENGTH}
 395         if this is not known in advance.
 396         """)
 397
 398     def startProducing(consumer):
 399         """
 400         Start producing to the given L{IConsumer} provider.
 401
 402         @return: A L{Deferred} which fires with C{None} when all bytes have
 403             been produced or with a L{Failure} if there is any problem before
 404             all bytes have been produced.
 405         """
 406
 407
 408     def stopProducing():
 409         """
 410         In addition to the standard behavior of L{IProducer.stopProducing}
 411         (stop producing data), make sure the L{Deferred} returned by
 412         C{startProducing} is never fired.
 413         """
 414
 415
 416
 417 class IRenderable(Interface):
 418     """
 419     An L{IRenderable} is an object that may be rendered by the
 420     L{twisted.web.template} templating system.
 421     """
 422
 423     def lookupRenderMethod(name):
 424         """
 425         Look up and return the render method associated with the given name.
 426
 427         @type name: C{str}
 428         @param name: The value of a render directive encountered in the
 429             document returned by a call to L{IRenderable.render}.
 430
 431         @return: A two-argument callable which will be invoked with the request
 432             being responded to and the tag object on which the render directive
 433             was encountered.
 434         """
 435
 436
 437     def render(request):
 438         """
 439         Get the document for this L{IRenderable}.
 440
 441         @type request: L{IRequest} provider or L{NoneType}
 442         @param request: The request in response to which this method is being
 443             invoked.
 444
 445         @return: An object which can be flattened.
 446         """
 447
 448
 449
 450 class ITemplateLoader(Interface):
 451     """
 452     A loader for templates; something usable as a value for
 453     L{twisted.web.template.Element}'s C{loader} attribute.
 454     """
 455
 456     def load():
 457         """
 458         Load a template suitable for rendering.
 459
 460         @return: a C{list} of C{list}s, C{unicode} objects, C{Element}s and
 461             other L{IRenderable} providers.
 462         """
 463
 464
 465
 466 class IResponse(Interface):
 467     """
 468     An object representing an HTTP response received from an HTTP server.
 469
 470     @since: 11.1
 471     """
 472
 473     version = Attribute(
 474         "A three-tuple describing the protocol and protocol version "
 475         "of the response.  The first element is of type C{str}, the second "
 476         "and third are of type C{int}.  For example, C{('HTTP', 1, 1)}.")
 477
 478
 479     code = Attribute("The HTTP status code of this response, as a C{int}.")
 480
 481
 482     phrase = Attribute(
 483         "The HTTP reason phrase of this response, as a C{str}.")
 484
 485
 486     headers = Attribute("The HTTP response L{Headers} of this response.")
 487
 488
 489     length = Attribute(
 490         "The C{int} number of bytes expected to be in the body of this "
 491         "response or L{UNKNOWN_LENGTH} if the server did not indicate how "
 492         "many bytes to expect.  For I{HEAD} responses, this will be 0; if "
 493         "the response includes a I{Content-Length} header, it will be "
 494         "available in C{headers}.")
 495
 496
 497     def deliverBody(protocol):
 498         """
 499         Register an L{IProtocol} provider to receive the response body.
 500
 501         The protocol will be connected to a transport which provides
 502         L{IPushProducer}.  The protocol's C{connectionLost} method will be
 503         called with:
 504
 505             - ResponseDone, which indicates that all bytes from the response
 506               have been successfully delivered.
 507
 508             - PotentialDataLoss, which indicates that it cannot be determined
 509               if the entire response body has been delivered.  This only occurs
 510               when making requests to HTTP servers which do not set
 511               I{Content-Length} or a I{Transfer-Encoding} in the response.
 512
 513             - ResponseFailed, which indicates that some bytes from the response
 514               were lost.  The C{reasons} attribute of the exception may provide
 515               more specific indications as to why.
 516         """
 517
 518
 519
 520 UNKNOWN_LENGTH = u"twisted.web.iweb.UNKNOWN_LENGTH"
 521
 522 __all__ = [
 523     "IUsernameDigestHash", "ICredentialFactory", "IRequest",
 524     "IBodyProducer", "IRenderable", "IResponse",
 525
 526     "UNKNOWN_LENGTH"]