Why is usage of the downloadURL & updateURL keys called unusual and how do they work?

Question

I was reading GM's wiki to determine the difference between @downloadURL & @updateURL (which I didn't). But what confused me even more that both are unadvised:

It is unusual to specify this value. Most scripts should omit it.

I'm surprised by that as it's the only way for scripts to auto-update and I don't see why these keys shouldn't be used.

The wiki itself is pretty lacking and no other forum sources are advised, so I have to ask here. Also would appreciate more detailed info on these keys.

Answer 1

Use of those keys is discouraged mainly by Greasemonkey's lead developer. Most others, including the Tampermonkey team feel no need for such a warning.
Also note that those directives are not always required for auto-updates to work.

Some reasons why he would say that it was unusual and that "most" scripts should omit it:

1. In most all cases it is not needed, see how updates work and how those directives work, below.
2. Adding and using those directives are just more items that the script writer must check and maintain. Why make work if it is not needed?.
3. The update implementation and those directives have been buggy and, perhaps, not well implemented in Greasemonkey.
4. Tampermonkey, and other engines, implement updates, and those directives, in a slightly different manner. This means that code that works on Tampermonkey may fail on Greasemonkey.

Note that that wiki entry was made by Greasemonkey's lead developer (Arantius) himself; so it wasn't just wiki noise.

---

How updates work:

Script updates are conducted in 4 phases:

1. The enabled phase and/or "forced" updates.
2. The check phase.
3. The download phase.
4. The parse and install phase.

For this question, we are only concerned with the check and download phases. We stipulate that updates are enabled and that the updated script was valid and installed correctly.

When updating scripts, Greasemonkey (and Tampermonkey) download files twice:

1. The first download, controlled by the script's updateURL value, is just to check the file's @version (if any) and date -- to see if an update is available.

2. The second download, controlled by the script's downloadURL value, is the actual download of the new script to install. This download will only occur if the server file has a higher @version number than the local file and/or if the server file has a later date than the local file. (Beware that there are critical differences here between script engines.)

   See "Why you might use @downloadURL and @updateURL", below, for reasons why 2 file downloads are used.

---

How @downloadURL and @updateURL work:

@downloadURL merely overrides the default internal "download URL" location.
@updateURL merely overrides the default internal "update URL" (or check) location.
In most cases, there is no need to do this. See, below.

1. When you install a userscript, Greasemonkey automatically records the install location. No meta directive is needed. By default, this is where Greasemonkey will both check for updates and download any updates.
2. But, if @downloadURL is specified, then Greasemonkey will both check and download from the specified location rather than the stored location.
3. But, if @updateURL is specified, then Greasemonkey will check (not download) from the "update" location given.

So: @updateURL overrides both @downloadURL and the default location for checking operations only.
While: @downloadURL overrides the default location for both checking and downloading (unless @updateURL is present).

---

Why you might use @downloadURL and @updateURL:

First, there are 2 downloads and potentially 2 different locations mainly for speed and bandwidth reasons. Consider a scenario where a very large userscript has thousands of users:

• Those users' browsers would constantly hammer the host server checking to see if an update was available. Most of the time, one wouldn't be and the large file would be downloaded over and over again unnecessarily. This got to be a problem for sites like the now defunct userscripts.org.
• Thus a system developed whereby a separate file was created to just hold version (and date) information. So the server would now have veryLarge.user.js and veryLarge.meta.js
• veryLarge.meta.js would be updated (by the developer) every time the userscript was and would just contain the Metadata Block from veryLarge.user.js.
• So the thousands of browsers would just repeatedly download the much smaller veryLarge.meta.js -- saving everybody time and saving the server bandwidth.

Nowadays, both Greasemonkey and Tampermonkey will automatically look for a *.meta.js file, so there is normally no need to specify one separately.

So, why explicitly specify @downloadURL and/or @updateURL? Some possible reasons:

1. Your script can be installed multiple ways or from multiple sources (cut and paste, locally copied file, secondary server, etc.) and you only want to maintain one "master" version.
2. You want to track how many initial and/or upgrade downloads your script has.
3. @downloadURL is also a handy "self documenting" way of recording/conveying where the user got the script from.
4. You want the *.meta.js file on a different server than the userscript for some reason.
5. Possibly http versus https issues (need to dig into this some day).
6. You are a bad guy and you want the script to update a malicious version at some future date from a server that you control -- that is not where the script was installed from.

Some differences between Greasemonkey and Tampermonkey:

^{(Warning: I haven't verified all of this in a while. Subject to change anyway as Tampermonkey is constantly improving (and Greasemonkey changes a lot too).)}

1. Tampermonkey requires a @version directive on both the current and newer file. This is how Tampermonkey determines if an update is available.

   Greasemonkey will also use this method, so always include @version in scripts you might want to auto-update.

   However, Greasemonkey also requires that the update file be newer. And if no version is present, Greasemonkey will just compare the dates only. Note that this has caused problems in Greasemonkey in the past and also foolishly assumes that many different machines are accurately synched with the correct date and time.

2. Greasemonkey will only update from https:// schemes by default, but can optionally be set to allow http:// and ftp:// schemes.

3. Both engines never allow updates from file:// schemes.