Anatomy of a complex path

There's a lot of discussion about routing going around, and to help clarify it, I'm putting together this example of a complex-but-reasonable case for the set of determinations a Drupal 8 site may need to make in order to fully resolve to a single router. I'm hoping that such an example will help bound the discussion and allow us to tease apart the appropriate separation of concerns for the remaining challenges we face.

Currently, we have agreement that we should permit multiple routes per path, and that the routing system should be able to effectively select between them based on varying additional contextual information. We've further determined that that contextual information may be native HTTP protocol information as represented on the Request object, or that it may be secondary/derived information that is not directly present in the Request, but has been deduced from it.

The main routing patch, as of this writing, is pioneering a NestedMatcher approach, which essentially does the following:

1. Find all registered routes (a RouteCollection) that match the path in the Request
2. Iterate over a pluggable-through-DIC-compilation series of PartialMatchers, each of contains logic to disqualify routes based on some logic. Disqualified routes should be removed from the RouteCollection.
3. Pass whatever remains in the RouteCollection to a FinalMatcher, which makes the final determination about which route to select based on its own logic. The default is just to grab the first route from the list.

Some concerns about the NestedMatcher approach have been raised. They're part of the motivation for this discussion - by laying out the big picture, we can better figure out whether the approach is, indeed, problematically non-deterministic.

node/{node} (simplified)

If we're looking for a complex case, node/{node} is the obvious choice. So let's look at that, and let's start by pretending that each route could only conceivably serve a single MIME type.

I've emphasized where these cases are likely to be created, as that influences the manner in which we can construct logic to satisfy the case.

• text/html - most of what Drupal does, and the type where all the Scotch/Panels-y stuff will do its thing.
  • Catchall - has no further conditionality beyond wanting text/html and rendering a node. This'll be the standard route core provides to handle the rendering of nodes.
  • For nodes of type 'Product' - say that a contrib module provides their own bundle called Product, and they want it to ship with some funky special route in order to provide a different set of blocks for the page. More on that later.
  • For nodes created in the last week - this is more of an site or distro builder, business logic-type conditional. thus, it would probably not be manually coded. This may not merit its own route.
• application/ld+json - with all the discussion about using JSON-LD, this only makes sense to include.
  • Catchall - core-provided, this would map to a controller with the default behavior for representing a node in JSON-LD.
  • For nodes of type 'Article' - probably contrib-provided for some special use case, IF it exists at all. Which I think it probably shouldn't - per-node-type dynamism should be achieved via logic contained within the controller, and has no reason to live at the route level.

(Please feel free to edit & add more)

The key point here is why the text/html variants merit routes, whereas the JSON-LD behavioral variation typically ought to be performed beneath the controller: in order to make Scotch/Panelsy controllers work, we need something to hang configuration (block placement & styling, caching, etc.) on. Maybe more importantly, we need to know the sort of Request that will cause that configuration to be used. That's an essential prerequisite as it's the only way for us to be able to perform cross-"panel" operations - e.g., making the decision at admin/structure/blocks that we want to add the 'Navigation' block to all right sidebars. Since we aren't injecting such blocks at runtime (doing so would undermine theming consistency, destroy the guarantee of accurate caching, and potentially have access control problems), the decisions made at that global level have to be injected into the configuration for each individual "panel." And the best way to determine which of the "panels" need configuration injected is to use the routing/matching system itself: mock a Request object and see which routes come back that match its criteria. So, if we were to move the conditionalized/variant selection logic anywhere below the route level, we would be less if at all able to reuse the existing routing system to make the determinations.

Accept, Content-Type, and mod_negotiation

Unfortunately, content negotiation is hardly so simple as the above list suggests. Browsers tend to send Accept headers that look more like this:

Accept:text/html,application/xhtml+xml,application/xml;q=0.9,/;q=0.8

Sooo, yeah, that's a whole stack of stuff to match against. With respect to doing the resolving, I agree with what Larry's said elsewhere already: it'd be great to follow on the heels of Apache mod_negotation for this, perhaps with a library like BadFaith...though it seems that progress on that has stalled. In any case, we still have to figure out what the best practices will be for designating the MIME type of the Response a given route is capable of producing. The Symfony\Component\HttpFoundation\Response class has some basic logic in it already: if the controller fails to explicitly set the Content-Type header, then it first attempts to set Content-Type based on the Accept header of the Request, and if that fails, then it simply defaults to text/html. That's fine, but will hopefully rarely happen, as I'm hoping the route building system will ensure some value is always given Content-Type on routes declared via hook_route_info(). That'll ensure we can filter them out effectively during routing.

There's a question hanging in the air, though: does it make more sense to have multiple routes differentiated by Content-Type, or should there be a single route with a controller that is capable of reading the Request's Accept header and responding accordingly? I don't think there's one answer; we need to take it case-by-case. That said, I do think that the Panelsy controller for text/html would be ill-served by trying to do double-duty, and should really just stick to the one MIME type.

HTTP methods and other headers

mod_negotation takes care of the Accept, Accept-Language, Accept-Charset and Accept-Encoding headers, but there are still others. Most likely to act as differentiating dimensions in the routing system are probably User-Agent, Referer, and maybe TE or Authorization. The various HTTP methods are also ripe candidates for differentiation.

These dimensions are all orthogonal to one another, which can make the resolving process somewhat complex. However, they also have externally defined ranges that are not especially subject to change. So while they may be multidimensional, they are at least non-arbitrary in the data they look at, which means we can (and should) define strategies around matching, fallbacks, and some form of wildcarding for each. This does seem to be a good case for the NestedMatcher approach, as we can stack up PartialMatchers for each of the dimensions in whatever order we determine to make the most sense (and maybe also only compile those matchers into the container if something actually needs them), and they can operate in their domains across a set of known ranges without stepping on each others' toes.

Controller resolution

Work on controllers, and the practical implications of this, is happening at http://drupal.org/node/1812720.