consulkit 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ed420f460a02053a0cdb911554388b96d9400118b3fc9fdad1a2534a3dbf9712
+  data.tar.gz: 3db9bb6b418452fa9501a9c68aa4e47b39d4007a18a0f08612c387841189316d
+SHA512:
+  metadata.gz: ed6a2dbf2ba8ada0961d3c7491c8501478f50742910f7f588c0adc0291898fa96f47ff7ec66d2d699b1e3d3fe47b1c9914fe2be08674da6b8ae84fba686ce075
+  data.tar.gz: 909cb251f11788907a6988441a4dd95c86678ccd7a53a46ce85e4946847e92535d257a469661b92408396d97adef3a2b6cd67c2b4c111caa898ff977949efe08

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,27 @@
+AllCops:
+  TargetRubyVersion: 2.6
+
+Metrics/MethodLength:
+  Max: 15
+
+Layout/LineLength:
+  Max: 120
+
+Metrics/BlockLength:
+  AllowedMethods: ['describe']
+
+Layout/EmptyLinesAroundClassBody:
+  EnforcedStyle: empty_lines_except_namespace
+
+Layout/EmptyLinesAroundModuleBody:
+  EnforcedStyle: empty_lines_except_namespace
+
+Layout/HashAlignment:
+  EnforcedHashRocketStyle: table
+  EnforcedColonStyle: table
+
+Style/TrailingCommaInHashLiteral:
+  EnforcedStyleForMultiline: consistent_comma
+
+Style/TrailingCommaInArrayLiteral:
+  EnforcedStyleForMultiline: consistent_comma

data/Gemfile

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec
+
+gem 'bundler', '~> 2.3'
+gem 'rake', '~> 13.0'
+gem 'rubocop', '~> 1.21'
+
+group :test do
+  gem 'rspec', '~> 3.0'
+  gem 'vcr'
+  gem 'webmock'
+end
+
+group :development do
+  gem 'yard'
+end

data/Gemfile.lock

@@ -0,0 +1,88 @@
+PATH
+  remote: .
+  specs:
+    consulkit (0.1.0)
+      faraday (~> 2.7)
+      faraday-retry (~> 2.2)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.8.4)
+      public_suffix (>= 2.0.2, < 6.0)
+    ast (2.4.2)
+    crack (0.4.5)
+      rexml
+    diff-lcs (1.5.0)
+    faraday (2.7.8)
+      faraday-net_http (>= 2.0, < 3.1)
+      ruby2_keywords (>= 0.0.4)
+    faraday-net_http (3.0.2)
+    faraday-retry (2.2.0)
+      faraday (~> 2.0)
+    hashdiff (1.0.1)
+    json (2.6.3)
+    language_server-protocol (3.17.0.3)
+    parallel (1.23.0)
+    parser (3.2.2.3)
+      ast (~> 2.4.1)
+      racc
+    public_suffix (5.0.1)
+    racc (1.7.1)
+    rainbow (3.1.1)
+    rake (13.0.6)
+    regexp_parser (2.8.1)
+    rexml (3.2.5)
+    rspec (3.12.0)
+      rspec-core (~> 3.12.0)
+      rspec-expectations (~> 3.12.0)
+      rspec-mocks (~> 3.12.0)
+    rspec-core (3.12.2)
+      rspec-support (~> 3.12.0)
+    rspec-expectations (3.12.3)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.12.0)
+    rspec-mocks (3.12.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.12.0)
+    rspec-support (3.12.1)
+    rubocop (1.53.1)
+      json (~> 2.3)
+      language_server-protocol (>= 3.17.0)
+      parallel (~> 1.10)
+      parser (>= 3.2.2.3)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.8, < 3.0)
+      rexml (>= 3.2.5, < 4.0)
+      rubocop-ast (>= 1.28.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 3.0)
+    rubocop-ast (1.29.0)
+      parser (>= 3.2.1.0)
+    ruby-progressbar (1.13.0)
+    ruby2_keywords (0.0.5)
+    unicode-display_width (2.4.2)
+    vcr (6.2.0)
+    webmock (3.18.1)
+      addressable (>= 2.8.0)
+      crack (>= 0.3.2)
+      hashdiff (>= 0.4.0, < 2.0.0)
+    yard (0.9.34)
+
+PLATFORMS
+  arm64-darwin-22
+  universal-darwin-22
+  x86_64-linux
+
+DEPENDENCIES
+  bundler (~> 2.3)
+  consulkit!
+  rake (~> 13.0)
+  rspec (~> 3.0)
+  rubocop (~> 1.21)
+  vcr
+  webmock
+  yard
+
+BUNDLED WITH
+   2.4.13

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2023 Etsy
+
+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,60 @@
+# consulkit
+
+Ruby API for interacting with HashiCorp's [Consul](https://www.consul.io/), heavily inspired by GitHub's [Octokit](https://github.com/octokit/octokit.rb).
+
+## Installation
+
+```
+gem "consulkit", :git => "git://github.com/ericnorris/consulkit.git"
+```
+
+## Usage
+
+Get a client using the default options:
+
+```ruby
+client = Consulkit::Client.new
+```
+
+...or provide customized options:
+
+```ruby
+client = Consulkit.Client.new(http_addr: "https://consul.example.com", http_token: "token")
+```
+
+### KV Store
+
+Reading keys:
+
+```ruby
+# Read a single key
+client.kv_read_single("foo")
+# => {"LockIndex"=>0, "Key"=>"foo", "Flags"=>1234, "Value"=>"bar", "CreateIndex"=>3532, "ModifyIndex"=>3914}
+
+# Read key recursively
+client.kv_read_recursive("foo")
+# => [{"LockIndex"=>0, "Key"=>"foo", "Flags"=>1234, "Value"=>"bar", "CreateIndex"=>3532, "ModifyIndex"=>3914}, ...]
+
+# Specify your own query parameters
+client.kv_read("foo", raw: true)
+# => "bar"
+```
+
+Writing keys:
+
+```ruby
+# Write a key
+client.kv_write("foo", "bar", flags: 1234)
+# => true
+
+# Write a key if it doesn't exist
+client.kv_write_cas("foo", "bar", 0)
+=> false
+
+> client.kv_write_cas("bar", "baz", 0)
+=> true
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/Rakefile

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]
+
+namespace :doc do
+  require 'yard'
+
+  YARD::Rake::YardocTask.new do |task|
+    task.files   = ['README.md', 'LICENSE.md', 'lib/**/*.rb']
+    task.options = [
+      '--output-dir', 'doc/yard',
+      '--markup', 'markdown',
+    ]
+  end
+end

data/lib/consulkit/client/kv.rb

@@ -0,0 +1,218 @@
+# frozen_string_literal: true
+
+require 'base64'
+
+module Consulkit
+  class Client
+    # Methods for accessing Consul's KV store.
+    module KV
+
+      # Reads the specified key, raising an exception if not found. The value of the keys in the response are
+      # automatically base64 decoded, if applicable.
+      #
+      # @see https://developer.hashicorp.com/consul/api-docs/kv#read-key
+      #
+      # @param key [String] the key to read.
+      # @option query_params [Hash] optional query parameters.
+      # @option query_params [Boolean] :recurse
+      # @option query_params [Boolean] :raw
+      # @option query_params [Boolean] :keys
+      # @option query_params [String] :separator
+      #
+      # @raise [Consulkit::Error::NotFound] if the key does not exist.
+      #
+      # @yield [Faraday::Response] The response from the underlying Faraday library.
+      #
+      # @return [Array<Hash>]
+      def kv_read!(key, query_params = {})
+        response = get("/v1/kv/#{key}", query_params)
+
+        if block_given?
+          yield response
+        else
+          kv_decode_response_body(response.body)
+        end
+      end
+
+      # Reads the specified key. The value of the keys in the response are automatically base64 decoded, if applicable.
+      #
+      # @see https://developer.hashicorp.com/consul/api-docs/kv#read-key
+      #
+      # @param key [String] the key to read.
+      # @option query_params [Hash] optional query parameters.
+      # @option query_params [Boolean] :recurse
+      # @option query_params [Boolean] :raw
+      # @option query_params [Boolean] :keys
+      # @option query_params [String] :separator
+      #
+      # @yield [Faraday::Response] The response from the underlying Faraday library.
+      #
+      # @return [Array<Hash>]
+      def kv_read(key, query_params = {}, &block)
+        kv_read!(key, query_params, &block)
+      rescue Consulkit::Error::NotFound
+        []
+      end
+
+      # Reads the specified key, expecting a single KV entry. The value of the key is automatically base64 decoded.
+      #
+      # @param key [String] the key to read.
+      #
+      # @return [Hash, nil]
+      def kv_read_single(key)
+        kv_read!(key).first
+      rescue Consulkit::Error::NotFound
+        nil
+      end
+
+      # Reads the specified key, and returns the X-Consul-Index value. The value of the keys in the response are
+      # automatically base64 decoded, if applicable.
+      #
+      # @see kv_read
+      #
+      # @param key [String] the key to read.
+      # @param query_params [Hash] optional query parameters.
+      #
+      # @return [Array<(Integer, Array<Hash>)>]
+      def kv_read_with_index(key, query_params = {})
+        kv_read!(key, **query_params) do |response|
+          [response.headers['X-Consul-Index'], kv_decode_response_body(response.body)]
+        end
+      rescue Consulkit::Error::NotFound => e
+        [e.response_headers['X-Consul-Index'], []]
+      end
+
+      # Reads the specified key, then yields the result of a blocking query for that key. The value of the keys in the
+      # response are automatically base64 decoded, if applicable. Return false from the block to end the loop.
+      #
+      # @see kv_read
+      #
+      # @param key [String] the key to read.
+      # @param query_params [Hash] optional query parameters.
+      #
+      # @yield [changed, result]
+      # @yieldparam changed [Boolean] true if the consul index has changed since the last query.
+      # @yieldparam result [Array<Hash>] the current result of the consul query.
+      def kv_read_blocking(key, wait = nil, query_params = {})
+        last_index, = kv_read_with_index(key, query_params)
+
+        loop do
+          new_index, result = kv_read_with_index(key, **query_params, wait: wait, index: last_index)
+
+          return unless yield(new_index != last_index, result)
+        end
+      end
+
+      # Reads the specified key recursively. The value of the keys in the response are automatically base64 decoded, if
+      # applicable.
+      #
+      # @see https://developer.hashicorp.com/consul/api-docs/kv#read-key
+      #
+      # @param key [String] the key to read.
+      # @param query_params [Hash] optional query parameters.
+      #
+      # @return [<Hash>]
+      def kv_read_recursive(key, query_params = {})
+        kv_read(key, **query_params, recurse: true)
+      end
+
+      # Reads the specified key recursively, returning a hash where each key is indexed by its key name. The value of
+      # the keys in the response are automatically base64 decoded, if applicable.
+      #
+      # @param key [String] the key to read.
+      #
+      # @return [Hash<String, Hash>]
+      def kv_read_recursive_as_hash(key)
+        kv_read_recursive(key).to_h do |entry|
+          [entry['Key'], entry]
+        end
+      end
+
+      # Creates or updates the specified key.
+      #
+      # @see https://developer.hashicorp.com/consul/api-docs/kv#create-update-key
+      # @see kv_write_cas
+      # @see kv_acquire_lock
+      # @see kv_release_lock
+      #
+      # @param key [String] the key to create or update.
+      # @option query_params [Hash] optional query parameters.
+      # @option query_params [Integer] :flags
+      # @option query_params [Integer] :cas
+      # @option query_params [String] :acquire
+      # @option query_params [String] :release
+      #
+      # @yield [Faraday::Response] The response from the underlying Faraday library.
+      #
+      # @return [Boolean]
+      def kv_write(key, value, query_params = {})
+        response = put("/v1/kv/#{key}", value, query_params)
+
+        if block_given?
+          yield response
+        else
+          response.body == true
+        end
+      end
+
+      # Atomically creates or updates the specified key, if and only if the modify index matches.
+      #
+      # @param key [String] the key to create or update.
+      # @param query_params [Hash] optional query parameters.
+      #
+      # return [Boolean]
+      def kv_write_cas(key, value, modify_index, query_params = {})
+        kv_write(key, value, **query_params, cas: modify_index)
+      end
+
+      # Atomically creates or updates the specified key by acquiring a lock with the session ID.
+      #
+      # @param key [String] the key to create or update.
+      # @param query_params [Hash] optional query parameters.
+      #
+      # return [Boolean]
+      def kv_acquire_lock(key, session_id, value = nil, query_params = {})
+        kv_write(key, value, **query_params, acquire: session_id)
+      end
+
+      # Atomically updates the specified key while releasing the associated lock.
+      #
+      # @param key [String] the key to update.
+      # @param query_params [Hash] optional query parameters.
+      #
+      # return [Boolean]
+      def kv_release_lock(key, session_id, value = nil, query_params = {})
+        kv_write(key, value, **query_params, release: session_id)
+      end
+
+      # Deletes the specified key.
+      #
+      # @param key [String] the key to delete.
+      # @param query_params [Hash] optional query parameters.
+      #
+      # return [Boolean]
+      def kv_delete(key, query_params = {})
+        delete("/v1/kv/#{key}", query_params).body == true
+      end
+
+      # Automatically base64 decodes the 'Value' of each KV entry in the body, if the body looks like a Consul KV entry
+      # list response.
+      #
+      # @param body [Object] the response body to decode.
+      #
+      # @return [Object, Array<Hash>] the body parameter, but with 'Value' base64 decoded, or the body parameter
+      # as-is.
+      def kv_decode_response_body(body)
+        return body unless body.is_a?(Array)
+        return body unless body.first.is_a?(Hash) && (body.first.key? 'Value')
+
+        body.each do |kv_entry|
+          next if kv_entry['Value'].nil?
+
+          kv_entry['Value'] = Base64.decode64(kv_entry['Value'])
+        end
+      end
+
+    end
+  end
+end

data/lib/consulkit/client/session.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Consulkit
+  class Client
+    # Methods for creating, deleting, and querying sessions.
+    module Session
+
+      # Creates a session.
+      #
+      # @see https://developer.hashicorp.com/consul/api-docs/session#create-session
+      #
+      # @example Create a session with a 60 second TTL and the 'delete' behavior.
+      #   session_create(ttl: "60s", behavior: 'delete')
+      #
+      # @param session_opts [Hash] options to create the session with.
+      # @option session_opts [String] :lock_delay
+      # @option session_opts [String] :node
+      # @option session_opts [String] :name
+      # @option session_opts [Array<String>] :node_checks
+      # @option session_opts [Array<Hash>] :service_checks
+      # @option session_opts [String] :behavior
+      # @option session_opts [String] :ttl
+      #
+      # @return String the ID of the created session.
+      def session_create(session_opts = {})
+        put('/v1/session/create', camel_case_keys(session_opts)).body['ID']
+      end
+
+      # Deletes a session.
+      #
+      # @param session_id [String] the ID of the session to delete.
+      #
+      # @return [Boolean]
+      def session_delete(session_id)
+        delete("/v1/session/destroy/#{session_id}").body == true
+      end
+
+      # Reads a session.
+      #
+      # @param session_id [String] the ID of the session to read.
+      #
+      # @return [Boolean]
+      def session_read(session_id)
+        get("/v1/session/info/#{session_id}").body
+      end
+
+      # Renews a session.
+      #
+      # @param session_id [String] the ID of the session to renew.
+      #
+      # @return [Hash]
+      def session_renew(session_id)
+        put("/v1/session/renew/#{session_id}").body
+      end
+
+    end
+  end
+end

data/lib/consulkit/client.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require 'consulkit/configurable'
+require 'consulkit/client/kv'
+require 'consulkit/client/session'
+
+module Consulkit
+  # Client for the Consul API.
+  class Client
+
+    include Consulkit::Configurable
+    include Consulkit::Client::KV
+    include Consulkit::Client::Session
+
+    def initialize(options = {})
+      CONFIGURABLE_KEYS.each do |key|
+        value = options[key].nil? ? Consulkit.instance_variable_get("@#{key}") : options[key]
+
+        instance_variable_set("@#{key}", value)
+      end
+    end
+
+    def delete(url, query_params = {})
+      request(:delete, url, query_params, nil)
+    end
+
+    def get(url, query_params = {})
+      request(:get, url, query_params, nil)
+    end
+
+    def post(url, body = nil, query_params = {})
+      request(:post, url, query_params, body)
+    end
+
+    def put(url, body = nil, query_params = {})
+      request(:put, url, query_params, body)
+    end
+
+    def request(method, url, query_params, body)
+      http.run_request(method, url, body, nil) do |request|
+        request.params.update(query_params) if query_params
+      end
+    end
+
+    def http
+      opts = @connection_options
+
+      opts['builder'] = @middleware.dup if middleware
+
+      opts['request'] ||= {}
+      opts['request']['params_encoder'] = Faraday::FlatParamsEncoder
+
+      opts['headers'] ||= {}
+      opts['headers']['Authorization'] = "Bearer #{http_token}" if @http_token
+
+      @http ||= Faraday.new(http_addr, opts)
+    end
+
+    def camel_case_keys(hash)
+      hash.transform_keys { |k| k.to_s.split('_').collect(&:capitalize).join }
+    end
+
+  end
+end

data/lib/consulkit/configurable.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Consulkit
+  # Configuration options for the {Consulkit} singleton and individual {Client} instances.
+  module Configurable
+
+    # [String] the HTTP(s) address to use to connect to Consul
+    attr_accessor :http_addr
+
+    # [String] the ACL token used for authentication
+    attr_writer :http_token
+
+    # [Hash] Faraday connection options
+    attr_accessor :connection_options
+
+    # [Faraday::RackBuilder] middleware for Faraday
+    attr_accessor :middleware
+
+    CONFIGURABLE_KEYS = %i[
+      connection_options
+      http_addr
+      http_token
+      middleware
+    ].freeze
+
+    def setup!
+      CONFIGURABLE_KEYS.each do |key|
+        instance_variable_set(:"@#{key}", Consulkit::Defaults.send(key))
+      end
+
+      self
+    end
+
+    def options
+      CONFIGURABLE_KEYS.to_h { |key| [key, instance_variable_get("@#{key}")] }
+    end
+
+  end
+end

data/lib/consulkit/defaults.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'faraday/retry'
+require 'consulkit/middleware/raise_error'
+
+module Consulkit
+  # Default configuration options for the {Consulkit} singleton and individual {Client} instances.
+  module Defaults
+
+    HTTP_ADDR = 'http://localhost:8500'
+
+    HTTP_TOKEN = nil
+
+    MIDDLEWARE = Faraday::RackBuilder.new do |builder|
+      retry_exceptions = Faraday::Retry::Middleware::DEFAULT_EXCEPTIONS + [Consulkit::Error::Server]
+
+      builder.use(Faraday::Request::Json)
+      builder.use(Faraday::Response::Json)
+      builder.use(Faraday::Retry::Middleware, exceptions: retry_exceptions)
+      builder.use(Consulkit::Middleware::RaiseError)
+
+      builder.adapter Faraday.default_adapter
+    end
+
+    class << self
+
+      def connection_options
+        {}
+      end
+
+      def http_addr
+        ENV.fetch('CONSUL_HTTP_ADDR', HTTP_ADDR)
+      end
+
+      def http_token
+        ENV.fetch('CONSUL_HTTP_TOKEN', HTTP_TOKEN)
+      end
+
+      def middleware
+        MIDDLEWARE
+      end
+
+    end
+
+  end
+end

data/lib/consulkit/error.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Consulkit
+  # An error returned from the Consul API.
+  class Error < StandardError
+
+    def initialize(response)
+      @response = response
+
+      super(error_message)
+    end
+
+    # Returns the appropriate Consulkit::Error subclass based on the status and
+    # response message, or nil if the response is not an error.
+    #
+    # @param [Hash] response the HTTP response
+    #
+    # @return Consulkit::Error
+    def self.from_response(response)
+      return unless (error_class = error_class_for(response))
+
+      error_class.new(response)
+    end
+
+    def response_status
+      @response.status
+    end
+
+    def response_headers
+      @response.response_headers
+    end
+
+    def response_body
+      @response.response_body
+    end
+
+    private
+
+    def error_message
+      @response.instance_eval do
+        "#{method.to_s.upcase} #{url}: #{status} #{reason_phrase} - #{body}"
+      end
+    end
+
+    class Client < Error; end
+
+    class BadRequest < Client; end
+
+    class Forbidden < Client; end
+
+    class ACLNotFound < Forbidden; end
+
+    class NotFound < Client; end
+
+    class Server < Error; end
+
+    # @private
+    private_class_method def self.error_class_for(response)
+      status = response[:status].to_i
+      body   = response[:body].to_s
+
+      case status
+      when 400 then BadRequest
+      when 403 then error_class_for_http403(body)
+      when 404 then NotFound
+
+      when 400..499 then Client
+      when 500..599 then Server
+      end
+    end
+
+    # @private
+    private_class_method def self.error_class_for_http403(body)
+      case body
+      when /acl not found/i then ACLNotFound
+      else Forbidden
+      end
+    end
+
+  end
+end

data/lib/consulkit/middleware/raise_error.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require 'consulkit/error'
+
+module Consulkit
+  module Middleware
+    # This class raises a Consulkit-flavored exception based on the HTTP status codes returned by
+    # the API.
+    class RaiseError < Faraday::Middleware
+
+      def on_complete(response)
+        return unless (error = Consulkit::Error.from_response(response))
+
+        raise error
+      end
+
+    end
+  end
+end

data/lib/consulkit/semaphore_coordinator.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+module Consulkit
+  # Coordinates the usage of a consul key as distributed semaphore, following the algorithm described by Hashicorp
+  # [here](https://developer.hashicorp.com/consul/tutorials/developer-configuration/distributed-semaphore).
+  class SemaphoreCoordinator
+
+    # Initializes the coordinater using the given Consulkit client and key prefix.
+    #
+    # @param client [Consulkit::Client] the client to use.
+    # @param key_prefix [String] the key_prefix to use.
+    # @param logger [Logger] if non-nil, will log during semaphore operations.
+    def initialize(client, key_prefix, logger = nil)
+      @client     = client
+      @key_prefix = key_prefix
+      @logger     = logger || Logger.new(IO::NULL)
+    end
+
+    # Continually attempts to acquire the semaphore until successful using exponential backoff.
+    #
+    # @see Consulkit::Client.session_create
+    #
+    # @param session_id [String] the ID of a consul session to associate with the semaphore.
+    # @param limit [Integer] the maximum number of holders for the semaphore.
+    # @param backoff_cap [Float] the maximum interval to wait between attempts.
+    # @param timeout [Float] the maximum number of seconds to sleep before giving up; nil means try forever.
+    #
+    # @return [Boolean]
+    def acquire(session_id, limit, backoff_cap: 10.0, timeout: nil)
+      exponential_backoff(backoff_cap, timeout) do
+        @logger.info(%(calling try_acquire("#{session_id}", #{limit})))
+
+        try_acquire(session_id, limit)
+      end
+    end
+
+    # Continually attempts to release the semaphore until successful using exponential backoff.
+    #
+    # @param session_id [String] the ID of a consul session to associate with the semaphore.
+    # @param backoff_cap [Float] the maximum interval to wait between attempts.
+    # @param timeout [Float] the maximum number of seconds to sleep before giving up; nil means try forever.
+    #
+    # @return [Boolean]
+    def release(session_id, backoff_cap: 10.0, timeout: nil)
+      exponential_backoff(backoff_cap, timeout) do
+        @logger.info(%(calling try_release("#{session_id}")))
+
+        try_release(session_id)
+      end
+    end
+
+    # Attempts to acquire the semaphore, allowing up to the given limit of holders.
+    #
+    # @see Consulkit::Client.session_create
+    #
+    # @param session_id [String] the ID of a consul session to associate with the semaphore.
+    # @param limit [Integer] the maximum number of holders for the semaphore.
+    #
+    # @return [Boolean]
+    def try_acquire(session_id, limit)
+      raise ArgumentError, 'semaphore limit must be at least 1' if limit < 1
+
+      read!
+
+      return true if @holders.include? session_id
+
+      unless @contenders.include? session_id
+        return false unless @client.kv_acquire_lock("#{@key_prefix}/#{session_id}", session_id)
+
+        @contenders << session_id
+      end
+
+      return false if @holders.size >= limit
+
+      @logger.info("semaphore has less than #{limit} holders, attempting to grab")
+
+      write_coordination_key(@holders.dup.add(session_id))
+    end
+
+    # Attempts to release the semaphore.
+    #
+    # @param session_id [String] the ID of a consul session to associate with the semaphore.
+    #
+    # @return [Boolean]
+    def try_release(session_id)
+      read!
+
+      return true unless @holders.include? session_id
+
+      if @contenders.include? session_id
+        @client.kv_delete("#{@key_prefix}/#{session_id}")
+        @contenders.delete(session_id)
+      end
+
+      write_coordination_key(@holders.dup.delete(session_id))
+    end
+
+    private
+
+    # Executes a block using [exponential backoff with jitter](https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/).
+    #
+    # @param backoff_cap [Float] the maximum interval to wait between attempts.
+    # @param timeout [Float] the maximum number of seconds to sleep before giving up; nil means try forever.
+    #
+    # @yieldreturn [Boolean]
+    #
+    # @return [Boolean]
+    def exponential_backoff(backoff_cap, timeout)
+      raise ArgumentError, 'backoff_cap must be at least 1.0' if backoff_cap < 1
+
+      # start with 200ms backoff
+      current_backoff = 0.2
+      elapsed_time    = 0
+
+      loop do
+        return true if yield
+
+        if !timeout.nil? && elapsed_time > timeout
+          @logger.info('timeout exceeded')
+
+          return false
+        end
+
+        # sleep up to the current_backoff value
+        time_to_sleep = rand(0..current_backoff)
+
+        @logger.info("call failed, will sleep #{time_to_sleep.truncate(3)} seconds until trying again")
+
+        sleep time_to_sleep
+
+        elapsed_time   += time_to_sleep
+        current_backoff = [2 * current_backoff, backoff_cap].min
+      end
+    end
+
+    # Reads the semaphore data from the key prefix.
+    def read!
+      @logger.info("reading semaphore @ key prefix '#{@key_prefix}'")
+
+      @modify_index   = 0
+      @contenders     = Set[]
+      claimed_holders = Set[]
+
+      @client.kv_read_recursive(@key_prefix).each do |entry|
+        if entry['Key'] == coordination_key_name
+          @modify_index   = entry['ModifyIndex']
+          claimed_holders = parse_holders(entry['Value'])
+        elsif entry['Session']
+          @contenders << entry['Session']
+        end
+      end
+
+      @holders = claimed_holders & @contenders
+    end
+
+    # Returns the expected name of the coordination key.
+    def coordination_key_name
+      "#{@key_prefix}/.lock"
+    end
+
+    # Parses the list of claimed semaphore holders.
+    def parse_holders(value)
+      Set.new(JSON.parse(value))
+    rescue JSON::ParserError, ArgumentError => e
+      @logger.warn("found invalid JSON or a non-array `holders` value: #{e}")
+
+      Set[]
+    end
+
+    # Attempts to write the coordination key with the optional new list of holders.
+    #
+    # @param new_holders [Set<String>] an optional new list of holders.
+    #
+    # @return [Boolean]
+    def write_coordination_key(new_holders = @holders)
+      if @client.kv_write_cas(coordination_key_name, JSON.generate(new_holders.to_a), @modify_index)
+        @holders = new_holders
+
+        return true
+      end
+
+      false
+    end
+
+  end
+end

data/lib/consulkit/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Consulkit
+
+  VERSION = '0.1.0'
+
+end

data/lib/consulkit.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require 'consulkit/client'
+require 'consulkit/configurable'
+require 'consulkit/defaults'
+require 'consulkit/semaphore_coordinator'
+require 'consulkit/version'
+
+# Ruby toolkit for the Consul API.
+#
+# @see https://developer.hashicorp.com/consul/api-docs
+module Consulkit
+
+  class << self
+
+    include Consulkit::Configurable
+
+    def client
+      Consulkit::Client.new(options)
+    end
+
+    def semaphore_coordinator(key_prefix, client: nil, logger: nil)
+      Consulkit::SemaphoreCoordinator.new(client || self.client, key_prefix, logger)
+    end
+
+  end
+
+end
+
+Consulkit.setup!

data/shell.nix

@@ -0,0 +1,15 @@
+with (import <nixpkgs> {});
+
+mkShell {
+  name = "consulkit";
+
+  buildInputs = [
+    ruby
+    bundler
+    rubocop
+  ];
+
+  shellHook = ''
+    bin/setup
+  '';
+}

metadata

@@ -0,0 +1,91 @@
+--- !ruby/object:Gem::Specification
+name: consulkit
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Eric Norris
+autorequire:
+bindir: exe
+cert_chain: []
+date: 1980-01-01 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+- !ruby/object:Gem::Dependency
+  name: faraday-retry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.2'
+description:
+email:
+- enorris@etsy.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/consulkit.rb
+- lib/consulkit/client.rb
+- lib/consulkit/client/kv.rb
+- lib/consulkit/client/session.rb
+- lib/consulkit/configurable.rb
+- lib/consulkit/defaults.rb
+- lib/consulkit/error.rb
+- lib/consulkit/middleware/raise_error.rb
+- lib/consulkit/semaphore_coordinator.rb
+- lib/consulkit/version.rb
+- shell.nix
+homepage: https://github.com/etsy/consulkit
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/etsy/consulkit
+  source_code_uri: https://github.com/etsy/consulkit
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.13
+signing_key:
+specification_version: 4
+summary: Ruby toolkit for the Consul API
+test_files: []