Codificar URL

Três respostas corretas, e por que um botão só está errado

A codificação percentual substitui um caractere por um % seguido do valor do byte em hexadecimal. A especificação divide os caracteres em três grupos, e tudo o que confunde nesse assunto vem daí. Os caracteres não reservados — letras, dígitos, hífen, ponto, sublinhado e til — nunca precisam ser codificados. Os caracteres reservados — as barras, pontos de interrogação, e-comerciais, sinais de igual e dois-pontos que dão estrutura a uma URL — precisam ser codificados *quando são dados* e não podem ser *quando são estrutura*. Todo o resto é sempre codificado.

É por isso que não existe uma única resposta certa. Codificar uma URL inteira precisa deixar as barras e o ponto de interrogação em paz, senão o endereço deixa de ser um endereço. Codificar um valor para colocar em um parâmetro de query precisa escapar e-comerciais e sinais de igual, senão um valor que contém um deles se divide em dois parâmetros. Codificar um segmento de caminho precisa escapar barras, senão um nome de arquivo com uma barra vira dois diretórios. Um botão único de Codificar escolhe um desses casos e erra nos outros dois terços — geralmente sem aviso, e geralmente de um jeito que só aparece com entradas incomuns.

O espaço é o caractere com mais história. Em uma URL, ele é %20. Em um formulário HTML enviado, é um +, que é uma codificação separada e mais antiga que sobrevive porque os formulários funcionam assim desde 1994. Os dois estão corretos no próprio contexto e nenhum está correto no contexto do outro, e é por isso que um sinal de mais em uma query string é ambíguo de um jeito que nenhum cuidado na hora de codificar consegue resolver.

Texto fora do ASCII é codificado primeiro em UTF-8 e depois byte a byte, então uma única letra acentuada vira duas sequências percentuais e um emoji vira quatro. A codificação dupla é o bug clássico: codificar algo já codificado transforma cada % em %25, então %20 vira %2520 e a outra ponta recebe um sinal de porcentagem literal. Se uma URL está cheia de %25, ela passou por um codificador a mais.

Quando você precisa de outra coisa

No código, use a função da própria linguagem e escolha-a com o mesmo cuidado que esta página exige. O JavaScript tem encodeURI para endereços inteiros e encodeURIComponent para valores; o Python tem urllib.parse.quote com um argumento safe que, por padrão, deixa as barras intactas; o PHP diferencia rawurlencode de urlencode, que diferem justamente na questão espaço versus sinal de mais descrita acima. Melhor ainda, monte URLs com um tipo URL em vez de juntar strings, e a questão desaparece.

Na linha de comando, jq -rR @uri codifica com segurança e lida com uma lista, e curl --data-urlencode monta um parâmetro corretamente codificado sem você precisar pensar em qual dos três casos está — é o único lugar em que isso é realmente fácil.