directus-bulk-fetch

CLI para download em massa de arquivos da coleção directus_files do Directus.

Descrição

Este pacote fornece uma ferramenta de linha de comando interativa para conectar-se a uma instância Directus e fazer o download em massa de arquivos da coleção directus_files, com suporte a downloads paralelos, retry automático, filtros por data e muito mais.

Funcionalidades

• 🔐 Autenticação por token
• 📥 Download automático de arquivos
• 🚀 Downloads paralelos/simultâneos configuráveis
• 🔄 Retry automático com backoff exponencial
• ⏱️ Timeout configurável para requisições
• 🎯 Filtros por período de upload
• 💾 Detecção de arquivos já baixados (evita re-downloads)
• 📋 Modo resume: retoma downloads que falharam
• 📊 Relatório detalhado com estatísticas
• 💥 Rastreamento de falhas em JSON
• ⚙️ Configuração via arquivo .env ou modo interativo

Instalação

Via npm (Recomendado)

npm install -g directus-bulk-fetch

Ou com npx (sem instalação global):

npx directus-bulk-fetch

Configuração

Copie o arquivo .env.example para .env e configure as variáveis:

cp .env.example .env

Edite o arquivo .env com suas credenciais:

# Configuração do Directus
DIRECTUS_URL=http://localhost:8055
DIRECTUS_TOKEN=seu-token-aqui

# Configuração de Rate Limit (intervalo em milissegundos entre requisições)
RATE_LIMIT_INTERVAL_MS=200

# Número de downloads simultâneos
CONCURRENT_DOWNLOADS=3

# Diretório de destino para os arquivos baixados
OUTPUT_DIR=./downloads

Uso

Modo Interativo (Recomendado)

Se instalado globalmente:

directus-bulk-fetch

Com npx:

npx directus-bulk-fetch

Menu Interativo

O CLI apresenta as seguintes opções:

1. Fazer download de arquivos: Inicia o processo de download com os parâmetros configurados
2. Ver configuração atual: Exibe as configurações em uso
3. Configurar credenciais: Permite alterar as credenciais para a sessão atual
4. Sair: Encerra a aplicação

Parâmetros de Download

Durante o processo de download, você poderá configurar:

• Data de início: Filtrar arquivos a partir de uma data de upload
• Data de fim: Filtrar arquivos até uma data de upload
• Limite de arquivos: Quantidade máxima de arquivos a baixar (-1 para todos)
• Diretório de destino: Onde os arquivos serão salvos
• Intervalo entre requisições: Tempo em milissegundos entre cada lote de requisições (rate limiting)
• Número de downloads simultâneos: Quantidade de arquivos baixados em paralelo (1-10)
• Número de retries: Tentativas em caso de falha (1-10)
• Timeout: Tempo máximo de espera por requisição em milissegundos
• Modo resume: Baixar apenas arquivos que falharam anteriormente

Como Funciona

1. Conexão: Conecta-se ao Directus usando a URL e token fornecidos
2. Consulta: Busca registros da coleção directus_files com os filtros de data aplicados
3. Download em Lotes: Baixa arquivos em lotes paralelos (configurável) usando a API do Directus (/assets/:id)
4. Retry com Backoff: Tenta novamente automaticamente em caso de falha, com espera exponencial
5. Validação: Verifica se o arquivo já existe antes de baixar (evita duplicatas)
6. Rastreamento de Falhas: Salva em JSON os arquivos que falharam após todas as tentativas
7. Modo Resume: Permite retomar o download apenas dos arquivos que falharam

Exemplos de Uso

Download de todos os arquivos

npx directus-bulk-fetch
# Selecione "Fazer download de arquivos"
# Deixe todos os filtros vazios
# Defina limite como -1

Download com período específico

npx directus-bulk-fetch
# Selecione "Fazer download de arquivos"
# Informe data de início: 2024-01-01
# Informe data de fim: 2024-12-31

Download em modo resume (após falhas)

npx directus-bulk-fetch
# Selecione "Fazer download de arquivos"
# Responda "Sim" para "Modo resume"
# Apenas arquivos que falharam anteriormente serão baixados

Notas Técnicas

• ✅ Arquivos já existentes no diretório de destino não serão baixados novamente
• 🔄 O rate limiting ajuda a evitar sobrecarga no servidor Directus
• 💾 Falhas são salvas em failed-downloads.json no diretório de destino
• ⏱️ O retry usa backoff exponencial (1s, 2s, 3s, etc.)
• 🔗 URLs do Directus com barra final (/) são tratadas corretamente
• 🎯 Apenas arquivos com filename_disk válido são processados
• 🔐 Autenticação via query parameter para compatibilidade com /assets endpoint

Solução de Problemas

Erro 404 nos downloads

Verifique se:

• A URL do Directus está correta (pode ter ou não barra final)
• O token tem permissões para acessar a coleção directus_files
• Os arquivos existem fisicamente no storage do Directus

Downloads lentos

Aumente o número de downloads simultâneos no .env:

CONCURRENT_DOWNLOADS=5  # Aumentar de 3 para 5

Muitos timeouts

Aumente o timeout no .env:

TIMEOUT_MS=60000  # 60 segundos

Roadmap

• [ ] Suporte a diferentes formatos de arquivo (não apenas JPG)
• [ ] Buscar metadados do arquivo para nome correto
• [ ] Opção de escolher coleção customizada
• [ ] Progress bar visual
• [ ] Exportação de relatório em CSV

Licença

Ver arquivo LICENSE