0
# Connection and Factory Functions
1

2
Core connection functionality providing multiple ways to establish RPyC connections including TCP, SSL, Unix sockets, SSH tunnels, subprocesses, and service discovery. These functions form the foundation for all RPyC distributed computing operations.
3

4
## Capabilities
5

6
### TCP Connections
7

8
Standard TCP socket connections for network-based RPyC communication.
9

10
```python { .api }
11
def connect(host, port, service=VoidService, config={}, ipv6=False, keepalive=False):
12
    """
13
    Connects to an RPyC server over TCP.
14
    
15
    Parameters:
16
    - host (str): Server hostname or IP address
17
    - port (int): Server port number  
18
    - service (Service): Local service to expose (default VoidService)
19
    - config (dict): Configuration dictionary
20
    - ipv6 (bool): Use IPv6 if True
21
    - keepalive (bool): Enable TCP keepalive
22
    
23
    Returns:
24
    Connection: RPyC connection object
25
    """
26
```
27

28
### SSL/TLS Connections
29

30
Secure connections using SSL/TLS encryption for protected communication.
31

32
```python { .api }
33
def ssl_connect(host, port, keyfile=None, certfile=None, ca_certs=None, 
34
               cert_reqs=None, ssl_version=None, ciphers=None,
35
               service=VoidService, config={}, ipv6=False, keepalive=False):
36
    """
37
    Connects to an RPyC server over SSL/TLS.
38
    
39
    Parameters:
40
    - host (str): Server hostname or IP address
41
    - port (int): Server port number
42
    - keyfile (str): Path to private key file
43
    - certfile (str): Path to certificate file
44
    - ca_certs (str): Path to CA certificates file
45
    - cert_reqs: Certificate requirements (ssl.CERT_NONE, ssl.CERT_OPTIONAL, ssl.CERT_REQUIRED)
46
    - ssl_version: SSL version to use
47
    - ciphers (str): Cipher suites to use
48
    - service (Service): Local service to expose
49
    - config (dict): Configuration dictionary
50
    - ipv6 (bool): Use IPv6 if True
51
    - keepalive (bool): Enable TCP keepalive
52
    
53
    Returns:
54
    Connection: Secure RPyC connection object
55
    """
56
```
57

58
### Unix Socket Connections
59

60
Local inter-process communication using Unix domain sockets.
61

62
```python { .api }
63
def unix_connect(path, service=VoidService, config={}):
64
    """
65
    Connects to an RPyC server over Unix domain socket.
66
    
67
    Parameters:
68
    - path (str): Path to Unix socket file
69
    - service (Service): Local service to expose
70
    - config (dict): Configuration dictionary
71
    
72
    Returns:
73
    Connection: RPyC connection object
74
    """
75
```
76

77
### SSH Tunnel Connections
78

79
Remote connections through SSH tunnels for secure remote access.
80

81
```python { .api }
82
def ssh_connect(remote_machine, remote_port, service=VoidService, config={}):
83
    """
84
    Connects to an RPyC server through SSH tunnel.
85
    
86
    Parameters:
87
    - remote_machine: SSH connection object or remote machine spec
88
    - remote_port (int): Remote port number on the SSH server
89
    - service (Service): Local service to expose
90
    - config (dict): Configuration dictionary
91
    
92
    Returns:
93
    Connection: RPyC connection through SSH tunnel
94
    """
95
```
96

97
### Subprocess Connections
98

99
Connections to RPyC servers running as subprocesses.
100

101
```python { .api }
102
def connect_subproc(args, service=VoidService, config={}):
103
    """
104
    Spawns RPyC server as subprocess and connects to it.
105
    
106
    Parameters:
107
    - args (list): Command line arguments for subprocess
108
    - service (Service): Local service to expose
109
    - config (dict): Configuration dictionary
110
    
111
    Returns:
112
    Connection: RPyC connection to subprocess
113
    """
114
```
115

116
### Thread and Process-based Connections
117

118
In-process and multi-process connections for local distributed computing.
119

120
```python { .api }
121
def connect_thread(service=VoidService, config={}, remote_service=VoidService, remote_config={}):
122
    """
123
    Creates in-thread RPyC connection for local distributed computing.
124
    
125
    Parameters:
126
    - service (Service): Local service to expose
127
    - config (dict): Local configuration dictionary
128
    - remote_service (Service): Remote service to run in thread
129
    - remote_config (dict): Remote configuration dictionary
130
    
131
    Returns:
132
    Connection: RPyC connection to thread
133
    """
134

135
def connect_multiprocess(service=VoidService, config={}, remote_service=VoidService, remote_config={}, args={}):
136
    """
137
    Creates RPyC connection to a new process with shared memory support.
138
    
139
    Parameters:
140
    - service (Service): Local service to expose
141
    - config (dict): Local configuration dictionary
142
    - remote_service (Service): Remote service to run in new process
143
    - remote_config (dict): Remote configuration dictionary
144
    - args (dict): Dictionary of local variables to share with new process
145
    
146
    Returns:
147
    Connection: RPyC connection to new process
148
    """
149
```
150

151
### Service Discovery
152

153
Automatic service discovery and connection through registry services.
154

155
```python { .api }
156
def discover(service_name, host=None, registrar=None, timeout=2):
157
    """
158
    Discovers RPyC services on the network.
159
    
160
    Parameters:
161
    - service_name (str): Name of service to discover
162
    - host (str): Host to search on (None for broadcast)
163
    - registrar: Registry client object
164
    - timeout (float): Discovery timeout in seconds
165
    
166
    Returns:
167
    list: List of (host, port) tuples for discovered services
168
    """
169

170
def list_services(registrar=None, filter_host=None, timeout=2):
171
    """
172
    Lists all available RPyC services.
173
    
174
    Parameters:
175
    - registrar: Registry client object  
176
    - filter_host (str): Filter services by host
177
    - timeout (float): Query timeout in seconds
178
    
179
    Returns:
180
    dict: Dictionary mapping service names to (host, port) tuples
181
    """
182

183
def connect_by_service(service_name, host=None, registrar=None, timeout=2, 
184
                      service=VoidService, config={}):
185
    """
186
    Discovers and connects to a named service.
187
    
188
    Parameters:
189
    - service_name (str): Name of service to connect to
190
    - host (str): Host to search on (None for broadcast)
191
    - registrar: Registry client object
192
    - timeout (float): Discovery timeout in seconds
193
    - service (Service): Local service to expose
194
    - config (dict): Configuration dictionary
195
    
196
    Returns:
197
    Connection: RPyC connection to discovered service
198
    """
199
```
200

201
### Low-level Connection Functions
202

203
Lower-level connection functions for custom transport mechanisms.
204

205
```python { .api }
206
def connect_stream(stream, service=VoidService, config={}):
207
    """
208
    Creates connection over an existing stream.
209
    
210
    Parameters:
211
    - stream: Stream object (SocketStream, PipeStream, etc.)
212
    - service (Service): Local service to expose
213
    - config (dict): Configuration dictionary
214
    
215
    Returns:
216
    Connection: RPyC connection over stream
217
    """
218

219
def connect_channel(channel, service=VoidService, config={}):
220
    """
221
    Creates connection over an existing channel.
222
    
223
    Parameters:
224
    - channel: Channel object
225
    - service (Service): Local service to expose  
226
    - config (dict): Configuration dictionary
227
    
228
    Returns:
229
    Connection: RPyC connection over channel
230
    """
231

232
def connect_pipes(input, output, service=VoidService, config={}):
233
    """
234
    Creates connection over input/output pipes.
235
    
236
    Parameters:
237
    - input: Input pipe/file object
238
    - output: Output pipe/file object
239
    - service (Service): Local service to expose
240
    - config (dict): Configuration dictionary
241
    
242
    Returns:
243
    Connection: RPyC connection over pipes
244
    """
245

246
def connect_stdpipes(service=VoidService, config={}):
247
    """
248
    Creates connection over stdin/stdout pipes.
249
    
250
    Parameters:
251
    - service (Service): Local service to expose
252
    - config (dict): Configuration dictionary
253
    
254
    Returns:
255
    Connection: RPyC connection over standard pipes
256
    """
257
```
258

259
## Examples
260

261
### Basic TCP Connection
262

263
```python
264
import rpyc
265

266
# Connect to RPyC server
267
conn = rpyc.connect('192.168.1.100', 12345)
268

269
# Use the connection
270
result = conn.root.remote_function()
271

272
# Clean up
273
conn.close()
274
```
275

276
### SSL Connection with Certificates
277

278
```python
279
import rpyc
280

281
# Secure connection with SSL
282
conn = rpyc.ssl_connect(
283
    'secure-server.com', 18821,
284
    certfile='/path/to/client.crt',
285
    keyfile='/path/to/client.key',
286
    ca_certs='/path/to/ca.crt'
287
)
288

289
# Use secure connection
290
data = conn.root.get_sensitive_data()
291
conn.close()
292
```
293

294
### Service Discovery
295

296
```python
297
import rpyc
298

299
# Discover available services
300
services = rpyc.list_services()
301
print("Available services:", services)
302

303
# Connect to a specific service by name
304
conn = rpyc.connect_by_service('CALCULATOR')
305
result = conn.root.add(5, 3)
306
conn.close()
307
```
308

309
### SSH Tunnel Connection
310

311
```python
312
import rpyc
313
from plumbum import SshMachine
314

315
# Create SSH connection
316
ssh = SshMachine('remote-server.com', user='myuser')
317

318
# Connect through SSH tunnel
319
conn = rpyc.ssh_connect(ssh, 12345)
320
result = conn.root.remote_computation()
321
conn.close()
322
```
323

324
### Multiprocess Connection
325

326
```python
327
import rpyc
328

329
# Connect to a new process with shared memory
330
conn = rpyc.connect_multiprocess(
331
    remote_service=MyService,
332
    args={'shared_data': some_shared_object}
333
)
334

335
# Access the remote service in the new process
336
result = conn.root.process_data()
337
conn.close()
338
```
339

340
## Exceptions
341

342
```python { .api }
343
class DiscoveryError(Exception):
344
    """Raised when service discovery fails"""
345

346
class ForbiddenError(Exception):
347
    """Raised when connection is forbidden by server"""
348
```