From 83728219db071cf765bf73823d5431b2ac093858 Mon Sep 17 00:00:00 2001 From: Tatsuhiro Tsujikawa Date: Wed, 24 Sep 2014 00:25:37 +0900 Subject: [PATCH] Update doc --- .gitignore | 2 + README.rst | 49 ++++++++++ configure.ac | 2 + doc/Makefile.am | 1 + doc/asio_http2.h.rst.in | 4 + doc/libnghttp2_asio.rst.in | 1 + doc/sources/index.rst | 2 + doc/sources/libnghttp2_asio.rst | 159 ++++++++++++++++++++++++++++++++ examples/.gitignore | 1 + 9 files changed, 221 insertions(+) create mode 100644 doc/asio_http2.h.rst.in create mode 100644 doc/libnghttp2_asio.rst.in create mode 100644 doc/sources/libnghttp2_asio.rst diff --git a/.gitignore b/.gitignore index 3044dee3..b516bf7d 100644 --- a/.gitignore +++ b/.gitignore @@ -40,3 +40,5 @@ doc/h2load-howto.rst doc/tutorial-hpack.rst doc/python-apiref.rst doc/building-android-binary.rst +doc/asio_http2.h.rst +doc/libnghttp2_asio.rst diff --git a/README.rst b/README.rst index 494f6074..df19aa94 100644 --- a/README.rst +++ b/README.rst @@ -11,6 +11,8 @@ HTTP/2 and SPDY. HPACK encoding and decoding are available as public API. +The experimental high level C++ library is also available. + We have Python binding of this libary, but we have not covered everything yet. @@ -100,6 +102,11 @@ To mitigate heap fragmentation in long running server programs * jemalloc +libnghttp2_asio C++ library requires the following packages: + +* libboost-dev >= 1.55.0 +* libboost-thread-dev >= 1.55.0 + The Python bindings require the following packages: * cython >= 0.19 @@ -961,6 +968,48 @@ associated value includes the state of dynamic header table after the corresponding header set was processed. The format is the same as ``deflatehd``. +libnghttp2_asio: High level HTTP/2 C++ library +---------------------------------------------- + +libnghttp2_asio is C++ library built on top of libnghttp2 and provides +high level abstraction API to build HTTP/2 applications. It depends +on Boost::ASIO library and OpenSSL. Currently libnghttp2_asio +provides server side API. + +libnghttp2_asio is not built by default. Use ``--enable-asio-lib`` +configure flag to build libnghttp2_asio. The required Boost libraries +are: + +* Boost::Asio +* Boost::System +* Boost::Thread + +Server API is designed to build HTTP/2 server very easily to utilize +C++11 anonymous function and closure. The bare minimum example of +HTTP/2 server looks like this: + +.. code-block:: cpp + + #include + + using namespace nghttp2::asio_http2; + using namespace nghttp2::asio_http2::server; + + int main(int argc, char* argv[]) + { + http2 server; + + server.listen + ("*", 3000, + [](std::shared_ptr req, std::shared_ptr res) + { + res->write_head(200); + res->end("hello, world"); + }); + } + +For more details, see the documentation of libnghttp2_asio. + Python bindings --------------- diff --git a/configure.ac b/configure.ac index 38a0566c..b71620ac 100644 --- a/configure.ac +++ b/configure.ac @@ -551,10 +551,12 @@ AC_CONFIG_FILES([ doc/tutorial-hpack.rst doc/nghttpx-howto.rst doc/h2load-howto.rst + doc/libnghttp2_asio.rst doc/python-apiref.rst doc/building-android-binary.rst doc/nghttp2.h.rst doc/nghttp2ver.h.rst + doc/asio_http2.h.rst ]) AC_OUTPUT diff --git a/doc/Makefile.am b/doc/Makefile.am index 5620924d..6aa0123b 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -37,6 +37,7 @@ EXTRA_DIST = \ sources/tutorial-hpack.rst \ sources/nghttpx-howto.rst \ sources/h2load-howto.rst \ + sources/libnghttp2_asio.rst \ sources/python-apiref.rst \ sources/building-android-binary.rst \ _themes/sphinx_rtd_theme/footer.html \ diff --git a/doc/asio_http2.h.rst.in b/doc/asio_http2.h.rst.in new file mode 100644 index 00000000..6f677440 --- /dev/null +++ b/doc/asio_http2.h.rst.in @@ -0,0 +1,4 @@ +asio_http2.h +============ + +.. literalinclude:: @top_srcdir@/src/includes/nghttp2/asio_http2.h diff --git a/doc/libnghttp2_asio.rst.in b/doc/libnghttp2_asio.rst.in new file mode 100644 index 00000000..38254e1c --- /dev/null +++ b/doc/libnghttp2_asio.rst.in @@ -0,0 +1 @@ +.. include:: @top_srcdir@/doc/sources/libnghttp2_asio.rst diff --git a/doc/sources/index.rst b/doc/sources/index.rst index 5874ffc5..0ae60e02 100644 --- a/doc/sources/index.rst +++ b/doc/sources/index.rst @@ -28,9 +28,11 @@ Contents: nghttpx-howto h2load-howto apiref + libnghttp2_asio python-apiref nghttp2.h nghttp2ver.h + asio_http2.h Source Issues diff --git a/doc/sources/libnghttp2_asio.rst b/doc/sources/libnghttp2_asio.rst new file mode 100644 index 00000000..4caa1b0d --- /dev/null +++ b/doc/sources/libnghttp2_asio.rst @@ -0,0 +1,159 @@ +libnghttp2_asio: High level HTTP/2 C++ library +============================================== + +libnghttp2_asio is C++ library built on top of libnghttp2 and provides +high level abstraction API to build HTTP/2 applications. It depends +on Boost::ASIO library and OpenSSL. Currently libnghttp2_asio +provides server side API. + +libnghttp2_asio is not built by default. Use ``--enable-asio-lib`` +configure flag to build libnghttp2_asio. The required Boost libraries +are: + +* Boost::Asio +* Boost::System +* Boost::Thread + +To use libnghttp2_asio, first include following header file: + +.. code-block:: cpp + + #include + +Also take a look at that header file :doc:`asio_http2.h`. + +Server API +---------- + +Server API is designed to build HTTP/2 server very easily to utilize +C++11 anonymous function and closure. The bare minimum example of +HTTP/2 server looks like this: + +.. code-block:: cpp + + #include + + using namespace nghttp2::asio_http2; + using namespace nghttp2::asio_http2::server; + + int main(int argc, char* argv[]) + { + http2 server; + + server.listen + ("*", 3000, + [](std::shared_ptr req, std::shared_ptr res) + { + res->write_head(200); + res->end("hello, world"); + }); + } + +First we instantiate ``nghttp2::asio_http2::server::http2`` object. +Then call ``nghttp2::asio_http2::server::http2::listen`` function with +address and port to listen to and callback function invoked when +request arrives. + +The ``req`` and ``res`` represent HTTP request and response +respectively. ``nghttp2::asio_http2_::server::response::write_head`` +constructs HTTP response header fields. The first argument is HTTP +status code, in the above example, which is 200. The second argument, +which is omitted in the above example, is additional header fields to +send. + +``nghttp2::asio_http2::server::response::end`` sends responde body. +In the above example, we send string "hello, world". + +Serving static files and enabling SSL/TLS ++++++++++++++++++++++++++++++++++++++++++ + +In this example, we serve a couple of static files and also enable +SSL/TLS. + +.. code-block:: cpp + + #include + + using namespace nghttp2::asio_http2; + using namespace nghttp2::asio_http2::server; + + int main(int argc, char* argv[]) + { + http2 server; + + server.tls("server.key", "server.crt"); + + server.listen + ("*", 3000, + [](std::shared_ptr req, std::shared_ptr res) + { + if(req->path() == "/" || req->path() == "/index.html") { + res->write_head(200); + res->end(file_reader("index.html")); + } else { + res->write_head(404); + res->end("404" + "404 Not Found"); + } + }); + } + +Specifying path to private key file and certificate file in +``nghttp2::asio_http2::server::http2::tls`` will enable SSL/TLS. Both +files must be in PEM format. + +In the above example, if request path is either "/" or "/index.html", +we serve index.html file in the current working directory. +``nghttp2::asio_http2::server::response::end`` has overload to take +function of type ``nghttp2::asio_http2::server::read_cb`` and +application pass its implementation to generate response body. For +the convenience, libnghttp2_asio library provides +``nghttp2::asio_http2::server::file_reader`` function to generate +function to server static file. + +Server push ++++++++++++ + +Server push is also supported. + +.. code-block:: cpp + + #include + + using namespace nghttp2::asio_http2; + using namespace nghttp2::asio_http2::server; + + int main(int argc, char* argv[]) + { + http2 server; + + server.tls("server.key", "server.crt"); + + server.listen + ("*", 3000, + [](std::shared_ptr req, std::shared_ptr res) + { + if(req->path() == "/") { + req->push("GET", "/my.css"); + + res->write_head(200); + res->end(file_reader("index.html")); + + return; + } + + if(req->path() == "/my.css") { + res->write_head(200); + res->end(file_reader("my.css")); + } + + res->write_head(404); + res->end("404" + "404 Not Found"); + }); + } + +When client requested "/", we push "/my.css". To push resource, call +``nghttp2::asio_http2::server::request::push`` function with desired +method and path. Later, the callback will be called with the pushed +resource "/my.css". diff --git a/examples/.gitignore b/examples/.gitignore index 848af16b..535fe627 100644 --- a/examples/.gitignore +++ b/examples/.gitignore @@ -2,3 +2,4 @@ client libevent-client libevent-server deflate +asio-sv