doc/outdated/state.txt

   1 ============================
   2 The State Engine of lighttpd
   3 ============================
   4
   5 ------------
   6 Module: core
   7 ------------
   8
   9 :Author: Jan Kneschke
  10 :Date: $Date: 2004/08/01 07:01:29 $
  11 :Revision: $Revision: 1.1 $
  12
  13 :abstract:
  14   This is a short summary of the state-engine which is driving the lighttpd
  15   webserver. It describes the basic concepts and the way the different parts
  16   of the server are connected.
  17
  18 .. meta::
  19   :keywords: lighttpd, state-engine
  20
  21 .. contents:: Table of Contents
  22
  23 Description
  24 ===========
  25
  26 States
  27 ------
  28
  29 The state-engine is currently made of 11 states which are walk-through on
  30 the way each connection. Some of them are specific for a special operation
  31 and some may never be hit at all.
  32
  33 :connect:
  34   waiting for a connection
  35 :reqstart:
  36   init the read-idle timer
  37 :read:
  38   read http-request-header from network
  39 :reqend:
  40   parse request
  41 :readpost:
  42   read http-request-content from network
  43 :handlereq:
  44   handle the request internally (might result in sub-requests)
  45 :respstart:
  46   prepare response header
  47 :write:
  48   write response-header + content to network
  49 :respend:
  50   cleanup environment, log request
  51 :error:
  52   reset connection (incl. close())
  53 :close:
  54   close connection (handle lingering close)
  55
  56 .. image:: state.png
  57
  58 A simple GET request (green path)
  59 ---------------------------------
  60
  61 The connection is idling in the 'connect' state waiting for a connection.
  62 As soon as the connection is set up we init the read-timer in 'reqstart'
  63 and start to read data from the network. As soon as we get the
  64 HTTP-request terminator (CRLFCRLF) we forward the header to the parser.
  65
  66 The parsed request is handled by 'handlereq' and as soon as a decision out
  67 the request is made it is sent to 'respstart' to prepare the
  68 HTTP-response header. In the 'write' state the prepare content is sent out
  69 to the network. When everything is sent 'respend' is entered to log the
  70 request and cleanup the environment. After the close() call the connection
  71 is set back to the 'connect' state again.
  72
  73 Keep-Alive (blue path)
  74 ----------------------
  75
  76 The Keep-Alive handling is implemented by going from the 'respend'
  77 directly to 'reqstart' without the close() and the accept() calls.
  78
  79 POST requests (grey path)
  80 -------------------------
  81
  82 As requests might contain a request-body the state 'readpost' entered as
  83 soon as the header is parsed and we know how much data we expect.
  84
  85 Pipelining
  86 ----------
  87
  88 HTTP/1.1 supportes pipelining (sending multiple requests without waiting
  89 for the response of the first request). This is handled transparently by
  90 the 'read' state.
  91
  92 Unexpected errors (red path)
  93 ----------------------------
  94
  95 For really hard errors we use the 'error' state which resets the
  96 connection and can be call from every state. It is only use if there is no
  97 other way to handle the issue (e.g. client-side close of the connection).
  98 If possible we should use http-status 500 ('internal server error') and
  99 log the issue in the errorlog.
 100
 101 If we have to take care of some data which is coming in after we ran into
 102 the error condition the 'close' state is used the init a half-close and
 103 read all the delay packet from the network.
 104
 105 Sub-Requests (lightblue)
 106 ------------------------
 107
 108 The FastCGI, CGI, ... intergration is done by introducing a loop in
 109 'handlereq' to handle all aspect which are neccesary to find out what has
 110 to be sent back to the client.
 111
 112 Functions
 113 =========
 114
 115 Important functions used by the state-engine
 116
 117 :state-engine:
 118
 119 - ``connection_state_machine()``
 120
 121 :connect:
 122
 123 - (nothing)
 124
 125 :reqstart:
 126
 127 - (nothing)
 128
 129 :read:
 130
 131 - ``connection_handle_read_state()``
 132 - ``connection_handle_read()``
 133
 134 :reqend:
 135
 136 - ``http_request_parse()``
 137
 138 :readpost:
 139
 140 - ``connection_handle_read_state()``
 141 - ``connection_handle_read()``
 142
 143 :handlereq:
 144
 145 - ``http_response_prepare()``
 146
 147 :respstart:
 148
 149 - ``connection_handle_write_prepare()``
 150
 151 :write:
 152
 153 - ``connection_handle_write()``
 154
 155 :respend:
 156
 157 - ``plugins_call_handle_request_done()``
 158 - ``plugins_call_handle_connection_close()``
 159 - ``connection_close()`` (if not keep-alive)
 160 - ``connection_reset()``
 161
 162 :error:
 163
 164 - ``plugins_call_handle_request_done()``
 165 - ``plugins_call_handle_connection_close()``
 166 - ``connection_reset()``
 167
 168 :close:
 169
 170 - ``connection_close()``