Cloud Storage

Acesse armazenamento de objetos compativel com S3. Upload, download, listagem e gerenciamento de arquivos com suporte a URLs pre-assinadas.

Para configuração de armazenamento, veja Cloud Storage.

Carregamento

local cloudstorage = require("cloudstorage")

Adquirindo Storage

Obter um recurso de cloud storage por ID do registro:

local storage, err = cloudstorage.get("app.infra:files")
if err then
    return nil, err
end

storage:upload_object("data/file.txt", "content")
storage:release()

Retorna: Storage, error

Fazendo Upload de Objetos

Upload de conteudo de string ou arquivo:

local storage = cloudstorage.get("app.infra:files")

-- Upload de conteudo string
local ok, err = storage:upload_object("reports/daily.json", json.encode({
    date = "2024-01-15",
    total = 1234
}))

-- Upload de arquivo
local fs = require("fs")
local vol = fs.get("app:data")
local file = vol:open("/large-file.bin", "r")

storage:upload_object("backups/large-file.bin", file)
file:close()

storage:release()

Retorna: boolean, error

Opções de Upload

Anexe metadados ou proteja a escrita com uma tabela de opções:

storage:upload_object("reports/daily.json", body, {
    content_type = "application/json",
    cache_control = "max-age=3600",
    metadata = { owner = "team-a", run_id = "1234" },  -- armazenado como x-amz-meta-*
    only_if_absent = true                              -- falha se a chave já existir
})

Uma escrita condicional que falha sua pré-condição retorna um erro precondition_failed.

Baixando Objetos

Baixar um objeto para um file writer:

local storage = cloudstorage.get("app.infra:files")
local fs = require("fs")
local vol = fs.get("app:temp")

local file = vol:open("/downloaded.json", "w")
local ok, err = storage:download_object("reports/daily.json", file)
file:close()

-- Baixar conteudo parcial (primeiro 1KB)
local partial = vol:open("/partial.bin", "w")
storage:download_object("backups/large-file.bin", partial, {
    range = "bytes=0-1023"
})
partial:close()

storage:release()

Retorna: boolean, error

Uma pré-condição que falha (if_match/if_none_match) retorna um erro precondition_failed.

Listando Objetos

Listar objetos com filtragem opcional por prefixo:

local storage = cloudstorage.get("app.infra:files")

local result, err = storage:list_objects({
    prefix = "reports/2024/",
    max_keys = 100
})

for _, obj in ipairs(result.objects) do
    print(obj.key, obj.size, obj.etag)
end

-- Paginar através de resultados grandes
local token = nil
repeat
    local result = storage:list_objects({
        prefix = "logs/",
        max_keys = 1000,
        continuation_token = token
    })
    for _, obj in ipairs(result.objects) do
        process(obj)
    end
    token = result.next_continuation_token
until not result.is_truncated

storage:release()

Retorna: table, error

Resultado contem objects, is_truncated, next_continuation_token. Cada objeto tem key, size, etag, storage_class e, opcionalmente, last_modified, version_id e owner.

Metadados do Objeto

Obtenha os metadados de um único objeto sem baixar seu corpo:

local storage = cloudstorage.get("app.infra:files")

local meta, err = storage:head_object("reports/daily.json")
if err then
    return nil, err
end

print(meta.size, meta.etag, meta.content_type)
for k, v in pairs(meta.metadata) do
    print("meta", k, v)
end

storage:release()

Retorna: table, error

Campos do resultado:

Um objeto inexistente retorna um erro not_found.

Deletando Objetos

Remover multiplos objetos:

local storage = cloudstorage.get("app.infra:files")

storage:delete_objects({
    "temp/file1.txt",
    "temp/file2.txt",
    "temp/file3.txt"
})

storage:release()

Retorna: boolean, error

URLs de Download

Criar uma URL temporaria que permite baixar um objeto sem credenciais. Util para compartilhar arquivos com usuários externos ou servir conteudo através da sua aplicação.

local storage, err = cloudstorage.get("app.infra:files")
if err then
    return nil, err
end

local url, err = storage:presigned_get_url("reports/quarterly.pdf", {
    expiration = 3600
})

storage:release()

if err then
    return nil, err
end

-- Retornar URL ao cliente para download direto
return {download_url = url}

Retorna: string, error

URLs de Upload

Criar uma URL temporaria que permite fazer upload de um objeto sem credenciais. Permite que clientes facam upload de arquivos diretamente para o armazenamento sem fazer proxy pelo seu servidor.

local storage, err = cloudstorage.get("app.infra:files")
if err then
    return nil, err
end

local url, err = storage:presigned_put_url("uploads/user-123/avatar.jpg", {
    expiration = 600,
    content_type = "image/jpeg",
    content_length = 1024 * 1024
})

storage:release()

if err then
    return nil, err
end

-- Retornar URL ao cliente para upload direto
return {upload_url = url}

Retorna: string, error

Métodos de Storage

Permissões

Operações de cloud storage estao sujeitas a avaliação de política de segurança.

Erros

Veja Error Handling para trabalhar com erros.