feat(i18n): read published copy without database access

go
codex 2 weeks ago
parent fbb8217abf
commit 70896fc36a

@ -0,0 +1,113 @@
<?php
namespace App\Services\UserCopy;
use MessageFormatter;
/** Small runtime Interface for server-rendered pages and JS bootstrap data. */
final class UserCopyCatalog
{
/** @var array{locale:string,generation:?string,messages:array<string,string>,metadata:array<string,array<string,mixed>>,fallback_scopes:list<string>} */
private readonly array $snapshot;
/** @param list<string> $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<string,mixed> $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<string,mixed> $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<string,mixed> */
public function catalog(): array
{
return $this->snapshot;
}
public function locale(): string
{
return $this->snapshot['locale'];
}
public function generation(): ?string
{
return $this->snapshot['generation'];
}
}

@ -0,0 +1,301 @@
<?php
namespace App\Services\UserCopy;
/**
* Read-only runtime Adapter. It reads only current.json and immutable files;
* persistence services are deliberately absent from this dependency graph.
*/
final class UserCopyRuntimeReader
{
private readonly string $root;
/** @var array<string,array<string,mixed>|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<string> $scopes
* @return array{locale:string,generation:?string,messages:array<string,string>,metadata:array<string,array<string,mixed>>,fallback_scopes:list<string>}
*/
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<string,string>,metadata:array<string,array<string,mixed>>,fallback_scopes:list<string>}
*/
public function readPage(string $locale, string $page): array
{
return $this->read($locale, $this->scopesForPage($page));
}
/** @return list<string> */
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<string,mixed>}|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<string,mixed> $manifest @return array<string,mixed>|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<string> $scopes
* @return array{locale:string,generation:null,messages:array<string,string>,metadata:array<string,array<string,mixed>>,fallback_scopes:list<string>}
*/
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<string,string>,metadata:array<string,array<string,mixed>>} */
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<string> $scopes @return list<string> */
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);
}
}

@ -0,0 +1,233 @@
<?php
require dirname(__DIR__) . '/vendor/autoload.php';
use App\Services\UserCopy\UserCopyCatalog;
use App\Services\UserCopy\UserCopyCatalogCompiler;
use App\Services\UserCopy\UserCopyCatalogException;
use App\Services\UserCopy\UserCopyManifest;
use App\Services\UserCopy\UserCopyPublicationStore;
use App\Services\UserCopy\UserCopyRuntimeReader;
use App\Services\UserCopy\UserCopySourceCatalog;
$assert = static function (bool $condition, string $message): void {
if (!$condition) {
throw new RuntimeException($message);
}
};
$reject = static function (callable $call, string $message) use ($assert): void {
try {
$call();
} catch (UserCopyCatalogException) {
return;
}
$assert(false, $message);
};
$removeTree = static function (string $directory): void {
if (!is_dir($directory)) {
return;
}
$iterator = new RecursiveIteratorIterator(
new RecursiveDirectoryIterator(
$directory,
FilesystemIterator::SKIP_DOTS
),
RecursiveIteratorIterator::CHILD_FIRST
);
foreach ($iterator as $item) {
$item->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";

@ -0,0 +1,39 @@
<?php
$root = dirname(__DIR__) . '/app/Services/UserCopy';
$files = glob($root . '/*.php');
if (!is_array($files) || $files === []) {
throw new RuntimeException('User copy runtime module is missing.');
}
$forbidden = [
'/Illuminate\\\\Database/',
'/\\bCapsule\\b/',
'/\\bPDO\\b/',
'/\\bPredis\\b/',
'/\\bRedis(?:Client)?\\b/',
'/\\bDB::/',
];
foreach ($files as $file) {
$source = file_get_contents($file);
if (!is_string($source)) {
throw new RuntimeException('Unable to read ' . $file);
}
foreach ($forbidden as $pattern) {
if (preg_match($pattern, $source) === 1) {
throw new RuntimeException(
basename($file) . ' introduced a runtime persistence dependency.'
);
}
}
}
$reader = file_get_contents($root . '/UserCopyRuntimeReader.php');
if (!is_string($reader)
|| preg_match('/\\b(?:fopen|fwrite|rename|mkdir|unlink)\\s*\\(/', $reader) === 1) {
throw new RuntimeException(
'The user copy runtime reader is no longer read-only.'
);
}
echo "User copy runtime stays filesystem-only and read-only.\n";
Loading…
Cancel
Save