{"schema":"libjg2-1", "vpath":"/git/", "avatar":"/git/avatar/", "alang":"", "gen_ut":1713301813, "reponame":"libwebsockets", "desc":"libwebsockets lightweight C networking library", "owner": { "name": "Andy Green", "email": "andy@warmcat.com", "md5": "c50933ca2aa61e0fe2c43d46bb6b59cb" },"url":"https://libwebsockets.org/repo/libwebsockets", "f":3, "items": [ {"schema":"libjg2-1", "cid":"af2b9b2845b32c5368fbf1615380ccfb", "oid":{ "oid": "ec76f8178dde74d9c9f485e0e2ff609a0b8ec1f4", "alias": [ "refs/heads/main"]},"blobname": "READMEs/README.test-apps.md", "blob": "Overview of lws test apps\n\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\n\nAre you building a client? You just need to look at the test client\n[libwebsockets-test-client](../test-apps/test-client.c).\n\nIf you are building a standalone server, there are three choices, in order of\npreferability.\n\n1) lwsws + protocol plugins\n\nLws provides a generic web server app that can be configured with JSON\nconfig files. https://libwebsockets.org itself uses this method.\n\nWith lwsws handling the serving part, you only need to write an lws protocol\nplugin. See [plugin-standalone](../plugin-standalone) for an example of how\nto do that outside lws itself, using lws public apis.\n\n $ cmake .. -DLWS_WITH_LWSWS\u003d1\n\nSee [README.lwsws.md](../READMEs/README.lwsws.md) for information on how to configure\nlwsws.\n\nNOTE this method implies libuv is used by lws, to provide crossplatform\nimplementations of timers, dynamic lib loading etc for plugins and lwsws.\n\n2) Using plugins in code\n\nThis method lets you configure web serving in code, instead of using lwsws.\n\nPlugins are still used, but you have a choice whether to dynamically load\nthem or statically include them. In this example, they are dynamically\nloaded.\n\n $ cmake .. -DLWS_WITH_PLUGINS\u003d1\n\nSee, eg, the [test-server](../test-apps/test-server.c)\n\n3) protocols in the server app\n\nThis is the original way lws implemented servers, plugins and libuv are not\nrequired, but without plugins separating the protocol code directly, the\ncombined code is all squidged together and is much less maintainable.\n\nThis method is still supported in lws but all ongoing and future work is\nbeing done in protocol plugins only.\n\nYou can simply include the plugin contents and have it buit statically into\nyour server, just define this before including the plugin source\n\n```\n#define LWS_PLUGIN_STATIC\n```\n\nThis gets you most of the advantages without needing dynamic loading +\nlibuv.\n\n\nNotes about lws test apps\n\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\n\n@section tsb Testing server with a browser\n\nIf you run [libwebsockets-test-server](../test-apps/test-server.c) and point your browser\n(eg, Chrome) to\n\n\thttp://127.0.0.1:7681\n\nIt will fetch a script in the form of `test.html`, and then run the\nscript in there on the browser to open a websocket connection.\nIncrementing numbers should appear in the browser display.\n\nBy default the test server logs to both stderr and syslog, you can control\nwhat is logged using `-d \u003clog level\u003e`, see later.\n\n\n@section tsd Running test server as a Daemon\n\nYou can use the -D option on the test server to have it fork into the\nbackground and return immediately. In this daemonized mode all stderr is\ndisabled and logging goes only to syslog, eg, `/var/log/messages` or similar.\n\nThe server maintains a lockfile at `/tmp/.lwsts-lock` that contains the pid\nof the parent process, and deletes this file when the parent process\nterminates.\n\nTo stop the daemon, do\n```\n $ kill \u005c`cat /tmp/.lwsts-lock\u005c`\n```\nIf it finds a stale lock (the pid mentioned in the file does not exist\nany more) it will delete the lock and create a new one during startup.\n\nIf the lock is valid, the daemon will exit with a note on stderr that\nit was already running.\n\n@section clicert Testing Client Certs\n\nHere is a very quick way to create a CA, and a client and server cert from it,\nfor testing.\n\n```\n$ cp -rp ./scripts/client-ca /tmp\n$ cd /tmp/client-ca\n$ ./create-ca.sh\n$ ./create-server-cert.sh server\n$ ./create-client-cert.sh client\n```\n\nThe last step wants an export password, you will need this password again to\nimport the p12 format certificate into your browser.\n\nThis will get you the following\n\n|name|function|\n|----|--------|\n|ca.pem|Your Certificate Authority cert|\n|ca.key|Private key for the CA cert|\n|client.pem|Client certificate, signed by your CA|\n|client.key|Client private key|\n|client.p12|combined client.pem + client.key in p12 format for browsers|\n|server.pem|Server cert, signed by your CA|\n|server.key|Server private key|\n\nYou can confirm yourself the client and server certs are signed by the CA.\n\n```\n $ openssl verify -verbose -trusted ca.pem server.pem\n $ openssl verify -verbose -trusted ca.pem client.pem\n```\n\nImport the client.p12 file into your browser. In FFOX57 it's\n\n - preferences\n - Privacy \u0026 Security\n - Certificates | View Certificates\n - Certificate Manager | Your Certificates | Import...\n - Enter the password you gave when creating client1.p12\n - Click OK.\n\nYou can then run the test server like this:\n\n```\n $ libwebsockets-test-server -s -A ca.pem -K server.key -C server.pem -v\n```\n\nWhen you connect your browser to https://localhost:7681 after accepting the\nselfsigned server cert, your browser will pop up a prompt to send the server\nyour client cert (the -v switch enables this). The server will only accept\na client cert that has been signed by ca.pem.\n\n@section sssl Using SSL on the server side\n\nTo test it using SSL/WSS, just run the test server with\n```\n\t$ libwebsockets-test-server --ssl\n```\nand use the URL\n```\n\thttps://127.0.0.1:7681\n```\nThe connection will be entirely encrypted using some generated\ncertificates that your browser will not accept, since they are\nnot signed by any real Certificate Authority. Just accept the\ncertificates in the browser and the connection will proceed\nin first https and then websocket wss, acting exactly the\nsame.\n\n[test-server.c](../test-apps/test-server.c) is all that is needed to use libwebsockets for\nserving both the script html over http and websockets.\n\n@section lwstsdynvhost Dynamic Vhosts\n\nYou can send libwebsockets-test-server or libwebsockets-test-server-v2.0 a SIGUSR1\nto toggle the creation and destruction of an identical second vhost on port + 1.\n\nThis is intended as a test and demonstration for how to bring up and remove\nvhosts dynamically.\n\n@section unixskt Testing Unix Socket Server support\n\nStart the test server with -U and the path to create the unix domain socket\n\n```\n $ libwebsockets-test-server -U /tmp/uds\n```\n\nOn exit, lws will delete the socket inode.\n\nTo test the client side, eg\n\n```\n $ nc -C -U /tmp/uds -i 30\n```\n\nand type\n\n`GET / HTTP/1.1`\n\nfollowed by two ENTER. The contents of test.html should be returned.\n\n@section wscl Testing websocket client support\n\nIf you run the test server as described above, you can also\nconnect to it using the test client as well as a browser.\n\n```\n\t$ libwebsockets-test-client localhost\n```\n\nwill by default connect to the test server on localhost:7681\nand print the dumb increment number from the server at the\nsame time as drawing random circles in the mirror protocol;\nif you connect to the test server using a browser at the\nsame time you will be able to see the circles being drawn.\n\nThe test client supports SSL too, use\n\n```\n\t$ libwebsockets-test-client localhost --ssl -s\n```\n\nthe -s tells it to accept the default self-signed cert from the server,\notherwise it will strictly fail the connection if there is no CA cert to\nvalidate the server's certificate.\n\n\n@section choosingts Choosing between test server variations\n\nIf you will be doing standalone serving with lws, ideally you should avoid\nmaking your own server at all, and use lwsws with your own protocol plugins.\n\nThe second best option is follow test-server-v2.0.c, which uses a mount to\nautoserve a directory, and lws protocol plugins for ws, without needing any\nuser callback code (other than what's needed in the protocol plugin).\n\nFor those two options libuv is needed to support the protocol plugins, if\nthat's not possible then the other variations with their own protocol code\nshould be considered.\n\n@section tassl Testing SSL on the client side\n\nTo test SSL/WSS client action, just run the client test with\n```\n\t$ libwebsockets-test-client localhost --ssl\n```\nBy default the client test applet is set to accept self-signed\ncertificates used by the test server, this is indicated by the\n`use_ssl` var being set to `2`. Set it to `1` to reject any server\ncertificate that it doesn't have a trusted CA cert for.\n\n\n@section taping Using the websocket ping utility\n\nlibwebsockets-test-ping connects as a client to a remote\nwebsocket server and pings it like the\nnormal unix ping utility.\n```\n\t$ libwebsockets-test-ping localhost\n\thandshake OK for protocol lws-mirror-protocol\n\tWebsocket PING localhost.localdomain (127.0.0.1) 64 bytes of data.\n\t64 bytes from localhost: req\u003d1 time\u003d0.1ms\n\t64 bytes from localhost: req\u003d2 time\u003d0.1ms\n\t64 bytes from localhost: req\u003d3 time\u003d0.1ms\n\t64 bytes from localhost: req\u003d4 time\u003d0.2ms\n\t64 bytes from localhost: req\u003d5 time\u003d0.1ms\n\t64 bytes from localhost: req\u003d6 time\u003d0.2ms\n\t64 bytes from localhost: req\u003d7 time\u003d0.2ms\n\t64 bytes from localhost: req\u003d8 time\u003d0.1ms\n\t^C\n\t--- localhost.localdomain websocket ping statistics ---\n\t8 packets transmitted, 8 received, 0% packet loss, time 7458ms\n\trtt min/avg/max \u003d 0.110/0.185/0.218 ms\n\t$\n```\nBy default it sends 64 byte payload packets using the 04\nPING packet opcode type. You can change the payload size\nusing the `-s\u003d` flag, up to a maximum of 125 mandated by the\n04 standard.\n\nUsing the lws-mirror protocol that is provided by the test\nserver, libwebsockets-test-ping can also use larger payload\nsizes up to 4096 is BINARY packets; lws-mirror will copy\nthem back to the client and they appear as a PONG. Use the\n`-m` flag to select this operation.\n\nThe default interval between pings is 1s, you can use the -i\u003d\nflag to set this, including fractions like `-i\u003d0.01` for 10ms\ninterval.\n\nBefore you can even use the PING opcode that is part of the\nstandard, you must complete a handshake with a specified\nprotocol. By default lws-mirror-protocol is used which is\nsupported by the test server. But if you are using it on\nanother server, you can specify the protocol to handshake with\nby `--protocol\u003dprotocolname`\n\n\n@section ta fraggle Fraggle test app\n\nBy default it runs in server mode\n```\n\t$ libwebsockets-test-fraggle\n\tlibwebsockets test fraggle\n\t(C) Copyright 2010-2011 Andy Green \u003candy@warmcat.com\u003e licensed under MIT\n\t Compiled with SSL support, not using it\n\t Listening on port 7681\n\tserver sees client connect\n\taccepted v06 connection\n\tSpamming 360 random fragments\n\tSpamming session over, len \u003d 371913. sum \u003d 0x2D3C0AE\n\tSpamming 895 random fragments\n\tSpamming session over, len \u003d 875970. sum \u003d 0x6A74DA1\n\t...\n```\nYou need to run a second session in client mode, you have to\ngive the `-c` switch and the server address at least:\n```\n\t$ libwebsockets-test-fraggle -c localhost\n\tlibwebsockets test fraggle\n\t(C) Copyright 2010-2011 Andy Green \u003candy@warmcat.com\u003e licensed under MIT\n\t Client mode\n\tConnecting to localhost:7681\n\tdenied deflate-stream extension\n\thandshake OK for protocol fraggle-protocol\n\tclient connects to server\n\tEOM received 371913 correctly from 360 fragments\n\tEOM received 875970 correctly from 895 fragments\n\tEOM received 247140 correctly from 258 fragments\n\tEOM received 695451 correctly from 692 fragments\n\t...\n```\nThe fraggle test sends a random number up to 1024 fragmented websocket frames\neach of a random size between 1 and 2001 bytes in a single message, then sends\na checksum and starts sending a new randomly sized and fragmented message.\n\nThe fraggle test client receives the same message fragments and computes the\nsame checksum using websocket framing to see when the message has ended. It\nthen accepts the server checksum message and compares that to its checksum.\n\n\n@section taproxy proxy support\n\nThe http_proxy environment variable is respected by the client\nconnection code for both `ws://` and `wss://`. It doesn't support\nauthentication.\n\nYou use it like this\n```\n\t$ export http_proxy\u003dmyproxy.com:3128\n\t$ libwebsockets-test-client someserver.com\n```\n\n@section talog debug logging\n\nBy default logging of severity \u0022notice\u0022, \u0022warn\u0022 or \u0022err\u0022 is enabled to stderr.\n\nAgain by default other logging is compiled in but disabled from printing.\n\nBy default debug logs below \u0022notice\u0022 in severity are not compiled in. To get\nthem included, add this option in CMAKE\n\n```\n\t$ cmake .. -DCMAKE_BUILD_TYPE\u003dDEBUG\n```\n\nIf you want to see more detailed debug logs, you can control a bitfield to\nselect which logs types may print using the `lws_set_log_level()` api, in the\ntest apps you can use `-d \u003cnumber\u003e` to control this. The types of logging\navailable are (OR together the numbers to select multiple)\n\n - 1 ERR\n - 2 WARN\n - 4 NOTICE\n - 8 INFO\n - 16 DEBUG\n - 32 PARSER\n - 64 HEADER\n - 128 EXTENSION\n - 256 CLIENT\n - 512 LATENCY\n\n\n@section ws13 Websocket version supported\n\nThe final IETF standard is supported for both client and server, protocol\nversion 13.\n\n\n@section latency Latency Tracking\n\nSince libwebsockets runs using `poll()` and a single threaded approach, any\nunexpected latency coming from system calls would be bad news. There's now\na latency tracking scheme that can be built in with `-DLWS_WITH_LATENCY\u003d1` at\ncmake, logging the time taken for system calls to complete and if\nthe whole action did complete that time or was deferred.\n\nYou can see the detailed data by enabling logging level 512 (eg, `-d 519` on\nthe test server to see that and the usual logs), however even without that\nthe \u0022worst\u0022 latency is kept and reported to the logs with NOTICE severity\nwhen the context is destroyed.\n\nSome care is needed interpreting them, if the action completed the first figure\n(in us) is the time taken for the whole action, which may have retried through\nthe poll loop many times and will depend on network roundtrip times. High\nfigures here don't indicate a problem. The figure in us reported after \u0022lat\u0022\nin the logging is the time taken by this particular attempt. High figures\nhere may indicate a problem, or if you system is loaded with another app at\nthat time, such as the browser, it may simply indicate the OS gave preferential\ntreatment to the other app during that call.\n\n\n@section autobahn Autobahn Test Suite\n\nLws can be tested against the autobahn websocket fuzzer in both client and\nserver modes\n\n1) pip install autobahntestsuite\n\n2) From your build dir:\n\n```\n $ cmake .. -DLWS_WITHOUT_EXTENSIONS\u003d0 -DLWS_WITH_MINIMAL_EXAMPLES\u003d1 \u0026\u0026 make\n```\n\n3) ../scripts/autobahn-test.sh\n\n4) In a browser go to the directory you ran wstest in (eg, /projects/libwebsockets)\n\nfile:///projects/libwebsockets/build/reports/clients/index.html\n\nto see the results\n\n\n@section autobahnnotes Autobahn Test Notes\n\n1) Two of the tests make no sense for Libwebsockets to support and we fail them.\n\n - Tests 2.10 + 2.11: sends multiple pings on one connection. Lws policy is to\nonly allow one active ping in flight on each connection, the rest are dropped.\nThe autobahn test itself admits this is not part of the standard, just someone's\nrandom opinion about how they think a ws server should act. So we will fail\nthis by design and it is no problem about RFC6455 compliance.\n\n2) Currently two parts of autobahn are broken and we skip them\n\nhttps://github.com/crossbario/autobahn-testsuite/issues/71\n \n","s":{"c":1713301813,"u": 700}} ],"g": 2212,"chitpc": 0,"ehitpc": 0,"indexed":0 , "ab": 1, "si": 0, "db":0, "di":0, "sat":0, "lfc": "0000"}