github-ds 0.2.11 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e66116af0b535ccdf52ef101f485bd38d4bbbc61de8ebee968576006b14fa24d
-  data.tar.gz: 037a17c54393e7a3b276393c521a40a39b891c859b214f440a9a54a0945a6881
+  metadata.gz: 19e5298765d4c64c5b96a860463b3ffbc804b71388cc328a08c39acfbdce5b4b
+  data.tar.gz: 42e94eb85be200d4f9183f406f9c0de52f4d5fd00fa007f82f50f159816b4152
 SHA512:
-  metadata.gz: 4d1f7260b82336ccf53659df796a3b7f013ae39fbcb6f766590f6f853b1e0295679a29c00db35d7919925ccf3953b54fa25d0be5e4c784c4297260c5fec3bd31
-  data.tar.gz: d297712f24a6169185f6a55fa29548e7b417842e4d9919fc23fcaeed0cf0cf72135d3ed225d122f70733c020e9f4a5dec925b995165a1f94737f4dda9642bc8f
+  metadata.gz: 0d0ace44595e6add1f4570b7d22dc9fe01e56172f8f3b63584d558353a1f25afec0ad744f788271b43b0d0e3b8c609d8d720cef5ee12072ab8843dcb70f52b85
+  data.tar.gz: a9c3918434873b9bae164ecf5042cd87154965380d95f476a2ad6b793b8d8200fd529b1d9df0ea8552734379a12ed948844675e0c9e24ea0d2bb814c871948d3

data/.travis.yml

@@ -13,3 +13,5 @@ env:
   - RAILS_VERSION=5.1.5
   - RAILS_VERSION=5.0.6
   - RAILS_VERSION=4.2.10
+services:
+  - mysql

data/github-ds.gemspec

@@ -39,4 +39,6 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "activesupport"
   spec.add_development_dependency "mysql2"
   spec.add_development_dependency "mocha", "~> 1.2.1"
+  spec.add_development_dependency "minitest-focus", "~> 1.1.2"
+  spec.add_development_dependency "pry", "~> 0.12.2"
 end

data/lib/github/ds/version.rb

@@ -1,5 +1,5 @@
 module GitHub
   module DS
-    VERSION = "0.2.11"
+    VERSION = "0.3.0"
   end
 end

data/lib/github/kv.rb

@@ -48,6 +48,7 @@ module GitHub
     KeyLengthError = Class.new(StandardError)
     ValueLengthError = Class.new(StandardError)
     UnavailableError = Class.new(StandardError)
+    InvalidValueError = Class.new(StandardError)
 
     class MissingConnectionError < StandardError; end
 
@@ -252,6 +253,102 @@ module GitHub
       }
     end
 
+    # increment :: String, Integer, expires: Time? -> Integer
+    #
+    # Increment the key's value by an amount.
+    #
+    # key             - The key to increment.
+    # amount          - The amount to increment the key's value by.
+    #                   The user can increment by both positive and
+    #                   negative values
+    # expires         - When the key should expire.
+    # touch_on_insert - Only when expires is specified. When true
+    #                   the expires value is only touched upon
+    #                   inserts. Otherwise the record is always
+    #                   touched.
+    #
+    # Returns the key's value after incrementing.
+    def increment(key, amount: 1, expires: nil, touch_on_insert: false)
+      validate_key(key)
+      validate_amount(amount) if amount
+      validate_expires(expires) if expires
+      validate_touch(touch_on_insert, expires)
+
+      expires ||= GitHub::SQL::NULL
+
+      # This query uses a few MySQL "hacks" to ensure that the incrementing
+      # is done atomically and the value is returned. The first trick is done
+      # using the `LAST_INSERT_ID` function. This allows us to manually set
+      # the LAST_INSERT_ID returned by the query. Here we are able to set it
+      # to the new value when an increment takes place, essentially allowing us
+      # to do: `UPDATE...;SELECT value from key_value where key=:key` in a
+      # single step.
+      #
+      # However the `LAST_INSERT_ID` trick is only used when the value is
+      # updated. Upon a fresh insert we know the amount is going to be set
+      # to the amount specified.
+      #
+      # Lastly we only do these tricks when the value at the key is an integer.
+      # If the value is not an integer the update ensures the values remain the
+      # same and we raise an error.
+      encapsulate_error {
+        sql = GitHub::SQL.run(<<-SQL, key: key, amount: amount, now: now, expires: expires, touch: !touch_on_insert, connection: connection)
+          INSERT INTO key_values (`key`, `value`, `created_at`, `updated_at`, `expires_at`)
+          VALUES(:key, :amount, :now, :now, :expires)
+          ON DUPLICATE KEY UPDATE
+            `value`=IF(
+              concat('',`value`*1) = `value`,
+              LAST_INSERT_ID(IF(
+                `expires_at` IS NULL OR `expires_at`>=:now,
+                `value`+:amount,
+                :amount
+              )),
+              `value`
+            ),
+            `updated_at`=IF(
+              concat('',`value`*1) = `value`,
+              :now,
+              `updated_at`
+            ),
+            `expires_at`=IF(
+              concat('',`value`*1) = `value`,
+              IF(
+                :touch,
+                :expires,
+                `expires_at`
+              ),
+              `expires_at`
+            )
+        SQL
+
+        # The ordering of these statements is extremely important if we are to
+        # support incrementing a negative amount. The checks occur in this order:
+        # 1. Check if an update with new values occurred? If so return the result
+        #    This could potentially result in `sql.last_insert_id` with a value
+        #    of 0, thus it must be before the second check.
+        # 2. Check if an update took place but nothing changed (I.E. no new value
+        #    was set)
+        # 3. Check if an insert took place.
+        #
+        # See https://dev.mysql.com/doc/refman/8.0/en/insert-on-duplicate.html for
+        # more information (NOTE: CLIENT_FOUND_ROWS is set)
+        if sql.affected_rows == 2
+          # An update took place in which data changed. We use a hack to set
+          # the last insert ID to be the new value.
+          sql.last_insert_id
+        elsif sql.affected_rows == 0 || (sql.affected_rows == 1 && sql.last_insert_id == 0)
+          # No insert took place nor did any update occur. This means that
+          # the value was not an integer thus not incremented.
+          raise InvalidValueError
+        elsif sql.affected_rows == 1
+          # If the number of affected_rows is 1 then a new value was inserted
+          # thus we can just return the amount given to us since that is the
+          # value at the key
+          amount
+        end
+      }
+    end
+
     # del :: String -> nil
     #
     # Deletes the specified key. Returns nil. Raises on error.
@@ -311,6 +408,28 @@ module GitHub
       }
     end
 
+    # mttl :: [String] -> Result<[Time | nil]>
+    #
+    # Returns the expires_at time for the specified key or nil.
+    #
+    # Example:
+    #
+    #  kv.mttl(["foo", "octocat"])
+    #    # => #<Result value: [2018-04-23 11:34:54 +0200, nil]>
+    #
+    def mttl(keys)
+      validate_key_array(keys)
+
+      Result.new {
+        kvs = GitHub::SQL.results(<<-SQL, :keys => keys, :now => now, :connection => connection).to_h
+          SELECT `key`, expires_at FROM key_values
+          WHERE `key` in :keys AND (expires_at IS NULL OR expires_at > :now)
+        SQL
+
+        keys.map { |key| kvs[key] }
+      }
+    end
+
   private
     def now
       use_local_time ? Time.now : GitHub::SQL::NOW
@@ -369,6 +488,19 @@ module GitHub
       end
     end
 
+    def validate_amount(amount)
+      raise ArgumentError.new("The amount specified must be an integer") unless amount.is_a? Integer
+      raise ArgumentError.new("The amount specified cannot be 0") if amount == 0
+    end
+
+    def validate_touch(touch, expires)
+      raise ArgumentError.new("touch_on_insert must be a boolean value") unless [true, false].include?(touch)
+
+      if touch && expires.nil?
+        raise ArgumentError.new("Please specify an expires value if you wish to touch on insert")
+      end
+    end
+
     def validate_expires(expires)
       unless expires.respond_to?(:to_time)
         raise TypeError, "expires must be a time of some sort (Time, DateTime, ActiveSupport::TimeWithZone, etc.), but was #{expires.class}"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: github-ds
 version: !ruby/object:Gem::Version
-  version: 0.2.11
+  version: 0.3.0
 platform: ruby
 authors:
 - GitHub Open Source
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2019-07-25 00:00:00.000000000 Z
+date: 2019-08-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -123,6 +123,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 1.2.1
+- !ruby/object:Gem::Dependency
+  name: minitest-focus
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.1.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.1.2
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.12.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.12.2
 description: A collection of libraries for working with SQL on top of ActiveRecord's
   connection.
 email: