numerousapp 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2df08c0abb56a4d38ce98c048fb814a37cb4ca37
-  data.tar.gz: 50b9313c710e3ab6c27a32cd895c10b03671bdfb
+  metadata.gz: 7018d2d603b7836ff5ce90f71f2cdf324ffb60d9
+  data.tar.gz: 4d7b0bd9d9e9d3307b0e68546dfced0e193ff457
 SHA512:
-  metadata.gz: 5e62912986ab1ce0f5377dd5a400c72fe749c61fa886689552cfa7c9e38c2f6747eb089d0d9f32129c669eaeb46990749d1c5dcd0051fdbd6f9b46c275b1d4c3
-  data.tar.gz: f124700210064a362c407fb976272aa874eced217ca947991fb0b2cdb6428dfd47782650efb455b4915eee0e32b2e58a773750d86c6b996c63c9ac796a901492
+  metadata.gz: cb2e36d7ad7e315684c349c757097e1e1094e403535186abb76b874cb7ec804b92b58d7652c837d41cacc89138117bacdf77fafc509f98dff126f3c6a5134681
+  data.tar.gz: 92a86c605f1357060f10a5fc1f0f6b1ddc846b281ab9c61cfd365f5df11a715d61eb25ddf3c5f2b39bc11badb62191eb915b80c6dbc08b340c0e645d54cd50f5

data/lib/numerousapp.rb

@@ -212,7 +212,7 @@ class NumerousClientInternals
 
     protected
 
-    VersionString = '20150222-1.1.0'
+    VersionString = '20150415-1.2.0'
 
     MethMap = {
         GET: Net::HTTP::Get,
@@ -383,9 +383,9 @@ class NumerousClientInternals
                 raise NumerousNetworkError.new(e)
             end
             et = Time.now - t0
-            # We report the elapsed round-trip time, either as a scalar (default)
-            # OR if you preset the :serverResponseTimes to be an array of length N
-            # then we keep the last N response times, thusly:
+            # We report the elapsed round-trip time, as a scalar (by default)
+            # OR if you preset the :serverResponseTimes to be an array
+            # of length N then we keep the last N response times, thusly:
             begin
                 times = @statistics[:serverResponseTimes]
                 times.insert(0, et)
@@ -534,19 +534,20 @@ class NumerousClientInternals
                     #
 		    # There is a bug in the NumerousApp server which can
 		    # cause collections to show duplicates of certain events
-		    # (or interactions/stream items). Explaining the bug in great
-		    # detail is beyond the scope here; suffice to say it only
-		    # happens for events that were recorded nearly-simultaneously
-		    # and happen to be getting reported right at a chunking boundary.
+		    # (or interactions/stream items). Explaining the bug in
+                    # great detail is beyond the scope here; suffice to say
+                    # it only happens for events that were recorded
+                    # nearly-simultaneously and happen to be getting reported
+                    # right at a chunking boundary.
                     #
                     # So we are filtering them out here. For a more involved
                     # discussion of this, see the python implementation. This
-                    # filtering "works" because it knows pragmatically how/where
-                    # the bug can show up
+                    # filtering "works" because it knows pragmatically
+                    # how/where the bug can show up
                     #
-                    # Turning off duplicate filtering is really meant only for testing.
+                    # Turning off duplicate filtering is for testing (only).
                     #
-                    # Not all API's require dupfiltering, hence the APIInfo test
+                    # Not all API's need dupfiltering, hence the APIInfo test
                     #
                     if (not filterInfo)    # the easy case, not filtering
                         block.call i
@@ -577,18 +578,18 @@ class NumerousClientInternals
     #    then delay the amount of time the server told us to delay.
     #
     # The arguments supplied to us are:
-    #     nr is the Numerous (handled explicitly so you can write external funcs too)
+    #     nr is the Numerous
     #     tparams is a Hash containing:
     #         :attempt         : the attempt number. Zero on the very first try
     #         :rateRemaining   : X-Rate-Limit-Remaining reported by the server
     #         :rateReset       : time (in seconds) until fresh rate granted
-    #         :resultCode      : HTTP code from the server (e.g., 409, 200, etc)
-    #         :resp            : the full-on response object if you must have it
+    #         :resultCode      : HTTP code from server (e.g., 409, 200, etc)
+    #         :resp            : the full-on response object
     #         :request         : information about the original request
-    #         :statistics      : place to record stats (purely informational stats)
+    #         :statistics      : place to record informational stats
     #         :debug           : current debug level
     #
-    #     td is the data you supplied as "throttleData" to the Numerous() constructor
+    #     td is the data you supplied as "throttleData" to Numerous.new()
     #     up is a tuple useful for calling the original system throttle policy:
     #          up[0] is the Proc
     #          up[1] is the td for *that* function
@@ -599,18 +600,18 @@ class NumerousClientInternals
     #
     # It's really (really really) important to understand the return value and
     # the fact that we are invoked AFTER each request:
-    #    false : simply means "don't do more retries". It does not imply anything
-    #            about the success or failure of the request; it simply means that
-    #            this most recent request (response) is the one to "take" as
+    #    false : means "don't do more retries". It does not imply anything
+    #            about the success or failure of the request; it simply means
+    #            this most recent request (response) is the one to use as
     #            the final answer
     #
     #    true  : means that the response is, indeed, to be interpreted as some
-    #            sort of rate-limit failure and should be discarded. The original
-    #            request will be sent again. Obviously it's a very bad idea to
-    #            return true in cases where the server might have done some
-    #            anything non-idempotent.
+    #            sort of rate-limit failure and should be discarded. The
+    #            original request will be sent again. Obviously it's a very
+    #            bad idea to return true in cases where the server might
+    #            have done anything non-idempotent.
     #
-    # All of this seems overly general for what basically amounts to "sleep sometimes"
+    # All of this seems overly general for what amounts to "sleep sometimes"
     #
 
     ThrottleDefault = Proc.new do |nr, tparams, td, up|
@@ -644,7 +645,7 @@ class NumerousClientInternals
             # voluntary arbitrary limit
             if rateleft >= 0 and rateleft < td[:voluntary]
                 stats[:throttleVoluntaryBackoff] += 1
-                # arbitrary .. 1 second if more than half left, 3 seconds if less
+                # arbitrary .. 1sec if more than half left, 3 secs if less
                 if (rateleft*2) > td[:voluntary]
                     sleep(1)
                 else
@@ -688,8 +689,10 @@ end
 # In those cases there is no useful return value from the method; the
 # method succeeds or else raises an exception (containing the failure code).
 #
-# For the collection operations the server returns a JSON array of dictionary
-# representations, possibly "chunked" into multiple request/response operations.
+# For the collection operations the server returns a JSON array
+# of dictionary representations, possibly "chunked" into multiple
+# request/response operations.
+#
 # The enumerator methods (e.g., "metrics") implement lazy-fetch and hide
 # the details of the chunking from you. They simply yield each individual
 # item (string-key Hash) to your block.
@@ -1137,7 +1140,7 @@ class NumerousMetric < NumerousClientInternals
 
         if not actualId
             # well, see if it looks like an int
-            i = id.to_i     # allow this to raise exception if id bogus type here
+            i = id.to_i     # raises exception if id bogus type here
             if i == id
                 actualId = i.to_s
             end
@@ -1159,7 +1162,7 @@ class NumerousMetric < NumerousClientInternals
       # read/update/delete a metric
       metric: {
         path: '/v1/metrics/%{metricId}' ,
-        PUT: {        # note that PUT has a /v2 interface but GET does not (yet?).
+        PUT: {     # note that PUT has a /v2 interface but GET does not (yet?).
             path: '/v2/metrics/%{metricId}'
         },
         DELETE: {
@@ -1248,6 +1251,27 @@ class NumerousMetric < NumerousClientInternals
         DELETE: {
             successCodes: [ 204 ]
         }
+      },
+
+      # permissions collection
+      permissionsCollection: {
+        path: '/v1/metrics/%{metricId}/permissions',
+        # GET the permissions collection
+        GET: {
+            next: 'nextURL',
+            list: 'permissions'
+        }
+      },
+
+      # individual permissions : GET, PUT, DELETE
+      permission: {
+        path: '/v1/metrics/%{metricId}/permissions/%{userId}',
+        defaults: {
+            userId: 'me'            # default userId meaning "myself"
+        },
+        DELETE: {
+            successCodes: [ 204 ]
+        }
       }
 
     }
@@ -1420,6 +1444,16 @@ class NumerousMetric < NumerousClientInternals
         return self
     end
 
+    # Enumerate the permissions of a metric.
+    #
+    # @yield [p] permissions
+    # @yieldparam p [Hash] String-key representation of one permission
+    # @return [NumerousMetric] self
+    def permissions(&block)
+        @nr.chunkedIterator(APIInfo[:permissionsCollection], {metricId:@id}, block)
+        return self
+    end
+
 
     # Obtain a specific metric event from the server
     #
@@ -1455,6 +1489,42 @@ class NumerousMetric < NumerousClientInternals
         return @nr.simpleAPI(api)
     end
 
+    # Obtain a specific permission resource for the given user
+    #
+    # @param [String] userId The specific user ID
+    # @return [Hash] The string-key hash of the permission
+    # @raise [NumerousError] Not found (.code will be 404)
+    #
+    def get_permission(userId=nil)
+        api = getAPI(:permission, :GET, {userId: userId})
+        return @nr.simpleAPI(api)
+    end
+
+    # Set a permission for the given user
+    # @param [Hash] perms
+    #   string-key hash of subscription parameters
+    # @param [String] userId
+    #   Optional (keyword arg). UserId (defaults to you)
+    def set_permission(perms, userId=nil)
+        # if you don't specify a userId but DO have a userId
+        # in the perms, use that one
+        if (not userId) and perms.key? 'userId'
+            userId = perms['userId']
+        end
+        api = getAPI(:permission, :PUT, {userId: userId})
+        return @nr.simpleAPI(api, jdict:perms)
+    end
+
+    # Delete a permission resource for the given user
+    #
+    # @param [String] userId The specific user ID
+    #
+    def delete_permission(userId)
+        api = getAPI(:permission, :DELETE, {userId: userId})
+        ignored = @nr.simpleAPI(api)
+        return nil
+    end
+
     # Subscribe to a metric.
     #
     # See the NumerousApp API docs for what should be

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: numerousapp
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 1.2.0
 platform: ruby
 authors:
 - Neil Webber
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-02-22 00:00:00.000000000 Z
+date: 2015-04-15 00:00:00.000000000 Z
 dependencies: []
 description: Classes implementing the NumerousApp REST APIs for metrics. Requires
   Ruby 2.x