system_proxy/lib.rs
1// Copyright (c) 2022 Sebastian Wiesner <sebastian@swsnr.de>
2//
3// This Source Code Form is subject to the terms of the Mozilla Public
4// License, v. 2.0. If a copy of the MPL was not distributed with this
5// file, You can obtain one at https://mozilla.org/MPL/2.0/.
6
7#![deny(warnings, missing_docs, clippy::all)]
8
9//! Lookup HTTP proxies in various ways.
10//!
11//! ## Available proxy lookup methods
12//!
13//! - [`env::EnvProxies`] looks up HTTP proxies in the wide-spread `$http_proxy` and
14//! related environment variables. It aims to be compatible to the well-known `curl` utility.
15//! - [`unix::GioProxyResolver`] asynchronously looks up HTTP proxies through Gio and
16//! Glib, i.e. the foundational library of the Gnome desktop environment. It links against the
17//! Glib library, but in turn supports dynamic proxy configuration, i.e. proxy configuration
18//! which changes while the process is running, and proxy auto-configuration.
19//! This requires the `gio` feature.
20//! - [`unix::FreedesktopPortalProxyResolver`] asynchronously looks up HTTP proxies
21//! through the Freedesktop Portal proxy resolver over DBus. The exact features supported by
22//! this resolver depend on the portal implementation; for Gnome at least the portal has the same
23//! set of features as the Gio resolver. This resolver does not link against any native
24//! libraries, but in turn requires the [`zbus`] crate for DBus support, and a running portal
25//! implementation at runtime.
26//!
27//! # Operating system support
28//!
29//! ## Linux
30//!
31//! Use either [`unix::GioProxyResolver`] or [`unix::FreedesktopPortalProxyResolver`] to access
32//! system proxy settings.
33//!
34//! ## Windows
35//!
36//! Windows support is planned, see <https://github.com/swsnr/system_proxy.rs/issues/5>.
37//!
38//! ## macOS
39//!
40//! MacOS support may come at some point, see <https://github.com/swsnr/system_proxy.rs/issues/2>.
41
42pub mod env;
43pub mod unix;