Fecha os desvios do padrao: frescura consultavel, cancelamento cooperativo e ADR 0005

[johnenderson]

Fecha os tres desvios conscientes que o ADR 0004 registrou contra o padrao Asynchronous Request-Reply: dois com codigo, um com ADR proprio.

A lib nao esta publicada, entao a quebra na SPI entra direto.

Desvio 2 — o gate deixou de ser garantia

Como a lib nao serve dados, o cliente le a base do consumidor e nada o impede de ler antes de a carga terminar. "So leia quando estiver quente" virou conselho.

A SPI JobFreshness deixa o endpoint de dominio declarar de quando sao os dados:

@GetMapping("/contas/aptas")
ResponseEntity<ContasResponse> aptas() {
    var contas = repository.buscarAptas();          // SQL de dominio, otimizado
    return ResponseEntity.ok(new ContasResponse(
            contas,
            freshness.lastRefreshedAt("contas").orElse(null),   // "dados de"
            freshness.isFresh("contas")));                      // dentro da janela?
}

• lastRefreshedAt(type): quando a ultima carga concluiu — a idade real dos dados. Vazio se nenhuma concluiu; carga que falhou nao conta como dado quente.
• isFresh(type): se essa conclusao esta dentro da janela configurada. Sempre false sem janela, pela mesma razao que toda submissao dispara carga nesse caso — prometer frescura ali seria mentir.

O desvio continua existindo (ler dado morno segue possivel), mas deixa de ser silencioso.

Desvio 3 — cancelar nao interrompe a rotina

Agora e cooperativo: JobContext.isCancelled() permite a rotina parar num ponto que ela escolhe.

Nao interrompemos a thread de proposito. Abortar no meio de um lote deixaria a base do consumidor parcialmente atualizada, sem ninguem para consertar — so a rotina sabe onde e seguro parar.

public void handle(JobContext ctx) {
    for (var lote : contas.emLotes(500)) {
        if (ctx.isCancelled()) {
            return;                  // para num ponto consistente
        }
        contas.reavaliar(lote);
    }
}

• Quebra de contrato: JobHandler.handle() passa a ser handle(JobContext ctx).
• Cada chamada le o storage — perguntar entre lotes, nao a cada item.
• Rotinas que ja chamam progress periodicamente nao precisam disto: o false devolvido por progress carrega a mesma informacao, sem leitura extra.
• Parar nao muda estado: o job permanece CANCELLED, e o complete que a lib tenta em seguida e recusado pelo UPDATE condicional. Nao existe "descancelar".

Desvio 1 — offload para uma fila (ADR 0005, nao implementado)

docs/adr/0005-dispatch-por-fila-na-propria-tabela.md desenha a alternativa: a propria tabela async_jobs como fila, com FOR UPDATE SKIP LOCKED, invertendo o dispatch de push para pull.

O ADR registra o ganho (distribuicao real entre instancias; queda de instancia deixa de depender de redispatch-after), o custo (latencia de um ciclo de poll, carga constante no banco, mais uma peca viva) e o criterio de quando implementar.

Nao implementado agora porque o ganho e balanceamento de fila, e para uma rotina de reaquecimento com single-flight ligado ha um job ativo por escopo — nao existe fila a balancear. As alternativas descartadas (broker dedicado, LISTEN/NOTIFY, advisory locks) estao registradas com o motivo.

No-op silencioso encontrado no caminho

freshness.enabled=true sem coalesce-in-flight=true nao fazia nada: a janela localiza a ultima carga concluida pela coalescing_key, e essa coluna so e gravada quando o coalescing esta ligado. A configuracao pedia para poupar carga e nada acontecia, sem aviso.

Agora falha o startup com a explicacao. Nao e acidental que os dois andem juntos — ambos falam do mesmo escopo: coalescing cobre carga em andamento, frescor cobre carga ja concluida.

Cobertura

AsyncJobProcessorAdapterOut nao tinha teste de unidade direto; ganhou um: start recusado, type desconhecido, excecao da rotina, fire-and-forget nao completado e os quatro casos de isCancelled. Mais o E2E que cancela um job com a rotina rodando e verifica que ela ve o cancelamento, para, e o estado terminal permanece.

./mvnw clean test
Tests run: 143, Failures: 0, Errors: 0, Skipped: 0

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud