-Testing server with a browser
------------------------------
+Overview of lws test apps
+=========================
+
+Are you building a client? You just need to look at the test client
+[libwebsockets-test-client](test-server/test-client.c).
+
+If you are building a standalone server, there are three choices, in order of
+preferability.
+
+1) lwsws + protocol plugins
+
+Lws provides a generic web server app that can be configured with JSON
+config files. https://libwebsockets.org itself uses this method.
+
+With lwsws handling the serving part, you only need to write an lws protocol
+plugin. See [plugin-standalone](plugin-standalone) for an example of how
+to do that outside lws itself, using lws public apis.
+
+ $ cmake .. -DLWS_WITH_LWSWS=1
+
+See [README.lwsws.md](README.lwsws.md) for information on how to configure
+lwsws.
+
+NOTE this method implies libuv is used by lws, to provide crossplatform
+implementations of timers, dynamic lib loading etc for plugins and lwsws.
+
+2) test-server-v2.0.c
+
+This method lets you configure web serving in code, instead of using lwsws.
+
+Plugins are still used, which implies libuv needed.
+
+ $ cmake .. -DLWS_WITH_PLUGINS=1
+
+See [test-server-v2.0.c](test-server/test-server-v2.0.c)
+
+3) protocols in the server app
+
+This is the original way lws implemented servers, plugins and libuv are not
+required, but without plugins separating the protocol code directly, the
+combined code is all squidged together and is much less maintainable.
+
+This method is still supported in lws but all ongoing and future work is
+being done in protocol plugins only.
+
+
+Notes about lws test apps
+=========================
+
+@section tsb Testing server with a browser
If you run [libwebsockets-test-server](test-server/test-server.c) and point your browser
(eg, Chrome) to
- http://127.0.0.1:7681
+ 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.
what is logged using `-d <log level>`, see later.
-Running test server as a Daemon
--------------------------------
+@section tsd Running test server as a Daemon
You can use the -D option on the test server to have it fork into the
background and return immediately. In this daemonized mode all stderr is
terminates.
To stop the daemon, do
-
-```bash
-$ kill `cat /tmp/.lwsts-lock`
```
-
+ $ kill cat /tmp/.lwsts-lock
+```
If it finds a stale lock (the pid mentioned in the file does not exist
any more) it will delete the lock and create a new one during startup.
it was already running.
-Using SSL on the server side
-----------------------------
+@section sssl Using SSL on the server side
To test it using SSL/WSS, just run the test server with
-
-```bash
-$ libwebsockets-test-server --ssl
```
-
+ $ libwebsockets-test-server --ssl
+```
and use the URL
-
- https://127.0.0.1:7681
-
+```
+ 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
[test-server.c](test-server/test-server.c) is all that is needed to use libwebsockets for
serving both the script html over http and websockets.
+@section lwstsdynvhost Dynamic Vhosts
+
+You can send libwebsockets-test-server or libwebsockets-test-server-v2.0 a SIGUSR1
+to toggle the creation and destruction of an identical second vhost on port + 1.
+
+This is intended as a test and demonstration for how to bring up and remove
+vhosts dynamically.
-Testing websocket client support
---------------------------------
+@section wscl 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.
-```bash
-$ libwebsockets-test-client localhost
+```
+ $ libwebsockets-test-client localhost
```
will by default connect to the test server on localhost:7681
if you connect to the test server using a browser at the
same time you will be able to see the circles being drawn.
+The test client supports SSL too, use
+
+```
+ $ libwebsockets-test-client localhost --ssl -s
+```
+
+the -s tells it to accept the default self-signed cert from the server,
+otherwise it will strictly fail the connection if there is no CA cert to
+validate the server's certificate.
+
-Choosing between test server variations
----------------------------------------
+@section choosingts Choosing between test server variations
If you will be doing standalone serving with lws, ideally you should avoid
making your own server at all, and use lwsws with your own protocol plugins.
should be considered.
-Testing simple echo
--------------------
+@section echo Testing simple echo
You can test against `echo.websockets.org` as a sanity test like
this (the client connects to port `80` by default):
-```bash
-$ libwebsockets-test-echo --client echo.websocket.org
+```
+ $ libwebsockets-test-echo --client echo.websocket.org
```
This echo test is of limited use though because it doesn't
negotiate any protocol. You can run the same test app as a
local server, by default on localhost:7681
-
-```bash
-$ libwebsockets-test-echo
```
-
+ $ libwebsockets-test-echo
+```
and do the echo test against the local echo server
-
-```bash
-$ libwebsockets-test-echo --client localhost --port 7681
```
-
+ $ libwebsockets-test-echo --client localhost --port 7681
+```
If you add the `--ssl` switch to both the client and server, you can also test
with an encrypted link.
-Testing SSL on the client side
-------------------------------
+@section tassl Testing SSL on the client side
To test SSL/WSS client action, just run the client test with
-
-```bash
-$ libwebsockets-test-client localhost --ssl
```
-
-By default the client test applet is set to accept selfsigned
+ $ libwebsockets-test-client localhost --ssl
+```
+By default the client test applet is set to accept self-signed
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
---------------------------------
+@section taping 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
+websocket server and pings it like the
normal unix ping utility.
-
-```bash
-$ 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
-$
```
-
+ $ 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
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
+another server, you can specify the protocol to handshake with
by `--protocol=protocolname`
-Fraggle test app
-----------------
+@section ta fraggle Fraggle test app
By default it runs in server mode
-
-```bash
-$ libwebsockets-test-fraggle
-libwebsockets test fraggle
-(C) Copyright 2010-2011 Andy Green <andy@warmcat.com> 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
-...
```
-
+ $ libwebsockets-test-fraggle
+ libwebsockets test fraggle
+ (C) Copyright 2010-2011 Andy Green <andy@warmcat.com> 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:
-
-```bash
-$ libwebsockets-test-fraggle -c localhost
-libwebsockets test fraggle
-(C) Copyright 2010-2011 Andy Green <andy@warmcat.com> 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
-...
```
-
+ $ libwebsockets-test-fraggle -c localhost
+ libwebsockets test fraggle
+ (C) Copyright 2010-2011 Andy Green <andy@warmcat.com> 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.
then accepts the server checksum message and compares that to its checksum.
-proxy support
--------------
+@section taproxy proxy support
The http_proxy environment variable is respected by the client
connection code for both `ws://` and `wss://`. It doesn't support
authentication.
You use it like this
-
-```bash
-$ export http_proxy=myproxy.com:3128
-$ libwebsockets-test-client someserver.com
+```
+ $ export http_proxy=myproxy.com:3128
+ $ libwebsockets-test-client someserver.com
```
-
-debug logging
--------------
+@section talog debug logging
By default logging of severity "notice", "warn" or "err" is enabled to stderr.
Again by default other logging is compiled in but disabled from printing.
-If you want to eliminate the debug logging below notice in severity, use the
-`--disable-debug` configure option to have it removed from the code by the
-preprocesser.
+By default debug logs below "notice" in severity are not compiled in. To get
+them included, add this option in CMAKE
+
+```
+ $ cmake .. -DCMAKE_BUILD_TYPE=DEBUG
+```
If you want to see more detailed debug logs, you can control a bitfield to
select which logs types may print using the `lws_set_log_level()` api, in the
- 512 LATENCY
-Websocket version supported
----------------------------
+@section ws13 Websocket version supported
The final IETF standard is supported for both client and server, protocol
version 13.
-Latency Tracking
-----------------
+@section latency Latency Tracking
Since libwebsockets runs using `poll()` and a single threaded approach, any
unexpected latency coming from system calls would be bad news. There's now
treatment to the other app during that call.
-Autobahn Test Suite
--------------------
+@section autobahn Autobahn Test Suite
Lws can be tested against the autobahn websocket fuzzer.
to see the results
-Autobahn Test Notes
--------------------
+@section autobahnnotes Autobahn Test Notes
1) Autobahn tests the user code + lws implementation. So to get the same
-results, you need to follow test-echo.c in terms of user implmentation.
+results, you need to follow test-echo.c in terms of user implementation.
-2) Some of the tests make no sense for Libwebsockets to support and we fail them.
+2) Two of the tests make no sense for Libwebsockets to support and we fail them.
- Tests 2.10 + 2.11: sends multiple pings on one connection. Lws policy is to
only allow one active ping in flight on each connection, the rest are dropped.
projects / platform / upstream / libwebsockets.git / blobdiff