Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/eagafonov/libwebsockets

Clone of http://git.warmcat.com/cgi-bin/cgit/libwebsockets for fixes and some new stuff
https://github.com/eagafonov/libwebsockets

Last synced: 3 days ago
JSON representation

Clone of http://git.warmcat.com/cgi-bin/cgit/libwebsockets for fixes and some new stuff

Awesome Lists containing this project

README 

        
Using test-server as a quickstart

---------------------------------



You need to regenerate the autotools and libtoolize stuff for your system



$ ./autogen.sh



Then 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



For mingw build, I did the following to get working build, ping test is

disabled when building this way



1) install mingw64_w32 compiler packages from Fedora

2) additionally install mingw64-zlib package

3) ./configure --prefix=/usr --enable-mingw --host=x86_64-w64-mingw32

4) make



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 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.



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  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  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 deviates from the google standard by sending full

       headers in the addchannel subcommand rather than just

       changed ones from original connect

    

    3) Quota is not implemented yet

    

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.



It also works compatibly with deflate-stream automatically.



2012-04-12  Andy Green