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