consul-client 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: c1729a5c12181f89e6921f85d96d2df356466a7d
+  data.tar.gz: b52bd63b9e2befc9b9a4d24422195973577362c5
+SHA512:
+  metadata.gz: 0aa261a9c0055617e26a30af166c99b07da4cef43491f1057a4ef597305ef02041af5f7e073f601b3b4f635df9c5011750496cf7a5bc7598d0b83bb55fd2eec1
+  data.tar.gz: 8201a743e89f3e39a475f41ee1295611b8e6502ce0460c37b939e241c57856783cb09ecc260ee02661274602f27fc3dc2c6e23532f6cc7c7dfdd570906a67240

data/README.md

@@ -0,0 +1,29 @@
+Consul Client
+=============
+
+Ruby client library for Consul HTTP API, providing both a thin wrapper around
+the raw API and higher level behaviours for operating in a Consul environment.
+
+_This library is experimental! Be sure to thoroughly test and code review
+before using for anything real._
+
+Usage
+-----
+
+Simple API usage:
+
+```ruby
+require 'consul/client'
+
+client = Consul::Client.v1.http
+client.get("/agent/self")
+```
+
+See `example` directory for more:
+
+* `puts_service.rb` is a minimum server that demostrates coordinated shutdown.
+* `http_service.rb` builds on top of webrick for an auto-updating server with
+  coordinated restart.
+
+A `Vagrantfile` is provided that makes three
+Consul nodes, which is handy for playing around.

data/consul-client.gemspec

@@ -0,0 +1,27 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Xavier Shay"]
+  gem.email         = ["contact@xaviershay.com"]
+  gem.description   =
+    %q{Ruby client library for Consul HTTP API.}
+  gem.summary       = %q{
+    Ruby client library for Consul HTTP API, providing both a thin wrapper
+    around the raw API and higher level behaviours for operating in a Consul
+    environment.
+  }
+  gem.homepage      = "http://github.com/xaviershay/consul-client"
+
+  gem.executables   = []
+  gem.required_ruby_version = '>= 2.1.2'
+  gem.files         = Dir.glob("{spec,lib}/**/*.rb") + %w(
+                        README.md
+                        consul-client.gemspec
+                      )
+  gem.test_files    = Dir.glob("spec/**/*.rb")
+  gem.name          = "consul-client"
+  gem.require_paths = ["lib"]
+  gem.license       = "Apache 2.0"
+  gem.version       = '0.1.0'
+  gem.has_rdoc      = false
+end

data/lib/consul/client.rb

@@ -0,0 +1,61 @@
+require 'consul/client/local_service'
+require 'consul/client/service'
+require 'consul/client/http'
+
+require 'logger'
+
+# Top-level Consul name space.
+module Consul
+  # Top-level client name space. All public entry points are via this module.
+  module Client
+    # Default logger that silences all diagnostic output.
+    NULL_LOGGER = Logger.new("/dev/null")
+
+    # Provides builders that support V1 of the Consul HTTP API.
+    # @return [Consul::Client::V1]
+    def self.v1
+      V1.new
+    end
+
+    # Do not instantiate this class directly.
+    #
+    # @see Consul::Client.v1
+    class V1
+      # Returns high-level local service utility functions.
+      #
+      # @param name [String] name of the service. Must match service ID in
+      #                        Consul.
+      # @param http [Consul::Client::HTTP] http client to use.
+      # @param logger [Logger] logger for diagnostic information.
+      # @return [Consul::Client::LocalService]
+      # @example
+      #     local = Consul::Client.v1.local_service('web')
+      #     local.coordinated_shutdown! { $healthy = false }
+      def local_service(name, http: http, logger: http.logger)
+        LocalService.new(name, http: http, logger: logger)
+      end
+
+      # Returns high-level service utility functions.
+      #
+      # @example
+      #     service = Consul::Client.v1.service('web')
+      #     service.lock('leader') { puts "I am the cluster leader!" }
+      def service(*args)
+        Service.new(*args)
+      end
+
+      # Returns a thin wrapper around the Consult HTTP API.
+      #
+      # @param host [String] host of Consul agent.
+      # @param port [Integer] port to connect to Consul agent.
+      # @param logger [Logger] logger for diagnostic information.
+      # @return [Consul::Client::HTTP]
+      # @example
+      #     http = Consul::Client.v1.http(logger: Logger.new($stdout))
+      #     puts http.get("/get/self")["Member"]["Name"]
+      def http(host: "localhost", port: 8500, logger: NULL_LOGGER)
+        HTTP.new(*args)
+      end
+    end
+  end
+end

data/lib/consul/client/http.rb

@@ -0,0 +1,125 @@
+require 'net/http'
+require 'json'
+require 'logger'
+
+module Consul
+  module Client
+    # Any non-successful response from Consul will result in this error being
+    # thrown.
+    ResponseException = Class.new(StandardError)
+
+    # Low-level wrapper around consul HTTP api. Do not instantiate this class
+    # directly, instead use the appropriate factory methods.
+    #
+    # @see Consul::Client::V1#http
+    class HTTP
+      # @api private
+      def initialize(host:, port:, logger:)
+        @host   = host
+        @port   = port
+        @logger = logger
+      end
+
+      # Get JSON data from an endpoint.
+      #
+      # @param request_uri [String] portion of the HTTP path after the version
+      #                             base, such as +/agent/self+.
+      # @return [Object] parsed JSON response
+      # @raise [ResponseException] if non-200 response is received.
+      def get(request_uri)
+        url = base_uri + request_uri
+        logger.debug("GET #{url}")
+
+        uri = URI.parse(url)
+
+        response = http_request(:get, uri)
+
+        parse_body(response)
+      end
+
+      # Watch an endpoint until the value returned causes the block to evaluate
+      # +false+.
+      #
+      # @param request_uri [String] portion of the HTTP path after the version
+      #                             base, such as +/agent/self+.
+      # @return [Object] parsed JSON response
+      # @raise [ResponseException] if non-200 response is received.
+      # @example blocks until there are at least 3 passing nodes for the web service.
+      #     http.get_while("/health/service/web?passing") do |data|
+      #       data.size <= 2
+      #     end
+      def get_while(request_uri, &block)
+        url = base_uri + request_uri
+        index = 0
+        json = nil
+
+        check = ->{
+          uri = URI.parse(url)
+          uri.query ||= ""
+          uri.query += "&index=#{index}&wait=10s"
+          logger.debug("GET #{uri}")
+
+          response = http_request(:get, uri)
+          index = response['x-consul-index'].to_i
+
+          json = parse_body(response)
+
+          block.(json)
+        }
+
+        while check.()
+        end
+
+        json
+      end
+
+      # Put request to an endpoint. If data is provided, it is JSON encoded and
+      # sent in the request body.
+      # @param request_uri [String] portion of the HTTP path after the version
+      #                             base, such as +/agent/self+.
+      # @param data        [Object] body for request
+      # @return [Object] parsed JSON response
+      # @raise [ResponseException] if non-200 response is received.
+      def put(request_uri, data = nil)
+        url = base_uri + request_uri
+        logger.debug("PUT #{url}")
+
+        uri = URI.parse(url)
+
+        response = http_request(:put, uri, data)
+
+        parse_body(response)
+      end
+
+      attr_accessor :logger
+
+      protected
+
+      def base_uri
+        "http://#{@host}:#{@port}/v1"
+      end
+
+      def parse_body(response)
+        JSON.parse("[#{response.body}]")[0]
+      end
+
+      def http_request(method, uri, data = nil)
+        method = {
+          get: Net::HTTP::Get,
+          put: Net::HTTP::Put,
+        }.fetch(method)
+
+        http     = Net::HTTP.new(uri.host, uri.port)
+        request  = method.new(uri.request_uri)
+        request.body = data.to_json if data
+        response = http.request(request)
+
+        if response.code.to_i >= 400
+          raise ResponseException, "#{response.code} on #{uri}"
+        end
+
+        response
+      end
+    end
+  end
+end

data/lib/consul/client/local_service.rb

@@ -0,0 +1,65 @@
+module Consul
+  module Client
+    # Provides operations on services running on the local machine. Do not
+    # instantiate this class directly, instead use the appropriate factory
+    # methods.
+    #
+    # @see Consul::Client::V1#local_service
+    class LocalService
+      # @api private
+      def initialize(name, http:, logger:)
+        @name   = name
+        @consul = consul
+        consul.logger = logger
+      end
+
+      # Coordinate the shutdown of this node with the rest of the cluster so
+      # that a minimum number of nodes is always healthy. Blocks until a
+      # shutdown lock has been obtained and the cluster is healthy before
+      # yielding, in which callers should mark the service unhealthy (but
+      # continue to accept traffic). After the unhealthy state of the service
+      # has propagated and `grace_period` seconds has passed, this method
+      # returns and the caller should stop accepting new connections, finish
+      # existing work, then terminate.
+      #
+      # @param min_nodes [Integer] minimum require nodes for cluster to be
+      #          considered healthy.
+      # @param grace_period [Integer] number of seconds to sleep after service
+      #          has been marked unhealthy in the cluster. This is important so
+      #          that any in-flight requests are still able to be handled.
+      def coordinated_shutdown!(min_nodes: 1, grace_period: 3, &block)
+        cluster = Consul::Client.v1.service(name, consul: consul)
+
+        cluster.lock("shutdown") do
+          cluster.wait_until_healthy!(min_nodes: min_nodes)
+          block.()
+          wait_until_unhealthy!
+
+          # Release lock here and perform shutdown in our own time, since we
+          # know the consistent view of nodes does not include this one and so
+          # is safe for other nodes to try restarting.
+        end
+
+        # Grace period for any in-flight connections on their way already
+        # before health check failure propagated.
+        #
+        # No way to avoid a sleep here.
+        Kernel.sleep grace_period
+      end
+
+      # Waits until the propagated health of this node is unhealthy so it is
+      # not receiving new traffic.
+      def wait_until_unhealthy!
+        agent = consul.get("/agent/self")["Member"]["Name"]
+        consul.get_while("/health/node/#{agent}") do |data|
+          status = data.detect {|x| x["CheckID"] == "service:#{name}" }["Status"]
+          status == 'passing'
+        end
+      end
+
+      private
+
+      attr_reader :name, :consul
+    end
+  end
+end

data/lib/consul/client/service.rb

@@ -0,0 +1,68 @@
+module Consul
+  module Client
+    # Provides cluster coordination features. Do not instantiate this class
+    # directly, instead use the appropriate factory methods.
+    #
+    # @see Consul::Client::V1#service
+    class Service
+      # @api private
+      def initialize(name, consul: Consul::Client.v1)
+        @name   = name
+        @consul = consul
+      end
+
+      # Creates a session tied to this cluster, then blocks indefinitely until
+      # the requested lock can be acquired, then yields. The lock is released
+      # and the session destroyed when the block completes.
+      #
+      # @param key [String] the name of the lock to acquire. This is namespace
+      #           under the service name and stored directly in the KV store,
+      #           so make sure it does not conflict with other names. For
+      #           instance, the leader lock for the +web+ service would be
+      #           stored at +/kv/web/leader+.
+      def lock(key, &block)
+        session = consul.put("/session/create",
+          LockDelay: '5s',
+          Checks:    ["service:#{name}", "serfHealth"]
+        )["ID"]
+        loop do
+          locked = consul.put("/kv/#{name}/#{key}?acquire=#{session}")
+
+          if locked
+            begin
+              block.call
+            ensure
+              consul.put("/kv/#{name}/#{key}?release=#{session}")
+              consul.put("/session/destroy/#{session}")
+            end
+            return
+          else
+            consul.get_while("/kv/#{name}/#{key}") do |body|
+              body[0]["Session"]
+            end
+          end
+          # TODO: Figure out why long poll doesn't work.
+          # https://gist.github.com/xaviershay/30128b968bde0e2d3e0b/edit
+          sleep 2
+        end
+      end
+
+      # Block indefinitely until the cluster is healthy.
+      #
+      # @param min_nodes [Integer] minimum number of nodes required to be
+      #           healthy for the cluster as a whole to be considered healthy.
+      #           This method will block until there is at least one more than
+      #           this number, assuming that the caller is about to terminate.
+      def wait_until_healthy!(min_nodes: 1)
+        consul.get_while("/health/service/#{name}?passing") do |data|
+          data.size <= min_nodes
+        end
+      end
+
+      private
+
+      attr_reader :name
+      attr_reader :consul
+    end
+  end
+end

metadata

@@ -0,0 +1,52 @@
+--- !ruby/object:Gem::Specification
+name: consul-client
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Xavier Shay
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-08-17 00:00:00.000000000 Z
+dependencies: []
+description: Ruby client library for Consul HTTP API.
+email:
+- contact@xaviershay.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- consul-client.gemspec
+- lib/consul/client.rb
+- lib/consul/client/http.rb
+- lib/consul/client/local_service.rb
+- lib/consul/client/service.rb
+homepage: http://github.com/xaviershay/consul-client
+licenses:
+- Apache 2.0
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.1.2
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: Ruby client library for Consul HTTP API, providing both a thin wrapper around
+  the raw API and higher level behaviours for operating in a Consul environment.
+test_files: []
+has_rdoc: false