whatsmeow Sync — Atualização Automatizada da Fork (Superadmin)

17.Z whatsmeow Sync — Atualização Automatizada da Fork (Superadmin)#

Job diário (systemd timer biazap-whatsmeow-claude-update.timer, 04:30 UTC) que mantem third_party/whatsmeow/ sincronizada com tulir/whatsmeow main sem perder os patches da nossa fork. Pipeline: workspace isolado em git worktree -> agente Claude Code headless faz merge + audit + build + test + patch pin + smoke isolado -> se smoke green e agente confirma Auto promote: yes, orquestrador faz ff merge em main + push + deploy worker. Caso contrario, branch fica pushed para review humano (status=pending_review).

Detalhes do design: .claude/rules/whatsmeow-claude-update.md.

Endpoint base: /v1/admin/whatsmeow-sync/*. Todos requerem JWT de superadmin. Retorna o envelope padrão de erros (error_code, trace_id).

GET/v1/admin/whatsmeow-sync/runs#

Lista execuções passadas (mais recentes primeiro, padrão 50).

Query: limit (1..200).

Resposta 200:

json 
{
  "data": [
    {
      "id": 7, "trigger": "scheduled", "started_at": "2026-04-21T04:30:00.000Z",
      "finished_at": "2026-04-21T04:34:12.500Z", "duration_ms": 252500,
      "before_sha": "9e93da2...", "after_sha": "5b88861...",
      "upstream_sha": "5b88861...", "tag_name": "biazap-sync-2026-04-21-043000",
      "baked_before": "2.3000.1034566421", "baked_after": "2.3000.1037753511",
      "status": "success", "worker_deployed": true,
      "worker_health_ok": true, "e2e_test_ok": true, "log_monitor_ok": true,
      "push_ok": true, "archive_pre_path": "/usr/workspace/biazap-archives/whatsmeow/2026-04-21-043000-pre.tar.gz",
      "archive_post_path": "/usr/workspace/biazap-archives/whatsmeow/2026-04-21-043000-post.tar.gz",
      "log_path": "/usr/workspace/biazap/data/logs/whatsmeow-sync/2026-04-21-043000.log",
      "created_at": "2026-04-21T04:30:00.100Z"
    }
  ],
  "total": 1, "limit": 50
}

GET/v1/admin/whatsmeow-sync/runs/{id}#

Detalhe de uma execução especifica. Mesmo shape de item em /runs, com campos extra quando aplicavel: failed_phase, failure_reason, conflict_files (array).

404 se id não existe.

GET/v1/admin/whatsmeow-sync/latest#

Última execução (qualquer status). Se nenhuma rodou ainda:

json 
{ "status": "pending_first_run" }

GET/v1/admin/whatsmeow-sync/status#

Resumo p/ o hero card do dashboard — mistura estado live do git com histórico do DB:

json 
{
  "current_baked": "2.3000.1037753511",
  "current_fork_sha": "5b88861abc...",
  "last_run_ok": true,
  "last_run_status": "success",
  "last_run_id": 7,
  "last_success_at": "2026-04-21T04:34:12Z",
  "last_success_tag_name": "biazap-sync-2026-04-21-043000",
  "last_known_upstream_sha": "5b88861abc...",
  "hours_since_last_run": 6,
  "hours_since_last_success": 6,
  "pending_first_run": false,
  "timer_healthy": true,
  "timer_health_message": ""
}

timer_healthy=false se hours_since_last_success > 30 (yellow) ou > 48 (red). Usado pelo card como sinal principal.

POST/v1/admin/whatsmeow-sync/run#

Dispara manualmente. Resposta 202:

json 
{
  "run_id": 8,
  "status": "queued",
  "unit": "biazap-whatsmeow-claude-update-manual-8",
  "poll": "/v1/admin/whatsmeow-sync/runs/8"
}

Rejeita com 409 SYNC_IN_PROGRESS se já existe um run com status=running. Pre-aloca a linha no DB antes de spawn.

POST/v1/admin/whatsmeow-sync/runs/{id}/rollback#

Reverte para o archive preservado de uma execução histórica. Requer que a target run tenha archive_post_path existente no disco.

Resposta 202:

json 
{
  "run_id": 9, "target_id": 7,
  "status": "queued", "unit": "biazap-whatsmeow-claude-update-rollback-9",
  "poll": "/v1/admin/whatsmeow-sync/runs/9"
}

Erros:

  • 404 — target run não existe
  • 400 NO_ARCHIVE — target não gravou archive_post (ex. skipped_up_to_date)
  • 410 ARCHIVE_MISSING — tarball foi removido do disco (retencao 30d)
  • 409 SYNC_IN_PROGRESS — outro run em andamento

Metricas#

  • biazap_whatsmeow_sync_runs_total{status,trigger} — counter
  • biazap_whatsmeow_sync_last_run_ok — gauge 0/1
  • biazap_whatsmeow_sync_last_success_timestamp_seconds — gauge
  • biazap_whatsmeow_sync_days_behind_upstream — gauge
  • biazap_whatsmeow_sync_phase_duration_seconds{phase} — histogram

Arquivos no disco#

  • Logs: /usr/workspace/biazap/data/logs/whatsmeow-sync/YYYY-MM-DD-HHMMSS.log
  • Archives: /usr/workspace/biazap-archives/whatsmeow/YYYY-MM-DD-HHMMSS-{pre,post}.tar.gz
  • Retencao de archives: 30 dias (configuravel via WHATSMEOW_SYNC_ARCHIVE_DAYS)
  • Retencao de rows em whatsmeow_sync_runs: permanente no momento (eventual cleanup via TODO).