webdav-general-summary

linux subdivision ying gai ke yi le ba

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 sofware!)

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

       - the rfc defines an 'opaquelocktoken' schema 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?