wormholes 0.0.1

data/.gitignore

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

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Aaron Royer
+
+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,83 @@
+# wormholes
+
+shell utility that warps text elsewhere
+
+## Installation
+
+```
+$ gem install wormholes
+```
+Make sure to include the "s". The singular form is something else entirely.
+
+## Usage
+
+Open one end of the wormhole with ```worm```. You can pipe any text into it you would like but a wormhole is generally best suited for some progressive, long-running output like a server log.
+
+```
+$ rails server | worm
+```
+At this point whatever is piped into the wormhole does not go anywhere. It disappears. You could say it goes into a black hole, I suppose.
+
+If you want to start seeing any of that text again, open the other end with ```hole```.
+
+```
+$ hole
+Started GET "/" for 127.0.0.1 at 2010-09-10 21:07:07 +1000
+  Processing by UsersController#index as HTML
+  SQL (0.5ms)  SELECT name
+ FROM sqlite_master
+ WHERE type = 'table' AND NOT name = 'sqlite_sequence'
+  User Load (0.5ms)  SELECT "users".* FROM "users" LIMIT 15 OFFSET 0
+  SQL (1.4ms)  SELECT COUNT(*) AS count_id FROM "users"
+Rendered users/index.html.erb within layouts/application (24.8ms)
+Completed 200 OK in 51ms (Views: 32.9ms | ActiveRecord: 2.3ms)
+...
+```
+
+You can kill ```hole``` with Ctrl-C when you want to stop seeing the output. As long as ```worm``` is running the wormhole will be open and you can fire up ```hole``` again to see what is going into the ```worm``` end.
+
+You can open as many ```hole```s as you would like, at the same time, and use them however you would use the original program producing the output.
+
+```
+$ hole | grep Rendered
+Rendered users/index.html.erb within layouts/application (24.8ms)
+
+```
+Meanwhile in another shell…
+
+```
+$ hole | grep SQL
+  SQL (0.5ms)  SELECT name
+  SQL (1.4ms)  SELECT COUNT(*) AS count_id FROM "users"
+```
+
+### Named wormholes
+
+So far you can only create one wormhole at a time, with one program piping its output into ```worm```. If you open another wormhole while the previous one is still open it will stop the other one. But you might want to open more than one at a time. To do this you can give a wormhole a name and refer to it when you open the other end.
+
+```
+$ yes | worm test
+```
+This creates a wormhole with the name 'test'. Open the other end with the same name.
+
+```
+$ hole test
+y
+y
+y
+...
+```
+
+This allows you to create as many wormholes as you want, at the same time, as long as they have unique names.
+
+## Why use this?
+
+Maybe you can think of ways to use this that I have not thought of. Getting log output wherever I want it, on demand, without restarting a server was the original use case.
+
+So I use it for things like having multiple ```grep```s running on log output (as above). Or to tuck away a running server in another shell and just ```hole | grep something``` in the shell I'm working in to grab the few lines I'm looking for and Ctrl-C it away and get back to what I was doing.
+
+All of these things can probably be done in other ways with the nice UNIX tools we know and love. If you have a file being appended to you can ```tail -f``` a bunch of times and get multiple outputs of your text. You can do stuff with ```tee```. You can use named pipes and sockets (wormholes uses UNIX sockets under the hood). You can think of wormholes as a formalization of some other ad hoc techniques.
+
+## License
+
+wormholes is MIT licensed

data/Rakefile

@@ -0,0 +1,10 @@
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+
+task :default => [:test]
+
+Rake::TestTask.new do |t|
+  t.libs << 'lib'
+  t.pattern = 'test/**/*_test.rb'
+end
+

data/bin/hole

@@ -0,0 +1,43 @@
+#!/usr/bin/env ruby
+# Usage: hole [NAME]
+#
+# Opens the other end of an existing wormhole. Pipe text into worm and use hole
+# to see the text coming out in real-time.
+#
+# NAME is an optional name to give the created wormhole. If you use a name
+# with worm then use the same name with hole to open the other end of the
+# named wormhole.
+#
+# To use, pipe output to worm
+#
+#   $ output_producing_program | worm
+#
+# Then, in another shell, get the output with hole
+#
+#   $ hole
+#   <output comes out here...>
+#
+require 'optparse'
+
+OptionParser.new do |opts|
+  opts.on('-h', '--help') do
+    IO.read(__FILE__).each_line do |line|
+      break unless line =~ /^#/
+      puts line[2..-1] unless line =~ /^#!/
+    end
+    exit
+  end
+end.parse!
+
+
+require 'wormholes'
+
+opts = {}
+opts[:name] = ARGV[0] if ARGV[0]
+
+hole = Wormholes::Hole.new opts
+hole.open
+
+trap('EXIT') { hole.close }
+
+hole.listen

data/bin/worm

@@ -0,0 +1,43 @@
+#!/usr/bin/env ruby
+# Usage: worm [NAME]
+#
+# Creates a wormhole for text. Pipe text into worm and use the corresponding
+# hole utility to see the text coming out in real-time.
+#
+# NAME is an optional name to give the created wormhole. If you use a name
+# with worm then use the same name with hole to open the other end of the
+# named wormhole.
+#
+# To use, pipe output to worm
+#
+#   $ output_producing_program | worm
+#
+# Then, in another shell, get the output with hole
+#
+#   $ hole
+#   <output comes out here...>
+#
+require 'optparse'
+
+OptionParser.new do |opts|
+  opts.on('-h', '--help') do
+    IO.read(__FILE__).each_line do |line|
+      break unless line =~ /^#/
+      puts line[2..-1] unless line =~ /^#!/
+    end
+    exit
+  end
+end.parse!
+
+
+require 'wormholes'
+
+opts = {}
+opts[:name] = ARGV[0] if ARGV[0]
+
+worm = Wormholes::Worm.new opts
+worm.open
+
+trap('EXIT') { worm.close }
+
+worm.send_stream($stdin)

data/lib/wormholes.rb

@@ -0,0 +1,12 @@
+require 'wormholes/version'
+require 'wormholes/utilities'
+require 'wormholes/worm'
+require 'wormholes/hole'
+
+module Wormholes
+  NAME_REGEX = /^[\w\d_-]+$/i
+
+  def self.socket_dir
+    ENV['WORMHOLES_SOCKET_DIR'] || File.join(ENV['HOME'], '.wormholes-sockets')
+  end
+end

data/lib/wormholes/hole.rb

@@ -0,0 +1,40 @@
+require 'socket'
+
+module Wormholes
+  class Hole
+    include Utilities
+
+    attr_accessor :name
+
+    def initialize(opts={})
+      @name = opts[:name] ? test_wormhole_name(opts[:name]) : 'default'
+      @socket_file = opts[:socket_file] || File.join(::Wormholes.socket_dir, "#{@name}.sock")
+      @output_stream = opts[:output_stream] || $stdout
+      @socket = nil
+    end
+
+    def open
+      @socket = UNIXSocket.new(@socket_file)
+    end
+
+    def close
+      @socket.close
+    end
+
+    def listen
+      begin
+        while listen_for_next_line
+          # no-op
+        end
+      rescue Interrupt
+        close
+      end
+    end
+
+    def listen_for_next_line
+      line = @socket.gets
+      @output_stream.puts line
+      line
+    end
+  end
+end

data/lib/wormholes/utilities.rb

@@ -0,0 +1,16 @@
+module Wormholes
+
+  # Stuff that is needed by both ends of the wormhole
+  module Utilities
+    def test_wormhole_name(name)
+      unless proper_wormhole_name?(name)
+        raise ArgumentError, 'Wormhole name must only contain letters, numbers, hyphens, or underscores'
+      end
+      name
+    end
+
+    def proper_wormhole_name?(name)
+      NAME_REGEX =~ name
+    end
+  end
+end

data/lib/wormholes/version.rb

@@ -0,0 +1,3 @@
+module Wormholes
+  VERSION = '0.0.1'
+end

data/lib/wormholes/worm.rb

@@ -0,0 +1,103 @@
+require 'socket'
+require 'fileutils'
+
+module Wormholes
+  class Worm
+    include Utilities
+
+    attr_accessor :server, :sockets, :name
+
+    def initialize(opts={})
+      @name = opts[:name] ? test_wormhole_name(opts[:name]) : 'default'
+      @socket_file = opts[:socket_file] || File.join(::Wormholes.socket_dir, "#{@name}.sock")
+      @sockets = []
+      @server = nil
+
+      @verbose = opts[:verbose] || false
+      @debug = opts[:debug] || false
+    end
+
+    def open
+      socket_dir = File.dirname(@socket_file)
+      FileUtils.mkdir_p(socket_dir) unless File.directory?(socket_dir)
+
+      File.unlink(@socket_file) if File.exist?(@socket_file) && File.socket?(@socket_file)
+      @server = UNIXServer.new(@socket_file)
+      accept_any_connection
+      update_status
+    end
+
+    def close
+      @server.close
+      @server = nil
+      File.unlink(@socket_file) if File.exist?(@socket_file) && File.socket?(@socket_file)
+      $stderr.puts "\n...wormhole closed" if @verbose
+    end
+
+    def send_to_clients(msg)
+      disconnected_sockets = []
+      @sockets.each do |s|
+        begin
+          s.puts msg
+        rescue SystemCallError => e
+          $stderr.puts "Client disconnected: #{s}" if @debug
+          disconnected_sockets << s
+        end
+      end
+      unless disconnected_sockets.empty?
+        @sockets = @sockets - disconnected_sockets
+        debug_sockets
+        update_status
+      end
+    end
+
+    def send_stream(stream=$stdin)
+      begin
+        while line = stream.gets
+          send_to_clients(line)
+        end
+      rescue Interrupt
+        close
+      end
+    end
+
+    private
+
+    def accept_any_connection
+      $worm = self
+      Thread.new do
+        while $worm.server
+          $worm.send(:accept_connection)
+        end
+      end
+    end
+
+    def accept_connection
+      socket = @server.accept
+      add_client socket
+      update_status
+    end
+
+    def add_client(socket)
+      $stderr.puts "Client connected: #{socket.inspect}" if @debug
+      @sockets << socket
+      debug_sockets
+    end
+
+    def update_status
+      return unless @verbose
+      @previous_status ||= ''
+      @previous_status.length.times { print "\b" }
+      status = "Clients: #{sockets.size}"
+      print status
+      @previous_status = status
+    end
+
+    def debug_sockets
+      return unless @debug
+      $stderr.puts "=== Sockets ==="
+      @sockets.each {|s| $stderr.puts s.inspect}
+      $stderr.puts "==============="
+    end
+  end
+end

data/test/hole_test.rb

@@ -0,0 +1,10 @@
+require File.expand_path('../test_helper', __FILE__)
+
+class HoleTest < MiniTest::Unit::TestCase
+  def test_proper_wormhole_names_are_enforced
+    GOOD_WORMHOLE_NAMES.each {|name| Wormholes::Hole.new :name => name }
+    BAD_WORMHOLE_NAMES.each do |name|
+        assert_raises(ArgumentError) { Wormholes::Hole.new :name => name }
+    end
+  end
+end

data/test/socket_wormhole_test.rb

@@ -0,0 +1,67 @@
+require File.expand_path('../test_helper', __FILE__)
+require 'fileutils'
+require 'tmpdir'
+require 'stringio'
+
+# Test wormholes using normal UNIX domain sockets
+class SocketWormholeTest < MiniTest::Unit::TestCase
+  def setup
+    @tmp_dir = File.join( Dir.tmpdir, "wormholes-tests-#{(0...10).map{ ('a'..'z').to_a[rand(26)] }.join}")
+    Dir.mkdir(@tmp_dir)
+  end
+
+  def teardown
+    FileUtils.rm_rf @tmp_dir
+  end
+
+  def test_a_line_can_be_sent
+    test_str = "this is what we will send\n"
+    str_io = StringIO.new
+
+    ENV['WORMHOLES_SOCKET_DIR'] = @tmp_dir
+    worm = Wormholes::Worm.new
+    worm.open
+
+    socket_file = File.join(@tmp_dir, 'default.sock')
+    assert File.exist?(socket_file), 'the socket file has been created'
+    assert File.socket?(socket_file), 'the socket file is, indeed, a socket'
+
+    hole = Wormholes::Hole.new(:output_stream => str_io)
+    hole.open
+
+    sleep 0.01 while worm.sockets.size < 1
+
+    thread = Thread.new { hole.listen_for_next_line }
+    worm.send_to_clients test_str
+    thread.join
+    worm.close
+
+    assert_equal test_str, str_io.string
+  end
+
+  def test_can_use_named_wormholes
+    test_str = "we will send this through the named wormhole\n"
+    str_io = StringIO.new
+    wormhole_name = 'deep-space-9'
+
+    ENV['WORMHOLES_SOCKET_DIR'] = @tmp_dir
+    worm = Wormholes::Worm.new(:name => wormhole_name)
+    worm.open
+
+    socket_file = File.join(@tmp_dir, "#{wormhole_name}.sock")
+    assert File.exist?(socket_file), 'the socket file has been created'
+    assert File.socket?(socket_file), 'the socket file is, indeed, a socket'
+
+    hole = Wormholes::Hole.new(:name => wormhole_name, :output_stream => str_io)
+    hole.open
+
+    sleep 0.01 while worm.sockets.size < 1
+
+    thread = Thread.new { hole.listen_for_next_line }
+    worm.send_to_clients test_str
+    thread.join
+    worm.close
+
+    assert_equal test_str, str_io.string
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,7 @@
+require 'rubygems'
+require 'minitest/autorun'
+
+require File.join(File.dirname(__FILE__), *%w[.. lib wormholes])
+
+GOOD_WORMHOLE_NAMES = %w[name a johnny5 500 2 default]
+BAD_WORMHOLE_NAMES = ['', 'two words', 'weird(name)', '#name', 'myemail@aol.com']

data/test/worm_test.rb

@@ -0,0 +1,10 @@
+require File.expand_path('../test_helper', __FILE__)
+
+class WormTest < MiniTest::Unit::TestCase
+  def test_proper_wormhole_names_are_enforced
+    GOOD_WORMHOLE_NAMES.each {|name| Wormholes::Worm.new :name => name }
+    BAD_WORMHOLE_NAMES.each do |name|
+        assert_raises(ArgumentError) { Wormholes::Worm.new :name => name }
+    end
+  end
+end

data/wormholes.gemspec

@@ -0,0 +1,19 @@
+# -*- encoding: utf-8 -*-
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'wormholes/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = "wormholes"
+  gem.version       = Wormholes::VERSION
+  gem.authors       = ["Aaron Royer"]
+  gem.email         = ["aaronroyer@gmail.com"]
+  gem.description   = %q{shell utility that warps text elsewhere}
+  gem.summary       = "Pipe text (like log output) in one end and output it anywhere else."
+  gem.homepage      = "https://github.com/aaronroyer/wormholes"
+
+  gem.files         = `git ls-files`.split($/)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_paths = ["lib"]
+end

metadata

@@ -0,0 +1,68 @@
+--- !ruby/object:Gem::Specification
+name: wormholes
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Aaron Royer
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-01-27 00:00:00.000000000 Z
+dependencies: []
+description: shell utility that warps text elsewhere
+email:
+- aaronroyer@gmail.com
+executables:
+- hole
+- worm
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/hole
+- bin/worm
+- lib/wormholes.rb
+- lib/wormholes/hole.rb
+- lib/wormholes/utilities.rb
+- lib/wormholes/version.rb
+- lib/wormholes/worm.rb
+- test/hole_test.rb
+- test/socket_wormhole_test.rb
+- test/test_helper.rb
+- test/worm_test.rb
+- wormholes.gemspec
+homepage: https://github.com/aaronroyer/wormholes
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.23
+signing_key: 
+specification_version: 3
+summary: Pipe text (like log output) in one end and output it anywhere else.
+test_files:
+- test/hole_test.rb
+- test/socket_wormhole_test.rb
+- test/test_helper.rb
+- test/worm_test.rb