From 02b0d5490cf0fe141dae02c4678758b94712a0c3 Mon Sep 17 00:00:00 2001 From: Genadi Samokovarov Date: Sat, 21 Feb 2015 18:56:53 +0200 Subject: [PATCH] Prepare for 2.1.0 release With Rails 4.2.1 coming soon, I think we can catch its release train and roll out 2.1.0. I have tweaked the README to reflect the recent changes and will put in shape the CHANGELOG. I also did a bit of cleanup that was on my list, the biggest one being, that we are no longer an engine, but a railtie as we don't use any of the engine features anymore. Another one is exposing `config.web_console.acceptable_content_types`, but only for potential user support, if we hit another Puma-like issue. I don't intend to document it in the README. --- CHANGELOG.markdown | 68 ++---- README.markdown | 217 +++++++++++------- lib/web_console.rb | 2 +- lib/web_console/{engine.rb => railtie.rb} | 16 +- lib/web_console/version.rb | 2 +- lib/web_console/whitelist.rb | 2 + .../{engine_test.rb => railtie_test.rb} | 20 +- web-console.gemspec | 4 +- 8 files changed, 189 insertions(+), 142 deletions(-) rename lib/web_console/{engine.rb => railtie.rb} (78%) rename test/web_console/{engine_test.rb => railtie_test.rb} (79%) diff --git a/CHANGELOG.markdown b/CHANGELOG.markdown index 63c907f1..89a082f6 100644 --- a/CHANGELOG.markdown +++ b/CHANGELOG.markdown @@ -1,48 +1,24 @@ # CHANGELOG -## 1.0.4 (December 13, 2013) - -* Fix Rails 4.0.2 incompatibility. [[#9](https://github.com/rails/web-console/pull/9)] - -## 1.0.3 (September 27, 2013) - -* Fallback to `rails console` if relative `bin/rails` isn't available. - -## 1.0.2 (September 24, 2013) - -* Depend on Rails 4.\* instead of 4.0.\*. - -## 1.0.1 (September 20, 2013 - -* Break rails meta-package dependency. [[#5](https://github.com/rails/web-console/pull/5)] -* Fix ActiveModel load error happening on rails -O configured apps. [[#4](https://github.com/rails/web-console/pull/4)] - -## 1.0.0 (September 16, 2013) - -* Don't throw server errors on finished slave processes. -* Add monokai color theme. - -## 0.4.0 (September 6, 2013) - -* Drop GPL dependency of vt100.js. -* Use term.js as vt100.js replacement. -* Add config.web_console.term for using custom $TERM. -* Add config.web_console.style.colors for color theming. -* Add config.web_console.style.font for using custom fonts. -* Fix ZSH repeating the first command argument on servers started inside a TMUX session. - -## 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 IRB adapters. -* Add config.web_console.prevent_irbrc_execution option. - -## 0.1.0 (July 30, 2013) - -* Initial release. +## master (unreleased) + +## 2.1.0 + +* [#109](https://github.com/rails/web-console/pull/109) Revamp unavailable session response message ([@gsamokovarov]) +* [#107](https://github.com/rails/web-console/pull/107) Fix pasting regression for all browsers ([@parterburn]) +* [#105](https://github.com/rails/web-console/pull/105) Lock scroll bottom on console window resize ([@noahpatterson]) +* [#104](https://github.com/rails/web-console/pull/104) Always whitelist localhost and inform users why no console is displayed ([@gsamokovarov]) +* [#100](https://github.com/rails/web-console/pull/100) Accept text/plain as acceptable content type for Puma ([@gsamokovarov]) +* [#98](https://github.com/rails/web-console/pull/98) Add arbitrary big z-index to the console ([@bglbruno]) +* [#88](https://github.com/rails/web-console/pull/88) Spelling fixes ([@jeffnv]) +* [#86](https://github.com/rails/web-console/pull/86) Disable autofocus when initializing the console ([@ryandao]) +* [#84](https://github.com/rails/web-console/pull/84) Allow Rails 5 as dependency in gemspec ([@jonatack]) +* [#69](https://github.com/rails/web-console/pull/69) Introduce middleware for request dispatch and console rendering ([@gsamokovarov]) + +[@jonatack]: https://github.com/jonatack +[@ryandao]: https://github.com/ryandao +[@jeffnv]: https://github.com/jeffnv +[@gsamokovarov]: https://github.com/gsamokovarov +[@bglbruno]: https://github.com/bglbruno +[@noahpatterson]: https://github.com/noahpatterson +[@parterburn]: https://github.com/parterburn diff --git a/README.markdown b/README.markdown index c4bed7b5..ebedfada 100644 --- a/README.markdown +++ b/README.markdown @@ -1,105 +1,122 @@

Documentation for: - v0.1.0 - v0.2.0 - v0.3.0 - v0.4.0 - v1.0.4 + v2.0.0

-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 controller 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. -> -> -- Franklin D. Roosevelt +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 diff --git a/lib/web_console.rb b/lib/web_console.rb index d764602e..8d6e521e 100644 --- a/lib/web_console.rb +++ b/lib/web_console.rb @@ -4,7 +4,7 @@ require 'active_support/logger' require 'web_console/integration' -require 'web_console/engine' +require 'web_console/railtie' require 'web_console/errors' require 'web_console/helper' require 'web_console/evaluator' diff --git a/lib/web_console/engine.rb b/lib/web_console/railtie.rb similarity index 78% rename from lib/web_console/engine.rb rename to lib/web_console/railtie.rb index 7d2c0189..371eeda2 100644 --- a/lib/web_console/engine.rb +++ b/lib/web_console/railtie.rb @@ -1,11 +1,7 @@ -require 'ipaddr' -require 'rails/engine' - -require 'active_model' -require 'sprockets/rails' +require 'rails/railtie' module WebConsole - class Engine < ::Rails::Engine + class Railtie < ::Rails::Railtie config.web_console = ActiveSupport::OrderedOptions.new config.web_console.whitelisted_ips = %w( 127.0.0.1 ::1 ) @@ -53,5 +49,13 @@ def render_exception_with_web_console(env, exception) Middleware.whiny_requests = config.web_console.whiny_requests end end + + # Leave this undocumented so we treat such content type misses as bugs, + # while still being able to help the affected users in the meantime. + initializer 'web_console.acceptable_content_types' do + if acceptable_content_types = config.web_console.acceptable_content_types + Request.acceptable_content_types.concat(Array(acceptable_content_types)) + end + end end end diff --git a/lib/web_console/version.rb b/lib/web_console/version.rb index d642b736..fd3d919b 100644 --- a/lib/web_console/version.rb +++ b/lib/web_console/version.rb @@ -1,3 +1,3 @@ module WebConsole - VERSION = '2.0.0' + VERSION = '2.1.0' end diff --git a/lib/web_console/whitelist.rb b/lib/web_console/whitelist.rb index 346f5622..f660f78b 100644 --- a/lib/web_console/whitelist.rb +++ b/lib/web_console/whitelist.rb @@ -1,3 +1,5 @@ +require 'ipaddr' + module WebConsole # Whitelist of allowed networks that can access Web Console. # diff --git a/test/web_console/engine_test.rb b/test/web_console/railtie_test.rb similarity index 79% rename from test/web_console/engine_test.rb rename to test/web_console/railtie_test.rb index 7c721eeb..150f4407 100644 --- a/test/web_console/engine_test.rb +++ b/test/web_console/railtie_test.rb @@ -1,7 +1,7 @@ require 'test_helper' module WebConsole - class EngineTest < ActiveSupport::TestCase + class RailtieTest < ActiveSupport::TestCase test 'config.whitelisted_ips sets whitelisted networks' do new_uninitialized_app do |app| app.config.web_console.whitelisted_ips = %w( 172.16.0.0/12 192.168.0.0/16 ) @@ -45,6 +45,17 @@ class EngineTest < ActiveSupport::TestCase end end + test 'config.acceptable_content_types adds extra content types' do + preserving_acceptable_content_type do + new_uninitialized_app do |app| + app.config.web_console.acceptable_content_types = [Mime::ALL] + app.initialize! + + assert_includes Request.acceptable_content_types, Mime::ALL + end + end + end + private def new_uninitialized_app(root = File.expand_path('../../dummy', __FILE__)) @@ -66,6 +77,13 @@ def new_uninitialized_app(root = File.expand_path('../../dummy', __FILE__)) Rails.application = old_app end + def preserving_acceptable_content_type + acceptable_content_types = Request.acceptable_content_types.dup + yield + ensure + Request.acceptable_content_types = acceptable_content_types + end + def teardown_fixtures(*) super rescue diff --git a/web-console.gemspec b/web-console.gemspec index 264cffae..4e5581fd 100644 --- a/web-console.gemspec +++ b/web-console.gemspec @@ -6,9 +6,9 @@ Gem::Specification.new do |s| s.name = "web-console" s.version = WebConsole::VERSION s.authors = ["Charlie Somerville", "Genadi Samokovarov", "Guillermo Iguaran", "Ryan Dao"] - s.email = ["gsamokovarov@gmail.com", "guilleiguaran@gmail.com", "daoduyducduong@gmail.com"] + s.email = ["charlie@charliesomerville.com", "gsamokovarov@gmail.com", "guilleiguaran@gmail.com", "daoduyducduong@gmail.com"] s.homepage = "https://github.com/rails/web-console" - s.summary = "A set of debugging tools for your Rails application." + s.summary = "A debugging tool for your Ruby on Rails applications." s.license = 'MIT' s.files = Dir["lib/**/*", "MIT-LICENSE", "Rakefile", "README.markdown"]