From f42d0c6ef956d119e8762a3ecda37886fa055637 Mon Sep 17 00:00:00 2001
From: Garrett D'Amore <garrett@damore.org>
Date: Sun, 5 Jan 2025 16:46:03 -0800
Subject: 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.
---
 docs/man/nng_http_handler_alloc.3http.adoc | 29 +++++++++++++----------------
 1 file changed, 13 insertions(+), 16 deletions(-)

(limited to 'docs/man/nng_http_handler_alloc.3http.adoc')

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.
-- 
cgit v1.2.3-70-g09d2

