| Author: | Kore Nordmann, Tobias Schlitt |
|---|---|
| Revision: | $Rev$ |
| Date: | $Date$ |
| Status: | Draft |
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.
It is currently not planned to also offer a WebDAV client component.
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).
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.
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.
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.
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:
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:
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.
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.
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.
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();
| Author: | Kore Nordmann, Tobias Schlitt |
|---|---|
| Revision: | $Rev$ |
| Date: | $Date$ |
| Status: | Draft |
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.
It is currently not planned to also offer a WebDAV client component.
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).
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.
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.
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.
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:
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:
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.
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.
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.
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();