[tahoe-dev] wapi for Tahoe Lock Files

[Zooko O'Whielacronx]

Here's a proposed wapi extension to let users acquire and release  
Tahoe Lock Files.

  * to create a lock file

POST /lock?t=create

This will return a write-cap to a newly created lock file.  (Under  
the hood, this is the same as what happens with "PUT /uri? 
mutable=true".)

  * to acquire a lock

POST /lock/$CAP?t=acquire

Where CAP is the write-capability created above.

The result from the ?t=acquire is either success or failure, and in  
either case the response body contains the "lockstring" -- the unique  
identifier of the lock which is currently in the lock file.  If the  
result is failure, then go to "waiting to get a lock" below.

If the result is success, then you have an exclusive lock in that  
lock file for the next 300 seconds.

  * releasing a lock

When you finish your write, then you should call

POST /lock/$CAP?t=release

  * re-acquiring a lock

If you haven't released the lock in 150 seconds, then you must  
reacquire it.  Call

POST /lock/$CAP?t=force&oldlockstring=$LOCKSTRING

Where LOCKSTRING is the string that was returned to you when you  
acquired this lock.

The response from ?t=force will include a new lockstring.  You now  
have around 300 more seconds (just as if you had acquired the lock  
when nobody previously had it).  If this attempt to reacquire fails  
(which can happen due to server or network problems -- the servers  
may be unreachable), then you MUST stop writing to the protected file  
or files, until you successfully reacquire the lock.

  * waiting to get a lock

If you try to get a lock with ?t=acquire and get a failure, then  
remember the lockstring that came back in the response body.  If that  
same lockstring is still in place more than 300 seconds from now,  
then you are allowed to force it with

POST /lock/$CAP?t=force&oldlockstring=$LOCKSTRING

passing the old lock string that you have observed to remain in place  
for longer than 300 seconds.


Make sense?


Regards,

Zooko