eZ component: Webdav, Design, 1.0
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

:Author: Kore Nordmann, Tobias Schlitt
:Revision: $Rev: 11456 $
:Date: $Date: 2010-03-22 13:44:22 +0000 (Mon, 22 Mar 2010) $
:Status: Draft

.. contents::

Scope
=====

The scope of this document is to describe the initial design of a component
that provides a WebDAV server, which works with all major other implementations
of the WebDAV_ protocol.

.. _WebDAV: http://en.wikipedia.org/wiki/WebDAV

It is currently not planned to also offer a WebDAV client component.

Design overview
===============

Because of the variaty of buggy and incomplete implementations of WebDAV, this
component will provide an abstraction to suite the different needs. Beside
that, an abstract interface to the backend will be provided.

The main class of this component will provide a fully `RFC 2518`_ compliant
implementation of a WebDAV_ server. An instance of this class retrieves an
instance of a handler class, which takes care for performing the requested
operations on a backend (for example the filesystem).

.. _`RFC 2518`: http://tools.ietf.org/html/rfc2518

Additionally, a collection of classes, which inherit the main class will be
provided. Each of this classes will provide a compatibility layer on top of the
RFC implementation, which works correctly with one or more "buggy" WebDAV
clients. A factory pattern implementation will be provided, which takes
automatically care of creating the correct server instance for a client.

Tiers
=====

The component is basically devided into 3 tiers: The top tier, being
represented by the main server class. An instance of this class is responsible
to dispatch a received request to a correct transport handler, which is capable
of parsing the request.

The transport handler level is the second tier. Classes in this tier are
responsible to parse an incoming request and extract all relevant information
to generate a response for it into a struct object. These struct object is then
passed back to the server object.

Based on the request struct object, the server checks the capabilities of its
third tier, the used backend handler. If the handler object provides all
necessary capabilities to generate a response, it is called to do so. If the
server class can perform emulation of not available capabilities and rely on
different features of the backend. In case there is no way, the backend can
handle the request, the server class will indicate that with an error
response.

The way back flows through the 3 tiers back again: The backend handler
generates a response object, which is passed back to the main server object,
which makes the active transport handler encode the response and sends it back
to the client.

Classes
=======

ezcWebdavServer
---------------

The ezcWebdavServer class is the main class of the package. It has to be
instantiated to create a server instance and provides a method to get the
server up and running. An object of this class takes the main controll over
serving the webdav service.

Among the configuration of the server instance there must be: A backend handler
object, which will be used to serve the received WebDAV requests. A fitting
configuration for the backend handler. A collection of transport handlers which
can be used to parse incoming requests. General configuration on the bevahiour
of the server instance (like locking and stuff).

The backend handler object must extend the base class ezcWebdavBackendHandler
and must indicate to the main server, which capabilities it provides. The
server class can potentially emulate certain capabilities, if the handler does
not provide it. An example here is locking, which can be either performed by
the handler itself or the main server class.

Such emulation functionality could possibly be extracted to a third category of
classes, which is only loaded by the main server object on-demand.

All configured transport handlers must implement the interface
ezcWebdavTransportHandler, which defines the necessary methods.

The standard webdav server contains a list of transport handlers associated
with regular expressions which should match the client name to be used. As a
fallback the standards compliant transport handler will be used.

Special implementation added by the user will be add on top of the list, to be
used at highest priority.

ezcWebdavBackend
----------------

All backend handlers for the Webdav component must extends this abstract base
class and implement its abstract methods for very basic WebDAV serving. The
operations defined for every backend handler to be mandatory are:

- head()
- get()
- propFind()
- propFetch()

All other WebDAV operations are optional to be implemented by a backend handler
and are defined by the handler itself. The additional basic capabilities of
backend handlers are indicated by implementing interfaces for the support
additional request methods, like put, change, etc.

Additional features, like encryption support will be indicated by returning a
bitmask of supported features by the backend handler.

The logical groups of capabilities are:

Put
  The put capability indicates, that a handler is capable of handling file
  uploads via HTTP-PUT method.
Change
  This sub class of WebDAV operations defines delete, copy and move operations to
  be supported by the handler class.
Make collection
  The creation of new collections also makes up a capability unit and can
  optionally be implemented.
Lock
  If the hander provides locking facilities on its own, the main server object
  must not take care about that.
GZIP-Compress
  Handlers implementing this facility can deal with GZIP and bzip2 based
  compression.

If a handler does not support a certain facility and the main server object is
not capable of emulating it, the server will respond using a "501 Not
Implemented" server error.

ezcWebdavTransport
------------------

A class implementing this interface is capable of parsing a raw HTTP request
into a struct extending ezcWebdavRequest and generating the HTTP response out
of the ezcWebdavResponse struct. One transport handler is usually built to
handle the communication with a certain set of specific client
implementations.

A transport handler class will be able to parse the incoming HTTP request data
into a struct identifying a certain type of request and containg all necessary
and unified data, so that a backend handler can repsond to it.

The backend handler will then create a corresponding response object, which
will be encoded back into HTTP data by the transport handler and send to the
client by the server.

Each request type will come with its own struct classes to represent request
and response data for the request. Beside the structured HTTP data, the structs
can contain any additional information that must be transferred between server,
transport handler and backend handler.

All struct classes representing either a request of response of the server will
extend the abstract base classes ezcWebdavRequest and ezcWebdavResponse.

An example of this structure is: ezcWebdavGetRequest and ezcWebdavGetResponse

These 2 classes will be used to serve GET requests. Beside the usual request
information - like URI, date and headers - the request object will contain
information about partial GET mechanisms to use and what else is important.
The backend handler will return an instance of ezcWebdavGetResponse if the
request was handled correctly, or a corresponding ezcWebdavErrorResponse
object, if the request failed.

The main server instance will know about available clients and will have a
regular expression for each of them, to identify the clients it communicates
to by matching the regualr expression against the client name provided in the
HTTP headers.

ezcWebdavPathFactory
--------------------

This class is meant to calculate the path of the requested item from the
backend based on the given path by the webdav client. The resulting path
string is absolute to the root of the backend repository.

This class is necessary to calculate the correct path when a server uses
rewrite rules for mapping directories to one or more webdav implementations.
The basic class uses pathinfo to parse the requested file / collection.

Request:   /path/to/webdav.php/path/to/file
Result:    /path/to/file

You may want to provide custome implementations for different mappings so that
rewrite could be used by the webserver to access files.

Request:   /images/path/to/file
Rewritten: /path/to/dav_images.php/path/to/file
Result:    /path/to/file

The factory class is necessary, because the paths contained in the request
body will match the same scheme like the original request path, but not be
rewritten by the webserver, so that the user may extend the path factory to
fit his own purposes.

Example code
============

The following snippet shows the API calls necessary to get a WebDAV server up
and running.

::

	<?php

	$server = new ezcWebdavServer();

	// Server data using file backend with data in "path/"
	$server->backend = new ezcWebdavBackendFile( '/path' );

    // Optionally register aditional transport handlers
	//
	// This step is only required, when a user wants to provide own
	// implementations for special clients.
	$server->registerTransportHandler(
		// Regular expression to match client name
		'(Microsoft.*Webdav\s+XP)i',
		// Class name of transport handler, extending ezcWebdavTransportHandler
		'ezcWebdavMicrosoftTransport'
	);
	$server->registerTransportHandler(
		// Regular expression to match client name
		'(.*Firefox.*)i',
		// Class name of transport handler, extending ezcWebdavTransportHandler
		'ezcWebdavMozillaTransport'
	);

	// Serve requests
	$server->handle();



..
   Local Variables:
   mode: rst
   fill-column: 79
   End: 
   vim: et syn=rst tw=79
