notes/webdav-general-summary

Ben's Quick Summary of WebDAV and DeltaV
=========================================

* WebDAV: RFC 2518.  Extends the standard HTTP methods to make web
  servers behave as traditional fileservers, complete with a locking
  model and meta-data properties.

* DeltaV: RFC 3253.  Adds more HTTP methods to WebDAV, introducing
  versioning concepts.  Provides a number of flexible versioning
  models that servers can support, and some backwards-compatibility
  modes for older WebDAV or HTTP/1.1 clients.


----------------------------------------

WebDAV
======

Key concepts introduced:  properties, collections, locking.

New HTTP client request headers:  {Depth, Destination, If, ...}
New HTTP server response headers: {DAV, ...}


* Property:    a meta-data name/value.  every property exists in 
               some unique "namespace", defined using xml namespaces.

  - a "live" property is one that is controlled by the server, like a
    file's content-length, for example, or a file's
    checked-in/checked-out state.  often the property is read-only; if
    not, the server enforces the propval's syntax/semantics.

  - a "dead" property is one that is invented and controlled by a
    user, just like file contents.

  - new HTTP methods:  PROPFIND, PROPPATCH to change propval.


* collection:  a directory.  contains a bunch of URIs and has props.

  - each child is called a 'member' URI.  each internal member URI
    must be relative to parent collection.
                  
  - collection URIs are supposed to end with trailing slashes.
    servers should auto-append them if not present.

  - new HTTP method:  MKCOL to create collection.


* locking:  a way of serializing access to a resource.

  - locking is totally optional -- the only 'flexible' part of the
    WebDAV spec.  a WebDAV server may support locking to any degree:
    either not at all, or some combination of exclusive or shared
    locks.  An OPTIONS response can return a header of DAV: 1 or DAV:
    2.  Level-2 support means locking is available.

  - new HTTP method: LOCK.  creates a lock and attaches it to the
    resource.  the server returns a 'lock token' to the client, which
    is defined to be any universally unique URI.  the 'lock' attached
    to the resource has these properties:

      * owner:   some authenticated username
      * token:   the specific lock identifier
      * scope:   either "exclusive" or "shared"
      * type:    "write".  [other types may exist someday]
      * depth:   for a collection, either 0 or infinity.
      * timeout: some value in seconds
      
       - exclusive locks behave how you think -- only one per resource
         allowed.  shared locks, on the other hand, are just for
         communication -- any number of them can be attached.

       - lock tokens are *not* secret: anyone can query the
         "DAV:lockdiscovery" property to see all the locks attached to
         a resource, which includes detailed descriptions of every
         field above.

       - to remove a lock with UNLOCK, or to modify something with an
         exclusive lock, the client must provide *two* things:

            1. authentication/authorization.  prove you own and/or are
               allowed to mess with the lock.  this happens via
               existing HTTP methods.

            2. the lock token, i.e. the "name" of the lock.  (this
               requirement also prevents some non-DAV aware program
               from using your auth credentials and accidentally doing
               an ignorant PUT.  think of it as credentials for your
               client software!)

       - 'DAV:supportedlock' live property: indicates what kinds of
          locking is allowed on a resource.

       - the rfc defines an 'opaquelocktoken' scheme that all dav
         servers must know how to understand: clients may generate and
         post them in an If: header.

       - a collection can have a lock of either Depth 0 or Infinity.
         a lock on a collection prevents adding/removing member URIs.
         if a lock-holder adds something to a deeply locked
         collection, then the newly added member becomes part of the
         same write lock.

       - a 'null resource' (which normally returns 404) can be locked,
         in order to reserve a name.  see section 7.4.


* other methods added by WebDAV:

   - COPY:  - copies resource to Destination: header.
            - optional "Overwrite: [T | F]" header defaults to T.
            - for collections, either Depth: [0 | infinity] allowed.
            - client can specify how to behave when copying props.

   - MOVE   - defined to be COPY + DELETE, but an atomic operation.


-------------------------------------------------------------------------

DeltaV
======

Models
======

A DeltaV server can support two different ways of working: server-side
working copies, and client-side working copies.  These systems aren't
mutually exclusive at all.  An OPTIONS request reveals which systems
the server supports.


The General Concepts
====================

If you understand this, everything will become really clear.  These
are the fundamentals.

DeltaV allows you version any kind of resource -- a file, a
collection, whatever.

 * If you take a resource on a server and put it under version control
   (using the VERSION-CONTROL method), a "Version Controlled
   Resource", or VCR, is created.  A VCR is a special thing: it's a
   unique, permanent URL used to talk about an entity under version
   control, no matter how many times it changes.

 * Every time you change a VCR (discussed below), a new "Version
   Resource" is created, or VR.  The VR is also a unique, permanent
   URL, representing some immutable object on the server; it
   represents the contents and (dead) properties of the VCR at one
   particular moment in time.

 * At any given time, a VCR has a "pointer" to some particular VR of
   itself.  The pointer is just a property, called "DAV:checked-in".
   By definition, the contents of the VCR are always equal to the
   contents of the VR it points to.  If you change the pointer to a
   different VR, the VCR's contents magically change to match.

 * All of a VCR's VR objects need to be organized somehow.  And in
   fact, they *are* organized into a little tree of predecessors and
   successors.  It turns out that every VCR has a "history" resource
   sitting in the background.  (The history resource may or may not be
   directly accessible, depending on whether the server supports the
   'Version History' feature.)  Regardless, a VCR's history resource
   is a container that contains all of the VRs, organized into a
   tree.  You might think of a history resource like an RCS
   file... except that the history is allowed to contain 'forks',
   i.e. a VR in the history might have multiple predecessors or
   successors.  Also, each VR in a history can have a human-readable
   "label" attached to it, so it's easier to talk about which VR you
   want.


Changing a VCR
==============

So, how do you make a change to VCR, then?  It all depends on what
deltaV features the server supports.

 * If the user is using the server-side working-copy model:

     - The client creates something called a 'workspace', using
       MKWORKSPACE.

     - CHECKOUT a VCR into the workspace.  The VCR's 'DAV:checked-in'
       property suddenly becomes a 'DAV:checked-out' property... but
       it still points to the same VR.

     - Use PUT and PROPATCH to change the contents or dead props of
       the VCR.  If you want to revert everything, just UNCHECKOUT.

     - CHECKIN the VCR.  A new VR is created in the VCR's history, and
       the 'DAV:checked-out' property becomes a 'DAV:checked-in'
       property, pointing to the new VR.

 * If the user is using the client-side working-copy model:

     - The client creates something called an 'activity', using
       MKACTIVITY.

     - CHECKOUT a VR into the activity.  This creates a temporary
       'working resource' (WR) in the activity.  The VCR's
       'DAV:checked-in' property suddenly becomes a 'DAV:checked-out'
       property... but it still points to the same VR.  The WR has a
       'DAV:checked-out' property that points to VR as well.

     - Use PUT and PROPATCH to change the contents or dead props of
       the WR.  If you want to revert everything, just UNCHECKOUT.

     - CHECKIN the WR.  A new VR is created in the VCR's history, and
       the VCR's 'DAV:checked-in' property points to it.  And
       normally, the temporary WR is deleted.      

See?  Not such a big deal.  Ahem.


Auto-Versioning
===============

What if some regular WebDAV client tries to use a deltaV server?  Or
an even dumber HTTP 1.1 client?  

If the server supports the 'auto-versioning' feature, then all
resources gain a new live property called 'DAV:auto-version'.  The
value of this property indicates how the server should behave when a
non-deltaV client does an ignorant PUT or PROPPATCH on a resource.  I
won't go into detail, but there are many possible behaviors:

  * do an implicit (auto-) CHECKOUT and CHECKIN.
  * auto-CHECKOUT, and wait for a lock to vanish before auto-CHECKIN.
  * same as above, but if not locked, wait for an explicit CHECKIN.
  * require a lock.  LOCK causes auto-CHECKOUT, UNLOCK causes auto-CHECKIN.



Basic Features
==============

DeltaV has a bunch of "basic features", and a bunch of "advanced
features".  Here are the basic features, in a nutshell.


* Version Control feature

    * new VERSION-CONTROL method to create a VCR.

    * resources gain a whole bunch of new live props (not all listed
      here), such some of which include DAV:checked-[in|out],
      DAV:auto-version, DAV:comment, the author.  VRs have properties
      that describe lists of successor and predecessor VRs.

    * new REPORT method.  two 'standard' reports are defined, but
      custom reports can be created.


* Checkout-in-place feature
 
    * new CHECKOUT, CHECKIN, UNCHECKOUT methods, which are able to
      modify VCRs in-place.


* Version History feature

    * version histories become tangible URLs.  introduce new dav
      resourcetype called 'DAV:version-history'.

    * all VCRs and VR's gain a 'DAV:version-history' prop that points
      to their history resource.

    * a version-history has a 'DAV:version-set' property that lists
      all VRs it contains, and a 'DAV:root-version' that points to the
      very first VR in the history.

    * a special REPORT allows one to convert a version-history URL
      into the VCR it represents.  (i.e. reverse-lookup.)


* Workspace feature

    * MKWORKSPACE creates a server-side working area.  an OPTIONS
      request can tell you where the client is allowed to do this.

    * the workspace resource has a property that lists all the
      resources it contains.  regular resources have a property
      indicating what workspace they're in.

    * The workspace can hold unversioned items put there by PUT & MKCOL.
      It can hold VCRs via CHECKOUT.

    * Special:  the VERSION-CONTROL method can create a *new* VCR from
      a history.  If two people both CHECKIN VCRs created from the
      same history resource, then poof... the history develops forks!


* Update feature

    * UPDATE method is able to tweak a VCR to "point" to a new VR.
      Very simple!


* Label feature

    * LABEL method allows you to attach a human-readable name to a
      particular VR.  

    * Each VR can have many names.  They're listed in a
      'DAV:label-name-set' property.

    * New http request header, "Label:", can be used to target
      a specific VR of a VCR.  This works when doing a GET of a VCR.
      It also works as you think on COPY, CHECKOUT, UDPATE, etc.


* Working Resource feature

    * This feature essentially allows client-side working copies to
      synchronize their data with the server.

    * all VRs gain two properties that control whether or not
      histories can (or should) contain forks.

    * a CHECKOUT of a VR creates a temporary 'working resource' (WR),
      which can then be modified.  When the WR is checked in, a new VR
      is created as usual, the WR vanishes, and the VCR is updated to
      point to the VR as usual.

    * note that this technique is an alternative to the
      Checkout-in-place feature, whereby VCRs are directly checked out
      and modified.



Advanced Features
=================

The advanced features of deltaV introduce a bunch of new concepts.
Here are the fundamentals.

[Whenever I say, "points to", I'm talking about some object leading to
another object via a specific property.]

* A "configuration" is a set of VCRs.  In particular, it contains a
  "root collection" which organizes the VCRs in some way.

  Note that this is _different_ than a versioned collection.  The main
  difference is that a collection is a *single* resource which
  contains dead-props and some directory-entries; its VRs just capture
  various states of the props and dirents.  But it's just ONE
  resource.  A configuration, however, is a SET of VCRs.  The VCRs may
  not necessarily be related to each other, either.  A configuration
  is a flexible thing -- its VCRs can be tweaked to point to
  different VRs, however you want, with no versioning happening in the
  background.  A collection, on the other hand, has a static set of
  dirents; to change them, you have to do a CHECKOUT, CHECKIN, which
  results in a new, static collection VR.

* A "baseline" is a special kind of resource which remembers this
  state of a configuration... it knows exactly which VR each VCR in
  the configuration should point to.  Just like a VR is a 'snapshot'
  of a VCR, a baseline is a 'snapshot' of the configuration.  And just
  like a VR, a baseline can have a human label too.
  
* Another kind of resource is a "version controlled configuration", or
  VCC.  This resource floats out in space;  its sole purpose is to
  magically connect a configuration to a baseline.   Specifically,
  each VCR in the configuration points to the VCC, and the VCC points
  to a baseline.

  And here's the usual magic: if you make the VCC point to a different
  baseline, then poof, the whole configuration suddenly switches to
  the baseline.  (That is, all of the configuration's VCRs suddenly
  point to the specific VRs of the baseline.)

* Finally, it's worth mentioning that a baseline resource points to a
  "baseline collection" resource.  This collection is a tree made up
  of the VRs in the baseline, easily browseable.  You can think of it
  as a "what-if" sort of preview -- i.e. "what would the configuration
  look like if I made its VCC point to this baseline?"  It also means
  people can view a baseline in action, *without* having to tweak a
  VCC, which might require write access of some kind.


Got all that?  Good.  Make some pictures.  :-)


How to create new baselines
===========================

The "in-place" method:

   Get this.  A VCC is really just a special kind of VCR!  But it's a
   VCR which represents the *whole state* of a configuration.  Just
   like a normal VCR, the VCC's "DAV:checked-in" property points to a
   baseline, which just a special kind of VR.

   That means you can do a CHECKOUT of the VCC in-place... then tweak
   the configuration to point to a new set of VR's... then CHECKIN the
   VCC.  Poof, a new baseline is created which captures your new
   configuration state.  And the VCC now points to that new baseline.

The "working resource" method:   

   Okay, so a baseline is a special kind of VR.  Fine, so we do a
   CHECKOUT of it, and get a "working baseline", which a special kind
   of WR.  

   Now, assuming you're using this method all around, you checkout the
   configuration's various VRs as WRs, modify the WRs, and check them
   back in to create new VRs.  Finally, you CHECKIN the working
   baseline, which creates a new baseline that captures the state of
   the configuration.  (The working baseline isn't something you tweak
   directly;  it's more like a token used at CHECKIN time.)


How Merging Works... at least for SVN.
=================

The deltaV MERGE command is very fancy.  It tracks merge ancestors in
properties, and sets flags for clients to manually resolve conflicts
on the server.

Subversion uses MERGE in a simpler way:

  1. We checkout a bunch of VRs into an activity, and patch them as a
     bunch of WRs.

  2. We checkout a "working baseline" into the activity, from whatever
     baseline represents the HEAD svn revision.

  3. We issue a MERGE request with the activity as the source.

     By definition, this causes the whole activity to be
     auto-checked-in.  First each WR in the activity is checked-in,
     causing the configuration to morph.  Then the working-baseline in
     the activity is checked-in, which creates a new baseline that
     captures the configuration state.

Of course, mod_dav_svn doesn't actually do all the checkin stuff;  but
what's important is that the *result* of the MERGE is exactly as IF
all this stuff had happened.  And that's all that matters.