Using test-server as a quickstart
---------------------------------
+For a Fedora x86_86 box, the following config line was
+needed:
+
+ ./configure --prefix=/usr --libdir=/usr/lib64 --enable-openssl
+
+For Apple systems, Christopher Baker reported that this is needed
+(and I was told separately enabling openssl makes trouble somehow)
+
+./configure CC="gcc -arch i386 -arch x86_64" CXX="g++ -arch i386 -arch
+x86_64" CPP="gcc -E" CXXCPP="g++ -E" --enable-nofork
+
+
+otherwise if /usr/local/... and /usr/local/lib are OK then...
+
+$ ./configure
+$ make clean
$ make
$ sudo make install
$ libwebsockets-test-server
should be enough to get a test server listening on port 7861.
+There are a couple of other possible configure options
+
+--enable-nofork disables the fork into the background API
+ and removes all references to fork() and
+ pr_ctl() from the sources. Use it if your
+ platform doesn't support forking.
+
+--enable-libcrypto by default libwebsockets uses its own
+ built-in md5 and sha-1 implementation for
+ simplicity. However the libcrypto ones
+ may be faster, and in a distro context it
+ may be highly desirable to use a common
+ library implementation for ease of security
+ upgrades. Give this configure option
+ to disable the built-in ones and force use
+ of the libcrypto (part of openssl) ones.
+
+--with-client-cert-dir=dir tells the client ssl support where to
+ look for trust certificates to validate
+ the remote certificate against.
+
+--enable-noping Don't try to build the ping test app
+ It needs some unixy environment that
+ may choke in other build contexts, this
+ lets you cleanly stop it being built
+
+--enable-x-google-mux Enable experimental x-google-mux support
+ in the build (see notes later in document)
+
+Testing server with a browser
+-----------------------------
+
If you point your browser (eg, Chrome) to
http://127.0.0.1:7681
-It will fetch "./test-server/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.
+Using SSL on the server side
+----------------------------
+
+To test it using SSL/WSS, just run the test server with
+
+$ libwebsockets-test-server --ssl
+
+and use the URL
+
+ https://127.0.0.1:7681
+
+The connection will be entirely encrypted using some generated
+certificates that your browser will not accept, since they are
+not signed by any real Certificate Authority. Just accept the
+certificates in the browser and the connection will proceed
+in first https and then websocket wss, acting exactly the
+same.
+
test-server.c is all that is needed to use libwebsockets for
serving both the script html over http and websockets.
-2010-10-31 Andy Green <andy@warmcat.com>
+
+Forkless operation
+------------------
+
+If your target device does not offer fork(), you can use
+libwebsockets from your own main loop instead. Use the
+configure option --nofork and simply call libwebsocket_service()
+from your own main loop as shown in the test app sources.
+
+
+Testing websocket client support
+--------------------------------
+
+If you run the test server as described above, you can also
+connect to it using the test client as well as a browser.
+
+$ libwebsockets-test-client localhost
+
+will by default connect to the test server on localhost:7681
+and print the dumb increment number from the server at the
+same time as drawing random circles in the mirror protocol;
+if you connect to the test server using a browser at the
+same time you will be able to see the circles being drawn.
+
+
+Testing SSL on the client side
+------------------------------
+
+To test SSL/WSS client action, just run the client test with
+
+$ libwebsockets-test-client localhost --ssl
+
+By default the client test applet is set to accept selfsigned
+certificates used by the test server, this is indicated by the
+use_ssl var being set to 2. Set it to 1 to reject any server
+certificate that it doesn't have a trusted CA cert for.
+
+
+Using the websocket ping utility
+--------------------------------
+
+libwebsockets-test-ping connects as a client to a remote
+websocket server using 04 protocol and pings it like the
+normal unix ping utility.
+
+$ libwebsockets-test-ping localhost
+handshake OK for protocol lws-mirror-protocol
+Websocket PING localhost.localdomain (127.0.0.1) 64 bytes of data.
+64 bytes from localhost: req=1 time=0.1ms
+64 bytes from localhost: req=2 time=0.1ms
+64 bytes from localhost: req=3 time=0.1ms
+64 bytes from localhost: req=4 time=0.2ms
+64 bytes from localhost: req=5 time=0.1ms
+64 bytes from localhost: req=6 time=0.2ms
+64 bytes from localhost: req=7 time=0.2ms
+64 bytes from localhost: req=8 time=0.1ms
+^C
+--- localhost.localdomain websocket ping statistics ---
+8 packets transmitted, 8 received, 0% packet loss, time 7458ms
+rtt min/avg/max = 0.110/0.185/0.218 ms
+$
+
+By default it sends 64 byte payload packets using the 04
+PING packet opcode type. You can change the payload size
+using the -s= flag, up to a maximum of 125 mandated by the
+04 standard.
+
+Using the lws-mirror protocol that is provided by the test
+server, libwebsockets-test-ping can also use larger payload
+sizes up to 4096 is BINARY packets; lws-mirror will copy
+them back to the client and they appear as a PONG. Use the
+-m flag to select this operation.
+
+The default interval between pings is 1s, you can use the -i=
+flag to set this, including fractions like -i=0.01 for 10ms
+interval.
+
+Before you can even use the PING opcode that is part of the
+standard, you must complete a handshake with a specified
+protocol. By default lws-mirror-protocol is used which is
+supported by the test server. But if you are using it on
+another server, you can specify the protcol to handshake with
+by --protocol=protocolname
+
+
+Fraggle test app
+----------------
+
+By default it runs in server mode
+
+$ libwebsockets-test-fraggle
+libwebsockets test fraggle
+(C) Copyright 2010-2011 Andy Green <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:
+
+$ 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.
+
+The fraggle test client receives the same message fragments and computes the
+same checksum using websocket framing to see when the message has ended. It
+then accepts the server checksum message and compares that to its checksum.
+
+
+proxy support
+-------------
+
+The http_proxy environment variable is respected by the client
+connection code for both ws:// and wss://. It doesn't support
+authentication yet.
+
+You use it like this
+
+export http_proxy=myproxy.com:3128
+libwebsockets-test-client someserver.com
+
+
+Websocket version supported
+---------------------------
+
+The websocket client code is 04 and 05 version, the server
+supports 00/76 in text mode and 04 and 05 dynamically
+per-connection depending on the version of the
+client / browser.
+
+
+External Polling Loop support
+-----------------------------
+
+libwebsockets maintains an internal poll() array for all of its
+sockets, but you can instead integrate the sockets into an
+external polling array. That's needed if libwebsockets will
+cooperate with an existing poll array maintained by another
+server.
+
+Four callbacks LWS_CALLBACK_ADD_POLL_FD, LWS_CALLBACK_DEL_POLL_FD,
+LWS_CALLBACK_SET_MODE_POLL_FD and LWS_CALLBACK_CLEAR_MODE_POLL_FD
+appear in the callback for protocol 0 and allow interface code to
+manage socket descriptors in other poll loops.
+
+
+x-google-mux support
+--------------------
+
+Experimental and super-preliminary x-google-mux support is available if
+enabled in ./configure with --enable-x-google-mux. Note that when changing
+configurations, you will need to do a make distclean before, then the new
+configure and then make ; make install. Don't forget the necessary other
+flags for your platform as described at the top of the readme.
+
+It has the following notes:
+
+ 1) To enable it, reconfigure with --enable-x-google-mux
+
+ 2) It conflicts with deflate-stream, use the -u switch on
+ the test client to disable deflate-stream
+
+ 3) It deviates from the google standard by sending full
+ headers in the addchannel subcommand rather than just
+ changed ones from original connect
+
+ 4) Quota is not implemented yet
+
+ 5) Close of subchannel is not really implemented yet
+
+ 6) Google opcode 0xf is changed to 0x7 to account for
+ v7 protocol changes to opcode layout
+
+ However despite those caveats, in fact it can run the
+ test client reliably over one socket (both dumb-increment
+ and lws-mirror-protocol), you can open a browser on the
+ same test server too and see the circles, etc.
+
+
+2011-05-23 Andy Green <andy@warmcat.com>
projects / profile / ivi / libwebsockets.git / blobdiff