wavefront-sdk 0.0.1 → 0.1.0

data/lib/wavefront-sdk/event.rb

@@ -5,7 +5,7 @@ module Wavefront
   # View and manage events. Events are identified by their millisecond
   # epoch timestamp.
   #
-  class Event < Wavefront::Base
+  class Event < Base
     @update_keys = [:startTime, :endTime, :name, :annotations]
 
     # GET /api/v2/event
@@ -17,9 +17,8 @@ module Wavefront
     # @param to [Time, Integer] end ot time range. Can be epoch
     #   millisecods or a Ruby time. If not supplied, defaults to the
     #   current time.
-    # @cursor [String] I think this is the 
-    #   must start with a timestamp.
-    # @limit [Integer] the number of events to return
+    # @param cursor [String] I think this must start with a timestamp.
+    # @param limit [Integer] the number of events to return
     # @return [Hash]
     #
     def list(from = nil, to = nil, limit = 100, cursor = nil)
@@ -52,7 +51,7 @@ module Wavefront
       api_post('', body, 'application/json')
     end
 
-    # DELETE /api/v2/event/{id}
+    # DELETE /api/v2/event/id
     # Delete a specific event.
     #
     # @param id [String] ID of the alert
@@ -63,7 +62,7 @@ module Wavefront
       api_delete(id)
     end
 
-    # GET /api/v2/event/{id}
+    # GET /api/v2/event/id
     # Get a specific event / Get a specific historical version of a
     # specific event.
     #
@@ -79,7 +78,7 @@ module Wavefront
       api_get(fragments.uri_concat)
     end
 
-    # PUT /api/v2/event/{id}
+    # PUT /api/v2/event/id
     # Update a specific event
     #
     # This method helps you update one or more properties of an event.
@@ -101,7 +100,7 @@ module Wavefront
       api_put(id, hash_for_update(describe(id), body), 'application/json')
     end
 
-    # POST /api/v2/event/{id}/close
+    # POST /api/v2/event/id/close
     # Close a specific event.
     #
     # @param id [String] the ID of the event
@@ -111,11 +110,11 @@ module Wavefront
       api_post([id, 'close'].uri_concat)
     end
 
-    # GET /api/v2/event/{id}/tag
+    # GET /api/v2/event/id/tag
     # Get all tags associated with a specific event
     #
     # @param id [String] ID of the event
-    # @returns [Hash] object describing the event with status and
+    # @return [Hash] object describing the event with status and
     #   response keys
     #
     def tags(id)
@@ -123,12 +122,12 @@ module Wavefront
       api_get([id, 'tag'].uri_concat)
     end
 
-    # POST /api/v2/event/{id}/tag
+    # POST /api/v2/event/id/tag
     # Set all tags associated with a specific event.
     #
     # @param id [String] ID of the event
     # @param tags [Array] list of tags to set.
-    # @returns [Hash] object describing the event with status and
+    # @return [Hash] object describing the event with status and
     #   response keys
     #
     def tag_set(id, tags)
@@ -138,12 +137,12 @@ module Wavefront
       api_post([id, 'tag'].uri_concat, tags, 'application/json')
     end
 
-    # DELETE /api/v2/event/{id}/tag/{tagValue}
+    # DELETE /api/v2/event/id/tag/tagValue
     # Remove a tag from a specific event.
     #
     # @param id [String] ID of the event
     # @param tag [String] tag to delete
-    # @returns [Hash] object with 'status' key and empty 'repsonse'
+    # @return [Hash] object with 'status' key and empty 'repsonse'
     #
     def tag_delete(id, tag)
       wf_event_id?(id)
@@ -151,12 +150,12 @@ module Wavefront
       api_delete([id, 'tag', tag].uri_concat)
     end
 
-    # PUT /api/v2/event/{id}/tag/{tagValue}
+    # PUT /api/v2/event/id/tag/tagValue
     # Add a tag to a specific event.
     #
     # @param id [String] ID of the event
     # @param tag [String] tag to set.
-    # @returns [Hash] object with 'status' key and empty 'repsonse'
+    # @return [Hash] object with 'status' key and empty 'repsonse'
     #
     def tag_add(id, tag)
       wf_event_id?(id)
@@ -164,10 +163,4 @@ module Wavefront
       api_put([id, 'tag', tag].uri_concat)
     end
   end
-
-  # A standard response.
-  #
-  class Response
-    class Event < Base; end
-  end
 end

data/lib/wavefront-sdk/exception.rb

@@ -21,7 +21,6 @@ module Wavefront
     class InvalidPoint < ::Exception; end
     class InvalidPrefixLength < ::Exception; end
     class InvalidProxyId < ::Exception; end
-    class InvalidResponse < ::Exception; end
     class InvalidSavedSearchId < ::Exception; end
     class InvalidSavedSearchEntity < ::Exception; end
     class InvalidSourceId < ::Exception; end
@@ -34,6 +33,7 @@ module Wavefront
     class InvalidWebhookId < ::Exception; end
     class InvalidVersion < ::Exception; end
     class NotImplemented < ::Exception; end
+    class UnparseableResponse < ::Exception; end
     class ValueOutOfRange < ::Exception; end
   end
 end

data/lib/wavefront-sdk/externallink.rb

@@ -4,7 +4,7 @@ module Wavefront
   #
   # Manage and query Wavefront external links.
   #
-  class ExternalLink < Wavefront::Base
+  class ExternalLink < Base
     def api_base
       '/extlink'
     end
@@ -22,9 +22,7 @@ module Wavefront
     # POST /api/v2/extlink
     # Create a specific external link.
     #
-    # @param name [String] a plaintext name for the link
-    # @param template [String] a mustache template for the link target
-    # @param description [String] a plaintext description of the link
+    # @param body [Hash] a description of the external link.
     # @return [Hash]
     #
     def create(body)
@@ -32,7 +30,7 @@ module Wavefront
       api_post('', body, 'application/json')
     end
 
-    # DELETE /api/v2/extlink/{id}
+    # DELETE /api/v2/extlink/id
     # Delete a specific external link.
     #
     # @param id [String] ID of the link
@@ -43,7 +41,7 @@ module Wavefront
       api_delete(id)
     end
 
-    # GET /api/v2/extlink/{id}
+    # GET /api/v2/extlink/id
     # Get a specific external link.
     #
     # @param id [String] ID of the limnk
@@ -54,11 +52,11 @@ module Wavefront
       api_get(id)
     end
 
-    # PUT /api/v2/extlink/{id}
+    # PUT /api/v2/extlink/id
     # Update a specific external link.
     #
     # @param id [String] ID of the link
-    # @param payload [Hash] a key:value hash where the key is the
+    # @param body [Hash] a key:value hash where the key is the
     #   property to change and the value is its desired value
     # @return [Hash]
     #
@@ -68,10 +66,4 @@ module Wavefront
       api_put(id, body)
     end
   end
-
-  # A standard response.
-  #
-  class Response
-    class ExternalLink < Base; end
-  end
 end

data/lib/wavefront-sdk/maintenancewindow.rb

@@ -4,7 +4,7 @@ module Wavefront
   #
   # Manage and query Wavefront maintenance windows
   #
-  class MaintenanceWindow < Wavefront::Base
+  class MaintenanceWindow < Base
 
     # GET /api/v2/maintenancewindow
     # Get all maintenance windows for a customer.
@@ -31,7 +31,7 @@ module Wavefront
       api_post('', body, 'application/json')
     end
 
-    # DELETE /api/v2/maintenancewindow/{id}
+    # DELETE /api/v2/maintenancewindow/id
     # Delete a specific maintenance window.
     #
     # @param id [String, Integer] ID of the maintenance window
@@ -42,7 +42,7 @@ module Wavefront
       api_delete(id)
     end
 
-    # GET /api/v2/maintenancewindow/{id}
+    # GET /api/v2/maintenancewindow/id
     # Get a specific maintenance window.
     #
     # @param id [String, Integer] ID of the maintenance window
@@ -53,7 +53,7 @@ module Wavefront
       api_get(id)
     end
 
-    # PUT /api/v2/maintenancewindow/{id}
+    # PUT /api/v2/maintenancewindow/id
     # Update a specific maintenance window.
     #
     # @param body [Hash] a hash of parameters describing the window.
@@ -66,10 +66,4 @@ module Wavefront
       api_put(id, body)
     end
   end
-
-  # A standard response.
-  #
-  class Response
-    class MaintenanceWindow < Base; end
-  end
 end

data/lib/wavefront-sdk/message.rb

@@ -4,7 +4,7 @@ module Wavefront
   #
   # Manage and query Wavefront messages.
   #
-  class Message < Wavefront::Base
+  class Message < Base
 
     # GET /api/v2/message
     # Gets messages applicable to the current user, i.e. within time
@@ -17,20 +17,14 @@ module Wavefront
       api_get('', { offset: offset, limit: limit, unreadOnly: unread_only })
     end
 
-    # POST /api/v2/message/{id}/read
+    # POST /api/v2/message/id/read
     # Mark a specific message as read
     #
-    # @param [id] message ID to mark as read
+    # @param id [String] message ID to mark as read
     #
     def read(id)
       wf_message_id?(id)
       api_post([id, 'read'].uri_concat)
     end
   end
-
-  # A standard response.
-  #
-  class Response
-    class Message < Base; end
-  end
 end

data/lib/wavefront-sdk/metric.rb

@@ -4,7 +4,7 @@ module Wavefront
   #
   # Query Wavefront metrics.
   #
-  class Metric < Wavefront::Base
+  class Metric < Base
     def api_base
       'chart/metric'
     end
@@ -13,8 +13,9 @@ module Wavefront
     # Get more details on a metric, including reporting sources and
     # approximate last time reported
     #
-    # @param offset [Int] agent at which the list begins
-    # @param limit [Int] the number of agents to return
+    # @param metric [String] the metric to fetch
+    # @param sources [Array[String]] a list of sources to check.
+    # @param cursor [String] optionally begin from this result
     #
     def detail(metric, sources = [], cursor = nil)
       raise ArgumentError unless metric.is_a?(String)
@@ -32,21 +33,4 @@ module Wavefront
       api_get('detail', q)
     end
   end
-
-  class Response
-
-    # The Metric response forges status and response methods to look
-    # like other classes and create a more consistent interface.
-    #
-    class Metric < Base
-      def populate(raw, status)
-        @response = Struct.new(*raw.keys).new(*raw.values).freeze
-
-        result = status == 200 ? 'OK' : 'ERROR'
-
-        @status = Struct.new(:result, :message, :code).
-          new(result, raw[:message] || raw[:error], status)
-      end
-    end
-  end
 end

data/lib/wavefront-sdk/proxy.rb

@@ -4,7 +4,7 @@ module Wavefront
   #
   # Manage and query Wavefront proxies.
   #
-  class Proxy < Wavefront::Base
+  class Proxy < Base
 
     # GET /api/v2/proxy
     # Get all proxies for a customer
@@ -16,7 +16,7 @@ module Wavefront
       api_get('', { offset: offset, limit: limit })
     end
 
-    # DELETE /api/v2/proxy/{id}
+    # DELETE /api/v2/proxy/id
     # Delete a specific proxy
     #
     # Deleting an active proxy moves it to 'trash', from where it
@@ -31,7 +31,7 @@ module Wavefront
       api_delete(id)
     end
 
-    # GET /api/v2/proxy/{id}
+    # GET /api/v2/proxy/id
     # Get a specific proxy
     #
     # @param id [String] ID of the proxy
@@ -42,7 +42,7 @@ module Wavefront
       api_get(id)
     end
 
-    # POST /api/v2/proxy/{id}/undelete
+    # POST /api/v2/proxy/id/undelete
     # Undelete a specific proxy
     #
     # Move an proxy from 'trash' back into active service.
@@ -55,7 +55,7 @@ module Wavefront
       api_post([id, 'undelete'].uri_concat)
     end
 
-    # PUT /api/v2/proxy/{id}
+    # PUT /api/v2/proxy/id
     # Update the name of a specific proxy
     #
     # Rename an proxy. This changes the human-readable name, not the
@@ -86,10 +86,4 @@ module Wavefront
       api_put(id, payload)
     end
   end
-
-  # A standard response
-  #
-  class Response
-    class Proxy < Base; end
-  end
 end

data/lib/wavefront-sdk/query.rb

@@ -4,7 +4,7 @@ module Wavefront
   #
   # Query Wavefront metrics.
   #
-  class Query < Wavefront::Base
+  class Query < Base
     def api_base
       'chart'
     end
@@ -25,6 +25,8 @@ module Wavefront
     # @param t_end [Time, Integer] The end of the query window.
     #   May be a Ruby Time object, or epoch milliseconds.
     # @param options [Hash] any other options defined in the API
+    # @raise [ArgumentError] if query is not a string
+    # @return [Wavefront::Response::Query]
     #
     def query(query, granularity = nil, t_start = nil, t_end = nil,
                options = {})
@@ -55,7 +57,7 @@ module Wavefront
     #   (cannot contain wildcards).
     # @param t_start [Time, Integer] start time of window: defaults
     #   to one hour before t_end
-    # @param t_start [Time, Integer] start time of window: defaults
+    # @param t_end [Time, Integer] end time of window: defaults
     #   to now
     #
     def raw(metric, source = nil, t_start = nil, t_end = nil)
@@ -74,23 +76,4 @@ module Wavefront
       api_get('raw', options)
     end
   end
-
-  class Response
-
-    # The Query response forges status and response methods to look
-    # like other classes and create a more consistent interface
-    #
-    class Query < Base
-      def populate(raw, status)
-        @response = Struct.new(*raw.keys).new(*raw.values).freeze
-
-        result = status == 200 ? 'OK' : 'ERROR'
-
-        if raw.key?(:warnings) || raw.key?(:error)
-          @status = Struct.new(:result, :message, :code).
-            new(result, raw[:message] || raw[:error], status)
-        end
-      end
-    end
-  end
 end

data/lib/wavefront-sdk/response.rb

@@ -1,4 +1,5 @@
 require 'json'
+require 'map'
 require_relative './exception'
 
 module Wavefront
@@ -6,50 +7,77 @@ module Wavefront
   # Every API path has its own response class, which allows us to
   # provide a stable interface. If the API changes underneath us,
   # the SDK will break in a predictable way, throwing a
-  # Wavefront::Exception::InvalidResponse exception.
+  # Wavefront::Exception::UnparseableResponse exception.
   #
   # Most Wavefront::Response classes present the returned data in
   # two parts, each accessible by dot notation.
-  #   #status is the status object, which normally contains
-  #   'result', 'message', and 'code'. It is a struct.
-  #  #response contains the JSON response body, turned into a Ruby
-  #  hash.
+  #
+  # @!attribute [r] status
+  #   @return [Wavefront::Types::Status]
+  # @!attribute [r] response
+  #   @return [Map] the response from the API turned into a Map,
+  #     which  allows
   #
   class Response
-    class Base
-      attr_reader :status, :response, :debug
-
-      # Create and return a Wavefront::Response object
-      # @param json [String] a raw response body from the Wavefront API
-      # @param status [Integer] HTTP return code from the API
-      # @param debug [Boolean] whether or not to print the exception
-      #   message if one is thrown
-      # @raise Wavefront::InvalidResponse if the response cannot be
-      #   parsed
-      # @return a Wavefront::Response object
+    attr_reader :status, :response
+
+    # Create and return a Wavefront::Response object
+    # @param json [String] a raw response body from the Wavefront API
+    # @param status [Integer] HTTP return code from the API
+    # @param debug [Boolean] whether or not to print the exception
+    #   message if one is thrown
+    # @raise [Wavefront::Exception::UnparseableResponse] if the
+    #   response cannot be parsed. This may be because the API
+    #   has changed underneath us.
+    #
+    def initialize(json, status, debug = false)
+      raw = json.empty? {} || JSON.parse(json, symbolize_names: true)
+
+      @status = build_status(raw, status)
+      @response = build_response(raw)
+      p self if debug
+    rescue => e
+      puts "could not parse:\n#{json}" if debug
+      puts e.message if debug
+      raise Wavefront::Exception::UnparseableResponse
+    end
+
+    def build_status(raw, status)
+      Wavefront::Type::Status.new(raw, status)
+    end
+
+    def build_response(raw)
+      Map(raw.is_a?(Hash) && raw.key?(:response) ? raw[:response] : raw)
+    end
+  end
+
+  class Type
+    #
+    # An object which provides information about whether the request
+    # was successful or not. Ordinarily this is easy to construct
+    # from the API's JSON response, but some classes, for instance
+    # Wavefront::Write fake it by constructing their own.
+    #
+    # @!attribute [r] result
+    #   @return [OK, ERROR] a string telling us how the request went
+    # @!attribute [r] message
+    #   @return [String] Any informational message from the API
+    # @!attribute [r] code
+    #   @return [Integer] the HTTP response code from the API
+    #     request
+    #
+    class Status
+      attr_reader :result, :message, :code
+
+      # @param raw [Hash] the API response, turned into a hash
+      # @param status [Integer] HTTP status code
       #
-      def initialize(json, status, debug = false)
-        @debug = debug
-        populate(JSON.parse(json, symbolize_names: true), status)
-      rescue => e
-        puts e.message if debug
-        raise Wavefront::Exception::InvalidResponse
-      end
+      def initialize(raw, status)
+        obj = raw.key?(:status) ? raw[:status] : raw
 
-      def populate(raw, _status = 200)
-        if raw.key?(:status)
-          @status = Struct.new(*raw[:status].keys).
-            new(*raw[:status].values).freeze
-        end
-
-        if raw.key?(:response)
-          if raw[:response].key?(:items)
-            @response = Struct.new(*raw[:response].keys).
-              new(*raw[:response].values).freeze
-          else
-            @response = raw[:response]
-          end
-        end
+        @result = obj[:result] || nil
+        @message = obj[:message] || nil
+        @code = obj[:code] || status
       end
     end
   end

data/lib/wavefront-sdk/savedsearch.rb

@@ -5,7 +5,7 @@ module Wavefront
   # View and manage Cloud Integrations. These are identified by
   # a UUID.
   #
-  class SavedSearch < Wavefront::Base
+  class SavedSearch < Base
 
     # GET /api/v2/savedsearch
     # Get all saved searches for a user.
@@ -30,7 +30,7 @@ module Wavefront
       api_post('', body, 'application/json')
     end
 
-    # DELETE /api/v2/savedsearch/{id}
+    # DELETE /api/v2/savedsearch/id
     # Delete a specific saved search.
     #
     # @param id [String] ID of the saved search
@@ -41,7 +41,7 @@ module Wavefront
       api_delete(id)
     end
 
-    # GET /api/v2/savedsearch/{id}
+    # GET /api/v2/savedsearch/id
     # Get a specific saved search.
     #
     # @param id [String] ID of the saved search
@@ -52,7 +52,7 @@ module Wavefront
       api_get(id)
     end
 
-    # PUT /api/v2/savedsearch/{id}
+    # PUT /api/v2/savedsearch/id
     # Update a specific saved search.
     #
     # @param id [String] ID of the saved search
@@ -64,7 +64,7 @@ module Wavefront
       api_put(id, body)
     end
 
-    # GET /api/v2/savedsearch/type/{entitytype}
+    # GET /api/v2/savedsearch/type/entitytype
     # Get all saved searches for a specific entity type for a user.
     #
     # @param entitytype [String] type of entity to retrieve
@@ -79,10 +79,4 @@ module Wavefront
 
     end
   end
-
-  # A standard response
-  #
-  class Response
-    class SavedSearch < Base; end
-  end
 end

data/lib/wavefront-sdk/search.rb

@@ -7,7 +7,7 @@ module Wavefront
   # this class covers the whole API with two methods, but leaves a
   # lot up to the user. It may grow, with convenience methods.
   #
-  class Search < Wavefront::Base
+  class Search < Base
 
     # POST /api/v2/search/agent
     # POST /api/v2/search/agent/deleted
@@ -49,10 +49,4 @@ module Wavefront
       api_post(path, body, 'application/json')
     end
   end
-
-  # A standard response
-  #
-  class Response
-    class Search < Base; end
-  end
 end