Re: [ogpx] content negotiation for LLSD over HTTP connections

[Carlo Wood <[e-mail]>]

Ok, I made a 'translation' of that IRC page for the purpose of ogpx:

For documentation purposes there would exist a (central) webpage,
for example http://protocols.ogpx.net, that lists all (accepted)
ogpx server implementations (basically meaning more or less
independent groups working on their own ogpx server versions).

For example, this page could list the labels:
SecondLife, OpenSim, BlueMoon, which link to websites
controlled by the aforementioned group. Lets call these
"implementation labels" for now.

Upon connection to a server, the server should send a message
to the client as early as possible (even before authentication,
or order to allow also the authentication method to be altered
in the future) indicating which protocol base it is using.
This would exist of a (list) of triplets exists of a label (string)
a version (integer) and a 'compatibility version' (integer).

For human readable and documentation reasons, the label should
always start with an "implementation label". It's highly suggested
to just add an integer behind that to complete the label and
make it unique. Lets call these labels "version labels".
For example, the version labels could read "SecondLife23",
"OpenSim1", etc.

For documentation purposes, each of the aforementioned websites
owned by the different implementer groups should list each of
these version labels with a link to more information about them.

The version string together with the version defines the (supported)
protocol of the server: every feature, mandatory of optional.

Neither side has to worry about the mandatory parts, since the
versions will take care of that: a 'compatibility version' is
oldest version that supports all mandatory stuff.

The client then reacts with the version label and protocol version
it 'requests', as well as all the optional features it wants.
The server confirms which optional features will be used, after
which the protocol is switched to the negotiated protocol.
The client acknowledges this and also switches to the final
protocol.

As an example, lets assume that one implementation (opensim)
adds a feature that allows clients to better synchronize animations
with sound. They assign the label "anisndsync" to it, which only
really has to be unique within the namespace of OpenSim.
It is made a negotiable feature of 'OpenSim1 version 30'.

A viewer that has no notion of this feature will logically not
request it, and therefore it will not be used.

If some grid makes the feature mandatory, the negotation fails
with such a client and the user is told to upgrade to a viewer
that supports 'anisndsync'. I do not consider it very likely
that anyone would make it mandatory however, until -say- 90%
of all viewers already support it, and the 4 year-old viewers
that still don't become really annoying.

If the client supports it, it will request it (if it's an optional
feature, still) and the server will grant it. Obviously the
server will know about it (it sent 'OpenSim1 30'), or else
the viewer would not have requested it.

However, then this feauture turns out to not to work - and
the opensim developers decide to remove it again from version
31. Removing a negotiable feature doesn't break compatiblity,
so there is nothing to indicate to a viewer (that was written
during version 30) that version 31 doesn't support it anymore.
What would happen is this: The server says: Opensim1 31 10.
(where 10 is the compatibility version in this example).
The viewer, only knowing about version 30 and before (that is,
version 10 to 30) doesn't have a clue what changed in
version 31, but it knows that 10 < 30, the version it does
support - and hence it is allowed to react as if the server
is version 30. So, it requests "anisndsync" as before.
This time however, the server doesn't acknowledge it, and
the feature is not used.

What worried people in the past with this sheme is:
How do the clients keep track of all the features that are
mandatory and/or negotiable for every version?

Well, this is really very very simple. For each implementated
feature the coder had to sit down and read the documenation.
Along with that documentation come the label and version
number. So, all that is needed is a map from "label + version"
to which *implemented* features are mandatory or negotiable.
The maintenance load of that is neglectable. It will be like
adding two lines of code extra per feature:

  protocol.register("OpenSim1", 30, "anisndsync", &handle_anisndsync);

and common code that takes care of the whole negotiation
will do the rest.

Mapping "OpenSim1" to the mandatory and optional features
might involve more code lines, but this code can simply be
copy&pasted from the documentation website of "OpenSim1".
Also this will be something that is easy to maintain (adding
and removing lines per added/delete feature).

-- 
Carlo Wood <[e-mail]>