[GitRepository] Add #git_transaction method

And also defines the following private helper methods and constants:

- `LOCKFILE_DIR`         # Where the locks are stored
- `#git_lock_filename`   # name of the lockfile for this record
- `#acquire_git_lock`    # fetches a lock for the instance (one per)
- `#release_git_lock`    # releases existing lock for other processes

`#git_transaction` is meant to be a multi-purpose method for dealing
with any file system changes so that only one process is able to
interact with it at a time.  According to the docs (`ri File#flock`),
`File#flock(FILE::LOCK_EX)` should block until the lock is available for
the process, so the first process to acquire the lock will process
first.

The method is also designed so that nested `#git_transaction` calls will
no-op and not release the lock pre-maturely.  This is important for
running multiple actions that by design need to happen by a single
process, but the sub actions are also configured to use the lock.

Implementation of this method will be done in a followup commit, but the
method is also meant to be a public interface so that when existing
methods implement this method, locks will work just fine with user
defined `git_transaction` blocks as well as with GitRepository method
API.

Author: NickLaMuro

app/models/git_repository.rb

@@ -4,6 +4,7 @@ class GitRepository < ApplicationRecord
   include AuthenticationMixin
 
   GIT_REPO_DIRECTORY = Rails.root.join('data/git_repos')
+  LOCKFILE_DIR       = GIT_REPO_DIRECTORY.join("locks")
 
   validates :url, :format => URI::regexp(%w(http https file)), :allow_nil => false
 
@@ -86,6 +87,26 @@ def update_repo
     @updated_repo = true
   end
 
+  # Configures a file lock in LOCKFILE_DIR so that only a single process has
+  # access to make changes to the `GitWorktree` at a time.  Assumes the record
+  # has been saved, since there is no way store (clone, fetch, pull, etc.) the
+  # git data to disk if there isn't a `id`.
+  #
+  # Only a single `@git_lock` can be aquired per-process, and do avoid
+  # deadlocks, his method is just a passthrough if `@git_lock` has already been
+  # defined (another method has already started a `git_transaction`.
+  #
+  # This means that you can surround a couple of actions with this method, and
+  # the lock will only be enforced on the top level.
+  #
+  # Return value is the result of the yielded block
+  def git_transaction
+    should_unlock = acquire_git_lock
+    yield
+  ensure
+    release_git_lock if should_unlock
+  end
+
   private
 
   def ensure_refreshed
@@ -155,6 +176,36 @@ def handling_worktree_errors
     raise MiqException::Error, err.message
   end
 
+  def git_lock_filename
+    @git_lock_filename ||= LOCKFILE_DIR.join(id.to_s)
+  end
+
+  def acquire_git_lock
+    return false if defined? @git_lock || !@git_lock.nil?
+
+    FileUtils.mkdir_p(LOCKFILE_DIR)
+
+    @git_lock = File.open(git_lock_filename, File::RDWR | File::CREAT, 0o644)
+    @git_lock.flock(File::LOCK_EX)                         # block waiting for lock
+    @git_lock.write("#{Process.pid} - #{Time.zone.now}\n") # for debugging
+    @git_lock.flush                                        # write current data
+    @git_lock.truncate(@git_lock.pos)                      # clean up remaining chars
+
+    true
+  end
+
+  def release_git_lock
+    return unless defined? @git_lock || @git_lock.nil?
+
+    @git_lock.flock(File::LOCK_UN)
+    @git_lock.close
+
+    # TODO:  unlink?  Unsure how to handle this if other processes are waiting
+    # on this though...
+
+    @git_lock = nil
+  end
+
   def worktree_params
     params = {:path => directory_name}
     params[:certificate_check] = method(:self_signed_cert_cb) if verify_ssl == OpenSSL::SSL::VERIFY_NONE