aboutsummaryrefslogtreecommitdiff
path: root/README
blob: 0f5d395965ab3c736ab11a8e76eabe1c8fca4d76 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
About
=====

GNU libmicrohttpd is a GNU package offering a C library that provides
a compact API and implementation of an HTTP 1.1 web server (HTTP 1.0
is also supported).  GNU libmicrohttpd only implements the HTTP 1.1
protocol.  The main application must still provide the application
logic to generate the content.

Additionally, a second, still very experimental library is provided
for SPDY (the base for HTTP 2.0) support.  libmicrospdy provides a
compact API and implementation of SPDY server. libmicrospdy currently
only implements partially version 3 of SPDY.


Installation
============

If you are using Subversion, run "autoreconf -fi" to create configure.

In order to run the testcases, you need a recent version of libcurl.
libcurl is not required if you just want to install the library.

Especially for development, do use the MHD_USE_DEBUG option to get
error messages.


Requirements for libmicrospdy
=============================

The following packages are needed to build libmicrospdy:

* zlib 
* OpenSSL >= 1.0.1

To run the test cases, involving requests, version of Spdylay, supporting
SPDY v3, is required. Spdylay is still under development and can be
found here:

http://spdylay.sourceforge.net/


Configure options
=================


If you are concerned about space, you should set "CFLAGS" to "-Os
-fomit-frame-pointer" to have gcc generate tight code.

You can use the following options to disable certain MHD features:

--disable-https: no HTTPS / TLS / SSL support (significant reduction)
--disable-messages: no error messages (they take space!)
--disable-postprocessor: no MHD_PostProcessor API
--disable-dauth: no digest authentication API
--disable-epoll: no support for epoll, even on Linux

The resulting binary should be about 30-40k depending on the platform.


Portability
===========

The latest version of libmicrohttpd will try to avoid SIGPIPE on its
sockets.  This should work on OS X, Linux and recent BSD systems (at
least).  On other systems that may trigger a SIGPIPE on send/recv, the
main application should install a signal handler to handle SIGPIPE.

libmicrohttpd should work well on GNU/Linux, BSD, OS X, W32 and z/OS.
Note that HTTPS is not supported on z/OS (yet).  We also have reports
of users using it on vxWorks and Symbian.  Note that on platforms
where the compiler does not support the "constructor" attribute, you
must call "MHD_init" before using any MHD functions and "MHD_fini"
after you are done using MHD.


Development Status
==================

This is a beta release for libmicrohttpd.  Before declaring the
library stable, we should implement support for HTTP "Upgrade" 
requests and have testcases for the following features:

- HTTP/1.1 pipelining (need to figure out how to ensure curl pipelines 
  -- and it seems libcurl has issues with pipelining, 
  see http://curl.haxx.se/mail/lib-2007-12/0248.html)
- resource limit enforcement
- client queuing early response, suppressing 100 CONTINUE
- chunked encoding to validate handling of footers
- more testing for SSL support
- MHD basic and digest authentication

In particular, the following functions are not covered by 'make check':
- mhd_panic_std (daemon.c); special case (abort)
- parse_options (daemon.c)
- MHD_set_panic_func (daemon.c)
- MHD_get_version (daemon.c)


This is an early alpha release for libmicrospdy.  The following things
should be implemented (in order of importance) before we can claim to
be reasonably complete:
- 8 different output queues (one for each priority) have to be implemented
together with a suitable algorithm for utilizing them. Otherwise, downloading
a file will block all responses with same or smaller priority
- SPDY RST_STREAM sending on each possible error (DONE?)
- SPDY_close_session
- Find the best way for closing still opened stream (new call or existing)
- SPDY_is_stream_opened
- SPDY PING (used often by browsers)
- receiving SPDY WINDOW_UPDATE
- SPDY Settings
- SPDY PUSH
- SPDY HEADERS
- SPDY Credentials

Additional ideas for features include:
- Individual callbacks for each session
- Individual timeout for each session

Unimplemented API functions of libmicrospdy:
- SPDY_settings_create ();
- SPDY_settings_add (...);
- SPDY_settings_lookup (...);
- SPDY_settings_iterate (...);
- SPDY_settings_destroy (...);
- SPDY_close_session(...);
- SPDY_send_ping(...);
- SPDY_send_settings (...);

In particular, we should write tests for:
- Enqueueing responses while considering request priorities.
- HTTP methods other than GET





Missing documentation:
======================

- libmicrohttpd manual:
  * document details on porting MHD (plibc, z/OS)
- libmicrospdy manual:
  * missing entirely


Notes on compiling on z/OS:
===========================

After extracting the archive, run

iconv -f UTF-8 -t IBM-1047 contrib/ascebc > /tmp/ascebc.sh
chmod +x /tmp/ascebc.sh
for n in `find * -type f`
do
  /tmp/ascebc.sh $n
done

to convert all source files to EBCDIC.  Note that you must run
"configure" from the directory where the configure script is
located.   Otherwise, configure will fail to find the
"contrib/xcc" script (which is a wrapper around the z/OS c89
compiler).