From: =?UTF-8?q?Joakim=20S=C3=B6derberg?= Date: Mon, 1 Dec 2014 00:21:10 +0000 (+0100) Subject: Subject: [PATCH] Nicer readmes using markdown. X-Git-Tag: upstream/1.7.3~465 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=4198276505dcc5f32040f11b0794aa0990e6a1cf;p=platform%2Fupstream%2Flibwebsockets.git Subject: [PATCH] Nicer readmes using markdown. This is still readable in raw text, but much nicer for github with heading and syntax highlighting and such. --- diff --git a/README.build b/README.build.md similarity index 69% rename from README.build rename to README.build.md index 5521e06..00a2702 100644 --- a/README.build +++ b/README.build.md @@ -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 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 - /build directory, which can be used to build. + `/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 - - - diff --git a/README.coding b/README.coding.md similarity index 65% rename from README.coding rename to README.coding.md index 333011c..a8a9f9d 100644 --- a/README.coding +++ b/README.coding.md @@ -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. diff --git a/README b/README.md similarity index 80% rename from README rename to README.md index ac17dc0..e84a07d 100644 --- a/README +++ b/README.md @@ -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----- +``` diff --git a/README.test-apps b/README.test-apps.md similarity index 79% rename from README.test-apps rename to README.test-apps.md index f8fb050..2a6635d 100644 --- a/README.test-apps +++ b/README.test-apps.md @@ -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 , see later. +what is logged using `-d `, 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 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 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 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 ` 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. -