feat(event-handler): implement route matching & resolution system for rest handler

[svozza]

Summary

Implements the route matching and resolution system by following the pattern of the appsync-event handler and centralising the resolution logic in the RouteHandlerRegistry. This different from the proposed solution in #4140, which envisioned multiple classes involved in the routing and matching logic. This design is simpler and has less moving parts.

Changes

• RouteHandlerRegistry
  • Changes the internal representation of the registry to contain registries for static and dynamic routes. The register function is responsible for deciding which goes where.
  • Added a method to determine the specificity of dynamic routes: routes with fewer parameters and more path segments are considered more specific.
  • When routes are added to the dynamic routes array, the addition is done in a way to ensure the array stays sorted in ascending order of specificity, i.e., the most specific route will be the first element etc. Doing so removes the need for the refresh method proposed that would have been called each time a route was added. This is also done in the register method.
  • The resolve method takes a HTTP method and a path
    • first we check the static route registry to find the handler
    • if that fails we check the dynamic registry, if we find a matching handler we extract any parameters from the path, parse and validate them, and return the handler, the parsed parameters and the raw parameters.
    • if that fails we return null.
• We have added two new functions to the utils module, although I am leaning towards moving them to be private methods in the RouteHandlerRegistry class as I don't think they're going to be used anywhere else:
  • processParams, which URL decodes any parameters in the path
  • validateParams, which throws a validation error if the parameters have invalid values
• Added unit tests with particular focus on ensuring the correctness of the specificity sorting. Note: the diff of the test file is so larger that GitHub automatically hides it.

Note

There was one part of the initial implementation that I wasn't able to incorporate. There was a recursive type that was defined but it was never used anywhere so I wasn't sure what to do with it:

type ExtractParams<T extends string> = 
  T extends `${infer Start}:${infer Param}/${infer Rest}`
    ? { [K in Param]: string } & ExtractParams<`${Start}${Rest}`>
    : T extends `${infer Start}:${infer Param}`
    ? { [K in Param]: string }
    : {};

Issue number: closes #4140

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

Disclaimer: We value your time and bandwidth. As such, any pull requests created on non-triaged issues might not be successful.

[dreamorosi]

Amazing work here, especially with the deep dive in time complexity and optimization.

The code looks good even though I haven't tested it in a function, I think for now we can merge it and progress - either way we'll have a team bug bash when we're near the release.

The only thing potentially missing, which I am ok to tackle in a separate issue is type safety.

The linked issue had an ugly recursive type (which I could swear I saw a question from you about but can't find anymore) that basically aimed at giving the experience described in the RFC in the section "Dynamic routes" which would allow you to do this in the route handler:

As I said, I'm ok to work on this separately and in the near future - I have a local PoC with this working (in terms of types) that I made over a year ago when I was working on the RFC, so we can potentially take some inspiration there.

[svozza]

The only thing potentially missing, which I am ok to tackle in a separate issue is type safety.

The linked issue had an ugly recursive type (which I could swear I saw a question from you about but can't find anymore) that basically aimed at giving the experience described in the #3500 in the section "Dynamic routes" which would allow you to do this in the route handler:

Yeah, I mentioned that recursive type in the PR body at the top, I wasn't sure what to do with it. That autocomplete use case is so nice, defo something we want! But agreed we can tackle it in a separate PR, this one is big enough as it is.

[dreamorosi]

Thanks for working on this!

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
6.7% Duplication on New Code

See analysis details on SonarQube Cloud