wavefront-sdk 0.0.1

data/lib/wavefront-sdk/version.rb

@@ -0,0 +1 @@
+WF_SDK_VERSION = '0.0.1'.freeze

data/lib/wavefront-sdk/webhook.rb

@@ -0,0 +1,73 @@
+require_relative './base'
+
+module Wavefront
+  #
+  # Manage and query Wavefront webhooks
+  #
+  class Webhook < Wavefront::Base
+
+    # GET /api/v2/webhook
+    # Get all webhooks for a customer.
+    #
+    # @param offset [Integer] webhook at which the list begins
+    # @param limit [Integer] the number of webhooks to return
+    #
+    def list(offset = 0, limit = 100)
+      api_get('', { offset: offset, limit: limit })
+    end
+
+    # POST /api/v2/webhook
+    # Create a specific webhook.
+    #
+    # @param body [Hash] a hash of parameters describing the webhook.
+    #   Please refer to the Wavefront Swagger docs for key:value
+    #   information
+    # @return [Hash]
+    #
+    def create(body)
+      raise ArgumentError unless body.is_a?(Hash)
+      api_post('', body, 'application/json')
+    end
+
+    # DELETE /api/v2/webhook/{id}
+    # Delete a specific webhook.
+    #
+    # @param id [String, Integer] ID of the webhook
+    # @return [Hash]
+    #
+    def delete(id)
+      wf_webhook_id?(id)
+      api_delete(id)
+    end
+
+    # GET /api/v2/webhook/{id}
+    # Get a specific webhook.
+    #
+    # @param id [String, Integer] ID of the webhook
+    # @return [Hash]
+    #
+    def describe(id)
+      wf_webhook_id?(id)
+      api_get(id)
+    end
+
+    # PUT /api/v2/webhook/{id}
+    # Update a specific webhook.
+    #
+    # @param body [Hash] a hash of parameters describing the webhook.
+    # @return [Hash]
+    # @raise any validation errors from body
+    #
+    def update(id, body)
+      wf_webhook_id?(id)
+      raise ArgumentError unless body.is_a?(Hash)
+      api_put(id, body)
+    end
+  end
+
+  # A standard response
+  #
+  class Response
+    class Webhook < Base; end
+  end
+end

data/lib/wavefront-sdk/write.rb

@@ -0,0 +1,225 @@
+require 'socket'
+require_relative './base'
+
+HOSTNAME = Socket.gethostname.freeze
+
+module Wavefront
+  #
+  # This class helps you send points to a Wavefront proxy in native
+  # format. Usually this is done on port 2878.
+  #
+  class Write < Wavefront::Base
+    attr_reader :sock, :summary
+
+    # Construct an object which allows us to write points to a
+    # Wavefront proxy.
+    #
+    # @pram creds [Hash] must contain the keys endpoint: and port.
+    # @param options [Hash] can contain the following keys:
+    #   proxy [String] the address of the Wavefront proxy. ('wavefront')
+    #   port [Integer] the port of the Wavefront proxy (2878)
+    #   tags [Hash] point tags which will be applied to every point
+    #   noop [Bool] if true, no proxy connection will be made, and
+    #     instead of sending the points, they will be printed in
+    #     Wavefront wire format.
+    #   novalidate [Bool] if true, points will not be validated.
+    #     This might make things go marginally quicker if you have
+    #     done point validation higher up in the chain.
+    #   verbose [Bool]
+    #   debug [Bool]
+    #
+    def post_initialize(_creds = {}, options = {})
+      defaults = { tags:       nil,
+                   noop:       false,
+                   novalidate: false,
+                   verbose:    false,
+                   debug:      false }
+
+      @summary = { sent: 0, rejected: 0, unsent: 0 }
+      @opts = setup_options(options, defaults)
+
+      wf_point_tags?(opts[:tags]) if opts[:tags]
+    end
+
+    def setup_options(user, defaults)
+      defaults.merge(user)
+    end
+
+    # Send raw data to a Wavefront proxy, automatically opening and
+    # closing a socket.
+    #
+    # @param point [Array[String]] an array of points in native
+    #   Wavefront wire format, as described in
+    #   https://community.wavefront.com/docs/DOC-1031. No validation
+    #   is performed.
+    #
+    def raw(points, openclose = true)
+      open if openclose
+
+      begin
+        [points].flatten.each{ |p| send_point(p) }
+      ensure
+        close if openclose
+      end
+    end
+
+    # Send multiple points to a Wavefront proxy.
+    #
+    # @param points [Array[Hash]] an array of points. Each point is
+    #   defined as a hash with the following keys:
+    #     path [String] metric path. (mandatory)
+    #     value [Numeric] value of metric. Numeric. Mandatory.
+    #     ts [Time, Integer] timestamp for point. Defaults to
+    #       current UTC time.
+    #     source [String] originating source of metric. Defaults to
+    #       the local hostname.
+    #     tags [Hash] key: value point tags which will be applied in
+    #       addition to any tags defined in the #initialize()
+    #       method.
+    # @param openclose [Bool] if this is false, you must have
+    #   already opened a socket to the proxy. If it is true, a
+    #   connection will be opened for you, used, and closed.
+    # @raise any unhandled point validation error is passed through
+    # @return true if no points are rejected, otherwise false
+    #
+    def write(points = [], openclose = true)
+      open if openclose
+
+      begin
+        [points].flatten.each do |p|
+          p[:ts] = p[:ts].to_i if p[:ts].is_a?(Time)
+          valid_point?(p)
+          send_point(hash_to_wf(p))
+        end
+      ensure
+        close if openclose
+      end
+
+      Wavefront::Response::Write.new(summary.to_json, nil)
+    end
+
+    def valid_point?(p)
+      return true if opts[:novalidate]
+
+      begin
+        wf_point?(p)
+        return true
+      rescue Wavefront::Exception::InvalidMetricName,
+             Wavefront::Exception::InvalidMetricValue,
+             Wavefront::Exception::InvalidTimestamp,
+             Wavefront::Exception::InvalidSourceId,
+             Wavefront::Exception::InvalidTag => e
+        log('Invalid point, skipping.', :info)
+        log("Invalid point: #{p}. (#{e})", :debug)
+        summary[:rejected] += 1
+        return false
+      end
+    end
+
+    # Convert a validated point has 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.
+    #
+    def hash_to_wf(p)
+      unless p.key?(:path) && p.key?(:value)
+        raise Wavefront::Exception::InvalidPoint
+      end
+
+      p[:source] = HOSTNAME unless p.key?(:source)
+
+      m = [p[:path], p[:value]]
+      m.<< p[:ts] if p[:ts]
+      m.<< 'source=' + p[:source]
+      m.<< p[:tags].to_wf_tag if p[:tags]
+      m.<< opts[:tags].to_wf_tag if opts[:tags]
+      m.join(' ')
+    end
+
+    # Send a point which is already in Wavefront wire format.
+    #
+    # @param point [String] a point description, probably from
+    #   #hash_to_wf()
+    #
+    def send_point(point)
+      if opts[:noop]
+        log "Would send: #{point}"
+        return
+      end
+
+      log("Sending: #{point}", :info)
+
+      begin
+        sock.puts(point)
+      rescue => e
+        summary[:unsent] += 1
+        log('WARNING: failed to send point.')
+        log(e.to_s, :debug)
+        return false
+      end
+
+      summary[:sent] += 1
+      true
+    end
+
+    # Open a socket to a Wavefront proxy, putting the descriptor
+    # in instance variable @sock.
+    #
+    def open
+      if opts[:noop]
+        log('No-op requested. Not opening connection to proxy.')
+        return true
+      end
+
+      log("Connecting to #{net[:proxy]}:#{net[:port]}.", :info)
+
+      begin
+        @sock = TCPSocket.new(net[:proxy], net[:port])
+      rescue => e
+        log(e, :error)
+        raise Wavefront::Exception::InvalidEndpoint
+      end
+    end
+
+    # Close the socket described by the @sock instance variable.
+    #
+    def close
+      return if opts[:noop]
+      log('Closing connection to proxy.', :info)
+      sock.close
+    end
+
+    private
+
+    # Overload the method which sets an API endpoint. A proxy
+    # endpoint has an address and a port, rather than an address and
+    # a token.
+    #
+    def setup_endpoint(creds)
+      @net = creds
+    end
+  end
+
+  class Response
+    # The Write response forges status and response methods to look
+    # like other classes and create a more consistent interface. As
+    # the request does not happen over HTTP, there's not much to put
+    # in the status object. The response object is the contents of
+    # the summary variable.
+    #
+    # @response=#<struct  sent=1, rejected=0, unsent=0>,
+    # @status=#<struct  result="OK", message=nil, code=nil>>
+    #
+    class Write < Base
+      def populate(raw, status)
+        @response = Struct.new(*raw.keys).new(*raw.values).freeze
+
+        ok = raw[:rejected] == 0 && raw[:unsent] == 0 ? 'OK' : 'ERROR'
+
+        @status = Struct.new(:result, :message, :code).new(ok, nil, nil)
+      end
+    end
+  end
+end

data/spec/.rubocop.yml

@@ -0,0 +1,14 @@
+#
+# Allow long blocks of tests
+#
+Metrics/BlockLength:
+  Max: 120
+
+Metrics/MethodLength:
+  Max: 80
+
+Metrics/AbcSize:
+  Max: 45
+
+Metrics/ClassLength:
+  Max: 300

data/spec/spec_helper.rb

@@ -0,0 +1,157 @@
+#
+# Stuff needed by multiple tests
+#
+require 'minitest/autorun'
+require 'webmock/minitest'
+
+CREDS = {
+  endpoint: 'test.example.com',
+  token:    '0123456789-ABCDEF'
+}
+
+POST_HEADERS = {
+  :'Content-Type' => 'text/plain', :Accept => 'application/json'
+}.freeze
+
+JSON_POST_HEADERS = {
+  :'Content-Type' => 'application/json', :Accept => 'application/json'
+}.freeze
+
+DUMMY_RESPONSE = '{"status":{"result":"OK","message":"","code":200},' \
+                 '"response":{"items":[{"name":"test data"}],"offset":0,' \
+                 '"limit":100,"totalItems":3,"moreItems":false}}'
+
+class WavefrontTestBase < MiniTest::Test
+  attr_reader :wf, :wf_noop, :uri_base, :headers
+
+  def initialize(args)
+    require_relative "../lib/wavefront-sdk/#{class_basename.downcase}"
+    super(args)
+  end
+
+  def class_basename
+    self.class.name.match(/Wavefront(\w+)Test/)[1]
+  end
+
+  def api_base
+    class_basename.downcase
+  end
+
+  def setup
+    klass = Object.const_get('Wavefront').const_get(class_basename)
+    @wf = klass.new(CREDS)
+    @uri_base = "https://#{CREDS[:endpoint]}/api/v2/" + api_base
+    @headers = { 'Authorization' => "Bearer #{CREDS[:token]}" }
+  end
+
+  def target_uri(path)
+    [uri_base, path].join(path.start_with?('?') ? '' : '/')
+  end
+
+  # A shorthand method for very common tests.
+  #
+  # @param method [String] the method you wish to test
+  # @args [String, Integer, Array] arguments with which to call method
+  # @path [String] extra API path components (beyond /api/v2/class)
+  # @call [Symbol] the type of API call (:get, :put etc.)
+  # @more_headers [Hash] any additional headers which should be
+  #   sent. You will normally need to add these for :put and :post
+  #   requests.
+  # @body [String] a JSON object you expect to be sent as part of
+  #   the request
+  #
+  #
+  def should_work(method, args, path, call = :get, more_headers = {},
+                  body = nil, id = nil)
+    path = Array(path)
+    uri = target_uri(path.first).sub(/\/$/, '')
+
+    headers = { 'Accept':          /.*/,
+                'Accept-Encoding': /.*/,
+                'Authorization':  'Bearer 0123456789-ABCDEF',
+                'User-Agent':     "wavefront-sdk #{WF_SDK_VERSION}"
+                }.merge(more_headers)
+
+    if body
+      stub_request(call, uri).with(body: body, headers:headers)
+        .to_return(body: DUMMY_RESPONSE, status: 200)
+    else
+      stub_request(call, uri).to_return(body: DUMMY_RESPONSE, status: 200)
+    end
+
+    if args.is_a?(Hash)
+      if id
+        wf.send(method, id, args)
+      else
+        wf.send(method, args)
+      end
+    else
+      if id
+        wf.send(method, id, *args)
+      else
+        wf.send(method, *args)
+      end
+    end
+
+    assert_requested(call, uri, headers: headers)
+    WebMock.reset!
+  end
+
+  def standard_exception
+    Object.const_get('Wavefront::Exception')
+      .const_get("Invalid#{class_basename}Id")
+  end
+
+  def should_be_invalid(method, args = '!!invalid_val!!')
+    assert_raises(standard_exception) { wf.send(method, *args) }
+  end
+
+  # Generic tag method testing.
+  #
+  def tag_tester(id)
+    # Can we get tags? : tests #tags
+    #
+    should_work('tags', id, "#{id}/tag")
+    should_be_invalid('tags')
+
+    # Can we set tags? tests #tag_set
+    #
+    should_work('tag_set', [id, 'tag'],
+                ["#{id}/tag", ['tag'].to_json], :post, JSON_POST_HEADERS)
+    should_work('tag_set', [id, %w(tag1 tag2)],
+                ["#{id}/tag", %w(tag1 tag2).to_json], :post,
+                JSON_POST_HEADERS)
+    should_fail_tags('tag_set', id)
+
+    # Can we add tags? : tests #tag_add
+    #
+    should_work('tag_add', [id, 'tagval'],
+                ["#{id}/tag/tagval", nil], :put, JSON_POST_HEADERS)
+    should_fail_tags('tag_add', id)
+
+    # Can we delete tags? : tests #tag_delete
+    #
+    should_work('tag_delete', [id, 'tagval'], "#{id}/tag/tagval", :delete)
+    should_fail_tags('tag_delete', id)
+  end
+
+  def should_fail_tags(method, id)
+    assert_raises(standard_exception) do
+      wf.send(method, '!!invalid!!', 'tag1')
+    end
+
+    assert_raises(Wavefront::Exception::InvalidString) do
+      wf.send(method, id, '<!!!>')
+    end
+  end
+end
+
+class Hash
+
+  # A quick way to deep-copy a hash.
+  #
+  def dup
+    Marshal.load(Marshal.dump(self))
+  end
+end
+