pry-remote-em 0.4.0 → 0.4.1

data/README.md

@@ -1,12 +1,14 @@
-# What is it?
-
-A way to start Pry remotely in EventMachine and to connect to it. This provides access to the state of the running program from anywhere.
+[PryRemoteEm](https://rubygems.org/gems/pry-remote-em) enables you to
+start instances of Pry in a running
+[EventMachine](http://rubyeventmachine.com/) program and connect to
+those Pry instances over a network or the Internet. Once connected you
+can interact with the internal state of the program.
 
 It's based off of [Mon-Ouie's](https://github.com/Mon-Ouie) [pry-remote](https://github.com/Mon-Ouie/pry-remote) for DRb.
 
-# Compatibility
-
-  MRI 1.9 or any other VM with support for Fibers is required.
+It adds user authentication and SSL support along with tab-completion
+and paging. It's compatble with MRI 1.9, or any other VM with support
+for Fibers and EventMachine.
 
 
 # Installation
@@ -78,23 +80,103 @@ You can then connect to the pry session using ``pry-remote-em``:
 
 # Features
 
+## Multiple Servers
+
+It's easy to run more than one PryRemoteEm service on a single machine,
+or even in the same process. When you start the service via
+*#remote_pry_em*, just specify *:auto* as the port to use. The service
+will automatically take the next free port from 6462.
+
+```ruby
+require "pry-remote-em/server"
+
+os     = ObjectSpace.each_object
+expose = []
+while expose.length < 5
+  o = os.next
+  expose.push(o) unless o.frozen?
+end
+
+EM.run {
+  expose.each {|o| o.remote_pry_em('localhost', :auto) }
+}
+```
+
+    $ ruby test/auto-demo.rb
+    [pry-remote-em] listening for connections on pryem://localhost:6462/
+    [pry-remote-em] listening for connections on pryem://localhost:6463/
+    [pry-remote-em] listening for connections on pryem://localhost:6464/
+    [pry-remote-em] listening for connections on pryem://localhost:6465/
+    [pry-remote-em] listening for connections on pryem://localhost:6466/
+
+```shell
+$ pry-remote-em
+[pry-remote-em] client connected to pryem://127.0.0.1:6462/
+[pry-remote-em] remote is PryRemoteEm 0.4.0 pryem
+[1] pry("pretty_print")> 
+
+$ pry-remote-em  pryem://127.0.0.1:6463/
+[pry-remote-em] client connected to pryem://127.0.0.1:6463/
+[pry-remote-em] remote is PryRemoteEm 0.4.0 pryem
+[1] pry("pack")> 
+
+$ pry-remote-em  pryem://127.0.0.1:6464/
+[pry-remote-em] client connected to pryem://127.0.0.1:6464/
+[pry-remote-em] remote is PryRemoteEm 0.4.0 pryem
+[1] pry("to_json")>
+
+$ pry-remote-em  pryem://127.0.0.1:6465/
+[pry-remote-em] client connected to pryem://127.0.0.1:6465/
+[pry-remote-em] remote is PryRemoteEm 0.4.0 pryem
+[1] pry("to_json")> 
+
+$ pry-remote-em  pryem://127.0.0.1:6466/
+[pry-remote-em] client connected to pryem://127.0.0.1:6466/
+[pry-remote-em] remote is PryRemoteEm 0.4.0 pryem
+[1] pry(#<RubyVM::InstructionSequence>)> 
+```
+
 ## TLS Encryption
   
-  When creating a server pass the :tls => true option to enable TLS. If
-you pass a Hash, e.g. ``:tls => {:private_key_file => '/tmp/server.key'}`` it will be used to configure the internal TLS handler. 
-  See [EventMachine::Connection#start_tls](http://eventmachine.rubyforge.org/EventMachine/Connection.html#M000296) for the available options.
+When creating a server pass the :tls => true option to enable TLS. 
+
+```ruby
+obj.remote_pry_em('localhost', :auto, :tls => true)
+```
+
+If you pass a Hash it will be used to configure the internal TLS handler. 
+
+```ruby
+obj.remote_pry_em('localhost', :auto, :tls => {:private_key_file => '/tmp/server.key'})
+``` 
+See [EventMachine::Connection#start_tls](http://eventmachine.rubyforge.org/EventMachine/Connection.html#M000296) for the available options.
+
+
+When the command line client connects to a TLS enabled server it will
+automatically use TLS mode even if the user didn't request it.
 
- To start the command line client in TLS mode pass it a pryems URL instead of a pryem URL.
+```bash
+$ pry-remote-em pryem://localhost:6462/
+[pry-remote-em] client connected to pryem://127.0.0.1:6462/
+[pry-remote-em] remote is PryRemoteEm 0.4.0 pryems
+[pry-remote-em] negotiating TLS
+[pry-remote-em] TLS connection established
+[1] pry(#<Hash>)> 
+```
+
+To always require a TLS connection give pry-remote-em a pryem*s* URL. If
+the server doesn't support TLS the connection will be terminated.
 
 ```bash
-  $ bin/pry-remote-em pryems:///
-  [pry-remote-em] client connected to pryem://127.0.0.1:6462/
-  [pry-remote-em] remote is PryRemoteEm 0.2.0 pryems
-  [pry-remote-em] negotiating TLS
-  [pry-remote-em] TLS connection established
-  [1] pry(#<Hash>)> 
+$ pry-remote-em pryems://localhost:6468/
+[pry-remote-em] client connected to pryem://127.0.0.1:6468/
+[pry-remote-em] remote is PryRemoteEm 0.4.0 pryem
+[pry-remote-em] connection failed
+[pry-remote-em] server doesn't support required scheme "pryems"
+[pry-remote-em] session terminated
 ```
 
+
 ## User Authentication
 
 ### Server
@@ -114,9 +196,9 @@ EM.run{
 
 #### Auth with a lambda
 ```ruby
-require ‘net/ldap’
+require 'net/ldap'
 ldap_anon = lambda do |user, pass|
-  ldap = Net::LDAP.new :host => “10.0.0.1”, :port => 389, :auth => {:method => :simple, :username => user, :password => pass}
+  ldap = Net::LDAP.new :host => '10.0.0.1', :port => 389, :auth => {:method => :simple, :username => user, :password => pass}
   ldap.bind
 end
 obj       = {:encoding => __ENCODING__, :weather => :cloudy}

data/lib/pry-remote-em/client.rb

@@ -55,7 +55,10 @@ module PryRemoteEm
     def receive_json(j)
       if j['p'] # prompt
         if @negotiated && !@unbound
-          Fiber.new { send_data(Readline.readline(j['p'], true)) }.resume
+          Fiber.new {
+            true while (l = Readline.readline(j['p'], true)).empty?
+            send_data(l)
+          }.resume
         end
 
       elsif j['d'] # printable data

data/lib/pry-remote-em/server.rb

@@ -1,5 +1,33 @@
 require 'pry'
 require 'pry-remote-em'
+# How it works with Pry
+#
+# When PryRemoteEm.run is called it registers with EventMachine for a given ip
+# and port. When a connection is received EM yields an instance of PryRemoteEm,
+# we start a Fiber (f1) then call Pry.start specifying the Server instance as the
+# input and output object for Pry. The Pry instance that is created goes into
+# its REPL.  When it gets to the read part it calls @input.readline
+# (PryRemoteEm#readline) and passes a prompt, e.g., [1] pry(#<Foo>)>.
+#
+# PryRemoteEm#readline calls #send_data with the prompt then yields from the
+# current Fiber (f1); the one we started when EventMachine yielded to us. The root
+# Fiber is now active again. At some point, the root Fiber receives data from
+# the client. It calls #receive_data in our Server instance. That instance then
+# resumes the Fiber (f1) that was waiting for #readline to finish.
+#
+# Inside the resumed Fiber (f1) PryRemoteEm#readline returns the recieved data
+# to the instance of Pry, which continues its REPL. Pry calls #puts, or #print
+# or #write on its output object (PryRemoteEm). We send that data out to the client
+# and immediately return. Pry then calls PryRemoteEm#readline again and again
+# we send the prompt then immediately yield back to the root Fiber.
+#
+# Pry just interacts with PryRemoteEm as if it were any other blocking Readline
+# object. The important bit is making sure that it is started in a new Fiber that
+# can be paused and resumed as needed. PryRemoteEm#readline pauses it and
+# PryRemoteEm#receive_json resumes it.
+#
+# Reference:
+# http://www.igvita.com/2010/03/22/untangling-evented-code-with-ruby-fibers/
 
 module PryRemoteEm
   module Server

data/lib/pry-remote-em/version.rb

@@ -1,3 +1,3 @@
 module PryRemoteEm
-  VERSION   = '0.4.0'
+  VERSION   = '0.4.1'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pry-remote-em
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.4.1
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-01-28 00:00:00.000000000Z
+date: 2012-01-31 00:00:00.000000000Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: eventmachine
-  requirement: &70305814043480 !ruby/object:Gem::Requirement
+  requirement: &70255566066140 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70305814043480
+  version_requirements: *70255566066140
 - !ruby/object:Gem::Dependency
   name: pry
-  requirement: &70305814042980 !ruby/object:Gem::Requirement
+  requirement: &70255566064780 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -32,10 +32,10 @@ dependencies:
         version: 0.9.6
   type: :runtime
   prerelease: false
-  version_requirements: *70305814042980
+  version_requirements: *70255566064780
 - !ruby/object:Gem::Dependency
   name: rb-readline
-  requirement: &70305814042560 !ruby/object:Gem::Requirement
+  requirement: &70255566063460 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -43,10 +43,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70305814042560
+  version_requirements: *70255566063460
 - !ruby/object:Gem::Dependency
   name: highline
-  requirement: &70305814042100 !ruby/object:Gem::Requirement
+  requirement: &70255566062900 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -54,7 +54,7 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70305814042100
+  version_requirements: *70255566062900
 description: Connect to Pry remotely using EventMachine with tab-completion, paging,
   user authentication and SSL support.
 email: pry-remote-em@simulacre.org
@@ -95,3 +95,4 @@ signing_key:
 specification_version: 3
 summary: Connect to Pry remotely using EventMachine
 test_files: []
+has_rdoc: