fixes #173 Define public HTTP server API

This introduces enough of the HTTP API to support fully server
applications, including creation of websocket style protocols,
pluggable handlers, and so forth.

We have also introduced scatter/gather I/O (rudimentary) for
aios, and made other enhancements to the AIO framework.  The
internals of the AIOs themselves are now fully private, and we
have eliminated the aio->a_addr member, with plans to remove the
pipe and possibly message members as well.

A few other minor issues were found and fixed as well.

The HTTP API includes request, response, and connection objects,
which can be used with both servers and clients.  It also defines
the HTTP server and handler objects, which support server applications.

Support for client applications will require a client object to be
exposed, and that should be happening shortly.

None of this is "documented" yet, bug again, we will follow up shortly.

1 files changed, 433 insertions, 0 deletions

diff --git a/src/nng.h b/src/nng.h
index 24689f96..47cd3bcc 100644
--- a/src/nng.h
+++ b/src/nng.h
@@ -252,6 +252,11 @@ NNG_DECL void nng_free(void *, size_t);
 // support asynchronous operations.  They contain the completion callback, and
 // a pointer to consumer data.  This is similar to how overlapped I/O
 // works in Windows, when used with a completion callback.
+//
+// AIO structures can carry up to 4 distinct input values, and up to
+// 4 distinct output values, and up to 4 distinct "private state" values.
+// The meaning of the inputs and the outputs are determined by the
+// I/O functions being called.
 
 // nng_aio_alloc allocates a new AIO, and associated the completion
 // callback and its opaque argument.  If NULL is supplied for the
@@ -277,11 +282,20 @@ NNG_DECL void nng_aio_stop(nng_aio *);
 // failure.
 NNG_DECL int nng_aio_result(nng_aio *);
 
+// nng_aio_count returns the number of bytes transferred for certain
+// I/O operations.  This is meaningless for other operations (e.g.
+// DNS lookups or TCP connection setup).
+NNG_DECL size_t nng_aio_count(nng_aio *);
+
 // nng_aio_cancel attempts to cancel any in-progress I/O operation.
 // The AIO callback will still be executed, but if the cancellation is
 // successful then the status will be NNG_ECANCELED.
 NNG_DECL void nng_aio_cancel(nng_aio *);
 
+// nng_aio_abort is like nng_aio_cancel, but allows for a different
+// error result to be returned.
+NNG_DECL void nng_aio_abort(nng_aio *, int);
+
 // nng_aio_wait waits synchronously for any pending operation to complete.
 // It also waits for the callback to have completed execution.  Therefore,
 // the caller of this function must not hold any locks acquired by the
@@ -296,6 +310,26 @@ NNG_DECL void nng_aio_set_msg(nng_aio *, nng_msg *);
 // receive operation.
 NNG_DECL nng_msg *nng_aio_get_msg(nng_aio *);
 
+// nng_aio_set_input sets an input parameter at the given index.
+NNG_DECL int nng_aio_set_input(nng_aio *, unsigned, void *);
+
+// nng_aio_get_input retrieves the input parameter at the given index.
+NNG_DECL void *nng_aio_get_input(nng_aio *, unsigned);
+
+// nng_aio_set_output sets an output result at the given index.
+NNG_DECL int nng_aio_set_output(nng_aio *, unsigned, void *);
+
+// nng_aio_get_output retrieves the output result at the given index.
+NNG_DECL void *nng_aio_get_output(nng_aio *, unsigned);
+
+// nng_aio_set_data sets an opaque data at the given index.  The intention
+// is to allow consumers to pass additional state for use in callback
+// functions.
+NNG_DECL int nng_aio_set_data(nng_aio *, unsigned, void *);
+
+// nng_aio_get_data retrieves the data that was previously stored.
+NNG_DECL void *nng_aio_get_output(nng_aio *, unsigned);
+
 // nng_aio_set_timeout sets a timeout on the AIO.  This should be called for
 // operations that should time out after a period.  The timeout should be
 // either a positive number of milliseconds, or NNG_DURATION_INFINITE to
@@ -751,6 +785,405 @@ NNG_DECL void nng_url_free(nng_url *);
 // nng_url_clone clones a URL structure.
 NNG_DECL int nng_url_clone(nng_url **, const nng_url *);
 
+// HTTP API.  Only present if HTTP support compiled into the library.
+// Functions will return NNG_ENOTSUP (or NULL or 0 as appropriate)
+// if the library lacks support for HTTP.
+
+// HTTP status codes.  This list is not exhaustive.
+enum nng_http_status {
+	NNG_HTTP_STATUS_CONTINUE                 = 100,
+	NNG_HTTP_STATUS_SWITCHING                = 101,
+	NNG_HTTP_STATUS_PROCESSING               = 102,
+	NNG_HTTP_STATUS_OK                       = 200,
+	NNG_HTTP_STATUS_CREATED                  = 201,
+	NNG_HTTP_STATUS_ACCEPTED                 = 202,
+	NNG_HTTP_STATUS_NOT_AUTHORITATIVE        = 203,
+	NNG_HTTP_STATUS_NO_CONTENT               = 204,
+	NNG_HTTP_STATUS_RESET_CONTENT            = 205,
+	NNG_HTTP_STATUS_PARTIAL_CONTENT          = 206,
+	NNG_HTTP_STATUS_MULTI_STATUS             = 207,
+	NNG_HTTP_STATUS_ALREADY_REPORTED         = 208,
+	NNG_HTTP_STATUS_IM_USED                  = 226,
+	NNG_HTTP_STATUS_MULTIPLE_CHOICES         = 300,
+	NNG_HTTP_STATUS_STATUS_MOVED_PERMANENTLY = 301,
+	NNG_HTTP_STATUS_FOUND                    = 302,
+	NNG_HTTP_STATUS_SEE_OTHER                = 303,
+	NNG_HTTP_STATUS_NOT_MODIFIED             = 304,
+	NNG_HTTP_STATUS_USE_PROXY                = 305,
+	NNG_HTTP_STATUS_TEMPORARY_REDIRECT       = 307,
+	NNG_HTTP_STATUS_PERMANENT_REDIRECT       = 308,
+	NNG_HTTP_STATUS_BAD_REQUEST              = 400,
+	NNG_HTTP_STATUS_UNAUTHORIZED             = 401,
+	NNG_HTTP_STATUS_PAYMENT_REQUIRED         = 402,
+	NNG_HTTP_STATUS_FORBIDDEN                = 403,
+	NNG_HTTP_STATUS_NOT_FOUND                = 404,
+	NNG_HTTP_STATUS_METHOD_NOT_ALLOWED       = 405,
+	NNG_HTTP_STATUS_NOT_ACCEPTABLE           = 406,
+	NNG_HTTP_STATUS_PROXY_AUTH_REQUIRED      = 407,
+	NNG_HTTP_STATUS_REQUEST_TIMEOUT          = 408,
+	NNG_HTTP_STATUS_CONFLICT                 = 409,
+	NNG_HTTP_STATUS_GONE                     = 410,
+	NNG_HTTP_STATUS_LENGTH_REQUIRED          = 411,
+	NNG_HTTP_STATUS_PRECONDITION_FAILED      = 412,
+	NNG_HTTP_STATUS_PAYLOAD_TOO_LARGE        = 413,
+	NNG_HTTP_STATUS_ENTITY_TOO_LONG          = 414,
+	NNG_HTTP_STATUS_UNSUPPORTED_MEDIA_TYPE   = 415,
+	NNG_HTTP_STATUS_RANGE_NOT_SATISFIABLE    = 416,
+	NNG_HTTP_STATUS_EXPECTATION_FAILED       = 417,
+	NNG_HTTP_STATUS_TEAPOT                   = 418,
+	NNG_HTTP_STATUS_UNPROCESSABLE_ENTITY     = 422,
+	NNG_HTTP_STATUS_LOCKED                   = 423,
+	NNG_HTTP_STATUS_FAILED_DEPENDENCY        = 424,
+	NNG_HTTP_STATUS_UPGRADE_REQUIRED         = 426,
+	NNG_HTTP_STATUS_PRECONDITION_REQUIRED    = 428,
+	NNG_HTTP_STATUS_TOO_MANY_REQUESTS        = 429,
+	NNG_HTTP_STATUS_HEADERS_TOO_LARGE        = 431,
+	NNG_HTTP_STATUS_UNAVAIL_LEGAL_REASONS    = 451,
+	NNG_HTTP_STATUS_INTERNAL_SERVER_ERROR    = 500,
+	NNG_HTTP_STATUS_NOT_IMPLEMENTED          = 501,
+	NNG_HTTP_STATUS_BAD_GATEWAY              = 502,
+	NNG_HTTP_STATUS_SERVICE_UNAVAILABLE      = 503,
+	NNG_HTTP_STATUS_GATEWAY_TIMEOUT          = 504,
+	NNG_HTTP_STATUS_HTTP_VERSION_NOT_SUPP    = 505,
+	NNG_HTTP_STATUS_VARIANT_ALSO_NEGOTIATES  = 506,
+	NNG_HTTP_STATUS_INSUFFICIENT_STORAGE     = 507,
+	NNG_HTTP_STATUS_LOOP_DETECTED            = 508,
+	NNG_HTTP_STATUS_NOT_EXTENDED             = 510,
+	NNG_HTTP_STATUS_NETWORK_AUTH_REQUIRED    = 511,
+};
+
+// nng_http_req represents an HTTP request.
+typedef struct nng_http_req nng_http_req;
+
+// nng_http_req_alloc creates a vanilla HTTP request object.  The object is
+// initialized with the given URL object for an HTTP/1.1 GET request by
+// default. It also adds the Host: header required for HTTP/1.1.  If the
+// url is NULL, then the uri and Host: header are uninitialized, and will
+// need to be set explicitly.
+NNG_DECL int nng_http_req_alloc(nng_http_req **, const nng_url *);
+
+// nng_http_req_free frees an HTTP request object.
+NNG_DECL void nng_http_req_free(nng_http_req *);
+
+// nng_http_req_get_method returns the method.
+NNG_DECL const char *nng_http_req_get_method(nng_http_req *);
+
+// nng_http_req_get_version returns the version, usually HTTP/1.1.
+NNG_DECL const char *nng_http_req_get_version(nng_http_req *);
+
+// nng_http_req_get_uri returns the "abs-uri", which is URL without
+// the scheme, host, or port.
+NNG_DECL const char *nng_http_req_get_uri(nng_http_req *);
+
+// nng_http_req_set_header sets an HTTP header, replacing any previous value
+// that might have been present.
+NNG_DECL int nng_http_req_set_header(
+    nng_http_req *, const char *, const char *);
+
+// nng_http_req_add_header adds an HTTP header, without disrupting any other
+// with the same name that might have been present.
+NNG_DECL int nng_http_req_add_header(
+    nng_http_req *, const char *, const char *);
+
+// nng_http_req_del_header deletes all occurrences of a named header.
+NNG_DECL int nng_http_req_del_header(nng_http_req *, const char *);
+
+// nng_http_req_get_header looks up a header with the named, returns NULL
+// if not found.
+NNG_DECL const char *nng_http_req_get_header(nng_http_req *, const char *);
+
+// nng_http_req_set_method is used to change the method of a request.
+// The method should be an upper case HTTP method, like POST, or DELETE.
+// Null sets the default ("GET").
+NNG_DECL int nng_http_req_set_method(nng_http_req *, const char *);
+
+// nng_http_req_set_version is used to change the version of a request.
+// Normally the version is "HTTP/1.1".  Note that the framework does
+// not support HTTP/2 at all.  Null sets the default ("HTTP/1.1").
+NNG_DECL int nng_http_req_set_version(nng_http_req *, const char *);
+
+// nng_http_req_set_uri is used to change the URI of a request.  This
+// should be an "abs-uri", that is a path, plus query and fragment if
+// needed.  The scheme, host, and port don't belong here.  The URI should
+// start with a leading '/' per HTTP.
+NNG_DECL int nng_http_req_set_uri(nng_http_req *, const char *);
+
+// nng_http_req_set_data adds entity data to the request.  The
+// data object must persist (so only really useful for static data).
+// The content-length header is updated as well, but the caller should
+// probably set the content-type header.
+NNG_DECL int nng_http_req_set_data(nng_http_req *, const void *, size_t);
+
+// nng_http_req_copy_data adds entity data to the response. A private
+// copy of the data is made (will be freed with the request).
+// The content-length header is updated as well, but the caller should
+// probably set the content-type header.
+NNG_DECL int nng_http_req_copy_data(nng_http_req *, const void *, size_t);
+
+// nng_http_res represents an HTTP response.
+typedef struct nng_http_res nng_http_res;
+
+// nng_http_res_alloc creates a vanilla HTTP response object.  The object is
+// initialized for an HTTP/1.1 200 OK response by default.
+NNG_DECL int nng_http_res_alloc(nng_http_res **);
+
+// nng_http_res_alloc_error creates an error HTTP response object.  The object
+// is initialized for an HTTP/1.1 response, and contains an associated
+// generic HTML error page.
+NNG_DECL int nng_http_res_alloc_error(nng_http_res **, uint16_t);
+
+// nng_http_res_free frees an HTTP response object.
+NNG_DECL void nng_http_res_free(nng_http_res *);
+
+// nng_http_res_get_status returns the HTTP status code from the server.
+NNG_DECL uint16_t nng_http_res_get_status(nng_http_res *);
+
+// nng_http_res_set_status sets the HTTP status code.
+NNG_DECL int nng_http_res_set_status(nng_http_res *, uint16_t);
+
+// nng_http_res_get_reason returns the human readable status message
+// that the server responds (or responded) with.
+NNG_DECL const char *nng_http_res_get_reason(nng_http_res *);
+
+// nng_http_res_set_rason sets the human readable status message.
+// NULL means that a default reason is used based on the status code.
+NNG_DECL int nng_http_res_set_reason(nng_http_res *, const char *);
+
+// nng_http_res_set_header sets an HTTP header, replacing any previous value
+// that might have been present.
+NNG_DECL int nng_http_res_set_header(
+    nng_http_res *, const char *, const char *);
+
+// nng_http_res_add_header adds an HTTP header, without disrupting any other
+// with the same name that might have been present.
+NNG_DECL int nng_http_res_add_header(
+    nng_http_res *, const char *, const char *);
+
+// nng_http_res_del_header deletes all occurrences of a named header.
+NNG_DECL int nng_http_res_del_header(nng_http_res *, const char *);
+
+// nng_http_res_get_header looks up a header with the named, returns NULL
+// if not found.
+NNG_DECL const char *nng_http_res_get_header(nng_http_res *, const char *);
+
+// nng_http_res_set_version is used to change the version of a response.
+// Normally the version is "HTTP/1.1".  Note that the framework does
+// not support HTTP/2 at all.  NULL sets the default ("HTTP/1.1").
+NNG_DECL int nng_http_res_set_version(nng_http_res *, const char *);
+
+// nng_http_res_get_version returns the version, usually HTTP/1.1.
+NNG_DECL const char *nng_http_res_get_version(nng_http_res *);
+
+// nng_http_res_set_data adds entity data to the response.  The
+// data object must persist (so only really useful for static data).
+// The content-length header is updated as well, but the caller should
+// probably set the content-type header.
+NNG_DECL int nng_http_res_set_data(nng_http_res *, const void *, size_t);
+
+// nng_http_res_copy_data adds entity data to the response. A private
+// copy of the data is made (will be freed with the request).
+// The content-length header is updated as well, but the caller should
+// probably set the content-type header.
+NNG_DECL int nng_http_res_copy_data(nng_http_res *, const void *, size_t);
+
+// An nng_http_conn represents an underlyinjg "connection".  It may be
+// a TCP channel, or a TLS channel, but the main thing is that this is
+// normally only used for exchanging HTTP requests and responses.
+typedef struct nng_http_conn nng_http_conn;
+
+// nng_http_conn_close closes the underlying channel.  Applications should
+// not use this channel after this operation is performed.
+NNG_DECL void nng_http_conn_close(nng_http_conn *);
+
+// nng_http_conn_read attempts to read data from the connection.  This
+// completes as soon as at least one byte is read; it does not wait
+// for the entire aio to be filled.
+NNG_DECL void nng_http_conn_read(nng_http_conn *, nng_aio *);
+
+// nng_http_conn_read_all is like nng_http_conn_read, but it does not
+// finish until either all the requested data is read, or an error occurs.
+NNG_DECL void nng_http_conn_read_all(nng_http_conn *, nng_aio *);
+
+// nng_http_conn_write attempts to write data, but it can write less
+// than the amount requested. (It completes as soon as at least one
+// byte is written.)
+NNG_DECL void nng_http_conn_write(nng_http_conn *, nng_aio *);
+
+// nng_http_conn_write_all is like nng_http_conn_write, but it does not
+// finish until either all the requested data is written, or an error occurs.
+NNG_DECL void nng_http_conn_write_all(nng_http_conn *, nng_aio *);
+
+// nng_http_conn_write_req writes the entire request.  It will also write any
+// data that has been attached.
+NNG_DECL void nng_http_conn_write_req(
+    nng_http_conn *, nng_http_req *, nng_aio *);
+
+// nng_http_conn_write_res writes the entire response.  It will also write any
+// data that has been attached.
+NNG_DECL void nng_http_conn_write_res(
+    nng_http_conn *, nng_http_res *, nng_aio *);
+
+// nng_http_conn_read_req reads an entire request, EXCEPT for any entity
+// data.  The caller is responsible for processing the headers in the request
+// and reading any submitted entity data itself.
+NNG_DECL void nng_http_conn_read_req(
+    nng_http_conn *, nng_http_req *, nng_aio *);
+
+// nng_http_conn_read_res reads an entire response, EXCEPT for any entity
+// data.  The caller is responsible for processing the headers in the response
+// and reading any submitted entity data itself.
+NNG_DECL void nng_http_conn_read_res(
+    nng_http_conn *, nng_http_res *, nng_aio *);
+
+// nng_http_handler is a handler used on the server side to handle HTTP
+// requests coming into a specific URL.
+typedef struct nng_http_handler nng_http_handler;
+
+// nng_http_handler_alloc creates a server handler object, for the supplied
+// absolute URI (path only) with the callback.  By default the handler
+// is assumed to handle only GET requests (and implictly HEAD requests
+// as well.)
+//
+// Note that methods which modify a handler cannot be called while the handler
+// is registered with the server, and that a handler can only be registered
+// once per server.
+//
+// The callback function will receive the following arguments (via
+// nng_aio_get_input(): nng_http_request *, nng_http_handler *, and
+// nng_http_conn *.  The first is a request object, for convenience.
+// The second is the handler, from which the callback can obtain any other
+// data it has set.  The final is the http connection, which can be used
+// to hijack the session.
+//
+// Upon completion, the handler should store an nng_http_res * as the
+// first output using nng_aio_set_output.  If it does not do so, or supplies
+// NULL, then it must send a response itself.
+//
+// The callback should return 0 in most circumstances; if it returns anything
+// other than 0 then the connection is terminated (after possibly sending
+// a 500 error response to the client.)
+NNG_DECL int nng_http_handler_alloc(
+    nng_http_handler **, const char *, void (*)(nng_aio *));
+
+// nng_http_handler_free frees the handler. This actually just drops a
+// reference count on the handler, as it may be in use by an existing
+// server.  The server will also call this when it is destroyed.
+NNG_DECL void nng_http_handler_free(nng_http_handler *);
+
+// nng_http_handler_alloc_file creates a "file" based handler, that
+// serves up static content from the given file path.  The content-type
+// supplied is determined from the file name using a simple built-in map.
+NNG_DECL int nng_http_handler_alloc_file(
+    nng_http_handler **, const char *, const char *);
+
+// nng_http_handler_alloc_static creates a static-content handler.
+// The last argument is the content-type, which may be NULL (in which case
+// "application/octet-stream" is assumed.)
+NNG_DECL int nng_http_handler_alloc_static(
+    nng_http_handler **, const char *, const void *, size_t, const char *);
+
+// nng_http_handler_alloc_file creates a "directory" based handler, that
+// serves up static content from the given directory tree.  Directories
+// that contain an index.html or index.htm file use that file for the
+// directory content, otherwise a suitable error page is returned (the server
+// does not generate index pages automatically.)  The content-type for
+// files is determined from the file name using a simple built-in map.
+NNG_DECL int nng_http_handler_alloc_directory(
+    nng_http_handler **, const char *, const char *);
+
+// nng_http_handler_set_method sets the method that the handler will be
+// called for.  By default this is GET.  If NULL is supplied for the
+// method, then the handler is executed regardless of method, and must
+// inspect the method itself.
+NNG_DECL int nng_http_handler_set_method(nng_http_handler *, const char *);
+
+// nng_http_handler_set_host sets the Host: that the handler will be
+// called for (to allow for virtual hosts).  If the value is NULL (the
+// default, then the Host: header is not considered when matching the
+// handler.)  Note that the Host: header must match *exactly* (except
+// that case is not considered.)
+NNG_DECL int nng_http_handler_set_host(nng_http_handler *, const char *);
+
+// nng_http_handler_set_tree indicates that the handler is being registered
+// for a heirarchical tree, rather than just a single path, so it will be
+// called for all child paths supplied.  By default the handler is only
+// called for an exact path match.
+NNG_DECL int nng_http_handler_set_tree(nng_http_handler *);
+
+// nng_http_handler_set_data is used to store additional data, along with
+// a possible clean up routine.  (The clean up is a custom deallocator and
+// will be called with the supplied data as an argument, when the handler
+// is being deallocated.)
+NNG_DECL int nng_http_handler_set_data(
+    nng_http_handler *, void *, void (*)(void *));
+
+// nng_http_handler_get_data returns the data that was previously stored.
+NNG_DECL void *nng_http_handler_get_data(nng_http_handler *);
+
+// nng_http_server is a handle to an HTTP server instance.  Servers
+// only serve a single port / address at this time.
+
+typedef struct nng_http_server nng_http_server;
+
+// nng_http_server_hold gets a server structure, using the address determined
+// from the URL.  If a server already exists, then a hold is placed on it, and
+// that instance is returned.  If no such server exists, then a new instance
+// is created.
+NNG_DECL int nng_http_server_hold(nng_http_server **, const nng_url *);
+
+// nng_http_server_release releases the hold on the server.  If this is the
+// last instance of the server, then it is shutdown and resources are freed.
+NNG_DECL void nng_http_server_release(nng_http_server *);
+
+// nng_http_server_start starts the server handling HTTP.  Once this is
+// called, it will not be possible to change certain parameters (such as
+// any TLS configuration).
+NNG_DECL int nng_http_server_start(nng_http_server *);
+
+// nng_http_server_stop stops the server.  No new client connections are
+// accepted after this returns.
+NNG_DECL void nng_http_server_stop(nng_http_server *);
+
+// nng_http_server_add_handler registers a handler on the server.
+// This function will return NNG_EADDRINUSE if a conflicting handler
+// is already registered (i.e. a handler with the same value for Host,
+// Method, and URL.)
+NNG_DECL int nng_http_server_add_handler(
+    nng_http_server *, nng_http_handler *);
+
+// nni_http_del_handler removes the given handler.  The caller is
+// responsible for finalizing it afterwards.  If the handler was not found
+// (not registered), NNG_ENOENT is returned.  In this case it is unsafe
+// to make assumptions about the validity of the handler.
+NNG_DECL int nng_http_server_del_handler(
+    nng_http_server *, nng_http_handler *);
+
+// nng_http_server_set_tls adds a TLS configuration to the server,
+// and enables the use of it.  This returns NNG_EBUSY if the server is
+// already started.   This wipes out the entire TLS configuration on the
+// server client, so the caller must have configured it reasonably.
+// This API is not recommended unless the caller needs complete control
+// over the TLS configuration.
+NNG_DECL int nng_http_server_set_tls(nng_http_server *, nng_tls_config *);
+
+// nng_http_server_get_tls obtains the TLS configuration if one is present,
+// or returns NNG_EINVAL.  The TLS configuration is invalidated if the
+// nng_http_server_set_tls function is called, so be careful.
+NNG_DECL int nng_http_server_get_tls(nng_http_server *, nng_tls_config **);
+
+// nng_http_hijack is intended to be called by a handler that wishes to
+// take over the processing of the HTTP session -- usually to change protocols
+// (such as in the case of websocket).  The caller is responsible for the
+// final disposal of the associated nng_http_conn.  Also, this completely
+// disassociates the http session from the server, so the server may be
+// stopped or destroyed without affecting the hijacked session.  Note also
+// that the hijacker will need to issue any HTTP reply itself.  Finally,
+// when a session is hijacked, the caller is also responsible for disposing
+// of the request structure.  (Some hijackers may keep the request for
+// further processing.)
+
+NNG_DECL int nng_http_hijack(nng_http_conn *);
+
 #ifdef __cplusplus
 }
 #endif