web-console 2.0.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3ba3b9c75139d0d2ccfdbc4e676fe7206491fc64
-  data.tar.gz: 46fd6d3d95b76a757d64719d2effdb7c6a69276c
+  metadata.gz: 9668f63dcb4699154e023fe36cfc97167572f43a
+  data.tar.gz: 238fc2451d041ea8a063052ee3665edce6a4db3b
 SHA512:
-  metadata.gz: 9d55c967bb0a036e5b5343ae29af236c1e313ed29927ca7d477b9f2463a9e16d12a3f7aae53d24c13871a7caafaaba73d6bf9754da1620da4f45d95925f3714b
-  data.tar.gz: 488fa77b5fe910bc08cdf50c87ae3cebb84b91b49412621fd132095a3fbf2b6fc13cdbcf8b0e2e60262e2cc20e812f4275b09411fdf42cea8ca8f69e83af470c
+  metadata.gz: d7a8aa82a257fd3386fc0506f6af4d73c727771824e97d5474755485597dcc15ef517c9bd7b1561258d9b38c46219f1d62ae7ea6cf1e56dc23cd214fc3fa2548
+  data.tar.gz: 4707a1c5c5c4d5d2d22d8931b99fad9e91f6f411db89d364a7b381585a523aad3b23818b12f142743c0bc961b17059ebe17cec7e68235d4b93c0823487a41b99

data/README.markdown

@@ -1,105 +1,122 @@
 <p align=right>
   Documentation for:
-  <a href=https://github.com/rails/web-console/tree/v0.1.0>v0.1.0</a>
-  <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>
+  <a href=https://github.com/rails/web-console/tree/v2.0.0>v2.0.0</a>
 </p>
 
-Web Console [![Build Status](https://travis-ci.org/rails/web-console.svg?branch=master)](https://travis-ci.org/rails/web-console)
-===========
+# Web Console [![Build Status](https://travis-ci.org/rails/web-console.svg?branch=master)](https://travis-ci.org/rails/web-console)
 
-_Web Console_ is a set of debugging tools for your Rails application.
+_Web Console_ is a debugging tool for your Ruby on Rails applications.
 
-**A debugging tool in the default error page.**
+- [Installation](#installation)
+- [Runtime](#runtime)
+  - [CRuby](#cruby)
+  - [JRuby](#jruby)
+  - [Rubinius](#rubinius)
+- [Configuration](#configuration)
+- [Usage](#usage)
+- [FAQ](#faq)
+- [Credits](#credits)
 
-An interactive console is launched automatically in the default Rails error
-page. It makes it easy to inspect the stack trace and execute Ruby code in the stack
-trace's bindings.
+## Installation
 
-_(Check out [better_errors] as a great alternative for any Rack application!)_
+_Web Console_ is meant to work as a Rails plugin. To install it in your current
+application, add the following to your `Gemfile`.
 
-![image](https://cloud.githubusercontent.com/assets/705116/3825943/a010af92-1d5a-11e4-84c2-4ed0ba367f4e.gif)
+```ruby
+group :development do
+  gem 'web-console', '~> 2.0'
+end
+```
 
-**A debugging tool in your controllers and views.**
+After you save the `Gemfile` changes, make sure to run `bundle install` and
+restart your server for the _Web Console_ to kick in.
 
-Drop `<%= console %>` anywhere in a view to launch an interactive console
-session and execute code in it. Drop `console` anywhere in a controler and do
-the same in the context of the controller action.
+## Runtime
 
-![image](https://cloud.githubusercontent.com/assets/705116/3825939/7e284de0-1d5a-11e4-9896-81465a38da76.gif)
+_Web Console_ uses [John Mair]'s [binding_of_caller] to spawn a console in a
+specific binding. This comes at the price of limited Ruby runtime support.
 
-Requirements
-------------
+### CRuby
 
-_Web Console_ has been tested on the following rubies.
+CRuby 1.9.2 and below is **not** supported.
 
-* _MRI Ruby_ 2.1.0
-* _MRI Ruby_ 2.0.0
-* _MRI Ruby_ 1.9.3
+### JRuby
 
-There is an experimental _JRuby_ 1.7 support. See Installation section for more
-information.
+JRuby needs to run in interpreted mode. You can enable it by:
 
-_Web Console_ is built explicitly for _Rails 4_.
+```bash
+export JRUBY_OPTS=-J-Djruby.compile.mode=OFF
 
-Installation
-------------
+# If you run JRuby 1.7.12 and above, you can use:
+export JRUBY_OPTS=--dev
+```
 
-To install it in your current application, add the following to your `Gemfile`.
+An unstable version of [binding_of_caller] is needed as the latest stable one
+won't compile on _JRuby_. To install it, put the following in your application
+`Gemfile`:
 
 ```ruby
 group :development do
-  gem 'web-console', '~> 2.0'
+  gem 'binding_of_caller', '0.7.3.pre1'
 end
 ```
 
-If you are running JRuby, you can get experimental support with adding a
-pre-release version of [binding_of_caller].
+Only _JRuby_ 1.7, is supported (no JRuby 9K support at the moment).
 
-```ruby
-group :development do
-  gem 'web-console', '~> 2.0'
+### Rubinius
 
-  gem 'binding_of_caller', '0.7.3.pre1'
-end
+Internal errors like `ZeroDevisionError` aren't caught.
+
+## Usage
+
+The web console allows you to create an interactive Ruby session in your
+browser. Those sessions are launched automatically in case on an error, but
+they can also be launched manually in in any page.
+
+For example, calling `console` in a view will display a console in the current
+page in the context of the view binding.
+
+```html
+<% console %>
 ```
 
-After you save the `Gemfile` changes, make sure to run `bundle install` and
-restart your server for the _Web Console_ to kick in.
+Calling `console` in a controller will result in a console in the context of
+the controller action:
 
-Configuration
--------------
+```ruby
+class PostsController < ApplicationController
+  def new
+    console
+    @post = Post.new
+  end
+end
+```
 
-> Today we have learned in the agony of war that great power involves great
-> responsibility.
->
-> -- <cite>Franklin D. Roosevelt</cite>
+Only one `console` invocation is allowed per request. If you happen to have
+multiple ones, a `WebConsole::DoubleRenderError` is raised.
 
-_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.
+## Configuration
+
+_Web Console_ allows you to execute arbitrary code on the server, so you
+should be very careful, who you give access to.
 
 ### config.web_console.whitelisted_ips
 
-By default, only requests coming from `127.0.0.1` are allowed.
+By default, only requests coming from IPv4 and IPv6 localhosts 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 `192.168.0.100`. You can do this:
+You can whitelist single IP's or whole networks. Say you want to share your
+console with `192.168.0.100`. You can do this:
 
 ```ruby
 class Application < Rails::Application
-  config.web_console.whitelisted_ips = %w( 127.0.0.1 192.168.0.100 )
+  config.web_console.whitelisted_ips = '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!
-
-If you want to whitelist a whole network, you can do:
+If you want to whitelist the whole private network, you can do:
 
 ```ruby
 class Application < Rails::Application
@@ -107,46 +124,76 @@ class Application < Rails::Application
 end
 ```
 
-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.
-
-Credits
--------
+Take a note that IPv4 and IPv6 localhosts are always allowed. This wasn't the
+case in 2.0.
 
-* Shoutout to [Charlie Somerville] for [better_errors]! Most of the exception
-  binding code is coming straight out of the [better_errors] project.
+### config.web_console.whiny_requests
 
-* _Web Console_ wouldn't be possible without the work [John Mair] put in
-  [binding_of_caller]. This is the technology that let us execute a console
-  right where an error occurred.
+When a console cannot be shown for a given IP address or content type, a
+messages like the following is printed in the server logs:
 
-* Thanks to [Charles Oliver Nutter] for all the JRuby feedback and support he
-  has given us.
+> Cannot render console from 192.168.1.133! Allowed networks:
+> 127.0.0.0/127.255.255.255, ::1
 
-FAQ
----
+If you don't wanna see this message anymore, set this option to `false`:
 
-### I'm running JRuby and there's no console on the default error page.
+```ruby
+class Application < Rails::Application
+  config.web_console.whiny_requests = false
+end
+```
 
-You would also have to run you Rails server in JRuby's interpreted mode. Enable
-it with code snippet below, then start your development Rails server with
-`rails server`, as usual.
+### config.web_console.templates_path
 
-```bash
-export JRUBY_OPTS=-J-Djruby.compile.mode=OFF
+If you wanna style the console yourself, you can place `style.css` at a
+directory pointed by `config.web_console.templates_path`:
 
-# If you run JRuby 1.7.12 and above, you can use:
-# export JRUBY_OPTS=--dev
+```ruby
+class Application < Rails::Application
+  config.web_console.templates_path = 'app/views/web_console'
+end
 ```
 
+You may wanna check the [templates] folder at the source tree for the files you
+may override.
+
+## FAQ
+
+### Where did /console go?
+
+The remote terminal emulator was extracted in its own gem that is no longer
+bundled with _Web Console_.
+
+If you miss this feature, check out [rvt].
+
+### Why I constantly get unavailable session errors?
+
+All of _Web Console_ sessions are stored in memory. If you happen to run on a
+multi-process server (like Unicorn) you may get unavailable session errors
+while the server is still running. This is because a request may hit a
+different worker (process) that doesn't have the desired session in memory.
+
+To avoid that, if you use such servers in development, configure them so they
+server requests only out of one process.
+
 ### How to inspect local and instance variables?
 
 The interactive console executes Ruby code. Invoking `instance_variables` and
 `local_variables` will give you what you want.
 
-  [better_errors]: https://github.com/charliesome/better_errors
-  [binding_of_caller]: https://github.com/banister/binding_of_caller
-  [Charlie Somerville]: https://github.com/charliesome
-  [John Mair]: https://github.com/banister
-  [Charles Oliver Nutter]: https://github.com/headius
+## Credits
+
+* Shoutout to [Charlie Somerville] for [better_errors] and [this] code.
+* Kudos to [John Mair] for [binding_of_caller].
+* Thanks to [Charles Oliver Nutter] for all the _JRuby_ feedback.
+* Hugs and kisses to all of our [contributors].
+
+[better_errors]: https://github.com/charliesome/better_errors
+[binding_of_caller]: https://github.com/banister/binding_of_caller
+[Charlie Somerville]: https://github.com/charliesome
+[John Mair]: https://github.com/banister
+[Charles Oliver Nutter]: https://github.com/headius
+[templates]: https://github.com/rails/web-console/tree/master/lib/web_console/templates
+[this]: https://github.com/rails/web-console/blob/master/lib/web_console/integration/cruby.rb#L20-L32
+[rvt]: https://github.com/gsamokovarov/rvt
+[contributors]: https://github.com/rails/web-console/graphs/contributors

data/lib/web_console.rb

@@ -1,22 +1,23 @@
 require 'binding_of_caller'
 
 require 'active_support/lazy_load_hooks'
-require 'action_dispatch/exception_wrapper'
-require 'action_dispatch/debug_exceptions'
+require 'active_support/logger'
 
-require 'web_console/core_ext/exception'
-require "web_console/view_helpers"
-require "web_console/controller_helpers"
-require 'web_console/engine'
-require 'web_console/repl'
-require 'web_console/repl_session'
-require 'web_console/unsupported_platforms'
+require 'web_console/integration'
+require 'web_console/railtie'
+require 'web_console/errors'
+require 'web_console/helper'
+require 'web_console/evaluator'
+require 'web_console/session'
+require 'web_console/template'
+require 'web_console/middleware'
+require 'web_console/whitelist'
+require 'web_console/request'
+require 'web_console/whiny_request'
 
 module WebConsole
-  # Shortcut the +WebConsole::Engine.config.web_console+.
-  def self.config
-    Engine.config.web_console
-  end
+  mattr_accessor :logger
+  @@logger = ActiveSupport::Logger.new($stderr)
 
   ActiveSupport.run_load_hooks(:web_console, self)
 end

data/lib/web_console/errors.rb

@@ -0,0 +1,7 @@
+module WebConsole
+  # The base class for every Web Console related error.
+  Error = Class.new(StandardError)
+
+  # Raised when there is an attempt to render a console more than once.
+  DoubleRenderError = Class.new(Error)
+end

data/lib/web_console/{repl.rb → evaluator.rb}

@@ -1,10 +1,11 @@
 module WebConsole
-  # Simple read–eval–print implementation.
+  # Simple Ruby code evaluator.
   #
-  # Provides only the most basic code evaluation with no multiline code
-  # support.
-  class REPL
-    # Cleanses exceptions raised inside #send_input.
+  # This class wraps a +Binding+ object and evaluates code inside of it. The
+  # difference of a regular +Binding+ eval is that +Evaluator+ will always
+  # return a string and will format exception output.
+  class Evaluator
+    # Cleanses exceptions raised inside #eval.
     cattr_reader :cleaner
     @@cleaner = ActiveSupport::BacktraceCleaner.new
     @@cleaner.add_silencer { |line| line.start_with?(File.expand_path('..', __FILE__)) }
@@ -13,11 +14,7 @@ module WebConsole
       @binding = binding
     end
 
-    def prompt
-      '>> '
-    end
-
-    def send_input(input)
+    def eval(input)
       "=> #{@binding.eval(input).inspect}\n"
     rescue Exception => exc
       format_exception(exc)

data/lib/web_console/helper.rb

@@ -0,0 +1,22 @@
+module WebConsole
+  module Helper
+    # Communicates with the middleware to render a console in a +binding+.
+    #
+    # If +bidning+ isn't explicitly given, Binding#of_caller will be used to
+    # get the binding of the previous frame. E.g. the one that invoked
+    # +console+.
+    #
+    # Raises DoubleRenderError if a double +console+ invocation per request is
+    # detected.
+    def console(binding = nil)
+      raise DoubleRenderError if request.env['web_console.binding']
+
+      request.env['web_console.binding'] = binding || ::Kernel.binding.of_caller(1)
+
+      # Make sure nothing is rendered from the view helper. Otherwise
+      # you're gonna see unexpected #<Binding:0x007fee4302b078> in the
+      # templates.
+      nil
+    end
+  end
+end

data/lib/web_console/integration.rb

@@ -0,0 +1,8 @@
+case RUBY_ENGINE
+when 'rbx'
+  require 'web_console/integration/rubinius'
+when 'jruby'
+  require 'web_console/integration/jruby'
+when 'ruby'
+  require 'web_console/integration/cruby'
+end

data/lib/web_console/integration/jruby.rb

@@ -0,0 +1,111 @@
+require 'English'
+require 'active_support/core_ext/string/strip'
+
+java_import org.jruby.RubyInstanceConfig
+
+module WebConsole
+  module JRuby
+    class << self
+      # Returns whether JRuby is ran in interpreted mode.
+      def interpreted_mode?
+        compile_mode     = ::JRuby.runtime.instance_config.compile_mode
+        interpreted_mode = RubyInstanceConfig::CompileMode::OFF
+
+        compile_mode == interpreted_mode
+      end
+
+      # A proc to be used in Kernel#set_trace_func.
+      #
+      # It sets Exception#bindings for an error with all the bindings the
+      # current ThreadContext contains.
+      def set_exception_bindings_trace_func
+        proc do |event, file, line, id, binding, classname|
+          case event
+          when 'raise'
+            if $ERROR_INFO.bindings.empty?
+              # binding_of_caller will generate an improperly built binding at
+              # caller[1]. Every call to a non existent method, constant or a
+              # local variable will result in a Java NullPointerException.
+              #
+              # The binding that Kernel#set_trace_func is giving us is properly
+              # built, so we can use in place of the broken one.
+              bindings = ::Kernel.binding.callers.drop(2).unshift(binding)
+              $ERROR_INFO.instance_variable_set(:@bindings, bindings)
+            end
+          end
+        end
+      end
+    end
+
+    # A fake binding for JRuby in non interpreted mode.
+    #
+    # It won't actually evaluate any code, rather it will tell the user how to
+    # enable interpreted mode.
+    class FakeJRubyBinding
+      TURN_ON_INTERPRETED_MODE_TEXT = <<-END.strip_heredoc
+        JRuby needs to run in interpreted mode for introspection support.
+
+        To turn on interpreted mode, put -J-Djruby.compile.mode=OFF in the
+        JRUBY_OPTS environment variable.
+      END
+
+      def TURN_ON_INTERPRETED_MODE_TEXT.inspect
+        self
+      end
+
+      TURN_ON_INTERPRETED_MODE_TEXT.freeze
+
+      def eval(*)
+        TURN_ON_INTERPRETED_MODE_TEXT
+      end
+    end
+
+    # A fake array of FakeJRubyBinding objects.
+    #
+    # It is used in Exception#bindings to make sure that when users switch
+    # bindings on the UI, they get a FakeJRubyBinding notifying them what to do
+    # if they want introspection.
+    class FakeJRubyBindingsArray < Array
+      def [](*)
+        FakeJRubyBinding.new
+      end
+
+      # For Kernel#Array and other implicit conversion API. JRuby expects it to
+      # return an object that is_a? an Array. This is the reasoning of
+      # FakeJRubyBindingsArray being a subclass of Array.
+      def to_ary
+        self
+      end
+    end
+  end
+end
+
+if WebConsole::JRuby.interpreted_mode?
+  ::Exception.class_eval do
+    def bindings
+      @bindings || []
+    end
+  end
+
+  # Kernel#set_trace_func will complain about not being able to capture all the
+  # events without the JRuby --debug flag.
+  silence_warnings do
+    set_trace_func WebConsole::JRuby.set_exception_bindings_trace_func
+  end
+else
+  ::Exception.class_eval do
+    def bindings
+      WebConsole::JRuby::FakeJRubyBindingsArray.new
+    end
+  end
+
+  ::Binding.class_eval do
+    def of_caller(*)
+      WebConsole::JRuby::FakeJRubyBinding.new
+    end
+
+    def callers
+      WebConsole::JRuby::FakeJRubyBindingsArray.new
+    end
+  end
+end