Add support for user-defined server routes

[rpkyle]

This PR proposes to address #131, in order that Dash for R users may be able to create and modify routes as is currently possible in Dash for Python, thanks to Flask's customizable routing. Fiery supports routing "plugins", but it can be complicated to use them, or modify routes that already exist (see below). Two new methods are proposed in Dash for R:

• server_route: this method registers a new URL rule, as described by its methods, url and handler function
• redirect: this method can be used to redirect a path (single, or parameterized/with wildcards) to another path, as the handler is specified internally and returns a 301 (Moved Permanently) status within the response

Since Dash for R lacks the support for decorator methods that Python provides, the handler argument allows matching a handler function with a URL to be routed. In brief, the server_route method registers the URL routing information via self$server$set_data("user-routes"). Upon invoking app$run_server, Dash checks whether any user-routes are defined; if one or more routes exists, a plugin is generated on the fly, to insert all the routes in the order they were defined. Finally, the plugin is attached to the running server object. This process is repeated when the server shuts down/is aborted and restarted. The routing information remains intact, as it was stored via set_data.

The proposed changes are a compromise between making the code succinct and continuing to take advantage of routr features, while making it easier for users to add/remove routes and find documentation for this feature generally.

---

Previous interface

... #code specifying packages, layout, callbacks omitted

plugin <- list(
  on_attach = function(server) {
    router <- server$plugins$request_routr
    route <- routr::Route$new()
    redirect_getting_started <- function(request, response, keys, ...) {
      response$status <- 301L
      response$set_header('Location', '/layout')
      TRUE
    }
    redirect_state <- function(request, response, keys, ...) {
      response$status <- 301L
      response$set_header('Location', '/basic-callbacks')
      TRUE
    }
    route$add_handler('get', '/getting-started', redirect_getting_started)
    route$add_handler('get', '/getting-started-part-2', redirect_state)
    route$add_handler('get', '/state', redirect_state)
    router$add_route(route, "redirects")
  },
  name = 'redirect_urls',
  require = 'request_routr'
)

app$server$attach(plugin)
app$run_server()

Proposed interface

... #code specifying packages, layout, callbacks omitted

app$server_route("/getting-started", function(request, response, keys, ...) {
  response$status <- 301L
  response$set_header('Location', '/layout')
  TRUE
})

app$server_route("/getting-started-part-2", function(request, response, keys, ...) {
  response$status <- 301L
  response$set_header('Location', '/basic-callbacks')
  TRUE
})

app$server_route("/state", function(request, response, keys, ...) {
  response$status <- 301L
  response$set_header('Location', '/basic-callbacks')
  TRUE
})

app$run_server()

The redirect method provides a simplification of the above:

app$redirect("/getting-started", "/layout")
app$redirect("/getting-started-part-2", "/basic-callbacks")
app$redirect("/state", "/basic-callbacks")

To do:

• tests to validate adding routes, resulting HTTP status codes and redirects (as applicable)
• provide sufficient documentation and simplify syntax, ensure example is provided
• update CHANGELOG.md
• allow developers to pass in a function when using app$redirect in lieu of a string for the new_path argument, which would be evaluated as a string within app$redirect's internal handler

[alexcjohnson]

This looks great - much nicer than the existing interface. I'm not sure about the utility of show_routes and remove_routes vs just documenting (or exposing some other way) app$server$get_data("user-routes") and letting users inspect or modify it directly.

Redirects seem to be a primary use case here, so we may as well make them even easier:

app$redirect("/getting-started", "/layout")

I notice in dash-docs we also have some parametrized redirects - in as far as these are simply replacing the head of the path and keeping the tail intact there may be some syntax we could use like:

app$redirect("/getting-started/*", "/layout/*")

[rpkyle]

This looks great - much nicer than the existing interface. I'm not sure about the utility of show_routes and remove_routes vs just documenting (or exposing some other way) app$server$get_data("user-routes") and letting users inspect or modify it directly.

OK, show_routes and remove_routes 🔪 in df49e5c

I have added a note on the usage of app$server$get_data("user-routes") and app$server$set_data("user-routes", list()) since the convenience functions have been removed.

[rpkyle]

@alexcjohnson I did change the terminology in this feature to use path rather than url, as the former is both more technically correct and also matches the usage in routr, reqres, etc.

[rpkyle]

Redirects seem to be a primary use case here, so we may as well make them even easier:
app$redirect("/getting-started", "/layout")

added in 8ced8ff

I notice in dash-docs we also have some parametrized redirects - in as far as these are simply replacing the head of the path and keeping the tail intact there may be some syntax we could use like:
app$redirect("/getting-started/*", "/layout/*")

I think the parameterized redirects you describe are already supported by routr (in fact we've used them in Dash for R already, right here):

https://github.com/thomasp85/routr/blob/ca37cc8c57ee644966fbba2cacd40646b9bcf2bd/R/route.R#L8-L15

I went ahead and added some examples to demonstrate this functionality within the online help, though.

@alexcjohnson Whoops, 🙈 I accidentally edited your comment instead of mine. I managed to restore it, I think, so hopefully the flow makes sense again.

[alexcjohnson]

Could possibly 🌴 a little more by calling self$server_route here?

[rpkyle]

@alexcjohnson Definitely, not sure why I didn't think of that but your suggestions have really helped to clean up the implementation. app$redirect is looking nice and lean now.

[alexcjohnson]

Excellent! Just one minor comment, this looks great. 💃