$Cambridge: hermes/src/prayer/docs/README,v 1.3 2008/09/16 09:59:56 dpc22 Exp $

Licence and Distribution
========================

See LICENSE and NOTICE in the docs directory.

Installation
============

See INSTALL in the docs directory.

Mailing lists
=============

  https://lists.cam.ac.uk/mailman/listinfo/prayer-announce
  https://lists.cam.ac.uk/mailman/listinfo/prayer-users

Welcome to Prayer
=================

Prayer is (yet another) Webmail interface for IMAP servers. Please look at
the "FEATURES" file in the docs directory if you want more information.

It exists because we weren't terribly happy about the characteristics of
existing Webmail interfaces: in particular scalibility problems with common
open source Webmail packages and the lack of flexibility that commercial
packages would give us.  This doesn't mean that Prayer is better than or
trying to compete with existing Webmail packages. It just means that Prayer
is better suited to our particular environment. We are releasing the code
into the public domain in case others feel the same way.

Prayer is a low level HTTP to IMAP gateway written from scratch in C. It is
not built on top of Apache or any of the standard scripting languages. This
is rather unusual. However, a dedicated Webmail gateway system is a very
specialised Web server: the Web server component less than 10% of the code.

Prayer maintains a great deal of internal state for each logged in user:
far more than most interactive Web applications. It works hard to minimise
the load induced by each login session by using persistent connections to
the IMAP server.  In fact Prayer uses anywhere up to five persistent IMAP
connections for a single logged in user: a permanent inbox stream (which
doubles to check user preferences and for postponed messages when a user
first logs in), plus optional extra streams for an additional live mail
folder plus user preferences, mail folder transfer and postponed-msgs as
they are required.  There is also an internal directory cache to factor out
round trips to the IMAP server each time that a directory is listed.

Prayer also tries quite hard to cache HTTP/1.0 and 1.1 connections to the
user-agent to remove the overhead associated with starting up fresh
connections, especially SSL connections.

Why "Prayer"?
=============

Malcolm Beattie, formerly of Oxford University Computing Services released
a Webmail package named WING (http://users.ox.ac.uk/~mbeattie/wing/) early
in 1999. It was unusual at the time in that it used persistent IMAP
connections and it was written using Apache mod_perl rather than mod_php.

We came to the conclusion that the WING code that was available to us in
1999 and 2000 was not sufficient mature to use for our own Webmail system.
Consequently (and with some reluctance) we decided to start writing our own
package. Prayer was the in house development name for this package, a
simple play on words to acknowledge the strong influence that WING had over
Prayer development, especially in the early days. But at the end of the
day, everything needs a name.

Acknowledgements
================

Espen Koht (a computer officer at the University of Cambridge) gave some
very useful feedback on user interface design during the development
process. The SSL session cache has been adapted from code used by the Cyrus
IMAP server (See NOTICE in the "docs" directory).

The Prayer design and early user interface was strongly influenced by WING
as explained in the previous section. Two other packages which have more
recently influenced the design are:

Postman:  ftp://ftp.uv.es/pub/unix/postman/postman.html

  An Apache CGI plugin written in C++ which uses a persistent connection to
  the IMAP server. This is probably what I would be using today if we
  hadn't got a long way into the development process when Postman was
  released.

sqwebmail: http://www.inter7.com/sqwebmail/

  A standalone Webmail gateway for maildir format mailfolders and the
  Courier IMAP server. I haven't looked in great detail at this package
  however the discussion regarding sanitation of text/HTML seems extremely
  sensible and was the starting point for what I have implemented in Prayer.

We have also looked at the popular Webmail interfaces IMP and Squirrelmail
from time to time.

Authors:
========

David Carter <dpc22@cam.ac.uk>
  - Design and implementation.

Stella Page <sp253@cam.ac.uk>
  - Initial Webmail evaluation. Help Text.

Comments / Bug-reports:
  mail-support@ucs.cam.ac.uk

Software Download
=================

ftp://ftp.csx.cam.ac.uk/pub/software/email/prayer/
