WWW Versioning Support

WWW Versioning Support

Draft Proposal (v 0.1, April 16, 1996)

Jim Whitehead

Abstract

TBD

1. Introduction

1.1 Purpose

The World-Wide Web has demonstrated great utility as a mechanism for allowing information entities to be published, then browsed by the global Internet community. However, the current publish/browse model only allows browsing of the most current revision of an entity; older versions of an entity become unaccessible after it is updated. The HTTP/1.1 specification extends the publish/browse model by allowing distributed editing of entities, affording use of the World-Wide Web for distributed home editing of personal web pages, tele-commuting, and distributed software development, among others. As defined in HTTP/1.1, the "PUT" method overwrites the current contents of the destination Uniform Resource Identifier (URI) or Uniform Resource Locator (URL). This allows users to overwrite each other's editing updates with successive PUT method invocations (the "lost update" problem), an unacceptable outcome during group work.

Versioning techniques alleviate both the loss of past revisions of an entity and the lost update problem. Fundamental to all versioning approaches is the provision of storage for past states of a entitiy and methods for the retrieval of those past states; together, they preserve the history of an entity for later examination or use. Versioning addresses the lost update problem by providing a policy for the creation, locking, and editing of a new state of an entity.

This document describes a set of extensions to the World-Wide Web which augment it with versioning capability. Included in this document are extensions to the HTTP/1.1 protocol to add methods specific to versioning, new entity types to describe collections of versioned entities and derivation relationships between versions of the same entity, and URI/URL naming conventions for versioned entities.

1.2 Desired Capabilites

The capabilities desired of versioning support for the World-Wide Web are:

Policy-neutral versioning: the methods defined for accessing, modifing, and locking entities should allow multiple versioning policies to be built on top of them. For example, lock-based policies, as employed by RCS, and merge-based policies, as implemented in CVS, should both be implementable.
Retrieval of a stated version of an entity: Any given revision of an entity should be accessible, thus supporting links to stated revisions of entities.
Writing to a given version of an entity: Once changes have been made to an entity, versioning policies often dictate that the changes be written into a new, stated version of that entity.
Parallel development support: Since it frequently occurs that multiple people edit the same entity simultaneously, this type of activity must be supported. User agents must be supplied with enough information to inform their users when they are entering a parallel development situation, and they must be supplied with the versions of parallel entities so they can provide merge support for the entity contents. Futhermore, since it is currently beyond the state of the art to provide merge support for certain entity types (e.g., MPEG video), it must be possible to disallow parallel development on these entity types.
Browsing within a collection of entities: Often multiple entities together form a logical grouping, for example, a collection of HTML and GIF entities which comprise online documentation for a software product. It is desirable to provide support for browsing within such a collection without requiring either the user or the entities to explicitly name the destination entity version of each link traversal.
Retrieval of derivation relationships between versions of an entity: The ability to trace the development and ownership of an entity provides visibility into the development of that entity, and is frequently useful to the user.
Visibility control: Through the user agent, it should be possible to control the external visibility of an entity. For example, this is useful for ensuring that working revisions of an entity are not accessible by the entire world.

1.3 Types of Group Work Supported

Single, Parallel Asynchronous, not Parallel Synchronous

2.0 Version Naming Conventions

A version of a URI is explicitly specified by appending a parameter called "v" to the URI. For example, version 3.0 of entity foo would be written foo;v=3.0.

3.0 Extensions to HTTP/1.1

(Note: IETF standard BNF is not consistently used throughout ... needs some cleanup)

3.1 New Methods

The new methods added to HTTP/1.1 to support versioning are:

"FLAG"

"LOCK"

"UNLOCK"

"USE"

3.2 FLAG

The FLAG method operates on flags associated with the Request-URI. FLAG makes use of a new Request Header Field called "Flag-Option". Valid values of Flag-Option are "SET" flag, "CLEAR" flag, and "QUERY". The FLAG method must be accompanied by a valid "Authorization" header field (ed: or the appropriate header field for identifying the end-user operating the user-agent to the HTTP server). The FLAG method always has an entity-body which contains a list of the active flags for the entity (including the effects of the requested Flag-Option), in the form:

For all users with flags set:

{user identification string}: {list of flags currently set for the user}

3.2.1 Flag-Option values

The "SET" Flag-Option sets the indicated flag to true. The "CLEAR" Flag-Option sets the indicated flag to false. The "QUERY" Flag-Option has no effect on any flag (and hence only causes the return of the current list of flags). A flag set on an entity (no version specified in the Request-URI) applies to all versions of that entity. A flag set on a particular version of an entity (version specified in Request-URI) applies to only the indicated version of the entity.

When the Flag-Option is "SET", the indicated flag will be set, then automatically cleared after one week, unless the "Auto-Timeout" header is present, in which case the value it specifies will be employed. An Auto-Timeout value of "Never" causes the flag to never automatically be cleared after a preset interval. Re-setting the same flag on the Request-URI is legal, and causes the timeout value to be updated.

3.2.2 Flag Naming Conventions

There are two flags with special names for the versioning context, these being:

"EDIT"

"LOCK"

The EDIT flag is for use by CVS-like versioning policies, and has the meaning: this entity is currently being edited by the named user. The LOCK flag is automatically set by the LOCK method, and indicates that the entity is locked. User-agents should not use other flags to duplicate the meaning of the EDIT and LOCK flags.

3.3 LOCK

The "LOCK" method causes the Request-URI to have the "PUT" method denied for all users except the user requesting the lock. This method must be accompanied by a valid "Authorization" header field. If the Request-URI specifically names a version, then the lock applies only to that version. If the Request-URI does not name a version, then the lock applies to all versions. If a "LOCK" is attempted on all versions of the Request-URI and there is currently a lock on an individual version of the Request-URI held by another user, a response with status code 409 Conflict will be returned, with an entity body which states that the Request-URI is already locked by another user(s), and naming the other user(s). In the event a "PUT" is attempted on a locked entity, a response with status code 409 Conflict will be returned, with an entity body which states the Request-URI is locked.

The "LOCK" method also causes the "LOCK" flag to be set on the Request-URI, however, the currently set flags are not returned in the entity-body.

When a LOCK is set, it will automatically be reset after one week, unless the "Auto-Timeout" header is present, in which case the value it specifies will be employed. An Auto-Timeout value of "Never" causes the lock to never automatically be reset after a predetermined interval. Re-locking the same Request-URI is legal, and causes the timeout value to be updated.

The LOCK method may also employ the new "If-Not-Modified-Since" header field to specify that the lock will occur only if the entity has not been modified since the time specified in this field. This ensures that a user does not take out a lock on an entity which has changes since they retrieved it. Typically, the time specified in the "If-Not-Modified-Since" field is the time of the most recent retrieval of the entity being locked.

3.4 UNLOCK

The "UNLOCK" method releases an existing lock, and clears the LOCK flag on the Request-URI, and must be accompanied by a valid "Authorization" field. If the Request-URI does not have a lock set by the requesting user, or if there is a lock currently held by another user, a response with status code 409 Conflict will be returned, with an entity body which explains the cause of the conflict.

3.5 USE

The "USE" method causes the server to always employ the specified version of the Request-URI when the Request-URI is employed in a method without stating an explicit version. This method allows a preferred version of an entity to be returned by the server in response to a GET or HEAD method. It also allows the version of a directory (container entity) to be prespecified for all methods.

4.0 Configurations

Browsing within a collection of entities (such as an older version of program documentation) may be accomplished using a configuration file. A configuration file contains a list of URI's (without a version explicitly specified), and a corresponding URI with the version specified. The configuration file is used by the user-agent as a filter: if a GET or HEAD method call is made against one of the URI's without the version explicitly specified from the active configuration file, the user-agent will substitute the URI with the version explicitly stated. The configuration file also contains an entry point designator, which specifies a member of the configuration to be loaded after the configuration itself has finished loading (this is analogous to loading a description of a book, then loading the contents of the first chapter for display).

Navigation within a configuration starts when the user-agent loads a configuration file (MIME type: text/config) -- the user agent parses the file, determines the entry point URI, performs a GET on it, then immediately starts using the configuration as a filter until the next configuration file is loaded, at which point only the new configuration is active.

4.1 Description of text/config type

The text/config (configuration file) type is just a simple mapping between URI's. This basic wrapping information has been augmented with HTML formatting codes so that the file can be displayed by a user-agent which does understand the text/config type. This allows limited browsing capability by using the configuration file as a menu.

ConfigFile = HTML-DTD

HTML-Head

Config-Banner

Config-Entry-Point

*(Config-Item)

HTML-End

The detailed BNF elaboration is TBD.

An example configuration file is:


<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">




<HEAD>

<TITLE>Configuration File: name of configuration file</TITLE>

</HEAD>



<BODY>

<H3>Configuration File: name of configuration file</H3>




<! Entry-point: http://www.ics.uci.edu/chimera/docs/intro.html;v=1.0
>






<! http://www.ics.uci.edu/chimera/docs/intro.html >

<A HREF="http://www.ics.uci.edu/chimera/docs/intro.html;v=1.0">

http://www.ics.uci.edu/chimera/docs/intro.html;v=1.0</A>







<! http://www.ics.uci.edu/chimera/docs/chapter1.html >

<A HREF="http://www.ics.uci.edu/chimera/docs/chapter1.html;v=1.4">

http://www.ics.uci.edu/chimera/docs/chapter1.html;v=1.4</A>

...

</BODY>

5.0 Derivations File

A TBD description of the file format which can be used to create a history view of the entity.

Appendix A CVS Style Use Example

Appendix A contains a description of an example use of the methods described in this document for implementing the CVS-style of versioning (merge-based).

The user starts by browsing through a series of pages. Eventually they find one they want to begin editing.

GET entity

Retrieves contents of page to be modified.

FLAG entity (Flag-Option: SET EDIT)

Notifies server that editing is taking place. The user agent receives back a list of flags already set on this entity, and notifies the user that they are entering a parallel work situation if the EDIT flag is already set. If the LOCK flag is set, the user is informed of the LOCK (and they may optionally proceed at their own risk, knowing they have to coordinate the release of the lock before they can save their changes).

The user now enters an "edit-save-check" cycle where they perform their work, save it, then check that it actually looks correct using a browser. There are several possibilities for where this work can be saved. One option is to the user's local disk. Another is to perform a PUT to a scratchpad area on the HTTP server.

In the case the user decides to stop editing, the user-agent sends a FLAG entity (Flag-Option: CLEAR EDIT), and performs a DELETE of all working copies on the server.

When the user has finished editing and wants to do a final save of their changes, the user agent performs a:

PUT new-entity-version	Save the contents to the server
FLAG entity (Flag-Option: CLEAR EDIT)	Inform the server that this user is not performing any more editing. The user-agent checks the flag settings on this entity to see if merging is necessary. (Ed: I think we may need to look at derivation information to fully determine if merging is necessary.)

Perform merge, if needed.

Appendix B RCS Style Use Example

Appendix B contains a description of an example use of the methods described in this document for implementing the RCS-style of versioning (lock-based).

The user starts by browsing through a series of pages. Eventually they find one they want to begin editing.

GET entity
Retrieval of the entity to be edited

FLAG entity (Flag-Option: QUERY) Retrieve all flags currently set on the entity. This allows the user-agent to check for other users editing this entity using non-locking styles, and for the existence of active locks on the entity.

Assuming there are no locks, or flags set...

LOCK entity (If-Not-Mofified-Since: time of GET of entity)

Assuming the lock was successful, the user now begins an edit-save-check cycle.

If they decide to abort their work, the user-agent issues an UNLOCK entity, and a DELETE of all working copies stored on the HTTP server.

If the user decides to perform their final save:

PUT new-entity-version	Save the final version of the entity
UNLOCK entity	Release the lock

Appendix C Issues that still need to be addressed

Issues which have not yet been addressed by this document are:

Visibility control by the end-user
Access control by the end-user
others? ...

GET entity	Retrieval of the entity to be edited
FLAG entity (Flag-Option: QUERY)	Retrieve all flags currently set on the entity. This allows the user-agent to check for other users editing this entity using non-locking styles, and for the existence of active locks on the entity.