From 9765bdfa9b5c300339ff0a533b9b0e7fe44aef2b Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Wed, 8 Oct 2025 16:06:11 -0700 Subject: More doc fixes for http (link fixes). --- docs/ref/api/http.md | 130 +++++++++++++++++++++++++-------------------------- docs/ref/xref.md | 7 +++ 2 files changed, 72 insertions(+), 65 deletions(-) diff --git a/docs/ref/api/http.md b/docs/ref/api/http.md index 91a3d8d6..772fe2ad 100644 --- a/docs/ref/api/http.md +++ b/docs/ref/api/http.md @@ -121,68 +121,68 @@ then a built in reason based on the _status_ will be used instead. Status codes are defined by the IETF. Here are definitions that NNG provides for convenience: -| Name | Code | Reason Text | Notes | -| ------------------------------------------------------------------------------------------------ | ---- | ------------------------------- | ----------------------------------------------------- | -| `NNG_HTTP_STATUS_CONTINUE` | 100 | Continue | Partial transfer, client may send body. | -| `NNG_HTTP_STATUS_SWITCHING` | 101 | Switching Protocols | Used when upgrading or hijacking a connection. | -| `NNG_HTTP_STATUS_PROCESSING` | 102 | Processing | -| `NNG_HTTP_STATUS_OK` | 200 | OK | Successful result. | -| `NNG_HTTP_STATUS_CREATED` | 201 | Created | Resource created successfully. | -| `NNG_HTTP_STATUS_ACCEPTED` | 202 | Created | Request accepted for future processing. | -| `NNG_HTTP_STATUS_NOT_AUTHORITATIVE` | 203 | Not Authoritative | Request successful, but modified by proxy. | -| `NNG_HTTP_STATUS_NO_CONTENT` | 204 | No Content | Request successful, no content returned. | -| `NNG_HTTP_STATUS_RESET_CONTENT` | 205 | Reset Content | Request successful, client should reload content. | -| `NNG_HTTP_STATUS_PARTIAL_CONTENT` | 206 | Partial Content | Response to a range request. | -| `NNG_HTTP_STATUS_MULTI_STATUS` | 207 | Multi-Status | Used with WebDAV. | -| `NNG_HTTP_STATUS_ALREADY_REPORTED` | 208 | Already Reported | Used with WebDAV. | -| `NNG_HTTP_STATUS_IM_USED` | 226 | IM Used | Used with delta encodings, rarely supported. | -| `NNG_HTTP_STATUS_MULTIPLE_CHOICES` | 300 | Multiple Choices | Multiple responses possible, client should choose. | -| `NNG_HTTP_STATUS_MOVED_PERMANENTLY` | 301 | Moved Permanently | Permanent redirection, may be saved by client. | -| `NNG_HTTP_STATUS_FOUND` | 302 | Found | Temporary redirection, client may switch to GET. | -| `NNG_HTTP_STATUS_SEE_OTHER` | 303 | See Other | Redirect, perhaps after a success POST or PUT. | -| `NNG_HTTP_STATUS_NOT_MODIFIED` | 304 | Not Modified | Resource not modified, client may use cached version. | -| `NNG_HTTP_STATUS_USE_PROXY` | 305 | Use Proxy | -| `NNG_HTTP_STATUS_TEMPORARY_REDIRECT` | 307 | Temporary Redirect | Temporary redirect, preserves method. | -| `NNG_HTTP_STATUS_PERMANENT_REDIRECT` | 308 | Permanent Redirect | Permanent redirect. | -| `NNG_HTTP_STATUS_BAD_REQUEST` | 400 | Bad Request | Generic problem with the request. | -| `NNG_HTTP_STATUS_UNAUTHORIZED` | 401 | Unauthorized | Indicates a problem with authentication. | -| `NNG_HTTP_STATUS_PAYMENT_REQUIRED` | 402 | Payment Required | -| `NNG_HTTP_STATUS_FORBIDDEN` | 403 | Forbidden | No permission to access resource. | -| `NNG_HTTP_STATUS_NOT_FOUND` | 404 | Not Found | Resource does not exist. | -| `NNG_HTTP_STATUS_METHOD_NOT_ALLOWED` | 405 | Method Not Allowed | Resource does not support the method. | -| `NNG_HTTP_STATUS_METHOD_NOT_ACCEPTABLE` | 406 | Not Acceptable | Could not satisfy accept requirements. | -| `NNG_HTTP_STATUS_PROXY_AUTH_REQUIRED` | 407 | Proxy Authentication Required | Proxy requires authentication. | -| `NNG_HTTP_STATUS_REQUEST_TIMEOUT` | 408 | Request Timeout | Timed out waiting for request. | -| `NNG_HTTP_STATUS_CONFLICT` | 409 | Conflict | Conflicting request. | -| `NNG_HTTP_STATUS_GONE` | 410 | Gone | Resource no longer exists. | -| `NNG_HTTP_STATUS_LENGTH_REQUIRED` | 411 | Length Required | Missing Content-Length. | -| `NNG_HTTP_STATUS_PRECONDITION_FAILED` | 412 | Precondition Failed | | -| `NNG_HTTP_STATUS_CONTENT_TOO_LARGE` | 413 | Content Too Large | | -| `NNG_HTTP_STATUS_URI_TOO_LONG` | 414 | URI Too Long | | -| `NNG_HTTP_STATUS_UNSUPPORTED_MEDIA_TYPE` | 415 | Unsupported Media Type | -| `NNG_HTTP_STATUS_RANGE_NOT_SATISFIABLE` | 416 | Range Not Satisfiable | -| `NNG_HTTP_STATUS_EXPECTATION_FAILED` | 417 | Expectation Failed | -| `NNG_HTTP_STATUS_TEAPOT` | 418 | I Am A Teapot | RFC 2324. | -| `NNG_HTTP_STATUS_UNPROCESSABLE_ENTITY` | 422 | Unprocessable Entity | -| `NNG_HTTP_STATUS_LOCKED` | 423 | Locked | -| `NNG_HTTP_STATUS_FAILED_DEPENDENCY` | 424 | Failed Dependency | -| `NNG_HTTP_STATUS_TOO_EARLY` | 425 | Too Early | -| `NNG_HTTP_STATUS_UPGRADE_REQUIRED` | 426 | Upgrade Required | -| `NNG_HTTP_STATUS_PRECONDITION_REQUIRED` | 428 | Precondition Required | | -| `NNG_HTTP_STATUS_TOO_MANY_REQUESTS` | 429 | Too Many Requests | | -| `NNG_HTTP_STATUS_HEADERS_TOO_LARGE` | 431 | Headers Too Large | | -| `NNG_HTTP_STATUS_UNAVAIL_LEGAL_REASONS` | 451 | Unavailable For Legal Reasons | | -| `NNG_HTTP_STATUS_INTERNAL_SERVER_ERROR` | 500 | Internal Server Error | -| `NNG_HTTP_STATUS_NOT_IMPLEMENTED` | 501 | Not Implemented | Server does not implement method. | -| `NNG_HTTP_STATUS_BAD_GATEWAY` | 502 | Bad Gateway | -| `NNG_HTTP_STATUS_SERVICE_UNAVAILALE` | 503 | Service Unavailable | -| `NNG_HTTP_STATUS_GATEWAY_TIMEOUT` | 504 | Gateway TImeout | -| `NNG_HTTP_STATUS_HTTP_VERSION_NOT_SUPP` | 505 | HTTP Version Not Supported | -| `NNG_HTTP_STATUS_VARIANT_ALSO_NEGOTIATES` | 506 | Variant Also Negotiates | -| `NNG_HTTP_STATUS_INSUFFICIENT_STORAGE` | 507 | Variant Also Negotiates | -| `NNG_HTTP_STATUS_LOOP_DETECTED` | 508 | Loop Detected | -| `NNG_HTTP_STATUS_NOT_EXTENDED` | 510 | Not Extended | -| `NNG_HTTP_STATUS_NETWORK_AUTH_REQUIRED` | 511 | Network Authentication Required | +| Name | Code | Reason Text | Notes | +| ----------------------------------------------------------------------------------------------- | ---- | ------------------------------- | ----------------------------------------------------- | +| `NNG_HTTP_STATUS_CONTINUE` | 100 | Continue | Partial transfer, client may send body. | +| `NNG_HTTP_STATUS_SWITCHING` | 101 | Switching Protocols | Used when upgrading or hijacking a connection. | +| `NNG_HTTP_STATUS_PROCESSING` | 102 | Processing | +| `NNG_HTTP_STATUS_OK` | 200 | OK | Successful result. | +| `NNG_HTTP_STATUS_CREATED` | 201 | Created | Resource created successfully. | +| `NNG_HTTP_STATUS_ACCEPTED` | 202 | Created | Request accepted for future processing. | +| `NNG_HTTP_STATUS_NOT_AUTHORITATIVE` | 203 | Not Authoritative | Request successful, but modified by proxy. | +| `NNG_HTTP_STATUS_NO_CONTENT` | 204 | No Content | Request successful, no content returned. | +| `NNG_HTTP_STATUS_RESET_CONTENT` | 205 | Reset Content | Request successful, client should reload content. | +| `NNG_HTTP_STATUS_PARTIAL_CONTENT` | 206 | Partial Content | Response to a range request. | +| `NNG_HTTP_STATUS_MULTI_STATUS` | 207 | Multi-Status | Used with WebDAV. | +| `NNG_HTTP_STATUS_ALREADY_REPORTED` | 208 | Already Reported | Used with WebDAV. | +| `NNG_HTTP_STATUS_IM_USED` | 226 | IM Used | Used with delta encodings, rarely supported. | +| `NNG_HTTP_STATUS_MULTIPLE_CHOICES` | 300 | Multiple Choices | Multiple responses possible, client should choose. | +| `NNG_HTTP_STATUS_MOVED_PERMANENTLY` | 301 | Moved Permanently | Permanent redirection, may be saved by client. | +| `NNG_HTTP_STATUS_FOUND` | 302 | Found | Temporary redirection, client may switch to GET. | +| `NNG_HTTP_STATUS_SEE_OTHER` | 303 | See Other | Redirect, perhaps after a success POST or PUT. | +| `NNG_HTTP_STATUS_NOT_MODIFIED` | 304 | Not Modified | Resource not modified, client may use cached version. | +| `NNG_HTTP_STATUS_USE_PROXY` | 305 | Use Proxy | +| `NNG_HTTP_STATUS_TEMPORARY_REDIRECT` | 307 | Temporary Redirect | Temporary redirect, preserves method. | +| `NNG_HTTP_STATUS_PERMANENT_REDIRECT` | 308 | Permanent Redirect | Permanent redirect. | +| `NNG_HTTP_STATUS_BAD_REQUEST` | 400 | Bad Request | Generic problem with the request. | +| `NNG_HTTP_STATUS_UNAUTHORIZED` | 401 | Unauthorized | Indicates a problem with authentication. | +| `NNG_HTTP_STATUS_PAYMENT_REQUIRED` | 402 | Payment Required | +| `NNG_HTTP_STATUS_FORBIDDEN` | 403 | Forbidden | No permission to access resource. | +| `NNG_HTTP_STATUS_NOT_FOUND` | 404 | Not Found | Resource does not exist. | +| `NNG_HTTP_STATUS_METHOD_NOT_ALLOWED` | 405 | Method Not Allowed | Resource does not support the method. | +| `NNG_HTTP_STATUS_METHOD_NOT_ACCEPTABLE` | 406 | Not Acceptable | Could not satisfy accept requirements. | +| `NNG_HTTP_STATUS_PROXY_AUTH_REQUIRED` | 407 | Proxy Authentication Required | Proxy requires authentication. | +| `NNG_HTTP_STATUS_REQUEST_TIMEOUT` | 408 | Request Timeout | Timed out waiting for request. | +| `NNG_HTTP_STATUS_CONFLICT` | 409 | Conflict | Conflicting request. | +| `NNG_HTTP_STATUS_GONE` | 410 | Gone | Resource no longer exists. | +| `NNG_HTTP_STATUS_LENGTH_REQUIRED` | 411 | Length Required | Missing Content-Length. | +| `NNG_HTTP_STATUS_PRECONDITION_FAILED` | 412 | Precondition Failed | | +| `NNG_HTTP_STATUS_CONTENT_TOO_LARGE` | 413 | Content Too Large | | +| `NNG_HTTP_STATUS_URI_TOO_LONG` | 414 | URI Too Long | | +| `NNG_HTTP_STATUS_UNSUPPORTED_MEDIA_TYPE` | 415 | Unsupported Media Type | +| `NNG_HTTP_STATUS_RANGE_NOT_SATISFIABLE` | 416 | Range Not Satisfiable | +| `NNG_HTTP_STATUS_EXPECTATION_FAILED` | 417 | Expectation Failed | +| `NNG_HTTP_STATUS_TEAPOT` | 418 | I Am A Teapot | RFC 2324. | +| `NNG_HTTP_STATUS_UNPROCESSABLE_ENTITY` | 422 | Unprocessable Entity | +| `NNG_HTTP_STATUS_LOCKED` | 423 | Locked | +| `NNG_HTTP_STATUS_FAILED_DEPENDENCY` | 424 | Failed Dependency | +| `NNG_HTTP_STATUS_TOO_EARLY` | 425 | Too Early | +| `NNG_HTTP_STATUS_UPGRADE_REQUIRED` | 426 | Upgrade Required | +| `NNG_HTTP_STATUS_PRECONDITION_REQUIRED` | 428 | Precondition Required | | +| `NNG_HTTP_STATUS_TOO_MANY_REQUESTS` | 429 | Too Many Requests | | +| `NNG_HTTP_STATUS_HEADERS_TOO_LARGE` | 431 | Headers Too Large | | +| `NNG_HTTP_STATUS_UNAVAIL_LEGAL_REASONS` | 451 | Unavailable For Legal Reasons | | +| `NNG_HTTP_STATUS_INTERNAL_SERVER_ERROR` | 500 | Internal Server Error | +| `NNG_HTTP_STATUS_NOT_IMPLEMENTED` | 501 | Not Implemented | Server does not implement method. | +| `NNG_HTTP_STATUS_BAD_GATEWAY` | 502 | Bad Gateway | +| `NNG_HTTP_STATUS_SERVICE_UNAVAILALE` | 503 | Service Unavailable | +| `NNG_HTTP_STATUS_GATEWAY_TIMEOUT` | 504 | Gateway TImeout | +| `NNG_HTTP_STATUS_HTTP_VERSION_NOT_SUPP` | 505 | HTTP Version Not Supported | +| `NNG_HTTP_STATUS_VARIANT_ALSO_NEGOTIATES` | 506 | Variant Also Negotiates | +| `NNG_HTTP_STATUS_INSUFFICIENT_STORAGE` | 507 | Variant Also Negotiates | +| `NNG_HTTP_STATUS_LOOP_DETECTED` | 508 | Loop Detected | +| `NNG_HTTP_STATUS_NOT_EXTENDED` | 510 | Not Extended | +| `NNG_HTTP_STATUS_NETWORK_AUTH_REQUIRED` | 511 | Network Authentication Required | ### Retrieving Headers @@ -532,7 +532,7 @@ 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_data`]. +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 @@ -555,7 +555,7 @@ necessarily be usable with other transactions. 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 @@ -683,7 +683,7 @@ URI appended. > [!TIP] > Be sure to use the appropriate value for _status_. -> Permanent redirection should use [`NNG_HTTP_STATUS_STATUS_MOVED_PERMANENTLY`] (301) +> 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). diff --git a/docs/ref/xref.md b/docs/ref/xref.md index 57964123..14b9303d 100644 --- a/docs/ref/xref.md +++ b/docs/ref/xref.md @@ -302,6 +302,8 @@ [`nng_http_handler_set_host`]: /api/http.md#filtering-byt-host [`nng_http_handler_set_method`]: /api/http.md#setting-the-method [`nng_http_handler_set_data`]: /api/http.md#setting-the-callback-argument +[`nng_http_handler_set_tree`]: /api/http.md#handling-an-entire-tree +[`nng_http_transact`]: /api/http.md#submitting-the-transaction @@ -366,6 +368,11 @@ [`NNG_HTTP_STATUS_NOT_EXTENDED`]: /api/http.md#NNG_HTTP_STATUS_NOT_EXTENDED [`NNG_HTTP_STATUS_NETWORK_AUTH_REQUIRED`]: /api/http.md#NNG_HTTP_STATUS_NETWORK_AUTH_REQUIRED + + +[`nng_tls_cert`]: /TODO.md +[`nng_tls_cert_free`]: /TODO.md + [`NNG_OK`]: /api/errors.md#NNG_OK -- cgit v1.2.3-70-g09d2