kamisama 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 482b1702ced157fcca3c04db289c376857183807
+  data.tar.gz: 1f059faa1c65b3741ebd176f60e93658cfb7d0aa
+SHA512:
+  metadata.gz: 036ead213535c5b0ccf332c88671cb3354431e21deeff00b6498a0eecde8b513d3db9e83d8753f66209bebe83ebff278f68ed4c53ed32f717ef6969608bc6f29
+  data.tar.gz: b316668f54aeee9358ff361c4851ab0d50de821f16147f5c5e30e9ef48309fe7a56a6eb8b5fc47c233a7083eae272fd0ea2f99b5063555f05a4e7f1fe4ab956a

data/.gitignore

@@ -0,0 +1,10 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+vendor/bundle

data/.rspec

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

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,13 @@
+# Contributor Code of Conduct
+
+As contributors and maintainers of this project, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities.
+
+We are committed to making participation in this project a harassment-free experience for everyone, regardless of level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, or religion.
+
+Examples of unacceptable behavior by participants include the use of sexual language or imagery, derogatory comments or personal attacks, trolling, public or private harassment, insults, or other unprofessional conduct.
+
+Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct. Project maintainers who do not follow the Code of Conduct may be removed from the project team.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening an issue or contacting one or more of the project maintainers.
+
+This Code of Conduct is adapted from the [Contributor Covenant](http://contributor-covenant.org), version 1.0.0, available at [http://contributor-covenant.org/version/1/0/0/](http://contributor-covenant.org/version/1/0/0/)

data/Gemfile

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

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2017 Igor Šarčević
+
+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,193 @@
+# Kamisama
+
+[![Build Status](https://semaphoreci.com/api/v1/renderedtext/kamisama/branches/master/badge.svg)](https://semaphoreci.com/renderedtext/kamisama)
+
+Start, monitor, and observe background worker processes, from Ruby.
+
+Based on [Unicorn](), [God](), and [Sidekiq]().
+
+# Usage
+
+Kamisama is useful for starting multiple background workers. For example, let's
+say that you have a background worker that crunches some data with periodic
+intervals.
+
+``` ruby
+def worker
+  loop do
+    puts "Crunching data..."
+
+    sleep 60
+  end
+end
+```
+
+A usual way to run this task is to wrap it in a Rake task, and an upstart script
+to keep it running forever. This is pretty well until you have one process that
+you want to execute. However, if you want to run multiple processes, you need to
+introduce and manage multiple upstart configurations. One upstart script that
+acts like the master who manages your workers, and upstart scripts that describe
+your workers.
+
+This setup is cumbersome, hard to test, and managing different configurations
+for different environments (production, staging, development) can be outright
+frustrating.
+
+Kamisama is here to help, by abstracting away the issue of running and monitor
+multiple background workers.
+
+Let's run 17 instances of the above worker with Kamisama:
+
+``` ruby
+def worker(worker_index)
+  loop do
+    puts "WORKER #{worker_index}: Crunching data..."
+
+    sleep 60
+  end
+end
+
+Kamisama.run(:instances => 17) { |index| worker(index) }
+```
+
+That's all! The above will start(fork) 17 processes on your machine, and restart
+them in case of failure.
+
+Keep in mind that you will still need to wrap Kamisama itself in a rake task
+and an Upstart script.
+
+### Respawn limits
+
+Respawning workers is desirable in most cases, but we would still like to avoid
+rapid restarts of your workers in a short amount of time. Such rapid restarts
+can harm your system, and usually indicate that a serious issue is killing
+your workers.
+
+If the job is respawned more than `respawn_limit` times in `respawn_interval`
+seconds, Kamisama will considered this to be a deeper problem and will die.
+
+``` ruby
+def worker(worker_index)
+  loop do
+    puts "WORKER #{worker_index}: Crunching data..."
+
+    sleep 60
+  end
+end
+
+config = {
+  :instances => 17,
+  :respawn_limit => 10,
+  :respawn_interval => 60
+}
+
+Kamisama.run(config) { |index| worker(index) }
+```
+
+## Signal control
+
+You can control your Kamisama process by sending kill signals to the running
+process.
+
+- [TERM](#term-signal) - terminates master process and all workers
+- [KILL](#kill-signal)  - terminates master process and all workers
+- [TTIN](#ttin-signal) - spawns a new worker
+- [TTIN](#ttou-signal) - terminates a running worker
+
+#### TERM signal
+
+If you send a term signal to your Kamisama process, it will immediately
+shutdown. Following this, every children will be notified by the kernel that the
+master process has died with the TERM signal.
+
+For example, if you have the following processes:
+
+``` bash
+2000 - PID of master process
+2001 - PID of first worker
+2002 - PID of second worker
+2003 - PID of third worker
+```
+
+Then when you send a "TERM" signal:
+
+``` bash
+kill -TERM 2000
+```
+
+The master process `2000` will die immediately, and the workers processes
+(2001, 2002, 2003) will receive the `TERM` signal.
+
+#### KILL signal
+
+If you send a kill signal to your Kamisama process, it will immediately
+shutdown. Following this, every children will be notified by the kernel that the
+master process has dies with the TERM signal.
+
+For example, if you have the following processes:
+
+``` bash
+2000 - PID of master process
+2001 - PID of first worker
+2002 - PID of second worker
+2003 - PID of third worker
+```
+
+Then when you send a "KILL" signal:
+
+``` bash
+kill -9 2000
+```
+
+The master process `2000` will die immediately, and the workers processes
+(2001, 2002, 2003) will receive the `TERM` signal.
+
+#### TTIN signal
+
+If you send a ttin signal to your Kamisama process, it will spawn a new process.
+
+For example, if you have the following processes:
+
+``` bash
+2000 - PID of master process
+2001 - PID of first worker
+2002 - PID of second worker
+2003 - PID of third worker
+```
+
+Then when you send a "TTIN" signal:
+
+``` bash
+kill -TTIN 2000
+```
+
+The master process `2000` will spawn a new worker process.
+
+#### TTOU signal
+
+If you send a ttou signal to your Kamisama process, it will kill the oldest
+worker.
+
+For example, if you have the following processes:
+
+``` bash
+2000 - PID of master process
+2001 - PID of first worker
+2002 - PID of second worker
+2003 - PID of third worker
+```
+
+Then when you send a "TTOU" signal:
+
+``` bash
+kill -TTOU 2000
+```
+
+The master process `2000` will send a `TERM` signal to the process `2001`.
+
+*NOTE*: This will only work if you have more than one running processes.
+
+## License
+
+The gem is available as open source under the terms of the
+[MIT License](http://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "kamisama"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start

data/bin/setup

@@ -0,0 +1,7 @@
+#!/bin/bash
+set -euo pipefail
+IFS=$'\n\t'
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/kamisama.gemspec

@@ -0,0 +1,28 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'kamisama/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "kamisama"
+  spec.version       = Kamisama::VERSION
+  spec.authors       = ["Igor Šarčević"]
+  spec.email         = ["igor@renderedtext.com"]
+
+  spec.summary       = %q{Start, monitor, and observe background worker processes, from Ruby.}
+  spec.description   = %q{Start, monitor, and observe background worker processes, from Ruby.}
+  spec.homepage      = "https://github.com/shiroyasha/kamisama"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "ffi", "~> 1.0"
+
+  spec.add_development_dependency "bundler", "~> 1.10"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec"
+  spec.add_development_dependency "sys-proctable"
+end

data/lib/kamisama.rb

@@ -0,0 +1,94 @@
+class Kamisama
+  require "kamisama/version"
+  require "kamisama/process_ctrl"
+  require "kamisama/task"
+  require "kamisama/respawn_limiter"
+
+  def self.run(options = {}, &block)
+    new(options, &block).run
+  end
+
+  def initialize(options, &block)
+    @block            = block
+    @instances        = options.fetch(:instances)
+    @respawn_limit    = options.fetch(:respawn_limit, 3)
+    @respawn_interval = options.fetch(:respawn_interval, 60)
+    @monitor_sleep    = 2
+
+    @term_signal_received = false
+
+    @respawn_limiter = Kamisama::RespawnLimiter.new(@respawn_limit, @respawn_interval)
+
+    @tasks = []
+  end
+
+  def run
+    puts "[Kamisama Master] Process id: #{Process.pid}"
+    puts "[Kamisama Master] Starting #{@instances} workers. \n"
+
+    @instances.times { add_worker }
+
+    handle_signals
+
+    monitor
+  end
+
+  def handle_signals
+    trap("TTIN") do
+      @instances += 1
+    end
+
+    trap("TTOU") do
+      # make sure that we always have at least one running worker
+      if @instances > 1
+        @instances -= 1
+      end
+    end
+
+    trap("TERM") do
+      @term_signal_received = true
+    end
+  end
+
+  def add_worker
+    puts "[Kamisama Master] #{Process.pid} Spawning new instance."
+
+    @worker_index ||= 0
+    @worker_index += 1
+
+    task = Kamisama::Task.new(@worker_index, @block)
+    task.start
+
+    @tasks << task
+  end
+
+  def term_worker
+    puts "[Kamisama Master] #{Process.pid} Terminating an instance."
+
+    task = @tasks.shift
+    task.terminate!
+  end
+
+  def monitor
+    loop do
+      break if @term_signal_received
+
+      add_worker  while @tasks.count < @instances
+      term_worker while @tasks.count > @instances
+
+      dead_tasks = @tasks.reject(&:alive?)
+
+      dead_tasks.each do |task|
+        @respawn_limiter.record!
+        task.restart!
+      end
+
+      sleep(@monitor_sleep)
+    end
+
+    puts "[Kamisama Master] #{Process.pid} Terminating all instances"
+    @tasks.each(&:terminate!)
+    exit
+  end
+
+end

data/lib/kamisama/process_ctrl.rb

@@ -0,0 +1,36 @@
+require "ffi"
+
+class Kamisama
+  class ProcessCtrl
+    SIGINT = 2
+    SIGTERM = 15
+
+    module LibC
+      PR_SET_NAME = 15
+      PR_SET_PDEATHSIG = 1
+
+      extend FFI::Library
+      ffi_lib "c"
+      attach_function :prctl, [:int, :long, :long, :long, :long], :int
+    end
+
+    def self.set_process_name(process_name)
+      # The process name is max 16 characters, so get the first 16, and if it is
+      # less pad with spaces to avoid formatting wierdness
+      process_name = "%-16.16s" % name
+
+      LibC.prctl(LibC::PR_SET_NAME, process_name, 0, 0, 0)
+    end
+
+    def self.set_parent_death_signal(signal)
+      case signal
+      when :sigint
+        LibC.prctl(LibC::PR_SET_PDEATHSIG, SIGINT, 0, 0, 0)
+      when :sigterm
+        LibC.prctl(LibC::PR_SET_PDEATHSIG, SIGTERM, 0, 0, 0)
+      else
+        raise "Unrecognized signal '#{signal.inspect}'"
+      end
+    end
+  end
+end

data/lib/kamisama/respawn_limiter.rb

@@ -0,0 +1,35 @@
+class Kamisama::RespawnLimiter
+
+  def initialize(respawn_limit, respawn_interval)
+    @respawn_limit = respawn_limit
+    @respawn_interval = respawn_interval
+
+    @respawns = []
+  end
+
+  def record!
+    now = Time.now.to_i
+
+    @respawns = @respawns.select { |timestamp| timestamp >= now - @respawn_interval } + [now]
+
+    die_if_breached!
+  end
+
+  def calculate_respawn_count
+    now = Time.now.to_i
+
+    @respawns.count { |timestamp| timestamp > (now - @respawn_interval) }
+  end
+
+  def die_if_breached!
+    respawn_count = calculate_respawn_count
+
+    if respawn_count >= @respawn_limit
+      puts "[Kamisama Master] Respawn count #{respawn_count} hit the limit of #{@respawn_limit} for the respawn interval of #{@respawn_interval} seconds."
+      puts "[Kamisama Master] Terminating."
+
+      exit(1)
+    end
+  end
+
+end

data/lib/kamisama/task.rb

@@ -0,0 +1,50 @@
+class Kamisama
+  class Task
+    def initialize(task_index, block)
+      @task_index = task_index
+      @block = block
+    end
+
+    def start
+      @pid = Process.fork do
+        begin
+          # receive sigterm when parent dies
+          Kamisama::ProcessCtrl.set_parent_death_signal(:sigterm)
+
+          log("Worker started. Hello!")
+
+          @block.call(@task_index)
+        rescue Exception => e
+          # handle all exceptions, even system ones
+          log("Shutting down... #{e.message}")
+          exit
+        ensure
+          exit
+        end
+      end
+
+      Process.detach(@pid)
+    end
+
+    def restart!
+      puts "[Kamisama Master] Restarting Worker."
+      @pid = nil
+      start
+    end
+
+    def terminate!
+      Process.kill("TERM", @pid)
+    end
+
+    def alive?
+      Process.getpgid(@pid)
+      true
+    rescue Errno::ESRCH
+      false
+    end
+
+    def log(message)
+      puts "[WORKER #{@task_index}] #{message}"
+    end
+  end
+end

data/lib/kamisama/version.rb

@@ -0,0 +1,3 @@
+class Kamisama
+  VERSION = "0.1.0"
+end

metadata

@@ -0,0 +1,129 @@
+--- !ruby/object:Gem::Specification
+name: kamisama
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Igor Šarčević
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2017-04-12 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ffi
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  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'
+- !ruby/object:Gem::Dependency
+  name: sys-proctable
+  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: Start, monitor, and observe background worker processes, from Ruby.
+email:
+- igor@renderedtext.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- CODE_OF_CONDUCT.md
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- kamisama.gemspec
+- lib/kamisama.rb
+- lib/kamisama/process_ctrl.rb
+- lib/kamisama/respawn_limiter.rb
+- lib/kamisama/task.rb
+- lib/kamisama/version.rb
+homepage: https://github.com/shiroyasha/kamisama
+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.4.8
+signing_key: 
+specification_version: 4
+summary: Start, monitor, and observe background worker processes, from Ruby.
+test_files: []