From f1e6bd1e5b89f96164c2ecee56a912ae6995cfae Mon Sep 17 00:00:00 2001 From: gdamore Date: Mon, 6 Oct 2025 05:16:55 +0000 Subject: deploy: 06d6d80f8c92ef1d3bd7c00c919e10a411183cb3 --- ref/api/http.html | 60 ++++++++++++++++++++++++++++++++++++------------------- 1 file changed, 39 insertions(+), 21 deletions(-) (limited to 'ref/api/http.html') diff --git a/ref/api/http.html b/ref/api/http.html index 18ec607b..aac5ec43 100644 --- a/ref/api/http.html +++ b/ref/api/http.html @@ -547,24 +547,42 @@ Furthermore, the HTTP server will no longer send any responses to the hijacked c

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.

+

Obtaining TLS Connection Details

+
nng_err nng_http_peer_cert(nng_http_conn *conn, nng_tls_cert **certp);
+
+

TODO: We need to document the cert API.

+

The nng_http_peer_cert function will obtain the TLS certificate object for the peer, if one is available. +This can then be used for additional authentication or identity specific logic.

+

The certificate must be released with [nng_tls_cert_free] when no longer in use. +See [nng_tls_cert] for more information about working with TLS certificates.

+
+

+ + note +

+

While it should be obvious that this function is only available when using HTTPS, +it also requires that peer authentication is in use, and may require that the underlying +TLS engine support peer certificate colleciton. (Some minimal configurations elide this +to save space in embedded environments.)

+

Client API

The NNG client API consists of an API for creating connections, and an API for performing transactions on those connections.

Client Object

typedef struct nng_http_client nng_http_client;
-

The nng_http_client object is the client side creator for nng_http objects. +

The nng_http_client object is the client side creator for nng_http objects. It is analogous to a dialer object used elsewhere in NNG, but it specifically is only for HTTP.

Create a Client

void nng_http_client_alloc(nng_http_client *clientp, const nng_url *url);
-

The nng_http_client_alloc allocates an HTTP client suitable for +

The nng_http_client_alloc allocates an HTTP client suitable for connecting to the server identified by url and stores a pointer to it in the location referenced by clientp.

Destroy a Client

void nng_http_client_free(nng_http_client *client);
-

The nng_http_client_free connection destroys the client object and any +

The nng_http_client_free connection destroys the client object and any of its resources.

@@ -578,9 +596,9 @@ and must be closed explicitly as needed.

nng_err nng_http_client_get_tls(nng_http_client *client, nng_tls_config **tlsp);
 nng_err nng_http_client_set_tls(nng_http_client *client, nng_tls_config *tls);
-

The nng_http_client_get_tls and nng_http_client_set_tls functions are used to +

The nng_http_client_get_tls and nng_http_client_set_tls functions are used to retrieve or change the TLS configuration used when making outbound connections, enabling -TLS as a result.

+TLS as a result.

If TLS has not been previously configured on client, then nng_http_client_get_tls will return NNG_EINVAL. Both functions will return NNG_ENOTSUP if either HTTP or TLS is not supported.

Calling nng_http_client_set_tls invalidates any client previously obtained with @@ -600,7 +618,7 @@ Existing connections will use the TLS configuration that there were created with void nng_http_client_connect(nng_http_client *client, nng_aio *aio); -

The nng_http_client_connect function makes an outgoing connection to the +

The nng_http_client_connect function makes an outgoing connection to the server configured for client, and creates an nng_http object for the connection.

This is done asynchronously, and when the operation succeseds the connection may be retried from the aio using nng_aio_get_output with index 0.

@@ -637,7 +655,7 @@ if ((rv = nng_aio_result(aio)) != 0) {

Sending the Request

void nng_http_write_request(nng_http *conn, nng_aio *aio);
-

The nng_http_write_request function starts an asynchronous write of +

The nng_http_write_request function starts an asynchronous write of the HTTP request associated with conn. The entire request is sent, including headers, and if present, the request body data. @@ -657,7 +675,7 @@ which provides a simpler interface for performing a complete HTTP client transac

Obtaining the Response

void nng_http_read_response(nng_http *conn, nng_aio *aio);
-

The nng_http_read_response function starts an asynchronous read from the +

The nng_http_read_response function starts an asynchronous read from the HTTP connection conn, reading an HTTP response into the response associated with conn, including all of the related headers.

It does not transfer any response body. To do that, use nng_http_read_all or nng_http_read.

@@ -679,9 +697,9 @@ need to do so may use the direct read functions.

Submitting the Transaction

void nng_http_transact(nng_http *conn, nng_aio *aio);
-

The HTTP request is issued, and the response processed, asynchronously by the nng_http_transact function. +

The HTTP request is issued, and the response processed, asynchronously by the nng_http_transact function. When the function is complete, the aio will be notified.

-

The nng_http_transact function is used to perform a complete +

The nng_http_transact function is used to perform a complete HTTP exchange over the connection conn, sending the request and attached body data to the remote server, and reading the response.

The entire response is read, including any associated body, which can @@ -719,7 +737,7 @@ may be obtained via [nng_aio_result()].

Handlers

typedef struct nng_http_handler nng_http_handler;
-

An nng_http_handler encapsulates a function used used to handle +

An nng_http_handler encapsulates a function used used to handle incoming requests on an HTTP server, routed based on method and URI, and the parameters used with that function.

Every handler has a Request-URI to which it refers, which is determined by the path argument. @@ -746,7 +764,7 @@ rather than just a single element. nng_err nng_http_handler_alloc(nng_http_handler **hp, const char *path, nng_http_handler_func cb); -

The nng_http_handler_alloc function allocates a generic handler +

The nng_http_handler_alloc function allocates a generic handler which will be used to process requests coming into an HTTP server. On success, a pointer to the handler is stored at the located pointed to by hp.

The handler function is specified by cb. @@ -779,7 +797,7 @@ sent, if possible, and the connection will be closed.

nng_err nng_http_handler_alloc_directory(nng_http_handler **hp, const char *path, const char *dirname);
 nng_err nng_http_handler_alloc_file(nng_http_handler **hp, const char *path, const char *filename);
-

The nng_http_handler_alloc_directory and nng_http_handler_alloc_file +

The nng_http_handler_alloc_directory and nng_http_handler_alloc_file create handlers pre-configured to act as static content servers for either a full directory at dirname, or the single file at filename. These support the “GET” and “HEAD” methods, and the directory variant will dynamically generate index.html content based on @@ -790,7 +808,7 @@ determined, the content type is set to “application/octet-stream”.

nng_err nng_http_handler_alloc_static(nng_http_handler **hp, const char *path,
         const void *data, size_t size, const char *content_type);
-

The nng_http_handler_alloc_static function creates a handler that +

The nng_http_handler_alloc_static function creates a handler that serves the content located in data (consisting of size bytes) at the URI path. The content_type determines the “Content-Type” header. If NULL is specified then a value of application/octet-stream is assumed.

@@ -798,7 +816,7 @@ then a value of application/octet-stream is assumed.

nng_err nng_http_handler_alloc_redirect(nng_http_handler **hp, const char *path,
         nng_http_status status, const char *location);
-

The nng_http_handler_alloc_redirect function creates a handler with +

The nng_http_handler_alloc_redirect function creates a handler with a function that simply directions from the URI at path to the given location.

The HTTP reply it creates will be with [status code][nng_http_status] status, which should be a 3XX code such as 301, and a Location: header will contain the URL @@ -828,7 +846,7 @@ created with POST should use [NNG_HTTP_STATUS_SEE_OTHERCollecting Request Body 

void nng_http_handler_collect_body(nng_http_handler *handler, bool want, size_t maxsz);
-

The nng_http_handler_collect_body function requests that HTTP server +

The nng_http_handler_collect_body function requests that HTTP server framework collect any request body for the request and attach it to the connection before calling the callback for the handler.

Subsequently the data can be retrieved by the handler from the request with the @@ -872,7 +890,7 @@ create few limitations.

void nng_http_handler_set_data(nng_http_handler *handler, void *data,
     void (*dtor)(void *));
-

The nng_http_handler_set_data function is used to set the +

The nng_http_handler_set_data function is used to set the data argument that will be passed to the callback.

Additionally, when the handler is deallocated, if dtor is not NULL, then it will be called with data as its argument. @@ -880,7 +898,7 @@ The intended use of this function is deallocate any resources associated with Setting the Method 

void nng_http_handler_set_method(nng_http_handler *handler, const char *method);
-

The nng_http_handler_set_method function sets the method that the +

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 the handler will be executed for all methods. @@ -898,7 +916,7 @@ sent for such requests.

Filtering by Host

void nng_http_handler_set_host(nng_http_handler *handler, const char *host);
-

The nng_http_handler_set_host function is used to limit the scope of the +

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.

This can be used to create servers with different content for different virtual hosts.

@@ -916,7 +934,7 @@ does not support a single server listening on different ports concurrently.

Handling an Entire Tree

void nng_http_handler_set_tree(nng_http_handler *handler);
-

The nng_http_handler_set_tree function causes the handler to be matched if the request URI sent +

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, and no more specific handler has been registered.

This is useful in cases when the handler would like to examine the entire path @@ -936,7 +954,7 @@ It can also provide a logical fallback instead of relying on a 404 error code.

Normally the server will send any attached response, but there are circumstances where a response must be sent manually, such as when hijacking a connection.

-

In such a case, nng_http_write_response can be called, which will send the response and any attached data, asynchronously +

In such a case, nng_http_write_response can be called, which will send the response and any attached data, asynchronously using the nng_aio aio.

By default, for HTTP/1.1 connections, the connection is kept open, and will be reused to receive new requests. For HTTP/1.0, or if the client has requested -- cgit v1.2.3-70-g09d2