Document HTTP server API completely.

19 files changed, 923 insertions, 5 deletions

diff --git a/docs/libnng.adoc b/docs/libnng.adoc
index 6ecf406b..3612b658 100644
--- a/docs/libnng.adoc
+++ b/docs/libnng.adoc
@@ -120,6 +120,7 @@ The following functions are used in the asynchronous model:
 |<<nng_aio_alloc#,nng_aio_alloc(3)>>|allocate asynchronous I/O handle
 |<<nng_aio_cancel#,nng_aio_cancel(3)>>|cancel asynchronous I/O operation
 |<<nng_aio_count#,nng_aio_count(3)>>|return number of bytes transferred
+|<<nng_aio_finish#,nng_aio_finish(3)>>|finish an asynchronous I/O operation
 |<<nng_aio_free#,nng_aio_free(3)>>|free asynchronous I/O handle
 |<<nng_aio_get_input#,nng_aio_get_input(3)>>|return input parameter
 |<<nng_aio_get_msg#,nng_aio_get_msg(3)>>|get message from an asynchronous receive
@@ -128,6 +129,7 @@ The following functions are used in the asynchronous model:
 |<<nng_aio_set_input#,nng_aio_set_input(3)>>|set input parameter
 |<<nng_aio_set_iov#,nng_aio_set_iov(3)>>|set scatter/gather vector
 |<<nng_aio_set_msg#,nng_aio_set_msg(3)>>|set message for an asynchronous send
+|<<nng_aio_set_output#,nng_aio_set_output(3)>>|set output result
 |<<nng_aio_set_timeout#,nng_aio_set_timeout(3)>>|set asynchronous I/O timeout
 |<<nng_aio_stop#,nng_aio_stop(3)>>|stop asynchronous I/O operation
 |<<nng_aio_wait#,nng_aio_wait(3)>>|wait for asynchronous I/O operation
@@ -252,7 +254,7 @@ These functions are intended for use with HTTP server applications.
 | <<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_method#,nng_http_handler_set_method(3)>>|set HTTP handler method
 | <<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
diff --git a/docs/nng_aio_set_input.adoc b/docs/nng_aio_set_input.adoc
index 6e0abefe..a6ffa4a7 100644
--- a/docs/nng_aio_set_input.adoc
+++ b/docs/nng_aio_set_input.adoc
@@ -37,7 +37,7 @@ increase in the future.)
 
 NOTE: If the _index_ does not correspond to a defined input for the operation,
 then this function will have no effect.  Note that attempts to set
-parameters with an index greater than three (3) will simply be ignored.
+parameters with an _index_ greater than three (3) will simply be ignored.
 
 CAUTION: It is an error to call this function while the _aio_ is currently
 in use by an active asynchronous operation.
diff --git a/docs/nng_aio_set_output.adoc b/docs/nng_aio_set_output.adoc
new file mode 100644
index 00000000..0c0c6cb9
--- /dev/null
+++ b/docs/nng_aio_set_output.adoc
@@ -0,0 +1,62 @@
+= nng_aio_set_output(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_aio_set_output - set output result
+
+== SYNOPSIS
+
+[source, c]
+-----------
+#include <nng/nng.h>
+
+void nng_aio_set_output(nng_aio *aio, unsigned int index, void *result);
+-----------
+
+== DESCRIPTION
+
+The `nng_aio_set_output()` function sets the output result at _index_ 
+to _result_ for the asynchronous operation associated with _aio_.
+
+The type and semantics of output results are determined by specific
+operations; the operation must supply appropriate output results when
+the operation completes successfully.
+
+The valid values of _index_ range from zero (0) to three (3), as no operation
+currently defined can return more than four results.  (This limit could
+increase in the future.)
+
+NOTE:  Note that attempts to set results with an _index_ greater than
+three (3) will be ignored.
+
+An output result set with this function may be retrieved later with
+the <<nng_aio_get_output#,nng_aio_get_output(3)>> function.
+
+== RETURN VALUES
+
+None.
+
+== ERRORS
+
+None.
+
+== SEE ALSO
+
+<<nng_aio_alloc#,nng_aio_alloc(3)>>,
+<<nng_aio_finish#,nng_aio_finish(3)>>,
+<<nng_aio_get_output#,nng_aio_get_output(3)>>,
+<<nng_aio_result#,nng_aio_result(3)>>,
+<<nng#,nng(7)>>
+
+== COPYRIGHT
+
+{copyright}
diff --git a/docs/nng_http_handler_alloc.adoc b/docs/nng_http_handler_alloc.adoc
index cde5b052..45ba7aff 100644
--- a/docs/nng_http_handler_alloc.adoc
+++ b/docs/nng_http_handler_alloc.adoc
@@ -41,7 +41,13 @@ 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.
+considered when determining whether the handler should be called.
+
+Additionally each handler has a method it is registered to handle
+(the default is "GET", see
+<<nng_http_handler_set_method#,nng_http_handler_set_method(3)), and
+optionally a 'Host' header it can be matched against (see
+<<nng_http_handler_set_host#,nng_http_handler_set_host(3)).
 
 In some cases, a handler may reference a logical tree rather (directory)
 rather than just a single element.
@@ -113,9 +119,9 @@ 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.
+`NNG_ENOMEM`:: Insufficient free memory exists to allocate a message.
+`NNG_ENOTSUP`:: No support for HTTP in the library.
 
 == SEE ALSO
 
diff --git a/docs/nng_http_handler_free.adoc b/docs/nng_http_handler_free.adoc
new file mode 100644
index 00000000..e86f34f3
--- /dev/null
+++ b/docs/nng_http_handler_free.adoc
@@ -0,0 +1,50 @@
+= nng_http_handler_free(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_free - free HTTP server handler
+
+== SYNOPSIS
+
+[source, c]
+-----------
+#include <nng/nng.h>
+
+void nng_http_handler_free(nng_http_handler *h);
+-----------
+
+
+== DESCRIPTION
+
+The `nng_http_handler_free()` function frees an allocated HTTP server handler.
+
+CAUTION: It is an error to free a handler that is registered with a server.
+Any handlers that are registered with servers are automatically freed
+when the server itself is deallocated.
+
+== RETURN VALUES
+
+None.
+
+== ERRORS
+
+None.
+
+== SEE ALSO
+
+<<nng_http_handler_alloc#,nng_http_handler_alloc(3)>>,
+<<nng_http_server_add_handler#,nng_http_server_add_handler(3)>>,
+<<nng#,nng(7)>>
+
+== COPYRIGHT
+
+{copyright}
diff --git a/docs/nng_http_handler_get_data.adoc b/docs/nng_http_handler_get_data.adoc
new file mode 100644
index 00000000..76437f64
--- /dev/null
+++ b/docs/nng_http_handler_get_data.adoc
@@ -0,0 +1,49 @@
+= nng_http_handler_get_data(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_get_data - return extra data for HTTP handler
+
+== SYNOPSIS
+
+[source, c]
+-----------
+#include <nng/nng.h>
+
+int nng_http_handler_get_data(nng_http_handler *handler, void *data,
+    void (*dtor)(void *));
+-----------
+
+== DESCRIPTION
+
+The `nng_http_handler_get_data()` function returns the data previously
+stored on _handler_ using the function
+<<nng_http_handler_set_data#,nng_http_handler_set_data(3)>>.
+
+== RETURN VALUES
+
+None.
+
+== ERRORS
+
+None.
+
+== SEE ALSO
+
+<<nng_http_handler_alloc#,nng_http_handler_alloc(3)>>,
+<<nng_http_handler_set_data#,nng_http_server_set_data(3)>>,
+<<nng_http_server_add_handler#,nng_http_server_add_handler(3)>>,
+<<nng#,nng(7)>>
+
+== COPYRIGHT
+
+{copyright}
diff --git a/docs/nng_http_handler_set_data.adoc b/docs/nng_http_handler_set_data.adoc
new file mode 100644
index 00000000..6daac924
--- /dev/null
+++ b/docs/nng_http_handler_set_data.adoc
@@ -0,0 +1,55 @@
+= nng_http_handler_set_data(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_get_data - set extra data for HTTP handler
+
+== SYNOPSIS
+
+[source, c]
+-----------
+#include <nng/nng.h>
+
+void *nng_http_handler_get_data(nng_http_handler *handler, void *data,
+    void (*dtor)(void *));
+-----------
+
+== DESCRIPTION
+
+The `nng_http_handler_set_data()` function is used to set an additional
+_data_ for the _handler_.  The stored _data_ can be retrieved later
+in the handler function using
+<<nng_http_handler_get_data#,nng_http_handler_get_data(3)>>.
+
+Additionally, when the handler is deallocated, if _dtor_ is not `NULL`,
+then it will be called with _data_ as its argument.  The intended use of
+this function is deallocate any resources associated with _data_.
+
+== RETURN VALUES
+
+This function returns 0 on success, and non-zero otherwise.
+
+== ERRORS
+
+`NNG_ENOMEM`:: Insufficient free memory to perform the operation.
+`NNG_ENOTSUP`:: No support for HTTP in the library.
+
+== SEE ALSO
+
+<<nng_http_handler_alloc#,nng_http_handler_alloc(3)>>,
+<<nng_http_handler_get_data#,nng_http_server_get_data(3)>>,
+<<nng_http_server_add_handler#,nng_http_server_add_handler(3)>>,
+<<nng#,nng(7)>>
+
+== COPYRIGHT
+
+{copyright}
diff --git a/docs/nng_http_handler_set_host.adoc b/docs/nng_http_handler_set_host.adoc
new file mode 100644
index 00000000..470cbead
--- /dev/null
+++ b/docs/nng_http_handler_set_host.adoc
@@ -0,0 +1,59 @@
+= nng_http_handler_set_host(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_set_host - set host for HTTP handler
+
+== SYNOPSIS
+
+[source, c]
+-----------
+#include <nng/nng.h>
+
+int nng_http_handler_set_host(nng_http_handler *handler, const char *host);
+-----------
+
+== DESCRIPTION
+
+The `nng_http_handler_set_host()` function is used to limit the scope of the
+_handler_ so that it will only be called when the specified _host_ matches
+the value of the `Host:` HTTP header.
+
+TIP: This can be used to create servers with multiple handlers for virtual
+hosting.
+
+The value of the _host_ can include a colon and port, and should match
+exactly the value of the `Host` header sent by the client.  (Canonicaliztion
+of the host name is performed though.)
+
+TIP: As the server framework does not support listening on multiple
+ports, the port number can be elided.  The matching test only considers
+the hostname or IP address, and ignores any trailing port number.
+
+== RETURN VALUES
+
+This function returns 0 on success, and non-zero otherwise.
+
+== ERRORS
+
+`NNG_ENOMEM`:: Insufficient free memory to perform the operation.
+`NNG_ENOTSUP`:: No support for HTTP in the library.
+
+== SEE ALSO
+
+<<nng_http_handler_alloc#,nng_http_handler_alloc(3)>>,
+<<nng_http_server_add_handler#,nng_http_server_add_handler(3)>>,
+<<nng#,nng(7)>>
+
+== COPYRIGHT
+
+{copyright}
diff --git a/docs/nng_http_handler_set_method.adoc b/docs/nng_http_handler_set_method.adoc
new file mode 100644
index 00000000..a993868e
--- /dev/null
+++ b/docs/nng_http_handler_set_method.adoc
@@ -0,0 +1,61 @@
+= nng_http_handler_set_method(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_set_method - set HTTP handler method
+
+== SYNOPSIS
+
+[source, c]
+-----------
+#include <nng/nng.h>
+
+int nng_http_handler_set_method(nng_http_handler *handler, const char *method);
+-----------
+
+== DESCRIPTION
+
+The `nng_http_handler_set_method()` function sets the _method_ that the
+_handler_ will be called for, such as "GET" or "POST".  (By default the
+"GET" method is handled.)  If _method_ is `NULL`, then the request method
+is not examined, and the handler will be executed regardless of the
+method.
+
+NOTE: The server will automatically call "GET" handlers if the client
+sends a "HEAD" request, and will suppress HTTP body data in the responses
+sent for such requests.
+
+NOTE: No validation of the _method_ is performed, but HTTP specifications
+insist that the actual method sent over the wire be capitalized.
+
+The handler may always examine the actual method used using the
+<<nng_http_req_get_method#,nng_http_req_get_method(3)>> function.
+
+== RETURN VALUES
+
+This function returns 0 on success, and non-zero otherwise.
+
+== ERRORS
+
+`NNG_ENOMEM`:: Insufficient free memory exists.
+`NNG_ENOTSUP`:: No support for HTTP in the library.
+
+== SEE ALSO
+
+<<nng_http_handler_alloc#,nng_http_handler_alloc(3)>>,
+<<nng_http_server_add_handler#,nng_http_server_add_handler(3)>>,
+<<nng_http_req_get_method#,nng_http_req_get_method(3)>>,
+<<nng#,nng(7)>>
+
+== COPYRIGHT
+
+{copyright}
diff --git a/docs/nng_http_handler_set_tree.adoc b/docs/nng_http_handler_set_tree.adoc
new file mode 100644
index 00000000..45b998bc
--- /dev/null
+++ b/docs/nng_http_handler_set_tree.adoc
@@ -0,0 +1,52 @@
+= nng_http_handler_set_tree(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_set_tree - set HTTP handler to match trees
+
+== SYNOPSIS
+
+[source, c]
+-----------
+#include <nng/nng.h>
+
+int nng_http_handler_set_tree(nng_http_handler *handler);
+-----------
+
+== DESCRIPTION
+
+The `nng_http_handler_set_tree()` function causes the _handler_ to be
+matched if the Request URI sent by the client is a logical child of
+the path for _handler_.
+
+TIP: This method is useful when constructing API handlers where a single
+service address (path) supports dynamically generated children.
+
+== RETURN VALUES
+
+This function returns 0 on success, and non-zero otherwise.
+
+== ERRORS
+
+`NNG_ENOMEM`:: Insufficient free memory exists.
+`NNG_ENOTSUP`:: No support for HTTP in the library.
+
+== SEE ALSO
+
+<<nng_http_handler_alloc#,nng_http_handler_alloc(3)>>,
+<<nng_http_server_add_handler#,nng_http_server_add_handler(3)>>,
+<<nng_http_req_get_method#,nng_http_req_get_method(3)>>,
+<<nng#,nng(7)>>
+
+== COPYRIGHT
+
+{copyright}
diff --git a/docs/nng_http_hijack.adoc b/docs/nng_http_hijack.adoc
new file mode 100644
index 00000000..39105c1d
--- /dev/null
+++ b/docs/nng_http_hijack.adoc
@@ -0,0 +1,66 @@
+= nng_http_hijack(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_hijack - hijack HTTP server connection
+
+== SYNOPSIS
+
+[source, c]
+-----------
+#include <nng/nng.h>
+
+void nng_http_hijack(nng_http_conn *conn);
+-----------
+
+== DESCRIPTION
+
+The `nng_http_hijack()` function hijacks the connection _conn_, causing it
+to be disassociated from the HTTP server where it was created.
+
+The purpose of this function is the creation of HTTP upgraders (such as
+WebSocket), where the underlying HTTP connection will be taken over for
+some other purpose, and should not be used any further by the server.
+
+This function is most useful when called from a handler function.
+(See <<nng_http_alloc_handler#,nng_http_alloc_handler(3).)
+
+NOTE: It is the responsibility of the caller to dispose of the underlying
+connection when it is no longer needed.  Furthermore, the HTTP server will
+no longer send any responses to the hijacked connection, so the caller should
+do that as well if appropriate.  (See
+<<nng_http_conn_write_res#,nng_http_conn_write_res(3)>>.)
+
+TIP: This function is intended to facilitate uses cases that involve changing
+the protocol from HTTP -- such as WebSocket.  Most applications will never need
+to use this function.
+
+== RETURN VALUES
+
+None.
+
+== ERRORS
+
+`NNG_ECLOSED`:: The connection was closed.
+`NNG_ENOMEM`:: Insufficient free memory exists.
+`NNG_ENOTSUP`:: HTTP not supported.
+
+== SEE ALSO
+
+<<nng_http_alloc_handler#,nng_http_alloc_handler(3)>>,
+<<nng_http_conn_write_res#,nng_http_conn_write_res(3)>>,
+<<nng_strerror#,nng_strerror(3)>>,
+<<nng#,nng(7)>>
+
+== COPYRIGHT
+
+{copyright}
diff --git a/docs/nng_http_server_add_handler.adoc b/docs/nng_http_server_add_handler.adoc
new file mode 100644
index 00000000..64645fbf
--- /dev/null
+++ b/docs/nng_http_server_add_handler.adoc
@@ -0,0 +1,61 @@
+= nng_http_server_add_handler(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_server_add_handler - add HTTP server handler
+
+== SYNOPSIS
+
+[source, c]
+-----------
+#include <nng/nng.h>
+
+int nng_http_server_add_handler(nng_http_server *s, nng_http_handler *h);
+-----------
+
+
+== DESCRIPTION
+
+The `nng_http_server_add_handler()` adds the handler _h_ to the server
+instance _s_.
+
+If another handler is already added to the server that would conflict
+with handler _h_, then the operation will fail with `NNG_EADDRINUSE`.
+
+If a handler is added to a server, and the server is subsequently
+deallocated, the handler and any of its resources will also be deallocated.
+
+Handlers that are added to a server may be subsequently removed using the
+<<nng_http_server_del_handler#,nng_http_server_del_handler(3)>> function.
+
+== RETURN VALUES
+
+This function returns 0 on success, and non-zero otherwise.
+
+== ERRORS
+
+`NNG_EADDRINUSE`:: Handler conflicts with another handler.
+`NNG_ENOMEM`:: Insufficient free memory exists.
+`NNG_ENOTSUP`:: HTTP not supported.
+
+== SEE ALSO
+
+
+<<nng_http_handler_alloc#,nng_http_handler_alloc(3)>>,
+<<nng_http_server_del_handler#,nng_http_server_del_handler(3)>>,
+<<nng_http_server_hold#,nng_http_server_hold(3)>>,
+<<nng_strerror#,nng_strerror(3)>>,
+<<nng#,nng(7)>>
+
+== COPYRIGHT
+
+{copyright}
diff --git a/docs/nng_http_server_del_handler.adoc b/docs/nng_http_server_del_handler.adoc
new file mode 100644
index 00000000..e3b628e8
--- /dev/null
+++ b/docs/nng_http_server_del_handler.adoc
@@ -0,0 +1,52 @@
+= nng_http_server_del_handler(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_server_del_handler - delete HTTP server handler
+
+== SYNOPSIS
+
+[source, c]
+-----------
+#include <nng/nng.h>
+
+int nng_http_server_del_hanlder(nng_http_server *s, nng_http_handler *h);
+-----------
+
+
+== DESCRIPTION
+
+The `nng_http_server_del_handler()` removes the handler _h_ from the server
+instance _s_.
+
+Once a handler has been deleted from a server, it is the responsibility
+of the caller to dispose of the handler, or add it to another server instance.
+
+== RETURN VALUES
+
+This function returns 0 on success, and non-zero otherwise.
+
+== ERRORS
+
+`NNG_ENOENT`:: Handler is not registered with server.
+`NNG_ENOTSUP`:: HTTP not supported.
+
+== SEE ALSO
+
+<<nng_http_handler_free#,nng_http_handler_free(3)>>,
+<<nng_http_server_add_handler#,nng_http_server_add_handler(3)>>,
+<<nng_strerror#,nng_strerror(3)>>,
+<<nng#,nng(7)>>
+
+== COPYRIGHT
+
+{copyright}
diff --git a/docs/nng_http_server_get_tls.adoc b/docs/nng_http_server_get_tls.adoc
new file mode 100644
index 00000000..4bd41207
--- /dev/null
+++ b/docs/nng_http_server_get_tls.adoc
@@ -0,0 +1,54 @@
+= nng_http_server_get_tls(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_server_get_tls - get HTTP server TLS configuration
+
+== SYNOPSIS
+
+[source, c]
+-----------
+#include <nng/nng.h>
+
+int nng_http_server_get_tls(nng_http_server *s, nng_tls_config **cfgp);
+-----------
+
+
+== DESCRIPTION
+
+The `nng_http_server_get_tls()` obtains the TLS configuration of server _s_ and
+saves a pointer to it in the address referenced by _cfgp_.
+
+The configuration will be `NULL` if the HTTP server instance is not enabled
+to use HTTPS.
+
+== RETURN VALUES
+
+This function returns 0 on success, and non-zero otherwise.
+
+== ERRORS
+
+`NNG_ENOMEM`:: Insufficient free memory exists.
+`NNG_ENOTSUP`:: Either HTTP or TLS not supported.
+
+== SEE ALSO
+
+<<nng_http_server_hold#,nng_http_server_hold(3)>>,
+<<nng_http_server_set_tls#,nng_http_server_set_tls(3)>>,
+<<nng_http_server_start#,nng_http_server_start(3)>>,
+<<nng_tls_config_alloc#,nng_tls_config_alloc(3)>>,
+<<nng_strerror#,nng_strerror(3)>>,
+<<nng#,nng(7)>>
+
+== COPYRIGHT
+
+{copyright}
diff --git a/docs/nng_http_server_hold.adoc b/docs/nng_http_server_hold.adoc
new file mode 100644
index 00000000..17e6397f
--- /dev/null
+++ b/docs/nng_http_server_hold.adoc
@@ -0,0 +1,66 @@
+= nng_http_server_hold(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_server_hold - get and hold HTTP server instance
+
+== SYNOPSIS
+
+[source, c]
+-----------
+#include <nng/nng.h>
+
+int nng_http_server_hold(nng_http_server **serverp, const nng_url *url);
+-----------
+
+
+== DESCRIPTION
+
+The `nng_http_server_hold()` acquires an instance of an HTTP server suitable
+for use in serving the URL identified by _url_, and stores a pointer to it
+at the location pointed to by _serverp_.
+
+This function first looks to see if an existing HTTP server instance exists,
+that is suitable for this.  If so, it increments the reference count on it
+and uses that.  Otherwise, it will attempt to create a new server instance
+with an initial reference count of one (1).
+
+The server instance is not started, and can have additional configuration
+applied to it before it is later started with
+<<nng_http_server_start#,nng_http_server_start(3)>>.
+
+NOTE: The URL matching logic in determining servers is unable to distinguish
+between different aliases for the same local IP address.  This may create
+problems when using URLs for virtual hosting.  It is recommended to use
+canonical IP addresses or names in the _url_ to avoid confusion.
+
+== RETURN VALUES
+
+This function returns 0 on success, and non-zero otherwise.
+
+== ERRORS
+
+`NNG_ENOMEM`:: Insufficient free memory exists.
+`NNG_ENOTSUP`:: HTTP not supported.
+
+== SEE ALSO
+
+<<nng_http_server_add_handler#,nng_http_server_add_handler(3)>>,
+<<nng_http_server_release#,nng_http_server_release(3)>>,
+<<nng_http_server_stop#,nng_http_server_stop(3)>>,
+<<nng_url_parse#,nng_url_parse(3)>>
+<<nng_strerror#,nng_strerror(3)>>,
+<<nng#,nng(7)>>
+
+== COPYRIGHT
+
+{copyright}
diff --git a/docs/nng_http_server_release.adoc b/docs/nng_http_server_release.adoc
new file mode 100644
index 00000000..7e293981
--- /dev/null
+++ b/docs/nng_http_server_release.adoc
@@ -0,0 +1,57 @@
+= nng_http_server_release(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_server_release - release HTTP server instance
+
+== SYNOPSIS
+
+[source, c]
+-----------
+#include <nng/nng.h>
+
+void nng_http_server_release(nng_http_server *server);
+-----------
+
+
+== DESCRIPTION
+
+The `nng_http_server_release()` releases an instance of an HTTP _server_
+that was previously held with
+<<nng_http_server_hold#,nng_http_server_hold(3)>>.
+
+This effectively drops the reference count on the server instance.  When
+the reference count drops to zero, then the _server_ and all resources
+associated with it (e.g. HTTP handlers, connections, etc.) are deallocated.
+(If the server is "running" when this occurs, then the server is stopped.)
+
+WARNING: It is an error to release an instance of a server that has
+not previously been held, or to attempt to release an instance more
+times than it has been held.
+
+== RETURN VALUES
+
+None.
+
+== ERRORS
+
+None.
+
+== SEE ALSO
+
+<<nng_http_server_hold#,nng_http_server_hold(3)>>,
+<<nng_http_server_stop#,nng_http_server_stop(3)>>,
+<<nng#,nng(7)>>
+
+== COPYRIGHT
+
+{copyright}
diff --git a/docs/nng_http_server_set_tls.adoc b/docs/nng_http_server_set_tls.adoc
new file mode 100644
index 00000000..5dda35ed
--- /dev/null
+++ b/docs/nng_http_server_set_tls.adoc
@@ -0,0 +1,64 @@
+= nng_http_server_set_tls(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_server_set_tls - set HTTP server TLS configuration
+
+== SYNOPSIS
+
+[source, c]
+-----------
+#include <nng/nng.h>
+
+int nng_http_server_set_tls(nng_http_server *s, nng_tls_config *cfg);
+-----------
+
+
+== DESCRIPTION
+
+The `nng_http_server_set_tls()` sets the TLS configuration of server _s_ to
+instance _s_.
+
+This change overwrites any previous TLS configuration.
+
+WARNING: This also invalidates any previously obtained values from
+<<nng_http_server_get_tls#,nng_http_server_get_tls(3)>>.
+
+If the server is already running (i.e. it has been started with
+<<nng_http_server_start#,nng_http_server_start(3)>>) then this will
+fail with `NNG_EBUSY`.
+
+TIP: Generally, the _cfg_ must have a configured private key, set with
+<<nng_tls_config_own_cert#,nng_tls_config_own_cert(3)>> or similar.
+
+== RETURN VALUES
+
+This function returns 0 on success, and non-zero otherwise.
+
+== ERRORS
+
+`NNG_EBUSY`:: Server instance is running.
+`NNG_ENOMEM`:: Insufficient free memory exists.
+`NNG_ENOTSUP`:: Either HTTP or TLS not supported.
+
+== SEE ALSO
+
+<<nng_http_server_get_tls#,nng_http_server_get_tls(3)>>,
+<<nng_http_server_hold#,nng_http_server_hold(3)>>,
+<<nng_http_server_start#,nng_http_server_start(3)>>,
+<<nng_tls_config_alloc#,nng_tls_config_alloc(3)>>,
+<<nng_strerror#,nng_strerror(3)>>,
+<<nng#,nng(7)>>
+
+== COPYRIGHT
+
+{copyright}
diff --git a/docs/nng_http_server_start.adoc b/docs/nng_http_server_start.adoc
new file mode 100644
index 00000000..7de4cb40
--- /dev/null
+++ b/docs/nng_http_server_start.adoc
@@ -0,0 +1,54 @@
+= nng_http_server_start(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_server_start - start HTTP server
+
+== SYNOPSIS
+
+[source, c]
+-----------
+#include <nng/nng.h>
+
+int nng_http_server_start(nng_http_server *server);
+-----------
+
+
+== DESCRIPTION
+
+The `nng_http_server_start()` starts the HTTP server instance _server_.
+This causes it to bind to the appropriate TCP port, and start accepting
+connections and handling HTTP requests.
+
+== RETURN VALUES
+
+This function returns 0 on success, and non-zero otherwise.
+
+== ERRORS
+
+`NNG_EADDRINUSE`:: The TCP port is unavaialble.
+`NNG_EADDRINVAL`:: The server is configured with an invalid address.
+`NNG_ENOMEM`:: Insufficient free memory exists.
+`NNG_ENOTSUP`:: HTTP not supported.
+
+== SEE ALSO
+
+<<nng_http_server_hold#,nng_http_server_hold(3)>>,
+<<nng_http_server_release#,nng_http_server_release(3)>>,
+<<nng_http_server_stop#,nng_http_server_stop(3)>>,
+<<nng_url_parse#,nng_url_parse(3)>>
+<<nng_strerror#,nng_strerror(3)>>,
+<<nng#,nng(7)>>
+
+== COPYRIGHT
+
+{copyright}
diff --git a/docs/nng_http_server_stop.adoc b/docs/nng_http_server_stop.adoc
new file mode 100644
index 00000000..f2577b2e
--- /dev/null
+++ b/docs/nng_http_server_stop.adoc
@@ -0,0 +1,48 @@
+= nng_http_server_stop(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_server_stop - stop HTTP server
+
+== SYNOPSIS
+
+[source, c]
+-----------
+#include <nng/nng.h>
+
+void nng_http_server_stop(nng_http_server *server);
+-----------
+
+
+== DESCRIPTION
+
+The `nng_http_server_stop()` stops the HTTP server instance _server_.
+This will cause it to close any underlying TCP sockets, and to terminate
+any HTTP connections associated with it.
+
+== RETURN VALUES
+
+None.
+
+== ERRORS
+
+None.
+
+== SEE ALSO
+
+<<nng_http_server_hold#,nng_http_server_hold(3)>>,
+<<nng_http_server_start#,nng_http_server_start(3)>>,
+<<nng#,nng(7)>>
+
+== COPYRIGHT
+
+{copyright}