3 HTTP protocol implementation for LuCI
4 (c) 2008 Freifunk Leipzig / Jo-Philipp Wich <xm@leipzig.freifunk.net>
6 Licensed under the Apache License, Version 2.0 (the "License");
7 you may not use this file except in compliance with the License.
8 You may obtain a copy of the License at
10 http://www.apache.org/licenses/LICENSE-2.0
16 --- LuCI http protocol class.
17 -- This class contains several functions useful for http message- and content
18 -- decoding and to retrive form data from raw http messages.
19 module("luci.http.protocol", package.seeall)
21 local ltn12 = require("luci.ltn12")
23 HTTP_MAX_CONTENT = 1024*8 -- 8 kB maximum content size
25 --- Decode an urlencoded string - optionally without decoding
26 -- the "+" sign to " " - and return the decoded string.
27 -- @param str Input string in x-www-urlencoded format
28 -- @param no_plus Don't decode "+" signs to spaces
29 -- @return The decoded string
31 function urldecode( str, no_plus )
33 local function __chrdec( hex )
34 return string.char( tonumber( hex, 16 ) )
37 if type(str) == "string" then
39 str = str:gsub( "+", " " )
42 str = str:gsub( "%%([a-fA-F0-9][a-fA-F0-9])", __chrdec )
48 --- Extract and split urlencoded data pairs, separated bei either "&" or ";"
49 -- from given url or string. Returns a table with urldecoded values.
50 -- Simple parameters are stored as string values associated with the parameter
51 -- name within the table. Parameters with multiple values are stored as array
52 -- containing the corresponding values.
53 -- @param url The url or string which contains x-www-urlencoded form data
54 -- @param tbl Use the given table for storing values (optional)
55 -- @return Table containing the urldecoded parameters
56 -- @see urlencode_params
57 function urldecode_params( url, tbl )
59 local params = tbl or { }
62 url = url:gsub( "^.+%?([^?]+)", "%1" )
65 for pair in url:gmatch( "[^&;]+" ) do
68 local key = urldecode( pair:match("^([^=]+)") )
69 local val = urldecode( pair:match("^[^=]+=(.+)$") )
72 if type(key) == "string" and key:len() > 0 then
73 if type(val) ~= "string" then val = "" end
75 if not params[key] then
77 elseif type(params[key]) ~= "table" then
78 params[key] = { params[key], val }
80 table.insert( params[key], val )
88 --- Encode given string to x-www-urlencoded format.
89 -- @param str String to encode
90 -- @return String containing the encoded data
92 function urlencode( str )
94 local function __chrenc( chr )
96 "%%%02x", string.byte( chr )
100 if type(str) == "string" then
102 "([^a-zA-Z0-9$_%-%.%+!*'(),])",
110 --- Encode each key-value-pair in given table to x-www-urlencoded format,
111 -- separated by "&". Tables are encoded as parameters with multiple values by
112 -- repeating the parameter name with each value.
113 -- @param tbl Table with the values
114 -- @return String containing encoded values
115 -- @see urldecode_params
116 function urlencode_params( tbl )
119 for k, v in pairs(tbl) do
120 if type(v) == "table" then
121 for i, v2 in ipairs(v) do
122 enc = enc .. ( #enc > 0 and "&" or "" ) ..
123 urlencode(k) .. "=" .. urlencode(v2)
126 enc = enc .. ( #enc > 0 and "&" or "" ) ..
127 urlencode(k) .. "=" .. urlencode(v)
134 --- (Internal function)
135 -- Initialize given parameter and coerce string into table when the parameter
137 -- @param tbl Table where parameter should be created
138 -- @param key Parameter name
139 -- @return Always nil
140 local function __initval( tbl, key )
141 if tbl[key] == nil then
143 elseif type(tbl[key]) == "string" then
144 tbl[key] = { tbl[key], "" }
146 table.insert( tbl[key], "" )
150 --- (Internal function)
151 -- Append given data to given parameter, either by extending the string value
152 -- or by appending it to the last string in the parameter's value table.
153 -- @param tbl Table containing the previously initialized parameter value
154 -- @param key Parameter name
155 -- @param chunk String containing the data to append
156 -- @return Always nil
158 local function __appendval( tbl, key, chunk )
159 if type(tbl[key]) == "table" then
160 tbl[key][#tbl[key]] = tbl[key][#tbl[key]] .. chunk
162 tbl[key] = tbl[key] .. chunk
166 --- (Internal function)
167 -- Finish the value of given parameter, either by transforming the string value
168 -- or - in the case of multi value parameters - the last element in the
169 -- associated values table.
170 -- @param tbl Table containing the previously initialized parameter value
171 -- @param key Parameter name
172 -- @param handler Function which transforms the parameter value
173 -- @return Always nil
176 local function __finishval( tbl, key, handler )
178 if type(tbl[key]) == "table" then
179 tbl[key][#tbl[key]] = handler( tbl[key][#tbl[key]] )
181 tbl[key] = handler( tbl[key] )
187 -- Table of our process states
188 local process_states = { }
190 -- Extract "magic", the first line of a http message.
191 -- Extracts the message type ("get", "post" or "response"), the requested uri
192 -- or the status code if the line descripes a http response.
193 process_states['magic'] = function( msg, chunk, err )
196 -- ignore empty lines before request
202 local method, uri, http_ver = chunk:match("^([A-Z]+) ([^ ]+) HTTP/([01]%.[019])$")
208 msg.request_method = method:lower()
209 msg.request_uri = uri
210 msg.http_version = tonumber( http_ver )
213 -- We're done, next state is header parsing
214 return true, function( chunk )
215 return process_states['headers']( msg, chunk )
221 local http_ver, code, message = chunk:match("^HTTP/([01]%.[019]) ([0-9]+) ([^\r\n]+)$")
226 msg.type = "response"
227 msg.status_code = code
228 msg.status_message = message
229 msg.http_version = tonumber( http_ver )
232 -- We're done, next state is header parsing
233 return true, function( chunk )
234 return process_states['headers']( msg, chunk )
241 return nil, "Invalid HTTP message magic"
245 -- Extract headers from given string.
246 process_states['headers'] = function( msg, chunk )
250 -- Look for a valid header format
251 local hdr, val = chunk:match( "^([A-Z][A-Za-z0-9%-_]+): +(.+)$" )
253 if type(hdr) == "string" and hdr:len() > 0 and
254 type(val) == "string" and val:len() > 0
256 msg.headers[hdr] = val
258 -- Valid header line, proceed
261 elseif #chunk == 0 then
262 -- Empty line, we won't accept data anymore
266 return nil, "Invalid HTTP header received"
269 return nil, "Unexpected EOF"
274 --- Creates a ltn12 source from the given socket. The source will return it's
275 -- data line by line with the trailing \r\n stripped of.
276 -- @param sock Readable network socket
277 -- @return Ltn12 source function
278 function header_source( sock )
279 return ltn12.source.simplify( function()
281 local chunk, err, part = sock:receive("*l")
285 if err ~= "timeout" then
287 and "Line exceeds maximum allowed length"
294 elseif chunk ~= nil then
297 chunk = chunk:gsub("\r$","")
304 --- Decode a mime encoded http message body with multipart/form-data
305 -- Content-Type. Stores all extracted data associated with its parameter name
306 -- in the params table withing the given message object. Multiple parameter
307 -- values are stored as tables, ordinary ones as strings.
308 -- If an optional file callback function is given then it is feeded with the
309 -- file contents chunk by chunk and only the extracted file name is stored
310 -- within the params table. The callback function will be called subsequently
311 -- with three arguments:
312 -- o Table containing decoded (name, file) and raw (headers) mime header data
313 -- o String value containing a chunk of the file data
314 -- o Boolean which indicates wheather the current chunk is the last one (eof)
315 -- @param src Ltn12 source function
316 -- @param msg HTTP message object
317 -- @param filecb File callback function (optional)
318 -- @return Value indicating successful operation (not nil means "ok")
319 -- @return String containing the error if unsuccessful
320 -- @see parse_message_header
321 function mimedecode_message_body( src, msg, filecb )
323 if msg and msg.env.CONTENT_TYPE then
324 msg.mime_boundary = msg.env.CONTENT_TYPE:match("^multipart/form%-data; boundary=(.+)$")
327 if not msg.mime_boundary then
328 return nil, "Invalid Content-Type found"
338 local function parse_headers( chunk, field )
342 chunk, stat = chunk:gsub(
343 "^([A-Z][A-Za-z0-9%-_]+): +([^\r\n]+)\r\n",
351 chunk, stat = chunk:gsub("^\r\n","")
355 if field.headers["Content-Disposition"] then
356 if field.headers["Content-Disposition"]:match("^form%-data; ") then
357 field.name = field.headers["Content-Disposition"]:match('name="(.-)"')
358 field.file = field.headers["Content-Disposition"]:match('filename="(.+)"$')
362 if not field.headers["Content-Type"] then
363 field.headers["Content-Type"] = "text/plain"
366 if field.name and field.file and filecb then
367 __initval( msg.params, field.name )
368 __appendval( msg.params, field.name, field.file )
371 elseif field.name then
372 __initval( msg.params, field.name )
374 store = function( hdr, buf, eof )
375 __appendval( msg.params, field.name, buf )
387 local function snk( chunk )
389 tlen = tlen + ( chunk and #chunk or 0 )
391 if msg.env.CONTENT_LENGTH and tlen > tonumber(msg.env.CONTENT_LENGTH) + 2 then
392 return nil, "Message body size exceeds Content-Length"
395 if chunk and not lchunk then
396 lchunk = "\r\n" .. chunk
399 local data = lchunk .. ( chunk or "" )
400 local spos, epos, found
403 spos, epos = data:find( "\r\n--" .. msg.mime_boundary .. "\r\n", 1, true )
406 spos, epos = data:find( "\r\n--" .. msg.mime_boundary .. "--\r\n", 1, true )
411 local predata = data:sub( 1, spos - 1 )
414 predata, eof = parse_headers( predata, field )
417 return nil, "Invalid MIME section header"
418 elseif not field.name then
419 return nil, "Invalid Content-Disposition header"
424 store( field, predata, true )
428 field = { headers = { } }
429 found = found or true
431 data, eof = parse_headers( data:sub( epos + 1, #data ), field )
438 lchunk = data:sub( #data - 78 + 1, #data )
439 data = data:sub( 1, #data - 78 )
442 store( field, data, false )
444 return nil, "Invalid MIME section header"
447 lchunk, data = data, nil
451 lchunk, eof = parse_headers( data, field )
454 store( field, lchunk, false )
455 lchunk, chunk = chunk, nil
463 return ltn12.pump.all( src, snk )
466 --- Decode an urlencoded http message body with application/x-www-urlencoded
467 -- Content-Type. Stores all extracted data associated with its parameter name
468 -- in the params table withing the given message object. Multiple parameter
469 -- values are stored as tables, ordinary ones as strings.
470 -- @param src Ltn12 source function
471 -- @param msg HTTP message object
472 -- @return Value indicating successful operation (not nil means "ok")
473 -- @return String containing the error if unsuccessful
474 -- @see parse_message_header
475 function urldecode_message_body( src, msg )
480 local function snk( chunk )
482 tlen = tlen + ( chunk and #chunk or 0 )
484 if msg.env.CONTENT_LENGTH and tlen > tonumber(msg.env.CONTENT_LENGTH) + 2 then
485 return nil, "Message body size exceeds Content-Length"
486 elseif tlen > HTTP_MAX_CONTENT then
487 return nil, "Message body size exceeds maximum allowed length"
490 if not lchunk and chunk then
494 local data = lchunk .. ( chunk or "&" )
498 spos, epos = data:find("^.-[;&]")
501 local pair = data:sub( spos, epos - 1 )
502 local key = pair:match("^(.-)=")
503 local val = pair:match("=([^%s]*)%s*$")
505 if key and #key > 0 then
506 __initval( msg.params, key )
507 __appendval( msg.params, key, val )
508 __finishval( msg.params, key, urldecode )
511 data = data:sub( epos + 1, #data )
521 return ltn12.pump.all( src, snk )
524 --- Try to extract an http message header including information like protocol
525 -- version, message headers and resulting CGI environment variables from the
526 -- given ltn12 source.
527 -- @param src Ltn12 source function
528 -- @return HTTP message object
529 -- @see parse_message_body
530 function parse_message_header( src )
535 local sink = ltn12.sink.simplify(
537 return process_states['magic']( msg, chunk )
541 -- Pump input data...
545 ok, err = ltn12.pump.step( src, sink )
548 if not ok and err then
554 -- Process get parameters
555 if ( msg.request_method == "get" or msg.request_method == "post" ) and
556 msg.request_uri:match("?")
558 msg.params = urldecode_params( msg.request_uri )
563 -- Populate common environment variables
565 CONTENT_LENGTH = msg.headers['Content-Length'];
566 CONTENT_TYPE = msg.headers['Content-Type'];
567 REQUEST_METHOD = msg.request_method:upper();
568 REQUEST_URI = msg.request_uri;
569 SCRIPT_NAME = msg.request_uri:gsub("?.+$","");
570 SCRIPT_FILENAME = ""; -- XXX implement me
571 SERVER_PROTOCOL = "HTTP/" .. string.format("%.1f", msg.http_version)
574 -- Populate HTTP_* environment variables
575 for i, hdr in ipairs( {
586 local var = 'HTTP_' .. hdr:upper():gsub("%-","_")
587 local val = msg.headers[hdr]
597 --- Try to extract and decode a http message body from the given ltn12 source.
598 -- This function will examine the Content-Type within the given message object
599 -- to select the appropriate content decoder.
600 -- Currently the application/x-www-urlencoded and application/form-data
601 -- mime types are supported. If the encountered content encoding can't be
602 -- handled then the whole message body will be stored unaltered as "content"
603 -- property within the given message object.
604 -- @param src Ltn12 source function
605 -- @param msg HTTP message object
606 -- @param filecb File data callback (optional, see mimedecode_message_body())
607 -- @return Value indicating successful operation (not nil means "ok")
608 -- @return String containing the error if unsuccessful
609 -- @see parse_message_header
610 function parse_message_body( src, msg, filecb )
611 -- Is it multipart/mime ?
612 if msg.env.REQUEST_METHOD == "POST" and msg.env.CONTENT_TYPE and
613 msg.env.CONTENT_TYPE:match("^multipart/form%-data")
616 return mimedecode_message_body( src, msg, filecb )
618 -- Is it application/x-www-form-urlencoded ?
619 elseif msg.env.REQUEST_METHOD == "POST" and msg.env.CONTENT_TYPE and
620 msg.env.CONTENT_TYPE == "application/x-www-form-urlencoded"
622 return urldecode_message_body( src, msg, filecb )
625 -- Unhandled encoding
626 -- If a file callback is given then feed it chunk by chunk, else
627 -- store whole buffer in message.content
632 -- If we have a file callback then feed it
633 if type(filecb) == "function" then
636 -- ... else append to .content
639 msg.content_length = 0
641 sink = function( chunk, err )
643 if ( msg.content_length + #chunk ) <= HTTP_MAX_CONTENT then
644 msg.content = msg.content .. chunk
645 msg.content_length = msg.content_length + #chunk
648 return nil, "POST data exceeds maximum allowed length"
657 local ok, err = ltn12.pump.step( src, sink )
659 if not ok and err then
670 --- Table containing human readable messages for several http status codes.
674 [301] = "Moved Permanently",
676 [304] = "Not Modified",
677 [400] = "Bad Request",
680 [405] = "Method Not Allowed",
681 [411] = "Length Required",
682 [412] = "Precondition Failed",
683 [500] = "Internal Server Error",
684 [503] = "Server Unavailable",