Multipart support.

Adds helper code to encode multipart/form-data requests.
This, for instances, allows to post images to Twitter.

The multipart encoder was adapted from @catwell's [lua-multipart-post](https://github.com/catwell/lua-multipart-post).

fixes #6

Author: ignacio

LICENSE

@@ -18,4 +18,30 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
-THE SOFTWARE.
+THE SOFTWARE.
+
+
+-----------------
+Contains code from lua-multipart-post
+
+https://github.com/catwell/lua-multipart-post
+
+Copyright (C) 2012-2013 by Moodstocks SAS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

README.md

@@ -8,7 +8,7 @@ This is an adaptation of Jeffrey Friedl's [Twitter OAuth Authentication Routines
 with Lightroom's code replaced by other libraries (i.e. [LuaSec][2], [LuaSocket][3], etc) and with HMAC-SHA1 calculations 
 done with [LuaCrypto][4] instead of [plain Lua][6].
 
-Most of the code was taken from [Jeffrey Friedl's blog][1].
+Most of the code was taken from [Jeffrey Friedl's blog][1]. Multipart encoding was adapted from @catwell's [lua-multipart-post][9].
 
 LuaOAuth supports two modes of operation. A "synchronous" mode were you block while you wait for the results or an 
 "asynchronous" mode where you must supply "callbacks" in order to receive the results. LuaOAuth will behave asynchronously 
@@ -76,9 +76,9 @@ Copy the following in a script and run it from the console. Follow the instructi
 ``` lua
 local OAuth = require "OAuth"
 local client = OAuth.new("consumer_key", "consumer_secret", {
-	RequestToken = "http://api.twitter.com/oauth/request_token", 
-	AuthorizeUser = {"http://api.twitter.com/oauth/authorize", method = "GET"},
-	AccessToken = "http://api.twitter.com/oauth/access_token"
+	RequestToken = "https://api.twitter.com/oauth/request_token", 
+	AuthorizeUser = {"https://api.twitter.com/oauth/authorize", method = "GET"},
+	AccessToken = "https://api.twitter.com/oauth/access_token"
 }) 
 local callback_url = "oob"
 local values = client:RequestToken({ oauth_callback = callback_url })
@@ -97,9 +97,9 @@ oauth_verifier = tostring(oauth_verifier)		-- must be a string
 
 -- now we'll use the tokens we got in the RequestToken call, plus our PIN
 local client = OAuth.new("consumer_key", "consumer_secret", {
-	RequestToken = "http://api.twitter.com/oauth/request_token", 
-	AuthorizeUser = {"http://api.twitter.com/oauth/authorize", method = "GET"},
-	AccessToken = "http://api.twitter.com/oauth/access_token"
+	RequestToken = "https://api.twitter.com/oauth/request_token", 
+	AuthorizeUser = {"https://api.twitter.com/oauth/authorize", method = "GET"},
+	AccessToken = "https://api.twitter.com/oauth/access_token"
 }, {
 	OAuthToken = oauth_token,
 	OAuthVerifier = oauth_verifier
@@ -129,41 +129,76 @@ local oauth_token = "<the value from last step>"
 local oauth_token_secret = "<the value from last step>"
 
 local client = OAuth.new("consumer_key", "consumer_secret", {
-	RequestToken = "http://api.twitter.com/oauth/request_token", 
-	AuthorizeUser = {"http://api.twitter.com/oauth/authorize", method = "GET"},
-	AccessToken = "http://api.twitter.com/oauth/access_token"
+	RequestToken = "https://api.twitter.com/oauth/request_token", 
+	AuthorizeUser = {"https://api.twitter.com/oauth/authorize", method = "GET"},
+	AccessToken = "https://api.twitter.com/oauth/access_token"
 }, {
 	OAuthToken = oauth_token,
 	OAuthTokenSecret = oauth_token_secret
 })
 
 -- the mandatory "Hello World" example...
 local response_code, response_headers, response_status_line, response_body = 
-	client:PerformRequest("POST", "http://api.twitter.com/1/statuses/update.json", {status = "Hello World From Lua!" .. os.time()})
+	client:PerformRequest("POST", "https://api.twitter.com/1.1/statuses/update.json", {status = "Hello World From Lua!" .. os.time()})
 print("response_code", response_code)
 print("response_status_line", response_status_line)
 for k,v in pairs(response_headers) do print(k,v) end
 print("response_body", response_body)
 ```
 
-Now, let's try to request my Twitts.
+Now, let's try to request my Tweets.
 
 ``` lua
 local oauth_token = "<the value from last step>"
 local oauth_token_secret = "<the value from last step>"
 
 local client = OAuth.new("consumer_key", "consumer_secret", {
-	RequestToken = "http://api.twitter.com/oauth/request_token", 
-	AuthorizeUser = {"http://api.twitter.com/oauth/authorize", method = "GET"},
-	AccessToken = "http://api.twitter.com/oauth/access_token"
+	RequestToken = "https://api.twitter.com/oauth/request_token", 
+	AuthorizeUser = {"https://api.twitter.com/oauth/authorize", method = "GET"},
+	AccessToken = "https://api.twitter.com/oauth/access_token"
 }, {
 	OAuthToken = oauth_token,
 	OAuthTokenSecret = oauth_token_secret
 })
 
 -- the mandatory "Hello World" example...
 local response_code, response_headers, response_status_line, response_body = 
-client:PerformRequest("GET", "http://api.twitter.com/1/statuses/user_timeline.json", {screen_name = "iburgueno"})
+client:PerformRequest("GET", "https://api.twitter.com/1.1/statuses/user_timeline.json", {screen_name = "iburgueno"})
+print("response_code", response_code)
+print("response_status_line", response_status_line)
+for k,v in pairs(response_headers) do print(k,v) end
+print("response_body", response_body)
+```
+
+And now, let's post an image:
+
+``` lua
+local oauth_token = "<the value from last step>"
+local oauth_token_secret = "<the value from last step>"
+
+local client = OAuth.new("consumer_key", "consumer_secret", {
+	RequestToken = "https://api.twitter.com/oauth/request_token", 
+	AuthorizeUser = {"https://api.twitter.com/oauth/authorize", method = "GET"},
+	AccessToken = "https://api.twitter.com/oauth/access_token"
+}, {
+	OAuthToken = oauth_token,
+	OAuthTokenSecret = oauth_token_secret
+})
+
+local helpers = require "OAuth.helpers"
+
+local req = helpers.multipart.Request{
+	status = "Hello World From Lua!",
+	["media[]"] = {
+		filename = "@picture.jpg",
+		data = picture_data -- some picture file you have read
+	}
+}
+local response_code, response_headers, response_status_line, response_body = 
+	client:PerformRequest("POST", 
+							"https://api.twitter.com/1.1/statuses/update_with_media.json", 
+							req.body, req.headers
+						 )
 print("response_code", response_code)
 print("response_status_line", response_status_line)
 for k,v in pairs(response_headers) do print(k,v) end
@@ -179,3 +214,4 @@ print("response_body", response_body)
 [6]: http://regex.info/blog/lua/sha1
 [7]: http://dev.twitter.com/apps
 [8]: https://github.com/ignacio/luanode
+[9]: https://github.com/catwell/lua-multipart-post

src/OAuth.lua

@@ -465,6 +465,8 @@ end
 -- @param url is the url to request
 -- @param arguments is an optional table whose keys and values will be encoded as "application/x-www-form-urlencoded" 
 --   (when doing a POST) or encoded and sent in the query string (when doing a GET).
+--   It can also be a string with the body to be sent in the request (usually a POST). In that case, you need to supply
+--   a valid Content-Type header.
 -- @param headers is an optional table with http headers to be sent in the request
 -- @param callback is only required if running under LuaNode. It is a function to be called with an (optional) error object and the result of the request.
 -- @return nothing if running under Luanode (the callback will be called instead). Else, the http status code 
@@ -506,6 +508,8 @@ end
 -- @param url is the url to request
 -- @param arguments is an optional table whose keys and values will be encoded as "application/x-www-form-urlencoded" 
 --  (when doing a POST) or encoded and sent in the query string (when doing a GET).
+--   It can also be a string with the body to be sent in the request (usually a POST). In that case, you need to supply
+--   a valid Content-Type header.
 -- @param headers is an optional table with http headers to be sent in the request
 -- @return a table with the headers, a table with the (cleaned up) arguments and the request body.
 function BuildRequest(self, method, url, arguments, headers)

src/OAuth/helpers.lua

@@ -1,4 +1,7 @@
-local pairs, table, tostring = pairs, table, tostring
+local pairs, table, tostring, select = pairs, table, tostring, select
+local type, assert = type, assert
+local string = require "string"
+local math = require "math"
 local Url, Qs
 local isLuaNode
 
@@ -21,3 +24,96 @@ url_encode_arguments = (isLuaNode and Qs.url_encode_arguments) or function(argum
 	end
 	return table.concat(body, "&")
 end
+
+
+---
+-- Multipart form-data helper.
+--
+-- Taken from https://github.com/catwell/lua-multipart-post
+--
+do	-- Create a scope to avoid these local helpers to escape
+
+local function fmt(p, ...)
+	if select('#',...) == 0 then
+		return p
+	else
+		return string.format(p, ...)
+	end
+end
+
+local function tprintf(t, p, ...)
+	t[#t + 1] = fmt(p, ...)
+end
+
+local function append_data(r, k, data, extra)
+	tprintf(r, "content-disposition: form-data; name=\"%s\"", k)
+	if extra.filename then
+		tprintf(r, "; filename=\"%s\"", extra.filename)
+	end
+	if extra.content_type then
+		tprintf(r, "\r\ncontent-type: %s", extra.content_type)
+	end
+	if extra.content_transfer_encoding then
+		tprintf(r, "\r\ncontent-transfer-encoding: %s", extra.content_transfer_encoding)
+	end
+	tprintf(r, "\r\n\r\n")
+	tprintf(r, data)
+	tprintf(r, "\r\n")
+end
+
+local function gen_boundary()
+	local t = {"BOUNDARY-"}
+	for i = 2, 17 do
+		t[i] = string.char(math.random(65, 90))
+	end
+	t[18] = "-BOUNDARY"
+	return table.concat(t)
+end
+
+local function encode(t, boundary)
+	local r = {}
+	local _t
+	
+	-- generate a boundary if none was supplied
+	boundary = boundary or gen_boundary()
+	
+	for k,v in pairs(t) do
+		tprintf(r,"--%s\r\n",boundary)
+		_t = type(v)
+		if _t == "string" then
+			append_data(r, k, v, {})
+		elseif _t == "table" then
+			assert(v.data, "invalid input")
+			local extra = {
+				filename = v.filename or v.name,
+				content_type = v.content_type or v.mimetype or "application/octet-stream",
+				content_transfer_encoding = v.content_transfer_encoding or "binary",
+			}
+			append_data(r, k, v.data, extra)
+		else
+			error(string.format("unexpected type %s", _t))
+		end
+	end
+	tprintf(r, "--%s--\r\n", boundary)
+	return table.concat(r)
+end
+
+
+multipart = {
+	---
+	-- t is a table with the data to be encoded as multipart/form-data
+	-- TODO: improve docs
+	Request = function(t)
+		local boundary = gen_boundary()
+		local body = encode(t, boundary)
+		return {
+			body = body,
+			headers = {
+				["Content-Length"] = #body,
+				["Content-Type"] = ("multipart/form-data; boundary=%s"):format(boundary),
+			},
+		}
+	end
+}
+
+end	-- end of multipart scope

unittest/run.lua

@@ -2,9 +2,7 @@ require "lunit"
 
 package.path = "../src/?.lua;../src/?/init.lua;".. package.path
 
-local OAuth = require "OAuth"
 local console = require "lunit-console"
-
 require "echo_lab_madgex_com"
 --require "twitter"
 require "termie"

unittest/test_twitter_multipart.jpg

@@ -1,20 +1,72 @@
 module(..., lunit.testcase, package.seeall)
 
-local consumer_key = "my consumer key (you need to change this)"
-local consumer_secret = "your consumer secret (you need to change this)"
+local OAuth = require "OAuth"
 
-function test()
+local consumer_key = "<your consumer key>"
+local consumer_secret = "<your consumer secret>"
+
+---
+-- Teste requesting a token from Twitter and build the authorization url.
+--
+function testAuthorize()
+	local OAuth = require "OAuth"
+	
 	local client = OAuth.new(consumer_key, consumer_secret, {
-		RequestToken = "http://api.twitter.com/oauth/request_token", 
+		RequestToken = "https://api.twitter.com/oauth/request_token",
 		AuthorizeUser = {"https://api.twitter.com/oauth/authorize", method = "GET"},
-		AccessToken = "http://api.twitter.com/oauth/access_token"
+		AccessToken = "https://api.twitter.com/oauth/access_token"
 	})
+
 	print("requesting token")
 	local values = client:RequestToken()
-	local auth_url = client:BuildAuthorizationUrl()
-	print("Test authorization at the following URL")
-	print(auth_url)
 	assert_table(values)
 	assert_string(values.oauth_token)
 	assert_string(values.oauth_token_secret)
+	--for k,v in pairs(values) do print(k,v) end
+	
+	local auth_url = client:BuildAuthorizationUrl()
+	assert_string(auth_url)
+	
+	print("Test authorization at the following URL: " .. auth_url)
+end
+
+
+---
+-- Uses the update_with_media Twitter endpoint to test a POST request with multipart/form-data encoding.
+--
+function testMultipartPost()
+
+	-- helper
+	local function read_image()
+		local f = assert(io.open([[test_twitter_multipart.jpg]], "rb"))
+		local image_data = f:read("*a")
+		f:close()
+		return image_data
+	end
+
+	local oauth_token = "<a valid oauth token>"
+	local oauth_token_secret = "<and its corresponding token secret>"
+
+	local client = OAuth.new(consumer_key, consumer_secret, {
+		RequestToken = "https://api.twitter.com/oauth/request_token",
+		AuthorizeUser = {"https://api.twitter.com/oauth/authorize", method = "GET"},
+		AccessToken = "https://api.twitter.com/oauth/access_token"
+	}, {
+		OAuthToken = oauth_token,
+		OAuthTokenSecret = oauth_token_secret
+	})
+
+	local helpers = require "OAuth.helpers"
+
+	local req = helpers.multipart.Request{
+		status = "Hello World From Lua!" .. os.time(),
+		["media[]"] = {
+			filename = "@test_multipart.jpg",
+			data = read_image()
+		}
+	}
+
+	local response_code, response_headers, response_status_line, response_body =
+		client:PerformRequest("POST", "https://api.twitter.com/1.1/statuses/update_with_media.json", req.body, req.headers)
+	assert_equal(200, response_code)
 end