[kforge-dev] url layout v0.2

[Rufus Pollock]

The following is a follow-up to my previous message on url layout and 
describes current thinking on the url scheme for kforge. All comments 
are welcome. This text is taken from the documentation to 
kforge.LocationMapper.

~rufus

URL Layout
**********

URL layout defines a view onto the underlying system data.
This primarily consists of two types:
     1. Core data: projects and persons/users
     2. Data for services

There are 3 main url addressing schemes:
     1. Admin view: primary view provided by the kforge system)
     2. Project view: for non-administrative access to project resources
     3. Per-service view or access: http access to services for users (so
     not APIs)

Defn: domainname is the site domain name such as kforge.net or
test.kforge.net it is to this that any hosts such as www or svn will be
prepended. Throughout we shall use kforge.net for illustration purposes
but this could be replaced by any valid domain name

Defn: **primary** view denotes the view presented at the default site url
i.e. kforge.net and www.kforge.net (we shall assume that usually these
resolve to the same thing)

Remarks on Service Addressing
=============================

Services are uniquely identified by:
     1. plugin_type, project, service_name
     2. service_id

And over-identified by:
     plugin_type, project, service_name, service_id

Therefore to address via a url we must either:
     1. Combine all 3 items into the url in some manner.
     2. Use service_id

It will be normal for service_name or service_id to come last in the url
string as these are the least significant pieces of info. However it is
unclear which should come first out of project and plugin_type. To
distinguish these two approaches we shall label them respectively:

     project addressing
     plugin addressing

Examples are:

Project Addressing:

     ${project}.kforge.net/${plugin}/${service_name}
     e.g. ukparse.kforge.net/wiki/wiki

Plugin addressing:
     ${plugin}.kforge.net/${project}/${service_name}
     e.g. wiki.kforge.net/ukparse/wiki

     or
     xxx.kforge.net/${plugin}/${project}/${service_id}

Remark: In general the service name will default to the plugin name. Thus
you will may end up with urls of the form  ..../wiki/wiki or /svn/svn.

This may seem a little annoying. If it were known that there were only
going to be one instance of that plugin per project then we could remove
the repetition and have /wiki or /svn. This adds an extra level of
complexity in that:
     1. Different projects have different url naming schemes
     2. One must specify in advance whether a project will allow multiple
     instances of a plugin and it will be difficult or impossible to change
     this once the decision has been taken

Thus this option will not be supported. (It was also suggested that one
could have some way to specify a default instance which would then be
served at the root plugin url e.g. /wiki/wiki/ would be available at /wiki/
or /svn/svn/ would be available at /svn/. However this is clearly
problematic as pages get served under this and these might conflict with
the names for other plugin instances e.g. often have project names at the
base of a svn repository and it is possible that you might have a project
in the repository /and/ another subversion instance in which case these
would both appear at /svn/project-name. Thus this case only works in the
situation in which there will be a single instance of the plugin).

Admin Virtual Host
==================

By default admin view will be the primary view.
It will also be available at admin.kforge.net
This is dealt with in greater detail elsewhere (e.g. the front controller
of the kforge user interface (kui) so it will only be sketched here and the
description is prescriptive rather than normative [[TODO: give explicit
location]].

admin.kforge.net/
     project/${project_name}/
         create
         delete
         service/
             ${service_name}
     user/${user_name}/
     ...


Projects Virtual Host
=====================

Available at projects.kforge.net
May also be a primary view.

Provides project priority addressing but with a fixed subdomain, i.e.

     projects.kforge.net/${project}/${plugin}/${service_name}
     projects.kforge.net/${project}/
         -- provide access to project web pages

Project Virtual Host
====================

Can *not* be a primary view as there are several and none have priority
Project priority addressing with project name as subdomain, i.e.

${project}.kforge.net/
     WEB ONLY -- No services?

Main use is to allow for this to direct to a site outside of kforge that is
run by project owner.

Plugin Virtual Host(s)
======================

Can *not* be a primary view as there are several and none have priority
Plugin priority addressing with plugin as subdomain, i.e.

${plugin}.kforge.net/${project}/
                             ${service_name}
                             ${service_id}