ceph/src/civetweb/docs/Embedding.md

   1 Embedding CivetWeb
   2 =========
   3
   4 CivetWeb is primarily designed so applications can easily add HTTP and HTTPS server as well as WebSocket functionality.  For example, an application server could use CivetWeb to enable a web service interface for automation or remote control.
   5
   6 However, it can also be used as a stand-alone executable. It can deliver static files and offers built-in server side Lua, JavaScript and CGI support. Some instructions how to build the stand-alone server can be found in [Building.md](https://github.com/civetweb/civetweb/blob/master/docs/Building.md).
   7
   8 Files
   9 ------
  10
  11 There is just a small set of files to compile in to the application,
  12 but if a library is desired, see [Building.md](https://github.com/CivetWeb/CivetWeb/blob/master/docs/Building.md)
  13
  14 #### Regarding the INL file extension
  15 The *INL* file extension represents code that is statically included inline in a source file.  Slightly different from C++ where it means "inline" code which is technically not the same as static code. CivetWeb overloads this extension for the sake of clarity as opposed to having .c extensions on files that should not be directly compiled.
  16
  17 #### HTTP Server Source Files
  18
  19 These files constitute the CivetWeb library.  They do not contain a `main` function,
  20 but all functions required to run a HTTP server.
  21
  22   - HTTP server API
  23     - include/civetweb.h
  24   - C implementation
  25     - src/civetweb.c
  26     - src/md5.inl (MD5 calculation)
  27     - src/sha1.inl (SHA calculation)
  28     - src/handle\_form.inl (HTML form handling functions)
  29     - src/timer.inl (optional timer support)
  30   - Optional: C++ wrapper
  31     - include/CivetServer.h (C++ interface)
  32     - src/CivetServer.cpp (C++ wrapper implementation)
  33   - Optional: Third party components
  34     - src/third\_party/* (third party components, mainly used for the standalone server)
  35     - src/mod\_*.inl (modules to access third party components from civetweb)
  36
  37
  38 Note: The C++ wrapper uses the official C interface (civetweb.h) and does not add new features to the server. Several features available in the C interface are missing in the C++ interface. While all features should be accessible using the C interface, this is not a design goal of the C++ interface.
  39
  40
  41 #### Additional Source Files for Executables
  42
  43 These files can be used to build a server executable. They contain a `main` function
  44 starting the HTTP server.
  45
  46   - Stand-alone C Server
  47       - src/main.c
  48   - Reference embedded C Server
  49       - examples/embedded\_c/embedded\_c.c
  50   - Reference embedded C++ Server
  51       - examples/embedded\_cpp/embedded\_cpp.cpp
  52
  53 Note: The "embedded" example is actively maintained, updated, extended and tested. Other examples in the examples/ folder might be outdated and remain there for reference.
  54
  55
  56 Quick Start
  57 ------
  58
  59 By default, the server will automatically serve up files like a normal HTTP server.  An embedded server is most likely going to overload this functionality.
  60
  61 ### C
  62   - Include the C interface ```civetweb.h```.
  63   - Use `mg_start()` to start the server.
  64       - Use *options* to select the port and document root among other things.
  65       - Use *callbacks* to add your own hooks.
  66   - Use `mg_set_request_handler()` to easily add your own request handlers.
  67   - Use `mg_stop()` to stop the server.
  68
  69 ### C++
  70   - Note that CivetWeb is Clean C, and C++ interface ```CivetServer.h``` is only a wrapper layer around the C interface.
  71     Not all CivetWeb features available in C are also available in C++.
  72   - Create CivetHandlers for each URI.
  73   - Register the handlers with `CivetServer::addHandler()`
  74   - `CivetServer` starts on contruction and stops on destruction.
  75   - Use contructor *options* to select the port and document root among other things.
  76   - Use constructor *callbacks* to add your own hooks.
  77
  78 Alternative quick start: Have a look at the examples embedded\_c and embedded\_cpp
  79
  80
  81 Lua Support
  82 ------
  83
  84 Lua is a server side include functionality.  Files ending in .lua will be processed with Lua.
  85
  86 ##### Add the following CFLAGS
  87
  88   - `-DLUA_COMPAT_ALL`
  89   - `-DUSE_LUA`
  90   - `-DUSE_LUA_SQLITE3`
  91   - `-DUSE_LUA_FILE_SYSTEM`
  92
  93 ##### Add the following sources
  94
  95   - src/mod\_lua.inl
  96   - src/third\_party/lua-5.2.4/src
  97      + lapi.c
  98      + lauxlib.c
  99      + lbaselib.c
 100      + lbitlib.c
 101      + lcode.c
 102      + lcorolib.c
 103      + lctype.c
 104      + ldblib.c
 105      + ldebug.c
 106      + ldo.c
 107      + ldump.c
 108      + lfunc.c
 109      + lgc.c
 110      + linit.c
 111      + liolib.c
 112      + llex.c
 113      + lmathlib.c
 114      + lmem.c
 115      + loadlib.c
 116      + lobject.c
 117      + lopcodes.c
 118      + loslib.c
 119      + lparser.c
 120      + lstate.c
 121      + lstring.c
 122      + lstrlib.c
 123      + ltable.c
 124      + ltablib.c
 125      + ltm.c
 126      + lundump.c
 127      + lvm.c
 128      + lzio.c
 129   - src/third\_party/sqlite3.c
 130   - src/third\_party/sqlite3.h
 131   - src/third\_party/lsqlite3.c
 132   - src/third\_party/lfs.c
 133   - src/third\_party/lfs.h
 134
 135 This build is valid for Lua version Lua 5.2. It is also possible to build with Lua 5.1 (including LuaJIT) or Lua 5.3.
 136
 137
 138 JavaScript Support
 139 ------
 140
 141 CivetWeb can be built with server side JavaScript support by including the Duktape library.
 142
 143
 144 CivetWeb internals
 145 ------
 146
 147 CivetWeb is multithreaded web server. `mg_start()` function allocates
 148 web server context (`struct mg_context`), which holds all information
 149 about web server instance:
 150
 151 - configuration options. Note that CivetWeb makes internal copies of
 152   passed options.
 153 - SSL context, if any
 154 - user-defined callbacks
 155 - opened listening sockets
 156 - a queue for accepted sockets
 157 - mutexes and condition variables for inter-thread synchronization
 158
 159 When `mg_start()` returns, all initialization is guaranteed to be complete
 160 (e.g. listening ports are opened, SSL is initialized, etc). `mg_start()` starts
 161 some threads: a master thread, that accepts new connections, and several
 162 worker threads, that process accepted connections. The number of worker threads
 163 is configurable via `num_threads` configuration option. That number puts a
 164 limit on number of simultaneous requests that can be handled by CivetWeb.
 165 If you embed CivetWeb into a program that uses SSL outside CivetWeb as well,
 166 you may need to initialize SSL before calling `mg_start()`, and set the pre-
 167 processor define `SSL_ALREADY_INITIALIZED`. This is not required if SSL is
 168 used only within CivetWeb.
 169
 170 When master thread accepts new a connection, a new accepted socket (described
 171 by `struct socket`) it placed into the accepted sockets queue,
 172 which has size of `MGSQLEN` (default 20).
 173 Any idle worker thread can grab accepted sockets from that queue.
 174 If all worker threads are busy, master thread can accept and queue up to
 175 20 more TCP connections, filling up the queue.
 176 In the attempt to queue even more accepted connection, the master thread blocks
 177 until there is space in the queue. When the master thread is blocked on a
 178 full queue, the operating system can also queue incoming connection.
 179 The number is limited by the `listen()` call parameter,
 180 which is `SOMAXCONN` and depends on the platform.
 181
 182 Worker threads are running in an infinite loop, which in a simplified form
 183 looks something like this:
 184
 185 ```C
 186     static void *worker_thread() {
 187       while (consume_socket()) {
 188         process_new_connection();
 189       }
 190     }
 191 ```
 192
 193 Function `consume_socket()` gets a new accepted socket from the CivetWeb socket
 194 queue, atomically removing it from the queue. If the queue is empty,
 195 `consume_socket()` blocks and waits until a new socket is placed in the queue
 196 by the master thread.
 197
 198 `process_new_connection()` actually processes the
 199 connection, i.e. reads the request, parses it, and performs appropriate action
 200 depending on the parsed request.
 201
 202 Master thread uses `poll()` and `accept()` to accept new connections on
 203 listening sockets. `poll()` is used to avoid `FD_SETSIZE` limitation of
 204 `select()`. Since there are only a few listening sockets, there is no reason
 205 to use hi-performance alternatives like `epoll()` or `kqueue()`. Worker
 206 threads use blocking IO on accepted sockets for reading and writing data.
 207 All accepted sockets have `SO_RCVTIMEO` and `SO_SNDTIMEO` socket options set
 208 (controlled by the `request_timeout_ms` CivetWeb option, 30 seconds default)
 209 which specifies a read/write timeout on client connections.
 210
 211
 212 A minimal example
 213 ------
 214
 215 Initializing a HTTP server
 216 ```C
 217 {
 218     /* Server context handle */
 219     struct mg_context *ctx;
 220
 221     /* Initialize the library */
 222     mg_init_library(0);
 223
 224     /* Start the server */
 225     ctx = mg_start(NULL, 0, NULL);
 226
 227     /* Add some handler */
 228     mg_set_request_handler(ctx, "/hello", handler, "Hello world");
 229
 230     ... Run the application ...
 231
 232     /* Stop the server */
 233     mg_stop(ctx);
 234
 235     /* Un-initialize the library */
 236     mg_exit_library();
 237 }
 238 ```
 239
 240 A simple callback
 241 ```C
 242 static int
 243 handler(struct mg_connection *conn, void *ignored)
 244 {
 245         const char *msg = "Hello world";
 246         unsigned long len = (unsigned long)strlen(msg);
 247
 248         mg_printf(conn,
 249                   "HTTP/1.1 200 OK\r\n"
 250                   "Content-Length: %lu\r\n"
 251                   "Content-Type: text/plain\r\n"
 252                   "Connection: close\r\n\r\n",
 253                   len);
 254
 255         mg_write(conn, msg, len);
 256
 257         return 200;
 258 }
 259 ```
 260