326 lines
11 KiB
HTML
326 lines
11 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
|
|
"http://www.w3.org/TR/html4/strict.dtd">
|
|
<html>
|
|
|
|
<head>
|
|
<meta name="description" content="LuaSocket: HTTP support">
|
|
<meta name="keywords" content="Lua, HTTP, Library, WWW, Browser, Network, Support">
|
|
<title>LuaSocket: HTTP support</title>
|
|
<link rel="stylesheet" href="reference.css" type="text/css">
|
|
</head>
|
|
|
|
<body>
|
|
|
|
<!-- header ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<div class=header>
|
|
<hr>
|
|
<center>
|
|
<table summary="LuaSocket logo">
|
|
<tr><td align=center><a href="http://www.lua.org">
|
|
<img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png">
|
|
</a></td></tr>
|
|
<tr><td align=center valign=top>Network support for the Lua language
|
|
</td></tr>
|
|
</table>
|
|
<p class=bar>
|
|
<a href="home.html">home</a> ·
|
|
<a href="home.html#download">download</a> ·
|
|
<a href="introduction.html">introduction</a> ·
|
|
<a href="introduction.html">introduction</a> ·
|
|
<a href="reference.html">reference</a>
|
|
</p>
|
|
</center>
|
|
<hr>
|
|
</div>
|
|
|
|
<!-- http +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<h2 id=http>HTTP</h2>
|
|
|
|
<p>
|
|
HTTP (Hyper Text Transfer Protocol) is the protocol used to exchange
|
|
information between web-browsers and servers. The <tt>http</tt>
|
|
namespace offers full support for the client side of the HTTP
|
|
protocol (i.e.,
|
|
the facilities that would be used by a web-browser implementation). The
|
|
implementation conforms to the HTTP/1.1 standard,
|
|
<a href="http://www.cs.princeton.edu/~diego/rfc/rfc2616.txt">RFC
|
|
2616</a>.
|
|
</p>
|
|
|
|
<p>
|
|
The module exports functions that provide HTTP functionality in different
|
|
levels of abstraction. From the simple
|
|
string oriented requests, through generic
|
|
<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a> based, down to even lower-level if you bother to look through the source code.
|
|
</p>
|
|
|
|
<p>
|
|
To obtain the <tt>http</tt> namespace, run:
|
|
</p>
|
|
|
|
<pre class=example>
|
|
-- loads the HTTP module and any libraries it requires
|
|
local http = require("socket.http")
|
|
</pre>
|
|
|
|
<p>
|
|
URLs must conform to
|
|
<a href="http://www.cs.princeton.edu/~diego/rfc/rfc1738.txt">RFC
|
|
1738</a>,
|
|
that is, an URL is a string in the form:
|
|
</p>
|
|
|
|
<blockquote>
|
|
<pre>
|
|
[http://][<user>[:<password>]@]<host>[:<port>][/<path>]
|
|
</pre>
|
|
</blockquote>
|
|
|
|
<p>
|
|
MIME headers are represented as a Lua table in the form:
|
|
</p>
|
|
|
|
<blockquote>
|
|
<table summary="MIME headers in Lua table">
|
|
<tr><td><tt>
|
|
headers = {<br>
|
|
field-1-name = <i>field-1-value</i>,<br>
|
|
field-2-name = <i>field-2-value</i>,<br>
|
|
field-3-name = <i>field-3-value</i>,<br>
|
|
...<br>
|
|
field-n-name = <i>field-n-value</i><br>
|
|
}
|
|
</tt></td></tr>
|
|
</table>
|
|
</blockquote>
|
|
|
|
<p>
|
|
Field names are case insensitive (as specified by the standard) and all
|
|
functions work with lowercase field names.
|
|
Field values are left unmodified.
|
|
</p>
|
|
|
|
<p class=note>
|
|
Note: MIME headers are independent of order. Therefore, there is no problem
|
|
in representing them in a Lua table.
|
|
</p>
|
|
|
|
<p>
|
|
The following constants can be set to control the default behavior of
|
|
the HTTP module:
|
|
</p>
|
|
|
|
<ul>
|
|
<li> <tt>PORT</tt>: default port used for connections;
|
|
<li> <tt>PROXY</tt>: default proxy used for connections;
|
|
<li> <tt>TIMEOUT</tt>: sets the timeout for all I/O operations;
|
|
<li> <tt>USERAGENT</tt>: default user agent reported to server.
|
|
</ul>
|
|
|
|
<!-- http.request ++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<p class=name id=request>
|
|
http.<b>request(</b>url [, body]<b>)</b><br>
|
|
http.<b>request{</b><br>
|
|
url = <i>string</i>,<br>
|
|
[sink = <i>LTN12 sink</i>,]<br>
|
|
[method = <i>string</i>,]<br>
|
|
[headers = <i>header-table</i>,]<br>
|
|
[source = <i>LTN12 source</i>],<br>
|
|
[step = <i>LTN12 pump step</i>,]<br>
|
|
[proxy = <i>string</i>,]<br>
|
|
[redirect = <i>boolean</i>,]<br>
|
|
[create = <i>function</i>]<br>
|
|
<b>}</b>
|
|
</p>
|
|
|
|
<p class=description>
|
|
The request function has two forms. The simple form downloads
|
|
a URL using the <tt>GET</tt> or <tt>POST</tt> method and is based
|
|
on strings. The generic form performs any HTTP method and is
|
|
<a href=http://lua-users.org/wiki/FiltersSourcesAndSinks>LTN12</a> based.
|
|
</p>
|
|
|
|
<p class=parameters>
|
|
If the first argument of the <tt>request</tt> function is a string, it
|
|
should be an <tt>url</tt>. In that case, if a <tt>body</tt>
|
|
is provided as a string, the function will perform a <tt>POST</tt> method
|
|
in the <tt>url</tt>. Otherwise, it performs a <tt>GET</tt> in the
|
|
<tt>url</tt>
|
|
</p>
|
|
|
|
<p class=parameters>
|
|
If the first argument is instead a table, the most important fields are
|
|
the <tt>url</tt> and the <em>simple</em>
|
|
<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
|
|
<tt>sink</tt> that will receive the downloaded content.
|
|
Any part of the <tt>url</tt> can be overridden by including
|
|
the appropriate field in the request table.
|
|
If authentication information is provided, the function
|
|
uses the Basic Authentication Scheme (see <a href="#authentication">note</a>)
|
|
to retrieve the document. If <tt>sink</tt> is <tt><b>nil</b></tt>, the
|
|
function discards the downloaded data. The optional parameters are the
|
|
following:
|
|
</p>
|
|
<ul>
|
|
<li><tt>method</tt>: The HTTP request method. Defaults to "GET";
|
|
<li><tt>headers</tt>: Any additional HTTP headers to send with the request;
|
|
<li><tt>source</tt>: <em>simple</em>
|
|
<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
|
|
source to provide the request body. If there
|
|
is a body, you need to provide an appropriate "<tt>content-length</tt>"
|
|
request header field, or the function will attempt to send the body as
|
|
"<tt>chunked</tt>" (something few servers support). Defaults to the empty source;
|
|
<li><tt>step</tt>:
|
|
<a href="http://lua-users.org/wiki/FiltersSourcesAndSinks">LTN12</a>
|
|
pump step function used to move data.
|
|
Defaults to the LTN12 <tt>pump.step</tt> function.
|
|
<li><tt>proxy</tt>: The URL of a proxy server to use. Defaults to no proxy;
|
|
<li><tt>redirect</tt>: Set to <tt><b>false</b></tt> to prevent the
|
|
function from automatically following 301 or 302 server redirect messages;
|
|
<li><tt>create</tt>: An optional function to be used instead of
|
|
<a href=tcp.html#socket.tcp><tt>socket.tcp</tt></a> when the communications socket is created.
|
|
</ul>
|
|
|
|
<p class=return>
|
|
In case of failure, the function returns <tt><b>nil</b></tt> followed by an
|
|
error message. If successful, the simple form returns the response
|
|
body as a string, followed by the response status code, the response
|
|
headers and the response status line. The complex function returns the same
|
|
information, except the first return value is just the number 1 (the body
|
|
goes to the <tt>sink</tt>).
|
|
</p>
|
|
|
|
<p class=return>
|
|
Even when the server fails to provide the contents of the requested URL (URL not found, for example),
|
|
it usually returns a message body (a web page informing the
|
|
URL was not found or some other useless page). To make sure the
|
|
operation was successful, check the returned status <tt>code</tt>. For
|
|
a list of the possible values and their meanings, refer to <a
|
|
href="http://www.cs.princeton.edu/~diego/rfc/rfc2616.txt">RFC
|
|
2616</a>.
|
|
</p>
|
|
|
|
<p class=description>
|
|
Here are a few examples with the simple interface:
|
|
</p>
|
|
|
|
<pre class=example>
|
|
-- load the http module
|
|
local io = require("io")
|
|
local http = require("socket.http")
|
|
local ltn12 = require("ltn12")
|
|
|
|
-- connect to server "www.cs.princeton.edu" and retrieves this manual
|
|
-- file from "~diego/professional/luasocket/http.html" and print it to stdout
|
|
http.request{
|
|
url = "http://www.cs.princeton.edu/~diego/professional/luasocket/http.html",
|
|
sink = ltn12.sink.file(io.stdout)
|
|
}
|
|
|
|
-- connect to server "www.example.com" and tries to retrieve
|
|
-- "/private/index.html". Fails because authentication is needed.
|
|
b, c, h = http.request("http://www.example.com/private/index.html")
|
|
-- b returns some useless page telling about the denied access,
|
|
-- h returns authentication information
|
|
-- and c returns with value 401 (Authentication Required)
|
|
|
|
-- tries to connect to server "wrong.host" to retrieve "/"
|
|
-- and fails because the host does not exist.
|
|
r, e = http.request("http://wrong.host/")
|
|
-- r is nil, and e returns with value "host not found"
|
|
</pre>
|
|
|
|
<p class=description>
|
|
And here is an example using the generic interface:
|
|
</p>
|
|
|
|
<pre class=example>
|
|
-- load the http module
|
|
http = require("socket.http")
|
|
|
|
-- Requests information about a document, without downloading it.
|
|
-- Useful, for example, if you want to display a download gauge and need
|
|
-- to know the size of the document in advance
|
|
r, c, h = http.request {
|
|
method = "HEAD",
|
|
url = "http://www.tecgraf.puc-rio.br/~diego"
|
|
}
|
|
-- r is 1, c is 200, and h would return the following headers:
|
|
-- h = {
|
|
-- date = "Tue, 18 Sep 2001 20:42:21 GMT",
|
|
-- server = "Apache/1.3.12 (Unix) (Red Hat/Linux)",
|
|
-- ["last-modified"] = "Wed, 05 Sep 2001 06:11:20 GMT",
|
|
-- ["content-length"] = 15652,
|
|
-- ["connection"] = "close",
|
|
-- ["content-Type"] = "text/html"
|
|
-- }
|
|
</pre>
|
|
|
|
<p class=note id=authentication>
|
|
Note: Some URLs are protected by their
|
|
servers from anonymous download. For those URLs, the server must receive
|
|
some sort of authentication along with the request or it will deny
|
|
download and return status "401 Authentication Required".
|
|
</p>
|
|
|
|
<p class=note>
|
|
The HTTP/1.1 standard defines two authentication methods: the Basic
|
|
Authentication Scheme and the Digest Authentication Scheme, both
|
|
explained in detail in
|
|
<a href="http://www.cs.princeton.edu/~diego/rfc/rfc2068.txt">RFC 2068</a>.
|
|
</p>
|
|
|
|
<p class=note>The Basic Authentication Scheme sends
|
|
<tt><user></tt> and
|
|
<tt><password></tt> unencrypted to the server and is therefore
|
|
considered unsafe. Unfortunately, by the time of this implementation,
|
|
the wide majority of servers and browsers support the Basic Scheme only.
|
|
Therefore, this is the method used by the toolkit whenever
|
|
authentication is required.
|
|
</p>
|
|
|
|
<pre class=example>
|
|
-- load required modules
|
|
http = require("socket.http")
|
|
mime = require("mime")
|
|
|
|
-- Connect to server "www.example.com" and tries to retrieve
|
|
-- "/private/index.html", using the provided name and password to
|
|
-- authenticate the request
|
|
b, c, h = http.request("http://fulano:silva@www.example.com/private/index.html")
|
|
|
|
-- Alternatively, one could fill the appropriate header and authenticate
|
|
-- the request directly.
|
|
r, c = http.request {
|
|
url = "http://www.example.com/private/index.html",
|
|
headers = { authentication = "Basic " .. (mime.b64("fulano:silva")) }
|
|
}
|
|
</pre>
|
|
|
|
<!-- footer +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
|
|
|
|
<div class=footer>
|
|
<hr>
|
|
<center>
|
|
<p class=bar>
|
|
<a href="home.html">home</a> ·
|
|
<a href="home.html#download">download</a> ·
|
|
<a href="installation.html">installation</a> ·
|
|
<a href="introduction.html">introduction</a> ·
|
|
<a href="reference.html">reference</a>
|
|
</p>
|
|
<p>
|
|
<small>
|
|
Last modified by Diego Nehab on <br>
|
|
Mon Nov 21 01:57:03 EST 2005
|
|
</small>
|
|
</p>
|
|
</center>
|
|
</div>
|
|
|
|
</body>
|
|
</html>
|