From 3b33f6878ee628da22fd4451f248c036aae231ed Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Mon, 5 Feb 2018 15:27:31 -0800 Subject: Inital swag at HTTP handler docs. We will need to document nng_aio_set_output, and both document and create an nng_aio_finish() function. --- docs/libnng.adoc | 37 +++++++++- docs/nng_http_conn_write_res.adoc | 9 +++ docs/nng_http_handler_alloc.adoc | 137 ++++++++++++++++++++++++++++++++++++++ 3 files changed, 182 insertions(+), 1 deletion(-) create mode 100644 docs/nng_http_handler_alloc.adoc (limited to 'docs') diff --git a/docs/libnng.adoc b/docs/libnng.adoc index 37bc01c8..6ecf406b 100644 --- a/docs/libnng.adoc +++ b/docs/libnng.adoc @@ -14,7 +14,7 @@ libnng - nanomsg next generation library == SYNOPSIS -*cc* ['flags'] 'files' *-lnng* ['libraries'] +*cc* [_flags_] _files_ *-lnng* [_libraries_] == DESCRIPTION @@ -230,6 +230,41 @@ and connections. | <>|set HTTP response protocol version |=== +==== HTTP Client Functions + +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 +|=== + +==== HTTP Server Functions + +These functions are intended for use with HTTP server applications. + +|=== +| <>|allocate HTTP server handler +| <>|free HTTP server handler +| <>|return extra data for HTTP handler +| <>|set extra data for HTTP handler +| <>|set host for HTTP handler +| <>|set method for HTTP handler +| <>|set HTTP handler to match trees +| <>|hijack HTTP server connection +| <>|add HTTP server handler +| <>|delete HTTP server handler +| <>|get HTTP server TLS configuration +| <>|get and hold HTTP server instance +| <>|release HTTP server instance +| <>|set HTTP server TLS configuration +| <>|start HTTP server +| <>|stop HTTP server +|=== + === TLS Configuration Objects The following functions are used to manipulate transport layer security diff --git a/docs/nng_http_conn_write_res.adoc b/docs/nng_http_conn_write_res.adoc index 8f5a407d..31e438b4 100644 --- a/docs/nng_http_conn_write_res.adoc +++ b/docs/nng_http_conn_write_res.adoc @@ -37,6 +37,15 @@ 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. +=== Persistent Connections + +By default, for `HTTP/1.1` connections, the connection is kept open, and +will be reused to receive new requests. + +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. + == RETURN VALUES None. diff --git a/docs/nng_http_handler_alloc.adoc b/docs/nng_http_handler_alloc.adoc new file mode 100644 index 00000000..cde5b052 --- /dev/null +++ b/docs/nng_http_handler_alloc.adoc @@ -0,0 +1,137 @@ += nng_http_handler_alloc(3) +:doctype: manpage +:manmanual: nng +:mansource: nng +:manvolnum: 3 +:copyright: Copyright 2018 mailto:info@staysail.tech[Staysail Systems, Inc.] + \ + Copyright 2018 mailto:info@capitar.com[Capitar IT Group BV] + \ + {blank} + \ + This document is supplied under the terms of the \ + https://opensource.org/licenses/MIT[MIT License]. + +== NAME + +nng_http_handler_alloc - allocate HTTP server handler + +== SYNOPSIS + +[source, c] +----------- +#include + +typedef struct nng_http_handler nng_http_handler; + +int nng_http_handler_alloc(nng_http_handler **hp, const char *path, + void (*func)(nng_aio *); +int nng_http_handler_alloc_directory(nng_http_handler **hp, const char *path, + const char *dirname); +int nng_http_handler_alloc_file(nng_http_handler **hp, const char *path, + const char *filename); +int nng_http_handler_alloc_static(nng_http_handler **hp, const char *path, + const void *data, size_t size, const char *content_type); +----------- + + +== DESCRIPTION + +The `nng_http_handler_alloc()` family of functions allocate a 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_. + +Every handler has a Request-URI to which it refers, which is determined +by the _path_ argument. Only the path component of the Request URI is +considered. + +In some cases, a handler may reference a logical tree rather (directory) +rather than just a single element. +(See <>). + +=== Custom Handler + +The generic (first) form of this creates a handler that uses a user-supplied +function to process HTTP requests. This function uses the asynchronous I/O +framework. The function takes a pointer to an `nng_aio` structure. That +structure will be passed with the following input values (retrieved with +<>): + + 0: ``nng_http_req *`` __request__:: The client's HTTP request. + 1: ``nng_http_handler *``__handler__:: Pointer to the handler object. + 2: ``nng_http_conn *``__conn__:: The underlying HTTP connection. + +The handler should create an `nng_http_res *` response (such as via +<> or +<>) and store that +in as the first output (index 0) with +<>. + +Alternatively, the handler may send the HTTP response (and any associated +body data) itself using the connection. In that case the output at index +0 of the _aio_ should be NULL. + +Finally, using the <> function, the +_aio_ should be completed successfully. If any non-zero status is returned +back to the caller instead, then a generic 500 response will be created and +sent, if possible, and the connection will be closed. + +=== Directory Handler + +The second member of this family, `nng_http_handler_alloc_directory()`, creates +a handler configured to serve a directory tree. The _uri_ is taken as +the root, and files are served from the directory tree rooted at _path_. + +When the client Request-URI resolves to a directory in the filesystem, +the handler looks first for a file named `index.html` or `index.htm`. If +one is found, then that file is returned back to the client. If no such +index file exists, then an `NNG_HTTP_STATUS_NOT_FOUND` (404) error is +sent back to the client. + +The `Content-Type` will be set automatically based upon the extension +of the requsted file name. If a content type cannot be determined from +the extension, then `application/octet-stream` is used. + +=== File Handler + +The third member of this family, `nng_http_handler_alloc_file()`, creates +a handler to serve up a single file; it does not traverse directories +or search for `index.html` or `index.htm` files. + +The `Content-Type` will be set automatically based upon the extension +of the requsted file name. If a content type cannot be determined from +the extension, then `application/octet-stream` is used. + +=== Static Handler + +The fourth member of this family, `nng_http_handler_alloc_static()`, creates +a handler to serve up fixed content located in program data. The client is +sent the _data_, with `Content-Length` of _size_ bytes, and `Content-Type` of +__content_type__. + +== RETURN VALUES + +This function returns 0 on success, and non-zero otherwise. + +== ERRORS + +`NNG_ENOMEM`:: Insufficient free memory exists to allocate a message. +`NNG_ENOTSUP`:: HTTP support not configured. +`NNG_EINVAL`:: An invalid _path_ was specified. + +== SEE ALSO + +<>, +<>, +<>, +<>, +<>, +<>, +<>, +<>, +<>, +<>, +<>, +<> + +== COPYRIGHT + +{copyright} -- cgit v1.2.3-70-g09d2