Urls in swarm

swarm_urls.md

bzz:// urls work well in a future scenario where everyone uses swarm-enabled browsers to access content. However, this is not the case now, so we need a strategy on how would we like to handle urls, so that they work well in most situations, e.g. in normal browsers, with different gateways, etc.

Let's define some terminology to describe the different user scenarios:

Client software environment

The user's software environment to access a swarm page

• public-gateway: normal browser using public http gateway
• local-gateway: normal browser and local swarm node http interface
• browser-plugin: normal browser with plugin to rewrite urls
  • it rewrites bzz:// to http://<gateway>/bzz:/
• local-proxy: normal browser with local proxy that rewrites urls (to gateway url)
  • same rewrite as with the browser-plugin
• mist: swarm enabled browser

Use cases

What is the use case of the user to access the swarm page?

• address-bar: writing url into the browser address bar
• web-link: clicking on an html link from a page on the regular internet
• swarm-link: clicking on an html link from a page on swarm

Possible URL formats:

• bzz://
• http://<gateway>/bzz:/
• /bzz:/
• web+bzz://

Analysis:

bzz://

Only works with extra software installed, so in these environments:

• browser-plugin
• local-proxy
• mist If you are in any of these environments, then it supports all the use cases (address-bar, web-link, swarm-link). Note: you can not register a protocol handler to bzz from JS, because it is not whitelisted by the browsers. See: https://developer.mozilla.org/en-US/docs/Web/API/Navigator/registerProtocolHandler#Permitted_schemes and https://developers.google.com/web/updates/2011/06/Registering-a-custom-protocol-handler

http://<gateway>/bzz:/

It somehow works everywhere, but not optimal if you would not like to use the exact gateway which is hardcoded into the url. So it only works well in the public-gateway environment. In all the other environments the users would not want to use this gateway, but they are forced to do so. In the public-gateway environment it supports all the use cases (address-bar, web-link, swarm-link).

/bzz:/

It can work in all environments, but only in the swarm-link use case.

In the address-bar use case:

It just won't work, because browser will treat as file system uri, and rewrite it this: file:///bzz:/

In the web-link use case:

It is broken in this use case too, because it is a domain-relative url. So e.g. if the source page is on https://medium.com/, then the link will target https://medium.com/bzz:/, which doesn't work.

web+bzz://

Same as bzz://, but it has the advantage that you can register a protocol handler from JS. With this protocol handler you can rewrite the url to use a public gateway. With this it can also support the public-gateway environment, but it means this extra JS snippet has to be included in the page by everyone who would like to link swarm content, because you can never know if the user has already registered the protocol or not.

Other solutions:

JS hack

We could provide a small JS snippet which rewrites the urls of a page to public gateway urls. Then for these pages bzz:// urls could work with the public-gateway environment. Unfortunately it is hard to write a JS snippet which is compatible with all different kind of webapps and frameworks. E.g. it turned out angular apps themselves also rewrite the bzz urls to unsafe:bzz:// which is in conflict with our rewrite. But even if we solve for this specific problem, there can be other issues, it is not a failsafe solution.

IPFS url scheme trick

IPFS encounters the same problem and there are huge discussions in the community about this. See e.g. here: ipfs/kubo#1678 (comment) There is one small difference on how they handle urls. If we would apply that to swarm, that could make the /bzz:/ urls much more useful. In ipfs all these urls are valid: /ipfs/<hash> ipfs://ipfs/<hash> http://<gateway>/ipfs/<hash>

What is an important difference, is that ipfs:/ and http://<gateway> is interchangeable. The /ipfs/<hash> url works will with both: if you are on a page from ipfs, it will just behave as a protocol-relative url, if you are on the standard web using a gateway, it will be a domain-relative url, so it works well the client environments.

We could adapt this to swarm by allowing the following url: bzz://bzz/<hash> In this case the /bzz/ url scheme would work in all environments in all use-cases, except web-link.

@zelig one problem with web+bzz:// is that it's really ugly