notes/locking/locking-implementation.txt

   1 Implementation for "Locking" feature
   2
   3 This document describes proposed implementation details for a new
   4 locking system in Subversion.
   5
   6 I. Introduction
   7
   8 II. Client Implementation
   9
  10    A. Overview
  11
  12    B. The "svn:needs-lock" property
  13
  14       1. Property as enforcement system
  15
  16       2. Property as communication system
  17
  18    C. Lock manipulation via client
  19
  20       1. Lock Tokens
  21
  22           Stored as 'entryprops'.  That is, just like
  23           last-changed-rev, last-author, etc., tokens come into the
  24           client with an svn:entry: prefix, are filtered by libsvn_wc,
  25           and stored in .svn/entries.   We'll call the new entryprops
  26           "svn:entry:lock-token", "svn:entry:lock-owner",
  27           "svn:entry:lock-comment and "svn:entry:lock-creation-date".
  28           (In DAV parlance, what
  29           we call 'entryprops' are called 'live props'.)
  30
  31           libsvn_wc stores the other fields of a lock (owner,
  32           comment, creation-date) in the entries file, so that they
  33           are available for the info command.  Note that this
  34           information is only stored if the current WC has a lock on
  35           the file.
  36
  37       2. New client subcommands
  38
  39          a. Creating a lock
  40
  41              'svn lock' calls new RA->lock() function, which marshals
  42              BASE rev of file to svn_fs_lock().  FS does a
  43              complimentary out-of-dateness check before creating the
  44              lock.  The lock is marshaled back to client, stored in
  45              .svn/entries file.
  46
  47          b. Using a lock
  48
  49             1. Using a lock to Commit
  50
  51                A new RA layer get_commit_editor2() function will be created.
  52                It takes a hash of path -> lock token from the working
  53                copy.  This will be used by the server to check that
  54                the WC locks match the current locks on the paths.  A
  55                flag keep_locks will also be added, specifying whether
  56                the committables should be unlocked after a successful commit.
  57
  58                libsvn_client will collect lock tokens during the
  59                harvesting of commit items.  If --no-unlock was not
  60                specified, unmodified objects will be treated as commit
  61                items if the WC has a lock on them.  A new status flag
  62                in svn_client_commit_info_t indicates that the object
  63                has a lock token.
  64
  65                A new svn_wc_process_committed2 WC function will be
  66                created with a flag indicating whether the lock toke
  67                should be removed as part of the post-commit entry update.
  68
  69             2. Releasing a lock
  70
  71                svn unlock uses the lock token stored in the WC and
  72                issues an ra->unlock command to the server.
  73
  74
  75          c. Breaking a lock
  76
  77             svn unlock --force will first ask the server for a lock
  78             token and use it in the ra->unlock command to break the
  79             lock.
  80
  81          d. Stealing a lock
  82
  83             svn lock --force uses ra->lock with the force argument set
  84             to TRUE to steal a lock.
  85
  86          e. Discovering/examining locks
  87
  88             1. seeing lock tokens in a working copy
  89
  90                The client uses the lock information stored in the
  91                entries file to show lock information with svn info and
  92                svn status.
  93
  94             2. seeing locks in a repository
  95
  96                The server will marshal the lock information as
  97                entryprops when calling the status editor.
  98
  99                svn info URL will use RA->get_lock to get the lock for the
 100                path specified.
 101
 102             3. 'svn update' behavior
 103
 104                 A.  At the start of an update, a new version of the
 105                 'reporter' vtable is used to describe not only mixed
 106                 revnums to the server, but also existing locktokens.
 107                 We need to be careful with protocols when marshaling
 108                 this new information to older or newer servers.
 109
 110                 In ra_svn a new command will be added to the report
 111                 command set for this purpose.
 112
 113                 B.  If a locktoken is defunct (expired, broken,
 114                 whatever), then the server sends a 'deletion' of the
 115                 locktoken entryprop, through normal means: the prop
 116                 deletion comes into the update_editor, and thus is
 117                 removed from .svn/entries.
 118
 119
 120 III. Server Implementation
 121
 122    A. Overview
 123
 124    B. Tracking locks
 125
 126       1. Define a lock-token:
 127
 128             UUID
 129             owner
 130             comment [optional]
 131             creation-date
 132             expiration-date [optional]
 133
 134       2. Define a lock-table that maps [fs-path --> lock-token]
 135
 136          Beware the "deletion problem": if a certain path is locked,
 137          then no parent directory of that path can be deleted.
 138
 139          The bad way to solve this problem is to do an O(N) recursive
 140          search of the directory being deleted, making sure no child
 141          is locked.
 142
 143          The good way to solve this problem is to implement the 'lock
 144          table' as a tree.  When an object is locked, we create the
 145          locked path in the lock-tree.  Then, the mere existence of a
 146          directory in the lock-tree means it has at least one locked
 147          child, and cannot be deleted.  This is a much more acceptable
 148          O(logN) search.
 149
 150    C.  How to implement locks in libsvn_fs
 151
 152           This option implies that both BDB and FSFS would need to
 153           implement the 'lock tree' in their own way.  Any user of
 154           libsvn_fs would automatically get lock-enforcement.
 155
 156
 157       1.  Define an API for associating a user with an open
 158           filesystem.  Locks cannot be created/destroyed without a
 159           username, except that the filesystem allows breaking a lock
 160           without a username.
 161
 162       2.  New fs functions for locks:
 163
 164               svn_fs_lock()       --> locks a file
 165               svn_fs_unlock()     --> unlocks a file
 166               svn_fs_get_locks()  --> returns list of locked paths
 167               svn_fs_get_lock()   --> discover if a path is locked
 168
 169             These functions don't do anything special, other than
 170             allow one to create/release/examine locks.  BDB and FSFS
 171             need to implement these functions independently.
 172
 173       3.  Wrap two of the functions in libsvn_repos, to invoke hooks.
 174
 175               svn_repos_fs_lock()
 176               svn_repos_fs_unlock()
 177
 178             As usually, encourage "good citizens" to use these
 179             wrappers, since they'll invoke the new hook scripts.  The
 180             only thing which calls the fs functions directly (and
 181             circumvents hooks) would be a tool like svnadmin (see
 182             'svnadmin unlock' in UI document.)
 183
 184       4.  Teach a number of fs functions to check for locks, and deal
 185           with them:
 186
 187           svn_fs_node_prop()
 188           svn_fs_apply_textdelta()
 189           svn_fs_apply_text()
 190           svn_fs_make_file()
 191           svn_fs_make_dir()
 192
 193             Check to see if the incoming path is locked.  If so, use
 194             the access descriptor to see if the caller has the lock token.
 195
 196               1. check that the lock-token correctly matches the
 197                  lock. (i.e. that the caller isn't using some defunct
 198                  or malformed token).
 199
 200               2. check that the lock owner matches whatever
 201                  authenticated username is currently attached to the fs.
 202
 203           svn_fs_copy()
 204           svn_fs_revision_link()
 205           svn_fs_delete()
 206
 207             Same logic as above, except that because these operations
 208             can operate on entire trees,  *multiple* lock-tokens might
 209             need to be checked in the access descriptor.
 210
 211           svn_fs_commit_txn()
 212
 213             Same logic, but this is the "final" check.  This function
 214             already briefly locks the revisions-table in order to do a
 215             final out-of-date check on everything.  In that same vein,
 216             it needs to briefly lock the locks-table, and verify every
 217             single lock.
 218
 219
 220       5.  auto-expiration of locks
 221
 222           The common code which reads locks should be implemented in a
 223           special way: whenever a lock is read, lock expiration should
 224           be checked.  If a lock has expired, then the lock should be
 225           removed, and the caller (doing the read operation) should
 226           get nothing back.
 227
 228           As discussed on the list -- the svn_fs_lock() command should
 229           take an optional argument for the 'expiration-date' field.
 230           But this field should *never* be used by anything other than
 231           mod_dav_svn responding to generic DAV clients.  We don't
 232           want to expose this feature to the svn client.
 233
 234
 235
 236    D. Configurable Mechanisms
 237
 238       1. New "pre-" hook scripts
 239
 240         a. pre-lock
 241
 242         b. pre-unlock
 243
 244       2. New "post-" hook scripts
 245
 246         a. post-lock
 247
 248         b. post-unlock
 249
 250
 251    E. Lock manipulation with server tools
 252
 253       1. 'svnlook listlocks'
 254
 255       2. 'svnadmin unlock'
 256