| 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. |
| |
