You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 1c5cee6
Browse filesBrowse the repository at this point in the historyBrowse files
fix(service-settings): judge OS_LOCALIZATION_LOCALE once the boot's locale list is whole, and one locale matcher for Setup and the IdP claim (#30589)
<!-- claude-projects-attribution: {"github_login":"os-bill"} -->
_Requested by **Bill** · [project
thread](https://claude.ai/code/project/chan_016iMXWSZDzqWRWvWzdNo8wg?thread=cmsg_016iMXWSZDzqWRWvWzdNo8wg21NveYnJ8STuX2gJsTgYaA)_
domain:server#4 · os-bill · session_01Utp6CZMkHvuDeVYgTD73qF
## 维护者速读
- **改了什么:** 三件事。①启动窗口:`OS_LOCALIZATION_LOCALE` 指定的语言如果要到 `kernel:ready`
期间才进语言列表(应用自建翻译项就是这时加载的),以前在 `kernel:ready` 早读的一方(auth 的邮件/短信默认语言)会把它判成
IGNORED 并丢掉;现在设置服务在 `kernel:bootstrapped`
之前不下"不在列表里"的结论,先让它生效,列表齐了再判一次,真不合法才报一次错并发变更事件让读方重读。②一个匹配器:Setup
默认语言的接受规则和 IdP 登录语言声明都改用 core 新导出的 `resolveOfferedLocale`,两边接受同一批写法。③更正
`auth-manager.ts` / `auth-plugin.ts` 里"邮件模板四种语言就是该设置的选项"的过期注释。
- **为什么改:** #30286 合入后的契约审查发现:启动窗口会把合法的环境变量误判丢弃(AGENTS.md "Startup
registry reads");Setup 拒收 `fr-FR`(部署提供 `fr`)而 IdP 声明 `fr-FR` 能落到
`fr`,两扇门对同一种语言说法不一;注释描述的是 #30286 之前的世界。
- **风险与回滚:** 放宽(`Clause-②: yes (widening)`):Setup
现在还接受已提供语言的地区/基础写法和大小写变体(`fr` 提供时的 `fr-FR`、`zh-CN` 的
`zh-cn`),以前接受的值全部照旧。IdP 在同时提供 `zh-Hans`/`zh-Hant` 时把 `zh-TW`
落到繁体(以前落到先列出的简体)。一个真正不合法的 `OS_LOCALIZATION_LOCALE` 在 `kernel:ready`
期间会暂时生效,`kernel:bootstrapped` 时报错并通知读方改回;一次性读方(应用内联种子在 `kernel:ready`
读)会用到这个暂时值,无法再通知它改回。回滚即撤本 PR。
- **先看:** `packages/core/src/fallbacks/memory-i18n.ts` 的
`resolveOfferedLocale`;`settings-service.ts` 的
`holdOptionSourceVerdicts` / `sealOptionSources` /
`holdsOptionSourceVerdict` 三段和 `effectiveEnvOverride`
里改动的一行;`settings-service-plugin.ts` 的两处接线。
- **两分钟验证:** `pnpm --filter @objectstack/service-settings exec vitest
run --maxWorkers=2 src/localization-locale-options.test.ts`,预期 18
条全绿,其中"read while the boot is still filling the locale list"三条是启动窗口的钉子。
- **需要你做的:** 无需你本人决定(非 BREAKING,放宽),按席位流程审查合入。
Fixes#30456
Clause-②: yes (widening) — `@objectstack/core` exports
`resolveOfferedLocale(requested, offered)`; `SettingsService` gains
`holdOptionSourceVerdicts()` and `sealOptionSources()`. The save of
`localization.locale` (`PUT /api/settings/localization`,
`SettingsService.setMany`) and an `OS_LOCALIZATION_LOCALE` override now
also accept a region or base of an offered language (`fr-FR` where `fr`
is offered, `fr` where `fr-FR` is) and another case of an offered code
(`zh-cn` for `zh-CN`); nothing accepted before is refused. The IdP
locale claim (`resolveIdpLocale`) lands a script or region spelling on
the offered code the platform locale table says it means (`zh-TW` on
`zh-Hant`, not on a `zh-Hans` listed first).
Metadata-protocol: none
## What changes
### 1. The boot window (`settings-service.ts`,
`settings-service-plugin.ts`)
Measured on `origin/main` 8e5fabe: `localization.locale`'s option
source (#30286) reads the i18n service's `getLocales()`, and that list
grows during `kernel:ready` when the i18n plugin syncs the app's
authored translations (`service-i18n/src/i18n-service-plugin.ts`,
`replaceAuthoredTranslations`). Auth's `applyLocalizationLocale`
(`plugin-auth/src/auth-plugin.ts`) reads the key in its own
`kernel:ready` handler. Whichever runs first decides: an
`OS_LOCALIZATION_LOCALE=vi-VN` whose language arrives as an authored
translation could be judged against a list without it, reported
`IGNORED` at `error`, and auth kept the next layer's value for the rest
of the process. That is the three-part shape AGENTS.md "Startup registry
reads" names (a filling registry, a terminal "absent", recorded in a log
and in the reader's state).
Cure 3 of that section, seal then judge:
- `holdOptionSourceVerdicts()`: `SettingsServicePlugin.init` calls it
before registering the source. While held, an `OS_*` override on a
**sourced** key that the source (or the declared table it stands in for,
when the list is still empty) does not admit is taken in force, not
reported, and remembered. `effectiveEnvOverride` changes by one
condition: `if (rejected && !this.holdsOptionSourceVerdict(namespace,
key))`. The other families (pattern, value domain, bounds, format) do
not depend on the list and are judged at once, as before.
- `sealOptionSources()`: the plugin calls it from `kernel:bootstrapped`,
which the kernel fires after every `kernel:ready` handler. Each
remembered key is judged again: one the list now admits stays in force
and nothing is said; one it still does not admit is reported once
through the existing `reportRejectedEnvOverride` (same message, same
dedupe), and a settings change (`{ namespace, key, scope: 'global',
action: 'set' }`) is emitted so a reader that applied the held value
reads the key again. Auth's reader already subscribes to `localization`
changes, so it re-applies without a code change.
- A `SettingsService` constructed without the plugin is never held and
judges at once, as before.
### 2. One matcher (`core`, `service-settings`, `plugin-auth`)
`resolveOfferedLocale(requested, offered)` in
`packages/core/src/fallbacks/memory-i18n.ts`, exported beside
`resolveLocale`. It reuses `resolveLocale` rather than copying it:
1. `resolveLocale`'s exact and case-insensitive steps;
2. the platform locale table: an offered code that means the same table
language (`platformLocaleTagOf`, through the read aliases), so `zh-TW`
is `zh-Hant`, `zh-CN` is `zh-Hans`, `en-US` is `en`;
3. `resolveLocale` itself for the base-language and variant steps.
Step 2 is what Setup's old `admits` did on its own, and it only changes
`resolveLocale`'s answer where two offered codes share a base language
and the table tells them apart (`zh-Hans`/`zh-Hant`), where
`resolveLocale` takes the first listed.
- Setup (`localization-locale-options.ts`): `admits(v)` is
`resolveOfferedLocale(v, codes) !== undefined`, and a stored second
spelling is served in the place of the code the matcher lands it on. The
docblock's "`fr-FR` is not `fr`" is replaced by the matcher's rules.
- IdP claim (`idp-locale-claim.ts`): `resolveIdpLocale` calls
`resolveOfferedLocale` instead of `resolveLocale`; the stored value is
still the supported code in the column's BCP-47 case.
### 3. The stale comment (`auth-manager.ts`, `auth-plugin.ts`)
`AUTH_EMAIL_TEMPLATE_LOCALES`' docblock said those four "are also the
four options the `localization.locale` setting offers, so the two ends
agree by construction". Since #30286 the setting offers the deployment's
list. The docblock now says how they agree: `normalizeAuthEmailLocale`
maps a value onto a row spelling where one of the four means it and
passes any other through, and `EmailService.sendTemplate` resolves it
against the bundle's tags and falls back to the `en-US` row
(`plugin-email/src/email-service.ts`, #28880 ladder). The same claim in
the `applyLocalizationLocale` comment of `auth-plugin.ts` ("whose four
options are exactly `AUTH_EMAIL_TEMPLATE_LOCALES`") is corrected the
same way. Comments only.
## Tests
- `service-settings/src/localization-locale-options.test.ts` (the
component's shared harness, now 18): a new top-level describe boots a
`LiteKernel` with a `kernel:ready` reader that runs before a stand-in
i18n plugin grows its list in its own `kernel:ready` step:
- `OS_LOCALIZATION_LOCALE=vi-VN`, list `['en']` gaining `vi-VN`: the
reader's first read is `vi-VN` from `env`, every read stays `vi-VN`, and
nothing is logged for the variable;
- `OS_LOCALIZATION_LOCALE=xx-XX`, never offered: held at the first read,
then exactly one `IGNORED` report and a re-read that lands on the
manifest default;
- a bare `SettingsService` judges at once; sealing it is a no-op.
- Matcher through the real `PUT`/`GET` routes: `fr-FR` where `fr` is
offered (served in `fr`'s place), `fr` where `fr-FR` is, `zh-cn` where
`zh-CN` is, `zh-TW` where `zh-Hans` and `zh-Hant` are (served in
`zh-Hant`'s place), `de-DE` still refused. The old pin "`fr-FR` refused
where `fr` is offered" is the narrowing this card removes and is
replaced.
- `plugin-auth/src/idp-locale-claim.test.ts`: `zh-TW` → `zh-Hant`,
`zh-CN` → `zh-Hans` with the scripts listed either way round, `fr-FR` →
`fr`, `de-DE` → unset.
- `core/src/fallbacks/fallbacks.test.ts`: `resolveOfferedLocale` step by
step, including `resolveLocale('zh-TW', ['zh-Hans','zh-Hant'])`
answering `zh-Hans` beside the new answer `zh-Hant`.
Ablation through `scripts/ablation-replace.mjs`, each restored after:
the hold condition removed ⇒ both boot-window pins red; the seal's
`emitChange` removed ⇒ the re-read pin red; the `kernel:bootstrapped`
hook removed ⇒ 2 red (including the existing "not in force once the list
drops it"); Setup's `admits` back to exact codes ⇒ 2 red;
`resolveIdpLocale` on a first-match matcher ⇒ the `zh-Hant` pin red; the
table step removed from `resolveOfferedLocale` ⇒ the core table pin red.
## Acceptance notes
- Seed one-shot readers (`packages/runtime/src/seed-locale.ts`): the app
plugin's inline seed reads the key in its `kernel:ready` handler
(`app-plugin.ts`), so it sees a held value. For an override the boot
does offer, that is now the right value where it used to be the next
layer's; for one the boot never offers, the seed uses it before
`kernel:bootstrapped` reports it, and a one-shot reader cannot be told
to read again. When demo staff or seed files defer the inline seed to
`kernel:bootstrapped`, its hook is registered during `kernel:ready`,
after the settings plugin's seal hook, so it reads after the seal.
- The list growing after the boot (`metadata:reloaded` adding a
translation item) is outside this card: by then the hold is sealed, and
an override is judged at each read against the list of that moment, as
#30286 left it.
- Auth prelude query count pin (`auth-prelude-query-count.pin.test.ts`,
seat 5's #30520): untouched, no query added.
- No service-settings translation key added.
## Verification
All at head `06b4c86f` (the branch with `origin/main` c23eafa merged),
after `pnpm install --frozen-lockfile` (exit 0) and a full build (`turbo
run build --filter='!@objectstack/docs'`, 119/119, under the verify
lock):
- `pnpm --filter @objectstack/core test`: 135 files, 3017 passed;
`typecheck` exit 0.
- `pnpm --filter @objectstack/service-settings test`: 69 files, 1175
passed; `typecheck` exit 0.
- `pnpm --filter @objectstack/plugin-auth test`: 224 files, 3985 passed
and 10 skipped; `typecheck` exit 0.
- `node scripts/pm/dispatch-gates.mjs --commands` derived 67 families
from the change set; each run with its exit recorded before any pipe: 67
of 67 exit 0. `--ran`: 67 derived, 67 run, 0 NOT-MEASURED, exit 0.
- `pnpm lint`: exit 0.
- `pnpm --filter @objectstack/dogfood test` under the lock: exit 0, 420
files passed and 3 skipped, 3496 tests passed and 36 skipped.
- CI check-runs: not yet reported at opening.
---
_Generated by [Claude
Code](https://claude.ai/code/session_01Utp6CZEhtHfQH5TLEVe3TF)_
---------
Co-authored-by: Claude <noreply@anthropic.com>
fix(service-settings): an `OS_LOCALIZATION_LOCALE` naming a language the boot is still loading is no longer dropped, and Setup's default language accepts by the same locale matcher as the IdP locale claim (#30456)
8
+
9
+
Clause-②: yes (widening) — `@objectstack/core` exports `resolveOfferedLocale(requested, offered)`; `SettingsService` gains `holdOptionSourceVerdicts()` and `sealOptionSources()`. The save of `localization.locale` (`PUT /api/settings/localization`, `SettingsService.setMany`) and an `OS_LOCALIZATION_LOCALE` override now also accept a region or base of an offered language (`fr-FR` where `fr` is offered, `fr` where `fr-FR` is) and another case of an offered code (`zh-cn` for `zh-CN`); nothing accepted before is refused. The IdP locale claim (`resolveIdpLocale`) lands a script or region spelling on the offered code the platform locale table says it means (`zh-TW` on `zh-Hant`, not on a `zh-Hans` listed first).
10
+
Metadata-protocol: none
11
+
12
+
-**The boot window.** The deployment's locale list fills during the boot: the app's authored translations arrive at `kernel:ready`. A `kernel:ready` reader of `localization.locale` (auth's mail and SMS default language) could ask before the language an `OS_LOCALIZATION_LOCALE` override names was in the list; the override was then reported `IGNORED` and the reader kept the next layer's value, though the boot went on to offer that language. `SettingsServicePlugin` now holds the option verdict on a sourced key until `kernel:bootstrapped`: while held, an override the list does not admit yet is in force and not reported; at `kernel:bootstrapped` it is judged again, and one the list still does not admit is reported once, as before, and a settings change is emitted for `localization.locale` so a reader that applied it reads the key again. The other value checks (pattern, domain, bounds, format) are judged at once, as ever. A `SettingsService` constructed without the plugin judges at once, as it always has.
13
+
-**One matcher.** Setup's default language and the IdP locale claim now both ask `resolveOfferedLocale` (`@objectstack/core`): `resolveLocale`'s exact and case-insensitive steps, then the platform locale table's language (`zh-TW` is `zh-Hant`, `en-US` is `en`), then `resolveLocale`'s base-language and variant steps. A language one door takes, the other takes too.
14
+
-**Comment.**`AUTH_EMAIL_TEMPLATE_LOCALES` (plugin-auth) no longer claims to be the setting's options: since #30286 the setting offers the deployment's locale list, and the two ends agree through `normalizeAuthEmailLocale`'s pass-through and the email service's `en-US` fallback.
0 commit comments