From bf7560b7a800a6956337e0e64f669e75e2aeb362 Mon Sep 17 00:00:00 2001 From: slhx agent Date: Thu, 11 Jun 2026 22:38:37 +0200 Subject: [PATCH] docs(runtime): align docs with hashed runtime asset Replace fixed /hemx.js wording with helper-provided runtime asset language so docs match hemx-axum runtime_js_path deployment boundaries. req: axum_integration/005 req: examples/001 --- docs/recipes/deploy-versioning.md | 42 ++++++++++++++++++------------- docs/recipes/pwa-offline.md | 9 ++++--- docs/tutorial-saas.md | 4 +-- docs/versioning.md | 7 +++--- examples/kanban.md | 10 ++++---- 5 files changed, 41 insertions(+), 31 deletions(-) diff --git a/docs/recipes/deploy-versioning.md b/docs/recipes/deploy-versioning.md index 19c84dd..3276f15 100644 --- a/docs/recipes/deploy-versioning.md +++ b/docs/recipes/deploy-versioning.md @@ -19,39 +19,46 @@ A compatible release contains: release - templates, CSS, island JavaScript, migrations, and app config for that release -Do not mix a newly built server with an old `/hemx.js`, old generated output, or -old cached page shell. Build fingerprints are derived from Surface/schema/ABI +Do not mix a newly built server with an old runtime asset, old generated output, +or old cached page shell. Build fingerprints are derived from Surface/schema/ABI parts, so mismatches are detected and partial updates fail closed instead of mutating the wrong DOM. req: abi/003 req: abi/004 req: failure/005 ## Asset serving -Serve `/hemx.js` from the same release as the server when possible: +Serve the embedded runtime at the helper-provided fingerprinted path from the +same release as the server: ```rust -async fn runtime() -> impl IntoResponse { - hemx_axum::runtime_js() +use axum::{routing::get, Router}; +use hemx_axum::{runtime_js, runtime_js_path}; + +let app = Router::new().route(runtime_js_path(), get(runtime)); + +async fn runtime() -> impl axum::response::IntoResponse { + runtime_js() } ``` -If a CDN is required, publish the runtime under a content-addressed release path -and keep the page shell pointing at that exact path: +Render page shells with that same `runtime_js_path()` value: ```html - + ``` -Avoid long-lived unversioned CDN caching for `/hemx.js`. If an unversioned path -is used, set a short cache TTL or purge it atomically with the server rollout. -CSS and explicit island scripts should follow the same release path policy. +`runtime_js()` is safe for long-lived caching because the public path includes a +hash of the embedded runtime bytes and the response carries immutable cache +headers. Do not publish app-owned version query strings or a long-lived +unversioned runtime URL. CSS and explicit island scripts should follow the same +release path policy. ## Rolling deploys Rolling deploys are safe when every response serves a self-consistent release. The easiest policy is sticky-by-release routing: -- page HTML, interaction POSTs, SSE/polling endpoints, and `/hemx.js` come from - the same server revision +- page HTML, interaction POSTs, SSE/polling endpoints, and the + `runtime_js_path()` asset come from the same server revision - a load balancer cookie or platform routing key keeps an active browser on one revision during the rollout window - old revisions stay alive until active SSE connections and in-flight forms have @@ -103,9 +110,9 @@ For v1, document changes in three buckets: not leak into beginner docs. req: public_api/002 req: public_api/005 Upgrade notes should explain what changed, whether generated code must be -regenerated, whether `/hemx.js` must be rolled with the server, and what fallback -users see if an old page talks to a new server. Use `docs/versioning.md` as the -release-policy checklist. +regenerated, whether the helper-provided runtime asset must be rolled with the +server, and what fallback users see if an old page talks to a new server. Use +`docs/versioning.md` as the release-policy checklist. ## Deployment checklist @@ -119,7 +126,8 @@ redgate health --strict Then verify deployment-specific behavior: -- page HTML includes the intended `/hemx.js`, CSS, and island asset release paths +- page HTML includes the intended `runtime_js_path()`, CSS, and island asset + release paths - interaction endpoints return the same build fingerprint as the initial root - SSE/polling endpoints stream batches from the same revision - a stale page talking to the new server reloads or navigates instead of applying diff --git a/docs/recipes/pwa-offline.md b/docs/recipes/pwa-offline.md index c783cb3..3ac7ee9 100644 --- a/docs/recipes/pwa-offline.md +++ b/docs/recipes/pwa-offline.md @@ -35,10 +35,11 @@ The normal path remains server-first typed handlers and generated effects. ## Cached shell -A PWA shell may cache page HTML, CSS, the matching `/hemx.js`, and explicit island -scripts for one release. It must obey the same release-unit policy as -`docs/recipes/deploy-versioning.md`: cached server HTML and cached runtime assets -must be compatible with the server that receives later interactions. req: abi/002 req: abi/004 +A PWA shell may cache page HTML, CSS, the matching `runtime_js_path()` asset, and +explicit island scripts for one release. It must obey the same release-unit +policy as `docs/recipes/deploy-versioning.md`: cached server HTML and cached +runtime assets must be compatible with the server that receives later +interactions. req: abi/002 req: abi/004 Recommended behavior: diff --git a/docs/tutorial-saas.md b/docs/tutorial-saas.md index 55d1aca..d40392c 100644 --- a/docs/tutorial-saas.md +++ b/docs/tutorial-saas.md @@ -218,8 +218,8 @@ To move from the local tutorial skeleton to production: `docs/recipes/observability-flags.md`. 4. Add optional PWA/offline behavior only through the adapter boundary in `docs/recipes/pwa-offline.md`. -5. Deploy server, generated output, and `/hemx.js` as one release unit following - `docs/recipes/deploy-versioning.md`. +5. Deploy server, generated output, and the helper-provided runtime asset as one + release unit following `docs/recipes/deploy-versioning.md`. 6. Follow `docs/versioning.md` for semver and upgrade notes. 7. Use `docs/diagnostics.md` when a template/build/derive/runtime mistake fails the app. diff --git a/docs/versioning.md b/docs/versioning.md index 30f4087..098fa4a 100644 --- a/docs/versioning.md +++ b/docs/versioning.md @@ -101,7 +101,8 @@ include upgrade notes with this shape: ### Required actions - Regenerate generated code with `cargo check` or your normal build. -- Deploy server and `/hemx.js` from the same release if ABI/fingerprint changed. +- Deploy server and the helper-provided runtime asset from the same release if + ABI/fingerprint changed. - Update any renamed helpers or advanced calls listed below. ### Compatibility behavior @@ -135,8 +136,8 @@ Before tagging a v1-compatible release: - Any incompatible generated ABI/runtime change bumps the relevant ABI/fingerprint inputs and has tests for fail-closed behavior. req: abi/005 - Advanced APIs touched by the release are still named as escape hatches in docs. -- Upgrade notes state whether users must regenerate code, redeploy `/hemx.js`, or - change app code. +- Upgrade notes state whether users must regenerate code, redeploy the + helper-provided runtime asset, or change app code. ## Policy for v1 cutover diff --git a/examples/kanban.md b/examples/kanban.md index f56ecf3..b91487a 100644 --- a/examples/kanban.md +++ b/examples/kanban.md @@ -283,14 +283,14 @@ the authoring boundary: ... - + ``` The compiler lowers those symbols to compact runtime metadata, but that metadata -is not an app-authoring contract. Runtime attachment: `/hemx.js` installs -delegated root listeners for forms, clicks, and pointer/drag events. App authors -keep composing generated resources; they do not attach per-node listeners, copy -numeric ids, or write selector glue. +is not an app-authoring contract. Runtime attachment: the helper-provided runtime +asset installs delegated root listeners for forms, clicks, and pointer/drag +events. App authors keep composing generated resources; they do not attach +per-node listeners, copy numeric ids, or write selector glue. No framework download. No VDOM. No hydration. No game loop.