-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathREADME-test-server
280 lines (203 loc) · 9.18 KB
/
README-test-server
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
Using test-server as a quickstart
---------------------------------
For a Fedora x86_86 box, the following config line was
needed:
./configure --prefix=/usr --libdir=/usr/lib64 --enable-openssl
For Apple systems, Christopher Baker reported that this is needed
(and I was told separately enabling openssl makes trouble somehow)
./configure CC="gcc -arch i386 -arch x86_64" CXX="g++ -arch i386 -arch
x86_64" CPP="gcc -E" CXXCPP="g++ -E" --enable-nofork
otherwise if /usr/local/... and /usr/local/lib are OK then...
$ ./configure
$ make clean
$ make
$ sudo make install
$ libwebsockets-test-server
should be enough to get a test server listening on port 7861.
There are a couple of other possible configure options
--enable-nofork disables the fork into the background API
and removes all references to fork() and
pr_ctl() from the sources. Use it if your
platform doesn't support forking.
--enable-libcrypto by default libwebsockets uses its own
built-in md5 and sha-1 implementation for
simplicity. However the libcrypto ones
may be faster, and in a distro context it
may be highly desirable to use a common
library implementation for ease of security
upgrades. Give this configure option
to disable the built-in ones and force use
of the libcrypto (part of openssl) ones.
--with-client-cert-dir=dir tells the client ssl support where to
look for trust certificates to validate
the remote certificate against.
--enable-noping Don't try to build the ping test app
It needs some unixy environment that
may choke in other build contexts, this
lets you cleanly stop it being built
--enable-x-google-mux Enable experimental x-google-mux support
in the build (see notes later in document)
Testing server with a browser
-----------------------------
If you point your browser (eg, Chrome) to
http://127.0.0.1:7681
It will fetch a script in the form of test.html, and then run the
script in there on the browser to open a websocket connection.
Incrementing numbers should appear in the browser display.
Using SSL on the server side
----------------------------
To test it using SSL/WSS, just run the test server with
$ libwebsockets-test-server --ssl
and use the URL
https://127.0.0.1:7681
The connection will be entirely encrypted using some generated
certificates that your browser will not accept, since they are
not signed by any real Certificate Authority. Just accept the
certificates in the browser and the connection will proceed
in first https and then websocket wss, acting exactly the
same.
test-server.c is all that is needed to use libwebsockets for
serving both the script html over http and websockets.
Forkless operation
------------------
If your target device does not offer fork(), you can use
libwebsockets from your own main loop instead. Use the
configure option --nofork and simply call libwebsocket_service()
from your own main loop as shown in the test app sources.
Testing websocket client support
--------------------------------
If you run the test server as described above, you can also
connect to it using the test client as well as a browser.
$ libwebsockets-test-client localhost
will by default connect to the test server on localhost:7681
and print the dumb increment number from the server at the
same time as drawing random circles in the mirror protocol;
if you connect to the test server using a browser at the
same time you will be able to see the circles being drawn.
Testing SSL on the client side
------------------------------
To test SSL/WSS client action, just run the client test with
$ libwebsockets-test-client localhost --ssl
By default the client test applet is set to accept selfsigned
certificates used by the test server, this is indicated by the
use_ssl var being set to 2. Set it to 1 to reject any server
certificate that it doesn't have a trusted CA cert for.
Using the websocket ping utility
--------------------------------
libwebsockets-test-ping connects as a client to a remote
websocket server using 04 protocol and pings it like the
normal unix ping utility.
$ libwebsockets-test-ping localhost
handshake OK for protocol lws-mirror-protocol
Websocket PING localhost.localdomain (127.0.0.1) 64 bytes of data.
64 bytes from localhost: req=1 time=0.1ms
64 bytes from localhost: req=2 time=0.1ms
64 bytes from localhost: req=3 time=0.1ms
64 bytes from localhost: req=4 time=0.2ms
64 bytes from localhost: req=5 time=0.1ms
64 bytes from localhost: req=6 time=0.2ms
64 bytes from localhost: req=7 time=0.2ms
64 bytes from localhost: req=8 time=0.1ms
^C
--- localhost.localdomain websocket ping statistics ---
8 packets transmitted, 8 received, 0% packet loss, time 7458ms
rtt min/avg/max = 0.110/0.185/0.218 ms
$
By default it sends 64 byte payload packets using the 04
PING packet opcode type. You can change the payload size
using the -s= flag, up to a maximum of 125 mandated by the
04 standard.
Using the lws-mirror protocol that is provided by the test
server, libwebsockets-test-ping can also use larger payload
sizes up to 4096 is BINARY packets; lws-mirror will copy
them back to the client and they appear as a PONG. Use the
-m flag to select this operation.
The default interval between pings is 1s, you can use the -i=
flag to set this, including fractions like -i=0.01 for 10ms
interval.
Before you can even use the PING opcode that is part of the
standard, you must complete a handshake with a specified
protocol. By default lws-mirror-protocol is used which is
supported by the test server. But if you are using it on
another server, you can specify the protcol to handshake with
by --protocol=protocolname
Fraggle test app
----------------
By default it runs in server mode
$ libwebsockets-test-fraggle
libwebsockets test fraggle
(C) Copyright 2010-2011 Andy Green <[email protected]> licensed under LGPL2.1
Compiled with SSL support, not using it
Listening on port 7681
server sees client connect
accepted v06 connection
Spamming 360 random fragments
Spamming session over, len = 371913. sum = 0x2D3C0AE
Spamming 895 random fragments
Spamming session over, len = 875970. sum = 0x6A74DA1
...
You need to run a second session in client mode, you have to
give the -c switch and the server address at least:
$ libwebsockets-test-fraggle -c localhost
libwebsockets test fraggle
(C) Copyright 2010-2011 Andy Green <[email protected]> licensed under LGPL2.1
Client mode
Connecting to localhost:7681
denied deflate-stream extension
handshake OK for protocol fraggle-protocol
client connects to server
EOM received 371913 correctly from 360 fragments
EOM received 875970 correctly from 895 fragments
EOM received 247140 correctly from 258 fragments
EOM received 695451 correctly from 692 fragments
...
The fraggle test sends a random number up to 1024 fragmented websocket frames
each of a random size between 1 and 2001 bytes in a single message, then sends
a checksum and starts sending a new randomly sized and fragmented message.
The fraggle test client receives the same message fragments and computes the
same checksum using websocket framing to see when the message has ended. It
then accepts the server checksum message and compares that to its checksum.
proxy support
-------------
The http_proxy environment variable is respected by the client
connection code for both ws:// and wss://. It doesn't support
authentication yet.
You use it like this
export http_proxy=myproxy.com:3128
libwebsockets-test-client someserver.com
Websocket version supported
---------------------------
The websocket client code is 04 and 05 version, the server
supports 00/76 in text mode and 04 and 05 dynamically
per-connection depending on the version of the
client / browser.
External Polling Loop support
-----------------------------
libwebsockets maintains an internal poll() array for all of its
sockets, but you can instead integrate the sockets into an
external polling array. That's needed if libwebsockets will
cooperate with an existing poll array maintained by another
server.
Four callbacks LWS_CALLBACK_ADD_POLL_FD, LWS_CALLBACK_DEL_POLL_FD,
LWS_CALLBACK_SET_MODE_POLL_FD and LWS_CALLBACK_CLEAR_MODE_POLL_FD
appear in the callback for protocol 0 and allow interface code to
manage socket descriptors in other poll loops.
x-google-mux support
--------------------
Experimental and super-preliminary x-google-mux support is available if
enabled in ./configure with --enable-x-google-mux. Note that when changing
configurations, you will need to do a make distclean before, then the new
configure and then make ; make install. Don't forget the necessary other
flags for your platform as described at the top of the readme.
It has the following notes:
1) To enable it, reconfigure with --enable-x-google-mux
2) It deviates from the google standard by sending full
headers in the addchannel subcommand rather than just
changed ones from original connect
3) Quota is not implemented yet
However despite those caveats, in fact it can run the
test client reliably over one socket (both dumb-increment
and lws-mirror-protocol), you can open a browser on the
same test server too and see the circles, etc.
It also works compatibly with deflate-stream automatically.
2011-05-28 Andy Green <[email protected]>