Implementation for "Locking" featureThis document describes proposed implementation details for a newlocking system in Subversion.I. IntroductionII. Client Implementation   A. Overview   B. The "svn:needs-lock" property      1. Property as enforcement system      2. Property as communication system   C. Lock manipulation via client      1. Lock Tokens          Stored as 'entryprops'.  That is, just like          last-changed-rev, last-author, etc., tokens come into the          client with an svn:entry: prefix, are filtered by libsvn_wc,          and stored in .svn/entries.   We'll call the new entryprops          "svn:entry:lock-token", "svn:entry:lock-owner",          "svn:entry:lock-comment and "svn:entry:lock-creation-date".          (In DAV parlance, what          we call 'entryprops' are called 'live props'.)          libsvn_wc stores the other fields of a lock (owner,          comment, creation-date) in the entries file, so that they          are available for the info command.  Note that this          information is only stored if the current WC has a lock on          the file.      2. New client subcommands                   a. Creating a lock             'svn lock' calls new RA->lock() function, which marshals             BASE rev of file to svn_fs_lock().  FS does a             complimentary out-of-dateness check before creating the             lock.  The lock is marshaled back to client, stored in             .svn/entries file.         b. Using a lock            1. Using a lock to Commit               A new RA layer get_commit_editor2() function will be created.               It takes a hash of path -> lock token from the working               copy.  This will be used by the server to check that               the WC locks match the current locks on the paths.  A               flag keep_locks will also be added, specifying whether               the committables should be unlocked after a successful commit.               libsvn_client will collect lock tokens during the               harvesting of commit items.  If --no-unlock was not               specified, unmodified objects will be treated as commit               items if the WC has a lock on them.  A new status flag               in svn_client_commit_info_t indicates that the object               has a lock token.               A new svn_wc_process_committed2 WC function will be               created with a flag indicating whether the lock toke               should be removed as part of the post-commit entry update.            2. Releasing a lock               svn unlock uses the lock token stored in the WC and               issues an ra->unlock command to the server.         c. Breaking a lock            svn unlock --force will first ask the server for a lock            token and use it in the ra->unlock command to break the            lock.         d. Stealing a lock            svn lock --force uses ra->lock with the force argument set            to TRUE to steal a lock.         e. Discovering/examining locks            1. seeing lock tokens in a working copy               The client uses the lock information stored in the               entries file to show lock information with svn info and               svn status.            2. seeing locks in a repository               The server will marshal the lock information as               entryprops when calling the status editor.               svn info URL will use RA->get_lock to get the lock for the               path specified.            3. 'svn update' behavior                A.  At the start of an update, a new version of the                'reporter' vtable is used to describe not only mixed                revnums to the server, but also existing locktokens.                We need to be careful with protocols when marshaling                this new information to older or newer servers.                In ra_svn a new command will be added to the report                command set for this purpose.                B.  If a locktoken is defunct (expired, broken,                whatever), then the server sends a 'deletion' of the                locktoken entryprop, through normal means: the prop                deletion comes into the update_editor, and thus is                removed from .svn/entries.III. Server Implementation   A. Overview   B. Tracking locks      1. Define a lock-token:             UUID            owner            comment [optional]            creation-date            expiration-date [optional]      2. Define a lock-table that maps [fs-path --> lock-token]         Beware the "deletion problem": if a certain path is locked,         then no parent directory of that path can be deleted.         The bad way to solve this problem is to do an O(N) recursive         search of the directory being deleted, making sure no child         is locked.         The good way to solve this problem is to implement the 'lock         table' as a tree.  When an object is locked, we create the         locked path in the lock-tree.  Then, the mere existence of a         directory in the lock-tree means it has at least one locked         child, and cannot be deleted.  This is a much more acceptable         O(logN) search.   C.  How to implement locks in libsvn_fs          This option implies that both BDB and FSFS would need to          implement the 'lock tree' in their own way.  Any user of          libsvn_fs would automatically get lock-enforcement.      1.  Define an API for associating a user with an open          filesystem.  Locks cannot be created/destroyed without a          username, except that the filesystem allows breaking a lock          without a username.      2.  New fs functions for locks:              svn_fs_lock()       --> locks a file              svn_fs_unlock()     --> unlocks a file              svn_fs_get_locks()  --> returns list of locked paths              svn_fs_get_lock()   --> discover if a path is locked            These functions don't do anything special, other than            allow one to create/release/examine locks.  BDB and FSFS            need to implement these functions independently.      3.  Wrap two of the functions in libsvn_repos, to invoke hooks.              svn_repos_fs_lock()              svn_repos_fs_unlock()            As usually, encourage "good citizens" to use these            wrappers, since they'll invoke the new hook scripts.  The            only thing which calls the fs functions directly (and            circumvents hooks) would be a tool like svnadmin (see            'svnadmin unlock' in UI document.)      4.  Teach a number of fs functions to check for locks, and deal          with them:          svn_fs_node_prop()          svn_fs_apply_textdelta()          svn_fs_apply_text()          svn_fs_make_file()          svn_fs_make_dir()            Check to see if the incoming path is locked.  If so, use            the access descriptor to see if the caller has the lock token.              1. check that the lock-token correctly matches the                 lock. (i.e. that the caller isn't using some defunct                 or malformed token).              2. check that the lock owner matches whatever                 authenticated username is currently attached to the fs.          svn_fs_copy()          svn_fs_revision_link()          svn_fs_delete()            Same logic as above, except that because these operations            can operate on entire trees,  *multiple* lock-tokens might            need to be checked in the access descriptor.          svn_fs_commit_txn()            Same logic, but this is the "final" check.  This function            already briefly locks the revisions-table in order to do a            final out-of-date check on everything.  In that same vein,            it needs to briefly lock the locks-table, and verify every            single lock.      5.  auto-expiration of locks          The common code which reads locks should be implemented in a          special way: whenever a lock is read, lock expiration should          be checked.  If a lock has expired, then the lock should be          removed, and the caller (doing the read operation) should          get nothing back.          As discussed on the list -- the svn_fs_lock() command should          take an optional argument for the 'expiration-date' field.          But this field should *never* be used by anything other than          mod_dav_svn responding to generic DAV clients.  We don't          want to expose this feature to the svn client.   D. Configurable Mechanisms      1. New "pre-" hook scripts        a. pre-lock        b. pre-unlock      2. New "post-" hook scripts        a. post-lock        b. post-unlock   E. Lock manipulation with server tools      1. 'svnlook listlocks'      2. 'svnadmin unlock'