Improve nginx map parsing, support default and regular expressions.

davidje13 · davidje13 · commit 12161115eddf · 2026-06-24T11:40:25.000+01:00
diff --git a/src/bin/buildRouter.mts b/src/bin/buildRouter.mts
@@ -15,6 +15,7 @@ import {
 } from '../index.mts';
 import type { ConfigMount } from './config/types.mts';
 import { dependencies } from './modules/dependencies.mts';
+import { Mapper, nginxTokenise } from './nginx.mts';
 import { render } from './template.mts';
 
 export interface LogInfo {
@@ -100,25 +101,44 @@ export async function buildRouter(mount: ConfigMount[], log: (info: LogInfo) =>
         );
         break;
       case 'redirect-map':
-        const norm = item.options.caseSensitive ? (v: string) => v : (v: string) => v.toLowerCase();
-        const mapping = new Map<string, string>();
+        const mapper = new Mapper(item.options.caseSensitive);
         if (typeof item.mapping === 'string') {
-          for (const statement of nginxTokenise(await readFile(item.mapping, 'utf-8'))) {
-            if (statement.length !== 2 || statement[0]![0] !== '/') {
+          const content = await readFile(item.mapping, 'utf-8');
+          tokens: for (const statement of nginxTokenise(content)) {
+            const key = statement[0]!;
+            if (key.literal) {
+              switch (key.token) {
+                case 'default':
+                  if (statement.length === 2) {
+                    mapper.setDefault(statement[1]!.token);
+                    continue tokens;
+                  }
+                  break;
+                case 'hostnames':
+                  throw new Error('redirect-map does not support hostnames');
+                case 'include':
+                  throw new Error('redirect-map does not support nested mapping files');
+                case 'volatile':
+                  // ignore
+                  break;
+              }
+            }
+            if (statement.length === 2) {
+              mapper.add(key.token, statement[1]!.token);
+            } else {
               throw new Error(
-                `unexpected statement in mapping file: ${statement.map((p) => JSON.stringify(p)).join(' ')}`,
+                `unknown statement in mapping file: ${statement.map((p) => JSON.stringify(p)).join(' ')}`,
               );
             }
-            mapping.set(norm(statement[0]!), statement[1]!);
           }
         } else {
           for (const [k, v] of Object.entries(item.mapping)) {
-            mapping.set(norm(k), v);
+            mapper.add(k, v);
           }
         }
         router.use((req, res) => {
-          const redirect = mapping.get(norm(req.url ?? '/'));
-          if (redirect !== undefined && redirect !== (req.url ?? '/')) {
+          const redirect = mapper.get(req.url ?? '/');
+          if (redirect && redirect !== (req.url ?? '/')) {
             res.setHeader('location', redirect);
             res.statusCode = item.status;
             return res.end();
@@ -143,32 +163,3 @@ const getParam = (req: IncomingMessage) => (key: string) =>
     : key[0] === '?'
       ? { _value: getQuery(req, key.substring(1)), _encoding: 'raw' }
       : { _value: getPathParameter(req, key), _encoding: 'raw' };
-
-function* nginxTokenise(source: string) {
-  let statement: string[] = [];
-  const token =
-    /(\s+|#[^\n]*)|(;)|(?:"((?:[^"\\]+|\\.)*)")|(?:'((?:[^'\\]+|\\.)*)')|((?:[^#;\s\\"']+|\\.)+)/y;
-  while (token.lastIndex < source.length) {
-    const m = token.exec(source);
-    if (!m) {
-      throw new Error('invalid nginx syntax');
-    }
-    const [, separator, semicolon, dquot, squot, nquot] = m;
-    if (separator) {
-      continue;
-    }
-    if (semicolon) {
-      yield statement;
-      statement = [];
-      continue;
-    }
-    const part = dquot ?? squot ?? nquot;
-    if (part === undefined) {
-      throw new Error('nginx tokenisation error');
-    }
-    statement.push(part.replaceAll(/\\(.)/g, '$1'));
-  }
-  if (statement.length) {
-    yield statement;
-  }
-}
diff --git a/src/bin/buildRouter.test.mts b/src/bin/buildRouter.test.mts
@@ -1,5 +1,6 @@
+import { join } from 'node:path';
 import { requestHandler } from '../index.mts';
-import { makeTestTempDir, makeTestTempFile } from '../test-helpers/makeFileStructure.mts';
+import { makeTestTempDir } from '../test-helpers/makeFileStructure.mts';
 import { responds } from '../test-helpers/responds.mts';
 import { withServer } from '../test-helpers/withServer.mts';
 import type { ConfigMount } from './config/types.mts';
@@ -308,10 +309,8 @@ describe('buildRouter', () => {
       });
     });
 
-    const TEST_MAPPING_FILE = makeTestTempFile(
-      'map-',
-      'redirects.map',
-      `
+    const NGINX_MAPS = makeTestTempDir('map-', {
+      'syntax.map': `
 /foo /new-foo;
 # comment
 /bar\t/new-bar #comment
@@ -324,7 +323,15 @@ describe('buildRouter', () => {
 /s1 /escaped\\ space;
 /s2 "/quoted space";
 `,
-    );
+      'with-default.map': `
+/foo /one;
+default /other;
+`,
+      'regex.map': `
+~*^/one/(.+)/end.(?<ext>.+)$ /new/$1.$ext;
+~^/case/(.+)/end.(?<ext>.+)$ /new/$1.$ext;
+`,
+    });
 
     it(
       'loads mappings from an nginx-formatted mapping file',
@@ -333,7 +340,7 @@ describe('buildRouter', () => {
         const router = await buildRouter([
           {
             type: 'redirect-map',
-            mapping: getTyped(TEST_MAPPING_FILE),
+            mapping: join(getTyped(NGINX_MAPS), 'syntax.map'),
             status: 307,
             options: { caseSensitive: false },
           },
@@ -368,6 +375,69 @@ describe('buildRouter', () => {
         });
       },
     );
+
+    it(
+      'supports "default" in nginx-formatted mapping files',
+      { timeout: 3000 },
+      async ({ getTyped }) => {
+        const router = await buildRouter([
+          {
+            type: 'redirect-map',
+            mapping: join(getTyped(NGINX_MAPS), 'with-default.map'),
+            status: 307,
+            options: { caseSensitive: false },
+          },
+        ]);
+        return withServer(router, async (url) => {
+          await expect(
+            fetch(url + '/foo', { redirect: 'manual' }),
+            responds({ status: 307, headers: { location: '/one' }, body: '' }),
+          );
+          await expect(
+            fetch(url + '/nope', { redirect: 'manual' }),
+            responds({ status: 307, headers: { location: '/other' }, body: '' }),
+          );
+        });
+      },
+    );
+
+    it(
+      'supports regular expressions in nginx-formatted mapping files',
+      { timeout: 3000 },
+      async ({ getTyped }) => {
+        const router = await buildRouter([
+          {
+            type: 'redirect-map',
+            mapping: join(getTyped(NGINX_MAPS), 'regex.map'),
+            status: 307,
+            options: { caseSensitive: false },
+          },
+          FALLBACK_200,
+        ]);
+        return withServer(router, async (url) => {
+          await expect(
+            fetch(url + '/one/a/end.xyz', { redirect: 'manual' }),
+            responds({ status: 307, headers: { location: '/new/a.xyz' }, body: '' }),
+          );
+          await expect(
+            fetch(url + '/one/a/END.xyz', { redirect: 'manual' }),
+            responds({ status: 307, headers: { location: '/new/a.xyz' }, body: '' }),
+          );
+          await expect(
+            fetch(url + '/nope/one/a/end.xyz', { redirect: 'manual' }),
+            responds({ status: 200 }),
+          );
+          await expect(
+            fetch(url + '/case/b/end.w', { redirect: 'manual' }),
+            responds({ status: 307, headers: { location: '/new/b.w' }, body: '' }),
+          );
+          await expect(
+            fetch(url + '/case/b/END.w', { redirect: 'manual' }),
+            responds({ status: 200 }),
+          );
+        });
+      },
+    );
   });
 
   it('logs requests', { timeout: 3000 }, async () => {
diff --git a/src/bin/man1/web-listener.1 b/src/bin/man1/web-listener.1
@@ -246,11 +246,17 @@ defined.
 Add redirects from an NGINX .map file.
 This format is loosely one redirect per line, with the requested URL first,
 then a space, then the redirect URL, and finally a semicolon.
-URLs can be quoted.
+Matching is case insensitive.
+URLs can be quoted, and regular expression syntax is supported by prefixing the
+URL with ~.
 Comments can be included using the # character.
 A full explanation can be found at
 .Lk https://nginx.org/en/docs/http/ngx_http_map_module.html .
-Note that matching is case insensitive.
+Note that regular expressions are parsed using native Javascript regular
+expression syntax rather than PCRE, as used by NGINX
+.Po
+the differences are usually not important
+.Pc .
 See
 .Sx REDIRECTING
 for the corresponding NGINX configuration.
@@ -699,25 +705,28 @@ The equivalent NGINX configuration is:
 .Bd -literal -offset 2n
 # map_hash_max_size 2048; # optionally set an explicit hashtable size
 map $request_uri $redirected {
-  include ./my-redirect-file.map;
+  include /path/to/my-redirect-file.map;
 }
 
 server {
-  if ($redirected == $request_uri) {
+  if ($redirected = $request_uri) {
     # do not redirect if we are already at the target URL
     # (e.g. if redirects are being used to normalise case)
     set $redirected "";
   }
   if ($redirected) {
-    return 301 $redirected;
+    return 307 $redirected;
   }
+
+  # (rest of configuration)
 }
 .Ed
 .Pp
 An example file:
 .Bd -literal -offset 2n
 /old-url /new-url;
 /another-old-url "/and-its-new-url"; # a comment
+"~*^/regex/(.*)$" /updated/$1;
 .Ed
 .
 .\"======================================================================
diff --git a/src/bin/nginx.mts b/src/bin/nginx.mts
@@ -0,0 +1,85 @@
+export class Mapper {
+  declare private readonly _norm: (v: string) => string;
+  declare private readonly _map: Map<string, string>;
+  declare private readonly _patterns: { _key: RegExp; _target: string }[];
+  declare private _fallback: string;
+
+  constructor(caseSensitive: boolean) {
+    this._norm = caseSensitive ? (v) => v : (v) => v.toLowerCase();
+    this._map = new Map();
+    this._patterns = [];
+    this._fallback = '';
+  }
+
+  add(key: string, value: string) {
+    if (key[0] === '/') {
+      this._map.set(this._norm(key), value);
+    } else if (key[0] === '~') {
+      const caseSensitive = key[1] !== '*';
+      const pattern = key.substring(caseSensitive ? 1 : 2);
+      this._patterns.push({ _key: new RegExp(pattern, caseSensitive ? '' : 'i'), _target: value });
+    } else {
+      throw new Error(`invalid URL: ${key}`);
+    }
+  }
+
+  setDefault(value: string) {
+    this._fallback = value;
+  }
+
+  get(key: string) {
+    const literal = this._map.get(this._norm(key));
+    if (literal !== undefined) {
+      return literal;
+    }
+    for (const p of this._patterns) {
+      p._key.lastIndex = 0;
+      const m = p._key.exec(key);
+      if (m) {
+        return p._target.replaceAll(/\$(?:([0-9]+)|([a-zA-Z][a-zA-Z0-9]*))/g, (_, id, name) => {
+          if (id) {
+            return m[Number.parseInt(id)] ?? '';
+          } else if (m.groups && Object.prototype.hasOwnProperty.call(m.groups, name)) {
+            return m.groups[name] ?? '';
+          } else {
+            return '';
+          }
+        });
+      }
+    }
+    return this._fallback;
+  }
+}
+
+export function* nginxTokenise(source: string) {
+  let statement: { token: string; literal: boolean }[] = [];
+  const token =
+    /(\s+|#[^\n]*)|(;)|(?:"((?:[^"\\]+|\\.)*)")|(?:'((?:[^'\\]+|\\.)*)')|((?:[^#;\s\\"']+|\\.)+)/y;
+  while (token.lastIndex < source.length) {
+    const m = token.exec(source);
+    if (!m) {
+      throw new Error('invalid nginx syntax');
+    }
+    const [, separator, semicolon, dquot, squot, nquot] = m;
+    if (separator) {
+      continue;
+    }
+    if (semicolon) {
+      yield statement;
+      statement = [];
+      continue;
+    }
+    if (nquot && !nquot.includes('\\')) {
+      statement.push({ token: nquot, literal: true });
+    } else {
+      const part = dquot ?? squot ?? nquot;
+      if (part === undefined) {
+        throw new Error('nginx tokenisation error');
+      }
+      statement.push({ token: part.replaceAll(/\\(.)/g, '$1'), literal: false });
+    }
+  }
+  if (statement.length) {
+    yield statement;
+  }
+}
