Implementation for "Locking" feature

This document describes proposed implementation details for a new
locking system in Subversion.

I. Introduction

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