From edd3b6bc34f211bd3d58642d0c69ce1b5bb9dc3b Mon Sep 17 00:00:00 2001 From: gdamore Date: Thu, 9 Oct 2025 01:22:20 +0000 Subject: deploy: 9c834956456924df7c885ab8b79573721acaff5c --- ref/api/http.html | 120 +++++++++++++++++++++++++++--------------------------- 1 file changed, 60 insertions(+), 60 deletions(-) (limited to 'ref/api/http.html') diff --git a/ref/api/http.html b/ref/api/http.html index b8db5c8c..325f793b 100644 --- a/ref/api/http.html +++ b/ref/api/http.html @@ -265,8 +265,8 @@ request headers, response status, response headers, and so forth.

performed after the first transaction is complete.

At any given point in time, an nng_http object can only refer to a single HTTP transaction. In NNG, these nng_http objects are used in both the client and server APIs.

-

The nng_http object is created by either nng_http_client_connect or by an HTTP server -object which then passes it to an nng_http_handler callback function.

+

The nng_http object is created by either nng_http_client_connect or by an HTTP server +object which then passes it to an nng_http_handler callback function.

HTTP Method

void nng_http_set_method(nng_http *conn, const char *method);
 const char *nng_http_get_method(nng_http *conn);
@@ -285,8 +285,8 @@ const char *nng_http_get_uri(nng_http *conn);
 
The nng_http_set_uri function sets the URI, which normally appears like a path such as “/docs/index.html”,
 for the next transaction on conn. It sets the URI to uri, and, if query is not NULL, also appends the
 contents of query, separated by either the ‘?’ or ‘&’ character, depending on whether uri already
-contains a query string. It may return NNG_ENOMEM, or NNG_EMSGSIZE if the the result is too long,
-or NNG_EINVAL if there is some other problem with the URI.

+contains a query string. It may return NNG_ENOMEM, or NNG_EMSGSIZE if the the result is too long,
+or NNG_EINVAL if there is some other problem with the URI.

 

 

   
@@ -304,7 +304,7 @@ const char *nng_http_get_version(nng_http *conn);
 
The nng_http_set_version function is used to select the HTTP protocol version to use for the
 exchange. At present, only the values NNG_HTTP_VERSION_1_0 and NNG_HTTP_VERSION_1_1 (corresponding to
 “HTTP/1.0” and “HTTP/1.1”) are supported. NNG will default to using “HTTP/1.1” if this function is not called.
-If an unsupported version is supplied, NNG_ENOTSUP will be returned, otherwise zero.

+If an unsupported version is supplied, NNG_ENOTSUP will be returned, otherwise zero.

 
The nng_http_get_version function is used to determine the version the client selected. Normally
 there is little need to use this, but there are some subtle semantic differences between HTTP/1.0 and HTTP/1.1.

 

@@ -340,7 +340,7 @@ then a built in reason based on the status will be used instead.

   
   tip
 

-
Callbacks used on the server may wish to use nng_http_server_set_error or nng_http_server_set_redirect instead of
+
Callbacks used on the server may wish to use nng_http_server_set_error or nng_http_server_set_redirect instead of
 nng_http_set_status, because those functions will also set the response body to a suitable HTML document
 for display to users.

 

@@ -432,11 +432,11 @@ void nng_http_del_header(nng_http *conn, const char *key);

The nng_http_add_header, nng_http_set_header, and nng_http_del_header functions are used to add a modify either the request or response headers for conn prior to sending to the connected peer on conn.

-

Thus, if the conn is a client connection created by nng_http_client_connect, then the request headers are modified. +

Thus, if the conn is a client connection created by nng_http_client_connect, then the request headers are modified. Conversely, if it is a connection created by an HTTP server and used in a callback function, then the response headers are modified.

The nng_http_add_header function adds a header with the name key, and the value val, to the list of headers. In so doing, it may bring collapse multiple headers with the same name into a comma separated list, following -the syntax specified in RFC 9110. The function may return NNG_ENOMEM, NNG_EMSGSIZE, or NNG_EINVAL.

+the syntax specified in RFC 9110. The function may return NNG_ENOMEM, NNG_EMSGSIZE, or NNG_EINVAL.

The nng_http_set_header function adds the header if it does not already exist, but replaces any and all previously existing headers with the same name key, if they exist. In all other respects it behaves similarly to nng_http_add_header.

The nng_http_del_header removes all headers with name key.

@@ -495,7 +495,7 @@ including any disposing of any underlying file descriptors or related resources.

The nng_http_reset function resets the request and response state of the the connection conn, so that it is just as if it had been freshly created with -nng_http_client_connect or passed into a handler function for a server callback.

+nng_http_client_connect or passed into a handler function for a server callback.

The intended purpose of this function is to clear the object state before reusing the conn for subsequent transactions.

Direct Read and Write

@@ -505,11 +505,11 @@ void nng_http_read_all(nng_http *conn, nng_aio *aio); void nng_http_write_all(nng_http *conn, nng_aio *aio);

The nng_http_read and nng_http_write functions read or write data asynchronously from or to the -connection conn, using the nng_iov that is set in aio with nng_aio_set_iov. +connection conn, using the nng_iov that is set in aio with nng_aio_set_iov. These functions will complete as soon as any data is transferred. -Use nng_aio_count to determine how much data was actually transferred.

+Use nng_aio_count to determine how much data was actually transferred.

The nng_http_read_all and nng_http_write_all functions perform the same task, but will keep resubmitting -operations until the the entire amount of data requested by the nng_iov is transferred.

+operations until the the entire amount of data requested by the nng_iov is transferred.

@@ -517,7 +517,7 @@ operations until the the entire amount of data requested by the nng_http_hijack. +

These functions are most likely to be useful after hijacking the connection with nng_http_hijack. They can be used to transfer request or response body data as well.

Hijacking Connections

nng_err nng_http_hijack(nng_http *conn);
@@ -529,7 +529,7 @@ to be disassociated from the HTTP server where it was created.

 WebSocket), where the underlying HTTP connection will be taken over for
 some other purpose, and should not be used any further by the server.

 
This function is most useful when called from a handler function.
-(See nng_http_handler_alloc.)

+(See nng_http_handler_alloc.)

 

 

   
@@ -537,7 +537,7 @@ some other purpose, and should not be used any further by the server.

 

 
It is the responsibility of the caller to dispose of the underlying connection when it is no longer needed.
 Furthermore, the HTTP server will no longer send any responses to the hijacked connection, so the caller should do that as well if appropriate.
-(See nng_http_write_response.)

+(See nng_http_write_response.)

 

 

 

@@ -554,7 +554,7 @@ Most applications will never need to use this function.

 
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.

+See nng_tls_cert for more information about working with TLS certificates.

 

 

   
@@ -571,8 +571,8 @@ 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.
-It is analogous to a dialer object used elsewhere in NNG, but it specifically is only for HTTP.

+
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);
 

@@ -589,7 +589,7 @@ of its resources.

   
   note
 

-
Any connections created by nng_http_client_connect are not affected by this function,
+
Any connections created by nng_http_client_connect are not affected by this function,
 and must be closed explicitly as needed.

 

 
Client TLS

@@ -597,10 +597,10 @@ and must be closed explicitly as needed.

 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 -retrieve or change the TLS configuration used when making outbound connections, enabling +retrieve or change the TLS configuration used when making outbound connections, enabling 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.

+

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 nng_http_client_get_tls, unless a separate hold on the object was obtained.

Once TLS is enabled for an nng_http_client, it is not possible to disable TLS.

@@ -610,7 +610,7 @@ Both functions will return NNG note

The TLS configuration itself cannot be changed once it has been used to create a connection, -such as by calling nng_http_client_connect, but a new one can be installed in the client. +such as by calling nng_http_client_connect, but a new one can be installed in the client. Existing connections will use the TLS configuration that there were created with.

Creating Connections

@@ -619,9 +619,9 @@ 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 -server configured for client, and creates an nng_http object for the connection.

+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.

+retried from the aio using nng_aio_get_output with index 0.

Example 1: Connecting to Google

nng_aio *aio;
 nng_url *url;
@@ -660,16 +660,16 @@ the HTTP request associated with conn.
 The entire request is sent,
 including headers, and if present, the request body data.
 (The request body can be set with
-nng_http_set_body or nng_http_copy_body.)

+nng_http_set_body or nng_http_copy_body.)

 
This function returns immediately, with no return value.
 Completion of the operation is signaled via the aio, and the final result
-may be obtained via nng_aio_result.

+may be obtained via nng_aio_result.

 

 

   
   tip
 

-
Consider using the nng_http_transact function,
+
Consider using the nng_http_transact function,
 which provides a simpler interface for performing a complete HTTP client transaction.

 

 
Obtaining the Response

@@ -678,7 +678,7 @@ which provides a simpler interface for performing a complete HTTP client transac
 
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.

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

 

 

   
@@ -692,7 +692,7 @@ need to do so may use the direct read functions.

   
   tip
 

-
An easier one-shot method for many use cases might be nng_http_transact.

+
An easier one-shot method for many use cases might be nng_http_transact.

 

 
Submitting the Transaction

 
void nng_http_transact(nng_http *conn, nng_aio *aio);
@@ -703,11 +703,11 @@ When the function is complete, the aio will be notified.

 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
-subsequently be obtained using nng_http_get_body.

+subsequently be obtained using nng_http_get_body.

 
This function is intended to make creation of client applications easier,
 by performing multiple asynchronous operations required to complete an
 entire HTTP transaction.

-
If an error occurs, the caller should close conn with nng_http_close, as it may not
+
If an error occurs, the caller should close conn with nng_http_close, as it may not
 necessarily be usable with other transactions.

 

 

@@ -731,7 +731,7 @@ request interleaving.

 

 
This function returns immediately, with no return value.
 Completion of the operation is signaled via the aio, and the final result
-may be obtained via nng_aio_result.

+may be obtained via nng_aio_result.

 
Response Body

 
Server API

 
Handlers

@@ -745,7 +745,7 @@ Only the path component of the Request URI is considered when determining whethe
 
This implementation limits the path length to 1024 bytes, including the
 zero termination byte. This does not prevent requests with much longer
 URIs from being supported, but doing so will require setting the handler to match a parent path in the tree using
-nng_http_handler_set_tree.

+nng_http_handler_set_tree.

 

 

   
@@ -754,11 +754,11 @@ URIs from being supported, but doing so will require setting the handler to matc
 
The NNG HTTP framework is optimized for URLs shorter than 200 characters.

 

 
Additionally each handler has a method it is registered to handle
-(the default is “GET” andc can be changed with nng_http_handler_set_method), and
-optionally a “Host” header it can be matched against (see nng_http_handler_set_host).

+(the default is “GET” andc can be changed with nng_http_handler_set_method), and
+optionally a “Host” header it can be matched against (see nng_http_handler_set_host).

 
In some cases, a handler may reference a logical tree rather (directory)
 rather than just a single element.
-(See nng_http_handler_set_tree).

+(See nng_http_handler_set_tree).

 
Implementing a Handler

 
typedef void (*nng_http_handler_func)(nng_http_conn *conn, void *arg, nng_aio *aio);
 
@@ -770,30 +770,30 @@ On success, a pointer to the handler is stored at the located pointed to by 
 
The handler function is specified by cb.
 This function uses the asynchronous I/O framework.

 
The function receives the connection on conn, and an optional data pointer that was set
-previously with nng_http_handler_set_data as the second argument. The
-final argument is the nng_aio aio, which must be “finished” to complete the operation.

-
The handler may call nng_http_write_response to send the response, or
+previously with nng_http_handler_set_data as the second argument. The
+final argument is the nng_aio aio, which must be “finished” to complete the operation.

+
The handler may call nng_http_write_response 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.

-
Response headers may be set using nng_http_set_header, and request headers
-may be accessed by using nng_http_get_header. They can also be iterated
-over using nng_http_next_header

-
Likewise the request body may be accessed, using nng_http_get_body, and
-the response body may be set using either nng_http_set_body or nng_http_copy_body.

+
Response headers may be set using nng_http_set_header, and request headers
+may be accessed by using nng_http_get_header. They can also be iterated
+over using nng_http_next_header

+
Likewise the request body may be accessed, using nng_http_get_body, and
+the response body may be set using either nng_http_set_body or nng_http_copy_body.

 

 

   
   note
 

 
The request body is only collected for the handler if the
-nng_http_handler_collect_body function has been called for the handler.

+nng_http_handler_collect_body function has been called for the handler.

 

-
The HTTP status should be set for the transaction using nng_http_set_status.

-
Finally, the handler should finish the operation by calling the nng_aio_finish function
-after having set the status to NNG_OK.
+
The HTTP status should be set for the transaction using nng_http_set_status.

+
Finally, the handler should finish the operation by calling the nng_aio_finish function
+after having set the status to NNG_OK.
 If any other status is set on the aio, then a generic 500 response will be created and
 sent, if possible, and the connection will be closed.

-
The aio may be scheduled for deferred completion using the nng_aio_start.

+
The aio may be scheduled for deferred completion using the nng_aio_start.

 
Serving Directories and Files

 
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);
@@ -819,7 +819,7 @@ then a value of application/octet-stream is assumed.

 

 
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 status,
+
The HTTP reply it creates will be with status code status,
 which should be a 3XX code such as 301, and a Location: header will contain the URL
 referenced by location, with any residual suffix from the request
 URI appended.

@@ -828,7 +828,7 @@ URI appended.

   
   tip
 

-
Use nng_http_handler_set_tree to redirect an entire tree.
+
Use nng_http_handler_set_tree to redirect an entire tree.
 For example, it is possible to redirect an entire HTTP site to another
 HTTPS site by specifying / as the path and then using the base
 of the new site, such as https://newsite.example.com as the new location.

@@ -839,10 +839,10 @@ of the new site, such as https://newsite.example.com as the new loc
   tip
 

 
Be sure to use the appropriate value for status.
-Permanent redirection should use NNG_HTTP_STATUS_MOVED_PERMANENTLY (301)
-and temporary redirections should use NNG_HTTP_STATUS_TEMPORARY_REDIRECT (307).
+Permanent redirection should use NNG_HTTP_STATUS_MOVED_PERMANENTLY (301)
+and temporary redirections should use NNG_HTTP_STATUS_TEMPORARY_REDIRECT (307).
 In REST APIs, using a redirection to supply the new location of an object
-created with POST should use NNG_HTTP_STATUS_SEE_OTHER (303).

+created with POST should use NNG_HTTP_STATUS_SEE_OTHER (303).

 
 
Collecting Request Body

 
void nng_http_handler_collect_body(nng_http_handler *handler, bool want, size_t maxsz);
@@ -851,12 +851,12 @@ created with POST should use nng_http_get_body function.

+nng_http_get_body function.

 
The collection is enabled if want is true.
 Furthermore, the data that the client may sent is limited by the
 value of maxsz.
 If the client attempts to send more data than maxsz, then the
-request will be terminated with NNG_HTTP_STATUS_CONTENT_TOO_LARGE (413).

+request will be terminated with NNG_HTTP_STATUS_CONTENT_TOO_LARGE (413).

 

 

   
@@ -903,7 +903,7 @@ The intended use of this function is deallocate any resources associated with 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.
-The handler may determine the actual method used with the nng_http_get_method function.

+The handler may determine the actual method used with the nng_http_get_method function.

 
The server will automatically call “GET” handlers if the client
 sends a “HEAD” request, and will suppress HTTP body data in the responses
 sent for such requests.

@@ -954,9 +954,9 @@ It can also provide a logical fallback instead of relying on a 404 error code.void nng_http_write_response(nng_http *conn, nng_aio *aio);
 

 
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.

+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
-using the nng_aio aio.

+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
 explicitly by setting the “Connection: close” header, the connection will be closed after the
-- 
cgit v1.2.3-70-g09d2