rax-radix-tree 1.0.2 → 1.0.3

package/README.md

@@ -1,7 +1,9 @@
-# Name
+# rax-radix-tree
 
 A high-performance radix tree implementation for Node.js, providing efficient routing and pattern matching capabilities. This library is built on top of the rax radix tree implementation in ANSI C (https://github.com/antirez/rax), offering excellent performance and scalability for large-scale applications.
 
+> Ships with TypeScript type definitions (`index.d.ts`).
+
 # Table of Contents
 
 - [Name](#name)
@@ -9,13 +11,17 @@ A high-performance radix tree implementation for Node.js, providing efficient ro
 - [Synopsis](#synopsis)
   - [RadixTree](#radixtree)
   - [HttpRadixTree](#httpradixtree)
+- [Matching Priority](#matching-priority)
 - [Class Methods](#class-methods)
   - [RadixTree](#radixtree-1)
     - [constructor](#constructor)
     - [findAllRoutes](#findallroutes)
     - [findRoute](#findroute)
+    - [addRoute](#addroute)
+    - [removeRoute](#removeroute)
   - [HttpRadixTree](#httpradixtree-1)
     - [constructor](#constructor-1)
+    - [findRoute (request fields)](#findroute-request-fields)
 - [Examples](#examples)
   - [Full Path Match](#full-path-match)
   - [Prefix Match](#prefix-match)
@@ -113,6 +119,20 @@ console.log(httpResult4); // null
 
 [Back to TOC](#table-of-contents)
 
+# Matching Priority
+
+`findAllRoutes` collects matches from three internal structures and returns them in a fixed category order:
+
+1. Exact matches (paths without wildcards)
+2. Suffix matches (paths starting with `*` / `**`, e.g. `**.jpg`)
+3. Prefix matches (paths ending with `*` / `**`, e.g. `/api/**`)
+
+Within each category, routes are sorted by descending path length (longer, more specific patterns first). `findRoute` returns the first route in this combined order (after applying the custom match function, if any).
+
+If a request omits the `method` argument (or passes an empty string), method filtering is skipped and routes match regardless of their configured `methods`. When a non-empty `method` is provided, a route matches only if its `methods` includes that method or `ALL`.
+
+[Back to TOC](#table-of-contents)
+
 # Class Methods
 
 ## RadixTree
@@ -128,7 +148,14 @@ Creates a new RadixTree instance.
 Parameters:
 
 - `routes`: Array of route configurations
-- `matchFunc`: Optional custom matching function
+- `matchFunc`: Optional custom matching function with signature `(route, req) => boolean`. When provided, `findRoute` returns the first route (in priority order) for which `matchFunc` returns a truthy value. `HttpRadixTree` uses this internally to apply host / remote address / expression checks.
+
+```js
+const tree = new RadixTree(routes, (route, req) => {
+  // custom logic, e.g. only accept internal traffic
+  return req.internal === true;
+});
+```
 
 Each route can contain the following properties:
 
@@ -149,11 +176,11 @@ Finds all routes that match the given path and method.
 Parameters:
 
 - `path`: The path to match against
-- `method`: (Optional) The HTTP method to match
+- `method`: (Optional) The HTTP method to match. If omitted or an empty string, method filtering is skipped and routes match regardless of their configured `methods`.
 
 Returns:
 
-- An array of matching routes
+- An array of matching routes, ordered as described in [Matching Priority](#matching-priority)
 
 ### findRoute
 
@@ -171,6 +198,30 @@ Returns:
 
 - The matching route object if found, or null if no match is found
 
+### addRoute
+
+```js
+addRoute(route: Route): this
+```
+
+Dynamically adds a single route after construction. The `route` argument has the same shape as the entries passed to the constructor (it must contain `paths`). Returns the tree instance for chaining.
+
+```js
+tree.addRoute({ paths: ['/api/reports/**'], methods: ['GET'], meta: { id: 99 } });
+```
+
+### removeRoute
+
+```js
+removeRoute(routePath: string): number
+```
+
+Removes all routes previously registered for a given path pattern. `routePath` must match a pattern that was supplied in some route's `paths` (e.g. `'/api/users'`, `'/api/*'`, `'**.jpg'`). Returns the number of route entries removed (`0` if none matched).
+
+```js
+const removed = tree.removeRoute('/api/reports/**'); // e.g. 1
+```
+
 ## HttpRadixTree
 
 ### constructor
@@ -191,7 +242,7 @@ Each HTTP route can contain the following properties:
 |-------------|-----------|------------------------------------------------------------------------------------------------|---------------------------------------------|
 | paths       | Required  | List of request paths to match. Supports the same matching rules as RadixTree.                 | `["/api/**", "/users/*"]`                   |
 | methods     | Optional  | List of HTTP methods to match. Same as RadixTree.                                              | `["GET", "POST"]`                           |
-| hosts       | Optional  | List of host addresses to match. Supports wildcards. For example, `*.example.com` can match `foo.example.com` and `bar.example.com`. | `["example.com", "*.api.com"]`              |
+| hosts       | Optional  | List of host addresses to match. Supports wildcards. `*.example.com` matches the apex `example.com` and any subdomain such as `foo.example.com`, but requires a dot boundary, so it does NOT match `badexample.com`. A `:port` suffix in the request `Host` header is ignored during comparison. | `["example.com", "*.api.com"]`              |
 | remoteAddrs | Optional  | List of remote addresses (IPv4 or IPv6) to match. Supports CIDR format.                        | `["127.0.0.1", "192.168.1.0/24", "::1", "fe80::/10"]` |
 | exprs       | Optional  | List of expressions to evaluate request parameters. Uses [filtrex](https://github.com/joewalnes/filtrex) syntax. | `["age >= 18", "category in ('electronics', 'books')"]` |
 | meta        | Optional  | Metadata to be returned when the route matches.                                                | `{ id: 1 }`                                 |
@@ -200,6 +251,25 @@ HttpRadixTree adds support for matching hosts, remote addresses, and custom expr
 
 Both classes provide powerful route matching capabilities and can be chosen based on different needs. RadixTree is suitable for general path matching scenarios, while HttpRadixTree is more suitable for complex HTTP routing matching requirements.
 
+### findRoute (request fields)
+
+`HttpRadixTree.findRoute(req)` accepts a request object with the following fields:
+
+| Field        | Description                                                                                     |
+|--------------|-------------------------------------------------------------------------------------------------|
+| `path`       | Required. The request path to match.                                                             |
+| `method`     | Optional. The HTTP method. See [Matching Priority](#matching-priority) for omitted-method behavior. |
+| `headers`    | Optional. Request headers object. `headers.host` is used for `hosts` matching.                   |
+| `remoteAddr` | Optional. Client IP used for `remoteAddrs` matching.                                             |
+| `args`       | Optional. Query/body parameters exposed to `exprs`.                                              |
+
+Expression (`exprs`) variables are built from `args` and `headers`:
+
+- `args` keys are lowercased (e.g. `age`, `category`).
+- `headers` keys are lowercased and `-` is replaced with `_` (e.g. `user-agent` becomes `user_agent`, `x-id` becomes `x_id`).
+- Numeric-looking string values are coerced to numbers before evaluation.
+- `method` and `path` are always available as variables.
+
 [Back to TOC](#table-of-contents)
 
 # Examples
@@ -422,6 +492,13 @@ console.log(tree.findRoute({
 npm install rax-radix-tree
 ```
 
+This package contains a native addon that is compiled from source on install via `node-gyp`. Make sure the following build prerequisites are available:
+
+- Node.js >= 16 (N-API / `node-addon-api` v8)
+- A C/C++ toolchain: Python 3, `make`, and a compiler (Xcode Command Line Tools on macOS, `build-essential` on Debian/Ubuntu, or the Visual Studio Build Tools on Windows)
+
+> Note: no prebuilt binaries are published yet, so a compiler toolchain is required at install time. Contributions adding prebuilt binaries (e.g. via `prebuildify`) are welcome.
+
 
 # Benchmarks
 

package/http-radix-tree.js

@@ -8,28 +8,46 @@ function contains(str, substr) {
     return str.includes(substr)
 }
 
+// Strip an optional :port from a Host header value so that
+// `example.com:8080` matches a configured host of `example.com`.
+// Bracketed IPv6 (`[::1]` / `[::1]:8080`) is unwrapped to `::1`.
+function normalizeHost(host) {
+    if (!host) {
+        return host
+    }
+    if (host.charCodeAt(0) === 91 /* '[' */) {
+        const end = host.indexOf(']')
+        return end === -1 ? host : host.slice(1, end)
+    }
+    const colon = host.indexOf(':')
+    // Only strip when there is a single colon (IPv4 / domain + port);
+    // a bare IPv6 address has multiple colons and must be left intact.
+    if (colon !== -1 && host.indexOf(':', colon + 1) === -1) {
+        return host.slice(0, colon)
+    }
+    return host
+}
+
 function matchHosts(configHosts, requestHost) {
     if (!requestHost) {
         return false
     }
-    const matched = configHosts.some(host => {
-        if (host.startsWith('*.')) {
-            const domain = host.slice(2)
-            return requestHost.endsWith(domain)
+    const host = normalizeHost(requestHost)
+    const matched = configHosts.some(configHost => {
+        if (configHost.startsWith('*.')) {
+            // `*.example.com` matches the apex `example.com` and any
+            // subdomain such as `foo.example.com`, but requires a dot
+            // boundary so it does NOT match `badexample.com`.
+            const domain = configHost.slice(2) // "example.com"
+            return host === domain || host.endsWith('.' + domain)
         }
-        return host === requestHost
+        return configHost === host
     })
 
     return matched
 }
 
-const cache = new LRUCache({
-    ttl: 1000 * 60,
-    max: 10000
-});
-
-
-function matchRemoteAddrs(configAddrs, requestIp) {
+function matchRemoteAddrs(configAddrs, requestIp, cache) {
     if (!requestIp) {
         return false
     }
@@ -94,7 +112,7 @@ function matchExprs(compiledExprs, req) {
     return false
 }
 
-function httpMatchRoute(route, req) {
+function httpMatchRoute(route, req, cache) {
     // Check hosts
     const host = req.headers ? req.headers.host : ''
     if (route.hosts && route.hosts.length > 0 && !matchHosts(route.hosts, host)) {
@@ -103,7 +121,7 @@ function httpMatchRoute(route, req) {
 
     // Check remoteAddrs
     if (route.remoteAddrs && route.remoteAddrs.length > 0
-        && !matchRemoteAddrs(route.remoteAddrs, req.remoteAddr)) {
+        && !matchRemoteAddrs(route.remoteAddrs, req.remoteAddr, cache)) {
         return false
     }
 
@@ -143,7 +161,23 @@ class HttpRadixTree extends RadixTree {
             }));
             route.compiledExprs = compiledExprs;
         }
-        super(routes, httpMatchRoute);
+        // Per-instance remote-address match cache so that multiple trees do
+        // not share (and pollute) one another's cached results.
+        const remoteAddrCache = new LRUCache({
+            ttl: 1000 * 60,
+            max: 10000,
+        });
+        super(routes, (route, req) => httpMatchRoute(route, req, remoteAddrCache));
+    }
+
+    addRoute(route) {
+        route = Object.assign({}, route);
+        const exprs = route.exprs || [];
+        route.compiledExprs = exprs.map(expr => ({
+            expr,
+            compiledExpr: compileExpression(expr, {extraFunctions: {contains}}),
+        }));
+        return super.addRoute(route);
     }
 }
 

package/index.d.ts

@@ -0,0 +1,82 @@
+export type HttpMethod =
+    | 'GET'
+    | 'POST'
+    | 'PUT'
+    | 'DELETE'
+    | 'PATCH'
+    | 'HEAD'
+    | 'OPTIONS'
+    | 'CONNECT'
+    | 'TRACE'
+    | 'ALL';
+
+export interface Route {
+    /**
+     * Path patterns to match. Full match by default; a trailing `*` matches a
+     * single segment (no `/`), `**` matches anything, and a leading `**`/`*`
+     * performs suffix matching (e.g. `**.jpg`).
+     */
+    paths: string[];
+    /** HTTP methods to match. Defaults to `['ALL']` when omitted. */
+    methods?: HttpMethod[] | string[];
+    /** Arbitrary metadata returned on a match. */
+    meta?: unknown;
+    [key: string]: unknown;
+}
+
+export interface HttpRoute extends Route {
+    /** Host names to match. Supports `*.example.com` wildcards. */
+    hosts?: string[];
+    /** Remote addresses to match. Supports CIDR (IPv4 / IPv6). */
+    remoteAddrs?: string[];
+    /** filtrex expressions evaluated against request args/headers. */
+    exprs?: string[];
+}
+
+/** A route as returned by lookups: the original config plus parsed metadata. */
+export type MatchedRoute = Route & {
+    path: string;
+    [key: string]: unknown;
+};
+
+export interface RequestLike {
+    path: string;
+    method?: string;
+    [key: string]: unknown;
+}
+
+export interface HttpRequestLike extends RequestLike {
+    headers?: Record<string, string>;
+    remoteAddr?: string;
+    args?: Record<string, string | number>;
+}
+
+export type MatchFunction = (route: MatchedRoute, req: RequestLike) => boolean;
+
+export class RadixTree {
+    constructor(routes: Route[], matchFunc?: MatchFunction);
+
+    /**
+     * Find every route matching `path` (and, when provided, `method`).
+     * Results are ordered exact -> suffix -> prefix. When `method` is omitted
+     * or empty, method filtering is skipped and all routes may match.
+     */
+    findAllRoutes(path: string, method?: string): MatchedRoute[];
+
+    /** Find the first matching route for a request, or null. */
+    findRoute(req: RequestLike): MatchedRoute | null;
+
+    /** Dynamically add a route after construction. Returns `this`. */
+    addRoute(route: Route): this;
+
+    /** Remove all routes registered for `routePath`. Returns the count removed. */
+    removeRoute(routePath: string): number;
+}
+
+export class HttpRadixTree extends RadixTree {
+    constructor(routes: HttpRoute[]);
+
+    findRoute(req: HttpRequestLike): MatchedRoute | null;
+
+    addRoute(route: HttpRoute): this;
+}

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "rax-radix-tree",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "Node.js binding for rax, a radix tree implementation in ANSI C (https://github.com/antirez/rax)",
   "author": "igeeky.io@gmail.com",
   "license": "MIT",
   "main": "index.js",
+  "types": "index.d.ts",
   "scripts": {
     "install": "node-gyp rebuild",
     "test": "mocha ./test/*.test.js"

package/radix-tree.js

@@ -163,8 +163,9 @@ class RadixTree {
     _routeSimpleMatch(routeInfo, reqPath, method) {
         const { treePath, pattern, matchType } = routeInfo.pathInfo;
         const routeMethods = routeInfo.methods;
-        // Check method matching
-        if (!routeMethods.includes('ALL') && !routeMethods.includes(method)) {
+        // Check method matching. An empty/omitted request method matches any
+        // route regardless of its configured methods.
+        if (method && !routeMethods.includes('ALL') && !routeMethods.includes(method)) {
             return false;
         }
 
@@ -213,19 +214,16 @@ class RadixTree {
         // Suffix tree lookup logic
         if (this.suffixRouteCount > 0) {
             const reversePath = path.split('').reverse().join('');
-            const treeIt = this.suffixTree.search(reversePath);
-            if (treeIt) {
-                let idx;
-                while ((idx = treeIt.up()) !== -1) {
-                    if (idx >= this.routes.length) {
-                        console.error("Index out of range");
-                        break;
-                    }
-                    const routesArr = this.routes[idx];
-                    for (const route of routesArr) {
-                        if (this._routeSimpleMatch(route, reversePath, method)) {
-                            allRoutes.push(route);
-                        }
+            const indices = this.suffixTree.prefixMatch(reversePath);
+            for (const idx of indices) {
+                if (idx >= this.routes.length) {
+                    console.error("Index out of range");
+                    break;
+                }
+                const routesArr = this.routes[idx];
+                for (const route of routesArr) {
+                    if (this._routeSimpleMatch(route, reversePath, method)) {
+                        allRoutes.push(route);
                     }
                 }
             }
@@ -233,19 +231,16 @@ class RadixTree {
 
         // Prefix tree lookup logic
         if (this.prefixRouteCount > 0) {
-            const treeIt = this.prefixTree.search(path);
-            if (treeIt) {
-                let idx;
-                while ((idx = treeIt.up()) !== -1) {
-                    if (idx >= this.routes.length) {
-                        console.error("Index out of range");
-                        break;
-                    }
-                    const routesArr = this.routes[idx];
-                    for (const route of routesArr) {
-                        if (this._routeSimpleMatch(route, path, method)) {
-                            allRoutes.push(route);
-                        }
+            const indices = this.prefixTree.prefixMatch(path);
+            for (const idx of indices) {
+                if (idx >= this.routes.length) {
+                    console.error("Index out of range");
+                    break;
+                }
+                const routesArr = this.routes[idx];
+                for (const route of routesArr) {
+                    if (this._routeSimpleMatch(route, path, method)) {
+                        allRoutes.push(route);
                     }
                 }
             }
@@ -278,6 +273,79 @@ class RadixTree {
 
         return null;
     }
+
+    /**
+     * Dynamically add a single route configuration after construction.
+     * The route has the same shape as those passed to the constructor.
+     * @param {Object} route - A route configuration containing `paths`.
+     * @returns {RadixTree} this, for chaining.
+     */
+    addRoute(route) {
+        route = Object.assign({}, route);
+        const routePaths = route.paths;
+        delete route.paths;
+        for (const routePath of routePaths) {
+            this._initRoute(route, routePath);
+        }
+        this._sortAllRoutes();
+        return this;
+    }
+
+    /**
+     * Dynamically remove all routes registered for a given path pattern.
+     * The pattern must match one previously supplied in a route's `paths`
+     * (e.g. '/api/users', '/api/*', '**.jpg').
+     * @param {string} routePath - The path pattern to remove.
+     * @returns {number} The number of route entries removed.
+     */
+    removeRoute(routePath) {
+        const pathInfo = parsePath(routePath);
+        const treePath = pathInfo.treePath;
+
+        if (pathInfo.matchType === MATCH_TYPE_EQUALS) {
+            const index = this.equalsMap[treePath];
+            if (index === undefined) {
+                return 0;
+            }
+            const removed = this._pruneBucket(index, routePath);
+            this.equalsRouteCount -= removed;
+            if (this.routes[index] === undefined) {
+                delete this.equalsMap[treePath];
+            }
+            return removed;
+        }
+
+        const tree = pathInfo.matchType === MATCH_TYPE_SUFFIX ? this.suffixTree : this.prefixTree;
+        const index = tree.find(treePath);
+        if (index === null) {
+            return 0;
+        }
+        const removed = this._pruneBucket(index, routePath);
+        if (pathInfo.matchType === MATCH_TYPE_PREFIX) {
+            this.prefixRouteCount -= removed;
+        } else {
+            this.suffixRouteCount -= removed;
+        }
+        if (this.routes[index] === undefined) {
+            tree.remove(treePath);
+        }
+        return removed;
+    }
+
+    // Remove every routeInfo whose origin path equals `routePath` from the
+    // bucket at `index`. Empties the slot (set to undefined) when nothing is
+    // left; the index slot is intentionally never reused so existing indices
+    // stored in the radix trees / equalsMap stay valid.
+    _pruneBucket(index, routePath) {
+        const bucket = this.routes[index];
+        if (!bucket) {
+            return 0;
+        }
+        const kept = bucket.filter(r => r.path !== routePath);
+        const removed = bucket.length - kept.length;
+        this.routes[index] = kept.length === 0 ? undefined : kept;
+        return removed;
+    }
 };
 
 exports.parsePath = parsePath;

package/src/rax_wrapper.cpp

@@ -2,6 +2,7 @@
 #include <string>
 #include <iostream>
 #include <climits>
+#include <cstdlib>
 
 extern "C" {
 #include "radix_tree.h"
@@ -11,6 +12,7 @@ class RaxIterator : public Napi::ObjectWrap<RaxIterator> {
 public:
   static Napi::Object Init(Napi::Env env, Napi::Object exports);
   RaxIterator(const Napi::CallbackInfo& info);
+  ~RaxIterator();
 
 private:
   static Napi::FunctionReference constructor;
@@ -30,6 +32,7 @@ class RadixTree : public Napi::ObjectWrap<RadixTree> {
 public:
   static Napi::Object Init(Napi::Env env, Napi::Object exports);
   RadixTree(const Napi::CallbackInfo& info);
+  ~RadixTree();
 
 private:
   static Napi::FunctionReference constructor;
@@ -40,6 +43,7 @@ private:
   Napi::Value Remove(const Napi::CallbackInfo& info);
   Napi::Value Find(const Napi::CallbackInfo& info);
   Napi::Value Search(const Napi::CallbackInfo& info);
+  Napi::Value PrefixMatch(const Napi::CallbackInfo& info);
   void Cleanup(const Napi::CallbackInfo& info);
 };
 
@@ -81,6 +85,13 @@ RaxIterator::RaxIterator(const Napi::CallbackInfo& info) : Napi::ObjectWrap<RaxI
   this->path.len = pathStr.length();
 }
 
+RaxIterator::~RaxIterator() {
+  if (this->path.buf != nullptr) {
+    delete[] this->path.buf;
+    this->path.buf = nullptr;
+  }
+}
+
 Napi::Value RaxIterator::Next(const Napi::CallbackInfo& info) {
   Napi::Env env = info.Env();
   int result = raxtree_next(this->iterator, &this->path);
@@ -114,6 +125,7 @@ Napi::Object RadixTree::Init(Napi::Env env, Napi::Object exports) {
     InstanceMethod("remove", &RadixTree::Remove),
     InstanceMethod("find", &RadixTree::Find),
     InstanceMethod("search", &RadixTree::Search),
+    InstanceMethod("prefixMatch", &RadixTree::PrefixMatch),
     InstanceMethod("cleanup", &RadixTree::Cleanup),
   });
 
@@ -129,6 +141,18 @@ RadixTree::RadixTree(const Napi::CallbackInfo& info) : Napi::ObjectWrap<RadixTre
   this->treeIt = raxtree_new_it(this->tree);
 }
 
+RadixTree::~RadixTree() {
+  if (this->treeIt != nullptr) {
+    raxtree_stop(this->treeIt);
+    free(this->treeIt);
+    this->treeIt = nullptr;
+  }
+  if (this->tree != nullptr) {
+    raxtree_destroy(this->tree);
+    this->tree = nullptr;
+  }
+}
+
 Napi::Value RadixTree::Insert(const Napi::CallbackInfo& info) {
   Napi::Env env = info.Env();
   if (info.Length() < 2) {
@@ -225,9 +249,44 @@ Napi::Value RadixTree::Search(const Napi::CallbackInfo& info) {
   return iteratorInstance;
 }
 
+// PrefixMatch seeks the largest key <= `key` and walks up the tree collecting
+// the values (route indices) of every ancestor key that is a prefix of `key`.
+// Doing the whole walk natively avoids one JS<->C++ boundary crossing per
+// ancestor and avoids allocating an iterator wrapper object per lookup.
+Napi::Value RadixTree::PrefixMatch(const Napi::CallbackInfo& info) {
+  Napi::Env env = info.Env();
+  if (info.Length() < 1) {
+    Napi::TypeError::New(env, "Wrong number of arguments").ThrowAsJavaScriptException();
+    return env.Null();
+  }
+
+  std::string ele = info[0].As<Napi::String>().Utf8Value();
+  rt_str_t path;
+  path.buf = (unsigned char*)ele.c_str();
+  path.len = ele.length();
+
+  raxtree_search(this->tree, this->treeIt, &path);
+
+  Napi::Array result = Napi::Array::New(env);
+  uint32_t i = 0;
+  int idx;
+  while ((idx = raxtree_up(this->treeIt, &path)) != -1) {
+    result.Set(i++, Napi::Number::New(env, idx));
+  }
+
+  return result;
+}
+
 void RadixTree::Cleanup(const Napi::CallbackInfo& info) {
-  raxtree_stop(this->treeIt);
-  raxtree_destroy(this->tree);
+  if (this->treeIt != nullptr) {
+    raxtree_stop(this->treeIt);
+    free(this->treeIt);
+    this->treeIt = nullptr;
+  }
+  if (this->tree != nullptr) {
+    raxtree_destroy(this->tree);
+    this->tree = nullptr;
+  }
 }
 
 Napi::Object InitAll(Napi::Env env, Napi::Object exports) {

package/test/30.regressions.test.js

@@ -0,0 +1,140 @@
+const assert = require('assert');
+const { RadixTree, HttpRadixTree } = require('../index');
+
+describe('Regressions', function () {
+    describe('Wildcard host dot boundary', function () {
+        let tree;
+        beforeEach(function () {
+            const routes = [
+                { paths: ['/**'], meta: { id: 1 }, hosts: ['*.example.com'] },
+            ];
+            tree = new HttpRadixTree(routes);
+        });
+
+        it('should match a subdomain', function () {
+            const result = tree.findRoute({ path: '/', headers: { host: 'foo.example.com' } });
+            assert.notStrictEqual(result, null);
+            assert.strictEqual(result.meta.id, 1);
+        });
+
+        it('should match the apex domain', function () {
+            const result = tree.findRoute({ path: '/', headers: { host: 'example.com' } });
+            assert.notStrictEqual(result, null);
+            assert.strictEqual(result.meta.id, 1);
+        });
+
+        it('should NOT match a domain sharing the suffix without a dot boundary', function () {
+            const result = tree.findRoute({ path: '/', headers: { host: 'badexample.com' } });
+            assert.strictEqual(result, null);
+        });
+
+        it('should NOT match an unrelated domain that ends with the base', function () {
+            const result = tree.findRoute({ path: '/', headers: { host: 'notexample.com' } });
+            assert.strictEqual(result, null);
+        });
+    });
+
+    describe('Host header with port', function () {
+        let tree;
+        beforeEach(function () {
+            const routes = [
+                { paths: ['/**'], meta: { id: 1 }, hosts: ['example.com'] },
+                { paths: ['/**'], meta: { id: 2 }, hosts: ['*.example.com'] },
+            ];
+            tree = new HttpRadixTree(routes);
+        });
+
+        it('should match exact host when the request host carries a port', function () {
+            const result = tree.findRoute({ path: '/', headers: { host: 'example.com:8080' } });
+            assert.notStrictEqual(result, null);
+            assert.strictEqual(result.meta.id, 1);
+        });
+
+        it('should match wildcard host when the request host carries a port', function () {
+            const result = tree.findRoute({ path: '/', headers: { host: 'api.example.com:443' } });
+            assert.notStrictEqual(result, null);
+            assert.strictEqual(result.meta.id, 2);
+        });
+    });
+
+    describe('findAllRoutes with omitted method', function () {
+        let tree;
+        beforeEach(function () {
+            const routes = [
+                { paths: ['/api/x'], methods: ['POST'], meta: { id: 1 } },
+                { paths: ['/api/x'], methods: ['ALL'], meta: { id: 2 } },
+            ];
+            tree = new RadixTree(routes);
+        });
+
+        it('should match method-specific routes when method is omitted', function () {
+            const result = tree.findAllRoutes('/api/x');
+            assert.strictEqual(result.length, 2);
+            assert.deepStrictEqual(result.map(r => r.meta.id).sort(), [1, 2]);
+        });
+
+        it('should still filter by method when one is provided', function () {
+            const result = tree.findAllRoutes('/api/x', 'GET');
+            assert.strictEqual(result.length, 1);
+            assert.strictEqual(result[0].meta.id, 2);
+        });
+    });
+
+    describe('Dynamic addRoute / removeRoute', function () {
+        it('should add exact, prefix and suffix routes after construction', function () {
+            const tree = new RadixTree([]);
+            tree.addRoute({ paths: ['/api/users'], meta: { id: 1 } });
+            tree.addRoute({ paths: ['/api/posts/**'], meta: { id: 2 } });
+            tree.addRoute({ paths: ['**.jpg'], meta: { id: 3 } });
+
+            assert.strictEqual(tree.findAllRoutes('/api/users')[0].meta.id, 1);
+            assert.strictEqual(tree.findAllRoutes('/api/posts/2023/05')[0].meta.id, 2);
+            assert.strictEqual(tree.findAllRoutes('/img/a.jpg')[0].meta.id, 3);
+        });
+
+        it('should remove an exact route and report the count', function () {
+            const tree = new RadixTree([
+                { paths: ['/api/users'], meta: { id: 1 } },
+                { paths: ['/api/users'], meta: { id: 2 } },
+            ]);
+            assert.strictEqual(tree.findAllRoutes('/api/users').length, 2);
+            const removed = tree.removeRoute('/api/users');
+            assert.strictEqual(removed, 2);
+            assert.strictEqual(tree.findAllRoutes('/api/users').length, 0);
+        });
+
+        it('should remove a prefix route without affecting others', function () {
+            const tree = new RadixTree([
+                { paths: ['/api/*'], meta: { id: 1 } },
+                { paths: ['/api/**'], meta: { id: 2 } },
+            ]);
+            assert.strictEqual(tree.findAllRoutes('/api/x').length, 2);
+            assert.strictEqual(tree.removeRoute('/api/*'), 1);
+            const result = tree.findAllRoutes('/api/x');
+            assert.strictEqual(result.length, 1);
+            assert.strictEqual(result[0].meta.id, 2);
+        });
+
+        it('should remove a suffix route', function () {
+            const tree = new RadixTree([{ paths: ['**.jpg'], meta: { id: 1 } }]);
+            assert.strictEqual(tree.findAllRoutes('/a/b.jpg').length, 1);
+            assert.strictEqual(tree.removeRoute('**.jpg'), 1);
+            assert.strictEqual(tree.findAllRoutes('/a/b.jpg').length, 0);
+        });
+
+        it('should return 0 when removing an unknown path', function () {
+            const tree = new RadixTree([{ paths: ['/x'], meta: { id: 1 } }]);
+            assert.strictEqual(tree.removeRoute('/does/not/exist'), 0);
+        });
+
+        it('should support HttpRadixTree.addRoute with compiled exprs', function () {
+            const tree = new HttpRadixTree([]);
+            tree.addRoute({ paths: ['/p/**'], exprs: ['age >= 18'], meta: { id: 1 } });
+            const ok = tree.findRoute({ path: '/p/1', args: { age: '20' } });
+            assert.notStrictEqual(ok, null);
+            assert.strictEqual(ok.meta.id, 1);
+            const no = tree.findRoute({ path: '/p/1', args: { age: '10' } });
+            assert.strictEqual(no, null);
+        });
+    });
+});