LuaSocket を使い Lua から Amazon S3 にファイルをエクスポート
Lua から Amazon S3 にファイルをエクスポートするには、libcurl でアップロードに署名し、HTTPS を検証してから、オブジェクトをダウンロードしてバイトを照合します。この例では LuaJIT の FFI 経由で libcurl を呼び出し、リトライの待機には LuaSocket を使います。バイナリファイルと空のファイル、AWS の一時認証情報、空白、Unicode、リテラルのパーセント記号を含むキーに対応します。
インストールとセットアップ
動作確認済みの環境は Linux と LuaJIT 2.1.1788460057、LuaRocks 3.13.0、LuaSocket 3.1.0-1、libcurl 8.22.0、AWS CLI v2 2.37.10 です。これらはテストしたバージョンであり、必須の最小バージョンではありません。最新の LuaJIT 2.1 ビルドと、HTTPS と AWS SigV4 が有効な、パッチ適用済みの libcurl リリースを使用してください。古い libcurl オプションがあるだけでは、S3 署名機能との互換性は確認できません。
信頼できるシステムパッケージマネージャーを使い、LuaJIT とその開発用ヘッダー、LuaRocks、C コンパイラー、Make、pkg-config、libcurl、システムの CA バンドル、AWS CLI v2、cmp、mktemp をインストールしてください。LuaJIT の開発用パッケージには、pkg-config エントリー luajit が必要です。既存の Lua プロジェクトの外にある空のディレクトリで作業し、LuaSocket rock を専用のツリーにインストールしてください。
(
set -eu
for tool in luajit luarocks cc make pkg-config aws cmp mktemp; do
command -v "$tool" >/dev/null || { printf 'Missing prerequisite: %s\n' "$tool" >&2; exit 1; }
done
case "$(aws --version)" in
aws-cli/2.*) ;;
*) printf 'AWS CLI v2 is required\n' >&2; exit 1 ;;
esac
lua_headers=$(pkg-config --variable=includedir luajit)
test -f "$lua_headers/lua.h"
luarocks --lua-version=5.1 --tree="$PWD/rocks" install luasocket 3.1.0-1 \
LUA_INCDIR="$lua_headers" LUA="$(command -v luajit)"
)
インストールに失敗した場合は、報告された前提条件の問題を解決し、同じディレクトリでこのブロックを再実行してください。Lua ソースファイルは上書きされません。後述の実行スクリプトは、上位プロジェクトの Lua 検索パスに依存せず、./rocks から LuaSocket を読み込みます。libcurl がローダーの通常の検索パス外にある場合に限り、LIBCURL_PATH に信頼できる共有ライブラリの絶対パスを設定してください。OpenResty と LuaSec は不要です。このモジュールは HTTPS で直接接続し、プロキシとリダイレクトを無効にします。ネットワークで S3 への直接アクセスが許可されている必要があります。
AWS 認証情報の設定
既存の汎用バケットと、選択したプレフィックスに対する s3:PutObject および
s3:GetObject の権限を持つ認証情報を使用してください。実行スクリプトは AWS CLI の認証情報解決を使い、プロセスメモリ内で Lua に認証情報を渡します。まず組織の既存の AWS CLI ワークフローでサインインするか、デプロイ環境のシークレットマネージャーから認証情報を提供してください。一時認証情報には AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY、AWS_SESSION_TOKEN が必要です。長期認証情報ではトークンを省略します。プログラムに認証情報を貼り付けたり、シェルトレースを有効にしたりしないでください。
AWS_REGION と S3_BUCKET に、実際のバケットのリージョンと名前を設定してください。以下のデフォルトエンドポイントは、小文字、数字、ハイフンで構成された名前を持つ、AWS 商用リージョンの通常のバケットに対応します。他のパーティション、ドットを含む名前、アクセスポイント、ディレクトリバケットには、それぞれ検証済みのエンドポイント設定が必要です。この例では IAM の設定もバケットの作成も行いません。
検証済みの署名転送機能の使用
libcurl の CURLOPT_AWS_SIGV4 がリクエストに署名します。セッショントークンは x-amz-security-token として送信され、署名対象のヘッダーに含まれます。キーはスラッシュ区切りを維持したまま UTF-8 バイトとしてエンコードされます。URL の正規化でオブジェクトキーが変わらないように、モジュールは単独のパス要素
. と .. を拒否します。署名機能は POSTFIELDS の正確なバイト列をハッシュします。これは CUSTOMREQUEST で HTTP メソッド PUT を選択していても同じです。これにより、チュートリアル内で独自の暗号実装を保守せずに済みます。
LuaJIT からのアップロード
このモジュールを s3_upload.lua として保存してください。メモリ内の各オブジェクトは意図的に 16 MiB に制限しています。これより大きいアップロードには、別途検証したストリーミングまたはマルチパートの実装が必要です。各試行の接続時間制限は 10 秒、転送全体の時間制限は 60 秒なので、低速な接続では小さなファイルでもタイムアウトする場合があります。endpoint と
cafile は任意の信頼できるデプロイ設定で、HTTPS フィクスチャでのテストに役立ちます。認証されていないリクエストからこれらを受け取らないでください。
local ffi = require("ffi")
local socket = require("socket")
ffi.cdef[[
typedef void CURL;
struct curl_slist { char *data; struct curl_slist *next; };
int curl_global_init(long flags);
CURL *curl_easy_init(void);
void curl_easy_cleanup(CURL *handle);
int curl_easy_setopt(CURL *handle, int option, ...);
int curl_easy_perform(CURL *handle);
int curl_easy_getinfo(CURL *handle, int info, ...);
struct curl_slist *curl_slist_append(struct curl_slist *list, const char *value);
void curl_slist_free_all(struct curl_slist *list);
]]
local curl = ffi.load(os.getenv("LIBCURL_PATH") or "curl")
assert(curl.curl_global_init(3) == 0, "Cannot initialize libcurl")
-- Stable option identifiers from libcurl's public curl.h ABI.
local O = { URL=10002, PROXY=10004, WRITEFUNCTION=20011, POSTFIELDS=10015,
HTTPHEADER=10023, CUSTOMREQUEST=10036, SSL_VERIFYPEER=64, CAINFO=10065,
POSTFIELDSIZE=60, SSL_VERIFYHOST=81, CONNECTTIMEOUT=78, TIMEOUT=13,
USERNAME=10173, PASSWORD=10174, AWS_SIGV4=10305,
PROTOCOLS_STR=10318, FOLLOWLOCATION=52 }
local M = {}
function M.encode_key(key)
assert(type(key) == "string" and #key > 0 and #key <= 1024, "Invalid object key")
for part in key:gmatch("[^/]+") do
assert(part ~= "." and part ~= "..", "Dot path components are unsupported")
end
return (key:gsub("([^A-Za-z0-9/_.~-])", function(byte)
return string.format("%%%02X", byte:byte())
end))
end
local function header(value)
assert(type(value) == "string" and #value > 0 and not value:find("[%c]"), "Invalid header value")
return value
end
local function request(config, key, body, content_type)
local handle = curl.curl_easy_init()
assert(handle ~= nil, "Cannot allocate curl handle")
local headers = nil
local function append_header(value)
local updated = curl.curl_slist_append(headers, value)
assert(updated ~= nil, "Cannot allocate curl header")
headers = updated
end
local received = 0
local writer = ffi.cast("size_t (*)(char *, size_t, size_t, void *)", function(_, size, count)
local length = tonumber(size * count)
received = received + length
if received > 1024 * 1024 then return 0 end
return length
end)
local function option(name, value)
if type(value) == "number" then value = ffi.new("long", value) end
assert(curl.curl_easy_setopt(handle, O[name], value) == 0, "Unsupported curl option: " .. name)
end
local ok, result = pcall(function()
local endpoint = config.endpoint or ("https://" .. config.bucket .. ".s3." .. config.region .. ".amazonaws.com")
assert(endpoint:match("^https://[A-Za-z0-9.-]+:?%d*$"), "Expected a trusted HTTPS origin")
option("URL", endpoint .. "/" .. M.encode_key(key))
option("PROTOCOLS_STR", "https")
option("PROXY", "")
option("FOLLOWLOCATION", 0)
option("SSL_VERIFYPEER", 1)
option("SSL_VERIFYHOST", 2)
if config.cafile then option("CAINFO", config.cafile) end
option("CONNECTTIMEOUT", 10)
option("TIMEOUT", 60)
option("USERNAME", header(config.access_key))
option("PASSWORD", header(config.secret_key))
option("AWS_SIGV4", "aws:amz:" .. config.region .. ":s3")
option("CUSTOMREQUEST", "PUT")
option("POSTFIELDSIZE", #body)
option("POSTFIELDS", body)
option("WRITEFUNCTION", writer)
for _, value in ipairs({"Content-Type: " .. header(content_type), "Expect:"}) do
append_header(value)
end
if config.session_token then
append_header("x-amz-security-token: " .. header(config.session_token))
end
option("HTTPHEADER", headers)
local code = curl.curl_easy_perform(handle)
local status = ffi.new("long[1]")
assert(curl.curl_easy_getinfo(handle, 0x200002, status) == 0, "Cannot read HTTP status")
return { transport=tonumber(code), status=tonumber(status[0]) }
end)
curl.curl_easy_cleanup(handle)
curl.curl_slist_free_all(headers)
writer:free()
if not ok then error(result) end
return result
end
-- libcurl calls a Lua callback; this call path must stay outside compiled FFI traces.
jit.off(request, true)
function M.retryable(result)
if result.transport ~= 0 then
return ({[6]=true, [7]=true, [18]=true, [28]=true, [55]=true, [56]=true})[result.transport] == true
end
return ({[408]=true, [429]=true, [500]=true, [502]=true, [503]=true, [504]=true})[result.status] == true
end
function M.upload(config, file_path, key, content_type)
assert(config.region and config.region:match("^[a-z0-9-]+$"), "Invalid region")
assert(config.bucket and #config.bucket >= 3 and #config.bucket <= 63
and config.bucket:match("^[a-z0-9][a-z0-9-]*[a-z0-9]$"), "Invalid bucket name")
local file = assert(io.open(file_path, "rb"))
local body, read_error = file:read(16 * 1024 * 1024 + 1)
file:close()
if read_error then error(read_error) end
body = body or ""
assert(#body <= 16 * 1024 * 1024, "Use multipart upload for larger files")
for attempt = 1, 4 do
local result = request(config, key, body, content_type)
if result.transport == 0 and result.status == 200 then return true end
if attempt == 4 or not M.retryable(result) then
return nil, "Upload failed (transport " .. result.transport .. ", HTTP " .. result.status .. ")"
end
socket.sleep(math.min(8, 0.25 * 2^(attempt - 1)) * (0.5 + math.random()))
end
end
return M
この呼び出し元を upload.lua として保存してください。
local s3 = require("s3_upload")
local ok, err = s3.upload({
access_key = os.getenv("AWS_ACCESS_KEY_ID"),
secret_key = os.getenv("AWS_SECRET_ACCESS_KEY"),
session_token = os.getenv("AWS_SESSION_TOKEN"),
region = os.getenv("AWS_REGION"),
bucket = os.getenv("S3_BUCKET")
}, assert(arg[1], "local file required"), assert(arg[2], "object key required"), "application/octet-stream")
assert(ok, err)
print("Uploaded")
以下を upload.sh として保存してください。両方の Lua ファイルがあるディレクトリから実行します。認証情報のエクスポート元は信頼できる AWS CLI 実行ファイルです。スクリプトは古いセッショントークンを消去してから、解決された認証情報を読み込みます。設定は子プロセスにのみ適用されます。
#!/usr/bin/env bash
set +x
set -eu
for tool in aws luajit; do
command -v "$tool" >/dev/null || { printf 'Missing prerequisite: %s\n' "$tool" >&2; exit 1; }
done
: "${AWS_REGION:?Set AWS_REGION to the bucket region}"
: "${S3_BUCKET:?Set S3_BUCKET to the bucket name}"
credentials=$(aws configure export-credentials --format env)
unset AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN
eval "$credentials"
export LUA_PATH='./?.lua;./rocks/share/lua/5.1/?.lua;./rocks/share/lua/5.1/?/init.lua'
export LUA_CPATH='./rocks/lib/lua/5.1/?.so'
exec luajit upload.lua "$@"
16 MiB 以下の既存の通常ファイルを使うか、小さなバイナリのサンプルを作成してください。このブロックは既存の report.bin を上書きしません。
(
set -eu
test ! -e report.bin
printf 'September report\000\377\n' > report.bin
)
your-bucket-name を使用するバケットに置き換えてください。AWS CLI へのログインに名前付きプロファイルを使う場合は、環境に AWS_PROFILE を設定してください。オブジェクトキーは引用符で囲んだまま、事前にエンコードせず、元の表記で渡してください。
AWS_REGION=us-east-1 S3_BUCKET=your-bucket-name \
bash upload.sh report.bin 'reports/September café %.bin'
呼び出し元は、S3 が HTTP 200 を返した後にのみ
Uploaded を出力します。既存のキーにアップロードすると、その現在のオブジェクトが置き換わります。バージョニングが有効なバケットでは別のバージョンが保持されます。最初のテストには新しいキーを使用してください。
リモートのバイト列の確認
この独立したダウンロード確認スクリプトを verify.sh として保存してください。同じ AWS CLI 認証情報ソースを使用し、指定したキーを正確にダウンロードして、ローカルファイルとすべてのバイトを比較します。成功時も失敗時も一時コピーを削除します。
#!/usr/bin/env bash
set -eu
: "${AWS_REGION:?Set AWS_REGION to the bucket region}"
: "${S3_BUCKET:?Set S3_BUCKET to the bucket name}"
test "$#" -eq 2
test -f "$1"
download=$(mktemp)
trap 'rm -f "$download"' EXIT
aws s3api get-object --bucket "$S3_BUCKET" --key "$2" --region "$AWS_REGION" \
"$download" >/dev/null
cmp -- "$1" "$download"
printf 'Verified identical bytes\n'
AWS_REGION=us-east-1 S3_BUCKET=your-bucket-name \
bash verify.sh report.bin 'reports/September café %.bin'
Verified identical bytes が出力されることを確認してください。オブジェクトがない場合、ダウンロードが拒否された場合、バイト列が異なる場合は、代わりにゼロ以外の終了コードになります。アップロードから検証までの間、元のファイルを変更しないでください。PutObject が成功するとリクエストボディ全体が保存されますが、この比較では意図したファイルとキーを指定したかどうかも確認できます。
エラー処理とリトライ
この PutObject 操作の成功を確認できるのは、HTTP 200 のみです。リダイレクト、認証失敗、その他の恒久的な HTTP エラーでは直ちに停止します。特定の一時的な転送エラー、スロットリング、サービスエラーでは、上記の時間制限を各試行に適用して、最大四回試行します。証明書の検証失敗ではリトライしません。検証を無効にせず、CA バンドルやエンドポイントを修正してください。入力が存在しない場合やファイルが大きすぎる場合は、アップロード前に失敗します。待機には socket.sleep() を秒の小数値で使用します。シェルコマンドを組み立てたり、整数用プレースホルダーで小数をフォーマットしたりはしません。
リトライごとに、同じバイト列とキーに対する新しいリクエストに署名します。レスポンスが失われても、バージョニングが有効なバケットに複数のバージョンが作成されたり、通知が繰り返されたりする可能性があります。こうした影響が問題になる場合は、結果が不明な処理と実際の状態を照合してください。回数を制限したこの例では、適応的スロットリング、Retry-After の処理、認証情報の自動更新、厳密に一度だけの配信は実装していません。
コンテンツタイプの処理
呼び出し元は application/octet-stream を使用します。PDF のコンテンツタイプを保存するには、upload.lua 内のその文字列を
application/pdf に置き換えてください。ファイルとキーの引数はそのままです。これはオブジェクトのメタデータを設定するもので、ファイルの内容は検証しません。モジュールはヘッダー値の制御文字を拒否し、サービスのレスポンスボディをエラーとして返しません。
まとめ
モジュールを組み込む前に、使用権限のあるテストバケットの新しいキーに対して、アップロードとバイト比較を実行してください。この例のメモリ制限を超えるファイルには、ストリーミングまたはマルチパートのクライアントを選び、完了時の動作を別途検証してください。制限を引き上げても、ファイル全体が Lua 内でバッファリングされる点は変わりません。
ご自身での運用は避けたいですか?
Transloadit は、単一の API 呼び出し内の処理の一環として、S3、Azure、Google Cloud などにファイルをエクスポートします。
