Version: Versión de desarrollo actual

S3 API

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

ptool.s3.connect

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

Campos de 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(...).

Ejemplo:

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

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

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

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

path (string, obligatorio): La ruta del objeto.
options (table, optional): Read options.
Returns: string.

Campos de 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.

Comportamiento:

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.

Ejemplo:

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

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, obligatorio): La ruta del objeto.
content (string, required): The bytes to upload.
options (table, optional): Write options.
Returns: table.

Campos de 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.

Comportamiento:

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

Ejemplo:

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

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

conn:delete(path) deletes an object.

path (string, obligatorio): La ruta del objeto.

exists

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

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

path (string, obligatorio): La ruta del objeto.
Returns: boolean.

list

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.

Ejemplo:

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

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

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

path (string, obligatorio): La ruta del objeto.
Returns: table.

Ejemplo:

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

Nombre canónico de la API: ptool.s3.Connection:put_bucket_acl.

conn:put_bucket_acl(options) reemplaza la ACL del bucket y devuelve nil si la operación se completa correctamente.

options (table, obligatorio): Opciones de ACL del bucket.
Devuelve: nil.

Campos de options:

acl (string, opcional): Una ACL predefinida del bucket. Los valores aceptados son "authenticated-read", "private", "public-read" y "public-read-write".
expected_bucket_owner (string, opcional): La solicitud falla si el bucket no pertenece a este ID de cuenta de AWS.
grant_full_control (string, opcional): Valor para la cabecera x-amz-grant-full-control.
grant_read (string, opcional): Valor para la cabecera x-amz-grant-read.
grant_read_acp (string, opcional): Valor para la cabecera x-amz-grant-read-acp.
grant_write (string, opcional): Valor para la cabecera x-amz-grant-write.
grant_write_acp (string, opcional): Valor para la cabecera x-amz-grant-write-acp.

Comportamiento:

Proporcione acl o uno o más campos grant_*. Las dos formas no pueden combinarse en una misma llamada.
Cada cadena proporcionada debe contener al menos un carácter.
Las cadenas de concesión usan la sintaxis de las cabeceras de concesión de S3, como un ID de cuenta, una dirección de correo electrónico o un URI de grupo aceptado por el proveedor de destino.
La operación se aplica al bucket de la conexión. No se aplica el prefijo root de la conexión.
Muchos proveedores compatibles con S3 deshabilitan las ACL o no implementan sus API. En ese caso, el error del proveedor se devuelve como s3_error.

Ejemplo:

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

Nombre canónico de la API: ptool.s3.Connection:put_object_acl.

conn:put_object_acl(path, options) reemplaza la ACL de un objeto y devuelve nil si la operación se completa correctamente.

path (string, obligatorio): La ruta del objeto.
options (table, obligatorio): Opciones de ACL del objeto.
Devuelve: nil.

Campos de options:

acl (string, opcional): Una ACL predefinida del objeto. Los valores aceptados son "authenticated-read", "aws-exec-read", "bucket-owner-full-control", "bucket-owner-read", "private", "public-read" y "public-read-write".
expected_bucket_owner (string, opcional): La solicitud falla si el bucket no pertenece a este ID de cuenta de AWS.
grant_full_control (string, opcional): Valor para la cabecera x-amz-grant-full-control.
grant_read (string, opcional): Valor para la cabecera x-amz-grant-read.
grant_read_acp (string, opcional): Valor para la cabecera x-amz-grant-read-acp.
grant_write (string, opcional): Valor para la cabecera x-amz-grant-write.
grant_write_acp (string, opcional): Valor para la cabecera x-amz-grant-write-acp.
version_id (string, opcional): Aplica la ACL a esta versión del objeto.
request_payer (string, opcional): Solo acepta "requester" y envía la confirmación de pago por el solicitante.

Comportamiento:

Proporcione acl o uno o más campos grant_*. Las dos formas no pueden combinarse en una misma llamada.
Cada cadena proporcionada debe contener al menos un carácter.
Las cadenas de concesión usan la sintaxis de las cabeceras de concesión de S3 aceptada por el proveedor de destino.
Se ignora el / inicial y el prefijo root de la conexión se aplica a la clave del objeto del mismo modo que en las demás operaciones de objetos.
Muchos proveedores compatibles con S3 deshabilitan las ACL o no implementan sus API. En ese caso, el error del proveedor se devuelve como s3_error.

Ejemplo:

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

ptool.s3.connect​

Connection​

read​

write​

delete​

exists​

list​

stat​

put_bucket_acl​

put_object_acl​

ptool.s3.connect

Connection

read

write

delete

exists

list

stat

put_bucket_acl

put_object_acl