* luci/libs/http: added inline documentation to luci.http.protocol & friends, fixed urlencode_params()
This commit is contained in:
Jo-Philipp Wich
parent
a93196b432
commit
ab9891e0af
4 changed files with 195 additions and 48 deletions
|
|
@ -13,14 +13,21 @@ $Id$
|
|||
|
||||
]]--
|
||||
|
||||
--- LuCI http protocol class.
|
||||
-- This class contains several functions useful for http message- and content
|
||||
-- decoding and to retrive form data from raw http messages.
|
||||
module("luci.http.protocol", package.seeall)
|
||||
|
||||
local ltn12 = require("luci.ltn12")
|
||||
|
||||
HTTP_MAX_CONTENT = 1024*8 -- 8 kB maximum content size
|
||||
|
||||
-- Decode an urlencoded string.
|
||||
-- Returns the decoded value.
|
||||
--- Decode an urlencoded string - optionally without decoding
|
||||
-- the "+" sign to " " - and return the decoded string.
|
||||
-- @param str Input string in x-www-urlencoded format
|
||||
-- @param no_plus Don't decode "+" signs to spaces
|
||||
-- @return The decoded string
|
||||
-- @see urlencode
|
||||
function urldecode( str, no_plus )
|
||||
|
||||
local function __chrdec( hex )
|
||||
|
|
@ -38,9 +45,15 @@ function urldecode( str, no_plus )
|
|||
return str
|
||||
end
|
||||
|
||||
|
||||
-- Extract and split urlencoded data pairs, separated bei either "&" or ";" from given url.
|
||||
-- Returns a table value with urldecoded values.
|
||||
--- 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.
|
||||
-- @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
|
||||
function urldecode_params( url, tbl )
|
||||
|
||||
local params = tbl or { }
|
||||
|
|
@ -72,9 +85,10 @@ function urldecode_params( url, tbl )
|
|||
return params
|
||||
end
|
||||
|
||||
|
||||
-- Encode given string in urlencoded format.
|
||||
-- Returns the encoded string.
|
||||
--- Encode given string to x-www-urlencoded format.
|
||||
-- @param str String to encode
|
||||
-- @return String containing the encoded data
|
||||
-- @see urldecode
|
||||
function urlencode( str )
|
||||
|
||||
local function __chrenc( chr )
|
||||
|
|
@ -93,23 +107,36 @@ function urlencode( str )
|
|||
return str
|
||||
end
|
||||
|
||||
|
||||
-- Encode given table to urlencoded string.
|
||||
-- Returns the encoded string.
|
||||
--- 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.
|
||||
-- @param tbl Table with the values
|
||||
-- @return String containing encoded values
|
||||
-- @see urldecode_params
|
||||
function urlencode_params( tbl )
|
||||
local enc = ""
|
||||
|
||||
for k, v in pairs(tbl) do
|
||||
enc = enc .. ( enc and "&" or "" ) ..
|
||||
urlencode(k) .. "=" ..
|
||||
urlencode(v)
|
||||
if type(v) == "table" then
|
||||
for i, v2 in ipairs(v) do
|
||||
enc = enc .. ( #enc > 0 and "&" or "" ) ..
|
||||
urlencode(k) .. "=" .. urlencode(v2)
|
||||
end
|
||||
else
|
||||
enc = enc .. ( #enc > 0 and "&" or "" ) ..
|
||||
urlencode(k) .. "=" .. urlencode(v)
|
||||
end
|
||||
end
|
||||
|
||||
return enc
|
||||
end
|
||||
|
||||
|
||||
-- Parameter helper
|
||||
--- (Internal function)
|
||||
-- Initialize given parameter and coerce string into table when the parameter
|
||||
-- already exists.
|
||||
-- @param tbl Table where parameter should be created
|
||||
-- @param key Parameter name
|
||||
-- @return Always nil
|
||||
local function __initval( tbl, key )
|
||||
if tbl[key] == nil then
|
||||
tbl[key] = ""
|
||||
|
|
@ -120,6 +147,14 @@ local function __initval( tbl, key )
|
|||
end
|
||||
end
|
||||
|
||||
--- (Internal function)
|
||||
-- Append given data to given parameter, either by extending the string value
|
||||
-- or by appending it to the last string in the parameter's value table.
|
||||
-- @param tbl Table containing the previously initialized parameter value
|
||||
-- @param key Parameter name
|
||||
-- @param chunk String containing the data to append
|
||||
-- @return Always nil
|
||||
-- @see __initval
|
||||
local function __appendval( tbl, key, chunk )
|
||||
if type(tbl[key]) == "table" then
|
||||
tbl[key][#tbl[key]] = tbl[key][#tbl[key]] .. chunk
|
||||
|
|
@ -128,6 +163,16 @@ local function __appendval( tbl, key, chunk )
|
|||
end
|
||||
end
|
||||
|
||||
--- (Internal function)
|
||||
-- Finish the value of given parameter, either by transforming the string value
|
||||
-- or - in the case of multi value parameters - the last element in the
|
||||
-- associated values table.
|
||||
-- @param tbl Table containing the previously initialized parameter value
|
||||
-- @param key Parameter name
|
||||
-- @param handler Function which transforms the parameter value
|
||||
-- @return Always nil
|
||||
-- @see __initval
|
||||
-- @see __appendval
|
||||
local function __finishval( tbl, key, handler )
|
||||
if handler then
|
||||
if type(tbl[key]) == "table" then
|
||||
|
|
@ -226,7 +271,10 @@ process_states['headers'] = function( msg, chunk )
|
|||
end
|
||||
|
||||
|
||||
-- Creates a header source from a given socket
|
||||
--- Creates a ltn12 source from the given socket. The source will return it's
|
||||
-- data line by line with the trailing \r\n stripped of.
|
||||
-- @param sock Readable network socket
|
||||
-- @return Ltn12 source function
|
||||
function header_source( sock )
|
||||
return ltn12.source.simplify( function()
|
||||
|
||||
|
|
@ -253,8 +301,23 @@ function header_source( sock )
|
|||
end )
|
||||
end
|
||||
|
||||
|
||||
-- Decode MIME encoded data.
|
||||
--- 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 withing 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 the mime headers of the corresponding section
|
||||
-- o String value containing a chunk of the file data
|
||||
-- o Boolean which indicates wheather the current chunk is the last one (eof)
|
||||
-- @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
|
||||
function mimedecode_message_body( src, msg, filecb )
|
||||
|
||||
if msg and msg.env.CONTENT_TYPE then
|
||||
|
|
@ -400,8 +463,15 @@ function mimedecode_message_body( src, msg, filecb )
|
|||
return ltn12.pump.all( src, snk )
|
||||
end
|
||||
|
||||
|
||||
-- Decode urlencoded data.
|
||||
--- 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 withing the given message object. Multiple parameter
|
||||
-- values are stored as tables, ordinary ones as strings.
|
||||
-- @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
|
||||
function urldecode_message_body( src, msg )
|
||||
|
||||
local tlen = 0
|
||||
|
|
@ -451,9 +521,13 @@ function urldecode_message_body( src, msg )
|
|||
return ltn12.pump.all( src, snk )
|
||||
end
|
||||
|
||||
|
||||
-- Parse a http message header
|
||||
function parse_message_header( source )
|
||||
--- Try to extract an http message header including information like protocol
|
||||
-- version, message headers and resulting CGI environment variables from the
|
||||
-- given ltn12 source.
|
||||
-- @param src Ltn12 source function
|
||||
-- @return HTTP message object
|
||||
-- @see parse_message_body
|
||||
function parse_message_header( src )
|
||||
|
||||
local ok = true
|
||||
local msg = { }
|
||||
|
|
@ -468,7 +542,7 @@ function parse_message_header( source )
|
|||
while ok do
|
||||
|
||||
-- get data
|
||||
ok, err = ltn12.pump.step( source, sink )
|
||||
ok, err = ltn12.pump.step( src, sink )
|
||||
|
||||
-- error
|
||||
if not ok and err then
|
||||
|
|
@ -520,21 +594,32 @@ function parse_message_header( source )
|
|||
return msg
|
||||
end
|
||||
|
||||
|
||||
-- Parse a http message body
|
||||
function parse_message_body( source, msg, filecb )
|
||||
--- 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.
|
||||
-- @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
|
||||
function parse_message_body( src, msg, filecb )
|
||||
-- Is it multipart/mime ?
|
||||
if msg.env.REQUEST_METHOD == "POST" and msg.env.CONTENT_TYPE and
|
||||
msg.env.CONTENT_TYPE:match("^multipart/form%-data")
|
||||
then
|
||||
|
||||
return mimedecode_message_body( source, msg, filecb )
|
||||
return mimedecode_message_body( src, msg, filecb )
|
||||
|
||||
-- Is it application/x-www-form-urlencoded ?
|
||||
elseif msg.env.REQUEST_METHOD == "POST" and msg.env.CONTENT_TYPE and
|
||||
msg.env.CONTENT_TYPE == "application/x-www-form-urlencoded"
|
||||
then
|
||||
return urldecode_message_body( source, msg, filecb )
|
||||
return urldecode_message_body( src, msg, filecb )
|
||||
|
||||
|
||||
-- Unhandled encoding
|
||||
|
|
@ -568,7 +653,7 @@ function parse_message_body( source, msg, filecb )
|
|||
|
||||
-- Pump data...
|
||||
while true do
|
||||
local ok, err = ltn12.pump.step( source, sink )
|
||||
local ok, err = ltn12.pump.step( src, sink )
|
||||
|
||||
if not ok and err then
|
||||
return nil, err
|
||||
|
|
@ -576,10 +661,13 @@ function parse_message_body( source, msg, filecb )
|
|||
return true
|
||||
end
|
||||
end
|
||||
|
||||
return true
|
||||
end
|
||||
end
|
||||
|
||||
-- Status codes
|
||||
--- Table containing human readable messages for several http status codes.
|
||||
-- @class table
|
||||
statusmsg = {
|
||||
[200] = "OK",
|
||||
[301] = "Moved Permanently",
|
||||
|
|
|
|||
|
|
@ -13,19 +13,30 @@ $Id$
|
|||
|
||||
]]--
|
||||
|
||||
--- LuCI http protocol implementation - HTTP/1.1 bits.
|
||||
-- This class provides basic ETag handling and implements most of the
|
||||
-- conditional HTTP/1.1 headers specified in RFC2616 Sct. 14.24 - 14.28 .
|
||||
module("luci.http.protocol.conditionals", package.seeall)
|
||||
|
||||
local date = require("luci.http.protocol.date")
|
||||
|
||||
|
||||
-- 14.19 / ETag
|
||||
--- Implement 14.19 / ETag.
|
||||
-- @param stat A file.stat structure
|
||||
-- @return String containing the generated tag suitable for ETag headers
|
||||
function mk_etag( stat )
|
||||
if stat ~= nil then
|
||||
return string.format( '"%x-%x-%x"', stat.ino, stat.size, stat.mtime )
|
||||
end
|
||||
end
|
||||
|
||||
-- 14.24 / If-Match
|
||||
--- 14.24 / If-Match
|
||||
-- Test whether the given message object contains an "If-Match" header and
|
||||
-- compare it against the given stat object.
|
||||
-- @param req HTTP request message object
|
||||
-- @param stat A file.stat object
|
||||
-- @return Boolean indicating wheather the precondition is ok
|
||||
-- @return Alternative status code if the precondition failed
|
||||
function if_match( req, stat )
|
||||
local h = req.headers
|
||||
local etag = mk_etag( stat )
|
||||
|
|
@ -44,7 +55,14 @@ function if_match( req, stat )
|
|||
return true
|
||||
end
|
||||
|
||||
-- 14.25 / If-Modified-Since
|
||||
--- 14.25 / If-Modified-Since
|
||||
-- Test whether the given message object contains an "If-Modified-Since" header
|
||||
-- and compare it against the given stat object.
|
||||
-- @param req HTTP request message object
|
||||
-- @param stat A file.stat object
|
||||
-- @return Boolean indicating wheather the precondition is ok
|
||||
-- @return Alternative status code if the precondition failed
|
||||
-- @return Table containing extra HTTP headers if the precondition failed
|
||||
function if_modified_since( req, stat )
|
||||
local h = req.headers
|
||||
|
||||
|
|
@ -66,7 +84,14 @@ function if_modified_since( req, stat )
|
|||
return true
|
||||
end
|
||||
|
||||
-- 14.26 / If-None-Match
|
||||
--- 14.26 / If-None-Match
|
||||
-- Test whether the given message object contains an "If-None-Match" header and
|
||||
-- compare it against the given stat object.
|
||||
-- @param req HTTP request message object
|
||||
-- @param stat A file.stat object
|
||||
-- @return Boolean indicating wheather the precondition is ok
|
||||
-- @return Alternative status code if the precondition failed
|
||||
-- @return Table containing extra HTTP headers if the precondition failed
|
||||
function if_none_match( req, stat )
|
||||
local h = req.headers
|
||||
local etag = mk_etag( stat )
|
||||
|
|
@ -94,12 +119,25 @@ function if_none_match( req, stat )
|
|||
end
|
||||
|
||||
-- 14.27 / If-Range
|
||||
-- The If-Range header is currently not implemented due to the lack of general
|
||||
-- byte range stuff in luci.http.protocol . This function will always return
|
||||
-- false, 412 to indicate a failed precondition.
|
||||
-- @param req HTTP request message object
|
||||
-- @param stat A file.stat object
|
||||
-- @return Boolean indicating wheather the precondition is ok
|
||||
-- @return Alternative status code if the precondition failed
|
||||
function if_range( req, stat )
|
||||
-- Sorry, no subranges (yet)
|
||||
return false, 412
|
||||
end
|
||||
|
||||
-- 14.28 / If-Unmodified-Since
|
||||
-- Test whether the given message object contains an "If-Unmodified-Since"
|
||||
-- header and compare it against the given stat object.
|
||||
-- @param req HTTP request message object
|
||||
-- @param stat A file.stat object
|
||||
-- @return Boolean indicating wheather the precondition is ok
|
||||
-- @return Alternative status code if the precondition failed
|
||||
function if_unmodified_since( req, stat )
|
||||
local h = req.headers
|
||||
|
||||
|
|
|
|||
|
|
@ -13,6 +13,8 @@ $Id$
|
|||
|
||||
]]--
|
||||
|
||||
--- LuCI http protocol implementation - date helper class.
|
||||
-- This class contains functions to parse, compare and format http dates.
|
||||
module("luci.http.protocol.date", package.seeall)
|
||||
|
||||
MONTHS = {
|
||||
|
|
@ -20,7 +22,9 @@ MONTHS = {
|
|||
"Sep", "Oct", "Nov", "Dec"
|
||||
}
|
||||
|
||||
-- This list is stolen from Perl's Time::Timezone
|
||||
--- The "TZ" table contains lowercased timezone names associated with their
|
||||
-- corresponding time offsets sepcified in seconds.
|
||||
-- @class table
|
||||
TZ = {
|
||||
-- DST zones
|
||||
["brst"] = -2*3600; -- Brazil Summer Time (East Daylight)
|
||||
|
|
@ -123,8 +127,9 @@ TZ = {
|
|||
["idle"] = 12*3600; -- International Date Line East
|
||||
}
|
||||
|
||||
|
||||
-- Find corresponding timezone offset
|
||||
--- Return the time offset in seconds between the UTC and given time zone.
|
||||
-- @param tz Symbolic or numeric timezone specifier
|
||||
-- @return Time offset to UTC in seconds
|
||||
function tz_offset(tz)
|
||||
|
||||
if type(tz) == "string" then
|
||||
|
|
@ -148,7 +153,9 @@ function tz_offset(tz)
|
|||
return 0
|
||||
end
|
||||
|
||||
-- Convert a HTTP date to unixtime
|
||||
--- Parse given HTTP date string and convert it to unix epoch time.
|
||||
-- @param data String containing the date
|
||||
-- @return Unix epoch time
|
||||
function to_unix(date)
|
||||
|
||||
local wd, day, mon, yr, hr, min, sec, tz = date:match(
|
||||
|
|
@ -182,12 +189,19 @@ function to_unix(date)
|
|||
return 0
|
||||
end
|
||||
|
||||
-- Convert a unixtime to HTTP date
|
||||
--- Convert the given unix epoch time to valid HTTP date string.
|
||||
-- @param time Unix epoch time
|
||||
-- @return String containing the formatted date
|
||||
function to_http(time)
|
||||
return os.date( "%a, %d %b %Y %H:%M:%S GMT", time )
|
||||
end
|
||||
|
||||
-- Compare two dates
|
||||
--- Compare two dates which can either be unix epoch times or HTTP date strings.
|
||||
-- @param d1 The first date or epoch time to compare
|
||||
-- @param d2 The first date or epoch time to compare
|
||||
-- @return -1 - if d1 is lower then d2
|
||||
-- @return 0 - if both dates are equal
|
||||
-- @return 1 - if d1 is higher then d2
|
||||
function compare(d1, d2)
|
||||
|
||||
if d1:match("[^0-9]") then d1 = to_unix(d1) end
|
||||
|
|
|
|||
|
|
@ -13,12 +13,15 @@ $Id$
|
|||
|
||||
]]--
|
||||
|
||||
--- LuCI http protocol implementation - mime helper class.
|
||||
-- This class provides functions to guess mime types from file extensions and
|
||||
-- vice versa.
|
||||
module("luci.http.protocol.mime", package.seeall)
|
||||
|
||||
require("luci.util")
|
||||
|
||||
|
||||
-- MIME mapping
|
||||
--- MIME mapping table containg extension - mimetype relations.
|
||||
-- @class table
|
||||
MIME_TYPES = {
|
||||
["txt"] = "text/plain";
|
||||
["js"] = "text/javascript";
|
||||
|
|
@ -62,8 +65,10 @@ MIME_TYPES = {
|
|||
["avi"] = "video/x-msvideo";
|
||||
}
|
||||
|
||||
-- extract extension from a filename and return corresponding mime-type or
|
||||
-- "application/octet-stream" if the extension is unknown
|
||||
--- Extract extension from a filename and return corresponding mime-type or
|
||||
-- "application/octet-stream" if the extension is unknown.
|
||||
-- @param filename The filename for which the mime type is guessed
|
||||
-- @return String containign the determined mime type
|
||||
function to_mime(filename)
|
||||
if type(filename) == "string" then
|
||||
local ext = filename:match("[^%.]+$")
|
||||
|
|
@ -76,8 +81,10 @@ function to_mime(filename)
|
|||
return "application/octet-stream"
|
||||
end
|
||||
|
||||
-- return corresponding extension for a given mime type or nil if the
|
||||
-- given mime-type is unknown
|
||||
--- Return corresponding extension for a given mime type or nil if the
|
||||
-- given mime-type is unknown.
|
||||
-- @param mimetype The mimetype to retrieve the extension from
|
||||
-- @return String with the extension or nil for unknown type
|
||||
function to_ext(mimetype)
|
||||
if type(mimetype) == "string" then
|
||||
for ext, type in luci.util.kspairs( MIME_TYPES ) do
|
||||
|
|
|
|||
Loading…
Reference in a new issue