feat(i18n): publish copy catalogs atomically
parent
68caff0048
commit
fbb8217abf
@ -0,0 +1,464 @@
|
||||
<?php
|
||||
|
||||
namespace App\Services\UserCopy;
|
||||
|
||||
/**
|
||||
* Filesystem Adapter for immutable locale generations.
|
||||
*
|
||||
* A generation is fully fsynced and atomically renamed before current.json is
|
||||
* switched. Publication failures can therefore leave only an unreachable
|
||||
* immutable generation; the previously active pointer remains authoritative.
|
||||
*/
|
||||
final class UserCopyPublicationStore
|
||||
{
|
||||
private readonly string $root;
|
||||
|
||||
public function __construct(string $rootDirectory)
|
||||
{
|
||||
$rootDirectory = rtrim($rootDirectory, DIRECTORY_SEPARATOR);
|
||||
if ($rootDirectory === '') {
|
||||
throw new UserCopyCatalogException(
|
||||
'User copy publication directory cannot be empty.'
|
||||
);
|
||||
}
|
||||
$this->ensureDirectory($rootDirectory);
|
||||
$resolved = realpath($rootDirectory);
|
||||
if (!is_string($resolved) || $resolved === '') {
|
||||
throw new UserCopyCatalogException(
|
||||
'User copy publication directory cannot be resolved.'
|
||||
);
|
||||
}
|
||||
$this->root = $resolved;
|
||||
$this->ensureDirectory($this->root . '/generations');
|
||||
}
|
||||
|
||||
/** @return array<string,mixed> */
|
||||
public function publish(UserCopyCompiledCatalog $catalog): array
|
||||
{
|
||||
return $this->withPublicationLock(function () use ($catalog): array {
|
||||
$this->assertGeneration($catalog->generation);
|
||||
$target = $this->generationDirectory($catalog->generation);
|
||||
if (is_dir($target)) {
|
||||
$manifest = $this->validateGeneration($catalog->generation);
|
||||
if (($manifest['locale'] ?? null) !== $catalog->locale
|
||||
|| !hash_equals(
|
||||
(string) ($manifest['catalog_sha256'] ?? ''),
|
||||
(string) ($catalog->manifest['catalog_sha256'] ?? '')
|
||||
)) {
|
||||
throw new UserCopyCatalogException(
|
||||
'An incompatible immutable user copy generation exists.'
|
||||
);
|
||||
}
|
||||
} else {
|
||||
$this->materializeGeneration($catalog);
|
||||
$this->validateGeneration($catalog->generation);
|
||||
}
|
||||
|
||||
$current = $this->readCurrentPointer();
|
||||
$manifestHash = hash(
|
||||
'sha256',
|
||||
$this->readRequiredFile($target . '/manifest.json')
|
||||
);
|
||||
$current['locales'][$catalog->locale] = [
|
||||
'generation' => $catalog->generation,
|
||||
'manifest_sha256' => $manifestHash,
|
||||
'catalog_sha256' => $catalog->manifest['catalog_sha256'],
|
||||
];
|
||||
ksort($current['locales'], SORT_STRING);
|
||||
$current['updated_at'] = gmdate('c');
|
||||
$this->writeCurrentPointer($current);
|
||||
return $current['locales'][$catalog->locale];
|
||||
});
|
||||
}
|
||||
|
||||
/** @return array<string,mixed> */
|
||||
public function rollback(string $locale, string $generation): array
|
||||
{
|
||||
return $this->withPublicationLock(function () use (
|
||||
$locale,
|
||||
$generation
|
||||
): array {
|
||||
$locale = $this->normalizeLocale($locale);
|
||||
$manifest = $this->validateGeneration($generation);
|
||||
if (($manifest['locale'] ?? null) !== $locale) {
|
||||
throw new UserCopyCatalogException(
|
||||
'User copy generation belongs to another locale.'
|
||||
);
|
||||
}
|
||||
|
||||
$manifestPath = $this->generationDirectory($generation)
|
||||
. '/manifest.json';
|
||||
$current = $this->readCurrentPointer();
|
||||
$current['locales'][$locale] = [
|
||||
'generation' => $generation,
|
||||
'manifest_sha256' => hash(
|
||||
'sha256',
|
||||
$this->readRequiredFile($manifestPath)
|
||||
),
|
||||
'catalog_sha256' => $manifest['catalog_sha256'],
|
||||
];
|
||||
ksort($current['locales'], SORT_STRING);
|
||||
$current['updated_at'] = gmdate('c');
|
||||
$this->writeCurrentPointer($current);
|
||||
return $current['locales'][$locale];
|
||||
});
|
||||
}
|
||||
|
||||
/** @return array<string,mixed> */
|
||||
public function current(): array
|
||||
{
|
||||
return $this->readCurrentPointer();
|
||||
}
|
||||
|
||||
/** @return array<string,mixed> */
|
||||
public function validateGeneration(string $generation): array
|
||||
{
|
||||
$this->assertGeneration($generation);
|
||||
$directory = $this->generationDirectory($generation);
|
||||
$raw = $this->readRequiredFile($directory . '/manifest.json');
|
||||
try {
|
||||
$manifest = json_decode($raw, true, 512, JSON_THROW_ON_ERROR);
|
||||
} catch (\JsonException $exception) {
|
||||
throw new UserCopyCatalogException(
|
||||
'User copy generation manifest is invalid.',
|
||||
0,
|
||||
$exception
|
||||
);
|
||||
}
|
||||
if (!is_array($manifest)
|
||||
|| ($manifest['schema'] ?? null) !== 1
|
||||
|| ($manifest['generation'] ?? null) !== $generation
|
||||
|| !is_string($manifest['locale'] ?? null)
|
||||
|| !is_string($manifest['catalog_sha256'] ?? null)
|
||||
|| !is_array($manifest['scopes'] ?? null)) {
|
||||
throw new UserCopyCatalogException(
|
||||
'User copy generation manifest has an invalid shape.'
|
||||
);
|
||||
}
|
||||
|
||||
$locale = $this->normalizeLocale($manifest['locale']);
|
||||
$scopeHashes = [];
|
||||
foreach ($manifest['scopes'] as $scope => $descriptor) {
|
||||
$this->assertScope($scope);
|
||||
if (!is_array($descriptor)
|
||||
|| ($descriptor['php'] ?? null) !== $locale . '/' . $scope . '.php'
|
||||
|| ($descriptor['json'] ?? null) !== $locale . '/' . $scope . '.json'
|
||||
|| preg_match(
|
||||
'/\A[a-f0-9]{64}\z/D',
|
||||
(string) ($descriptor['payload_sha256'] ?? '')
|
||||
) !== 1) {
|
||||
throw new UserCopyCatalogException(
|
||||
'User copy scope descriptor is invalid: ' . $scope
|
||||
);
|
||||
}
|
||||
$jsonRaw = $this->readRequiredFile(
|
||||
$directory . '/' . $descriptor['json']
|
||||
);
|
||||
try {
|
||||
$jsonPayload = json_decode(
|
||||
$jsonRaw,
|
||||
true,
|
||||
512,
|
||||
JSON_THROW_ON_ERROR
|
||||
);
|
||||
} catch (\JsonException $exception) {
|
||||
throw new UserCopyCatalogException(
|
||||
'Compiled user copy JSON is invalid: ' . $scope,
|
||||
0,
|
||||
$exception
|
||||
);
|
||||
}
|
||||
$phpPath = $directory . '/' . $descriptor['php'];
|
||||
if (!is_file($phpPath)) {
|
||||
throw new UserCopyCatalogException(
|
||||
'Compiled user copy PHP is missing: ' . $scope
|
||||
);
|
||||
}
|
||||
try {
|
||||
$phpPayload = require $phpPath;
|
||||
} catch (\Throwable $exception) {
|
||||
throw new UserCopyCatalogException(
|
||||
'Compiled user copy PHP is invalid: ' . $scope,
|
||||
0,
|
||||
$exception
|
||||
);
|
||||
}
|
||||
if (!is_array($jsonPayload) || !is_array($phpPayload)
|
||||
|| UserCopySourceCatalog::canonicalJson($jsonPayload)
|
||||
!== UserCopySourceCatalog::canonicalJson($phpPayload)) {
|
||||
throw new UserCopyCatalogException(
|
||||
'Compiled user copy scope formats disagree: ' . $scope
|
||||
);
|
||||
}
|
||||
$payloadHash = hash(
|
||||
'sha256',
|
||||
UserCopySourceCatalog::canonicalJson($phpPayload)
|
||||
);
|
||||
if (!hash_equals($descriptor['payload_sha256'], $payloadHash)) {
|
||||
throw new UserCopyCatalogException(
|
||||
'Compiled user copy scope identity is invalid: ' . $scope
|
||||
);
|
||||
}
|
||||
$scopeHashes[$scope] = $payloadHash;
|
||||
}
|
||||
ksort($scopeHashes, SORT_STRING);
|
||||
$catalogHash = hash(
|
||||
'sha256',
|
||||
UserCopySourceCatalog::canonicalJson($scopeHashes)
|
||||
);
|
||||
if (!hash_equals($manifest['catalog_sha256'], $catalogHash)) {
|
||||
throw new UserCopyCatalogException(
|
||||
'Compiled user copy catalog identity is invalid.'
|
||||
);
|
||||
}
|
||||
return $manifest;
|
||||
}
|
||||
|
||||
private function materializeGeneration(UserCopyCompiledCatalog $catalog): void
|
||||
{
|
||||
$temporary = $this->root . '/generations/.tmp-'
|
||||
. bin2hex(random_bytes(12));
|
||||
$target = $this->generationDirectory($catalog->generation);
|
||||
$this->ensureDirectory($temporary);
|
||||
try {
|
||||
$localeDirectory = $temporary . '/' . $catalog->locale;
|
||||
$this->ensureDirectory($localeDirectory);
|
||||
foreach ($catalog->scopes as $scope => $payload) {
|
||||
$this->assertScope($scope);
|
||||
$this->writeSyncedFile(
|
||||
$localeDirectory . '/' . $scope . '.json',
|
||||
UserCopySourceCatalog::canonicalJson($payload)
|
||||
);
|
||||
$this->writeSyncedFile(
|
||||
$localeDirectory . '/' . $scope . '.php',
|
||||
"<?php\n\nreturn " . var_export($payload, true) . ";\n"
|
||||
);
|
||||
}
|
||||
$this->syncDirectory($localeDirectory);
|
||||
$this->writeSyncedFile(
|
||||
$temporary . '/manifest.json',
|
||||
UserCopySourceCatalog::canonicalJson($catalog->manifest)
|
||||
);
|
||||
$this->syncDirectory($temporary);
|
||||
if (!rename($temporary, $target)) {
|
||||
throw new UserCopyCatalogException(
|
||||
'Unable to publish immutable user copy generation.'
|
||||
);
|
||||
}
|
||||
$this->syncDirectory($this->root . '/generations');
|
||||
} finally {
|
||||
if (is_dir($temporary)) {
|
||||
$this->removeTemporaryDirectory($temporary);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/** @return array<string,mixed> */
|
||||
private function readCurrentPointer(): array
|
||||
{
|
||||
$path = $this->root . '/current.json';
|
||||
if (!is_file($path)) {
|
||||
return ['schema' => 1, 'locales' => []];
|
||||
}
|
||||
$raw = $this->readRequiredFile($path);
|
||||
try {
|
||||
$current = json_decode($raw, true, 512, JSON_THROW_ON_ERROR);
|
||||
} catch (\JsonException $exception) {
|
||||
throw new UserCopyCatalogException(
|
||||
'Current user copy pointer is invalid.',
|
||||
0,
|
||||
$exception
|
||||
);
|
||||
}
|
||||
if (!is_array($current)
|
||||
|| ($current['schema'] ?? null) !== 1
|
||||
|| !is_array($current['locales'] ?? null)) {
|
||||
throw new UserCopyCatalogException(
|
||||
'Current user copy pointer has an invalid shape.'
|
||||
);
|
||||
}
|
||||
return $current;
|
||||
}
|
||||
|
||||
/** @param array<string,mixed> $current */
|
||||
private function writeCurrentPointer(array $current): void
|
||||
{
|
||||
$temporary = $this->root . '/.current-'
|
||||
. bin2hex(random_bytes(12)) . '.tmp';
|
||||
try {
|
||||
$this->writeSyncedFile(
|
||||
$temporary,
|
||||
UserCopySourceCatalog::canonicalJson($current)
|
||||
);
|
||||
if (!rename($temporary, $this->root . '/current.json')) {
|
||||
throw new UserCopyCatalogException(
|
||||
'Unable to switch the current user copy generation.'
|
||||
);
|
||||
}
|
||||
$this->syncDirectory($this->root);
|
||||
} finally {
|
||||
if (is_file($temporary)) {
|
||||
@unlink($temporary);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/** @template T @param callable():T $callback @return T */
|
||||
private function withPublicationLock(callable $callback)
|
||||
{
|
||||
$handle = fopen($this->root . '/publish.lock', 'c+b');
|
||||
if (!is_resource($handle)) {
|
||||
throw new UserCopyCatalogException(
|
||||
'Unable to open the user copy publication lock.'
|
||||
);
|
||||
}
|
||||
try {
|
||||
if (!flock($handle, LOCK_EX)) {
|
||||
throw new UserCopyCatalogException(
|
||||
'Unable to acquire the user copy publication lock.'
|
||||
);
|
||||
}
|
||||
return $callback();
|
||||
} finally {
|
||||
flock($handle, LOCK_UN);
|
||||
fclose($handle);
|
||||
}
|
||||
}
|
||||
|
||||
private function writeSyncedFile(string $path, string $contents): void
|
||||
{
|
||||
$handle = fopen($path, 'x+b');
|
||||
if (!is_resource($handle)) {
|
||||
throw new UserCopyCatalogException(
|
||||
'Unable to create compiled user copy file.'
|
||||
);
|
||||
}
|
||||
try {
|
||||
$length = strlen($contents);
|
||||
$written = 0;
|
||||
while ($written < $length) {
|
||||
$count = fwrite($handle, substr($contents, $written));
|
||||
if (!is_int($count) || $count < 1) {
|
||||
throw new UserCopyCatalogException(
|
||||
'Unable to write compiled user copy file.'
|
||||
);
|
||||
}
|
||||
$written += $count;
|
||||
}
|
||||
if (!fflush($handle) || !fsync($handle)) {
|
||||
throw new UserCopyCatalogException(
|
||||
'Unable to sync compiled user copy file.'
|
||||
);
|
||||
}
|
||||
} finally {
|
||||
fclose($handle);
|
||||
}
|
||||
@chmod($path, 0640);
|
||||
}
|
||||
|
||||
private function syncDirectory(string $path): void
|
||||
{
|
||||
$handle = fopen($path, 'r');
|
||||
if (!is_resource($handle)) {
|
||||
throw new UserCopyCatalogException(
|
||||
'Unable to open user copy directory for syncing.'
|
||||
);
|
||||
}
|
||||
try {
|
||||
if (!fsync($handle)) {
|
||||
throw new UserCopyCatalogException(
|
||||
'Unable to sync user copy directory.'
|
||||
);
|
||||
}
|
||||
} finally {
|
||||
fclose($handle);
|
||||
}
|
||||
}
|
||||
|
||||
private function ensureDirectory(string $path): void
|
||||
{
|
||||
if (is_dir($path)) {
|
||||
return;
|
||||
}
|
||||
if (!mkdir($path, 0750, true) && !is_dir($path)) {
|
||||
throw new UserCopyCatalogException(
|
||||
'Unable to create user copy publication directory.'
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
private function readRequiredFile(string $path): string
|
||||
{
|
||||
$contents = is_file($path) ? file_get_contents($path) : false;
|
||||
if (!is_string($contents)) {
|
||||
throw new UserCopyCatalogException(
|
||||
'Required user copy publication file is unavailable.'
|
||||
);
|
||||
}
|
||||
return $contents;
|
||||
}
|
||||
|
||||
private function generationDirectory(string $generation): string
|
||||
{
|
||||
return $this->root . '/generations/' . $generation;
|
||||
}
|
||||
|
||||
private function assertGeneration(string $generation): void
|
||||
{
|
||||
if (preg_match('/\Ag-[a-f0-9]{64}\z/D', $generation) !== 1) {
|
||||
throw new UserCopyCatalogException(
|
||||
'Invalid user copy generation identifier.'
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
private function assertScope(string $scope): void
|
||||
{
|
||||
if (preg_match('/\A[a-z0-9][a-z0-9._-]{0,63}\z/D', $scope) !== 1) {
|
||||
throw new UserCopyCatalogException('Invalid user copy scope.');
|
||||
}
|
||||
}
|
||||
|
||||
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);
|
||||
}
|
||||
|
||||
private function removeTemporaryDirectory(string $directory): void
|
||||
{
|
||||
$prefix = $this->root . '/generations/.tmp-';
|
||||
if (!str_starts_with($directory, $prefix)) {
|
||||
throw new UserCopyCatalogException(
|
||||
'Refusing to remove a non-temporary user copy directory.'
|
||||
);
|
||||
}
|
||||
$iterator = new \RecursiveIteratorIterator(
|
||||
new \RecursiveDirectoryIterator(
|
||||
$directory,
|
||||
\FilesystemIterator::SKIP_DOTS
|
||||
),
|
||||
\RecursiveIteratorIterator::CHILD_FIRST
|
||||
);
|
||||
foreach ($iterator as $item) {
|
||||
if ($item->isDir()) {
|
||||
@rmdir($item->getPathname());
|
||||
} else {
|
||||
@unlink($item->getPathname());
|
||||
}
|
||||
}
|
||||
@rmdir($directory);
|
||||
}
|
||||
}
|
||||
@ -0,0 +1,93 @@
|
||||
<?php
|
||||
|
||||
require dirname(__DIR__) . '/vendor/autoload.php';
|
||||
|
||||
use App\Services\UserCopy\UserCopyCatalogCompiler;
|
||||
use App\Services\UserCopy\UserCopyManifest;
|
||||
use App\Services\UserCopy\UserCopyPublicationStore;
|
||||
use App\Services\UserCopy\UserCopySourceCatalog;
|
||||
|
||||
$assert = static function (bool $condition, string $message): void {
|
||||
if (!$condition) {
|
||||
throw new RuntimeException($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' => [
|
||||
'test.page' => ['label' => '测试页', 'scopes' => ['common']],
|
||||
],
|
||||
'entries' => [[
|
||||
'key' => 'common.test.title',
|
||||
'scope' => 'common',
|
||||
'page' => 'test.page',
|
||||
'kind' => 'title',
|
||||
'source' => '中文安全基线',
|
||||
'format' => 'plain_text',
|
||||
'parameters' => [],
|
||||
'criticality' => 'required',
|
||||
'allow_hide' => false,
|
||||
'toast_tone' => null,
|
||||
]],
|
||||
]);
|
||||
$compiler = new UserCopyCatalogCompiler(new UserCopySourceCatalog($manifest));
|
||||
$root = sys_get_temp_dir() . '/virt-user-copy-store-'
|
||||
. bin2hex(random_bytes(8));
|
||||
mkdir($root, 0750, true);
|
||||
|
||||
try {
|
||||
$store = new UserCopyPublicationStore($root);
|
||||
$first = $compiler->compile('en', [
|
||||
'common.test.title' => '管理员发布版本一',
|
||||
]);
|
||||
$firstPointer = $store->publish($first);
|
||||
$assert($firstPointer['generation'] === $first->generation,
|
||||
'First immutable generation was not activated.');
|
||||
$store->validateGeneration($first->generation);
|
||||
|
||||
$second = $compiler->compile('en', [
|
||||
'common.test.title' => '管理员发布版本二',
|
||||
]);
|
||||
$secondPointer = $store->publish($second);
|
||||
$assert($secondPointer['generation'] === $second->generation
|
||||
&& $first->generation !== $second->generation,
|
||||
'A changed catalog did not create a new generation.');
|
||||
$assert(is_dir($root . '/generations/' . $first->generation)
|
||||
&& is_dir($root . '/generations/' . $second->generation),
|
||||
'Publishing removed a retained immutable generation.');
|
||||
|
||||
$rollback = $store->rollback('en', $first->generation);
|
||||
$assert($rollback['generation'] === $first->generation,
|
||||
'Rollback did not reactivate the retained generation.');
|
||||
$current = json_decode(
|
||||
(string) file_get_contents($root . '/current.json'),
|
||||
true,
|
||||
512,
|
||||
JSON_THROW_ON_ERROR
|
||||
);
|
||||
$assert($current['locales']['en']['generation'] === $first->generation,
|
||||
'The authoritative pointer disagrees with the rollback result.');
|
||||
} finally {
|
||||
$removeTree($root);
|
||||
}
|
||||
|
||||
echo "User copy publication store tests passed.\n";
|
||||
Loading…
Reference in New Issue