Debian Codegraph @

HACKING

raw
1 General idea.
2
3 FIXME: client, server. HTTP.
4
5 All HTTP requests are made by the client, htc, and are served by the
6 server, hts.
7
8 Data is sent to the server using HTTP PUT requests. These have a
9 Content-Length header line, which is obeyed strictly if the --strict
10 option is used. tunnel.c provides a nice interface to the
11 complexities of HTTP requests. See tunnel.h for information about the
12 programming interface.
13
14 In the other direction, data is transferred using HTTP GET requests.
15
16
17 Proxy buffering.
18
19 Some proxies buffer data in HTTP PUT or POST requests. FIXME: explain
20 why this is a problem and how it is solved.
21
22
23 Debugging.
24
25 To enable debugging code, use --enable-debug with 'configure'. This
26 will make htc and hts recognize a --debug switch.
27 --debug 0 - no messages whatsoever
28 --debug 1 - log_notice () - important events
29 --debug 2 - log_error () - unexpected errors
30 --debug 3 - log_debug () - sparse debugging
31 --debug 4 - log_verbose () - debugging in innner loops
32 --debug 5 - log_annoying () - system calls and more
33
34 Without --enable-debug, log_notice() and log_error() will log using
35 syslog() with level LOG_NOTICE and LOG_ERROR, respectively.
36 log_debug(), log_verbose(), and log_annoying() will be disabled.
37
38
39 Some notes about the protocol.
40
41 The data sent in HTTP requests is in itself formatted according to a
42 simple protocol. This is needed becase some HTTP proxy servers buffer
43 data before sending it to its final destination.
44
45 There are seven different requests in this protocol, and there are
46 two types of requests. Requests with the 0x40 bit set consists of
47 just one byte, with no additional data. Requests with the 0x40 bit
48 clear have a two-byte length field and a variable length data field.
49
50 TUNNEL_OPEN
51 01 xx xx yy...
52 xx xx = length of auth data
53 yy... = auth data
54
55 OPEN is the initial request. For now, auth data is unused,
56 but should be used for authentication.
57
58 TUNNEL_DATA
59 02 xx xx yy...
60 xx xx = lenth of data
61 yy... = data
62
63 DATA is the one and only way to send data.
64
65 TUNNEL_PADDING
66 03 xx xx yy...
67 xx xx = lenth of padding
68 yy... = padding (will be discarded)
69
70 PADDING exists only to allow padding the HTTP data. This is
71 needed for HTTP proxies that buffer data.
72
73 TUNNEL_ERROR
74 04 xx xx yy...
75 xx xx = length of error message
76 yy... = error message
77
78 Report an error to the peer.
79
80 TUNNEL_PAD1
81 45
82 PAD1 can be used for padding when a PADDING request would be
83 too long with regard to Content-Length. PADDING should always
84 be preferred, though, because it's easier for the recipent to
85 parse one large request than many small.
86
87 TUNNEL_CLOSE
88 46
89 CLOSE is used to close the tunnel. No more data can be sent
90 after this request is issued, except for a TUNNEL_DISCONNECT.
91
92 TUNNEL_DISCONNECT
93 47
94 DISCONNECT is used to close the connection temporarily,
95 probably because Content-Length - 1 number of bytes of data
96 has been sent in the HTTP request.