Andy Green | 6c1f64e | 2013-01-20 11:28:06 +0800 | [diff] [blame] | 1 | Testing server with a browser |
| 2 | ----------------------------- |
| 3 | |
| 4 | If you run libwebsockets-test-server and point your browser |
| 5 | (eg, Chrome) to |
| 6 | |
| 7 | http://127.0.0.1:7681 |
| 8 | |
| 9 | It will fetch a script in the form of test.html, and then run the |
| 10 | script in there on the browser to open a websocket connection. |
| 11 | Incrementing numbers should appear in the browser display. |
| 12 | |
| 13 | By default the test server logs to both stderr and syslog, you can control |
| 14 | what is logged using -d <log level>, see later. |
| 15 | |
| 16 | |
| 17 | Running test server as a Daemon |
| 18 | ------------------------------- |
| 19 | |
| 20 | You can use the -D option on the test server to have it fork into the |
| 21 | background and return immediately. In this daemonized mode all stderr is |
| 22 | disabled and logging goes only to syslog, eg, /var/log/messages or similar. |
| 23 | |
| 24 | The server maintains a lockfile at /tmp/.lwsts-lock that contains the pid |
| 25 | of the master process, and deletes this file when the master process |
| 26 | terminates. |
| 27 | |
| 28 | To stop the daemon, do |
| 29 | |
| 30 | kill `cat /tmp/.lwsts-lock` |
| 31 | |
| 32 | If it finds a stale lock (the pid mentioned in the file does not exist |
| 33 | any more) it will delete the lock and create a new one during startup. |
| 34 | |
| 35 | If the lock is valid, the daemon will exit with a note on stderr that |
| 36 | it was already running.s |
| 37 | |
| 38 | |
| 39 | Using SSL on the server side |
| 40 | ---------------------------- |
| 41 | |
| 42 | To test it using SSL/WSS, just run the test server with |
| 43 | |
| 44 | $ libwebsockets-test-server --ssl |
| 45 | |
| 46 | and use the URL |
| 47 | |
| 48 | https://127.0.0.1:7681 |
| 49 | |
| 50 | The connection will be entirely encrypted using some generated |
| 51 | certificates that your browser will not accept, since they are |
| 52 | not signed by any real Certificate Authority. Just accept the |
| 53 | certificates in the browser and the connection will proceed |
| 54 | in first https and then websocket wss, acting exactly the |
| 55 | same. |
| 56 | |
| 57 | test-server.c is all that is needed to use libwebsockets for |
| 58 | serving both the script html over http and websockets. |
| 59 | |
| 60 | |
Andy Green | 6c1f64e | 2013-01-20 11:28:06 +0800 | [diff] [blame] | 61 | Testing websocket client support |
| 62 | -------------------------------- |
| 63 | |
| 64 | If you run the test server as described above, you can also |
| 65 | connect to it using the test client as well as a browser. |
| 66 | |
| 67 | $ libwebsockets-test-client localhost |
| 68 | |
| 69 | will by default connect to the test server on localhost:7681 |
| 70 | and print the dumb increment number from the server at the |
| 71 | same time as drawing random circles in the mirror protocol; |
| 72 | if you connect to the test server using a browser at the |
| 73 | same time you will be able to see the circles being drawn. |
| 74 | |
| 75 | |
Andy Green | 769153e | 2013-01-30 11:03:01 +0800 | [diff] [blame] | 76 | Testing simple echo |
| 77 | ------------------- |
| 78 | |
| 79 | You can test against echo.websockets.org as a sanity test like |
| 80 | this (the client connects to port 80 by default): |
| 81 | |
| 82 | $ libwebsockets-test-echo --client echo.websocket.org |
| 83 | |
| 84 | This echo test is of limited use though because it doesn't |
| 85 | negotiate any protocol. You can run the same test app as a |
| 86 | local server, by default on localhost:7681 |
| 87 | |
| 88 | $ libwebsockets-test-echo |
| 89 | |
| 90 | and do the echo test against the local echo server |
| 91 | |
| 92 | $ libwebsockets-test-echo --client localhost --port 7681 |
| 93 | |
| 94 | If you add the --ssl switch to both the client and server, you can also test |
| 95 | with an encrypted link. |
| 96 | |
| 97 | |
Andy Green | 6c1f64e | 2013-01-20 11:28:06 +0800 | [diff] [blame] | 98 | Testing SSL on the client side |
| 99 | ------------------------------ |
| 100 | |
| 101 | To test SSL/WSS client action, just run the client test with |
| 102 | |
| 103 | $ libwebsockets-test-client localhost --ssl |
| 104 | |
| 105 | By default the client test applet is set to accept selfsigned |
| 106 | certificates used by the test server, this is indicated by the |
| 107 | use_ssl var being set to 2. Set it to 1 to reject any server |
| 108 | certificate that it doesn't have a trusted CA cert for. |
| 109 | |
| 110 | |
| 111 | Using the websocket ping utility |
| 112 | -------------------------------- |
| 113 | |
| 114 | libwebsockets-test-ping connects as a client to a remote |
| 115 | websocket server using 04 protocol and pings it like the |
| 116 | normal unix ping utility. |
| 117 | |
| 118 | $ libwebsockets-test-ping localhost |
| 119 | handshake OK for protocol lws-mirror-protocol |
| 120 | Websocket PING localhost.localdomain (127.0.0.1) 64 bytes of data. |
| 121 | 64 bytes from localhost: req=1 time=0.1ms |
| 122 | 64 bytes from localhost: req=2 time=0.1ms |
| 123 | 64 bytes from localhost: req=3 time=0.1ms |
| 124 | 64 bytes from localhost: req=4 time=0.2ms |
| 125 | 64 bytes from localhost: req=5 time=0.1ms |
| 126 | 64 bytes from localhost: req=6 time=0.2ms |
| 127 | 64 bytes from localhost: req=7 time=0.2ms |
| 128 | 64 bytes from localhost: req=8 time=0.1ms |
| 129 | ^C |
| 130 | --- localhost.localdomain websocket ping statistics --- |
| 131 | 8 packets transmitted, 8 received, 0% packet loss, time 7458ms |
| 132 | rtt min/avg/max = 0.110/0.185/0.218 ms |
| 133 | $ |
| 134 | |
| 135 | By default it sends 64 byte payload packets using the 04 |
| 136 | PING packet opcode type. You can change the payload size |
| 137 | using the -s= flag, up to a maximum of 125 mandated by the |
| 138 | 04 standard. |
| 139 | |
| 140 | Using the lws-mirror protocol that is provided by the test |
| 141 | server, libwebsockets-test-ping can also use larger payload |
| 142 | sizes up to 4096 is BINARY packets; lws-mirror will copy |
| 143 | them back to the client and they appear as a PONG. Use the |
| 144 | -m flag to select this operation. |
| 145 | |
| 146 | The default interval between pings is 1s, you can use the -i= |
| 147 | flag to set this, including fractions like -i=0.01 for 10ms |
| 148 | interval. |
| 149 | |
| 150 | Before you can even use the PING opcode that is part of the |
| 151 | standard, you must complete a handshake with a specified |
| 152 | protocol. By default lws-mirror-protocol is used which is |
| 153 | supported by the test server. But if you are using it on |
| 154 | another server, you can specify the protcol to handshake with |
| 155 | by --protocol=protocolname |
| 156 | |
| 157 | |
| 158 | Fraggle test app |
| 159 | ---------------- |
| 160 | |
| 161 | By default it runs in server mode |
| 162 | |
| 163 | $ libwebsockets-test-fraggle |
| 164 | libwebsockets test fraggle |
| 165 | (C) Copyright 2010-2011 Andy Green <andy@warmcat.com> licensed under LGPL2.1 |
| 166 | Compiled with SSL support, not using it |
| 167 | Listening on port 7681 |
| 168 | server sees client connect |
| 169 | accepted v06 connection |
| 170 | Spamming 360 random fragments |
| 171 | Spamming session over, len = 371913. sum = 0x2D3C0AE |
| 172 | Spamming 895 random fragments |
| 173 | Spamming session over, len = 875970. sum = 0x6A74DA1 |
| 174 | ... |
| 175 | |
| 176 | You need to run a second session in client mode, you have to |
| 177 | give the -c switch and the server address at least: |
| 178 | |
| 179 | $ libwebsockets-test-fraggle -c localhost |
| 180 | libwebsockets test fraggle |
| 181 | (C) Copyright 2010-2011 Andy Green <andy@warmcat.com> licensed under LGPL2.1 |
| 182 | Client mode |
| 183 | Connecting to localhost:7681 |
| 184 | denied deflate-stream extension |
| 185 | handshake OK for protocol fraggle-protocol |
| 186 | client connects to server |
| 187 | EOM received 371913 correctly from 360 fragments |
| 188 | EOM received 875970 correctly from 895 fragments |
| 189 | EOM received 247140 correctly from 258 fragments |
| 190 | EOM received 695451 correctly from 692 fragments |
| 191 | ... |
| 192 | |
| 193 | The fraggle test sends a random number up to 1024 fragmented websocket frames |
| 194 | each of a random size between 1 and 2001 bytes in a single message, then sends |
| 195 | a checksum and starts sending a new randomly sized and fragmented message. |
| 196 | |
| 197 | The fraggle test client receives the same message fragments and computes the |
| 198 | same checksum using websocket framing to see when the message has ended. It |
| 199 | then accepts the server checksum message and compares that to its checksum. |
| 200 | |
| 201 | |
| 202 | proxy support |
| 203 | ------------- |
| 204 | |
| 205 | The http_proxy environment variable is respected by the client |
| 206 | connection code for both ws:// and wss://. It doesn't support |
| 207 | authentication. |
| 208 | |
| 209 | You use it like this |
| 210 | |
| 211 | export http_proxy=myproxy.com:3128 |
| 212 | libwebsockets-test-client someserver.com |
| 213 | |
| 214 | |
| 215 | debug logging |
| 216 | ------------- |
| 217 | |
| 218 | By default logging of severity "notice", "warn" or "err" is enabled to stderr. |
| 219 | |
| 220 | Again by default other logging is comiled in but disabled from printing. |
| 221 | |
| 222 | If you want to eliminate the debug logging below notice in severity, use the |
| 223 | --disable-debug configure option to have it removed from the code by the |
| 224 | preprocesser. |
| 225 | |
| 226 | If you want to see more detailed debug logs, you can control a bitfield to |
| 227 | select which logs types may print using the lws_set_log_level() api, in the |
| 228 | test apps you can use -d <number> to control this. The types of logging |
| 229 | available are (OR together the numbers to select multiple) |
| 230 | |
| 231 | 1 ERR |
| 232 | 2 WARN |
| 233 | 4 NOTICE |
| 234 | 8 INFO |
| 235 | 16 DEBUG |
| 236 | 32 PARSER |
| 237 | 64 HEADER |
| 238 | 128 EXTENSION |
| 239 | 256 CLIENT |
Andy Green | d636e35 | 2013-01-29 12:36:17 +0800 | [diff] [blame] | 240 | 512 LATENCY |
Andy Green | 6c1f64e | 2013-01-20 11:28:06 +0800 | [diff] [blame] | 241 | |
| 242 | |
| 243 | Websocket version supported |
| 244 | --------------------------- |
| 245 | |
Andy Green | 3b228c5 | 2013-01-30 08:31:43 +0800 | [diff] [blame] | 246 | The final IETF standard is supported for both client and server, protocol |
| 247 | version 13. |
Andy Green | 6c1f64e | 2013-01-20 11:28:06 +0800 | [diff] [blame] | 248 | |
| 249 | |
Andy Green | d636e35 | 2013-01-29 12:36:17 +0800 | [diff] [blame] | 250 | Latency Tracking |
| 251 | ---------------- |
| 252 | |
| 253 | Since libwebsockets runs using poll() and a single threaded approach, any |
| 254 | unexpected latency coming from system calls would be bad news. There's now |
| 255 | a latency tracking scheme that can be built in with --with-latency at |
| 256 | configure-time, logging the time taken for system calls to complete and if |
| 257 | the whole action did complete that time or was deferred. |
| 258 | |
| 259 | You can see the detailed data by enabling logging level 512 (eg, -d 519 on |
| 260 | the test server to see that and the usual logs), however even without that |
| 261 | the "worst" latency is kept and reported to the logs with NOTICE severity |
| 262 | when the context is destroyed. |
| 263 | |
| 264 | Some care is needed interpreting them, if the action completed the first figure |
| 265 | (in us) is the time taken for the whole action, which may have retried through |
| 266 | the poll loop many times and will depend on network roundtrip times. High |
| 267 | figures here don't indicate a problem. The figure in us reported after "lat" |
| 268 | in the logging is the time taken by this particular attempt. High figures |
| 269 | here may indicate a problem, or if you system is loaded with another app at |
| 270 | that time, such as the browser, it may simply indicate the OS gave preferential |
| 271 | treatment to the other app during that call. |
| 272 | |