diplomat 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 09c6058fde667219b0e08ed9118dc49000da12c9
-  data.tar.gz: b13753886f7406977b20c336093a0c259fa848bc
+  metadata.gz: 8c4fdef4cc41c9b67236ee64307e8f156ffcc790
+  data.tar.gz: 3506d1b24c567796d5fa397ae3055da5efbac41f
 SHA512:
-  metadata.gz: 28e5c5a6251a9dbfd8d3962fdd2eab0f7fc7bf53a085ff1ac35e00584bc90a6bc48c37cec1981265fd0fcc8a34fe99388543284bdd40b71ed76dd76a4a349bdb
-  data.tar.gz: 86db1e94a2adca8ab6d55e05daabcff8ecef6cb64a285a3f4ca6dd21921d938b3b211c6e28a1736f582cef5e33350780bc2906027c8f611ff3d7a7505d9485e4
+  metadata.gz: 837c53a701c4a1d3d1c2d8972bde7895530319dd056dcb9d5d1d9567c0c59ea130e3dca260df277f3f145bec30d18891987a9519e74551e21682090e95fc237d
+  data.tar.gz: 8a0d0aab7c784b5af4bb39a6d7aeb24b717d9c49134293542dc5ba5aa19a53f373bf067502ff0b30a8b7dff40951a49deb39c6cb935e56a1fedf33e4af380a84

data/README.md

@@ -118,6 +118,39 @@ Release a lock:
 Diplomat::Lock.release("/key/to/lock", sessionid )
 ```
 
+### Events
+
+Fire an event:
+
+```ruby
+Diplomat::Event.fire('do_something', 'payload')
+```
+
+List all events with a certain name received by the local agent:
+
+```ruby
+Diplomat::Event.get_all('do_something')
+```
+
+Get the latest event with a certain name received by the local agent:
+
+```ruby
+Diplomat::Event.get('do_something')
+```
+
+Iterate through the events with a certain name received by the local agent:
+
+```ruby
+events = Enumerator.new do |y|
+  ret = {token: :first}
+  while ret = begin Diplomat::Event.get('do_something', ret[:token], :reject) rescue nil end
+    y.yield(ret[:value])
+  end
+end
+
+events.each{ |e| puts e }
+```
+
 ### Custom configuration
 
 You can create a custom configuration using the following syntax:
@@ -136,13 +169,18 @@ This is traditionally kept inside the `config/initializers` directory if you're
 ### Todo
 
 -  [ ] Updating Docs with latest changes
+-  [ ] Using custom objects for response objects (instead of openStruct)
 -  [ ] PUTing and DELETEing services
+-  [ ] Custom SSL Cert Middleware for faraday
 -  [x] Allowing the custom configuration of the consul url to connect to
 -  [x] Deleting Keys
 -  [x] Listing available services
 -  [x] Health
 -  [x] Members
 -  [x] Status
+-  [x] Datacenter support for services
+-  [x] Ruby 1.8 support
+-  [x] Events
 
 
 ## Enjoy!

data/lib/diplomat.rb

@@ -20,7 +20,7 @@ module Diplomat
   self.root_path = File.expand_path "..", __FILE__
   self.lib_path = File.expand_path "../diplomat", __FILE__
 
-  require_libs "configuration", "rest_client", "kv", "service", "members", "check", "health", "session", "lock", "error"
+  require_libs "configuration", "rest_client", "kv", "service", "members", "check", "health", "session", "lock", "error", "event"
   self.configuration ||= Diplomat::Configuration.new
 
   class << self

data/lib/diplomat/error.rb

@@ -1,5 +1,7 @@
 module Diplomat
   class KeyNotFound < StandardError; end
   class KeyAlreadyExists < StandardError; end
+  class EventNotFound < StandardError; end
+  class EventAlreadyExists < StandardError; end
   class UnknownStatus < StandardError; end
 end

data/lib/diplomat/event.rb

@@ -0,0 +1,163 @@
+require 'faraday'
+
+module Diplomat
+  class Event < Diplomat::RestClient
+
+    # Send an event
+    # @param name [String] the event name
+    # @param value [String] the payload of the event
+    # @param service [String] the target service name
+    # @param node [String] the target node name
+    # @param tag [String] the target tag name, must only be used with service
+    # @return [nil]
+    def fire name, value=nil, service=nil, node=nil, tag=nil
+      raw = @conn.put do |req|
+        url = [ "/v1/event/fire/#{name}" ]
+        url += use_named_parameter("service", service)
+        url += use_named_parameter("node", node)
+        url += use_named_parameter("tag", tag) if service
+        req.url concat_url url
+        req.body = value unless value.nil?
+      end
+      nil
+    end
+
+    # Get the list of events matching name
+    # @param name [String] the name of the event (regex)
+    # @param not_found [Symbol] behaviour if there are no events matching name;
+    #   :reject with exception, or :wait for a non-empty list
+    # @param found [Symbol] behaviour if there are already events matching name;
+    #   :reject with exception, :return its current value, or :wait for its next value
+    # @return [Array[hash]] The list of { :name, :payload } hashes
+    # @note
+    #   Events are sent via the gossip protocol; there is no guarantee of delivery
+    #   success or order, but the local agent will store up to 256 events that do
+    #   arrive. This method lists those events.
+    #   It has the same semantics as Kv::get, except the value returned is a list
+    #   i.e. the current value is all events up until now, the next value is the
+    #   current list plus the next event to arrive.
+    #   To get a specific event in the sequence, @see #get
+    #   When trying to get a list of events matching a name, there are two possibilities:
+    #   - The list doesn't (yet) exist / is empty
+    #   - The list exists / is non-empty
+    #   The combination of not_found and found behaviour gives maximum possible
+    #   flexibility. For X: reject, R: return, W: wait
+    #   - X X - meaningless; never return a value
+    #   - X R - "normal" non-blocking get operation. Default
+    #   - X W - get the next value only (must have a current value)
+    #   - W X - get the first value only (must not have a current value)
+    #   - W R - get the first or current value; always return something, but
+    #           block only when necessary
+    #   - W W - get the first or next value; wait until there is an update
+    def get_all name=nil, not_found=:reject, found=:return
+      url = ["/v1/event/list"]
+      url += use_named_parameter("name", name)
+
+      # Event list never returns 404 or blocks, but may return an empty list
+      @raw = @conn.get concat_url url
+      if JSON.parse(@raw.body).count == 0
+        case not_found
+          when :reject
+            raise Diplomat::EventNotFound, name
+          when :wait
+            index = @raw.headers["x-consul-index"]
+        end
+      else
+        case found
+          when :reject
+            raise Diplomat::EventAlreadyExists, name
+          when :return
+            parse_body
+            return return_payload
+          when :wait
+            index = @raw.headers["x-consul-index"]
+        end
+      end
+
+      # Wait for first/next event
+      url += use_named_parameter("index", index)
+      @raw = @conn.get do |req|
+        req.url concat_url url
+        req.options.timeout = 86400
+      end
+      parse_body
+      return_payload
+    end
+
+    # Get a specific event in the sequence matching name
+    # @param name [String] the name of the event (regex)
+    # @param token [String|Symbol] the ordinate of the event in the sequence;
+    #   String are tokens returned by previous calls to this function
+    #   Symbols are the special tokens :first, :last, and :next
+    # @param not_found [Symbol] behaviour if there is no matching event;
+    #   :reject with exception, or :wait for event
+    # @param found [Symbol] behaviour if there is a matching event;
+    #   :reject with exception, or :return its current value
+    # @return [hash] A hash with keys :value and :token;
+    #   :value is a further hash of the :name and :payload of the event,
+    #   :token is the event's ordinate in the sequence and can be passed to future calls to get the subsequent event
+    # @note
+    #   Whereas the consul API for events returns all past events that match
+    #   name, this method allows retrieval of individual events from that
+    #   sequence. However, because consul's API isn't conducive to this, we can
+    #   offer first, last, next (last + 1) events, or arbitrary events in the
+    #   middle, though these can only be identified relative to the preceding
+    #   event. However, this is ideal for iterating through the sequence of
+    #   events (while being sure that none are missed).
+    def get name=nil, token=:last, not_found=:wait, found=:return
+      url = ["/v1/event/list"]
+      url += use_named_parameter("name", name)
+      @raw = @conn.get concat_url url
+      body = JSON.parse(@raw.body)
+      # TODO: deal with unknown symbols, invalid indices (find_index will return nil)
+      idx = case token
+              when :first then 0
+              when :last then body.length - 1
+              when :next then body.length
+              else body.find_index { |e| e["ID"] == token } + 1
+            end
+      if idx == body.length then
+        case not_found
+          when :reject
+            raise Diplomat::EventNotFound, name
+          when :wait
+            # Wait for next event
+            index = @raw.headers["x-consul-index"]
+            url += use_named_parameter("index", index)
+            @raw = @conn.get do |req|
+              req.url concat_url url
+              req.options.timeout = 86400
+            end
+            body = JSON.parse(@raw.body)
+            event = body.last # If it's possible for two events to arrive at once, this needs to #find again
+        end
+      else
+        case found
+          when :reject
+            raise Diplomat::EventAlreadyExits, name
+          when :return
+            event = body[idx]
+        end
+      end
+
+      { :value => { :name => event["Name"], :payload => Base64.decode64(event["Payload"]) },
+        :token => event["ID"] }
+    end
+
+
+    # @note This is sugar, see (#fire)
+    def self.fire *args
+      Diplomat::Event.new.fire *args
+    end
+
+    # @note This is sugar, see (#get_all)
+    def self.get_all *args
+      Diplomat::Event.new.get_all *args
+    end
+
+    # @note This is sugar, see (#get)
+    def self.get *args
+      Diplomat::Event.new.get *args
+    end
+  end
+end

data/lib/diplomat/kv.rb

@@ -13,7 +13,7 @@ module Diplomat
     # @param not_found [Symbol] behaviour if the key doesn't exist;
     #   :reject with exception, or :wait for it to appear
     # @param found [Symbol] behaviour if the key does exist;
-    #   :reject with exception, :wait for its next value, or :return its current value
+    #   :reject with exception, :return its current value, or :wait for its next value
     # @return [String] The base64-decoded value associated with the key
     # @note
     #   When trying to access a key, there are two possibilites:
@@ -33,8 +33,8 @@ module Diplomat
       @options = options
 
       url = ["/v1/kv/#{@key}"]
-      url += check_acl_token unless check_acl_token.nil?
-      url += use_consistency(@options) unless use_consistency(@options).nil?
+      url += check_acl_token
+      url += use_consistency(@options)
 
       # 404s OK using this connection
       raw = @conn_no_err.get concat_url url
@@ -61,10 +61,7 @@ module Diplomat
       end
 
       # Wait for first/next value
-      url = ["/v1/kv/#{@key}"]
-      url += check_acl_token unless check_acl_token.nil?
-      url += use_consistency(@options) unless use_consistency(@options).nil?
-      url += ["index=#{index}"]
+      url += use_named_parameter("index", index)
       @raw = @conn.get do |req|
         req.url concat_url url
         req.options.timeout = 86400
@@ -83,8 +80,8 @@ module Diplomat
       @options = options
       @raw = @conn.put do |req|
         url = ["/v1/kv/#{key}"]
-        url += check_acl_token unless check_acl_token.nil?
-        url += use_cas(@options) unless use_cas(@options).nil?
+        url += check_acl_token
+        url += use_cas(@options)
         req.url concat_url url
         req.body = value
       end
@@ -101,7 +98,7 @@ module Diplomat
     def delete key
       @key = key
       url = ["/v1/kv/#{@key}"]
-      url += check_acl_token unless check_acl_token.nil?
+      url += check_acl_token
       @raw = @conn.delete concat_url url
     end
 
@@ -122,41 +119,16 @@ module Diplomat
 
     private
 
-    # Parse the body, apply it to the raw attribute
-    def parse_body
-      @raw = JSON.parse(@raw.body)
-    end
-
-    # Get the key from the raw output
-    def return_key
-      @key = @raw["Key"]
-    end
-
-    # Get the value from the raw output
-    def return_value
-      if @raw.count == 1
-        @value = @raw.first["Value"]
-        @value = Base64.decode64(@value) unless @value.nil?
-      else
-        @value = @raw.map do |e|
-                   {
-                     :key => e["Key"],
-                     :value => e["Value"].nil? ? e["Value"] : Base64.decode64(e["Value"])
-                   }
-                 end
-      end
-    end
-
     def check_acl_token
-      ["token=#{Diplomat.configuration.acl_token}"] if Diplomat.configuration.acl_token
+      use_named_parameter("token", Diplomat.configuration.acl_token)
     end
 
     def use_cas(options)
-      ["cas=#{options[:cas]}"] if options && options[:cas]
+      if options then use_named_parameter("cas", options[:cas]) else [] end
     end
 
     def use_consistency(options)
-      ["#{options[:consistency]}"] if options && options[:consistency]
+      if options && options[:consistency] then ["#{options[:consistency]}"] else [] end
     end
   end
 end

data/lib/diplomat/rest_client.rb

@@ -8,12 +8,16 @@ module Diplomat
       start_connection api_connection
     end
 
+    def use_named_parameter(name, value)
+      if value then ["#{name}=#{value}"] else [] end
+    end
+
     def concat_url parts
-        if parts.length > 1 then
-            parts.first << '?' << parts.drop(1).join('&')
-        else
-            parts.first
-        end
+      if parts.length > 1 then
+        parts.first + '?' + parts.drop(1).join('&')
+      else
+        parts.first
+      end
     end
 
     private
@@ -41,5 +45,33 @@ module Diplomat
       end
     end
 
+    # Parse the body, apply it to the raw attribute
+    def parse_body
+      @raw = JSON.parse(@raw.body)
+    end
+
+    # Get the key/value(s) from the raw output
+    def return_value
+      if @raw.count == 1
+        @value = @raw.first["Value"]
+        @value = Base64.decode64(@value) unless @value.nil?
+      else
+        @value = @raw.map do |e|
+          {
+            :key => e["Key"],
+            :value => (Base64.decode64(e["Value"]) unless e["Value"].nil?)
+          }
+        end
+      end
+    end
+
+    # Get the name and payload(s) from the raw output
+    def return_payload
+      @value = @raw.map do |e|
+        { :name => e["Name"],
+          :payload => (Base64.decode64(e["Payload"]) unless e["Payload"].nil?) }
+      end
+    end
+
   end
 end

data/lib/diplomat/version.rb

@@ -1,3 +1,3 @@
 module Diplomat
-  VERSION = "0.7.0"
+  VERSION = "0.8.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: diplomat
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.8.0
 platform: ruby
 authors:
 - John Hamelink
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-05-04 00:00:00.000000000 Z
+date: 2015-05-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -180,6 +180,7 @@ files:
 - lib/diplomat/check.rb
 - lib/diplomat/configuration.rb
 - lib/diplomat/error.rb
+- lib/diplomat/event.rb
 - lib/diplomat/health.rb
 - lib/diplomat/kv.rb
 - lib/diplomat/lock.rb