8.6 Client Responsibilities

Locks can be used in ways that frustrate users and subvert the purpose of locking. Clients have several responsibilities to improve interoperability.

8.6.1 Why Client Software Must Store Lock Tokens

If the client loses track of a lock token, the token may be rediscovered by querying the lockdiscovery property. Rediscovery of lock tokens allows clients to gracefully handle crashes, data losses, or simply lost messages from the server. Typically, the software presents the user with information about the lock, and asks if the user would like to remove the lock.

Some early WebDAV client implementations did not store the lock token. Instead, the client software relied on the server to provide the lock token in the lockdiscovery property whenever needed. This is a bad idea. Clients must store lock tokens for as long as the locks exist. It's not enough for the client to simply cache lock tokens in memory while the client is running; when the client exits, those locks must be unlocked or the lock tokens must be stored for use next time.

Storing lock tokens is a burden for the client, so why is it required? On first examination, the WebDAV server seems to enforce proper use of lock tokens. After all, the server only allows the client to use the lock token successfully if it's authenticated as the lock creator. Most of the time, the authorization check prevents inappropriate use of the lock token, but there are two cases in which the server cannot prevent misuse:

• In the case in which unauthenticated users are allowed to take out locks, the server can't identify who is allowed to use the lock token. The server must allow any request to use a lock token when the lock creator didn't authenticate.

• When two authoring clients are run by the same user to edit the same file, the authorization check can't tell the difference. For example, you might open a file on your work computer, make changes and go home, and then open the file on your home computer. Two authoring clients can accidentally overwrite each other's changes, just as two authors can.

A WebDAV server may have no way to avoid these corner cases of the lost update problem. Unless all client software stores the lock token for the duration of the lock, users may suffer the lost update problem despite locking the resource.

A server's access control policies may allow users other than the lock creator to access the lock token and "hijack" the lock. Some servers allow administrators or resource owners to remove locks. This can be a desirable feature because it allows the server to keep lock timeouts high and still gives resource owners control over their resources. However, client software should only hijack a lock at the explicit request of the user, because it's very disruptive to the user who made the original LOCK request. Clients should only allow hijacking when doing an UNLOCK (and the server may limit hijacking in the same way). If the hijacking user wants to make changes, a new lock can be obtained.

8.6.2 Renew Often, Renew Early, Unlock Promptly

For many reasons, a client can lose a lock; it can be pretty confusing to the user when this happens, because the user doesn't know whether it's safe to overwrite the file anyway. To prevent this, it's tempting for the client to ask for long timeouts. However, long timeouts prevent other users from making changes in the case of orphaned locks. A timeout of an hour to a day seems like a reasonable compromise, but the decision would change depending on the type of client. A client that automatically creates locks, like Office 2000, probably shouldn't reserve locks for more than a day or so. However, a client that does offline synchronization and locks files at the user's request might reasonably lock a file for a week.

If lock timeouts are around an hour or a day, there are plenty of chances for the client to fail to renew the lock.

• The laptop the client was running on went to sleep.

• The network connection was lost during the time the lock needed to be renewed.

• The user's authentication information timed out and the user wasn't around to enter his or her password again.

• A bug exists in client or server software.

To keep these renewal failures to a minimum, client software should attempt to renew the lock well before the expiration so that there's a grace period for the client to try again before really losing the lock. The client could renew hour-long locks every half hour or day-long locks every few hours.

Finally, the client should unlock the file when the lock is no longer needed, rather than let the server time out and clean up the lock. This practice lets other users get on with their changes.

8.6.3 Verifying Lock Persistence

Section 3.7.6 explained how to avoid overwriting somebody else's changes by using the If-Match header: If the ETag is still the same, then the resource hasn't been changed. You'd think that when a resource is locked, this step isn't necessary any more but it still is. There are several (hopefully rare) cases where the file can change even though it was originally locked:

• The lock was accidentally not renewed (some possible causes were listed in the previous section).

• An administrator removed the lock before its expiration. Some servers allow administrators to remove locks through a non-WebDAV interface in order to be able to clean up inappropriate or inconvenient locks.

• Another client chose to get the lock token using lockdiscovery and then used the lock token to destroy the lock and change the resource. Since WebDAV does not consider the lock token to be a secret, this may be possible, depending on how the server treats lock and unlock permissions. It's up to the server implementation whether to limit UNLOCK to the lock creator. The choice depends on how much control the server gives to the user and the resource owner, as well as how often the server requires administrator intervention for unusual cases like destroying locks. Thus, servers for different purposes (Web site authoring, file sharing, document management) might legitimately make different choices here.

The inclusion of the lock token in the If header provides some protection from situations where the client wasn't up to date on the lock state. The If header is a conditional test as well as a way to provide lock tokens, so the request must be failed by the server if the condition fails. That means that the client's information on the lock state must be correct (or the condition must be loosely constraining) before the operation is allowed. That safeguard may prevent lost updates in cases where the original user's lock disappears and another change is made to the file before the original user's change is uploaded.

In any case, it's safest to use ETags as well as lock tokens whenever possible, to verify that the resource is still in the expected state.

8.6.4 Managing Deadlocks

Clients may have to take out multiple exclusive locks on multiple resources in order to complete some operations safely. For example, both Alice and Bob might want to move résumés around between /hr/recruiting/resumes/ and /hr/archives/resumes/. If they pick different collections to lock first and hold onto the first lock waiting to get a second lock, they could both wait a long time (see Figure 8-8).

Figure 8-8. Deadlock: Two clients each waiting to get a second lock.

Servers can do nothing to prevent these kinds of deadlocks. Therefore, it's up to the client to be aware of the problem and act responsibly to avoid remaining deadlocked. The only workable approach is for every client to back off and give other clients a chance to complete their operations. This means that clients should never hold onto a lock while waiting to get another lock. Instead, release the successful lock and try to get both locks later. Random short waits, with exponentially increasing backoff, is a common technique in such scenarios.

It's sometimes possible to lock a parent collection such that only one lock is needed. (In this case, either Alice or Bob could have locked /hr/ if they had sufficient permissions.) However, since this approach may block more operations than is necessary, it's not always appreciated by other users, because a collection can't be locked if one of its descendants is already exclusively locked, and vice versa.

8.6.5 Handling Lock-Null Resources

Not all servers support the full specification for lock-null resources. The specification itself may be changed since there are so many problems with lock-null resources. Therefore, client implementers must tread carefully. A responsible client should behave as follows:

• Use the If header and an ETag whenever locking existing resources in case the server will not clean out the lock-null resource when the lock goes away. In fact, use ETags whenever working with resources that are believed to exist and not to have changed.

• Do not rely on being able to use MKCOL on a lock-null resource. Instead, follow a MKCOL request quickly with a LOCK request (perhaps in a pipelined request, even though it's not normally recommended to have one pipelined request rely on another succeeding). This practice introduces a possible race condition, but the only pragmatic way to avoid problems is simply to do the two requests quickly.

• Do not create lock-null resources and leave them in that state. Either quickly convert them to regular resources with PUT or attempt to clean them out using UNLOCK so that other clients can either see the new resource or not have to worry about it.

• If unlocking a lock-null resource, check to see if the server actually removed it. If it did not, attempt a DELETE to clean up.

8.6.6 Using Shared Locks

Shared locks require more client effort to use correctly and responsibly. In addition to all the considerations for exclusive locks, a client with a shared lock must also consider how to coordinate changes to the resource locked with a shared lock. How this is done depends on why the client is using shared locks. There are at least four possible cases involving different coordination.

Advisory Locks

Sometimes locks can serve a purpose that is closer to "advisory" than "preventative." All the lock owner wants to do is put up a flag saying "I'm modifying this file, change it at your own risk." This doesn't prevent others from modifying the same file, but it's likely to make the other clients aware that the resource is in use. If a CM system uses advisory locks already, shared locks may be supported for backward compatibility. To make advisory locks work well, client software must communicate frequently with the user, letting the user know how the resource is locked and whether changes will be overwritten.

Read Locks

Client software may request a shared lock in order to prevent the resource from being changed while the client reads the resource. Normally, this isn't a concern in WebDAV, but some large resources may be downloaded using byte ranges (see Section 3.7.12), and it's easier to download a file in multiple ranges if it doesn't change between requests. A shared read lock is much more useful than an exclusive read lock because other users reading the same resource can take out their own shared read lock. The resource can't be changed until the last client has finished downloading the resource and releases the last shared lock.

Sharing Locks Among Processes

Sophisticated client applications involving multiple processes may have an out-of-band mechanism for coordinating changes to the same WebDAV resource. These processes may all be acting in concert on behalf of the same user. The processes could be running on the same computer or on different computers. Shared locks may be helpful for these processes to reserve the resource for changes without blocking other processes out. Each process must mark the shared lock so that the other processes know that the locks can indeed be used in this manner.

Custom Locking

Some systems may require a different lock model than the one WebDAV provides. It may be possible for these systems to use shared locks, then to use some nonstandard mechanism (such as custom dead properties) to communicate information about who may modify the file at what point. For example, a custom workflow process might use shared locks to transfer lock protection from one user to another at a certain phase of the process. The client applications involved in this process must mark the shared locks so that other applications can be sure this is how the lock is being used.