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

checksums.yaml

@@ -1,7 +1,15 @@
 ---
-SHA1:
-  metadata.gz: 513e0ed61ff5a07f7a0cf4da5ff19264649a8c8f
-  data.tar.gz: 2edc588b822646885c8965f5d10d8bc075849eea
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    Y2ZlMDRhZWIzMzM2NDg0MmRlNmNhY2ZkNzY0Nzc3NjhlYWMwNjJiMw==
+  data.tar.gz: !binary |-
+    NDFhYzZhYmY1Zjg1NzYxMzM4NzA1NzIzMWFkMTJmMDBlYzRjOGE4Yg==
 SHA512:
-  metadata.gz: 034b7dacb2d35b0590b74cf4712ac21a54fb201cf8de6fba36a7a0dbd2d840ad519957b0c96ce2d94f50ec59f9c87c2e89e55bf219d23fef1a93600259301ca1
-  data.tar.gz: 0f22cd5a079652573a20329cf8bf961f0842b3f13c95b8dc2f037b7cf512f0cfc042edbfbe1804fd84ecdf77fc0bfb3df2481c3c39b7f2ce28f2fdd860d417e5
+  metadata.gz: !binary |-
+    MzZmNTNmOGVlYTgyN2I4MjljZGU5ZGZlODJkMTMyM2JlNWQyMmY3OTQxY2Fh
+    NDVjZmYxNmQ1OGNiMTA5ODUwM2U5ZjJlMmEzMjY4MmMyOWY4Y2M0ZmI5YzJj
+    OTU5MDQ0MzMxODk4NGNjMGI3Yzk2ZjYxZjc4ODkyODU0MGNhM2Y=
+  data.tar.gz: !binary |-
+    MDcxOWE3OTFkNzQ3ODk1MTVhYzFjYTlmMWNiNGM4ZmU5N2UzMDc3M2U5Zjkz
+    YTU5MDVhM2JmODQ0ZTgzYmVkZjdiNDRhZWE0ZDI0YjQwYjBkNWEzZGEzOGQw
+    YWE3OTE2ODlmODc3ZjY2YTE1ODBjYzcxNmY4M2M0MTJkMTVhMWY=

data/.gitignore

@@ -3,7 +3,7 @@
 .bundle
 .config
 .yardoc
-Gemfile.lock
+.ruby-version
 InstalledFiles
 _yardoc
 coverage
@@ -12,11 +12,10 @@ lib/bundler/man
 pkg
 rdoc
 spec/reports
+spec/support/database.yml
 test/tmp
 test/version_tmp
 tmp
-*.bundle
-*.so
-*.o
-*.a
-mkmf.log
+bin/
+log/
+/Gemfile.lock

data/.rspec

@@ -0,0 +1 @@
+--colour

data/.travis.yml

@@ -0,0 +1,19 @@
+language: ruby
+rvm:
+  - 2.1.2
+  - 2.0.0
+  - 1.9.3
+env:
+  - DB=mysql
+  - DB=postgres
+before_script:
+  - cp spec/support/database.travis.yml spec/support/database.yml
+  - mysql -e 'create database double_entry_test;'
+  - psql -c 'create database double_entry_test;' -U postgres
+script:
+  - rake spec
+  - ruby script/jack_hammer -t 2000
+gemfile:
+  - gemfiles/Gemfile.rails-3.2.0
+  - gemfiles/Gemfile.rails-4.0.0
+  - gemfiles/Gemfile.rails-4.1.0

data/.yardopts

@@ -0,0 +1,2 @@
+--markup markdown
+- LICENSE.md

data/Gemfile

@@ -1,4 +1,3 @@
 source 'https://rubygems.org'
 
-# Specify your gem's dependencies in double_entry.gemspec
 gemspec

data/LICENSE.md

@@ -0,0 +1,19 @@
+Copyright © 2014 Envato Pty Ltd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -1,29 +1,236 @@
 # DoubleEntry
 
-TODO: Write a gem description
+[![Gem Version](https://badge.fury.io/rb/double_entry.svg)](http://badge.fury.io/rb/double_entry)
+[![Build Status](https://travis-ci.org/envato/double_entry.svg)](https://travis-ci.org/envato/double_entry)
+[![Code Climate](https://codeclimate.com/github/envato/double_entry.png)](https://codeclimate.com/github/envato/double_entry)
+
+![Show me the Money](http://24.media.tumblr.com/tumblr_m3bwbqNJIG1rrgbmqo1_500.gif)
+
+Keep track of all the monies!
+
+DoubleEntry is an accounting system based on the principles of a
+[Double-entry Bookkeeping](http://en.wikipedia.org/wiki/Double-entry_bookkeeping_system)
+system.  While this gem acts like a double-entry bookkeeping system, as it creates
+two entries in the database for each transfer, it does *not* enforce accounting rules.
+
+DoubleEntry uses the Money gem to avoid floating point rounding errors.
+
+## Compatibility
+
+DoubleEntry has been tested with:
+
+Ruby Versions: 1.9.3, 2.0.0, 2.1.2
+
+Rails Versions: Rails 3.2.x, 4.0.x, 4.1.x
+
+**Databases Supported:**
+ * MySQL
+ * PostgreSQL
 
 ## Installation
 
-Add this line to your application's Gemfile:
+In your application's `Gemfile`, add:
 
     gem 'double_entry'
 
-And then execute:
+Then run:
+
+    bundle
+    rails generate double_entry:install
+
+Run migration files:
+
+    rake db:migrate
+
+
+## Interface
+
+The entire API for recording financial transactions is available through a few
+methods in the **DoubleEntry** module. For full details on
+what the API provides, please view the documentation on these methods.
+
+A configuration file should be used to define a set of accounts, and potential
+transfers between those accounts.  See the Configuration section for more details.
+
+
+### Accounts
+
+Money is kept in Accounts.
+
+Each Account has a scope, which is used to subdivide the account into smaller
+accounts. For example, an account can be scoped by user to ensure that each
+user has their own individual account.
+
+Scoping accounts is recommended.  Unscoped accounts may perform more slowly
+than scoped accounts due to lock contention.
+
+To get a particular account:
+
+    account = DoubleEntry.account(:spending, :scope => user)
+
+(This actually returns an Account::Instance object.)
+
+See **DoubleEntry::Account** for more info.
+
+
+### Balances
+
+Calling:
+
+    account.balance
+
+will return the current balance for an account as a Money object.
+
+
+### Transfers
+
+To transfer money between accounts:
+
+    DoubleEntry.transfer(20.dollars, :from => account_a, :to => account_b, :code => :purchase)
+
+The possible transfers, and their codes, should be defined in the configuration.
+
+See **DoubleEntry::Transfer** for more info.
+
+
+### Locking
+
+If you're doing more than one transfer in a single financial transaction, or
+you're doing other database operations along with the transfer, you'll need to
+manually lock the accounts you're using:
+
+    DoubleEntry.lock_accounts(account_a, account_b) do
+      # Do some other stuff in here...
+      DoubleEntry.transfer(20.dollars, :from => account_a, :to => account_b, :code => :purchase)
+    end
+
+The lock_accounts call generates a database transaction, which must be the
+outermost transaction.
+
+See **DoubleEntry::Locking** for more info.
+
+
+## Implementation
+
+All transfers and balances are stored in the lines table. As this is a
+double-entry accounting system, each transfer generates two lines table
+entries: one for the source account, and one for the destination.
+
+Lines table entries also store the running balance for the account. To retrieve
+the current balance for an account, we find the most recent lines table entry
+for it.
+
+See **DoubleEntry::Line** for more info.
+
+AccountBalance records cache the current balance for each Account, and are used
+to perform database level locking.
+
+## Configuration
+
+A configuration file should be used to define a set of accounts, optional scopes on
+the accounts, and permitted transfers between those accounts.
+
+The configuration file should be kept in your application's load path.  For example,
+*config/initializers/double_entry.rb*
+
+For example, the following specifies two accounts, account_a and account_b.
+Each account is scoped by User (where User is an object with an ID), meaning
+each user can have their own account of each type.
+
+This configuration also specifies that money can be transferred between the two accounts.
+
+```ruby
+require 'double_entry'
+
+DoubleEntry.accounts = DoubleEntry::Account::Set.new.tap do |accounts|
+  user_scope = lambda do |user_identifier|
+    if user_identifier.is_a?(User)
+      user_identifier.id
+    else
+      user_identifier
+    end
+  end
+
+  accounts << DoubleEntry::Account.new(identifier: :savings,  scope_identifier: user_scope, positive_only: true)
+  accounts << DoubleEntry::Account.new(identifier: :checking, scope_identifier: user_scope)
+end
+
+DoubleEntry.transfers = DoubleEntry::Transfer::Set.new.tap do |transfers|
+  transfers << DoubleEntry::Transfer.new(from: :checking, to: :savings,  code: :deposit)
+  transfers << DoubleEntry::Transfer.new(from: :savings,  to: :checking, code: :withdraw)
+end
+```
+
+## Jackhammer
+
+Run a concurrency test on the code.
+
+This spawns a bunch of processes, and does random transactions between a set
+of accounts, then validates that all the numbers add up at the end.
+
+You can also tell out it to flush out the account balances table at regular
+intervals, to validate that new account balances records get created with the
+correct balances from the lines table.
+
+    ./script/jack_hammer -t 20
+    Cleaning out the database...
+    Setting up 5 accounts...
+    Spawning 20 processes...
+    Flushing balances
+    Process 1 running 1 transfers...
+    Process 0 running 1 transfers...
+    Process 3 running 1 transfers...
+    Process 2 running 1 transfers...
+    Process 4 running 1 transfers...
+    Process 5 running 1 transfers...
+    Process 6 running 1 transfers...
+    Process 7 running 1 transfers...
+    Process 8 running 1 transfers...
+    Process 9 running 1 transfers...
+    Process 10 running 1 transfers...
+    Process 11 running 1 transfers...
+    Process 12 running 1 transfers...
+    Process 13 running 1 transfers...
+    Process 14 running 1 transfers...
+    Process 16 running 1 transfers...
+    Process 15 running 1 transfers...
+    Process 17 running 1 transfers...
+    Process 19 running 1 transfers...
+    Process 18 running 1 transfers...
+    Reconciling...
+    All the Line records were written, FTW!
+    All accounts reconciled, FTW!
+    Done successfully :)
+
+## Future Direction
+
+No immediate to-do's.
+
+## Development Environment Setup
+
+1. Clone this repo.
+
+        git clone git@github.com:envato/double_entry.git && cd double_entry
+
+2. Run the included setup script to install the gem dependencies.
+
+        ./script/setup.sh
+
+3. Install MySQL and PostgreSQL. The tests run using both databases.
+4. Create a database in MySQL.
+
+        mysql -u root -e 'create database double_entry_test;'
 
-    $ bundle
+5. Create a database in PostgreSQL.
 
-Or install it yourself as:
+        psql -c 'create database double_entry_test;' -U postgres
 
-    $ gem install double_entry
+6. Specify how the tests should connect to the database
 
-## Usage
+        cp spec/support/database.example.yml spec/support/database.yml
+        vim spec/support/database.yml
 
-TODO: Write usage instructions here
+7. Run the tests
 
-## Contributing
+        bundle exec rake
 
-1. Fork it ( https://github.com/[my-github-username]/double_entry/fork )
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create a new Pull Request

data/Rakefile

@@ -1,2 +1,14 @@
+require "rspec/core/rake_task"
 require "bundler/gem_tasks"
 
+RSpec::Core::RakeTask.new(:spec) do |t|
+  t.verbose = false
+end
+
+task :default do
+  %w(mysql postgres).each do |db|
+    puts "Running tests with `DB=#{db}`"
+    ENV['DB'] = db
+    Rake::Task["spec"].execute
+  end
+end

data/double_entry.gemspec

@@ -1,22 +1,37 @@
-# coding: utf-8
+# encoding: utf-8
+
 lib = File.expand_path('../lib', __FILE__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
 require 'double_entry/version'
 
-Gem::Specification.new do |spec|
-  spec.name          = "double_entry"
-  spec.version       = DoubleEntry::VERSION
-  spec.authors       = ["Orien Madgwick"]
-  spec.email         = ["_@orien.io"]
-  spec.summary       = "Tools to build your double entry financial ledger"
-  spec.homepage      = "https://github.com/envato/double_entry"
-  spec.license       = "MIT"
+Gem::Specification.new do |gem|
+  gem.name          = 'double_entry'
+  gem.version       = DoubleEntry::VERSION
+  gem.authors       = ['Anthony Sellitti', 'Keith Pitt', 'Martin Jagusch', 'Martin Spickermann', 'Mark Turnley', 'Orien Madgwick', 'Pete Yandall', 'Stephanie Staub']
+  gem.email         = ['anthony.sellitti@envato.com', 'me@keithpitt.com', '_@mj.io', 'spickemann@gmail.com', 'mark@envato.com', '_@orien.io', 'pete@envato.com', 'staub.steph@gmail.com']
+  # gem.description   = %q{}
+  gem.summary       = 'Tools to build your double entry financial ledger'
+  gem.homepage      = 'https://github.com/envato/double_entry'
+
+  gem.files         = `git ls-files`.split($/)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_paths = ['lib']
 
-  spec.files         = `git ls-files -z`.split("\x0")
-  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
-  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
-  spec.require_paths = ["lib"]
+  gem.add_dependency 'money',                 '>= 5.1.0'
+  gem.add_dependency 'encapsulate_as_money'
+  gem.add_dependency 'activerecord',          '>= 3.2.9'
+  gem.add_dependency 'activesupport',         '>= 3.0.0'
+  gem.add_dependency 'railties',              '>= 3.0.0'
 
-  spec.add_development_dependency "bundler", "~> 1.6"
-  spec.add_development_dependency "rake"
+  gem.add_development_dependency 'rake'
+  gem.add_development_dependency 'mysql2'
+  gem.add_development_dependency 'pg'
+  gem.add_development_dependency 'rspec'
+  gem.add_development_dependency 'rspec-its'
+  gem.add_development_dependency 'database_cleaner'
+  gem.add_development_dependency 'generator_spec'
+  gem.add_development_dependency 'machinist'
+  gem.add_development_dependency 'timecop'
 end

data/gemfiles/Gemfile.rails-3.2.0

@@ -0,0 +1,5 @@
+source 'https://rubygems.org'
+
+gemspec :path => '../'
+
+gem 'rails', '~>3.2.0'

data/gemfiles/Gemfile.rails-4.0.0

@@ -0,0 +1,5 @@
+source 'https://rubygems.org'
+
+gemspec :path => '../'
+
+gem 'rails', '~>4.0.0'

data/gemfiles/Gemfile.rails-4.1.0

@@ -0,0 +1,5 @@
+source 'https://rubygems.org'
+
+gemspec :path => '../'
+
+gem 'rails', '~>4.1.0'

data/lib/active_record/locking_extensions.rb

@@ -0,0 +1,61 @@
+# encoding: utf-8
+module ActiveRecord
+
+  # These methods are available as class methods on ActiveRecord::Base.
+  module LockingExtensions
+
+    # Execute the given block within a database transaction, and retry the
+    # transaction from the beginning if a RestartTransaction exception is raised.
+    def restartable_transaction(&block)
+      begin
+        transaction(&block)
+      rescue ActiveRecord::RestartTransaction
+        retry
+      end
+    end
+
+    # Execute the given block, and retry the current restartable transaction if a
+    # MySQL deadlock occurs.
+    def with_restart_on_deadlock
+      begin
+        yield
+      rescue ActiveRecord::StatementInvalid => exception
+        if exception.message =~ /deadlock/i
+          raise ActiveRecord::RestartTransaction
+        else
+          raise
+        end
+      end
+    end
+
+    # Create the record, but ignore the exception if there's a duplicate.
+    def create_ignoring_duplicates!(*args)
+      # Error examples:
+      #   PG::Error: ERROR:  deadlock detected
+      #   Mysql::Error: Deadlock found when trying to get lock
+      #   PG::Error: ERROR:  duplicate key value violates unique constraint
+      #   Mysql2::Error: Duplicate entry 'keith' for key 'index_users_on_username': INSERT INTO `users...
+      begin
+        create!(*args)
+      rescue ActiveRecord::StatementInvalid => exception
+        if  exception.message =~ /duplicate/i
+          # Just ignore it...someone else has already created the record.
+        elsif  exception.message =~ /deadlock/i
+          # Somebody else is in the midst of creating the record. We'd better
+          # retry, so we ensure they're done before we move on.
+          retry
+        else
+          raise
+        end
+      end
+    end
+
+  end
+
+  # Raise this inside a restartable_transaction to retry the transaction from the beginning.
+  class RestartTransaction < RuntimeError
+  end
+
+end
+
+ActiveRecord::Base.extend(ActiveRecord::LockingExtensions)