46 | libebb is a lightweight HTTP server library for C. It lays the 47 | foundation for writing a web server by providing the socket juggling 48 | and request parsing. By implementing the HTTP/1.1 grammar provided in 49 | RFC2612, libebb understands most most valid HTTP/1.1 connections 50 | (persistent, pipelined, and chunked requests included) and rejects 51 | invalid or malicious requests. libebb supports SSL over HTTP. 52 |
53 | 54 |55 | The library embraces a minimalistic single-threaded evented design. 56 | No control is removed from the user. For example, all allocations are 57 | done through callbacks so that the user might implement in optimal 58 | ways for their specific application. By design libebb is not 59 | thread-safe and all provided callbacks must not block. libebb uses 60 | the high-performance 61 | libev event loop, but does not control it. The user of the library may 62 | start and stop the loop at will, they may attach thier own watchers. 63 |
64 | 65 |66 | libebb depends on POSIX sockets, libev, and optionally GnuTLS. 67 |
68 | 69 |70 | libebb is in the early stages of development and probably contains 71 | many bugs. The API is subject to radical changes. If you're 72 | interested checkout 73 | the source code and join the mailing 75 | list. A release will be made when it proves stable. 76 |
77 | 78 |libebb is released under the MIT license.
79 | 80 |83 | libebb is a simple API, mostly it is providing callbacks. There are 84 | two types of callbacks that one will work with: 85 |
86 | 87 |new_* like new_connection and
90 | new_requeston_* like
93 | on_body and on_close.
97 | In libebb there are three important classes: ebb_server,
98 | ebb_connection, and ebb_request.
99 | Each server has many peer connections. Each peer connection may have many
100 | requests.
101 | There are two additional classes ebb_buf and ebb_request_parser
102 | which may or may not be useful.
103 |
ebb_server
107 | ebb_server represents a single web server listening on a
108 | single port. The user must allocate the structure themselves, then
109 | call ebb_server_init() and provide a libev event loop.
110 | ebb_server_set_secure() will make the server understand
111 | HTTPS connections.
112 |
115 | After initialized the ebb_server_listen_on_port() can be
116 | called to open the server up to new connections. libebb does not
117 | control the event loop, it is the user's responsibility to start the
118 | event loop (using ev_loop()) after
119 | ebb_server_listen_on_port() is called.
120 |
123 | To accept connections you must provide the new server with a callback
124 | called new_connection. This callback must return an allocated
125 | and initialized ebb_connection structure.
126 | To set this callback do
127 |
my_server->new_connection = my_new_connection_callback;130 | 131 |
132 | Additional documentation can be found in ebb.h
133 |
ebb_connection
138 | This structure contains information and callbacks for a single client
139 | connection. It is allocated and initialized through the
140 | new_connection callback in ebb_server.
141 | To initialize a newly allocated ebb_connection use
142 | ebb_connection_init().
143 |
146 | After ebb_connection_init() is called a number of
147 | callbacks can be set: new_request, new_buf,
148 | on_timeout, and on_close.
149 |
152 | When an ebb_connection is returned to an
153 | ebb_server, data is immediately data is read from the
154 | socket. This data must be stored somewhere. Because libebb is
155 | agnostic about allocation decisions, it passes this off to the user in
156 | the form of a callback: connection->new_buf. This
157 | callback returns a newly allocated and initialized
158 | ebb_buf structure. How much libebb attempts to read from
159 | the socket is determined by how large the returned
160 | ebb_buf structure is. Using new_buf is
161 | optional. By default libebb reads data into a static buffer
162 | (allocated at compile time), writing over it on each read. In many
163 | web server using the static buffer will be sufficent because callbacks
164 | made during the parsing will buffer the data elsewhere. Providing a
165 | new_buf callback is necessary only if you want to save
166 | the raw data coming from the socket.
167 |
170 | The new_request callback is called at the beginning of a
171 | request. It must return a newly allocated and initialized
172 | ebb_request structure. Because HTTP/1.1 supports peristant
174 | connections, there may be many requests per connection.
175 |
178 | You may access the file descriptor for the client socket inside the
179 | ebb_connection structure. Writing the response, in valid
180 | HTTP, is the user's responsibility. Remember, requests must be
181 | returned to client in the same order that they were received.
182 |
185 | A convience function,
191 | To close a peer connection use
192 | ebb_connnection_schedule_close(). Because SSL may require
193 | some additional communication to close the connection properly, the
194 | file descriptor cannot be closed immediately. The
195 | on_close callback will be made when the peer socket is
196 | finally closed.
197 | Only once on_close is called may the
198 | user free the ebb_connection structure.
199 |
ebb_request
205 | This structure provides information about a request. For example,
206 | request->method == EBB_POST would mean the method of
207 | the request is POST. There are also many callbacks
208 | which can be set to handle data from a request as it is parsed.
209 |
212 | The on_uri callback and all other
213 | ebb_element_cb callbacks provide pointers to request
214 | data. The annoying thing is they do not necessarily provide a
215 | complete string. This is because the reads from the socket may not
216 | contain an entire request and for efficency libebb does not attempt to
217 | buffer the data. Theoretically, one might receive an
218 | on_uri callback 10 times, each providing just a single
219 | character of the request's URI. See ebb_request_parser.h for
220 | a full list of callbacks that you may provide. (If you don't set them,
221 | they are ignored.)
222 |
225 | The on_complete callback is called at the end of
226 | each request.
227 | Only once on_complete is called may the
228 | user free the ebb_request structure.
229 |
234 | A simple example is provided in examples/hello_world.c.
235 |