riak-ruby-ledger 0.0.4 → 0.0.5

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    NTFkZWMxYzc0MDM4MzdjYWZiYzY3ZGVmOWY1MGNmYTczMjNiZDgzMA==
+    YmFiZWE5ODMwODQwODRiYzI3YjBjM2Y5ZDAwMmM0NzI4Y2ZhZDZlNA==
   data.tar.gz: !binary |-
-    MzFlMzBlYzM0MDYwYWU1OGVkNWM0MDRhZGM4NDhmMjIyZDA5OTQ4Mw==
+    ZDNhNDI3MzA5NWZjY2U3NGRhYjAxNGMzYzVhOTEwMGUzZTZjYTA5OQ==
 SHA512:
   metadata.gz: !binary |-
-    YjYwMWMzNGJjMzg1OTQ3ZGZlNGI5M2VlZjE1NDgzZTc1YzQzOGJhMzU4MDhh
-    MmRkY2U3ZWRhYTU0M2Y4MmIzMjdhMTc5NTZkNDdlMTRhMmU2YTc0NTU0ZWZk
-    ZDBjNzJjMjc1M2U4MWE2NTY0ZDdkZjA1MTQyYTU3MTljODEwNDY=
+    YjI5MzU1MzVhYzZhZDY4Y2UwMzJiNGJkMDc3YjdjY2JmNmU5MTM4MzM4ZjQ3
+    OTRjYjI5Mzg5NTI4ZGIxY2M5MjUwNmY3YWVlZmRhNDI2OWViZmIzZWZhYjQw
+    ODE1NTFhYWQyM2YwZDU0OGVhYzQyYjUxMTgxZjRiMTcwZmNmNGE=
   data.tar.gz: !binary |-
-    Y2QxZDNlNWFmOWYyY2E2YjgzM2U4NjlhYWYzNDFkZmY5OTI2YTgyZWJhZDMy
-    ZWY0MDc0ODkyZjBmODU0MTFiMDNlOTdhNjRhOTE5NjE4YzE5NjE1ZjYyNjg4
-    MWIxNzc0M2Q2ODg5ZjEwMGQxYzNlYzUyYTdjMDRmYmU4NmI2YmI=
+    ZjRmNjQ3NmJhNzlmNTBjMWNmMGM2ZWFhNWRhNjJiMGQxMzFhNmIzYzI1M2Fk
+    MGM2YzU1YWEwNzRmYzYxYTVmMzdhYzc2NTFhNzdiMjZhNDNiYTliMjQwNjFj
+    MThjZTAxMzc2MDFhMTk5ODdiZjM5NWY2ZDJiYzcyZjg4NDc1MTM=

data/README.md

@@ -1,49 +1,94 @@
 # Riak-Ruby-Ledger
 
-A PNCounter CRDT with ledger transaction ids for tunable write idempotence
+An alternative to Riak Counters with idempotent writes within a client defined window.
 
-## Summary of Functionality
+# Summary
 
-### What does it do?
+### Quick Links
 
-This gem attempts to provide a tunable Counter option by combining non-idempotent GCounters and a partially idempotent GSet for calculating a running counter or ledger.
+Below are a few documents that are relevant to this gem, **please read before considering using this gem for anything important**.
 
-#### Zero Transaction History
-CRDT PNCounters (two GCounters) such as Riak Counters are non-idempotent, and store nothing about a counter transaction other than the final value. As such it doesn't make sense to use them to store any counter that needs to be accurate.
+##### Riak Ruby Ledger Docs
 
-#### Entire Transaction History
-Another approach would be to use a CRDT GSet to store the entire set of transactions, and calculate the current value from the unique list of transaction ids. While accurate, this isn't feasible for many use cases do the space it consumes.
+Document Link | Description
+--- | ---
+[[docs/riak_counter_drift.md]](https://github.com/drewkerrigan/riak-ruby-ledger/blob/master/docs/riak_counter_drift.md) | Why Riak Counters may or may not work for your use case (Counter Drift).
+[[docs/implementation.md]](https://github.com/drewkerrigan/riak-ruby-ledger/blob/master/docs/implementation.md) | Implementation details about this gem as well as some of the reasoning behind the approach.
+[[docs/usage.md]](https://github.com/drewkerrigan/riak-ruby-ledger/blob/master/docs/usage.md) | Suggested usage of this gem from your application, and implications of changing various settings.
+[[docs/release_notes.md](https://github.com/drewkerrigan/riak-ruby-ledger/blob/master/docs/release_notes.md)] | Information about what changed in each version
 
-#### Tunable Transaction History
-By allowing clients to set how many transactions to keep in the counter object as well as set a retry policy on the Riak actions performed on the counter, a good balance can be achieved. The `Riak::Ledger` class in this gem can be instantiated with the following options:
+### Counter Drift
 
-```
-:actor => Actor ID, one per thread or serialized writer
-:history_length => Number of transactions to store per actor per type (credit or debit)
-:retry_count => Number of times to retry Riak requests if they fail
-```
+**Why shouldn't I use Riak Counters?**
+
+CRDT PNCounters (two plain GCounters) such as Riak Counters are non-idempotent and store nothing about a counter transaction other than the final value. This means that if an increment operation fails in any number of ways (500 response from server, process that made the call dies, network connection is interrupted, operation times out, etc), your application now has no idea whether or not the increment actually happened.
+
+**What is Counter Drift?**
+
+In the above situation of a failed increment operation, your application has two choices:
+
+1. Retry the operation: This could result in the operation occuring twice causing what is called **positive counter drift**
+2. Don't retry the operation: This could result in the operation never occuring at all causing **negative counter drift**
+
+As such it doesn't make sense to use plain GCounters or PNCounters to store any counter that needs to be accurate.
+
+***More information about Riak Counters and Drift***: [[docs/riak_counter_drift.md]](https://github.com/drewkerrigan/riak-ruby-ledger/blob/master/docs/riak_counter_drift.md)
+
+### Implementation
+
+The data type implemented is a PNCounter CRDT with an ordered array of transactions for each GCounter actor. Transaction ids are stored with the GCounter, so operations against this counter are idempotent while the transaction remains in any actor's array.
+
+**High Level API**
+
+Function | Description
+--- | ---
+`Riak::Ledger.new` | Creates a new Ledger instance
+`Riak::Ledger.find!` | Finds an existing Ledger in Riak, merges it locally, and then writes the merged value back to Riak
+`#credit!`, `#debit!`, `#update!` | Reads the existing state of the ledger from Riak, merges it locally, and adds a new `transaction` and positive or negative `value`
+
+**Ledger Options**
+
+Name | Description
+--- | ---
+`:retry_count`[Integer] | When a write to Riak is a "maybe" (500, timeout, or any other error condition), resubmit the request `:retry_count` number of times, and return false if it is still unsuccessful
+`:history_length`[Integer] | Keep up to `:history_length` number of transactions in each actor's section of the underlying GCounter. When the (`:history_length` + 1)th transaction is written then merged, add the oldest transaction's value to the actor's total
+
+***More information about the implementation and how edge cases can be avoided***: [[docs/implementation.md]](https://github.com/drewkerrigan/riak-ruby-ledger/blob/master/docs/implementation.md)
+
+### Suggested Usage and Configuration
+
+Depending on your use case, you may want to tweak the configuration options `:history_length` and `:retry_count`.
+
+The default `:history_length` is 10. This means that if a transaction fails, but your application is unable to determine whether or not the counter was actually incremented, you have a buffer space or window of 9 additional transactions on that counter before you can no longer retry the original failed transaction without assuming counter drift is happening.
 
-Furthermore, each `#credit!` and `#debit!` action against the ledger takes an (assumed) globally unique `transaction` id that is determined by your application.
+The default `:retry_count` is also 10. This means that if a transaction fails, the actor that attempted the transaction will continue trying 9 more times. If the request to change the counter still fails after the 10th try, the operation will return `false` for failure. At this point your application can attempt to try the transaction again, or return a failure to the user with a note that the transaction will be retried in the future.
 
-These options combined give you reasonable guarentees that a single transaction can be retried per counter continually as long as less than X number of other transactions are applied to the same counter (where X is the `:history_length`).
+An example of a failure might look like the following:
 
-The gem will automatically retry `:retry_count` number of times, and if it still fails after that you can define a secondary retry or reconciliation policy within your application to deal with the failure, although if the actions are continually failing, it is possible that something is systematically wrong with your Riak cluster.
+1. transaction1 fails with actor1, and because of the nature of the failure, your application is unsure whether or not the counter was actually incremented.
 
-### What doesn't it do?
+	1. If your `:retry_count` is low, you can quickly determine in your application that something went wrong, and inform the user that the transaction was unsuccessful for now, but will be attempted later
+	2. If your `:retry_count` is high, the user will be kept waiting longer, but the odds of the transaction eventually working are higher
+2. If after the initial retries, the transaction was still a failure, your application must decide what to do next
 
-This gem cannot guarentee transaction idempotence over the entire lifetime of a counter for greater than `:history_length` number of transactions. If your application requires this level of idempotence on a counter, a slower reading GSet based implementation may be right for you, but keep in mind this will penalize the most active users of the counter.
+	1. If your `:history_length` is low, your options are limited. You must continue to retry that same failed transaction for that user (using any available actor) until it is successful. If you allow additional transactions to take place on the same counter before retrying, you run a high risk of counter drift.
+	2. If your `:history_length` is medium-high, then you have an allowance of (`:history_length` - 1) additional transactions for that counter before you run the risk of counter drift.
 
-### Further Reading
+**Note**
 
-In order to attempt to best meet the requirements of *most* counters that cannot be satisfied with Riak Counters, this gem implements approach ***2b*** described in the [Problem Statement](https://github.com/drewkerrigan/riak-ruby-ledger/tree/ack-refactor#problem-statement) below as it should handle the most likely retry scenarios for most applications.
+This gem cannot guarentee transaction idempotence of a counter for greater than `:history_length` number of transactions.
 
-CRDT paper from Shapiro et al. at INRIA [http://hal.upmc.fr/docs/00/55/55/88/PDF/techreport.pdf](http://hal.upmc.fr/docs/00/55/55/88/PDF/techreport.pdf)
+***More information about configuration and implications of changing various settings***: [[docs/usage.md]](https://github.com/drewkerrigan/riak-ruby-ledger/blob/master/docs/usage.md)
 
-Riak Counters: [http://basho.com/counters-in-riak-1-4/](http://basho.com/counters-in-riak-1-4/)
+### Additional Reading
 
-Other Riak Data Types: [github.com/basho/riak_dt](https://github.com/basho/riak_dt)
+Document Link | Description
+--- | ---
+[[http://hal.upmc.fr/docs/00/55/55/88/PDF/techreport.pdf](http://hal.upmc.fr/docs/00/55/55/88/PDF/techreport.pdf)] | CRDT paper from Shapiro et al. at INRIA
+[[http://basho.com/counters-in-riak-1-4/](http://basho.com/counters-in-riak-1-4/)] | Riak Counters
+[[github.com/basho/riak_dt](https://github.com/basho/riak_dt)] | Other Riak Data Types
 
-## Installation
+# Installation
 
 Add this line to your application's Gemfile:
 
@@ -57,7 +102,7 @@ Or install it yourself as:
 
     $ gem install riak-ruby-ledger
 
-## Usage
+# Usage
 
 ### Initialize
 
@@ -65,7 +110,7 @@ Or install it yourself as:
 require 'riak' # riak-client gem
 require 'ledger' # riak-ruby-ledger gem
 
-# Name your thread
+# Name each of your threads
 Thread.current["name"] = "ACTOR1"
 
 # Create a Riak::Client instance
@@ -148,272 +193,10 @@ ledger.has_transaction? "txn6" #true
 ledger.delete()
 ```
 
-## Problem Statement
-
-### When to use Riak Counters
-
-Riak Counters are very well suited for certain problems:
-
-* Facebook likes
-* Youtube views
-* Reddit upvotes
-* Twitter followers
-* Any non-critical counts
-    * Counts that do not adversely affect applications or users when off by a few
-
-### When not to use Riak Counters
-
-* Currency (virtual or real) balances
-* Metrics that result in charging a customer
-    * Keeping track of how many calls are made to a paid API endpoint
-    * Storage used by a user
-* Real-time counts
-* Any critical counts
-    * Counts that must be accurate
-
-### Counter Drift
-
-Riak Counters as currently implemented are not ***idempotent***. This simply means that you cannot retry the same increment or decrement operation more than once.
-
-Take the following scenario into consideration:
-
-1. User buys an in-game item that costs 50 gold, and has a current balance of 100 gold
-2. Application server attempts to debit user's account 50 gold
-    a. If Riak successfully returns 200 response code, no problem!
-    b. If Riak returns 500 (or any other error code), we don't have any way of knowing whether or not the operation succeeded
-    c. If the application server fails at any point in the execution, we also don't have a good way of knowing whether or not the operation succeeded
-
-In the case of 2b and 2c, we have the following choices:
-
-* Retry the operation (Risk absolute positive drift)
-    * If the original counter decrement was successful, we have now debited the user's balance twice, thereby charging them 100 gold for a 50 gold item
-* Never retry (Risk absolute negative drift)
-    * If the original counter decrement was unsuccessful, we gave the user an item for free
-
-## Idempotent Counters
-
-There are several approaches to making counters varying degrees of idempotent, the ones relative to the goals of this gem described here.
-
-### Definitions
-
-* ***Transaction id***: Globally unique externally generated transaction id that is available per counter action (increment or decrement)
-* ***Actor***: A thread, process, or server that is able to serially perform actions (a single actor can never perform actions in parallel with itself)
-* ***Sibling***: In Riak, when you write to the same key without specifying a vector clock, a sibling is created. This is denoted below as `[...sibling1..., ...sibling2...]`.
-
-### Approach 1: Ensure idempotent counter actions at any time, by any actor
-
-This is possible if the entire transaction history is stored inside of the counter object:
-
-Actor 1 writes txn1: 50
-
-```
-{"txn1": 50}
-```
-
-Actor 2 writes txn1: 50, txn2: 100
-
-```
-[
-	#sibling 1
-	{"txn1": 50},
-	#sibling 2
-	{"txn1": 50, "txn2": 100}
-]
-```
-
-Actor 1 reads and merges value
-
-```
-{"txn1": 50, "txn2": 100}
-```
-
-Total: 150
-
-This is not a counter, but a ***GSet***, because the entire set of transactions needs to be stored with the object. The total for a counter is defined by the sum of the entire set of values
-
-***Pros***: 
-
-* Retry any action at any time by any actor in the system.
-* Optimize for writes: No need to read the value prior to writing a new transaction.
-
-***Cons***: 
-
-* GSet sizes can become too large for ruby to handle. If more than ~1000 transactions are expected for a single counter, this approach should not be used
-
-
-### Approach 2a: Ensure idempotent counter actions by any actor, for the current transaction
-
-In this approach, the transaction id is stored per actor for the most recently written transaction
-
-Actor 1 writes txn1: 50
-
-```
-Actor1: {"total": 0} {"txn1": 50}
-```
-
-Actor 2 attempts to write txn1: 50
-
-Actor 2 reads current value and sees that txn1 has already been written, ignores it's own txn1
-
-Actor 2 writes merged value
-
-```
-Actor1: {"total": 0} {"txn1": 50}
-```
-
-Actor 2 Writes txn2: 100
-
-```
-Actor1: {"total": 0} {"txn1": 50}
-Actor2: {"total": 0} {"txn2": 100}
-```
-
-Actor 2 Reads current value, and writes txn3: 10 along with it's own merged data
-
-```
-Actor1: {"total": 0} {"txn1": 50}
-Actor2: {"total": 100} {"txn3": 10}
-```
-
-Actor 1 reads and merges value
-
-```
-Actor1: {"total": 0} {"txn1": 50}
-Actor2: {"total": 100} {"txn3": 10}
-```
-
-Total: 160
-
-***Pros***: 
-
-* Retry an action with any actor in the system, assuming the actions are serialized per counter
-* Optimize for reads: Since a very small amount of data is stored in the counter, reads should be very fast
-
-***Cons***: 
-
-* Counter drift is a possibility in the case where transaction 1 fails, several other transactions succeed without retrying transaction 1, and then transaction 1 is tried again
-
-### Approach 2b: Ensure idempotent counter actions by any actor, for the previous `X` transactions
-
-This approach is the same as 2a, but instead of only storing the most previous transaction, we store the most previous `X` transactions. In this example we'll use X=5
-
-Actor 1 writes txn1: 50, txn2: 10, txn3: 100 (order is preserved using an array instead of a hash for transactions)
-
-```
-Actor1: {"total": 0} [["txn1", 50], ["txn2", 10], ["txn3", 100]]}
-```
-
-Actor 2 attempts to write txn1: 50
-
-Actor 2 reads current value and sees that txn1 has already been written, ignores it's own txn1
-
-Actor 2 writes merged value
-
-```
-Actor1: {"total": 0} [["txn1", 50], ["txn2", 10], ["txn3", 100]]
-```
-
-Actor 2 Writes txn4: 100
-
-```
-Actor1: {"total": 0} [["txn1", 50], ["txn2", 10], ["txn3", 100]]
-Actor2: {"total": 0} [["txn4", 100]]
-```
-
-Actor 1 Writes txn5: 20, txn6: 20
-
-```
-Actor1: {"total": 0} [["txn1", 50], ["txn2", 10], ["txn3", 100], ["txn5", 20], ["txn6", 20]]
-Actor2: {"total": 0} [["txn4", 100]]
-```
-
-Actor 1 Writes txn7: 30, and writes it's own merged data
-
-```
-Actor1: {"total": 50} [["txn2", 10], ["txn3", 100], ["txn5", 20], ["txn6", 20], ["txn7", 30]]
-Actor2: {"total": 0} [["txn4", 100]]
-```
-
-Actor 1 reads and merges value
-
-```
-Actor1: {"total": 50} [["txn2", 10], ["txn3", 100], ["txn5", 20], ["txn6", 20], ["txn7", 30]]
-Actor2: {"total": 0} [["txn4", 100]]
-```
-
-Total: 330
-
-***Pros***: 
-
-* Retry an action with any actor in the system, for the last X actions
-* Optimize for reads: Since a very small amount of data is stored in the counter, reads should be very fast
-
-***Cons***: 
-
-* Counter drift is a possibility in the case where transaction 1 fails, X + 1 actions occur, and transaction 1 is retried
-
-### Approach 3: Ensure idempotent counter actions by a single actor, for the current transaction
-
-In this approach, a globally unique transaction id is no longer required, because we are assuming that only a single actor can ever be responsible for a single transaction
-
-Actor 1 writes request1: 50, the request shows an error, but the write actually occurred in Riak
-
-```
-Actor1: {"total": 0} {"request1": 50}
-```
-
-Actor 1 retries request1: 50, the request succeeds, but since request1 is already there, it is ignored and returns a success to the client
-
-```
-Actor1: {"total": 0} {"request1": 50}
-```
-
-Actor 1 writes request2: 100, the request succeeds
-
-```
-Actor1: {"total": 50} {"request2": 100}
-```
-
-Actor 2 writes request3: 10. Since request ids are only unique to the actor, no cross-actor uniqueness check can be made.
-
-```
-Actor1: {"total": 50} {"request2": 100}
-Actor2: {"total": 0} {"request3": 10}
-```
-
-Actor 2 Writes request4: 100
-
-```
-Actor1: {"total": 50} {"request2": 100}
-Actor2: {"total": 10} {"request4": 100}
-```
-
-Actor 1 reads and merges value
-
-```
-Actor1: {"total": 50} {"request2": 100}
-Actor2: {"total": 10} {"request4": 100}
-```
-
-Total: 260
-
-***Pros***: 
-
-* No reliance on an external globally unique transaction id
-* Optimize for reads: Since a very small amount of data is stored in the counter, reads should be very fast
-
-***Cons***: 
-
-* Counter drift is a possibility if any action is retried by someone other than the current actor during it's current transaction
-
-## Conclusion
-
-In order to attempt to best meet the requirements of *most* counters that cannot be satisfied with Riak Counters, this gem implements approach ***2b*** as it should handle the most likely retry scenarios for most applications.
-
-## Contributing
+# Contributing
 
 1. Fork it
 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 new Pull Request
+5. Create new Pull Request

data/docs/implementation.md

@@ -0,0 +1,366 @@
+## Implementation
+
+### Summary
+
+The data type implemented is a PNCounter CRDT with an ordered array of transactions for each GCounter actor. Transaction ids are stored with the GCounter, so operations against this counter are idempotent while the transaction remains in any actor's array.
+
+**High Level API**
+
+Function | Description
+--- | ---
+`Riak::Ledger.new` | Creates a new Ledger instance
+`Riak::Ledger.find!` | Finds an existing Ledger in Riak, merges it locally, and then writes the merged value back to Riak
+`#credit!`, `#debit!`, `#update!` | Reads the existing state of the ledger from Riak, merges it locally, and adds a new `transaction` and positive or negative `value`
+
+**Ledger Options**
+
+Name | Description
+--- | ---
+`:retry_count`[Integer] | When a write to Riak is a "maybe" (500, timeout, or any other error condition), resubmit the request `:retry_count` number of times, and return false if it is still unsuccessful
+`:history_length`[Integer] | Keep up to `:history_length` number of transactions in each actor's section of the underlying GCounter. When the (`:history_length` + 1)th transaction is written then merged, add the oldest transaction's value to the actor's total
+
+### GCounters
+
+A typical GCounter data structure looks something like this:
+
+```
+{
+    "actor1": 10,
+    "actor2": 20,
+    "actor3": 5
+}
+```
+
+Since no actor can affect any other actor's total, this is a safe way to increment a single number in a concurrent way. The total value of this counter is defined by the totals of all actors summed
+
+### PNCounters
+
+Because GCounters only allow for a counter to increment, a simple way to allow for decrements is to use two GCounters. A PNCounter is defined by two GCounters, one for increments, and one for decrements.
+
+```
+{
+    "p": <GCounter>,
+    "n": <GCounter>,
+}
+```
+
+"p" is for positive, and "n" is for negative, so the current value of a PNCounter is defined by P minus N.
+
+### TPNCounter and TGCounter (unique to this gem and its functionality)
+
+For idempotent operations over a limited window of transactions, an array of transactions can be stored with each actor's counter value. The mechanics of the GCounter are unchanged, but the method with which the single total value for an actor gets incremented is dependent upon the current size of the transaction list.
+
+The new data structure for the GCounter portion of this gem's PNCounter looks like this:
+
+```
+{
+    "actor1": {"total": 10, "txns": [["txn1": 5],["txn2": 1],["txn3":10]]},
+    "actor2": {"total": 20, "txns": [["txn4": 5],["txn5": 1],["txn6":10]]},
+    "actor3": {"total": 5, "txns": [["txn7": 5],["txn8": 1],["txn9":10]]}
+}
+```
+
+Since these are not true PN or G counters, in the code they are named `Riak::CRDT::TPNCoutner` and `Riak::CRDT::TGCounter` (T for transaction)
+
+#### History Length
+
+The history length option determines the maximum length of the transaction array per actor before that actor will start removing (oldest first) transactions from its list. Take the following code example into consideration:
+
+For this example, the `:history_length` is lowered to 3 so it gets reached faster.
+
+```
+options = {:history_length => 3}
+ledger = Riak::Ledger.new(client["ledgers"], "player_2", options)
+
+ledger.credit!("txn1", 10)
+ledger.credit!("txn2", 10)
+ledger.credit!("txn3", 10)
+ledger.credit!("txn4", 10)
+ledger.credit!("txn5", 10)
+ledger.credit!("txn6", 10)
+
+ledger.value #60
+
+ledger.has_transaction? "txn1" #false
+ledger.has_transaction? "txn2" #false
+ledger.has_transaction? "txn3" #true
+
+# txn3 is still in the history because the most previous write does not trigger a merge of the actor's total
+# Performing a find! will trigger the merge however
+ledger = Riak::Ledger.find!(client["ledgers"], "player_2", options)
+
+ledger.has_transaction? "txn3" #false
+ledger.has_transaction? "txn4" #true
+ledger.has_transaction? "txn5" #true
+ledger.has_transaction? "txn6" #true
+```
+
+#### Edge Case: Duplicates
+
+**First line of defense**
+
+Before every write, the Ledger class will read the current value of the counter from Riak, if it already exists, the operation will not continue because the transaction has already been placed.
+
+It is possible to have duplicate transactions in across multiple actors however if the following happens:
+
+1. Actor 1 attempts to write transaction1, but is taking a long time to do so for some reason
+2. Your application decides that Actor 1 has taken too long, and issues the same transaction to Actor 2 for writing
+3. Since Actor 1's version of the transaction is still in flight, it could finish successfully while Actor 2's write of transaction1 was also successful
+
+This situation would result in siblings getting created where the merged result ends up being 2 actors with the same transaction1
+
+**Second line of defense**
+
+Upon Actor 2's or Actor 1's next merge, they will find that there is indeed a duplicate, and the following logic happens in order to deal with the duplicate:
+
+1. A merge occurs, and a string comparison on the actors' ids takes place to see who should own the transaction
+
+	1. If Actor 1 is merging, "ACTOR1" is less than "ACTOR2", so Actor 1 gets rid of the transaction without counting it
+	2. If Actor 2 is merging, "ACTOR2" is greater than "ACTOR1", so Actor 2 keeps the transaction, knowing that Actor 1 should delete it
+
+This approach allows for the case in which Actor1 and Actor2 are simultaneously merging, similarly to when they simultaneously added the transaction
+
+It is quite possible however for Actor 1 to become stale, and never get rid of the transaction as they should have...
+
+**Third and final line of defense**
+
+The following workflow should be read in the voice of Actor 2:
+
+If we have held onto a duplicate this long, we meet the following criteria:
+
+1. We are the actor who is supposed to keep this duplicate while the other removes it
+2. We have had enough time to do :history_length number of transactions since the other actor
+    has performed a merge
+3. If they stay dormant and the txn remains untouched there, I shouldn't count it
+4. If they are currently merging and about to count it, I also shouldn't count it for fear of counting it twice,
+5. The third possibility is the following:
+    
+    1. Actor 1 attempts to write transaction 1, it takes a long time, application decides to retry after timeout
+    2. Actor 2 manages to successfully write transaction 1, and then :history_length - 1 more writes and
+      is currently deciding what to do with that transaction ("hmmm, should I count it?")
+    3. While that merge is happening, Actor 1 finally finishes writing transaction 1 and now Actor 2's
+      request is taking a long time for some reason
+    4. While still waiting on Actor 2, Actor 1 performs another merge and sees that Actor 2 has transaction 1
+      knowing it is the inferior actor, Actor 1 removes without counting. But at this stage, Actor 2 wouldn't have known that Actor 1 ever even had transaction 1, and would have correctly counted the value
+
+Given that 5) would actually be handled by the second line of defense, this leaves us with 3) and 4). Since both of those situations result in Actor 1 counting the value, during the compression phases of Actor 2's merge, if the duplicate transaction is about to be deleted, Actor 2 would remove the transaction without counting it towards it's own total.
+
+## Other Possible Approaches to the Idempotent Counter Problem
+
+ There are several approaches to making counters varying degrees of idempotent, the ones relative to the goals of this gem described here.
+
+### Definitions
+
+ * ***Transaction id***: Globally unique externally generated transaction id that is available per counter action (increment or decrement)
+ * ***Actor***: A thread, process, or server that is able to serially perform actions (a single actor can never perform actions in parallel with itself)
+ * ***Sibling***: In Riak, when you write to the same key without specifying a vector clock, a sibling is created. This is denoted below as `[...sibling1..., ...sibling2...]`.
+
+### Approach 1: Ensure idempotent counter actions at any time, by any actor
+
+ This is possible if the entire transaction history is stored inside of the counter object:
+
+ Actor 1 writes txn1: 50
+
+ ```
+ {"txn1": 50}
+ ```
+
+ Actor 2 writes txn1: 50, txn2: 100
+
+ ```
+ [
+ 	#sibling 1
+ 	{"txn1": 50},
+ 	#sibling 2
+ 	{"txn1": 50, "txn2": 100}
+ ]
+ ```
+
+ Actor 1 reads and merges value
+
+ ```
+ {"txn1": 50, "txn2": 100}
+ ```
+
+ Total: 150
+
+ This is not a counter, but a ***GSet***, because the entire set of transactions needs to be stored with the object. The total for a counter is defined by the sum of the entire set of values
+
+ ***Pros***:
+
+ * Retry any action at any time by any actor in the system.
+ * Optimize for writes: No need to read the value prior to writing a new transaction.
+
+ ***Cons***:
+
+ * GSet sizes can become too large for ruby to handle. If more than ~1000 transactions are expected for a single counter, this approach should not be used
+
+
+### Approach 2a: Ensure idempotent counter actions by any actor, for the current transaction
+
+ In this approach, the transaction id is stored per actor for the most recently written transaction
+
+ Actor 1 writes txn1: 50
+
+ ```
+ Actor1: {"total": 0} {"txn1": 50}
+ ```
+
+ Actor 2 attempts to write txn1: 50
+
+ Actor 2 reads current value and sees that txn1 has already been written, ignores it's own txn1
+
+ Actor 2 writes merged value
+
+ ```
+ Actor1: {"total": 0} {"txn1": 50}
+ ```
+
+ Actor 2 Writes txn2: 100
+
+ ```
+ Actor1: {"total": 0} {"txn1": 50}
+ Actor2: {"total": 0} {"txn2": 100}
+ ```
+
+ Actor 2 Reads current value, and writes txn3: 10 along with it's own merged data
+
+ ```
+ Actor1: {"total": 0} {"txn1": 50}
+ Actor2: {"total": 100} {"txn3": 10}
+ ```
+
+ Actor 1 reads and merges value
+
+ ```
+ Actor1: {"total": 0} {"txn1": 50}
+ Actor2: {"total": 100} {"txn3": 10}
+ ```
+
+ Total: 160
+
+ ***Pros***:
+
+ * Retry an action with any actor in the system, assuming the actions are serialized per counter
+ * Optimize for reads: Since a very small amount of data is stored in the counter, reads should be very fast
+
+ ***Cons***:
+
+ * Counter drift is a possibility in the case where transaction 1 fails, several other transactions succeed without retrying transaction 1, and then transaction 1 is tried again
+
+### Approach 2b: Ensure idempotent counter actions by any actor, for the previous `X` transactions
+
+ This approach is the same as 2a, but instead of only storing the most previous transaction, we store the most previous `X` transactions. In this example we'll use X=5
+
+ Actor 1 writes txn1: 50, txn2: 10, txn3: 100 (order is preserved using an array instead of a hash for transactions)
+
+ ```
+ Actor1: {"total": 0} [["txn1", 50], ["txn2", 10], ["txn3", 100]]}
+ ```
+
+ Actor 2 attempts to write txn1: 50
+
+ Actor 2 reads current value and sees that txn1 has already been written, ignores it's own txn1
+
+ Actor 2 writes merged value
+
+ ```
+ Actor1: {"total": 0} [["txn1", 50], ["txn2", 10], ["txn3", 100]]
+ ```
+
+ Actor 2 Writes txn4: 100
+
+ ```
+ Actor1: {"total": 0} [["txn1", 50], ["txn2", 10], ["txn3", 100]]
+ Actor2: {"total": 0} [["txn4", 100]]
+ ```
+
+ Actor 1 Writes txn5: 20, txn6: 20
+
+ ```
+ Actor1: {"total": 0} [["txn1", 50], ["txn2", 10], ["txn3", 100], ["txn5", 20], ["txn6", 20]]
+ Actor2: {"total": 0} [["txn4", 100]]
+ ```
+
+ Actor 1 Writes txn7: 30, and writes it's own merged data
+
+ ```
+ Actor1: {"total": 50} [["txn2", 10], ["txn3", 100], ["txn5", 20], ["txn6", 20], ["txn7", 30]]
+ Actor2: {"total": 0} [["txn4", 100]]
+ ```
+
+ Actor 1 reads and merges value
+
+ ```
+ Actor1: {"total": 50} [["txn2", 10], ["txn3", 100], ["txn5", 20], ["txn6", 20], ["txn7", 30]]
+ Actor2: {"total": 0} [["txn4", 100]]
+ ```
+
+ Total: 330
+
+ ***Pros***:
+
+ * Retry an action with any actor in the system, for the last X actions
+ * Optimize for reads: Since a very small amount of data is stored in the counter, reads should be very fast
+
+ ***Cons***:
+
+ * Counter drift is a possibility in the case where transaction 1 fails, X + 1 actions occur, and transaction 1 is retried
+
+### Approach 3: Ensure idempotent counter actions by a single actor, for the current transaction
+
+ In this approach, a globally unique transaction id is no longer required, because we are assuming that only a single actor can ever be responsible for a single transaction
+
+ Actor 1 writes request1: 50, the request shows an error, but the write actually occurred in Riak
+
+ ```
+ Actor1: {"total": 0} {"request1": 50}
+ ```
+
+ Actor 1 retries request1: 50, the request succeeds, but since request1 is already there, it is ignored and returns a success to the client
+
+ ```
+ Actor1: {"total": 0} {"request1": 50}
+ ```
+
+ Actor 1 writes request2: 100, the request succeeds
+
+ ```
+ Actor1: {"total": 50} {"request2": 100}
+ ```
+
+ Actor 2 writes request3: 10. Since request ids are only unique to the actor, no cross-actor uniqueness check can be made.
+
+ ```
+ Actor1: {"total": 50} {"request2": 100}
+ Actor2: {"total": 0} {"request3": 10}
+ ```
+
+ Actor 2 Writes request4: 100
+
+ ```
+ Actor1: {"total": 50} {"request2": 100}
+ Actor2: {"total": 10} {"request4": 100}
+ ```
+
+ Actor 1 reads and merges value
+
+ ```
+ Actor1: {"total": 50} {"request2": 100}
+ Actor2: {"total": 10} {"request4": 100}
+ ```
+
+ Total: 260
+
+ ***Pros***:
+
+ * No reliance on an external globally unique transaction id
+ * Optimize for reads: Since a very small amount of data is stored in the counter, reads should be very fast
+
+ ***Cons***:
+
+ * Counter drift is a possibility if any action is retried by someone other than the current actor during it's current transaction
+
+## Conclusion
+
+ In order to attempt to best meet the requirements of *most* counters that cannot be satisfied with Riak Counters, this gem implements approach ***2b*** as it should handle the most likely retry scenarios for most applications.