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 +