Execução Assíncrona

A Execução Assíncrona é o modo de processamento baseado no padrão fire-and-forget (dispare e esqueça). Nesse modelo, a Engine recebe a requisição HTTP, valida as regras de entrada, gera um identificador único de sessão, despacha o fluxo para o barramento de eventos e devolve imediatamente uma resposta de sucesso ao cliente, sem aguardar o processamento das etapas pelos runners.

Ciclo de Vida da Requisição Assíncrona

Diferente do modo síncrono, a execução assíncrona desacopla o tempo de vida da conexão HTTP do tempo necessário para processar o fluxo:

Cliente HTTP                 Engine                      Barramento / Runners           Cache de Sessão
     │                         │                                  │                            │
     │── 1. POST /async/public─►│                                  │                            │
     │                         │── 2. Valida e cria Sessão ──────►│                            │
     │                         │── 3. Publica 1ª Etapa ──────────►│                            │
     │◄── 4. HTTP 200 OK ──────│                                  │                            │
     │    {"sessao": "UUID"}   │                                  │── 5. Processa Etapas ─────►│
     │                         │                                  │   (Processamento em BG)    │
     │                         │                                                               │
     │                         │                                                               │
     │── 6. GET /v1/core/info/idSessao ─────────────────────────────────────────────────────►│
     │◄── 7. Consulta Estado da Sessão (Opcional) ─────────────────────────────────────────────│

1. Recebimento e Validação

A Engine recebe a chamada através de um endpoint assíncrono (ex: /v1/core/async/public/{slugProjeto}/{slugPacote}/{slugFluxo} ou /v1/core/async/internal/{coFluxo}). O pipeline inicial executa a validação de rota, inicializador HTTP, escopo de origem, credenciais de segurança e regras do adaptador de entrada.

2. Validação do Adaptador `ASYNC`

A Engine verifica se a versão do fluxo permite execução assíncrona inspecionando o adaptador do grupo ASYNC. Se o fluxo estiver configurado com ASYNC_OFF, a requisição assíncrona é rejeitada imediatamente.

3. Criação de Sessão e Despacho

A Engine registra a sessão em memória no cache com o identificador único (idSessao), sinalizando a flag async = TRUE, e publica a primeira etapa do fluxo no barramento de eventos.

4. Resposta Imediata ao Cliente

Sem suspender a thread ou criar estruturas de espera em memória (CompletableFuture), a Engine retorna imediatamente ao cliente o código HTTP 200 OK com a confirmação de envio e o ID da sessão gerada:

{
  "sessao": "b3a1f49e-82c2-4808-9b88-123456789abc",
  "mensagem": "Enviado para processamento com sucesso"
}

5. Processamento em Background

Os runners consomem os eventos do barramento, executam suas tarefas atômicas e progridem com as etapas do fluxo de forma totalmente desacoplada da requisição HTTP original.

Consulta de Estado da Sessão (`GET /v1/core/info/{idSessao}`)

Como o cliente não recebe o resultado final do fluxo na resposta da requisição inicial, a Engine disponibiliza um endpoint nativo para inspeção e acompanhamento do estado do processamento:

Rota: GET /v1/core/info/{idSessao}
Funcionamento: O cliente realiza uma chamada consultando o identificador da sessão retornado no momento do acionamento assíncrono.
Retorno: A Engine busca os dados da sessão no cache em memória e devolve o estado atual do processamento, indicando se a sessão está em andamento, concluída ou interrompida por erro, além de disponibilizar os dados acumulados acumulados no histórico de etapas.

Casos de Uso Recomendados

Processamento de Carga Elevada / Longa Duração

Processos de lote (batch), geração de relatórios extensos ou chamadas a APIs legadas de baixa performance que excederiam o tempo limite de timeout HTTP síncrono.

Invocação de Webhooks de Entrada

Recepção de notificações de eventos vindas de plataformas parceiras em que a confirmação de recebimento deve ser entregue em poucos milissegundos.

Disparos do Agendador

Execuções automáticas acionadas por regras temporais em que não há um cliente humano aguardando a resposta em tela.