Mirrors/libwebsockets
1
0
Fork 0
mirror of https://github.com/warmcat/libwebsockets.git synced 2025-03-09 00:00:04 +01:00
Code Issues Releases Wiki Activity

Subject: [PATCH] Nicer readmes using markdown.

Browse source 
This is still readable in raw text, but much nicer for github with heading and syntax highlighting and such.
This commit is contained in:
=?UTF-8?q?Joakim=20S=C3=B6derberg?= 2014-12-01 01:21:10 +01:00 • committed by Andy Green
parent 453a9b34fd
commit 4198276505
4 changed files with 216 additions and 156 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

132
README.build → README.build.md
View file

@ -4,9 +4,9 @@ Introduction to CMake
CMake is a multi-platform build tool that can generate build files for many
different target platforms. See more info at http://www.cmake.org
CMake also allows/recommends you to do "out of source"-builds, that is,
the build files are separated from your sources, so there is no need to
create elaborate clean scripts to get a clean source tree, instead you
CMake also allows/recommends you to do "out of source"-builds, that is,
the build files are separated from your sources, so there is no need to
create elaborate clean scripts to get a clean source tree, instead you
simply remove your build directory.
Libwebsockets has been tested to build successfully on the following platforms
@ -21,7 +21,7 @@ Building the library and test apps
----------------------------------
The project settings used by CMake to generate the platform specific build
files is called CMakeLists.txt. CMake then uses one of its "Generators" to
files is called [CMakeLists.txt](CMakeLists.txt). CMake then uses one of its "Generators" to
output a Visual Studio project or Make file for instance. To see a list of
the available generators for your platform, simply run the "cmake" command.
@ -38,48 +38,60 @@ Building on Unix:
3. Generate the build files (default is Make files):
cd /path/to/src
mkdir build
cd build
cmake ..
```bash
$ cd /path/to/src
$ mkdir build
$ cd build
$ cmake ..
```
(NOTE: The build/ directory can have any name and be located anywhere
on your filesystem, and that the argument ".." given to cmake is simply
the source directory of libwebsockets containing the CMakeLists.txt
(**NOTE**: The `build/`` directory can have any name and be located anywhere
on your filesystem, and that the argument `..` given to cmake is simply
the source directory of **libwebsockets** containing the [CMakeLists.txt](CMakeLists.txt)
project file. All examples in this file assumes you use "..")
NOTE2
**NOTE2**:
A common option you may want to give is to set the install path, same
as --prefix= with autotools. It defaults to /usr/local.
You can do this by, eg
cmake -DCMAKE_INSTALL_PREFIX:PATH=/usr ..
```bash
$ cmake -DCMAKE_INSTALL_PREFIX:PATH=/usr ..
```
NOTE3
**NOTE3**:
On machines that want libraries in lib64, you can also add the
following to the cmake line
-DLIB_SUFFIX=64
NOTE4
```bash
-DLIB_SUFFIX=64
```
**NOTE4**:
If you are building against a non-distro OpenSSL (eg, in order to get
access to ALPN support only in newer OpenSSL versions) the nice way to
express that in one cmake command is eg,
cmake .. -DOPENSSL_ROOT_DIR=/usr/local/ssl \
```bash
$ cmake .. -DOPENSSL_ROOT_DIR=/usr/local/ssl \
-DCMAKE_INCLUDE_DIRECTORIES_PROJECT_BEFORE=/usr/local/ssl \
-DLWS_WITH_HTTP2=1
```
When you run the test apps using non-distro SSL, you have to force them
to use your libs, not the distro ones
LD_LIBRARY_PATH=/usr/local/ssl/lib libwebsockets-test-server --ssl
```bash
$ LD_LIBRARY_PATH=/usr/local/ssl/lib libwebsockets-test-server --ssl
```
4. Finally you can build using the generated Makefile:
make
```bash
$ make
```
Quirk of cmake
--------------
@ -97,15 +109,17 @@ Building on Windows (Visual Studio)
3. Generate the Visual studio project by opening the Visual Studio cmd prompt:
```bash
cd <path to src>
md build
cd build
cmake -G "Visual Studio 10" ..
```
(NOTE: There is also a cmake-gui available on Windows if you prefer that)
(**NOTE**: There is also a cmake-gui available on Windows if you prefer that)
4. Now you should have a generated Visual Studio Solution in your
<path to src>/build directory, which can be used to build.
`<path to src>/build` directory, which can be used to build.
Setting compile options
-----------------------
@ -129,7 +143,7 @@ Unix GUI
--------
If you have a curses enabled build you simply type:
(not all packages include this, my debian install does not for example).
ccmake
Windows GUI
@ -145,17 +159,19 @@ http://www.yassl.com/yaSSL/Products-cyassl.html
It contains a OpenSSL compatability layer which makes it possible to pretty
much link to it instead of OpenSSL, giving a much smaller footprint.
NOTE: cyassl needs to be compiled using the --enable-opensslextra flag for
**NOTE**: cyassl needs to be compiled using the `--enable-opensslextra` flag for
this to work.
Compiling libwebsockets with CyaSSL
-----------------------------------
```bash
cmake .. -DLWS_USE_CYASSL=1 \
-DLWS_CYASSL_INCLUDE_DIRS=/path/to/cyassl \
-DLWS_CYASSL_LIB=/path/to/cyassl/cyassl.a ..
```
NOTE: On windows use the .lib file extension for LWS_CYASSL_LIB instead.
**NOTE**: On windows use the .lib file extension for `LWS_CYASSL_LIB` instead.
Reproducing HTTP2.0 tests
@ -165,41 +181,48 @@ You must have built and be running lws against a version of openssl that has
ALPN / NPN. Most distros still have older versions. You'll know it's right by
seeing
```bash
lwsts[4752]: Compiled with OpenSSL support
lwsts[4752]: Using SSL mode
lwsts[4752]: HTTP2 / ALPN enabled
```
at lws startup.
For non-SSL HTTP2.0 upgrade
nghttp -nvasu http://localhost:7681/test.htm
```bash
$ nghttp -nvasu http://localhost:7681/test.htm
```
For SSL / ALPN HTTP2.0 upgrade
nghttp -nvas https://localhost:7681/test.html
```
$ nghttp -nvas https://localhost:7681/test.html
```
Cross compiling
---------------
To enable cross compiling libwebsockets using CMake you need to create
To enable cross compiling **libwebsockets** using CMake you need to create
a "Toolchain file" that you supply to CMake when generating your build files.
CMake will then use the cross compilers and build paths specified in this file
to look for dependencies and such.
Libwebsockets includes an example toolchain file cross-arm-linux-gnueabihf.cmake
**Libwebsockets** includes an example toolchain file [cross-arm-linux-gnueabihf.cmake](cross-arm-linux-gnueabihf.cmake)
you can use as a starting point.
The commandline to configure for cross with this would look like
cmake .. -DCMAKE_INSTALL_PREFIX:PATH=/usr \
```bash
$ cmake .. -DCMAKE_INSTALL_PREFIX:PATH=/usr \
-DCMAKE_TOOLCHAIN_FILE=../cross-arm-linux-gnueabihf.cmake \
-DWITHOUT_EXTENSIONS=1 -DWITH_SSL=0
```
The example shows how to build with no external cross lib dependencies, you
need to proide the cross libraries otherwise.
need to provide the cross libraries otherwise.
NOTE: start from an EMPTY build directory if you had a non-cross build in there
**NOTE**: start from an EMPTY build directory if you had a non-cross build in there
before the settings will be cached and your changes ignored.
Additional information on cross compilation with CMake:
@ -215,13 +238,15 @@ server, built on ARM Cortex-A9:
Update at 8dac94d (2013-02-18)
./configure --without-client --without-extensions --disable-debug --without-daemonize
```bash
$ ./configure --without-client --without-extensions --disable-debug --without-daemonize
Context Creation, 1024 fd limit[2]: 16720 (includes 12 bytes per fd)
Per-connection [3]: 72 bytes, +1328 during headers
.text .rodata .data .bss
11512 2784 288 4
```
This shows the impact of the major configuration with/without options at
13ba5bbc633ea962d46d using Ubuntu ARM on a PandaBoard ES.
@ -231,25 +256,24 @@ additional dynamic allocations via malloc. These are a bit old now but give
the right idea for relative "expense" of features.
Static allocations, ARM9
.text .rodata .data .bss
All (no without) 35024 9940 336 4104
without client 25684 7144 336 4104
without client, exts 21652 6288 288 4104
without client, exts, debug[1] 19756 3768 288 4104
without server 30304 8160 336 4104
without server, exts 25382 7204 288 4104
without server, exts, debug[1] 23712 4256 288 4104
[1] --disable-debug only removes messages below lwsl_notice. Since that is
the default logging level the impact is not noticable, error, warn and notice
| | .text | .rodata | .data | .bss |
|--------------------------------|---------|---------|-------|------|
| All (no without) | 35024 | 9940 | 336 | 4104 |
| without client | 25684 | 7144 | 336 | 4104 |
| without client, exts | 21652 | 6288 | 288 | 4104 |
| without client, exts, debug[1] | 19756 | 3768 | 288 | 4104 |
| without server | 30304 | 8160 | 336 | 4104 |
| without server, exts | 25382 | 7204 | 288 | 4104 |
| without server, exts, debug[1] | 23712 | 4256 | 288 | 4104 |
[1] `--disable-debug` only removes messages below `lwsl_notice`. Since that is
the default logging level the impact is not noticeable, error, warn and notice
logs are all still there.
[2] 1024 fd per process is the default limit (set by ulimit) in at least Fedora
[2] `1024` fd per process is the default limit (set by ulimit) in at least Fedora
and Ubuntu. You can make significant savings tailoring this to actual expected
peak fds, ie, at a limit of 20, context creation allocation reduces to 4432 +
240 = 4672)
peak fds, ie, at a limit of `20`, context creation allocation reduces to `4432 +
240 = 4672`)
[3] known header content is freed after connection establishment

117
README.coding → README.coding.md
View file

@ -1,7 +1,7 @@
Daemonization
-------------
There's a helper api lws_daemonize built by default that does everything you
There's a helper api `lws_daemonize` built by default that does everything you
need to daemonize well, including creating a lock file. If you're making
what's basically a daemon, just call this early in your init to fork to a
headless background process and exit the starting process.
@ -22,19 +22,19 @@ in use by the user code.
If you want to restrict that allocation, or increase it, you can use ulimit or
similar to change the avaiable number of file descriptors, and when restarted
libwebsockets will adapt accordingly.
**libwebsockets** will adapt accordingly.
Libwebsockets is singlethreaded
-------------------------------
Directly performing websocket actions from other threads is not allowed.
Aside from the internal data being inconsistent in forked() processes,
the scope of a wsi (struct websocket) can end at any time during service
with the socket closing and the wsi freed.
Aside from the internal data being inconsistent in `forked()` processes,
the scope of a `wsi` (`struct websocket`) can end at any time during service
with the socket closing and the `wsi` freed.
Websocket write activities should only take place in the
"LWS_CALLBACK_SERVER_WRITEABLE" callback as described below.
`LWS_CALLBACK_SERVER_WRITEABLE` callback as described below.
Only live connections appear in the user callbacks, so this removes any
possibility of trying to used closed and freed wsis.
@ -49,14 +49,14 @@ Only send data when socket writeable
------------------------------------
You should only send data on a websocket connection from the user callback
"LWS_CALLBACK_SERVER_WRITEABLE" (or "LWS_CALLBACK_CLIENT_WRITEABLE" for
`LWS_CALLBACK_SERVER_WRITEABLE` (or `LWS_CALLBACK_CLIENT_WRITEABLE` for
clients).
If you want to send something, do not just send it but request a callback
when the socket is writeable using
- libwebsocket_callback_on_writable(context, wsi) for a specific wsi, or
- libwebsocket_callback_on_writable_all_protocol(protocol) for all connections
- `libwebsocket_callback_on_writable(context, wsi)`` for a specific `wsi`, or
- `libwebsocket_callback_on_writable_all_protocol(protocol)` for all connections
using that protocol to get a callback when next writeable.
Usually you will get called back immediately next time around the service
@ -70,30 +70,30 @@ See the test server code for an example of how to do this.
Do not rely on only your own WRITEABLE requests appearing
---------------------------------------------------------
Libwebsockets may generate additional LWS_CALLBACK_CLIENT_WRITEABLE events
Libwebsockets may generate additional `LWS_CALLBACK_CLIENT_WRITEABLE` events
if it met network conditions where it had to buffer your send data internally.
So your code for LWS_CALLBACK_CLIENT_WRITEABLE needs to own the decision
So your code for `LWS_CALLBACK_CLIENT_WRITEABLE` needs to own the decision
about what to send, it can't assume that just because the writeable callback
came it really is time to send something.
It's quite possible you get an 'extra' writeable callback at any time and
just need to return 0 and wait for the expected callback later.
just need to `return 0` and wait for the expected callback later.
Closing connections from the user side
--------------------------------------
When you want to close a connection, you do it by returning -1 from a
When you want to close a connection, you do it by returning `-1` from a
callback for that connection.
You can provoke a callback by calling libwebsocket_callback_on_writable on
You can provoke a callback by calling `libwebsocket_callback_on_writable` on
the wsi, then notice in the callback you want to close it and just return -1.
But usually, the decision to close is made in a callback already and returning
-1 is simple.
If the socket knows the connection is dead, because the peer closed or there
was an affirmitive network error like a FIN coming, then libwebsockets will
was an affirmitive network error like a FIN coming, then **libwebsockets** will
take care of closing the connection automatically.
If you have a silently dead connection, it's possible to enter a state where
@ -106,10 +106,11 @@ Fragmented messages
-------------------
To support fragmented messages you need to check for the final
frame of a message with libwebsocket_is_final_fragment. This
check can be combined with libwebsockets_remaining_packet_payload
frame of a message with `libwebsocket_is_final_fragment`. This
check can be combined with `libwebsockets_remaining_packet_payload`
to gather the whole contents of a message, eg:
```
case LWS_CALLBACK_RECEIVE:
{
Client * const client = (Client *)user;
@ -128,29 +129,30 @@ to gather the whole contents of a message, eg:
client->AppendMessageFragment(in, len, remaining);
}
break;
```
The test app llibwebsockets-test-fraggle sources also show how to
The test app libwebsockets-test-fraggle sources also show how to
deal with fragmented messages.
Debug Logging
-------------
Also using lws_set_log_level api you may provide a custom callback to actually
Also using `lws_set_log_level` api you may provide a custom callback to actually
emit the log string. By default, this points to an internal emit function
that sends to stderr. Setting it to NULL leaves it as it is instead.
that sends to stderr. Setting it to `NULL` leaves it as it is instead.
A helper function lwsl_emit_syslog() is exported from the library to simplify
logging to syslog. You still need to use setlogmask, openlog and closelog
A helper function `lwsl_emit_syslog()` is exported from the library to simplify
logging to syslog. You still need to use `setlogmask`, `openlog` and `closelog`
in your user code.
The logging apis are made available for user code.
lwsl_err(...)
lwsl_warn(...)
lwsl_notice(...)
lwsl_info(...)
lwsl_debug(...)
- `lwsl_err(...)`
- `lwsl_warn(...)`
- `lwsl_notice(...)`
- `lwsl_info(...)`
- `lwsl_debug(...)`
The difference between notice and info is that notice will be logged by default
whereas info is ignored by default.
@ -159,22 +161,22 @@ whereas info is ignored by default.
External Polling Loop support
-----------------------------
libwebsockets maintains an internal poll() array for all of its
**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
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
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.
You can pass all pollfds that need service to libwebsocket_service_fd(), even
if the socket or file does not belong to libwebsockets it is safe.
You can pass all pollfds that need service to `libwebsocket_service_fd()`, even
if the socket or file does not belong to **libwebsockets** it is safe.
If libwebsocket handled it, it zeros the pollfd revents field before returning.
So you can let libwebsockets try and if pollfd->revents is nonzero on return,
If **libwebsocket** handled it, it zeros the pollfd `revents` field before returning.
So you can let **libwebsockets** try and if `pollfd->revents` is nonzero on return,
you know it needs handling by your code.
@ -184,13 +186,17 @@ Using with in c++ apps
The library is ready for use by C++ apps. You can get started quickly by
copying the test server
```bash
$ cp test-server/test-server.c test.cpp
```
and building it in C++ like this
```bash
$ g++ -DINSTALL_DATADIR=\"/usr/share\" -ocpptest test.cpp -lwebsockets
```
INSTALL_DATADIR is only needed because the test server uses it as shipped, if
`INSTALL_DATADIR` is only needed because the test server uses it as shipped, if
you remove the references to it in your app you don't need to define it on
the g++ line either.
@ -198,11 +204,11 @@ the g++ line either.
Availability of header information
----------------------------------
From v1.2 of the library onwards, the HTTP header content is free()d as soon
From v1.2 of the library onwards, the HTTP header content is `free()`d as soon
as the websocket connection is established. For websocket servers, you can
copy interesting headers by handling LWS_CALLBACK_FILTER_PROTOCOL_CONNECTION
copy interesting headers by handling `LWS_CALLBACK_FILTER_PROTOCOL_CONNECTION`
callback, for clients there's a new callback just for this purpose
LWS_CALLBACK_CLIENT_FILTER_PRE_ESTABLISH.
`LWS_CALLBACK_CLIENT_FILTER_PRE_ESTABLISH`.
TCP Keepalive
@ -214,7 +220,7 @@ by default TCP will just not report anything and you will never get any more
incoming data or sign the link is dead until you try to send.
To deal with getting a notification of that situation, you can choose to
enable TCP keepalives on all libwebsockets sockets, when you create the
enable TCP keepalives on all **libwebsockets** sockets, when you create the
context.
To enable keepalive, set the ka_time member of the context creation parameter
@ -223,45 +229,44 @@ also fill ka_probes and ka_interval in that case.
With keepalive enabled, the TCP layer will send control packets that should
stimulate a response from the peer without affecting link traffic. If the
response is not coming, the socket will announce an error at poll() forcing
response is not coming, the socket will announce an error at `poll()` forcing
a close.
Note that BSDs don't support keepalive time / probes / inteveral per-socket
Note that BSDs don't support keepalive time / probes / interval per-socket
like Linux does. On those systems you can enable keepalive by a nonzero
value in ka_time, but the systemwide kernel settings for the time / probes/
interval are used, regardless of what nonzero value is in ka_time.
value in `ka_time`, but the systemwide kernel settings for the time / probes/
interval are used, regardless of what nonzero value is in `ka_time`.
Optimizing SSL connections
--------------------------
There's a member ssl_cipher_list in the lws_context_creation_info struct
There's a member `ssl_cipher_list` in the `lws_context_creation_info` struct
which allows the user code to restrict the possible cipher selection at
context-creation time.
You might want to look into that to stop the ssl peers selecting a ciher which
You might want to look into that to stop the ssl peers selecting a cipher which
is too computationally expensive. To use it, point it to a string like
"RC4-MD5:RC4-SHA:AES128-SHA:AES256-SHA:HIGH:!DSS:!aNULL"
`"RC4-MD5:RC4-SHA:AES128-SHA:AES256-SHA:HIGH:!DSS:!aNULL"`
if left NULL, then the "DEFAULT" set of ciphers are all possible to select.
if left `NULL`, then the "DEFAULT" set of ciphers are all possible to select.
Async nature of client connections
----------------------------------
When you call libwebsocket_client_connect(..) and get a wsi back, it does not
When you call `libwebsocket_client_connect(..)` and get a `wsi` back, it does not
mean your connection is active. It just mean it started trying to connect.
Your client connection is actually active only when you receive
LWS_CALLBACK_CLIENT_ESTABLISHED for it.
`LWS_CALLBACK_CLIENT_ESTABLISHED` for it.
There's a 5 second timeout for the connection, and it may give up or die for
other reasons, if any of that happens you'll get a
LWS_CALLBACK_CLIENT_CONNECTION_ERROR callback on protocol 0 instead for the
wsi.
`LWS_CALLBACK_CLIENT_CONNECTION_ERROR` callback on protocol 0 instead for the
`wsi`.
After attempting the connection and getting back a non-NULL wsi you should
loop calling libwebsocket_service() until one of the above callbacks occurs.
As usual, see test-client.c for example code.
After attempting the connection and getting back a non-`NULL` `wsi` you should
loop calling `libwebsocket_service()` until one of the above callbacks occurs.
As usual, see [test-client.c](test-server/test-client.c) for example code.

22
README → README.md
View file

@ -1,3 +1,11 @@
[![Travis Build Status](https://travis-ci.org/warmcat/libwebsockets.png)](https://travis-ci.org/warmcat/libwebsockets)
[![Appveyor Build status](https://ci.appveyor.com/api/projects/status/6aq2tpajh1nmy6b3)](https://ci.appveyor.com/project/warmcat/libwebsockets)
[![Coverity Scan Build Status](https://scan.coverity.com/projects/2506/badge.svg)](https://scan.coverity.com/projects/2506)
libwebsockets
-------------
This is the libwebsockets C library for lightweight websocket clients and
servers. For support, visit
@ -9,17 +17,18 @@ and consider joining the project mailing list at
You can get the latest version of the library from git
http://git.libwebsockets.org
https://github.com/warmcat/libwebsockets
- http://git.libwebsockets.org
- https://github.com/warmcat/libwebsockets
for more information:
README.build - information on building the library
README.coding - information for writing code using the library
README.test-apps - information about the test apps built with the library
- [README.build.md](README.build.md) - information on building the library
- [README.coding.md](README.coding.md) - information for writing code using the library
- [README.test-apps.md](README.test-apps.md) - information about the test apps built with the library
After 1.3, tags will be signed using a key corresponding to this public key
After libwebsockets 1.3, tags will be signed using a key corresponding to this public key
```
-----BEGIN PGP PUBLIC KEY BLOCK-----
Version: GnuPG v1
@ -72,3 +81,4 @@ cX6tdPyGz3o0aywfJ9dcN6izleSV1gYmXmIoS0cQyezVqTUkT8C12zeRB7mtWsDa
+AWJGq/WfB7N6pPh8S/XMW4e6ptuUodjiA==
=HV8t
-----END PGP PUBLIC KEY BLOCK-----
```

101
README.test-apps → README.test-apps.md
View file

@ -1,17 +1,17 @@
Testing server with a browser
-----------------------------
If you run libwebsockets-test-server and point your 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
It will fetch a script in the form of test.html, and then run the
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.
By default the test server logs to both stderr and syslog, you can control
what is logged using -d <log level>, see later.
what is logged using `-d <log level>`, see later.
Running test server as a Daemon
@ -19,21 +19,23 @@ 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
disabled and logging goes only to syslog, eg, /var/log/messages or similar.
disabled and logging goes only to syslog, eg, `/var/log/messages` or similar.
The server maintains a lockfile at /tmp/.lwsts-lock that contains the pid
The server maintains a lockfile at `/tmp/.lwsts-lock` that contains the pid
of the master process, and deletes this file when the master process
terminates.
To stop the daemon, do
kill `cat /tmp/.lwsts-lock`
```bash
$ 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.
If the lock is valid, the daemon will exit with a note on stderr that
it was already running.s
it was already running.
Using SSL on the server side
@ -41,7 +43,9 @@ Using SSL on the server side
To test it using SSL/WSS, just run the test server with
```bash
$ libwebsockets-test-server --ssl
```
and use the URL
@ -54,7 +58,7 @@ 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
[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.
@ -64,7 +68,9 @@ 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
```
will by default connect to the test server on localhost:7681
and print the dumb increment number from the server at the
@ -76,22 +82,28 @@ same time you will be able to see the circles being drawn.
Testing simple echo
-------------------
You can test against echo.websockets.org as a sanity test like
this (the client connects to port 80 by default):
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
```
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
```
and do the echo test against the local echo server
```bash
$ libwebsockets-test-echo --client localhost --port 7681
```
If you add the --ssl switch to both the client and server, you can also test
If you add the `--ssl` switch to both the client and server, you can also test
with an encrypted link.
@ -100,11 +112,13 @@ 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
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
`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.
@ -115,7 +129,8 @@ 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
```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
@ -131,20 +146,21 @@ Websocket PING localhost.localdomain (127.0.0.1) 64 bytes of data.
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
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.
`-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
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
@ -152,7 +168,7 @@ 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
by `--protocol=protocolname`
Fraggle test app
@ -160,6 +176,7 @@ 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
@ -172,11 +189,13 @@ 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:
give the `-c` switch and the server address at least:
$ libwebsockets-test-fraggle -c localhost
```bash
$ libwebsockets-test-fraggle -c localhost
libwebsockets test fraggle
(C) Copyright 2010-2011 Andy Green <andy@warmcat.com> licensed under LGPL2.1
Client mode
@ -189,6 +208,7 @@ 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
@ -203,13 +223,15 @@ proxy support
-------------
The http_proxy environment variable is respected by the client
connection code for both ws:// and wss://. It doesn't support
connection code for both `ws://` and `wss://`. It doesn't support
authentication.
You use it like this
export http_proxy=myproxy.com:3128
libwebsockets-test-client someserver.com
```bash
$ export http_proxy=myproxy.com:3128
$ libwebsockets-test-client someserver.com
```
debug logging
@ -217,27 +239,27 @@ debug logging
By default logging of severity "notice", "warn" or "err" is enabled to stderr.
Again by default other logging is comiled in but disabled from printing.
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
`--disable-debug` configure option to have it removed from the code by the
preprocesser.
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
test apps you can use -d <number> to control this. The types of logging
select which logs types may print using the `lws_set_log_level()` api, in the
test apps you can use `-d <number>` to control this. The types of logging
available are (OR together the numbers to select multiple)
1 ERR
2 WARN
4 NOTICE
8 INFO
16 DEBUG
32 PARSER
64 HEADER
128 EXTENSION
256 CLIENT
512 LATENCY
- 1 ERR
- 2 WARN
- 4 NOTICE
- 8 INFO
- 16 DEBUG
- 32 PARSER
- 64 HEADER
- 128 EXTENSION
- 256 CLIENT
- 512 LATENCY
Websocket version supported
@ -250,13 +272,13 @@ version 13.
Latency Tracking
----------------
Since libwebsockets runs using poll() and a single threaded approach, any
Since libwebsockets runs using `poll()` and a single threaded approach, any
unexpected latency coming from system calls would be bad news. There's now
a latency tracking scheme that can be built in with --with-latency at
a latency tracking scheme that can be built in with `--with-latency` at
configure-time, logging the time taken for system calls to complete and if
the whole action did complete that time or was deferred.
You can see the detailed data by enabling logging level 512 (eg, -d 519 on
You can see the detailed data by enabling logging level 512 (eg, `-d 519` on
the test server to see that and the usual logs), however even without that
the "worst" latency is kept and reported to the logs with NOTICE severity
when the context is destroyed.
@ -269,4 +291,3 @@ in the logging is the time taken by this particular attempt. High figures
here may indicate a problem, or if you system is loaded with another app at
that time, such as the browser, it may simply indicate the OS gave preferential
treatment to the other app during that call.