Implement partial matching of routes (#142)

ptoffy · gwynne · web-flow · commit c49a866c7a09 · 2025-10-27T12:19:11.000+01:00
* Implement partial matching * Attempt at making it fast * Cleanup * Undo * Partial Matching 2 (#143) * Different approach to partial matching * Nits * Avoid a copy * Minor improvements * Nit * Update Sources/RoutingKit/PathComponent.swift Co-authored-by: Gwynne Raskind <gwynne@vapor.codes> * Update Sources/RoutingKit/TrieRouter/TrieRouterNode.swift Co-authored-by: Gwynne Raskind <gwynne@vapor.codes> * Nits * Nit --------- Co-authored-by: Gwynne Raskind <gwynne@vapor.codes>
diff --git a/Package.swift b/Package.swift
@@ -13,13 +13,15 @@ let package = Package(
         .library(name: "RoutingKit", targets: ["RoutingKit"])
     ],
     dependencies: [
-        .package(url: "https://github.com/apple/swift-log.git", from: "1.6.4")
+        .package(url: "https://github.com/apple/swift-log.git", from: "1.6.4"),
+        .package(url: "https://github.com/apple/swift-algorithms.git", from: "1.2.1"),
     ],
     targets: [
         .target(
             name: "RoutingKit",
             dependencies: [
-                .product(name: "Logging", package: "swift-log")
+                .product(name: "Logging", package: "swift-log"),
+                .product(name: "Algorithms", package: "swift-algorithms"),
             ],
             swiftSettings: swiftSettings
         ),
diff --git a/Sources/RoutingKit/PathComponent.swift b/Sources/RoutingKit/PathComponent.swift
@@ -1,3 +1,5 @@
+import Algorithms
+
 /// A single path component of a `Route`. An array of these components describes
 /// a route's path, including which parts are constant and which parts are dynamic.
 public enum PathComponent: ExpressibleByStringInterpolation, CustomStringConvertible, Sendable, Hashable {
@@ -12,6 +14,7 @@ public enum PathComponent: ExpressibleByStringInterpolation, CustomStringConvert
     /// Represented as `:` followed by the identifier.
     case parameter(String)
 
+    case partialParameter(template: String, components: [Substring], parameters: [Substring])
     /// A dynamic parameter component with discarded value.
     ///
     /// Represented as `*`
@@ -30,7 +33,31 @@ public enum PathComponent: ExpressibleByStringInterpolation, CustomStringConvert
 
     // See `ExpressibleByStringLiteral.init(stringLiteral:)`.
     public init(stringLiteral value: String) {
-        if value.hasPrefix(":") {
+        if value.firstIndex(of: "{") != nil {
+            var components: [Substring] = []
+            var parameters: [Substring] = []
+
+            var inBraces = false
+
+            for (index, char) in value.dropFirst().indexed() {
+                switch char {
+                case "{":
+                    inBraces = true
+                    parameters.append("")
+                    components.append("")
+                case "}":
+                    inBraces = false
+                    if index < value.index(before: value.endIndex) { components.append("") }
+                default:
+                    if inBraces {
+                        parameters[parameters.index(before: parameters.endIndex)].append(char)
+                    } else {
+                        components[components.index(before: components.endIndex)].append(char)
+                    }
+                }
+            }
+            self = .partialParameter(template: .init(value.dropFirst()), components: components, parameters: parameters)
+        } else if value.starts(with: ":") {
             self = .parameter(.init(value.dropFirst()))
         } else if value == "*" {
             self = .anything
@@ -44,14 +71,11 @@ public enum PathComponent: ExpressibleByStringInterpolation, CustomStringConvert
     // See `CustomStringConvertible.description`.
     public var description: String {
         switch self {
-        case .anything:
-            return "*"
-        case .catchall:
-            return "**"
-        case .parameter(let name):
-            return ":" + name
-        case .constant(let constant):
-            return constant
+        case .anything: "*"
+        case .catchall: "**"
+        case .parameter(let name): ":" + name
+        case .constant(let constant): constant
+        case .partialParameter(let template, _, _): template
         }
     }
 }
diff --git a/Sources/RoutingKit/TrieRouter/TrieRouter.swift b/Sources/RoutingKit/TrieRouter/TrieRouter.swift
@@ -1,3 +1,5 @@
+public import Algorithms
+import Foundation
 import Logging
 
 /// Generic ``TrieRouter`` built using the "trie" tree algorithm.
@@ -37,29 +39,22 @@ public final class TrieRouter<Output: Sendable>: Router, Sendable, CustomStringC
     ///   - path: Raw path segments.
     ///   - parameters: Will collect dynamic parameter values.
     /// - Returns: Output of matching route, if found.
-    @inlinable public func route(path: [String], parameters: inout Parameters) -> Output? {
-        // always start at the root node
+    @inlinable
+    public func route(path: [String], parameters: inout Parameters) -> Output? {
         var currentNode = self.root
-
         let isCaseInsensitive = self.options.contains(.caseInsensitive)
-
         var currentCatchall: (Node, [String])?
 
-        // traverse the string path supplied
-        search: for (index, slice) in path.enumerated() {
-            // store catchall in case search hits dead end
+        search: for (index, slice) in path.indexed() {
             if let catchall = currentNode.catchall {
                 currentCatchall = (catchall, [String](path.dropFirst(index)))
             }
 
-            // check the constants first
             if let constant = currentNode.constants[isCaseInsensitive ? slice.lowercased() : slice] {
                 currentNode = constant
                 continue search
             }
 
-            // no constants matched, check for dynamic members
-            // including parameters or anythings
             if let wildcard = currentNode.wildcard {
                 if let name = wildcard.parameter {
                     parameters.set(name, to: slice)
@@ -69,9 +64,19 @@ public final class TrieRouter<Output: Sendable>: Router, Sendable, CustomStringC
                 continue search
             }
 
-            // no matches, stop searching
+            if let partials = currentNode.partials, !partials.isEmpty {
+                for partial in partials {
+                    if let captures = isMatchForPartial(partial: partial, path: slice, parameters: parameters) {
+                        for (name, value) in captures {
+                            parameters.set(String(name), to: String(value))
+                        }
+                        currentNode = partial.node
+                        continue search
+                    }
+                }
+            }
+
             if let (catchall, subpaths) = currentCatchall {
-                // fallback to catchall output if we have one
                 parameters.setCatchall(matched: subpaths)
                 return catchall.output
             } else {
@@ -80,14 +85,11 @@ public final class TrieRouter<Output: Sendable>: Router, Sendable, CustomStringC
         }
 
         if let output = currentNode.output {
-            // return the currently resolved responder if there hasn't been an early exit.
             return output
         } else if let (catchall, subpaths) = currentCatchall {
-            // fallback to catchall output if we have one
             parameters.setCatchall(matched: subpaths)
             return catchall.output
         } else {
-            // current node has no output and there was not catchall
             return nil
         }
     }
@@ -96,4 +98,46 @@ public final class TrieRouter<Output: Sendable>: Router, Sendable, CustomStringC
     public var description: String {
         self.root.description
     }
+
+    @usableFromInline
+    func isMatchForPartial(partial: Node.PartialMatch, path: String, parameters: Parameters) -> [Substring: Substring]? {
+        var result: [Substring: Substring] = [:]
+        var index = path.startIndex
+
+        var componentIndex = partial.components.startIndex
+        let lastComponentIndex = partial.components.index(before: partial.components.endIndex)
+
+        while componentIndex <= lastComponentIndex {
+            if index >= path.endIndex {
+                // If we're at the end but there are more components, fail
+                if componentIndex < lastComponentIndex { return nil }
+                break
+            }
+
+            let element = partial.components[componentIndex]
+
+            if element.isEmpty {
+                let endIndex: String.Index
+                if componentIndex < lastComponentIndex {
+                    let nextElement = partial.components[partial.components.index(after: componentIndex)]
+                    // greedy matching
+                    guard let range = path.range(of: nextElement, options: .backwards, range: index..<path.endIndex) else { return nil }
+                    endIndex = range.lowerBound
+                } else {
+                    endIndex = path.endIndex
+                }
+                result[partial.parameters[result.count]] = path[index..<endIndex]
+                index = endIndex
+            } else {
+                // Verify the literal matches at current position
+                let substring = path[index...].prefix(element.count)
+                guard substring == element else { return nil }
+                index = substring.endIndex
+            }
+
+            partial.components.formIndex(after: &componentIndex)
+        }
+
+        return result
+    }
 }
diff --git a/Sources/RoutingKit/TrieRouter/TrieRouterBuilder.swift b/Sources/RoutingKit/TrieRouter/TrieRouterBuilder.swift
@@ -125,6 +125,12 @@ public struct TrieRouterBuilder<Output: Sendable>: RouterBuilder {
                 explicitlyIncludesAnything: true
             )
             return node.copyWith(wildcard: newWildcard)
+        case .partialParameter(let template, let components, let parameters):
+            var partials = node.partials ?? []
+            let child = partials.first(where: { $0.template == template })?.node ?? Node()
+            let updatedChild = insertRoute(node: child, path: path.dropFirst(), output: output)
+            partials.append(.init(template: template, components: components, parameters: parameters, node: updatedChild))
+            return node.copyWith(partials: partials)
         }
     }
 }
diff --git a/Sources/RoutingKit/TrieRouter/TrieRouterNode.swift b/Sources/RoutingKit/TrieRouter/TrieRouterNode.swift
@@ -40,14 +40,33 @@ final class TrieRouterNode<Output: Sendable>: Sendable, CustomStringConvertible
         }
     }
 
+    @usableFromInline
+    struct PartialMatch: Sendable {
+        @usableFromInline
+        let template: String
+
+        @usableFromInline
+        let components: [Substring]
+
+        @usableFromInline
+        let parameters: [Substring]
+
+        @usableFromInline
+        let node: TrieRouterNode
+    }
+
     /// All constant child nodes.
     @usableFromInline
     let constants: [String: TrieRouterNode]
 
-    /// Wildcard child node that may be a named parameter or an anything
+    /// Wildcard child node that may be a named parameter or an anything.
     @usableFromInline
     let wildcard: Wildcard?
 
+    /// Partial match child nodes.
+    @usableFromInline
+    let partials: [PartialMatch]?
+
     /// Catchall node, if one exists.
     /// This node should not have any child nodes.
     @usableFromInline
@@ -58,11 +77,18 @@ final class TrieRouterNode<Output: Sendable>: Sendable, CustomStringConvertible
     let output: Output?
 
     /// Creates a new ``TrieRouterNode``.
-    init(output: Output? = nil, constants: [String: TrieRouterNode] = [:], wildcard: Wildcard? = nil, catchall: TrieRouterNode? = nil) {
+    init(
+        output: Output? = nil,
+        constants: [String: TrieRouterNode] = [:],
+        wildcard: Wildcard? = nil,
+        catchall: TrieRouterNode? = nil,
+        partials: [PartialMatch]? = nil
+    ) {
         self.output = output
         self.constants = constants
         self.wildcard = wildcard
         self.catchall = catchall
+        self.partials = partials
     }
 
     @usableFromInline
@@ -89,6 +115,11 @@ final class TrieRouterNode<Output: Sendable>: Sendable, CustomStringConvertible
             }
         }
 
+        for partial in self.partials ?? [] {
+            desc.append("→ \(partial.template)")
+            desc += partial.node.subpathDescriptions.indented()
+        }
+
         if self.catchall != nil {
             desc.append("→ **")
         }
@@ -99,13 +130,15 @@ final class TrieRouterNode<Output: Sendable>: Sendable, CustomStringConvertible
         output: Output? = nil,
         constants: [String: TrieRouterNode]? = nil,
         wildcard: Wildcard? = nil,
-        catchall: TrieRouterNode? = nil
+        catchall: TrieRouterNode? = nil,
+        partials: [PartialMatch]? = nil
     ) -> TrieRouterNode {
         TrieRouterNode(
             output: output ?? self.output,
             constants: constants ?? self.constants,
             wildcard: wildcard ?? self.wildcard,
-            catchall: catchall ?? self.catchall
+            catchall: catchall ?? self.catchall,
+            partials: partials ?? self.partials
         )
     }
 }
diff --git a/Tests/RoutingKitTests/RouterTests.swift b/Tests/RoutingKitTests/RouterTests.swift
@@ -309,4 +309,25 @@ struct RouterTests {
         #expect(Set(params3.allNames) == ["bar"])
         #expect(params3.getCatchall() == ["bam"])
     }
+
+    @Test func testPartial() throws {
+        var routerBuilder = TrieRouterBuilder<Int>()
+        routerBuilder.register(42, at: ["test", ":{my-file}.json"])
+        routerBuilder.register(41, at: ["test", ":{my}-test-{file}.{extension}"])
+
+        let router = routerBuilder.build()
+
+        var params = Parameters()
+        #expect(router.route(path: ["test", "report.json"], parameters: &params) == 42)
+        #expect(params.get("my-file") == "report")
+
+        #expect(router.route(path: ["test", ".json.json"], parameters: &params) == 42)
+        #expect(params.get("my-file") == ".json")
+
+        params = Parameters()
+        #expect(router.route(path: ["test", "foo-test-bar.txt"], parameters: &params) == 41)
+        #expect(params.get("my") == "foo")
+        #expect(params.get("file") == "bar")
+        #expect(params.get("extension") == "txt")
+    }
 }

Original file line number	Diff line number	Diff line change
`@@ -125,6 +125,12 @@ public struct TrieRouterBuilder<Output: Sendable>: RouterBuilder {`
`125`	`125`	`explicitlyIncludesAnything: true`
`126`	`126`	`)`
`127`	`127`	`return node.copyWith(wildcard: newWildcard)`
	`128`	`+ case .partialParameter(let template, let components, let parameters):`
	`129`	`+ var partials = node.partials ?? []`
	`130`	`+ let child = partials.first(where: { $0.template == template })?.node ?? Node()`
	`131`	`+ let updatedChild = insertRoute(node: child, path: path.dropFirst(), output: output)`
	`132`	`+ partials.append(.init(template: template, components: components, parameters: parameters, node: updatedChild))`
	`133`	`+ return node.copyWith(partials: partials)`
`128`	`134`	`}`
`129`	`135`	`}`
`130`	`136`	`}`