Inital swag at HTTP handler docs.

We will need to document nng_aio_set_output, and both document
and create an nng_aio_finish() function.

3 files changed, 182 insertions, 1 deletions

diff --git a/docs/libnng.adoc b/docs/libnng.adoc
index 37bc01c8..6ecf406b 100644
--- a/docs/libnng.adoc
+++ b/docs/libnng.adoc
@@ -14,7 +14,7 @@ libnng - nanomsg next generation library
 
 == SYNOPSIS
 
-*cc* ['flags'] 'files' *-lnng* ['libraries']
+*cc* [_flags_] _files_ *-lnng* [_libraries_]
 
 
 == DESCRIPTION
@@ -230,6 +230,41 @@ and connections.
 | <<nng_http_res_set_version#,nng_http_res_set_version(3)>>|set HTTP response protocol version
 |===
 
+==== HTTP Client Functions
+
+These functions are intended for use with HTTP client applications.
+
+|===
+| <<nng_http_client_alloc#,nng_http_client_alloc(3)>>|allocate HTTP client
+| <<nng_http_client_connect#,nng_http_client_connect(3)>>|establish HTTP client connection
+| <<nng_http_client_free#,nng_http_client_free(3)>>|free HTTP client
+| <<nng_http_client_get_tls#,nng_http_client_get_tls(3)>>|get HTTP client TLS configuration
+| <<nng_http_client_set_tls#,nng_http_client_set_tls(3)>>|set HTTP client TLS configuration
+|===
+
+==== HTTP Server Functions
+
+These functions are intended for use with HTTP server applications.
+
+|===
+| <<nng_http_handler_alloc#,nng_http_handler_alloc(3)>>|allocate HTTP server handler
+| <<nng_http_handler_free#,nng_http_handler_free(3)>>|free HTTP server handler
+| <<nng_http_handler_get_data#,nng_http_handler_get_data(3)>>|return extra data for HTTP handler
+| <<nng_http_handler_set_data#,nng_http_handler_set_data(3)>>|set extra data for HTTP handler
+| <<nng_http_handler_set_host#,nng_http_handler_set_host(3)>>|set host for HTTP handler
+| <<nng_http_handler_set_method#,nng_http_handler_set_method(3)>>|set method for HTTP handler
+| <<nng_http_handler_set_tree#,nng_http_handler_set_tree(3)>>|set HTTP handler to match trees
+| <<nng_http_hijack#,nng_http_hijack(3)>>|hijack HTTP server connection
+| <<nng_http_server_add_handler#,nng_http_server_add_handler(3)>>|add HTTP server handler
+| <<nng_http_server_del_handler#,nng_http_server_del_handler(3)>>|delete HTTP server handler
+| <<nng_http_server_get_tls#,nng_http_server_get_tls(3)>>|get HTTP server TLS configuration
+| <<nng_http_server_hold#,nng_http_server_get_tls(3)>>|get and hold HTTP server instance
+| <<nng_http_server_release#,nng_http_server_get_tls(3)>>|release HTTP server instance
+| <<nng_http_server_set_tls#,nng_http_server_set_tls(3)>>|set HTTP server TLS configuration
+| <<nng_http_server_start#,nng_http_server_start(3)>>|start HTTP server
+| <<nng_http_server_stop#,nng_http_server_stop(3)>>|stop HTTP server
+|===
+
 === TLS Configuration Objects
 
 The following functions are used to manipulate transport layer security
diff --git a/docs/nng_http_conn_write_res.adoc b/docs/nng_http_conn_write_res.adoc
index 8f5a407d..31e438b4 100644
--- a/docs/nng_http_conn_write_res.adoc
+++ b/docs/nng_http_conn_write_res.adoc
@@ -37,6 +37,15 @@ the operation is signaled via the _aio_, and the final result may be
 obtained via <<nng_aio_result#,nng_aio_result>>. That result will
 either be zero or an error code.
 
+=== Persistent Connections
+
+By default, for `HTTP/1.1` connections, the connection is kept open, and
+will be reused to receive new requests.
+
+If however the _res_ contains a header of `Connection:` with a value 
+of `Close` (case-insensitive) or the response corresponds to `HTTP/1.0`,
+then the connection is immediately after sending the response.
+
 == RETURN VALUES
 
 None.
diff --git a/docs/nng_http_handler_alloc.adoc b/docs/nng_http_handler_alloc.adoc
new file mode 100644
index 00000000..cde5b052
--- /dev/null
+++ b/docs/nng_http_handler_alloc.adoc
@@ -0,0 +1,137 @@
+= nng_http_handler_alloc(3)
+:doctype: manpage
+:manmanual: nng
+:mansource: nng
+:manvolnum: 3
+:copyright: Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] + \
+            Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV] + \
+            {blank} + \
+            This document is supplied under the terms of the \
+            https://opensource.org/licenses/MIT[MIT License].
+
+== NAME
+
+nng_http_handler_alloc - allocate HTTP server handler
+
+== SYNOPSIS
+
+[source, c]
+-----------
+#include <nng/nng.h>
+
+typedef struct nng_http_handler nng_http_handler;
+
+int nng_http_handler_alloc(nng_http_handler **hp, const char *path,
+    void (*func)(nng_aio *);
+int nng_http_handler_alloc_directory(nng_http_handler **hp, const char *path,
+    const char *dirname);
+int nng_http_handler_alloc_file(nng_http_handler **hp, const char *path,
+    const char *filename);
+int nng_http_handler_alloc_static(nng_http_handler **hp, const char *path,
+    const void *data, size_t size, const char *content_type);
+-----------
+
+
+== DESCRIPTION
+
+The `nng_http_handler_alloc()` family of functions allocate a handler
+which will be used to process requests coming into an HTTP server.
+On success, a pointer to the handler is stored at the located pointed to
+by _hp_.
+
+Every handler has a Request-URI to which it refers, which is determined
+by the _path_ argument. Only the path component of the Request URI is
+considered.
+
+In some cases, a handler may reference a logical tree rather (directory)
+rather than just a single element.
+(See <<nng_http_handler_set_tree#,nng_http_handler_set_tree(3)>>).
+
+=== Custom Handler
+
+The generic (first) form of this creates a handler that uses a user-supplied
+function to process HTTP requests.  This function uses the asynchronous I/O
+framework.  The function takes a pointer to an `nng_aio` structure.  That
+structure will be passed with the following input values (retrieved with
+<<nng_aio_get_input#,nng_aio_get_input(3)>>):
+
+   0: ``nng_http_req *`` __request__:: The client's HTTP request.
+   1: ``nng_http_handler *``__handler__:: Pointer to the handler object.
+   2: ``nng_http_conn *``__conn__:: The underlying HTTP connection.
+
+The handler should create an `nng_http_res *` response (such as via
+<<nng_http_res_alloc#,nng_http_res_alloc(3)>> or
+<<nng_http_res_alloc_error#,nng_http_res_alloc_error(3)>>) and store that
+in as the first output (index 0) with
+<<nng_aio_set_output#,nng_aio_set_output(3)>>.
+
+Alternatively, the handler may send the HTTP response (and any associated
+body data) itself using the connection.  In that case the output at index
+0 of the _aio_ should be NULL.
+
+Finally, using the <<nng_aio_finish#,nng_aio_finish(3)>> function, the
+_aio_ should be completed successfully.  If any non-zero status is returned
+back to the caller instead, then a generic 500 response will be created and
+sent, if possible, and the connection will be closed.
+
+=== Directory Handler
+
+The second member of this family, `nng_http_handler_alloc_directory()`, creates
+a handler configured to serve a directory tree.  The _uri_ is taken as
+the root, and files are served from the directory tree rooted at _path_.
+
+When the client Request-URI resolves to a directory in the filesystem,
+the handler looks first for a file named `index.html` or `index.htm`.  If
+one is found, then that file is returned back to the client.   If no such
+index file exists, then an `NNG_HTTP_STATUS_NOT_FOUND` (404) error is
+sent back to the client.
+
+The `Content-Type` will be set automatically based upon the extension
+of the requsted file name.  If a content type cannot be determined from
+the extension, then `application/octet-stream` is used.
+
+=== File Handler
+
+The third member of this family, `nng_http_handler_alloc_file()`, creates
+a handler to serve up a single file; it does not traverse directories
+or search for `index.html` or `index.htm` files. 
+
+The `Content-Type` will be set automatically based upon the extension
+of the requsted file name.  If a content type cannot be determined from
+the extension, then `application/octet-stream` is used.
+
+=== Static Handler
+
+The fourth member of this family, `nng_http_handler_alloc_static()`, creates
+a handler to serve up fixed content located in program data.  The client is
+sent the _data_, with `Content-Length` of _size_ bytes, and `Content-Type` of
+__content_type__.
+
+== RETURN VALUES
+
+This function returns 0 on success, and non-zero otherwise.
+
+== ERRORS
+
+`NNG_ENOMEM`:: Insufficient free memory exists to allocate a message.
+`NNG_ENOTSUP`:: HTTP support not configured.
+`NNG_EINVAL`:: An invalid _path_ was specified.
+
+== SEE ALSO
+
+<<nng_aio_finish#,nng_aio_finish(3)>>,
+<<nng_aio_get_input#,nng_aio_get_input(3)>>,
+<<nng_aio_set_output#,nng_aio_set_output(3)>>,
+<<nng_http_handler_free#,nng_http_handler_free(3)>>,
+<<nng_http_handler_set_host#,nng_http_handler_set_host(3)>>,
+<<nng_http_handler_set_method#,nng_http_handler_set_method(3)>>,
+<<nng_http_handler_set_tree#,nng_http_handler_set_tree(3)>>,
+<<nng_http_res_alloc#,nng_http_res_alloc(3)>>,
+<<nng_http_res_alloc_error#,nng_http_res_alloc_error(3)>>,
+<<nng_http_server_add_handler#,nng_http_server_add_handler(3)>>,
+<<nng_strerror#,nng_strerror(3)>>,
+<<nng#,nng(7)>>
+
+== COPYRIGHT
+
+{copyright}