feat: expose sanitizeUrlPath (#415)

Author: Eomm

README.md

@@ -28,6 +28,7 @@ Do you need a real-world example that uses this router? Check out [Fastify](http
   - [hasRoute (method, path, [constraints])](#hasroute-method-path-constraints)
   - [lookup(request, response, [context], [done])](#lookuprequest-response-context-done)
   - [find(method, path, [constraints])](#findmethod-path-constraints)
+  - [sanitizeUrlPath(url, [useSemicolonDelimiter])](#sanitizeurlpathurl-usesemicolondelimiter)
   - [prettyPrint([{ method: 'GET', commonPrefix: false, includeMeta: true || [] }])](#prettyprint-commonprefix-false-includemeta-true---)
   - [reset()](#reset)
   - [routes](#routes)
@@ -489,6 +490,27 @@ router.find('GET', '/example', { host: 'fastify.io', version: '1.x' })
 // => null
 ```
 
+#### sanitizeUrlPath(url, [useSemicolonDelimiter])
+Sanitize and decode a URL path using the same logic that `lookup` uses internally.
+
+```js
+const FindMyWay = require('find-my-way')
+
+const url = '/foo%20bar?foo=bar'
+const path = FindMyWay.sanitizeUrlPath(url)
+
+console.log(path) // '/foo bar'
+```
+
+If you need to support `;` as a query string delimiter (for example `/foo;bar=1`), pass `useSemicolonDelimiter: true`:
+
+```js
+const path = FindMyWay.sanitizeUrlPath('/foo;bar=1', true)
+console.log(path) // '/foo'
+```
+
+This function will throw an error if the URL is malformed.
+
 <a name="pretty-print"></a>
 #### prettyPrint([{ commonPrefix: false, includeMeta: true || [] }])
 `find-my-way` builds a tree of routes for each HTTP method. If you call the `prettyPrint`

index.js

@@ -762,6 +762,14 @@ Router.prototype.all = function (path, handler, store) {
   this.on(httpMethods, path, handler, store)
 }
 
+Router.sanitizeUrlPath = function sanitizeUrlPath (url, useSemicolonDelimiter) {
+  const decoded = safeDecodeURI(url, useSemicolonDelimiter)
+  if (decoded.shouldDecodeParam) {
+    return safeDecodeURIComponent(decoded.path)
+  }
+  return decoded.path
+}
+
 module.exports = Router
 
 function escapeRegExp (string) {

lib/url-sanitizer.js

@@ -34,6 +34,15 @@ function decodeComponentChar (highCharCode, lowCharCode) {
   return null
 }
 
+/**
+ * Safely decodes a URI path, preserving reserved characters in querystring.
+ *
+ * @param {string} path - The full request path, possibly including querystring.
+ * @param {boolean} [useSemicolonDelimiter] - When true, also treat `;` as a query delimiter.
+ * @returns {{ path: string, querystring: string, shouldDecodeParam: boolean }}
+ * An object containing the decoded path, the raw querystring, and a flag indicating
+ * whether any path parameters contain percent-encoded reserved characters.
+ */
 function safeDecodeURI (path, useSemicolonDelimiter) {
   let shouldDecode = false
   let shouldDecodeParam = false

test/url-sanitizer.test.js

@@ -0,0 +1,43 @@
+'use strict'
+
+const { test } = require('node:test')
+const FindMyWay = require('..')
+
+test('sanitizeUrlPath should decode reserved characters inside params and strip querystring', t => {
+  t.plan(1)
+
+  const url = '/%65ncod%65d?foo=bar'
+  const sanitized = FindMyWay.sanitizeUrlPath(url)
+
+  t.assert.equal(sanitized, '/encoded')
+})
+
+test('sanitizeUrlPath should decode non-reserved characters but keep reserved encoded when not in params', t => {
+  t.plan(1)
+
+  const url = '/hello/%20world?foo=bar'
+  const sanitized = FindMyWay.sanitizeUrlPath(url)
+
+  t.assert.equal(sanitized, '/hello/ world')
+})
+
+test('sanitizeUrlPath should treat semicolon as queryparameter delimiter when enabled', t => {
+  t.plan(2)
+
+  const url = '/hello/%23world;foo=bar'
+
+  const sanitizedWithDelimiter = FindMyWay.sanitizeUrlPath(url, true)
+  t.assert.equal(sanitizedWithDelimiter, '/hello/#world')
+
+  const sanitizedWithoutDelimiter = FindMyWay.sanitizeUrlPath(url, false)
+  t.assert.equal(sanitizedWithoutDelimiter, '/hello/#world;foo=bar')
+})
+
+test('sanitizeUrlPath trigger an error if the url is invalid', t => {
+  t.plan(1)
+
+  const url = '/Hello%3xWorld/world'
+  t.assert.throws(() => {
+    FindMyWay.sanitizeUrlPath(url)
+  }, 'URIError: URI malformed')
+})