web-console 1.0.4 → 2.0.0.beta1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 577d50cf084f3c7d66fdf4eb99b5da8ac0baf148
-  data.tar.gz: ca9605e96da6c53f080be46a1660d88bb736a183
+  metadata.gz: cc7be22774c0ed19fa1cc197bb32a8289078f9d7
+  data.tar.gz: c97418fb52eebab0ed839e4889e4154a0aeb48f7
 SHA512:
-  metadata.gz: 7d44aa991870097a0b6230ec5bcfb152dc4f66f41141ee1544500c2cbe2e8a4bd78020829896c66ce4eea188e7f70d782e5e2ef935a020086456a80c97951ee1
-  data.tar.gz: cc0dcacfc0eb21071a92791100cc96380c9a59acaaf0be54c4208b6727761ac0ac590198ae0b96eb790b10371b1ff0e79ad451148f7c7cc81e15558511e6000e
+  metadata.gz: 5edfba9b1fd714b835609e9534ba89fcb2cc7bca5c505ac5a4368e6e1218a295b5ddb129c251299a117a2976660ffef69ab2b82be28778ed805459c978a2cc41
+  data.tar.gz: 02cc4186912594113ed78a3eaf88e8f5e9ffa1bd31cbf842087de4c7cd4360d4776d04308432062c2e94c82072eb653ef63c51137ca845642db139fa83b03567

data/README.markdown

@@ -4,23 +4,19 @@
   <a href=https://github.com/rails/web-console/tree/v0.2.0>v0.2.0</a>
   <a href=https://github.com/rails/web-console/tree/v0.3.0>v0.3.0</a>
   <a href=https://github.com/rails/web-console/tree/v0.4.0>v0.4.0</a>
+  <a href=https://github.com/rails/web-console/tree/v1.0.4>v1.0.4</a>
 </p>
 
-Web Console [![Version](https://badge.fury.io/rb/web-console.png)](http://badge.fury.io/rb/web-console) [![Travis](https://travis-ci.org/rails/web-console.png)](https://travis-ci.org/rails/web-console)
-===========
-
-No doubt, `rails console` is one of the most useful commands, Rails has to
-offer. However, sometimes you can't easily access it, or maybe you want to
-share it with a coworker without configuring remote desktop server.
+<p align=center>
+  <em>Web Console is going through an overhaul, if you are looking for a stable
+  version documentation, checkout the links above.</em>
+</p>
 
-This is where _Web Console_ comes to play. It gives you the same
-`rails console` experience, right in the browser. Its not just a tool that
-let's you evaluate Ruby code, there are a lot of those. Its a [VT100]
-compatible terminal, running `rails console`.
+Web Console [![Travis](https://travis-ci.org/rails/web-console.png)](https://travis-ci.org/rails/web-console)
+===========
 
-![demo](http://f.cl.ly/items/3N3K412T381u2w360F2M/Screen%20Shot%202013-09-06%20at%208.24.57%20PM.png)
+Web Console is a debugging console for you Rails application. It is launched whenever an error occurs or manually by using the console helper.
 
-You can see _Web Console_ in action at this [video].
 
 Requirements
 ------------
@@ -29,261 +25,44 @@ _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_ is built explicitly for _Rails 4_.
 
-_Web Console_ has been built explicitly for _Rails 4_. Check out the
-[web-console-rails3] project for a _Rails 3_ compatible build.
+Dependencies
+------------
+
+Web Console is bundled with `bindings_of_caller`. Because of the dependency, the gem only works on MRI Ruby at the moment.
 
 Installation
 ------------
 
-To install it in your current application, add the following to your `Gemfile`.
-
-```ruby
-group :development do
-  gem 'web-console'
-end
-```
+Add the `web-console` gem to your Gemfile. Be sure to use the master branch version for now:
 
-After you save the `Gemfile` changes, make sure to run `bundle install` and
-restart your server for the _Web Console_ to take affect.
+    gem 'web-console', git: 'git://github.com/rails/web-console
 
-By default, it should be available in your development environment under
-`/console`. The route is not automatically mounted in a production environment
-and we strongly encourage you to keep it that way.
 
-Configuration
+Use Cases
 -------------
 
-> Today we have learned in the agony of war that great power involves great
-> responsibility.
->
-> -- <cite>Franklin D. Roosevelt</cite>
-
-_Web Console_ is a powerful tool. It allows you to execute arbitrary code on
-the server, so you should be very careful, who you give access to it.
-
-### config.web_console.whitelisted_ips
-
-By default, only requests coming from `127.0.0.1` are allowed.
-
-`config.web_console.whitelisted_ips` lets you control which IP's have access to
-the console.
-
-Let's say you want to share your console with just that one roommate, you like
-and his/her IP is `192.168.0.100`.
-
-```ruby
-class Application < Rails::Application
-  config.web_console.whitelisted_ips = %w( 127.0.0.1 192.168.0.100 )
-end
-```
-
-From the example, you can guess that `config.web_console.whitelisted_ips`
-accepts an array of ip addresses, provided as strings. An important thing to
-note here is that, we won't push `127.0.0.1` if you manually set the option!
-
-Now let's assume you like all of your roommates. Instead of enumerating their
-IP's, you can whitelist the whole private network. Now every time their IP's
-change, you'll have them covered.
-
-```ruby
-class Application < Rails::Application
-  config.web_console.whitelisted_ips = '192.168.0.0/16'
-end
-```
-
-You can see that `config.web_console.whitelisted_ips` accepts plains strings
-too. More than that, they can cover whole networks.
-
-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.default_mount_path
-
-By default, the console will be automatically mounted on `/console`.
-
-_(This happens only in the development and test environments!)_.
-
-Say you want to mount the console to `/debug`, so you can more easily remember
-where to go, when your application needs debugging.
-
-```ruby
-class Application < Rails::Application
-  config.web_console.default_mount_path = '/debug'
-end
-```
-
-### config.web_console.automount
-
-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. If the relative `bin/rails` does not exist, it
-doesn't exist, `rails console` will be run.
-
-One of the advantages of being a [VT100] emulator is that _Web Console_ can run
-most of your terminal applications.
+### Debug when an error happens
 
-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.
+Web Console is launched automatically in the default Rails error page. It's easy to inspect the stack trace and execute Ruby code in the stack trace's bindings.
 
-```ruby
-class Application < Rails::Application
-  # You have to run /bin/login as root. That should worry you and you may work
-  # around it by running ssh connecting to the same machine.
-  config.web_console.command = 'sudo /bin/login'
-end
-```
+![image](https://cloud.githubusercontent.com/assets/705116/3825943/a010af92-1d5a-11e4-84c2-4ed0ba367f4e.gif)
 
-_Poor man's solution to SSH._ ![boom](http://f.cl.ly/items/3n2h0p1w0B261u2d201b/boom.png)
+### Inspect view and controller binding
 
-**If you ever decide to use _Web Console_ that way, use SSL to encrypt the
-traffic, otherwise all the input (including the negotiated username and
-password) can be easily sniffed!**
+In your view, drop `<%= console %>` anywhere to launch the console and execute code in the view binding. A helper for running the console in the controller binding is under development.
 
-### config.web_console.term
-
-By default, the _Web Console_ terminal will report itself as `xterm-color`. You
-can override this option to change that.
-
-### config.web_console.timeout
-
-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. To enable it, 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 for the development server seems
-  # reasonable. You may want to experiment with the value.
-  config.web_console.timeout = 45.seconds
-end
-```
-
-Styling
--------
-
-If you would like to style the terminal a bit different than the default
-appearance, you can do so with the following options.
-
-### config.web_console.style.colors
-
-_Web Console_ supports up to 256 color themes, though most of the common
-terminal themes are usually just 16 colors.
-
-The default color theme is a white-on-black theme called `light`. For
-different appearance you may want to experiment with the other included color
-themes.
-
-- `monokai` _the default Sublime Text colors_
-- `solarized_dark` _light version of the common solarized colors_
-- `solarized_light` _dark version of the common solarized colors_
-- `tango` _theme based on the tango colors_
-- `xterm` _the standard xterm theme_
-
-If you would like to use a custom theme, you may do so with the following
-syntax.
-
-```ruby
-class Application < Rails::Application
-  # First, you have to define and register your custom color theme. Each color
-  # theme is mapped to a name.
-  WebConsole::Colors.register_theme(:custom) do |c|
-    # The most common color themes are the 16 colors one. They are built from 3
-    # parts.
-
-    # 8 darker colors.
-    c.add '#000000'
-    c.add '#cd0000'
-    c.add '#00cd00'
-    c.add '#cdcd00'
-    c.add '#0000ee'
-    c.add '#cd00cd'
-    c.add '#00cdcd'
-    c.add '#e5e5e5'
-
-    # 8 lighter colors.
-    c.add '#7f7f7f'
-    c.add '#ff0000'
-    c.add '#00ff00'
-    c.add '#ffff00'
-    c.add '#5c5cff'
-    c.add '#ff00ff'
-    c.add '#00ffff'
-    c.add '#ffffff'
-
-    # Background and foreground colors.
-    c.background '#ffffff'
-    c.foreground '#000000'
-  end
-
-  # Now you have to tell Web Console to actually use it.
-  config.web_console.style.colors = :custom
-end
-```
-
-### config.web_console.style.font
-
-You may also change the font, which is following the CSS font property syntax.
-By default it is `large DejaVu Sans Mono, Liberation Mono, monospace`.
-
-Trial
------
-
-If you just want to try the web-console, without having to go through the
-trouble of installing it, we provide a [Docker] container that does that for
-you.
-
-To try it, install [Docker] first and then paste the following snippet in your
-shell.
-
-```bash
-docker build -t rails/web-console github.com/rails/web-console && docker run -i -t rails/web-console
-```
+![image](https://cloud.githubusercontent.com/assets/705116/3825939/7e284de0-1d5a-11e4-9896-81465a38da76.gif)
 
 FAQ
 ---
 
-### I'm running JRuby and the console doesn't load.
-
-**TL;DR** Give it a bit of time, it will load.
-
-While spawning processes is relatively cheap on _MRI_, this is not the case in
-_JRuby_. Spawning another process is slow. Spawning another **JRuby** process
-is even slower. Read more about the problem at the _JRuby_ [wiki].
+### Is there any plan to support JRuby and Rubinius?
 
-### Changing the colors is broken.
+`bindings_of_caller` only works on MRI Ruby at the moment. There's a plan to make Web Console work with JRuby and Rubinius, but most likely without the ability to navigate exception backtrace.
 
-Some of the style sheets may be cached on the file system. Run
-`rake tmp:cache:clear` to clear those up.
+### How to get local and instance variables of a binding in the console?
 
-  [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
+The console executes Ruby code, and therefore, invoking `instance_variables` and `local_variables` will give you what you want.

data/lib/action_dispatch/debug_exceptions.rb

@@ -0,0 +1,115 @@
+module ActionDispatch
+  class DebugExceptions
+    RESCUES_TEMPLATE_PATH.replace(File.expand_path('../templates', __FILE__))
+
+    def call(env)
+      request = Request.new(env)
+
+      if request.put? && m = env["PATH_INFO"].match(%r{/repl_sessions/(?<id>.+?)\z})
+        update_repl_session(m[:id], request.params[:input])
+      elsif request.post? && m = env["PATH_INFO"].match(%r{/repl_sessions/(?<id>.+?)/trace\z})
+        change_stack_trace(m[:id], request.params[:frame_id])
+      else
+        middleware_call(env)
+      end
+    end
+
+    def middleware_call(env)
+      _, headers, body = response = @app.call(env)
+
+      if headers['X-Cascade'] == 'pass'
+        body.close if body.respond_to?(:close)
+        raise ActionController::RoutingError, "No route matches [#{env['REQUEST_METHOD']}] #{env['PATH_INFO'].inspect}"
+      end
+
+      response
+    rescue Exception => exception
+      raise exception if env['action_dispatch.show_exceptions'] == false
+      render_exception(env, exception)
+    end
+
+    private
+
+    def update_repl_session(id, input)
+      console_session = WebConsole::REPLSession.find(id)
+      response = console_session.save({ input: input })
+      [200, { "Content-Type" => "text/plain; charset=utf-8" }, [response.to_json]]
+    end
+
+    def change_stack_trace(id, frame_id)
+      console_session = WebConsole::REPLSession.find(id)
+      binding = console_session.binding_stack[frame_id.to_i]
+      console_session.binding = binding
+      [200, { "Content-Type" => "text/plain; charset=utf-8" }, [JSON.dump("success")]]
+    end
+
+    def render_exception(env, exception)
+      if exception.respond_to?(:original_exception) && exception.original_exception
+        exception = exception.original_exception
+      end
+
+      wrapper = ExceptionWrapper.new(env, exception)
+      traces = traces_from_wrapper(wrapper)
+      extract_sources = wrapper.extract_sources
+      console_session = WebConsole::REPLSession.create(
+        binding: binding_from_exception(exception),
+        binding_stack: exception.__web_console_bindings_stack
+      )
+      log_error(env, wrapper)
+
+      if env['action_dispatch.show_detailed_exceptions']
+        request = Request.new(env)
+        template = ActionView::Base.new([RESCUES_TEMPLATE_PATH],
+          request: request,
+          exception: wrapper.exception,
+          application_trace: traces[:application_trace],
+          framework_trace: traces[:framework_trace],
+          full_trace: traces[:full_trace],
+          routes_inspector: routes_inspector(exception),
+          extract_sources: extract_sources,
+          console_session: console_session
+        )
+        file = "rescues/#{wrapper.rescue_template}"
+
+        if request.xhr?
+          body = template.render(template: file, layout: false, formats: [:text])
+          format = "text/plain"
+        else
+          body = template.render(template: file, layout: 'rescues/layout')
+          format = "text/html"
+        end
+
+        [wrapper.status_code, {'Content-Type' => "#{format}; charset=#{Response.default_charset}", 'Content-Length' => body.bytesize.to_s}, [body]]
+      else
+        raise exception
+      end
+    end
+
+    # Augment the exception traces by providing ids for all unique stack frame
+    def traces_from_wrapper(wrapper)
+      id_counter = 0
+
+      application_trace = wrapper.application_trace.map do |trace|
+        prev = id_counter
+        id_counter += 1
+        { id: prev, trace: trace }
+      end
+
+      framework_trace = wrapper.framework_trace.map do |trace|
+        prev = id_counter
+        id_counter += 1
+        { id: prev, trace: trace }
+      end
+
+      {
+        application_trace: application_trace,
+        framework_trace: framework_trace,
+        full_trace: application_trace + framework_trace
+      }
+    end
+
+    def binding_from_exception(exception)
+      exception.__web_console_bindings_stack[0]
+    end
+  end
+end

data/lib/action_dispatch/exception_wrapper.rb

@@ -0,0 +1,15 @@
+module ActionDispatch
+  class ExceptionWrapper
+    def extract_sources
+      exception.backtrace.map do |trace|
+        file, line = trace.split(":")
+        line_number = line.to_i
+        {
+          code: source_fragment(file, line_number),
+          file: file,
+          line_number: line_number
+        }
+      end
+    end
+  end
+end