DotGNU
Resource Locator
String specification
Version 0.9
By:
Enzo-Adrian
Reyes(myrddian@bigpond.net.au)
With contributions
by:
Barry Fitzgerald(fitzix@sdf.lonestar.org)
Daniel W.
Connolly(http://www.w3.org/People/Connolly/)
Matthias
Rosenkranz(rose@m-rosenkranz.de)
Sean B.
Palmer(sean@mysterylights.com)
The idea behind a RLS (Resource Locator String) is the easy identification, and passing of information from peer to peer. It can also be used by end users to locate remote services provided by DotGNU. A RLS can be used to point to any DotGNU, this forces the RLS to be generic in format and also extendable for the individual service. Hence each service may expect a different RLS input, it is up to the individual service to interpret it's RLS tokens and data.
The format of an RLS contains two non-optional fields, these fields are separated using the '/' character. As an extension to these non-optional fields, RLS's have two extra fields which are optional. The format of an RLS is as follows:
rls://[User name@]<DotGNU Server>[:port]/<DotGNU
Service>[?Meta-Token]The optional fields are in square brackets, while the non-optional
fields are in nested in "<>" brackets.
Note: Please do note that the RLS specification is trying to conform to IETF RFC 2396 regarding Universal Resource Identifiers. If you find conflicts against the RFC please inform one of the Authors of the breach.
The first
non-optional field is the "<DotGNU server>"
field. This field tells a machine the IP/DNS of the server to locate
the service. The second field is the "<DotGNU Service>"
field and contains a string which is passed to the server, contained
in the server field, to open the named service. Some examples:
(1) rls://dotgnu.org/cvs
(2) rls://dotgnu.org/maillists
(3) rls://gnu.org/tbbs
The first example opens the dotgnu.org server and asks for it's cvs service. The second example also opens the same server and ask's to use the mail-list service. The third opens gnu.org and asks for the tbbs service.
The optional fields contain information which is of no use to the DotGNU server, but rather to the service it provides.
The first optional field is the user-name field. Now this field is used for the authentication mechanism in DotGNU. Examples include:
(1) rls://myrddian@dotgnu.org/authentication
(2) rls://fitzix@dotgnu.org/authentication
(3) rls://nb@dotgnu.org/auth
(4) rls://myrddian@dotgnu.org/cvs
So, here in these examples, all use the authentication service (different names can be used but convention should be followed). So it tells us, that user myrddian is seeking authentication from server dotgnu.org. Another less obvious example is that of self authentication. In number four, user myrddian wants to use the CVS service but CVS may ask for authentication, however the authentication data is on the local server, so it will self verify.
(1) rls://dotgnu.org/spell?I%20wnt%20to%20chke%20my,%20speeling
An RLS contains a Meta-Token this token contains a series of embeded tokens. The Meta-token is a RFC-2396 compliant string, this means it must contain escape characters in the format %hh, for seperators or any reserved characters. Tokens are embedded in this string. When a server receives a Meta-Token string it must convert it to the Standard Token format descrived below. This also works the other way around, Tokens must be converted and nested inside this Meta-Token.
Tokens
The tokens string, can contain data, be it a pointer back to another object or a string. The format of tokens on how their data is represented is not enforced, the DotGNU server will not enforce token data. The only exception to this rule is separation of Token data, and or nesting of token data. These are the only two rules enforced by the primary DotGNU server, everything else and the data the tokens contains has to be enforced by the individual service.
Tokens are separated using the ',' character, so <token 1>,<token2> can be recognized separately. If a string may contain the comma separator it is recommended that it be nested within " " as this prevents premature separation.
Nested tokens have two ways to separate the data, one way is to have the entire nested data within square brackets, the other is to have an identifier before the square brackets. Now, the first format might be useful to encase other RLS on to the same string, an example of this the first would contain the where the service the second where authentication can be found for the user requesting the service. Tokens with an identifier may contain other data other than nested RLS's. Examples include:
(1)[rls://myrddian@someisp.com/authentication]
(2)msg[hey,what]
(3)[rls://myrddian@someisp.com/auth],cmd[checkout[.], checkin]
Number 1 uses another RLS to check authentication for the CVS
service.
Number 2 uses a named nested token and it has two extra
fields inside.
Number 3 has both separation and nesting examples.
Conformance to RFC 2396 has solved another problem for us. Now, the RLS spec includes support for Heirarchical Services. In other words, services can have services within them. For example:
(1) rls://fitzix@dotgnu.org/cvs/checkin?dotgnu
In this example, I'm using the service "checkin" under
"cvs" to check the module "dotgnu" into the cvs
tree at dotgnu.org. With the inclusion of Heirarchical Services, the
ultimate flexible interface to the dotGNU API can be achieved.
Ports
Because a DotGNU server may not be in a standard port, a referring port must be passed along with the RLS. For Example:
) rls://dotgnu.org:1234
With the optional nesting fields, RLS's can point to any data. Their simplification has lead to better versatility. Because the tokens can point to any data, the data pointed to can be encrypted. While the RLS string it self may be transported over a secure encrypted protocol to provide better security. Tokens can also contain nested encryption keys, thus allowing even better security.