luci-base: fold luci.http.protocol into luci.http

With only the decoder routines remaining in luci.http.protocol, it makes no
sense to keep the low level protocol class around, so fold the remaining code
into the central luci.http class.

Also adjust the few direct users of luci.http.protocol accordingly.

Signed-off-by: Jo-Philipp Wich <jo@mein.io>

1 files changed, 141 insertions, 46 deletions

diff --git a/modules/luci-base/luasrc/http.luadoc b/modules/luci-base/luasrc/http.luadoc
index 8a325db21..f8121230b 100644
--- a/modules/luci-base/luasrc/http.luadoc
+++ b/modules/luci-base/luasrc/http.luadoc
@@ -6,25 +6,24 @@ module "luci.http"
 ---[[
 Close the HTTP-Connection.
 
-
-@class function
-@name close
+@class			function
+@name			close
 ]]
 
 ---[[
 Return the request content if the request was of unknown type.
 
-@class function
-@name content
-@return	HTTP request body
-@return	HTTP request body length
+@class			function
+@name			content
+@return			HTTP request body
+@return			HTTP request body length
 ]]
 
 ---[[
 Get a certain HTTP input value or a table of all input values.
 
-@class function
-@name formvalue
+@class			function
+@name			formvalue
 @param name		Name of the GET or POST variable to fetch
 @param noparse	Don't parse POST data before getting the value
 @return			HTTP input value or table of all input value
@@ -33,8 +32,8 @@ Get a certain HTTP input value or a table of all input values.
 ---[[
 Get a table of all HTTP input values with a certain prefix.
 
-@class function
-@name formvaluetable
+@class			function
+@name			formvaluetable
 @param prefix	Prefix
 @return			Table of all HTTP input values with given prefix
 ]]
@@ -42,18 +41,18 @@ Get a table of all HTTP input values with a certain prefix.
 ---[[
 Get the value of a certain HTTP-Cookie.
 
-@class function
-@name getcookie
+@class			function
+@name			getcookie
 @param name		Cookie Name
 @return			String containing cookie data
 ]]
 
 ---[[
 Get the value of a certain HTTP environment variable
-
 or the environment table itself.
-@class function
-@name getenv
+
+@class			function
+@name			getenv
 @param name		Environment variable
 @return			HTTP environment value or environment table
 ]]
@@ -61,41 +60,41 @@ or the environment table itself.
 ---[[
 Set a handler function for incoming user file uploads.
 
-@class function
-@name setfilehandler
+@class			function
+@name			setfilehandler
 @param callback	Handler function
 ]]
 
 ---[[
 Send a HTTP-Header.
 
-@class function
-@name header
-@param key	Header key
-@param value Header value
+@class			function
+@name			header
+@param key		Header key
+@param value	Header value
 ]]
 
 ---[[
 Set the mime type of following content data.
 
-@class function
-@name prepare_content
-@param mime	Mimetype of following content
+@class			function
+@name			prepare_content
+@param mime		Mimetype of following content
 ]]
 
 ---[[
 Get the RAW HTTP input source
 
-@class function
-@name source
-@return	HTTP LTN12 source
+@class			function
+@name			source
+@return			HTTP LTN12 source
 ]]
 
 ---[[
 Set the HTTP status code and status message.
 
-@class function
-@name status
+@class			function
+@name			status
 @param code		Status code
 @param message	Status message
 ]]
@@ -105,8 +104,9 @@ Send a chunk of content data to the client.
 
 This function is as a valid LTN12 sink.
 If the content chunk is nil this function will automatically invoke close.
-@class function
-@name write
+
+@class			function
+@name			write
 @param content	Content chunk
 @param src_err	Error object from source (optional)
 @see close
@@ -115,51 +115,146 @@ If the content chunk is nil this function will automatically invoke close.
 ---[[
 Splice data from a filedescriptor to the client.
 
-@class function
-@name splice
-@param fp	File descriptor
-@param size	Bytes to splice (optional)
+@class			function
+@name			splice
+@param fp		File descriptor
+@param size		Bytes to splice (optional)
 ]]
 
 ---[[
 Redirects the client to a new URL and closes the connection.
 
-@class function
-@name redirect
-@param url	Target URL
+@class			function
+@name			redirect
+@param url		Target URL
 ]]
 
 ---[[
 Create a querystring out of a table of key - value pairs.
 
-@class function
-@name build_querystring
-@param table		Query string source table
+@class			function
+@name			build_querystring
+@param table	Query string source table
 @return			Encoded HTTP query string
 ]]
 
 ---[[
 Return the URL-decoded equivalent of a string.
 
+@class			function
+@name			urldecode
 @param str		URL-encoded string
 @param no_plus	Don't decode + to " "
 @return			URL-decoded string
-@see urlencode
+@see			urlencode
 ]]
 
 ---[[
 Return the URL-encoded equivalent of a string.
 
+@class			function
+@name			urlencode
 @param str		Source string
 @return			URL-encoded string
-@see urldecode
+@see			urldecode
 ]]
 
 ---[[
 Send the given data as JSON encoded string.
 
-@class function
-@name write_json
+@class			function
+@name			write_json
 @param data		Data to send
 ]]
 
+---[[
+Extract and split urlencoded data pairs, separated bei either "&" or ";"
+from given url or string. Returns a table with urldecoded values.
+
+Simple parameters are stored as string values associated with the parameter
+name within the table. Parameters with multiple values are stored as array
+containing the corresponding values.
+
+@class			function
+@name			urldecode_params
+@param url		The url or string which contains x-www-urlencoded form data
+@param tbl		Use the given table for storing values (optional)
+@return			Table containing the urldecoded parameters
+@see			urlencode_params
+]]
+
+---[[
+Encode each key-value-pair in given table to x-www-urlencoded format,
+separated by "&".
+
+Tables are encoded as parameters with multiple values by repeating the
+parameter name with each value.
+
+@class			function
+@name			urlencode_params
+@param tbl		Table with the values
+@return			String containing encoded values
+@see			urldecode_params
+]]
+
+---[[
+Decode a mime encoded http message body with multipart/form-data Content-Type.
+
+Stores all extracted data associated with its parameter name
+in the params table within the given message object. Multiple parameter
+values are stored as tables, ordinary ones as strings.
+
+If an optional file callback function is given then it is feeded with the
+file contents chunk by chunk and only the extracted file name is stored
+within the params table. The callback function will be called subsequently
+with three arguments:
+ o Table containing decoded (name, file) and raw (headers) mime header data
+ o String value containing a chunk of the file data
+ o Boolean which indicates wheather the current chunk is the last one (eof)
+
+@class			function
+@name			mimedecode_message_body
+@param src		Ltn12 source function
+@param msg		HTTP message object
+@param filecb	File callback function (optional)
+@return			Value indicating successful operation (not nil means "ok")
+@return			String containing the error if unsuccessful
+@see			parse_message_header
+]]
+
+---[[
+Decode an urlencoded http message body with application/x-www-urlencoded
+Content-Type.
+
+Stores all extracted data associated with its parameter name in the params
+table within the given message object. Multiple parameter values are stored
+as tables, ordinary ones as strings.
+
+@class			function
+@name			urldecode_message_body
+@param src		Ltn12 source function
+@param msg		HTTP message object
+@return			Value indicating successful operation (not nil means "ok")
+@return			String containing the error if unsuccessful
+@see			parse_message_header
+]]
+
+---[[
+Try to extract and decode a http message body from the given ltn12 source.
+This function will examine the Content-Type within the given message object
+to select the appropriate content decoder.
+
+Currently the application/x-www-urlencoded and application/form-data
+mime types are supported. If the encountered content encoding can't be
+handled then the whole message body will be stored unaltered as "content"
+property within the given message object.
+
+@class			function
+@name			parse_message_body
+@param src		Ltn12 source function
+@param msg		HTTP message object
+@param filecb	File data callback (optional, see mimedecode_message_body())
+@return			Value indicating successful operation (not nil means "ok")
+@return			String containing the error if unsuccessful
+@see			parse_message_header
+]]