consul-ruby-client 0.0.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: ea81d2569729debbb271b229358775f919a0de0c
+  data.tar.gz: 521ad0389c65a8d57ca62202faada9546d467416
+SHA512:
+  metadata.gz: 5c86f347a8a0ca26a65a4cf825688544ce14d75d2988a6e38d78c5c4adfdb3f9f9cbfbef0ebe78dab87212220bf13bcf68a43be07f18160aa1253ceac90e7073
+  data.tar.gz: 93e0c798a11880043e1545daa87eb84e6210af4f91f5849bd1640c0a3adbc6db127db645943f7a5ed40244bcbb65591367d05196ed177908bae3c2cc6c27546a

data/.gitignore

@@ -0,0 +1,17 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log
+
+# Ignore all development gems.
+*.gem

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in consul-ruby-client.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Michael Hotan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2015 Michael Hotan
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,81 @@
+# Consul::Client
+
+Thin Ruby Client around Consul REST API
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'consul-ruby-client'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install consul-ruby-client
+
+## Usage
+
+To use the client you have to require the root library
+
+```
+# Add the dependencies
+require 'consul/client'
+
+# Import that namespace
+include Consul::Client
+```
+
+### Key Value Store
+
+```
+kvs = KeyValue.new
+kvs.put('cat','dog')
+kvs.get('cat')
+
+```
+
+### Agent
+
+```
+agent = Agent.new
+agent.register(Agent::Service.for_name('my_service'))
+agent.services
+```
+
+### Catalog
+
+TODO
+
+### Sessions
+
+TODO
+
+### Status
+
+TODO
+
+## TODO
+
+* Tests,
+Currently all test were done throught building and installing the ruby client
+and verifying through REPL.  That is not the long term solution.  We are looking
+at integrating Consul into the rspec test itself.
+However a solid short term win will be completing rspec tests with set fixtures.
+
+* Implement more advance locking mechanisms
+* Complete the Agent API self, join, and force-leave
+* ACL API
+* Events
+
+## Contributing
+
+1. Fork it ( https://github.com/[my-github-username]/consul-client/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request

data/Rakefile

@@ -0,0 +1,2 @@
+require "bundler/gem_tasks"
+

data/consul-ruby-client.gemspec

@@ -0,0 +1,29 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'consul/client/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'consul-ruby-client'
+  spec.version       = Consul::Client::VERSION
+  spec.authors       = ['Michael Hotan']
+  spec.email         = ['michael.hotan@socrata.com']
+  spec.summary       = %q{Ruby Client library for communicating with Consul Agents.}
+  spec.description   = %q{Consul agents expose a HTTP REST API and this library is used to communicate directly with it.}
+  spec.homepage      = 'https://github.com/mhotan-s/consul-ruby-client'
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ['lib']
+
+  spec.add_development_dependency 'bundler', '~> 1.7'
+  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'rspec', '~> 3.2'
+  spec.add_development_dependency 'simplecov', '~> 0.9'
+  spec.add_development_dependency 'webmock', '~> 1.21'
+  spec.add_dependency 'rest-client', '~> 1.6'
+  spec.add_dependency 'representable', '~> 2.1'
+  spec.add_dependency 'json', '~> 1.8'
+end

data/lib/consul/client.rb

@@ -0,0 +1,18 @@
+require_relative '../consul/model/health_check'
+require_relative '../consul/model/key_value'
+require_relative '../consul/model/node'
+require_relative '../consul/model/service'
+require_relative '../consul/model/session'
+require_relative '../consul/client/version'
+require_relative '../consul/client/base'
+require_relative '../consul/client/agent'
+require_relative '../consul/client/catalog'
+require_relative '../consul/client/key_value'
+require_relative '../consul/client/session'
+require_relative '../consul/client/status'
+
+module Consul
+  module Client
+    # Modules added above.
+  end
+end

data/lib/consul/client/agent.rb

@@ -0,0 +1,322 @@
+require_relative 'base'
+require_relative '../model/service'
+require_relative '../model/health_check'
+
+# Consul Agent Client.
+# Represents Ruby endpoint as described here: https://www.consul.io/docs/agent/http/agent.html
+module Consul
+  module Client
+    class Agent
+      include Consul::Client::Base
+
+      # Public: Returns all the services registered with this Agent.
+      #
+      # Returns: An array of all the ConsulService(s) registered on this agent.
+      def services
+        begin
+          resp = _get build_agent_url('services')
+        rescue
+          @logger.warn('Unable to request all the services on this through the HTTP API')
+          return nil
+        end
+        # Consul returns id => ConsulServiceObjects.
+        s_hash = JSON.parse(resp)
+        s_hash.keys.map { |n| Consul::Model::Service.new.extend(Consul::Model::Service::Representer).from_hash(s_hash[n]) }
+      end
+
+      # Public: Returns the service that has the associated name.
+      #
+      # Returns: ConsulService if exists, nil if no service by this name exists.
+      def service(id)
+        ss = services
+        ss.keep_if {|s| s.id == id}.first unless ss.nil?
+      end
+
+      def checks
+        begin
+          resp = _get build_agent_url('checks')
+        rescue
+          @logger.warn('Unable to request all the checks on this through the HTTP API')
+          return nil
+        end
+        # Consul returns id => ConsulServiceObjects.
+        s_hash = JSON.parse(resp)
+        s_hash.keys.map { |n| Consul::Model::HealthCheck.new.extend(Consul::Model::HealthCheck::Representer).from_hash(s_hash[n]) }
+      end
+
+      # Public: Returns a check by a given id.
+      # Returns: nil if no such check exists, or the check instance with the correct id
+      def check(id)
+        c = checks
+        c.keep_if {|c| c.check_id == id}.first unless c.nil?
+      end
+
+      # Public: Returns a Health Check for a specific service.
+      #
+      # service_id - The ID of the service.
+      def service_check(service_id)
+        check("service:#{service_id}")
+      end
+
+      # Public: Registers either a service or a Health check with configured consul agent.
+      #
+      # entity - Consul::Model::Service or Consul::Model::HealthCheck instance.
+      #
+      # Example
+      #   agent = Consul::Client::Agent.new('dc1')
+      #   # Register a service
+      #   agent.register(Consul::Client::Agent::Service.for_name('cat'))
+      #   # Register a HealthCheck
+      #   agent.register(Consul::Client::HealthCheck.ttl('my_check_name', '15m'))
+      #   # Register a service with a Consul Health Check
+      #   agent.register(Consul::Client::Agent::Service.for_name('cat', Consul::Client::Agent::Service.ttl_health_check('15m')))
+      #
+      # Returns true upon success, false upon failure
+      def register(entity)
+        raise TypeError unless entity.kind_of? Consul::Model::HealthCheck or entity.kind_of? Consul::Model::Service
+        case entity
+          when Consul::Model::HealthCheck
+            return register_with_backoff(build_check_url('register'), entity.extend(Consul::Model::HealthCheck::Representer), 0, 3)
+          else
+            entity = entity.extend(Consul::Model::Service::Representer)
+            success = register_with_backoff(build_service_url('register'), entity, 0, 3)
+            if success
+              @logger.info("Successfully registered service #{entity.name}.")
+              unless entity.check.nil?
+                # Pass the first health check
+                c = check("service:#{entity.name}")
+                @logger.info("Updating status for health check #{c.check_id} to \"pass\".")
+                _get build_check_status_url(c.check_id, 'pass')
+              end
+            end
+            return success
+        end
+      end
+
+      # Public: deregisters an existing ConsulHealthCheck or ConsulService
+      #
+      # entity - ConsulHealthCheck or ConsulService to unregister from this
+      #
+      # Returns - the HTTP Response
+      def deregister(entity)
+        unless entity.nil?
+          raise TypeError unless entity.kind_of? Consul::Model::HealthCheck or entity.kind_of? Consul::Model::Service
+          case entity
+            when Consul::Model::HealthCheck
+              url = build_check_url('deregister')
+            else
+              url = build_service_url('deregister')
+          end
+          _get "#{url}/#{entity.id}"
+        end
+      end
+
+      # Public: Pass a health check.
+      #
+      # check - Consul::Model::HealthCheck to pass.  Cannot be nil or wrong type
+      #
+      def pass(check)
+        update_check_status(check, 'pass')
+      end
+
+      # Public: Warn a health check
+      #
+      # check - Consul::Model::HealthCheck to pass.  Cannot be nil or wrong type
+      #
+      def warn(check)
+        update_check_status(check, 'warn')
+      end
+
+      # Public: Fails a health check
+      #
+      # check - Consul::Model::HealthCheck to pass.  Cannot be nil or wrong type
+      #
+      def fail(check)
+        update_check_status(check, 'fail')
+      end
+
+      # Public: Enter maintenance mode.
+      #
+      # enable  - Flag to indicate to enable maintanence mode or not
+      # service - Set maintanence for a particular service is set.
+      # reason  - Optional reason.
+      def maintenance(enable, service = nil, reason = nil)
+        if service.nil?
+          url = build_agent_url('maintenance')
+        else
+          if service.instance_of?(Consul::Model::Service)
+            service = service.id
+          end
+          raise ArgumentError.new "Unable to create request for #{service}" unless service.respond_to?(:to_str)
+          url = build_service_url("maintenance/#{service}")
+        end
+        params = {:enable => enable}
+        params[:reason] = reason unless reason.nil?
+        _get url, params
+      end
+
+      module HealthCheck
+
+        # Public: TTL Check
+        #
+        # name  - The name of the check, Cannot be nil
+        # ttl   - Time to live time window. IE "15s", Cannot be nil
+        # id    - ID to associate with this check if 'name' is not desired.
+        # notes - Message to place as notes for this check
+        #
+        # Returns: Consul::Model::HealthCheck instance
+        def self.ttl(name, ttl, id = name, notes = nil)
+          validate_arg name
+          validate_arg ttl
+          c = Consul::Model::HealthCheck.new(name: name, ttl: ttl)
+          c[:id] = id unless id.nil?
+          c[:notes] = notes unless notes.nil?
+          c
+        end
+
+        # Public: TTL Check
+        #
+        # name      - The name of the check, Cannot be nil
+        # script    - The script to run locally
+        # interval  - The time interval to conduct the check. IE: '10s'
+        # id        - ID to associate with this check if 'name' is not desired.
+        # notes     - Message to place as notes for this check.
+        #
+        # Returns: Consul::Model::HealthCheck instance
+        def self.script(name, script, interval, id = name, notes = nil)
+          validate_arg name
+          validate_arg script
+          validate_arg interval
+          c = Consul::Model::HealthCheck.new(name: name, script: script, interval: interval)
+          c[:id] = id unless id.nil?
+          c[:notes] = notes unless notes.nil?
+          c
+        end
+
+        # Public: TTL Check
+        #
+        # name      - The name of the check, Cannot be nil
+        # http      - The HTTP endpoint to hit with periodic GET.
+        # interval  - The time interval to conduct the check. IE: '10s'
+        # id        - ID to associate with this check if 'name' is not desired.
+        # notes     - Message to place as notes for this check
+        #
+        # Returns: Consul::Model::HealthCheck instance
+        def self.http(name, http, interval, id = name, notes = nil)
+          validate_arg name
+          validate_arg http
+          validate_arg interval
+          c = Consul::Model::HealthCheck.new(name: name, script: script, interval: interval)
+          c[:id] = id unless id.nil?
+          c[:notes] = notes unless notes.nil?
+          c
+        end
+
+        private
+
+        def self.validate_arg(arg)
+          raise ArgumentError.new "Illegal Argument: #{arg}" if arg.nil? or arg.empty?
+        end
+
+      end
+
+      # Container Module for simpler way to create a service.
+      module Service
+
+        # Public: Creates a service using a specific name
+        #
+        # name  -  Name of the service to create
+        # check - The Consul::Model::HealthCheck instance to associate with this Session
+        #
+        # Returns: Consul::Model::Service instance
+        def self.for_name(name, check = nil)
+          raise ArgumentError.new "Illegal name: \"#{name}\" for service." if name.nil?
+          unless check.nil? or check.is_a?(Consul::Model::HealthCheck)
+            raise TypeError.new "Illegal Check type: #{check}.  Expecting Consul::Model::HealthCheck"
+          end
+          if check.nil?
+            Consul::Model::Service.new(name: name)
+          else # There is a health check to register
+            Consul::Model::Service.new(name: name, check: check)
+          end
+        end
+
+        # Public: Creates a health check meant to be used when registering a service.
+        #
+        #
+        #
+        # Returns: Consul::Model::HealthCheck instance that represents a script
+        def self.script_health_check(script, interval)
+          Consul::Model::HealthCheck.new(script: script, interval: interval)
+        end
+
+        def self.http_health_check(http, interval)
+          Consul::Model::HealthCheck.new(http: http, interval: interval)
+        end
+
+        def self.ttl_health_check(ttl)
+          Consul::Model::HealthCheck.new(ttl: ttl)
+        end
+      end
+
+      private
+
+      # Private: Updates the check with the argument status.
+      def update_check_status(check, status)
+        unless check.instance_of?(Consul::Model::HealthCheck) and check.respond_to?(:to_str)
+          check = check(check.to_str)
+        end
+        return false if check.nil?
+        raise ArgumentError.new "Illegal Status #{status}" unless status == 'pass' or status == 'warn' or status == 'fail'
+        resp = _get build_check_url("#{status}/#{check.check_id}")
+        resp.code == 200
+      end
+
+      # Private: Register a consul entity with the existing agent but attempts and exponentially increasing interval if
+      # fails.
+      #
+      # url - The url to make the register request through.
+      # entity - JSON representation of the entity
+      # iteration - The current attempt iteration
+      # threshold - Number of attempts to try
+      #
+      def register_with_backoff(url, entity, iteration, threshold)
+        # Checking a greater iteration just to be on the safe side.
+        unless iteration > threshold or threshold <= 0 or iteration < 0
+          sleep((1.0/2.0*(2.0**iteration - 1.0)).ceil) if iteration > 0
+          success, _ = _put(url, entity.to_json)
+          unless success # Unless we successfully registered.
+            if threshold == iteration
+              @logger.error("Unable to complete registration after #{threshold + 1} attempts")
+            else
+              # Attempt to register again using the exponential backoff.
+              @logger.warn("Unable to complete registration after #{iteration + 1} attempts, Retrying up to #{threshold+1} attempts")
+              register_with_backoff(url, entity, iteration + 1, threshold)
+            end
+          end
+          return true
+        end
+        false
+      end
+
+      def build_service_url(suffix)
+        build_agent_url("service/#{suffix}")
+      end
+
+      def build_check_url(suffix)
+        build_agent_url("check/#{suffix}")
+      end
+
+      # status : "pass", "warn", or "fail"
+      def build_check_status_url(check_id, status)
+        build_check_url("#{status}/#{check_id}")
+      end
+
+      # Returns host:port/v1/agent/suffix
+      def build_agent_url(suffix)
+        "#{base_versioned_url}/agent/#{suffix}"
+      end
+
+    end
+  end
+end