メインコンテンツまでスキップ
バージョン: 現在の開発版

S3 API

S3-compatible object storage helpers are available under ptool.s3 and p.s3.

ptool.s3.connect​

v0.10.0 - 追加。

ptool.s3.connect(options) opens an S3-compatible object storage connection and returns a Connection object.

options のフィールド:

  • bucket (string, required): The bucket name.
  • region (string, optional): The AWS region or provider region.
  • endpoint (string, optional): A custom S3-compatible endpoint URL such as MinIO, R2, or another object storage service.
  • access_key_id (string, optional): The access key ID.
  • secret_access_key (string, optional): The secret access key.
  • session_token (string, optional): The session token.
  • root (string, optional): A root prefix applied to all object operations.
  • allow_anonymous (boolean, optional): When true, allow unsigned requests if credentials are not configured. Defaults to false.

Environment fallback:

  • Explicit options values win.
  • Missing region, endpoint, access_key_id, secret_access_key, and session_token values fall back to:
    • AWS_REGION
    • AWS_ENDPOINT, AWS_ENDPOINT_URL, or AWS_S3_ENDPOINT
    • AWS_ACCESS_KEY_ID
    • AWS_SECRET_ACCESS_KEY
    • AWS_SESSION_TOKEN
  • Environment fallback uses ptool's runtime environment view, so values set through p.os.setenv(...) are also visible to ptool.s3.connect(...).

例:

local s3 = ptool.s3.connect({
  bucket = "artifacts",
  region = "auto",
  endpoint = "https://<account>.r2.cloudflarestorage.com",
  access_key_id = p.os.getenv("AWS_ACCESS_KEY_ID"),
  secret_access_key = p.os.getenv("AWS_SECRET_ACCESS_KEY"),
  root = "builds/",
})

Connection​

v0.10.0 - 追加。

Connection represents an open object storage connection returned by ptool.s3.connect().

It is implemented as a Lua userdata.

Methods:

  • conn:read(path[, options]) -> string
  • conn:write(path, content[, options]) -> table
  • conn:delete(path) -> nil
  • conn:exists(path) -> boolean
  • conn:list([prefix]) -> table
  • conn:stat(path) -> table
  • conn:put_bucket_acl(options) -> nil
  • conn:put_object_acl(path, options) -> nil

Path rules:

  • Object paths must be non-empty strings unless otherwise noted.
  • Leading / is ignored, so /foo/bar.txt and foo/bar.txt target the same object.
  • Paths are relative to root when root is configured on the connection.

Entry table shape:

  • path (string): The object path relative to the connection root.
  • size (integer): The object size in bytes.
  • etag (string | nil): The object ETag when available.
  • last_modified (string | nil): The last-modified timestamp when available.
  • content_type (string | nil): The object content type when available.
  • version (string | nil): The object version when available.
  • metadata (table | nil): User-defined object metadata when available.
  • is_file (boolean): Whether the entry is a file.
  • is_dir (boolean): Whether the entry is a directory.
  • mode (string): One of "file", "dir", or "unknown".

read​

v0.10.0 - Introduced. Unreleased - Changed.

Canonical API name: ptool.s3.Connection:read.

conn:read(path[, options]) reads an object as raw bytes and returns a Lua string.

  • path (string、必須): オブジェクトのパス。
  • options (table, optional): Read options.
  • Returns: string.

options のフィールド:

  • range (table, optional): Reads a byte range using half-open bounds [start, end).
    • start (integer, optional): The first byte offset to include.
    • end (integer, optional): The first byte offset to exclude.

動作:

  • Omitting range reads the full object.
  • { start = N } reads from byte N to the end.
  • { end = N } reads from the beginning up to, but not including, byte N.
  • { start = A, end = B } reads bytes A through B - 1.

例:

local s3 = ptool.s3.connect({ bucket = "artifacts" })
local content = s3:read("releases/v1.0.0/notes.txt")
print(content)

local prefix = s3:read("releases/v1.0.0/notes.txt", {
  range = { start = 0, end = 5 },
})
print(prefix)

write​

v0.10.0 - Introduced. Unreleased - Changed.

Canonical API name: ptool.s3.Connection:write.

conn:write(path, content[, options]) writes a Lua string to an object as raw bytes and returns an entry table.

  • path (string、必須): オブジェクトのパス。
  • content (string, required): The bytes to upload.
  • options (table, optional): Write options.
  • Returns: table.

options のフィールド:

  • content_type (string, optional): Sets the object content type.
  • cache_control (string, optional): Sets the object cache-control header.
  • content_disposition (string, optional): Sets the object content-disposition header.
  • content_encoding (string, optional): Sets the object content-encoding header.
  • metadata (table, optional): Sets user-defined metadata as string key/value pairs.
  • if_not_exists (boolean, optional): Write only when the object does not already exist. Defaults to false.
  • if_match (string, optional): Write only when the current ETag matches.
  • if_none_match (string, optional): Write only when the current ETag does not match.

動作:

  • content is uploaded byte-for-byte.
  • Embedded NUL bytes and non-UTF-8 bytes are preserved.
  • The returned entry avoids an immediate follow-up stat() call for common metadata.
  • Some S3-compatible services may not echo user-defined metadata or etag in the write response. When that happens, those fields remain nil until a later stat().

例:

local s3 = ptool.s3.connect({ bucket = "artifacts" })
local entry = s3:write("tmp/hello.txt", "hello\n", {
  content_type = "text/plain; charset=utf-8",
  metadata = { author = "ptool" },
})
print(entry.path, entry.etag, entry.version)

s3:write("tmp/blob.bin", "\x00\xffABC")

delete​

v0.10.0 - 追加。

Canonical API name: ptool.s3.Connection:delete.

conn:delete(path) deletes an object.

  • path (string、必須): オブジェクトのパス。

exists​

v0.10.0 - 追加。

Canonical API name: ptool.s3.Connection:exists.

conn:exists(path) checks whether an object exists.

  • path (string、必須): オブジェクトのパス。
  • Returns: boolean.

list​

v0.10.0 - 追加。

Canonical API name: ptool.s3.Connection:list.

conn:list([prefix]) lists entries under a prefix and returns a dense Lua array table.

  • prefix (string, optional): The prefix to list. Defaults to the connection root.
  • Returns: table.

例:

local s3 = ptool.s3.connect({ bucket = "artifacts", root = "builds/" })
local entries = s3:list("2026/")

for _, entry in ipairs(entries) do
  print(entry.path, entry.mode, entry.size)
end

stat​

v0.10.0 - 追加。

Canonical API name: ptool.s3.Connection:stat.

conn:stat(path) returns metadata for a single object.

  • path (string、必須): オブジェクトのパス。
  • Returns: table.

例:

local s3 = ptool.s3.connect({ bucket = "artifacts" })
local meta = s3:stat("releases/v1.0.0/app.tar.zst")
print(meta.size, meta.etag, meta.last_modified)

put_bucket_acl​

v0.12.0 - 追加。

正規 API 名: ptool.s3.Connection:put_bucket_acl。

conn:put_bucket_acl(options) はバケット ACL を置き換え、成功時に nil を返します。

  • options (table、必須): バケット ACL のオプション。
  • 戻り値: nil。

options のフィールド:

  • acl (string、任意): 定義済みバケット ACL。指定可能な値は "authenticated-read"、"private"、"public-read"、"public-read-write" です。
  • expected_bucket_owner (string、任意): バケットの所有者がこの AWS アカウント ID でない場合、リクエストは失敗します。
  • grant_full_control (string、任意): x-amz-grant-full-control ヘッダーの値。
  • grant_read (string、任意): x-amz-grant-read ヘッダーの値。
  • grant_read_acp (string、任意): x-amz-grant-read-acp ヘッダーの値。
  • grant_write (string、任意): x-amz-grant-write ヘッダーの値。
  • grant_write_acp (string、任意): x-amz-grant-write-acp ヘッダーの値。

動作:

  • acl または 1 つ以上の grant_* フィールドのどちらかを指定します。両方の形式を 1 回の呼び出しで併用することはできません。
  • 指定する文字列はすべて空でない必要があります。
  • 権限付与文字列には、対象プロバイダーが受け付けるアカウント ID、メールアドレス、グループ URI などの S3 権限付与ヘッダー構文を使用します。
  • この操作は接続先バケットを対象とします。接続の root プレフィックスは適用されません。
  • 多くの S3 互換プロバイダーでは ACL が無効化されているか、ACL API が実装されていません。その場合、プロバイダーのエラーが s3_error として返されます。

例:

local s3 = ptool.s3.connect({ bucket = "artifacts" })

s3:put_bucket_acl({ acl = "private" })

s3:put_bucket_acl({
  grant_read = 'uri="http://acs.amazonaws.com/groups/global/AllUsers"',
})

put_object_acl​

v0.12.0 - 追加。

正規 API 名: ptool.s3.Connection:put_object_acl。

conn:put_object_acl(path, options) はオブジェクトの ACL を置き換え、成功時に nil を返します。

  • path (string、必須): オブジェクトのパス。
  • options (table、必須): オブジェクト ACL のオプション。
  • 戻り値: nil。

options のフィールド:

  • acl (string、任意): 定義済みオブジェクト ACL。指定可能な値は "authenticated-read"、"aws-exec-read"、"bucket-owner-full-control"、"bucket-owner-read"、"private"、"public-read"、"public-read-write" です。
  • expected_bucket_owner (string、任意): バケットの所有者がこの AWS アカウント ID でない場合、リクエストは失敗します。
  • grant_full_control (string、任意): x-amz-grant-full-control ヘッダーの値。
  • grant_read (string、任意): x-amz-grant-read ヘッダーの値。
  • grant_read_acp (string、任意): x-amz-grant-read-acp ヘッダーの値。
  • grant_write (string、任意): x-amz-grant-write ヘッダーの値。
  • grant_write_acp (string、任意): x-amz-grant-write-acp ヘッダーの値。
  • version_id (string、任意): このオブジェクトバージョンに ACL を適用します。
  • request_payer (string、任意): "requester" のみを受け付け、リクエスタ支払いの承認を送信します。

動作:

  • acl または 1 つ以上の grant_* フィールドのどちらかを指定します。両方の形式を 1 回の呼び出しで併用することはできません。
  • 指定する文字列はすべて空でない必要があります。
  • 権限付与文字列には、対象プロバイダーが受け付ける S3 権限付与ヘッダー構文を使用します。
  • 先頭の / は無視され、接続の root プレフィックスが他のオブジェクト操作と同じ方法でオブジェクトキーに適用されます。
  • 多くの S3 互換プロバイダーでは ACL が無効化されているか、ACL API が実装されていません。その場合、プロバイダーのエラーが s3_error として返されます。

例:

local s3 = ptool.s3.connect({
  bucket = "artifacts",
  root = "public/",
})

s3:put_object_acl("index.html", { acl = "public-read" })

s3:put_object_acl("release.zip", {
  acl = "bucket-owner-full-control",
  version_id = "example-version-id",
  request_payer = "requester",
})