Add possibility to explicitly set a tree handler as exclusive (#1158)

- Default tree handler behavior is now non-exclusive
- Add 'longest uri first' ordering for http handlers

3 files changed, 18 insertions, 3 deletions

diff --git a/docs/man/libnng.3.adoc b/docs/man/libnng.3.adoc
index 4e59890f..84c653b7 100644
--- a/docs/man/libnng.3.adoc
+++ b/docs/man/libnng.3.adoc
@@ -3,6 +3,7 @@
 // Copyright 2019 Staysail Systems, Inc. <info@staysail.tech>
 // Copyright 2018 Capitar IT Group BV <info@capitar.com>
 // Copyright 2019 Devolutions <info@devolutions.net>
+// Copyright 2020 Dirac Research <robert.bielik@dirac.com>
 //
 // This document is supplied under the terms of the MIT License, a
 // copy of which should be located in the distribution where this
diff --git a/docs/man/nng_http_handler_alloc.3http.adoc b/docs/man/nng_http_handler_alloc.3http.adoc
index 6504212f..506cdcf9 100644
--- a/docs/man/nng_http_handler_alloc.3http.adoc
+++ b/docs/man/nng_http_handler_alloc.3http.adoc
@@ -2,6 +2,7 @@
 //
 // Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
 // Copyright 2018 Capitar IT Group BV <info@capitar.com>
+// Copyright 2020 Dirac Research <robert.bielik@dirac.com>
 //
 // This document is supplied under the terms of the MIT License, a
 // copy of which should be located in the distribution where this
@@ -111,10 +112,14 @@ 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 requested file name.
-If a content type cannot be determined from
+of the requested file name. If a content type cannot be determined from
 the extension, then `application/octet-stream` is used.
 
+The directory handler is created as a tree handler initially in exclusive mode (see
+xref:nng_http_handler_set_tree.3http.adoc[nng_http_handler_set_tree_exclusive
+]). This can be changed by calling xref:nng_http_handler_set_tree.3http.adoc
+[nng_http_handler_set_tree(3http)] after creating the directory handler.
+
 === File Handler
 
 The third member of this family, `nng_http_handler_alloc_file()`, creates
@@ -178,6 +183,7 @@ xref:nng_http_handler_free.3http.adoc[nng_http_handler_free(3http)],
 xref:nng_http_handler_set_host.3http.adoc[nng_http_handler_set_host(3http)],
 xref:nng_http_handler_set_method.3http.adoc[nng_http_handler_set_method(3http)],
 xref:nng_http_handler_set_tree.3http.adoc[nng_http_handler_set_tree(3http)],
+xref:nng_http_handler_set_tree.3http.adoc[nng_http_handler_set_tree_exclusive(3http)],
 xref:nng_http_res_alloc.3http.adoc[nng_http_res_alloc(3http)],
 xref:nng_http_res_alloc_error.3http.adoc[nng_http_res_alloc_error(3http)],
 xref:nng_http_server_add_handler.3http.adoc[nng_http_server_add_handler(3http)],
diff --git a/docs/man/nng_http_handler_set_tree.3http.adoc b/docs/man/nng_http_handler_set_tree.3http.adoc
index fc26ec70..dd2731f8 100644
--- a/docs/man/nng_http_handler_set_tree.3http.adoc
+++ b/docs/man/nng_http_handler_set_tree.3http.adoc
@@ -2,6 +2,7 @@
 //
 // Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
 // Copyright 2018 Capitar IT Group BV <info@capitar.com>
+// Copyright 2020 Dirac Research <robert.bielik@dirac.com>
 //
 // This document is supplied under the terms of the MIT License, a
 // copy of which should be located in the distribution where this
@@ -21,6 +22,8 @@ nng_http_handler_set_tree - set HTTP handler to match trees
 #include <nng/supplemental/http/http.h>
 
 int nng_http_handler_set_tree(nng_http_handler *handler);
+
+int nng_http_handler_set_tree_exclusive(nng_http_handler *handler);
 ----
 
 == DESCRIPTION
@@ -29,7 +32,12 @@ 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
+The `nng_http_handler_set_tree_exclusive()` function is similar to `nng_http_server_set_tree()`
+with the distinction that the _handler_ will be considered to *exclusively* handling its 
+Request URI. Other handlers will be tested against _handler_ when being added to a server, 
+possibly resulting in a URI conflict error.
+
+TIP: These methods are useful when constructing API handlers where a single
 service address (path) supports dynamically generated children.
 
 == RETURN VALUES