moonbridge

changeset 184:97d3ca77c86a

Code cleanup, renamed functions, added documentation for HTTP module
author jbe
date Fri Jun 19 18:24:58 2015 +0200 (2015-06-19)
parents 478d6237e17a
children 1019bac12a82
files moonbridge_http.lua reference.txt
line diff
     1.1 --- a/moonbridge_http.lua	Fri Jun 19 16:54:33 2015 +0200
     1.2 +++ b/moonbridge_http.lua	Fri Jun 19 18:24:58 2015 +0200
     1.3 @@ -647,7 +647,7 @@
     1.4                local afterbound = false  -- interpret 2 bytes after boundary ("\r\n" or "--")
     1.5                local terminated = false  -- final boundary read
     1.6                local bigchunk = ""
     1.7 -              request:set_request_body_streamer(function(chunk)
     1.8 +              request:stream_request_body(function(chunk)
     1.9                  if chunk == nil then
    1.10                    if not terminated then
    1.11                      request_error(true, "400 Bad Request", "Premature end of multipart/form-data request body")
    1.12 @@ -808,6 +808,15 @@
    1.13          send(socket:write(key, ": ", value, "\r\n"))
    1.14          state = old_state
    1.15        end
    1.16 +      -- method to announce (and enforce) connection close after sending the
    1.17 +      -- response:
    1.18 +      function request:close_after_finish()
    1.19 +        assert_not_faulty()
    1.20 +        if state == "headers_sent" or state == "finished" then
    1.21 +          error("All HTTP headers have already been sent")
    1.22 +        end
    1.23 +        close_requested = true
    1.24 +      end
    1.25        -- function to terminate header section in response, optionally flushing:
    1.26        -- (may be called multiple times unless response is finished)
    1.27        local function finish_headers(with_flush)
    1.28 @@ -935,7 +944,7 @@
    1.29          streamed_post_param_patterns[#streamed_post_param_patterns+1] = {pattern, callback}
    1.30        end
    1.31        -- method to register request body stream handler
    1.32 -      function request:set_request_body_streamer(callback)
    1.33 +      function request:stream_request_body(callback)
    1.34          if state ~= "init" then
    1.35            error("Cannot setup request body streamer at this stage anymore")
    1.36          end
    1.37 @@ -962,8 +971,8 @@
    1.38          consume_all()
    1.39        end
    1.40        -- method to stream request body
    1.41 -      function request:stream_request_body(callback)
    1.42 -        request:set_request_body_streamer(function(chunk)
    1.43 +      function request:stream_request_body_now(callback)
    1.44 +        request:stream_request_body(function(chunk)
    1.45            if chunk ~= nil then
    1.46              callback(chunk)
    1.47            end
    1.48 @@ -972,9 +981,13 @@
    1.49        end
    1.50        -- metamethod to read special attibutes of request object:
    1.51        function request_mt:__index(key, value)
    1.52 -        if key == "body" then
    1.53 +        if key == "faulty" then
    1.54 +          return state == "faulty"
    1.55 +        elseif key == "fresh" then
    1.56 +          return state == "init" and process_body_chunk == nil
    1.57 +        elseif key == "body" then
    1.58            local chunks = {}
    1.59 -          request:stream_request_body(function(chunk)
    1.60 +          request:stream_request_body_now(function(chunk)
    1.61              chunks[#chunks+1] = chunk
    1.62            end)
    1.63            self.body = table.concat(chunks)
     2.1 --- a/reference.txt	Fri Jun 19 16:54:33 2015 +0200
     2.2 +++ b/reference.txt	Fri Jun 19 18:24:58 2015 +0200
     2.3 @@ -432,34 +432,32 @@
     2.4  
     2.5  A corresponding "Connection: close" header is automatically sent.
     2.6  
     2.7 +See also request:monologue().
     2.8 +
     2.9 +
    2.10 +### request:consume_input()
    2.11 +
    2.12 +Starts processing the request body (if existent) to set the values
    2.13 +request.post_params, request.post_params_list, request.post_metadata, and
    2.14 +and request.post_metadata_list and/or to call POST field stream handlers that
    2.15 +have been previously registered with request:stream_post_param(...) or
    2.16 +request:stream_post_params(...), or to call a previously registered request
    2.17 +body stream handler that was set with request:set_request_body_streamer().
    2.18 +
    2.19 +This method gets invoked automatically when the POST param tables
    2.20 +(request.post_params, etc.) are accessed or if request.body is accessed.
    2.21 +
    2.22  
    2.23  ### request.cookies
    2.24  
    2.25  A table with all cookies sent by the client.
    2.26  
    2.27  
    2.28 -### request.defer_reading()
    2.29 -
    2.30 -Disables automatic request body processing on write. Can be called before
    2.31 -sending a HTTP status code to send a response before the request has been fully
    2.32 -received.
    2.33 -
    2.34 -CAUTION: Responding to a request before the request body has been processed may
    2.35 -lead to a deadlock if the browser does not process the response while trying to
    2.36 -send the request. Therefore, this function should only be used if:
    2.37 -
    2.38 -- the TCP stack has enough buffer space for the response (i.e. if the response
    2.39 -  is small enough), and if
    2.40 -- a timer is used to cancel the response in case of a deadlock.
    2.41 -
    2.42 -It is recommended to not use this function unless certain performance tweaks
    2.43 -are desired.
    2.44 -
    2.45 -
    2.46  ### request.faulty
    2.47  
    2.48 -Normally set to false. In case of a read or write error on the client
    2.49 -connection, this value is set to true before a Lua error is raised.
    2.50 +Normally set to false. In case of a write error on the client connection or
    2.51 +certain other unexpected errors, this value is set to true before a Lua error
    2.52 +is raised.
    2.53  
    2.54  A faulty request handle must not be used, or another Lua error will be raised.
    2.55  
    2.56 @@ -485,6 +483,12 @@
    2.57  body, it is required to call request:finish().
    2.58  
    2.59  
    2.60 +### request.fresh
    2.61 +
    2.62 +Set to false whenever the request object has been used (e.g. data has been read
    2.63 +or sent out, or a stream handler was installed); true otherwise.
    2.64 +
    2.65 +
    2.66  ### request.get_params
    2.67  
    2.68  A table that maps field names to their corresponding GET value. If there are
    2.69 @@ -543,6 +547,12 @@
    2.70  The HTTP request method, e.g. "HEAD", "GET", or "POST".
    2.71  
    2.72  
    2.73 +### request:monologue()
    2.74 +
    2.75 +Same as request:close_after_finish() but additionally discards all input data
    2.76 +immediately.
    2.77 +
    2.78 +
    2.79  ### request.path
    2.80  
    2.81  The requested path without a leading slash and without the query part (e.g.
    2.82 @@ -599,25 +609,6 @@
    2.83  request-target in section 5.3.4 in RFC 7230).
    2.84  
    2.85  
    2.86 -### request:process_request_body()
    2.87 -
    2.88 -Starts processing the request body (if existent) to set the values
    2.89 -request.post_params, request.post_params_list, request.post_metadata, and
    2.90 -and request.post_metadata_list and/or to call POST field stream handlers that
    2.91 -have been previously registered with request:stream_post_param(...) or
    2.92 -request:stream_post_params(...).
    2.93 -
    2.94 -This method gets invoked automatically when the POST param tables
    2.95 -(request.post_params, etc.) are accessed, or if a response is sent (to avoid
    2.96 -deadlocks with the webbrowser). (Note: Automatic request body processing on
    2.97 -write may be disabled by calling request:defer_reading().)
    2.98 -
    2.99 -After this method returned, all registered POST field stream handlers have
   2.100 -received all data. Registration of other POST field stream handlers is not
   2.101 -possible after this method has been called (or after request.post_params_list
   2.102 -or request.post_params have been accessed).
   2.103 -
   2.104 -
   2.105  ### request:send_data(...)
   2.106  
   2.107  Sends data as response body. All arguments are converted via tostring(...) and
   2.108 @@ -672,6 +663,9 @@
   2.109    as second argument.
   2.110  - The second time without any arguments.
   2.111  
   2.112 +Note that request:consume_input() needs to be called to enforce streaming to
   2.113 +finish.
   2.114 +
   2.115  
   2.116  ### request:stream_post_params(pattern, callback)
   2.117  
   2.118 @@ -681,15 +675,20 @@
   2.119  
   2.120  ### request:stream_request_body(callback)
   2.121  
   2.122 -Start streaming of request body. For each chunk of the request body, the
   2.123 -callback function is called with the corresponding chunk. End of data is
   2.124 -indicated through return of request:stream_request_body(...) (not by calling
   2.125 -the callback without arguments).
   2.126 +Registeres a stream handler for the whole request body. For each chunk of the
   2.127 +request body, the callback function is called with the corresponding chunk. End
   2.128 +of data is indicated by passing a nil value to the callback functuion.
   2.129  
   2.130 -The function may be called with nil instead of a callback function. In this
   2.131 -case, the request body is read and discarded. Only if nil is passed instead of
   2.132 -a callback, then the function may also be invoked when the request body has
   2.133 -already been read and/or processed. In the latter case, the function performs
   2.134 -no operation.
   2.135 +Note that request:consume_input() needs to be called to enforce streaming to
   2.136 +finish.
   2.137  
   2.138  
   2.139 +### request:stream_request_body_now(callback)
   2.140 +
   2.141 +Start streaming of request body immediately. On EOF the function returns and
   2.142 +the callback function is *not* called with nil as argument.
   2.143 +
   2.144 +Note that request:consume_input() needs to be called to enforce streaming to
   2.145 +finish.
   2.146 +
   2.147 +

Impressum / About Us