Package to setup system wide HTTP(S) Proxy on Desktop Platforms

x/sysproxy/README.md

@@ -0,0 +1,32 @@
+# Platform support
+
+The table below summarizes system-wide support this package offers for various types of proxies on desktop platforms.
+
+| Proxy Type | Windows | MacOS | Linux |
+| --- | ----------- | ------ | ------ |
+| HTTP | Yes | Yes | Yes
+| HTTPS | Yes | Yes | Yes
+| SOCKS | No | Yes | Yes
+
+
+`SetupWebProxy` implementation in this package setups both HTTP and HTTPS proxy when they distinguished by the platform. `SetupSOCKSProxy` sets up SOCKS proxy that proxies all TCP-based connections.
+
+For example, on MacOS, if you have HTTP Proxy setup and visit a website over HTTPS, your traffic does NOT go through the proxy. 
+
+However, if only HTTPS proxy is setup, both HTTP and HTTPS requests go through the HTTPS proxy.
+
+If SOCKS is setup, both HTTP and HTTPS requests go through the proxy since it is performed at the TCP layer. SOCKS does not support UDP.
+
+On Windows, The client only supports SOCKS4 spec and cannot connecto SOCKS5 proxy.
+
+Support for FTP Proxy setting was not included due lack of adoption and usage. Username and password authentication was not included due to potential unreliability and untestd behavior. Please note that in SOCKS and HTTP proxy, credentials are communicated in plain text.
+
+If you have a need for any of those, feel free to open an issue and let me know about the use case.
+
+## Other notes
+
+1. Windows does not explicitly distinguish between HTTP and HTTPS proxy. Also, username/password support authentication is not supported.
+
+2. MacOS SOCKS client does not seems to correctly support authentication even thoguh it accepts credentials [[ref](https://discussions.apple.com/thread/255394737?sortBy=best)].
+
+3. On GNOME, username/Pass authenticartion is not currently supported for HTTPS proxy [[ref](https://gitlab.gnome.org/GNOME/gsettings-desktop-schemas/-/issues/42)].

x/sysproxy/doc.go

@@ -0,0 +1,80 @@
+// Copyright 2024 Jigsaw Operations LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+/*
+Package sysproxy provides a simple interface to set/unset system-wide proxy settings.
+
+# Platform Support
+
+Currently this package supports desktop platforms only. The following platforms are supported:
+  - macOS
+  - Linux (Gnome)
+  - Windows
+
+# macOS
+
+To configure proxy settings on macOS, we use networksetup utility with following options. To set web proxy:
+
+	networksetup -setwebproxy <networkservice> <domain> <portnumber>
+
+To set secure web proxy:
+
+	networksetup -setsecurewebproxy <networkservice> <domain> <portnumber>
+
+For more information, see the link [here].
+
+# Linux
+
+Currently only GNOME is supported. This package uses gsettings untility to setup proxy settings. The following commands are used to set proxy settings:
+
+	gsetting set org.gnome.system.proxy.http host 'proxy.example.com'
+	gsetting set org.gnome.system.proxy.http port 8080
+
+The following parameters can be set for other types of proxies:
+
+	org.gnome.system.proxy.https
+	org.gnome.system.proxy.ftp
+	org.gnome.system.proxy.socks
+
+For more information, you can checkout the documentation for [gsettings] and its [configuration].
+
+# Windows
+
+On Windows, the package uses HKCU\Software\Microsoft\Windows\CurrentVersion\Internet Settings + InternetSetOptionW
+to setup proxy settings. For more information, you can checkout the documentation for [InternetSetOptionW].
+
+# Usage
+
+To set up system-wide proxy settings, use the [SetWebProxy] or [SetSOCKSProxy] methods to connect to a Web (HTTP & HTTPS) or SOCKS proxy.
+This function takes two arguments: the IP address / hostname and the port of the proxy server.
+
+To clear system-wide proxy settings, use the [ClearWebProxy] or [ClearSOCKSProxy] function.
+This will set the address and port to "127.0.0.1:0" and disable the proxy.
+
+To ensure that the system-wide proxy settings are unset upon program termination, it is recommended to call:
+
+	defer ClearWebProxy()
+
+	// or
+
+	defer ClearSOCKSProxy()
+
+after the setting the proxy.
+
+[here]: https://keith.github.io/xcode-man-pages/networksetup.8.html
+[gsettings]: https://github.com/GNOME/gsettings-desktop-schemas/blob/master/schemas/org.gnome.system.proxy.gschema.xml.in
+[configuration]: https://developer-old.gnome.org/ProxyConfiguration/
+[InternetSetOptionW]: https://learn.microsoft.com/en-us/windows/win32/api/wininet/nf-wininet-internetsetoptionw
+*/
+package sysproxy