web-repl 0.1

data/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2014 Ari Russo
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

data/README.md

@@ -0,0 +1,66 @@
+# web-repl
+    
+This is a Javascript [REPL](http://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop) that runs in Ruby.  Evaluation is done by a web browser instance.
+
+One use of this is to control the Chrome Developer Console remotely.
+
+#### Background
+
+I was working on a toy program recently that needed the browser to be in full screen mode, which made using the regular Chrome console very difficult to use.  I came up with this program as an alternative.
+
+There are similar tools that run in nodejs for example but since my program uses a Ruby backend anyway, this is convenient for me.
+
+It communicates over websocket.
+
+There is basically no attention to security here, so please use at your own discretion.  
+
+#### Usage
+
+###### Browser
+
+To enable the browser side of this, include something like this in the head of your webpage:
+
+```html
+<script src="js/replConnection.js"></script>
+<script type="text/javascript">
+  window.onload = function() {
+    var repl = new ReplConnection("localhost", 9007, { debug: true, reconnect: true });
+    repl.start();
+  }
+</script>
+```
+
+The javascript assets for this project are located in the [/js directory](https://github.com/arirusso/web-repl/tree/master/js).
+
+There is also a full example of a webpage (with [rack](http://rack.github.io/) configuration) in the [/examples/page directory](https://github.com/arirusso/web-repl/tree/master/examples/page)
+
+###### REPL
+
+The REPL can be used either in a Ruby program/console or there is a "binary" Ruby script.
+
+In Ruby the usage looks like this:
+
+```ruby
+require "web-repl"
+
+WebRepl.start(:host => "localhost", :port => 9007)
+```
+
+You can see an explanation of background usage here.
+
+To use this as a script, run this from the command line.  (The script should install with the gem)
+
+    web-repl localhost:9007
+    
+#### Installation
+
+    gem install web-repl
+    
+or with Bundler
+
+    gem "web-repl"
+
+#### License
+
+Licensed under Apache 2.0, See the file LICENSE
+Copyright (c) 2014 [Ari Russo](http://arirusso.com) 

data/bin/web-repl

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+
+require "optparse"
+require "web-repl"
+
+ARGV[0]
+
+raise OptionParser::MissingArgument if ARGV[0].nil?
+
+host, port = *ARGV[0].scan(/(\w+):(\d{4,})/)[0]
+
+raise OptionParser::MissingArgument if host.nil? || port.nil?
+
+WebRepl.start(:host => host, :port => port)
+exit 0

data/js/replConnection-0.1.min.js

@@ -0,0 +1 @@
+function ReplConnection(e,t,n){if(n===null){n={}}this.debug=!!n.debug;this.reconnect=!!n.reconnect;this.retryTime=n.retryTime||1e3;this.onReceive=n.onReceive;this.host=e;this.port=t;this.active=false;this.socket;this.supported="WebSocket"in window;if(this.supported){console.log("REPL: socket ok")}else{console.log("REPL: socket not supported")}}ReplConnection.prototype.eval=function(statement){response={};try{response.value=eval(statement)}catch(err){response.error=err.message}return response};ReplConnection.prototype.initSocket=function(e){if(this.socket!==undefined&&this.socket!==null){this.socket.close()}var t="ws://"+this.host+":"+this.port+"/echo";this.socket=new WebSocket(t);e()};ReplConnection.prototype.handleSocketOpen=function(){this.active=true;console.log("REPL: socket ready")};ReplConnection.prototype.tryConnection=function(){console.log("REPL: waiting for connection");if(this.reconnect){var e=this;window.setTimeout(function(){e.start()},this.retryTime)}};ReplConnection.prototype.handleSocketClose=function(e){if(!this.active){this.tryConnection()}else{console.log("REPL: socket closed");this.active=false;if(this.reconnect){this.tryConnection()}}};ReplConnection.prototype.handleMessageReceived=function(e){if(this.debug){console.log("REPL: message received");console.log(e)}var t=JSON.parse(e.data);var n=t.timestamp;t.timestamp=new Date(n);if(this.onReceive!==undefined){this.onReceive(t)}var r=this.eval(t.statement);r.timestamp=(new Date).getTime();var i=JSON.stringify(r);if(this.debug){console.log("REPL: replying ");console.log(r)}this.socket.send(i)};ReplConnection.prototype.initEventHandling=function(){var e=this;this.socket.onopen=function(){e.handleSocketOpen()};this.socket.onclose=function(t){e.handleSocketClose(t)};this.socket.onmessage=function(t){e.handleMessageReceived(t)}};ReplConnection.prototype.start=function(e){if(this.supported){var t=this;this.initSocket(function(){t.initEventHandling();if(e!==undefined){e(t)}})}}

data/js/replConnection.js

@@ -0,0 +1,117 @@
+// A connection to the REPL server using Websocket
+function ReplConnection(host, port, options) {
+  if (options === null) {
+    options = {};
+  }
+  this.debug = !!options.debug;
+  this.reconnect = !!options.reconnect;
+  this.retryTime = options.retryTime || 1000;
+  this.onReceive = options.onReceive;
+  this.host = host;
+  this.port = port;
+  this.active = false;
+  this.socket;
+  this.supported = ("WebSocket" in window);
+  if (this.supported) {
+    console.log("REPL: socket ok");
+  } else {
+    console.log("REPL: socket not supported");
+  }
+}
+
+// This is the "eval" for the REPL
+ReplConnection.prototype.eval = function(statement) {
+  response = {}
+  try {
+    response.value = eval(statement);
+  } catch(err) {
+    response.error = err.message;
+  }
+  return response;
+}
+
+// Initialize the Websocket connection
+ReplConnection.prototype.initSocket = function(successCallback) {
+  if (this.socket !== undefined && this.socket !== null) { 
+    this.socket.close();
+  }
+  var address = "ws://" + this.host + ":" + this.port + "/echo";
+  this.socket = new WebSocket(address);
+  successCallback();
+}
+
+// To be run when the Websocket registers as being open
+ReplConnection.prototype.handleSocketOpen = function() {
+  this.active = true;
+  console.log("REPL: socket ready");
+}
+
+// Try to create a Websocket connection
+ReplConnection.prototype.tryConnection = function() {
+  console.log("REPL: waiting for connection");
+  if (this.reconnect) {
+    var connection = this;
+    window.setTimeout(function() {
+      connection.start();
+    }, this.retryTime);
+  }
+}
+
+// To be run when the Websocket registers as being closed.  This includes when it's waiting for a connection.
+ReplConnection.prototype.handleSocketClose = function(event) {
+  if (!this.active) {
+    this.tryConnection();  
+  } else {  
+    console.log("REPL: socket closed"); 
+    this.active = false;
+    if (this.reconnect) {
+      this.tryConnection();
+    }
+  }
+}
+
+// To be run when the Websocket registers an event over the connection.
+ReplConnection.prototype.handleMessageReceived = function(event) {
+  if (this.debug) {
+    console.log("REPL: message received");
+    console.log(event);
+  }
+  var message = JSON.parse(event.data);
+  // turn the timestamp from the rec'd message into a real date
+  var timestamp = message.timestamp;
+  message.timestamp = new Date(timestamp); 
+  //
+  if (this.onReceive !== undefined) {
+    this.onReceive(message); // fire the custom callback
+  }
+  // prepare the response
+  var response = this.eval(message.statement); // evaluate the statement
+  response.timestamp = new Date().getTime(); // timestamp for the returned message
+  var json = JSON.stringify(response);
+  if (this.debug) {
+    console.log("REPL: replying ");
+    console.log(response);
+  }
+  this.socket.send(json);
+}
+
+// Initialize the Websocket event handling actions
+ReplConnection.prototype.initEventHandling = function() {
+  var connection = this;
+  this.socket.onopen = function() { connection.handleSocketOpen() };
+  this.socket.onclose = function(event) { connection.handleSocketClose(event); };
+  this.socket.onmessage = function(event) { connection.handleMessageReceived(event); };
+}
+
+// Initialize the Websocket and start waiting for a REPL connection
+ReplConnection.prototype.start = function(successCallback) {
+  if (this.supported) {
+    var connection = this;
+    this.initSocket(function() {
+      connection.initEventHandling();
+      if (successCallback !== undefined) {
+        successCallback(connection);
+      }
+    });
+  }
+}

data/lib/web-repl.rb

@@ -0,0 +1,22 @@
+# libs
+require "colorize"
+require "em-websocket"
+require "json"
+require "readline"
+require "socket"
+
+# classes
+require "web-repl/messager"
+require "web-repl/patch"
+require "web-repl/repl"
+
+module WebRepl
+
+  VERSION = "0.1"
+
+  # Shortcut to REPL.start
+  def self.start(*a)
+    REPL.start(*a)
+  end
+
+end

data/lib/web-repl/messager.rb

@@ -0,0 +1,48 @@
+module WebRepl
+
+  # Handles sending and receiving messages to/from the socket
+  class Messager
+ 
+    # @param [EventMachine::WebSocket] socket
+    # @param [Hash] options
+    # @option options [Boolean] :debug
+    def initialize(socket, options = {})
+      @socket = socket
+      @debug = options[:debug]
+    end
+
+    # Handle an inputted message
+    # @param [String] raw_message A raw inputted JSON message
+    # @return [Hash]
+    def in(raw_message, &block)
+      hash = JSON.parse(raw_message, :symbolize_names => true)
+      hash[:timestamp] = Time.at(hash[:timestamp].to_i / 1000) if !hash[:timestamp].nil?
+      yield(hash) if block_given?
+      hash
+    end
+
+    # Generate a new timestamp in js format
+    # @return [Fixnum]
+    def new_timestamp
+      Time.now.to_i * 1000 # javascript time int format
+    end
+
+    # Send a message over the socket
+    # @param [Hash] message A message to send
+    # @return [String, nil] If a message was sent, its JSON string; otherwise nil
+    def out(message)
+      if !@socket.nil?
+        message[:timestamp] ||= new_timestamp
+        json = message.to_json
+        @debug.puts "Sending message: #{json}" if @debug
+        @socket.send(json)
+        json
+      else
+        @debug.puts "Warning: No connection" if @debug
+        nil
+      end
+    end
+
+  end
+
+end

data/lib/web-repl/patch.rb

@@ -0,0 +1,39 @@
+# Patch EventMachine::WebSocket so that we can initialize EM on demand.  This is useful when 
+# having multiple EMs working.  It won't error out by calling EM.run repeatedly.
+#
+module EventMachine
+  module WebSocket
+    def self.start(options = {}, &block)
+      EM.epoll
+      if EM.reactor_running?
+        handle_start(options, &block)
+      else
+        EM.run { handle_start(options, &block) }
+      end
+    end
+
+    def self.run(options = {}, &block)
+      if EM.reactor_running?
+        handle_run(options, &block)
+      else
+        EM.run { handle_run(options, &block) }
+      end      
+    end
+
+    private
+
+    def self.handle_run(options = {}, &block)
+      host, port = options.values_at(:host, :port)
+      EM.start_server(host, port, Connection, options) do |c|
+        yield c
+      end
+    end
+
+    def self.handle_start(options = {}, &block)
+      trap("TERM") { stop }
+      trap("INT")  { stop }
+      run(options, &block)
+    end
+
+  end
+end

data/lib/web-repl/repl.rb

@@ -0,0 +1,128 @@
+module WebRepl
+
+  # The main REPL object
+  class REPL
+
+    attr_reader :thread
+
+    # Start a repl connection
+    # @param [Hash] config A hash of config options to be passed to EM::WebSocket.run directly
+    # @param [Hash] options
+    # @option options [IO, nil] :debug A debug logger or nil if debug is not needed (default: nil)
+    # @option options [Boolean] :background Do not wait for input, just run in the bg
+    # @return [WebRepl::REPL]
+    def self.start(config, options = {})
+      new(config, options).tap { |repl| repl.start(options) }
+    end
+
+    # @param [Hash] config A hash of config options to be passed to EM::WebSocket.run directly
+    # @param [Hash] options
+    # @option options [IO, nil] :debug A debug logger or nil if debug is not needed (default: nil)
+    def initialize(config, options = {})
+      @config = config
+      @socket = nil
+      @messager = nil
+      @buffer = []
+      @debug = options[:debug]
+    end
+
+    # Send a statement to the browser for evaluation
+    # @param [Fixnum, String] statement A Javascript statement to be evaluated
+    # @return [String, nil] The data that was sent to the browser, or nil if sending could not be completed. 
+    def evaluate(statement)
+      @messager.out({ :statement => statement }) unless @messager.nil?
+    end
+
+    # Prompt the Ruby user for input and send that input to the browser for evaluation (blocking)
+    # @return [String, nil] The data that was sent to the browser, or nil if sending could not be completed
+    def gets
+      line = Readline.readline('> ', true)
+      return nil if line.nil?
+      if line =~ /^\s*$/ or Readline::HISTORY.to_a[-2] == line
+        Readline::HISTORY.pop
+      end      
+      statement = line.strip
+      case statement
+      when "exit" then exit
+      else
+        evaluate(statement)
+      end
+    end
+
+    # Wait for a response from the browser
+    def wait_for_response
+      loop until !@buffer.empty?
+    end
+
+    # Start the Websocket connection (blocking)
+    # @param [Hash] options
+    # @option options [Boolean] :background Do not wait for input, just run in the bg
+    def start(options = {}, &block)
+      @thread = Thread.new do
+        EM::WebSocket.run(@config) do |ws|
+          if @socket.nil?
+            @socket = ws
+            @messager = Messager.new(@socket)
+            configure_event_handling(:background => options[:background], &block)
+          end
+        end
+      end
+      acknowledge_handshake do
+        yield if block_given?
+        gets unless !!options[:background]
+      end
+      @thread.join unless !!options[:background]
+    end
+
+    # Execute a block when a connection is made
+    # @return [TrueClass]
+    def acknowledge_handshake(&block)
+      Thread.new do
+        loop until !@handshake.nil?
+        yield
+      end
+    end
+
+    # Close the REPL
+    def close
+      @socket.close unless @socket.nil?
+      @thread.kill unless @thread.nil?
+    end
+
+    private
+
+    def handle_open(handshake, options = {})
+      puts "web-repl: Connection open"
+      @handshake = handshake
+    end
+
+    def handle_close
+      puts "web-repl: Connection closed"
+      @handshake = nil
+    end
+
+    def handle_message_received(raw_message, options = {})
+      @messager.in(raw_message) do |message|
+        @buffer.clear
+        @buffer << message
+        keys = { :error => :red, :value => :white }
+        text = nil
+        keys.each do |k,v| 
+          text ||= message[k].to_s.send(v) unless message[k].nil?
+        end
+        puts(text)
+      end
+      gets unless !!options[:background]
+    end
+
+    # Configure the Websocket event handling
+    # @param [Hash] options
+    # @option options [Boolean] :background Do not wait for input, just run in the bg
+    def configure_event_handling(options = {})
+      @socket.onopen { |handshake| handle_open(handshake) }
+      @socket.onclose { handle_close }
+      @socket.onmessage { |raw_message| handle_message_received(raw_message) }
+    end
+
+  end
+end

data/test/helper.rb

@@ -0,0 +1,8 @@
+dir = File.dirname(File.expand_path(__FILE__))
+$LOAD_PATH.unshift dir + '/../lib'
+
+require 'test/unit'
+require "mocha/test_unit"
+require "shoulda-context"
+
+require "web-repl"

data/test/messager_test.rb

@@ -0,0 +1,88 @@
+require "helper"
+
+class WebRepl::MessagerTest < Test::Unit::TestCase
+
+  include WebRepl
+
+  context "Messager" do
+
+    setup do
+      @socket = Object.new
+      @messager = Messager.new(@socket)
+    end
+
+    context "#in" do
+
+      setup do
+        @message = { :value => "blah", :timestamp => 1396406728702 }.to_json
+        @result = @messager.in(@message)
+      end
+
+      should "convert from String to Hash" do
+        assert_not_nil @result
+        assert_equal Hash, @result.class
+        assert_equal "blah", @result[:value]
+      end
+
+      should "convert timestamp from js time to ruby" do
+        timestamp = @result[:timestamp]
+        assert_not_nil timestamp
+        assert_equal Time, timestamp.class
+        assert_equal 2014, timestamp.year
+        assert_equal 4, timestamp.month
+        assert_equal 22, timestamp.hour
+      end
+      
+    end
+
+    context "#new_timestamp" do
+
+      should "be js int time format" do
+        result = @messager.new_timestamp
+        assert_not_nil result
+        assert_equal Fixnum, result.class
+        assert result.to_s.size > Time.new.to_i.to_s.size
+        assert_equal (result / 1000).to_s.size, Time.new.to_i.to_s.size
+      end
+
+    end
+
+    context "#out" do
+
+      setup do
+        @message = { :statement => "something" }
+      end
+
+      should "not overwrite timestamp" do
+        @socket.expects(:send).once
+        ts = Time.now.to_i / 1000
+        @message[:timestamp] = ts
+        @messager.out(@message)
+        assert_equal ts, @message[:timestamp]
+      end
+
+      should "generate new timestamp" do
+        @socket.expects(:send).once
+        @messager.out(@message)
+        assert_not_nil @message[:timestamp]
+        assert_equal Fixnum, @message[:timestamp].class
+      end
+
+      should "return nil if fails" do
+        messager = Messager.new(nil)
+        result = messager.out(@message)
+        assert_nil result
+      end
+
+      should "return json string if success" do
+        @socket.expects(:send).once
+        result = @messager.out(@message)
+        assert_not_nil result
+        assert_equal String, result.class
+      end
+
+    end
+
+  end
+
+end

data/test/repl_test.rb

@@ -0,0 +1,14 @@
+require "helper"
+
+class WebRepl::ReplTest < Test::Unit::TestCase
+
+  include WebRepl
+
+  context "Repl" do
+
+    # TODO
+    #
+  end
+
+end
+

metadata

@@ -0,0 +1,140 @@
+--- !ruby/object:Gem::Specification
+name: web-repl
+version: !ruby/object:Gem::Version
+  version: '0.1'
+  prerelease: 
+platform: ruby
+authors:
+- Ari Russo
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-04-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: colorize
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: em-websocket
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: mocha
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: shoulda-context
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Javascript/Web REPL in Ruby
+email:
+- ari.russo@gmail.com
+executables:
+- web-repl
+extensions: []
+extra_rdoc_files: []
+files:
+- bin/web-repl
+- js/replConnection-0.1.min.js
+- js/replConnection.js
+- lib/web-repl/messager.rb
+- lib/web-repl/patch.rb
+- lib/web-repl/repl.rb
+- lib/web-repl.rb
+- test/helper.rb
+- test/messager_test.rb
+- test/repl_test.rb
+- LICENSE
+- README.md
+homepage: http://github.com/arirusso/web-repl
+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: 1.3.6
+requirements: []
+rubyforge_project: web-repl
+rubygems_version: 1.8.25
+signing_key: 
+specification_version: 3
+summary: Javascript/Web REPL in Ruby
+test_files:
+- test/messager_test.rb
+- test/repl_test.rb