Debian Codegraph @

docs/source/usage.rst

raw
1 Usage
2 -----
3
4 .. currentmodule:: socksio
5
6 TL;DR check the `examples directory
7 <https://github.com/sethmlarson/socksio/tree/master/examples/>`_.
8
9 Being sans-I/O means that in order to test ``socksio`` you need an I/O
10 library. And the most basic I/O is, of course, the standard library’s
11 ``socket`` module.
12
13 You’ll need to know ahead of time the type of SOCKS proxy you want to
14 connect to. Assuming we have a SOCKS4 proxy running in our machine on
15 port 8080, we will first create a connection to it:
16
17 .. code:: python
18
19 import socket
20
21 sock = socket.create_connection(("localhost", 8080))
22
23 ``socksio`` exposes modules for SOCKS4, SOCKS4A and SOCKS5, each of them
24 includes a ``Connection`` class:
25
26 .. code:: python
27
28 from socksio import socks4
29
30 # The SOCKS4 protocol requires a `user_id` to be supplied.
31 conn = socks4.SOCKS4Connection(user_id=b"socksio")
32
33 Since ``socksio`` is a sans-I/O library, we will use the socket to send
34 and receive data to our SOCKS4 proxy. The raw data, however, will be
35 created and parsed by our :class:`SOCKS4Connection <socks4.SOCKS4Connection>`.
36
37 We need to tell our connection we want to make a request to the proxy.
38 We do that by first creating a request object.
39
40 In SOCKS4 we only need to send a command along with an IP address and
41 port. ``socksio`` exposes the different types of commands as enumerables
42 and a convenience :meth:`~socks4.SOCKS4Request.from_address`
43 class method in the request classes to create a valid request object:
44
45 .. code:: python
46
47 # SOCKS4 does not allow domain names, below is an IP for google.com
48 request = socks4.SOCKS4Request.from_address(
49 socks4.SOCKS4Command.CONNECT, ("216.58.204.78", 80))
50
51 ``from_address`` methods are available on all request classes in
52 ``socksio``, they accept addresses as tuples of ``(address, port)`` as
53 well as string ``address:port``.
54
55 Now we ask the connection to send our request:
56
57 .. code:: python
58
59 conn.send(request)
60
61 The :class:`SOCKS4Connection <socks4.SOCKS4Connection>` will then compose the
62 necessary ``bytes`` in the proper format for us to send to our proxy:
63
64 .. code:: python
65
66 data = conn.data_to_send()
67 sock.sendall(data)
68
69 If all goes well the proxy will have sent reply, we just need to read
70 from the socket and pass the data to the
71 :class:`SOCKS4Connection <socks4.SOCKS4Connection>`:
72
73 .. code:: python
74
75 data = sock.recv(1024)
76 event = conn.receive_data(data)
77
78 The connection will parse the data and return an event from it, in this
79 case, a :class:`SOCKS4Reply <socks4.SOCKS4Reply>` that includes attributes for
80 the fields in the SOCKS reply:
81
82 .. code:: python
83
84 if event.reply_code != socks4.SOCKS4ReplyCode.REQUEST_GRANTED:
85 raise Exception(
86 "Server could not connect to remote host: {}".format(event.reply_code)
87 )
88
89 If all went well the connection has been established correctly and we
90 can start sending our request directly to the proxy:
91
92 .. code:: python
93
94 sock.sendall(b"GET / HTTP/1.1\r\nhost: google.com\r\n\r\n")
95 data = receive_data(sock)
96 print(data)
97 # b'HTTP/1.1 301 Moved Permanently\r\nLocation: http://www.google.com/...`
98
99 The same methodology is used for all protocols, check out the
100 `examples directory <https://github.com/sethmlarson/socksio/tree/master/examples/>`_
101 for more information.