From 25490a300910e357ac864a1916a4285e239fbf30 Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Sat, 29 Sep 2018 21:55:31 -0700 Subject: fixes #738 http server needs a way to collect request entity data --- docs/man/libnng.3.adoc | 1 + docs/man/nng_http_handler_alloc.3http.adoc | 1 + docs/man/nng_http_handler_collect_body.3http.adoc | 78 +++++++++++++++++++++++ 3 files changed, 80 insertions(+) create mode 100644 docs/man/nng_http_handler_collect_body.3http.adoc (limited to 'docs') diff --git a/docs/man/libnng.3.adoc b/docs/man/libnng.3.adoc index 0a62f931..25e8b08d 100644 --- a/docs/man/libnng.3.adoc +++ b/docs/man/libnng.3.adoc @@ -356,6 +356,7 @@ These functions are intended for use with HTTP server applications. |=== |<>|allocate HTTP server handler +|<>|set HTTP handler to collect request body |<>|free HTTP server handler |<>|return extra data for HTTP handler |<>|set extra data for HTTP handler diff --git a/docs/man/nng_http_handler_alloc.3http.adoc b/docs/man/nng_http_handler_alloc.3http.adoc index 523b5328..d5861d14 100644 --- a/docs/man/nng_http_handler_alloc.3http.adoc +++ b/docs/man/nng_http_handler_alloc.3http.adoc @@ -149,6 +149,7 @@ This function returns 0 on success, and non-zero otherwise. <>, <>, <>, +<>, <>, <>, <>, diff --git a/docs/man/nng_http_handler_collect_body.3http.adoc b/docs/man/nng_http_handler_collect_body.3http.adoc new file mode 100644 index 00000000..875f32c4 --- /dev/null +++ b/docs/man/nng_http_handler_collect_body.3http.adoc @@ -0,0 +1,78 @@ += nng_http_handler_collect_body(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_collect_body - set HTTP handler to collect request body + +== SYNOPSIS + +[source, c] +---- +#include +#include + +int nng_http_handler_collect_body(nng_http_handler *handler, bool want, size_t maxsz); +---- + +== DESCRIPTION + +The `nng_http_handler_collect_data()` function causes the _handler_ to +collect any request body that was submitted with the request, and attach +it to the `nng_http_req` before the handler is called. + +Subsequently the data can be retrieved by the handler from the request with the +`<>` 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 a 400 "`Bad Request`" status. + +TIP: Limiting the size of incoming request data can provide protection +against denial of service attacks, as a buffer of the client-supplied +size must be allocated to receive the data. + +In order to provide an unlimited size, use `(size_t)-1` for _maxsz_. +The value `0` for _maxsz_ can be used to prevent any data from being passed +by the client. + +The built-in handlers for files, directories, and static data limit the +_maxsz_ to zero by default. +Otherwise the default setting is to enable this capability with a default +value of _maxsz_ of 1 megabyte. + +NOTE: The handler looks for data indicated by the `Content-Length:` HTTP +header. +If this header is absent, the request is assumed not to contain any data. + +NOTE: This specifically does not support the `Chunked` transfer-encoding. +This is considered a bug, and is a deficiency for full HTTP/1.1 compliance. +However, few clients send data in this format, so in practice this should +not create few limitations. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +[horizontal] +`NNG_ENOTSUP`:: No support for HTTP in the library. + +== SEE ALSO + +[.text-left] +<>, +<>, +<>, +<> -- cgit v1.2.3-70-g09d2