README.coding

   1 Daemonization
   2 -------------
   3
   4 There's a helper api lws_daemonize built by default that does everything you
   5 need to daemonize well, including creating a lock file.  If you're making
   6 what's basically a daemon, just call this early in your init to fork to a
   7 headless background process and exit the starting process.
   8
   9 Notice stdout, stderr, stdin are all redirected to /dev/null to enforce your
  10 daemon is headless, so you'll need to sort out alternative logging, by, eg,
  11 syslog.
  12
  13
  14 Maximum number of connections
  15 -----------------------------
  16
  17 The maximum number of connections the library can deal with is decided when
  18 it starts by querying the OS to find out how many file descriptors it is
  19 allowed to open (1024 on Fedora for example).  It then allocates arrays that
  20 allow up to that many connections, minus whatever other file descriptors are
  21 in use by the user code.
  22
  23 If you want to restrict that allocation, or increase it, you can use ulimit or
  24 similar to change the avaiable number of file descriptors, and when restarted
  25 libwebsockets will adapt accordingly.
  26
  27
  28 Libwebsockets is singlethreaded
  29 -------------------------------
  30
  31 Directly performing websocket actions from other threads is not allowed.
  32 Aside from the internal data being inconsistent in forked() processes,
  33 the scope of a wsi (struct websocket) can end at any time during service
  34 with the socket closing and the wsi freed.
  35
  36 Websocket write activities should only take place in the
  37 "LWS_CALLBACK_SERVER_WRITEABLE" callback as described below.
  38
  39 Only live connections appear in the user callbacks, so this removes any
  40 possibility of trying to used closed and freed wsis.
  41
  42 If you need to service other socket or file descriptors as well as the
  43 websocket ones, you can combine them together with the websocket ones
  44 in one poll loop, see "External Polling Loop support" below, and
  45 still do it all in one thread / process context.
  46
  47
  48 Only send data when socket writeable
  49 ------------------------------------
  50
  51 You should only send data on a websocket connection from the user callback
  52 "LWS_CALLBACK_SERVER_WRITEABLE" (or "LWS_CALLBACK_CLIENT_WRITEABLE" for
  53 clients).
  54
  55 If you want to send something, do not just send it but request a callback
  56 when the socket is writeable using
  57
  58  - libwebsocket_callback_on_writable(context, wsi) for a specific wsi, or
  59  - libwebsocket_callback_on_writable_all_protocol(protocol) for all connections
  60 using that protocol to get a callback when next writeable.
  61
  62 Usually you will get called back immediately next time around the service
  63 loop, but if your peer is slow or temporarily inactive the callback will be
  64 delayed accordingly.  Generating what to write and sending it should be done
  65 in the ...WRITEABLE callback.
  66
  67 See the test server code for an example of how to do this.
  68
  69
  70 Closing connections from the user side
  71 --------------------------------------
  72
  73 When you want to close a connection, you do it by returning -1 from a
  74 callback for that connection.
  75
  76 You can provoke a callback by calling libwebsocket_callback_on_writable on
  77 the wsi, then notice in the callback you want to close it and just return -1.
  78 But usually, the decision to close is made in a callback already and returning
  79 -1 is simple.
  80
  81 If the socket knows the connection is dead, because the peer closed or there
  82 was an affirmitive network error like a FIN coming, then libwebsockets  will
  83 take care of closing the connection automatically.
  84
  85 If you have a silently dead connection, it's possible to enter a state where
  86 the send pipe on the connection is choked but no ack will ever come, so the
  87 dead connection will never become writeable.  To cover that, you can use TCP
  88 keepalives (see later in this document)
  89
  90
  91 Fragmented messages
  92 -------------------
  93
  94 To support fragmented messages you need to check for the final
  95 frame of a message with libwebsocket_is_final_fragment. This
  96 check can be combined with libwebsockets_remaining_packet_payload
  97 to gather the whole contents of a message, eg:
  98
  99     case LWS_CALLBACK_RECEIVE:
 100     {
 101         Client * const client = (Client *)user;
 102         const size_t remaining = libwebsockets_remaining_packet_payload(wsi);
 103
 104         if (!remaining && libwebsocket_is_final_fragment(wsi)) {
 105             if (client->HasFragments()) {
 106                 client->AppendMessageFragment(in, len, 0);
 107                 in = (void *)client->GetMessage();
 108                 len = client->GetMessageLength();
 109             }
 110
 111             client->ProcessMessage((char *)in, len, wsi);
 112             client->ResetMessage();
 113         } else
 114             client->AppendMessageFragment(in, len, remaining);
 115     }
 116     break;
 117
 118 The test app llibwebsockets-test-fraggle sources also show how to
 119 deal with fragmented messages.
 120
 121
 122 Debug Logging
 123 -------------
 124
 125 Also using lws_set_log_level api you may provide a custom callback to actually
 126 emit the log string.  By default, this points to an internal emit function
 127 that sends to stderr.  Setting it to NULL leaves it as it is instead.
 128
 129 A helper function lwsl_emit_syslog() is exported from the library to simplify
 130 logging to syslog.  You still need to use setlogmask, openlog and closelog
 131 in your user code.
 132
 133 The logging apis are made available for user code.
 134
 135 lwsl_err(...)
 136 lwsl_warn(...)
 137 lwsl_notice(...)
 138 lwsl_info(...)
 139 lwsl_debug(...)
 140
 141 The difference between notice and info is that notice will be logged by default
 142 whereas info is ignored by default.
 143
 144
 145 External Polling Loop support
 146 -----------------------------
 147
 148 libwebsockets maintains an internal poll() array for all of its
 149 sockets, but you can instead integrate the sockets into an
 150 external polling array.  That's needed if libwebsockets will
 151 cooperate with an existing poll array maintained by another
 152 server.
 153
 154 Four callbacks LWS_CALLBACK_ADD_POLL_FD, LWS_CALLBACK_DEL_POLL_FD,
 155 LWS_CALLBACK_SET_MODE_POLL_FD and LWS_CALLBACK_CLEAR_MODE_POLL_FD
 156 appear in the callback for protocol 0 and allow interface code to
 157 manage socket descriptors in other poll loops.
 158
 159
 160 Using with in c++ apps
 161 ----------------------
 162
 163 The library is ready for use by C++ apps.  You can get started quickly by
 164 copying the test server
 165
 166 $ cp test-server/test-server.c test.cpp
 167
 168 and building it in C++ like this
 169
 170 $ g++ -DINSTALL_DATADIR=\"/usr/share\" -ocpptest test.cpp -lwebsockets
 171
 172 INSTALL_DATADIR is only needed because the test server uses it as shipped, if
 173 you remove the references to it in your app you don't need to define it on
 174 the g++ line either.
 175
 176
 177 Availability of header information
 178 ----------------------------------
 179
 180 From v1.2 of the library onwards, the HTTP header content is free()d as soon
 181 as the websocket connection is established.  For websocket servers, you can
 182 copy interesting headers by handling LWS_CALLBACK_FILTER_PROTOCOL_CONNECTION
 183 callback, for clients there's a new callback just for this purpose
 184 LWS_CALLBACK_CLIENT_FILTER_PRE_ESTABLISH.
 185
 186
 187 TCP Keepalive
 188 -------------
 189
 190 It is possible for a connection which is not being used to send to die
 191 silently somewhere between the peer and the side not sending.  In this case
 192 by default TCP will just not report anything and you will never get any more
 193 incoming data or sign the link is dead until you try to send.
 194
 195 To deal with getting a notification of that situation, you can choose to
 196 enable TCP keepalives on all libwebsockets sockets, when you create the
 197 context.
 198
 199 To enable keepalive, set the ka_time member of the context creation parameter
 200 struct to a nonzero value (in seconds) at context creation time.  You should
 201 also fill ka_probes and ka_interval in that case.
 202
 203 With keepalive enabled, the TCP layer will send control packets that should
 204 stimulate a response from the peer without affecting link traffic.  If the
 205 response is not coming, the socket will announce an error at poll() forcing
 206 a close.
 207
 208 Note that BSDs don't support keepalive time / probes / inteveral per-socket
 209 like Linux does.  On those systems you can enable keepalive by a nonzero
 210 value in ka_time, but the systemwide kernel settings for the time / probes/
 211 interval are used, regardless of what nonzero value is in ka_time.
 212
 213 Optimizing SSL connections
 214 --------------------------
 215
 216 There's a member ssl_cipher_list in the lws_context_creation_info struct
 217 which allows the user code to restrict the possible cipher selection at
 218 context-creation time.
 219
 220 You might want to look into that to stop the ssl peers selecting a ciher which
 221 is too computationally expensive.  To use it, point it to a string like
 222
 223 "RC4-MD5:RC4-SHA:AES128-SHA:AES256-SHA:HIGH:!DSS:!aNULL"
 224
 225 if left NULL, then the "DEFAULT" set of ciphers are all possible to select.
 226