[epic]pr() v2 #982

In coordination with @thomasp85

The current internals of plumber make design decisions very difficult to improve upon. This Issue is here to describe a "v2" version of a plumbed {plumber} file. The goal will be to opt-in to removing unexpected behaviors and integrate with external packages such as {routr}, {reqres}, and possibly {fiery}.

Use modern packages. Less is more!

Wants

• Opt-in to a v2 parser
  • This might possibly need to be done with a regex on the first line: (Ex: # plumber::::v2)
  • (Waiting for a route to be hit may be too late!)
• Middleware
  • Use roxygen2 to parse the block. (Use less home-grown solutions!)
  • Return Next to go on to the next route
  • via routr::RouteStack
    • Execution
      • A routr::Route (think current Plumber object) will match against the incoming request path.
      • If there is a match, the endpoint will execute
      • If the endpoint returns True, a response has been made.
      • {plumber} can wrap this to maintain it's current "return this object" behavior around the routr::Route endpoint
    • By default the current matching route for a plumber::filter is /**.
      • It would then easily fall back to the next matching route.
    • Starting with a ported plumber::filter object, we could easily add a stricter path assignment for middleware support!
• Add {promises} support to
  • routr::Route execution
  • {fiery}?
    • Static routes can easily be put into {httpuv} side return (big speed improvement!)
• OpenAPI
  • Requirement!
  • {routr} would need enhancements to support OpenAPI
  • {plumber} would construct the info. {routr} only orchestrates putting the pre-filled components together.
  • {plumber} needs ability to autogenerate and update/overwrite the returned OpenAPI value
• Parameter handling
  • Magic variables: req, res, body, query (list of query parameters), and any path variable (excluding the original 4)
    • Path variables are required
  • req and res will be from the {reqres} package.
  • body is the body object from req
  • query is a named list of character values
• Benefits of using
  • {reqres}
    • [Willing to add CORS]
    • Native multi serialization type support given the request accepts header
    • Native multi body parser support
    • Query parameters are lazily evaluated. Speed improvement!
  • {routr}
    • Route definition framework independent of the execution server
      • If {httpuv2} ever came out, we could easily update the server and not every route object
    • routr::RouteStack by definition supports middleware!
    • routr::RouteStack would allow for multiple "mounts" at the same location as the fallback routr::Route will be used (continuing in the stack until a hit is found)

Schedule

We have 3 months to work.

• Work <= 2 months on big swing features
• Give GitHub a month to test. Small features only!