Esta página foi traduzida automaticamente. Em caso de divergência, prevalece o original em inglês.

Scripts de envio para o R2 do 256t.org

Este diretório contém scripts para enviar conteúdo ao bucket do Cloudflare R2 que sustenta o 256t.org.

Visão geral

O bucket 256t-cids hospeda: - Arquivos de CID: arquivos de armazenamento endereçável por conteúdo (enviados por r2_upload.py) - Arquivos do site estático: arquivos gerados do site (enviados por r2_static_upload.py)

Os dois scripts usam a CLI Wrangler, da Cloudflare, para todas as operações no R2.

Scripts

r2_upload.py - Envio de arquivos de CID

Implementa armazenamento endereçável por conteúdo usando CIDs (identificadores de conteúdo) como chaves de objeto no R2.

r2_static_upload.py - Envio do site estático

Envia todos os arquivos do site estático do diretório dist/ para o R2, com os tipos de conteúdo e cabeçalhos de cache adequados.

Instalação

O script requer a CLI Wrangler (instalada via npm):

npm install -g wrangler
# ou use npx wrangler para uma execução avulsa

Uso

Enviar um arquivo de CID

python .github/scripts/r2_upload.py examples/hello.txt

Verificar um objeto de CID existente

python .github/scripts/r2_upload.py examples/hello.txt --verify-only

Enviar os arquivos do site estático

python .github/scripts/r2_static_upload.py dist

O nome do bucket 256t-cids está fixo no código dos dois scripts.

Configuração

O script usa o Wrangler para se autenticar no Cloudflare R2. Você vai precisar de: - CLOUDFLARE_ACCOUNT_ID: o ID da sua conta Cloudflare - CLOUDFLARE_API_TOKEN: um token de API da Cloudflare com permissões de leitura e escrita no R2

Eles podem ser definidos como variáveis de ambiente; caso contrário, o Wrangler solicitará a autenticação.

Comportamento do envio

Ao enviar um arquivo, o script:

  1. Calcula o CID a partir do conteúdo do arquivo
  2. Verifica se o objeto existe tentando baixá-lo
  3. Verifica o conteúdo se o objeto existir: - Se o CID do conteúdo baixado corresponder: pula o envio (já é válido) - Se o CID não corresponder: erro (violação de integridade)
  4. Envia o objeto com o Wrangler se ele não existir:
wrangler r2 object put 256t-cids/{cid} \
  --file {filepath} \
  --cache-control "public, max-age=31536000, immutable" \
  --content-type "application/octet-stream"

Processo de verificação

O script verifica os objetos da seguinte forma:

  1. Baixa o objeto com o Wrangler: bash wrangler r2 object get 256t-cids/{cid} --file /tmp/downloaded
  2. Calcula o CID a partir do conteúdo baixado
  3. Compara o CID calculado com o CID esperado

Se forem iguais, o objeto é válido. Caso contrário, há uma violação de integridade.

Configurações de cache

Todos os objetos enviados usam as seguintes configurações de cache:

Cache-Control: public, max-age=31536000, immutable

Isso instrui os clientes a manter o conteúdo em cache indefinidamente, já que o conteúdo endereçado por CID é imutável.

Integração com CI/CD (GitHub Actions)

Para usar este script no GitHub Actions, você precisa configurar os seguintes segredos no seu repositório:

Segredos obrigatórios do GitHub

  1. CLOUDFLARE_ACCOUNT_ID: o ID da sua conta Cloudflare
  2. CLOUDFLARE_API_TOKEN: um token de API da Cloudflare com permissões de leitura e escrita no R2

Configurando os segredos do GitHub

  1. Acesse Settings → Secrets and variables → Actions no seu repositório
  2. Clique em "New repository secret"
  3. Adicione cada um dos segredos obrigatórios

Configuração do workflow

O workflow r2-upload.yml usa esses segredos para se autenticar na Cloudflare:

- name: Upload to R2
  env:
    CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
    CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
  run: |
    npm install -g wrangler
    python .github/scripts/r2_upload.py examples/hello.txt

Diretrizes de validação

Ao validar objetos de CID:

  1. Baixe o objeto do R2
  2. Calcule o CID a partir do conteúdo baixado
  3. Compare com o CID esperado
  4. Observação: este método exige baixar o objeto inteiro, mas garante a integridade

Tratamento de erros

O script trata várias condições de erro:

Solução de problemas

"Content CID mismatch"

Indica um problema sério de integridade: existe um objeto com uma chave de CID, mas seu conteúdo não corresponde ao CID esperado. Isso nunca deve acontecer em operação normal.

Erros de autenticação

Verifique se suas credenciais da Cloudflare estão configuradas corretamente: - Confira a variável de ambiente CLOUDFLARE_ACCOUNT_ID - Confira a variável de ambiente CLOUDFLARE_API_TOKEN - Verifique se o token de API tem permissões de leitura e escrita no R2 - Verifique se o token não expirou

Desenvolvimento

Testando localmente

Para testar o script localmente:

  1. Instale o Wrangler: npm install -g wrangler
  2. Autentique-se na Cloudflare: wrangler login
  3. Defina o ID da sua conta: export CLOUDFLARE_ACCOUNT_ID=your-account-id
  4. Execute o script: python .github/scripts/r2_upload.py examples/hello.txt

Observação: o Wrangler também oferece desenvolvimento local do R2 com a opção --local, mas este script foi feito para buckets R2 remotos.

Referências