Repository navigation
feat(update-check): the version endpoint of the daily update check as a Worker - #2646
bryan-minimal wants to merge 4 commits into
Conversation
|
Warning Review limit reached
This review includes 8 billable files and costs up to $2.00.
Reviews can continue after your included limit without a manual trigger. An admin must approve usage-based billing. Or wait 33 minutes for your next included review. View limit details
Comment |
|
Approved: every review thread resolved at @mitodrummer resolved the last thread, which releases the approval this review had withheld. Nothing to do. |
… a Worker Unit 1 of gominimal/inbox#589: workers/update-check answers GET /v1/<channel>/<key>?os&arch&install&id with the channel's current pointer, read from the minimal-one bucket through a 5 minute edge cache, and writes one Analytics Engine data point per answered request: the eight request fields plus country and ASN, never the address. A channel outside {stable, unstable, nightly}, a field outside its charset or a missing one is a 404 with nothing recorded; an unreadable pointer is a 503. Plain JavaScript with the logic apart from the platform binding, so the tests run on node's own runner: no package manager or lockfile enters this repo. Two catalog tasks pin node and wrangler through pkgs, a path-scoped CI workflow runs the tests, and deploy-update-check.yml is webapp's deploy-worker.yml gate (green CI on the exact commit, first-party main only) with the Worker swapped and no paging. The proxied update.minimal.dev record and the rate-limit rule are gominimal/infra's. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
3041780 to
e1bc8b1
Compare
mitodrummer
left a comment
There was a problem hiding this comment.
Reviewed at e1bc8b12. The Worker logic is tight. Parsing refuses before anything is recorded. A bad pointer is a 503 and never reaches a client. No address is stored. A failing analytics write doesn't fail the answer. And the deploy gate is webapp's, copied verbatim. CI is green, including update-check worker tests.
Inline:
- The up-to-date flag on unstable and nightly, whose pointer is a short hash, not a version. This one matters before the client lands.
HEADrequests write data points.- Saying in the README that the install count is an upper bound.
- Webapp leftovers in
deploy-update-check.yml, and the two differentrun-taskpins.
Not inline: AGENTS.md treats .github/workflows/ as frozen and CODEOWNER-gated, and this PR adds two workflows. That's a maintainer call; I'm flagging it so it gets made on purpose.
…he count is a bound From review (#2646): a HEAD is a probe and is answered without a data point; "up to date" also holds for a whole version string whose g<hash> suffix is the pointer, and the README names what <key> is on each channel (a version on stable, a short hash on unstable and nightly, as the installer recorded it); the README says the install count is an upper bound held down only by infra's per-source rate-limit rule; the deploy workflow loses three comments copied from webapp that did not describe this job, and pins run-task to the same v1 sha as ci.yml. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
|
Round 3 (one commit on top) answers every inline thread; details in each. On the one not inline: AGENTS.md's " |
From review (#2646): `cacheTtl` with `cacheEverything` kept every status for five minutes, so one transient 5xx from the bucket would have been a 503 for every client at that edge until it expired. `cacheTtlByStatus` keeps a pointer for the five minutes and an error for none. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
… upload From review (#2646): the deploy gate watches ci.yml, and the Worker's tests run in ci-update-check.yml, so a red test run did not stop a deploy of that commit. The deploy job now runs the same task right before the upload; a failure there is a failed deploy, whatever workflow the tests ran in first. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
There was a problem hiding this comment.
minimal-review — approval withheld
Verdict COMMENT — APPROVE withheld: 7 unresolved threads — mitodrummer workers/update-check/src/logic.js, mitodrummer workers/update-check/src/logic.js:103, mitodrummer workers/update-check/README.md:56, mitodrummer .github/workflows/deploy-update-check.yml, mitodrummer .github/workflows/deploy-update-check.yml, …. No findings.
Panel: 3 of 3 personas ran (correctness, security, supply-chain).
There was a problem hiding this comment.
minimal-review — approved
Verdict APPROVE — every review thread is resolved; @mitodrummer closed the last one. The review of 0e2c6fb569f6 withheld this approval on the threads open then.
mitodrummer
left a comment
There was a problem hiding this comment.
Approved at 0e2c6fb. Every point from my review is addressed and checked in the code: the <key> contract per channel and the g<hash> match, data points on GET only, the install count documented as an upper bound, the webapp leftovers gone, one run-task pin, bucket errors not cached at the edge, and the Worker's tests running before the deploy. CI is green. CodeRabbit was rate-limited on this head, so it didn't review it.
|
@mitodrummer, on your "two new workflows in a frozen directory" point: Bryan asked for a plan for the other home, so here it is for a decision, not a fait accompli. #2646 stays as is until someone says move. What moving the Worker to gominimal/webapp would look likewebapp already has everything this Worker needs: wrangler pinned through the catalog, Repo changes beside it, about 15 lines in total:
What disappears from gominimal/minimal: both new workflows, the two catalog tasks, the Node test runner, and What changes for the client (#2650): one line in Trade-offs
EffortAbout half an hour to port (the logic is a straight TS translation), one webapp PR to review, then close #2646 and a one-line follow-up on #2650. The first deploy happens on the next green main after the webapp merge, through the existing gate. If you both prefer this, I would open the webapp PR today and leave #2646 open until the webapp one is merged and deployed, so the endpoint never regresses to "nothing behind the route". |
|
@bryan-minimal Agreed: move it to gominimal/webapp as you laid out. Keep #2646 open until the webapp version has merged and I checked the pieces the plan relies on in webapp: |
|
The webapp version is up: gominimal/webapp#916, the same logic as this PR's round 5, typed, with the nine tests in vitest and the deploy riding deploy-worker.yml's gate beside landing-edge. This PR stays open until |
norrietaylor
left a comment
There was a problem hiding this comment.
Local review of 0e2c6fb5. The inline comments are in order of severity.
- Most important: the deploy gate does not see a change to
.minimal/minimal.toml, a read error can return 500 instead of 503, and the README points to a client file and a docs section that do not exist. - Three comments are related to open threads (the deploy gate and the Worker tests, the install count, and
HEAD). They add a different point. They do not repeat the thread.
Generated by Claude Code
| @@ -0,0 +1,401 @@ | |||
| # Deploy the update-check Cloudflare Worker (workers/update-check, the version | |||
There was a problem hiding this comment.
This PR adds two workflow files under .github/workflows/. AGENTS.md says that this directory is frozen and CODEOWNER-gated, and that CI logic goes in scripts/ and the justfile (docs/ci-strategy.md §8: "the CI YAML schedules, the logic lives here and in scripts/").
A new deploy workflow must have a YAML file. But this file has approximately 400 lines, and most of them are shell logic: the resolve step, the re-run guard, the wait for CI and the changed-paths gate. Move that logic into a script under scripts/, with a _test.sh harness, and keep the YAML as a short schedule. Then the logic has tests, and a person can run it locally.
Generated by Claude Code
| echo "changed=true" >> "${GITHUB_OUTPUT}" | ||
| exit 0 | ||
| fi | ||
| changed=$(git diff --name-only "${base}" "${SHA}" -- \ |
There was a problem hiding this comment.
The changed-paths diff includes only workers/update-check and this workflow. It does not include .minimal/minimal.toml. That file has the deploy-update-check and test-update-check tasks, and the locked_commit that pins wrangler and node.
Example: a commit changes only locked_commit (a new wrangler), or it changes [tasks.deploy-update-check]. It merges to main. The gate sets changed=false, logs "No Worker-relevant change", and does not deploy. The push filter of ci-update-check.yml (line 12) also does not include .minimal/minimal.toml, so the Worker tests do not run on main either. The changed deploy path runs only when an unrelated Worker change merges later.
Add .minimal/minimal.toml to this diff and to the push paths. The pull_request paths already include it.
Generated by Claude Code
| return null; | ||
| } | ||
| if (!resp || !resp.ok) return null; | ||
| const text = (await resp.text()).trim(); |
There was a problem hiding this comment.
await resp.text() is outside the try/catch in latestFor. Thus, if the body stream fails, the error goes up out of handle(). latestFor does not return null.
Example: the bucket sends a 200 header, and then it resets the connection. Or the body of the edge subrequest fails while the Worker reads it. The rejection is not caught, and the Worker answers with the Cloudflare 500 page. It does not answer with the documented 503 and Retry-After: 300. Clients get a status that is not documented, and no back-off hint.
Put the resp.text() call in the try block.
Generated by Claude Code
| # update-check | ||
|
|
||
| The version endpoint of `min`'s daily update check (gominimal/inbox#589). | ||
| The client is `crates/minimal/src/update_check.rs`; the user-facing page is |
There was a problem hiding this comment.
The README (and wrangler.toml) name the client crates/minimal/src/update_check.rs, and the user-facing page docs/reference/telemetry.md, "Update check". Neither is in the tree: there is no update_check.rs, and telemetry.md has no update-check section.
This Worker records an install UUID, the country and the ASN for each check. At the moment, no user-facing document tells users about this collection. If the Worker deploys before the client and the docs PR merge, it collects data with no disclosure.
Link the PR or the issue that adds the client and the docs. Alternatively, do not deploy until the disclosure is on main.
Generated by Claude Code
| contents: read | ||
|
|
||
| jobs: | ||
| test: |
There was a problem hiding this comment.
This job is in a separate workflow, and no lane aggregator includes it (ci-success and the others). Thus, a failed Worker test does not stop a merge.
Example: a PR breaks the logic.js tests. CI update-check is red, but it is not required, so the PR merges. Then the test step of the deploy fails on main, and no Worker change deploys until someone repairs main. Review does not find the problem; main finds it after the merge.
This is related to the open thread on line 43 of deploy-update-check.yml, which is about the deploy gate. This comment is about the merge gate. Add this job to a lane aggregator, or make it a required check.
Generated by Claude Code
| # Set only by the resolve step's superseded-commit refusal, whose non-zero | ||
| # exit is a designed outcome rather than a malfunction — the edge is ahead | ||
| # of that commit. The `notify` job must not page for it. | ||
| superseded: ${{ steps.resolve.outputs.superseded }} |
There was a problem hiding this comment.
The superseded outputs (here, and on line 318) have the comment "The notify job must not page for it". This workflow has no notify job, and its last comment says that paging is not implemented.
Thus, the two outputs and the code that writes them are not used. The comments tell about behavior that this workflow does not have. This can confuse a person who debugs a superseded-commit refusal. It looks like these lines came from the webapp deploy-worker.yml. Remove the outputs, or add a comment that says which future job reads them.
Generated by Claude Code
| GH_TOKEN: ${{ github.token }} | ||
| REPOSITORY: ${{ github.repository }} | ||
| SHA: ${{ steps.resolve.outputs.sha }} | ||
| # This repo's ci.yml never cancels a run on main (its concurrency |
There was a problem hiding this comment.
This comment says that ci.yml "never cancels a run on main", so cancelled means only a manual cancel. But a GitHub concurrency group cancels a pending run when a newer run queues, also with cancel-in-progress: false. The comment in the script some lines below says exactly that.
Also, line 24 says that this workflow "used to be scoped by" push: paths:. This workflow is new, so it was never scoped that way.
The two comments do not agree. A maintainer who reads only this comment can remove the re-target branch as unreachable. Then a dispatch during many merges fails with "CI concluded 'cancelled'". It does not follow HEAD. Change this comment so that it agrees with the script, and remove the "used to be" wording on line 24.
Generated by Claude Code
|
|
||
| # The update-check Worker (workers/update-check, inbox#589): its tests run on | ||
| # Node's own runner, so no package manager or lockfile enters this repo. | ||
| [tasks.test-update-check] |
There was a problem hiding this comment.
The new test and deploy entry points are min run tasks only. They have no justfile recipe. AGENTS.md says: "Build and test only through just. ... If something has no recipe, add one — the justfile is where local build knowledge lives."
Thus, just --list does not show the Worker tests, and just ci does not run them. A contributor who uses the documented pre-PR command does not run them locally. Add a just test-update-check recipe that calls this task, and add it to just ci.
Generated by Claude Code
| client proves (the login-verified metrics of inbox#515). | ||
|
|
||
| ```sql | ||
| SELECT blob2 AS channel, count(DISTINCT blob1) AS installs |
There was a problem hiding this comment.
These queries use count(DISTINCT blob1) and do not use _sample_interval. Analytics Engine samples data when the volume is high.
When sampling starts, Analytics Engine does not keep some install ids. Then count(DISTINCT blob1) counts fewer installs than the true number. The README (line 46) now calls the count an upper bound, as the open thread on this line asked. But with sampling, the count can be lower than the true number. Thus, it is not an upper bound in all conditions.
Say in the README that the count is approximate in both directions when sampling occurs. Alternatively, give a query that uses _sample_interval.
Generated by Claude Code
| } | ||
| const fields = parseRequest(request.url); | ||
| if (fields === null) return new Response(null, { status: 404 }); | ||
| const latest = await latestFor(fields.channel, fetchFn); |
There was a problem hiding this comment.
A HEAD request fetches the bucket pointer before the Worker answers it. If the bucket is not available, the Worker returns 503. But no body and no data point use the pointer for a HEAD.
Example: an uptime monitor sends HEAD during a short GCS outage. It gets 503 and sends alerts. Each probe also costs a cache lookup or an origin fetch, but a probe must be cheap and must have no side effects.
This is related to the open thread on line 103, which is about the data point for HEAD. Answer HEAD before the call to latestFor, if the probe only has to show that the Worker runs.
Generated by Claude Code
|
The Worker lives in gominimal/webapp now: webapp#916 merged 2026-10-29, carrying the review points raised here that still applied. Closing this copy. |
What
Unit 1 of gominimal/inbox#589: the version endpoint the daily update check in #2650 talks to.
workers/update-check/answersGET /v1/<channel>/<key>?os&arch&install&idwith{"channel","latest"}, wherelatestis the channel pointer ings://minimal-one/<channel>read through a 5 minute edge cache. Promotion stays the single source of truth; nothing is written on release. One Analytics Engine data point per answered request carries the eight request fields plus country and ASN, never the address, indexed by install id socount(DISTINCT blob1)over a day is the install count (queries in the README). A channel outside the allow-list, a value outside its charset or a missing field is a 404 with nothing recorded; an unreadable pointer is a 503.Plain JavaScript, logic apart from the platform binding, tests on
node --test: no package manager or lockfile enters this repo. Two catalog tasks (test-update-check,deploy-update-check) pin node and wrangler through pkgs.ci-update-check.ymlruns the tests when the tree changes.deploy-update-check.ymlis webapp'sdeploy-worker.ymlgate (green CI on the exact commit, first-party main only, changed-paths) with the Worker swapped and the paging job left out, since this repo has no paging action.Needs before the first deploy (Bryan)
CLOUDFLARE_WORKER_DEPLOY_TOKEN(Workers Scripts:Edit, Workers Routes:Edit, Zone:Read on minimal.dev) andCLOUDFLARE_ACCOUNT_ID, as in webapp.update.minimal.devAAAA record and the rate-limit rule (companion PR).Proof
curl -s 'https://update.minimal.dev/v1/stable/0.7.1?os=linux&arch=x86_64&install=installer&id=<uuid>'returns the stable pointer, and one row appears in the Analytics Engine SQL API.🤖 Generated with Claude Code