double_entry 0.0.1.pre → 0.1.0.pre.pre.alpha

data/lib/double_entry/locking.rb

@@ -0,0 +1,187 @@
+# encoding: utf-8
+module DoubleEntry
+
+  # Lock financial accounts to ensure consistency.
+  #
+  # In order to ensure financial transactions always keep track of balances
+  # consistently, database-level locking is needed. This module takes care of
+  # it.
+  #
+  # See DoubleEntry.lock_accounts and DoubleEntry.transfer for the public interface
+  # to this stuff.
+  #
+  # Locking is done on DoubleEntry::AccountBalance records. If an AccountBalance
+  # record for an account doesn't exist when you try to lock it, the locking
+  # code will create one.
+  #
+  # script/jack_hammer can be used to run concurrency tests on double_entry to
+  # validates that locking works properly.
+  module Locking
+    include Configurable
+
+    class Configuration
+      # Set this in your tests if you're using transactional_fixtures, so we know
+      # not to complain about a containing transaction when you call lock_accounts.
+      attr_accessor :running_inside_transactional_fixtures
+
+      def initialize #:nodoc:
+        @running_inside_transactional_fixtures = false
+      end
+    end
+
+    # Run the passed in block in a transaction with the given accounts locked for update.
+    #
+    # The transaction must be the outermost transaction to ensure data integrity. A
+    # LockMustBeOutermostTransaction will be raised if it isn't.
+    def self.lock_accounts(*accounts)
+      lock = Lock.new(accounts)
+
+      if lock.in_a_locked_transaction?
+        lock.ensure_locked!
+        yield
+      else
+        lock.perform_lock(&Proc.new)
+      end
+    end
+
+    # Return the account balance record for the given account name if there's a
+    # lock on it, or raise a LockNotHeld if there isn't.
+    def self.balance_for_locked_account(account)
+      Lock.new([account]).balance_for(account)
+    end
+
+    class Lock
+      @@locks = Hash.new
+
+      def initialize(accounts)
+        # Make sure we always lock in the same order, to avoid deadlocks.
+        @accounts = accounts.flatten.sort
+      end
+
+      # Lock the given accounts, creating account balance records for them if
+      # needed.
+      def perform_lock(&block)
+        ensure_outermost_transaction!
+
+        unless lock_and_call(&block)
+          create_missing_account_balances
+          unless lock_and_call(&block)
+            raise LockDisaster
+          end
+        end
+      end
+
+      # Return true if we're inside a lock_accounts block.
+      def in_a_locked_transaction?
+        !locks.nil?
+      end
+
+      def ensure_locked!
+        @accounts.each do |account|
+          raise LockNotHeld.new(account) unless have_lock?(account)
+        end
+      end
+
+      def balance_for(account)
+        ensure_locked!
+
+        locks[account]
+      end
+
+      private
+
+      def locks
+        @@locks[Thread.current.object_id]
+      end
+
+      def locks=(locks)
+        @@locks[Thread.current.object_id] = locks
+      end
+
+      def remove_locks
+        @@locks.delete(Thread.current.object_id)
+      end
+
+      # Return true if there's a lock on the given account.
+      def have_lock?(account)
+        in_a_locked_transaction? && locks.has_key?(account)
+      end
+
+      # Raise an exception unless we're outside any transactions.
+      def ensure_outermost_transaction!
+        minimum_transaction_level = Locking.configuration.running_inside_transactional_fixtures ? 1 : 0
+        unless AccountBalance.connection.open_transactions <= minimum_transaction_level
+          raise LockMustBeOutermostTransaction
+        end
+      end
+
+
+      # Start a transaction, grab locks on the given accounts, then call the block
+      # from within the transaction.
+      #
+      # If any account can't be locked (because there isn't a corresponding account
+      # balance record), don't call the block, and return false.
+      def lock_and_call
+        locks_succeeded = nil
+        AccountBalance.restartable_transaction do
+          locks_succeeded = AccountBalance.with_restart_on_deadlock { grab_locks }
+          if locks_succeeded
+            begin
+              yield
+            ensure
+              remove_locks
+            end
+          end
+        end
+        locks_succeeded
+      end
+
+      # Grab a lock on the account balance record for each account.
+      #
+      # If all the account balance records exist, set locks to a hash mapping
+      # accounts to account balances, and return true.
+      #
+      # If one or more account balance records don't exist, set
+      # accounts_with_balances to the corresponding accounts, and return false.
+      def grab_locks
+        account_balances = @accounts.map {|account| AccountBalance.find_by_account(account, :lock => true) }
+
+        if account_balances.any?(&:nil?)
+          @accounts_without_balances = @accounts.zip(account_balances).
+            select  {|account, account_balance| account_balance.nil? }.
+            collect {|account, account_balance| account }
+          false
+        else
+          self.locks = Hash[*@accounts.zip(account_balances).flatten]
+          true
+        end
+      end
+
+      # Create all the account_balances for the given accounts.
+      def create_missing_account_balances
+        @accounts_without_balances.each do |account|
+          # Get the initial balance from the lines table.
+          balance = account.balance
+
+          # Try to create the balance record, but ignore it if someone else has done it in the meantime.
+          AccountBalance.create_ignoring_duplicates!(:account => account, :balance => balance)
+        end
+      end
+    end
+
+    # Raised when lock_accounts is called inside an existing transaction.
+    class LockMustBeOutermostTransaction < RuntimeError
+    end
+
+    # Raised when attempting a transfer on an account that's not locked.
+    class LockNotHeld < RuntimeError
+      def initialize(account)
+        super "No lock held for account: #{account.identifier}, scope #{account.scope}"
+      end
+    end
+
+    # Raised if things go horribly, horribly wrong. This should never happen.
+    class LockDisaster < RuntimeError
+    end
+  end
+end

data/lib/double_entry/month_range.rb

@@ -0,0 +1,92 @@
+# encoding: utf-8
+module DoubleEntry
+  class MonthRange < TimeRange
+
+    class << self
+      def from_time(time)
+        new(:year => time.year, :month => time.month)
+      end
+
+      def current
+        from_time(Time.now)
+      end
+
+      # Obtain a sequence of MonthRanges from the given start to the current
+      # month.
+      #
+      # @option options :from [Time] Time of the first in the returned sequence
+      #   of MonthRanges.
+      # @return [Array<MonthRange>]
+      def reportable_months(options = {})
+        month = options[:from] ? from_time(options[:from]) : earliest_month
+        last = self.current
+        [month].tap do |months|
+          while month != last
+            month = month.next
+            months << month
+          end
+        end
+      end
+
+      def earliest_month
+        from_time(DoubleEntry::Reporting.configuration.start_of_business)
+      end
+    end
+
+    attr_reader :year, :month
+
+    def initialize(options = {})
+      super options
+
+      if options.present?
+        @month = options[:month]
+
+        month_start = Time.local(year, options[:month], 1)
+        @start = month_start
+        @finish = month_start.end_of_month
+
+        @start = MonthRange.earliest_month.start if options[:range_type] == :all_time
+      end
+    end
+
+    def previous
+      if month <= 1
+        MonthRange.new :year => year - 1, :month => 12
+      else
+        MonthRange.new :year => year, :month => month - 1
+      end
+    end
+
+    def next
+      if month >= 12
+        MonthRange.new :year => year + 1, :month => 1
+      else
+        MonthRange.new :year => year, :month => month + 1
+      end
+    end
+
+    def beginning_of_financial_year
+      first_month_of_financial_year = DoubleEntry::Reporting.configuration.first_month_of_financial_year
+      year = (month >= first_month_of_financial_year) ? @year : (@year - 1)
+      MonthRange.new(:year => year, :month => first_month_of_financial_year)
+    end
+
+    alias_method :succ, :next
+
+    def <=>(other)
+      self.start <=> other.start
+    end
+
+    def ==(other)
+      (self.month == other.month) and (self.year == other.year)
+    end
+
+    def all_time
+      MonthRange.new(:year => year, :month => month, :range_type => :all_time)
+    end
+
+    def to_s
+      start.strftime("%Y, %b")
+    end
+  end
+end

data/lib/double_entry/reporting.rb

@@ -0,0 +1,16 @@
+# encoding: utf-8
+module DoubleEntry
+  module Reporting
+    include Configurable
+
+    class Configuration
+      attr_accessor :start_of_business, :first_month_of_financial_year
+
+      def initialize #:nodoc:
+        @start_of_business = Time.new(1970, 1, 1)
+        @first_month_of_financial_year = 7
+      end
+    end
+
+  end
+end

data/lib/double_entry/time_range.rb

@@ -0,0 +1,55 @@
+# encoding: utf-8
+module DoubleEntry
+  class TimeRange
+    attr_reader :start, :finish
+    attr_reader :year, :month, :week, :day, :hour, :range_type
+
+    def self.make(options = {})
+      @options = options
+      case
+        when (options[:year] and options[:week] and options[:day] and options[:hour])
+          HourRange.new(options)
+        when (options[:year] and options[:week] and options[:day])
+          DayRange.new(options)
+        when (options[:year] and options[:week])
+          WeekRange.new(options)
+        when (options[:year] and options[:month])
+          MonthRange.new(options)
+        when options[:year]
+          YearRange.new(options)
+        else
+          raise "Invalid range information #{options}"
+      end
+    end
+
+    def self.range_from_time_for_period(start_time, period_name)
+       case period_name
+         when 'month'
+           DoubleEntry::YearRange.from_time(start_time)
+         when 'week'
+            DoubleEntry::YearRange.from_time(start_time)
+         when 'day'
+           DoubleEntry::MonthRange.from_time(start_time)
+         when 'hour'
+           DoubleEntry::DayRange.from_time(start_time)
+       end
+    end
+
+    def include?(time)
+      (time >= @start) and (time <= @finish)
+    end
+
+    def initialize(options)
+      @year = options[:year]
+      @range_type = options[:range_type] || :normal
+    end
+
+    def key
+      "#{@year}:#{@month}:#{@week}:#{@day}:#{@hour}"
+    end
+
+    def human_readable_name
+      self.class.name.gsub('DoubleEntry::', '').gsub('Range', '')
+    end
+  end
+end

data/lib/double_entry/time_range_array.rb

@@ -0,0 +1,43 @@
+# encoding: utf-8
+module DoubleEntry
+  class TimeRangeArray
+    class << self
+
+      def make(range_type, start, finish = nil)
+        raise "Must specify range for #{range_type}-by-#{range_type} reports" if start == nil
+
+        case range_type
+        when 'hour'
+          make_array HourRange, start, finish
+        when 'day'
+          make_array DayRange, start, finish
+        when 'week'
+          make_array WeekRange, start, finish
+        when 'month'
+          make_array MonthRange, start, finish
+        when 'year'
+          make_array YearRange, start
+        else
+          raise ArgumentError.new("Invalid range type '#{range_type}'")
+        end
+      end
+
+      private
+
+      def make_array(type, start, finish = nil)
+        start = type.from_time(Time.parse(start))
+        finish = type.from_time(Time.parse(finish)) if finish
+
+        loop = start
+        last = finish || type.current
+        results = [loop]
+        while(loop != last) do
+          loop = loop.next
+          results << loop
+        end
+
+        results
+      end
+    end
+  end
+end

data/lib/double_entry/transfer.rb

@@ -0,0 +1,70 @@
+# encoding: utf-8
+module DoubleEntry
+  class Transfer
+    class Set < Array
+      def find(from, to, code)
+        _find(from.identifier, to.identifier, code)
+      end
+
+      def <<(transfer)
+        if _find(transfer.from, transfer.to, transfer.code)
+          raise DuplicateTransfer.new
+        else
+          super(transfer)
+        end
+      end
+
+    private
+
+      def _find(from, to, code)
+        detect do |transfer|
+          transfer.from == from and transfer.to == to and transfer.code == code
+        end
+      end
+    end
+
+    attr_accessor :code, :from, :to, :description, :meta_requirement
+
+    def initialize(attributes)
+      @meta_requirement = []
+      attributes.each { |name, value| send("#{name}=", value) }
+    end
+
+    def process!(amount, from, to, code, meta, detail)
+      if from.scope_identity == to.scope_identity and from.identifier == to.identifier
+        raise TransferNotAllowed.new
+      end
+
+      meta_requirement.each do |key|
+        if meta[key].nil?
+          raise RequiredMetaMissing.new
+        end
+      end
+
+      Locking.lock_accounts(from, to) do
+        credit, debit = Line.new, Line.new
+
+        credit_balance = Locking.balance_for_locked_account(from)
+        debit_balance  = Locking.balance_for_locked_account(to)
+
+        credit_balance.update_attribute :balance, credit_balance.balance - amount
+        debit_balance.update_attribute  :balance, debit_balance.balance  + amount
+
+        credit.amount,  debit.amount  = -amount, amount
+        credit.account, debit.account = from, to
+        credit.code,    debit.code    = code, code
+        credit.meta,    debit.meta    = meta, meta
+        credit.detail,  debit.detail  = detail, detail
+        credit.balance, debit.balance = credit_balance.balance, debit_balance.balance
+
+        credit.partner_account, debit.partner_account = to, from
+
+        credit.save!
+        debit.partner_id = credit.id
+        debit.save!
+        credit.update_attribute :partner_id, debit.id
+      end
+    end
+
+  end
+end