As arquiteturas de aplicações modernas estão em constante evolução. Um endpoint nascido como API v1 chega à v3; a estrutura de path por trás de um monolito muda completamente após uma divisão em microserviços; um parceiro B2B está acostumado a um esquema de URL diferente; ou um projeto de modernização impõe um novo layout de path. Quando toda mudança exige reconfigurar o cliente ou o backend do zero, o projeto deixa de ser uma tarefa técnica e se torna um longo exercício de coordenação.
A abordagem clássica oferece duas opções ruins. A primeira é adicionar suporte a novos paths no backend — manter endpoints antigos enquanto também se escreve novos dobra a complexidade do código e a carga de testes. A segunda é forçar clientes ou parceiros a migrarem para o novo path — isso gera atrito social e operacional, frequentemente exige renegociação de contratos B2B, aguarda atualizações de aplicativos móveis e estende o cronograma de transição.
O modelo correto é introduzir uma camada de reescrita controlada no fluxo de requisição-resposta. Essa camada converte o path que o cliente envia no path que o backend entende e, se necessário, escreve os paths internos no corpo da resposta de volta para os paths externos que o cliente espera. O backend moderniza internamente; o cliente ou parceiro continua trabalhando com o esquema de URL que já conhece.
Para essa camada ser eficaz, três condições devem ser atendidas. Primeiro, lógica flexível de busca-e-substituição: path fixo, substituição de prefixo, preservação de query e transformações de string baseadas em FX devem ser todas suportadas. Segundo, aplicação condicional: a regra deve ser acionada apenas quando o Host, método, IP, cookie, header ou condição FX corretos corresponderem — não em toda requisição. Terceiro, mapeamento bidirecional com o corpo de resposta: caso contrário, os links internos que o backend retorna tornam-se URLs quebradas no lado do cliente.
A Reescrita de URL e Path do TR7 entrega esse modelo: ações set_path, set_pathq e normalize_uri; padrões FX STRREPLACE / STRREPLACEALL; aplicação condicional FX/ACL; e mapeamento bidirecional de path via modifyResponse formam a base de uma arquitetura de remapeamento transparente de path de backend.
A camada de reescrita de URL do TR7 constrói uma ponte controlada entre camadas de arquitetura de aplicação — indo muito além da simples substituição de path.
Uma requisição recebida para `/api/v1/users/123` pode ser convertida para o path `/internal/v3/users/123` que o backend espera. set_path altera apenas o path; set_pathq reescreve path e query string juntos. O cliente continua enviando sua URL existente enquanto o backend opera na nova arquitetura.
Quando uma substituição fixa de path não é suficiente, a linguagem de expressões FX assume. STRREPLACE e STRREPLACEALL transformam segmentos específicos — prefixo, sufixo ou segmento intermediário — dentro do path. Os operadores podem compor variáveis, campos de busca-e-substituição e condições dentro do mesmo modelo de regra.
Cada regra de reescrita pode ser definida com uma condição FX/ACL. A regra é acionada apenas em um Host, método, IP de origem, cookie, header ou valor de variável FX correspondente. Diferentes transformações de path com diferentes condições podem correr em paralelo no mesmo vService.
Alterar o path da requisição sozinho frequentemente não é suficiente — o backend pode retornar paths internos no corpo da resposta. Com modifyResponse, links HTML, campos href em JSON ou qualquer texto contendo paths internos são escritos de volta para o formato de path externo. O resultado é uma arquitetura de remapeamento transparente de path de backend completamente transparente do ponto de vista do cliente.
A reescrita de path de URL não é uma ação única — é o bloco de construção fundamental para padrões de migração, compatibilidade e mapeamento bidirecional de ocultação de path.
set_path substitui a porção do path da requisição recebida por um novo valor de path. O novo valor pode ser escrito estaticamente ou tornado dinâmico usando variáveis de conteúdo inteligente como `%HOST`, `%PATH`, `%METHOD` ou `%SRCIP`. A query string não é preservada quando set_path é usado; se os dados de query precisam ser retidos, set_pathq é preferido. Esta ação é usada para mapear uma estrutura de URL externa antiga para um novo layout de serviço interno.
set_pathq gerencia path e query string em uma única ação de reescrita. Os operadores podem incluir o valor `%QUERY` existente no novo path para preservar os parâmetros que o cliente enviou. Novos parâmetros também podem ser acrescentados — por exemplo, a requisição `/api/v1/users?id=42` pode ser transformada em `/internal/v3/users?id=42&version=v3-from-v1`. Esse é um mecanismo de transição prático para versionamento de API e compatibilidade com parceiros.
normalize_uri normaliza o path e os componentes de URI para uma forma padrão. As opções incluem mesclagem de múltiplas barras, remoção de segmentos de ponto, resolução de travessias `../`, decodificação de caracteres seguros por RFC 3986, colocação de sequências percent-encoded em maiúsculas, tratamento de fragmentos e ordenação alfabética de parâmetros de query. Essa normalização é importante para consistência de chaves de cache, legibilidade de auditoria e resiliência contra tentativas de bypass de segurança. Também ajuda os controles WAAP e outros controles de segurança a tomarem decisões no mesmo path canônico.
STRREPLACE substitui a primeira correspondência; STRREPLACEALL substitui todas as correspondências. Os operadores podem escrever expressões como `%PATH.STRREPLACE("/old/", "/new/")` para transformar segmentos específicos dentro do path. Esta abordagem lida com substituição de prefixo, substituição de segmento intermediário e movimentação de segmentos de URL legados para um novo layout de serviço. Campos auxiliares na interface facilitam a entrada de valores de busca e substituição de forma mais controlada.
Cada regra de reescrita de path pode correr condicionalmente. A condição pode ser uma correspondência de header Host, uma restrição de método HTTP, uma verificação de intervalo de IP de origem, uma comparação de valor de cookie ou header, ou qualquer expressão verdadeiro/falso produzida pelo mecanismo FX. No mesmo vService, transformações de path específicas por parceiro, por tenant ou por método podem coexistir com condições diferentes. Requisições que não correspondem continuam pelo fluxo normal sem serem afetadas.
Quando set_path ou set_pathq converte o path da requisição para um path interno, o backend pode retornar paths internos no corpo da resposta. O modo replace do modifyResponse escreve esses paths internos de volta para o formato externo. Por exemplo: o cliente solicita `/api/v1/orders`, o backend trabalha com `/internal/orders`, e `"href":"/internal/users/42"` no JSON de resposta é retornado como `"href":"/api/v1/users/42"`. O cliente opera sem nunca ver a estrutura de URL real do backend.
modifyResponse não se limita ao remapeamento de path — suporta diferentes transformações no corpo de resposta. O modo replace corresponde a padrões regex ou texto simples e os substitui, tornando-o a ferramenta principal para remapeamento de path. O modo htmlTag injeta conteúdo controlado em tags HTML. O modo mask oculta dados sensíveis. No contexto de Reescrita de URL e Path, essa capacidade é posicionada especificamente para mapeamento bidirecional de path.
A reescrita de path é aplicada na fase de requisição antes que os controles de segurança downstream avaliem a requisição. Isso significa que Virtual Patching, correspondência de assinaturas WAAP, chaves de rate limiting e regras de tráfego operam no path reescrito. O path normalizado ou reorganizado torna-se a entrada comum para cada camada de decisão subsequente. A lacuna entre a URL externa e o path do serviço interno não produz mais inconsistência de política.
A transformação de path deve ser operacionalmente observável. O TR7 pode carregar o path da requisição original e o valor do path reescrito para o fluxo de auditoria e log. No lado do SIEM, a pergunta "qual path o cliente solicitou, qual path o sistema enviou ao backend?" torna-se respondível. Essa visibilidade é crítica durante projetos de migração e revisões de segurança.
Múltiplas regras de path podem correr em sequência no mesmo vService. A primeira regra normaliza a URI, a segunda realiza uma substituição de prefixo, e a terceira enriquece a query string ou acrescenta um sufixo sob uma condição específica. Cada regra opera sobre a saída da anterior. Esse modelo permite uma cadeia de transformação legível, testável e incremental em vez de uma única regra grande e arriscada.
A reescrita de path de URL é operada em conjunto com variáveis de conteúdo inteligente, integração FX, a linguagem de condições, características de desempenho, comportamento de erro e o padrão de reescrita de resposta.
A nova definição de path pode usar `%PATH`, `%QUERY`, `%HOST`, `%METHOD`, `%SRCIP`, `%PORT` e variáveis personalizadas. Essas variáveis são compostas no campo de valor das ações set_path e set_pathq para produzir um path dinâmico. Funções FX podem ser aplicadas a qualquer uma dessas variáveis.
A reescrita de path de URL é um dos consumidores do mecanismo de expressões FX do TR7. Os operadores não aprendem uma linguagem separada para transformação de path — usam STRREPLACE, STRREPLACEALL e outras funções FX dentro da mesma lógica de expressão. Esse modelo compartilhado fornece uma abordagem de gerenciamento consistente entre regras de tráfego, templates de log e definições de condição.
Condições FX/ACL restringem o escopo de reescrita. Expressões como `%HOST == "partner.example.com"`, `%METHOD in ["POST","PUT"]`, `%SRCIP in MAP_IP("partner_ips")` ou `%HEADER("X-Tenant") == "tenant-a"` são todas válidas. Múltiplas condições podem ser combinadas com lógica AND / OR.
A reescrita de path adiciona baixa sobrecarga por requisição; transformações baseadas em string não requerem operações adicionais de socket ou leitura de arquivo. STRREPLACE e STRREPLACEALL correm em memória. A reescrita de corpo de resposta é mais custosa porque pode exigir buffer de corpo e processamento de regex, portanto deve ser usada apenas onde cenários de remapeamento de path genuinamente o exigem.
Se um erro de parse FX, variável ausente ou incompatibilidade de regex ocorrer durante a reescrita, a requisição pode continuar pelo fluxo normal via fallback seguro — ela não é descartada. O erro é gravado no log de auditoria para que o operador possa investigar o problema de configuração posteriormente. Esse comportamento protege o acesso à produção de ser interrompido por uma regra mal configurada.
O padrão recomendado para remapeamento transparente de path tem duas partes: no lado da requisição, o path externo é convertido para o path interno; no lado da resposta, os paths internos no corpo da resposta são escritos de volta para paths externos. Essas duas regras correm como um par correspondente no mesmo vService. Esse padrão torna-se a estrutura padrão para cenários de API gateway, integrações com parceiros B2B e projetos de migração de monolito para microserviços.
Os clientes existentes continuam usando endpoints `/api/v1/...` enquanto o TR7 converte a requisição internamente para a estrutura `/api/v3/...`. Os links v3 no corpo da resposta são escritos de volta para o formato v1 via modifyResponse. O backend moderno é ativado sem nenhuma mudança no código do cliente.
Um parceiro pode ter usado o esquema de URL `/services/payments/...` por anos enquanto a equipe interna migrou para `/v2/payment-api/...`. Uma regra set_path específica para o parceiro, definida para o header Host do parceiro, lida com a tradução. O parceiro continua trabalhando com a URL antiga; a nova arquitetura de serviço corre por dentro.
Um monolito legado serve os paths `/app/orders`, `/app/users` e `/app/inventory`, cada um dos quais está sendo movido para um serviço de backend separado. O TR7 aplica roteamento baseado em prefixo e remapeamento de path sem expor a divisão aos clientes. Os usuários mantêm o mesmo esquema de URL enquanto os serviços são separados em segundo plano.
Um invasor pode tentar paths percent-encoded, travessias de dot-segment ou confusão de barras para evadir a correspondência de assinaturas WAAP. normalize_uri traz o path para a forma canônica e os controles WAAP subsequentes operam nesse valor limpo. Variantes de URL que são escritas de forma diferente mas apontam para o mesmo recurso são avaliadas de forma mais consistente.
Versionamento de API, compatibilidade com parceiros B2B e remapeamento transparente de path de backend — vamos percorrer uma configuração ao vivo nos seus próprios serviços.