S3 API

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

ptool.s3.connect

Unreleased - 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

Unreleased - Introduced.

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

It is implemented as a Lua userdata.

Methods:

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

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

Unreleased - Introduced.

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

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

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

Example:

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

write

Unreleased - Introduced.

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

conn:write(path, content) writes a Lua string to an object as raw bytes.

• path (string, required): The object path.
• content (string, required): The bytes to upload.

Behavior:

• content is uploaded byte-for-byte.
• Embedded NUL bytes and non-UTF-8 bytes are preserved.

Example:

local s3 = ptool.s3.connect({ bucket = "artifacts" })
s3:write("tmp/hello.txt", "hello\n")
s3:write("tmp/blob.bin", "\x00\xffABC")

delete

Unreleased - Introduced.

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

conn:delete(path) deletes an object.

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

exists

Unreleased - 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

Unreleased - 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

Unreleased - 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)