Regras de codificação percentual

Codificação percentual escreve % seguido de exatamente dois dígitos hexadecimais para cada octeto escapado:

byte 32 (espaço)  → %20
byte 38 (&)       → %26
byte 231 (decimal) → hex E7 → %E7   (significado depende do contexto de decode!)

Letras A–F podem ser maiúsculas ou minúsculas (%e7 ≡ %E7). Interoperabilidade melhora com consistência, mas parsers devem aceitar caso misto.

Um escape = um byte (não “uma unidade UTF-16”)

Ao codificar strings Unicode, codifique os octetos UTF-8 salvo esquema que diga o contrário:

π (U+03C0)

Bytes UTF-8: CF 80  → %CF%80
Modelo mental errado: codificar os dígitos do code point “03C0” em hex
Modelo certo: serializar em bytes primeiro, escapar cada byte problemático como %HH

Quais bytes precisam de escape?

Checklist em nível de aprendizado:

1. Bytes cujo caractere gráfico interagiria com separadores URI (?, &, #, /, :, @, [, ]) quando pertencem a dados opacos, não pontuação.
2. Bytes fora do ASCII para caminhos de compatibilidade ampla.
3. Bytes de controle, espaços, DEL e espaço em branco ambíguo como dado literal em parâmetros.

RFC 3986 define regras genéricas e comportamentos normalizados; frameworks podem apertar (por exemplo rejeitar % solto no final).

Escapes inválidos

Sequências incompletas confundem parsers:

%           → malformado (sem dígitos)
%AB         → malformado (faltam dois nibbles hex)
%GG         → dígitos hex inválidos

Boas bibliotecas validam ou rejeitam entrada malformada em vez de “adivinhar”.

Over-encoding e double encoding

Aplicar codificação percentual duas vezes é bug recorrente:

valor literal: 100%

primeira passagem:    100%25     (percent literal vira %25)
passagem errada:      100%2525   (codificou de novo o % já seguro)

Se o servidor recebe %2525, muitas vezes decodifica duas vezes em um % — não o que você queria para exibição. Decida uma vez se o subsistema espera texto codificado ou decodificado e mantenha o invariante.

Dicas de normalização

Canonicalização inclui:

• Hex maiúsculo vs minúsculo (ambos válidos).
• Codificar pontuação vs deixar literal quando legalmente não ambíguo no componente.
• Normalizar Unicode para NFC antes de UTF-8 (opcional, evita grafias duplicadas divergindo servidores).

Consistência entre gateways (CDN vs app vs banco) evita mismatches sutis em assinatura ou cache.