libwebsockets/README.md

[![Travis Build Status](https://travis-ci.org/warmcat/libwebsockets.svg)](https://travis-ci.org/warmcat/libwebsockets)
[![Appveyor Build status](https://ci.appveyor.com/api/projects/status/qfasji8mnfnd2r8t?svg=true)](https://ci.appveyor.com/project/lws-team/libwebsockets)
[![Coverity Scan Build Status](https://scan.coverity.com/projects/3576/badge.svg)](https://scan.coverity.com/projects/3576)

![lws-overview](./doc-assets/lws-overview.png)

News
----

## Major CI improvements for QA

The Travis build of lws done on every commit now runs 

Tests|Count|Explanation
---|---|---
Build / Linux / gcc|14|-Wall -Werror cmake config variants
Build / Mac / Clang|14|-Wall -Werror cmake config variants
Build / Windows / MSVC|7|default
Selftests|openssl:33, mbedtls:33|minimal examples built and run against each other and remote server
attack.sh|225|Correctness, robustness and security tests for http parser
Autobahn Server|480|Testing lws ws client, including permessage-deflate
Autobahn Client|480|Testing lws ws server, including permaessage-deflate
h2spec|openssl:146, mbedtls:146|Http/2 server compliance suite (in strict mode)
h2load|openssl:6, mbedtls:6|Http/2 server load tool (checks 10K / 100K in h1 and h2, at 1, 10, 100 concurrency)
h2load SMP|6|Http/2 and http/1.1 server load checks on SMP server build

The over 1,500 tests run on every commit take most of an hour to complete.
If any problems are found, it breaks the travis build, generating an email.

Current master passes all the tests and these new CI arrangements will help
keep it that way.

## Lws has the first official ws-over-h2 server support

![wss-over-h2](https://libwebsockets.org/sc-wss-over-h2.png)

There's a new standard on the RFC track that enables multiplexing ws connections
over an http/2 link.  Compared to making individual tcp and tls connections for
each ws link back to the same server, this makes your site start up radically
faster, and since all the connections are in one tls tunnel, with considerable memory
reduction serverside.

To enable it on master you just need -DLWS_WITH_HTTP2=1 at cmake.  No changes to
existing code are necessary for either http/2 (if you use the official header creation
apis if you return your own headers, as shown in the test apps for several versions)
or to take advantage of ws-over-h2.  When built with http/2 support, it automatically
falls back to http/1 and traditional ws upgrade if that's all the client can handle.

Currently only Chrome Canary v67 supports this ws-over-h2 encapsulation (chrome
must be started with `--enable-websocket-over-http2` switch to enable it currently)
but the other browsers will catch up soon.

## New "minimal examples"

https://github.com/warmcat/libwebsockets/tree/master/minimal-examples

These are like the test apps, but focus on doing one thing, the best way, with the minimum amount of code.  For example the minimal-http-server serves the cwd on http/1 or http/2 in 50 LOC.  Same thing with tls is just three more lines.

They build standalone, so it's easier to copy them directly to start your own project; they
are CC0 licensed (public domain) to facilitate that.

## Windows binary builds

32- and 64-bit Windows binary builds are available via Appveyor.  Visit [lws on Appveyor](https://ci.appveyor.com/project/lws-team/libwebsockets),
click on a build, the ARTIFACTS, and unzip the zip file at `C:\Program Files (x86)/libwebsockets`.

## Latest Stable

 - v2.4.2 is out... HTTP/2 server support and mbedTLS as a TLS backend.

see the changelog https://github.com/warmcat/libwebsockets/blob/v2.4-stable/changelog

Please note the additional READMEs have moved to ./READMEs/

## ESP32 is supported

ESP32 is now supported in lws!  Download the

 - factory https://github.com/warmcat/lws-esp32-factory and
 - test server app https://github.com/warmcat/lws-esp32-test-server-demos

The ESP32 stuff has my dynamic mbedtls buffer allocation patches applied,
which reduce allocation for small payload TLS links by around 26KiB per connection.

## Support

This is the libwebsockets C library for lightweight websocket clients and
servers.  For support, visit

 https://libwebsockets.org
 https://github.com/warmcat/libwebsockets

and consider joining the project mailing list at

 https://libwebsockets.org/mailman/listinfo/libwebsockets

You can get the latest version of the library from git:

- https://github.com/warmcat/libwebsockets
- https://libwebsockets.org/git

Doxygen API docs for master: https://libwebsockets.org/lws-api-doc-master/html/index.html
Update badges in README.md Fix the link to Appveyor and use SVG images. 2016-08-26 23:42:04 +02:00			`[![Travis Build Status](https://travis-ci.org/warmcat/libwebsockets.svg)](https://travis-ci.org/warmcat/libwebsockets)`
			`[![Appveyor Build status](https://ci.appveyor.com/api/projects/status/qfasji8mnfnd2r8t?svg=true)](https://ci.appveyor.com/project/lws-team/libwebsockets)`
README: fix coverity link coverity link was pointing to the wrong project Signed-off-by: Alejandro Mery <amery@geeks.cl> 2014-12-07 03:36:13 +01:00			`[![Coverity Scan Build Status](https://scan.coverity.com/projects/3576/badge.svg)](https://scan.coverity.com/projects/3576)`
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. 2014-12-01 01:21:10 +01:00
lws overview 2018-04-15 09:19:28 +08:00			`![lws-overview](./doc-assets/lws-overview.png)`
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. 2014-12-01 01:21:10 +01:00
esp32: separate factory setup 2017-03-16 10:46:31 +08:00			`News`
			`----`

autobahn fixes This replaces the old test-app for echo with separate client and server minimal versions. The autobahn test script is made more autonomous and tests both client and server. 2018-04-20 10:33:23 +08:00			`## Major CI improvements for QA`

			`The Travis build of lws done on every commit now runs`

			`Tests\|Count\|Explanation`
			`---\|---\|---`
refactor: also migrate tls to the ops struct and private.h pattern Several new ops are planned for tls... so better to bite the bullet and clean it out to the same level as roles + event-libs first. Also adds a new travis target "mbedtls" and all the tests except autobahn against mbedtls build. 2018-05-01 12:41:42 +08:00			`Build / Linux / gcc\|14\|-Wall -Werror cmake config variants`
			`Build / Mac / Clang\|14\|-Wall -Werror cmake config variants`
autobahn fixes This replaces the old test-app for echo with separate client and server minimal versions. The autobahn test script is made more autonomous and tests both client and server. 2018-04-20 10:33:23 +08:00			`Build / Windows / MSVC\|7\|default`
refactor: also migrate tls to the ops struct and private.h pattern Several new ops are planned for tls... so better to bite the bullet and clean it out to the same level as roles + event-libs first. Also adds a new travis target "mbedtls" and all the tests except autobahn against mbedtls build. 2018-05-01 12:41:42 +08:00			`Selftests\|openssl:33, mbedtls:33\|minimal examples built and run against each other and remote server`
autobahn fixes This replaces the old test-app for echo with separate client and server minimal versions. The autobahn test script is made more autonomous and tests both client and server. 2018-04-20 10:33:23 +08:00			`attack.sh\|225\|Correctness, robustness and security tests for http parser`
			`Autobahn Server\|480\|Testing lws ws client, including permessage-deflate`
			`Autobahn Client\|480\|Testing lws ws server, including permaessage-deflate`
refactor: also migrate tls to the ops struct and private.h pattern Several new ops are planned for tls... so better to bite the bullet and clean it out to the same level as roles + event-libs first. Also adds a new travis target "mbedtls" and all the tests except autobahn against mbedtls build. 2018-05-01 12:41:42 +08:00			`h2spec\|openssl:146, mbedtls:146\|Http/2 server compliance suite (in strict mode)`
			`h2load\|openssl:6, mbedtls:6\|Http/2 server load tool (checks 10K / 100K in h1 and h2, at 1, 10, 100 concurrency)`
travis: refactor the yml and add smp-specific tests 2018-04-27 13:09:15 +08:00			`h2load SMP\|6\|Http/2 and http/1.1 server load checks on SMP server build`
autobahn fixes This replaces the old test-app for echo with separate client and server minimal versions. The autobahn test script is made more autonomous and tests both client and server. 2018-04-20 10:33:23 +08:00
refactor: also migrate tls to the ops struct and private.h pattern Several new ops are planned for tls... so better to bite the bullet and clean it out to the same level as roles + event-libs first. Also adds a new travis target "mbedtls" and all the tests except autobahn against mbedtls build. 2018-05-01 12:41:42 +08:00			`The over 1,500 tests run on every commit take most of an hour to complete.`
autobahn fixes This replaces the old test-app for echo with separate client and server minimal versions. The autobahn test script is made more autonomous and tests both client and server. 2018-04-20 10:33:23 +08:00			`If any problems are found, it breaks the travis build, generating an email.`

			`Current master passes all the tests and these new CI arrangements will help`
			`keep it that way.`

h2 ws: fixes against chrome 2018-03-11 11:26:06 +08:00			`## Lws has the first official ws-over-h2 server support`

wss-over-h2: show feedback in test page if active 2018-03-22 07:44:02 +08:00			`![wss-over-h2](https://libwebsockets.org/sc-wss-over-h2.png)`

minimal: http-server-tls 2018-03-20 13:28:25 +08:00			`There's a new standard on the RFC track that enables multiplexing ws connections`
h2 ws: fixes against chrome 2018-03-11 11:26:06 +08:00			`over an http/2 link. Compared to making individual tcp and tls connections for`
			`each ws link back to the same server, this makes your site start up radically`
minimal: http-server-tls 2018-03-20 13:28:25 +08:00			`faster, and since all the connections are in one tls tunnel, with considerable memory`
h2 ws: fixes against chrome 2018-03-11 11:26:06 +08:00			`reduction serverside.`

			`To enable it on master you just need -DLWS_WITH_HTTP2=1 at cmake. No changes to`
			`existing code are necessary for either http/2 (if you use the official header creation`
			`apis if you return your own headers, as shown in the test apps for several versions)`
			`or to take advantage of ws-over-h2. When built with http/2 support, it automatically`
			`falls back to http/1 and traditional ws upgrade if that's all the client can handle.`

minimal: http-server-tls 2018-03-20 13:28:25 +08:00			`Currently only Chrome Canary v67 supports this ws-over-h2 encapsulation (chrome`
			must be started with `--enable-websocket-over-http2` switch to enable it currently)
			`but the other browsers will catch up soon.`
h2 ws: fixes against chrome 2018-03-11 11:26:06 +08:00
smp: force cancel on pt that was assigned new wsi 2018-03-08 12:04:13 +08:00			`## New "minimal examples"`

			`https://github.com/warmcat/libwebsockets/tree/master/minimal-examples`

minimal: http-server-tls 2018-03-20 13:28:25 +08:00			`These are like the test apps, but focus on doing one thing, the best way, with the minimum amount of code. For example the minimal-http-server serves the cwd on http/1 or http/2 in 50 LOC. Same thing with tls is just three more lines.`
smp: force cancel on pt that was assigned new wsi 2018-03-08 12:04:13 +08:00
minimal: http-server-tls 2018-03-20 13:28:25 +08:00			`They build standalone, so it's easier to copy them directly to start your own project; they`
smp: force cancel on pt that was assigned new wsi 2018-03-08 12:04:13 +08:00			`are CC0 licensed (public domain) to facilitate that.`

			`## Windows binary builds`

appveyor artifacts debug 2017-10-26 07:24:45 +08:00			`32- and 64-bit Windows binary builds are available via Appveyor. Visit [lws on Appveyor](https://ci.appveyor.com/project/lws-team/libwebsockets),`
			click on a build, the ARTIFACTS, and unzip the zip file at `C:\Program Files (x86)/libwebsockets`.

smp: force cancel on pt that was assigned new wsi 2018-03-08 12:04:13 +08:00			`## Latest Stable`

			`- v2.4.2 is out... HTTP/2 server support and mbedTLS as a TLS backend.`
v2.4.0 2017-10-16 20:09:58 +08:00
			`see the changelog https://github.com/warmcat/libwebsockets/blob/v2.4-stable/changelog`

clean up top level of project 2017-09-22 09:46:58 +08:00			`Please note the additional READMEs have moved to ./READMEs/`

smp: force cancel on pt that was assigned new wsi 2018-03-08 12:04:13 +08:00			`## ESP32 is supported`
v2.3.0 2017-07-28 14:13:42 +08:00
esp32: separate factory setup 2017-03-16 10:46:31 +08:00			`ESP32 is now supported in lws! Download the`

			`- factory https://github.com/warmcat/lws-esp32-factory and`
			`- test server app https://github.com/warmcat/lws-esp32-test-server-demos`

smp: force cancel on pt that was assigned new wsi 2018-03-08 12:04:13 +08:00			`The ESP32 stuff has my dynamic mbedtls buffer allocation patches applied,`
			`which reduce allocation for small payload TLS links by around 26KiB per connection.`

			`## Support`
client fixups after esp8266 2016-08-07 08:33:08 +08:00
add README Signed-off-by: Andy Green <andy.green@linaro.org> 2013-02-06 16:07:27 +09:00			`This is the libwebsockets C library for lightweight websocket clients and`
			`servers. For support, visit`

libwebsockets.org url updates Signed-off-by: Andy Green <andy.green@linaro.org> 2016-02-21 10:42:46 +08:00			`https://libwebsockets.org`
			`https://github.com/warmcat/libwebsockets`
add README Signed-off-by: Andy Green <andy.green@linaro.org> 2013-02-06 16:07:27 +09:00
			`and consider joining the project mailing list at`

libwebsockets.org url updates Signed-off-by: Andy Green <andy.green@linaro.org> 2016-02-21 10:42:46 +08:00			`https://libwebsockets.org/mailman/listinfo/libwebsockets`
add README Signed-off-by: Andy Green <andy.green@linaro.org> 2013-02-06 16:07:27 +09:00
libwebsockets.org url updates Signed-off-by: Andy Green <andy.green@linaro.org> 2016-02-21 10:42:46 +08:00			`You can get the latest version of the library from git:`
add README Signed-off-by: Andy Green <andy.green@linaro.org> 2013-02-06 16:07:27 +09:00
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. 2014-12-01 01:21:10 +01:00			`- https://github.com/warmcat/libwebsockets`
libwebsockets.org url updates Signed-off-by: Andy Green <andy.green@linaro.org> 2016-02-21 10:42:46 +08:00			`- https://libwebsockets.org/git`
add README Signed-off-by: Andy Green <andy.green@linaro.org> 2013-02-06 16:07:27 +09:00
documentation convert to doxygen Signed-off-by: Andy Green <andy@warmcat.com> 2016-06-20 17:05:31 +08:00			`Doxygen API docs for master: https://libwebsockets.org/lws-api-doc-master/html/index.html`
add README Signed-off-by: Andy Green <andy.green@linaro.org> 2013-02-06 16:07:27 +09:00