numerousapp 1.0.2 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5bc753ba4ac5af22bec9d355a0450327a4c0415c
-  data.tar.gz: e5e47a6f1f2a339338bdb5fe60a66366f33fa610
+  metadata.gz: 2df08c0abb56a4d38ce98c048fb814a37cb4ca37
+  data.tar.gz: 50b9313c710e3ab6c27a32cd895c10b03671bdfb
 SHA512:
-  metadata.gz: aba6414701c7c0ddf0e33379f3dc35a3b48070587e535be8e57ceea8247f564cc2a8a9429ac67c32dd0a028faf2ee313d548c41f18a1dbb3943ff17e9df775d1
-  data.tar.gz: bfbae46781b680556c3cec93a0f380d7a765443c54b9d672a6d0ca54bf4c71b4ca6bce24241a431e0b626a1f2522a31f49f0ef8f9aaf0136f853d65df149cdf1
+  metadata.gz: 5e62912986ab1ce0f5377dd5a400c72fe749c61fa886689552cfa7c9e38c2f6747eb089d0d9f32129c669eaeb46990749d1c5dcd0051fdbd6f9b46c275b1d4c3
+  data.tar.gz: f124700210064a362c407fb976272aa874eced217ca947991fb0b2cdb6428dfd47782650efb455b4915eee0e32b2e58a773750d86c6b996c63c9ac796a901492

data/lib/numerousapp.rb

@@ -1,7 +1,7 @@
 #
 # The MIT License (MIT)
 #
-# Copyright (c) 2014 Neil Webber
+# Copyright (c) 2015 Neil Webber
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to deal
@@ -39,12 +39,17 @@ require 'net/http'
 require 'uri'
 
 #
-# NumerousError exceptions indicate errors from the server
+# == NumerousError
+#
+# Exceptions indicate errors from the server
 #
 class NumerousError < StandardError
+
     #
-    # @!attribute msg
-    #      human-targeted error message as a string
+    # initialize a NumerousError
+    #
+    # @param msg
+    #      StandardError message attribute
     #
     # @!attribute code
     #      HTTP error code (e.g., 404)
@@ -53,7 +58,6 @@ class NumerousError < StandardError
     #      hash containing more ad-hoc information, most usefully :id which
     #      is the URL that was used in the request to the server
     #
-
     def initialize(msg, code, details)
         super(msg)
         @code = code
@@ -70,12 +74,28 @@ end
 class NumerousAuthError < NumerousError
 end
 
+#
+# A NumerousNetworkError occurs when there is a "somewhat normal" network
+# error. The library catches the lower level exceptions that normally happen
+# when the network is down or the HTTP connection times out and translates
+# those into this exception so you can rescue this without being exposed to
+# all the details of the lower-level networking exceptions.
+#
+class NumerousNetworkError < NumerousError
+    def initialize(xc)
+        super("Network Error", -1, { :netException => xc })
+    end
+end
+
 #
 # A NumerousMetricConflictError occurs when you write to a metric
 # and specified "only if changed" and your value
 # was (already) the current value
 #
 class NumerousMetricConflictError < NumerousError
+    def initialize(msg, details)
+        super(msg, 409, details)
+    end
 end
 
 #
@@ -103,9 +123,10 @@ class NumerousClientInternals
     # @!attribute [r] debugLevel
     #    @return [Fixnum] Current debugging level; use debug() method to change.
     #
-    def initialize(apiKey, server:'api.numerousapp.com',
+    def initialize(apiKey=nil, server:'api.numerousapp.com',
                            throttle:nil, throttleData:nil)
 
+        # specifying apiKey=nil asks us to get key from various default places.
         if not apiKey
             apiKey = Numerous.numerousKey()
         end
@@ -130,7 +151,8 @@ class NumerousClientInternals
         #     [ 1 ] - specific data for Proc
         #     [ 2 ] - "up" tuple for chained policy
         #
-        # and the default policy uses the "data" (40) as the voluntary backoff point
+        # and the default policy uses the "data" as a hash of parameters:
+        #    :voluntary -- the threshold point for voluntary backoff
         #
         @arbitraryMaximumTries = 10
         voluntary = { voluntary: 40}
@@ -143,7 +165,7 @@ class NumerousClientInternals
             @throttlePolicy = [throttle, throttleData, @throttlePolicy]
         end
 
-        @statistics = Hash.new { |h, k| h[k] = 0 }  # just useful debug/testing info
+        @statistics = Hash.new { |h, k| h[k] = 0 }  # statistics are "infotainment"
         @debugLevel = 0
 
     end
@@ -151,8 +173,11 @@ class NumerousClientInternals
     attr_reader :serverName, :debugLevel
     attr_reader :statistics
 
+    # String representation of Numerous
+    #
+    # @return [String] Human-appropriate string representation.
     def to_s()
-        oid = (2 * self.object_id).to_s(16)
+        oid = (2 * self.object_id).to_s(16)  # XXX "2*" makes it match native to_s
         return "<Numerous {#{@serverName}} @ 0x#{oid}>"
     end
 
@@ -172,8 +197,13 @@ class NumerousClientInternals
         return prev
     end
 
-    # XXX This is primarily for testing; control filtering of bogus duplicates
-    #     If you are calling this you are probably doing something wrong.
+    #
+    # This is primarily for testing; control filtering of bogus duplicates
+    # @note If you are calling this you are probably doing something wrong.
+    #
+    # @param [Boolean] f
+    #    New value for duplicate filtering flag.
+    # @return [Boolean] Previous value of duplicate filtering flag.
     def setBogusDupFilter(f)
         prev = @filterDuplicates
         @filterDuplicates = f
@@ -182,7 +212,7 @@ class NumerousClientInternals
 
     protected
 
-    VersionString = '20150215-1.0.2'
+    VersionString = '20150222-1.1.0'
 
     MethMap = {
         GET: Net::HTTP::Get,
@@ -197,7 +227,6 @@ class NumerousClientInternals
     # and fills in the variable fields in URLs. It returns an "api context"
     # containing all the API-specific details needed by simpleAPI.
     #
-
     def makeAPIcontext(info, whichOp, kwargs={})
         rslt = {}
         rslt[:httpMethod] = whichOp
@@ -238,8 +267,9 @@ class NumerousClientInternals
     BCharsLen = BChars.length
 
     def makeboundary(s)
-        # Just try something fixed, and if it is no good extend it with random
-        b = "RoLlErCaSeDbOuNdArY8675309".b
+        # Just try something fixed, and if it is no good extend it with random.
+        # For amusing porpoises make it this way so we don't also contain it.
+        b = "RoLlErCaSeDbOuNdArY867".b + "5309".b
         while s.include? b
             b += BChars[rand(BCharsLen)]
         end
@@ -342,7 +372,16 @@ class NumerousClientInternals
 
             @statistics[:serverRequests] += 1
             t0 = Time.now
-            resp = @http.request(rq)
+            begin
+                resp = @http.request(rq)
+            rescue StandardError => e
+                # it's PDB (pretty bogus) that we have to rescue
+                # StandardError but the underlying http library can just throw
+                # too many exceptions to know what they all are; it really
+                # should have encapsulated them into an HTTPNetError class...
+                # so, we'll just assume any "standard error" is a network issue
+                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
@@ -377,7 +416,10 @@ class NumerousClientInternals
                    :resultCode=> resp.code.to_i,
                    :resp=> resp,
                    :statistics=> @statistics,
-                   :request=> { :httpMethod => api[:httpMethod], :url => path } }
+                   :request=> { :httpMethod => api[:httpMethod],
+                                 :url => path,
+                                 :jdict => jdict }
+                 }
 
             td = @throttlePolicy[1]
             up = @throttlePolicy[2]
@@ -529,9 +571,7 @@ class NumerousClientInternals
     # return true to force a retry or false to accept this response as-is.
     #
     # The policy this implements:
-    #    if the server failed with too busy, do backoff based on attempt number
-    #
-    #    if we are "getting close" to our limit, arbitrarily delay ourselves
+    #    if we are "getting close" to our limit, arbitrarily delay ourselves.
     #
     #    if we truly got spanked with "Too Many Requests"
     #    then delay the amount of time the server told us to delay.
@@ -568,9 +608,7 @@ class NumerousClientInternals
     #            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. We assume that a 429 ("Too Many") or
-    #            a 500 ("Too Busy") response from the server means the server didn't
-    #            actually do anything (so a retry, timed appropriately, is ok)
+    #            anything non-idempotent.
     #
     # All of this seems overly general for what basically amounts to "sleep sometimes"
     #
@@ -596,13 +634,6 @@ class NumerousClientInternals
             next false               # too many tries
         end
 
-        # if the server actually has failed with too busy, sleep and try again
-        if tparams[:resultCode] == 500
-            stats[:throttle500] += 1
-            sleep(backoff)
-            next true
-        end
-
         # if we weren't told to back off, no need to retry
         if tparams[:resultCode] != 429
             # but if we are closing in on the limit then slow ourselves down
@@ -844,6 +875,11 @@ class Numerous  < NumerousClientInternals
         return NumerousMetric.new(id, self)
     end
 
+    # just a DRY shorthand for use in metricByLabel
+    RaiseConflict = lambda { |s1, s2|
+        raise NumerousMetricConflictError.new("Multiple matches", [s1, s2])
+    }
+    private_constant :RaiseConflict
 
     #
     # Version of metric() that accepts a name (label)
@@ -853,9 +889,6 @@ class Numerous  < NumerousClientInternals
     # @param [String] matchType 'FIRST','BEST','ONE','STRING' or 'ID'
     #
     def metricByLabel(labelspec, matchType:'FIRST')
-        def raiseConflict(s1,s2)
-            raise NumerousMetricConflictError.new("Multiple matches", 409, [s1, s2])
-        end
 
         bestMatch = [ nil, 0 ]
 
@@ -889,7 +922,7 @@ class Numerous  < NumerousClientInternals
             if matchType == 'STRING'        # exact full match required
                 if m['label'] == labelspec
                     if bestMatch[0]
-                        raiseConflict(bestMatch[0]['label'], m['label'])
+                        RaiseConflict.call(bestMatch[0]['label'], m['label'])
                     end
                     bestMatch = [ m, 1 ]   # the length is irrelevant with STRING
                 end
@@ -899,7 +932,7 @@ class Numerous  < NumerousClientInternals
                     if matchType == 'FIRST'
                         return self.metric(m['id'])
                     elsif (matchType == 'ONE') and (bestMatch[1] > 0)
-                        raiseConflict(bestMatch[0]['label'], m['label'])
+                        RaiseConflict.call(bestMatch[0]['label'], m['label'])
                     end
                     if mm[0].length > bestMatch[1]
                         bestMatch = [ m, mm[0].length ]
@@ -935,6 +968,12 @@ class Numerous  < NumerousClientInternals
     # ignore it or delete from their own tree :)
     #
 
+    # find an apikey from various default places
+    # @param [String] s
+    #    See documentation for details; a file name or a key or a "readable" object.
+    # @param [String] credsAPIKey
+    #    Key to use in accessing json dict if one is found.
+    # @return [String] the API key.
     def self.numerousKey(s:nil, credsAPIKey:'NumerousAPIKey')
 
     	if not s
@@ -1069,7 +1108,15 @@ class NumerousMetric < NumerousClientInternals
     # though it's handy sometimes in cut/paste interactive testing/use.
     #
 
-    def initialize(id, nr)
+    def initialize(id, nr=nil)
+
+        # If you don't specify a Numerous we'll make one for you.
+        # For this to work, NUMEROUSAPIKEY environment variable must exist.
+        #   m = NumerousMetric.new('234234234') is ok for simple one-shots
+        # but note it makes a private Numerous for every metric.
+
+        nr ||= Numerous.new(nil)
+
         actualId = nil
         begin
             fields = id.split('/')
@@ -1112,7 +1159,9 @@ class NumerousMetric < NumerousClientInternals
       # read/update/delete a metric
       metric: {
         path: '/v1/metrics/%{metricId}' ,
-        # no entries needed for GET/PUT because no special codes etc
+        PUT: {        # note that PUT has a /v2 interface but GET does not (yet?).
+            path: '/v2/metrics/%{metricId}'
+        },
         DELETE: {
             successCodes: [ 204 ]
         }
@@ -1449,6 +1498,17 @@ class NumerousMetric < NumerousClientInternals
     #   causes the server to ADD newval to the current metric value.
     #   Note that this IS atomic at the server. Two clients doing
     #   simultaneous ADD operations will get the correct (serialized) result.
+    #
+    # @param [String] updated
+    #   updated allows you to specify the timestamp associated with the value
+    #     -- it must be a string in the format described in the NumerousAPI
+    #        documentation. Example: '2015-02-08T15:27:12.863Z'
+    #        NOTE: The server API implementation REQUIRES the fractional
+    #              seconds be EXACTLY 3 digits. No other syntax will work.
+    #              You will get 400/BadRequest if your format is incorrect.
+    #              In particular a direct strftime won't work; you will have
+    #              to manually massage it to conform to the above syntax.
+    #
     # @param [Boolean] dictionary
     #   If true the entire metric will be returned as a string-key Hash;
     #   else (false/default) the bare number (Fixnum or Float) for the
@@ -1457,7 +1517,7 @@ class NumerousMetric < NumerousClientInternals
     #   value of the metric is returned as a bare number.
     # @return [Hash] if dictionary is true the entire new metric is returned.
     #
-    def write(newval, onlyIf:false, add:false, dictionary:false)
+    def write(newval, onlyIf:false, add:false, dictionary:false, updated:nil)
         j = { 'value' => newval }
         if onlyIf
             j['onlyIfChanged'] = true
@@ -1465,6 +1525,9 @@ class NumerousMetric < NumerousClientInternals
         if add
             j['action'] = 'ADD'
         end
+        if updated
+            j['updated'] = updated
+        end
 
         @cachedHash = nil  # will need to refresh cache on next access
         api = getAPI(:events, :POST)
@@ -1475,7 +1538,7 @@ class NumerousMetric < NumerousClientInternals
             # if onlyIf was specified and the error is "conflict"
             # (meaning: no change), raise ConflictError specifically
             if onlyIf and e.code == 409
-                raise NumerousMetricConflictError.new("No Change", 0, e.details)
+                raise NumerousMetricConflictError.new("No Change", e.details)
             else
                 raise e        # never mind, plain NumerousError is fine
             end
@@ -1645,6 +1708,15 @@ class NumerousMetric < NumerousClientInternals
         return v['links']['web']
     end
 
+    # the phone application generates a nmrs:// URL as a way to link to
+    # the application view of a metric (vs a web view). This makes
+    # one of those for you so you don't have to "know" the format of it.
+    #
+    # @return [String] nmrs:// style URL
+    def appURL
+        return "nmrs://metric/" + @id
+    end
+
     # Delete a metric (permanently). Be 100% you want this, because there
     # is absolutely no undo.
     #

metadata

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