Expiração de arquivos: regras de ciclo de vida no object storage

Todo app que recebe arquivos acumula lixo: miniaturas temporárias, exports que o usuário baixa uma vez, logs, anexos de rascunhos abandonados. Se ninguém apaga, o storage cresce e a conta cresce junto. Um cron que lista e deleta objetos resolve, mas é mais código para manter e mais um ponto de falha.

Regras de ciclo de vida (lifecycle rules) resolvem isso dentro do próprio storage. Você declara a política uma vez e ela passa a valer para todos os arquivos que casam com o filtro, antigos e novos. Os exemplos abaixo usam a API do Amazon S3, que virou o padrão de mercado e é aceita por vários storages compatíveis.

O que é uma regra de ciclo de vida?#

É uma instrução com três partes: um filtro que escolhe os objetos, uma ação e um prazo. A ação mais comum é a expiração (apagar). Em storages com classes de armazenamento também existe a transição (mover para uma classe mais barata).

No S3, cada regra tem um ID (até 255 caracteres), um status (Enabled ou Disabled) e um filtro por prefixo de chave, por tags, por tamanho do objeto ou por uma combinação. Um filtro vazio atinge o bucket inteiro. O prefixo é o que você conhece como "pasta": tmp/, exports/, logs/.

Quando a regra roda?#

Não há horário exato. No S3, o prazo em dias é somado à data de criação do objeto (que é a data da última modificação) e o resultado é arredondado para a próxima meia-noite UTC. Um arquivo criado em 15/01 às 10h30 UTC com regra de 3 dias fica elegível em 19/01 às 00h00 UTC. A remoção em si acontece depois, de forma assíncrona.

Na prática, use a expiração para limpeza, não para segurança. Se um link precisa parar de funcionar em 10 minutos, use um link temporário assinado com validade curta e deixe a regra de ciclo de vida só para a faxina.

Como criar uma regra de expiração com boto3?#

Instale com pip install boto3 e leia as credenciais e o endpoint de variáveis de ambiente. O exemplo expira tudo em tmp/ depois de 7 dias e aborta uploads multipart parados há 3 dias.

import os

import boto3
from botocore.config import Config

s3 = boto3.client(
    "s3",
    region_name="us-east-1",
    endpoint_url=os.environ.get("S3_ENDPOINT"),  # omita na AWS; defina em storage compatível
    aws_access_key_id=os.environ["S3_ACCESS_KEY"],
    aws_secret_access_key=os.environ["S3_SECRET_KEY"],
    config=Config(signature_version="s3v4"),
)

s3.put_bucket_lifecycle_configuration(
    Bucket=os.environ["S3_BUCKET"],
    LifecycleConfiguration={
        "Rules": [
            {
                "ID": "expira-tmp-em-7-dias",
                "Status": "Enabled",
                "Filter": {"Prefix": "tmp/"},
                "Expiration": {"Days": 7},
            },
            {
                "ID": "aborta-multipart-parado",
                "Status": "Enabled",
                "Filter": {"Prefix": ""},
                "AbortIncompleteMultipartUpload": {"DaysAfterInitiation": 3},
            },
        ]
    },
)

Atenção: put_bucket_lifecycle_configuration substitui a configuração inteira. Para adicionar uma regra, leia as atuais com get_bucket_lifecycle_configuration, acrescente a nova e envie a lista completa. Se enviar só a nova, as outras somem.

A mesma coisa com a AWS CLI, usando um arquivo lifecycle.json com o conteúdo {"Rules": [...]}:

aws s3api put-bucket-lifecycle-configuration \
  --bucket "$S3_BUCKET" \
  --endpoint-url "$S3_ENDPOINT" \
  --lifecycle-configuration file://lifecycle.json

E o versionamento e os uploads incompletos?#

Dois casos pegam muita gente de surpresa.

Bucket com versionamento. A ação Expiration só mexe na versão atual: ela cria um marcador de exclusão e a versão antiga vira "não atual", ainda ocupando espaço. Para apagar de vez, adicione NoncurrentVersionExpiration com NoncurrentDays. Esse prazo é a sua janela de recuperação para deleções acidentais. Você pode usar NewerNoncurrentVersions (de 1 a 100) para manter as últimas N versões, mas então a regra precisa incluir o elemento Filter.

Uploads multipart abandonados. Uma regra de expiração não remove partes de um upload que nunca terminou, e essas partes continuam ocupando espaço. A ação AbortIncompleteMultipartUpload resolve isso, como no exemplo acima, mas não pode ser usada em regras com filtro por tags. Veja mais em como enviar arquivos grandes.

Como verificar que a regra funciona?#

1. Releia a configuração: s3.get_bucket_lifecycle_configuration(Bucket=...) deve devolver as regras com Status: Enabled.
2. Antes de ativar em produção, liste o prefixo com list_objects_v2(Prefix="tmp/"): é exatamente o conjunto que a regra atingiria.
3. Envie um objeto de teste em tmp/, espere passar o prazo (use 1 dia em um bucket de teste) e confirme que ele sumiu.
4. Confirme que uma pasta sem regra, como invoices/, não foi afetada.

Quais são os erros mais comuns?#

• Filtro vazio por engano. Filter: {"Prefix": ""} atinge o bucket todo. Numa regra de expiração, isso apaga todo objeto que passar do prazo.
• Esquecer a barra final. tmp também casa com tmp-final/. Use tmp/.
• Regra por data. Uma ação com Date não roda uma vez só: continua valendo para objetos novos enquanto a regra estiver ativa. Prefira Days.
• Substituir a configuração sem ler a anterior. Veja o aviso acima.
• Usar expiração onde precisa de retenção. Para cópias de banco de dados, defina o prazo de propósito, como em backups no object storage.

Como fazer isso na Square Cloud#

No Blob Storage da Square Cloud, a regra do exemplo (apagar o que está em tmp/ depois de 7 dias) não passa pela API de ciclo de vida do S3: ela vira uma regra de pasta "apagar após N dias", que você define no painel. A contagem parte da última escrita de cada arquivo, e prazos abaixo de 7 dias só existem no Enterprise; nos outros planos, os 7 dias do exemplo já são o mínimo. O endpoint S3 (https://s3-blob.squarecloud.app, região auto) cobre as operações de objeto: List, Head, Get, Put, Copy, Delete, multipart e URLs pré-assinadas.

A mesma pasta aceita outras regras que completam a faxina: visibilidade, cache, tamanho máximo e extensões permitidas. Em cada objeto, você ainda define expiração e Cache-Control. E vale o conselho da seção sobre quando a regra roda: para um link que precisa parar de funcionar logo, use uma URL pré-assinada ou o link temporário do painel, de até 24 horas, e deixe a regra de pasta só para a limpeza.

Não há taxa de saída nem de entrada, e a cota incluída vai de 5 GB a 250 GB, conforme o plano; apagar o que é temporário é o que mantém você dentro dela. Para começar, defina no painel a regra de 7 dias na pasta tmp/. Conheça o Blob Storage e compare as cotas em Preços.