You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
virt/web/app/Services/Cloud/CloudObjectStorageBackendRe...

777 lines
32 KiB
PHTML

<?php
namespace App\Services\Cloud;
use App\Models\CloudStorageBackend;
use App\Models\CloudStorageReplica;
/**
* Transactional registry for object-storage failure domains.
*
* This service owns configuration and health only. It never copies or deletes
* provider objects.
* Historical or failed rows remain addressable for exact reconciliation;
* only two backends may be active for new writes at the same time.
*/
final class CloudObjectStorageBackendRegistry
{
private const CREDENTIAL_PURPOSE = 'object-storage-backend-credentials';
private const MAX_ACTIVE_BACKENDS = 2;
/** @return list<array<string,mixed>> */
public static function listView(): array
{
return CloudStorageBackend::query()->where('admin_state', '<>', 'retired')
->orderBy('write_priority')->orderBy('id')->get()
->map(static fn (CloudStorageBackend $backend): array => self::dto($backend))
->values()->all();
}
/** @return array<string,int> */
public static function summary(): array
{
$backends = CloudStorageBackend::query()
->where('admin_state', '<>', 'retired')->get();
return [
'configured_backends' => $backends->count(),
'active_backends' => $backends->where('admin_state', 'active')->count(),
'healthy_backends' => $backends->where('health_state', 'healthy')->count(),
'writable_backends' => $backends->filter(
static fn (CloudStorageBackend $backend): bool => self::isWritable($backend)
)->count(),
];
}
/** @return array<string,mixed> */
public static function create(array $input, int $actorUserId): array
{
self::assertActor($actorUserId);
$spec = self::validatedSpec($input, true);
$connection = (new CloudStorageBackend())->getConnection();
$backend = $connection->transaction(static function () use (
$connection,
$spec
): CloudStorageBackend {
self::lockCatalog($connection);
$rows = CloudStorageBackend::query()->where('admin_state', '<>', 'retired')
->orderBy('id')->lockForUpdate()->get();
if ($rows->contains(static fn (CloudStorageBackend $row): bool =>
hash_equals((string) $row->identity_sha256, $spec['identity_sha256']))) {
throw new CloudError('相同 Endpoint、Bucket 和前缀的对象存储已存在', 409);
}
$now = time();
$backend = new CloudStorageBackend();
$backend->backend_key = bin2hex(random_bytes(16));
self::applySpec($backend, $spec);
$backend->config_revision = 1;
$backend->tested_revision = 0;
$backend->admin_state = 'draft';
$backend->health_state = 'unknown';
$backend->consecutive_failures = 0;
$backend->consecutive_successes = 0;
$backend->last_error_code = '';
$backend->last_tested_at = 0;
$backend->last_healthy_at = 0;
$backend->next_probe_at = 0;
$backend->created_at = $now;
$backend->updated_at = $now;
$backend->save();
return $backend;
});
return self::dto($backend);
}
/** @return array<string,mixed> */
public static function update(
int $backendId,
array $input,
int $expectedRevision,
int $actorUserId
): array {
self::assertActor($actorUserId);
self::assertId($backendId);
self::assertRevision($expectedRevision);
$connection = (new CloudStorageBackend())->getConnection();
$backend = $connection->transaction(static function () use (
$connection,
$backendId,
$input,
$expectedRevision
): CloudStorageBackend {
self::lockCatalog($connection);
$backend = CloudStorageBackend::query()->whereKey($backendId)
->lockForUpdate()->first();
if (!$backend instanceof CloudStorageBackend
|| (string) $backend->admin_state === 'retired') {
throw new CloudError('对象存储后端不存在', 404);
}
self::assertExpectedRevision($backend, $expectedRevision);
$spec = self::validatedSpec($input, false, $backend);
$identityChanged = !hash_equals(
(string) $backend->identity_sha256,
$spec['identity_sha256']
);
if ($identityChanged && CloudStorageReplica::query()
->where('backend_id', $backend->id)->exists()) {
throw new CloudError('已有对象副本引用该后端,不能修改 Endpoint、Bucket、前缀或寻址方式', 409);
}
if ($identityChanged && CloudStorageBackend::query()
->where('id', '<>', $backend->id)
->where('identity_sha256', $spec['identity_sha256'])
->where('admin_state', '<>', 'retired')->exists()) {
throw new CloudError('相同 Endpoint、Bucket 和前缀的对象存储已存在', 409);
}
$runtimeChanged = self::runtimeChanged($backend, $spec);
$oldRevision = (int) $backend->config_revision;
$wasTested = (int) $backend->tested_revision === $oldRevision;
self::applySpec($backend, $spec);
$backend->config_revision = $oldRevision + 1;
if ($runtimeChanged) {
$backend->tested_revision = 0;
$backend->health_state = 'unknown';
$backend->consecutive_successes = 0;
$backend->last_error_code = '';
$backend->next_probe_at = 0;
$backend->admin_state = CloudStorageReplica::query()
->where('backend_id', $backend->id)->exists()
? 'read_only' : 'draft';
} elseif ($wasTested) {
$backend->tested_revision = $oldRevision + 1;
}
$backend->updated_at = time();
$backend->save();
return $backend;
});
return self::dto($backend);
}
/** @return array<string,mixed> */
public static function test(
int $backendId,
int $expectedRevision,
int $actorUserId,
?CloudObjectStorageS3Client $client = null
): array {
self::assertActor($actorUserId);
self::assertId($backendId);
self::assertRevision($expectedRevision);
$backend = self::find($backendId);
self::assertExpectedRevision($backend, $expectedRevision);
$runtime = self::runtimeFromBackend($backend);
try {
($client ?? new CloudObjectStorageS3Client())->headBucket(
$runtime['config'],
$runtime['credentials']
);
} catch (CloudObjectStorageTestError $error) {
self::recordTestFailure($backendId, $expectedRevision, $error->publicCode);
throw new CloudError($error->getMessage(), 502);
}
$connection = $backend->getConnection();
$backend = $connection->transaction(static function () use (
$backendId,
$expectedRevision
): CloudStorageBackend {
$locked = CloudStorageBackend::query()->whereKey($backendId)
->lockForUpdate()->firstOrFail();
self::assertExpectedRevision($locked, $expectedRevision,
'连接测试期间配置已改变,请重新测试');
$now = time();
$locked->tested_revision = $expectedRevision;
$locked->health_state = 'healthy';
$locked->consecutive_failures = 0;
$locked->consecutive_successes = (int) $locked->consecutive_successes + 1;
$locked->last_error_code = '';
$locked->last_tested_at = $now;
$locked->last_healthy_at = $now;
$locked->next_probe_at = $now + 300;
$locked->updated_at = $now;
$locked->save();
return $locked;
});
return self::dto($backend);
}
/** @return array<string,mixed> */
public static function activate(int $backendId, int $expectedRevision, int $actorUserId): array
{
return self::transition($backendId, $expectedRevision, $actorUserId,
['draft', 'disabled', 'read_only'], 'active', true);
}
/** @return array<string,mixed> */
public static function drain(int $backendId, int $expectedRevision, int $actorUserId): array
{
return self::transition($backendId, $expectedRevision, $actorUserId,
['active', 'read_only'], 'draining', false);
}
/** @return array<string,mixed> */
public static function resume(int $backendId, int $expectedRevision, int $actorUserId): array
{
return self::transition($backendId, $expectedRevision, $actorUserId,
['draining'], 'active', true);
}
/** @return array<string,mixed> */
public static function disable(int $backendId, int $expectedRevision, int $actorUserId): array
{
return self::transition($backendId, $expectedRevision, $actorUserId,
['draft', 'active', 'read_only', 'draining', 'disabled'],
'disabled', false);
}
/**
* Server-side runtime. Credentials and provider identity never enter a DTO.
* Disabled/draining backends remain usable for exact historical reads and
* deletes; requireHealthy only checks current connectivity evidence.
*
* @return array{config:array<string,mixed>,credentials:array{access_key_id:string,secret_access_key:string},revision:int,backend_id:int}
*/
public static function runtime(int $backendId, bool $requireHealthy = true): array
{
self::assertId($backendId);
$backend = self::find($backendId);
if ((string) $backend->admin_state === 'retired') {
throw new CloudError('对象存储后端已退役', 503);
}
if ($requireHealthy && !self::hasCurrentHealth($backend)) {
throw new CloudError('对象存储后端尚未通过当前配置的连接验证', 503);
}
return self::runtimeFromBackend($backend);
}
/** @return array<string,mixed> */
private static function transition(
int $backendId,
int $expectedRevision,
int $actorUserId,
array $allowed,
string $target,
bool $requireHealthy
): array {
self::assertActor($actorUserId);
self::assertId($backendId);
self::assertRevision($expectedRevision);
$connection = (new CloudStorageBackend())->getConnection();
$backend = $connection->transaction(static function () use (
$connection,
$backendId,
$expectedRevision,
$allowed,
$target,
$requireHealthy
): CloudStorageBackend {
self::lockCatalog($connection);
$backends = CloudStorageBackend::query()
->where('admin_state', '<>', 'retired')
->orderBy('id')->lockForUpdate()->get();
$backend = $backends->first(static fn (
CloudStorageBackend $row
): bool => (int) $row->id === $backendId);
if (!$backend instanceof CloudStorageBackend) {
throw new CloudError('对象存储后端不存在', 404);
}
self::assertExpectedRevision($backend, $expectedRevision);
if (!in_array((string) $backend->admin_state, $allowed, true)) {
throw new CloudError('对象存储后端当前状态不允许此操作', 409);
}
if ($requireHealthy && !self::hasCurrentHealth($backend)) {
throw new CloudError('请先通过当前配置的连接测试', 409);
}
if ($target === 'active') {
$otherActive = $backends->filter(static fn (
CloudStorageBackend $row
): bool => (int) $row->id !== $backendId
&& (string) $row->admin_state === 'active')->count();
if ($otherActive >= self::MAX_ACTIVE_BACKENDS) {
throw new CloudError(
'同时最多启用两个对象存储后端,请先排空或停用一个后端',
409
);
}
}
$oldRevision = (int) $backend->config_revision;
$wasTested = (int) $backend->tested_revision === $oldRevision;
$backend->config_revision = $oldRevision + 1;
if ($wasTested) {
$backend->tested_revision = $oldRevision + 1;
}
$backend->admin_state = $target;
$backend->updated_at = time();
$backend->save();
return $backend;
});
return self::dto($backend);
}
private static function recordTestFailure(int $backendId, int $expectedRevision, string $code): void
{
$connection = (new CloudStorageBackend())->getConnection();
$connection->transaction(static function () use (
$backendId,
$expectedRevision,
$code
): void {
$backend = CloudStorageBackend::query()->whereKey($backendId)
->lockForUpdate()->firstOrFail();
self::assertExpectedRevision($backend, $expectedRevision,
'连接测试期间配置已改变,请重新测试');
$backend->tested_revision = 0;
$backend->health_state = in_array($code, [
'endpoint_unreachable', 'service_unavailable', 'rate_limited',
], true) ? 'unreachable' : 'degraded';
$backend->consecutive_failures = (int) $backend->consecutive_failures + 1;
$backend->consecutive_successes = 0;
$backend->last_error_code = $code;
$backend->last_tested_at = time();
$backend->next_probe_at = time() + min(
3600,
60 * (2 ** min(5, (int) $backend->consecutive_failures - 1))
);
if ((string) $backend->admin_state === 'active') {
$backend->admin_state = 'read_only';
}
$backend->updated_at = time();
$backend->save();
});
}
private static function find(int $backendId): CloudStorageBackend
{
$backend = CloudStorageBackend::query()->whereKey($backendId)->first();
if (!$backend instanceof CloudStorageBackend) {
throw new CloudError('对象存储后端不存在', 404);
}
return $backend;
}
/** Serialize backend-count and immutable-identity mutations. */
private static function lockCatalog($connection): void
{
$mutex = $connection->table('cloud_storage_backend_catalog_mutex')
->where('id', 1)->lockForUpdate()->first(['id']);
if ($mutex === null) {
throw new CloudError('对象存储后端目录尚未初始化', 503);
}
}
/** @return array<string,mixed> */
private static function dto(CloudStorageBackend $backend): array
{
$state = (string) $backend->admin_state;
$healthy = self::hasCurrentHealth($backend);
$errors = [
'endpoint_unreachable' => '无法连接 Endpoint,请检查证书、DNS 和防火墙。',
'region_mismatch' => 'Bucket 区域不匹配。',
'auth_or_permission_denied' => '凭据或 Bucket 权限验证失败。',
'bucket_not_found' => 'Bucket 不存在或不可访问。',
'rate_limited' => '对象存储暂时限制请求。',
'service_unavailable' => '对象存储服务暂时不可用。',
'request_rejected' => '对象存储拒绝兼容性检查。',
];
$lastError = (string) $backend->last_error_code;
return [
'id' => (int) $backend->id,
'backend_key' => (string) $backend->backend_key,
'name' => (string) $backend->name,
'driver' => 's3',
'endpoint' => (string) $backend->endpoint,
'region' => (string) $backend->region,
'bucket' => (string) $backend->bucket,
'prefix' => (string) $backend->prefix,
'path_style' => (bool) $backend->path_style,
'failure_domain' => (string) $backend->failure_domain,
'write_priority' => (int) $backend->write_priority,
'admin_state' => $state,
'health_state' => (string) $backend->health_state,
'ready' => $healthy,
'configured' => true,
'credentials_configured' => trim((string) $backend->sealed_credentials) !== '',
'revision' => (int) $backend->config_revision,
'tested_revision' => (int) $backend->tested_revision,
'last_error_code' => $lastError,
'last_error' => $errors[$lastError] ?? '',
'last_tested_at' => (int) $backend->last_tested_at,
'last_tested_at_text' => (int) $backend->last_tested_at > 0
? date('Y-m-d H:i:s', (int) $backend->last_tested_at) : '',
'can_edit' => $state !== 'retired',
'can_test' => $state !== 'retired',
'can_activate' => in_array($state, ['draft', 'disabled', 'read_only'], true)
&& $healthy,
'can_drain' => in_array($state, ['active', 'read_only'], true),
'can_resume' => $state === 'draining' && $healthy,
'can_disable' => $state !== 'retired' && $state !== 'disabled',
];
}
private static function isWritable(CloudStorageBackend $backend): bool
{
return (string) $backend->admin_state === 'active'
&& self::hasCurrentHealth($backend);
}
private static function hasCurrentHealth(CloudStorageBackend $backend): bool
{
return (int) $backend->config_revision > 0
&& (int) $backend->tested_revision === (int) $backend->config_revision
&& (string) $backend->health_state === 'healthy';
}
/** @return array{config:array<string,mixed>,credentials:array{access_key_id:string,secret_access_key:string},revision:int,backend_id:int} */
private static function runtimeFromBackend(CloudStorageBackend $backend): array
{
$credentials = CloudSecrets::decrypt(
(string) $backend->sealed_credentials,
self::CREDENTIAL_PURPOSE
);
$access = $credentials['access_key_id'] ?? null;
$secret = $credentials['secret_access_key'] ?? null;
if (!is_string($access) || !is_string($secret)) {
throw new CloudError('对象存储访问凭据内容无效', 503);
}
self::assertCredentials($access, $secret);
return [
'config' => [
'endpoint' => (string) $backend->endpoint,
'region' => (string) $backend->region,
'bucket' => (string) $backend->bucket,
'prefix' => (string) $backend->prefix,
'path_style' => (bool) $backend->path_style,
],
'credentials' => [
'access_key_id' => $access,
'secret_access_key' => $secret,
],
'revision' => (int) $backend->config_revision,
'backend_id' => (int) $backend->id,
];
}
/** @return array<string,mixed> */
private static function validatedSpec(
array $input,
bool $requireCredentials,
?CloudStorageBackend $current = null
): array {
CloudInput::only($input, [
'name', 'endpoint', 'region', 'bucket', 'prefix', 'path_style',
'failure_domain', 'write_priority', 'access_key_id',
'secret_access_key',
]);
$name = self::name($input['name'] ?? ($current?->name ?? ''));
$endpoint = self::endpoint($input['endpoint'] ?? ($current?->endpoint ?? ''));
$region = self::region($input['region'] ?? ($current?->region ?? ''));
$bucket = self::bucket($input['bucket'] ?? ($current?->bucket ?? ''));
$prefix = self::objectPrefix($input['prefix'] ?? ($current?->prefix ?? ''));
$pathStyle = array_key_exists('path_style', $input)
? self::boolean($input['path_style'], '请选择 S3 寻址方式')
: (bool) ($current?->path_style ?? false);
if (!$pathStyle && self::endpointHostIsIp($endpoint)) {
throw new CloudError('IP 地址 Endpoint 只能使用路径寻址');
}
$failureDomain = self::failureDomain(
$input['failure_domain'] ?? ($current?->failure_domain ?? '')
);
$writePriority = self::writePriority(
$input['write_priority'] ?? ($current?->write_priority ?? 100)
);
$access = is_string($input['access_key_id'] ?? null)
? trim((string) $input['access_key_id']) : '';
$secret = is_string($input['secret_access_key'] ?? null)
? (string) $input['secret_access_key'] : '';
if (($access === '') !== ($secret === '')) {
throw new CloudError('Access Key ID 和 Secret Access Key 必须同时填写');
}
if ($access !== '') {
self::assertCredentials($access, $secret);
$sealed = CloudSecrets::encrypt([
'access_key_id' => $access,
'secret_access_key' => $secret,
], self::CREDENTIAL_PURPOSE);
} elseif ($current instanceof CloudStorageBackend) {
$sealed = (string) $current->sealed_credentials;
self::runtimeFromBackend($current);
} elseif ($requireCredentials) {
throw new CloudError('首次保存对象存储必须填写 Access Key 和 Secret Key');
} else {
throw new CloudError('对象存储访问凭据尚未配置', 503);
}
return [
'name' => $name,
'endpoint' => $endpoint,
'region' => $region,
'bucket' => $bucket,
'prefix' => $prefix,
'path_style' => $pathStyle,
'failure_domain' => $failureDomain,
'write_priority' => $writePriority,
'sealed_credentials' => $sealed,
'identity_sha256' => self::identityHash(
$endpoint,
$bucket,
$prefix,
$pathStyle
),
];
}
/** @param array<string,mixed> $spec */
private static function applySpec(CloudStorageBackend $backend, array $spec): void
{
$backend->identity_sha256 = $spec['identity_sha256'];
$backend->name = $spec['name'];
$backend->driver = 's3';
$backend->endpoint = $spec['endpoint'];
$backend->region = $spec['region'];
$backend->bucket = $spec['bucket'];
$backend->prefix = $spec['prefix'];
$backend->path_style = $spec['path_style'] ? 1 : 0;
$backend->failure_domain = $spec['failure_domain'];
$backend->sealed_credentials = $spec['sealed_credentials'];
$backend->write_priority = $spec['write_priority'];
}
/** @param array<string,mixed> $spec */
private static function runtimeChanged(CloudStorageBackend $backend, array $spec): bool
{
return (string) $backend->endpoint !== $spec['endpoint']
|| (string) $backend->region !== $spec['region']
|| (string) $backend->bucket !== $spec['bucket']
|| (string) $backend->prefix !== $spec['prefix']
|| (bool) $backend->path_style !== $spec['path_style']
|| !hash_equals((string) $backend->sealed_credentials,
(string) $spec['sealed_credentials']);
}
private static function identityHash(
string $endpoint,
string $bucket,
string $prefix,
bool $pathStyle
): string {
return hash('sha256', json_encode([
'driver' => 's3',
'endpoint' => $endpoint,
'bucket' => $bucket,
'prefix' => $prefix,
'path_style' => $pathStyle,
], JSON_THROW_ON_ERROR | JSON_UNESCAPED_SLASHES));
}
private static function assertExpectedRevision(
CloudStorageBackend $backend,
int $expected,
string $message = '对象存储配置已被修改,请刷新页面后重试'
): void {
if ((int) $backend->config_revision !== $expected) {
throw new CloudError($message, 409);
}
}
private static function assertActor(int $actorUserId): void
{
if ($actorUserId < 1) {
throw new CloudError('管理员身份无效', 403);
}
}
private static function assertId(int $backendId): void
{
if ($backendId < 1) {
throw new CloudError('对象存储后端不存在', 404);
}
}
private static function assertRevision(int $revision): void
{
if ($revision < 1) {
throw new CloudError('对象存储配置版本无效,请刷新页面后重试', 409);
}
}
private static function name($value): string
{
if (!is_string($value)) {
throw new CloudError('对象存储名称格式无效');
}
$value = trim($value);
if ($value === '' || mb_strlen($value, 'UTF-8') > 80
|| preg_match('//u', $value) !== 1
|| preg_match('/[\x00-\x1F\x7F]/u', $value) === 1) {
throw new CloudError('对象存储名称需为 1 至 80 个字符且不能包含控制字符');
}
return $value;
}
private static function endpoint($value): string
{
if (!is_string($value)) {
throw new CloudError('Endpoint 格式无效');
}
$parts = parse_url(trim($value));
if (!is_array($parts)
|| strtolower((string) ($parts['scheme'] ?? '')) !== 'https'
|| !isset($parts['host']) || isset($parts['user'])
|| isset($parts['pass']) || isset($parts['query'])
|| isset($parts['fragment'])
|| !in_array((string) ($parts['path'] ?? ''), ['', '/'], true)) {
throw new CloudError('Endpoint 必须是仅包含主机和可选端口的 HTTPS 地址');
}
$host = strtolower(trim((string) $parts['host'], '[]'));
if ($host === '' || $host === 'localhost' || str_ends_with($host, '.localhost')) {
throw new CloudError('Endpoint 主机无效');
}
if (filter_var($host, FILTER_VALIDATE_IP)) {
if (self::blockedEndpointIp($host)) {
throw new CloudError('Endpoint 不能使用回环、链路本地、未指定或组播地址');
}
} else {
if (preg_match('/^[0-9.]+$/D', $host) === 1
|| strlen($host) > 253 || str_ends_with($host, '.')) {
throw new CloudError('Endpoint 主机名无效');
}
foreach (explode('.', $host) as $label) {
if (preg_match('/^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/D', $label) !== 1) {
throw new CloudError('Endpoint 主机名无效');
}
}
}
$port = isset($parts['port']) ? (int) $parts['port'] : 443;
if ($port < 1 || $port > 65535) {
throw new CloudError('Endpoint 端口必须为 1 至 65535');
}
$authority = str_contains($host, ':') ? '[' . $host . ']' : $host;
if ($port !== 443) {
$authority .= ':' . $port;
}
return 'https://' . $authority;
}
private static function endpointHostIsIp(string $endpoint): bool
{
$host = parse_url($endpoint, PHP_URL_HOST);
return is_string($host)
&& filter_var(trim($host, '[]'), FILTER_VALIDATE_IP) !== false;
}
private static function blockedEndpointIp(string $host): bool
{
$packed = inet_pton($host);
if ($packed === false) {
return true;
}
if (strlen($packed) === 4) {
$octets = array_values(unpack('C4', $packed));
return $octets[0] === 0 || $octets[0] === 127
|| ($octets[0] === 169 && $octets[1] === 254)
|| $octets[0] >= 224;
}
$bytes = array_values(unpack('C16', $packed));
return $host === '::' || $host === '::1' || $bytes[0] === 0xff
|| ($bytes[0] === 0xfe && ($bytes[1] & 0xc0) === 0x80);
}
private static function region($value): string
{
if (!is_string($value)) {
throw new CloudError('Region 格式无效');
}
$value = strtolower(trim($value));
if (preg_match('/^[a-z0-9][a-z0-9-]{0,62}$/D', $value) !== 1) {
throw new CloudError('Region 只能包含小写字母、数字和连字符,最多 63 位');
}
return $value;
}
private static function bucket($value): string
{
if (!is_string($value)) {
throw new CloudError('Bucket 名称格式无效');
}
$value = strtolower(trim($value));
if (strlen($value) < 3 || strlen($value) > 63
|| preg_match('/^[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?$/D', $value) !== 1
|| str_contains($value, '..') || str_contains($value, '.-')
|| str_contains($value, '-.') || filter_var($value, FILTER_VALIDATE_IP)) {
throw new CloudError('Bucket 名称需符合 S3 DNS 命名规则(3 至 63 位)');
}
return $value;
}
private static function objectPrefix($value): string
{
if (!is_string($value)) {
throw new CloudError('对象前缀格式无效');
}
$value = trim($value, " \t\n\r\0\x0B/");
if ($value === '') {
return '';
}
if (strlen($value) > 255
|| preg_match('/^[A-Za-z0-9][A-Za-z0-9._\/-]*$/D', $value) !== 1
|| str_contains($value, '//')) {
throw new CloudError('对象前缀只能包含英文、数字、点、下划线、连字符和斜线,最多 255 位');
}
foreach (explode('/', $value) as $segment) {
if ($segment === '.' || $segment === '..') {
throw new CloudError('对象前缀不能包含点路径段');
}
}
return $value;
}
private static function failureDomain($value): string
{
if (!is_string($value)) {
throw new CloudError('故障域格式无效');
}
$value = strtolower(trim($value));
if ($value === ''
|| preg_match('/^[a-z0-9][a-z0-9_.:-]{0,79}$/D', $value) !== 1) {
throw new CloudError('故障域必须填写,且只能包含英文、数字、点、冒号、下划线和连字符,最多 80 位');
}
return $value;
}
private static function writePriority($value): int
{
if (is_int($value)) {
$priority = $value;
} elseif (is_string($value)
&& preg_match('/^(?:0|[1-9][0-9]{0,5})$/D', $value) === 1) {
$priority = (int) $value;
} else {
throw new CloudError('写入优先级格式无效');
}
if ($priority < 0 || $priority > 100000) {
throw new CloudError('写入优先级需为 0 至 100000');
}
return $priority;
}
private static function assertCredentials(string $access, string $secret): void
{
if (preg_match('/^[A-Za-z0-9][A-Za-z0-9._-]{2,127}$/D', $access) !== 1) {
throw new CloudError('Access Key ID 需为 3 至 128 位英文、数字、点、下划线或连字符');
}
if (strlen($secret) < 8 || strlen($secret) > 256
|| trim($secret) !== $secret
|| preg_match('/[\x00-\x1F\x7F]/', $secret) === 1) {
throw new CloudError('Secret Access Key 需为 8 至 256 位且不能包含首尾空格或控制字符');
}
}
private static function boolean($value, string $message): bool
{
$parsed = filter_var($value, FILTER_VALIDATE_BOOLEAN, FILTER_NULL_ON_FAILURE);
if ($parsed === null) {
throw new CloudError($message);
}
return $parsed;
}
}