Http nng err

docs/ref/api/aio.md

@@ -81,7 +81,7 @@ is safe to call from _aio_'s own callback.
 ## Cancellation
 
 ```c
-void nng_aio_abort(nng_aio *aio, int err);
+void nng_aio_abort(nng_aio *aio, nng_err err);
 void nng_aio_cancel(nng_aio *aio);
 void nng_aio_stop(nng_aio *aio);
 ```
@@ -169,7 +169,7 @@ This is the same test used internally by [`nng_aio_wait`].
 ## Result of Operation
 
 ```c
-int nng_aio_result(nng_aio *aio);
+nng_err nng_aio_result(nng_aio *aio);
 size_t nng_aio_count(nng_aio *aio);
 ```
 

docs/ref/api/errors.md

@@ -1,21 +1,29 @@
 # Errors
 
+```c
+typedef enum ... nng_err;
+```
+
 Many _NNG_ functions can fail for a variety of reasons.
 These functions tend to return either zero on success,
 or a non-zero error code to indicate failure.
 {{footnote: This convention goes back to UNIX system calls,
 which behave the same way, but _NNG_ does not use a separate
 _errno_ variable.}}
 
-All these error codes are `int`.
+All these error codes are `nng_err`.
+
+> [!NOTE]
+> Many APIs are still using `int`, but the `nng_err` enumeration can be used
+> instead, and will help with debugging.
 
 Not every possible error code is defined here, as sometimes
 an underlying system or library error code is "wrapped".
 
 ## Human Readable Error Message
 
 ```c
-const char *nng_strerror(int err);
+const char *nng_strerror(nng_err err);
 ```
 
 The {{i:`nng_strerror`}} returns the human-readable description of the

docs/ref/api/http.md

@@ -56,7 +56,7 @@ set when issuing the transaction.
 ### HTTP URI
 
 ```c
-int nng_http_set_uri(nng_http *conn, const char *uri, const char *query);
+nng_err nng_http_set_uri(nng_http *conn, const char *uri, const char *query);
 const char *nng_http_get_uri(nng_http *conn);
 ```
 
@@ -76,7 +76,7 @@ will have any query concentated, for example "/api/get_user.cgi?name=garrett".
 ### HTTP Version
 
 ```c
-int nng_http_set_version(nng_http *conn, const char *version);
+nng_err nng_http_set_version(nng_http *conn, const char *version);
 const char *nng_http_get_version(nng_http *conn);
 ```
 
@@ -98,9 +98,10 @@ there is little need to use this, but there are some subtle semantic differences
 ### HTTP Status
 
 ```c
-uint16_t nng_http_get_status(nng_http *conn);
+typedef enum ... nng_http_status;
+nng_http_status nng_http_get_status(nng_http *conn);
 const char *nng_http_get_reason(nng_http_conn *conn);
-void nng_http_set_status(nng_http *conn, uint16_t status, const char *reason);
+void nng_http_set_status(nng_http *conn, nng_http_status status, const char *reason);
 ```
 
 The {{i:`nng_http_get_status`}} function obtains the numeric code (typipcally numbered from 100 through 599) returned
@@ -210,8 +211,8 @@ The scan can be rest by setting _next_ to `NULL`.
 ### Modifying Headers
 
 ```c
-int nng_http_add_header(nng_http *conn, const char *key, const char *val);
-int nng_http_set_header(nng_http *conn, const char *key, const char *val);
+nng_err nng_http_add_header(nng_http *conn, const char *key, const char *val);
+nng_err nng_http_set_header(nng_http *conn, const char *key, const char *val);
 void nng_http_del_header(nng_http *conn, const char *key);
 ```
 
@@ -323,7 +324,7 @@ They can be used to transfer request or response body data as well.
 ### Hijacking Connections
 
 ```c
-void nng_http_hijack(nng_http_conn *conn);
+nng_err nng_http_hijack(nng_http *conn);
 ```
 
 TODO: This API will change to convert the conn into a stream object.
@@ -387,8 +388,8 @@ of its resources.
 ### Client TLS
 
 ```c
-int nng_http_client_get_tls(nng_http_client *client, nng_tls_config **tlsp);
-int nng_http_client_set_tls(nng_http_client *client, nng_tls_config *tls);
+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 {{i:`nng_http_client_get_tls`}} and {{i:`nng_http_client_set_tls`}} functions are used to
@@ -456,15 +457,6 @@ if ((rv = nng_aio_result(aio)) != 0) {
 
 ### Preparing a Transaction
 
-```c
-int nng_http_set_version(nng_http *conn, const char *version);
-int nng_http_set_uri(nng_http *conn, const char *uri);
-```
-
-The {{i:`nng_http_set_uri`}} function provides a URI for the transaction. This will be used to
-set the URI for the request. The URI typically appears like a path, starting with "/", although
-it may also contain a query string.
-
 ### Request Body
 
 ### Sending the Request
@@ -510,7 +502,7 @@ It does _not_ transfer any response body. To do that, use [`nng_http_read_all`]
 ### Submitting the Transaction
 
 ```c
-int nng_http_transact(nng_http *conn, nng_aio *aio);
+void nng_http_transact(nng_http *conn, nng_aio *aio);
 ```
 
 The HTTP request is issued, and the response processed, asynchronously by the {{i:`nng_http_transact`}} function.

include/nng/http.h

@@ -25,7 +25,7 @@ extern "C" {
 #include <nng/nng.h>
 
 // HTTP status codes.  This list is not exhaustive.
-enum nng_http_status {
+typedef enum {
 	NNG_HTTP_STATUS_CONTINUE                 = 100,
 	NNG_HTTP_STATUS_SWITCHING                = 101,
 	NNG_HTTP_STATUS_PROCESSING               = 102,
@@ -86,7 +86,7 @@ enum nng_http_status {
 	NNG_HTTP_STATUS_LOOP_DETECTED            = 508,
 	NNG_HTTP_STATUS_NOT_EXTENDED             = 510,
 	NNG_HTTP_STATUS_NETWORK_AUTH_REQUIRED    = 511,
-};
+} nng_http_status;
 
 #define NNG_HTTP_VERSION_1_0 "HTTP/1.0"
 #define NNG_HTTP_VERSION_1_1 "HTTP/1.1"
@@ -147,13 +147,13 @@ NNG_DECL void nng_http_reset(nng_http *);
 // include an optional query string, either inline in the URI to start,
 // or as a separate argument.  If the query string already exists
 // and one is also supplied here, it will be appended (separated with &).
-NNG_DECL int nng_http_set_uri(nng_http *, const char *, const char *);
+NNG_DECL nng_err nng_http_set_uri(nng_http *, const char *, const char *);
 
 // nng_http_get_uri returns the URI.  It will be NULL if not set.
 NNG_DECL const char *nng_http_get_uri(nng_http *);
 
 // nng_http_get_status gets the status of the last transaction
-NNG_DECL uint16_t nng_http_get_status(nng_http *);
+NNG_DECL nng_http_status nng_http_get_status(nng_http *);
 
 // nng_http_reason gets the message associated with status of the last
 // transaction
@@ -162,12 +162,12 @@ NNG_DECL const char *nng_http_get_reason(nng_http *);
 // nng_http_set_status sets the status for the transaction (server API),
 // and also sets the reason (message) for it.  (If NULL is used for the reason,
 // then a builtin value is used based on the code.)
-NNG_DECL void nng_http_set_status(nng_http *, uint16_t, const char *);
+NNG_DECL void nng_http_set_status(nng_http *, nng_http_status, const char *);
 
 // nng_http_set_version is used to change the version of a request.
 // Normally the version is "HTTP/1.1".  Note that the framework does
 // not support HTTP/2 at all.  Null sets the default ("HTTP/1.1").
-NNG_DECL int nng_http_set_version(nng_http *, const char *);
+NNG_DECL nng_err nng_http_set_version(nng_http *, const char *);
 
 // nng_http_get_version is used to get the version of a request.
 NNG_DECL const char *nng_http_get_version(nng_http *);
@@ -184,8 +184,8 @@ NNG_DECL const char *nng_http_get_method(nng_http *);
 // a header to either the request or response.  Clients modify the request
 // headers, and servers (and callbacks on the server) modify response headers.
 // These can return NNG_ENOMEM, NNG_MSGSIZE, etc.
-NNG_DECL int nng_http_set_header(nng_http *, const char *, const char *);
-NNG_DECL int nng_http_add_header(nng_http *, const char *, const char *);
+NNG_DECL nng_err nng_http_set_header(nng_http *, const char *, const char *);
+NNG_DECL nng_err nng_http_add_header(nng_http *, const char *, const char *);
 
 // nng_http_del_header removes all of the headers for the given header.
 // For clients this is done on the request headers, for servers its the
@@ -205,7 +205,7 @@ NNG_DECL void nng_http_set_body(nng_http *, void *, size_t);
 
 // nng_http_copy_body sets the body to send out in the next exchange, but
 // makes a local copy.  It can fail due to NNG_ENOMEM.
-NNG_DECL int nng_http_copy_body(nng_http *, const void *, size_t);
+NNG_DECL nng_err nng_http_copy_body(nng_http *, const void *, size_t);
 
 // nng_http_handler is a handler used on the server side to handle HTTP
 // requests coming into a specific URL.
@@ -230,7 +230,7 @@ typedef struct nng_http_handler nng_http_handler;
 // completion by nng_aio_finish.  The second argument to this function is the
 // handler data that was optionally set by nng_handler_set_data.
 typedef void (*nng_http_handler_func)(nng_http *, void *, nng_aio *);
-NNG_DECL int nng_http_handler_alloc(
+NNG_DECL nng_err nng_http_handler_alloc(
     nng_http_handler **, const char *, nng_http_handler_func);
 
 // nng_http_handler_free frees the handler. This actually just drops a
@@ -241,28 +241,28 @@ NNG_DECL void nng_http_handler_free(nng_http_handler *);
 // nng_http_handler_alloc_file creates a "file" based handler, that
 // serves up static content from the given file path.  The content-type
 // supplied is determined from the file name using a simple built-in map.
-NNG_DECL int nng_http_handler_alloc_file(
+NNG_DECL nng_err nng_http_handler_alloc_file(
     nng_http_handler **, const char *, const char *);
 
 // nng_http_handler_alloc_static creates a static-content handler.
 // The last argument is the content-type, which may be NULL (in which case
 // "application/octet-stream" is assumed.)
-NNG_DECL int nng_http_handler_alloc_static(
+NNG_DECL nng_err nng_http_handler_alloc_static(
     nng_http_handler **, const char *, const void *, size_t, const char *);
 
 // nng_http_handler_alloc_redirect creates an HTTP redirect handler.
 // The status is given, along with the new URL.  If the status is 0,
 // then 301 will be used instead.
-NNG_DECL int nng_http_handler_alloc_redirect(
-    nng_http_handler **, const char *, uint16_t, const char *);
+NNG_DECL nng_err nng_http_handler_alloc_redirect(
+    nng_http_handler **, const char *, nng_http_status, const char *);
 
 // nng_http_handler_alloc_file creates a "directory" based handler, that
 // serves up static content from the given directory tree.  Directories
 // that contain an index.html or index.htm file use that file for the
 // directory content, otherwise a suitable error page is returned (the server
 // does not generate index pages automatically.)  The content-type for
 // files is determined from the file name using a simple built-in map.
-NNG_DECL int nng_http_handler_alloc_directory(
+NNG_DECL nng_err nng_http_handler_alloc_directory(
     nng_http_handler **, const char *, const char *);
 
 // nng_http_handler_set_method sets the method that the handler will be
@@ -310,7 +310,7 @@ typedef struct nng_http_server nng_http_server;
 // from the URL.  If a server already exists, then a hold is placed on it, and
 // that instance is returned.  If no such server exists, then a new instance
 // is created.
-NNG_DECL int nng_http_server_hold(nng_http_server **, const nng_url *);
+NNG_DECL nng_err nng_http_server_hold(nng_http_server **, const nng_url *);
 
 // nng_http_server_release releases the hold on the server.  If this is the
 // last instance of the server, then it is shutdown and resources are freed.
@@ -319,7 +319,7 @@ NNG_DECL void nng_http_server_release(nng_http_server *);
 // nng_http_server_start starts the server handling HTTP.  Once this is
 // called, it will not be possible to change certain parameters (such as
 // any TLS configuration).
-NNG_DECL int nng_http_server_start(nng_http_server *);
+NNG_DECL nng_err nng_http_server_start(nng_http_server *);
 
 // nng_http_server_stop stops the server.  No new client connections are
 // accepted after this returns.  Once a server is stopped fully, the
@@ -331,14 +331,14 @@ NNG_DECL void nng_http_server_stop(nng_http_server *);
 // This function will return NNG_EADDRINUSE if a conflicting handler
 // is already registered (i.e. a handler with the same value for Host,
 // Method, and URL.)
-NNG_DECL int nng_http_server_add_handler(
+NNG_DECL nng_err nng_http_server_add_handler(
     nng_http_server *, nng_http_handler *);
 
 // nni_http_del_handler removes the given handler.  The caller is
 // responsible for finalizing it afterwards.  If the handler was not found
 // (not registered), NNG_ENOENT is returned.  In this case it is unsafe
 // to make assumptions about the validity of the handler.
-NNG_DECL int nng_http_server_del_handler(
+NNG_DECL nng_err nng_http_server_del_handler(
     nng_http_server *, nng_http_handler *);
 
 // nng_http_server_set_tls adds a TLS configuration to the server,
@@ -347,36 +347,36 @@ NNG_DECL int nng_http_server_del_handler(
 // server client, so the caller must have configured it reasonably.
 // This API is not recommended unless the caller needs complete control
 // over the TLS configuration.
-NNG_DECL int nng_http_server_set_tls(nng_http_server *, nng_tls_config *);
+NNG_DECL nng_err nng_http_server_set_tls(nng_http_server *, nng_tls_config *);
 
 // nng_http_server_get_tls obtains the TLS configuration if one is present,
 // or returns NNG_EINVAL.  The TLS configuration is invalidated if the
 // nng_http_server_set_tls function is called, so be careful.
-NNG_DECL int nng_http_server_get_tls(nng_http_server *, nng_tls_config **);
+NNG_DECL nng_err nng_http_server_get_tls(nng_http_server *, nng_tls_config **);
 
 // nng_http_server_get_addr obtains the address with which the server was
 // initialized or returns NNG_EINVAL. Useful for instance when the port has
 // been automatically assigned.
-NNG_DECL int nng_http_server_get_addr(nng_http_server *, nng_sockaddr *);
+NNG_DECL nng_err nng_http_server_get_addr(nng_http_server *, nng_sockaddr *);
 
 // nng_http_server_set_error_page sets a custom error page (HTML) content
 // to be sent for the given error code.  This is used when the error is
 // generated internally by the framework.
-NNG_DECL int nng_http_server_set_error_page(
-    nng_http_server *, uint16_t, const char *);
+NNG_DECL nng_err nng_http_server_set_error_page(
+    nng_http_server *, nng_http_status, const char *);
 
 // nng_http_server_set_error_file works like nng_http_server_error_page,
 // except that the content is loaded from the named file path.  The contents
 // are loaded at the time this function is called, so this function should be
 // called anytime the contents of the named file have changed.
-NNG_DECL int nng_http_server_set_error_file(
-    nng_http_server *, uint16_t, const char *);
+NNG_DECL nng_err nng_http_server_set_error_file(
+    nng_http_server *, nng_http_status, const char *);
 
-// nng_http_server_res_error takes replaces the body of the response with
+// nng_http_server_error takes replaces the body of the response with
 // a custom error page previously set for the server, using the status
 // of the response.  The response must have the status set first using
 // nng_http_res_set_status.
-NNG_DECL int nng_http_server_error(nng_http_server *, nng_http *);
+NNG_DECL nng_err nng_http_server_error(nng_http_server *, nng_http *);
 
 // nng_http_hijack is intended to be called by a handler that wishes to
 // take over the processing of the HTTP session -- usually to change protocols
@@ -389,7 +389,7 @@ NNG_DECL int nng_http_server_error(nng_http_server *, nng_http *);
 // of the request structure.  (Some hijackers may keep the request for
 // further processing.)
 
-NNG_DECL int nng_http_hijack(nng_http *);
+NNG_DECL nng_err nng_http_hijack(nng_http *);
 
 // nng_http_client represents a "client" object.  Clients can be used
 // to create HTTP connections.  At present, connections are not cached
@@ -398,7 +398,7 @@ typedef struct nng_http_client nng_http_client;
 
 // nng_http_client_alloc allocates a client object, associated with
 // the given URL.
-NNG_DECL int nng_http_client_alloc(nng_http_client **, const nng_url *);
+NNG_DECL nng_err nng_http_client_alloc(nng_http_client **, const nng_url *);
 
 // nng_http_client_free frees the client.  Connections created by the
 // the client are not necessarily closed.
@@ -408,12 +408,12 @@ NNG_DECL void nng_http_client_free(nng_http_client *);
 // the entire TLS configuration on the client, so the caller must have
 // configured it reasonably.  This API is not recommended unless the
 // caller needs complete control over the TLS configuration.
-NNG_DECL int nng_http_client_set_tls(nng_http_client *, nng_tls_config *);
+NNG_DECL nng_err nng_http_client_set_tls(nng_http_client *, nng_tls_config *);
 
 // nng_http_client_get_tls obtains the TLS configuration if one is present,
 // or returns NNG_EINVAL.  The supplied TLS configuration object may
 // be invalidated by any future calls to nni_http_client_set_tls.
-NNG_DECL int nng_http_client_get_tls(nng_http_client *, nng_tls_config **);
+NNG_DECL nng_err nng_http_client_get_tls(nng_http_client *, nng_tls_config **);
 
 // nng_http_client_connect establishes a new connection with the server
 // named in the URL used when the client was created.  Once the connection