# HG changeset patch # User paulb # Date 1113001773 0 # Node ID 4316c11b58abca68a84dfda4e46da9b1f26dfe40 # Parent fb79a0a0bd3a51e1761d502e5e6785782ed42528 [project @ 2005-04-08 23:09:33 by paulb] Converted documents to XHTML. Removed old plain text documents, adding various XHTML replacements. Fixed path support information which was out-of-date or missing in the old PATH.txt document (concerning Zope and WSGI respectively). diff -r fb79a0a0bd3a -r 4316c11b58ab docs/AUTH.txt --- a/docs/AUTH.txt Fri Apr 08 22:33:56 2005 +0000 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,82 +0,0 @@ -Authentication in WebStack --------------------------- - -There are two principal methods of introducing authentication and applying -access control to WebStack applications: - - * Use of authenticators, where the "remote user" is set in the - server/framework environment and tested in the application. - - * Use of the WebStack.Resources.LoginRedirect and WebStack.Resources.Login - modules. - -Application-wide Authenticators -------------------------------- - -First, set up the usage of such authentication mechanisms in the -server/framework environment. For example, introduce Auth directives in your -Apache configuration (see docs/ModPython/NOTES.txt) or protected folders in -your Zope instance (see docs/Zope/NOTES.txt). - -Then, define an authenticator when deploying your application; this -authenticator will respond with a decision when prompted by the server or -underlying framework, either allowing or denying access for the user whose -identity has been presented to the server/framework. - -In this mechanism, authenticators rely on authentication information from the -server/framework and have a "global" effect on access to the application. - -LoginRedirect and Login Modules -------------------------------- - -The LoginRedirect and Login modules provide a single sign-on environment for -WebStack applications. Unlike the authenticator-only approach, each -application or part of an application utilising this mechanism must be wrapped -inside a LoginRedirectResource object which determines whether a given -transaction contains information identifying the application's user. - -Should sufficient information be present in the transaction, the user is -allowed to access the application and is identified in the normal way (ie. the -Transaction object's get_user method). Otherwise, a redirect occurs to a login -screen provided by a LoginResource object which then presents a login form to -be completed by the user. - -The LoginResource object verifies the identity of the user, testing the -supplied credentials against the credentials database specified in the -deployment of the resource. Upon successful authentication, the user is -redirected back to the application, which should let the user gain access. - -Some server/framework environments do not permit automatic redirection back to -the application, notably Apache/mod_python. In such cases, a success screen is -presented to the user with a link to the application they were attempting to -access. - -In this mechanism, authenticators are employed, but only to verify the -credentials of users when LoginResource or LoginRedirectResource objects are -accessed. - -Anonymous Access ----------------- - -With application-wide authenticators, anonymous access to resources and -applications can be difficult to permit alongside access by specific users, -mostly because servers and frameworks which employ HTTP authentication schemes -do so globally for a given application. - -With the LoginRedirect and Login modules, it is possible to declare a -particular request parameter which must be present in the URL used to access a -particular application for the client to be given anonymous access. -Consequently, anonymous users are then identified specially with a special -username that can also be configured. - -Logout Functions ----------------- - -With application-wide authenticators, a logout function may not be available -if the server/framework has been configured to use HTTP authentication -schemes, since no such function is defined for such schemes. - -With the LoginRedirect and Login modules, it is possible to declare a -particular request parameter which must be present in the URL used to access a -particular application for the client to be logged out. A special logout -confirmation URL may also be configured. diff -r fb79a0a0bd3a -r 4316c11b58ab docs/DEPLOY.txt --- a/docs/DEPLOY.txt Fri Apr 08 22:33:56 2005 +0000 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,29 +0,0 @@ -When deploying an application, it is possible to use a one-shot deploy -function for certain frameworks. The deploy function is called as follows: - -deploy(resource) -deploy(resource, authenticator) # where authenticators are used - -For some frameworks, an address may be specified: - -deploy(resource, address=(host_string, port_integer)) -deploy(resource, authenticator, address=(host_string, port_integer)) - -Framework Address Information ---------- ------------------- - -BaseHTTPRequestHandler Supported -CGI N/A -Twisted Supported (host_string is ignored) -WSGI N/A - -The other frameworks do not support the deploy function due to the way -applications are typically integrated into the various server mechanisms: - -Framework Deployment Details ---------- ------------------ - -JavaServlet Applications are packaged specially -ModPython Applications must expose certain functions -Webware Applications must expose certain classes -Zope Applications must expose certain functions/classes diff -r fb79a0a0bd3a -r 4316c11b58ab docs/PATH.txt --- a/docs/PATH.txt Fri Apr 08 22:33:56 2005 +0000 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,13 +0,0 @@ -Path Semantics in WebStack --------------------------- - - get_path_info - ------------- -BaseHTTPRequestHandler Same as path (correct) -CGI Path beyond resource (correct) -Java Servlet API Path beyond context (correct) -mod_python Path beyond resource (correct) -Twisted Same as path (correct) -Webware <= 0.8.1 Not supported (needs ExtraPathInfo support) -Webware > 0.8.1 Path beyond context (correct) -Zope 2.7.2-0 Same as path (correct) diff -r fb79a0a0bd3a -r 4316c11b58ab docs/anatomy.html --- a/docs/anatomy.html Fri Apr 08 22:33:56 2005 +0000 +++ b/docs/anatomy.html Fri Apr 08 23:09:33 2005 +0000 @@ -1,61 +1,58 @@ - + +
The simplest way to think of a Web application is as just some code -which -gets run every time an HTTP request arrives at a specific network -address and -which produces an HTTP response. Without WebStack, such code often -needs to -be tailored to the software which causes it to be run, but with -WebStack you + +
The simplest way to think of a Web application is as just some code which +gets run every time an HTTP request arrives at a specific network address and +which produces an HTTP response. Without WebStack, such code often needs to +be tailored to the software which causes it to be run, but with WebStack you just need to do this:
Most of the time, you need only to think about the first activity
-(writing
-against the WebStack API).
+
+
Most of the time, you need only to think about the first activity (writing
+against the WebStack API).
class MyResource:-
"This is a resource - something which defines the behaviour of an application."
def respond(self, trans):
[Examine the transaction, decide what the user wants to do.]
[Perform some kind of action with the information supplied.]
[Produce some kind of response which tells the user what happened.]
The parts of the pseudo-code in the above text which aren't valid
-Python
-(ie. the bits in square brackets) will use various WebStack API calls
-to look
-at what the user specified in the request and to send information back
-to the
-user in the response.
+
class MyResource:+ +
"This is a resource - something which defines the behaviour of an application."
def respond(self, trans):
[Examine the transaction, decide what the user wants to do.]
[Perform some kind of action with the information supplied.]
[Produce some kind of response which tells the user what happened.]
The parts of the pseudo-code in the above text which aren't valid Python
+(ie. the bits in square brackets) will use various WebStack API calls to look
+at what the user specified in the request and to send information back to the
+user in the response.
WebStack applications consist of resource classes which contain the
-application code. In the above example, the only thing we need to
-consider is what our code does, not how resource objects are created
-and invoked (that is done in the adapter code). In more complicated
-applications, there may be a need to create our own resource objects
-explicitly, but this is not particularly interesting to think about at
-this point - see "Treating the Path
-Like a Filesystem" for a discussion of multiple resource objects.
+application code. In the above example, the only thing we need to consider is
+what our code does, not how resource objects are created and invoked (that is
+done in the adapter code). In more complicated applications, there may be a
+need to create our own resource objects explicitly, but this is not
+particularly interesting to think about at this point - see "Treating the Path Like a Filesystem" for a
+discussion of multiple resource objects.
When writing an application, we must consider a number of factors -which -have an impact on the code (and other things) that we will need to -provide as + +
When writing an application, we must consider a number of factors which +have an impact on the code (and other things) that we will need to provide as part of the finished product or service.
When deploying an application, it is possible to use a one-shot deploy
+function for certain frameworks. The deploy
function is called
+as follows:
deploy(resource) +deploy(resource, authenticator) # where authenticators are used+ +
For some frameworks, an address may be specified:
+deploy(resource, address=(host_string, port_integer)) +deploy(resource, authenticator, address=(host_string, port_integer))+ +
Framework | +Address Information | +
---|---|
BaseHTTPRequestHandler | +Supported | +
CGI | +Ignored | +
Twisted | +Supported (host_string is ignored) |
+
WSGI | +Ignored | +
The other frameworks do not support the deploy function due to the way +applications are typically integrated into the various server mechanisms:
+ +Framework | +Deployment Details | +
---|---|
JavaServlet | +Applications are packaged specially | +
ModPython | +Applications must expose certain functions | +
Webware | +Applications must expose certain classes | +
Zope | +Applications must expose certain functions/classes | +
This set of documents describes the process of making a Web -application + +
This set of documents describes the process of making a Web application using the WebStack framework.
+First of all, let us assume that the WebStack distribution has been
unpacked and now sits in the WebStack-0.9
directory.
Before we begin, we must make sure that the WebStack package is -available + +
Before we begin, we must make sure that the WebStack package is available
to Python. The easiest way to do this is to change into the
WebStack-0.9
directory and to run the setup.py
script provided with the version of Python you are going to be using
(possibly as a privileged user like root
):
cd WebStack-0.9-
python setup.py install
If you don't want to install WebStack in this way, or if you can't
-do so
-because you don't have root
privileges, you can just make
-sure
+
cd WebStack-0.9+ +
python setup.py install
If you don't want to install WebStack in this way, or if you can't do so
+because you don't have root
privileges, you can just make sure
that the WebStack-0.9
directory sits on the
PYTHONPATH
.
Since many Web applications have complete control over how paths are -interpreted, the form of the path doesn't necessarily have to follow -any -obvious structure as far as users of your application is concerned. -Here's an +interpreted, the form of the path doesn't necessarily have to follow any +obvious structure as far as users of your application is concerned. Here's an example:
/000251923572ax-0015-
However, many would argue that such obscure references, whilst -perfectly -acceptable to machines, would make any application counter-intuitive -and very -difficult to reference. Sometimes, application developers do not want -people + +
However, many would argue that such obscure references, whilst perfectly +acceptable to machines, would make any application counter-intuitive and very +difficult to reference. Sometimes, application developers do not want people "bookmarking" resources or functions within an application, and so such concerns don't matter to them.
diff -r fb79a0a0bd3a -r 4316c11b58ab docs/paths-services.html --- a/docs/paths-services.html Fri Apr 08 22:33:56 2005 +0000 +++ b/docs/paths-services.html Fri Apr 08 23:09:33 2005 +0000 @@ -1,25 +1,27 @@ - + +...but really using it to broadly identify different resources or services. In this approach, we take a path like this...
/tools/viewer+
...and interpret it as being a request for a certain function of the -application. Often, this approach is used because it matches some -aspect of +application. Often, this approach is used because it matches some aspect of how the application is actually organised. Consider this example:
/cgi-bin/script.pl+
This kind of thing generally appears in URLs because of the way the -application concerned has been deployed - CGI programs live in a -particular +application concerned has been deployed - CGI programs live in a particular place and are accessed using a special path "prefix".
diff -r fb79a0a0bd3a -r 4316c11b58ab docs/paths.html --- a/docs/paths.html Fri Apr 08 22:33:56 2005 +0000 +++ b/docs/paths.html Fri Apr 08 23:09:33 2005 +0000 @@ -1,10 +1,11 @@ - - + + + -/folder/application/resourceLet us say that the application was deployed in a Zope server instance inside @@ -86,8 +87,7 @@
There are various differing approaches to the problem of interpreting paths to resources within Web applications, but these can mostly be divided @@ -116,5 +116,53 @@ + +
The following table summarises the support for paths within applications +amongst the supported server environments or frameworks within WebStack:
+ +Framework | +Behaviour/Level of Support | +
---|---|
BaseHTTPRequestHandler | +Same as path (correct) | +
CGI | +Path beyond resource (correct) | +
Java Servlet API | +Path beyond context (correct) | +
mod_python | +Path beyond resource (correct) | +
Twisted | +Same as path (correct) | +
Webware | +<= 0.8.1: Not supported (needs ExtraPathInfo
+ support)+ > 0.8.1: Path beyond context (correct) |
+
WSGI | +Path beyond resource (correct) | +
Zope | +Path beyond resource (correct) | +
Making sure that Web applications are "secure" involves many different +aspects of application design, deployment and administration. This document +covers only the usage of the authentication features of the WebStack API.
+ +There are two principal methods of introducing authentication and applying +access control to WebStack applications:
+WebStack.Resources.LoginRedirect
and
+ WebStack.Resources.Login
modules.First, set up the usage of such authentication mechanisms in the
+server/framework environment. For example, introduce Auth
+directives in your Apache configuration (see
+docs/ModPython/NOTES.txt
) or protected folders in your Zope
+instance (see docs/Zope/NOTES.txt
).
Then, define an authenticator when deploying your application; this +authenticator will respond with a decision when prompted by the server or +underlying framework, either allowing or denying access for the user whose +identity has been presented to the server/framework.
+ +In this mechanism, authenticators rely on authentication information from +the server/framework and have a "global" effect on access to the +application.
+ +The LoginRedirect
and Login
modules provide a
+"single sign-on" environment for WebStack applications. Unlike the
+authenticator-only approach, each application or part of an application
+utilising this mechanism must be wrapped inside a
+LoginRedirectResource
object which determines whether a given
+transaction contains information identifying the application's user.
Should sufficient information be present in the transaction, the user is
+allowed to access the application and is identified in the normal way (ie.
+the get_user
method on the transaction object). Otherwise, a
+redirect occurs to a login screen provided by a LoginResource
+object which then presents a login form to be completed by the user.
The LoginResource
object verifies the identity of the user,
+testing the supplied credentials against the credentials database specified
+in the deployment of the resource. Upon successful authentication, the user
+is redirected back to the application, which should let the user gain
+access.
Some server/framework environments do not permit automatic redirection +back to the application, notably Apache/mod_python. In such cases, a success +screen is presented to the user with a link to the application they were +attempting to access.
+ +In this mechanism, authenticators are employed, but only to verify the
+credentials of users when LoginResource
or
+LoginRedirectResource
objects are accessed.
With application-wide authenticators, anonymous access to resources and +applications can be difficult to permit alongside access by specific users, +mostly because servers and frameworks which employ HTTP authentication +schemes do so globally for a given application.
+ +With the LoginRedirect
and Login
modules, it is
+possible to declare a particular request parameter which must be present in
+the URL used to access a particular application for the client to be given
+anonymous access. Consequently, anonymous users are then identified specially
+with a special username that can also be configured.
With application-wide authenticators, a logout function may not be +available if the server/framework has been configured to use HTTP +authentication schemes, since no such function is defined for such +schemes.
+ +With the LoginRedirect
and Login
modules, it is
+possible to declare a particular request parameter which must be present in
+the URL used to access a particular application for the client to be logged
+out. A special logout confirmation URL may also be configured.