Skip to content
/ rustdrivesync Public

Sincronização unidirecional de arquivos com Google Drive - CLI desenvolvida em Rust com arquitetura limpa, rate limiting, retry automático e uploads paralelos

License

MIT license
0 stars 0 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

chapzin/rustdrivesync

BranchesTags

Repository files navigation

RustDriveSync

Rust License Status Version Tests Coverage

Sincronização unidirecional de arquivos com Google Drive

RustDriveSync é uma ferramenta CLI desenvolvida em Rust para sincronização eficiente e confiável de arquivos locais com o Google Drive. Projetada para ser leve, rápida e segura.

🎯 Características

Core Features (V1.0)

  • ✅ Dependency Injection - Abstrações via traits para múltiplos backends
  • ✅ Rate Limiting - Proteção automática contra limites da API (800 req/100s)
  • ✅ Retry com Backoff - Recuperação automática de falhas (exponential backoff)
  • ✅ Uploads Paralelos - Até 10x mais rápido (configurável)
  • ✅ Thread-Safe - Arquitetura async/await com Tokio
  • ✅ Sincronização unidirecional (local → Google Drive)
  • ✅ Modo único ou monitoramento contínuo (watch mode)
  • ✅ Upload com streaming - memória constante para arquivos grandes
  • ✅ Autenticação OAuth2 segura
  • ✅ Configuração via arquivo TOML
  • ✅ Logs detalhados com níveis configuráveis
  • ✅ Detecção de mudanças por hash MD5 incremental
  • ✅ Detecção automática de MIME types - suporte a 800+ formatos
  • ✅ Preservação de estrutura de pastas - mantém hierarquia de diretórios

Qualidade e Arquitetura

  • ✅ 118 testes (36.46% cobertura total, >70% em módulos críticos)
  • ✅ Documentação completa - ADRs, C4 diagrams, security docs
  • ✅ SOLID principles - Clean architecture
  • ✅ Zero breaking changes - Código legado continua funcionando

📋 Pré-requisitos

  • Rust 1.70 ou superior
  • Credenciais OAuth2 do Google Cloud Console

🚀 Instalação

Via Cargo

cargo install rustdrivesync

Build manual

git clone https://github.com/usuario/rustdrivesync
cd rustdrivesync
cargo build --release

O binário estará em target/release/rustdrivesync

🔧 Configuração Inicial

1. Obter Credenciais do Google Cloud Console

Para usar o RustDriveSync, você precisa de credenciais OAuth 2.0 do Google. Siga este guia passo a passo:

Passo 1: Criar um Projeto no Google Cloud

  1. Acesse o Google Cloud Console

  2. Criar Novo Projeto

    • Clique no seletor de projeto no topo (ao lado de "Google Cloud")
    • Clique em "New Project" (Novo Projeto)
    • Digite um nome: ex: "RustDriveSync" ou "My Drive Backup"
    • Clique em "Create" (Criar)
    • Aguarde alguns segundos até o projeto ser criado
    • Selecione o projeto criado no seletor de projetos

Passo 2: Habilitar a Google Drive API

  1. Acessar a API Library

  2. Buscar e Habilitar

    • Na barra de busca, digite: Google Drive API
    • Clique em "Google Drive API" nos resultados
    • Clique no botão azul "Enable" (Habilitar)
    • Aguarde a ativação (geralmente instantânea)

Passo 3: Configurar Tela de Consentimento OAuth

⚠️ Obrigatório antes de criar credenciais

  1. Acessar OAuth Consent Screen

  2. Configurar Tipo de Usuário

    • Selecione "External" (para uso pessoal)
    • Clique em "Create" (Criar)

  3. Preencher Informações Obrigatórias

    • App name: "RustDriveSync" (ou seu nome preferido)
    • User support email: Seu email
    • Developer contact email: Seu email
    • Clique em "Save and Continue" (Salvar e Continuar)

  4. Escopos (Scopes)

    • Clique em "Add or Remove Scopes"
    • Busque e selecione: https://www.googleapis.com/auth/drive.file
    • Clique em "Update" e depois "Save and Continue"

  5. Test Users (Usuários de Teste)

    • Clique em "Add Users"
    • Adicione seu email (o que você usará para sincronizar)
    • Clique em "Add" e depois "Save and Continue"

  6. Revisar e Confirmar

    • Clique em "Back to Dashboard"

Passo 4: Criar Credenciais OAuth 2.0

  1. Acessar Credentials

  2. Criar Nova Credencial

    • Clique no botão "+ Create Credentials" no topo
    • Selecione "OAuth client ID"

  3. Configurar Tipo de Aplicação

    • Application type: Selecione "Desktop app"
    • Name: "RustDriveSync CLI" (ou qualquer nome)
    • Clique em "Create"

  4. Baixar Credenciais

    • Uma janela popup aparecerá com "OAuth client created"
    • Clique em "Download JSON" (ícone de download ⬇️)
    • O arquivo será baixado como client_secret_XXXXX.json
    • Renomeie este arquivo para credentials.json
    • Mova para uma pasta segura (ex: ~/.config/rustdrivesync/)

Passo 5: Proteger Suas Credenciais

# Linux/macOS
mkdir -p ~/.config/rustdrivesync
mv ~/Downloads/client_secret_*.json ~/.config/rustdrivesync/credentials.json
chmod 600 ~/.config/rustdrivesync/credentials.json

# Windows (PowerShell)
New-Item -Path "$env:APPDATA\rustdrivesync" -ItemType Directory -Force
Move-Item "$env:USERPROFILE\Downloads\client_secret_*.json" "$env:APPDATA\rustdrivesync\credentials.json"

✅ Pronto! Você agora tem o arquivo credentials.json necessário.

⚠️ Troubleshooting

Erro: "Access blocked: This app's request is invalid"

  • Certifique-se de configurar a OAuth Consent Screen (Passo 3)
  • Adicione seu email como Test User

Erro: "The OAuth client was not found"

  • Verifique se criou credenciais do tipo "Desktop app"
  • Não use "Web application" ou "Service account"

Arquivo credentials.json não baixa

  • Vá em Credentials → Clique no nome da credencial criada
  • Clique no ícone de download (⬇️) no lado direito

2. Criar Configuração

rustdrivesync config --init

Isso criará um arquivo config.example.toml. Copie-o para config.toml e edite:

cp config.example.toml config.toml
vim config.toml

Configure pelo menos:

  • source.path: pasta local a sincronizar
  • google_drive.credentials_file: caminho para credentials.json
  • google_drive.target_folder_id ou target_folder_name

3. Autenticar

rustdrivesync auth

Isso abrirá seu navegador para autorizar o aplicativo.

📖 Uso

Sincronização Única

rustdrivesync sync --once

Monitoramento Contínuo

rustdrivesync sync --watch

Simular (Dry Run)

rustdrivesync sync --dry-run

Verificar Status

rustdrivesync status

Listar Arquivos

# Arquivos pendentes
rustdrivesync list

# Arquivos no Google Drive
rustdrivesync list --remote

# Diferenças local vs remoto
rustdrivesync list --diff

📂 Preservação de Estrutura de Pastas

Por padrão, o RustDriveSync preserva a estrutura de diretórios local no Google Drive.

Comportamento

Com preserve_folder_structure = true (padrão):

LOCAL                           GOOGLE DRIVE
/home/user/Documentos/          RustDriveSync/
├── projeto/                    ├── projeto/
│   ├── arquivo1.txt       →    │   ├── arquivo1.txt
│   └── src/                    │   └── src/
│       └── main.rs        →    │       └── main.rs
└── fotos/                      └── fotos/
    └── foto.jpg           →        └── foto.jpg

Com preserve_folder_structure = false (modo legado):

LOCAL                           GOOGLE DRIVE
/home/user/Documentos/          RustDriveSync/
├── projeto/                    ├── arquivo1.txt
│   ├── arquivo1.txt       →    ├── main.rs
│   └── src/                    └── foto.jpg
│       └── main.rs        →
└── fotos/
    └── foto.jpg           →

Configuração

No arquivo config.toml:

[sync]
preserve_folder_structure = true  # Padrão: true

Performance

  • Cache inteligente: Pastas criadas são armazenadas em cache para evitar chamadas redundantes à API
  • Criação recursiva: Toda a hierarquia é criada automaticamente quando necessário
  • Thread-safe: Cache compartilhado com segurança entre uploads paralelos

🗄️ Backups Grandes (SQL, Vídeos, etc.)

O RustDriveSync foi projetado para lidar com arquivos muito grandes (até 5 TB):

Características para Arquivos Grandes:

  • ✅ Streaming Upload: Memória constante (~256 KB) independente do tamanho
  • ✅ Resumable Upload: Retoma de onde parou se a conexão cair
  • ✅ MD5 Streaming: Calcula hash sem carregar arquivo inteiro na memória
  • ✅ Chunks configuráveis: Otimize para seu cenário (5-64 MB)
  • ✅ Retry robusto: Até 7 tentativas com backoff exponencial

Performance Esperada (Arquivo de 7 GB):

  • Cálculo MD5: ~30 segundos
  • Upload (100 Mbps): ~11-14 minutos
  • Memória usada: 256 KB fixo
  • Limite diário: 750 GB (Google Drive)

Configuração Rápida:

[sync]
max_file_size_mb = 10240  # 10 GB
chunk_size_mb = 32
max_concurrent_uploads = 2

Veja config.large-backups.toml para configuração completa e detalhada.

📚 Documentação

Para Usuários

  • Guia de Uso Completo - Tutorial passo a passo em Português
    • Instalação e configuração inicial
    • Comandos básicos e avançados
    • Exemplos práticos de uso
    • Solução de problemas comuns
    • Dicas de segurança

Para Desenvolvedores

API Documentation

# Gerar documentação Rust
cargo doc --open

⚙️ Configuração

Perfis de Configuração

O RustDriveSync pode ser configurado para diferentes cenários:

Perfil Tamanho dos Arquivos max_file_size_mb chunk_size_mb max_concurrent
📄 Documentos < 100 MB 100 5 4-8
💾 Backups Médios 100 MB - 1 GB 1024 16 2-4
🗄️ Backups SQL Grandes 6-8 GB 10240 32 1-2
🎥 Vídeos > 10 GB 50000 64 1

Arquivos de exemplo:

  • config.example.toml - Configuração padrão para backups grandes
  • config.large-backups.toml - Configuração otimizada para backups SQL (6-8 GB)

Exemplo de config.toml (Backups Grandes):

[general]
log_level = "info"
log_file = "./logs/rustdrivesync.log"  # Monitorar progresso

[source]
path = "/var/backups/database"  # Pasta de backups
recursive = true
ignore_hidden = false
ignore_patterns = ["*.tmp", "*.partial"]

[google_drive]
credentials_file = "./credentials.json"
token_file = "./token.json"
target_folder_id = "1ABC123xyz"  # Ou use target_folder_name = "Backups-SQL"

[sync]
mode = "once"  # Usar com cron/scheduler
conflict_resolution = "overwrite"

# CONFIGURAÇÃO PARA ARQUIVOS GRANDES (6-8 GB)
max_file_size_mb = 10240  # 10 GB (crítico!)
chunk_size_mb = 32         # Chunks maiores = mais eficiente
max_concurrent_uploads = 2 # Evita saturar conexão

verify_upload = true
preserve_folder_structure = true

[retry]
max_attempts = 5          # Mais tentativas para arquivos grandes
initial_delay_seconds = 2
max_delay_seconds = 120   # 2 minutos de delay máximo

Veja config.example.toml para todas as opções disponíveis.

🏗️ Arquitetura

┌─────────────────────────────────────────────────┐
│                  RustDriveSync                  │
├─────────────────────────────────────────────────┤
│                                                 │
│  CLI (clap) → Config → Core Engine              │
│                         │                       │
│                         ├─ File Scanner         │
│                         ├─ Sync Engine          │
│                         └─ State Manager        │
│                         │                       │
│                         ▼                       │
│               Google Drive Client               │
│               (OAuth2 + Upload)                 │
│                                                 │
└─────────────────────────────────────────────────┘

🧪 Desenvolvimento

Build

cargo build

Testes

cargo test

Linting

cargo clippy

Formatação

cargo fmt

📝 Roadmap

✅ V1.0 - Production Ready (CONCLUÍDO)

Fundação:

  • Estrutura base e CLI ✅
  • Sistema de configuração ✅
  • Integração com Google Drive ✅
  • Sync engine completo ✅
  • File watcher (modo watch) ✅
  • Streaming de uploads ✅

Qualidade e Performance:

  • Dependency Injection com traits ✅
  • Rate limiting automático (800 req/100s) ✅
  • Retry com exponential backoff ✅
  • Uploads paralelos (5-10x speedup) ✅
  • 113 testes (>70% cobertura em módulos críticos) ✅
  • Documentação completa (ADRs, C4, Security) ✅

🚀 Próximos Passos

V1.1 (Q1 2026) - Melhorias de Segurança e Observabilidade:

  • OS Keychain integration (macOS Keychain, Windows Credential Manager, Linux Secret Service)
  • Jitter em retry para prevenir thundering herd
  • Structured logging (JSON format)
  • Prometheus metrics endpoint
  • E2E tests com Docker

V1.2 (Q2 2026) - Múltiplos Backends:

  • Backend S3 (AWS S3, MinIO, Wasabi)
  • Backend Dropbox
  • SQLite state (substituir JSON)
  • Progress bar melhorado (multi-file)
  • Cobertura de testes >50%

V2.0 (Q3-Q4 2026) - Sincronização Avançada:

  • Sincronização bidirecional (Drive → Local)
  • Resolução automática de conflitos
  • End-to-end encryption opcional
  • Web dashboard (status, métricas, logs)
  • Multi-user support

V3.0 (2027) - Enterprise Features:

  • Webhooks para notificações
  • API REST para integração
  • Suporte a múltiplos clouds simultâneos
  • Versionamento de arquivos
  • Rollback de mudanças

📋 Veja ROADMAP.md para detalhes completos sobre features planejadas, sprints, e debt técnica. 📄 Veja CHANGELOG.md para histórico detalhado de mudanças.

🤝 Contribuindo

Contribuições são bem-vindas! Por favor:

  1. Fork o projeto
  2. Crie uma branch para sua feature (git checkout -b feature/AmazingFeature)
  3. Commit suas mudanças (git commit -m 'Add some AmazingFeature')
  4. Push para a branch (git push origin feature/AmazingFeature)
  5. Abra um Pull Request

📄 Licença

Este projeto está licenciado sob a Licença MIT - veja o arquivo LICENSE para detalhes.

🔗 Links Úteis

🙏 Agradecimentos

  • Comunidade Rust
  • Mantenedores das crates utilizadas (clap, tokio, yup-oauth2, etc.)
  • Contribuidores do projeto

Desenvolvido com ❤️ em Rust

About

Sincronização unidirecional de arquivos com Google Drive - CLI desenvolvida em Rust com arquitetura limpa, rate limiting, retry automático e uploads paralelos

Topics

rust cli sync oauth2 backup async google-drive rate-limiting clean-architecture tokio

Resources

Readme

License

MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 2

v1.1.1 - Otimizações para Backups Grandes Latest
Jan 7, 2026
+ 1 release

Packages

No packages published

Contributors 2

  •  
  •  

Languages