Custom domains page polls certificate progress fast only while a certificate is generating

[dawsontoth]

Closes #1630

Stacked on #1801. Its base is claude/1626-preserve-domain-cert-intent, so this diff is only the polling change. Review and merge #1801 first, then this retargets to stage.

⊙ Problem

The cluster Domains table polled the cluster's ChallengeCertificate rows every 5 seconds for as long as it was open. A cluster without that table answers 404, and getSearchByValue deliberately reads a 404 as an empty result. So the poll never errored, pollUnlessForbidden could never stop it, and one long-lived tab sent 993 doomed requests in 112 minutes. In RUM, /Cluster/{id}/operation 404s rose from 71 to 1,399 a week (#1630). The rows exist only to show a certificate being generated, so the 5s rate was spent exactly when there was nothing to watch.

❓ Your call: is a once-a-minute idle poll the right floor? I kept one so changes made outside this tab (a bind from another tab, a renewal starting) still show up within a minute. Stopping the idle poll entirely (false) would remove the remaining ~1 request/min per open tab, but those changes would then only appear on refocus or remount. Either way it's one constant.

💡 Solution

The poll runs at 5s only while a certificate is generating (no issueDate, or inProgress), or for three minutes after a domain change. Otherwise it polls once a minute. The 403 stop from pollUnlessForbidden still applies on top.

The issue's recommended option 2 needed one correction. Invalidating the rows when the domain-ids mutation succeeds is not enough on its own: central manager answers the PUT before host manager acts on it, and host manager only upserts a row per added domain once it reconciles the change (deploying the cert component and restarting, the first time). An immediate re-read usually finds nothing yet. So the mutation starts a three-minute watch window and re-reads the rows at once.

⚠️ Look hardest: three minutes is a judgment, not a measurement. If host manager takes longer, the new rows are still found by the next idle tick (≤60s later), and from then on the 5s rate applies while the certificate generates.

⚖️ Alternatives

• Idle backoff alone (the issue's option 1): it adds up to 60s before a bind's progress appears, in the one flow this table exists for.
• Treat the 404 as terminal (option 3): it means changing getSearchByValue's shared 404-as-empty contract, or wrapping it. The watch window already covers the only Studio action that creates the table, and the idle rate bounds everything else.
• Poll fast while any cluster instance is UPDATING: it is a server-side signal, but it couples this query to the cluster record and to statuses that version upgrades also use.

🔧 Changes

• getChallengeCertificates.ts: challengeCertificatePollInterval picks 5s or 60s, and the query's refetchInterval wraps it in pollUnlessForbidden. watchChallengeCertificates opens a per-cluster window and invalidates challengeCertificatesQueryKey, the key the query itself uses. isGeneratingCertificate is now the one definition of "generating".
• setDomainIdsOnCluster.ts: the mutation's onSuccess also calls watchChallengeCertificates. It runs at mutation level, so it fires even if the table unmounted mid-request.
• tableDefinition.tsx: both "generating" checks use isGeneratingCertificate.
• src/features/cluster/DESIGN.md, DESIGN.md: a note on cert intent being cluster-wide (from Unbinding one custom domain no longer turns off certificates for the others #1801) and on why certificate progress is polled this way, plus the index line.

✅ Verification

End-to-end route: not observable end-to-end here. It needs a cluster without the ChallengeCertificate table and an open Domains tab over minutes. Verified at the query's own refetchInterval and through the real DomainsManagement:

• getChallengeCertificates.test.ts (new), against the query options' own refetchInterval:
  • idles at 60s for empty, missing and fully issued rows;
  • polls at 5s for a pending or renewing certificate;
  • polls at 5s after watchChallengeCertificates, for that cluster only, and idles again once the window passes (fake Date);
  • still returns false on a 403.
• Management.test.tsx: a domain change re-reads the certificate rows at once (a second search_by_value on ChallengeCertificate).
• Fails on base: with the mutation's onSuccess reverted to the Unbinding one custom domain no longer turns off certificates for the others #1801 version, the re-read test fails (expected 2 calls, got 1). Making the interval constant again fails the idle and window tests, and ignoring the window fails the window test.
• Gates on the final head: npx vitest run 396 files / 3,675 passed (exit 0), npx tsc -b exit 0, npx oxlint --format stylish . exit 0, npx dprint check exit 0, with Node 24.21.0.

Pre-push review: one full round against the #1801 branch (codex graded, gemini). The verdict was COMMENTS with no defects found. The Harper-domain adjudicator failed on auth and the Cursor legs failed on the 1Password SSH agent, as on #1801. I took the comment trims. I rejected:

• .ts import extensions: this repo's imports are extensionless throughout;
• an unbounded watchingUntil map: it holds one entry per cluster this tab changed domains on;
• a fake-time leak between tests: each test uses its own cluster id, and the fixed date precedes any real run.

_{🤖 Generated with Claude Code (Claude Opus 5.5); posted via @dawsontoth.}

Related PRs: #1801 overlaps (this PR stacks on it)

Complexity: medium

_{Review-Coverage: authored=claude; ran=gemini,codex; blocked=cursor-composer(no-receipt),domain(auth); declined=cursor-grok,cursor-kimi,cursor-muse; rounds=1; full=1 @ 5b0d6a8}

_{Review-Attention: read ~3m (raised: degraded review) @ 5b0d6a8}

[gemini-code-assist]

Code Review

This pull request introduces dynamic polling for custom domain certificate progress, utilizing a 5-second interval during active generation or immediately after a domain change, and a 1-minute interval during idle periods. It also adds corresponding tests and documentation. The review feedback recommends evicting stale entries from the watchingUntil map in getChallengeCertificates.ts to prevent memory accumulation over time as cluster IDs churn.

[gemini-code-assist]

To prevent memory accumulation over time as cluster IDs churn (e.g., due to deletion, rolling replacements, or autoscaling), stale entries in the watchingUntil map should be evicted once they exceed their validity horizon.

export function watchChallengeCertificates(queryClient: QueryClient, clusterId: string) {
	const now = Date.now();
	for (const [id, until] of watchingUntil.entries()) {
		if (until <= now) {
			watchingUntil.delete(id);
		}
	}
	watchingUntil.set(clusterId, now + CERTIFICATE_WATCH_AFTER_DOMAIN_CHANGE_MS);
	return queryClient.invalidateQueries({ queryKey: challengeCertificatesQueryKey(clusterId) });
}

References

1. When caching or tracking state (such as last observation times) for dynamic entities (e.g., cluster nodes) processed in chronological order, evict stale entries once they exceed their validity horizon. This prevents memory accumulation when entity IDs churn (e.g., due to autoscaling or rolling replacements). Ensure that evicted entities can be correctly re-registered if they reappear.

[dawsontoth]

Declining. The only writer is watchChallengeCertificates, called once per successful domain change from setDomainIdsOnCluster's onSuccess (setDomainIdsOnCluster.ts:37). The map is keyed by cluster id, so a repeat overwrites the entry. A tab therefore holds at most one number per cluster its user changed domains on by hand. Nothing here churns the way the referenced autoscaling case does. An expired entry is also already inert, because the read compares it against Date.now() (getChallengeCertificates.ts:41). An eviction pass would add code to save a few bytes on a small, bounded set of entries.

_{🤖 Generated by Claude Code (Claude Opus 5.5); posted via @dawsontoth.}

[github-actions]

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	71.16%	11385 / 15999
🔵	Statements	71.28%	12136 / 17025
🔵	Functions	65.55%	2998 / 4573
🔵	Branches	66.69%	8883 / 13319

File Coverage

File	Stmts	Branches	Functions	Lines	Uncovered Lines
Changed Files
src/features/cluster/domains/Management.tsx	76.82%	84.31%	81.25%	78.2%	87, 96-97, 189-215, 223, 229-230
src/features/cluster/domains/constants/tableDefinition.tsx	81.39%	81.25%	73.33%	82.92%	38-43, 102, 128, 152, 161, 174
src/features/cluster/domains/queries/getChallengeCertificates.ts	94.44%	91.66%	100%	100%	51
src/features/clusters/hooks/useUpdateCluster.ts	0%	100%	0%	0%	12-23
src/features/clusters/mutations/setDomainIdsOnCluster.ts	100%	100%	100%	100%
src/features/clusters/upsert/ClusterBilling.tsx	0%	0%	0%	0%	33-134
src/features/clusters/upsert/ClusterDetails.tsx	0%	0%	0%	0%	62-260
src/features/clusters/upsert/ClusterForm.tsx	0%	0%	0%	0%	72-590
src/features/organization/mutations/deleteDomain.ts	40%	100%	33.33%	40%	11-12, 17
src/features/organization/queries/getOrganizationDomains.ts	100%	100%	100%	100%

Generated in workflow #2246 for commit b2ee95a by the Vitest Coverage Report Action