Skip to content

Commit 8f167eb

Browse files
sspickleclaude
sspickle
and
claude
committed
docs: add glowscript.org -> webvpython.org migration plan
Covers moving both zones to Cloudflare, caching Classic's static files, docs on the main domain, a separate runner origin, the database read/write fixes, cutover with legacy.glowscript.org as fallback, and deliberate backports to Classic. Records the verified current state: shared glowscript Datastore, costs, and traffic profile. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QNw6KLiif2r9zSoSQug4iL
1 parent 0367c6b commit 8f167eb

2 files changed

Lines changed: 179 additions & 0 deletions

File tree

‎AGENTS.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,8 @@ Docs: ./webVPythonDocsHome
99

1010
The Flask Host and Runners were synced with Classic GlowScript in June 2026. See `docs/superpowers/specs/2026-06-05-glowscript-migration-sync-design.md` for what was done.
1111

12+
The plan for moving production from glowscript.org to webvpython.org (Cloudflare, cutover, legacy fallback) is in `docs/superpowers/specs/2026-09-26-glowscript-to-webvpython-migration.md`.
13+
1214
## Second public URL: beta.webvpython.org
1315

1416
Added June 2026. Both `https://flaskdstorehost-dhppn6xgeq-uc.a.run.app` and `https://beta.webvpython.org` are live.

‎docs/superpowers/specs/2026-09-26-glowscript-to-webvpython-migration.md‎

Lines changed: 177 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,177 @@
1+
# glowscript.org → webvpython.org Migration Plan
2+
3+
**Date:** 2026-09-26
4+
**Status:** Planning. Nothing below has been executed yet except where marked.
5+
**Supersedes nothing.** The 2026-06-05 sync spec brought flaskHost and the runners up
6+
to date with Classic; this document covers moving production traffic.
7+
8+
---
9+
10+
## End state
11+
12+
| Hostname | Serves | Backend |
13+
|---|---|---|
14+
| `webvpython.org`, `www.webvpython.org` | IDE, API, docs (`/docs/…`) | Cloud Run `flaskdstorehost` (project `glowscript`) |
15+
| `run.webvpython.org` (name TBD) | RS and WASM runners (untrusted user code) | GCS `rswvprunner` / `wmvprunner` via a thin proxy (see Phase 2) |
16+
| `glowscript.org`, `www.glowscript.org` | 301 → `webvpython.org`, path preserved | Cloudflare Redirect Rule (no server) |
17+
| `legacy.glowscript.org` | Classic GlowScript, as a fallback | GAE app, project `glowscript` |
18+
| `sandbox.glowscript.org` | Classic's untrusted runner | GAE app (unchanged) |
19+
20+
All of the above are proxied by Cloudflare.
21+
22+
---
23+
24+
## Current state (verified 2026-09-26)
25+
26+
**Projects**
27+
- `glowscript`: the Classic GAE app (glowscript.org, www, sandbox) **and** the Cloud Run service
28+
`flaskdstorehost` (beta.webvpython.org, via a Cloud Run domain mapping created 2026-06-11).
29+
- `glowscript-py38`: the GAE app for glowscriptdev.spvi.net, plus the GCS buckets `rswvprunner`,
30+
`wmvprunner`, `glow-docs`.
31+
32+
**One shared database.** Classic (`main.py:22`, `ide/routes.py:75`) and flaskHost
33+
(`src/ndb_models.py:21`) both call `ndb.Client(project=None)`, so each uses its own GCP
34+
project's Datastore, and both run in project `glowscript`. Beta and Classic read and write the
35+
same users, folders and programs. This is what makes `legacy.glowscript.org` a real fallback: a
36+
user who goes back sees the same work.
37+
38+
> ⚠️ `make serve-prod` points local Flask at **`glowscript-py38`**, not `glowscript`, even though
39+
> it warns about "LIVE production data". Billing shows almost no reads in `glowscript-py38`, so
40+
> it looks like the glowscriptdev database. Decide whether that is intended (a safer prod-like
41+
> copy) and fix either the target or the warning.
42+
43+
**DNS.** Both `glowscript.org` and `webvpython.org` are at GoDaddy (`domaincontrol.com`), with
44+
no DNSSEC (no DS records), so there's no DNSSEC to switch off before changing nameservers.
45+
`webvpython.org` apex is a GoDaddy forward page; `beta.webvpython.org` is a CNAME to
46+
`ghs.googlehosted.com`.
47+
48+
**Cost, Classic GAE** (Cloud Billing export `instructormi.billing.gcp_billing_export_v1_*`):
49+
50+
| Month | App Engine total | Firestore reads+writes | Instances | Out bandwidth |
51+
|---|---|---|---|---|
52+
| 2026-08 | $15.99 | $7.01 | $5.50 | $2.08 (46.7 GB) |
53+
| 2026-09 (26 days) | $37.80 | $17.47 | $12.43 | $6.94 (88.7 GB) |
54+
55+
Beta (`flaskdstorehost` + buckets) costs pennies today, but it has almost no traffic yet.
56+
57+
**Classic traffic profile** (sample of 5,000 requests, 2026-09-26):
58+
- About **95% of outgoing bytes are `/package/*` (82%) and `/lib/*` (13%)**. A single package
59+
file is ~4.4 MB and is served with `Cache-Control: public, max-age=600`, so browsers fetch
60+
it again after 10 minutes.
61+
- The most frequent API call is **`PUT …/program/<name>` (autosave)**, about 2× program GETs.
62+
The IDE saves 1 s after typing stops (`ide/ide.js:1466`), and each save does 3–4 reads plus a
63+
write. Two of those reads are the same User entity, once in `parseUrlPath` and again in
64+
`authorize_user`.
65+
- Background noise: `/wp-admin`, `/.aws`, `/.well-known` scans.
66+
67+
---
68+
69+
## Constraints
70+
71+
1. **The runner must stay on a different origin from the IDE.** The runner executes student
72+
code, and the IDE origin holds the session cookie and returns the CSRF secret from
73+
`/api/login`. Classic does this with `sandbox.glowscript.org`; the new stack must keep a
74+
separate hostname (`run.webvpython.org` or similar). Docs are trusted content and can live
75+
on the IDE origin.
76+
2. **Legacy stays independent.** The fallback only helps if a bug in the new stack doesn't
77+
also break it. Don't make Classic load its runtime from the new runner buckets; copy fixes
78+
to it deliberately (Phase 5).
79+
3. **Allowed-origin lists must be updated together:** runner `build.env` `TRUSTED_HOST`
80+
(rsWVPRunner and wmWVPRunner), Google OAuth authorized redirect URIs, and Classic's
81+
sandbox parent-origin check if `legacy.glowscript.org` is to use `sandbox.glowscript.org`.
82+
4. **Logins don't carry over.** Session cookies are per domain, so users signed in on
83+
glowscript.org sign in again on webvpython.org. Programs are unaffected (shared database).
84+
85+
---
86+
87+
## Phases
88+
89+
Each phase is independently deployable and reversible.
90+
91+
### Phase 0: Move both zones to Cloudflare (no behavior change)
92+
93+
Same procedure as the trinket migration (see the Cloudflare CDN runbook on the Desktop,
94+
2026-09-20):
95+
1. Export each zone from GoDaddy; import into Cloudflare; verify record by record.
96+
2. SSL/TLS **Full (strict)**, per zone.
97+
3. Flip nameservers at GoDaddy.
98+
4. Turn on the Cloudflare proxy (orange cloud) record by record, checking each host.
99+
100+
**Certificate renewal.** GAE and Cloud Run domain mappings use Google-managed certificates.
101+
Check that they keep renewing once proxied. If one doesn't, upload a Cloudflare **Origin CA**
102+
certificate (valid 15 years) to GAE (`gcloud app ssl-certificates create`, then set the
103+
domain mapping to manual certificates). Don't use Flexible mode.
104+
105+
### Phase 1: Cache Classic's static files at the edge (glowscript.org)
106+
107+
The immediate win, since Classic carries all the real traffic until cutover.
108+
- Cache Rule (operator **wildcard**, not `equals`): `/package/*`, `/lib/*`, `/css/*`
109+
→ eligible for cache, Edge TTL override **1 day**.
110+
- Package files are rebuilt under the same name (e.g. `glow.3.2.min.js`), so **purge the
111+
Cloudflare cache after every Classic deploy** (dashboard button or API). Add that step to
112+
whatever deploys Classic.
113+
- Optional: set `default_expiration` in `app.yaml` so browsers keep files longer than 10 min.
114+
- Expected effect: most of the 88.7 GB/month of GAE egress stops reaching Google.
115+
116+
### Phase 2: New-stack hostnames and docs on the main domain
117+
118+
- **Docs:** serve `/docs/…` from `flaskdstorehost` (proxying `glow-docs`), so docs share the
119+
IDE's URL. With Cloudflare caching `/docs/*`, Cloud Run sees only cache misses.
120+
- **Runners:** a separate hostname. Either a tiny Cloud Run proxy that reads the buckets, or
121+
keep `storage.googleapis.com` for now. Avoid a Google Cloud Load Balancer with backend
122+
buckets: its forwarding rule costs ~$18/month before any traffic.
123+
- **Cache headers:** GCS sends `max-age=3600` by default, and `rsWVPRunner/do_build.sh` uploads
124+
with `gsutil cp -r`, which never deletes stale objects and sets no `Cache-Control`. Either set
125+
cache-control on upload and rely on the build-date stamp in `run.js`, or purge after each
126+
runner deploy.
127+
- Update `build.env` in both runners and the OAuth redirect URIs for the new hostnames.
128+
- Move `OAUTH_CLIENT_SECRET` on `flaskdstorehost` from a plain env var to Secret Manager.
129+
130+
### Phase 3: Cut database reads and writes (flaskHost first)
131+
132+
flaskHost copied Classic's pattern (`src/routes.py:357` in `parseUrlPath`, `:272` in
133+
`authorize_user`). Fix it there, since that's where traffic is going:
134+
1. Fetch the User once per request (share it between `parseUrlPath` and `authorize_user`).
135+
2. Autosave: don't `PUT` if the source hasn't changed since the last save; consider a longer
136+
debounce than 1 s (`src/ide.js:1673`, `:2102`).
137+
3. Measure before and after from the billing export (Firestore Read Ops / Entity Writes).
138+
139+
Optional: backport to Classic, which pays the bill today.
140+
141+
### Phase 4: Cutover
142+
143+
1. `webvpython.org` + `www` → `flaskdstorehost` (Cloud Run domain mappings; keep `beta.` too).
144+
2. Map `legacy.glowscript.org` to the GAE app; add it to OAuth redirect URIs and to the
145+
sandbox's allowed parents.
146+
3. Cloudflare Redirect Rule: `glowscript.org/*` and `www.glowscript.org/*` →
147+
`https://webvpython.org/$1`, 301. Program links are hash-based (`/#/user/…`); browsers carry
148+
the fragment across a redirect, so deep links keep working.
149+
4. Announce `legacy.glowscript.org` as the way back.
150+
151+
**Rollback:** delete the redirect rule. glowscript.org serves Classic again immediately, and no
152+
data needs migrating because the database is shared.
153+
154+
**Check before cutover:** third-party pages that embed glowscript.org in iframes. A redirect
155+
works for top-level pages, but confirm embeds follow it and are allowed to be framed on
156+
webvpython.org.
157+
158+
### Phase 5: Keep legacy in sync, deliberately
159+
160+
`rsWVPRunner` is now ahead of Classic (vec kwargs, acorn fix, `print()` messages). Add a
161+
`make sync-classic` target that copies `rsWVPRunner/package/` and `rsWVPRunner/lib/` into
162+
`glowscript/` for review, commit and deploy, then purges Cloudflare. Run it only when you've
163+
decided a fix belongs in legacy.
164+
165+
### Phase 6: Retire (later)
166+
167+
Once legacy traffic is negligible: remove the GAE domain mappings and disable the app. With
168+
automatic scaling and no minimum instances, an idle GAE app costs almost nothing, so there's no
169+
rush.
170+
171+
---
172+
173+
## Open questions
174+
175+
- `make serve-prod` database target (see Current state).
176+
- Final name for the runner hostname.
177+
- Whether Classic should get the Phase 3 database fixes.

0 commit comments

Comments
 (0)