From 64a2a6f779a79489bcd7b7f2d76470aad03bb5cf Mon Sep 17 00:00:00 2001 From: Kelvin Amoaba <97001695+AmoabaKelvin@users.noreply.github.com> Date: Tue, 10 Nov 2026 03:52:19 +0000 Subject: [PATCH] perf(mobile): let newer phones fetch their language catalog from the desktop instead of downloading all of them (#40519) * perf(mobile): let newer phone shells fetch the language catalog from the desktop instead of downloading all of them * fix(mobile): hash only the buildId fields so phone readers can recompute it * fix(mobile): use the catalog chunk when the generation still has it * fix(desktop): give catalog reads their own read-slot budget --- .../build-mobile-web-app-bundle.mjs | 38 ++- .../mobile-web-bundle-manifest.mjs | 26 +- .../verify-mobile-web-app-bundle.mjs | 19 ++ .../verify-packaged-mobile-web-bundle.cjs | 22 +- .../server-bundle/orcad-mobile-web-bundle.mjs | 2 +- mobile/src/i18n/bundled-locale-catalogs.ts | 23 ++ mobile/src/i18n/locale-catalog-imports.ts | 26 +- mobile/src/i18n/locale-catalog-imports.web.ts | 36 +++ mobile/src/i18n/mobile-i18n.test.ts | 3 +- mobile/src/i18n/mobile-i18n.ts | 14 +- .../i18n/page-locale-catalog-source.test.ts | 218 ++++++++++++++ mobile/src/i18n/page-locale-catalog-source.ts | 265 ++++++++++++++++++ .../mobile-web-shell/bridge-host-init.test.ts | 1 + .../bridge-host-native-verbs.test.ts | 2 +- mobile/src/mobile-web-shell/bridge-host.ts | 9 +- .../bridge/bridge-envelope.ts | 4 +- .../bridge/bridge-frame-fields.ts | 10 + .../bridge/bridge-init-frame.ts | 6 +- .../generation-manifest-read.ts | 6 +- .../generation-staging-assets.ts | 3 +- .../mobile-web-shell/generation-store.test.ts | 26 +- .../mobile-web-shell-session-effects.ts | 10 +- .../mobile-web-bundle-fetch.test.ts | 18 +- .../web-bundle/mobile-web-bundle-fetch.ts | 17 +- .../mobile-web-bundle-reply-schemas.ts | 12 +- .../mobile-web-bundle-window-reader.ts | 9 +- mobile/web-entry/index.tsx | 10 +- .../mobile-web-bundle.test-fixture.ts | 20 +- .../mobile-delivery/mobile-web-bundle.test.ts | 41 +++ .../mobile-delivery/mobile-web-bundle.ts | 53 +++- ...ntime-rpc-mobile-paired-desktop-methods.ts | 1 + .../locale-catalog-contract.ts | 29 ++ .../mobile-web-bundle/manifest-contract.ts | 43 ++- src/shared/orcad-artifacts.test.ts | 12 + src/shared/orcad-artifacts.ts | 9 +- .../rpc-params-catalog.generated.ts | 2 + 36 files changed, 964 insertions(+), 81 deletions(-) create mode 100644 mobile/src/i18n/bundled-locale-catalogs.ts create mode 100644 mobile/src/i18n/locale-catalog-imports.web.ts create mode 100644 mobile/src/i18n/page-locale-catalog-source.test.ts create mode 100644 mobile/src/i18n/page-locale-catalog-source.ts create mode 100644 src/shared/mobile-web-bundle/locale-catalog-contract.ts diff --git a/config/scripts/build/mobile-web-app/build-mobile-web-app-bundle.mjs b/config/scripts/build/mobile-web-app/build-mobile-web-app-bundle.mjs index 605d2ac7816..4b1a1d008b8 100644 --- a/config/scripts/build/mobile-web-app/build-mobile-web-app-bundle.mjs +++ b/config/scripts/build/mobile-web-app/build-mobile-web-app-bundle.mjs @@ -1,4 +1,4 @@ -import { readFile } from 'node:fs/promises' +import { readFile, readdir } from 'node:fs/promises' import { readRouteSnapshot } from '../../mobile-web-app/mobile-web-app-route-snapshot.mjs' import { MOBILE_WEB_APP_DEPENDENCY_PATH } from '../../mobile-web-app/mobile-web-app-bundle-dependencies.mjs' import { existsSync, realpathSync } from 'node:fs' @@ -457,6 +457,32 @@ export async function mobileWebAppModuleClosure(entryModules, { absWorkingDir } // One lazily imported chunk per UI language; the page fetches only the active one after init. const LOCALE_CATALOG_INPUT = /(^|\/)src\/i18n\/locales\/[^/]+\.json$/ +const localeCatalogDir = join(mobileDir, 'src', 'i18n', 'locales') + +// The same catalogs as JSON for the host to serve one at a time, to shells that skip the chunks; +// English is the page's inline fallback, so it has none. +export async function readLocaleCatalogs(directory = localeCatalogDir) { + const names = (await readdir(directory)) + .filter((name) => name.endsWith('.json') && name !== 'en.json') + .sort() + return Promise.all( + names.map(async (name) => { + // Minify: the host sends and the phone keeps the parsed object, not the source layout. + const bytes = Buffer.from( + JSON.stringify(JSON.parse(await readFile(join(directory, name), 'utf8'))), + 'utf8' + ) + const sha256 = sha256Hex(bytes) + return { + locale: name.slice(0, -'.json'.length), + bytes, + path: `catalogs/${sha256}.json`, + sha256, + byteLength: bytes.byteLength + } + }) + ) +} function localeCatalogOutputs(metafile) { return new Set( @@ -586,11 +612,13 @@ export async function buildMobileWebAppBundle({ desktopVersion, protocolWindow, { script, chunks, images, catalogChunks, entryStaticBytes, chunkCount, routeChunks, routeKeys }, + catalogs, scrollbarStyle ] = await Promise.all([ readDesktopVersion(), readProtocolWindow(), bundleMobileWebApp({ appDir }), + readLocaleCatalogs(), readFile(join(projectDir, 'src/shared/styles/scrollbar-sleek.css'), 'utf8').then((style) => // The shared desktop stylesheet can be checked out as CRLF on Windows. style.replace(/\r\n/g, '\n') @@ -598,9 +626,14 @@ export async function buildMobileWebAppBundle({ ]) // Names already hash final bytes, so hashedAsset must reproduce them. const scriptAsset = hashedAsset(script, 'js') + const catalogChunkSet = new Set(catalogChunks) const written = [ scriptAsset, - ...[...chunks, ...images].map(({ name, bytes }) => hashedAsset(bytes, extname(name).slice(1))) + ...[...chunks, ...images].map((output) => ({ + ...hashedAsset(output.bytes, extname(output.name).slice(1)), + // Shells that read catalogs from the host skip these; older shells download them as before. + ...(catalogChunkSet.has(output) ? { kind: 'catalog' } : {}) + })) ] // Root-absolute URLs survive nested routes; CSP allows only about: base. ESM entry/chunks load under existing self policy. @@ -624,6 +657,7 @@ export async function buildMobileWebAppBundle({ const { manifest } = await writeMobileWebBundleTree({ outDir, written: [indexAsset, ...written], + catalogs, desktopVersion, protocolWindow, routes: resolveMobileWebPageRoutes(routeKeys, pageRoutes), diff --git a/config/scripts/build/mobile-web-app/mobile-web-bundle-manifest.mjs b/config/scripts/build/mobile-web-app/mobile-web-bundle-manifest.mjs index 4504d345fd4..ad84a39bd02 100644 --- a/config/scripts/build/mobile-web-app/mobile-web-bundle-manifest.mjs +++ b/config/scripts/build/mobile-web-app/mobile-web-bundle-manifest.mjs @@ -133,6 +133,8 @@ async function compressWithBrotli(written) { export async function writeMobileWebBundleTree({ outDir, written, + // Host-only JSON outside `assets` and buildId, served one at a time over RPC. + catalogs = [], desktopVersion, protocolWindow, // Empty route list makes shell render every screen natively. @@ -143,14 +145,15 @@ export async function writeMobileWebBundleTree({ }) { const brotliCopies = brotli ? await compressWithBrotli(written) : new Map() const assets = written - .map(({ path, sha256, byteLength, contentType }) => { + .map(({ path, sha256, byteLength, contentType, kind }) => { const copy = brotliCopies.get(path) return { path, sha256, byteLength, contentType, - ...(copy === undefined ? {} : { brotliByteLength: copy.byteLength }) + ...(copy === undefined ? {} : { brotliByteLength: copy.byteLength }), + ...(kind === undefined ? {} : { kind }) } }) .sort((left, right) => (left.path < right.path ? -1 : left.path > right.path ? 1 : 0)) @@ -164,14 +167,27 @@ export async function writeMobileWebBundleTree({ entrypoint: MOBILE_WEB_BUNDLE_ENTRYPOINT, totalBytes: assets.reduce((total, asset) => total + asset.byteLength, 0), assets, - routes + routes, + ...(catalogs.length === 0 + ? {} + : { + catalogs: catalogs.map(({ locale, path, sha256, byteLength }) => ({ + locale, + path, + sha256, + byteLength + })) + }) } // Clear entire output or stale unreferenced assets ship inside asar. await rm(outDir, { recursive: true, force: true }) await mkdir(join(outDir, 'assets'), { recursive: true }) - for (const asset of written) { - await writeFile(join(outDir, asset.path), asset.bytes) + if (catalogs.length > 0) { + await mkdir(join(outDir, 'catalogs'), { recursive: true }) + } + for (const file of [...written, ...catalogs]) { + await writeFile(join(outDir, file.path), file.bytes) } for (const [path, copy] of brotliCopies) { await writeFile(join(outDir, mobileWebBundleBrotliPath(path)), copy) diff --git a/config/scripts/build/mobile-web-app/verify-mobile-web-app-bundle.mjs b/config/scripts/build/mobile-web-app/verify-mobile-web-app-bundle.mjs index b853a7d7a88..b6832054702 100644 --- a/config/scripts/build/mobile-web-app/verify-mobile-web-app-bundle.mjs +++ b/config/scripts/build/mobile-web-app/verify-mobile-web-app-bundle.mjs @@ -29,6 +29,8 @@ export function mobileWebAppBundleMaxAssets(routeCount, imageCount, catalogChunk // fetched only for the active language, never before the first route. Code keeps its own fence. export const MOBILE_WEB_APP_BUNDLE_MAX_CATALOG_CHUNKS = 10 export const MOBILE_WEB_APP_BUNDLE_MAX_CATALOG_BYTES = 3 * 1024 * 1024 +// The host sends a catalog's JSON in one reply, which must fit a 1 MiB relay frame once encrypted. +export const MOBILE_WEB_APP_HOST_CATALOG_MAX_BYTES = 384 * 1024 // Our own fence on the page's code, well inside the phone contract (32 MiB total, 10 MiB per asset in // manifest-contract.ts); it fails the build before the code weighs more than any one asset may. @@ -185,6 +187,23 @@ export async function verifyMobileWebAppBundle({ bundleDir = defaultBundleDir } `${String(MOBILE_WEB_APP_BUNDLE_MAX_CATALOG_BYTES)} bytes` ) } + // buildId leaves the host's JSON catalogs out, so a stale copy shows only here. + const hostCatalogsOf = (built) => JSON.stringify(built.catalogs ?? []) + if (hostCatalogsOf(first.manifest) !== hostCatalogsOf(second.manifest)) { + fail('host language catalogs are not reproducible') + } + if (hostCatalogsOf(first.manifest) !== hostCatalogsOf(manifest)) { + fail(`${bundleDir} is stale: its host language catalogs differ from a fresh build's`) + } + const oversized = (manifest.catalogs ?? []).find( + (catalog) => catalog.byteLength > MOBILE_WEB_APP_HOST_CATALOG_MAX_BYTES + ) + if (oversized) { + fail( + `the ${oversized.locale} host catalog is ${String(oversized.byteLength)} bytes, over the ` + + `${String(MOBILE_WEB_APP_HOST_CATALOG_MAX_BYTES)} one reply carries` + ) + } const budgetBytes = mobileWebAppBundleBudgetBytes(manifest) - first.catalogBytes if (budgetBytes > MOBILE_WEB_APP_BUNDLE_MAX_TOTAL_BYTES) { fail( diff --git a/config/scripts/desktop-distribution/runtime-verification/verify-packaged-mobile-web-bundle.cjs b/config/scripts/desktop-distribution/runtime-verification/verify-packaged-mobile-web-bundle.cjs index 769e1c90235..46370dc1d46 100644 --- a/config/scripts/desktop-distribution/runtime-verification/verify-packaged-mobile-web-bundle.cjs +++ b/config/scripts/desktop-distribution/runtime-verification/verify-packaged-mobile-web-bundle.cjs @@ -106,6 +106,19 @@ function parseManifest(bundleDir) { } } } + if (manifest.catalogs !== undefined && !Array.isArray(manifest.catalogs)) { + throw failure('manifest catalogs is not a list') + } + for (const catalog of manifest.catalogs ?? []) { + if (typeof catalog !== 'object' || catalog === null || typeof catalog.locale !== 'string') { + throw failure('manifest catalog entry has no locale') + } + assertSafeRelativePath(catalog.path) + if (typeof catalog.sha256 !== 'string' || !SHA256_PATTERN.test(catalog.sha256)) { + throw failure(`manifest catalog ${catalog.path} has no sha256 digest`) + } + assertInteger(catalog.byteLength, `catalogs[${catalog.path}].byteLength`) + } if (!manifest.assets.some((asset) => asset.path === manifest.entrypoint)) { throw failure(`manifest entrypoint ${manifest.entrypoint} is not one of its assets`) } @@ -126,6 +139,11 @@ function parseManifest(bundleDir) { return manifest } +// Assets go to the phone; catalogs stay on the host, which serves one on request. +function servedFiles(manifest) { + return [...manifest.assets, ...(manifest.catalogs ?? [])] +} + function listBundleFiles(directory, prefix = '') { const found = [] for (const entry of readdirSync(directory, { withFileTypes: true })) { @@ -164,7 +182,7 @@ function assertNoUnlistedFiles(bundleDir, manifest) { const listed = new Set([ 'manifest.json', ...darkBuildMarkerFileNames(), - ...manifest.assets.map((asset) => asset.path), + ...servedFiles(manifest).map((file) => file.path), ...brotliCopies(manifest).map((asset) => brotliPath(asset)) ]) const strays = listBundleFiles(bundleDir).filter((path) => !listed.has(path)) @@ -180,7 +198,7 @@ function assertNoUnlistedFiles(bundleDir, manifest) { function assertMobileWebBundleBuilt(bundleDir = MOBILE_WEB_BUNDLE_DIR) { const manifest = parseManifest(bundleDir) assertNoUnlistedFiles(bundleDir, manifest) - for (const asset of manifest.assets) { + for (const asset of servedFiles(manifest)) { const assetPath = join(bundleDir, asset.path) const size = statSize(bundleDir, asset.path) if (size !== asset.byteLength) { diff --git a/config/scripts/orcad-distribution/server-bundle/orcad-mobile-web-bundle.mjs b/config/scripts/orcad-distribution/server-bundle/orcad-mobile-web-bundle.mjs index dd94c56f62e..7fa363a1907 100644 --- a/config/scripts/orcad-distribution/server-bundle/orcad-mobile-web-bundle.mjs +++ b/config/scripts/orcad-distribution/server-bundle/orcad-mobile-web-bundle.mjs @@ -19,7 +19,7 @@ export function stageOrcadMobileWebBundle(outputDir, bundleDir = MOBILE_WEB_BUND // The release template refuses the variable itself. assertNoDarkOutputOfOffSwitches([bundleDir]) assertMobileWebBundleBuilt(bundleDir) - // The guard refuses unlisted files, so the tree is the manifest, its assets and a dark marker. + // The guard refuses unlisted files, so the tree is the manifest, its assets and catalogs, and a dark marker. cpSync(bundleDir, join(outputDir, ...ORCAD_MOBILE_WEB_DIR.split('/')), { recursive: true }) } diff --git a/mobile/src/i18n/bundled-locale-catalogs.ts b/mobile/src/i18n/bundled-locale-catalogs.ts new file mode 100644 index 00000000000..5883e969ed4 --- /dev/null +++ b/mobile/src/i18n/bundled-locale-catalogs.ts @@ -0,0 +1,23 @@ +import type { SupportedUiLocale } from '../../../src/shared/ui-locale' + +export type LocaleCatalog = Readonly> + +// Literal specifiers: Metro evaluates only the chosen module, and the page build splits each into its own chunk. +const CATALOG_IMPORTS: Record, () => Promise> = { + de: () => import('./locales/de.json').then((module) => module.default), + es: () => import('./locales/es.json').then((module) => module.default), + fr: () => import('./locales/fr.json').then((module) => module.default), + ja: () => import('./locales/ja.json').then((module) => module.default), + ko: () => import('./locales/ko.json').then((module) => module.default), + pt: () => import('./locales/pt.json').then((module) => module.default), + ru: () => import('./locales/ru.json').then((module) => module.default), + tr: () => import('./locales/tr.json').then((module) => module.default), + zh: () => import('./locales/zh.json').then((module) => module.default), + 'zh-Hant': () => import('./locales/zh-Hant.json').then((module) => module.default) +} + +export function importBundledLocaleCatalog( + locale: Exclude +): Promise { + return CATALOG_IMPORTS[locale]() +} diff --git a/mobile/src/i18n/locale-catalog-imports.ts b/mobile/src/i18n/locale-catalog-imports.ts index 664d608019e..d89bb938fea 100644 --- a/mobile/src/i18n/locale-catalog-imports.ts +++ b/mobile/src/i18n/locale-catalog-imports.ts @@ -1,23 +1,9 @@ import type { SupportedUiLocale } from '../../../src/shared/ui-locale' +import type { LocaleCatalog } from './bundled-locale-catalogs' -export type LocaleCatalog = Readonly> +export { importBundledLocaleCatalog as importLocaleCatalog } from './bundled-locale-catalogs' -// Literal specifiers: Metro evaluates only the chosen module, and the page build splits each into its own chunk. -const CATALOG_IMPORTS: Record, () => Promise> = { - de: () => import('./locales/de.json').then((module) => module.default), - es: () => import('./locales/es.json').then((module) => module.default), - fr: () => import('./locales/fr.json').then((module) => module.default), - ja: () => import('./locales/ja.json').then((module) => module.default), - ko: () => import('./locales/ko.json').then((module) => module.default), - pt: () => import('./locales/pt.json').then((module) => module.default), - ru: () => import('./locales/ru.json').then((module) => module.default), - tr: () => import('./locales/tr.json').then((module) => module.default), - zh: () => import('./locales/zh.json').then((module) => module.default), - 'zh-Hant': () => import('./locales/zh-Hant.json').then((module) => module.default) -} - -export function importLocaleCatalog( - locale: Exclude -): Promise { - return CATALOG_IMPORTS[locale]() -} +// Bundled catalogs never change after their import, so none arrives later; the page build's .web.ts does. +export const onLocaleCatalogArrival: ( + listener: (locale: Exclude, catalog: LocaleCatalog) => void +) => () => void = () => () => undefined diff --git a/mobile/src/i18n/locale-catalog-imports.web.ts b/mobile/src/i18n/locale-catalog-imports.web.ts new file mode 100644 index 00000000000..9b3d85fdce2 --- /dev/null +++ b/mobile/src/i18n/locale-catalog-imports.web.ts @@ -0,0 +1,36 @@ +import type { SupportedUiLocale } from '../../../src/shared/ui-locale' +import { importBundledLocaleCatalog, type LocaleCatalog } from './bundled-locale-catalogs' + +// A shell that skips the catalog chunks has page-locale-catalog-source.ts read them from the desktop +// and the device store; other shells import the chunk as before. No transport here, so pages that +// only translate pull in none. +export type { LocaleCatalog } +type CatalogLocale = Exclude +type CatalogLoader = (locale: CatalogLocale) => Promise +type ArrivalListener = (locale: CatalogLocale, catalog: LocaleCatalog) => void + +let loader: CatalogLoader | null = null +const arrivalListeners = new Set() + +export function publishPageLocaleCatalogLoader(next: CatalogLoader): void { + loader = next +} + +// Resolve the catalog or reject so activation falls back to English. +export function importLocaleCatalog(locale: CatalogLocale): Promise { + return loader === null ? importBundledLocaleCatalog(locale) : loader(locale) +} + +// A catalog that arrives after activation settled: a newer copy, or the first one after an offline start. +export function onLocaleCatalogArrival(listener: ArrivalListener): () => void { + arrivalListeners.add(listener) + return () => { + arrivalListeners.delete(listener) + } +} + +export function announceLocaleCatalog(locale: CatalogLocale, catalog: LocaleCatalog): void { + for (const listener of arrivalListeners) { + listener(locale, catalog) + } +} diff --git a/mobile/src/i18n/mobile-i18n.test.ts b/mobile/src/i18n/mobile-i18n.test.ts index a2906b02959..08e08089f53 100644 --- a/mobile/src/i18n/mobile-i18n.test.ts +++ b/mobile/src/i18n/mobile-i18n.test.ts @@ -7,7 +7,8 @@ vi.mock('./locale-catalog-imports', () => ({ importLocaleCatalog: (locale: string) => failing.has(locale) ? Promise.reject(new Error('missing chunk')) - : new Promise((resolve) => pending.set(locale, resolve)) + : new Promise((resolve) => pending.set(locale, resolve)), + onLocaleCatalogArrival: () => () => undefined })) const { activateMobileUiLocale, getMobileUiLocale, mobileI18n, translate } = diff --git a/mobile/src/i18n/mobile-i18n.ts b/mobile/src/i18n/mobile-i18n.ts index c3f58905000..d3a5b94be34 100644 --- a/mobile/src/i18n/mobile-i18n.ts +++ b/mobile/src/i18n/mobile-i18n.ts @@ -3,7 +3,7 @@ import { resolvePluralFamilyKey } from '../../../src/shared/i18n-plural-family' import { pseudoLocalizeString } from '../../../src/shared/pseudo-localization' import { DEFAULT_UI_LOCALE, type SupportedUiLocale } from '../../../src/shared/ui-locale' import enRuntimeRequired from './en-runtime-required.json' -import { importLocaleCatalog } from './locale-catalog-imports' +import { importLocaleCatalog, onLocaleCatalogArrival } from './locale-catalog-imports' export type Translate = (key: string, fallback: string, options?: TOptions) => string @@ -83,10 +83,12 @@ export function subscribeMobileUiLanguage(listener: () => void): () => void { } let activationRequest = 0 +let requestedLocale: SupportedUiLocale = DEFAULT_UI_LOCALE // Latest request wins: an older catalog import that settles later must not replace a newer choice. export async function activateMobileUiLocale(locale: SupportedUiLocale): Promise { const request = ++activationRequest + requestedLocale = locale try { if (locale !== 'en' && !mobileI18n.hasResourceBundle(locale, 'translation')) { const catalog = await importLocaleCatalog(locale) @@ -115,6 +117,16 @@ export async function activateMobileUiLocale(locale: SupportedUiLocale): Promise publish() } +// Switch in place, without a reload: a newer copy replaces the shown one, a first copy replaces the English fallback. +// Install it even when another language is up now, so switching back shows the newer copy. +onLocaleCatalogArrival((locale, catalog) => { + mobileI18n.removeResourceBundle(locale, 'translation') + mobileI18n.addResourceBundle(locale, 'translation', catalog, false, true, { skipCopy: true }) + if (locale === requestedLocale) { + void activateMobileUiLocale(locale) + } +}) + // Development-only layout check: accents and pads every string so clipping shows on device. export function setMobilePseudoLocalization(enabled: boolean): void { if (pseudoLocalization !== enabled) { diff --git a/mobile/src/i18n/page-locale-catalog-source.test.ts b/mobile/src/i18n/page-locale-catalog-source.test.ts new file mode 100644 index 00000000000..d69a92dc1b2 --- /dev/null +++ b/mobile/src/i18n/page-locale-catalog-source.test.ts @@ -0,0 +1,218 @@ +import { describe, expect, it, vi } from 'vitest' +import type { ConnectionState } from '../transport/connection/connection-state' +import type { RpcResponse } from '../transport/rpc/rpc-wire-types' +import { + decodeDeviceStoreValue, + encodeDeviceStoreValue +} from '../device-store/device-store-value-codec' +import type { PageDeviceStore } from '../mobile-web-shell/bridge/page-device-store' + +// The page build resolves mobile-i18n's catalog import to the .web module; mirror that here. +vi.mock('./locale-catalog-imports', () => import('./locale-catalog-imports.web')) +// A shell that skipped the catalog chunks: only locales listed here are on disk. +const chunksOnDisk = new Map>() +vi.mock('./bundled-locale-catalogs', () => ({ + importBundledLocaleCatalog: async (locale: string) => { + const catalog = chunksOnDisk.get(locale) + if (!catalog) { + throw new Error('not on disk') + } + return catalog + } +})) + +const OLD_SHA = 'a'.repeat(64) +const NEW_SHA = 'b'.repeat(64) + +type SentRequest = { + method: string + params: unknown + reply: (response: RpcResponse) => void + fail: (error: Error) => void +} + +function fakeClient(initial: ConnectionState) { + let state = initial + let generation = 1 + const listeners = new Set<(next: ConnectionState) => void>() + const sent: SentRequest[] = [] + return { + sent, + getState: () => state, + getGeneration: () => generation, + onStateChange: (listener: (next: ConnectionState) => void) => { + listeners.add(listener) + return () => { + listeners.delete(listener) + } + }, + sendRequest: (method: string, params?: unknown) => + new Promise((reply, fail) => sent.push({ method, params, reply, fail })), + moveTo(next: ConnectionState) { + state = next + for (const listener of listeners) { + listener(next) + } + }, + // The shell swaps in an already-connected replacement, as on a relay-to-LAN move. + cutover() { + generation += 1 + for (const listener of listeners) { + listener('connected') + } + } + } +} + +function fakeStore(rows: Record): PageDeviceStore & { rows: Map } { + const stored = new Map(Object.entries(rows)) + return { + rows: stored, + available: () => true, + read: async (_table, keys) => ({ + status: 'ok', + values: keys.map((key) => stored.get(key) ?? null) + }), + write: async (_table, ops) => { + for (const op of ops) { + if (op.value !== null) { + stored.set(op.key, op.value) + } + } + return { written: true } + } + } +} + +const { startPageLocaleCatalogs } = await import('./page-locale-catalog-source') +const i18n = await import('./mobile-i18n') + +// Module state outlives a test, so each test uses its own locale and publishes its own source. +function openPage(client: ReturnType, store: PageDeviceStore): void { + startPageLocaleCatalogs({ client, store }) +} + +// Microtasks, then one macrotask, which is when the store write runs. +async function settle(): Promise { + for (let turn = 0; turn < 20; turn++) { + await Promise.resolve() + } + await new Promise((resolve) => setTimeout(resolve, 0)) +} + +describe('the page language catalog', () => { + it('opens on the stored copy, then switches in place to the desktop newer one', async () => { + const client = fakeClient('connected') + const store = fakeStore({ + 'i18n-catalog:de': encodeDeviceStoreValue({ + v: 1, + sha256: OLD_SHA, + catalog: { greeting: 'Hallo' } + }) + }) + openPage(client, store) + + await i18n.activateMobileUiLocale('de') + expect(i18n.translate('greeting', 'Hello')).toBe('Hallo') + expect(client.sent.map(({ method, params }) => ({ method, params }))).toEqual([ + { method: 'mobileWeb.bundle.localeCatalog', params: { locale: 'de', knownSha256: OLD_SHA } } + ]) + + client.sent[0].reply({ + id: 'r1', + ok: true, + result: { locale: 'de', sha256: NEW_SHA, catalog: { greeting: 'Servus' } } + }) + await settle() + + expect(i18n.getMobileUiLocale()).toBe('de') + expect(i18n.translate('greeting', 'Hello')).toBe('Servus') + expect(decodeDeviceStoreValue(store.rows.get('i18n-catalog:de') ?? '')).toEqual({ + v: 1, + sha256: NEW_SHA, + catalog: { greeting: 'Servus' } + }) + }) + + it('shows English offline with nothing stored, then the language once the desktop answers', async () => { + vi.spyOn(console, 'warn').mockImplementation(() => {}) + const client = fakeClient('reconnecting') + openPage(client, fakeStore({})) + + await i18n.activateMobileUiLocale('fr') + expect(i18n.getMobileUiLocale()).toBe('en') + expect(i18n.translate('greeting', 'Hello')).toBe('Hello') + expect(client.sent).toHaveLength(0) + + client.moveTo('connected') + await settle() + expect(client.sent.map(({ params }) => params)).toEqual([{ locale: 'fr' }]) + client.sent[0].reply({ + id: 'r1', + ok: true, + result: { locale: 'fr', sha256: NEW_SHA, catalog: { greeting: 'Bonjour' } } + }) + await settle() + + expect(i18n.getMobileUiLocale()).toBe('fr') + expect(i18n.translate('greeting', 'Hello')).toBe('Bonjour') + }) + + it('opens in English when the first request fails on a live link, then switches on the next connection', async () => { + vi.spyOn(console, 'warn').mockImplementation(() => {}) + const client = fakeClient('connected') + openPage(client, fakeStore({})) + + const activation = i18n.activateMobileUiLocale('ja') + await settle() + client.sent[0].fail(new Error('timed out')) + await activation + expect(i18n.getMobileUiLocale()).toBe('en') + + client.moveTo('reconnecting') + client.moveTo('connected') + await settle() + client.sent[1].reply({ + id: 'r2', + ok: true, + result: { locale: 'ja', sha256: NEW_SHA, catalog: { greeting: 'こんにちは' } } + }) + await settle() + + expect(i18n.getMobileUiLocale()).toBe('ja') + expect(i18n.translate('greeting', 'Hello')).toBe('こんにちは') + }) + + it('asks again on the connection a cutover swaps in, without waiting for another reconnect', async () => { + vi.spyOn(console, 'warn').mockImplementation(() => {}) + const client = fakeClient('reconnecting') + openPage(client, fakeStore({})) + + await i18n.activateMobileUiLocale('ko') + client.moveTo('connected') + await settle() + client.cutover() + client.sent[0].fail(new Error('client cut over')) + await settle() + client.sent[1].reply({ + id: 'r2', + ok: true, + result: { locale: 'ko', sha256: NEW_SHA, catalog: { greeting: '안녕하세요' } } + }) + await settle() + + expect(i18n.getMobileUiLocale()).toBe('ko') + expect(i18n.translate('greeting', 'Hello')).toBe('안녕하세요') + }) + + it('imports the chunk an older shell left on disk, with no wait and no request', async () => { + chunksOnDisk.set('es', { greeting: 'Hola' }) + const client = fakeClient('reconnecting') + openPage(client, fakeStore({})) + + await i18n.activateMobileUiLocale('es') + + expect(i18n.translate('greeting', 'Hello')).toBe('Hola') + expect(client.sent).toHaveLength(0) + }) +}) diff --git a/mobile/src/i18n/page-locale-catalog-source.ts b/mobile/src/i18n/page-locale-catalog-source.ts new file mode 100644 index 00000000000..76333fdc22b --- /dev/null +++ b/mobile/src/i18n/page-locale-catalog-source.ts @@ -0,0 +1,265 @@ +import * as z from 'zod' +import type { SupportedUiLocale } from '../../../src/shared/ui-locale' +import { SHA256_PATTERN } from '../../../src/shared/mobile-web-bundle/manifest-contract' +import { + MOBILE_WEB_BUNDLE_LOCALE_CATALOG_METHOD, + MobileWebBundleLocaleCatalogResultSchema +} from '../../../src/shared/mobile-web-bundle/locale-catalog-contract' +import { withTimeoutResult } from '../../../src/shared/promise-timeout-fallback' +import { + decodeDeviceStoreValue, + encodeDeviceStoreValue +} from '../device-store/device-store-value-codec' +import type { BridgeRpcClient } from '../mobile-web-shell/bridge/bridge-rpc-client' +import type { PageDeviceStore } from '../mobile-web-shell/bridge/page-device-store' +import { isMobileMethodUnavailableError } from '../transport/rpc/mobile-method-unavailable' +import { captureRpcOperationSettlement, defineRpcOperation } from '../transport/rpc/rpc-operation' +import { rpcResultVariant } from '../transport/rpc/rpc-operation-result-reader' +import { importBundledLocaleCatalog } from './bundled-locale-catalogs' +import { + announceLocaleCatalog as announce, + publishPageLocaleCatalogLoader, + type LocaleCatalog +} from './locale-catalog-imports.web' + +// The desktop serves the active catalog and the phone keeps a copy per host; only the page entry imports this. +type CatalogLocale = Exclude +type HeldCatalog = { readonly sha256: string; readonly catalog: LocaleCatalog } +type CatalogClient = Pick< + BridgeRpcClient, + 'getState' | 'getGeneration' | 'onStateChange' | 'sendRequest' +> +type CatalogSource = { readonly client: CatalogClient; readonly store: PageDeviceStore } + +const storedCatalogSchema = z.object({ + v: z.literal(1), + sha256: z.string().regex(SHA256_PATTERN), + catalog: z.record(z.string(), z.unknown()) +}) + +const localeCatalogRead = defineRpcOperation({ + name: 'mobileWeb.bundle-locale-catalog', + method: MOBILE_WEB_BUNDLE_LOCALE_CATALOG_METHOD, + acceptance: 'require-result-or-throw', + barrier: 'on-settle', + // Loose like every phone reader, so a host may add fields. + read: rpcResultVariant( + 'mobile-web-bundle-locale-catalog', + MobileWebBundleLocaleCatalogResultSchema.loose() + ) +}) + +const syncing = new Set() +// The stored read plus a relay round trip with the largest catalog fit well inside; past it the page opens in English. +const FIRST_PAINT_CATALOG_WAIT_MS = 3_000 + +const storeKey = (locale: CatalogLocale): string => `i18n-catalog:${locale}` + +async function readStoredCatalog( + store: PageDeviceStore, + locale: CatalogLocale +): Promise { + if (!store.available()) { + return null + } + const read = await store.read('cache', [storeKey(locale)]).catch(() => null) + const raw = read?.status === 'ok' ? read.values[0] : null + if (!raw) { + return null + } + const parsed = storedCatalogSchema.safeParse(decodeDeviceStoreValue(raw)) + return parsed.success ? { sha256: parsed.data.sha256, catalog: parsed.data.catalog } : null +} + +function writeStoredCatalog( + store: PageDeviceStore, + locale: CatalogLocale, + next: HeldCatalog +): void { + if (store.available()) { + const value = encodeDeviceStoreValue({ v: 1, ...next }) + void store.write('cache', [{ key: storeKey(locale), value }]).catch(() => undefined) + } +} + +// A send the host never answered, as opposed to a refusal or an unreadable reply. +class CatalogSendFailed extends Error { + constructor( + message: string, + readonly generation: number | null = null + ) { + super(message) + } +} + +const generationOf = (client: CatalogClient): number | null => client.getGeneration?.() ?? null + +// After a failed send, wait for a reconnect or a cutover to another connection, which is often connected already. +// False once pairing is revoked: that connection never comes back. +function whenConnected(client: CatalogClient, failedGeneration: number | null): Promise { + let reconnected = failedGeneration === null || client.getState() !== 'connected' + const ready = (): boolean => + client.getState() === 'connected' && (reconnected || generationOf(client) !== failedGeneration) + if (ready() || client.getState() === 'auth-failed') { + return Promise.resolve(ready()) + } + return new Promise((resolve) => { + const stop = client.onStateChange((state) => { + reconnected ||= state !== 'connected' + if (ready() || state === 'auth-failed') { + stop() + resolve(ready()) + } + }) + }) +} + +// Rejects when the connection drops first, so a first paint never waits on a reply that can't come. +function beforeConnectionLoss(client: CatalogClient, work: Promise): Promise { + return new Promise((resolve, reject) => { + const stop = client.onStateChange((state) => { + if (state !== 'connected') { + stop() + reject(new CatalogSendFailed('[i18n] connection lost before the catalog arrived')) + } + }) + work.then( + (value) => { + stop() + resolve(value) + }, + (error: unknown) => { + stop() + reject(error) + } + ) + }) +} + +// One request. On an answer the copy becomes the page's and the store's. +async function askHost( + { client, store }: CatalogSource, + locale: CatalogLocale, + known: HeldCatalog | undefined +): Promise { + const generation = generationOf(client) + const settled = await captureRpcOperationSettlement(client, localeCatalogRead, { + locale, + ...(known ? { knownSha256: known.sha256 } : {}) + }) + if (settled.status === 'rejected') { + throw new CatalogSendFailed(`[i18n] the ${locale} catalog request got no answer`, generation) + } + const { outcome } = settled + if (outcome.kind === 'decoded') { + const { sha256, catalog } = outcome.value + // A null catalog only confirms the copy the phone named. + const next = catalog !== null ? { sha256, catalog } : known?.sha256 === sha256 ? known : null + if (next) { + if (next !== known) { + // After the first paint: encoding the copy is main-thread work nothing waits on. + setTimeout(() => { + writeStoredCatalog(store, locale, next) + }, 0) + } + return next + } + } + const refusal = outcome.kind === 'outer-refused' ? outcome.error : undefined + throw new Error( + isMobileMethodUnavailableError(refusal?.code, refusal?.message) + ? '[i18n] this desktop serves no language catalogs' + : `[i18n] the desktop answered no ${locale} catalog` + ) +} + +// Asks until the host answers, resending once per new connection; a refusal ends it. +async function syncFromHost( + current: CatalogSource, + locale: CatalogLocale, + known: HeldCatalog | undefined, + failedGeneration: number | null +): Promise { + for (;;) { + if (!(await whenConnected(current.client, failedGeneration))) { + throw new Error('[i18n] this phone is no longer paired with the desktop') + } + try { + return await askHost(current, locale, known) + } catch (error) { + if (!(error instanceof CatalogSendFailed)) { + throw error + } + failedGeneration = error.generation + } + } +} + +// One sync per locale, announcing a copy other than the one the page already shows. +function syncOnce( + current: CatalogSource, + locale: CatalogLocale, + known: HeldCatalog | undefined, + failedGeneration: number | null = null +): void { + if (syncing.has(locale)) { + return + } + syncing.add(locale) + syncFromHost(current, locale, known, failedGeneration).then( + (next) => { + syncing.delete(locale) + if (next !== known) { + announce(locale, next.catalog) + } + }, + () => { + syncing.delete(locale) + } + ) +} + +// What a first paint may wait for: the stored copy, else one request while connected. +async function firstCatalog(current: CatalogSource, locale: CatalogLocale): Promise { + // Only a locale with no catalog installed is asked for, so nothing is held in memory here. + const known = await readStoredCatalog(current.store, locale) + if (known) { + // Show the stored copy now; a newer one replaces it when the host answers. + syncOnce(current, locale, known) + return known + } + if (current.client.getState() !== 'connected') { + throw new CatalogSendFailed('[i18n] no connection for the catalog yet') + } + return beforeConnectionLoss(current.client, askHost(current, locale, undefined)) +} + +async function loadCatalog(current: CatalogSource, locale: CatalogLocale): Promise { + // A generation an older shell downloaded still holds the chunk: no wait, and this page's own strings. + const bundled = await importBundledLocaleCatalog(locale).catch(() => null) + if (bundled !== null) { + return bundled + } + const first = firstCatalog(current, locale) + const settled = await withTimeoutResult(first, FIRST_PAINT_CATALOG_WAIT_MS) + if (settled.ok) { + return settled.value.catalog + } + // Activation shows English meanwhile; whatever comes later switches the page in place. + first.then( + (late) => { + announce(locale, late.catalog) + }, + (failure: unknown) => { + if (failure instanceof CatalogSendFailed) { + syncOnce(current, locale, undefined, failure.generation) + } + } + ) + throw new Error(`[i18n] no ${locale} catalog for the first paint`) +} + +// Before the first activation, so its catalog comes from the desktop and the store. +export function startPageLocaleCatalogs(current: CatalogSource): void { + publishPageLocaleCatalogLoader((locale) => loadCatalog(current, locale)) +} diff --git a/mobile/src/mobile-web-shell/bridge-host-init.test.ts b/mobile/src/mobile-web-shell/bridge-host-init.test.ts index 0a64fd9585f..a2add44e7ad 100644 --- a/mobile/src/mobile-web-shell/bridge-host-init.test.ts +++ b/mobile/src/mobile-web-shell/bridge-host-init.test.ts @@ -48,6 +48,7 @@ describe('init and state', () => { expect(init.grants.native).toEqual([ BRIDGE_FAULT_GRANT, BRIDGE_RPC_ENVELOPE_GRANT, + 'hostCatalogs', 'navigate', 'storage', 'haptics', diff --git a/mobile/src/mobile-web-shell/bridge-host-native-verbs.test.ts b/mobile/src/mobile-web-shell/bridge-host-native-verbs.test.ts index 87e837fc66b..3a9655cfb7b 100644 --- a/mobile/src/mobile-web-shell/bridge-host-native-verbs.test.ts +++ b/mobile/src/mobile-web-shell/bridge-host-native-verbs.test.ts @@ -205,7 +205,7 @@ describe('grants scoped to the route the page was opened for', () => { const bridge = harness({ routeGrants: navigationOnly, ready: true }) expect(bridge.last()).toMatchObject({ type: 'init', - grants: { native: ['fault', 'rpcEnvelope', 'navigate', 'storage'] } + grants: { native: ['fault', 'rpcEnvelope', 'hostCatalogs', 'navigate', 'storage'] } }) for (const [method, params] of [ ['native.clipboard.read', { mime: 'text' }], diff --git a/mobile/src/mobile-web-shell/bridge-host.ts b/mobile/src/mobile-web-shell/bridge-host.ts index 914b25c9b70..166f3e791d3 100644 --- a/mobile/src/mobile-web-shell/bridge-host.ts +++ b/mobile/src/mobile-web-shell/bridge-host.ts @@ -7,9 +7,8 @@ import { BridgeHostRequests } from './bridge-host-requests' import { BridgeHostSubscriptions } from './bridge-host-subscriptions' import { createBridgeHostStreamFrames } from './bridge-host-stream-frames' import { - BRIDGE_FAULT_GRANT, BRIDGE_PROTOCOL_VERSION, - BRIDGE_RPC_ENVELOPE_GRANT, + BRIDGE_SHELL_GRANTS, readBridgeClientMessage, type BridgeClientMessage } from './bridge/bridge-envelope' @@ -30,11 +29,7 @@ export type { BridgeHost, BridgeHostDiagnostic, BridgeHostOptions } from './brid // Bind the host structurally to one RPC client; the protocol lets pages name no other host. Native origin checks reject expired sessions, and init caps are enforced here. export function createBridgeHost(options: BridgeHostOptions): BridgeHost { const { client, buildId, sessionId, pageRoutes, host } = options - const granted: readonly string[] = [ - BRIDGE_FAULT_GRANT, - BRIDGE_RPC_ENVELOPE_GRANT, - ...options.routeGrants - ] + const granted: readonly string[] = [...BRIDGE_SHELL_GRANTS, ...options.routeGrants] // Validate manifest pairs like the route: a pair refused by the page would invalidate the entire init. const parsedRouteGrants = options.pageRouteGrants === undefined diff --git a/mobile/src/mobile-web-shell/bridge/bridge-envelope.ts b/mobile/src/mobile-web-shell/bridge/bridge-envelope.ts index 8f8e8946fa9..5af16b2a9b3 100644 --- a/mobile/src/mobile-web-shell/bridge/bridge-envelope.ts +++ b/mobile/src/mobile-web-shell/bridge/bridge-envelope.ts @@ -32,10 +32,12 @@ export { BRIDGE_EXTERNAL_LINK_GRANT, BRIDGE_FAULT_GRANT, BRIDGE_FOREGROUND_NUDGE_REASONS, + BRIDGE_HOST_CATALOGS_GRANT, BRIDGE_ID_PATTERN, BRIDGE_NAVIGATE_BACK_NOTIFY, BRIDGE_PROTOCOL_VERSION, - BRIDGE_RPC_ENVELOPE_GRANT + BRIDGE_RPC_ENVELOPE_GRANT, + BRIDGE_SHELL_GRANTS } from './bridge-frame-fields' import { isPageStorageKey, diff --git a/mobile/src/mobile-web-shell/bridge/bridge-frame-fields.ts b/mobile/src/mobile-web-shell/bridge/bridge-frame-fields.ts index 9fea8193746..0a2ce887cd6 100644 --- a/mobile/src/mobile-web-shell/bridge/bridge-frame-fields.ts +++ b/mobile/src/mobile-web-shell/bridge/bridge-frame-fields.ts @@ -25,3 +25,13 @@ export const BRIDGE_EXTERNAL_LINK_GRANT = 'externalLink' // Negotiate rpcEnvelope before relying on extra wire fields; older shells drop unknown fields and could execute without caller-required metadata. export const BRIDGE_RPC_ENVELOPE_GRANT = 'rpcEnvelope' + +// The shell skipped the build's language-catalog chunks, so the page reads its catalog from the desktop. +export const BRIDGE_HOST_CATALOGS_GRANT = 'hostCatalogs' + +// Granted to every page this shell opens, whatever its route declares. +export const BRIDGE_SHELL_GRANTS: readonly string[] = [ + BRIDGE_FAULT_GRANT, + BRIDGE_RPC_ENVELOPE_GRANT, + BRIDGE_HOST_CATALOGS_GRANT +] diff --git a/mobile/src/mobile-web-shell/bridge/bridge-init-frame.ts b/mobile/src/mobile-web-shell/bridge/bridge-init-frame.ts index 2c5208dfe6f..ac4c256e67f 100644 --- a/mobile/src/mobile-web-shell/bridge/bridge-init-frame.ts +++ b/mobile/src/mobile-web-shell/bridge/bridge-init-frame.ts @@ -6,9 +6,8 @@ import { import { BRIDGE_MAX_PENDING_REQUESTS, BRIDGE_MAX_SUBSCRIPTIONS } from './bridge-caps' import { MOBILE_WEB_SHELL_GRANTS } from '../page-route-policy' import { - BRIDGE_FAULT_GRANT, BRIDGE_PROTOCOL_VERSION, - BRIDGE_RPC_ENVELOPE_GRANT, + BRIDGE_SHELL_GRANTS, type BridgeColorScheme, type BridgeConnectionSnapshot, type BridgeHostMessage, @@ -27,8 +26,7 @@ import type { HostStatusReply } from '../../transport/hosts/host-status-reply-sc // Grant the intersection of implemented capabilities and route declarations, plus protocol fault. Use the same resolved list for init and enforcement; new names need no version bump. export const BRIDGE_NATIVE_GRANTS: readonly string[] = [ - BRIDGE_FAULT_GRANT, - BRIDGE_RPC_ENVELOPE_GRANT, + ...BRIDGE_SHELL_GRANTS, ...MOBILE_WEB_SHELL_GRANTS ] diff --git a/mobile/src/mobile-web-shell/generation-manifest-read.ts b/mobile/src/mobile-web-shell/generation-manifest-read.ts index 875cf4966d5..71c6ee09e18 100644 --- a/mobile/src/mobile-web-shell/generation-manifest-read.ts +++ b/mobile/src/mobile-web-shell/generation-manifest-read.ts @@ -1,5 +1,6 @@ import { MobileWebBundleManifestReadSchema, + shellDownloadedAssets, type MobileWebBundleManifestRead } from '../transport/web-bundle/mobile-web-bundle-reply-schemas' import { MANIFEST_FILE_NAME } from './generation-asset-path' @@ -33,12 +34,13 @@ export async function readWaitingStage( } // Deletes are not atomic, so a kill mid-delete can leave the manifest without its assets; only every byte counts as whole. const sizes = new Map() - for (const folder of new Set(manifest.assets.map((asset) => parentOf(asset.path)))) { + const assets = shellDownloadedAssets(manifest) + for (const folder of new Set(assets.map((asset) => parentOf(asset.path)))) { for (const file of await fs.listFiles(folder === '' ? directory : joinUri(directory, folder))) { sizes.set(folder === '' ? file.name : `${folder}/${file.name}`, file.size) } } - const whole = manifest.assets.every((asset) => sizes.get(asset.path) === asset.byteLength) + const whole = assets.every((asset) => sizes.get(asset.path) === asset.byteLength) return whole ? { hostKey, buildId, directory, manifest } : null } diff --git a/mobile/src/mobile-web-shell/generation-staging-assets.ts b/mobile/src/mobile-web-shell/generation-staging-assets.ts index ded1033d931..cd61866c2b4 100644 --- a/mobile/src/mobile-web-shell/generation-staging-assets.ts +++ b/mobile/src/mobile-web-shell/generation-staging-assets.ts @@ -1,10 +1,11 @@ import type { MobileWebBundleFetchResult } from '../transport/web-bundle/mobile-web-bundle-fetch' +import { shellDownloadedAssets } from '../transport/web-bundle/mobile-web-bundle-reply-schemas' import { requireStorablePath } from './generation-asset-path' import { joinUri } from './generation-cache-uri' export function stagingAssetsOf(directory: string, result: MobileWebBundleFetchResult) { const reused = new Set(result.reused) - return result.manifest.assets.map((asset) => ({ + return shellDownloadedAssets(result.manifest).map((asset) => ({ asset, uri: joinUri(directory, requireStorablePath(asset.path)), bytes: reused.has(asset.path) ? null : requireExactBytes(result.assets.get(asset.path), asset) diff --git a/mobile/src/mobile-web-shell/generation-store.test.ts b/mobile/src/mobile-web-shell/generation-store.test.ts index b14db27039d..7b5ebd20edf 100644 --- a/mobile/src/mobile-web-shell/generation-store.test.ts +++ b/mobile/src/mobile-web-shell/generation-store.test.ts @@ -13,7 +13,7 @@ const HOST = deriveHostCacheKey('host-a') function buildResult(options: { buildId?: string - assets?: readonly { path: string; byteLength: number }[] + assets?: readonly { path: string; byteLength: number; kind?: string }[] bytes?: ReadonlyMap }): MobileWebBundleFetchResult { const listed = options.assets ?? [ @@ -24,7 +24,8 @@ function buildResult(options: { path: asset.path, sha256: String(index).repeat(64).slice(0, 64), byteLength: asset.byteLength, - contentType: 'text/html; charset=utf-8' + contentType: 'text/html; charset=utf-8', + ...(asset.kind === undefined ? {} : { kind: asset.kind }) })) const totalBytes = assets.reduce((sum, asset) => sum + asset.byteLength, 0) return { @@ -75,4 +76,25 @@ describe('an update staged behind a live page', () => { expect((await store.readActiveGeneration(HOST))?.buildId).toBe(SECOND_BUILD) expect(await fs.fileExists(`${ROOT}/${HOST}/generations/${BUILD}/index.html`)).toBe(false) }) + + it('stages a build without its language-catalog chunks and still commits it at the next launch', async () => { + const fs = createFakeFileSystem() + const first = createGenerationStore({ fileSystem: fs }) + await activate(first, HOST) + first.holdGeneration(HOST) + const withCatalog = buildResult({ + assets: [ + { path: 'index.html', byteLength: 8 }, + { path: 'assets/de.js', byteLength: 3, kind: 'catalog' } + ], + bytes: new Map([['index.html', new Uint8Array(8)]]) + }) + first.deferCommit(await first.stageGeneration(HOST, withCatalog)) + + const relaunched = createGenerationStore({ fileSystem: fs }) + + const build = withCatalog.manifest.buildId + expect((await relaunched.readActiveGeneration(HOST))?.buildId).toBe(build) + expect(await fs.fileExists(`${ROOT}/${HOST}/generations/${build}/assets/de.js`)).toBe(false) + }) }) diff --git a/mobile/src/mobile-web-shell/mobile-web-shell-session-effects.ts b/mobile/src/mobile-web-shell/mobile-web-shell-session-effects.ts index b1b413b9886..a8d939a15d7 100644 --- a/mobile/src/mobile-web-shell/mobile-web-shell-session-effects.ts +++ b/mobile/src/mobile-web-shell/mobile-web-shell-session-effects.ts @@ -1,9 +1,10 @@ import { fetchMobileWebBundle } from '../transport/web-bundle/mobile-web-bundle-fetch' import { mobileWebBundleStreamBytes } from '../transport/web-bundle/mobile-web-bundle-window-reader' import { mobileWebBundleManifestRead } from '../transport/web-bundle/mobile-web-bundle-operations' -import type { - MobileWebBundleManifestRead, - MobileWebBundleManifestReply +import { + shellDownloadedAssets, + type MobileWebBundleManifestRead, + type MobileWebBundleManifestReply } from '../transport/web-bundle/mobile-web-bundle-reply-schemas' import type { MobileWebBundleCompatManifest } from '../transport/web-bundle/mobile-web-bundle-compat' import { runRpcOperation } from '../transport/rpc/rpc-operation' @@ -88,8 +89,9 @@ export async function readManifest( manifest: { ...compatOf(manifest), buildId: manifest.buildId, + // What this shell downloads: wire bytes, without the catalog chunks it skips. totalBytes: mobileWebBundleStreamBytes(opened), - totalAssets: manifest.assets.length, + totalAssets: shellDownloadedAssets(manifest).length, routes: manifest.routes } }) diff --git a/mobile/src/transport/web-bundle/mobile-web-bundle-fetch.test.ts b/mobile/src/transport/web-bundle/mobile-web-bundle-fetch.test.ts index 643778934ec..276a5df91e9 100644 --- a/mobile/src/transport/web-bundle/mobile-web-bundle-fetch.test.ts +++ b/mobile/src/transport/web-bundle/mobile-web-bundle-fetch.test.ts @@ -35,6 +35,7 @@ type HostOptions = { buildId?: string intercept?: (call: HostCall) => unknown onInFlight?: (inFlight: number) => void + catalogs?: readonly string[] } /** Box first, so params that are not an object read as absent instead of throwing. */ @@ -51,7 +52,8 @@ function bundleHost(files: Record, options: HostOptions = {}) { path, sha256: toHex(sha256(content)), byteLength: content.byteLength, - contentType: 'text/plain' + contentType: 'text/plain', + ...(options.catalogs?.includes(path) ? { kind: 'catalog' } : {}) })) .sort((left, right) => (left.path < right.path ? -1 : 1)) // Derive fixture ids from final asset lists unless the test explicitly selects a mismatch. @@ -156,4 +158,18 @@ describe('fetchMobileWebBundle', () => { await expect(failed).rejects.toThrow(/index\.html hashed [0-9a-f]{64}, not/) expect(await refusalOf(failed)).toBe('asset-checksum-mismatch') }) + + it('leaves language-catalog chunks on the desktop and fetches the rest', async () => { + const host = bundleHost( + { 'index.html': 'abcdef', 'assets/de.js': 'catalog' }, + { catalogs: ['assets/de.js'] } + ) + + const fetched = await fetchMobileWebBundle({ client: host.client }) + + expect([...fetched.assets.keys()]).toEqual(['index.html']) + expect(host.calls.some((call) => paramField(call.params, 'path') === 'assets/de.js')).toBe( + false + ) + }) }) diff --git a/mobile/src/transport/web-bundle/mobile-web-bundle-fetch.ts b/mobile/src/transport/web-bundle/mobile-web-bundle-fetch.ts index e27bef83ddb..60d00a83979 100644 --- a/mobile/src/transport/web-bundle/mobile-web-bundle-fetch.ts +++ b/mobile/src/transport/web-bundle/mobile-web-bundle-fetch.ts @@ -1,10 +1,11 @@ import { CryptoDigestAlgorithm, digest } from 'expo-crypto' import { PrioritySemaphore } from '../../../../src/shared/priority-semaphore' import { mobileWebBundleManifestRead } from './mobile-web-bundle-operations' -import type { - MobileWebBundleAssetRead, - MobileWebBundleManifestRead, - MobileWebBundleManifestReply +import { + shellDownloadedAssets, + type MobileWebBundleAssetRead, + type MobileWebBundleManifestRead, + type MobileWebBundleManifestReply } from './mobile-web-bundle-reply-schemas' import type { RpcClient } from '../rpc/rpc-client-contract' import { MobileWebBundleFetchError } from './mobile-web-bundle-fetch-refusal' @@ -53,7 +54,7 @@ export type MobileWebBundleFetchProgress = { export type MobileWebBundleFetchResult = { readonly manifest: MobileWebBundleManifestRead readonly assets: ReadonlyMap - // stageGeneration must copy every reused asset or fail rather than stage an incomplete tree. + // stageGeneration must copy every reused asset or fail rather than stage an incomplete tree (skipped catalogs aside). readonly reused: readonly string[] readonly totalBytes: number readonly elapsedMs: number @@ -93,10 +94,12 @@ export async function fetchMobileWebBundle(args: { const manifest = opened.manifest const reader = mobileWebBundleWindowReader(args.client, opened) const connection = connectionReadsOf(args.client) + // Before reuse: a skipped catalog an older generation lists may not be on disk there either. + const wanted = shellDownloadedAssets(manifest) const candidates = new Set( - args.reusable === undefined ? [] : manifest.assets.filter((entry) => args.reusable?.has(entry)) + args.reusable === undefined ? [] : wanted.filter((entry) => args.reusable?.has(entry)) ) - const fetched = manifest.assets.filter((entry) => !candidates.has(entry)) + const fetched = wanted.filter((entry) => !candidates.has(entry)) const assets = new Map() const reused: string[] = [] let receivedBytes = 0 diff --git a/mobile/src/transport/web-bundle/mobile-web-bundle-reply-schemas.ts b/mobile/src/transport/web-bundle/mobile-web-bundle-reply-schemas.ts index 602d3d5d4ea..cc72d59b214 100644 --- a/mobile/src/transport/web-bundle/mobile-web-bundle-reply-schemas.ts +++ b/mobile/src/transport/web-bundle/mobile-web-bundle-reply-schemas.ts @@ -46,7 +46,9 @@ const assetSchema = z.looseObject({ .nonnegative() .max(MOBILE_WEB_BUNDLE_MAX_ASSET_BYTES) .optional() - .catch(undefined) + .catch(undefined), + // A kind this build cannot read is a plain asset, downloaded like any other. + kind: z.string().optional().catch(undefined) }) // Read unknown schema versions as numbers so compatibility can name the required update. @@ -132,3 +134,11 @@ export const MobileWebBundleBrotliRangeReplySchema = z.looseObject({ export type MobileWebBundleManifestReply = z.output export type MobileWebBundleManifestRead = MobileWebBundleManifestReply['manifest'] export type MobileWebBundleAssetRead = MobileWebBundleManifestRead['assets'][number] + +// Language-catalog chunks stay on the desktop: this shell grants the page hostCatalogs, and the +// page reads its one catalog over RPC. Everything else is the generation, on disk. +export function shellDownloadedAssets(manifest: { + readonly assets: readonly Asset[] +}): Asset[] { + return manifest.assets.filter((asset) => asset.kind !== 'catalog') +} diff --git a/mobile/src/transport/web-bundle/mobile-web-bundle-window-reader.ts b/mobile/src/transport/web-bundle/mobile-web-bundle-window-reader.ts index 9ed37e44bdd..3182c2744a9 100644 --- a/mobile/src/transport/web-bundle/mobile-web-bundle-window-reader.ts +++ b/mobile/src/transport/web-bundle/mobile-web-bundle-window-reader.ts @@ -7,9 +7,10 @@ import { mobileWebBundleRangeRead } from './mobile-web-bundle-operations' import { decodeMobileWebBundleRange } from './mobile-web-bundle-range-decode' -import type { - MobileWebBundleAssetRead, - MobileWebBundleManifestReply +import { + shellDownloadedAssets, + type MobileWebBundleAssetRead, + type MobileWebBundleManifestReply } from './mobile-web-bundle-reply-schemas' import { MobileWebBundleFetchError } from './mobile-web-bundle-fetch-refusal' import type { RpcClient } from '../rpc/rpc-client-contract' @@ -121,7 +122,7 @@ export function mobileWebBundleStreamBytes( opened: Pick ): number { const brotliLengths = brotliStreamLengths(opened) - return opened.manifest.assets.reduce( + return shellDownloadedAssets(opened.manifest).reduce( (sum, asset) => sum + (brotliLengths.get(asset.path) ?? asset.byteLength), 0 ) diff --git a/mobile/web-entry/index.tsx b/mobile/web-entry/index.tsx index a2da5aad055..df11b8b7952 100644 --- a/mobile/web-entry/index.tsx +++ b/mobile/web-entry/index.tsx @@ -17,6 +17,7 @@ import { type PageMountTarget } from '../src/mobile-web-shell/bridge/page-bootstrap' import { storageReadResultSchema } from '../src/mobile-web-shell/bridge/bridge-native-verbs' +import { BRIDGE_HOST_CATALOGS_GRANT } from '../src/mobile-web-shell/bridge/bridge-frame-fields' import { publishPageStorage, refreshPageTerminalSettings @@ -33,6 +34,7 @@ import { PageFaultBoundary } from '../src/mobile-web-shell/bridge/page-fault-bou import type { BridgeUiLocale } from '../src/mobile-web-shell/bridge/bridge-envelope' import { BRIDGE_OPEN_ROUTE_PARAM } from '../src/mobile-web-shell/bridge/bridge-route-update' import { activateMobileUiLocale, subscribeMobileUiLanguage } from '../src/i18n/mobile-i18n' +import { startPageLocaleCatalogs } from '../src/i18n/page-locale-catalog-source' import { getUiIntlLocale } from '../src/i18n/ui-intl-locale' import { readDeviceUiLocaleTags, resolveUiLocaleFromTags } from '../src/i18n/system-ui-locale' import { publishPageHostProfile } from '../src/mobile-web-shell/bridge/page-host-profile' @@ -158,6 +160,12 @@ bootstrapShellPage({ // Apply before the first render so no component paints the default dark palette first. applyMobileColorScheme(session.colorScheme) client.onColorSchemeUpdate(applyMobileColorScheme) + const deviceStore = createPageDeviceStore(client) + publishPageDeviceStore(deviceStore) + // A shell that skipped the catalog chunks has the page read its catalog from the desktop; before the first load. + if (session.grants.native.includes(BRIDGE_HOST_CATALOGS_GRANT)) { + startPageLocaleCatalogs({ client, store: deviceStore }) + } // Subscribe before the first catalog load so a switch during startup is not lost; the latest request wins. let uiLocaleActivation = activatePageUiLocale(session.uiLocale) client.onUiLocaleUpdate((locale) => { @@ -187,8 +195,6 @@ bootstrapShellPage({ ).value : null ) - const deviceStore = createPageDeviceStore(client) - publishPageDeviceStore(deviceStore) // An open-target boot paints the shell's target first, so that is the screen to preload and restore. const route = bootRoute(session.route?.params?.[BRIDGE_OPEN_ROUTE_PARAM]) const queryClient = createOrcaQueryClient() diff --git a/src/main/runtime/rpc/methods/mobile-delivery/mobile-web-bundle.test-fixture.ts b/src/main/runtime/rpc/methods/mobile-delivery/mobile-web-bundle.test-fixture.ts index ff015a62f71..ea816a3e2a6 100644 --- a/src/main/runtime/rpc/methods/mobile-delivery/mobile-web-bundle.test-fixture.ts +++ b/src/main/runtime/rpc/methods/mobile-delivery/mobile-web-bundle.test-fixture.ts @@ -10,7 +10,8 @@ import { MOBILE_WEB_BUNDLE_CHUNK_BYTES } from '../../../../../shared/mobile-web- import { computeMobileWebBundleId, mobileWebBundleBrotliPath, - type MobileWebBundleAsset + type MobileWebBundleAsset, + type MobileWebBundleCatalog } from '../../../../../shared/mobile-web-bundle/manifest-contract' export const sha256Hex = (bytes: Buffer): string => createHash('sha256').update(bytes).digest('hex') @@ -52,14 +53,24 @@ export type SyntheticMobileWebBundle = { root: string buildId: string assets: MobileWebBundleAsset[] + catalogs: MobileWebBundleCatalog[] } export function writeSyntheticMobileWebBundle( root: string, seed: number, - extraAssets: readonly SyntheticAsset[] = [] + extraAssets: readonly SyntheticAsset[] = [], + localeCatalogs: Readonly>> = {} ): SyntheticMobileWebBundle { mkdirSync(join(root, 'assets'), { recursive: true }) + const catalogs = Object.entries(localeCatalogs).map(([locale, catalog]) => { + const bytes = Buffer.from(JSON.stringify(catalog), 'utf8') + const sha256 = sha256Hex(bytes) + const path = `catalogs/${sha256}.json` + mkdirSync(join(root, 'catalogs'), { recursive: true }) + writeFileSync(join(root, path), bytes) + return { locale, path, sha256, byteLength: bytes.byteLength } + }) const written = [...syntheticAssets(seed), ...extraAssets] const copies = new Map() for (const asset of written) { @@ -91,11 +102,12 @@ export function writeSyntheticMobileWebBundle( entrypoint: 'index.html', totalBytes: assets.reduce((total, asset) => total + asset.byteLength, 0), assets, - routes: [] + routes: [], + ...(catalogs.length === 0 ? {} : { catalogs }) }), 'utf8' ) - return { root, buildId, assets } + return { root, buildId, assets, catalogs } } /** Only the envelope reads runtimeId; bundle methods read directly from this install. */ diff --git a/src/main/runtime/rpc/methods/mobile-delivery/mobile-web-bundle.test.ts b/src/main/runtime/rpc/methods/mobile-delivery/mobile-web-bundle.test.ts index 0a426114237..4ad687cb8f2 100644 --- a/src/main/runtime/rpc/methods/mobile-delivery/mobile-web-bundle.test.ts +++ b/src/main/runtime/rpc/methods/mobile-delivery/mobile-web-bundle.test.ts @@ -214,6 +214,47 @@ describe('an install that carries a mobile web bundle', () => { }) }) +describe('the language catalogs a build serves on request', () => { + let bundle: SyntheticMobileWebBundle + + beforeEach(() => { + bundle = writeSyntheticMobileWebBundle(join(scratch, 'out', 'mobile-web'), 1, [], { + de: { greeting: 'Hallo' } + }) + }) + + it('serves the listed catalog, then nothing to a phone that already holds it', async () => { + const [german] = bundle.catalogs + + const first = await call('mobileWeb.bundle.localeCatalog', { locale: 'de' }) + const again = await call('mobileWeb.bundle.localeCatalog', { + locale: 'de', + knownSha256: german.sha256 + }) + + expect(first.ok && first.result).toEqual({ + locale: 'de', + sha256: german.sha256, + catalog: { greeting: 'Hallo' } + }) + expect(again.ok && again.result).toEqual({ + locale: 'de', + sha256: german.sha256, + catalog: null + }) + }) + + it('refuses a locale the build has no catalog for, and a catalog file that changed', async () => { + writeFileSync(join(bundle.root, bundle.catalogs[0].path), '{"greeting":"Servus"}') + + const french = await call('mobileWeb.bundle.localeCatalog', { locale: 'fr' }) + const changed = await call('mobileWeb.bundle.localeCatalog', { locale: 'de' }) + + expect(errorMessage(french)).toBe('mobile_web_bundle_asset_unknown') + expect(errorMessage(changed)).toBe('mobile_web_bundle_asset_changed') + }) +}) + describe('where the resolver probes', () => { it('finds the bundle beside an out/main app path', async () => { const bundle = writeSyntheticMobileWebBundle(join(scratch, 'out', 'mobile-web'), 3) diff --git a/src/main/runtime/rpc/methods/mobile-delivery/mobile-web-bundle.ts b/src/main/runtime/rpc/methods/mobile-delivery/mobile-web-bundle.ts index 1d700f41cf2..c7fe1de157b 100644 --- a/src/main/runtime/rpc/methods/mobile-delivery/mobile-web-bundle.ts +++ b/src/main/runtime/rpc/methods/mobile-delivery/mobile-web-bundle.ts @@ -1,6 +1,9 @@ -/** Serve only this install's bundle over authenticated RPC: manifest, then chunks or advertised ranges. +/** Serve only this install's bundle over authenticated RPC: manifest, then chunks or advertised ranges, and the page's language catalog. * Never proxy to SSH/relay execution hosts: the phone paired with this desktop. * Verify/read failures map to asset-changed without exposing host paths. */ +import { createHash } from 'node:crypto' +import { readFile } from 'node:fs/promises' +import { join } from 'node:path' import { MOBILE_WEB_BUNDLE_BROTLI_RANGE_METHOD, MOBILE_WEB_BUNDLE_CHUNK_BYTES, @@ -20,6 +23,12 @@ import { mobileWebBundleBrotliPath, type MobileWebBundleAsset } from '../../../../../shared/mobile-web-bundle/manifest-contract' +import { + MOBILE_WEB_BUNDLE_LOCALE_CATALOG_METHOD, + MobileWebBundleLocaleCatalogParamsSchema, + type MobileWebBundleLocaleCatalogParams, + type MobileWebBundleLocaleCatalogResult +} from '../../../../../shared/mobile-web-bundle/locale-catalog-contract' import { loadBundledMobileWebBundle, type BundledMobileWebBundle @@ -55,6 +64,42 @@ function abortIfDisconnected(ctx: RpcContext): void { } } +/** Answer from the build's own catalog file, so the page reads the strings it was built with. */ +async function readLocaleCatalog( + params: MobileWebBundleLocaleCatalogParams, + ctx: RpcContext +): Promise { + const bundle = requireBundle() + const entry = bundle.manifest.catalogs?.find((catalog) => catalog.locale === params.locale) + if (!entry) { + throw bundleError('mobile_web_bundle_asset_unknown') + } + if (params.knownSha256 === entry.sha256) { + return { locale: entry.locale, sha256: entry.sha256, catalog: null } + } + // Its own budget, so a page's one catalog read never waits behind its shell's bundle download. + const release = acquireMobileWebBundleReadSlot(`catalog:${mobileWebBundleReadBucket(ctx)}`) + if (!release) { + throw bundleError('mobile_web_bundle_read_limited') + } + try { + abortIfDisconnected(ctx) + const bytes = await readFile(join(bundle.root, entry.path)) + if (createHash('sha256').update(bytes).digest('hex') !== entry.sha256) { + throw bundleError('mobile_web_bundle_asset_changed') + } + const catalog: unknown = JSON.parse(bytes.toString('utf8')) + if (typeof catalog !== 'object' || catalog === null || Array.isArray(catalog)) { + throw bundleError('mobile_web_bundle_asset_changed') + } + return { locale: entry.locale, sha256: entry.sha256, catalog: { ...catalog } } + } catch (error) { + throw asContractError(error, entry.path) + } finally { + release() + } +} + /** Map unreadable, missing or truncated assets to asset-changed; host paths stay private. */ function asContractError(error: unknown, path: string): unknown { if (error instanceof InvalidArgumentError || isClientDisconnectedError(error)) { @@ -201,5 +246,11 @@ export const MOBILE_WEB_BUNDLE_METHODS = [ handler: (params, ctx): Promise => // The raw asset's hash still gates every window of its copy. readVerifiedWindow(ctx, params, MOBILE_WEB_BUNDLE_CHUNK_BYTES, rawWindowReply, brotliCopyOf) + }), + defineMethod({ + name: MOBILE_WEB_BUNDLE_LOCALE_CATALOG_METHOD, + permission: 'workspace', + params: MobileWebBundleLocaleCatalogParamsSchema, + handler: readLocaleCatalog }) ] diff --git a/src/main/runtime/rpc/server/runtime-rpc-mobile-paired-desktop-methods.ts b/src/main/runtime/rpc/server/runtime-rpc-mobile-paired-desktop-methods.ts index 333dd8868ed..945761935cd 100644 --- a/src/main/runtime/rpc/server/runtime-rpc-mobile-paired-desktop-methods.ts +++ b/src/main/runtime/rpc/server/runtime-rpc-mobile-paired-desktop-methods.ts @@ -5,6 +5,7 @@ export const PAIRED_DESKTOP_METHODS = [ // Device and pairing concerns of the phone's own pairing. 'mobileWeb.bundle.brotliRange', 'mobileWeb.bundle.chunk', + 'mobileWeb.bundle.localeCatalog', 'mobileWeb.bundle.manifest', 'mobileWeb.bundle.range', 'notifications.getMissedSince', diff --git a/src/shared/mobile-web-bundle/locale-catalog-contract.ts b/src/shared/mobile-web-bundle/locale-catalog-contract.ts new file mode 100644 index 00000000000..813776ab994 --- /dev/null +++ b/src/shared/mobile-web-bundle/locale-catalog-contract.ts @@ -0,0 +1,29 @@ +import * as z from 'zod' +import { MobileWebBundleCatalogLocaleSchema, SHA256_PATTERN } from './manifest-contract' + +/** The page's UI-language catalog, served from the build's host-only `catalogs` instead of shipping in every update. */ +export const MOBILE_WEB_BUNDLE_LOCALE_CATALOG_METHOD = 'mobileWeb.bundle.localeCatalog' + +export const MobileWebBundleLocaleCatalogParamsSchema = z + .object({ + locale: MobileWebBundleCatalogLocaleSchema, + /** The copy the phone already holds; a match answers with no catalog. */ + knownSha256: z.string().regex(SHA256_PATTERN).optional() + }) + .strict() + +export const MobileWebBundleLocaleCatalogResultSchema = z + .object({ + locale: MobileWebBundleCatalogLocaleSchema, + sha256: z.string().regex(SHA256_PATTERN), + /** Null when `knownSha256` already names this catalog. */ + catalog: z.record(z.string(), z.unknown()).nullable() + }) + .strict() + +export type MobileWebBundleLocaleCatalogParams = z.infer< + typeof MobileWebBundleLocaleCatalogParamsSchema +> +export type MobileWebBundleLocaleCatalogResult = z.infer< + typeof MobileWebBundleLocaleCatalogResultSchema +> diff --git a/src/shared/mobile-web-bundle/manifest-contract.ts b/src/shared/mobile-web-bundle/manifest-contract.ts index 19462a4906c..654994733d3 100644 --- a/src/shared/mobile-web-bundle/manifest-contract.ts +++ b/src/shared/mobile-web-bundle/manifest-contract.ts @@ -18,6 +18,7 @@ export const MOBILE_WEB_BUNDLE_MAX_ROUTES = 64 export const MOBILE_WEB_BUNDLE_MAX_ROUTE_GRANTS = 16 // What a route's two lists can grant together; released shells cap each list alone, never the pair. export const MOBILE_WEB_BUNDLE_MAX_GRANTED_ROUTE_GRANTS = 2 * MOBILE_WEB_BUNDLE_MAX_ROUTE_GRANTS +export const MOBILE_WEB_BUNDLE_MAX_CATALOGS = 32 export const SHA256_PATTERN = /^[a-f0-9]{64}$/ const ASSET_PATH_PATTERN = /^[A-Za-z0-9._-]+(?:\/[A-Za-z0-9._-]+)*$/ @@ -29,6 +30,7 @@ const MAX_CONTENT_TYPE_LENGTH = 128 const MAX_DESKTOP_VERSION_LENGTH = 64 const MAX_ROUTE_PATHNAME_LENGTH = 255 const MAX_GRANT_NAME_LENGTH = 64 +const UI_LOCALE_PATTERN = /^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$/ /** Rooted, single-slash, no query and no fragment: a phone writes this into its own history. */ const ROUTE_PATHNAME_PATTERN = /^\/(?![/\\])[^?#\s]*$/ /** Plain capabilities or shell verbs native..; require at least two native segments to match the shell table and keep verbs grantable per route. */ @@ -73,7 +75,9 @@ export const MobileWebBundleAssetSchema = z .int() .nonnegative() .max(MOBILE_WEB_BUNDLE_MAX_ASSET_BYTES) - .optional() + .optional(), + /** A language-catalog chunk: shells that read catalogs from the host skip it; outside buildId. */ + kind: z.literal('catalog').optional() }) .strict() @@ -84,8 +88,25 @@ export function mobileWebBundleBrotliPath(assetPath: string): string { return `${assetPath}.br` } +export const MobileWebBundleCatalogLocaleSchema = z.string().max(32).regex(UI_LOCALE_PATTERN) + +/** A UI-language catalog the host serves on request; phones never download it with the build. */ +export const MobileWebBundleCatalogSchema = z + .object({ + locale: MobileWebBundleCatalogLocaleSchema, + path: MobileWebBundleAssetPathSchema, + sha256: z.string().regex(SHA256_PATTERN), + byteLength: z.number().int().nonnegative().max(MOBILE_WEB_BUNDLE_MAX_ASSET_BYTES) + }) + .strict() + +export type MobileWebBundleCatalog = z.infer + +/** The fields buildId hashes; readers with looser optional fields can still recompute it. */ +type HashedAsset = Pick + /** Code-unit order, not `localeCompare`: the sort feeds a content hash, so it must not vary. */ -function compareAssetPaths(left: MobileWebBundleAsset, right: MobileWebBundleAsset): number { +function compareAssetPaths(left: HashedAsset, right: HashedAsset): number { if (left.path === right.path) { return 0 } @@ -93,7 +114,7 @@ function compareAssetPaths(left: MobileWebBundleAsset, right: MobileWebBundleAss } /** Canonical buildId input: path-sorted assets, fixed key order, no whitespace. Sorting here makes the hash independent of caller order. */ -export function serializeMobileWebBundleAssets(assets: readonly MobileWebBundleAsset[]): string { +export function serializeMobileWebBundleAssets(assets: readonly HashedAsset[]): string { return JSON.stringify( [...assets].sort(compareAssetPaths).map((asset) => ({ path: asset.path, @@ -105,7 +126,7 @@ export function serializeMobileWebBundleAssets(assets: readonly MobileWebBundleA } /** Pure-JS SHA-256 lets phones recompute cached manifest ids; Metro provides no Node core shims. */ -export function computeMobileWebBundleId(assets: readonly MobileWebBundleAsset[]): string { +export function computeMobileWebBundleId(assets: readonly HashedAsset[]): string { const digest = sha256(new TextEncoder().encode(serializeMobileWebBundleAssets(assets))) return Array.from(digest, (byte) => byte.toString(16).padStart(2, '0')).join('') } @@ -139,9 +160,19 @@ function validateManifestInvariants( minCompatibleRuntimeProtocolVersion: number runtimeProtocolVersion: number assets: readonly MobileWebBundleAsset[] + catalogs?: readonly MobileWebBundleCatalog[] }, context: z.RefinementCtx ): void { + const catalogLocales = new Set(manifest.catalogs?.map((catalog) => catalog.locale)) + if (catalogLocales.size !== (manifest.catalogs?.length ?? 0)) { + context.addIssue({ + code: 'custom', + path: ['catalogs'], + message: 'catalogs must name each locale once' + }) + return + } // Return on cheap failures before hashing; zod refines even after the asset-count ceiling fails. if (manifest.assets.length > MOBILE_WEB_BUNDLE_MAX_ASSETS) { return @@ -223,7 +254,9 @@ export const MobileWebBundleManifestSchema = z totalBytes: z.number().int().nonnegative().max(MOBILE_WEB_BUNDLE_MAX_TOTAL_BYTES), assets: z.array(MobileWebBundleAssetSchema).min(1).max(MOBILE_WEB_BUNDLE_MAX_ASSETS), /** Outside buildId’s asset hash; routes derive from the same source tree as the script, so identical assets imply identical routes. */ - routes: z.array(MobileWebBundleRouteSchema).max(MOBILE_WEB_BUNDLE_MAX_ROUTES) + routes: z.array(MobileWebBundleRouteSchema).max(MOBILE_WEB_BUNDLE_MAX_ROUTES), + /** The same catalogs as JSON for `mobileWeb.bundle.localeCatalog`; host-only, outside `assets` and buildId. */ + catalogs: z.array(MobileWebBundleCatalogSchema).max(MOBILE_WEB_BUNDLE_MAX_CATALOGS).optional() }) .strict() .superRefine(validateManifestInvariants) diff --git a/src/shared/orcad-artifacts.test.ts b/src/shared/orcad-artifacts.test.ts index 46f258e88ec..9fb4a927482 100644 --- a/src/shared/orcad-artifacts.test.ts +++ b/src/shared/orcad-artifacts.test.ts @@ -24,4 +24,16 @@ describe('standalone runtime artifacts', () => { 'out/mobile-web/index.html.br' ]) }) + + it('ships the host-only language catalogs with the page assets', () => { + const manifest = { + assets: [{ path: 'index.html' }], + catalogs: [{ locale: 'de', path: 'catalogs/de.json' }] + } + + expect(orcadMobileWebAssetFilenames(JSON.stringify(manifest))).toEqual([ + 'out/mobile-web/catalogs/de.json', + 'out/mobile-web/index.html' + ]) + }) }) diff --git a/src/shared/orcad-artifacts.ts b/src/shared/orcad-artifacts.ts index c87ae582132..6baf8fbe3f1 100644 --- a/src/shared/orcad-artifacts.ts +++ b/src/shared/orcad-artifacts.ts @@ -189,7 +189,7 @@ export function isOrcadMobileWebAssetPath(path: string): boolean { ) } -/** Slot paths of every asset `manifestText` lists and their brotli copies, sorted; throws rather than ship a partial page. */ +/** Slot paths of every asset `manifestText` lists, their brotli copies and the host-only catalogs, sorted; throws rather than ship a partial page. */ export function orcadMobileWebAssetFilenames(manifestText: string): string[] { const manifest: unknown = JSON.parse(manifestText) const assets = @@ -197,7 +197,12 @@ export function orcadMobileWebAssetFilenames(manifestText: string): string[] { if (!Array.isArray(assets) || assets.length === 0) { throw new Error(`${ORCAD_MOBILE_WEB_MANIFEST} lists no assets`) } - const filenames = assets.flatMap((asset: unknown) => { + const catalogs = + manifest && typeof manifest === 'object' && 'catalogs' in manifest ? manifest.catalogs : [] + if (!Array.isArray(catalogs)) { + throw new Error(`${ORCAD_MOBILE_WEB_MANIFEST} catalogs is not a list`) + } + const filenames = [...assets, ...catalogs].flatMap((asset: unknown) => { const entry = asset && typeof asset === 'object' ? asset : {} const path = 'path' in entry ? entry.path : undefined if (typeof path !== 'string' || !isOrcadMobileWebAssetPath(path)) { diff --git a/src/shared/rpc-contract/rpc-params-catalog.generated.ts b/src/shared/rpc-contract/rpc-params-catalog.generated.ts index 996590d4caa..d68a27482b2 100644 --- a/src/shared/rpc-contract/rpc-params-catalog.generated.ts +++ b/src/shared/rpc-contract/rpc-params-catalog.generated.ts @@ -32,6 +32,7 @@ import { DesktopBrowserBridgeResultParams } from '../desktop-browser-bridge-protocol' import { MobileWebBundleChunkParamsSchema } from '../mobile-web-bundle/bundle-rpc-contract' +import { MobileWebBundleLocaleCatalogParamsSchema } from '../mobile-web-bundle/locale-catalog-contract' import { OrcadMigrationBlobChunkRequestSchema } from '../orcad-migration/orcad-migration-blob-transfer' import { OrcadMigrationSnapshotChunkRequestSchema } from '../orcad-migration/orcad-migration-scrollback' import { @@ -1322,6 +1323,7 @@ export const RPC_PARAMS_BY_METHOD = { 'mobileRelay.projectSections': null, 'mobileWeb.bundle.brotliRange': MobileWebBundleChunkParamsSchema, 'mobileWeb.bundle.chunk': MobileWebBundleChunkParamsSchema, + 'mobileWeb.bundle.localeCatalog': MobileWebBundleLocaleCatalogParamsSchema, 'mobileWeb.bundle.manifest': null, 'mobileWeb.bundle.range': MobileWebBundleChunkParamsSchema, 'nativeChat.readSession': NativeChatSession,