Web Distributed Authoring and Versioning (WebDAV) Locking Protocol

At present, this specification only defines one lock type, the write lock.¶

DAV:lockdiscovery property for a resource that has two shared write locks on it, with infinite timeouts:

   <D:lockdiscovery xmlns:D="DAV:">
     <D:activelock>
       <D:locktype><D:write/></D:locktype>
       <D:lockscope><D:shared/></D:lockscope>
       <D:depth>0</D:depth>
       <D:owner>Jane Smith</D:owner>
       <D:timeout>Infinite</D:timeout>
       <D:locktoken>
         <D:href
   >opaquelocktoken:f81de2ad-7f3d-a1b2-4f3c-00a0c91a9d76</D:href>
       </D:locktoken>
       <D:lockroot>
         <D:href
   >http://example.com/container/</D:href>
       </D:lockroot>
     </D:activelock>
   </D:lockdiscovery>
   <D:lockdiscovery>
     <D:activelock>
       <D:locktype><D:write/></D:locktype>
       <D:lockscope><D:shared/></D:lockscope>
       <D:depth>0</D:depth>
       <D:owner>John Doe</D:owner>
       <D:timeout>Infinite</D:timeout>
       <D:locktoken>
         <D:href
   >opaquelocktoken:f81de2ad-7f3d-a1b2-4f3c-00a0c91a9d77</D:href>
       </D:locktoken>
       <D:lockroot>
         <D:href
   >http://example.com/container/</D:href>
       </D:lockroot>
     </D:activelock>
   </D:lockdiscovery>

DAV:lockdiscovery property for a resource with no locks on it:

   <D:lockdiscovery xmlns:D="DAV:"/>

DAV:supportedlock property for a resource that supports both exclusive and shares write locks:

   <D:supportedlock xmlns:D="DAV:">
     <D:lockentry>
       <D:lockscope><D:exclusive/></D:lockscope>
       <D:locktype><D:write/></D:locktype>
     </D:lockentry>
     <D:lockentry>
       <D:lockscope><D:shared/></D:lockscope>
       <D:locktype><D:write/></D:locktype>
     </D:lockentry>
   </D:supportedlock>

DAV:supportedlock property for a resource that doesn't support any locks at all:

   <D:supportedlock xmlns:D="DAV:"/>

In section 9.8, [RFC2518] specifies that locks should be refreshed implicitly every time "...any time an owner of the lock sends a method to any member of the lock, including unsupported methods, or methods which are unsuccessful." This features has been removed (locks need to be refreshed explicitly using the LOCK method).¶

Compatibility considerations ¶

• Clients historically have never relied on this feature as it was never implemented in widely deployed WebDAV servers.

In section 7.4, [RFC2518] specifies a special resource type called "lock-null resource" that's being created when a LOCK method request is applied to a null resource. In practice, no real interoperability was achieved because many servers failed to implement this feature properly and few clients (if any) ever relied on that particular functionality.¶

Removing this feature also means that there is no atomic way to create a collection in locked state, but in practice, this doesn't seem to be a problem.¶

Compatibility considerations ¶

• There do not seem to be any widely deployed clients that actually relied on "lock-null resources".

Clients can take advantage of the new DAV:lockroot element to discover the URL to which the LOCK request (that created the lock) was applied.¶

Compatibility consideration ¶

• Clients will have to fail gracefully when communicating with older servers that do not support the new property.

The most basic form of lock is an exclusive lock. This is a lock where the access right in question is only granted to a single principal. The need for this arbitration results from a desire to avoid having to merge results.¶

However, there are times when the goal of a lock is not to exclude others from exercising an access right but rather to provide a mechanism for principals to indicate that they intend to exercise their access rights. Shared locks are provided for this case. A shared lock allows multiple principals to receive a lock. Hence any principal with appropriate access can get the lock.¶

With shared locks there are two trust sets that affect a resource. The first trust set is created by access permissions. Principals who are trusted, for example, may have permission to write to the resource. Among those who have access permission to write to the resource, the set of principals who have taken out a shared lock also must trust each other, creating a (typically) smaller trust set within the access permission write set.¶

Starting with every possible principal on the Internet, in most situations the vast majority of these principals will not have write access to a given resource. Of the small number who do have write access, some principals may decide to guarantee their edits are free from overwrite conflicts by using exclusive write locks. Others may decide they trust their collaborators will not overwrite their work (the potential set of collaborators being the set of principals who have write permission) and use a shared lock, which informs their collaborators that a principal may be working on the resource.¶

The WebDAV extensions to HTTP do not need to provide all of the communications paths necessary for principals to coordinate their activities. When using shared locks, principals may use any out of band communication channel to coordinate their work (e.g., face-to-face interaction, written notes, post-it notes on the screen, telephone conversation, Email, etc.) The intent of a shared lock is to let collaborators know who else may be working on a resource.¶

Shared locks are included because experience from web distributed authoring systems has indicated that exclusive locks are often too rigid. An exclusive lock is used to enforce a particular editing process: take out an exclusive lock, read the resource, perform edits, write the resource, release the lock. This editing process has the problem that locks are not always properly released, for example when a program crashes, or when a lock owner leaves without unlocking a resource. While both timeouts and administrative action can be used to remove an offending lock, neither mechanism may be available when needed; the timeout may be long or the administrator may not be available.¶

A WebDAV compliant server is not required to support locking in any form. If the server does support locking it may choose to support any combination of exclusive and shared locks for any access types.¶

The reason for this flexibility is that locking policy strikes to the very heart of the resource management and versioning systems employed by various storage repositories. These repositories require control over what sort of locking will be made available. For example, some repositories only support shared write locks while others only provide support for exclusive write locks while yet others use no locking at all. As each system is sufficiently different to merit exclusion of certain locking features, this specification leaves locking as the sole axis of negotiation within WebDAV.¶

A lock token is a type of state token, represented as a URI, which identifies a particular lock. A lock token is returned by every successful LOCK operation in the DAV:lockdiscovery property in the response body, and can also be found through lock discovery on a resource.¶

Lock token URIs MUST be unique across all resources for all time. This uniqueness constraint allows lock tokens to be submitted across resources and servers without fear of confusion.¶

This specification provides a lock token URI scheme called "opaquelocktoken" that meets the uniqueness requirements. However resources are free to return any URI scheme so long as it meets the uniqueness requirements.¶

Submitting a lock token provides no special access rights. Anyone can find out anyone else's lock token by performing lock discovery. Locks MUST be enforced based upon whatever authentication mechanism is used by the server, not based on the secrecy of the token values.¶

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. Lock capability discovery differs from discovery of supported access control types, since there may be access control types without corresponding lock types. A client can determine what lock types the server supports by retrieving the DAV:supportedlock property.¶

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

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 lists all outstanding locks, describes their type, and where available, provides their lock token.¶

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

• Two clients A and B are interested in editing the resource 'index.html'. Client A is an HTTP client rather than a WebDAV client, and so does not know how to perform locking.
• Client A doesn't lock the document, but does a GET and begins editing.
• Client B does LOCK, performs a GET and begins editing.
• Client B finishes editing, performs a PUT, then an UNLOCK.
• Client A performs a PUT, overwriting and losing all of B's changes.

There are several reasons why the WebDAV protocol itself cannot prevent this situation. First, it cannot force all clients to use locking because it must be compatible with HTTP clients that do not comprehend locking. Second, it cannot require servers to support locking because of the variety of repository implementations, some of which rely on reservations and merging rather than on locking. Finally, being stateless, it cannot enforce a sequence of operations like LOCK / GET / PUT / UNLOCK.¶

WebDAV servers that support locking can reduce the likelihood that clients will accidentally overwrite each other's changes by requiring clients to lock resources before modifying them. Such servers would effectively prevent HTTP 1.0 and HTTP 1.1 clients from modifying resources.¶

WebDAV clients can be good citizens by using a lock / retrieve / write /unlock sequence of operations (at least by default) whenever they interact with a WebDAV server that supports locking.¶

HTTP 1.1 clients can be good citizens, avoiding overwriting other clients' changes, by using entity tags in If-Match headers with any requests that would modify resources.¶

Information managers may attempt to prevent overwrites by implementing client-side procedures requiring locking before modifying WebDAV resources.¶

A write lock MUST prevent a principal without the lock from successfully executing a PUT, POST, PROPPATCH, LOCK, UNLOCK, MOVE, DELETE, or MKCOL on the locked resource. All other current methods, GET in particular, function independently of the lock.¶

Note, however, that as new methods are created it will be necessary to specify how they interact with a write lock.¶

A successful request for an exclusive or shared write lock MUST result in the generation of a unique lock token associated with the requesting principal. Thus if five principals have a shared write lock on the same resource there will be five lock tokens, one for each principal.¶

While those without a write lock may not alter a property on a resource it is still possible for the values of live properties to change, even while locked, due to the requirements of their schemas. Only dead properties and live properties defined to respect locks are guaranteed not to change while write locked.¶

A write lock on a collection, whether created by a "Depth: 0" or "Depth: infinity" lock request, prevents the addition or removal of member URIs of the collection by non-lock owners. As a consequence, when a principal issues a PUT or POST request to create a new resource under a URI which needs to be an internal member of a write locked collection to maintain HTTP namespace consistency, or issues a DELETE to remove a resource which has a URI which is an existing internal member URI of a write locked collection, this request MUST fail if the principal does not have a write lock on the collection.¶

However, if a write lock request is issued to a collection containing member URIs identifying resources that are currently locked in a manner which conflicts with the write lock, the request MUST fail with a 423 (Locked) status code.¶

If a lock owner causes the URI of a resource to be added as an internal member URI of a locked collection then the new resource MUST be automatically added to the lock. This is the only mechanism that allows a resource to be added to a write lock. Thus, for example, if the collection /a/b/ is write locked and the resource /c is moved to /a/b/c then resource /a/b/c will be added to the write lock.¶

If a user agent is not required to have knowledge about a lock when requesting an operation on a locked resource, the following scenario might occur. Program A, run by User A, takes out a write lock on a resource. Program B, also run by User A, has no knowledge of the lock taken out by Program A, yet performs a PUT to the locked resource. In this scenario, the PUT succeeds because locks are associated with a principal, not a program, and thus program B, because it is acting with principal A's credential, is allowed to perform the PUT. However, had program B known about the lock, it would not have overwritten the resource, preferring instead to present a dialog box describing the conflict to the user. Due to this scenario, a mechanism is needed to prevent different programs from accidentally ignoring locks taken out by other programs with the same authorization.¶

In order to prevent these collisions a lock token MUST be submitted by an authorized principal in the If header for all locked resources that a method may interact with or the method MUST fail. For example, if a resource is to be moved and both the source and destination are locked then two lock tokens must be submitted, one for the source and the other for the destination.¶

A COPY method invocation MUST NOT duplicate any write locks active on the source. However, as previously noted, if the COPY copies the resource into a collection that is locked with "Depth: infinity", then the resource will be added to the lock.¶

A successful MOVE request on a write locked resource MUST NOT move the write lock with the resource. However, the resource is subject to being added to an existing lock at the destination, as specified in Appendix B.3.4. For example, if the MOVE makes the resource a child of a collection that is locked with "Depth: infinity", then the resource will be added to that collection's lock. Additionally, if a resource locked with "Depth: infinity" is moved to a destination that is within the scope of the same lock (e.g., within the namespace tree covered by the lock), the moved resource will again be a added to the lock. In both these examples, as specified in Appendix B.3.5, an If header must be submitted containing a lock token for both the source and destination.¶

[rfc.comment.5: Just state that locks can be refreshed and point to actual method description. --reschke] ¶

If a resource, source or destination, within the scope of the method with a Depth header is locked in such a way as to prevent the successful execution of the method, then the lock token for that resource MUST be submitted with the request in the If request header.¶

The Lock-Token request header is used with the UNLOCK method to identify the lock to be removed. The lock token in the Lock-Token request header MUST identify a lock that contains the resource identified by Request-URI as a member.¶

The Lock-Token response header is used with the LOCK method to indicate the lock token created as a result of a successful LOCK request to create a new lock.¶

[rfc.comment.9: Discussion of timeout behaviour should move somewhere else. Keep only the actual syntax description here. --reschke] Clients may include Timeout headers in their LOCK requests. However, the server is not required to honor or even consider these requests. Clients MUST NOT submit a Timeout request header with any method other than a LOCK method.¶

A Timeout request header MUST contain at least one TimeType and may contain multiple TimeType entries. The purpose of listing multiple TimeType entries is to indicate multiple different values and value types that are acceptable to the client. The client lists the TimeType entries in order of preference.¶

Timeout response values MUST use a Second value, Infinite, or a TimeType the client has indicated familiarity with. The server may assume a client is familiar with any TimeType submitted in a Timeout header.¶

The "Second" TimeType specifies the number of seconds that will elapse between granting of the lock at the server, and the automatic removal of the lock. The timeout value for TimeType "Second" MUST NOT be greater than 2^32-1.¶

If the timeout expires then the lock may be lost. Specifically, if the server wishes to harvest the lock upon time-out, the server SHOULD act as if an UNLOCK method was executed by the server on the resource using the lock token of the timed-out lock, performed with its override authority. Thus logs should be updated with the disposition of the lock, notifications should be sent, etc., just as they would be for an UNLOCK request.¶

Servers are advised to pay close attention to the values submitted by clients, as they will be indicative of the type of activity the client intends to perform. For example, an applet running in a browser may need to lock a resource, but because of the instability of the environment within which the applet is running, the applet may be turned off without warning. As a result, the applet is likely to ask for a relatively small timeout value so that if the applet dies, the lock can be quickly harvested. However, a document management system is likely to ask for an extremely long timeout because its user may be planning on going off-line.¶

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

Name:

lockinfo

Namespace:

DAV:

Purpose:

The lockinfo XML element is used with a LOCK method to specify the type of lock the client wishes to have created.