From f42d0c6ef956d119e8762a3ecda37886fa055637 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore 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_conn_read_req.3http.adoc | 10 +++++----- docs/man/nng_http_conn_write_res.3http.adoc | 7 +++---- docs/man/nng_http_handler_alloc.3http.adoc | 29 +++++++++++++---------------- 3 files changed, 21 insertions(+), 25 deletions(-) (limited to 'docs') 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. +// Copyright 2025 Staysail Systems, Inc. // Copyright 2018 Capitar IT Group BV // // 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 #include -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. +// Copyright 2025 Staysail Systems, Inc. // Copyright 2018 Capitar IT Group BV // // 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 #include -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. +// Copyright 2025 Staysail Systems, Inc. // Copyright 2018 Capitar IT Group BV // Copyright 2020 Dirac Research // @@ -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