S3 API

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

ptool.s3.connect

v0.10.0 - Introduced.

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

options fields:

• 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(...).

Example:

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 - Introduced.

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, required): The object path.
• options (table, optional): Read options.
• Returns: string.

options fields:

• 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.

Behavior:

• 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.

Example:

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, required): The object path.
• content (string, required): The bytes to upload.
• options (table, optional): Write options.
• Returns: table.

options fields:

• 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.

Behavior:

• 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().

Example:

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 - Introduced.

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

conn:delete(path) deletes an object.

• path (string, required): The object path.

exists

v0.10.0 - Introduced.

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

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

• path (string, required): The object path.
• Returns: boolean.

list

v0.10.0 - Introduced.

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.

Example:

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 - Introduced.

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

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

• path (string, required): The object path.
• Returns: table.

Example:

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 - Introduced.

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

conn:put_bucket_acl(options) replaces the bucket ACL and returns nil on success.

• options (table, required): Bucket ACL options.
• Returns: nil.

options fields:

• acl (string, optional): A canned bucket ACL. Accepted values are "authenticated-read", "private", "public-read", and "public-read-write".
• expected_bucket_owner (string, optional): Fails the request if the bucket is not owned by this AWS account ID.
• grant_full_control (string, optional): Value for the x-amz-grant-full-control header.
• grant_read (string, optional): Value for the x-amz-grant-read header.
• grant_read_acp (string, optional): Value for the x-amz-grant-read-acp header.
• grant_write (string, optional): Value for the x-amz-grant-write header.
• grant_write_acp (string, optional): Value for the x-amz-grant-write-acp header.

Behavior:

• Supply either acl or one or more grant_* fields. The two forms cannot be combined in one call.
• Every supplied string must be non-empty.
• Grant strings use the S3 grant-header syntax, such as an account ID, email address, or group URI accepted by the target provider.
• The operation targets the connection bucket. The connection's root prefix is not applied.
• Many S3-compatible providers disable ACLs or do not implement the ACL APIs. In that case, the provider error is returned as an s3_error.

Example:

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 - Introduced.

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

conn:put_object_acl(path, options) replaces an object's ACL and returns nil on success.

• path (string, required): The object path.
• options (table, required): Object ACL options.
• Returns: nil.

options fields:

• acl (string, optional): A canned object ACL. Accepted values are "authenticated-read", "aws-exec-read", "bucket-owner-full-control", "bucket-owner-read", "private", "public-read", and "public-read-write".
• expected_bucket_owner (string, optional): Fails the request if the bucket is not owned by this AWS account ID.
• grant_full_control (string, optional): Value for the x-amz-grant-full-control header.
• grant_read (string, optional): Value for the x-amz-grant-read header.
• grant_read_acp (string, optional): Value for the x-amz-grant-read-acp header.
• grant_write (string, optional): Value for the x-amz-grant-write header.
• grant_write_acp (string, optional): Value for the x-amz-grant-write-acp header.
• version_id (string, optional): Applies the ACL to this object version.
• request_payer (string, optional): Accepts only "requester" and sends the requester-pays acknowledgement.

Behavior:

• Supply either acl or one or more grant_* fields. The two forms cannot be combined in one call.
• Every supplied string must be non-empty.
• Grant strings use the S3 grant-header syntax accepted by the target provider.
• Leading / is ignored, and the connection's root prefix is applied to the object key in the same way as other object operations.
• Many S3-compatible providers disable ACLs or do not implement the ACL APIs. In that case, the provider error is returned as an s3_error.

Example:

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",
})