subversion-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From cmpil...@apache.org
Subject svn commit: r900584 [1/2] - in /subversion/trunk: notes/ notes/http-and-webdav/ www/
Date Mon, 18 Jan 2010 22:00:44 GMT
Author: cmpilato
Date: Mon Jan 18 22:00:43 2010
New Revision: 900584

URL: http://svn.apache.org/viewvc?rev=900584&view=rev
Log:
Move WebDAV- and HTTP-related technical notes and docs into a
subdirectory of notes/ dedicated to such things.

* notes/http-and-webdav
  New directory.

* notes/http-protocol-v2.txt,
* notes/webdav-acl-notes,
* notes/webdav-general-summary,
* notes/webdav-protocol,
* notes/webdav-proxy,
* www/webdav-usage.html
  Move all this stuff...

* notes/http-and-webdav/http-protocol-v2.txt,
* notes/http-and-webdav/webdav-acl-notes,
* notes/http-and-webdav/webdav-general-summary,
* notes/http-and-webdav/webdav-protocol,
* notes/http-and-webdav/webdav-proxy,
* notes/http-and-webdav/webdav-usage.html
  ...to here.

Added:
    subversion/trunk/notes/http-and-webdav/
    subversion/trunk/notes/http-and-webdav/http-protocol-v2.txt
      - copied unchanged from r900550, subversion/trunk/notes/http-protocol-v2.txt
    subversion/trunk/notes/http-and-webdav/webdav-acl-notes   (with props)
    subversion/trunk/notes/http-and-webdav/webdav-general-summary   (with props)
    subversion/trunk/notes/http-and-webdav/webdav-protocol   (with props)
    subversion/trunk/notes/http-and-webdav/webdav-proxy   (with props)
    subversion/trunk/notes/http-and-webdav/webdav-usage.html   (with props)
Removed:
    subversion/trunk/notes/http-protocol-v2.txt
    subversion/trunk/notes/webdav-acl-notes
    subversion/trunk/notes/webdav-general-summary
    subversion/trunk/notes/webdav-protocol
    subversion/trunk/notes/webdav-proxy
    subversion/trunk/www/webdav-usage.html

Added: subversion/trunk/notes/http-and-webdav/webdav-acl-notes
URL: http://svn.apache.org/viewvc/subversion/trunk/notes/http-and-webdav/webdav-acl-notes?rev=900584&view=auto
==============================================================================
--- subversion/trunk/notes/http-and-webdav/webdav-acl-notes (added)
+++ subversion/trunk/notes/http-and-webdav/webdav-acl-notes Mon Jan 18 22:00:43 2010
@@ -0,0 +1,308 @@
+This documents highlights the current WebDAV ACL specification and
+should start to identify how Subversion can implement the requisite
+functionality to become compliant.  Note that some of these items may
+require work in Apache HTTP Server and/or its included mod_dav to succeed.
+
+RFC 3744: http://www.ietf.org/rfc/rfc3744.txt
+
+===Open questions===
+
+* Are WebDAV ACLs version independent, version dependent, or up to impl?
+Justin: Seems up to impl.  I'd believe that ACLs are properties of the
+        resource and should be versioned.
+Brane: ACLs should be version-specific with history, but that's not the
+       same as versioned, as you should be able to change the access
+       permissions for a path in an old (i.e., non-HEAD) revision.
+
+* What inheritance model should Subversion support?  If so, how?
+Justin: WebDAV ACLs indicate inheritance via DAV:inherited property and
+        DAV:inherited-acl property (for ACE and ACLs, respectively).  So, the
+        inheritance is directly known and explicit (i.e. X inherits from Y).
+        I believe a similar model would work fine within Subversion.
+Brane: Agreed. This is very similar to the NTFS inheritance model (no
+       surprise there :-) I'd add the restriction that ACLs and ACEs
+       can only be inherited from "..", i.e., not from anywhere
+       in the repos.
+Wilfredo: Note that there is no way in the protocol to specify inheritance.
+          That is, you can't say (over DAV), "this should inherit from that",
+          So any policy set by the server would have to be one everyone can
+          live with, unless you want to add an extension to provide a way to
+          communicate a policy change to the server.
+Wilfredo: Note also that if you have a resource that inherits from another, and
+          the latter is deleted, you've got to do some cleanup on the server.
+          This can be avoided if you only allow inheritance from a parent.
+
+* Should ACLs themselves be versioned?
+Justin: See above, yes, I think they should.  (Those that aren't derived.)
+
+* What sub/superset of WebDAV privileges should Subversion have, and how
+  should they map to WebDAV's privilege model?
+Brane: We should at least have a create-child privilege (subsumed in DAV:write,
+       and never inherited -- ouch!) that can be applied to tags dirs
+       so that tags can be created there, but not modified (e.g.,
+       set DAV:read and SVN:create-child on the dir, and make all ACLs
+       inherited by default (unless overriden))
+Wilfredo: Use DAV:bind for "create child".
+          Again, configurable inheritance will require an extension element
+          (eg. SVN:inherit) in ACL requests.
+Wilfredo: DAV does not require any specific privileges, but does define a few
+          that are useful.  You can also mark some as "abstract", which means
+          they can not be set/unset independently, and a privilege may aggregate
+          others.  Here's the full set defined by DAV, in the hierarchy I used
+          in Twisted:
+          
+          - DAV:all
+            - DAV:read
+            - DAV:write
+              - DAV:write-properties
+              - DAV:write-content
+            - DAV:bind
+            - DAV:unbind
+            - DAV:read-acl
+            - DAV:write-acl
+            - DAV:read-current-user-privilege-set
+
+* What other types of access control mechanisms are we going to require?
+Justin: Bill has mentioned that we might want to control who can change
+        the log.  Indeed, there seems to be a separate class of repository
+        specific attributes.  Could we key them off of the Subversion root?
+        These would seem to be an extension of the WebDAV ACL model, but
+        necessary ones for uses.
+Wilfredo: You can support specific ACEs on the root resource and not allow them
+          on the rest, so you could, for example, have SVN:rewrite-log under
+          DAV:write-properties on the root resource to globally control log
+          edits.  Or (perhaps less confusing for clients), expose it on all
+          resources, but require that it be inherited from the root by all
+          others.
+
+* What are the real semantics of DAV:owner?  Could it be the person who
+  create this file?  The site admin?  What?
+Brane: The owner=creator variant seems most common, although on Windows
+       I've seen setups where the creator doesn't have the "Object
+       Ownership" privilege, and the ownership reverts to the creator
+       of the enclosing composite entity (directory, that is).
+       This makes sense in a role-based authz system, which is
+       probably the way Subversion wants to go...
+Wilfredo: DAV:owner and DAV:group are useful if you are using a UNIX-style
+          backing store for permissions.  I would suggest that we not use
+          either of these and simply grant DAV:all to the *list* of principals
+          who you consider to be owners.  I think the UNIX owner model is
+          unnecessarily limiting you to one owner.
+          That is, I think that copying or inheriting ACEs from the containing
+          collection is more appropriate.
+
+* What to do about inherited and protected ACEs on MOVEs? (up to impl.)
+Wilfredo: See my note above under "inheritance model" re: dangling inheritance
+          references.
+
+* What ACLs would be required for deletion?  (up to impl.)
+Brane: There are three options: DAV:write on containing directory (that's
+       the Unix way, and consistent with our directory structuring),
+       DAV:write on the object (that's close to the Windows way),
+       or DAV:owner on the object.
+Wilfredo: DAV:unbind on the parent.
+
+* Can the repository structure be itself unchanged with only modifications
+  contained within ra_dav and mod_dav_svn?
+Justin says: Just might be possible.  If Subversion implemented the ACLs
+             and related items as simple properties on the file, this
+             approach may work as mod_dav/mod_dav_svn handles enforcement.
+Brane says: Even if it's possible, it's evil. Access control must be part
+            of the FS semantics in order to behave the same across all
+            RA layers.
+
+===Answered questions===
+
+* Can Subversion handle the principal data model?  That is, can it enumerate
+  what users it recognizes.  Similarly, can we represent the groups in a
+  controlled fashion?
+Justin: Isn't the concept of a user foreign to Subversion?  Indeed, Greg says
+        it is.  So, mod_dav would have to introduce a model to map backend
+        authentication models and present a unified principal model.  Still,
+        work would have to be done in Apache httpd to achieve this.  But,
+        storage of users doesn't occur with SVN.  All SVN would receive is an
+        authenticated username.
+Brane: Agreed. But note that there must be a mapping between WebDAV
+       principals and Subversion users that is compatible for different
+       access methods. Note also that the concept of groups is important
+       for generating sane ACLs, yet the FS must also know the actual
+       user. It seems that a user->list-of-groups mapping has to be
+       available to the FS somehow.
+Wilfredo: Note also that DAV principals must be exposed as HTTP resources as
+          well; a principal collection is going to want to live somewhere in
+          the repository namespace unless there's a way to put it somewhere
+          else on the HTTP server.
+          On the other hand, if you are parking a repository on a server which
+          also has non-svn DAV resources, there probably should be a way to
+          share the principals, which implies they should be managed by mod_dav,
+          not (necessarily) in the FS layer.  Maybe this sort of sharing isn't
+          that important, though.
+
+* Given Subversion does not know about users, what sorts of ACLs could be
+  placed on other non-DAV access to the repository (say ra_local)? 
+Justin: Greg hints that ra_local doesn't use ACLs as it would be possible
+        to just bypass SVN and edit the BDB backend directly.  ACLs are
+        therefore only desired for ra_dav access.
+Brane: Nonsense. What if I, as an admin, want to administer the database
+       (and modify ACLs) using ra_local? (E.g., while Apache is down
+       for database recovery/upgrade/etc.)
+
+===Required to-do items===
+
+- Contemplate the nature of ACLs
+
+- Construct a mapping of WebDAV ACL properties and values to potential SVN
+  counterparts.
+
+- Define extensions to the mod_dav provider API that allows ACLs to be
+  implemented in a provider-neutral fashion.  mod_dav should be able to
+  handle most of the protocol logic, but it will have to retrieve certain
+  items from the provider to achieve this.
+
+- Allow mod_dav to handle principal URLs via authentication rewrite.
+  - mod_dav can be written to use these backends and expose provider URLs and
+    handle the DAV methods on them.
+
+===Completed items===
+
+- Apache httpd authentication switched to a provider model for post-2.0.42
+  releases.
+
+===30,000ft summary of WebDAV ACL draft===
+****
+Note: You are encouraged to read the draft in its entirety, but this is
+      just a rough sketch so that I can remember what is in it.
+****
+
+Principal:
+  - Single URL which identifies a person
+  - Certain DAV methods must be implemented on these URLs
+
+Privileges:
+
+- DAV:read
+  - Controls: GET/PROPFIND
+  - MAY control: OPTIONS
+- DAV:write
+  - Controls: PUT/PROPPATCH
+  - Locking interacts with it
+  - Includes DAV:write-properties and DAV:write-content (3.10)
+- DAV:write-properties
+  - Controls: PROPPATCH.
+  - Modify dead properties, but (optionally) live ones
+- DAV:write-content
+  - Controls: PUT (for existing resource)
+- DAV:bind
+  - Controls: PUT (for new resource)
+- DAV:unbind
+  - Controls: DELETE
+- DAV:unlock
+  - Controls: UNLOCK
+- DAV:read-acl
+  - Controls: PROPFIND (on DAV:acl)
+- DAV:read-current-user-privilege-set
+  - Controls: PROPFIND (on DAV:current-user-privilege-set)
+- DAV:write-acl
+  - Modify ACLs
+- DAV:all
+  - Everything
+
+Principal properties:
+- DAV:alternate-URI-set
+  - Required
+  - HREF
+  - More knowledge about principal
+- DAV:principal-URL
+  - Required
+  - Definitive singular URL
+- DAV:group-member-set (group principals)
+  - Direct members of group
+- DAV:group-membership
+  - Required
+  - What groups a principal belongs to
+
+ACL properties:
+- DAV:owner
+  - Protected
+- DAV:supported-privilege-set
+  - Protected
+  - What properties are allowed
+- DAV:current-user-privilege-set
+  - Protected
+  - Computed effective access for current principal
+- DAV:acl
+  - Collection of ACEs (see below)
+- DAV:inherited-acl-set
+  - Indicates which entities that this ACL inherits from
+- DAV:principal-collection-set
+  - Collection of principals for this server
+
+ACE properties:
+- DAV:ace
+  - Invert
+  - DAV:principal
+    - href to a principal URL
+    - DAV:all
+      - All users
+    - DAV:authenticated
+    - DAV:unauthenticated
+    - DAV:property
+      - If specified property value matches what we know, success.
+        - DAV:owner matching (?)
+    - DAV:self
+      - Only for principal URLs if authenticated as that principal
+  - grant or deny privilege:
+    - See above for ACE privileges
+  - DAV:protected
+    - Any attempt to remove this MUST fail
+  - DAV:inherited-acl-set
+    - This ACE comes from resource in href
+ 
+ACE ordering:
+- DAV:deny-before-grant
+
+Allowed ACE:
+- DAV:grant-only
+  - Deny ACEs are not supported
+- DAV:no-invert
+  - DAV:invert is not supported
+
+Required principals
+- DAV:required-principal
+  - Defines that a principal must be defined for this property ACE
+    - Usually for DAV:owner (?)
+  - This is mentioned but its usage is not defined in the RFC.  I think it
+    was meant to be removed... -wsanchez
+
+DAV methods changes:
+- OPTIONS
+  - Must return literal "access-control"
+- MOVE
+  - Must move non-inherited and non-protected ACEs from DAV:acl
+- COPY
+  - Permissions must not be copied.  Default ACL may apply.
+  - If wish to preserve ACL, retrieve before COPY, then reapply ACLs.
+- DELETE
+- LOCK
+  - Only lock owner may modify ACEs
+
+Access control methods:
+- ACL
+  - Allows updating of ACLs
+
+Reporting:
+- REPORT
+  - Must support DAV:expand-property
+- DAV:acl-principal-prop-set 
+  - Required
+  - Returns property requested for all principals
+    - Client access?
+- DAV:principal-match
+  - Required
+  - Lists which ACEs you are the principal on
+- DAV:principal-property-search
+  - Required
+  - Does a search for principals who match the criteria
+- DAV:principal-search-property-set
+  - Required
+  - Returns what properties may be searched on DAV:principal-property-search

Propchange: subversion/trunk/notes/http-and-webdav/webdav-acl-notes
------------------------------------------------------------------------------
    svn:eol-style = native

Added: subversion/trunk/notes/http-and-webdav/webdav-general-summary
URL: http://svn.apache.org/viewvc/subversion/trunk/notes/http-and-webdav/webdav-general-summary?rev=900584&view=auto
==============================================================================
--- subversion/trunk/notes/http-and-webdav/webdav-general-summary (added)
+++ subversion/trunk/notes/http-and-webdav/webdav-general-summary Mon Jan 18 22:00:43 2010
@@ -0,0 +1,446 @@
+
+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.
+
+
+
+

Propchange: subversion/trunk/notes/http-and-webdav/webdav-general-summary
------------------------------------------------------------------------------
    svn:eol-style = native

Added: subversion/trunk/notes/http-and-webdav/webdav-protocol
URL: http://svn.apache.org/viewvc/subversion/trunk/notes/http-and-webdav/webdav-protocol?rev=900584&view=auto
==============================================================================
--- subversion/trunk/notes/http-and-webdav/webdav-protocol (added)
+++ subversion/trunk/notes/http-and-webdav/webdav-protocol Mon Jan 18 22:00:43 2010
@@ -0,0 +1,379 @@
+This file documents Subversion's use of the WebDAV/DeltaV protocol.
+
+
+IMPORTANT RFCs and LINKS
+========================
+
+  * RFC 2518  (WebDAV)
+
+  * RFC 3253  (DeltaV)
+
+  * Subversion's limited uses of DeltaV, as well as interoperability
+    issues, are explained in the "WebDAV" appendix of the free
+    Subversion book (at http://svnbook.red-bean.com)
+
+
+
+
+HTTP METHODS USED, indexed by svn commands that access network
+==============================================================
+
+
+Read Commands  :  (OPTIONS, PROPFIND, GET, REPORT)
+-------------
+
+  Most commands have to resolve peg-revisions before starting:
+
+  * -r X foo@Y      REPORT                        ('get-locations')
+
+       ...if an old server doesn't support 'get-locations' report, the
+       client traces history using the 'log-report' instead.
+
+  And any command which has to convert a date to a revision:
+
+  * -r {DATE}       REPORT                        ('dated-rev-report')
+
+
+  The following group of commands all use the custom 'update-report'
+  request, which is just a fancy way of driving svn_repos_dir_delta():
+
+  * svn checkout / svn export / svn update:
+   (do_update RA interface)
+
+     ra_neon:       PROPFIND, REPORT              ('update-report' w/send-all)
+
+     ra_serf:       PROPFIND, REPORT              ('update-report')
+                    ... then many PROPFIND/GETs on many parallel connections
+
+    svn update only                               ('merge-info-report')
+
+  * svn switch:     OPTIONS, PROPFIND, REPORT     ('update-report',
+                                                   'merge-info-report')
+
+  * svn diff:       OPTIONS, PROPFIND, REPORT     ('update-report')
+                    ... then many GETs
+
+  * svn merge:      OPTIONS, PROPFIND, REPORT     ('update-report',
+                                                   'merge-info-report')
+                    ... then many GETs
+
+  * svn status -u:  OPTIONS, PROPFIND, REPORT     ('update-report' and
+                                                   'get-locks-report')
+
+  * svn cp URL wc:  OPTIONS, PROPFIND, REPORT     ('update-report')
+                    (this is just like checkout)
+
+
+  And these guys are left over:
+
+  * svn log:        OPTIONS, PROPFIND, REPORT     ('log-report')
+
+  * svn blame:      OPTIONS, PROPFIND, REPORT     ('file-revs-report')
+                    [older clients use GET
+                     and different REPORT]        ('log-report')
+
+  * svn ls:         PROPFIND
+
+  * svn ls -v:      PROPFIND, REPORT              ('get-locks-report')
+
+  * svn cat:        PROPFIND, GET
+
+  * svn info URL:   PROPFIND
+
+  * svn plist URL:  PROPFIND
+
+  * svn pget URL:   PROPFIND
+ 
+
+
+
+Write Commands  :  (MKACTIVITY, PROPPATCH, PUT, CHECKOUT, MKCOL, MOVE,
+--------------      COPY, DELETE, LOCK, UNLOCK, MERGE)
+
+  With the exception of LOCK/UNLOCK, every write command performs some
+  sort of DeltaV commit operation.  In DeltaV, a commit always starts
+  by creating a transaction (MKACTIVITY), applies a log message
+  (PROPPATCH), does some other write methods, and then ends by
+  committing the transaction (MERGE).  If the MERGE fails, the client
+  may try to remove the transaction with a DELETE.
+
+  * svn commit:
+     ra_neon:       OPTIONS, PROPFIND, MKACTIVITY, 
+                    {CHECKOUT, COPY, MOVE, DELETE, PROPPATCH, PUT, MKCOL},
+                    MERGE (DELETE)
+
+     ra_serf:       OPTIONS to acquire activity collection set
+     (no major      MKACTIVITY to a unique UUID relative to activity set
+      differences)  PROPFIND to get what we think our baseline is
+                    CHECKOUT of baseline revision into activity
+                    Setting log: PROPPATCH on root directory
+                    Delete a file: CHECKOUT file / DELETE
+                    Add a dir:  MKCOL
+                    Add a file: CHECKOUT parent dirs / PUT raw-file
+                    Edit a file: CHECKOUT file / PUT svndiff stream
+                    End commit: MERGE activity, DELETE activity
+
+  * svn import:     OPTIONS, PROPFIND, MKACTIVITY,
+                    {PROPPATCH, PUT, MKCOL},
+                    MERGE (DELETE)
+
+  * svn lock:       PROPFIND, LOCK
+  
+  * svn unlock:     PROPFIND, UNLOCK
+
+  * svn cp URL URL: OPTIONS, PROPFIND, MKACTIVITY, PROPPATCH,
+                    COPY, MERGE.  (DELETE)
+
+  * svn mv URL URL: OPTIONS, PROPFIND, MKACTIVITY, PROPPATCH,
+                    COPY, DELETE, MERGE.  (DELETE)
+
+  * svn rm URL:     OPTIONS, PROPFIND, MKACTIVITY, PROPPATCH, DELETE, MERGE.
+
+  * svn mkdir URL:  OPTIONS, PROPFIND, MKACTIVITY, PROPPATCH, MKCOL, MERGE.
+
+  * svn pset --revprop:  PROPPATCH
+
+Remembering Our Location
+========================
+
+For a file in our WC, both ra_serf and ra_neon will store the checked-in href
+(where the original text-base and properties can be found) in the
+svn:wc:ra_dav:version-url wcprop.
+
+Example property:
+  svn:wc:ra_dav:version-url -> /repos/test/!svn/ver/2/httpd/configure
+
+GET
+===
+
+ra_serf
+-------
+
+For a file that a WC already has when it wants to do an update, ra_serf will
+send two extra headers:
+
+  X-SVN-VR-Base: <checked-in href of locally-present file>
+  Accept-Encoding: svndiff1;q=0.9,svndiff;q=0.8
+
+The server may choose not to return svndiff content but return full-text.
+
+(ra_neon has this same functionality, but is largely just dead code.)
+
+Example
+-------
+
+Request:
+
+  GET /repos/test/!svn/ver/3/httpd/configure HTTP/1.1
+  X-SVN-VR-Base: /repos/test/!svn/ver/2/httpd/configure
+  Accept-Encoding: svndiff1;q=0.9,svndiff;q=0.8
+
+Response:
+
+  HTTP/1.1 200 OK
+  ETag: "3//httpd/configure"
+  Vary: Accept-Encoding
+  Content-Type: application/vnd.svn-svndiff
+  
+  ...svn-svndiff stream that can be passed to svn_txdelta_parse_svndiff...
+
+Custom REPORTs
+==============
+
+We use a bunch of custom reports, here's a little info on what they look like.
+
+update-report
+-------------
+
+Purpose: Present what we have in our WC to the server and let it tell us what
+         has changed.  Has an optional 'send-all' attribute that will include
+         the text-deltas in base64-encoding inline to the XML REPORT response.
+
+Target URL: Base VCC URL
+            Example: REPORT /repos/test/!svn/vcc/default
+
+Note: ra_serf will not set the send-all attribute to the update-report.  It
+      will instead take the returned D:checked-in href and do a pipelined
+      PROPFIND / GET on that resource.
+
+Note: If a client had a previous revision, it would not send the 'start-empty'
+      attribute to entry.
+
+Request:
+
+  <S:update-report send-all="true" xmlns:S="svn:">
+    <S:src-path>http://localhost:8080/repos/test/httpd/support</S:src-path>
+    <S:target-revision>2</S:target-revision>
+    <S:entry rev="2"  start-empty="true"></S:entry>
+  </S:update-report>
+
+Response:
+
+<S:update-report xmlns:S="svn:" xmlns:V="..." xmlns:D="DAV:" send-all="true">
+  <S:target-revision rev="2"/>
+  <S:open-directory rev="2">
+    <D:checked-in>
+      <D:href>/repos/test/!svn/ver/2/httpd/support</D:href>
+    </D:checked-in>
+    <S:set-prop name="svn:entry:committed-rev">2</S:set-prop>
+    ... more set props ...
+    <S:add-file name="ab.c">
+      <D:checked-in>
+        <D:href>/repos/test/!svn/ver/2/httpd/support/ab.c</D:href>
+      </D:checked-in>
+      <S:set-prop name="svn:entry:committed-rev">2</S:set-prop>
+      ... more set props for the file ...
+      <S:txdelta>...base64-encoded file content...</S:txdelta>
+    </S:add-file>
+    <S:add-directory name="os" bc-url="/repos/test/!svn/bc/2/httpd/os">
+      <D:checked-in>
+        <D:href>/repos/test/!svn/ver/2/httpd/os</D:href>
+      </D:checked-in>
+      ...directory contents...
+    </S:add-directory>
+  </S:open-directory>
+</S:update-report>
+
+dated-rev-report
+----------------
+
+Purpose: Get the revision associated with a particular date.
+
+Target URL: VCC URL for repos.
+
+Request:
+
+  <S:dated-rev-report xmlns:S="svn:" xmlns:D="DAV:">
+    <D:creationdate>2005-12-07T13:06:26.034802Z</D:creationdate>
+  </S:dated-rev-report>
+
+Response:
+
+  <S:dated-rev-report xmlns:S="svn:" xmlns:D="DAV:">
+    <D:version-name>4747</D:version-name>
+  </S:dated-rev-report>
+
+get-locks-report
+----------------
+
+Purpose: Get the locks associated with a particular resource.
+
+Target URL: URL of item we're getting the locks for
+
+Request:
+
+  <S:get-locks-report xmlns:S="svn">
+  </S:get-locks-report>
+
+Response:
+
+  <S:get-locks-report xmlns:S="svn">
+    <S:lock>
+      <S:path>/foo/bar/baz</S:path>
+      <S:token>opaquelocktoken:706689a6-8cef-0310-9809-fb7545cbd44e</S:token>
+      <S:owner>fred</S:owner>
+      <S:comment encoding="base64">ET39IGCB93LL4M</S:comment>
+      <S:creationdate>2005-02-07T14:17:08Z</S:creationdate>
+      <S:expirationdate>2005-02-08T14:17:08Z</S:expirationdate>
+    </S:lock>
+  </S:get-locks-report>
+
+get-locations
+-------------
+
+Purpose: Get the location of a path appearing in a particular revision.
+
+Target URL: Current baseline collection for a directory plus relative paths.
+            Example: REPORT /repos/test/!svn/bc/5/httpd
+
+Request:
+ 
+  <S:get-locations xmlns:S="svn:">
+    <S:path></S:path>
+    <S:peg-revision>5</S:peg-revision>
+    <S:location-revision>1</S:location-revision>
+  </S:get-locations>
+
+Response:
+
+  <?xml version="1.0" encoding="utf-8"?>
+  <S:get-locations-report xmlns:S="svn:" xmlns:D="DAV:">
+    <S:location rev="1" path="/httpd"/>
+  </S:get-locations-report>
+
+log-report
+----------
+
+Purpose: Retrieve the log for a portion of the repository.
+
+Target URL: Current baseline collection for a directory plus relative paths.
+            Example: REPORT /repos/test/!svn/bc/5/httpd/support
+
+Request:
+
+  <S:log-report xmlns:S="svn:">
+    <S:start-revision>2</S:start-revision>
+    <S:end-revision>2</S:end-revision>
+    <S:limit>1</S:limit> (optional)
+    <S:discover-changed-paths/> (optional)
+    <S:strict-node-history/> (optional)
+    <S:include-merged-revisions/> (optional)
+    <S:revprop>REVPROP</S:revprop>... | <S:all-revprops/> | <S:no-revprops/>
+      ('revprop', 'all-revprops', and 'no-revprops' are all optional)
+    <S:path></S:path>... (optional)
+  </S:log-report>
+
+Response:
+
+  <?xml version="1.0" encoding="utf-8"?>
+  <S:log-report xmlns:S="svn:" xmlns:D="DAV:">
+    <S:log-item>
+      <D:version-name>2</D:version-name>
+      <S:creator-displayname>bob</S:creator-displayname>
+      <S:date>2006-02-27T18:44:26.149336Z</S:date>
+      <D:comment>Add doo-hickey</D:comment>
+      <S:revprop name="REVPROP">value</S:revprop>... (optional)
+      <S:has-children/> (optional)
+      <S:added-path( copyfrom-path="PATH" copyfrom-rev="REVNUM">PATH</S:added-path>... (optional)
+      <S:replaced-path( copyfrom-path="PATH" copyfrom-rev="REVNUM">PATH</S:replaced-path>... (optional)
+      <S:deleted-path>PATH</S:deleted-path>... (optional)
+      <S:modified-path>PATH</S:modified-path>... (optional)
+    </S:log-item>
+    ...multiple log-items for each returned revision...
+  </S:log-report>
+
+mergeinfo-report
+----------------
+
+Purpose: Retrieve the merge history for a portion of the repository
+(e.g. a set of paths) at a particular revision.
+
+Target URL: URL of item we're getting merge info for.
+
+Note: <S:inherit> is a representation of the svn_mergeinfo_inheritance_t
+      struct and can have the values 'explicit', 'inherited', or
+      'nearest-ancestor'.  The default value is 'explicit' if <S:inherit>
+      is not present or has any other value than those three. 
+
+      <S:include-descendants> represents the 'include_descendants'
+      boolean argument to svn_ra_get_mergeinfo().  It can be 'yes' or
+      'no'; the default value is 'no' (mapping to FALSE).
+
+Request:
+
+  <S:mergeinfo-report xmlns:S="svn:">
+    <S:revision>1</S:revision>
+    <S:inherit>inherited</S:inherit>
+    <S:include-descendants>yes</S:include-descendants>
+    <S:path>/A/B/E/alpha</S:path>
+  </S:mergeinfo-report>
+
+Response:
+
+  <?xml version="1.0" encoding="utf-8"?>
+  <S:mergeinfo-report xmlns:S="svn:" xmlns:D="DAV:">
+    <S:mergeinfo-item>
+      <S:mergeinfo-path>/A_COPY/B/E</S:mergeinfo-path>
+      <S:mergeinfo-info>/A/B/E:1,3-4</S:mergeinfo-info>
+    </S:mergeinfo-item>
+  </S:mergeinfo-report>

Propchange: subversion/trunk/notes/http-and-webdav/webdav-protocol
------------------------------------------------------------------------------
    svn:eol-style = native

Added: subversion/trunk/notes/http-and-webdav/webdav-proxy
URL: http://svn.apache.org/viewvc/subversion/trunk/notes/http-and-webdav/webdav-proxy?rev=900584&view=auto
==============================================================================
--- subversion/trunk/notes/http-and-webdav/webdav-proxy (added)
+++ subversion/trunk/notes/http-and-webdav/webdav-proxy Mon Jan 18 22:00:43 2010
@@ -0,0 +1,89 @@
+Purpose: A master/slave server replication model for Subversion WebDAV-based
+transactions.
+
+Some or all clients interact with a slave server, but the slave transparently
+passes all of the write-oriented activites to the master (rewriting the
+content as necessary).  The slaves are essentially read-only, but they
+do have a complete copy of the repository locally.  This serves to
+alleviate read traffic from the master server, and may dramatically
+speed up read operations, if a slave is sited closer to the users.
+
+This model has several advantages to using a straight HTTP DAV-aware
+caching proxy, in that each slave can respond to all read-only requests
+without ever having to relay them to the master backend.
+
+Proxy server requirements:
+  Subversion 1.5 or newer
+  Apache HTTP Server 2.2.0 or higher with at least mod_proxy,
+  mod_proxy_http, mod_dav, and mod_dav_svn enabled
+  (Several fixes to mod_proxy were committed for this patch that
+  were not backported to the 2.0 branch of httpd.)
+
+Example configuration:
+
+Participants:
+  Slave  -> slave.example.com  (there can be many!)
+  Master -> master.example.com (there can only be one!)
+  A WebDAV client (ra_neon, ra_serf, other WebDAV clients)
+
+Each client does:
+
+ % svn co http://slave.example.com/repos/slave/
+ ...
+ % svn ci
+ % ...etc...
+
+ (The client can perform all operations as normal.)
+
+Each slave has:
+
+<Location /repos/slave>
+  DAV svn
+  SVNPath /my/local/copy/of/repos
+  SVNMasterURI http://master.example.com/repos/master
+</Location>
+
+The master:
+
+The master MUST have a post-commit hook that updates all of the slaves.  An
+example that does this using 'svnadmin dump'/'svnadmin load' and ssh is
+provided below.  svnsync can be used instead, but is left as an exercise to
+the reader.
+
+Note that if revprop changes are permitted via a pre-revprop-change
+hook (which is not true by default), a post-revprop-change hook is
+needed as well, to propagate those changes to slaves.
+
+Additionally, if locks are permitted on the master repository, lock databases
+need to kept in sync via post-lock and post-unlock hooks on the master pushing
+the lock state to the slaves.  (Username preservation is left as an exercise to
+the reader.)  If the lock database is not propagated, users will not be able to
+accurately determine whether a lock is held - but locking will still work.
+
+----
+#!/bin/sh
+REPOS="$1"
+REV="$2"
+SLAVE_HOST=slave.example.com
+SLAVE_PATH=/my/local/copy/of/repos
+
+# Ensure svnadmin is in your PATH on both this machine and the remote server!
+svnadmin dump --incremental -q -r"$REV" "$REPOS" |
+  ssh $SLAVE_HOST "svnadmin load -q $SLAVE_PATH"
+----
+
+Issues/Thoughts:
+- The master maybe should update the slaves using a DAV commit of its own.
+  (essentially replay the commit once it is approved).  This requires
+  a way to inject commits/user to the slave.  But, this would eliminate the
+  reliance on post-commit hooks.
+- This isn't multi-master replication.  The slave won't accept commits
+  on its own.  If the master can't be contacted for a write operation, it
+  will return a proxy error.  (Multi-master == distributed repositories.)
+- Remove the location_filter for the header.  I believe mod_proxy does this
+  for us already.  We may just be duplicating things.  We will still have
+  to rewrite the bodies of the requests/responses though.
+  Apache-2.2.11's mod_proxy does no such Location Header fixing may be
+  the Later versions could.
+- Determine a better way to handle the MERGE call.  It's the only operation
+  that doesn't occur on the activity URL.

Propchange: subversion/trunk/notes/http-and-webdav/webdav-proxy
------------------------------------------------------------------------------
    svn:eol-style = native



Mime
View raw message