Os afterChange/afterDelete de activity e googleCalendarSync rodavam a reconciliacao completa dentro da transacao do save, segurando row lock + pool por todo o I/O do Google (15s por hop, N RTTs -> 45-75s). Corrige com deadline proprio do hook (GOOGLE_CALENDAR_SYNC_HOOK_TIMEOUT_MS=5s) via AbortSignal.timeout combinado com per-hop 15s no cliente (AbortSignal.any) — manual/webhook mantem 15s sem transacao como fallback confiavel. Fail-closed preservado (abort vira paused). Pin unit hook < per-hop + int hook <=7s com fetch lento.
22 KiB
Impl: C114-LOCK — hooks do sync do Google Calendar seguram a row lock por I/O de rede (mesmo anti-padrão do S11)
Status: rascunho Atualizado em: 2026-08-24 Issue: #870 Intenção: body da Issue #870 (spec expandida — sem plano de intenção linkado; derivado de #762 S11-FOLLOWUP) Appetite restante: herdado — P2, correção cirúrgica (sem novas collections/migrations), similar ao S11-FOLLOWUP
Leitura da intenção
- Outcome: dissociar a janela de
row lock+pool connectiondaactivity/googleCalendarSync— hoje segurada por todo o I/O do Google — da duração do sync: no caminho dos hooks (afterChange/afterDelete), a janela cai deN × 15s(potencial dezenas de segundos:token → listEvents → N×insert/update/delete → watchEvents → stopChannel, cada um comREQUEST_TIMEOUT_MS=15semsrc/utilities/googleCalendarClient.ts:27) para≤5–8s, com o aceite do S11 intacto. - O que NÃO negociar (lockdowns):
- Fail-closed/LGPD intocado; produção no homeserver (
teqo_1313) nunca tocada por dev/test; migrations já shipadas intocadas (push:false); contratos públicos intocados (rota manualrunGoogleCalendarSyncNow, webhookPOST /campanha/agenda/google-webhook/, pill/dialog da agenda). - Aceite herdado do S11: hook aguardado dentro da transação do save para que o reload mostre o status novo (
synced/paused) e ospersistsdo próprio sync nãodeadlockempor usarem a mesmareq.transactionID. Contactcomo pessoa canônica,mutationKind='googleCalendarSync'como anti-reentrada, guards purosshouldSyncActivityOperation/shouldSyncConfigChangepreservados.
- Fail-closed/LGPD intocado; produção no homeserver (
- O que reavaliar (hipóteses):
- Que
INSTAGRAM_SYNC_HOOK_TIMEOUT_MS=5sresolve Google como resolve Instagram — verificado que não: Instagram é 1 fetch (10s → 5scorta 50% e ainda completa em rede boa); Google são múltiplos round-trips sequenciais (ensureGoogleCalendarPushChannel+runSyncPasscomlistEvents+ Nwrites+watch/stop), cada um comAbortSignal.timeout(15s)próprio —5saborta quase sempre no primeiro hop, tornando o caminho do hookbest-efforte empurrando o caminho confiável paramanual/webhook(já sem lock). - Que
onPayloadTransactionCommit/queueMicrotaskdesacoplam o lock — verificado que não serve para transações internas do Payload (só parawithPayloadTransaction); hook do Payload já está comtransactionIDdodb.update/db.deleteinterno.
- Que
Abordagem recomendada
flowchart LR
A[Save Activity / googleCalendarSync<br/>db.update — transação + row lock] --> B[afterChange / afterDelete aguardado<br/>guard puro + runCampaignCalendarSync<br/>com deadline curto do hook]
B --> C[Sync tenta: token/list/write/watch/stop<br/>cada fetch com timeout 15s mas<br/>deadline global do hook 5-8s]
C -->|ok ou falha mapeada| D[recordSyncState via req.transactionID<br/>mesma conexão — sem deadlock]
D --> E[commitTransaction<br/>libera lock + pool]
E --> F[Retry manual / webhook<br/>sem req transacional — deadline cheio 15s — caminho confiável]
style B fill:#fee,stroke:#c00
style F fill:#efe,stroke:#090
Opções consideradas: A | B | C
- A — deadline específico do hook (S11 puro, adaptado para Google): novo
GOOGLE_CALENDAR_SYNC_HOOK_TIMEOUT_MS = 5_000(ou8_000, ver Decisão D1) emsrc/utilities/googleCalendarSync.ts(ao lado deREQUEST_TIMEOUT_MS=15_000), usado só poractivityGoogleCalendarSyncHook/googleCalendarSyncConfigHookviaAbortSignalinjetado no engine/cliente. Botão manual e webhook mantêm o deadline cheio (sem transação aberta). Persists continuamreq-bound (mesma conexão), sem deadlock. - B — pós-commit fire-and-forget (desacoplamento total): no hook, se
req.transactionIDexiste, agendarunCampaignCalendarSyncviaqueueMicrotask/setTimeoutcompayloaddesacoplado (ou tentariaonPayloadTransactionCommit), comsignalcheio. Lock segura zero I/O;revalidateTag/reloaddesacoplados. - C — fetch-antes-do-persist / mover I/O para
beforeChange/beforeValidate: reestruturar para buscar no Google antes de adquirir o lock.
Recomendação: A — porque cabe no appetite P2 e é a única que encurta a janela sem reescrever o aceite nem exigir infra nova.
- Cirúrgica: 1 constante + 1 parâmetro
signal/timeoutMsno engine/cliente + 2 call sites nos hooks. Sem migration, sem collection, semrevalidateTagnovo, semcron/outbox. Mesmo shape do S11-FOLLOWUP (SocialFeedSettings.ts:35-47+instagramSync.ts:34). - Preserva o aceite caro de reverter: hook continua aguardado e
tx-bound— reload mostralastSyncedAt/lastError/pausedcom as credenciais/calendário novos;recordSyncState/applyGoogleReverseActivityPatchviareqnão abrem segunda conexão que bloquearia no lock (padrão já validado no Instagram comresolvePersistDatabase/getPostgresTransactionDatabase). - Caminho confiável já existe sem lock:
src/app/(campaign)/campanha/actions/googleCalendarSync.ts:61(runGoogleCalendarSyncNow,reason:'manual') e webhook — ambos chamamrunCampaignCalendarSync(payload, {reason})semreqtransacional, então seu I/O de15s×Nnunca segura lock. O hook vira oportunístico de baixa latência; falha por timeout é mapeada parapaused(lastErrorfatiado em 500) e recuperável no botão — mesmofail-closeddo Instagram (describeInstagramError). - Para Google multi-RTT,
5sde fato aborta mais que Instagram, mas isso é o trade-off correto em P2: seguraractivity/googleCalendarSyncpor45–75sbloqueia writes concorrentes da campanha e esgota o pool Drizzle (conexão presa porawaitde rede) — pior que abortar cedo e deixar o manual completar.Bseria o ideal final, mas não cabe (ver Rejeitadas).
Alternativas rejeitadas:
- B — pós-commit: rejeitada como entrega P2. Razão verificada:
src/utilities/payloadTransaction.ts:37-48(onPayloadTransactionCommit) só descarrega para transações abertas porwithPayloadTransaction(payload.db.beginTransactionpróprio); transações internas do Payload (db.update/deleteque disparamafterChange) nunca chamamrunAfterCommitCallbacks—onPayloadTransactionCommitseriano-op(comentário38-45e uso emcreateCampaignNotification.ts:32-36que explicitamente checatransactionID ? onPayloadTransactionCommit : queueMicrotaske documentaqueueMicrotaskantes decommitTransactionparawithPayloadTransaction).queueMicrotaskincondicional no hook dispara antes docommit(microtasks flush antes doawait commitTransaction), lendoloadGoogleCalendarSyncConfig/loadSyncActivitiesainda sem odoccommitado e potencialmente vendosnapshotstale; se adiar parasetTimeout(0)perde oawaited reload— oStatusPanelda agenda leria o estado antigo até o sync em background chegar, exigindo marcadorsincronizando...+ polling + rework de e2e, desproporcional para trigger raro (saves com campo espelhado mudado, não todotask toggle). Gatilho futuro: se produto reportar que status antigo após save é problema real, reabrir como Issue própria comoutbox/tabela de jobs oupg LISTEN/NOTIFY— fora de P2. - C — fetch-antes-do-persist: infeasível. Verificado no source do Payload (
node_modules/payload/dist/collections/operations/update.jseglobals/operations/update.js, mesma ordem citada no S11-FOLLOWUP): a ordem édb.update(adquirerow lock) →afterRead→afterChange(aguardados) →commitTransaction. A transação/lock já estão abertos quando o hook roda (beforeChange/beforeValidatetambém rodam dentro da mesma transação). Mover o fetch parabeforeChangenão encurta a janela. - D (variação implícita) — reduzir
REQUEST_TIMEOUT_MSglobal para 5s: rejeitada — encolheria a folga do botão manual/webhook (que hoje precisam de15spor hop paratoken→list→watchsequenciais + retries401→re-mintemgoogleCalendarClient.ts:149) sem benefício de lock (esses caminhos não seguram lock). O S11 já rejeitouEpelo mesmo motivo. - E (variação) — manter
15sno hook e só trocarpayload.updatepor SQL cru desacoplado: não resolve — o lock é segurado peloawaitde rede, não peloUPDATEde estado; SQL cru viagetPostgresTransactionDatabase(postgresTransactionLocks.ts:19) ainda usa a mesma conexão transacional e não libera o lock antes docommit.
Decisões de engenharia (forma obrigatória)
D1 — Janela de lock do hook: Opções: A|B|C / Recomendação: A — deadline curto específico do hook
- Opções: A
GOOGLE_CALENDAR_SYNC_HOOK_TIMEOUT_MS = 5_000(paridade S11) | B8_000| C manter15_000(status quo). - Recomendação: A (5_000) com tolerância para 8_000 se o primeiro int mostrar abort >90% em rede boa — porque
5sjá corta~93%da janela pior-caso (75s→5s) e alinha a semântica dos dois hooks da casa (INSTAGRAM_SYNC_HOOK_TIMEOUT_MS);8sé o teto P2 se o time medir que5snunca completa nemtoken+listemp95prod (Googlep95documentado ~1–2s por hop,5scobre2–3hops sequenciais). A escolha é barata de reverter (1 constante). - Alternativas rejeitadas: C (manter
15s) — mantém o acoplamentorow lock × N×RTTque a Issue denuncia e acopla latência de writes deactivityà saúde do Google; B sem medição éoverfitting— só sobe para8scom evidência dep95, não por default.
D2 — Como o deadline chega ao I/O: Opções: A|B|C / Recomendação: A — AbortSignal injetado no engine/cliente
- Opções: A
runCampaignCalendarSync(payload, {signal, req})→createGoogleCalendarClient(credentials, fetch, signal)combinasignalexterno comAbortSignal.timeout(REQUEST_TIMEOUT_MS)por hop (viaAbortSignal.any/reason) | BtimeoutMsnumérico por hop | Csignalsó nolistEvents. - Recomendação: A —
signalexterno combinado — porque o engine já temclient?injetável (googleCalendarSync.ts:747) e o cliente já usasignalporfetch(googleCalendarClient.ts:108,145); combinar preservaREQUEST_TIMEOUT_MS=15spor hop mas respeita o deadline global do hook (abortawatchEvents/stopChannelse o budget estourou). Reuso profundo, semhelpernovo. - Alternativas rejeitadas: B (timeout numérico) — duplica semântica de
AbortSignale exigeplumbingdesetTimeoutmanual; C (sólist) — deixatoken/watch/stopsegurarem lock após o budget.
D3 — Persist do estado durante o hook: Opções: A|B / Recomendação: A — manter req-bound (mesma conexão)
- Opções: A manter
recordSyncState(payload, req, patch)eapplyGoogleReverseActivityPatch(payload, req, ...)comreq(mesmatransactionID) | B trocar para SQL cru desacoplado (getPostgresTransactionDatabase+sql UPDATE) fora da transação. - Recomendação: A — porque
Aédeadlock-free(mesma conexão não bloqueia no próprio lock) e atômico com o save (statuspaused/syncedcomitta junto);Bexigiriapoolfora da transação que bloquearia no lock atécommit— exatamente o antipadrão que o Instagram corrigiu comresolvePersistDatabase(instagramSync.ts:68-79) ao fazer o oposto (usar a conexão transacional quandoreq.transactionIDexiste). - Alternativas rejeitadas: B — reintroduz o bloqueio que se quer remover e perde atomicidade do
lastSyncedAtcom o save.
Componentes / mudanças
GOOGLE_CALENDAR_SYNC_HOOK_TIMEOUT_MS(src/utilities/googleCalendarSync.ts): nova constante5_000(exportada, com comentário do acoplamentorow lock × I/O— espelho deINSTAGRAM_SYNC_HOOK_TIMEOUT_MSemsrc/utilities/socialFeed/instagramSync.ts:34), ao lado deREQUEST_TIMEOUT_MS. Se mediçãop95justificar,8_000com comentário.CampaignCalendarSyncOptions+createGoogleCalendarClient(src/utilities/googleCalendarSync.ts:746,src/utilities/googleCalendarClient.ts:91): adicionarsignal?: AbortSignalemCampaignCalendarSyncOptionsecreateGoogleCalendarClient(credentials, fetchImpl, hookSignal?);apiFetch/requestAccessTokencombinamhookSignalcomAbortSignal.timeout(REQUEST_TIMEOUT_MS)(ex.:AbortSignal.any([hookSignal, AbortSignal.timeout(REQUEST_TIMEOUT_MS)])quandohookSignalexiste).runSyncPass/ensureGoogleCalendarPushChannelpropagam osignalparaclient.listEvents/watchEvents/stopChannele pararecordSyncState/loadSyncActivitiesviareq(inalterado).activityGoogleCalendarSyncHook+googleCalendarSyncConfigHook(src/utilities/googleCalendarSyncHooks.ts:43-45,65): trocarawait runCampaignCalendarSync(req.payload, {reason, req})porawait runCampaignCalendarSync(req.payload, {reason, req, signal: AbortSignal.timeout(GOOGLE_CALENDAR_SYNC_HOOK_TIMEOUT_MS)})(1 linha por hook + import da constante + ajuste do JSDoc do antipadrão). Mantémtry/catchque nunca joga nowrite pathe o guardmutationKind='googleCalendarSync'(googleCalendarSyncHooks.ts:41).- Migration: sem migration. Access / Consent: sem mudança (guards
shouldSync*puros,access/*intocado). UI: zero mudança (pill/dialog leemreadGoogleCalendarSyncViewderivado). - Depth check — reuso obrigatório:
googleCalendarSync.ts(enginerunSyncPass/ensurePushChannel/recordSyncState),googleCalendarSyncHooks.ts(seam fina mockável —tests/unit/googleCalendarSyncHooks.unit.spec.ts:13),googleCalendarClient.ts(REQUEST_TIMEOUT_MS,AbortSignal,joseJWT),payloadTransaction.tsapenas como referência negativa (não usaronPayloadTransactionCommitparatransactionIDdo Payload),notification/createCampaignNotification.ts:21-38apenas como referência do porquêqueueMicrotaskantes decommitquebra.
Dados → forma (se aplicável)
Não aplicável — sem mudança de schema/coleção. O lastSeenEventIds/pushChannel*/lastError continuam json/text/date em src/collections/GoogleCalendarSync.ts:48-179; Activity.lastMirroredChangeAt (src/collections/Activity.ts:744) continua date e é o relógio da regra de conflito (googleEditIsNewer).
Fases verificáveis
-
Tracer / engine+hooks —
GOOGLE_CALENDAR_SYNC_HOOK_TIMEOUT_MS+signalplumbing- Adicionar
GOOGLE_CALENDAR_SYNC_HOOK_TIMEOUT_MS = 5_000emgoogleCalendarSync.ts(comentário do acoplamentorow lock × N×RTT, citandoREQUEST_TIMEOUT_MSeS11-FOLLOWUP #762). - Adicionar
signal?: AbortSignalemCampaignCalendarSyncOptionsecreateGoogleCalendarClient(..., hookSignal?); combinar comAbortSignal.timeout(REQUEST_TIMEOUT_MS)emrequestAccessToken/apiFetch. - Trocar os dois call sites em
googleCalendarSyncHooks.ts:44,65parasignal: AbortSignal.timeout(GOOGLE_CALENDAR_SYNC_HOOK_TIMEOUT_MS).runGoogleCalendarSyncNow(actions/googleCalendarSync.ts:66) e webhook seguem semsignal(deadline cheio). - Verificação:
pnpm tsc --noEmit,pnpm test:unit(googleCalendarSyncHooks.unit.spec.tscontinua verde —vi.mockna seam do engine).
- Adicionar
-
Testes de domínio — pin do invariante + int do hook
- Unit (
tests/unit/googleCalendarSync.unit.spec.tsougoogleCalendarSyncHooks.unit.spec.ts):expect(GOOGLE_CALENDAR_SYNC_HOOK_TIMEOUT_MS).toBe(5_000)eexpect(GOOGLE_CALENDAR_SYNC_HOOK_TIMEOUT_MS).toBeLessThan(15_000)(ouREQUEST_TIMEOUT_MS), pinandohook < botãocomo eminstagramSync.unit.spec.ts. Teste na seam de constantes — 1 arquivo, sem helper novo. - Int (
tests/int/googleCalendarSync.int.spec.ts): um caso comfetchstubado que dorme>6snotokenelistEvents, disparapayload.create({collection:'activity', ...})com campo espelhado mudado, e asserta que ocreateresolve em≤7s(não segura15s×N) e quegoogleCalendarSync.lastErrorfoi persistido comoAbortError/paused(status derivadopaused), provando que odeadlinedo hook abortou o I/O mas não quebrou o save. - Gatilho: se
5sse mostrar agressivo demais em prod (p95real >5s paratoken+list), um follow-up de 1 linha sobe para8s— ainda~90%de corte.
- Unit (
-
Gates —
pnpm gate:fast; push via pnpm pushpnpm lint && pnpm format:check && pnpm tsc --noEmit && pnpm knip && pnpm madge --circular+pnpm test:unit+pnpm test:int+pnpm build(build aplica migrations, mas não há migration nova).pnpm changelog:buildnão é manual — registrar UMA entrada curta emdocs/changelog/2026-08-24-c114-lock.md(appetite,GOOGLE_CALENDAR_SYNC_HOOK_TIMEOUT_MS,signalplumbing, sem migration). Entrega viapnpm push(CIchecksroda unit/int/e2e curado; PR auto-merge viaAUTOMERGE_PAT).
Rabbit holes / Não escopo
- Mitigação do candidato B (
sincronizando...+ polling +revalidatepós-commit): fora de escopo desta entrega P2. Gatilho: produto reportar que status antigo após save é problema real → Issue própria comoutbox/tabela de jobs. onPayloadTransactionCommitinútil paratransactionIDdo Payload: nomeado e rejeitado acima — não tentaronPayloadTransactionCommit(req.transactionID, ...)dentro deafterChangedo Payload; sówithPayloadTransactiondescarrega oMap(payloadTransaction.ts:54-65).queueMicrotasktambém é armadilha (flush antes decommitparawithPayloadTransaction).- Re-entrada / concorrência /
reversePatch:mutationKind='googleCalendarSync'(googleCalendarSync.ts:391,392,878) já quebra o loop (activityGoogleCalendarSyncHook.ts:41);runSyncPassconverge por igualdade de conteúdo (googleEventContentEquals/googleEditableContentEquals) elastSeenEventIdscomremovedEventIds— não reabrir mutex/lock novo nesta Issue. revalidateTagacoplado: ao contrário do S11 (SocialFeedSettings.ts:45+REVALIDATE_SOCIAL_FEED_TAG), os hooks do Google não fazemrevalidateTag; não há ISR da home acoplado aqui — não moverrevalidatepara pós-commit.- Render path sem deadline /
watchEventsbest-effort:ensureGoogleCalendarPushChanneljá ébest-efforte nunca pausa o espelho (pushChannelErrorseparado delastError); não mexer nochannel ensurealém de respeitar osignaldo hook. Cron de renovação seguePUSH_CHANNEL_RENEW_LEAD_MS=48h. - Reduzir
REQUEST_TIMEOUT_MSglobal ou mover fetch parabeforeChange: não escopo (rejeitadas acima). - Múltiplas escritas de
recordSyncState+reversePatchconflitando: fora de escopo —recordSyncStatejá éoverrideAccess:trueereq-bound; conflito é benigno (próximopassreconverge). - Flake pré-existente
admin.e2e.spec.ts:44(picker Instagram): já descartado no S11-FOLLOWUP, sem relação com este lock.
Riscos e mitigação
- Google
p95>5s → hook aborta sempre, sync só via botão/webhook: mitigado —pausedé o estado esperado paraAbortError(recordSyncStatecomlastErrorAt/lastError), botãorunGoogleCalendarSyncNowmantém15spor hop e completa; agenda mostrapausedaté retry manual; se métrica prod mostrar abort >90% em rede boa, follow-up de 1 linha sobe para8s(ainda corta~89%da janela). - Abort no meio de
runSyncPassdeixalastSeenEventIdsdesatualizado: benigno —recordSyncStatedelastSeenEventIdssó ocorre empassbem-sucedido (googleCalendarSync.ts:587-592); falha não persisteids, próximopass(manual/webhook ou próximo save relevante) re-lista e reconverge semcancelespúrio (regralastSeenIds.has(eventId)em569). - Abort durante
watchEvents/stopChannel:ensureGoogleCalendarPushChanneljá mapeia falha parapushChannelErrorsem pausar o espelho (googleCalendarSync.ts:734-736) —hookcomsignalabortado cai no mesmocatch. - Sem deadlock novo:
signalabortado não abre segunda conexão;recordSyncStatecomrequsa a mesmadb.sessions[transactionID].dbquandoreq.transactionIDexiste (mesmo padrãoresolvePersistDatabasedo Instagram que evitapoolbloquear no lock). - Sem regressão de acesso/consent/migration: invariantes do repo intocados;
pnpm migrate:createnão roda.
Aceite de engenharia
- Aceite de produto ainda coberto (janela de lock do save com campo espelhado cai de
N×15spara≤5s(teto8s); reload mostralastSyncedAt/pausedfinal quando o budget permite;fail-closedpreservado;manual/webhooksem lock seguem caminho confiável) - Invariantes
AGENTS.md/engineering-standards.mdcpreservados (sem migration, sempush:true, semS3/DATABASE_URLremoto, semContactparalelo, semConsentparalelo, sem twin de módulo — editagoogleCalendarSync*dono do concern) - Testes de domínio previstos (unit pin
GOOGLE_CALENDAR_SYNC_HOOK_TIMEOUT_MS < REQUEST_TIMEOUT_MS+ int dehook ≤7scomfetchlento; e2e existentegoogleCalendarSyncint + agenda pill seguem cobrindo o aceite)
Self-score decision-quality (gate ≥4)
5/5
- Decisões caras têm rejeitadas? Sim —
B(onPayloadTransactionCommit/queueMicrotaskpós-commit) eC(fetch-antes-do-persist) com razões verificadas no source do Payload (update.js) e empayloadTransaction.ts:37-48/createCampaignNotification.ts:21-38;D(reduzirREQUEST_TIMEOUT_MSglobal) também rejeitada. - Cabe no appetite? Sim — P2 cirúrgico: 1 constante +
signalplumbing no engine/cliente + 2 linhas nos hooks; sem migration/collection/UI/revalidate. - Rabbit holes nomeados? Sim —
onPayloadTransactionCommitinútil,queueMicrotaskantes decommit, re-entradamutationKind, concorrênciareversePatch/lastSeenEventIds,revalidateTagacoplado (S11 vs C114),watchEventsbest-effort. - Depth check reusa? Sim — reusa
googleCalendarSync.ts(runCampaignCalendarSync/runSyncPass/ensurePushChannel/recordSyncState),googleCalendarClient.ts(REQUEST_TIMEOUT_MS/AbortSignal/jose),googleCalendarSyncHooks.ts(seam fina), e referenciapayloadTransaction.ts/notificationapenas como não-usar paratransactionIDdo Payload. - Intenção preservada? Sim — encurta a janela de
row lock/poolsem reescrever o outcome (hook aguardado,persisttx-bound,fail-closed,manual/webhooksem lock como fallback).