Debian Codegraph @

docs/guides/proxy/index.md

raw
1 # Proxy Setup
2
3 ## Overview
4
5 Shoutrrr supports proxying HTTP requests for notification services, allowing you to route traffic through a proxy server. This can be configured using an environment variable or by customizing the HTTP client in code.
6
7 ## Usage
8
9 ### Environment Variable
10
11 Set the `HTTP_PROXY` environment variable to the proxy URL. This applies to all HTTP-based services used by Shoutrrr.
12
13 ```bash title="Set HTTP_PROXY Environment Variable"
14 export HTTP_PROXY="socks5://localhost:1337"
15 ```
16
17 ### Custom HTTP Client
18
19 Override the default HTTP client in your Go code to configure a proxy with specific transport settings.
20
21 ```go title="Configure Custom HTTP Client with Proxy"
22 import (
23 "log"
24 "net/http"
25 "net/url"
26 "time"
27 )
28
29 proxyURL, err := url.Parse("socks5://localhost:1337")
30 if err != nil {
31 log.Fatalf("Error parsing proxy URL: %v", err)
32 }
33
34 http.DefaultClient.Transport = &http.Transport{
35 Proxy: http.ProxyURL(proxyURL),
36 DialContext: (&net.Dialer{
37 Timeout: 30 * time.Second,
38 KeepAlive: 30 * time.Second,
39 }).DialContext,
40 ForceAttemptHTTP2: true,
41 MaxIdleConns: 100,
42 IdleConnTimeout: 90 * time.Second,
43 TLSHandshakeTimeout: 10 * time.Second,
44 ExpectContinueTimeout: 1 * time.Second,
45 }
46 ```
47
48 ## Examples
49
50 <!-- markdownlint-disable -->
51 ### Using Environment Variable for Proxy
52
53 !!! Example
54 ```bash title="Set Proxy and Send Notification"
55 export HTTP_PROXY="socks5://localhost:1337"
56 shoutrrr send --url "discord://abc123@123456789" --message "Hello via proxy!"
57 ```
58
59 ```text title="Expected Output"
60 Notification sent
61 ```
62
63 ### Using Custom HTTP Client in Go
64
65 !!! Example
66 ```go title="Send Notification with Proxy"
67 package main
68
69 import (
70 "log"
71 "net/http"
72 "net/url"
73 "time"
74 "github.com/nicholas-fedor/shoutrrr"
75 )
76
77 func main() {
78 proxyURL, err := url.Parse("socks5://localhost:1337")
79 if err != nil {
80 log.Fatalf("Error parsing proxy URL: %v", err)
81 }
82
83 http.DefaultClient.Transport = &http.Transport{
84 Proxy: http.ProxyURL(proxyURL),
85 DialContext: (&net.Dialer{
86 Timeout: 30 * time.Second,
87 KeepAlive: 30 * time.Second,
88 }).DialContext,
89 ForceAttemptHTTP2: true,
90 MaxIdleConns: 100,
91 IdleConnTimeout: 90 * time.Second,
92 TLSHandshakeTimeout: 10 * time.Second,
93 ExpectContinueTimeout: 1 * time.Second,
94 }
95
96 url := "discord://abc123@123456789"
97 errs := shoutrrr.Send(url, "Hello via proxy!")
98 if len(errs) > 0 {
99 for _, err := range errs {
100 log.Println("Error:", err)
101 }
102 }
103 }
104 ```
105
106 ```text title="Expected Output (Success)"
107 (No output on success)
108 ```
109
110 ```text title="Expected Output (Error)"
111 Error: failed to send message: unexpected response status code
112 ```
113 <!-- markdownlint-restore -->
114
115 ## Notes
116
117 - **Environment Variable**: `HTTP_PROXY` supports protocols like `http`, `https`, or `socks5`. It affects all HTTP-based services globally.
118 - **Custom HTTP Client**: Provides fine-grained control over proxy settings, suitable for Go applications requiring specific transport configurations.
119 - **Service Compatibility**: Ensure the proxy supports the protocol used by the service (e.g., HTTPS for Discord, SMTP).
120 - **Timeouts**: The custom client example includes a 30-second dial timeout and 10-second TLS handshake timeout, adjustable as needed.