7 - This is the last planned release under LGPLv2+SLE. It's not planned to be
8 maintained like previous releases, please switch to master for the latest
9 stuff or continue to use v3.1-stable until the next release under the
12 - NEW: completely refactored scheduler with a unified, sorted us-resolution
13 linked-list implementation. All polled checks like timeout are migrated
14 to use the new timers, which also work on the event lib implementations.
15 Faster operation, us-resolution timeouts and generic scheduled callbacks
18 - NEW: lws_dsh specialized buffer memory allocator that can borrow space
19 from other cooperating buffers on the same list.
21 - NEW: lws_sequencer allows managing multi-connection processes and
24 - NEW: memory buffer cert support
26 - NEW: LWS_WITH_NETWORK in CMake... can be configured without any network-
29 - NEW: builds on QNX 6.5 and SmartOS
31 - NEW: JOSE / JWK / JWS / JWE support, for all common ciphers and algs,
32 works on OpenSSL and mbedtls backends
34 - NEW: gencrypto now has genaes and genec in addition to genrsa, works
35 on OpenSSL and mbedtls backends
39 - NEW: Basic Auth works on ws connections
41 - CHANGE: REMOVED: LWS_WITH_GENRSA, LWS_WITH_GENHASH, LWS_WITH_GENEC,
42 LWS_WITH_GENAES have all been removed and combined into LWS_WITH_GENCRYPTO
44 - CHANGE: REMOVED: LWS_WITH_JWS, LWS_WITH_JWE have been removed and combined
50 - CHANGE: REMOVED: lws_client_connect() and lws_client_connect_extended()
51 compatibility apis for lws_client_connect_via_info() have been marked as
52 deprecated for several versions and are now removed. Use
53 lws_client_connect_via_info() directly instead.
56 - LWS_WITH_HTTP2: now defaults ON
58 - CHANGE: Minimal examples updated to use Content Security Policy best
60 `LWS_SERVER_OPTION_HTTP_HEADERS_SECURITY_BEST_PRACTICES_ENFORCE` vhost
61 option flag and disabling of inline style and scripts. A side-effect of
62 this is that buffers used to marshal headers have to be prepared to take
63 more content than previously... LWS_RECOMMENDED_MIN_HEADER_SPACE (2048
64 currently) is available for user (and internal) use to logically tie the
65 buffer size to this usecase (and follow future increases).
68 - LWS_FOR_GITOHASHI: sets various cmake options suitable for gitohashi
69 - LWS_WITH_ASAN: for Linux, enable build with ASAN
71 Don't forget LWS_WITH_DISTRO_RECOMMENDED, which enables a wide range of lws
72 options suitable for a distro build of the library.
74 - NEW: lws threadpool - lightweight pool of pthreads integrated to lws wsi, with
75 all synchronization to event loop handled internally, queue for excess tasks
76 [threadpool docs](https://libwebsockets.org/git/libwebsockets/tree/lib/misc/threadpool)
77 [threadpool minimal example](https://libwebsockets.org/git/libwebsockets/tree/minimal-examples/ws-server/minimal-ws-server-threadpool)
78 Cmake config: `-DLWS_WITH_THREADPOOL=1`
80 - NEW: libdbus support integrated on lws event loop
81 [lws dbus docs](https://libwebsockets.org/git/libwebsockets/tree/lib/roles/dbus)
82 [lws dbus client minimal examples](https://libwebsockets.org/git/libwebsockets/tree/minimal-examples/dbus-client)
83 [lws dbus server minimal examples](https://libwebsockets.org/git/libwebsockets/tree/minimal-examples/dbus-server)
84 Cmake config: `-DLWS_ROLE_DBUS=1`
86 - NEW: lws allocated chunks (lwsac) - helpers for optimized mass allocation of small
87 objects inside a few larger malloc chunks... if you need to allocate a lot of
88 inter-related structs for a limited time, this removes per-struct allocation
89 library overhead completely and removes the need for any destruction handling
90 [lwsac docs](https://libwebsockets.org/git/libwebsockets/tree/lib/misc/lwsac)
91 [lwsac minimal example](https://libwebsockets.org/git/libwebsockets/tree/minimal-examples/api-tests/api-test-lwsac)
92 Cmake Config: `-DLWS_WITH_LWSAC=1`
94 - NEW: lws tokenizer - helper api for robustly tokenizing your own strings without
95 allocating or adding complexity. Configurable by flags for common delimiter
96 sets and comma-separated-lists in the tokenizer. Detects and reports syntax
98 [lws_tokenize docs](https://libwebsockets.org/git/libwebsockets/tree/include/libwebsockets/lws-tokenize.h)
99 [lws_tokenize minimal example / api test](https://libwebsockets.org/git/libwebsockets/tree/minimal-examples/api-tests/api-test-lws_tokenize)
101 - NEW: lws full-text search - optimized trie generation, serialization,
102 autocomplete suggestion generation and instant global search support extensible
103 to huge corpuses of UTF-8 text while remaining super lightweight on resources.
104 [full-text search docs](https://libwebsockets.org/git/libwebsockets/tree/lib/misc/fts)
105 [full-text search minimal example / api test](https://libwebsockets.org/git/libwebsockets/tree/minimal-examples/api-tests/api-test-fts)
106 [demo](https://libwebsockets.org/ftsdemo/)
107 [demo sources](https://libwebsockets.org/git/libwebsockets/tree/plugins/protocol_fulltext_demo.c)
108 Cmake config: `-DLWS_WITH_FTS=1 -DLWS_WITH_LWSAC=1`
110 - NEW: gzip + brotli http server-side compression - h1 and h2 automatic advertising
111 of server compression and application to files with mimetypes "text/*",
112 "application/javascript" and "image/svg.xml".
113 Cmake config: `-DLWS_WITH_HTTP_STREAM_COMPRESSION=1`, `-DLWS_WITH_HTTP_BROTLI=1`
115 - NEW: managed disk cache - API for managing a directory containing cached files
116 with hashed names, and automatic deletion of LRU files once the cache is
118 [lws diskcache docs](https://libwebsockets.org/git/libwebsockets/tree/include/libwebsockets/lws-diskcache.h)
119 Cmake config: `-DLWS_WITH_DISKCACHE=1`
121 - NEW: http reverse proxy - lws mounts support proxying h1 or h2 requests to
122 a local or remote IP, or unix domain socket over h1. This allows microservice
123 type architectures where parts of the common URL space are actually handled
124 by external processes which may be remote or on the same machine.
125 [lws gitohashi serving](https://libwebsockets.org/git/) is handled this way.
126 CMake config: `-DLWS_WITH_HTTP_PROXY=1`
128 - NEW: lws_buflist - internally several types of ad-hoc malloc'd buffer have
129 been replaced by a new, exported api `struct lws_buflist`. This allows
130 multiple buffers to be chained and drawn down in strict FIFO order.
132 - NEW: In the case of h1 upgrade, the connection header is checked to contain
133 "upgrade". The vhost flag LWS_SERVER_OPTION_VHOST_UPG_STRICT_HOST_CHECK
134 also causes the Host: header to be confirmed to match the vhost name and
137 - NEW: If no 404 redirect for `lws_return_http_status()` is specified for the vhost,
138 the status page produced will try to bring in a stylesheet `/error.css`. This allows
139 you to produce styled 404 or other error pages with logos, graphics etc. See
140 https://libwebsockets.org/git/badrepo for an example of what you can do with it.
145 - CHANGE: Clients used to call LWS_CALLBACK_CLOSED same as servers...
146 LWS_CALLBACK_CLIENT_CLOSED has been introduced and is called for clients
149 - CHANGE: LWS_CALLBACK_CLIENT_CONNECTION_ERROR used to only be directed at
150 protocols[0]. However in many cases, the protocol to bind to was provided
151 at client connection info time and the wsi bound accordingly. In those
152 cases, CONNECTION_ERROR is directed at the bound protocol, not protcols[0]
155 - CHANGE: CMAKE: the following cmake defaults have changed with this version:
157 - LWS_WITH_ZIP_FOPS: now defaults OFF
158 - LWS_WITH_RANGES: now defaults OFF
159 - LWS_WITH_ZLIB: now defaults OFF
160 - LWS_WITHOUT_EXTENSIONS: now defaults ON
162 - CHANGE: REMOVED: lws_alloc_vfs_file() (read a file to malloc buffer)
164 - CHANGE: REMOVED: lws_read() (no longer useful outside of lws internals)
166 - CHANGE: REMOVED: ESP8266... ESP32 is now within the same price range and much
169 - CHANGE: soname bump... don't forget to `ldconfig`
171 - NEW: all event libraries support "foreign" loop integration where lws itself
172 if just a temporary user of the loop unrelated to the actual loop lifecycle.
174 See `minimal-http-server-eventlib-foreign` for example code demonstrating
175 this for all the event libraries.
177 Internal loop in lws is also supported and demonstrated by
178 `minimal-http-server-eventlib`.
180 - NEW: ws-over-h2 support. This is a new RFC-on-the-way supported by Chrome
181 and shortly firefox that allows ws connections to be multiplexed back to the
182 server on the same tcp + tls wrapper h2 connection that the html and scripts
183 came in on. This is hugely faster that discrete connections.
185 - NEW: UDP socket adoption and related event callbacks
187 - NEW: Multi-client connection binding, queuing and pipelining support.
189 Lws detects multiple client connections to the same server and port, and
190 optimizes how it handles them according to the server type and provided
191 flags. For http/1.0, all occur with individual parallel connections. For
192 http/1.1, you can enable keepalive pipelining, so the connections occur
193 sequentially on a single network connection. For http/2, they all occur
194 as parallel streams within a single h2 network connection.
196 See minimal-http-client-multi for example code.
198 - NEW: High resolution timer API for wsi, get a callback on your wsi with
199 LWS_CALLBACK_TIMER, set and reset the timer with lws_set_timer_usecs(wsi, us)
200 Actual resolution depends on event backend. Works with all backends, poll,
201 libuv, libevent, and libev.
203 - NEW: Protocols can arrange vhost-protocol instance specific callbacks with
204 second resolution using `lws_timed_callback_vh_protocol()`
206 - NEW: ACME client plugin for self-service TLS certificates
208 - NEW: RFC7517 JSON Web Keys RFC7638 JWK thumbprint, and RFC7515 JSON Web
211 - NEW: lws_cancel_service() now provides a generic way to synchronize events
212 from other threads, which appear as a LWS_CALLBACK_EVENT_WAIT_CANCELLED
213 callback on all protocols. This is compatible with all the event libraries.
215 - NEW: support BSD poll() where changes to the poll wait while waiting are
218 - NEW: Introduce generic hash, hmac and RSA apis that operate the same
219 regardless of OpenSSL or mbedTLS tls backend
221 - NEW: Introduce X509 element query api that works the same regardless of
222 OpenSSL or mbedTLS tls backend
224 - NEW: Introduce over 30 "minimal examples" in ./minimal-examples... these
225 replace most of the old test servers
227 - test-echo -> minimal-ws-server-echo and minimal-ws-client-echo
229 - test-server-libuv / -libevent / -libev ->
230 minimal-https-server-eventlib / -eventlib-foreign / -eventlib-demos
232 - test-server-v2.0 -> folded into all the minimal servers
234 - test-server direct http serving -> minimal-http-server-dynamic
236 The minimal examples allow individual standalone build using their own
237 small CMakeLists.txt.
239 - NEW: lws now detects any back-to-back writes that did not go through the
240 event loop inbetween and reports them. This will flag any possibility of
241 failure rather than wait until the problem happens.
243 - NEW: CMake has LWS_WITH_DISTRO_RECOMMENDED to select features that are
244 appropriate for distros
246 - NEW: Optional vhost URL `error_document_404` if given causes a redirect there
247 instead of serve the default 404 page.
249 - NEW: lws_strncpy() wrapper guarantees NUL in copied string even if it was
252 - NEW: for client connections, local protocol binding name can be separated
253 from the ws subprotocol name if needed, using .local_protocol_name
255 - NEW: Automatic detection of time discontiguities
257 - NEW: Applies TCP_USER_TIMEOUT for Linux tcp keepalive where available
259 - QA: 1600 tests run on each commit in Travis CI, including almost all
260 Autobahn in client and server mode, various h2load tests, h2spec, attack.sh
261 the minimal example selftests and others.
263 - QA: fix small warnings introduced on gcc8.x (eg, Fedora 28)
265 - QA: Add most of -Wextra on gcc (-Wsign-compare, -Wignored-qualifiers,
266 -Wtype-limits, -Wuninitialized)
268 - QA: clean out warnings on windows
270 - QA: pass all 146 h2spec tests now on strict
272 - QA: introduce 35 selftests that operate different minimal examples against
273 each other and confirm the results.
275 - QA: LWS_WITH_MINIMAL_EXAMPLES allows mass build of all relevant minimal-
276 examples with the LWS build, for CI and to make all the example binaries
277 available from the lws build dir ./bin
279 - REFACTOR: the lws source directory layout in ./lib has been radically
280 improved, and there are now README.md files in selected subdirs with extra
281 documentation of interest to people working on lws itself.
283 - REFACTOR: pipelined transactions return to the event loop before starting the
286 - REFACTOR: TLS: replace all TLS library constants with generic LWS ones and
287 adapt all the TLS library code to translate to these common ones.
289 Isolated all the tls-related private stuff in `./lib/tls/private.h`, and all
290 the mbedTLS stuff in `./lib/tls/mbedtls` + openSSL stuff in
293 - REFACTOR: the various kinds of wsi possible with lws have been extracted
294 from the main code and isolated into "roles" in `./lib/roles` which
295 communicate with the core code via an ops struct. Everything related to
296 ah is migrated to the http role.
298 wsi modes are eliminated and replaced by the ops pointer for the role the
299 wsi is performing. Generic states for wsi are available to control the
300 lifecycle using core code.
302 Adding new "roles" is now much easier with the changes and ops struct to
305 - REFACTOR: reduce four different kinds of buffer management in lws into a
306 generic scatter-gather struct lws_buflist.
308 - REFACTOR: close notifications go through event loop
314 - HTTP/2 server support is now mature and usable! LWS_WITH_HTTP2=1 enables it.
315 Uses ALPN to serve HTTP/2, HTTP/1 and ws[s] connections all from the same
316 listen port seamlessly. (Requires ALPN-capable OpenSSL 1.1 or mbedTLS).
318 - LWS_WITH_MBEDTLS=1 at CMake now builds and works against mbedTLS instead of
319 OpenSSL. Most things work identically, although on common targets where
320 OpenSSL has acceleration, mbedTLS is many times slower in operation. However
321 it is a lot smaller codewise.
323 - Generic hash apis introduced that work the same on mbedTLS or OpenSSL backend
325 - LWS_WITH_PEER_LIMITS tracks IPs across all vhosts and allows restrictions on
326 both the number of simultaneous connections and wsi in use for any single IP
328 - lws_ring apis provide a generic single- or multi-tail ringbuffer... mirror
329 protocol now uses this. Features include ring elements may be sized to fit
330 structs in the ringbuffer, callback when no tail any longer needs an element
331 and it can be deleted, and zerocopy options to write new members directly
332 into the ringbuffer, and use the ringbuffer element by address too.
334 - abstract ssh 2 server plugin included, with both plugin and standalone
335 demos provided. You can bind the plugin to a vhost and also serve full-
336 strength ssh from the vhost. IO from the ssh server is controlled by an
337 "ops" struct of callbacks for tx, rx, auth etc.
339 - Many fixes, cleanups, source refactors and other improvements.
345 - ESP32 OpenSSL support for client and server
347 - ESP32 4 x WLAN credential slots may be configured
349 - Libevent event loop support
351 - SOCKS5 proxy support
353 - lws_meta protocol for websocket connection multiplexing
355 - lws_vhost_destroy() added... allows dynamic removal of listening
356 vhosts. Vhosts with shared listen sockets adopt the listen socket
357 automatically if the owner is destroyed.
361 - Improved CGI handling suitable for general CGI scripting, eg, PHP
363 - Convert even the "old style" test servers to use statically included
366 - LWS_WITH_STATS cmake option dumps resource usage and timing information
367 every few seconds to debug log, including latency information about
368 delay from asking for writeable callback to getting it
370 - Large (> 2GB) files may be served
372 - LWS_WITH_HTTP_PROXY Cmake option adds proxying mounts
374 - Workaround for libev build by disabling -Werror on the test app
376 - HTTP2 support disabled since no way to serve websockets on it
384 - A mount can be protected by Basic Auth... in lwsws it looks like this
388 "mountpoint": "/basic-auth",
389 "origin": "file://_lws_ddir_/libwebsockets-test-server/private",
390 "basic-auth": "/var/www/balogins-private"
394 The text file named in `basic-auth` contains user:password information
397 See README.lwsws.md for more information.
399 - RFC7233 RANGES support in lws server... both single and multipart.
400 This allows seeking for multimedia file serving and download resume.
401 It's enabled by default but can be disabled by CMake option.
403 - On Linux, lwsws can reload configuration without dropping ongoing
404 connections, when sent a SIGHUP. The old configuration drops its
405 listen sockets so the new configuration can listen on them.
406 New connections connect to the server instance with the new
407 configuration. When all old connections eventually close, the old
408 instance automatically exits. This is equivalent to
409 `systemctl reload apache`
411 - New `adopt` api allow adoption including SSL negotiation and
412 for raw sockets and file descriptors.
414 - Chunked transfer encoding supported for client and server
416 - Adaptations to allow operations inside OPTEE Secure World
418 - ESP32 initial port - able to do all test server functions. See
421 - Serving gzipped files from inside a ZIP file is supported... this
422 includes directly serving the gzipped content if the client
423 indicated it could accept it (ie, almost all browsers) saving
424 bandwidth and time. For clients that can't accept it, lws
425 automatically decompresses and serves the content in memory-
426 efficient chunks. Only a few hundred bytes of heap are needed
427 to serve any size file from inside the zip. See README.coding.md
429 - RAW file descriptors may now be adopted into the lws event loop,
430 independent of event backend (including poll service).
433 - RAW server socket descriptors may now be enabled on the vhost if
434 the first thing sent on the connection is not a valid http method.
435 The user code can associate these with a specific protocol per
436 vhost, and RAW-specific callbacks appear there for creation, rx,
437 writable and close. See libwebsockets-test-server-v2.0 for an example.
440 - RAW client connections are now possible using the method "RAW".
441 After connection, the socket is associated to the protocol
442 named in the client connection info and RAW-specific callbacks
443 appear there for creation, rx, writable and close.
444 See libwebsockets-test-client (with raw://) for an example.
453 - Support POST arguments, including multipart and file attachment
455 - Move most of lwsws into lws, make the stub CC0
457 - Add loopback test plugin to confirm client ws / http coexistence
459 - Integrate lwsws testing on Appveyor (ie, windows)
461 - Introduce helpers for sql, urlencode and urldecode sanitation
463 - Introduce LWS_CALLBACK_HTTP_BIND_PROTOCOL / DROP_PROTOCOL that
464 are compatible with http:/1.1 pipelining and different plugins
465 owning different parts of the URL space
467 - lwsgs - Generic Sessions plugin supports serverside sessions,
468 cookies, hashed logins, forgot password etc
470 - Added APIs for sending email to SMTP servers
472 - Messageboard example plugin for lwsgs
474 - Automatic PING sending at fixed intervals and close if no response
476 - Change default header limit in ah to 4096 (from 1024)
478 - Add SNI matching for wildcards if no specific wildcard vhost name match
480 - Convert docs to Doxygen
497 - There are only api additions, the api is compatible with v1.7.x. But
498 there is necessarily an soname bump to 8.
500 - If you are using lws client, you mainly need to be aware the option
501 LWS_SERVER_OPTION_DO_SSL_GLOBAL_INIT is needed at context-creation time
504 - If you are using lws for serving, the above is also true but there are
505 many new features to simplify your code (and life). There is a
508 https://libwebsockets.org/lws-2.0-new-features.html
510 but basically the keywords are vhosts, mounts and plugins. You can now
511 do the web serving part from lws without any user callback code at all.
512 See ./test-server/test-server-v2.0.c for an example, it has no user
513 code for ws either since it uses the protocol plugins... that one C file
514 is all that is needed to do the whole test server function.
516 You now have the option to use a small generic ws-capable webserver
517 "lwsws" and write your ws part as a plugin. That eliminates even
518 cut-and-pasting the test server code and offers more configurable
519 features like control over http cacheability in JSON.
525 These are already in 1.7.x series
527 1) MAJOR (Windows-only) fix assert firing
529 2) MAJOR http:/1.1 connections handled by lws_return_http_status() did not
530 get sent a content-length resulting in the link hanging until the peer closed
531 it. attack.sh updated to add a test for this.
533 3) MINOR An error about hdr struct in _lws_ws_related is corrected, it's not
534 known to affect anything until after it was fixed
536 4) MINOR During the close shutdown wait state introduced at v1.7, if something
537 requests callback on writeable for the socket it will busywait until the
540 5) MAJOR Although the test server has done it for a few versions already, it
541 is now required for the user code to explicitly call
543 if (lws_http_transaction_completed(wsi))
546 when it finishes replying to a transaction in http. Previously the library
547 did it for you, but that disallowed large, long transfers with multiple
548 trips around the event loop (and cgi...).
550 6) MAJOR connections on ah waiting list that closed did not get removed from
553 7) MAJOR since we added the ability to hold an ah across http keepalive
554 transactions where more headers had already arrived, we broke the ability
555 to tell if more headers had arrived. Result was if the browser didn't
556 close the keepalive, we retained ah for the lifetime of the keepalive,
559 8) MAJOR windows-only-POLLHUP was not coming
561 9) Client should not send ext hdr if no exts
566 1) MINOR test-server gained some new switches
568 -C <file> use external SSL cert file
569 -K <file> use external SSL key file
570 -A <file> use external SSL CA cert file
572 -u <uid> set effective uid
573 -g <gid> set effective gid
575 together you can use them like this to have the test-server work with the
576 usual purchased SSL certs from an official CA.
578 --ssl -C your.crt -K your.key -A your.cer -u 99 -g 99
580 2) MINOR the OpenSSL magic to setup ECDH cipher usage is implemented in the
581 library, and the ciphers restricted to use ECDH only.
582 Using this, the lws test server can score an A at SSLLABS test
584 3) MINOR STS (SSL always) header is added to the test server if you use --ssl. With
585 that, we score A+ at SSLLABS test
587 4) MINOR daemonize function (disabled at cmake by default) is updated to work
590 5) MINOR example systemd .service file now provided for test server
591 (not installed by default)
593 6) test server html is updated with tabs and a new live server monitoring
594 feature. Input sanitization added to the js.
596 7) client connections attempted when no ah is free no longer fail, they are
597 just deferred until an ah becomes available.
599 8) The test client pays attention to if you give it an http:/ or https://
600 protocol string to its argument in URL format. If so, it stays in http[s]
601 client mode and doesn't upgrade to ws[s], allowing you to do generic http client
602 operations. Receiving transfer-encoding: chunked is supported.
604 9) If you enable -DLWS_WITH_HTTP_PROXY=1 at cmake, the test server has a
605 new URI path http://localhost:7681/proxytest If you visit here, a client
606 connection to http://example.com:80 is spawned, and the results piped on
607 to your original connection.
609 10) Also with LWS_WITH_HTTP_PROXY enabled at cmake, lws wants to link to an
610 additional library, "libhubbub". This allows lws to do html rewriting on the
611 fly, adjusting proxied urls in a lightweight and fast way.
613 11) There's a new context creation flag LWS_SERVER_OPTION_DO_SSL_GLOBAL_INIT,
614 this is included automatically if you give any other SSL-related option flag.
615 If you give no SSL-related option flag, nor this one directly, then even
616 though SSL support may be compiled in, it is never initialized nor used for the
617 whole lifetime of the lws context.
619 Conversely in order to prepare the context to use SSL, even though, eg, you
620 are not listening on SSL but will use SSL client connections later, you must
621 give this flag explicitly to make sure SSL is initialized.
627 1) MINOR APIBREAK There's a new member in struct lws_context_creation_info, ecdh_curve,
628 which lets you set the name of the ECDH curve OpenSSL should use. By
629 default (if you leave ecdh_curve NULL) it will use "prime256v1"
631 2) MINOR NEWAPI It was already possible to adopt a foreign socket that had not
632 been read from using lws_adopt_socket() since v1.7. Now you can adopt a
633 partially-used socket if you don't need SSL, by passing it what you read
634 so it can drain that before reading from the socket.
636 LWS_VISIBLE LWS_EXTERN struct lws *
637 lws_adopt_socket_readbuf(struct lws_context *context, lws_sockfd_type accept_fd,
638 const char *readbuf, size_t len);
640 3) MINOR NEWAPI CGI type "network io" subprocess execution is now possible from
643 LWS_VISIBLE LWS_EXTERN int
644 lws_cgi(struct lws *wsi, char * const *exec_array, int script_uri_path_len,
647 LWS_VISIBLE LWS_EXTERN int
648 lws_cgi_kill(struct lws *wsi);
650 To use it, you must first set the cmake option
652 $ cmake .. -DLWS_WITH_CGI=1
654 See test-server-http.c and test server path
656 http://localhost:7681/cgitest
658 stdin gets http body, you can test it with wget
660 $ echo hello > hello.txt
661 $ wget http://localhost:7681/cgitest --post-file=hello.txt -O- --quiet
665 The test script returns text/html table showing /proc/meminfo. But the cgi
666 support is complete enough to run cgit cgi.
668 4) There is a helper api for forming logging timestamps
671 lwsl_timestamp(int level, char *p, int len)
673 this generates this kind of timestamp for use as logging preamble
675 lwsts[13116]: [2016/01/25 14:52:52:8386] NOTICE: Initial logging level 7
677 5) struct lws_client_connect_info has a new member
681 If it's NULL, then everything happens as before, lws_client_connect_via_info()
682 makes a ws or wss connection to the address given.
684 If you set method to a valid http method like "GET", though, then this method
685 is used and the connection remains in http[s], it's not upgraded to ws[s].
687 So with this, you can perform http[s] client operations as well as ws[s] ones.
689 There are 4 new related callbacks
691 LWS_CALLBACK_ESTABLISHED_CLIENT_HTTP = 44,
692 LWS_CALLBACK_CLOSED_CLIENT_HTTP = 45,
693 LWS_CALLBACK_RECEIVE_CLIENT_HTTP = 46,
694 LWS_CALLBACK_COMPLETED_CLIENT_HTTP = 47,
696 6) struct lws_client_connect_info has a new member
698 const char *parent_wsi
700 if non-NULL, the client wsi is set to be a child of parent_wsi. This ensures
701 if parent_wsi closes, then the client child is closed just before.
703 7) If you're using SSL, there's a new context creation-time option flag
704 LWS_SERVER_OPTION_REDIRECT_HTTP_TO_HTTPS. If you give this, non-ssl
705 connections to the server listen port are accepted and receive a 301
706 redirect to / on the same host and port using https://
708 8) User code may set per-connection extension options now, using a new api
709 "lws_set_extension_option()".
711 This should be called from the ESTABLISHED callback like this
713 lws_set_extension_option(wsi, "permessage-deflate",
714 "rx_buf_size", "12"); /* 1 << 12 */
716 If the extension is not active (missing or not negotiated for the
717 connection, or extensions are disabled on the library) the call is
718 just returns -1. Otherwise the connection's extension has its
719 named option changed.
721 The extension may decide to alter or disallow the change, in the
722 example above permessage-deflate restricts the size of his rx
723 output buffer also considering the protocol's rx_buf_size member.
726 New application lwsws
727 ---------------------
729 A libwebsockets-based general webserver is built by default now, lwsws.
731 It's configured by JSON, by default in
735 which contains global lws context settings like this
748 which contains zero or more files describing vhosts, like this
752 { "name": "warmcat.com",
754 "host-ssl-key": "/etc/pki/tls/private/warmcat.com.key",
755 "host-ssl-cert": "/etc/pki/tls/certs/warmcat.com.crt",
756 "host-ssl-ca": "/etc/pki/tls/certs/warmcat.com.cer",
759 { "home": "file:///var/www/warmcat.com" },
760 { "default": "index.html" }
776 1) There is now a "permessage-deflate" / RFC7692 implementation. It's very
777 similar to "deflate-frame" we have offered for a long while; deflate-frame is
778 now provided as an alias of permessage-deflate.
780 The main differences are that the new permessage-deflate implementation:
782 - properly performs streaming respecting input and output buffer limits. The
783 old deflate-frame implementation could only work on complete deflate input
784 and produce complete inflate output for each frame. The new implementation
785 only mallocs buffers at initialization.
787 - goes around the event loop after each input package is processed allowing
788 interleaved output processing. The RX flow control api can be used to
789 force compressed input processing to match the rate of compressed output
790 processing (test--echo shows an example of how to do this).
792 - when being "deflate-frame" for compatibility he uses the same default zlib
793 settings as the old "deflate-frame", but instead of exponentially increasing
794 malloc allocations until the whole output will fit, he observes the default
795 input and output chunking buffer sizes of "permessage-deflate", that's
796 1024 in and 1024 out at a time.
798 2) deflate-stream has been disabled for many versions (for over a year) and is
799 now removed. Browsers are now standardizing on "permessage-deflate" / RFC7692
801 3) struct lws_extension is simplified, and lws extensions now have a public
802 api (their callback) for use in user code to compose extensions and options
803 the user code wants. lws_get_internal_exts() is deprecated but kept around
804 as a NOP. The changes allow one extension implementation to go by different
805 names and allows the user client code to control option offers per-ext.
807 The test client and server are updated to use the new way. If you use
808 the old way it should still work, but extensions will be disabled until you
811 Extensions are now responsible for allocating and per-instance private struct
812 at instance construction time and freeing it when the instance is destroyed.
813 Not needing to know the size means the extension's struct can be opaque
820 1) The info struct gained three new members
822 - max_http_header_data: 0 for default (1024) or set the maximum amount of known
823 http header payload that lws can deal with. Payload in unknown http
824 headers is dropped silently. If for some reason you need to send huge
825 cookies or other HTTP-level headers, you can now increase this at context-
828 - max_http_header_pool: 0 for default (16) or set the maximum amount of http
829 headers that can be tracked by lws in this context. For the server, if
830 the header pool is completely in use then accepts on the listen socket
831 are disabled until one becomes free. For the client, if you simultaneously
832 have pending connects for more than this number of client connections,
833 additional connects will fail until some of the pending connections timeout
836 - timeout_secs: 0 for default (currently 20s), or set the library's
837 network activity timeout to the given number of seconds
839 HTTP header processing in lws only exists until just after the first main
840 callback after the HTTP handshake... for ws connections that is ESTABLISHED and
841 for HTTP connections the HTTP callback.
843 So these settings are not related to the maximum number of simultaneous
844 connections, but the number of HTTP handshakes that may be expected or ongoing,
845 or have just completed, at one time. The reason it's useful is it changes the
846 memory allocation for header processing to be one-time at context creation
847 instead of every time there is a new connection, and gives you control over
850 Setting max_http_header_pool to 1 is fine it will just queue incoming
851 connections before the accept as necessary, you can still have as many
852 simultaneous post-header connections as you like. Since the http header
853 processing is completed and the allocation released after ESTABLISHED or the
854 HTTP callback, even with a pool of 1 many connections can be handled rapidly.
856 2) There is a new callback that allows the user code to get acccess to the
857 optional close code + aux data that may have been sent by the peer.
859 LWS_CALLBACK_WS_PEER_INITIATED_CLOSE:
860 The peer has sent an unsolicited Close WS packet. @in and
861 @len are the optional close code (first 2 bytes, network
862 order) and the optional additional information which is not
863 defined in the standard, and may be a string or non-human-
865 If you return 0 lws will echo the close and then close the
866 connection. If you return nonzero lws will just close the
869 As usual not handling it does the right thing, if you're not interested in it
872 The test server has "open and close" testing buttons at the bottom, if you
873 open and close that connection, on close it will send a close code 3000 decimal
874 and the string "Bye!" as the aux data.
876 The test server dumb-increment callback handles this callback reason and prints
878 lwsts[15714]: LWS_CALLBACK_WS_PEER_INITIATED_CLOSE: len 6
879 lwsts[15714]: 0: 0x0B
880 lwsts[15714]: 1: 0xB8
881 lwsts[15714]: 2: 0x42
882 lwsts[15714]: 3: 0x79
883 lwsts[15714]: 4: 0x65
884 lwsts[15714]: 5: 0x21
886 3) There is a new API to allow the user code to control the content of the
887 close frame sent when about to return nonzero from the user callback to
888 indicate the connection should close.
891 * lws_close_reason - Set reason and aux data to send with Close packet
892 * If you are going to return nonzero from the callback
893 * requesting the connection to close, you can optionally
894 * call this to set the reason the peer will be told if
897 * @wsi: The websocket connection to set the close reason on
898 * @status: A valid close status from websocket standard
899 * @buf: NULL or buffer containing up to 124 bytes of auxiliary data
900 * @len: Length of data in @buf to send
902 LWS_VISIBLE LWS_EXTERN void
903 lws_close_reason(struct lws *wsi, enum lws_close_status status,
904 unsigned char *buf, size_t len);
906 An extra button is added to the "open and close" test server page that requests
907 that the test server close the connection from his end.
909 The test server code will do so by
911 lws_close_reason(wsi, LWS_CLOSE_STATUS_GOINGAWAY,
912 (unsigned char *)"seeya", 5);
915 The browser shows the close code and reason he received
917 websocket connection CLOSED, code: 1001, reason: seeya
919 4) There's a new context creation time option flag
921 LWS_SERVER_OPTION_VALIDATE_UTF8
923 if you set it in info->options, then TEXT and CLOSE frames will get checked to
924 confirm that they contain valid UTF-8. If they don't, the connection will get
927 5) ECDH Certs are now supported. Enable the CMake option
929 cmake .. -DLWS_SSL_SERVER_WITH_ECDH_CERT=1
931 **and** the info->options flag
933 LWS_SERVER_OPTION_SSL_ECDH
935 to build in support and select it at runtime.
937 6) There's a new api lws_parse_uri() that simplifies chopping up
938 https://xxx:yyy/zzz uris into parts nicely. The test client now uses this
939 to allow proper uris as well as the old address style.
941 7) SMP support is integrated into LWS without any internal threading. It's
942 very simple to use, libwebsockets-test-server-pthread shows how to do it,
943 use -j <n> argument there to control the number of service threads up to 32.
945 Two new members are added to the info struct
947 unsigned int count_threads;
948 unsigned int fd_limit_per_thread;
950 leave them at the default 0 to get the normal singlethreaded service loop.
952 Set count_threads to n to tell lws you will have n simultaneous service threads
953 operating on the context.
955 There is still a single listen socket on one port, no matter how many
958 When a connection is made, it is accepted by the service thread with the least
959 connections active to perform load balancing.
961 The user code is responsible for spawning n threads running the service loop
962 associated to a specific tsi (Thread Service Index, 0 .. n - 1). See
963 the libwebsockets-test-server-pthread for how to do.
965 If you leave fd_limit_per_thread at 0, then the process limit of fds is shared
966 between the service threads; if you process was allowed 1024 fds overall then
967 each thread is limited to 1024 / n.
969 You can set fd_limit_per_thread to a nonzero number to control this manually, eg
970 the overall supported fd limit is less than the process allowance.
972 You can control the context basic data allocation for multithreading from Cmake
973 using -DLWS_MAX_SMP=, if not given it's set to 32. The serv_buf allocation
974 for the threads (currently 4096) is made at runtime only for active threads.
976 Because lws will limit the requested number of actual threads supported
977 according to LWS_MAX_SMP, there is an api lws_get_count_threads(context) to
978 discover how many threads were actually allowed when the context was created.
980 It's required to implement locking in the user code in the same way that
981 libwebsockets-test-server-pthread does it, for the FD locking callbacks.
983 If LWS_MAX_SMP=1, then there is no code related to pthreads compiled in the
984 library. If more than 1, a small amount of pthread mutex code is built into
989 LWS_VISIBLE struct lws *
990 lws_adopt_socket(struct lws_context *context, lws_sockfd_type accept_fd)
992 allows foreign sockets accepted by non-lws code to be adopted by lws as if they
993 had just been accepted by lws' own listen socket.
995 9) X-Real-IP: header has been added as WSI_TOKEN_HTTP_X_REAL_IP
997 10) Libuv support is added, there are new related user apis
999 typedef void (lws_uv_signal_cb_t)(uv_loop_t *l, uv_signal_t *w, int revents);
1001 LWS_VISIBLE LWS_EXTERN int
1002 lws_uv_sigint_cfg(struct lws_context *context, int use_uv_sigint,
1003 lws_uv_signal_cb_t *cb);
1005 LWS_VISIBLE LWS_EXTERN int
1006 lws_uv_initloop(struct lws_context *context, uv_loop_t *loop, int tsi);
1009 lws_uv_sigint_cb(uv_loop_t *loop, uv_signal_t *watcher, int revents);
1019 1) LWS_SEND_BUFFER_POST_PADDING is now 0 and deprecated. You can remove it; if
1020 you still use it, obviously it does nothing. Old binary code with nonzero
1021 LWS_SEND_BUFFER_POST_PADDING is perfectly compatible, the old code just
1022 allocated a buffer bigger than the library is going to use.
1024 The example apps no longer use LWS_SEND_BUFFER_POST_PADDING.
1026 The only path who made use of it was sending with LWS_WRITE_CLOSE --->
1028 2) Because of lws_close_reason() formalizing handling close frames,
1029 LWS_WRITE_CLOSE is removed from libwebsockets.h. It was only of use to send
1030 close frames...close frame content should be managed using lws_close_reason()
1033 3) We check for invalid CLOSE codes and complain about protocol violation in
1034 our close code. But it changes little since we were in the middle of closing
1037 4) zero-length RX frames and zero length TX frames are now allowed.
1039 5) Pings and close used to be limited to 124 bytes, the correct limit is 125
1040 so that is now also allowed.
1042 6) LWS_PRE is provided as a synonym for LWS_SEND_BUFFER_PRE_PADDING, either is
1045 7) There's generic support for RFC7462 style extension options built into the
1046 library now. As a consequence, a field "options" is added to lws_extension.
1047 It can be NULL if there are no options on the extension. Extension internal
1048 info is part of the public abi because extensions may be implemented outside
1051 8) WSI_TOKEN_PROXY enum was accidentally defined to collide with another token
1052 of value 73. That's now corrected and WSI_TOKEN_PROXY moved to his own place at
1055 9) With the addition of libuv support, libev is not the only event loop
1056 library in town and his api names must be elaborated with _ev_
1058 Callback typedef: lws_signal_cb ---> lws_ev_signal_cb_t
1059 lws_sigint_cfg --> lws_ev_sigint_cfg
1060 lws_initloop --> lws_ev_initloop
1061 lws_sigint_cb --> lws_ev_sigint_cb
1063 10) Libev support is made compatible with multithreaded service,
1064 lws_ev_initloop (was lws_initloop) gets an extra argument for the
1065 thread service index (use 0 if you will just have 1 service thread).
1067 LWS_VISIBLE LWS_EXTERN int
1068 lws_ev_initloop(struct lws_context *context, ev_loop_t *loop, int tsi);
1071 (for earlier changelogs, see the tagged releases)