locking-functional-spec.txt [plain text]
A Functional Specification for "Locking"
This document describes the features of a new locking system for
Subversion. It attempts to avoid specific design and implementation
choices wherever possible.
A separate document will outline a proposed implementation for this
specification.
I. Introduction
A. Goals
1. Provide a mechanism to ensure that a user has exclusive
rights to commit changes to a file from a particular working
copy.
2. Provide a communication mechanism to decrease the chances of
a user wasting time working on a file locked by someone else.
B. Summary
We recommend implementing a lightweight locking mechanism.
Teach the server to track and enforce exclusive write locks.
Provide means for repository administrators to manipulate locks
and enforce locking policies. Provide a series of client
commands for creating, removing, breaking, and stealing locks.
Lastly, create a new property to communicate that a path must be
locked before committing.
Note that Subversion is still an inherently concurrent system.
The ability to lock paths is optional, and can even be prevented
by the repository administrator.
II. New Client Behaviors
A. Overview
1. Definition of "lock"
A lock grants one user the exclusive right to change a
certain file from a specific working copy.
2. Lock restrictions
If a file is locked, the owner of the lock has the exclusive
right to change the file's text and properties, to delete the
file, and to move the file.
The restriction on moving or deleting a locked file is a
restriction on changing its full path name in any way,
including by moving or renaming or deleting any of its
parent directories.
(A locked file can still be read and copied, and any copy of it
will not automatically be locked.)
B. Client requirements for locking
1. Enforcement system
It must be possible to declare that certain files absolutely
require locks before committing.
2. Communication system
There must be a system in place that tells users when locking
is necessary; ideally, it would prevent a user from
beginning work in the first place. If a lock already exists,
a user should be able to see who created it, when, and why.
C. Lock manipulation via client
1. Lock Representations in the Working Copy
In order to associate a lock with a particular working copy,
the working copy must store some representation of the lock,
and occasionally synchronize this with the repository's
master list of locks.
Because locks can be broken or stolen, it is possible for a
working copy's lock representation to become "defunct". A
defunct lock cannot be used or released--it is useless and is
cleaned up when the client next synchronizes with the server.
2. Actions
This section defines specific terminology to describe the
kind of lock-related actions that a Subversion client can
perform.
a. Creating a lock
To lock a file:
- A user must be authenticated to the server
- The file must not already be locked.
Upon successfully locking a file, the working copy retains
a representation of the lock.
b. Using a lock
To make use of a lock, two forms of authentication must be
provided to the server:
- The authenticated username that owns the lock
- A non-defunct lock representation
If either of these forms of authentication are missing or
incorrect, the lock cannot be used.
1. Using a lock to Commit
Upon successful commit, a locked file is released by
default. The Subversion client provides an option to
retain the lock after commit.
2. Releasing a lock
After successful release, the representation of the lock
is removed from both the working copy and the server.
c. Breaking a lock
"Breaking" a lock is a means of releasing a lock when:
- The authenticated username is not the same as the
lock owner, or
- The working-copy lock representation is unavailable.
(e.g. Harry locks file foo and is suddenly laid off.
Sally decides to clean up his mess and breaks the lock on
foo, without using Harry's username or lock
representation.)
d. Stealing a lock
"Stealing" a lock is a means of creating a lock when:
- The file is locked by you, but you don't have a
representation of the lock in your current working
copy, or
- The file is locked by someone else.
In order to steal a lock, a user must be authenticated to
the server.
(e.g. Harry locks file foo and goes on vacation. Sally
needs to make changes to foo and obtains a lock on foo by
stealing Harry's lock, without using Harry's username or
lock representation.)
e. Discovering/examining locks
The Subversion client provides interfaces to answer the
following questions:
- Ask working copy to display all lock representations
- Examine a particular lock representation
- Ask server to list all locks underneath a given path,
optionally displaying all attributes of the locks
(Possibly able to restrict this query to a single user)
- Ask server whether a given file is locked
III. New Server Behaviors
A. Overview
1. Definition of a lock
As noted in section II.A.1, a lock grants one user the
exclusive right to change a certain file from a specific
working copy.
2. Attributes of a lock
A lock is an immutable data object. It must contain: a
unique identifier, the path being locked, the username that
owns the lock, and a creation timestamp. A lock comment is
optional.
3. Lock Restrictions
See II.A.2 for details. The server will enforce these
behaviors.
B. Tracking locks
The Subversion server holds the master list of all locks for a
repository. It responds to client requests to create, release,
break and steal locks.
When a client asks about a lock, the server reports whether the
lock is valid or is defunct (i.e. the server no longer has a
lock corresponding to the lock representation in question).
When a client creates or steals a lock, the server returns a
lock representation.
C. Enforcement
During a commit, the server checks for locks the same way that
it checks for out-of-dateness.
As each changed path arrives, the server checks to see if the
path is locked. If the path is locked, the server makes certain
that the correct username and lock representation have been
presented by the client. If not, the entire commit is rejected
immediately.
In addition, the server re-checks and enforces locks during
commit finalization.
D. Configurable Mechanisms
The server provides mechanisms to enable diverse administrative
locking policies, including:
1. Allow or disallow creating, breaking, and stealing of locks
based on specific criteria (e.g. username, path, etc.)
2. Perform tasks after creating, breaking, and stealing a lock
(e.g. sending email, collecting stats, etc.)
E. Lock manipulation with svnadmin
1. Discovering locks
svnadmin provides interfaces to answer the following
questions:
- List all locks in a repository underneath a given path
(Possibly able to restrict this query to a single user)
- Ask whether a given repository file is locked
2. Unconditional release of locks
svnadmin provides an interface to unconditionally release a
specific lock.