Document aliases

[carlosmunoz]

This change presents a more elegant approach to document access.

It introduces a "document alias" node type which when viewed is able to render the json or html content for any Document object in the system.

This effectively creates a vanity url system that can be shaped in any way for callers to access the json or preview representations of the content.

[benradey]

Capturing my early thoughts here that I would like to have some discussion around...

• Rather than create nodes that are named the same as the product and version (example, /content/documentation/rhel/8/coolDoc [speaking of which, I forgot, is locale accounted for here? Do we even want the same vanities/redirects for locales??]), let's consider how we can use those nodes to "point at" the real product and version, so things like product renames might automatically carry over to vanity URLs as well (assuming that is a feature that we want). So, our node structure might look more like /content/documentation/abcd1234-5678.../wxyz9876-5432.../coolDoc.
• I like the idea of having a special resource type for pantheon/alias for the actual redirect nodes, and I wonder if we shouldn't take that a step further for vanity vs redirect vs something else - perhaps one type could return a 200 OK, whereas another could return a 302 Permanently Moved (or whatever the actual codes are). There is likely a range of implications there, such as "how does the browser wind up displaying the URL," "does this affect google search results," etc.

We should definitely find those answers as a team. Regardless, I think this is a really good foundation to start from.

[carlosmunoz]

* Rather than create nodes that are named the same as the product and version (example, `/content/documentation/rhel/8/coolDoc` [speaking of which, I forgot, is locale accounted for here? Do we even _want_ the same vanities/redirects for locales??]), let's consider how we can use those nodes to "point at" the real product and version, so things like product renames might automatically carry over to vanity URLs as well (assuming that is a feature that we want). So, our node structure might look more like `/content/documentation/abcd1234-5678.../wxyz9876-5432.../coolDoc`.

I disagree with this, as the whole point is to create a very readable layer of resources that directly points to the git-structured content. Adding these ideas would mean we would not be able to tell the full structure of the content by looking at the tree. We could however add fields to any folders which are named based on products (for example), so that a product rename would be easily reflected in any content structure that is based off the modified entity.

* I like the idea of having a special resource type for `pantheon/alias` for the actual redirect nodes, and I wonder if we shouldn't take that a step further for vanity vs redirect vs something else - perhaps one type could return a 200 OK, whereas another could return a 302 Permanently Moved (or whatever the actual codes are). There is likely a range of implications there, such as "how does the browser wind up displaying the URL," "does this affect google search results," etc.

This is not a bad diea. Part of the panteon/alias type could be some fields detailing what the response code should be.

We should definitely find those answers as a team. Regardless, I think this is a really good foundation to start from.

[benradey]

I disagree with this, as the whole point is to create a very readable layer of resources that directly points to the git-structured content. Adding these ideas would mean we would not be able to tell the full structure of the content by looking at the tree. We could however add fields to any folders which are named based on products (for example), so that a product rename would be easily reflected in any content structure that is based off the modified entity.

I think there are tradeoffs both ways. If we set up the tree your way for maximum readability in composum, then we have data duplication in the system (product url fragments stored in at least 2 places) and we'll need to add extra logic for product renames to make sure that all entries get updated, and accept the risk that we may not get that logic 100% right. If we set up the tree my way, the tree becomes less readable through composum and our logic for exposing the mappings to users will have to do some extra translation.

I think my way is safer from a data integrity perspective, but I do acknowledge that it complicates the system somewhat. I could be convinced that a url-changing product update is already a "big deal" anyways in that it will necessitate a mass rebuild or some such, and there will already be a fair bit of logic there anyway, so what's the harm in adding an extra few lines to update the redirect mapping tree as well?