Changelog
---------
-(since v1.23)
+v2.3.0
+======
-User api additions
-------------------
+ - ESP32 OpenSSL support for client and server
-POST method is supported
+ - ESP32 4 x WLAN credential slots may be configured
-The protocol 0 / HTTP callback can now get two new kinds of callback,
-LWS_CALLBACK_HTTP_BODY (in and len are a chunk of the body of the HTTP request)
-and LWS_CALLBACK_HTTP_BODY_COMPLETION (the expected amount of body has arrived
-and been passed to the user code already). These callbacks are used with the
-post method (see the test server for details).
+ - Libevent event loop support
-The period between the HTTP header completion and the completion of the body
-processing is protected by a 5s timeout.
+ - SOCKS5 proxy support
-The chunks are stored in a malloc'd buffer of size protocols[0].rx_buffer_size.
+ - lws_meta protocol for websocket connection multiplexing
+ - lws_vhost_destroy() added... allows dynamic removal of listening
+ vhosts. Vhosts with shared listen sockets adopt the listen socket
+ automatically if the owner is destroyed.
-New server option you can enable from user code
-LWS_SERVER_OPTION_ALLOW_NON_SSL_ON_SSL_PORT allows non-SSL connections to
-also be accepted on an SSL listening port. It's disabled unless you enable
-it explicitly.
+ - IPv6 on Windows
+ - Improved CGI handling suitable for general CGI scripting, eg, PHP
-Two new callbacks are added in protocols[0] that are optional for allowing
-limited thread access to libwebsockets, LWS_CALLBACK_LOCK_POLL and
-LWS_CALLBACK_UNLOCK_POLL.
+ - Convert even the "old style" test servers to use statically included
+ plugin sources
-If you use them, they protect internal and external poll list changes, but if
-you want to use external thread access to libwebsocket_callback_on_writable()
-you have to implement your locking here even if you don't use external
-poll support.
+ - LWS_WITH_STATS cmake option dumps resource usage and timing information
+ every few seconds to debug log, including latency information about
+ delay from asking for writeable callback to getting it
-If you will use another thread for this, take a lot of care about managing
-your list of live wsi by doing it from ESTABLISHED and CLOSED callbacks
-(with your own locking).
+ - Large (> 2GB) files may be served
+ - LWS_WITH_HTTP_PROXY Cmake option adds proxying mounts
+ - Workaround for libev build by disabling -Werror on the test app
-User api changes
-----------------
+ - HTTP2 support disabled since no way to serve websockets on it
-Extra optional argument to libwebsockets_serve_http_file() allows injecion
-of HTTP headers into the canned response. Eg, cookies may be added like
-that without getting involved in having to send the header by hand.
-
-A new info member http_proxy_address may be used at context creation time to
-set the http proxy. If non-NULL, it overrides http_proxy environment var.
-
-Cmake supports LWS_SSL_CLIENT_USE_OS_CA_CERTS defaulting to on, which gets
-the client to use the OS CA Roots. If you're worried somebody with the
-ability to forge for force creation of a client cert from the root CA in
-your OS, you should disable this since your selfsigned $0 cert is a lot safer
-then...
-
-
-v1.23-chrome32-firefox24
-========================
-
- Android.mk | 29 +
- CMakeLists.txt | 573 ++++++++----
- COPYING | 503 -----------
- INSTALL | 365 --------
- Makefile.am | 13 -
- README.build | 371 ++------
- README.coding | 63 ++
- autogen.sh | 1578 ---------------------------------
- changelog | 69 ++
- cmake/FindGit.cmake | 163 ++++
- cmake/FindOpenSSLbins.cmake | 15 +-
- cmake/UseRPMTools.cmake | 176 ++++
- config.h.cmake | 25 +-
- configure.ac | 226 -----
- cross-arm-linux-gnueabihf.cmake | 28 +
- lib/Makefile.am | 89 --
- lib/base64-decode.c | 98 +-
- lib/client-handshake.c | 123 ++-
- lib/client-parser.c | 19 +-
- lib/client.c | 145 ++-
- lib/daemonize.c | 4 +-
- lib/extension.c | 2 +-
- lib/getifaddrs.h | 4 +-
- lib/handshake.c | 76 +-
- lib/libwebsockets.c | 491 ++++++----
- lib/libwebsockets.h | 164 ++--
- lib/output.c | 214 ++++-
- lib/parsers.c | 102 +--
- lib/private-libwebsockets.h | 66 +-
- lib/server-handshake.c | 5 +-
- lib/server.c | 29 +-
- lib/sha-1.c | 2 +-
- libwebsockets-api-doc.html | 249 +++---
- libwebsockets.pc.in | 11 -
- libwebsockets.spec | 14 +-
- m4/ignore-me | 2 -
- scripts/FindLibWebSockets.cmake | 33 +
- scripts/kernel-doc | 1 +
- test-server/Makefile.am | 131 ---
- test-server/leaf.jpg | Bin 0 -> 2477518 bytes
- test-server/test-client.c | 78 +-
- test-server/test-echo.c | 33 +-
- test-server/test-fraggle.c | 26 +-
- test-server/test-ping.c | 15 +-
- test-server/test-server.c | 197 +++-
- test-server/test.html | 5 +-
- win32port/win32helpers/gettimeofday.c | 74 +-
- win32port/win32helpers/websock-w32.h | 6 +-
- 48 files changed, 2493 insertions(+), 4212 deletions(-)
+v2.2.0
+======
-User api additions
-------------------
+Major new features
- - You can now call libwebsocket_callback_on_writable() on http connectons,
- and get a LWS_CALLBACK_HTTP_WRITEABLE callback, the same way you can
- regulate writes with a websocket protocol connection.
-
- - A new member in the context creation parameter struct "ssl_cipher_list" is
- added, replacing CIPHERS_LIST_STRING. NULL means use the ssl library
- default list of ciphers.
-
- - Not really an api addition, but libwebsocket_service_fd() will now zero
- the revents field of the pollfd it was called with if it handled the
- descriptor. So you can tell if it is a non-lws fd by checking revents
- after the service call... if it's still nonzero, the descriptor
- belongs to you and you need to take care of it.
-
- - libwebsocket_rx_flow_allow_all_protocol(protocol) will unthrottle all
- connections with the established protocol. It's designed to be
- called from user server code when it sees it can accept more input
- and may have throttled connections using the server rx flow apis
- while it was unable to accept any other input The user server code
- then does not have to try to track while connections it choked, this
- will free up all of them in one call.
-
- - there's a new, optional callback LWS_CALLBACK_CLOSED_HTTP which gets
- called when an HTTP protocol socket closes
-
- - for LWS_CALLBACK_FILTER_PROTOCOL_CONNECTION callback, the user_space alloc
- has already been done before the callback happens. That means we can
- use the user parameter to the callback to contain the user pointer, and
- move the protocol name to the "in" parameter. The docs for this
- callback are also updated to reflect how to check headers in there.
-
- - libwebsocket_client_connect() is now properly nonblocking and async. See
- README.coding and test-client.c for information on the callbacks you
- can rely on controlling the async connection period with.
-
- - if your OS does not support the http_proxy environment variable convention
- (eg, reportedly OSX), you can use a new api libwebsocket_set_proxy()
- to set the proxy details inbetween context creation and the connection
- action. For OSes that support http_proxy, that's used automatically.
+ - A mount can be protected by Basic Auth... in lwsws it looks like this
-User api changes
-----------------
+ ```
+{
+ "mountpoint": "/basic-auth",
+ "origin": "file://_lws_ddir_/libwebsockets-test-server/private",
+ "basic-auth": "/var/www/balogins-private"
+}
+```
- - the external poll callbacks now get the socket descriptor coming from the
- "in" parameter. The user parameter provides the user_space for the
- wsi as it normally does on the other callbacks.
- LWS_CALLBACK_FILTER_NETWORK_CONNECTION also has the socket descriptor
- delivered by @in now instead of @user.
+The text file named in `basic-auth` contains user:password information
+one per line.
- - libwebsocket_write() now returns -1 for error, or the amount of data
- actually accepted for send. Under load, the OS may signal it is
- ready to send new data on the socket, but have only a restricted
- amount of memory to buffer the packet compared to usual.
+See README.lwsws.md for more information.
+ - RFC7233 RANGES support in lws server... both single and multipart.
+ This allows seeking for multimedia file serving and download resume.
+ It's enabled by default but can be disabled by CMake option.
-User api removal
-----------------
+ - On Linux, lwsws can reload configuration without dropping ongoing
+ connections, when sent a SIGHUP. The old configuration drops its
+ listen sockets so the new configuration can listen on them.
+ New connections connect to the server instance with the new
+ configuration. When all old connections eventually close, the old
+ instance automatically exits. This is equivalent to
+ `systemctl reload apache`
- - libwebsocket_ensure_user_space() is removed from the public api, if you
- were using it to get user_space, you need to adapt your code to only
- use user_space inside the user callback.
-
- - CIPHERS_LIST_STRING is removed
-
- - autotools build has been removed. See README.build for info on how to
- use CMake for your platform
-
-
-v1.21-chrome26-firefox18
-========================
-
- - Fixes buffer overflow bug in max frame size handling if you used the
- default protocol buffer size. If you declared rx_buffer_size in your
- protocol, which is recommended anyway, your code was unaffected.
-
-v1.2-chrome26-firefox18
-=======================
-
-Diffstat
---------
-
- .gitignore | 16 +++
- CMakeLists.txt | 544 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
- LICENSE | 526 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
- Makefile.am | 1 +
- README | 20 +++
- README.build | 258 ++++++++++++++++++++++++++++++++-----
- README.coding | 52 ++++++++
- changelog | 136 ++++++++++++++++++++
- cmake/FindOpenSSLbins.cmake | 33 +++++
- config.h.cmake | 173 +++++++++++++++++++++++++
- configure.ac | 22 +++-
- lib/Makefile.am | 20 ++-
- lib/base64-decode.c | 2 +-
- lib/client-handshake.c | 190 +++++++++++-----------------
- lib/client-parser.c | 88 +++++++------
- lib/client.c | 384 ++++++++++++++++++++++++++++++-------------------------
- lib/daemonize.c | 32 +++--
- lib/extension-deflate-frame.c | 58 +++++----
- lib/extension-deflate-stream.c | 19 ++-
- lib/extension-deflate-stream.h | 4 +-
- lib/extension.c | 11 +-
- lib/getifaddrs.c | 315 +++++++++++++++++++++++-----------------------
- lib/getifaddrs.h | 30 ++---
- lib/handshake.c | 124 +++++++++++-------
- lib/libwebsockets.c | 736 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++--------------------------------------
- lib/libwebsockets.h | 237 ++++++++++++++++++++++------------
- lib/output.c | 192 +++++++++++-----------------
- lib/parsers.c | 966 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++----------------------------------------------------------------
- lib/private-libwebsockets.h | 225 +++++++++++++++++++++------------
- lib/server-handshake.c | 82 ++++++------
- lib/server.c | 96 +++++++-------
- libwebsockets-api-doc.html | 189 ++++++++++++++++++----------
- libwebsockets.spec | 17 +--
- test-server/attack.sh | 148 ++++++++++++++++++++++
- test-server/test-client.c | 125 +++++++++---------
- test-server/test-echo.c | 31 +++--
- test-server/test-fraggle.c | 32 ++---
- test-server/test-ping.c | 52 ++++----
- test-server/test-server.c | 129 ++++++++++++-------
- win32port/libwebsocketswin32/libwebsocketswin32.vcxproj | 279 ----------------------------------------
- win32port/libwebsocketswin32/libwebsocketswin32.vcxproj.filters | 23 +++-
- 41 files changed, 4398 insertions(+), 2219 deletions(-)
+ - New `adopt` api allow adoption including SSL negotiation and
+ for raw sockets and file descriptors.
+ - Chunked transfer encoding supported for client and server
-User api additions
+ - Adaptations to allow operations inside OPTEE Secure World
+
+ - ESP32 initial port - able to do all test server functions. See
+ README.build.md
+
+ - Serving gzipped files from inside a ZIP file is supported... this
+ includes directly serving the gzipped content if the client
+ indicated it could accept it (ie, almost all browsers) saving
+ bandwidth and time. For clients that can't accept it, lws
+ automatically decompresses and serves the content in memory-
+ efficient chunks. Only a few hundred bytes of heap are needed
+ to serve any size file from inside the zip. See README.coding.md
+
+ - RAW file descriptors may now be adopted into the lws event loop,
+ independent of event backend (including poll service).
+ See README.coding.md
+
+ - RAW server socket descriptors may now be enabled on the vhost if
+ the first thing sent on the connection is not a valid http method.
+ The user code can associate these with a specific protocol per
+ vhost, and RAW-specific callbacks appear there for creation, rx,
+ writable and close. See libwebsockets-test-server-v2.0 for an example.
+ See README.coding.md
+
+ - RAW client connections are now possible using the method "RAW".
+ After connection, the socket is associated to the protocol
+ named in the client connection info and RAW-specific callbacks
+ appear there for creation, rx, writable and close.
+ See libwebsockets-test-client (with raw://) for an example.
+ See README.coding.md
+
+
+v2.1.0
+======
+
+Major new features
+
+ - Support POST arguments, including multipart and file attachment
+
+ - Move most of lwsws into lws, make the stub CC0
+
+ - Add loopback test plugin to confirm client ws / http coexistence
+
+ - Integrate lwsws testing on Appveyor (ie, windows)
+
+ - Introduce helpers for sql, urlencode and urldecode sanitation
+
+ - Introduce LWS_CALLBACK_HTTP_BIND_PROTOCOL / DROP_PROTOCOL that
+ are compatible with http:/1.1 pipelining and different plugins
+ owning different parts of the URL space
+
+ - lwsgs - Generic Sessions plugin supports serverside sessions,
+ cookies, hashed logins, forgot password etc
+
+ - Added APIs for sending email to SMTP servers
+
+ - Messageboard example plugin for lwsgs
+
+ - Automatic PING sending at fixed intervals and close if no response
+
+ - Change default header limit in ah to 4096 (from 1024)
+
+ - Add SNI matching for wildcards if no specific wildcard vhost name match
+
+ - Convert docs to Doxygen
+
+ - ESP8266 support ^^
+
+Fixes
+-----
+
+See git log v2.0.0..
+
+
+
+v2.0.0
+======
+
+Summary
+-------
+
+ - There are only api additions, the api is compatible with v1.7.x. But
+ there is necessarily an soname bump to 8.
+
+ - If you are using lws client, you mainly need to be aware the option
+ LWS_SERVER_OPTION_DO_SSL_GLOBAL_INIT is needed at context-creation time
+ if you will use SSL.
+
+ - If you are using lws for serving, the above is also true but there are
+ many new features to simplify your code (and life). There is a
+ summany online here
+
+ https://libwebsockets.org/lws-2.0-new-features.html
+
+ but basically the keywords are vhosts, mounts and plugins. You can now
+ do the web serving part from lws without any user callback code at all.
+ See ./test-server/test-server-v2.0.c for an example, it has no user
+ code for ws either since it uses the protocol plugins... that one C file
+ is all that is needed to do the whole test server function.
+
+ You now have the option to use a small generic ws-capable webserver
+ "lwsws" and write your ws part as a plugin. That eliminates even
+ cut-and-pasting the test server code and offers more configurable
+ features like control over http cacheability in JSON.
+
+
+Fixes
+-----
+
+These are already in 1.7.x series
+
+1) MAJOR (Windows-only) fix assert firing
+
+2) MAJOR http:/1.1 connections handled by lws_return_http_status() did not
+get sent a content-length resulting in the link hanging until the peer closed
+it. attack.sh updated to add a test for this.
+
+3) MINOR An error about hdr struct in _lws_ws_related is corrected, it's not
+known to affect anything until after it was fixed
+
+4) MINOR During the close shutdown wait state introduced at v1.7, if something
+requests callback on writeable for the socket it will busywait until the
+socket closes
+
+5) MAJOR Although the test server has done it for a few versions already, it
+is now required for the user code to explicitly call
+
+ if (lws_http_transaction_completed(wsi))
+ return -1;
+
+when it finishes replying to a transaction in http. Previously the library
+did it for you, but that disallowed large, long transfers with multiple
+trips around the event loop (and cgi...).
+
+6) MAJOR connections on ah waiting list that closed did not get removed from
+the waiting list...
+
+7) MAJOR since we added the ability to hold an ah across http keepalive
+transactions where more headers had already arrived, we broke the ability
+to tell if more headers had arrived. Result was if the browser didn't
+close the keepalive, we retained ah for the lifetime of the keepalive,
+using up the pool.
+
+8) MAJOR windows-only-POLLHUP was not coming
+
+9) Client should not send ext hdr if no exts
+
+Changes
+-------
+
+1) MINOR test-server gained some new switches
+
+ -C <file> use external SSL cert file
+ -K <file> use external SSL key file
+ -A <file> use external SSL CA cert file
+
+ -u <uid> set effective uid
+ -g <gid> set effective gid
+
+together you can use them like this to have the test-server work with the
+usual purchased SSL certs from an official CA.
+
+ --ssl -C your.crt -K your.key -A your.cer -u 99 -g 99
+
+2) MINOR the OpenSSL magic to setup ECDH cipher usage is implemented in the
+library, and the ciphers restricted to use ECDH only.
+Using this, the lws test server can score an A at SSLLABS test
+
+3) MINOR STS (SSL always) header is added to the test server if you use --ssl. With
+that, we score A+ at SSLLABS test
+
+4) MINOR daemonize function (disabled at cmake by default) is updated to work
+with systemd
+
+5) MINOR example systemd .service file now provided for test server
+(not installed by default)
+
+6) test server html is updated with tabs and a new live server monitoring
+feature. Input sanitization added to the js.
+
+7) client connections attempted when no ah is free no longer fail, they are
+just deferred until an ah becomes available.
+
+8) The test client pays attention to if you give it an http:/ or https://
+protocol string to its argument in URL format. If so, it stays in http[s]
+client mode and doesn't upgrade to ws[s], allowing you to do generic http client
+operations. Receiving transfer-encoding: chunked is supported.
+
+9) If you enable -DLWS_WITH_HTTP_PROXY=1 at cmake, the test server has a
+new URI path http://localhost:7681/proxytest If you visit here, a client
+connection to http://example.com:80 is spawned, and the results piped on
+to your original connection.
+
+10) Also with LWS_WITH_HTTP_PROXY enabled at cmake, lws wants to link to an
+additional library, "libhubbub". This allows lws to do html rewriting on the
+fly, adjusting proxied urls in a lightweight and fast way.
+
+11) There's a new context creation flag LWS_SERVER_OPTION_DO_SSL_GLOBAL_INIT,
+this is included automatically if you give any other SSL-related option flag.
+If you give no SSL-related option flag, nor this one directly, then even
+though SSL support may be compiled in, it is never initialized nor used for the
+whole lifetime of the lws context.
+
+Conversely in order to prepare the context to use SSL, even though, eg, you
+are not listening on SSL but will use SSL client connections later, you must
+give this flag explicitly to make sure SSL is initialized.
+
+
+User API additions
------------------
- - lws_get_library_version() returns a const char * with a string like
- "1.1 9e7f737", representing the library version from configure.ac
- and the git HEAD hash the library was built from
-
- - TCP Keepalive can now optionally be applied to all lws sockets, on Linux
- also with controllable timeout, number of probes and probe interval.
- (On BSD type OS, you can only use system default settings for the
- timing and retries, although enabling it is supported by setting
- ka_time to nonzero, the exact value has no meaning.)
- This enables detection of idle connections which are logically okay,
- but are in fact dead, due to network connectivity issues at the server,
- client, or any intermediary. By default it's not enabled, but you
- can enable it by setting a non-zero timeout (in seconds) at the new
- ka_time member at context creation time.
-
- - Two new optional user callbacks added, LWS_CALLBACK_PROTOCOL_DESTROY which
- is called one-time per protocol as the context is being destroyed, and
- LWS_CALLBACK_PROTOCOL_INIT which is called when the context is created
- and the protocols are added, again it's a one-time affair.
- This lets you manage per-protocol allocations properly including
- cleaning up after yourself when the server goes down.
+1) MINOR APIBREAK There's a new member in struct lws_context_creation_info, ecdh_curve,
+which lets you set the name of the ECDH curve OpenSSL should use. By
+default (if you leave ecdh_curve NULL) it will use "prime256v1"
-User api changes
-----------------
+2) MINOR NEWAPI It was already possible to adopt a foreign socket that had not
+been read from using lws_adopt_socket() since v1.7. Now you can adopt a
+partially-used socket if you don't need SSL, by passing it what you read
+so it can drain that before reading from the socket.
+
+LWS_VISIBLE LWS_EXTERN struct lws *
+lws_adopt_socket_readbuf(struct lws_context *context, lws_sockfd_type accept_fd,
+ const char *readbuf, size_t len);
+
+3) MINOR NEWAPI CGI type "network io" subprocess execution is now possible from
+a simple api.
+
+LWS_VISIBLE LWS_EXTERN int
+lws_cgi(struct lws *wsi, char * const *exec_array, int script_uri_path_len,
+ int timeout_secs);
+
+LWS_VISIBLE LWS_EXTERN int
+lws_cgi_kill(struct lws *wsi);
+
+To use it, you must first set the cmake option
+
+$ cmake .. -DLWS_WITH_CGI=1
+
+See test-server-http.c and test server path
- - libwebsocket_create_context() has changed from taking a ton of parameters
- to just taking a pointer to a struct containing the parameters. The
- struct lws_context_creation_info is in libwebsockets.h, the members
- are in the same order as when they were parameters to the call
- previously. The test apps are all updated accordingly so you can
- see example code there.
-
- - Header tokens are now deleted after the websocket connection is
- established. Not just the header data is saved, but the pointer and
- length array is also removed from (union) scope saving several hundred
- bytes per connection once it is established
-
- - struct libwebsocket_protocols has a new member rx_buffer_size, this
- controls rx buffer size per connection of that protocol now. Sources
- for apps built against older versions of the library won't declare
- this in their protocols, defaulting it to 0. Zero buffer is legal,
- it causes a default buffer to be allocated (currently 4096)
-
- If you want to receive only atomic frames in your user callback, you
- should set this to greater than your largest frame size. If a frame
- comes that exceeds that, no error occurs but the callback happens as
- soon as the buffer limit is reached, and again if it is reached again
- or the frame completes. You can detect that has happened by seeing
- there is still frame content pending using
- libwebsockets_remaining_packet_payload()
-
- By correctly setting this, you can save a lot of memory when your
- protocol has small frames (see the test server and client sources).
-
- - LWS_MAX_HEADER_LEN now defaults to 1024 and is the total amount of known
- header payload lws can cope with, that includes the GET URL, origin
- etc. Headers not understood by lws are ignored and their payload
- not included in this.
-
-
-User api removals
+http://localhost:7681/cgitest
+
+stdin gets http body, you can test it with wget
+
+$ echo hello > hello.txt
+$ wget http://localhost:7681/cgitest --post-file=hello.txt -O- --quiet
+lwstest script
+read="hello"
+
+The test script returns text/html table showing /proc/meminfo. But the cgi
+support is complete enough to run cgit cgi.
+
+4) There is a helper api for forming logging timestamps
+
+LWS_VISIBLE int
+lwsl_timestamp(int level, char *p, int len)
+
+this generates this kind of timestamp for use as logging preamble
+
+lwsts[13116]: [2016/01/25 14:52:52:8386] NOTICE: Initial logging level 7
+
+5) struct lws_client_connect_info has a new member
+
+ const char *method
+
+If it's NULL, then everything happens as before, lws_client_connect_via_info()
+makes a ws or wss connection to the address given.
+
+If you set method to a valid http method like "GET", though, then this method
+is used and the connection remains in http[s], it's not upgraded to ws[s].
+
+So with this, you can perform http[s] client operations as well as ws[s] ones.
+
+There are 4 new related callbacks
+
+ LWS_CALLBACK_ESTABLISHED_CLIENT_HTTP = 44,
+ LWS_CALLBACK_CLOSED_CLIENT_HTTP = 45,
+ LWS_CALLBACK_RECEIVE_CLIENT_HTTP = 46,
+ LWS_CALLBACK_COMPLETED_CLIENT_HTTP = 47,
+
+6) struct lws_client_connect_info has a new member
+
+ const char *parent_wsi
+
+if non-NULL, the client wsi is set to be a child of parent_wsi. This ensures
+if parent_wsi closes, then the client child is closed just before.
+
+7) If you're using SSL, there's a new context creation-time option flag
+LWS_SERVER_OPTION_REDIRECT_HTTP_TO_HTTPS. If you give this, non-ssl
+connections to the server listen port are accepted and receive a 301
+redirect to / on the same host and port using https://
+
+8) User code may set per-connection extension options now, using a new api
+"lws_set_extension_option()".
+
+This should be called from the ESTABLISHED callback like this
+
+ lws_set_extension_option(wsi, "permessage-deflate",
+ "rx_buf_size", "12"); /* 1 << 12 */
+
+If the extension is not active (missing or not negotiated for the
+connection, or extensions are disabled on the library) the call is
+just returns -1. Otherwise the connection's extension has its
+named option changed.
+
+The extension may decide to alter or disallow the change, in the
+example above permessage-deflate restricts the size of his rx
+output buffer also considering the protocol's rx_buf_size member.
+
+
+New application lwsws
+---------------------
+
+A libwebsockets-based general webserver is built by default now, lwsws.
+
+It's configured by JSON, by default in
+
+ /etc/lwsws/conf
+
+which contains global lws context settings like this
+
+{
+ "global": {
+ "uid": "99",
+ "gid": "99",
+ "interface": "eth0",
+ "count-threads": "1"
+ }
+}
+
+ /etc/lwsws/conf.d/*
+
+which contains zero or more files describing vhosts, like this
+
+{
+ "vhosts": [
+ { "name": "warmcat.com",
+ "port": "443",
+ "host-ssl-key": "/etc/pki/tls/private/warmcat.com.key",
+ "host-ssl-cert": "/etc/pki/tls/certs/warmcat.com.crt",
+ "host-ssl-ca": "/etc/pki/tls/certs/warmcat.com.cer",
+ "mounts": [
+ { "/": [
+ { "home": "file:///var/www/warmcat.com" },
+ { "default": "index.html" }
+ ]
+ }
+ ]
+ }
+ ]
+}
+
+
+
+v1.7.0
+======
+
+Extension Changes
-----------------
- - The configuration-time option MAX_USER_RX_BUFFER has been replaced by a
- buffer size chosen per-protocol. For compatibility, there's a default
- of 4096 rx buffer, but user code should set the appropriate size for
- the protocol frames.
-
- - LWS_INITIAL_HDR_ALLOC and LWS_ADDITIONAL_HDR_ALLOC are no longer needed
- and have been removed. There's a new header management scheme that
- handles them in a much more compact way.
-
- - libwebsockets_hangup_on_client() is removed. If you want to close the
- connection you must do so from the user callback and by returning
- -1 from there.
-
- - libwebsocket_close_and_free_session() is now private to the library code
- only and not exposed for user code. If you want to close the
- connection, you must do so from the user callback by returning -1
- from there.
-
-
-New features
-------------
-
- - Cmake project file added, aimed initially at Windows support: this replaces
- the visual studio project files that were in the tree until now.
-
- - CyaSSL now supported in place of OpenSSL (--use-cyassl on configure)
-
- - PATH_MAX or MAX_PATH no longer needed
-
- - cutomizable frame rx buffer size by protocol
-
- - optional TCP keepalive so dead peers can be detected, can be enabled at
- context-creation time
-
- - valgrind-clean: no SSL or CyaSSL: completely clean. With OpenSSL, 88 bytes
- lost at OpenSSL library init and symptomless reports of uninitialized
- memory usage... seems to be a known and ignored problem at OpenSSL
-
- - By default debug is enabled and the library is built for -O0 -g to faclitate
- that. Use --disable-debug configure option to build instead with -O4
- and no -g (debug info), obviously providing best performance and
- reduced binary size.
-
- - 1.0 introduced some code to try to not deflate small frames, however this
- seems to break when confronted with a mixture of frames above and
- below the threshold, so it's removed. Veto the compression extension
- in your user callback if you will typically have very small frames.
-
- - There are many memory usage improvements, both a reduction in malloc/
- realloc and architectural changes. A websocket connection now
- consumes only 296 bytes with SSL or 272 bytes without on x86_64,
- during header processing an additional 1262 bytes is allocated in a
- single malloc, but is freed when the websocket connection starts.
- The RX frame buffer defined by the protocol in user
- code is also allocated per connection, this represents the largest
- frame you can receive atomically in that protocol.
-
- - On ARM9 build, just http+ws server no extensions or ssl, <12Kbytes .text
- and 112 bytes per connection (+1328 only during header processing)
-
-
-v1.1-chrome26-firefox18
-=======================
-
-Diffstat
---------
-
- Makefile.am | 4 +
- README-test-server | 291 ---
- README.build | 239 ++
- README.coding | 138 ++
- README.rst | 72 -
- README.test-apps | 272 +++
- configure.ac | 116 +-
- lib/Makefile.am | 55 +-
- lib/base64-decode.c | 5 +-
- lib/client-handshake.c | 121 +-
- lib/client-parser.c | 394 ++++
- lib/client.c | 807 +++++++
- lib/daemonize.c | 212 ++
- lib/extension-deflate-frame.c | 132 +-
- lib/extension-deflate-stream.c | 12 +-
- lib/extension-x-google-mux.c | 1223 ----------
- lib/extension-x-google-mux.h | 96 -
- lib/extension.c | 8 -
- lib/getifaddrs.c | 271 +++
- lib/getifaddrs.h | 76 +
- lib/handshake.c | 582 +----
- lib/libwebsockets.c | 2493 ++++++---------------
- lib/libwebsockets.h | 115 +-
- lib/md5.c | 217 --
- lib/minilex.c | 440 ++++
- lib/output.c | 628 ++++++
- lib/parsers.c | 2016 +++++------------
- lib/private-libwebsockets.h | 284 +--
- lib/server-handshake.c | 275 +++
- lib/server.c | 377 ++++
- libwebsockets-api-doc.html | 300 +--
- m4/ignore-me | 2 +
- test-server/Makefile.am | 111 +-
- test-server/libwebsockets.org-logo.png | Bin 0 -> 7029 bytes
- test-server/test-client.c | 45 +-
- test-server/test-echo.c | 330 +++
- test-server/test-fraggle.c | 20 +-
- test-server/test-ping.c | 22 +-
- test-server/test-server-extpoll.c | 554 -----
- test-server/test-server.c | 349 ++-
- test-server/test.html | 3 +-
- win32port/zlib/ZLib.vcxproj | 749 ++++---
- win32port/zlib/ZLib.vcxproj.filters | 188 +-
- win32port/zlib/adler32.c | 348 ++-
- win32port/zlib/compress.c | 160 +-
- win32port/zlib/crc32.c | 867 ++++----
- win32port/zlib/crc32.h | 882 ++++----
- win32port/zlib/deflate.c | 3799 +++++++++++++++-----------------
- win32port/zlib/deflate.h | 688 +++---
- win32port/zlib/gzclose.c | 50 +-
- win32port/zlib/gzguts.h | 325 ++-
- win32port/zlib/gzlib.c | 1157 +++++-----
- win32port/zlib/gzread.c | 1242 ++++++-----
- win32port/zlib/gzwrite.c | 1096 +++++----
- win32port/zlib/infback.c | 1272 ++++++-----
- win32port/zlib/inffast.c | 680 +++---
- win32port/zlib/inffast.h | 22 +-
- win32port/zlib/inffixed.h | 188 +-
- win32port/zlib/inflate.c | 2976 +++++++++++++------------
- win32port/zlib/inflate.h | 244 +-
- win32port/zlib/inftrees.c | 636 +++---
- win32port/zlib/inftrees.h | 124 +-
- win32port/zlib/trees.c | 2468 +++++++++++----------
- win32port/zlib/trees.h | 256 +--
- win32port/zlib/uncompr.c | 118 +-
- win32port/zlib/zconf.h | 934 ++++----
- win32port/zlib/zlib.h | 3357 ++++++++++++++--------------
- win32port/zlib/zutil.c | 642 +++---
- win32port/zlib/zutil.h | 526 ++---
- 69 files changed, 19556 insertions(+), 20145 deletions(-)
-
-user api changes
-----------------
+1) There is now a "permessage-deflate" / RFC7692 implementation. It's very
+similar to "deflate-frame" we have offered for a long while; deflate-frame is
+now provided as an alias of permessage-deflate.
+
+The main differences are that the new permessage-deflate implementation:
+
+ - properly performs streaming respecting input and output buffer limits. The
+ old deflate-frame implementation could only work on complete deflate input
+ and produce complete inflate output for each frame. The new implementation
+ only mallocs buffers at initialization.
+
+ - goes around the event loop after each input package is processed allowing
+ interleaved output processing. The RX flow control api can be used to
+ force compressed input processing to match the rate of compressed output
+ processing (test--echo shows an example of how to do this).
+
+ - when being "deflate-frame" for compatibility he uses the same default zlib
+ settings as the old "deflate-frame", but instead of exponentially increasing
+ malloc allocations until the whole output will fit, he observes the default
+ input and output chunking buffer sizes of "permessage-deflate", that's
+ 1024 in and 1024 out at a time.
- - libwebsockets_serve_http_file() now takes a context as first argument
+2) deflate-stream has been disabled for many versions (for over a year) and is
+now removed. Browsers are now standardizing on "permessage-deflate" / RFC7692
- - libwebsockets_get_peer_addresses() now takes a context and wsi as first
- two arguments
+3) struct lws_extension is simplified, and lws extensions now have a public
+api (their callback) for use in user code to compose extensions and options
+the user code wants. lws_get_internal_exts() is deprecated but kept around
+as a NOP. The changes allow one extension implementation to go by different
+names and allows the user client code to control option offers per-ext.
+The test client and server are updated to use the new way. If you use
+the old way it should still work, but extensions will be disabled until you
+update your code.
-user api additions
+Extensions are now responsible for allocating and per-instance private struct
+at instance construction time and freeing it when the instance is destroyed.
+Not needing to know the size means the extension's struct can be opaque
+to user code.
+
+
+User api additions
------------------
- - lwsl_...() logging apis, default to stderr but retargetable by user code;
- may be used also by user code
+1) The info struct gained three new members
+
+ - max_http_header_data: 0 for default (1024) or set the maximum amount of known
+ http header payload that lws can deal with. Payload in unknown http
+ headers is dropped silently. If for some reason you need to send huge
+ cookies or other HTTP-level headers, you can now increase this at context-
+ creation time.
+
+ - max_http_header_pool: 0 for default (16) or set the maximum amount of http
+ headers that can be tracked by lws in this context. For the server, if
+ the header pool is completely in use then accepts on the listen socket
+ are disabled until one becomes free. For the client, if you simultaneously
+ have pending connects for more than this number of client connections,
+ additional connects will fail until some of the pending connections timeout
+ or complete.
+
+ - timeout_secs: 0 for default (currently 20s), or set the library's
+ network activity timeout to the given number of seconds
+
+HTTP header processing in lws only exists until just after the first main
+callback after the HTTP handshake... for ws connections that is ESTABLISHED and
+for HTTP connections the HTTP callback.
+
+So these settings are not related to the maximum number of simultaneous
+connections, but the number of HTTP handshakes that may be expected or ongoing,
+or have just completed, at one time. The reason it's useful is it changes the
+memory allocation for header processing to be one-time at context creation
+instead of every time there is a new connection, and gives you control over
+the peak allocation.
- - lws_set_log_level() set which logging apis are able to emit (defaults to
- notice, warn, err severities), optionally set the emit callback
+Setting max_http_header_pool to 1 is fine it will just queue incoming
+connections before the accept as necessary, you can still have as many
+simultaneous post-header connections as you like. Since the http header
+processing is completed and the allocation released after ESTABLISHED or the
+HTTP callback, even with a pool of 1 many connections can be handled rapidly.
- - lwsl_emit_syslog() helper callback emits to syslog
+2) There is a new callback that allows the user code to get acccess to the
+optional close code + aux data that may have been sent by the peer.
- - lws_daemonize() helper code that forks the app into a headless daemon
- properly, maintains a lock file with pid in suitable for sysvinit etc to
- control lifecycle
+LWS_CALLBACK_WS_PEER_INITIATED_CLOSE:
+ The peer has sent an unsolicited Close WS packet. @in and
+ @len are the optional close code (first 2 bytes, network
+ order) and the optional additional information which is not
+ defined in the standard, and may be a string or non-human-
+ readble data.
+ If you return 0 lws will echo the close and then close the
+ connection. If you return nonzero lws will just close the
+ connection.
- - LWS_CALLBACK_HTTP_FILE_COMPLETION callback added since http file
- transfer is now asynchronous (see test server code)
+As usual not handling it does the right thing, if you're not interested in it
+just ignore it.
- - lws_frame_is_binary() from a wsi pointer, let you know if the received
- data was sent in BINARY mode
+The test server has "open and close" testing buttons at the bottom, if you
+open and close that connection, on close it will send a close code 3000 decimal
+and the string "Bye!" as the aux data.
+The test server dumb-increment callback handles this callback reason and prints
-user api removals
------------------
+lwsts[15714]: LWS_CALLBACK_WS_PEER_INITIATED_CLOSE: len 6
+lwsts[15714]: 0: 0x0B
+lwsts[15714]: 1: 0xB8
+lwsts[15714]: 2: 0x42
+lwsts[15714]: 3: 0x79
+lwsts[15714]: 4: 0x65
+lwsts[15714]: 5: 0x21
+
+3) There is a new API to allow the user code to control the content of the
+close frame sent when about to return nonzero from the user callback to
+indicate the connection should close.
+
+/**
+ * lws_close_reason - Set reason and aux data to send with Close packet
+ * If you are going to return nonzero from the callback
+ * requesting the connection to close, you can optionally
+ * call this to set the reason the peer will be told if
+ * possible.
+ *
+ * @wsi: The websocket connection to set the close reason on
+ * @status: A valid close status from websocket standard
+ * @buf: NULL or buffer containing up to 124 bytes of auxiliary data
+ * @len: Length of data in @buf to send
+ */
+LWS_VISIBLE LWS_EXTERN void
+lws_close_reason(struct lws *wsi, enum lws_close_status status,
+ unsigned char *buf, size_t len);
+
+An extra button is added to the "open and close" test server page that requests
+that the test server close the connection from his end.
+
+The test server code will do so by
+
+ lws_close_reason(wsi, LWS_CLOSE_STATUS_GOINGAWAY,
+ (unsigned char *)"seeya", 5);
+ return -1;
+
+The browser shows the close code and reason he received
+
+websocket connection CLOSED, code: 1001, reason: seeya
+
+4) There's a new context creation time option flag
+
+LWS_SERVER_OPTION_VALIDATE_UTF8
+
+if you set it in info->options, then TEXT and CLOSE frames will get checked to
+confirm that they contain valid UTF-8. If they don't, the connection will get
+closed by lws.
+
+5) ECDH Certs are now supported. Enable the CMake option
+
+cmake .. -DLWS_SSL_SERVER_WITH_ECDH_CERT=1
+
+**and** the info->options flag
+
+LWS_SERVER_OPTION_SSL_ECDH
+
+to build in support and select it at runtime.
+
+6) There's a new api lws_parse_uri() that simplifies chopping up
+https://xxx:yyy/zzz uris into parts nicely. The test client now uses this
+to allow proper uris as well as the old address style.
- - libwebsockets_fork_service_loop() - no longer supported (had intractable problems)
- arrange your code to act from the user callback instead from same
- process context as the service loop
+7) SMP support is integrated into LWS without any internal threading. It's
+very simple to use, libwebsockets-test-server-pthread shows how to do it,
+use -j <n> argument there to control the number of service threads up to 32.
- - libwebsockets_broadcast() - use libwebsocket_callback_on_writable[_all_protocol]()
- instead from same process context as the service loop. See the test apps
- for examples.
+Two new members are added to the info struct
- - x-google-mux() removed until someone wants it
+ unsigned int count_threads;
+ unsigned int fd_limit_per_thread;
+
+leave them at the default 0 to get the normal singlethreaded service loop.
- - pre -v13 (ancient) protocol support removed
+Set count_threads to n to tell lws you will have n simultaneous service threads
+operating on the context.
+There is still a single listen socket on one port, no matter how many
+service threads.
-New features
-------------
+When a connection is made, it is accepted by the service thread with the least
+connections active to perform load balancing.
- - echo test server and client compatible with echo.websocket.org added
+The user code is responsible for spawning n threads running the service loop
+associated to a specific tsi (Thread Service Index, 0 .. n - 1). See
+the libwebsockets-test-server-pthread for how to do.
- - many new configure options (see README.build) to reduce footprint of the
- library to what you actually need, eg, --without-client and
- --without-server
+If you leave fd_limit_per_thread at 0, then the process limit of fds is shared
+between the service threads; if you process was allowed 1024 fds overall then
+each thread is limited to 1024 / n.
- - http + websocket server can build to as little as 12K .text for ARM
+You can set fd_limit_per_thread to a nonzero number to control this manually, eg
+the overall supported fd limit is less than the process allowance.
+
+You can control the context basic data allocation for multithreading from Cmake
+using -DLWS_MAX_SMP=, if not given it's set to 32. The serv_buf allocation
+for the threads (currently 4096) is made at runtime only for active threads.
+
+Because lws will limit the requested number of actual threads supported
+according to LWS_MAX_SMP, there is an api lws_get_count_threads(context) to
+discover how many threads were actually allowed when the context was created.
+
+It's required to implement locking in the user code in the same way that
+libwebsockets-test-server-pthread does it, for the FD locking callbacks.
+
+If LWS_MAX_SMP=1, then there is no code related to pthreads compiled in the
+library. If more than 1, a small amount of pthread mutex code is built into
+the library.
+
+8) New API
+
+LWS_VISIBLE struct lws *
+lws_adopt_socket(struct lws_context *context, lws_sockfd_type accept_fd)
+
+allows foreign sockets accepted by non-lws code to be adopted by lws as if they
+had just been accepted by lws' own listen socket.
+
+9) X-Real-IP: header has been added as WSI_TOKEN_HTTP_X_REAL_IP
+
+10) Libuv support is added, there are new related user apis
+
+typedef void (lws_uv_signal_cb_t)(uv_loop_t *l, uv_signal_t *w, int revents);
+
+LWS_VISIBLE LWS_EXTERN int
+lws_uv_sigint_cfg(struct lws_context *context, int use_uv_sigint,
+ lws_uv_signal_cb_t *cb);
+
+LWS_VISIBLE LWS_EXTERN int
+lws_uv_initloop(struct lws_context *context, uv_loop_t *loop, int tsi);
+
+LWS_VISIBLE void
+lws_uv_sigint_cb(uv_loop_t *loop, uv_signal_t *watcher, int revents);
+
+and CMAKE option
+
+LWS_WITH_LIBUV
+
+
+User api changes
+----------------
- - no more MAX_CLIENTS limitation; adapts to support the max number of fds
- allowed to the process by ulimit, defaults to 1024 on Fedora and
- Ubuntu. Use ulimit to control this without needing to configure
- the library. Code here is smaller and faster.
+1) LWS_SEND_BUFFER_POST_PADDING is now 0 and deprecated. You can remove it; if
+you still use it, obviously it does nothing. Old binary code with nonzero
+LWS_SEND_BUFFER_POST_PADDING is perfectly compatible, the old code just
+allocated a buffer bigger than the library is going to use.
- - adaptive ratio of listen socket to connection socket service allows
- good behaviour under Apache ab test load. Tested with thousands
- of simultaneous connections
+The example apps no longer use LWS_SEND_BUFFER_POST_PADDING.
- - reduction in per-connection memory footprint by moving to a union to hold
- mutually-exclusive state for the connection
+The only path who made use of it was sending with LWS_WRITE_CLOSE --->
- - robustness: Out of Memory taken care of for all allocation code now
+2) Because of lws_close_reason() formalizing handling close frames,
+LWS_WRITE_CLOSE is removed from libwebsockets.h. It was only of use to send
+close frames...close frame content should be managed using lws_close_reason()
+now.
- - internal getifaddrs option if your toolchain lacks it (some uclibc)
+3) We check for invalid CLOSE codes and complain about protocol violation in
+our close code. But it changes little since we were in the middle of closing
+anyway.
- - configurable memory limit for deflate operations
+4) zero-length RX frames and zero length TX frames are now allowed.
- - improvements in SSL code nonblocking operation, possible hang solved,
- some SSL operations broken down into pollable states so there is
- no library blocking, timeout coverage for SSL_connect
+5) Pings and close used to be limited to 124 bytes, the correct limit is 125
+so that is now also allowed.
- - extpoll test server merged into single test server source
+6) LWS_PRE is provided as a synonym for LWS_SEND_BUFFER_PRE_PADDING, either is
+valid to use now.
- - robustness: library should deal with all recoverable socket conditions
+7) There's generic support for RFC7462 style extension options built into the
+library now. As a consequence, a field "options" is added to lws_extension.
+It can be NULL if there are no options on the extension. Extension internal
+info is part of the public abi because extensions may be implemented outside
+the library.
- - rx flowcontrol for backpressure notification fixed and implmeneted
- correctly in the test server
+8) WSI_TOKEN_PROXY enum was accidentally defined to collide with another token
+of value 73. That's now corrected and WSI_TOKEN_PROXY moved to his own place at
+77.
- - optimal lexical parser added for header processing; all headers in a
- single 276-byte state table
+9) With the addition of libuv support, libev is not the only event loop
+library in town and his api names must be elaborated with _ev_
- - latency tracking api added (configure --with-latency)
+ Callback typedef: lws_signal_cb ---> lws_ev_signal_cb_t
+ lws_sigint_cfg --> lws_ev_sigint_cfg
+ lws_initloop --> lws_ev_initloop
+ lws_sigint_cb --> lws_ev_sigint_cb
- - Improved in-tree documentation, REAME.build, README.coding,
- README.test-apps, changelog
+10) Libev support is made compatible with multithreaded service,
+lws_ev_initloop (was lws_initloop) gets an extra argument for the
+thread service index (use 0 if you will just have 1 service thread).
- - Many small fixes
+LWS_VISIBLE LWS_EXTERN int
+lws_ev_initloop(struct lws_context *context, ev_loop_t *loop, int tsi);
-v1.0-chrome25-firefox17 (6cd1ea9b005933f)
+(for earlier changelogs, see the tagged releases)
projects / platform / upstream / libwebsockets.git / blobdiff