os-proxy

Manage system-wide proxy settings

Why?

• Cross-platform behavior.
• Uses native APIs for managing config.
• Can monitor external changes via events.

Install

npm install os-proxy --save

Usage

Get it into your program.

const osProxy = require('os-proxy');

Set the system proxy.

Tip: This is a url.format() compatible object.

osProxy.set({
    // Proxy configuration.
    hostname : 'example.com'.
    port     : 1234
})
.then(() => {
    console.log('Proxy onfiguration has finished saving.');
});

At any time, you may retrieve the current proxy configuration.

osProxy.get({
    device : 'Wi-Fi'
})
.then((config) => {
    console.log('Proxy config:', config);
})

Because proxies can also be set through system menus, osProxy has been made aware of the platform-specific configuration store and knows how to monitor its changes at the file system level. All of that is abstracted away into opt-in signals.

// Register a listener for config store changes.
osProxy.changed.always((event) => {
    console.log(
        'Someone changed the proxy settings at:', event.path,
        'That is where', process.platform, 'keeps them.'
    );
});
// Begin monitoring the config store.
osProxy.watch();

It is just as easy to stop monitoring the config store.

osProxy.unwatch();

API

get(option)

Returns a promise for the current system configuration.

option

Type: object

device

Type: string
Default: Wi-Fi

The device whose proxy configuration should be returned.

set(option)

Returns a promise for modifying the system configuration.

option

Type: object

hostname

Type: string

The hostname of the proxy to use.

port

Type: number

The port number of the proxy to use.

device

Type: string
Default: Wi-Fi

The device that should use the proxy.

enabled

Type: boolean
Default: true

Whether the proxy should be enabled or disabled after the configuration is saved.

enable()

Returns a promise for turning on proxy mode.

disable()

Returns a promise for turning off proxy mode.

toggle()

Returns a promise for reversing the on/off state of proxy mode.

clear()

Returns a promise for erasing the configuration data and disabling proxy mode.

changed

Type: Signal

An event emitter with methods like .always() and .never() for adding and removing listeners that are called when changes to the system configuration are detected, either via this library or by other means. You must call watch() in order to begin receiving events.

watch(path, option)

Start monitoring for changes to the system configuration. Events will be emitted as a changed signal.

Similar to chokidar.watch(), except path defaults to the operating system's proxy configuration file.

unwatch(path)

Stop monitoring for changes to the system configuration. Events will no longer be emitted.

Similar to chokidar.unwatch(), except path defaults to the operating system's proxy configuration file.

CLI

See os-proxy-cli to use this on the command line.

Contributing

See our contributing guidelines for more details.

1. Fork it.
2. Make a feature branch: git checkout -b my-new-feature
3. Commit your changes: git commit -am 'Add some feature'
4. Push to the branch: git push origin my-new-feature
5. Submit a pull request.

License

MPL-2.0 © Seth Holladay

Go make something, dang it.