Sysproxy

https://github.com/zzzgydi/sysproxy-rs
Admin
Sysproxy is a Rust library for getting and setting system proxy settings across Windows, macOS, and...
Tokens:4,987
Snippets:32
Trust Score:8.1
License:MIT
Update:5 months ago
Show doc for...
Tokens:
Raw
### Get Current Autoproxy Settings

Source: https://context7.com/zzzgydi/sysproxy-rs/llms.txt

Reads the current PAC-based auto proxy settings from the OS. Handles potential errors during the read operation.

```rust
use sysproxy::Autoproxy;

fn check_auto_proxy() {
    match Autoproxy::get_auto_proxy() {
        Ok(ap) => {
            if ap.enable {
                println!("Auto proxy is active, PAC URL: {}", ap.url);
            } else {
                println!("Auto proxy is disabled");
            }
        }
        Err(e) => eprintln!("Error reading auto proxy: {}", e),
    }
}
```

--------------------------------

### Read and Set System Proxy with Sysproxy

Source: https://context7.com/zzzgydi/sysproxy-rs/llms.txt

Demonstrates how to check platform support, read current proxy settings, enable a new proxy configuration, and disable the proxy. Ensure the platform is supported before proceeding.

```rust
use sysproxy::Sysproxy;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Check platform support
    assert!(Sysproxy::is_support(), "Platform not supported");

    // Read the current system proxy
    let current = Sysproxy::get_system_proxy()?;
    println!("Proxy enabled: {}", current.enable);
    println!("Host: {}:{}", current.host, current.port);
    println!("Bypass: {}", current.bypass);

    // Enable a proxy
    let proxy = Sysproxy {
        enable: true,
        host: "127.0.0.1".into(),
        port: 7890,
        bypass: "localhost,127.0.0.1".into(),
    };
    proxy.set_system_proxy()?;
    println!("Proxy set successfully");

    // Disable the proxy (keep host/port values, just toggle enable)
    let mut disabled = proxy.clone();
    disabled.enable = false;
    disabled.set_system_proxy()?;
    println!("Proxy disabled");

    Ok(())
}
```

--------------------------------

### Enable System Proxy

Source: https://context7.com/zzzgydi/sysproxy-rs/llms.txt

Configures the system proxy with the specified host and port, including a bypass list. It then verifies the change by reading the proxy settings again.

```rust
use sysproxy::Sysproxy;

fn enable_proxy(host: &str, port: u16) -> sysproxy::Result<()> {
    let proxy = Sysproxy {
        enable: true,
        host: host.to_string(),
        port,
        // Windows uses semicolons internally, but this library accepts commas
        bypass: "localhost,127.0.0.1,192.168.*".to_string(),
    };
    proxy.set_system_proxy()?;
    println!("System proxy set to {}:{}", host, port);

    // Verify the change was applied
    let check = Sysproxy::get_system_proxy()?;
    assert_eq!(check.host, host);
    assert_eq!(check.port, port);
    assert!(check.enable);
    Ok(())
}
```

--------------------------------

### Set System Autoproxy Configuration

Source: https://context7.com/zzzgydi/sysproxy-rs/llms.txt

Applies PAC-based proxy settings to the OS. Verifies the configuration immediately after setting.

```rust
use sysproxy::Autoproxy;

fn configure_pac_proxy(pac_url: &str) -> sysproxy::Result<()> {
    let proxy = Autoproxy {
        enable: true,
        url: pac_url.to_string(),
    };
    proxy.set_auto_proxy()?;

    // Verify
    let check = Autoproxy::get_auto_proxy()?;
    assert!(check.enable);
    assert_eq!(check.url, pac_url);
    println!("PAC proxy configured: {}", pac_url);
    Ok(())
}
```

--------------------------------

### Autoproxy Configuration

Source: https://context7.com/zzzgydi/sysproxy-rs/llms.txt

Demonstrates how to read, enable, and disable PAC URL-based proxy configurations using the Autoproxy struct.

```APIDOC
## `Autoproxy` Struct

The `Autoproxy` struct represents a PAC (Proxy Auto-Config) URL-based proxy configuration with two fields: `enable` (bool) and `url` (String). It is used to configure automatic proxy discovery via a `.pac` script URL instead of a static host/port.

### Example Usage
```rust
use sysproxy::Autoproxy;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    assert!(Autoproxy::is_support(), "Platform not supported");

    // Read current auto proxy setting
    let current = Autoproxy::get_auto_proxy()?;
    println!("Auto proxy enabled: {}", current.enable);
    println!("PAC URL: {}", current.url);

    // Enable auto proxy with a PAC file URL
    let auto = Autoproxy {
        enable: true,
        url: "http://192.168.1.1:1080/proxy.pac".into(),
    };
    auto.set_auto_proxy()?;
    println!("Auto proxy configured");

    // Disable auto proxy
    let off = Autoproxy {
        enable: false,
        url: "".into(),
    };
    off.set_auto_proxy()?;
    println!("Auto proxy disabled");

    Ok(())
}
```
```

--------------------------------

### Configure Autoproxy with PAC URL

Source: https://context7.com/zzzgydi/sysproxy-rs/llms.txt

Demonstrates enabling and disabling automatic proxy configuration using a PAC file URL. Ensure the platform supports autoproxy before calling.

```rust
use sysproxy::Autoproxy;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    assert!(Autoproxy::is_support(), "Platform not supported");

    // Read current auto proxy setting
    let current = Autoproxy::get_auto_proxy()?;
    println!("Auto proxy enabled: {}", current.enable);
    println!("PAC URL: {}", current.url);

    // Enable auto proxy with a PAC file URL
    let auto = Autoproxy {
        enable: true,
        url: "http://192.168.1.1:1080/proxy.pac".into(),
    };
    auto.set_auto_proxy()?;
    println!("Auto proxy configured");

    // Disable auto proxy
    let off = Autoproxy {
        enable: false,
        url: "".into(),
    };
    off.set_auto_proxy()?;
    println!("Auto proxy disabled");

    Ok(())
}
```

--------------------------------

### Check Platform Support for Proxy Management

Source: https://context7.com/zzzgydi/sysproxy-rs/llms.txt

Checks if the current target OS supports proxy management operations using static methods. Useful for conditional logic in cross-platform applications.

```rust
use sysproxy::{Autoproxy, Sysproxy};

fn setup_proxy_if_supported() {
    if !Sysproxy::is_support() {
        println!("Proxy management not supported on this platform");
        return;
    }
    if !Autoproxy::is_support() {
        println!("Auto proxy not supported on this platform");
        return;
    }

    let proxy = Sysproxy {
        enable: true,
        host: "10.0.0.1".into(),
        port: 8080,
        bypass: "localhost".into(),
    };

    match proxy.set_system_proxy() {
        Ok(_) => println!("Proxy configured"),
        Err(e) => eprintln!("Failed: {}", e),
    }
}
```

--------------------------------

### Add Sysproxy to Cargo.toml

Source: https://context7.com/zzzgydi/sysproxy-rs/llms.txt

Shows how to include the sysproxy crate in your project's dependencies. It provides two options: one with the default 'iptools' feature enabled for CIDR utility, and another with default features disabled for a smaller binary size.

```toml
[dependencies]
# With the default iptools feature (enables utils::ipv4_cidr_to_wildcard)
sysproxy = "0.3.0"

# Without the iptools feature (smaller binary, no CIDR utility)
sysproxy = { version = "0.3.0", default-features = false }
```

--------------------------------

### Read System Proxy Configuration

Source: https://context7.com/zzzgydi/sysproxy-rs/llms.txt

Reads the current system-wide manual proxy configuration. Handles potential errors during the read operation and prints the status.

```rust
use sysproxy::Sysproxy;

fn print_system_proxy() {
    match Sysproxy::get_system_proxy() {
        Ok(proxy) => {
            if proxy.enable {
                println!("Active proxy: {}:{}", proxy.host, proxy.port);
                if !proxy.bypass.is_empty() {
                    println!("Bypass list: {}", proxy.bypass);
                }
            } else {
                println!("No proxy is currently active");
            }
        }
        Err(e) => eprintln!("Failed to read proxy: {}", e),
    }
}
```

--------------------------------

### Sysproxy::get_system_proxy

Source: https://context7.com/zzzgydi/sysproxy-rs/llms.txt

Reads the current system-wide manual proxy configuration from the OS. This method abstracts platform-specific mechanisms on macOS, Linux, and Windows.

```APIDOC
## Sysproxy::get_system_proxy

### Description
Reads the current system-wide manual proxy configuration from the OS. On macOS it queries SOCKS, HTTP, and HTTPS settings via `networksetup` and merges them. On Linux it reads from `gsettings` or KDE's `kioslaverc`. On Windows it reads `ProxyEnable`, `ProxyServer`, and `ProxyOverride` values from the `HKCU\SOFTWARE\Microsoft\Windows\CurrentVersion\Internet Settings` registry key.

### Method
`Sysproxy::get_system_proxy()`

### Parameters
None

### Response
#### Success Response
- **Sysproxy** (struct) - The current system proxy configuration, including `enable` (bool), `host` (String), `port` (u16), and `bypass` (String).

#### Response Example
```rust
Ok(Sysproxy {
    enable: true,
    host: "127.0.0.1".to_string(),
    port: 7890,
    bypass: "localhost,127.0.0.1".to_string(),
})
```
```

--------------------------------

### Sysproxy::is_support / Autoproxy::is_support

Source: https://context7.com/zzzgydi/sysproxy-rs/llms.txt

Static methods to check if the current target operating system supports proxy operations. Returns `true` for Linux, macOS, and Windows.

```APIDOC
## `Sysproxy::is_support` / `Autoproxy::is_support`

Static methods that return `true` at compile time if the current target OS is one of the supported platforms: `linux`, `macos`, or `windows`. Useful for conditional logic in cross-platform binaries to guard proxy operations.

### Example Usage
```rust
use sysproxy::{Autoproxy, Sysproxy};

fn setup_proxy_if_supported() {
    if !Sysproxy::is_support() {
        println!("Proxy management not supported on this platform");
        return;
    }
    if !Autoproxy::is_support() {
        println!("Auto proxy not supported on this platform");
        return;
    }

    let proxy = Sysproxy {
        enable: true,
        host: "10.0.0.1".into(),
        port: 8080,
        bypass: "localhost".into(),
    };

    match proxy.set_system_proxy() {
        Ok(_) => println!("Proxy configured"),
        Err(e) => eprintln!("Failed: {}", e),
    }
}
```
```

--------------------------------

### Sysproxy::set_system_proxy

Source: https://context7.com/zzzgydi/sysproxy-rs/llms.txt

Applies the `Sysproxy` configuration to the OS. This method configures HTTP, HTTPS, and SOCKS proxies along with the bypass list, or disables the proxy if `enable` is false.

```APIDOC
## Sysproxy::set_system_proxy

### Description
Applies the `Sysproxy` configuration to the OS. When `enable` is `true`, configures HTTP, HTTPS, and SOCKS proxies along with the bypass list. When `enable` is `false`, clears or disables the proxy. On Windows this calls the Win32 `InternetSetOptionW` API and triggers `INTERNET_OPTION_PROXY_SETTINGS_CHANGED` + `INTERNET_OPTION_REFRESH` to propagate changes to running applications.

### Method
`proxy_instance.set_system_proxy()`

### Parameters
This method is called on an instance of the `Sysproxy` struct.

### Request Body (Implicit via struct fields)
- **enable** (bool) - Whether to enable or disable the proxy.
- **host** (String) - The proxy server host address.
- **port** (u16) - The proxy server port.
- **bypass** (String) - A comma-separated string of hosts to bypass.

### Request Example
```rust
let proxy = Sysproxy {
    enable: true,
    host: "127.0.0.1".into(),
    port: 7890,
    bypass: "localhost,127.0.0.1".into(),
};
proxy.set_system_proxy()?;
```

### Response
#### Success Response
None (returns `()` on success)

#### Error Response
- **sysproxy::Error** - An error type if the operation fails.
```

--------------------------------

### Convert IPv4 CIDR to Wildcard for Bypass Lists

Source: https://context7.com/zzzgydi/sysproxy-rs/llms.txt

Converts IPv4 CIDR notation to wildcard strings for proxy bypass lists. Requires the 'iptools' feature to be enabled.

```rust
use sysproxy::utils::ipv4_cidr_to_wildcard;

fn build_bypass_list() -> sysproxy::Result<()> {
    // Single host range collapses to wildcard
    let loopback = ipv4_cidr_to_wildcard("127.0.0.1/8")?;
    // => ["127.*"]

    let private_16 = ipv4_cidr_to_wildcard("192.168.0.0/16")?;
    // => ["192.168.*"]

    let private_24 = ipv4_cidr_to_wildcard("10.0.0.0/24")?;
    // => ["10.0.0.*"] (or expanded range if not byte-aligned)

    let bypass = [loopback, private_16, private_24]
        .concat()
        .join(",");

    println!("Bypass list: {}", bypass); // "127.*,192.168.*,10.0.0.*"

    let proxy = sysproxy::Sysproxy {
        enable: true,
        host: "127.0.0.1".into(),
        port: 7890,
        bypass,
    };
    proxy.set_system_proxy()?;
    Ok(())
}
```

--------------------------------

### Handle Proxy Errors in Rust

Source: https://context7.com/zzzgydi/sysproxy-rs/llms.txt

Demonstrates how to handle various errors returned by sysproxy operations using a match statement. This includes specific error types like NetworkInterface, NotSupport, ParseStr, Io, and platform-specific SystemCall errors.

```rust
use sysproxy::{Error, Sysproxy};

fn handle_proxy_errors() {
    match Sysproxy::get_system_proxy() {
        Ok(proxy) => println!("Got proxy: {:?}", proxy),
        Err(Error::NetworkInterface) => {
            eprintln!("Could not detect the active network interface (macOS)");
        }
        Err(Error::NotSupport) => {
            eprintln!("Proxy is not supported in this environment");
        }
        Err(Error::ParseStr(s)) => {
            eprintln!("Failed to parse value: {}", s);
        }
        Err(Error::Io(e)) => {
            eprintln!("I/O error (process execution failed): {}", e);
        }
        #[cfg(target_os = "windows")]
        Err(Error::SystemCall(e)) => {
            eprintln!("Win32 API error: {}", e);
        }
        Err(e) => eprintln!("Other error: {}", e),
    }
}
```

--------------------------------

### Autoproxy::get_auto_proxy

Source: https://context7.com/zzzgydi/sysproxy-rs/llms.txt

Reads the current PAC-based auto proxy settings from the operating system. This method is platform-dependent and interacts with OS-specific configurations.

```APIDOC
## `Autoproxy::get_auto_proxy`

Reads the current PAC-based auto proxy settings from the OS. On macOS it calls `networksetup -getautoproxyurl`. On Linux/GNOME it reads `org.gnome.system.proxy autoconfig-url`; on KDE it reads `Proxy Config Script` from `kioslaverc`. On Windows it reads the `AutoConfigURL` registry value.

### Example Usage
```rust
use sysproxy::Autoproxy;

fn check_auto_proxy() {
    match Autoproxy::get_auto_proxy() {
        Ok(ap) => {
            if ap.enable {
                println!("Auto proxy is active, PAC URL: {}", ap.url);
            } else {
                println!("Auto proxy is disabled");
            }
        }
        Err(e) => eprintln!("Error reading auto proxy: {}", e),
    }
}
```
```

--------------------------------

### utils::ipv4_cidr_to_wildcard

Source: https://context7.com/zzzgydi/sysproxy-rs/llms.txt

Converts an IPv4 CIDR notation string into wildcard strings for use in proxy bypass lists. This utility is helpful for dynamically generating bypass configurations.

```APIDOC
## `utils::ipv4_cidr_to_wildcard`

Converts an IPv4 CIDR notation string (e.g., `"192.168.0.0/16"`) into one or more wildcard strings (e.g., `["192.168.*"]`) suitable for use in proxy bypass lists. This is particularly useful when constructing the `bypass` field of a `Sysproxy` from network range specifications. Requires the default `iptools` feature.

### Example Usage
```rust
use sysproxy::utils::ipv4_cidr_to_wildcard;

fn build_bypass_list() -> sysproxy::Result<()> {
    // Single host range collapses to wildcard
    let loopback = ipv4_cidr_to_wildcard("127.0.0.1/8")?;
    // => ["127.*"]

    let private_16 = ipv4_cidr_to_wildcard("192.168.0.0/16")?;
    // => ["192.168.*"]

    let private_24 = ipv4_cidr_to_wildcard("10.0.0.0/24")?;
    // => ["10.0.0.*"] (or expanded range if not byte-aligned)

    let bypass = [loopback, private_16, private_24]
        .concat()
        .join(",");

    println!("Bypass list: {}", bypass); // "127.*,192.168.*,10.0.0.*"

    let proxy = sysproxy::Sysproxy {
        enable: true,
        host: "127.0.0.1".into(),
        port: 7890,
        bypass,
    };
    proxy.set_system_proxy()?;
    Ok(())
}
```
```

--------------------------------

### Autoproxy::set_auto_proxy

Source: https://context7.com/zzzgydi/sysproxy-rs/llms.txt

Applies PAC-based proxy settings to the operating system. This method allows enabling or disabling the auto proxy configuration and setting a specific PAC URL.

```APIDOC
## `Autoproxy::set_auto_proxy`

Applies PAC-based proxy settings to the OS. When `enable` is `true`, sets the system to use the provided `url` as the auto-config URL. When `enable` is `false`, clears the auto proxy configuration. On KDE this writes to both `gsettings` and `kioslaverc` to maintain consistency across interfaces.

### Example Usage
```rust
use sysproxy::Autoproxy;

fn configure_pac_proxy(pac_url: &str) -> sysproxy::Result<()> {
    let proxy = Autoproxy {
        enable: true,
        url: pac_url.to_string(),
    };
    proxy.set_auto_proxy()?;

    // Verify
    let check = Autoproxy::get_auto_proxy()?;
    assert!(check.enable);
    assert_eq!(check.url, pac_url);
    println!("PAC proxy configured: {}", pac_url);
    Ok(())
}
```
```

--------------------------------

### Disable System Proxy

Source: https://context7.com/zzzgydi/sysproxy-rs/llms.txt

Disables the currently configured system proxy by setting its enable flag to false and applying the changes.

```rust
use sysproxy::Sysproxy;

fn disable_proxy() -> sysproxy::Result<()> {
    let mut proxy = Sysproxy::get_system_proxy()?;
    proxy.enable = false;
    proxy.set_system_proxy()?;
    println!("Proxy disabled");
    Ok(())
}
```
Tokens:
Raw