pry-remote-em 0.7.5 → 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 9891306377f0196004da3a9bd1c69beb92d49756
+  data.tar.gz: d09d7572adf27c19d9b8f8fdf69290c4dc25264e
+SHA512:
+  metadata.gz: b15649c543deaa0b4e48fdb3ec1f8db2b7296709c50c62ac1e6e69f2b2cbf4abcaf3af61ca9270a7c850422f9afd940cd9fc38a5b2a3bfdd506e12f5bf0600ae
+  data.tar.gz: e15c4019739eef9f214a63c6b064ca33564a12f8051da4cf25889885cfa31fca497c23b4a22110bbcb3d5a6bc15b9bbc4ed61dce7ce83ef85c5f233f1ea39c70

data/CHANGELOG.md

@@ -0,0 +1,140 @@
+# 1.0.0
+
+## Breaking changes
+
+* **BREAKING CHANGE** Change `!` and `!!` messaging commands to `^` and `^^` to avoid confusing with Pry's built in `!` command and Ruby's `not` semantics
+* **BREAKING CHANGE** Change `PryRemoteEm::Server.run` method signature to hash-only form (`remote_pry_em` method's signature didn't changed)
+* **BREAKING CHANGE** Change `allow_shell_cmds` setting to `true` by default instead of `false`, because most of projects does not use $SAFE and any shell command can be run from Ruby code with `system` call or backticks, so this option is illusion in most cases
+* **BREAKING CHANGE** `PryRemoteEm::Server.run` returns whole server description instead of URL
+* **BREAKING CHANGE** Rename public constants to avoid confusing
+* **BREAKING CHANGE** Drop support for eventmachine prior to 1.0.0.beta4
+
+## Features
+
+* Add `PryRemoteEm::Sandbox` as target by default, see Readme for details
+* Add proxy-by-default setting to CLI
+* Add possibility to use environment variables on CLI connection
+* Add more environment variables to control server without code changing (described in readme)
+* Add support for empty environment variables and nil arguments on server start
+* Add possibility to set external url for server (to use lib with NAT or Docker) using `PRYEMURL` or `external_url` option
+* Add ability to use custom server name using `PRYEMNAME` environment variable or `name` option (and displaying it in the prompt)
+* Add ability to start server without starting broker using `PRYEMREMOTEBROKER` environment variable or `remote_broker` option
+* Add `pry-remote-em-broker` binary to start broker without starting server
+* Add `Object#pry_remote_em` alias to `Object#remote_pry_em` to avoid common confusing
+* Add support for options hash as first argument instead of third in `Object#remote_pry_em`
+* Add local history loading on session start
+* Add support for `pry-coolline` (just install this gem to make it work)
+* Add support for several URIs per one server (when binding to 0.0.0.0)
+* Add option to ignore localhost urls in the list (useful when server binding to 0.0.0.0 in Docker, where localhost is useless)
+* Add support for `details` option on server start and corresponding CLI option to display some usefull information about server instead or url in broker table (for example, health status, which can be updated on every heartbeat via details hash mutating)
+
+## Fixes
+
+* Fix proxy, it didn't work at all
+* Fix interative shell commands, they didn't work at all
+* Fix `libc++abi.dylib: Pure virtual function called!` error on client disconnecting
+* Fix strange buffer bugs on long output over network using MessagePack protocol instead of JSON
+* Fix console crash on pager quit
+* Fix console crash on Ctrl+C (now it's clears the buffer like in native Pry)
+* Fix IPv6 localhost crash
+* Fix missing requires when using broker without server
+* Fix port access check when using environment variables
+* Fix strange effects when registering in broker from Docker (now broker use UUID as a key instead of URI)
+* Fix message `broker connection unbound starting a new one` on EventMachine stopping
+* Fix unregistering in broker by timeout only, now servers unregister instantly after closing connection
+* Fix interative shell commands echo printing
+* Fix unknown shell command problem (now valid `command not found` message is printing)
+* Fix behaviour on empty input, now it's exactly like as in native Pry
+* Fix saving empty strings in history
+
+## Chore
+
+* Add ruby-termios to runtime dependencies to avoid confusing `unable to load keyboard dependencies` message
+* Bump dependencies versions
+* Remove useless return values from inner methods
+* Add stable 3 seconds timeout on broker reconnection, not random one
+* Require `pry-remote-em/server` by defaults
+* Correct README for default broker port
+* Use single quotes by default
+* Use Ruby 1.9 hash syntax by default
+* Use semantic versioning, starting at 1.0.0 (since we're using it in production for a long time already)
+
+# 0.7.5
+
+* [#42](https://github.com/gruis/pry-remote-em/pull/42) - Use bytesize String method instead of length in protocol. [distorhead](https://github.com/distorhead)
+
+# 0.7.4
+
+* [#40](https://github.com/gruis/pry-remote-em/pull/40) - require 'pry', not its parts [rking](https://github.com/rking)
+* [#39](https://github.com/gruis/pry-remote-em/pull/39) - stagger_output needs Pry::Pager to be loaded in the parent scope [pcmantz](https://github.com/pcmantz)
+
+# 0.7.3
+
+* Broker listens at 6462 everything else starts at 6463
+* cli assumes port 6462 when not specified
+
+# 0.7.2
+
+* Broker.run yields to a block when broker connection has been established
+
+# 0.7.1
+
+* server list can be filtered by host, port, name, or SSL support
+* server list can be sorted by host, port, name, or SSL support
+* cli assumes port 6461 when not specified
+* cli accepts -c and -p options to immediately connect or proxy from the broker to a server matching the name specified on the command line
+* closes #37 loosens pry version requirement
+* client sorts server list by host address
+* when registering 0.0.0.0 with a Broker register each interface instead
+
+# 0.7.0
+
+* fixes #21 version matching between client and server allow differences in patch levels
+* fixes #31 client reports own version when incompatible with server
+* client supports vi mode: rb-readline replaced by readline
+* fixes #31 termios is no longer a hard requirement: shell commands will be disabled without it
+* adds PryRemoteEm.servers and PryRemoteEm.stop_server
+* broker can proxy requests to local or remote servers that have registered with it
+* closes #11 all servers will attempt to register with a broker; client will retrieve list of servers from the broker and present a menu to the user by default
+* when specifying a specific port to listen on the option :port_fail can be set to :auto; if binding fails attempt to bind on the next port
+* server.run returns a url (String) with the scheme, host and port of the listening server
+* json specific parts of wire protocol are abstracted away from client and server
+* json proto is a bit more robust: delimeter can be a part of data and CRC is performed
+
+# 0.6.2
+
+* handle reset command appropriately
+
+# 0.6.1
+
+* messages are tagged with user that sent them if authentication is being used
+
+# 0.6.0
+
+* adds shell command support
+* adds auth event callbacks
+* adds configurable logger
+
+# 0.5.0
+
+* adds simple messaging with '!' and '!!'
+
+# 0.4.3
+
+* fixes https://github.com/gruis/pry-remote-em/issues/26
+* fixes https://github.com/gruis/pry-remote-em/issues/24
+
+# 0.4.2
+
+* fixes https://github.com/gruis/pry-remote-em/issues/23
+
+# 0.4.1
+
+* empty lines don't cause termination
+
+# 0.4.0
+
+* User/Pass authentication
+* TLS support
+* Paging support
+* Tab completion

data/README.md

@@ -28,13 +28,13 @@ class Foo
   end
 end
 
-EM.run { Foo.new 10, 20 } 
+EM.run { Foo.new 10, 20 }
 ```
 
 Running it will print out a message telling you Pry is waiting for a
 program to connect itself to it:
 
-     [pry-remote-em] listening for connections on pryem://localhost:6462/
+     [pry-remote-em] listening for connections on pryem://127.0.0.1:6462/
 
 You can then connect to the pry session using ``pry-remote-em``:
 
@@ -88,7 +88,7 @@ or even in the same process. When you start the service via
 will automatically take the next free port from 6462.
 
 ```ruby
-require "pry-remote-em/server"
+require 'pry-remote-em/server'
 
 os     = ObjectSpace.each_object
 expose = []
@@ -97,9 +97,9 @@ while expose.length < 5
   expose.push(o) unless o.frozen?
 end
 
-EM.run {
+EM.run do
   expose.each {|o| o.remote_pry_em('localhost', :auto) }
-}
+end
 ```
 
     $ ruby test/auto-demo.rb
@@ -114,12 +114,12 @@ EM.run {
 $ pry-remote-em pryem://127.0.0.1:6462/
 [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")> 
+[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")> 
+[1] pry("pack")>
 
 $ pry-remote-em  pryem://127.0.0.1:6464/
 [pry-remote-em] client connected to pryem://127.0.0.1:6464/
@@ -129,22 +129,22 @@ $ pry-remote-em  pryem://127.0.0.1:6464/
 $ 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")> 
+[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>)> 
+[1] pry(#<RubyVM::InstructionSequence>)>
 ```
 
 ## Server Broker
 
 When more than one server is running on a given host and each server is
 started with :auto it can be time consuming to manually figure out which
-port each server is running on. The Broker which listens on port 6461
-keeps track of which server is running on which port. 
+port each server is running on. The Broker which listens on port 6462
+keeps track of which server is running on which port.
 
-By default the pry-remote-em cli utility will connect to the broker and 
+By default the pry-remote-em cli utility will connect to the broker and
 retrieve a list of known servers. You can then select one to connect to
 by its id, name or url. You can also choose to proxy your connection
 through the broker to the selected server.
@@ -152,7 +152,7 @@ through the broker to the selected server.
 ```shell
 
 $ bin/pry-remote-em
-[pry-remote-em] client connected to pryem://127.0.0.1:6461/
+[pry-remote-em] client connected to pryem://127.0.0.1:6462/
 [pry-remote-em] remote is PryRemoteEm 0.7.0 pryem
 -----------------------------------------------------------------------------
 | id  |  name                              |  url                           |
@@ -176,15 +176,15 @@ connect to: 3
 [1] pry(#<#<Class:0x007f924b9bbee8>>)>
 ```
 
-By default the Broker will listen on 127.0.0.1:6461. To change the ip
+By default the Broker will listen on 127.0.0.1:6462. To change the ip
 address that the Broker binds to specify it in a PRYEMBROKER environment
 variable, or in :broker_host option passed to #remote_pry_em.
 
 ```shell
 
-$ PRYEMBROKER=0.0.0.0 be ./test/service.rb  
+$ PRYEMBROKER=0.0.0.0 be ./test/service.rb
 I, [2012-07-13T21:10:00.936993 #88528]  INFO -- : [pry-remote-em] listening for connections on pryem://0.0.0.0:6462/
-I, [2012-07-13T21:10:00.937132 #88528]  INFO -- : [pry-remote-em broker] listening on pryem://0.0.0.0:6461
+I, [2012-07-13T21:10:00.937132 #88528]  INFO -- : [pry-remote-em broker] listening on pryem://0.0.0.0:6462
 I, [2012-07-13T21:10:00.937264 #88528]  INFO -- : [pry-remote-em] listening for connections on pryem://0.0.0.0:1337/
 I, [2012-07-13T21:10:00.937533 #88528]  INFO -- : [pry-remote-em] listening for connections on pryems://0.0.0.0:6463/
 I, [2012-07-13T21:10:00.937804 #88528]  INFO -- : [pry-remote-em] listening for connections on pryems://0.0.0.0:6464/
@@ -194,15 +194,15 @@ I, [2012-07-13T21:10:00.938835 #88528]  INFO -- : [pry-remote-em] listening for
 I, [2012-07-13T21:10:00.939230 #88528]  INFO -- : [pry-remote-em] listening for connections on pryem://0.0.0.0:6468/
 I, [2012-07-13T21:10:00.939640 #88528]  INFO -- : [pry-remote-em] listening for connections on pryem://0.0.0.0:6469/
 I, [2012-07-13T21:10:01.031576 #88528]  INFO -- : [pry-remote-em broker] received client connection from 127.0.0.1:62288
-I, [2012-07-13T21:10:01.031931 #88528]  INFO -- : [pry-remote-em] client connected to pryem://127.0.0.1:6461/
+I, [2012-07-13T21:10:01.031931 #88528]  INFO -- : [pry-remote-em] client connected to pryem://127.0.0.1:6462/
 I, [2012-07-13T21:10:01.032120 #88528]  INFO -- : [pry-remote-em] remote is PryRemoteEm 0.7.0 pryem
-I, [2012-07-13T21:10:01.032890 #88528]  INFO -- : [pry-remote-em broker] registered pryem://127.0.0.1:6462/ - "#<#<Class:0x007f924b9bbee8>>" 
-I, [2012-07-13T21:10:01.125123 #88528]  INFO -- : [pry-remote-em broker] registered pryem://127.0.0.1:6469/ - "#<#<Class:0x007f924b9bbee8>>" 
+I, [2012-07-13T21:10:01.032890 #88528]  INFO -- : [pry-remote-em broker] registered pryem://127.0.0.1:6462/ - "#<#<Class:0x007f924b9bbee8>>"
+I, [2012-07-13T21:10:01.125123 #88528]  INFO -- : [pry-remote-em broker] registered pryem://127.0.0.1:6469/ - "#<#<Class:0x007f924b9bbee8>>"
 I, [2012-07-13T21:10:01.125487 #88528]  INFO -- : [pry-remote-em broker] registered pryems://127.0.0.1:6467/ - "#<#<Class:0x007f924b9bbee8>>"
 I, [2012-07-13T21:10:01.490729 #88528]  INFO -- : [pry-remote-em broker] registered pryems://127.0.0.1:6464/ - "#<#<Class:0x007f924b9bbee8>>"
-I, [2012-07-13T21:10:01.583015 #88528]  INFO -- : [pry-remote-em broker] registered pryem://127.0.0.1:1337/ - "#<Foo>"                       
+I, [2012-07-13T21:10:01.583015 #88528]  INFO -- : [pry-remote-em broker] registered pryem://127.0.0.1:1337/ - "#<Foo>"
 I, [2012-07-13T21:10:01.674842 #88528]  INFO -- : [pry-remote-em broker] registered pryems://127.0.0.1:6466/ - "#<#<Class:0x007f924b9bbee8>>"
-I, [2012-07-13T21:10:01.766813 #88528]  INFO -- : [pry-remote-em broker] registered pryem://127.0.0.1:6468/ - "#<#<Class:0x007f924b9bbee8>>" 
+I, [2012-07-13T21:10:01.766813 #88528]  INFO -- : [pry-remote-em broker] registered pryem://127.0.0.1:6468/ - "#<#<Class:0x007f924b9bbee8>>"
 I, [2012-07-13T21:10:01.858423 #88528]  INFO -- : [pry-remote-em broker] registered pryems://127.0.0.1:6465/ - "#<#<Class:0x007f924b9bbee8>>"
 ```
 
@@ -211,7 +211,7 @@ running on a different host. Just specify the Brokers address in the
 PRYEMBROKER environment variable or the :broker_host option passed to #remote_pry_em.
 
 To connect to a broker running on a seperate host with the cli client
-just specify it on the command line ``bin/pry-remote-em preym://10.0.0.2:6461/``.
+just specify it on the command line ``bin/pry-remote-em preym://10.0.0.2:6462/``.
 You can then proxy your client connections to remote servers through
 that Broker.
 
@@ -220,18 +220,18 @@ TLS enabled server.
 
 
 ## TLS Encryption
-  
-When creating a server pass the :tls => true option to enable TLS. 
+
+When creating a server pass the tls: true option to enable TLS.
 
 ```ruby
-obj.remote_pry_em('localhost', :auto, :tls => true)
+obj.remote_pry_em('localhost', :auto, tls: true)
 ```
 
-If you pass a Hash it will be used to configure the internal TLS handler. 
+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'})
-``` 
+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.
 
 
@@ -244,7 +244,7 @@ $ pry-remote-em pryem://localhost: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>)> 
+[1] pry(#<Hash>)>
 ```
 
 To always require a TLS connection give pry-remote-em a pryem*s* URL. If
@@ -270,24 +270,24 @@ or any object that responds to #call.
 
 #### Auth with a Hash
 ```ruby
-auth_hash = {'caleb' => 'crane', 'john' => 'lowski'}
-obj       = {:encoding => __ENCODING__, :weather => :cloudy}
-EM.run{
-  obj.remote_pry_em('localhost', :auto, :tls => true, :auth => auth_hash)
-}
+auth_hash = { 'caleb' => 'crane', 'john' => 'lowski' }
+obj       = { encoding: __ENCODING__, weather: :cloudy }
+EM.run do
+  obj.remote_pry_em('localhost', :auto, tls: true, auth: auth_hash)
+end
 ```
 
 #### Auth with a lambda
 ```ruby
 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}
-EM.run{
-  obj.remote_pry_em('localhost', :auto, :tls => true, :auth => ldap_anon)
-}
+obj       = { encoding: __ENCODING__, weather: :cloudy }
+EM.run do
+  obj.remote_pry_em('localhost', :auto, tls: true, auth: ldap_anon)
+end
 ```
 
 #### Auth with an object
@@ -301,10 +301,10 @@ class Authenticator
   end
 end
 
-obj       = {:encoding => __ENCODING__, :weather => :cloudy}
-EM.run{
-  obj.remote_pry_em('localhost', :auto, :tls => true, :auth => Authenticator.new(auth_hash))
-}
+obj       = { encoding: __ENCODING__, weather: :cloudy }
+EM.run do
+  obj.remote_pry_em('localhost', :auto, tls: true, auth: Authenticator.new(auth_hash))
+end
 ```
 
 
@@ -323,7 +323,7 @@ $ pry-remote-em pryems://localhost:6464/
 [pry-remote-em] TLS connection established
 user: caleb
 caleb's password: *****
-[1] pry(#<Hash>)> 
+[1] pry(#<Hash>)>
 ```
 
 
@@ -357,7 +357,7 @@ $ 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
 [1] pry(#<Hash>)> key (^TAB ^TAB)
-key   key?  keys  
+key   key?  keys
 [1] pry(#<Hash>)> keys
 => [:encoding]
 ```
@@ -384,13 +384,285 @@ The standard Pry pager is supported through the included client.
 :
 ```
 
+## Sandbox
+
+The `PryRemoteEm::Sandbox` class introduced to help in case when you
+do not mush interested in console's executing context but just want to
+access a remote server's "control panel" with usefull methods and
+without worrying about breaking some object's internal state.
+
+To use sandbox just run `PryRemoteEm::Server.run` instead of
+`binding.remote_pry_em`. You can include any modules with your
+application's business logic in this class to get real "control panel"
+for your program.
+
+The simple example:
+
+```ruby
+# Microservice A, a.rb
+
+require 'bundler'
+Bundler.require
+
+DB = Sequel.sqlite
+
+module ControlPanel
+  def u(id)
+    DB[:users].find(id)
+  end
+
+  def ban(id)
+    DB[:users].where(id: id).update u(id).merge('status' => 'banned')
+  end
+end
+
+PryRemoteEm::Sandbox.include ControlPanel
+
+EventMachine.run do
+  trap(:INT) { EventMachine.stop }
+
+  PryRemoteEm::Server.run name: 'Microservice A', port: :auto, remote_broker: true, details: { environment: 'staging' }
+end
+```
+
+```ruby
+# Microservice B, b.rb
+
+require 'bundler'
+Bundler.require
+
+module Transport
+  # ...
+end
+
+module ControlPanel
+  def ping(microservice)
+    Transport.send_ping(microservice)
+  end
+end
+
+PryRemoteEm::Sandbox.include ControlPanel
+
+EventMachine.run do
+  trap(:INT) { EventMachine.stop }
+
+  PryRemoteEm::Server.run name: 'Microservice B', port: :auto, remote_broker: true, details: { environment: 'staging' }
+end
+```
+
+Then, in shell:
+
+```shell
+$ pry-remote-em-broker > /dev/null &
+$ ruby a.rb > /dev/null &
+$ ruby b.rb > /dev/null &
+$
+$ pry-remote-em -P --sn -d environment
+[pry-remote-em] client connected to pryem://127.0.0.1:6462/
+[pry-remote-em] remote is PryRemoteEm 1.0.0 pryem
+------------------------------------------
+|     |  name            |  environment  |
+------------------------------------------
+|  1  |  Microservice A  |  staging      |
+|  2  |  Microservice B  |  staging      |
+------------------------------------------
+(q) to quit; (r) to refresh; (c) to connect without proxy
+proxy to: 1
+[pry-remote-em] remote is PryRemoteEm 1.0.0 pryem
+[1] Microservice A (sandbox)> u 13
+=> {"id"=>13, "violations"=>4, "status"=>"active"}
+[2] Microservice A (sandbox)> @my_bad_user = _
+=> {"id"=>13, "violations"=>4, "status"=>"active"}
+[3] Microservice A (sandbox)> ban 13 # You can use control panel to work with some business cases
+=> 1
+[4] Microservice A (sandbox)> exit
+[pry-remote-em] session terminated
+$
+$ pry-remote-em pryem://127.0.0.1:6463
+[pry-remote-em] remote is PryRemoteEm 1.0.0 pryem
+[1] Microservice A (sandbox)> @my_bad_user
+=> {"id"=>13, "violations"=>4, "status"=>"banned"}
+[2] Microservice A (sandbox)> exit
+[pry-remote-em] session terminated
+$
+$ pry-remote-em pryem://127.0.0.1:6464
+[pry-remote-em] remote is PryRemoteEm 1.0.0 pryem
+[1] Microservice A (sandbox)> ping :A # Or you can use it to check infrastructure and perform custom communications between servers
+=> "pong"
+[2] Microservice A (sandbox)> exit
+[pry-remote-em] session terminated
+```
+
+In sandbox you have those possibilities "out of the box":
+
+* `puts`, `putc`, `print`, `p` and `pp` methods works almost as you
+expected. In other contexts they will use server's STDOUT, but in
+sandbox they will send all the data to client. Remember, you'll lost
+those methods out of the sandbox context:
+
+```shell
+$ pry-remote-em pryem://127.0.0.1:6463
+[pry-remote-em] remote is PryRemoteEm 1.0.0 pryem
+[1] Demo Server (sandbox)> puts 'Hello World' # It works!
+Hello World
+=> nil
+[2] Demo Server (sandbox)> Object.new.instance_eval { puts "Hello World" } # Do not work
+=> nil
+[3] Demo Server (sandbox)> cd Object.new
+[4] Demo Server (#<Object>):1> puts "Hello World" # Do not work
+=> nil
+```
+
+* `any_errors?`, `last_error` and `last_errors` methods in sandbox
+context with `PryRemoteEm::Sandbox.add_error` method from your code
+to help you store all the bugs and debug it in the bug's execution
+context. It also integrated with `wtf?` command. For example:
+
+```ruby
+require 'bundler'
+Bundler.require
+
+def safe_handler(source_binding)
+  yield
+rescue => exception
+  PryRemoteEm::Sandbox.add_error(exception, source_binding)
+  raise
+end
+
+def danger_mathod(a, b)
+  safe_handler(binding) do
+    a / b
+  end
+end
+
+EventMachine.run do
+  trap(:INT) { EventMachine.stop }
+
+  EventMachine.error_handler do |exception|
+    PryRemoteEm::Sandbox.add_error(exception)
+  end
+
+  EventMachine.add_timer(5) { danger_mathod 1, 0 }
+
+  PryRemoteEm::Server.run name: 'Demo Server', details: { hostname: 'local' }
+end
+```
+
+Then, in shell:
+
+```shell
+$ pry-remote-em -P --sn -d hostname
+[pry-remote-em] client connected to pryem://127.0.0.1:6462/
+[pry-remote-em] remote is PryRemoteEm 1.0.0 pryem
+------------------------------------
+|     |  name         |  hostname  |
+------------------------------------
+|  1  |  Demo Server  |  local     |
+------------------------------------
+(q) to quit; (r) to refresh; (c) to connect without proxy
+proxy to: 1
+[pry-remote-em] remote is PryRemoteEm 1.0.0 pryem
+[1] Demo Server (sandbox)> any_errors?
+=> true
+[2] Demo Server (sandbox)> last_error
+=> #<ZeroDivisionError: divided by 0>
+[3] Demo Server (sandbox)> wtf?
+Exception: ZeroDivisionError: divided by 0
+--
+0: demo_server.rb:13:in `/'
+1: demo_server.rb:13:in `block in danger_mathod'
+2: demo_server.rb:5:in `safe_handler'
+3: demo_server.rb:12:in `danger_mathod'
+4: demo_server.rb:24:in `block (2 levels) in <main>'
+5: /usr/local/lib/ruby/gems/2.4.0/gems/eventmachine-1.2.7/lib/eventmachine.rb:195:in `run_machine'
+6: /usr/local/lib/ruby/gems/2.4.0/gems/eventmachine-1.2.7/lib/eventmachine.rb:195:in `run'
+7: demo_server.rb:17:in `<main>'
+[4] Demo Server (sandbox)> cd last_error.source_binding
+[5] Demo Server (main):1> whereami
+
+From: /Users/user/Projects/demo/demo_server.rb @ line 12 Object#danger_mathod:
+
+    11: def danger_mathod(a, b)
+ => 12:   safe_handler(binding) do
+    13:     a / b
+    14:   end
+    15: end
+
+[6] Demo Server (main):1> ls
+self.methods: inspect  to_s
+locals: _  __  _dir_  _ex_  _file_  _in_  _out_  _pry_  a  b
+[7] Demo Server (main):1> a
+=> 1
+[8] Demo Server (main):1> b
+=> 0
+```
+
+* `server` method to access PryRemoteEm::Server description object.
+For example, it can be useful for changing `details`:
+
+```ruby
+require 'bundler'
+Bundler.require
+
+module HealthChecker
+  # ...
+end
+
+EventMachine.run do
+  trap(:INT) { EventMachine.stop }
+
+  PryRemoteEm::Server.run name: 'Demo Server', heartbeat_interval: 1, details: { hand_check: false }
+end
+```
+
+Then, in shell:
+
+```shell
+$ pry-remote-em -P --sn -d hand_check
+[pry-remote-em] client connected to pryem://127.0.0.1:6462/
+[pry-remote-em] remote is PryRemoteEm 1.0.0 pryem
+--------------------------------------
+|     |  name         |  hand_check  |
+--------------------------------------
+|  1  |  Demo Server  |  true        |
+|  2  |  Demo Server  |  true        |
+|  3  |  Demo Server  |  false       |
+|  4  |  Demo Server  |  false       |
+|  5  |  Demo Server  |  false       |
+--------------------------------------
+(q) to quit; (r) to refresh; (c) to connect without proxy
+proxy to: 3
+[1] Demo Server (sandbox)> HealthChecker.all_ok?
+=> true
+[2] Demo Server (sandbox)> server[:details][:hand_check] = true
+=> true
+[3] Demo Server (sandbox)> exit
+[pry-remote-em] session terminated
+$
+$ sleep 1
+$ pry-remote-em -P --sn -d hand_check
+[pry-remote-em] client connected to pryem://127.0.0.1:6462/
+[pry-remote-em] remote is PryRemoteEm 1.0.0 pryem
+--------------------------------------
+|     |  name         |  hand_check  |
+--------------------------------------
+|  1  |  Demo Server  |  true        |
+|  2  |  Demo Server  |  true        |
+|  3  |  Demo Server  |  true        |
+|  4  |  Demo Server  |  false       |
+|  5  |  Demo Server  |  false       |
+--------------------------------------
+(q) to quit; (r) to refresh; (c) to connect without proxy
+proxy to:
+```
+
 ## Messaging
 It is possible for each pry-remote-em service to host multiple
 simultaneous connections. You can send messages to other connections
-with the '!' and '!!' prefix.
+with the '^' and '^^' prefix.
 
-The '!' prefix will send the message to connections on the same object.
-the '!!' prefix will send the message to all connections in the current
+The '^' prefix will send the message to connections on the same object.
+the '^^' prefix will send the message to all connections in the current
 process.
 
 Message will not be displayed by the clients until the presses enter.
@@ -403,8 +675,8 @@ Available events are:
  - auth_ok      - called each time authentication succeeds
 
 ```ruby
-log         = ::Logger.new('/var/log/auth.pry.log')
-obj.new.remote_pry_em('0.0.0.0', :auto, :tls => true, :auth => auth_hash) do |pry|
+log = ::Logger.new('/var/log/auth.pry.log')
+obj.new.remote_pry_em('0.0.0.0', :auto, tls: true, auth: auth_hash) do |pry|
   pry.auth_attempt do |user, ip|
     log.info("got an authentication attempt for #{user} from #{ip}")
   end
@@ -418,8 +690,8 @@ end
 ```
 
 ## Shell Commands
-If the pry-remote-em service is started with the ``:allow_shell_cmds =>
-true`` option set it will spawn sub processes for any command prefixed
+Unless the pry-remote-em service is started with the ``allow_shell_cmds:
+false`` option set it will spawn sub processes for any command prefixed
 with a '.'.
 
 ```
@@ -431,7 +703,7 @@ Interactive commands like ``vim`` will probably not behave
 appropriately.
 
 
-If the server was not started with the ``allow_shell_cmds`` option then
+If the server was started with the ``allow_shell_cmds: false`` option then
 all shell commands will be met with a rejection notice.
 
 ```
@@ -439,8 +711,7 @@ all shell commands will be met with a rejection notice.
 shell commands are not allowed by this server
 ```
 
-The server will also log whenever a user attempts to execute a shell
-command.
+The server will also log whenever a user attempts to execute a shell command.
 
 ```
 W, [2012-02-11T19:21:27.663941 #36471]  WARN -- : executing shell command 'ls -al' for  (127.0.0.1:63878)
@@ -450,18 +721,31 @@ W, [2012-02-11T19:21:27.663941 #36471]  WARN -- : executing shell command 'ls -a
 E, [2012-02-11T19:23:40.770380 #36471] ERROR -- : refused to execute shell command 'ls' for caleb (127.0.0.1:63891)
 ```
 
-# Missing Features
+# Environment variables
+
+* PRYEMNAME - pry server name to show in broker's list, default - target object's inspect
+* PRYEMURL - pry server URL to show in broker's list, default - pryem://#{server_host}:#{server_port}/
+* PRYEMHOST - host to bind pry server, default - 127.0.0.1
+* PRYEMPORT - port to bind pry server, default - 6463
+* PRYEMBROKER - host to bind pry broker, default - 127.0.0.1
+* PRYEMBROKERPORT - port to bind pry broker, default - 6462
+* PRYEMREMOTEBROKER - start server without starting broker, default - broker starting with server
+* PRYEMNOPAGER - disable paging on long output, default - pager enabled
+* PRYEMNEGOTIMEOUT - connection negotiation timeout in seconds, default - 15
+* PRYEMHBSEND - server to broker heartbeat interval in seconds, default - 15
+* PRYEMHBCHECK - heartbeat check on broker interval in seconds, default - 20
+* PRYEMBROKERTIMEOUT - reconnect to broker timeout in seconds, default - 3
+* PRYEMSANDBOXERRORS - number of errors to store in sandbox, default - 100
 
-  - HTTP Transport [ticket](https://github.com/simulacre/pry-remote-em/issues/12)
-  - Ssh key based authentication
+# Missing Features
 
+  - HTTP Transport ([ticket](https://github.com/gruis/pry-remote-em/issues/12))
+  - SSH key based authentication
+  - Looking for connected users and their history
 
 # Issues
 
- Please post any bug reports or feature requests on [Github](https://github.com/simulacre/pry-remote-em/issues)
-
-
-
+ Please post any bug reports or feature requests on [Github](https://github.com/gruis/pry-remote-em/issues)
 
 # Copyright
 
@@ -469,7 +753,7 @@ Copyright (c) 2012 Caleb Crane
 
 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 
+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: