From 70896fc36af008fc738ffbaee3674535a7a28f51 Mon Sep 17 00:00:00 2001 From: codex Date: Sat, 7 Nov 2026 03:54:46 +0800 Subject: [PATCH] feat(i18n): read published copy without database access --- web/app/Services/UserCopy/UserCopyCatalog.php | 113 +++++++ .../UserCopy/UserCopyRuntimeReader.php | 301 ++++++++++++++++++ web/tests/UserCopyCatalogRuntimeTest.php | 233 ++++++++++++++ .../UserCopyRuntimeNoDatabaseContractTest.php | 39 +++ 4 files changed, 686 insertions(+) create mode 100644 web/app/Services/UserCopy/UserCopyCatalog.php create mode 100644 web/app/Services/UserCopy/UserCopyRuntimeReader.php create mode 100644 web/tests/UserCopyCatalogRuntimeTest.php create mode 100644 web/tests/UserCopyRuntimeNoDatabaseContractTest.php diff --git a/web/app/Services/UserCopy/UserCopyCatalog.php b/web/app/Services/UserCopy/UserCopyCatalog.php new file mode 100644 index 00000000..6afc15e2 --- /dev/null +++ b/web/app/Services/UserCopy/UserCopyCatalog.php @@ -0,0 +1,113 @@ +,metadata:array>,fallback_scopes:list} */ + private readonly array $snapshot; + + /** @param list $scopes */ + public function __construct( + UserCopyRuntimeReader $reader, + string $locale, + array $scopes + ) { + $this->snapshot = $reader->read($locale, $scopes); + } + + public static function forPage( + UserCopyRuntimeReader $reader, + string $locale, + string $page + ): self { + return new self($reader, $locale, $reader->scopesForPage($page)); + } + + /** @param array $parameters */ + public function text(string $key, array $parameters = []): string + { + if (!array_key_exists($key, $this->snapshot['messages']) + || !isset($this->snapshot['metadata'][$key])) { + throw new UserCopyCatalogException( + 'Unknown user copy key: ' . $key + ); + } + $message = $this->snapshot['messages'][$key]; + $metadata = $this->snapshot['metadata'][$key]; + if (($metadata['hidden'] ?? false) === true) { + return ''; + } + $required = is_array($metadata['parameters'] ?? null) + ? $metadata['parameters'] : []; + $missing = array_values(array_diff($required, array_keys($parameters))); + if ($missing !== []) { + throw new UserCopyCatalogException( + 'Missing user copy parameters for ' . $key . ': ' + . implode(', ', $missing) + ); + } + if (($metadata['format'] ?? 'plain_text') !== 'icu') { + return $message; + } + + $formatter = MessageFormatter::create( + $this->snapshot['locale'], + $message + ); + if (!$formatter instanceof MessageFormatter) { + throw new UserCopyCatalogException( + 'Unable to create user copy formatter for ' . $key . '.' + ); + } + $result = $formatter->format($parameters); + if (!is_string($result)) { + throw new UserCopyCatalogException( + 'Unable to format user copy for ' . $key . ': ' + . $formatter->getErrorMessage() + ); + } + return $result; + } + + /** + * @param array $parameters + * @return array{title:string,body:string,tone:string} + */ + public function toast(string $baseKey, array $parameters = []): array + { + $titleKey = $baseKey . '.title'; + $bodyKey = $baseKey . '.body'; + if (!isset($this->snapshot['messages'][$bodyKey]) + && isset($this->snapshot['messages'][$baseKey . '.message'])) { + $bodyKey = $baseKey . '.message'; + } + $tone = $this->snapshot['metadata'][$bodyKey]['severity'] + ?? $this->snapshot['metadata'][$titleKey]['severity'] + ?? 'info'; + return [ + 'title' => $this->text($titleKey, $parameters), + 'body' => $this->text($bodyKey, $parameters), + 'tone' => is_string($tone) ? $tone : 'info', + ]; + } + + /** @return array */ + public function catalog(): array + { + return $this->snapshot; + } + + public function locale(): string + { + return $this->snapshot['locale']; + } + + public function generation(): ?string + { + return $this->snapshot['generation']; + } +} diff --git a/web/app/Services/UserCopy/UserCopyRuntimeReader.php b/web/app/Services/UserCopy/UserCopyRuntimeReader.php new file mode 100644 index 00000000..34623fa1 --- /dev/null +++ b/web/app/Services/UserCopy/UserCopyRuntimeReader.php @@ -0,0 +1,301 @@ +|null> */ + private array $scopeCache = []; + + public function __construct( + string $rootDirectory, + private readonly UserCopySourceCatalog $source + ) { + $this->root = rtrim($rootDirectory, DIRECTORY_SEPARATOR); + if ($this->root === '') { + throw new UserCopyCatalogException( + 'User copy runtime directory cannot be empty.' + ); + } + } + + /** + * @param list $scopes + * @return array{locale:string,generation:?string,messages:array,metadata:array>,fallback_scopes:list} + */ + public function read(string $locale, array $scopes): array + { + $locale = $this->normalizeLocale($locale); + $scopes = $this->normalizeScopes($scopes); + $fallback = $this->sourceSnapshot($locale, $scopes); + $active = $this->activeGeneration($locale); + if ($active === null) { + return $fallback; + } + + $generation = $active['generation']; + $manifest = $active['manifest']; + $messages = []; + $metadata = []; + $fallbackScopes = []; + foreach ($scopes as $scope) { + $payload = $this->readScope( + $locale, + $generation, + $scope, + $manifest + ); + if ($payload === null) { + $fallbackScopes[] = $scope; + $payload = $this->sourceScope($locale, $scope); + } + foreach ($payload['messages'] as $key => $message) { + $messages[$key] = $message; + } + foreach ($payload['metadata'] as $key => $entryMetadata) { + $metadata[$key] = $entryMetadata; + } + } + ksort($messages, SORT_STRING); + ksort($metadata, SORT_STRING); + + return [ + 'locale' => $locale, + 'generation' => $generation, + 'messages' => $messages, + 'metadata' => $metadata, + 'fallback_scopes' => $fallbackScopes, + ]; + } + + /** + * @return array{locale:string,generation:?string,messages:array,metadata:array>,fallback_scopes:list} + */ + public function readPage(string $locale, string $page): array + { + return $this->read($locale, $this->scopesForPage($page)); + } + + /** @return list */ + public function scopesForPage(string $page): array + { + $pages = $this->source->pageScopes(); + if (!isset($pages[$page])) { + throw new UserCopyCatalogException( + 'Unknown user copy page: ' . $page + ); + } + return $pages[$page]; + } + + /** @return array{generation:string,manifest:array}|null */ + private function activeGeneration(string $locale): ?array + { + $path = $this->root . '/current.json'; + $raw = is_file($path) ? file_get_contents($path) : false; + if (!is_string($raw)) { + return null; + } + try { + $current = json_decode($raw, true, 512, JSON_THROW_ON_ERROR); + } catch (\JsonException) { + return null; + } + $pointer = is_array($current) + && ($current['schema'] ?? null) === 1 + && is_array($current['locales'] ?? null) + && is_array($current['locales'][$locale] ?? null) + ? $current['locales'][$locale] : null; + if ($pointer === null) { + return null; + } + $generation = $pointer['generation'] ?? null; + if (!is_string($generation) + || preg_match('/\Ag-[a-f0-9]{64}\z/D', $generation) !== 1 + || preg_match( + '/\A[a-f0-9]{64}\z/D', + (string) ($pointer['manifest_sha256'] ?? '') + ) !== 1) { + return null; + } + + $manifestPath = $this->root . '/generations/' . $generation + . '/manifest.json'; + $manifestRaw = is_file($manifestPath) + ? file_get_contents($manifestPath) : false; + if (!is_string($manifestRaw) + || !hash_equals($pointer['manifest_sha256'], hash('sha256', $manifestRaw))) { + return null; + } + try { + $manifest = json_decode( + $manifestRaw, + true, + 512, + JSON_THROW_ON_ERROR + ); + } catch (\JsonException) { + return null; + } + if (!is_array($manifest) + || ($manifest['schema'] ?? null) !== 1 + || ($manifest['locale'] ?? null) !== $locale + || ($manifest['generation'] ?? null) !== $generation + || ($manifest['source_manifest_sha256'] ?? null) + !== $this->source->sourceHash() + || ($manifest['catalog_sha256'] ?? null) + !== ($pointer['catalog_sha256'] ?? null) + || !is_array($manifest['scopes'] ?? null)) { + return null; + } + return ['generation' => $generation, 'manifest' => $manifest]; + } + + /** @param array $manifest @return array|null */ + private function readScope( + string $locale, + string $generation, + string $scope, + array $manifest + ): ?array { + $descriptor = $manifest['scopes'][$scope] ?? null; + if (!is_array($descriptor) + || ($descriptor['php'] ?? null) !== $locale . '/' . $scope . '.php' + || preg_match( + '/\A[a-f0-9]{64}\z/D', + (string) ($descriptor['payload_sha256'] ?? '') + ) !== 1) { + return null; + } + + $cacheKey = $generation . '|' . $locale . '|' . $scope; + if (array_key_exists($cacheKey, $this->scopeCache)) { + return $this->scopeCache[$cacheKey]; + } + $path = $this->root . '/generations/' . $generation + . '/' . $locale . '/' . $scope . '.php'; + if (!is_file($path)) { + return $this->scopeCache[$cacheKey] = null; + } + try { + $payload = require $path; + } catch (\Throwable) { + return $this->scopeCache[$cacheKey] = null; + } + if (!is_array($payload) + || ($payload['schema'] ?? null) !== 1 + || ($payload['locale'] ?? null) !== $locale + || ($payload['scope'] ?? null) !== $scope + || !is_array($payload['messages'] ?? null) + || !is_array($payload['metadata'] ?? null)) { + return $this->scopeCache[$cacheKey] = null; + } + $hash = hash( + 'sha256', + UserCopySourceCatalog::canonicalJson($payload) + ); + if (!hash_equals($descriptor['payload_sha256'], $hash)) { + return $this->scopeCache[$cacheKey] = null; + } + return $this->scopeCache[$cacheKey] = $payload; + } + + /** + * @param list $scopes + * @return array{locale:string,generation:null,messages:array,metadata:array>,fallback_scopes:list} + */ + private function sourceSnapshot(string $locale, array $scopes): array + { + $messages = []; + $metadata = []; + foreach ($scopes as $scope) { + $payload = $this->sourceScope($locale, $scope); + $messages += $payload['messages']; + $metadata += $payload['metadata']; + } + ksort($messages, SORT_STRING); + ksort($metadata, SORT_STRING); + return [ + 'locale' => $locale, + 'generation' => null, + 'messages' => $messages, + 'metadata' => $metadata, + 'fallback_scopes' => $scopes, + ]; + } + + /** @return array{messages:array,metadata:array>} */ + private function sourceScope(string $locale, string $scope): array + { + $messages = []; + $metadata = []; + foreach ($this->source->entriesForScopes([$scope]) as $key => $entry) { + $messages[$key] = $entry['source']; + $metadata[$key] = [ + 'kind' => $entry['kind'], + 'criticality' => $entry['criticality'], + 'severity' => $entry['severity'], + 'format' => $entry['format'], + 'required' => $entry['required'], + 'allow_hide' => $entry['allow_hide'], + 'hidden' => false, + 'translated' => false, + 'parameters' => $entry['parameters'], + 'source_hash' => $entry['source_hash'], + 'placeholder_hash' => $entry['placeholder_hash'], + ]; + } + return [ + 'schema' => 1, + 'locale' => $locale, + 'scope' => $scope, + 'messages' => $messages, + 'metadata' => $metadata, + ]; + } + + /** @param list $scopes @return list */ + private function normalizeScopes(array $scopes): array + { + $known = array_fill_keys($this->source->scopes(), true); + foreach ($this->source->pageScopes() as $pageScopes) { + foreach ($pageScopes as $scope) { + $known[$scope] = true; + } + } + $normalized = ['common' => true]; + foreach ($scopes as $scope) { + if (!is_string($scope) || !isset($known[$scope])) { + throw new UserCopyCatalogException( + 'Unknown user copy scope.' + ); + } + $normalized[$scope] = true; + } + return array_keys($normalized); + } + + private function normalizeLocale(string $locale): string + { + $locale = str_replace('_', '-', trim($locale)); + if (preg_match( + '/\A[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8})*\z/D', + $locale + ) !== 1) { + throw new UserCopyCatalogException('Invalid user copy locale.'); + } + $parts = explode('-', $locale); + $parts[0] = strtolower($parts[0]); + for ($index = 1; $index < count($parts); $index++) { + $parts[$index] = strlen($parts[$index]) === 2 + ? strtoupper($parts[$index]) : $parts[$index]; + } + return implode('-', $parts); + } +} diff --git a/web/tests/UserCopyCatalogRuntimeTest.php b/web/tests/UserCopyCatalogRuntimeTest.php new file mode 100644 index 00000000..dee05c3d --- /dev/null +++ b/web/tests/UserCopyCatalogRuntimeTest.php @@ -0,0 +1,233 @@ +isDir() + ? rmdir($item->getPathname()) + : unlink($item->getPathname()); + } + rmdir($directory); +}; + +$manifest = UserCopyManifest::validate([ + 'version' => 1, + 'pages' => [ + 'cloud.empty' => [ + 'label' => '预声明页面', + 'scopes' => ['common', 'empty_scope'], + ], + 'cloud.instances' => [ + 'label' => '实例页面', + 'scopes' => ['common', 'instances'], + ], + ], + 'entries' => [ + [ + 'key' => 'common.toast.success.title', + 'scope' => 'common', + 'page' => 'cloud.instances', + 'kind' => 'toast_title', + 'source' => '操作完成', + 'format' => 'plain_text', + 'parameters' => [], + 'criticality' => 'required', + 'allow_hide' => false, + 'toast_tone' => 'success', + ], + [ + 'key' => 'common.toast.success.body', + 'scope' => 'common', + 'page' => 'cloud.instances', + 'kind' => 'toast_body', + 'source' => '操作已完成。', + 'format' => 'plain_text', + 'parameters' => [], + 'criticality' => 'required', + 'allow_hide' => false, + 'toast_tone' => 'success', + ], + [ + 'key' => 'instances.title', + 'scope' => 'instances', + 'page' => 'cloud.instances', + 'kind' => 'title', + 'source' => '实例', + 'format' => 'plain_text', + 'parameters' => [], + 'criticality' => 'required', + 'allow_hide' => false, + 'toast_tone' => null, + ], + [ + 'key' => 'instances.count', + 'scope' => 'instances', + 'page' => 'cloud.instances', + 'kind' => 'description', + 'source' => '{count, plural, =0 {没有实例} other {# 个实例}}', + 'format' => 'icu', + 'parameters' => ['count' => 'integer'], + 'criticality' => 'required', + 'allow_hide' => false, + 'toast_tone' => null, + ], + [ + 'key' => 'instances.optional_help', + 'scope' => 'instances', + 'page' => 'cloud.instances', + 'kind' => 'help', + 'source' => '中文后备说明', + 'format' => 'plain_text', + 'parameters' => [], + 'criticality' => 'normal', + 'allow_hide' => true, + 'toast_tone' => null, + ], + ], +]); + +$root = sys_get_temp_dir() . '/virt-user-copy-' + . bin2hex(random_bytes(8)); +mkdir($root, 0750, true); + +try { + $source = new UserCopySourceCatalog($manifest); + $assert(in_array('empty_scope', $source->pageScopes()['cloud.empty'], true), + 'A predeclared scope without entries was rejected.'); + $compiler = new UserCopyCatalogCompiler($source); + $store = new UserCopyPublicationStore($root); + + $versionOne = $compiler->compile('en', [ + 'common.toast.success.title' => '管理员发布标题', + 'common.toast.success.body' => '管理员发布内容。', + 'instances.title' => '管理员发布实例标题', + 'instances.count' => '{count, plural, =1 {管理员发布 1 台} other {管理员发布 # 台}}', + ]); + $firstPointer = $store->publish($versionOne); + $assert($firstPointer['generation'] === $versionOne->generation, + 'Publication did not switch to the compiled generation.'); + $assert(is_file($root . '/current.json') + && is_file($root . '/generations/' . $versionOne->generation + . '/en/common.php') + && is_file($root . '/generations/' . $versionOne->generation + . '/en/empty_scope.php') + && is_file($root . '/generations/' . $versionOne->generation + . '/en/instances.json'), + 'Publication did not materialize both immutable catalog formats.'); + + $reader = new UserCopyRuntimeReader($root, $source); + $catalogOne = UserCopyCatalog::forPage( + $reader, + 'en', + 'cloud.instances' + ); + $assert($catalogOne->text('instances.title') === '管理员发布实例标题', + 'The active target translation was not read.'); + $assert($catalogOne->text('instances.optional_help') === '中文后备说明', + 'A missing target translation did not fall back to Chinese source.'); + $assert($catalogOne->text('instances.count', ['count' => 2]) === '管理员发布 2 台', + 'ICU parameters were not rendered with the target locale.'); + $toast = $catalogOne->toast('common.toast.success'); + $assert($toast === [ + 'title' => '管理员发布标题', + 'body' => '管理员发布内容。', + 'tone' => 'success', + ], 'Toast title, body, or source-owned tone drifted.'); + $assert($catalogOne->catalog()['fallback_scopes'] === [], + 'A complete immutable catalog was incorrectly marked as fallback.'); + + $versionTwo = $compiler->compile('en', [ + 'common.toast.success.title' => '管理员发布标题', + 'common.toast.success.body' => '管理员发布内容。', + 'instances.title' => '管理员发布的新实例标题', + 'instances.count' => '{count, plural, =1 {新版 1 台} other {新版 # 台}}', + ]); + $store->publish($versionTwo); + $catalogTwo = UserCopyCatalog::forPage( + $reader, + 'en', + 'cloud.instances' + ); + $assert($catalogOne->text('instances.title') === '管理员发布实例标题' + && $catalogTwo->text('instances.title') === '管理员发布的新实例标题', + 'An atomic generation switch mutated an existing request snapshot.'); + + $store->rollback('en', $versionOne->generation); + $rolledBack = UserCopyCatalog::forPage( + $reader, + 'en', + 'cloud.instances' + ); + $assert($rolledBack->text('instances.title') === '管理员发布实例标题', + 'Rollback did not atomically reactivate the retained generation.'); + + $pointerBeforeFailure = file_get_contents($root . '/current.json'); + $reject(static fn () => $compiler->compile('en', [ + 'instances.count' => '{total, plural, =1 {错误 1 台} other {错误 # 台}}', + ]), 'A placeholder contract mismatch was accepted.'); + $assert(file_get_contents($root . '/current.json') === $pointerBeforeFailure, + 'A failed compilation changed the active generation pointer.'); + + $unpublished = UserCopyCatalog::forPage( + $reader, + 'fr', + 'cloud.instances' + ); + $assert($unpublished->generation() === null + && $unpublished->text('instances.title') === '实例', + 'An unpublished locale did not use the zero-database Chinese fallback.'); + + $hidden = $compiler->compile('en', [ + 'instances.optional_help' => ['hidden' => true], + ]); + $store->publish($hidden); + $hiddenCatalog = UserCopyCatalog::forPage( + $reader, + 'en', + 'cloud.instances' + ); + $assert($hiddenCatalog->text('instances.optional_help') === '', + 'An allowed optional copy slot was not hidden.'); + $reject(static fn () => $compiler->compile('en', [ + 'instances.title' => ['hidden' => true], + ]), 'Required interface copy was allowed to become hidden.'); + + $store->validateGeneration($versionOne->generation); + $store->validateGeneration($versionTwo->generation); +} finally { + $removeTree($root); +} + +echo "User copy runtime publication tests passed.\n"; diff --git a/web/tests/UserCopyRuntimeNoDatabaseContractTest.php b/web/tests/UserCopyRuntimeNoDatabaseContractTest.php new file mode 100644 index 00000000..3e9a7c1a --- /dev/null +++ b/web/tests/UserCopyRuntimeNoDatabaseContractTest.php @@ -0,0 +1,39 @@ +