root/trunk/diva/http.py

# -*- coding: utf-8 -*-
#
# Copyright (C) 2007-2008 Christopher Lenz
# All rights reserved.
#
# This software is licensed as described in the file COPYING, which
# you should have received as part of this distribution.

"""Various objects and functions for working with HTTP exchanges."""

from calendar import timegm
from datetime import datetime, timedelta
from email.Utils import formatdate
import logging

from diva import app
from diva.core import register_filter
from diva.util import decorator
from webob.exc import status_map

__all__ = ['abort', 'allow', 'caching', 'match']
__docformat__ = 'restructuredtext en'

log = logging.getLogger('diva.http')


def abort(status, message='', headers=None):
    """Aborts the request processing immediately by raising an HTTP exception
    corresponding to the specified status code.
    
    >>> abort(404)
    Traceback (most recent call last):
      ...
    HTTPNotFound: 404 Not Found
    Content-Type: text/html; charset=UTF-8
    Content-Length: 0
    <BLANKLINE>
    <BLANKLINE>
    
    >>> abort(301, headers=[('Location', 'http://example.org/')])
    Traceback (most recent call last):
      ...
    HTTPMovedPermanently: 301 Moved Permanently
    Content-Type: text/html; charset=UTF-8
    Content-Length: 0
    Location: http://example.org/
    <BLANKLINE>
    <BLANKLINE>
    
    :param status: the HTTP status code
    :param message: an optional message to be displayed to the user (for example
                    on the error page)
    :param headers: a list of ``(name, value)`` tuples that define any headers
                    that should be included with the response
    """
    log.debug('Abort with status %d (%r)', status, message)
    raise status_map[status](headers=headers, detail=message).exception


def allow(*methods):
    """Decorator for request handlers that handle only requests using the
    specified methods.

    Requests using a method not in the allowed list result in a ``405 Method
    Not Allowed`` error response.

    Note that allowing ``GET`` implies allowing ``HEAD``.

    :param methods: the allowed request methods as strings
    """
    methods = [m.upper() for m in methods]
    if 'GET' in methods and 'HEAD' not in methods:
        methods.append('HEAD')
    def decorate(func):
        @decorator(func)
        def wrapper(*args, **kwargs):
            __traceback_hide__ = True
            if app.ctxt.request.method.upper() not in methods:
                abort(405, headers=[('Allow', ','.join(methods))])
            return func(*args, **kwargs)
        return wrapper
    return decorate


def _add_caching_headers(response, max_age=None, vary_on=None, **options):
    status = response.status_int
    if status < 200 or status >= 300:
        # Caching headers only for success status codes
        return

    if max_age is not None and not isinstance(max_age, timedelta):
        max_age = timedelta(0, max_age)

    headers = response.headers
    if 'Cache-Control' not in headers:
        params = []
        for name, value in options.items():
            name = name.replace('_', '-')
            if value is True:
                params.append(name)
        if max_age is not None:
            params.append('max-age=%d' % (
                max_age.seconds + max_age.days * 86400
            ))
        if params:
            headers['Cache-Control'] = '; '.join(params)

    if max_age is not None and 'Expires' not in headers:
        expires = datetime.utcnow() + max_age
        headers['Expires'] = expires.strftime('%a, %d %b %Y %H:%M:%S GMT')

    if vary_on and 'Vary' not in headers:
        headers['Vary'] = ','.join(vary_on)


def caching(max_age=None, vary_on=None, **options):
    """Decorator that allows controlling HTTP headers related to caching.
    
    :param max_age: the maximum number of seconds the output should be cached
    :param vary_on: a list of HTTP header names that should be taken into
                    account by cache
    :keyword options: any additional keyword arguments are added to the
                      "Cache-Control" header of the response if they have a
                      truth value; for example, ``must_revalidate=1`` would add
                      the "must-revalidate" flag to the header
    """
    def decorate(func):
        @decorator(func)
        def wrapper(*args, **kwargs):
            __traceback_hide__ = True
            retval = func(*args, **kwargs)
            _add_caching_headers(app.ctxt.response, max_age=max_age,
                                 vary_on=vary_on, **options)
            return retval
        return wrapper
    return decorate


def match(etag=None, last_modified=None):
    """Checks the current request for conditional GET semantics based on the
    "If-Modified-Since" and/or "If-None-Match" headers.
    
    If the request includes one of those headers, and their value matches the
    given parameters, a "204 Not Modified" response is sent. Otherwise, the
    headers "Last-Modified" and/or "ETag" are headers are added to the response.
    
    :param etag: the entity tag value
    :param last_modified: the last modification date (either as a ``datetime``
                          object or as a numeric timestamp)
    """
    request = app.ctxt.request
    response = app.ctxt.response
    if response.status_int < 200 or response.status_int >= 300:
        # Only do the matching for responses with a HTTP success codes
        return

    if etag is not None:
        response.etag = str('"%s"' % etag) # FIXME: WebOb #251
        if request.method in ('PUT', 'DELETE') and request.if_match \
                and etag not in request.if_match:
            log.debug('Etag %r did not match %r', etag, request.if_match)
            abort(412)
        elif request.method in ('GET', 'HEAD') and request.if_none_match \
                and etag in request.if_none_match:
            log.debug('Etag %r matched %r', etag, request.if_none_match)
            abort(304)

    if last_modified is not None:
        response.last_modified = last_modified
        if request.method in ('PUT', 'DELETE') \
                and request.if_unmodified_since \
                and response.last_modified != request.if_unmodified_since:
            log.debug('Modification time "%s" did not match "%s"',
                      response.last_modified, request.if_unmodified_since)
            abort(412)
        elif request.method in ('GET', 'HEAD') and request.if_modified_since \
                and response.last_modified == request.if_modified_since:
            log.debug('Modification time "%s" matched "%s"',
                      response.last_modified, request.if_modified_since)
            abort(304)


@register_filter('caching')
def caching_filter(request, response, chain):
    """Request filter that adds standard cache disabling headers to responses
    that have no explicit cache control.
    """
    try:
        return chain.next()(request, response, chain)
    finally:
        _add_caching_headers(response, max_age=0)