11.6 Using Non-DeltaV Clients

It is possible to deploy a DeltaV repository in which only DeltaV-compatible clients are fully supported and plain WebDAV clients can browse but are unable to author resources on their own. That's the easy behavior: The repository simply has to forbid write operations to checked-in resources.

Although accepting this kind of limitation for DeltaV as a whole would have made its design simpler, it was always thought that DeltaV systems should be WebDAV compliant: A non-DeltaV client should be able to view and edit versioned resources. This section discusses how backward compatibility is ensured and managed.

In addition to allowing plain WebDAV clients to modify checked-out resources with PUT and PROPPATCH, DeltaV servers must consider how GET, LOCK, MOVE, and COPY are handled with non-DeltaV clients.

11.6.1 Read Operations and UPDATE

An HTTP client can use GET without knowing if the resource supports WebDAV. Similarly, a WebDAV client can use GET and PROPFIND without having to know if the resource is under version control. If the server supports UPDATE, this feature changes how all these read requests work. UPDATE does this by changing the target version of a VCR, which also changes the checked-in property value to point to the new target version. Section 11.2.1 explained that a target version is the version whose contents and dead properties are exposed by the checked-in VCR. Figure 11-7 shows a resource where the target version, and thus the content exposed in the checked in VCR, is not the latest version.

Figure 11-7. Versioned resource after UPDATE.

There are a number of reasons to use UPDATE:

• To allow other clients to see a version that isn't the latest version, if a previous version is more appropriate to display.

• So that when the resource is subsequently checked out, modifications to the checked-out resource can begin from the content in a previous version. This is an easy way to roll back to a previous version's contents: UPDATE to the previous version, CHECKOUT, and then CHECKIN.

• As we will see in Chapter 12, other features use UPDATE in interesting ways.

Here are some of the operations affected:

• A PROPFIND request to a checked-in VCR will return the dead properties of the target version, not necessarily the latest version. However, PROPFIND always returns the live properties of the VCR, which are often different from the live properties of the target version.

• If a VCR is used as the source of a COPY request, the body and properties that are copied depend entirely on the target version of the source VCR.

• A CHECKOUT request to a VCR checks out the target version, using that version's content as a starting point for the new version. When CHECKIN happens, it's the previous target version that gets a new successor added.

11.6.2 Auto-Version: Enabling Write Operations

Write operations are a little harder to handle, because a WebDAV-only client will not know to do CHECKOUT and CHECKIN operations. The server could forbid all write operations on VCRs that aren't checked out, but this would prevent existing WebDAV authoring applications being used with DeltaV servers. Therefore, the server must have a way to allow write operations and automatically create new versions.

DeltaV defines the auto-version property on a VCR to indicate or control how the server will handle write operations without an explicit CHECKOUT operation. The server must either manage or watch the property value and enforce behavior accordingly. Clients may be interested in the value of this property to predict what the server will do, or they may on some servers be allowed to give the property a new value to change auto-versioning behavior for that resource. Table 11-3 explains each of the possible values for this property.

If the auto-version property is not null, then write operations on that VCR can succeed even when it is checked in. The server must behave as if the client sent CHECKOUT and CHECKIN operations at certain points in time. Those points in time depend on the value of auto-version.

The auto-version property can be empty or contain one of four values: checkout-checkin, checkout-unlocked-checkin, checkout, or locked-checkout.

The checkout-unlocked-checkin value is particularly useful because it allows any WebDAV client to edit the resource, including both clients that don't understand DeltaV and clients that don't use locks. It has excellent characteristics when locks are used. Some nonversioning WebDAV clients, such as the Office 2000 client, always lock a resource while editing it online. While the resource is locked, the client may issue many PUT requests.

Table 11-3. Auto-version Values

Checkout-checkin	The server will check out and check in the VCR along with every write operation. This can result in many versions but is guaranteed to capture changes. Although the operations are the same as the explicit CHECKOUT and CHECKIN methods, the resource is never left in the checked-out state by a non-DeltaV client.
checkout-unlocked-checkin	The server will automatically check out a VCR when it is changed. If the resource is not locked, the server will also automatically check it in (just like checkout-checkin). However, if the VCR is locked, then the server won't check in the resource until it is unlocked. The resource appears in checked-out state from the first write operation until the UNLOCK request.
checkout	The server automatically checks out the VCR when it is modified, but checkin is not done automatically. The resource remains checked out, preventing other clients from checking out the resource in place. Thus, a change by one non-DeltaV client leaves the VCR checked out indefinitely. Other non-DeltaV clients may make changes while the VCR remains checked out, but no new versions are created until a DeltaV-aware client sends a CHECKIN request.
locked-checkout	The server checks out the resource when it receives a write operation on a locked resource. However, the server does not allow write operations at all if the resource is not locked. When the lock goes away, the server checks in the resource. This option is slightly different from checkout-unlocked-checkin because it forces the client to lock or check out the resource before being allowed to edit it.

Saving the result of every one of these PUT requests would take a lot of storage space and may not be useful to others. Instead, the server can wait until the client unlocks the resource (in the case of Office 2000, this happens when the user closes the file) to check it in. In case the client connection is lost, the server should check the resource in when the lock expires rather than leave it indefinitely checked out. This is a good idea, although DeltaV does not require it.

The checkout value is not so useful because it requires versioning-aware clients to check the resource in eventually; otherwise, all changes will accumulate without creating new versions. However, it can be useful when a version-control client is used in conjunction with a regular WebDAV authoring tool: The version-control client can be used to check out and check in the resource, while the authoring tool can be used to edit the resource. Many source control versioning systems already operate in this manner.

Clients may be able to change the value of the auto-version property to tell the server exactly how to automatically create versions. Servers are not required to allow the property to be changed, however. Servers may support all four options, some, or none. The value of the property could change depending on the resource.

Whenever a VCR is checked in after being edited in place with auto-versioning, the server must automatically set the target version of the VCR to be the new version. Otherwise, nonversioning clients would never see the results of their work.

11.6.3 Locking

Locking deserves special consideration because if non-DeltaV clients can unknowingly check out or check in a resource, a DeltaV client could also accidentally check out or check in. Avoiding accidental checkouts is easy: Don't issue a write operation to a VCR unless it's already checked out. Avoiding accidental checkins is a little tricker because the resource may be checked in if it is locked and then unlocked. The client should not issue LOCK and then UNLOCK (without any CHECKOUT before or between) unless it knows the server's auto-versioning behavior.

Server implementors have a great responsibility here to think through locking and versioning to make sure all possible combinations of operations behave properly. Otherwise, it's too difficult to write a client that can interoperate with a variety of servers. These are guidelines I've developed for servers based on the requirements in the DeltaV specification as well as an analysis of how a client would attempt to perform various tasks:

• The server should allow a LOCK operation on a VCR (assuming the client has write privileges) even if it isn't checked out and even if there is no auto-versioning allowed, because the client may do the CHECKOUT next. It's important for clients to be able to do LOCK first to protect their checked-out resource from changes by other clients.

• The server must allow clients to issue CHECKOUT on a locked VCR, even if auto-versioning makes the CHECKOUT unnecessary. The client needs to be able to explicitly check out the locked resource to show to other clients that it is checked out. Otherwise, the resource would not appear as checked out until the first PUT request, as DeltaV requires.

• If the client does an explicit CHECKOUT before or after a LOCK request, then issues an UNLOCK request, the server must not check in until an explicit CHECKIN request is received (even if auto-versioning would normally cause the resource to be checked in on UNLOCK). The client may want to remove the lock in order to allow another client application to edit the resource before checking in later. This allows two clients to synchronize modifications to a checked-out resource to create one collaborative new version.

Locking before checkout is highly beneficial to avoid race conditions, too. A DeltaV client might issue a PROPPATCH request to a resource it believes to be checked in, to quickly change a property value. If another DeltaV client checked out the resource just before the PROPPATCH request without locking the resource, the property change would accidentally become part of the checkout, not an independent change. With checkout state, there's no parallel to the way the If header allows the client to verify lock state (Section 8.4.2), so the client can't make operations conditional on the checkout state of the resource.

11.6.4 "Safe Save" Problems with Existing Clients

It's not easy to support regular WebDAV clients editing VCRs. Some applications use "safe save" algorithms that can accidentally overwrite versioned resources with unversioned resources. Safe save algorithms were designed for local or remote unversioned file systems, but these applications sometimes use a layer that mimics the local file system, so the application is unaware it is even using a versioning repository.

When saving a file, the application needs to have a backup copy in case something goes wrong while making changes. File system write operations are often done piece by piece, so if the write is interrupted in the middle, the file could be left corrupted. To keep from corrupting an important file in this manner, the application may save to a temporary file. If all the partial writes work, then the application can move or copy the temporary file over the original file. Since the operating system is responsible for the move or copy operation working atomically, this process should help avoid file corruption. The temporary file may be deleted or left around as a backup.

For example, TextEdit on Mac OS X creates a backup file by appending a tilde character (~) to the file name and saving the file. TextEdit can be configured not to keep backup files, but unfortunately it still creates the backup files and then deletes them. When the Mac OS X WebDAV client receives these commands from TextEdit, the client requests a MOVE of my.txt to my~.txt, PUT to my.txt, then DELETE my~.txt. Let's walk through the confusion this causes:

1. The MOVE of my.txt to my~.txt is treated as a rename, so the version history that was linked to my.txt will instead be associated with my~.txt. The URL my.txt now has no resource and no version history.

2. PUT of my.txt will create a new resource, which may or may not be made version-controlled by the server. Imagine other users of the file discovering that the version-controlled file has become unversioned somehow and lost all its version history.

3. The DELETE of my~.txt either destroys the version history or at least deletes the reference to the version history.

One could imagine having special logic in the server to deal with this situation. The server could decide to forbid the DELETE of a VCR, but this would leave a clutter of backup files.

Alternatively, the server could watch for PUT operations to URLs that previously had a version history, and the server would restore (perhaps duplicate) the version history. However, there are legitimate MOVE/PUT combinations where the new file is supposed to have a new version history. The server could also look out for telltale file names such as those with a first part ending in ~, but in practice there are many such temporary file-naming systems, and some of them are stupidly similar to what a human might name a file.

Finally, it's difficult to watch for all safe save algorithms, because they differ greatly, not only in how they name files but also in what operations are used. Apple's default mail program does a PUT to a temp file and then a MOVE to the real URL. Some Macintosh OS X software using system APIs employs a four-step procedure to save new content to my.txt:

1. MOVE my.txt to my~.txt (move the original file out of the way).

2. PUT data1234.txt (create a completely new URL rather than upload to the official URL).

3. MOVE data1234.txt to my.txt (start using the official URL).

4. DELETE my~.txt (cleanup).

It's unclear why these four steps are used. Perhaps two layers of software each performed a different safe save, and their operations combined in this way. Or, maybe the application designers wanted to confirm that both the save operation and the move operation worked before deleting the original. It doesn't matter, because with all the variations in potential safe save algorithms, servers can't deal with all of them.

Safe save algorithms are not recommended for use with any WebDAV server, and particularly not with DeltaV servers. If client software must use a safe save algorithm, there is one that will work adequately with versioning, although it is not ideal:

1. Choose an unlikely temporary file name, not one that users could easily stumble upon. PUT the new content to the temporarily file name first, creating a temporary resource. Check that the content was uploaded correctly. Note that the server may automatically create that resource as a VCR.

2. COPY the temporary file to the real file. In a versioning system, this will create a new version of my.txt with the content from the temporary file. (This only works if auto-versioning is allowed, but that's immaterial since a change would not have been allowed in the first place.) Do not use MOVE, because this will overwrite the destination version history.

3. DELETE the temporary file to clean up. Note that if it was created as a VCR, then the process may leave a new VHR in the version history collection, but it will not be visible to most operations.