Add a more ergonomic API around path segment matching

[citizennet]

Add a more ergonomic API around path segment matching

[cprussin]

Folks, the feedback here is really helpful, thank you both for leaving those opinions @akheron and @paluh . You guys have convinced me, there are enough tools out there that can be used and the simplicity of HTTPure is valuable. I'll close this ticket as something that doesn't need to happen.

I do think before we go to 1.0 it would be nice to do a better job documenting some common patterns around routing, such as the array pattern matching approach, and using tools like the ones you listed @paluh . I'll add a note in #106 to remember to do that.

Thanks again all!

[cprussin]

@akheron I've put a lot of thought into this issue, I'm not quite convinced on the proposed solution and would love to get feedback/ideas, so if you have any to give, it would be much appreciated!

[akheron]

I've used array pattern matching to accomplish good ergonomics, and I think it's the way to go. It solves matching the path and capturing parameters at the same time.

Matching path only:

router { path } =
  case path of
    ["todos", id] -> readTodo id
    ["todos"] -> listTodos
    [] -> frontPage
    _ -> HTTPure.notFound

Matching path and method:

router { method, path } =
  handle method path
  where
    handle HTTPure.Get ["todos", id] -> readTodo id
    handle HTTPure.Put ["todos", id] -> updateTodo id
    handle HTTPure.Get [] -> frontPage
    handle _ [] -> HTTPure.methodNotAllowed
    handle _ _ -> HTTPure.notFound

[cprussin]

That's what I was originally leaning towards, but I started thinking more along the lines of the express API, because working on array pattern matching is somewhat limited in a few ways. Specifically:

1. We can't match on specific ID shapes (/todos/\d{4}-\d{6}--contrived but a lot of use cases do build IDs that have specific shapes).
2. We can't deal in variable-length segments. For instance, in Express, you could match something like (/:locale:)?/todos/:id.
3. Doing anything involving requiring regexes immediately becomes a non-ergonomic API.

I'm not entirely convinced these 3 are significant problems--they all have workarounds, and it may be cleaner to defer to the workarounds than to move away from PS language features.

For 1., the workaround is just to match on any shape and check the shape in the route handler. I just don't love that, because it means that some aspects of routing are moved out of the router, but it works. For 2, you just have to have two different matches, one for each case--not a huge deal. 3 is a gross API, but totally doable--and perhaps not something we should cater towards, since HTTPure I think should make everything possible, but should make good things easy, and I can't think of a case where complex regex path matching would ever be a good thing.

So I guess the question is, at this time, do you feel that any of these 3 are significant enough limitations (or that the workarounds are gross enough) to be worth catering solutions?

[cprussin]

Oh, and one other problem with array pattern matching: you can't do case-insensitive matches. That isn't a big issue for something like a REST API, but it's a non-starter for something that serves, e.g., a UI, where addresses are entered by users into address bars in browsers. HTTPure should be able to cater to both use cases. I don't know of any good workaround here, other than making all routes use regexes, which gets back into the gross ergonomics situation.

[akheron]

The thing I like most in HTTPure is that the serve takes a function that processes all requests. The user is free to implement routing, request handlers, middleware etc. in any way he sees fit. However, providing helpers for common use cases (e.g. routing) would be a big plus, so that each user doesn't have to reinvent the wheel.

I suggest figuring out the best way to create composable routers, which could then be used for different purposes. If the user wants regex route matching, it could be used while also using plain array pattern matching or simple prefix matching for other purposes.

In purescript-httpure-rest-router I approached the problem like this: https://github.com/cprussin/purescript-httpure-rest-router/blob/f8883ba2cc95646ead3933ec7bce8a12b9fc6b90/examples/Todo.purs#L105-L119

The only problem with those arrays of routes and making a router function using Router.router is that routers made like this are not composable, i.e. the router always returns a response even though none of the routes matches (falling back to 404).

PS. Case-insitive matching could be accomplished by e.g. converting the path of some or all requests to lowercase in a middleware function.

[paluh]

Hi,

I'm not sure if I should add any comments as I'm not a contributor but barely a user (we have just started to build a service around httpure)... but anyway here are my two cents:

I really like clean API which is provided by this framework and I think that advanced/opinionated routing options should be delegated to external libraries like: purescript-httpure-rest-router, purescript-routing, purescript-routing-duplex, purescript-boomboom, purescript-boomerang or some other (maybe "contrib") proposition.
Routing can be done in different ways and with different focus in mind. If you are building API you can lean toward performance and simplicity and don't need bidirectional routes, if you are implementing a web service you probably don't want to hard code any urls in your HTMLs and want some automatic serialization for your typed routes etc.

I think that your path representation as just an array of segments is nearly ideal as it is lightweight, covers really simple scenarios and can be base for integration with any other more advanced routing option...

Thanks for your work on httpure!