Return to state.txt CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / lighttpd / doc / outdated

1.4.33

    1: ============================
    2: The State Engine of lighttpd
    3: ============================
    4: 
    5: ------------
    6: Module: core
    7: ------------
    8: 
    9: :Author: Jan Kneschke
   10: :Date: $Date: 2013/10/14 10:32:48 $
   11: :Revision: $Revision: 1.1.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()``