Skip to content

End every cloud example cleanly when it has no resource key - #163

Draft
jwrosewell wants to merge 6 commits into
rcfrom
examples/cloud-no-key
Draft

jwrosewell wants to merge 6 commits into
rcfrom
examples/cloud-no-key

Conversation

@jwrosewell

@jwrosewell jwrosewell commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

The specification this brings the code into conformance with

device-detection-specification/required-examples.md lines 140 to 145 at dbaf099c says

A cloud example run with no Resource Key MUST end without an error, name the environment variable to set, give a link to where a Resource Key is created, such as the configurator, and exit successfully, so that its test runs it with no arguments or settings (see Execution).

A cloud example run with no resource key threw an exception, failed in its builder or, for the 51Did creator context demo server, exited with status 1, and the Location examples asked for a key to be pasted into the source.

What changed

Links are to the head, 0bf566c9.

  1. Every cloud example ends cleanly with no key. Each Device Detection, IP Intelligence and Location cloud example, and the 51Did creator context demo server, looks for its key as its argument and then in _51DEGREES_RESOURCE_KEY (the Device Detection examples then in TestResourceKey, and the TAC and native model examples in SuperResourceKey, as before). With none it says which variable to set, links to the configuration page tagged for the example, adds the contact page for the TAC and native model examples, whose properties need a paid licence, and ends with its Find out more section and exit code 0. The web examples end the same way rather than start a server that cannot answer.
  2. KeyHelper in each product's examples shared module gains the lookup and the message, and FindOutMore the section a cloud example with no key ends with.
  3. AGENTS.md says what a cloud example does with no key, and the Location Find out more tests match the new message.

Examples, AGENTS.md and the 51Did developer example only. No package code changes, and no public name is removed or renamed.

Before you upgrade

A cloud example run with no resource key now prints how to get one and exits with code 0, where it threw or exited with 1. A script that ran an example to check a key was set should check the variable itself.

Tests

Each cloud example's test runs it in a new Java process with every variable whose name holds KEY left out of its environment, as it runs from a fresh clone, and checks that it exits with code 0, names the variable to set, links to the configuration page with the campaign tags and ends with its Find out more section. ExampleProcess, in each product's examples shared module, starts that process, because a running Java process cannot remove a variable from its own environment. The tests are CloudExamplesWithoutKeyTest (Device Detection and IP Intelligence consoles), GettingStartedWebCloudWithoutKeyTest (Device Detection and IP Intelligence cloud web examples), GettingStartedWebCloudMixedWithoutKeyTest, Location's CloudExamplesWithoutKeyTests and CreatorContextDemoServerWithoutKeyTests.

Red and green, run 43919206686 on tmp/red-163, which runs each part's new tests at the test commit 7c22ff3 and at the head 0bf566c, with Maven going on past a failing module so every class runs.

Part Red at 7c22ff3 Green at 0bf566c
Device Detection examples CloudExamplesWithoutKeyTest fails 5 of 5, GettingStartedWebCloudWithoutKeyTest 1 of 1 5 of 5 and 1 of 1 pass
IP Intelligence examples CloudExamplesWithoutKeyTest fails 4 of 4, both web classes 1 of 1 4 of 4 and both 1 of 1 pass
Location examples CloudExamplesWithoutKeyTests fails 2 of 2 2 of 2 pass
51Did developer example CreatorContextDemoServerWithoutKeyTests fails 1 of 1, "CreatorContextDemoServer should end with exit code 0 ==> expected: <0> but was: <1>" 1 of 1 passes

An earlier run, 43909921570, stopped each product at its first failing module, so the console classes did not run on its red side, and its green side for Device Detection did not compile at 0955829, because after the merge of rc, which brought in #187, KeyHelper.findResourceKey and TacCloud still called KeyUtils.isInvalidKey, which the examples no longer import. Commit 0bf566c calls the examples' own isInvalidKey in both places.

Green, also the full build below.

Build

Run 43919096223 built 0bf566c merged with rc 81e3d4a on nine configurations, Ubuntu x64 with Java 8, 11, 17 and 21, Ubuntu arm64 with Java 17, and Windows with Java 8, 11, 17 and 21. Configure and all nine Build and Test jobs passed, read from each job's log, and CloudExamplesWithoutKeyTest passed 5 of 5 for Device Detection and 4 of 4 for IP Intelligence in all nine jobs. Each of its ten Setting 'PullRequestSha' lines names 0bf566c, and its Configure job printed "Left out 6 macOS entries". The run's last job, which only gathers the results, was still waiting for a runner when this was written.

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.

Base branch

rc 81e3d4a is merged into the head with a merge commit, 0955829, with no conflict, and 0bf566c then fixes the two calls the merge left without their class, as the Tests section says.

What remains

  1. #173 carried a second version of this work and gave it up at its bd93f86, so this draft is the one that makes the cloud examples end cleanly.
  2. #188 brings AGENTS.md's Cloud examples section up to date with the rest once this draft has merged.

Each cloud example runs in a new Java process with every variable whose
name holds KEY left out of its environment, as it runs from a fresh
clone, and must end with exit code 0, name the variable to set, link to
the configuration page with the campaign tags, and end with its Find out
more section. ExampleProcess, in each product's examples shared module,
starts the process, because a running Java process cannot remove a
variable from its own environment.
A cloud example run with no resource key threw an exception, failed in
its builder or, for the 51Did demo server, exited with status 1, and the
Location examples asked for a key to be pasted into the source. The
specification now says a cloud example run with no resource key ends
without an error, names the environment variable to set, gives the
tagged link to where a key is created, and exits successfully, so that
its test runs it with no settings.

Each Device Detection, IP Intelligence and Location cloud example, and
the 51Did creator context demo server, now looks for its key as its
argument and then in _51DEGREES_RESOURCE_KEY (the Device Detection
examples then in TestResourceKey, the TAC and native model examples in
SuperResourceKey, as before). With none it says which variable to set,
links to the configuration page tagged for the example, adds the
contact page for the TAC and native model examples, whose properties
need a paid licence, and ends with its Find out more section and exit
code 0. The web examples end the same way rather than start a server
that cannot answer.
jwrosewell added a commit that referenced this pull request Nov 16, 2026
…ith no key to the drafts that carry them

The Derived Property Element and its example are #156's, Comparer on the
free data file is #158's, and every cloud example ending cleanly with no
resource key is #163's, so each file this draft changed only for those
is put back to rc's version. The cloud cases of the no-settings tests go
with them, as #163's tests cover each cloud example run with no key.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant