realm-server: backfill realm.json card from .realm.json (CS-11150)#4848
realm-server: backfill realm.json card from .realm.json (CS-11150)#4848backspace wants to merge 2 commits into
Conversation
…(CS-11150) The CS-10051 RealmConfig card was added without a migration for existing realm directories — staging shows 661/701 realms still relying entirely on the legacy .realm.json sidecar. This backfill walks each realm directory on boot, writes /realm.json as a RealmConfig card when the card is absent, and trims the migrated fields (name, backgroundURL, iconURL, hostRoutingRules, includePrerenderedDefaultRealmIndex) out of the sidecar. Pre-existing cards are left alone — the card is the source of truth and the backfill never overwrites it. Mirrors realm-metadata-backfill.ts (CS-10053): same advisory-lock pattern (distinct lock id 7331013), same source/published/bootstrap walk, same idempotent-rerun semantics. Unblocks CS-11131 once verified in every environment. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 4b71e3cb69
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| if (!url) { | ||
| continue; |
There was a problem hiding this comment.
In a multi-instance startup wave, one process can skip runRegistryBackfillWithAdvisoryLock (lock held elsewhere) and still win the config-backfill lock, so this published-realm pass may run before realm_registry has the disk_id -> url rows; in that case if (!url) continue drops those realms and they remain unmigrated for that rollout because the process that did finish registry can then skip config-backfill due lock contention. This leaves some published realms without realm.json, which defeats the migration guarantees needed before .realm.json removal.
Useful? React with 👍 / 👎.
Host Test Results 1 files ±0 1 suites ±0 1h 27m 21s ⏱️ - 2m 41s Results for commit ccf3214. ± Comparison against earlier commit 4b71e3c. Realm Server Test Results 1 files ±0 1 suites ±0 9m 5s ⏱️ + 1m 0s Results for commit ccf3214. ± Comparison against earlier commit 4b71e3c. |
1 participant
Summary
realm-server/lib/realm-config-card-backfill.ts: a one-time, boot-time migration that materializes aRealmConfigcard at/realm.jsonfor every realm directory that doesn't have one yet, populating it from the legacy.realm.jsonsidecar. After writing the card it trims the migrated keys (name,backgroundURL,iconURL,hostRoutingRules,includePrerenderedDefaultRealmIndex) out of the sidecar.7331013), same source / published / bootstrap walk, same idempotent-rerun semantics. Skips realms that already have arealm.jsoncard — the card is the source of truth.realm_registry, idempotent rerun, malformed JSON, non-object JSON.Why
CS-10051 introduced the RealmConfig card and switched
parseRealmInfoto prefer it over.realm.json, with the sidecar left as a fallback. No migration was written to create the card for realms that already existed on disk. EFS survey on staging shows 661/701 realm directories (94%) still rely entirely on the legacy sidecar:.realm.jsonrealm.jsoncardRemoving the sidecar today (CS-11131) would strip name/icon/background from those 661 realms. This PR unblocks that.
After this PR ships and is verified-complete in every environment, the module becomes dead code and is removed alongside the sidecar in CS-11131. CS-11131's description has been updated with that cleanup checklist.
Out of scope
.realm.jsonentirely) is gated on this PR + CS-10055 + CS-11151.boxel-home,boxel-catalog,boxel-skillssister repos that still ship their own populated.realm.jsonand needrealm.jsoncards added upstream.Test plan
MATRIX_REGISTRATION_SHARED_SECRET=test-secret TEST_FILES=realm-config-card-backfill-test pnpm --filter @cardstack/realm-server test(11/11 ✓)populated .realm.json + absent realm.jsonrows. (aws-accessskill +boxel-claude-fs-readonlytask)showAsCatalog/publishablein.realm.jsonafter this runs (the metadata-backfill trim should have already converged; if not, separate bug).🤖 Generated with Claude Code