http: server callback API simplified

This simplified API lets callbacks obtain the response from the
connection objection directly, and does not require the aio to carry
it as a parameter.  Further, the request and response are both
stored inline in the connection, reducing allocations.

This is at present only for the server; the client will get a similar
set of changes.

3 files changed, 21 insertions, 25 deletions

diff --git a/docs/man/nng_http_conn_read_req.3http.adoc b/docs/man/nng_http_conn_read_req.3http.adoc
index 01d790cc..4a8d3e05 100644
--- a/docs/man/nng_http_conn_read_req.3http.adoc
+++ b/docs/man/nng_http_conn_read_req.3http.adoc
@@ -1,6 +1,6 @@
 = nng_http_conn_read_req(3http)
 //
-// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
+// Copyright 2025 Staysail Systems, Inc. <info@staysail.tech>
 // Copyright 2018 Capitar IT Group BV <info@capitar.com>
 //
 // This document is supplied under the terms of the MIT License, a
@@ -20,15 +20,15 @@ nng_http_conn_read_req - read HTTP request
 #include <nng/nng.h>
 #include <nng/supplemental/http/http.h>
 
-void nng_http_conn_read_req(nng_http_conn *conn, nng_http_req *req,
-    nng_aio *aio);
+void nng_http_conn_read_req(nng_http_conn *conn, nng_aio *aio);
 ----
 
 == DESCRIPTION
 
 The `nng_http_conn_read_req()` function starts an asynchronous read from the
-HTTP connection _conn_, reading an HTTP request into the _req_, including all
-of the related headers.
+HTTP connection _conn_, reading an HTTP request into the request object
+associated with _conn_, including all of the related headers.
+(The request object can be obtained via `nng_http_conn_req()`.
 
 NOTE: Any HTTP entity/body data associated with the request is *not* read
 automatically.
diff --git a/docs/man/nng_http_conn_write_res.3http.adoc b/docs/man/nng_http_conn_write_res.3http.adoc
index 6c998785..e88ad164 100644
--- a/docs/man/nng_http_conn_write_res.3http.adoc
+++ b/docs/man/nng_http_conn_write_res.3http.adoc
@@ -1,6 +1,6 @@
 = nng_http_conn_write_res(3http)
 //
-// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
+// Copyright 2025 Staysail Systems, Inc. <info@staysail.tech>
 // Copyright 2018 Capitar IT Group BV <info@capitar.com>
 //
 // This document is supplied under the terms of the MIT License, a
@@ -20,14 +20,13 @@ nng_http_conn_write_res - write HTTP response
 #include <nng/nng.h>
 #include <nng/supplemental/http/http.h>
 
-void nng_http_conn_write_res(nng_http_conn *conn, nng_http_res *res,
-    nng_aio *aio);
+void nng_http_conn_write_res(nng_http_conn *conn, nng_aio *aio);
 ----
 
 == DESCRIPTION
 
 The `nng_http_conn_write_res()` function starts an asynchronous write of
-the HTTP response _res_ to the connection _conn_.
+the HTTP response associated with the connection _conn_.
 The entire response is sent,
 including headers, and if present, the response body data.
 (The response body can be set with
diff --git a/docs/man/nng_http_handler_alloc.3http.adoc b/docs/man/nng_http_handler_alloc.3http.adoc
index 9291fd56..23171450 100644
--- a/docs/man/nng_http_handler_alloc.3http.adoc
+++ b/docs/man/nng_http_handler_alloc.3http.adoc
@@ -1,6 +1,6 @@
 = nng_http_handler_alloc(3http)
 //
-// Copyright 2018 Staysail Systems, Inc. <info@staysail.tech>
+// Copyright 2025 Staysail Systems, Inc. <info@staysail.tech>
 // Copyright 2018 Capitar IT Group BV <info@capitar.com>
 // Copyright 2020 Dirac Research <robert.bielik@dirac.com>
 //
@@ -23,8 +23,10 @@ nng_http_handler_alloc - allocate HTTP server handler
 
 typedef struct nng_http_handler nng_http_handler;
 
+typedef void (*nng_http_hander_func)(nng_http_conn *conn, void *arg, nng_aio *aio);
+
 int nng_http_handler_alloc(nng_http_handler **hp, const char *path,
-    void (*func)(nng_aio *);
+    nng_http_handler_func cb);
 
 int nng_http_handler_alloc_directory(nng_http_handler **hp, const char *path,
     const char *dirname);
@@ -72,24 +74,19 @@ rather than just a single element.
 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 xref:nng_aio.5.adoc[`nng_aio`] structure.
 
-The _aio_ will be passed with the following input values (retrieved with
-xref:nng_aio_get_input.3.adoc[`nng_aio_get_input()`]):
+The function receives the connection on _conn_, and the data that it set
+previously with `nng_http_handler_set_data` as the second argument.  The
+final argument is the _aio_, which must be "finished" to complete the operation.
 
-   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 function takes a pointer to an xref:nng_aio.5.adoc[`nng_aio`] structure.
 
-The handler should create an `nng_http_res *` response (such as via
-xref:nng_http_res_alloc.3http.adoc[`nng_http_res_alloc()`] or
-xref:nng_http_res_alloc_error.3http.adoc[`nng_http_res_alloc_error()`]) and store that
-in as the first output (index 0) with
-xref:nng_aio_set_output.3.adoc[`nng_aio_set_output()`].
+The handler should obtain `nng_http_res *` response from the
+connection (`nng_http_conn_res`) and update it to reflect the final status.
 
-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.
+The handler may call `nng_http_conn_write_res` to send the response, or
+it may simply let the framework do so on its behalf.  The server will perform
+this step if the callback has not already done so.
 
 Finally, using the xref:nng_aio_finish.3.adoc[`nng_aio_finish()`] function, the
 _aio_ should be completed successfully.