[jwrosewell]

Problem

Five faults in the examples that update a data file, and in two example messages, all at 758fea81.

1. The automatic update examples look for a data file before they check for a licence key. Each of the six resolves its data file at start-up, for example IP Intelligence dataFileSystemWatcher.js line 59, and only then checks for the key at line 74. A file the data submodule links to is downloaded when it is missing, so a fresh clone with no key downloads a data file only to be told a key is needed. The three IP Intelligence examples also default to the Lite data file (line 52), about 230 MB to download.
2. They end with status 1 when they have worked. All six stop themselves three seconds after start-up with process.exit(1), for example Device Detection dataFileSystemWatcher.js line 113, so a run that did what it should reports failure.
3. The update data file examples ignore _51DEGREES_LICENSE_KEY. Both read the key from LicenseKey, then LICENSEKEY, with no deprecation message, and their message tells a person to set LicenseKey (Device Detection updatedatafile.js lines 173, 202 and 210, and the same lines in the IP Intelligence one). The automatic update examples beside them read _51DEGREES_LICENSE_KEY, which common-ci's list gives as "A licence key, for data file updates and for 51Did requests that need one" (environment-variables.md line 28 at common-ci 39564dad).
4. The cloud metadata example names another example when no key is set. It says "Native model lookup requires a paid subscription" and "in the the environment variable" (metaData.js lines 120 and 125).
5. The match metrics example prints a link nobody can follow from a terminal, /documentation/4.5/_device_detection__hash.html#DeviceDetection_Hash_DataSetProduction with no host (matchMetrics.js lines 113 and 114).

What the specification says

The IP Intelligence examples page, required-examples.md lines 84 to 87 at c8128ca4:

A performance, reload or update example, whose Properties do not matter to what it shows, uses the Asn data file, which is far smaller to download. An example downloads its file when it is missing.

The Device Detection examples page, required-examples.md lines 115 to 117 at c8128ca4:

An example whose purpose needs the Enterprise Data File or a License Key, such as one that updates the data file, explains that when it runs with the Lite Data File, gives the same link, and completes without failure.

On names, James Rosewell's rule of about 16:55 UTC on 12 November is that every environment variable name a package, a test, an example or a CI script reads is public, so a patch release never removes or renames one. When a name changes to its _51DEGREES_ form, the old name is still read for at least one release, only when the new name is unset or empty, with a deprecation message naming the new one.

What changed

1. The six automatic update examples check for the licence key first and look for a data file only when there is one. With no key they print what the key is for and the contact link, as before, and look for nothing.
2. The three IP Intelligence automatic update examples default to the ASN data file, 51Degrees-IPIV4AsnIpiV41.ipi. The Device Detection ones keep the Lite data file, the only free one.
3. All six end with process.exit(0) once they have shown how updates are set up.
4. Both update data file examples read _51DEGREES_LICENSE_KEY first, through a new getLicenseKey(), which they export for the test. LicenseKey and then LICENSEKEY are still read, only when _51DEGREES_LICENSE_KEY is unset or empty, with a deprecation message printed once. The message for a missing key names _51DEGREES_LICENSE_KEY.
5. The cloud metadata example's message says "Showing every property needs a paid subscription" and loses the doubled "the". The line with the configuration page address is not touched, because #87 changes it.
6. The match metrics example prints the full documentation address with its campaign tags and the section anchor. The page and the anchor DeviceDetection_Hash_DataSetProduction were checked to exist.

Tests

Written first, in commit c573b699.

• automaticUpdates.test.js in both automaticupdates folders runs each of the six examples in its own process, from its own folder, as a person runs it. A small file loaded first with --require replaces the data file lookup with one that prints the name asked for and gives an empty file, and the Pipeline builder with one that prints the data file it was given and builds nothing, so the examples run with no data file, no network and no working key. With no key an example must say it needs one and look for no data file. With a key it must look for and build on the ASN data file (IP Intelligence) or the Lite data file (Device Detection), and end with status 0.

• ci/tests/deprecatedVariableNames.test.js checks both update data file examples' getLicenseKey() in the way it already checks every other helper that reads a variable. The old name is read when the new one is unset or empty, the deprecation is said once and names the new name, the new name wins when both are set, and nothing is read or said when neither is.

• metaDataWithoutKey.test.js runs the cloud metadata example with no resource key and checks the message.

• matchMetrics.test.js now reads what the example writes on the Lite data file, where it read nothing, and checks the link.

• Red, the full build of the test commit (run 43554589557). All 7 Setting 'PullRequestSha' lines, Configure's and the six jobs', are c573b69, and each of the six jobs failed the 8 new update data file tests in its unit tests, so its integration tests did not run there.

• Red for the integration tests on one Ubuntu runner with Node.js 24 and the native modules built (run 43559600824). With the tests as they now are on rc's examples, all 12 automatic update checks and the metadata check failed, 13 of 13, and so did the match metrics check on the Lite data file.

• Green on the same runner at cc710ab (run 43559593333), where 13 of 13 passed, and the match metrics check on the Lite data file passed.

Two later commits change only the automatic update tests. 967a053 shows what an example wrote to its error output when it fails, and cc710ab3 writes a newline escape into the stand-ins file, where a real newline had made that file a syntax error, so that every example ended with status 1 in the first red and green runs alike (43557576924 and 43557583119). The throwaway workflows of these runs are not part of this draft.

The merge of rc

de89bd4c merges rc at 7539a0b, which holds #103. #103 added the Find out more section to the same six automatic update examples, beside the lines this draft changes, and the six conflicts are resolved keeping both. Each example prints the section before it ends with process.exit(0), and in the three IP Intelligence ones #103's FIND_OUT_MORE list sits above this draft's comment about the ASN data file. The campaign tag lint passes.

Full build

Run 43576016634 on tmp/pr-matrix-101-c, started by tools/pr-matrix.py without macOS. All 7 Setting 'PullRequestSha' lines give this head, de89bd4, and Configure printed "Left out 2 macOS entries". Each of the six Build and Test jobs, Ubuntu, Ubuntu ARM and Windows on Node.js 22 and 24, passed 1,489 unit tests with 2 skipped and 163 integration tests with 4 skipped, the new tests and #103's Find out more checks among them, so the automatic update examples also ran and ended with status 0 on Windows. The build of the head before the merge, cc710ab, run 43560348516, passed as well.

macOS was left out of this draft's full build under the 9 November decision. The rc head is built with macOS before it merges into main.

What remains

1. common-ci's list gives LicenseKey and LICENSEKEY as names of their own for the Java and Node.js update examples (environment-variables.md lines 98 and 99 at 39564dad). For Node.js they are now deprecated names of _51DEGREES_LICENSE_KEY, which line 28 should list. That change belongs to common-ci, as common-ci#331.
2. This draft changes only the wrong words in the cloud metadata example's message, not what a cloud example does with no resource key. How a cloud example ends with no resource key has since been settled, as each names the environment variable to set, links to where a key is created and exits with status 0. That change touches every cloud example, so it is in its own draft, #133.