URLPattern no Node.js: rotas e validação de URLs

O URLPattern no Node.js permite comparar URLs completas ou partes delas com padrões declarativos. Em vez de quebrar o caminho manualmente, aplicar expressões regulares e depois extrair parâmetros, você define protocolo, hostname, pathname, search e hash em um único objeto.

A API é especialmente útil em roteadores leves, proxies, validação de callbacks, regras de autorização, filtros de webhooks e ferramentas que precisam reconhecer famílias de URLs. Ela segue o modelo dos Web Standards e pode ser usada de forma semelhante em ambientes compatíveis.

Neste guia, você aprenderá a criar padrões, testar URLs, extrair grupos nomeados, combinar host e caminho, lidar com baseURL, usar ignoreCase, evitar padrões permissivos e aplicar URLPattern com segurança.

Disponibilidade e estabilidade

A classe URLPattern está disponível globalmente em versões atuais do Node.js, mas sua estabilidade deve ser confirmada na versão de runtime adotada. Consulte a documentação oficial de URLPattern antes de usar em produção.

const pattern = new URLPattern({ pathname: '/users/:id' });

Se o projeto suporta versões anteriores, faça feature detection:

if (typeof URLPattern === 'undefined') {
  throw new Error('URLPattern não está disponível neste runtime');
}

Primeiro teste

const pattern = new URLPattern({
  pathname: '/products/:slug'
});

console.log(pattern.test('https://example.com/products/notebook'));
// true

O método test() retorna apenas um booleano. Use quando você quer saber se a URL corresponde ao padrão.

Extraindo grupos com exec

const pattern = new URLPattern({
  pathname: '/users/:userId/orders/:orderId'
});

const match = pattern.exec(
  'https://example.com/users/42/orders/900'
);

console.log(match.pathname.groups.userId);  // 42
console.log(match.pathname.groups.orderId); // 900

exec() retorna informações separadas por componente da URL. Isso evita misturar hostname, query e pathname em uma regex única.

Padrão completo

const pattern = new URLPattern({
  protocol: 'https',
  hostname: 'api.example.com',
  pathname: '/v1/orders/:id'
});

O padrão acima rejeita HTTP, outro host e rotas fora de /v1/orders. Essa combinação é útil para allowlists de destinos externos.

Usando string

const pattern = new URLPattern(
  'https://api.example.com/v1/orders/:id'
);

A forma em objeto é mais explícita quando apenas alguns componentes importam. A forma em string é conveniente para padrões completos.

Base URL

const pattern = new URLPattern(
  '/docs/:section/:page',
  'https://example.com'
);

console.log(
  pattern.test('https://example.com/docs/node/streams')
);

A base permite construir padrões relativos. Não use uma base controlada pelo usuário sem validação.

Wildcards

const pattern = new URLPattern({
  pathname: '/assets/*'
});

Wildcards são úteis, mas ampliam o conjunto aceito. Prefira grupos específicos quando a aplicação conhece a estrutura esperada.

Grupos nomeados

const pattern = new URLPattern({
  pathname: '/blog/:year/:month/:slug'
});

Depois do match, valide cada grupo. URLPattern identifica a estrutura, mas não garante que year seja um ano válido ou que slug esteja autorizado.

const result = pattern.exec(url);
const year = Number(result.pathname.groups.year);

if (!Number.isInteger(year) || year < 2000 || year > 2100) {
  throw new Error('Ano inválido');
}

Hostname com subdomínio

const pattern = new URLPattern({
  hostname: ':tenant.example.com',
  pathname: '/dashboard'
});

Esse formato pode extrair um tenant do host. Nunca use o valor diretamente para acessar dados. Verifique se o tenant existe, se o usuário pertence a ele e se a origem é confiável.

Consulte Multi-Tenancy no Node.js.

Query string

const pattern = new URLPattern({
  pathname: '/search',
  search: '?q=:term'
});

Em muitos casos, é melhor combinar URLPattern para o caminho e URLSearchParams para parâmetros. Query strings podem conter ordem diferente, chaves repetidas e valores opcionais.

const url = new URL(input);

if (!routePattern.test(url)) {
  return false;
}

const term = url.searchParams.get('q');

Veja URL API no Node.js.

Hash

Fragments normalmente não chegam ao servidor HTTP, porque são processados pelo navegador. Eles podem aparecer em ferramentas, CLIs e processamento de URLs armazenadas.

const pattern = new URLPattern({
  hash: '#section-:id'
});

Case sensitivity

const pattern = new URLPattern(
  { pathname: '/Docs/:page' },
  undefined,
  { ignoreCase: true }
);

Use ignoreCase somente quando a regra de negócio realmente permite. Caminhos HTTP podem ser case-sensitive em vários servidores.

Roteador simples

const routes = [
  {
    method: 'GET',
    pattern: new URLPattern({ pathname: '/users/:id' }),
    handler: getUser
  },
  {
    method: 'POST',
    pattern: new URLPattern({ pathname: '/users' }),
    handler: createUser
  }
];

function resolveRoute(request) {
  const url = new URL(request.url);

  for (const route of routes) {
    if (route.method !== request.method) continue;

    const match = route.pattern.exec(url);
    if (match) return { route, match };
  }

  return null;
}

Para aplicações completas, frameworks oferecem middleware, validação e tratamento de erros. URLPattern é útil quando você precisa de uma camada pequena ou regras independentes do framework.

Proxy reverso

const allowedDestinations = [
  new URLPattern('https://api.partner.com/v1/*'),
  new URLPattern('https://files.partner.com/public/*')
];

function isAllowed(url) {
  return allowedDestinations.some(pattern => pattern.test(url));
}

Ao criar proxy, valide também DNS, redirects, IPs privados e resolução dinâmica. Apenas comparar a string não elimina SSRF.

Veja SSRF no Node.js.

Callbacks OAuth

URLPattern pode validar a estrutura de callbacks registrados:

const callbackPattern = new URLPattern({
  protocol: 'https',
  hostname: 'app.example.com',
  pathname: '/auth/callback'
});

Não aceite wildcards amplos em redirect URIs. OAuth exige correspondência rígida para evitar redirecionamentos maliciosos.

Consulte OAuth 2.0 com PKCE no Node.js.

Webhooks

Ao receber um webhook, URLPattern pode mapear versões e provedores:

const webhook = new URLPattern({
  pathname: '/webhooks/:provider/:version'
});

Depois do match, valide assinatura, timestamp, replay e tamanho do corpo. O padrão da URL não autentica o emissor.

Regras de autorização

const adminRoutes = new URLPattern({
  pathname: '/admin/*'
});

if (adminRoutes.test(url) && !user.roles.includes('admin')) {
  throw new Error('Acesso negado');
}

Essa lógica pode ajudar, mas autorização não deve depender apenas do caminho. Verifique recurso, tenant, método e política.

Veja RBAC no Node.js.

Validação após o match

Grupos sempre devem passar por validação de domínio:

const id = match.pathname.groups.id;

if (!/^[1-9][0-9]*$/.test(id)) {
  throw new Error('ID inválido');
}

URLPattern separa estrutura. Regras como faixa numérica, existência, permissão e formato pertencem à aplicação.

Percent-encoding

URLs podem conter caracteres codificados. Teste valores com espaços, barras codificadas e Unicode. Não decodifique repetidamente, pois double decoding pode transformar entrada inofensiva em traversal.

Integração com URL

const url = new URL(input);

if (url.protocol !== 'https:') {
  throw new Error('HTTPS obrigatório');
}

const result = pattern.exec(url);

Use URL para normalização e inspeção; use URLPattern para correspondência.

Performance

Crie padrões uma vez e reutilize. Não construa um novo objeto para cada requisição sem necessidade.

const patterns = Object.freeze([
  new URLPattern({ pathname: '/health' }),
  new URLPattern({ pathname: '/users/:id' })
]);

Meça em carga real. Para centenas de milhares de rotas, uma estrutura especializada pode ser mais eficiente.

Testes

import test from 'node:test';
import assert from 'node:assert/strict';

test('extrai usuário', () => {
  const pattern = new URLPattern({ pathname: '/users/:id' });
  const match = pattern.exec('https://example.com/users/42');

  assert.equal(match.pathname.groups.id, '42');
});

Inclua hosts incorretos, protocolo HTTP, caminhos extras, Unicode, query repetida e entradas inválidas.

Erros comuns

• usar wildcard em redirects;
• confiar em grupo sem validação;
• ignorar protocolo e hostname;
• usar pattern como proteção completa contra SSRF;
• confundir query com pathname;
• habilitar ignoreCase sem necessidade;
• recriar padrões em toda requisição;
• não testar percent-encoding.

Checklist

• verifique suporte do runtime;
• defina componentes explicitamente;
• reutilize padrões;
• valide grupos extraídos;
• combine com URLSearchParams;
• restrinja host e protocolo;
• evite wildcards em destinos sensíveis;
• teste entradas adversariais;
• mantenha autorização separada;
• meça performance.

Conclusão

O URLPattern no Node.js fornece uma forma declarativa de reconhecer URLs e extrair parâmetros. A API reduz regex manuais e mantém protocolo, host, caminho, query e hash separados.

Use-a para roteamento leve, proxies, callbacks e webhooks, mas mantenha validação e autorização após o match. Um padrão confirma estrutura; ele não prova identidade, permissão ou segurança do destino.

Para o comportamento padronizado, consulte também a especificação URLPattern.