Visão Geral e Arquitetura de Runners

Os Runners (motores de execução) são microsserviços especializados e atômicos responsáveis pelo processamento individual de cada etapa de um fluxo. Eles estendem uma classe abstrata comum (Runner) que padroniza a recepção de mensagens do barramento, a resolução de parâmetros, o gerenciamento de estado da sessão e o despacho de telemetria.

---

Atributos Comuns de Etapa

Independentemente do tipo de processamento (seja uma chamada HTTP, validação de entrada ou execução de script), qualquer bloco desenhado no Editor Visual possui dois atributos identificadores obrigatórios na definição da etapa (DefinicaoDeEtapa):

• alias: Nome amigável e descritivo atribuído pelo desenvolvedor no Editor Visual. É utilizado para identificação do nó no diagrama e para referenciar o histórico de execução em etapas subsequentes (ex: ${historico.alias_da_etapa.body}).

• motor: Identificador técnico do tipo do runner encarregado de processar aquela etapa. Determina qual consumidor do barramento de eventos responderá pelo nó (ex: DADOS_ENTRADA, SCRIPT_JS, HTTP_CLIENT).

---

O Ciclo de Vida da Classe Abstrata Runner

Todos os runners herdam a infraestrutura de orquestração fornecida pela classe base Runner. Essa abstração assegura que o desenvolvedor do nó foque exclusivamente na implementação do método de negócio atômico (run), enquanto o ciclo de vida da execução ocorre de forma padronizada:

Ciclo de vida da classe Runner

[ Barramento de Eventos (Kafka) ] ──► consumirMensagem()
                                          │
                                          ▼
┌────────────────────────────────────────────────────────────────────────┐
│                          MÉTODO PROCESSAR()                            │
│  1. Inicia contagem e atribui idExecucaoMotor (UUID)                  │
│  2. Buscar Etapa (Recupera definição visual do cache)                  │
│  3. Construir Plano de Execução                                        │
│     - Calcula Índice de Referência e Índice de Substituição           │
│     - Carrega Dados de Sessão necessários do Cache                     │
│     - Efetua Interpolação de Parâmetros no JSON da Etapa               │
└──────────────────────────────────┬─────────────────────────────────────┘
                                   │
                                   ▼
┌────────────────────────────────────────────────────────────────────────┐
│                        MÉTODO ABSTRATO RUN()                           │
│  (Executado pelo Runner Concreto: HTTP, Script, SQL, Validação)         │
└──────────────────────────────────┬─────────────────────────────────────┘
                                   │
                                   ▼
┌────────────────────────────────────────────────────────────────────────┐
│                        FINALIZAÇÃO E DESPACHO                          │
│  1. Avalia retorno ou exceção (InterrupcaoException)                   │
│  2. Marca Dados e Histórico para Commit transacional na Sessão        │
│  3. Calcula o próximo destino (ServicoRoteador)                        │
│  4. Executa Commit e despacha próximo evento no Barramento            │
│  5. Envia métricas assincronamente ao ServicoColetorEstatistica       │
└────────────────────────────────────────────────────────────────────────┘

---

Fases de Processamento de um Runner

1. Resolução do Plano de Execução (construirPlanoDeExecucao)

Antes de executar a lógica do nó, a classe base inspeciona o documento JSON da etapa para otimizar o acesso à memória e interpolar variáveis:

• Índice de Referência: Identifica quais dados da sessão ($entrada, $dados, $historico, $variaveis) precisam ser carregados do cache. O runner pode estender o método atualizarIndiceDeReferencia se necessitar de dados específicos da transação que não estejam explicitados no JSON.

• Índice de Substituição: Mapeia quais marcações no padrão ${...} exigem interpolação de valores.

• Interpolação de Parâmetros: Submete o JSON da etapa ao ServicoSubstituicaoDeParametro, gerando o objeto DefinicaoDeEtapa pronto para consumo.

2. Execução Atômica do Motor (run)

Método abstrato sobrescrito por cada runner concreto. Recebe a solicitação de contexto (ContextoDeExecucao), a definição com os parâmetros já substituídos (DefinicaoDeEtapa) e o estado atual dos dados da sessão (Document dados).

• Devolve um objeto RetornoDeExecucao indicando se a etapa finalizou com sucesso, dados gerados para gravação na sessão, histórico de resposta ou sinal de interrupção.

3. Roteamento e Persistência Transacional (despachar)

• Sucesso: Se o nó for a última etapa do fluxo, a sessão é marcada como finalizada. Caso contrário, o ServicoRoteador avalia as condições dos conectores de destino e determina a próxima etapa a ser acionada.

• Garantia Transacional: As alterações no estado da sessão (dados gravados e histórico) são salvas em um único lote (commit) antes do disparo da próxima etapa no barramento.

• Interrupção: Em caso de exceção de negócio ou erro inesperado (InterrupcaoException), o estado transacional é marcado como falha, um alerta de erro é anexado à sessão e o fluxo é interrompido.

4. Telemetria Assíncrona (ServicoColetorEstatistica)

Ao término da execução (seja em caso de sucesso ou falha), o tempo total gasto em milissegundos, dados de interrupção e identificadores da execução são empacotados e enviados de forma assíncrona para o coletor de estatísticas em background, garantindo zero impacto no tempo de resposta do fluxo principal.

Note

A telemetria é enviada de forma assíncrona para o ServicoColetorEstatistica, garantindo zero impacto no tempo de resposta do fluxo principal.