NAME

HTTP::Proxy::GreaseMonkey - Run GreaseMonkey scripts in any browser

VERSION

This document describes HTTP::Proxy::GreaseMonkey version 0.05

SYNOPSIS

    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;
  

DESCRIPTION

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.

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.

Mac OS

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.

Other Platforms

Patches welcome from anyone who has equivalent instructions for other platforms.

Compatibility

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:

    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;

Supported Functions

The GM_registerMenuCommand function is not supported; it makes no sense in a proxied environment.

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_log outputs log messages to any TTY that the proxy is attached to. Log output does not appear in the browser.

GM_xmlhttpRequest forwards requests via the proxy to bypass the browser's cross site scripting policy.

Performance

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.

Security

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.

INTERFACE

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.

CONFIGURATION AND ENVIRONMENT

HTTP::Proxy::GreaseMonkey requires no configuration files or environment variables.

DEPENDENCIES

None.

INCOMPATIBILITIES

None reported.

BUGS AND LIMITATIONS

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.

AUTHOR

Andy Armstrong <andy@hexten.net>

LICENCE AND COPYRIGHT

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.