Release 0.3.0

CHANGELOG.markdown

@@ -1,6 +1,13 @@
 # CHANGELOG
 
-## Master (Unreleased)
+## 0.3.0 (August 23, 2013)
+
+* Proper VT100 emulation.
+* Add config.web_console.command to allow custom programs execution.
+* Add config.web_console.timeout to allow for long-polling, where available.
+* Remove config.web_console.prevent_irbrc_execution.
+
+## 0.2.0 (August 1, 2013)
 
 * Run closest .irbrc config while initializing the IRB adapters.
 * Add config.web_console.prevent_irbrc_execution option.

Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    web-console (0.2.0)
+    web-console (0.3.0)
       rails (~> 4.0.0)
 
 GEM

README.markdown

@@ -4,7 +4,7 @@
   <a href=https://github.com/gsamokovarov/web-console/tree/v0.2.0>v0.2.0</a>
 </p>
 
-Web Console [![Travis](https://travis-ci.org/gsamokovarov/web-console.png)](https://travis-ci.org/gsamokovarov/web-console) [![Version](https://badge.fury.io/rb/web-console.png)](http://badge.fury.io/rb/web-console)
+Web Console [![Version](https://badge.fury.io/rb/web-console.png)](http://badge.fury.io/rb/web-console) [![Travis](https://travis-ci.org/gsamokovarov/web-console.png)](https://travis-ci.org/gsamokovarov/web-console)
 ===========
 
 There is no doubt that `rails console` is one of the most useful commands,
@@ -14,16 +14,24 @@ server.
 
 This is where _Web Console_ comes to the rescue. It gives you the same
 `rails console` experience, right in the browser. It's not just a tool that
-let's you evaluate Ruby code, there are a lot of those. It's your `IRB`
-session, the way you configured it.
+let's you evaluate Ruby code, there are a lot of those. It's a [VT100]
+compatible terminal, running `rails console`.
 
-![web-console-demo](http://f.cl.ly/items/1b2E2C052g1v1A233N0g/web-console-demo.png)
+You can see _Web Console_ in action at this [video].
 
 Requirements
 ------------
 
-To run _Web Console_ you need to be running _Rails 4_ and _MRI Ruby 1.9.3_ and
-above. It may run on _Rubinius_ and _JRuby_, but we haven't tested those yet.
+_Web Console_ has been tested on the following rubies.
+
+* _MRI Ruby_ 2.0.0
+* _MRI Ruby_ 1.9.3
+* _JRuby_ 1.7.4
+
+_Rubunius_ in 1.9 mode may work, but it hasn't been tested.
+
+_Web Console_ has been built explicitly for _Rails 4_. For a _Rails 3_
+compatible build, check out the [web-console-rails3] project.
 
 Installation
 ------------
@@ -32,7 +40,7 @@ To install it in your current application, add the following to your `Gemfile`.
 
 ```ruby
 group :development do
-  gem 'web-console', '~> 0.2.0'
+  gem 'web-console', '~> 0.3.0'
 end
 ```
 
@@ -91,14 +99,9 @@ Again, note that this network doesn't allow `127.0.0.1`.  If you want to access
 the console, you have to do so from it's external IP or add `127.0.0.1` to the
 mix.
 
-### config.web_console.prevent_irbrc_execution
-
-By default, the `IRB` adapter will execute the contents of the user's `.irbrc`.
-Set this option to `false` if you would like to prevent that.
-
 ### config.web_console.default_mount_path
 
-By default, the console will be mounted on `/console`.
+By default, the console will be automatically mounted on `/console`.
 
 _(This happens only in the development and test environments!)_.
 
@@ -111,20 +114,75 @@ class Application < Rails::Application
 end
 ```
 
-Restart your server and you are done!
+### config.web_console.automount
 
-Compatibility
--------------
+If you want to explicitly mount `WebConsole::Engine`, you can prevent the
+automatic mount by setting this option to `false`.
+
+### config.web_console.command
+
+By default, _Web Console_ will run `Rails.root.join('bin/rails console)` to
+spawn you a fresh Rails console.
+
+One of the advantages of being a [VT100] emulator is that _Web Console_ can run
+most of your terminal applications.
+
+Let say _(for some reason)_ you can't run SSH on your server machine. You can
+run [`login`][login] instead to let users sign into the host system.
+
+```ruby
+class Application < Rails::Application
+  config.web_console.command = 'sudo /bin/login'
+end
+```
 
-### Pry
+_Poor man's solution to SSH._ ![boom](http://f.cl.ly/items/3n2h0p1w0B261u2d201b/boom.png)
 
-_Web Console_ isn't limited to just `IRB`. If you like `Pry` more than `IRB`,
-we provide support for it through the [web-console-pry] project. Visit it's
-[home page][web-console-pry] for more information.
+**If you ever decide to use _Web Console_ that way, use SSL to encrypt the
+traffic, otherwise all the input can be easily sniffed!**
 
-### Rails 3
+### config.web_console.timeout
 
-For _Rails 3_ support, check out [web-console-rails3].
+You may have noticed that _Web Console_ client sends a lot of requests to the
+server. And by a lot, we really mean, **a lot** _(every few milliseconds)_.
+We do this since we can't reliably predict when the output of your command
+execution will come available, so we poll for it.
+
+This option control how much will the server wait on the process output pipe
+for input, before signalling the client to try again.
+
+Maybe some day Web Sockets or SSE can be used for more efficient communication.
+Until that day, you can use long-polling as a more efficient way of
+communication.
+
+To enable long-polling, use [Puma] as your development server and add the
+following to your configuration
+
+```ruby
+class Application < Rails::Application
+  # You have to explicitly enable the concurrency, as in development mode,
+  # the falsy config.cache_classes implies no concurrency support.
+  #
+  # The concurrency is enabled by removing the Rack::Lock middleware, which
+  # wraps each request in a mutex, effectively making the request handling
+  # synchronous.
+  config.allow_concurrency = true
+
+  # For long-polling 45 seconds timeout seems reasonable.
+  config.web_console.timeout = 45.seconds
+end
+```
+
+FAQ
+---
+
+### I'm running JRuby and the console doesn't load.
+
+While spawning processes is relatively cheap on _MRI_, this is not the case in
+_JRuby_. Spawning another processes in _JRuby_ slow. Spawning another **JRuby**
+process is even slower. Read more at the _JRuby_ [wiki].
+
+**TL;DR** Give it a bit of time, it will load.
 
 Test Drive
 ----------
@@ -139,6 +197,10 @@ To try it, install [Docker] first and then run the following snippet in your she
 sudo docker build -t gsamokovarov/web-console github.com/gsamokovarov/web-console && sudo docker run -i -t !#:3
 ```
 
-  [web-console-pry]: https://github.com/gsamokovarov/web-console-pry
-  [web-console-rails3]: https://github.com/gsamokovarov/web-console-rails3
   [Docker]: http://www.docker.io/
+  [Puma]: http://puma.io/
+  [VT100]: http://en.wikipedia.org/wiki/VT100
+  [login]: http://linux.die.net/man/1/login
+  [video]: http://www.youtube.com/watch?v=zjuJRXCLkHk
+  [web-console-rails3]: https://github.com/gsamokovarov/web-console-rails3
+  [wiki]: https://github.com/jruby/jruby/wiki/Improving-startup-time#avoid-spawning-sub-rubies

lib/web_console/version.rb

@@ -1,3 +1,3 @@
 module WebConsole
-  VERSION = '0.2.0'
+  VERSION = '0.3.0'
 end