Update more interfaces with comments / documentation Change-Id: Ifabf46453e17ab35231388566b221b830c5c6ff3 Reviewed-on: https://weave-review.googlesource.com/1410 Reviewed-by: Alex Vakulenko <avakulenko@google.com>
diff --git a/libweave/include/weave/provider/http_server.h b/libweave/include/weave/provider/http_server.h index da53e1f..ced7975 100644 --- a/libweave/include/weave/provider/http_server.h +++ b/libweave/include/weave/provider/http_server.h
@@ -14,6 +14,96 @@ namespace weave { namespace provider { +// This interface should be implemented by the user of libweave and +// provided during device creation in Device::Create(...) +// libweave will use this interface to handle HTTP / HTTPS requests for Privet +// APIs. +// +// This interface consist of 2 parts that need to be implemented by the +// libweave user: HttpServer and HttpServer::Request. HttpServer provides +// interface to control webserver, and is used to initialize Device object. +// Request provides an abstraction for a specific HTTP request and may be a +// short-lived object. +// +// Implementation of AddHttpsRequestHandler(...) method should follow the +// same guidelines as implementation of AddHttpRequestHandler(...) with the +// only difference, it is for HTTPS connection (not HTTP). +// +// Implementation of GetHttpPort() method should return port number on +// which HTTP server will be listening. Normally it is port 80, but this +// allows implementer to choose different port if necessary and tell it to +// libweave. +// +// Implementation of GetHttpsPort() should follow the same guidelines as +// GetHttpPort(). Default HTTPS port is 443, but could be changed and +// communicated to libweave using this method. +// +// Implementation of GetHttpsCertificateFingerprint() method should +// compute fingerprint of the certificate that HTTPS web server will be using. +// Method of computing fingerprint is the following: +// fingerprint = SHA256 ( DER certificate ) +// You can see example implementation in HttpServerImpl::GenerateX509() +// in libweave/examples/provider/event_http_server.cc +// +// Implementation of AddHttpRequestHandler(...) method should add path +// to the list of the exposed entry points for the webserver and store +// path and callback pair somewhere. Once webserver receives an HTTP request, +// it should check if there is a libweave-registered handler corresponding to +// the path in the request. If there is one, implementation should invoke +// the callback associated with this path. If there is no callback associated +// with request path, webserver should return HTTP status code 404. +// +// For example, let's say local IP is "192.168.0.1" and libweave called +// AddHttpRequestHandler("/privet/info", InfoHandlerCallback); +// If webserver receives "http://192.168.0.1/privet/info" request, HttpServer +// implementation must invoke InfoHandlerCallback. +// If webserver receives "http://192.168.0.1/privet/auth" request, it must +// return HTTP status code 404 response. +// +// As everywhere else, invoking callbacks have some limitations: +// - callback should not be called before AddHttpRequestHandler() returns +// - callback should be called on the same thread +// +// Once HttpServer implementation invokes a registered callback, it should +// provide the Request interface implementation to access a request data. +// +// Implementation of GetPath() method should return path of the HTTP +// request. For example, "/privet/info". +// +// Implementation of the GetFirstHeader(...) method should return the first +// header in the request matching name parameter of this method. +// For example, GetFirstHeader("Content-Length") may return "3495". +// +// Implementation of GetData() method should return full request data +// in a binary format wrapped into std::string object. +// +// Implementation of the SendReply(...) method should send request response +// message with specified parameters: +// status_code - standard HTTP status code, for example 200 to indicate +// successful response. +// data - binary data of the response body wrapped into std::string object. +// mime_type - MIME type of the response, that should be transferred into +// "Content-Type" HTTP header. +// Implementation of the SendReply(...) method may also add other standard +// HTTP headers, like "Content-Length" or "Transfer-Encoding" depending on +// capabilities of the server and client which made this request. +// +// In case a device has multiple networking interfaces, the device developer +// needs to make a decision where local APIs (Privet) are necessary and where +// they are not needed. For example, it may not make sense to expose local +// APIs on any external-facing network interface (cellular or WAN). +// +// In some cases, there might be more then one network interface where local +// APIs makes sense. For example, a device may have both WiFi and Ethernet +// connections. In such case, webserver should start on both interfaces +// simultaneously, and allow requests from both interfaces to be handled by +// libweave. +// +// From libweave perspective, it always looks like there is only one network +// interface. It is the job of HttpServer implementation to hide network +// complexity from libweave and to bring webserver up on the same port on all +// interfaces. + class HttpServer { public: class Request {