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
This commit is contained in:
Kelvin Amoaba
2026-11-10 03:52:19 +00:00
committed by GitHub
parent 618c7f5b3f
commit 64a2a6f779
36 changed files with 964 additions and 81 deletions
@@ -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),
@@ -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)
@@ -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(
@@ -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) {
@@ -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 })
}
@@ -0,0 +1,23 @@
import type { SupportedUiLocale } from '../../../src/shared/ui-locale'
export type LocaleCatalog = Readonly<Record<string, unknown>>
// Literal specifiers: Metro evaluates only the chosen module, and the page build splits each into its own chunk.
const CATALOG_IMPORTS: Record<Exclude<SupportedUiLocale, 'en'>, () => Promise<LocaleCatalog>> = {
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<SupportedUiLocale, 'en'>
): Promise<LocaleCatalog> {
return CATALOG_IMPORTS[locale]()
}
+6 -20
View File
@@ -1,23 +1,9 @@
import type { SupportedUiLocale } from '../../../src/shared/ui-locale'
import type { LocaleCatalog } from './bundled-locale-catalogs'
export type LocaleCatalog = Readonly<Record<string, unknown>>
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<Exclude<SupportedUiLocale, 'en'>, () => Promise<LocaleCatalog>> = {
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<SupportedUiLocale, 'en'>
): Promise<LocaleCatalog> {
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<SupportedUiLocale, 'en'>, catalog: LocaleCatalog) => void
) => () => void = () => () => undefined
@@ -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<SupportedUiLocale, 'en'>
type CatalogLoader = (locale: CatalogLocale) => Promise<LocaleCatalog>
type ArrivalListener = (locale: CatalogLocale, catalog: LocaleCatalog) => void
let loader: CatalogLoader | null = null
const arrivalListeners = new Set<ArrivalListener>()
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<LocaleCatalog> {
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)
}
}
+2 -1
View File
@@ -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 } =
+13 -1
View File
@@ -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<void> {
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) {
@@ -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<string, Record<string, unknown>>()
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<RpcResponse>((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<string, string>): PageDeviceStore & { rows: Map<string, string> } {
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<typeof fakeClient>, store: PageDeviceStore): void {
startPageLocaleCatalogs({ client, store })
}
// Microtasks, then one macrotask, which is when the store write runs.
async function settle(): Promise<void> {
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)
})
})
@@ -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<SupportedUiLocale, 'en'>
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<CatalogLocale>()
// 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<HeldCatalog | null> {
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<boolean> {
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<T>(client: CatalogClient, work: Promise<T>): Promise<T> {
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<HeldCatalog> {
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<HeldCatalog> {
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<HeldCatalog> {
// 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<LocaleCatalog> {
// 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))
}
@@ -48,6 +48,7 @@ describe('init and state', () => {
expect(init.grants.native).toEqual([
BRIDGE_FAULT_GRANT,
BRIDGE_RPC_ENVELOPE_GRANT,
'hostCatalogs',
'navigate',
'storage',
'haptics',
@@ -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' }],
+2 -7
View File
@@ -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
@@ -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,
@@ -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
]
@@ -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
]
@@ -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<string, number>()
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
}
@@ -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)
@@ -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<string, Uint8Array>
}): 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)
})
})
@@ -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
}
})
@@ -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<string, string>, 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
)
})
})
@@ -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<string, Uint8Array>
// 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<string, Uint8Array>()
const reused: string[] = []
let receivedBytes = 0
@@ -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<typeof MobileWebBundleManifestReplySchema>
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<Asset extends { readonly kind?: string }>(manifest: {
readonly assets: readonly Asset[]
}): Asset[] {
return manifest.assets.filter((asset) => asset.kind !== 'catalog')
}
@@ -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<MobileWebBundleManifestReply, 'rangeBytes' | 'manifest'>
): 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
)
+8 -2
View File
@@ -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()
@@ -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<Record<string, Record<string, unknown>>> = {}
): 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<string, Buffer>()
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. */
@@ -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)
@@ -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<MobileWebBundleLocaleCatalogResult> {
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<MobileWebBundleBrotliRangeResult> =>
// 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
})
]
@@ -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',
@@ -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
>
@@ -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.<domain>.<action>; 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<typeof MobileWebBundleCatalogSchema>
/** The fields buildId hashes; readers with looser optional fields can still recompute it. */
type HashedAsset = Pick<MobileWebBundleAsset, 'path' | 'sha256' | 'byteLength' | 'contentType'>
/** 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)
+12
View File
@@ -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'
])
})
})
+7 -2
View File
@@ -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)) {
+2
View File
@@ -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,