From 0cc96c69b3fce09a9c4a8d467d17cfbda76bc02f Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Thu, 30 Aug 2018 14:23:39 -0700 Subject: fixes #681 HTTP convenience GET method desired... This adds a couple of new methods, and related documentation and test cases. --- docs/man/CMakeLists.txt | 4 ++ docs/man/libnng.3.adoc | 16 +++-- docs/man/nng_http_client_transact.3http.adoc | 89 +++++++++++++++++++++++++ docs/man/nng_http_conn_read_res.3http.adoc | 8 +++ docs/man/nng_http_conn_transact.3http.adoc | 98 ++++++++++++++++++++++++++++ docs/man/nng_http_conn_write_req.3http.adoc | 8 +++ docs/man/nng_http_conn_write_res.3http.adoc | 8 +++ docs/man/nng_http_req_get_data.3http.adoc | 50 ++++++++++++++ docs/man/nng_http_res_get_data.3http.adoc | 50 ++++++++++++++ 9 files changed, 325 insertions(+), 6 deletions(-) create mode 100644 docs/man/nng_http_client_transact.3http.adoc create mode 100644 docs/man/nng_http_conn_transact.3http.adoc create mode 100644 docs/man/nng_http_req_get_data.3http.adoc create mode 100644 docs/man/nng_http_res_get_data.3http.adoc (limited to 'docs/man') diff --git a/docs/man/CMakeLists.txt b/docs/man/CMakeLists.txt index af644a62..21651ba5 100644 --- a/docs/man/CMakeLists.txt +++ b/docs/man/CMakeLists.txt @@ -198,11 +198,13 @@ if (NNG_ENABLE_DOC) nng_http_client_free nng_http_client_get_tls nng_http_client_set_tls + nng_http_client_transact nng_http_conn_close nng_http_conn_read nng_http_conn_read_all nng_http_conn_read_req nng_http_conn_read_res + nng_http_conn_transact nng_http_conn_write nng_http_conn_write_all nng_http_conn_write_req @@ -220,6 +222,7 @@ if (NNG_ENABLE_DOC) nng_http_req_copy_data nng_http_req_del_header nng_http_req_free + nng_http_req_get_data nng_http_req_get_header nng_http_req_get_method nng_http_req_get_uri @@ -235,6 +238,7 @@ if (NNG_ENABLE_DOC) nng_http_res_copy_data nng_http_res_del_header nng_http_res_free + nng_http_res_get_data nng_http_res_get_header nng_http_res_get_reason nng_http_res_get_status diff --git a/docs/man/libnng.3.adoc b/docs/man/libnng.3.adoc index 23306997..3e3037f9 100644 --- a/docs/man/libnng.3.adoc +++ b/docs/man/libnng.3.adoc @@ -287,6 +287,7 @@ and connections. |<>|copy HTTP request body |<>|delete HTTP request header |<>|free HTTP request structure +|<>|get HTTP request body |<>|return HTTP request header |<>|return HTTP request method |<>|return HTTP request URI @@ -302,11 +303,12 @@ and connections. |<>|copy HTTP response body |<>|delete HTTP response header |<>|free HTTP response structure -|<>|set HTTP response body +|<>|get HTTP response body |<>|return HTTP response header |<>|return HTTP response reason |<>|return HTTP response status |<>|return HTTP response protocol version +|<>|set HTTP response body |<>|set HTTP response header |<>|set HTTP response reason |<>|set HTTP response status @@ -318,11 +320,13 @@ and connections. These functions are intended for use with HTTP client applications. |=== -| <>|allocate HTTP client -| <>|establish HTTP client connection -| <>|free HTTP client -| <>|get HTTP client TLS configuration -| <>|set HTTP client TLS configuration +|<>|allocate HTTP client +|<>|establish HTTP client connection +|<>|free HTTP client +|<>|get HTTP client TLS configuration +|<>|set HTTP client TLS configuration +|<>|perform one HTTP transaction +|<>|perform one HTTP transaction on connection |=== ==== HTTP Server Functions diff --git a/docs/man/nng_http_client_transact.3http.adoc b/docs/man/nng_http_client_transact.3http.adoc new file mode 100644 index 00000000..a469dc50 --- /dev/null +++ b/docs/man/nng_http_client_transact.3http.adoc @@ -0,0 +1,89 @@ += nng_http_client_transact(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_client_transact - perform one HTTP transaction + +== SYNOPSIS + +[source, c] +---- +#include +#include + +void nng_http_client_transact(nng_http_client *client, nng_http_req *req, + nng_http_res *res, nng_aio *aio); +---- + +== DESCRIPTION + +The `nng_http_client_transact()` function is used to perform a complete +HTTP exchange. +It creates a new connection using _client_, performs the transaction by +sending the request _req_ +(and attached body data) to the remote server, then reading the response +_res_, and finally closes the connection that it created. +The entire response is read, including any associated body, which can +subsequently be obtained using +`<>`. + +This function is intended to make creation of client applications easier, +by performing multiple asynchronous operations required to complete an +entire HTTP transaction. + +A similar function, +`<>`, +exists. +That function behaves similarily, but uses an existing connection, which +can be reused. + +NOTE: This function does not support reading data sent using chunked +transfer encoding, and if the server attempts to do so, the underlying +connection will be closed and an `NNG_ENOTSUP` error will be returned. +This limitation is considered a bug, and a fix is planned for the future. + +WARNING: If the remote server tries to send an extremely large buffer, +then a corresponding allocation will be made, which can lead to denial +of service attacks. +Client applications should take care to use this only with reasonably +trust-worthy servers. + +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 `<>`. +That result will either be zero or an error code. + +== RETURN VALUES + +None. + +== ERRORS + +[horizontal] +`NNG_ECANCELED`:: The operation was canceled. +`NNG_ECLOSED`:: The connection was closed. +`NNG_ECONNRESET`:: The peer closed the connection. +`NNG_ENOMEM`:: Insufficient free memory to perform the operation. +`NNG_ENOTSUP`:: HTTP operations are not supported, or peer sent chunked encoding. +`NNG_EPROTO`:: An HTTP protocol error occurred. +`NNG_ETIMEDOUT`:: Timeout waiting for data from the connection. + +== SEE ALSO + +[.text-left] +<>, +<>, +<>, +<>, +<>, +<>, +<> diff --git a/docs/man/nng_http_conn_read_res.3http.adoc b/docs/man/nng_http_conn_read_res.3http.adoc index 4e2f2713..96e64ed6 100644 --- a/docs/man/nng_http_conn_read_res.3http.adoc +++ b/docs/man/nng_http_conn_read_res.3http.adoc @@ -42,6 +42,12 @@ the operation is signaled via the _aio_, and the final result may be obtained via `<>`. That result will either be zero or an error code. +NOTE: Consider using the +`<>` or +`<>` functions, +which provide a simpler interface for performing a complete HTTP client +transaction. + == RETURN VALUES None. @@ -63,5 +69,7 @@ None. <>, <>, <>, +<>, +<>, <>, <> diff --git a/docs/man/nng_http_conn_transact.3http.adoc b/docs/man/nng_http_conn_transact.3http.adoc new file mode 100644 index 00000000..bd41f659 --- /dev/null +++ b/docs/man/nng_http_conn_transact.3http.adoc @@ -0,0 +1,98 @@ += nng_http_conn_transact(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_conn_transact - perform one HTTP transaction on connection + +== SYNOPSIS + +[source, c] +---- +#include +#include + +void nng_http_conn_transact(nng_http_conn *conn, nng_http_req *req, + nng_http_res *res, nng_aio *aio); +---- + +== DESCRIPTION + +The `nng_http_conn_transact()` function is used to perform a complete +HTTP exchange over the connection _conn_, sending the request _req_ +(and attached body data) to the remote server, and reading the response +_res_. +The entire response is read, including any associated body, which can +subsequently be obtained using +`<>`. + +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 +`<>`, as it may not +necessarily be usable with other transactions. + +A similar function, +`<>`, +exists. +That function behaves similarily, but creates a connection on demand +for the transaction, and disposes of it when finished. + +NOTE: This function does not support reading data sent using chunked +transfer encoding, and if the server attempts to do so, the underlying +connection will be closed and an `NNG_ENOTSUP` error will be returned. +This limitation is considered a bug, and a fix is planned for the future. + +WARNING: If the remote server tries to send an extremely large buffer, +then a corresponding allocation will be made, which can lead to denial +of service attacks. +Client applications should take care to use this only with reasonably +trust-worthy servers. + +WARNING: A given connection _conn_ should be used with only one +operation or transaction at a time as HTTP/1.1 has no support for +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 `<>`. +That result will either be zero or an error code. + +== RETURN VALUES + +None. + +== ERRORS + +[horizontal] +`NNG_ECANCELED`:: The operation was canceled. +`NNG_ECLOSED`:: The connection was closed. +`NNG_ECONNRESET`:: The peer closed the connection. +`NNG_ENOMEM`:: Insufficient free memory to perform the operation. +`NNG_ENOTSUP`:: HTTP operations are not supported, or peer sent chunked encoding. +`NNG_EPROTO`:: An HTTP protocol error occurred. +`NNG_ETIMEDOUT`:: Timeout waiting for data from the connection. + +== SEE ALSO + +[.text-left] +<>, +<>, +<>, +<>, +<>, +<>, +<>, +<>, +<>, +<> diff --git a/docs/man/nng_http_conn_write_req.3http.adoc b/docs/man/nng_http_conn_write_req.3http.adoc index 0384e7b1..338ab26d 100644 --- a/docs/man/nng_http_conn_write_req.3http.adoc +++ b/docs/man/nng_http_conn_write_req.3http.adoc @@ -39,6 +39,12 @@ Completion of the operation is signaled via the _aio_, and the final result may be obtained via `<>`. That result will either be zero or an error code. +NOTE: Consider using the +`<>` or +`<>` functions, +which provide a simpler interface for performing a complete HTTP client +transaction. + == RETURN VALUES None. @@ -59,6 +65,8 @@ None. <>, <>, <>, +<>, <>, +<>, <>, <> diff --git a/docs/man/nng_http_conn_write_res.3http.adoc b/docs/man/nng_http_conn_write_res.3http.adoc index 2bab9a31..62d7a3d1 100644 --- a/docs/man/nng_http_conn_write_res.3http.adoc +++ b/docs/man/nng_http_conn_write_res.3http.adoc @@ -48,6 +48,12 @@ If however the _res_ contains a header of `Connection:` with a value of `Close` (case-insensitive) or the response corresponds to `HTTP/1.0`, then the connection is immediately after sending the response. +NOTE: Consider using the +`<>` or +`<>` functions, +which provide a simpler interface for performing a complete HTTP client +transaction. + == RETURN VALUES None. @@ -68,6 +74,8 @@ None. <>, <>, <>, +<>, <>, +<>, <>, <> diff --git a/docs/man/nng_http_req_get_data.3http.adoc b/docs/man/nng_http_req_get_data.3http.adoc new file mode 100644 index 00000000..cd5c076e --- /dev/null +++ b/docs/man/nng_http_req_get_data.3http.adoc @@ -0,0 +1,50 @@ += nng_http_req_get_data(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_req_get_data - get HTTP request body + +== SYNOPSIS + +[source, c] +---- +#include +#include + +void nng_http_req_get_data(nng_http_req *req, void **bodyp, size_t *sizep); +---- + +== DESCRIPTION + +The `nng_http_req_get_data()` gets the HTTP body associated with +the request _req_, storing a pointer to the buffer at the location referenced +by _bodyp_, and the length of the associated buffer at the location referenced +by _sizep_. + +NOTE: The buffer returned is owned by _req_, and will automatically freed +when the request is freed. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +<>, +<>, +<>, +<> diff --git a/docs/man/nng_http_res_get_data.3http.adoc b/docs/man/nng_http_res_get_data.3http.adoc new file mode 100644 index 00000000..44f98c1f --- /dev/null +++ b/docs/man/nng_http_res_get_data.3http.adoc @@ -0,0 +1,50 @@ += nng_http_res_get_data(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_res_get_data - get HTTP response body + +== SYNOPSIS + +[source, c] +---- +#include +#include + +void nng_http_res_get_data(nng_http_res *res, void **bodyp, size_t *sizep); +---- + +== DESCRIPTION + +The `nng_http_res_get_data()` gets the HTTP body associated with +the request _res_, storing a pointer to the buffer at the location referenced +by _bodyp_, and the length of the associated buffer at the location referenced +by _sizep_. + +NOTE: The buffer returned is owned by _res_, and will automatically freed +when the request is freed. + +== RETURN VALUES + +None. + +== ERRORS + +None. + +== SEE ALSO + +[.text-left] +<>, +<>, +<>, +<> -- cgit v1.2.3-70-g09d2