kapacitor-ruby 0.0.14 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 82ce3690bdcf6c10b5f3470557f61812dacdf11b
-  data.tar.gz: bf3d8bfb1845055a22735db2450808c63c72b6e4
+  metadata.gz: 102b40a3d2e642e578b98767820e73cfda264ba6
+  data.tar.gz: 86987d17ef079c29882d6987c39746346034bd3a
 SHA512:
-  metadata.gz: 2cdf19fe98d1d673e0ca8a340a9f8f2934e4cc77cd2624f16f7cdda2f4abd6916e5896edc61df80b015fe0ac9f3579564ebf4775fc94b0155179da7431143662
-  data.tar.gz: 8e8f9f3bf74a98f6e67cd456a34605626d3a42b6f4ad10d83cb01303a5b9d70a630561c759c2b67bbdbabc4c55474fa16fb8da21879dbae881ddae424923d4e1
+  metadata.gz: 157f9a71d7a9bcef701a72d25d602151acc7f12b3376e00fa9273c30d12f47c2fb12b133989005c9fbe8d631659017762dcd421af2cc650409900fbd50fabc97
+  data.tar.gz: e82e8b70df2a1bc3051e6912d46e07fde3a16f5ec0a9848ca9418402bc0e3b1131c0e2611587b7d4d885a21c024a738222359dedc00e4a65ee7ee7213806f587

data/README.md

@@ -11,63 +11,7 @@ gem install kapacitor-ruby
 ```
 
 ## Usage
-```
-require 'kapacitor/client'
-kapacitor = Kapacitor::Client.new(host: 'localhost:9092', version: 'v1')
-```
-
-### Templates
-
-#### `define_template`
-Create a new template definition
-```
-define_template(id: 'name', type: 'stream', script: 'tickscript')
-```
-
-#### `update_template`
-Update one or more templates' options
-```
-update_template(id: 'name', type: 'batch')
-```
-
-#### `delete_template`
-Delete a template
-```
-delete_template(id: 'name')
-```
-
-#### `templates`
-Fetch all templates
-```
-templates()
-```
-
-### Tasks
-
-#### `define_task`
-Create a new task
-```
-define_task(id: 'name', template_id: 'optional template', type: 'stream', dbrps: [{'db' => 'telegraf', 'rp' => 'default'}], script: 'tickscript', status: 'enabled', vars: {})
-```
-
-#### `update_task`
-Update one or more task's options
-
-```
-update_task(id: 'name', template_id: 'optional template', type: 'stream', dbrps: [{'db' => 'telegraf', 'rp' => 'default'}], script: 'tickscript', status: 'enabled', vars: {})
-```
-
-#### `delete_task`
-Delete a task
-```
-delete_task(id: 'name')
-```
-
-#### `tasks`
-Fetch all tasks
-```
-tasks()
-```
+Online documentation is available at [rubydoc](http://www.rubydoc.info/gems/kapacitor-ruby/).
 
 ## Contact
 Matteo Cerutti - matteo.cerutti@hotmail.co.uk

data/lib/kapacitor/client.rb

@@ -1,136 +1,172 @@
-#
-# client.rb
-#
-
 require 'net/http'
 require 'json'
 
 module Kapacitor
   class Client
-    attr_reader :uri, :http
-
-    def initialize(opts = {})
-      host = opts['host'] || 'localhost:9092'
-      version = opts['version'] || 'v1'
-
-      @uri = URI.parse("http://#{host}/kapacitor/#{version}")
+    # @return [URI] Kapacitor REST API URL
+    attr_reader :uri
+    # @return [Net::HTTP] HTTP client instance
+    attr_reader :http
+
+    # Create a new client
+    #
+    # @param url [String] Kapacitor REST API's URL (defaults to `http://localhost:9092`)
+    # @param version [Integer] API version (defaults to `v1preview`)
+    #
+    def initialize(host: 'http://localhost:9092', version: 'v1preview')
+      @uri = URI.parse("#{host}/kapacitor/#{version}")
       @http = Net::HTTP.new(@uri.host, @uri.port)
     end
 
-    def define_template(id, opts = {})
-      raise ArgumentError, "Kapacitor template type is required" unless opts['type']
-      raise ArgumentError, "Kapacitor template tickscript required" unless opts['script']
-
-      if opts['type']
-        raise ArgumentError, "Kapacitor template type can be either 'batch' or 'stream'" unless (opts['type'] == 'batch' or opts['type'] == 'stream')
-      end
+    # Define a Kapacitor template
+    #
+    # @param id [String] Template ID
+    # @param type [String] Template type. Valid values: `batch`, `stream`.
+    # @param script [String] Tick script
+    #
+    def define_template(id:, type:, script:)
+      raise ArgumentError, "Kapacitor template type can be either 'batch' or 'stream'" unless type == 'batch' || type == 'stream'
 
       req = {
         'id' => id,
-        'type' => opts['type'],
-        'script' => opts['script']
+        'type' => type,
+        'script' => script
       }
 
-      api_post('/templates', req)
+      api_post(endpoint: '/templates', data: req)
     end
 
-    def update_template(id, opts = {})
+    # Update a Kapacitor template
+    #
+    # @param id [String] Template ID
+    # @param **opts [Hash] Any number of template parameters to push into the Hash
+    #
+    def update_template(id:, **opts)
       req = {}
-      req['type'] = opts['type'] if opts['type']
-      req['script'] = opts['script'] if opts['script']
+      req['type'] = opts[:type] if opts[:type]
+      req['script'] = opts[:script] if opts[:script]
 
-      if opts['type']
-        raise ArgumentError, "Kapacitor template type can be either 'batch' or 'stream'" unless (opts['type'] == 'batch' or opts['type'] == 'stream')
+      if opts[:type]
+        raise ArgumentError, "Kapacitor template type can be either 'batch' or 'stream'" unless opts[:type] == 'batch' or opts[:type] == 'stream'
       end
 
-      api_patch("/templates/#{id}", req) unless req.empty?
+      api_patch(endpoint: "/templates/#{id}", data: req) unless req.empty?
     end
 
-    def delete_template(id)
-      api_delete("/templates/#{id}")
+    # Delete a Kapacitor template
+    #
+    # @param id [String] Template ID
+    #
+    def delete_template(id:)
+      api_delete(endpoint: "/templates/#{id}")
     end
 
+    # Retrieve Kapacitor templates
+    #
+    # @param offset [Integer] Offset count for paginating through templates
+    # @param limit [Integer] Maximum number of templates to return
+    # @return [Array[Hash]] List of templates
+    #
     def templates(offset: 0, limit: 100)
-      templates = []
+      ret = []
 
       loop do
-        res = api_get("/templates?offset=#{offset}&limit=#{limit}")['templates']
+        res = api_get(endpoint: "/templates?offset=#{offset}&limit=#{limit}")['templates']
         break unless res.size > 0
-        templates += res
+        ret += res
         offset += limit
       end
 
-      templates
+      ret
     end
 
-    def define_task(id, opts = {})
-      raise ArgumentError, "Kapacitor task dbrps is required" unless opts['dbrps']
-
-      if (opts['template_id'].nil? and opts['type'].nil? and opts['script'].nil?) or (opts['template_id'] and (opts['type'] or opts['script']))
+    # Define a Kapacitor task
+    #
+    # @param id [String] Task ID
+    # @param dbrps [String] List of database retention policy pairs the task is allowed to access.
+    # @param **opts [Hash] Any number of task parameters to push into the Hash
+    #
+    def define_task(id:, dbrps:, **opts)
+      if (opts[:template_id].nil? && opts[:type].nil? && opts[:script].nil?) || (opts[:template_id] && (opts[:type] || opts[:script]))
         raise ArgumentError, "Must specify either a Template ID or a script and type"
-      elsif opts['template_id'].nil? and (opts['type'].nil? or opts['script'].nil?)
+      elsif opts['template_id'].nil? && (opts['type'].nil? || opts['script'].nil?)
         raise ArgumentError, "Must specify both task type and script when not using a Template ID"
       end
 
-      if opts['status']
-        raise ArgumentError, "Kapacitor task status can be either 'enabled' or 'disabled'" unless (opts['status'] == 'enabled' or opts['status'] == 'disabled')
+      if opts[:status]
+        raise ArgumentError, "Kapacitor task status can be either 'enabled' or 'disabled'" unless opts[:status] == 'enabled' || opts[:status] == 'disabled'
       end
 
-      if opts['type']
-        raise ArgumentError, "Kapacitor task type can be either 'batch' or 'stream'" unless (opts['type'] == 'batch' or opts['type'] == 'stream')
+      if opts[:type]
+        raise ArgumentError, "Kapacitor task type can be either 'batch' or 'stream'" unless opts[:type] == 'batch' || opts[:type] == 'stream'
       end
 
       req = {
         'id' => id,
-        'dbrps' => opts['dbrps'],
-        'status' => opts['status'] || 'enabled'
+        'dbrps' => dbrps,
+        'status' => opts[:status] || 'enabled'
       }
 
-      if opts['template_id']
-        req['template-id'] = opts['template_id']
+      if opts[:template_id]
+        req['template-id'] = opts[:template_id]
       else
-        req['type'] = opts['type']
-        req['script'] = opts['script']
+        req['type'] = opts[:type]
+        req['script'] = opts[:script]
       end
 
-      req['vars'] = opts['vars'] if opts['vars']
+      req['vars'] = opts[:vars] if opts[:vars]
 
-      api_post('/tasks', req)
+      api_post(endpoint: '/tasks', data: req)
     end
 
-    def update_task(id, opts = {})
+    # Update a Kapacitor task
+    #
+    # @param id [String] Task ID
+    # @param **opts [Hash] Any number of task parameters to push into the Hash
+    #
+    def update_task(id:, **opts)
       req = {}
-      req['template-id'] = opts['template_id'] if opts['template_id']
-      req['type'] = opts['type'] if opts['type']
-      req['dbrps'] = opts['dbrps'] if opts['dbrps']
-      req['script'] = opts['script'] if opts['script']
-      req['status'] = opts['status'] if opts['status']
-      req['vars'] = opts['vars'] if opts['vars']
-
-      if opts['type']
-        raise ArgumentError, "Kapacitor template type can be either 'batch' or 'stream'" unless (opts['type'] == 'batch' or opts['type'] == 'stream')
+      req['template-id'] = opts[:template_id] if opts[:template_id]
+      req['type'] = opts[:type] if opts[:type]
+      req['dbrps'] = opts[:dbrps] if opts[:dbrps]
+      req['script'] = opts[:script] if opts[:script]
+      req['status'] = opts[:status] if opts[:status]
+      req['vars'] = opts[:vars] if opts[:vars]
+
+      if opts[:type]
+        raise ArgumentError, "Kapacitor template type can be either 'batch' or 'stream'" unless opts[:type] == 'batch' || opts[:type] == 'stream'
       end
 
       if opts['status']
-        raise ArgumentError, "Kapacitor task status can be either 'enabled' or 'disabled'" unless (opts['status'] == 'enabled' or opts['status'] == 'disabled')
+        raise ArgumentError, "Kapacitor task status can be either 'enabled' or 'disabled'" unless opts[:status] == 'enabled' || opts[:status] == 'disabled'
       end
 
-      api_patch("/tasks/#{id}", req) unless req.empty?
+      api_patch(endpoint: "/tasks/#{id}", data: req) unless req.empty?
     end
 
-    def delete_task(id)
-      api_delete("/tasks/#{id}")
+    # Delete a Kapacitor task
+    #
+    # @param id [String] Task ID
+    #
+    def delete_task(id:)
+      api_delete(endpoint: "/tasks/#{id}")
     end
 
+    # Retrieve Kapacitor tasks
+    #
+    # @param offset [Integer] Offset count for paginating through tasks
+    # @param limit [Integer] Maximum number of tasks to return
+    # @return [Array[Hash]] List of tasks
+    #
     def tasks(offset: 0, limit: 100)
       tasks = []
 
       loop do
-        res = api_get("/tasks?fields=id&offset=#{offset}&limit=#{limit}")['tasks']
+        res = api_get(endpoint: "/tasks?fields=id&offset=#{offset}&limit=#{limit}")['tasks']
         break unless res.size > 0
 
         res.each do |task|
-          tasks << api_get("/tasks/#{task['id']}")
+          tasks << api_get(endpoint: "/tasks/#{task['id']}")
         end
 
         offset += limit
@@ -139,10 +175,70 @@ module Kapacitor
       tasks
     end
 
+    # Define a topic handler
+    #
+    # @param id [String] Handler ID
+    # @param topic [String] Topic name
+    # @param actions [Array[Hash]] Handler actions
+    #
+    def define_topic_handler(id:, topic:, actions:)
+      req = {}
+      req['id'] = id
+
+      actions = [actions] unless actions.is_a?(Array)
+      raise ArgumentError, "Kapacitor topic handler requires one or more actions" unless actions.size > 0
+
+      actions.each do |action|
+        raise ArgumentError, "Missing required kind attribute for action #{action}"
+      end
+
+      req['actions'] = actions
+      api_post(endpoint: "/alerts/topics/#{topic}/handlers", data: req)
+    end
+
+    # Update a topic handler
+    #
+    # @param id [String] Handler ID
+    # @param topic [String] Topic name
+    # @param actions [Array[Hash]] Handler actions
+    #
+    def update_topic_handler(id:, topic:, actions:)
+      req = {}
+
+      actions = [actions] unless actions.is_a?(Array)
+      raise ArgumentError, "Kapacitor topic handler requires one or more actions" unless actions.size > 0
+
+      req['actions'] = actions
+      api_put(endpoint: "/alerts/topics/#{topic}/handlers/#{id}", data: req) unless req.empty?
+    end
+
+    # Delete a topic handler
+    #
+    # @param id [String] Handler ID
+    # @param topic [String] Topic name
+    #
+    def delete_topic_handler(id:, topic:)
+      api_delete(endpoint: "/alerts/topics/#{topic}/handlers/#{id}")
+    end
+
+    # Retrieve topic's handlers
+    #
+    # @param topic [String] Topic name
+    # @return [Array[Hash]] List of handlers
+    #
+    def topic_handlers(topic:)
+      return api_get(endpoint: "/alerts/topics/#{topic}/handlers")['handlers']
+    end
+
 private
-    def api_get(q)
+    # Perform a HTTP GET request
+    #
+    # @param endpoint [String] HTTP API endpoint
+    # @return [Array[Hash], Hash] API response
+    #
+    def api_get(endpoint:)
       begin
-        req = Net::HTTP::Get.new(self.uri.path + q, {'Content-type' => 'application/json', 'Accept' => 'application/json'})
+        req = Net::HTTP::Get.new(self.uri.path + endpoint, {'Content-type' => 'application/json', 'Accept' => 'application/json'})
         resp = self.http.request(req)
 
         if resp.code == '200'
@@ -161,9 +257,14 @@ private
       data
     end
 
-    def api_post(q, data)
+    # Perform a HTTP POST request
+    #
+    # @param endpoint [String] HTTP API endpoint
+    # @param data [Hash] Request data
+    #
+    def api_post(endpoint:, data:)
       begin
-        req = Net::HTTP::Post.new(self.uri.path + q, {'Content-Type' => 'application/json', 'Accept' => 'application/json'})
+        req = Net::HTTP::Post.new(self.uri.path + endpoint, {'Content-Type' => 'application/json', 'Accept' => 'application/json'})
         req.body = data.to_json
         resp = self.http.request(req)
 
@@ -183,9 +284,13 @@ private
       data
     end
 
-    def api_delete(q)
+    # Perform a HTTP DELETE request
+    #
+    # @param endpoint [String] HTTP API endpoint
+    #
+    def api_delete(endpoint:)
       begin
-        req = Net::HTTP::Delete.new(self.uri.path + q, {'Content-type' => 'application/json', 'Accept' => 'application/json'})
+        req = Net::HTTP::Delete.new(self.uri.path + endpoint, {'Content-type' => 'application/json', 'Accept' => 'application/json'})
         resp = self.http.request(req)
 
         if resp.code == '204'
@@ -206,9 +311,14 @@ private
       data
     end
 
-    def api_patch(q, data)
+    # Perform a HTTP PATCH request
+    #
+    # @param endpoint [String] HTTP API endpoint
+    # @param data [Hash] Request data
+    #
+    def api_patch(endpoint:, data:)
       begin
-        req = Net::HTTP::Patch.new(self.uri.path + q, {'Content-Type' => 'application/json', 'Accept' => 'application/json'})
+        req = Net::HTTP::Patch.new(self.uri.path + endpoint, {'Content-Type' => 'application/json', 'Accept' => 'application/json'})
         req.body = data.to_json
         resp = self.http.request(req)
 
@@ -227,5 +337,32 @@ private
 
       data
     end
+
+    # Perform a HTTP PUT request
+    #
+    # @param endpoint [String] HTTP API endpoint
+    # @param data [Hash] Request data
+    #
+    def api_put(endpoint:, data:)
+      begin
+        req = Net::HTTP::Put.new(self.uri.path + endpoint, {'Content-Type' => 'application/json', 'Accept' => 'application/json'})
+        req.body = data.to_json
+        resp = self.http.request(req)
+
+        if resp.code == '200'
+          begin
+            data = JSON.parse(resp.body)
+          rescue JSON::ParserError
+            raise Exception, "Failed to decode response message"
+          end
+        else
+          raise Exception, "Query returned a non successful HTTP code (Code: #{resp.code}, Error: #{resp.message})"
+        end
+      rescue
+        raise Exception, "Failed to execute PUT request to Kapacitor REST API (#{$!})"
+      end
+
+      data
+    end
   end
 end

data/lib/kapacitor/version.rb

@@ -3,7 +3,7 @@
 #
 
 module Kapacitor
-  VERSION = "0.0.14"
+  VERSION = "1.0.0"
 
   def self.version
     VERSION

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: kapacitor-ruby
 version: !ruby/object:Gem::Version
-  version: 0.0.14
+  version: 1.0.0
 platform: ruby
 authors:
 - Matteo Cerutti
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-04-24 00:00:00.000000000 Z
+date: 2017-09-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json