proclib 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: b8a7d4e4a70ff96e2309807bffc296bb93d9aa67
+  data.tar.gz: 4c09847012dfc3010071e7d589ab6802786726fe
+SHA512:
+  metadata.gz: cead6a0fffa9ee03ae07ab6ea2c0dfd368171497e4b30f5b31d7c12bfedfde362d76bcd2bf1d6788aba12dbf05369a196ab235783507a7f9d290239f4782b1a1
+  data.tar.gz: 9b4385413c690e8ef80484b6d20fe986f2d23f97a1cba6a9f3157ce203db427b78620a233dffeb3ab63cdbc2d35ea80b1b4d989686a0fd9871c1574e266f3e95

data/.gitignore

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

data/.rspec

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

data/.travis.yml

@@ -0,0 +1,5 @@
+sudo: false
+language: ruby
+rvm:
+  - 2.3.3
+before_install: gem install bundler -v 1.13.6

data/Gemfile

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

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2017 Jack Forrest
+
+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,23 @@
+# Proclib
+
+High-level tools for subprocess management in Ruby
+
+## Status
+
+I use Proclib as a suport library for a couple of systems utilities that I'm
+slowly preparing for a proper open-source release.  Proclib is one of
+several extracted libraries that I'll be maturing into their own projects.
+
+Proclib is currently beta quality at best.
+
+## Usage
+
+See `examples/main.rb`
+
+Currenty, Proclib doesn't do anything on exit to kill child processes, so you'll
+need to trap the appropriate signals yourself to keep from leaving orphaned processes
+around.
+
+## License
+
+[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 "proclib"
+
+# 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,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/examples/main.rb

@@ -0,0 +1,21 @@
+require 'pry'
+require 'pathname'
+
+Thread.abort_on_exception = true
+
+$LOAD_PATH.unshift Pathname.new(File.expand_path(__FILE__)).join('..', '..', 'lib').to_s
+
+require_relative '../lib/proclib'
+
+# Run a quick command with output logged to the console
+
+Proclib.run("echo herorooo >&2", tag: :test, log_to_console: true)
+
+_, stdout, _ = Proclib.run("ls /tmp/", capture_output: true)
+
+puts "Files in /tmp"
+puts stdout.join
+
+cmd = "seq 1 10 | while read n; do echo $n; sleep 0.5; done"
+
+Proclib.run({tmp: cmd, home: cmd}, log_to_console: true)

data/lib/proclib.rb

@@ -0,0 +1,34 @@
+require 'open3'
+require 'thread'
+
+require 'proclib/version'
+
+require 'proclib/event_emitter'
+require 'proclib/process'
+require 'proclib/process_group'
+require 'proclib/executor'
+
+module Proclib
+  module Methods
+    def run(cmd, tag: nil, log_to_console: false, capture_output: true)
+      runnable = if cmd.kind_of? String
+         Process.new(cmd, tag: tag || cmd[0..20])
+      elsif cmd.kind_of?(Hash)
+        processes = cmd.map {|(k,v)| Process.new(v, tag: k || v[0..20]) }
+        ProcessGroup.new(processes)
+      else
+        raise ArgumentError, "Unexpected type for `cmd`: #{cmd.class}.  \n"\
+          "Expected String or Hash"
+      end
+
+      executor = Executor.new(runnable,
+        log_to_console: log_to_console,
+        cache_output: capture_output)
+      executor.run_sync
+    end
+  end
+
+  class << self
+    include Methods
+  end
+end

data/lib/proclib/event_emitter.rb

@@ -0,0 +1,71 @@
+module Proclib
+  # Async event utils
+  module EventEmitter
+    Event = Struct.new(:name, :sender, :data)
+    Error = Class.new(StandardError)
+
+    # Provides callbacks on events from bound producers
+    class Channel
+      COMPLETE = Object.new
+
+      def initialize
+        @queue = ::Queue.new
+        @handlers = Hash.new
+      end
+
+      def push(msg)
+        unless msg.kind_of?(Event)
+          raise(Error, "EventEmitter::Queue should only handle messages of type EventEmitter::Event")
+        end
+
+        @queue.push(msg)
+      end
+
+      def on(name, &handler)
+        (handlers[name] ||= Array.new) << handler
+      end
+
+      def watch
+        while ev = @queue.pop
+          break if ev == COMPLETE
+          handlers[ev.name].each {|h| h.call(ev)} if handlers[ev.name]
+        end
+      end
+
+      def finalize
+        @queue.push(COMPLETE)
+      end
+
+      private
+      attr_reader :handlers
+    end
+
+    # Emits messages to bound channel
+    module Producer
+      def bind_to(queue)
+        @event_queue = queue
+      end
+
+      def bound?
+        ! @event_queue.nil?
+      end
+
+      private
+
+      def bubble_events_for(child)
+        if bound?
+          child.bind_to(@event_queue)
+        end
+      end
+
+      def emit(name, data = nil)
+        push(Event.new(name, self, data))
+      end
+
+      def push(event)
+        @event_queue.push(event) if bound?
+      end
+    end
+  end
+  private_constant :EventEmitter
+end

data/lib/proclib/executor.rb

@@ -0,0 +1,57 @@
+require 'proclib/event_emitter'
+require 'proclib/loggers/console'
+require 'proclib/output_cache'
+
+module Proclib
+  # Runs a runnable, handling emitted events and dispatching to configured
+  # facilities
+  class Executor
+    attr_reader :opts
+
+    def initialize(runnable, opts = {})
+      @runnable = runnable
+      @opts = opts
+    end
+
+    def on(name, &block)
+      channel.on(name, &block)
+    end
+
+    def run_sync
+      configure
+      runnable.spawn
+      channel.watch
+      return @status, *%i{stdout stderr}.map {|i| output_cache.pipe_aggregate(i) }
+    end
+
+    private
+
+    attr_reader :runnable, :log_to_console
+
+    def configure
+      runnable.bind_to(channel)
+      channel.on(:complete) do |event|
+        @status = event.data.to_i
+        channel.finalize
+      end
+      configure_output
+    end
+
+    def configure_output
+      channel.on(:output) {|e| console_logger << e.data } if opts[:log_to_console]
+      channel.on(:output) {|e| output_cache << e.data} if opts[:cache_output]
+    end
+
+    def output_cache
+      @output_cache ||= OutputCache.new
+    end
+
+    def console_logger
+      @console_logger ||= Loggers::Console.new
+    end
+
+    def channel
+      @channel ||= EventEmitter::Channel.new
+    end
+  end
+end

data/lib/proclib/loggers/console.rb

@@ -0,0 +1,24 @@
+require 'proclib/string_formatting'
+
+using Proclib::StringFormatting
+
+module Proclib
+  module Loggers
+    class Console
+      def log(message)
+        STDOUT.printf("[ %-20s | %-8s ] %s",
+          message.process_tag.to_s.truncate_to(20).colorize(:cyan),
+          stylized_pipe_name(message),
+          message.line)
+      end
+      alias_method :<<, :log
+
+      private
+
+      def stylized_pipe_name(message)
+        color = ( {stdout: :blue, stderr: :yellow}[message.pipe_name] || :default )
+        message.pipe_name.to_s.truncate_to(8).colorize(color)
+      end
+    end
+  end
+end

data/lib/proclib/output_cache.rb

@@ -0,0 +1,40 @@
+module Proclib
+  class OutputCache
+    class Entry < Struct.new(:process_tag, :pipe_name, :cache)
+      def <<(line)
+        entry << line
+      end
+
+      private
+
+      def entry
+        (process_cache[pipe_name] ||= Array.new)
+      end
+
+      def process_cache
+        (cache[process_tag] ||= Hash.new)
+      end
+    end
+
+    def << message
+      Entry.new(message.process_tag, message.pipe_name, cache) << message.line
+    end
+
+    def pipe_aggregate(name)
+      process_caches.map {|c| c[name] || []}.flatten
+    end
+
+    private
+
+    def process_caches
+      cache.values
+    end
+
+    # Data structure: { process_tag: { stdin: [], stdout: [] } }
+    def cache
+      @cache ||= Hash.new
+    end
+  end
+
+  private_constant :OutputCache
+end

data/lib/proclib/output_handler.rb

@@ -0,0 +1,37 @@
+require 'thread'
+
+module Proclib
+  # Emits events for the given io pipe with relevant tagging info
+  class OutputHandler
+    Message = Class.new(Struct.new(:process_tag, :pipe_name, :line))
+
+    include EventEmitter::Producer
+
+    def initialize(process_tag, pipe_name, pipe)
+      @process_tag, @pipe_name, @pipe = process_tag, pipe_name, pipe
+    end
+
+    def start
+      @thread = Thread.new { monitor }
+    end
+
+    def wait
+      @thread.join
+    end
+
+    def kill
+      @thread.exit
+    end
+
+    private
+
+    attr_reader :process_tag, :pipe_name, :pipe
+
+    def monitor
+      pipe.each_line do |line|
+        emit(:output, Message.new(process_tag, pipe_name, line))
+      end
+      emit(:end_of_output)
+    end
+  end
+end

data/lib/proclib/process.rb

@@ -0,0 +1,72 @@
+require 'open3'
+require 'ostruct'
+
+require 'proclib/output_handler'
+
+module Proclib
+  # Runs a single process, emitting output, state changes and exit status
+  class Process
+    include EventEmitter::Producer
+
+    attr_reader :cmdline, :tag
+
+    Error = Class.new(StandardError)
+
+    def initialize(cmdline, tag:)
+      @cmdline = cmdline
+      @tag = tag
+      @state = :ready
+      @io_handlers = OpenStruct.new
+      @pipes = OpenStruct.new
+    end
+
+    def spawn
+      raise(Error, "Already started process") unless @wait_thread.nil?
+
+      pipes.stdin, pipes.stdout, pipes.stderr, @wait_thread = Open3.popen3(cmdline)
+      @state = :running?
+      start_output_emitters
+      start_watch_thread
+    end
+
+    def complete?
+      @state == :complete
+    end
+
+    private
+    attr_reader :wait_thread, :io_handlers, :pipes
+
+    def start_watch_thread
+      Thread.new do
+        result = wait_thread.value
+        io_handlers.each_pair {|(_, e)| e.wait }
+        @state = :complete
+        emit(:exit, result)
+        emit(:complete)
+      end
+    end
+
+    def start_output_emitters
+      %i(stderr stdout).map do |type|
+        io_handlers[type] = OutputHandler.new(tag, type, pipes[type]).tap do |handler|
+          bubble_events_for(handler)
+          handler.start
+        end
+      end
+    end
+
+    def check_started
+      if wait_thread.nil?
+        raise Error, "Process `#{tag}` is not yet started!"
+      end
+    end
+
+    def output_buffer
+      check_started
+      @output_buffer ||= OutputBuffer.new(tag, stdout_pipe, stderr_pipe).tap do |buffer|
+        bubble_events_for(buffer)
+      end
+    end
+  end
+  private_constant :Process
+end

data/lib/proclib/process_group.rb

@@ -0,0 +1,41 @@
+require 'proclib/event_emitter'
+
+module Proclib
+  class ProcessGroup
+    include EventEmitter::Producer
+
+    def initialize(processes)
+      @processes = processes
+    end
+
+    def spawn
+      processes.each do |process|
+        process.bind_to(channel)
+        process.spawn
+      end
+
+      start_watch_thread
+    end
+
+    def kill
+      processes.each(&:kill)
+    end
+
+    private
+    attr_reader :processes
+
+    def start_watch_thread
+      Thread.new { channel.watch }
+    end
+
+    def channel
+      @channel ||= EventEmitter::Channel.new.tap do |channel|
+        channel.on(:output) {|ev| push(ev) }
+        channel.on(:exit) do |ev|
+          emit(:complete) if processes.all?(&:complete?)
+        end
+      end
+    end
+  end
+  private_constant :ProcessGroup
+end

data/lib/proclib/string_formatting.rb

@@ -0,0 +1,28 @@
+module Proclib
+  module StringFormatting
+    refine String do
+      UnknownColor = Class.new(StandardError)
+
+      COLORS = {
+        yellow: 33,
+        blue: 34,
+        cyan: 36,
+        default: 0,
+      }
+
+      def colorize(color)
+        color = COLORS[color]
+
+        if color.nil?
+          raise(UnknownColor, "Unknown color for string: `#{color}`")
+        end
+
+        "\033[#{color}m#{self}\033[#{COLORS[:default]}m"
+      end
+
+      def truncate_to(size)
+        self[0..size]
+      end
+    end
+  end
+end

data/lib/proclib/version.rb

@@ -0,0 +1,3 @@
+module Proclib
+  VERSION = "0.1.0"
+end

data/proclib.gemspec

@@ -0,0 +1,29 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'proclib/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "proclib"
+  spec.version       = Proclib::VERSION
+  spec.authors       = ["Jack Forrest"]
+  spec.email         = ["jack@jrforrest.net"]
+
+  spec.summary       = %q{Provides tools for subprocess management}
+  spec.description   = "Proclib allows easy management of subprocess with a "\
+    "very high-level interface, with niceties such as multiplexed logging of "\
+    "output to logfiles and the console, output capture, and signal propagation."
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.13"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "pry"
+end

metadata

@@ -0,0 +1,123 @@
+--- !ruby/object:Gem::Specification
+name: proclib
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Jack Forrest
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2017-11-25 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.13'
+- !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: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: pry
+  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: Proclib allows easy management of subprocess with a very high-level interface,
+  with niceties such as multiplexed logging of output to logfiles and the console,
+  output capture, and signal propagation.
+email:
+- jack@jrforrest.net
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- examples/main.rb
+- lib/proclib.rb
+- lib/proclib/event_emitter.rb
+- lib/proclib/executor.rb
+- lib/proclib/loggers/console.rb
+- lib/proclib/output_cache.rb
+- lib/proclib/output_handler.rb
+- lib/proclib/process.rb
+- lib/proclib/process_group.rb
+- lib/proclib/string_formatting.rb
+- lib/proclib/version.rb
+- proclib.gemspec
+homepage: 
+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.5.2
+signing_key: 
+specification_version: 4
+summary: Provides tools for subprocess management
+test_files: []