Hi,
I've had a go at implementing this for my personal blog. Here are some things:
We introduce a new HTTP header called "Onion-Location" with the exact same restrictions and semantics as the Location HTTP header. Websites can use the Onion-Location HTTP header to specify their onion counterpart, in the same way that they would use the Location header.
Example: Onion-Location: http://vwc43ag5jyewlfgf.onion
This example is perhaps not the best example. I tried to get things working with the Healthy Onions add-on, but found that the developer had interpreted this to mean that the Onion-Location value is just a replacement for the protocol and domain parts of the URL, not a replacement for the whole URL.
There may not be a 1:1 mapping in the URL space between the two URL domains. At the very least, I would add a trailing slash (/) to the example. The Healthy Onions developer seems to expect the string to end with ".onion".
My personal website is a static site (mostly). In my implementation, I took a list of all possible HTML URLs (excluding images, stylesheets, etc.) and generated a list of corresponding onion locations.
I figured that being a blog, people often link to individual pages instead of just to my homepage (which is probably the least useful page on the site). Having the Onion-Location header on every page someone could land on gives the best chance that they will discover the onion service.
But then I realised that some of the locations I had generated Onion-Locations for would also be serving Location headers as they were old URLs. What should a browser do in this case? What should an implementer do? In my implementation, I've thrown in the Onion-Location headers regardless of whether or not a Location header is also present because it was easier.
It could be preferable that the redirection is followed after switching to the Onion service (i.e. Location header is ignored until user responds to the Onion-Location header prompt), but this would mean the page wouldn't have loaded before you get the prompt to go to the Onion service, which may be confusing for users. Alternatively, if the page has a Location header then the Onion-Location header should be ignored.
Thanks, Iain.