Daniel Erat | 748945e | 2015-08-11 09:22:30 -0600 | [diff] [blame] | 1 | About |
| 2 | ===== |
| 3 | |
| 4 | GNU libmicrohttpd is a GNU package offering a C library that provides |
| 5 | a compact API and implementation of an HTTP 1.1 web server (HTTP 1.0 |
| 6 | is also supported). GNU libmicrohttpd only implements the HTTP 1.1 |
| 7 | protocol. The main application must still provide the application |
| 8 | logic to generate the content. |
| 9 | |
| 10 | Additionally, a second, still very experimental library is provided |
| 11 | for SPDY (the base for HTTP 2.0) support. libmicrospdy provides a |
| 12 | compact API and implementation of SPDY server. libmicrospdy currently |
| 13 | only implements partially version 3 of SPDY. |
| 14 | |
| 15 | |
| 16 | Installation |
| 17 | ============ |
| 18 | |
| 19 | If you are using Subversion, run "autoreconf -fi" to create configure. |
| 20 | |
| 21 | In order to run the testcases, you need a recent version of libcurl. |
| 22 | libcurl is not required if you just want to install the library. |
| 23 | |
| 24 | Especially for development, do use the MHD_USE_DEBUG option to get |
| 25 | error messages. |
| 26 | |
| 27 | |
| 28 | Requirements for libmicrospdy |
| 29 | ============================= |
| 30 | |
| 31 | The following packages are needed to build libmicrospdy: |
| 32 | |
| 33 | * zlib |
| 34 | * OpenSSL >= 1.0.1 |
| 35 | |
| 36 | To run the test cases, involving requests, version of Spdylay, supporting |
| 37 | SPDY v3, is required. Spdylay is still under development and can be |
| 38 | found here: |
| 39 | |
| 40 | http://spdylay.sourceforge.net/ |
| 41 | |
| 42 | |
| 43 | Configure options |
| 44 | ================= |
| 45 | |
| 46 | |
| 47 | If you are concerned about space, you should set "CFLAGS" to "-Os |
| 48 | -fomit-frame-pointer" to have gcc generate tight code. |
| 49 | |
| 50 | You can use the following options to disable certain MHD features: |
| 51 | |
| 52 | --disable-https: no HTTPS / TLS / SSL support (significant reduction) |
| 53 | --disable-messages: no error messages (they take space!) |
| 54 | --disable-postprocessor: no MHD_PostProcessor API |
| 55 | --disable-dauth: no digest authentication API |
| 56 | --disable-epoll: no support for epoll, even on Linux |
| 57 | |
| 58 | The resulting binary should be about 30-40k depending on the platform. |
| 59 | |
| 60 | |
| 61 | Portability |
| 62 | =========== |
| 63 | |
| 64 | The latest version of libmicrohttpd will try to avoid SIGPIPE on its |
| 65 | sockets. This should work on OS X, Linux and recent BSD systems (at |
| 66 | least). On other systems that may trigger a SIGPIPE on send/recv, the |
| 67 | main application should install a signal handler to handle SIGPIPE. |
| 68 | |
| 69 | libmicrohttpd should work well on GNU/Linux, BSD, OS X, W32 and z/OS. |
| 70 | Note that HTTPS is not supported on z/OS (yet). We also have reports |
| 71 | of users using it on vxWorks and Symbian. Note that on platforms |
| 72 | where the compiler does not support the "constructor" attribute, you |
| 73 | must call "MHD_init" before using any MHD functions and "MHD_fini" |
| 74 | after you are done using MHD. |
| 75 | |
| 76 | |
| 77 | Development Status |
| 78 | ================== |
| 79 | |
| 80 | This is a beta release for libmicrohttpd. Before declaring the |
| 81 | library stable, we should implement support for HTTP "Upgrade" |
| 82 | requests and have testcases for the following features: |
| 83 | |
| 84 | - HTTP/1.1 pipelining (need to figure out how to ensure curl pipelines |
| 85 | -- and it seems libcurl has issues with pipelining, |
| 86 | see http://curl.haxx.se/mail/lib-2007-12/0248.html) |
| 87 | - resource limit enforcement |
| 88 | - client queuing early response, suppressing 100 CONTINUE |
| 89 | - chunked encoding to validate handling of footers |
| 90 | - more testing for SSL support |
| 91 | - MHD basic and digest authentication |
| 92 | |
| 93 | In particular, the following functions are not covered by 'make check': |
| 94 | - mhd_panic_std (daemon.c); special case (abort) |
| 95 | - parse_options (daemon.c) |
| 96 | - MHD_set_panic_func (daemon.c) |
| 97 | - MHD_get_version (daemon.c) |
| 98 | |
| 99 | |
| 100 | This is an early alpha release for libmicrospdy. The following things |
| 101 | should be implemented (in order of importance) before we can claim to |
| 102 | be reasonably complete: |
| 103 | - 8 different output queues (one for each priority) have to be implemented |
| 104 | together with a suitable algorithm for utilizing them. Otherwise, downloading |
| 105 | a file will block all responses with same or smaller priority |
| 106 | - SPDY RST_STREAM sending on each possible error (DONE?) |
| 107 | - SPDY_close_session |
| 108 | - Find the best way for closing still opened stream (new call or existing) |
| 109 | - SPDY_is_stream_opened |
| 110 | - SPDY PING (used often by browsers) |
| 111 | - receiving SPDY WINDOW_UPDATE |
| 112 | - SPDY Settings |
| 113 | - SPDY PUSH |
| 114 | - SPDY HEADERS |
| 115 | - SPDY Credentials |
| 116 | |
| 117 | Additional ideas for features include: |
| 118 | - Individual callbacks for each session |
| 119 | - Individual timeout for each session |
| 120 | |
| 121 | Unimplemented API functions of libmicrospdy: |
| 122 | - SPDY_settings_create (); |
| 123 | - SPDY_settings_add (...); |
| 124 | - SPDY_settings_lookup (...); |
| 125 | - SPDY_settings_iterate (...); |
| 126 | - SPDY_settings_destroy (...); |
| 127 | - SPDY_close_session(...); |
| 128 | - SPDY_send_ping(...); |
| 129 | - SPDY_send_settings (...); |
| 130 | |
| 131 | In particular, we should write tests for: |
| 132 | - Enqueueing responses while considering request priorities. |
| 133 | - HTTP methods other than GET |
| 134 | |
| 135 | |
| 136 | |
| 137 | |
| 138 | |
| 139 | Missing documentation: |
| 140 | ====================== |
| 141 | |
| 142 | - libmicrospdy manual: |
| 143 | * missing entirely |