*** Proxy API RFC


** API

define_hook("proxy_enabled_hook");
define_hook("proxy_disabled_hook");
define_hook("proxy_profile_updated_hook");

define_keywords("$http", "$ssl", "$ftp", "$gopher", "$socks", "$socks_ver",
                "$socks_dns", "$excludes" "$ac_url", "$ac_retry_min",
                "$ac_retry_max", "$ac_timeout");
function proxy_define_profile(name) {}

define_keywords("$http", "$ssl", "$ftp", "$gopher", "$socks", "$socks_ver",
                "$excludes", "$remote_dns", "$ac_url", "$ac_retry_min",
                "$ac_retry_max", "$ac_timeout");
function proxy_update_profile(name) {}

function proxy_remove_profile(name) {}

function proxy_enable(name) {}

function proxy_disable() {}

function proxy_toggle() {}
interactive("proxy-toggle", "Toggle use of proxy.", proxy_toggle);

// Proxy modes.
PROXY_NONE        = 0;
PROXY_AUTO_DETECT = 1;
PROXY_AUTO_CONFIG = 2;
PROXY_SYSTEM      = 4;
PROXY_MANUAL      = 5;

function proxy_set_mode(mode) {}

function proxy_enable_mode_line(formatter) {}


** NOTES

* State

Changes made to the network.proxy.* preferences by any means other than this API must be noticed and
handled, otherwise its state will be inconsistent with Mozilla's. Therefore, network.proxy.* will be
watched and the situation will be handled in one of a few ways.

1. Force the pref to reset to the value defined by the current profile. Users would not be able to modify
proxy settings via about:config, for example - but neither would extensions be able to modify proxy settings.

2. Include a built-in proxy profile *Custom* which indicates that the proxy settings are no longer
controlled by this API.

3. Any other ideas?


* hooks

'enabled' is passed the profile name. 'disabled' has no arguments.

'profile_updated' is passed the profile name and exists for the sake of the mode line widget, which will
need to be notified when 'update_profile' is called on the currently-enabled profile.


* define and update functions

These accept proxy addresses in the form of 1.2.3.4 or 1.2.3.4:1234. If no port is specified, the
well-known port of 8080 is assumed for all proxies except SOCKS, which assumes 1080.

The '$ac_*' keywords correspond to Mozilla's autoconfig prefs.

Default values for all parameters correspond to Mozilla's default value, if any.


* toggle function

The implementation will remember the last profile used and toggle it when this command is called. If no
proxy was previously enabled, a message should be printed to the minibuffer saying so.


* enable_mode_line function

'formatter' is an optional argument which if present must be a function which accepts a single argument,
the name of the enabled proxy profile, or null if proxy is disabled, and returns the string printed to
the modeline.

The proxy widget's 'update' method should be added to proxy_*_hooks.