0
# Proxy Chaining
1

2
Sequential proxy routing through multiple proxy servers for enhanced anonymity and flexible network routing. Allows routing traffic through a chain of proxies, with each proxy in the chain connecting to the next.
3

4
## Capabilities
5

6
### ChainProxyConnector Class
7

8
Connector class that routes connections through multiple proxies in sequence, supporting mixed proxy types and configurations.
9

10
```python { .api }
11
class ChainProxyConnector:
12
    def __init__(self, proxy_infos: Iterable[ProxyInfo], **kwargs):
13
        """
14
        Create a chained proxy connector for aiohttp.
15
        
16
        Args:
17
            proxy_infos (Iterable[ProxyInfo]): Sequence of proxy configurations
18
            **kwargs: Additional arguments passed to TCPConnector
19
        """
20
```
21

22
#### Usage Examples
23

24
```python
25
import aiohttp
26
from aiohttp_socks import ChainProxyConnector, ProxyInfo, ProxyType
27

28
# Create proxy chain with ProxyInfo objects
29
proxy_chain = [
30
    ProxyInfo(
31
        proxy_type=ProxyType.SOCKS5,
32
        host='first-proxy.example.com',
33
        port=1080,
34
        username='user1',
35
        password='pass1'
36
    ),
37
    ProxyInfo(
38
        proxy_type=ProxyType.SOCKS4,
39
        host='second-proxy.example.com', 
40
        port=1081
41
    ),
42
    ProxyInfo(
43
        proxy_type=ProxyType.HTTP,
44
        host='third-proxy.example.com',
45
        port=3128,
46
        username='user3',
47
        password='pass3'
48
    )
49
]
50

51
connector = ChainProxyConnector(proxy_chain)
52

53
# Use with aiohttp
54
async with aiohttp.ClientSession(connector=connector) as session:
55
    async with session.get('http://httpbin.org/ip') as response:
56
        data = await response.json()
57
        print(data)
58
```
59

60
### URL-based Chain Creation
61

62
Create proxy chains directly from lists of proxy URL strings for convenient configuration.
63

64
```python { .api }
65
@classmethod
66
def from_urls(cls, urls: Iterable[str], **kwargs: Any) -> 'ChainProxyConnector':
67
    """
68
    Create ChainProxyConnector from list of proxy URLs.
69
    
70
    Args:
71
        urls (Iterable[str]): Sequence of proxy URLs
72
        **kwargs: Additional arguments passed to constructor
73
        
74
    Returns:
75
        ChainProxyConnector: Configured chain connector instance
76
        
77
    Each URL format: protocol://[username:password@]host:port
78
    """
79
```
80

81
#### Usage Examples
82

83
```python
84
from aiohttp_socks import ChainProxyConnector
85

86
# Simple proxy chain from URLs
87
proxy_urls = [
88
    'socks5://user:password@first-proxy.example.com:1080',
89
    'socks4://second-proxy.example.com:1081', 
90
    'http://user:password@third-proxy.example.com:3128'
91
]
92

93
connector = ChainProxyConnector.from_urls(proxy_urls)
94

95
# Mixed proxy types in chain
96
mixed_chain = [
97
    'socks5://127.0.0.1:1080',      # Local SOCKS5
98
    'socks4a://proxy.example.com:1081',  # Remote SOCKS4a  
99
    'http://proxy.example.com:3128'      # HTTP proxy
100
]
101

102
connector = ChainProxyConnector.from_urls(mixed_chain)
103
```
104

105
### ProxyInfo Configuration
106

107
Data structure for specifying proxy configuration in chains, providing all necessary connection parameters.
108

109
```python { .api }
110
class ProxyInfo(NamedTuple):
111
    proxy_type: ProxyType
112
    host: str
113
    port: int
114
    username: Optional[str] = None
115
    password: Optional[str] = None
116
    rdns: Optional[bool] = None
117
    """
118
    Proxy configuration information.
119
    
120
    Attributes:
121
        proxy_type (ProxyType): Type of proxy (SOCKS4/4a/5/5h/HTTP)
122
        host (str): Proxy server hostname or IP address
123
        port (int): Proxy server port number
124
        username (str, optional): Username for proxy authentication
125
        password (str, optional): Password for proxy authentication  
126
        rdns (bool, optional): Enable remote DNS resolution
127
    """
128
```
129

130
#### Usage Examples
131

132
```python
133
from aiohttp_socks import ProxyInfo, ProxyType
134

135
# Basic proxy info
136
proxy1 = ProxyInfo(
137
    proxy_type=ProxyType.SOCKS5,
138
    host='proxy.example.com',
139
    port=1080
140
)
141

142
# Authenticated proxy with remote DNS
143
proxy2 = ProxyInfo(
144
    proxy_type=ProxyType.SOCKS5,
145
    host='secure-proxy.example.com',
146
    port=1080,
147
    username='myuser',
148
    password='mypass',
149
    rdns=True
150
)
151

152
# HTTP proxy
153
proxy3 = ProxyInfo(
154
    proxy_type=ProxyType.HTTP,
155
    host='http-proxy.example.com',
156
    port=3128,
157
    username='httpuser',
158
    password='httppass'
159
)
160

161
# Create chain from ProxyInfo objects
162
chain = [proxy1, proxy2, proxy3]
163
connector = ChainProxyConnector(chain)
164
```
165

166
### Chain Routing Behavior
167

168
When using proxy chains, traffic flows through proxies in the order specified:
169

170
1. **First Proxy**: Client connects to the first proxy in the chain
171
2. **Intermediate Proxies**: Each proxy connects to the next proxy in sequence
172
3. **Final Destination**: Last proxy connects to the target server
173

174
This creates a tunnel through multiple proxy servers, with each proxy only knowing about its immediate predecessor and successor in the chain. This provides enhanced privacy and allows routing through different networks or geographic locations.