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": null, "archive_post_path": null,
      "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#

Descontinuado em 2026-04-28 com a migração para whatsmeow-claude-update. O novo workflow usa git worktrees em vez de archives .tar.gz, entao rollback automático para uma execução histórica não e simetrico ao script legado. O endpoint sempre responde 410 Gone com error_code=ROLLBACK_DEPRECATED e a receita de rollback manual na mensagem.

Auth: Superadmin

Resposta 410 (ROLLBACK_DEPRECATED): rollback automático foi removido. Para rollback manual: (1) binario do worker via bash scripts/deploy-worker.sh --rollback; (2) pin do submodule via git revert <bump-commit> em main + push + deploy. Ver .claude/rules/whatsmeow-claude-update.md seção "Recovery — failed_deploy".

Erros:

  • 400 BAD_REQUEST — id inválido
  • 404 NOT_FOUND — target run não existe

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#

  • Workspace isolado: /usr/workspace/biazap-update/<TS>/biazap (git worktree)
  • Logs do orquestrador + agente: /usr/workspace/biazap-update/<TS>/logs/ (claude.jsonl, claude.summary.txt, promote.log, deploy-worker.log)
  • Workspaces antigos: limpeza manual (sugerido >14 dias)
  • Retencao de rows em whatsmeow_sync_runs: permanente no momento.