simultaneous 0.2.0

data/lib/simultaneous/rack.rb

@@ -0,0 +1,83 @@
+# encoding: UTF-8
+
+require 'rack/async'
+
+module Simultaneous
+  module Rack
+    # A Rack handler that allows you to create a HTML5 Server-Sent Events
+    # endpoint. Relies on EventMachine to easily handle multiple
+    # open connections simultaneously
+    #
+    # To use, first create an instance of the EventSource class:
+    #
+    #   messenger = Simultaneous::Rack::EventSource.new
+    #
+    # Then map this onto a URL in your application, e.g. in a RackUp file
+    #
+    #   app = ::Rack::Builder.new do
+    #     map "/messages" do
+    #       run messenger.app
+    #     end
+    #   end
+    #   run app
+    #
+    # In your web-page, set up an EventSource using the new APIs
+    #
+    #   source = new EventSource('/messages');
+    #   source.addEventListener('message', function(e) {
+    #     alert(e.data);
+    #   }, false);
+    #
+    #
+    # Then when you want to send a messages to all your clients you
+    # use your (Ruby) EventSource instance like so:
+    #
+    #   messenger.deliver("Hello!")
+    #
+    # IMPORTANT:
+    #
+    # This will only work when run behind Thin or some other, EventMachine
+    # driven webserver. See <https://github.com/matsadler/rack-async> for more
+    # info.
+    #
+    class EventSource
+
+      def initialize
+        @lock = Mutex.new
+        @timer = nil
+        @clients = []
+      end
+
+      def app
+        ::Rack::Async.new(self)
+      end
+
+      def call(env)
+        stream = env['async.body']
+        stream.errback { cleanup!(stream) }
+
+        @lock.synchronize { @clients << stream }
+
+        [200, {"Content-type" => "text/event-stream"}, stream]
+      end
+
+      def deliver_event(event)
+        send(event.to_sse)
+      end
+
+      def deliver(data)
+        send("data: #{data}\n\n")
+      end
+
+      private
+
+      def send(message)
+        @clients.each { |client| client << message }
+      end
+
+        def cleanup!(connection)
+          @lock.synchronize { @clients.delete(connection) }
+        end
+      end
+    end
+  end

data/lib/simultaneous/server.rb

@@ -0,0 +1,74 @@
+# encoding: UTF-8
+
+require 'eventmachine'
+
+module Simultaneous
+  class Server < EM::Connection
+
+    def self.channel
+      @channel ||= EM::Channel.new
+    end
+
+    def self.start(connection_string = Simultaneous.connection, options = {})
+      Simultaneous.connection = connection_string
+      connection = Simultaneous::Connection.new(connection_string, options)
+      @server = connection.start_server(self)
+    end
+
+
+    def self.broadcast(data)
+      channel << data
+    end
+
+    def self.receive_data(data)
+      command = Simultaneous::Command.load(data)
+      run(command)
+    end
+
+    def self.run(command)
+      if Command.allowed?(command)
+        puts command.debug if $debug
+        command.run
+      else
+        raise PermissionsError, "'#{command.class}' is not an approved command"
+      end
+    end
+
+    def self.set_pid(task_name, pid)
+      pids[task_name] = pid.to_i
+    end
+
+    def self.get_pid(task)
+      pids[task.name]
+    end
+
+    def self.pids
+      @pids ||= {}
+    end
+
+    def self.kill(task_name, signal="TERM")
+      pid = pids[task_name]
+      Process.kill(signal, pid) unless pid == 0
+    end
+
+    def self.task_complete(task_name)
+      pid = pids.delete(task_name)
+    end
+
+    def channel
+      Simultaneous::Server.channel
+    end
+
+    def post_init
+      @sid = channel.subscribe { |m| send_data "#{m}\n" }
+    end
+
+    def receive_data(data)
+      Simultaneous::Server.receive_data(data)
+    end
+
+    def unbind
+      channel.unsubscribe @sid if @sid
+    end
+  end
+end

data/lib/simultaneous/task.rb

@@ -0,0 +1,37 @@
+module Simultaneous
+  module Task
+
+    def self.task_name
+      ENV[Simultaneous::ENV_TASK_NAME]
+    end
+
+    def self.pid
+      $$
+    end
+
+    def self.included(klass)
+      Simultaneous.client = Simultaneous::TaskClient.new
+      Simultaneous.set_pid(self.task_name, pid) if task_name
+      at_exit {
+        begin
+          Simultaneous.task_complete(self.task_name)
+        rescue Errno::ECONNREFUSED
+        rescue Errno::ENOENT
+        end
+
+      # Simultaneous.client.close
+      }
+    rescue Errno::ECONNREFUSED
+    rescue Errno::ENOENT
+      # server isn't running but we don't want this to stop our script
+    end
+
+
+    def simultaneous_event(event, message)
+      Simultaneous.send_event(event, message)
+    rescue Errno::ECONNREFUSED
+    rescue Errno::ENOENT
+      # server isn't running but we don't want this to stop our script
+    end
+  end
+end

data/lib/simultaneous/task_client.rb

@@ -0,0 +1,37 @@
+# encoding: UTF-8
+
+require 'socket'
+
+module Simultaneous
+  class TaskClient
+    attr_reader :domain
+
+    def initialize(domain = Simultaneous.domain, connection_string=Simultaneous.connection)
+      @domain = domain
+      @connection = Simultaneous::Connection.new(connection_string)
+    end
+
+    def run(command)
+      command.domain = self.domain
+      send(command.dump)
+    end
+
+    def send(command)
+      connect do |connection|
+        connection.send(command, 0)
+      end
+    end
+
+    def connect
+      @connection.sync_socket do |socket|
+        yield(socket)
+      end
+    end
+
+    def close
+    end
+
+    def on_event(event)
+    end
+  end
+end

data/lib/simultaneous/task_description.rb

@@ -0,0 +1,37 @@
+# encoding: UTF-8
+
+module Simultaneous
+  class TaskDescription
+    attr_reader :name, :binary, :options, :params, :env
+
+    # options:
+    #   :nice
+    #   :logfile - defaults to PWD/log/task_name.log
+    #
+    #
+    # name, path_to_binary, options, default_parameters, env
+    def initialize(name, path_to_binary, options={}, default_parameters={}, env={})
+      @name, @binary, @params, @options, @env = name, path_to_binary, default_parameters, options, env
+    end
+
+    def niceness
+      (options[:nice] || options[:niceness] || 0)
+    end
+
+    def logfile
+      (options[:logfile] || options[:log] || default_log_file)
+    end
+
+    def pwd
+      (options[:pwd] || default_pwd)
+    end
+
+    def default_log_file
+      File.expand_path(File.join(Dir.pwd, "log", "#{name}-task.log"))
+    end
+
+    def default_pwd
+      "/"
+    end
+  end
+end

data/lib/simultaneous.rb

@@ -0,0 +1,265 @@
+# encoding: UTF-8
+
+require 'socket'
+require 'eventmachine'
+
+module Simultaneous
+  VERSION = "0.2.0"
+
+  DEFAULT_CONNECTION = "/tmp/simultaneous-server.sock"
+  DEFAULT_PORT = 9999
+  DEFAULT_HOST = 'localhost'
+
+  ENV_CONNECTION = "SIMULTANEOUS_CONNECTION"
+  ENV_DOMAIN = "SIMULTANEOUS_DOMAIN"
+  ENV_TASK_NAME = "SIMULTANEOUS_TASK_NAME"
+
+  class Error < ::StandardError; end
+  class PermissionsError < Error; end
+  class FileNotFoundError < Error; end
+
+  module ClassMethods
+
+    def server_binary
+      File.expand_path("../../bin/simultaneous-server", __FILE__)
+    end
+
+    # Registers a task and makes it available for easy launching using #fire
+    #
+    # @param [Symbol] task_name
+    #   the name for the task. This should be unique
+    #
+    # @param [String] path_to_binary
+    #   the path to the executable that should be run when this task is launched
+    #
+    # @param [Hash] options
+    #   A hash of options for the task. Available options are:
+    #     :niceness: the niceness value of the process, >=0
+    #     :logfile:  the location of the processes log file to which all io will be redirected
+    #     :pwd:      directory that the task should work in
+    #
+    # @param [Fixnum] niceness
+    #   the niceness value of the process >= 0. The higher this value the 'nicer' the launched
+    #   process will be (a high nice value results in a low priority task).
+    #   On UNIX systems the max, nicest, value is 20
+    #
+    # @param [Hash] default_params
+    #   A Hash of parameters that should be passed to every invocation of the task.
+    #   These will be converted to command line parameters
+    #     { "setting" => "value", "output" => "destination"}
+    #   gives the parameters
+    #     --setting=value --output=destination
+    #   @see Simultaneous::Utilities#to_arguments
+    #
+    # @param [Hash] env
+    #   A Hash of values to add to the task's ENV settings
+    #
+    def add_task(task_name, path_to_binary, options={}, default_params={}, env={})
+      tasks[task_name] = TaskDescription.new(task_name, path_to_binary, options, default_params, env)
+    end
+
+    # Launches the given task
+    #
+    # @param [Symbol] task_name the name of the task to launch
+    # @param [Hash] params parameters to pass to the executable
+    def fire(task_name, params={})
+      task = tasks[task_name]
+      command = Command::Fire.new(task, params)
+      client.run(command)
+    end
+
+    def client=(client)
+      @client.close if @client
+      @client = client
+    end
+
+    def client
+      @client ||= \
+        begin
+          client = \
+            if ::EM.reactor_running?
+              Client.new(domain, connection)
+            else
+              TaskClient.new(domain, connection)
+            end
+          # make sure that new client is hooked into all listeners
+          event_listeners.each do |event, blocks|
+            blocks.each do |block|
+              client.on_event(event, &block)
+            end
+          end
+          client
+        end
+    end
+
+    def event_listeners
+      @event_listeners ||= Hash.new { |hash, key| hash[key] = [] }
+    end
+
+    def on_event(event, &block)
+      event_listeners[event] << block
+      client.on_event(event, &block) if client
+    end
+
+    def reset_client!
+      @client = nil
+    end
+
+    def reset!
+      reset_client!
+      @tasks = nil
+    end
+
+    # Returns the path to the binary for the given task
+    #
+    # @param [Symbol] task_name the name of the task
+    # @return [String] the path of the task's binary
+    def binary(task_name)
+      tasks[task_name].binary
+    end
+
+    # Gets the TaskDescription of a task
+    #
+    # @param [Symbol] task_name the name of the task to get
+    def [](task_name)
+      tasks[task_name]
+    end
+
+    def tasks
+      @tasks ||= {}
+    end
+
+    def connection=(connection)
+      reset_client!
+      @connection = connection
+    end
+
+    def domain=(domain)
+      reset_client!
+      @domain = domain
+    end
+
+    def connection
+      @connection ||= (ENV[Simultaneous::ENV_CONNECTION] || Simultaneous::DEFAULT_CONNECTION)
+    end
+
+    def domain
+      @domain ||= (ENV[Simultaneous::ENV_DOMAIN] || "domain#{$$}")
+    end
+
+    # Used by the {Simultaneous::Daemon} module to set the correct PID for a given task
+    def map_pid(task_name, pid)
+      command = Command::SetPid.new(task_name, pid)
+      client.run(command)
+    end
+
+    alias_method :set_pid, :map_pid
+
+    def send_event(event, data)
+      command = Command::ClientEvent.new(domain, event, data)
+      client.run(command)
+    end
+
+    # Sends a running task the TERM signal
+    def term(task_name)
+      kill(task_name, "TERM")
+    end
+
+    # Sends a running task the INT signal
+    def int(task_name)
+      kill(task_name, "INT")
+    end
+
+    # Sends a running task an arbitrary signal
+    #
+    # @param [Symbol] task_name the name of the task to send the signal
+    # @param [String] signal the signal to send
+    #
+    # @see Signal#list for a full list of signals available
+    def kill(task_name, signal="TERM")
+      command = Command::Kill.new(task_name, signal)
+      client.run(command)
+    end
+
+    def task_complete(task_name)
+      command = Command::TaskComplete.new(task_name)
+      client.run(command)
+    end
+
+    def to_arguments(params={})
+      params.keys.sort { |a, b| a.to_s <=> b.to_s }.map do |key|
+        %(--#{key}=#{to_parameter(params[key])})
+      end.join(" ")
+    end
+
+    # Maps objects to command line parameters suitable for parsing by Thor
+    # @see https://github.com/wycats/thor
+    def to_parameter(obj)
+      case obj
+      when String
+        obj.inspect
+      when Array
+        obj.map { |o| to_parameter(o) }.join(' ')
+      when Hash
+        obj.map do |k, v|
+          "#{k}:#{to_parameter(obj[k])}"
+        end.join(' ')
+      when Numeric
+        obj
+      else
+        to_parameter(obj.to_s)
+      end
+    end
+
+    TCP_CONNECTION_MATCH = %r{^([^/]+):(\d+)}
+    # Convert connection string into an argument array suitable for passing
+    # to EM.connect or EM.server
+    # e.g.
+    #   "/path/to/socket.sock" #=> ["/path/to/socket.sock"]
+    #   "localhost:9999" #=> ["localhost", 9999]
+    #
+    def parse_connection(connection_string)
+      if connection_string =~ TCP_CONNECTION_MATCH
+        [$1, $2.to_i]
+      else
+        [connection_string]
+      end
+    end
+
+    def client_connection(connection_string)
+      if connection_string =~ TCP_CONNECTION_MATCH
+        TCPSocket.new($1, $2.to_i)
+      else
+        UNIXSocket.new(connection_string)
+      end
+    end
+
+    protected
+
+    # Catch method missing to enable launching of tasks by direct name
+    # e.g.
+    #   Simultaneous.add_task(:process_things, "/usr/bin/process")
+    # launch this task:
+    #   Simultaneous.process_things
+    #
+    def method_missing(method, *args, &block)
+      if tasks.key?(method)
+        fire(method, *args, &block)
+      else
+        super
+      end
+    end
+  end
+
+  extend ClassMethods
+
+  autoload :Connection,       "simultaneous/connection"
+  autoload :Server,           "simultaneous/server"
+  autoload :Client,           "simultaneous/client"
+  autoload :TaskClient,       "simultaneous/task_client"
+  autoload :Task,             "simultaneous/task"
+  autoload :TaskDescription,  "simultaneous/task_description"
+  autoload :BroadcastMessage, "simultaneous/broadcast_message"
+  autoload :Command,          "simultaneous/command"
+  autoload :Rack,             "simultaneous/rack"
+end