Subject: feedback on rfc2518bis-14: locking

From: Manfred Baedke <[email-masked]>
Date: Fri, 31 Mar 2006 17:05:50 +0200

Since I criticized the sections 6 and 7 in previous mails, I think I 
should make a proposal for the normative parts of them (which should
of course be completed by examples and, possibly, some non-normative
explanations). Note that almost all subsections of sections 7 are 
removed, which is really meant this way.

6.  Locking

    The ability to lock a resource provides a mechanism for serializing
    access to that resource.  Using a lock, an authoring client can
    provide a reasonable guarantee that another principal will not modify
    a resource while it is being edited.  In this way, a client can
    prevent the "lost update" problem.

    This specification allows locks to vary over two client-specified
    parameters, the number of principals involved (exclusive vs. shared)
    and the type of access to be granted.  This document defines locking
    for only one access type, write.  However, the syntax is extensible,
    and permits the eventual specification of locking for other access
    types.

6.1.  Lock Model

   This section provides a concise model for how locking behaves.  Later
   sections will provide more detail on some of the concepts and refer
   back to these model statements.  Normative statements related to LOCK
   and UNLOCK handling can be found in the sections on those methods,
   whereas normative statements that cover any method are gathered here.

   1.  A lock either directly or indirectly locks a resource.

   2.  A resource becomes directly locked when a LOCK request to an URL
       of that resource creates a new lock.  The "lock-root" of the new
       lock is that URL.  If at the time of the request, the URL is not
       mapped to a resource, a new empty resource is created and
       directly locked.

   3.  A lock is either exclusive or shared. An exclusive lock conflicts
       with any other kind of lock on the same resource, whether either
       lock is direct or indirect.  A server MUST NOT create conflicting
       locks on a resource.

   4.  If a collection C is locked with an infinite depth lock L, the set
       of resources that are indirectly locked by L is exactly the set 

       of member resources of C:

       *  If a new element is added to the set of member resources of
          the collection, then the new member resource MUST become
          indirectly locked by L.

       *  If a recource is removed from the set of member resources of
          the collection, then the resource MUST no longer be indirectly
          locked by L.

   5.  Each lock is identified by a single unique lock token
       (Section 6.3).

   6.  An UNLOCK request deletes the lock with the specified lock token.
       After a lock is deleted, no resource is locked by that lock.

   7.  A lock token is "submitted" in a request when it appears in an If
       header (the Write Lock section (Section 7) discusses when token
       submission is required for write locks).

   8.  Any operation which causes the lock-root of a lock to become an
       unmapped URL MUST delete the lock.

6.2.  Lock Creator

   The lock creator is the authenticated principal who issued the request
   that created the lock.

   When submission of a lock token is required to perform an operation,
   a server MUST check that the authenticated principal matches the lock
   creator.

6.3.  Lock Tokens

   A lock token is a type of state token which identifies a particular
   lock.  Each lock has exactly one unique lock token generated by the
   server.  Clients MUST NOT attempt to interpret lock tokens in any
   way.

   Lock token URIs MUST be unique across all resources for all time.

   Servers MAY make lock tokens publicly readable (e.g. in the DAV:
   lockdiscovery property).  One use case for making lock tokens
   readable is so that a long-lived lock can be deleted by the resource
   owner (the client that issued the lock request might have crashed or
   disconnected before deleting the lock).  Except for the case of
   using UNLOCK (Section 9.11) under user guidance, a client SHOULD NOT
   use a lock token created by another client instance.

   This specification encourages servers to create UUIDs for lock
   tokens, and to use the URI form defined by "A Universally Unique
   Identifier (UUID) URN Namespace" ([RFC4122]).  However servers are
   free to use any URI (e.g. from another scheme) so long as it meets
   the uniqueness requirements.  For example, a valid lock token might
   be constructed using the "opaquelocktoken" scheme defined in
   Appendix C.

   Example: "urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6"

6.4.  Lock Timeout

   A lock MAY have a limited lifetime.  The lifetime is suggested by the
   client when creating or refreshing the lock, but the server
   ultimately chooses the timeout value. Timeout is measured in seconds
   remaining until lock expiration.

   The timeout counter MUST be restarted if a refresh LOCK request is
   successful (see Section 9.10.2).  The timeout counter SHOULD NOT be
   restarted at any other time.

   If the timeout expires then the lock SHOULD be deleted. In this case
   the server SHOULD act as if an UNLOCK request (Section 9.11) was
   successfully performed with the lock token of the timed-out
   lock being submitted.

   A client MUST NOT assume that just because the time-out has expired
   the lock has immediately been deleted.

   Clients MUST assume that locks can arbitrarily disappear at any time,
   regardless of the value given in the Timeout header.
   For example, a sufficiently privileged user may delete a lock at any
   time or the system may crash in such a way that it loses the record
   of the lock's existence.

6.5.  Lock Capability Discovery

   Since server lock support is optional, a client trying to lock a
   resource on a server can either try the lock and hope for the best,
   or perform some form of discovery to determine what lock capabilities
   the server supports.  This is known as lock capability discovery. A
   client can determine what lock types the server supports by
   retrieving the DAV:supportedlock property.

   Any resource that supports the LOCK method MUST support the
   DAV:supportedlock property.

6.8.  Active Lock Discovery

   If another principal locks a resource that a principal wishes to
   access, it is useful for the second principal to be able to find out
   who the first principal is.  For this purpose the DAV:lockdiscovery
   property is provided.  This property contains a (not necessarily
   complete) list of locks that lock the given resource, describes
   their types, and MAY even provide the lock tokens.

   Any resource that supports the LOCK method MUST support the
   DAV:lockdiscovery property.

7.  Write Lock

   This section describes the semantics specific to the write lock type.
   The write lock is a specific instance of a lock type, and is the only
   lock type described in this specification.

7.1 Write Locks and the Lockable State of a Resource

   The lockable state of a resource consists of

    * the content of the resource

    * a set of name-value pairs, containing the names and values of the
      unprotected properties of a resource (the notion of a protected
      property is defined in section 15)

    * the set of internal members of the resource

   If a resource is locked by a write lock L, a request that would change
   the lockable state of this resource MUST fail if the lock token of
   L has not been submitted with the request or if the request was not
   issued by the lock creator of L.