From 6d74a90b72c80edbd58d8b2b29105e749bdfc28e Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Fri, 17 Jan 2025 05:49:14 -0800 Subject: http: handler API clean ups --- docs/man/nng_http_handler_free.3http.adoc | 47 --------- docs/ref/api/http.md | 157 ++++++++++++++++-------------- docs/ref/xref.md | 5 + 3 files changed, 91 insertions(+), 118 deletions(-) delete mode 100644 docs/man/nng_http_handler_free.3http.adoc (limited to 'docs') diff --git a/docs/man/nng_http_handler_free.3http.adoc b/docs/man/nng_http_handler_free.3http.adoc deleted file mode 100644 index 0e1a5b1c..00000000 --- a/docs/man/nng_http_handler_free.3http.adoc +++ /dev/null @@ -1,47 +0,0 @@ -= nng_http_handler_free(3http) -// -// Copyright 2018 Staysail Systems, Inc. -// Copyright 2018 Capitar IT Group BV -// -// This document is supplied under the terms of the MIT License, a -// copy of which should be located in the distribution where this -// file was obtained (LICENSE.txt). A copy of the license may also be -// found online at https://opensource.org/licenses/MIT. -// - -== NAME - -nng_http_handler_free - free HTTP server handler - -== SYNOPSIS - -[source, c] ----- -#include -#include - -void nng_http_handler_free(nng_http_handler *h); ----- - -== DESCRIPTION - -The `nng_http_handler_free()` function frees an allocated HTTP server handler. - -IMPORTANT: It is an error to free a handler that is registered with a server. -Any handlers that are registered with servers are automatically freed -when the server itself is deallocated. - -== RETURN VALUES - -None. - -== ERRORS - -None. - -== SEE ALSO - -[.text-left] -xref:nng_http_handler_alloc.3http.adoc[nng_http_handler_alloc(3http)], -xref:nng_http_server_add_handler.3http.adoc[nng_http_server_add_handler(3http)], -xref:nng.7.adoc[nng(7)] diff --git a/docs/ref/api/http.md b/docs/ref/api/http.md index 8cb1945e..bec22f1b 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 defininitions 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 | Unavailabe 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 | Unavailabe 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 @@ -578,6 +578,7 @@ typedef void (*nng_http_hander_func)(nng_http_conn *conn, void *arg, nng_aio *ai nng_err nng_http_handler_alloc(nng_http_handler **hp, const char *path, nng_http_handler_func cb); ``` + The {{i:`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_. @@ -615,26 +616,27 @@ The _aio_ may be scheduled for deferred completion using the [`nng_aio_start`]. ### Serving Directories and Files ```c -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); +nng_err nng_http_handler_directory(nng_http_handler **hp, const char *path, const char *dirname); +nng_err nng_http_handler_file(nng_http_handler **hp, const char *path, const char *filename, const char *ctype); ``` -The {{i:`nng_http_handler_alloc_directory`}} and {{i:`nng_http_handler_alloc_file`}} +The {{i:`nng_http_handler_directory`}} and {{i:`nng_http_handler_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 the directory contents. These will also set the "Content-Type" if the file extension -matches one of the built-in values already known. If the no suitable MIME type can be -determined, the content type is set to "application/octet-stream". +matches one of the built-in values already known and _ctype_ is `NULL`. +If _ctype_ is not `NULL`, then the "Content-Type" is set to its value. +Otherwise, if no suitable MIME type can be determined, the content type is set to "application/octet-stream". ### Static Handler ```c -nng_err nng_http_handler_alloc_static(nng_http_handler **hp, const char *path, +nng_err nng_http_handler_static(nng_http_handler **hp, const char *path, const void *data, size_t size, const char *content_type); ``` -The {{i:`nng_http_handler_alloc_static`}} function creates a handler that +The {{i:`nng_http_handler_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. @@ -642,11 +644,11 @@ then a value of `application/octet-stream` is assumed. ### Redirect Handler ```c -nng_err nng_http_handler_alloc_redirect(nng_http_handler **hp, const char *path, +nng_err nng_http_handler_redirect(nng_http_handler **hp, const char *path, nng_http_status status, const char *location); ``` -The {{i:`nng_http_handler_alloc_redirect`}} function creates a handler with +The {{i:`nng_http_handler_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_, @@ -779,6 +781,19 @@ the path to pass additional parameters. > service address (path) supports dynamically generated children. > It can also provide a logical fallback instead of relying on a 404 error code. +### Destroying a Handler + +```c +void nng_http_handler_free(nng_http_handler *handler); +``` + +The {{i:`nng_http_handler_free`}} function can be called to destroy a handler. + +> [!TIP] +> This function should not normally be needed, unless a the handler cannot be +> added to a server. Once the handler is taken over by the server, it is owned +> by the server and the server will dispose of it when it is removed or the server is destroyed. + ### Sending the Response Explicitly ```c diff --git a/docs/ref/xref.md b/docs/ref/xref.md index e3b57585..32523c77 100644 --- a/docs/ref/xref.md +++ b/docs/ref/xref.md @@ -294,6 +294,11 @@ [`nng_http_read_all`]: /api/http.md#direct-read-and-write [`nng_http_write`]: /api/http.md#direct-read-and-write [`nng_http_write_all`]: /api/http.md#direct-read-and-write +[`nng_http_handler_alloc`]: /api/http.md#nng_http_handler_alloc +[`nng_http_handler_static`]: /api/http.md#nng_http_handler_static +[`nng_http_handler_redirect`]: /api/http.md#nng_http_handler_redirect +[`nng_http_handler_file`]: /api/http.md#nng_http_handler_file +[`nng_http_handler_directory`]: /api/http.md#nng_http_handler_directory -- cgit v1.2.3-70-g09d2