Resolução de Endpoints

A Engine é o componente de entrada responsável por receber as requisições HTTP, identificar qual fluxo e versão devem ser acionados, e preparar o ambiente de execução. Para determinar a rota correta, a Engine utiliza dois mecanismos distintos de resolução de rotas: Resolução por Slugs e Resolução por Código.

---

Estratégias de Resolução de Rotas

A plataforma disponibiliza rotas com propósitos e estratégias de navegação diferentes, atendendo tanto a chamadas de clientes externos quanto a invocações de infraestrutura interna.

Estratégias de resolução de rotas

                  ┌─────────────────────────────────────────┐
                  │            REQUISIÇÃO HTTP              │
                  └────────────────────┬────────────────────┘
                                       │
            ┌──────────────────────────┴──────────────────────────┐
            ▼                                                     ▼
┌───────────────────────┐                             ┌───────────────────────┐
│ Resolução por Slugs   │                             │ Resolução por Código  │
│ (Escopo Público)      │                             │ (Interno / Agendador) │
└───────────┬───────────┘                             └───────────┬───────────┘
            │                                                     │
            │ Consulta Slugs                                      │ Consulta Código
            ▼                                                     ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                            CACHE DE GESTÃO                                  │
│             (Resolução local de alta performance / Fallback API)            │
└──────────────────────────────────────┬──────────────────────────────────────┘
                                       │
                                       ▼
                       ┌──────────────────────────────┐
                       │ ID do Fluxo + Versão Ativa   │
                       └──────────────────────────────┘

Resolução por Slugs

Utilizada para expor rotas amigáveis voltadas a integrações externas, sistemas de terceiros ou aplicações frontend.

Resolução por Código

Destinada ao uso de infraestrutura, chamadas de subfluxos (autorreferência) e disparos de tarefas programadas, priorizando menor consumo de processamento na resolução do caminho.

---

1. Resolução por Slugs (Escopo Público)

• Padrão de URI: /v1/core/public/{slugProjeto}/{slugPacote}/{slugFluxo}

• Funcionamento: O cliente não precisa conhecer os identificadores internos do sistema (UUIDs ou códigos numéricos). A Engine recebe a tríade de slugs e realiza a resolução sequencial do caminho:

1. Identifica o Projeto pelo slugProjeto.

2. Identifica o Pacote pelo slugPacote dentro do projeto.

3. Identifica o Fluxo pelo slugFluxo dentro do pacote.

• Validação de Inicializador: A Engine valida se o método HTTP utilizado na chamada (GET, POST, PUT, DELETE, PATCH) corresponde exatamente ao Inicializador HTTP configurado no cadastro do fluxo. Se o método for divergente, a requisição é rejeitada.

---

2. Resolução por Código (Escopos Interno e Agendador)

• Padrão de URI (Interno): /v1/core/internal/{coFluxo}

• Padrão de URI (Agendador): /v1/core/scheduler/{coFluxo}

• Funcionamento: O chamador informa diretamente o código único do fluxo (coFluxo). A Engine salta as etapas de mapeamento de slugs do projeto e pacote, localizando o fluxo de forma direta no índice em memória.

• Uso Típico:

• internal: Invocação de subfluxos operados pelo runner de autorreferência.

• scheduler: Chamadas disparadas pelo Agendador nos horários programados por expressão CRON.

---

Mecanismo de Cache e Alta Performance

A resolução de endpoints é projetada para operar com o menor tempo de resposta possível, evitando acessos frequentes ao banco de dados relacional durante as chamadas de execução:

1. Resolução via Cache em Memória

A Engine mantém um repositório de cache de gestão atualizado com os mapeamentos de slugs e códigos de todos os fluxos publicados.

• Para chamadas por slug, a chave de busca em memória combina slugProjeto:slugPacote:slugFluxo:inicializadorHttp.

• Para chamadas por código, a busca é feita diretamente pela chave do código do fluxo coFluxo.

2. Degradação Graciosa (Cache-aside)

Se a Engine receber uma chamada para um fluxo recém-publicado que ainda não esteja carregado em sua memória local (cache miss), ela realiza uma consulta à API do Console em segundo plano, atualiza seu cache interno de forma não-bloqueante e prossegue com a execução do fluxo.

Note

Em caso de cache miss, a Engine consulta a API do Console em segundo plano e prossegue com a execução sem bloquear a chamada original.

---

Resoluções de Versão e Tags

Uma vez localizado o fluxo (seja por slug ou por código), a Engine determina a versão exata que deve ser executada:

• Versão Padrão (Sem Tag): Se a requisição não especificar uma versão, a Engine busca no cache a versão padrão publicada para aquele ambiente.

• Versão Específica via Parâmetro (Tag): O cliente pode direcionar a chamada para uma tag de versão específica informando o parâmetro de consulta tag na URL (ex: ?tag=v2-beta). A Engine localiza a publicação correspondente àquela tag e executa o modelo associado.