Update documentation

README.md

@@ -1,9 +1,13 @@
 ![CivetWeb](https://raw.github.com/civetweb/civetweb/master/resources/civetweb_64x64.png "CivetWeb") CivetWeb
 =======
 
-**Continuous integration (Travis, Appveyor), coverage check (coveralls) and source code analysis (coverity) are currently in a setup phase**
+Continuous integration for Linux and OSX using ([Travis CI](https://travis-ci.org/civetweb/civetweb)):
 
 [![Travis Build Status](https://travis-ci.org/civetweb/civetweb.svg?branch=master)](https://travis-ci.org/civetweb/civetweb)
+
+
+Note: Continuous integration for Windows ([AppVeyor](https://ci.appveyor.com/project/civetweb/civetweb)), coverage check ([coveralls](https://coveralls.io/github/civetweb/civetweb)) and source code analysis ([Coverity](https://scan.coverity.com/projects/5784)) are currently in a setup phase:
+
 [![Appveyor Build Status](https://ci.appveyor.com/api/projects/status/github/civetweb/civetweb?svg=true)](https://ci.appveyor.com/project/civetweb/civetweb/branch/master)
 [![Coverage Status](https://coveralls.io/repos/github/civetweb/civetweb/badge.svg?branch=master)](https://coveralls.io/github/civetweb/civetweb?branch=master)
 [![Coverity Scan Build Status](https://scan.coverity.com/projects/5784/badge.svg)](https://scan.coverity.com/projects/5784)
@@ -18,6 +22,9 @@ Project mission is to provide easy to use, powerful, C/C++ embeddable web
 server with optional CGI, SSL and Lua support.
 CivetWeb has a MIT license so you can innovate without restrictions.
 
+CivetWeb can be used by developers as a library, to add web server functionality to an existing application.
+It can also be used by end users as a stand-alone web server. It is available as single executable, no installation is required.
+
 
 Where to find the official version?
 -----------------------------------
@@ -38,10 +45,11 @@ https://groups.google.com/d/forum/civetweb
 Quick start documentation
 --------------------------
 
-- [docs/Installing.md](https://github.com/civetweb/civetweb/blob/master/docs/Installing.md) - Install Guide
+- [docs/Installing.md](https://github.com/civetweb/civetweb/blob/master/docs/Installing.md) - Install Guide (for end users using pre-built binaries)
 - [docs/UserManual.md](https://github.com/civetweb/civetweb/blob/master/docs/UserManual.md) - End User Guide
-- [docs/Building.md](https://github.com/civetweb/civetweb/blob/master/docs/Building.md) - Buildiing the Server Quick Start
-- [docs/Embedding.md](https://github.com/civetweb/civetweb/blob/master/docs/Embedding.md) - Embedding Quick Start
+- [docs/Building.md](https://github.com/civetweb/civetweb/blob/master/docs/Building.md) - Building the Server (quick start guide)
+- [docs/Embedding.md](https://github.com/civetweb/civetweb/blob/master/docs/Embedding.md) - Embedding (how to add HTTP support to an existing application)
+- [docs/OpenSSL.md](https://github.com/civetweb/civetweb/blob/master/docs/OpenSSL.md) - Adding HTTPS (SSL/TLS) support using OpenSSL.
 - [RELEASE_NOTES.md](https://github.com/civetweb/civetweb/blob/master/RELEASE_NOTES.md) - Release Notes
 - [LICENSE.md](https://github.com/civetweb/civetweb/blob/master/LICENSE.md) - Copyright License
 
@@ -63,17 +71,19 @@ simplicity by a carefully selected list of features:
 - Works on Windows, Mac, Linux, UNIX, iPhone, Android, Buildroot, and many
   other platforms.
 - Scripting and database support (Lua scipts, Lua Server Pages, CGI + SQLite
-  database).
+  database, Server side javascript).
   This provides a ready to go, powerful web development platform in a one
   single-click executable with **no dependencies**.
-- Support for CGI, HTTPS/SSL, SSI, HTTP digest (MD5) authorization, Websocket,
+- Support for CGI, HTTPS (SSL/TLS), SSI, HTTP digest (MD5) authorization, Websocket,
   WEbDAV.
+- Optional support for authentication using client side X.509 certificates.
 - Resumed download, URL rewrite, file blacklist, IP-based ACL, Windows service.
 - Download speed limit based on client subnet or URI pattern.
 - Simple and clean embedding API.
 - The source is in single file to make things easy.
 - Embedding examples included.
 - HTTP client capable of sending arbitrary HTTP/HTTPS requests.
+- Websocket client functionality available (WS/WSS).
 
 
 ### Optionally included software
@@ -112,17 +122,29 @@ Contributions
 Contributions are welcome provided all contributions carry the MIT license.
 
 DO NOT APPLY fixes copied from Mongoose to this project to prevent GPL tainting.
+Since 2013 CivetWeb and Mongoose are developed independently. By now the code base differs, so patches cannot be safely transfered in either direction.
 
+Some guidelines can be found in [docs/Contribution.md](https://github.com/civetweb/civetweb/blob/master/docs/Contribution.md).
 
-### Author
+### Authors
 
 CivetWeb is based on the Mongoose project.  The original author of Mongoose was
-Sergey Lyubka, however, the license of Mongoose has been changed after writing
-and distributing the original code this project is based on.
+Sergey Lyubka:
+```
+Copyright (c) 2004-2013 Sergey Lyubka
+MIT license
+```
+
+However, on August 16, 2013, the license of Mongoose has been changed
+after writing and distributing the original code this project is based on.
+CivetWeb has been forked from the last MIT version of Mongoose.
+Since 2013, CivetWeb has seen many improvements from various authors.
+```
+Copyright (c) 2013-2016 the CivetWeb developers
+```
+A list of authors can be found in [CREDITS.md](https://github.com/civetweb/civetweb/blob/master/CREDITS.md)
 
 Using the CivetWeb project ensures the MIT licenses terms are applied and
 GPL cannot be imposed on any of this code as long as it is sourced from
 here. This code will remain free with the MIT license protection.
 
-A list of authors can be found in [CREDITS.md](https://github.com/civetweb/civetweb/blob/master/CREDITS.md)
-

docs/Building.md

@@ -1,19 +1,25 @@
-Building Civetweb
+Building CivetWeb
 =========
 
 This guide covers the build instructions for the stand-alone web server.
-See [Embedding.md](https://github.com/civetweb/civetweb/blob/master/docs/Embedding.md) for information on extending an application.
+See [Embedding.md](https://github.com/civetweb/civetweb/blob/master/docs/Embedding.md) for information on extending an existing C or C++ application. A brief overview of the source code files can be found in [Embedding.md](https://github.com/civetweb/civetweb/blob/master/docs/Embedding.md) as well.
 
 #### Where to get the source code?
+
+The latest version can be found at
 https://github.com/civetweb/civetweb
 
+Released versions can be found at
+https://github.com/civetweb/civetweb/releases
+
 
 Building for Windows
 ---------
 
 #### Using Visual Studio
-Open the *VS2012/civetweb.sln* in Visual Studio.
-To include SSL support, you may have to add an extra library for the cryptography support. You might wish to use yaSSL.  However, it is GPL licensed. See [yaSSL.md](https://github.com/civetweb/civetweb/blob/master/docs/yaSSL.md) for more information.
+
+Open the *VS/civetweb.sln* in Visual Studio.
+To include SSL support, you may have to add an extra library for the cryptography support. You might wish to use yaSSL.  However, it is GPL licensed or uses a commercial license. See [yaSSL.md](https://github.com/civetweb/civetweb/blob/master/docs/yaSSL.md) for more information.
 Alternatively, you might wish to use OpenSSL. See [OpenSSL.md](https://github.com/civetweb/civetweb/blob/master/docs/OpenSSL.md) for more information.
 
 #### Using MinGW-w64 or TDM-GCC
@@ -27,7 +33,7 @@ mingw32-make CC=gcc
 Open the Qt Designer project in the Qt folder
 
 #### Using CMake
-Except for Lua and Duktape support, CivetWeb can also be built with CMake.
+Except for the components in the `third_party` folder (e.g., Lua and Duktape), CivetWeb can also be built with CMake.
 CMake can be used for all supported operating systems.
 
 
@@ -39,7 +45,7 @@ Building for Linux, BSD, and OSX
 ```
 make help
 ```
-Get help
+Get a list of all supported make option
 
 ```
 make build
@@ -66,7 +72,7 @@ building the static library or the server will result in a link error.
 ```
 make clean
 ```
-Clean up the mess
+Clean up files generated during the build
 
 ## Setting build options
 

docs/Contribution.md

@@ -1,10 +1,10 @@
-Contributing to CivetWeb (**Draft**)
+Contributing to CivetWeb
 ====
 
-Contributions to CivetWeb are welcome.
+Contributions to CivetWeb are welcome, provided all contributions carry the MIT license.
 
 - Please first create an issue on GitHub or create a thread on the CivetWeb discussion group.
-- If possible, create a pull request on GitHub. Please take care your modifications pass the continuous integration checks. These checks are performed automatically when you create a pull request, but they may take some hours.
+- If possible, create a pull request on GitHub. Please take care your modifications pass the continuous integration checks. These checks are performed automatically when you create a pull request, but it may take some hours until all tests are completed.
 - Alternatively, you can post a patch. However, pull requests are preferred.
-- Contributor names are listed in CREDITS.md, unless you don't want your name to be listed there.
+- Contributor names are listed in CREDITS.md, unless you explicitly state you don't want your name to be listed there.
 

docs/Embedding.md

@@ -3,8 +3,7 @@ Embedding CivetWeb
 
 CivetWeb is primarily designed so applications can easily add HTTP and HTTPS server as well as WebSocket functionality.  For example, an application server could use CivetWeb to enable a web service interface for automation or remote control.
 
-However, it can also be used as a stand-alone executable. It can deliver static files and offers built-in server side Lua, JavaScript and CGI support.
-
+However, it can also be used as a stand-alone executable. It can deliver static files and offers built-in server side Lua, JavaScript and CGI support. Some instructions how to build the stand-alone server can be found in [Building.md](https://github.com/civetweb/civetweb/blob/master/docs/Building.md).
 
 Files
 ------
@@ -20,16 +19,22 @@ The *INL* file extension represents code that is statically included inline in a
 These files constitute the CivetWeb library.  They do not contain a `main` function,
 but all functions required to run a HTTP server.
 
-  - HTTP Server API
-      - include/civetweb.h
+  - HTTP server API
+    - include/civetweb.h
   - C implementation
     - src/civetweb.c
-    - src/md5.inl (MD5 calculation)    
-  - Optional: C++ Wrapper
+    - src/md5.inl (MD5 calculation)
+    - src/handle_form.inl (HTML form handling functions)
+  - Optional: C++ wrapper
     - include/CivetServer.h (C++ interface)
     - src/CivetServer.cpp (C++ wrapper implementation)
-    
-#### Executable Source Files
+  - Optional: Third party components
+    - src/third_party/* (third party components, mainly used for the standalone server)
+    - src/mod_*.inl (modules to access third party components from civetweb)
+
+Note: The C++ wrapper uses the official C interface (civetweb.h) and does not add new features to the server. Some features available in the C interface might be missing in the C++ interface.
+
+#### Additional Source Files for Executables
 
 These files can be used to build a server executable. They contain a `main` function
 starting the HTTP server.
@@ -41,6 +46,8 @@ starting the HTTP server.
   - Reference embedded C++ Server
       - examples/embedded_cpp/embedded_cpp.cpp
 
+Note: The "embedded" example is actively maintained, updated, extended and tested. Other examples in the examples/ folder might be outdated and remain there for reference.
+
 Quick Start
 ------
 
@@ -176,7 +183,7 @@ looks something like this:
 Function `consume_socket()` gets a new accepted socket from the CivetWeb socket
 queue, atomically removing it from the queue. If the queue is empty,
 `consume_socket()` blocks and waits until a new socket is placed in the queue
-by the master thread. 
+by the master thread.
 
 `process_new_connection()` actually processes the
 connection, i.e. reads the request, parses it, and performs appropriate action
@@ -188,6 +195,6 @@ listening sockets. `poll()` is used to avoid `FD_SETSIZE` limitation of
 to use hi-performance alternatives like `epoll()` or `kqueue()`. Worker
 threads use blocking IO on accepted sockets for reading and writing data.
 All accepted sockets have `SO_RCVTIMEO` and `SO_SNDTIMEO` socket options set
-(controlled by the `request_timeout_ms` CivetWeb option, 30 seconds default) 
+(controlled by the `request_timeout_ms` CivetWeb option, 30 seconds default)
 which specifies a read/write timeout on client connections.
 

docs/OpenSSL.md

@@ -99,23 +99,23 @@ xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
 </pre>
 
 
-Including a dertificate from a certificate authority
+Including a certificate from a certificate authority
 ----
 
 CivetWeb requires one certificate file in PEM format.
-If you got multiple files from your certificate authority, 
-you need to copy their content together into one file. 
-Make sure the file has one section BEGIN RSA PRIVATE KEY / 
-END RSA PRIVATE KEY, and at least one section 
-BEGIN CERTIFICATE / END CERTIFICATE. 
-In case you received a file with a section 
-BEGIN PRIVATE KEY / END PRIVATE KEY, 
+If you got multiple files from your certificate authority,
+you need to copy their content together into one file.
+Make sure the file has one section BEGIN RSA PRIVATE KEY /
+END RSA PRIVATE KEY, and at least one section
+BEGIN CERTIFICATE / END CERTIFICATE.
+In case you received a file with a section
+BEGIN PRIVATE KEY / END PRIVATE KEY,
 you may get a suitable file by adding the letters RSA manually.
 
-Set the "ssl_certificate" configuration parameter to the 
+Set the "ssl_certificate" configuration parameter to the
 file name (including path) of the resulting *.pem file.
 
-The file must look like the file in the section 
+The file must look like the file in the section
 "Creating a self signed certificate", but it will have several
 BEGIN CERTIFICATE / END CERTIFICATE sections.
 

docs/UserManual.md

@@ -392,6 +392,18 @@ for a full buffer or timeout to occur.
     0    Keep the default: Nagel's algorithm enabled
     1    Disable Nagel's algorithm for all sockets
 
+### static\_file\_max\_age `3600`
+Set the maximum time (in seconds) a cache may store a static files.
+
+This option will set the `Cache-Control: max-age` value for static files.
+Dynamically generated content, i.e., content created by a script or callback,
+must send cache control headers by themselfes.
+
+A value >0 corresponds to a maximum allowed caching time in seconds.
+This value should not exceed one year (RFC 2616, Section 14.21).
+A value of 0 will send "do not cache" headers for all static files.
+For values <0 and values >31622400, the behavior is undefined.
+
 ### decode\_url `yes`
 URL encoded request strings are decoded in the server, unless it is disabled
 by setting this option to `no`.
@@ -441,7 +453,7 @@ TLS1.2 | 4
 
 ### ssl_short_trust `no`
 Enables the use of short lived certificates. This will allow for the certificates
-and keys specified in `ssl_certificate`, `ssl_ca_file` and `ssl_ca_path` to be 
+and keys specified in `ssl_certificate`, `ssl_ca_file` and `ssl_ca_path` to be
 exchanged and reloaded while the server is running.
 
 In an automated environment it is advised to first write the new pem file to

docs/yaSSL.md

@@ -1,23 +1,24 @@
-Adding CyaSSL Support
+Adding wolfSSL (formerly CyaSSL) support
 =====
 
-### Only required for Windows!
-
-In order to support SSL *HTTPS* connections in Civetweb on Windows,
+In order to support SSL *HTTPS* connections in Civetweb,
 you may wish to use the GPLv2 licensed CyaSSL library.  By using this
 library, the resulting binary may have to have the GPL license unless
 you buy a commercial license from [wolfSSL](http://www.yassl.com/).
 
+*Note: The following instructions have not been checked for the most recent versions of CivetWeb and wolfSSL. Some information might be outdated.*
+
+
 Getting Started
 ----
 
-- Download Cayssl at http://www.yassl.com/
+- Download Cayssl at https://www.wolfssl.com (formerly http://www.yassl.com/)
 - Extract the zip file
     - To make this seemless, extract to a directory parallel to with Civetweb is
 
 ### Example Project
 
-If you download to cyaSSL to cyassl-2.7.0 in a directory parallel to with Civetweb, you can open the *VS2012/civetweb_yassl* solution in Visual Studio.
+If you download cyaSSL to cyassl-2.7.0 in a directory parallel to Civetweb, you can open the *VS/civetweb_yassl* solution in Visual Studio.
 
 Build Configuration
 ----

src/civetweb.c

@@ -1195,8 +1195,6 @@ static struct mg_option config_options[] = {
     {"error_pages", CONFIG_TYPE_DIRECTORY, NULL},
     {"tcp_nodelay", CONFIG_TYPE_NUMBER, "0"},
 #if !defined(NO_CACHING)
-    /* The name of this config option might change (until it is documented). */
-    /* TODO: Document this option. */
     {"static_file_max_age", CONFIG_TYPE_NUMBER, "3600"},
 #endif
 
@@ -2260,6 +2258,11 @@ send_static_cache_header(struct mg_connection *conn)
 	/* Use "Cache-Control: max-age" instead of "Expires" header.
 	 * Reason: see https://www.mnot.net/blog/2007/05/15/expires_max-age */
 	/* See also https://www.mnot.net/cache_docs/ */
+    /* According to RFC 2616, Section 14.21, caching times should not exceed
+     * one year. A year with 365 days corresponds to 31536000 seconds, a leap
+     * year to 31622400 seconds. For the moment, we just send whatever has
+     * been configured, still the behavior for >1 year should be considered
+     * as undefined. */.
 	return mg_printf(conn, "Cache-Control: max-age=%u\r\n", (unsigned)max_age);
 #else  /* NO_CACHING */
 	return send_no_cache_header(conn);