++++++++++++++++++++++++++
Railroad Integration Guide
++++++++++++++++++++++++++
------------------------------------------------
How to integrate a Railroad server with your CMS
------------------------------------------------

:Author: Guido Goldstein
:Email: gst@infrae.com
:License: BSD, see LICENSE.txt


1. Requirements
===============

1.1 Server side
---------------

On the server side a running Railroad server is required; the setup is
described in the install document.


1.2 Client (CMS) side
---------------------

1.2.1 Silva integration
_______________________

**Outdated! There will be a new Silva extension shortly!**

The follwing software in addition to Zope and Silva is needed to
implement the client side of Railroad:

1. the pydavclient package
2. libxml2 with Python bindings (for 1.)
3. SilvaExternalSources extension
4. SilvaRailroad extension

The Silva extensions should be installed in the ``Products`` directory
of your Zope.

libxml2 and it's Python bindings must be installed for the Python
version your Zope is using!

The `pydavclient` package can be installed through its ``setup.py``
script, which will install a package ``dav`` in the ``site-packages``
directory of the used Python version. Administrator rights might be
needed for this step!

1.2.2 Plone integration
_______________________

Based on the brand new basic Zope objects, there is a basic Plone
integration available in a package called PloneRailroad.


2. Form based upload
====================

The form based upload is used to send a file to the Railroad server
via a POST request. The upload is not going through the CMS. To
achieve this, a form which points to the upload URL of the repository
is needed.

This is a core service which is found under
`prefix`/service/formupload/ on the Railroad server.


2.1 Required fields
-------------------

The following form fields must be present -- and filled in correctly
-- for a successful upload:

**1. field_file**
   The field for the uploaded file. This is filled in by the browser when
   the user chooses a file to upload.

**2. ok_url**
   The url to redirect to when everything went fine.
   This has to be set by the CMS to an URL to which the upload process will
   redirect the user in case the upload succeeded.
   Two paramters will be appended to this URL: ``url`` and ``errormsg``. The
   latter holds a textual message to be displayed to the user, the ``url``
   parameter holds the full URL of the created resource.

**3. error_url**
   The url to redirect to when an error occured.
   This has to be set by the CMS to an URL to which the upload process will
   redirect the user in case the upload failed.
   One parameter will be appended to this URL:``errormsg``. It holds a textual
   message to be displayed to the user.

**4. link_url**
   Set when this upload is ment to be an update, else empty. It holds
   the full URL of the Railroad resource the CMS object refers to. If
   the basename and the mime-type of this URL are matching the
   basename and mime-type of field_file, the upload is considered to
   be an update. Otherwise the upload will be rejected.

2.2 Use with authorization
--------------------------

If authorization is enabled, the following form fields are required in
addition to the above mentioned fields:

**1. object_id**
   The id of the CMS side object referring to the resource -- or will
   be referring to in case this is a first time upload. This means
   that the CMS side object has to exist when the upload is initiated!

**2. client_id**
   The id of the client CMS which owns the referring object and the
   uploading user is registered with. Usually this field contains the
   name of the client as given by the Railroad administrator during
   registration of the client.

**3. user**
   The name of the user as known to the CMS.

**4. passwd**
   The password of the user as known to the CMS. This **is** a
   security hole when HTTPS is not used!



3. WebDAV upload
================

Later...


4. Authorization
================

4.1 How does the authorization work
-----------------------------------

The authorization in Railroad is based on a call-back mechanism which
uses the authorization scheme of the client CMS owning a particular
resource. This technique avoids the hassles of implementing a
authorization scheme for Railroad itself (which would be difficult
because of the wide variety of CMSes around).

4.1.1 Registration
__________________

Every CMS has to be registered before it can use a Railroad
repository.

This is the data that needs to be collected:

**1. Client Id**
   The identification (aka name) for the CMS.

**2. Admin EMail**
   The email address of the administrator of the CMS.

**3. Authorization URL**
   The URL `called` by the Railroad system to trigger the
   authorization process in the CMS.

**4. Authorization domain**
   The domain for which the `Basic Auth` header should be set.

This data is stored in the database and used heavily during the
authorization process -- which means on every request to a resource on the
Railroad server!

More in this in the installation document chapter 3.


4.1.2 Ownership
_______________

The Railroad authorization code keeps track of the ownership of a
resource, which is defined in to levels: the first level ownership is
the owning CMS, the second level ownership is a user on that CMS.

The Railroad authorization code keeps track of the CMS from which a
resource was initially uploaded. This CMS is called the `owning CMS`.

The second level of ownership is a user on the owning CMS. The `owning
user` is the user who did the initial upload of the resource.


4.2 The callback mechanism
--------------------------

The `call` to the authorization URL is a ``GET`` request with the
following parameters:

**1. id**
   The object id of the resource (the id by which the referring
   object in the CMS is identified).

**2. method**
   The request method (GET, PROPFIND... all HTTP/1.1 and WebDAV methods).

If the request is answered with a response status of 200, the
requested action on the resource is permitted, otherwise the action
will be denied (with a 401 response code, which will give the user
opportunity to choose a different user/password combination).

If authorization is required for the resource is question, the
Railroad server will supply user and password using the `Basic
Authorization` scheme of HTTP.

Only `Basic Auth` is and will be supported.

For a in depth explanation of the problems with authorization over
multiple domains see the `authorization.txt` document.

4.2 Implementing the CMS side
-----------------------------

On the CMS side only little work is needed to integrate a Railroad
server with authentcation/authorization.

As stated above, for every request to a resource on the Railroad
server a request to the owning CMS is made asking for authorization. 
So the CMS has to provide an URL which the Railroad server can query
(using a simple GET request, see 4.1.2).

The ``id`` parameter to the request denotes the object in the CMS that
refers to the resource in the Railroad repository. The CMS should take
the ``method`` and check if it is allowed for the given object. If so,
the CMS has to return a response with its status set to 200 and no
body. If the given method is not allowed for the object in question
the CMS has to return a response with status set greater or equal 400
and no body (usually 401).



5. Search
=========

Later...





..
   Local Variables:
   mode: rst
   indent-tabs-mode: nil
   sentence-end-double-space: nil
   fill-column: 70
   End:
