JS Commander

About

JS Commander (jscmd for short) is an HTTP proxy server with a JavaScript console. It lets you evaluate JavaScript code in most browsers that support XmlHttpRequest. It is tested with Firefox 2, IE 6/7, Safari 2.0.4 and Opera 9 (including Wii).

The JavaScript console and the web browser can be run on different machines, so it’s especially useful if you want to debug/run JavaScript code in embedded browsers with poor keyboard support and small screens such as iPhone, iPod Touch and Wii.

Installation

First you need to intstall Ruby 1.8.5 (or later) and RubyGems. The Ruby platforms tested are Mac OS X, Linux, Windows XP (mswin32), Windows XP (cygwin) and JRuby 1.0 RC1. It works best on UNIX / Linux systems.

With RubyGems installed, you can install jscmd through the following command line:

$ sudo gem install jscmd -y

(You may or may not need sudo.)

Also you have to install eventmachine-win32 and win32-process gems on mswin32 platform. On UNIX platforms you can optionally install eventmachine gem to use embedded Stomp Server (described later).

Usage

Enter jscmd from your shell.

$ jscmd
[2007-05-04 14:38:02] INFO  WEBrick 1.3.1
[2007-05-04 14:38:02] INFO  ruby 1.8.5 (2006-08-25) [powerpc-darwin8.7.0]
[2007-05-04 14:38:02] INFO  JSCommander::ProxyServer#start: pid=681 port=9000
Press Ctrl+D to exit.
>

By default, the proxy server starts up on TCP port 9000. You can change the port using -p option. On mswin32 platform, Stomp Server is also started on TCP port 61613.

Configure your web browser to use the proxy server at localhost:9000. Once the browser connects to the proxy server, you’ll see the host name of the page you have opened in the console.

[rimo.tv]>

You can then enter any JavaScript code in the console. You can even go to another website by changing the value of the “location” object. If you go to another web site, the connection between the proxy server and the browser will be temporarily closed and it will take few seconds until the prompt shows up again.

[rimo.tv]> document.title
Rimo
[rimo.tv]> location = "http://www.yahoo.com/" 
http://www.yahoo.com/
[rimo.tv]> aborted
> 
[www.yahoo.com]>

jscmd uses readline library, so you can use Emacs-style key bindings. For instance, you can navigate through the history using Ctrl+P (or up) and Ctrl+N (or down) keys. Also you can see the auto-completion of the property name using [tab] key.

[rimo.tv]> window.a[press tab here]
window.addEventListener  window.addToBookmark     window.attachEvent       
window.addEventStream    window.alert             
[rimo.tv]> window.a

Known Issues

SSL is not supported.
The proxy server is not designed to be used with many tabs / windows opened at same time. Each tab opens persistent connection to the proxy server, so if you open multiple tabs, you will easily hit the max number of connections to the proxy server. You can raise the limit to larger value to workaround this issue. In Firefox, this value can be configured by typing “about:config” in address bar and searching for “network.http.max-persistent-connections-per-proxy”.
Also it’s pretty hard to use the console with multiple web pages opened at once because there is no way to choose which web page you send your JavaScript code to.

Advanced Features

Command Line Options

You can see the full list of available options with jscmd -h, but here’s the point:

JS Commander is split into several modules. The modules talk to each other through the messaging server. The modules available by default are:

Proxy Server, which communicates directly with web browser. It is started with -x option.
Console, which enables you to type JavaScript and see the result. It is started with -c option.
URL Forwarder, which enables you to send the URL of the page you are watching now to another browser. It is started with -u option.

You can choose which module(s) to start using these options. If you don’t specify any options at all, it is equivalent to -cx, which starts up Proxy Server and Console.

Another important option is about the messaging server. By default (on UNIX platforms), when only Proxy Server and Console are started at once, the internal messaging server is used to make a pipe between the two modules. Instead of using this internal messaging server, you can choose to start up Stomp Server as a messaging server using -S option. On mswin32 platform, Stomp Server is started by default.

Here is the typical usage of Stomp Server. You always want to run Stomp Server and Proxy Server, so that you can use the web browser normally through the proxy server without launching JavaScript Console:

$ jscmd -Sx

You sometimes want to use JavaScript Console. The following command line only starts up Console, and connects to Stomp Server running at localhost:

$ jscmd -c

You can also connect to Stomp Server using any language that support Stomp client libraries. In examples/ directory, there’s an example script written in Perl that shows the title of the web page you are watching.

Console APIs

Like FireBug, by putting console.debug(“foo”) in the JavaScript code, you can see that message in the console. Supported methods in the console object are debug, info, warn, error and log.

Also in the console, you can use a special function called dir to list the properties of the object.

[rimo.tv]> dir(window)
0                       [object Window]
CSSPrimitiveValue       \nfunction CSSPrimitiveValue() { [native code] }
DOMParser               \nfunction DOMParser() { [native code] }
FlashObject             \nfunction (_1,id,w,h,_5,c,_7,_8,_9,_a,_b)\n{\n  if (...
Image                   \nfunction Image() { [native code] }
Option                  \nfunction Option() { [native code] }
...

URL Forwarder

You can send the page you are watching in your browser (say Firefox) to another browser (say, Opera running on Wii) using URL Forwarder. URL Forwarder is started by adding -u option and the web server starts up on port 9001 by default. If you open http://localhost:9001/ with Firefox, you’ll see a web page with a link which says “Open with Wii”. Drag this link into your bookmark toolbar. If you go to any web page and push this bookmark button, the same page will be opened in your Wii.

You will no longer be frustrated typing long URLs with a software keyboard in Wii :)

Forums / Bug Tracker

Please post questions and suggestions to the forums.

If you have found any bugs, please file them into the tracker.

License

JS Commander is copyrighted free software by Shinya Kasatani (kasatani at gmail.com). You can redistribute and/or modify it under the same license as Ruby. See COPYING file for details.