xp-framework/rfc — Issue #177: The web
Author: thekid
Created: 2011-10-17 16:03:16+00:00
State: open
Labels: draft, framework

Scope of Change
====
A new package named "web" will be created. It will supersede the scriptlet
and webservices packages and will provide a revamped scriptlet and service
APIs including xp-framework/rfc #61 and xp-framework/rfc #78.

Rationale
====
The scriptlet and webservices APIs have come of age, are fragile, hardly
testable and often geared towards the Apache webserver environment.

Functionality
====
The new APIs...

* ...must be easily testable by unittests
* ...must run in any webserver environment, including the XP server
* ...must support easy development
* ...must provide a secure and stable production environment
* ...should adhere to the "convention over configuration" principle
* ...should integrate well with existing APIs

Package structure
----

```
web # Top-level package
|- auth # Authentication
|- env # Environment (Production, Development, ...)
|- intf # Server Interfaces (Apache, CGI, ...)
|- services # Web services
| |- soap
| |- uddi
| |- json
| |- xmlrpc
| `- wddx
|- impl # Scriptlet implementations
`- model # Revamped scriptlet API
|- view
| `- xsl
|- routing
`- facade
|- dataset
`- remote

```

Top-level package "web"
----
This package contains the fundamentals for the web APIs:
* Request / Response interfaces
* Filters
* Dispatchers
* Sessioning
* The Scriptlet class

Package "web.auth"
----
Contains the authentication and authorization classes used for all web
APIs.

Package "web.env"
----
Encapsulates different environments:
* Production
* Development
* Staging
* ...

The development environment will reveal complete stacktraces, for example,
while the production environment will not show them to prevent information
disclosure.

Package "web.intf"
----
Interfaces with the so-called PHP "SAPI"s:
* PHP Apache Module
* CGI
* FastCGI
* ...

Package "web.services"
----
Contains the classes supporting web services accessed via HTTP. Its subpackages
implement the different payload serialization formats.

Package "web.impl"
----
Different scriptlet implementations:
* Download
* Export
* ...

Package "web.model"
----
The revamped "scriptlet API" (in quotation marks because scriptlets today
are usually referred to as that, meaning the "state / handler / wrapper"
engine implemented in scriptlet.xml.workflow).

Overview:

* The state / handler / wrapper part of the old API will stay.
* The view engines will be exchangeable but will default to XSL
* The URLs should be short and bookmarkable
* The session should be transported by cookie if possible

URL Conventions
----
As the entry point file should exist in xp-tools to avoid boilerplate
code, we need /(.*) to map to it.

Exceptions:

```
/static : Files inside "document root", e.g. CSS, JavaScript, images
/favicon.ico : Icon to be used inside browser's favorites menu / URL bar

```

Sample apache configuration:

```
RewriteEngine on
RewriteRule !(static|xp-bin|favicon.ico) /xp-bin/index.php
[PT,E=USE_XP:"/path/to/xp/:/path/to/extra/lib/"]

Alias /xp-bin /home/thekid/devel/xp/trunk/tools/web
Alias /static/common /var/www/htdocs
Alias /static /home/thekid/www/htdocs
DocumentRoot /home/thekid/www/htdocs/

```

Security considerations
====
None.

Speed impact
====
None.

Dependencies
====
This RFC groups the following others:

* xp-framework/rfc #61 - No access on raw server environment variables
* xp-framework/rfc #78 - New scriptlet API
* xp-framework/rfc #146 - Unicode
* xp-framework/rfc #161 - Scriptlet authenticator
* xp-framework/rfc #154 - Unify scriptlet environment
* xp-framework/rfc #166 - XP runners

Related documents
====
None.