[z3-checkins] r41934 - z3/deliverance/DeliveranceVHoster/trunk/docs
ianb at codespeak.net
ianb at codespeak.net
Fri Apr 6 07:51:22 CEST 2007
Author: ianb
Date: Fri Apr 6 07:51:21 2007
New Revision: 41934
Added:
z3/deliverance/DeliveranceVHoster/trunk/docs/hooks.txt (contents, props changed)
z3/deliverance/DeliveranceVHoster/trunk/docs/rest-api.txt (contents, props changed)
Log:
Added some docs
Added: z3/deliverance/DeliveranceVHoster/trunk/docs/hooks.txt
==============================================================================
--- (empty file)
+++ z3/deliverance/DeliveranceVHoster/trunk/docs/hooks.txt Fri Apr 6 07:51:21 2007
@@ -0,0 +1,78 @@
+Hooks
+=====
+
+There are three hooks that you can configure (in the ``.ini`` file) to
+programmatically handle parts of DeliveranceVHoster's handling of
+requests.
+
+Each is configured by pointing to a Python file (ending in ``.py``),
+giving a module name, or pointing directly to an object. If you point
+to a Python file or module then the system will look for an object
+(usually a function) with the name of the setting (e.g.,
+``init_domain``). You can point all the settings to the same file or
+module, and have different functions in that file.
+
+All the hook functions get access to the configuration (referred to as
+``app_conf``), a dictionary of all the settings in the
+DeliveranceVHoster section of the ``.ini`` file. You can put
+arbitrary settings in that file, to pass them through to the hooks.
+
+``init_domain``
+---------------
+
+When a new virtual host is visited, a ``dvhoster.model.DomainInfo``
+object is created for that virtual host. After it is created, this
+function is called, and can setup any initial settings. To see what
+attributes are available see the ``dvhoster.model`` file; generally
+they are attributes with the same names as used in the `REST API
+<rest-api.html>`_.
+
+The function should look like::
+
+ def init_domain(domain_info, app_conf):
+ domain_info.remote_uris = []
+
+Or potentially something more useful.
+
+``find_remote_uri``
+-------------------
+
+This function is called after the ``remote_uris`` have been searched
+and a match found (or potentially no match found). It returns the
+remote_uri that should be used. It should look like::
+
+ def find_remote_uri(remote_uri, remote_uri_info, environ,
+ app_conf):
+ if remote_uri is not None:
+ # It was set explicitly in the remote_uris setting
+ return remote_uri
+ if remote_uri_info is None:
+ # There was no match found at all; fail:
+ return None
+ # You can make changes to environ if you want, or read it
+ # for more information.
+ # This would actually be a little silly, though:
+ return remote_uri_info['comment']
+
+``should_theme_uri``
+--------------------
+
+This function is called and should return True (the request should be
+themed) or False (the request should be left alone). It should look
+like::
+
+ def should_theme_uri(remote_uri, environ, app_conf):
+ if 'python' in environ.get('HTTP_USER_AGENT'):
+ # probably a request with urllib or something
+ return False
+ return True
+
+Exceptions
+----------
+
+In any of these methods you may raise exceptions from
+`paste.httpexceptions
+<http://pythonpaste.org/module-paste.httpexceptions.html>`_. Perhaps,
+for instance, a redirection is in order (``HTTPMovedPermanently``).
+Or an unauthorized request (``HTTPForbidden``).
+
Added: z3/deliverance/DeliveranceVHoster/trunk/docs/rest-api.txt
==============================================================================
--- (empty file)
+++ z3/deliverance/DeliveranceVHoster/trunk/docs/rest-api.txt Fri Apr 6 07:51:21 2007
@@ -0,0 +1,113 @@
+REST API
+========
+
+DeliveranceVHoster configuration is done through a REST API. This API
+is made up of a series of `resources
+<http://en.wikipedia.org/wiki/Resource_%28Web%29>`_ that can be read
+with GET and set with PUT.
+
+The API is available at ``/.deliverance/`` under the domain. Each
+domain presents the configuration for that domain. So when you access
+``http://foo.com/.deliverance/aliases`` you are accessing the
+``aliases`` parameter for ``foo.com``. There's no global
+configuration presented though this API, only domain-specific
+configuration.
+
+Resources
+---------
+
+Each of these resources can be read with GET and set with PUT.
+
+``/.deliverance/static/*``
+
+ Static files. You can use PUT to update or save files, and DELETE
+ to remove them. Use MKCOL to create directories. When a file is
+ put here it becomes a global override. So if you PUT a file at
+ ``/.deliverance/static/styles/style.css``, then a request to
+ ``/styles/style.css`` will return that file. Any other request to
+ ``/styles/*`` will be handled normally. ``index.html`` can be used
+ to override directory indexes.
+
+ You can GET directories here, which will give you directory listings
+ in simple HTML. PROPLIST (from WebDAV) is not supported.
+
+``/.deliverance/rules/rules.xml``
+
+ The rules file. This is an XML document. A file
+ ``/.deliverance/rules/standardrules.xml`` is always set, which are
+ standard rules applicable to HTML. You can include these rules with
+ XInclude.
+
+ Similar to ``/.deliverance/static`` you can create directories here
+ and add arbitrary files. The files appear in ``/_rules`` (e.g.,
+ ``/_rules/rules.xml``).
+
+``/.deliverance/domain``
+
+ The main domain, like ``foo.com`` in the example. A simple string.
+ You can PUT a new value here to rename the entire site. If you
+ rename a site, the original name automatically becomes an alias.
+
+ You can GET this value to see if you are accessing the canonical
+ domain or an alias; for ``/.deliverance`` requests the redirection
+ does not occur.
+
+``/.deliverance/aliases``
+
+ This is a list of domains that are aliases for this domain. The
+ list text, one domain per line. Any request to one of these aliases
+ will be redirected to the canonical/main domain.
+
+``/.deliverance/theme_uri``
+
+ The URI of the theme. This is a simple string, with no encoding.
+
+``/.deliverance/remote_uris``
+
+ A JSON structure, looking like::
+
+ [{"path": "", "remote_uri": "http://localhost:8080"},
+ {"path": "/tasks", "remote_uri": "http://localhost:9090"}]
+
+ This means that requests to ``/tasks/*`` will be forwarded to the
+ server at ``http://localhost:9090``, while all other requests
+ (anything under the null path ``""``) will be forwarded to
+ ``http://localhost:8080``. Requests ``/tasks`` will be redirected
+ to ``/tasks/``.
+
+ Each setting can also have a key ``headers``, which is a dictionary
+ of headers to set on the request. These are header the application
+ being forwarded to can consume. Additionally a ``comment`` key can
+ hold any value.
+
+ ``remote_uri`` is optional. Using `hooks <hooks.html>`_ you can set
+ a remote URI programmatically without setting it in domain-specific
+ configuration.
+
+ This resource must be set for a new virtual host to be usable. You
+ can do this with a `hook <hook.html>`_, or otherwise all requests
+ (except to this configuration API) will fail.
+
+``/.deliverance/addition_request_headers``
+
+ A JSON structure looking like::
+
+ [["X-Foo", "Bar"],
+ ["X-Foo-2", "Bar 2"]]
+
+ Each item is a header (name and value) that will be set on all
+ requests to this domain.
+
+``/.deliverance/redirects``
+
+ A JSON structure, looking like::
+
+ [{"path": "/foo.html", "rewrite": "/foo/",
+ "comment": "from old site"},
+ {"prefix": "/blog/index.cgi/", "rewrite": "/blog/"}]
+
+ Each item represents a redirection, typically set to support an old
+ set of URLs after a transition. Each item must contain either
+ ``path`` (a fixed path to redirect) or ``prefix`` (a directory to
+ redirect). It is redirected to the value of ``rewrite``. You may
+ optionally include a comment.
More information about the z3-checkins
mailing list