notes/locking/locking-functional-spec.txt

   1 A Functional Specification for "Locking"
   2
   3 This document describes the features of a new locking system for
   4 Subversion.  It attempts to avoid specific design and implementation
   5 choices wherever possible.
   6
   7 A separate document will outline a proposed implementation for this
   8 specification.
   9
  10 I. Introduction
  11
  12    A. Goals
  13
  14       1. Provide a mechanism to ensure that a user has exclusive
  15          rights to commit changes to a file from a particular working
  16          copy.
  17
  18       2. Provide a communication mechanism to decrease the chances of
  19          a user wasting time working on a file locked by someone else.
  20
  21    B. Summary
  22
  23       We recommend implementing a lightweight locking mechanism.
  24       Teach the server to track and enforce exclusive write locks.
  25       Provide means for repository administrators to manipulate locks
  26       and enforce locking policies.  Provide a series of client
  27       commands for creating, removing, breaking, and stealing locks.
  28       Lastly, create a new property to communicate that a path must be
  29       locked before committing.
  30
  31       Note that Subversion is still an inherently concurrent system.
  32       The ability to lock paths is optional, and can even be prevented
  33       by the repository administrator.
  34
  35
  36 II. New Client Behaviors
  37
  38    A. Overview
  39
  40       1. Definition of "lock"
  41
  42          A lock grants one user the exclusive right to change a
  43          certain file from a specific working copy.
  44
  45       2. Lock restrictions
  46
  47          If a file is locked, the owner of the lock has the exclusive
  48          right to change the file's text and properties, to delete the
  49          file, and to move the file.
  50
  51          The restriction on moving or deleting a locked file is a
  52          restriction on changing its full path name in any way,
  53          including by moving or renaming or deleting any of its
  54          parent directories.
  55
  56          (A locked file can still be read and copied, and any copy of it
  57          will not automatically be locked.)
  58
  59    B. Client requirements for locking
  60
  61       1. Enforcement system
  62
  63          It must be possible to declare that certain files absolutely
  64          require locks before committing.
  65
  66       2. Communication system
  67
  68          There must be a system in place that tells users when locking
  69          is necessary;  ideally, it would prevent a user from
  70          beginning work in the first place.  If a lock already exists,
  71          a user should be able to see who created it, when, and why.
  72
  73    C. Lock manipulation via client
  74
  75       1. Lock Representations in the Working Copy
  76
  77          In order to associate a lock with a particular working copy,
  78          the working copy must store some representation of the lock,
  79          and occasionally synchronize this with the repository's
  80          master list of locks.
  81
  82          Because locks can be broken or stolen, it is possible for a
  83          working copy's lock representation to become "defunct".  A
  84          defunct lock cannot be used or released--it is useless and is
  85          cleaned up when the client next synchronizes with the server.
  86
  87       2. Actions
  88
  89          This section defines specific terminology to describe the
  90          kind of lock-related actions that a Subversion client can
  91          perform.
  92
  93          a. Creating a lock
  94
  95             To lock a file:
  96
  97                - A user must be authenticated to the server
  98                - The file must not already be locked.
  99
 100             Upon successfully locking a file, the working copy retains
 101             a representation of the lock.
 102
 103          b. Using a lock
 104
 105             To make use of a lock, two forms of authentication must be
 106             provided to the server:
 107
 108                - The authenticated username that owns the lock
 109                - A non-defunct lock representation
 110
 111             If either of these forms of authentication are missing or
 112             incorrect, the lock cannot be used.
 113
 114             1. Using a lock to Commit
 115
 116                Upon successful commit, a locked file is released by
 117                default.  The Subversion client provides an option to
 118                retain the lock after commit.
 119
 120             2. Releasing a lock
 121
 122                After successful release, the representation of the lock
 123                is removed from both the working copy and the server.
 124
 125          c. Breaking a lock
 126
 127             "Breaking" a lock is a means of releasing a lock when:
 128
 129                - The authenticated username is not the same as the
 130                  lock owner, or
 131                - The working-copy lock representation is unavailable.
 132
 133             (e.g. Harry locks file foo and is suddenly laid off.
 134             Sally decides to clean up his mess and breaks the lock on
 135             foo, without using Harry's username or lock
 136             representation.)
 137
 138          d. Stealing a lock
 139
 140             "Stealing" a lock is a means of creating a lock when:
 141
 142                - The file is locked by you, but you don't have a
 143                  representation of the lock in your current working
 144                  copy, or
 145                - The file is locked by someone else.
 146
 147             In order to steal a lock, a user must be authenticated to
 148             the server.
 149
 150             (e.g. Harry locks file foo and goes on vacation.  Sally
 151             needs to make changes to foo and obtains a lock on foo by
 152             stealing Harry's lock, without using Harry's username or
 153             lock representation.)
 154
 155          e. Discovering/examining locks
 156
 157             The Subversion client provides interfaces to answer the
 158             following questions:
 159
 160             - Ask working copy to display all lock representations
 161
 162             - Examine a particular lock representation
 163
 164             - Ask server to list all locks underneath a given path,
 165               optionally displaying all attributes of the locks
 166               (Possibly able to restrict this query to a single user)
 167
 168             - Ask server whether a given file is locked
 169
 170
 171 III. New Server Behaviors
 172
 173    A. Overview
 174
 175       1. Definition of a lock
 176
 177          As noted in section II.A.1, a lock grants one user the
 178          exclusive right to change a certain file from a specific
 179          working copy.
 180
 181       2. Attributes of a lock
 182
 183          A lock is an immutable data object.  It must contain: a
 184          unique identifier, the path being locked, the username that
 185          owns the lock, and a creation timestamp.  A lock comment is
 186          optional.
 187
 188       3. Lock Restrictions
 189
 190          See II.A.2 for details.  The server will enforce these
 191          behaviors.
 192
 193    B. Tracking locks
 194
 195       The Subversion server holds the master list of all locks for a
 196       repository.  It responds to client requests to create, release,
 197       break and steal locks.
 198
 199       When a client asks about a lock, the server reports whether the
 200       lock is valid or is defunct (i.e. the server no longer has a
 201       lock corresponding to the lock representation in question).
 202       When a client creates or steals a lock, the server returns a
 203       lock representation.
 204
 205    C. Enforcement
 206
 207       During a commit, the server checks for locks the same way that
 208       it checks for out-of-dateness.
 209
 210       As each changed path arrives, the server checks to see if the
 211       path is locked.  If the path is locked, the server makes certain
 212       that the correct username and lock representation have been
 213       presented by the client.  If not, the entire commit is rejected
 214       immediately.
 215
 216       In addition, the server re-checks and enforces locks during
 217       commit finalization.
 218
 219    D. Configurable Mechanisms
 220
 221       The server provides mechanisms to enable diverse administrative
 222       locking policies, including:
 223
 224       1. Allow or disallow creating, breaking, and stealing of locks
 225          based on specific criteria (e.g. username, path, etc.)
 226
 227       2. Perform tasks after creating, breaking, and stealing a lock
 228          (e.g. sending email, collecting stats, etc.)
 229
 230    E. Lock manipulation with svnadmin
 231
 232       1. Discovering locks
 233
 234          svnadmin provides interfaces to answer the following
 235          questions:
 236
 237          - List all locks in a repository underneath a given path
 238            (Possibly able to restrict this query to a single user)
 239
 240          - Ask whether a given repository file is locked
 241
 242       2. Unconditional release of locks
 243
 244          svnadmin provides an interface to unconditionally release a
 245          specific lock.
 246