Within Beaker, all Dat sites have a "Primary URL" (pURL). This is dat://{key} by default. Dat sites can assign multiple DNS short names, but the pURL will only be changed to a DNS shortname if the site's dat.json assigns a "domain" value. This value will be confirmed against the DNS record.
Therefore the "Primary URL" can be visualized as:
var hostname = key
if (manifest.domain && getDNSRecord(manifest.domain) === key) {
hostname = manifest.domain
}
var pURL = `dat://${hostname}`If you intend to use a DNS shortname for a website, you should assign its DNS record and set the domain in the dat.json manifest. (Beaker's UI will help you accomplish this.)
Internally, Beaker will translate URLs to the pURL. Other URLs can be used (in navigation and with the DatArchive API) but they will be translated to the pURL internally.
As an example, imagine that both paulfrazee.com and pfrazee.com point to the same Dat site, but the "domain" is set to pfrazee.com making it the pURL. This means that a call to UnwalledGarden's follow("dat://paulfrazee.com") will result in pfrazee.com being followed.
You can get the current pURL of a site by using DatArchive#getInfo(). The returned url value will be the pURL.
When a pURL points to a DNS shortname, Beaker will watch for reassignments to new dat keys via the DNS record. Reassignments are automatically accepted and processed. In most cases, this means updating internal dat-key records. Unwalled Garden's crawler will automatically reindex the site in order to properly process any changes.
A manifest domain change is more difficult to address, as it changes the Primary URL of the site. In addition to internal re-assignments as when the pURL DNS-record changes (see above) Beaker will update published the Unwalled Garden follows records to point to the new pURL. Any other URLs will not be changed, however, and so records such as comments on your posts will point to the old pURL.
You should try not to change your pURL often, as it will cause content to go out-of-sync with your identity.