HTTP (Hyper Text Transfer Protocol)はWebブラウザとサーバ間で情報を転送するのに使用されるプロトコルです。
httpネームスペースは(Webブラウザの実装するような)HTTPプロトコルのクライアント側の完全なサポートを提供します。
実装はHTTP/1.1標準,RFC2616に従います。

このモジュールは抽象的に異なるレベルのHTTPの機能を持った関数を提供します。
心配であれば単純な文字列を使用する一般的なLTN12に基づいたリクエスト指向のものから、低レベルなものにソースコードを読み進めてください。

httpネームスペースを取得するには次のように行います。

-- HTTPモジュールをロード
local http = require("socket.http")

URLはRFC1738にしたがった形式になり、次のような形式の文字列です。

[http://][<user>[:<password>]@]<host>[:<port>][/<path>] 

MIMEヘッダはLuaテーブルであらわし、次のような形式になります。

headers = {
  field-1-name = field-1-value,
  field-2-name = field-2-value,
  field-3-name = field-3-value,
  ...
  field-n-name = field-n-value
}

field(要素)名は大文字小文字を気にしていません(規格で決められています)。
すべての関数は小文字の要素名で動作します。要素名は変更されず、そのままにされます。

注意: MIMEヘッダは順番が関係ありません。したがってLuaテーブルで表しても問題ないのです。

HTTPモジュールのデフォルトの動作を指定するために、次のものを設定することができます。

• PORT : 接続用のデフォルトのポート番号です。
• PROXY : 接続に使用されるデフォルトのプロキシです。
• TIMEOUT : すべてのI/O操作のタイムアウトを設定します。
• USERAGENT : サーバに通知するデフォルトのユーザエージェントです。

http.request(url [, body])
http.request{
  url = string,
  [sink = LTN12 sink,]
  [method = string,]
  [headers = header-table,]
  [source = LTN12 source],
  [step = LTN12 pump step,]
  [proxy = string,]
  [redirect = boolean,]
  [create = function]
}

request関数には2つの形式があります。
簡単な形式では文字列を使用してGETもしくはPOSTメソッドを使用してURLからダウンロードします。
一般的な形式ではLTN12を使用してあらゆるHTTPメソッドを実行することができます。

request関数の最初の引数が文字列の場合、その文字列はURLでなければなりません。
文字列でbodyを指定した場合、この関数はurlにPOSTメソッドでアクセスします。
bodyを省略した場合はurlにGETでアクセスします。

最初の引数がテーブルの場合、重要な要素はurlとダウンロードするデータを受信するLTN12のsinkです。
リクエストテーブルに対応する要素が含まれる場合、urlの一部が上書きされます。
認証用の情報が含まれる場合、この関数はドキュメントを検索するのにBASIC認証のスキーム(注)を使用します。
sinkがnilの場合、この関数はダウンロードしたデータを破棄します。
オプションパラメータとして、次のようなものがあります。

• method : HTTPリクエストのメソッド。デフォルトは"GET"。
• headers : リクエストで付加して送信するHTTPヘッダ。
• source : リクエストのbody用のLTN12ソース。bodyが存在する場合は、適切な"content-length"リクエストヘッダを付加するか、"chanked"(一部のサーバのみ対応しています)としてbodyを送信する必要があります。デフォルトは空のソースです。
• step : データを転送するLTN12のpump step関数です。デフォルトはLTN12のpump.step関数です。
• proxy : 使用するプロキシサーバのURLです。デフォルトはプロキシなしです。
• redirect : 301や302サーバリダイレクトメッセージで自動的にリダイレクトさせない場合はfalseを指定します。
• create : 通信用ソケットが作成される時、socket.tcpの代わりに使用するオプション関数です。

エラーの場合、nilに続けてエラーメッセージを返します。
成功の場合、簡単な形式ではレスポンスのbodyを文字列で返し、続いてレスポンスのステータスコード、レスポンスヘッダとレスポンスのステータスラインを返します。
一般的な形式でも、最初に数字の1を返す以外は同じ値を返します(bodyはsinkに渡されます)。

リクエストしたURLの内容をサーバが返さない場合(例えばURL not found)も、通常通りメッセージbodyを返します(URLが見つからなかった、その他役に立つページがなかったなどを通知するWebページ)。
操作が成功したかどうかは返されるステータスcodeを確認してください。その値と意味の一覧はRFC2616を参照してください。

簡単な形式でのいくつか例を示します。

-- httpモジュールをロード
local io = require("io")
local http = require("socket.http")
local ltn12 = require("ltn12")

-- サーバ "www.cs.princeton.edu" に接続し "~diego/professional/luasocket/http.html"
-- からマニュアルファイルを検索して標準出力に出力する。
http.request{ 
    url = "http://www.cs.princeton.edu/~diego/professional/luasocket/http.html", 
    sink = ltn12.sink.file(io.stdout)
}

-- サーバ "www.example.com" に接続し、"/private/index.html"を検索。
-- 認証が必要となるので失敗する。
b, c, h = http.request("http://www.example.com/private/index.html")
-- b アクセス拒否を通知する役に立たないページの内容
-- h 認証情報
-- c 401の値(認証が必要)

-- サーバ "wrong.host" に接続し、"/"を取得しようとするが
-- ホストが存在しないので失敗。
r, e = http.request("http://wrong.host/")
-- rはnil。eの値は "host not found"

続いて一般的な形式を使用した例です。

-- httpモジュールを読み込む
http = require("socket.http")

-- ドキュメントの情報を指定。まだダウンロードされない。
-- ダウンロードゲージを表示したり、ドキュメントの進歩具合を知りたいときに、この例は役に立ちます
r, c, h = http.request {
  method = "HEAD",
  url = "http://www.tecgraf.puc-rio.br/~diego"
}
-- r は 1。c は 200。 h は次のようなヘッダを返します。
-- 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"
-- }

注意 : POSTリクエストを送信するとき、簡単な形式では"Content-type: application/x-www-form-urlencoded"
ヘッダをリクストに付加します。これはHTTPフォームで使用されるタイプです。
別のタイプが必要な場合は一般的な形式を使用してください。

注意 : 誰でもダウンロードできないように保護されているURLがあります。
それらのURLはリクエストで認証情報を受け取るか、ステータス"401 Authentication Required"を返してダウンロードを拒否します。

HTTP/1.1では2つの認証方法が定義されています。Basic認証とDigest認証で、両方ともRFC2068で詳細が説明されています。

Basic認証では<user>と<password>が暗号化されずに送信されるので危険だと考えられています。
残念ながら、現在の実装では大多数のサーバとブラウザはBasic認証のみをサポートしています。
したがって認証が必要な場合にはいつもこの手法が使用されます。

-- 必要なモジュールをロード
http = require("socket.http")
mime = require("mime")

-- サーバ"www.example.com"に接続し、認証用のユーザ名とパスワードを
-- 使用して"/private/index.html"を取得する
b, c, h = http.request("http://fulano:silva@www.example.com/private/index.html")

-- 別の方法として、リクエストに直接、適切な認証ヘッダを付加する方法もあります。
r, c = http.request {
  url = "http://www.example.com/private/index.html",
  headers = { authentication = "Basic " .. (mime.b64("fulano:silva")) }
}