infrae.wsgi 2.2.1

WSGI support for Zope 2

infrae.wsgi provides a support to run Zope 2 as a WSGI application.

Contents

• Introduction

  • Errors

• Installation

  • Paste Deploy

  • Virtual Hosting

• Testing

  • Functional Testing

• Changes

  • 2.2.1 (2013-10-08)

  • 2.2 (2013-06-22)

  • 2.1 (2012-12-10)

  • 2.0.1 (2012-09-19)

  • 2.0 (2012-09-04)

  • 1.3 (2011-07-27)

  • 1.2 (2011-02-02)

  • 1.1 (2010-10-07)

  • 1.0 (2010-07-15)

Introduction

It basically does the same work than:

• repoze.zope2,

• Zope 2 new builtin WSGI publisher.

Except than:

• It work with real Zope 2 applications and no monkey-patches,

• It pay specially attention to properly implement streaming. You can use your ZODB connection while streaming, (either with the .write method of request, or returning an IResult or an IStreamIterator iterator). ConflictError generate a final error if they happens during a streaming operation, not re-sending things again on the same HTTP connection,

• All ConflictError are properly managed.

• All those cases are tested.

It does not:

• Provide Zope 2 as a collection of WSGI middlewares, as Zope 2 paradigm / code base is not good for it,

• Do all fancy request body changes that old Zope 2 publisher does, as nobody use it anymore since a very long time.

Errors

Error messages are handled a bit differently than in traditional Zope 2, in order to make things simpler.

They are views on errors (called error.html), and wrapped in acquisition around the context where they happened:

from five import grok

class CorpError(Exception):
    """Custom corporate error.
    """

class CorpErrorMessage(grok.View):
    grok.context(CorpError)
    grok.name('error.html')

    def render(self):
        # aq_parent(self) is where the error happened
        return u'I Failed: %s' % str(self.error.args)

Errors are logged with useful information:

• Which is the URL triggering this error,

• The user-agent,

• The referent,

• The logged in username,

• On which object, its physical path and meta_type if possible.

The error log can be accessible online via /errorlog.html on any Zope 2 content.

Errors can also be sent to a Sentry service (see Paste Deploy section).

The error log ignores certain errors by default: NotFound, Redirect, Unauthorized, Forbidden, BadRequest, BrokenReferenceError. The errlog.html page has a form configure some (or all) of these errors to not be ignored. This is not a persistent setting and is forgotten on restart.

Installation

infrae.wsgi has been and deployed with Paste Deploy, mod_wsgi and nginx. It correctly respect the WSGI specification and should work with any WSGI server.

Paste Deploy

The application is available with the entry point infrae.wsgi#zope2.

It expect an option variable called zope_conf that point to the Zope 2 configuration file.

The option debug_mode can as well be specified, to run Zope in debug mode. In debug mode, error pages will not be rendered by Zope and the errors will propagate in the WSGI stack. This behavior will let you debug errors with specialized middlewares.

To disable the error propagation in debug mode, the option debug_exceptions can be set to off.

The option zope_workers can be used to specify the maximum of threads Zope should allow to process requests at the same time (default to 4). This can be usefull if you wish to allow more threads in your wsgi environment, in case you have middlewares or other applications that intercept the requests and support more threads than Zope does.

The option show_errors accepts a comma-separated list of errors which will not be ignored. This overrides the default list of ignored errors (see the Errors section, above)

The option ignore_errors accepts a comma-separated list of errors which will be ignored. This overrides the default list of ignored errors too.

The configuration accepts options for Raven (Sentry’s client):

raven.dsn = http://public:[e-mail]/1
raven.include_paths = my.package, my.other.package
raven.exclude_paths = my.package.crud

Those options requires Raven to be installed.

Virtual Hosting

You can add two headers in your proxy in order to control the virtual hosting:

• X-VHM-URL: That would the complete URL of your site, at which you want to see your Zope application, like http://www.mysite.com/application.

• X-VHM-Path: That would be an optional path to the Zope folder you see at the given URL instead of the Zope root, lile /my/folder.

Testing

A test request TestRequest can be imported from infrae.wsgi.testing. It behaves exactly like a request used by Zope. It takes the following parameters when creating it:

application

WSGI application to use with the request.

layers

Zope layers to apply on the request.

url

URL used with the request.

method

HTTP method used with the request.

headers

HTTP headers that where sent with the request.

debug

Should the request ran with the debug mode.

form

Form data associated with the request.

Functional Testing

A layer inheriting of infrae.testing Zope2Layer layer called ZopeBrowserLayer let you write functional tests.

It provides both an http function and a ZopeBrowser class (like the one provided by zope.testbrowser) that you can use, and that will connect to the tested application using the WSGI support provided by this package.

This will let you do functional testing, and things will work exactly like in your browser, as the requests will be processed the same way than they are in real life (which is not really the case with the Testing module of Zope 2).

You will be actually able to test applications that do use streaming:

import unittest

from infrae.wsgi.testing import ZopeBrowser, ZopeBrowserLayer
import corp.testpackage


class CorpTestCase(unittest.TestCase):
   layer = BrowserLayer(corp.testpackage)

   def setUp(self):
       self.root = self.layer.get_application()
       # Create some test content

   def test_feature(self):
       browser = ZopeBrowser()
       browser.open('http://localhost/somepage')
       self.assertEqual(browser.status, 200)
       ...

This feature is provided by wsgi_intercept. It is available only if wsgi_intercept is included in the environment.

Changes

2.2.1 (2013-10-08)

• Fix an UnicodeError in error message logging facilities.

2.2 (2013-06-22)

• Improve logging with raven: the message used to contain the annotated traceback, that was too long.

• Fix HTTP status code 204 that was set even when a Content-Length was defined.

• Fixed paster startup crash when multiple mount points don’t exists yet.

• wsgi_intercept support is now optional for testing. There is a simple test layer BrowserLayer that provides a test WSGI application without the feature. The layers and browser with the support have been prefixed with Zope. In order to enable this feature you must depend on the feature [intercept].

2.1 (2012-12-10)

• In paster, the propagations of errors in the stack can be disabled with debug_exceptions, if you set it to off. This option only has an effect if debug_mode is activated.

• In paster, the list of default errors that are ignored in the log can be customized by both options show_errors and ignore_errors.

• Add a plugin to log errors in Sentry (this requires raven to be installed).

2.0.1 (2012-09-19)

• Add an optional WSGI middleware that display the same debug information than debugzope.html does.

• Add an event that is triggered before an error page is rendered.

• If an error view implements IBrowserPublisher, call browserDefault in order to retrieve the real view to render.

2.0 (2012-09-04)

• Refactor the virtual hosting, traversing and authentication code from Zope 2 BaseRequest into three different pieces of code, that can be customized. This makes possible to change how authentication, or virtual hosting is done.

• Add a TestRequest that can be used in tests. This is the same thing than a zope.publisher test request, except it is based on a Zope 2 request, and have all the same behavior than a Zope 2 request.

• A configurable semaphore have been added to limit the number of concurrent threads that can access the Zope 2 application. This is usefull when you have middleware that handles requests on their own, so they are not limited to the restriction imposed by Zope 2 on the number of threads.

1.3 (2011-07-27)

• Improve logging.

• BadRequest and Forbidden exceptions are now ignored by default in the logs.

• Fix a bug the original CONTENT_LENGTH header is empty.

• When an error happens on an IBrowserPage, use the page’s context when handling the error (to prevent falling back to the nearest Site)

1.2 (2011-02-02)

• Add a view debugzope.html that display a dump of the server threads. You need to be manager to access it.

• You can from the errorlog.html configure the error you wish to ignore (not log). This is a non persistent setting.

• Handle buggy PAS unauthorized plugins, by catching any error, and logging them. In case of problem, a basic 401 response is sent back.

• Add the ZPublisher insertBase functionality: if a base is set by the request, and we render HTML, with an HEAD tag and no BASE tag, insert a BASE tag with the value provided by the request. This fix broken ZMI screens.

1.1 (2010-10-07)

• Fix a bug where Content-Length is not set and cannot be set.

• Correctly encode payload when needed before sending it (if it was a unicode string).

• Error codes less when 500 triggers a commit now, this let you support login pages that uses a Zope session ID.

• Add some hooks in the testing code to be more extensible (used for infrae.testbrowser).

1.0 (2010-07-15)

• Initial release.