wavefront-sdk 1.2.1 → 1.3.0

data/.travis.yml

@@ -1,9 +1,10 @@
 language: ruby
 cache: bundler
 rvm:
-- 2.2.8
-- 2.3.5
-- 2.4.2
+- 2.2.9
+- 2.3.6
+- 2.4.3
+- 2.5.0
 before_install: gem install bundler --no-rdoc --no-ri
 deploy:
   provider: rubygems
@@ -13,4 +14,4 @@ deploy:
   on:
     tags: true
     repo: snltd/wavefront-sdk
-    ruby: 2.3.5
+    ruby: 2.3.6

data/README.md

@@ -69,6 +69,16 @@ wf.list.response.items.each { |user| puts user[:identifier] }
 wf.delete('lolex@oldplace.com')
 ```
 
+All API classes expect `user` support pagination and will only
+return blocks of results. The `everything()` method returns a lazy
+enumerator to make dealing with pagination simpler.
+
+```ruby
+Wavefront::Alert.new(c.creds).everything.each_with_index do |m, i|
+  puts "#{i} #{m.id}"
+end
+```
+
 Retrieve a timeseries over the last 10 minutes, with one minute bucket
 granularity. We will describe the time as a Ruby object, but could also use
 an epoch timestamp. The SDK happily converts between the two.

data/lib/wavefront-sdk/base.rb

@@ -21,8 +21,8 @@ module Wavefront
   class Base
     include Wavefront::Validators
     include Wavefront::Mixins
-    attr_reader :opts, :debug, :noop, :verbose, :net, :api_base, :conn,
-                :update_keys, :logger
+    attr_reader :opts, :debug, :noop, :verbose, :net, :conn, :update_keys,
+                :logger
 
     # Create a new API object. This will always be called from a
     # class which inherits this one. If the inheriting class defines
@@ -181,18 +181,21 @@ module Wavefront
     #   :debug to DEBUG.
     #
     def log(msg, level = nil)
-
       if logger
         logger.send(level || :info, msg)
       else
-        # print it unless it's a debug and we're not in debug
-        #
-        return if level == :debug && ! opts[:debug]
-        return if level == :info && ! opts[:verbose]
-        puts msg
+        print_message(msg, level)
       end
     end
 
+    # Print it unless it's a debug and we're not in debug
+    #
+    def print_message(msg, level)
+      return if level == :debug && ! opts[:debug]
+      return if level == :info && ! opts[:verbose]
+      puts msg
+    end
+
     # If we need to massage a raw response to fit what the
     # Wavefront::Response class expects (I'm looking at you,
     # 'User'), a class can provide a {#response_shim} method.
@@ -205,6 +208,23 @@ module Wavefront
       Wavefront::Response.new(body, resp.status, debug)
     end
 
+    # Return all objects using a lazy enumerator
+    # @return Enumerable
+    #
+    def everything
+      Enumerator.new do |y|
+        offset = 0
+        limit = 100
+
+        loop do
+          resp = api_get('', { offset: offset, limit: limit }).response
+          resp.items.map { |i| y.<< i }
+          offset += limit
+          raise StopIteration unless resp.moreItems == true
+        end
+      end.lazy
+    end
+
     private
 
     # Try to describe the actual HTTP calls we make. There's a bit

data/lib/wavefront-sdk/constants.rb

@@ -0,0 +1,3 @@
+# Constants
+#
+DELTA = "\u2206" # "Increment" -- alt-J on a Mac

data/lib/wavefront-sdk/credentials.rb

@@ -31,11 +31,17 @@ module Wavefront
     #   and/or 'profile' which select a profile section from 'file'
     #
     def initialize(options = {})
-      raw = load_from_file(options)
-      raw = env_override(raw)
-      populate(raw)
+      raw = load_from_file(cred_files(options), options[:profile] ||
+                           'default')
+      populate(env_override(raw))
     end
 
+    # If the user has set certain environment variables, their
+    # values will override values from the config file or
+    # command-line.
+    # @param raw [Hash] the existing credentials
+    # @return [Hash] the modified credentials
+    #
     def env_override(raw)
       { endpoint: 'WAVEFRONT_ENDPOINT',
         token:    'WAVEFRONT_TOKEN',
@@ -44,25 +50,39 @@ module Wavefront
       raw
     end
 
+    # Make the helper values. We use a Map so they're super-easy to
+    # access
+    #
+    # @param raw [Hash] the combined options from config file,
+    #   command-line and env vars.
+    # @return void
+    #
     def populate(raw)
       @config = Map(raw)
       @creds = Map(raw.select { |k, _v| [:endpoint, :token].include?(k) })
       @proxy = Map(raw.select { |k, _v| [:proxy, :port].include?(k) })
     end
 
-    def load_from_file(opts)
-      ret = {}
-
-      profile = opts[:profile] || 'default'
+    # @return [Array] a list of possible credential files
+    #
+    def cred_files(opts = {})
+      if opts.key?(:file)
+        Array(Pathname.new(opts[:file]))
+      else
+        [Pathname.new('/etc/wavefront/credentials'),
+          Pathname.new(ENV['HOME']) + '.wavefront']
+      end
+    end
 
-      c_file = if opts.key?(:file)
-                 Array(Pathname.new(opts[:file]))
-               else
-                 [Pathname.new('/etc/wavefront/credentials'),
-                  Pathname.new(ENV['HOME']) + '.wavefront']
-               end
+    # @param files [Array][Pathname] a list of ini-style config files
+    # @param profile [String] a profile name
+    # @return [Hash] the given profile from the given list of files.
+    #   If multiple files match, the last one will be used
+    #
+    def load_from_file(files, profile = 'default')
+      ret = {}
 
-      c_file.each do |f|
+      files.each do |f|
         next unless f.exist?
         ret = load_profile(f, profile)
         ret[:file] = f
@@ -71,9 +91,8 @@ module Wavefront
       ret
     end
 
-    # Load in configuration (optionally) given section of an
-    # ini-style configuration file not there, we don't consider that
-    # an error.
+    # Load in an (optionally) given section of an ini-style
+    # configuration file not there, we don't consider that an error.
     #
     # @param file [Pathname] the file to read
     # @param profile [String] the section in the config to read

data/lib/wavefront-sdk/mixins.rb

@@ -1,5 +1,6 @@
 require 'date'
 require_relative './exception'
+require_relative './parse_time'
 
 module Wavefront
   module Mixins
@@ -13,28 +14,8 @@ module Wavefront
     # @raise Wavefront::InvalidTimestamp
     #
     def parse_time(t, ms = false)
-      #
-      # Numbers, or things that look like numbers, pass straight
-      # through. No validation, because maybe the user means one
-      # second past the epoch, or the year 2525.
-      #
-      return t if t.is_a?(Numeric)
-
-      if t.is_a?(String)
-        return t.to_i if t.match(/^\d+$/)
-
-        if t.start_with?('-') || t.start_with?('+')
-          return relative_time(t, ms)
-        end
-
-        begin
-          t = DateTime.parse("#{t} #{Time.now.getlocal.zone}")
-        rescue
-          raise Wavefront::Exception::InvalidTimestamp
-        end
-      end
-
-      ms ? t.to_datetime.strftime('%Q').to_i : t.strftime('%s').to_i
+      return relative_time(t, ms) if t =~ /^[\-+]/
+      ParseTime.new(t, ms).parse!
     end
 
     # Return a timetamp described by the given string. That is,

data/lib/wavefront-sdk/notificant.rb

@@ -80,5 +80,5 @@ module Wavefront
       wf_notificant_id?(id)
       api_post(['test', id].uri_concat, nil)
     end
-   end
+  end
 end

data/lib/wavefront-sdk/parse_time.rb

@@ -0,0 +1,58 @@
+module Wavefront
+  # Parse various times into integers. This class is not for direct
+  # consumption: it's used by the mixins parse_time method, which
+  # does all the type sanity stuff.
+  #
+  class ParseTime
+    attr_reader :t, :ms
+
+    # param t [Numeric] a timestamp
+    # param ms [Bool] whether the timestamp is in milliseconds
+    #
+    def initialize(t, ms = false)
+      @t = t
+      @ms = ms
+    end
+
+    # @return [Fixnum] timestamp
+    #
+    def parse_time_Fixnum
+      t
+    end
+
+    # @return [Integer] timestamp
+    #
+    def parse_time_Integer
+      t
+    end
+
+    # @return [Fixnum] timestamp
+    #
+    def parse_time_String
+      return t.to_i if t =~ /^\d+$/
+      @t = DateTime.parse("#{t} #{Time.now.getlocal.zone}")
+      parse_time_Time
+    end
+
+    # @return [Integer] timestamp
+    #
+    def parse_time_Time
+      if ms
+        t.to_datetime.strftime('%Q').to_i
+      else
+        t.strftime('%s').to_i
+      end
+    end
+
+    def parse_time_DateTime
+      parse_time_Time
+    end
+
+    def parse!
+      method = ('parse_time_' + t.class.name).to_sym
+      send(method)
+    rescue
+      raise Wavefront::Exception::InvalidTimestamp
+    end
+  end
+end

data/lib/wavefront-sdk/response.rb

@@ -31,12 +31,7 @@ module Wavefront
     #   has changed underneath us.
     #
     def initialize(json, status, debug = false)
-      begin
-        raw = json.empty? ? {} : JSON.parse(json, symbolize_names: true)
-      rescue
-        raw = { message: json, code: status }
-      end
-
+      raw = raw_response(json, status)
       @status = build_status(raw, status)
       @response = build_response(raw)
 
@@ -47,6 +42,12 @@ module Wavefront
       raise Wavefront::Exception::UnparseableResponse
     end
 
+    def raw_response(json, status)
+      json.empty? ? {} : JSON.parse(json, symbolize_names: true)
+    rescue
+      { message: json, code: status }
+    end
+
     def build_status(raw, status)
       Wavefront::Type::Status.new(raw, status)
     end

data/lib/wavefront-sdk/search.rb

@@ -72,8 +72,11 @@ module Wavefront
     #   active (false) entities
     #
     def raw_search(entity = nil, body = nil, deleted = false)
-      raise ArgumentError unless entity.is_a?(String) || entity.is_a?(Symbol)
-      raise ArgumentError unless body.is_a?(Hash)
+      unless (entity.is_a?(String) || entity.is_a?(Symbol)) &&
+        body.is_a?(Hash)
+        raise ArgumentError
+      end
+
       path = [entity]
       path.<< 'deleted' if deleted
       api_post(path, body.to_json, 'application/json')

data/lib/wavefront-sdk/user.rb

@@ -95,5 +95,12 @@ module Wavefront
                     code:    status },
       }.to_json
     end
+
+    # the user API class does not support pagination. Be up-front
+    # about that.
+    #
+    def everything
+      raise NoMethodError
+    end
   end
 end

data/lib/wavefront-sdk/validators.rb

@@ -1,3 +1,4 @@
+require_relative './constants'
 require_relative './exception'
 
 module Wavefront
@@ -35,7 +36,8 @@ module Wavefront
     #
     def wf_metric_name?(v)
       if v.is_a?(String) && v.size < 1024 &&
-         (v.match(/^[\w\-\.]+$/) || v.match(%r{^\"[\w\-\.\/,]+\"$}))
+         (v.match(/^#{DELTA}?[\w\-\.]+$/) ||
+          v.match(%r{^\"#{DELTA}?[\w\-\.\/,]+\"$}))
         return true
       end
 
@@ -162,13 +164,19 @@ module Wavefront
     #
     def wf_point_tags?(tags)
       raise Wavefront::Exception::InvalidTag unless tags.is_a?(Hash)
+      tags.each { |k, v| wf_point_tag?(k, v) }
+    end
 
-      tags.each do |k, v|
-        unless k && v && (k.size + v.size < 254) && k.match(/^[\w\-\.:]+$/)
-          raise Wavefront::Exception::InvalidTag
-        end
-      end
-      true
+    # Validate a single point tag, probably on behalf of
+    # #wf_point_tags?
+    # @param k [String] tag key
+    # @param v [String] tag value
+    # @raise Wavefront::Exception::InvalidTag if any tag is not valid
+    # @return nil
+    #
+    def wf_point_tag?(k, v)
+      return if  k && v && (k.size + v.size < 254) && k =~ /^[\w\-\.:]+$/
+      raise Wavefront::Exception::InvalidTag
     end
 
     # Ensure the given argument is a valid Wavefront proxy ID

data/lib/wavefront-sdk/version.rb

@@ -1 +1 @@
-WF_SDK_VERSION = '1.2.1'.freeze
+WF_SDK_VERSION = '1.3.0'.freeze

data/lib/wavefront-sdk/write.rb

@@ -1,4 +1,5 @@
 require 'socket'
+require_relative './constants'
 require_relative './base'
 
 HOSTNAME = Socket.gethostname.freeze
@@ -108,6 +109,28 @@ module Wavefront
       Wavefront::Response.new(resp, nil)
     end
 
+    # A wrapper method around #write() which guarantees all points
+    # will be sent as deltas. You can still manually prefix any
+    # metric with a Δ and use #write(), but depending on your
+    # use-case, this method may be safer. It's easy to forget the Δ.
+    #
+    # @param points [Array[Hash]] see #write()
+    # @param openclose [Bool] see #write()
+    #
+    def write_delta(points, openclose = true)
+      write(paths_to_deltas(points), openclose)
+    end
+
+    # Prefix all paths in a points array (as passed to
+    # #write_delta() with a delta symbol
+    #
+    # @param points [Array[Hash]] see #write()
+    # @return [Array[Hash]]
+    #
+    def paths_to_deltas(points)
+      [points].flatten.map { |p| p.tap { p[:path] = DELTA + p[:path] } }
+    end
+
     def valid_point?(p)
       return true if opts[:novalidate]
 
@@ -126,13 +149,14 @@ module Wavefront
       end
     end
 
-    # Convert a validated point has to a string conforming to
+    # Convert a validated point to a string conforming to
     # https://community.wavefront.com/docs/DOC-1031.  No validation
     # is done here.
     #
     # @param p [Hash] a hash describing a point. See #write() for
     #   the format.
     #
+    # rubocop:disable Metrics/CyclomaticComplexity
     def hash_to_wf(p)
       unless p.key?(:path) && p.key?(:value)
         raise Wavefront::Exception::InvalidPoint
@@ -183,10 +207,12 @@ module Wavefront
         return true
       end
 
-      log("Connecting to #{net[:proxy]}:#{net[:port]}.", :info)
+      port = net[:port] || 2878
+
+      log("Connecting to #{net[:proxy]}:#{port}.", :info)
 
       begin
-        @sock = TCPSocket.new(net[:proxy], net[:port])
+        @sock = TCPSocket.new(net[:proxy], port)
       rescue => e
         log(e, :error)
         raise Wavefront::Exception::InvalidEndpoint