HTTP::Proxy::GreaseMonkey - Run GreaseMonkey scripts in any browser
This document describes HTTP::Proxy::GreaseMonkey version 0.05
use HTTP::Proxy; use HTTP::Proxy::GreaseMonkey; my $proxy = HTTP::Proxy->new( port => 8030 ); my $gm = HTTP::Proxy::GreaseMonkey->new; $gm->add_script( 'gm/myscript.js' ); $proxy->push_filter( mime => 'text/html', response => $gm ); $proxy->start;
GreaseMonkey allows arbitrary user defined Javascript to be run against specific pages. Unfortunately GreaseMonkey only works with FireFox.
HTTP::Proxy::GreaseMonkey creates a local HTTP proxy that allows GreaseMonkey user scripts to be used with any browser.
HTTP::Proxy::GreaseMonkey
When you install HTTP::Proxy::GreaseMonkey a program called gmproxy is installed in your default bin directory. To launch the GreaseMonkey proxy issue a command something like this:
$ gmproxy ~/.userscripts
By default the proxy will listen on port 8030. The supplied directory is scanned before each request; any scripts that have been updated or added will be reloaded and any that have been deleted will be discarded.
On MacOS net.hexten.gmproxy.plist is created in the project home directory. Create a directory called ~/.userscripts and then add gmproxy as a launch item:
$ cp net.hexten.gmproxy.plist ~/Library/LaunchAgents $ launchctl load ~/Library/LaunchAgents/net.hexten.gmproxy.plist $ launchctl start net.hexten.gmproxy
Then change your network settings to route HTTP through proxy localhost:8030. Once this is done gmproxy will load automatically when you log in.
Important: As of 2007-12-17 PubSubAgent crashes periodically (actually during .mac synchronisation) when HTTP is proxied. The solution appears to be to add *.mac.com to the list of domains that bypass the proxy. As far as I'm aware this is a Mac OS problem that has nothing specifically to do with HTTP::Proxy::GreaseMonkey.
Patches welcome from anyone who has equivalent instructions for other platforms.
For maximum GreaseMonkey compatibility this module must be used in conjunction with HTTP::Proxy::GreaseMonkey::Redirector which provides compatibility services within the proxy. The easiest way to achieve this is to use the gmproxy command line program. If you're rolling your own proxy use something like this to install the necessary filters:
gmproxy
my $proxy = HTTP::Proxy->new( port => $self->port, start_servers => $self->servers ); my $gm = HTTP::Proxy::GreaseMonkey::ScriptHome->new; $gm->verbose( $self->verbose ); my @dirs = map glob, @args; $gm->add_dir( @dirs ); $proxy->push_filter( mime => 'text/html', response => $gm ); # Make the redirector my $redir = HTTP::Proxy::GreaseMonkey::Redirector->new; $redir->passthru( $gm->get_passthru_key ); $redir->state_file( File::Spec->catfile( $dirs[0], 'state.yml' ) ) if @dirs; $proxy->push_filter( request => $redir, ); $proxy->start;
The GM_registerMenuCommand function is not supported; it makes no sense in a proxied environment.
GM_registerMenuCommand
GM_setValue and GM_getValue operate on a YAML encoded state file which, by default, is stored in the first named user scripts directory.
GM_setValue
GM_getValue
GM_log outputs log messages to any TTY that the proxy is attached to. Log output does not appear in the browser.
GM_log
GM_xmlhttpRequest forwards requests via the proxy to bypass the browser's cross site scripting policy.
GM_xmlhttpRequest
GM_setValue, GM_getValue and GM_log talk to the proxy using synchronous JSONRPC - so they're a little slow. It remains to be seen whether this is a problem for typical GreaseMonkey scripts.
I believe it would be possible for a specially crafted page that was aware of this implementation to access the GM_xmlhttpRequest backdoor and make cross-site HTTP requests.
I'll attempt to plug that security hole in a future release.
add_script( $script )
Add a GM script to the proxy. The argument may be the filename of a script or an existing HTTP::Proxy::GreaseMonkey::Script.
verbose
Set / get verbosity.
get_passthru_key
Get the passthru key that is used to signal to the proxy that it should rewrite request URLs.
get_gm_globals
Return a block of Javascript that initialises various globals that are required by the GreaseMonkey environment.
get_support_script
Returns a block of Javascript that is injected before any user scripts. Typically this code provides the GM_* support functions.
init
Called to initialise the filter.
will_modify
Will this filter modify content? Called by HTTP::Proxy.
begin
Called at the start of processing.
filter
The filter entry point. Called for each chunk of input.
end
Finished processing.
HTTP::Proxy::GreaseMonkey requires no configuration files or environment variables.
None.
None reported.
No bugs have been reported.
Please report any bugs or feature requests to bug-http-proxy-greasemonkey@rt.cpan.org, or through the web interface at http://rt.cpan.org.
bug-http-proxy-greasemonkey@rt.cpan.org
Andy Armstrong <andy@hexten.net>
<andy@hexten.net>
Copyright (c) 2007, Andy Armstrong <andy@hexten.net>.
This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.
To install HTTP::Proxy::GreaseMonkey, copy and paste the appropriate command in to your terminal.
cpanm
cpanm HTTP::Proxy::GreaseMonkey
CPAN shell
perl -MCPAN -e shell install HTTP::Proxy::GreaseMonkey
For more information on module installation, please visit the detailed CPAN module installation guide.