apprentice 0.0.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 5668ebd248945d42c501dba8c9a41ec836e33fe5
+  data.tar.gz: 1fc8746957d18e8e60197b3be49ada6e141ac6fc
+SHA512:
+  metadata.gz: bc00be6fd55cda823fe1be0482449da93abebb77fae7e76f2e12ddc36189a755a1d19c2cd057b74de857a33558dc87d7a2bbc0ea5780b94a3e7f8c09482f6035
+  data.tar.gz: 1ba4da56b061846ad0dbefab3ad37478f17e9c77f5719ca311fbd54a7630071cde6f1f11cafebe6e1d2858f81652c097201e42809579decb154dd9db28965fa0

data/.gitignore

@@ -0,0 +1,18 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+.idea

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format documentation

data/Gemfile

@@ -0,0 +1,10 @@
+source 'https://rubygems.org'
+
+gem 'mysql2'
+gem 'eventmachine'
+
+gem 'rspec'
+gem 'ipaddress'
+
+# Specify your gem's dependencies in apprentice.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Moritz Heiber
+
+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,58 @@
+# Apprentice
+
+Apprentice is tiny server application that determines the current state of a running [MariaDB Galera master-master cluster setup](https://mariadb.com/kb/en/what-is-mariadb-galera-cluster/) and responds to HTTP requests on a pre-defined port, depending on the state of the server it is checking on.
+
+## How does it work?
+
+You can find out about the syntax by running `apprentice --help`:
+
+    $ apprentice --help
+    Usage: apprentice [options]
+
+    Specific options:
+        -s, --server SERVER              Connect to SERVER
+        -u, --user USER                  USER to connect the server with
+        -p, --password PASSWORD          PASSWORD to use
+        -i, --ip IP                      Local IP to bind to
+            --port PORT                  Local PORT to use
+            --sql_port PORT              Port of the MariaDB server to connect to
+            --[no-]accept-donor          Accept cluster state "Donor/Desynced" as valid
+
+    Common options:
+        -h, --help                       Show this message
+        -v, --version                    Show version
+
+
+## What it does
+
+It determines whether or not the server it is connected to is alive and ready to serve connections to clients. Furthermore, it also determines whether said server is a healthy part of the MariaDB cluster it belongs.
+
+## What it doesn't do
+
+* **Loadbalancing**: In turn, it's ment to supply loadbalancers with data on whether or not to include a certain node into their balancing pool
+* **Relay client connections**: Apprentice itself only serves two responses on a pre-determined port:
+    * *`200 OK`*: The server Apprentice is checking is healthy and ready to accept connections
+    * *`503 Service Unavailable`*: The server is unavailable and not ready for connections
+
+## What's it checking exactly?
+
+Apprentice checks the following variables:
+
+* **wsrep_cluster_size**: A cluster size below 2 is considered an error since there must never be one single server inside a cluster setup.
+* **wsrep_ready**: Shows whether or not the replication is actually running or not. This must return `ON` for the server to be considered
+* **wsrep_local_state**: This should read `4`, however, you may also use the --donor-allowed flag on the command-line to turn the value `2` into an acceptable value. Whether or not this is a desired state in your environment is at your discretion.
+    * *Note*: The value `2` indicates the server in question is currently being used as a donor to another member of the cluster and might be exhibiting slow-downs and/or erratic behaviour due to elevated network traffic and disc IO. For further explanation please [consult the MariaDB documentation](https://mariadb.com/kb/en/what-is-mariadb-galera-cluster/).
+
+## That's great and all, but what gives?
+By itself, Apprentice doesn't do aynthing all that useful. However, it accommodates [HAProxy's httpchk method](http://cbonte.github.io/haproxy-dconv/configuration-1.4.html#option%20httpchk) quite nicely, making it possible to let HAProxy not only balance connection among a large pool of MariaDB cluster servers but also check on the cluster members health while doing so. With it you needn't care about a server dropping out of the cluster and clients still connecting to it since HAProxy and Apprentice are going to take care of that failing member by taking him out of the connection pool.
+
+## Goodies
+
+I've included an (untested) init.d script which you may use in order to start Apprentice at boot time.
+
+## TODO
+
+* Write better (r)docs. I'm sorry for the abysmal state they're in right now
+* Be a lot more forgiving when it comes to SQL connection errors/reconnects/server going awol.
+* Finish the rspec definitions. Sorry for missing out on those as well.
+* Write a better init script

data/Rakefile

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

data/apprentice.gemspec

@@ -0,0 +1,23 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'apprentice/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'apprentice'
+  spec.version       = Apprentice::VERSION
+  spec.authors       = 'Moritz Heiber'
+  spec.email         = %w{moritz.heiber@gmail.com}
+  spec.description   = 'A MariaDB cluster integrity checker'
+  spec.summary       = 'Check given servers for consistency and replication status'
+  spec.homepage      = 'http://github.com/moritzheiber/apprentice'
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = %w{lib}
+
+  spec.add_development_dependency 'bundler', '~> 1.3'
+  spec.add_development_dependency 'rake'
+end

data/bin/apprentice

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+
+require 'apprentice'
+
+sentinel = Apprentice::Sentinel.new
+sentinel.run

data/init.d/apprentice.sh

@@ -0,0 +1,83 @@
+#!/bin/bash
+### BEGIN INIT INFO
+# Provides:          apprentice
+# Required-Start:    mysql
+# Required-Stop:
+# Default-Start:     2 3 4 5
+# Default-Stop:      0 1 6
+# Short-Description: a MariaDB cluster integrity checker
+### END INIT INFO
+
+NAME="`basename ${0/.sh/}`"
+DAEMON="`which apprentice`"
+PIDFILE="/var/run/${NAME}.pid"
+
+[ -r /etc/default/${NAME} ] && source /etc/default/${NAME}
+
+for file in /lib/init/vars.sh /lib/lsb/init-functions ; do
+  source ${file}
+done
+
+#
+# Function that starts the daemon/service
+#
+do_start()
+{
+    log_begin_msg "Starting ${NAME}..."
+
+    if [ ! "${START}" = "true" ]; then
+      log_failure_msg "this service is disabled. Enable it in /etc/default/$NAME"
+      return 2
+    elif [ ! "${SERVER}" ] || [ ! "${PASSWORD}" ] || [ ! ${USER} ] ; then
+      log_failure_msg "Missing variables inside defaults file."
+      return 2
+    fi
+
+    pidfile_dirname=`dirname ${PIDFILE}`
+
+    [ -d "$pidfile_dirname" ] || mkdir -p "$pidfile_dirname"
+    chown $USER:$GROUP "$pidfile_dirname"
+    chmod 0750 "$pidfile_dirname"
+
+    DAEMON_ARGS="--password ${PASSWORD} --user ${USER} --server ${SERVER} ${EXTRA_ARGS}"
+
+    start-stop-daemon --start --background --make-pidfile --quiet \
+            --pidfile ${PIDFILE} --exec ${DAEMON} --test > /dev/null || return 1
+    start-stop-daemon --start --background --make-pidfile --quiet \
+            --pidfile ${PIDFILE} --exec ${DAEMON} -- ${DAEMON_ARGS} || return 2
+    log_end_msg $?
+}
+
+do_stop()
+{
+    log_begin_msg "Stopping ${NAME}..."
+
+    start-stop-daemon --stop --quiet --retry=TERM/30/KILL/5 --signal 15 --pidfile ${PIDFILE}
+    RETVAL="$?"
+    [ "$RETVAL" = 2 ] && return 2
+    [ "$?" = 2 ] && return 2
+    rm -f ${PIDFILE}
+    log_end_msg $?
+    return "$RETVAL"
+}
+
+case "$1" in
+  start)
+    do_start
+    ;;
+  stop)
+    do_stop
+    ;;
+  reload)
+    do_stop
+    do_start
+    ;;
+  restart|force-reload)
+    do_stop
+    do_start
+    ;;
+  *)
+    echo "Usage: ${NAME} {start|stop|restart|reload|force-reload}" >&2
+    exit 3
+    ;;
+esac

data/lib/apprentice.rb

@@ -0,0 +1,28 @@
+require 'eventmachine'
+require 'apprentice/configuration'
+require 'apprentice/version'
+require 'apprentice/server'
+
+module Apprentice
+  class Sentinel
+    include Configuration
+    include Server
+
+    def initialize
+      @options = get_config
+    end
+
+    def run
+      EM.run do
+        Signal.trap('INT') { EventMachine.stop }
+        Signal.trap('TERM') { EventMachine.stop }
+        EventMachine.start_server(
+            @options.ip,
+            @options.port,
+            Server::EventServer,
+            @options
+        )
+      end
+    end
+  end
+end

data/lib/apprentice/checker.rb

@@ -0,0 +1,21 @@
+module Checker
+  require 'apprentice/checks/galera'
+  include Galera
+
+  STATES = {1 => 'Joining',2 => 'Donor/Desynced',3 => 'Joined',4 => 'Synced'}
+  CODES = {200 => 'OK',503 => 'Service Unavailable'}
+
+  def format_text(texts)
+    value = ''
+    if !texts.empty?
+      texts.each do |t|
+        value << "#{t}\r\n"
+      end
+    end
+    return value
+  end
+
+  def generate_response(code = 503, text)
+    "HTTP/1.1 #{code} #{CODES[code]}\r\nContent-type: text/plain\r\nContent-length: #{text.length}\r\n\r\n#{text}"
+  end
+end

data/lib/apprentice/checks/galera.rb

@@ -0,0 +1,51 @@
+module Galera
+  def get_galera_status
+    begin
+      result = @client.query "SHOW STATUS LIKE 'wsrep_%';"
+      if result.count > 0
+        result.each do |r|
+          @status.merge!(Hash[*r])
+        end
+      end
+    rescue Exception => message
+      puts message
+    end
+  end
+
+  def run_checks
+    get_galera_status
+    unless @status.empty?
+      response = {code: 200, text: []}
+      if !check_cluster_size
+        response[:text] << "Cluster size is #{@status['wsrep_cluster_size']}. Split-brain situation is likely."
+      end
+      if !check_ready_state
+        response[:text] << 'Cluster replication is not running.'
+      end
+      if !check_local_state
+        response[:text] << "Local state is '#{STATES[@status['wsrep_local_state']]}'."
+      end
+      response[:code] = 503 unless response[:text].empty?
+      return response
+    else
+      return {code: 503, text: ['Unable to determine cluster status']}
+    end
+  end
+
+  def check_cluster_size
+    return true if Integer(@status['wsrep_cluster_size']) > 1
+    false
+  end
+
+  def check_ready_state
+    return true if @status['wsrep_ready'] == 'ON'
+    false
+  end
+
+  def check_local_state
+    s = Integer(@status['wsrep_local_state'])
+    return true if s == 4 || (s == 2 && @donor_allowed)
+    false
+  end
+
+end

data/lib/apprentice/configuration.rb

@@ -0,0 +1,60 @@
+require 'optparse'
+require 'ostruct'
+
+module Configuration
+  def get_config
+    options = OpenStruct.new
+    options.ip = '0.0.0.0'
+    options.port = 3307
+    options.sql_port = 3306
+    options.accept_donor = false
+
+    opt_parser = OptionParser.new do |opts|
+      opts.banner = "Usage: apprentice [options]\n"
+      opts.separator ''
+      opts.separator 'Specific options:'
+
+      opts.on('-s SERVER', '--server SERVER',
+        'Connect to SERVER') { |s| options.server = s }
+      opts.on('-u USER', '--user USER',
+        'USER to connect the server with') { |u| options.user = u }
+      opts.on('-p PASSWORD', '--password PASSWORD',
+        'PASSWORD to use') { |p| options.password = p }
+
+      opts.on('-i', '--ip IP',
+        'Local IP to bind to') { |i| options.ip = i }
+      opts.on('--port PORT',
+        'Local PORT to use') { |p| options.port = p }
+      opts.on('--sql_port PORT',
+        'Port of the MariaDB server to connect to') { |p| options.sql_port = p }
+      opts.on('--[no-]accept-donor',
+        'Accept cluster state "Donor/Desynced" as valid') { |ad| options.accept_donor = ad }
+
+      opts.separator ''
+      opts.separator 'Common options:'
+
+      opts.on_tail('-h', '--help', 'Show this message') do
+        puts opts
+        exit
+      end
+      opts.on_tail('-v', '--version', 'Show version') do
+        puts "Apprentice #{Apprentice::VERSION}"
+        exit
+      end
+    end
+
+    begin
+      ARGV << 's-h' if ARGV.size < 3
+      opt_parser.parse!(ARGV)
+      unless options.server && options.user && options.password
+        $stderr.puts 'Error: you have to specify a user, a password and the server to connect to'
+        $stderr.puts 'Try -h/--help for more options'
+        exit
+      end
+      return options
+    rescue OptionParser::ParseError
+      $stderr.print "Error: #{$!}\n"
+      exit
+    end
+  end
+end

data/lib/apprentice/server.rb

@@ -0,0 +1,40 @@
+module Server
+  class EventServer < EM::Connection
+    require 'apprentice/checker'
+    require 'mysql2/em'
+    include Checker
+
+    attr_accessor :client
+
+    def initialize(options)
+      @ip = options.ip
+      @port = options.port
+      @sql_port = options.sql_port
+      @server = options.server
+      @user = options.user
+      @password = options.password
+      @donor_allowed = options.donor_allowed
+      @status = {}
+
+      begin
+        @client = Mysql2::Client.new(
+            host: @server,
+            port: @sql_port,
+            username: @user,
+            password: @password,
+            as: :array,
+            reconnect: true
+        )
+      rescue Exception => message
+        puts message
+        EM.stop_server
+      end
+    end
+
+    def receive_data(data)
+      response = run_checks
+      response_text = format_text(response[:text])
+      send_data generate_response(response[:code], response_text)
+    end
+  end
+end

data/lib/apprentice/version.rb

@@ -0,0 +1,3 @@
+module Apprentice
+  VERSION = '0.0.2'
+end

data/spec/lib/apprentice_spec.rb

@@ -0,0 +1,8 @@
+require 'spec_helper'
+require 'apprentice'
+require 'ipaddress'
+
+describe Apprentice do
+  describe Apprentice::Sentinel do
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,17 @@
+# This file was generated by the `rspec --init.d` command. Conventionally, all
+# specs live under a `spec` directory, which RSpec adds to the `$LOAD_PATH`.
+# Require this file using `require "spec_helper"` to ensure that it is only
+# loaded once.
+#
+# See http://rubydoc.info/gems/rspec-core/RSpec/Core/Configuration
+RSpec.configure do |config|
+  config.treat_symbols_as_metadata_keys_with_true_values = true
+  config.run_all_when_everything_filtered = true
+  config.filter_run :focus
+
+  # Run specs in random order to surface order dependencies. If you find an
+  # order dependency and want to debug it, you can fix the order by providing
+  # the seed, which is printed after each run.
+  #     --seed 1234
+  config.order = 'random'
+end

metadata

@@ -0,0 +1,93 @@
+--- !ruby/object:Gem::Specification
+name: apprentice
+version: !ruby/object:Gem::Version
+  version: 0.0.2
+platform: ruby
+authors:
+- Moritz Heiber
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-09-05 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: A MariaDB cluster integrity checker
+email:
+- moritz.heiber@gmail.com
+executables:
+- apprentice
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .rspec
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- apprentice.gemspec
+- bin/apprentice
+- init.d/apprentice.sh
+- lib/apprentice.rb
+- lib/apprentice/checker.rb
+- lib/apprentice/checks/galera.rb
+- lib/apprentice/configuration.rb
+- lib/apprentice/server.rb
+- lib/apprentice/version.rb
+- spec/lib/apprentice_spec.rb
+- spec/spec_helper.rb
+homepage: http://github.com/moritzheiber/apprentice
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.0.7
+signing_key: 
+specification_version: 4
+summary: Check given servers for consistency and replication status
+test_files:
+- spec/lib/apprentice_spec.rb
+- spec/spec_helper.rb
+has_rdoc: