Skip to content

feat(update-check): the version endpoint of the daily update check as a Worker - #2646

Closed
bryan-minimal wants to merge 4 commits into
mainfrom
feat/589-update-check-worker
Closed

bryan-minimal wants to merge 4 commits into
mainfrom
feat/589-update-check-worker

Conversation

@bryan-minimal

@bryan-minimal bryan-minimal commented Oct 26, 2026 •

Copy link
Copy Markdown
Member

What

Unit 1 of gominimal/inbox#589: the version endpoint the daily update check in #2650 talks to.

workers/update-check/ answers GET /v1/<channel>/<key>?os&arch&install&id with {"channel","latest"}, where latest is the channel pointer in gs://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 so count(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.yml runs the tests when the tree changes. deploy-update-check.yml is webapp's deploy-worker.yml gate (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)

  • Repo secrets CLOUDFLARE_WORKER_DEPLOY_TOKEN (Workers Scripts:Edit, Workers Routes:Edit, Zone:Read on minimal.dev) and CLOUDFLARE_ACCOUNT_ID, as in webapp.
  • gominimal/infra: the proxied update.minimal.dev AAAA record and the rate-limit rule (companion PR).

Proof

  • 7 node tests: parsing and every refusal, pointer validation through the edge cache, the data point's columns with no address, up-to-date marking, 404/503/405 with nothing recorded, a throwing sink not refusing the answer.
  • After the first deploy: 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

@bryan-minimal
bryan-minimal requested a review from a team as a code owner October 26, 2026 20:59
@coderabbitai

coderabbitai Bot commented Oct 26, 2026 •

Copy link
Copy Markdown
Contributor

Warning

Review limit reached

  • Run on-demand review

This review includes 8 billable files and costs up to $2.00.

  • Ask an admin to make reviews automatic

Open in CodeRabbit

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.

Check out review usage here.

View limit details

Limit details: You’ve used all 2 included reviews currently available.

Learn how review limits work.

Review configuration:

Run configuration
  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: CHILL
  • Plan: Essentials
  • Run ID: 7c8262ee-2956-4b2c-861a-520612ed7428
Commits

Reviewing files that changed from the base of the PR and between 2ced764 and 0e2c6fb.

Files selected for processing: 8
  • .github/workflows/ci-update-check.yml
  • .github/workflows/deploy-update-check.yml
  • .minimal/minimal.toml
  • workers/update-check/README.md
  • workers/update-check/src/index.js
  • workers/update-check/src/logic.js
  • workers/update-check/test/logic.test.js
  • workers/update-check/wrangler.toml
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Comment @coderabbitai help to get the list of available commands.

@minimal-foundry

minimal-foundry Bot commented Oct 26, 2026 •

Copy link
Copy Markdown
Contributor

Approved: every review thread resolved at 0e2c6fb569f6.

@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>

@minimal-foundry minimal-foundry Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

minimal-review — advisory review

Verdict COMMENT — 1 finding, 1 inline.

Panel: 2 of 3 personas ran (correctness, security); did not complete: supply-chain.

Comment thread workers/update-check/src/logic.js Resolved
@bryan-minimal
bryan-minimal force-pushed the feat/589-update-check-worker branch from 3041780 to e1bc8b1 Compare October 26, 2026 21:06

@minimal-foundry minimal-foundry Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

minimal-review — approval withheld

Verdict COMMENT — APPROVE withheld: 1 unresolved thread — minimal-foundry[bot] workers/update-check/src/logic.js:91. No findings.

Panel: 3 of 3 personas ran (correctness, security, supply-chain).

@mitodrummer mitodrummer left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.
  • HEAD requests 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 different run-task pins.

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.

Comment thread workers/update-check/src/logic.js Resolved
Comment thread workers/update-check/src/logic.js Resolved
Comment thread workers/update-check/README.md Resolved
…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>
@bryan-minimal

Copy link
Copy Markdown
Member Author

Round 3 (one commit on top) answers every inline thread; details in each. On the one not inline: AGENTS.md's ".github/workflows/ is frozen and CODEOWNER-gated" is a rule for agents editing existing workflows; this PR adds two new ones (the Worker's tests and its deploy gate), which is the maintainer call Karl flagged. Bryan owns that call; CODEOWNERS makes it explicit at approval time.

@minimal-foundry minimal-foundry Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

minimal-review — advisory review

Verdict COMMENT — 2 findings, 2 inline.

Panel: 3 of 3 personas ran (correctness, security, supply-chain).

Comment thread workers/update-check/src/logic.js Resolved
Comment thread workers/update-check/src/logic.js Resolved
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>

@minimal-foundry minimal-foundry Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

minimal-review — advisory review

Verdict COMMENT — 1 finding, 1 inline.

Panel: 3 of 3 personas ran (correctness, security, supply-chain).

… 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>

@minimal-foundry minimal-foundry Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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).

@minimal-foundry minimal-foundry Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@minimal-foundry minimal-foundry Bot added the review:approved minimal-review approved the current head label Oct 27, 2026

@mitodrummer mitodrummer left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@bryan-minimal

Copy link
Copy Markdown
Member Author

@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 like

webapp already has everything this Worker needs: wrangler pinned through the catalog, @cloudflare/workers-types, vitest with workers/**/*.test.ts in its include and coverage, the deploy-worker.yml gate, and the two Cloudflare secrets. The Worker becomes a sibling of landing-edge:

workers/update-check/
  wrangler.toml        # same as #2646's: route update.minimal.dev/*, the analytics_engine_datasets binding
  tsconfig.json        # landing-edge's, minus the `@/` alias (nothing shared is imported)
  src/index.ts         # the platform binding, 9 lines
  src/logic.ts         # logic.js as it stands, typed
  src/logic.test.ts    # the 9 tests, in vitest's describe/it/expect

Repo changes beside it, about 15 lines in total:

  • .minimal/minimal.toml: [tasks.deploy-update-check], a copy of [tasks.deploy-worker] that cds into workers/update-check.
  • .github/workflows/deploy-worker.yml: workers/update-check added to the changed-paths list, and a second deploy step after the landing-edge one with the same secrets. The gate (green CI on the exact commit, first-party main only) is reused as is; pnpm run check and vitest run already cover the new files, so the Worker's tests run in CI and before every deploy with nothing added.

What disappears from gominimal/minimal: both new workflows, the two catalog tasks, the Node test runner, and workers/ itself. #2646 closes. The .github/workflows/ rule stays untouched. Infra is unchanged: the update.minimal.dev record and the rate-limit rule are applied already, and the route stays wrangler-owned in the Worker's wrangler.toml wherever it lives.

What changes for the client (#2650): one line in docs/reference/telemetry.md, the "service source" link, to the webapp path. The contract (GET /v1/<channel>/<key>?os&arch&install&id, the six fields, {"channel","latest"}) is the same bytes.

Trade-offs

  • Lost: client and endpoint in one repo. The telemetry page's link covers "exactly what is sent and stored", which was the reason for co-locating.
  • Gained: no new deploy machinery anywhere, no Node in the Rust repo, the Worker tested and typechecked by the toolchain that already does that for landing-edge, and one place that knows how to deploy Workers.
  • Neutral: webapp's deploy gate deploys on every green main commit that touches workers/update-check, which for a file that changes a few times a year is fine.

Effort

About 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".

@mitodrummer

Copy link
Copy Markdown
Member

@bryan-minimal Agreed: move it to gominimal/webapp as you laid out. Keep #2646 open until the webapp version has merged and update.minimal.dev answers from it, then close this. #2650's telemetry link then points at the webapp path.

I checked the pieces the plan relies on in webapp: workers/landing-edge, deploy-worker.yml, vitest covering workers/**/*.test.ts, and [tasks.deploy-worker] with the catalog's wrangler. The port should carry over what this PR settled: the per-channel <key> contract and the g<hash> match, data points on GET only, the upper-bound note, and cacheTtlByStatus so a bucket error is never cached. Tag me on the webapp PR and I'll review it.

@bryan-minimal

Copy link
Copy Markdown
Member Author

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 update.minimal.dev answers from that deploy, then closes; #2650's link changes then.

@norrietaylor norrietaylor left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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}" -- \

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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();

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 }}

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Comment thread .minimal/minimal.toml

# 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]

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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);

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@bryan-minimal

Copy link
Copy Markdown
Member Author

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

review:approved minimal-review approved the current head

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants