API de S3

Os utilitários de armazenamento de objetos compatíveis com S3 estão disponíveis em ptool.s3 e p.s3.

ptool.s3.connect

v0.10.0 - Introduzido.

ptool.s3.connect(options) abre uma conexão de armazenamento de objetos compatível com S3 e retorna um objeto Connection.

Campos de options:

• bucket (string, obrigatório): O nome do bucket.
• region (string, opcional): A região da AWS ou do provedor.
• endpoint (string, opcional): Uma URL de endpoint compatível com S3 personalizada, como MinIO, R2 ou outro serviço de armazenamento de objetos.
• access_key_id (string, opcional): O ID da access key.
• secret_access_key (string, opcional): A secret access key.
• session_token (string, opcional): O token de sessão.
• root (string, opcional): Um prefixo raiz aplicado a todas as operações com objetos.
• allow_anonymous (boolean, opcional): Quando true, permite requisições sem assinatura se as credenciais não estiverem configuradas. O padrão é false.

Fallback de ambiente:

• Valores explícitos em options têm prioridade.
• Valores ausentes de region, endpoint, access_key_id, secret_access_key e session_token usam fallback para:
  • AWS_REGION
  • AWS_ENDPOINT, AWS_ENDPOINT_URL ou AWS_S3_ENDPOINT
  • AWS_ACCESS_KEY_ID
  • AWS_SECRET_ACCESS_KEY
  • AWS_SESSION_TOKEN
• O fallback de ambiente usa a visão do ambiente de runtime do ptool, então valores definidos com p.os.setenv(...) também ficam visíveis para ptool.s3.connect(...).

Exemplo:

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

Connection representa uma conexão aberta de armazenamento de objetos retornada por ptool.s3.connect().

Ela é implementada como um userdata Lua.

Métodos:

• 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

Regras de caminho:

• Os caminhos de objetos devem ser strings não vazias, salvo indicação em contrário.
• A barra inicial / é ignorada, então /foo/bar.txt e foo/bar.txt apontam para o mesmo objeto.
• Os caminhos são relativos a root quando root está configurado na conexão.

Estrutura da tabela de entrada:

• path (string): O caminho do objeto relativo à raiz da conexão.
• size (integer): O tamanho do objeto em bytes.
• etag (string | nil): O ETag do objeto, quando disponível.
• last_modified (string | nil): O timestamp da última modificação, quando disponível.
• content_type (string | nil): O tipo de conteúdo do objeto, quando disponível.
• version (string | nil): A versão do objeto, quando disponível.
• metadata (table | nil): Metadados definidos pelo usuário do objeto, quando disponíveis.
• is_file (boolean): Se a entrada é um arquivo.
• is_dir (boolean): Se a entrada é um diretório.
• mode (string): Um entre "file", "dir" ou "unknown".

read

v0.10.0 - Introduzido. Não lançado - Alterado.

Nome canônico da API: ptool.s3.Connection:read.

conn:read(path[, options]) lê um objeto como bytes brutos e retorna uma string Lua.

• path (string, obrigatório): O caminho do objeto.
• options (table, optional): Opções de leitura.
• Retorna: string.

Campos de options:

• range (table, optional): Lê um intervalo de bytes usando limites semiabertos [start, end).
  • start (integer, optional): O primeiro deslocamento de byte a incluir.
  • end (integer, optional): O primeiro deslocamento de byte a excluir.

Comportamento:

• Omitir range lê o objeto inteiro.
• { start = N } lê do byte N até o fim.
• { end = N } lê do início até, mas sem incluir, o byte N.
• { start = A, end = B } lê os bytes de A até B - 1.

Exemplo:

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 - Introduzido. Não lançado - Alterado.

Nome canônico da API: ptool.s3.Connection:write.

conn:write(path, content[, options]) grava uma string Lua em um objeto como bytes brutos e retorna uma tabela de entrada.

• path (string, obrigatório): O caminho do objeto.
• content (string, obrigatório): Os bytes a enviar.
• options (table, optional): Opções de gravação.
• Retorna: table.

Campos de options:

• content_type (string, optional): Define o tipo de conteúdo do objeto.
• cache_control (string, optional): Define o cabeçalho cache-control do objeto.
• content_disposition (string, optional): Define o cabeçalho content-disposition do objeto.
• content_encoding (string, optional): Define o cabeçalho content-encoding do objeto.
• metadata (table, optional): Define metadados personalizados como pares string chave/valor.
• if_not_exists (boolean, optional): Grava somente quando o objeto ainda não existe. O padrão é false.
• if_match (string, optional): Grava somente quando o ETag atual corresponde.
• if_none_match (string, optional): Grava somente quando o ETag atual não corresponde.

Comportamento:

• content é enviado byte a byte.
• Bytes NUL embutidos e bytes não UTF-8 são preservados.
• A entrada retornada evita uma chamada stat() imediata de acompanhamento para metadados comuns.
• Alguns serviços compatíveis com S3 podem não ecoar metadata ou etag definidos pelo usuário na resposta de gravação. Quando isso acontece, esses campos permanecem nil até um stat() posterior.

Exemplo:

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

Nome canônico da API: ptool.s3.Connection:delete.

conn:delete(path) exclui um objeto.

• path (string, obrigatório): O caminho do objeto.

exists

v0.10.0 - Introduzido.

Nome canônico da API: ptool.s3.Connection:exists.

conn:exists(path) verifica se um objeto existe.

• path (string, obrigatório): O caminho do objeto.
• Retorna: boolean.

list

v0.10.0 - Introduzido.

Nome canônico da API: ptool.s3.Connection:list.

conn:list([prefix]) lista entradas sob um prefixo e retorna uma tabela array Lua densa.

• prefix (string, opcional): O prefixo a listar. O padrão é a raiz da conexão.
• Retorna: table.

Exemplo:

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

Nome canônico da API: ptool.s3.Connection:stat.

conn:stat(path) retorna metadados de um único objeto.

• path (string, obrigatório): O caminho do objeto.
• Retorna: table.

Exemplo:

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

Nome canônico da API: ptool.s3.Connection:put_bucket_acl.

conn:put_bucket_acl(options) substitui a ACL do bucket e retorna nil em caso de sucesso.

• options (table, obrigatório): Opções da ACL do bucket.
• Retorna: nil.

Campos de options:

• acl (string, opcional): Uma ACL predefinida do bucket. Os valores aceitos são "authenticated-read", "private", "public-read" e "public-read-write".
• expected_bucket_owner (string, opcional): A requisição falha se o bucket não pertencer a este ID de conta da AWS.
• grant_full_control (string, opcional): Valor do cabeçalho x-amz-grant-full-control.
• grant_read (string, opcional): Valor do cabeçalho x-amz-grant-read.
• grant_read_acp (string, opcional): Valor do cabeçalho x-amz-grant-read-acp.
• grant_write (string, opcional): Valor do cabeçalho x-amz-grant-write.
• grant_write_acp (string, opcional): Valor do cabeçalho x-amz-grant-write-acp.

Comportamento:

• Forneça acl ou um ou mais campos grant_*. As duas formas não podem ser combinadas na mesma chamada.
• Todas as strings fornecidas devem ser não vazias.
• As strings de concessão usam a sintaxe dos cabeçalhos de concessão do S3, como um ID de conta, endereço de e-mail ou URI de grupo aceito pelo provedor de destino.
• A operação tem como alvo o bucket da conexão. O prefixo root da conexão não é aplicado.
• Muitos provedores compatíveis com S3 desabilitam ACLs ou não implementam as APIs de ACL. Nesse caso, o erro do provedor é retornado como s3_error.

Exemplo:

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

Nome canônico da API: ptool.s3.Connection:put_object_acl.

conn:put_object_acl(path, options) substitui a ACL de um objeto e retorna nil em caso de sucesso.

• path (string, obrigatório): O caminho do objeto.
• options (table, obrigatório): Opções da ACL do objeto.
• Retorna: nil.

Campos de options:

• acl (string, opcional): Uma ACL predefinida do objeto. Os valores aceitos são "authenticated-read", "aws-exec-read", "bucket-owner-full-control", "bucket-owner-read", "private", "public-read" e "public-read-write".
• expected_bucket_owner (string, opcional): A requisição falha se o bucket não pertencer a este ID de conta da AWS.
• grant_full_control (string, opcional): Valor do cabeçalho x-amz-grant-full-control.
• grant_read (string, opcional): Valor do cabeçalho x-amz-grant-read.
• grant_read_acp (string, opcional): Valor do cabeçalho x-amz-grant-read-acp.
• grant_write (string, opcional): Valor do cabeçalho x-amz-grant-write.
• grant_write_acp (string, opcional): Valor do cabeçalho x-amz-grant-write-acp.
• version_id (string, opcional): Aplica a ACL a esta versão do objeto.
• request_payer (string, opcional): Aceita somente "requester" e envia a confirmação de pagamento pelo solicitante.

Comportamento:

• Forneça acl ou um ou mais campos grant_*. As duas formas não podem ser combinadas na mesma chamada.
• Todas as strings fornecidas devem ser não vazias.
• As strings de concessão usam a sintaxe dos cabeçalhos de concessão do S3 aceita pelo provedor de destino.
• A / inicial é ignorada, e o prefixo root da conexão é aplicado à chave do objeto da mesma forma que nas outras operações de objeto.
• Muitos provedores compatíveis com S3 desabilitam ACLs ou não implementam as APIs de ACL. Nesse caso, o erro do provedor é retornado como s3_error.

Exemplo:

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