Файловый менеджер - Редактировать - /var/www/html/libs.zip
Ðазад
PK ! >���� � telemetry/README.mdnu �Iw�� The `telemetry` library implements a minimal OpenTelemetry tracing client that is compatible with the OTEL data model but not compliant with the OTEL client specification. This was developed to avoid taking a dependency on the official OpenTelemetry PHP client, which was deemed too complex to integrate with MediaWiki ([T340552](https://phabricator.wikimedia.org/T340552)). `telemetry` requires a PSR-3 logger, a PSR-18 HTTP client and a PSR-17 HTTP factory. PK ! ���3� � telemetry/Tracer.phpnu �Iw�� <?php namespace Wikimedia\Telemetry; use Wikimedia\Assert\Assert; /** * @since 1.43 * @internal */ class Tracer implements TracerInterface { /** * The length of a trace ID in bytes, as specified by the OTEL specification. */ private const TRACE_ID_BYTES_LENGTH = 16; /** * The length of a span ID in bytes, as specified by the OTEL specification. */ private const SPAN_ID_BYTES_LENGTH = 8; private Clock $clock; private SamplerInterface $sampler; private ExporterInterface $exporter; private TracerState $tracerState; /** * Whether tracing has been explicitly ended by calling shutdown() on this instance. * @var bool */ private bool $wasShutdown = false; public function __construct( Clock $clock, SamplerInterface $sampler, ExporterInterface $exporter, TracerState $tracerState ) { $this->clock = $clock; $this->sampler = $sampler; $this->exporter = $exporter; $this->tracerState = $tracerState; } /** @inheritDoc */ public function createSpan( string $spanName ): SpanInterface { $activeSpanContext = $this->tracerState->getActiveSpanContext(); // Gracefully handle attempts to instrument code after shutdown() was called. if ( !$this->wasShutdown ) { Assert::precondition( $activeSpanContext !== null, 'Attempted to create a span with the currently active span as the implicit parent, ' . 'but no span was active. Use createRootSpan() to create a span with no parent (i.e. a root span).' ); } return $this->newSpan( $spanName, $activeSpanContext ); } /** @inheritDoc */ public function createRootSpan( string $spanName ): SpanInterface { return $this->newSpan( $spanName, null ); } /** @inheritDoc */ public function createSpanWithParent( string $spanName, SpanContext $parentSpanContext ): SpanInterface { return $this->newSpan( $spanName, $parentSpanContext ); } private function newSpan( string $spanName, ?SpanContext $parentSpanContext ): SpanInterface { $traceId = $parentSpanContext !== null ? $parentSpanContext->getTraceId() : $this->generateId( self::TRACE_ID_BYTES_LENGTH ); $spanId = $this->generateId( self::SPAN_ID_BYTES_LENGTH ); $sampled = $this->sampler->shouldSample( $parentSpanContext ); $spanContext = new SpanContext( $traceId, $spanId, $parentSpanContext !== null ? $parentSpanContext->getSpanId() : null, $spanName, $sampled ); if ( $this->wasShutdown || !$sampled ) { return new NoopSpan( $spanContext ); } return new Span( $this->clock, $this->tracerState, $spanContext ); } /** @inheritDoc */ public function shutdown(): void { $this->wasShutdown = true; $this->exporter->export( $this->tracerState ); } /** * Generate a valid hexadecimal string for use as a trace or span ID, with the given length in bytes. * * @param int $bytesLength The byte length of the ID * @return string The ID as a hexadecimal string */ private function generateId( int $bytesLength ): string { return bin2hex( random_bytes( $bytesLength ) ); } } PK ! �;j j telemetry/SpanContext.phpnu �Iw�� <?php namespace Wikimedia\Telemetry; use JsonSerializable; /** * Data transfer object holding data associated with a given span. * * @since 1.43 */ class SpanContext implements JsonSerializable { /** * The ID of the trace this span is part of, as a hexadecimal string. * @var string */ private string $traceId; /** * The ID of this span, as a hexadecimal string. * @var string */ private string $spanId; /** * The ID of this span, as a hexadecimal string, or `null` if this is a root span. * @var string|null */ private ?string $parentSpanId; /** * A concise description of the work represented by this span. * @see TracerInterface::createSpan() * @var string */ private string $name; /** * Whether the active sampler decided to sample and record this span. * @var bool */ private bool $sampled; /** * Key-value metadata associated with this span. * @see Span::setAttributes() * @var array */ private array $attributes = []; /** * Describes the relationship of this span to other spans within the same trace. * @see Span::setSpanKind() * @var int */ private int $spanKind = SpanInterface::SPAN_KIND_INTERNAL; /** * UNIX epoch timestamp in nanoseconds at which this span was started, * or `null` if this span was not started yet. * @var int|null */ private ?int $startEpochNanos = null; /** * UNIX epoch timestamp in nanoseconds at which this span was ended, * or `null` if this span was not ended yet. * @var int|null */ private ?int $endEpochNanos = null; public function __construct( string $traceId, string $spanId, ?string $parentSpanId, string $name, bool $sampled ) { $this->traceId = $traceId; $this->spanId = $spanId; $this->parentSpanId = $parentSpanId; $this->name = $name; $this->sampled = $sampled; } public function setEndEpochNanos( int $endEpochNanos ): void { $this->endEpochNanos = $endEpochNanos; } public function setStartEpochNanos( int $startEpochNanos ): void { $this->startEpochNanos = $startEpochNanos; } public function setSpanKind( int $spanKind ): void { $this->spanKind = $spanKind; } public function setAttributes( array $attributes ): void { $this->attributes = $attributes; } public function isSampled(): bool { return $this->sampled; } public function getSpanId(): string { return $this->spanId; } public function getTraceId(): string { return $this->traceId; } public function getParentSpanId(): ?string { return $this->parentSpanId; } public function wasStarted(): bool { return $this->startEpochNanos !== null; } public function wasEnded(): bool { return $this->endEpochNanos !== null; } public function jsonSerialize(): array { $json = [ 'traceId' => $this->traceId, 'parentSpanId' => $this->parentSpanId, 'spanId' => $this->spanId, 'name' => $this->name, 'startTimeUnixNano' => $this->startEpochNanos, 'endTimeUnixNano' => $this->endEpochNanos, 'kind' => $this->spanKind ]; if ( $this->attributes ) { $json['attributes'] = OtlpSerializer::serializeKeyValuePairs( $this->attributes ); } return $json; } /** * Check whether the given SpanContext belongs to the same span. * * @param SpanContext|null $other * @return bool */ public function equals( ?SpanContext $other ): bool { if ( $other === null ) { return false; } return $other->spanId === $this->spanId; } } PK ! �#(|K K telemetry/TracerState.phpnu �Iw�� <?php namespace Wikimedia\Telemetry; use Wikimedia\Assert\Assert; /** * Holds shared telemetry state, such as finished span data buffered for export. * * Since this data is tied to the lifetime of a given web request or process, this class is a singleton to * avoid discarding data in the case of MediaWiki service container resets. * * @since 1.43 * @internal */ class TracerState { /** * Shared tracer state for the current process or web request, `null` if uninitialized. * @var TracerState|null */ private static ?TracerState $instance = null; /** * List of already finished spans to be exported. * @var SpanContext[] */ private array $finishedSpanContexts = []; /** * Stack holding contexts for activated spans. * @var SpanContext[] */ private array $activeSpanContextStack = []; /** * Get or initialize the shared tracer state for the current process or web request. * @return TracerState */ public static function getInstance(): TracerState { self::$instance ??= new self(); return self::$instance; } /** * Reset shared tracer state. Useful for testing. * @return void */ public static function destroyInstance(): void { Assert::precondition( defined( 'MW_PHPUNIT_TEST' ), 'This function can only be called in tests' ); self::$instance = null; } /** * Add the given span to the list of finished spans. * @param SpanContext $context * @return void */ public function addSpanContext( SpanContext $context ): void { $this->finishedSpanContexts[] = $context; } /** * Get the list of finished spans. * @return SpanContext[] */ public function getSpanContexts(): array { return $this->finishedSpanContexts; } /** * Clear the list of finished spans. */ public function clearSpanContexts(): void { $this->finishedSpanContexts = []; } /** * Make the given span the active span. * @param SpanContext $spanContext Context of the span to activate * @return void */ public function activateSpan( SpanContext $spanContext ): void { $this->activeSpanContextStack[] = $spanContext; } /** * Deactivate the given span, if it was the active span. * @param SpanContext $spanContext Context of the span to deactivate * @return void */ public function deactivateSpan( SpanContext $spanContext ): void { $activeSpanContext = $this->getActiveSpanContext(); Assert::invariant( $activeSpanContext !== null && $activeSpanContext->getSpanId() === $spanContext->getSpanId(), 'Attempted to deactivate a span which is not the active span.' ); array_pop( $this->activeSpanContextStack ); } /** * Get the context of the currently active span, or `null` if no span is active. * @return SpanContext|null */ public function getActiveSpanContext(): ?SpanContext { return $this->activeSpanContextStack[count( $this->activeSpanContextStack ) - 1] ?? null; } } PK ! ��H telemetry/TracerInterface.phpnu �Iw�� <?php namespace Wikimedia\Telemetry; use Wikimedia\Assert\PreconditionException; /** * Base interface for an OpenTelemetry tracer responsible for creating spans. * @since 1.43 */ interface TracerInterface { /** * Create a span with the given name and the currently active span as the implicit parent. * This requires a span to be already active and will throw an error otherwise. * * @param string $spanName The descriptive name of this span. * Refer to the <a href="https://opentelemetry.io/docs/specs/otel/trace/api/#span">OTEL Tracing API * spec</a> for recommended naming conventions. * @return SpanInterface * @throws PreconditionException If no span was active */ public function createSpan( string $spanName ): SpanInterface; /** * Create a new root span, i.e. a span with no parent that forms the basis for a new trace. * * @param string $spanName The descriptive name of this span. * Refer to the <a href="https://opentelemetry.io/docs/specs/otel/trace/api/#span">OTEL Tracing API * spec</a> for recommended naming conventions. * @return SpanInterface */ public function createRootSpan( string $spanName ): SpanInterface; /** * Create a span with the given name and parent. * * @param string $spanName The descriptive name of this span. * Refer to the <a href="https://opentelemetry.io/docs/specs/otel/trace/api/#span">OTEL Tracing API * spec</a> for recommended naming conventions. * @param SpanContext $parentSpanContext Context of the parent span this span should be associated with. * @return SpanInterface */ public function createSpanWithParent( string $spanName, SpanContext $parentSpanContext ): SpanInterface; /** * Shut down this tracer and export collected trace data. * @return void */ public function shutdown(): void; } PK ! (��A� � telemetry/NoopSpan.phpnu �Iw�� <?php namespace Wikimedia\Telemetry; /** * An unsampled span that does nothing and persists no data. * * @since 1.43 * @internal */ class NoopSpan implements SpanInterface { private SpanContext $context; public function __construct( SpanContext $context ) { $this->context = $context; } /** @inheritDoc */ public function getContext(): SpanContext { return $this->context; } /** @inheritDoc */ public function setAttributes( array $attributes ): SpanInterface { return $this; } /** @inheritDoc */ public function setSpanKind( int $spanKind ): SpanInterface { return $this; } /** @inheritDoc */ public function start( ?int $epochNanos = null ): SpanInterface { return $this; } /** @inheritDoc */ public function end( ?int $epochNanos = null ): void { // no-op } /** @inheritDoc */ public function activate(): void { // no-op } /** @inheritDoc */ public function deactivate(): void { // no-op } } PK ! J���1 1 telemetry/ExporterInterface.phpnu �Iw�� <?php namespace Wikimedia\Telemetry; /** * Base interface for OTEL trace data exporters. * @since 1.43 * @internal */ interface ExporterInterface { /** * Export all trace data. * @param TracerState $tracerState * @return void */ public function export( TracerState $tracerState ): void; } PK ! X�M�� � telemetry/OtlpHttpExporter.phpnu �Iw�� <?php namespace Wikimedia\Telemetry; use GuzzleHttp\Psr7\Utils; use Psr\Http\Client\ClientExceptionInterface; use Psr\Http\Client\ClientInterface; use Psr\Http\Message\RequestFactoryInterface; use Psr\Log\LoggerInterface; /** * An {@link ExporterInterface} that exports collected data over HTTP, serialized in OTLP JSON format. * * @since 1.43 * @internal */ class OtlpHttpExporter implements ExporterInterface { private ClientInterface $client; private RequestFactoryInterface $requestFactory; private LoggerInterface $logger; /** * URI of the OTLP receiver endpoint to send data to. * @var string */ private string $endpoint; /** * Descriptive name used to identify this service in traces. * @var string */ private string $serviceName; /** * The host name of this server to be reported in traces. * @var string */ private string $hostName; public function __construct( ClientInterface $client, RequestFactoryInterface $requestFactory, LoggerInterface $logger, string $uri, string $serviceName, string $hostName ) { $this->client = $client; $this->requestFactory = $requestFactory; $this->logger = $logger; $this->endpoint = $uri; $this->serviceName = $serviceName; $this->hostName = $hostName; } /** @inheritDoc */ public function export( TracerState $tracerState ): void { $spanContexts = $tracerState->getSpanContexts(); if ( count( $spanContexts ) === 0 ) { return; } $resourceInfo = array_filter( [ 'service.name' => $this->serviceName, 'host.name' => $this->hostName, "server.socket.address" => $_SERVER['SERVER_ADDR'] ?? null, ] ); $data = [ 'resourceSpans' => [ [ 'resource' => [ 'attributes' => OtlpSerializer::serializeKeyValuePairs( $resourceInfo ) ], 'scopeSpans' => [ [ 'scope' => [ 'name' => 'org.wikimedia.telemetry', ], 'spans' => $spanContexts ] ] ] ] ]; $request = $this->requestFactory->createRequest( 'POST', $this->endpoint ) ->withHeader( 'Content-Type', 'application/json' ) ->withBody( Utils::streamFor( json_encode( $data ) ) ); try { $response = $this->client->sendRequest( $request ); if ( $response->getStatusCode() !== 200 ) { $this->logger->error( 'Failed to export trace data' ); } } catch ( ClientExceptionInterface $e ) { $this->logger->error( 'Failed to connect to exporter', [ 'exception' => $e ] ); } // Clear out finished spans after exporting them. $tracerState->clearSpanContexts(); } } PK ! �.��� � telemetry/OtlpSerializer.phpnu �Iw�� <?php namespace Wikimedia\Telemetry; /** * Utility class for serializing data in OTLP JSON format. * * @since 1.43 * @internal */ class OtlpSerializer { /** * Map of PHP types to their corresponding type name used in the OTLP JSON format. */ private const TYPE_MAP = [ 'string' => 'stringValue', 'integer' => 'intValue', 'boolean' => 'boolValue', 'double' => 'doubleValue', 'array' => 'arrayValue' ]; /** * Serialize an associative array into the format expected by the OTLP JSON format. * @param array $keyValuePairs The associative array to serialize * @return array */ public static function serializeKeyValuePairs( array $keyValuePairs ): array { $serialized = []; foreach ( $keyValuePairs as $key => $value ) { $type = gettype( $value ); if ( isset( self::TYPE_MAP[$type] ) ) { $serialized[] = [ 'key' => $key, 'value' => [ self::TYPE_MAP[$type] => $value ] ]; } } return $serialized; } } PK ! ��*� telemetry/SamplerInterface.phpnu �Iw�� <?php namespace Wikimedia\Telemetry; /** * Interface for OTEL span samplers. * @since 1.43 */ interface SamplerInterface { /** * Determine whether a newly created span should be sampled based on its parent span data. * * @param SpanContext|null $parentSpanContext Context of he parent span of the newly created span, * or `null` if the newly created span is a root span. * @return bool Whether the newly created span should be sampled. */ public function shouldSample( ?SpanContext $parentSpanContext ): bool; } PK ! ���� � telemetry/Clock.phpnu �Iw�� <?php namespace Wikimedia\Telemetry; use Wikimedia\Assert\Assert; /** * A click providing the current time in nanoseconds, backed by {@link hrtime}. * * @since 1.43 * @internal */ class Clock { /** * Timestamp to return in place of the current time, or `null` to use the current time. * @var int|null */ private static ?int $mockTime = null; /** * The reference UNIX timestamp in nanoseconds which hrtime() offsets should be added to * to derive an absolute timestamp. * @var int|null */ private ?int $referenceTime = null; public function __construct() { Assert::precondition( PHP_INT_SIZE >= 8, 'The Clock class requires 64-bit integers to support nanosecond timing' ); } /** * Get the current time, represented as the number of nanoseconds since the UNIX epoch. * @return int */ public function getCurrentNanoTime(): int { $this->referenceTime ??= (int)( 1e9 * microtime( true ) ) - hrtime( true ); return self::$mockTime ?? ( $this->referenceTime + hrtime( true ) ); } /** * Set a mock time to override the timestamp returned by {@link Clock::getCurrentNanoTime()}. * Useful for testing. * * @param int|null $epochNanos The override timestamp, or `null` to return to using the current time. * @return void */ public static function setMockTime( ?int $epochNanos ): void { Assert::precondition( defined( 'MW_PHPUNIT_TEST' ), 'This method should only be used in tests' ); self::$mockTime = $epochNanos; } } PK ! �d_27 7 telemetry/SpanInterface.phpnu �Iw�� <?php namespace Wikimedia\Telemetry; /** * Represents an OpenTelemetry span, i.e. a single operation within a trace. * * @since 1.43 * @see https://opentelemetry.io/docs/specs/otel/trace/api/#span */ interface SpanInterface { /** * Default value. Indicates that the span represents an internal operation within an application, * as opposed to an operations with remote parents or children. */ public const SPAN_KIND_INTERNAL = 1; /** * Indicates that the span covers server-side handling of a synchronous RPC or other remote request. */ public const SPAN_KIND_SERVER = 2; /** * Indicates that the span describes a request to some remote service. */ public const SPAN_KIND_CLIENT = 3; /** * Indicates that the span describes the initiators of an asynchronous request. */ public const SPAN_KIND_PRODUCER = 4; /** * Indicates that the span describes a child of an asynchronous * {@link SpanInterface::SPAN_KIND_PRODUCER} request. */ public const SPAN_KIND_CONSUMER = 5; /** * Get the context holding data for this span. * @return SpanContext */ public function getContext(): SpanContext; /** * Set attributes (arbitrary metadata) for this span. * * When deciding on the set of attributes to register as well as their naming, consider following * <a href="https://opentelemetry.io/docs/specs/semconv/general/trace/">Semantic Conventions</a> where * applicable. * * @param array $attributes key-value mapping of attribute names to values * @return SpanInterface fluent interface */ public function setAttributes( array $attributes ): SpanInterface; /** * Set the kind of this span, which describes how it relates to its parent and children * within the overarching trace. * * @param int $spanKind One of the SpanInterface::SPAN_KIND_** constants * @see https://opentelemetry.io/docs/specs/otel/trace/api/#spankind * @return SpanInterface fluent interface */ public function setSpanKind( int $spanKind ): SpanInterface; /** * Start this span, optionally specifying an override for its start time. * @param int|null $epochNanos The start time to use, or `null` to use the current time. * @return SpanInterface */ public function start( ?int $epochNanos = null ): SpanInterface; /** * End this span, optionally specifying an override for its end time. * @param int|null $epochNanos The end time to use, or `null` to use the current time. * @return void */ public function end( ?int $epochNanos = null ): void; /** * Make this span the active span. * * This will cause any spans started without specifying an explicit parent to automatically * become children of this span as long as it remains active. * * @return void */ public function activate(): void; /** * Deactivate this span. * @return void */ public function deactivate(): void; } PK ! q3nJ� � telemetry/Span.phpnu �Iw�� <?php namespace Wikimedia\Telemetry; use Wikimedia\Assert\Assert; /** * Represents an OpenTelemetry span, i.e. a single operation within a trace. * * @since 1.43 * @see https://opentelemetry.io/docs/specs/otel/trace/api/#span */ class Span implements SpanInterface { private Clock $clock; private TracerState $tracerState; private SpanContext $context; public function __construct( Clock $clock, TracerState $tracerState, SpanContext $context ) { $this->clock = $clock; $this->tracerState = $tracerState; $this->context = $context; } public function __destruct() { $this->end(); $activeSpanContext = $this->tracerState->getActiveSpanContext(); if ( $this->context->equals( $activeSpanContext ) ) { $this->deactivate(); } } /** @inheritDoc */ public function getContext(): SpanContext { return $this->context; } /** @inheritDoc */ public function setAttributes( array $attributes ): SpanInterface { $this->context->setAttributes( $attributes ); return $this; } /** @inheritDoc */ public function setSpanKind( int $spanKind ): SpanInterface { $this->context->setSpanKind( $spanKind ); return $this; } /** @inheritDoc */ public function start( ?int $epochNanos = null ): SpanInterface { Assert::precondition( !$this->context->wasStarted(), 'Cannot start a span more than once' ); $this->context->setStartEpochNanos( $epochNanos ?? $this->clock->getCurrentNanoTime() ); return $this; } /** @inheritDoc */ public function end( ?int $epochNanos = null ): void { Assert::precondition( $this->context->wasStarted(), 'Cannot end a span that has not been started' ); // Make duplicate end() calls a no-op, since it may occur legitimately, // e.g. when a span wrapped in an RAII ScopedSpan wrapper is ended explicitly. if ( !$this->context->wasEnded() ) { $this->context->setEndEpochNanos( $epochNanos ?? $this->clock->getCurrentNanoTime() ); $this->tracerState->addSpanContext( $this->context ); } } /** @inheritDoc */ public function activate(): void { $this->tracerState->activateSpan( $this->getContext() ); } /** @inheritDoc */ public function deactivate(): void { $this->tracerState->deactivateSpan( $this->getContext() ); } } PK ! ��� � � telemetry/NoopTracer.phpnu �Iw�� <?php namespace Wikimedia\Telemetry; /** * A no-op tracer that creates no-op spans and persists no data. * Useful for scenarios where tracing is disabled. * * @since 1.43 * @internal */ class NoopTracer implements TracerInterface { private SpanContext $noopSpanContext; public function __construct() { $this->noopSpanContext = new SpanContext( '', '', null, '', false ); } /** @inheritDoc */ public function createSpan( string $spanName, $parentSpan = null ): SpanInterface { return new NoopSpan( $this->noopSpanContext ); } /** @inheritDoc */ public function createRootSpan( string $spanName ): SpanInterface { return new NoopSpan( $this->noopSpanContext ); } /** @inheritDoc */ public function createSpanWithParent( string $spanName, SpanContext $parentSpanContext ): SpanInterface { return new NoopSpan( $this->noopSpanContext ); } /** @inheritDoc */ public function shutdown(): void { // no-op } } PK ! �.%y� � " telemetry/ProbabilisticSampler.phpnu �Iw�� <?php namespace Wikimedia\Telemetry; use Wikimedia\Assert\Assert; /** * A {@link SamplerInterface} implementation that samples a given percentage of root spans, * while respecting sampling decisions made by other samplers for a given trace. * * @since 1.43 * @internal */ class ProbabilisticSampler implements SamplerInterface { /** * The chance of sampling a root span, as a percentage (0-100). * @var int */ private int $percentChance; public function __construct( int $percentChance ) { Assert::parameter( $percentChance >= 0 && $percentChance <= 100, '$percentChance', 'must be between 0 and 100 inclusive' ); $this->percentChance = $percentChance; } /** @inheritDoc */ public function shouldSample( ?SpanContext $parentSpanContext ): bool { if ( $parentSpanContext !== null ) { return $parentSpanContext->isSampled(); } return mt_rand( 1, 100 ) <= $this->percentChance; } } PK ! ��� m m ReplacementArray.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace MediaWiki\Language; /** * Wrapper around strtr() that holds replacements */ class ReplacementArray { private array $data; /** * Create an object with the specified replacement array * The array should have the same form as the replacement array for strtr() * @param array $data */ public function __construct( array $data = [] ) { $this->data = $data; } /** * @return array */ public function __sleep() { return [ 'data' ]; } /** * Set the whole replacement array at once * @param array $data */ public function setArray( array $data ) { $this->data = $data; } /** * @return array */ public function getArray() { return $this->data; } /** * Set an element of the replacement array * @param string $from * @param string $to */ public function setPair( $from, $to ) { $this->data[$from] = $to; } /** * @param array $data */ public function mergeArray( $data ) { $this->data = $data + $this->data; } /** * @param ReplacementArray $other */ public function merge( ReplacementArray $other ) { $this->data = $other->data + $this->data; } /** * @param string $from */ public function removePair( $from ) { unset( $this->data[$from] ); } /** * @param array $data */ public function removeArray( $data ) { foreach ( $data as $from => $to ) { $this->removePair( $from ); } } /** * @param string $subject * @return string */ public function replace( $subject ) { return strtr( $subject, $this->data ); } } /** @deprecated class alias since 1.43 */ class_alias( ReplacementArray::class, 'ReplacementArray' ); PK ! �3� � MemoizedCallable.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file * @author Ori Livneh */ /** * APCu-backed function memoization * * This class provides memoization for pure functions. A function is pure * if its result value depends on nothing other than its input parameters * and if invoking it does not cause any side-effects. * * The first invocation of the memoized callable with a particular set of * arguments will be delegated to the underlying callable. Repeat invocations * with the same input parameters will be served from APCu. * * @par Example: * @code * $memoizedStrrev = new MemoizedCallable( 'range' ); * $memoizedStrrev->invoke( 5, 8 ); // result: array( 5, 6, 7, 8 ) * $memoizedStrrev->invokeArgs( array( 5, 8 ) ); // same * MemoizedCallable::call( 'range', array( 5, 8 ) ); // same * @endcode * * @since 1.27 */ class MemoizedCallable { /** @var callable */ private $callable; /** @var string Unique name of callable; used for cache keys. */ private $callableName; /** @var int */ private $ttl; /** * @param callable $callable Function or method to memoize. * @param int $ttl TTL in seconds. Defaults to 3600 (1hr). Capped at 86400 (24h). */ public function __construct( $callable, $ttl = 3600 ) { if ( !is_callable( $callable, false, $this->callableName ) ) { throw new InvalidArgumentException( 'Argument 1 passed to MemoizedCallable::__construct() must ' . 'be an instance of callable; ' . get_debug_type( $callable ) . ' given' ); } if ( $this->callableName === 'Closure::__invoke' ) { throw new InvalidArgumentException( 'Cannot memoize unnamed closure' ); } $this->callable = $callable; $this->ttl = min( max( $ttl, 1 ), 86400 ); } /** * Fetch the result of a previous invocation. * * @param string $key * @param bool &$success * @return bool */ protected function fetchResult( $key, &$success ) { $success = false; if ( function_exists( 'apcu_fetch' ) ) { return apcu_fetch( $key, $success ); } return false; } /** * Store the result of an invocation. * * @param string $key * @param mixed $result */ protected function storeResult( $key, $result ) { if ( function_exists( 'apcu_store' ) ) { apcu_store( $key, $result, $this->ttl ); } } /** * Invoke the memoized function or method. * * @throws InvalidArgumentException If parameters list contains non-scalar items. * @param array $args Parameters for memoized function or method. * @return mixed The memoized callable's return value. */ public function invokeArgs( array $args = [] ) { foreach ( $args as $arg ) { if ( $arg !== null && !is_scalar( $arg ) ) { throw new InvalidArgumentException( 'MemoizedCallable::invoke() called with non-scalar ' . 'argument' ); } } $hash = md5( serialize( $args ) ); $key = __CLASS__ . ':' . $this->callableName . ':' . $hash; $success = false; $result = $this->fetchResult( $key, $success ); if ( !$success ) { $result = ( $this->callable )( ...$args ); $this->storeResult( $key, $result ); } return $result; } /** * Invoke the memoized function or method. * * Like MemoizedCallable::invokeArgs(), but variadic. * * @param mixed ...$params Parameters for memoized function or method. * @return mixed The memoized callable's return value. */ public function invoke( ...$params ) { return $this->invokeArgs( $params ); } /** * Shortcut method for creating a MemoizedCallable and invoking it * with the specified arguments. * * @param callable $callable * @param array $args * @param int $ttl * @return mixed */ public static function call( $callable, array $args = [], $ttl = 3600 ) { $instance = new self( $callable, $ttl ); return $instance->invokeArgs( $args ); } } PK ! [2�C\& \& ! lockmanager/QuorumLockManager.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ /** * Base class for lock managers that use a quorum of peer servers for locks. * * The resource space can also be sharded into separate peer groups. * * See MemcLockManager and RedisLockManager. * * @stable to extend * @ingroup LockManager * @since 1.20 */ abstract class QuorumLockManager extends LockManager { /** @var array Map of bucket indexes to peer server lists */ protected $srvsByBucket = []; // (bucket index => (lsrv1, lsrv2, ...)) /** @var array Map of degraded buckets */ protected $degradedBuckets = []; // (bucket index => UNIX timestamp) final protected function doLockByType( array $pathsByType ) { $status = StatusValue::newGood(); $pathsByTypeByBucket = []; // (bucket => type => paths) // Get locks that need to be acquired (buckets => locks)... foreach ( $pathsByType as $type => $paths ) { foreach ( $paths as $path ) { if ( isset( $this->locksHeld[$path][$type] ) ) { ++$this->locksHeld[$path][$type]; } else { $bucket = $this->getBucketFromPath( $path ); $pathsByTypeByBucket[$bucket][$type][] = $path; } } } // Acquire locks in each bucket in bucket order to reduce contention. Any blocking // mutexes during the acquisition step will not involve circular waiting on buckets. ksort( $pathsByTypeByBucket ); $lockedPaths = []; // files locked in this attempt (type => paths) // Attempt to acquire these locks... foreach ( $pathsByTypeByBucket as $bucket => $bucketPathsByType ) { // Try to acquire the locks for this bucket $status->merge( $this->doLockingRequestBucket( $bucket, $bucketPathsByType ) ); if ( !$status->isOK() ) { $status->merge( $this->doUnlockByType( $lockedPaths ) ); return $status; } // Record these locks as active foreach ( $bucketPathsByType as $type => $paths ) { foreach ( $paths as $path ) { $this->locksHeld[$path][$type] = 1; // locked // Keep track of what locks were made in this attempt $lockedPaths[$type][] = $path; } } } return $status; } /** * @stable to override * * @param array $pathsByType * * @return StatusValue */ protected function doUnlockByType( array $pathsByType ) { $status = StatusValue::newGood(); $pathsByTypeByBucket = []; // (bucket => type => paths) foreach ( $pathsByType as $type => $paths ) { foreach ( $paths as $path ) { if ( !isset( $this->locksHeld[$path][$type] ) ) { $status->warning( 'lockmanager-notlocked', $path ); } else { --$this->locksHeld[$path][$type]; // Reference count the locks held and release locks when zero if ( $this->locksHeld[$path][$type] <= 0 ) { unset( $this->locksHeld[$path][$type] ); $bucket = $this->getBucketFromPath( $path ); $pathsByTypeByBucket[$bucket][$type][] = $path; } if ( $this->locksHeld[$path] === [] ) { unset( $this->locksHeld[$path] ); // no SH or EX locks left for key } } } } // Remove these specific locks if possible, or at least release // all locks once this process is currently not holding any locks. foreach ( $pathsByTypeByBucket as $bucket => $bucketPathsByType ) { $status->merge( $this->doUnlockingRequestBucket( $bucket, $bucketPathsByType ) ); } if ( $this->locksHeld === [] ) { $status->merge( $this->releaseAllLocks() ); $this->degradedBuckets = []; // safe to retry the normal quorum } return $status; } /** * Attempt to acquire locks with the peers for a bucket. * This is all or nothing; if any key is locked then this totally fails. * * @param int $bucket * @param array $pathsByType Map of LockManager::LOCK_* constants to lists of paths * @return StatusValue */ final protected function doLockingRequestBucket( $bucket, array $pathsByType ) { return $this->collectPledgeQuorum( $bucket, function ( $lockSrv ) use ( $pathsByType ) { return $this->getLocksOnServer( $lockSrv, $pathsByType ); } ); } /** * Attempt to release locks with the peers for a bucket * * @param int $bucket * @param array $pathsByType Map of LockManager::LOCK_* constants to lists of paths * @return StatusValue */ final protected function doUnlockingRequestBucket( $bucket, array $pathsByType ) { return $this->releasePledges( $bucket, function ( $lockSrv ) use ( $pathsByType ) { return $this->freeLocksOnServer( $lockSrv, $pathsByType ); } ); } /** * Attempt to acquire pledges with the peers for a bucket. * This is all or nothing; if any key is already pledged then this totally fails. * * @param int $bucket * @param callable $callback Pledge method taking a server name and yielding a StatusValue * @return StatusValue */ final protected function collectPledgeQuorum( $bucket, callable $callback ) { $status = StatusValue::newGood(); $yesVotes = 0; // locks made on trustable servers $votesLeft = count( $this->srvsByBucket[$bucket] ); // remaining peers $quorum = floor( $votesLeft / 2 + 1 ); // simple majority // Get votes for each peer, in order, until we have enough... foreach ( $this->srvsByBucket[$bucket] as $lockSrv ) { if ( !$this->isServerUp( $lockSrv ) ) { --$votesLeft; $status->warning( 'lockmanager-fail-svr-acquire', $lockSrv ); $this->degradedBuckets[$bucket] = time(); continue; // server down? } // Attempt to acquire the lock on this peer $status->merge( $callback( $lockSrv ) ); if ( !$status->isOK() ) { return $status; // vetoed; resource locked } ++$yesVotes; // success for this peer if ( $yesVotes >= $quorum ) { return $status; // lock obtained } --$votesLeft; $votesNeeded = $quorum - $yesVotes; if ( $votesNeeded > $votesLeft ) { break; // short-circuit } } // At this point, we must not have met the quorum $status->setResult( false ); return $status; } /** * Attempt to release pledges with the peers for a bucket * * @param int $bucket * @param callable $callback Pledge method taking a server name and yielding a StatusValue * @return StatusValue */ final protected function releasePledges( $bucket, callable $callback ) { $status = StatusValue::newGood(); $yesVotes = 0; // locks freed on trustable servers $votesLeft = count( $this->srvsByBucket[$bucket] ); // remaining peers $quorum = floor( $votesLeft / 2 + 1 ); // simple majority $isDegraded = isset( $this->degradedBuckets[$bucket] ); // not the normal quorum? foreach ( $this->srvsByBucket[$bucket] as $lockSrv ) { if ( !$this->isServerUp( $lockSrv ) ) { $status->warning( 'lockmanager-fail-svr-release', $lockSrv ); } else { // Attempt to release the lock on this peer $status->merge( $callback( $lockSrv ) ); ++$yesVotes; // success for this peer // Normally the first peers form the quorum, and the others are ignored. // Ignore them in this case, but not when an alternative quorum was used. if ( $yesVotes >= $quorum && !$isDegraded ) { break; // lock released } } } // Set a bad StatusValue if the quorum was not met. // Assumes the same "up" servers as during the acquire step. $status->setResult( $yesVotes >= $quorum ); return $status; } /** * Get the bucket for resource path. * This should avoid throwing any exceptions. * * @param string $path * @return int */ protected function getBucketFromPath( $path ) { $prefix = substr( sha1( $path ), 0, 2 ); // first 2 hex chars (8 bits) return (int)base_convert( $prefix, 16, 10 ) % count( $this->srvsByBucket ); } /** * Check if a lock server is up. * This should process cache results to reduce RTT. * * @param string $lockSrv * @return bool */ abstract protected function isServerUp( $lockSrv ); /** * Get a connection to a lock server and acquire locks * * @param string $lockSrv * @param array $pathsByType Map of LockManager::LOCK_* constants to lists of paths * @return StatusValue */ abstract protected function getLocksOnServer( $lockSrv, array $pathsByType ); /** * Get a connection to a lock server and release locks on $paths. * * Subclasses must effectively implement this or releaseAllLocks(). * * @param string $lockSrv * @param array $pathsByType Map of LockManager::LOCK_* constants to lists of paths * @return StatusValue */ abstract protected function freeLocksOnServer( $lockSrv, array $pathsByType ); /** * Release all locks that this session is holding. * * Subclasses must effectively implement this or freeLocksOnServer(). * * @return StatusValue */ abstract protected function releaseAllLocks(); final protected function doLock( array $paths, $type ) { // @phan-suppress-previous-line PhanPluginNeverReturnMethod throw new LogicException( __METHOD__ . ': proxy class does not need this method.' ); } final protected function doUnlock( array $paths, $type ) { // @phan-suppress-previous-line PhanPluginNeverReturnMethod throw new LogicException( __METHOD__ . ': proxy class does not need this method.' ); } } PK ! ��o� lockmanager/ScopedLock.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ /** * Self-releasing locks. * * Helper for consumers of LockManager, to create locks that automatically * release when an object is destroyed or goes out of scope. * * @ingroup LockManager * @since 1.19 */ class ScopedLock { /** @var LockManager */ protected $manager; /** @var StatusValue */ protected $status; /** @var array Map of lock types to resource paths */ protected $pathsByType; /** * @param LockManager $manager * @param array $pathsByType Map of lock types to path lists * @param StatusValue $status */ protected function __construct( LockManager $manager, array $pathsByType, StatusValue $status ) { $this->manager = $manager; $this->pathsByType = $pathsByType; $this->status = $status; } /** * Get a ScopedLock object representing a lock on resource paths. * Any locks are released once this object goes out of scope. * The StatusValue object is updated with any errors or warnings. * * @param LockManager $manager * @param array $paths List of storage paths or map of lock types to path lists * @param int|string $type LockManager::LOCK_* constant or "mixed" and $paths * can be a map of types to paths (since 1.22). Otherwise $type should be an * integer and $paths should be a list of paths. * @param StatusValue $status * @param int $timeout Timeout in seconds (0 means non-blocking) (since 1.22) * @return ScopedLock|null Returns null on failure */ public static function factory( LockManager $manager, array $paths, $type, StatusValue $status, $timeout = 0 ) { $pathsByType = is_int( $type ) ? [ $type => $paths ] : $paths; $lockStatus = $manager->lockByType( $pathsByType, $timeout ); $status->merge( $lockStatus ); if ( $lockStatus->isOK() ) { return new self( $manager, $pathsByType, $status ); } return null; } /** * Release a scoped lock and set any errors in the attached StatusValue object. * This is useful for early release of locks before function scope is destroyed. * This is the same as setting the lock object to null. * * @param ScopedLock|null &$lock * @since 1.21 */ public static function release( ?ScopedLock &$lock = null ) { $lock = null; } /** * Release the locks when this goes out of scope */ public function __destruct() { $wasOk = $this->status->isOK(); $this->status->merge( $this->manager->unlockByType( $this->pathsByType ) ); if ( $wasOk ) { // Make sure StatusValue is OK, despite any unlockFiles() fatals $this->status->setResult( true, $this->status->value ); } } } PK ! ���)S! S! lockmanager/RedisLockManager.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ use Wikimedia\ObjectCache\RedisConnectionPool; /** * Manage locks using redis servers. * * This is meant for multi-wiki systems that may share files. * All locks are non-blocking, which avoids deadlocks. * * All lock requests for a resource, identified by a hash string, will map to one * bucket. Each bucket maps to one or several peer servers, each running redis. * A majority of peers must agree for a lock to be acquired. * * This class requires Redis 2.6 as it makes use of Lua scripts for fast atomic operations. * * @ingroup LockManager * @since 1.22 */ class RedisLockManager extends QuorumLockManager { /** @var array Mapping of lock types to the type actually used */ protected $lockTypeMap = [ self::LOCK_SH => self::LOCK_SH, self::LOCK_UW => self::LOCK_SH, self::LOCK_EX => self::LOCK_EX ]; /** @var RedisConnectionPool */ protected $redisPool; /** @var array Map server names to hostname/IP and port numbers */ protected $lockServers = []; /** * Construct a new instance from configuration. * * @param array $config Parameters include: * - lockServers : Associative array of server names to "<IP>:<port>" strings. * - srvsByBucket : An array of up to 16 arrays, each containing the server names * in a bucket. Each bucket should have an odd number of servers. * If omitted, all servers will be in one bucket. (optional). * - redisConfig : Configuration for RedisConnectionPool::singleton() (optional). * @throws Exception */ public function __construct( array $config ) { parent::__construct( $config ); $this->lockServers = $config['lockServers']; if ( isset( $config['srvsByBucket'] ) ) { // Sanitize srvsByBucket config to prevent PHP errors $this->srvsByBucket = array_filter( $config['srvsByBucket'], 'is_array' ); $this->srvsByBucket = array_values( $this->srvsByBucket ); // consecutive } else { $this->srvsByBucket = [ array_keys( $this->lockServers ) ]; } $config['redisConfig']['serializer'] = 'none'; $this->redisPool = RedisConnectionPool::singleton( $config['redisConfig'] ); } protected function getLocksOnServer( $lockSrv, array $pathsByType ) { $status = StatusValue::newGood(); $pathList = array_merge( ...array_values( $pathsByType ) ); $server = $this->lockServers[$lockSrv]; $conn = $this->redisPool->getConnection( $server, $this->logger ); if ( !$conn ) { foreach ( $pathList as $path ) { $status->fatal( 'lockmanager-fail-acquirelock', $path ); } return $status; } $pathsByKey = []; // (type:hash => path) map foreach ( $pathsByType as $type => $paths ) { $typeString = ( $type == LockManager::LOCK_SH ) ? 'SH' : 'EX'; foreach ( $paths as $path ) { $pathsByKey[$this->recordKeyForPath( $path, $typeString )] = $path; } } try { static $script = /** @lang Lua */ <<<LUA local failed = {} -- Load input params (e.g. session, ttl, time of request) local rSession, rTTL, rMaxTTL, rTime = unpack(ARGV) -- Check that all the locks can be acquired for i,requestKey in ipairs(KEYS) do local _, _, rType, resourceKey = string.find(requestKey,"(%w+):(%w+)$") local keyIsFree = true local currentLocks = redis.call('hKeys',resourceKey) for i,lockKey in ipairs(currentLocks) do -- Get the type and session of this lock local _, _, type, session = string.find(lockKey,"(%w+):(%w+)") -- Check any locks that are not owned by this session if session ~= rSession then local lockExpiry = redis.call('hGet',resourceKey,lockKey) if 1*lockExpiry < 1*rTime then -- Lock is stale, so just prune it out redis.call('hDel',resourceKey,lockKey) elseif rType == 'EX' or type == 'EX' then keyIsFree = false break end end end if not keyIsFree then failed[#failed+1] = requestKey end end -- If all locks could be acquired, then do so if #failed == 0 then for i,requestKey in ipairs(KEYS) do local _, _, rType, resourceKey = string.find(requestKey,"(%w+):(%w+)$") redis.call('hSet',resourceKey,rType .. ':' .. rSession,rTime + rTTL) -- In addition to invalidation logic, be sure to garbage collect redis.call('expire',resourceKey,rMaxTTL) end end return failed LUA; $res = $conn->luaEval( $script, array_merge( array_keys( $pathsByKey ), // KEYS[0], KEYS[1],...,KEYS[N] [ $this->session, // ARGV[1] $this->lockTTL, // ARGV[2] self::MAX_LOCK_TTL, // ARGV[3] time() // ARGV[4] ] ), count( $pathsByKey ) # number of first argument(s) that are keys ); } catch ( RedisException $e ) { $res = false; $this->redisPool->handleError( $conn, $e ); } if ( $res === false ) { foreach ( $pathList as $path ) { $status->fatal( 'lockmanager-fail-acquirelock', $path ); } } elseif ( count( $res ) ) { $status->fatal( 'lockmanager-fail-conflict' ); } return $status; } protected function freeLocksOnServer( $lockSrv, array $pathsByType ) { $status = StatusValue::newGood(); $pathList = array_merge( ...array_values( $pathsByType ) ); $server = $this->lockServers[$lockSrv]; $conn = $this->redisPool->getConnection( $server, $this->logger ); if ( !$conn ) { foreach ( $pathList as $path ) { $status->fatal( 'lockmanager-fail-releaselock', $path ); } return $status; } $pathsByKey = []; // (type:hash => path) map foreach ( $pathsByType as $type => $paths ) { $typeString = ( $type == LockManager::LOCK_SH ) ? 'SH' : 'EX'; foreach ( $paths as $path ) { $pathsByKey[$this->recordKeyForPath( $path, $typeString )] = $path; } } try { static $script = /** @lang Lua */ <<<LUA local failed = {} -- Load input params (e.g. session) local rSession = unpack(ARGV) for i,requestKey in ipairs(KEYS) do local _, _, rType, resourceKey = string.find(requestKey,"(%w+):(%w+)$") local released = redis.call('hDel',resourceKey,rType .. ':' .. rSession) if released > 0 then -- Remove the whole structure if it is now empty if redis.call('hLen',resourceKey) == 0 then redis.call('del',resourceKey) end else failed[#failed+1] = requestKey end end return failed LUA; $res = $conn->luaEval( $script, array_merge( array_keys( $pathsByKey ), // KEYS[0], KEYS[1],...,KEYS[N] [ $this->session, // ARGV[1] ] ), count( $pathsByKey ) # number of first argument(s) that are keys ); } catch ( RedisException $e ) { $res = false; $this->redisPool->handleError( $conn, $e ); } if ( $res === false ) { foreach ( $pathList as $path ) { $status->fatal( 'lockmanager-fail-releaselock', $path ); } } else { foreach ( $res as $key ) { $status->fatal( 'lockmanager-fail-releaselock', $pathsByKey[$key] ); } } return $status; } protected function releaseAllLocks() { return StatusValue::newGood(); // not supported } protected function isServerUp( $lockSrv ) { $conn = $this->redisPool->getConnection( $this->lockServers[$lockSrv], $this->logger ); return (bool)$conn; } /** * @param string $path * @param string $type One of (EX,SH) * @return string */ protected function recordKeyForPath( $path, $type ) { return implode( ':', [ __CLASS__, 'locks', "$type:" . $this->sha1Base36Absolute( $path ) ] ); } /** * Make sure remaining locks get cleared */ public function __destruct() { $pathsByType = []; foreach ( $this->locksHeld as $path => $locks ) { foreach ( $locks as $type => $count ) { $pathsByType[$type][] = $path; } } if ( $pathsByType ) { $this->unlockByType( $pathsByType ); } } } PK ! -м�o- o- lockmanager/MemcLockManager.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ use Wikimedia\ObjectCache\MemcachedBagOStuff; use Wikimedia\ObjectCache\MemcachedPhpBagOStuff; use Wikimedia\WaitConditionLoop; /** * Manage locks using memcached servers. * * Version of LockManager based on using memcached servers. * This is meant for multi-wiki systems that may share files. * All locks are non-blocking, which avoids deadlocks. * * All lock requests for a resource, identified by a hash string, will map to one * bucket. Each bucket maps to one or several peer servers, each running memcached. * A majority of peers must agree for a lock to be acquired. * * @ingroup LockManager * @since 1.20 */ class MemcLockManager extends QuorumLockManager { /** @var array Mapping of lock types to the type actually used */ protected $lockTypeMap = [ self::LOCK_SH => self::LOCK_SH, self::LOCK_UW => self::LOCK_SH, self::LOCK_EX => self::LOCK_EX ]; /** @var MemcachedBagOStuff[] Map of (server name => MemcachedBagOStuff) */ protected $cacheServers = []; /** @var MapCacheLRU Server status cache */ protected $statusCache; /** * Construct a new instance from configuration. * * @param array $config Parameters include: * - lockServers : Associative array of server names to "<IP>:<port>" strings. * - srvsByBucket : An array of up to 16 arrays, each containing the server names * in a bucket. Each bucket should have an odd number of servers. * If omitted, all servers will be in one bucket. [optional]. * - memcConfig : Configuration array for MemcachedBagOStuff::construct() with an * additional 'class' parameter specifying which MemcachedBagOStuff * subclass to use. The server names will be injected. [optional] * @throws Exception */ public function __construct( array $config ) { parent::__construct( $config ); if ( isset( $config['srvsByBucket'] ) ) { // Sanitize srvsByBucket config to prevent PHP errors $this->srvsByBucket = array_filter( $config['srvsByBucket'], 'is_array' ); $this->srvsByBucket = array_values( $this->srvsByBucket ); // consecutive } else { $this->srvsByBucket = [ array_keys( $config['lockServers'] ) ]; } $memcConfig = $config['memcConfig'] ?? []; $memcConfig += [ 'class' => MemcachedPhpBagOStuff::class ]; // default $class = $memcConfig['class']; if ( !is_subclass_of( $class, MemcachedBagOStuff::class ) ) { throw new InvalidArgumentException( "$class is not of type MemcachedBagOStuff." ); } foreach ( $config['lockServers'] as $name => $address ) { $params = [ 'servers' => [ $address ] ] + $memcConfig; $this->cacheServers[$name] = new $class( $params ); } $this->statusCache = new MapCacheLRU( 100 ); } protected function getLocksOnServer( $lockSrv, array $pathsByType ) { $status = StatusValue::newGood(); $memc = $this->getCache( $lockSrv ); // List of affected paths $paths = array_merge( ...array_values( $pathsByType ) ); $paths = array_unique( $paths ); // List of affected lock record keys $keys = array_map( [ $this, 'recordKeyForPath' ], $paths ); // Lock all of the active lock record keys... if ( !$this->acquireMutexes( $memc, $keys ) ) { $status->fatal( 'lockmanager-fail-conflict' ); return $status; } // Fetch all the existing lock records... $lockRecords = $memc->getMulti( $keys ); $now = time(); // Check if the requested locks conflict with existing ones... foreach ( $pathsByType as $type => $paths2 ) { foreach ( $paths2 as $path ) { $locksKey = $this->recordKeyForPath( $path ); $locksHeld = isset( $lockRecords[$locksKey] ) ? self::sanitizeLockArray( $lockRecords[$locksKey] ) : self::newLockArray(); // init foreach ( $locksHeld[self::LOCK_EX] as $session => $expiry ) { if ( $expiry < $now ) { // stale? unset( $locksHeld[self::LOCK_EX][$session] ); } elseif ( $session !== $this->session ) { $status->fatal( 'lockmanager-fail-conflict' ); } } if ( $type === self::LOCK_EX ) { foreach ( $locksHeld[self::LOCK_SH] as $session => $expiry ) { if ( $expiry < $now ) { // stale? unset( $locksHeld[self::LOCK_SH][$session] ); } elseif ( $session !== $this->session ) { $status->fatal( 'lockmanager-fail-conflict' ); } } } if ( $status->isOK() ) { // Register the session in the lock record array $locksHeld[$type][$this->session] = $now + $this->lockTTL; // We will update this record if none of the other locks conflict $lockRecords[$locksKey] = $locksHeld; } } } // If there were no lock conflicts, update all the lock records... if ( $status->isOK() ) { foreach ( $paths as $path ) { $locksKey = $this->recordKeyForPath( $path ); $locksHeld = $lockRecords[$locksKey]; $ok = $memc->set( $locksKey, $locksHeld, self::MAX_LOCK_TTL ); if ( !$ok ) { $status->fatal( 'lockmanager-fail-acquirelock', $path ); } else { $this->logger->debug( __METHOD__ . ": acquired lock on key $locksKey." ); } } } // Unlock all of the active lock record keys... $this->releaseMutexes( $memc, $keys ); return $status; } protected function freeLocksOnServer( $lockSrv, array $pathsByType ) { $status = StatusValue::newGood(); $memc = $this->getCache( $lockSrv ); // List of affected paths $paths = array_merge( ...array_values( $pathsByType ) ); $paths = array_unique( $paths ); // List of affected lock record keys $keys = array_map( [ $this, 'recordKeyForPath' ], $paths ); // Lock all of the active lock record keys... if ( !$this->acquireMutexes( $memc, $keys ) ) { foreach ( $paths as $path ) { $status->fatal( 'lockmanager-fail-releaselock', $path ); } return $status; } // Fetch all the existing lock records... $lockRecords = $memc->getMulti( $keys ); // Remove the requested locks from all records... foreach ( $pathsByType as $type => $paths2 ) { foreach ( $paths2 as $path ) { $locksKey = $this->recordKeyForPath( $path ); // lock record if ( !isset( $lockRecords[$locksKey] ) ) { $status->warning( 'lockmanager-fail-releaselock', $path ); continue; // nothing to do } $locksHeld = $this->sanitizeLockArray( $lockRecords[$locksKey] ); if ( isset( $locksHeld[$type][$this->session] ) ) { unset( $locksHeld[$type][$this->session] ); // unregister this session $lockRecords[$locksKey] = $locksHeld; } else { $status->warning( 'lockmanager-fail-releaselock', $path ); } } } // Persist the new lock record values... foreach ( $paths as $path ) { $locksKey = $this->recordKeyForPath( $path ); if ( !isset( $lockRecords[$locksKey] ) ) { continue; // nothing to do } $locksHeld = $lockRecords[$locksKey]; if ( $locksHeld === $this->newLockArray() ) { $ok = $memc->delete( $locksKey ); } else { $ok = $memc->set( $locksKey, $locksHeld, self::MAX_LOCK_TTL ); } if ( $ok ) { $this->logger->debug( __METHOD__ . ": released lock on key $locksKey." ); } else { $status->fatal( 'lockmanager-fail-releaselock', $path ); } } // Unlock all of the active lock record keys... $this->releaseMutexes( $memc, $keys ); return $status; } /** * @see QuorumLockManager::releaseAllLocks() * @return StatusValue */ protected function releaseAllLocks() { return StatusValue::newGood(); // not supported } /** * @see QuorumLockManager::isServerUp() * @param string $lockSrv * @return bool */ protected function isServerUp( $lockSrv ) { return (bool)$this->getCache( $lockSrv ); } /** * Get the MemcachedBagOStuff object for a $lockSrv * * @param string $lockSrv Server name * @return MemcachedBagOStuff|null */ protected function getCache( $lockSrv ) { if ( !isset( $this->cacheServers[$lockSrv] ) ) { throw new InvalidArgumentException( "Invalid cache server '$lockSrv'." ); } $online = $this->statusCache->get( "online:$lockSrv", 30 ); if ( $online === null ) { $online = $this->cacheServers[$lockSrv]->set( __CLASS__ . ':ping', 1, 1 ); if ( !$online ) { // server down? $this->logger->warning( __METHOD__ . ": Could not contact $lockSrv." ); } $this->statusCache->set( "online:$lockSrv", (int)$online ); } return $online ? $this->cacheServers[$lockSrv] : null; } /** * @param string $path * @return string */ protected function recordKeyForPath( $path ) { return implode( ':', [ __CLASS__, 'locks', $this->sha1Base36Absolute( $path ) ] ); } /** * @return array An empty lock structure for a key */ protected function newLockArray() { return [ self::LOCK_SH => [], self::LOCK_EX => [] ]; } /** * @param array $a * @return array An empty lock structure for a key */ protected function sanitizeLockArray( $a ) { if ( is_array( $a ) && isset( $a[self::LOCK_EX] ) && isset( $a[self::LOCK_SH] ) ) { return $a; } $this->logger->error( __METHOD__ . ": reset invalid lock array." ); return $this->newLockArray(); } /** * @param MemcachedBagOStuff $memc * @param array $keys List of keys to acquire * @return bool */ protected function acquireMutexes( MemcachedBagOStuff $memc, array $keys ) { $lockedKeys = []; // Acquire the keys in lexicographical order, to avoid deadlock problems. // If P1 is waiting to acquire a key P2 has, P2 can't also be waiting for a key P1 has. sort( $keys ); // Try to quickly loop to acquire the keys, but back off after a few rounds. // This reduces memcached spam, especially in the rare case where a server acquires // some lock keys and dies without releasing them. Lock keys expire after a few minutes. $loop = new WaitConditionLoop( static function () use ( $memc, $keys, &$lockedKeys ) { foreach ( array_diff( $keys, $lockedKeys ) as $key ) { if ( $memc->add( "$key:mutex", 1, 180 ) ) { // lock record $lockedKeys[] = $key; } } return array_diff( $keys, $lockedKeys ) ? WaitConditionLoop::CONDITION_CONTINUE : true; }, 3.0 // timeout ); $loop->invoke(); if ( count( $lockedKeys ) != count( $keys ) ) { $this->releaseMutexes( $memc, $lockedKeys ); // failed; release what was locked return false; } return true; } /** * @param MemcachedBagOStuff $memc * @param array $keys List of acquired keys */ protected function releaseMutexes( MemcachedBagOStuff $memc, array $keys ) { foreach ( $keys as $key ) { $memc->delete( "$key:mutex" ); } } /** * Make sure remaining locks get cleared */ public function __destruct() { $pathsByType = []; foreach ( $this->locksHeld as $path => $locks ) { foreach ( $locks as $type => $count ) { $pathsByType[$type][] = $path; } } if ( $pathsByType ) { $this->unlockByType( $pathsByType ); } } } PK ! �)� � lockmanager/FSLockManager.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ /** * Simple lock management based on server-local temporary files. * * All locks are non-blocking, which avoids deadlocks. * * This should work fine for small sites running from a single web server. * Do not use this with 'lockDirectory' set to an NFS mount unless the * NFS client is at least version 2.6.12. Otherwise, the BSD flock() * locks will be ignored; see http://nfs.sourceforge.net/#section_d. * * @ingroup LockManager * @since 1.19 */ class FSLockManager extends LockManager { /** @var array Mapping of lock types to the type actually used */ protected $lockTypeMap = [ self::LOCK_SH => self::LOCK_SH, self::LOCK_UW => self::LOCK_SH, self::LOCK_EX => self::LOCK_EX ]; /** @var string Global dir for all servers */ protected $lockDir; /** @var array Map of (locked key => lock file handle) */ protected $handles = []; /** @var bool */ protected $isWindows; /** * Construct a new instance from configuration. * * @param array $config Includes: * - lockDirectory : Directory containing the lock files */ public function __construct( array $config ) { parent::__construct( $config ); $this->lockDir = $config['lockDirectory']; $this->isWindows = ( PHP_OS_FAMILY === 'Windows' ); } /** * @see LockManager::doLock() * @param array $paths * @param int $type * @return StatusValue */ protected function doLock( array $paths, $type ) { $status = StatusValue::newGood(); $lockedPaths = []; // files locked in this attempt foreach ( $paths as $path ) { $status->merge( $this->doSingleLock( $path, $type ) ); if ( $status->isOK() ) { $lockedPaths[] = $path; } else { // Abort and unlock everything $status->merge( $this->doUnlock( $lockedPaths, $type ) ); return $status; } } return $status; } /** * @see LockManager::doUnlock() * @param array $paths * @param int $type * @return StatusValue */ protected function doUnlock( array $paths, $type ) { $status = StatusValue::newGood(); foreach ( $paths as $path ) { $status->merge( $this->doSingleUnlock( $path, $type ) ); } return $status; } /** * Lock a single resource key * * @param string $path * @param int $type * @return StatusValue */ protected function doSingleLock( $path, $type ) { $status = StatusValue::newGood(); if ( isset( $this->locksHeld[$path][$type] ) ) { ++$this->locksHeld[$path][$type]; } elseif ( isset( $this->locksHeld[$path][self::LOCK_EX] ) ) { $this->locksHeld[$path][$type] = 1; } else { if ( isset( $this->handles[$path] ) ) { $handle = $this->handles[$path]; } else { // phpcs:ignore Generic.PHP.NoSilencedErrors.Discouraged $handle = @fopen( $this->getLockPath( $path ), 'a+' ); if ( !$handle && !is_dir( $this->lockDir ) ) { // Create the lock directory and try again // phpcs:ignore Generic.PHP.NoSilencedErrors.Discouraged if ( @mkdir( $this->lockDir, 0777, true ) ) { // phpcs:ignore Generic.PHP.NoSilencedErrors.Discouraged $handle = @fopen( $this->getLockPath( $path ), 'a+' ); } else { $this->logger->error( "Cannot create directory '{$this->lockDir}'." ); } } } if ( $handle ) { // Either a shared or exclusive lock $lock = ( $type == self::LOCK_SH ) ? LOCK_SH : LOCK_EX; if ( flock( $handle, $lock | LOCK_NB ) ) { // Record this lock as active $this->locksHeld[$path][$type] = 1; $this->handles[$path] = $handle; } else { fclose( $handle ); $status->fatal( 'lockmanager-fail-conflict' ); } } else { $status->fatal( 'lockmanager-fail-openlock', $path ); } } return $status; } /** * Unlock a single resource key * * @param string $path * @param int $type * @return StatusValue */ protected function doSingleUnlock( $path, $type ) { $status = StatusValue::newGood(); if ( !isset( $this->locksHeld[$path] ) ) { $status->warning( 'lockmanager-notlocked', $path ); } elseif ( !isset( $this->locksHeld[$path][$type] ) ) { $status->warning( 'lockmanager-notlocked', $path ); } else { $handlesToClose = []; --$this->locksHeld[$path][$type]; if ( $this->locksHeld[$path][$type] <= 0 ) { unset( $this->locksHeld[$path][$type] ); } if ( $this->locksHeld[$path] === [] ) { unset( $this->locksHeld[$path] ); // no locks on this path if ( isset( $this->handles[$path] ) ) { $handlesToClose[] = $this->handles[$path]; unset( $this->handles[$path] ); } } // Unlock handles to release locks and delete // any lock files that end up with no locks on them... if ( $this->isWindows ) { // Windows: for any process, including this one, // calling unlink() on a locked file will fail $status->merge( $this->closeLockHandles( $path, $handlesToClose ) ); $status->merge( $this->pruneKeyLockFiles( $path ) ); } else { // Unix: unlink() can be used on files currently open by this // process and we must do so in order to avoid race conditions $status->merge( $this->pruneKeyLockFiles( $path ) ); $status->merge( $this->closeLockHandles( $path, $handlesToClose ) ); } } return $status; } /** * @param string $path * @param array $handlesToClose * @return StatusValue */ private function closeLockHandles( $path, array $handlesToClose ) { $status = StatusValue::newGood(); foreach ( $handlesToClose as $handle ) { if ( !flock( $handle, LOCK_UN ) ) { $status->fatal( 'lockmanager-fail-releaselock', $path ); } if ( !fclose( $handle ) ) { $status->warning( 'lockmanager-fail-closelock', $path ); } } return $status; } /** * @param string $path * @return StatusValue */ private function pruneKeyLockFiles( $path ) { $status = StatusValue::newGood(); if ( !isset( $this->locksHeld[$path] ) ) { # No locks are held for the lock file anymore if ( !unlink( $this->getLockPath( $path ) ) ) { $status->warning( 'lockmanager-fail-deletelock', $path ); } unset( $this->handles[$path] ); } return $status; } /** * Get the path to the lock file for a key * @param string $path * @return string */ protected function getLockPath( $path ) { return "{$this->lockDir}/{$this->sha1Base36Absolute( $path )}.lock"; } /** * Make sure remaining locks get cleared */ public function __destruct() { while ( count( $this->locksHeld ) ) { foreach ( $this->locksHeld as $path => $locks ) { $this->doSingleUnlock( $path, self::LOCK_EX ); $this->doSingleUnlock( $path, self::LOCK_SH ); } } } } PK ! m��/� � lockmanager/NullLockManager.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ /** * Simple lock management based on in-process reference counting. * * @since 1.19 * @ingroup LockManager */ class NullLockManager extends LockManager { protected function doLock( array $paths, $type ) { foreach ( $paths as $path ) { if ( isset( $this->locksHeld[$path][$type] ) ) { ++$this->locksHeld[$path][$type]; } else { $this->locksHeld[$path][$type] = 1; } } return StatusValue::newGood(); } protected function doUnlock( array $paths, $type ) { $status = StatusValue::newGood(); foreach ( $paths as $path ) { if ( isset( $this->locksHeld[$path][$type] ) ) { if ( --$this->locksHeld[$path][$type] <= 0 ) { unset( $this->locksHeld[$path][$type] ); if ( !$this->locksHeld[$path] ) { unset( $this->locksHeld[$path] ); // clean up } } } else { $status->warning( 'lockmanager-notlocked', $path ); } } return $status; } } PK ! ܛy" y" lockmanager/LockManager.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ use Psr\Log\LoggerInterface; use Psr\Log\NullLogger; use Wikimedia\RequestTimeout\RequestTimeout; use Wikimedia\WaitConditionLoop; /** * @defgroup LockManager Lock management * @ingroup FileBackend */ /** * Resource locking handling. * * Locks on resource keys can either be shared or exclusive. * * Implementations must keep track of what is locked by this process * in-memory and support nested locking calls (using reference counting). * At least LOCK_UW and LOCK_EX must be implemented. LOCK_SH can be a no-op. * Locks should either be non-blocking or have low wait timeouts. * * Subclasses should avoid throwing exceptions at all costs. * * @stable to extend * @ingroup LockManager * @since 1.19 */ abstract class LockManager { /** @var LoggerInterface */ protected $logger; /** @var array Mapping of lock types to the type actually used */ protected $lockTypeMap = [ self::LOCK_SH => self::LOCK_SH, self::LOCK_UW => self::LOCK_EX, // subclasses may use self::LOCK_SH self::LOCK_EX => self::LOCK_EX ]; /** @var array Map of (resource path => lock type => count) */ protected $locksHeld = []; /** @var string domain (usually wiki ID) */ protected $domain; /** @var int maximum time locks can be held */ protected $lockTTL; /** @var string Random 32-char hex number */ protected $session; /** Lock types; stronger locks have higher values */ public const LOCK_SH = 1; // shared lock (for reads) public const LOCK_UW = 2; // shared lock (for reads used to write elsewhere) public const LOCK_EX = 3; // exclusive lock (for writes) /** Max expected lock expiry in any context */ protected const MAX_LOCK_TTL = 2 * 3600; // 2 hours /** Default lock TTL in CLI mode */ protected const CLI_LOCK_TTL = 3600; // 1 hour /** Minimum lock TTL. The configured lockTTL is ignored if it is less than this value. */ protected const MIN_LOCK_TTL = 5; // seconds /** The minimum lock TTL if it is guessed from max_execution_time rather than configured. */ protected const MIN_GUESSED_LOCK_TTL = 5 * 60; // 5 minutes /** * Construct a new instance from configuration * @stable to call * * @param array $config Parameters include: * - domain : Domain (usually wiki ID) that all resources are relative to [optional] * - lockTTL : Age (in seconds) at which resource locks should expire. * This only applies if locks are not tied to a connection/process. */ public function __construct( array $config ) { $this->domain = $config['domain'] ?? 'global'; if ( isset( $config['lockTTL'] ) ) { $this->lockTTL = max( self::MIN_LOCK_TTL, $config['lockTTL'] ); } elseif ( PHP_SAPI === 'cli' || PHP_SAPI === 'phpdbg' ) { $this->lockTTL = self::CLI_LOCK_TTL; } else { $ttl = 2 * ceil( RequestTimeout::singleton()->getWallTimeLimit() ); $this->lockTTL = ( $ttl === INF || $ttl < self::MIN_GUESSED_LOCK_TTL ) ? self::MIN_GUESSED_LOCK_TTL : $ttl; } // Upper bound on how long to keep lock structures around. This is useful when setting // TTLs, as the "lockTTL" value may vary based on CLI mode and app server group. This is // a "safe" value that can be used to avoid clobbering other locks that use high TTLs. $this->lockTTL = min( $this->lockTTL, self::MAX_LOCK_TTL ); $random = []; for ( $i = 1; $i <= 5; ++$i ) { $random[] = mt_rand( 0, 0xFFFFFFF ); } $this->session = md5( implode( '-', $random ) ); $this->logger = $config['logger'] ?? new NullLogger(); } /** * Lock the resources at the given abstract paths * * @param array $paths List of resource names * @param int $type LockManager::LOCK_* constant * @param int $timeout Timeout in seconds (0 means non-blocking) (since 1.21) * @return StatusValue */ final public function lock( array $paths, $type = self::LOCK_EX, $timeout = 0 ) { return $this->lockByType( [ $type => $paths ], $timeout ); } /** * Lock the resources at the given abstract paths * * @param array $pathsByType Map of LockManager::LOCK_* constants to lists of paths * @param int $timeout Timeout in seconds (0 means non-blocking) (since 1.21) * @return StatusValue * @since 1.22 */ final public function lockByType( array $pathsByType, $timeout = 0 ) { $pathsByType = $this->normalizePathsByType( $pathsByType ); $status = null; $loop = new WaitConditionLoop( function () use ( &$status, $pathsByType ) { $status = $this->doLockByType( $pathsByType ); return $status->isOK() ?: WaitConditionLoop::CONDITION_CONTINUE; }, $timeout ); $loop->invoke(); // @phan-suppress-next-line PhanTypeMismatchReturn WaitConditionLoop throws or status is set return $status; } /** * Unlock the resources at the given abstract paths * * @param array $paths List of paths * @param int $type LockManager::LOCK_* constant * @return StatusValue */ final public function unlock( array $paths, $type = self::LOCK_EX ) { return $this->unlockByType( [ $type => $paths ] ); } /** * Unlock the resources at the given abstract paths * * @param array $pathsByType Map of LockManager::LOCK_* constants to lists of paths * @return StatusValue * @since 1.22 */ final public function unlockByType( array $pathsByType ) { $pathsByType = $this->normalizePathsByType( $pathsByType ); $status = $this->doUnlockByType( $pathsByType ); return $status; } /** * Get the base 36 SHA-1 of a string, padded to 31 digits. * Before hashing, the path will be prefixed with the domain ID. * This should be used internally for lock key or file names. * * @param string $path * @return string */ final protected function sha1Base36Absolute( $path ) { return Wikimedia\base_convert( sha1( "{$this->domain}:{$path}" ), 16, 36, 31 ); } /** * Normalize the $paths array by converting LOCK_UW locks into the * appropriate type and removing any duplicated paths for each lock type. * * @param array $pathsByType Map of LockManager::LOCK_* constants to lists of paths * @return array * @since 1.22 */ final protected function normalizePathsByType( array $pathsByType ) { $res = []; foreach ( $pathsByType as $type => $paths ) { foreach ( $paths as $path ) { if ( (string)$path === '' ) { throw new InvalidArgumentException( __METHOD__ . ": got empty path." ); } } $res[$this->lockTypeMap[$type]] = array_unique( $paths ); } return $res; } /** * @see LockManager::lockByType() * @stable to override * @param array $pathsByType Map of LockManager::LOCK_* constants to lists of paths * @return StatusValue * @since 1.22 */ protected function doLockByType( array $pathsByType ) { $status = StatusValue::newGood(); $lockedByType = []; // map of (type => paths) foreach ( $pathsByType as $type => $paths ) { $status->merge( $this->doLock( $paths, $type ) ); if ( $status->isOK() ) { $lockedByType[$type] = $paths; } else { // Release the subset of locks that were acquired foreach ( $lockedByType as $lType => $lPaths ) { $status->merge( $this->doUnlock( $lPaths, $lType ) ); } break; } } return $status; } /** * Lock resources with the given keys and lock type * * @param array $paths List of paths * @param int $type LockManager::LOCK_* constant * @return StatusValue */ abstract protected function doLock( array $paths, $type ); /** * @see LockManager::unlockByType() * @stable to override * @param array $pathsByType Map of LockManager::LOCK_* constants to lists of paths * @return StatusValue * @since 1.22 */ protected function doUnlockByType( array $pathsByType ) { $status = StatusValue::newGood(); foreach ( $pathsByType as $type => $paths ) { $status->merge( $this->doUnlock( $paths, $type ) ); } return $status; } /** * Unlock resources with the given keys and lock type * * @param array $paths List of paths * @param int $type LockManager::LOCK_* constant * @return StatusValue */ abstract protected function doUnlock( array $paths, $type ); } PK ! �W��� � objectcache/README.mdnu �Iw�� # wikimedia/objectcache ## Statistics Sent to StatsD under MediaWiki's namespace. ### WANObjectCache The default WANObjectCache provided by MediaWikiServices disables these statistics in entry points where MW_ENTRY_POINT is 'cli'. #### `wanobjectcache.{kClass}.{cache_action_and_result}` Upon cache access via `WANObjectCache::getWithSetCallback()`, this measures the total time spent in this method from start to end for all cases, except process-cache hits. See also `wanobjectcache.{kClass}.regen_walltime`, which, during misses/renews, measures just the portion of time spent in the callback to regenerate the value. * Type: Measure (in milliseconds). * Variable `kClass`: The first part of your cache key. * Variable `result`: One of: * `"hit.good"`: A non-expired value was returned (and call did not get chosen for pre-emptive refresh). * `"hit.refresh"`: A non-expired value was returned (and call was chosen for a pre-emptive refresh, and an async refresh was scheduled). * `"hit.volatile"`: A value was found that was generated and stored less than 0.1s ago, and returned as-is despite appearing to also be expired already. This amount of time is considered negligible in terms of clock accuracy, and by random chance we usually decide to treat these as a cache hit (see `RECENT_SET_HIGH_MS`). * `"hit.stale"`: An expired value was found, but we are within the allowed stale period specified by a `lockTSE` option, and the current request did not get the regeneration lock. The stale value is returned as-is. * `"miss.compute"`: A new value was computed by the callback and returned. No non-expired value was found, and if this key needed a regeneration lock, we got the lock. * `"miss.busy"`: A busy value was produced by a `busyValue` callback and returned. No non-expired value was found, and we tried to use a regeneration lock (per the `busyValue` option), but the current request did not get the lock. * `"renew.compute"`: Artificial demand from an async refresh, led to a new value being computed by the callback. These are like `"miss.compute"`, but in response to `"hit.refresh"`. * `"renew.busy"`: Artificial demand from an async refresh failed to produce a value. The key used the `busyValue` option, and could not get a regeneration lock. #### `wanobjectcache.{kClass}.regen_walltime` Upon cache update due to a cache miss or async refresh, this measures the time spent in the regeneration callback when computing a new value. * Type: Measure (in milliseconds). * Variable `kClass`: The first part of your cache key. #### `wanobjectcache.{kClass}.ck_touch.{result}` Call counter from `WANObjectCache::touchCheckKey()`. * Type: Counter. * Variable `kClass`: The first part of your cache key. * Variable `result`: One of `"ok"` or `"error"`. #### `wanobjectcache.{kClass}.ck_reset.{result}` Call counter from `WANObjectCache::resetCheckKey()`. * Type: Counter. * Variable `kClass`: The first part of your cache key. * Variable `result`: One of `"ok"` or `"error"`. #### `wanobjectcache.{kClass}.delete.{result}` Call counter from `WANObjectCache::delete()`. * Type: Counter. * Variable `kClass`: The first part of your cache key. * Variable `result`: One of `"ok"` or `"error"`. PK ! 3�T� � objectcache/HashBagOStuff.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\ObjectCache; use InvalidArgumentException; /** * Store data in a memory for the current request/process only. * * This keeps values in a simple associative array. * Data will not persist and is not shared with other requests * on the same server. * * @newable * @ingroup Cache */ class HashBagOStuff extends MediumSpecificBagOStuff { /** @var mixed[] */ protected $bag = []; /** @var int|double Max entries allowed, INF for unlimited */ protected $maxCacheKeys; /** @var string CAS token prefix for this instance */ private $token; /** @var int CAS token counter */ private static $casCounter = 0; public const KEY_VAL = 0; public const KEY_EXP = 1; public const KEY_CAS = 2; /** * @stable to call * * @param array $params Additional parameters include: * - maxKeys : only allow this many keys (using oldest-first eviction) * * @phpcs:ignore Generic.Files.LineLength * @phan-param array{logger?:\Psr\Log\LoggerInterface,asyncHandler?:callable,keyspace?:string,reportDupes?:bool,segmentationSize?:int,segmentedValueMaxSize?:int,maxKeys?:int} $params */ public function __construct( $params = [] ) { $params['segmentationSize'] ??= INF; parent::__construct( $params ); $this->token = microtime( true ) . ':' . mt_rand(); $maxKeys = $params['maxKeys'] ?? INF; if ( $maxKeys !== INF && ( !is_int( $maxKeys ) || $maxKeys <= 0 ) ) { throw new InvalidArgumentException( '$maxKeys parameter must be above zero' ); } $this->maxCacheKeys = $maxKeys; $this->attrMap[self::ATTR_DURABILITY] = self::QOS_DURABILITY_SCRIPT; } protected function doGet( $key, $flags = 0, &$casToken = null ) { $getToken = ( $casToken === self::PASS_BY_REF ); $casToken = null; if ( !$this->hasKey( $key ) || $this->expire( $key ) ) { return false; } // Refresh key position for maxCacheKeys eviction $temp = $this->bag[$key]; unset( $this->bag[$key] ); $this->bag[$key] = $temp; $value = $this->bag[$key][self::KEY_VAL]; if ( $getToken && $value !== false ) { $casToken = $this->bag[$key][self::KEY_CAS]; } return $value; } protected function doSet( $key, $value, $exptime = 0, $flags = 0 ) { // Refresh key position for maxCacheKeys eviction unset( $this->bag[$key] ); $this->bag[$key] = [ self::KEY_VAL => $value, self::KEY_EXP => $this->getExpirationAsTimestamp( $exptime ), self::KEY_CAS => $this->token . ':' . ++self::$casCounter ]; if ( count( $this->bag ) > $this->maxCacheKeys ) { $evictKey = array_key_first( $this->bag ); unset( $this->bag[$evictKey] ); } return true; } protected function doAdd( $key, $value, $exptime = 0, $flags = 0 ) { if ( $this->hasKey( $key ) && !$this->expire( $key ) ) { // key already set return false; } return $this->doSet( $key, $value, $exptime, $flags ); } protected function doDelete( $key, $flags = 0 ) { unset( $this->bag[$key] ); return true; } protected function doIncrWithInit( $key, $exptime, $step, $init, $flags ) { $curValue = $this->doGet( $key ); if ( $curValue === false ) { $newValue = $this->doSet( $key, $init, $exptime ) ? $init : false; } elseif ( $this->isInteger( $curValue ) ) { $newValue = max( $curValue + $step, 0 ); $this->bag[$key][self::KEY_VAL] = $newValue; } else { $newValue = false; } return $newValue; } /** * Clear all values in cache */ public function clear() { $this->bag = []; } /** * @param string $key * * @return bool */ protected function expire( $key ) { $et = $this->bag[$key][self::KEY_EXP]; if ( $et == self::TTL_INDEFINITE || $et > $this->getCurrentTime() ) { return false; } $this->doDelete( $key ); return true; } /** * Does this bag have a non-null value for the given key? * * @param string $key * * @return bool * @since 1.27 */ public function hasKey( $key ) { return isset( $this->bag[$key] ); } } /** @deprecated class alias since 1.43 */ class_alias( HashBagOStuff::class, 'HashBagOStuff' ); PK ! �tu��C �C objectcache/RedisBagOStuff.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\ObjectCache; use ArrayUtils; use Exception; use Redis; use RedisException; /** * Store data in Redis. * * This requires the php-redis PECL extension (2.2.4 or later) and * a Redis server (2.6.12 or later). * * @see http://redis.io/ * @see https://github.com/phpredis/phpredis/blob/d310ed7c8/Changelog.md * * @note Avoid use of Redis::MULTI transactions for twemproxy support * * @ingroup Cache * @ingroup Redis * @phan-file-suppress PhanTypeComparisonFromArray It's unclear whether exec() can return false */ class RedisBagOStuff extends MediumSpecificBagOStuff { /** @var RedisConnectionPool */ protected $redisPool; /** @var array List of server names */ protected $servers; /** @var array Map of (tag => server name) */ protected $serverTagMap; /** @var bool */ protected $automaticFailover; /** * Construct a RedisBagOStuff object. Parameters are: * * - servers: An array of server names. A server name may be a hostname, * a hostname/port combination or the absolute path of a UNIX socket. * If a hostname is specified but no port, the standard port number * 6379 will be used. Arrays keys can be used to specify the tag to * hash on in place of the host/port. Required. * * - connectTimeout: The timeout for new connections, in seconds. Optional, * default is 1 second. * * - persistent: Set this to true to allow connections to persist across * multiple web requests. False by default. * * - password: The authentication password, will be sent to Redis in * clear text. Optional, if it is unspecified, no AUTH command will be * sent. * * - automaticFailover: If this is false, then each key will be mapped to * a single server, and if that server is down, any requests for that key * will fail. If this is true, a connection failure will cause the client * to immediately try the next server in the list (as determined by a * consistent hashing algorithm). True by default. This has the * potential to create consistency issues if a server is slow enough to * flap, for example if it is in swap death. * * @param array $params */ public function __construct( $params ) { parent::__construct( $params ); $redisConf = [ 'serializer' => 'none' ]; // manage that in this class foreach ( [ 'connectTimeout', 'persistent', 'password' ] as $opt ) { if ( isset( $params[$opt] ) ) { $redisConf[$opt] = $params[$opt]; } } $this->redisPool = RedisConnectionPool::singleton( $redisConf ); $this->servers = $params['servers']; foreach ( $this->servers as $key => $server ) { $this->serverTagMap[is_int( $key ) ? $server : $key] = $server; } $this->automaticFailover = $params['automaticFailover'] ?? true; // ...and uses rdb snapshots (redis.conf default) $this->attrMap[self::ATTR_DURABILITY] = self::QOS_DURABILITY_DISK; } protected function doGet( $key, $flags = 0, &$casToken = null ) { $getToken = ( $casToken === self::PASS_BY_REF ); $casToken = null; $conn = $this->getConnection( $key ); if ( !$conn ) { return false; } $e = null; try { $blob = $conn->get( $key ); if ( $blob !== false ) { $value = $this->unserialize( $blob ); $valueSize = strlen( $blob ); } else { $value = false; $valueSize = false; } if ( $getToken && $value !== false ) { $casToken = $blob; } } catch ( RedisException $e ) { $value = false; $valueSize = false; $this->handleException( $conn, $e ); } $this->logRequest( 'get', $key, $conn->getServer(), $e ); $this->updateOpStats( self::METRIC_OP_GET, [ $key => [ 0, $valueSize ] ] ); return $value; } protected function doSet( $key, $value, $exptime = 0, $flags = 0 ) { $conn = $this->getConnection( $key ); if ( !$conn ) { return false; } $ttl = $this->getExpirationAsTTL( $exptime ); $serialized = $this->getSerialized( $value, $key ); $valueSize = strlen( $serialized ); $e = null; try { if ( $ttl ) { $result = $conn->setex( $key, $ttl, $serialized ); } else { $result = $conn->set( $key, $serialized ); } } catch ( RedisException $e ) { $result = false; $this->handleException( $conn, $e ); } $this->logRequest( 'set', $key, $conn->getServer(), $e ); $this->updateOpStats( self::METRIC_OP_SET, [ $key => [ $valueSize, 0 ] ] ); return $result; } protected function doDelete( $key, $flags = 0 ) { $conn = $this->getConnection( $key ); if ( !$conn ) { return false; } $e = null; try { // Note that redis does not return false if the key was not there $result = ( $conn->del( $key ) !== false ); } catch ( RedisException $e ) { $result = false; $this->handleException( $conn, $e ); } $this->logRequest( 'delete', $key, $conn->getServer(), $e ); $this->updateOpStats( self::METRIC_OP_DELETE, [ $key ] ); return $result; } protected function doGetMulti( array $keys, $flags = 0 ) { $blobsFound = []; [ $keysByServer, $connByServer ] = $this->getConnectionsForKeys( $keys ); foreach ( $keysByServer as $server => $batchKeys ) { $conn = $connByServer[$server]; $e = null; try { // Avoid mget() to reduce CPU hogging from a single request $conn->multi( Redis::PIPELINE ); foreach ( $batchKeys as $key ) { $conn->get( $key ); } $batchResult = $conn->exec(); if ( $batchResult === false ) { $this->logRequest( 'get', implode( ',', $batchKeys ), $server, true ); continue; } foreach ( $batchResult as $i => $blob ) { if ( $blob !== false ) { $blobsFound[$batchKeys[$i]] = $blob; } } } catch ( RedisException $e ) { $this->handleException( $conn, $e ); } $this->logRequest( 'get', implode( ',', $batchKeys ), $server, $e ); } // Preserve the order of $keys $result = []; $valueSizesByKey = []; foreach ( $keys as $key ) { if ( array_key_exists( $key, $blobsFound ) ) { $blob = $blobsFound[$key]; $value = $this->unserialize( $blob ); if ( $value !== false ) { $result[$key] = $value; } $valueSize = strlen( $blob ); } else { $valueSize = false; } $valueSizesByKey[$key] = [ 0, $valueSize ]; } $this->updateOpStats( self::METRIC_OP_GET, $valueSizesByKey ); return $result; } protected function doSetMulti( array $data, $exptime = 0, $flags = 0 ) { $ttl = $this->getExpirationAsTTL( $exptime ); $op = $ttl ? 'setex' : 'set'; $keys = array_keys( $data ); $valueSizesByKey = []; [ $keysByServer, $connByServer, $result ] = $this->getConnectionsForKeys( $keys ); foreach ( $keysByServer as $server => $batchKeys ) { $conn = $connByServer[$server]; $e = null; try { // Avoid mset() to reduce CPU hogging from a single request $conn->multi( Redis::PIPELINE ); foreach ( $batchKeys as $key ) { $serialized = $this->getSerialized( $data[$key], $key ); if ( $ttl ) { $conn->setex( $key, $ttl, $serialized ); } else { $conn->set( $key, $serialized ); } $valueSizesByKey[$key] = [ strlen( $serialized ), 0 ]; } $batchResult = $conn->exec(); if ( $batchResult === false ) { $result = false; $this->logRequest( $op, implode( ',', $batchKeys ), $server, true ); continue; } $result = $result && !in_array( false, $batchResult, true ); } catch ( RedisException $e ) { $this->handleException( $conn, $e ); $result = false; } $this->logRequest( $op, implode( ',', $batchKeys ), $server, $e ); } $this->updateOpStats( self::METRIC_OP_SET, $valueSizesByKey ); return $result; } protected function doDeleteMulti( array $keys, $flags = 0 ) { [ $keysByServer, $connByServer, $result ] = $this->getConnectionsForKeys( $keys ); foreach ( $keysByServer as $server => $batchKeys ) { $conn = $connByServer[$server]; $e = null; try { // Avoid delete() with array to reduce CPU hogging from a single request $conn->multi( Redis::PIPELINE ); foreach ( $batchKeys as $key ) { $conn->del( $key ); } $batchResult = $conn->exec(); if ( $batchResult === false ) { $result = false; $this->logRequest( 'delete', implode( ',', $batchKeys ), $server, true ); continue; } // Note that redis does not return false if the key was not there $result = $result && !in_array( false, $batchResult, true ); } catch ( RedisException $e ) { $this->handleException( $conn, $e ); $result = false; } $this->logRequest( 'delete', implode( ',', $batchKeys ), $server, $e ); } $this->updateOpStats( self::METRIC_OP_DELETE, array_values( $keys ) ); return $result; } public function doChangeTTLMulti( array $keys, $exptime, $flags = 0 ) { $relative = $this->isRelativeExpiration( $exptime ); $op = ( $exptime == self::TTL_INDEFINITE ) ? 'persist' : ( $relative ? 'expire' : 'expireAt' ); [ $keysByServer, $connByServer, $result ] = $this->getConnectionsForKeys( $keys ); foreach ( $keysByServer as $server => $batchKeys ) { $conn = $connByServer[$server]; $e = null; try { $conn->multi( Redis::PIPELINE ); foreach ( $batchKeys as $key ) { if ( $exptime == self::TTL_INDEFINITE ) { $conn->persist( $key ); } elseif ( $relative ) { $conn->expire( $key, $this->getExpirationAsTTL( $exptime ) ); } else { $conn->expireAt( $key, $this->getExpirationAsTimestamp( $exptime ) ); } } $batchResult = $conn->exec(); if ( $batchResult === false ) { $result = false; $this->logRequest( $op, implode( ',', $batchKeys ), $server, true ); continue; } $result = in_array( false, $batchResult, true ) ? false : $result; } catch ( RedisException $e ) { $this->handleException( $conn, $e ); $result = false; } $this->logRequest( $op, implode( ',', $batchKeys ), $server, $e ); } $this->updateOpStats( self::METRIC_OP_CHANGE_TTL, array_values( $keys ) ); return $result; } protected function doAdd( $key, $value, $exptime = 0, $flags = 0 ) { $conn = $this->getConnection( $key ); if ( !$conn ) { return false; } $ttl = $this->getExpirationAsTTL( $exptime ); $serialized = $this->getSerialized( $value, $key ); $valueSize = strlen( $serialized ); try { $result = $conn->set( $key, $serialized, $ttl ? [ 'nx', 'ex' => $ttl ] : [ 'nx' ] ); } catch ( RedisException $e ) { $result = false; $this->handleException( $conn, $e ); } $this->logRequest( 'add', $key, $conn->getServer(), $result ); $this->updateOpStats( self::METRIC_OP_ADD, [ $key => [ $valueSize, 0 ] ] ); return $result; } protected function doIncrWithInit( $key, $exptime, $step, $init, $flags ) { $conn = $this->getConnection( $key ); if ( !$conn ) { return false; } $ttl = $this->getExpirationAsTTL( $exptime ); try { static $script = /** @lang Lua */ <<<LUA local key = KEYS[1] local ttl, step, init = unpack( ARGV ) if redis.call( 'exists', key ) == 1 then return redis.call( 'incrBy', key, step ) end if 1 * ttl ~= 0 then redis.call( 'setex', key, ttl, init ) else redis.call( 'set', key, init ) end return 1 * init LUA; $result = $conn->luaEval( $script, [ $key, $ttl, $step, $init ], 1 ); } catch ( RedisException $e ) { $result = false; $this->handleException( $conn, $e ); } $this->logRequest( 'incrWithInit', $key, $conn->getServer(), $result ); return $result; } protected function doChangeTTL( $key, $exptime, $flags ) { $conn = $this->getConnection( $key ); if ( !$conn ) { return false; } $relative = $this->isRelativeExpiration( $exptime ); try { if ( $exptime == self::TTL_INDEFINITE ) { $result = $conn->persist( $key ); $this->logRequest( 'persist', $key, $conn->getServer(), $result ); } elseif ( $relative ) { $result = $conn->expire( $key, $this->getExpirationAsTTL( $exptime ) ); $this->logRequest( 'expire', $key, $conn->getServer(), $result ); } else { $result = $conn->expireAt( $key, $this->getExpirationAsTimestamp( $exptime ) ); $this->logRequest( 'expireAt', $key, $conn->getServer(), $result ); } } catch ( RedisException $e ) { $result = false; $this->handleException( $conn, $e ); } $this->updateOpStats( self::METRIC_OP_CHANGE_TTL, [ $key ] ); return $result; } /** * @param string[] $keys * * @return array ((server => redis handle wrapper), (server => key batch), success) * @phan-return array{0:array<string,string[]>,1:array<string,RedisConnRef|Redis>,2:bool} */ protected function getConnectionsForKeys( array $keys ) { $keysByServer = []; $connByServer = []; $success = true; foreach ( $keys as $key ) { $candidateTags = $this->getCandidateServerTagsForKey( $key ); $conn = null; // Find a suitable server for this key... // phpcs:ignore Generic.CodeAnalysis.AssignmentInCondition.FoundInWhileCondition while ( ( $tag = array_shift( $candidateTags ) ) !== null ) { $server = $this->serverTagMap[$tag]; // Reuse connection handles for keys mapping to the same server if ( isset( $connByServer[$server] ) ) { $conn = $connByServer[$server]; } else { $conn = $this->redisPool->getConnection( $server, $this->logger ); if ( !$conn ) { continue; } // If automatic failover is enabled, check that the server's link // to its master (if any) is up -- but only if there are other // viable candidates left to consider. Also, getMasterLinkStatus() // does not work with twemproxy, though $candidates will be empty // by now in such cases. if ( $this->automaticFailover && $candidateTags ) { try { /** @var string[] $info */ $info = $conn->info(); if ( ( $info['master_link_status'] ?? null ) === 'down' ) { // If the master cannot be reached, fail-over to the next server. // If masters are in data-center A, and replica DBs in data-center B, // this helps avoid the case were fail-over happens in A but not // to the corresponding server in B (e.g. read/write mismatch). continue; } } catch ( RedisException $e ) { // Server is not accepting commands $this->redisPool->handleError( $conn, $e ); continue; } } // Use this connection handle $connByServer[$server] = $conn; } // Use this server for this key $keysByServer[$server][] = $key; break; } if ( !$conn ) { // No suitable server found for this key $success = false; $this->setLastError( BagOStuff::ERR_UNREACHABLE ); } } return [ $keysByServer, $connByServer, $success ]; } /** * @param string $key * * @return RedisConnRef|Redis|null Redis handle wrapper for the key or null on failure */ protected function getConnection( $key ) { [ , $connByServer ] = $this->getConnectionsForKeys( [ $key ] ); return reset( $connByServer ) ?: null; } private function getCandidateServerTagsForKey( string $key ): array { $candidates = array_keys( $this->serverTagMap ); if ( count( $this->servers ) > 1 ) { ArrayUtils::consistentHashSort( $candidates, $key, '/' ); if ( !$this->automaticFailover ) { $candidates = array_slice( $candidates, 0, 1 ); } } return $candidates; } /** * Log a fatal error * * @param string $msg */ protected function logError( $msg ) { $this->logger->error( "Redis error: $msg" ); } /** * The redis extension throws an exception in response to various read, write * and protocol errors. Sometimes it also closes the connection, sometimes * not. The safest response for us is to explicitly destroy the connection * object and let it be reopened during the next request. * * @param RedisConnRef $conn * @param RedisException $e */ protected function handleException( RedisConnRef $conn, RedisException $e ) { $this->setLastError( BagOStuff::ERR_UNEXPECTED ); $this->redisPool->handleError( $conn, $e ); } /** * Send information about a single request to the debug log * * @param string $op * @param string $keys * @param string $server * @param Exception|bool|null $e */ public function logRequest( $op, $keys, $server, $e = null ) { $this->debug( "$op($keys) on $server: " . ( $e ? "failure" : "success" ) ); } } /** @deprecated class alias since 1.43 */ class_alias( RedisBagOStuff::class, 'RedisBagOStuff' ); PK ! � � � objectcache/APCUBagOStuff.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\ObjectCache; /** * Store data in the local server memory via APCu (php-apcu) * * Past issues of note: * - Memory corruption when `apc.serializer=default` in INI: * https://phabricator.wikimedia.org/T120267 * - We used to recommend `apc.serializer=php` as non-default setting, and if not set, * applied serialize() manually to workaround bugs and to create values we can use * as CAS tokens. Upstream defaults to serializer=php since php-apcu 5.1.15 (2018). * https://gerrit.wikimedia.org/r/671634 * * @see https://www.php.net/apcu * @ingroup Cache */ class APCUBagOStuff extends MediumSpecificBagOStuff { /** * @var string String to append to each APC key. This may be changed * whenever the handling of values is changed, to prevent existing code * from encountering older values which it cannot handle. */ private const KEY_SUFFIX = ':5'; /** @var int Max attempts for implicit CAS operations */ private static $CAS_MAX_ATTEMPTS = 100; public function __construct( array $params = [] ) { // No use in segmenting values $params['segmentationSize'] = INF; parent::__construct( $params ); // Versions of apcu < 5.1.19 use apc.use_request_time=1 by default, causing new keys // to be assigned timestamps based on the start of the PHP request/script. The longer // the request has been running, the more likely that newly stored keys will instantly // be seen as expired by other requests. Disable apc.use_request_time. ini_set( 'apc.use_request_time', '0' ); if ( PHP_SAPI === 'cli' ) { $this->attrMap[self::ATTR_DURABILITY] = ini_get( 'apc.enable_cli' ) ? self::QOS_DURABILITY_SCRIPT : self::QOS_DURABILITY_NONE; } else { $this->attrMap[self::ATTR_DURABILITY] = self::QOS_DURABILITY_SERVICE; } } protected function doGet( $key, $flags = 0, &$casToken = null ) { $getToken = ( $casToken === self::PASS_BY_REF ); $casToken = null; $value = apcu_fetch( $key . self::KEY_SUFFIX ); if ( $getToken && $value !== false ) { // Note that if the driver handles serialization then this uses the PHP value // as the token. This might require inspection or re-serialization in doCas(). $casToken = $value; } return $value; } protected function doSet( $key, $value, $exptime = 0, $flags = 0 ) { $ttl = $this->getExpirationAsTTL( $exptime ); return apcu_store( $key . self::KEY_SUFFIX, $value, $ttl ); } protected function doAdd( $key, $value, $exptime = 0, $flags = 0 ) { if ( apcu_exists( $key . self::KEY_SUFFIX ) ) { // Avoid global write locks for high contention keys return false; } $ttl = $this->getExpirationAsTTL( $exptime ); return apcu_add( $key . self::KEY_SUFFIX, $value, $ttl ); } protected function doDelete( $key, $flags = 0 ) { apcu_delete( $key . self::KEY_SUFFIX ); return true; } protected function doIncrWithInit( $key, $exptime, $step, $init, $flags ) { // Use apcu 5.1.12 $ttl argument if apcu_inc() will initialize to $init: // https://www.php.net/manual/en/function.apcu-inc.php if ( $step === $init ) { /** @noinspection PhpMethodParametersCountMismatchInspection */ $ttl = $this->getExpirationAsTTL( $exptime ); $result = apcu_inc( $key . self::KEY_SUFFIX, $step, $success, $ttl ); } else { $result = false; for ( $i = 0; $i < self::$CAS_MAX_ATTEMPTS; ++$i ) { $oldCount = apcu_fetch( $key . self::KEY_SUFFIX ); if ( $oldCount === false ) { $count = $init; $ttl = $this->getExpirationAsTTL( $exptime ); if ( apcu_add( $key . self::KEY_SUFFIX, $count, $ttl ) ) { $result = $count; break; } } elseif ( is_int( $oldCount ) ) { $count = $oldCount + $step; if ( apcu_cas( $key . self::KEY_SUFFIX, $oldCount, $count ) ) { $result = $count; break; } } else { break; } } } return $result; } } /** @deprecated class alias since 1.43 */ class_alias( APCUBagOStuff::class, 'APCUBagOStuff' ); PK ! �!m�Jq Jq objectcache/BagOStuff.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ /** * @defgroup Cache BagOStuff * * Most important classes are: * * @see ObjectCacheFactory * @see WANObjectCache * @see BagOStuff */ namespace Wikimedia\ObjectCache; use InvalidArgumentException; use Psr\Log\LoggerAwareInterface; use Psr\Log\LoggerInterface; use Psr\Log\NullLogger; use Wikimedia\LightweightObjectStore\ExpirationAwareness; use Wikimedia\LightweightObjectStore\StorageAwareness; use Wikimedia\ScopedCallback; use Wikimedia\Stats\StatsFactory; /** * Abstract class for any ephemeral data store * * Class instances should be created with an intended access scope for the dataset, such as: * - a) A single PHP thread on a server (e.g. stored in a PHP variable) * - b) A single application server (e.g. stored in php-apcu or sqlite) * - c) All application servers in datacenter (e.g. stored in memcached or mysql) * - d) All application servers in all datacenters (e.g. stored via mcrouter or dynomite) * * Callers should use the proper factory methods that yield BagOStuff instances. Site admins * should make sure that the configuration for those factory methods match their access scope. * BagOStuff subclasses have widely varying levels of support replication features within and * among datacenters. * * Subclasses should override the default "segmentationSize" field with an appropriate value. * The value should not be larger than what the backing store (by default) supports. It also * should be roughly informed by common performance bottlenecks (e.g. values over a certain size * having poor scalability). The same goes for the "segmentedValueMaxSize" member, which limits * the maximum size and chunk count (indirectly) of values. * * A few notes about data consistency for BagOStuff instances: * - Read operation methods, e.g. get(), should be synchronous in the local datacenter. * When used with READ_LATEST, such operations should reflect any prior writes originating * from the local datacenter (e.g. by avoiding replica DBs or invoking quorom reads). * - Write operation methods, e.g. set(), should be synchronous in the local datacenter, with * asynchronous cross-datacenter replication. This replication can be either "best effort" * or eventually consistent. If the write succeeded, then any subsequent `get()` operations with * READ_LATEST, regardless of datacenter, should reflect the changes. * - Locking operation methods, e.g. lock(), unlock(), and getScopedLock(), should only apply * to the local datacenter. * - Any set of single-key write operation method calls originating from a single datacenter * should observe "best effort" linearizability. * In this context, "best effort" means that consistency holds as long as connectivity is * strong, network latency is low, and there are no relevant storage server failures. * Per https://en.wikipedia.org/wiki/PACELC_theorem, the store should act as a PA/EL * distributed system for these operations. * * @stable to extend * @newable * @ingroup Cache * @copyright 2003-2004 Brooke Vibber <bvibber@wikimedia.org> */ abstract class BagOStuff implements ExpirationAwareness, StorageAwareness, IStoreKeyEncoder, LoggerAwareInterface { /** @var StatsFactory */ protected $stats; /** @var LoggerInterface */ protected $logger; /** @var callable|null */ protected $asyncHandler; /** @var int[] Map of (BagOStuff:ATTR_* constant => BagOStuff:QOS_* constant) */ protected $attrMap = []; /** @var string Default keyspace; used by makeKey() */ protected $keyspace; /** @var int BagOStuff:ERR_* constant of the last error that occurred */ protected $lastError = self::ERR_NONE; /** @var int Error event sequence number of the last error that occurred */ protected $lastErrorId = 0; /** @var int Next sequence number to use for watch/error events */ protected static $nextErrorMonitorId = 1; /** @var float|null */ private $wallClockOverride; /** Bitfield constants for get()/getMulti(); these are only advisory */ /** If supported, avoid reading stale data due to replication */ public const READ_LATEST = 1; /** Promise that the caller handles detection of staleness */ public const READ_VERIFIED = 2; /** Bitfield constants for set()/merge(); these are only advisory */ /** Only change state of the in-memory cache */ public const WRITE_CACHE_ONLY = 8; /** Allow partitioning of the value if it is a large string */ public const WRITE_ALLOW_SEGMENTS = 16; /** * Delete all the segments if the value is partitioned * @deprecated since 1.43 Use WRITE_ALLOW_SEGMENTS instead. */ public const WRITE_PRUNE_SEGMENTS = self::WRITE_ALLOW_SEGMENTS; /** * If supported, do not block on write operation completion; instead, treat writes as * succesful based on whether they could be buffered. When using this flag with methods * that yield item values, the boolean "true" will be used as a placeholder. The next * blocking operation (e.g. typical read) will trigger a flush of the operation buffer. */ public const WRITE_BACKGROUND = 64; /** Abort after the first merge conflict */ public const MAX_CONFLICTS_ONE = 1; /** @var string Global keyspace; used by makeGlobalKey() */ protected const GLOBAL_KEYSPACE = 'global'; /** @var string Precomputed global cache key prefix (needs no encoding) */ protected const GLOBAL_PREFIX = 'global:'; /** @var int Item is a single cache key */ protected const ARG0_KEY = 0; /** @var int Item is an array of cache keys */ protected const ARG0_KEYARR = 1; /** @var int Item is an array indexed by cache keys */ protected const ARG0_KEYMAP = 2; /** @var int Item does not involve any keys */ protected const ARG0_NONKEY = 3; /** @var int Item is an array indexed by cache keys */ protected const RES_KEYMAP = 0; /** @var int Item does not involve any keys */ protected const RES_NONKEY = 1; /** * @stable to call * * @param array $params Parameters include: * - keyspace: Keyspace to use for keys in makeKey(). [Default: "local"] * - asyncHandler: Callable to use for scheduling tasks after the web request ends. * In CLI mode, it should run the task immediately. [Default: null] * - stats: IStatsdDataFactory instance. [optional] * - logger: \Psr\Log\LoggerInterface instance. [optional] * * @phan-param array{keyspace?:string,logger?:\Psr\Log\LoggerInterface,asyncHandler?:callable} $params */ public function __construct( array $params = [] ) { $this->keyspace = $params['keyspace'] ?? 'local'; $this->stats = $params['stats'] ?? StatsFactory::newNull(); $this->setLogger( $params['logger'] ?? new NullLogger() ); $asyncHandler = $params['asyncHandler'] ?? null; if ( is_callable( $asyncHandler ) ) { $this->asyncHandler = $asyncHandler; } } /** * @param LoggerInterface $logger * * @return void */ public function setLogger( LoggerInterface $logger ) { $this->logger = $logger; } /** * @since 1.35 * @return LoggerInterface */ public function getLogger(): LoggerInterface { return $this->logger; } /** * Get an item, regenerating and setting it if not found * * The callback can take $exptime as argument by reference and modify it. * Nothing is stored nor deleted if the callback returns false. * * @param string $key * @param int $exptime Time-to-live (seconds) * @param callable $callback Callback that derives the new value * @param int $flags Bitfield of BagOStuff::READ_* or BagOStuff::WRITE_* constants [optional] * * @return mixed The cached value if found or the result of $callback otherwise * @since 1.27 */ final public function getWithSetCallback( $key, $exptime, $callback, $flags = 0 ) { $value = $this->get( $key, $flags ); if ( $value === false ) { $value = $callback( $exptime ); if ( $value !== false && $exptime >= 0 ) { $this->set( $key, $value, $exptime, $flags ); } } return $value; } /** * Get an item * * If the key includes a deterministic input hash (e.g. the key can only have * the correct value) or complete staleness checks are handled by the caller * (e.g. nothing relies on the TTL), then the READ_VERIFIED flag should be set. * This lets tiered backends know they can safely upgrade a cached value to * higher tiers using standard TTLs. * * @param string $key * @param int $flags Bitfield of BagOStuff::READ_* constants [optional] * * @return mixed Returns false on failure or if the item does not exist */ abstract public function get( $key, $flags = 0 ); /** * Set an item * * @param string $key * @param mixed $value * @param int $exptime Either an interval in seconds or a unix timestamp for expiry * @param int $flags Bitfield of BagOStuff::WRITE_* constants * If setting WRITE_ALLOW_SEGMENTS, remember to also set it in any delete() calls. * @return bool Success */ abstract public function set( $key, $value, $exptime = 0, $flags = 0 ); /** * Delete an item if it exists * * For large values set with WRITE_ALLOW_SEGMENTS, this only deletes the placeholder * key with the segment list. To delete the underlying blobs, include WRITE_ALLOW_SEGMENTS * in the flags for delete() as well. While deleting the segment list key has the effect of * functionally deleting the key, it leaves unused blobs in storage. * * The reason that this is not done automatically, is that to delete underlying blobs, * requires first fetching the current segment list. Given that 99% of keys don't use * WRITE_ALLOW_SEGMENTS, this would be wasteful. * * @param string $key * @param int $flags Bitfield of BagOStuff::WRITE_* constants * @return bool Success (item deleted or not found) */ abstract public function delete( $key, $flags = 0 ); /** * Insert an item if it does not already exist * * @param string $key * @param mixed $value * @param int $exptime * @param int $flags Bitfield of BagOStuff::WRITE_* constants (since 1.33) * * @return bool Success (item created) */ abstract public function add( $key, $value, $exptime = 0, $flags = 0 ); /** * Merge changes into the existing cache value (possibly creating a new one) * * The callback function returns the new value given the current value * (which will be false if not present), and takes the arguments: * (this BagOStuff, cache key, current value, TTL). * The TTL parameter is reference set to $exptime. It can be overridden in the callback. * Nothing is stored nor deleted if the callback returns false. * * @param string $key * @param callable $callback Callback method to be executed * @param int $exptime Either an interval in seconds or a unix timestamp for expiry * @param int $attempts The amount of times to attempt a merge in case of failure * @param int $flags Bitfield of BagOStuff::WRITE_* constants * * @return bool Success */ abstract public function merge( $key, callable $callback, $exptime = 0, $attempts = 10, $flags = 0 ); /** * Change the expiration on an item * * If an expiry in the past is given then the key will immediately be expired * * For large values written using WRITE_ALLOW_SEGMENTS, this only changes the TTL of the * main segment list key. While lowering the TTL of the segment list key has the effect of * functionally lowering the TTL of the key, it might leave unused blobs in cache for longer. * Raising the TTL of such keys is not effective, since the expiration of a single segment * key effectively expires the entire value. * * @param string $key * @param int $exptime TTL or UNIX timestamp * @param int $flags Bitfield of BagOStuff::WRITE_* constants (since 1.33) * * @return bool Success (item found and updated) * @since 1.28 */ abstract public function changeTTL( $key, $exptime = 0, $flags = 0 ); /** * Acquire an advisory lock on a key string, exclusive to the caller * * @param string $key * @param int $timeout Lock wait timeout; 0 for non-blocking [optional] * @param int $exptime Lock time-to-live in seconds; 1 day maximum [optional] * @param string $rclass If this thread already holds the lock, and the lock was acquired * using the same value for this parameter, then return true and use reference counting so * that only the unlock() call from the outermost lock() caller actually releases the lock * (note that only the outermost time-to-live is used) [optional] * * @return bool Success */ abstract public function lock( $key, $timeout = 6, $exptime = 6, $rclass = '' ); /** * Release an advisory lock on a key string * * @param string $key * * @return bool Success */ abstract public function unlock( $key ); /** * Get a lightweight exclusive self-unlocking lock * * Note that the same lock cannot be acquired twice. * * This is useful for task de-duplication or to avoid obtrusive * (though non-corrupting) DB errors like INSERT key conflicts * or deadlocks when using LOCK IN SHARE MODE. * * @param string $key * @param int $timeout Lock wait timeout; 0 for non-blocking [optional] * @param int $exptime Lock time-to-live [optional]; 1 day maximum * @param string $rclass Allow reentry if set and the current lock used this value * * @return ScopedCallback|null Returns null on failure * @since 1.26 */ final public function getScopedLock( $key, $timeout = 6, $exptime = 30, $rclass = '' ) { $exptime = min( $exptime ?: INF, self::TTL_DAY ); if ( !$this->lock( $key, $timeout, $exptime, $rclass ) ) { return null; } return new ScopedCallback( function () use ( $key ) { $this->unlock( $key ); } ); } /** * Delete all objects expiring before a certain date * * @param string|int $timestamp The reference date in MW or TS_UNIX format * @param callable|null $progress Optional, a function which will be called * regularly during long-running operations with the percentage progress * as the first parameter. [optional] * @param int|float $limit Maximum number of keys to delete [default: INF] * @param string|null $tag Tag to purge a single shard only. * This is only supported when server tags are used in configuration. * * @return bool Success; false if unimplemented */ abstract public function deleteObjectsExpiringBefore( $timestamp, ?callable $progress = null, $limit = INF, ?string $tag = null ); /** * Get a batch of items * * @param string[] $keys List of keys * @param int $flags Bitfield; supports READ_LATEST [optional] * * @return mixed[] Map of (key => value) for existing keys */ abstract public function getMulti( array $keys, $flags = 0 ); /** * Set a batch of items * * This does not support WRITE_ALLOW_SEGMENTS to avoid excessive read I/O * * WRITE_BACKGROUND can be used for bulk insertion where the response is not vital * * @param mixed[] $valueByKey Map of (key => value) * @param int $exptime Either an interval in seconds or a unix timestamp for expiry * @param int $flags Bitfield of BagOStuff::WRITE_* constants (since 1.33) * * @return bool Success * @since 1.24 */ abstract public function setMulti( array $valueByKey, $exptime = 0, $flags = 0 ); /** * Delete a batch of items * * This does not support WRITE_ALLOW_SEGMENTS to avoid excessive read I/O * * WRITE_BACKGROUND can be used for bulk deletion where the response is not vital * * @param string[] $keys List of keys * @param int $flags Bitfield of BagOStuff::WRITE_* constants * @return bool Success (items deleted and/or not found) * @since 1.33 */ abstract public function deleteMulti( array $keys, $flags = 0 ); /** * Change the expiration of multiple items * * @see BagOStuff::changeTTL() * * @param string[] $keys List of keys * @param int $exptime TTL or UNIX timestamp * @param int $flags Bitfield of BagOStuff::WRITE_* constants (since 1.33) * * @return bool Success (all items found and updated) * @since 1.34 */ abstract public function changeTTLMulti( array $keys, $exptime, $flags = 0 ); /** * Increase the value of the given key (no TTL change) if it exists or create it otherwise * * This will create the key with the value $init and TTL $exptime instead if not present. * Callers should make sure that both ($init - $step) and $exptime are invariants for all * operations to any given key. The value of $init should be at least that of $step. * * The new value is returned, except if the WRITE_BACKGROUND flag is given, in which case * the handler may choose to return true to indicate that the operation has been dispatched. * * @param string $key Key built via makeKey() or makeGlobalKey() * @param int $exptime Time-to-live (in seconds) or a UNIX timestamp expiration * @param int $step Amount to increase the key value by [default: 1] * @param int|null $init Value to initialize the key to if it does not exist [default: $step] * @param int $flags Bit field of class WRITE_* constants [optional] * * @return int|bool New value (or true if asynchronous) on success; false on failure * @since 1.24 */ abstract public function incrWithInit( $key, $exptime, $step = 1, $init = null, $flags = 0 ); /** * Get a "watch point" token that can be used to get the "last error" to occur after now * * @return int A token to that can be used with getLastError() * @since 1.38 */ public function watchErrors() { return self::$nextErrorMonitorId++; } /** * Get the "last error" registry * * The method should be invoked by a caller as part of the following pattern: * - The caller invokes watchErrors() to get a "since token" * - The caller invokes a sequence of cache operation methods * - The caller invokes getLastError() with the "since token" * * External callers can also invoke this method as part of the following pattern: * - The caller invokes clearLastError() * - The caller invokes a sequence of cache operation methods * - The caller invokes getLastError() * * @param int $watchPoint Only consider errors from after this "watch point" [optional] * * @return int BagOStuff:ERR_* constant for the "last error" registry * @note Parameters added in 1.38: $watchPoint * @since 1.23 */ public function getLastError( $watchPoint = 0 ) { return ( $this->lastErrorId > $watchPoint ) ? $this->lastError : self::ERR_NONE; } /** * Clear the "last error" registry * * @since 1.23 * @deprecated Since 1.38, hard deprecated in 1.43 */ public function clearLastError() { wfDeprecated( __METHOD__, '1.38' ); $this->lastError = self::ERR_NONE; } /** * Set the "last error" registry due to a problem encountered during an attempted operation * * @param int $error BagOStuff:ERR_* constant * * @since 1.23 */ protected function setLastError( $error ) { $this->lastError = $error; $this->lastErrorId = self::$nextErrorMonitorId++; } /** * Make a cache key from the given components, in the "global" keyspace * * Global keys are shared with and visible to all sites hosted in the same * infrastructure (e.g. cross-wiki within the same wiki farm). Others sites * may read the stored value from their requests, and they must be able to * correctly compute new values from their own request context. * * @see BagOStuff::makeKeyInternal * @since 1.27 * * @param string $keygroup Key group component, should be under 48 characters. * @param string|int ...$components Additional, ordered, key components for entity IDs * * @return string Colon-separated, keyspace-prepended, ordered list of encoded components */ public function makeGlobalKey( $keygroup, ...$components ) { return $this->makeKeyInternal( self::GLOBAL_KEYSPACE, func_get_args() ); } /** * Make a cache key from the given components, in the default keyspace * * The default keyspace is unique to a given site. Subsequent web requests * to the same site (e.g. local wiki, or same domain name) will interact * with the same keyspace. * * Requests to other sites hosted on the same infrastructure (e.g. cross-wiki * or cross-domain), have their own keyspace that naturally avoids conflicts. * * As caller you are responsible for: * - Limit the key group (first component) to 48 characters * * Internally, the colon is used as delimiter (":"), and this is * automatically escaped in supplied components to avoid ambiguity or * key conflicts. BagOStuff subclasses are responsible for applying any * additional escaping or limits as-needed before sending commands over * the network. * * @see BagOStuff::makeKeyInternal * @since 1.27 * * @param string $keygroup Key group component, should be under 48 characters. * @param string|int ...$components Additional, ordered, key components for entity IDs * * @return string Colon-separated, keyspace-prepended, ordered list of encoded components */ public function makeKey( $keygroup, ...$components ) { return $this->makeKeyInternal( $this->keyspace, func_get_args() ); } /** * Check whether a cache key is in the global keyspace * * @param string $key * * @return bool * @since 1.35 */ public function isKeyGlobal( $key ) { return str_starts_with( $key, self::GLOBAL_PREFIX ); } /** * @param int $flag BagOStuff::ATTR_* constant * * @return int BagOStuff:QOS_* constant * @since 1.28 */ public function getQoS( $flag ) { return $this->attrMap[$flag] ?? self::QOS_UNKNOWN; } /** * @deprecated since 1.43, not used anywhere. * @return int|float The chunk size, in bytes, of segmented objects (INF for no limit) * @since 1.34 */ public function getSegmentationSize() { wfDeprecated( __METHOD__, '1.43' ); return INF; } /** * @deprecated since 1.43, not used anywhere. * @return int|float Maximum total segmented object size in bytes (INF for no limit) * @since 1.34 */ public function getSegmentedValueMaxSize() { wfDeprecated( __METHOD__, '1.43' ); return INF; } /** * @param int $field * @param int $flags * * @return bool * @since 1.34 */ final protected function fieldHasFlags( $field, $flags ) { return ( ( $field & $flags ) === $flags ); } /** * Merge the flag maps of one or more BagOStuff objects into a "lowest common denominator" map * * @param BagOStuff[] $bags * * @return int[] Resulting flag map (class ATTR_* constant => class QOS_* constant) */ final protected function mergeFlagMaps( array $bags ) { $map = []; foreach ( $bags as $bag ) { foreach ( $bag->attrMap as $attr => $rank ) { if ( isset( $map[$attr] ) ) { $map[$attr] = min( $map[$attr], $rank ); } else { $map[$attr] = $rank; } } } return $map; } /** * Make a cache key for the given keyspace and components * * Subclasses may override this method in order to apply different escaping, * or to deal with size constraints (such as MemcachedBagOStuff). For example * by converting long components into hashes. * * If you override this method, you MUST override ::requireConvertGenericKey() * to return true. This ensures that wrapping classes (e.g. MultiWriteBagOStuff) * know to re-encode keys before calling read/write methods. See also ::proxyCall(). * * @see BagOStuff::proxyCall * @since 1.27 * * @param string $keyspace * @param string[]|int[] $components Key group and other components * * @return string */ protected function makeKeyInternal( $keyspace, $components ) { if ( count( $components ) < 1 ) { throw new InvalidArgumentException( "Missing key group" ); } $key = $keyspace; foreach ( $components as $component ) { // Escape delimiter (":") and escape ("%") characters $key .= ':' . strtr( $component, [ '%' => '%25', ':' => '%3A' ] ); } return $key; } /** * Whether ::proxyCall() must re-encode cache keys before calling read/write methods. * * @stable to override * @see BagOStuff::makeKeyInternal * @see BagOStuff::proxyCall * @since 1.41 * @return bool */ protected function requireConvertGenericKey(): bool { return false; } /** * Convert a key from BagOStuff::makeKeyInternal into one for the current subclass * * @see BagOStuff::proxyCall * * @param string $key Result from BagOStuff::makeKeyInternal * * @return string Result from current subclass override of BagOStuff::makeKeyInternal */ private function convertGenericKey( $key ) { if ( !$this->requireConvertGenericKey() ) { // If subclass doesn't overwrite makeKeyInternal, no re-encoding is needed. return $key; } // Extract the components from a "generic" key formatted by BagOStuff::makeKeyInternal() // Note that the order of each corresponding search/replace pair matters! $components = str_replace( [ '%3A', '%25' ], [ ':', '%' ], explode( ':', $key ) ); if ( count( $components ) < 2 ) { // Legacy key, not even formatted by makeKey()/makeGlobalKey(). Keep as-is. return $key; } $keyspace = array_shift( $components ); return $this->makeKeyInternal( $keyspace, $components ); } /** * Call a method on behalf of wrapper BagOStuff instance * * The "wrapper" BagOStuff subclass that calls proxyCall() MUST NOT override * the default makeKeyInternal() implementation, because proxyCall() needs * to turn the "generic" key back into an array, and re-format it according * to the backend-specific BagOStuff::makeKey implementation. * * For example, when using MultiWriteBagOStuff with Memcached as a backend, * writes will go via MemcachedBagOStuff::proxyCall(), which then reformats * the "generic" result of BagOStuff::makeKey (called as MultiWriteBagOStuff::makeKey) * using MemcachedBagOStuff::makeKeyInternal. * * @param string $method Name of a non-final public method that reads/changes keys * @param int $arg0Sig BagOStuff::ARG0_* constant describing argument 0 * @param int $resSig BagOStuff::RES_* constant describing the return value * @param array $genericArgs Method arguments passed to the wrapper instance * @param BagOStuff $wrapper The wrapper BagOStuff instance using this result * * @return mixed Method result with any keys remapped to "generic" keys */ protected function proxyCall( string $method, int $arg0Sig, int $resSig, array $genericArgs, BagOStuff $wrapper ) { // Get the corresponding store-specific cache keys... $storeArgs = $genericArgs; switch ( $arg0Sig ) { case self::ARG0_KEY: $storeArgs[0] = $this->convertGenericKey( $genericArgs[0] ); break; case self::ARG0_KEYARR: foreach ( $genericArgs[0] as $i => $genericKey ) { $storeArgs[0][$i] = $this->convertGenericKey( $genericKey ); } break; case self::ARG0_KEYMAP: $storeArgs[0] = []; foreach ( $genericArgs[0] as $genericKey => $v ) { $storeArgs[0][$this->convertGenericKey( $genericKey )] = $v; } break; } // Result of invoking the method with the corresponding store-specific cache keys $watchPoint = $this->watchErrors(); $storeRes = $this->$method( ...$storeArgs ); $lastError = $this->getLastError( $watchPoint ); if ( $lastError !== self::ERR_NONE ) { $wrapper->setLastError( $lastError ); } // Convert any store-specific cache keys in the result back to generic cache keys if ( $resSig === self::RES_KEYMAP ) { // Map of (store-specific cache key => generic cache key) $genericKeyByStoreKey = array_combine( $storeArgs[0], $genericArgs[0] ); $genericRes = []; foreach ( $storeRes as $storeKey => $value ) { $genericRes[$genericKeyByStoreKey[$storeKey]] = $value; } } else { $genericRes = $storeRes; } return $genericRes; } /** * @internal For testing only * @return float UNIX timestamp * @codeCoverageIgnore */ public function getCurrentTime() { return $this->wallClockOverride ?: microtime( true ); } /** * @internal For testing only * * @param float|null &$time Mock UNIX timestamp * * @codeCoverageIgnore */ public function setMockTime( &$time ) { $this->wallClockOverride =& $time; } } /** @deprecated class alias since 1.43 */ class_alias( BagOStuff::class, 'BagOStuff' ); PK ! A�8�A� A� % objectcache/utils/MemcachedClient.phpnu �Iw�� <?php // phpcs:ignoreFile -- It's an external lib and it isn't. Let's not bother. /** * Memcached client for PHP. * * +---------------------------------------------------------------------------+ * | memcached client, PHP | * +---------------------------------------------------------------------------+ * | Copyright (c) 2003 Ryan T. Dean <rtdean@cytherianage.net> | * | All rights reserved. | * | | * | Redistribution and use in source and binary forms, with or without | * | modification, are permitted provided that the following conditions | * | are met: | * | | * | 1. Redistributions of source code must retain the above copyright | * | notice, this list of conditions and the following disclaimer. | * | 2. Redistributions in binary form must reproduce the above copyright | * | notice, this list of conditions and the following disclaimer in the | * | documentation and/or other materials provided with the distribution. | * | | * | THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR | * | IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES | * | OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. | * | IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, | * | INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT | * | NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, | * | DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY | * | THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT | * | (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF | * | THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. | * +---------------------------------------------------------------------------+ * | Author: Ryan T. Dean <rtdean@cytherianage.net> | * | Heavily influenced by the Perl memcached client by Brad Fitzpatrick. | * | Permission granted by Brad Fitzpatrick for relicense of ported Perl | * | client logic under 2-clause BSD license. | * +---------------------------------------------------------------------------+ * * @file * $TCAnet$ */ /** * This is a PHP client for memcached - a distributed memory cache daemon. * * More information is available at http://www.danga.com/memcached/ * * Usage example: * * $mc = new MemcachedClient(array( * 'servers' => array( * '127.0.0.1:10000', * array( '192.0.0.1:10010', 2 ), * '127.0.0.1:10020' * ), * 'debug' => false, * 'compress_threshold' => 10240, * 'persistent' => true * )); * * $mc->add( 'key', array( 'some', 'array' ) ); * $mc->replace( 'key', 'some random string' ); * $val = $mc->get( 'key' ); * * @author Ryan T. Dean <rtdean@cytherianage.net> * @version 0.1.2 */ use Psr\Log\LoggerInterface; use Psr\Log\NullLogger; use Wikimedia\AtEase\AtEase; use Wikimedia\IPUtils; use Wikimedia\LightweightObjectStore\StorageAwareness; /** * memcached client class implemented using (p)fsockopen() * * @author Ryan T. Dean <rtdean@cytherianage.net> * @ingroup Cache */ class MemcachedClient implements StorageAwareness { // {{{ properties // {{{ public // {{{ constants // {{{ flags /** * Flag: indicates data is serialized */ const SERIALIZED = 1; /** * Flag: indicates data is compressed */ const COMPRESSED = 2; /** * Flag: indicates data is an integer */ const INTVAL = 4; // }}} /** * Minimum savings to store data compressed */ const COMPRESSION_SAVINGS = 0.20; // }}} /** * Command statistics * * @var array * @access public */ public $stats; // }}} // {{{ private /** * Cached Sockets that are connected * * @var array * @access private */ public $_cache_sock; /** * Current debug status; 0 - none to 9 - profiling * * @var bool * @access private */ public $_debug; /** * Dead hosts, assoc array, 'host'=>'unixtime when ok to check again' * * @var array * @access private */ public $_host_dead; /** * Is compression available? * * @var bool * @access private */ public $_have_zlib; /** * Do we want to use compression? * * @var bool * @access private */ public $_compress_enable; /** * At how many bytes should we compress? * * @var int * @access private */ public $_compress_threshold; /** * Are we using persistent links? * * @var bool * @access private */ public $_persistent; /** * If only using one server; contains ip:port to connect to * * @var string * @access private */ public $_single_sock; /** * Array containing ip:port or array(ip:port, weight) * * @var array * @access private */ public $_servers; /** * Our bit buckets * * @var array * @access private */ public $_buckets; /** * Total # of bit buckets we have * * @var int * @access private */ public $_bucketcount; /** * # of total servers we have * * @var int * @access private */ public $_active; /** * Stream timeout in seconds. Applies for example to fread() * * @var int * @access private */ public $_timeout_seconds; /** * Stream timeout in microseconds * * @var int * @access private */ public $_timeout_microseconds; /** * Connect timeout in seconds */ public $_connect_timeout; /** * Number of connection attempts for each server */ public $_connect_attempts; /** @var int StorageAwareness:ERR_* constant of the last cache command */ public $_last_cmd_status = self::ERR_NONE; /** * @var LoggerInterface */ private $_logger; // }}} // }}} // {{{ methods // {{{ public functions // {{{ memcached() /** * Memcache initializer * * @param array $args Associative array of settings */ public function __construct( $args ) { $this->set_servers( $args['servers'] ?? array() ); $this->_debug = $args['debug'] ?? false; $this->stats = array(); $this->_compress_threshold = $args['compress_threshold'] ?? 0; $this->_persistent = $args['persistent'] ?? false; $this->_compress_enable = true; $this->_have_zlib = function_exists( 'gzcompress' ); $this->_cache_sock = array(); $this->_host_dead = array(); $this->_timeout_seconds = 0; $this->_timeout_microseconds = $args['timeout'] ?? 500_000; $this->_connect_timeout = $args['connect_timeout'] ?? 0.1; $this->_connect_attempts = 2; $this->_logger = $args['logger'] ?? new NullLogger(); } // }}} /** * @param mixed $value * @return string|integer */ public function serialize( $value ) { return serialize( $value ); } /** * @param string $value * @return mixed */ public function unserialize( $value ) { return unserialize( $value ); } // {{{ add() /** * Adds a key/value to the memcache server if one isn't already set with * that key * * @param string $key Key to set with data * @param mixed $val Value to store * @param int $exp (optional) Expiration time. This can be a number of seconds * to cache for (up to 30 days inclusive). Any timespans of 30 days + 1 second or * longer must be the timestamp of the time at which the mapping should expire. It * is safe to use timestamps in all cases, regardless of expiration * eg: strtotime("+3 hour") * * @return bool */ public function add( $key, $val, $exp = 0 ) { $this->_last_cmd_status = self::ERR_NONE; return $this->_set( 'add', $key, $val, $exp ); } // }}} // {{{ decr() /** * Decrease a value stored on the memcache server * * @param string $key Key to decrease * @param int $amt (optional) amount to decrease * * @return mixed False on failure, value on success */ public function decr( $key, $amt = 1 ) { $this->_last_cmd_status = self::ERR_NONE; return $this->_incrdecr( 'decr', $key, $amt ); } // }}} // {{{ delete() /** * Deletes a key from the server, optionally after $time * * @param string $key Key to delete * @param int $time (optional) how long to wait before deleting * * @return bool True on success, false on failure */ public function delete( $key, $time = 0 ) { $this->_last_cmd_status = self::ERR_NONE; if ( !$this->_active ) { return false; } $sock = $this->get_sock( $key ); if ( !$sock ) { return false; } $key = is_array( $key ) ? $key[1] : $key; if ( isset( $this->stats['delete'] ) ) { $this->stats['delete']++; } else { $this->stats['delete'] = 1; } $cmd = "delete $key $time\r\n"; if ( !$this->_fwrite( $sock, $cmd ) ) { return false; } $res = $this->_fgets( $sock ); if ( $this->_debug ) { $this->_debugprint( sprintf( "MemCache: delete %s (%s)", $key, $res ) ); } if ( $res == "DELETED" || $res == "NOT_FOUND" ) { return true; } $this->_last_cmd_status = self::ERR_UNEXPECTED; return false; } /** * Changes the TTL on a key from the server to $time * * @param string $key * @param int $time TTL in seconds * * @return bool True on success, false on failure */ public function touch( $key, $time = 0 ) { $this->_last_cmd_status = self::ERR_NONE; if ( !$this->_active ) { return false; } $sock = $this->get_sock( $key ); if ( !$sock ) { return false; } $key = is_array( $key ) ? $key[1] : $key; if ( isset( $this->stats['touch'] ) ) { $this->stats['touch']++; } else { $this->stats['touch'] = 1; } $cmd = "touch $key $time\r\n"; if ( !$this->_fwrite( $sock, $cmd ) ) { return false; } $res = $this->_fgets( $sock ); if ( $this->_debug ) { $this->_debugprint( sprintf( "MemCache: touch %s (%s)", $key, $res ) ); } if ( $res == "TOUCHED" ) { return true; } return false; } // }}} // {{{ disconnect_all() /** * Disconnects all connected sockets */ public function disconnect_all() { foreach ( $this->_cache_sock as $sock ) { fclose( $sock ); } $this->_cache_sock = array(); } // }}} // {{{ enable_compress() /** * Enable / Disable compression * * @param bool $enable True to enable, false to disable */ public function enable_compress( $enable ) { $this->_compress_enable = $enable; } // }}} // {{{ forget_dead_hosts() /** * Forget about all of the dead hosts */ public function forget_dead_hosts() { $this->_host_dead = array(); } // }}} // {{{ get() /** * Retrieves the value associated with the key from the memcache server * * @param array|string $key key to retrieve * @param float $casToken [optional] * * @return mixed */ public function get( $key, &$casToken = null ) { $getToken = ( func_num_args() >= 2 ); $this->_last_cmd_status = self::ERR_NONE; if ( $this->_debug ) { $this->_debugprint( "get($key)" ); } if ( !is_array( $key ) && strval( $key ) === '' ) { $this->_last_cmd_status = self::ERR_UNEXPECTED; $this->_debugprint( "Skipping key which equals to an empty string" ); return false; } if ( !$this->_active ) { $this->_last_cmd_status = self::ERR_UNEXPECTED; return false; } $sock = $this->get_sock( $key ); if ( !$sock ) { $this->_last_cmd_status = self::ERR_UNREACHABLE; return false; } $key = is_array( $key ) ? $key[1] : $key; if ( isset( $this->stats['get'] ) ) { $this->stats['get']++; } else { $this->stats['get'] = 1; } $cmd = $getToken ? "gets" : "get"; $cmd .= " $key\r\n"; if ( !$this->_fwrite( $sock, $cmd ) ) { $this->_last_cmd_status = self::ERR_NO_RESPONSE; return false; } $val = array(); if ( !$this->_load_items( $sock, $val, $casToken ) ) { $this->_last_cmd_status = self::ERR_NO_RESPONSE; } if ( $this->_debug ) { foreach ( $val as $k => $v ) { $this->_debugprint( sprintf( "MemCache: sock %s got %s", $this->serialize( $sock ), $k ) ); } } $value = false; if ( isset( $val[$key] ) ) { $value = $val[$key]; } return $value; } // }}} // {{{ get_multi() /** * Get multiple keys from the server(s) * * @param array $keys Keys to retrieve * * @return array */ public function get_multi( $keys ) { $this->_last_cmd_status = self::ERR_NONE; if ( !$this->_active ) { $this->_last_cmd_status = self::ERR_UNEXPECTED; return array(); } if ( isset( $this->stats['get_multi'] ) ) { $this->stats['get_multi']++; } else { $this->stats['get_multi'] = 1; } $sock_keys = array(); $socks = array(); foreach ( $keys as $key ) { $sock = $this->get_sock( $key ); if ( !$sock ) { $this->_last_cmd_status = self::ERR_UNREACHABLE; continue; } $key = is_array( $key ) ? $key[1] : $key; $sockValue = intval( $sock ); if ( !isset( $sock_keys[$sockValue] ) ) { $sock_keys[$sockValue] = array(); $socks[] = $sock; } $sock_keys[$sockValue][] = $key; } $gather = array(); // Send out the requests foreach ( $socks as $sock ) { $cmd = 'get'; foreach ( $sock_keys[intval( $sock )] as $key ) { $cmd .= ' ' . $key; } $cmd .= "\r\n"; if ( $this->_fwrite( $sock, $cmd ) ) { $gather[] = $sock; } else { $this->_last_cmd_status = self::ERR_NO_RESPONSE; } } // Parse responses $val = array(); foreach ( $gather as $sock ) { if ( !$this->_load_items( $sock, $val ) ) { $this->_last_cmd_status = self::ERR_NO_RESPONSE; } } if ( $this->_debug ) { foreach ( $val as $k => $v ) { $this->_debugprint( sprintf( "MemCache: got %s", $k ) ); } } return $val; } // }}} // {{{ incr() /** * Increments $key (optionally) by $amt * * @param string $key Key to increment * @param int $amt (optional) amount to increment * * @return int|null Null if the key does not exist yet (this does NOT * create new mappings if the key does not exist). If the key does * exist, this returns the new value for that key. */ public function incr( $key, $amt = 1 ) { return $this->_incrdecr( 'incr', $key, $amt ); } // }}} // {{{ replace() /** * Overwrites an existing value for key; only works if key is already set * * @param string $key Key to set value as * @param mixed $value Value to store * @param int $exp (optional) Expiration time. This can be a number of seconds * to cache for (up to 30 days inclusive). Any timespans of 30 days + 1 second or * longer must be the timestamp of the time at which the mapping should expire. It * is safe to use timestamps in all cases, regardless of expiration * eg: strtotime("+3 hour") * * @return bool */ public function replace( $key, $value, $exp = 0 ) { return $this->_set( 'replace', $key, $value, $exp ); } // }}} // {{{ run_command() /** * Passes through $cmd to the memcache server connected by $sock; returns * output as an array (null array if no output) * * @param Resource $sock Socket to send command on * @param string $cmd Command to run * * @return array Output array */ public function run_command( $sock, $cmd ) { if ( !$sock ) { return array(); } if ( !$this->_fwrite( $sock, $cmd ) ) { return array(); } $ret = array(); while ( true ) { $res = $this->_fgets( $sock ); $ret[] = $res; if ( preg_match( '/^END/', $res ) ) { break; } if ( strlen( $res ) == 0 ) { break; } } return $ret; } // }}} // {{{ set() /** * Unconditionally sets a key to a given value in the memcache. Returns true * if set successfully. * * @param string $key Key to set value as * @param mixed $value Value to set * @param int $exp (optional) Expiration time. This can be a number of seconds * to cache for (up to 30 days inclusive). Any timespans of 30 days + 1 second or * longer must be the timestamp of the time at which the mapping should expire. It * is safe to use timestamps in all cases, regardless of expiration * eg: strtotime("+3 hour") * * @return bool True on success */ public function set( $key, $value, $exp = 0 ) { return $this->_set( 'set', $key, $value, $exp ); } // }}} // {{{ cas() /** * Sets a key to a given value in the memcache if the current value still corresponds * to a known, given value. Returns true if set successfully. * * @param float $casToken Current known value * @param string $key Key to set value as * @param mixed $value Value to set * @param int $exp (optional) Expiration time. This can be a number of seconds * to cache for (up to 30 days inclusive). Any timespans of 30 days + 1 second or * longer must be the timestamp of the time at which the mapping should expire. It * is safe to use timestamps in all cases, regardless of expiration * eg: strtotime("+3 hour") * * @return bool True on success */ public function cas( $casToken, $key, $value, $exp = 0 ) { return $this->_set( 'cas', $key, $value, $exp, $casToken ); } // }}} // {{{ set_compress_threshold() /** * Set the compression threshold * * @param int $thresh Threshold to compress if larger than */ public function set_compress_threshold( $thresh ) { $this->_compress_threshold = $thresh; } // }}} // {{{ set_debug() /** * Set the debug flag * * @see __construct() * @param bool $dbg True for debugging, false otherwise */ public function set_debug( $dbg ) { $this->_debug = $dbg; } // }}} // {{{ set_servers() /** * Set the server list to distribute key gets and puts between * * @see __construct() * @param array $list Array of servers to connect to */ public function set_servers( $list ) { $this->_servers = $list; $this->_active = count( $list ); $this->_buckets = null; $this->_bucketcount = 0; $this->_single_sock = null; if ( $this->_active == 1 ) { $this->_single_sock = $this->_servers[0]; } } /** * Sets the timeout for new connections * * @param int $seconds Number of seconds * @param int $microseconds Number of microseconds */ public function set_timeout( $seconds, $microseconds ) { $this->_timeout_seconds = $seconds; $this->_timeout_microseconds = $microseconds; } // }}} // }}} // {{{ private methods // {{{ _close_sock() /** * Close the specified socket * * @param string $sock Socket to close * * @access private */ function _close_sock( $sock ) { $host = array_search( $sock, $this->_cache_sock ); fclose( $this->_cache_sock[$host] ); unset( $this->_cache_sock[$host] ); } // }}} // {{{ _connect_sock() /** * Connects $sock to $host, timing out after $timeout * * @param int $sock Socket to connect * @param string $host Host:IP to connect to * * @return bool * @access private */ function _connect_sock( &$sock, $host ) { $port = null; $hostAndPort = IPUtils::splitHostAndPort( $host ); if ( $hostAndPort ) { $ip = $hostAndPort[0]; if ( $hostAndPort[1] ) { $port = $hostAndPort[1]; } } else { $ip = $host; } $sock = false; $timeout = $this->_connect_timeout; $errno = $errstr = null; for ( $i = 0; !$sock && $i < $this->_connect_attempts; $i++ ) { AtEase::suppressWarnings(); if ( $this->_persistent == 1 ) { $sock = pfsockopen( $ip, $port, $errno, $errstr, $timeout ); } else { $sock = fsockopen( $ip, $port, $errno, $errstr, $timeout ); } AtEase::restoreWarnings(); } if ( !$sock ) { $this->_error_log( "Error connecting to $host: $errstr" ); $this->_dead_host( $host ); return false; } // Initialise timeout stream_set_timeout( $sock, $this->_timeout_seconds, $this->_timeout_microseconds ); // If the connection was persistent, flush the read buffer in case there // was a previous incomplete request on this connection if ( $this->_persistent ) { $this->_flush_read_buffer( $sock ); } return true; } // }}} // {{{ _dead_sock() /** * Marks a host as dead until 30-40 seconds in the future * * @param string $sock Socket to mark as dead * * @access private */ function _dead_sock( $sock ) { $host = array_search( $sock, $this->_cache_sock ); $this->_dead_host( $host ); } /** * @param string $host */ function _dead_host( $host ) { $hostAndPort = IPUtils::splitHostAndPort( $host ); if ( $hostAndPort ) { $ip = $hostAndPort[0]; } else { $ip = $host; } $this->_host_dead[$ip] = time() + 30 + intval( rand( 0, 10 ) ); $this->_host_dead[$host] = $this->_host_dead[$ip]; unset( $this->_cache_sock[$host] ); } // }}} // {{{ get_sock() /** * get_sock * * @param string $key Key to retrieve value for; * * @return Resource|bool Resource on success, false on failure * @access private */ function get_sock( $key ) { if ( !$this->_active ) { return false; } if ( $this->_single_sock !== null ) { return $this->sock_to_host( $this->_single_sock ); } $hv = is_array( $key ) ? intval( $key[0] ) : $this->_hashfunc( $key ); if ( $this->_buckets === null ) { $bu = array(); foreach ( $this->_servers as $v ) { if ( is_array( $v ) ) { for ( $i = 0; $i < $v[1]; $i++ ) { $bu[] = $v[0]; } } else { $bu[] = $v; } } $this->_buckets = $bu; $this->_bucketcount = count( $bu ); } $realkey = is_array( $key ) ? $key[1] : $key; for ( $tries = 0; $tries < 20; $tries++ ) { $host = $this->_buckets[$hv % $this->_bucketcount]; $sock = $this->sock_to_host( $host ); if ( $sock ) { return $sock; } $hv = $this->_hashfunc( $hv . $realkey ); } return false; } // }}} // {{{ _hashfunc() /** * Creates a hash integer based on the $key * * @param string $key Key to hash * * @return int Hash value * @access private */ function _hashfunc( $key ) { # Hash function must be in [0,0x7ffffff] # We take the first 31 bits of the MD5 hash, which unlike the hash # function used in a previous version of this client, works return hexdec( substr( md5( $key ), 0, 8 ) ) & 0x7fffffff; } // }}} // {{{ _incrdecr() /** * Perform increment/decrement on $key * * @param string $cmd Command to perform * @param string|array $key Key to perform it on * @param int $amt Amount to adjust * * @return int New value of $key * @access private */ function _incrdecr( $cmd, $key, $amt = 1 ) { $this->_last_cmd_status = self::ERR_NONE; if ( !$this->_active ) { $this->_last_cmd_status = self::ERR_UNEXPECTED; return null; } $sock = $this->get_sock( $key ); if ( !$sock ) { $this->_last_cmd_status = self::ERR_UNREACHABLE; return null; } $key = is_array( $key ) ? $key[1] : $key; if ( isset( $this->stats[$cmd] ) ) { $this->stats[$cmd]++; } else { $this->stats[$cmd] = 1; } if ( !$this->_fwrite( $sock, "$cmd $key $amt\r\n" ) ) { $this->_last_cmd_status = self::ERR_NO_RESPONSE; return null; } $line = $this->_fgets( $sock ); if ( $this->_debug ) { $this->_debugprint( "$cmd($key): $line" ); } $match = array(); if ( !preg_match( '/^(\d+)/', $line, $match ) ) { $this->_last_cmd_status = self::ERR_NO_RESPONSE; return null; } return (int)$match[1]; } // }}} // {{{ _load_items() /** * Load items into $ret from $sock * * @param Resource $sock Socket to read from * @param array $ret returned values * @param float $casToken [optional] * @return bool True for success, false for failure * * @access private */ function _load_items( $sock, &$ret, &$casToken = null ) { $results = array(); while ( 1 ) { $decl = $this->_fgets( $sock ); if ( $decl === false ) { /* * If nothing can be read, something is wrong because we know exactly when * to stop reading (right after "END") and we return right after that. */ return false; } elseif ( preg_match( '/^VALUE (\S+) (\d+) (\d+)(?: (\d+))?$/', $decl, $match ) ) { /* * Read all data returned. This can be either one or multiple values. * Save all that data (in an array) to be processed later: we'll first * want to continue reading until "END" before doing anything else, * to make sure that we don't leave our client in a state where it's * output is not yet fully read. */ $results[] = array( $match[1], // rkey $match[2], // flags $match[3], // len $match[4] ?? null, // casToken (appears with "gets" but not "get") $this->_fread( $sock, $match[3] + 2 ), // data ); } elseif ( $decl == "END" ) { /** * All data has been read, time to process the data and build * meaningful return values. */ foreach ( $results as [ $rkey, $flags, /* length */, $casToken, $data ] ) { if ( $data === false || substr( $data, -2 ) !== "\r\n" ) { $this->_handle_error( $sock, 'line ending missing from data block from $1' ); return false; } $data = substr( $data, 0, -2 ); $ret[$rkey] = $data; if ( $this->_have_zlib && $flags & self::COMPRESSED ) { $ret[$rkey] = gzuncompress( $ret[$rkey] ); } /* * This unserialize is the exact reason that we only want to * process data after having read until "END" (instead of doing * this right away): "unserialize" can trigger outside code: * in the event that $ret[$rkey] is a serialized object, * unserializing it will trigger __wakeup() if present. If that * function attempted to read from memcached (while we did not * yet read "END"), these 2 calls would collide. */ if ( $flags & self::SERIALIZED ) { $ret[$rkey] = $this->unserialize( $ret[$rkey] ); } elseif ( $flags & self::INTVAL ) { $ret[$rkey] = intval( $ret[$rkey] ); } } return true; } else { $this->_handle_error( $sock, 'Error parsing response from $1' ); return false; } } } // }}} // {{{ _set() /** * Performs the requested storage operation to the memcache server * * @param string $cmd Command to perform * @param string $key Key to act on * @param mixed $val What we need to store * @param int $exp (optional) Expiration time. This can be a number of seconds * to cache for (up to 30 days inclusive). Any timespans of 30 days + 1 second or * longer must be the timestamp of the time at which the mapping should expire. It * is safe to use timestamps in all cases, regardless of expiration * eg: strtotime("+3 hour") * @param float $casToken [optional] * * @return bool * @access private */ function _set( $cmd, $key, $val, $exp, $casToken = null ) { $this->_last_cmd_status = self::ERR_NONE; if ( !$this->_active ) { $this->_last_cmd_status = self::ERR_UNEXPECTED; return false; } $sock = $this->get_sock( $key ); if ( !$sock ) { $this->_last_cmd_status = self::ERR_UNREACHABLE; return false; } if ( isset( $this->stats[$cmd] ) ) { $this->stats[$cmd]++; } else { $this->stats[$cmd] = 1; } $flags = 0; if ( is_int( $val ) ) { $flags |= self::INTVAL; } elseif ( !is_scalar( $val ) ) { $val = $this->serialize( $val ); $flags |= self::SERIALIZED; if ( $this->_debug ) { $this->_debugprint( "client: serializing data as it is not scalar" ); } } $len = strlen( $val ); if ( $this->_have_zlib && $this->_compress_enable && $this->_compress_threshold && $len >= $this->_compress_threshold ) { $c_val = gzcompress( $val, 9 ); $c_len = strlen( $c_val ); if ( $c_len < $len * ( 1 - self::COMPRESSION_SAVINGS ) ) { if ( $this->_debug ) { $this->_debugprint( sprintf( "client: compressing data; was %d bytes is now %d bytes", $len, $c_len ) ); } $val = $c_val; $len = $c_len; $flags |= self::COMPRESSED; } } $command = "$cmd $key $flags $exp $len"; if ( $casToken ) { $command .= " $casToken"; } if ( !$this->_fwrite( $sock, "$command\r\n$val\r\n" ) ) { $this->_last_cmd_status = self::ERR_NO_RESPONSE; return false; } $line = $this->_fgets( $sock ); if ( $this->_debug ) { $this->_debugprint( sprintf( "%s %s (%s)", $cmd, $key, $line ) ); } if ( $line === "STORED" ) { return true; } elseif ( $line === "NOT_STORED" && $cmd === "set" ) { // "Not stored" is always used as the mcrouter response with AllAsyncRoute return true; } if ( $line === false ) { $this->_last_cmd_status = self::ERR_NO_RESPONSE; } return false; } // }}} // {{{ sock_to_host() /** * Returns the socket for the host * * @param string $host Host:IP to get socket for * * @return Resource|bool IO Stream or false * @access private */ function sock_to_host( $host ) { if ( isset( $this->_cache_sock[$host] ) ) { return $this->_cache_sock[$host]; } $sock = null; $now = time(); $hostAndPort = IPUtils::splitHostAndPort( $host ); if ( $hostAndPort ) { $ip = $hostAndPort[0]; } else { $ip = $host; } if ( isset( $this->_host_dead[$host] ) && $this->_host_dead[$host] > $now || isset( $this->_host_dead[$ip] ) && $this->_host_dead[$ip] > $now ) { return null; } if ( !$this->_connect_sock( $sock, $host ) ) { return null; } // Do not buffer writes stream_set_write_buffer( $sock, 0 ); $this->_cache_sock[$host] = $sock; return $this->_cache_sock[$host]; } /** * @param string $text */ function _debugprint( $text ) { $this->_logger->debug( $text ); } /** * @param string $text */ function _error_log( $text ) { $this->_logger->error( "Memcached error: $text" ); } /** * Write to a stream. If there is an error, mark the socket dead. * * @param Resource $sock The socket * @param string $buf The string to write * @return bool True on success, false on failure */ function _fwrite( $sock, $buf ) { $bytesWritten = 0; $bufSize = strlen( $buf ); while ( $bytesWritten < $bufSize ) { $result = fwrite( $sock, $buf ); $data = stream_get_meta_data( $sock ); if ( $data['timed_out'] ) { $this->_handle_error( $sock, 'timeout writing to $1' ); return false; } // Contrary to the documentation, fwrite() returns zero on error in PHP 5.3. if ( $result === false || $result === 0 ) { $this->_handle_error( $sock, 'error writing to $1' ); return false; } $bytesWritten += $result; } return true; } /** * Handle an I/O error. Mark the socket dead and log an error. * * @param Resource $sock * @param string $msg */ function _handle_error( $sock, $msg ) { $peer = stream_socket_get_name( $sock, true /** remote **/ ); if ( strval( $peer ) === '' ) { $peer = array_search( $sock, $this->_cache_sock ); if ( $peer === false ) { $peer = '[unknown host]'; } } $msg = str_replace( '$1', $peer, $msg ); $this->_error_log( "$msg" ); $this->_dead_sock( $sock ); } /** * Read the specified number of bytes from a stream. If there is an error, * mark the socket dead. * * @param Resource $sock The socket * @param int $len The number of bytes to read * @return string|bool The string on success, false on failure. */ function _fread( $sock, $len ) { $buf = ''; while ( $len > 0 ) { $result = fread( $sock, $len ); $data = stream_get_meta_data( $sock ); if ( $data['timed_out'] ) { $this->_handle_error( $sock, 'timeout reading from $1' ); return false; } if ( $result === false ) { $this->_handle_error( $sock, 'error reading buffer from $1' ); return false; } if ( $result === '' ) { // This will happen if the remote end of the socket is shut down $this->_handle_error( $sock, 'unexpected end of file reading from $1' ); return false; } $len -= strlen( $result ); $buf .= $result; } return $buf; } /** * Read a line from a stream. If there is an error, mark the socket dead. * The \r\n line ending is stripped from the response. * * @param Resource $sock The socket * @return string|bool The string on success, false on failure */ function _fgets( $sock ) { $result = fgets( $sock ); // fgets() may return a partial line if there is a select timeout after // a successful recv(), so we have to check for a timeout even if we // got a string response. $data = stream_get_meta_data( $sock ); if ( $data['timed_out'] ) { $this->_handle_error( $sock, 'timeout reading line from $1' ); return false; } if ( $result === false ) { $this->_handle_error( $sock, 'error reading line from $1' ); return false; } if ( substr( $result, -2 ) === "\r\n" ) { $result = substr( $result, 0, -2 ); } elseif ( substr( $result, -1 ) === "\n" ) { $result = substr( $result, 0, -1 ); } else { $this->_handle_error( $sock, 'line ending missing in response from $1' ); return false; } return $result; } /** * Flush the read buffer of a stream * @param Resource $f */ function _flush_read_buffer( $f ) { if ( !$f ) { return; } $r = array( $f ); $w = null; $e = null; $n = stream_select( $r, $w, $e, 0, 0 ); while ( $n == 1 && !feof( $f ) ) { fread( $f, 1024 ); $r = array( $f ); $w = null; $e = null; $n = stream_select( $r, $w, $e, 0, 0 ); } } // }}} // }}} // }}} } PK ! ���# # & objectcache/utils/StorageAwareness.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\LightweightObjectStore; /** * Generic interface providing error code and quality-of-service constants for object stores * * @internal For use by BagOStuff and WANObjectCache * @ingroup Cache */ interface StorageAwareness { /** No storage medium error */ public const ERR_NONE = 0; /** Storage medium failed to yield a complete response to an operation */ public const ERR_NO_RESPONSE = 1; /** Storage medium could not be reached to establish a connection */ public const ERR_UNREACHABLE = 2; /** Storage medium operation failed due to usage limitations or an I/O error */ public const ERR_UNEXPECTED = 3; /** @deprecated Since 1.41; Emulation/fallback mode; see QOS_EMULATION_*; higher is better */ public const ATTR_EMULATION = 1; /** Durability of writes; see QOS_DURABILITY_* (higher means stronger) */ public const ATTR_DURABILITY = 2; /** Data is never saved to begin with (blackhole store) */ public const QOS_DURABILITY_NONE = 1; /** Data is lost at the end of the current web request or CLI script */ public const QOS_DURABILITY_SCRIPT = 2; /** Data is lost once the service storing the data restarts */ public const QOS_DURABILITY_SERVICE = 3; /** Data is saved to disk and writes do not usually block on fsync() */ public const QOS_DURABILITY_DISK = 4; /** Data is saved to disk and writes usually block on fsync(), like a standard RDBMS */ public const QOS_DURABILITY_RDBMS = 5; /** Generic "unknown" value; useful for comparisons (always "good enough") */ public const QOS_UNKNOWN = INF; } PK ! 5p� n n ) objectcache/utils/ExpirationAwareness.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\LightweightObjectStore; /** * Generic interface providing Time-To-Live constants for expirable object storage * * @ingroup Cache * @since 1.35 */ interface ExpirationAwareness { /** @var int One second, in seconds */ public const TTL_SECOND = 1; /** @var int One minute, in seconds */ public const TTL_MINUTE = 60; /** @var int One hour, in seconds */ public const TTL_HOUR = 3_600; /** @var int One day, in seconds */ public const TTL_DAY = 86_400; /** @var int One week, in seconds */ public const TTL_WEEK = 604_800; /** @var int One month, in seconds */ public const TTL_MONTH = 2_592_000; /** @var int One year, in seconds */ public const TTL_YEAR = 31_536_000; /** @var int Reasonably strict cache time that last the life of quick requests */ public const TTL_PROC_SHORT = 3; /** @var int Loose cache time that can survive slow web requests */ public const TTL_PROC_LONG = 30; /** @var int Idiom for "store indefinitely" */ public const TTL_INDEFINITE = 0; /** @var int Idiom for "do not store the newly generated result" */ public const TTL_UNCACHEABLE = -1; } PK ! �� �V" V" " objectcache/utils/RedisConnRef.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\ObjectCache; use Psr\Log\LoggerAwareInterface; use Psr\Log\LoggerInterface; use Redis; use RedisException; /** * Wrapper class for Redis connections that automatically reuses connections (via RAII pattern) * * This class proxies a Redis class instance from the php-redis PECL extension. * All its methods can be called the same way. * * @see <https://github.com/phpredis/phpredis#table-of-contents> * * @ingroup Cache * @since 1.21 */ class RedisConnRef implements LoggerAwareInterface { /** @var RedisConnectionPool */ protected $pool; /** @var Redis */ protected $conn; /** @var string */ protected $server; /** @var string|null */ protected $lastError; /** * @var LoggerInterface */ protected $logger; /** * No authentication errors. */ private const AUTH_NO_ERROR = 200; /** * Temporary authentication error; recovered by reauthenticating. */ private const AUTH_ERROR_TEMPORARY = 201; /** * Authentication error was permanent and could not be recovered. */ private const AUTH_ERROR_PERMANENT = 202; /** * @param RedisConnectionPool $pool * @param string $server * @param Redis $conn * @param LoggerInterface $logger */ public function __construct( RedisConnectionPool $pool, $server, Redis $conn, LoggerInterface $logger ) { $this->pool = $pool; $this->server = $server; $this->conn = $conn; $this->logger = $logger; } public function setLogger( LoggerInterface $logger ) { $this->logger = $logger; } /** * @return string * @since 1.23 */ public function getServer() { return $this->server; } public function getLastError() { return $this->lastError; } public function clearLastError() { $this->lastError = null; } /** * Magic __call handler for most Redis functions. * * @param string $name * @param array $arguments * @return mixed * @throws RedisException */ public function __call( $name, $arguments ) { // Work around https://github.com/nicolasff/phpredis/issues/70 $lname = strtolower( $name ); if ( ( $lname === 'blpop' || $lname === 'brpop' || $lname === 'brpoplpush' ) && count( $arguments ) > 1 ) { // Get timeout off the end since it is always required and argument length can vary $timeout = end( $arguments ); // Only give the additional one second buffer if not requesting an infinite timeout $this->pool->resetTimeout( $this->conn, ( $timeout > 0 ? $timeout + 1 : $timeout ) ); } return $this->tryCall( $name, $arguments ); } /** * Do the method call in the common try catch handler. * * @param string $method * @param array $arguments * @return mixed * @throws RedisException */ private function tryCall( $method, $arguments ) { $this->conn->clearLastError(); try { $res = $this->conn->$method( ...$arguments ); $authError = $this->checkAuthentication(); if ( $authError === self::AUTH_ERROR_TEMPORARY ) { $res = $this->conn->$method( ...$arguments ); } if ( $authError === self::AUTH_ERROR_PERMANENT ) { throw new RedisException( "Failure reauthenticating to Redis." ); } return $res; } finally { $this->postCallCleanup(); } } /** * Key Scan * Handle this explicitly due to needing the iterator passed by reference. * See: https://github.com/phpredis/phpredis#scan * * @param int &$iterator * @param string|null $pattern * @param int|null $count * @return array */ public function scan( &$iterator, $pattern = null, $count = null ) { return $this->tryCall( 'scan', [ &$iterator, $pattern, $count ] ); } /** * Set Scan * Handle this explicitly due to needing the iterator passed by reference. * See: https://github.com/phpredis/phpredis#sScan * * @param string $key * @param int &$iterator * @param string|null $pattern * @param int|null $count * @return array */ public function sScan( $key, &$iterator, $pattern = null, $count = null ) { return $this->tryCall( 'sScan', [ $key, &$iterator, $pattern, $count ] ); } /** * Hash Scan * Handle this explicitly due to needing the iterator passed by reference. * See: https://github.com/phpredis/phpredis#hScan * * @param string $key * @param int &$iterator * @param string|null $pattern * @param int|null $count * @return array */ public function hScan( $key, &$iterator, $pattern = null, $count = null ) { return $this->tryCall( 'hScan', [ $key, &$iterator, $pattern, $count ] ); } /** * Sorted Set Scan * Handle this explicitly due to needing the iterator passed by reference. * See: https://github.com/phpredis/phpredis#hScan * * @param string $key * @param int &$iterator * @param string|null $pattern * @param int|null $count * @return array */ public function zScan( $key, &$iterator, $pattern = null, $count = null ) { return $this->tryCall( 'zScan', [ $key, &$iterator, $pattern, $count ] ); } /** * Handle authentication errors and automatically reauthenticate. * * @return int self::AUTH_NO_ERROR, self::AUTH_ERROR_TEMPORARY, or self::AUTH_ERROR_PERMANENT */ private function checkAuthentication() { $lastError = $this->conn->getLastError(); if ( $lastError && preg_match( '/^ERR operation not permitted\b/', $lastError ) ) { if ( !$this->pool->reauthenticateConnection( $this->server, $this->conn ) ) { return self::AUTH_ERROR_PERMANENT; } $this->conn->clearLastError(); $this->logger->info( "Used automatic re-authentication for Redis.", [ 'redis_server' => $this->server ] ); return self::AUTH_ERROR_TEMPORARY; } return self::AUTH_NO_ERROR; } /** * Post Redis call cleanup. * * @return void */ private function postCallCleanup() { $this->lastError = $this->conn->getLastError() ?: $this->lastError; // Restore original timeout in the case of blocking calls. $this->pool->resetTimeout( $this->conn ); } /** * @param string $script * @param array $params * @param int $numKeys * @return mixed * @throws RedisException */ public function luaEval( $script, array $params, $numKeys ) { $sha1 = sha1( $script ); // 40 char hex $conn = $this->conn; // convenience $server = $this->server; // convenience // Try to run the server-side cached copy of the script $conn->clearLastError(); $res = $conn->evalSha( $sha1, $params, $numKeys ); // If we got a permission error reply that means that (a) we are not in // multi()/pipeline() and (b) some connection problem likely occurred. If // the password the client gave was just wrong, an exception should have // been thrown back in getConnection() previously. $lastError = $conn->getLastError(); if ( $lastError && preg_match( '/^ERR operation not permitted\b/', $lastError ) ) { $this->pool->reauthenticateConnection( $server, $conn ); $conn->clearLastError(); $res = $conn->eval( $script, $params, $numKeys ); $this->logger->info( "Used automatic re-authentication for Lua script '$sha1'.", [ 'redis_server' => $server ] ); } // If the script is not in cache, use eval() to retry and cache it $lastError = $conn->getLastError(); if ( $lastError && preg_match( '/^NOSCRIPT/', $lastError ) ) { $conn->clearLastError(); $res = $conn->eval( $script, $params, $numKeys ); $this->logger->info( "Used eval() for Lua script '$sha1'.", [ 'redis_server' => $server ] ); } $lastError = $conn->getLastError(); if ( $lastError ) { // script bug? $this->logger->error( 'Lua script error on server "{redis_server}": {lua_error}', [ 'redis_server' => $server, 'lua_error' => $lastError ] ); $this->lastError = $lastError; } return $res; } /** * @param Redis $conn * @return bool */ public function isConnIdentical( Redis $conn ) { return $this->conn === $conn; } public function __destruct() { $this->pool->freeConnection( $this->server, $this->conn ); } } /** @deprecated class alias since 1.43 */ class_alias( RedisConnRef::class, 'RedisConnRef' ); PK ! �:��4 �4 ) objectcache/utils/RedisConnectionPool.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\ObjectCache; use Exception; use InvalidArgumentException; use Psr\Log\LoggerAwareInterface; use Psr\Log\LoggerInterface; use Psr\Log\NullLogger; use Redis; use RedisException; use RuntimeException; /** * Manage one or more Redis client connection. * * This can be used to get RedisConnRef objects that automatically reuses * connections internally after the calling function has returned (and thus * your RedisConnRef instance leaves scope/destructs). * * This provides an easy way to cache connection handles that may also have state, * such as a handle does between multi() and exec(), and without hoarding connections. * The wrappers use PHP magic methods so that calling functions on them calls the * function of the actual Redis object handle. * * @ingroup Cache * @since 1.21 */ class RedisConnectionPool implements LoggerAwareInterface { /** @var int Connection timeout in seconds */ protected $connectTimeout; /** @var string Read timeout in seconds */ protected $readTimeout; /** @var string Plaintext auth password */ protected $password; /** @var bool Whether connections persist */ protected $persistent; /** @var int Serializer to use (Redis::SERIALIZER_*) */ protected $serializer; /** @var string ID for persistent connections */ protected $id; /** @var int Current idle pool size */ protected $idlePoolSize = 0; /** * @var array (server name => ((connection info array),...) * @phan-var array<string,array{conn:Redis,free:bool}[]> */ protected $connections = []; /** @var array (server name => UNIX timestamp) */ protected $downServers = []; /** @var array (pool ID => RedisConnectionPool) */ protected static $instances = []; /** integer; seconds to cache servers as "down". */ private const SERVER_DOWN_TTL = 30; /** * @var LoggerInterface */ protected $logger; /** * @param array $options * @param string $id * @throws Exception */ protected function __construct( array $options, $id ) { if ( !class_exists( Redis::class ) ) { throw new RuntimeException( __CLASS__ . ' requires a Redis client library. ' . 'See https://www.mediawiki.org/wiki/Redis#Setup' ); } $this->logger = $options['logger'] ?? new NullLogger(); $this->connectTimeout = $options['connectTimeout']; $this->readTimeout = $options['readTimeout']; $this->persistent = $options['persistent']; $this->password = $options['password']; if ( !isset( $options['serializer'] ) || $options['serializer'] === 'php' ) { $this->serializer = Redis::SERIALIZER_PHP; } elseif ( $options['serializer'] === 'igbinary' ) { if ( !defined( 'Redis::SERIALIZER_IGBINARY' ) ) { throw new InvalidArgumentException( __CLASS__ . ': configured serializer "igbinary" not available' ); } $this->serializer = Redis::SERIALIZER_IGBINARY; } elseif ( $options['serializer'] === 'none' ) { $this->serializer = Redis::SERIALIZER_NONE; } else { throw new InvalidArgumentException( "Invalid serializer specified." ); } $this->id = $id; } public function setLogger( LoggerInterface $logger ) { $this->logger = $logger; } /** * @param array $options * @return array */ protected static function applyDefaultConfig( array $options ) { if ( !isset( $options['connectTimeout'] ) ) { $options['connectTimeout'] = 1; } if ( !isset( $options['readTimeout'] ) ) { $options['readTimeout'] = 1; } if ( !isset( $options['persistent'] ) ) { $options['persistent'] = false; } if ( !isset( $options['password'] ) ) { $options['password'] = null; } return $options; } /** * @param array $options * $options include: * - connectTimeout : The timeout for new connections, in seconds. * Optional, default is 1 second. * - readTimeout : The timeout for operation reads, in seconds. * Commands like BLPOP can fail if told to wait longer than this. * Optional, default is 1 second. * - persistent : Set this to true to allow connections to persist across * multiple web requests. False by default. * - password : The authentication password, will be sent to Redis in clear text. * Optional, if it is unspecified, no AUTH command will be sent. * - serializer : Set to "php", "igbinary", or "none". Default is "php". * @return RedisConnectionPool */ public static function singleton( array $options ) { $options = self::applyDefaultConfig( $options ); // Map the options to a unique hash... ksort( $options ); // normalize to avoid pool fragmentation $id = sha1( serialize( $options ) ); // Initialize the object at the hash as needed... if ( !isset( self::$instances[$id] ) ) { self::$instances[$id] = new self( $options, $id ); } return self::$instances[$id]; } /** * Destroy all singleton() instances * @since 1.27 */ public static function destroySingletons() { self::$instances = []; } /** * Get a connection to a redis server. Based on code in RedisBagOStuff.php. * * @param string $server A hostname/port combination or the absolute path of a UNIX socket. * If a hostname is specified but no port, port 6379 will be used. * @param LoggerInterface|null $logger PSR-3 logger instance. [optional] * @return RedisConnRef|Redis|false Returns false on failure * @throws InvalidArgumentException */ public function getConnection( $server, ?LoggerInterface $logger = null ) { // The above @return also documents 'Redis' for convenience with IDEs. // RedisConnRef uses PHP magic methods, which wouldn't be recognised. $logger = $logger ?: $this->logger; // Check the listing "dead" servers which have had a connection errors. // Servers are marked dead for a limited period of time, to // avoid excessive overhead from repeated connection timeouts. if ( isset( $this->downServers[$server] ) ) { $now = time(); if ( $now > $this->downServers[$server] ) { // Dead time expired unset( $this->downServers[$server] ); } else { // Server is dead $logger->debug( 'Server "{redis_server}" is marked down for another ' . ( $this->downServers[$server] - $now ) . ' seconds', [ 'redis_server' => $server ] ); return false; } } // Check if a connection is already free for use if ( isset( $this->connections[$server] ) ) { foreach ( $this->connections[$server] as &$connection ) { if ( $connection['free'] ) { $connection['free'] = false; --$this->idlePoolSize; return new RedisConnRef( $this, $server, $connection['conn'], $logger ); } } } if ( !$server ) { throw new InvalidArgumentException( __CLASS__ . ": invalid configured server \"$server\"" ); } elseif ( substr( $server, 0, 1 ) === '/' ) { // UNIX domain socket // These are required by the redis extension to start with a slash, but // we still need to set the port to a special value to make it work. $host = $server; $port = 0; } else { // TCP connection if ( preg_match( '/^\[(.+)\]:(\d+)$/', $server, $m ) ) { // (ip, port) [ $host, $port ] = [ $m[1], (int)$m[2] ]; } elseif ( preg_match( '/^((?:[\w]+\:\/\/)?[^:]+):(\d+)$/', $server, $m ) ) { // (ip, uri or path, port) [ $host, $port ] = [ $m[1], (int)$m[2] ]; if ( substr( $host, 0, 6 ) === 'tls://' && version_compare( phpversion( 'redis' ), '5.0.0' ) < 0 ) { throw new RuntimeException( 'A newer version of the Redis client library is required to use TLS. ' . 'See https://www.mediawiki.org/wiki/Redis#Setup' ); } } else { // (ip or path, port) [ $host, $port ] = [ $server, 6379 ]; } } $conn = new Redis(); try { if ( $this->persistent ) { $result = $conn->pconnect( $host, $port, $this->connectTimeout, $this->id ); } else { $result = $conn->connect( $host, $port, $this->connectTimeout ); } if ( !$result ) { $logger->error( 'Could not connect to server "{redis_server}"', [ 'redis_server' => $server ] ); // Mark server down for some time to avoid further timeouts $this->downServers[$server] = time() + self::SERVER_DOWN_TTL; return false; } if ( ( $this->password !== null ) && !$conn->auth( $this->password ) ) { $logger->error( 'Authentication error connecting to "{redis_server}"', [ 'redis_server' => $server ] ); } } catch ( RedisException $e ) { $this->downServers[$server] = time() + self::SERVER_DOWN_TTL; $logger->error( 'Redis exception connecting to "{redis_server}"', [ 'redis_server' => $server, 'exception' => $e, ] ); return false; } $conn->setOption( Redis::OPT_READ_TIMEOUT, $this->readTimeout ); $conn->setOption( Redis::OPT_SERIALIZER, $this->serializer ); $this->connections[$server][] = [ 'conn' => $conn, 'free' => false ]; return new RedisConnRef( $this, $server, $conn, $logger ); } /** * Mark a connection to a server as free to return to the pool * * @param string $server * @param Redis $conn * @return bool */ public function freeConnection( $server, Redis $conn ) { $found = false; foreach ( $this->connections[$server] as &$connection ) { if ( $connection['conn'] === $conn && !$connection['free'] ) { $connection['free'] = true; ++$this->idlePoolSize; break; } } $this->closeExcessIdleConections(); return $found; } /** * Close any extra idle connections if there are more than the limit */ protected function closeExcessIdleConections() { if ( $this->idlePoolSize <= count( $this->connections ) ) { return; // nothing to do (no more connections than servers) } foreach ( $this->connections as &$serverConnections ) { foreach ( $serverConnections as $key => &$connection ) { if ( $connection['free'] ) { unset( $serverConnections[$key] ); if ( --$this->idlePoolSize <= count( $this->connections ) ) { return; // done (no more connections than servers) } } } } } /** * The redis extension throws an exception in response to various read, write * and protocol errors. Sometimes it also closes the connection, sometimes * not. The safest response for us is to explicitly destroy the connection * object and let it be reopened during the next request. * * @param RedisConnRef $cref * @param RedisException $e */ public function handleError( RedisConnRef $cref, RedisException $e ) { $server = $cref->getServer(); $this->logger->error( 'Redis exception on server "{redis_server}"', [ 'redis_server' => $server, 'exception' => $e, ] ); foreach ( $this->connections[$server] as $key => $connection ) { if ( $cref->isConnIdentical( $connection['conn'] ) ) { $this->idlePoolSize -= $connection['free'] ? 1 : 0; unset( $this->connections[$server][$key] ); break; } } } /** * Re-send an AUTH request to the redis server (useful after disconnects). * * This works around an upstream bug in phpredis. phpredis hides disconnects by transparently * reconnecting, but it neglects to re-authenticate the new connection. To the user of the * phpredis client API this manifests as a seemingly random tendency of connections to lose * their authentication status. * * This method is for internal use only. * * @see https://github.com/nicolasff/phpredis/issues/403 * * @param string $server * @param Redis $conn * @return bool Success */ public function reauthenticateConnection( $server, Redis $conn ) { if ( $this->password !== null && !$conn->auth( $this->password ) ) { $this->logger->error( 'Authentication error connecting to "{redis_server}"', [ 'redis_server' => $server ] ); return false; } return true; } /** * Adjust or reset the connection handle read timeout value * * @param Redis $conn * @param int|null $timeout Optional */ public function resetTimeout( Redis $conn, $timeout = null ) { $conn->setOption( Redis::OPT_READ_TIMEOUT, $timeout ?: $this->readTimeout ); } /** * Make sure connections are closed */ public function __destruct() { foreach ( $this->connections as &$serverConnections ) { foreach ( $serverConnections as &$connection ) { try { /** @var Redis $conn */ $conn = $connection['conn']; $conn->close(); } catch ( RedisException $e ) { // The destructor can be called on shutdown when random parts of the system // have been destructed already, causing weird errors. Ignore them. } } } } } /** @deprecated class alias since 1.43 */ class_alias( RedisConnectionPool::class, 'RedisConnectionPool' ); PK ! ���4 4 objectcache/WANObjectCache.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\ObjectCache; use ArrayIterator; use Closure; use Exception; use MapCacheLRU; use Psr\Log\LoggerAwareInterface; use Psr\Log\LoggerInterface; use Psr\Log\NullLogger; use RuntimeException; use UnexpectedValueException; use Wikimedia\LightweightObjectStore\ExpirationAwareness; use Wikimedia\LightweightObjectStore\StorageAwareness; use Wikimedia\Stats\IBufferingStatsdDataFactory; use Wikimedia\Stats\StatsFactory; /** * Multi-datacenter aware caching interface * * ### Using WANObjectCache * * %WANObjectCache (known as **WANCache**, pronounced whan-cache) improves performance * by reducing database load, increasing web server capacity (fewer repeated computations) and * providing faster access to data. The data cached here follows a "cache-aside" strategy, with * data potentially derived from database rows. Generally speaking, cache data should be treated * as equally up-to-date to data from a replica database, and is thus essentially subject to the * same replication lag. * * The primary way to interact with this class is via the getWithSetCallback() method. * * Each data center has its own cache cluster, with web servers in a given datacenter * populating and reading from the local datacenter only. The exceptions are methods delete(), * touchCheckKey(), and resetCheckKey(), which also asynchronously broadcast the equivalent * purge to other datacenters. * * To learn how this is used and configured at Wikimedia Foundation, * refer to <https://wikitech.wikimedia.org/wiki/Memcached_for_MediaWiki>. * * For broader guidance on how to approach caching in MediaWiki at scale, * refer to <https://wikitech.wikimedia.org/wiki/MediaWiki_Engineering/Guides/Backend_performance_practices>. * * For your code to "see" new values in a timely manner, you need to follow either the * validation strategy, or the purge strategy. * * #### Strategy 1: Validation * * The validation strategy refers to the natural avoidance of stale data * by one of the following means: * * - A) The cached value is immutable. * * If you can obtain all the information needed to uniquely describe the value, * then the value never has to change or be purged. Instead, the key changes, * which naturally creates a miss where you can compute the right value. * For example, a transformation like parsing or transforming some input, * could have a cache key like `example-myparser, option-xyz, v2, hash1234` * which would describe the transformation, the version/parameters, and a hash * of the exact input. * * This also naturally avoids oscillation or corruption in the context of multiple * servers and data centers, where your code may not always be running the same version * everywhere at the same time. Newer code would have its own set of cache keys, * ensuring a deterministic outcome. * - B) The value is cached with a low TTL. * * If you can tolerate a few seconds or minutes of delay before changes are reflected * in the way your data is used, and if re-computation is quick, you can consider * caching it with a "blind" TTL – using the value's age as your method of validation. * - C) Validity is checked against an external source. * * Perhaps you prefer to utilize the old data as fallback or to help compute the new * value, or for other reasons you need to have a stable key across input changes * (e.g. cache by page title instead of revision ID). If you put the variable identifier * (e.g. input hash, or revision ID) in the cache value, and validate this on retrieval * then you don't need purging or expiration. * * After calling get() you can validate the ID inside the cached value against what * you know. When needed, recompute the value and call set(). * * #### Strategy 2: Purge * * The purge strategy refers to the approach whereby your application knows that source * data has changed and can react by purging the relevant cache keys. * The simplest purge method is delete(). * * Note that cache updates and purges are not immediately visible to all application servers in * all data centers. The cache should be treated like a replica database in this regard. * If immediate synchronization is required, then solutions must be sought outside WANCache. * * Write operations like delete() and the "set" part of getWithSetCallback(), may return true as * soon as the command has been sent or buffered to an open connection to the cache cluster. * It will be processed and/or broadcasted asynchronously. * * @anchor wanobjectcache-deployment * ### Deploying WANObjectCache * * There are two supported ways for sysadmins to set up multi-DC cache purging: * * - A) Set up mcrouter as the cache backend, with a memcached BagOStuff class for the 'cache' * parameter, and a wildcard routing prefix for the 'broadcastRoutingPrefix' parameter. * Configure mcrouter as follows: * - Define a "<datacenter>" pool of memcached servers for each datacenter. * - Define a "<datacenter>/wan" route to each datacenter, using "AllSyncRoute" for the * routes that go to the local datacenter pool and "AllAsyncRoute" for the routes that * go to remote datacenter pools. The child routes should use "HashRoute|<datacenter>". * This allows for the use of a wildcard route for 'broadcastRoutingPrefix'. See * https://github.com/facebook/mcrouter/wiki/Routing-Prefix and * https://github.com/facebook/mcrouter/wiki/Multi-cluster-broadcast-setup. * - In order to reroute operations from "down" servers to spare ("gutter") servers, use * "FailoverWithExptimeRoute" (failover_exptime=60) instead of "HashRoute|<datacenter>" * in the "AllSyncRoute"/"AllAsyncRoute" child routes. * The "gutter" pool is a set of memcached servers that only handle failover traffic. * Such servers should be carefully spread over different rows and racks. See * https://github.com/facebook/mcrouter/wiki/List-of-Route-Handles#failoverroute * - B) Set up dynomite as the cache backend, using a memcached BagOStuff class for the 'cache' * parameter. Note that with this setup, all key setting operations will be broadcasted, * rather than just purges. Writes will be eventually consistent via the Dynamo replication * model. See https://github.com/Netflix/dynomite. * * Broadcasted operations like delete() and touchCheckKey() are intended to run * immediately in the local datacenter and asynchronously in remote datacenters. * * This means that callers in all datacenters may see older values for however many * milliseconds that the purge took to reach that datacenter. As with any cache, this * should not be relied on for cases where reads are used to determine writes to source * (e.g. non-cache) data stores, except when reading immutable data. * * Internally, access to a given key actually involves the use of one or more "sister" keys. * A sister key is constructed by prefixing the base key with "WANCache:" (used to distinguish * WANObjectCache formatted keys) and suffixing a colon followed by a single-character sister * key type. The sister key types include the following: * * - `v`: used to store "regular" values (metadata-wrapped) and temporary purge "tombstones". * - `t`: used to store "last purge" timestamps for "check" keys. * - `m`: used to store temporary mutex locks to avoid cache stampedes. * - `i`: used to store temporary interim values (metadata-wrapped) for tombstoned keys. * - `c`: used to store temporary "cool-off" indicators, which specify a period during which * values cannot be stored, neither regularly nor using interim keys. * * @ingroup Cache * @newable * @since 1.26 */ class WANObjectCache implements ExpirationAwareness, StorageAwareness, IStoreKeyEncoder, LoggerAwareInterface { /** @var BagOStuff The local datacenter cache */ protected $cache; /** @var MapCacheLRU[] Map of group PHP instance caches */ protected $processCaches = []; /** @var LoggerInterface */ protected $logger; /** @var StatsFactory */ protected $stats; /** @var callable|null Function that takes a WAN cache callback and runs it later */ protected $asyncHandler; /** * Routing prefix for operations that should be broadcasted to all data centers. * * If null, the there is only one datacenter or a backend proxy broadcasts everything. * * @var string|null */ protected $broadcastRoute; /** @var bool Whether to use "interim" caching while keys are tombstoned */ protected $useInterimHoldOffCaching = true; /** @var float Unix timestamp of the oldest possible valid values */ protected $epoch; /** @var string Stable secret used for hashing long strings into key components */ protected $secret; /** @var int Scheme to use for key coalescing (Hash Tags or Hash Stops) */ protected $coalesceScheme; /** @var array<int,array> List of (key, UNIX timestamp) tuples for get() cache misses */ private $missLog; /** @var int Callback stack depth for getWithSetCallback() */ private $callbackDepth = 0; /** @var mixed[] Temporary warm-up cache */ private $warmupCache = []; /** @var int Key fetched */ private $warmupKeyMisses = 0; /** @var float|null */ private $wallClockOverride; /** Max expected seconds to pass between delete() and DB commit finishing */ private const MAX_COMMIT_DELAY = 3; /** Max expected seconds of combined lag from replication and "view snapshots" */ private const MAX_READ_LAG = 7; /** Seconds to tombstone keys on delete() and to treat keys as volatile after purges */ public const HOLDOFF_TTL = self::MAX_COMMIT_DELAY + self::MAX_READ_LAG + 1; /** Consider regeneration if the key will expire within this many seconds */ private const LOW_TTL = 60; /** Max TTL, in seconds, to store keys when a data source has high replication lag */ public const TTL_LAGGED = 30; /** Expected time-till-refresh, in seconds, if the key is accessed once per second */ private const HOT_TTR = 900; /** Minimum key age, in seconds, for expected time-till-refresh to be considered */ private const AGE_NEW = 60; /** Idiom for getWithSetCallback() meaning "no cache stampede mutex" */ private const TSE_NONE = -1; /** Idiom for set()/getWithSetCallback() meaning "no post-expiration persistence" */ public const STALE_TTL_NONE = 0; /** Idiom for set()/getWithSetCallback() meaning "no post-expiration grace period" */ public const GRACE_TTL_NONE = 0; /** Idiom for delete()/touchCheckKey() meaning "no hold-off period" */ public const HOLDOFF_TTL_NONE = 0; /** @var float Idiom for getWithSetCallback() meaning "no minimum required as-of timestamp" */ public const MIN_TIMESTAMP_NONE = 0.0; /** Default process cache name and max key count */ private const PC_PRIMARY = 'primary:1000'; /** Idiom for get()/getMulti() to return extra information by reference */ public const PASS_BY_REF = []; /** Use twemproxy-style Hash Tag key scheme (e.g. "{...}") */ private const SCHEME_HASH_TAG = 1; /** Use mcrouter-style Hash Stop key scheme (e.g. "...|#|") */ private const SCHEME_HASH_STOP = 2; /** Seconds to keep dependency purge keys around */ private const CHECK_KEY_TTL = self::TTL_YEAR; /** Seconds to keep interim value keys for tombstoned keys around */ private const INTERIM_KEY_TTL = 2; /** Seconds to keep lock keys around */ private const LOCK_TTL = 10; /** Seconds to ramp up the chance of regeneration due to expected time-till-refresh */ private const RAMPUP_TTL = 30; /** @var float Tiny negative float to use when CTL comes up >= 0 due to clock skew */ private const TINY_NEGATIVE = -0.000001; /** @var float Tiny positive float to use when using "minTime" to assert an inequality */ private const TINY_POSITIVE = 0.000001; /** Min millisecond set() backoff during hold-off (far less than INTERIM_KEY_TTL) */ private const RECENT_SET_LOW_MS = 50; /** Max millisecond set() backoff during hold-off (far less than INTERIM_KEY_TTL) */ private const RECENT_SET_HIGH_MS = 100; /** Consider value generation somewhat high if it takes this many seconds or more */ private const GENERATION_HIGH_SEC = 0.2; /** Key to the tombstone entry timestamp */ private const PURGE_TIME = 0; /** Key to the tombstone entry hold-off TTL */ private const PURGE_HOLDOFF = 1; /** Cache format version number */ private const VERSION = 1; /** Version number attribute for a key; keep value for b/c (< 1.36) */ public const KEY_VERSION = 'version'; /** Generation completion timestamp attribute for a key; keep value for b/c (< 1.36) */ public const KEY_AS_OF = 'asOf'; /** Logical TTL attribute for a key */ public const KEY_TTL = 'ttl'; /** Remaining TTL attribute for a key; keep value for b/c (< 1.36) */ public const KEY_CUR_TTL = 'curTTL'; /** Tomstone timestamp attribute for a key; keep value for b/c (< 1.36) */ public const KEY_TOMB_AS_OF = 'tombAsOf'; /** Highest "check" key timestamp for a key; keep value for b/c (< 1.36) */ public const KEY_CHECK_AS_OF = 'lastCKPurge'; /** Value for a key */ private const RES_VALUE = 0; /** Version number attribute for a key */ private const RES_VERSION = 1; /** Generation completion timestamp attribute for a key */ private const RES_AS_OF = 2; /** Logical TTL attribute for a key */ private const RES_TTL = 3; /** Tomstone timestamp attribute for a key */ private const RES_TOMB_AS_OF = 4; /** Highest "check" key timestamp for a key */ private const RES_CHECK_AS_OF = 5; /** Highest "touched" timestamp for a key */ private const RES_TOUCH_AS_OF = 6; /** Remaining TTL attribute for a key */ private const RES_CUR_TTL = 7; /** Key to WAN cache version number; stored in blobs */ private const FLD_FORMAT_VERSION = 0; /** Key to the cached value; stored in blobs */ private const FLD_VALUE = 1; /** Key to the original TTL; stored in blobs */ private const FLD_TTL = 2; /** Key to the cache timestamp; stored in blobs */ private const FLD_TIME = 3; /** Key to the flags bit field (reserved number) */ private const /** @noinspection PhpUnusedPrivateFieldInspection */ FLD_FLAGS = 4; /** Key to collection cache version number; stored in blobs */ private const FLD_VALUE_VERSION = 5; private const /** @noinspection PhpUnusedPrivateFieldInspection */ FLD_GENERATION_TIME = 6; /** Single character component for value keys */ private const TYPE_VALUE = 'v'; /** Single character component for timestamp check keys */ private const TYPE_TIMESTAMP = 't'; /** Single character component for mutex lock keys */ private const TYPE_MUTEX = 'm'; /** Single character component for interim value keys */ private const TYPE_INTERIM = 'i'; /** Value prefix of purge values */ private const PURGE_VAL_PREFIX = 'PURGED'; /** * @stable to call * @param array $params * - cache : BagOStuff object for a persistent cache * - logger : LoggerInterface object * - stats : StatsFactory object. Since 1.43, constructing a WANObjectCache object * with an IBufferingStatsdDataFactory stats collector will emit a warning. * - asyncHandler : A function that takes a callback and runs it later. If supplied, * whenever a preemptive refresh would be triggered in getWithSetCallback(), the * current cache value is still used instead. However, the async-handler function * receives a WAN cache callback that, when run, will execute the value generation * callback supplied by the getWithSetCallback() caller. The result will be saved * as normal. The handler is expected to call the WAN cache callback at an opportune * time (e.g. HTTP post-send), though generally within a few 100ms. [optional] * - broadcastRoutingPrefix: a routing prefix used to broadcast certain operations to all * datacenters; See also <https://github.com/facebook/mcrouter/wiki/Config-Files>. * This prefix takes the form `/<datacenter>/<name of wan route>/`, where `datacenter` * is usually a wildcard to select all matching routes (e.g. the WAN cluster in all DCs). * See also <https://github.com/facebook/mcrouter/wiki/Multi-cluster-broadcast-setup>. * This is required when using mcrouter as a multi-region backing store proxy. [optional] * - epoch: lowest UNIX timestamp a value/tombstone must have to be valid. [optional] * - secret: stable secret used for hashing long strings into key components. [optional] * - coalesceScheme: which key scheme to use in order to encourage the backend to place any * "helper" keys for a "value" key within the same cache server. This reduces network * overhead and reduces the chance the single downed cache server causes disruption. * Use "hash_stop" with mcrouter and "hash_tag" with dynomite. [default: "hash_stop"] */ public function __construct( array $params ) { $this->cache = $params['cache']; $this->broadcastRoute = $params['broadcastRoutingPrefix'] ?? null; $this->epoch = $params['epoch'] ?? 0; $this->secret = $params['secret'] ?? (string)$this->epoch; if ( ( $params['coalesceScheme'] ?? '' ) === 'hash_tag' ) { // https://redis.io/topics/cluster-spec // https://github.com/twitter/twemproxy/blob/v0.4.1/notes/recommendation.md#hash-tags // https://github.com/Netflix/dynomite/blob/v0.7.0/notes/recommendation.md#hash-tags $this->coalesceScheme = self::SCHEME_HASH_TAG; } else { // https://github.com/facebook/mcrouter/wiki/Key-syntax $this->coalesceScheme = self::SCHEME_HASH_STOP; } $this->setLogger( $params['logger'] ?? new NullLogger() ); if ( isset( $params['stats'] ) && $params['stats'] instanceof IBufferingStatsdDataFactory ) { wfDeprecated( __METHOD__, 'Use of StatsdDataFactory is deprecated in 1.43. Use StatsFactory instead.' ); $params['stats'] = null; } $this->stats = $params['stats'] ?? StatsFactory::newNull(); $this->asyncHandler = $params['asyncHandler'] ?? null; $this->missLog = array_fill( 0, 10, [ '', 0.0 ] ); } /** * @param LoggerInterface $logger */ public function setLogger( LoggerInterface $logger ) { $this->logger = $logger; } /** * Get an instance that wraps EmptyBagOStuff * * @return WANObjectCache */ public static function newEmpty() { return new static( [ 'cache' => new EmptyBagOStuff() ] ); } /** * Fetch the value of a key from cache * * If supplied, $curTTL is set to the remaining TTL (current time left): * - a) INF; if $key exists, has no TTL, and is not purged by $checkKeys * - b) float (>=0); if $key exists, has a TTL, and is not purged by $checkKeys * - c) float (<0); if $key is tombstoned, stale, or existing but purged by $checkKeys * - d) null; if $key does not exist and is not tombstoned * * If a key is tombstoned, $curTTL will reflect the time since delete(). * * The timestamp of $key will be checked against the last-purge timestamp * of each of $checkKeys. Those $checkKeys not in cache will have the last-purge * initialized to the current timestamp. If any of $checkKeys have a timestamp * greater than that of $key, then $curTTL will reflect how long ago $key * became invalid. Callers can use $curTTL to know when the value is stale. * The $checkKeys parameter allow mass key purges by updating a single key: * - a) Each "check" key represents "last purged" of some source data * - b) Callers pass in relevant "check" keys as $checkKeys in get() * - c) When the source data that "check" keys represent changes, * the touchCheckKey() method is called on them * * Source data entities might exist in a DB that uses snapshot isolation * (e.g. the default REPEATABLE-READ in innoDB). Even for mutable data, that * isolation can largely be maintained by doing the following: * - a) Calling delete() on entity change *and* creation, before DB commit * - b) Keeping transaction duration shorter than the delete() hold-off TTL * - c) Disabling interim key caching via useInterimHoldOffCaching() before get() calls * * However, pre-snapshot values might still be seen if an update was made * in a remote datacenter but the purge from delete() didn't relay yet. * * Consider using getWithSetCallback(), which has cache slam avoidance and key * versioning features, instead of bare get()/set() calls. * * Do not use this method on versioned keys accessed via getWithSetCallback(). * * When using the $info parameter, it should be passed in as WANObjectCache::PASS_BY_REF. * In that case, it becomes a key metadata map. Otherwise, for backwards compatibility, * $info becomes the value generation timestamp (null if the key is nonexistant/tombstoned). * Key metadata map fields include: * - WANObjectCache::KEY_VERSION: value version number; null if key is nonexistant * - WANObjectCache::KEY_AS_OF: value generation timestamp (UNIX); null if key is nonexistant * - WANObjectCache::KEY_TTL: assigned TTL (seconds); null if key is nonexistant/tombstoned * - WANObjectCache::KEY_CUR_TTL: remaining TTL (seconds); null if key is nonexistant * - WANObjectCache::KEY_TOMB_AS_OF: tombstone timestamp (UNIX); null if key is not tombstoned * - WANObjectCache::KEY_CHECK_AS_OF: highest "check" key timestamp (UNIX); null if none * * @param string $key Cache key made with makeKey()/makeGlobalKey() * @param float|null &$curTTL Seconds of TTL left [returned] * @param string[] $checkKeys Map of (integer or cache key => "check" key(s)); * "check" keys must also be made with makeKey()/makeGlobalKey() * @param array &$info Metadata map [returned] * @return mixed Value of cache key; false on failure */ final public function get( $key, &$curTTL = null, array $checkKeys = [], &$info = [] ) { // Note that an undeclared variable passed as $info starts as null (not the default). // Also, if no $info parameter is provided, then it doesn't matter how it changes here. $legacyInfo = ( $info !== self::PASS_BY_REF ); $now = $this->getCurrentTime(); $res = $this->fetchKeys( [ $key ], $checkKeys, $now )[$key]; $curTTL = $res[self::RES_CUR_TTL]; $info = $legacyInfo ? $res[self::RES_AS_OF] : [ self::KEY_VERSION => $res[self::RES_VERSION], self::KEY_AS_OF => $res[self::RES_AS_OF], self::KEY_TTL => $res[self::RES_TTL], self::KEY_CUR_TTL => $res[self::RES_CUR_TTL], self::KEY_TOMB_AS_OF => $res[self::RES_TOMB_AS_OF], self::KEY_CHECK_AS_OF => $res[self::RES_CHECK_AS_OF] ]; if ( $curTTL === null || $curTTL <= 0 ) { // Log the timestamp in case a corresponding set() call does not provide "walltime" unset( $this->missLog[array_key_first( $this->missLog )] ); $this->missLog[] = [ $key, $this->getCurrentTime() ]; } return $res[self::RES_VALUE]; } /** * Fetch the value of several keys from cache * * $curTTLs becomes a map of only present/tombstoned $keys to their current time-to-live. * * $checkKeys holds the "check" keys used to validate values of applicable keys. The * integer indexes hold "check" keys that apply to all of $keys while the string indexes * hold "check" keys that only apply to the cache key with that name. The logic of "check" * keys otherwise works the same as in WANObjectCache::get(). * * When using the $info parameter, it should be passed in as WANObjectCache::PASS_BY_REF. * In that case, it becomes a mapping of all the $keys to their metadata maps, each in the * style of WANObjectCache::get(). Otherwise, for backwards compatibility, $info becomes a * map of only present/tombstoned $keys to their value generation timestamps. * * @see WANObjectCache::get() * * @param string[] $keys List/map with makeKey()/makeGlobalKey() cache keys as values * @param array<string,float> &$curTTLs Map of (key => seconds of TTL left) [returned] * @param string[]|string[][] $checkKeys Map of (integer or cache key => "check" key(s)); * "check" keys must also be made with makeKey()/makeGlobalKey() * @param array<string,array> &$info Map of (key => metadata map) [returned] * @return array<string,mixed> Map of (key => value) for existing values in order of $keys */ final public function getMulti( array $keys, &$curTTLs = [], array $checkKeys = [], &$info = [] ) { // Note that an undeclared variable passed as $info starts as null (not the default). // Also, if no $info parameter is provided, then it doesn't matter how it changes here. $legacyInfo = ( $info !== self::PASS_BY_REF ); $curTTLs = []; $info = []; $valuesByKey = []; $now = $this->getCurrentTime(); $resByKey = $this->fetchKeys( $keys, $checkKeys, $now ); foreach ( $resByKey as $key => $res ) { if ( $res[self::RES_VALUE] !== false ) { $valuesByKey[$key] = $res[self::RES_VALUE]; } if ( $res[self::RES_CUR_TTL] !== null ) { $curTTLs[$key] = $res[self::RES_CUR_TTL]; } $info[$key] = $legacyInfo ? $res[self::RES_AS_OF] : [ self::KEY_VERSION => $res[self::RES_VERSION], self::KEY_AS_OF => $res[self::RES_AS_OF], self::KEY_TTL => $res[self::RES_TTL], self::KEY_CUR_TTL => $res[self::RES_CUR_TTL], self::KEY_TOMB_AS_OF => $res[self::RES_TOMB_AS_OF], self::KEY_CHECK_AS_OF => $res[self::RES_CHECK_AS_OF] ]; } return $valuesByKey; } /** * Fetch the value and key metadata of several keys from cache * * $checkKeys holds the "check" keys used to validate values of applicable keys. * The integer indexes hold "check" keys that apply to all of $keys while the string * indexes hold "check" keys that only apply to the cache key with that name. * * @param string[] $keys List/map with makeKey()/makeGlobalKey() cache keys as values * @param string[]|string[][] $checkKeys Map of (integer or cache key => "check" key(s)); * "check" keys must also be made with makeKey()/makeGlobalKey() * @param float $now The current UNIX timestamp * @param callable|null $touchedCb Callback yielding a UNIX timestamp from a value, or null * @return array<string,array> Map of (key => WANObjectCache::RESULT_* map) in order of $keys * @note Callable type hints are not used to avoid class-autoloading */ protected function fetchKeys( array $keys, array $checkKeys, float $now, $touchedCb = null ) { $resByKey = []; // List of all sister keys that need to be fetched from cache $allSisterKeys = []; // Order-corresponding value sister key list for the base key list ($keys) $valueSisterKeys = []; // List of "check" sister keys to compare all value sister keys against $checkSisterKeysForAll = []; // Map of (base key => additional "check" sister key(s) to compare against) $checkSisterKeysByKey = []; foreach ( $keys as $key ) { $sisterKey = $this->makeSisterKey( $key, self::TYPE_VALUE ); $allSisterKeys[] = $sisterKey; $valueSisterKeys[] = $sisterKey; } foreach ( $checkKeys as $i => $checkKeyOrKeyGroup ) { // Note: avoid array_merge() inside loop in case there are many keys if ( is_int( $i ) ) { // Single "check" key that applies to all base keys $sisterKey = $this->makeSisterKey( $checkKeyOrKeyGroup, self::TYPE_TIMESTAMP ); $allSisterKeys[] = $sisterKey; $checkSisterKeysForAll[] = $sisterKey; } else { // List of "check" keys that apply to a specific base key foreach ( (array)$checkKeyOrKeyGroup as $checkKey ) { $sisterKey = $this->makeSisterKey( $checkKey, self::TYPE_TIMESTAMP ); $allSisterKeys[] = $sisterKey; $checkSisterKeysByKey[$i][] = $sisterKey; } } } if ( $this->warmupCache ) { // Get the wrapped values of the sister keys from the warmup cache $wrappedBySisterKey = $this->warmupCache; $sisterKeysMissing = array_diff( $allSisterKeys, array_keys( $wrappedBySisterKey ) ); if ( $sisterKeysMissing ) { $this->warmupKeyMisses += count( $sisterKeysMissing ); $wrappedBySisterKey += $this->cache->getMulti( $sisterKeysMissing ); } } else { // Fetch the wrapped values of the sister keys from the backend $wrappedBySisterKey = $this->cache->getMulti( $allSisterKeys ); } // List of "check" sister key purge timestamps to compare all value sister keys against $ckPurgesForAll = $this->processCheckKeys( $checkSisterKeysForAll, $wrappedBySisterKey, $now ); // Map of (base key => extra "check" sister key purge timestamp(s) to compare against) $ckPurgesByKey = []; foreach ( $checkSisterKeysByKey as $keyWithCheckKeys => $checkKeysForKey ) { $ckPurgesByKey[$keyWithCheckKeys] = $this->processCheckKeys( $checkKeysForKey, $wrappedBySisterKey, $now ); } // Unwrap and validate any value found for each base key (under the value sister key) reset( $keys ); foreach ( $valueSisterKeys as $valueSisterKey ) { // Get the corresponding base key for this value sister key $key = current( $keys ); next( $keys ); if ( array_key_exists( $valueSisterKey, $wrappedBySisterKey ) ) { // Key exists as either a live value or tombstone value $wrapped = $wrappedBySisterKey[$valueSisterKey]; } else { // Key does not exist $wrapped = false; } $res = $this->unwrap( $wrapped, $now ); $value = $res[self::RES_VALUE]; foreach ( array_merge( $ckPurgesForAll, $ckPurgesByKey[$key] ?? [] ) as $ckPurge ) { $res[self::RES_CHECK_AS_OF] = max( $ckPurge[self::PURGE_TIME], $res[self::RES_CHECK_AS_OF] ); // Timestamp marking the end of the hold-off period for this purge $holdoffDeadline = $ckPurge[self::PURGE_TIME] + $ckPurge[self::PURGE_HOLDOFF]; // Check if the value was generated during the hold-off period if ( $value !== false && $holdoffDeadline >= $res[self::RES_AS_OF] ) { // How long ago this value was purged by *this* "check" key $ago = min( $ckPurge[self::PURGE_TIME] - $now, self::TINY_NEGATIVE ); // How long ago this value was purged by *any* known "check" key $res[self::RES_CUR_TTL] = min( $res[self::RES_CUR_TTL], $ago ); } } if ( $touchedCb !== null && $value !== false ) { $touched = $touchedCb( $value ); if ( $touched !== null && $touched >= $res[self::RES_AS_OF] ) { $res[self::RES_CUR_TTL] = min( $res[self::RES_CUR_TTL], $res[self::RES_AS_OF] - $touched, self::TINY_NEGATIVE ); } } else { $touched = null; } $res[self::RES_TOUCH_AS_OF] = max( $res[self::RES_TOUCH_AS_OF], $touched ); $resByKey[$key] = $res; } return $resByKey; } /** * @param string[] $checkSisterKeys List of "check" sister keys * @param mixed[] $wrappedBySisterKey Preloaded map of (sister key => wrapped value) * @param float $now UNIX timestamp * @return array[] List of purge value arrays */ private function processCheckKeys( array $checkSisterKeys, array $wrappedBySisterKey, float $now ) { $purges = []; foreach ( $checkSisterKeys as $timeKey ) { $purge = isset( $wrappedBySisterKey[$timeKey] ) ? $this->parsePurgeValue( $wrappedBySisterKey[$timeKey] ) : null; if ( $purge === null ) { // No holdoff when lazy creating a check key, use cache right away (T344191) $wrapped = $this->makeCheckPurgeValue( $now, self::HOLDOFF_TTL_NONE, $purge ); $this->cache->add( $timeKey, $wrapped, self::CHECK_KEY_TTL, $this->cache::WRITE_BACKGROUND ); } $purges[] = $purge; } return $purges; } /** * Set the value of a key in cache * * Simply calling this method when source data changes is not valid because * the changes do not replicate to the other WAN sites. In that case, delete() * should be used instead. This method is intended for use on cache misses. * * If data was read using "view snapshots" (e.g. innodb REPEATABLE-READ), * use 'since' to avoid the following race condition: * - a) T1 starts * - b) T2 updates a row, calls delete(), and commits * - c) The HOLDOFF_TTL passes, expiring the delete() tombstone * - d) T1 reads the row and calls set() due to a cache miss * - e) Stale value is stuck in cache * * Setting 'lag' and 'since' help avoids keys getting stuck in stale states. * * Be aware that this does not update the process cache for getWithSetCallback() * callers. Keys accessed via that method are not generally meant to also be set * using this primitive method. * * Consider using getWithSetCallback(), which has cache slam avoidance and key * versioning features, instead of bare get()/set() calls. * * Do not use this method on versioned keys accessed via getWithSetCallback(). * * Example usage: * @code * $dbr = MediaWikiServices::getInstance()->getConnectionProvider()->getReplicaDatabase(); * $setOpts = Database::getCacheSetOptions( $dbr ); * // Fetch the row from the DB * $row = $dbr->selectRow( ... ); * $key = $cache->makeKey( 'building', $buildingId ); * $cache->set( $key, $row, $cache::TTL_DAY, $setOpts ); * @endcode * * @param string $key Cache key made with makeKey()/makeGlobalKey() * @param mixed $value Value to set for the cache key * @param int $ttl Seconds to live. Special values are: * - WANObjectCache::TTL_INDEFINITE: Cache forever (default) * - WANObjectCache::TTL_UNCACHEABLE: Do not cache (if the key exists, it is not deleted) * @param array $opts Options map: * - lag: Highest seconds of replication lag potentially affecting reads used to generate * the value. This should not be affected by the duration of transaction "view snapshots" * (e.g. innodb REPEATABLE-READ) nor the time elapsed since the first read (though both * increase staleness). For reads using view snapshots, only the replication lag during * snapshot initialization matters. Use false if replication is stopped/broken on a * replica server involved in the reads. * Default: 0 seconds * - since: UNIX timestamp indicative of the highest possible staleness caused by the * duration of transaction "view snapshots" (e.g. innodb REPEATABLE-READ) and the time * elapsed since the first read. This should not be affected by replication lag. * Default: 0 seconds * - pending: Whether this data is possibly from an uncommitted write transaction. * Generally, other threads should not see values from the future and * they certainly should not see ones that ended up getting rolled back. * Default: false * - lockTSE: If excessive replication/snapshot lag is detected, then store the value * with this TTL and flag it as stale. This is only useful if the reads for this key * use getWithSetCallback() with "lockTSE" set. Note that if "staleTTL" is set * then it will still add on to this TTL in the excessive lag scenario. * Default: WANObjectCache::TSE_NONE * - staleTTL: Seconds to keep the key around if it is stale. The get()/getMulti() * methods return such stale values with a $curTTL of 0, and getWithSetCallback() * will call the generation callback in such cases, passing in the old value * and its as-of time to the callback. This is useful if adaptiveTTL() is used * on the old value's as-of time when it is verified as still being correct. * Default: WANObjectCache::STALE_TTL_NONE * - segmentable: Allow partitioning of the value if it is a large string. * Default: false. * - creating: Optimize for the case where the key does not already exist. * Default: false * - version: Integer version number signifying the format of the value. * Default: null * - walltime: How long the value took to generate in seconds. Default: null * @phpcs:ignore Generic.Files.LineLength * @phan-param array{lag?:float|int,since?:float|int,pending?:bool,lockTSE?:int,staleTTL?:int,creating?:bool,version?:int,walltime?:int|float,segmentable?:bool} $opts * @note Options added in 1.28: staleTTL * @note Options added in 1.33: creating * @note Options added in 1.34: version, walltime * @note Options added in 1.40: segmentable * @return bool Success */ final public function set( $key, $value, $ttl = self::TTL_INDEFINITE, array $opts = [] ) { $keygroup = $this->determineKeyGroupForStats( $key ); $ok = $this->setMainValue( $key, $value, $ttl, $opts['version'] ?? null, $opts['walltime'] ?? null, $opts['lag'] ?? 0, $opts['since'] ?? null, $opts['pending'] ?? false, $opts['lockTSE'] ?? self::TSE_NONE, $opts['staleTTL'] ?? self::STALE_TTL_NONE, $opts['segmentable'] ?? false, $opts['creating'] ?? false ); $this->stats->getCounter( 'wanobjectcache_set_total' ) ->setLabel( 'keygroup', $keygroup ) ->setLabel( 'result', ( $ok ? 'ok' : 'error' ) ) ->copyToStatsdAt( "wanobjectcache.$keygroup.set." . ( $ok ? 'ok' : 'error' ) ) ->increment(); return $ok; } /** * @param string $key Cache key made with makeKey()/makeGlobalKey() * @param mixed $value * @param int|float $ttl * @param int|null $version * @param float|null $walltime * @param float|int|bool $dataReplicaLag * @param float|int|null $dataReadSince * @param bool $dataPendingCommit * @param int $lockTSE * @param int $staleTTL * @param bool $segmentable * @param bool $creating * @return bool Success */ private function setMainValue( $key, $value, $ttl, ?int $version, ?float $walltime, $dataReplicaLag, $dataReadSince, bool $dataPendingCommit, int $lockTSE, int $staleTTL, bool $segmentable, bool $creating ) { if ( $ttl < 0 ) { // not cacheable return true; } $now = $this->getCurrentTime(); $ttl = (int)$ttl; $walltime ??= $this->timeSinceLoggedMiss( $key, $now ); $dataSnapshotLag = ( $dataReadSince !== null ) ? max( 0, $now - $dataReadSince ) : 0; $dataCombinedLag = $dataReplicaLag + $dataSnapshotLag; // Forbid caching data that only exists within an uncommitted transaction. Also, lower // the TTL when the data has a "since" time so far in the past that a delete() tombstone, // made after that time, could have already expired (the key is no longer write-holed). // The mitigation TTL depends on whether this data lag is assumed to systemically effect // regeneration attempts in the near future. The TTL also reflects regeneration wall time. if ( $dataPendingCommit ) { // Case A: data comes from an uncommitted write transaction $mitigated = 'pending writes'; // Data might never be committed; rely on a less problematic regeneration attempt $mitigationTTL = self::TTL_UNCACHEABLE; } elseif ( $dataSnapshotLag > self::MAX_READ_LAG ) { // Case B: high snapshot lag $pregenSnapshotLag = ( $walltime !== null ) ? ( $dataSnapshotLag - $walltime ) : 0; if ( ( $pregenSnapshotLag + self::GENERATION_HIGH_SEC ) > self::MAX_READ_LAG ) { // Case B1: generation started when transaction duration was already long $mitigated = 'snapshot lag (late generation)'; // Probably non-systemic; rely on a less problematic regeneration attempt $mitigationTTL = self::TTL_UNCACHEABLE; } else { // Case B2: slow generation made transaction duration long $mitigated = 'snapshot lag (high generation time)'; // Probably systemic; use a low TTL to avoid stampedes/uncacheability $mitigationTTL = self::TTL_LAGGED; } } elseif ( $dataReplicaLag === false || $dataReplicaLag > self::MAX_READ_LAG ) { // Case C: low/medium snapshot lag with high replication lag $mitigated = 'replication lag'; // Probably systemic; use a low TTL to avoid stampedes/uncacheability $mitigationTTL = self::TTL_LAGGED; } elseif ( $dataCombinedLag > self::MAX_READ_LAG ) { $pregenCombinedLag = ( $walltime !== null ) ? ( $dataCombinedLag - $walltime ) : 0; // Case D: medium snapshot lag with medium replication lag if ( ( $pregenCombinedLag + self::GENERATION_HIGH_SEC ) > self::MAX_READ_LAG ) { // Case D1: generation started when read lag was too high $mitigated = 'read lag (late generation)'; // Probably non-systemic; rely on a less problematic regeneration attempt $mitigationTTL = self::TTL_UNCACHEABLE; } else { // Case D2: slow generation made read lag too high $mitigated = 'read lag (high generation time)'; // Probably systemic; use a low TTL to avoid stampedes/uncacheability $mitigationTTL = self::TTL_LAGGED; } } else { // Case E: new value generated with recent data $mitigated = null; // Nothing to mitigate $mitigationTTL = null; } if ( $mitigationTTL === self::TTL_UNCACHEABLE ) { $this->logger->warning( "Rejected set() for {cachekey} due to $mitigated.", [ 'cachekey' => $key, 'lag' => $dataReplicaLag, 'age' => $dataSnapshotLag, 'walltime' => $walltime ] ); // no-op the write for being unsafe return true; } // TTL to use in staleness checks (does not effect persistence layer TTL) $logicalTTL = null; if ( $mitigationTTL !== null ) { // New value was generated from data that is old enough to be risky if ( $lockTSE >= 0 ) { // Persist the value as long as normal, but make it count as stale sooner $logicalTTL = min( $ttl ?: INF, $mitigationTTL ); } else { // Persist the value for a shorter duration $ttl = min( $ttl ?: INF, $mitigationTTL ); } $this->logger->warning( "Lowered set() TTL for {cachekey} due to $mitigated.", [ 'cachekey' => $key, 'lag' => $dataReplicaLag, 'age' => $dataSnapshotLag, 'walltime' => $walltime ] ); } // Wrap that value with time/TTL/version metadata $wrapped = $this->wrap( $value, $logicalTTL ?: $ttl, $version, $now ); $storeTTL = $ttl + $staleTTL; $flags = $this->cache::WRITE_BACKGROUND; if ( $segmentable ) { $flags |= $this->cache::WRITE_ALLOW_SEGMENTS; } if ( $creating ) { $ok = $this->cache->add( $this->makeSisterKey( $key, self::TYPE_VALUE ), $wrapped, $storeTTL, $flags ); } else { $ok = $this->cache->merge( $this->makeSisterKey( $key, self::TYPE_VALUE ), static function ( $cache, $key, $cWrapped ) use ( $wrapped ) { // A string value means that it is a tombstone; do nothing in that case return ( is_string( $cWrapped ) ) ? false : $wrapped; }, $storeTTL, $this->cache::MAX_CONFLICTS_ONE, $flags ); } return $ok; } /** * Purge a key from all datacenters * * This should only be called when the underlying data (being cached) * changes in a significant way. This deletes the key and starts a hold-off * period where the key cannot be written to for a few seconds (HOLDOFF_TTL). * This is done to avoid the following race condition: * - a) Some DB data changes and delete() is called on a corresponding key * - b) A request refills the key with a stale value from a lagged DB * - c) The stale value is stuck there until the key is expired/evicted * * This is implemented by storing a special "tombstone" value at the cache * key that this class recognizes; get() calls will return false for the key * and any set() calls will refuse to replace tombstone values at the key. * For this to always avoid stale value writes, the following must hold: * - a) Replication lag is bounded to being less than HOLDOFF_TTL; or * - b) If lag is higher, the DB will have gone into read-only mode already * * Note that set() can also be lag-aware and lower the TTL if it's high. * * Be aware that this does not clear the process cache. Even if it did, callbacks * used by getWithSetCallback() might still return stale data in the case of either * uncommitted or not-yet-replicated changes (callback generally use replica DBs). * * When using potentially long-running ACID transactions, a good pattern is * to use a pre-commit hook to issue the delete(). This means that immediately * after commit, callers will see the tombstone in cache upon purge relay. * It also avoids the following race condition: * - a) T1 begins, changes a row, and calls delete() * - b) The HOLDOFF_TTL passes, expiring the delete() tombstone * - c) T2 starts, reads the row and calls set() due to a cache miss * - d) T1 finally commits * - e) Stale value is stuck in cache * * Example usage: * @code * $dbw->startAtomic( __METHOD__ ); // start of request * ... <execute some stuff> ... * // Update the row in the DB * $dbw->update( ... ); * $key = $cache->makeKey( 'homes', $homeId ); * // Purge the corresponding cache entry just before committing * $dbw->onTransactionPreCommitOrIdle( function() use ( $cache, $key ) { * $cache->delete( $key ); * } ); * ... <execute some stuff> ... * $dbw->endAtomic( __METHOD__ ); // end of request * @endcode * * The $ttl parameter can be used when purging values that have not actually changed * recently. For example, user-requested purges or cache cleanup scripts might not need * to invoke a hold-off period on cache backfills, so they can use HOLDOFF_TTL_NONE. * * Note that $ttl limits the effective range of 'lockTSE' for getWithSetCallback(). * * If called twice on the same key, then the last hold-off TTL takes precedence. For * idempotence, the $ttl should not vary for different delete() calls on the same key. * * @param string $key Cache key made with makeKey()/makeGlobalKey() * @param int $ttl Tombstone TTL; Default: WANObjectCache::HOLDOFF_TTL * @return bool True if the item was purged or not found, false on failure */ final public function delete( $key, $ttl = self::HOLDOFF_TTL ) { // Purge values must be stored under the value key so that WANObjectCache::set() // can atomically merge values without accidentally undoing a recent purge and thus // violating the holdoff TTL restriction. $valueSisterKey = $this->makeSisterKey( $key, self::TYPE_VALUE ); if ( $ttl <= 0 ) { // A client or cache cleanup script is requesting a cache purge, so there is no // volatility period due to replica DB lag. Any recent change to an entity cached // in this key should have triggered an appropriate purge event. $ok = $this->relayNonVolatilePurge( $valueSisterKey ); } else { // A cacheable entity recently changed, so there might be a volatility period due // to replica DB lag. Clients usually expect their actions to be reflected in any // of their subsequent web request. This is attainable if (a) purge relay lag is // lower than the time it takes for subsequent request by the client to arrive, // and, (b) DB replica queries have "read-your-writes" consistency due to DB lag // mitigation systems. $now = $this->getCurrentTime(); // Set the key to the purge value in all datacenters $purge = $this->makeTombstonePurgeValue( $now ); $ok = $this->relayVolatilePurge( $valueSisterKey, $purge, $ttl ); } $keygroup = $this->determineKeyGroupForStats( $key ); $this->stats->getCounter( 'wanobjectcache_delete_total' ) ->setLabel( 'keygroup', $keygroup ) ->setLabel( 'result', ( $ok ? 'ok' : 'error' ) ) ->copyToStatsdAt( "wanobjectcache.$keygroup.delete." . ( $ok ? 'ok' : 'error' ) ) ->increment(); return $ok; } /** * Fetch the value of a timestamp "check" key * * The key will be *initialized* to the current time if not set, * so only call this method if this behavior is actually desired * * The timestamp can be used to check whether a cached value is valid. * Callers should not assume that this returns the same timestamp in * all datacenters due to relay delays. * * The level of staleness can roughly be estimated from this key, but * if the key was evicted from cache, such calculations may show the * time since expiry as ~0 seconds. * * Note that "check" keys won't collide with other regular keys. * * @param string $key Cache key made with makeKey()/makeGlobalKey() * @return float UNIX timestamp */ final public function getCheckKeyTime( $key ) { return $this->getMultiCheckKeyTime( [ $key ] )[$key]; } /** * Fetch the values of each timestamp "check" key * * This works like getCheckKeyTime() except it takes a list of keys * and returns a map of timestamps instead of just that of one key * * This might be useful if both: * - a) a class of entities each depend on hundreds of other entities * - b) these other entities are depended upon by millions of entities * * The later entities can each use a "check" key to purge their dependee entities. * However, it is expensive for the former entities to verify against all of the relevant * "check" keys during each getWithSetCallback() call. A less expensive approach is to do * these verifications only after a "time-till-verify" (TTV) has passed. This is a middle * ground between using blind TTLs and using constant verification. The adaptiveTTL() method * can be used to dynamically adjust the TTV. Also, the initial TTV can make use of the * last-modified times of the dependent entities (either from the DB or the "check" keys). * * Example usage: * @code * $value = $cache->getWithSetCallback( * $cache->makeGlobalKey( 'wikibase-item', $id ), * self::INITIAL_TTV, // initial time-till-verify * function ( $oldValue, &$ttv, &$setOpts, $oldAsOf ) use ( $checkKeys, $cache ) { * $now = microtime( true ); * // Use $oldValue if it passes max ultimate age and "check" key comparisons * if ( $oldValue && * $oldAsOf > max( $cache->getMultiCheckKeyTime( $checkKeys ) ) && * ( $now - $oldValue['ctime'] ) <= self::MAX_CACHE_AGE * ) { * // Increase time-till-verify by 50% of last time to reduce overhead * $ttv = $cache->adaptiveTTL( $oldAsOf, self::MAX_TTV, self::MIN_TTV, 1.5 ); * // Unlike $oldAsOf, "ctime" is the ultimate age of the cached data * return $oldValue; * } * * $mtimes = []; // dependency last-modified times; passed by reference * $value = [ 'data' => $this->fetchEntityData( $mtimes ), 'ctime' => $now ]; * // Guess time-till-change among the dependencies, e.g. 1/(total change rate) * $ttc = 1 / array_sum( array_map( * function ( $mtime ) use ( $now ) { * return 1 / ( $mtime ? ( $now - $mtime ) : 900 ); * }, * $mtimes * ) ); * // The time-to-verify should not be overly pessimistic nor optimistic * $ttv = min( max( $ttc, self::MIN_TTV ), self::MAX_TTV ); * * return $value; * }, * [ 'staleTTL' => $cache::TTL_DAY ] // keep around to verify and re-save * ); * @endcode * * @see WANObjectCache::getCheckKeyTime() * @see WANObjectCache::getWithSetCallback() * * @param string[] $keys Cache keys made with makeKey()/makeGlobalKey() * @return float[] Map of (key => UNIX timestamp) * @since 1.31 */ final public function getMultiCheckKeyTime( array $keys ) { $checkSisterKeysByKey = []; foreach ( $keys as $key ) { $checkSisterKeysByKey[$key] = $this->makeSisterKey( $key, self::TYPE_TIMESTAMP ); } $wrappedBySisterKey = $this->cache->getMulti( $checkSisterKeysByKey ); $wrappedBySisterKey += array_fill_keys( $checkSisterKeysByKey, false ); $now = $this->getCurrentTime(); $times = []; foreach ( $checkSisterKeysByKey as $key => $checkSisterKey ) { $purge = $this->parsePurgeValue( $wrappedBySisterKey[$checkSisterKey] ); if ( $purge === null ) { $wrapped = $this->makeCheckPurgeValue( $now, self::HOLDOFF_TTL_NONE, $purge ); $this->cache->add( $checkSisterKey, $wrapped, self::CHECK_KEY_TTL, $this->cache::WRITE_BACKGROUND ); } $times[$key] = $purge[self::PURGE_TIME]; } return $times; } /** * Increase the last-purge timestamp of a "check" key in all datacenters * * This method should only be called when some heavily referenced data changes in * a significant way, such that it is impractical to call delete() on all the cache * keys that should be purged. The get*() method calls used to fetch these keys must * include the given "check" key in the relevant "check" keys argument/option. * * A "check" key essentially represents a last-modified time of an entity. When the * key is touched, the timestamp will be updated to the current time. Keys fetched * using get*() calls, that include the "check" key, will be seen as purged. * * The timestamp of the "check" key is treated as being HOLDOFF_TTL seconds in the * future by get*() methods in order to avoid race conditions where keys are updated * with stale values (e.g. from a lagged replica DB). A high TTL is set on the "check" * key, making it possible to know the timestamp of the last change to the corresponding * entities in most cases. This might use more cache space than resetCheckKey(). * * When a few important keys get a large number of hits, a high cache time is usually * desired as well as "lockTSE" logic. The resetCheckKey() method is less appropriate * in such cases since the "time since expiry" cannot be inferred, causing any get() * after the reset to treat the key as being "hot", resulting in more stale value usage. * * Note that "check" keys won't collide with other regular keys. * * @see WANObjectCache::get() * @see WANObjectCache::getWithSetCallback() * @see WANObjectCache::resetCheckKey() * * @param string $key Cache key made with makeKey()/makeGlobalKey() * @param int $holdoff HOLDOFF_TTL or HOLDOFF_TTL_NONE constant * @return bool True if the item was purged or not found, false on failure */ final public function touchCheckKey( $key, $holdoff = self::HOLDOFF_TTL ) { $checkSisterKey = $this->makeSisterKey( $key, self::TYPE_TIMESTAMP ); $now = $this->getCurrentTime(); $purge = $this->makeCheckPurgeValue( $now, $holdoff ); $ok = $this->relayVolatilePurge( $checkSisterKey, $purge, self::CHECK_KEY_TTL ); $keygroup = $this->determineKeyGroupForStats( $key ); $this->stats->getCounter( 'wanobjectcache_check_total' ) ->setLabel( 'keygroup', $keygroup ) ->setLabel( 'result', ( $ok ? 'ok' : 'error' ) ) ->copyToStatsdAt( "wanobjectcache.$keygroup.ck_touch." . ( $ok ? 'ok' : 'error' ) ) ->increment(); return $ok; } /** * Clear the last-purge timestamp of a "check" key in all datacenters * * Similar to touchCheckKey(), in that keys fetched using get*() calls, that include * the given "check" key, will be seen as purged. However, there are some differences: * - a) The "check" key will be deleted from all caches and lazily * re-initialized when accessed (rather than set everywhere) * - b) Thus, dependent keys will be known to be stale, but not * for how long (they are treated as "just" purged), which * effects any lockTSE logic in getWithSetCallback() * - c) Since "check" keys are initialized only on the server the key hashes * to, any temporary ejection of that server will cause the value to be * seen as purged as a new server will initialize the "check" key. * * The advantage over touchCheckKey() is that the "check" keys, which have high TTLs, * will only be created when a get*() method actually uses those keys. This is better * when a large number of "check" keys must be changed in a short period of time. * * Note that "check" keys won't collide with other regular keys. * * @see WANObjectCache::get() * @see WANObjectCache::getWithSetCallback() * @see WANObjectCache::touchCheckKey() * * @param string $key Cache key made with makeKey()/makeGlobalKey() * @return bool True if the item was purged or not found, false on failure */ final public function resetCheckKey( $key ) { $checkSisterKey = $this->makeSisterKey( $key, self::TYPE_TIMESTAMP ); $ok = $this->relayNonVolatilePurge( $checkSisterKey ); $keygroup = $this->determineKeyGroupForStats( $key ); $this->stats->getCounter( 'wanobjectcache_reset_total' ) ->setLabel( 'keygroup', $keygroup ) ->setLabel( 'result', ( $ok ? 'ok' : 'error' ) ) ->copyToStatsdAt( "wanobjectcache.$keygroup.ck_reset." . ( $ok ? 'ok' : 'error' ) ) ->increment(); return $ok; } /** * Method to fetch/regenerate a cache key * * On cache miss, the key will be set to the callback result via set() * (unless the callback returns false) and that result will be returned. * The arguments supplied to the callback are: * - $oldValue: prior cache value or false if none was present * - &$ttl: alterable reference to the TTL to be assigned to the new value * - &$setOpts: alterable reference to the set() options to be used with the new value * - $oldAsOf: generation UNIX timestamp of $oldValue or null if not present (since 1.28) * - $params: custom field/value map as defined by $cbParams (since 1.35) * * It is strongly recommended to set the 'lag' and 'since' fields to avoid race conditions * that can cause stale values to get stuck at keys. Usually, callbacks ignore the current * value, but it can be used to maintain "most recent X" values that come from time or * sequence based source data, provided that the "as of" id/time is tracked. Note that * preemptive regeneration and $checkKeys can result in a non-false current value. * * Usage of $checkKeys is similar to get() and getMulti(). However, rather than the caller * having to inspect a "current time left" variable (e.g. $curTTL, $curTTLs), a cache * regeneration will automatically be triggered using the callback. * * The $ttl argument and "hotTTR" option (in $opts) use time-dependent randomization * to avoid stampedes. Keys that are slow to regenerate and either heavily used * or subject to explicit (unpredictable) purges, may need additional mechanisms. * The simplest way to avoid stampedes for such keys is to use 'lockTSE' (in $opts). * If explicit purges are needed, also: * - a) Pass $key into $checkKeys * - b) Use touchCheckKey( $key ) instead of delete( $key ) * * This applies cache server I/O stampede protection against duplicate cache sets. * This is important when the callback is slow and/or yields large values for a key. * * Example usage (typical key): * @code * $catInfo = $cache->getWithSetCallback( * // Key to store the cached value under * $cache->makeKey( 'cat-attributes', $catId ), * // Time-to-live (in seconds) * $cache::TTL_MINUTE, * // Function that derives the new key value * function ( $oldValue, &$ttl, array &$setOpts ) { * $dbr = MediaWikiServices::getInstance()->getConnectionProvider()->getReplicaDatabase(); * // Account for any snapshot/replica DB lag * $setOpts += Database::getCacheSetOptions( $dbr ); * * return $dbr->selectRow( ... ); * } * ); * @endcode * * Example usage (key that is expensive and hot): * @code * $catConfig = $cache->getWithSetCallback( * // Key to store the cached value under * $cache->makeKey( 'site-cat-config' ), * // Time-to-live (in seconds) * $cache::TTL_DAY, * // Function that derives the new key value * function ( $oldValue, &$ttl, array &$setOpts ) { * $dbr = MediaWikiServices::getInstance()->getConnectionProvider()->getReplicaDatabase(); * // Account for any snapshot/replica DB lag * $setOpts += Database::getCacheSetOptions( $dbr ); * * return CatConfig::newFromRow( $dbr->selectRow( ... ) ); * }, * [ * // Calling touchCheckKey() on this key purges the cache * 'checkKeys' => [ $cache->makeKey( 'site-cat-config' ) ], * // Try to only let one datacenter thread manage cache updates at a time * 'lockTSE' => 30, * // Avoid querying cache servers multiple times in a web request * 'pcTTL' => $cache::TTL_PROC_LONG * ] * ); * @endcode * * Example usage (key with dynamic dependencies): * @code * $catState = $cache->getWithSetCallback( * // Key to store the cached value under * $cache->makeKey( 'cat-state', $cat->getId() ), * // Time-to-live (seconds) * $cache::TTL_HOUR, * // Function that derives the new key value * function ( $oldValue, &$ttl, array &$setOpts ) { * // Determine new value from the DB * $dbr = MediaWikiServices::getInstance()->getConnectionProvider()->getReplicaDatabase(); * // Account for any snapshot/replica DB lag * $setOpts += Database::getCacheSetOptions( $dbr ); * * return CatState::newFromResults( $dbr->select( ... ) ); * }, * [ * // The "check" keys that represent things the value depends on; * // Calling touchCheckKey() on any of them purges the cache * 'checkKeys' => [ * $cache->makeKey( 'sustenance-bowls', $cat->getRoomId() ), * $cache->makeKey( 'people-present', $cat->getHouseId() ), * $cache->makeKey( 'cat-laws', $cat->getCityId() ), * ] * ] * ); * @endcode * * Example usage (key that is expensive with too many DB dependencies for "check" keys): * @code * $catToys = $cache->getWithSetCallback( * // Key to store the cached value under * $cache->makeKey( 'cat-toys', $catId ), * // Time-to-live (seconds) * $cache::TTL_HOUR, * // Function that derives the new key value * function ( $oldValue, &$ttl, array &$setOpts ) { * // Determine new value from the DB * $dbr = MediaWikiServices::getInstance()->getConnectionProvider()->getReplicaDatabase(); * // Account for any snapshot/replica DB lag * $setOpts += Database::getCacheSetOptions( $dbr ); * * return CatToys::newFromResults( $dbr->select( ... ) ); * }, * [ * // Get the highest timestamp of any of the cat's toys * 'touchedCallback' => function ( $value ) use ( $catId ) { * $dbr = MediaWikiServices::getInstance()->getConnectionProvider()->getReplicaDatabase(); * $ts = $dbr->selectField( 'cat_toys', 'MAX(ct_touched)', ... ); * * return wfTimestampOrNull( TS_UNIX, $ts ); * }, * // Avoid DB queries for repeated access * 'pcTTL' => $cache::TTL_PROC_SHORT * ] * ); * @endcode * * Example usage (hot key holding most recent 100 events): * @code * $lastCatActions = $cache->getWithSetCallback( * // Key to store the cached value under * $cache->makeKey( 'cat-last-actions', 100 ), * // Time-to-live (in seconds) * 10, * // Function that derives the new key value * function ( $oldValue, &$ttl, array &$setOpts ) { * $dbr = MediaWikiServices::getInstance()->getConnectionProvider()->getReplicaDatabase(); * // Account for any snapshot/replica DB lag * $setOpts += Database::getCacheSetOptions( $dbr ); * * // Start off with the last cached list * $list = $oldValue ?: []; * // Fetch the last 100 relevant rows in descending order; * // only fetch rows newer than $list[0] to reduce scanning * $rows = iterator_to_array( $dbr->select( ... ) ); * // Merge them and get the new "last 100" rows * return array_slice( array_merge( $new, $list ), 0, 100 ); * }, * [ * // Try to only let one datacenter thread manage cache updates at a time * 'lockTSE' => 30, * // Use a magic value when no cache value is ready rather than stampeding * 'busyValue' => 'computing' * ] * ); * @endcode * * Example usage (key holding an LRU subkey:value map; this can avoid flooding cache with * keys for an unlimited set of (constraint,situation) pairs, thereby avoiding elevated * cache evictions and wasted memory): * @code * $catSituationTolerabilityCache = $this->cache->getWithSetCallback( * // Group by constraint ID/hash, cat family ID/hash, or something else useful * $this->cache->makeKey( 'cat-situation-tolerability-checks', $groupKey ), * WANObjectCache::TTL_DAY, // rarely used groups should fade away * // The $scenarioKey format is $constraintId:<ID/hash of $situation> * function ( $cacheMap ) use ( $scenarioKey, $constraintId, $situation ) { * $lruCache = MapCacheLRU::newFromArray( $cacheMap ?: [], self::CACHE_SIZE ); * $result = $lruCache->get( $scenarioKey ); // triggers LRU bump if present * if ( $result === null || $this->isScenarioResultExpired( $result ) ) { * $result = $this->checkScenarioTolerability( $constraintId, $situation ); * $lruCache->set( $scenarioKey, $result, 3 / 8 ); * } * // Save the new LRU cache map and reset the map's TTL * return $lruCache->toArray(); * }, * [ * // Once map is > 1 sec old, consider refreshing * 'ageNew' => 1, * // Update within 5 seconds after "ageNew" given a 1hz cache check rate * 'hotTTR' => 5, * // Avoid querying cache servers multiple times in a request; this also means * // that a request can only alter the value of any given constraint key once * 'pcTTL' => WANObjectCache::TTL_PROC_LONG * ] * ); * $tolerability = isset( $catSituationTolerabilityCache[$scenarioKey] ) * ? $catSituationTolerabilityCache[$scenarioKey] * : $this->checkScenarioTolerability( $constraintId, $situation ); * @endcode * * @see WANObjectCache::get() * @see WANObjectCache::set() * * @param string $key Cache key made with makeKey()/makeGlobalKey() * @param int $ttl Nominal seconds-to-live for newly computed values. Special values are: * - WANObjectCache::TTL_INDEFINITE: Cache forever (subject to LRU-style evictions) * - WANObjectCache::TTL_UNCACHEABLE: Do not cache (if the key exists, it is not deleted) * @param callable $callback Value generation function * @param array $opts Options map: * - checkKeys: List of "check" keys. The key at $key will be seen as stale when either * touchCheckKey() or resetCheckKey() is called on any of the keys in this list. This * is useful if thousands or millions of keys depend on the same entity. The entity can * simply have its "check" key updated whenever the entity is modified. * Default: []. * - graceTTL: If the key is stale due to a purge (by "checkKeys" or "touchedCallback") * less than this many seconds ago, consider reusing the stale value. The odds of a * refresh become more likely over time, becoming certain once the grace period is * reached. This can reduce traffic spikes when millions of keys are compared to the * same "check" key and touchCheckKey() or resetCheckKey() is called on that "check" key. * This option is not useful for avoiding traffic spikes in the case of the key simply * expiring on account of its TTL (use "lowTTL" instead). * Default: WANObjectCache::GRACE_TTL_NONE. * - lockTSE: If the value is stale and the "time since expiry" (TSE) is less than the given * number of seconds ago, then reuse the stale value if another such thread is already * regenerating the value. The TSE of the key is influenced by purges (e.g. via delete(), * "checkKeys", "touchedCallback"), and various other options (e.g. "staleTTL"). A low * enough TSE is assumed to indicate a high enough key access rate to justify stampede * avoidance. Note that no cache value exists after deletion, expiration, or eviction * at the storage-layer; to prevent stampedes during these cases, use "busyValue". * Default: WANObjectCache::TSE_NONE. * - busyValue: Specify a placeholder value to use when no value exists and another thread * is currently regenerating it. This assures that cache stampedes cannot happen if the * value falls out of cache. This also mitigates stampedes when value regeneration * becomes very slow (greater than $ttl/"lowTTL"). If this is a closure, then it will * be invoked to get the placeholder when needed. * Default: null. * - pcTTL: Process cache the value in this PHP instance for this many seconds. This avoids * network I/O when a key is read several times. This will not cache when the callback * returns false, however. Note that any purges will not be seen while process cached; * since the callback should use replica DBs and they may be lagged or have snapshot * isolation anyway, this should not typically matter. * Default: WANObjectCache::TTL_UNCACHEABLE. * - pcGroup: Process cache group to use instead of the primary one. If set, this must be * of the format ALPHANUMERIC_NAME:MAX_KEY_SIZE, e.g. "mydata:10". Use this for storing * large values, small yet numerous values, or some values with a high cost of eviction. * It is generally preferable to use a class constant when setting this value. * This has no effect unless pcTTL is used. * Default: WANObjectCache::PC_PRIMARY. * - version: Integer version number. This lets callers make breaking changes to the format * of cached values without causing problems for sites that use non-instantaneous code * deployments. Old and new code will recognize incompatible versions and purges from * both old and new code will been seen by each other. When this method encounters an * incompatibly versioned value at the provided key, a "variant key" will be used for * reading from and saving to cache. The variant key is specific to the key and version * number provided to this method. If the variant key value is older than that of the * provided key, or the provided key is non-existant, then the variant key will be seen * as non-existant. Therefore, delete() calls purge the provided key's variant keys. * The "checkKeys" and "touchedCallback" options still apply to variant keys as usual. * Avoid storing class objects, as this reduces compatibility (due to serialization). * Default: null. * - minAsOf: Reject values if they were generated before this UNIX timestamp. * This is useful if the source of a key is suspected of having possibly changed * recently, and the caller wants any such changes to be reflected. * Default: WANObjectCache::MIN_TIMESTAMP_NONE. * - hotTTR: Expected time-till-refresh (TTR) in seconds for keys that average ~1 hit per * second (e.g. 1Hz). Keys with a hit rate higher than 1Hz will refresh sooner than this * TTR and vise versa. Such refreshes won't happen until keys are "ageNew" seconds old. * This uses randomization to avoid triggering cache stampedes. The TTR is useful at * reducing the impact of missed cache purges, since the effect of a heavily referenced * key being stale is worse than that of a rarely referenced key. Unlike simply lowering * $ttl, seldomly used keys are largely unaffected by this option, which makes it * possible to have a high hit rate for the "long-tail" of less-used keys. * Default: WANObjectCache::HOT_TTR. * - lowTTL: Consider pre-emptive updates when the current TTL (seconds) of the key is less * than this. It becomes more likely over time, becoming certain once the key is expired. * This helps avoid cache stampedes that might be triggered due to the key expiring. * Default: WANObjectCache::LOW_TTL. * - ageNew: Consider popularity refreshes only once a key reaches this age in seconds. * Default: WANObjectCache::AGE_NEW. * - staleTTL: Seconds to keep the key around if it is stale. This means that on cache * miss the callback may get $oldValue/$oldAsOf values for keys that have already been * expired for this specified time. This is useful if adaptiveTTL() is used on the old * value's as-of time when it is verified as still being correct. * Default: WANObjectCache::STALE_TTL_NONE * - touchedCallback: A callback that takes the current value and returns a UNIX timestamp * indicating the last time a dynamic dependency changed. Null can be returned if there * are no relevant dependency changes to check. This can be used to check against things * like last-modified times of files or DB timestamp fields. This should generally not be * used for small and easily queried values in a DB if the callback itself ends up doing * a similarly expensive DB query to check a timestamp. Usages of this option makes the * most sense for values that are moderately to highly expensive to regenerate and easy * to query for dependency timestamps. The use of "pcTTL" reduces timestamp queries. * Default: null. * @param array $cbParams Custom field/value map to pass to the callback (since 1.35) * @phpcs:ignore Generic.Files.LineLength * @phan-param array{checkKeys?:string[],graceTTL?:int,lockTSE?:int,busyValue?:mixed,pcTTL?:int,pcGroup?:string,version?:int,minAsOf?:float|int,hotTTR?:int,lowTTL?:int,ageNew?:int,staleTTL?:int,touchedCallback?:callable} $opts * @return mixed Value found or written to the key * @note Options added in 1.28: version, busyValue, hotTTR, ageNew, pcGroup, minAsOf * @note Options added in 1.31: staleTTL, graceTTL * @note Options added in 1.33: touchedCallback * @note Callable type hints are not used to avoid class-autoloading */ final public function getWithSetCallback( $key, $ttl, $callback, array $opts = [], array $cbParams = [] ) { $version = $opts['version'] ?? null; $pcTTL = $opts['pcTTL'] ?? self::TTL_UNCACHEABLE; $pCache = ( $pcTTL >= 0 ) ? $this->getProcessCache( $opts['pcGroup'] ?? self::PC_PRIMARY ) : null; // Use the process cache if requested as long as no outer cache callback is running. // Nested callback process cache use is not lag-safe with regard to HOLDOFF_TTL since // process cached values are more lagged than persistent ones as they are not purged. if ( $pCache && $this->callbackDepth == 0 ) { $cached = $pCache->get( $key, $pcTTL, false ); if ( $cached !== false ) { $this->logger->debug( "getWithSetCallback($key): process cache hit" ); return $cached; } } [ $value, $valueVersion, $curAsOf ] = $this->fetchOrRegenerate( $key, $ttl, $callback, $opts, $cbParams ); if ( $valueVersion !== $version ) { // Current value has a different version; use the variant key for this version. // Regenerate the variant value if it is not newer than the main value at $key // so that purges to the main key propagate to the variant value. $this->logger->debug( "getWithSetCallback($key): using variant key" ); [ $value ] = $this->fetchOrRegenerate( $this->makeGlobalKey( 'WANCache-key-variant', md5( $key ), (string)$version ), $ttl, $callback, [ 'version' => null, 'minAsOf' => $curAsOf ] + $opts, $cbParams ); } // Update the process cache if enabled if ( $pCache && $value !== false ) { $pCache->set( $key, $value ); } return $value; } /** * Do the actual I/O for getWithSetCallback() when needed * * @see WANObjectCache::getWithSetCallback() * * @param string $key Cache key made with makeKey()/makeGlobalKey() * @param int $ttl * @param callable $callback * @param array $opts * @param array $cbParams * @return array Ordered list of the following: * - Cached or regenerated value * - Cached or regenerated value version number or null if not versioned * - Timestamp of the current cached value at the key or null if there is no value * @note Callable type hints are not used to avoid class-autoloading */ private function fetchOrRegenerate( $key, $ttl, $callback, array $opts, array $cbParams ) { $checkKeys = $opts['checkKeys'] ?? []; $graceTTL = $opts['graceTTL'] ?? self::GRACE_TTL_NONE; $minAsOf = $opts['minAsOf'] ?? self::MIN_TIMESTAMP_NONE; $hotTTR = $opts['hotTTR'] ?? self::HOT_TTR; $lowTTL = $opts['lowTTL'] ?? min( self::LOW_TTL, $ttl ); $ageNew = $opts['ageNew'] ?? self::AGE_NEW; $touchedCb = $opts['touchedCallback'] ?? null; $startTime = $this->getCurrentTime(); $keygroup = $this->determineKeyGroupForStats( $key ); // Get the current key value and its metadata $curState = $this->fetchKeys( [ $key ], $checkKeys, $startTime, $touchedCb )[$key]; $curValue = $curState[self::RES_VALUE]; // Use the cached value if it exists and is not due for synchronous regeneration if ( $this->isAcceptablyFreshValue( $curState, $graceTTL, $minAsOf ) ) { if ( !$this->isLotteryRefreshDue( $curState, $lowTTL, $ageNew, $hotTTR, $startTime ) ) { $this->stats->getTiming( 'wanobjectcache_getwithset_seconds' ) ->setLabel( 'keygroup', $keygroup ) ->setLabel( 'result', 'hit' ) ->setLabel( 'reason', 'good' ) ->copyToStatsdAt( "wanobjectcache.$keygroup.hit.good" ) ->observe( 1e3 * ( $this->getCurrentTime() - $startTime ) ); return [ $curValue, $curState[self::RES_VERSION], $curState[self::RES_AS_OF] ]; } elseif ( $this->scheduleAsyncRefresh( $key, $ttl, $callback, $opts, $cbParams ) ) { $this->logger->debug( "fetchOrRegenerate($key): hit with async refresh" ); $this->stats->getTiming( 'wanobjectcache_getwithset_seconds' ) ->setLabel( 'keygroup', $keygroup ) ->setLabel( 'result', 'hit' ) ->setLabel( 'reason', 'refresh' ) ->copyToStatsdAt( "wanobjectcache.$keygroup.hit.refresh" ) ->observe( 1e3 * ( $this->getCurrentTime() - $startTime ) ); return [ $curValue, $curState[self::RES_VERSION], $curState[self::RES_AS_OF] ]; } else { $this->logger->debug( "fetchOrRegenerate($key): hit with sync refresh" ); } } $isKeyTombstoned = ( $curState[self::RES_TOMB_AS_OF] !== null ); // Use the interim key as a temporary alternative if the key is tombstoned if ( $isKeyTombstoned ) { $volState = $this->getInterimValue( $key, $minAsOf, $startTime, $touchedCb ); $volValue = $volState[self::RES_VALUE]; } else { $volState = $curState; $volValue = $curValue; } // During the volatile "hold-off" period that follows a purge of the key, the value // will be regenerated many times if frequently accessed. This is done to mitigate // the effects of backend replication lag as soon as possible. However, throttle the // overhead of locking and regeneration by reusing values recently written to cache // tens of milliseconds ago. Verify the "as of" time against the last purge event. $lastPurgeTime = max( // RES_TOUCH_AS_OF depends on the value (possibly from the interim key) $volState[self::RES_TOUCH_AS_OF], $curState[self::RES_TOMB_AS_OF], $curState[self::RES_CHECK_AS_OF] ); $safeMinAsOf = max( $minAsOf, $lastPurgeTime + self::TINY_POSITIVE ); if ( $this->isExtremelyNewValue( $volState, $safeMinAsOf, $startTime ) ) { $this->logger->debug( "fetchOrRegenerate($key): volatile hit" ); $this->stats->getTiming( 'wanobjectcache_getwithset_seconds' ) ->setLabel( 'keygroup', $keygroup ) ->setLabel( 'result', 'hit' ) ->setLabel( 'reason', 'volatile' ) ->copyToStatsdAt( "wanobjectcache.$keygroup.hit.volatile" ) ->observe( 1e3 * ( $this->getCurrentTime() - $startTime ) ); return [ $volValue, $volState[self::RES_VERSION], $curState[self::RES_AS_OF] ]; } $lockTSE = $opts['lockTSE'] ?? self::TSE_NONE; $busyValue = $opts['busyValue'] ?? null; $staleTTL = $opts['staleTTL'] ?? self::STALE_TTL_NONE; $segmentable = $opts['segmentable'] ?? false; $version = $opts['version'] ?? null; // Determine whether one thread per datacenter should handle regeneration at a time $useRegenerationLock = // Note that since tombstones no-op set(), $lockTSE and $curTTL cannot be used to // deduce the key hotness because |$curTTL| will always keep increasing until the // tombstone expires or is overwritten by a new tombstone. Also, even if $lockTSE // is not set, constant regeneration of a key for the tombstone lifetime might be // very expensive. Assume tombstoned keys are possibly hot in order to reduce // the risk of high regeneration load after the delete() method is called. $isKeyTombstoned || // Assume a key is hot if requested soon ($lockTSE seconds) after purge. // This avoids stampedes when timestamps from $checkKeys/$touchedCb bump. ( $curState[self::RES_CUR_TTL] !== null && $curState[self::RES_CUR_TTL] <= 0 && abs( $curState[self::RES_CUR_TTL] ) <= $lockTSE ) || // Assume a key is hot if there is no value and a busy fallback is given. // This avoids stampedes on eviction or preemptive regeneration taking too long. ( $busyValue !== null && $volValue === false ); // If a regeneration lock is required, threads that do not get the lock will try to use // the stale value, the interim value, or the $busyValue placeholder, in that order. If // none of those are set then all threads will bypass the lock and regenerate the value. $hasLock = $useRegenerationLock && $this->claimStampedeLock( $key ); if ( $useRegenerationLock && !$hasLock ) { // Determine if there is stale or volatile cached value that is still usable // @phan-suppress-next-line PhanTypeMismatchArgumentNullable False positive if ( $this->isValid( $volValue, $volState[self::RES_AS_OF], $minAsOf ) ) { $this->logger->debug( "fetchOrRegenerate($key): returning stale value" ); $this->stats->getTiming( 'wanobjectcache_getwithset_seconds' ) ->setLabel( 'keygroup', $keygroup ) ->setLabel( 'result', 'hit' ) ->setLabel( 'reason', 'stale' ) ->copyToStatsdAt( "wanobjectcache.$keygroup.hit.stale" ) ->observe( 1e3 * ( $this->getCurrentTime() - $startTime ) ); return [ $volValue, $volState[self::RES_VERSION], $curState[self::RES_AS_OF] ]; } elseif ( $busyValue !== null ) { $miss = is_infinite( $minAsOf ) ? 'renew' : 'miss'; $this->logger->debug( "fetchOrRegenerate($key): busy $miss" ); $this->stats->getTiming( 'wanobjectcache_getwithset_seconds' ) ->setLabel( 'keygroup', $keygroup ) ->setLabel( 'result', $miss ) ->setLabel( 'reason', 'busy' ) ->copyToStatsdAt( "wanobjectcache.$keygroup.$miss.busy" ) ->observe( 1e3 * ( $this->getCurrentTime() - $startTime ) ); $placeholderValue = $this->resolveBusyValue( $busyValue ); return [ $placeholderValue, $version, $curState[self::RES_AS_OF] ]; } } // Generate the new value given any prior value with a matching version $setOpts = []; $preCallbackTime = $this->getCurrentTime(); ++$this->callbackDepth; // https://github.com/phan/phan/issues/4419 $value = null; try { $value = $callback( ( $curState[self::RES_VERSION] === $version ) ? $curValue : false, $ttl, $setOpts, ( $curState[self::RES_VERSION] === $version ) ? $curState[self::RES_AS_OF] : null, $cbParams ); } finally { --$this->callbackDepth; } $postCallbackTime = $this->getCurrentTime(); // How long it took to generate the value $walltime = max( $postCallbackTime - $preCallbackTime, 0.0 ); $this->stats->getTiming( 'wanobjectcache_regen_seconds' ) ->setLabel( 'keygroup', $keygroup ) ->copyToStatsdAt( "wanobjectcache.$keygroup.regen_walltime" ) ->observe( 1e3 * $walltime ); // Attempt to save the newly generated value if applicable if ( // Callback yielded a cacheable value ( $value !== false && $ttl >= 0 ) && // Current thread was not raced out of a regeneration lock or key is tombstoned ( !$useRegenerationLock || $hasLock || $isKeyTombstoned ) ) { // If the key is write-holed then use the (volatile) interim key as an alternative if ( $isKeyTombstoned ) { $this->setInterimValue( $key, $value, $lockTSE, $version, $segmentable ); } else { $this->setMainValue( $key, $value, $ttl, $version, $walltime, // @phan-suppress-next-line PhanCoalescingAlwaysNull $setOpts['lag'] ?? 0, // @phan-suppress-next-line PhanCoalescingAlwaysNull $setOpts['since'] ?? $preCallbackTime, // @phan-suppress-next-line PhanCoalescingAlwaysNull $setOpts['pending'] ?? false, $lockTSE, $staleTTL, $segmentable, ( $curValue === false ) ); } } $this->yieldStampedeLock( $key, $hasLock ); $miss = is_infinite( $minAsOf ) ? 'renew' : 'miss'; $this->logger->debug( "fetchOrRegenerate($key): $miss, new value computed" ); $this->stats->getTiming( 'wanobjectcache_getwithset_seconds' ) ->setLabel( 'keygroup', $keygroup ) ->setLabel( 'result', $miss ) ->setLabel( 'reason', 'compute' ) ->copyToStatsdAt( "wanobjectcache.$keygroup.$miss.compute" ) ->observe( 1e3 * ( $this->getCurrentTime() - $startTime ) ); return [ $value, $version, $curState[self::RES_AS_OF] ]; } /** * @param string $key Cache key made with makeKey()/makeGlobalKey() * @return bool Success */ private function claimStampedeLock( $key ) { $checkSisterKey = $this->makeSisterKey( $key, self::TYPE_MUTEX ); // Note that locking is not bypassed due to I/O errors; this avoids stampedes return $this->cache->add( $checkSisterKey, 1, self::LOCK_TTL ); } /** * @param string $key Cache key made with makeKey()/makeGlobalKey() * @param bool $hasLock */ private function yieldStampedeLock( $key, $hasLock ) { if ( $hasLock ) { $checkSisterKey = $this->makeSisterKey( $key, self::TYPE_MUTEX ); $this->cache->delete( $checkSisterKey, $this->cache::WRITE_BACKGROUND ); } } /** * Get sister keys that should be collocated with their corresponding base cache keys * * The key will bear the WANCache prefix and use the configured coalescing scheme * * @param string[] $baseKeys Cache keys made with makeKey()/makeGlobalKey() * @param string $type Consistent hashing agnostic suffix character matching [a-zA-Z] * @param string|null $route Routing prefix (optional) * @return string[] Order-corresponding list of sister keys */ private function makeSisterKeys( array $baseKeys, string $type, ?string $route = null ) { $sisterKeys = []; foreach ( $baseKeys as $baseKey ) { $sisterKeys[] = $this->makeSisterKey( $baseKey, $type, $route ); } return $sisterKeys; } /** * Get a sister key that should be collocated with a base cache key * * The keys will bear the WANCache prefix and use the configured coalescing scheme * * @param string $baseKey Cache key made with makeKey()/makeGlobalKey() * @param string $typeChar Consistent hashing agnostic suffix character matching [a-zA-Z] * @param string|null $route Routing prefix (optional) * @return string Sister key */ private function makeSisterKey( string $baseKey, string $typeChar, ?string $route = null ) { if ( $this->coalesceScheme === self::SCHEME_HASH_STOP ) { // Key style: "WANCache:<base key>|#|<character>" $sisterKey = 'WANCache:' . $baseKey . '|#|' . $typeChar; } else { // Key style: "WANCache:{<base key>}:<character>" $sisterKey = 'WANCache:{' . $baseKey . '}:' . $typeChar; } if ( $route !== null ) { $sisterKey = $this->prependRoute( $sisterKey, $route ); } return $sisterKey; } /** * Check if a key value is non-false, new enough, and has an "as of" time almost equal to now * * If the value was just written to cache, and it did not take an unusually long time to * generate, then it is probably not worth regenerating yet. For example, replica databases * might still return lagged pre-purge values anyway. * * @param array $res Current value WANObjectCache::RES_* data map * @param float $minAsOf Minimum acceptable value "as of" UNIX timestamp * @param float $now Current UNIX timestamp * @return bool Whether the age of a volatile value is negligible */ private function isExtremelyNewValue( $res, $minAsOf, $now ) { if ( $res[self::RES_VALUE] === false || $res[self::RES_AS_OF] < $minAsOf ) { return false; } $age = $now - $res[self::RES_AS_OF]; return ( $age < mt_rand( self::RECENT_SET_LOW_MS, self::RECENT_SET_HIGH_MS ) / 1e3 ); } /** * @param string $key Cache key made with makeKey()/makeGlobalKey() * @param float $minAsOf Minimum acceptable value "as of" UNIX timestamp * @param float $now Fetch time to determine "age" metadata * @param callable|null $touchedCb Function to find the max "dependency touched" UNIX timestamp * @return array<int,mixed> Result map/n-tuple from unwrap() * @phan-return array{0:mixed,1:mixed,2:?float,3:?int,4:?float,5:?float,6:?float,7:?float} * @note Callable type hints are not used to avoid class-autoloading */ private function getInterimValue( $key, $minAsOf, $now, $touchedCb ) { if ( $this->useInterimHoldOffCaching ) { $interimSisterKey = $this->makeSisterKey( $key, self::TYPE_INTERIM ); $wrapped = $this->cache->get( $interimSisterKey ); $res = $this->unwrap( $wrapped, $now ); if ( $res[self::RES_VALUE] !== false && $res[self::RES_AS_OF] >= $minAsOf ) { if ( $touchedCb !== null ) { // Update "last purge time" since the $touchedCb timestamp depends on $value // Get the new "touched timestamp", accounting for callback-checked dependencies $res[self::RES_TOUCH_AS_OF] = max( $touchedCb( $res[self::RES_VALUE] ), $res[self::RES_TOUCH_AS_OF] ); } return $res; } } return $this->unwrap( false, $now ); } /** * @param string $key Cache key made with makeKey()/makeGlobalKey() * @param mixed $value * @param int|float $ttl * @param int|null $version Value version number * @param bool $segmentable * @return bool Success */ private function setInterimValue( $key, $value, $ttl, ?int $version, bool $segmentable ) { $now = $this->getCurrentTime(); $ttl = max( self::INTERIM_KEY_TTL, (int)$ttl ); // Wrap that value with time/TTL/version metadata $wrapped = $this->wrap( $value, $ttl, $version, $now ); $flags = $this->cache::WRITE_BACKGROUND; if ( $segmentable ) { $flags |= $this->cache::WRITE_ALLOW_SEGMENTS; } return $this->cache->set( $this->makeSisterKey( $key, self::TYPE_INTERIM ), $wrapped, $ttl, $flags ); } /** * @param mixed $busyValue * @return mixed */ private function resolveBusyValue( $busyValue ) { return ( $busyValue instanceof Closure ) ? $busyValue() : $busyValue; } /** * Method to fetch multiple cache keys at once with regeneration * * This works the same as getWithSetCallback() except: * - a) The $keys argument must be the result of WANObjectCache::makeMultiKeys() * - b) The $callback argument expects a function that returns an entity value, using * boolean "false" if it does not exist. The callback takes the following arguments: * - $id: ID of the entity to query * - $oldValue: prior cache value or false if none was present * - &$ttl: reference to the TTL to be assigned to the new value (alterable) * - &$setOpts: reference to the new value set() options (alterable) * - $oldAsOf: generation UNIX timestamp of $oldValue or null if not present * - c) The return value is a map of (cache key => value) in the order of $keyedIds * * @see WANObjectCache::getWithSetCallback() * @see WANObjectCache::getMultiWithUnionSetCallback() * * Example usage: * @code * $rows = $cache->getMultiWithSetCallback( * // Map of cache keys to entity IDs * $cache->makeMultiKeys( * $this->fileVersionIds(), * function ( $id, $cache ) { * return $cache->makeKey( 'file-version', $id ); * } * ), * // Time-to-live (in seconds) * $cache::TTL_DAY, * // Function that derives the new key value * function ( $id, $oldValue, &$ttl, array &$setOpts ) { * $dbr = MediaWikiServices::getInstance()->getConnectionProvider()->getReplicaDatabase(); * // Account for any snapshot/replica DB lag * $setOpts += Database::getCacheSetOptions( $dbr ); * * // Load the row for this file * $queryInfo = File::getQueryInfo(); * $row = $dbr->selectRow( * $queryInfo['tables'], * $queryInfo['fields'], * [ 'id' => $id ], * __METHOD__, * [], * $queryInfo['joins'] * ); * * return $row ? (array)$row : false; * }, * [ * // Process cache for 30 seconds * 'pcTTL' => 30, * // Use a dedicated 500 item cache (initialized on-the-fly) * 'pcGroup' => 'file-versions:500' * ] * ); * $files = array_map( [ __CLASS__, 'newFromRow' ], $rows ); * @endcode * * @param ArrayIterator $keyedIds Result of WANObjectCache::makeMultiKeys() * @param int $ttl Seconds to live for key updates * @param callable $callback Callback that yields entity generation callbacks * @param array $opts Options map similar to that of getWithSetCallback() * @return mixed[] Map of (cache key => value) in the same order as $keyedIds * @since 1.28 */ final public function getMultiWithSetCallback( ArrayIterator $keyedIds, $ttl, callable $callback, array $opts = [] ) { // Batch load required keys into the in-process warmup cache $this->warmupCache = $this->fetchWrappedValuesForWarmupCache( $this->getNonProcessCachedMultiKeys( $keyedIds, $opts ), $opts['checkKeys'] ?? [] ); $this->warmupKeyMisses = 0; // The required callback signature includes $id as the first argument for convenience // to distinguish different items. To reuse the code in getWithSetCallback(), wrap the // callback with a proxy callback that has the standard getWithSetCallback() signature. // This is defined only once per batch to avoid closure creation overhead. $proxyCb = static function ( $oldValue, &$ttl, &$setOpts, $oldAsOf, $params ) use ( $callback ) { return $callback( $params['id'], $oldValue, $ttl, $setOpts, $oldAsOf ); }; // Get the order-preserved result map using the warm-up cache $values = []; foreach ( $keyedIds as $key => $id ) { $values[$key] = $this->getWithSetCallback( $key, $ttl, $proxyCb, $opts, [ 'id' => $id ] ); } $this->warmupCache = []; return $values; } /** * Method to fetch/regenerate multiple cache keys at once * * This works the same as getWithSetCallback() except: * - a) The $keys argument expects the result of WANObjectCache::makeMultiKeys() * - b) The $callback argument expects a function that returns a map of (ID => new value), * using boolean "false" for entities that could not be found, for all entity IDs in * $ids. The callback takes the following arguments: * - $ids: list of entity IDs that require value generation * - &$ttls: reference to the (entity ID => new TTL) map (alterable) * - &$setOpts: reference to the new value set() options (alterable) * - c) The return value is a map of (cache key => value) in the order of $keyedIds * - d) The "lockTSE" and "busyValue" options are ignored * * @see WANObjectCache::getWithSetCallback() * @see WANObjectCache::getMultiWithSetCallback() * * Example usage: * @code * $rows = $cache->getMultiWithUnionSetCallback( * // Map of cache keys to entity IDs * $cache->makeMultiKeys( * $this->fileVersionIds(), * function ( $id ) use ( $cache ) { * return $cache->makeKey( 'file-version', $id ); * } * ), * // Time-to-live (in seconds) * $cache::TTL_DAY, * // Function that derives the new key value * function ( array $ids, array &$ttls, array &$setOpts ) { * $dbr = MediaWikiServices::getInstance()->getConnectionProvider()->getReplicaDatabase(); * // Account for any snapshot/replica DB lag * $setOpts += Database::getCacheSetOptions( $dbr ); * * // Load the rows for these files * $rows = array_fill_keys( $ids, false ); * $queryInfo = File::getQueryInfo(); * $res = $dbr->select( * $queryInfo['tables'], * $queryInfo['fields'], * [ 'id' => $ids ], * __METHOD__, * [], * $queryInfo['joins'] * ); * foreach ( $res as $row ) { * $rows[$row->id] = $row; * $mtime = wfTimestamp( TS_UNIX, $row->timestamp ); * $ttls[$row->id] = $this->adaptiveTTL( $mtime, $ttls[$row->id] ); * } * * return $rows; * }, * ] * ); * $files = array_map( [ __CLASS__, 'newFromRow' ], $rows ); * @endcode * * @param ArrayIterator $keyedIds Result of WANObjectCache::makeMultiKeys() * @param int $ttl Seconds to live for key updates * @param callable $callback Callback that yields entity generation callbacks * @param array $opts Options map similar to that of getWithSetCallback() * @return mixed[] Map of (cache key => value) in the same order as $keyedIds * @since 1.30 */ final public function getMultiWithUnionSetCallback( ArrayIterator $keyedIds, $ttl, callable $callback, array $opts = [] ) { $checkKeys = $opts['checkKeys'] ?? []; $minAsOf = $opts['minAsOf'] ?? self::MIN_TIMESTAMP_NONE; // unset incompatible keys unset( $opts['lockTSE'] ); unset( $opts['busyValue'] ); // Batch load required keys into the in-process warmup cache $keysByIdGet = $this->getNonProcessCachedMultiKeys( $keyedIds, $opts ); $this->warmupCache = $this->fetchWrappedValuesForWarmupCache( $keysByIdGet, $checkKeys ); $this->warmupKeyMisses = 0; // IDs of entities known to be in need of generation $idsRegen = []; // Find out which keys are missing/deleted/stale $now = $this->getCurrentTime(); $resByKey = $this->fetchKeys( $keysByIdGet, $checkKeys, $now ); foreach ( $keysByIdGet as $id => $key ) { $res = $resByKey[$key]; if ( $res[self::RES_VALUE] === false || $res[self::RES_CUR_TTL] < 0 || $res[self::RES_AS_OF] < $minAsOf ) { $idsRegen[] = $id; } } // Run the callback to populate the generation value map for all required IDs $newSetOpts = []; $newTTLsById = array_fill_keys( $idsRegen, $ttl ); $newValsById = $idsRegen ? $callback( $idsRegen, $newTTLsById, $newSetOpts ) : []; $method = __METHOD__; // The required callback signature includes $id as the first argument for convenience // to distinguish different items. To reuse the code in getWithSetCallback(), wrap the // callback with a proxy callback that has the standard getWithSetCallback() signature. // This is defined only once per batch to avoid closure creation overhead. $proxyCb = function ( $oldValue, &$ttl, &$setOpts, $oldAsOf, $params ) use ( $callback, $newValsById, $newTTLsById, $newSetOpts, $method ) { $id = $params['id']; if ( array_key_exists( $id, $newValsById ) ) { // Value was already regenerated as expected, so use the value in $newValsById $newValue = $newValsById[$id]; $ttl = $newTTLsById[$id]; $setOpts = $newSetOpts; } else { // Pre-emptive/popularity refresh and version mismatch cases are not detected // above and thus $newValsById has no entry. Run $callback on this single entity. $ttls = [ $id => $ttl ]; $result = $callback( [ $id ], $ttls, $setOpts ); if ( !isset( $result[$id] ) ) { // T303092 $this->logger->warning( $method . ' failed due to {id} not set in result {result}', [ 'id' => $id, 'result' => json_encode( $result ) ] ); } $newValue = $result[$id]; $ttl = $ttls[$id]; } return $newValue; }; // Get the order-preserved result map using the warm-up cache $values = []; foreach ( $keyedIds as $key => $id ) { $values[$key] = $this->getWithSetCallback( $key, $ttl, $proxyCb, $opts, [ 'id' => $id ] ); } $this->warmupCache = []; return $values; } /** * @see BagOStuff::makeGlobalKey() * @since 1.27 * @param string $keygroup Key group component, should be under 48 characters. * @param string|int ...$components Additional, ordered, key components for entity IDs * @return string Colon-separated, keyspace-prepended, ordered list of encoded components */ public function makeGlobalKey( $keygroup, ...$components ) { return $this->cache->makeGlobalKey( $keygroup, ...$components ); } /** * @see BagOStuff::makeKey() * @since 1.27 * @param string $keygroup Key group component, should be under 48 characters. * @param string|int ...$components Additional, ordered, key components for entity IDs * @return string Colon-separated, keyspace-prepended, ordered list of encoded components */ public function makeKey( $keygroup, ...$components ) { return $this->cache->makeKey( $keygroup, ...$components ); } /** * Hash a possibly long string into a suitable component for makeKey()/makeGlobalKey() * * @param string $component A raw component used in building a cache key * @return string 64 character HMAC using a stable secret for public collision resistance * @since 1.34 */ public function hash256( $component ) { return hash_hmac( 'sha256', $component, $this->secret ); } /** * Get an iterator of (cache key => entity ID) for a list of entity IDs * * The $callback argument expects a function that returns the key for an entity ID via * makeKey()/makeGlobalKey(). There should be no network nor filesystem I/O used in the * callback. The entity ID/key mapping must be 1:1 or an exception will be thrown. Use * the hash256() method for any hashing. The callback takes the following arguments: * - $id: An entity ID * - $cache: This WANObjectCache instance * * Example usage for the default keyspace: * @code * $keyedIds = $cache->makeMultiKeys( * $modules, * function ( $module, $cache ) { * return $cache->makeKey( 'example-module', $module ); * } * ); * @endcode * * Example usage for mixed default and global keyspace: * @code * $keyedIds = $cache->makeMultiKeys( * $filters, * function ( $filter, $cache ) { * return self::isCentral( $filter ) * ? $cache->makeGlobalKey( 'example-filter', $filter ) * : $cache->makeKey( 'example-filter', $filter ) * } * ); * @endcode * * Example usage with hashing: * @code * $keyedIds = $cache->makeMultiKeys( * $urls, * function ( $url, $cache ) { * return $cache->makeKey( 'example-url', $cache->hash256( $url ) ); * } * ); * @endcode * * @see WANObjectCache::makeKey() * @see WANObjectCache::makeGlobalKey() * @see WANObjectCache::hash256() * * @param string[]|int[] $ids List of entity IDs * @param callable $keyCallback Function returning makeKey()/makeGlobalKey() on the input ID * @return ArrayIterator Iterator of (cache key => ID); order of $ids is preserved * @since 1.28 */ final public function makeMultiKeys( array $ids, $keyCallback ) { $idByKey = []; foreach ( $ids as $id ) { // Discourage triggering of automatic makeKey() hashing in some backends if ( strlen( $id ) > 64 ) { $this->logger->warning( __METHOD__ . ": long ID '$id'; use hash256()" ); } $key = $keyCallback( $id, $this ); // Edge case: ignore key collisions due to duplicate $ids like "42" and 42 if ( !isset( $idByKey[$key] ) ) { $idByKey[$key] = $id; } elseif ( (string)$id !== (string)$idByKey[$key] ) { throw new UnexpectedValueException( "Cache key collision; IDs ('$id','{$idByKey[$key]}') map to '$key'" ); } } return new ArrayIterator( $idByKey ); } /** * Get an (ID => value) map from (i) a non-unique list of entity IDs, and (ii) the list * of corresponding entity values by first appearance of each ID in the entity ID list * * For use with getMultiWithSetCallback() and getMultiWithUnionSetCallback(). * * *Only* use this method if the entity ID/key mapping is trivially 1:1 without exception. * Key generation method must utilize the *full* entity ID in the key (not a hash of it). * * Example usage: * @code * $poems = $cache->getMultiWithSetCallback( * $cache->makeMultiKeys( * $uuids, * function ( $uuid ) use ( $cache ) { * return $cache->makeKey( 'poem', $uuid ); * } * ), * $cache::TTL_DAY, * function ( $uuid ) use ( $url ) { * return $this->http->run( [ 'method' => 'GET', 'url' => "$url/$uuid" ] ); * } * ); * $poemsByUUID = $cache->multiRemap( $uuids, $poems ); * @endcode * * @see WANObjectCache::makeMultiKeys() * @see WANObjectCache::getMultiWithSetCallback() * @see WANObjectCache::getMultiWithUnionSetCallback() * * @param string[]|int[] $ids Entity ID list makeMultiKeys() * @param mixed[] $res Result of getMultiWithSetCallback()/getMultiWithUnionSetCallback() * @return mixed[] Map of (ID => value); order of $ids is preserved * @since 1.34 */ final public function multiRemap( array $ids, array $res ) { if ( count( $ids ) !== count( $res ) ) { // If makeMultiKeys() is called on a list of non-unique IDs, then the resulting // ArrayIterator will have less entries due to "first appearance" de-duplication $ids = array_keys( array_fill_keys( $ids, true ) ); if ( count( $ids ) !== count( $res ) ) { throw new UnexpectedValueException( "Multi-key result does not match ID list" ); } } return array_combine( $ids, $res ); } /** * Get a "watch point" token that can be used to get the "last error" to occur after now * * @return int A token that the current error event * @since 1.38 */ public function watchErrors() { return $this->cache->watchErrors(); } /** * Get the "last error" registry * * The method should be invoked by a caller as part of the following pattern: * - The caller invokes watchErrors() to get a "since token" * - The caller invokes a sequence of cache operation methods * - The caller invokes getLastError() with the "since token" * * External callers can also invoke this method as part of the following pattern: * - The caller invokes clearLastError() * - The caller invokes a sequence of cache operation methods * - The caller invokes getLastError() * * @param int $watchPoint Only consider errors from after this "watch point" [optional] * @return int BagOStuff:ERR_* constant for the "last error" registry * @note Parameters added in 1.38: $watchPoint */ final public function getLastError( $watchPoint = 0 ) { $code = $this->cache->getLastError( $watchPoint ); switch ( $code ) { case self::ERR_NONE: return self::ERR_NONE; case self::ERR_NO_RESPONSE: return self::ERR_NO_RESPONSE; case self::ERR_UNREACHABLE: return self::ERR_UNREACHABLE; default: return self::ERR_UNEXPECTED; } } /** * Clear the "last error" registry * @deprecated Since 1.38, hard deprecated in 1.43 */ final public function clearLastError() { wfDeprecated( __METHOD__, '1.38' ); $this->cache->clearLastError(); } /** * Clear the in-process caches; useful for testing * * @since 1.27 */ public function clearProcessCache() { $this->processCaches = []; } /** * Enable or disable the use of brief caching for tombstoned keys * * When a key is purged via delete(), there normally is a period where caching * is hold-off limited to an extremely short time. This method will disable that * caching, forcing the callback to run for any of: * - WANObjectCache::getWithSetCallback() * - WANObjectCache::getMultiWithSetCallback() * - WANObjectCache::getMultiWithUnionSetCallback() * * This is useful when both: * - a) the database used by the callback is known to be up-to-date enough * for some particular purpose (e.g. replica DB has applied transaction X) * - b) the caller needs to exploit that fact, and therefore needs to avoid the * use of inherently volatile and possibly stale interim keys * * @see WANObjectCache::delete() * @param bool $enabled Whether to enable interim caching * @since 1.31 */ final public function useInterimHoldOffCaching( $enabled ) { $this->useInterimHoldOffCaching = $enabled; } /** * @param int $flag ATTR_* class constant * @return int QOS_* class constant * @since 1.28 */ public function getQoS( $flag ) { return $this->cache->getQoS( $flag ); } /** * Get a TTL that is higher for objects that have not changed recently * * This is useful for keys that get explicit purges and DB or purge relay * lag is a potential concern (especially how it interacts with CDN cache) * * Example usage: * @code * // Last-modified time of page * $mtime = wfTimestamp( TS_UNIX, $page->getTimestamp() ); * // Get adjusted TTL. If $mtime is 3600 seconds ago and $minTTL/$factor left at * // defaults, then $ttl is 3600 * .2 = 720. If $minTTL was greater than 720, then * // $ttl would be $minTTL. If $maxTTL was smaller than 720, $ttl would be $maxTTL. * $ttl = $cache->adaptiveTTL( $mtime, $cache::TTL_DAY ); * @endcode * * Another use case is when there are no applicable "last modified" fields in the DB, * and there are too many dependencies for explicit purges to be viable, and the rate of * change to relevant content is unstable, and it is highly valued to have the cached value * be as up-to-date as possible. * * Example usage: * @code * $query = "<some complex query>"; * $idListFromComplexQuery = $cache->getWithSetCallback( * $cache->makeKey( 'complex-graph-query', $hashOfQuery ), * GraphQueryClass::STARTING_TTL, * function ( $oldValue, &$ttl, array &$setOpts, $oldAsOf ) use ( $query, $cache ) { * $gdb = $this->getReplicaGraphDbConnection(); * // Account for any snapshot/replica DB lag * $setOpts += GraphDatabase::getCacheSetOptions( $gdb ); * * $newList = iterator_to_array( $gdb->query( $query ) ); * sort( $newList, SORT_NUMERIC ); // normalize * * $minTTL = GraphQueryClass::MIN_TTL; * $maxTTL = GraphQueryClass::MAX_TTL; * if ( $oldValue !== false ) { * // Note that $oldAsOf is the last time this callback ran * $ttl = ( $newList === $oldValue ) * // No change: cache for 150% of the age of $oldValue * ? $cache->adaptiveTTL( $oldAsOf, $maxTTL, $minTTL, 1.5 ) * // Changed: cache for 50% of the age of $oldValue * : $cache->adaptiveTTL( $oldAsOf, $maxTTL, $minTTL, .5 ); * } * * return $newList; * }, * [ * // Keep stale values around for doing comparisons for TTL calculations. * // High values improve long-tail keys hit-rates, though might waste space. * 'staleTTL' => GraphQueryClass::GRACE_TTL * ] * ); * @endcode * * @param int|float|string|null $mtime UNIX timestamp; null if none * @param int $maxTTL Maximum TTL (seconds) * @param int $minTTL Minimum TTL (seconds); Default: 30 * @param float $factor Value in the range (0,1); Default: .2 * @return int Adaptive TTL * @since 1.28 */ public function adaptiveTTL( $mtime, $maxTTL, $minTTL = 30, $factor = 0.2 ) { // handle fractional seconds and string integers $mtime = (int)$mtime; if ( $mtime <= 0 ) { // no last-modified time provided return $minTTL; } $age = (int)$this->getCurrentTime() - $mtime; return (int)min( $maxTTL, max( $minTTL, $factor * $age ) ); } /** * @internal For use by unit tests only * @return int * @since 1.30 */ final public function getWarmupKeyMisses() { // Number of misses in $this->warmupCache during the last call to certain methods return $this->warmupKeyMisses; } /** * Set a sister key to a purge value in all datacenters * * This method should not wait for the operation to complete on remote datacenters * * Since older purge values can sometimes arrive after newer ones, use a relative expiry * so that even if the older value replaces the newer value, the TTL will greater than the * remaining TTL on the older value (assuming that all purges for a key use the same TTL). * * @param string $sisterKey A value key or "check" key * @param string $purgeValue Result of makeTombstonePurgeValue()/makeCheckKeyPurgeValue() * @param int $ttl Seconds to keep the purge value around * @return bool Success */ protected function relayVolatilePurge( string $sisterKey, string $purgeValue, int $ttl ) { if ( $this->broadcastRoute !== null ) { $routeKey = $this->prependRoute( $sisterKey, $this->broadcastRoute ); } else { $routeKey = $sisterKey; } return $this->cache->set( $routeKey, $purgeValue, $ttl, $this->cache::WRITE_BACKGROUND ); } /** * Remove a sister key from all datacenters * * This method should not wait for the operation to complete on remote datacenters * * @param string $sisterKey A value key or "check" key * @return bool Success */ protected function relayNonVolatilePurge( string $sisterKey ) { if ( $this->broadcastRoute !== null ) { $routeKey = $this->prependRoute( $sisterKey, $this->broadcastRoute ); } else { $routeKey = $sisterKey; } return $this->cache->delete( $routeKey, $this->cache::WRITE_BACKGROUND ); } /** * @param string $sisterKey * @param string $route Key routing prefix * @return string */ protected function prependRoute( string $sisterKey, string $route ) { if ( $sisterKey[0] === '/' ) { throw new RuntimeException( "Sister key '$sisterKey' already contains a route." ); } return $route . $sisterKey; } /** * Schedule a deferred cache regeneration if possible * * @param string $key Cache key made with makeKey()/makeGlobalKey() * @param int $ttl Seconds to live * @param callable $callback * @param array $opts * @param array $cbParams * @return bool Success * @note Callable type hints are not used to avoid class-autoloading */ private function scheduleAsyncRefresh( $key, $ttl, $callback, array $opts, array $cbParams ) { if ( !$this->asyncHandler ) { return false; } // Update the cache value later, such during post-send of an HTTP request. This forces // cache regeneration by setting "minAsOf" to infinity, meaning that no existing value // is considered valid. Furthermore, note that preemptive regeneration is not applicable // to invalid values, so there is no risk of infinite preemptive regeneration loops. $func = $this->asyncHandler; $func( function () use ( $key, $ttl, $callback, $opts, $cbParams ) { $opts['minAsOf'] = INF; try { $this->fetchOrRegenerate( $key, $ttl, $callback, $opts, $cbParams ); } catch ( Exception $e ) { // Log some context for easier debugging $this->logger->error( 'Async refresh failed for {key}', [ 'key' => $key, 'ttl' => $ttl, 'exception' => $e ] ); throw $e; } } ); return true; } /** * Check if a key value is non-false, new enough, and either fresh or "gracefully" stale * * @param array $res Current value WANObjectCache::RES_* data map * @param int $graceTTL Consider using stale values if $curTTL is greater than this * @param float $minAsOf Minimum acceptable value "as of" UNIX timestamp * @return bool */ private function isAcceptablyFreshValue( $res, $graceTTL, $minAsOf ) { if ( !$this->isValid( $res[self::RES_VALUE], $res[self::RES_AS_OF], $minAsOf ) ) { // Value does not exists or is too old return false; } $curTTL = $res[self::RES_CUR_TTL]; if ( $curTTL > 0 ) { // Value is definitely still fresh return true; } // Remaining seconds during which this stale value can be used $curGraceTTL = $graceTTL + $curTTL; return ( $curGraceTTL > 0 ) // Chance of using the value decreases as $curTTL goes from 0 to -$graceTTL ? !$this->worthRefreshExpiring( $curGraceTTL, $graceTTL, $graceTTL ) // Value is too stale to fall in the grace period : false; } /** * Check if a key is due for randomized regeneration due to near-expiration/popularity * * @param array $res Current value WANObjectCache::RES_* data map * @param float $lowTTL Consider a refresh when $curTTL is less than this; the "low" threshold * @param int $ageNew Age of key when this might recommend refreshing (seconds) * @param int $hotTTR Age of key when it should be refreshed if popular (seconds) * @param float $now The current UNIX timestamp * @return bool */ protected function isLotteryRefreshDue( $res, $lowTTL, $ageNew, $hotTTR, $now ) { $curTTL = $res[self::RES_CUR_TTL]; $logicalTTL = $res[self::RES_TTL]; $asOf = $res[self::RES_AS_OF]; return ( $this->worthRefreshExpiring( $curTTL, $logicalTTL, $lowTTL ) || $this->worthRefreshPopular( $asOf, $ageNew, $hotTTR, $now ) ); } /** * Check if a key is due for randomized regeneration due to its popularity * * This is used so that popular keys can preemptively refresh themselves for higher * consistency (especially in the case of purge loss/delay). Unpopular keys can remain * in cache with their high nominal TTL. This means popular keys keep good consistency, * whether the data changes frequently or not, and long-tail keys get to stay in cache * and get hits too. Similar to worthRefreshExpiring(), randomization is used. * * @param float $asOf UNIX timestamp of the value * @param int $ageNew Age of key when this might recommend refreshing (seconds) * @param int $timeTillRefresh Age of key when it should be refreshed if popular (seconds) * @param float $now The current UNIX timestamp * @return bool */ protected function worthRefreshPopular( $asOf, $ageNew, $timeTillRefresh, $now ) { if ( $ageNew < 0 || $timeTillRefresh <= 0 ) { return false; } $age = $now - $asOf; $timeOld = $age - $ageNew; if ( $timeOld <= 0 ) { return false; } $popularHitsPerSec = 1; // Lifecycle is: new, ramp-up refresh chance, full refresh chance. // Note that the "expected # of refreshes" for the ramp-up time range is half // of what it would be if P(refresh) was at its full value during that time range. $refreshWindowSec = max( $timeTillRefresh - $ageNew - self::RAMPUP_TTL / 2, 1 ); // P(refresh) * (# hits in $refreshWindowSec) = (expected # of refreshes) // P(refresh) * ($refreshWindowSec * $popularHitsPerSec) = 1 (by definition) // P(refresh) = 1/($refreshWindowSec * $popularHitsPerSec) $chance = 1 / ( $popularHitsPerSec * $refreshWindowSec ); // Ramp up $chance from 0 to its nominal value over RAMPUP_TTL seconds to avoid stampedes $chance *= ( $timeOld <= self::RAMPUP_TTL ) ? $timeOld / self::RAMPUP_TTL : 1; return ( mt_rand( 1, 1_000_000_000 ) <= 1_000_000_000 * $chance ); } /** * Check if a key is nearing expiration and thus due for randomized regeneration * * If $curTTL is greater than the "low" threshold (e.g. not nearing expiration) then this * returns false. If $curTTL <= 0 (e.g. value already expired), then this returns false. * Otherwise, the chance of this returning true increases steadily from 0% to 100% as * $curTTL moves from the "low" threshold down to 0 seconds. * * The logical TTL will be used as the "low" threshold if it is less than $lowTTL. * * This method uses deadline-aware randomization in order to handle wide variations * of cache access traffic without the need for configuration or expensive state. * * @param float $curTTL Approximate TTL left on the key * @param float $logicalTTL Full logical TTL assigned to the key; 0 for "infinite" * @param float $lowTTL Consider a refresh when $curTTL is less than this; the "low" threshold * @return bool */ protected function worthRefreshExpiring( $curTTL, $logicalTTL, $lowTTL ) { if ( $lowTTL <= 0 ) { return false; } // T264787: avoid having keys start off with a high chance of being refreshed; // the point where refreshing becomes possible cannot precede the key lifetime. $effectiveLowTTL = min( $lowTTL, $logicalTTL ?: INF ); // How long the value was in the "low TTL" phase $timeOld = $effectiveLowTTL - $curTTL; if ( $timeOld <= 0 || $timeOld >= $effectiveLowTTL ) { return false; } // Ratio of the low TTL phase that has elapsed (r) $ttrRatio = $timeOld / $effectiveLowTTL; // Use p(r) as the monotonically increasing "chance of refresh" function, // having p(0)=0 and p(1)=1. The value expires at the nominal expiry. $chance = $ttrRatio ** 4; return ( mt_rand( 1, 1_000_000_000 ) <= 1_000_000_000 * $chance ); } /** * Check that a wrapper value exists and has an acceptable age * * @param array|false $value Value wrapper or false * @param float $asOf Value generation "as of" timestamp * @param float $minAsOf Minimum acceptable value "as of" UNIX timestamp * @return bool */ protected function isValid( $value, $asOf, $minAsOf ) { return ( $value !== false && $asOf >= $minAsOf ); } /** * @param mixed $value * @param int $ttl Seconds to live or zero for "indefinite" * @param int|null $version Value version number or null if not versioned * @param float $now Unix Current timestamp just before calling set() * @return array */ private function wrap( $value, $ttl, $version, $now ) { // Returns keys in ascending integer order for PHP7 array packing: // https://nikic.github.io/2014/12/22/PHPs-new-hashtable-implementation.html $wrapped = [ self::FLD_FORMAT_VERSION => self::VERSION, self::FLD_VALUE => $value, self::FLD_TTL => $ttl, self::FLD_TIME => $now ]; if ( $version !== null ) { $wrapped[self::FLD_VALUE_VERSION] = $version; } return $wrapped; } /** * @param array|string|false $wrapped The entry at a cache key (false if key is nonexistant) * @param float $now Unix Current timestamp (preferably pre-query) * @return array<int,mixed> Result map/n-tuple that includes the following: * - WANObjectCache::RES_VALUE: value or false if absent/tombstoned/malformed * - WANObjectCache::KEY_VERSION: value version number; null if there is no value * - WANObjectCache::KEY_AS_OF: value generation timestamp (UNIX); null if there is no value * - WANObjectCache::KEY_TTL: assigned logical TTL (seconds); null if there is no value * - WANObjectCache::KEY_TOMB_AS_OF: tombstone timestamp (UNIX); null if not tombstoned * - WANObjectCache::RES_CHECK_AS_OF: null placeholder for highest "check" key timestamp * - WANObjectCache::RES_TOUCH_AS_OF: null placeholder for highest "touched" timestamp * - WANObjectCache::KEY_CUR_TTL: remaining logical TTL (seconds) (negative if tombstoned) * @phan-return array{0:mixed,1:mixed,2:?float,3:?int,4:?float,5:?float,6:?float,7:?float} */ private function unwrap( $wrapped, $now ) { // https://nikic.github.io/2014/12/22/PHPs-new-hashtable-implementation.html $res = [ // Attributes that only depend on the fetched key value self::RES_VALUE => false, self::RES_VERSION => null, self::RES_AS_OF => null, self::RES_TTL => null, self::RES_TOMB_AS_OF => null, // Attributes that depend on caller-specific "check" keys or "touched callbacks" self::RES_CHECK_AS_OF => null, self::RES_TOUCH_AS_OF => null, self::RES_CUR_TTL => null ]; if ( is_array( $wrapped ) ) { // Entry expected to be a cached value; validate it if ( ( $wrapped[self::FLD_FORMAT_VERSION] ?? null ) === self::VERSION && $wrapped[self::FLD_TIME] >= $this->epoch ) { if ( $wrapped[self::FLD_TTL] > 0 ) { // Get the approximate time left on the key $age = $now - $wrapped[self::FLD_TIME]; $curTTL = max( $wrapped[self::FLD_TTL] - $age, 0.0 ); } else { // Key had no TTL, so the time left is unbounded $curTTL = INF; } $res[self::RES_VALUE] = $wrapped[self::FLD_VALUE]; $res[self::RES_VERSION] = $wrapped[self::FLD_VALUE_VERSION] ?? null; $res[self::RES_AS_OF] = $wrapped[self::FLD_TIME]; $res[self::RES_CUR_TTL] = $curTTL; $res[self::RES_TTL] = $wrapped[self::FLD_TTL]; } } else { // Entry expected to be a tombstone; parse it $purge = $this->parsePurgeValue( $wrapped ); if ( $purge !== null ) { // Tombstoned keys should always have a negative "current TTL" $curTTL = min( $purge[self::PURGE_TIME] - $now, self::TINY_NEGATIVE ); $res[self::RES_CUR_TTL] = $curTTL; $res[self::RES_TOMB_AS_OF] = $purge[self::PURGE_TIME]; } } return $res; } /** * @param string $key Cache key in the format `<keyspace>:<keygroup>[:<other components>]...` * as formatted by WANObjectCache::makeKey() or ::makeKeyGlobal. * @return string The key group of this cache key */ private function determineKeyGroupForStats( $key ) { $parts = explode( ':', $key, 3 ); // Fallback in case the key was not made by makeKey. // Replace dots because they are special in StatsD (T232907) return strtr( $parts[1] ?? $parts[0], '.', '_' ); } /** * Extract purge metadata from cached value if it is a valid purge value * * Valid purge values come from makeTombstonePurgeValue()/makeCheckKeyPurgeValue() * * @param mixed $value Cached value * @return array|null Tuple of (UNIX timestamp, hold-off seconds); null if value is invalid */ private function parsePurgeValue( $value ) { if ( !is_string( $value ) ) { return null; } $segments = explode( ':', $value, 3 ); $prefix = $segments[0]; if ( $prefix !== self::PURGE_VAL_PREFIX ) { // Not a purge value return null; } $timestamp = (float)$segments[1]; // makeTombstonePurgeValue() doesn't store hold-off TTLs $holdoff = isset( $segments[2] ) ? (int)$segments[2] : self::HOLDOFF_TTL; if ( $timestamp < $this->epoch ) { // Purge value is too old return null; } return [ self::PURGE_TIME => $timestamp, self::PURGE_HOLDOFF => $holdoff ]; } /** * @param float $timestamp UNIX timestamp * @return string Wrapped purge value; format is "PURGED:<timestamp>" */ private function makeTombstonePurgeValue( float $timestamp ) { return self::PURGE_VAL_PREFIX . ':' . (int)$timestamp; } /** * @param float $timestamp UNIX timestamp * @param int $holdoff In seconds * @param array|null &$purge Unwrapped purge value array [returned] * @return string Wrapped purge value; format is "PURGED:<timestamp>:<holdoff>" */ private function makeCheckPurgeValue( float $timestamp, int $holdoff, ?array &$purge = null ) { $normalizedTime = (int)$timestamp; // Purge array that matches what parsePurgeValue() would have returned $purge = [ self::PURGE_TIME => (float)$normalizedTime, self::PURGE_HOLDOFF => $holdoff ]; return self::PURGE_VAL_PREFIX . ":$normalizedTime:$holdoff"; } /** * @param string $group * @return MapCacheLRU */ private function getProcessCache( $group ) { if ( !isset( $this->processCaches[$group] ) ) { [ , $size ] = explode( ':', $group ); $this->processCaches[$group] = new MapCacheLRU( (int)$size ); if ( $this->wallClockOverride !== null ) { $this->processCaches[$group]->setMockTime( $this->wallClockOverride ); } } return $this->processCaches[$group]; } /** * @param ArrayIterator $keys * @param array $opts * @return string[] Map of (ID => cache key) */ private function getNonProcessCachedMultiKeys( ArrayIterator $keys, array $opts ) { $pcTTL = $opts['pcTTL'] ?? self::TTL_UNCACHEABLE; $keysMissing = []; if ( $pcTTL > 0 && $this->callbackDepth == 0 ) { $pCache = $this->getProcessCache( $opts['pcGroup'] ?? self::PC_PRIMARY ); foreach ( $keys as $key => $id ) { if ( !$pCache->has( $key, $pcTTL ) ) { $keysMissing[$id] = $key; } } } return $keysMissing; } /** * @param string[] $keys Cache keys made with makeKey()/makeGlobalKey() * @param string[]|string[][] $checkKeys Map of (integer or cache key => "check" key(s)); * "check" keys must also be made with makeKey()/makeGlobalKey() * @return array<string,mixed> Map of (sister key => value, or, false if not found) */ private function fetchWrappedValuesForWarmupCache( array $keys, array $checkKeys ) { if ( !$keys ) { return []; } // Get all the value keys to fetch... $sisterKeys = $this->makeSisterKeys( $keys, self::TYPE_VALUE ); // Get all the "check" keys to fetch... foreach ( $checkKeys as $i => $checkKeyOrKeyGroup ) { // Note: avoid array_merge() inside loop in case there are many keys if ( is_int( $i ) ) { // Single "check" key that applies to all value keys $sisterKeys[] = $this->makeSisterKey( $checkKeyOrKeyGroup, self::TYPE_TIMESTAMP ); } else { // List of "check" keys that apply to a specific value key foreach ( (array)$checkKeyOrKeyGroup as $checkKey ) { $sisterKeys[] = $this->makeSisterKey( $checkKey, self::TYPE_TIMESTAMP ); } } } $wrappedBySisterKey = $this->cache->getMulti( $sisterKeys ); $wrappedBySisterKey += array_fill_keys( $sisterKeys, false ); return $wrappedBySisterKey; } /** * @param string $key Cache key made with makeKey()/makeGlobalKey() * @param float $now Current UNIX timestamp * @return float|null Seconds since the last logged get() miss for this key, or, null */ private function timeSinceLoggedMiss( $key, $now ) { // phpcs:ignore Generic.CodeAnalysis.AssignmentInCondition.Found for ( end( $this->missLog ); $miss = current( $this->missLog ); prev( $this->missLog ) ) { if ( $miss[0] === $key ) { return ( $now - $miss[1] ); } } return null; } /** * @return float UNIX timestamp * @codeCoverageIgnore */ protected function getCurrentTime() { return $this->wallClockOverride ?: microtime( true ); } /** * @param float|null &$time Mock UNIX timestamp for testing * @codeCoverageIgnore */ public function setMockTime( &$time ) { $this->wallClockOverride =& $time; $this->cache->setMockTime( $time ); foreach ( $this->processCaches as $pCache ) { $pCache->setMockTime( $time ); } } } /** @deprecated class alias since 1.43 */ class_alias( WANObjectCache::class, 'WANObjectCache' ); PK ! eA��� � objectcache/CachedBagOStuff.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\ObjectCache; /** * Wrap any BagOStuff and add an in-process memory cache to it. * * The differences between CachedBagOStuff and MultiWriteBagOStuff are: * - CachedBagOStuff supports only one "backend". * - There's a flag for writes to only go to the in-memory cache. * - The in-memory cache is always updated. * - Locks go to the backend cache (with MultiWriteBagOStuff, it would wind * up going to the HashBagOStuff used for the in-memory cache). * * @newable * @ingroup Cache */ class CachedBagOStuff extends BagOStuff { /** @var BagOStuff */ protected $store; /** @var HashBagOStuff */ protected $procCache; /** * @stable to call * * @param BagOStuff $backend Permanent backend to use * @param array $params Parameters for HashBagOStuff */ public function __construct( BagOStuff $backend, $params = [] ) { $params['keyspace'] = $backend->keyspace; parent::__construct( $params ); $this->store = $backend; $this->procCache = new HashBagOStuff( $params ); $this->attrMap = $backend->attrMap; } public function get( $key, $flags = 0 ) { $value = $this->procCache->get( $key, $flags ); if ( $value !== false || $this->procCache->hasKey( $key ) ) { return $value; } $value = $this->store->proxyCall( __FUNCTION__, self::ARG0_KEY, self::RES_NONKEY, func_get_args(), $this ); $this->set( $key, $value, self::TTL_INDEFINITE, self::WRITE_CACHE_ONLY ); return $value; } public function getMulti( array $keys, $flags = 0 ) { $valueByKeyCached = []; $keysFetch = []; foreach ( $keys as $key ) { $value = $this->procCache->get( $key, $flags ); if ( $value === false && !$this->procCache->hasKey( $key ) ) { $keysFetch[] = $key; } else { $valueByKeyCached[$key] = $value; } } $valueByKeyFetched = $this->store->proxyCall( __FUNCTION__, self::ARG0_KEYARR, self::RES_KEYMAP, [ $keysFetch, $flags ], $this ); $this->setMulti( $valueByKeyFetched, self::TTL_INDEFINITE, self::WRITE_CACHE_ONLY ); return $valueByKeyCached + $valueByKeyFetched; } public function set( $key, $value, $exptime = 0, $flags = 0 ) { $this->procCache->set( $key, $value, $exptime, $flags ); if ( $this->fieldHasFlags( $flags, self::WRITE_CACHE_ONLY ) ) { return true; } return $this->store->proxyCall( __FUNCTION__, self::ARG0_KEY, self::RES_NONKEY, func_get_args(), $this ); } public function delete( $key, $flags = 0 ) { $this->procCache->delete( $key, $flags ); if ( $this->fieldHasFlags( $flags, self::WRITE_CACHE_ONLY ) ) { return true; } return $this->store->proxyCall( __FUNCTION__, self::ARG0_KEY, self::RES_NONKEY, func_get_args(), $this ); } public function add( $key, $value, $exptime = 0, $flags = 0 ) { if ( $this->get( $key ) === false ) { return $this->set( $key, $value, $exptime, $flags ); } // key already set return false; } // These just call the backend (tested elsewhere) // @codeCoverageIgnoreStart public function merge( $key, callable $callback, $exptime = 0, $attempts = 10, $flags = 0 ) { $this->procCache->delete( $key ); return $this->store->proxyCall( __FUNCTION__, self::ARG0_KEY, self::RES_NONKEY, func_get_args(), $this ); } public function changeTTL( $key, $exptime = 0, $flags = 0 ) { $this->procCache->delete( $key ); return $this->store->proxyCall( __FUNCTION__, self::ARG0_KEY, self::RES_NONKEY, func_get_args(), $this ); } public function lock( $key, $timeout = 6, $exptime = 6, $rclass = '' ) { return $this->store->proxyCall( __FUNCTION__, self::ARG0_KEY, self::RES_NONKEY, func_get_args(), $this ); } public function unlock( $key ) { return $this->store->proxyCall( __FUNCTION__, self::ARG0_KEY, self::RES_NONKEY, func_get_args(), $this ); } public function deleteObjectsExpiringBefore( $timestamp, ?callable $progress = null, $limit = INF, ?string $tag = null ) { $this->procCache->deleteObjectsExpiringBefore( $timestamp, $progress, $limit, $tag ); return $this->store->proxyCall( __FUNCTION__, self::ARG0_NONKEY, self::RES_NONKEY, func_get_args(), $this ); } public function setMulti( array $valueByKey, $exptime = 0, $flags = 0 ) { $this->procCache->setMulti( $valueByKey, $exptime, $flags ); if ( $this->fieldHasFlags( $flags, self::WRITE_CACHE_ONLY ) ) { return true; } return $this->store->proxyCall( __FUNCTION__, self::ARG0_KEYMAP, self::RES_NONKEY, func_get_args(), $this ); } public function deleteMulti( array $keys, $flags = 0 ) { $this->procCache->deleteMulti( $keys, $flags ); if ( $this->fieldHasFlags( $flags, self::WRITE_CACHE_ONLY ) ) { return true; } return $this->store->proxyCall( __FUNCTION__, self::ARG0_KEYARR, self::RES_NONKEY, func_get_args(), $this ); } public function changeTTLMulti( array $keys, $exptime, $flags = 0 ) { $this->procCache->changeTTLMulti( $keys, $exptime, $flags ); if ( $this->fieldHasFlags( $flags, self::WRITE_CACHE_ONLY ) ) { return true; } return $this->store->proxyCall( __FUNCTION__, self::ARG0_KEYARR, self::RES_NONKEY, func_get_args(), $this ); } public function incrWithInit( $key, $exptime, $step = 1, $init = null, $flags = 0 ) { $this->procCache->delete( $key ); return $this->store->proxyCall( __FUNCTION__, self::ARG0_KEY, self::RES_NONKEY, func_get_args(), $this ); } public function setMockTime( &$time ) { parent::setMockTime( $time ); $this->procCache->setMockTime( $time ); $this->store->setMockTime( $time ); } // @codeCoverageIgnoreEnd } /** @deprecated class alias since 1.43 */ class_alias( CachedBagOStuff::class, 'CachedBagOStuff' ); PK ! �zJv@ @ " objectcache/MemcachedBagOStuff.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\ObjectCache; use Exception; use InvalidArgumentException; use RuntimeException; /** * Store data in a memcached server or memcached cluster. * * This is a base class for MemcachedPhpBagOStuff and MemcachedPeclBagOStuff. * * @ingroup Cache */ abstract class MemcachedBagOStuff extends MediumSpecificBagOStuff { /** @var string Routing prefix appended to keys during operations */ protected $routingPrefix; /** * @param array $params Additional parameters include: * - routingPrefix: a routing prefix of the form "<datacenter>/<cluster>/" used to convey * the location/strategy to use for handling keys accessed from this instance. The prefix * is prepended to keys during cache operations. The memcached proxy must preserve these * prefixes in any responses that include requested keys (e.g. get/gets). The proxy is * also assumed to strip the routing prefix from the stored key name, which allows for * unprefixed access. This can be used with mcrouter. [optional] */ public function __construct( array $params ) { $params['segmentationSize'] ??= 917_504; // < 1MiB parent::__construct( $params ); $this->routingPrefix = $params['routingPrefix'] ?? ''; // ...and does not use special disk-cache plugins $this->attrMap[self::ATTR_DURABILITY] = self::QOS_DURABILITY_SERVICE; } /** * Format a cache key. * * @since 1.27 * @see BagOStuff::makeKeyInternal * * @param string $keyspace * @param string[]|int[] $components * * @return string */ protected function makeKeyInternal( $keyspace, $components ) { // Memcached keys have a maximum length of 255 characters. From that, // subtract the number of characters we need for the keyspace and for // the separator character needed for each argument. To handle some // custom prefixes used by thing like WANObjectCache, limit to 205. $charsLeft = 205 - strlen( $keyspace ) - count( $components ); foreach ( $components as &$component ) { $component = strtr( $component, ' ', '_' ); // Make sure %, #, and non-ASCII chars are escaped $component = preg_replace_callback( '/[^\x21-\x22\x24\x26-\x39\x3b-\x7e]+/', static function ( $m ) { return rawurlencode( $m[0] ); }, $component ); // 33 = 32 characters for the MD5 + 1 for the '#' prefix. if ( $charsLeft > 33 && strlen( $component ) > $charsLeft ) { $component = '#' . md5( $component ); } $charsLeft -= strlen( $component ); } if ( $charsLeft < 0 ) { return $keyspace . ':BagOStuff-long-key:##' . md5( implode( ':', $components ) ); } return $keyspace . ':' . implode( ':', $components ); } protected function requireConvertGenericKey(): bool { return true; } /** * Ensure that a key is safe to use (contains no control characters and no * characters above the ASCII range.) * * @param string $key * * @return string * @throws Exception */ public function validateKeyEncoding( $key ) { if ( preg_match( '/[^\x21-\x7e]+/', $key ) ) { throw new InvalidArgumentException( "Key contains invalid characters: $key" ); } return $key; } /** * @param string $key * * @return string */ protected function validateKeyAndPrependRoute( $key ) { $this->validateKeyEncoding( $key ); if ( $this->routingPrefix === '' ) { return $key; } if ( $key[0] === '/' ) { throw new RuntimeException( "Key '$key' already contains a route." ); } return $this->routingPrefix . $key; } /** * @param string $key * * @return string */ protected function stripRouteFromKey( $key ) { if ( $this->routingPrefix === '' ) { return $key; } if ( str_starts_with( $key, $this->routingPrefix ) ) { return substr( $key, strlen( $this->routingPrefix ) ); } return $key; } /** * @param int|float $exptime * * @return int */ protected function fixExpiry( $exptime ) { if ( $exptime < 0 ) { // The PECL driver does not seem to like negative relative values $expiresAt = $this->getCurrentTime() + $exptime; } elseif ( $this->isRelativeExpiration( $exptime ) ) { // TTLs higher than 30 days will be detected as absolute TTLs // (UNIX timestamps), and will result in the cache entry being // discarded immediately because the expiry is in the past. // Clamp expires >30d at 30d, unless they're >=1e9 in which // case they are likely to really be absolute (1e9 = 2011-09-09) $expiresAt = min( $exptime, self::TTL_MONTH ); } else { $expiresAt = $exptime; } return (int)$expiresAt; } protected function doIncrWithInit( $key, $exptime, $step, $init, $flags ) { if ( $flags & self::WRITE_BACKGROUND ) { return $this->doIncrWithInitAsync( $key, $exptime, $step, $init ); } else { return $this->doIncrWithInitSync( $key, $exptime, $step, $init ); } } /** * @param string $key * @param int $exptime * @param int $step * @param int $init * * @return bool True on success, false on failure */ abstract protected function doIncrWithInitAsync( $key, $exptime, $step, $init ); /** * @param string $key * @param int $exptime * @param int $step * @param int $init * * @return int|bool New value or false on failure */ abstract protected function doIncrWithInitSync( $key, $exptime, $step, $init ); } /** @deprecated class alias since 1.43 */ class_alias( MemcachedBagOStuff::class, 'MemcachedBagOStuff' ); PK ! wj�i� � objectcache/IStoreKeyEncoder.phpnu �Iw�� <?php namespace Wikimedia\ObjectCache; /** * Key-encoding methods for object caching (BagOStuff and WANObjectCache) * * @ingroup Cache * @since 1.34 */ interface IStoreKeyEncoder { /** * @see BagOStuff::makeGlobalKey * * @param string $keygroup * @param string|int ...$components * * @return string */ public function makeGlobalKey( $keygroup, ...$components ); /** * @see BagOStuff::makeKey * * @param string $keygroup * @param string|int ...$components * * @return string */ public function makeKey( $keygroup, ...$components ); } /** @deprecated class alias since 1.43 */ class_alias( IStoreKeyEncoder::class, 'IStoreKeyEncoder' ); PK ! j2O%� � % objectcache/MemcachedPhpBagOStuff.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\ObjectCache; use MemcachedClient; /** * Store data on memcached servers(s) via a pure-PHP memcached client. * * In configuration, the CACHE_MEMCACHED will activate the MemcachedPhpBagOStuff * class. This works out of the box without any PHP extension or other PECL * dependencies. If you can install the php-memcached PECL extension, * it is recommended to use MemcachedPeclBagOStuff instead. * * @ingroup Cache */ class MemcachedPhpBagOStuff extends MemcachedBagOStuff { /** @var MemcachedClient */ protected $client; /** * Available parameters are: * - servers: The list of IP:port combinations holding the memcached servers. * - persistent: Whether to use a persistent connection * - compress_threshold: The minimum size an object must be before it is compressed * - timeout: The read timeout in microseconds * - connect_timeout: The connect timeout in seconds * * @param array $params */ public function __construct( $params ) { parent::__construct( $params ); // Default class-specific parameters $params += [ 'compress_threshold' => 1500, 'connect_timeout' => 0.5, 'timeout' => 500000, ]; $this->client = new MemcachedClient( $params ); $this->client->set_servers( $params['servers'] ); $this->client->set_debug( true ); } protected function doGet( $key, $flags = 0, &$casToken = null ) { $getToken = ( $casToken === self::PASS_BY_REF ); $casToken = null; $routeKey = $this->validateKeyAndPrependRoute( $key ); // T257003: only require "gets" (instead of "get") when a CAS token is needed $res = $getToken // @phan-suppress-next-line PhanTypeMismatchArgument False positive ? $this->client->get( $routeKey, $casToken ) : $this->client->get( $routeKey ); if ( $this->client->_last_cmd_status !== self::ERR_NONE ) { $this->setLastError( $this->client->_last_cmd_status ); } return $res; } protected function doSet( $key, $value, $exptime = 0, $flags = 0 ) { $routeKey = $this->validateKeyAndPrependRoute( $key ); $res = $this->client->set( $routeKey, $value, $this->fixExpiry( $exptime ) ); if ( $this->client->_last_cmd_status !== self::ERR_NONE ) { $this->setLastError( $this->client->_last_cmd_status ); } return $res; } protected function doDelete( $key, $flags = 0 ) { $routeKey = $this->validateKeyAndPrependRoute( $key ); $res = $this->client->delete( $routeKey ); if ( $this->client->_last_cmd_status !== self::ERR_NONE ) { $this->setLastError( $this->client->_last_cmd_status ); } return $res; } protected function doAdd( $key, $value, $exptime = 0, $flags = 0 ) { $routeKey = $this->validateKeyAndPrependRoute( $key ); $res = $this->client->add( $routeKey, $value, $this->fixExpiry( $exptime ) ); if ( $this->client->_last_cmd_status !== self::ERR_NONE ) { $this->setLastError( $this->client->_last_cmd_status ); } return $res; } protected function doCas( $casToken, $key, $value, $exptime = 0, $flags = 0 ) { $routeKey = $this->validateKeyAndPrependRoute( $key ); $res = $this->client->cas( $casToken, $routeKey, $value, $this->fixExpiry( $exptime ) ); if ( $this->client->_last_cmd_status !== self::ERR_NONE ) { $this->setLastError( $this->client->_last_cmd_status ); } return $res; } protected function doIncrWithInitAsync( $key, $exptime, $step, $init ) { $routeKey = $this->validateKeyAndPrependRoute( $key ); $watchPoint = $this->watchErrors(); $this->client->add( $routeKey, $init - $step, $this->fixExpiry( $exptime ) ); $this->client->incr( $routeKey, $step ); return !$this->getLastError( $watchPoint ); } protected function doIncrWithInitSync( $key, $exptime, $step, $init ) { $routeKey = $this->validateKeyAndPrependRoute( $key ); $watchPoint = $this->watchErrors(); $newValue = $this->client->incr( $routeKey, $step ) ?? false; if ( $newValue === false && !$this->getLastError( $watchPoint ) ) { // No key set; initialize $success = $this->client->add( $routeKey, $init, $this->fixExpiry( $exptime ) ); $newValue = $success ? $init : false; if ( $newValue === false && !$this->getLastError( $watchPoint ) ) { // Raced out initializing; increment $newValue = $this->client->incr( $routeKey, $step ) ?? false; } } return $newValue; } protected function doChangeTTL( $key, $exptime, $flags ) { $routeKey = $this->validateKeyAndPrependRoute( $key ); $res = $this->client->touch( $routeKey, $this->fixExpiry( $exptime ) ); if ( $this->client->_last_cmd_status !== self::ERR_NONE ) { $this->setLastError( $this->client->_last_cmd_status ); } return $res; } protected function doGetMulti( array $keys, $flags = 0 ) { $routeKeys = []; foreach ( $keys as $key ) { $routeKeys[] = $this->validateKeyAndPrependRoute( $key ); } $resByRouteKey = $this->client->get_multi( $routeKeys ); $res = []; foreach ( $resByRouteKey as $routeKey => $value ) { $res[$this->stripRouteFromKey( $routeKey )] = $value; } if ( $this->client->_last_cmd_status !== self::ERR_NONE ) { $this->setLastError( $this->client->_last_cmd_status ); } return $res; } protected function serialize( $value ) { return is_int( $value ) ? $value : $this->client->serialize( $value ); } protected function unserialize( $value ) { return $this->isInteger( $value ) ? (int)$value : $this->client->unserialize( $value ); } } /** @deprecated class alias since 1.43 */ class_alias( MemcachedPhpBagOStuff::class, 'MemcachedPhpBagOStuff' ); PK ! ^t��d� d� ' objectcache/MediumSpecificBagOStuff.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\ObjectCache; use InvalidArgumentException; use JsonSerializable; use stdClass; use Wikimedia\ObjectCache\Serialized\SerializedValueContainer; use Wikimedia\WaitConditionLoop; /** * Helper classs that implements most of BagOStuff for a backend. * * This should be used by concrete implementations only. Wrapper classes that * proxy another BagOStuff should extend and implement BagOStuff directly. * * @ingroup Cache * @since 1.34 */ abstract class MediumSpecificBagOStuff extends BagOStuff { /** @var array<string,array> Map of (key => (class LOCK_* constant => value) */ protected $locks = []; /** @var int Bytes; chunk size of segmented cache values */ protected $segmentationSize; /** @var int Bytes; maximum total size of a segmented cache value */ protected $segmentedValueMaxSize; /** @var float Seconds; maximum expected seconds for a lock ping to reach the backend */ protected $maxLockSendDelay = 0.05; /** @var array */ private $duplicateKeyLookups = []; /** @var bool */ private $reportDupes = false; /** @var bool */ private $dupeTrackScheduled = false; /** Component to use for key construction of blob segment keys */ private const SEGMENT_COMPONENT = 'segment'; /** Idiom for doGet() to return extra information by reference */ protected const PASS_BY_REF = -1; protected const METRIC_OP_GET = 'get'; protected const METRIC_OP_SET = 'set'; protected const METRIC_OP_DELETE = 'delete'; protected const METRIC_OP_CHANGE_TTL = 'change_ttl'; protected const METRIC_OP_ADD = 'add'; protected const METRIC_OP_INCR = 'incr'; protected const METRIC_OP_DECR = 'decr'; protected const METRIC_OP_CAS = 'cas'; protected const LOCK_RCLASS = 0; protected const LOCK_DEPTH = 1; protected const LOCK_TIME = 2; protected const LOCK_EXPIRY = 3; /** * @see BagOStuff::__construct() * Additional $params options include: * - logger: Psr\Log\LoggerInterface instance * - reportDupes: Whether to emit warning log messages for all keys that were * requested more than once (requires an asyncHandler). * - segmentationSize: The chunk size, in bytes, of segmented values. The value should * not exceed the maximum size of values in the storage backend, as configured by * the site administrator. * - segmentedValueMaxSize: The maximum total size, in bytes, of segmented values. * This should be configured to a reasonable size give the site traffic and the * amount of I/O between application and cache servers that the network can handle. * * @param array $params * * @phpcs:ignore Generic.Files.LineLength * @phan-param array{logger?:\Psr\Log\LoggerInterface,asyncHandler?:callable,reportDupes?:bool,segmentationSize?:int|float,segmentedValueMaxSize?:int} $params */ public function __construct( array $params = [] ) { parent::__construct( $params ); if ( !empty( $params['reportDupes'] ) && $this->asyncHandler ) { $this->reportDupes = true; } // Default to 8MiB if segmentationSize is not set $this->segmentationSize = $params['segmentationSize'] ?? 8_388_608; // Default to 64MiB if segmentedValueMaxSize is not set $this->segmentedValueMaxSize = $params['segmentedValueMaxSize'] ?? 67_108_864; } /** * Get an item with the given key * * If the key includes a deterministic input hash (e.g. the key can only have * the correct value) or complete staleness checks are handled by the caller * (e.g. nothing relies on the TTL), then the READ_VERIFIED flag should be set. * This lets tiered backends know they can safely upgrade a cached value to * higher tiers using standard TTLs. * * @param string $key * @param int $flags Bitfield of BagOStuff::READ_* constants [optional] * * @return mixed Returns false on failure or if the item does not exist */ public function get( $key, $flags = 0 ) { $this->trackDuplicateKeys( $key ); return $this->resolveSegments( $key, $this->doGet( $key, $flags ) ); } /** * Track the number of times that a given key has been used. * * @param string $key */ private function trackDuplicateKeys( $key ) { if ( !$this->reportDupes ) { return; } if ( !isset( $this->duplicateKeyLookups[$key] ) ) { // Track that we have seen this key. This N-1 counting style allows // easy filtering with array_filter() later. $this->duplicateKeyLookups[$key] = 0; } else { $this->duplicateKeyLookups[$key] += 1; if ( $this->dupeTrackScheduled === false ) { $this->dupeTrackScheduled = true; // Schedule a callback that logs keys processed more than once by get(). call_user_func( $this->asyncHandler, function () { $dups = array_filter( $this->duplicateKeyLookups ); foreach ( $dups as $key => $count ) { $this->logger->warning( 'Duplicate get(): "{key}" fetched {count} times', // Count is N-1 of the actual lookup count [ 'key' => $key, 'count' => $count + 1, ] ); } } ); } } } /** * Get an item * * The CAS token should be null if the key does not exist or the value is corrupt * * @param string $key * @param int $flags Bitfield of BagOStuff::READ_* constants [optional] * @param mixed &$casToken CAS token if MediumSpecificBagOStuff::PASS_BY_REF [returned] * * @return mixed Returns false on failure or if the item does not exist */ abstract protected function doGet( $key, $flags = 0, &$casToken = null ); public function set( $key, $value, $exptime = 0, $flags = 0 ) { $entry = $this->makeValueOrSegmentList( $key, $value, $exptime, $flags, $ok ); // Only when all segments (if any) are stored should the main key be changed return $ok && $this->doSet( $key, $entry, $exptime, $flags ); } /** * Set an item * * @param string $key * @param mixed $value * @param int $exptime Either an interval in seconds or a unix timestamp for expiry * @param int $flags Bitfield of BagOStuff::WRITE_* constants * * @return bool Success */ abstract protected function doSet( $key, $value, $exptime = 0, $flags = 0 ); public function delete( $key, $flags = 0 ) { if ( !$this->fieldHasFlags( $flags, self::WRITE_ALLOW_SEGMENTS ) ) { return $this->doDelete( $key, $flags ); } $mainValue = $this->doGet( $key, self::READ_LATEST ); if ( !$this->doDelete( $key, $flags ) ) { return false; } if ( !SerializedValueContainer::isSegmented( $mainValue ) ) { // no segments to delete return true; } $orderedKeys = array_map( function ( $segmentHash ) use ( $key ) { return $this->makeGlobalKey( self::SEGMENT_COMPONENT, $key, $segmentHash ); }, $mainValue->{SerializedValueContainer::SEGMENTED_HASHES} ); return $this->deleteMulti( $orderedKeys, $flags & ~self::WRITE_ALLOW_SEGMENTS ); } /** * Delete an item * * @param string $key * @param int $flags Bitfield of BagOStuff::WRITE_* constants * * @return bool True if the item was deleted or not found, false on failure */ abstract protected function doDelete( $key, $flags = 0 ); public function add( $key, $value, $exptime = 0, $flags = 0 ) { $entry = $this->makeValueOrSegmentList( $key, $value, $exptime, $flags, $ok ); // Only when all segments (if any) are stored should the main key be changed return $ok && $this->doAdd( $key, $entry, $exptime, $flags ); } /** * Insert an item if it does not already exist * * @param string $key * @param mixed $value * @param int $exptime * @param int $flags Bitfield of BagOStuff::WRITE_* constants (since 1.33) * * @return bool Success */ abstract protected function doAdd( $key, $value, $exptime = 0, $flags = 0 ); /** * Merge changes into the existing cache value (possibly creating a new one) * * The callback function returns the new value given the current value * (which will be false if not present), and takes the arguments: * (this BagOStuff, cache key, current value, TTL). * The TTL parameter is reference set to $exptime. It can be overridden in the callback. * Nothing is stored nor deleted if the callback returns false. * * @param string $key * @param callable $callback Callback method to be executed * @param int $exptime Either an interval in seconds or a unix timestamp for expiry * @param int $attempts The amount of times to attempt a merge in case of failure * @param int $flags Bitfield of BagOStuff::WRITE_* constants * * @return bool Success */ public function merge( $key, callable $callback, $exptime = 0, $attempts = 10, $flags = 0 ) { return $this->mergeViaCas( $key, $callback, $exptime, $attempts, $flags ); } /** * @param string $key * @param callable $callback Callback method to be executed * @param int $exptime Either an interval in seconds or a unix timestamp for expiry * @param int $attempts The amount of times to attempt a merge in case of failure * @param int $flags Bitfield of BagOStuff::WRITE_* constants * * @return bool Success * @see BagOStuff::merge() */ final protected function mergeViaCas( $key, callable $callback, $exptime, $attempts, $flags ) { $attemptsLeft = $attempts; do { $token = self::PASS_BY_REF; // Get the old value and CAS token from cache $watchPoint = $this->watchErrors(); $currentValue = $this->resolveSegments( $key, $this->doGet( $key, $flags, $token ) ); if ( $this->getLastError( $watchPoint ) ) { // Don't spam slow retries due to network problems (retry only on races) $this->logger->warning( __METHOD__ . ' failed due to read I/O error on get() for {key}.', [ 'key' => $key ] ); $success = false; break; } // Derive the new value from the old value $value = $callback( $this, $key, $currentValue, $exptime ); $keyWasNonexistent = ( $currentValue === false ); $valueMatchesOldValue = ( $value === $currentValue ); // free RAM in case the value is large unset( $currentValue ); $watchPoint = $this->watchErrors(); if ( $value === false || $exptime < 0 ) { // do nothing $success = true; } elseif ( $valueMatchesOldValue && $attemptsLeft !== $attempts ) { // recently set by another thread to the same value $success = true; } elseif ( $keyWasNonexistent ) { // Try to create the key, failing if it gets created in the meantime $success = $this->add( $key, $value, $exptime, $flags ); } else { // Try to update the key, failing if it gets changed in the meantime $success = $this->cas( $token, $key, $value, $exptime, $flags ); } if ( $this->getLastError( $watchPoint ) ) { // Don't spam slow retries due to network problems (retry only on races) $this->logger->warning( __METHOD__ . ' failed due to write I/O error for {key}.', [ 'key' => $key ] ); $success = false; break; } } while ( !$success && --$attemptsLeft ); return $success; } /** * Set an item if the current CAS token matches the provided CAS token * * @param mixed $casToken Only set the item if it still has this CAS token * @param string $key * @param mixed $value * @param int $exptime Either an interval in seconds or a unix timestamp for expiry * @param int $flags Bitfield of BagOStuff::WRITE_* constants * * @return bool Success */ protected function cas( $casToken, $key, $value, $exptime = 0, $flags = 0 ) { if ( $casToken === null ) { $this->logger->warning( __METHOD__ . ' got empty CAS token for {key}.', [ 'key' => $key ] ); // caller may have meant to use add()? return false; } $entry = $this->makeValueOrSegmentList( $key, $value, $exptime, $flags, $ok ); // Only when all segments (if any) are stored should the main key be changed return $ok && $this->doCas( $casToken, $key, $entry, $exptime, $flags ); } /** * Set an item if the current CAS token matches the provided CAS token * * @param mixed $casToken CAS token from an existing version of the key * @param string $key * @param mixed $value * @param int $exptime Either an interval in seconds or a unix timestamp for expiry * @param int $flags Bitfield of BagOStuff::WRITE_* constants * * @return bool Success */ protected function doCas( $casToken, $key, $value, $exptime = 0, $flags = 0 ) { // @TODO: the use of lock() assumes that all other relevant sets() use a lock if ( !$this->lock( $key, 0 ) ) { // non-blocking return false; } $curCasToken = self::PASS_BY_REF; $watchPoint = $this->watchErrors(); $exists = ( $this->doGet( $key, self::READ_LATEST, $curCasToken ) !== false ); if ( $this->getLastError( $watchPoint ) ) { // Fail if the old CAS token could not be read $success = false; $this->logger->warning( __METHOD__ . ' failed due to write I/O error for {key}.', [ 'key' => $key ] ); } elseif ( $exists && $this->tokensMatch( $casToken, $curCasToken ) ) { $success = $this->doSet( $key, $value, $exptime, $flags ); } else { // mismatched or failed $success = false; $this->logger->info( __METHOD__ . ' failed due to race condition for {key}.', [ 'key' => $key, 'key_exists' => $exists ] ); } $this->unlock( $key ); return $success; } /** * @param mixed $value CAS token for an existing key * @param mixed $otherValue CAS token for an existing key * * @return bool Whether the two tokens match */ final protected function tokensMatch( $value, $otherValue ) { $type = gettype( $value ); // Ideally, tokens are counters, timestamps, hashes, or serialized PHP values. // However, some classes might use the PHP values themselves. if ( $type !== gettype( $otherValue ) ) { return false; } // Serialize both tokens to strictly compare objects or arrays (which might objects // nested inside). Note that this will not apply if integer/string CAS tokens are used. if ( $type === 'array' || $type === 'object' ) { return ( serialize( $value ) === serialize( $otherValue ) ); } // For string/integer tokens, use a simple comparison return ( $value === $otherValue ); } /** * Change the expiration on a key if it exists * * If an expiry in the past is given then the key will immediately be expired * * For large values written using WRITE_ALLOW_SEGMENTS, this only changes the TTL of the * main segment list key. While lowering the TTL of the segment list key has the effect of * functionally lowering the TTL of the key, it might leave unused blobs in cache for longer. * Raising the TTL of such keys is not effective, since the expiration of a single segment * key effectively expires the entire value. * * @param string $key * @param int $exptime TTL or UNIX timestamp * @param int $flags Bitfield of BagOStuff::WRITE_* constants (since 1.33) * * @return bool Success Returns false on failure or if the item does not exist * @since 1.28 */ public function changeTTL( $key, $exptime = 0, $flags = 0 ) { return $this->doChangeTTL( $key, $exptime, $flags ); } /** * @param string $key * @param int $exptime * @param int $flags * * @return bool */ protected function doChangeTTL( $key, $exptime, $flags ) { // @TODO: the use of lock() assumes that all other relevant sets() use a lock if ( !$this->lock( $key, 0 ) ) { return false; } $expiry = $this->getExpirationAsTimestamp( $exptime ); $delete = ( $expiry != self::TTL_INDEFINITE && $expiry < $this->getCurrentTime() ); // Use doGet() to avoid having to trigger resolveSegments() $blob = $this->doGet( $key, self::READ_LATEST ); if ( $blob ) { if ( $delete ) { $ok = $this->doDelete( $key, $flags ); } else { $ok = $this->doSet( $key, $blob, $exptime, $flags ); } } else { $ok = false; } $this->unlock( $key ); return $ok; } public function incrWithInit( $key, $exptime, $step = 1, $init = null, $flags = 0 ) { $step = (int)$step; $init = is_int( $init ) ? $init : $step; return $this->doIncrWithInit( $key, $exptime, $step, $init, $flags ); } /** * @param string $key * @param int $exptime * @param int $step * @param int $init * @param int $flags * * @return int|bool New value or false on failure */ abstract protected function doIncrWithInit( $key, $exptime, $step, $init, $flags ); /** * @param string $key * @param int $timeout * @param int $exptime * @param string $rclass * * @return bool */ public function lock( $key, $timeout = 6, $exptime = 6, $rclass = '' ) { $exptime = min( $exptime ?: INF, self::TTL_DAY ); $acquired = false; if ( isset( $this->locks[$key] ) ) { // Already locked; avoid deadlocks and allow lock reentry if specified if ( $rclass != '' && $this->locks[$key][self::LOCK_RCLASS] === $rclass ) { ++$this->locks[$key][self::LOCK_DEPTH]; $acquired = true; } } else { // Not already locked; acquire a lock on the backend $lockTsUnix = $this->doLock( $key, $timeout, $exptime ); if ( $lockTsUnix !== null ) { $this->locks[$key] = [ self::LOCK_RCLASS => $rclass, self::LOCK_DEPTH => 1, self::LOCK_TIME => $lockTsUnix, self::LOCK_EXPIRY => $lockTsUnix + $exptime ]; $acquired = true; } } return $acquired; } /** * @see MediumSpecificBagOStuff::lock() * * @param string $key * @param int $timeout Lock wait timeout; 0 for non-blocking [optional] * @param int $exptime Lock time-to-live 1 day maximum [optional] * * @return float|null UNIX timestamp of acquisition; null on failure */ protected function doLock( $key, $timeout, $exptime ) { $lockTsUnix = null; $fname = __METHOD__; $loop = new WaitConditionLoop( function () use ( $key, $exptime, $fname, &$lockTsUnix ) { $watchPoint = $this->watchErrors(); if ( $this->add( $this->makeLockKey( $key ), 1, $exptime ) ) { $lockTsUnix = microtime( true ); return WaitConditionLoop::CONDITION_REACHED; } elseif ( $this->getLastError( $watchPoint ) ) { $this->logger->warning( "$fname failed due to I/O error for {key}.", [ 'key' => $key ] ); return WaitConditionLoop::CONDITION_ABORTED; } return WaitConditionLoop::CONDITION_CONTINUE; }, $timeout ); $code = $loop->invoke(); if ( $code === $loop::CONDITION_TIMED_OUT ) { $this->logger->warning( "$fname failed due to timeout for {key}.", [ 'key' => $key, 'timeout' => $timeout ] ); } return $lockTsUnix; } /** * Release an advisory lock on a key string * * @param string $key * * @return bool Success */ public function unlock( $key ) { $released = false; if ( isset( $this->locks[$key] ) ) { if ( --$this->locks[$key][self::LOCK_DEPTH] > 0 ) { $released = true; } else { $released = $this->doUnlock( $key ); unset( $this->locks[$key] ); if ( !$released ) { $this->logger->warning( __METHOD__ . ' failed to release lock for {key}.', [ 'key' => $key ] ); } } } else { $this->logger->warning( __METHOD__ . ' no lock to release for {key}.', [ 'key' => $key ] ); } return $released; } /** * @see MediumSpecificBagOStuff::unlock() * * @param string $key * * @return bool Success */ protected function doUnlock( $key ) { $released = false; // Estimate the remaining TTL of the lock key $curTTL = $this->locks[$key][self::LOCK_EXPIRY] - $this->getCurrentTime(); // Check the risk of race conditions for key deletion if ( $this->getQoS( self::ATTR_DURABILITY ) <= self::QOS_DURABILITY_SCRIPT ) { // Lock (and data) keys use memory specific to this request (e.g. HashBagOStuff) $isSafe = true; } else { // It is unsafe to delete the lock key if there is a serious risk of the key already // being claimed by another thread before the delete operation reaches the backend $isSafe = ( $curTTL > $this->maxLockSendDelay ); } if ( $isSafe ) { $released = $this->doDelete( $this->makeLockKey( $key ) ); } else { $this->logger->warning( "Lock for {key} held too long ({age} sec).", [ 'key' => $key, 'curTTL' => $curTTL ] ); } return $released; } /** * @param string $key * * @return string */ protected function makeLockKey( $key ) { return "$key:lock"; } public function deleteObjectsExpiringBefore( $timestamp, ?callable $progress = null, $limit = INF, ?string $tag = null ) { return false; } /** * Get an associative array containing the item for each of the keys that have items. * * @param string[] $keys List of keys; can be a map of (unused => key) for convenience * @param int $flags Bitfield; supports READ_LATEST [optional] * * @return mixed[] Map of (key => value) for existing keys; preserves the order of $keys */ public function getMulti( array $keys, $flags = 0 ) { $foundByKey = $this->doGetMulti( $keys, $flags ); $res = []; foreach ( $keys as $key ) { // Resolve one blob at a time (avoids too much I/O at once) if ( array_key_exists( $key, $foundByKey ) ) { // A value should not appear in the key if a segment is missing $value = $this->resolveSegments( $key, $foundByKey[$key] ); if ( $value !== false ) { $res[$key] = $value; } } } return $res; } /** * Get an associative array containing the item for each of the keys that have items. * * @param string[] $keys List of keys * @param int $flags Bitfield; supports READ_LATEST [optional] * * @return array Map of (key => value) for existing keys; preserves the order of $keys */ protected function doGetMulti( array $keys, $flags = 0 ) { $res = []; foreach ( $keys as $key ) { $val = $this->doGet( $key, $flags ); if ( $val !== false ) { $res[$key] = $val; } } return $res; } /** * Batch insertion/replace * * This does not support WRITE_ALLOW_SEGMENTS to avoid excessive read I/O * * @param mixed[] $valueByKey Map of (key => value) * @param int $exptime Either an interval in seconds or a unix timestamp for expiry * @param int $flags Bitfield of BagOStuff::WRITE_* constants (since 1.33) * * @return bool Success * @since 1.24 */ public function setMulti( array $valueByKey, $exptime = 0, $flags = 0 ) { if ( $this->fieldHasFlags( $flags, self::WRITE_ALLOW_SEGMENTS ) ) { throw new InvalidArgumentException( __METHOD__ . ' got WRITE_ALLOW_SEGMENTS' ); } return $this->doSetMulti( $valueByKey, $exptime, $flags ); } /** * @param mixed[] $data Map of (key => value) * @param int $exptime Either an interval in seconds or a unix timestamp for expiry * @param int $flags Bitfield of BagOStuff::WRITE_* constants * * @return bool Success */ protected function doSetMulti( array $data, $exptime = 0, $flags = 0 ) { $res = true; foreach ( $data as $key => $value ) { $res = $this->doSet( $key, $value, $exptime, $flags ) && $res; } return $res; } public function deleteMulti( array $keys, $flags = 0 ) { if ( $this->fieldHasFlags( $flags, self::WRITE_ALLOW_SEGMENTS ) ) { throw new InvalidArgumentException( __METHOD__ . ' got WRITE_ALLOW_SEGMENTS' ); } return $this->doDeleteMulti( $keys, $flags ); } /** * @param string[] $keys List of keys * @param int $flags Bitfield of BagOStuff::WRITE_* constants * * @return bool Success */ protected function doDeleteMulti( array $keys, $flags = 0 ) { $res = true; foreach ( $keys as $key ) { $res = $this->doDelete( $key, $flags ) && $res; } return $res; } /** * Change the expiration of multiple keys that exist * * @param string[] $keys List of keys * @param int $exptime TTL or UNIX timestamp * @param int $flags Bitfield of BagOStuff::WRITE_* constants (since 1.33) * * @return bool Success * * @since 1.34 */ public function changeTTLMulti( array $keys, $exptime, $flags = 0 ) { return $this->doChangeTTLMulti( $keys, $exptime, $flags ); } /** * @param string[] $keys List of keys * @param int $exptime TTL or UNIX timestamp * @param int $flags Bitfield of BagOStuff::WRITE_* constants * * @return bool Success */ protected function doChangeTTLMulti( array $keys, $exptime, $flags = 0 ) { $res = true; foreach ( $keys as $key ) { $res = $this->doChangeTTL( $key, $exptime, $flags ) && $res; } return $res; } /** * Get and reassemble the chunks of blob at the given key * * @param string $key * @param mixed $mainValue * * @return string|null|bool The combined string, false if missing, null on error */ final protected function resolveSegments( $key, $mainValue ) { if ( SerializedValueContainer::isSegmented( $mainValue ) ) { $orderedKeys = array_map( function ( $segmentHash ) use ( $key ) { return $this->makeGlobalKey( self::SEGMENT_COMPONENT, $key, $segmentHash ); }, $mainValue->{SerializedValueContainer::SEGMENTED_HASHES} ); $segmentsByKey = $this->doGetMulti( $orderedKeys ); $parts = []; foreach ( $orderedKeys as $segmentKey ) { if ( isset( $segmentsByKey[$segmentKey] ) ) { $parts[] = $segmentsByKey[$segmentKey]; } else { // missing segment return false; } } return $this->unserialize( implode( '', $parts ) ); } return $mainValue; } /** * Check if a value should use a segmentation wrapper due to its size * * In order to avoid extra serialization and/or twice-serialized wrappers, just check if * the value is a large string. Support cache wrappers (e.g. WANObjectCache) that use 2D * arrays to wrap values. This does not recurse in order to avoid overhead from complex * structures and the risk of infinite loops (due to references). * * @param mixed $value * @param int $flags * * @return bool */ private function useSegmentationWrapper( $value, $flags ) { if ( $this->segmentationSize === INF || !$this->fieldHasFlags( $flags, self::WRITE_ALLOW_SEGMENTS ) ) { return false; } if ( is_string( $value ) ) { return ( strlen( $value ) >= $this->segmentationSize ); } if ( is_array( $value ) ) { // Expect that the contained value will be one of the first array entries foreach ( array_slice( $value, 0, 4 ) as $v ) { if ( is_string( $v ) && strlen( $v ) >= $this->segmentationSize ) { return true; } } } // Avoid breaking functions for incrementing/decrementing integer key values return false; } /** * Make the entry to store at a key (inline or segment list), storing any segments * * @param string $key * @param mixed $value * @param int $exptime * @param int $flags * @param mixed|null &$ok Whether the entry is usable (e.g. no missing segments) [returned] * * @return mixed The entry (inline value, wrapped inline value, or wrapped segment list) * @since 1.34 */ final protected function makeValueOrSegmentList( $key, $value, $exptime, $flags, &$ok ) { $entry = $value; $ok = true; if ( $this->useSegmentationWrapper( $value, $flags ) ) { $segmentSize = $this->segmentationSize; $maxTotalSize = $this->segmentedValueMaxSize; $serialized = $this->getSerialized( $value, $key ); $size = strlen( $serialized ); if ( $size > $maxTotalSize ) { $this->logger->warning( "Value for {key} exceeds $maxTotalSize bytes; cannot segment.", [ 'key' => $key ] ); } else { // Split the serialized value into chunks and store them at different keys $chunksByKey = []; $segmentHashes = []; $count = intdiv( $size, $segmentSize ) + ( ( $size % $segmentSize ) ? 1 : 0 ); for ( $i = 0; $i < $count; ++$i ) { $segment = substr( $serialized, $i * $segmentSize, $segmentSize ); $hash = sha1( $segment ); $chunkKey = $this->makeGlobalKey( self::SEGMENT_COMPONENT, $key, $hash ); $chunksByKey[$chunkKey] = $segment; $segmentHashes[] = $hash; } $flags &= ~self::WRITE_ALLOW_SEGMENTS; $ok = $this->setMulti( $chunksByKey, $exptime, $flags ); $entry = SerializedValueContainer::newSegmented( $segmentHashes ); } } return $entry; } /** * @param int|float $exptime * * @return bool Whether the expiry is non-infinite, and, negative or not a UNIX timestamp * @since 1.34 */ final protected function isRelativeExpiration( $exptime ) { return ( $exptime !== self::TTL_INDEFINITE && $exptime < ( 10 * self::TTL_YEAR ) ); } /** * Convert an optionally relative timestamp to an absolute time * * The input value will be cast to an integer and interpreted as follows: * - zero: no expiry; return zero (e.g. TTL_INDEFINITE) * - negative: relative TTL; return UNIX timestamp offset by this value * - positive (< 10 years): relative TTL; return UNIX timestamp offset by this value * - positive (>= 10 years): absolute UNIX timestamp; return this value * * @param int $exptime * * @return int Expiration timestamp or TTL_INDEFINITE for indefinite * @since 1.34 */ final protected function getExpirationAsTimestamp( $exptime ) { if ( $exptime == self::TTL_INDEFINITE ) { return $exptime; } return $this->isRelativeExpiration( $exptime ) ? intval( $this->getCurrentTime() + $exptime ) : $exptime; } /** * Convert an optionally absolute expiry time to a relative time. If an * absolute time is specified which is in the past, use a short expiry time. * * The input value will be cast to an integer and interpreted as follows: * - zero: no expiry; return zero (e.g. TTL_INDEFINITE) * - negative: relative TTL; return a short expiry time (1 second) * - positive (< 10 years): relative TTL; return this value * - positive (>= 10 years): absolute UNIX timestamp; return offset to current time * * @param int $exptime * * @return int Relative TTL or TTL_INDEFINITE for indefinite * @since 1.34 */ final protected function getExpirationAsTTL( $exptime ) { if ( $exptime == self::TTL_INDEFINITE ) { return $exptime; } return $this->isRelativeExpiration( $exptime ) ? $exptime : (int)max( $exptime - $this->getCurrentTime(), 1 ); } /** * Check if a value is an integer * * @param mixed $value * * @return bool */ final protected function isInteger( $value ) { if ( is_int( $value ) ) { return true; } elseif ( !is_string( $value ) ) { return false; } $integer = (int)$value; return ( $value === (string)$integer ); } public function getQoS( $flag ) { return $this->attrMap[$flag] ?? self::QOS_UNKNOWN; } /** * @deprecated since 1.43, not used anywhere. */ public function getSegmentationSize() { wfDeprecated( __METHOD__, '1.43' ); return $this->segmentationSize; } /** * @deprecated since 1.43, not used anywhere. */ public function getSegmentedValueMaxSize() { wfDeprecated( __METHOD__, '1.43' ); return $this->segmentedValueMaxSize; } /** * Get the serialized form a value, logging a warning if it involves custom classes * * @param mixed $value * @param string $key * * @return string|int String/integer representation of value * @since 1.35 */ protected function getSerialized( $value, $key ) { $this->checkValueSerializability( $value, $key ); return $this->serialize( $value ); } /** * Log if a new cache value does not appear suitable for serialization at a quick glance * * This aids migration of values to JSON-like structures and the debugging of exceptions * due to serialization failure. * * This does not recurse more than one level into container structures. * * A proper cache key value is one of the following: * - null * - a scalar * - an array with scalar/null values * - an array tree with scalar/null "leaf" values * - an stdClass instance with scalar/null field values * - an stdClass instance tree with scalar/null "leaf" values * - an instance of a class that implements JsonSerializable * * @param mixed $value Result of the value generation callback for the key * @param string $key Cache key */ private function checkValueSerializability( $value, $key ) { if ( is_array( $value ) ) { $this->checkIterableMapSerializability( $value, $key ); } elseif ( is_object( $value ) ) { // Note that Closure instances count as objects if ( $value instanceof stdClass ) { $this->checkIterableMapSerializability( $value, $key ); } elseif ( !( $value instanceof JsonSerializable ) ) { $this->logger->warning( "{class} value for '{cachekey}'; serialization is suspect.", [ 'cachekey' => $key, 'class' => get_class( $value ) ] ); } } } /** * @param array|stdClass $value Result of the value generation callback for the key * @param string $key Cache key */ private function checkIterableMapSerializability( $value, $key ) { foreach ( $value as $index => $entry ) { if ( is_object( $entry ) ) { // Note that Closure instances count as objects if ( !( $entry instanceof \stdClass ) && !( $entry instanceof \JsonSerializable ) ) { $this->logger->warning( "{class} value for '{cachekey}' at '$index'; serialization is suspect.", [ 'cachekey' => $key, 'class' => get_class( $entry ) ] ); return; } } } } /** * @param mixed $value * * @return string|int|false String/integer representation * @note Special handling is usually needed for integers so incr()/decr() work */ protected function serialize( $value ) { return is_int( $value ) ? $value : serialize( $value ); } /** * @param string|int|false $value * * @return mixed Original value or false on error * @note Special handling is usually needed for integers so incr()/decr() work */ protected function unserialize( $value ) { return $this->isInteger( $value ) ? (int)$value : unserialize( $value ); } /** * @param string $text */ protected function debug( $text ) { $this->logger->debug( "{class} debug: $text", [ 'class' => static::class ] ); } /** * @param string $key Key generated by BagOStuff::makeKeyInternal * * @return string A stats prefix to describe this class of key (e.g. "objectcache.file") */ private function determinekeyGroupForStats( $key ): string { // Key came directly from BagOStuff::makeKey() or BagOStuff::makeGlobalKey() // and thus has the format of "<scope>:<collection>[:<constant or variable>]..." $components = explode( ':', $key, 3 ); // Handle legacy callers that fail to use the key building methods $keygroup = $components[1] ?? 'UNKNOWN'; return strtr( $keygroup, '.', '_' ); } /** * @param string $op Operation name as a MediumSpecificBagOStuff::METRIC_OP_* constant * @param array<int,string>|array<string,int[]> $keyInfo Key list, if payload sizes are not * applicable, otherwise, map of (key => (send payload size, receive payload size)); send * and receive sizes are 0 where not applicable and receive sizes are "false" for keys * that were not found during read operations */ protected function updateOpStats( string $op, array $keyInfo ) { $deltasByMetric = []; foreach ( $keyInfo as $indexOrKey => $keyOrSizes ) { if ( is_array( $keyOrSizes ) ) { $key = $indexOrKey; [ $sPayloadSize, $rPayloadSize ] = $keyOrSizes; } else { $key = $keyOrSizes; $sPayloadSize = 0; $rPayloadSize = 0; } // Metric prefix for the cache wrapper and key collection name $keygroup = $this->determinekeyGroupForStats( $key ); if ( $op === self::METRIC_OP_GET ) { // This operation was either a "hit" or "miss" for this key if ( $rPayloadSize === false ) { $statsdName = "objectcache.{$keygroup}.{$op}_miss_rate"; $statsName = "bagostuff_miss_total"; } else { $statsdName = "objectcache.{$keygroup}.{$op}_hit_rate"; $statsName = "bagostuff_hit_total"; } } else { // There is no concept of "hit" or "miss" for this operation $statsdName = "objectcache.{$keygroup}.{$op}_call_rate"; $statsName = "bagostuff_call_total"; } $deltasByMetric[$statsdName] = [ 'delta' => ( $deltasByMetric[$statsdName]['delta'] ?? 0 ) + 1, 'metric' => $statsName, 'keygroup' => $keygroup, 'operation' => $op, ]; if ( $sPayloadSize > 0 ) { $statsdName = "objectcache.{$keygroup}.{$op}_bytes_sent"; $statsName = "bagostuff_bytes_sent_total"; $deltasByMetric[$statsdName] = [ 'delta' => ( $deltasByMetric[$statsdName]['delta'] ?? 0 ) + $sPayloadSize, 'metric' => $statsName, 'keygroup' => $keygroup, 'operation' => $op, ]; } if ( $rPayloadSize > 0 ) { $statsdName = "objectcache.{$keygroup}.{$op}_bytes_read"; $statsName = "bagostuff_bytes_read_total"; $deltasByMetric[$statsdName] = [ 'delta' => ( $deltasByMetric[$statsdName]['delta'] ?? 0 ) + $rPayloadSize, 'metric' => $statsName, 'keygroup' => $keygroup, 'operation' => $op, ]; } } foreach ( $deltasByMetric as $statsdName => $delta ) { $this->stats->getCounter( $delta['metric'] ) ->setLabel( 'keygroup', $delta['keygroup'] ) ->setLabel( 'operation', $delta['operation'] ) ->copyToStatsdAt( $statsdName ) ->incrementBy( $delta['delta'] ); } } } /** @deprecated class alias since 1.43 */ class_alias( MediumSpecificBagOStuff::class, 'MediumSpecificBagOStuff' ); PK ! �bt@ @ & objectcache/MemcachedPeclBagOStuff.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\ObjectCache; use Memcached; use RuntimeException; use UnexpectedValueException; use Wikimedia\ScopedCallback; /** * Store data on memcached server(s) via the php-memcached PECL extension. * * To use memcached out of the box without any PECL dependency, use the * MemcachedPhpBagOStuff class instead. * * @ingroup Cache */ class MemcachedPeclBagOStuff extends MemcachedBagOStuff { /** @var Memcached */ protected $client; /** * Available parameters are: * - servers: List of IP:port combinations holding the memcached servers. * - persistent: Whether to use a persistent connection * - compress_threshold: The minimum size an object must be before it is compressed * - timeout: The read timeout in microseconds * - connect_timeout: The connect timeout in seconds * - retry_timeout: Time in seconds to wait before retrying a failed connect attempt * - server_failure_limit: Limit for server connect failures before it is removed * - serializer: Either "php" or "igbinary". Igbinary produces more compact * values, but serialization is much slower unless the php.ini * option igbinary.compact_strings is off. * - use_binary_protocol Whether to enable the binary protocol (default is ASCII) * - allow_tcp_nagle_delay Whether to permit Nagle's algorithm for reducing packet count * * @param array $params */ public function __construct( $params ) { parent::__construct( $params ); // Default class-specific parameters $params += [ 'compress_threshold' => 1500, 'connect_timeout' => 0.5, 'timeout' => 500_000, 'serializer' => 'php', 'use_binary_protocol' => false, 'allow_tcp_nagle_delay' => true ]; if ( $params['persistent'] ) { // The pool ID must be unique to the server/option combination. // The Memcached object is essentially shared for each pool ID. // We can only reuse a pool ID if we keep the config consistent. $connectionPoolId = md5( serialize( $params ) ); $client = new Memcached( $connectionPoolId ); } else { $client = new Memcached(); } $this->initializeClient( $client, $params ); $this->client = $client; // The compression threshold is an undocumented php.ini option for some // reason. There's probably not much harm in setting it globally, for // compatibility with the settings for the PHP client. ini_set( 'memcached.compression_threshold', $params['compress_threshold'] ); } /** * Initialize the client only if needed and reuse it otherwise. * This avoids duplicate servers in the list and new connections. * * @param Memcached $client * @param array $params * * @throws RuntimeException */ private function initializeClient( Memcached $client, array $params ) { if ( $client->getServerList() ) { $this->logger->debug( __METHOD__ . ": pre-initialized client instance." ); return; // preserve persistent handle } $this->logger->debug( __METHOD__ . ": initializing new client instance." ); $options = [ Memcached::OPT_NO_BLOCK => false, Memcached::OPT_BUFFER_WRITES => false, Memcached::OPT_NOREPLY => false, // Network protocol (ASCII or binary) Memcached::OPT_BINARY_PROTOCOL => $params['use_binary_protocol'], // Set various network timeouts Memcached::OPT_CONNECT_TIMEOUT => $params['connect_timeout'] * 1000, Memcached::OPT_SEND_TIMEOUT => $params['timeout'], Memcached::OPT_RECV_TIMEOUT => $params['timeout'], Memcached::OPT_POLL_TIMEOUT => $params['timeout'] / 1000, // Avoid pointless delay when sending/fetching large blobs Memcached::OPT_TCP_NODELAY => !$params['allow_tcp_nagle_delay'], // Set libketama mode since it's recommended by the documentation Memcached::OPT_LIBKETAMA_COMPATIBLE => true ]; if ( isset( $params['retry_timeout'] ) ) { $options[Memcached::OPT_RETRY_TIMEOUT] = $params['retry_timeout']; } if ( isset( $params['server_failure_limit'] ) ) { $options[Memcached::OPT_SERVER_FAILURE_LIMIT] = $params['server_failure_limit']; } if ( $params['serializer'] === 'php' ) { $options[Memcached::OPT_SERIALIZER] = Memcached::SERIALIZER_PHP; } elseif ( $params['serializer'] === 'igbinary' ) { // @phan-suppress-next-line PhanImpossibleCondition if ( !Memcached::HAVE_IGBINARY ) { throw new RuntimeException( __CLASS__ . ': the igbinary extension is not available ' . 'but igbinary serialization was requested.' ); } $options[Memcached::OPT_SERIALIZER] = Memcached::SERIALIZER_IGBINARY; } if ( !$client->setOptions( $options ) ) { throw new RuntimeException( "Invalid options: " . json_encode( $options, JSON_PRETTY_PRINT ) ); } $servers = []; foreach ( $params['servers'] as $host ) { if ( preg_match( '/^\[(.+)\]:(\d+)$/', $host, $m ) ) { $servers[] = [ $m[1], (int)$m[2] ]; // (ip, port) } elseif ( preg_match( '/^([^:]+):(\d+)$/', $host, $m ) ) { $servers[] = [ $m[1], (int)$m[2] ]; // (ip or path, port) } else { $servers[] = [ $host, false ]; // (ip or path, port) } } if ( !$client->addServers( $servers ) ) { throw new RuntimeException( "Failed to inject server address list" ); } } /** * If $flags is true or is an integer with the WRITE_BACKGROUND bit set, * enable no-reply mode, and disable it when the scope object is destroyed. * This makes writes much faster. * * @param bool|int $flags * * @return ScopedCallback|null */ private function noReplyScope( $flags ) { if ( $flags !== true && !( $flags & self::WRITE_BACKGROUND ) ) { return null; } $client = $this->client; $client->setOption( Memcached::OPT_NOREPLY, true ); return new ScopedCallback( static function () use ( $client ) { $client->setOption( Memcached::OPT_NOREPLY, false ); } ); } protected function doGet( $key, $flags = 0, &$casToken = null ) { $getToken = ( $casToken === self::PASS_BY_REF ); $casToken = null; $this->debug( "get($key)" ); $routeKey = $this->validateKeyAndPrependRoute( $key ); // T257003: only require "gets" (instead of "get") when a CAS token is needed if ( $getToken ) { /** @noinspection PhpUndefinedClassConstantInspection */ $flags = Memcached::GET_EXTENDED; $res = $this->client->get( $routeKey, null, $flags ); if ( is_array( $res ) ) { $result = $res['value']; $casToken = $res['cas']; } else { $result = false; } } else { $result = $this->client->get( $routeKey ); } return $this->checkResult( $key, $result ); } protected function doSet( $key, $value, $exptime = 0, $flags = 0 ) { $this->debug( "set($key)" ); $routeKey = $this->validateKeyAndPrependRoute( $key ); $noReplyScope = $this->noReplyScope( $flags ); $result = $this->client->set( $routeKey, $value, $this->fixExpiry( $exptime ) ); ScopedCallback::consume( $noReplyScope ); return ( !$result && $this->client->getResultCode() === Memcached::RES_NOTSTORED ) // "Not stored" is always used as the mcrouter response with AllAsyncRoute ? true : $this->checkResult( $key, $result ); } protected function doCas( $casToken, $key, $value, $exptime = 0, $flags = 0 ) { $this->debug( "cas($key)" ); $routeKey = $this->validateKeyAndPrependRoute( $key ); $result = $this->client->cas( $casToken, $routeKey, $value, $this->fixExpiry( $exptime ) ); return $this->checkResult( $key, $result ); } protected function doDelete( $key, $flags = 0 ) { $this->debug( "delete($key)" ); $routeKey = $this->validateKeyAndPrependRoute( $key ); $noReplyScope = $this->noReplyScope( $flags ); $result = $this->client->delete( $routeKey ); ScopedCallback::consume( $noReplyScope ); return ( !$result && $this->client->getResultCode() === Memcached::RES_NOTFOUND ) // "Not found" is counted as success in our interface ? true : $this->checkResult( $key, $result ); } protected function doAdd( $key, $value, $exptime = 0, $flags = 0 ) { $this->debug( "add($key)" ); $routeKey = $this->validateKeyAndPrependRoute( $key ); $noReplyScope = $this->noReplyScope( $flags ); $result = $this->client->add( $routeKey, $value, $this->fixExpiry( $exptime ) ); ScopedCallback::consume( $noReplyScope ); return $this->checkResult( $key, $result ); } protected function doIncrWithInitAsync( $key, $exptime, $step, $init ) { $this->debug( "incrWithInit($key)" ); $routeKey = $this->validateKeyAndPrependRoute( $key ); $watchPoint = $this->watchErrors(); $scope = $this->noReplyScope( true ); $this->checkResult( $key, $this->client->add( $routeKey, $init - $step, $this->fixExpiry( $exptime ) ) ); $this->checkResult( $key, $this->client->increment( $routeKey, $step ) ); ScopedCallback::consume( $scope ); $lastError = $this->getLastError( $watchPoint ); return !$lastError; } protected function doIncrWithInitSync( $key, $exptime, $step, $init ) { $this->debug( "incrWithInit($key)" ); $routeKey = $this->validateKeyAndPrependRoute( $key ); $watchPoint = $this->watchErrors(); $result = $this->client->increment( $routeKey, $step ); $newValue = $this->checkResult( $key, $result ); if ( $newValue === false && !$this->getLastError( $watchPoint ) ) { // No key set; initialize $result = $this->client->add( $routeKey, $init, $this->fixExpiry( $exptime ) ); $newValue = $this->checkResult( $key, $result ) ? $init : false; if ( $newValue === false && !$this->getLastError( $watchPoint ) ) { // Raced out initializing; increment $result = $this->client->increment( $routeKey, $step ); $newValue = $this->checkResult( $key, $result ); } } return $newValue; } /** * Check the return value from a client method call and take any necessary * action. Returns the value that the wrapper function should return. At * present, the return value is always the same as the return value from * the client, but some day we might find a case where it should be * different. * * @param string|false $key The key used by the caller, or false if there wasn't one. * @param mixed $result The return value * * @return mixed */ protected function checkResult( $key, $result ) { static $statusByCode = [ Memcached::RES_HOST_LOOKUP_FAILURE => self::ERR_UNREACHABLE, Memcached::RES_SERVER_MARKED_DEAD => self::ERR_UNREACHABLE, Memcached::RES_SERVER_TEMPORARILY_DISABLED => self::ERR_UNREACHABLE, Memcached::RES_UNKNOWN_READ_FAILURE => self::ERR_NO_RESPONSE, Memcached::RES_WRITE_FAILURE => self::ERR_NO_RESPONSE, Memcached::RES_PARTIAL_READ => self::ERR_NO_RESPONSE, // Hard-code values that only exist in recent versions of the PECL extension. // https://github.com/JetBrains/phpstorm-stubs/blob/master/memcached/memcached.php 3 /* Memcached::RES_CONNECTION_FAILURE */ => self::ERR_UNREACHABLE, 27 /* Memcached::RES_FAIL_UNIX_SOCKET */ => self::ERR_UNREACHABLE, 6 /* Memcached::RES_READ_FAILURE */ => self::ERR_NO_RESPONSE ]; if ( $result !== false ) { return $result; } $client = $this->client; $code = $client->getResultCode(); switch ( $code ) { case Memcached::RES_SUCCESS: break; case Memcached::RES_DATA_EXISTS: case Memcached::RES_NOTSTORED: case Memcached::RES_NOTFOUND: $this->debug( "result: " . $client->getResultMessage() ); break; default: $msg = $client->getResultMessage(); $logCtx = []; if ( $key !== false ) { $server = $client->getServerByKey( $key ); $logCtx['memcached-server'] = "{$server['host']}:{$server['port']}"; $logCtx['memcached-key'] = $key; $msg = "Memcached error for key \"{memcached-key}\" " . "on server \"{memcached-server}\": $msg"; } else { $msg = "Memcached error: $msg"; } $this->logger->error( $msg, $logCtx ); $this->setLastError( $statusByCode[$code] ?? self::ERR_UNEXPECTED ); } return $result; } protected function doGetMulti( array $keys, $flags = 0 ) { $this->debug( 'getMulti(' . implode( ', ', $keys ) . ')' ); $routeKeys = []; foreach ( $keys as $key ) { $routeKeys[] = $this->validateKeyAndPrependRoute( $key ); } // The PECL implementation uses multi-key "get"/"gets"; no need to pipeline. // T257003: avoid Memcached::GET_EXTENDED; no tokens are needed and that requires "gets" // https://github.com/libmemcached/libmemcached/blob/eda2becbec24363f56115fa5d16d38a2d1f54775/libmemcached/get.cc#L272 $resByRouteKey = $this->client->getMulti( $routeKeys ); if ( is_array( $resByRouteKey ) ) { $res = []; foreach ( $resByRouteKey as $routeKey => $value ) { $res[$this->stripRouteFromKey( $routeKey )] = $value; } } else { $res = false; } $res = $this->checkResult( false, $res ); return $res !== false ? $res : []; } protected function doSetMulti( array $data, $exptime = 0, $flags = 0 ) { $this->debug( 'setMulti(' . implode( ', ', array_keys( $data ) ) . ')' ); $exptime = $this->fixExpiry( $exptime ); $dataByRouteKey = []; foreach ( $data as $key => $value ) { $dataByRouteKey[$this->validateKeyAndPrependRoute( $key )] = $value; } $noReplyScope = $this->noReplyScope( $flags ); // Ignore "failed to set" warning from php-memcached 3.x (T251450) // phpcs:ignore Generic.PHP.NoSilencedErrors.Discouraged $result = @$this->client->setMulti( $dataByRouteKey, $exptime ); ScopedCallback::consume( $noReplyScope ); return $this->checkResult( false, $result ); } protected function doDeleteMulti( array $keys, $flags = 0 ) { $this->debug( 'deleteMulti(' . implode( ', ', $keys ) . ')' ); $routeKeys = []; foreach ( $keys as $key ) { $routeKeys[] = $this->validateKeyAndPrependRoute( $key ); } $noReplyScope = $this->noReplyScope( $flags ); $resultArray = $this->client->deleteMulti( $routeKeys ) ?: []; ScopedCallback::consume( $noReplyScope ); $result = true; foreach ( $resultArray as $code ) { if ( !in_array( $code, [ true, Memcached::RES_NOTFOUND ], true ) ) { // "Not found" is counted as success in our interface $result = false; } } return $this->checkResult( false, $result ); } protected function doChangeTTL( $key, $exptime, $flags ) { $this->debug( "touch($key)" ); $routeKey = $this->validateKeyAndPrependRoute( $key ); // Avoid NO_REPLY due to libmemcached hang // https://phabricator.wikimedia.org/T310662#8031692 $result = $this->client->touch( $routeKey, $this->fixExpiry( $exptime ) ); return $this->checkResult( $key, $result ); } protected function serialize( $value ) { if ( is_int( $value ) ) { return $value; } $serializer = $this->client->getOption( Memcached::OPT_SERIALIZER ); if ( $serializer === Memcached::SERIALIZER_PHP ) { return serialize( $value ); } elseif ( $serializer === Memcached::SERIALIZER_IGBINARY ) { return igbinary_serialize( $value ); } throw new UnexpectedValueException( __METHOD__ . ": got serializer '$serializer'." ); } protected function unserialize( $value ) { if ( $this->isInteger( $value ) ) { return (int)$value; } $serializer = $this->client->getOption( Memcached::OPT_SERIALIZER ); if ( $serializer === Memcached::SERIALIZER_PHP ) { return unserialize( $value ); } elseif ( $serializer === Memcached::SERIALIZER_IGBINARY ) { return igbinary_unserialize( $value ); } throw new UnexpectedValueException( __METHOD__ . ": got serializer '$serializer'." ); } } /** @deprecated class alias since 1.43 */ class_alias( MemcachedPeclBagOStuff::class, 'MemcachedPeclBagOStuff' ); PK ! e�$v�3 �3 # objectcache/MultiWriteBagOStuff.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\ObjectCache; use InvalidArgumentException; use Wikimedia\ObjectFactory\ObjectFactory; /** * Wrap multiple BagOStuff objects, to implement different caching tiers. * * The order of the caches is important. The first tier is considered the primary * and highest tier which must handle the majority of the load for reads, * and is generally less persistent, smaller, and faster (e.g. evicts data * regularly based on demand, keeping fewer keys at a given time). * The other caches are consider secondary and lower tiers, which should * hold more data and retain it for longer than the primary tier. * * Data writes ("set") go to all given BagOStuff caches. * If the `replication => async` option is set, then only the primary write * is blocking during the web request, with other writes deferred until * after the web response is sent. * * Data reads try each cache in the order they are given, until a value is found. * When a value is found at a secondary tier, it is automatically copied (back) * to the primary tier. * * **Example**: Keep popular data in memcached, with a fallback to a MySQL database. * This is how ParserCache is used at Wikimedia Foundation (as of 2024). * * ``` * $wgObjectCaches['parsercache-multiwrite'] = [ * 'class' => 'MultiWriteBagOStuff', * 'caches' => [ * 0 => [ * 'class' => 'MemcachedPeclBagOStuff', * 'servers' => [ '127.0.0.1:11212' ], * ], * 1 => [ * 'class' => 'SqlBagOStuff', * 'servers' => $parserCacheDbServers, * 'purgePeriod' => 0, * 'tableName' => 'pc', * 'shards' => 256, * 'reportDupes' => false * ], * ] * ]; * ``` * * If you configure a memcached server for MultiWriteBagOStuff that is the same * as the one used for MediaWiki more generally, it is recommended to specify * the tier via ObjectCache::getInstance() so that the same object and Memcached * connection can be re-used. * * ``` * $wgObjectCaches['my-memcached'] = [ .. ]; * $wgMainCacheType = 'my-memcached'; * * $wgObjectCaches['parsercache-multiwrite'] = [ * 'class' => 'MultiWriteBagOStuff', * 'caches' => [ * 0 => [ * 'factory' => [ 'ObjectCache', 'getInstance' ], * 'args' => [ 'my-memcached' ], * ], * 1 => [ * 'class' => 'SqlBagOStuff', * 'servers' => $parserCacheDbServers, * 'purgePeriod' => 0, * 'tableName' => 'pc', * 'shards' => 256, * 'reportDupes' => false * ], * ] * ]; * ``` * * The makeKey() method of this class uses an implementation-agnostic encoding. * When it forward gets and sets to the other BagOStuff objects, keys are * automatically re-encoded. For example, to satisfy the character and length * constraints of MemcachedBagOStuff. * * @newable * @ingroup Cache */ class MultiWriteBagOStuff extends BagOStuff { /** @var BagOStuff[] Backing cache stores in order of highest to lowest tier */ protected $caches; /** @var bool Use async secondary writes */ protected $asyncWrites = false; /** @var int[] List of all backing cache indexes */ protected $cacheIndexes = []; /** @var int TTL when a key is copied to a higher cache tier */ private static $UPGRADE_TTL = 3600; /** * @stable to call * * @param array $params * - caches: A numbered array of either ObjectFactory::getObjectFromSpec * arrays yielding BagOStuff objects or direct BagOStuff objects. * If using the former, the 'args' field *must* be set. * The first cache is the primary one, being the first to * be read in the fallback chain. Writes happen to all stores * in the order they are defined. However, lock()/unlock() calls * only use the primary store. * - replication: Either 'sync' or 'async'. This controls whether writes * to secondary stores are deferred when possible. To use 'async' writes * requires the 'asyncHandler' option to be set as well. * Async writes can increase the chance of some race conditions * or cause keys to expire seconds later than expected. It is * safe to use for modules when cached values: are immutable, * invalidation uses logical TTLs, invalidation uses etag/timestamp * validation against the DB, or merge() is used to handle races. * * @phan-param array{caches:array<int,array|BagOStuff>,replication:string} $params */ public function __construct( $params ) { parent::__construct( $params ); if ( empty( $params['caches'] ) || !is_array( $params['caches'] ) ) { throw new InvalidArgumentException( __METHOD__ . ': "caches" parameter must be an array of caches' ); } $this->caches = []; foreach ( $params['caches'] as $cacheInfo ) { if ( $cacheInfo instanceof BagOStuff ) { $this->caches[] = $cacheInfo; } else { $this->caches[] = ObjectFactory::getObjectFromSpec( $cacheInfo ); } } $this->attrMap = $this->mergeFlagMaps( $this->caches ); $this->asyncWrites = ( isset( $params['replication'] ) && $params['replication'] === 'async' && is_callable( $this->asyncHandler ) ); $this->cacheIndexes = array_keys( $this->caches ); } public function get( $key, $flags = 0 ) { $args = func_get_args(); if ( $this->fieldHasFlags( $flags, self::READ_LATEST ) ) { // If the latest write was a delete(), we do NOT want to fallback // to the other tiers and possibly see the old value. Also, this // is used by merge(), which only needs to hit the primary. return $this->callKeyMethodOnTierCache( 0, __FUNCTION__, self::ARG0_KEY, self::RES_NONKEY, $args ); } $value = false; // backends checked $missIndexes = []; foreach ( $this->cacheIndexes as $i ) { $value = $this->callKeyMethodOnTierCache( $i, __FUNCTION__, self::ARG0_KEY, self::RES_NONKEY, $args ); if ( $value !== false ) { break; } $missIndexes[] = $i; } if ( $value !== false && $this->fieldHasFlags( $flags, self::READ_VERIFIED ) && $missIndexes ) { // Backfill the value to the higher (and often faster/smaller) cache tiers $this->callKeyWriteMethodOnTierCaches( $missIndexes, 'set', self::ARG0_KEY, self::RES_NONKEY, [ $key, $value, self::$UPGRADE_TTL ] ); } return $value; } public function set( $key, $value, $exptime = 0, $flags = 0 ) { return $this->callKeyWriteMethodOnTierCaches( $this->cacheIndexes, __FUNCTION__, self::ARG0_KEY, self::RES_NONKEY, func_get_args() ); } public function delete( $key, $flags = 0 ) { return $this->callKeyWriteMethodOnTierCaches( $this->cacheIndexes, __FUNCTION__, self::ARG0_KEY, self::RES_NONKEY, func_get_args() ); } public function add( $key, $value, $exptime = 0, $flags = 0 ) { // Try the write to the top-tier cache $ok = $this->callKeyMethodOnTierCache( 0, __FUNCTION__, self::ARG0_KEY, self::RES_NONKEY, func_get_args() ); if ( $ok ) { // Relay the add() using set() if it succeeded. This is meant to handle certain // migration scenarios where the same store might get written to twice for certain // keys. In that case, it makes no sense to return false due to "self-conflicts". $okSecondaries = $this->callKeyWriteMethodOnTierCaches( array_slice( $this->cacheIndexes, 1 ), 'set', self::ARG0_KEY, self::RES_NONKEY, [ $key, $value, $exptime, $flags ] ); if ( $okSecondaries === false ) { $ok = false; } } return $ok; } public function merge( $key, callable $callback, $exptime = 0, $attempts = 10, $flags = 0 ) { return $this->callKeyWriteMethodOnTierCaches( $this->cacheIndexes, __FUNCTION__, self::ARG0_KEY, self::RES_NONKEY, func_get_args() ); } public function changeTTL( $key, $exptime = 0, $flags = 0 ) { return $this->callKeyWriteMethodOnTierCaches( $this->cacheIndexes, __FUNCTION__, self::ARG0_KEY, self::RES_NONKEY, func_get_args() ); } public function lock( $key, $timeout = 6, $exptime = 6, $rclass = '' ) { // Only need to lock the first cache; also avoids deadlocks return $this->callKeyMethodOnTierCache( 0, __FUNCTION__, self::ARG0_KEY, self::RES_NONKEY, func_get_args() ); } public function unlock( $key ) { // Only the first cache is locked return $this->callKeyMethodOnTierCache( 0, __FUNCTION__, self::ARG0_KEY, self::RES_NONKEY, func_get_args() ); } public function deleteObjectsExpiringBefore( $timestamp, ?callable $progress = null, $limit = INF, ?string $tag = null ) { $ret = false; foreach ( $this->caches as $cache ) { if ( $cache->deleteObjectsExpiringBefore( $timestamp, $progress, $limit, $tag ) ) { $ret = true; } } return $ret; } public function getMulti( array $keys, $flags = 0 ) { // Just iterate over each key in order to handle all the backfill logic $res = []; foreach ( $keys as $key ) { $val = $this->get( $key, $flags ); if ( $val !== false ) { $res[$key] = $val; } } return $res; } public function setMulti( array $valueByKey, $exptime = 0, $flags = 0 ) { return $this->callKeyWriteMethodOnTierCaches( $this->cacheIndexes, __FUNCTION__, self::ARG0_KEYMAP, self::RES_NONKEY, func_get_args() ); } public function deleteMulti( array $keys, $flags = 0 ) { return $this->callKeyWriteMethodOnTierCaches( $this->cacheIndexes, __FUNCTION__, self::ARG0_KEYARR, self::RES_NONKEY, func_get_args() ); } public function changeTTLMulti( array $keys, $exptime, $flags = 0 ) { return $this->callKeyWriteMethodOnTierCaches( $this->cacheIndexes, __FUNCTION__, self::ARG0_KEYARR, self::RES_NONKEY, func_get_args() ); } public function incrWithInit( $key, $exptime, $step = 1, $init = null, $flags = 0 ) { return $this->callKeyWriteMethodOnTierCaches( $this->cacheIndexes, __FUNCTION__, self::ARG0_KEY, self::RES_NONKEY, func_get_args() ); } public function setMockTime( &$time ) { parent::setMockTime( $time ); foreach ( $this->caches as $cache ) { $cache->setMockTime( $time ); } } /** * Call a method on the cache instance for the given cache tier (index) * * @param int $index Cache tier * @param string $method Method name * @param int $arg0Sig BagOStuff::A0_* constant describing argument 0 * @param int $rvSig BagOStuff::RV_* constant describing the return value * @param array $args Method arguments * * @return mixed The result of calling the given method */ private function callKeyMethodOnTierCache( $index, $method, $arg0Sig, $rvSig, array $args ) { return $this->caches[$index]->proxyCall( $method, $arg0Sig, $rvSig, $args, $this ); } /** * Call a write method on the cache instances, in order, for the given tiers (indexes) * * @param int[] $indexes List of cache tiers * @param string $method Method name * @param int $arg0Sig BagOStuff::ARG0_* constant describing argument 0 * @param int $resSig BagOStuff::RES_* constant describing the return value * @param array $args Method arguments * * @return mixed First synchronous result or false if any failed; null if all asynchronous */ private function callKeyWriteMethodOnTierCaches( array $indexes, $method, $arg0Sig, $resSig, array $args ) { $res = null; if ( $this->asyncWrites && array_diff( $indexes, [ 0 ] ) && $method !== 'merge' ) { // Deep-clone $args to prevent misbehavior when something writes an // object to the BagOStuff then modifies it afterwards, e.g. T168040. $args = unserialize( serialize( $args ) ); } foreach ( $indexes as $i ) { $cache = $this->caches[$i]; if ( $i == 0 || !$this->asyncWrites ) { // Tier 0 store or in sync mode: write synchronously and get result $storeRes = $cache->proxyCall( $method, $arg0Sig, $resSig, $args, $this ); if ( $storeRes === false ) { $res = false; } elseif ( $res === null ) { // first synchronous result $res = $storeRes; } } else { // Secondary write in async mode: do not block this HTTP request ( $this->asyncHandler )( function () use ( $cache, $method, $arg0Sig, $resSig, $args ) { $cache->proxyCall( $method, $arg0Sig, $resSig, $args, $this ); } ); } } return $res; } } /** @deprecated class alias since 1.43 */ class_alias( MultiWriteBagOStuff::class, 'MultiWriteBagOStuff' ); PK ! `�w� � objectcache/EmptyBagOStuff.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\ObjectCache; /** * No-op implementation that stores nothing. * * Used as placeholder or fallback when disabling caching. * * This can be used in configuration via the CACHE_NONE constant. * * @ingroup Cache */ class EmptyBagOStuff extends MediumSpecificBagOStuff { public function __construct( array $params = [] ) { parent::__construct( $params ); $this->attrMap[self::ATTR_DURABILITY] = self::QOS_DURABILITY_NONE; } protected function doGet( $key, $flags = 0, &$casToken = null ) { $casToken = null; return false; } protected function doSet( $key, $value, $exptime = 0, $flags = 0 ) { return true; } protected function doDelete( $key, $flags = 0 ) { return true; } protected function doAdd( $key, $value, $exptime = 0, $flags = 0 ) { return true; } protected function doIncrWithInit( $key, $exptime, $step, $init, $flags ) { // faster return $init; } public function merge( $key, callable $callback, $exptime = 0, $attempts = 10, $flags = 0 ) { // faster return true; } } /** @deprecated class alias since 1.43 */ class_alias( EmptyBagOStuff::class, 'EmptyBagOStuff' ); PK ! ���eV, V, objectcache/RESTBagOStuff.phpnu �Iw�� <?php namespace Wikimedia\ObjectCache; use InvalidArgumentException; use Psr\Log\LoggerInterface; use Wikimedia\Http\MultiHttpClient; /** * Store key-value data via an HTTP service. * * ### Important caveats * * This interface is currently an incomplete BagOStuff implementation, * supported only for use with MediaWiki features that accept a dedicated * cache type to use for a narrow set of cache keys that share the same * key expiry and replication requirements, and where the key-value server * in question is statically configured with domain knowledge of said * key expiry and replication requirements. * * Specifically, RESTBagOStuff has the following limitations: * * - The expiry parameter is ignored in methods like `set()`. * * There is not currently an agreed protocol for sending this to a * server. This class is written for use with MediaWiki\Session\SessionManager * and Kask/Cassanda at WMF, which does not expose a customizable expiry. * * As such, it is not recommended to use RESTBagOStuff to back a general * purpose cache type (such as MediaWiki's main cache, or main stash). * Instead, it is only supported toMediaWiki features where a cache type can * be pointed for a narrow set of keys that naturally share the same TTL * anyway, or where the feature behaves correctly even if the logical expiry * is longer than specified (e.g. immutable keys, or value verification) * * - Most methods are non-atomic. * * The class should only be used for get, set, and delete operations. * Advanced methods like `incr()`, `add()` and `lock()` do exist but * inherit a native and best-effort implementation based on get+set. * These should not be relied upon. * * ### Backend requirements * * The HTTP server will receive requests for URLs like `{baseURL}/{KEY}`. It * must implement the GET, PUT and DELETE methods. * * E.g., when the base URL is `/sessions/v1`, then `set()` will: * * `PUT /sessions/v1/mykeyhere` * * and `get()` would do: * * `GET /sessions/v1/mykeyhere` * * and `delete()` would do: * * `DELETE /sessions/v1/mykeyhere` * * ### Example configuration * * Minimal generic configuration: * * @code * $wgObjectCaches['sessions'] = array( * 'class' => 'RESTBagOStuff', * 'url' => 'http://localhost:7231/example/' * ); * @endcode * * * Configuration for [Kask](https://www.mediawiki.org/wiki/Kask) session store: * @code * $wgObjectCaches['sessions'] = array( * 'class' => 'RESTBagOStuff', * 'url' => 'https://kaskhost:1234/sessions/v1/', * 'httpParams' => [ * 'readHeaders' => [], * 'writeHeaders' => [ 'content-type' => 'application/octet-stream' ], * 'deleteHeaders' => [], * 'writeMethod' => 'POST', * ], * 'serialization_type' => 'JSON', * 'extendedErrorBodyFields' => [ 'type', 'title', 'detail', 'instance' ] * ); * $wgSessionCacheType = 'sessions'; * @endcode */ class RESTBagOStuff extends MediumSpecificBagOStuff { /** * Default connection timeout in seconds. The kernel retransmits the SYN * packet after 1 second, so 1.2 seconds allows for 1 retransmit without * permanent failure. */ private const DEFAULT_CONN_TIMEOUT = 1.2; /** * Default request timeout */ private const DEFAULT_REQ_TIMEOUT = 3.0; /** * @var MultiHttpClient */ private $client; /** * REST URL to use for storage. * * @var string */ private $url; /** * HTTP parameters: readHeaders, writeHeaders, deleteHeaders, writeMethod. * * @var array */ private $httpParams; /** * Optional serialization type to use. Allowed values: "PHP", "JSON". * * @var string */ private $serializationType; /** * Optional HMAC Key for protecting the serialized blob. If omitted no protection is done * * @var string */ private $hmacKey; /** * @var array additional body fields to log on error, if possible */ private $extendedErrorBodyFields; public function __construct( $params ) { $params['segmentationSize'] ??= INF; if ( empty( $params['url'] ) ) { throw new InvalidArgumentException( 'URL parameter is required' ); } if ( empty( $params['client'] ) ) { // Pass through some params to the HTTP client. $clientParams = [ 'connTimeout' => $params['connTimeout'] ?? self::DEFAULT_CONN_TIMEOUT, 'reqTimeout' => $params['reqTimeout'] ?? self::DEFAULT_REQ_TIMEOUT, ]; foreach ( [ 'caBundlePath', 'proxy', 'telemetry' ] as $key ) { if ( isset( $params[$key] ) ) { $clientParams[$key] = $params[$key]; } } $this->client = new MultiHttpClient( $clientParams ); } else { $this->client = $params['client']; } $this->httpParams['writeMethod'] = $params['httpParams']['writeMethod'] ?? 'PUT'; $this->httpParams['readHeaders'] = $params['httpParams']['readHeaders'] ?? []; $this->httpParams['writeHeaders'] = $params['httpParams']['writeHeaders'] ?? []; $this->httpParams['deleteHeaders'] = $params['httpParams']['deleteHeaders'] ?? []; $this->extendedErrorBodyFields = $params['extendedErrorBodyFields'] ?? []; $this->serializationType = $params['serialization_type'] ?? 'PHP'; $this->hmacKey = $params['hmac_key'] ?? ''; // The parent constructor calls setLogger() which sets the logger in $this->client parent::__construct( $params ); // Make sure URL ends with / $this->url = rtrim( $params['url'], '/' ) . '/'; $this->attrMap[self::ATTR_DURABILITY] = self::QOS_DURABILITY_DISK; } public function setLogger( LoggerInterface $logger ) { parent::setLogger( $logger ); $this->client->setLogger( $logger ); } protected function doGet( $key, $flags = 0, &$casToken = null ) { $getToken = ( $casToken === self::PASS_BY_REF ); $casToken = null; $req = [ 'method' => 'GET', 'url' => $this->url . rawurlencode( $key ), 'headers' => $this->httpParams['readHeaders'], ]; $value = false; $valueSize = false; [ $rcode, , $rhdrs, $rbody, $rerr ] = $this->client->run( $req ); if ( $rcode === 200 && is_string( $rbody ) ) { $value = $this->decodeBody( $rbody ); $valueSize = strlen( $rbody ); // @FIXME: use some kind of hash or UUID header as CAS token if ( $getToken && $value !== false ) { $casToken = $rbody; } } elseif ( $rcode === 0 || ( $rcode >= 400 && $rcode != 404 ) ) { $this->handleError( 'Failed to fetch {cacheKey}', $rcode, $rerr, $rhdrs, $rbody, [ 'cacheKey' => $key ] ); } $this->updateOpStats( self::METRIC_OP_GET, [ $key => [ 0, $valueSize ] ] ); return $value; } protected function doSet( $key, $value, $exptime = 0, $flags = 0 ) { $req = [ 'method' => $this->httpParams['writeMethod'], 'url' => $this->url . rawurlencode( $key ), 'body' => $this->encodeBody( $value ), 'headers' => $this->httpParams['writeHeaders'], ]; [ $rcode, , $rhdrs, $rbody, $rerr ] = $this->client->run( $req ); $res = ( $rcode === 200 || $rcode === 201 || $rcode === 204 ); if ( !$res ) { $this->handleError( 'Failed to store {cacheKey}', $rcode, $rerr, $rhdrs, $rbody, [ 'cacheKey' => $key ] ); } $this->updateOpStats( self::METRIC_OP_SET, [ $key => [ strlen( $rbody ), 0 ] ] ); return $res; } protected function doAdd( $key, $value, $exptime = 0, $flags = 0 ) { // NOTE: This is non-atomic if ( $this->get( $key ) === false ) { return $this->set( $key, $value, $exptime, $flags ); } // key already set return false; } protected function doDelete( $key, $flags = 0 ) { $req = [ 'method' => 'DELETE', 'url' => $this->url . rawurlencode( $key ), 'headers' => $this->httpParams['deleteHeaders'], ]; [ $rcode, , $rhdrs, $rbody, $rerr ] = $this->client->run( $req ); $res = in_array( $rcode, [ 200, 204, 205, 404, 410 ] ); if ( !$res ) { $this->handleError( 'Failed to delete {cacheKey}', $rcode, $rerr, $rhdrs, $rbody, [ 'cacheKey' => $key ] ); } $this->updateOpStats( self::METRIC_OP_DELETE, [ $key ] ); return $res; } protected function doIncrWithInit( $key, $exptime, $step, $init, $flags ) { // NOTE: This is non-atomic $curValue = $this->doGet( $key ); if ( $curValue === false ) { $newValue = $this->doSet( $key, $init, $exptime ) ? $init : false; } elseif ( $this->isInteger( $curValue ) ) { $sum = max( $curValue + $step, 0 ); $newValue = $this->doSet( $key, $sum, $exptime ) ? $sum : false; } else { $newValue = false; } return $newValue; } /** * Processes the response body. * * @param string $body request body to process * * @return mixed|bool the processed body, or false on error */ private function decodeBody( $body ) { $pieces = explode( '.', $body, 3 ); if ( count( $pieces ) !== 3 || $pieces[0] !== $this->serializationType ) { return false; } [ , $hmac, $serialized ] = $pieces; if ( $this->hmacKey !== '' ) { $checkHmac = hash_hmac( 'sha256', $serialized, $this->hmacKey, true ); if ( !hash_equals( $checkHmac, base64_decode( $hmac ) ) ) { return false; } } switch ( $this->serializationType ) { case 'JSON': $value = json_decode( $serialized, true ); return ( json_last_error() === JSON_ERROR_NONE ) ? $value : false; case 'PHP': return unserialize( $serialized ); default: throw new \DomainException( "Unknown serialization type: $this->serializationType" ); } } /** * Prepares the request body (the "value" portion of our key/value store) for transmission. * * @param string $body request body to prepare * * @return string the prepared body */ private function encodeBody( $body ) { switch ( $this->serializationType ) { case 'JSON': $value = json_encode( $body ); if ( $value === false ) { throw new InvalidArgumentException( __METHOD__ . ": body could not be encoded." ); } break; case 'PHP': $value = serialize( $body ); break; default: throw new \DomainException( "Unknown serialization type: $this->serializationType" ); } if ( $this->hmacKey !== '' ) { $hmac = base64_encode( hash_hmac( 'sha256', $value, $this->hmacKey, true ) ); } else { $hmac = ''; } return $this->serializationType . '.' . $hmac . '.' . $value; } /** * Handle storage error * * @param string $msg Error message * @param int $rcode Error code from client * @param string $rerr Error message from client * @param array $rhdrs Response headers * @param string $rbody Error body from client (if any) * @param array $context Error context for PSR-3 logging */ protected function handleError( $msg, $rcode, $rerr, $rhdrs, $rbody, $context = [] ) { $message = "$msg : ({code}) {error}"; $context = [ 'code' => $rcode, 'error' => $rerr ] + $context; if ( $this->extendedErrorBodyFields !== [] ) { $body = $this->decodeBody( $rbody ); if ( $body ) { $extraFields = ''; foreach ( $this->extendedErrorBodyFields as $field ) { if ( isset( $body[$field] ) ) { $extraFields .= " : ({$field}) {$body[$field]}"; } } if ( $extraFields !== '' ) { $message .= " {extra_fields}"; $context['extra_fields'] = $extraFields; } } } $this->logger->error( $message, $context ); $this->setLastError( $rcode === 0 ? self::ERR_UNREACHABLE : self::ERR_UNEXPECTED ); } } /** @deprecated class alias since 1.43 */ class_alias( RESTBagOStuff::class, 'RESTBagOStuff' ); PK ! �E1� 3 objectcache/serialized/SerializedValueContainer.phpnu �Iw�� <?php namespace Wikimedia\ObjectCache\Serialized; use stdClass; /** * Helper class for segmenting large cache values without relying * on serializing classes. * * @since 1.34 * @ingroup Cache */ class SerializedValueContainer { private const SCHEMA = '__svc_schema__'; // 64 bit UID private const SCHEMA_SEGMENTED = 'CAYCDAgCDw4'; public const SEGMENTED_HASHES = '__hashes__'; /** * @param string[] $segmentHashList Ordered list of hashes for each segment * @return stdClass */ public static function newSegmented( array $segmentHashList ) { return (object)[ self::SCHEMA => self::SCHEMA_SEGMENTED, self::SEGMENTED_HASHES => $segmentHashList ]; } /** * @param mixed $value * @return bool */ public static function isSegmented( $value ): bool { return ( $value instanceof stdClass && ( $value->{self::SCHEMA} ?? null ) === self::SCHEMA_SEGMENTED ); } } /** @deprecated class alias since 1.43 */ class_alias( SerializedValueContainer::class, 'SerializedValueContainer' ); PK ! ~�Aww w NonSerializableTrait.phpnu �Iw�� <?php namespace Wikimedia\NonSerializable; use LogicException; /** * A trait that prevents serialization via php's builtin serialize() function. */ trait NonSerializableTrait { /** * @throws LogicException always * @return never */ public function __sleep() { throw new LogicException( 'Instances of ' . get_class( $this ) . ' are not serializable!' ); } } PK ! D�~ Stats/Metrics/GaugeMetric.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * @file */ declare( strict_types=1 ); namespace Wikimedia\Stats\Metrics; use Wikimedia\Stats\Exceptions\IllegalOperationException; use Wikimedia\Stats\Sample; /** * Gauge Metric Implementation * * Gauge Metrics can be set to any numeric value and are identified by type "g". * * @author Cole White * @since 1.38 */ class GaugeMetric implements MetricInterface { use MetricTrait; /** * The StatsD protocol type indicator: * https://github.com/statsd/statsd/blob/v0.9.0/docs/metric_types.md * https://docs.datadoghq.com/developers/dogstatsd/datagram_shell/?tab=metrics */ private const TYPE_INDICATOR = "g"; /** * Sets metric to value. * * @param float $value * @return void */ public function set( float $value ): void { foreach ( $this->baseMetric->getStatsdNamespaces() as $namespace ) { $this->baseMetric->getStatsdDataFactory()->gauge( $namespace, $value ); } try { $this->baseMetric->addSample( new Sample( $this->baseMetric->getLabelValues(), $value ) ); } catch ( IllegalOperationException $ex ) { // Log the condition and give the caller something that will absorb calls. trigger_error( $ex->getMessage(), E_USER_WARNING ); } } /** @inheritDoc */ public function getTypeIndicator(): string { return self::TYPE_INDICATOR; } } PK ! �%�� � Stats/Metrics/NullMetric.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * @file */ declare( strict_types=1 ); namespace Wikimedia\Stats\Metrics; /** * Null Metric Implementation * * When a request from cache yields a type other than what was requested * or an unrecoverable situation has occurred, an instance of this class * should be passed to the caller to provide an interface that suppresses * method calls against it. * * @author Cole White * @since 1.38 */ class NullMetric { /** * Silently suppress all undefined method calls. * * @param $method_name string * @param $args array * @return NullMetric */ public function __call( string $method_name, array $args ): NullMetric { return $this; } } PK ! )�8�� � Stats/Metrics/BaseMetric.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * @file */ declare( strict_types=1 ); namespace Wikimedia\Stats\Metrics; use InvalidArgumentException; use Wikimedia\Stats\Exceptions\IllegalOperationException; use Wikimedia\Stats\IBufferingStatsdDataFactory; use Wikimedia\Stats\Sample; use Wikimedia\Stats\StatsUtils; /** * Base Metric Implementation V1 * * Implements shared Metric functionality: * * Label validation and handling * * Sample rate validation and handling * * Sample generation * * Common properties * * StatsD transition support * * @author Cole White * @since 1.41 */ class BaseMetric implements BaseMetricInterface { /** @var float */ private float $sampleRate = StatsUtils::DEFAULT_SAMPLE_RATE; /** @var string */ private string $name; /** @var string */ private string $component; /** @var array key-value pairs of metric-specific labels */ private array $workingLabels = []; /** @var string[] ordered array of label keys */ private array $labelKeys = []; /** @var Sample[] */ private array $samples = []; /** @var IBufferingStatsdDataFactory|null */ private ?IBufferingStatsdDataFactory $statsdDataFactory = null; /** @var string[] */ private array $statsdNamespaces = []; /** @inheritDoc */ public function __construct( string $component, string $name ) { $this->component = $component; $this->name = StatsUtils::normalizeString( $name ); } /** @inheritDoc */ public function addSample( Sample $sample ): void { $this->samples[] = $sample; } /** @inheritDoc */ public function setSampleRate( float $sampleRate ): void { if ( $this->hasSamples() ) { throw new IllegalOperationException( "Stats: Cannot change sample rate on metric with recorded samples." ); } StatsUtils::validateNewSampleRate( $sampleRate ); $this->sampleRate = $sampleRate; } /** @inheritDoc */ public function getName(): string { return $this->name; } /** @inheritDoc */ public function getSampleRate(): float { return $this->sampleRate; } /** @inheritDoc */ public function getSamples(): array { return StatsUtils::getFilteredSamples( $this->sampleRate, $this->samples ); } /** @inheritDoc */ public function getSampleCount(): int { return count( $this->samples ); } /** @inheritDoc */ public function addLabel( string $key, string $value ): void { StatsUtils::validateLabelValue( $value ); $key = StatsUtils::normalizeString( $key ); StatsUtils::validateLabelKey( $key ); $this->addLabelKey( $key ); $this->workingLabels[$key] = StatsUtils::normalizeString( $value ); } /** @inheritDoc */ public function getStatsdDataFactory() { return $this->statsdDataFactory; } /** @inheritDoc */ public function withStatsdDataFactory( $statsdDataFactory ): BaseMetric { $this->statsdDataFactory = $statsdDataFactory; return $this; } /** @inheritDoc */ public function setStatsdNamespaces( $statsdNamespaces ): void { if ( $this->statsdDataFactory === null ) { return; } $statsdNamespaces = is_array( $statsdNamespaces ) ? $statsdNamespaces : [ $statsdNamespaces ]; foreach ( $statsdNamespaces as $namespace ) { if ( $namespace === '' ) { throw new InvalidArgumentException( "Stats: StatsD namespace cannot be empty." ); } if ( !is_string( $namespace ) ) { throw new InvalidArgumentException( "Stats: StatsD namespace must be a string." ); } } $this->statsdNamespaces = $statsdNamespaces; } /** @inheritDoc */ public function getStatsdNamespaces(): array { return $this->statsdNamespaces; } /** * Registers a label key * * @param string $key * @return void */ private function addLabelKey( string $key ): void { if ( in_array( $key, $this->labelKeys, true ) ) { return; // key already exists } if ( $this->hasSamples() ) { throw new IllegalOperationException( "Stats: Cannot add labels to a metric containing samples for '" . $this->name . "'" ); } $this->labelKeys[] = $key; } /** @return string[] */ public function getLabelKeys(): array { return $this->labelKeys; } /** * Get label values in the order of labelKeys. * * @return string[] */ public function getLabelValues(): array { $output = []; # make sure all labels are accounted for if ( array_diff( $this->labelKeys, array_keys( $this->workingLabels ) ) ) { throw new IllegalOperationException( "Stats: Cannot associate label keys with label values: " . "Not all initialized labels have an assigned value." ); } foreach ( $this->labelKeys as $labelKey ) { $output[] = $this->workingLabels[$labelKey]; } return $output; } /** @inheritDoc */ public function clearLabels(): void { $this->workingLabels = []; } /** @inheritDoc */ public function getComponent(): string { return $this->component; } private function hasSamples(): bool { return $this->samples !== []; } } PK ! 2�1& & ! Stats/Metrics/MetricInterface.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * @file */ namespace Wikimedia\Stats\Metrics; use Psr\Log\LoggerInterface; use Wikimedia\Stats\Sample; /** * Metric Interface * * @author Cole White * @since 1.41 */ interface MetricInterface { /** * @param BaseMetricInterface $baseMetric * @param LoggerInterface $logger */ public function __construct( BaseMetricInterface $baseMetric, LoggerInterface $logger ); /** @return string */ public function getName(): string; /** @return string */ public function getComponent(): string; /** @return float */ public function getSampleRate(): float; /** @return string */ public function getTypeIndicator(): string; /** * Returns subset of samples corresponding to sample rate setting. * * @return Sample[] */ public function getSamples(): array; /** * Returns a count of samples recorded by the metric. * * @return int */ public function getSampleCount(): int; /** * Sets sample rate on a new metric instance. * * @param float $sampleRate * @return self|NullMetric */ public function setSampleRate( float $sampleRate ); /** * Returns the list of defined label keys. * * @return string[] */ public function getLabelKeys(): array; /** * Adds a label $key with $value. * Note that the order in which labels are added is significant for StatsD output. * * Example: * ```php * $statsFactory->getCounter( 'testMetric_total' ) * ->setLabel( 'first', 'foo' ) * ->setLabel( 'second', 'bar' ) * ->increment(); * ``` * statsd: "mediawiki.testMetric_total.foo.bar" * prometheus: "mediawiki_testMetric_total{ first='foo', second='bar' } * * @param string $key * @param string $value * @return self|NullMetric */ public function setLabel( string $key, string $value ); /** * Convenience function to set a number of labels at once. * @see ::setLabel * @param array<string,string> $labels * @return self|NullMetric */ public function setLabels( array $labels ); /** * Copies metric operation to StatsD at provided namespace. * * Takes a namespace or multiple namespaces. * * @param string|string[] $statsdNamespaces * @return self|NullMetric */ public function copyToStatsdAt( $statsdNamespaces ); /** * Returns metric with cleared labels. * * @return self|NullMetric */ public function fresh(); } PK ! �6?�l l Stats/Metrics/MetricTrait.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * @file */ declare( strict_types=1 ); namespace Wikimedia\Stats\Metrics; use InvalidArgumentException; use Psr\Log\LoggerInterface; use Wikimedia\Stats\Exceptions\IllegalOperationException; /** * Implementation code common to all metric types. * * @internal * @since 1.43 */ trait MetricTrait { /** @var BaseMetricInterface */ private BaseMetricInterface $baseMetric; /** @var LoggerInterface */ private LoggerInterface $logger; /** @inheritDoc */ public function __construct( $baseMetric, $logger ) { $this->baseMetric = $baseMetric; $this->logger = $logger; } /** @inheritDoc */ public function getName(): string { return $this->baseMetric->getName(); } /** @inheritDoc */ public function getComponent(): string { return $this->baseMetric->getComponent(); } /** @inheritDoc */ public function getSamples(): array { return $this->baseMetric->getSamples(); } /** @inheritDoc */ public function getSampleCount(): int { return $this->baseMetric->getSampleCount(); } /** @inheritDoc */ public function getSampleRate(): float { return $this->baseMetric->getSampleRate(); } /** @inheritDoc */ public function setSampleRate( float $sampleRate ) { try { $this->baseMetric->setSampleRate( $sampleRate ); } catch ( IllegalOperationException | InvalidArgumentException $ex ) { // Log the condition and give the caller something that will absorb calls. trigger_error( $ex->getMessage(), E_USER_WARNING ); return new NullMetric; } return $this; } /** @inheritDoc */ public function getLabelKeys(): array { return $this->baseMetric->getLabelKeys(); } /** @inheritDoc */ public function setLabel( string $key, string $value ) { try { $this->baseMetric->addLabel( $key, $value ); } catch ( IllegalOperationException | InvalidArgumentException $ex ) { // Log the condition and give the caller something that will absorb calls. trigger_error( $ex->getMessage(), E_USER_WARNING ); return new NullMetric; } return $this; } /** @inheritDoc */ public function setLabels( array $labels ) { try { foreach ( $labels as $key => $value ) { $this->baseMetric->addLabel( $key, $value ); } } catch ( IllegalOperationException | InvalidArgumentException $ex ) { // Log the condition and give the caller something that will absorb calls. trigger_error( $ex->getMessage(), E_USER_WARNING ); return new NullMetric; } return $this; } /** @inheritDoc */ public function copyToStatsdAt( $statsdNamespaces ) { try { $this->baseMetric->setStatsdNamespaces( $statsdNamespaces ); } catch ( InvalidArgumentException $ex ) { // Log the condition and give the caller something that will absorb calls. trigger_error( $ex->getMessage(), E_USER_WARNING ); return new NullMetric; } return $this; } /** @inheritDoc */ public function fresh(): self { $this->baseMetric->clearLabels(); return $this; } } PK ! ��� � Stats/Metrics/CounterMetric.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * @file */ declare( strict_types=1 ); namespace Wikimedia\Stats\Metrics; use Wikimedia\Stats\Exceptions\IllegalOperationException; use Wikimedia\Stats\Sample; /** * Counter Metric Implementation * * Counter Metrics only ever increase and are identified by type "c". * * @author Cole White * @since 1.38 */ class CounterMetric implements MetricInterface { use MetricTrait; /** * The StatsD protocol type indicator: * https://github.com/statsd/statsd/blob/v0.9.0/docs/metric_types.md * https://docs.datadoghq.com/developers/dogstatsd/datagram_shell/?tab=metrics */ private const TYPE_INDICATOR = "c"; /** * Increments metric by one. * * @return void */ public function increment(): void { $this->incrementBy( 1 ); } /** * Increments metric by provided value. * * @param float $value * @return void */ public function incrementBy( float $value ): void { foreach ( $this->baseMetric->getStatsdNamespaces() as $namespace ) { $this->baseMetric->getStatsdDataFactory()->updateCount( $namespace, $value ); } try { $this->baseMetric->addSample( new Sample( $this->baseMetric->getLabelValues(), $value ) ); } catch ( IllegalOperationException $ex ) { // Log the condition and give the caller something that will absorb calls. trigger_error( $ex->getMessage(), E_USER_WARNING ); } } /** @inheritDoc */ public function getTypeIndicator(): string { return self::TYPE_INDICATOR; } } PK ! �XT� � Stats/Metrics/TimingMetric.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * @file */ declare( strict_types=1 ); namespace Wikimedia\Stats\Metrics; use Wikimedia\Stats\Exceptions\IllegalOperationException; use Wikimedia\Stats\Sample; /** * Timing Metric Implementation * * Timing metrics track duration data which can be broken into histograms. * They are identified by type "ms". * * @author Cole White * @since 1.38 */ class TimingMetric implements MetricInterface { use MetricTrait; /** * The StatsD protocol type indicator: * https://github.com/statsd/statsd/blob/v0.9.0/docs/metric_types.md * https://docs.datadoghq.com/developers/dogstatsd/datagram_shell/?tab=metrics */ private const TYPE_INDICATOR = "ms"; /** @var float|null */ private ?float $startTime = null; /** * Starts a timer. * * @return void */ public function start(): void { $this->startTime = hrtime( true ); } /** * Stops a running timer. * * @return void */ public function stop(): void { if ( $this->startTime === null ) { trigger_error( "Stats: stop() called before start() for metric '{$this->getName()}'", E_USER_WARNING ); return; } $this->observeNanoseconds( hrtime( true ) - $this->startTime ); $this->startTime = null; } /** * Records a previously calculated observation in milliseconds. * * @param float $milliseconds * @return void */ public function observe( float $milliseconds ): void { foreach ( $this->baseMetric->getStatsdNamespaces() as $namespace ) { $this->baseMetric->getStatsdDataFactory()->timing( $namespace, $milliseconds ); } try { $this->baseMetric->addSample( new Sample( $this->baseMetric->getLabelValues(), $milliseconds ) ); } catch ( IllegalOperationException $ex ) { // Log the condition and give the caller something that will absorb calls. trigger_error( $ex->getMessage(), E_USER_WARNING ); } } /** * Record a previously calculated observation in seconds. * * Common usage: * ```php * $startTime = microtime( true ) * # work to be measured... * $metric->observeSeconds( microtime( true ) - $startTime ) * ``` * * @param float $seconds * @return void * @since 1.43 */ public function observeSeconds( float $seconds ): void { $this->observe( $seconds * 1000 ); } /** * Record a previously calculated observation in nanoseconds. * * Common usage: * ```php * $startTime = hrtime( true ) * # work to be measured... * $metric->observeNanoseconds( hrtime( true ) - $startTime ) * ``` * @param float $nanoseconds * @return void * @since 1.43 */ public function observeNanoseconds( float $nanoseconds ): void { $this->observe( $nanoseconds * 1e-6 ); } /** @inheritDoc */ public function getTypeIndicator(): string { return self::TYPE_INDICATOR; } } PK ! V�6�� � % Stats/Metrics/BaseMetricInterface.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * @file */ declare( strict_types=1 ); namespace Wikimedia\Stats\Metrics; use Wikimedia\Stats\IBufferingStatsdDataFactory; use Wikimedia\Stats\Sample; /** * Base Metric Interface * * Interface for defining a Base Metric. * * @author Cole White * @since 1.41 */ interface BaseMetricInterface { /** * @param string $component The component this metric will track. * @param string $name The Metric Name. */ public function __construct( string $component, string $name ); /** * Records a Metric Sample. * * @param Sample $sample * @return void */ public function addSample( Sample $sample ): void; /** * Returns the configured sample rate. * * @return float */ public function getSampleRate(): float; /** * Sets the sample rate. * * @param float $sampleRate */ public function setSampleRate( float $sampleRate ): void; /** * Returns subset of samples corresponding to sample rate setting. * * @return Sample[] */ public function getSamples(): array; /** * Returns a count of samples recorded by the metric. * * @return int */ public function getSampleCount(): int; /** * Returns the Metric Name * * @return string */ public function getName(): string; /** * Add a label with key => value. * Note that the order in which labels are added is significant for StatsD output. * * Example: * ```php * $statsFactory->withComponent( 'demo' ) * ->getCounter( 'testMetric_total' ) * ->setLabel( 'first', 'foo' ) * ->setLabel( 'second', 'bar' ) * ->setLabel( 'third', 'baz' ) * ->increment(); * ``` * statsd: "mediawiki.demo.testMetric_total.foo.bar.baz" * prometheus: "mediawiki_demo_testMetric_total{first='foo',second='bar',third='baz'} * * @param string $key * @param string $value * @return void */ public function addLabel( string $key, string $value ): void; /** * Returns array of label keys. * * @return string[] */ public function getLabelKeys(): array; /** * Returns an array of label values in the order of label keys. * * @return string[] */ public function getLabelValues(): array; /** * Returns the Metric Component * * @return string */ public function getComponent(): string; /** * Clears the working labels. * * @return void */ public function clearLabels(): void; /** * Gets StatsD Data Factory instance or null. */ public function getStatsdDataFactory(); /** * Validates and sets legacy StatsD namespaces. * * @param string|string[] $statsdNamespaces * @return void */ public function setStatsdNamespaces( $statsdNamespaces ): void; /** * Returns the configured legacy StatsD namespaces. * * @return string[] */ public function getStatsdNamespaces(): array; /** * StatsD Data Factory instance to copy metrics to. * * @param IBufferingStatsdDataFactory $statsdDataFactory * @return BaseMetricInterface */ public function withStatsdDataFactory( IBufferingStatsdDataFactory $statsdDataFactory ); } PK ! ۸/U� � Stats/NullStatsdDataFactory.phpnu �Iw�� <?php namespace Wikimedia\Stats; use Liuggio\StatsdClient\Entity\StatsdData; use Liuggio\StatsdClient\Entity\StatsdDataInterface; /** * @author Addshore * @since 1.27 */ class NullStatsdDataFactory implements IBufferingStatsdDataFactory { /** * This function creates a 'timing' StatsdData. * * @param string|array $key The metric(s) to set. * @param float $time The elapsed time (ms) to log */ public function timing( $key, $time ) { } /** * This function creates a 'gauge' StatsdData. * * @param string|array $key The metric(s) to set. * @param float $value The value for the stats. */ public function gauge( $key, $value ) { } /** * This function creates a 'set' StatsdData object * A "Set" is a count of unique events. * This data type acts like a counter, but supports counting * of unique occurrences of values between flushes. The backend * receives the number of unique events that happened since * the last flush. * * The reference use case involved tracking the number of active * and logged in users by sending the current userId of a user * with each request with a key of "uniques" (or similar). * * @param string|array $key The metric(s) to set. * @param float $value The value for the stats. * * @return array */ public function set( $key, $value ) { return []; } /** * This function creates a 'increment' StatsdData object. * * @param string|array $key The metric(s) to increment. * * @return array */ public function increment( $key ) { return []; } /** * This function creates a 'decrement' StatsdData object. * * * @param string|array $key The metric(s) to decrement. * * @return mixed */ public function decrement( $key ) { return []; } /** * This function creates a 'updateCount' StatsdData object. * * @param string|array $key The metric(s) to decrement. * @param int $delta The delta to add to the each metric * * @return mixed */ public function updateCount( $key, $delta ) { return []; } /** * Produce a StatsdDataInterface Object. * * @param string $key The key of the metric * @param int $value The amount to increment/decrement each metric by. * @param string $metric The metric type * ("c" for count, "ms" for timing, "g" for gauge, "s" for set) * * @return StatsdDataInterface */ public function produceStatsdData( $key, $value = 1, $metric = StatsdDataInterface::STATSD_METRIC_COUNT ) { $data = new StatsdData(); $data->setKey( $key ); $data->setValue( $value ); $data->setMetric( $metric ); return $data; } public function hasData() { return false; } public function getData() { return []; } public function clearData() { // Nothing to do, always empty } public function getDataCount() { return 0; } public function setEnabled( $enabled ) { // Nothing to do, null factory is always disabled. } } /** @deprecated class alias since 1.43 */ class_alias( NullStatsdDataFactory::class, 'NullStatsdDataFactory' ); PK ! U�wM Stats/SamplingStatsdClient.phpnu �Iw�� <?php /** * Copyright 2015 * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\Stats; use Exception; use InvalidArgumentException; use Liuggio\StatsdClient\Entity\StatsdData; use Liuggio\StatsdClient\Entity\StatsdDataInterface; use Liuggio\StatsdClient\StatsdClient; use LogicException; use Wikimedia\RequestTimeout\TimeoutException; /** * A statsd client that applies the sampling rate to the data items before sending them. * * @deprecated since 1.43 No longer used after $wgSamplingStatsdClient was removed. * @since 1.26 */ class SamplingStatsdClient extends StatsdClient { /** @var array */ protected $samplingRates = []; /** * Sampling rates as an associative array of patterns and rates. * Patterns are Unix shell patterns (e.g. 'MediaWiki.api.*'). * Rates are sampling probabilities (e.g. 0.1 means 1 in 10 events are sampled). * @param array $samplingRates * @since 1.28 */ public function setSamplingRates( array $samplingRates ) { $this->samplingRates = $samplingRates; } /** * Sets sampling rate for all items in $data. * The sample rate specified in a StatsdData entity overrides the sample rate specified here. * * @inheritDoc */ public function appendSampleRate( $data, $sampleRate = 1 ) { $samplingRates = $this->samplingRates; if ( !$samplingRates && $sampleRate !== 1 ) { $samplingRates = [ '*' => $sampleRate ]; } if ( $samplingRates ) { array_walk( $data, static function ( $item ) use ( $samplingRates ) { /** @var StatsdData $item */ foreach ( $samplingRates as $pattern => $rate ) { if ( fnmatch( $pattern, $item->getKey(), FNM_NOESCAPE ) ) { $item->setSampleRate( $item->getSampleRate() * $rate ); break; } } } ); } return $data; } /** * Send the metrics over UDP * Sample the metrics according to their sample rate and send the remaining ones. * * @param StatsdDataInterface|StatsdDataInterface[] $data message(s) to sent * strings are not allowed here as sampleData requires a StatsdDataInterface * @param int $sampleRate * * @return int the data sent in bytes */ public function send( $data, $sampleRate = 1 ) { if ( !is_array( $data ) ) { $data = [ $data ]; } if ( !$data ) { return 0; } foreach ( $data as $item ) { if ( !( $item instanceof StatsdDataInterface ) ) { throw new InvalidArgumentException( 'SamplingStatsdClient does not accept stringified messages' ); } } // add sampling $data = $this->appendSampleRate( $data, $sampleRate ); $data = $this->sampleData( $data ); $data = array_map( 'strval', $data ); // reduce number of packets if ( $this->getReducePacket() ) { $data = $this->reduceCount( $data ); } // failures in any of this should be silently ignored if .. $written = 0; try { $fp = $this->getSender()->open(); if ( !$fp ) { return 0; } foreach ( $data as $message ) { $written += $this->getSender()->write( $fp, $message ); } $this->getSender()->close( $fp ); } catch ( TimeoutException $e ) { throw $e; } catch ( Exception $e ) { $this->throwException( $e ); } return $written; } /** * Throw away some of the data according to the sample rate. * @param StatsdDataInterface[] $data * @return StatsdDataInterface[] */ protected function sampleData( $data ) { $newData = []; $mt_rand_max = mt_getrandmax(); foreach ( $data as $item ) { $samplingRate = $item->getSampleRate(); if ( $samplingRate <= 0.0 || $samplingRate > 1.0 ) { throw new LogicException( 'Sampling rate shall be within ]0, 1]' ); } if ( $samplingRate === 1 || ( mt_rand() / $mt_rand_max <= $samplingRate ) ) { $newData[] = $item; } } return $newData; } /** * Ideally this would override parent::throwException(), but that is private, * not protected. * * @param Exception $exception */ private function throwException( Exception $exception ) { if ( !$this->getFailSilently() ) { throw $exception; } } } /** @deprecated class alias since 1.43 */ class_alias( SamplingStatsdClient::class, 'SamplingStatsdClient' ); PK ! ���� � Stats/OutputFormats.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * @file */ declare( strict_types=1 ); namespace Wikimedia\Stats; use Wikimedia\Stats\Emitters\EmitterInterface; use Wikimedia\Stats\Emitters\NullEmitter; use Wikimedia\Stats\Emitters\UDPEmitter; use Wikimedia\Stats\Exceptions\UnsupportedFormatException; use Wikimedia\Stats\Formatters\DogStatsdFormatter; use Wikimedia\Stats\Formatters\FormatterInterface; use Wikimedia\Stats\Formatters\NullFormatter; use Wikimedia\Stats\Formatters\StatsdFormatter; /** * Metrics Format and Output Helpers * * @author Cole White * @since 1.41 */ class OutputFormats { public const NULL = 1; public const STATSD = 2; public const DOGSTATSD = 3; private const SUPPORTED_FORMATS = [ 'null' => self::NULL, 'statsd' => self::STATSD, 'dogstatsd' => self::DOGSTATSD ]; /** * Convert friendly format name to integer. * * @param string $format * @return int */ public static function getFormatFromString( string $format ): int { if ( self::SUPPORTED_FORMATS[$format] ?? false ) { return self::SUPPORTED_FORMATS[$format]; } throw new UnsupportedFormatException( "Format '" . $format . "' not supported. Expected one of " . json_encode( array_keys( self::SUPPORTED_FORMATS ) ) ); } /** * Returns an instance of the requested formatter. * * @param int $format * @return FormatterInterface */ public static function getNewFormatter( int $format ): FormatterInterface { switch ( $format ) { case self::DOGSTATSD: return new DogStatsdFormatter(); case self::STATSD: return new StatsdFormatter(); case self::NULL: return new NullFormatter(); default: throw new UnsupportedFormatException( 'Unsupported metrics format. Got format: ' . $format ); } } /** * Returns an emitter instance appropriate the formatter instance. * * @param string $prefix * @param StatsCache $cache * @param FormatterInterface $formatter * @param string|null $target * @return EmitterInterface */ public static function getNewEmitter( string $prefix, StatsCache $cache, FormatterInterface $formatter, ?string $target = null ): EmitterInterface { switch ( get_class( $formatter ) ) { case StatsdFormatter::class: case DogStatsdFormatter::class: return new UDPEmitter( $prefix, $cache, $formatter, $target ); case NullFormatter::class: return new NullEmitter; default: throw new UnsupportedFormatException( 'Unsupported metrics format. Got format: ' . get_class( $formatter ) ); } } } PK ! ��(�> > Stats/StatsdAwareInterface.phpnu �Iw�� <?php namespace Wikimedia\Stats; use Liuggio\StatsdClient\Factory\StatsdDataFactoryInterface; /** * Describes a Statsd aware interface * * @stable to implement * * @since 1.27 * @author Addshore */ interface StatsdAwareInterface { /** * Sets a StatsdDataFactory instance on the object * * @param StatsdDataFactoryInterface $statsFactory * @return null */ public function setStatsdDataFactory( StatsdDataFactoryInterface $statsFactory ); } /** @deprecated class alias since 1.43 */ class_alias( StatsdAwareInterface::class, 'StatsdAwareInterface' ); PK ! l�2aq q Stats/StatsCache.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ declare( strict_types=1 ); namespace Wikimedia\Stats; use TypeError; use Wikimedia\Stats\Metrics\MetricInterface; use Wikimedia\Stats\Metrics\NullMetric; /** * Singleton cache for Metric instances. * * For reuse and collision avoidance. Serves as the data source for Metric Emitters. * * @author Cole White * @since 1.41 */ class StatsCache { public const DELIMITER = '.'; /** @var MetricInterface[] */ private array $cache = []; /** * Get a metric object from cache or null. * * @param string $component * @param string $name * @param string $expectedClass * @return MetricInterface|null * @throws TypeError If cached value is for a different metric type. */ public function get( string $component, string $name, string $expectedClass ) { $key = self::cacheKey( $component, $name ); $metric = $this->cache[$key] ?? null; if ( $metric !== null && get_class( $metric ) !== $expectedClass ) { throw new TypeError( "Encountered metric name collision: $key defined as " . get_class( $metric ) . " but $expectedClass was requested" ); } return $metric; } /** * Add a metric object to the cache. * * @param string $component * @param string $name * @param MetricInterface|NullMetric $metric */ public function set( string $component, string $name, $metric ): void { $this->cache[self::cacheKey( $component, $name )] = $metric; } /** * Get all metrics from cache. * * @return MetricInterface[] */ public function getAllMetrics(): array { return $this->cache; } /** * Clears the cache. * * @return void */ public function clear(): void { $this->cache = []; } /** * Get the metric formatted name. * * Takes the provided name and constructs a more specific name by combining * component and name. * * @param string $component * @param string $name * @return string */ private static function cacheKey( string $component, string $name ): string { // mitigate collision of empty-component metric with a component metric if ( $component !== '' ) { return implode( self::DELIMITER, [ $component, $name ] ); } return $name; } } PK ! ��p! Stats/Emitters/NullEmitter.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * @file */ namespace Wikimedia\Stats\Emitters; /** * Metrics Null Emitter Implementation * * Emitter for null-formatted metrics. * * @author Cole White * @since 1.41 */ class NullEmitter implements EmitterInterface { public function send(): void { } } PK ! ��x� Stats/Emitters/UDPEmitter.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * @file */ declare( strict_types=1 ); namespace Wikimedia\Stats\Emitters; use InvalidArgumentException; use UDPTransport; use Wikimedia\Stats\Formatters\FormatterInterface; use Wikimedia\Stats\Metrics\NullMetric; use Wikimedia\Stats\StatsCache; use Wikimedia\Stats\StatsUtils; /** * Metrics UDP Emitter Implementation * * Leverages UDPTransport to emit wire-formatted metrics. * * @author Cole White * @since 1.41 */ class UDPEmitter implements EmitterInterface { /** @var string */ private string $prefix; /** @var StatsCache */ private StatsCache $cache; /** @var FormatterInterface */ private FormatterInterface $formatter; /** @var UDPTransport|null */ private ?UDPTransport $transport; /** @var int */ private int $payloadSize; public function __construct( string $prefix, StatsCache $cache, FormatterInterface $formatter, ?string $target ) { $this->prefix = $this->normalizePrefix( $prefix ); $this->cache = $cache; $this->formatter = $formatter; $this->transport = $target ? UDPTransport::newFromString( $target ) : null; $this->payloadSize = UDPTransport::MAX_PAYLOAD_SIZE; } /** * Sets payload size for batching. * * @param int $payloadSize * @return UDPEmitter */ public function withPayloadSize( int $payloadSize ): UDPEmitter { $this->payloadSize = $payloadSize; return $this; } /** * Overrides the transport. * * @param UDPTransport $transport * @return UDPEmitter */ public function withTransport( UDPTransport $transport ): UDPEmitter { $this->transport = $transport; return $this; } private function normalizePrefix( string $prefix ): string { if ( $prefix === '' ) { throw new InvalidArgumentException( 'UDPEmitter: Prefix cannot be empty.' ); } return StatsUtils::normalizeString( $prefix ); } /** * Renders metrics and samples through the formatter and returns a string[] of wire-formatted metric samples. * * @return array */ private function render(): array { $output = []; foreach ( $this->cache->getAllMetrics() as $metric ) { // Skip NullMetric instances. if ( get_class( $metric ) === NullMetric::class ) { continue; } foreach ( $this->formatter->getFormattedSamples( $this->prefix, $metric ) as $formatted ) { $output[] = $formatted; } } return $output; } /** * Batch the array of samples into payload of payloadSize and * emit them via the configured transport. * * @param array $samples * @param int $payloadSize * @return void */ private function batch( array $samples, int $payloadSize ): void { $payload = ''; foreach ( $samples as $sample ) { if ( strlen( $payload ) + strlen( $sample ) + 1 > $payloadSize ) { // Send this payload and make a new one $this->transport->emit( $payload ); $payload = ''; } $payload .= $sample . "\n"; } // Send what is left in the payload if ( strlen( $payload ) > 0 ) { $this->transport->emit( $payload ); } } /** * @inheritDoc */ public function send(): void { $this->batch( $this->render(), $this->payloadSize ); } } PK ! ��U� � # Stats/Emitters/EmitterInterface.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * @file */ namespace Wikimedia\Stats\Emitters; /** * Emitter Interface * * Renderers run the contents of StatsCache through a Formatter to * produce wire-formatted metrics. * * @author Cole White * @since 1.41 */ interface EmitterInterface { /** * Runs metrics and their samples from the cache through the formatter and sends them along. * * @return void */ public function send(): void; } PK ! ��� � $ Stats/BufferingStatsdDataFactory.phpnu �Iw�� <?php /** * Copyright 2015 Ori Livneh * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\Stats; use Liuggio\StatsdClient\Entity\StatsdData; use Liuggio\StatsdClient\Entity\StatsdDataInterface; use Liuggio\StatsdClient\Factory\StatsdDataFactory; /** * MediaWiki's adaption of StatsdDataFactory that provides buffering and metric prefixing. * * The buffering functionality exists as a performance optimisation to reduce network * traffic and StatsD processing by maximally utilizing StatsdClient's ability to * compress counter increments, and send all data in a few large UDP packets * over a single connection. * * These buffers are sent from MediaWikiEntryPoint::emitBufferedStatsdData. For web requests, * this happens post-send. For command-line scripts, this happens periodically from a database * callback (see MWLBFactory::applyGlobalState). * * @todo Evaluate upstream's StatsdService class, which implements similar buffering logic * and was released in statsd-php-client 1.0.13, shortly after we implemented this here * for statsd-php-client 1.0.12 at the time. * * @since 1.25 * @method StatsdData produceStatsdDataEntity() We use StatsdData::setKey, which is not in * StatsdDataInterface https://gerrit.wikimedia.org/r/643976 */ class BufferingStatsdDataFactory extends StatsdDataFactory implements IBufferingStatsdDataFactory { /** @var array */ protected $buffer = []; /** @var bool */ protected $enabled = true; /** @var string */ private $prefix; public function __construct( $prefix ) { parent::__construct(); $this->prefix = $prefix; } // // Methods for StatsdDataFactoryInterface // /** * @param string $key * @param float|int $time * @return void */ public function timing( $key, $time ) { if ( !$this->enabled ) { return; } $this->buffer[] = [ $key, $time, StatsdDataInterface::STATSD_METRIC_TIMING ]; } /** * @param string $key * @param float|int $value * @return void */ public function gauge( $key, $value ) { if ( !$this->enabled ) { return; } $this->buffer[] = [ $key, $value, StatsdDataInterface::STATSD_METRIC_GAUGE ]; } /** * @param string $key * @param float|int $value * @return array */ public function set( $key, $value ) { if ( !$this->enabled ) { return []; } $this->buffer[] = [ $key, $value, StatsdDataInterface::STATSD_METRIC_SET ]; return []; } /** * @param string $key * @return array */ public function increment( $key ) { if ( !$this->enabled ) { return []; } $this->buffer[] = [ $key, 1, StatsdDataInterface::STATSD_METRIC_COUNT ]; return []; } /** * @param string $key * @return void */ public function decrement( $key ) { if ( !$this->enabled ) { return; } $this->buffer[] = [ $key, -1, StatsdDataInterface::STATSD_METRIC_COUNT ]; } /** * @param string $key * @param int $delta * @return void */ public function updateCount( $key, $delta ) { if ( !$this->enabled ) { return; } $this->buffer[] = [ $key, $delta, StatsdDataInterface::STATSD_METRIC_COUNT ]; } /** * Normalize a metric key for StatsD * * The following are changes you may rely on: * * - Non-alphanumerical characters are converted to underscores. * - Empty segments are removed, e.g. "foo..bar" becomes "foo.bar". * This is mainly for StatsD-Graphite-Carbon setups where each segment is a directory * and must have a non-empty name. * - Deliberately invalid input that looks like `__METHOD__` (namespaced PHP class and method) * is changed from "\\Namespace\\Class::method" to "Namespace_Class.method". * This is used by ProfilerOutputStats. * * @param string $key * @return string */ private static function normalizeMetricKey( $key ) { $key = strtr( $key, [ '::' => '.' ] ); $key = preg_replace( '/[^a-zA-Z0-9.]+/', '_', $key ); $key = trim( $key, '_.' ); return strtr( $key, [ '..' => '.' ] ); } public function produceStatsdData( $key, $value = 1, $metric = StatsdDataInterface::STATSD_METRIC_COUNT ) { $entity = $this->produceStatsdDataEntity(); if ( $key !== null ) { $key = self::normalizeMetricKey( "{$this->prefix}.{$key}" ); $entity->setKey( $key ); } if ( $value !== null ) { $entity->setValue( $value ); } if ( $metric !== null ) { $entity->setMetric( $metric ); } return $entity; } // // Methods for IBufferingStatsdDataFactory // public function hasData() { return (bool)$this->buffer; } /** * @since 1.30 * @return StatsdData[] */ public function getData() { $data = []; foreach ( $this->buffer as [ $key, $val, $metric ] ) { // Optimization: Don't bother transmitting a counter update with a delta of zero if ( $metric === StatsdDataInterface::STATSD_METRIC_COUNT && !$val ) { continue; } // Optimisation: Avoid produceStatsdData cost during web requests (T288702). // Instead, we do it here in getData() right before the data is transmitted. $data[] = $this->produceStatsdData( $key, $val, $metric ); } return $data; } public function clearData() { $this->buffer = []; } public function getDataCount() { return count( $this->buffer ); } public function setEnabled( $enabled ) { $this->enabled = $enabled; } } /** @deprecated class alias since 1.43 */ class_alias( BufferingStatsdDataFactory::class, 'BufferingStatsdDataFactory' ); PK ! �pz)� � Stats/Sample.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * @file */ declare( strict_types=1 ); namespace Wikimedia\Stats; /** * Sample Data Class * * A container for a metric sample to be passed to the rendering function. * * @author Cole White * @since 1.41 */ class Sample { /** @var string[] */ private array $labelValues; /** @var float */ private float $value; /** * @param string[] $labelValues * @param float $value */ public function __construct( array $labelValues, float $value ) { $this->labelValues = $labelValues; $this->value = $value; } /** @return string[] */ public function getLabelValues(): array { return $this->labelValues; } /** @return float */ public function getValue(): float { return $this->value; } } PK ! ��x`e e % Stats/IBufferingStatsdDataFactory.phpnu �Iw�� <?php namespace Wikimedia\Stats; use Liuggio\StatsdClient\Entity\StatsdData; use Liuggio\StatsdClient\Factory\StatsdDataFactoryInterface; /** * MediaWiki adaptation of StatsdDataFactory that provides buffering functionality. * * @stable to implement * @since 1.30 * @see BufferingStatsdDataFactory */ interface IBufferingStatsdDataFactory extends StatsdDataFactoryInterface { /** * Check whether this data factory has any buffered data. * @return bool */ public function hasData(); /** * Return the buffered data from the factory. * @return StatsdData[] */ public function getData(); /** * Clear all buffered data from the factory * @since 1.31 */ public function clearData(); /** * Return the number of buffered statsd data entries * @return int * @since 1.31 */ public function getDataCount(); /** * Set collection enable status. * @param bool $enabled Will collection be enabled? * @return void */ public function setEnabled( $enabled ); } /** @deprecated class alias since 1.43 */ class_alias( IBufferingStatsdDataFactory::class, 'IBufferingStatsdDataFactory' ); PK ! �E�� � Stats/StatsFactory.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * @file */ declare( strict_types=1 ); namespace Wikimedia\Stats; use InvalidArgumentException; use Psr\Log\LoggerInterface; use Psr\Log\NullLogger; use TypeError; use Wikimedia\Stats\Emitters\EmitterInterface; use Wikimedia\Stats\Emitters\NullEmitter; use Wikimedia\Stats\Exceptions\InvalidConfigurationException; use Wikimedia\Stats\Metrics\BaseMetric; use Wikimedia\Stats\Metrics\CounterMetric; use Wikimedia\Stats\Metrics\GaugeMetric; use Wikimedia\Stats\Metrics\NullMetric; use Wikimedia\Stats\Metrics\TimingMetric; /** * StatsFactory Implementation * * This is the primary interface for validating metrics definitions * caching defined metrics, and returning metric instances from cache * if previously defined. * * @author Cole White * @since 1.41 */ class StatsFactory { /** @var string */ private string $component; /** @var StatsCache */ private StatsCache $cache; /** @var EmitterInterface */ private EmitterInterface $emitter; /** @var LoggerInterface */ private LoggerInterface $logger; /** @var IBufferingStatsdDataFactory|null */ private ?IBufferingStatsdDataFactory $statsdDataFactory = null; /** * StatsFactory builds, configures, and caches Metrics. * * @param StatsCache $cache * @param EmitterInterface $emitter * @param LoggerInterface $logger * @param string $component */ public function __construct( StatsCache $cache, EmitterInterface $emitter, LoggerInterface $logger, string $component = '' ) { $this->component = StatsUtils::normalizeString( $component ); $this->cache = $cache; $this->emitter = $emitter; $this->logger = $logger; } /** * Returns a new StatsFactory instance prefixed by component. * * @param string $component * @return StatsFactory */ public function withComponent( string $component ): StatsFactory { $statsFactory = new StatsFactory( $this->cache, $this->emitter, $this->logger, $component ); return $statsFactory->withStatsdDataFactory( $this->statsdDataFactory ); } public function withStatsdDataFactory( ?IBufferingStatsdDataFactory $statsdDataFactory ): StatsFactory { $this->statsdDataFactory = $statsdDataFactory; return $this; } /** * Makes a new CounterMetric or fetches one from cache. * * If a collision occurs, returns a NullMetric to suppress exceptions. * * @param string $name * @return CounterMetric|NullMetric */ public function getCounter( string $name ) { return $this->getMetric( $name, CounterMetric::class ); } /** * Makes a new GaugeMetric or fetches one from cache. * * If a collision occurs, returns a NullMetric to suppress exceptions. * * @param string $name * @return GaugeMetric|NullMetric */ public function getGauge( string $name ) { return $this->getMetric( $name, GaugeMetric::class ); } /** * Makes a new TimingMetric or fetches one from cache. * * If a collision occurs, returns a NullMetric to suppress exceptions. * * @param string $name * @return TimingMetric|NullMetric */ public function getTiming( string $name ) { return $this->getMetric( $name, TimingMetric::class ); } /** * Send all buffered metrics to the target and destroy the cache. */ public function flush(): void { $this->trackUsage(); $this->emitter->send(); $this->cache->clear(); } /** * Create a metric totaling all samples in the cache. */ private function trackUsage(): void { $accumulator = 0; foreach ( $this->cache->getAllMetrics() as $metric ) { $accumulator += $metric->getSampleCount(); } $this->getCounter( 'stats_buffered_total' ) ->copyToStatsdAt( 'stats.statslib.buffered' ) ->incrementBy( $accumulator ); } /** * Fetches a metric from cache or makes a new metric. * * If a metric name collision occurs, returns a NullMetric to suppress runtime exceptions. * * @param string $name * @param string $className * @return CounterMetric|TimingMetric|GaugeMetric|NullMetric */ private function getMetric( string $name, string $className ) { $name = StatsUtils::normalizeString( $name ); StatsUtils::validateMetricName( $name ); try { $metric = $this->cache->get( $this->component, $name, $className ); } catch ( TypeError | InvalidArgumentException | InvalidConfigurationException $ex ) { // Log the condition and give the caller something that will absorb calls. trigger_error( $ex->getMessage(), E_USER_WARNING ); return new NullMetric; } if ( $metric === null ) { $baseMetric = new BaseMetric( $this->component, $name ); $metric = new $className( $baseMetric->withStatsdDataFactory( $this->statsdDataFactory ), $this->logger ); $this->cache->set( $this->component, $name, $metric ); } return $metric->fresh(); } /** * Returns an instance of StatsFactory as a NULL value object * as a default for consumer code to fall back to. This can also * be used in tests environment where we don't need the full * UDP emitter object. * * @since 1.42 * * @return self */ public static function newNull(): self { return new self( new StatsCache(), new NullEmitter(), new NullLogger() ); } } PK ! ZF"� Stats/StatsUtils.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * @file */ declare( strict_types=1 ); namespace Wikimedia\Stats; use InvalidArgumentException; use Wikimedia\Stats\Exceptions\InvalidConfigurationException; /** * * StatsUtils Implementation * * Functionality common to all metric types. * * @author Cole White * @since 1.38 */ class StatsUtils { public const RE_VALID_NAME_AND_LABEL_NAME = "/^[a-zA-Z_][a-zA-Z0-9_]*$/"; public const DEFAULT_SAMPLE_RATE = 1.0; /** * Validates the new sample rate. Throws InvalidArgumentException if provided an invalid rate. * * @param float $newSampleRate * @throws InvalidArgumentException */ public static function validateNewSampleRate( float $newSampleRate ): void { if ( $newSampleRate < 0.0 || $newSampleRate > 1.0 ) { throw new InvalidArgumentException( "Sample rate can only be between 0.0 and 1.0. Got: " . $newSampleRate ); } } /** * Returns a subset of samples based on configured sample rate. * * @param float $sampleRate * @param array $samples * @return array */ public static function getFilteredSamples( float $sampleRate, array $samples ): array { if ( $sampleRate === 1.0 ) { return $samples; } $output = []; $randMax = mt_getrandmax(); foreach ( $samples as $sample ) { if ( mt_rand() / $randMax < $sampleRate ) { $output[] = $sample; } } return $output; } /** * Determines if provided string is a valid name. * * @param string $name * @return void * @throws InvalidArgumentException * @throws InvalidConfigurationException */ public static function validateMetricName( string $name ) { if ( $name === "" ) { throw new InvalidArgumentException( "Stats: Metric name cannot be empty." ); } if ( !preg_match( self::RE_VALID_NAME_AND_LABEL_NAME, $name ) ) { throw new InvalidConfigurationException( "Invalid metric name: '" . $name . "'" ); } } /** * Determines if provided string is a valid label key. * * @param string $key * @return void * @throws InvalidArgumentException * @throws InvalidConfigurationException */ public static function validateLabelKey( string $key ) { if ( $key === "" ) { throw new InvalidArgumentException( "Stats: Label key cannot be empty." ); } if ( !preg_match( self::RE_VALID_NAME_AND_LABEL_NAME, $key ) ) { throw new InvalidConfigurationException( "Invalid label key: '" . $key . "'" ); } } public static function validateLabelValue( string $value ) { if ( $value === "" ) { throw new InvalidArgumentException( "Stats: Label value cannot be empty." ); } } /** * Merges two associative arrays of labels. Prioritizes leftmost labels. * * @param array $leftLabels * @param array $rightLabels * @return array */ public static function mergeLabels( array $leftLabels, array $rightLabels ): array { $output = []; foreach ( $leftLabels as $key => $value ) { $output[$key] = $value; } foreach ( $rightLabels as $key => $value ) { if ( array_key_exists( $key, $output ) ) { continue; } $output[$key] = $value; } return $output; } /** * Normalize an array of strings. * * @param string[] $entities * @return string[] */ public static function normalizeArray( array $entities ): array { $normalizedEntities = []; foreach ( $entities as $entity ) { $normalizedEntities[] = self::normalizeString( $entity ); } return $normalizedEntities; } /** * Normalize strings to a metrics-compatible format. * * Replace any other non-alphanumeric characters with underscores. * Eliminate repeated underscores. * Trim leading or trailing underscores. * * @param string $entity * @return string */ public static function normalizeString( string $entity ): string { $entity = preg_replace( "/[^a-z0-9]/i", "_", $entity ); $entity = preg_replace( "/_+/", "_", $entity ); return trim( $entity, "_" ); } } PK ! d�^�� � 2 Stats/Exceptions/InvalidConfigurationException.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * @file */ namespace Wikimedia\Stats\Exceptions; use InvalidArgumentException; /** * InvalidConfigurationException * * This exception is raised when StatsFactory or Metric gets an associative * array as configuration that it cannot use to properly instantiate a Metric. * * @author Cole White * @since 1.41 */ class InvalidConfigurationException extends InvalidArgumentException { } PK ! eI�� . Stats/Exceptions/IllegalOperationException.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * @file */ namespace Wikimedia\Stats\Exceptions; use RuntimeException; /** * Thrown when an unresolvable configuration condition has been requested. * * @author Cole White * @since 1.41 */ class IllegalOperationException extends RuntimeException { } PK ! �d�7� � / Stats/Exceptions/UnsupportedFormatException.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * @file */ namespace Wikimedia\Stats\Exceptions; use InvalidArgumentException; /** * UnsupportedFormatException * * Raised when a metrics format is defined in the LocalSettings * configuration, but is not supported. * * See: OutputFormats::SUPPORTED_FORMATS and $wgStatsFormat * * @author Cole White * @since 1.41 */ class UnsupportedFormatException extends InvalidArgumentException { } PK ! �� W W ) Stats/PrefixingStatsdDataFactoryProxy.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\Stats; use Liuggio\StatsdClient\Entity\StatsdDataInterface; use Liuggio\StatsdClient\Factory\StatsdDataFactoryInterface; /** * Proxy to prefix metric keys sent to a StatsdDataFactoryInterface * * @since 1.32 */ class PrefixingStatsdDataFactoryProxy implements StatsdDataFactoryInterface { /** * @var string */ private $prefix; /** * @var StatsdDataFactoryInterface */ private $factory; /** * @param StatsdDataFactoryInterface $factory * @param string $prefix */ public function __construct( StatsdDataFactoryInterface $factory, $prefix ) { $this->factory = $factory; $this->prefix = rtrim( $prefix, '.' ); } /** * @param string $key * @return string */ private function addPrefixToKey( $key ) { return $this->prefix . '.' . $key; } public function timing( $key, $time ) { return $this->factory->timing( $this->addPrefixToKey( $key ), $time ); } public function gauge( $key, $value ) { return $this->factory->gauge( $this->addPrefixToKey( $key ), $value ); } public function set( $key, $value ) { return $this->factory->set( $this->addPrefixToKey( $key ), $value ); } public function increment( $key ) { return $this->factory->increment( $this->addPrefixToKey( $key ) ); } public function decrement( $key ) { return $this->factory->decrement( $this->addPrefixToKey( $key ) ); } public function updateCount( $key, $delta ) { return $this->factory->updateCount( $this->addPrefixToKey( $key ), $delta ); } public function produceStatsdData( $key, $value = 1, $metric = StatsdDataInterface::STATSD_METRIC_COUNT ) { return $this->factory->produceStatsdData( $this->addPrefixToKey( $key ), $value, $metric ); } } /** @deprecated class alias since 1.43 */ class_alias( PrefixingStatsdDataFactoryProxy::class, 'PrefixingStatsdDataFactoryProxy' ); PK ! �Y�ŭ � ' Stats/Formatters/FormatterInterface.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * @file */ namespace Wikimedia\Stats\Formatters; use Wikimedia\Stats\Metrics\MetricInterface; /** * Metrics Formatter Interface * * @author Cole White * @since 1.41 */ interface FormatterInterface { /** * Renders metric to line format. * * @param string $prefix * @param MetricInterface $metric * @return string[] */ public function getFormattedSamples( string $prefix, MetricInterface $metric ): array; } PK ! �pHz: : ' Stats/Formatters/DogStatsdFormatter.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * @file */ declare( strict_types=1 ); namespace Wikimedia\Stats\Formatters; use Wikimedia\Stats\Metrics\MetricInterface; /** * DogStatsD Wire Format Implementation * * @author Cole White * @since 1.41 */ class DogStatsdFormatter implements FormatterInterface { /** @inheritDoc */ public function getFormattedSamples( string $prefix, MetricInterface $metric ): array { $output = []; // append component to prefix if set if ( $metric->getComponent() !== '' ) { $prefix .= ".{$metric->getComponent()}"; } foreach ( $metric->getSamples() as $sample ) { // dot-separate prefix, component, and name `prefix.component.name` $stat = implode( '.', [ $prefix, $metric->getName() ] ); // merge value with separator `:42` $value = ':' . $sample->getValue(); // merge type indicator with separator `|c` $type = '|' . $metric->getTypeIndicator(); // blank string if samplerate is 1.0, otherwise add samplerate indicator `|@0.5` $sampleRate = $metric->getSampleRate() !== 1.0 ? '|@' . $metric->getSampleRate() : ''; // merge label keys and label values `key:value` $labels = []; $labelValues = $sample->getLabelValues(); foreach ( $metric->getLabelKeys() as $i => $labelKey ) { $labels[] = $labelKey . ':' . $labelValues[$i]; } // combine label kv pairs `|# key1:value1,key2:value2` $tags = $labels === [] ? '' : '|#' . implode( ",", $labels ); // combine and append to output `prefix.component.name:42|c|@0.5|#key1:value1,key2:value2` $output[] = $stat . $value . $type . $sampleRate . $tags; } return $output; } } PK ! .��s s " Stats/Formatters/NullFormatter.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * @file */ declare( strict_types=1 ); namespace Wikimedia\Stats\Formatters; /** * Null Formatter Implementation * * For passing to unconfigurable Renderers. * * @author Cole White * @since 1.41 */ class NullFormatter implements FormatterInterface { /** @inheritDoc */ public function getFormattedSamples( string $prefix, $metric ): array { return []; } } PK ! �\�G $ Stats/Formatters/StatsdFormatter.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * @file */ declare( strict_types=1 ); namespace Wikimedia\Stats\Formatters; use Wikimedia\Stats\Metrics\MetricInterface; /** * StatsD Wire Format Implementation * * @author Cole White * @since 1.41 */ class StatsdFormatter implements FormatterInterface { /** @inheritDoc */ public function getFormattedSamples( string $prefix, MetricInterface $metric ): array { $output = []; // append component to prefix if set if ( $metric->getComponent() !== '' ) { $prefix .= ".{$metric->getComponent()}"; } foreach ( $metric->getSamples() as $sample ) { // dot-separate prefix, component, name, and label values `prefix.component.name.value1.value2` $stat = implode( '.', array_merge( [ $prefix, $metric->getName() ], $sample->getLabelValues() ) ); // merge value with separator `:42` $value = ':' . $sample->getValue(); // merge type indicator with separator `|c` $type = '|' . $metric->getTypeIndicator(); // blank string if samplerate is 1.0, otherwise add samplerate indicator `|@0.5` $sampleRate = $metric->getSampleRate() !== 1.0 ? '|@' . $metric->getSampleRate() : ''; // combine and append to output `prefix.component.name.value1.value2:42|c|@0.5` $output[] = $stat . $value . $type . $sampleRate; } return $output; } } PK ! �����w �w ! ParamValidator/ParamValidator.phpnu �Iw�� <?php namespace Wikimedia\ParamValidator; use DomainException; use InvalidArgumentException; use Wikimedia\Assert\Assert; use Wikimedia\Message\DataMessageValue; use Wikimedia\Message\MessageValue; use Wikimedia\Message\ParamType; use Wikimedia\Message\ScalarParam; use Wikimedia\ObjectFactory\ObjectFactory; /** * Service for formatting and validating API parameters * * A settings array is simply an array with keys being the relevant PARAM_* * constants from this class, TypeDef, and its subclasses. * * As a general overview of the architecture here: * - ParamValidator handles some general validation of the parameter, * then hands off to a TypeDef subclass to validate the specific representation * based on the parameter's type. * - TypeDef subclasses handle conversion between the string representation * submitted by the client and the output PHP data types, validating that the * strings are valid representations of the intended type as they do so. * - ValidationException is used to report fatal errors in the validation back * to the caller, since the return value represents the successful result of * the validation and might be any type or class. * - The Callbacks interface allows ParamValidator to reach out and fetch data * it needs to perform the validation. Currently that includes: * - Fetching the value of the parameter being validated (largely since a generic * caller cannot know whether it needs to fetch a string from $_GET/$_POST or * an array from $_FILES). * - Reporting of non-fatal warnings back to the caller. * - Fetching the "high limits" flag when necessary, to avoid the need for loading * the user unnecessarily. * * @since 1.34 * @unstable */ class ParamValidator { // region Constants for parameter settings arrays /** @name Constants for parameter settings arrays * These constants are keys in the settings array that define how the * parameters coming in from the request are to be interpreted. * * If a constant is associated with a failure code, the failure code * and data are described. ValidationExceptions are typically thrown, but * those indicated as "non-fatal" are instead passed to * Callbacks::recordCondition(). * * Additional constants may be defined by TypeDef subclasses, or by other * libraries for controlling things like auto-generated parameter documentation. * For purposes of namespacing the constants, the values of all constants * defined by this library begin with 'param-'. * * @{ */ /** * (mixed) Default value of the parameter. If omitted, null is the default. * * TypeDef::validate() will be informed when the default value was used by the presence of * 'is-default' in $options. */ public const PARAM_DEFAULT = 'param-default'; /** * (string|array) Type of the parameter. * Must be a registered type or an array of enumerated values (in which case the "enum" * type must be registered). If omitted, the default is the PHP type of the default value * (see PARAM_DEFAULT). */ public const PARAM_TYPE = 'param-type'; /** * (bool) Indicate that the parameter is required. * * Failure codes: * - 'missingparam': The parameter is omitted/empty (and no default was set). No data. */ public const PARAM_REQUIRED = 'param-required'; /** * (bool) Indicate that the parameter is multi-valued. * * A multi-valued parameter may be submitted in one of several formats. All * of the following result in a value of `[ 'a', 'b', 'c' ]`. * - "a|b|c", i.e. pipe-separated. * - "\x1Fa\x1Fb\x1Fc", i.e. separated by U+001F, with a signalling U+001F at the start. * - As a string[], e.g. from a query string like "foo[]=a&foo[]=b&foo[]=c". * * Each of the multiple values is passed individually to the TypeDef. * $options will contain a 'values-list' key holding the entire list. * * By default duplicates are removed from the resulting parameter list. Use * PARAM_ALLOW_DUPLICATES to override that behavior. * * Failure codes: * - 'toomanyvalues': More values were supplied than are allowed. See * PARAM_ISMULTI_LIMIT1, PARAM_ISMULTI_LIMIT2, and constructor option * 'ismultiLimits'. Data: * - 'limit': The limit currently in effect. * - 'lowlimit': The limit when high limits are not allowed. * - 'highlimit': The limit when high limits are allowed. * - 'unrecognizedvalues': Non-fatal. Invalid values were passed and * PARAM_IGNORE_UNRECOGNIZED_VALUES was set. Data: * - 'values': The unrecognized values. */ public const PARAM_ISMULTI = 'param-ismulti'; /** * (int) Maximum number of multi-valued parameter values allowed * * @see PARAM_ISMULTI */ public const PARAM_ISMULTI_LIMIT1 = 'param-ismulti-limit1'; /** * (int) Maximum number of multi-valued parameter values allowed for users * allowed high limits. * * @see PARAM_ISMULTI */ public const PARAM_ISMULTI_LIMIT2 = 'param-ismulti-limit2'; /** * (bool|string) Whether a magic "all values" value exists for multi-valued * enumerated types, and if so what that value is. * * When PARAM_TYPE has a defined set of values and PARAM_ISMULTI is true, * this allows for an asterisk ('*') to be passed in place of a pipe-separated list of * every possible value. If a string is set, it will be used in place of the asterisk. */ public const PARAM_ALL = 'param-all'; /** * (bool) Allow the same value to be set more than once when PARAM_ISMULTI is true? * * If not truthy, the set of values will be passed through * `array_values( array_unique() )`. The default is falsey. */ public const PARAM_ALLOW_DUPLICATES = 'param-allow-duplicates'; /** * (bool) Indicate that the parameter's value should not be logged. * * Failure codes: (non-fatal) * - 'param-sensitive': Always recorded when the parameter is used. */ public const PARAM_SENSITIVE = 'param-sensitive'; /** * (bool) Indicate that a deprecated parameter was used. * * Failure codes: (non-fatal) * - 'param-deprecated': Always recorded when the parameter is used. */ public const PARAM_DEPRECATED = 'param-deprecated'; /** * (bool) Whether to downgrade "badvalue" errors to non-fatal when validating multi-valued * parameters. * @see PARAM_ISMULTI */ public const PARAM_IGNORE_UNRECOGNIZED_VALUES = 'param-ignore-unrecognized-values'; /** @} */ // endregion -- end of Constants for parameter settings arrays /** * @see TypeDef::OPT_ENFORCE_JSON_TYPES */ public const OPT_ENFORCE_JSON_TYPES = TypeDef::OPT_ENFORCE_JSON_TYPES; /** Magic "all values" value when PARAM_ALL is true. */ public const ALL_DEFAULT_STRING = '*'; /** A list of standard type names and types that may be passed as `$typeDefs` to __construct(). */ public const STANDARD_TYPES = [ 'boolean' => [ 'class' => TypeDef\BooleanDef::class ], 'checkbox' => [ 'class' => TypeDef\PresenceBooleanDef::class ], 'integer' => [ 'class' => TypeDef\IntegerDef::class ], 'limit' => [ 'class' => TypeDef\LimitDef::class ], 'float' => [ 'class' => TypeDef\FloatDef::class ], 'double' => [ 'class' => TypeDef\FloatDef::class ], 'string' => [ 'class' => TypeDef\StringDef::class ], 'password' => [ 'class' => TypeDef\PasswordDef::class ], 'NULL' => [ 'class' => TypeDef\StringDef::class, 'args' => [ [ TypeDef\StringDef::OPT_ALLOW_EMPTY => true, ] ], ], 'timestamp' => [ 'class' => TypeDef\TimestampDef::class ], 'upload' => [ 'class' => TypeDef\UploadDef::class ], 'enum' => [ 'class' => TypeDef\EnumDef::class ], 'expiry' => [ 'class' => TypeDef\ExpiryDef::class ], ]; /** @var Callbacks */ private $callbacks; /** @var ObjectFactory */ private $objectFactory; /** @var (TypeDef|array)[] Map parameter type names to TypeDef objects or ObjectFactory specs */ private $typeDefs = []; /** @var int Default values for PARAM_ISMULTI_LIMIT1 */ private $ismultiLimit1; /** @var int Default values for PARAM_ISMULTI_LIMIT2 */ private $ismultiLimit2; /** * @param Callbacks $callbacks * @param ObjectFactory $objectFactory To turn specs into TypeDef objects * @param array $options Associative array of additional settings * - 'typeDefs': (array) As for addTypeDefs(). If omitted, self::STANDARD_TYPES will be used. * Pass an empty array if you want to start with no registered types. * - 'ismultiLimits': (int[]) Two ints, being the default values for PARAM_ISMULTI_LIMIT1 and * PARAM_ISMULTI_LIMIT2. If not given, defaults to `[ 50, 500 ]`. */ public function __construct( Callbacks $callbacks, ObjectFactory $objectFactory, array $options = [] ) { $this->callbacks = $callbacks; $this->objectFactory = $objectFactory; $this->addTypeDefs( $options['typeDefs'] ?? self::STANDARD_TYPES ); $this->ismultiLimit1 = $options['ismultiLimits'][0] ?? 50; $this->ismultiLimit2 = $options['ismultiLimits'][1] ?? 500; } /** * List known type names * @return string[] */ public function knownTypes() { return array_keys( $this->typeDefs ); } /** * Register multiple type handlers * * @see addTypeDef() * @param array $typeDefs Associative array mapping `$name` to `$typeDef`. */ public function addTypeDefs( array $typeDefs ) { foreach ( $typeDefs as $name => $def ) { $this->addTypeDef( $name, $def ); } } /** * Register a type handler * * To allow code to omit PARAM_TYPE in settings arrays to derive the type * from PARAM_DEFAULT, it is strongly recommended that the following types be * registered: "boolean", "integer", "double", "string", "NULL", and "enum". * * When using ObjectFactory specs, the following extra arguments are passed: * - The Callbacks object for this ParamValidator instance. * * @param string $name Type name * @param TypeDef|array $typeDef Type handler or ObjectFactory spec to create one. */ public function addTypeDef( $name, $typeDef ) { Assert::parameterType( [ TypeDef::class, 'array' ], $typeDef, '$typeDef' ); if ( isset( $this->typeDefs[$name] ) ) { throw new InvalidArgumentException( "Type '$name' is already registered" ); } $this->typeDefs[$name] = $typeDef; } /** * Register a type handler, overriding any existing handler * @see addTypeDef * @param string $name Type name * @param TypeDef|array|null $typeDef As for addTypeDef, or null to unregister a type. */ public function overrideTypeDef( $name, $typeDef ) { Assert::parameterType( [ TypeDef::class, 'array', 'null' ], $typeDef, '$typeDef' ); if ( $typeDef === null ) { unset( $this->typeDefs[$name] ); } else { $this->typeDefs[$name] = $typeDef; } } /** * Test if a type is registered * @param string $name Type name * @return bool */ public function hasTypeDef( $name ) { return isset( $this->typeDefs[$name] ); } /** * Get the TypeDef for a type * @param string|array $type Any array is considered equivalent to the string "enum". * @return TypeDef|null */ public function getTypeDef( $type ) { if ( is_array( $type ) ) { $type = 'enum'; } if ( !isset( $this->typeDefs[$type] ) ) { return null; } $def = $this->typeDefs[$type]; if ( !$def instanceof TypeDef ) { $def = $this->objectFactory->createObject( $def, [ 'extraArgs' => [ $this->callbacks ], 'assertClass' => TypeDef::class, ] ); $this->typeDefs[$type] = $def; } return $def; } /** * Logic shared by normalizeSettings() and checkSettings() * @param array|mixed $settings * @return array */ private function normalizeSettingsInternal( $settings ) { // Shorthand if ( !is_array( $settings ) ) { $settings = [ self::PARAM_DEFAULT => $settings, ]; } // When type is not given, determine it from the type of the PARAM_DEFAULT if ( !isset( $settings[self::PARAM_TYPE] ) ) { $settings[self::PARAM_TYPE] = gettype( $settings[self::PARAM_DEFAULT] ?? null ); } return $settings; } /** * Normalize a parameter settings array * @param array|mixed $settings Default value or an array of settings * using PARAM_* constants. * @return array */ public function normalizeSettings( $settings ) { $settings = $this->normalizeSettingsInternal( $settings ); $typeDef = $this->getTypeDef( $settings[self::PARAM_TYPE] ); if ( $typeDef ) { $settings = $typeDef->normalizeSettings( $settings ); } return $settings; } /** * Validate a parameter settings array * * This is intended for validation of parameter settings during unit or * integration testing, and should implement strict checks. * * The rest of the code should generally be more permissive. * * @param string $name Parameter name * @param array|mixed $settings Default value or an array of settings * using PARAM_* constants. * @param array $options Options array, passed through to the TypeDef and Callbacks. * @return array * - 'issues': (string[]) Errors detected in $settings, as English text. If the settings * are valid, this will be the empty array. * - 'allowedKeys': (string[]) ParamValidator keys that are allowed in `$settings`. * - 'messages': (MessageValue[]) Messages to be checked for existence. */ public function checkSettings( string $name, $settings, array $options ): array { $settings = $this->normalizeSettingsInternal( $settings ); $issues = []; $allowedKeys = [ self::PARAM_TYPE, self::PARAM_DEFAULT, self::PARAM_REQUIRED, self::PARAM_ISMULTI, self::PARAM_SENSITIVE, self::PARAM_DEPRECATED, self::PARAM_IGNORE_UNRECOGNIZED_VALUES, ]; $messages = []; $type = $settings[self::PARAM_TYPE]; $typeDef = null; if ( !is_string( $type ) && !is_array( $type ) ) { $issues[self::PARAM_TYPE] = 'PARAM_TYPE must be a string or array, got ' . gettype( $type ); } else { $typeDef = $this->getTypeDef( $settings[self::PARAM_TYPE] ); if ( !$typeDef ) { if ( is_array( $type ) ) { $type = 'enum'; } $issues[self::PARAM_TYPE] = "Unknown/unregistered PARAM_TYPE \"$type\""; } } if ( isset( $settings[self::PARAM_DEFAULT] ) ) { try { $this->validateValue( $name, $settings[self::PARAM_DEFAULT], $settings, [ 'is-default' => true ] + $options ); } catch ( ValidationException $ex ) { $issues[self::PARAM_DEFAULT] = 'Value for PARAM_DEFAULT does not validate (code ' . $ex->getFailureMessage()->getCode() . ')'; } } if ( !is_bool( $settings[self::PARAM_REQUIRED] ?? false ) ) { $issues[self::PARAM_REQUIRED] = 'PARAM_REQUIRED must be boolean, got ' . gettype( $settings[self::PARAM_REQUIRED] ); } if ( !is_bool( $settings[self::PARAM_ISMULTI] ?? false ) ) { $issues[self::PARAM_ISMULTI] = 'PARAM_ISMULTI must be boolean, got ' . gettype( $settings[self::PARAM_ISMULTI] ); } if ( !empty( $settings[self::PARAM_ISMULTI] ) ) { $allowedKeys = array_merge( $allowedKeys, [ self::PARAM_ISMULTI_LIMIT1, self::PARAM_ISMULTI_LIMIT2, self::PARAM_ALL, self::PARAM_ALLOW_DUPLICATES ] ); $limit1 = $settings[self::PARAM_ISMULTI_LIMIT1] ?? $this->ismultiLimit1; $limit2 = $settings[self::PARAM_ISMULTI_LIMIT2] ?? $this->ismultiLimit2; if ( !is_int( $limit1 ) ) { $issues[self::PARAM_ISMULTI_LIMIT1] = 'PARAM_ISMULTI_LIMIT1 must be an integer, got ' . gettype( $settings[self::PARAM_ISMULTI_LIMIT1] ); } elseif ( $limit1 <= 0 ) { $issues[self::PARAM_ISMULTI_LIMIT1] = "PARAM_ISMULTI_LIMIT1 must be greater than 0, got $limit1"; } if ( !is_int( $limit2 ) ) { $issues[self::PARAM_ISMULTI_LIMIT2] = 'PARAM_ISMULTI_LIMIT2 must be an integer, got ' . gettype( $settings[self::PARAM_ISMULTI_LIMIT2] ); } elseif ( $limit2 < $limit1 ) { $issues[self::PARAM_ISMULTI_LIMIT2] = 'PARAM_ISMULTI_LIMIT2 must be greater than or equal to PARAM_ISMULTI_LIMIT1, but ' . "$limit2 < $limit1"; } $all = $settings[self::PARAM_ALL] ?? false; if ( !is_string( $all ) && !is_bool( $all ) ) { $issues[self::PARAM_ALL] = 'PARAM_ALL must be a string or boolean, got ' . gettype( $all ); } elseif ( $all !== false && $typeDef ) { if ( $all === true ) { $all = self::ALL_DEFAULT_STRING; } $values = $typeDef->getEnumValues( $name, $settings, $options ); if ( !is_array( $values ) ) { $issues[self::PARAM_ALL] = 'PARAM_ALL cannot be used with non-enumerated types'; } elseif ( in_array( $all, $values, true ) ) { $issues[self::PARAM_ALL] = 'Value for PARAM_ALL conflicts with an enumerated value'; } } if ( !is_bool( $settings[self::PARAM_ALLOW_DUPLICATES] ?? false ) ) { $issues[self::PARAM_ALLOW_DUPLICATES] = 'PARAM_ALLOW_DUPLICATES must be boolean, got ' . gettype( $settings[self::PARAM_ALLOW_DUPLICATES] ); } } if ( !is_bool( $settings[self::PARAM_SENSITIVE] ?? false ) ) { $issues[self::PARAM_SENSITIVE] = 'PARAM_SENSITIVE must be boolean, got ' . gettype( $settings[self::PARAM_SENSITIVE] ); } if ( !is_bool( $settings[self::PARAM_DEPRECATED] ?? false ) ) { $issues[self::PARAM_DEPRECATED] = 'PARAM_DEPRECATED must be boolean, got ' . gettype( $settings[self::PARAM_DEPRECATED] ); } if ( !is_bool( $settings[self::PARAM_IGNORE_UNRECOGNIZED_VALUES] ?? false ) ) { $issues[self::PARAM_IGNORE_UNRECOGNIZED_VALUES] = 'PARAM_IGNORE_UNRECOGNIZED_VALUES must be ' . 'boolean, got ' . gettype( $settings[self::PARAM_IGNORE_UNRECOGNIZED_VALUES] ); } $ret = [ 'issues' => $issues, 'allowedKeys' => $allowedKeys, 'messages' => $messages ]; if ( $typeDef ) { $ret = $typeDef->checkSettings( $name, $settings, $options, $ret ); } return $ret; } /** * Fetch and validate a parameter value using a settings array * * @param string $name Parameter name * @param array|mixed $settings Default value or an array of settings * using PARAM_* constants. * @param array $options Options array, passed through to the TypeDef and Callbacks. * - An additional option, 'is-default', will be set when the value comes from PARAM_DEFAULT. * @return mixed Validated parameter value * @throws ValidationException if the value is invalid */ public function getValue( $name, $settings, array $options = [] ) { $settings = $this->normalizeSettings( $settings ); $typeDef = $this->getTypeDef( $settings[self::PARAM_TYPE] ); if ( !$typeDef ) { throw new DomainException( "Param $name's type is unknown - {$settings[self::PARAM_TYPE]}" ); } $value = $typeDef->getValue( $name, $settings, $options ); if ( $value !== null ) { if ( !empty( $settings[self::PARAM_SENSITIVE] ) ) { $strValue = $typeDef->stringifyValue( $name, $value, $settings, $options ); $this->callbacks->recordCondition( DataMessageValue::new( 'paramvalidator-param-sensitive', [], 'param-sensitive' ) ->plaintextParams( $name, $strValue ), $name, $value, $settings, $options ); } // Set a warning if a deprecated parameter has been passed if ( !empty( $settings[self::PARAM_DEPRECATED] ) ) { $strValue = $typeDef->stringifyValue( $name, $value, $settings, $options ); $this->callbacks->recordCondition( DataMessageValue::new( 'paramvalidator-param-deprecated', [], 'param-deprecated' ) ->plaintextParams( $name, $strValue ), $name, $value, $settings, $options ); } } elseif ( isset( $settings[self::PARAM_DEFAULT] ) ) { $value = $settings[self::PARAM_DEFAULT]; $options['is-default'] = true; } return $this->validateValue( $name, $value, $settings, $options ); } /** * Validate a parameter value using a settings array * * @param string $name Parameter name * @param null|mixed $value Parameter value * @param array|mixed $settings Default value or an array of settings * using PARAM_* constants. * @param array $options Options array, passed through to the TypeDef and Callbacks. * - An additional option, 'values-list', will be set when processing the * values of a multi-valued parameter. * @return mixed Validated parameter value(s) * @throws ValidationException if the value is invalid */ public function validateValue( $name, $value, $settings, array $options = [] ) { $settings = $this->normalizeSettings( $settings ); $typeDef = $this->getTypeDef( $settings[self::PARAM_TYPE] ); if ( !$typeDef ) { throw new DomainException( "Param $name's type is unknown - {$settings[self::PARAM_TYPE]}" ); } if ( $value === null ) { if ( !empty( $settings[self::PARAM_REQUIRED] ) ) { throw new ValidationException( DataMessageValue::new( 'paramvalidator-missingparam', [], 'missingparam' ) ->plaintextParams( $name ), $name, $value, $settings ); } return null; } // Non-multi if ( empty( $settings[self::PARAM_ISMULTI] ) ) { if ( is_string( $value ) && substr( $value, 0, 1 ) === "\x1f" ) { throw new ValidationException( DataMessageValue::new( 'paramvalidator-notmulti', [], 'badvalue' ) ->plaintextParams( $name, $value ), $name, $value, $settings ); } // T326764: If the type of the actual param value is different from // the type that is defined via getParamSettings(), throw an exception // because this is a type to value mismatch. if ( is_array( $value ) && !$typeDef->supportsArrays() ) { throw new ValidationException( DataMessageValue::new( 'paramvalidator-notmulti', [], 'badvalue' ) ->plaintextParams( $name, gettype( $value ) ), $name, $value, $settings ); } return $typeDef->validate( $name, $value, $settings, $options ); } // Split the multi-value and validate each parameter $limit1 = $settings[self::PARAM_ISMULTI_LIMIT1] ?? $this->ismultiLimit1; $limit2 = max( $limit1, $settings[self::PARAM_ISMULTI_LIMIT2] ?? $this->ismultiLimit2 ); if ( is_array( $value ) ) { $valuesList = $value; } elseif ( $options[ self::OPT_ENFORCE_JSON_TYPES ] ?? false ) { throw new ValidationException( DataMessageValue::new( 'paramvalidator-multivalue-must-be-array', [], 'multivalue-must-be-array' )->plaintextParams( $name ), $name, $value, $settings ); } else { $valuesList = self::explodeMultiValue( $value, $limit2 + 1 ); } // Handle PARAM_ALL $enumValues = $typeDef->getEnumValues( $name, $settings, $options ); if ( is_array( $enumValues ) && isset( $settings[self::PARAM_ALL] ) && count( $valuesList ) === 1 ) { $allValue = is_string( $settings[self::PARAM_ALL] ) ? $settings[self::PARAM_ALL] : self::ALL_DEFAULT_STRING; if ( $valuesList[0] === $allValue ) { return $enumValues; } } // Avoid checking useHighLimits() unless it's actually necessary $sizeLimit = ( $limit2 > $limit1 && count( $valuesList ) > $limit1 && $this->callbacks->useHighLimits( $options ) ) ? $limit2 : $limit1; if ( count( $valuesList ) > $sizeLimit ) { throw new ValidationException( DataMessageValue::new( 'paramvalidator-toomanyvalues', [], 'toomanyvalues', [ 'parameter' => $name, 'limit' => $sizeLimit, 'lowlimit' => $limit1, 'highlimit' => $limit2, ] )->plaintextParams( $name )->numParams( $sizeLimit ), $name, $valuesList, $settings ); } $options['values-list'] = $valuesList; $validValues = []; $invalidValues = []; foreach ( $valuesList as $v ) { try { $validValues[] = $typeDef->validate( $name, $v, $settings, $options ); } catch ( ValidationException $ex ) { if ( $ex->getFailureMessage()->getCode() !== 'badvalue' || empty( $settings[self::PARAM_IGNORE_UNRECOGNIZED_VALUES] ) ) { throw $ex; } $invalidValues[] = $v; } } if ( $invalidValues ) { if ( is_array( $value ) ) { $value = self::implodeMultiValue( $value ); } $this->callbacks->recordCondition( DataMessageValue::new( 'paramvalidator-unrecognizedvalues', [], 'unrecognizedvalues', [ 'values' => $invalidValues, ] ) ->plaintextParams( $name, $value ) ->commaListParams( array_map( static function ( $v ) { return new ScalarParam( ParamType::PLAINTEXT, $v ); }, $invalidValues ) ) ->numParams( count( $invalidValues ) ), $name, $value, $settings, $options ); } // Throw out duplicates if requested if ( empty( $settings[self::PARAM_ALLOW_DUPLICATES] ) ) { $validValues = array_values( array_unique( $validValues ) ); } return $validValues; } /** * Describe parameter settings in a machine-readable format. * * @param string $name Parameter name. * @param array|mixed $settings Default value or an array of settings * using PARAM_* constants. * @param array $options Options array. * @return array */ public function getParamInfo( $name, $settings, array $options ) { $settings = $this->normalizeSettings( $settings ); $typeDef = $this->getTypeDef( $settings[self::PARAM_TYPE] ); $info = []; $info['type'] = $settings[self::PARAM_TYPE]; $info['required'] = !empty( $settings[self::PARAM_REQUIRED] ); if ( !empty( $settings[self::PARAM_DEPRECATED] ) ) { $info['deprecated'] = true; } if ( !empty( $settings[self::PARAM_SENSITIVE] ) ) { $info['sensitive'] = true; } if ( isset( $settings[self::PARAM_DEFAULT] ) ) { $info['default'] = $settings[self::PARAM_DEFAULT]; } $info['multi'] = !empty( $settings[self::PARAM_ISMULTI] ); if ( $info['multi'] ) { $info['lowlimit'] = $settings[self::PARAM_ISMULTI_LIMIT1] ?? $this->ismultiLimit1; $info['highlimit'] = max( $info['lowlimit'], $settings[self::PARAM_ISMULTI_LIMIT2] ?? $this->ismultiLimit2 ); $info['limit'] = $info['highlimit'] > $info['lowlimit'] && $this->callbacks->useHighLimits( $options ) ? $info['highlimit'] : $info['lowlimit']; if ( !empty( $settings[self::PARAM_ALLOW_DUPLICATES] ) ) { $info['allowsduplicates'] = true; } $allSpecifier = $settings[self::PARAM_ALL] ?? false; if ( $allSpecifier !== false ) { if ( !is_string( $allSpecifier ) ) { $allSpecifier = self::ALL_DEFAULT_STRING; } $info['allspecifier'] = $allSpecifier; } } if ( $typeDef ) { $info = array_merge( $info, $typeDef->getParamInfo( $name, $settings, $options ) ); } // Filter out nulls (strictly) return array_filter( $info, static function ( $v ) { return $v !== null; } ); } /** * Describe parameter settings in human-readable format * * @param string $name Parameter name being described. * @param array|mixed $settings Default value or an array of settings * using PARAM_* constants. * @param array $options Options array. * @return MessageValue[] */ public function getHelpInfo( $name, $settings, array $options ) { $settings = $this->normalizeSettings( $settings ); $typeDef = $this->getTypeDef( $settings[self::PARAM_TYPE] ); // Define ordering. Some are overwritten below, some expected from the TypeDef $info = [ self::PARAM_DEPRECATED => null, self::PARAM_REQUIRED => null, self::PARAM_SENSITIVE => null, self::PARAM_TYPE => null, self::PARAM_ISMULTI => null, self::PARAM_ISMULTI_LIMIT1 => null, self::PARAM_ALL => null, self::PARAM_DEFAULT => null, ]; if ( !empty( $settings[self::PARAM_DEPRECATED] ) ) { $info[self::PARAM_DEPRECATED] = MessageValue::new( 'paramvalidator-help-deprecated' ); } if ( !empty( $settings[self::PARAM_REQUIRED] ) ) { $info[self::PARAM_REQUIRED] = MessageValue::new( 'paramvalidator-help-required' ); } if ( !empty( $settings[self::PARAM_ISMULTI] ) ) { $info[self::PARAM_ISMULTI] = MessageValue::new( 'paramvalidator-help-multi-separate' ); $lowcount = $settings[self::PARAM_ISMULTI_LIMIT1] ?? $this->ismultiLimit1; $highcount = max( $lowcount, $settings[self::PARAM_ISMULTI_LIMIT2] ?? $this->ismultiLimit2 ); $values = $typeDef ? $typeDef->getEnumValues( $name, $settings, $options ) : null; if ( // Only mention the limits if they're likely to matter. $values === null || count( $values ) > $lowcount || !empty( $settings[self::PARAM_ALLOW_DUPLICATES] ) ) { if ( $highcount > $lowcount ) { $info[self::PARAM_ISMULTI_LIMIT1] = MessageValue::new( 'paramvalidator-help-multi-max' ) ->numParams( $lowcount, $highcount ); } else { $info[self::PARAM_ISMULTI_LIMIT1] = MessageValue::new( 'paramvalidator-help-multi-max-simple' ) ->numParams( $lowcount ); } } $allSpecifier = $settings[self::PARAM_ALL] ?? false; if ( $allSpecifier !== false ) { if ( !is_string( $allSpecifier ) ) { $allSpecifier = self::ALL_DEFAULT_STRING; } $info[self::PARAM_ALL] = MessageValue::new( 'paramvalidator-help-multi-all' ) ->plaintextParams( $allSpecifier ); } } if ( isset( $settings[self::PARAM_DEFAULT] ) && $typeDef ) { $value = $typeDef->stringifyValue( $name, $settings[self::PARAM_DEFAULT], $settings, $options ); if ( $value === '' ) { $info[self::PARAM_DEFAULT] = MessageValue::new( 'paramvalidator-help-default-empty' ); } elseif ( $value !== null ) { $info[self::PARAM_DEFAULT] = MessageValue::new( 'paramvalidator-help-default' ) ->plaintextParams( $value ); } } if ( $typeDef ) { $info = array_merge( $info, $typeDef->getHelpInfo( $name, $settings, $options ) ); } // Put the default at the very end (the TypeDef may have added extra messages) $default = $info[self::PARAM_DEFAULT]; unset( $info[self::PARAM_DEFAULT] ); $info[self::PARAM_DEFAULT] = $default; // Filter out nulls return array_filter( $info ); } /** * Split a multi-valued parameter string, like explode() * * Note that, unlike explode(), this will return an empty array when given * an empty string. * * @param string $value * @param int $limit * @return string[] */ public static function explodeMultiValue( $value, $limit ) { if ( $value === '' || $value === "\x1f" ) { return []; } if ( substr( $value, 0, 1 ) === "\x1f" ) { $sep = "\x1f"; $value = substr( $value, 1 ); } else { $sep = '|'; } return explode( $sep, $value, $limit ); } /** * Implode an array as a multi-valued parameter string, like implode() * * @param array $value * @return string */ public static function implodeMultiValue( array $value ) { if ( $value === [ '' ] ) { // There's no value that actually returns a single empty string. // Best we can do is this that returns two, which will be deduplicated to one. return '|'; } foreach ( $value as $v ) { if ( strpos( $v, '|' ) !== false ) { return "\x1f" . implode( "\x1f", $value ); } } return implode( '|', $value ); } } PK ! �<�� � ParamValidator/README.mdnu �Iw�� Wikimedia API Parameter Validator ================================= This library implements a system for processing and validating parameters to an API from data like that in PHP's `$_GET`, `$_POST`, and `$_FILES` arrays, based on a declarative definition of available parameters. Usage ----- <pre lang="php"> use Wikimedia\ParamValidator\ParamValidator; use Wikimedia\ParamValidator\TypeDef\IntegerDef; use Wikimedia\ParamValidator\SimpleCallbacks as ParamValidatorCallbacks; use Wikimedia\ParamValidator\ValidationException; // We assume these are available from your environment in some manner. /** @var Wikimedia\ObjectFactory\ObjectFactory $objectFactory */ $objectFactory = ...; /** @var Wikimedia\Message\MessageFormatterFactory $messageFormatterFactory */ $messageFormatterFactory = ...; $validator = new ParamValidator( new ParamValidatorCallbacks( $_POST + $_GET, $_FILES ), $objectFactory ); try { $intValue = $validator->getValue( 'intParam', [ ParamValidator::PARAM_TYPE => 'integer', ParamValidator::PARAM_DEFAULT => 0, IntegerDef::PARAM_MIN => 0, IntegerDef::PARAM_MAX => 5, ] ); } catch ( ValidationException $ex ) { $error = $messageFormatterFactory->getTextFormatter( 'en' )->format( $ex->getFailureMessage() ); echo "Validation error: $error\n"; } </pre> Failure reporting ----------------- This library uses Wikimedia\Message\DataMessageValue objects to report errors in both human-readable and machine-readable formats. Basic i18n for all errors generated by the library is included. For possible failure codes and their parameters, see the documentation of the relevant `PARAM_*` constants and TypeDef classes. Running tests ------------- composer install --prefer-dist composer test PK ! ��`� $ ParamValidator/Util/UploadedFile.phpnu �Iw�� <?php namespace Wikimedia\ParamValidator\Util; use Psr\Http\Message\UploadedFileInterface; use RuntimeException; use Wikimedia\AtEase\AtEase; /** * A simple implementation of UploadedFileInterface * * This exists so ParamValidator needn't depend on any specific PSR-7 * implementation for a class implementing UploadedFileInterface. It shouldn't * be used directly by other code, other than perhaps when implementing * Callbacks::getUploadedFile() when another PSR-7 library is not already in use. * * @since 1.34 * @unstable */ class UploadedFile implements UploadedFileInterface { /** @var array File data */ private $data; /** @var bool */ private $fromUpload; /** @var UploadedFileStream|null */ private $stream = null; /** @var bool Whether moveTo() was called */ private $moved = false; /** * @param array $data Data from $_FILES * @param bool $fromUpload Set false if using this task with data not from * $_FILES. Intended for unit testing. */ public function __construct( array $data, $fromUpload = true ) { $this->data = $data; $this->fromUpload = $fromUpload; } /** * Throw if there was an error * @throws RuntimeException */ private function checkError() { switch ( $this->data['error'] ) { case UPLOAD_ERR_OK: break; case UPLOAD_ERR_INI_SIZE: throw new RuntimeException( 'Upload exceeded maximum size' ); case UPLOAD_ERR_FORM_SIZE: throw new RuntimeException( 'Upload exceeded form-specified maximum size' ); case UPLOAD_ERR_PARTIAL: throw new RuntimeException( 'File was only partially uploaded' ); case UPLOAD_ERR_NO_FILE: throw new RuntimeException( 'No file was uploaded' ); case UPLOAD_ERR_NO_TMP_DIR: throw new RuntimeException( 'PHP has no temporary folder for storing uploaded files' ); case UPLOAD_ERR_CANT_WRITE: throw new RuntimeException( 'PHP was unable to save the uploaded file' ); case UPLOAD_ERR_EXTENSION: throw new RuntimeException( 'A PHP extension stopped the file upload' ); default: throw new RuntimeException( 'Unknown upload error code ' . $this->data['error'] ); } if ( $this->moved ) { throw new RuntimeException( 'File has already been moved' ); } if ( !isset( $this->data['tmp_name'] ) || !file_exists( $this->data['tmp_name'] ) ) { throw new RuntimeException( 'Uploaded file is missing' ); } } public function getStream() { if ( $this->stream ) { return $this->stream; } $this->checkError(); $this->stream = new UploadedFileStream( $this->data['tmp_name'] ); return $this->stream; } public function moveTo( $targetPath ) { $this->checkError(); if ( $this->fromUpload && !is_uploaded_file( $this->data['tmp_name'] ) ) { throw new RuntimeException( 'Specified file is not an uploaded file' ); } error_clear_last(); $ret = AtEase::quietCall( $this->fromUpload ? 'move_uploaded_file' : 'rename', $this->data['tmp_name'], $targetPath ); if ( $ret === false ) { $err = error_get_last(); throw new RuntimeException( "Move failed: " . ( $err['message'] ?? 'Unknown error' ) ); } $this->moved = true; if ( $this->stream ) { $this->stream->close(); $this->stream = null; } } public function getSize() { return $this->data['size'] ?? null; } public function getError() { return $this->data['error'] ?? UPLOAD_ERR_NO_FILE; } public function getClientFilename() { $ret = $this->data['name'] ?? null; return $ret === '' ? null : $ret; } public function getClientMediaType() { $ret = $this->data['type'] ?? null; return $ret === '' ? null : $ret; } } PK ! �v�� � * ParamValidator/Util/UploadedFileStream.phpnu �Iw�� <?php namespace Wikimedia\ParamValidator\Util; use Psr\Http\Message\StreamInterface; use RuntimeException; use Stringable; use Throwable; use Wikimedia\AtEase\AtEase; /** * Implementation of StreamInterface for a file in $_FILES * * This exists so ParamValidator needn't depend on any specific PSR-7 * implementation for a class implementing UploadedFileInterface. It shouldn't * be used directly by other code. * * @internal * @since 1.34 */ class UploadedFileStream implements Stringable, StreamInterface { /** @var resource|null File handle */ private $fp; /** @var int|false|null File size. False if not set yet. */ private $size = false; /** * Call, throwing on error * @param callable $func Callable to call * @param array $args Arguments * @param mixed $fail Failure return value * @param string $msg Message prefix * @return mixed * @throws RuntimeException if $func returns $fail */ private static function quietCall( callable $func, array $args, $fail, $msg ) { error_clear_last(); $ret = AtEase::quietCall( $func, ...$args ); if ( $ret === $fail ) { $err = error_get_last(); throw new RuntimeException( "$msg: " . ( $err['message'] ?? 'Unknown error' ) ); } return $ret; } /** * @param string $filename */ public function __construct( $filename ) { $this->fp = self::quietCall( 'fopen', [ $filename, 'r' ], false, 'Failed to open file' ); } /** * Check if the stream is open * @throws RuntimeException if closed */ private function checkOpen() { if ( !$this->fp ) { throw new RuntimeException( 'Stream is not open' ); } } public function __destruct() { $this->close(); } public function __toString() { try { $this->seek( 0 ); return $this->getContents(); } catch ( Throwable $ex ) { // Not allowed to throw return ''; } } public function close() { if ( $this->fp ) { // Spec doesn't care about close errors. try { // PHP 7 emits warnings, suppress AtEase::quietCall( 'fclose', $this->fp ); } catch ( \TypeError $unused ) { // While PHP 8 throws exceptions, ignore } $this->fp = null; } } public function detach() { $ret = $this->fp; $this->fp = null; return $ret; } public function getSize() { if ( $this->size === false ) { $this->size = null; if ( $this->fp ) { // Spec doesn't care about errors here. try { $stat = AtEase::quietCall( 'fstat', $this->fp ); } catch ( \TypeError $unused ) { } $this->size = $stat['size'] ?? null; } } return $this->size; } public function tell() { $this->checkOpen(); return self::quietCall( 'ftell', [ $this->fp ], -1, 'Cannot determine stream position' ); } public function eof() { // Spec doesn't care about errors here. try { return !$this->fp || AtEase::quietCall( 'feof', $this->fp ); } catch ( \TypeError $unused ) { return true; } } public function isSeekable() { return (bool)$this->fp; } public function seek( $offset, $whence = SEEK_SET ) { $this->checkOpen(); self::quietCall( 'fseek', [ $this->fp, $offset, $whence ], -1, 'Seek failed' ); } public function rewind() { $this->seek( 0 ); } public function isWritable() { return false; } public function write( $string ) { // @phan-suppress-previous-line PhanPluginNeverReturnMethod $this->checkOpen(); throw new RuntimeException( 'Stream is read-only' ); } public function isReadable() { return (bool)$this->fp; } public function read( $length ) { $this->checkOpen(); return self::quietCall( 'fread', [ $this->fp, $length ], false, 'Read failed' ); } public function getContents() { $this->checkOpen(); return self::quietCall( 'stream_get_contents', [ $this->fp ], false, 'Read failed' ); } public function getMetadata( $key = null ) { $this->checkOpen(); $ret = self::quietCall( 'stream_get_meta_data', [ $this->fp ], false, 'Metadata fetch failed' ); if ( $key !== null ) { $ret = $ret[$key] ?? null; } return $ret; } } PK ! zɎL L & ParamValidator/ValidationException.phpnu �Iw�� <?php namespace Wikimedia\ParamValidator; use Throwable; use UnexpectedValueException; use Wikimedia\Message\DataMessageValue; /** * Error reporting for ParamValidator * * @newable * @since 1.34 * @unstable */ class ValidationException extends UnexpectedValueException { /** @var DataMessageValue */ protected $failureMessage; /** @var string */ protected $paramName; /** @var mixed */ protected $paramValue; /** @var array */ protected $settings; /** * @stable to call * @param DataMessageValue $failureMessage * @param string $name Parameter name being validated * @param mixed $value Value of the parameter * @param array $settings Settings array being used for validation * @param Throwable|null $previous Previous throwable causing this failure */ public function __construct( DataMessageValue $failureMessage, $name, $value, $settings, ?Throwable $previous = null ) { $this->failureMessage = $failureMessage; $this->paramName = $name; $this->paramValue = $value; $this->settings = $settings; // Parent class needs some static English message. $msg = "Validation of `$name` failed: " . $failureMessage->getCode(); $data = $failureMessage->getData(); if ( $data ) { $msg .= ' ' . json_encode( $data, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE ); } parent::__construct( $msg, 0, $previous ); } /** * Fetch the validation failure message * * Users are encouraged to use this with an appropriate message formatter rather * than relying on the limited English text returned by getMessage(). * * @return DataMessageValue */ public function getFailureMessage() { return $this->failureMessage; } /** * Fetch the parameter name that failed validation * @return string */ public function getParamName() { return $this->paramName; } /** * Fetch the parameter value that failed validation * @return mixed */ public function getParamValue() { return $this->paramValue; } /** * Fetch the settings array that failed validation * @return array */ public function getSettings() { return $this->settings; } } PK ! Ê�� � ParamValidator/Callbacks.phpnu �Iw�� <?php namespace Wikimedia\ParamValidator; use Psr\Http\Message\UploadedFileInterface; use Wikimedia\Message\DataMessageValue; /** * Interface defining callbacks needed by ParamValidator * * The user of ParamValidator is expected to pass an object implementing this * interface to ParamValidator's constructor. * * All methods in this interface accept an "options array". This is the same `$options` * passed to ParamValidator::getValue(), ParamValidator::validateValue(), and the like * and is intended for communication of non-global state. * * @since 1.34 * @unstable */ interface Callbacks { /** * Test if a parameter exists in the request * @param string $name Parameter name * @param array $options Options array * @return bool True if present, false if absent. * Return false for file upload parameters. */ public function hasParam( $name, array $options ); /** * Fetch a value from the request * * Return `$default` for file-upload parameters. * * @param string $name Parameter name to fetch * @param mixed $default Default value to return if the parameter is unset. * @param array $options Options array * @return string|string[]|mixed A string or string[] if the parameter was found, * or $default if it was not. */ public function getValue( $name, $default, array $options ); /** * Test if a parameter exists as an upload in the request * @param string $name Parameter name * @param array $options Options array * @return bool True if present, false if absent. */ public function hasUpload( $name, array $options ); /** * Fetch data for a file upload * @param string $name Parameter name of the upload * @param array $options Options array * @return UploadedFileInterface|null Uploaded file, or null if there is no file for $name. */ public function getUploadedFile( $name, array $options ); /** * Record non-fatal conditions. * @param DataMessageValue $message Failure message * @param string $name Parameter name * @param mixed $value Parameter value * @param array $settings Parameter settings array * @param array $options Options array */ public function recordCondition( DataMessageValue $message, $name, $value, array $settings, array $options ); /** * Indicate whether "high limits" should be used. * * Some settings have multiple limits, one for "normal" users and a higher * one for "privileged" users. This is used to determine which class the * current user is in when necessary. * * @param array $options Options array * @return bool Whether the current user is privileged to use high limits */ public function useHighLimits( array $options ); } PK ! ��� , , ParamValidator/TypeDef.phpnu �Iw�� <?php namespace Wikimedia\ParamValidator; use Wikimedia\Message\DataMessageValue; use Wikimedia\Message\MessageValue; /** * Base definition for ParamValidator types. * * Most methods in this class accept an "options array". This is just the `$options` * passed to ParamValidator::getValue(), ParamValidator::validateValue(), and the like * and is intended for communication of non-global state to the Callbacks. * * @since 1.34 * @unstable for use in extensions. Intended to become stable to extend, at * least for use in MediaWiki, which already defines some subclasses. */ abstract class TypeDef { /** * @unstable Temporarily log warnings to detect misbehaving clients (T305973) */ public const OPT_LOG_BAD_TYPES = 'log-bad-types'; /** * Option that instructs TypeDefs to enforce the native type of parameter * values, instead of allowing string values as input. This is intended for * use with values coming from a JSON request body, and may accommodate for * differences between the type system of PHP and JSON. */ public const OPT_ENFORCE_JSON_TYPES = 'enforce-json-types'; /** @var Callbacks */ protected $callbacks; /** * @stable to call * * @param Callbacks $callbacks */ public function __construct( Callbacks $callbacks ) { $this->callbacks = $callbacks; } /** * Whether the value may be an array. * Note that this is different from multi-value. * This should only return true if each value can be an array. * @since 1.41 * @stable to override * @return bool */ public function supportsArrays() { return false; } /** * Fails if $value is not a string. * * @param string $name Parameter name being validated. * @param mixed $value Value being validated. * @param array $settings Parameter settings array. * @param array $options Options array. * * @return void */ protected function failIfNotString( string $name, $value, array $settings, array $options ): void { if ( !is_string( $value ) ) { $this->fatal( $this->failureMessage( 'needstring' ) ->params( gettype( $value ) ), $name, $value, $settings, $options ); } } /** * Throw a ValidationException. * This is a wrapper for failure() which explicitly declares that it * never returns, which is useful to static analysis tools like Phan. * * Note that parameters for `$name` and `$value` are always added as `$1` * and `$2`. * * @param DataMessageValue|string $failure Failure code or message. * @param string $name Parameter name being validated. * @param mixed $value Value being validated. * @param array $settings Parameter settings array. * @param array $options Options array. * @return never * @throws ValidationException always */ protected function fatal( $failure, $name, $value, array $settings, array $options ) { $this->failure( $failure, $name, $value, $settings, $options ); } /** * Record a failure message * * Depending on `$fatal`, this will either throw a ValidationException or * call $this->callbacks->recordCondition(). * * Note that parameters for `$name` and `$value` are always added as `$1` * and `$2`. * * @param DataMessageValue|string $failure Failure code or message. * @param string $name Parameter name being validated. * @param mixed $value Value being validated. * @param array $settings Parameter settings array. * @param array $options Options array. * @param bool $fatal Whether the failure is fatal */ protected function failure( $failure, $name, $value, array $settings, array $options, $fatal = true ) { if ( !is_string( $value ) ) { $value = (string)$this->stringifyValue( $name, $value, $settings, $options ); } if ( is_string( $failure ) ) { $mv = $this->failureMessage( $failure ) ->plaintextParams( $name, $value ); } else { $mv = DataMessageValue::new( $failure->getKey(), [], $failure->getCode(), $failure->getData() ) ->plaintextParams( $name, $value ) ->params( ...$failure->getParams() ); } if ( $fatal ) { throw new ValidationException( $mv, $name, $value, $settings ); } $this->callbacks->recordCondition( $mv, $name, $value, $settings, $options ); } /** * Create a DataMessageValue representing a failure * * The message key will be "paramvalidator-$code" or "paramvalidator-$code-$suffix". * * Use DataMessageValue's param mutators to add additional MessageParams. * Note that `failure()` will prepend parameters for `$name` and `$value`. * * @param string $code Failure code. * @param array|null $data Failure data. * @param string|null $suffix Suffix to append when producing the message key * @return DataMessageValue */ protected function failureMessage( $code, ?array $data = null, $suffix = null ): DataMessageValue { return DataMessageValue::new( "paramvalidator-$code" . ( $suffix !== null ? "-$suffix" : '' ), [], $code, $data ); } /** * Get the value from the request * @stable to override * * @note Only override this if you need to use something other than * $this->callbacks->getValue() to fetch the value. Reformatting from a * string should typically be done by self::validate(). * @note Handling of ParamValidator::PARAM_DEFAULT should be left to ParamValidator, * as should PARAM_REQUIRED and the like. * * @param string $name Parameter name being fetched. * @param array $settings Parameter settings array. * @param array $options Options array. * @return null|mixed Return null if the value wasn't present, otherwise a * value to be passed to self::validate(). */ public function getValue( $name, array $settings, array $options ) { return $this->callbacks->getValue( $name, null, $options ); } /** * Validate the value * * When ParamValidator is processing a multi-valued parameter, this will be * called once for each of the supplied values. Which may mean zero calls. * * When getValue() returned null, this will not be called. * * @param string $name Parameter name being validated. * @param mixed $value Value to validate, from getValue(). * @param array $settings Parameter settings array. * @param array $options Options array. Note the following values that may be set * by ParamValidator: * - is-default: (bool) If present and true, the value was taken from PARAM_DEFAULT rather * that being supplied by the client. * - values-list: (string[]) If defined, values of a multi-valued parameter are being processed * (and this array holds the full set of values). * @return mixed Validated value * @throws ValidationException if the value is invalid */ abstract public function validate( $name, $value, array $settings, array $options ); /** * Normalize a settings array * @stable to override * @param array $settings * @return array */ public function normalizeSettings( array $settings ) { return $settings; } /** * Validate a parameter settings array * * This is intended for validation of parameter settings during unit or * integration testing, and should implement strict checks. * * The rest of the code should generally be more permissive. * * @see ParamValidator::checkSettings() * @stable to override * * @param string $name Parameter name * @param array|mixed $settings Default value or an array of settings * using PARAM_* constants. * @param array $options Options array, passed through to the TypeDef and Callbacks. * @param array $ret * - 'issues': (string[]) Errors detected in $settings, as English text. If the settings * are valid, this will be the empty array. Keys on input are ParamValidator constants, * allowing the typedef to easily override core validation; this need not be preserved * when returned. * - 'allowedKeys': (string[]) ParamValidator keys that are allowed in `$settings`. * - 'messages': (MessageValue[]) Messages to be checked for existence. * @return array $ret, with any relevant changes. */ public function checkSettings( string $name, $settings, array $options, array $ret ): array { return $ret; } /** * Get the values for enum-like parameters * * This is primarily intended for documentation and implementation of * PARAM_ALL; it is the responsibility of the TypeDef to ensure that validate() * accepts the values returned here. * @stable to override * * @param string $name Parameter name being validated. * @param array $settings Parameter settings array. * @param array $options Options array. * @return array|null All possible enumerated values, or null if this is * not an enumeration. */ public function getEnumValues( $name, array $settings, array $options ) { return null; } /** * Convert a value to a string representation. * * This is intended as the inverse of getValue() and validate(): this * should accept anything returned by those methods or expected to be used * as PARAM_DEFAULT, and if the string from this method is passed in as client * input or PARAM_DEFAULT it should give equivalent output from validate(). * * @param string $name Parameter name being converted. * @param mixed $value Parameter value being converted. Do not pass null. * @param array $settings Parameter settings array. * @param array $options Options array. * @return string|null Return null if there is no representation of $value * reasonably satisfying the description given. */ public function stringifyValue( $name, $value, array $settings, array $options ) { if ( is_array( $value ) ) { return '(array)'; } return (string)$value; } /** * Describe parameter settings in a machine-readable format. * * Keys should be short strings using lowercase ASCII letters. Values * should generally be values that could be encoded in JSON or the like. * * This is intended to handle PARAM constants specific to this class. It * generally shouldn't handle constants defined on ParamValidator itself. * @stable to override * * @param string $name Parameter name. * @param array $settings Parameter settings array. * @param array $options Options array. * @return array */ public function getParamInfo( $name, array $settings, array $options ) { return []; } /** * Describe parameter settings in human-readable format * * Keys in the returned array should generally correspond to PARAM * constants. * * If relevant, a MessageValue describing the type itself should be * returned with key ParamValidator::PARAM_TYPE. * * The default messages for other ParamValidator-defined PARAM constants * may be suppressed by returning null as the value for those constants, or * replaced by returning a replacement MessageValue. Normally, however, * the default messages should not be changed. * * MessageValues describing any other constraints applied via PARAM * constants specific to this class should also be returned. * @stable to override * * @param string $name Parameter name being described. * @param array $settings Parameter settings array. * @param array $options Options array. * @return (MessageValue|null)[] */ public function getHelpInfo( $name, array $settings, array $options ) { return []; } } PK ! � ѹ � $ ParamValidator/TypeDef/StringDef.phpnu �Iw�� <?php namespace Wikimedia\ParamValidator\TypeDef; use Wikimedia\Message\MessageValue; use Wikimedia\ParamValidator\Callbacks; use Wikimedia\ParamValidator\ParamValidator; use Wikimedia\ParamValidator\TypeDef; /** * Type definition for string types * * The result from validate() is a PHP string. * * Failure codes: * - 'missingparam': The parameter is the empty string (and that's not allowed). No data. * * Additional codes may be generated when using certain PARAM constants. See * the constants' documentation for details. * * @since 1.34 * @unstable */ class StringDef extends TypeDef { /** * When this option is set, the empty string is considered a proper value. */ public const OPT_ALLOW_EMPTY = 'allowEmptyWhenRequired'; /** * (integer) Maximum length of a string in bytes. * * Failure codes: * - 'maxbytes': The string is too long. Data: * - 'maxbytes': The maximum number of bytes allowed, or null if no limit * - 'maxchars': The maximum number of characters allowed, or null if no limit */ public const PARAM_MAX_BYTES = 'param-max-bytes'; /** * (integer) Maximum length of a string in characters (Unicode codepoints). * * The string is assumed to be encoded as UTF-8. * * Failure codes: * - 'maxchars': The string is too long. Data: * - 'maxbytes': The maximum number of bytes allowed, or null if no limit * - 'maxchars': The maximum number of characters allowed, or null if no limit */ public const PARAM_MAX_CHARS = 'param-max-chars'; /** @var bool */ protected $allowEmptyWhenRequired = false; /** * @param Callbacks $callbacks * @param array $options Options: * - allowEmptyWhenRequired: (bool) Whether to reject the empty string when PARAM_REQUIRED. * Defaults to false. */ public function __construct( Callbacks $callbacks, array $options = [] ) { parent::__construct( $callbacks ); $this->allowEmptyWhenRequired = !empty( $options[ self::OPT_ALLOW_EMPTY ] ); } public function validate( $name, $value, array $settings, array $options ) { $allowEmptyWhenRequired = $options[ self::OPT_ALLOW_EMPTY ] ?? $this->allowEmptyWhenRequired; if ( !$allowEmptyWhenRequired && $value === '' && !empty( $settings[ParamValidator::PARAM_REQUIRED] ) ) { $this->failure( 'missingparam', $name, $value, $settings, $options ); } $this->failIfNotString( $name, $value, $settings, $options ); $len = strlen( $value ); if ( isset( $settings[self::PARAM_MAX_BYTES] ) && $len > $settings[self::PARAM_MAX_BYTES] ) { $this->failure( $this->failureMessage( 'maxbytes', [ 'maxbytes' => $settings[self::PARAM_MAX_BYTES] ?? null, 'maxchars' => $settings[self::PARAM_MAX_CHARS] ?? null, ] )->numParams( $settings[self::PARAM_MAX_BYTES], $len ), $name, $value, $settings, $options ); } $len = mb_strlen( $value, 'UTF-8' ); if ( isset( $settings[self::PARAM_MAX_CHARS] ) && $len > $settings[self::PARAM_MAX_CHARS] ) { $this->failure( $this->failureMessage( 'maxchars', [ 'maxbytes' => $settings[self::PARAM_MAX_BYTES] ?? null, 'maxchars' => $settings[self::PARAM_MAX_CHARS] ?? null, ] )->numParams( $settings[self::PARAM_MAX_CHARS], $len ), $name, $value, $settings, $options ); } return $value; } public function checkSettings( string $name, $settings, array $options, array $ret ): array { $ret = parent::checkSettings( $name, $settings, $options, $ret ); $ret['allowedKeys'] = array_merge( $ret['allowedKeys'], [ self::PARAM_MAX_BYTES, self::PARAM_MAX_CHARS, ] ); $maxb = $settings[self::PARAM_MAX_BYTES] ?? PHP_INT_MAX; if ( !is_int( $maxb ) ) { $ret['issues'][self::PARAM_MAX_BYTES] = 'PARAM_MAX_BYTES must be an integer, got ' . gettype( $maxb ); } elseif ( $maxb < 0 ) { $ret['issues'][self::PARAM_MAX_BYTES] = 'PARAM_MAX_BYTES must be greater than or equal to 0'; } $maxc = $settings[self::PARAM_MAX_CHARS] ?? PHP_INT_MAX; if ( !is_int( $maxc ) ) { $ret['issues'][self::PARAM_MAX_CHARS] = 'PARAM_MAX_CHARS must be an integer, got ' . gettype( $maxc ); } elseif ( $maxc < 0 ) { $ret['issues'][self::PARAM_MAX_CHARS] = 'PARAM_MAX_CHARS must be greater than or equal to 0'; } if ( !$this->allowEmptyWhenRequired && !empty( $settings[ParamValidator::PARAM_REQUIRED] ) ) { if ( $maxb === 0 ) { $ret['issues'][] = 'PARAM_REQUIRED is set, allowEmptyWhenRequired is not set, and ' . 'PARAM_MAX_BYTES is 0. That\'s impossible to satisfy.'; } if ( $maxc === 0 ) { $ret['issues'][] = 'PARAM_REQUIRED is set, allowEmptyWhenRequired is not set, and ' . 'PARAM_MAX_CHARS is 0. That\'s impossible to satisfy.'; } } return $ret; } public function getParamInfo( $name, array $settings, array $options ) { $info = parent::getParamInfo( $name, $settings, $options ); $info['maxbytes'] = $settings[self::PARAM_MAX_BYTES] ?? null; $info['maxchars'] = $settings[self::PARAM_MAX_CHARS] ?? null; return $info; } public function getHelpInfo( $name, array $settings, array $options ) { $info = parent::getHelpInfo( $name, $settings, $options ); if ( isset( $settings[self::PARAM_MAX_BYTES] ) ) { $info[self::PARAM_MAX_BYTES] = MessageValue::new( 'paramvalidator-help-type-string-maxbytes' ) ->numParams( $settings[self::PARAM_MAX_BYTES] ); } if ( isset( $settings[self::PARAM_MAX_CHARS] ) ) { $info[self::PARAM_MAX_CHARS] = MessageValue::new( 'paramvalidator-help-type-string-maxchars' ) ->numParams( $settings[self::PARAM_MAX_CHARS] ); } return $info; } } PK ! ���%� � % ParamValidator/TypeDef/BooleanDef.phpnu �Iw�� <?php namespace Wikimedia\ParamValidator\TypeDef; use Wikimedia\Message\MessageValue; use Wikimedia\Message\ParamType; use Wikimedia\Message\ScalarParam; use Wikimedia\ParamValidator\ParamValidator; use Wikimedia\ParamValidator\TypeDef; /** * Type definition for boolean types * * This type accepts certain defined strings to mean 'true' or 'false'. * The result from validate() is a PHP boolean. * * Failure codes: * - 'badbool': The value is not a recognized boolean. No data. * * @since 1.34 * @unstable */ class BooleanDef extends TypeDef { public const TRUEVALS = [ 'true', 't', 'yes', 'y', 'on', '1' ]; public const FALSEVALS = [ 'false', 'f', 'no', 'n', 'off', '0' ]; public function validate( $name, $value, array $settings, array $options ) { if ( is_bool( $value ) ) { return $value; } elseif ( $options[ self::OPT_ENFORCE_JSON_TYPES ] ?? false ) { $this->fatal( $this->failureMessage( 'badbool-type' ) ->params( gettype( $value ) ), $name, $value, $settings, $options ); } $value = strtolower( $value ); if ( in_array( $value, self::TRUEVALS, true ) ) { return true; } if ( $value === '' || in_array( $value, self::FALSEVALS, true ) ) { return false; } $this->fatal( $this->failureMessage( 'badbool' ) ->textListParams( array_map( [ $this, 'quoteVal' ], self::TRUEVALS ) ) ->numParams( count( self::TRUEVALS ) ) ->textListParams( array_merge( array_map( [ $this, 'quoteVal' ], self::FALSEVALS ), [ MessageValue::new( 'paramvalidator-emptystring' ) ] ) ) ->numParams( count( self::FALSEVALS ) + 1 ), $name, $value, $settings, $options ); } private function quoteVal( $v ) { return new ScalarParam( ParamType::TEXT, "\"$v\"" ); } public function stringifyValue( $name, $value, array $settings, array $options ) { return $value ? self::TRUEVALS[0] : self::FALSEVALS[0]; } public function getHelpInfo( $name, array $settings, array $options ) { $info = parent::getHelpInfo( $name, $settings, $options ); $info[ParamValidator::PARAM_TYPE] = MessageValue::new( 'paramvalidator-help-type-boolean' ) ->params( empty( $settings[ParamValidator::PARAM_ISMULTI] ) ? 1 : 2 ); return $info; } } PK ! &M�R� � % ParamValidator/TypeDef/NumericDef.phpnu �Iw�� <?php namespace Wikimedia\ParamValidator\TypeDef; use Wikimedia\Message\MessageValue; use Wikimedia\Message\ParamType; use Wikimedia\Message\ScalarParam; use Wikimedia\ParamValidator\ParamValidator; use Wikimedia\ParamValidator\TypeDef; use Wikimedia\ParamValidator\ValidationException; /** * Type definition base class for numeric types * * * Failure codes: * - 'outofrange': The value was outside of the allowed range. Data: * - 'min': Minimum allowed, or null if there is no limit. * - 'curmax': Current maximum allowed, or null if there is no limit. * - 'max': Normal maximum allowed, or null if there is no limit. * - 'highmax': High limits maximum allowed, or null if there is no limit. * * @stable to extend * @since 1.35 * @unstable */ abstract class NumericDef extends TypeDef { /** * (bool) Whether to enforce the specified range. * * If set and truthy, the 'outofrange' failure is non-fatal. */ public const PARAM_IGNORE_RANGE = 'param-ignore-range'; /** * (int|float) Minimum allowed value. */ public const PARAM_MIN = 'param-min'; /** * (int|float) Maximum allowed value (normal limits) */ public const PARAM_MAX = 'param-max'; /** * (int|float) Maximum allowed value (high limits) */ public const PARAM_MAX2 = 'param-max2'; /** @var string PHP type (as from `gettype()`) of values this NumericDef handles */ protected $valueType = 'integer'; /** * Check the range of a value * @param int|float $value Value to check. * @param string $name Parameter name being validated. * @param mixed $origValue Original value being validated. * @param array $settings Parameter settings array. * @param array $options Options array. * @return int|float Validated value, may differ from $value if * PARAM_IGNORE_RANGE was set. * @throws ValidationException if the value out of range, and PARAM_IGNORE_RANGE wasn't set. */ protected function checkRange( $value, $name, $origValue, array $settings, array $options ) { $min = $settings[self::PARAM_MIN] ?? null; $max1 = $settings[self::PARAM_MAX] ?? null; $max2 = $settings[self::PARAM_MAX2] ?? $max1; $err = false; if ( $min !== null && $value < $min ) { $err = true; $value = $min; } elseif ( $max1 !== null && $value > $max1 ) { if ( $max2 > $max1 && $this->callbacks->useHighLimits( $options ) ) { if ( $value > $max2 ) { $err = true; $value = $max2; } } else { $err = true; $value = $max1; } } if ( $err ) { $what = ''; if ( $min !== null ) { $what .= 'min'; } if ( $max1 !== null ) { $what .= 'max'; } $max = $max2 !== null && $max2 > $max1 && $this->callbacks->useHighLimits( $options ) ? $max2 : $max1; $this->failure( $this->failureMessage( 'outofrange', [ 'min' => $min, 'curmax' => $max, 'max' => $max1, 'highmax' => $max2, ], $what )->numParams( $min ?? '', $max ?? '' ), $name, $origValue, $settings, $options, empty( $settings[self::PARAM_IGNORE_RANGE] ) ); } return $value; } /** * @inheritDoc * @stable to override */ public function normalizeSettings( array $settings ) { if ( !isset( $settings[self::PARAM_MAX] ) ) { unset( $settings[self::PARAM_MAX2] ); } if ( isset( $settings[self::PARAM_MAX2] ) && isset( $settings[self::PARAM_MAX] ) && $settings[self::PARAM_MAX2] < $settings[self::PARAM_MAX] ) { $settings[self::PARAM_MAX2] = $settings[self::PARAM_MAX]; } return parent::normalizeSettings( $settings ); } /** * @inheritDoc * @stable to override */ public function checkSettings( string $name, $settings, array $options, array $ret ): array { $ret = parent::checkSettings( $name, $settings, $options, $ret ); $ret['allowedKeys'] = array_merge( $ret['allowedKeys'], [ self::PARAM_IGNORE_RANGE, self::PARAM_MIN, self::PARAM_MAX, self::PARAM_MAX2, ] ); if ( !is_bool( $settings[self::PARAM_IGNORE_RANGE] ?? false ) ) { $ret['issues'][self::PARAM_IGNORE_RANGE] = 'PARAM_IGNORE_RANGE must be boolean, got ' . gettype( $settings[self::PARAM_IGNORE_RANGE] ); } $min = $settings[self::PARAM_MIN] ?? null; $max = $settings[self::PARAM_MAX] ?? null; $max2 = $settings[self::PARAM_MAX2] ?? null; if ( $min !== null && gettype( $min ) !== $this->valueType ) { $ret['issues'][self::PARAM_MIN] = "PARAM_MIN must be $this->valueType, got " . gettype( $min ); } if ( $max !== null && gettype( $max ) !== $this->valueType ) { $ret['issues'][self::PARAM_MAX] = "PARAM_MAX must be $this->valueType, got " . gettype( $max ); } if ( $max2 !== null && gettype( $max2 ) !== $this->valueType ) { $ret['issues'][self::PARAM_MAX2] = "PARAM_MAX2 must be $this->valueType, got " . gettype( $max2 ); } if ( $min !== null && $max !== null && $min > $max ) { $ret['issues'][] = "PARAM_MIN must be less than or equal to PARAM_MAX, but $min > $max"; } if ( $max2 !== null ) { if ( $max === null ) { $ret['issues'][] = 'PARAM_MAX2 cannot be used without PARAM_MAX'; } elseif ( $max2 < $max ) { $ret['issues'][] = "PARAM_MAX2 must be greater than or equal to PARAM_MAX, but $max2 < $max"; } } return $ret; } /** * @inheritDoc * @stable to override */ public function getParamInfo( $name, array $settings, array $options ) { $info = parent::getParamInfo( $name, $settings, $options ); $info['min'] = $settings[self::PARAM_MIN] ?? null; $info['max'] = $settings[self::PARAM_MAX] ?? null; $info['highmax'] = $settings[self::PARAM_MAX2] ?? $info['max']; if ( $info['max'] === null || $info['highmax'] <= $info['max'] ) { unset( $info['highmax'] ); } return $info; } /** * @inheritDoc * @stable to override */ public function getHelpInfo( $name, array $settings, array $options ) { $info = parent::getHelpInfo( $name, $settings, $options ); $min = '−∞'; $max = '∞'; $msg = ''; if ( isset( $settings[self::PARAM_MIN] ) ) { $msg .= 'min'; $min = new ScalarParam( ParamType::NUM, $settings[self::PARAM_MIN] ); } if ( isset( $settings[self::PARAM_MAX] ) ) { $msg .= 'max'; $max = $settings[self::PARAM_MAX]; if ( isset( $settings[self::PARAM_MAX2] ) && $settings[self::PARAM_MAX2] > $max && $this->callbacks->useHighLimits( $options ) ) { $max = $settings[self::PARAM_MAX2]; } $max = new ScalarParam( ParamType::NUM, $max ); } if ( $msg !== '' ) { $isMulti = !empty( $settings[ParamValidator::PARAM_ISMULTI] ); // Messages: paramvalidator-help-type-number-min, paramvalidator-help-type-number-max, // paramvalidator-help-type-number-minmax $info[self::PARAM_MIN] = MessageValue::new( "paramvalidator-help-type-number-$msg" ) ->params( $isMulti ? 2 : 1, $min, $max ); } return $info; } } PK ! �Q�E % ParamValidator/TypeDef/IntegerDef.phpnu �Iw�� <?php namespace Wikimedia\ParamValidator\TypeDef; use Wikimedia\Message\MessageValue; use Wikimedia\ParamValidator\ParamValidator; /** * Type definition for integer types * * A valid representation consists of an optional sign (`+` or `-`) followed by * one or more decimal digits. * * The result from validate() is a PHP integer. * * * Failure codes: * - 'badinteger': The value was invalid or could not be represented as a PHP * integer. No data. * * @since 1.34 * @unstable */ class IntegerDef extends NumericDef { public function validate( $name, $value, array $settings, array $options ) { if ( is_int( $value ) ) { $ret = $value; } elseif ( is_float( $value ) ) { // Since JSON does not distinguish between integers and floats, // floats without a fractional parts can be treated as integers. // This is in line with the definition of the "integer" type in // JSON Schema, see https://json-schema.org/understanding-json-schema/reference/numeric. $ret = intval( $value ); if ( $ret - $value !== 0.0 ) { $this->fatal( $this->failureMessage( 'badinteger-fraction' ) ->params( gettype( $value ) ), $name, $value, $settings, $options ); } } elseif ( $options[ self::OPT_ENFORCE_JSON_TYPES ] ?? false ) { $this->fatal( $this->failureMessage( 'badinteger-type' ) ->params( gettype( $value ) ), $name, $value, $settings, $options ); } else { if ( is_array( $value ) || !preg_match( '/^[+-]?\d+$/D', $value ) ) { $this->fatal( 'badinteger', $name, $value, $settings, $options ); } else { $ret = intval( $value, 10 ); } } // intval() returns min/max on overflow, so check that if ( $ret === PHP_INT_MAX || $ret === PHP_INT_MIN ) { $tmp = ( $ret < 0 ? '-' : '' ) . ltrim( $value, '-0' ); if ( $tmp !== (string)$ret ) { $this->failure( 'badinteger', $name, $value, $settings, $options ); } } return $this->checkRange( $ret, $name, $value, $settings, $options ); } public function getHelpInfo( $name, array $settings, array $options ) { $info = parent::getHelpInfo( $name, $settings, $options ); $info[ParamValidator::PARAM_TYPE] = MessageValue::new( 'paramvalidator-help-type-integer' ) ->params( empty( $settings[ParamValidator::PARAM_ISMULTI] ) ? 1 : 2 ); return $info; } public function stringifyValue( $name, $value, array $settings, array $options ) { if ( !is_array( $value ) ) { return parent::stringifyValue( $name, $value, $settings, $options ); } return ParamValidator::implodeMultiValue( $value ); } } PK ! � �� � # ParamValidator/TypeDef/FloatDef.phpnu �Iw�� <?php namespace Wikimedia\ParamValidator\TypeDef; use Wikimedia\Message\MessageValue; use Wikimedia\ParamValidator\ParamValidator; /** * Type definition for a floating-point type * * A valid representation consists of: * - an optional sign (`+` or `-`) * - a decimal number, using `.` as the decimal separator and no grouping * - an optional E-notation suffix: the letter 'e' or 'E', an optional * sign, and an integer * * Thus, for example, "12", "-.4", "6.022e23", or "+1.7e-10". * * The result from validate() is a PHP float. * * Failure codes: * - 'badfloat': The value was invalid. No data. * - 'badfloat-notfinite': The value was in a valid format, but conversion resulted in * infinity or NAN. * * @since 1.34 * @unstable */ class FloatDef extends NumericDef { /** @inheritDoc */ protected $valueType = 'double'; public function validate( $name, $value, array $settings, array $options ) { if ( is_float( $value ) ) { $ret = $value; } elseif ( is_int( $value ) ) { $ret = (float)$value; } elseif ( $options[ self::OPT_ENFORCE_JSON_TYPES ] ?? false ) { $this->fatal( $this->failureMessage( 'badfloat-type' ) ->params( gettype( $value ) ), $name, $value, $settings, $options ); } else { if ( !preg_match( '/^[+-]?(?:\d*\.)?\d+(?:[eE][+-]?\d+)?$/D', $value ) ) { // Use a regex to avoid any potential oddness PHP's default conversion might allow. $this->fatal( 'badfloat', $name, $value, $settings, $options ); } $ret = (float)$value; } if ( !is_finite( $ret ) ) { $this->fatal( 'badfloat-notfinite', $name, $value, $settings, $options ); } return $this->checkRange( $ret, $name, $value, $settings, $options ); } public function stringifyValue( $name, $value, array $settings, array $options ) { // Ensure sufficient precision for round-tripping $digits = PHP_FLOAT_DIG; return sprintf( "%.{$digits}g", $value ); } public function getHelpInfo( $name, array $settings, array $options ) { $info = parent::getHelpInfo( $name, $settings, $options ); $info[ParamValidator::PARAM_TYPE] = MessageValue::new( 'paramvalidator-help-type-float' ) ->params( empty( $settings[ParamValidator::PARAM_ISMULTI] ) ? 1 : 2 ); return $info; } } PK ! 䏎ĉ � - ParamValidator/TypeDef/PresenceBooleanDef.phpnu �Iw�� <?php namespace Wikimedia\ParamValidator\TypeDef; use Wikimedia\Message\MessageValue; use Wikimedia\ParamValidator\ParamValidator; use Wikimedia\ParamValidator\TypeDef; /** * Type definition for checkbox-like boolean types * * This boolean is considered true if the parameter is present in the request, * regardless of value. The only way for it to be false is for the parameter to * be omitted entirely. * * The result from validate() is a PHP boolean. * * @since 1.34 * @unstable */ class PresenceBooleanDef extends TypeDef { public function getValue( $name, array $settings, array $options ) { return $this->callbacks->hasParam( $name, $options ) ? true : null; } public function validate( $name, $value, array $settings, array $options ) { return (bool)$value; } public function normalizeSettings( array $settings ) { // Cannot be multi-valued $settings[ParamValidator::PARAM_ISMULTI] = false; // Default the default to false so ParamValidator::getValue() returns false (T244440) $settings += [ ParamValidator::PARAM_DEFAULT => false ]; return parent::normalizeSettings( $settings ); } public function checkSettings( string $name, $settings, array $options, array $ret ): array { $ret = parent::checkSettings( $name, $settings, $options, $ret ); if ( !empty( $settings[ParamValidator::PARAM_ISMULTI] ) && !isset( $ret['issues'][ParamValidator::PARAM_ISMULTI] ) ) { $ret['issues'][ParamValidator::PARAM_ISMULTI] = 'PARAM_ISMULTI cannot be used for presence-boolean-type parameters'; } if ( ( $settings[ParamValidator::PARAM_DEFAULT] ?? false ) !== false && !isset( $ret['issues'][ParamValidator::PARAM_DEFAULT] ) ) { $ret['issues'][ParamValidator::PARAM_DEFAULT] = 'Default for presence-boolean-type parameters must be false or null'; } return $ret; } public function getParamInfo( $name, array $settings, array $options ) { $info = parent::getParamInfo( $name, $settings, $options ); // No need to report the default of "false" $info['default'] = null; return $info; } public function getHelpInfo( $name, array $settings, array $options ) { $info = parent::getHelpInfo( $name, $settings, $options ); $info[ParamValidator::PARAM_TYPE] = MessageValue::new( 'paramvalidator-help-type-presenceboolean' )->params( 1 ); // No need to report the default of "false" $info[ParamValidator::PARAM_DEFAULT] = null; return $info; } } PK ! �bt� $ ParamValidator/TypeDef/ExpiryDef.phpnu �Iw�� <?php namespace Wikimedia\ParamValidator\TypeDef; use InvalidArgumentException; use Wikimedia\Message\DataMessageValue; use Wikimedia\Message\MessageValue; use Wikimedia\ParamValidator\ParamValidator; use Wikimedia\ParamValidator\TypeDef; use Wikimedia\Timestamp\ConvertibleTimestamp; /** * Type definition for expiry timestamps. * * @since 1.35 */ class ExpiryDef extends TypeDef { /** @var array Possible values that mean "doesn't expire". */ public const INFINITY_VALS = [ 'infinite', 'indefinite', 'infinity', 'never' ]; /** * (bool) If truthy, the value given for the PARAM_MAX setting is used if the provided expiry * exceeds it, and the 'badexpiry-duration' message is shown as a warning. * * If false, 'badexpiry-duration' is shown and is fatal. */ public const PARAM_USE_MAX = 'param-use-max'; /** * (int|float) Maximum non-infinity duration. */ public const PARAM_MAX = 'param-max'; public function validate( $name, $value, array $settings, array $options ) { $this->failIfNotString( $name, $value, $settings, $options ); try { $expiry = self::normalizeExpiry( $value, TS_ISO_8601 ); } catch ( InvalidArgumentException $e ) { $this->failure( 'badexpiry', $name, $value, $settings, $options ); } if ( $expiry !== 'infinity' && $expiry < ConvertibleTimestamp::now( TS_ISO_8601 ) ) { $this->failure( 'badexpiry-past', $name, $value, $settings, $options ); } $max = $settings[self::PARAM_MAX] ?? null; if ( self::expiryExceedsMax( $expiry, $max ) ) { $dontUseMax = empty( $settings[self::PARAM_USE_MAX] ); // Show warning that expiry exceeds the max, and that the max is being used instead. $msg = DataMessageValue::new( $dontUseMax ? 'paramvalidator-badexpiry-duration' : 'paramvalidator-badexpiry-duration-max', [ $max ] ); $this->failure( $msg, $name, $value, $settings, $options, $dontUseMax ); return self::normalizeExpiry( $max, TS_ISO_8601 ); } return $expiry; } public function getHelpInfo( $name, array $settings, array $options ) { $info = parent::getHelpInfo( $name, $settings, $options ); $info[ParamValidator::PARAM_TYPE] = MessageValue::new( 'paramvalidator-help-type-expiry' ) ->params( empty( $settings[ParamValidator::PARAM_ISMULTI] ) ? 1 : 2 ) ->textListParams( // Should be quoted or monospace for presentation purposes, // but textListParams() doesn't do this. array_map( static function ( $val ) { return "\"$val\""; }, self::INFINITY_VALS ) ); return $info; } /** * Normalize a user-inputted expiry in ConvertibleTimestamp. * @param string|null $expiry * @param int|null $style null or in a format acceptable to ConvertibleTimestamp (TS_* constants) * * @return ConvertibleTimestamp|string|null Timestamp as ConvertibleTimestamp if $style is null, a string * timestamp in $style is not null, 'infinity' if $expiry is one of the self::INFINITY_VALS, * or null if $expiry is null. * * @throws InvalidArgumentException if $expiry is invalid */ public static function normalizeExpiry( ?string $expiry = null, ?int $style = null ) { if ( $expiry === null ) { return null; } if ( in_array( $expiry, self::INFINITY_VALS, true ) ) { return 'infinity'; } // ConvertibleTimestamp::time() used so we can fake the current time in ExpiryDefTest. $unix = strtotime( $expiry, ConvertibleTimestamp::time() ); if ( $unix === false ) { // Invalid expiry. throw new InvalidArgumentException( "Invalid expiry value: {$expiry}" ); } // Don't pass 0, since ConvertibleTimestamp interprets that to mean the current timestamp. // '00' does the right thing. Without this check, calling normalizeExpiry() // with 1970-01-01T00:00:00Z incorrectly returns the current time. $expiryConvertibleTimestamp = new ConvertibleTimestamp( $unix === 0 ? '00' : $unix ); if ( $style !== null ) { return $expiryConvertibleTimestamp->getTimestamp( $style ); } return $expiryConvertibleTimestamp; } /** * Returns a normalized expiry or the max expiry if the given expiry exceeds it. * @param string|null $expiry * @param string|null $maxExpiryDuration * @param int|null $style null or in a format acceptable to ConvertibleTimestamp (TS_* constants) * @return ConvertibleTimestamp|string|null Timestamp as ConvertibleTimestamp if $style is null, a string * timestamp in $style is not null, 'infinity' if $expiry is one of the self::INFINITY_VALS, * or null if $expiry is null. */ public static function normalizeUsingMaxExpiry( ?string $expiry, ?string $maxExpiryDuration, ?int $style ) { if ( self::expiryExceedsMax( $expiry, $maxExpiryDuration ) ) { return self::normalizeExpiry( $maxExpiryDuration, $style ); } return self::normalizeExpiry( $expiry, $style ); } public function checkSettings( string $name, $settings, array $options, array $ret ): array { $ret = parent::checkSettings( $name, $settings, $options, $ret ); $ret['allowedKeys'][] = self::PARAM_USE_MAX; $ret['allowedKeys'][] = self::PARAM_MAX; return $ret; } /** * Given an expiry, test if the normalized value exceeds the given maximum. * * @param string|null $expiry * @param string|null $max Relative maximum duration acceptable by strtotime() (i.e. '6 months') * @return bool */ private static function expiryExceedsMax( ?string $expiry, ?string $max = null ): bool { $expiry = self::normalizeExpiry( $expiry ); $max = self::normalizeExpiry( $max ); if ( !$max || !$expiry || $expiry === 'infinity' ) { // Either there is no max or given expiry was invalid. return false; } return $expiry > $max; } } PK ! �!iX� � " ParamValidator/TypeDef/EnumDef.phpnu �Iw�� <?php namespace Wikimedia\ParamValidator\TypeDef; use Wikimedia\Message\DataMessageValue; use Wikimedia\Message\ListParam; use Wikimedia\Message\ListType; use Wikimedia\Message\MessageParam; use Wikimedia\Message\MessageValue; use Wikimedia\Message\ParamType; use Wikimedia\Message\ScalarParam; use Wikimedia\ParamValidator\ParamValidator; use Wikimedia\ParamValidator\TypeDef; /** * Type definition for enumeration types. * * This class expects that PARAM_TYPE is an array of allowed values. Subclasses * may override getEnumValues() to determine the allowed values differently. * * The result from validate() is one of the defined values. * * Failure codes: * - 'badvalue': The value is not a recognized value. No data. * * Additional codes may be generated when using certain PARAM constants. See * the constants' documentation for details. * * @since 1.34 * @unstable */ class EnumDef extends TypeDef { /** * (array) Associative array of deprecated values. * * Keys are the deprecated parameter values. Value is one of the following: * - null: Parameter isn't actually deprecated. * - true: Parameter is deprecated. * - MessageValue: Parameter is deprecated, and this message (converted to a DataMessageValue) * is used in place of the default for passing to $this->failure(). * * Note that this does not add any values to the enumeration, it only * documents existing values as being deprecated. * * Failure codes: (non-fatal) * - 'deprecated-value': A deprecated value was encountered. No data. */ public const PARAM_DEPRECATED_VALUES = 'param-deprecated-values'; public function validate( $name, $value, array $settings, array $options ) { $values = $this->getEnumValues( $name, $settings, $options ); if ( in_array( $value, $values, true ) ) { // Set a warning if a deprecated parameter value has been passed if ( empty( $options['is-default'] ) && isset( $settings[self::PARAM_DEPRECATED_VALUES][$value] ) ) { $msg = $settings[self::PARAM_DEPRECATED_VALUES][$value]; if ( $msg instanceof MessageValue ) { $message = DataMessageValue::new( $msg->getKey(), $msg->getParams(), 'deprecated-value', $msg instanceof DataMessageValue ? $msg->getData() : null ); } else { $message = $this->failureMessage( 'deprecated-value' ); } $this->failure( $message, $name, $value, $settings, $options, false ); } return $value; } $isMulti = isset( $options['values-list'] ); $this->failure( $this->failureMessage( 'badvalue', [], $isMulti ? 'enummulti' : 'enumnotmulti' ) ->textListParams( array_map( static function ( $v ) { return new ScalarParam( ParamType::PLAINTEXT, $v ); }, $values ) ) ->numParams( count( $values ) ), $name, $value, $settings, $options ); } public function checkSettings( string $name, $settings, array $options, array $ret ): array { $ret = parent::checkSettings( $name, $settings, $options, $ret ); $ret['allowedKeys'][] = self::PARAM_DEPRECATED_VALUES; $dv = $settings[self::PARAM_DEPRECATED_VALUES] ?? []; if ( !is_array( $dv ) ) { $ret['issues'][self::PARAM_DEPRECATED_VALUES] = 'PARAM_DEPRECATED_VALUES must be an array, got ' . gettype( $dv ); } else { $values = array_map( function ( $v ) use ( $name, $settings, $options ) { return $this->stringifyValue( $name, $v, $settings, $options ); }, $this->getEnumValues( $name, $settings, $options ) ); foreach ( $dv as $k => $v ) { $k = $this->stringifyValue( $name, $k, $settings, $options ); if ( !in_array( $k, $values, true ) ) { $ret['issues'][] = "PARAM_DEPRECATED_VALUES contains \"$k\", which is not " . 'one of the enumerated values'; } elseif ( $v instanceof MessageValue ) { $ret['messages'][] = $v; } elseif ( $v !== null && $v !== true ) { $type = $v === false ? 'false' : ( is_object( $v ) ? get_class( $v ) : gettype( $v ) ); $ret['issues'][] = 'Values in PARAM_DEPRECATED_VALUES must be null, true, or MessageValue, ' . "but value for \"$k\" is $type"; } } } return $ret; } public function getEnumValues( $name, array $settings, array $options ) { return array_values( $settings[ParamValidator::PARAM_TYPE] ); } public function stringifyValue( $name, $value, array $settings, array $options ) { if ( !is_array( $value ) ) { return parent::stringifyValue( $name, $value, $settings, $options ); } return ParamValidator::implodeMultiValue( $value ); } public function getParamInfo( $name, array $settings, array $options ) { $info = parent::getParamInfo( $name, $settings, $options ); $info['type'] = $this->sortEnumValues( $name, $this->getEnumValues( $name, $settings, $options ), $settings, $options ); if ( !empty( $settings[self::PARAM_DEPRECATED_VALUES] ) ) { $deprecatedValues = array_intersect( array_keys( $settings[self::PARAM_DEPRECATED_VALUES] ), $this->getEnumValues( $name, $settings, $options ) ); if ( $deprecatedValues ) { $deprecatedValues = $this->sortEnumValues( $name, $deprecatedValues, $settings, $options ); $info['deprecatedvalues'] = array_values( $deprecatedValues ); } } return $info; } public function getHelpInfo( $name, array $settings, array $options ) { $info = parent::getHelpInfo( $name, $settings, $options ); $isMulti = !empty( $settings[ParamValidator::PARAM_ISMULTI] ); $values = $this->getEnumValuesForHelp( $name, $settings, $options ); $count = count( $values ); $i = array_search( '', $values, true ); if ( $i === false ) { $valuesParam = new ListParam( ListType::COMMA, $values ); } else { unset( $values[$i] ); $valuesParam = MessageValue::new( 'paramvalidator-help-type-enum-can-be-empty' ) ->commaListParams( $values ) ->numParams( count( $values ) ); } $info[ParamValidator::PARAM_TYPE] = MessageValue::new( 'paramvalidator-help-type-enum' ) ->params( $isMulti ? 2 : 1 ) ->params( $valuesParam ) ->numParams( $count ); // Suppress standard ISMULTI message, it should be incorporated into our type message. $info[ParamValidator::PARAM_ISMULTI] = null; return $info; } /** * Sort enum values for help/param info output * * @param string $name Parameter name being described. * @param string[] $values Values being sorted * @param array $settings Parameter settings array. * @param array $options Options array. * @return string[] */ protected function sortEnumValues( string $name, array $values, array $settings, array $options ): array { // sort values by deprecation status and name $flags = []; foreach ( $values as $k => $value ) { $flag = 0; if ( isset( $settings[self::PARAM_DEPRECATED_VALUES][$value] ) ) { $flag |= 1; } $flags[$k] = $flag; } array_multisort( $flags, $values, SORT_NATURAL ); return $values; } /** * Return enum values formatted for the help message * * @param string $name Parameter name being described. * @param array $settings Parameter settings array. * @param array $options Options array. * @return (MessageParam|string)[] */ protected function getEnumValuesForHelp( $name, array $settings, array $options ) { $values = $this->getEnumValues( $name, $settings, $options ); $values = $this->sortEnumValues( $name, $values, $settings, $options ); // @todo Indicate deprecated values in some manner. Probably that needs // MessageValue and/or MessageParam to have a generic ability to wrap // values in HTML without that HTML coming out in the text format too. return $values; } } PK ! )�Q� � & ParamValidator/TypeDef/PasswordDef.phpnu �Iw�� <?php namespace Wikimedia\ParamValidator\TypeDef; use Wikimedia\ParamValidator\ParamValidator; /** * Type definition for "password" types * * This is a string type that forces PARAM_SENSITIVE = true. * * @see StringDef * @since 1.34 * @unstable */ class PasswordDef extends StringDef { public function normalizeSettings( array $settings ) { $settings[ParamValidator::PARAM_SENSITIVE] = true; return parent::normalizeSettings( $settings ); } public function checkSettings( string $name, $settings, array $options, array $ret ): array { $ret = parent::checkSettings( $name, $settings, $options, $ret ); if ( ( $settings[ParamValidator::PARAM_SENSITIVE] ?? true ) !== true && !isset( $ret['issues'][ParamValidator::PARAM_SENSITIVE] ) ) { $ret['issues'][ParamValidator::PARAM_SENSITIVE] = 'Cannot set PARAM_SENSITIVE to false for password-type parameters'; } return $ret; } } PK ! S���� � # ParamValidator/TypeDef/LimitDef.phpnu �Iw�� <?php namespace Wikimedia\ParamValidator\TypeDef; use Wikimedia\Message\MessageValue; use Wikimedia\ParamValidator\ParamValidator; /** * Type definition for "limit" types * * A limit type is an integer type that also accepts the magic value "max". * IntegerDef::PARAM_MIN defaults to 0 for this type. * * @see IntegerDef * @since 1.34 * @unstable */ class LimitDef extends IntegerDef { /** * @inheritDoc * * Additional `$options` accepted: * - 'parse-limit': (bool) Default true, set false to return 'max' rather * than determining the effective value. */ public function validate( $name, $value, array $settings, array $options ) { if ( $value === 'max' ) { if ( $options['parse-limit'] ?? true ) { $value = $this->callbacks->useHighLimits( $options ) ? $settings[self::PARAM_MAX2] ?? $settings[self::PARAM_MAX] ?? PHP_INT_MAX : $settings[self::PARAM_MAX] ?? PHP_INT_MAX; } return $value; } return parent::validate( $name, $value, $settings, $options ); } public function normalizeSettings( array $settings ) { $settings += [ self::PARAM_MIN => 0, ]; // Cannot be multi-valued $settings[ParamValidator::PARAM_ISMULTI] = false; return parent::normalizeSettings( $settings ); } public function checkSettings( string $name, $settings, array $options, array $ret ): array { $ret = parent::checkSettings( $name, $settings, $options, $ret ); if ( !empty( $settings[ParamValidator::PARAM_ISMULTI] ) && !isset( $ret['issues'][ParamValidator::PARAM_ISMULTI] ) ) { $ret['issues'][ParamValidator::PARAM_ISMULTI] = 'PARAM_ISMULTI cannot be used for limit-type parameters'; } if ( ( $settings[self::PARAM_MIN] ?? 0 ) < 0 ) { $ret['issues'][] = 'PARAM_MIN must be greater than or equal to 0'; } if ( !isset( $settings[self::PARAM_MAX] ) ) { $ret['issues'][] = 'PARAM_MAX must be set'; } return $ret; } public function getHelpInfo( $name, array $settings, array $options ) { $info = parent::getHelpInfo( $name, $settings, $options ); $info[ParamValidator::PARAM_TYPE] = MessageValue::new( 'paramvalidator-help-type-limit' ) ->params( 1 ); return $info; } } PK ! K��� � ' ParamValidator/TypeDef/TimestampDef.phpnu �Iw�� <?php namespace Wikimedia\ParamValidator\TypeDef; use InvalidArgumentException; use Wikimedia\Message\MessageValue; use Wikimedia\ParamValidator\Callbacks; use Wikimedia\ParamValidator\ParamValidator; use Wikimedia\ParamValidator\TypeDef; use Wikimedia\ParamValidator\ValidationException; use Wikimedia\Timestamp\ConvertibleTimestamp; use Wikimedia\Timestamp\TimestampException; /** * Type definition for timestamp types * * This uses the wikimedia/timestamp library for parsing and formatting the * timestamps. * * The result from validate() is a ConvertibleTimestamp by default, but this * may be changed by both a constructor option and a PARAM constant. * * Failure codes: * - 'badtimestamp': The timestamp is not valid. No data, but the * TimestampException is available via Exception::getPrevious(). * - 'unclearnowtimestamp': Non-fatal. The value is the empty string or "0". * Use 'now' instead if you really want the current timestamp. No data. * * @since 1.34 * @unstable */ class TimestampDef extends TypeDef { /** * (string|int) Timestamp format to return from validate() * * Values include: * - 'ConvertibleTimestamp': A ConvertibleTimestamp object. * - 'DateTime': A PHP DateTime object * - One of ConvertibleTimestamp's TS_* constants. * * This does not affect the format returned by stringifyValue(). */ public const PARAM_TIMESTAMP_FORMAT = 'param-timestamp-format'; /** @var string|int */ protected $defaultFormat; /** @var int */ protected $stringifyFormat; /** * @param Callbacks $callbacks * @param array $options Options: * - defaultFormat: (string|int) Default for PARAM_TIMESTAMP_FORMAT. * Default if not specified is 'ConvertibleTimestamp'. * - stringifyFormat: (int) Format to use for stringifyValue(). * Default is TS_ISO_8601. */ public function __construct( Callbacks $callbacks, array $options = [] ) { parent::__construct( $callbacks ); $this->defaultFormat = $options['defaultFormat'] ?? 'ConvertibleTimestamp'; $this->stringifyFormat = $options['stringifyFormat'] ?? TS_ISO_8601; // Check values by trying to convert 0 if ( $this->defaultFormat !== 'ConvertibleTimestamp' && $this->defaultFormat !== 'DateTime' && ConvertibleTimestamp::convert( $this->defaultFormat, 0 ) === false ) { throw new InvalidArgumentException( 'Invalid value for $options[\'defaultFormat\']' ); } if ( ConvertibleTimestamp::convert( $this->stringifyFormat, 0 ) === false ) { throw new InvalidArgumentException( 'Invalid value for $options[\'stringifyFormat\']' ); } } public function validate( $name, $value, array $settings, array $options ) { // Confusing synonyms for the current time accepted by ConvertibleTimestamp if ( !$value ) { $this->failure( 'unclearnowtimestamp', $name, $value, $settings, $options, false ); $value = 'now'; } $format = $settings[self::PARAM_TIMESTAMP_FORMAT] ?? $this->defaultFormat; try { $timestampObj = new ConvertibleTimestamp( $value === 'now' ? false : $value ); $timestamp = ( $format !== 'ConvertibleTimestamp' && $format !== 'DateTime' ) ? $timestampObj->getTimestamp( $format ) : null; } catch ( TimestampException $ex ) { // $this->failure() doesn't handle passing a previous exception throw new ValidationException( $this->failureMessage( 'badtimestamp' )->plaintextParams( $name, $value ), $name, $value, $settings, $ex ); } switch ( $format ) { case 'ConvertibleTimestamp': return $timestampObj; case 'DateTime': // Eew, no getter. return $timestampObj->timestamp; default: return $timestamp; } } public function checkSettings( string $name, $settings, array $options, array $ret ): array { $ret = parent::checkSettings( $name, $settings, $options, $ret ); $ret['allowedKeys'] = array_merge( $ret['allowedKeys'], [ self::PARAM_TIMESTAMP_FORMAT, ] ); $f = $settings[self::PARAM_TIMESTAMP_FORMAT] ?? $this->defaultFormat; if ( $f !== 'ConvertibleTimestamp' && $f !== 'DateTime' && ConvertibleTimestamp::convert( $f, 0 ) === false ) { $ret['issues'][self::PARAM_TIMESTAMP_FORMAT] = 'Value for PARAM_TIMESTAMP_FORMAT is not valid'; } return $ret; } public function stringifyValue( $name, $value, array $settings, array $options ) { if ( !$value instanceof ConvertibleTimestamp ) { $value = new ConvertibleTimestamp( $value ); } return $value->getTimestamp( $this->stringifyFormat ); } public function getHelpInfo( $name, array $settings, array $options ) { $info = parent::getHelpInfo( $name, $settings, $options ); $info[ParamValidator::PARAM_TYPE] = MessageValue::new( 'paramvalidator-help-type-timestamp' ) ->params( empty( $settings[ParamValidator::PARAM_ISMULTI] ) ? 1 : 2 ); return $info; } } PK ! ����� � $ ParamValidator/TypeDef/UploadDef.phpnu �Iw�� <?php namespace Wikimedia\ParamValidator\TypeDef; use InvalidArgumentException; use Psr\Http\Message\UploadedFileInterface; use UnexpectedValueException; use Wikimedia\Message\MessageValue; use Wikimedia\ParamValidator\ParamValidator; use Wikimedia\ParamValidator\TypeDef; use Wikimedia\ParamValidator\Util\UploadedFile; /** * Type definition for upload types * * The result from validate() is an object implementing UploadedFileInterface. * * Failure codes: * - 'badupload': The upload is not valid. Data: * - 'code': A value indicating why the upload was not valid: * - 'inisize': The upload exceeded the maximum in php.ini. * - 'formsize': The upload exceeded the maximum in the form post. * - 'partial': The file was only partially uploaded. * - 'nofile': There was no file. * - 'notmpdir': PHP has no temporary directory to store the upload. * - 'cantwrite': PHP could not store the upload. * - 'phpext': A PHP extension rejected the upload. * - 'notupload': The field was present in the submission but was not encoded as an upload. * - 'size': The configured size (in bytes), if 'code' is 'inisize'. * * @since 1.34 * @unstable */ class UploadDef extends TypeDef { public function getValue( $name, array $settings, array $options ) { $ret = $this->callbacks->getUploadedFile( $name, $options ); if ( $ret && $ret->getError() === UPLOAD_ERR_NO_FILE && !$this->callbacks->hasParam( $name, $options ) ) { // This seems to be that the client explicitly specified "no file" for the field // instead of just omitting the field completely. DWTM. $ret = null; } elseif ( !$ret && $this->callbacks->hasParam( $name, $options ) ) { // The client didn't format their upload properly so it came in as an ordinary // field. Convert it to an error. $ret = new UploadedFile( [ 'name' => '', 'type' => '', 'tmp_name' => '', 'error' => -42, // PHP's UPLOAD_ERR_* are all positive numbers. 'size' => 0, ] ); } return $ret; } /** * Fetch the value of PHP's upload_max_filesize ini setting * * This method exists so it can be mocked by unit tests that can't * affect ini_get() directly. * * @codeCoverageIgnore * @return string|false */ protected function getIniSize() { return ini_get( 'upload_max_filesize' ); } public function validate( $name, $value, array $settings, array $options ) { static $codemap = [ -42 => 'notupload', // Local from getValue() UPLOAD_ERR_FORM_SIZE => 'formsize', UPLOAD_ERR_PARTIAL => 'partial', UPLOAD_ERR_NO_FILE => 'nofile', UPLOAD_ERR_NO_TMP_DIR => 'notmpdir', UPLOAD_ERR_CANT_WRITE => 'cantwrite', UPLOAD_ERR_EXTENSION => 'phpext', ]; if ( !$value instanceof UploadedFileInterface ) { // Err? $type = get_debug_type( $value ); throw new InvalidArgumentException( "\$value must be UploadedFileInterface, got $type" ); } $err = $value->getError(); if ( $err === UPLOAD_ERR_OK ) { return $value; } elseif ( $err === UPLOAD_ERR_INI_SIZE ) { static $prefixes = [ 'g' => 1024 ** 3, 'm' => 1024 ** 2, 'k' => 1024 ** 1, ]; $size = $this->getIniSize(); $last = strtolower( substr( $size, -1 ) ); $size = intval( $size, 10 ) * ( $prefixes[$last] ?? 1 ); $this->failure( $this->failureMessage( 'badupload', [ 'code' => 'inisize', 'size' => $size, ], 'inisize' )->sizeParams( $size ), $name, '', $settings, $options ); } elseif ( isset( $codemap[$err] ) ) { $this->failure( $this->failureMessage( 'badupload', [ 'code' => $codemap[$err] ], $codemap[$err] ), $name, '', $settings, $options ); } else { $constant = ''; foreach ( get_defined_constants() as $c => $v ) { // @phan-suppress-next-line PhanTypeComparisonFromArray if ( $v === $err && str_starts_with( $c, 'UPLOAD_ERR_' ) ) { $constant = " ($c?)"; } } throw new UnexpectedValueException( "Unrecognized PHP upload error value $err$constant" ); } } public function checkSettings( string $name, $settings, array $options, array $ret ): array { $ret = parent::checkSettings( $name, $settings, $options, $ret ); if ( isset( $settings[ParamValidator::PARAM_DEFAULT] ) ) { $ret['issues'][ParamValidator::PARAM_DEFAULT] = 'Cannot specify a default for upload-type parameters'; } if ( !empty( $settings[ParamValidator::PARAM_ISMULTI] ) && !isset( $ret['issues'][ParamValidator::PARAM_ISMULTI] ) ) { $ret['issues'][ParamValidator::PARAM_ISMULTI] = 'PARAM_ISMULTI cannot be used for upload-type parameters'; } return $ret; } public function stringifyValue( $name, $value, array $settings, array $options ) { // Not going to happen. return null; } public function getHelpInfo( $name, array $settings, array $options ) { $info = parent::getHelpInfo( $name, $settings, $options ); $info[ParamValidator::PARAM_TYPE] = MessageValue::new( 'paramvalidator-help-type-upload' ); return $info; } } PK ! � �(4 4 " ParamValidator/SimpleCallbacks.phpnu �Iw�� <?php namespace Wikimedia\ParamValidator; use Wikimedia\Message\DataMessageValue; use Wikimedia\ParamValidator\Util\UploadedFile; /** * Simple Callbacks implementation for $_GET/$_POST/$_FILES data * * Options array keys used by this class: * - 'useHighLimits': (bool) Return value from useHighLimits() * * @since 1.34 * @unstable */ class SimpleCallbacks implements Callbacks { /** @var (string|string[])[] $_GET/$_POST data */ private $params; /** @var (array|UploadedFile)[] $_FILES data or UploadedFile instances */ private $files; /** @var array[] Any recorded conditions */ private $conditions = []; /** * @param (string|string[])[] $params Data from $_POST + $_GET * @param array[] $files Data from $_FILES */ public function __construct( array $params, array $files = [] ) { $this->params = $params; $this->files = $files; } public function hasParam( $name, array $options ) { return isset( $this->params[$name] ); } public function getValue( $name, $default, array $options ) { return $this->params[$name] ?? $default; } public function hasUpload( $name, array $options ) { return isset( $this->files[$name] ); } public function getUploadedFile( $name, array $options ) { $file = $this->files[$name] ?? null; if ( $file && !$file instanceof UploadedFile ) { $file = new UploadedFile( $file ); $this->files[$name] = $file; } // @phan-suppress-next-line PhanTypeMismatchReturnNullable False positive return $file; } public function recordCondition( DataMessageValue $message, $name, $value, array $settings, array $options ) { $this->conditions[] = [ 'message' => $message, 'name' => $name, 'value' => $value, 'settings' => $settings, ]; } /** * Fetch any recorded conditions * @return array[] */ public function getRecordedConditions() { return $this->conditions; } /** * Clear any recorded conditions */ public function clearRecordedConditions() { $this->conditions = []; } public function useHighLimits( array $options ) { return !empty( $options['useHighLimits'] ); } } PK ! G��a�( �( ParamValidator/i18n/mk.jsonnu �Iw�� { "@metadata": { "authors": [ "Bjankuloski06" ] }, "paramvalidator-badbool": "Неважечка вредност „$2“ за Буловиот параметар „$1“. Задајте $3 за точно или $5 за неточно.", "paramvalidator-badbool-type": "Неважечка вредност „$2“ за Буловиот параметар „$1“. Наместо тоа, ја добив вредноста $3.", "paramvalidator-badexpiry": "Неважечка вредност „$2“ за параметарот за истек \"$1\".", "paramvalidator-badexpiry-duration": "Дадената вредност „$2“ за параметарот <var>$1</var> го надминува дозволеното од „$3“.", "paramvalidator-badexpiry-duration-max": "Дадената вредност „$2“ за параметарот <var>$1</var> го надминува дозволеното од „$3“. Ќе ја применам највисоката дозволена вредност.", "paramvalidator-badexpiry-past": "Вредноста „$2“ за параметарот за истек „$1“ е во минатото.", "paramvalidator-badfloat": "Неважечка вредност „$2“ за децималниот параметар \"$1\".", "paramvalidator-badfloat-type": "Неважечка вредност „$2“ за подвижниот параметар „$1“. Наместо тоа, ја добив вредноста $3.", "paramvalidator-badfloat-notfinite": "Вредноста „$2“ за децималниот параметар „$1“ е преголема или не е број.", "paramvalidator-badinteger": "Неважечка вредност „$2“ за целобројниот параметар „$1“.", "paramvalidator-badinteger-type": "Неважечка вредност „$2“ за целобројниот параметар „$1“. Наместо тоа, ја добив вредноста $3.", "paramvalidator-badinteger-fraction": "Неважечка вредност „$2“ за целобројниот параметар „$1“. Наместо тоа, добив дробна вредност.", "paramvalidator-badtimestamp": "Неважечка вредност „$2“ временскиот параметар „$1“.", "paramvalidator-badupload-cantwrite": "Податотеката за „$1“ не може да се складира за обработка поради погрешна поставеност на опслужувачот (запишувањето не успеа).", "paramvalidator-badupload-formsize": "Подигнатата податотека за „$1“ ја надминува границата зададена од клиентот.", "paramvalidator-badupload-inisize": "Подигнатата податотека за „$1“ ја надминува границата ос $3 зададена од опслужувачот.", "paramvalidator-badupload-nofile": "Нема укажано податотека за подигачкиот параметар „$1“.", "paramvalidator-badupload-notmpdir": "Податотеката за „$1“ не можеше да се складира за обработка поради погрешна поставеност на опслужувачот (нема привремена папка).", "paramvalidator-badupload-notupload": "Параметарот за подигање „$1“ не е податотечно подигање; ќе мора да користите податоци од повеќеделно/образец за вашиот POST и да вклучите податотечно име во заглавието Content-Disposition.", "paramvalidator-badupload-partial": "Податотеката за „$1“ е само делумно подигната.", "paramvalidator-badupload-phpext": "PHP-додаток го спречи подигањето на податотеката за „$1“.", "paramvalidator-badvalue-enummulti": "Неважечка вредност „$2“ за параметарот „$1“. {{PLURAL:$4|Се допушта само „$3“.|Допуштени вредности се $3.}}", "paramvalidator-badvalue-enumnotmulti": "Непрепознаена вредност за параметарот „$1“: $2.", "paramvalidator-deprecated-value": "Вредноста „$2“ за параметарот „$1“ е застарена.", "paramvalidator-emptystring": "празната низа", "paramvalidator-maxbytes": "Вредноста за параметарот „$1“ не може да биде поголема од $3 {{PLURAL:$3|бајт|бајти}} (беше $4).", "paramvalidator-maxchars": "Вредноста за параметарот „$1“ не може да биде подолга од $3 {{PLURAL:$3|знак|знаци}} (беше $4).", "paramvalidator-missingparam": "Параметарот „$1“ мора да биде зададен.", "paramvalidator-notmulti": "Параметарот „$1“ прифаќа само една вредност. Одделувањето на повќе вредности од U+001F се користи само за повеќевредносни параметри.", "paramvalidator-multivalue-must-be-array": "Мора да се укаже повеќевредносниот параметар „$1“ како низа.", "paramvalidator-needstring": "Параметарот „$1“ прифаќа само низна вредност, но доби $2", "paramvalidator-outofrange-max": "Вредноста „$2“ за параметарот „$1“ не може да е поголема од $4.", "paramvalidator-outofrange-minmax": "Вредноста „$2“ за параметарот „$1“ мора да изнесува помеѓу $3 и $4.", "paramvalidator-outofrange-min": "Вредноста „$2“ за параметарот „$1“ не може да биде помала од $3.", "paramvalidator-param-deprecated": "Параметарот „$1“ е застарен.", "paramvalidator-toomanyvalues": "На параметарот „$1“ му се зададени премногу вредности. Се допушта највеќе $2.", "paramvalidator-unclearnowtimestamp": "Задавањето на „$2“ за временскиот параметар „$1“ е застарено. Доколку морате да внесете тековно време без да го пресметувате од клиентска страна, употребете го „now“.", "paramvalidator-unrecognizedvalues": "{{PLURAL:$4|Непрепознаена вредност|Непрепознаени вредности}} за параметарот „$1“: $3", "paramvalidator-help-default": "По основно: $1", "paramvalidator-help-default-empty": "По основно: (празно)", "paramvalidator-help-deprecated": "Овој параметар е застарен.", "paramvalidator-help-multi-separate": "Одделувајте ги вредностие со „|“, или на списокот ставете му претставка U+001F и одделувајте со U+001F.", "paramvalidator-help-multi-max": "Дозволени се највеќе {{PLURAL:$1|$1}} вредности ({{PLURAL:$2|$2}} за клиенти со повеќе следување).", "paramvalidator-help-multi-max-simple": "Дозволени се највеќе {{PLURAL:$1|$1}} вредности.", "paramvalidator-help-multi-all": "За да ги укажете сите вредности, користете <kbd>$1</kbd>.", "paramvalidator-help-required": "Овој параметар е задолжителен.", "paramvalidator-help-type-boolean": "Вид: {{PLURAL:$1|1=Булов|2=список на Булови}}", "paramvalidator-help-type-enum-can-be-empty": "{{PLURAL:$2|0=Мора да биде празно|Може да биде празно или $1}}", "paramvalidator-help-type-enum": "{{PLURAL:$1|1=Една од следниве вредности|2=Вредности (одделени со U+007C (права црта), или ставете претставка U+001F пред списокот и одделете со U+001F)}}: $2", "paramvalidator-help-type-expiry": "Вид: {{PLURAL:$1|1=истек|2=список на истеци}}.\n\nМоже да биде релативно (на пр. <kbd>5 месеци</kbd> или <kbd>2 недели</kbd>) или пак апсолутно (на пр. <kbd>2014-09-18T12:34:56Z</kbd>). За да нема истек, употребете $2.", "paramvalidator-help-type-float": "Вид: {{PLURAL:$1|1=децимален број|2=список на децимални броеви}}", "paramvalidator-help-type-integer": "Вид: {{PLURAL:$1|1=цел број|2=список на цели броеви}}", "paramvalidator-help-type-limit": "Вид: цел број или „max“", "paramvalidator-help-type-number-max": "{{PLURAL:$1|1=Вредноста не може да изнесува|2=Вредностите не може да изнесуваат}} повеќе од $3.", "paramvalidator-help-type-number-minmax": "{{PLURAL:$1|1=Вредноста мора да изнесува|2=Вредностите мораат да изнесуваат}} помеѓу $2 и $3.", "paramvalidator-help-type-number-min": "{{PLURAL:$1|1=Вредноста не може да изнесува|2=Вредностите не може да изнесуваат}} помалку од $2.", "paramvalidator-help-type-presenceboolean": "Вид: Булов", "paramvalidator-help-type-string-maxbytes": "Не може да биде поголемо од $1 {{PLURAL:$1|бајт|бајти}}.", "paramvalidator-help-type-string-maxchars": "Не може да биде поголемо од $1 {{PLURAL:$1|знак|знаци}}.", "paramvalidator-help-type-timestamp": "Вид: {{PLURAL:$1|1=временска ознака|2=список на временски ознаки}}", "paramvalidator-help-type-upload": "Мора да биде објавено како податотечно подигање користејќи податоци кои се повеќеделни или од образец." } PK ! .��1�& �& ParamValidator/i18n/uk.jsonnu �Iw�� { "@metadata": { "authors": [ "Movses", "Piramidion", "Ата" ] }, "paramvalidator-badbool": "Недійсне значення «$2» для параметра «$1», який вимагає логічного типу даних. Вкажіть $3 для підтвердження («true»), або $5 для заперечення («false»).", "paramvalidator-badexpiry": "Недійсне значення «$2» параметра «$1», що втратив актуальність.", "paramvalidator-badexpiry-duration": "Подане значення «$2» параметра <var>$1</var> перевищує максимальне значення «$3».", "paramvalidator-badexpiry-duration-max": "Подане значення «$2» параметра <var>$1</var> перевищує максимальне значення «$3». Використано максимальне значення.", "paramvalidator-badexpiry-past": "Значення «$2» для параметра втрати актуальності «$1» перебуває в минулому.", "paramvalidator-badfloat": "Недійсне значення «$2» для параметра «$1», який вимагає числа з рухомою комою.", "paramvalidator-badfloat-notfinite": "Значення «$2» для параметра «$1», який вимагає числа з рухомою комою, є надто великим, або не є числом.", "paramvalidator-badinteger": "Недійсне значення «$2» для параметра «$1», який вимагає цілого числа.", "paramvalidator-badtimestamp": "Недійсне значення «$2» для параметра «$1», який вимагає мітки часу.", "paramvalidator-badupload-cantwrite": "Файл для параметра «$1» не вдалося зберегти для опрацювання через неправильну конфігурацію сервера (запис зазнав невдачі).", "paramvalidator-badupload-formsize": "Завантажений файл для параметра «$1» перевищує встановлений клієнтом максимум.", "paramvalidator-badupload-inisize": "Завантажений файл для параметра «$1» перевищує встановлений сервером максимум у $3.", "paramvalidator-badupload-nofile": "Не вказано жодного файлу для параметра завантаження «$1».", "paramvalidator-badupload-notmpdir": "Файл для параметра «$1» не вдалося зберегти для опрацювання через неправильну конфігурацію сервера (відсутній тимчасовий каталог).", "paramvalidator-badupload-notupload": "Параметр завантаження файлу «$1» не є завантаженням файлу; не забудьте використати multipart/form-data для вашого POST, і додайте назву файлу в заголовок Content-Disposition.", "paramvalidator-badupload-partial": "Файл для параметра «$1» було завантажено лише частково.", "paramvalidator-badupload-phpext": "PHP-розширення запобігло завантаженню файлу для параметра «$1».", "paramvalidator-badvalue-enummulti": "Недійсне значення «$2» для параметра «$1». {{PLURAL:$4|Дозволено лише значення «$3».|Дозволені значення: $3.}}", "paramvalidator-badvalue-enumnotmulti": "Нерозпізнане значення для параметра «$1»: $2.", "paramvalidator-deprecated-value": "Значення «$2» для параметра «$1» було визнано застарілим.", "paramvalidator-emptystring": "порожній рядок", "paramvalidator-maxbytes": "Значення параметра «$1» не може бути довшим, ніж $3 {{PLURAL:$3|байт|байти|байтів}} (було $4).", "paramvalidator-maxchars": "Значення параметра «$1» не може бути довшим, ніж $3 {{PLURAL:$3|символ|символи|символів}} (було $4).", "paramvalidator-missingparam": "Має бути встановлено параметр «$1».", "paramvalidator-notmulti": "Параметр «$1» приймає лише одне значення. Роздільник U+001F для вказування багатьох значень можна використовувати лише в тих параметрах, які допускають декілька значень водночас.", "paramvalidator-outofrange-max": "Значення «$2» параметра «$1» має бути не більшим, ніж $4.", "paramvalidator-outofrange-minmax": "Значення «$2» параметра «$1» має перебувати між $3 та $4.", "paramvalidator-outofrange-min": "Значення «$2» параметра «$1» має бути не меншим, ніж $3.", "paramvalidator-param-deprecated": "Параметр «$1» було визнано застарілим.", "paramvalidator-toomanyvalues": "Вказано надто багато значень для параметра «$1». Ліміт становить $2.", "paramvalidator-unclearnowtimestamp": "Вказування значення «$2» для параметра «$1», який вимагає мітки часу, було визнано застарілим. Якщо з якоїсь причини вам необхідно чітко вказати саме поточний час без вираховування його з боку клієнта, використайте значення «now».", "paramvalidator-unrecognizedvalues": "{{PLURAL:$4|Нерозпізнане значення|Нерозпізнані значення}} для параметра «$1»: $3", "paramvalidator-help-default": "Стандартно: $1", "paramvalidator-help-default-empty": "Стандартно: (порожнє)", "paramvalidator-help-deprecated": "Цей параметр є застарілим.", "paramvalidator-help-multi-separate": "Відокремлюйте значення за допомогою «|», або додавайте до списку префікс U+001F та використовуйте U+001F як роздільник.", "paramvalidator-help-multi-max": "Максимальна кількість значень — {{PLURAL:$1|$1}} ({{PLURAL:$2|$2}} для клієнтів, яким дозволено вищі ліміти).", "paramvalidator-help-multi-max-simple": "Максимальна кількість значень — {{PLURAL:$1|$1}}.", "paramvalidator-help-multi-all": "Щоб зазначити всі значення, використовуйте <kbd>$1</kbd>.", "paramvalidator-help-required": "Цей параметр є обов'язковим.", "paramvalidator-help-type-boolean": "Тип: {{PLURAL:$1|1=логічне значення|2=список логічних значень}}", "paramvalidator-help-type-enum-can-be-empty": "{{PLURAL:$2|0=Має бути порожнім|Може бути порожнім, або $1}}", "paramvalidator-help-type-enum": "{{PLURAL:$1|1=Одне із вказаних значень|2=Значення (відокремлюйте за допомогою U+007C (вертикальна риска), чи додавайте перед списком префікс U+001F та використовуйте U+001F як роздільник)}}: $2", "paramvalidator-help-type-expiry": "Тип: {{PLURAL:$1|1=втрата актуальності|2=список втрат актуальності}}.\n\nМоже бути відносним (напр. <kbd>5 months</kbd> або <kbd>2 weeks</kbd>) чи абсолютним (напр. <kbd>2014-09-18T12:34:56Z</kbd>). Якщо зазначення втрати актуальності не потрібне — використовуйте $2.", "paramvalidator-help-type-float": "Тип: {{PLURAL:$1|1=число з рухомою комою|2=список чисел з рухомою комою}}", "paramvalidator-help-type-integer": "Тип: {{PLURAL:$1|1=ціле число|2=список цілих чисел}}", "paramvalidator-help-type-limit": "Тип: ціле число або «max»", "paramvalidator-help-type-number-max": "{{PLURAL:$1|1=Значення має бути не більшим|2=Значення мають бути не більшими}}, ніж $3.", "paramvalidator-help-type-number-minmax": "{{PLURAL:$1|1=Значення має|2=Значення мають}} перебувати між $2 та $3.", "paramvalidator-help-type-number-min": "{{PLURAL:$1|1=Значення має бути не меншим|2=Значення мають бути не меншими}}, ніж $2.", "paramvalidator-help-type-presenceboolean": "Тип: логічне значення", "paramvalidator-help-type-string-maxbytes": "Не може бути довшим, ніж $1 {{PLURAL:$1|байт|байти|байтів}}.", "paramvalidator-help-type-string-maxchars": "Не може бути довшим, ніж $1 {{PLURAL:$1|символ|символи|символів}}.", "paramvalidator-help-type-timestamp": "Тип: {{PLURAL:$1|1=мітка часу|2=список міток часу}}", "paramvalidator-help-type-upload": "Повинно бути надіслано у формі надсилання файлу використовуючи multipart/form-data." } PK ! �z��� � ParamValidator/i18n/ia.jsonnu �Iw�� { "@metadata": { "authors": [ "McDutchie" ] }, "paramvalidator-badbool": "Valor \"$2\" non valide pro le parametro boolean \"$1\". Passa $3 pro ver o $5 pro false.", "paramvalidator-badbool-type": "Le valor “$2” del parametro boolean “$1” non es valide. Le valor obtenite es $3.", "paramvalidator-badexpiry": "Valor \"$2\" non valide pro le parametro de expiration \"$1\".", "paramvalidator-badexpiry-duration": "Le valor \"$2\" date pro le parametro <var>$1</var> excede le maximo de \"$3\".", "paramvalidator-badexpiry-duration-max": "Le valor \"$2\" date pro le parametro <var>$1</var> excede le maximo de \"$3\". Le maximo essera usate in su loco.", "paramvalidator-badexpiry-past": "Le valor \"$2\" date pro le parametro de expiration \"$1\" es in le passato.", "paramvalidator-badfloat": "Valor \"$2\" non valide pro le parametro de virgula flottante \"$1\".", "paramvalidator-badfloat-type": "Le valor “$2” del parametro a virgula flottante “$1” non es valide. Le valor obtenite es $3.", "paramvalidator-badfloat-notfinite": "Le valor \"$2\" pro le parametro de virgula flottante \"$1\" es troppo grande o non es un numero.", "paramvalidator-badinteger": "Valor \"$2\" non valide pro le parametro de numero integre \"$1\".", "paramvalidator-badinteger-type": "Le valor “$2” del parametro de numero integre “$1” non es valide. Le valor obtenite es $3.", "paramvalidator-badinteger-fraction": "Le valor “$2” del parametro de numero integre “$1” non es valide. Le valor obtenite es un numero a virgula flottante con un parte fractional.", "paramvalidator-badtimestamp": "Valor \"$2\" non valide pro le parametro de data e hora \"$1\".", "paramvalidator-badupload-cantwrite": "Le file pro \"$1\" non poteva esser immagazinate pro esser processate a causa de un mal configuration del servitor (scriptura fallite).", "paramvalidator-badupload-formsize": "Le file incargate pro \"$1\" excede le maximo specificate per le cliente.", "paramvalidator-badupload-inisize": "Le file incargate pro \"$1\" excede le maximo $3 del servitor.", "paramvalidator-badupload-nofile": "Necun file ha essite fornite pro le parametro de incargamento \"$1\".", "paramvalidator-badupload-notmpdir": "Le file pro \"$1\" non poteva esser immagazinate pro esser processate a causa de un mal configuration del servitor (necun directorio temporari).", "paramvalidator-badupload-notupload": "Le parametro de incargamento de file <var>$1</var> non es un incargamento de file; assecura te de usar <code>multipart/form-data</code> pro tu invio POST e include un nomine de file in le capite <code>Content-Disposition</code>.", "paramvalidator-badupload-partial": "Le file pro \"$1\" ha essite incargate solo partialmente.", "paramvalidator-badupload-phpext": "Un extension de PHP ha impedite le incargamento del file pro \"$1\".", "paramvalidator-badvalue-enummulti": "Valor non valide \"$2\" pro le parametro \"$1\". {{PLURAL:$4|Solmente \"$3\" es permittite.|Le valores permittite es $3.}}", "paramvalidator-badvalue-enumnotmulti": "Valor non recognoscite pro le parametro \"$1\": $2.", "paramvalidator-deprecated-value": "Le valor \"$2\" del parametro \"$1\" ha essite declarate obsolescente.", "paramvalidator-emptystring": "le catena vacue", "paramvalidator-maxbytes": "Le valor del parametro \"$1\" non pote haber plus de $3 byte{{PLURAL:$3||s}} (ha $4).", "paramvalidator-maxchars": "Le valor del parametro \"$1\" non pote haber plus de $3 character{{PLURAL:$3||es}} (ha $4).", "paramvalidator-missingparam": "Le parametro \"$1\" debe esser definite.", "paramvalidator-notmulti": "Le parametro \"$1\" accepta solmente un valor. Le separation de valores multiple U+001F pote solmente esser usate pro parametros con multiple valores.", "paramvalidator-multivalue-must-be-array": "Le parametro multi-valor “$1” debe esser date como matrice.", "paramvalidator-needstring": "Le parametro “$1” accepta solmente un valor de catena de characteres, ma ha recipite $2", "paramvalidator-outofrange-max": "Le valor \"$2\" del parametro \"$1\" non debe esser superior a $4.", "paramvalidator-outofrange-minmax": "Le valor \"$2\" del parametro \"$1\" debe esser inter $3 e $4.", "paramvalidator-outofrange-min": "Le valor \"$2\" del parametro \"$1\" non debe esser inferior a $3.", "paramvalidator-param-deprecated": "Le parametro \"$1\" ha essite declarate obsolescente.", "paramvalidator-toomanyvalues": "Troppo de valores fornite pro le parametro \"$1\". Le limite es $2.", "paramvalidator-unclearnowtimestamp": "Passar \"$2\" pro le parametro de data e hora \"$1\" es obsolescente. Si tu ha un necessitate de specificar explicitemente le hora currente sin calcular lo al latere del cliente, usa \"now\" (ora).", "paramvalidator-unrecognizedvalues": "Valor{{PLURAL:$4||es}} non recognoscite pro le parametro \"$1\": $3", "paramvalidator-help-default": "Predefinite: $1", "paramvalidator-help-default-empty": "Predefinite: (vacue)", "paramvalidator-help-deprecated": "Iste parametro es obsolescente.", "paramvalidator-help-multi-separate": "Separa valores con \"|\", o prefixa le lista con U+001F e separa lo con U+001F.", "paramvalidator-help-multi-max": "Le numero maxime de valores es {{PLURAL:$1|$1}} ({{PLURAL:$2|$2}} pro clientes al quales ha essite permittite limites plus alte).", "paramvalidator-help-multi-max-simple": "Le numero maxime de valores es {{PLURAL:$1|$1}}.", "paramvalidator-help-multi-all": "Pro specificar tote le valores, usa <kbd>$1</kbd>.", "paramvalidator-help-required": "Iste parametro es obligatori.", "paramvalidator-help-type-boolean": "Typo: {{PLURAL:$1|1=booleano|2=lista de booleanos}}", "paramvalidator-help-type-enum-can-be-empty": "{{PLURAL:$2|0=Debe esser vacue|Pote esser vacue, o $1}}", "paramvalidator-help-type-enum": "{{PLURAL:$1|1=Un del sequente valores|2=Valores (separar con U+007C (barra vertical), o prefixar le lista con U+001F e separar con U+001F)}}: $2", "paramvalidator-help-type-expiry": "Typo: {{PLURAL:$1|1=expiration|2=lista de expirationes}}.\n\nPote esser relative (p.ex. <kbd>5 months</kbd> (5 menses) o <kbd>2 weeks</kbd> (2 septimanas)) o absolute (p.ex. <kbd>2014-09-18T12:34:56Z</kbd>). Pro non haber alcun expiration, usa $2.", "paramvalidator-help-type-float": "Typo: {{PLURAL:$1|1=numero a virgula flottante|2=lista de numeros a virgula flottante}}", "paramvalidator-help-type-integer": "Typo: {{PLURAL:$1|1=numero integre|2=lista de numeros integre}}", "paramvalidator-help-type-limit": "Typo: numero integre o \"max\"", "paramvalidator-help-type-number-max": "Le {{PLURAL:$1|1=valor|2=valores}} non debe esser plus grande que $3.", "paramvalidator-help-type-number-minmax": "Le {{PLURAL:$1|1=valor|2=valores}} debe esser inter $2 e $3.", "paramvalidator-help-type-number-min": "Le {{PLURAL:$1|1=valor|2=valores}} non debe esser minus de $2.", "paramvalidator-help-type-presenceboolean": "Typo: booleano", "paramvalidator-help-type-string-maxbytes": "Non pote esser plus longe que $1 {{PLURAL:$1|byte|bytes}}.", "paramvalidator-help-type-string-maxchars": "Non pote esser plus longe que $1 character{{PLURAL:$1||es}}.", "paramvalidator-help-type-timestamp": "Typo: {{PLURAL:$1|1=data e hora|2=lista de datas e horas}}", "paramvalidator-help-type-upload": "Debe esser inviate como un incargamento de file usante multipart/form-data." } PK ! {��� � ParamValidator/i18n/ja.jsonnu �Iw�� { "@metadata": { "authors": [ "Kkairri", "Omotecho" ] }, "paramvalidator-badbool": "ブール変数\"$1\"に対する値\"$2\"が正しくありません。$3を真に、もしくは$5を偽にしてください。", "paramvalidator-badexpiry": "有効期限属性「$1」に対する「$2」が無効です。", "paramvalidator-badexpiry-duration": "変数 <var>$1</var> に対する値「$2」は上限「$3」を超えています。", "paramvalidator-badexpiry-duration-max": "<var>$1</var> 属性に対する値「$2」は上限値「$3」を超えています。代わりに最大値を使います。", "paramvalidator-badexpiry-past": "有効期限変数「$1」に対する値「$2」を過ぎています。", "paramvalidator-badfloat": "浮動パラメータ「$2」に対する値「$1」が無効です。", "paramvalidator-badfloat-notfinite": "浮動変数「$1」に対する値「$2」は大きすぎるまたは数値ではありません。", "paramvalidator-badinteger": "整数変数「$1」に対する値「$2」は無効です。", "paramvalidator-badtimestamp": "タイムスタンプ属性「$1」に対する値「$2」は無効です。", "paramvalidator-badupload-cantwrite": "「$1」に対するファイルはサーバの設定不良 (書きこみの失敗) により保存と処理ができません。", "paramvalidator-badupload-formsize": "The uploaded file for 「$1」に対してアップロードしたファイルはクライアントの設定した上限を超過しています。", "paramvalidator-badupload-inisize": "アップロードしたファイル「$1」はサーバ上限$3を超えています。", "paramvalidator-badupload-nofile": "アップロード変数「$1」に対応するファイルはありません。", "paramvalidator-badupload-notmpdir": "「$1」に対するファイルはサーバの設定不良 (書きこみの失敗) により保存と処理ができません。", "paramvalidator-badupload-notupload": "ファイルアップロード変数「$1」はファイルアップロードではありません。POST にはマルチパートもしくはフォームデータを使い、Content-Disposition ヘッダにファイル名を記述してください。", "paramvalidator-badupload-partial": "「$1」に対するファイルのアップロードは途中までしか終わっていません。", "paramvalidator-badupload-phpext": "PHP 拡張機能が「$1」に対するファイルのアップロードを防止しました。", "paramvalidator-badvalue-enummulti": "変数「$1」に対する値「$2」は無効です。{{PLURAL:$4|「$3」のみ有効です。|$3のみ有効です。}}", "paramvalidator-badvalue-enumnotmulti": "パラメータ「$1」に対する値「$2」は未承認です。", "paramvalidator-deprecated-value": "変数「$1」に対する値「$2」は廃止されました。", "paramvalidator-emptystring": "空の文字列", "paramvalidator-maxbytes": "変数「$1」に対する値の上限は「$3」{{PLURAL:$3||バイト|バイト}}です（入力値は$4）。", "paramvalidator-maxchars": "パラメータ「$1」に対する値の上限は「$3」{{PLURAL:$3||文字|文字}}です（入力値は$4）。", "paramvalidator-missingparam": "変数「$1」が未設定です。", "paramvalidator-notmulti": "変数「$1」は数値を1件しか受け付けません。U+0001F 複数値の区切り子は複数値の変数にしか使えません。", "paramvalidator-outofrange-max": "パラメータ「$1」に対する値「$2」の上限は「$4」です。", "paramvalidator-outofrange-minmax": "変数「$1」に対する値「$2」は「$3」以上「$4」未満です。", "paramvalidator-outofrange-min": "パラメータ「$1」に対する値「$2」の下限は「$3」です。", "paramvalidator-param-deprecated": "変数「$1」は廃止されました。", "paramvalidator-toomanyvalues": "変数「$1」に対する値が多すぎます。上限は$2です。", "paramvalidator-unclearnowtimestamp": "タイムスタンプ属性「$1」に対してあてる「$2」は廃止されました。何かの理由でクライアント側で計算せずに現在時間を設定する必要がある場合は、「now」を使用します。", "paramvalidator-unrecognizedvalues": "変数「$1」に対する未知の{{PLURAL:$4|値|値}}です: $3", "paramvalidator-help-default": "既定: $1", "paramvalidator-help-default-empty": "既定: (空)", "paramvalidator-help-deprecated": "この変数は廃止されました。", "paramvalidator-help-multi-separate": "数値の区切り子は「|」を使用するか、もしくは一覧の接頭辞として U+001F を記述し、U+001F で区切ります。", "paramvalidator-help-multi-max": "値の最大値は {{PLURAL:$1|$1}}（緩い制限が適用されるクライアントでは{{PLURAL:$2|$2}}）です。", "paramvalidator-help-multi-max-simple": "値の最大値は {{PLURAL:$1|$1}} です。", "paramvalidator-help-multi-all": "すべての値を指定するには、<kbd>$1</kbd>を用いてください。", "paramvalidator-help-required": "この変数は必須です。", "paramvalidator-help-type-boolean": "型: {{PLURAL:$1|1=真偽値|2=真偽値のリスト}}", "paramvalidator-help-type-enum-can-be-empty": "{{PLURAL:$2|0=必ず空|空もしくは$1を使用}}", "paramvalidator-help-type-enum": "{{PLURAL:$1|1=次の値のいずれか|2=複数の値(U+007C (パイプ記号)で区切るもしくは一覧の接頭辞に U+001F を記述し U+001F で区切る)}}: $2", "paramvalidator-help-type-expiry": "種別: {{PLURAL:$1|1=有効期限|2=有効期限の一覧}}。\n\nおそらく相対値 (例 <kbd>5ヵ月</kbd> または <kbd>2週間</kbd>) あるいは絶対値 (例<kbd>2014-09-18T12:34:56Z</kbd>)。有効期限がない場合は、$2を使います。", "paramvalidator-help-type-float": "種別: {{PLURAL:$1|1=浮動値|2=浮動値の一覧}}", "paramvalidator-help-type-integer": "型: {{PLURAL:$1|1=整数|2=整数のリスト}}", "paramvalidator-help-type-limit": "型: 整数 または \"max\"", "paramvalidator-help-type-number-max": "{{PLURAL:$1|1=値|2=複数の値}}の上限は必ず$3以下です。", "paramvalidator-help-type-number-minmax": "{{PLURAL:$1|1=値|2=複数の値}}は$2以上$3以下です。", "paramvalidator-help-type-number-min": "{{PLURAL:$1|1=値|2=複数の値}}の下限は必ず$2以上です。", "paramvalidator-help-type-presenceboolean": "型: 真偽値", "paramvalidator-help-type-string-maxbytes": "$1 {{PLURAL:$1|byte|バイト}}より長くすることはできません。", "paramvalidator-help-type-string-maxchars": "$1を超える{{PLURAL:$1|character|文字数}}は無効です。", "paramvalidator-help-type-timestamp": "種別: {{PLURAL:$1|1=ライムスタンプ|2=ライムスタンプの一覧}}", "paramvalidator-help-type-upload": "ファイルアップロードには multipart/form-data を使って投稿してください。" } PK ! F��) ) ParamValidator/i18n/en.jsonnu �Iw�� { "@metadata": { "authors": [ "Anomie", "MusikAnimal", "Siebrand", "Zoranzoki21" ] }, "paramvalidator-badbool": "Invalid value \"$2\" for boolean parameter \"$1\". Pass $3 for true, or $5 for false.", "paramvalidator-badbool-type": "Invalid value \"$2\" for boolean parameter \"$1\". Got a $3 value instead.", "paramvalidator-badexpiry": "Invalid value \"$2\" for expiry parameter \"$1\".", "paramvalidator-badexpiry-duration": "Given value \"$2\" for parameter <var>$1</var> exceeds the maximum of \"$3\".", "paramvalidator-badexpiry-duration-max": "Given value \"$2\" for parameter <var>$1</var> exceeds the maximum of \"$3\". Using maximum instead.", "paramvalidator-badexpiry-past": "Value \"$2\" for expiry parameter \"$1\" is in the past.", "paramvalidator-badfloat": "Invalid value \"$2\" for float parameter \"$1\".", "paramvalidator-badfloat-type": "Invalid value \"$2\" for float parameter \"$1\". Got a $3 value instead.", "paramvalidator-badfloat-notfinite": "Value \"$2\" for float parameter \"$1\" is too large or is not a number.", "paramvalidator-badinteger": "Invalid value \"$2\" for integer parameter \"$1\".", "paramvalidator-badinteger-type": "Invalid value \"$2\" for integer parameter \"$1\". Got a $3 value instead.", "paramvalidator-badinteger-fraction": "Invalid value \"$2\" for integer parameter \"$1\". Got a float with a fractional part instead.", "paramvalidator-badtimestamp": "Invalid value \"$2\" for timestamp parameter \"$1\".", "paramvalidator-badupload-cantwrite": "The file for \"$1\" could not be stored for processing due to a server misconfiguration (write failed).", "paramvalidator-badupload-formsize": "The uploaded file for \"$1\" exceeds the client-specified maximum.", "paramvalidator-badupload-inisize": "The uploaded file for \"$1\" exceeds the server's maximum of $3.", "paramvalidator-badupload-nofile": "No file was provided for upload parameter \"$1\".", "paramvalidator-badupload-notmpdir": "The file for \"$1\" could not be stored for processing due to a server misconfiguration (no temporary directory).", "paramvalidator-badupload-notupload": "File upload parameter \"$1\" is not a file upload; be sure to use multipart/form-data for your POST and include a filename in the Content-Disposition header.", "paramvalidator-badupload-partial": "The file for \"$1\" was only partially uploaded.", "paramvalidator-badupload-phpext": "A PHP extension prevented the upload of the file for \"$1\".", "paramvalidator-badvalue-enummulti": "Invalid value \"$2\" for parameter \"$1\". {{PLURAL:$4|Only \"$3\" is allowed.|Allowed values are $3.}}", "paramvalidator-badvalue-enumnotmulti": "Unrecognized value for parameter \"$1\": $2.", "paramvalidator-deprecated-value": "The value \"$2\" to parameter \"$1\" has been deprecated.", "paramvalidator-emptystring": "the empty string", "paramvalidator-maxbytes": "The value for parameter \"$1\" cannot be longer than $3 {{PLURAL:$3|byte|bytes}} (was $4).", "paramvalidator-maxchars": "The value for parameter \"$1\" cannot be longer than $3 {{PLURAL:$3|character|characters}} (was $4).", "paramvalidator-missingparam": "The \"$1\" parameter must be set.", "paramvalidator-notmulti": "Parameter \"$1\" accepts only a single value. U+001F multi-value separation may only be used for multi-valued parameters.", "paramvalidator-multivalue-must-be-array": "Multi-value parameter \"$1\" must be given as an array.", "paramvalidator-needstring": "Parameter \"$1\" accepts only a string value, but got $2", "paramvalidator-outofrange-max": "The value \"$2\" for parameter \"$1\" must be no greater than $4.", "paramvalidator-outofrange-minmax": "The value \"$2\" for parameter \"$1\" must be between $3 and $4.", "paramvalidator-outofrange-min": "The value \"$2\" for parameter \"$1\" must be no less than $3.", "paramvalidator-param-deprecated": "The parameter \"$1\" has been deprecated.", "paramvalidator-param-sensitive": "", "paramvalidator-toomanyvalues": "Too many values supplied for parameter \"$1\". The limit is $2.", "paramvalidator-unclearnowtimestamp": "Passing \"$2\" for timestamp parameter \"$1\" has been deprecated. If for some reason you need to explicitly specify the current time without calculating it client-side, use \"now\".", "paramvalidator-unrecognizedvalues": "Unrecognized {{PLURAL:$4|value|values}} for parameter \"$1\": $3", "paramvalidator-help-default": "Default: $1", "paramvalidator-help-default-empty": "Default: (empty)", "paramvalidator-help-deprecated": "This parameter is deprecated.", "paramvalidator-help-multi-separate": "Separate values with \"|\", or prefix the list with U+001F and separate with U+001F.", "paramvalidator-help-multi-max": "Maximum number of values is {{PLURAL:$1|$1}} ({{PLURAL:$2|$2}} for clients that are allowed higher limits).", "paramvalidator-help-multi-max-simple": "Maximum number of values is {{PLURAL:$1|$1}}.", "paramvalidator-help-multi-all": "To specify all values, use <kbd>$1</kbd>.", "paramvalidator-help-required": "This parameter is required.", "paramvalidator-help-type-boolean": "Type: {{PLURAL:$1|1=boolean|2=list of booleans}}", "paramvalidator-help-type-enum-can-be-empty": "{{PLURAL:$2|0=Must be empty|Can be empty, or $1}}", "paramvalidator-help-type-enum": "{{PLURAL:$1|1=One of the following values|2=Values (separate with U+007C (pipe), or prefix the list with U+001F and separate with U+001F)}}: $2", "paramvalidator-help-type-expiry": "Type: {{PLURAL:$1|1=expiry|2=list of expiries}}.\n\nMay be relative (e.g. <kbd>5 months</kbd> or <kbd>2 weeks</kbd>) or absolute (e.g. <kbd>2014-09-18T12:34:56Z</kbd>). For no expiry, use $2.", "paramvalidator-help-type-float": "Type: {{PLURAL:$1|1=float|2=list of floats}}", "paramvalidator-help-type-integer": "Type: {{PLURAL:$1|1=integer|2=list of integers}}", "paramvalidator-help-type-limit": "Type: integer or \"max\"", "paramvalidator-help-type-number-max": "The {{PLURAL:$1|1=value|2=values}} must be no greater than $3.", "paramvalidator-help-type-number-minmax": "The {{PLURAL:$1|1=value|2=values}} must be between $2 and $3.", "paramvalidator-help-type-number-min": "The {{PLURAL:$1|1=value|2=values}} must be no less than $2.", "paramvalidator-help-type-presenceboolean": "Type: boolean", "paramvalidator-help-type-string-maxbytes": "Cannot be longer than $1 {{PLURAL:$1|byte|bytes}}.", "paramvalidator-help-type-string-maxchars": "Cannot be longer than $1 {{PLURAL:$1|character|characters}}.", "paramvalidator-help-type-timestamp": "Type: {{PLURAL:$1|1=timestamp|2=list of timestamps}}", "paramvalidator-help-type-upload": "Must be posted as a file upload using multipart/form-data." } PK ! �w � � ParamValidator/i18n/lb.jsonnu �Iw�� { "@metadata": { "authors": [ "Robby", "Volvox" ] }, "paramvalidator-badinteger": "Ongültege Wäert „$2“ fir de ganzzuelege Parameter „$1“.", "paramvalidator-badtimestamp": "Ongültege Wäert „$2“ fir den Zäitstempel-Parameter „$1“.", "paramvalidator-param-deprecated": "De Parameter \"$1\" ass elo vereelzt.", "paramvalidator-help-default": "Standard: $1", "paramvalidator-help-default-empty": "Standard: (eidel)", "paramvalidator-help-deprecated": "Dëse Parameter ass vereelzt.", "paramvalidator-help-multi-max-simple": "Maximal Zuel vun de Wäerter ass {{PLURAL:$1|$1}}.", "paramvalidator-help-required": "Dëse Parameter ass obligatoresch.", "paramvalidator-help-type-limit": "Typ: Ganz Zuel oder „max“", "paramvalidator-help-type-number-max": "{{PLURAL:$1|1=De Wäert däerf|2=D'Wäerter däerfen}} net méi grouss si wéi $3.", "paramvalidator-help-type-number-minmax": "{{PLURAL:$1|1=De Wäert muss|2=D'Wäerter mussen}} tëscht $2 an $3 leien.", "paramvalidator-help-type-number-min": "{{PLURAL:$1|1=De Wäert däerf|2=D'Wäerter däerfen}} net méi kleng si wéi $2.", "paramvalidator-help-type-string-maxbytes": "Däerf net méi laang wéi {{PLURAL:$1|Byte}} sinn.", "paramvalidator-help-type-string-maxchars": "Däerf net méi laang wéi {{PLURAL:$1|Zeeche}} sinn.", "paramvalidator-help-type-timestamp": "Typ: {{PLURAL:$1|1=Zäitstempel|2=Lëscht vun Zäitstempelen}}" } PK ! c�)�* * ParamValidator/i18n/ru.jsonnu �Iw�� { "@metadata": { "authors": [ "BerryAVGN", "Facenapalm", "Okras", "Stjn", "WindEwriX" ] }, "paramvalidator-badbool": "Недопустимое значение «$2» для логического параметра «$1». Передайте $3 для истинного значения, или $5 для ложного.", "paramvalidator-badbool-type": "Недопустимое значение «$2» для логического параметра «$1». Вместо этого получено значение типа $3.", "paramvalidator-badexpiry": "Недопустимое значение «$2» для параметра истечения срока «$1».", "paramvalidator-badexpiry-duration": "Заданное значение «$2» для параметра <var>$1</var> превышает максимально допустимое «$3».", "paramvalidator-badexpiry-duration-max": "Заданное значение «$2» для параметра <var>$1</var> превышает максимально допустимое «$3». Поэтому вместо него использовано максимальное значение.", "paramvalidator-badexpiry-past": "Значение «$2» для параметра истечения срока «$1» уже в прошлом.", "paramvalidator-badfloat": "Недопустимое значение «$2» для параметра с плавающей запятой «$1».", "paramvalidator-badfloat-type": "Недопустимое значение «$2» для числового параметра с плавающей запятой «$1». Вместо этого получено значение типа $3.", "paramvalidator-badfloat-notfinite": "Значение «$2» для параметра с плавающей запятой «$1» слишком велико или не является числом.", "paramvalidator-badinteger": "Недопустимое значение «$2» для целочисленного параметра «$1».", "paramvalidator-badinteger-type": "Недопустимое значение «$2» для целочисленного параметра «$1». Вместо этого получено значение типа $3.", "paramvalidator-badinteger-fraction": "Недопустимое значение «$2» для целочисленного параметра «$1». Вместо этого получено число с плавающей точкой и дробной частью.", "paramvalidator-badtimestamp": "Недопустимое значение «$2» для параметра временной метки «$1».", "paramvalidator-badupload-cantwrite": "Файл для «$1» не удалось сохранить для обработки из-за неправильной конфигурации сервера (запись не удалась).", "paramvalidator-badupload-formsize": "Загруженный файл для «$1» превышает установленный клиентом максимум.", "paramvalidator-badupload-inisize": "Загруженный файл для «$1» превышает максимальное значение сервера, равное $3.", "paramvalidator-badupload-nofile": "Для параметра загрузки «$1» не было предоставлено ни одного файла.", "paramvalidator-badupload-notmpdir": "Файл для «$1» не удалось сохранить для обработки из-за неправильной конфигурации сервера (нет временного каталога).", "paramvalidator-badupload-notupload": "Параметр загрузки файла «$1» не является параметром загрузки файла; обязательно используйте multipart/form-data для POST и включите имя файла в заголовок Content-Disposition.", "paramvalidator-badupload-partial": "Файл для «$1» был загружен лишь частично.", "paramvalidator-badupload-phpext": "Расширение PHP не позволило загрузить файл для «$1».", "paramvalidator-badvalue-enummulti": "Недопустимое значение «$2» для параметра «$1». {{PLURAL:$4|Допускается только «$3».|Допустимые значения - $3.}}", "paramvalidator-badvalue-enumnotmulti": "Нераспознанное значение параметра «$1»: $2.", "paramvalidator-deprecated-value": "Значение «$2» для параметра «$1» устарело.", "paramvalidator-emptystring": "пустая строка", "paramvalidator-maxbytes": "Значение параметра «$1» не может быть длиннее $3 {{PLURAL:$3|байта|байт|байтов}} (было $4).", "paramvalidator-maxchars": "Значение параметра «$1» не может быть длиннее $3 {{PLURAL:$3|символа|символов}} (было $4).", "paramvalidator-missingparam": "Параметр «$1» должен быть задан.", "paramvalidator-notmulti": "Параметр «$1» принимает только одно значение. Многозначное разделение U+001F может использоваться только для многозначных параметров.", "paramvalidator-multivalue-must-be-array": "Многозначный параметр «$1» должен быть задан в виде массива.", "paramvalidator-needstring": "Параметр «$1» принимает только строковые значения, но получил $2", "paramvalidator-outofrange-max": "Значение «$2» для параметра «$1» должно быть не больше, чем $4.", "paramvalidator-outofrange-minmax": "Значение «$2» для параметра «$1» должно быть между $3 и $4.", "paramvalidator-outofrange-min": "Значение «$2» для параметра «$1» должно быть не меньше, чем $3.", "paramvalidator-param-deprecated": "Параметр «$1» устарел.", "paramvalidator-toomanyvalues": "Для параметра «$1» передано слишком много значений. Ограничением является значение $2.", "paramvalidator-unclearnowtimestamp": "Передача значения «$2» для параметра timestamp «$1» устарела. Если по каким-то причинам вам необходимо явно указать текущее время, не вычисляя его на стороне клиента, используйте «now».", "paramvalidator-unrecognizedvalues": "{{PLURAL:$4|Нераспознанное значение|Нераспознанные значения|Нераспознанных значений}} параметра «$1»: $3", "paramvalidator-help-default": "По умолчанию: $1", "paramvalidator-help-default-empty": "По умолчанию: (пусто)", "paramvalidator-help-deprecated": "Этот параметр устарел.", "paramvalidator-help-multi-separate": "Разделяйте значения с помощью «|», или префикс списка с помощью U+001F и разделение с помощью U+001F.", "paramvalidator-help-multi-max": "Максимальное количество значений — {{PLURAL:$1|$1}} ({{PLURAL:$2|$2}} для клиентов, которым разрешены более высокие лимиты).", "paramvalidator-help-multi-max-simple": "Максимальное количество значений — {{PLURAL:$1|$1}}.", "paramvalidator-help-multi-all": "Чтобы указать все значения, используйте <kbd>$1</kbd>.", "paramvalidator-help-required": "Это обязательный параметр.", "paramvalidator-help-type-boolean": "Тип: {{PLURAL:$1|1=логическое значение|2=список логических значений}}", "paramvalidator-help-type-enum-can-be-empty": "{{PLURAL:$2|0=Должен быть пустым|Может быть пустым или $1}}", "paramvalidator-help-type-enum": "{{PLURAL:$1|1=Одно из следующих значений|2=Значения (разделять с помощью U+007C (труба), или префикс списка с помощью U+001F и разделять с помощью U+001F)}}: $2", "paramvalidator-help-type-expiry": "Тип: {{PLURAL:$1|1=истечение срока действия|2=список истечений сроков действия}}.\n\nСрок действия может быть относительным (например, <kbd>5 months</kbd> или <kbd>2 weeks</kbd>) или абсолютным (например, <kbd>2014-09-18T12:34:56Z</kbd>). Если бессрочно = $2.", "paramvalidator-help-type-float": "Тип: {{PLURAL:$1|1=значение с плавающей запятой|2=список со значениями с плавающей запятой}}", "paramvalidator-help-type-integer": "Тип: {{PLURAL:$1|1=целочисленное значение|2=список целочисленных значений}}", "paramvalidator-help-type-limit": "Тип: целочисленное значение или «max»", "paramvalidator-help-type-number-max": "{{PLURAL:$1|1=Значение должно|2=Значения должны}} быть не больше $3.", "paramvalidator-help-type-number-minmax": "{{PLURAL:$1|1=Значение должно|2=Значения должны}} быть между $2 и $3.", "paramvalidator-help-type-number-min": "{{PLURAL:$1|1=Значение должно|2=Значения должны}} быть не меньше $2.", "paramvalidator-help-type-presenceboolean": "Тип: логическое значение", "paramvalidator-help-type-string-maxbytes": "Не может быть длиннее $1 {{PLURAL:$1|байта|байтов}}.", "paramvalidator-help-type-string-maxchars": "Не может быть длиннее $1 {{PLURAL:$1|символа|символов}}.", "paramvalidator-help-type-timestamp": "Тип: {{PLURAL:$1|1=временная метка|2=список временных меток}}", "paramvalidator-help-type-upload": "Должно быть отправлено как файл с использованием multipart/form-data." } PK ! !�!�D D ParamValidator/i18n/tr.jsonnu �Iw�� { "@metadata": { "authors": [ "BaRaN6161 TURK" ] }, "paramvalidator-badbool": "\"$1\" boole parametresi için geçersiz \"$2\" değeri. True için $3 veya false için $5 iletin.", "paramvalidator-badexpiry": "\"$1\" sona erme parametresi için geçersiz \"$2\" değeri.", "paramvalidator-badexpiry-duration": "<var>$1</var> parametresi için \"$2\" verilen maksimum \"$3\" değerini aşıyor.", "paramvalidator-badexpiry-duration-max": "Given value \"$2\" for parameter <var>$1</var> exceeds the maximum of \"$3\". Bunun yerine maksimum kullanılıyor.", "paramvalidator-badexpiry-past": "\"$1\" son kullanma parametresi için \"$2\" değeri geçmişte.", "paramvalidator-badfloat": "\"$1\" float parametresi için geçersiz \"$2\" değeri.", "paramvalidator-badfloat-notfinite": "\"$1\" float parametresi için \"$2\" değeri çok büyük veya bir sayı değil.", "paramvalidator-badinteger": "\"$1\" tamsayı parametresi için geçersiz \"$2\" değeri.", "paramvalidator-badtimestamp": "\"$1\" zaman damgası parametresi için geçersiz \"$2\" değeri.", "paramvalidator-badupload-cantwrite": "\"$1\" dosyası, sunucu yanlış yapılandırması (yazma başarısız) nedeniyle işlenmek üzere saklanamadı.", "paramvalidator-badupload-formsize": "\"$1\" için yüklenen dosya, istemcinin belirttiği maksimum değeri aşıyor.", "paramvalidator-badupload-inisize": "\"$1\" için yüklenen dosya sunucunun maksimum $3 aşıyor.", "paramvalidator-badupload-nofile": "\"$1\" yükleme parametresi için dosya sağlanmadı.", "paramvalidator-badupload-notmpdir": "\"$1\" dosyası, sunucu yanlış yapılandırması nedeniyle (geçici dizin yok) işlenmek üzere saklanamadı.", "paramvalidator-badupload-notupload": "\"$1\" dosya yükleme parametresi bir dosya yüklemesi değil; POST'unuz için çok bölümlü/form verisi kullandığınızdan ve Content-Disposition başlığına bir dosya adı eklediğinizden emin olun.", "paramvalidator-badupload-partial": "\"$1\" dosyası yalnızca kısmen yüklendi.", "paramvalidator-badupload-phpext": "Bir PHP uzantısı \"$1\" için dosyanın yüklenmesini engelledi.", "paramvalidator-badvalue-enummulti": "\"$1\" parametresi için geçersiz \"$2\" değeri. {{PLURAL:$4|Yalnızca \"$3\" a izin verilir.|İzin verilen değerler $3.}}", "paramvalidator-badvalue-enumnotmulti": "\"$1\" parametresi için tanınmayan değer: $2.", "paramvalidator-deprecated-value": "\"$1\" parametresine \"$2\" değeri kullanımdan kaldırıldı.", "paramvalidator-emptystring": "boş dize", "paramvalidator-maxbytes": "\"$1\" parametresi değeri $3 bayttan daha uzun olamaz ($4 idi).", "paramvalidator-maxchars": "\"$1\" parametresi değeri $3 karakterden uzun olamaz ($4 idi).", "paramvalidator-missingparam": "\"$1\" parametresi ayarlanmalıdır.", "paramvalidator-notmulti": "\"$1\" parametresi yalnızca tek bir değeri kabul eder. U+001F çok değerli ayırma yalnızca çok değerli parametreler için kullanılabilir.", "paramvalidator-outofrange-max": "\"$1\" parametresi için \"$2\" değeri $4 fazladan büyük olmamalıdır.", "paramvalidator-outofrange-minmax": "\"$1\" parametresi için \"$2\" değeri $3 ile $4 arasında olmalıdır.", "paramvalidator-outofrange-min": "\"$1\" parametresi için \"$2\" değeri $3 daha az olmamalıdır.", "paramvalidator-param-deprecated": "\"$1\" parametresi kullanımdan kaldırıldı.", "paramvalidator-toomanyvalues": "\"$1\" parametresi için çok fazla değer sağlandı. Limit $2.", "paramvalidator-unclearnowtimestamp": "\"$1\" zaman damgası parametresi için \"$2\" iletiliyor. Herhangi bir nedenden ötürü, istemci tarafını hesaplamadan geçerli saati açıkça belirtmeniz gerekiyorsa, \"now\" kullanın.", "paramvalidator-unrecognizedvalues": "\"$1\" parametresi için tanınmayan {{PLURAL:$4|değer|değerler}}: $3", "paramvalidator-help-default": "Varsayılan: $1", "paramvalidator-help-default-empty": "Varsayılan: (boş)", "paramvalidator-help-deprecated": "Bu parametre kullanımdan kaldırıldı.", "paramvalidator-help-multi-separate": "Değerleri \"|\" ile ayırın veya listeye U+001F ile önek ekleyin ve U+001F ile ayırın.", "paramvalidator-help-multi-max": "Maksimum değer sayısı {{PLURAL:$1|$1}} ({{PLURAL:$2|$2}} için daha yüksek sınırlara izin verilir).", "paramvalidator-help-multi-max-simple": "Maksimum değer sayısı {{PLURAL:$1|$1}}.", "paramvalidator-help-multi-all": "Tüm değerleri belirtmek için <kbd>$1</kbd> kullanın.", "paramvalidator-help-required": "Bu parametre gerekli.", "paramvalidator-help-type-boolean": "Tür: {{PLURAL:$1|1=boole|2=boole listesi}}", "paramvalidator-help-type-enum-can-be-empty": "{{PLURAL:$2|0=Boş olmalıdır|Boş veya $1 olabilir}}", "paramvalidator-help-type-enum": "{{PLURAL:$1|1=Aşağıdaki değerlerden biri|2=Değerler (U+007C (boru) ile ayırın veya listeye U+001F ile önek ekleyin ve U+001F ile ayırın)}}: $2", "paramvalidator-help-type-expiry": "Tür: {{PLURAL:$1|1=bitiş|2=süre bitimi listesi}}.\n\nGöreli (ör. <kbd>5 ay</kbd> veya <kbd>2 hafta</kbd>) veya mutlak (örn. <kbd>2014-09-18T12:34:56Z</kbd>) olabilir. Süre bitimi olmaması için, $2 kullanın.", "paramvalidator-help-type-float": "Tür: {{PLURAL:$1|1=şamandıra|2=şamandıra listesi}}", "paramvalidator-help-type-integer": "Tür: {{PLURAL:$1|1=tamsayı|2=tamsayı listesi}}", "paramvalidator-help-type-limit": "Tür: tamsayı veya \"maks\"", "paramvalidator-help-type-number-max": "{{PLURAL:$1|1=Değer|2=Değerler}} $3 fazladan olmamalıdır.", "paramvalidator-help-type-number-minmax": "{{PLURAL:$1|1=Değer|2=Değerler}}, $2 ile $3 arasında olmalıdır.", "paramvalidator-help-type-number-min": "{{PLURAL:$1|1=Değer|2=Değerler}}, $2 daha az olmamalıdır.", "paramvalidator-help-type-presenceboolean": "Tür: boole", "paramvalidator-help-type-string-maxbytes": "$1 bayt fazladan uzun olamaz.", "paramvalidator-help-type-string-maxchars": "$1 karakterden uzun olamaz.", "paramvalidator-help-type-timestamp": "Tür: {{PLURAL:$1|1=zaman çizelgesi|2=zaman çizelgesi listesi}}", "paramvalidator-help-type-upload": "Çok parçalı/form verileri kullanılarak dosya yüklemesi olarak gönderilmelidir." } PK ! ��2A~ ~ ParamValidator/i18n/fr.jsonnu �Iw�� { "@metadata": { "authors": [ "Assorted-Interests", "Gomoko", "Méthodes Bulebe Hangi", "Orlodrim", "Pamputt", "Thibaut120094", "Verdy p", "Wladek92", "Mahabarata" ] }, "paramvalidator-badbool": "Valeur « $2 » non valide pour le paramètre booléen « $1 ». Passer $3 pour vrai, ou $5 pour faux.", "paramvalidator-badbool-type": "Valeur « $2 » invalide pour le paramètre booléen « $1 ». La valeur semble être de type $3.", "paramvalidator-badexpiry": "Valeur « $2 » non valide pour le paramètre d’expiration « $1 ».", "paramvalidator-badexpiry-duration": "La valeur « $2 » donnée pour le paramètre <var>$1</var> dépasse le maximum de « $3 ».", "paramvalidator-badexpiry-duration-max": "La valeur « $2 » donnée pour le paramètre <var>$1</var> dépasse le maximum de « $3 ». Utilisation de la valeur maximale à la place.", "paramvalidator-badexpiry-past": "La valeur « $2 » pour le paramètre d’expiration « $1 » est dans le passé.", "paramvalidator-badfloat": "Valeur « $2 » non valide pour le paramètre flottant « $1 ».", "paramvalidator-badfloat-type": "Valeur « $2 » invalide pour le paramètre flottant « $1 ». La valeur semble être de type $3.", "paramvalidator-badfloat-notfinite": "La valeur « $2 » pour le paramètre flottant « $1 » est trop grande ou n’est pas un nombre.", "paramvalidator-badinteger": "Valeur « $2 » non valide pour le paramètre entier « $1 ».", "paramvalidator-badinteger-type": "Valeur « $2 » invalide pour le paramètre entier « $1 ». La valeur semble être de type $3.", "paramvalidator-badinteger-fraction": "Valeur « $2 » invalide pour le paramètre entier « $1 ». La valeur semble être un flottant avec une partie décimale.", "paramvalidator-badtimestamp": "Valeur « $2 » non valide pour le paramètre d’horodatage « $1 ».", "paramvalidator-badupload-cantwrite": "Le fichier pour « $1 » n’a pas pu être stocké pour être traité du fait d’une mauvaise configuration du serveur (échec d’écriture).", "paramvalidator-badupload-formsize": "Le fichier téléchargé pour « $1 » dépasse le maximum spécifié pour le client.", "paramvalidator-badupload-inisize": "Le fichier téléchargé pour « $1 » dépasse le maximum du serveur de $3.", "paramvalidator-badupload-nofile": "Aucun fichier n’a été fourni pour le paramètre de téléversement « $1 ».", "paramvalidator-badupload-notmpdir": "Le fichier pour « $1 » n’a pas pu être enregistré pour traitement du fait d’une mauvaise configuration du serveur (pas de répertoire temporaire).", "paramvalidator-badupload-notupload": "Le paramètre de téléversement de fichier « $1 » n’est pas un téléversement de fichier ; assurez-vous d’utiliser le format « multipart/form-data » pour votre POST et d’inclure un nom de fichier dans l’entête « Content-Disposition ».", "paramvalidator-badupload-partial": "Le fichier pour « $1 » n’a été que partiellement téléversé.", "paramvalidator-badupload-phpext": "Une extension PHP a empêché le téléversement du fichier pour « $1 ».", "paramvalidator-badvalue-enummulti": "Valeur « $2 » non valide pour le paramètre « $1 ». {{PLURAL:$4|Seul « $3 » est autorisé.|Les valeurs autorisées sont $3.}}", "paramvalidator-badvalue-enumnotmulti": "Valeur non reconnue pour le paramètre « $1 » : $2.", "paramvalidator-deprecated-value": "La valeur « $2 » pour le paramètre « $1 » est obsolète.", "paramvalidator-emptystring": "chaîne vide", "paramvalidator-maxbytes": "La valeur du paramètre « $1 » ne peut pas dépasser $3 {{PLURAL:$3|octet|octets}} (c’était $4 {{PLURAL:$3|octet|octets}}).", "paramvalidator-maxchars": "La valeur pour le paramètre « $1 » ne peut pas dépasser $3 {{PLURAL:$3|caractère|caractères}} (elle était $4).", "paramvalidator-missingparam": "Le paramètre « $1 » doit être défini.", "paramvalidator-notmulti": "Le paramètre « $1 » n’accepte qu’une seule valeur. La séparation multi-valeurs U+001F ne peut être utilisée que pour les paramètres multi-valués.", "paramvalidator-multivalue-must-be-array": "Le paramètre à valeurs multiples \"$1\" doit être donné en tant qu'un tableau.", "paramvalidator-needstring": "Le paramètre \"$1\" accepte seulement une valeur de type chaîne, mais a reçu $2", "paramvalidator-outofrange-max": "La valeur « $2 » pour le paramètre « $1 » ne doit pas dépasser $4.", "paramvalidator-outofrange-minmax": "La valeur « $2 » pour le paramètre « $1 » doit être entre $3 et $4.", "paramvalidator-outofrange-min": "La valeur « $2 » pour le paramètre « $1 » ne doit pas être inférieure à $3.", "paramvalidator-param-deprecated": "Le paramètre « $1 » a été marqué obsolète.", "paramvalidator-toomanyvalues": "Trop de valeurs fournies pour le paramètre « $1 ». La limite est $2.", "paramvalidator-unclearnowtimestamp": "Passer « $2 » pour le paramètre d’horodatage « $1 » a été marqué obsolète. Si, pour une raison quelconque, vous avez besoin de spécifier explicitement l’heure actuelle sans la calculer côté client, utilisez « now ».", "paramvalidator-unrecognizedvalues": "{{PLURAL:$4|Valeur non reconnue|Valeurs non reconnues}} pour le paramètre « $1 » : $3", "paramvalidator-help-default": "Par défaut : $1", "paramvalidator-help-default-empty": "Par défaut : (vide)", "paramvalidator-help-deprecated": "Ce paramètre est obsolète.", "paramvalidator-help-multi-separate": "Séparer les valeurs avec « | », ou préfixer la liste avec U+001F et séparer avec U+001F.", "paramvalidator-help-multi-max": "Le nombre maximal de valeurs est {{PLURAL:$1|$1}} (ou {{PLURAL:$2|$2}} pour les clients ayant droit aux limites plus élevées).", "paramvalidator-help-multi-max-simple": "Le nombre maximal de valeurs est {{PLURAL:$1|$1}}.", "paramvalidator-help-multi-all": "Pour indiquer toutes les valeurs, utiliser <kbd>$1</kbd>.", "paramvalidator-help-required": "Ce paramètre est obligatoire.", "paramvalidator-help-type-boolean": "Type: {{PLURAL:$1|1=booléen|2=liste de booléens}}", "paramvalidator-help-type-enum-can-be-empty": "{{PLURAL:$2|0=Doit être vide|Peut être vide, ou $1}}", "paramvalidator-help-type-enum": "{{PLURAL:$1|1=Une des valeurs suivantes|2=Valeurs (séparer avec U+007C (barre verticale), ou préfixer la liste avec U+001F et la séparer avec U+001F)}} : $2", "paramvalidator-help-type-expiry": "Type : {{PLURAL:$1|1=expiration|2=liste d’expirations}}.\n\nPeut être relatif (par ex. <kbd>5 months</kbd> ou <kbd>2 weeks</kbd>) ou absolu (par ex. <kbd>2014-09-18T12:34:56Z</kbd>). Pour ne pas avoir d’expiration, utiliser $2.", "paramvalidator-help-type-float": "Type : {{PLURAL:$1|1=flottant|2=liste de flottants}}", "paramvalidator-help-type-integer": "Type: {{PLURAL:$1|1=entier|2=liste d'entiers}}", "paramvalidator-help-type-limit": "Type : entier ou « max »", "paramvalidator-help-type-number-max": "{{PLURAL:$1|1=La valeur ne doit pas être plus grande|2=Les valeurs ne doivent pas être plus grandes}} que $3.", "paramvalidator-help-type-number-minmax": "{{PLURAL:$1|1=La valeur doit|2=Les valeurs doivent}} être entre $2 et $3.", "paramvalidator-help-type-number-min": "{{PLURAL:$1|1=La valeur ne peut|2=Les valeurs ne peuvent}} pas être {{PLURAL:$1|inférieure|inférieures}} à $2.", "paramvalidator-help-type-presenceboolean": "Type : booléen", "paramvalidator-help-type-string-maxbytes": "Ne peut pas être plus long que $1 {{PLURAL:$1|octet|octets}}.", "paramvalidator-help-type-string-maxchars": "Ne peut pas être plus long que $1 {{PLURAL:$1|caractère|caractères}}.", "paramvalidator-help-type-timestamp": "Type : {{PLURAL:$1|1=horodatage|2=liste d'horodatages}}", "paramvalidator-help-type-upload": "Doit être posté sous forme de téléversement de fichier utilisant multipart/form-data." } PK ! (x�\?. ?. ParamValidator/i18n/qqq.jsonnu �Iw�� { "@metadata": { "authors": [ "Amire80", "Anomie", "D41D8CD98F", "Liuxinyu970226", "McDutchie", "MusikAnimal", "Nemo bis", "Purodha", "Raymond", "Robby", "Shirayuki", "Siebrand", "Tacsipacsi", "Umherirrender", "Zoranzoki21" ] }, "paramvalidator-badbool": "Error in API parameter validation. Parameters:\n* $1 - Parameter name.\n* $2 - Parameter value.\n* $3 - List of values recognized as \"true\", as a text list.\n* $4 - Count of values in $3.\n* $5 - List of values recognized as \"false\", as a text list. Includes {{msg-mw|paramvalidator-emptystring}}.\n* $6 - Count of values in $5.", "paramvalidator-badbool-type": "Error in API parameter validation. Parameters:\n* $1 - Parameter name.\n* $2 - Parameter value.\n* $3 - The actual type of the parameter value.", "paramvalidator-badexpiry": "Error in API parameter validation. Parameters:\n* $1 - Parameter name.\n* $2 - Parameter value.", "paramvalidator-badexpiry-duration": "Error in API parameter validation. Parameters:\n* $1 - Parameter name.\n* $2 - Parameter value.\n* $3 - Maximum permitted value.", "paramvalidator-badexpiry-duration-max": "Error in API parameter validation. Parameters:\n* $1 - Parameter name.\n* $2 - Parameter value.\n* $3 - Maximum permitted value.", "paramvalidator-badexpiry-past": "Error in API parameter validation. Parameters:\n* $1 - Parameter name.\n* $2 - Parameter value.", "paramvalidator-badfloat": "Error in API parameter validation. Parameters:\n* $1 - Parameter name.\n* $2 - Parameter value.", "paramvalidator-badfloat-type": "Error in API parameter validation. Parameters:\n* $1 - Parameter name.\n* $2 - Parameter value.\n* $3 - The actual type of the parameter value.", "paramvalidator-badfloat-notfinite": "Error in API parameter validation. Parameters:\n* $1 - Parameter name.\n* $2 - Parameter value.", "paramvalidator-badinteger": "Error in API parameter validation. Parameters:\n* $1 - Parameter name.\n* $2 - Parameter value.", "paramvalidator-badinteger-type": "Error in API parameter validation. Parameters:\n* $1 - Parameter name.\n* $2 - Parameter value.\n* $3 - The actual type of the parameter value.", "paramvalidator-badinteger-fraction": "Error in API parameter validation. Parameters:\n* $1 - Parameter name.\n* $2 - Parameter value.", "paramvalidator-badtimestamp": "Error in API parameter validation. Parameters:\n* $1 - Parameter name.\n* $2 - Parameter value.", "paramvalidator-badupload-cantwrite": "Error in API parameter validation. Parameters:\n* $1 - Parameter name.\n* $2 - Empty (unused).", "paramvalidator-badupload-formsize": "Error in API parameter validation. Parameters:\n* $1 - Parameter name.\n* $2 - Empty (unused).", "paramvalidator-badupload-inisize": "Error in API parameter validation. Parameters:\n* $1 - Parameter name.\n* $2 - Empty (unused).\n* $3 - Maximum allowed size, formated with appropriate units.", "paramvalidator-badupload-nofile": "Error in API parameter validation. Parameters:\n* $1 - Parameter name.\n* $2 - Empty (unused).", "paramvalidator-badupload-notmpdir": "Error in API parameter validation. Parameters:\n* $1 - Parameter name.\n* $2 - Empty (unused).", "paramvalidator-badupload-notupload": "Error in API parameter validation. Parameters:\n* $1 - Parameter name.\n* $2 - Empty (unused).", "paramvalidator-badupload-partial": "Error in API parameter validation. Parameters:\n* $1 - Parameter name.\n* $2 - Empty (unused).", "paramvalidator-badupload-phpext": "Error in API parameter validation. Parameters:\n* $1 - Parameter name.\n* $2 - Empty (unused).", "paramvalidator-badvalue-enummulti": "Error in API parameter validation. Parameters:\n* $1 - Parameter name.\n* $2 - Parameter value.\n* $3 - Allowed values, as a text list.\n* $4 - Count of values in $3.", "paramvalidator-badvalue-enumnotmulti": "Error in API parameter validation. Parameters:\n* $1 - Parameter name.\n* $2 - Parameter value.\n* $3 - Allowed values, as a text list.\n* $4 - Count of values in $3.", "paramvalidator-deprecated-value": "Error in API parameter validation. Parameters:\n* $1 - Parameter name.\n* $2 - Parameter value.", "paramvalidator-emptystring": "Text used to represent the empty string in help messages.", "paramvalidator-maxbytes": "Error in API parameter validation. Parameters:\n* $1 - Parameter name.\n* $2 - Parameter value.\n* $3 - Maximum allowed size in bytes.\n* $4 - Size of the supplied string in bytes.", "paramvalidator-maxchars": "Error in API parameter validation. \"Characters\" here refers to Unicode codepoints. Parameters:\n* $1 - Parameter name.\n* $2 - Parameter value.\n* $3 - Maximum allowed size in Unicode codepoints.\n* $4 - Size of the supplied string in Unicode codepoints.", "paramvalidator-missingparam": "Error in API parameter validation. Parameters:\n* $1 - Parameter name.", "paramvalidator-notmulti": "Error in API parameter validation. Parameters:\n* $1 - Parameter name.\n* $2 - Parameter value.", "paramvalidator-multivalue-must-be-array": "Error in API parameter validation. Parameters:\n* $1 - Parameter name.", "paramvalidator-needstring": "Error in API parameter validation. Parameters:\n* $1 - Parameter name.\n* $2 - Actual parameter type.", "paramvalidator-outofrange-max": "Error in API parameter validation. Parameters:\n* $1 - Parameter name.\n* $2 - Parameter value.\n* $3 - Unused.\n* $4 - Maximum allowed value.", "paramvalidator-outofrange-minmax": "Error in API parameter validation. Parameters:\n* $1 - Parameter name.\n* $2 - Parameter value.\n* $3 - Minimum allowed value\n* $4 - Maximum allowed value.", "paramvalidator-outofrange-min": "Error in API parameter validation. Parameters:\n* $1 - Parameter name.\n* $2 - Parameter value.\n* $3 - Minimum allowed value\n* $4 - Unused.", "paramvalidator-param-deprecated": "Error in API parameter validation. Parameters:\n* $1 - Parameter name.\n* $2 - Parameter value.", "paramvalidator-param-sensitive": "Error in API parameter validation. Parameters:\n* $1 - Parameter name.\n* $2 - Parameter value.", "paramvalidator-toomanyvalues": "Error in API parameter validation. Parameters:\n* $1 - Parameter name.\n* $2 - Number of allowed values.", "paramvalidator-unclearnowtimestamp": "Error in API parameter validation. Parameters:\n* $1 - Parameter name.\n* $2 - Parameter value.", "paramvalidator-unrecognizedvalues": "Error in API parameter validation. Parameters:\n* $1 - Parameter name.\n* $2 - Parameter value.\n* $3 - List of unrecognized values, as a comma-separated list.\n* $4 - Count of values in $3.", "paramvalidator-help-default": "Help message indicating the default value of a parameter. Parameters:\n* $1 - The default value\n\nSee also: {{msg-mw|paramvalidator-help-default-empty}}\n{{Identical|Default}}", "paramvalidator-help-default-empty": "Help message indicating that the default value of a parameter is the empty string.\n\nSee also:\n* {{msg-mw|paramvalidator-help-default}}", "paramvalidator-help-deprecated": "Help message indicating the parameter is deprecated.", "paramvalidator-help-multi-separate": "Used to indicate how to separate multiple values.", "paramvalidator-help-multi-max": "Used to indicate the maximum number of values accepted for a multi-valued parameter when that value is influenced by the user being allowed high limits (otherwise {{msg-mw|paramvalidator-help-multi-max-simple}} is used).\n\nParameters:\n* $1 - Maximum value without high limits\n* $2 - Maximum value with high limits", "paramvalidator-help-multi-max-simple": "Used to indicate the maximum number of values accepted for a multi-valued parameter when that value is not influenced by the user being allowed high limits (otherwise {{msg-mw|paramvalidator-help-multi-max}} is used).\n\nParameters:\n* $1 - Maximum value", "paramvalidator-help-multi-all": "Used to indicate what string can be used to specify all possible values of a multi-valued parameter. \n\nParameters:\n* $1 - String to specify all possible values of the parameter", "paramvalidator-help-required": "Help message indicating the parameter is required.", "paramvalidator-help-type-boolean": "Used to indicate that a parameter is a boolean (\"true\" or \"false\") or list of booleans. Parameters:\n* $1 - 1 if the parameter takes one value, 2 if the parameter takes any number of values", "paramvalidator-help-type-enum-can-be-empty": "Used to indicate that one of the possible values in the list is the empty string.\n\nParameters:\n* $1 - Remainder of the list, as a comma-separated list.\n* $2 - Number of items in $1; may be 0", "paramvalidator-help-type-enum": "Used to display the possible values for a parameter taking a list of values\n\nParameters:\n* $1 - 1 if the parameter takes one value, 2 if the parameter takes any number of values\n* $2 - Comma-separated list of values, possibly formatted using {{msg-mw|paramvalidator-help-list-can-be-empty}}\n* $3 - Number of items in $2 (including the empty string, if applicable).\n{{Identical|Value}}", "paramvalidator-help-type-expiry": "Help message indicating valid values for the expiry type.\n\nParameters:\n* $1 - 1 if the parameter takes one value, 2 if the parameter takes any number of values\n* $2 - Comma-separated list of values representing 'never expires'.", "paramvalidator-help-type-float": "Used to indicate that a parameter is a decimal number or list of numbers. Parameters:\n* $1 - 1 if the parameter takes one value, 2 if the parameter takes any number of values", "paramvalidator-help-type-integer": "Used to indicate that a parameter is an integer or list of integers. Parameters:\n* $1 - 1 if the parameter takes one value, 2 if the parameter takes any number of values", "paramvalidator-help-type-limit": "Used to indicate that a parameter is a \"limit\" type. Parameters:\n* $1 - Always 1", "paramvalidator-help-type-number-max": "Used to display a numeric parameter with a maximum but no minimum value.\n\nParameters:\n* $1 - 1 if the parameter takes one value, 2 if the parameter takes any number of values\n* $2 - (Unused)\n* $3 - Maximum value\nSee also:\n* {{msg-mw|Api-help-param-number-min}}\n* {{msg-mw|Api-help-param-number-minmax}}", "paramvalidator-help-type-number-minmax": "Used to display a numeric parameter with a maximum and minimum values\n\nParameters:\n* $1 - 1 if the parameter takes one value, 2 if the parameter takes any number of values\n* $2 - Minimum value\n* $3 - Maximum value\n\nSee also:\n* {{msg-mw|paramvalidator-help-number-min}}\n* {{msg-mw|paramvalidator-help-number-max}}", "paramvalidator-help-type-number-min": "Used to display a numeric parameter with a minimum but no maximum value\n\nParameters:\n* $1 - 1 if the parameter takes one value, 2 if the parameter takes any number of values\n* $2 - Minimum value\n* $3 - unused\n\nSee also:\n* {{msg-mw|paramvalidator-help-number-max}}\n* {{msg-mw|paramvalidator-help-number-minmax}}", "paramvalidator-help-type-presenceboolean": "Used to indicate that a parameter is a checkbox-like boolean (true if present regardless of value, false if absent). Parameters:\n* $1 - Always 1.", "paramvalidator-help-type-string-maxbytes": "Used to display the maximum allowed length of a parameter, in bytes. Parameters:\n* $1 - Maximum allowed length in bytes.", "paramvalidator-help-type-string-maxchars": "Used to display the maximum allowed length of a parameter, in characters (i.e. Unicode codepoints).\n* $1 - Maximum allowed length in Unicode codepoints.", "paramvalidator-help-type-timestamp": "Used to indicate that a parameter is a timestamp or list of timestamps. Parameters:\n* $1 - 1 if the parameter takes one value, 2 if the parameter takes any number of values", "paramvalidator-help-type-upload": "Used to indicate that an 'upload'-type parameter must be posted as a file upload using multipart/form-data." } PK ! *w�� ParamValidator/i18n/br.jsonnu �Iw�� { "@metadata": { "authors": [ "Fulup", "Huñvreüs" ] }, "paramvalidator-badexpiry": "Talvoud \"$2\" direizh evit an arventenn aet d'e dermen \"$1\".", "paramvalidator-badexpiry-past": "An talvoud \"$2\" evit an arventenn aet d'e dermen \"$1\" a zo tremenet c'hoazh.", "paramvalidator-badfloat": "Talvoud \"$2\" direizh evit an arventenn war-neuñv \"$1\".", "paramvalidator-badfloat-notfinite": "Re vras eo an talvoud \"$2\" evit an arventenn war-neuñv \"$1\", pe neuze n'eo ket un niver eo.", "paramvalidator-badinteger": "Talvoud \"$2\" direizh evit an arventenn anterin \"$1\".", "paramvalidator-badupload-cantwrite": "N'eus ket bet gallet stokañ ar restr evit \"$1\" abalamour d'ur fazi kefluniañ er servijer (skrivadur c'hwitet).", "paramvalidator-badupload-inisize": "Re vras eo ar restr pellgarget \"$1\" evit galloudezh ar servijer hag a zo $3", "paramvalidator-badupload-partial": "Pellgarget eo bet ar restr evit \"$1\" en un doare darnel hepken.", "paramvalidator-badupload-phpext": "Gant un astenn PHP eo bet miret enporzhiañ ar restr evit \"$1\".", "paramvalidator-badvalue-enumnotmulti": "N'eo ket bet anavezet talvoud an arventenn \"$1\" : $2.", "paramvalidator-emptystring": "an neudennad c'houllo", "paramvalidator-maxbytes": "Ne c'hall ket an talvoud evit an arventenn \"$1\" bezañ hiroc'h eget $3 {{PLURAL:$3|okted}} (ha $4 a oa).", "paramvalidator-maxchars": "Ne c'hall ket an talvoud evit an arventenn \"$1\" bezañ hiroc'h eget $3 {{PLURAL:$3|arouezenn}} (ha $4 a oa).", "paramvalidator-missingparam": "Rekis eo termeniñ an arventenn \"$1\".", "paramvalidator-outofrange-max": "Ne c'hall ket an talvoud \"$2\" bezañ brasoc'h eget $4 evit an arventenn \"$1\".", "paramvalidator-outofrange-minmax": "Ret eo d'an talvoud \"$2\" evit an arventenn \"$1\" bezañ etre $3 ha $4.", "paramvalidator-outofrange-min": "Ne c'hall ket an talvoud \"$2\" evit an arventenn \"$1\" bezañ dindan $3.", "paramvalidator-param-deprecated": "Merket eo bet an arventenn \"$1\" evel dispredet.", "paramvalidator-help-default": "Dre ziouer : $1", "paramvalidator-help-default-empty": "Dre ziouer : (goullo)", "paramvalidator-help-deprecated": "Dispredet eo an arventenn-mañ", "paramvalidator-help-multi-max-simple": "An niver brasañ a dalvoudoù a zo {{PLURAL:$1|$1}}.", "paramvalidator-help-multi-all": "Evit merkan an holl dalvoudoù, grit gant <kbd>$1</kbd>.", "paramvalidator-help-required": "Rekis eo an arventenn-mañ.", "paramvalidator-help-type-boolean": "Type: {{PLURAL:$1|1=boolean|2=roll booleanoù}}", "paramvalidator-help-type-enum-can-be-empty": "{{PLURAL:$2|0=a rank bezañ goullo|a c'hall bezañ goullo, pe $1}}", "paramvalidator-help-type-expiry": "Seurt : {{PLURAL:$1|1=expiration|2=roll aet d'e dermen}}.\n\nA c'hall bezañ relativel (da sk. <kbd>5 miz</kbd> pe <kbd>2 sizhun</kbd>) pe krenn (da sk. <kbd>2014-09-18T12:34:56Z</kbd>). Kuit da gaout un deiziad termen, ober gant $2.", "paramvalidator-help-type-float": "Seurt : {{PLURAL:$1|1=float|2=roll ar re war-neuñv}}", "paramvalidator-help-type-integer": "Type: {{PLURAL:$1|1=anterin|2=roll aniveroù anterin}}", "paramvalidator-help-type-limit": "Seurt : anterin pe \"brasañ\"", "paramvalidator-help-type-number-minmax": "An {{PLURAL:$1|1=talvoud|2=talvoudoù}} a rank bezañ etre $2 ha $3.", "paramvalidator-help-type-number-min": "Ne c'hall ket an {{PLURAL:$1|1=talvoud|2=talvoudoù}} bezañ dindan $2.", "paramvalidator-help-type-presenceboolean": "Seurt : boolean", "paramvalidator-help-type-timestamp": "Type: {{PLURAL:$1|1=timestamp|2=roll an eurdeziata}}" } PK ! ڰ�� ParamValidator/i18n/pt-br.jsonnu �Iw�� { "@metadata": { "authors": [ "Eduardo Addad de Oliveira", "Eduardoaddad", "Flaviane da Silva", "Iohanen", "Re demz", "McDutchie", "Felipe L. Ewald" ] }, "paramvalidator-badbool": "Valor inválido \"$2\" para o parâmetro booleano \"$1\". Passe $3 para true ou $5 para false.", "paramvalidator-badbool-type": "Valor inválido \"$2\" para o parâmetro booleano \"$1\". Em vez disso, obteve um valor $3.", "paramvalidator-badexpiry": "Valor inválido \"$2\" para o parâmetro de expiração \"$1\".", "paramvalidator-badexpiry-duration": "O valor \"$2\" dado para o paramêtro <var>$1</var> excede o máximo de \"$3\".", "paramvalidator-badexpiry-duration-max": "Valor dado \"$2\" para o parâmetro <var>$1</var> excede o máximo de \"$3\". Usando o máximo em seu lugar.", "paramvalidator-badexpiry-past": "O valor \"$2\" para o parâmetro de expiração \"$1\" está no passado.", "paramvalidator-badfloat": "Valor inválido \"$2\" para o parâmetro float \"$1\".", "paramvalidator-badfloat-type": "Valor inválido \"$2\" para o parâmetro float \"$1\". Em vez disso, obteve um valor de $3.", "paramvalidator-badfloat-notfinite": "O valor \"$2\" para o parâmetro flutuante \"$1\" é muito grande ou não é um número.", "paramvalidator-badinteger": "Valor inválido \"$2\" para o parâmetro inteiro \"$1\".", "paramvalidator-badinteger-type": "Valor inválido \"$2\" para o parâmetro inteiro \"$1\". Em vez disso, obteve um valor $3.", "paramvalidator-badinteger-fraction": "Valor inválido \"$2\" para o parâmetro inteiro \"$1\". Em vez disso, obteve um float com uma parte fracionária.", "paramvalidator-badtimestamp": "Valor inválido \"$2\" para o parâmetro de carimbo de data/hora \"$1\".", "paramvalidator-badupload-cantwrite": "O arquivo para \"$1\" não pôde ser armazenado para processamento devido a uma configuração incorreta do servidor (falha na gravação).", "paramvalidator-badupload-formsize": "O arquivo enviado para \"$1\" excede o máximo especificado pelo cliente.", "paramvalidator-badupload-inisize": "O arquivo enviado para \"$1\" excede o máximo de $3 do servidor.", "paramvalidator-badupload-nofile": "Nenhum arquivo foi fornecido para o parâmetro de carregamento de \"$1\".", "paramvalidator-badupload-notmpdir": "O arquivo para \"$1\" não pôde ser armazenado para processamento devido a uma configuração incorreta do servidor (nenhum diretório temporário).", "paramvalidator-badupload-notupload": "O parâmetro de carregamento de arquivo \"$1\" não é um upload de arquivo; certifique-se de usar dados de várias partes/formulário para o seu POST e inclua um nome de arquivo no cabeçalho Disposição de conteúdo.", "paramvalidator-badupload-partial": "O arquivo para \"$1\" foi carregado apenas parcialmente.", "paramvalidator-badupload-phpext": "Uma extensão PHP impediu o carregamento do arquivo por \"$1\".", "paramvalidator-badvalue-enummulti": "Valor inválido \"$2\" para o parâmetro \"$1\". {{PLURAL:$4|Só é permitido \"$3\".|Os valores permitidos são $3.}}", "paramvalidator-badvalue-enumnotmulti": "Valor não reconhecido para o parâmetro \"$1\": $2.", "paramvalidator-deprecated-value": "O valor \"$2\" para o parâmetro \"$1\" foi descontinuado.", "paramvalidator-emptystring": "a cadeia está vazia", "paramvalidator-maxbytes": "O valor para o parâmetro \"$1\" não pode ter mais de $3 {{PLURAL:$3|byte|bytes}} (tinha $4).", "paramvalidator-maxchars": "O valor para o parâmetro \"$1\" não pode ter mais de $3 {{PLURAL:$3|carácter|caracteres}} (tinha $4).", "paramvalidator-missingparam": "O parâmetro \"$1\" deve ser definido.", "paramvalidator-notmulti": "O parâmetro \"$1\" só aceita um único valor. A separação multivalor U+001F só pode ser usada em parâmetros multivalor.", "paramvalidator-multivalue-must-be-array": "O parâmetro de vários valores \"$1\" deve ser fornecido como uma matriz.", "paramvalidator-needstring": "Parametro \"$1\" aceita apenas um valor em texto, mas recebeu \"$2\"", "paramvalidator-outofrange-max": "O valor \"$2\" para o parâmetro \"$1\" não deve ser maior que $4.", "paramvalidator-outofrange-minmax": "O valor \"$2\" para o parâmetro \"$1\" deve estar entre $3 e $4.", "paramvalidator-outofrange-min": "O valor \"$2\" para o parâmetro \"$1\" não deve ser inferior a $3.", "paramvalidator-param-deprecated": "O parâmetro \"$1\" foi descontinuado.", "paramvalidator-toomanyvalues": "Valores demais fornecidos para o parâmetro \"$1\". O limite é de $2.", "paramvalidator-unclearnowtimestamp": "A passagem de \"$2\" no parâmetro de data e hora \"$1\" foi descontinuada. Se, por qualquer razão, precisar de especificar de forma explícita a hora atual sem a calcular no lado do cliente, use \"now\".", "paramvalidator-unrecognizedvalues": "{{PLURAL:$4|Valor não reconhecido|Valores não reconhecidos}} para o parâmetro \"$1\": $3.", "paramvalidator-help-default": "Padrão: $1", "paramvalidator-help-default-empty": "Padrão: (vazio)", "paramvalidator-help-deprecated": "Este parâmetro está obsoleto.", "paramvalidator-help-multi-separate": "Separe os valores com \"|\" ou prefixe a lista com U+001F e separe-os com U+001F.", "paramvalidator-help-multi-max": "O número máximo de valores é {{PLURAL:$1|$1}} ({{PLURAL:$2|$2}} para clientes aos quais limites mais altos são permetidos).", "paramvalidator-help-multi-max-simple": "O número máximo de valores é {{PLURAL:$1|$1}}.", "paramvalidator-help-multi-all": "Para especificar todos os valores, use <kbd>$1</kbd>.", "paramvalidator-help-required": "Este parâmetro é obrigatório.", "paramvalidator-help-type-boolean": "Tipo: {{PLURAL:$1|1=boleano|2=lista de booleanos}}", "paramvalidator-help-type-enum-can-be-empty": "{{PLURAL:$2|0=Deve estar vazio|Pode estar vazio ou $1}}", "paramvalidator-help-type-enum": "{{PLURAL:$1|1=Um dos seguintes valores|2=Valores (separar com U+007C (barra vertical) ou prefixar a lista com U+001F e separar os valores com U+001F)}}: $2", "paramvalidator-help-type-expiry": "Tipo: {{PLURAL:$1|1=expiração|2=lista de expirações}}.\n\nPode ser relativo (p.ex. <kbd>5 months</kbd> ou <kbd>2 weeks</kbd>) ou absoluto (p.ex. <kbd>2014-09-18T12:34:56Z</kbd>). Para não haver expiração, usar $2.", "paramvalidator-help-type-float": "Tipo: {{PLURAL:$1|1=flutuante|2=lista de flutuantes}}", "paramvalidator-help-type-integer": "Tipo: {{PLURAL:$1|1=inteiro|2=lista de inteiros}}", "paramvalidator-help-type-limit": "Tipo: número inteiro ou \"max\"", "paramvalidator-help-type-number-max": "{{PLURAL:$1|1=O valor não pode ser maior|2=Os valores não podem ser maiores}} que $3.", "paramvalidator-help-type-number-minmax": "{{PLURAL:$1|1=O valor deve estar entre|2=Os valores devem estar entre}} $2 e $3.", "paramvalidator-help-type-number-min": "{{PLURAL:$1|1=O valor não pode ser inferior a|2=Os valores não podem ser inferiores a}} $2.", "paramvalidator-help-type-presenceboolean": "Tipo: booleano", "paramvalidator-help-type-string-maxbytes": "Não pode exceder $1 {{PLURAL:$1|byte|bytes}}.", "paramvalidator-help-type-string-maxchars": "Não pode exceder $1 {{PLURAL:$1|carácter|caracteres}}.", "paramvalidator-help-type-timestamp": "Tipo: {{PLURAL:$1|1=carimbo de data/hora|2=lista de carimbo de data/hora}}", "paramvalidator-help-type-upload": "Deve ser postado como um upload de arquivo usando multipart/form-data." } PK ! b+��c c ParamValidator/i18n/ca.jsonnu �Iw�� { "@metadata": { "authors": [ "Fitoschido", "Mguix", "Toniher" ] }, "paramvalidator-badupload-partial": "S’ha pujat només parcialment el fitxer per a «$1».", "paramvalidator-emptystring": "la cadena buida", "paramvalidator-missingparam": "Cal definir el paràmetre «$1».", "paramvalidator-param-deprecated": "El paràmetre «$1» és obsolet.", "paramvalidator-help-default": "Per defecte: $1", "paramvalidator-help-default-empty": "Per defecte: (buit)", "paramvalidator-help-deprecated": "El paràmetre és obsolet.", "paramvalidator-help-multi-max-simple": "El nombre màxim de valors és {{PLURAL:$1|$1}}.", "paramvalidator-help-multi-all": "Per a especificar tots els valors, feu servir <kbd>$1</kbd>.", "paramvalidator-help-required": "Cal aquest paràmetre.", "paramvalidator-help-type-boolean": "Tipus: {{PLURAL:$1|1=booleà|2=llista de booleans}}", "paramvalidator-help-type-enum-can-be-empty": "{{PLURAL:$2|0=Cal que sigui buit|Pot ser buit o $1}}", "paramvalidator-help-type-integer": "Tipus: {{PLURAL:$1|1=enter|2=llista d'enters}}", "paramvalidator-help-type-limit": "Type: enter o «max»", "paramvalidator-help-type-number-max": "{{PLURAL:$1|1=El valor no ha|2=Els valors no han}} de ser més gran que $3.", "paramvalidator-help-type-presenceboolean": "Tipus: booleà", "paramvalidator-help-type-string-maxbytes": "No pot tenir més {{PLURAL:$1|d'$1 byte|de $1 bytes}}.", "paramvalidator-help-type-string-maxchars": "No pot tenir més {{PLURAL:$1|d'$1 caràcter|de $1 caràcters}}.", "paramvalidator-help-type-timestamp": "Tipus: {{PLURAL:$1|1=datació|2=llista de datacions}}" } PK ! FO�i i ParamValidator/i18n/zh-hans.jsonnu �Iw�� { "@metadata": { "authors": [ "Diskdance", "Func", "LittlePaw365", "沈澄心" ] }, "paramvalidator-badbool": "布尔类型参数\"$1\"的值\"$2\"无效。传递 $3 为真，或 $5 为假。", "paramvalidator-badbool-type": "布尔参数“$1”的值“$2”无效。实际取到的值为$3。", "paramvalidator-badexpiry": "日期类型参数\"$1\"的值\"$2\"无效。", "paramvalidator-badexpiry-duration": "提供给参数<var>$1</var>的值\"$2\"超过了最大值\"$3\"。", "paramvalidator-badexpiry-duration-max": "提供给参数<var>$1</var>的值\"$2\"超过了最大值\"$3\"。使用最大值代替。", "paramvalidator-badexpiry-past": "期限参数“$1”的值“$2”位于过去。", "paramvalidator-badfloat": "浮点参数“$1”的值“$2”无效。", "paramvalidator-badfloat-type": "浮点参数“$1”的值“$2”无效。实际取到的值为$3。", "paramvalidator-badfloat-notfinite": "浮点参数“$1”的值“$2”太大或不是数字。", "paramvalidator-badinteger": "整数参数“$1”的值“$2”无效。", "paramvalidator-badinteger-type": "整数参数“$1”的值“$2”无效。实际取到的值为$3。", "paramvalidator-badinteger-fraction": "整数参数“$1”的值“$2”无效。实际取到的值为有小数的浮点数。", "paramvalidator-badtimestamp": "时间戳参数“$1”的值“$2”无效。", "paramvalidator-badupload-cantwrite": "由于服务器配置问题（写操作失败），提供给“$1”参数的文件无法被保存和处理。", "paramvalidator-badupload-formsize": "为“$1”上传的文件大小超过了客户端配置的最大值。", "paramvalidator-badupload-inisize": "为“$1”上传的文件大小超过了服务器配置的最大值$3。", "paramvalidator-badupload-nofile": "没有为上传参数“$1”提供文件。", "paramvalidator-badupload-notmpdir": "由于服务器配置问题（没有临时目录），提供给“$1”参数的文件无法被保存和处理。", "paramvalidator-badupload-notupload": "文件上传参数“$1”没有包含文件；确保为您的POST操作使用 multipart/form-data 类型，并将文件名包含在 Content-Disposition 标头中。", "paramvalidator-badupload-partial": "为“$1”上传的文件仅部分上传。", "paramvalidator-badupload-phpext": "一个PHP扩展阻止了\"$1\"文件的上传。", "paramvalidator-badvalue-enummulti": "参数\"$1\"的值\"$2\"无效。{{PLURAL:$4|只允许\"$3\"|允许的值有$3}}。", "paramvalidator-badvalue-enumnotmulti": "参数\"$1\"的值无法识别：$2。", "paramvalidator-deprecated-value": "参数\"$1\"的值\"$2\"已经被弃用。", "paramvalidator-emptystring": "空字符串", "paramvalidator-maxbytes": "参数“$1”的值不能超过$3{{PLURAL:$3|字节}}（提供了$4）。", "paramvalidator-maxchars": "参数“$1”的值不能超过$3{{PLURAL:$3|字符}}（提供了$4）。", "paramvalidator-missingparam": "\"$1\"参数必须被设置。", "paramvalidator-notmulti": "\"$1\"参数只接受单个值。U+001F多值分隔法只能用于支持多个值的参数。", "paramvalidator-multivalue-must-be-array": "多值参数“$1”必须以数组形式给出。", "paramvalidator-needstring": "参数“$1”仅接受字符串值，但取到的是$2", "paramvalidator-outofrange-max": "给参数\"$1\"的值\"$2\"必须不大于$4。", "paramvalidator-outofrange-minmax": "给参数\"$1\"的值\"$2\"必须介于$3和$4之间。", "paramvalidator-outofrange-min": "给参数\"$1\"的值\"$2\"必须不小于$3。", "paramvalidator-param-deprecated": "参数\"$1\"已被弃用。", "paramvalidator-toomanyvalues": "为参数\"$1\"提供了太多值。限制为$2。", "paramvalidator-unclearnowtimestamp": "为时间戳参数\"$1\"传递\"$2\"已被弃用。如因某些原因您需要明确指定当前时间而不在客户端计算，请使用\"now\"。", "paramvalidator-unrecognizedvalues": "参数\"$1\"有无法识别的{{PLURAL:$4|值}}：$3。", "paramvalidator-help-default": "默认：$1", "paramvalidator-help-default-empty": "默认：(空)", "paramvalidator-help-deprecated": "这个参数已被废弃。", "paramvalidator-help-multi-separate": "用\"|\"分隔值，或用U+001F作为列表前缀，并用U+001F分隔。", "paramvalidator-help-multi-max": "值的最大值为{{PLURAL:$1|$1}}（允许更高上限的客户端为{{PLURAL:$2|$2}}）。", "paramvalidator-help-multi-max-simple": "值的最大值为{{PLURAL:$1|$1}}。", "paramvalidator-help-multi-all": "要指定所有值，请使用<kbd>$1</kbd>。", "paramvalidator-help-required": "这个参数是必需的。", "paramvalidator-help-type-boolean": "类型：{{PLURAL:$1|1=布尔|2=布尔列表}}", "paramvalidator-help-type-enum-can-be-empty": "{{PLURAL:$2|0=必须为空|可以为空，或$1}}", "paramvalidator-help-type-enum": "{{PLURAL:$1|1=下列值之一|2=多个值（使用U+007C(管道符)分隔，或者用U+001F作为列表前缀，并用U+001F分隔）}}：$2", "paramvalidator-help-type-expiry": "类型：{{PLURAL:$1|1=期限|2=期限列表}}。\n\n可以为相对值（例如<kbd>5 months</kbd>或<kbd>2 weeks</kbd>）或者绝对值（例如<kbd>2014-09-18T12:34:56Z</kbd>）。如没有到期时间，使用$2。", "paramvalidator-help-type-float": "类型：{{PLURAL:$1|1=浮点数|2=浮点数列表}}", "paramvalidator-help-type-integer": "类型：{{PLURAL:$1|1=整数|2=整数列表}}", "paramvalidator-help-type-limit": "类型：整数或\"max\"", "paramvalidator-help-type-number-max": "{{PLURAL:$1|值}}必须不大于$3。", "paramvalidator-help-type-number-minmax": "{{PLURAL:$1|值}}必须介于$2和$3之间。", "paramvalidator-help-type-number-min": "{{PLURAL:$1|值}}必须不少于$2。", "paramvalidator-help-type-presenceboolean": "类型：布尔", "paramvalidator-help-type-string-maxbytes": "不能超过$1{{PLURAL:$1|字节}}。", "paramvalidator-help-type-string-maxchars": "不能超过$1个{{PLURAL:$1|字符}}。", "paramvalidator-help-type-timestamp": "类型：{{PLURAL:$1|1=时间戳|2=时间戳列表}}", "paramvalidator-help-type-upload": "必须使用POST方法及multipart/form-data作为文件上传。" } PK ! �R}H H ParamValidator/i18n/nl.jsonnu �Iw�� { "@metadata": { "authors": [ "McDutchie", "PonkoSasuke", "Robin van der Vliet", "Romaine" ] }, "paramvalidator-badbool": "Onbekende waarde “$2” voor de booleaanse parameter “$1”. Geef $3 door voor “true”, of $5 voor “false”.", "paramvalidator-badbool-type": "Onbekende waarde “$2” voor de booleaanse parameter “$1”. In plaats daarvan is een $3-waarde ontvangen.", "paramvalidator-badexpiry": "Ongeldige waarde \"$2\" voor vervaldatumparameter \"$1\".", "paramvalidator-badexpiry-duration": "De gegeven waarde “$2” voor parameter <var>$1</var> overschrijdt het maximum van “$3”.", "paramvalidator-badexpiry-duration-max": "De gegeven waarde “$2” voor parameter <var>$1</var> overschrijdt het maximum van “$3”. In plaats daarvan wordt het maximum gebruikt.", "paramvalidator-badexpiry-past": "Waarde \"$2\" voor vervaldatumparameter \"$1\" is in het verleden.", "paramvalidator-badfloat": "Ongeldige waarde “$2” voor de float-parameter “$1”.", "paramvalidator-badfloat-type": "Ongeldige waarde “$2” voor de float-parameter “$1”. In plaats daarvan is een “$3”-waarde ontvangen.", "paramvalidator-badfloat-notfinite": "De waarde “$2” voor de float-parameter “$1” is te groot of is geen getal.", "paramvalidator-badinteger": "Ongeldige waarde “$2” voor de geheel-getalparameter “$1”.", "paramvalidator-badinteger-type": "Ongeldige waarde “$2” voor de geheel-getalparameter “$1”. In plaats daarvan is een “$3”-waarde ontvangen.", "paramvalidator-badinteger-fraction": "Ongeldige waarde “$2” voor de geheel-getalparameter “$1”. In plaats daarvan is een float met een breukdeel ontvangen.", "paramvalidator-badtimestamp": "Ongeldige waarde “$2” voor tijdstipparameter “$1”.", "paramvalidator-badupload-cantwrite": "Het bestand voor “$1” kon niet worden opgeslagen voor verwerking vanwege een verkeerde configuratie van de server (schrijfbewerking mislukt).", "paramvalidator-badupload-formsize": "Het geüploade bestand voor “$1” overschrijdt het door de klant opgegeven maximum.", "paramvalidator-badupload-inisize": "Het geüploade bestand voor “$1” overschrijdt het servermaximum van $3.", "paramvalidator-badupload-nofile": "Er is geen bestand verstrekt voor uploadparameter “$1”.", "paramvalidator-badupload-notmpdir": "Het bestand voor “$1” kon niet worden opgeslagen voor verwerking vanwege een verkeerde serverconfiguratie (geen tijdelijke map).", "paramvalidator-badupload-notupload": "De bestandsuploadparameter “$1” is geen bestandsupload. Zorg ervoor dat u multipart/form-data gebruikt voor uw POST-verzoek en neem een bestandsnaam op in de header Content-Disposition.", "paramvalidator-badupload-partial": "Het bestand voor “$1” is slechts gedeeltelijk geüpload.", "paramvalidator-badupload-phpext": "Een PHP-extensie heeft het uploaden van het bestand voor “$1” verhinderd.", "paramvalidator-badvalue-enummulti": "Ongeldige waarde “$2” voor parameter “$1”. {{PLURAL:$4|Alleen “$3” is toegestaan.|De toegestane waarden zijn $3.}}", "paramvalidator-badvalue-enumnotmulti": "Onbekende waarde voor parameter “$1”: $2.", "paramvalidator-deprecated-value": "De waarde “$2” is verouderd voor parameter “$1”.", "paramvalidator-emptystring": "de lege tekenreeks", "paramvalidator-maxbytes": "De waarde voor parameter “$1” kan niet langer zijn dan $3 {{PLURAL:$3| byte|bytes}} (was $4).", "paramvalidator-maxchars": "De waarde voor parameter “$1” kan niet langer zijn dan $3 {{PLURAL:$3| teken|tekens}} (was $4).", "paramvalidator-missingparam": "De parameter “$1” moet worden gedefinieerd.", "paramvalidator-notmulti": "De parameter “$1” accepteert slechts één waarde. Het waardescheidingsteken U+001F mag alleen worden gebruikt voor parameters met meerdere waarden.", "paramvalidator-multivalue-must-be-array": "De multi-waardeparameter “$1” moet als array worden opgegeven.", "paramvalidator-needstring": "De parameter “$1” accepteert alleen een tekenreekswaarde, maar kreeg $2", "paramvalidator-outofrange-max": "De waarde “$2” voor parameter “$1” mag niet groter zijn dan $4.", "paramvalidator-outofrange-minmax": "De waarde “$2” voor parameter “$1” moet tussen $3 en $4 liggen.", "paramvalidator-outofrange-min": "De waarde “$2” voor parameter “$1” mag niet kleiner zijn dan $3.", "paramvalidator-param-deprecated": "De parameter \"$1\" is verouderd.", "paramvalidator-toomanyvalues": "Er zijn te veel waarden opgegeven voor parameter \"$1\". De limiet is $2.", "paramvalidator-unclearnowtimestamp": "Het doorgeven van “$2” voor de tijdstip-parameter “$1” wordt afgeraden. Als het toch nodig is uitdrukkelijk de huidige tijd op te geven zonder deze aan de cliëntzijde te berekenen, gebruikt u “now”.", "paramvalidator-unrecognizedvalues": "Niet herkende {{PLURAL:$4|waarde|waarden}} voor parameter \"$1\": $3", "paramvalidator-help-default": "Standaard: $1", "paramvalidator-help-default-empty": "Standaard: (leeg)", "paramvalidator-help-deprecated": "Deze parameter is verouderd.", "paramvalidator-help-multi-separate": "Scheid de waarden met “|”, of plaats het voorvoegsel U+001F voor de lijst en scheid de waarden met U+001F.", "paramvalidator-help-multi-max": "Maximumaantal waarden is {{PLURAL:$1|$1}} (of {{PLURAL:$2|$2}} voor cliënten waaraan hogere limieten zijn toegestaan).", "paramvalidator-help-multi-max-simple": "Het maximale aantal waarden is {{PLURAL:$1|$1}}.", "paramvalidator-help-multi-all": "Gebruik <kbd>$1</kbd> om alle waarden op te geven.", "paramvalidator-help-required": "Deze parameter is vereist.", "paramvalidator-help-type-boolean": "Type: {{PLURAL:$1|1=booleaanse waarde|2=lijst met booleaanse waarden}}", "paramvalidator-help-type-enum-can-be-empty": "{{PLURAL:$2|0=Moet leeg zijn|Kan leeg zijn, of $1}}", "paramvalidator-help-type-enum": "{{PLURAL:$1|1=Een van de volgende waarden|2=Waarden (gescheiden met U+007C (sluisteken), of voeg vóór de lijst U+001F toe en scheid met U+001F)}}: $2", "paramvalidator-help-type-expiry": "Type: {{PLURAL:$1|1=vervaldatum|2=vervaldatalijst}}.\n\nKan relatief zijn (b.v. <kbd>5 maanden</kbd> of <kbd>2 weken</kbd>) of absoluut (e.g. <kbd>2014-09-18T12:34:56Z</kbd>). Is er geen vervaldatum, gebruik $2.", "paramvalidator-help-type-float": "Type: {{PLURAL:$1|1=zwevendekommagetal|2=lijst met zwevendekommagetalen}}", "paramvalidator-help-type-integer": "Type: {{PLURAL:$1|1=geheel getal|2=lijst met gehele getallen}}", "paramvalidator-help-type-limit": "Type: geheel getal of “max”", "paramvalidator-help-type-number-max": "De {{PLURAL:$1|1=waarde mag|2=waarden mogen}} niet groter zijn dan $3.", "paramvalidator-help-type-number-minmax": "De {{PLURAL:$1|1=waarde moet|2=waarden moeten}} tussen $2 en $3 liggen.", "paramvalidator-help-type-number-min": "De {{PLURAL:$1|1=waarde mag|2=waarden mogen}} niet kleiner zijn dan $2.", "paramvalidator-help-type-presenceboolean": "Type: booleaans", "paramvalidator-help-type-string-maxbytes": "Mag niet langer zijn dan $1 {{PLURAL:$1|byte|bytes}}.", "paramvalidator-help-type-string-maxchars": "Mag niet langer zijn dan $1 {{PLURAL:$1|teken|tekens}}.", "paramvalidator-help-type-timestamp": "Type: {{PLURAL:$1|1=tijdstip|2=lijst met tijdstippen}}", "paramvalidator-help-type-upload": "Moet worden gepost als een geüpload bestand met behulp van multipart/form-data." } PK ! I��f f ParamValidator/i18n/gl.jsonnu �Iw�� { "@metadata": { "authors": [ "Toliño" ] }, "paramvalidator-badbool": "O valor \"$2\" non é válido para o parámetro booleano \"$1\". Pase $3 para verdadeiro ou $5 para falso.", "paramvalidator-badbool-type": "O valor \"$2\" non é válido para o parámetro booleano \"$1\". Recibiuse un valor $3.", "paramvalidator-badexpiry": "O valor \"$2\" non é válido para o parámetro de caducidade \"$1\".", "paramvalidator-badexpiry-duration": "O valor \"$2\" dado para o parámetro <var>$1</var> supera o máximo de \"$3\".", "paramvalidator-badexpiry-duration-max": "O valor \"$2\" dado para o parámetro <var>$1</var> supera o máximo de \"$3\". Úsase o máximo no seu lugar.", "paramvalidator-badexpiry-past": "O valor \"$2\" para o parámetro de caducidade \"$1\" está no pasado.", "paramvalidator-badfloat": "O valor \"$2\" non é válido para o parámetro de número de coma flotante \"$1\".", "paramvalidator-badfloat-type": "O valor \"$2\" non é válido para o parámetro de número de coma flotante \"$1\". Recibiuse un valor $3.", "paramvalidator-badfloat-notfinite": "O valor \"$2\" para o parámetro de número de coma flotante \"$1\" é demasiado grande ou non é un número.", "paramvalidator-badinteger": "O valor \"$2\" non é válido para o parámetro de número enteiro \"$1\".", "paramvalidator-badinteger-type": "O valor \"$2\" non é válido para o parámetro de número enteiro \"$1\". Recibiuse un valor $3.", "paramvalidator-badinteger-fraction": "O valor \"$2\" non é válido para o parámetro de número enteiro \"$1\". Recibiuse un número de coma flotante cunha parte fraccionaria.", "paramvalidator-badtimestamp": "O valor \"$2\" non é válido para o parámetro de marca temporal \"$1\".", "paramvalidator-badupload-cantwrite": "O ficheiro para \"$1\" non se puido almacenar para o seu procesamento debido a unha configuración incorrecta do servidor (fallou a escritura).", "paramvalidator-badupload-formsize": "O ficheiro cargado para \"$1\" supera o máximo especificado polo cliente.", "paramvalidator-badupload-inisize": "O ficheiro cargado para \"$1\" supera o máximo do servidor de $3.", "paramvalidator-badupload-nofile": "Non se proporcionou ningún ficheiro para o parámetro de carga \"$1\".", "paramvalidator-badupload-notmpdir": "O ficheiro para \"$1\" non se puido almacenar para o seu procesamento debido a unha configuración incorrecta do servidor (non hai ningún directorio temporal).", "paramvalidator-badupload-notupload": "O parámetro de subida de ficheiros \"$1\" non é unha subida de ficheiros; asegúrese de usar multipart/form-data para a súa petición POST e de incluír un nome de ficheiro na cabeceira Content-Disposition.", "paramvalidator-badupload-partial": "O ficheiro para \"$1\" só se subiu parcialmente.", "paramvalidator-badupload-phpext": "Unha extensión de PHP impediu a carga do ficheiro para \"$1\".", "paramvalidator-badvalue-enummulti": "O valor \"$2\" non é válido para o parámetro \"$1\". {{PLURAL:$4|Só se permite \"$3\".|Os valores permitidos son: $3.}}", "paramvalidator-badvalue-enumnotmulti": "Valor non recoñecido para o parámetro \"$1\": $2.", "paramvalidator-deprecated-value": "O valor \"$2\" para o parámetro \"$1\" está obsoleto.", "paramvalidator-emptystring": "a cadea baleira", "paramvalidator-maxbytes": "O valor para o parámetro \"$1\" non pode superar $3 {{PLURAL:$3|byte|bytes}} (era $4).", "paramvalidator-maxchars": "O valor para o parámetro \"$1\" non pode superar $3 {{PLURAL:$3|carácter|caracteres}} (era $4).", "paramvalidator-missingparam": "Cómpre establecer o parámetro \"$1\".", "paramvalidator-notmulti": "O parámetro \"$1\" só acepta un único valor. A separación de valor múltiple U+001F só se pode utilizar para parámetros de valor múltiple.", "paramvalidator-multivalue-must-be-array": "O parámetro de valor múltiple \"$1\" debe especificarse en forma de matriz.", "paramvalidator-needstring": "O parámetro \"$1\" só acepta un valor de cadea de caracteres, pero recibiu un valor de tipo $2", "paramvalidator-outofrange-max": "O valor \"$2\" para o parámetro \"$1\" non debe ser superior a $4.", "paramvalidator-outofrange-minmax": "O valor \"$2\" para o parámetro \"$1\" debe estar entre $3 e $4.", "paramvalidator-outofrange-min": "O valor \"$2\" para o parámetro \"$1\" non debe ser inferior a $3.", "paramvalidator-param-deprecated": "O parámetro \"$1\" está obsoleto.", "paramvalidator-toomanyvalues": "Demasiados valores para o parámetro \"$1\". O límite é $2.", "paramvalidator-unclearnowtimestamp": "Pasar \"$2\" para o parámetro de marca temporal \"$1\" está obsoleto. Se, por algún motivo, precisa especificar explicitamente a hora actual sen calculala no lado do cliente, use \"now\".", "paramvalidator-unrecognizedvalues": "{{PLURAL:$4|Valor non recoñecido|Valores non recoñecidos}} para o parámetro \"$1\": $3", "paramvalidator-help-default": "Por defecto: $1", "paramvalidator-help-default-empty": "Por defecto: (baleiro)", "paramvalidator-help-deprecated": "Este parámetro está obsoleto.", "paramvalidator-help-multi-separate": "Separe os valores con \"|\" ou inclúa un prefixo na lista con U+001F e separe con U+001F.", "paramvalidator-help-multi-max": "O número máximo de valores é {{PLURAL:$1|$1}} ({{PLURAL:$2|$2}} para os clientes aos que se lles permiten límites máis altos).", "paramvalidator-help-multi-max-simple": "O número máximo de valores é {{PLURAL:$1|$1}}.", "paramvalidator-help-multi-all": "Para especificar todos os valores, use <kbd>$1</kbd>.", "paramvalidator-help-required": "Este parámetro é obrigatorio.", "paramvalidator-help-type-boolean": "Tipo: {{PLURAL:$1|1=booleano|2=lista de booleanos}}", "paramvalidator-help-type-enum-can-be-empty": "{{PLURAL:$2|0=Debe estar baleiro|Pode estar baleiro ou ser $1}}", "paramvalidator-help-type-enum": "{{PLURAL:$1|1=Un dos seguintes valores|2=Valores (separar con U+007C (barra vertical) ou incluír un prefixo na lista con U+001F e separar con U+001F)}}: $2", "paramvalidator-help-type-expiry": "Tipo: {{PLURAL:$1|1=caducidade|2=lista de caducidades}}.\n\nPode ser un tempo relativo (por exemplo, <kbd>5 months</kbd> ou <kbd>2 weeks</kbd>) ou absoluto (por exemplo, <kbd>2014-09-18T12:34:56Z</kbd>). Para que non caduque, use $2.", "paramvalidator-help-type-float": "Tipo: {{PLURAL:$1|1=número|2=lista de números}} de coma flotante", "paramvalidator-help-type-integer": "Tipo: {{PLURAL:$1|1=número enteiro|2=lista de números enteiros}}", "paramvalidator-help-type-limit": "Tipo: número enteiro ou \"max\"", "paramvalidator-help-type-number-max": "{{PLURAL:$1|1=O valor|2=Os valores}} non {{PLURAL:$1|debe|deben}} ser {{PLURAL:$1|superior|superiores}} a $3.", "paramvalidator-help-type-number-minmax": "{{PLURAL:$1|1=O valor debe|2=Os valores deben}} estar entre $2 e $3.", "paramvalidator-help-type-number-min": "{{PLURAL:$1|1=O valor|2=Os valores}} non {{PLURAL:$1|debe|deben}} ser {{PLURAL:$1|inferior|inferiores}} a $2.", "paramvalidator-help-type-presenceboolean": "Tipo: booleano", "paramvalidator-help-type-string-maxbytes": "Non pode superar $1 {{PLURAL:$1|byte|bytes}}.", "paramvalidator-help-type-string-maxchars": "Non pode superar $1 {{PLURAL:$1|carácter|caracteres}}.", "paramvalidator-help-type-timestamp": "Tipo: {{PLURAL:$1|1=marca temporal|2=lista de marcas temporales}}", "paramvalidator-help-type-upload": "Debe enviarse como unha carga de ficheiros utilizando multipart/form-data." } PK ! ʚM�� � ParamValidator/i18n/he.jsonnu �Iw�� { "@metadata": { "authors": [ "Amire80", "ערן" ] }, "paramvalidator-badbool": "ערך בלתי־תקין \"$2\" עבור פרמטר הבוליאני \"$1\". יש להעביר $3 בשביל אמת, או $5 בשביל שקר.", "paramvalidator-badbool-type": "ערך בלתי־תקין \"$2\" לפרמטר בוליאני \"$1\". הגיע ערך של $3 במקום זאת.", "paramvalidator-badexpiry": "ערך בלתי־תקין \"$2\" עבור פרמטר התפוגה \"$1\".", "paramvalidator-badexpiry-duration": "הערך \"$2\" שניתן לפרמטר <var>$1</var> עובר את הערך המרבי של \"$3\".", "paramvalidator-badexpiry-duration-max": "הערך \"$2\" שניתן לפרמטר <var>$1</var> עובר את הערך המרבי של \"$3\". הערך המרבי ישמש במקומו.", "paramvalidator-badexpiry-past": "הערך \"$2\" עבור פרמטר התפוגה \"$1\" בעבר.", "paramvalidator-badfloat": "ערך בלתי־תקין \"$2\" עבור פרמטר הנקודה הצפה \"$1\".", "paramvalidator-badfloat-type": "ערך בלתי־תקין \"$2\" לפרמטר נקודה צפה \"$1\". הגיע ערך של $3 במקום זאת.", "paramvalidator-badfloat-notfinite": "הערך \"$2\" עבור פרמטר הנקודה הצפה \"$1\" גדול מדי או שאינו מספר.", "paramvalidator-badinteger": "ערך בלתי־תקין \"$2\" עבור פרמטר המספר השלם \"$1\".", "paramvalidator-badinteger-type": "ערך בלתי־תקין \"$2\" לפרמטר מספר שלם \"$1\". הגיע ערך של $3 במקום זאת.", "paramvalidator-badinteger-fraction": "ערך בלתי־תקין \"$2\" לפרמטר מספר שלם \"$1\". הגיע ערך עם חלק השבר במקום זאת.", "paramvalidator-badtimestamp": "ערך בלתי־תקין \"$2\" עבור פרמטר חותם־הזמן \"$1\".", "paramvalidator-badupload-cantwrite": "לא היה אפשר לאחסן את הקובץ עבור \"$1\" לעיבוד בשל הגדרות שגויות בשרת (כישלון בכתיבה).", "paramvalidator-badupload-formsize": "הקובץ שהועלה עבור \"$1\" חורג מהערך המרבי שהגדיר הלקוח.", "paramvalidator-badupload-inisize": "הקובץ שהועלה עבור \"$1\" חורג מהערך המרבי של השרת $3.", "paramvalidator-badupload-nofile": "לא סופק קובץ עבור פרמטר ההעלאה \"$1\".", "paramvalidator-badupload-notmpdir": "לא היה אפשר לאחסן את הקובץ עבור \"$1\" לעיבוד בשל הגדרות שגויות בשרת (אין תיקייה זמנית).", "paramvalidator-badupload-notupload": "פרמטר העלאת הקובץ \"$1\" הוא לא העלאת קובץ; יש להקפיד להשתמש ב־multipart/form-data בשביל בקשת ה־POST שלך ולכלול שם קובץ בכותר Content-Disposition.", "paramvalidator-badupload-partial": "הקובץ עבור \"$1\" הועלה רק חלקית.", "paramvalidator-badupload-phpext": "הרחבת PHP מנעה את ההעלאה של הקובץ עבור \"$1\".", "paramvalidator-badvalue-enummulti": "ערך בלתי־תקין \"$2\" עבור פרמטר \"$1\". {{PLURAL:$4|מותר רק \"$3\".|הערכים המותרים הם $3.}}", "paramvalidator-badvalue-enumnotmulti": "לפרמטר \"$1\" יש ערך בלתי־מוכר: $2.", "paramvalidator-deprecated-value": "הערך \"$2\" עבור הפרמטר \"$1\" הוכרז כמיושן.", "paramvalidator-emptystring": "המחרוזת הריקה", "paramvalidator-maxbytes": "הערך עבור הפרמטר \"$1\" לא יכול להיות ארוך {{PLURAL:$3|מבית אחד|מ־$3 בתים}} (היה $4).", "paramvalidator-maxchars": "הערך עבור הפרמטר \"$1\" לא יכול להיות ארוך {{PLURAL:$3|מתו אחד|מ־$3 תווים}} (היה $4).", "paramvalidator-missingparam": "הפרמטר \"$1\" צריך להיות מוגדר.", "paramvalidator-notmulti": "הפרמטר \"$1\" מקבל רק ערך בודד. הפרדת ערכים מרובים ב־U+001F יכולה לשמש רק בפרמטרים מרובי־ערכים.", "paramvalidator-multivalue-must-be-array": "יש לתת את הפרמטר מרובה־הערכים \"$1\" כמערך.", "paramvalidator-needstring": "הפרמטר \"$1\" מקבל רק ערך מחרוזת, אבל הוא קיבל $2", "paramvalidator-outofrange-max": "הערך \"$2\" עבור הפרמטר \"$1\" לא יכול להיות גדול מ־$4.", "paramvalidator-outofrange-minmax": "הערך \"$2\" עבור הפרמטר \"$1\" צריך להיות בין $3 לבין $4.", "paramvalidator-outofrange-min": "הערך \"$2\" עבור הפרמטר \"$1\" לא יכול להיות קטן מ־$3.", "paramvalidator-param-deprecated": "הפרמטר \"$1\" הוכרז בתור מיושן.", "paramvalidator-toomanyvalues": "יותר מדי ערכים סופקו לפרמטר \"$1\". המגבלה היא $2.", "paramvalidator-unclearnowtimestamp": "העברת \"$2\" עבור פרמטר חותם־הזמן \"$1\" הוכרזה בתור מיושנת. אם מסיבה כלשהי נחוץ לך להגדיר במפורש את הזמן הנוכחי ללא חישובו בצד הלקוח, יש להשתמש ב־\"now\".", "paramvalidator-unrecognizedvalues": "{{PLURAL:$4|ערך בלתי־ידוע|ערכים בלתי־ידועים}} עבור הפרמטר \"$1\": $3.", "paramvalidator-help-default": "ברירת המחדל: $1", "paramvalidator-help-default-empty": "ברירת המחדל: (ריק)", "paramvalidator-help-deprecated": "הפרמטר הזה מיושן.", "paramvalidator-help-multi-separate": "יש להפריד ערכים באמצעות \"|\", או להתחיל את הרשימה ב־U+001F ולהפריד ב־U+001F.", "paramvalidator-help-multi-max": "המספר המרבי של ערכים הוא {{PLURAL:$1|$1}} (או {{PLURAL:$2|$2}} עבור לקוחות שמותרות להם מגבלות גבוהות יותר).", "paramvalidator-help-multi-max-simple": "המספר המרבי של הערכים הוא {{PLURAL:$1|$1}}.", "paramvalidator-help-multi-all": "כדי לתת את כל הערכים, יש להשתמש ב־<kbd>$1</kbd>.", "paramvalidator-help-required": "הפרמטר הזה נדרש.", "paramvalidator-help-type-boolean": "סוג: {{PLURAL:$1|1=בוליאני|2=רשימת בוליאנים}}", "paramvalidator-help-type-enum-can-be-empty": "{{PLURAL:$2|0=חייב להיות ריק|יכול להיות ריק, או $1}}", "paramvalidator-help-type-enum": "{{PLURAL:$1|1=אחד מהערכים הבאים|2=ערכים (מופרדים ב־U+007C (קו ניצב), או להתחיל את הרשימה ב־U+001F ולהפריד ב־U+001F)}}: $2", "paramvalidator-help-type-expiry": "סוג: {{PLURAL:$1|1=תפוגה|2=רשימת תפוגות}}.\n\nיכול להיות יחסי (למשל <kbd>5 months</kbd> או <kbd>2 weeks</kbd>) או מוחלט (למשל <kbd>2014-09-18T12:34:56Z</kbd>). לביטול התפוגה יש להשתמש בערך $2.", "paramvalidator-help-type-float": "סוג: {{PLURAL:$1|1=מספר עם נקודה צפה|2=רשימת מספרים עם נקודה צפה}}", "paramvalidator-help-type-integer": "סוג: {{PLURAL:$1|1=מספר שלם|2=רשימת מספרים שלמים}}", "paramvalidator-help-type-limit": "סוג: מספר שלם או \"max\"", "paramvalidator-help-type-number-max": "{{PLURAL:$1|1=הערך לא יכול להיות גדול|2=הערכים לא יכולים להיות גדולים}} מ־$3.", "paramvalidator-help-type-number-minmax": "{{PLURAL:$1|1=הערך חייב|2=הערכים חייבים}} להיות בין $2 ל־$3.", "paramvalidator-help-type-number-min": "{{PLURAL:$1|1=הערך לא יכול להיות קטן|2=הערכים לא יכולים להיות קטנים}} מ־$2.", "paramvalidator-help-type-presenceboolean": "סוג: בוליאני", "paramvalidator-help-type-string-maxbytes": "לא יכול להיות ארוך {{PLURAL:$1|מבית אחד|מ־$1 בתים}}.", "paramvalidator-help-type-string-maxchars": "לא יכול להיות ארוך {{PLURAL:$1|מתו אחד|מ־$1 תווים}}.", "paramvalidator-help-type-timestamp": "סוג: {{PLURAL:$1|1=חותם־זמן|2=רשימת חותמי־זמן}}", "paramvalidator-help-type-upload": "חייב להישלח (posted) בתור העלאת קובץ באמצעות multipart/form-data." } PK ! �X��G G ParamValidator/i18n/zh-hant.jsonnu �Iw�� { "@metadata": { "authors": [ "Kly", "Winston Sung", "捍粵者" ] }, "paramvalidator-badbool": "用於布林值參數「$1」的值「$2」無效。傳遞$3為 true，傳遞$5為 false。", "paramvalidator-badbool-type": "布林參數「$1」的值「$2」無效。實際取到的值為「$3」。", "paramvalidator-badexpiry": "用於逾期參數「$1」的值「$2」無效。", "paramvalidator-badexpiry-duration": "給予參數 <var>$1</var> 的值「$2」超過上限「$3」。", "paramvalidator-badexpiry-duration-max": "給予參數 <var>$1</var> 的值「$2」超過上限「$3」。使用最大值替代。", "paramvalidator-badexpiry-past": "用於逾期參數「$1」的值「$2」是過去的值。", "paramvalidator-badfloat": "用於浮點參數「$1」的值「$2」無效。", "paramvalidator-badfloat-type": "浮點參數「$1」的值「$2」無效。實際取到的值為「$3」。", "paramvalidator-badfloat-notfinite": "用於浮點參數「$1」的值「$2」太大或不是數字。", "paramvalidator-badinteger": "用於整數參數「$1」的值「$2」無效。", "paramvalidator-badinteger-type": "整數參數「$1」的值「$2」無效。實際取到的值為「$3」。", "paramvalidator-badinteger-fraction": "整數參數「$1」的值「$2」無效。實際取到的值為有小數的浮點數。", "paramvalidator-badtimestamp": "用於時間戳記參數「$1」的值「$2」。", "paramvalidator-badupload-cantwrite": "出於伺服器設置錯誤（寫入失敗），無法處理「$1」的檔案儲存。", "paramvalidator-badupload-formsize": "用於「$1」的上傳檔案超出客戶端指定的最大大小。", "paramvalidator-badupload-inisize": "用於「$1」的上傳檔案超出伺服器允許的最大大小 $3。", "paramvalidator-badupload-nofile": "沒有提供用於上傳參數「$1」的檔案。", "paramvalidator-badupload-notmpdir": "出於伺服器設置錯誤（沒有臨時目錄），無法處理「$1」的檔案儲存。", "paramvalidator-badupload-notupload": "檔案上傳參數「$1」不是一個檔案上傳，請確定在您的 POST 有使用 multipart/form-data，並且在 Content-Disposition 標頭有包含檔案名稱。", "paramvalidator-badupload-partial": "用於「$1」的檔案只有部份被上傳。", "paramvalidator-badupload-phpext": "PHP 擴充功能禁止上傳用於「$1」的檔案。", "paramvalidator-badvalue-enummulti": "用於參數「$1」的值「$2」無效。{{PLURAL:$4|僅允許「$3」。|允許的值為$3。}}", "paramvalidator-badvalue-enumnotmulti": "無法識別參數「$1」的值：$2。", "paramvalidator-deprecated-value": "用於參數「$1」的值「$2」已棄用。", "paramvalidator-emptystring": "空字串", "paramvalidator-maxbytes": "用於參數「$1」的值不可大於 $3 {{PLURAL:$3|位元組}}（提供的為 $4 位元組）。", "paramvalidator-maxchars": "用於參數「$1」的值不可大於 $3 個{{PLURAL:$3|字元}}（提供的為 $4 個）。", "paramvalidator-missingparam": "「$1」參數必須被設定。", "paramvalidator-notmulti": "參數「$1」僅接受單一值。U+001F 區分的多個值僅能用在多項值參數。", "paramvalidator-multivalue-must-be-array": "多值參數「$1」必須是陣列。", "paramvalidator-needstring": "參數「$1」僅接受字串值，但取到的是$2。", "paramvalidator-outofrange-max": "用於參數「$1」的值「$2」不能大於 $4。", "paramvalidator-outofrange-minmax": "用於參數「$1」的值「$2」必須介於 $3 與 $4 之間。", "paramvalidator-outofrange-min": "用於參數「$1」的值「$2」不能小於 $3。", "paramvalidator-param-deprecated": "參數「$1」已棄用。", "paramvalidator-toomanyvalues": "替參數「$1」提供太多的值。限制為 $2。", "paramvalidator-unclearnowtimestamp": "傳遞給時間戳記參數「$1」的值「$2」已被棄用。若出於某些原因，您不需在客戶端計算來明確指定時間，請使用「now」。", "paramvalidator-unrecognizedvalues": "參數「$1」有無法識別的{{PLURAL:$4|值}}：$3。", "paramvalidator-help-default": "預設值：$1", "paramvalidator-help-default-empty": "預設值：（空白）", "paramvalidator-help-deprecated": "此參數已棄用。", "paramvalidator-help-multi-separate": "請用「|」來區分值，或是以 U+001F 作為列表字首並以 U+001F 區分。", "paramvalidator-help-multi-max": "值的最大數目為 {{PLURAL:$1|$1}}（用於客戶端允許的較高限制為 {{PLURAL:$2|$2}}）。", "paramvalidator-help-multi-max-simple": "值的最大數量為 {{PLURAL:$1|$1}}。", "paramvalidator-help-multi-all": "要指定所有值，請使用<kbd>$1</kbd>。", "paramvalidator-help-required": "此為必填參數。", "paramvalidator-help-type-boolean": "類型：{{PLURAL:$1|1=布林值|2=布林值列表}}", "paramvalidator-help-type-enum-can-be-empty": "{{PLURAL:$2|0=必須留空|可以留空，或是$1}}", "paramvalidator-help-type-enum": "{{PLURAL:$1|1=以下多個值其一|2=多個值（以 U+007C（豎線字元）區分，或是以 U+001F 作為列表字首並以 U+001F 區分。）}}：$2", "paramvalidator-help-type-expiry": "類型：{{PLURAL:$1|1=逾期|2=逾期列表}}。\n\n可以是相對時間（例如：<kbd>5 months</kbd> 或 <kbd>2 weeks</kbd>）或是絕對時間（例如：<kbd>2014-09-18T12:34:56Z</kbd>）。若要無期限，請使用 $2。", "paramvalidator-help-type-float": "類型：{{PLURAL:$1|1=布林值|2=浮點值列表}}", "paramvalidator-help-type-integer": "類型：{{PLURAL:$1|1=整數|2=整數列表}}", "paramvalidator-help-type-limit": "類型：整數或「max」", "paramvalidator-help-type-number-max": "{{PLURAL:$1|1=數值|2=數值}}不可大於 $3。", "paramvalidator-help-type-number-minmax": "{{PLURAL:$1|1=數值|2=數值}}必須在 $2 與 $3 之間。", "paramvalidator-help-type-number-min": "{{PLURAL:$1|1=數值|2=數值}}不可小於 $2。", "paramvalidator-help-type-presenceboolean": "類型：布林值", "paramvalidator-help-type-string-maxbytes": "不能超過 $1 {{PLURAL:$1|位元組|位元組}}。", "paramvalidator-help-type-string-maxchars": "不能長過$1{{PLURAL:$1|字元}}。", "paramvalidator-help-type-timestamp": "類型：{{PLURAL:$1|1=時間戳記|2=時間戳記列表}}", "paramvalidator-help-type-upload": "必須使用 multipart/form-data 以檔案上傳的方式傳送。" } PK ! �B&� � ParamValidator/i18n/es.jsonnu �Iw�� { "@metadata": { "authors": [ "Fitoschido", "Dgstranz" ] }, "paramvalidator-badvalue-enummulti": "Valor no válido «$2» para el parámetro «$1». {{PLURAL:$4|Solo se permite «$3».|Los valores permitidos son $3.}}", "paramvalidator-badvalue-enumnotmulti": "Valor no reconocido para el parámetro «$1»: $2.", "paramvalidator-deprecated-value": "El valor «$2» del parámetro «$1» está marcado como obsoleto.", "paramvalidator-emptystring": "la cadena vacía", "paramvalidator-maxbytes": "El valor del parámetro «$1» no puede ocupar más de $3 {{PLURAL:$3|byte|bytes}} (ocupa $4).", "paramvalidator-maxchars": "El valor del parámetro «$1» no puede ocupar más de $3 {{PLURAL:$3|carácter|caracteres}} (ocupa $4).", "paramvalidator-missingparam": "Se debe establecer el parámetro «$1».", "paramvalidator-notmulti": "El parámetro «$1» solo acepta un valor. La separación multivalor U+001F solo se pueden utilizar en parámetros multivaluados.", "paramvalidator-multivalue-must-be-array": "Se debe proporcionar el parámetro multivaluado «$1» en forma de matriz.", "paramvalidator-needstring": "El parámetro «$1» solo acepta un valor de tipo cadena, pero recibió $2", "paramvalidator-outofrange-max": "El valor «$2» del parámetro «$1» debe ser no mayor de $4.", "paramvalidator-outofrange-minmax": "El valor «$2» del parámetro «$1» debe estar entre $3 y $4.", "paramvalidator-outofrange-min": "El valor «$2» del parámetro «$1» debe ser no menor de $3.", "paramvalidator-param-deprecated": "El parámetro «$1» está marcado como obsoleto.", "paramvalidator-toomanyvalues": "Se proporcionaron demasiados valores para el parámetro «$1». El límite es $2.", "paramvalidator-unrecognizedvalues": "{{PLURAL:$4|Valor no reconocido|Valores no reconocidos}} para el parámetro «$1»: $3", "paramvalidator-help-default": "Predeterminado: $1", "paramvalidator-help-default-empty": "Predeterminado: (vacío)", "paramvalidator-help-deprecated": "Este parámetro está obsoleto.", "paramvalidator-help-multi-max": "El número máximo de valores es {{PLURAL:$1|$1}} ({{PLURAL:$2|$2}} para clientes con permiso para utilizar límites superiores).", "paramvalidator-help-multi-max-simple": "El número máximo de valores es {{PLURAL:$1|$1}}.", "paramvalidator-help-multi-all": "Para especificar todos los valores, utiliza <kbd>$1</kbd>.", "paramvalidator-help-required": "Este parámetro es obligatorio.", "paramvalidator-help-type-boolean": "Tipo: {{PLURAL:$1|1=booleano|2=lista de booleanos}}", "paramvalidator-help-type-float": "Tipo: {{PLURAL:$1|1=flotante|2=lista de flotantes}}", "paramvalidator-help-type-integer": "Tipo: {{PLURAL:$1|1=entero|2=lista de enteros}}", "paramvalidator-help-type-limit": "Tipo: entero o «max»", "paramvalidator-help-type-number-max": "{{PLURAL:$1|1=El valor debe ser no mayor|2=Los valores deben ser no mayores}} de $3.", "paramvalidator-help-type-number-minmax": "{{PLURAL:$1|1=El valor debe|2=Los valores deben}} estar entre $2 y $3.", "paramvalidator-help-type-number-min": "{{PLURAL:$1|1=El valor debe ser no menor|2=Los valores deben ser no menores}} de $2.", "paramvalidator-help-type-presenceboolean": "Tipo: booleano", "paramvalidator-help-type-string-maxbytes": "No puede ocupar más de $1 {{PLURAL:$1|byte|bytes}}.", "paramvalidator-help-type-string-maxchars": "No puede ocupar más de $1 {{PLURAL:$1|carácter|caracteres}}.", "paramvalidator-help-type-timestamp": "Tipo: {{PLURAL:$1|1=cronomarcador|2=lista de cronomarcadores}}" } PK ! ��#�E E ParamValidator/i18n/sl.jsonnu �Iw�� { "@metadata": { "authors": [ "Eleassar", "Mainframe98" ] }, "paramvalidator-badbool": "Neveljavna vrednost »$2« za booleanov parameter »$1«. Določite $3 za »res« ali »$5« za »ni res«.", "paramvalidator-badexpiry": "Neveljavna vrednost »$2« za parameter preteka »$1«.", "paramvalidator-badexpiry-duration": "Podana vrednost »$2« za parameter <var>$1</var> presega največjo dovoljeno vrednost »$3«.", "paramvalidator-badexpiry-duration-max": "Podana vrednost »$2« za parameter <var>$1</var> presega največjo dovoljeno vrednost »$3«. Uporabljena bo največja dovoljena vrednost.", "paramvalidator-badexpiry-past": "Vrednost »$2« za parameter preteka »$1« je v preteklosti.", "paramvalidator-badfloat": "Neveljavna vrednost »$2« za plavajoči parameter »$1«.", "paramvalidator-badfloat-notfinite": "Vrednost »$2« za plavajoči parameter »$1« je prevelika ali ni število.", "paramvalidator-badinteger": "Neveljavna vrednost »$2« za celošteviski parameter »$1«.", "paramvalidator-badtimestamp": "Neveljavna vrednost »$2« za parameter časovnega žiga »$1«.", "paramvalidator-badupload-cantwrite": "Datoteke za »$1« ni bilo mogoče shraniti za obdelavo zaradi napačne konfiguracije strežnika (zapisovanje ni uspelo).", "paramvalidator-badupload-formsize": "Naložena datoteka »$1« presega največjo vrednost, določeno za odjemalec.", "paramvalidator-badupload-inisize": "Naložena vrednost »$1« presega največjo za strežnik določeno vrednost $3.", "paramvalidator-badupload-nofile": "Za parameter nalaganja »$1« ni bila podana nobena datoteka.", "paramvalidator-badupload-notmpdir": "Datoteke za »$1« ni bilo mogoče shraniti za obdelavo zaradi napačne konfiguracije strežnika (ni začasne mape).", "paramvalidator-badupload-notupload": "Parameter nalaganja datoteke »$1« ni nalaganje datoteke; zagotovite, da je za POST uporabljen format »multipart/form-dadta« in v glavo »Content-Disposition« vključite ime datoteke.", "paramvalidator-badupload-partial": "Datoteka za »$1« se je naložila samo deloma.", "paramvalidator-badupload-phpext": "Neka PHP-razširitev je preprečila naložitev datoteke za »$1«.", "paramvalidator-badvalue-enummulti": "Neveljavna vrednost »$2« za parameter »$1«. {{PLURAL:$4|Dovoljena je samo vrednost »$3«|Dovoljene vrednosti so $3}}.", "paramvalidator-badvalue-enumnotmulti": "Neprepoznana vrednost za parameter »$1«: $2.", "paramvalidator-deprecated-value": "Vrednost »$2« za parameter »$1« je opuščena.", "paramvalidator-emptystring": "prazen niz", "paramvalidator-maxbytes": "Vrednost za parameter »$1« ne sme biti daljša od $3 {{PLURAL:$3|zloga|zlogov}} (bila je $4).", "paramvalidator-maxchars": "Vrednost za parameter »$1« ne sme biti daljša od $3 ({{PLURAL:$3|znaka|znakov}}) (bila je $4).", "paramvalidator-missingparam": "Parameter »$1« mora biti določen.", "paramvalidator-notmulti": "Parameter »$1« sprejma samo eno vrednost. Ločevanje z več vrednostmi U+001F se lahko uporablja samo za parametre z več vrednostmi.", "paramvalidator-outofrange-max": "Vrednost »$2« za parameter »$1« ne sme biti večja od $4.", "paramvalidator-outofrange-minmax": "Vrednost »$2« za parameter »$1« mora biti med $3 in $4.", "paramvalidator-outofrange-min": "Vrednost »$2« za parameter »$1« ne sme biti manjša od $3.", "paramvalidator-param-deprecated": "Parameter »$1« je opuščen.", "paramvalidator-toomanyvalues": "Za parameter »$1« je podanih preveč vrednosti. Omejitev je $2.", "paramvalidator-unclearnowtimestamp": "Posredovanje »$2« za parameter časovnega žiga »$1« je opuščena. Če mora iz nekega razloga izrecno določiti trenutni čas, ne da bi ga izračunali na strani odjemalca, uporabite »zdaj«.", "paramvalidator-unrecognizedvalues": "{{PLURAL:$4|Neprepoznana vrednost|Neprepoznani vrednosti|Neprepoznane vrednosti}} za parameter »$1«: $3", "paramvalidator-help-default": "Privzeto: $1", "paramvalidator-help-default-empty": "Privzeto (prazno)", "paramvalidator-help-deprecated": "Ta parameter je opuščen.", "paramvalidator-help-multi-separate": "Vrednosti ločite z »|« ali seznamu dodajte predpono U+001F in jih ločite z U+001F.", "paramvalidator-help-multi-max": "Največje število vrednosti je {{PLURAL:$1|$1}} ({{PLURAL:$2|$2}} za odjemalce z večjimi dovoljenimi omejitvami)", "paramvalidator-help-multi-max-simple": "Največje število vrednosti je {{PLURAL:$1|$1}}.", "paramvalidator-help-multi-all": "Za določitev vseh vrednosti uporabite <kbd>$1</kbd>.", "paramvalidator-help-required": "Ta parameter je obvezen.", "paramvalidator-help-type-boolean": "Vtipkajte: {{PLURAL:$1|1=Boolovo vrednost|2=seznam Boolovih vrednosti}}", "paramvalidator-help-type-enum-can-be-empty": "{{PLURAL:$2|0=Biti mora prazno|Lahko je prazno ali $1}}", "paramvalidator-help-type-enum": "{{PLURAL:$1|1=Ena od naslednjih vrednosti|2=Vrednosti (ločite z U+007C (navpičnico) ali seznamu doajte predpono U+001F in jih ločite z U+001F)}}: $2", "paramvalidator-help-type-expiry": "Vtipkajte: {{PLURAL:$1|1=pretek|2=seznam pretekov}}.\n\nLahko je relativen (npr. <kbd>5 months</kbd> ali <kbd>2 weeks</kbd>) ali absoluten (npr. <kbd>2014-09-18T12:34:56Z</kbd>). Če ne želite določiti preteka, uporabite $2.", "paramvalidator-help-type-float": "Vtipkajte {{PLURAL:$1|1=plavajoče število|seznam plavajočih števil}}", "paramvalidator-help-type-integer": "Vtipkajte: {{PLURAL:$1|1=celo število|2=seznam celih števil}}", "paramvalidator-help-type-limit": "Vtipkajte: celo število ali »max«", "paramvalidator-help-type-number-max": "{{PLURAL:$1|1=Vrednost ne sme biti večja|2=Vrednosti ne smejo biti večje}} od $3.", "paramvalidator-help-type-number-minmax": "{{PLURAL:$1|1=Vrednost mora|2=Vrednosti morajo}} biti med $2 in $3.", "paramvalidator-help-type-number-min": "The {{PLURAL:$1|1=Vrednost ne sme biti manjša|2=Vrednosti ne smejo biti manjše}} od $2.", "paramvalidator-help-type-presenceboolean": "Tip: bool", "paramvalidator-help-type-string-maxbytes": "Ne sme biti daljše od $1 {{PLURAL:$1|zloga|zlogov}}.", "paramvalidator-help-type-string-maxchars": "Ne sme biti daljše od $1 {{PLURAL:$1|znaka|znakov}}.", "paramvalidator-help-type-timestamp": "Vtipkajte: {{PLURAL:$1|1=časovni žig|2=seznam časovnih žigov}}", "paramvalidator-help-type-upload": "Posredovano mora biti kot naložena datoteka z »multipart/form-data«." } PK ! N�� � � ParamValidator/i18n/nb.jsonnu �Iw�� { "@metadata": { "authors": [ "Jon Harald Søby" ] }, "paramvalidator-badbool": "Ugyldig verdi «$2» for den boolske parameteren «$1». Send $3 for true eller $5 for false.", "paramvalidator-badbool-type": "Ugyldig verdi «$2» for den boolske parameteren «$1». Fikk en $3-verdi i stedet.", "paramvalidator-badexpiry": "Ugyldig verdi «$2» for utløpsparameteren «$1».", "paramvalidator-badexpiry-duration": "Den gitte verdien «$2» for parameteren <var>$1</var> overskrider maksimumen på «$3».", "paramvalidator-badexpiry-duration-max": "Den gitte verdien «$2» for parameteren <var>$1</var> overskrider maksimumen på «$3». Bruk maksimumen i stedet.", "paramvalidator-badexpiry-past": "Verdien «$2» for utløpsparameteren «$1» er i fortiden.", "paramvalidator-badfloat": "Ugyldig verdi «$2» for flyttallsparameteren «$1».", "paramvalidator-badfloat-type": "Ugyldig verdi «$2» for flyttallparameteren «$1». Fikk en $3-verdi i stedet.", "paramvalidator-badfloat-notfinite": "Verdien «$2» for flyttallsparameteren «$1» er for stor eller ikke et tall.", "paramvalidator-badinteger": "Ugyldig verdi «$2» for heltallsparameteren «$1».", "paramvalidator-badinteger-type": "Ugyldig verdi «$2» for heltallparameteren «$1». Fikk en $3-verdi i stedet.", "paramvalidator-badinteger-fraction": "Ugyldig verdi «$2» for heltallverdien «$1». Fikk et flyttall med desimaler i stedet.", "paramvalidator-badtimestamp": "Ugyldig verdi «$2» for tidsstempelparameteren «$1».", "paramvalidator-badupload-cantwrite": "Fila for «$1» kunne ikke lagres for prosessering på grunn av en feilkonfigurasjon i tjeneren (skriving mislyktes).", "paramvalidator-badupload-formsize": "Den opplastede fila for «$1» overskrider maksimalstørrelsen angitt i klienten.", "paramvalidator-badupload-inisize": "Den opplastede fila for «$1» overskriver tjeneres maksimalstørrelse $3.", "paramvalidator-badupload-nofile": "Ingen fil angitt for opplastingsparameteren «$1».", "paramvalidator-badupload-notmpdir": "Fila for «$1» kunne ikke lagres for prosessering på grunn av en feilkonfigurasjon i tjeneren (ingen midlertidig mappe).", "paramvalidator-badupload-notupload": "Filopplastingsparameteren «$1» er ikke en filopplasting; sørg for å bruke multipart/form-data for POST og inkluder et filnavn i Content-Disposition-headeren.", "paramvalidator-badupload-partial": "Fila for «$1» ble bare delvis lastet opp.", "paramvalidator-badupload-phpext": "En PHP-utvidelse forhindret opplastingen av fila for «$1».", "paramvalidator-badvalue-enummulti": "Ugyldig verdi «$2» for parameteren «$1». {{PLURAL:$4|Kun «$3» er tillatt.|Tillatte verdier er $3.}}", "paramvalidator-badvalue-enumnotmulti": "Ikke gjenkjent verdi for parameteren «$1»: $2.", "paramvalidator-deprecated-value": "Verdien «$2» for parameteren «$1» er udtatert.", "paramvalidator-emptystring": "den tomme strengen", "paramvalidator-maxbytes": "Verdien for parameteren «$1» kan ikke være lengre enn $3 {{PLURAL:$3|byte}} (var $4).", "paramvalidator-maxchars": "Verdien for parameteren «$1» kan ikke være lengre enn $3 {{PLURAL:$3|tegn}} (var $4).", "paramvalidator-missingparam": "Parameteren «$1» må være satt.", "paramvalidator-notmulti": "Parameteren «$1» godtar bare én enkel verdi. Flere verdier atskilt med U+001F kan bare brukes for parametere som kan ta flere verdier.", "paramvalidator-multivalue-must-be-array": "Flerverdiparameteren «$1» må gis som en array.", "paramvalidator-needstring": "Parameteren «$1» godtar kun strengverdier, men fikk $2", "paramvalidator-outofrange-max": "Verdien «$2» for parameteren «$1» kan ikke være større enn $4.", "paramvalidator-outofrange-minmax": "Verdien «$2» for parameteren «$1» må være mellom $3 og $4.", "paramvalidator-outofrange-min": "Verdien «$2» for parameteren «$1» kan ikke være mindre enn $3.", "paramvalidator-param-deprecated": "Parameteren «$1» har blitt foreldet.", "paramvalidator-toomanyvalues": "For mange verdier angitt for parameteren «$1». Grensa er $2.", "paramvalidator-unclearnowtimestamp": "Å sende «$2» for tidsstempelparameteren «$1» har blitt foreldet. Hvis du trenger å eksplisitt angi den nåværende tiden uten å regne den ut på klientsiden, bruk «now».", "paramvalidator-unrecognizedvalues": "Ikke {{PLURAL:$4|gjenkjent verdi|gjenkjente verdier}} for parameteren «$1»: $3", "paramvalidator-help-default": "Standard: $1", "paramvalidator-help-default-empty": "Stardard: (tom)", "paramvalidator-help-deprecated": "Denne parameteren er foreldet.", "paramvalidator-help-multi-separate": "Skill verdier fra hverandre med «|», eller begynn lista med U+001F og skill verdiene fra hverandre med U+001F.", "paramvalidator-help-multi-max": "Maksimalt antall verdier er {{PLURAL:$1|$1}} ({{PLURAL:$2|$2}} for klienter som er tillatt høyere grenser).", "paramvalidator-help-multi-max-simple": "Maksimalt antall verdier er {{PLURAL:$1|$1}}.", "paramvalidator-help-multi-all": "For å angi alle verdier, bruk <kbd>$1</kbd>.", "paramvalidator-help-required": "Denne parameteren er påkrevd.", "paramvalidator-help-type-boolean": "Type: {{PLURAL:$1|1=boolsk verdi|2=liste over boolske verdier}}", "paramvalidator-help-type-enum-can-be-empty": "{{PLURAL:$2|0=Må være tom|Kan være tom, eller $1}}", "paramvalidator-help-type-enum": "{{PLURAL:$1|1=Én av følgende verdier|2=Verdier (atskill med U+007C (vertikalstrek) eller bruk U+001F foran og atskill med U+001F)}}: $2", "paramvalidator-help-type-expiry": "Type: {{PLURAL:$1|1=utløp|2=liste over utløp}}.\n\nKan være relativ (f.eks. <kbd>5 months</kbd> eller <kbd>2 weeks</kbd>) eller absolutt (f.eks. <kbd>2014-09-18T12:34:56Z</kbd>). For ingen utløpsdato, bruk $2.", "paramvalidator-help-type-float": "Type: {{PLURAL:$1|1=flyttall|2=liste over flyttall}}", "paramvalidator-help-type-integer": "Type: {{PLURAL:$1|1=heltall|2=liste over heltall}}", "paramvalidator-help-type-limit": "Type: heltall eller «max»", "paramvalidator-help-type-number-max": "{{PLURAL:$1|1=Verdien|2=Verdiene}} kan ikke være større enn $3.", "paramvalidator-help-type-number-minmax": "{{PLURAL:$1|1=Verdien|2=Verdiene}} må være mellom $2 og $3.", "paramvalidator-help-type-number-min": "{{PLURAL:$1|1=Verdien|2=Verdiene}} kan ikke være lavere enn $2.", "paramvalidator-help-type-presenceboolean": "Type: boolsk", "paramvalidator-help-type-string-maxbytes": "Kan ikke være lengre enn $1 {{PLURAL:$1|byte}}.", "paramvalidator-help-type-string-maxchars": "Kan ikke være lengre enn $1 {{PLURAL:$1|tegn}}.", "paramvalidator-help-type-timestamp": "Type: {{PLURAL:$1|1=tidsstempel|liste over tidsstempler}}", "paramvalidator-help-type-upload": "Må postes som en filopplasting med multipart/form-data." } PK ! D�"� � ParamValidator/i18n/fa.jsonnu �Iw�� { "@metadata": { "authors": [ "Ebrahim", "Ebraminio", "FarsiNevis", "Jeeputer" ] }, "paramvalidator-badexpiry": "مقدار نامعتبر «$2» برای پارامتر انقضای «$1».", "paramvalidator-badinteger": "مقدار نامعتبر «$2» برای پارامتر صحیح «$1».", "paramvalidator-badvalue-enummulti": "مقدار نامعتبر «$2» برای پارامتر «$1». {{PLURAL:$4|فقط «$3» مجاز است.|مقادیر مجاز عبارتاند از $3.}}", "paramvalidator-deprecated-value": "مقدار «$2» برای پارامتر «$1» منسوخ شده است.", "paramvalidator-maxbytes": "مقدار پارامتر «$1» نمیتواند طولانیتر از $3 {{PLURAL:$3|بایت}} باشد ($4 بود).", "paramvalidator-missingparam": "پارامتر «$1» باید تعیین شود.", "paramvalidator-outofrange-max": "مقدار «$2» برای پارامتر «$1» نباید بزرگتر از $4 باشد.", "paramvalidator-outofrange-min": "مقدار «$2» برای پارامتر «$1» نباید کوچکتر از $3 باشد.", "paramvalidator-help-default": "پیشفرض: $1", "paramvalidator-help-multi-max": "حداکثر تعداد مقدارها {{PLURAL:$1|$1}} است ({{PLURAL:$2|$2}} برای متقضایانی که مجوز محدودیتهای بالاتر را دارند).", "paramvalidator-help-required": "این پارامتر الزامی است.", "paramvalidator-help-type-boolean": "نوع: {{PLURAL:$1|1=بولی|2=فهرستی از بولیها}}", "paramvalidator-help-type-expiry": "نوع: {{PLURAL:$1|1=انقضا|۲=فهرستی از انقضاها}}.\n\nمیتواند نسبی (برای مثال <kbd>5 months</kbd> یا <kbd>2 weeks</kbd>) یا دقیق (برای مثال <kbd>2014-09-18T12:34:56Z</kbd>) باشد. برای انقضای نامعین از $2 استفاده کنید.", "paramvalidator-help-type-integer": "نوع: {{PLURAL:$1|1=عدد صحیح|2=فهرستی از اعداد صحیح}}", "paramvalidator-help-type-number-max": "{{PLURAL:$1|1=مقدار|2=مقادیر}} نباید بزرگتر از $3 {{PLURAL:$1|1=باشد|2=باشند}}.", "paramvalidator-help-type-presenceboolean": "نوع: بولی", "paramvalidator-help-type-string-maxbytes": "نباید بیشتر از $1 بایت باشد.", "paramvalidator-help-type-timestamp": "نوع: {{PLURAL:$1|1=برچسب زمان|2=فهرستی از برچسبهای زمان}}" } PK ! b=�� � ParamValidator/i18n/ur.jsonnu �Iw�� { "@metadata": { "authors": [ "Muhammad Shuaib" ] }, "paramvalidator-help-default": "طے شدہ: $1", "paramvalidator-help-default-empty": "طے شدہ: (خالی)", "paramvalidator-help-deprecated": "یہ پیرامیٹر اب متروک ہے۔", "paramvalidator-help-multi-all": "تمام قدروں کی تعیین کے لیے <kbd>$1</kbd> کا استعمال کریں۔", "paramvalidator-help-required": "یہ پیرامیٹر لازمی ہے۔", "paramvalidator-help-type-boolean": "طرز: {{PLURAL:$1|1=بولین|2=بولین کی فہرست}}", "paramvalidator-help-type-enum": "{{PLURAL:$1| 1 = ذیل کی قدروں میں سے کوئی ایک | 2 = قدریں (جنھیں U + 007C (پائپ) سے علاحدہ کیا گیا ہے، یا فہرست کو U + 001F سے شروع کریں اور U + 001F)}} سے علاحدہ کریں: $2", "paramvalidator-help-type-limit": "طرز: عدد صحیح یا \"max\"", "paramvalidator-help-type-presenceboolean": "طرز: بولین", "paramvalidator-help-type-string-maxbytes": "$1 {{PLURAL:$1|بائٹ}} سے زیادہ نہیں ہو سکتا۔", "paramvalidator-help-type-timestamp": "طرز: {{PLURAL:$1|1=مہر وقت|2=وقت کے مہر کی فہرست}}" } PK ! E[ �u! u! ParamValidator/i18n/ar.jsonnu �Iw�� { "@metadata": { "authors": [ "Meno25" ] }, "paramvalidator-badbool": "قيمة غير صالحة \" $2 \" للمعامل المنطقي \" $1 \". مرر $3 للصواب أو $5 للخطأ.", "paramvalidator-badbool-type": "قيمة غير صالحة \"$2\" للمعلمة المنطقية \"$1\". حصلت على قيمة $3 بدلاً من ذلك.", "paramvalidator-badexpiry": "قيمة غير صالحة \" $2 \" لمعامل انتهاء الصلاحية \" $1 \".", "paramvalidator-badexpiry-duration": "القيمة المقدمة \" $2 \" للمعلمة <var>$1</var> تتجاوز الحد الأقصى وهو \" $3 \".", "paramvalidator-badexpiry-duration-max": "القيمة المقدمة \" $2 \" للمعلمة <var>$1</var> تتجاوز الحد الأقصى وهو \" $3 \". باستخدام الحد الأقصى بدلاً من ذلك.", "paramvalidator-badexpiry-past": "قيمة \" $2 \" لمعامل انتهاء الصلاحية \" $1 \" في الماضي.", "paramvalidator-badfloat": "قيمة غير صحيحة \" $2 \" لمعامل الطفو \" $1 \".", "paramvalidator-badfloat-type": "قيمة غير صالحة \"$2\" لمعلمة التعويم \"$1\". حصلت على قيمة $3 بدلاً من ذلك.", "paramvalidator-badfloat-notfinite": "القيمة \" $2 \" للمعامل العائم \" $1 \" كبيرة جدًا أو ليست رقمًا.", "paramvalidator-badinteger": "قيمة غير صالحة \" $2 \" للمعامل الصحيح \" $1 \".", "paramvalidator-badinteger-type": "قيمة غير صالحة \"$2\" لمعلمة العدد الصحيح \"$1\". حصلت على قيمة $3 بدلاً من ذلك.", "paramvalidator-badinteger-fraction": "قيمة غير صالحة \"$2\" لمعلمة العدد الصحيح \"$1\". حصلت على عدد عشري بجزء كسري بدلاً من ذلك.", "paramvalidator-badtimestamp": "قيمة غير صالحة \" $2 \" لمعلمة الطابع الزمني \" $1 \".", "paramvalidator-badupload-cantwrite": "تعذر تخزين ملف \" $1 \" للمعالجة بسبب خطأ في تكوين الخادم (فشلت الكتابة).", "paramvalidator-badupload-formsize": "الملف الذي تم تحميله لـ \" $1 \" يتجاوز الحد الأقصى المحدد من قبل العميل.", "paramvalidator-badupload-inisize": "يتجاوز الملف الذي تم تحميله لـ \" $1 \" الحد الأقصى للخادم وهو $3 .", "paramvalidator-badupload-nofile": "لم يتم توفير ملف لمعلمة التحميل \" $1 \".", "paramvalidator-badupload-notmpdir": "تعذر تخزين ملف \" $1 \" للمعالجة بسبب خطأ في تكوين الخادم (لا يوجد دليل مؤقت).", "paramvalidator-badupload-notupload": "معلمة تحميل الملف \" $1 \" ليست تحميل ملف ؛ تأكد من استخدام بيانات نموذجية / متعددة الأجزاء لـ POST وتضمين اسم ملف في عنوان Content-Disposition.", "paramvalidator-badupload-partial": "تم تحميل ملف \" $1 \" جزئيًا فقط.", "paramvalidator-badupload-phpext": "منع امتداد PHP تحميل ملف \" $1 \".", "paramvalidator-badvalue-enummulti": "قيمة غير صالحة \" $2 \" للمعلمة \" $1 \". {{PLURAL:$4| مسموح فقط بـ \" $3 \". | القيم المسموح بها هي $3 }}", "paramvalidator-badvalue-enumnotmulti": "قيمة غير معروفة للمعامل \" $1 \": $2 .", "paramvalidator-deprecated-value": "تم إهمال القيمة \" $2 \" للمعلمة \" $1 \".", "paramvalidator-emptystring": "السلسلة الفارغة", "paramvalidator-maxbytes": "لا يمكن أن تكون قيمة المعلمة \" $1 \" أطول من $3 {{PLURAL:$3| بايت | بايت}} (كان $4 ).", "paramvalidator-maxchars": "لا يمكن أن تكون قيمة المعلمة \" $1 \" أطول من $3 {{PLURAL:$3| حرف | محارف}} (كان $4 ).", "paramvalidator-missingparam": "يجب تعيين المعلمة \" $1 \".", "paramvalidator-notmulti": "تقبل المعلمة \" $1 \" قيمة واحدة فقط. لا يجوز استخدام الفصل متعدد القيم U + 001F إلا للمعلمات متعددة القيم.", "paramvalidator-multivalue-must-be-array": "يجب تقديم المعلمة متعددة القيم \"$1\" كمصفوفة.", "paramvalidator-needstring": "يقبل المعامل \"$1\" قيمة سلسلة فقط، ولكن تم الحصول على $2", "paramvalidator-outofrange-max": "يجب ألا تزيد قيمة \" $2 \" للمعلمة \" $1 \" عن $4 .", "paramvalidator-outofrange-minmax": "يجب أن تتراوح قيمة \" $2 \" للمعلمة \" $1 \" بين $3 $4 .", "paramvalidator-outofrange-min": "يجب ألا تقل القيمة \" $2 \" للمعامل \" $1 \" عن $3 .", "paramvalidator-param-deprecated": "تم إهمال المعلمة \" $1 \".", "paramvalidator-toomanyvalues": "تم توفير عدد كبير جدًا من القيم للمعامل \" $1 \". الحد هو $2 .", "paramvalidator-unclearnowtimestamp": "تم إهمال تمرير \" $2 \" لمعلمة الطابع الزمني \" $1 \". إذا احتجت لسبب ما إلى تحديد الوقت الحالي صراحةً دون حسابه من جانب العميل ، فاستخدم \"الآن\".", "paramvalidator-unrecognizedvalues": "غير معروف {{PLURAL:$4| القيمة | القيم}} للمعلمة \" $1 \": $3", "paramvalidator-help-default": "الافتراضي: $1", "paramvalidator-help-default-empty": "الافتراضي: (فارغ)", "paramvalidator-help-deprecated": "تم إهمال هذه المعلمة.", "paramvalidator-help-multi-separate": "افصل القيم بـ \"|\" ، أو ابدأ القائمة بـ U + 001F وافصل بينها بـ U + 001F.", "paramvalidator-help-multi-max": "الحد الأقصى لعدد القيم هو {{PLURAL:$1|$1}} ({{PLURAL:$2|$2}} للعملاء المسموح لهم بحدود أعلى).", "paramvalidator-help-multi-max-simple": "الحد الأقصى لعدد القيم هو {{PLURAL:$1| $1 }}.", "paramvalidator-help-multi-all": "لتحديد كل القيم ، استخدم <kbd>$1</kbd> .", "paramvalidator-help-required": "هذه المعلمة مطلوبة.", "paramvalidator-help-type-boolean": "النوع: {{PLURAL:$1| 1 = منطقي | 2 = قائمة منطقية}}", "paramvalidator-help-type-enum-can-be-empty": "{{PLURAL:$2| 0 = يجب أن يكون فارغًا | يمكن أن يكون فارغًا ، أو $1 }}", "paramvalidator-help-type-enum": "{{PLURAL:$1| 1 = إحدى القيم التالية | 2 = القيم (منفصلة بـ U + 007C (أنبوب) ، أو ابدأ القائمة بـ U + 001F وافصل بـ U + 001F)}}: $2", "paramvalidator-help-type-expiry": "النوع: {{PLURAL:$1|1=انتهاء الصلاحية|2=قائمة انتهاء الصلاحية}}.\n\nقد تكون نسبية (على سبيل المثال <kbd>5 أشهر</kbd> أو <kbd>أسبوعين</kbd> ) أو مطلقة (على سبيل المثال <kbd>2014-09-18T12:34:56Z</kbd>). لعدم انتهاء الصلاحية ، استخدم $2.", "paramvalidator-help-type-float": "النوع: {{PLURAL:$1| 1 = float | 2 = قائمة العوامات}}", "paramvalidator-help-type-integer": "النوع: {{PLURAL:$1| 1 = عدد صحيح | 2 = قائمة الأعداد الصحيحة}}", "paramvalidator-help-type-limit": "النوع: عدد صحيح أو \"ماكس\"", "paramvalidator-help-type-number-max": "{{PLURAL:$1| 1 = القيمة | 2 = القيم}} يجب ألا تزيد عن $3 .", "paramvalidator-help-type-number-minmax": "{{PLURAL:$1| 1 = القيمة | 2 = القيم}} يجب أن تكون بين $2 $3 .", "paramvalidator-help-type-number-min": "{{PLURAL:$1| 1 = القيمة | 2 = القيم}} يجب ألا تقل عن $2 .", "paramvalidator-help-type-presenceboolean": "النوع: منطقي", "paramvalidator-help-type-string-maxbytes": "لا يمكن أن يكون أطول من $1 {{PLURAL:$1| بايت | بايت}}.", "paramvalidator-help-type-string-maxchars": "لا يمكن أن يكون أطول من $1 {{PLURAL:$1| حرف | أحرف}}.", "paramvalidator-help-type-timestamp": "النوع: {{PLURAL:$1| 1 = الطابع الزمني | 2 = قائمة الطوابع الزمنية}}", "paramvalidator-help-type-upload": "يجب نشرها كتحميل ملف باستخدام بيانات متعددة الأجزاء / النموذج." } PK ! ��k� � ParamValidator/i18n/pl.jsonnu �Iw�� { "@metadata": { "authors": [ "Msz2001", "Rail" ] }, "paramvalidator-badbool": "Niepoprawna wartość „$2” dla parametru „$1”, który jest typu boolowskiego. Użyj $3 jako „prawda” albo $5 jako „fałsz”.", "paramvalidator-badexpiry": "Niepoprawna wartość „$2” dla parametru „$1”, określającego czas wygaśnięcia.", "paramvalidator-badexpiry-duration": "Podana wartość „$2” dla parametru <var>$1</var> przekracza maksymalną ($3).", "paramvalidator-badexpiry-duration-max": "Podana wartość „$2” dla parametru <var>$1</var> przekracza maksymalną ($3). Użyta zostanie wartość maksymalna.", "paramvalidator-badexpiry-past": "Wartość „$2” dla parametru „$1”, określającego czas wygaśnięcia, jest w przeszłości.", "paramvalidator-badfloat": "Niepoprawna wartość „$2” dla parametru „$1” typu float.", "paramvalidator-badfloat-notfinite": "Wartość „$2” dla parametru „$1” typu float jest zbyt duża albo nie jest liczbą.", "paramvalidator-badinteger": "Niepoprawna wartość „$2” dla parametru „$1”, który jest typu całkowitoliczbowego.", "paramvalidator-badtimestamp": "Niepoprawna wartość „$2” dla parametru „$1”, który oczekuje znacznika czasu.", "paramvalidator-badupload-cantwrite": "Nie udało się skierować pliku „$1” do dalszego przetwarzania ze względu na błędną konfigurację serwera (błąd zapisu).", "paramvalidator-badupload-formsize": "Przesyłany plik „$1” przekracza maksymalny rozmiar określony przez klienta.", "paramvalidator-badupload-inisize": "Przesyłany plik „$1” przekracza maksymalny rozmiar określony przez serwer ($3).", "paramvalidator-badupload-nofile": "Nie został określony plik do przesłania dla parametru „$1”.", "paramvalidator-badupload-notmpdir": "Nie udało się skierować pliku „$1” do dalszego przetwarzania ze względu na błędną konfigurację serwera (brak katalogu do tymczasowego zapisu).", "paramvalidator-badupload-notupload": "Parametr „$1” nie określa pliku do przesłania. Upewnij się, że używasz typu zawartości „multipart/form-data” dla żądania POST oraz dołącz nazwę pliku w nagłówku Content-Disposition.", "paramvalidator-badupload-partial": "Plik „$1” został przesłany częściowo.", "paramvalidator-badupload-phpext": "Rozszerzenie PHP powstrzymało przesłanie pliku „$1”.", "paramvalidator-badvalue-enummulti": "Niepoprawna wartość „$2” dla parametru „$1”. {{PLURAL:$4|Dozwolona jest jedynie „$3”.|Dozwolone wartości to: $3.}}", "paramvalidator-badvalue-enumnotmulti": "Nierozpoznana wartość „$2” dla parametru „$1”.", "paramvalidator-deprecated-value": "Wartość „$2” dla parametru „$1” została uznana za przestarzałą.", "paramvalidator-emptystring": "pusty napis", "paramvalidator-maxbytes": "Wartość dla parametru „$1” nie może być dłuższa niż $3 {{PLURAL:$3|bajt|bajty|bajtów}} (podana ma rozmiar $4 {{PLURAL:$4|bajta|bajtów}}).", "paramvalidator-maxchars": "Wartość dla parametru „$1” nie może być dłuższa niż $3 {{PLURAL:$3|znak|znaki|znaków}} (podana ma {{PLURAL:$4|znak|znaki|znaków}}).", "paramvalidator-missingparam": "Parametr „$1” musi być ustawiony.", "paramvalidator-notmulti": "Parametr „$1” pozwala tylko na podanie pojedynczej wartości. Separator U+001F może być użyty jedynie dla parametrów akceptujących wiele wartości.", "paramvalidator-outofrange-max": "Wartość „$2” dla parametru „$1” nie może być większa niż $4.", "paramvalidator-outofrange-minmax": "Wartość „$2” dla parametru „$1” musi być pomiędzy $3 i $4.", "paramvalidator-outofrange-min": "Wartość „$2” dla parametru „$1” nie może być mniejsza niż $3.", "paramvalidator-param-deprecated": "Parametr „$1” został uznany za przestarzały.", "paramvalidator-toomanyvalues": "Podano za dużo wartości dla parametru „$1”. Maksymalna dozwolona ilość to $2.", "paramvalidator-unclearnowtimestamp": "Podawanie „$2” jako wartości dla parametru „$1” jest przestarzałe. Jeśli z jakiegoś powodu musisz podać bieżący czas bez obliczania go po stronie klienta, użyj „now”.", "paramvalidator-unrecognizedvalues": "{{PLURAL:$4|Nierozpoznana wartość|Nierozpoznane wartości}} dla parametru „$1”: $3.", "paramvalidator-help-default": "Domyślnie: $1", "paramvalidator-help-default-empty": "Domyślnie: (pusta)", "paramvalidator-help-deprecated": "Ten parametr jest przestarzały.", "paramvalidator-help-multi-separate": "Rozdzielaj wartości za pomocą znaku „|” lub poprzedź listę U+001F i rozdzielaj wartości również z użyciem U+001F.", "paramvalidator-help-multi-max": "Maksymalna liczba wartości to {{PLURAL:$1|$1}} ({{PLURAL:$2|$2}} dla klientów z podwyższonymi limitami).", "paramvalidator-help-multi-max-simple": "Maksymalna liczba wartości to {{PLURAL:$1|$1}}.", "paramvalidator-help-multi-all": "Aby wskazać wszystkie wartości, użyj <kbd>$1</kbd>.", "paramvalidator-help-required": "Ten parametr jest wymagany.", "paramvalidator-help-type-boolean": "Typ: {{PLURAL:$1|1=wartość boolowska|2=lista wartości boolowskich}}", "paramvalidator-help-type-enum-can-be-empty": "{{PLURAL:$2|0=Musi być pusty|Może być pusty albo $1}}", "paramvalidator-help-type-enum": "{{PLURAL:$1|1=Jedna z następujących wartości|2=Wartości (oddzielane z użyciem U+007C (potoku, „|”) albo poprzedzone i rozdzielane znakiem U+001F)}}: $2", "paramvalidator-help-type-expiry": "Typ: {{PLURAL:$1|1=data wygaśnięcia|2=lista dat wygaśnięcia}}.\n\nData może być względna (np. <kbd>5 months</kbd> lub <kbd>2 weeks</kbd>) albo bezwzględna (np. <kbd>2014-09-18T12:34:56Z</kbd>). Wartości, które określają trwanie w nieskończoność to: $2.", "paramvalidator-help-type-float": "Typ: {{PLURAL:$1|1=float|2=lista floatów}}", "paramvalidator-help-type-integer": "Typ: {{PLURAL:$1|1=liczba całkowita|2=lista liczb całkowitych}}", "paramvalidator-help-type-limit": "Typ: liczba całkowita lub „max”", "paramvalidator-help-type-number-max": "{{PLURAL:$1|Wartość nie może być większa|Wartości nie mogą być większe}} niż $3.", "paramvalidator-help-type-number-minmax": "{{PLURAL:$1|Wartość musi|Wartości muszą}} znajdować się pomiędzy $2 a $3.", "paramvalidator-help-type-number-min": "{{PLURAL:$1|Wartość nie może być mniejsza|Wartości nie mogą być mniejsze}} niż $2.", "paramvalidator-help-type-presenceboolean": "Typ: wartość boolowska", "paramvalidator-help-type-string-maxbytes": "Nie może być dłuższa niż $1 {{PLURAL:$1|bajt|bajty|bajtów}}.", "paramvalidator-help-type-string-maxchars": "Nie może być dłuższa niż $1 {{PLURAL:$1|znak|znaki|znaków}}.", "paramvalidator-help-type-timestamp": "Typ: {{PLURAL:$1|1=znacznik czasu|2=lista znaczników czasu}}", "paramvalidator-help-type-upload": "Musi być przesłana jako plik, z użyciem typu zawartości „multipart/form-data”." } PK ! C�h�` ` ParamValidator/i18n/ban.jsonnu �Iw�� { "@metadata": { "authors": [ "Chinamoonroll" ] }, "paramvalidator-badbool": "Aji tan patut \"$2\" antuk paraméter boolean \"$1\". Liwat $3 antuk beneh, utawi $5 antuk iwang.", "paramvalidator-badexpiry": "Aji tan patut \"$2\" antuk paraméter kadaluwarsa \"$1\".", "paramvalidator-badexpiry-duration": "Baang aji \"$2\" antuk paraméter <var>$1</var> ngaliwatin maksimum \"$3\".", "paramvalidator-emptystring": "string puyung", "paramvalidator-help-default": "Baku: $1", "paramvalidator-help-default-empty": "Baku: (puyung)", "paramvalidator-help-type-boolean": "Soroh: {{PLURAL:$1|1=boolean|2=lis boolean}}", "paramvalidator-help-type-enum-can-be-empty": "{{PLURAL:$2|0=Patut puyung|Prasida puyung, utawi $1}}", "paramvalidator-help-type-limit": "Soroh: integer utawi \"maks\"", "paramvalidator-help-type-presenceboolean": "Soroh: boolean" } PK ! f��� ParamValidator/i18n/ce.jsonnu �Iw�� { "@metadata": { "authors": [ "Умар" ] }, "paramvalidator-emptystring": "баьсса могӀа", "paramvalidator-missingparam": "«$1» параметр хила йеза.", "paramvalidator-help-default": "Ӏадйитаран кеп: $1", "paramvalidator-help-default-empty": "Ӏадйитаран кеп: (йаьсса)", "paramvalidator-help-deprecated": "ХӀара параметр ширйелла.", "paramvalidator-help-multi-max-simple": "МаьӀнийн максимум дукхалла — {{PLURAL:$1|$1}}.", "paramvalidator-help-multi-all": "Дерриге маьӀнаш билгалдан лелайе <kbd>$1</kbd>.", "paramvalidator-help-required": "ХӀара хила йеза параметр йу.", "paramvalidator-help-type-boolean": "Тайпа: {{PLURAL:$1|логикин маьӀна}}", "paramvalidator-help-type-enum-can-be-empty": "{{PLURAL:$2|0=Йаьсса хила йеза|Йаьсса хила мега йа $1}}", "paramvalidator-help-type-integer": "Тайпа: {{PLURAL:$1|дийнатерахьан маьӀна}}", "paramvalidator-help-type-limit": "Тайпа: дийнатерахьан маьӀна йа «max»", "paramvalidator-help-type-number-max": "{{PLURAL:$1|МаьӀна}} хила ца деза $3 сов даьлла.", "paramvalidator-help-type-number-minmax": "{{PLURAL:$1|МаьӀна}} хила деза $2 а, $3 йуккъехь.", "paramvalidator-help-type-number-min": "{{PLURAL:$1|МаьӀна}} $2 доца хила ца деза.", "paramvalidator-help-type-presenceboolean": "Тайпа: логикин маьӀна", "paramvalidator-help-type-string-maxbytes": "Хила ца йеза $1 {{PLURAL:$1|байтал}} йеха.", "paramvalidator-help-type-string-maxchars": "Хила ца йеза $1 {{PLURAL:$1|хьаьркал}} йеха.", "paramvalidator-help-type-timestamp": "Тайпа: {{PLURAL:$1|ханна билгало}}", "paramvalidator-help-type-upload": "Файл санна дӀайахьийта йеза multipart/form-data лелош." } PK ! ޗ� ParamValidator/i18n/de.jsonnu �Iw�� { "@metadata": { "authors": [ "Brettchenweber", "Justman10000", "McDutchie" ] }, "paramvalidator-badbool": "Ungültiger Wert „$2“ für den booleschen Parameter „$1“. Übergib $3 für true oder $5 für false.", "paramvalidator-badbool-type": "Ungültiger Wert \"$2\" für booleschen Parameter \"$1\". Erhalte stattdessen den Wert \"$3\".", "paramvalidator-badexpiry": "Ungültiger Wert „$2“ für den Ablauf-Parameter „$1“.", "paramvalidator-badexpiry-duration": "Der gegebene Wert „$2“ für den Parameter <var>$1<var> überschreitet das Maximum von „$3“.", "paramvalidator-badexpiry-duration-max": "Der gegebene Wert „$2“ für den Parameter <var>$1<var> überschreitet das Maximum von „$3“. Verwende wird stattdessen das Maximum.", "paramvalidator-badexpiry-past": "Der Wert „$2“ für den Ablauf-Parameter „$1“ liegt in der Vergangenheit.", "paramvalidator-badfloat": "Ungültiger Wert „$2“ für den Float-Parameter „$1“.", "paramvalidator-badfloat-type": "Ungültiger Wert \"$2\" für Float-Parameter \"$1\". Erhalte stattdessen den Wert \"$3\".", "paramvalidator-badfloat-notfinite": "Der Wert „$2“ für den Float-Parameter „$1“ ist zu groß oder ist keine Zahl.", "paramvalidator-badinteger": "Ungültiger Wert „$2“ für den ganzzahligen Parameter „$1“.", "paramvalidator-badinteger-type": "Ungültiger Wert \"$2\" für Integer-Parameter \"$1\". Erhalte stattdessen den Wert \"$3\".", "paramvalidator-badinteger-fraction": "Ungültiger Wert \"$2\" für Integer-Parameter \"$1\". Erhalte stattdessen eine Fließkommazahl mit Nachkommastellen.", "paramvalidator-badtimestamp": "Ungültiger Wert „$2“ für den Zeitstempel-Parameter „$1“.", "paramvalidator-badupload-cantwrite": "Die Datei für „$1“ konnte aufgrund einer Server-Fehlkonfiguration (Schreibfehler) nicht zur Verarbeitung gespeichert werden.", "paramvalidator-badupload-formsize": "Die hochgeladene Datei für „$1“ überschreitet das clientseitige Maximum.", "paramvalidator-badupload-inisize": "Die hochgeladene Datei für „$1“ überschreitet das serverseitige Maximum von $3.", "paramvalidator-badupload-nofile": "Für den Upload-Parameter „$1“ wurde keine Datei bereitgestellt.", "paramvalidator-badupload-notmpdir": "Die Datei für „$1“ konnte aufgrund einer Server-Fehlkonfiguration nicht zur Verarbeitung gespeichert werden (kein temporäres Verzeichnis).", "paramvalidator-badupload-notupload": "Der Datei-Upload-Parameter „$1“ ist kein Datei-Upload; stelle sicher, dass du multipart/form-data für den POST verwendest und einen Dateinamen in den Content-Disposition-Header einfügst.", "paramvalidator-badupload-partial": "Die Datei für „$1“ wurde nur teilweise hochgeladen.", "paramvalidator-badupload-phpext": "Eine PHP-Erweiterung verhinderte den Upload der Datei für „$1“.", "paramvalidator-badvalue-enummulti": "Ungültiger Wert „$2“ für den Parameter „$1“. {{PLURAL:$4|Nur „$3“ ist erlaubt.|Erlaubte Werte sind $3.}}", "paramvalidator-badvalue-enumnotmulti": "Nicht erkannter Wert für den Parameter „$1“: $2.", "paramvalidator-deprecated-value": "Der Wert „$2“ für den Parameter „$1“ ist veraltet.", "paramvalidator-emptystring": "der leere String", "paramvalidator-maxbytes": "Der Wert für den Parameter „$1“ kann nicht länger als $3 {{PLURAL:$3|Byte|Bytes}} sein (war $4).", "paramvalidator-maxchars": "The value for parameter \"$1\" cannot be longer than $3 {{PLURAL:$3|Zeichen}} (war $4).", "paramvalidator-missingparam": "Der Parameter „$1“ muss gesetzt werden.", "paramvalidator-notmulti": "Der Parameter „$1“ akzeptiert nur einen einzigen Wert. U+001F-Mehrwerttrennung darf nur für mehrwertige Parameter verwendet werden.", "paramvalidator-multivalue-must-be-array": "Der mehrwertige Parameter \"$1\" muss als Array angegeben werden.", "paramvalidator-needstring": "Der Parameter \"$1\" akzeptiert nur einen String-Wert, erhält jedoch $2", "paramvalidator-outofrange-max": "Der Wert „$2“ für den Parameter „$1“ darf nicht größer als $4 sein.", "paramvalidator-outofrange-minmax": "Der Wert „$2“ für den Parameter „$1“ muss zwischen $3 und $4 liegen.", "paramvalidator-outofrange-min": "Der Wert „$2“ für den Parameter „$1“ darf nicht weniger als $3 betragen.", "paramvalidator-param-deprecated": "Der Parameter „$1“ ist veraltet.", "paramvalidator-toomanyvalues": "Zu viele Werte für den Parameter „$1“ geliefert. Die Grenze liegt bei $2.", "paramvalidator-unclearnowtimestamp": "Die Übergabe von „$2“ für den Zeitstempel-Parameter „$1“ ist veraltet. Wenn aus irgendeinem Grund die aktuelle Zeit explizit angeben muss, ohne sie clientseitig zu berechnen, verwende „now“.", "paramvalidator-unrecognizedvalues": "Nicht {{PLURAL:$4|erkannter Wert|erkannte Werte}} für den Parameter „$1“: $3", "paramvalidator-help-default": "Standard: $1", "paramvalidator-help-default-empty": "Standard: (leer)", "paramvalidator-help-deprecated": "Dieser Parameter ist veraltet.", "paramvalidator-help-multi-separate": "Trenne die Werte mit „|“, oder stelle der Liste U+001F vor und trenne sie mit U+001F.", "paramvalidator-help-multi-max": "Die maximale Anzahl von Werten beträgt {{PLURAL:$1|$1}} ({{PLURAL:$2|$2}} für Clients, denen höhere Limits erlaubt sind).", "paramvalidator-help-multi-max-simple": "Die maximale Anzahl von Werten beträgt {{PLURAL:$1|$1}}", "paramvalidator-help-multi-all": "Um alle Werte anzugeben, verwende <kbd>$1<kbd>.", "paramvalidator-help-required": "Dieser Parameter ist erforderlich.", "paramvalidator-help-type-boolean": "Typ: {{PLURAL:$1|1=Boolean|2=Liste Boolean-Werte}}", "paramvalidator-help-type-enum-can-be-empty": "{{PLURAL:$2|0=Muss leer sein|Kann leer sein oder $1}}", "paramvalidator-help-type-enum": "{{PLURAL:$1|1=Einer der folgenden Werte|2=Werte (getrennt durchh U+007C (Pipe) oder Präfix der Liste mit U+001F und getrennt durch U+001F)}}: $2", "paramvalidator-help-type-expiry": "Typ: {{PLURAL:$1|1=Ablaufzeit|2=Liste von Ablaufzeiten}}.\n\nKann relativ (z.B. <kbd>5 months</kbd> oder <kbd>2 weeks</kbd>) oder absolut (z.B. <kbd>2014-09-18T12:34:56Z</kbd>) sein. Für keine Ablaufzeit verwende $2.", "paramvalidator-help-type-float": "Type {{PLURAL:$1|1=Gleitkommazahl|2=Liste von Gleitkommazahlen}}", "paramvalidator-help-type-integer": "Typ: {{PLURAL:$1|1=Ganzzahl|2=Liste von Ganzzahlen}}", "paramvalidator-help-type-limit": "Typ: integer oder „max“", "paramvalidator-help-type-number-max": "{{PLURAL:$1|1=Der Wert darf|2=Die Werte dürfen}} nicht größer sein als $3.", "paramvalidator-help-type-number-minmax": "{{PLURAL:$1|1=Der Wert muss|2=Die Werte müssen}} zwischen $2 und $3 liegen.", "paramvalidator-help-type-number-min": "{{PLURAL:$1|1=Der Wert darf|2=Die Werte dürfen}} nicht kleiner sein als $2.", "paramvalidator-help-type-presenceboolean": "Typ: boolean", "paramvalidator-help-type-string-maxbytes": "Kann nicht länger sein als {{PLURAL:$1|ein Byte|$1 Bytes}}.", "paramvalidator-help-type-string-maxchars": "Kann nicht länger sein als {{PLURAL:$1|ein|$1}} Zeichen.", "paramvalidator-help-type-timestamp": "Typ: {{PLURAL:$1|1=Zeitstempel|2=Liste von Zeitstempeln}}", "paramvalidator-help-type-upload": "Muss als Dateiupload mithilfe eines multipart/form-data-Formulars bereitgestellt werden." } PK ! {Jؒ� � ParamValidator/i18n/pt.jsonnu �Iw�� { "@metadata": { "authors": [ "Hamilton Abreu" ] }, "paramvalidator-badbool": "Valor inválido \"$2\" para o parâmetro booliano \"$1\". Passar $3 para verdadeiro ou $5 para falso.", "paramvalidator-badexpiry": "Valor inválido \"$2\" para o parâmetro de expiração \"$1\".", "paramvalidator-badexpiry-duration": "O valor dado \"$2\" para o parâmetro <var>$1</var> excede o máximo \"$3\".", "paramvalidator-badexpiry-duration-max": "O valor dado \"$2\" para o parâmetro <var>$1</var> excede o máximo \"$3\". Será antes usado o máximo.", "paramvalidator-badexpiry-past": "O valor \"$2\" para o parâmetro de expiração \"$1\" é no passado.", "paramvalidator-badfloat": "Valor inválido \"$2\" para o parâmetro de vírgula flutuante \"$1\".", "paramvalidator-badfloat-notfinite": "O valor \"$2\" para o parâmetro de vírgula flutuante \"$1\" é demasiado grande ou não é um número.", "paramvalidator-badinteger": "Valor inválido \"$2\" para o parâmetro inteiro \"$1\".", "paramvalidator-badtimestamp": "Valor inválido \"$2\" para o parâmetro de data e hora \"$1\".", "paramvalidator-badupload-cantwrite": "O ficheiro para \"$1\" não pôde ser armazenado para processamento devido a uma configuração incorreta do servidor (falha de escrita).", "paramvalidator-badupload-formsize": "O ficheiro carregado para \"$1\" excede o máximo especificado pelo cliente.", "paramvalidator-badupload-inisize": "O ficheiro carregado para \"$1\" excede o máximo do servidor, $3.", "paramvalidator-badupload-nofile": "Não foi fornecido nenhum ficheiro para o parâmetro de carregamento \"$1\".", "paramvalidator-badupload-notmpdir": "O ficheiro para \"$1\" não pôde ser armazenado para processamento devido a uma configuração incorreta do servidor (não há diretório temporário).", "paramvalidator-badupload-notupload": "O parâmetro para carregamento de ficheiros \"$1\" não é um carregamento de ficheiro; certifique-se de que usa multipart/form-data no seu POST e inclui um nome de ficheiro no cabeçalho Content-Disposition.", "paramvalidator-badupload-partial": "O ficheiro para \"$1\" só foi carregado parcialmente.", "paramvalidator-badupload-phpext": "Uma extensão PHP impediu o carregamento do ficheiro para \"$1\".", "paramvalidator-badvalue-enummulti": "Valor inválido \"$2\" para o parâmetro \"$1\". {{PLURAL:$4|Só é permitido \"$3\".|Os valores permitidos são $3.}}", "paramvalidator-badvalue-enumnotmulti": "Valor não reconhecido para o parâmetro \"$1\": $2.", "paramvalidator-deprecated-value": "O valor \"$2\" para o parâmetro \"$1\" foi descontinuado.", "paramvalidator-emptystring": "texto vazio", "paramvalidator-maxbytes": "O valor para o parâmetro \"$1\" não pode ter mais de $3 {{PLURAL:$3|byte|bytes}} (tinha $4).", "paramvalidator-maxchars": "O valor para o parâmetro \"$1\" não pode ter mais de $3 {{PLURAL:$3|carácter|caracteres}} (tinha $4).", "paramvalidator-missingparam": "O parâmetro \"$1\" tem de estar definido.", "paramvalidator-notmulti": "O parâmetro \"$1\" só aceita um único valor. A separação multivalor U+001F só pode ser usada em parâmetros multivalor.", "paramvalidator-outofrange-max": "O valor \"$2\" para o parâmetro \"$1\" não pode ser maior do que $4.", "paramvalidator-outofrange-minmax": "O valor \"$2\" para o parâmetro \"$1\" tem de estar entre $3 e $4.", "paramvalidator-outofrange-min": "O valor \"$2\" para o parâmetro \"$1\" não pode ser inferior a $3.", "paramvalidator-param-deprecated": "O parâmetro \"$1\" foi descontinuado.", "paramvalidator-toomanyvalues": "Foram fornecidos demasiados valores para o parâmetro \"$1\". O limite é $2.", "paramvalidator-unclearnowtimestamp": "A passagem de \"$2\" no parâmetro de data e hora \"$1\" foi descontinuada. Se, por qualquer razão, precisar de especificar de forma explícita a hora atual sem a calcular no lado do cliente, use \"now\".", "paramvalidator-unrecognizedvalues": "{{PLURAL:$4|Valor não reconhecido|Valores não reconhecidos}} para o parâmetro \"$1\": $3.", "paramvalidator-help-default": "Valor por omissão: $1", "paramvalidator-help-default-empty": "Valor por omissão: (vazio)", "paramvalidator-help-deprecated": "Este parâmetro foi descontinuado.", "paramvalidator-help-multi-separate": "Separe os valores com \"|\" ou prefixe a lista com U+001F e separe-os com U+001F.", "paramvalidator-help-multi-max": "O número máximo de valores é {{PLURAL:$1|$1}} ({{PLURAL:$2|$2}} para clientes a quem são permitidos limites mais elevados).", "paramvalidator-help-multi-max-simple": "O número máximo de valores é {{PLURAL:$1|$1}}.", "paramvalidator-help-multi-all": "Para especificar todos os valores, use <kbd>$1</kbd>.", "paramvalidator-help-required": "Este parâmetro é obrigatório.", "paramvalidator-help-type-boolean": "Tipo: {{PLURAL:$1|1=booliano|2=lista de boolianos}}", "paramvalidator-help-type-enum-can-be-empty": "{{PLURAL:$2|0=Tem de estar vazio|Pode estar vazio, ou ser $1}}", "paramvalidator-help-type-enum": "{{PLURAL:$1|1=Um dos seguintes valores|2=Valores (separar com U+007C (barra vertical) ou prefixar a lista com U+001F e separar os valores com U+001F)}}: $2", "paramvalidator-help-type-expiry": "Tipo: {{PLURAL:$1|1=expiração|2=lista de expirações}}.\n\nPode ser relativo (p.ex. <kbd>5 months</kbd> ou <kbd>2 weeks</kbd>) ou absoluto (p.ex. <kbd>2014-09-18T12:34:56Z</kbd>). Para não haver expiração, usar $2.", "paramvalidator-help-type-float": "Tipo: {{PLURAL:$1|1=vírgula flutuante|2=lista de vírgulas flutuantes}}", "paramvalidator-help-type-integer": "Tipo: {{PLURAL:$1|1=inteiro|2=lista de inteiros}}", "paramvalidator-help-type-limit": "Tipo: inteiro ou \"max\"", "paramvalidator-help-type-number-max": "{{PLURAL:$1|1=O valor não pode ser maior|2=Os valores não podem ser maiores}} do que $3.", "paramvalidator-help-type-number-minmax": "{{PLURAL:$1|1=O valor tem|2=Os valores têm}} de estar entre $2 e $3.", "paramvalidator-help-type-number-min": "{{PLURAL:$1|1=O valor não pode ser inferior|2=Os valores não podem ser inferiores}} a $2.", "paramvalidator-help-type-presenceboolean": "Tipo: booliano", "paramvalidator-help-type-string-maxbytes": "Não pode exceder $1 {{PLURAL:$1|byte|bytes}}.", "paramvalidator-help-type-string-maxchars": "Não pode exceder $1 {{PLURAL:$1|carácter|caracteres}}.", "paramvalidator-help-type-timestamp": "Tipo: {{PLURAL:$1|1=data e hora|2=lista de datas e horas}}", "paramvalidator-help-type-upload": "Deve ser enviado na forma de carregamento de um ficheiro usando multipart/form-data." } PK ! �Nص� � ParamValidator/i18n/io.jsonnu �Iw�� { "@metadata": { "authors": [ "Joao Xavier" ] }, "paramvalidator-badbool": "Nevalida valoro \"$2\" por booleana parametro \"$1\". Informez $3 se vera, o $5 se falsa.", "paramvalidator-badbool-type": "Nevalida valoro \"$2\" por parametro booleana \"$1\". Informesis valoro $3, nekorekta.", "paramvalidator-badfloat": "Nevalida valoro \"$2\" por flotacanta parametro \"$1\".", "paramvalidator-help-default": "Normala: $1", "paramvalidator-help-default-empty": "Normala: (vakua)", "paramvalidator-help-deprecated": "L'uzo di ca parametro esas deskonsilata.", "paramvalidator-help-multi-separate": "Separez valori per \"|\", o informez prefixo por la listo uzanta U+001F, e separanta ol per U+001F.", "paramvalidator-help-required": "On bezonas ca parametro.", "paramvalidator-help-type-boolean": "Tipo: {{PLURAL:$1|1=booleano*|2=listo pri booleani*}}", "paramvalidator-help-type-enum-can-be-empty": "{{PLURAL:$2|0=Mustas vakuesar|Povas vakuesar, o $1}}", "paramvalidator-help-type-enum": "{{PLURAL:$1|1=Un ek la sequanta valori|2=Valori (separita per U+007C \"|\", o informez prefixo por la listo U+001F, e separez ol per U+001F)}}: $2", "paramvalidator-help-type-limit": "Tipo: integro, o \"max\" (maximo)", "paramvalidator-help-type-number-max": "{{PLURAL:$1|1=Valoro|2=Valori}} mustas esar min granda kam $3.", "paramvalidator-help-type-presenceboolean": "Tipo: *booleana (Vera/Falsa)" } PK ! �A9ß � ParamValidator/i18n/diq.jsonnu �Iw�� { "@metadata": { "authors": [ "1917 Ekim Devrimi" ] }, "paramvalidator-emptystring": "rêza venge", "paramvalidator-missingparam": "Gani parametrey \"$1\" eyar bo.", "paramvalidator-help-default": "Hesabyaye : $1", "paramvalidator-help-default-empty": "Hesabyaye: (veng)", "paramvalidator-help-deprecated": "Parametre wedariyayo", "paramvalidator-help-required": "No parametre lazımo", "paramvalidator-help-type-boolean": "Tewr: {{PLURAL:$1|1=boolean|2=lista booleans}}", "paramvalidator-help-type-enum-can-be-empty": "{{PLURAL:$2|0=wa veng bo|veng ya zi $1 beno }}", "paramvalidator-help-type-float": "Tewr: {{PLURAL:$1|1=natlon|2=lista naylonan}}", "paramvalidator-help-type-integer": "Tewr: {{PLURAL:$1|1=tamamar|2=lista tamamari}}", "paramvalidator-help-type-limit": "Tewr: tam amar ya zi \"max\"", "paramvalidator-help-type-number-max": "Wa {{PLURAL:$1|1=erca |2=ercê }} $3 ra zeder bê.", "paramvalidator-help-type-presenceboolean": "Tewr:Boolean", "paramvalidator-help-type-string-maxbytes": "$1 {{PLURAL:$1|bayte|$1 baytan }} ra kemi nêbeno", "paramvalidator-help-type-string-maxchars": "$1 {{PLURAL:$1|karakter|$1 karakteran}} ra kemi nêbeno" } PK ! ��' � � ParamValidator/i18n/ko.jsonnu �Iw�� { "@metadata": { "authors": [ "Ykhwong", "Tensama0415" ] }, "paramvalidator-badexpiry": "만료 변수 \"$1\"에 유효하지 않은 값 \"$2\"이 지정되었습니다.", "paramvalidator-badfloat": "float 변수 \"$1\"에 유효하지 않은 값 \"$2\"이 지정되었습니다.", "paramvalidator-badfloat-notfinite": "float 변수 \"$1\"에 대한 값 \"$2\"은 너무 크거나 숫자가 아닙니다.", "paramvalidator-badinteger": "정수 변수 \"$1\"에 유효하지 않은 값 \"$2\"이 지정되었습니다.", "paramvalidator-badtimestamp": "시간 기록 변수 \"$1\"에 유효하지 않은 값 \"$2\"이 지정되었습니다.", "paramvalidator-badupload-formsize": "\"$1\"에 대한 업로드 파일은 클라이언트가 지정한 최대값을 초과합니다.", "paramvalidator-badupload-inisize": "\"$1\"에 대한 업로드 파일은 서버의 최대값($3)을 초과합니다.", "paramvalidator-badupload-nofile": "업로드 변수 \"$1\"에 대한 파일이 제공되지 않았습니다.", "paramvalidator-badupload-partial": "\"$1\"에 대한 파일이 일부만 업로드되었습니다.", "paramvalidator-badupload-phpext": "PHP 확장 기능으로 인해 \"$1\"에 대한 파일 업로드가 차단되었습니다.", "paramvalidator-badvalue-enumnotmulti": "변수 \"$1\"에 대한 알 수 없는 값: $2.", "paramvalidator-deprecated-value": "\"$1\" 변수에 대한 값 \"$2\"은 구식입니다.", "paramvalidator-emptystring": "빈 문자열", "paramvalidator-missingparam": "\"$1\" 변수는 설정이 필수입니다.", "paramvalidator-multivalue-must-be-array": "다중값 변수 \"$1\"은 반드시 배열로 주어져야 합니다.", "paramvalidator-needstring": "변수 \"$1\"은 문자열 값만을 허용하지만, $2를 받았습니다.", "paramvalidator-outofrange-max": "\"$1\" 변수의 \"$2\" 값은 $4 미만이어야 합니다.", "paramvalidator-outofrange-minmax": "\"$1\" 변수의 \"$2\" 값은 $3에서 $4 사이여야 합니다.", "paramvalidator-outofrange-min": "\"$1\" 변수의 \"$2\" 값은 $3 보다 작아서는 안 됩니다.", "paramvalidator-param-deprecated": "\"$1\" 변수는 구식입니다.", "paramvalidator-toomanyvalues": "\"$1\" 변수에 너무 많은 갯수의 값이 주어졌습니다. 상한은 $2입니다.", "paramvalidator-unrecognizedvalues": "\"$1\" 변수에 대해 인식할 수 없는 {{PLURAL:$4|값}}: $3", "paramvalidator-help-default": "기본값: $1", "paramvalidator-help-default-empty": "기본값: (빈 값)", "paramvalidator-help-deprecated": "이 변수는 구식입니다.", "paramvalidator-help-multi-max": "값의 최대 수는 {{PLURAL:$1|$1}}(더 높은 제한이 허용된 클라이언트의 경우 {{PLURAL:$2|$2}})입니다.", "paramvalidator-help-multi-max-simple": "값의 최대 수는 {{PLURAL:$1|$1}}입니다.", "paramvalidator-help-multi-all": "모든 값을 지정하려면, <kbd>$1</kbd>를 사용하십시오.", "paramvalidator-help-required": "이 변수는 필수입니다.", "paramvalidator-help-type-boolean": "유형: {{PLURAL:$1|1=불리언|2=불리언 목록}}", "paramvalidator-help-type-enum-can-be-empty": "{{PLURAL:$2|0=비어 있어야 함|비어 있을 수 있음 또는 $1}}", "paramvalidator-help-type-float": "유형: {{PLURAL:$1|1=플로트|2=플로트 목록}}", "paramvalidator-help-type-integer": "유형: {{PLURAL:$1|1=정수|2=정수 목록}}", "paramvalidator-help-type-limit": "유형: 정수 또는 \"max\"", "paramvalidator-help-type-number-max": "{{PLURAL:$1|값}}은 $3 값을 초과할 수 없습니다.", "paramvalidator-help-type-number-minmax": "{{PLURAL:$1|1=값|2=값들}}은 $2와 $3 사이여야 합니다.", "paramvalidator-help-type-number-min": "{{PLURAL:$1|1=값|2=값들}}은 $2 이상이어야 합니다.", "paramvalidator-help-type-presenceboolean": "유형: 불리언", "paramvalidator-help-type-string-maxbytes": "$1{{PLURAL:$1|바이트}}를 초과할 수 없습니다.", "paramvalidator-help-type-string-maxchars": "$1{{PLURAL:$1|자}}를 초과할 수 없습니다.", "paramvalidator-help-type-timestamp": "유형: {{PLURAL:$1|1=타임스탬프|2=타임스탬프 목록}}", "paramvalidator-help-type-upload": "여러 부분/폼 데이터를 사용한 파일 업로드로 게시되어야 합니다." } PK ! H1a�e e ParamValidator/i18n/sv.jsonnu �Iw�� { "@metadata": { "authors": [ "Sabelöga", "WikiPhoenix", "Lejonel" ] }, "paramvalidator-badbool": "\"$2\" är ett ogiltigt värde för booleska parametern \"$1\". Ange $3 för true eller $5 för false.", "paramvalidator-badbool-type": "Ogiltigt värde \"$2\" för booleska parametern \"$1\". Fick ett $3-värde istället.", "paramvalidator-badexpiry": "Ogiltigt värde \"$2\" för utgångsparametern \"$1\".", "paramvalidator-badexpiry-duration": "Det givna värdet \"$2\" för parametern <var>$1</var> överskrider gränsen för \"$3\".", "paramvalidator-badexpiry-duration-max": "Det givna värdet \"$2\" för parametern <var>$1</var> överskrider gränsen för \"$3\". Använd det hösta tillåtna istället.", "paramvalidator-badexpiry-past": "Värdet \"$2\" för utgångsparametern \"$1\" är i dåtiden", "paramvalidator-badfloat": "Ogiltigt värde \"$2\" för float-parametern \"$1\".", "paramvalidator-badfloat-type": "Ogiltigt värde \"$2\" för float-parametern \"$1\". Fick ett $3-värde istället.", "paramvalidator-badfloat-notfinite": "Värdet \"$2\" för float-parametern \"$1\" är för stor eller är inte ett nummer.", "paramvalidator-badinteger": "Ogiltigt färde \"$2\" för heltalsparametern \"$1\".", "paramvalidator-badinteger-type": "Ogiltigt värde \"$2\" för heltalsparametern \"$1\". Fick ett $3-värde istället.", "paramvalidator-badinteger-fraction": "Ogiltigt värde \"$2\" för heltalsparametern \"$1\". Fick en float med en bråkdel istället.", "paramvalidator-badtimestamp": "Ogiltigt värde \"$2\" för tidstämpelsparametern \"$1\".", "paramvalidator-badupload-cantwrite": "Filen för \"$1\" kunde inte lagras för bearbetning på grund av en felkonfigurering i servern (skrivning misslyckades).", "paramvalidator-badupload-formsize": "Den uppladdade filen för \"$1\" överskriver det av klienten angivna högsta tillåtna.", "paramvalidator-badupload-inisize": "Den uppladdade filen för \"$1\" överskrider serverns hösta tillåtna för $3.", "paramvalidator-badupload-nofile": "Ingen fil angavs för uppladdningsparametern \"$1\".", "paramvalidator-badupload-notmpdir": "Filen för \"$1\" kunde inte lagras för bearbetning på grund av en felkonfigurerad server (ingen tillfällig katalog).", "paramvalidator-badupload-notupload": "Filuppladdningsparametern \"$1\" är inte en filuppladdning; se till att använda multipart/form-data för din POST och inkludera ett filnamn i Content-Disposition-rubriken.", "paramvalidator-badupload-partial": "Filen för \"$1\" laddades endast delvis upp.", "paramvalidator-badupload-phpext": "Ett PHP-tillägg förhindrade uppladdningen av filerna för \"$1\".", "paramvalidator-badvalue-enummulti": "Ogiltigt värde \"$2\" för parametern \"$1\". {{PLURAL:$4|Endast \"$3\" tillåts.|Tillåtna värden är $3.}}", "paramvalidator-badvalue-enumnotmulti": "Okänt värde för parameter \"$1\": \"$2\".", "paramvalidator-deprecated-value": "Värdet \"$2\" till parameter \"$1\" är föråldrad.", "paramvalidator-emptystring": "den tomma strängen", "paramvalidator-maxbytes": "Värdet för parametern \"$1\" får inte vara längre än $3 {{PLURAL:$3|byte}} (var $4).", "paramvalidator-maxchars": "Värdet för parametern \"$1\" får inte vara längre än $3 {{PLURAL:$3|tecken}} (var $4).", "paramvalidator-missingparam": "Parametern \"$1\" måste anges.", "paramvalidator-notmulti": "Parametern \"$1\" accepterar endast ett enda värde. Flervärdesseparering med U+001F får bara användas för flervärdesparametrar.", "paramvalidator-multivalue-must-be-array": "Flervärdesparametrarn \"$1\" måste anges som en array.", "paramvalidator-needstring": "Parametern \"$1\" accepterar bara ett strängvärde, men fick $2.", "paramvalidator-outofrange-max": "Värdet \"$2\" för parametern \"$1\" får inte vara större än $4.", "paramvalidator-outofrange-minmax": "Värdet \"$2\" för parametern \"$1\" måste ligga mellan $3 och $4.", "paramvalidator-outofrange-min": "Värdet \"$2\" för parametern \"$1\" får inte vara mindre än $3.", "paramvalidator-param-deprecated": "Parametern \"$1\" är föråldrad.", "paramvalidator-toomanyvalues": "För många värden har angetts för parametern \"$1\". Gränsen ligger på $2.", "paramvalidator-unclearnowtimestamp": "Det är föråldrat att passera \"$2\" för tidsstämpelparametern \"$1\". Om du av någon anledning behöver uttryckligen ange den aktuella tiden utan att beräkna det på klientsidan, använd \"now\".", "paramvalidator-unrecognizedvalues": "{{PLURAL:$4|Okänt värde|Okända värden}} för parametern \"$1\": $3", "paramvalidator-help-default": "Standard: $1", "paramvalidator-help-default-empty": "Standard: (tom)", "paramvalidator-help-deprecated": "Den här parametern är föråldrad.", "paramvalidator-help-multi-separate": "Särskilj värden med \"|\", eller prefigera listan med U+001F och särskilj med U+001F.", "paramvalidator-help-multi-max": "Högsta antalet värden är {{PLURAL:$1|$1}} ({{PLURAL:$2|$2}} för klienter som tillåts högre gränser).", "paramvalidator-help-multi-max-simple": "Högsta antalet värden är {{PLURAL:$1|$1}}.", "paramvalidator-help-multi-all": "För att ange alla värden, använd <kbd>$1</kbd>.", "paramvalidator-help-required": "Den här parametern är obligatorisk.", "paramvalidator-help-type-boolean": "Typ: {{PLURAL:$1|1=boolesk|2=lista över booleaner}}", "paramvalidator-help-type-enum-can-be-empty": "{{PLURAL:$2|0=Måste vara tom|Kan vara tom, eller $1}}", "paramvalidator-help-type-enum": "{{PLURAL:$1|1=En av följande värden|2=Värden (särskilj med U+007C (rör), eller prefigera listan med U+001F och särskilj med U+001F)}}: $2", "paramvalidator-help-type-expiry": "Typ: {{PLURAL:$1|1=utgångstid|2=lista över utgångstider}}.\n\nKan relatera till (t.ex. <kbd>5 månader</kbd> eller <kbd>2 veckor</kbd>) eller absolut (t.ex. <kbd>2014-09-18T12:34:56Z</kbd>). För ingen utgångstid, använd $2.", "paramvalidator-help-type-float": "Typ: {{PLURAL:$1|1=float|2=lista över floats}}", "paramvalidator-help-type-integer": "Typ: {{PLURAL:$1|1=heltal|2=lista över heltal}}", "paramvalidator-help-type-limit": "Typ: heltal eller \"max\"", "paramvalidator-help-type-number-max": "{{PLURAL:$1|1=Värdet|2=Värdena}} får inte vara större än $3.", "paramvalidator-help-type-number-minmax": "{{PLURAL:$1|1=Värdet|2=Värdena}} måste ligga mellan $2 och $3.", "paramvalidator-help-type-number-min": "{{PLURAL:$1|1=Värdet|2=Värdena}} får inte vara mindre än $2.", "paramvalidator-help-type-presenceboolean": "Typ: boolesk", "paramvalidator-help-type-string-maxbytes": "Kan inte vara längre än $1 {{PLURAL:$1|byte}}.", "paramvalidator-help-type-string-maxchars": "Kan inte vara längre än $1 {{PLURAL:$1|tecken}}.", "paramvalidator-help-type-timestamp": "Typ: {{PLURAL:$1|1=tidsstämpel|2=lista över tidsstämplar}}", "paramvalidator-help-type-upload": "Måste läggas upp som filuppladdning med hjälp av multipart/form-data." } PK ! �/��� � ParamValidator/i18n/en-gb.jsonnu �Iw�� { "@metadata": { "authors": [ "Reedy" ] }, "paramvalidator-badvalue-enumnotmulti": "Unrecognised value for parameter \"$1\": $2.", "paramvalidator-unrecognizedvalues": "Unrecognised {{PLURAL:$4|value|values}} for parameter \"$1\": $3" } PK ! �� � � ParamValidator/i18n/hu.jsonnu �Iw�� { "@metadata": { "authors": [ "Dj", "Tacsipacsi" ] }, "paramvalidator-badbool": "A „$1” logikai paraméterhez megadott „$2” érték nem megfelelő. Adjon át $3 értéket igaznak, $5 értéket hamisnak.", "paramvalidator-badexpiry": "A(z) „$1” lejárati paraméternél megadott „$2” érték érvénytelen.", "paramvalidator-badexpiry-duration": "A(z) <var>$1</var> paraméter adott „$2” értéke meghaladja a „$3” maximális értéket.", "paramvalidator-badexpiry-duration-max": "A(z) <var>$1</var> paraméter „$2” értéke meghaladja a „$3” maximális értéket. A maximális érték kerül használatra.", "paramvalidator-badexpiry-past": "A „$2” lejárati paraméter „$1” értéke a múltban van.", "paramvalidator-badfloat": "A(z) „$1” lebegőpontos szám paraméternél megadott „$2” érték érvénytelen.", "paramvalidator-badfloat-notfinite": "A(z) „$1” lebegőpontos szám paraméternél megadott „$2” érték túl nagy, vagy nem szám.", "paramvalidator-badinteger": "A(z) „$1” egész szám paraméternél megadott „$2” érték érvénytelen.", "paramvalidator-badtimestamp": "A(z) „$1” időbélyeg paraméternél megadott „$2” érték érvénytelen.", "paramvalidator-badupload-cantwrite": "A(z) „$1” paraméternél megadott fájlt nem lehet feldolgozás céljából eltárolni a szerver hibás konfigurációs miatt (az írás sikertelen).", "paramvalidator-badupload-formsize": "A(z) „$1” paraméternél megadott fájl meghaladja az ügyfél által megadott maximumot.", "paramvalidator-badupload-inisize": "A(z) „$1” paraméternél megadott feltöltött fájl meghaladja a szerver maximumát, ami $3.", "paramvalidator-badupload-nofile": "A(z) „$1” paraméternél nem lett megadva fájl.", "paramvalidator-badupload-notmpdir": "A(z) „$1” paraméternél megadott fájlt nem lehet feldolgozás céljából eltárolni a szerver hibás konfigurációs miatt (nincs ideiglenes könyvtár).", "paramvalidator-badupload-notupload": "A „$1” fájlfeltöltési paraméter nem fájlfeltöltés; ügyeljél arra, hogy multipart\n/form-data-t használj a POST-hoz, és szerepeljen benne egy fájlnév a Content-Disposition fejlécben.", "paramvalidator-badupload-partial": "A(z) „$1” paraméternél megadott fájlt csak részben került feltöltésre.", "paramvalidator-badupload-phpext": "A(z) „$1” paraméternél megadott fájl feltöltét megakadályozta egy PHP-kiterjesztés.", "paramvalidator-badvalue-enummulti": "A(z) „$1” paraméternél megadott „$2” érték érvénytelen.{{PLURAL:$4|Csak „$3” engedélyezett|Az alábbi értékek engedélyezettek: $3}}", "paramvalidator-badvalue-enumnotmulti": "A „$1” paraméterhez megadott érték nem felismerhető: $2.", "paramvalidator-deprecated-value": "A(z) „$1” paraméternél megadott „$2” érték elavult.", "paramvalidator-emptystring": "üres karakterlánc", "paramvalidator-maxbytes": "A(z) „$1” paraméternél megadott érték nem lehet {{PLURAL:$3|$3}} bájtnál hosszabb ($4 volt).", "paramvalidator-maxchars": "A(z) „$1” paraméternél megadott érték nem lehet mint {{PLURAL:$3|$3}} karakternél hosszabb ($4 volt).", "paramvalidator-missingparam": "A(z) „$1” paramétert be kell állítani.", "paramvalidator-notmulti": "A(z) „$1” paraméter csak egyetlen értékes fogad el. Az U+001F többértékű elválasztás csak többértékű paramétereknél használható.", "paramvalidator-outofrange-max": "A(z) „$1” paraméternél megadott „$2” érték nem lehet nagyobb, mint $4.", "paramvalidator-outofrange-minmax": "A(z) „$1” paraméternél megadott „$2” értéknek $3 és $4 közé kell esnie.", "paramvalidator-outofrange-min": "A(z) „$1” paraméternél megadott „$2” érték nem lehet kevesebb, mint $3.", "paramvalidator-param-deprecated": "A(z) „$1” paraméter elavult.", "paramvalidator-toomanyvalues": "Túl sok megadott érték a „$1” paraméternél. A limit $2.", "paramvalidator-unclearnowtimestamp": "A(z) „$1” paraméternél megadott „$2” érték már elavult. Ha valamilyen oknál fogva kifejezetten meg kell adnia az aktuális időt anélkül, hogy azt kliensoldalon számítaná ki, használja a „now” lehetőséget.", "paramvalidator-unrecognizedvalues": "Felismerhetetlen {{PLURAL:$4|érték|értékek}} „$1” paraméternél: $3", "paramvalidator-help-default": "Alapértelmezett: $1", "paramvalidator-help-default-empty": "Alapértelmezett: (üres)", "paramvalidator-help-deprecated": "Ez a paraméter elavult.", "paramvalidator-help-multi-separate": "Az értékeket \"|\"-vel válaszd el, vagy a lista elé tegyél U+001F karaktert, és válaszd el U+001F karakterrel.", "paramvalidator-help-multi-max": "Az értékek maximális száma {{PLURAL:$1|$1}}. ($2 magasabb korláttal rendelkező ügyfelek számára).", "paramvalidator-help-multi-max-simple": "Az értékek maximális száma {{PLURAL:$1|$1}}.", "paramvalidator-help-multi-all": "Az összes érték megadásához használd a(z) <kbd>$1</kbd> értéket.", "paramvalidator-help-required": "Ez a paraméter kötelező.", "paramvalidator-help-type-boolean": "Típus: {{PLURAL:$1|1=logikai|2=logikai értékek listája}}", "paramvalidator-help-type-enum-can-be-empty": "{{PLURAL:$2|0=Üresnek kell lennie|Lehet üres vagy $1}}", "paramvalidator-help-type-enum": "{{PLURAL:$1|1=A következő értékek egyike|2=Értékek (az U+007C-vel (pipe) elválasztva, vagy a lista előtt U+001F, és elválasztva U+001F karakterrel)}}: $2", "paramvalidator-help-type-expiry": "Típus: {{PLURAL:$1| 1=lejárat|2=lejárati lista}}.\n\nLehet relatív (pl. <kbd>5 hónap</kbd> vagy <kbd>2 hét</kbd> ) vagy abszolút (pl. <kbd>2014-09-18T12:34:56Z</kbd> ). Ha nincs lejárati idő, használd ezeket: $2.", "paramvalidator-help-type-float": "Típus: {{PLURAL:$1|1=lebegőpontos szám|2=lebegőpontos számok listája}}", "paramvalidator-help-type-integer": "Típus: {{PLURAL:$1|1=egész szám|2=egész számok listája}}", "paramvalidator-help-type-limit": "Típus: egész szám vagy „max”", "paramvalidator-help-type-number-max": "Az {{PLURAL:$1|1=érték nem lehet nagyobb|2=értékek nem lehetnek nagyobbak}}, mint $3.", "paramvalidator-help-type-number-minmax": "{{PLURAL:$1|1=Az értéknek $2 és $3 között kell lennie.|2=Az értékeknek $2 és $3 között kell lenniük.}}", "paramvalidator-help-type-number-min": "Az {{PLURAL:$1|1=érték nem lehet kisebb|2=értékek nem lehetnek kisebbek}} mint $2.", "paramvalidator-help-type-presenceboolean": "Típus: logikai", "paramvalidator-help-type-string-maxbytes": "Nem lehet hosszabb $1 {{PLURAL:$1|bájtnál}}.", "paramvalidator-help-type-string-maxchars": "Nem lehet hosszabb $1 {{PLURAL:$1|karakternél}}.", "paramvalidator-help-type-timestamp": "Típus: {{PLURAL:$1|1=időbélyeg|2=időbélyegek listája}}", "paramvalidator-help-type-upload": "Fájlfeltöltésként kell közzétenni multipart/form-data használatával." } PK ! ��� � HttpStatus.phpnu �Iw�� <?php /** * List of HTTP status codes. * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ /** * @todo document */ class HttpStatus { /** * Get the message associated with an HTTP response status code * * @param int $code Status code * @return string|null Message, or null if $code is not known */ public static function getMessage( $code ) { static $statusMessage = [ 100 => 'Continue', 101 => 'Switching Protocols', 102 => 'Processing', 200 => 'OK', 201 => 'Created', 202 => 'Accepted', 203 => 'Non-Authoritative Information', 204 => 'No Content', 205 => 'Reset Content', 206 => 'Partial Content', 207 => 'Multi-Status', 300 => 'Multiple Choices', 301 => 'Moved Permanently', 302 => 'Found', 303 => 'See Other', 304 => 'Not Modified', 305 => 'Use Proxy', 307 => 'Temporary Redirect', 400 => 'Bad Request', 401 => 'Unauthorized', 402 => 'Payment Required', 403 => 'Forbidden', 404 => 'Not Found', 405 => 'Method Not Allowed', 406 => 'Not Acceptable', 407 => 'Proxy Authentication Required', 408 => 'Request Timeout', 409 => 'Conflict', 410 => 'Gone', 411 => 'Length Required', 412 => 'Precondition Failed', 413 => 'Request Entity Too Large', 414 => 'Request-URI Too Large', 415 => 'Unsupported Media Type', 416 => 'Request Range Not Satisfiable', 417 => 'Expectation Failed', 422 => 'Unprocessable Entity', 423 => 'Locked', 424 => 'Failed Dependency', 428 => 'Precondition Required', 429 => 'Too Many Requests', 431 => 'Request Header Fields Too Large', 500 => 'Internal Server Error', 501 => 'Not Implemented', 502 => 'Bad Gateway', 503 => 'Service Unavailable', 504 => 'Gateway Timeout', 505 => 'HTTP Version Not Supported', 507 => 'Insufficient Storage', 511 => 'Network Authentication Required', ]; return $statusMessage[$code] ?? null; } /** * Construct an HTTP status code header * * @since 1.42 * @param int $code Status code * @return string */ public static function getHeader( $code ): string { static $version = null; $message = self::getMessage( $code ); if ( $message === null ) { throw new InvalidArgumentException( "Unknown HTTP status code $code" ); } if ( $version === null ) { $version = isset( $_SERVER['SERVER_PROTOCOL'] ) && $_SERVER['SERVER_PROTOCOL'] === 'HTTP/1.0' ? '1.0' : '1.1'; } return "HTTP/$version $code $message"; } /** * Output an HTTP status code header * * @since 1.26 * @param int $code Status code */ public static function header( $code ) { \MediaWiki\Request\HeaderCallback::warnIfHeadersSent(); try { header( self::getHeader( $code ) ); } catch ( InvalidArgumentException $ex ) { trigger_error( "Unknown HTTP status code $code", E_USER_WARNING ); } } } PK ! ���y� � composer/ComposerJson.phpnu �Iw�� <?php namespace Wikimedia\Composer; /** * Reads a composer.json file and provides accessors to get * its hash and the required dependencies * * @since 1.25 */ class ComposerJson { /** * @var array[] */ private $contents; /** * @param string $location */ public function __construct( $location ) { $this->contents = json_decode( file_get_contents( $location ), true ); } /** * Dependencies as specified by composer.json * * @return string[] */ public function getRequiredDependencies() { $deps = []; if ( isset( $this->contents['require'] ) ) { foreach ( $this->contents['require'] as $package => $version ) { // Examples of package dependencies that don't have a / in the name: // php, ext-xml, composer-plugin-api if ( strpos( $package, '/' ) !== false ) { $deps[$package] = self::normalizeVersion( $version ); } } } return $deps; } /** * Strip a leading "v" from the version name * * @param string $version * @return string */ public static function normalizeVersion( $version ) { // Composer auto-strips the "v" in front of the tag name return ltrim( $version, 'v' ); } } PK ! �#�7 composer/ComposerLock.phpnu �Iw�� <?php namespace Wikimedia\Composer; /** * Reads a composer.lock file and provides accessors to get * its hash and what is installed * * @since 1.25 */ class ComposerLock { /** * @var array[] * @phan-var array{packages:array{name:string,version:string,type:string,license?:string,authors?:mixed,description?:string}} */ private $contents; /** * @param string $location */ public function __construct( $location ) { $this->contents = json_decode( file_get_contents( $location ), true ); } /** * Dependencies currently installed according to composer.lock * * @return array[] */ public function getInstalledDependencies() { $deps = []; foreach ( $this->contents['packages'] as $installed ) { $deps[$installed['name']] = [ 'version' => ComposerJson::normalizeVersion( $installed['version'] ), 'type' => $installed['type'], 'licenses' => $installed['license'] ?? [], 'authors' => $installed['authors'] ?? [], 'description' => $installed['description'] ?? '', ]; } return $deps; } } PK ! [�;u� � composer/ComposerInstalled.phpnu �Iw�� <?php namespace Wikimedia\Composer; /** * Reads an installed.json file and provides accessors to get what is * installed * * @since 1.27 */ class ComposerInstalled { /** * @var array[] */ private $contents; /** * @param string $location */ public function __construct( $location ) { $this->contents = json_decode( file_get_contents( $location ), true ); } /** * Dependencies currently installed according to installed.json * * @return array[] */ public function getInstalledDependencies() { $contents = $this->contents['packages']; $deps = []; foreach ( $contents as $installed ) { $deps[$installed['name']] = [ 'version' => ComposerJson::normalizeVersion( $installed['version'] ), 'type' => $installed['type'], 'licenses' => $installed['license'] ?? [], 'authors' => $installed['authors'] ?? [], 'description' => $installed['description'] ?? '', ]; } ksort( $deps ); return $deps; } } PK ! � �(/ (/ MapCacheLRU.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file * @ingroup Cache */ use Wikimedia\LightweightObjectStore\ExpirationAwareness; /** * Store key-value entries in a size-limited in-memory LRU cache. * * The last-modification timestamp of entries is internally tracked so that callers can * specify the maximum acceptable age of entries in calls to the has() method. As a convenience, * the hasField(), getField(), and setField() methods can be used for entries that are field/value * maps themselves; such fields will have their own internally tracked last-modification timestamp. * * @ingroup Cache * @since 1.23 */ class MapCacheLRU implements ExpirationAwareness { /** @var array Map of (key => value) */ private $cache = []; /** @var array Map of (key => (UNIX timestamp, (field => UNIX timestamp))) */ private $timestamps = []; /** @var float Default entry timestamp if not specified */ private $epoch; /** @var int Max number of entries */ private $maxCacheKeys; /** @var float|null */ private $wallClockOverride; /** @var float */ private const RANK_TOP = 1.0; /** @var int Array key that holds the entry's main timestamp (flat key use) */ private const SIMPLE = 0; /** @var int Array key that holds the entry's field timestamps (nested key use) */ private const FIELDS = 1; /** * @param int $maxKeys Maximum number of entries allowed (min 1) */ public function __construct( int $maxKeys ) { if ( $maxKeys <= 0 ) { throw new InvalidArgumentException( '$maxKeys must be above zero' ); } $this->maxCacheKeys = $maxKeys; // Use the current time as the default "as of" timestamp of entries $this->epoch = $this->getCurrentTime(); } /** * @param array $values Key/value map in order of increasingly recent access * @param int $maxKeys * @return MapCacheLRU * @since 1.30 */ public static function newFromArray( array $values, $maxKeys ) { $mapCache = new self( $maxKeys ); $mapCache->cache = ( count( $values ) > $maxKeys ) ? array_slice( $values, -$maxKeys, null, true ) : $values; return $mapCache; } /** * @return array Key/value map in order of increasingly recent access * @since 1.30 */ public function toArray() { return $this->cache; } /** * Set a key/value pair. * This will prune the cache if it gets too large based on LRU. * If the item is already set, it will be pushed to the top of the cache. * * To reduce evictions due to one-off use of many new keys, $rank can be * set to have keys start at the top of a bottom fraction of the list. A value * of 3/8 means values start at the top of the bottom 3/8s of the list and are * moved to the top of the list when accessed a second time. * * @param string $key * @param mixed $value * @param float $rank Bottom fraction of the list where keys start off [default: 1.0] * @return void */ public function set( $key, $value, $rank = self::RANK_TOP ) { if ( $this->has( $key ) ) { $this->ping( $key ); } elseif ( count( $this->cache ) >= $this->maxCacheKeys ) { $evictKey = array_key_first( $this->cache ); unset( $this->cache[$evictKey] ); unset( $this->timestamps[$evictKey] ); } if ( $rank < 1.0 && $rank > 0 ) { $offset = intval( $rank * count( $this->cache ) ); $this->cache = array_slice( $this->cache, 0, $offset, true ) + [ $key => $value ] + array_slice( $this->cache, $offset, null, true ); } else { $this->cache[$key] = $value; } $this->timestamps[$key] = [ self::SIMPLE => $this->getCurrentTime(), self::FIELDS => [] ]; } /** * Check if a key exists * * @param string|int $key * @param float $maxAge Ignore items older than this many seconds [default: INF] * @return bool * @since 1.32 Added $maxAge */ public function has( $key, $maxAge = INF ) { if ( !is_int( $key ) && !is_string( $key ) ) { throw new UnexpectedValueException( __METHOD__ . ': invalid key; must be string or integer.' ); } return array_key_exists( $key, $this->cache ) && ( // Optimization: Avoid expensive getAge/getCurrentTime for common case (T275673) $maxAge === INF || $maxAge <= 0 || $this->getKeyAge( $key ) <= $maxAge ); } /** * Get the value for a key. * This returns null if the key is not set. * If the item is already set, it will be pushed to the top of the cache. * * @param string $key * @param float $maxAge Ignore items older than this many seconds [default: INF] * @param mixed|null $default Value to return if no key is found [default: null] * @return mixed Returns $default if the key was not found or is older than $maxAge * @since 1.32 Added $maxAge * @since 1.34 Added $default * * Although sometimes this can be tainted, taint-check doesn't distinguish separate instances * of MapCacheLRU, so assume untainted to cut down on false positives. See T272134. * @return-taint none */ public function get( $key, $maxAge = INF, $default = null ) { if ( !$this->has( $key, $maxAge ) ) { return $default; } $this->ping( $key ); return $this->cache[$key]; } /** * @param string|int $key * @param string|int $field * @param mixed $value * @param float $initRank */ public function setField( $key, $field, $value, $initRank = self::RANK_TOP ) { if ( $this->has( $key ) ) { $this->ping( $key ); if ( !is_array( $this->cache[$key] ) ) { $type = get_debug_type( $this->cache[$key] ); throw new UnexpectedValueException( "Cannot add field to non-array value ('$key' is $type)" ); } } else { $this->set( $key, [], $initRank ); } if ( !is_string( $field ) && !is_int( $field ) ) { throw new UnexpectedValueException( __METHOD__ . ": invalid field for '$key'; must be string or integer." ); } $this->cache[$key][$field] = $value; $this->timestamps[$key][self::FIELDS][$field] = $this->getCurrentTime(); } /** * @param string|int $key * @param string|int $field * @param float $maxAge Ignore items older than this many seconds [default: INF] * @return bool * @since 1.32 Added $maxAge */ public function hasField( $key, $field, $maxAge = INF ) { $value = $this->get( $key ); if ( !is_int( $field ) && !is_string( $field ) ) { throw new UnexpectedValueException( __METHOD__ . ": invalid field for '$key'; must be string or integer." ); } return is_array( $value ) && array_key_exists( $field, $value ) && ( $maxAge === INF || $maxAge <= 0 || $this->getKeyFieldAge( $key, $field ) <= $maxAge ); } /** * @param string|int $key * @param string|int $field * @param float $maxAge Ignore items older than this many seconds [default: INF] * @return mixed Returns null if the key was not found or is older than $maxAge * @since 1.32 Added $maxAge */ public function getField( $key, $field, $maxAge = INF ) { if ( !$this->hasField( $key, $field, $maxAge ) ) { return null; } return $this->cache[$key][$field]; } /** * @return array * @since 1.25 */ public function getAllKeys() { return array_keys( $this->cache ); } /** * Get an item with the given key, producing and setting it if not found. * * If the callback returns false, then nothing is stored. * * @since 1.28 * @param string $key * @param callable $callback Callback that will produce the value * @param float $rank Bottom fraction of the list where keys start off [default: 1.0] * @param float $maxAge Ignore items older than this many seconds [default: INF] * @return mixed The cached value if found or the result of $callback otherwise * @since 1.32 Added $maxAge */ public function getWithSetCallback( $key, callable $callback, $rank = self::RANK_TOP, $maxAge = INF ) { if ( $this->has( $key, $maxAge ) ) { $value = $this->get( $key ); } else { $value = $callback(); if ( $value !== false ) { $this->set( $key, $value, $rank ); } } return $value; } /** * Format a cache key string * * @since 1.41 * @param string|int ...$components Key components * @return string */ public function makeKey( ...$components ) { // Based on BagOStuff::makeKeyInternal, except without a required // $keygroup prefix. While MapCacheLRU can and is used as cache for // multiple groups of keys, it is equally common for the instance itself // to represent a single group, and thus have keys where the first component // can directly be a user-controlled variable. $key = ''; foreach ( $components as $i => $component ) { if ( $i > 0 ) { $key .= ':'; } $key .= strtr( $component, [ '%' => '%25', ':' => '%3A' ] ); } return $key; } /** * Clear one or several cache entries, or all cache entries * * @param string|int|array|null $keys * @return void */ public function clear( $keys = null ) { if ( func_num_args() == 0 ) { $this->cache = []; $this->timestamps = []; } else { foreach ( (array)$keys as $key ) { unset( $this->cache[$key] ); unset( $this->timestamps[$key] ); } } } /** * Get the maximum number of keys allowed * * @return int * @since 1.32 */ public function getMaxSize() { return $this->maxCacheKeys; } /** * Resize the maximum number of cache entries, removing older entries as needed * * @param int $maxKeys Maximum number of entries allowed (min 1) * @return void * @since 1.32 */ public function setMaxSize( int $maxKeys ) { if ( $maxKeys <= 0 ) { throw new InvalidArgumentException( '$maxKeys must be above zero' ); } $this->maxCacheKeys = $maxKeys; while ( count( $this->cache ) > $this->maxCacheKeys ) { $evictKey = array_key_first( $this->cache ); unset( $this->cache[$evictKey] ); unset( $this->timestamps[$evictKey] ); } } /** * Push an entry to the top of the cache * * @param string $key */ private function ping( $key ) { $item = $this->cache[$key]; unset( $this->cache[$key] ); $this->cache[$key] = $item; } /** * @param string|int $key * @return float UNIX timestamp; the age of the given entry */ private function getKeyAge( $key ) { $mtime = $this->timestamps[$key][self::SIMPLE] ?? $this->epoch; return ( $this->getCurrentTime() - $mtime ); } /** * @param string|int $key * @param string|int|null $field * @return float UNIX timestamp; the age of the given entry field */ private function getKeyFieldAge( $key, $field ) { $mtime = $this->timestamps[$key][self::FIELDS][$field] ?? $this->epoch; return ( $this->getCurrentTime() - $mtime ); } public function __serialize() { return [ 'entries' => $this->cache, 'timestamps' => $this->timestamps, 'maxCacheKeys' => $this->maxCacheKeys, ]; } public function __unserialize( $data ) { $this->cache = $data['entries'] ?? []; $this->timestamps = $data['timestamps'] ?? []; // Fallback needed for serializations prior to T218511 $this->maxCacheKeys = $data['maxCacheKeys'] ?? ( count( $this->cache ) + 1 ); $this->epoch = $this->getCurrentTime(); } /** * @return float UNIX timestamp * @codeCoverageIgnore */ protected function getCurrentTime() { return $this->wallClockOverride ?: microtime( true ); } /** * @param float|null &$time Mock UNIX timestamp for testing * @codeCoverageIgnore */ public function setMockTime( &$time ) { $this->wallClockOverride =& $time; } } PK ! �7��/ �/ StringUtils.phpnu �Iw�� <?php use MediaWiki\Libs\UnpackFailedException; use Wikimedia\Assert\Assert; use Wikimedia\AtEase\AtEase; /** * Methods to play with strings. * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ /** * A collection of static methods to play with strings. */ class StringUtils { /** * Test whether a string is valid UTF-8. * * The function check for invalid byte sequences, overlong encoding but * not for different normalisations. * * @note In MediaWiki 1.21, this function did not provide proper UTF-8 validation. * In particular, the pure PHP code path did not in fact check for overlong forms. * Beware of this when backporting code to that version of MediaWiki. * * @since 1.21 * @param string $value String to check * @return bool Whether the given $value is a valid UTF-8 encoded string */ public static function isUtf8( $value ) { return mb_check_encoding( (string)$value, 'UTF-8' ); } /** * Explode a string, but ignore any instances of the separator inside * the given start and end delimiters, which may optionally nest. * The delimiters are literal strings, not regular expressions. * @param string $startDelim Start delimiter * @param string $endDelim End delimiter * @param string $separator Separator string for the explode. * @param string $subject Subject string to explode. * @param bool $nested True iff the delimiters are allowed to nest. * @return ArrayIterator */ public static function delimiterExplode( $startDelim, $endDelim, $separator, $subject, $nested = false ) { $inputPos = 0; $lastPos = 0; $depth = 0; $encStart = preg_quote( $startDelim, '!' ); $encEnd = preg_quote( $endDelim, '!' ); $encSep = preg_quote( $separator, '!' ); $len = strlen( $subject ); $m = []; $exploded = []; while ( $inputPos < $len && preg_match( "!$encStart|$encEnd|$encSep!S", $subject, $m, PREG_OFFSET_CAPTURE, $inputPos ) ) { $match = $m[0][0]; $matchPos = $m[0][1]; $inputPos = $matchPos + strlen( $match ); if ( $match === $separator ) { if ( $depth === 0 ) { $exploded[] = substr( $subject, $lastPos, $matchPos - $lastPos ); $lastPos = $inputPos; } } elseif ( $match === $startDelim ) { if ( $depth === 0 || $nested ) { $depth++; } } else { $depth--; } } $exploded[] = substr( $subject, $lastPos ); // This method could be rewritten in the future to avoid creating an // intermediate array, since the return type is just an iterator. return new ArrayIterator( $exploded ); } /** * Perform an operation equivalent to `preg_replace()` * * Matches this code: * * preg_replace( "!$startDelim(.*?)$endDelim!", $replace, $subject ); * * ..except that it's worst-case O(N) instead of O(N^2). Compared to delimiterReplace(), this * implementation is fast but memory-hungry and inflexible. The memory requirements are such * that I don't recommend using it on anything but guaranteed small chunks of text. * * @param string $startDelim * @param string $endDelim * @param string $replace * @param string $subject * @return string */ public static function hungryDelimiterReplace( $startDelim, $endDelim, $replace, $subject ) { $segments = explode( $startDelim, $subject ); $output = array_shift( $segments ); foreach ( $segments as $s ) { $endDelimPos = strpos( $s, $endDelim ); if ( $endDelimPos === false ) { $output .= $startDelim . $s; } else { $output .= $replace . substr( $s, $endDelimPos + strlen( $endDelim ) ); } } return $output; } /** * Perform an operation equivalent to `preg_replace_callback()` * * Matches this code: * * preg_replace_callback( "!$startDelim(.*)$endDelim!s$flags", $callback, $subject ); * * If the start delimiter ends with an initial substring of the end delimiter, * e.g. in the case of C-style comments, the behavior differs from the model * regex. In this implementation, the end must share no characters with the * start, so e.g. `/*\/` is not considered to be both the start and end of a * comment. `/*\/xy/*\/` is considered to be a single comment with contents `/xy/`. * * The implementation of delimiterReplaceCallback() is slower than hungryDelimiterReplace() * but uses far less memory. The delimiters are literal strings, not regular expressions. * * @param string $startDelim Start delimiter * @param string $endDelim End delimiter * @param callable $callback Function to call on each match * @param string $subject * @param string $flags Regular expression flags * @return string */ private static function delimiterReplaceCallback( $startDelim, $endDelim, $callback, $subject, $flags = '' ) { $inputPos = 0; $outputPos = 0; $contentPos = 0; $output = ''; $foundStart = false; $encStart = preg_quote( $startDelim, '!' ); $encEnd = preg_quote( $endDelim, '!' ); $strcmp = strpos( $flags, 'i' ) === false ? 'strcmp' : 'strcasecmp'; $endLength = strlen( $endDelim ); $m = []; while ( $inputPos < strlen( $subject ) && preg_match( "!($encStart)|($encEnd)!S$flags", $subject, $m, PREG_OFFSET_CAPTURE, $inputPos ) ) { $tokenOffset = $m[0][1]; if ( $m[1][0] != '' ) { if ( $foundStart && $strcmp( $endDelim, substr( $subject, $tokenOffset, $endLength ) ) == 0 ) { # An end match is present at the same location $tokenType = 'end'; $tokenLength = $endLength; } else { $tokenType = 'start'; $tokenLength = strlen( $m[0][0] ); } } elseif ( $m[2][0] != '' ) { $tokenType = 'end'; $tokenLength = strlen( $m[0][0] ); } else { throw new InvalidArgumentException( 'Invalid delimiter given to ' . __METHOD__ ); } if ( $tokenType == 'start' ) { # Only move the start position if we haven't already found a start # This means that START START END matches outer pair if ( !$foundStart ) { # Found start $inputPos = $tokenOffset + $tokenLength; # Write out the non-matching section $output .= substr( $subject, $outputPos, $tokenOffset - $outputPos ); $outputPos = $tokenOffset; $contentPos = $inputPos; $foundStart = true; } else { # Move the input position past the *first character* of START, # to protect against missing END when it overlaps with START $inputPos = $tokenOffset + 1; } } elseif ( $tokenType == 'end' ) { if ( $foundStart ) { # Found match $output .= $callback( [ substr( $subject, $outputPos, $tokenOffset + $tokenLength - $outputPos ), substr( $subject, $contentPos, $tokenOffset - $contentPos ) ] ); $foundStart = false; } else { # Non-matching end, write it out $output .= substr( $subject, $inputPos, $tokenOffset + $tokenLength - $outputPos ); } $inputPos = $outputPos = $tokenOffset + $tokenLength; } else { throw new InvalidArgumentException( 'Invalid delimiter given to ' . __METHOD__ ); } } if ( $outputPos < strlen( $subject ) ) { $output .= substr( $subject, $outputPos ); } return $output; } /** * Perform an operation equivalent to `preg_replace()` with flags. * * Matches this code: * * preg_replace( "!$startDelim(.*)$endDelim!$flags", $replace, $subject ); * * @param string $startDelim Start delimiter regular expression * @param string $endDelim End delimiter regular expression * @param string $replace Replacement string. May contain $1, which will be * replaced by the text between the delimiters * @param string $subject String to search * @param string $flags Regular expression flags * @return string The string with the matches replaced */ public static function delimiterReplace( $startDelim, $endDelim, $replace, $subject, $flags = '' ) { return self::delimiterReplaceCallback( $startDelim, $endDelim, static function ( array $matches ) use ( $replace ) { return strtr( $replace, [ '$0' => $matches[0], '$1' => $matches[1] ] ); }, $subject, $flags ); } /** * More or less "markup-safe" str_replace() * Ignores any instances of the separator inside `<...>` * @param string $search * @param string $replace * @param string $text * @return string */ public static function replaceMarkup( $search, $replace, $text ) { $placeholder = "\x00"; // Remove placeholder instances $text = str_replace( $placeholder, '', $text ); // Replace instances of the separator inside HTML-like tags with the placeholder $cleaned = self::delimiterReplaceCallback( '<', '>', static function ( array $matches ) use ( $search, $placeholder ) { return str_replace( $search, $placeholder, $matches[0] ); }, $text ); // Explode, then put the replaced separators back in $cleaned = str_replace( $search, $replace, $cleaned ); $text = str_replace( $placeholder, $search, $cleaned ); return $text; } /** * Utility function to check if the given string is a valid PCRE regex. Avoids * manually calling suppressWarnings and restoreWarnings, and provides a * one-line solution without the need to use @. * * @since 1.34 * @param string $string The string you want to check being a valid regex * @return bool */ public static function isValidPCRERegex( $string ) { AtEase::suppressWarnings(); // @phan-suppress-next-line PhanParamSuspiciousOrder False positive $isValid = preg_match( $string, '' ); AtEase::restoreWarnings(); return $isValid !== false; } /** * Escape a string to make it suitable for inclusion in a preg_replace() * replacement parameter. * * @param string $string * @return string */ public static function escapeRegexReplacement( $string ) { $string = str_replace( '\\', '\\\\', $string ); return str_replace( '$', '\\$', $string ); } /** * Workalike for explode() with limited memory usage. * * @param string $separator * @param string $subject * @return ArrayIterator|ExplodeIterator */ public static function explode( $separator, $subject ) { if ( substr_count( $subject, $separator ) > 1000 ) { return new ExplodeIterator( $separator, $subject ); } else { return new ArrayIterator( explode( $separator, $subject ) ); } } /** * Wrapper around php's unpack. * * @param string $format The format string (See php's docs) * @param string $data A binary string of binary data * @param int|false $length The minimum length of $data or false. This is to * prevent reading beyond the end of $data. false to disable the check. * * Also be careful when using this function to read unsigned 32 bit integer * because php might make it negative. * * @throws UnpackFailedException If $data not long enough, or if unpack fails * @return array Associative array of the extracted data * @since 1.42 */ public static function unpack( string $format, string $data, $length = false ): array { Assert::parameterType( [ 'integer', 'false' ], $length, '$length' ); if ( $length !== false ) { $realLen = strlen( $data ); if ( $realLen < $length ) { throw new UnpackFailedException( "Tried to unpack a " . "string of length $realLen, but needed one " . "of at least length $length." ); } } AtEase::suppressWarnings(); $result = unpack( $format, $data ); AtEase::restoreWarnings(); if ( $result === false ) { // If it cannot extract the packed data. throw new UnpackFailedException( "unpack could not unpack binary data" ); } return $result; } } PK ! ���^ ^ CookieJar.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file * @ingroup HTTP */ /** * Cookie jar to use with MWHttpRequest. Does not handle cookie unsetting. */ class CookieJar { /** @var Cookie[] */ private $cookie = []; /** * Set a cookie in the cookie jar. Make sure only one cookie per-name exists. * @see Cookie::set() * @param string $name * @param string $value * @param array $attr */ public function setCookie( $name, $value, $attr ) { /* cookies: case insensitive, so this should work. * We'll still send the cookies back in the same case we got them, though. */ $index = strtoupper( $name ); if ( isset( $this->cookie[$index] ) ) { $this->cookie[$index]->set( $value, $attr ); } else { $this->cookie[$index] = new Cookie( $name, $value, $attr ); } } /** * @see Cookie::serializeToHttpRequest * @param string $path * @param string $domain * @return string */ public function serializeToHttpRequest( $path, $domain ) { $cookies = []; foreach ( $this->cookie as $c ) { $serialized = $c->serializeToHttpRequest( $path, $domain ); if ( $serialized ) { $cookies[] = $serialized; } } return implode( '; ', $cookies ); } /** * Parse the content of an Set-Cookie HTTP Response header. * * @param string $cookie * @param string $domain Cookie's domain * @return null */ public function parseCookieResponseHeader( $cookie, $domain ) { $len = strlen( 'Set-Cookie:' ); if ( substr_compare( 'Set-Cookie:', $cookie, 0, $len, true ) === 0 ) { $cookie = substr( $cookie, $len ); } $bit = array_map( 'trim', explode( ';', $cookie ) ); if ( count( $bit ) >= 1 ) { [ $name, $value ] = explode( '=', array_shift( $bit ), 2 ); $attr = []; foreach ( $bit as $piece ) { $parts = explode( '=', $piece ); if ( count( $parts ) > 1 ) { $attr[strtolower( $parts[0] )] = $parts[1]; } else { $attr[strtolower( $parts[0] )] = true; } } if ( !isset( $attr['domain'] ) ) { $attr['domain'] = $domain; } elseif ( !Cookie::validateCookieDomain( $attr['domain'], $domain ) ) { return null; } $this->setCookie( $name, $value, $attr ); } } } PK ! !h#] ] StaticArrayWriter.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. * */ namespace Wikimedia; /** * Format a static PHP array to be written to a file * * @newable * @since 1.32 */ class StaticArrayWriter { /** * @param array $data Array with keys/values to export * @param string $header * @return string PHP code */ public function create( array $data, $header = 'Automatically generated' ) { return self::write( $data, $header ); } /** * Create a PHP file that returns the array. * * @since 1.35 * @param array $data Array with keys/values to export * @param string $header * @return string PHP code */ public static function write( array $data, $header ) { $code = "<?php\n" . "// " . implode( "\n// ", explode( "\n", $header ) ) . "\n" . "return " . self::encodeArray( $data ) . ";\n"; return $code; } /** * Create an PHP class file with the array as a class constant. * * PHP classes can be autoloaded by name, which allows usage to be decoupled * from the file path. * * @since 1.37 * @param array $data * @param array{header:string,namespace:string,class:string,const:string} $layout * @return string PHP code */ public static function writeClass( array $data, array $layout ) { $code = "<?php\n" . "// " . implode( "\n// ", explode( "\n", $layout['header'] ) ) . "\n" . "\n" . "namespace {$layout['namespace']};\n" . "\n" . "class {$layout['class']} {\n" . "\tpublic const {$layout['const']} = " . self::encodeArray( $data, 1 ) . ";\n}\n"; return $code; } /** * Recursively turn an array into properly-indented PHP * * @param array $array * @param int $indent Indentation level * @return string PHP code */ private static function encodeArray( array $array, $indent = 0 ) { $code = "[\n"; $tabs = str_repeat( "\t", $indent ); if ( array_is_list( $array ) ) { foreach ( $array as $item ) { $code .= self::encodeItem( $item, $indent + 1 ); } } else { foreach ( $array as $key => $value ) { $code .= self::encodePair( $key, $value, $indent + 1 ); } } $code .= "$tabs]"; return $code; } /** * Recursively turn one k/v pair into properly-indented PHP * * @param string|int $key * @param mixed $value * @param int $indent Indentation level * @return string PHP code */ private static function encodePair( $key, $value, $indent = 0 ) { $tabs = str_repeat( "\t", $indent ); $line = $tabs . var_export( $key, true ) . ' => '; $line .= self::encodeValue( $value, $indent ); $line .= ",\n"; return $line; } /** * Recursively turn one list item into properly-indented PHP * * @param mixed $value * @param int $indent Indentation level * @return string PHP code */ private static function encodeItem( $value, $indent = 0 ) { $tabs = str_repeat( "\t", $indent ); $line = $tabs . self::encodeValue( $value, $indent ); $line .= ",\n"; return $line; } /** * Recursively turn one value into properly-indented PHP * * @since 1.38 * @param mixed $value * @param int $indent Indentation level * @return string PHP code */ public static function encodeValue( $value, $indent = 0 ) { if ( is_array( $value ) ) { return self::encodeArray( $value, $indent ); } else { $exportedValue = var_export( $value, true ); if ( $exportedValue === 'NULL' ) { // var_export() exports nulls as uppercase NULL which // violates our own coding standards. $exportedValue = 'null'; } return $exportedValue; } } } PK ! � ��� � DebugInfo/Placeholder.phpnu �Iw�� <?php namespace Wikimedia\DebugInfo; /** * A class used for replacing large objects in var_dump() output. * * @since 1.40 */ class Placeholder { /** @var string A description of the replaced object */ public $desc; /** * @param mixed $value */ public function __construct( $value ) { if ( is_object( $value ) ) { $this->desc = get_class( $value ) . '#' . spl_object_id( $value ); } else { $this->desc = get_debug_type( $value ); } } } PK ! Wa� � � DebugInfo/AnnotationReader.phpnu �Iw�� <?php namespace Wikimedia\DebugInfo; /** * Utility class for reading doc comment annotations * * @since 1.40 */ class AnnotationReader { /** @var bool[] */ private static $cache = []; /** * Determine whether a ReflectionProperty has a specified annotation * * @param \ReflectionProperty $property * @param string $annotationName * @return bool */ public static function propertyHasAnnotation( \ReflectionProperty $property, string $annotationName ) { $cacheKey = "$annotationName@{$property->class}::{$property->name}"; if ( !isset( self::$cache[$cacheKey] ) ) { $comment = $property->getDocComment(); if ( $comment === false ) { self::$cache[$cacheKey] = false; } else { $encAnnotation = preg_quote( $annotationName, '!' ); self::$cache[$cacheKey] = (bool)preg_match( "!^[ \t]*(/\*\*|\*)[ \t]*@$encAnnotation\b!im", $comment ); } } return self::$cache[$cacheKey]; } } PK ! �WX X DebugInfo/DebugInfoTrait.phpnu �Iw�� <?php namespace Wikimedia\DebugInfo; /** * A trait for automatic __debugInfo() modifications. * * Recursion into properties is prevented if they have a @noVarDump annotation * in their doc comment. See T277618. * * @since 1.40 */ trait DebugInfoTrait { public function __debugInfo() { return DumpUtils::objectToArray( $this ); } } PK ! �j Z� � DebugInfo/DumpUtils.phpnu �Iw�� <?php namespace Wikimedia\DebugInfo; /** * @since 1.40 */ class DumpUtils { /** * Convert an object to an array by casting, but filter the properties * to make recursive dumping more feasible. * * phpcs:ignore MediaWiki.Commenting.FunctionComment.ObjectTypeHintParam * @param object $object * @return array * @throws \ReflectionException */ public static function objectToArray( $object ) { $vars = (array)$object; $class = new \ReflectionClass( $object ); while ( $class ) { foreach ( $class->getProperties() as $property ) { if ( AnnotationReader::propertyHasAnnotation( $property, 'noVarDump' ) ) { // Ref: zend_declare_typed_property(), zend_mangle_property_name() if ( $property->isPrivate() ) { $mangledName = "\0{$class->name}\0{$property->name}"; } elseif ( $property->isProtected() ) { $mangledName = "\0*\0{$property->name}"; } else { $mangledName = $property->name; } if ( isset( $vars[$mangledName] ) && !is_scalar( $vars[$mangledName] ) ) { $vars[$mangledName] = new Placeholder( $vars[$mangledName] ); } } } $class = $class->getParentClass(); } return $vars; } } PK ! �VP& & WRStats/README.mdnu �Iw�� WRStats is a library for production-compatible metric storage and retrieval. ## Data model Currently, only counters are supported, in the RRDTool sense of an increment-only value with some support for calculating derivatives (rates). Memcached is the intended data store. Since memcached does not support floating-point increment, metrics can be transparently scaled by a resolution factor. Each metric can contain multiple time-series sequences. A sequence is a set of counter values, equally spaced in time, with a fixed retention period. So for example, a metric might contain a sequence with a value for each second, expiring after one minute, and a sequence with a value for each minute, expiring after one hour. To read a rate, a sequence is selected, then all buckets in the requested time range are fetched. When the boundary of the time range does not exactly coincide with the boundary of a bucket, interpolation is applied, to scale down the counter value from the bucket. Interpolation assumes that the rate of events in the time window is constant. If the end of the bucket would be after the current time, the current time is used as the bucket end time for interpolation purposes. In other words, the number of events in the future is assumed to be zero; all events are assumed to be in the past. ## Storage keys Storage keys are composed of an array of components, conventionally joined by the storage class into a string key separated by colons: <prefix> : <metric name> : <sequence name> : <time> [ : <entity key> ] * The prefix is a string or array of strings which are fixed for a given factory. The prefix is supposed to identify the caller. * The metric name identifies the metric in the configuration. * The sequence name identifies the sequence. If there is only one unnamed sequence, its name is the empty string. Subsequent sequences will be named after their key in the configuration array. An explicit sequence name can be given if desired for stability. * The time bucket is identified by an integer. * Additional key components can be supplied. This "entity key" is used to distinguish different instances of a metric which share the same configuration. For example, if you want to count the number of edits by each user, the entity key could include the user ID. Entity keys may either be local (LocalEntityKey) or global (GlobalEntityKey). This flag is passed down to the storage class. If a local entity key is supplied, MediaWiki will prefix the key with the name of the wiki. ## Usage ```php $specs = [ 'a' => [ 'type' => 'counter', 'sequences' => [ [ 'timeStep' => 10, 'expiry' => 3600, ] ], 'resolution' => 1, ], 'b' => [ 'type' => 'counter', 'resolution' => 0.01, 'sequences' => [ [ 'timeStep' => 1, 'expiry' => 60, ] ] ], ]; $entity = new LocalEntityKey( [ 'user_id' => 1 ] ); $wrstatsFactory = MediaWikiServices::getInstance()->getWRStatsFactory(); $writer = $wrstatsFactory->createWriter( $specs ); $writer->incr( 'a', $entity, 1 ); $writer->incr( 'b', $entity, 25 ); $writer->flush(); $reader = $wrstatsFactory->createReader( $specs ); $rateA = $reader->getRate( 'a', $entity, $reader->latest( 60 ) ); $rateB = $reader->getRate( 'b', $entity, $reader->latest( 120 ) ); print $rateA->perSecond(); print $rateB->perMinute(); ``` ## Rate limiter WRStatsRateLimiter uses underlying WRStats metrics to implement rate limiting functionality. The rate limiter allows you to limit the number of actions in a rolling time window. WRStats does not require a synchronous data store, so the counter may overshoot its limit slightly before actions are prevented. Typical usage: ```php $wrstatsFactory = MediaWikiServices::getInstance()->getWRStatsFactory(); $rateLimiter = $wrstatsFactory->createRateLimiter( 'by_user' => [ new LimitCondition( 10, 60 ) // 10 edits per minute ], 'MyLimitCaller' ); $entity = new LocalEntityKey( [ 'user_id', 1 ] ); if ( $rateLimiter->tryIncr( 'by_user', $entity )->isAllowed() ) { // perform the action } ``` PK ! c%�"H H WRStats/WRStatsFactory.phpnu �Iw�� <?php namespace Wikimedia\WRStats; /** * The main entry point to WRStats, for creating readers and writers. * * Readers and writers should generally be used for a batch and then discarded. * Factory objects can be retained indefinitely. * * @since 1.39 */ class WRStatsFactory { /** @var StatsStore */ private $store; /** @var float|int|null */ private $now; /** * @param StatsStore $store */ public function __construct( StatsStore $store ) { $this->store = $store; } /** * Create a writer. Writers gather a batch of increment operations and then * commit them when flush() is called, or when the writer is destroyed. * * @param array $specs An array of metric specification arrays, indexed by * name, where each element is an associative array with the following * keys (all optional): * - type: (string) Always "counter" * - resolution: (int|float) The resolution of the counter value. * For example, if this is 0.01, counters will be rounded to two * decimal places. Necessary because we support backends that only * store integers, but we present an interface that allows float * values. * - sequences: (array) An array of sequence specification, each * sequence spec being an associative array with the following keys: * - expiry: (int|float) The expiry time of the counters, in seconds. * - timeStep: (int|float) The time duration represented by a counter * bucket. If this is too small, many buckets will be required, * making fetches slower. If this is too large, there will be some * jitter in the resulting rates as the current time moves from one * bucket to the next. * * @param string|string[] $prefix A string or array of strings to prefix * before storage keys. * @return WRStatsWriter */ public function createWriter( $specs, $prefix = 'WRStats' ) { $writer = new WRStatsWriter( $this->store, $specs, $prefix ); if ( $this->now !== null ) { $writer->setCurrentTime( $this->now ); } return $writer; } /** * Create a reader. Readers gather a batch of read operations, returning * promises. The batch is executed when the first promise is resolved. * * @see createWriter * * @param array $specs * @param string|string[] $prefix * @return WRStatsReader */ public function createReader( $specs, $prefix = 'WRStats' ) { $reader = new WRStatsReader( $this->store, $specs, $prefix ); if ( $this->now !== null ) { $reader->setCurrentTime( $this->now ); } return $reader; } /** * Create a rate limiter. * * @param LimitCondition[] $conditions An array in which the key is the * condition name, and the value is a LimitCondition describing the limit. * @param string|string[] $prefix A string or array of strings to prefix * before storage keys. * @param array $options An associative array of options: * - bucketCount: Each window is divided into this many time buckets. * Fetching the current count will typically result in a request for * this many keys. * @return WRStatsRateLimiter */ public function createRateLimiter( $conditions, $prefix = 'WRStats', $options = [] ) { $rateLimiter = new WRStatsRateLimiter( $this->store, $conditions, $prefix, $options ); if ( $this->now !== null ) { $rateLimiter->setCurrentTime( $this->now ); } return $rateLimiter; } /** * Set a current timestamp to be injected into new instances on creation * * @param float|int $now Seconds since epoch */ public function setCurrentTime( $now ) { $this->now = $now; } } PK ! @��� � WRStats/WRStatsRateLimiter.phpnu �Iw�� <?php namespace Wikimedia\WRStats; /** * A rate limiter with a WRStats backend * * @since 1.39 */ class WRStatsRateLimiter { /** @var StatsStore */ private $store; /** @var LimitCondition[] */ private $conditions; /** @var array */ private $specs; /** @var string|string[] */ private $prefix; /** @var float|int|null */ private $now; /** Default number of time buckets per action */ public const BUCKET_COUNT = 30; /** * @internal Use WRStatsFactory::createRateLimiter instead * @param StatsStore $store * @param LimitCondition[] $conditions * @param string|string[] $prefix * @param array $options */ public function __construct( StatsStore $store, $conditions, $prefix = 'WRLimit', $options = [] ) { $this->store = $store; $this->conditions = $conditions; $this->prefix = $prefix; $bucketCount = $options['bucketCount'] ?? self::BUCKET_COUNT; $specs = []; foreach ( $conditions as $name => $condition ) { $specs[$name] = [ 'sequences' => [ [ 'timeStep' => $condition->window / $bucketCount, 'expiry' => $condition->window ] ] ]; } $this->specs = $specs; } /** * Create a batch object for rate limiting of multiple metrics. * * @param int $defaultAmount The amount to increment each metric by, if no * amount is passed to localOp/globalOp * @return LimitBatch */ public function createBatch( $defaultAmount = 1 ) { return new LimitBatch( $this, $defaultAmount ); } /** * Check whether executing a single operation would exceed the defined limit, * without incrementing the count. * * @param string $condName * @param EntityKey|null $entityKey * @param int $amount * @return LimitOperationResult */ public function peek( string $condName, ?EntityKey $entityKey = null, $amount = 1 ): LimitOperationResult { $actions = [ new LimitOperation( $condName, $entityKey, $amount ) ]; $result = $this->peekBatch( $actions ); return $result->getAllResults()[0]; } /** * Check whether executing a given set of increment operations would exceed * any defined limit, without actually performing the increment. * * @param LimitOperation[] $operations * @return LimitBatchResult */ public function peekBatch( array $operations ) { $reader = new WRStatsReader( $this->store, $this->specs, $this->prefix ); if ( $this->now !== null ) { $reader->setCurrentTime( $this->now ); } $rates = []; $amounts = []; foreach ( $operations as $operation ) { $name = $operation->condName; $cond = $this->conditions[$name] ?? null; if ( $cond === null ) { throw new WRStatsError( "Unrecognized metric \"$name\"" ); } if ( !isset( $rates[$name] ) ) { $range = $reader->latest( $cond->window ); $rates[$name] = $reader->getRate( $name, $operation->entityKey, $range ); $amounts[$name] = 0; } $amounts[$name] += $operation->amount; } $results = []; foreach ( $operations as $i => $operation ) { $name = $operation->condName; $total = $rates[$name]->total(); $cond = $this->conditions[$name]; $results[$i] = new LimitOperationResult( $cond, $total, $total + $amounts[$name] ); } return new LimitBatchResult( $results ); } /** * Check if the limit would be exceeded by incrementing the specified * metric. If not, increment it. * * @param string $condName * @param EntityKey|null $entityKey * @param int $amount * @return LimitOperationResult */ public function tryIncr( string $condName, ?EntityKey $entityKey = null, $amount = 1 ): LimitOperationResult { $actions = [ new LimitOperation( $condName, $entityKey, $amount ) ]; $result = $this->tryIncrBatch( $actions ); return $result->getAllResults()[0]; } /** * Check if the limit would be exceeded by execution of the given set of * increment operations. If not, perform the increments. * * @param LimitOperation[] $operations * @return LimitBatchResult */ public function tryIncrBatch( array $operations ) { $result = $this->peekBatch( $operations ); if ( $result->isAllowed() ) { $this->incrBatch( $operations ); } return $result; } /** * Unconditionally increment a metric. * * @param string $condName * @param EntityKey|null $entityKey * @param int $amount * @return void */ public function incr( string $condName, ?EntityKey $entityKey = null, $amount = 1 ) { $actions = [ new LimitOperation( $condName, $entityKey, $amount ) ]; $this->incrBatch( $actions ); } /** * Unconditionally increment a set of metrics. * * @param LimitOperation[] $operations */ public function incrBatch( array $operations ) { $writer = new WRStatsWriter( $this->store, $this->specs, $this->prefix ); if ( $this->now !== null ) { $writer->setCurrentTime( $this->now ); } foreach ( $operations as $operation ) { $writer->incr( $operation->condName, $operation->entityKey, $operation->amount ); } $writer->flush(); } /** * Set the current time. * * @param float|int $now */ public function setCurrentTime( $now ) { $this->now = $now; } /** * Forget a time set with setCurrentTime(). Use the actual current time. */ public function resetCurrentTime() { $this->now = null; } } PK ! �0� � � WRStats/LocalEntityKey.phpnu �Iw�� <?php namespace Wikimedia\WRStats; /** * Entity key with isGlobal=false * * @newable * @since 1.39 */ class LocalEntityKey extends EntityKey { public function isGlobal() { return false; } } PK ! ��v � WRStats/WRStatsWriter.phpnu �Iw�� <?php namespace Wikimedia\WRStats; /** * Writers gather a batch of increment operations and then * commit them when flush() is called, or when the writer is destroyed. * * @since 1.39 */ class WRStatsWriter { /** @var StatsStore */ private $store; /** @var array<string,MetricSpec> */ private $metricSpecs; /** @var float[][] Values indexed by TTL and storage key */ private $queuedValues = []; /** @var float|int|null The UNIX timestamp used for the current time */ private $now; /** @var string[] */ private $prefixComponents; /** * @internal Use WRStatsFactory::createWriter instead * @param StatsStore $store * @param array<string,array> $specs * @param string|string[] $prefix */ public function __construct( StatsStore $store, $specs, $prefix ) { $this->store = $store; $this->metricSpecs = []; foreach ( $specs as $name => $spec ) { $this->metricSpecs[$name] = new MetricSpec( $spec ); } $this->prefixComponents = is_array( $prefix ) ? $prefix : [ $prefix ]; if ( !count( $this->prefixComponents ) ) { throw new WRStatsError( __METHOD__ . ': there must be at least one prefix component' ); } } /** * Queue an increment operation. * * @param string $name The metric name * @param EntityKey|null $entity Additional storage key components * @param float|int $value The value to add */ public function incr( $name, ?EntityKey $entity = null, $value = 1 ) { $metricSpec = $this->metricSpecs[$name] ?? null; $entity ??= new LocalEntityKey; if ( $metricSpec === null ) { throw new WRStatsError( "Unrecognised metric \"$name\"" ); } $res = $metricSpec->resolution; $scaledValue = $value / $res; foreach ( $metricSpec->sequences as $seqSpec ) { $timeStep = $seqSpec->timeStep; $timeBucket = (int)( $this->now() / $timeStep ); $key = $this->store->makeKey( $this->prefixComponents, [ $name, $seqSpec->name, $timeBucket ], $entity ); $ttl = $seqSpec->hardExpiry; if ( !isset( $this->queuedValues[$ttl][$key] ) ) { $this->queuedValues[$ttl][$key] = 0; } $this->queuedValues[$ttl][$key] += (int)round( $scaledValue ); } } /** * Set the time to be used as the current time * * @param float|int $now */ public function setCurrentTime( $now ) { $this->now = $now; } /** * Reset the stored current time. In a long-running process this should be * called regularly to write new results. * * @return void */ public function resetCurrentTime() { $this->now = null; } /** * @return float|int */ private function now() { $this->now ??= microtime( true ); return $this->now; } /** * Commit the batch of increment operations. */ public function flush() { foreach ( $this->queuedValues as $ttl => $values ) { $this->store->incr( $values, $ttl ); } $this->queuedValues = []; } /** * Commit the batch of increment operations. */ public function __destruct() { $this->flush(); } /** * Delete all stored metrics corresponding to the specs supplied to the * constructor, resetting the counters to zero. * * @param EntityKey[]|null $entities An array of additional storage key * components. The default is the empty local entity. */ public function resetAll( ?array $entities = null ) { $entities ??= [ new LocalEntityKey ]; $this->queuedValues = []; $keys = []; foreach ( $this->metricSpecs as $name => $metricSpec ) { foreach ( $metricSpec->sequences as $seqSpec ) { $timeStep = $seqSpec->timeStep; $ttl = $seqSpec->hardExpiry; $lastBucket = (int)( $this->now() / $timeStep ) + 1; $firstBucket = (int)( ( $this->now() - $ttl ) / $timeStep ) - 1; for ( $bucket = $firstBucket; $bucket <= $lastBucket; $bucket++ ) { foreach ( $entities as $entity ) { $keys[] = $this->store->makeKey( $this->prefixComponents, [ $name, $seqSpec->name, $bucket ], $entity ); } } } } $this->store->delete( $keys ); } } PK ! �:�� � WRStats/EntityKey.phpnu �Iw�� <?php namespace Wikimedia\WRStats; /** * Base class for entity keys. An entity key is an array of storage key * components which can be used to distinguish stats with the same metric name. * The entity key object also carries a global flag which is passed through to * the store. * * @since 1.39 */ abstract class EntityKey { /** @var array */ private $components; /** * @param array $components Array of elements, each convertible to string. */ public function __construct( array $components = [] ) { $this->components = $components; } /** * @return array */ public function getComponents() { return $this->components; } /** * @return bool */ abstract public function isGlobal(); } PK ! R�] WRStats/LimitBatch.phpnu �Iw�� <?php namespace Wikimedia\WRStats; /** * A class representing a batch of increment/peek operations on a WRStatsRateLimiter * * @since 1.39 */ class LimitBatch { /** @var WRStatsRateLimiter */ private $limiter; /** @var int */ private $defaultAmount; /** @var LimitOperation[] */ private $operations = []; /** * @internal Use WRStatsFactory::createRateLimiter()->createBatch() instead * @param WRStatsRateLimiter $limiter * @param int $defaultAmount */ public function __construct( WRStatsRateLimiter $limiter, $defaultAmount ) { $this->limiter = $limiter; $this->defaultAmount = $defaultAmount; } /** * Construct a local entity key and queue an operation for it. * * @param string $condName The condition name to be incremented/tested, * which must match one of the ones passed to createRateLimiter() * @param mixed $components Entity key component or array of components * @param int|null $amount The amount to increment by, or null to use the default * @return $this */ public function localOp( $condName, $components = [], $amount = null ) { if ( !is_array( $components ) ) { $components = [ $components ]; } $this->queueOp( $condName, new LocalEntityKey( array_merge( [ $condName ], $components ) ), $amount ); return $this; } /** * Construct a global entity key and queue an operation for it. * * @param string $condName The condition name to be incremented/tested, * which must match one of the ones passed to createRateLimiter() * @param mixed $components Entity key components * @param int|null $amount The amount, or null to use the default * @return $this */ public function globalOp( $condName, $components = [], $amount = null ) { if ( !is_array( $components ) ) { $components = [ $components ]; } $this->queueOp( $condName, new GlobalEntityKey( array_merge( [ $condName ], $components ) ), $amount ); return $this; } private function queueOp( $type, $entity, $amount ) { $amount ??= $this->defaultAmount; if ( isset( $this->operations[$type] ) ) { throw new WRStatsError( 'Cannot queue multiple actions of the same type, ' . 'because the result array is indexed by type' ); } $this->operations[$type] = new LimitOperation( $type, $entity, $amount ); } /** * Execute the batch, checking each operation against the defined limit, * but don't actually increment the metrics. * * @return LimitBatchResult */ public function peek() { return $this->limiter->peekBatch( $this->operations ); } /** * Execute the batch, unconditionally incrementing all the specified metrics. */ public function incr() { $this->limiter->incrBatch( $this->operations ); } /** * Execute the batch, checking each operation against the defined limit. * If all operations are allowed, all metrics will be incremented. If some * of the operations exceed the limit, none of the metrics will be * incremented. * * @return LimitBatchResult */ public function tryIncr() { return $this->limiter->tryIncrBatch( $this->operations ); } } PK ! '�[r r WRStats/RatePromise.phpnu �Iw�� <?php namespace Wikimedia\WRStats; /** * A WRStats query result promise. It contains the input parameters to a query. * When an accessor method is called, it triggers batch query execution in the * parent WRStatsReader. * * @since 1.39 */ class RatePromise { /** @var WRStatsReader */ private $reader; /** @var string */ private $name; /** @var EntityKey */ private $entity; /** @var MetricSpec */ private $metricSpec; /** @var SequenceSpec */ private $seqSpec; /** @var TimeRange */ private $range; /** @var int|float|null Lazy-initialised query result */ private $total; /** * @internal Use via WRStatsReader from WRStatsFactory::createReader instead * @param WRStatsReader $reader * @param string $name * @param EntityKey $entity * @param MetricSpec $metricSpec * @param SequenceSpec $seqSpec * @param TimeRange $range */ public function __construct( WRStatsReader $reader, string $name, EntityKey $entity, MetricSpec $metricSpec, SequenceSpec $seqSpec, TimeRange $range ) { $this->reader = $reader; $this->name = $name; $this->entity = $entity; $this->metricSpec = $metricSpec; $this->seqSpec = $seqSpec; $this->range = $range; } /** * Get the total counter value summed over the specified time range. * * @return float|int */ public function total() { if ( $this->total === null ) { $this->total = $this->reader->internalGetCount( $this->name, $this->entity, $this->metricSpec, $this->seqSpec, $this->range ); } return $this->total; } /** * Get the counter value as a rate per second. * * @return float */ public function perSecond() { return $this->total() / $this->range->getDuration(); } /** * Get the counter value as a rate per minute * * @return float */ public function perMinute() { return $this->perSecond() * 60; } /** * Get the counter value as a rate per hour * * @return float */ public function perHour() { return $this->perSecond() * 3600; } /** * Get the counter value as a rate per day * * @return float */ public function perDay() { return $this->perSecond() * 86400; } } PK ! vѯV V WRStats/MetricSpec.phpnu �Iw�� <?php namespace Wikimedia\WRStats; /** * Class representation of normalized metric specifications * * @internal */ class MetricSpec { /** The default (value axis) resolution */ public const DEFAULT_RESOLUTION = 1; /** @var string */ public $type; /** @var float|int */ public $resolution; /** @var array<string,SequenceSpec> Sequences in ascending order of expiry */ public $sequences; /** * @param array $spec */ public function __construct( array $spec ) { $this->type = $spec['type'] ?? 'counter'; $this->resolution = $spec['resolution'] ?? self::DEFAULT_RESOLUTION; foreach ( [ 'timeStep', 'expiry' ] as $var ) { if ( isset( $spec[$var] ) ) { throw new WRStatsError( "$var must be in the sequences array" ); } } $seqArrays = $spec['sequences'] ?? []; if ( !$seqArrays ) { $seqArrays = [ [] ]; } $sequences = []; foreach ( $seqArrays as $i => $seqArray ) { if ( !is_array( $seqArray ) ) { throw new WRStatsError( 'sequences must be an array of arrays' ); } $seqSpec = new SequenceSpec( $seqArray ); while ( isset( $sequences[$seqSpec->name] ) ) { $seqSpec->name .= "s$i"; } $sequences[$seqSpec->name] = $seqSpec; } uasort( $sequences, static function ( SequenceSpec $a, SequenceSpec $b ) { return $a->hardExpiry <=> $b->hardExpiry; } ); $this->sequences = $sequences; } } PK ! �pN�4 4 WRStats/LimitCondition.phpnu �Iw�� <?php namespace Wikimedia\WRStats; /** * @since 1.39 * @newable */ class LimitCondition { /** @var int The maximum number of events */ public $limit; /** @var float|int The number of seconds over which the number of events may occur */ public $window; /** * @param int|float|string $limit The maximum number of events * @param int|float|string $window The number of seconds over which the * number of events may occur */ public function __construct( $limit, $window ) { $this->limit = (int)$limit; $this->window = +$window; if ( $this->window <= 0 ) { throw new WRStatsError( 'Condition window must be positive' ); } } /** * Get the condition as a number of events per second * * @return float|int */ public function perSecond() { return $this->limit / $this->window; } } PK ! =NV�~! ~! WRStats/WRStatsReader.phpnu �Iw�� <?php namespace Wikimedia\WRStats; /** * Readers gather a batch of read operations, returning * promises. The batch is executed when the first promise is resolved. * * @since 1.39 */ class WRStatsReader { /** @var StatsStore */ private $store; /** @var array<string,MetricSpec> */ private $metricSpecs; /** @var string[] */ private $prefixComponents; /** @var float|int|null The UNIX timestamp used for the current time */ private $now; /** @var bool[] Storage keys ready to be fetched */ private $queuedKeys = []; /** @var int[] Unscaled integers returned by the store, indexed by key */ private $cachedValues = []; /** * @internal Use WRStatsFactory::createReader instead * @param StatsStore $store * @param array<string,array> $specs * @param string|string[] $prefix */ public function __construct( StatsStore $store, $specs, $prefix ) { $this->store = $store; $this->metricSpecs = []; foreach ( $specs as $name => $spec ) { $this->metricSpecs[$name] = new MetricSpec( $spec ); } $this->prefixComponents = is_array( $prefix ) ? $prefix : [ $prefix ]; if ( !count( $this->prefixComponents ) ) { throw new WRStatsError( __METHOD__ . ': there must be at least one prefix component' ); } } /** * Get a TimeRange for some period ending at the current time. Note that * this will use the same value of the current time for subsequent calls * until resetCurrentTime() is called. * * @param int|float $numSeconds * @return TimeRange */ public function latest( $numSeconds ) { $now = $this->now(); return new TimeRange( $now - $numSeconds, $now ); } /** * Get a specified time range * * @param int|float $start The UNIX time of the start of the range * @param int|float $end The UNIX time of the end of the range * @return TimeRange */ public function timeRange( $start, $end ) { return new TimeRange( $start, $end ); } /** * Queue a fetch operation. * * @param string $metricName The metric name, the key into $specs. * @param EntityKey|null $entity Additional storage key components * @param TimeRange $range The time range to fetch * @return RatePromise */ public function getRate( $metricName, ?EntityKey $entity, TimeRange $range ) { $metricSpec = $this->metricSpecs[$metricName] ?? null; if ( $metricSpec === null ) { throw new WRStatsError( "Unrecognised metric \"$metricName\"" ); } $entity ??= new LocalEntityKey; $now = $this->now(); $seqSpec = null; foreach ( $metricSpec->sequences as $seqSpec ) { $seqStart = $now - $seqSpec->softExpiry; if ( $seqStart <= $range->start ) { break; } } if ( !$seqSpec ) { // This check exists to make Phan happy. // It should never fail since we apply normalization in MetricSpec::__construct() throw new WRStatsError( 'There should have been at least one sequence' ); } $timeStep = $seqSpec->timeStep; $firstBucket = (int)( $range->start / $timeStep ); $lastBucket = (int)ceil( $range->end / $timeStep ); for ( $bucket = $firstBucket; $bucket <= $lastBucket; $bucket++ ) { $key = $this->store->makeKey( $this->prefixComponents, [ $metricName, $seqSpec->name, $bucket ], $entity ); if ( !isset( $this->cachedValues[$key] ) ) { $this->queuedKeys[$key] = true; } } return new RatePromise( $this, $metricName, $entity, $metricSpec, $seqSpec, $range ); } /** * Queue a batch of fetch operations for different metrics with the same * time range. * * @param string[] $metricNames * @param EntityKey|null $entity * @param TimeRange $range * @return RatePromise[] */ public function getRates( $metricNames, ?EntityKey $entity, TimeRange $range ) { $rates = []; foreach ( $metricNames as $name ) { $rates[$name] = $this->getRate( $name, $entity, $range ); } return $rates; } /** * Perform any queued fetch operations. */ public function fetch() { if ( !$this->queuedKeys ) { return; } $this->cachedValues += $this->store->query( array_keys( $this->queuedKeys ) ); $this->queuedKeys = []; } /** * Set the current time to be used in latest() etc. * * @param int|float $now */ public function setCurrentTime( $now ) { $this->now = $now; } /** * Clear the current time so that it will be filled with the real current * time on the next call. */ public function resetCurrentTime() { $this->now = null; } /** * @return float|int */ private function now() { $this->now ??= microtime( true ); return $this->now; } /** * @internal Utility for resolution in RatePromise * @param string $metricName * @param EntityKey $entity * @param MetricSpec $metricSpec * @param SequenceSpec $seqSpec * @param TimeRange $range * @return float|int */ public function internalGetCount( $metricName, EntityKey $entity, MetricSpec $metricSpec, SequenceSpec $seqSpec, TimeRange $range ) { $this->fetch(); $timeStep = $seqSpec->timeStep; $firstBucket = (int)( $range->start / $timeStep ); $lastBucket = (int)( $range->end / $timeStep ); $now = $this->now(); $total = 0; for ( $bucket = $firstBucket; $bucket <= $lastBucket; $bucket++ ) { $key = $this->store->makeKey( $this->prefixComponents, [ $metricName, $seqSpec->name, $bucket ], $entity ); $value = $this->cachedValues[$key] ?? 0; if ( !$value ) { continue; } elseif ( $bucket === $firstBucket ) { if ( $bucket === $lastBucket ) { // It can be assumed that there are zero events in the future $bucketStartTime = $bucket * $timeStep; $rateInterpolationEndTime = min( $bucketStartTime + $timeStep, $now ); $interpolationDuration = $rateInterpolationEndTime - $bucketStartTime; if ( $interpolationDuration > 0 ) { $total += $value * $range->getDuration() / $interpolationDuration; } } else { $overlapDuration = max( ( $bucket + 1 ) * $timeStep - $range->start, 0 ); $total += $value * $overlapDuration / $timeStep; } } elseif ( $bucket === $lastBucket ) { // It can be assumed that there are zero events in the future $bucketStartTime = $bucket * $timeStep; $rateInterpolationEndTime = min( $bucketStartTime + $timeStep, $now ); $overlapDuration = max( $range->end - $bucketStartTime, 0 ); $interpolationDuration = $rateInterpolationEndTime - $bucketStartTime; if ( $overlapDuration === $interpolationDuration ) { // Special case for 0/0 -- current time exactly on boundary. $total += $value; } elseif ( $interpolationDuration > 0 ) { $total += $value * $overlapDuration / $interpolationDuration; } } else { $total += $value; } } // Round to nearest resolution step for nicer display $rounded = round( $total ) * $metricSpec->resolution; // Convert to integer if integer is expected if ( is_int( $metricSpec->resolution ) ) { $rounded = (int)$rounded; } return $rounded; } /** * Resolve a batch of RatePromise objects, returning their counter totals, * indexed as in the input array. * * @param array<mixed,RatePromise> $rates * @return array<mixed,float|int> */ public function total( $rates ) { $result = []; foreach ( $rates as $key => $rate ) { $result[$key] = $rate->total(); } return $result; } /** * Resolve a batch of RatePromise objects, returning their per-second rates. * * @param array<mixed,RatePromise> $rates * @return array<mixed,float> */ public function perSecond( $rates ) { $result = []; foreach ( $rates as $key => $rate ) { $result[$key] = $rate->perSecond(); } return $result; } /** * Resolve a batch of RatePromise objects, returning their per-minute rates. * * @param array<mixed,RatePromise> $rates * @return array<mixed,float> */ public function perMinute( $rates ) { $result = []; foreach ( $rates as $key => $rate ) { $result[$key] = $rate->perMinute(); } return $result; } /** * Resolve a batch of RatePromise objects, returning their per-hour rates. * * @param array<mixed,RatePromise> $rates * @return array<mixed,float> */ public function perHour( $rates ) { $result = []; foreach ( $rates as $key => $rate ) { $result[$key] = $rate->perHour(); } return $result; } /** * Resolve a batch of RatePromise objects, returning their per-day rates. * * @param array<mixed,RatePromise> $rates * @return array<mixed,float> */ public function perDay( $rates ) { $result = []; foreach ( $rates as $key => $rate ) { $result[$key] = $rate->perDay(); } return $result; } } PK ! (��N� � WRStats/GlobalEntityKey.phpnu �Iw�� <?php namespace Wikimedia\WRStats; /** * Entity key with isGlobal=true * * @newable * @since 1.39 */ class GlobalEntityKey extends EntityKey { public function isGlobal() { return true; } } PK ! ْ�� WRStats/TimeRange.phpnu �Iw�� <?php namespace Wikimedia\WRStats; /** * A time range * * @since 1.39 */ class TimeRange { /** @var float|int UNIX start time */ public $start; /** @var float|int UNIX end time */ public $end; /** * @internal * * @param float|int $start * @param float|int $end */ public function __construct( $start, $end ) { $this->start = $start; $this->end = $end; } /** * Get the duration of the time range in seconds. * * @return float|int */ public function getDuration() { return $this->end - $this->start; } } PK ! ��ɐ � WRStats/BagOStuffStatsStore.phpnu �Iw�� <?php namespace Wikimedia\WRStats; use Wikimedia\ObjectCache\BagOStuff; /** * An adaptor allowing WRStats to store data in MediaWiki's BagOStuff * * @newable * @since 1.39 */ class BagOStuffStatsStore implements StatsStore { /** @var BagOStuff */ private $cache; /** * @param BagOStuff $cache */ public function __construct( BagOStuff $cache ) { $this->cache = $cache; } /** * @inheritDoc * @suppress PhanParamTooFewUnpack */ public function makeKey( $prefix, $internals, $entity ) { if ( $entity->isGlobal() ) { return $this->cache->makeGlobalKey( ...$prefix, ...$internals, ...$entity->getComponents() ); } else { return $this->cache->makeKey( ...$prefix, ...$internals, ...$entity->getComponents() ); } } public function incr( array $values, $ttl ) { foreach ( $values as $key => $value ) { $this->cache->incrWithInit( $key, $ttl, $value, $value, BagOStuff::WRITE_BACKGROUND ); } } public function delete( array $keys ) { $this->cache->deleteMulti( $keys, BagOStuff::WRITE_BACKGROUND ); } public function query( array $keys ) { return $this->cache->getMulti( $keys ); } } PK ! K�c WRStats/SequenceSpec.phpnu �Iw�� <?php namespace Wikimedia\WRStats; /** * Class representation of normalized sequence specifications. * * @internal */ class SequenceSpec { /** The default time bucket size (seconds) */ public const DEFAULT_TIME_STEP = 600; /** The default expiry time (seconds) */ public const DEFAULT_EXPIRY = 3600; /** @var string */ public $name; /** @var float|int */ public $timeStep; /** @var float|int */ public $softExpiry; /** @var int */ public $hardExpiry; /** * @param array $spec */ public function __construct( array $spec ) { $this->timeStep = $spec['timeStep'] ?? self::DEFAULT_TIME_STEP; $this->softExpiry = $spec['expiry'] ?? self::DEFAULT_EXPIRY; $this->hardExpiry = (int)ceil( $this->softExpiry + $this->timeStep ); $this->name = $spec['name'] ?? ''; } } PK ! K� '� � WRStats/LimitOperation.phpnu �Iw�� <?php namespace Wikimedia\WRStats; /** * One item in a LimitBatch. * * To perform a single operation, it is generally recommended to use * the simpler interface of WRStatsRateLimiter::peek(), ::incr(), and * ::tryIncr() instead of constructing LimitOperation objects. * * @newable * @since 1.39 */ class LimitOperation { /** @var string */ public $condName; /** @var EntityKey */ public $entityKey; /** @var int */ public $amount; /** * @param string $condName * @param EntityKey|null $entityKey * @param int $amount */ public function __construct( string $condName, ?EntityKey $entityKey = null, $amount = 1 ) { $this->condName = $condName; $this->entityKey = $entityKey ?? new LocalEntityKey; $this->amount = $amount; } } PK ! ��� WRStats/StatsStore.phpnu �Iw�� <?php namespace Wikimedia\WRStats; /** * Narrow interface for WRStatsFactory to a memcached-like key-value store. * * @since 1.39 */ interface StatsStore { /** * Construct a string key from its components * * @param string[] $prefix The prefix components. * @param array<string|int> $internals The internal components. * @param EntityKey $entity The entity components. If $entity->isGlobal() * is true, the key as a whole should be treated as global. * @return string */ public function makeKey( $prefix, $internals, $entity ); /** * Perform a batch of increment operations. * * @param int[] $values The deltas to add, indexed by the key as returned by makeKey() * @param int $ttl The expiry time of any new entries, in seconds. This is * a hint, allowing the storage layer to control space usage. Implementing * expiry is not a requirement. */ public function incr( array $values, $ttl ); /** * Perform a batch of delete operations. * * @param string[] $keys Keys to delete; strings returned by makeKey() */ public function delete( array $keys ); /** * Perform a batch of fetch operations. * * @param string[] $keys Keys to get; strings returned by makeKey() * @return int[] Integers */ public function query( array $keys ); } PK ! �f`xZ Z WRStats/ArrayStatsStore.phpnu �Iw�� <?php namespace Wikimedia\WRStats; /** * In-memory stats store. */ class ArrayStatsStore implements StatsStore { /** * @var array[] Associative array mapping data keys to arrays where the * first entry is the value and the second is the TTL. */ private $data = []; public function makeKey( $prefix, $internals, $entity ) { $globality = $entity->isGlobal() ? 'global' : 'local'; return implode( ':', array_merge( [ $globality ], $prefix, $internals, $entity->getComponents() ) ); } public function incr( array $values, $ttl ) { foreach ( $values as $key => $value ) { if ( !isset( $this->data[$key] ) ) { $this->data[$key] = [ 0, $ttl ]; } $this->data[$key][0] += $value; } } public function delete( array $keys ) { foreach ( $keys as $key ) { unset( $this->data[$key] ); } } public function query( array $keys ) { $values = []; foreach ( $keys as $key ) { if ( isset( $this->data[$key] ) ) { $values[$key] = $this->data[$key][0]; } } return $values; } /** * @return array */ public function getData() { return $this->data; } } PK ! 6� � WRStats/WRStatsError.phpnu �Iw�� <?php namespace Wikimedia\WRStats; /** * Exception class for errors thrown by the WRStats library * * @since 1.39 */ class WRStatsError extends \Exception { } PK ! 9M��> > WRStats/LimitOperationResult.phpnu �Iw�� <?php namespace Wikimedia\WRStats; /** * Information about the result of a single item in a limit batch * * @since 1.39 */ class LimitOperationResult { /** @var LimitCondition */ public $condition; /** @var int The previous metric value before the current action was executed */ public $prevTotal; /** @var int The value the metric would have if the increment operation were allowed */ public $newTotal; /** * @internal * * @param LimitCondition $condition * @param int $prevTotal * @param int $newTotal */ public function __construct( LimitCondition $condition, $prevTotal, $newTotal ) { $this->condition = $condition; $this->prevTotal = $prevTotal; $this->newTotal = $newTotal; } /** * Whether the operation was/is allowed. * * @return bool */ public function isAllowed() { return $this->newTotal <= $this->condition->limit; } /** * Get a string representing the object, for testing or debugging * * @return string */ public function dump() { return "LimitActionResult{{$this->newTotal}/{$this->condition->limit}}"; } } PK ! M��� � WRStats/LimitBatchResult.phpnu �Iw�� <?php namespace Wikimedia\WRStats; /** * A class representing the results from a batch operation. * * @since 1.39 */ class LimitBatchResult { /** @var LimitOperationResult[] */ private $results; /** @var bool|null */ private $allowed; /** * @internal Use WRStatsFactory::createRateLimiter() instead * @param LimitOperationResult[] $results */ public function __construct( $results ) { $this->results = $results; } /** * Determine whether the batch as a whole is/was allowed * * @return bool */ public function isAllowed() { if ( $this->allowed === null ) { $this->allowed = true; foreach ( $this->results as $result ) { if ( !$result->isAllowed() ) { $this->allowed = false; break; } } } return $this->allowed; } /** * Get LimitOperationResult objects for operations exceeding the limit. * * The keys will match the input array. For input arrays constructed by * LimitBatch, the keys will be the condition names. * * @return LimitOperationResult[] */ public function getFailedResults() { $failed = []; foreach ( $this->results as $i => $result ) { if ( !$result->isAllowed() ) { $failed[$i] = $result; } } return $failed; } /** * Get LimitOperationResult objects for operations not exceeding the limit. * * The keys will match the input array. For input arrays constructed by * LimitBatch, the keys will be the condition names. * * @return LimitOperationResult[] */ public function getPassedResults() { $passed = []; foreach ( $this->results as $i => $result ) { if ( $result->isAllowed() ) { $passed[$i] = $result; } } return $passed; } /** * Get LimitOperationResult objects for all operations in the batch. * * The keys will match the input array. For input arrays constructed by * LimitBatch, the keys will be the condition names. * * @return LimitOperationResult[] */ public function getAllResults() { return $this->results; } } PK ! ڸ��; ; Emptiable.phpnu �Iw�� <?php namespace MediaWiki\Libs; /** * An interface to check for emptiness of an object */ interface Emptiable { /** * Check if object is empty * @return bool Is it empty */ public function isEmpty(); } /** @deprecated class alias since 1.41 */ class_alias( Emptiable::class, 'MediaWiki\\Emptiable' ); PK ! ��t7 7 http/HttpAcceptParser.phpnu �Iw�� <?php /** * Utility for parsing a HTTP Accept header value into a weight map. May also be used with * other, similar headers like Accept-Language, Accept-Encoding, etc. * * @license GPL-2.0-or-later * @author Daniel Kinzler */ namespace Wikimedia\Http; class HttpAcceptParser { /** * Parse media types from an Accept header and sort them by q-factor. * * Note that his was mostly ported from, * https://github.com/arlolra/negotiator/blob/full-parse-access/lib/mediaType.js * * @param string $accept * @return array[] * - type: (string) * - subtype: (string) * - q: (float) q-factor weighting * - i: (int) index * - params: (array) */ public function parseAccept( $accept ): array { $accepts = explode( ',', $accept ); // FIXME: Allow commas in quotes $ret = []; foreach ( $accepts as $i => $a ) { if ( !preg_match( '!^([^\s/;]+)/([^;\s]+)\s*(?:;(.*))?$!D', trim( $a ), $matches ) ) { continue; } $q = 1; $params = []; if ( isset( $matches[3] ) ) { $kvps = explode( ';', $matches[3] ); // FIXME: Allow semi-colon in quotes foreach ( $kvps as $kv ) { [ $key, $val ] = explode( '=', trim( $kv ), 2 ); $key = strtolower( trim( $key ) ); $val = trim( $val ); if ( $key === 'q' ) { $q = (float)$val; // FIXME: Spec is stricter about this } else { if ( $val && $val[0] === '"' && $val[ strlen( $val ) - 1 ] === '"' ) { $val = substr( $val, 1, strlen( $val ) - 2 ); } $params[$key] = $val; } } } $ret[] = [ 'type' => $matches[1], 'subtype' => $matches[2], 'q' => $q, 'i' => $i, 'params' => $params, ]; } // Sort list. First by q values, then by order usort( $ret, static function ( $a, $b ) { if ( $b['q'] > $a['q'] ) { return 1; } elseif ( $b['q'] === $a['q'] ) { return $a['i'] - $b['i']; } else { return -1; } } ); return $ret; } /** * Parses an HTTP header into a weight map, that is an associative array * mapping values to their respective weights. Any header name preceding * weight spec is ignored for convenience. * * Note that type parameters and accept extension like the "level" parameter * are not supported, weights are derived from "q" values only. * * See RFC 7231 section 5.3.2 for details. * * @param string $rawHeader * * @return array */ public function parseWeights( $rawHeader ) { // first, strip header name $rawHeader = preg_replace( '/^[-\w]+:\s*/', '', $rawHeader ); // Return values in lower case $rawHeader = strtolower( $rawHeader ); $accepts = $this->parseAccept( $rawHeader ); // Create a list like "en" => 0.8 return array_reduce( $accepts, static function ( $prev, $next ) { $type = "{$next['type']}/{$next['subtype']}"; $prev[$type] = $next['q']; return $prev; }, [] ); } } PK ! �.��$ $ " http/TelemetryHeadersInterface.phpnu �Iw�� <?php namespace Wikimedia\Http; /** * Provide Request Telemetry information * @unstable * @since 1.41 */ interface TelemetryHeadersInterface { /** * Get Headers to outgoing requests * @return array<string, string> Headers array */ public function getRequestHeaders(): array; } PK ! �>�w �w http/MultiHttpClient.phpnu �Iw�� <?php /** * HTTP service client * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\Http; use InvalidArgumentException; use MediaWiki\MediaWikiServices; use Psr\Log\LoggerAwareInterface; use Psr\Log\LoggerInterface; use Psr\Log\NullLogger; /** * Class to handle multiple HTTP requests * * If curl is available, requests will be made concurrently. * Otherwise, they will be made serially. * * HTTP request maps are arrays that use the following format: * - method : GET/HEAD/PUT/POST/DELETE * - url : HTTP/HTTPS URL * - query : <query parameter field/value associative array> (uses RFC 3986) * - headers : <header name/value associative array> * - body : source to get the HTTP request body from; * this can simply be a string (always), a resource for * PUT requests, and a field/value array for POST request; * array bodies are encoded as multipart/form-data and strings * use application/x-www-form-urlencoded (headers sent automatically) * - stream : resource to stream the HTTP response body to * - proxy : HTTP proxy to use * - flags : map of boolean flags which supports: * - relayResponseHeaders : write out header via header() * Request maps can use integer index 0 instead of 'method' and 1 instead of 'url'. * * Since 1.35, callers should use HttpRequestFactory::createMultiClient() to get * a client object with appropriately configured timeouts. * * @since 1.23 */ class MultiHttpClient implements LoggerAwareInterface { /** Regex for headers likely to contain tokens, etc. that we want to redact from logs */ private const SENSITIVE_HEADERS = '/(^|-|_)(authorization|auth|password|cookie)($|-|_)/'; /** * @phpcs:ignore MediaWiki.Commenting.PropertyDocumentation.ObjectTypeHintVar * @var resource|object|null curl_multi_init() handle, initialized in getCurlMulti() */ protected $cmh = null; /** @var string|null SSL certificates path */ protected $caBundlePath; /** @var float */ protected $connTimeout = 10; /** @var float */ protected $maxConnTimeout = INF; /** @var float */ protected $reqTimeout = 30; /** @var float */ protected $maxReqTimeout = INF; /** @var bool */ protected $usePipelining = false; /** @var int */ protected $maxConnsPerHost = 50; /** @var string|null proxy */ protected $proxy; /** @var string|false */ protected $localProxy = false; /** @var string[] */ protected $localVirtualHosts = []; /** @var string */ protected $userAgent = 'wikimedia/multi-http-client v1.1'; /** @var LoggerInterface */ protected $logger; /** @var array */ protected array $headers = []; // In PHP 7 due to https://bugs.php.net/bug.php?id=76480 the request/connect // timeouts are periodically polled instead of being accurately respected. // The select timeout is set to the minimum timeout multiplied by this factor. private const TIMEOUT_ACCURACY_FACTOR = 0.1; private ?TelemetryHeadersInterface $telemetry = null; /** * Since 1.35, callers should use HttpRequestFactory::createMultiClient() to get * a client object with appropriately configured timeouts instead of constructing * a MultiHttpClient directly. * * @param array $options * - connTimeout : default connection timeout (seconds) * - reqTimeout : default request timeout (seconds) * - maxConnTimeout : maximum connection timeout (seconds) * - maxReqTimeout : maximum request timeout (seconds) * - proxy : HTTP proxy to use * - localProxy : Reverse proxy to use for domains in localVirtualHosts * - localVirtualHosts : Domains that are configured as virtual hosts on the same machine * - usePipelining : whether to use HTTP pipelining if possible (for all hosts) * - maxConnsPerHost : maximum number of concurrent connections (per host) * - userAgent : The User-Agent header value to send * - logger : a \Psr\Log\LoggerInterface instance for debug logging * - caBundlePath : path to specific Certificate Authority bundle (if any) * - headers : an array of default headers to send with every request * - telemetry : a \Wikimedia\Http\RequestTelemetry instance to track telemetry data * @throws \Exception */ public function __construct( array $options ) { if ( isset( $options['caBundlePath'] ) ) { $this->caBundlePath = $options['caBundlePath']; if ( !file_exists( $this->caBundlePath ) ) { throw new InvalidArgumentException( "Cannot find CA bundle: " . $this->caBundlePath ); } } static $opts = [ 'connTimeout', 'maxConnTimeout', 'reqTimeout', 'maxReqTimeout', 'usePipelining', 'maxConnsPerHost', 'proxy', 'userAgent', 'logger', 'localProxy', 'localVirtualHosts', 'headers', 'telemetry' ]; foreach ( $opts as $key ) { if ( isset( $options[$key] ) ) { $this->$key = $options[$key]; } } $this->logger ??= new NullLogger; } /** * Execute an HTTP(S) request * * This method returns a response map of: * - code : HTTP response code or 0 if there was a serious error * - reason : HTTP response reason (empty if there was a serious error) * - headers : <header name/value associative array> * - body : HTTP response body or resource (if "stream" was set) * - error : Any error string * The map also stores integer-indexed copies of these values. This lets callers do: * @code * [ $rcode, $rdesc, $rhdrs, $rbody, $rerr ] = $http->run( $req ); * @endcode * @param array $req HTTP request array * @param array $opts * - connTimeout : connection timeout per request (seconds) * - reqTimeout : post-connection timeout per request (seconds) * - usePipelining : whether to use HTTP pipelining if possible (for all hosts) * - maxConnsPerHost : maximum number of concurrent connections (per host) * - httpVersion : One of 'v1.0', 'v1.1', 'v2' or 'v2.0'. Leave empty to use * PHP/curl's default * @return array Response array for request */ public function run( array $req, array $opts = [] ) { return $this->runMulti( [ $req ], $opts )[0]['response']; } /** * Execute a set of HTTP(S) requests. * * If curl is available, requests will be made concurrently. * Otherwise, they will be made serially. * * The maps are returned by this method with the 'response' field set to a map of: * - code : HTTP response code or 0 if there was a serious error * - reason : HTTP response reason (empty if there was a serious error) * - headers : <header name/value associative array> * - body : HTTP response body or resource (if "stream" was set) * - error : Any error string * The map also stores integer-indexed copies of these values. This lets callers do: * @code * [ $rcode, $rdesc, $rhdrs, $rbody, $rerr ] = $req['response']; * @endcode * All headers in the 'headers' field are normalized to use lower case names. * This is true for the request headers and the response headers. Integer-indexed * method/URL entries will also be changed to use the corresponding string keys. * * @param array[] $reqs Map of HTTP request arrays * @param array $opts Options * - connTimeout : connection timeout per request (seconds) * - reqTimeout : post-connection timeout per request (seconds) * - usePipelining : whether to use HTTP pipelining if possible (for all hosts) * - maxConnsPerHost : maximum number of concurrent connections (per host) * - httpVersion : One of 'v1.0', 'v1.1', 'v2' or 'v2.0'. Leave empty to use * PHP/curl's default * @return array[] $reqs With response array populated for each * @throws \Exception */ public function runMulti( array $reqs, array $opts = [] ) { $this->normalizeRequests( $reqs ); $opts += [ 'connTimeout' => $this->connTimeout, 'reqTimeout' => $this->reqTimeout ]; if ( $this->maxConnTimeout && $opts['connTimeout'] > $this->maxConnTimeout ) { $opts['connTimeout'] = $this->maxConnTimeout; } if ( $this->maxReqTimeout && $opts['reqTimeout'] > $this->maxReqTimeout ) { $opts['reqTimeout'] = $this->maxReqTimeout; } if ( $this->isCurlEnabled() ) { switch ( $opts['httpVersion'] ?? null ) { case 'v1.0': $opts['httpVersion'] = CURL_HTTP_VERSION_1_0; break; case 'v1.1': $opts['httpVersion'] = CURL_HTTP_VERSION_1_1; break; case 'v2': case 'v2.0': $opts['httpVersion'] = CURL_HTTP_VERSION_2_0; break; default: $opts['httpVersion'] = CURL_HTTP_VERSION_NONE; } return $this->runMultiCurl( $reqs, $opts ); } else { # TODO: Add handling for httpVersion option return $this->runMultiHttp( $reqs, $opts ); } } /** * Determines if the curl extension is available * * @return bool true if curl is available, false otherwise. */ protected function isCurlEnabled() { // Explicitly test if curl_multi* is blocked, as some users' hosts provide // them with a modified curl with the multi-threaded parts removed(!) return extension_loaded( 'curl' ) && function_exists( 'curl_multi_init' ); } /** * Execute a set of HTTP(S) requests concurrently * * @see MultiHttpClient::runMulti() * * @param array[] $reqs Map of HTTP request arrays * @param array $opts * - connTimeout : connection timeout per request (seconds) * - reqTimeout : post-connection timeout per request (seconds) * - usePipelining : whether to use HTTP pipelining if possible * - maxConnsPerHost : maximum number of concurrent connections (per host) * - httpVersion: : HTTP version to use * @phan-param array{connTimeout?:int,reqTimeout?:int,usePipelining?:bool,maxConnsPerHost?:int} $opts * @return array $reqs With response array populated for each * @throws \Exception * @suppress PhanTypeInvalidDimOffset */ private function runMultiCurl( array $reqs, array $opts ) { $chm = $this->getCurlMulti( $opts ); $selectTimeout = $this->getSelectTimeout( $opts ); // Add all of the required cURL handles... $handles = []; foreach ( $reqs as $index => &$req ) { $handles[$index] = $this->getCurlHandle( $req, $opts ); curl_multi_add_handle( $chm, $handles[$index] ); } unset( $req ); // don't assign over this by accident $infos = []; // Execute the cURL handles concurrently... $active = null; // handles still being processed do { // Do any available work... do { $mrc = curl_multi_exec( $chm, $active ); $info = curl_multi_info_read( $chm ); if ( $info !== false ) { // Note: cast to integer even works on PHP 8.0+ despite the // handle being an object not a resource, because CurlHandle // has a backwards-compatible cast_object handler. $infos[(int)$info['handle']] = $info; } } while ( $mrc == CURLM_CALL_MULTI_PERFORM ); // Wait (if possible) for available work... if ( $active > 0 && $mrc == CURLM_OK && curl_multi_select( $chm, $selectTimeout ) == -1 ) { // PHP bug 63411; https://curl.haxx.se/libcurl/c/curl_multi_fdset.html usleep( 5000 ); // 5ms } } while ( $active > 0 && $mrc == CURLM_OK ); // Remove all of the added cURL handles and check for errors... foreach ( $reqs as $index => &$req ) { $ch = $handles[$index]; curl_multi_remove_handle( $chm, $ch ); if ( isset( $infos[(int)$ch] ) ) { $info = $infos[(int)$ch]; $errno = $info['result']; if ( $errno !== 0 ) { $req['response']['error'] = "(curl error: $errno)"; if ( function_exists( 'curl_strerror' ) ) { $req['response']['error'] .= " " . curl_strerror( $errno ); } $this->logger->warning( "Error fetching URL \"{$req['url']}\": " . $req['response']['error'] ); } else { $this->logger->debug( "HTTP complete: {method} {url} code={response_code} size={size} " . "total={total_time} connect={connect_time}", [ 'method' => $req['method'], 'url' => $req['url'], 'response_code' => $req['response']['code'], 'size' => curl_getinfo( $ch, CURLINFO_SIZE_DOWNLOAD ), 'total_time' => $this->getCurlTime( $ch, CURLINFO_TOTAL_TIME, 'CURLINFO_TOTAL_TIME_T' ), 'connect_time' => $this->getCurlTime( $ch, CURLINFO_CONNECT_TIME, 'CURLINFO_CONNECT_TIME_T' ), ] ); } } else { $req['response']['error'] = "(curl error: no status set)"; } // For convenience with array destructuring $req['response'][0] = $req['response']['code']; $req['response'][1] = $req['response']['reason']; $req['response'][2] = $req['response']['headers']; $req['response'][3] = $req['response']['body']; $req['response'][4] = $req['response']['error']; curl_close( $ch ); // Close any string wrapper file handles if ( isset( $req['_closeHandle'] ) ) { fclose( $req['_closeHandle'] ); unset( $req['_closeHandle'] ); } } unset( $req ); // don't assign over this by accident return $reqs; } /** * @param array &$req HTTP request map * @phpcs:ignore Generic.Files.LineLength * @phan-param array{url:string,proxy?:?string,query:mixed,method:string,body:string|resource,headers:array<string,string>,stream?:resource,flags:array} $req * @param array $opts * - connTimeout : default connection timeout * - reqTimeout : default request timeout * - httpVersion: default HTTP version * @phpcs:ignore MediaWiki.Commenting.FunctionComment.ObjectTypeHintReturn * @return resource|object * @throws \Exception */ protected function getCurlHandle( array &$req, array $opts ) { $ch = curl_init(); curl_setopt( $ch, CURLOPT_PROXY, $req['proxy'] ?? $this->proxy ); curl_setopt( $ch, CURLOPT_CONNECTTIMEOUT_MS, intval( $opts['connTimeout'] * 1e3 ) ); curl_setopt( $ch, CURLOPT_TIMEOUT_MS, intval( $opts['reqTimeout'] * 1e3 ) ); curl_setopt( $ch, CURLOPT_FOLLOWLOCATION, 1 ); curl_setopt( $ch, CURLOPT_MAXREDIRS, 4 ); curl_setopt( $ch, CURLOPT_HEADER, 0 ); if ( $this->caBundlePath !== null ) { curl_setopt( $ch, CURLOPT_SSL_VERIFYPEER, true ); curl_setopt( $ch, CURLOPT_CAINFO, $this->caBundlePath ); } curl_setopt( $ch, CURLOPT_RETURNTRANSFER, 1 ); $url = $req['url']; $query = http_build_query( $req['query'], '', '&', PHP_QUERY_RFC3986 ); if ( $query != '' ) { $url .= strpos( $req['url'], '?' ) === false ? "?$query" : "&$query"; } curl_setopt( $ch, CURLOPT_URL, $url ); curl_setopt( $ch, CURLOPT_CUSTOMREQUEST, $req['method'] ); curl_setopt( $ch, CURLOPT_NOBODY, ( $req['method'] === 'HEAD' ) ); curl_setopt( $ch, CURLOPT_HTTP_VERSION, $opts['httpVersion'] ?? CURL_HTTP_VERSION_NONE ); if ( $req['method'] === 'PUT' ) { curl_setopt( $ch, CURLOPT_PUT, 1 ); // phpcs:ignore MediaWiki.Usage.ForbiddenFunctions.is_resource if ( is_resource( $req['body'] ) ) { curl_setopt( $ch, CURLOPT_INFILE, $req['body'] ); if ( isset( $req['headers']['content-length'] ) ) { curl_setopt( $ch, CURLOPT_INFILESIZE, $req['headers']['content-length'] ); } elseif ( isset( $req['headers']['transfer-encoding'] ) && $req['headers']['transfer-encoding'] === 'chunks' ) { curl_setopt( $ch, CURLOPT_UPLOAD, true ); } else { throw new InvalidArgumentException( "Missing 'Content-Length' or 'Transfer-Encoding' header." ); } } elseif ( $req['body'] !== '' ) { $fp = fopen( "php://temp", "wb+" ); fwrite( $fp, $req['body'], strlen( $req['body'] ) ); rewind( $fp ); curl_setopt( $ch, CURLOPT_INFILE, $fp ); curl_setopt( $ch, CURLOPT_INFILESIZE, strlen( $req['body'] ) ); $req['_closeHandle'] = $fp; // remember to close this later } else { curl_setopt( $ch, CURLOPT_INFILESIZE, 0 ); } curl_setopt( $ch, CURLOPT_READFUNCTION, static function ( $ch, $fd, $length ) { return (string)fread( $fd, $length ); } ); } elseif ( $req['method'] === 'POST' ) { curl_setopt( $ch, CURLOPT_POST, 1 ); curl_setopt( $ch, CURLOPT_POSTFIELDS, $req['body'] ); } else { // phpcs:ignore MediaWiki.Usage.ForbiddenFunctions.is_resource if ( is_resource( $req['body'] ) || $req['body'] !== '' ) { throw new InvalidArgumentException( "HTTP body specified for a non PUT/POST request." ); } $req['headers']['content-length'] = 0; } if ( !isset( $req['headers']['user-agent'] ) ) { $req['headers']['user-agent'] = $this->userAgent; } $headers = []; foreach ( $req['headers'] as $name => $value ) { if ( strpos( $name, ':' ) !== false ) { throw new InvalidArgumentException( "Header name must not contain colon-space." ); } $headers[] = $name . ': ' . trim( $value ); } curl_setopt( $ch, CURLOPT_HTTPHEADER, $headers ); curl_setopt( $ch, CURLOPT_HEADERFUNCTION, static function ( $ch, $header ) use ( &$req ) { if ( !empty( $req['flags']['relayResponseHeaders'] ) && trim( $header ) !== '' ) { header( $header ); } $length = strlen( $header ); $matches = []; if ( preg_match( "/^(HTTP\/(?:1\.[01]|2)) (\d{3}) (.*)/", $header, $matches ) ) { $req['response']['code'] = (int)$matches[2]; $req['response']['reason'] = trim( $matches[3] ); // After a redirect we will receive this again, but we already stored headers // that belonged to a redirect response. Start over. $req['response']['headers'] = []; return $length; } if ( strpos( $header, ":" ) === false ) { return $length; } [ $name, $value ] = explode( ":", $header, 2 ); $name = strtolower( $name ); $value = trim( $value ); if ( isset( $req['response']['headers'][$name] ) ) { $req['response']['headers'][$name] .= ', ' . $value; } else { $req['response']['headers'][$name] = $value; } return $length; } ); // This works with both file and php://temp handles (unlike CURLOPT_FILE) $hasOutputStream = isset( $req['stream'] ); curl_setopt( $ch, CURLOPT_WRITEFUNCTION, static function ( $ch, $data ) use ( &$req, $hasOutputStream ) { if ( $hasOutputStream ) { // @phan-suppress-next-line PhanTypePossiblyInvalidDimOffset False positive return fwrite( $req['stream'], $data ); } else { // @phan-suppress-next-line PhanTypeArraySuspiciousNullable $req['response']['body'] .= $data; return strlen( $data ); } } ); return $ch; } /** * @param array $opts * @phpcs:ignore MediaWiki.Commenting.FunctionComment.ObjectTypeHintReturn * @return resource|object * @throws \Exception */ protected function getCurlMulti( array $opts ) { if ( !$this->cmh ) { $cmh = curl_multi_init(); // Limit the size of the idle connection cache such that consecutive parallel // request batches to the same host can avoid having to keep making connections curl_multi_setopt( $cmh, CURLMOPT_MAXCONNECTS, (int)$this->maxConnsPerHost ); $this->cmh = $cmh; } $curlVersion = curl_version()['version']; // CURLMOPT_MAX_HOST_CONNECTIONS is available since PHP 7.0.7 and cURL 7.30.0 if ( version_compare( $curlVersion, '7.30.0', '>=' ) ) { // Limit the number of in-flight requests for any given host $maxHostConns = $opts['maxConnsPerHost'] ?? $this->maxConnsPerHost; curl_multi_setopt( $this->cmh, CURLMOPT_MAX_HOST_CONNECTIONS, (int)$maxHostConns ); } if ( $opts['usePipelining'] ?? $this->usePipelining ) { if ( version_compare( $curlVersion, '7.43', '<' ) ) { // The option is a boolean $pipelining = 1; } elseif ( version_compare( $curlVersion, '7.62', '<' ) ) { // The option is a bitfield and HTTP/1.x pipelining is supported $pipelining = CURLPIPE_HTTP1 | CURLPIPE_MULTIPLEX; } else { // The option is a bitfield but HTTP/1.x pipelining has been removed $pipelining = CURLPIPE_MULTIPLEX; } // Suppress deprecation, we know already (T264735) // phpcs:ignore Generic.PHP.NoSilencedErrors @curl_multi_setopt( $this->cmh, CURLMOPT_PIPELINING, $pipelining ); } return $this->cmh; } /** * Get a time in seconds, formatted with microsecond resolution, or fall back to second * resolution on PHP 7.2 * * @phpcs:ignore MediaWiki.Commenting.FunctionComment.ObjectTypeHintParam * @param resource|object $ch * @param int $oldOption * @param string $newConstName * @return string */ private function getCurlTime( $ch, $oldOption, $newConstName ): string { if ( defined( $newConstName ) ) { return sprintf( "%.6F", curl_getinfo( $ch, constant( $newConstName ) ) / 1e6 ); } else { return (string)curl_getinfo( $ch, $oldOption ); } } /** * Execute a set of HTTP(S) requests sequentially. * * @see MultiHttpClient::runMulti() * @todo Remove dependency on MediaWikiServices: rewrite using Guzzle T202352 * @param array $reqs Map of HTTP request arrays * @phpcs:ignore Generic.Files.LineLength * @phan-param array<int,array{url:string,query:array,method:string,body:string,headers:array<string,string>,proxy?:?string}> $reqs * @param array $opts * - connTimeout : connection timeout per request (seconds) * - reqTimeout : post-connection timeout per request (seconds) * @phan-param array{connTimeout:int,reqTimeout:int} $opts * @return array $reqs With response array populated for each * @throws \Exception */ private function runMultiHttp( array $reqs, array $opts = [] ) { $httpOptions = [ 'timeout' => $opts['reqTimeout'] ?? $this->reqTimeout, 'connectTimeout' => $opts['connTimeout'] ?? $this->connTimeout, 'logger' => $this->logger, 'caInfo' => $this->caBundlePath, ]; foreach ( $reqs as &$req ) { $reqOptions = $httpOptions + [ 'method' => $req['method'], 'proxy' => $req['proxy'] ?? $this->proxy, 'userAgent' => $req['headers']['user-agent'] ?? $this->userAgent, 'postData' => $req['body'], ]; $url = $req['url']; $query = http_build_query( $req['query'], '', '&', PHP_QUERY_RFC3986 ); if ( $query != '' ) { $url .= strpos( $req['url'], '?' ) === false ? "?$query" : "&$query"; } $httpRequest = MediaWikiServices::getInstance()->getHttpRequestFactory()->create( $url, $reqOptions, __METHOD__ ); $httpRequest->setLogger( $this->logger ); foreach ( $req['headers'] as $header => $value ) { $httpRequest->setHeader( $header, $value ); } $sv = $httpRequest->execute()->getStatusValue(); $respHeaders = array_map( static function ( $v ) { return implode( ', ', $v ); }, $httpRequest->getResponseHeaders() ); $req['response'] = [ 'code' => $httpRequest->getStatus(), 'reason' => '', 'headers' => $respHeaders, 'body' => $httpRequest->getContent(), 'error' => '', ]; if ( !$sv->isOK() ) { $svErrors = $sv->getErrors(); if ( isset( $svErrors[0] ) ) { $req['response']['error'] = $svErrors[0]['message']; // param values vary per failure type (ex. unknown host vs unknown page) if ( isset( $svErrors[0]['params'][0] ) ) { if ( is_numeric( $svErrors[0]['params'][0] ) ) { if ( isset( $svErrors[0]['params'][1] ) ) { // @phan-suppress-next-line PhanTypeInvalidDimOffset $req['response']['reason'] = $svErrors[0]['params'][1]; } } else { $req['response']['reason'] = $svErrors[0]['params'][0]; } } } } $req['response'][0] = $req['response']['code']; $req['response'][1] = $req['response']['reason']; $req['response'][2] = $req['response']['headers']; $req['response'][3] = $req['response']['body']; $req['response'][4] = $req['response']['error']; } return $reqs; } /** * Normalize headers array * @param array $headers * @return array */ private function normalizeHeaders( array $headers ): array { $normalized = []; foreach ( $headers as $name => $value ) { $normalized[strtolower( $name )] = $value; } return $normalized; } /** * Normalize request information * * @param array[] &$reqs the requests to normalize */ private function normalizeRequests( array &$reqs ) { foreach ( $reqs as &$req ) { $req['response'] = [ 'code' => 0, 'reason' => '', 'headers' => [], 'body' => '', 'error' => '' ]; if ( isset( $req[0] ) ) { $req['method'] = $req[0]; // short-form unset( $req[0] ); } if ( isset( $req[1] ) ) { $req['url'] = $req[1]; // short-form unset( $req[1] ); } if ( !isset( $req['method'] ) ) { throw new InvalidArgumentException( "Request has no 'method' field set." ); } elseif ( !isset( $req['url'] ) ) { throw new InvalidArgumentException( "Request has no 'url' field set." ); } if ( $this->localProxy !== false && $this->isLocalURL( $req['url'] ) ) { $this->useReverseProxy( $req, $this->localProxy ); } $req['query'] ??= []; $req['headers'] = $this->normalizeHeaders( array_merge( $this->headers, $this->telemetry ? $this->telemetry->getRequestHeaders() : [], $req['headers'] ?? [] ) ); if ( !isset( $req['body'] ) ) { $req['body'] = ''; $req['headers']['content-length'] = 0; } // Redact some headers we know to have tokens before logging them $logHeaders = $req['headers']; foreach ( $logHeaders as $header => $value ) { if ( preg_match( self::SENSITIVE_HEADERS, $header ) === 1 ) { $logHeaders[$header] = '[redacted]'; } } $this->logger->debug( "HTTP start: {method} {url}", [ 'method' => $req['method'], 'url' => $req['url'], 'headers' => $logHeaders, ] ); $req['flags'] ??= []; } } private function useReverseProxy( array &$req, $proxy ) { $parsedProxy = parse_url( $proxy ); if ( $parsedProxy === false ) { throw new InvalidArgumentException( "Invalid reverseProxy configured: $proxy" ); } $parsedUrl = parse_url( $req['url'] ); if ( $parsedUrl === false ) { throw new InvalidArgumentException( "Invalid url specified: {$req['url']}" ); } // Set the current host in the Host header // @phan-suppress-next-line PhanTypePossiblyInvalidDimOffset $req['headers']['Host'] = $parsedUrl['host']; // Replace scheme, host and port in the request // @phan-suppress-next-line PhanTypePossiblyInvalidDimOffset $parsedUrl['scheme'] = $parsedProxy['scheme']; // @phan-suppress-next-line PhanTypePossiblyInvalidDimOffset $parsedUrl['host'] = $parsedProxy['host']; if ( isset( $parsedProxy['port'] ) ) { $parsedUrl['port'] = $parsedProxy['port']; } else { unset( $parsedUrl['port'] ); } $req['url'] = self::assembleUrl( $parsedUrl ); // Explicitly disable use of another proxy by setting to false, // since null will fallback to $this->proxy $req['proxy'] = false; } /** * This is derived from MediaWiki\Utils\UrlUtils::assemble but changed to work * with parse_url's result so the delimiter is hardcoded. * * The basic structure used: * [scheme://][[user][:pass]@][host][:port][path][?query][#fragment] * * @param array $urlParts URL parts, as output from parse_url() * @return string URL assembled from its component parts */ private static function assembleUrl( array $urlParts ): string { $result = isset( $urlParts['scheme'] ) ? $urlParts['scheme'] . '://' : ''; if ( isset( $urlParts['host'] ) ) { if ( isset( $urlParts['user'] ) ) { $result .= $urlParts['user']; if ( isset( $urlParts['pass'] ) ) { $result .= ':' . $urlParts['pass']; } $result .= '@'; } $result .= $urlParts['host']; if ( isset( $urlParts['port'] ) ) { $result .= ':' . $urlParts['port']; } } if ( isset( $urlParts['path'] ) ) { $result .= $urlParts['path']; } if ( isset( $urlParts['query'] ) && $urlParts['query'] !== '' ) { $result .= '?' . $urlParts['query']; } if ( isset( $urlParts['fragment'] ) ) { $result .= '#' . $urlParts['fragment']; } return $result; } /** * Check if the URL can be served by localhost * * @note this is mostly a copy of MWHttpRequest::isLocalURL() * @param string $url Full url to check * @return bool */ private function isLocalURL( $url ) { if ( !$this->localVirtualHosts ) { // Shortcut return false; } // Extract host part $matches = []; if ( preg_match( '!^https?://([\w.-]+)[/:].*$!', $url, $matches ) ) { $host = $matches[1]; // Split up dotwise $domainParts = explode( '.', $host ); // Check if this domain or any superdomain is listed as a local virtual host $domainParts = array_reverse( $domainParts ); $domain = ''; $countParts = count( $domainParts ); for ( $i = 0; $i < $countParts; $i++ ) { $domainPart = $domainParts[$i]; if ( $i == 0 ) { $domain = $domainPart; } else { $domain = $domainPart . '.' . $domain; } if ( in_array( $domain, $this->localVirtualHosts ) ) { return true; } } } return false; } /** * Get a suitable select timeout for the given options. * * @param array $opts * @return float */ private function getSelectTimeout( $opts ) { $connTimeout = $opts['connTimeout'] ?? $this->connTimeout; $reqTimeout = $opts['reqTimeout'] ?? $this->reqTimeout; $timeouts = array_filter( [ $connTimeout, $reqTimeout ] ); if ( count( $timeouts ) === 0 ) { return 1; } $selectTimeout = min( $timeouts ) * self::TIMEOUT_ACCURACY_FACTOR; // Minimum 10us if ( $selectTimeout < 10e-6 ) { $selectTimeout = 10e-6; } return $selectTimeout; } /** * Register a logger * * @param LoggerInterface $logger */ public function setLogger( LoggerInterface $logger ) { $this->logger = $logger; } public function __destruct() { if ( $this->cmh ) { curl_multi_close( $this->cmh ); $this->cmh = null; } } } /** @deprecated class alias since 1.43 */ class_alias( MultiHttpClient::class, 'MultiHttpClient' ); PK ! p�7�� � http/HttpAcceptNegotiator.phpnu �Iw�� <?php namespace Wikimedia\Http; /** * Utility for negotiating a value from a set of supported values using a preference list. * This is intended for use with HTTP headers like Accept, Accept-Language, Accept-Encoding, etc. * See RFC 2616 section 14 for details. * * To use this with a request header, first parse the header value into an array of weights * using HttpAcceptParser, then call getBestSupportedKey. * * @license GPL-2.0-or-later * @author Daniel Kinzler * @author Thiemo Kreuz */ class HttpAcceptNegotiator { /** * @var string[] */ private $supportedValues; /** * @var string */ private $defaultValue; /** * @param string[] $supported A list of supported values. */ public function __construct( array $supported ) { $this->supportedValues = $supported; $this->defaultValue = reset( $supported ); } /** * Returns the best supported key from the given weight map. Of the keys from the * $weights parameter that are also in the list of supported values supplied to * the constructor, this returns the key that has the highest weight associated * with it. If two keys have the same weight, the more specific key is preferred, * as required by RFC2616 section 14. Keys that map to 0 or false are ignored. * If no matching key is found, $default is returned. * * @param float[] $weights An associative array mapping accepted values to their * respective weights. * * @param null|string $default The value to return if none of the keys in $weights * is supported (null by default). * * @return null|string The best supported key from the $weights parameter. */ public function getBestSupportedKey( array $weights, $default = null ) { // Make sure we correctly bias against wildcards and ranges, see RFC2616, section 14. foreach ( $weights as $name => &$weight ) { if ( $name === '*' || $name === '*/*' ) { $weight -= 0.000002; } elseif ( substr( $name, -2 ) === '/*' ) { $weight -= 0.000001; } } // Sort $weights by value and... asort( $weights ); // remove any keys with values equal to 0 or false (HTTP/1.1 section 3.9) $weights = array_filter( $weights ); // ...use the ordered list of keys $preferences = array_reverse( array_keys( $weights ) ); $value = $this->getFirstSupportedValue( $preferences, $default ); return $value; } /** * Returns the first supported value from the given preference list. Of the values from * the $preferences parameter that are also in the list of supported values supplied * to the constructor, this returns the value that has the lowest index in the list. * If no such value is found, $default is returned. * * @param string[] $preferences A list of acceptable values, in order of preference. * * @param null|string $default The value to return if non of the keys in $weights * is supported (null by default). * * @return null|string The best supported key from the $weights parameter. */ public function getFirstSupportedValue( array $preferences, $default = null ) { foreach ( $preferences as $value ) { foreach ( $this->supportedValues as $supported ) { if ( $this->valueMatches( $value, $supported ) ) { return $supported; } } } return $default; } /** * Returns true if the given acceptable value matches the given supported value, * according to the HTTP specification. The following rules are used: * * - comparison is case-insensitive * - if $accepted and $supported are equal, they match * - if $accepted is `*` or `*` followed by `/*`, it matches any $supported value. * - if both $accepted and $supported contain a `/`, and $accepted ends with `/*`, * they match if the part before the first `/` is equal. * * @param string $accepted An accepted value (may contain wildcards) * @param string $supported A supported value. * * @return bool Whether the given supported value matches the given accepted value. */ private function valueMatches( $accepted, $supported ) { // RDF 2045: MIME types are case insensitive. // full match if ( strcasecmp( $accepted, $supported ) === 0 ) { return true; } // wildcard match (HTTP/1.1 section 14.1, 14.2, 14.3) if ( $accepted === '*' || $accepted === '*/*' ) { return true; } // wildcard match (HTTP/1.1 section 14.1) if ( substr( $accepted, -2 ) === '/*' && strncasecmp( $accepted, $supported, strlen( $accepted ) - 2 ) === 0 ) { return true; } return false; } } PK ! 风eE E # rdbms/lbfactory/LBFactorySimple.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\Rdbms; use InvalidArgumentException; /** * LoadBalancer manager for sites with one "main" cluster and any number of "external" clusters * * @see LBFactoryMulti * * The class allows for large site farms to split up their data in the following ways: * - Vertically shard compact site-specific data by site (e.g. page/comment metadata) * - Vertically shard compact global data by module (e.g. account/notification data) * - Horizontally shard any bulk data by blob key (e.g. page/comment content) * * @ingroup Database */ class LBFactorySimple extends LBFactory { /** @var LoadBalancer */ private $mainLB; /** @var LoadBalancer[] */ private $externalLBs = []; /** @var array Configuration for the LoadMonitor to use within LoadBalancer instances */ private $loadMonitorConfig; /** @var array[] Map of (server index => server config map) */ private $mainServers; /** @var array[][] Map of (cluster => server index => server config map) */ private $externalServersByCluster = []; /** * @see LBFactory::__construct() * @param array $conf Additional parameters include: * - servers : list of server config maps to Database::factory(). * Additionally, the server maps should have a 'load' key, which is used to decide * how often clients connect to one server verses the others. A 'max lag' key should * also be set on server maps, indicating how stale the data can be before the load * balancer tries to avoid using it. The map can have 'is static' set to disable blocking * replication sync checks (intended for archive servers with unchanging data). * - externalClusters : map of cluster names to server arrays. The servers arrays have the * same format as "servers" above. * - loadMonitor: LoadMonitor::__construct() parameters with "class" field. [optional] */ public function __construct( array $conf ) { parent::__construct( $conf ); $this->mainServers = $conf['servers'] ?? []; foreach ( ( $conf['externalClusters'] ?? [] ) as $cluster => $servers ) { foreach ( $servers as $index => $server ) { $this->externalServersByCluster[$cluster][$index] = $server; } } if ( isset( $conf['loadMonitor'] ) ) { $this->loadMonitorConfig = $conf['loadMonitor']; } elseif ( isset( $conf['loadMonitorClass'] ) ) { // b/c $this->loadMonitorConfig = [ 'class' => $conf['loadMonitorClass'] ]; } else { $this->loadMonitorConfig = [ 'class' => LoadMonitor::class ]; } } public function newMainLB( $domain = false ): ILoadBalancerForOwner { return $this->newLoadBalancer( self::CLUSTER_MAIN_DEFAULT, $this->mainServers ); } public function getMainLB( $domain = false ): ILoadBalancer { $this->mainLB ??= $this->newMainLB( $domain ); return $this->mainLB; } public function newExternalLB( $cluster ): ILoadBalancerForOwner { if ( !isset( $this->externalServersByCluster[$cluster] ) ) { throw new InvalidArgumentException( "Unknown cluster '$cluster'." ); } return $this->newLoadBalancer( $cluster, $this->externalServersByCluster[$cluster] ); } public function getExternalLB( $cluster ): ILoadBalancer { if ( !isset( $this->externalLBs[$cluster] ) ) { $this->externalLBs[$cluster] = $this->newExternalLB( $cluster ); } return $this->externalLBs[$cluster]; } public function getAllMainLBs(): array { return [ self::CLUSTER_MAIN_DEFAULT => $this->getMainLB() ]; } public function getAllExternalLBs(): array { $lbs = []; foreach ( $this->externalServersByCluster as $cluster => $_ ) { $lbs[$cluster] = $this->getExternalLB( $cluster ); } return $lbs; } private function newLoadBalancer( string $clusterName, array $servers ) { $lb = new LoadBalancer( array_merge( $this->baseLoadBalancerParams(), [ 'servers' => $servers, 'loadMonitor' => $this->loadMonitorConfig, 'clusterName' => $clusterName ] ) ); $this->initLoadBalancer( $lb ); return $lb; } protected function getLBsForOwner() { if ( $this->mainLB !== null ) { yield $this->mainLB; } foreach ( $this->externalLBs as $lb ) { yield $lb; } } } PK ! E�4�= �= " rdbms/lbfactory/LBFactoryMulti.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\Rdbms; use InvalidArgumentException; use LogicException; use UnexpectedValueException; /** * LoadBalancer manager for sites with several "main" database clusters * * Each database cluster consists of a "primary" server and any number of replica servers, * all of which converge, as soon as possible, to contain the same schemas and records. If * a replication topology has multiple primaries, then the "primary" is merely the preferred * co-primary for the current context (e.g. datacenter). * * For single-primary topologies, the schemas and records of the primary define the "dataset". * For multiple-primary topologies, the "dataset" is the convergent result of applying/merging * all committed events (regardless of the co-primary they originated on); it possible that no * co-primary has yet converged upon this state at any given time (especially when there are * frequent writes and co-primaries are geographically distant). * * A "main" cluster contain a "main" dataset, which consists of data that is compact, highly * relational (e.g. read by JOIN queries), and essential to one or more sites. The "external" * clusters each store an "external" dataset, which consists of data that is non-relational * (e.g. key/value pairs), self-contained (e.g. JOIN queries and transactions thereof never * involve a main dataset), or too bulky to reside in a main dataset (e.g. text blobs). * * The class allows for large site farms to split up their data in the following ways: * - Vertically shard compact site-specific data by site (e.g. page/comment metadata) * - Vertically shard compact global data by module (e.g. account/notification data) * - Horizontally shard any bulk data by blob key (e.g. page/comment content blobs) * * @ingroup Database */ class LBFactoryMulti extends LBFactory { /** @var array<string,LoadBalancer> Map of (main section => tracked LoadBalancer) */ private $mainLBs = []; /** @var array<string,LoadBalancer> Map of (external cluster => tracked LoadBalancer) */ private $externalLBs = []; /** @var string[] Map of (server name => IP address) */ private $hostsByServerName; /** @var string[] Map of (database name => main section) */ private $sectionsByDB; /** @var int[][][] Map of (main section => group => server name => load ratio) */ private $groupLoadsBySection; /** @var int[][] Map of (external cluster => server name => load ratio) */ private $externalLoadsByCluster; /** @var array Server config map ("host", "serverName", "load", and "groupLoads" ignored) */ private $serverTemplate; /** @var array Server config map overriding "serverTemplate" for all external servers */ private $externalTemplateOverrides; /** @var array[] Map of (main section => server config map overrides) */ private $templateOverridesBySection; /** @var array[] Map of (external cluster => server config map overrides) */ private $templateOverridesByCluster; /** @var array Server config override map for all main/external primary DB servers */ private $masterTemplateOverrides; /** @var array[] Map of (server name => server config map overrides) for all servers */ private $templateOverridesByServer; /** @var string[]|bool[] A map of (main section => read-only message) */ private $readOnlyBySection; /** @var array Configuration for the LoadMonitor to use within LoadBalancer instances */ private $loadMonitorConfig; /** @var DatabaseDomain[] Map of (domain ID => domain instance) */ private $nonLocalDomainCache = []; /** * Template override precedence (highest => lowest): * - templateOverridesByServer * - masterTemplateOverrides * - templateOverridesBySection/templateOverridesByCluster * - externalTemplateOverrides * - serverTemplate * Overrides only work on top level keys (so nested values will not be merged). * * Server config maps should be of the format Database::factory() requires. * Additionally, a 'max lag' key should also be set on server maps, indicating how stale the * data can be before the load balancer tries to avoid using it. The map can have 'is static' * set to disable blocking replication sync checks (intended for archive servers with * unchanging data). * * @see LBFactory::__construct() * @param array $conf Additional parameters include: * - hostsByName: map of (server name => IP address). [optional] * - sectionsByDB: map of (database => main section). The database name "DEFAULT" is * interpreted as a catch-all for all databases not otherwise mentioned. If no section * name is specified for "DEFAULT", then the catch-all section is assumed to be named * "DEFAULT". [optional] * - sectionLoads: map of (main section => server name => load ratio); the first host * listed in each section is the primary DB server for that section. [optional] * - groupLoadsBySection: map of (main section => group => server name => group load ratio). * Any ILoadBalancer::GROUP_GENERIC group will be ignored. [optional] * - externalLoads: map of (cluster => server name => load ratio) map. [optional] * - serverTemplate: server config map for Database::factory(). * Note that "host", "serverName" and "load" entries will be overridden by * "groupLoadsBySection" and "hostsByName". [optional] * - externalTemplateOverrides: server config map overrides for external stores; * respects the override precedence described above. [optional] * - templateOverridesBySection: map of (main section => server config map overrides); * respects the override precedence described above. [optional] * - templateOverridesByCluster: map of (external cluster => server config map overrides); * respects the override precedence described above. [optional] * - masterTemplateOverrides: server config map overrides for masters; * respects the override precedence described above. [optional] * - templateOverridesByServer: map of (server name => server config map overrides); * respects the override precedence described above and applies to both core * and external storage. [optional] * - loadMonitor: LoadMonitor::__construct() parameters with "class" field. [optional] * - readOnlyBySection: map of (main section => message text or false). * String values make sections read only, whereas anything else does not * restrict read/write mode. [optional] * - configCallback: A callback that returns a conf array that can be passed to * the reconfigure() method. This will be used to autoReconfigure() to load * any updated configuration. */ public function __construct( array $conf ) { parent::__construct( $conf ); $this->hostsByServerName = $conf['hostsByName'] ?? []; $this->sectionsByDB = $conf['sectionsByDB']; $this->sectionsByDB += [ self::CLUSTER_MAIN_DEFAULT => self::CLUSTER_MAIN_DEFAULT ]; $this->groupLoadsBySection = $conf['groupLoadsBySection'] ?? []; foreach ( ( $conf['sectionLoads'] ?? [] ) as $section => $loadsByServerName ) { $this->groupLoadsBySection[$section][ILoadBalancer::GROUP_GENERIC] = $loadsByServerName; } $this->externalLoadsByCluster = $conf['externalLoads'] ?? []; $this->serverTemplate = $conf['serverTemplate'] ?? []; $this->externalTemplateOverrides = $conf['externalTemplateOverrides'] ?? []; $this->templateOverridesBySection = $conf['templateOverridesBySection'] ?? []; $this->templateOverridesByCluster = $conf['templateOverridesByCluster'] ?? []; $this->masterTemplateOverrides = $conf['masterTemplateOverrides'] ?? []; $this->templateOverridesByServer = $conf['templateOverridesByServer'] ?? []; $this->readOnlyBySection = $conf['readOnlyBySection'] ?? []; if ( isset( $conf['loadMonitor'] ) ) { $this->loadMonitorConfig = $conf['loadMonitor']; } elseif ( isset( $conf['loadMonitorClass'] ) ) { // b/c $this->loadMonitorConfig = [ 'class' => $conf['loadMonitorClass'] ]; } else { $this->loadMonitorConfig = [ 'class' => LoadMonitor::class ]; } foreach ( $this->externalLoadsByCluster as $cluster => $_ ) { if ( isset( $this->groupLoadsBySection[$cluster] ) ) { throw new LogicException( "External cluster '$cluster' has the same name as a main section/cluster" ); } } } public function newMainLB( $domain = false ): ILoadBalancerForOwner { $domainInstance = $this->resolveDomainInstance( $domain ); $database = $domainInstance->getDatabase(); $section = $this->getSectionFromDatabase( $database ); if ( !isset( $this->groupLoadsBySection[$section][ILoadBalancer::GROUP_GENERIC] ) ) { throw new UnexpectedValueException( "Section '$section' has no hosts defined." ); } return $this->newLoadBalancer( $section, array_merge( $this->serverTemplate, $this->templateOverridesBySection[$section] ?? [] ), $this->groupLoadsBySection[$section], // Use the LB-specific read-only reason if everything isn't already read-only is_string( $this->readOnlyReason ) ? $this->readOnlyReason : ( $this->readOnlyBySection[$section] ?? false ) ); } /** * @param DatabaseDomain|string|false $domain * @return DatabaseDomain */ private function resolveDomainInstance( $domain ) { if ( $domain instanceof DatabaseDomain ) { return $domain; // already a domain instance } elseif ( $domain === false || $domain === $this->localDomain->getId() ) { return $this->localDomain; } elseif ( isset( $this->domainAliases[$domain] ) ) { // This array acts as both the original map and as instance cache. // Instances pass-through DatabaseDomain::newFromId as-is. $this->domainAliases[$domain] = DatabaseDomain::newFromId( $this->domainAliases[$domain] ); return $this->domainAliases[$domain]; } $cachedDomain = $this->nonLocalDomainCache[$domain] ?? null; if ( $cachedDomain === null ) { $cachedDomain = DatabaseDomain::newFromId( $domain ); $this->nonLocalDomainCache = [ $domain => $cachedDomain ]; } return $cachedDomain; } public function getMainLB( $domain = false ): ILoadBalancer { $domainInstance = $this->resolveDomainInstance( $domain ); $section = $this->getSectionFromDatabase( $domainInstance->getDatabase() ); if ( !isset( $this->mainLBs[$section] ) ) { $this->mainLBs[$section] = $this->newMainLB( $domain ); } return $this->mainLBs[$section]; } public function newExternalLB( $cluster ): ILoadBalancerForOwner { if ( !isset( $this->externalLoadsByCluster[$cluster] ) ) { throw new InvalidArgumentException( "Unknown cluster '$cluster'" ); } return $this->newLoadBalancer( $cluster, array_merge( $this->serverTemplate, $this->externalTemplateOverrides, $this->templateOverridesByCluster[$cluster] ?? [] ), [ ILoadBalancer::GROUP_GENERIC => $this->externalLoadsByCluster[$cluster] ], $this->readOnlyReason ); } public function getExternalLB( $cluster ): ILoadBalancer { if ( !isset( $this->externalLBs[$cluster] ) ) { $this->externalLBs[$cluster] = $this->newExternalLB( $cluster ); } return $this->externalLBs[$cluster]; } public function getAllMainLBs(): array { $lbs = []; foreach ( $this->sectionsByDB as $db => $section ) { if ( !isset( $lbs[$section] ) ) { $lbs[$section] = $this->getMainLB( $db ); } } return $lbs; } public function getAllExternalLBs(): array { $lbs = []; foreach ( $this->externalLoadsByCluster as $cluster => $unused ) { $lbs[$cluster] = $this->getExternalLB( $cluster ); } return $lbs; } protected function getLBsForOwner() { foreach ( $this->mainLBs as $lb ) { yield $lb; } foreach ( $this->externalLBs as $lb ) { yield $lb; } } /** * Make a new load balancer object based on template and load array * * @param string $clusterName * @param array $serverTemplate * @param array $groupLoads * @param string|false $readOnlyReason * @return LoadBalancer */ private function newLoadBalancer( string $clusterName, array $serverTemplate, array $groupLoads, $readOnlyReason ) { $lb = new LoadBalancer( array_merge( $this->baseLoadBalancerParams(), [ 'servers' => $this->makeServerConfigArrays( $serverTemplate, $groupLoads ), 'loadMonitor' => $this->loadMonitorConfig, 'readOnlyReason' => $readOnlyReason, 'clusterName' => $clusterName ] ) ); $this->initLoadBalancer( $lb ); return $lb; } /** * Make a server array as expected by LoadBalancer::__construct() * * @param array $serverTemplate Server config map * @param int[][] $groupLoads Map of (group => server name => load) * @return array[] List of server config maps */ private function makeServerConfigArrays( array $serverTemplate, array $groupLoads ) { // The primary DB server is the first host explicitly listed in the generic load group if ( !$groupLoads[ILoadBalancer::GROUP_GENERIC] ) { throw new UnexpectedValueException( "Empty generic load array; no primary DB defined." ); } $groupLoadsByServerName = []; foreach ( $groupLoads as $group => $loadByServerName ) { foreach ( $loadByServerName as $serverName => $load ) { $groupLoadsByServerName[$serverName][$group] = $load; } } // Get the ordered map of (server name => load); the primary DB server is first $genericLoads = $groupLoads[ILoadBalancer::GROUP_GENERIC]; // Implicitly append any hosts that only appear in custom load groups $genericLoads += array_fill_keys( array_keys( $groupLoadsByServerName ), 0 ); $servers = []; foreach ( $genericLoads as $serverName => $load ) { $servers[] = array_merge( $serverTemplate, $servers ? [] : $this->masterTemplateOverrides, $this->templateOverridesByServer[$serverName] ?? [], [ 'host' => $this->hostsByServerName[$serverName] ?? $serverName, 'serverName' => $serverName, 'load' => $load, 'groupLoads' => $groupLoadsByServerName[$serverName] ?? [] ] ); } return $servers; } /** * @param string $database * @return string Main section name */ private function getSectionFromDatabase( $database ) { return $this->sectionsByDB[$database] ?? $this->sectionsByDB[self::CLUSTER_MAIN_DEFAULT] ?? self::CLUSTER_MAIN_DEFAULT; } public function reconfigure( array $conf ): void { if ( !$conf ) { return; } foreach ( $this->mainLBs as $lb ) { // Approximate what LBFactoryMulti::__construct does (T346365) $groupLoads = $conf['groupLoadsBySection'][$lb->getClusterName()] ?? []; $groupLoads[ILoadBalancer::GROUP_GENERIC] = $conf['sectionLoads'][$lb->getClusterName()]; $config = [ 'servers' => $this->makeServerConfigArrays( $conf['serverTemplate'] ?? [], $groupLoads ) ]; $lb->reconfigure( $config ); } foreach ( $this->externalLBs as $lb ) { $groupLoads = [ ILoadBalancer::GROUP_GENERIC => $conf['externalLoads'][$lb->getClusterName()] ]; $config = [ 'servers' => $this->makeServerConfigArrays( $conf['serverTemplate'] ?? [], $groupLoads ) ]; $lb->reconfigure( $config ); } } } PK ! ��� � ' rdbms/lbfactory/IConnectionProvider.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\Rdbms; /** * Provide primary and replica IDatabase connections. * * This is a narrow interface intended as the main entrypoint to the Rdbms library. * No methods should be added unless absolutely needed. * * The main implementation is \Wikimedia\Rdbms\LBFactory. * To obtain an instance, use \MediaWiki\MediaWikiServices::getDBLoadBalancerFactory(). * * @see ILBFactory * @since 1.40 * @ingroup Database */ interface IConnectionProvider { /** * Get connection to the primary database. * * This should be used when there the code needs to write to the database. * * This method accepts virtual domains * ({@see \MediaWiki\MainConfigSchema::VirtualDomainsMapping}). * * @since 1.40 * @param string|false $domain Domain ID, or false for the current domain * @return IDatabase */ public function getPrimaryDatabase( $domain = false ): IDatabase; /** * Get connection to a replica database. * * Note that a read can have replication lag. * * This method accepts virtual domains * ({@see \MediaWiki\MainConfigSchema::VirtualDomainsMapping}). * * @since 1.40 * @param string|false $domain Domain ID, or false for the current domain * @param string|null $group Query group; null for the default group * @return IReadableDatabase */ public function getReplicaDatabase( $domain = false, $group = null ): IReadableDatabase; /** * Commit primary DB transactions and wait for replication (if $ticket indicates it is safe). * * This is mostly used in jobs or deferred updates dealing with batching. * * The ticket is used to check that the caller owns the transaction round or can act on * behalf of the caller that owns the transaction round. * * @see ILBFactory::commitPrimaryChanges() * @see ILBFactory::waitForReplication() * @since 1.28 * @param string $fname Caller name (e.g. __METHOD__) * @param mixed $ticket Result of getEmptyTransactionTicket() * @param array $opts Options to waitForReplication() * @return bool True if the wait was successful, false on timeout */ public function commitAndWaitForReplication( $fname, $ticket, array $opts = [] ); /** * Get a token asserting that no write transactions are active on tracked connections. * * This is mostly used in jobs or deferred updates dealing with batching. * * @since 1.28 * @param string $fname Caller name (e.g. __METHOD__) * @return mixed A value to pass to commitAndWaitForReplication() */ public function getEmptyTransactionTicket( $fname ); } PK ! L�qR� � # rdbms/lbfactory/LBFactorySingle.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\Rdbms; use BadMethodCallException; use InvalidArgumentException; /** * LoadBalancer manager for sites with one "main" cluster using only injected database connections * * This class assumes that there are no "external" clusters. * * LoadBalancerDisabled will be used if a null connection handle is injected. * * @see ILBFactory * @ingroup Database */ class LBFactorySingle extends LBFactory { /** @var LoadBalancerSingle|LoadBalancerDisabled */ private $mainLB; /** * @note Use of {@link newFromConnection} is preferable * * @param array $conf An associative array containing one of the following: * - connection: The IDatabase connection handle to use; null to disable access */ public function __construct( array $conf ) { parent::__construct( $conf ); if ( !array_key_exists( 'connection', $conf ) ) { throw new InvalidArgumentException( "Missing 'connection' argument." ); } $conn = $conf['connection']; if ( $conn ) { $mainLB = new LoadBalancerSingle( array_merge( $this->baseLoadBalancerParams(), [ 'connection' => $conn ] ) ); } else { $mainLB = new LoadBalancerDisabled( $this->baseLoadBalancerParams() ); } $this->initLoadBalancer( $mainLB ); $this->mainLB = $mainLB; } /** * @param IDatabase $db Live connection handle * @param array $params Parameter map to LBFactorySingle::__construct() * @return LBFactorySingle * @since 1.28 */ public static function newFromConnection( IDatabase $db, array $params = [] ) { return new static( array_merge( [ 'localDomain' => $db->getDomainID() ], $params, [ 'connection' => $db ] ) ); } /** * @param array $params Parameter map to LBFactorySingle::__construct() * @return LBFactorySingle * @since 1.40 */ public static function newDisabled( array $params = [] ) { return new static( array_merge( $params, [ 'connection' => null ] ) ); } public function newMainLB( $domain = false ): ILoadBalancerForOwner { // @phan-suppress-previous-line PhanPluginNeverReturnMethod throw new BadMethodCallException( "Method is not supported." ); } public function getMainLB( $domain = false ): ILoadBalancer { return $this->mainLB; } public function newExternalLB( $cluster ): ILoadBalancerForOwner { // @phan-suppress-previous-line PhanPluginNeverReturnMethod throw new BadMethodCallException( "Method is not supported." ); } public function getExternalLB( $cluster ): ILoadBalancer { // @phan-suppress-previous-line PhanPluginNeverReturnMethod throw new BadMethodCallException( "Method is not supported." ); } public function getAllMainLBs(): array { return [ self::CLUSTER_MAIN_DEFAULT => $this->mainLB ]; } public function getAllExternalLBs(): array { return []; } protected function getLBsForOwner() { if ( $this->mainLB !== null ) { yield $this->mainLB; } } public function __destruct() { // do nothing since the connection was injected } } PK ! w��Y �Y rdbms/lbfactory/LBFactory.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\Rdbms; use Exception; use Generator; use Liuggio\StatsdClient\Factory\StatsdDataFactoryInterface; use Psr\Log\LoggerInterface; use Psr\Log\NullLogger; use RuntimeException; use Throwable; use Wikimedia\ObjectCache\BagOStuff; use Wikimedia\ObjectCache\EmptyBagOStuff; use Wikimedia\ObjectCache\WANObjectCache; use Wikimedia\RequestTimeout\CriticalSectionProvider; use Wikimedia\ScopedCallback; use Wikimedia\Stats\NullStatsdDataFactory; /** * @see ILBFactory * @ingroup Database */ abstract class LBFactory implements ILBFactory { /** @var CriticalSectionProvider|null */ private $csProvider; /** * @var callable|null An optional callback that returns a ScopedCallback instance, * meant to profile the actual query execution in {@see Database::doQuery} */ private $profiler; /** @var TransactionProfiler */ private $trxProfiler; /** @var StatsdDataFactoryInterface */ private $statsd; /** @var LoggerInterface */ private $logger; /** @var callable Error logger */ private $errorLogger; /** @var callable Deprecation logger */ private $deprecationLogger; /** @var ChronologyProtector */ protected $chronologyProtector; /** @var BagOStuff */ protected $srvCache; /** @var WANObjectCache */ protected $wanCache; /** @var DatabaseDomain Local domain */ protected $localDomain; /** @var bool Whether this PHP instance is for a CLI script */ private $cliMode; /** @var string Agent name for query profiling */ private $agent; /** @var array[] $aliases Map of (table => (dbname, schema, prefix) map) */ private $tableAliases = []; /** @var string[] Map of (index alias => index) */ private $indexAliases = []; /** @var DatabaseDomain[]|string[] Map of (domain alias => DB domain) */ protected $domainAliases = []; /** @var array[] Map of virtual domain to array of cluster and domain */ protected array $virtualDomainsMapping = []; /** @var string[] List of registered virtual domains */ protected array $virtualDomains = []; /** @var callable[] */ private $replicationWaitCallbacks = []; /** @var int|null Ticket used to delegate transaction ownership */ private $ticket; /** @var string|false String if a requested DBO_TRX transaction round is active */ private $trxRoundId = false; /** @var string One of the ROUND_* class constants */ private $trxRoundStage = self::ROUND_CURSORY; /** @var int Default replication wait timeout */ private $replicationWaitTimeout; /** @var string|false Reason all LBs are read-only or false if not */ protected $readOnlyReason = false; /** @var string|null */ private $defaultGroup = null; private const ROUND_CURSORY = 'cursory'; private const ROUND_BEGINNING = 'within-begin'; private const ROUND_COMMITTING = 'within-commit'; private const ROUND_ROLLING_BACK = 'within-rollback'; private const ROUND_COMMIT_CALLBACKS = 'within-commit-callbacks'; private const ROUND_ROLLBACK_CALLBACKS = 'within-rollback-callbacks'; private const ROUND_ROLLBACK_SESSIONS = 'within-rollback-session'; /** * @var callable */ private $configCallback = null; public function __construct( array $conf ) { $this->configure( $conf ); if ( isset( $conf['configCallback'] ) ) { $this->configCallback = $conf['configCallback']; } } /** * @param array $conf * @return void */ protected function configure( array $conf ): void { $this->localDomain = isset( $conf['localDomain'] ) ? DatabaseDomain::newFromId( $conf['localDomain'] ) : DatabaseDomain::newUnspecified(); if ( isset( $conf['readOnlyReason'] ) && is_string( $conf['readOnlyReason'] ) ) { $this->readOnlyReason = $conf['readOnlyReason']; } $this->chronologyProtector = $conf['chronologyProtector'] ?? new ChronologyProtector(); $this->srvCache = $conf['srvCache'] ?? new EmptyBagOStuff(); $this->wanCache = $conf['wanCache'] ?? WANObjectCache::newEmpty(); $this->logger = $conf['logger'] ?? new NullLogger(); $this->errorLogger = $conf['errorLogger'] ?? static function ( Throwable $e ) { trigger_error( get_class( $e ) . ': ' . $e->getMessage(), E_USER_WARNING ); }; $this->deprecationLogger = $conf['deprecationLogger'] ?? static function ( $msg ) { trigger_error( $msg, E_USER_DEPRECATED ); }; $this->profiler = $conf['profiler'] ?? null; $this->trxProfiler = $conf['trxProfiler'] ?? new TransactionProfiler(); $this->statsd = $conf['statsdDataFactory'] ?? new NullStatsdDataFactory(); $this->csProvider = $conf['criticalSectionProvider'] ?? null; $this->cliMode = $conf['cliMode'] ?? ( PHP_SAPI === 'cli' || PHP_SAPI === 'phpdbg' ); $this->agent = $conf['agent'] ?? ''; $this->defaultGroup = $conf['defaultGroup'] ?? null; $this->replicationWaitTimeout = $this->cliMode ? 60 : 1; $this->virtualDomainsMapping = $conf['virtualDomainsMapping'] ?? []; $this->virtualDomains = $conf['virtualDomains'] ?? []; static $nextTicket; $this->ticket = $nextTicket = ( is_int( $nextTicket ) ? $nextTicket++ : mt_rand() ); } public function destroy() { /** @noinspection PhpUnusedLocalVariableInspection */ $scope = ScopedCallback::newScopedIgnoreUserAbort(); foreach ( $this->getLBsForOwner() as $lb ) { $lb->disable( __METHOD__ ); } } /** * Reload config using the callback passed defined $config['configCallback']. * * If the config returned by the callback is different from the existing config, * this calls reconfigure() on all load balancers, which causes them to invalidate * any existing connections and re-connect using the new configuration. * * Long-running processes should call this from time to time * (but not too often, because it is somewhat expensive), * preferably after each batch. * Maintenance scripts can do that by calling $this->waitForReplication(), * which calls this method. */ public function autoReconfigure(): void { if ( !$this->configCallback ) { return; } $conf = ( $this->configCallback )(); if ( $conf ) { $this->reconfigure( $conf ); } } /** * Reconfigure using the given config array. * Any fields omitted from $conf will be taken from the current config. * * If the config changed, this calls reconfigure() on all load balancers, * which causes them to close all existing connections. * * @note This invalidates the current transaction ticket. * * @warning This must only be called in top level code such as the execute() * method of a maintenance script. Any database connection in use when this * method is called will become defunct. * * @since 1.39 * * @param array $conf A configuration array, using the same structure as * the one passed to the constructor (see also $wgLBFactoryConf). */ public function reconfigure( array $conf ): void { if ( !$conf ) { return; } foreach ( $this->getLBsForOwner() as $lb ) { $lb->reconfigure( $conf ); } } public function getLocalDomainID(): string { return $this->localDomain->getId(); } public function shutdown( $flags = self::SHUTDOWN_NORMAL, ?callable $workCallback = null, &$cpIndex = null, &$cpClientId = null ) { /** @noinspection PhpUnusedLocalVariableInspection */ $scope = ScopedCallback::newScopedIgnoreUserAbort(); if ( ( $flags & self::SHUTDOWN_NO_CHRONPROT ) != self::SHUTDOWN_NO_CHRONPROT ) { // Remark all of the relevant DB primary positions foreach ( $this->getLBsForOwner() as $lb ) { if ( $lb->hasPrimaryConnection() ) { $this->chronologyProtector->stageSessionPrimaryPos( $lb ); } } // Write the positions to the persistent stash $this->chronologyProtector->persistSessionReplicationPositions( $cpIndex ); $this->logger->debug( __METHOD__ . ': finished ChronologyProtector shutdown' ); } $cpClientId = $this->chronologyProtector->getClientId(); $this->commitPrimaryChanges( __METHOD__ ); $this->logger->debug( 'LBFactory shutdown completed' ); } public function getAllLBs() { foreach ( $this->getLBsForOwner() as $lb ) { yield $lb; } } /** * Get all tracked load balancers with the internal "for owner" interface. * * @return Generator|ILoadBalancerForOwner[] */ abstract protected function getLBsForOwner(); public function flushReplicaSnapshots( $fname = __METHOD__ ) { if ( $this->trxRoundId !== false && $this->trxRoundId !== $fname ) { $this->logger->warning( "$fname: transaction round '{$this->trxRoundId}' still running", [ 'exception' => new RuntimeException() ] ); } foreach ( $this->getLBsForOwner() as $lb ) { $lb->flushReplicaSnapshots( $fname ); } } final public function beginPrimaryChanges( $fname = __METHOD__ ) { $this->assertTransactionRoundStage( self::ROUND_CURSORY ); /** @noinspection PhpUnusedLocalVariableInspection */ $scope = ScopedCallback::newScopedIgnoreUserAbort(); foreach ( $this->getLBsForOwner() as $lb ) { $lb->flushReplicaSnapshots( $fname ); } $this->trxRoundStage = self::ROUND_BEGINNING; if ( $this->trxRoundId !== false ) { throw new DBTransactionError( null, "$fname: transaction round '{$this->trxRoundId}' already started" ); } $this->trxRoundId = $fname; // Flush snapshots and appropriately set DBO_TRX on primary connections foreach ( $this->getLBsForOwner() as $lb ) { $lb->beginPrimaryChanges( $fname ); } $this->trxRoundStage = self::ROUND_CURSORY; } final public function commitPrimaryChanges( $fname = __METHOD__, int $maxWriteDuration = 0 ) { $this->assertTransactionRoundStage( self::ROUND_CURSORY ); /** @noinspection PhpUnusedLocalVariableInspection */ $scope = ScopedCallback::newScopedIgnoreUserAbort(); $this->trxRoundStage = self::ROUND_COMMITTING; if ( $this->trxRoundId !== false && $this->trxRoundId !== $fname ) { throw new DBTransactionError( null, "$fname: transaction round '{$this->trxRoundId}' still running" ); } // Run pre-commit callbacks and suppress post-commit callbacks, aborting on failure do { $count = 0; // number of callbacks executed this iteration foreach ( $this->getLBsForOwner() as $lb ) { $count += $lb->finalizePrimaryChanges( $fname ); } } while ( $count > 0 ); $this->trxRoundId = false; // Perform pre-commit checks, aborting on failure foreach ( $this->getLBsForOwner() as $lb ) { $lb->approvePrimaryChanges( $maxWriteDuration, $fname ); } // Log the DBs and methods involved in multi-DB transactions $this->logIfMultiDbTransaction(); // Actually perform the commit on all primary DB connections and revert DBO_TRX foreach ( $this->getLBsForOwner() as $lb ) { $lb->commitPrimaryChanges( $fname ); } // Run all post-commit callbacks in a separate step $this->trxRoundStage = self::ROUND_COMMIT_CALLBACKS; $e = $this->executePostTransactionCallbacks(); $this->trxRoundStage = self::ROUND_CURSORY; // Throw any last post-commit callback error if ( $e instanceof Exception ) { throw $e; } foreach ( $this->getLBsForOwner() as $lb ) { $lb->flushReplicaSnapshots( $fname ); } } final public function rollbackPrimaryChanges( $fname = __METHOD__ ) { /** @noinspection PhpUnusedLocalVariableInspection */ $scope = ScopedCallback::newScopedIgnoreUserAbort(); $this->trxRoundStage = self::ROUND_ROLLING_BACK; $this->trxRoundId = false; // Actually perform the rollback on all primary DB connections and revert DBO_TRX foreach ( $this->getLBsForOwner() as $lb ) { $lb->rollbackPrimaryChanges( $fname ); } // Run all post-commit callbacks in a separate step $this->trxRoundStage = self::ROUND_ROLLBACK_CALLBACKS; $this->executePostTransactionCallbacks(); $this->trxRoundStage = self::ROUND_CURSORY; foreach ( $this->getLBsForOwner() as $lb ) { $lb->flushReplicaSnapshots( $fname ); } } final public function flushPrimarySessions( $fname = __METHOD__ ) { /** @noinspection PhpUnusedLocalVariableInspection */ $scope = ScopedCallback::newScopedIgnoreUserAbort(); // Release named locks and table locks on all primary DB connections $this->trxRoundStage = self::ROUND_ROLLBACK_SESSIONS; foreach ( $this->getLBsForOwner() as $lb ) { $lb->flushPrimarySessions( $fname ); } $this->trxRoundStage = self::ROUND_CURSORY; } /** * @return Exception|null */ private function executePostTransactionCallbacks() { $fname = __METHOD__; // Run all post-commit callbacks until new ones stop getting added $e = null; // first callback exception do { foreach ( $this->getLBsForOwner() as $lb ) { $ex = $lb->runPrimaryTransactionIdleCallbacks( $fname ); $e = $e ?: $ex; } } while ( $this->hasPrimaryChanges() ); // Run all listener callbacks once foreach ( $this->getLBsForOwner() as $lb ) { $ex = $lb->runPrimaryTransactionListenerCallbacks( $fname ); $e = $e ?: $ex; } return $e; } public function hasTransactionRound() { return ( $this->trxRoundId !== false ); } public function isReadyForRoundOperations() { return ( $this->trxRoundStage === self::ROUND_CURSORY ); } /** * Log query info if multi DB transactions are going to be committed now */ private function logIfMultiDbTransaction() { $callersByDB = []; foreach ( $this->getLBsForOwner() as $lb ) { $primaryName = $lb->getServerName( ServerInfo::WRITER_INDEX ); $callers = $lb->pendingPrimaryChangeCallers(); if ( $callers ) { $callersByDB[$primaryName] = $callers; } } if ( count( $callersByDB ) >= 2 ) { $dbs = implode( ', ', array_keys( $callersByDB ) ); $msg = "Multi-DB transaction [{$dbs}]:\n"; foreach ( $callersByDB as $db => $callers ) { $msg .= "$db: " . implode( '; ', $callers ) . "\n"; } $this->logger->info( $msg ); } } public function hasPrimaryChanges() { foreach ( $this->getLBsForOwner() as $lb ) { if ( $lb->hasPrimaryChanges() ) { return true; } } return false; } public function laggedReplicaUsed() { foreach ( $this->getLBsForOwner() as $lb ) { if ( $lb->laggedReplicaUsed() ) { return true; } } return false; } public function hasOrMadeRecentPrimaryChanges( $age = null ) { foreach ( $this->getLBsForOwner() as $lb ) { if ( $lb->hasOrMadeRecentPrimaryChanges( $age ) ) { return true; } } return false; } public function waitForReplication( array $opts = [] ) { $opts += [ 'timeout' => $this->replicationWaitTimeout, 'ifWritesSince' => null ]; $lbs = []; foreach ( $this->getLBsForOwner() as $lb ) { $lbs[] = $lb; } // Get all the primary DB positions of applicable DBs right now. // This can be faster since waiting on one cluster reduces the // time needed to wait on the next clusters. $primaryPositions = array_fill( 0, count( $lbs ), false ); foreach ( $lbs as $i => $lb ) { if ( // No writes to wait on getting replicated !$lb->hasPrimaryConnection() || // No replication; avoid getPrimaryPos() permissions errors (T29975) !$lb->hasStreamingReplicaServers() || // No writes since the last replication wait ( $opts['ifWritesSince'] && $lb->lastPrimaryChangeTimestamp() < $opts['ifWritesSince'] ) ) { continue; // no need to wait } $primaryPositions[$i] = $lb->getPrimaryPos(); } // Run any listener callbacks *after* getting the DB positions. The more // time spent in the callbacks, the less time is spent in waitForAll(). foreach ( $this->replicationWaitCallbacks as $callback ) { $callback(); } $failed = []; foreach ( $lbs as $i => $lb ) { if ( $primaryPositions[$i] ) { // The RDBMS may not support getPrimaryPos() if ( !$lb->waitForAll( $primaryPositions[$i], $opts['timeout'] ) ) { $failed[] = $lb->getServerName( ServerInfo::WRITER_INDEX ); } } } return !$failed; } public function setWaitForReplicationListener( $name, ?callable $callback = null ) { if ( $callback ) { $this->replicationWaitCallbacks[$name] = $callback; } else { unset( $this->replicationWaitCallbacks[$name] ); } } public function getEmptyTransactionTicket( $fname ) { if ( $this->hasPrimaryChanges() ) { $this->logger->error( __METHOD__ . ": $fname does not have outer scope", [ 'exception' => new RuntimeException() ] ); return null; } return $this->ticket; } public function getPrimaryDatabase( $domain = false ): IDatabase { return $this->getMappedDatabase( DB_PRIMARY, [], $domain ); } public function getReplicaDatabase( $domain = false, $group = null ): IReadableDatabase { if ( $group === null ) { $groups = []; } else { $groups = [ $group ]; } return $this->getMappedDatabase( DB_REPLICA, $groups, $domain ); } public function getLoadBalancer( $domain = false ): ILoadBalancer { if ( $domain !== false && in_array( $domain, $this->virtualDomains ) ) { if ( isset( $this->virtualDomainsMapping[$domain] ) ) { $config = $this->virtualDomainsMapping[$domain]; if ( isset( $config['cluster'] ) ) { return $this->getExternalLB( $config['cluster'] ); } $domain = $config['db']; } else { // It's not configured, assume local db. $domain = false; } } return $this->getMainLB( $domain ); } /** * Helper for getPrimaryDatabase and getReplicaDatabase() providing virtual * domain mapping. * * @param int $index * @param array $groups * @param string|false $domain * @return IDatabase */ private function getMappedDatabase( $index, $groups, $domain ) { if ( $domain !== false && in_array( $domain, $this->virtualDomains ) ) { $dbDomain = $this->virtualDomainsMapping[$domain]['db'] ?? false; } else { $dbDomain = $domain; } return $this->getLoadBalancer( $domain )->getConnection( $index, $groups, $dbDomain ); } final public function commitAndWaitForReplication( $fname, $ticket, array $opts = [] ) { if ( $ticket !== $this->ticket ) { $this->logger->error( __METHOD__ . ": $fname does not have outer scope ($ticket vs {$this->ticket})", [ 'exception' => new RuntimeException() ] ); return false; } // The transaction owner and any caller with the empty transaction ticket can commit // so that getEmptyTransactionTicket() callers don't risk seeing DBTransactionError. if ( $this->trxRoundId !== false && $fname !== $this->trxRoundId ) { $this->logger->info( "$fname: committing on behalf of {$this->trxRoundId}" ); $fnameEffective = $this->trxRoundId; } else { $fnameEffective = $fname; } $this->commitPrimaryChanges( $fnameEffective ); $waitSucceeded = $this->waitForReplication( $opts ); // If a nested caller committed on behalf of $fname, start another empty $fname // transaction, leaving the caller with the same empty transaction state as before. if ( $fnameEffective !== $fname ) { $this->beginPrimaryChanges( $fnameEffective ); } return $waitSucceeded; } public function disableChronologyProtection() { $this->chronologyProtector->setEnabled( false ); } /** * Get parameters to ILoadBalancer::__construct() * * @return array */ final protected function baseLoadBalancerParams() { if ( $this->trxRoundStage === self::ROUND_COMMIT_CALLBACKS ) { $initStage = ILoadBalancerForOwner::STAGE_POSTCOMMIT_CALLBACKS; } elseif ( $this->trxRoundStage === self::ROUND_ROLLBACK_CALLBACKS ) { $initStage = ILoadBalancerForOwner::STAGE_POSTROLLBACK_CALLBACKS; } else { $initStage = null; } return [ 'localDomain' => $this->localDomain, 'readOnlyReason' => $this->readOnlyReason, 'srvCache' => $this->srvCache, 'wanCache' => $this->wanCache, 'profiler' => $this->profiler, 'trxProfiler' => $this->trxProfiler, 'logger' => $this->logger, 'errorLogger' => $this->errorLogger, 'deprecationLogger' => $this->deprecationLogger, 'statsdDataFactory' => $this->statsd, 'cliMode' => $this->cliMode, 'agent' => $this->agent, 'defaultGroup' => $this->defaultGroup, 'chronologyProtector' => $this->chronologyProtector, 'roundStage' => $initStage, 'criticalSectionProvider' => $this->csProvider ]; } /** * @param ILoadBalancerForOwner $lb */ protected function initLoadBalancer( ILoadBalancerForOwner $lb ) { if ( $this->trxRoundId !== false ) { $lb->beginPrimaryChanges( $this->trxRoundId ); // set DBO_TRX } $lb->setTableAliases( $this->tableAliases ); $lb->setIndexAliases( $this->indexAliases ); $lb->setDomainAliases( $this->domainAliases ); } public function setTableAliases( array $aliases ) { $this->tableAliases = $aliases; } public function setIndexAliases( array $aliases ) { $this->indexAliases = $aliases; } public function setDomainAliases( array $aliases ) { $this->domainAliases = $aliases; } public function getTransactionProfiler(): TransactionProfiler { return $this->trxProfiler; } public function setLocalDomainPrefix( $prefix ) { $this->localDomain = new DatabaseDomain( $this->localDomain->getDatabase(), $this->localDomain->getSchema(), $prefix ); foreach ( $this->getLBsForOwner() as $lb ) { $lb->setLocalDomainPrefix( $prefix ); } } public function redefineLocalDomain( $domain ) { $this->closeAll( __METHOD__ ); $this->localDomain = DatabaseDomain::newFromId( $domain ); foreach ( $this->getLBsForOwner() as $lb ) { $lb->redefineLocalDomain( $this->localDomain ); } } public function closeAll( $fname = __METHOD__ ) { /** @noinspection PhpUnusedLocalVariableInspection */ $scope = ScopedCallback::newScopedIgnoreUserAbort(); foreach ( $this->getLBsForOwner() as $lb ) { $lb->closeAll( $fname ); } } public function setAgentName( $agent ) { $this->agent = $agent; } public function hasStreamingReplicaServers() { foreach ( $this->getLBsForOwner() as $lb ) { if ( $lb->hasStreamingReplicaServers() ) { return true; } } return false; } public function setDefaultReplicationWaitTimeout( $seconds ) { $old = $this->replicationWaitTimeout; $this->replicationWaitTimeout = max( 1, (int)$seconds ); return $old; } /** * @param string $stage */ private function assertTransactionRoundStage( $stage ) { if ( $this->trxRoundStage !== $stage ) { throw new DBTransactionError( null, "Transaction round stage must be '$stage' (not '{$this->trxRoundStage}')" ); } } } PK ! p!9�J J rdbms/lbfactory/ILBFactory.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\Rdbms; use Generator; use InvalidArgumentException; /** * Manager of ILoadBalancer objects and, indirectly, IDatabase connections * * Each Load balancer instances corresponds to a specific database cluster. * A "cluster" is the set of database servers that manage a given dataset. * * The "main" clusters are meant to colocate the most basic and highly relational application * data for one or more "sister projects" managed by this site. This allows for highly flexible * queries. Each project is identified by a database domain. Note that if there are several * projects stored on a cluster, then the cluster dataset is a superset of the dataset for each * of those projects. * * The "external" clusters are meant to provide places for bulk text storage, to colocate bulky * relational data from specific modules, and to colocate data from cross-project modules such * as authentication systems. An external cluster can have a database/schema for each project. * * @see ILoadBalancer * * @ingroup Database * @since 1.28 */ interface ILBFactory extends IConnectionProvider { /** Idiom for "no special shutdown flags" */ public const SHUTDOWN_NORMAL = 0; /** Do not save "session consistency" DB replication positions */ public const SHUTDOWN_NO_CHRONPROT = 1; /** @var string Default main cluster name (do not change this) */ public const CLUSTER_MAIN_DEFAULT = 'DEFAULT'; /** * Sub-classes may extend the required keys in $conf with additional parameters * * @param array $conf Array with keys: * - localDomain: A DatabaseDomain or database domain ID string * - virtualDomains: List of virtual database domain ID strings [optional]. * These can be passed to {@see ILBFactory::getPrimaryDatabase()} and * {@see ILBFactory::getReplicaDatabase()}, with the actual cluster and database * domain being automatically resolved via "virtualDomainsMapping". Virtual database * domains not defined there will resolve to the local database domain. * - virtualDomainsMapping: Map of (virtual database domain ID => config map) [optional]. * Each config map has a "db" key and an optional "cluster" key. The "db" key specifies * the actual database domain configured for use, with false indicating that the local * database domain is configured for use. The "cluster" key, if provided, specifies the * name of the external cluster configured for use, otherwise, the main cluster for the * actual database domain will be used. * - chronologyProtector: ChronologyProtector instance [optional] * - readOnlyReason: Reason the primary server is read-only (false if not) * - srvCache: BagOStuff instance for server cache [optional] * - cpStash: BagOStuff instance for ChronologyProtector store [optional]. * See [ChronologyProtector requirements](@ref ChronologyProtector-storage-requirements). * - wanCache: WANObjectCache instance [optional] * - cliMode: Whether the execution context is a CLI script [optional] * - profiler: Callback that takes a profile section name and returns a ScopedCallback * that ends the profile section in its destructor [optional] * - trxProfiler: TransactionProfiler instance [optional] * - logger: PSR-3 logger instance [optional] * - errorLogger: Callback that takes an Exception and logs it [optional] * - deprecationLogger: Callback to log a deprecation warning [optional] * - secret: Secret string to use for HMAC hashing [optional] * - criticalSectionProvider: CriticalSectionProvider instance [optional] */ public function __construct( array $conf ); /** * Close all connections and make further attempts to open connections result in DBAccessError * * This only applies to the tracked load balancer instances. * * @see ILoadBalancer::disable() */ public function destroy(); /** * Reload the configuration if necessary. * This may or may not have any effect. */ public function autoReconfigure(): void; /** * Get the local (and default) database domain ID of connection handles * * @see DatabaseDomain * @return string Database domain ID; this specifies DB name, schema, and table prefix * @since 1.32 */ public function getLocalDomainID(): string; /** * Close all connections and redefine the local database domain * * This only applies to the tracked load balancer instances. * * This method is only intended for use with schema creation or integration testing * * @param DatabaseDomain|string $domain * @since 1.33 */ public function redefineLocalDomain( $domain ); /** * Get the tracked load balancer instance for a given domain. * * If no tracked instances exists, then one will be instantiated. * * This method accepts virtual domains * ({@see \MediaWiki\MainConfigSchema::VirtualDomainsMapping}). * * @since 1.43 * @param string|false $domain Domain ID, or false for the current domain * @return ILoadBalancer */ public function getLoadBalancer( $domain = false ): ILoadBalancer; /** * Create a new load balancer instance for the main cluster that handles the given domain * * The resulting object is considered to be owned by the caller. Namely, it will be * untracked, the caller is responsible for cleaning it up, and replication positions * from it will not be saved by ChronologyProtector. * * This method is for only advanced usage and callers should almost always use * getMainLB() instead. This method can be useful when a table is used as a key/value * store. In that cases, one might want to query it in autocommit mode (DBO_TRX off) * but still use DBO_TRX transaction rounds on other tables. * * @note The local/default database domain used by the load balancer instance will * still inherit from this ILBFactory instance, regardless of the $domain parameter. * * @param string|false $domain Domain ID, or false for the current domain * @return ILoadBalancerForOwner */ public function newMainLB( $domain = false ): ILoadBalancerForOwner; /** * Get the tracked load balancer instance for the main cluster that handles the given domain * * If no tracked instances exists, then one will be instantiated * * @note The local/default database domain used by the load balancer instance will * still inherit from this ILBFactory instance, regardless of the $domain parameter. * * @param string|false $domain Domain ID, or false for the current domain * @return ILoadBalancer */ public function getMainLB( $domain = false ): ILoadBalancer; /** * Create a new load balancer instance for an external cluster * * The resulting object will be untracked and the caller is responsible for cleaning it up. * Database replication positions will not be saved by ChronologyProtector. * * This method is for only advanced usage and callers should almost always use * getExternalLB() instead. This method can be useful when a table is used as a * key/value store. In that cases, one might want to query it in autocommit mode * (DBO_TRX off) but still use DBO_TRX transaction rounds on other tables. * * @param string $cluster External cluster name * @throws InvalidArgumentException If $cluster is not recognized * @return ILoadBalancerForOwner */ public function newExternalLB( $cluster ): ILoadBalancerForOwner; /** * Get the tracked load balancer instance for an external cluster * * If no tracked instances exists, then one will be instantiated * * @param string $cluster External cluster name * @throws InvalidArgumentException If $cluster is not recognized * @return ILoadBalancer */ public function getExternalLB( $cluster ): ILoadBalancer; /** * Get the tracked load balancer instances for all main clusters * * If no tracked instance exists for a cluster, then one will be instantiated * * Note that default main cluster name is ILoadBalancer::CLUSTER_MAIN_DEFAULT * * @return ILoadBalancer[] Map of (cluster name => ILoadBalancer) * @since 1.29 */ public function getAllMainLBs(): array; /** * Get the tracked load balancer instances for all external clusters * * If no tracked instance exists for a cluster, then one will be instantiated * * @return ILoadBalancer[] Map of (cluster name => ILoadBalancer) * @since 1.29 */ public function getAllExternalLBs(): array; /** * Get all tracked load balancer instances (generator) * * @return Generator|ILoadBalancer[] * @since 1.39 */ public function getAllLBs(); /** * Prepare all instantiated tracked load balancer instances for shutdown * * @param int $flags Bit field of ILBFactory::SHUTDOWN_* constants * @param callable|null $workCallback Work to mask ChronologyProtector writes * @param int|null &$cpIndex Position key write counter for ChronologyProtector [returned] * @param string|null &$cpClientId Client ID hash for ChronologyProtector [returned] */ public function shutdown( $flags = self::SHUTDOWN_NORMAL, ?callable $workCallback = null, &$cpIndex = null, &$cpClientId = null ); /** * Commit all replica database server transactions, clearing any point-in-time view snapshots * * This only applies to the instantiated tracked load balancer instances. * * This is useful for getting rid of stale data from an implicit transaction round * * @param string $fname Caller name @phan-mandatory-param * @deprecated Since 1.43 */ public function flushReplicaSnapshots( $fname = __METHOD__ ); /** * Wrap subsequent queries for all transaction round aware primary connections in a transaction * * Each of these transactions will be owned by this ILBFactory instance such that direct * calls to {@link IDatabase::commit()} or {@link IDatabase::rollback()} will be disabled. * These transactions get resolved by a single call to either {@link commitPrimaryChanges()} * or {@link rollbackPrimaryChanges()}, after which, the transaction wrapping and ownership * behavior revert back to the default. When there are multiple connections involved, these * methods perform best-effort distributed transactions. When using distributed transactions, * the RDBMS should be configured to used pessimistic concurrency control such that the commit * step of each transaction is unlikely to fail. * * Transactions on replication connections are flushed so that future reads will not keep * using the same point-in-time view snapshots (e.g. from MySQL REPEATABLE-READ). However, * this does not wait for replication to catch up, so subsequent reads from replicas might * not reflect recently committed changes. * * This only applies to the tracked load balancer instances. * * This allows for custom transaction rounds from any outer transaction scope. * * @param string $fname @phan-mandatory-param * @throws DBTransactionError * @since 1.37 */ public function beginPrimaryChanges( $fname = __METHOD__ ); /** * Commit all primary connection transactions and flush all replica connection transactions * * Transactions on replication connections are flushed so that future reads will not keep * using the same point-in-time view snapshots (e.g. from MySQL REPEATABLE-READ). However, * this does not wait for replication to catch up, so subsequent reads from replicas might * not reflect the committed changes. * * This only applies to the instantiated tracked load balancer instances. * * @param string $fname Caller name @phan-mandatory-param * @param int $maxWriteDuration abort if more than this much time was spent in write queries * @throws DBTransactionError * @since 1.37 */ public function commitPrimaryChanges( $fname = __METHOD__, int $maxWriteDuration = 0 ); /** * Rollback all primary connection transactions and flush all replica connection transactions * * This only applies to the instantiated tracked load balancer instances. * * @param string $fname Caller name @phan-mandatory-param * @since 1.37 */ public function rollbackPrimaryChanges( $fname = __METHOD__ ); /** * Release important session-level state (named lock, table locks) as post-rollback cleanup * * This only applies to the instantiated tracked load balancer instances. * * This should only be called by application entry point functions, since there must be * no chance that a future caller will still be expecting some of the lost session state. * * @param string $fname Caller name @phan-mandatory-param * @since 1.38 */ public function flushPrimarySessions( $fname = __METHOD__ ); /** * Check if an explicit transaction round is active * * @return bool * @since 1.29 */ public function hasTransactionRound(); /** * Check if transaction rounds can be started, committed, or rolled back right now * * This can be used as a recursion guard to avoid exceptions in transaction callbacks. * * @return bool * @since 1.32 */ public function isReadyForRoundOperations(); /** * Determine if any primary connection has pending changes * * This only applies to the instantiated tracked load balancer instances. * * @return bool * @since 1.37 */ public function hasPrimaryChanges(); /** * Determine if any lagged replica database server connection was used. * * This only applies to the instantiated tracked load balancer instances. * * @return bool */ public function laggedReplicaUsed(); /** * Determine if any primary connection has pending/written changes from this request * * This only applies to the instantiated tracked load balancer instances. * * @param float|null $age How many seconds ago is "recent" [defaults to LB lag wait timeout] * @return bool */ public function hasOrMadeRecentPrimaryChanges( $age = null ); /** * Waits for the replica database server to catch up to the current primary position * * Use this when updating very large numbers of rows, as in maintenance scripts, to * avoid causing too much lag. This is a no-op if there are no replica database servers. * * By default this waits on all DB clusters actually used in this request. * This makes sense when lag being waiting on is caused by the code that does this check. * In that case, setting "ifWritesSince" can avoid the overhead of waiting for clusters * that were not changed since the last wait check. * * Never call this function after a large DB write that is *still* in a transaction. * It only makes sense to call this after the possible lag inducing changes were committed. * * This only applies to the instantiated tracked load balancer instances. * * @param array $opts Optional fields that include: * - timeout: Max wait time. Default: 60 seconds for CLI, 1 second for web. * - ifWritesSince: Only wait if writes were done since this UNIX timestamp. * @return bool True on success, false if a timeout or error occurred while waiting */ public function waitForReplication( array $opts = [] ); /** * Add a callback to be run in every call to waitForReplication() prior to any waiting * * Callbacks must clear any transactions that they start. * * @param string $name Callback name * @param callable|null $callback Use null to unset a callback */ public function setWaitForReplicationListener( $name, ?callable $callback = null ); /** * Disable the ChronologyProtector on all instantiated tracked load balancer instances * * This can be called at the start of special API entry points. */ public function disableChronologyProtection(); /** * Set a new table prefix for the existing local domain ID for testing * * @param string $prefix * @since 1.33 */ public function setLocalDomainPrefix( $prefix ); /** * Close all connections on instantiated tracked load balancer instances * * @param string $fname Caller name (e.g. __METHOD__) @phan-mandatory-param */ public function closeAll( $fname = __METHOD__ ); /** * @param string $agent Agent name for query profiling */ public function setAgentName( $agent ); /** * Whether it has streaming replica servers. * * @since 1.41 * @return bool */ public function hasStreamingReplicaServers(); /** * Set the default timeout for replication wait checks * * @param int $seconds Timeout, in seconds * @return int The previous default timeout * @since 1.35 */ public function setDefaultReplicationWaitTimeout( $seconds ); /** * Make certain table names use their own database, schema, and table prefix * when passed into SQL queries pre-escaped and without a qualified database name * * For example, "user" can be converted to "myschema.mydbname.user" for convenience. * Appearances like `user`, somedb.user, somedb.someschema.user will used literally. * * Calling this twice will completely clear any old table aliases. Also, note that * callers are responsible for making sure the schemas and databases actually exist. * * @param array[] $aliases Map of (table => (dbname, schema, prefix) map) * @since 1.31 */ public function setTableAliases( array $aliases ); /** * Convert certain index names to alternative names before querying the DB * * Note that this applies to indexes regardless of the table they belong to. * * This can be employed when an index was renamed X => Y in code, but the new Y-named * indexes were not yet built on all DBs. After all the Y-named ones are added by the DBA, * the aliases can be removed, and then the old X-named indexes dropped. * * @param string[] $aliases Map of (index alias => index name) * @since 1.31 */ public function setIndexAliases( array $aliases ); /** * Convert certain database domains to alternative ones * * This can be used for backwards compatibility logic. * * @param DatabaseDomain[]|string[] $aliases Map of (domain alias => domain) * @since 1.35 */ public function setDomainAliases( array $aliases ); /** * Get the TransactionProfiler used by this instance * * @return TransactionProfiler * @since 1.35 */ public function getTransactionProfiler(): TransactionProfiler; } PK ! �v� rdbms/ConfiguredReadOnlyMode.phpnu �Iw�� <?php namespace Wikimedia\Rdbms; /** * Determine whether a site is statically configured as read-only. * * Unlike ReadOnlyMode, this only checks site configuration. * It does not confirm whether the primary database host actively accepts writes. * * To obtain an instance, use \MediaWiki\MediaWikiServices::getConfiguredReadOnlyMode(). * This service can be configured via $wgReadOnly and $wgReadOnlyFile. * * @since 1.29 */ class ConfiguredReadOnlyMode { /** @var string|false|null */ private $reason; /** @var string|null */ private $reasonFile; /** * @param string|false|null $reason Current reason for read-only mode, if known. null means look * in $reasonFile instead. * @param string|null $reasonFile A file to look in for a reason, if $reason is null. If it * exists and is non-empty, its contents are treated as the reason for read-only mode. * Otherwise, the site is not read-only. */ public function __construct( $reason, ?string $reasonFile = null ) { $this->reason = $reason; $this->reasonFile = $reasonFile; } /** * Check whether the site is in read-only mode. * * @return bool */ public function isReadOnly(): bool { return $this->getReason() !== false; } /** * @return string|false String when in read-only mode; false otherwise */ public function getReason() { if ( $this->reason !== null ) { return $this->reason; } if ( $this->reasonFile === null ) { return false; } // Try the reason file if ( is_file( $this->reasonFile ) && filesize( $this->reasonFile ) > 0 ) { $this->reason = file_get_contents( $this->reasonFile ); } // No need to try the reason file again $this->reasonFile = null; return $this->reason ?? false; } /** * Set the read-only mode, which will apply for the remainder of the * request or until a service reset. * * @param string|false|null $msg */ public function setReason( $msg ): void { $this->reason = $msg; } } /** @deprecated class alias since 1.41 */ class_alias( ConfiguredReadOnlyMode::class, 'ConfiguredReadOnlyMode' ); PK ! *��"� � $ rdbms/expression/ExpressionGroup.phpnu �Iw�� <?php namespace Wikimedia\Rdbms; use InvalidArgumentException; use Wikimedia\Rdbms\Database\DbQuoter; // Very long type annotations :( // phpcs:disable Generic.Files.LineLength /** * A composite node representing a group of expressions. * * @since 1.42 */ abstract class ExpressionGroup implements IExpression { /** * @var IExpression[] */ protected array $children = []; /** * @param IExpression ...$children * @internal Outside of rdbms, Use IReadableDatabase::andExpr() or ::orExpr to create an expression group object */ public function __construct( IExpression ...$children ) { $this->children = $children; } final protected function add( IExpression $expression ) { $this->children[] = $expression; } abstract protected function getType(): string; /** * @internal to rdbms * @param non-empty-array<string,?scalar|RawSQLValue|Blob|LikeValue|non-empty-list<scalar|Blob>>|non-empty-array<int,IExpression> $conds * @param-taint $conds exec_sql_numkey * @return static */ public static function newFromArray( array $conds ) { if ( !$conds ) { throw new InvalidArgumentException( "The array of conditions can't be empty." ); } $exprs = []; foreach ( $conds as $field => $cond ) { if ( is_numeric( $field ) ) { if ( !$cond instanceof IExpression ) { throw new InvalidArgumentException( __METHOD__ . ": Only IExpression are allowed with numeric key." ); } $exprs[] = $cond; } else { if ( $cond instanceof IExpression ) { throw new InvalidArgumentException( __METHOD__ . ": unexpected key $field for IExpression value" ); } $exprs[] = new Expression( $field, '=', $cond ); } } // @phan-suppress-next-line PhanTypeInstantiateAbstractStatic return new static( ...$exprs ); } /** * @param DbQuoter $dbQuoter * @return string * @return-taint none */ final public function toSql( DbQuoter $dbQuoter ): string { if ( !$this->children ) { throw new InvalidArgumentException( "The array of values can't be empty." ); } $sqls = array_map( static fn ( $value ) => $value->toSql( $dbQuoter ), $this->children ); return '(' . implode( ' ' . $this->getType() . ' ', $sqls ) . ')'; } final public function toGeneralizedSql(): string { if ( !$this->children ) { throw new InvalidArgumentException( "The array of values can't be empty." ); } $sqls = array_map( static fn ( $value ) => $value->toGeneralizedSql(), $this->children ); return '(' . implode( ' ' . $this->getType() . ' ', $sqls ) . ')'; } } PK ! Y@/�� � % rdbms/expression/RawSQLExpression.phpnu �Iw�� <?php namespace Wikimedia\Rdbms; use Wikimedia\Rdbms\Database\DbQuoter; /** * Raw SQL expression to be used in query builders * * @note This should be used very rarely and NEVER with user input. * * @newable * @since 1.42 */ class RawSQLExpression extends Expression { private string $expression = ''; /** * This should be used very rarely and NEVER with user input. * * It can be used as a boolean expression in a WHERE condition, in cases where `$db->expr()` * can't be used because the expression doesn't have a left side, operator and right side, * e.g. for conditions like `WHERE EXISTS( SELECT ... )`. * * $queryBuilder->where( new RawSQLExpression( 'EXISTS(' . $subqueryBuilder->getSQL() . ')' ) ) * * Or when the condition is a simple SQL literal and writing it as SQL is the easiest: * * $queryBuilder->where( new RawSQLExpression( 'range_start != range_end' ) ) * * (See also RawSQLValue, which may be more readable in other cases.) * * @param string $expression Expression (SQL fragment) * @param-taint $expression exec_sql * @since 1.42 */ public function __construct( string $expression ) { $this->expression = $expression; } /** * @internal to be used by rdbms library only */ public function toSql( DbQuoter $dbQuoter ): string { return $this->expression; } public function toGeneralizedSql(): string { return $this->expression; } } PK ! =��p� � ' rdbms/expression/AndExpressionGroup.phpnu �Iw�� <?php namespace Wikimedia\Rdbms; /** * Representing a group of expressions chained via AND * * @since 1.42 */ class AndExpressionGroup extends ExpressionGroup { protected function getType(): string { return 'AND'; } // While these methods are not actually "side-effect-free" (they mutate the object), // we annotate them with @phan-side-effect-free for consistency with Expression. /** * @param string $field * @param-taint $field exec_sql * @param string $op One of '>', '<', '!=', '=', '>=', '<=', IExpression::LIKE, IExpression::NOT_LIKE * @phan-param '\x3E'|'\x3C'|'!='|'='|'\x3E='|'\x3C='|'LIKE'|'NOT LIKE' $op * @param-taint $op exec_sql * @param ?scalar|RawSQLValue|Blob|LikeValue|non-empty-list<scalar|Blob> $value * @param-taint $value escapes_sql * @phan-side-effect-free */ public function and( string $field, string $op, $value ): AndExpressionGroup { $expr = new Expression( $field, $op, $value ); $this->add( $expr ); return $this; } /** * @param IExpression $expr * @return AndExpressionGroup * @phan-side-effect-free */ public function andExpr( IExpression $expr ): AndExpressionGroup { $this->add( $expr ); return $this; } } PK ! #��/ / rdbms/expression/IExpression.phpnu �Iw�� <?php namespace Wikimedia\Rdbms; use Wikimedia\Rdbms\Database\DbQuoter; /** * @since 1.42 */ interface IExpression { public const ACCEPTABLE_OPERATORS = [ '>', '<', '!=', '=', '>=', '<=', self::LIKE, self::NOT_LIKE ]; public const LIKE = 'LIKE'; public const NOT_LIKE = 'NOT LIKE'; /** * Return SQL for execution. * @internal */ public function toSql( DbQuoter $dbQuoter ): string; /** * Return SQL for aggregated logging. * * Replaces values with placeholders. * * @internal */ public function toGeneralizedSql(): string; } PK ! h�?�B B rdbms/expression/Expression.phpnu �Iw�� <?php namespace Wikimedia\Rdbms; use InvalidArgumentException; use LogicException; use Wikimedia\Rdbms\Database\DbQuoter; /** * A composite leaf representing an expression. * * @since 1.42 */ class Expression implements IExpression { private string $field; private string $op; /** @var ?scalar|RawSQLValue|Blob|LikeValue|non-empty-list<scalar|Blob> */ private $value; /** * Store an expression * * @param string $field * @param-taint $field exec_sql * @param string $op One of '>', '<', '!=', '=', '>=', '<=', IExpression::LIKE, IExpression::NOT_LIKE * @phan-param '\x3E'|'\x3C'|'!='|'='|'\x3E='|'\x3C='|'LIKE'|'NOT LIKE' $op * @param-taint $op exec_sql * @param ?scalar|RawSQLValue|Blob|LikeValue|non-empty-list<scalar|Blob> $value * @param-taint $value escapes_sql * @internal Outside of rdbms, Use IReadableDatabase::expr() to create an expression object. */ public function __construct( string $field, string $op, $value ) { if ( !in_array( $op, IExpression::ACCEPTABLE_OPERATORS ) ) { throw new InvalidArgumentException( "Operator $op is not supported" ); } if ( ( is_array( $value ) || $value === null ) && !in_array( $op, [ '!=', '=' ] ) ) { throw new InvalidArgumentException( "Operator $op can't take array or null as value" ); } if ( is_array( $value ) ) { if ( !$value ) { throw new InvalidArgumentException( "The array of values can't be empty" ); } elseif ( !array_is_list( $value ) ) { throw new InvalidArgumentException( "The array of values must be a list" ); } elseif ( in_array( null, $value, true ) ) { throw new InvalidArgumentException( "NULL can't be in the array of values" ); } } if ( in_array( $op, [ IExpression::LIKE, IExpression::NOT_LIKE ] ) && !( $value instanceof LikeValue ) ) { throw new InvalidArgumentException( "Value for 'LIKE' expression must be of LikeValue type" ); } if ( !in_array( $op, [ IExpression::LIKE, IExpression::NOT_LIKE ] ) && ( $value instanceof LikeValue ) ) { throw new InvalidArgumentException( "LikeValue may only be used with 'LIKE' expression" ); } $field = trim( $field ); if ( !preg_match( '/^[A-Za-z\d\._]+$/', $field ) ) { throw new InvalidArgumentException( "$field might contain SQL injection" ); } $this->field = $field; $this->op = $op; $this->value = $value; } /** * @param string $field * @param-taint $field exec_sql * @param string $op One of '>', '<', '!=', '=', '>=', '<=', IExpression::LIKE, IExpression::NOT_LIKE * @phan-param '\x3E'|'\x3C'|'!='|'='|'\x3E='|'\x3C='|'LIKE'|'NOT LIKE' $op * @param-taint $op exec_sql * @param ?scalar|RawSQLValue|Blob|LikeValue|non-empty-list<scalar|Blob> $value * @param-taint $value escapes_sql * @phan-side-effect-free */ public function and( string $field, string $op, $value ): AndExpressionGroup { $exprGroup = new AndExpressionGroup( $this ); return $exprGroup->and( $field, $op, $value ); } /** * @param string $field * @param-taint $field exec_sql * @param string $op One of '>', '<', '!=', '=', '>=', '<=', IExpression::LIKE, IExpression::NOT_LIKE * @phan-param '\x3E'|'\x3C'|'!='|'='|'\x3E='|'\x3C='|'LIKE'|'NOT LIKE' $op * @param-taint $op exec_sql * @param ?scalar|RawSQLValue|Blob|LikeValue|non-empty-list<scalar|Blob> $value * @param-taint $value escapes_sql * @phan-side-effect-free */ public function or( string $field, string $op, $value ): OrExpressionGroup { $exprGroup = new OrExpressionGroup( $this ); return $exprGroup->or( $field, $op, $value ); } /** * @param IExpression $expr * @return AndExpressionGroup * @phan-side-effect-free */ public function andExpr( IExpression $expr ): AndExpressionGroup { $exprGroup = new AndExpressionGroup( $this ); return $exprGroup->andExpr( $expr ); } /** * @param IExpression $expr * @return OrExpressionGroup * @phan-side-effect-free */ public function orExpr( IExpression $expr ): OrExpressionGroup { $exprGroup = new OrExpressionGroup( $this ); return $exprGroup->orExpr( $expr ); } /** * @internal to be used by rdbms library only * @return-taint none */ public function toSql( DbQuoter $dbQuoter ): string { if ( is_array( $this->value ) ) { if ( count( $this->value ) === 1 ) { $value = $this->value[0]; if ( $this->op === '=' ) { return $this->field . ' = ' . $dbQuoter->addQuotes( $value ); } elseif ( $this->op === '!=' ) { return $this->field . ' != ' . $dbQuoter->addQuotes( $value ); } else { throw new LogicException( "Operator $this->op can't take array as value" ); } } $list = implode( ',', array_map( static fn ( $value ) => $dbQuoter->addQuotes( $value ), $this->value ) ); if ( $this->op === '=' ) { return $this->field . " IN ($list)"; } elseif ( $this->op === '!=' ) { return $this->field . " NOT IN ($list)"; } else { throw new LogicException( "Operator $this->op can't take array as value" ); } } if ( $this->value === null ) { if ( $this->op === '=' ) { return $this->field . " IS NULL"; } elseif ( $this->op === '!=' ) { return $this->field . " IS NOT NULL"; } else { throw new LogicException( "Operator $this->op can't take null as value" ); } } if ( $this->value instanceof LikeValue ) { // implies that `op` is LIKE or NOT_LIKE, checked in constructor return $this->field . ' ' . $this->op . ' ' . $this->value->toSql( $dbQuoter ); } return $this->field . ' ' . $this->op . ' ' . $dbQuoter->addQuotes( $this->value ); } /** * @internal to be used by rdbms library only */ public function toGeneralizedSql(): string { return $this->field . ' ' . $this->op . ' ?'; } } PK ! K�=" rdbms/expression/LikeValue.phpnu �Iw�� <?php namespace Wikimedia\Rdbms; use InvalidArgumentException; use Wikimedia\Rdbms\Database\DbQuoter; /** * Content of like value * * @newable * @since 1.42 */ class LikeValue { /** @var (string|LikeMatch)[] */ private array $values = []; /** * @param string|LikeMatch $value * @param string|LikeMatch ...$values */ public function __construct( $value, ...$values ) { if ( !is_string( $value ) && !( $value instanceof LikeMatch ) ) { $type = get_debug_type( $value ); throw new InvalidArgumentException( "\$value must be string or LikeMatch, got $type" ); } $this->values = [ $value ]; foreach ( $values as $value ) { if ( !is_string( $value ) && !( $value instanceof LikeMatch ) ) { $type = get_debug_type( $value ); throw new InvalidArgumentException( "\$value must be string or LikeMatch, got $type" ); } $this->values[] = $value; } } /** * @internal to be used by rdbms library only * @return-taint none */ public function toSql( DbQuoter $dbQuoter ): string { $s = ''; // We use ` instead of \ as the default LIKE escape character, since addQuotes() // may escape backslashes, creating problems of double escaping. The ` // character has good cross-DBMS compatibility, avoiding special operators // in MS SQL like ^ and % $escapeChar = '`'; foreach ( $this->values as $value ) { if ( $value instanceof LikeMatch ) { $s .= $value->toString(); } else { $s .= $this->escapeLikeInternal( $value, $escapeChar ); } } return $dbQuoter->addQuotes( $s ) . ' ESCAPE ' . $dbQuoter->addQuotes( $escapeChar ); } private function escapeLikeInternal( $s, $escapeChar = '`' ) { return str_replace( [ $escapeChar, '%', '_' ], [ "{$escapeChar}{$escapeChar}", "{$escapeChar}%", "{$escapeChar}_" ], $s ); } } PK ! �� � & rdbms/expression/OrExpressionGroup.phpnu �Iw�� <?php namespace Wikimedia\Rdbms; /** * Representing a group of expressions chained via OR * * @since 1.42 */ class OrExpressionGroup extends ExpressionGroup { protected function getType(): string { return 'OR'; } // While these methods are not actually "side-effect-free" (they mutate the object), // we annotate them with @phan-side-effect-free for consistency with Expression. /** * @param string $field * @param-taint $field exec_sql * @param string $op One of '>', '<', '!=', '=', '>=', '<=', IExpression::LIKE, IExpression::NOT_LIKE * @phan-param '\x3E'|'\x3C'|'!='|'='|'\x3E='|'\x3C='|'LIKE'|'NOT LIKE' $op * @param-taint $op exec_sql * @param ?scalar|RawSQLValue|Blob|LikeValue|non-empty-list<scalar|Blob> $value * @param-taint $value escapes_sql * @phan-side-effect-free */ public function or( string $field, string $op, $value ): OrExpressionGroup { $expr = new Expression( $field, $op, $value ); $this->add( $expr ); return $this; } /** * @param IExpression $expr * @return OrExpressionGroup * @phan-side-effect-free */ public function orExpr( IExpression $expr ): OrExpressionGroup { $this->add( $expr ); return $this; } } PK ! ]9� � rdbms/ReadOnlyMode.phpnu �Iw�� <?php namespace Wikimedia\Rdbms; /** * Determine whether a site is currently in read-only mode. * * To obtain an instance, use \MediaWiki\MediaWikiServices::getReadOnlyMode(). * * @since 1.29 */ class ReadOnlyMode { /** @var ConfiguredReadOnlyMode */ private $configuredReadOnly; /** @var ILBFactory */ private $lbFactory; /** * @internal For ServiceWiring only * @param ConfiguredReadOnlyMode $cro * @param ILBFactory $lbFactory */ public function __construct( ConfiguredReadOnlyMode $cro, ILBFactory $lbFactory ) { $this->configuredReadOnly = $cro; $this->lbFactory = $lbFactory; } /** * Check whether the site is in read-only mode. * * @param string|false $domain Domain ID, or false for the current domain * @return bool */ public function isReadOnly( $domain = false ): bool { return $this->getReason( $domain ) !== false; } /** * Check if the site is in read-only mode and return the message if so * * This checks both statically configured read-only mode, and (cached) * whether the primary database host accepting writes. * * Calling this may result in database connection. * * This method accepts virtual domains * ({@see \MediaWiki\MainConfigSchema::VirtualDomainsMapping}). * * @param string|false $domain Domain ID, or false for the current domain * @return string|false String when in read-only mode; false otherwise */ public function getReason( $domain = false ) { $reason = $this->configuredReadOnly->getReason(); if ( $reason !== false ) { return $reason; } $reason = $this->lbFactory->getLoadBalancer( $domain )->getReadOnlyReason(); return $reason ?? false; } /** * @since 1.41 * @return string|false String when site is configured to be in read-only mode; false otherwise */ public function getConfiguredReason() { return $this->configuredReadOnly->getReason(); } /** * Check whether the site is configured to be in read-only mode. * * @since 1.41 * @return bool */ public function isConfiguredReadOnly() { return $this->configuredReadOnly->getReason() !== false; } /** * Override the read-only mode, which will apply for the remainder of the * request or until a service reset. * * @param string|false|null $msg */ public function setReason( $msg ): void { $this->configuredReadOnly->setReason( $msg ); } } /** @deprecated class alias since 1.41 */ class_alias( ReadOnlyMode::class, 'ReadOnlyMode' ); PK ! �5��T T rdbms/defines.phpnu �Iw�� <?php use Wikimedia\Rdbms\IDatabase; use Wikimedia\Rdbms\ILoadBalancer; /** @{ * Database related constants */ define( 'DBO_DEBUG', IDatabase::DBO_DEBUG ); define( 'DBO_NOBUFFER', IDatabase::DBO_NOBUFFER ); define( 'DBO_IGNORE', IDatabase::DBO_IGNORE ); define( 'DBO_TRX', IDatabase::DBO_TRX ); define( 'DBO_DEFAULT', IDatabase::DBO_DEFAULT ); define( 'DBO_PERSISTENT', IDatabase::DBO_PERSISTENT ); define( 'DBO_SYSDBA', IDatabase::DBO_SYSDBA ); define( 'DBO_DDLMODE', IDatabase::DBO_DDLMODE ); /** @deprecated since 1.39, use the "ssl" parameter */ define( 'DBO_SSL', IDatabase::DBO_SSL ); define( 'DBO_COMPRESS', IDatabase::DBO_COMPRESS ); /** @} */ /** @{ * Valid database indexes * Operation-based indexes */ define( 'DB_REPLICA', ILoadBalancer::DB_REPLICA ); /** @since 1.36 */ define( 'DB_PRIMARY', ILoadBalancer::DB_PRIMARY ); /** @} */ PK ! M+� 2 2 rdbms/ServerInfo.phpnu �Iw�� <?php namespace Wikimedia\Rdbms; use InvalidArgumentException; use UnexpectedValueException; /** * Container for accessing information about the database servers in a database cluster * * @internal * @ingroup Database */ class ServerInfo { /** * Default 'maxLag' when unspecified * @internal Only for use within LoadBalancer/LoadMonitor */ public const MAX_LAG_DEFAULT = 6; public const WRITER_INDEX = 0; /** @var array[] Map of (server index => server config array) */ private $servers; public function addServer( $i, $server ) { $this->servers[$i] = $server; } public function getServerMaxLag( $i ) { return $this->servers[$i]['max lag'] ?? self::MAX_LAG_DEFAULT; } public function getServerDriver( $i ) { return $this->servers[$i]['driver'] ?? null; } public function getServerType( $i ) { return $this->servers[$i]['type'] ?? 'unknown'; } public function getServerName( $i ): string { return $this->servers[$i]['serverName'] ?? 'localhost'; } public function getServerInfo( $i ) { return $this->servers[$i] ?? false; } public function getServerCount() { return count( $this->servers ); } public function hasServerIndex( $i ) { return isset( $this->servers[$i] ); } public function getLagTimes() { $knownLagTimes = []; // map of (server index => 0 seconds) $indexesWithLag = []; foreach ( $this->servers as $i => $server ) { if ( empty( $server['is static'] ) ) { $indexesWithLag[] = $i; // DB server might have replication lag } else { $knownLagTimes[$i] = 0; // DB server is a non-replicating and read-only archive } } return [ $indexesWithLag, $knownLagTimes ]; } /** * @param int $i Server index * @param string|null $field Server index field [optional] * @return mixed * @throws InvalidArgumentException */ public function getServerInfoStrict( $i, $field = null ) { if ( !isset( $this->servers[$i] ) || !is_array( $this->servers[$i] ) ) { throw new InvalidArgumentException( "No server with index '$i'" ); } if ( $field !== null ) { if ( !array_key_exists( $field, $this->servers[$i] ) ) { throw new InvalidArgumentException( "No field '$field' in server index '$i'" ); } return $this->servers[$i][$field]; } return $this->servers[$i]; } /** * @return int[] List of replica server indexes */ public function getStreamingReplicaIndexes() { $indexes = []; foreach ( $this->servers as $i => $server ) { if ( $i !== self::WRITER_INDEX && empty( $server['is static'] ) ) { $indexes[] = $i; } } return $indexes; } public function hasStreamingReplicaServers() { return (bool)$this->getStreamingReplicaIndexes(); } public function reconfigureServers( $paramServers ) { $newIndexBySrvName = []; $this->normalizeServerMaps( $paramServers, $newIndexBySrvName ); // Map of (existing server index => corresponding index in new config or null) $newIndexByServerIndex = []; // Remove servers that no longer exist in the new config and preserve those that // still exist, even if they switched replication roles (e.g. primary/secondary). // Note that if the primary server is depooled and a replica server is promoted // to primary, then DB_PRIMARY handles will fail with server index errors. Note // that if the primary server swaps roles with a replica server, then write queries // to DB_PRIMARY handles will fail with read-only errors. foreach ( $this->servers as $i => $server ) { $srvName = $this->getServerName( $i ); // Since pooling or depooling of servers causes the remaining servers to be // assigned different indexes, find the corresponding index by server name. // Also, note that the primary can be reconfigured as a replica (moved from // the writer index) and vice versa (moved to the writer index). $newIndex = $newIndexByServerIndex[$i] = $newIndexBySrvName[$srvName] ?? null; if ( $newIndex === null ) { unset( $this->servers[$i] ); } } return $newIndexByServerIndex; } public function normalizeServerMaps( array $servers, ?array &$indexBySrvName = null ) { if ( !$servers ) { throw new InvalidArgumentException( 'Missing or empty "servers" parameter' ); } $listKey = -1; $indexBySrvName = []; foreach ( $servers as $i => $server ) { if ( ++$listKey !== $i ) { throw new UnexpectedValueException( 'List expected for "servers" parameter' ); } $srvName = $server['serverName'] ?? $server['host'] ?? ''; $srvName = ( $srvName !== '' ) ? $srvName : 'localhost'; if ( isset( $indexBySrvName[$srvName] ) ) { // Duplicate server names confuse caching, logging, and reconfigure() throw new UnexpectedValueException( 'Duplicate server name "' . $srvName . '"' ); } $indexBySrvName[$srvName] = $i; $servers[$i]['serverName'] = $srvName; $servers[$i]['groupLoads'] ??= []; } return $servers; } /** * @return string Name of the primary DB server of the relevant DB cluster (e.g. "db1052") */ public function getPrimaryServerName() { return $this->getServerName( self::WRITER_INDEX ); } public function hasReplicaServers() { return ( $this->getServerCount() > 1 ); } } PK ! F�2� � ' rdbms/exception/DBSessionStateError.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\Rdbms; /** * @newable * @ingroup Database */ class DBSessionStateError extends DBTransactionError { } PK ! *k�� # rdbms/exception/DBLanguageError.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\Rdbms; use Throwable; /** * @since 1.39 * @newable * @ingroup Database */ class DBLanguageError extends DBUnexpectedError { public function __construct( $error, ?Throwable $prev = null ) { parent::__construct( null, $error, $prev ); } } PK ! L;��� � , rdbms/exception/DBQueryDisconnectedError.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\Rdbms; /** * @newable * @ingroup Database * @since 1.34 */ class DBQueryDisconnectedError extends DBQueryError { /** * @stable to call * @param IDatabase $db * @param string $error * @param int|string $errno * @param string $sql * @param string $fname * @param string|null $message Optional message, intended for subclasses (optional) */ public function __construct( IDatabase $db, $error, $errno, $sql, $fname, $message = null ) { $message ??= "A connection error occurred during a query. \n" . "Query: $sql\n" . "Function: $fname\n" . "Error: $errno $error\n"; parent::__construct( $db, $error, $errno, $sql, $fname, $message ); } } PK ! '�ȁ� � + rdbms/exception/DBTransactionStateError.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\Rdbms; /** * @newable * @ingroup Database */ class DBTransactionStateError extends DBTransactionError { } PK ! ��ĉv v & rdbms/exception/DBTransactionError.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\Rdbms; use Wikimedia\NormalizedException\INormalizedException; use Wikimedia\NormalizedException\NormalizedExceptionTrait; /** * @newable * @ingroup Database */ class DBTransactionError extends DBExpectedError implements INormalizedException { use NormalizedExceptionTrait; /** * @stable to call * @param IDatabase|null $db * @param string $error * @param array $params parameters to be passed down to the i18n message * @param \Throwable|null $prev * @param array $errorParams PSR-3 message context */ public function __construct( ?IDatabase $db, $error, array $params = [], ?\Throwable $prev = null, $errorParams = [] ) { $this->normalizedMessage = $error; $this->messageContext = $errorParams; parent::__construct( $db, self::getMessageFromNormalizedMessage( $error, $params ), $params, $prev ); } } PK ! ���� � * rdbms/exception/DBTransactionSizeError.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\Rdbms; /** * @newable * @ingroup Database */ class DBTransactionSizeError extends DBTransactionError { public function getKey() { return 'transaction-duration-limit-exceeded'; } } PK ! �ZI� � rdbms/exception/DBError.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\Rdbms; use RuntimeException; /** * Database error base class. * * Catching and silencing this class or its subclasses is strongly discouraged. * Most code should not catch DB errors at all, * but let them bubble to the MediaWiki exception handler. * If necessary, cleanup can be done in a finally block; * catching the exception and then rethrowing it is also acceptable. * * @newable * @ingroup Database */ class DBError extends RuntimeException { /** @var IDatabase|null */ public $db; /** * Construct a database error * @stable to call * @param IDatabase|null $db Object which threw the error * @param string $error A simple error message to be used for debugging * @param \Throwable|null $prev Previous throwable */ public function __construct( ?IDatabase $db, $error, ?\Throwable $prev = null ) { parent::__construct( $error, 0, $prev ); $this->db = $db; } } PK ! 'Qq� � ' rdbms/exception/DBReadOnlyRoleError.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\Rdbms; /** * Exception class for attempted DB write access to a DBConnRef with the DB_REPLICA role * * @newable * @ingroup Database */ class DBReadOnlyRoleError extends DBUnexpectedError { } PK ! ߘ��� � # rdbms/exception/DBReadOnlyError.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\Rdbms; /** * @newable * @ingroup Database */ class DBReadOnlyError extends DBExpectedError { } PK ! �9 �� � % rdbms/exception/DBConnectionError.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\Rdbms; /** * @newable * @ingroup Database */ class DBConnectionError extends DBExpectedError { /** * @stable to call * @param IDatabase|null $db Object throwing the error * @param string $error Error text */ public function __construct( ?IDatabase $db = null, $error = 'unknown error' ) { $msg = 'Cannot access the database'; if ( trim( $error ) != '' ) { $msg .= ": $error"; } parent::__construct( $db, $msg ); } } PK ! ;��; ; ! rdbms/exception/DBAccessError.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\Rdbms; /** * Exception class for attempted DB access * * @newable * @ingroup Database */ class DBAccessError extends DBUnexpectedError { /** * @stable to call */ public function __construct() { parent::__construct( null, "Database access has been disabled." ); } } PK ! �鮟E E rdbms/exception/DBQueryError.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\Rdbms; /** * @ingroup Database * @newable */ class DBQueryError extends DBExpectedError { /** @var string */ public $error; /** @var int */ public $errno; /** @var string */ public $sql; /** @var string */ public $fname; /** * @stable to call * @param IDatabase $db * @param string $error * @param int|string $errno * @param string $sql * @param string $fname * @param string|null $message Optional message, intended for subclasses (optional) */ public function __construct( IDatabase $db, $error, $errno, $sql, $fname, $message = null ) { $message ??= "Error $errno: $error\n" . "Function: $fname\n" . "Query: $sql\n"; parent::__construct( $db, $message ); $this->error = $error; $this->errno = $errno; $this->sql = $sql; $this->fname = $fname; } } PK ! &pi i # rdbms/exception/DBExpectedError.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\Rdbms; use Wikimedia\Message\MessageSpecifier; /** * Base class for the more common types of database errors. These are known to occur * frequently, so we try to give friendly error messages for them. * * @newable * @ingroup Database * @since 1.23 */ class DBExpectedError extends DBError implements MessageSpecifier { /** @var string[] Message parameters */ protected $params; /** * @stable to call * @param IDatabase|null $db * @param string $error * @param array $params * @param \Throwable|null $prev */ public function __construct( ?IDatabase $db, $error, array $params = [], ?\Throwable $prev = null ) { parent::__construct( $db, $error, $prev ); $this->params = $params; } public function getKey() { return 'databaseerror-text'; } public function getParams() { return $this->params; } } PK ! wJr� � % rdbms/exception/DBUnexpectedError.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\Rdbms; /** * @newable * @ingroup Database */ class DBUnexpectedError extends DBError { } PK ! dX�D� � * rdbms/exception/DBReplicationWaitError.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\Rdbms; /** * Exception class for replica DB wait errors * @newable * @ingroup Database */ class DBReplicationWaitError extends DBExpectedError { } PK ! �| � � ' rdbms/exception/DBQueryTimeoutError.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\Rdbms; /** * Error thrown when a query times out * * @newable * @ingroup Database */ class DBQueryTimeoutError extends DBQueryError { /** * @stable to call * * @param IDatabase $db * @param string $error * @param int|string $errno * @param string $sql * @param string $fname */ public function __construct( IDatabase $db, $error, $errno, $sql, $fname ) { $message = "A database query timeout has occurred. \n" . "Query: $sql\n" . "Function: $fname\n" . "Error: $errno $error\n"; parent::__construct( $db, $error, $errno, $sql, $fname, $message ); } public function getKey() { return 'transaction-max-statement-time-exceeded'; } } PK ! ��Z�c �c rdbms/platform/ISQLPlatform.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\Rdbms\Platform; use Wikimedia\Rdbms\DBError; use Wikimedia\Rdbms\IExpression; use Wikimedia\Rdbms\LikeMatch; use Wikimedia\Rdbms\RawSQLValue; use Wikimedia\Rdbms\Subquery; // Very long type annotations :( // phpcs:disable Generic.Files.LineLength /** * Interface for query language. * Note: This is for simple SQL operations, use query builder classes for building full queries. * * Methods of this interface should be only used by rdbms library. * @since 1.39 */ interface ISQLPlatform { /** Combine list with comma delimiters */ public const LIST_COMMA = 0; /** Combine list with AND clauses */ public const LIST_AND = 1; /** Convert map into a SET clause */ public const LIST_SET = 2; /** Treat as field name and do not apply value escaping */ public const LIST_NAMES = 3; /** Combine list with OR clauses */ public const LIST_OR = 4; /** Unconditional update/delete of whole table */ public const ALL_ROWS = '*'; /** Idiom for "no special flags" */ public const QUERY_NORMAL = 0; /** Ignore query errors and return false when they happen */ public const QUERY_SILENCE_ERRORS = 1; // b/c for 1.32 query() argument; (int)true = 1 /** Track a TEMPORARY table CREATE as if it was for a permanent table (for testing) */ public const QUERY_PSEUDO_PERMANENT = 2; /** Enforce that a query does not make effective writes */ public const QUERY_REPLICA_ROLE = 4; /** Ignore the current presence of any DBO_TRX flag */ public const QUERY_IGNORE_DBO_TRX = 8; /** Do not try to retry the query if the connection was lost */ public const QUERY_NO_RETRY = 16; /** Query is a read-only Data Query Language query */ public const QUERY_CHANGE_NONE = 32; /** Query is a Transaction Control Language command (BEGIN, USE, SET, ...) */ public const QUERY_CHANGE_TRX = 64; /** Query is a Data Manipulation Language command (INSERT, DELETE, LOCK, ...) */ public const QUERY_CHANGE_ROWS = 128; /** Query is a Data Definition Language command */ public const QUERY_CHANGE_SCHEMA = 256; /** Query is a command for advisory locks */ public const QUERY_CHANGE_LOCKS = 512; /** * Special value for ->caller() / $fname parameter used when providing a caller is not * expected, because we're formatting a subquery that won't be executed directly. * @since 1.43 */ public const CALLER_SUBQUERY = 'subquery'; /** * Special value for ->caller() / $fname parameter used when a caller is not provided. * @since 1.43 */ public const CALLER_UNKNOWN = 'unknown'; /** * @param string|int $field * @return string */ public function bitNot( $field ); /** * @param string|int $fieldLeft * @param string|int $fieldRight * @return string */ public function bitAnd( $fieldLeft, $fieldRight ); /** * @param string|int $fieldLeft * @param string|int $fieldRight * @return string */ public function bitOr( $fieldLeft, $fieldRight ); /** * Escape a SQL identifier (e.g. table, column, database) for use in a SQL query * * Depending on the database this will either be `backticks` or "double quotes" * * @param string $s * @param-taint $s escapes_sql NOTE: this is subpar, as addIdentifierQuotes isn't always the right type of escaping. * @return string * @return-taint none * @since 1.33 */ public function addIdentifierQuotes( $s ); /** * Build a GREATEST function statement comparing columns/values * * Integer and float values in $values will not be quoted * * If $fields is an array, then each value with a string key is treated as an expression * (which must be manually quoted); such string keys do not appear in the SQL and are only * descriptive aliases. * * @param string|string[] $fields Name(s) of column(s) with values to compare * @param string|int|float|string[]|int[]|float[] $values Values to compare * @return mixed * @since 1.35 in IDatabase, moved to ISQLPlatform in 1.39 */ public function buildGreatest( $fields, $values ); /** * Build a LEAST function statement comparing columns/values * * Integer and float values in $values will not be quoted * * If $fields is an array, then each value with a string key is treated as an expression * (which must be manually quoted); such string keys do not appear in the SQL and are only * descriptive aliases. * * @param string|string[] $fields Name(s) of column(s) with values to compare * @param string|int|float|string[]|int[]|float[] $values Values to compare * @return mixed * @since 1.35 in IDatabase, moved to ISQLPlatform in 1.39 */ public function buildLeast( $fields, $values ); /** * Build a condition comparing multiple values, for use with indexes that cover * multiple fields, common when e.g. paging through results or doing batch operations. * * For example, you might be displaying a list of people ordered alphabetically by their last * and first name, split across multiple pages. The first page of the results ended at Jane Doe. * When building the query for the next page, you would use: * * $queryBuilder->where( $db->buildComparison( '>', [ 'last' => 'Doe', 'first' => 'Jane' ] ) ); * * This will return people whose last name follows Doe, or whose last name is Doe and first name * follows Jane. * * Note that the order of keys in the associative array $conds is significant, * and must match the order of fields used by the index. * * When comparing a single value, prefer using the expression builder: * * $db->expr( 'key', '<=', $val ) * * // equivalent to: * $db->buildComparison( '<=', [ 'key' => $val ] ) * 'key <= ' . $db->addQuotes( $val ) * * @param string $op Comparison operator, one of '>', '>=', '<', '<=' * @param non-empty-array<string,mixed> $conds Map of field names to their values to use in the comparison * @return string SQL code */ public function buildComparison( string $op, array $conds ): string; /** * Makes an encoded list of strings from an array * * These can be used to make conjunctions or disjunctions on SQL condition strings * derived from an array ({@see IDatabase::select} $conds documentation). * * Example usage: * @code * $sql = $db->makeList( [ * 'rev_page' => $id, * $db->makeList( [ 'rev_minor' => 1, 'rev_len < 500' ], $db::LIST_OR ) * ], $db::LIST_AND ); * @endcode * This would set $sql to "rev_page = '$id' AND (rev_minor = 1 OR rev_len < 500)" * * @param array $a Containing the data * @param-taint $a escapes_sql - Note, this is also special-cased in MediaWikiSecurityCheckPlugin * @param int $mode IDatabase class constant: * - IDatabase::LIST_COMMA: Comma separated, no field names * - IDatabase::LIST_AND: ANDed WHERE clause (without the WHERE). * - IDatabase::LIST_OR: ORed WHERE clause (without the WHERE) * - IDatabase::LIST_SET: Comma separated with field names, like a SET clause * - IDatabase::LIST_NAMES: Comma separated field names * @param-taint $mode none * @throws DBError If an error occurs, {@see IDatabase::query} * @return string * @return-taint none */ public function makeList( array $a, $mode = self::LIST_COMMA ); /** * Build a "OR" condition with pairs from a two-dimensional array. * * The associative array should have integer keys relating to the $baseKey field. * The nested array should have string keys for the $subKey field. The inner * values are ignored, and are typically boolean true. * * Example usage: * ``` * $data = [ * 2 => [ * 'Foo' => true, * 'Bar' => true, * ], * 3 => [ * 'Quux' => true, * ], * ]; * // (page_namespace = 2 AND page_title IN ('Foo','Bar')) * // OR (page_namespace = 3 AND page_title = 'Quux') * ``` * @todo This is effectively specific to MediaWiki's LinkBatch. * Consider deprecating or generalising slightly. * * @param array $data Nested array, must be non-empty * @phan-param non-empty-array $data * @param string $baseKey Field name to match the base-level keys to (eg 'pl_namespace') * @param string $subKey Field name to match the sub-level keys to (eg 'pl_title') * @return string SQL fragment */ public function makeWhereFrom2d( $data, $baseKey, $subKey ); /** * Given an array of condition arrays representing an OR list of AND lists, * for example: * * (A=1 AND B=2) OR (A=1 AND B=3) * * produce an SQL expression in which the conditions are factored: * * (A=1 AND (B=2 OR B=3)) * * We also use IN() to simplify further: * * (A=1 AND (B IN (2,3)) * * More compactly, in boolean algebra notation, a sum of products, e.g. * AB + AC is factored to produce A(B+C). Factoring proceeds recursively * to reduce expressions with any number of variables, for example * AEP + AEQ + AFP + AFQ = A(E(P+Q) + F(P+Q)) * * The algorithm is simple and will not necessarily find the shortest * possible expression. For the best results, fields should be given in a * consistent order, and the fields with values likely to be shared should * be leftmost in the associative arrays. * * @param array $condsArray An array of associative arrays. The associative * array keys represent field names, and the values represent the field * values to compare against. * @return string SQL expression fragment */ public function factorConds( $condsArray ); /** * Build a concatenation list to feed into a SQL query * @param string[] $stringList Raw SQL expression list; caller is responsible for escaping * @return string */ public function buildConcat( $stringList ); /** * Construct a LIMIT query with optional offset * * The SQL should be adjusted so that only the first $limit rows * are returned. If $offset is provided as well, then the first $offset * rows should be discarded, and the next $limit rows should be returned. * If the result of the query is not ordered, then the rows to be returned * are theoretically arbitrary. * * $sql is expected to be a SELECT, if that makes a difference. * * @param string $sql SQL query we will append the limit too * @param int $limit The SQL limit * @param int|false $offset The SQL offset (default false) * @return string * @since 1.34 in IDatabase, moved to ISQLPlatform in 1.39 */ public function limitResult( $sql, $limit, $offset = false ); /** * LIKE statement wrapper * * This takes a variable-length argument list with parts of pattern to match * containing either string literals that will be escaped or tokens returned by * {@link anyChar()} or {@link anyString()}. * Alternatively, the function could be provided with an array of the aforementioned parameters. * * Example: $dbr->buildLike( 'My_page_title/', $dbr->anyString() ) returns * a LIKE clause that searches for subpages of 'My page title'. * Alternatively: * $pattern = [ 'My_page_title/', $dbr->anyString() ]; * $query .= $dbr->buildLike( $pattern ); * * @since 1.16 in IDatabase, moved to ISQLPlatform in 1.39 * @param array[]|string|LikeMatch $param * @param-taint $param escapes_sql * @param string|LikeMatch ...$params * @param-taint ...$params escapes_sql * @return string Fully built LIKE statement * @return-taint none */ public function buildLike( $param, ...$params ); /** * Returns a token for {@link buildLike()} that denotes a '_' to be used in a LIKE query * * @return LikeMatch */ public function anyChar(); /** * Returns a token for {@link buildLike()} that denotes a '%' to be used in a LIKE query * * @return LikeMatch */ public function anyString(); /** * Determine if the RDBMS supports ORDER BY and LIMIT for separate subqueries within UNION * * @return bool */ public function unionSupportsOrderAndLimit(); /** * Construct a UNION query * * This is used for providing overload point for other DB abstractions * not compatible with the MySQL syntax. * * @internal callers outside of rdbms library should use UnionQueryBuilder instead. * * @param array $sqls SQL statements to combine * @param bool $all Either {@link IDatabase::UNION_ALL} or {@link IDatabase::UNION_DISTINCT} * @param array $options Query options * * @return string SQL fragment */ public function unionQueries( $sqls, $all, $options = [] ); /** * Convert a timestamp in one of the formats accepted by {@link ConvertibleTimestamp} * to the format used for inserting into timestamp fields in this DBMS * * The result is unquoted, and needs to be passed through addQuotes() * before it can be included in raw SQL. * * @param string|int $ts * * @return string */ public function timestamp( $ts = 0 ); /** * Convert a timestamp in one of the formats accepted by ConvertibleTimestamp * to the format used for inserting into timestamp fields in this DBMS * * If NULL is input, it is passed through, allowing NULL values to be inserted * into timestamp fields. * * The result is unquoted, and needs to be passed through addQuotes() * before it can be included in raw SQL. * * @param string|int|null $ts * * @return string|null */ public function timestampOrNull( $ts = null ); /** * Find out when 'infinity' is. Most DBMSes support this. This is a special * keyword for timestamps in PostgreSQL, and works with CHAR(14) as well * because "i" sorts after all numbers. * * @return string */ public function getInfinity(); /** * Encode an expiry time into the DBMS dependent format * * @param string $expiry Timestamp for expiry, or the 'infinity' string * @return string */ public function encodeExpiry( $expiry ); /** * Decode an expiry time into a DBMS independent format * * @param string $expiry DB timestamp field value for expiry * @param int $format TS_* constant, defaults to TS_MW * @return string */ public function decodeExpiry( $expiry, $format = TS_MW ); /** * Returns an SQL expression for a simple conditional * * This doesn't need to be overridden unless CASE isn't supported in the RDBMS. * * @param string|IExpression|array<string,?scalar|non-empty-array<int,?scalar>>|array<int,string|IExpression> $cond * SQL condition expression (yields a boolean) * @param string $caseTrueExpression SQL expression to return when the condition is true * @param string $caseFalseExpression SQL expression to return when the condition is false * @return string SQL fragment */ public function conditional( $cond, $caseTrueExpression, $caseFalseExpression ); /** * Returns a SQL expression for simple string replacement (e.g. REPLACE() in mysql) * * @param string $orig Column to modify * @param string $old Column to seek * @param string $new Column to replace with * @return string */ public function strreplace( $orig, $old, $new ); /** * Build a SUBSTRING function * * Behavior for non-ASCII values is undefined. * * @param string $input Field name * @param int $startPosition Positive integer * @param int|null $length Non-negative integer length or null for no limit * @throws \InvalidArgumentException * @return string SQL text * @since 1.31 in IDatabase, moved to ISQLPlatform in 1.39 */ public function buildSubString( $input, $startPosition, $length = null ); /** * @param string $field Field or column to cast * @return string * @since 1.28 in IDatabase, moved to ISQLPlatform in 1.39 */ public function buildStringCast( $field ); /** * @param string $field Field or column to cast * @return string * @since 1.31 in IDatabase, moved to ISQLPlatform in 1.39 */ public function buildIntegerCast( $field ); /** * Returns true if this database does an implicit order by when the column has an index * For example: SELECT page_title FROM page LIMIT 1 * * @return bool */ public function implicitOrderby(); /** * Make certain table names use their own database, schema, and table prefix * when passed into SQL queries pre-escaped and without a qualified database name * * For example, "user" can be converted to "myschema.mydbname.user" for convenience. * Appearances like `user`, somedb.user, somedb.someschema.user will used literally. * * Calling this twice will completely clear any old table aliases. Also, note that * callers are responsible for making sure the schemas and databases actually exist. * * @param array[] $aliases Map of (unqualified name of table => (dbname, schema, prefix) map) * @since 1.28 in IDatabase, moved to ISQLPlatform in 1.39 */ public function setTableAliases( array $aliases ); /** * Convert certain index names to alternative names before querying the DB * * Note that this applies to indexes regardless of the table they belong to. * * This can be employed when an index was renamed X => Y in code, but the new Y-named * indexes were not yet built on all DBs. After all the Y-named ones are added by the DBA, * the aliases can be removed, and then the old X-named indexes dropped. * * @param string[] $aliases * @since 1.31 in IDatabase, moved to ISQLPlatform in 1.39 */ public function setIndexAliases( array $aliases ); /** * Return current table aliases. * * @internal only to be used inside rdbms library */ public function getTableAliases(); /** * Take the same arguments as IDatabase::select() and return the SQL it would use * * This can be useful for making UNION queries, where the SQL text of each query * is needed. In general, however, callers outside of Database classes should just * use select(). * * @see IDatabase::select() * * @param string|array $tables Table reference(s), using the unqualified name of tables * or of the form "information_schema.<identifier>". * @param-taint $tables exec_sql * @param string|array $vars Field names * @param-taint $vars exec_sql * @param string|IExpression|array<string,?scalar|non-empty-array<int,?scalar>|RawSQLValue>|array<int,string|IExpression> $conds * Conditions * @param-taint $conds exec_sql_numkey * @param string $fname Caller function name @phan-mandatory-param * @param-taint $fname exec_sql * @param string|array $options Query options * @param-taint $options none This is special-cased in MediaWikiSecurityCheckPlugin * @param string|array $join_conds Join conditions * @param-taint $join_conds none This is special-cased in MediaWikiSecurityCheckPlugin * @return string SQL query string * @return-taint onlysafefor_sql */ public function selectSQLText( $tables, $vars, $conds = '', $fname = __METHOD__, $options = [], $join_conds = [] ); /** * Format a table name ready for use in constructing an SQL query * * This does two important things: it quotes the table names to clean them up, * and it adds a table prefix if only given a table name with no quotes. * * All functions of this object which require a table name call this function * themselves. Pass the canonical name to such functions. This is only needed * when calling {@link query()} directly. * * The provided name should not qualify the database nor the schema, unless the name * is of the form "information_schema.<identifier>". Unlike information_schema tables, * regular tables can receive writes and are subject to configuration regarding table * aliases, virtual domains, and LBFactory sharding. Callers needing to access remote * databases should use appropriate connection factory methods. * * @note This function does not sanitize user input. It is not safe to use * this function to escape user input. * @param string $name The unqualified name of a table (no quotes, db, schema, nor table * prefix), or a table name of the form "information_schema.<unquoted identifier>". * @param string $format One of: * quoted - Automatically pass the table name through addIdentifierQuotes() * so that it can be used in a query. * raw - Do not add identifier quotes to the table name. * @return string Qualified table name (includes any applicable prefix or foreign db/schema) */ public function tableName( string $name, $format = 'quoted' ); /** * Fetch a number of table names into an associative array * * Much like {@link tableName()}, this is only needed when calling * {@link query()} directly. Prefer calling other methods, * or using {@link SelectQueryBuilder}. * * Theoretical example (which really does not require raw SQL): * ``` * [ 'user' => $user, 'watchlist' => $watchlist ] = * $dbr->tableNames( 'user', 'watchlist' ); * $sql = "SELECT wl_namespace, wl_title FROM $watchlist, $user * WHERE wl_user=user_id AND wl_user=$nameWithQuotes"; * ``` * * @param string ...$tables * @return array * @deprecated since 1.39; if you must format table names, * write several calls to {@link tableName} or use {@link tableNamesN} * instead of calling this function. */ public function tableNames( ...$tables ); /** * Fetch a number of table names into a zero-indexed numerical array * * Much like {@link tableName()}, this is only needed when calling * {@link query()} directly. It is slightly more convenient than * {@link tableNames()}, but you should still prefer calling other * methods, or using {@link SelectQueryBuilder}. * * Theoretical example (which really does not require raw SQL): * ``` * [ $user, $watchlist ] = $dbr->tableNamesN( 'user', 'watchlist' ); * $sql = "SELECT wl_namespace,wl_title FROM $watchlist,$user * WHERE wl_user=user_id AND wl_user=$nameWithQuotes"; * ``` * * @param string ...$tables * @return array * @deprecated Since 1.43; if you must format table names, * write several calls to {@link tableName}. */ public function tableNamesN( ...$tables ); /** * Build a GROUP_CONCAT or equivalent statement for a query. * * This is useful for combining a field for several rows into a single string. * NULL values will not appear in the output, duplicated values will appear, * and the resulting delimiter-separated values have no defined sort order. * Code using the results may need to use the PHP unique() or sort() methods. * * @param string $delim Glue to bind the results together * @param string|array $tables Table reference(s), using the unqualified name of tables * or of the form "information_schema.<identifier>". {@see select} for details. * @param string $field Field name * @param string|IExpression|array<string,?scalar|non-empty-array<int,?scalar>|RawSQLValue>|array<int,string|IExpression> $conds * Conditions * @param string|array $join_conds Join conditions * @return string SQL text * @since 1.23 */ public function buildGroupConcatField( $delim, $tables, $field, $conds = '', $join_conds = [] ); /** * Equivalent to IDatabase::selectSQLText() except wraps the result in Subquery * * @see IDatabase::selectSQLText() * * @param string|array $tables Table reference(s), using the unqualified name of tables * or of the form "information_schema.<identifier>". {@see select} for details. * @param string|array $vars Field names * @param string|array $conds Conditions * @param string $fname Caller function name @phan-mandatory-param * @param string|array $options Query options * @param string|array $join_conds Join conditions * @return Subquery * @since 1.31 */ public function buildSelectSubquery( $tables, $vars, $conds = '', $fname = __METHOD__, $options = [], $join_conds = [] ); /** * Build a reference to a column value from the conflicting proposed upsert() row. * * The reference comes in the form of an alias, function, or parenthesized SQL expression. * It can be used in upsert() SET expressions to handle the merging of column values between * each conflicting pair of existing and proposed rows. Such proposed rows are said to have * been "excluded" from insertion in favor of updating the existing row. * * This is useful for multi-row upserts() since the proposed values cannot just be included * as literals in the SET expressions. * * @see IDatabase::upsert() * * @param string $column Column name * @return string SQL expression returning a scalar * @since 1.39 */ public function buildExcludedValue( $column ); /** * Set schema variables to be used when streaming commands from SQL files or stdin * * Variables appear as SQL comments and are substituted by their corresponding values * * @param array|null $vars Map of (variable => value) or null to use the defaults */ public function setSchemaVars( $vars ); } PK ! �e�[; ; ! rdbms/platform/SqlitePlatform.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\Rdbms\Platform; use Wikimedia\Rdbms\Query; /** * @since 1.38 * @see ISQLPlatform */ class SqlitePlatform extends SQLPlatform { public function buildGreatest( $fields, $values ) { return $this->buildSuperlative( 'MAX', $fields, $values ); } public function buildLeast( $fields, $values ) { return $this->buildSuperlative( 'MIN', $fields, $values ); } /** * Build a concatenation list to feed into a SQL query * * @param string[] $stringList * @return string */ public function buildConcat( $stringList ) { return '(' . implode( ') || (', $stringList ) . ')'; } /** * @param string[] $sqls * @param bool $all Whether to "UNION ALL" or not * @param array $options Query options, will be ignored in Sqlite * @return string */ public function unionQueries( $sqls, $all, $options = [] ) { $glue = $all ? ' UNION ALL ' : ' UNION '; return implode( $glue, $sqls ); } /** * @return bool */ public function unionSupportsOrderAndLimit() { return false; } public function buildSubstring( $input, $startPosition, $length = null ) { $this->assertBuildSubstringParams( $startPosition, $length ); $params = [ $input, $startPosition ]; if ( $length !== null ) { $params[] = $length; } return 'SUBSTR(' . implode( ',', $params ) . ')'; } /** * @param string $field Field or column to cast * @return string * @since 1.28 */ public function buildStringCast( $field ) { return 'CAST ( ' . $field . ' AS TEXT )'; } public function tableName( string $name, $format = 'quoted' ) { if ( preg_match( '/^sqlite_[a-z_]+$/', $name ) ) { // Such names are reserved for internal SQLite tables return $name; } return parent::tableName( $name, $format ); } protected function makeSelectOptions( array $options ) { // Remove problematic options that the base implementation converts to SQL foreach ( $options as $k => $v ) { if ( is_numeric( $k ) && ( $v === 'FOR UPDATE' || $v === 'LOCK IN SHARE MODE' ) ) { $options[$k] = ''; } } return parent::makeSelectOptions( $options ); } public function buildGroupConcatField( $delim, $tables, $field, $conds = '', $join_conds = [] ) { $fld = "group_concat($field," . $this->quoter->addQuotes( $delim ) . ')'; return '(' . $this->selectSQLText( $tables, $fld, $conds, static::CALLER_SUBQUERY, [], $join_conds ) . ')'; } protected function makeInsertNonConflictingVerbAndOptions() { return [ 'INSERT OR IGNORE INTO', '' ]; } /** * @param array $options * @return array */ protected function makeUpdateOptionsArray( $options ) { $options = parent::makeUpdateOptionsArray( $options ); $options = $this->rewriteIgnoreKeyword( $options ); return $options; } /** * @param array $options * @return array */ private function rewriteIgnoreKeyword( $options ) { # SQLite uses OR IGNORE not just IGNORE foreach ( $options as $k => $v ) { if ( $v == 'IGNORE' ) { $options[$k] = 'OR IGNORE'; } } return $options; } public function dropTableSqlText( $table ) { // No CASCADE support; https://www.sqlite.org/lang_droptable.html return "DROP TABLE " . $this->tableName( $table ); } public function isTransactableQuery( Query $sql ) { return parent::isTransactableQuery( $sql ) && !in_array( $sql->getVerb(), [ 'ATTACH', 'PRAGMA' ], true ); } } PK ! �|a� �� rdbms/platform/SQLPlatform.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\Rdbms\Platform; use InvalidArgumentException; use Psr\Log\LoggerInterface; use Psr\Log\NullLogger; use RuntimeException; use Throwable; use Wikimedia\Assert\Assert; use Wikimedia\Rdbms\Database\DbQuoter; use Wikimedia\Rdbms\DatabaseDomain; use Wikimedia\Rdbms\DBLanguageError; use Wikimedia\Rdbms\IExpression; use Wikimedia\Rdbms\LikeMatch; use Wikimedia\Rdbms\LikeValue; use Wikimedia\Rdbms\Query; use Wikimedia\Rdbms\QueryBuilderFromRawSql; use Wikimedia\Rdbms\RawSQLValue; use Wikimedia\Rdbms\Subquery; use Wikimedia\Timestamp\ConvertibleTimestamp; /** * Sql abstraction object. * This class nor any of its subclasses shouldn't create a db connection. * It also should not become stateful. The constructor should only rely on addQuotes() method in Database. * Later that should be replaced with an implementation that doesn't use db connections. * @since 1.39 */ class SQLPlatform implements ISQLPlatform { /** @var array[] Current map of (table => (dbname, schema, prefix) map) */ protected $tableAliases = []; /** @var string[] Current map of (index alias => index) */ protected $indexAliases = []; /** @var DatabaseDomain|null */ protected $currentDomain; /** @var array|null Current variables use for schema element placeholders */ protected $schemaVars; /** @var DbQuoter */ protected $quoter; /** @var LoggerInterface */ protected $logger; /** @var callable Error logging callback */ protected $errorLogger; public function __construct( DbQuoter $quoter, ?LoggerInterface $logger = null, ?DatabaseDomain $currentDomain = null, $errorLogger = null ) { $this->quoter = $quoter; $this->logger = $logger ?? new NullLogger(); $this->currentDomain = $currentDomain ?: DatabaseDomain::newUnspecified(); $this->errorLogger = $errorLogger ?? static function ( Throwable $e ) { trigger_error( get_class( $e ) . ': ' . $e->getMessage(), E_USER_WARNING ); }; } public function bitNot( $field ) { return "(~$field)"; } public function bitAnd( $fieldLeft, $fieldRight ) { return "($fieldLeft & $fieldRight)"; } public function bitOr( $fieldLeft, $fieldRight ) { return "($fieldLeft | $fieldRight)"; } public function addIdentifierQuotes( $s ) { if ( strcspn( $s, "\0\"`'." ) !== strlen( $s ) ) { throw new DBLanguageError( "Identifier must not contain quote, dot or null characters" ); } $quoteChar = $this->getIdentifierQuoteChar(); return $quoteChar . $s . $quoteChar; } /** * Get the character used for identifier quoting * @return string */ protected function getIdentifierQuoteChar() { return '"'; } /** * @inheritDoc */ public function buildGreatest( $fields, $values ) { return $this->buildSuperlative( 'GREATEST', $fields, $values ); } /** * @inheritDoc */ public function buildLeast( $fields, $values ) { return $this->buildSuperlative( 'LEAST', $fields, $values ); } /** * Build a superlative function statement comparing columns/values * * Integer and float values in $values will not be quoted * * If $fields is an array, then each value with a string key is treated as an expression * (which must be manually quoted); such string keys do not appear in the SQL and are only * descriptive aliases. * * @param string $sqlfunc Name of a SQL function * @param string|string[] $fields Name(s) of column(s) with values to compare * @param string|int|float|string[]|int[]|float[] $values Values to compare * @return string */ protected function buildSuperlative( $sqlfunc, $fields, $values ) { $fields = is_array( $fields ) ? $fields : [ $fields ]; $values = is_array( $values ) ? $values : [ $values ]; $encValues = []; foreach ( $fields as $alias => $field ) { if ( is_int( $alias ) ) { $encValues[] = $this->addIdentifierQuotes( $field ); } else { $encValues[] = $field; // expression } } foreach ( $values as $value ) { if ( is_int( $value ) || is_float( $value ) ) { $encValues[] = $value; } elseif ( is_string( $value ) ) { $encValues[] = $this->quoter->addQuotes( $value ); } elseif ( $value === null ) { throw new DBLanguageError( 'Null value in superlative' ); } else { throw new DBLanguageError( 'Unexpected value type in superlative' ); } } return $sqlfunc . '(' . implode( ',', $encValues ) . ')'; } public function buildComparison( string $op, array $conds ): string { if ( !in_array( $op, [ '>', '>=', '<', '<=' ] ) ) { throw new InvalidArgumentException( "Comparison operator must be one of '>', '>=', '<', '<='" ); } if ( count( $conds ) === 0 ) { throw new InvalidArgumentException( "Empty input" ); } // Construct a condition string by starting with the least significant part of the index, and // adding more significant parts progressively to the left of the string. // // For example, given $conds = [ 'a' => 4, 'b' => 7, 'c' => 1 ], this will generate a condition // like this: // // WHERE a > 4 // OR (a = 4 AND (b > 7 // OR (b = 7 AND (c > 1)))) // // …which is equivalent to the following, which might be easier to understand: // // WHERE a > 4 // OR a = 4 AND b > 7 // OR a = 4 AND b = 7 AND c > 1 // // …and also equivalent to the following, using tuple comparison syntax, which is most intuitive // but apparently performs worse: // // WHERE (a, b, c) > (4, 7, 1) $sql = ''; foreach ( array_reverse( $conds ) as $field => $value ) { if ( is_int( $field ) ) { throw new InvalidArgumentException( 'Non-associative array passed to buildComparison() (typo?)' ); } $encValue = $this->quoter->addQuotes( $value ); if ( $sql === '' ) { $sql = "$field $op $encValue"; // Change '>=' to '>' etc. for remaining fields, as the equality is handled separately $op = rtrim( $op, '=' ); } else { $sql = "$field $op $encValue OR ($field = $encValue AND ($sql))"; } } return $sql; } public function makeList( array $a, $mode = self::LIST_COMMA ) { $first = true; $list = ''; $keyWarning = null; foreach ( $a as $field => $value ) { if ( $first ) { $first = false; } else { if ( $mode == self::LIST_AND ) { $list .= ' AND '; } elseif ( $mode == self::LIST_OR ) { $list .= ' OR '; } else { $list .= ','; } } if ( ( $mode == self::LIST_AND || $mode == self::LIST_OR ) && is_numeric( $field ) ) { if ( $value instanceof IExpression ) { $list .= "(" . $value->toSql( $this->quoter ) . ")"; } elseif ( is_array( $value ) ) { throw new InvalidArgumentException( __METHOD__ . ": unexpected array value without key" ); } elseif ( $value instanceof RawSQLValue ) { throw new InvalidArgumentException( __METHOD__ . ": unexpected raw value without key" ); } else { $list .= "($value)"; } } elseif ( $value instanceof IExpression ) { if ( $mode == self::LIST_AND || $mode == self::LIST_OR ) { throw new InvalidArgumentException( __METHOD__ . ": unexpected key $field for IExpression value" ); } else { throw new InvalidArgumentException( __METHOD__ . ": unexpected IExpression outside WHERE clause" ); } } elseif ( $mode == self::LIST_SET && is_numeric( $field ) ) { $list .= "$value"; } elseif ( ( $mode == self::LIST_AND || $mode == self::LIST_OR ) && is_array( $value ) ) { // Remove null from array to be handled separately if found $includeNull = false; foreach ( array_keys( $value, null, true ) as $nullKey ) { $includeNull = true; unset( $value[$nullKey] ); } if ( count( $value ) == 0 && !$includeNull ) { throw new InvalidArgumentException( __METHOD__ . ": empty input for field $field" ); } elseif ( count( $value ) == 0 ) { // only check if $field is null $list .= "$field IS NULL"; } else { // IN clause contains at least one valid element if ( $includeNull ) { // Group subconditions to ensure correct precedence $list .= '('; } if ( count( $value ) == 1 ) { // Special-case single values, as IN isn't terribly efficient // (but call makeList() so that warnings are emitted if needed) $list .= $field . " = " . $this->makeList( $value ); } else { $list .= $field . " IN (" . $this->makeList( $value ) . ") "; } // if null present in array, append IS NULL if ( $includeNull ) { $list .= " OR $field IS NULL)"; } } } elseif ( is_array( $value ) ) { throw new InvalidArgumentException( __METHOD__ . ": unexpected nested array" ); } elseif ( $value === null ) { if ( $mode == self::LIST_AND || $mode == self::LIST_OR ) { $list .= "$field IS "; } elseif ( $mode == self::LIST_SET ) { $list .= "$field = "; } elseif ( $mode === self::LIST_COMMA && !is_numeric( $field ) ) { $keyWarning ??= [ __METHOD__ . ": array key {key} in list of values ignored", [ 'key' => $field, 'exception' => new RuntimeException() ] ]; } elseif ( $mode === self::LIST_NAMES && !is_numeric( $field ) ) { $keyWarning ??= [ __METHOD__ . ": array key {key} in list of fields ignored", [ 'key' => $field, 'exception' => new RuntimeException() ] ]; } $list .= 'NULL'; } else { if ( $mode == self::LIST_AND || $mode == self::LIST_OR || $mode == self::LIST_SET ) { $list .= "$field = "; } elseif ( $mode === self::LIST_COMMA && !is_numeric( $field ) ) { $keyWarning ??= [ __METHOD__ . ": array key {key} in list of values ignored", [ 'key' => $field, 'exception' => new RuntimeException() ] ]; } elseif ( $mode === self::LIST_NAMES && !is_numeric( $field ) ) { $keyWarning ??= [ __METHOD__ . ": array key {key} in list of fields ignored", [ 'key' => $field, 'exception' => new RuntimeException() ] ]; } $list .= $mode == self::LIST_NAMES ? $value : $this->quoter->addQuotes( $value ); } } if ( $keyWarning ) { // Only log one warning about this per function call, to reduce log spam when a dynamically // generated associative array is passed $this->logger->warning( ...$keyWarning ); } return $list; } public function makeWhereFrom2d( $data, $baseKey, $subKey ) { $conds = []; foreach ( $data as $base => $sub ) { if ( count( $sub ) ) { $conds[] = $this->makeList( [ $baseKey => $base, $subKey => array_map( 'strval', array_keys( $sub ) ) ], self::LIST_AND ); } } if ( !$conds ) { throw new InvalidArgumentException( "Data for $baseKey and $subKey must be non-empty" ); } return $this->makeList( $conds, self::LIST_OR ); } public function factorConds( $condsArray ) { if ( count( $condsArray ) === 0 ) { throw new InvalidArgumentException( __METHOD__ . ": empty condition array" ); } $condsByFieldSet = []; foreach ( $condsArray as $conds ) { if ( !count( $conds ) ) { throw new InvalidArgumentException( __METHOD__ . ": empty condition subarray" ); } $fieldKey = implode( ',', array_keys( $conds ) ); $condsByFieldSet[$fieldKey][] = $conds; } $result = ''; foreach ( $condsByFieldSet as $conds ) { if ( $result !== '' ) { $result .= ' OR '; } $result .= $this->factorCondsWithCommonFields( $conds ); } return $result; } /** * Same as factorConds() but with each element in the array having the same * set of array keys. Validation is done by the caller. * * @param array $condsArray * @return string */ private function factorCondsWithCommonFields( $condsArray ) { $first = $condsArray[array_key_first( $condsArray )]; if ( count( $first ) === 1 ) { // IN clause $field = array_key_first( $first ); $values = []; foreach ( $condsArray as $conds ) { $values[] = $conds[$field]; } return $this->makeList( [ $field => $values ], self::LIST_AND ); } $field1 = array_key_first( $first ); $nullExpressions = []; $expressionsByField1 = []; foreach ( $condsArray as $conds ) { $value1 = $conds[$field1]; unset( $conds[$field1] ); if ( $value1 === null ) { $nullExpressions[] = $conds; } else { $expressionsByField1[$value1][] = $conds; } } $wrap = false; $result = ''; foreach ( $expressionsByField1 as $value1 => $expressions ) { if ( $result !== '' ) { $result .= ' OR '; $wrap = true; } $factored = $this->factorCondsWithCommonFields( $expressions ); $result .= "($field1 = " . $this->quoter->addQuotes( $value1 ) . " AND $factored)"; } if ( count( $nullExpressions ) ) { $factored = $this->factorCondsWithCommonFields( $nullExpressions ); if ( $result !== '' ) { $result .= ' OR '; $wrap = true; } $result .= "($field1 IS NULL AND $factored)"; } if ( $wrap ) { return "($result)"; } else { return $result; } } /** * @inheritDoc * @stable to override */ public function buildConcat( $stringList ) { return 'CONCAT(' . implode( ',', $stringList ) . ')'; } public function limitResult( $sql, $limit, $offset = false ) { if ( !is_numeric( $limit ) ) { throw new DBLanguageError( "Invalid non-numeric limit passed to " . __METHOD__ ); } // This version works in MySQL and SQLite. It will very likely need to be // overridden for most other RDBMS subclasses. return "$sql LIMIT " . ( ( is_numeric( $offset ) && $offset != 0 ) ? "{$offset}," : "" ) . "{$limit} "; } /** * @stable to override * @param string $s * @param string $escapeChar * @return string */ public function escapeLikeInternal( $s, $escapeChar = '`' ) { return str_replace( [ $escapeChar, '%', '_' ], [ "{$escapeChar}{$escapeChar}", "{$escapeChar}%", "{$escapeChar}_" ], $s ); } public function buildLike( $param, ...$params ) { if ( is_array( $param ) ) { $params = $param; } else { $params = func_get_args(); } // @phan-suppress-next-line PhanParamTooFewUnpack $likeValue = new LikeValue( ...$params ); return ' LIKE ' . $likeValue->toSql( $this->quoter ); } public function anyChar() { return new LikeMatch( '_' ); } public function anyString() { return new LikeMatch( '%' ); } /** * @inheritDoc * @stable to override */ public function unionSupportsOrderAndLimit() { return true; // True for almost every DB supported } public function unionQueries( $sqls, $all, $options = [] ) { $glue = $all ? ') UNION ALL (' : ') UNION ('; $sql = '(' . implode( $glue, $sqls ) . ')'; if ( !$this->unionSupportsOrderAndLimit() ) { return $sql; } $sql .= $this->makeOrderBy( $options ); $limit = $options['LIMIT'] ?? null; $offset = $options['OFFSET'] ?? false; if ( $limit !== null ) { $sql = $this->limitResult( $sql, $limit, $offset ); } return $sql; } public function conditional( $cond, $caseTrueExpression, $caseFalseExpression ) { if ( is_array( $cond ) ) { $cond = $this->makeList( $cond, self::LIST_AND ); } if ( $cond instanceof IExpression ) { $cond = $cond->toSql( $this->quoter ); } return "(CASE WHEN $cond THEN $caseTrueExpression ELSE $caseFalseExpression END)"; } public function strreplace( $orig, $old, $new ) { return "REPLACE({$orig}, {$old}, {$new})"; } public function timestamp( $ts = 0 ) { $t = new ConvertibleTimestamp( $ts ); // Let errors bubble up to avoid putting garbage in the DB return $t->getTimestamp( TS_MW ); } public function timestampOrNull( $ts = null ) { if ( $ts === null ) { return null; } else { return $this->timestamp( $ts ); } } public function getInfinity() { return 'infinity'; } public function encodeExpiry( $expiry ) { return ( $expiry == '' || $expiry == 'infinity' || $expiry == $this->getInfinity() ) ? $this->getInfinity() : $this->timestamp( $expiry ); } public function decodeExpiry( $expiry, $format = TS_MW ) { if ( $expiry == '' || $expiry == 'infinity' || $expiry == $this->getInfinity() ) { return 'infinity'; } return ConvertibleTimestamp::convert( $format, $expiry ); } /** * @inheritDoc * @stable to override */ public function buildSubstring( $input, $startPosition, $length = null ) { $this->assertBuildSubstringParams( $startPosition, $length ); $functionBody = "$input FROM $startPosition"; if ( $length !== null ) { $functionBody .= " FOR $length"; } return 'SUBSTRING(' . $functionBody . ')'; } /** * Check type and bounds for parameters to self::buildSubstring() * * All supported databases have substring functions that behave the same for * positive $startPosition and non-negative $length, but behaviors differ when * given negative $startPosition or negative $length. The simplest * solution to that is to just forbid those values. * * @param int $startPosition * @param int|null $length * @since 1.31 in Database, moved to SQLPlatform in 1.39 */ protected function assertBuildSubstringParams( $startPosition, $length ) { if ( $startPosition === 0 ) { // The DBMSs we support use 1-based indexing here. throw new InvalidArgumentException( 'Use 1 as $startPosition for the beginning of the string' ); } if ( !is_int( $startPosition ) || $startPosition < 0 ) { throw new InvalidArgumentException( '$startPosition must be a positive integer' ); } if ( !( ( is_int( $length ) && $length >= 0 ) || $length === null ) ) { throw new InvalidArgumentException( '$length must be null or an integer greater than or equal to 0' ); } } public function buildStringCast( $field ) { // In theory this should work for any standards-compliant // SQL implementation, although it may not be the best way to do it. return "CAST( $field AS CHARACTER )"; } public function buildIntegerCast( $field ) { return 'CAST( ' . $field . ' AS INTEGER )'; } public function implicitOrderby() { return true; } /** * Allows for index remapping in queries where this is not consistent across DBMS * * TODO: Make it protected once all the code is moved over. * * @param string $index * @return string */ public function indexName( $index ) { return $this->indexAliases[$index] ?? $index; } public function setTableAliases( array $aliases ) { $this->tableAliases = $aliases; } public function setIndexAliases( array $aliases ) { $this->indexAliases = $aliases; } /** * @return array[] */ public function getTableAliases() { return $this->tableAliases; } public function setPrefix( $prefix ) { $this->currentDomain = new DatabaseDomain( $this->currentDomain->getDatabase(), $this->currentDomain->getSchema(), $prefix ); } public function setCurrentDomain( DatabaseDomain $currentDomain ) { $this->currentDomain = $currentDomain; } /** * @internal For use by tests * @return DatabaseDomain */ public function getCurrentDomain() { return $this->currentDomain; } public function selectSQLText( $tables, $vars, $conds = '', $fname = __METHOD__, $options = [], $join_conds = [] ) { if ( !is_array( $tables ) ) { if ( $tables === '' || $tables === null || $tables === false ) { $tables = []; } elseif ( is_string( $tables ) ) { $tables = [ $tables ]; } else { throw new DBLanguageError( __METHOD__ . ' called with incorrect table parameter' ); } } if ( is_array( $vars ) ) { $fields = implode( ',', $this->fieldNamesWithAlias( $vars ) ); } else { $fields = $vars; } $options = (array)$options; $useIndexByTable = $options['USE INDEX'] ?? []; if ( !is_array( $useIndexByTable ) ) { if ( count( $tables ) <= 1 ) { $useIndexByTable = [ reset( $tables ) => $useIndexByTable ]; } else { $e = new DBLanguageError( __METHOD__ . " got ambiguous USE INDEX ($fname)" ); ( $this->errorLogger )( $e ); } } $ignoreIndexByTable = $options['IGNORE INDEX'] ?? []; if ( !is_array( $ignoreIndexByTable ) ) { if ( count( $tables ) <= 1 ) { $ignoreIndexByTable = [ reset( $tables ) => $ignoreIndexByTable ]; } else { $e = new DBLanguageError( __METHOD__ . " got ambiguous IGNORE INDEX ($fname)" ); ( $this->errorLogger )( $e ); } } if ( $this->selectOptionsIncludeLocking( $options ) && $this->selectFieldsOrOptionsAggregate( $vars, $options ) ) { // Some DB types (e.g. postgres) disallow FOR UPDATE with aggregate // functions. Discourage use of such queries to encourage compatibility. $this->logger->warning( __METHOD__ . ": aggregation used with a locking SELECT ($fname)" ); } if ( count( $tables ) ) { $from = ' FROM ' . $this->tableNamesWithIndexClauseOrJOIN( $tables, $useIndexByTable, $ignoreIndexByTable, $join_conds ); } else { $from = ''; } [ $startOpts, $preLimitTail, $postLimitTail ] = $this->makeSelectOptions( $options ); if ( is_array( $conds ) ) { $where = $this->makeList( $conds, self::LIST_AND ); } elseif ( $conds instanceof IExpression ) { $where = $conds->toSql( $this->quoter ); } elseif ( $conds === null || $conds === false ) { $where = ''; $this->logger->warning( __METHOD__ . ' called from ' . $fname . ' with incorrect parameters: $conds must be a string or an array', [ 'db_log_category' => 'sql' ] ); } elseif ( is_string( $conds ) ) { $where = $conds; } else { throw new DBLanguageError( __METHOD__ . ' called with incorrect parameters' ); } // Keep historical extra spaces after FROM to avoid testing failures if ( $where === '' || $where === '*' ) { $sql = "SELECT $startOpts $fields $from $preLimitTail"; } else { $sql = "SELECT $startOpts $fields $from WHERE $where $preLimitTail"; } if ( isset( $options['LIMIT'] ) ) { $sql = $this->limitResult( $sql, $options['LIMIT'], $options['OFFSET'] ?? false ); } $sql = "$sql $postLimitTail"; if ( isset( $options['EXPLAIN'] ) ) { $sql = 'EXPLAIN ' . $sql; } if ( $fname === static::CALLER_UNKNOWN || str_starts_with( $fname, 'Wikimedia\\Rdbms\\' ) || $fname === '{closure}' ) { $exception = new RuntimeException(); // Try to figure out and report the real caller $caller = ''; foreach ( $exception->getTrace() as $call ) { if ( str_ends_with( $call['file'] ?? '', 'Test.php' ) ) { // Don't warn when called directly by test code, adding callers there is pointless break; } elseif ( str_starts_with( $call['class'] ?? '', 'Wikimedia\\Rdbms\\' ) ) { // Keep looking for the caller of a rdbms method } elseif ( str_ends_with( $call['class'] ?? '', 'SelectQueryBuilder' ) ) { // Keep looking for the caller of any custom SelectQueryBuilder } else { // Warn about the external caller we found $caller = implode( '::', array_filter( [ $call['class'] ?? null, $call['function'] ] ) ); break; } } if ( $fname === '{closure}' ) { // Someone did ->caller( __METHOD__ ) in a local function, e.g. in a callback to // getWithSetCallback(), MWCallableUpdate or doAtomicSection(). That's not very helpful. // Provide a more specific message. The caller has to be provided like this: // $method = __METHOD__; // function ( ... ) use ( $method ) { ... } $warning = "SQL query with incorrect caller (__METHOD__ used inside a closure: {caller}): {sql}"; } else { $warning = "SQL query did not specify the caller (guessed caller: {caller}): {sql}"; } $this->logger->warning( $warning, [ 'sql' => $sql, 'caller' => $caller, 'exception' => $exception ] ); } return $sql; } /** * @param string|array $options * @return bool */ private function selectOptionsIncludeLocking( $options ) { $options = (array)$options; foreach ( [ 'FOR UPDATE', 'LOCK IN SHARE MODE' ] as $lock ) { if ( in_array( $lock, $options, true ) ) { return true; } } return false; } /** * @param array|string $fields * @param array|string $options * @return bool */ private function selectFieldsOrOptionsAggregate( $fields, $options ) { foreach ( (array)$options as $key => $value ) { if ( is_string( $key ) ) { if ( preg_match( '/^(?:GROUP BY|HAVING)$/i', $key ) ) { return true; } } elseif ( is_string( $value ) ) { if ( preg_match( '/^(?:DISTINCT|DISTINCTROW)$/i', $value ) ) { return true; } } } $regex = '/^(?:COUNT|MIN|MAX|SUM|GROUP_CONCAT|LISTAGG|ARRAY_AGG)\s*\\(/i'; foreach ( (array)$fields as $field ) { if ( is_string( $field ) && preg_match( $regex, $field ) ) { return true; } } return false; } /** * Gets an array of aliased field names * * @param array $fields [ [alias] => field ] * @return string[] See fieldNameWithAlias() */ protected function fieldNamesWithAlias( $fields ) { $retval = []; foreach ( $fields as $alias => $field ) { if ( is_numeric( $alias ) ) { $alias = $field; } $retval[] = $this->fieldNameWithAlias( $field, $alias ); } return $retval; } /** * Get an aliased field name * e.g. fieldName AS newFieldName * * @stable to override * @param string $name Field name * @param string|false $alias Alias (optional) * @return string SQL name for aliased field. Will not alias a field to its own name */ public function fieldNameWithAlias( $name, $alias = false ) { if ( !$alias || (string)$alias === (string)$name ) { return $name; } else { return $name . ' AS ' . $this->addIdentifierQuotes( $alias ); // PostgreSQL needs AS } } /** * Get the aliased table name clause for a FROM clause * which might have a JOIN and/or USE INDEX or IGNORE INDEX clause * * @param array $tables Array of ([alias] => table reference) * @param array $use_index Same as for select() * @param array $ignore_index Same as for select() * @param array $join_conds Same as for select() * @return string */ protected function tableNamesWithIndexClauseOrJOIN( $tables, $use_index = [], $ignore_index = [], $join_conds = [] ) { $ret = []; $retJOIN = []; $use_index = (array)$use_index; $ignore_index = (array)$ignore_index; $join_conds = (array)$join_conds; foreach ( $tables as $alias => $table ) { if ( !is_string( $alias ) ) { // No alias? Set it equal to the table name $alias = $table; } if ( is_array( $table ) ) { // A parenthesized group if ( count( $table ) > 1 ) { $joinedTable = '(' . $this->tableNamesWithIndexClauseOrJOIN( $table, $use_index, $ignore_index, $join_conds ) . ')'; } else { // Degenerate case $innerTable = reset( $table ); $innerAlias = key( $table ); $joinedTable = $this->tableNameWithAlias( $innerTable, is_string( $innerAlias ) ? $innerAlias : $innerTable ); } } else { $joinedTable = $this->tableNameWithAlias( $table, $alias ); } // Is there a JOIN clause for this table? if ( isset( $join_conds[$alias] ) ) { Assert::parameterType( 'array', $join_conds[$alias], "join_conds[$alias]" ); [ $joinType, $conds ] = $join_conds[$alias]; $tableClause = $this->normalizeJoinType( $joinType ); $tableClause .= ' ' . $joinedTable; if ( isset( $use_index[$alias] ) ) { // has USE INDEX? $use = $this->useIndexClause( implode( ',', (array)$use_index[$alias] ) ); if ( $use != '' ) { $tableClause .= ' ' . $use; } } if ( isset( $ignore_index[$alias] ) ) { // has IGNORE INDEX? $ignore = $this->ignoreIndexClause( implode( ',', (array)$ignore_index[$alias] ) ); if ( $ignore != '' ) { $tableClause .= ' ' . $ignore; } } $on = $this->makeList( (array)$conds, self::LIST_AND ); if ( $on != '' ) { $tableClause .= ' ON (' . $on . ')'; } $retJOIN[] = $tableClause; } elseif ( isset( $use_index[$alias] ) ) { // Is there an INDEX clause for this table? $tableClause = $joinedTable; $tableClause .= ' ' . $this->useIndexClause( implode( ',', (array)$use_index[$alias] ) ); $ret[] = $tableClause; } elseif ( isset( $ignore_index[$alias] ) ) { // Is there an INDEX clause for this table? $tableClause = $joinedTable; $tableClause .= ' ' . $this->ignoreIndexClause( implode( ',', (array)$ignore_index[$alias] ) ); $ret[] = $tableClause; } else { $tableClause = $joinedTable; $ret[] = $tableClause; } } // We can't separate explicit JOIN clauses with ',', use ' ' for those $implicitJoins = implode( ',', $ret ); $explicitJoins = implode( ' ', $retJOIN ); // Compile our final table clause return implode( ' ', [ $implicitJoins, $explicitJoins ] ); } /** * Validate and normalize a join type * * Subclasses may override this to add supported join types. * * @param string $joinType * @return string */ protected function normalizeJoinType( string $joinType ) { switch ( strtoupper( $joinType ) ) { case 'JOIN': case 'INNER JOIN': return 'JOIN'; case 'LEFT JOIN': return 'LEFT JOIN'; case 'STRAIGHT_JOIN': case 'STRAIGHT JOIN': // MySQL only return 'JOIN'; default: return $joinType; } } /** * Get an aliased table name * * This returns strings like "tableName AS newTableName" for aliased tables * and "(SELECT * from tableA) newTablename" for subqueries (e.g. derived tables) * * @see Database::tableName() * @param string|Subquery $table The unqualified name of a table, or Subquery * @param string|false $alias Table alias (optional) * @return string SQL name for aliased table. Will not alias a table to its own name */ protected function tableNameWithAlias( $table, $alias = false ) { if ( is_string( $table ) ) { $quotedTable = $this->tableName( $table ); } elseif ( $table instanceof Subquery ) { $quotedTable = (string)$table; } else { throw new InvalidArgumentException( "Table must be a string or Subquery" ); } if ( $alias === false || $alias === $table ) { if ( $table instanceof Subquery ) { throw new InvalidArgumentException( "Subquery table missing alias" ); } return $quotedTable; } else { return $quotedTable . ' ' . $this->addIdentifierQuotes( $alias ); } } public function tableName( string $name, $format = 'quoted' ) { $prefix = $this->currentDomain->getTablePrefix(); // Warn about table names that look qualified if ( ( str_contains( $name, '.' ) && !preg_match( '/^information_schema\.[a-z_0-9]+$/', $name ) ) || ( $prefix !== '' && str_starts_with( $name, $prefix ) ) ) { $this->logger->warning( __METHOD__ . ' called with qualified table ' . $name, [ 'db_log_category' => 'sql' ] ); } // Extract necessary database, schema, table identifiers and quote them as needed $formattedComponents = []; foreach ( $this->qualifiedTableComponents( $name ) as $component ) { if ( $format === 'quoted' ) { $formattedComponents[] = $this->addIdentifierQuotes( $component ); } else { $formattedComponents[] = $component; } } return implode( '.', $formattedComponents ); } /** * Get the table components needed for a query given the currently selected database/schema * * The resulting array will take one of the follow forms: * - <table identifier> * - <database identifier>.<table identifier> (e.g. non-Postgres) * - <schema identifier>.<table identifier> (e.g. Postgres-only) * - <database identifier>.<schema identifier>.<table identifier> (e.g. Postgres-only) * * If the provided table name only consists of an unquoted table identifier that has an * entry in ({@link getTableAliases()}), then, the resulting components will be determined * from the alias configuration. If such alias configuration does not specify the table * prefix, then the current DB domain prefix will be prepended to the table identifier. * * In all other cases where the provided table name only consists of an unquoted table * identifier, the current DB domain prefix will be prepended to the table identifier. * * Empty database/schema identifiers are omitted from the resulting array. * * @param string $name Table name as database.schema.table, database.table, or table * @return string[] Non-empty list of unquoted identifiers that form the qualified table name */ public function qualifiedTableComponents( $name ) { $identifiers = $this->extractTableNameComponents( $name ); if ( count( $identifiers ) > 3 ) { throw new DBLanguageError( "Too many components in table name '$name'" ); } // Table alias config and prefixes only apply to unquoted single-identifier names if ( count( $identifiers ) == 1 && !$this->isQuotedIdentifier( $identifiers[0] ) ) { [ $table ] = $identifiers; if ( isset( $this->tableAliases[$table] ) ) { // This is an "alias" table that uses a different db/schema/prefix scheme $database = $this->tableAliases[$table]['dbname']; $schema = is_string( $this->tableAliases[$table]['schema'] ) ? $this->tableAliases[$table]['schema'] : $this->relationSchemaQualifier(); $prefix = is_string( $this->tableAliases[$table]['prefix'] ) ? $this->tableAliases[$table]['prefix'] : $this->currentDomain->getTablePrefix(); } else { // Use the current database domain to resolve the schema and prefix $database = ''; $schema = $this->relationSchemaQualifier(); $prefix = $this->currentDomain->getTablePrefix(); } $qualifierIdentifiers = [ $database, $schema ]; $tableIdentifier = $prefix . $table; } else { $qualifierIdentifiers = array_slice( $identifiers, 0, -1 ); $tableIdentifier = end( $identifiers ); } $components = []; foreach ( $qualifierIdentifiers as $identifier ) { if ( $identifier !== null && $identifier !== '' ) { $components[] = $this->isQuotedIdentifier( $identifier ) ? substr( $identifier, 1, -1 ) : $identifier; } } $components[] = $this->isQuotedIdentifier( $tableIdentifier ) ? substr( $tableIdentifier, 1, -1 ) : $tableIdentifier; return $components; } /** * Extract the dot-separated components of a table name, preserving identifier quotation * * @param string $name Table name, possible qualified with db or db+schema * @return string[] Non-empty list of the identifiers included in the provided table name */ public function extractTableNameComponents( string $name ) { $quoteChar = $this->getIdentifierQuoteChar(); $components = []; foreach ( explode( '.', $name ) as $component ) { if ( $this->isQuotedIdentifier( $component ) ) { $unquotedComponent = substr( $component, 1, -1 ); } else { $unquotedComponent = $component; } if ( str_contains( $unquotedComponent, $quoteChar ) ) { throw new DBLanguageError( 'Table name component contains unexpected quote or dot character' ); } $components[] = $component; } return $components; } /** * Get the database identifer and prefixed table name identifier for a table * * The table name is assumed to be relative to the current DB domain * * This method is useful for TEMPORARY table tracking. In MySQL, temp tables with identical * names can co-exist on different databases, which can be done via CREATE and USE. Note * that SQLite/PostgreSQL do not allow changing the database within a session. This method * omits the schema identifier for several reasons: * - MySQL/MariaDB do not support schemas at all. * - SQLite/PostgreSQL put all TEMPORARY tables in the same schema (TEMP and pgtemp, * respectively). When these engines resolve a table reference, they first check for * a matching table in the temp schema, before checking the current DB domain schema. * Note that this breaks table segregation based on the schema component of the DB * domain, e.g. a temp table with unqualified name "x" resolves to the same underlying * table whether the current DB domain is "my_db-schema1-mw_" or "my_db-schema2-mw_". * By ignoring the schema, we can at least account for this. * - Exposing the the TEMP/pg_temp schema here would be too leaky of an abstraction, * running the risk of unexpected results, such as identifiers that don't match. It is * easier to just avoid creating identically-named TEMPORARY tables on different schemas. * * @internal only to be used inside rdbms library * @param string $table Table name * @return array{0:string|null,1:string} (unquoted database name, unquoted prefixed table name) */ public function getDatabaseAndTableIdentifier( string $table ) { $components = $this->qualifiedTableComponents( $table ); switch ( count( $components ) ) { case 1: return [ $this->currentDomain->getDatabase(), $components[0] ]; case 2: return $components; default: throw new DBLanguageError( 'Too many table components' ); } } /** * @stable to override * @return string|null Schema to use to qualify relations in queries */ protected function relationSchemaQualifier() { return $this->currentDomain->getSchema(); } /** * @deprecated since 1.39. */ public function tableNames( ...$tables ) { wfDeprecated( __METHOD__, '1.39' ); $retVal = []; foreach ( $tables as $name ) { $retVal[$name] = $this->tableName( $name ); } return $retVal; } public function tableNamesN( ...$tables ) { $retVal = []; foreach ( $tables as $name ) { $retVal[] = $this->tableName( $name ); } return $retVal; } /** * Returns if the given identifier looks quoted or not according to * the database convention for quoting identifiers * * @note Do not use this to determine if untrusted input is safe. * A malicious user can trick this function. * @param string $name * @return bool */ public function isQuotedIdentifier( $name ) { $quoteChar = $this->getIdentifierQuoteChar(); return strlen( $name ) > 1 && $name[0] === $quoteChar && $name[-1] === $quoteChar; } /** * USE INDEX clause. * * This can be used as optimisation in queries that affect tables with multiple * indexes if the database does not pick the most optimal one by default. * The "right" index might vary between database backends and versions thereof, * as such in practice this is biased toward specifically improving performance * of large wiki farms that use MySQL or MariaDB (like Wikipedia). * * @stable to override * @param string $index * @return string */ public function useIndexClause( $index ) { return ''; } /** * IGNORE INDEX clause. * * The inverse of Database::useIndexClause. * * @param string $index * @return string */ public function ignoreIndexClause( $index ) { return ''; } /** * Returns an optional USE INDEX clause to go after the table, and a * string to go at the end of the query. * * @see Database::select() * * @stable to override * @param array $options Associative array of options to be turned into * an SQL query, valid keys are listed in the function. * @return string[] (START OPTIONS, PRE-LIMIT TAIL, POST-LIMIT TAIL) */ protected function makeSelectOptions( array $options ) { $preLimitTail = $postLimitTail = ''; $startOpts = ''; $noKeyOptions = []; foreach ( $options as $key => $option ) { if ( is_numeric( $key ) ) { $noKeyOptions[$option] = true; } } $preLimitTail .= $this->makeGroupByWithHaving( $options ); $preLimitTail .= $this->makeOrderBy( $options ); if ( isset( $noKeyOptions['FOR UPDATE'] ) ) { $postLimitTail .= ' FOR UPDATE'; } if ( isset( $noKeyOptions['LOCK IN SHARE MODE'] ) ) { $postLimitTail .= ' LOCK IN SHARE MODE'; } if ( isset( $noKeyOptions['DISTINCT'] ) || isset( $noKeyOptions['DISTINCTROW'] ) ) { $startOpts .= 'DISTINCT'; } # Various MySQL extensions if ( isset( $noKeyOptions['STRAIGHT_JOIN'] ) ) { $startOpts .= ' /*! STRAIGHT_JOIN */'; } if ( isset( $noKeyOptions['SQL_BIG_RESULT'] ) ) { $startOpts .= ' SQL_BIG_RESULT'; } if ( isset( $noKeyOptions['SQL_BUFFER_RESULT'] ) ) { $startOpts .= ' SQL_BUFFER_RESULT'; } if ( isset( $noKeyOptions['SQL_SMALL_RESULT'] ) ) { $startOpts .= ' SQL_SMALL_RESULT'; } if ( isset( $noKeyOptions['SQL_CALC_FOUND_ROWS'] ) ) { $startOpts .= ' SQL_CALC_FOUND_ROWS'; } return [ $startOpts, $preLimitTail, $postLimitTail ]; } /** * Returns an optional GROUP BY with an optional HAVING * * @param array $options Associative array of options * @return string * @see Database::select() * @since 1.21 */ protected function makeGroupByWithHaving( $options ) { $sql = ''; if ( isset( $options['GROUP BY'] ) ) { $gb = is_array( $options['GROUP BY'] ) ? implode( ',', $options['GROUP BY'] ) : $options['GROUP BY']; $sql .= ' GROUP BY ' . $gb; } if ( isset( $options['HAVING'] ) ) { $having = is_array( $options['HAVING'] ) ? $this->makeList( $options['HAVING'], self::LIST_AND ) : $options['HAVING']; $sql .= ' HAVING ' . $having; } return $sql; } /** * Returns an optional ORDER BY * * @param array $options Associative array of options * @return string * @see Database::select() * @since 1.21 */ protected function makeOrderBy( $options ) { if ( isset( $options['ORDER BY'] ) ) { $ob = is_array( $options['ORDER BY'] ) ? implode( ',', $options['ORDER BY'] ) : $options['ORDER BY']; return ' ORDER BY ' . $ob; } return ''; } public function buildGroupConcatField( $delim, $tables, $field, $conds = '', $join_conds = [] ) { $fld = "GROUP_CONCAT($field SEPARATOR " . $this->quoter->addQuotes( $delim ) . ')'; return '(' . $this->selectSQLText( $tables, $fld, $conds, static::CALLER_SUBQUERY, [], $join_conds ) . ')'; } public function buildSelectSubquery( $tables, $vars, $conds = '', $fname = __METHOD__, $options = [], $join_conds = [] ) { return new Subquery( $this->selectSQLText( $tables, $vars, $conds, $fname, $options, $join_conds ) ); } public function insertSqlText( $table, array $rows ) { $encTable = $this->tableName( $table ); [ $sqlColumns, $sqlTuples ] = $this->makeInsertLists( $rows ); return [ "INSERT INTO $encTable ($sqlColumns) VALUES $sqlTuples", "INSERT INTO $encTable ($sqlColumns) VALUES '?'" ]; } /** * Make SQL lists of columns, row tuples, and column aliases for INSERT/VALUES expressions * * The tuple column order is that of the columns of the first provided row. * The provided rows must have exactly the same keys and ordering thereof. * * @param array[] $rows Non-empty list of (column => value) maps * @param string $aliasPrefix Optional prefix to prepend to the magic alias names * @param string[] $typeByColumn Optional map of (column => data type) * @return array (comma-separated columns, comma-separated tuples, comma-separated aliases) * @since 1.35 */ public function makeInsertLists( array $rows, $aliasPrefix = '', array $typeByColumn = [] ) { $firstRow = $rows[0]; if ( !is_array( $firstRow ) || !$firstRow ) { throw new DBLanguageError( 'Got an empty row list or empty row' ); } // List of columns that define the value tuple ordering $tupleColumns = array_keys( $firstRow ); $valueTuples = []; foreach ( $rows as $row ) { $rowColumns = array_keys( $row ); // VALUES(...) requires a uniform correspondence of (column => value) if ( $rowColumns !== $tupleColumns ) { throw new DBLanguageError( 'Got row columns (' . implode( ', ', $rowColumns ) . ') ' . 'instead of expected (' . implode( ', ', $tupleColumns ) . ')' ); } // Make the value tuple that defines this row $valueTuples[] = '(' . $this->makeList( array_values( $row ), self::LIST_COMMA ) . ')'; } $magicAliasFields = []; foreach ( $tupleColumns as $column ) { $magicAliasFields[] = $aliasPrefix . $column; } return [ $this->makeList( $tupleColumns, self::LIST_NAMES ), implode( ',', $valueTuples ), $this->makeList( $magicAliasFields, self::LIST_NAMES ) ]; } public function insertNonConflictingSqlText( $table, array $rows ) { $encTable = $this->tableName( $table ); [ $sqlColumns, $sqlTuples ] = $this->makeInsertLists( $rows ); [ $sqlVerb, $sqlOpts ] = $this->makeInsertNonConflictingVerbAndOptions(); return [ rtrim( "$sqlVerb $encTable ($sqlColumns) VALUES $sqlTuples $sqlOpts" ), rtrim( "$sqlVerb $encTable ($sqlColumns) VALUES '?' $sqlOpts" ) ]; } /** * @stable to override * @return string[] ("INSERT"-style SQL verb, "ON CONFLICT"-style clause or "") * @since 1.35 */ protected function makeInsertNonConflictingVerbAndOptions() { return [ 'INSERT IGNORE INTO', '' ]; } public function insertSelectNativeSqlText( $destTable, $srcTable, array $varMap, $conds, $fname, array $insertOptions, array $selectOptions, $selectJoinConds ) { [ $sqlVerb, $sqlOpts ] = $this->isFlagInOptions( 'IGNORE', $insertOptions ) ? $this->makeInsertNonConflictingVerbAndOptions() : [ 'INSERT INTO', '' ]; $encDstTable = $this->tableName( $destTable ); $sqlDstColumns = implode( ',', array_keys( $varMap ) ); $selectSql = $this->selectSQLText( $srcTable, array_values( $varMap ), $conds, $fname, $selectOptions, $selectJoinConds ); return rtrim( "$sqlVerb $encDstTable ($sqlDstColumns) $selectSql $sqlOpts" ); } /** * @param string $option Query option flag (e.g. "IGNORE" or "FOR UPDATE") * @param array $options Combination option/value map and boolean option list * @return bool Whether the option appears as an integer-keyed value in the options * @since 1.35 */ public function isFlagInOptions( $option, array $options ) { foreach ( array_keys( $options, $option, true ) as $k ) { if ( is_int( $k ) ) { return true; } } return false; } /** * Build an SQL condition to find rows with matching key values to those in $rows. * * @param array[] $rows Non-empty list of rows * @param string[] $uniqueKey List of columns that define a single unique index * @return string */ public function makeKeyCollisionCondition( array $rows, array $uniqueKey ) { if ( !$rows ) { throw new DBLanguageError( "Empty row array" ); } elseif ( !$uniqueKey ) { throw new DBLanguageError( "Empty unique key array" ); } if ( count( $uniqueKey ) == 1 ) { // Use a simple IN(...) clause $column = reset( $uniqueKey ); $values = array_column( $rows, $column ); if ( count( $values ) !== count( $rows ) ) { throw new DBLanguageError( "Missing values for unique key ($column)" ); } return $this->makeList( [ $column => $values ], self::LIST_AND ); } $nullByUniqueKeyColumn = array_fill_keys( $uniqueKey, null ); $orConds = []; foreach ( $rows as $row ) { $rowKeyMap = array_intersect_key( $row, $nullByUniqueKeyColumn ); if ( count( $rowKeyMap ) != count( $uniqueKey ) ) { throw new DBLanguageError( "Missing values for unique key (" . implode( ',', $uniqueKey ) . ")" ); } $orConds[] = $this->makeList( $rowKeyMap, self::LIST_AND ); } return count( $orConds ) > 1 ? $this->makeList( $orConds, self::LIST_OR ) : $orConds[0]; } public function deleteJoinSqlText( $delTable, $joinTable, $delVar, $joinVar, $conds ) { if ( !$conds ) { throw new DBLanguageError( __METHOD__ . ' called with empty $conds' ); } $delTable = $this->tableName( $delTable ); $joinTable = $this->tableName( $joinTable ); $sql = "DELETE FROM $delTable WHERE $delVar IN (SELECT $joinVar FROM $joinTable "; if ( $conds != '*' ) { $sql .= 'WHERE ' . $this->makeList( $conds, self::LIST_AND ); } $sql .= ')'; return $sql; } /** * @param string $table The unqualified name of a table * @param string|array $conds * @return Query */ public function deleteSqlText( $table, $conds ) { $isCondValid = ( is_string( $conds ) || is_array( $conds ) ) && $conds; if ( !$isCondValid ) { throw new DBLanguageError( __METHOD__ . ' called with empty conditions' ); } $encTable = $this->tableName( $table ); $sql = "DELETE FROM $encTable"; $condsSql = ''; $cleanCondsSql = ''; if ( $conds !== self::ALL_ROWS && $conds !== [ self::ALL_ROWS ] ) { $cleanCondsSql = ' WHERE ' . $this->scrubArray( $conds ); if ( is_array( $conds ) ) { $conds = $this->makeList( $conds, self::LIST_AND ); } $condsSql .= ' WHERE ' . $conds; } return new Query( $sql . $condsSql, self::QUERY_CHANGE_ROWS, 'DELETE', $table, $sql . $cleanCondsSql ); } private function scrubArray( $array, $listType = self::LIST_AND ) { if ( is_array( $array ) ) { $scrubbedArray = []; foreach ( $array as $key => $value ) { if ( $value instanceof IExpression ) { $scrubbedArray[$key] = $value->toGeneralizedSql(); } else { $scrubbedArray[$key] = '?'; } } return $this->makeList( $scrubbedArray, $listType ); } return '?'; } public function updateSqlText( $table, $set, $conds, $options ) { $isCondValid = ( is_string( $conds ) || is_array( $conds ) ) && $conds; if ( !$isCondValid ) { throw new DBLanguageError( __METHOD__ . ' called with empty conditions' ); } $encTable = $this->tableName( $table ); $opts = $this->makeUpdateOptions( $options ); $sql = "UPDATE $opts $encTable"; $condsSql = " SET " . $this->makeList( $set, self::LIST_SET ); $cleanCondsSql = " SET " . $this->scrubArray( $set, self::LIST_SET ); if ( $conds && $conds !== self::ALL_ROWS && $conds !== [ self::ALL_ROWS ] ) { $cleanCondsSql .= ' WHERE ' . $this->scrubArray( $conds ); if ( is_array( $conds ) ) { $conds = $this->makeList( $conds, self::LIST_AND ); } $condsSql .= ' WHERE ' . $conds; } return new Query( $sql . $condsSql, self::QUERY_CHANGE_ROWS, 'UPDATE', $table, $sql . $cleanCondsSql ); } /** * Make UPDATE options for the Database::update function * * @param array $options The options passed to Database::update * @return string */ protected function makeUpdateOptions( $options ) { $opts = $this->makeUpdateOptionsArray( $options ); return implode( ' ', $opts ); } /** * Make UPDATE options array for Database::makeUpdateOptions * * @stable to override * @param array $options * @return array */ protected function makeUpdateOptionsArray( $options ) { $options = $this->normalizeOptions( $options ); $opts = []; if ( in_array( 'IGNORE', $options ) ) { $opts[] = 'IGNORE'; } return $opts; } /** * @param string|array $options * @return array Combination option/value map and boolean option list * @since 1.35, moved to SQLPlatform in 1.39 */ final public function normalizeOptions( $options ) { if ( is_array( $options ) ) { return $options; } elseif ( is_string( $options ) ) { return ( $options === '' ) ? [] : [ $options ]; } else { throw new DBLanguageError( __METHOD__ . ': expected string or array' ); } } public function dropTableSqlText( $table ) { // https://mariadb.com/kb/en/drop-table/ // https://dev.mysql.com/doc/refman/8.0/en/drop-table.html // https://www.postgresql.org/docs/9.2/sql-truncate.html return "DROP TABLE " . $this->tableName( $table ) . " CASCADE"; } /** * @param string $sql SQL query * @return string|null * @deprecated Since 1.42 */ public function getQueryVerb( $sql ) { wfDeprecated( __METHOD__, '1.42' ); return QueryBuilderFromRawSql::buildQuery( $sql, 0 )->getVerb(); } /** * Determine whether a SQL statement is sensitive to isolation level. * * A SQL statement is considered transactable if its result could vary * depending on the transaction isolation level. Operational commands * such as 'SET' and 'SHOW' are not considered to be transactable. * * Main purpose: Used by query() to decide whether to begin a transaction * before the current query (in DBO_TRX mode, on by default). * * @return bool */ public function isTransactableQuery( Query $sql ) { return !in_array( $sql->getVerb(), [ 'BEGIN', 'ROLLBACK', 'ROLLBACK TO SAVEPOINT', 'COMMIT', 'SET', 'SHOW', 'CREATE', 'ALTER', 'USE', 'SHOW' ], true ); } public function buildExcludedValue( $column ) { /* @see Database::upsert() */ // This can be treated like a single value since __VALS is a single row table return "(SELECT __$column FROM __VALS)"; } public function savepointSqlText( $identifier ) { return 'SAVEPOINT ' . $this->addIdentifierQuotes( $identifier ); } public function releaseSavepointSqlText( $identifier ) { return 'RELEASE SAVEPOINT ' . $this->addIdentifierQuotes( $identifier ); } public function rollbackToSavepointSqlText( $identifier ) { return 'ROLLBACK TO SAVEPOINT ' . $this->addIdentifierQuotes( $identifier ); } public function rollbackSqlText() { return 'ROLLBACK'; } public function dispatchingInsertSqlText( $table, $rows, $options ) { $rows = $this->normalizeRowArray( $rows ); if ( !$rows ) { return false; } $options = $this->normalizeOptions( $options ); if ( $this->isFlagInOptions( 'IGNORE', $options ) ) { [ $sql, $cleanSql ] = $this->insertNonConflictingSqlText( $table, $rows ); } else { [ $sql, $cleanSql ] = $this->insertSqlText( $table, $rows ); } return new Query( $sql, self::QUERY_CHANGE_ROWS, 'INSERT', $table, $cleanSql ); } /** * @param array $rowOrRows A single (field => value) map or a list of such maps * @return array[] List of (field => value) maps * @since 1.35 */ final protected function normalizeRowArray( array $rowOrRows ) { if ( !$rowOrRows ) { $rows = []; } elseif ( isset( $rowOrRows[0] ) ) { $rows = $rowOrRows; } else { $rows = [ $rowOrRows ]; } foreach ( $rows as $row ) { if ( !is_array( $row ) ) { throw new DBLanguageError( "Got non-array in row array" ); } elseif ( !$row ) { throw new DBLanguageError( "Got empty array in row array" ); } } return $rows; } /** * Validate and normalize parameters to upsert() or replace() * * @param string|string[]|string[][] $uniqueKeys Unique indexes (only one is allowed) * @param array[] &$rows The row array, which will be replaced with a normalized version. * @return string[] List of columns that defines a single unique index * @since 1.35 */ final public function normalizeUpsertParams( $uniqueKeys, &$rows ) { $rows = $this->normalizeRowArray( $rows ); if ( !$uniqueKeys ) { throw new DBLanguageError( 'No unique key specified for upsert/replace' ); } $uniqueKey = $this->normalizeUpsertKeys( $uniqueKeys ); $this->assertValidUpsertRowArray( $rows, $uniqueKey ); return $uniqueKey; } /** * @param array|string $conds * @param string $fname * @return array * @since 1.31 */ final public function normalizeConditions( $conds, $fname ) { if ( $conds === null || $conds === false ) { $this->logger->warning( __METHOD__ . ' called from ' . $fname . ' with incorrect parameters: $conds must be a string or an array', [ 'db_log_category' => 'sql' ] ); return []; } elseif ( $conds === '' ) { return []; } return is_array( $conds ) ? $conds : [ $conds ]; } /** * @param string|string[]|string[][] $uniqueKeys Unique indexes (only one is allowed) * @return string[] List of columns that defines a single unique index * @since 1.35 */ private function normalizeUpsertKeys( $uniqueKeys ) { if ( is_string( $uniqueKeys ) ) { return [ $uniqueKeys ]; } elseif ( !is_array( $uniqueKeys ) ) { throw new DBLanguageError( 'Invalid unique key array' ); } else { if ( count( $uniqueKeys ) !== 1 || !isset( $uniqueKeys[0] ) ) { throw new DBLanguageError( "The unique key array should contain a single unique index" ); } $uniqueKey = $uniqueKeys[0]; if ( is_string( $uniqueKey ) ) { // Passing a list of strings for single-column unique keys is too // easily confused with passing the columns of composite unique key $this->logger->warning( __METHOD__ . " called with deprecated parameter style: " . "the unique key array should be a string or array of string arrays", [ 'exception' => new RuntimeException(), 'db_log_category' => 'sql', ] ); return $uniqueKeys; } elseif ( is_array( $uniqueKey ) ) { return $uniqueKey; } else { throw new DBLanguageError( 'Invalid unique key array entry' ); } } } /** * @param array<int,array> $rows Normalized list of rows to insert * @param string[] $uniqueKey Columns of the unique key to UPSERT upon * @since 1.37 */ final protected function assertValidUpsertRowArray( array $rows, array $uniqueKey ) { foreach ( $rows as $row ) { foreach ( $uniqueKey as $column ) { if ( !isset( $row[$column] ) ) { throw new DBLanguageError( "NULL/absent values for unique key (" . implode( ',', $uniqueKey ) . ")" ); } } } } /** * @param array $set Combined column/literal assignment map and SQL assignment list * @param string[] $uniqueKey Columns of the unique key to UPSERT upon * @param array<int,array> $rows List of rows to upsert * @since 1.37 */ final public function assertValidUpsertSetArray( array $set, array $uniqueKey, array $rows ) { if ( !$set ) { throw new DBLanguageError( "Update assignment list can't be empty for upsert" ); } // Sloppy callers might construct the SET array using the ROW array, leaving redundant // column definitions for unique key columns. Detect this for backwards compatibility. $soleRow = ( count( $rows ) == 1 ) ? reset( $rows ) : null; // Disallow value changes for any columns in the unique key. This avoids additional // insertion order dependencies that are unwieldy and difficult to implement efficiently // in PostgreSQL. foreach ( $set as $k => $v ) { if ( is_string( $k ) ) { // Key is a column name and value is a literal (e.g. string, int, null, ...) if ( in_array( $k, $uniqueKey, true ) ) { if ( $soleRow && array_key_exists( $k, $soleRow ) && $soleRow[$k] === $v ) { $this->logger->warning( __METHOD__ . " called with redundant assignment to column '$k'", [ 'exception' => new RuntimeException(), 'db_log_category' => 'sql', ] ); } else { throw new DBLanguageError( "Cannot reassign column '$k' since it belongs to the provided unique key" ); } } } elseif ( preg_match( '/^([a-zA-Z0-9_]+)\s*=/', $v, $m ) ) { // Value is of the form "<unquoted alphanumeric column> = <SQL expression>" if ( in_array( $m[1], $uniqueKey, true ) ) { throw new DBLanguageError( "Cannot reassign column '{$m[1]}' since it belongs to the provided unique key" ); } } } } /** * @param array|string $var Field parameter in the style of select() * @return string|null Column name or null; ignores aliases */ final public function extractSingleFieldFromList( $var ) { if ( is_array( $var ) ) { if ( !$var ) { $column = null; } elseif ( count( $var ) == 1 ) { $column = $var[0] ?? reset( $var ); } else { throw new DBLanguageError( __METHOD__ . ': got multiple columns' ); } } else { $column = $var; } return $column; } public function setSchemaVars( $vars ) { $this->schemaVars = is_array( $vars ) ? $vars : null; } /** * Get schema variables. If none have been set via setSchemaVars(), then * use some defaults from the current object. * * @return array */ protected function getSchemaVars() { return $this->schemaVars ?? $this->getDefaultSchemaVars(); } /** * Get schema variables to use if none have been set via setSchemaVars(). * * Override this in derived classes to provide variables for tables.sql * and SQL patch files. * * @stable to override * @return array */ protected function getDefaultSchemaVars() { return []; } /** * Database-independent variable replacement. Replaces a set of variables * in an SQL statement with their contents as given by $this->getSchemaVars(). * * Supports '{$var}' `{$var}` and / *$var* / (without the spaces) style variables. * * - '{$var}' should be used for text and is passed through the database's * addQuotes method. * - `{$var}` should be used for identifiers (e.g. table and database names). * It is passed through the database's addIdentifierQuotes method which * can be overridden if the database uses something other than backticks. * - / *_* / or / *$wgDBprefix* / passes the name that follows through the * database's tableName method. * - / *i* / passes the name that follows through the database's indexName method. * - In all other cases, / *$var* / is left unencoded. Except for table options, * its use should be avoided. In 1.24 and older, string encoding was applied. * * @param string $ins SQL statement to replace variables in * @return string The new SQL statement with variables replaced */ public function replaceVars( $ins ) { $vars = $this->getSchemaVars(); return preg_replace_callback( '! /\* (\$wgDBprefix|[_i]) \*/ (\w*) | # 1-2. tableName, indexName \'\{\$ (\w+) }\' | # 3. addQuotes `\{\$ (\w+) }` | # 4. addIdentifierQuotes /\*\$ (\w+) \*/ # 5. leave unencoded !x', function ( $m ) use ( $vars ) { // Note: Because of <https://bugs.php.net/bug.php?id=51881>, // check for both nonexistent keys *and* the empty string. if ( isset( $m[1] ) && $m[1] !== '' ) { if ( $m[1] === 'i' ) { return $this->indexName( $m[2] ); } else { return $this->tableName( $m[2] ); } } elseif ( isset( $m[3] ) && $m[3] !== '' && array_key_exists( $m[3], $vars ) ) { return $this->quoter->addQuotes( $vars[$m[3]] ); } elseif ( isset( $m[4] ) && $m[4] !== '' && array_key_exists( $m[4], $vars ) ) { return $this->addIdentifierQuotes( $vars[$m[4]] ); } elseif ( isset( $m[5] ) && $m[5] !== '' && array_key_exists( $m[5], $vars ) ) { return $vars[$m[5]]; } else { return $m[0]; } }, $ins ); } public function lockSQLText( $lockName, $timeout ) { throw new RuntimeException( 'locking must be implemented in subclasses' ); } public function lockIsFreeSQLText( $lockName ) { throw new RuntimeException( 'locking must be implemented in subclasses' ); } public function unlockSQLText( $lockName ) { throw new RuntimeException( 'locking must be implemented in subclasses' ); } } PK ! F`�p p rdbms/platform/MySQLPlatform.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\Rdbms\Platform; use Wikimedia\Rdbms\DBLanguageError; use Wikimedia\Rdbms\Query; /** * @since 1.39 * @see ISQLPlatform */ class MySQLPlatform extends SQLPlatform { protected function getIdentifierQuoteChar() { return '`'; } public function buildStringCast( $field ) { return "CAST( $field AS BINARY )"; } /** * @param string $field Field or column to cast * @return string */ public function buildIntegerCast( $field ) { return 'CAST( ' . $field . ' AS SIGNED )'; } protected function normalizeJoinType( string $joinType ) { switch ( strtoupper( $joinType ) ) { case 'STRAIGHT_JOIN': case 'STRAIGHT JOIN': return 'STRAIGHT_JOIN'; default: return parent::normalizeJoinType( $joinType ); } } /** * @param string $index * @return string */ public function useIndexClause( $index ) { return "FORCE INDEX (" . $this->indexName( $index ) . ")"; } /** * @param string $index * @return string */ public function ignoreIndexClause( $index ) { return "IGNORE INDEX (" . $this->indexName( $index ) . ")"; } public function deleteJoinSqlText( $delTable, $joinTable, $delVar, $joinVar, $conds ) { if ( !$conds ) { throw new DBLanguageError( __METHOD__ . ' called with empty $conds' ); } $delTable = $this->tableName( $delTable ); $joinTable = $this->tableName( $joinTable ); $sql = "DELETE $delTable FROM $delTable, $joinTable WHERE $delVar=$joinVar "; if ( $conds != '*' ) { $sql .= ' AND ' . $this->makeList( $conds, self::LIST_AND ); } return $sql; } public function isTransactableQuery( Query $sql ) { return parent::isTransactableQuery( $sql ) && // TODO: Use query verb !preg_match( '/^SELECT\s+(GET|RELEASE|IS_FREE)_LOCK\(/', $sql->getSQL() ); } public function buildExcludedValue( $column ) { /* @see DatabaseMySQL::upsert() */ // Within "INSERT INTO ON DUPLICATE KEY UPDATE" statements: // - MySQL>= 8.0.20 supports and prefers "VALUES ... AS". // - MariaDB >= 10.3.3 supports and prefers VALUE(). // - Both support the old VALUES() function // https://dev.mysql.com/doc/refman/8.0/en/insert-on-duplicate.html // https://mariadb.com/kb/en/insert-on-duplicate-key-update/ return "VALUES($column)"; } public function lockSQLText( $lockName, $timeout ) { $encName = $this->quoter->addQuotes( $this->makeLockName( $lockName ) ); // Unlike NOW(), SYSDATE() gets the time at invocation rather than query start. // The precision argument is silently ignored for MySQL < 5.6 and MariaDB < 5.3. // https://dev.mysql.com/doc/refman/5.6/en/date-and-time-functions.html#function_sysdate // https://dev.mysql.com/doc/refman/5.6/en/fractional-seconds.html return "SELECT IF(GET_LOCK($encName,$timeout),UNIX_TIMESTAMP(SYSDATE(6)),NULL) AS acquired"; } public function lockIsFreeSQLText( $lockName ) { $encName = $this->quoter->addQuotes( $this->makeLockName( $lockName ) ); return "SELECT IS_FREE_LOCK($encName) AS unlocked"; } public function unlockSQLText( $lockName ) { $encName = $this->quoter->addQuotes( $this->makeLockName( $lockName ) ); return "SELECT RELEASE_LOCK($encName) AS released"; } public function makeLockName( $lockName ) { // https://dev.mysql.com/doc/refman/5.7/en/locking-functions.html#function_get-lock // MySQL 5.7+ enforces a 64 char length limit. return ( strlen( $lockName ) > 64 ) ? sha1( $lockName ) : $lockName; } } PK ! %�" �" # rdbms/platform/PostgresPlatform.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\Rdbms\Platform; use Wikimedia\Rdbms\DBLanguageError; use Wikimedia\Rdbms\Query; use Wikimedia\Timestamp\ConvertibleTimestamp; /** * @since 1.39 * @see ISQLPlatform */ class PostgresPlatform extends SQLPlatform { /** @var string */ private $coreSchema; public function limitResult( $sql, $limit, $offset = false ) { return "$sql LIMIT $limit " . ( is_numeric( $offset ) ? " OFFSET {$offset} " : '' ); } public function buildConcat( $stringList ) { return implode( ' || ', $stringList ); } public function timestamp( $ts = 0 ) { $ct = new ConvertibleTimestamp( $ts ); return $ct->getTimestamp( TS_POSTGRES ); } public function buildStringCast( $field ) { return $field . '::text'; } public function implicitOrderby() { return false; } public function getCoreSchema(): string { return $this->coreSchema; } public function setCoreSchema( string $coreSchema ): void { $this->coreSchema = $coreSchema; } public function selectSQLText( $tables, $vars, $conds = '', $fname = __METHOD__, $options = [], $join_conds = [] ) { if ( is_string( $options ) ) { $options = [ $options ]; } // Change the FOR UPDATE option as necessary based on the join conditions. Then pass // to the parent function to get the actual SQL text. // In Postgres when using FOR UPDATE, only the main table and tables that are inner joined // can be locked. That means tables in an outer join cannot be FOR UPDATE locked. Trying to // do so causes a DB error. This wrapper checks which tables can be locked and adjusts it // accordingly. // MySQL uses "ORDER BY NULL" as an optimization hint, but that is illegal in PostgreSQL. if ( is_array( $options ) ) { $forUpdateKey = array_search( 'FOR UPDATE', $options, true ); if ( $forUpdateKey !== false && $join_conds ) { unset( $options[$forUpdateKey] ); $options['FOR UPDATE'] = []; $toCheck = $tables; reset( $toCheck ); while ( $toCheck ) { $alias = key( $toCheck ); $name = $toCheck[$alias]; unset( $toCheck[$alias] ); $hasAlias = !is_numeric( $alias ); if ( !$hasAlias && is_string( $name ) ) { $alias = $name; } if ( !isset( $join_conds[$alias] ) || !preg_match( '/^(?:LEFT|RIGHT|FULL)(?: OUTER)? JOIN$/i', $join_conds[$alias][0] ) ) { if ( is_array( $name ) ) { // It's a parenthesized group, process all the tables inside the group. $toCheck = array_merge( $toCheck, $name ); } else { // Quote alias names so $this->tableName() won't mangle them $options['FOR UPDATE'][] = $hasAlias ? $this->addIdentifierQuotes( $alias ) : $alias; } } } } if ( isset( $options['ORDER BY'] ) && ( $options['ORDER BY'] == 'NULL' || $options['ORDER BY'] == [ 'NULL' ] ) ) { unset( $options['ORDER BY'] ); } } return parent::selectSQLText( $tables, $vars, $conds, $fname, $options, $join_conds ); } protected function makeSelectOptions( array $options ) { $preLimitTail = $postLimitTail = ''; $startOpts = ''; $noKeyOptions = []; foreach ( $options as $key => $option ) { if ( is_numeric( $key ) ) { $noKeyOptions[$option] = true; } } $preLimitTail .= $this->makeGroupByWithHaving( $options ); $preLimitTail .= $this->makeOrderBy( $options ); if ( isset( $options['FOR UPDATE'] ) ) { $postLimitTail .= ' FOR UPDATE OF ' . implode( ', ', array_map( [ $this, 'tableName' ], $options['FOR UPDATE'] ) ); } elseif ( isset( $noKeyOptions['FOR UPDATE'] ) ) { $postLimitTail .= ' FOR UPDATE'; } if ( isset( $noKeyOptions['DISTINCT'] ) || isset( $noKeyOptions['DISTINCTROW'] ) ) { $startOpts .= 'DISTINCT'; } return [ $startOpts, $preLimitTail, $postLimitTail ]; } public function getDatabaseAndTableIdentifier( string $table ) { $components = $this->qualifiedTableComponents( $table ); switch ( count( $components ) ) { case 1: return [ $this->currentDomain->getDatabase(), $components[0] ]; case 2: return [ $this->currentDomain->getDatabase(), $components[1] ]; case 3: return [ $components[0], $components[2] ]; default: throw new DBLanguageError( 'Too many table components' ); } } protected function relationSchemaQualifier() { if ( $this->coreSchema === $this->currentDomain->getSchema() ) { // The schema to be used is now in the search path; no need for explicit qualification return ''; } return parent::relationSchemaQualifier(); } public function buildGroupConcatField( $delim, $tables, $field, $conds = '', $join_conds = [] ) { $fld = "array_to_string(array_agg($field)," . $this->quoter->addQuotes( $delim ) . ')'; return '(' . $this->selectSQLText( $tables, $fld, $conds, static::CALLER_SUBQUERY, [], $join_conds ) . ')'; } public function makeInsertLists( array $rows, $aliasPrefix = '', array $typeByColumn = [] ) { $firstRow = $rows[0]; if ( !is_array( $firstRow ) || !$firstRow ) { throw new DBLanguageError( 'Got an empty row list or empty row' ); } // List of columns that define the value tuple ordering $tupleColumns = array_keys( $firstRow ); $valueTuples = []; foreach ( $rows as $row ) { $rowColumns = array_keys( $row ); // VALUES(...) requires a uniform correspondence of (column => value) if ( $rowColumns !== $tupleColumns ) { throw new DBLanguageError( 'Got row columns (' . implode( ', ', $rowColumns ) . ') ' . 'instead of expected (' . implode( ', ', $tupleColumns ) . ')' ); } // Make the value tuple that defines this row $typedRowValues = []; foreach ( $row as $column => $value ) { $type = $typeByColumn[$column] ?? null; if ( $value === null ) { $typedRowValues[] = 'NULL'; } elseif ( $type !== null ) { $typedRowValues[] = $this->quoter->addQuotes( $value ) . '::' . $type; } else { $typedRowValues[] = $this->quoter->addQuotes( $value ); } } $valueTuples[] = '(' . implode( ',', $typedRowValues ) . ')'; } $magicAliasFields = []; foreach ( $tupleColumns as $column ) { $magicAliasFields[] = $aliasPrefix . $column; } return [ $this->makeList( $tupleColumns, self::LIST_NAMES ), implode( ',', $valueTuples ), $this->makeList( $magicAliasFields, self::LIST_NAMES ) ]; } protected function makeInsertNonConflictingVerbAndOptions() { return [ 'INSERT INTO', 'ON CONFLICT DO NOTHING' ]; } protected function makeUpdateOptionsArray( $options ) { $options = $this->normalizeOptions( $options ); // PostgreSQL doesn't support anything like "ignore" for UPDATE. $options = array_diff( $options, [ 'IGNORE' ] ); return parent::makeUpdateOptionsArray( $options ); } public function isTransactableQuery( Query $sql ) { return parent::isTransactableQuery( $sql ) && !preg_match( '/^SELECT\s+pg_(try_|)advisory_\w+\(/', $sql->getSQL() ); } public function lockSQLText( $lockName, $timeout ) { // http://www.postgresql.org/docs/9.2/static/functions-admin.html#FUNCTIONS-ADVISORY-LOCKS $key = $this->quoter->addQuotes( $this->bigintFromLockName( $lockName ) ); return "SELECT (CASE WHEN pg_try_advisory_lock($key) " . "THEN EXTRACT(epoch from clock_timestamp()) " . "ELSE NULL " . "END) AS acquired"; } public function lockIsFreeSQLText( $lockName ) { // http://www.postgresql.org/docs/9.2/static/functions-admin.html#FUNCTIONS-ADVISORY-LOCKS $key = $this->quoter->addQuotes( $this->bigintFromLockName( $lockName ) ); return "SELECT (CASE(pg_try_advisory_lock($key)) WHEN FALSE THEN FALSE ELSE pg_advisory_unlock($key) END) AS unlocked"; } public function unlockSQLText( $lockName ) { // http://www.postgresql.org/docs/9.2/static/functions-admin.html#FUNCTIONS-ADVISORY-LOCKS $key = $this->quoter->addQuotes( $this->bigintFromLockName( $lockName ) ); return "SELECT pg_advisory_unlock($key) AS released"; } /** * @param string $lockName * @return string Integer */ private function bigintFromLockName( $lockName ) { return \Wikimedia\base_convert( substr( sha1( $lockName ), 0, 15 ), 16, 10 ); } } PK ! 4�"p�, �, ! rdbms/loadmonitor/LoadMonitor.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\Rdbms; use Liuggio\StatsdClient\Factory\StatsdDataFactoryInterface; use Psr\Log\LoggerInterface; use Psr\Log\NullLogger; use RuntimeException; use Wikimedia\ObjectCache\BagOStuff; use Wikimedia\ObjectCache\IStoreKeyEncoder; use Wikimedia\ObjectCache\WANObjectCache; use Wikimedia\Rdbms\Platform\ISQLPlatform; use Wikimedia\ScopedCallback; use Wikimedia\Stats\NullStatsdDataFactory; /** * Basic DB load monitor with no external dependencies * * This uses both local server and local datacenter caches for DB server state information. * * * @ingroup Database */ class LoadMonitor implements ILoadMonitor { /** @var ILoadBalancer */ protected $lb; /** @var BagOStuff */ protected $srvCache; /** @var WANObjectCache */ protected $wanCache; /** @var LoggerInterface */ protected $logger; /** @var StatsdDataFactoryInterface */ protected $statsd; /** @var int|float */ private $maxConnCount; private int $totalConnectionsAdjustment; /** @var float|null */ private $wallClockOverride; /** @var bool Whether the "server states" cache key is in the process of being updated */ private $serverStatesKeyLocked = false; /** Cache key version */ private const VERSION = 3; /** Target time-till-refresh for DB server states */ private const STATE_TARGET_TTL = 10; /** Seconds to persist DB server states on cache (fresh or stale) */ private const STATE_PRESERVE_TTL = 60; /** * @inheritDoc */ public function __construct( ILoadBalancer $lb, BagOStuff $srvCache, WANObjectCache $wCache, $options ) { $this->lb = $lb; $this->srvCache = $srvCache; $this->wanCache = $wCache; $this->logger = new NullLogger(); $this->statsd = new NullStatsdDataFactory(); if ( isset( $options['maxConnCount'] ) ) { $this->maxConnCount = (int)( $options['maxConnCount'] ); } else { $this->maxConnCount = INF; } $this->totalConnectionsAdjustment = (int)( $options['totalConnectionsAdjustment'] ?? 10 ); } public function setLogger( LoggerInterface $logger ) { $this->logger = $logger; } public function setStatsdDataFactory( StatsdDataFactoryInterface $statsFactory ) { $this->statsd = $statsFactory; } public function scaleLoads( array &$weightByServer ) { if ( count( $weightByServer ) <= 1 ) { // Single-server group; relative adjustments are pointless return; } $serverIndexes = array_keys( $weightByServer ); $stateByServerIndex = $this->getServerStates( $serverIndexes ); $totalConnections = 0; $totalWeights = 0; $circuitBreakingEnabled = true; foreach ( $weightByServer as $i => $weight ) { $serverState = $stateByServerIndex[$i]; $totalConnections += (int)$serverState[self::STATE_CONN_COUNT] * $serverState[self::STATE_UP]; $totalWeights += $weight; // Set up circuit breaking. If at least one replica can take more connections // allow the flow. if ( $serverState[self::STATE_UP] && $weight > 0 && $serverState[self::STATE_CONN_COUNT] < $this->maxConnCount ) { $circuitBreakingEnabled = false; } } if ( $circuitBreakingEnabled ) { throw new DBUnexpectedError( null, 'Database servers in ' . $this->lb->getClusterName() . ' are overloaded. ' . 'In order to protect application servers, the circuit breaking to databases of this section ' . 'have been activated. Please try again a few seconds.' ); } foreach ( $weightByServer as $i => $weight ) { if ( // host is down or !$stateByServerIndex[$i][self::STATE_UP] || // host is primary or explicitly set to zero $weight <= 0 ) { $weightByServer[$i] = 0; continue; } $connRatio = $stateByServerIndex[$i][self::STATE_CONN_COUNT] / ( $totalConnections + $this->totalConnectionsAdjustment ); $weightRatio = $weight / $totalWeights; $diffRatio = $connRatio - $weightRatio; $adjustedRatio = max( $weightRatio - ( $diffRatio / 2.0 ), 0 ); $weightByServer[$i] = (int)round( $totalWeights * $adjustedRatio ); } } protected function getServerStates( array $serverIndexes ): array { $stateByServerIndex = array_fill_keys( $serverIndexes, null ); // Perform any cache regenerations in randomized order so that the // DB servers will each have similarly up-to-date state cache entries. $shuffledServerIndexes = $serverIndexes; shuffle( $shuffledServerIndexes ); foreach ( $shuffledServerIndexes as $i ) { $key = $this->makeStateKey( $this->srvCache, $i ); $state = $this->srvCache->get( $key ) ?: null; if ( $this->isStateFresh( $state ) ) { $this->logger->debug( __METHOD__ . ": fresh local cache hit for '{db_server}'", [ 'db_server' => $this->lb->getServerName( $i ) ] ); } else { $lock = $this->srvCache->getScopedLock( $key, 0, 10 ); if ( $lock || !$state ) { $state = $this->getStateFromWanCache( $i, $state ); $this->srvCache->set( $key, $state, self::STATE_PRESERVE_TTL ); } } $stateByServerIndex[$i] = $state; } return $stateByServerIndex; } protected function getStateFromWanCache( $i, ?array $srvPrevState ) { $hit = true; $key = $this->makeStateKey( $this->wanCache, $i ); $state = $this->wanCache->getWithSetCallback( $key, self::STATE_PRESERVE_TTL, function ( $wanPrevState ) use ( $srvPrevState, $i, &$hit ) { $prevState = $wanPrevState ?: $srvPrevState ?: null; $hit = false; return $this->computeServerState( $i, $prevState ); }, [ 'lockTSE' => 30 ] ); if ( $hit ) { $this->logger->debug( __METHOD__ . ": WAN cache hit for '{db_server}'", [ 'db_server' => $this->lb->getServerName( $i ) ] ); } else { $this->logger->info( __METHOD__ . ": mutex acquired; regenerated cache for '{db_server}'", [ 'db_server' => $this->lb->getServerName( $i ) ] ); } return $state; } protected function makeStateKey( IStoreKeyEncoder $cache, int $i ) { return $cache->makeGlobalKey( 'rdbms-gauge', self::VERSION, $this->lb->getClusterName(), $this->lb->getServerName( ServerInfo::WRITER_INDEX ), $this->lb->getServerName( $i ) ); } /** * @param int $i * @param array|null $previousState * @return array<string,mixed> * @phan-return array{up:float,conn_count:float|int|false,time:float} * @throws DBAccessError */ protected function computeServerState( int $i, ?array $previousState ) { $startTime = $this->getCurrentTime(); // Double check for circular recursion in computeServerStates()/getWeightScale(). // Mainly, connection attempts should use LoadBalancer::getServerConnection() // rather than something that will pick a server based on the server states. $this->acquireServerStatesLoopGuard(); $cluster = $this->lb->getClusterName(); $serverName = $this->lb->getServerName( $i ); $statServerName = str_replace( '.', '_', $serverName ); $newState = $this->newInitialServerState(); if ( $this->lb->getServerInfo( $i )['load'] <= 0 ) { // Callers only use this server when they have *no choice* anyway (e.g. primary) $newState[self::STATE_AS_OF] = $this->getCurrentTime(); // Avoid connecting, especially since it might reside in a remote datacenter return $newState; } // Get a new, untracked, connection in order to gauge server health $flags = ILoadBalancer::CONN_UNTRACKED_GAUGE | ILoadBalancer::CONN_SILENCE_ERRORS; // Get a connection to this server without triggering other server connections $conn = $this->lb->getServerConnection( $i, ILoadBalancer::DOMAIN_ANY, $flags ); // Determine the number of open connections in this server if ( $conn ) { try { $connCount = $this->getConnCountForDb( $conn ); } catch ( DBError $e ) { $connCount = false; } } else { $connCount = false; } // Only keep one connection open at a time if ( $conn ) { $conn->close( __METHOD__ ); } $endTime = $this->getCurrentTime(); $newState[self::STATE_AS_OF] = $endTime; $newState[self::STATE_CONN_COUNT] = $connCount; $newState[self::STATE_UP] = $conn ? 1.0 : 0.0; if ( $previousState ) { $newState[self::STATE_CONN_COUNT] = ( $previousState[self::STATE_CONN_COUNT] + $connCount ) / 2; } if ( $connCount === false ) { $this->logger->error( __METHOD__ . ": host {db_server} is not up?", [ 'db_server' => $serverName ] ); } else { $this->statsd->timing( "loadbalancer.connCount.$cluster.$statServerName", $connCount ); if ( $connCount > $this->maxConnCount ) { $this->logger->warning( "Server {db_server} has {conn_count} open connections (>= {max_conn})", [ 'db_server' => $serverName, 'conn_count' => $connCount, 'max_conn' => $this->maxConnCount ] ); } } return $newState; } /** * @return array<string,mixed> * @phan-return array{up:float,conn_count:int|int|false,time:float} */ protected function newInitialServerState() { return [ // Moving average of connectivity; treat as good self::STATE_UP => 1.0, // Number of connections to that replica; treat as none self::STATE_CONN_COUNT => 0, // UNIX timestamp of state generation completion; treat as "outdated" self::STATE_AS_OF => 0.0, ]; } /** * @param array|null $state * @return bool */ private function isStateFresh( $state ) { if ( !$state ) { return false; } return $this->getCurrentTime() - $state[self::STATE_AS_OF] > self::STATE_TARGET_TTL; } /** * @return ScopedCallback */ private function acquireServerStatesLoopGuard() { if ( $this->serverStatesKeyLocked ) { throw new RuntimeException( "Circular recursion detected while regenerating server states cache. " . "This may indicate improper connection handling in " . get_class( $this ) ); } $this->serverStatesKeyLocked = true; // lock return new ScopedCallback( function () { $this->serverStatesKeyLocked = false; // unlock } ); } /** * @return float UNIX timestamp * @codeCoverageIgnore */ protected function getCurrentTime() { return $this->wallClockOverride ?: microtime( true ); } /** * @param float|null &$time Mock UNIX timestamp for testing * @codeCoverageIgnore */ public function setMockTime( &$time ) { $this->wallClockOverride =& $time; } private function getConnCountForDb( IDatabase $conn ): int { if ( $conn->getType() !== 'mysql' ) { return 0; } $query = new Query( 'SELECT COUNT(*) AS pcount FROM INFORMATION_SCHEMA.PROCESSLIST', ISQLPlatform::QUERY_SILENCE_ERRORS | ISQLPlatform::QUERY_IGNORE_DBO_TRX | ISQLPlatform::QUERY_CHANGE_NONE, 'SELECT', null, 'SELECT COUNT(*) AS pcount FROM INFORMATION_SCHEMA.PROCESSLIST' ); $res = $conn->query( $query, __METHOD__ ); $row = $res ? $res->fetchObject() : false; return $row ? (int)$row->pcount : 0; } } PK ! R�:� � % rdbms/loadmonitor/LoadMonitorNull.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\Rdbms; /** * @ingroup Database */ class LoadMonitorNull extends LoadMonitor { public function scaleLoads( array &$weightByServer ) { } } PK ! �J9� � " rdbms/loadmonitor/ILoadMonitor.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\Rdbms; use Psr\Log\LoggerAwareInterface; use Wikimedia\ObjectCache\BagOStuff; use Wikimedia\ObjectCache\WANObjectCache; use Wikimedia\Stats\StatsdAwareInterface; /** * Database load monitoring interface * * @internal This class should not be called outside of LoadBalancer * @ingroup Database */ interface ILoadMonitor extends LoggerAwareInterface, StatsdAwareInterface { public const STATE_UP = 'up'; public const STATE_CONN_COUNT = 'conn_count'; public const STATE_AS_OF = 'time'; /** * Construct a new LoadMonitor with a given LoadBalancer parent * * @param ILoadBalancer $lb LoadBalancer this instance serves * @param BagOStuff $sCache Local server memory cache * @param WANObjectCache $wCache Local cluster memory cache * @param array $options Additional parameters include: * - maxConnCount: maximum number of connections before circuit breaking to kick in [default: infinity] */ public function __construct( ILoadBalancer $lb, BagOStuff $sCache, WANObjectCache $wCache, $options ); /** * Perform load ratio adjustment before deciding which server to use * * @param array<int,int|float> &$weightByServer Map of (server index => weight) */ public function scaleLoads( array &$weightByServer ); } PK ! E��` ` - rdbms/connectionmanager/ConnectionManager.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\Rdbms; use InvalidArgumentException; /** * Database connection manager. * * This manages access to primary and replica databases. * * @since 1.29 * @ingroup Database * @author Addshore */ class ConnectionManager { /** * @var ILoadBalancer */ private $loadBalancer; /** * The symbolic name of the target database, or false for the local wiki's database. * * @var string|false */ private $domain; /** * @var string[] */ private $groups = []; /** * @param ILoadBalancer $loadBalancer * @param string|false $domain Optional logical DB name, defaults to current wiki. * This follows the convention for database names used by $loadBalancer. * @param string[] $groups see LoadBalancer::getConnection * * @throws InvalidArgumentException */ public function __construct( ILoadBalancer $loadBalancer, $domain = false, array $groups = [] ) { if ( !is_string( $domain ) && $domain !== false ) { throw new InvalidArgumentException( '$dbName must be a string, or false.' ); } $this->loadBalancer = $loadBalancer; $this->domain = $domain; $this->groups = $groups; } /** * @param int $i * @param string[]|null $groups * @param int $flags * @return IDatabase */ private function getConnection( $i, ?array $groups = null, int $flags = 0 ) { $groups ??= $this->groups; return $this->loadBalancer->getConnection( $i, $groups, $this->domain, $flags ); } /** * Returns a connection to the primary DB, for updating. * * @since 1.29 * @since 1.37 Added optional $flags parameter * @param int $flags * @return IDatabase */ public function getWriteConnection( int $flags = 0 ) { return $this->getConnection( DB_PRIMARY, null, $flags ); } /** * Returns a database connection for reading. * * @since 1.29 * @since 1.37 Added optional $flags parameter * @param string[]|null $groups * @param int $flags * @return IReadableDatabase */ public function getReadConnection( ?array $groups = null, int $flags = 0 ) { $groups ??= $this->groups; return $this->getConnection( DB_REPLICA, $groups, $flags ); } } PK ! q���� � > rdbms/connectionmanager/SessionConsistentConnectionManager.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\Rdbms; /** * Database connection manager. * * This manages access to primary and replica databases. It also manages state that indicates whether * the replica databases are possibly outdated after a write operation, and thus the primary database * should be used for subsequent read operations. * * @note: Services that access overlapping sets of database tables, or interact with logically * related sets of data in the database, should share a SessionConsistentConnectionManager. * Services accessing unrelated sets of information may prefer to not share a * SessionConsistentConnectionManager, so they can still perform read operations against replica * databases after a (unrelated, per the assumption) write operation to the primary database. * Generally, sharing a SessionConsistentConnectionManager improves consistency (by avoiding race * conditions due to replication lag), but can reduce performance (by directing more read * operations to the primary database server). * * @since 1.29 * @ingroup Database * @author Daniel Kinzler * @author Addshore */ class SessionConsistentConnectionManager extends ConnectionManager { /** * @var bool */ private $forceWriteConnection = false; /** * Forces all future calls to getReadConnection() to return a write connection. * Use this before performing read operations that are critical for a future update. * * @since 1.29 */ public function prepareForUpdates() { $this->forceWriteConnection = true; } /** * @since 1.29 * @since 1.37 Added optional $flags parameter * * @param string[]|null $groups * @param int $flags * * @return IReadableDatabase */ public function getReadConnection( ?array $groups = null, int $flags = 0 ) { if ( $this->forceWriteConnection ) { return parent::getWriteConnection( $flags ); } return parent::getReadConnection( $groups, $flags ); } /** * @since 1.29 * @since 1.37 Added optional $flags parameter * * @param int $flags * * @return IDatabase */ public function getWriteConnection( int $flags = 0 ) { $this->prepareForUpdates(); return parent::getWriteConnection( $flags ); } } PK ! ���� � 4 rdbms/database/resultwrapper/MysqliResultWrapper.phpnu �Iw�� <?php namespace Wikimedia\Rdbms; use mysqli_result; class MysqliResultWrapper extends ResultWrapper { /** @var DatabaseMySQL */ private $db; /** @var mysqli_result|null */ private $result; /** * @internal * @param DatabaseMySQL $db * @param mysqli_result $result */ public function __construct( DatabaseMySQL $db, mysqli_result $result ) { $this->db = $db; $this->result = $result; } protected function doNumRows() { // We are not checking for any errors here, since // there are no errors mysql_num_rows can cause. // See https://dev.mysql.com/doc/refman/5.7/en/mysql-fetch-row.html. // See https://phabricator.wikimedia.org/T44430 return $this->result->num_rows; } private function checkFetchError() { $errno = $this->db->lastErrno(); // Unfortunately, mysql_fetch_array does not reset the last errno. // Only check for CR_SERVER_LOST and CR_UNKNOWN_ERROR, as // these are the only errors mysql_fetch_array can cause. // See https://dev.mysql.com/doc/refman/5.7/en/mysql-fetch-row.html. if ( $errno == 2000 || $errno == 2013 ) { throw new DBUnexpectedError( $this->db, 'Error in fetchRow(): ' . htmlspecialchars( $this->db->lastError() ) ); } } protected function doFetchObject() { $object = $this->result->fetch_object(); $this->checkFetchError(); if ( $object === null ) { return false; } return $object; } protected function doFetchRow() { $array = $this->result->fetch_array(); $this->checkFetchError(); if ( $array === null ) { return false; } return $array; } protected function doSeek( $pos ) { $this->result->data_seek( $pos ); } protected function doFree() { $this->result = null; } protected function doGetFieldNames() { $names = []; foreach ( $this->result->fetch_fields() as $fieldInfo ) { $names[] = $fieldInfo->name; } return $names; } /** * Get information about a field in the result set * * @param string $fieldName * @return bool|MySQLField * @internal For DatabaseMySQL::fieldInfo() only * */ public function getInternalFieldInfo( $fieldName ) { for ( $i = 0; $i < $this->result->field_count; $i++ ) { $meta = $this->result->fetch_field_direct( $i ); if ( $fieldName == $meta->name ) { // Add missing properties to result (using flags property) // which will be part of function mysql-fetch-field for backward compatibility $meta->not_null = $meta->flags & MYSQLI_NOT_NULL_FLAG; $meta->primary_key = $meta->flags & MYSQLI_PRI_KEY_FLAG; $meta->unique_key = $meta->flags & MYSQLI_UNIQUE_KEY_FLAG; $meta->multiple_key = $meta->flags & MYSQLI_MULTIPLE_KEY_FLAG; $meta->binary = $meta->flags & MYSQLI_BINARY_FLAG; $meta->numeric = $meta->flags & MYSQLI_NUM_FLAG; $meta->blob = $meta->flags & MYSQLI_BLOB_FLAG; $meta->unsigned = $meta->flags & MYSQLI_UNSIGNED_FLAG; $meta->zerofill = $meta->flags & MYSQLI_ZEROFILL_FLAG; return new MySQLField( $meta ); } } return false; } } PK ! ��D D / rdbms/database/resultwrapper/IResultWrapper.phpnu �Iw�� <?php namespace Wikimedia\Rdbms; use Countable; use OutOfBoundsException; use SeekableIterator; use stdClass; /** * Result wrapper for grabbing data queried from an IDatabase object * * Note that using the Iterator methods in combination with the non-Iterator * DB result iteration functions may cause rows to be skipped or repeated. * * By default, this will use the iteration methods of the IDatabase handle if provided. * Subclasses can override methods to make it solely work on the result resource instead. * If no database is provided, and the subclass does not override the DB iteration methods, * then a RuntimeException will be thrown when iteration is attempted. * * The result resource field should not be accessed from non-Database related classes. * It is database class specific and is stored here to associate iterators with queries. * * @ingroup Database */ interface IResultWrapper extends Countable, SeekableIterator { /** * Get the number of rows in a result object * * @return int */ public function numRows(); /** * Get the number of rows in a result object * * @return int */ public function count(): int; /** * Fetch the next row from the given result object, in object form. Fields can be retrieved with * $row->fieldname, with fields acting like member variables. If no more rows are available, * false is returned. * * @return stdClass|false * @throws DBUnexpectedError Thrown if the database returns an error */ public function fetchObject(); /** * Fetch the next row from the given result object, in associative array form. Fields are * retrieved with $row['fieldname']. If no more rows are available, false is returned. * * @return array|false * @throws DBUnexpectedError Thrown if the database returns an error */ public function fetchRow(); /** * Change the position of the cursor in a result object. * See mysql_data_seek() * * @throws OutOfBoundsException * @param int $pos */ public function seek( $pos ): void; /** * Free a result object * * This either saves memory in PHP (buffered queries) or on the server (unbuffered queries). * In general, queries are not large enough in result sets for this to be worth calling. */ public function free(); /** * @return stdClass|array|false */ #[\ReturnTypeWillChange] public function current(); /** * @return int */ public function key(): int; /** * @return void */ public function next(): void; /** * Get the names of the fields in the result * * @since 1.37 * @return string[] */ public function getFieldNames(); } PK ! �3͂ � 2 rdbms/database/resultwrapper/FakeResultWrapper.phpnu �Iw�� <?php namespace Wikimedia\Rdbms; use RuntimeException; use stdClass; /** * Overloads the relevant methods of the real ResultWrapper so it * doesn't go anywhere near an actual database. */ class FakeResultWrapper extends ResultWrapper { /** @var stdClass[]|array[]|null */ protected $result; /** * @param stdClass[]|array[]|FakeResultWrapper $result */ public function __construct( $result ) { if ( $result instanceof self ) { $this->result = $result->result; } else { $this->result = $result; } } protected function doNumRows() { return count( $this->result ); } protected function doFetchObject() { $value = $this->result[$this->currentPos] ?? false; return is_array( $value ) ? (object)$value : $value; } protected function doFetchRow() { $row = $this->doFetchObject(); return is_object( $row ) ? get_object_vars( $row ) : $row; } protected function doSeek( $pos ) { } protected function doFree() { $this->result = null; } protected function doGetFieldNames() { // @phan-suppress-previous-line PhanPluginNeverReturnMethod throw new RuntimeException( __METHOD__ . ' is unimplemented' ); } } PK ! �kOi i 4 rdbms/database/resultwrapper/SqliteResultWrapper.phpnu �Iw�� <?php namespace Wikimedia\Rdbms; use ArrayIterator; use PDO; use PDOStatement; class SqliteResultWrapper extends ResultWrapper { /** @var PDOStatement|null */ private $result; /** @var ArrayIterator|null */ private $rows; /** * @internal * @param PDOStatement $result */ public function __construct( PDOStatement $result ) { $this->result = $result; // SQLite doesn't allow buffered results or data seeking etc, so we'll // use fetchAll. PDO has PDO::CURSOR_SCROLL but the SQLite C API doesn't // support it, so the driver raises an error if it is used. $this->rows = $result->fetchAll( PDO::FETCH_OBJ ); } protected function doNumRows() { return count( $this->rows ); } protected function doFetchObject() { return $this->rows[$this->currentPos] ?? false; } protected function doFetchRow() { $obj = $this->doFetchObject(); if ( is_object( $obj ) ) { $i = 0; $row = get_object_vars( $obj ); foreach ( $row as $value ) { $row[$i++] = $value; } return $row; } else { return $obj; } } protected function doSeek( $pos ) { // Nothing to do -- parent updates $this->currentPos } protected function doFree() { $this->rows = null; $this->result = null; } protected function doGetFieldNames() { if ( $this->rows ) { return array_keys( get_object_vars( $this->rows[0] ) ); } else { return []; } } } PK ! -~��? ? . rdbms/database/resultwrapper/ResultWrapper.phpnu �Iw�� <?php namespace Wikimedia\Rdbms; use OutOfBoundsException; use stdClass; /** * Result wrapper for grabbing data queried from an IDatabase object * * Only IDatabase-related classes should construct these. Other code may * use the FakeResultWrapper class for convenience or compatibility shims. * * Note that using the Iterator methods in combination with the non-Iterator * IDatabase result iteration functions may cause rows to be skipped or repeated. * * By default, this will use the iteration methods of the IDatabase handle if provided. * Subclasses can override methods to make it solely work on the result resource instead. * * @ingroup Database */ abstract class ResultWrapper implements IResultWrapper { /** * @var int The offset of the row that would be returned by the next call * to fetchObject(). */ protected $nextPos = 0; /** * @var int The offset of the current row that would be returned by current() * and may have been previously returned by fetchObject(). */ protected $currentPos = 0; /** * @var stdClass|array|bool|null The row at $this->currentPos, or null if it has * not yet been retrieved, or false if the current row was past the end. */ protected $currentRow; /** * @var string[]|null Cache of field names */ private $fieldNames; /** * Get the number of rows in the result set * * @since 1.37 * @return int */ abstract protected function doNumRows(); /** * Get the next row as a stdClass object, or false if iteration has * proceeded past the end. The offset within the result set is in * $this->currentPos. * * @since 1.37 * @return stdClass|bool */ abstract protected function doFetchObject(); /** * Get the next row as an array containing the data duplicated, once with * string keys and once with numeric keys, per the PDO::FETCH_BOTH * convention. Or false if iteration has proceeded past the end. * * @return array|bool */ abstract protected function doFetchRow(); /** * Modify the current cursor position to the row with the specified offset. * If $pos is out of bounds, the behaviour is undefined. * * @param int $pos */ abstract protected function doSeek( $pos ); /** * Free underlying data. It is not necessary to do anything. */ abstract protected function doFree(); /** * Get the field names in the result set. * * @return string[] */ abstract protected function doGetFieldNames(); public function numRows() { return $this->doNumRows(); } public function count(): int { return $this->doNumRows(); } public function fetchObject() { $this->currentPos = $this->nextPos++; $this->currentRow = $this->doFetchObject(); return $this->currentRow; } public function fetchRow() { $this->currentPos = $this->nextPos++; $this->currentRow = $this->doFetchRow(); return $this->currentRow; } public function seek( $pos ): void { $numRows = $this->numRows(); // Allow seeking to zero if there are no results $max = $numRows ? $numRows - 1 : 0; if ( $pos < 0 || $pos > $max ) { throw new OutOfBoundsException( __METHOD__ . ': invalid position' ); } if ( $numRows ) { $this->doSeek( $pos ); } $this->nextPos = $pos; $this->currentPos = $pos; $this->currentRow = null; } public function free() { $this->doFree(); $this->currentRow = false; } public function rewind(): void { $this->seek( 0 ); } #[\ReturnTypeWillChange] public function current() { $this->currentRow ??= $this->fetchObject(); return $this->currentRow; } public function key(): int { return $this->currentPos; } public function next(): void { $this->fetchObject(); } public function valid(): bool { return $this->currentPos >= 0 && $this->currentPos < $this->numRows(); } public function getFieldNames() { $this->fieldNames ??= $this->doGetFieldNames(); return $this->fieldNames; } } PK ! 4tt� � 6 rdbms/database/resultwrapper/PostgresResultWrapper.phpnu �Iw�� <?php namespace Wikimedia\Rdbms; // Phan insists these are resources until we drop PHP 7.4 /* @phan-file-suppress PhanTypeMismatchArgumentInternal */ class PostgresResultWrapper extends ResultWrapper { /** @var DatabasePostgres */ private $db; /** @var resource */ private $handle; /** @var resource */ private $result; /** * @internal * @param DatabasePostgres $db * @param resource $handle * @param resource $result */ public function __construct( DatabasePostgres $db, $handle, $result ) { $this->db = $db; $this->handle = $handle; $this->result = $result; } protected function doNumRows() { return pg_num_rows( $this->result ); } protected function doFetchObject() { // pg_fetch_object may raise a warning after a seek to an invalid offset // phpcs:ignore Generic.PHP.NoSilencedErrors.Discouraged $row = @pg_fetch_object( $this->result ); // Map boolean values (T352229) if ( is_object( $row ) ) { $numFields = pg_num_fields( $this->result ); for ( $i = 0; $i < $numFields; $i++ ) { if ( pg_field_type( $this->result, $i ) === 'bool' ) { $name = pg_field_name( $this->result, $i ); $row->$name = $this->convertBoolean( $row->$name ); } } } return $row; } protected function doFetchRow() { // phpcs:ignore Generic.PHP.NoSilencedErrors.Discouraged $row = @pg_fetch_array( $this->result ); // Map boolean values (T352229) if ( is_array( $row ) ) { $numFields = pg_num_fields( $this->result ); for ( $i = 0; $i < $numFields; $i++ ) { if ( pg_field_type( $this->result, $i ) === 'bool' ) { $name = pg_field_name( $this->result, $i ); $row[$i] = $this->convertBoolean( $row[$i] ); $row[$name] = $this->convertBoolean( $row[$name] ); } } } return $row; } /** * Convert a boolean value from the database to the string '0' or '1' for * compatibility with MySQL. * * @param mixed $value * @return mixed */ private function convertBoolean( $value ) { if ( $value === 't' ) { return '1'; } elseif ( $value === 'f' ) { return '0'; } else { // Just pass through values that are not 't' or 'f' return $value; } } protected function doSeek( $pos ) { pg_result_seek( $this->result, $pos ); } protected function doFree() { return pg_free_result( $this->result ); } protected function doGetFieldNames() { $names = []; $n = pg_num_fields( $this->result ); for ( $i = 0; $i < $n; $i++ ) { $names[] = pg_field_name( $this->result, $i ); } return $names; } } PK ! ��H� k k $ rdbms/database/IReadableDatabase.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\Rdbms; use stdClass; use Stringable; use Wikimedia\Rdbms\Database\DbQuoter; use Wikimedia\Rdbms\Database\IDatabaseFlags; use Wikimedia\Rdbms\Platform\ISQLPlatform; // Very long type annotations :( // phpcs:disable Generic.Files.LineLength /** * A database connection without write operations. * * @since 1.40 * @ingroup Database */ interface IReadableDatabase extends Stringable, ISQLPlatform, DbQuoter, IDatabaseFlags { /** Parameter to unionQueries() for UNION ALL */ public const UNION_ALL = true; /** Parameter to unionQueries() for UNION DISTINCT */ public const UNION_DISTINCT = false; /** * Get a human-readable string describing the current software version * * Use getServerVersion() to get machine-friendly information. * * @return string Version information from the database server */ public function getServerInfo(); /** * Get/set the table prefix * * @param string|null $prefix The table prefix to set, or omitted to leave it unchanged * @return string The previous table prefix */ public function tablePrefix( $prefix = null ); /** * Get/set the db schema * * @param string|null $schema The database schema to set, or omitted to leave it unchanged * @return string The previous db schema */ public function dbSchema( $schema = null ); /** * @return bool Whether a connection to the database open */ public function isOpen(); /** * Return the currently selected domain ID * * Null components (database/schema) might change once a connection is established * * @return string */ public function getDomainID(); /** * Get the RDBMS type of the server (e.g. "mysql", "sqlite") * * @return string */ public function getType(); /** * Get the RDBMS-specific error code from the last attempted query statement * * @return int|string Error code (integer or hexadecimal depending on RDBMS type) */ public function lastErrno(); /** * Get the RDBMS-specific error description from the last attempted query statement * * @return string */ public function lastError(); /** * Returns a wikitext style link to the DB's website (e.g. "[https://www.mysql.com/ MySQL]") * * Should at least contain plain text, if for some reason your database has no website. * * @return string Wikitext of a link to the server software's web site */ public function getSoftwareLink(); /** * A string describing the current software version * * @return string Version information from the database server. */ public function getServerVersion(); /** * Close the database connection * * This should only be called after any transactions have been resolved, * aside from read-only automatic transactions (assuming no callbacks are registered). * If a transaction is still open anyway, it will be rolled back. * * @internal Only for use by LoadBalancer * * @param string $fname Caller name @phan-mandatory-param * @return bool Success * @throws DBError */ public function close( $fname = __METHOD__ ); /** * Create an empty SelectQueryBuilder which can be used to run queries * against this connection. * * @note A new query builder must be created per query. Query builders * should not be reused since this uses a fluent interface and the state of * the builder changes during the query which may cause unexpected results. * * @return SelectQueryBuilder */ public function newSelectQueryBuilder(): SelectQueryBuilder; /** * Create an empty UnionQueryBuilder which can be used to run queries * against this connection. * * @note A new query builder must be created per query. Query builders * should not be reused since this uses a fluent interface and the state of * the builder changes during the query which may cause unexpected results. * * @since 1.41 * @return UnionQueryBuilder */ public function newUnionQueryBuilder(): UnionQueryBuilder; /** * A SELECT wrapper which returns a single field from a single result row * * If no result rows are returned from the query, false is returned. * * New callers should use {@link newSelectQueryBuilder} with {@link SelectQueryBuilder::fetchField} * instead, which is more readable and less error-prone. * * @internal callers outside of rdbms library should use SelectQueryBuilder instead. * * @param string|array $tables Table reference(s), using the unqualified name of tables * or of the form "information_schema.<identifier>". {@see select} for details. * @param-taint $tables exec_sql * @param string|array $var The field name to select. This must be a valid SQL fragment: do not * use unvalidated user input. Can be an array, but must contain exactly 1 element then. * {@see select} for details. * @param-taint $var exec_sql * @param string|IExpression|array<string,?scalar|non-empty-array<int,?scalar>|RawSQLValue>|array<int,string|IExpression> $cond * The condition array. {@see select} for details. * @param-taint $cond exec_sql_numkey * @param string $fname The function name of the caller. @phan-mandatory-param * @param-taint $fname exec_sql * @param string|array $options The query options. {@see select} for details. * @param-taint $options none This is special-cased in MediaWikiSecurityCheckPlugin * @param string|array $join_conds The query join conditions. {@see select} for details. * @param-taint $join_conds none This is special-cased in MediaWikiSecurityCheckPlugin * @return mixed|false The value from the field, or false if nothing was found * @return-taint tainted * @throws DBError If an error occurs, {@see query} */ public function selectField( $tables, $var, $cond = '', $fname = __METHOD__, $options = [], $join_conds = [] ); /** * A SELECT wrapper which returns a list of single field values from result rows * * If no result rows are returned from the query, an empty array is returned. * * New callers should use {@link newSelectQueryBuilder} with {@link SelectQueryBuilder::fetchFieldValues} * instead, which is more readable and less error-prone. * * @internal callers outside of rdbms library should use SelectQueryBuilder instead. * * @param string|array $tables Table reference(s), using the unqualified name of tables * or of the form "information_schema.<identifier>". {@see select} for details. * @param-taint $tables exec_sql * @param string $var The field name to select. This must be a valid SQL * fragment: do not use unvalidated user input. * @param-taint $var exec_sql * @param string|IExpression|array<string,?scalar|non-empty-array<int,?scalar>|RawSQLValue>|array<int,string|IExpression> $cond * The condition array. {@see select} for details. * @param-taint $cond exec_sql_numkey * @param string $fname The function name of the caller. @phan-mandatory-param * @param-taint $fname exec_sql * @param string|array $options The query options. {@see select} for details. * @param-taint $options none This is special-cased in MediaWikiSecurityCheckPlugin * @param string|array $join_conds The query join conditions. {@see select} for details. * @param-taint $join_conds none This is special-cased in MediaWikiSecurityCheckPlugin * * @return array The values from the field in the order they were returned from the DB * @return-taint tainted * @throws DBError If an error occurs, {@see query} * @since 1.25 */ public function selectFieldValues( $tables, $var, $cond = '', $fname = __METHOD__, $options = [], $join_conds = [] ): array; /** * Execute a SELECT query constructed using the various parameters provided * * New callers should use {@link newSelectQueryBuilder} with {@link SelectQueryBuilder::fetchResultSet} * instead, which is more readable and less error-prone. * * @param string|array $tables Table reference(s), using the unqualified name of tables * or of the form "information_schema.<identifier>". * @param-taint $tables exec_sql * * Each table reference assigns a table name to a specified collection of rows * for the context of the query (e.g. field expressions, WHERE clause, GROUP BY * clause, HAVING clause, ect...). Use of multiple table references implies a JOIN. * * If a string is given, it must hold the name of the table having the specified * collection of rows. If an array is given, each entry must be one of the following: * - A string holding the name of the existing table which has the collection * of rows. If keyed by a string, the key will be the assigned table name. * - A Subquery instance which specifies the collection of rows derived from * a subquery. If keyed by a string, the key will be the assigned table name. * Otherwise, the SQL text of the subquery will be the assigned table name. * - An array specifying the collection of rows derived from a parenthesized * JOIN. It must be keyed by a string, which will be used as the assigned * table name. * * String keys allow table aliases to be specified, for example: * * [ 'a' => 'user' ] * * This includes the user table in the query, with the alias "a" available * for use in field names (e.g. a.user_name). * * A derived table, defined by the result of selectSQLText(), requires an alias * key and a Subquery instance value which wraps the SQL query, for example: * * [ 'c' => new Subquery( 'SELECT ...' ) ] * * Joins using parentheses for grouping (since MediaWiki 1.31) may be * constructed using nested arrays. For example, * * [ 'tableA', 'nestedB' => [ 'tableB', 'b2' => 'tableB2' ] ] * * along with `$join_conds` like * * [ 'b2' => [ 'JOIN', 'b_id = b2_id' ], 'nestedB' => [ 'LEFT JOIN', 'b_a = a_id' ] ] * * will produce SQL something like * * FROM tableA LEFT JOIN (tableB JOIN tableB2 AS b2 ON (b_id = b2_id)) ON (b_a = a_id) * * All of the table names given here are automatically run through * Database::tableName(), which causes the table prefix (if any) to be * added, and various other table name mappings to be performed. * * Do not use untrusted user input as a table name. Alias names should * not have characters outside of the Basic multilingual plane. * * @param string|array $vars Field name(s) * @param-taint $vars exec_sql * * May be either a field name or an array of field names. The field names * can be complete fragments of SQL, for direct inclusion into the SELECT * query. If an array is given, field aliases can be specified, for example: * * [ 'maxrev' => 'MAX(rev_id)' ] * * This includes an expression with the alias "maxrev" in the query. * * If an expression is given, care must be taken to ensure that it is * DBMS-independent. * * Untrusted user input must not be passed to this parameter. * * @param string|IExpression|array<string,?scalar|non-empty-array<int,?scalar>|RawSQLValue>|array<int,string|IExpression> $conds * @param-taint $conds exec_sql_numkey * * May be either a string containing a single condition, or an array of * conditions. If an array is given, the conditions constructed from each * element are combined with AND. * * Array elements may take one of two forms: * * - Elements with a numeric key are interpreted as raw SQL fragments. * - Elements with a string key are interpreted as equality conditions, * where the key is the field name. * - If the value of such an array element is a scalar (such as a * string), it will be treated as data and thus quoted appropriately. * If it is null, an IS NULL clause will be added. * - If the value is an array, an IN (...) clause will be constructed * from its non-null elements, and an IS NULL clause will be added * if null is present, such that the field may match any of the * elements in the array. The non-null elements will be quoted. * * Note that expressions are often DBMS-dependent in their syntax. * DBMS-independent wrappers are provided for constructing several types of * expression commonly used in condition queries. See: * - IDatabase::buildLike() * - IDatabase::conditional() * * Untrusted user input is safe in the values of string keys, however untrusted * input must not be used in the array key names or in the values of numeric keys. * Escaping of untrusted input used in values of numeric keys should be done via * IDatabase::addQuotes() * * Use an empty array, string, or IDatabase::ALL_ROWS to select all rows. * * You *can* put simple join conditions here, but this is strongly discouraged. * Instead of * * // $conds... * 'rev_actor = actor_id', * * use (see below for $join_conds): * * // $join_conds... * 'actor' => [ 'JOIN', 'rev_actor = actor_id' ], * * @param string $fname Caller function name @phan-mandatory-param * @param-taint $fname exec_sql * * @param string|array $options Query options * @param-taint $options none This is special-cased in MediaWikiSecurityCheckPlugin * * Optional: Array of query options. Boolean options are specified by * including them in the array as a string value with a numeric key, for * example: * * [ 'FOR UPDATE' ] * * The supported options are: * * - OFFSET: Skip this many rows at the start of the result set. OFFSET * with LIMIT can theoretically be used for paging through a result set, * but this is discouraged for performance reasons. * * - LIMIT: Integer: return at most this many rows. The rows are sorted * and then the first rows are taken until the limit is reached. LIMIT * is applied to a result set after OFFSET. * * - LOCK IN SHARE MODE: Boolean: lock the returned rows so that they can't be * changed until the next COMMIT. Cannot be used with aggregate functions * (COUNT, MAX, etc., but also DISTINCT). * * - FOR UPDATE: Boolean: lock the returned rows so that they can't be * changed nor read with LOCK IN SHARE MODE until the next COMMIT. * Cannot be used with aggregate functions (COUNT, MAX, etc., but also DISTINCT). * * - DISTINCT: Boolean: return only unique result rows. * * - GROUP BY: May be either an SQL fragment string naming a field or * expression to group by, or an array of such SQL fragments. * * - HAVING: May be either a string containing a HAVING clause or an array of * conditions building the HAVING clause. If an array is given, the conditions * constructed from each element are combined with AND. * * - ORDER BY: May be either an SQL fragment giving a field name or * expression to order by, or an array of such SQL fragments. * * - USE INDEX: This may be either a string giving the index name to use * for the query, or an array. If it is an associative array, each key * gives the table name (or alias), each value gives the index name to * use for that table. All strings are SQL fragments and so should be * validated by the caller. * * - IGNORE INDEX: This may be either be a string giving an index name to * ignore for the query, or an array. If it is an associative array, * each key gives the table name (or alias), each value gives the index * name to ignore for that table. All strings are SQL fragments and so * should be validated by the caller. * * - EXPLAIN: In MySQL, this causes an EXPLAIN SELECT query to be run, * instead of SELECT. * * - MAX_EXECUTION_TIME: (only in MySQL/MariaDB) maximum allowed time to * run the query in milliseconds (if database supports it). * * And also the following boolean MySQL extensions, see the MySQL manual * for documentation: * * - STRAIGHT_JOIN * - SQL_BIG_RESULT * - SQL_BUFFER_RESULT * - SQL_SMALL_RESULT * - SQL_CALC_FOUND_ROWS * * @param string|array $join_conds Join conditions * @param-taint $join_conds none This is special-cased in MediaWikiSecurityCheckPlugin * * Optional associative array of table-specific join conditions. * Simple conditions can also be specified in the regular $conds, * but this is strongly discouraged in favor of the more explicit syntax here. * * The key of the array contains the table name or alias. The value is an * array with two elements, numbered 0 and 1. The first gives the type of * join, the second is the same as the $conds parameter. Thus it can be * an SQL fragment, or an array where the string keys are equality and the * numeric keys are SQL fragments all AND'd together. For example: * * [ 'page' => [ 'LEFT JOIN', 'page_latest=rev_id' ] ] * * @internal * @return IResultWrapper Resulting rows * @return-taint tainted * @throws DBError If an error occurs, {@see query} */ public function select( $tables, $vars, $conds = '', $fname = __METHOD__, $options = [], $join_conds = [] ); /** * Wrapper to IDatabase::select() that only fetches one row (via LIMIT) * * If the query returns no rows, false is returned. * * This method is convenient for fetching a row based on a unique key condition. * * New callers should use {@link newSelectQueryBuilder} with {@link SelectQueryBuilder::fetchRow} * instead, which is more readable and less error-prone. * * @internal * @param string|array $tables Table reference(s), using the unqualified name of tables * or of the form "information_schema.<identifier>". {@see select} for details. * @param-taint $tables exec_sql * @param string|array $vars Field names * @param-taint $vars exec_sql * @param string|IExpression|array<string,?scalar|non-empty-array<int,?scalar>|RawSQLValue>|array<int,string|IExpression> $conds * Conditions * @param-taint $conds exec_sql_numkey * @param string $fname Caller function name @phan-mandatory-param * @param-taint $fname exec_sql * @param string|array $options Query options * @param-taint $options none This is special-cased in MediaWikiSecurityCheckPlugin * @param array|string $join_conds Join conditions * @param-taint $join_conds none This is special-cased in MediaWikiSecurityCheckPlugin * @return stdClass|false * @return-taint tainted * @throws DBError If an error occurs, {@see query} */ public function selectRow( $tables, $vars, $conds, $fname = __METHOD__, $options = [], $join_conds = [] ); /** * Estimate the number of rows in dataset * * MySQL allows you to estimate the number of rows that would be returned * by a SELECT query, using EXPLAIN SELECT. The estimate is provided using * index cardinality statistics, and is notoriously inaccurate, especially * when large numbers of rows have recently been added or deleted. * * For DBMSs that don't support fast result size estimation, this function * will actually perform the SELECT COUNT(*). * * Takes the same arguments as IDatabase::select(). * * New callers should use {@link newSelectQueryBuilder} with {@link SelectQueryBuilder::estimateRowCount} * instead, which is more readable and less error-prone. * * @internal * @param string|string[] $tables Table reference(s), using the unqualified name of tables * or of the form "information_schema.<identifier>". {@see select} for details. * @param string $var Column for which NULL values are not counted [default "*"] * @param string|IExpression|array<string,?scalar|non-empty-array<int,?scalar>|RawSQLValue>|array<int,string|IExpression> $conds * Filters on the table * @param string $fname Function name for profiling @phan-mandatory-param * @param array $options Options for select * @param array|string $join_conds Join conditions * @return int Row count * @throws DBError If an error occurs, {@see query} */ public function estimateRowCount( $tables, $var = '*', $conds = '', $fname = __METHOD__, $options = [], $join_conds = [] ): int; /** * Get the number of rows in dataset * * This is useful when trying to do COUNT(*) but with a LIMIT for performance. * * Takes the same arguments as IDatabase::select(). * * New callers should use {@link newSelectQueryBuilder} with {@link SelectQueryBuilder::fetchRowCount} * instead, which is more readable and less error-prone. * * @since 1.27 Added $join_conds parameter * * @internal * @param string|string[] $tables Table reference(s), using the unqualified name of tables * or of the form "information_schema.<identifier>". {@see select} for details. * @param-taint $tables exec_sql * @param string $var Column for which NULL values are not counted [default "*"] * @param-taint $var exec_sql * @param string|IExpression|array<string,?scalar|non-empty-array<int,?scalar>|RawSQLValue>|array<int,string|IExpression> $conds * Filters on the table * @param-taint $conds exec_sql_numkey * @param string $fname Function name for profiling @phan-mandatory-param * @param-taint $fname exec_sql * @param array $options Options for select * @param-taint $options none This is special-cased in MediaWikiSecurityCheckPlugin * @param array $join_conds Join conditions (since 1.27) * @param-taint $join_conds none This is special-cased in MediaWikiSecurityCheckPlugin * @return int Row count * @return-taint none * @throws DBError If an error occurs, {@see query} */ public function selectRowCount( $tables, $var = '*', $conds = '', $fname = __METHOD__, $options = [], $join_conds = [] ): int; /** * Returns true if DBs are assumed to be on potentially different servers * * In systems like mysql/mariadb, different databases can easily be referenced on a single * connection merely by name, even in a single query via JOIN. On the other hand, Postgres * treats databases as logically separate, with different database users, requiring special * mechanisms like postgres_fdw to "mount" foreign DBs. This is true even among DBs on the * same server. Changing the selected database via selectDomain() requires a new connection. * * @return bool * @since 1.29 */ public function databasesAreIndependent(); /** * Set the current domain (database, schema, and table prefix) * * This will throw an error for some database types if the database is unspecified * * This should only be called by a load balancer or if the handle is not attached to one * * @param string|DatabaseDomain $domain * @throws DBConnectionError If databasesAreIndependent() is true and connection change fails * @throws DBError On query error, if domain changes are disallowed, or the domain is invalid * @since 1.32 */ public function selectDomain( $domain ); /** * Get the current database name; null if there isn't one * * @return string|null */ public function getDBname(); /** * Get the hostname or IP address of the server * * @return string|null */ public function getServer(); /** * Get the readable name for the server * * @return string Readable server name, falling back to the hostname or IP address * @since 1.36 */ public function getServerName(); /** * Ping the server and try to reconnect if it there is no connection * * @return bool Success or failure */ public function ping(); /** * Get the seconds of replication lag on this database server * * Callers should avoid using this method while a transaction is active * * @return float|int|false Database replication lag in seconds or false on error * @throws DBError If an error occurs, {@see query} */ public function getLag(); /** * Get a cached estimate of the seconds of replication lag on this database server, * using the estimate obtained at the start of the current transaction if one is active * * This is useful when transactions might use snapshot isolation (e.g. REPEATABLE-READ in * innodb), so the "real" lag of that data is this lag plus transaction duration. If they * don't, it is still safe to be pessimistic. In AUTOCOMMIT mode, this still gives an * indication of the staleness of subsequent reads. * * @return array ('lag': seconds or false on error, 'since': UNIX timestamp of BEGIN) * @throws DBError If an error occurs, {@see query} * @since 1.27 */ public function getSessionLagStatus(); /** * Some DBMSs have a special format for inserting into blob fields, they * don't allow simple quoted strings to be inserted. To insert into such * a field, pass the data through this function before passing it to * IDatabase::insert(). * * @param string $b * @return string|Blob * @throws DBError */ public function encodeBlob( $b ); /** * Some DBMSs return a special placeholder object representing blob fields * in result objects. Pass the object through this function to return the * original string. * * @param string|Blob $b * @return string * @throws DBError */ public function decodeBlob( $b ); /** * See Expression::__construct() * * @since 1.42 * @param string $field * @param-taint $field exec_sql * @param string $op One of '>', '<', '!=', '=', '>=', '<=', IExpression::LIKE, IExpression::NOT_LIKE * @phan-param '\x3E'|'\x3C'|'!='|'='|'\x3E='|'\x3C='|'LIKE'|'NOT LIKE' $op * @param-taint $op exec_sql * @param ?scalar|RawSQLValue|Blob|LikeValue|non-empty-list<scalar|Blob> $value * @param-taint $value escapes_sql * @return Expression * @phan-side-effect-free */ public function expr( string $field, string $op, $value ): Expression; /** * See Expression::__construct() * * @since 1.43 * @param non-empty-array<string,?scalar|RawSQLValue|Blob|LikeValue|non-empty-list<scalar|Blob>>|non-empty-array<int,IExpression> $conds * @param-taint $conds exec_sql_numkey * @return AndExpressionGroup * @phan-side-effect-free */ public function andExpr( array $conds ): AndExpressionGroup; /** * See Expression::__construct() * * @since 1.43 * @param non-empty-array<string,?scalar|RawSQLValue|Blob|LikeValue|non-empty-list<scalar|Blob>>|non-empty-array<int,IExpression> $conds * @param-taint $conds exec_sql_numkey * @return OrExpressionGroup * @phan-side-effect-free */ public function orExpr( array $conds ): OrExpressionGroup; /** * Get a debugging string that mentions the database type, the ID of this instance, * and the ID of any underlying connection resource or driver object if one is present * * @return string "<db type> object #<X>" or "<db type> object #<X> (resource/handle id #<Y>)" * @since 1.34 */ public function __toString(); } PK ! {'yf yf rdbms/database/DatabaseMySQL.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\Rdbms; use mysqli; use mysqli_result; use RuntimeException; use Wikimedia\AtEase\AtEase; use Wikimedia\IPUtils; use Wikimedia\Rdbms\Platform\MySQLPlatform; use Wikimedia\Rdbms\Platform\SQLPlatform; use Wikimedia\Rdbms\Replication\MysqlReplicationReporter; /** * MySQL database abstraction layer. * * Defines methods independent of the used MySQL extension. * * @property mysqli|null $conn * * @ingroup Database * @since 1.22 * @see Database */ class DatabaseMySQL extends Database { /** @var string|null */ private $sslKeyPath; /** @var string|null */ private $sslCertPath; /** @var string|null */ private $sslCAFile; /** @var string|null */ private $sslCAPath; /** * Open SSL cipher list string * @see https://docs.openssl.org/3.3/man1/openssl-ciphers/ * @var string|null */ private $sslCiphers; /** @var bool Use experimental UTF-8 transmission encoding */ private $utf8Mode; /** @var SQLPlatform */ protected $platform; /** @var MysqlReplicationReporter */ protected $replicationReporter; /** @var int Last implicit row ID for the session (0 if none) */ private $sessionLastAutoRowId; /** * Additional $params include: * - lagDetectionMethod : set to one of (Seconds_Behind_Master,pt-heartbeat). * pt-heartbeat assumes the table is at heartbeat.heartbeat * and uses UTC timestamps in the heartbeat.ts column. * (https://www.percona.com/doc/percona-toolkit/2.2/pt-heartbeat.html) * - lagDetectionOptions : if using pt-heartbeat, this can be set to an array map. * The "conds" key overrides the WHERE clause used to find the relevant row in the * `heartbeat` table, e.g. ['shard' => 's1']. By default, the row used is the newest * row having a server_id matching that of the immediate replication source server * for the given replica. * - useGTIDs : use GTID methods like MASTER_GTID_WAIT() when possible. * - sslKeyPath : path to key file [default: null] * - sslCertPath : path to certificate file [default: null] * - sslCAFile: path to a single certificate authority PEM file [default: null] * - sslCAPath : parth to certificate authority PEM directory [default: null] * - sslCiphers : array list of allowable ciphers [default: null] * @param array $params */ public function __construct( array $params ) { foreach ( [ 'KeyPath', 'CertPath', 'CAFile', 'CAPath', 'Ciphers' ] as $name ) { $var = "ssl{$name}"; if ( isset( $params[$var] ) ) { $this->$var = $params[$var]; } } $this->utf8Mode = !empty( $params['utf8Mode'] ); parent::__construct( $params ); $this->platform = new MySQLPlatform( $this, $this->logger, $this->currentDomain, $this->errorLogger ); $this->replicationReporter = new MysqlReplicationReporter( $params['topologyRole'], $this->logger, $params['srvCache'], $params['lagDetectionMethod'] ?? 'Seconds_Behind_Master', $params['lagDetectionOptions'] ?? [], !empty( $params['useGTIDs' ] ) ); } /** * @return string */ public function getType() { return 'mysql'; } protected function open( $server, $user, $password, $db, $schema, $tablePrefix ) { $this->close( __METHOD__ ); if ( $schema !== null ) { throw $this->newExceptionAfterConnectError( "Got schema '$schema'; not supported." ); } $this->installErrorHandler(); try { $this->conn = $this->mysqlConnect( $server, $user, $password, $db ); } catch ( RuntimeException $e ) { $this->restoreErrorHandler(); throw $this->newExceptionAfterConnectError( $e->getMessage() ); } $error = $this->restoreErrorHandler(); if ( !$this->conn ) { throw $this->newExceptionAfterConnectError( $error ?: $this->lastError() ); } try { $this->currentDomain = new DatabaseDomain( ( $db !== '' ) ? $db : null, null, $tablePrefix ); $this->platform->setCurrentDomain( $this->currentDomain ); $set = []; if ( !$this->flagsHolder->getFlag( self::DBO_GAUGE ) ) { // Abstract over any excessive MySQL defaults $set[] = 'group_concat_max_len = 262144'; // Set any custom settings defined by site config // https://dev.mysql.com/doc/refman/5.7/en/innodb-parameters.html foreach ( $this->connectionVariables as $var => $val ) { // Escape strings but not numbers to avoid MySQL complaining if ( !is_int( $val ) && !is_float( $val ) ) { $val = $this->addQuotes( $val ); } $set[] = $this->platform->addIdentifierQuotes( $var ) . ' = ' . $val; } } if ( $set ) { $sql = 'SET ' . implode( ', ', $set ); $flags = self::QUERY_NO_RETRY | self::QUERY_CHANGE_TRX; $query = new Query( $sql, $flags, 'SET' ); // Avoid using query() so that replaceLostConnection() does not throw // errors if the transaction status is STATUS_TRX_ERROR $qs = $this->executeQuery( $query, __METHOD__, $flags ); if ( $qs->res === false ) { $this->reportQueryError( $qs->message, $qs->code, $sql, __METHOD__ ); } } } catch ( RuntimeException $e ) { throw $this->newExceptionAfterConnectError( $e->getMessage() ); } } protected function doSelectDomain( DatabaseDomain $domain ) { if ( $domain->getSchema() !== null ) { throw new DBExpectedError( $this, __CLASS__ . ": domain '{$domain->getId()}' has a schema component" ); } $database = $domain->getDatabase(); // A null database means "don't care" so leave it as is and update the table prefix if ( $database === null ) { $this->currentDomain = new DatabaseDomain( $this->currentDomain->getDatabase(), null, $domain->getTablePrefix() ); $this->platform->setCurrentDomain( $this->currentDomain ); return true; } if ( $database !== $this->getDBname() ) { $sql = 'USE ' . $this->addIdentifierQuotes( $database ); $query = new Query( $sql, self::QUERY_CHANGE_TRX, 'USE' ); $qs = $this->executeQuery( $query, __METHOD__, self::QUERY_CHANGE_TRX ); if ( $qs->res === false ) { $this->reportQueryError( $qs->message, $qs->code, $sql, __METHOD__ ); return false; // unreachable } } // Update that domain fields on success (no exception thrown) $this->currentDomain = $domain; $this->platform->setCurrentDomain( $domain ); return true; } /** * @return string */ public function lastError() { if ( $this->conn ) { // Even if it's non-zero, it can still be invalid $error = $this->mysqlError( $this->conn ); if ( !$error ) { $error = $this->mysqlError(); } } else { $error = $this->mysqlError() ?: $this->lastConnectError; } return $error; } protected function isInsertSelectSafe( array $insertOptions, array $selectOptions, $fname ) { $row = $this->replicationReporter->getReplicationSafetyInfo( $this, $fname ); // For row-based-replication, the resulting changes will be relayed, not the query if ( $row->binlog_format === 'ROW' ) { return true; } // LIMIT requires ORDER BY on a unique key or it is non-deterministic if ( isset( $selectOptions['LIMIT'] ) ) { return false; } // In MySQL, an INSERT SELECT is only replication safe with row-based // replication or if innodb_autoinc_lock_mode is 0. When those // conditions aren't met, use non-native mode. // While we could try to determine if the insert is safe anyway by // checking if the target table has an auto-increment column that // isn't set in $varMap, that seems unlikely to be worth the extra // complexity. return ( in_array( 'NO_AUTO_COLUMNS', $insertOptions ) || (int)$row->innodb_autoinc_lock_mode === 0 ); } protected function checkInsertWarnings( Query $query, $fname ) { if ( $this->conn && $this->conn->warning_count ) { // Yeah it's weird. It's not iterable. $warnings = $this->conn->get_warnings(); $done = $warnings === false; while ( !$done ) { if ( in_array( $warnings->errno, [ // List based on https://dev.mysql.com/doc/refman/8.0/en/sql-mode.html#ignore-effect-on-execution 1048, /* ER_BAD_NULL_ERROR */ 1526, /* ER_NO_PARTITION_FOR_GIVEN_VALUE */ 1748, /* ER_ROW_DOES_NOT_MATCH_GIVEN_PARTITION_SET */ 1242, /* ER_SUBQUERY_NO_1_ROW */ 1369, /* ER_VIEW_CHECK_FAILED */ // Truncation and overflow per T108255 1264, /* ER_WARN_DATA_OUT_OF_RANGE */ 1265, /* WARN_DATA_TRUNCATED */ ] ) ) { $this->reportQueryError( 'Insert returned unacceptable warning: ' . $warnings->message, $warnings->errno, $query->getSQL(), $fname ); } $done = !$warnings->next(); } } } public function estimateRowCount( $tables, $var = '*', $conds = '', $fname = __METHOD__, $options = [], $join_conds = [] ): int { $conds = $this->platform->normalizeConditions( $conds, $fname ); $column = $this->platform->extractSingleFieldFromList( $var ); if ( is_string( $column ) && !in_array( $column, [ '*', '1' ] ) ) { $conds[] = "$column IS NOT NULL"; } $options['EXPLAIN'] = true; $res = $this->select( $tables, $var, $conds, $fname, $options, $join_conds ); if ( $res === false ) { return -1; } if ( !$res->numRows() ) { return 0; } $rows = 1; foreach ( $res as $plan ) { $rows *= $plan->rows > 0 ? $plan->rows : 1; // avoid resetting to zero } return (int)$rows; } public function tableExists( $table, $fname = __METHOD__ ) { [ $db, $pt ] = $this->platform->getDatabaseAndTableIdentifier( $table ); if ( isset( $this->sessionTempTables[$db][$pt] ) ) { return true; // already known to exist and won't be found in the query anyway } return (bool)$this->newSelectQueryBuilder() ->select( '1' ) ->from( 'information_schema.tables' ) ->where( [ 'table_schema' => $db, 'table_name' => $pt, ] ) ->caller( $fname ) ->fetchField(); } /** * @param string $table * @param string $field * @return MySQLField|false */ public function fieldInfo( $table, $field ) { $query = new Query( "SELECT * FROM " . $this->tableName( $table ) . " LIMIT 1", self::QUERY_SILENCE_ERRORS | self::QUERY_IGNORE_DBO_TRX | self::QUERY_CHANGE_NONE, 'SELECT' ); $res = $this->query( $query, __METHOD__ ); if ( !$res ) { return false; } /** @var MysqliResultWrapper $res */ '@phan-var MysqliResultWrapper $res'; return $res->getInternalFieldInfo( $field ); } public function indexInfo( $table, $index, $fname = __METHOD__ ) { # https://dev.mysql.com/doc/mysql/en/SHOW_INDEX.html $index = $this->platform->indexName( $index ); $query = new Query( 'SHOW INDEX FROM ' . $this->tableName( $table ), self::QUERY_IGNORE_DBO_TRX | self::QUERY_CHANGE_NONE, 'SHOW' ); $res = $this->query( $query, $fname ); foreach ( $res as $row ) { if ( $row->Key_name === $index ) { return [ 'unique' => !$row->Non_unique ]; } } return false; } /** * @param string $s * @return string */ public function strencode( $s ) { return $this->mysqlRealEscapeString( $s ); } public function serverIsReadOnly() { // Avoid SHOW to avoid internal temporary tables $flags = self::QUERY_IGNORE_DBO_TRX | self::QUERY_CHANGE_NONE; $query = new Query( "SELECT @@GLOBAL.read_only AS Value", $flags, 'SELECT' ); $res = $this->query( $query, __METHOD__ ); $row = $res->fetchObject(); return $row && (bool)$row->Value; } /** * @return string */ public function getSoftwareLink() { [ $variant ] = $this->getMySqlServerVariant(); if ( $variant === 'MariaDB' ) { return '[{{int:version-db-mariadb-url}} MariaDB]'; } return '[{{int:version-db-mysql-url}} MySQL]'; } /** * @return string[] (one of ("MariaDB","MySQL"), x.y.z version string) */ private function getMySqlServerVariant() { $version = $this->getServerVersion(); // MariaDB includes its name in its version string; this is how MariaDB's version of // the mysql command-line client identifies MariaDB servers. // https://dev.mysql.com/doc/refman/8.0/en/information-functions.html#function_version // https://mariadb.com/kb/en/version/ $parts = explode( '-', $version, 2 ); $number = $parts[0]; $suffix = $parts[1] ?? ''; if ( strpos( $suffix, 'MariaDB' ) !== false || strpos( $suffix, '-maria-' ) !== false ) { $vendor = 'MariaDB'; } else { $vendor = 'MySQL'; } return [ $vendor, $number ]; } /** * @return string */ public function getServerVersion() { // MariaDB 10 adds the prefix "5.5.5-", and only some newer client libraries strip // it off (see RPL_VERSION_HACK in include/mysql_com.h). $version = $this->conn->server_info; if ( str_starts_with( $version, '5.5.5-' ) && ( str_contains( $version, 'MariaDB' ) || str_contains( $version, '-maria-' ) ) ) { $version = substr( $version, strlen( '5.5.5-' ) ); } return $version; } /** * @param array $options */ public function setSessionOptions( array $options ) { $sqlAssignments = []; if ( isset( $options['connTimeout'] ) ) { $encTimeout = (int)$options['connTimeout']; $sqlAssignments[] = "net_read_timeout=$encTimeout"; $sqlAssignments[] = "net_write_timeout=$encTimeout"; } if ( isset( $options['groupConcatMaxLen'] ) ) { $maxLength = (int)$options['groupConcatMaxLen']; $sqlAssignments[] = "group_concat_max_len=$maxLength"; } if ( $sqlAssignments ) { $query = new Query( 'SET ' . implode( ', ', $sqlAssignments ), self::QUERY_CHANGE_TRX | self::QUERY_CHANGE_NONE, 'SET' ); $this->query( $query, __METHOD__ ); } } /** * @param string &$sql * @param string &$newLine * @return bool */ public function streamStatementEnd( &$sql, &$newLine ) { if ( preg_match( '/^DELIMITER\s+(\S+)/i', $newLine, $m ) ) { $this->delimiter = $m[1]; $newLine = ''; } return parent::streamStatementEnd( $sql, $newLine ); } public function doLockIsFree( string $lockName, string $method ) { $query = new Query( $this->platform->lockIsFreeSQLText( $lockName ), self::QUERY_CHANGE_LOCKS, 'SELECT' ); $res = $this->query( $query, $method ); $row = $res->fetchObject(); return ( $row->unlocked == 1 ); } public function doLock( string $lockName, string $method, int $timeout ) { $query = new Query( $this->platform->lockSQLText( $lockName, $timeout ), self::QUERY_CHANGE_LOCKS, 'SELECT' ); $res = $this->query( $query, $method ); $row = $res->fetchObject(); return ( $row->acquired !== null ) ? (float)$row->acquired : null; } public function doUnlock( string $lockName, string $method ) { $query = new Query( $this->platform->unlockSQLText( $lockName ), self::QUERY_CHANGE_LOCKS, 'SELECT' ); $res = $this->query( $query, $method ); $row = $res->fetchObject(); return ( $row->released == 1 ); } protected function doFlushSession( $fname ) { // Note that RELEASE_ALL_LOCKS() is not supported well enough to use here. // https://mariadb.com/kb/en/release_all_locks/ $releaseLockFields = []; foreach ( $this->sessionNamedLocks as $name => $info ) { $encName = $this->addQuotes( $this->platform->makeLockName( $name ) ); $releaseLockFields[] = "RELEASE_LOCK($encName)"; } if ( $releaseLockFields ) { $sql = 'SELECT ' . implode( ',', $releaseLockFields ); $flags = self::QUERY_CHANGE_LOCKS | self::QUERY_NO_RETRY; $query = new Query( $sql, $flags, 'SELECT' ); $qs = $this->executeQuery( $query, __METHOD__, $flags ); if ( $qs->res === false ) { $this->reportQueryError( $qs->message, $qs->code, $sql, $fname, true ); } } } public function upsert( $table, array $rows, $uniqueKeys, array $set, $fname = __METHOD__ ) { $identityKey = $this->platform->normalizeUpsertParams( $uniqueKeys, $rows ); if ( !$rows ) { return; } $this->platform->assertValidUpsertSetArray( $set, $identityKey, $rows ); $encTable = $this->tableName( $table ); [ $sqlColumns, $sqlTuples ] = $this->platform->makeInsertLists( $rows ); $sqlColumnAssignments = $this->makeList( $set, self::LIST_SET ); // No need to expose __NEW.* since buildExcludedValue() uses VALUES(column) // https://mariadb.com/kb/en/insert-on-duplicate-key-update/ // https://dev.mysql.com/doc/refman/8.0/en/insert-on-duplicate.html $sql = "INSERT INTO $encTable " . "($sqlColumns) VALUES $sqlTuples " . "ON DUPLICATE KEY UPDATE $sqlColumnAssignments"; $query = new Query( $sql, self::QUERY_CHANGE_ROWS, 'INSERT', $table ); $this->query( $query, $fname ); // Count updates of conflicting rows and row inserts equally toward the change count $this->lastQueryAffectedRows = min( $this->lastQueryAffectedRows, count( $rows ) ); } public function replace( $table, $uniqueKeys, $rows, $fname = __METHOD__ ) { $this->platform->normalizeUpsertParams( $uniqueKeys, $rows ); if ( !$rows ) { return; } $encTable = $this->tableName( $table ); [ $sqlColumns, $sqlTuples ] = $this->platform->makeInsertLists( $rows ); // https://dev.mysql.com/doc/refman/8.0/en/replace.html $sql = "REPLACE INTO $encTable ($sqlColumns) VALUES $sqlTuples"; // Note that any auto-increment columns on conflicting rows will be reassigned // due to combined DELETE+INSERT semantics. This will be reflected in insertId(). $query = new Query( $sql, self::QUERY_CHANGE_ROWS, 'REPLACE', $table ); $this->query( $query, $fname ); // Do not count deletions of conflicting rows toward the change count $this->lastQueryAffectedRows = min( $this->lastQueryAffectedRows, count( $rows ) ); } protected function isConnectionError( $errno ) { // https://mariadb.com/kb/en/mariadb-error-codes/ // https://dev.mysql.com/doc/mysql-errors/8.0/en/server-error-reference.html // https://dev.mysql.com/doc/mysql-errors/8.0/en/client-error-reference.html return in_array( $errno, [ 2013, 2006, 2003, 1927, 1053 ], true ); } protected function isQueryTimeoutError( $errno ) { // https://mariadb.com/kb/en/mariadb-error-codes/ // https://dev.mysql.com/doc/refman/8.0/en/client-error-reference.html // https://dev.mysql.com/doc/mysql-errors/8.0/en/server-error-reference.html return in_array( $errno, [ 3024, 2062, 1969, 1028 ], true ); } protected function isKnownStatementRollbackError( $errno ) { // https://mariadb.com/kb/en/mariadb-error-codes/ // https://dev.mysql.com/doc/mysql-errors/8.0/en/server-error-reference.html return in_array( $errno, [ 3024, 1969, 1022, 1062, 1216, 1217, 1137, 1146, 1051, 1054 ], true ); } /** * @param string $oldName * @param string $newName * @param bool $temporary * @param string $fname * @return bool */ public function duplicateTableStructure( $oldName, $newName, $temporary = false, $fname = __METHOD__ ) { $tmp = $temporary ? 'TEMPORARY ' : ''; $newNameQuoted = $this->addIdentifierQuotes( $newName ); $oldNameQuoted = $this->addIdentifierQuotes( $oldName ); $query = new Query( "CREATE $tmp TABLE $newNameQuoted (LIKE $oldNameQuoted)", self::QUERY_PSEUDO_PERMANENT | self::QUERY_CHANGE_SCHEMA, $temporary ? 'CREATE TEMPORARY' : 'CREATE', // Use a dot to avoid double-prefixing in Database::getTempTableWrites() '.' . $newName ); return $this->query( $query, $fname ); } /** * List all tables on the database * * @param string|null $prefix Only show tables with this prefix, e.g. mw_ * @param string $fname Calling function name * @return array */ public function listTables( $prefix = null, $fname = __METHOD__ ) { $qb = $this->newSelectQueryBuilder() ->select( 'table_name' ) ->from( 'information_schema.tables' ) ->where( [ 'table_schema' => $this->currentDomain->getDatabase(), 'table_type' => 'BASE TABLE' ] ) ->caller( $fname ); if ( $prefix !== null && $prefix !== '' ) { $qb->andWhere( $this->expr( 'table_name', IExpression::LIKE, new LikeValue( $prefix, $this->anyString() ) ) ); } return $qb->fetchFieldValues(); } public function selectSQLText( $tables, $vars, $conds = '', $fname = __METHOD__, $options = [], $join_conds = [] ) { $sql = parent::selectSQLText( $tables, $vars, $conds, $fname, $options, $join_conds ); // https://dev.mysql.com/doc/refman/5.7/en/optimizer-hints.html // https://mariadb.com/kb/en/library/aborting-statements/ $timeoutMsec = intval( $options['MAX_EXECUTION_TIME'] ?? 0 ); if ( $timeoutMsec > 0 ) { [ $vendor, $number ] = $this->getMySqlServerVariant(); if ( $vendor === 'MariaDB' && version_compare( $number, '10.1.2', '>=' ) ) { $timeoutSec = $timeoutMsec / 1000; $sql = "SET STATEMENT max_statement_time=$timeoutSec FOR $sql"; } elseif ( $vendor === 'MySQL' && version_compare( $number, '5.7.0', '>=' ) ) { $sql = preg_replace( '/^SELECT(?=\s)/', "SELECT /*+ MAX_EXECUTION_TIME($timeoutMsec)*/", $sql ); } } return $sql; } protected function doSingleStatementQuery( string $sql ): QueryStatus { $conn = $this->getBindingHandle(); // Hide packet warnings caused by things like dropped connections AtEase::suppressWarnings(); $res = $conn->query( $sql ); AtEase::restoreWarnings(); // Note that mysqli::insert_id only reflects the last query statement $insertId = (int)$conn->insert_id; $this->lastQueryInsertId = $insertId; $this->sessionLastAutoRowId = $insertId ?: $this->sessionLastAutoRowId; return new QueryStatus( $res instanceof mysqli_result ? new MysqliResultWrapper( $this, $res ) : $res, $conn->affected_rows, $conn->error, $conn->errno ); } /** * @param string|null $server * @param string|null $user * @param string|null $password * @param string|null $db * @return mysqli|null * @throws DBConnectionError */ private function mysqlConnect( $server, $user, $password, $db ) { if ( !function_exists( 'mysqli_init' ) ) { throw $this->newExceptionAfterConnectError( "MySQLi functions missing, have you compiled PHP with the --with-mysqli option?" ); } // PHP 8.1.0+ throws exceptions by default. Turn that off for consistency. mysqli_report( MYSQLI_REPORT_OFF ); // Other than mysql_connect, mysqli_real_connect expects an explicit port number // e.g. "localhost:1234" or "127.0.0.1:1234" // or Unix domain socket path // e.g. "localhost:/socket_path" or "localhost:/foo/bar:bar:bar" // colons are known to be used by Google AppEngine, // see <https://cloud.google.com/sql/docs/mysql/connect-app-engine> // // We need to parse the port or socket path out of $realServer $port = null; $socket = null; $hostAndPort = IPUtils::splitHostAndPort( $server ); if ( $hostAndPort ) { $realServer = $hostAndPort[0]; if ( $hostAndPort[1] ) { $port = $hostAndPort[1]; } } elseif ( substr_count( $server, ':/' ) == 1 ) { // If we have a colon slash instead of a colon and a port number // after the ip or hostname, assume it's the Unix domain socket path [ $realServer, $socket ] = explode( ':', $server, 2 ); } else { $realServer = $server; } $mysqli = mysqli_init(); // Make affectedRows() for UPDATE reflect the number of matching rows, regardless // of whether any column values changed. This is what callers want to know and is // consistent with what Postgres and SQLite return. $flags = MYSQLI_CLIENT_FOUND_ROWS; if ( $this->ssl ) { $flags |= MYSQLI_CLIENT_SSL; $mysqli->ssl_set( $this->sslKeyPath, $this->sslCertPath, $this->sslCAFile, $this->sslCAPath, $this->sslCiphers ); } if ( $this->getFlag( self::DBO_COMPRESS ) ) { $flags |= MYSQLI_CLIENT_COMPRESS; } if ( $this->getFlag( self::DBO_PERSISTENT ) ) { $realServer = 'p:' . $realServer; } if ( $this->utf8Mode ) { // Tell the server we're communicating with it in UTF-8. // This may engage various charset conversions. $mysqli->options( MYSQLI_SET_CHARSET_NAME, 'utf8' ); } else { $mysqli->options( MYSQLI_SET_CHARSET_NAME, 'binary' ); } $mysqli->options( MYSQLI_OPT_CONNECT_TIMEOUT, $this->connectTimeout ?: 3 ); if ( $this->receiveTimeout ) { $mysqli->options( MYSQLI_OPT_READ_TIMEOUT, $this->receiveTimeout ); } // @phan-suppress-next-line PhanTypeMismatchArgumentNullableInternal socket seems set when used $ok = $mysqli->real_connect( $realServer, $user, $password, $db, $port, $socket, $flags ); return $ok ? $mysqli : null; } protected function closeConnection() { return ( $this->conn instanceof mysqli ) ? mysqli_close( $this->conn ) : true; } protected function lastInsertId() { return $this->sessionLastAutoRowId; } protected function doHandleSessionLossPreconnect() { // https://mariadb.com/kb/en/last_insert_id/ $this->sessionLastAutoRowId = 0; } public function insertId() { if ( $this->lastEmulatedInsertId === null ) { $conn = $this->getBindingHandle(); // Note that mysqli::insert_id only reflects the last query statement $this->lastEmulatedInsertId = (int)$conn->insert_id; } return $this->lastEmulatedInsertId; } /** * @return int */ public function lastErrno() { if ( $this->conn instanceof mysqli ) { return $this->conn->errno; } else { return mysqli_connect_errno(); } } /** * @param mysqli|null $conn Optional connection object * @return string */ private function mysqlError( $conn = null ) { if ( $conn === null ) { return (string)mysqli_connect_error(); } else { return $conn->error; } } private function mysqlRealEscapeString( $s ) { $conn = $this->getBindingHandle(); return $conn->real_escape_string( (string)$s ); } } PK ! h]�� � ( rdbms/database/IMaintainableDatabase.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\Rdbms; use Exception; use RuntimeException; /** * Advanced database interface for IDatabase handles that include maintenance methods * * This is useful for type-hints used by installer, upgrader, and background scripts * that will make use of lower-level and longer-running queries, including schema changes. * * @ingroup Database * @since 1.28 */ interface IMaintainableDatabase extends IDatabase { /** * Read and execute SQL commands from a file. * * Returns true on success, error string or exception on failure (depending * on object's error ignore settings). * * @param string $filename File name to open * @param callable|null $lineCallback Optional function called before reading each line * @param callable|null $resultCallback Optional function called for each MySQL result * @param string|false $fname Calling function name or false if name should be * generated dynamically using $filename * @param callable|null $inputCallback Optional function called for each * complete line sent * @return bool|string * @throws Exception */ public function sourceFile( $filename, ?callable $lineCallback = null, ?callable $resultCallback = null, $fname = false, ?callable $inputCallback = null ); /** * Read and execute commands from an open file handle. * * Returns true on success, error string or exception on failure (depending * on object's error ignore settings). * * @param resource $fp File handle * @param callable|null $lineCallback Optional function called before reading each query * @param callable|null $resultCallback Optional function called for each MySQL result * @param string $fname Calling function name @phan-mandatory-param * @param callable|null $inputCallback Optional function called for each complete query sent * @return bool|string */ public function sourceStream( $fp, ?callable $lineCallback = null, ?callable $resultCallback = null, $fname = __METHOD__, ?callable $inputCallback = null ); /** * Called by sourceStream() to check if we've reached a statement end * * @param string &$sql SQL assembled so far * @param string &$newLine New line about to be added to $sql * @return bool Whether $newLine contains end of the statement */ public function streamStatementEnd( &$sql, &$newLine ); /** * Delete a table * * @param string $table The unqualified name of a table * @param string $fname @phan-mandatory-param * @return bool Whether the table already existed * @throws DBError If an error occurs */ public function dropTable( $table, $fname = __METHOD__ ); /** * Delete all data in a table and reset any sequences owned by that table * * @param string $table The unqualified name of a table * @param string $fname @phan-mandatory-param * @throws DBError If an error occurs * @since 1.42 */ public function truncateTable( $table, $fname = __METHOD__ ); /** * Creates a new table with structure copied from existing table * * Note that unlike most database abstraction functions, this function does not * automatically append database prefix, because it works at a lower abstraction level. * The table names passed to this function shall not be quoted (this function calls * addIdentifierQuotes() when needed). * * @param string $oldName Name of table whose structure should be copied * @param string $newName Name of table to be created * @param bool $temporary Whether the new table should be temporary * @param string $fname Calling function name @phan-mandatory-param * @return bool True if operation was successful * @throws RuntimeException */ public function duplicateTableStructure( $oldName, $newName, $temporary = false, $fname = __METHOD__ ); /** * List all tables on the database. * * Since MW 1.42, this will no longer include MySQL views. * * @param string|null $prefix Only show tables with this prefix, e.g. mw_ * @param string $fname Calling function name @phan-mandatory-param * @throws DBError * @return array */ public function listTables( $prefix = null, $fname = __METHOD__ ); /** * Get information about a field * Returns false if the field doesn't exist * * @param string $table The unqualified name of a table * @param string $field Field name * * @return false|Field */ public function fieldInfo( $table, $field ); /** * Determines whether a field exists in a table * * @param string $table The unqualified name of a table * @param string $field Field to check on that table * @param string $fname Calling function name @phan-mandatory-param * @return bool Whether $table has field $field * @throws DBError If an error occurs, {@see query} */ public function fieldExists( $table, $field, $fname = __METHOD__ ); /** * Determines whether an index exists * * @param string $table The unqualified name of a table * @param string $index * @param string $fname @phan-mandatory-param * @return bool * @throws DBError If an error occurs, {@see query} */ public function indexExists( $table, $index, $fname = __METHOD__ ); /** * Determines if a given index is unique * * @param string $table The unqualified name of a table * @param string $index * @param string $fname Calling function name @phan-mandatory-param * @return bool|null Returns null if the index does not exist * @throws DBError If an error occurs, {@see query} */ public function indexUnique( $table, $index, $fname = __METHOD__ ); /** * Query whether a given table exists * * @param string $table The unqualified name of a table * @param string $fname @phan-mandatory-param * @return bool * @throws DBError If an error occurs, {@see query} */ public function tableExists( $table, $fname = __METHOD__ ); } PK ! 0{_xl l rdbms/database/DatabaseFlags.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\Rdbms\Database; use Wikimedia\Rdbms\DBLanguageError; use Wikimedia\Rdbms\Platform\ISQLPlatform; /** * @ingroup Database * @internal * @since 1.39 */ class DatabaseFlags implements IDatabaseFlags { /** @var int Current bit field of class DBO_* constants */ protected $flags; /** @var int[] Prior flags member variable values */ private $priorFlags = []; /** @var string[] List of DBO_* flags that can be changed after connection */ protected const MUTABLE_FLAGS = [ 'DBO_DEBUG', 'DBO_NOBUFFER', 'DBO_TRX', 'DBO_DDLMODE', ]; /** @var int Bit field of all DBO_* flags that can be changed after connection */ protected const DBO_MUTABLE = ( self::DBO_DEBUG | self::DBO_NOBUFFER | self::DBO_TRX | self::DBO_DDLMODE ); public function __construct( $flags ) { $this->flags = $flags; } public function setFlag( $flag, $remember = self::REMEMBER_NOTHING ) { if ( $flag & ~static::DBO_MUTABLE ) { throw new DBLanguageError( "Got $flag (allowed: " . implode( ', ', static::MUTABLE_FLAGS ) . ')' ); } if ( $remember === self::REMEMBER_PRIOR ) { $this->priorFlags[] = $this->flags; } $this->flags |= $flag; } public function clearFlag( $flag, $remember = self::REMEMBER_NOTHING ) { if ( $flag & ~static::DBO_MUTABLE ) { throw new DBLanguageError( "Got $flag (allowed: " . implode( ', ', static::MUTABLE_FLAGS ) . ')' ); } if ( $remember === self::REMEMBER_PRIOR ) { $this->priorFlags[] = $this->flags; } $this->flags &= ~$flag; } public function restoreFlags( $state = self::RESTORE_PRIOR ) { if ( !$this->priorFlags ) { return; } if ( $state === self::RESTORE_INITIAL ) { $this->flags = reset( $this->priorFlags ); $this->priorFlags = []; } else { $this->flags = array_pop( $this->priorFlags ); } } public function getFlag( $flag ) { return ( ( $this->flags & $flag ) === $flag ); } /** * @param int $flags A bit field of flags * @param int $bit Bit flag constant * @return bool Whether the bit field has the specified bit flag set */ public static function contains( int $flags, int $bit ) { return ( ( $flags & $bit ) === $bit ); } /** * @param int $queryFlags A bit field of ISQLPlatform::QUERY_* constants * @return bool Whether the implicit transaction flag is set and applies to the query flags */ public function hasApplicableImplicitTrxFlag( int $queryFlags ) { return $this->hasImplicitTrxFlag() && !( self::contains( $queryFlags, ISQLPlatform::QUERY_CHANGE_TRX ) || self::contains( $queryFlags, ISQLPlatform::QUERY_CHANGE_SCHEMA ) || self::contains( $queryFlags, ISQLPlatform::QUERY_CHANGE_LOCKS ) || self::contains( $queryFlags, ISQLPlatform::QUERY_IGNORE_DBO_TRX ) ); } /** * @return bool Whether the implicit transaction flag is set */ public function hasImplicitTrxFlag() { return $this->getFlag( self::DBO_TRX ); } } PK ! ٯBM�+ �+ + rdbms/database/position/MySQLPrimaryPos.phpnu �Iw�� <?php namespace Wikimedia\Rdbms; use InvalidArgumentException; use Stringable; /** * DBPrimaryPos implementation for MySQL and MariaDB. * * Note that primary positions and sync logic here make some assumptions: * * - Binlog-based usage assumes single-source replication and non-hierarchical replication. * - GTID-based usage allows getting/syncing with multi-source replication. It is assumed * that GTID sets are complete (e.g. include all domains on the server). * * @see https://mariadb.com/kb/en/library/gtid/ * @see https://dev.mysql.com/doc/refman/5.6/en/replication-gtids-concepts.html * @internal */ class MySQLPrimaryPos implements Stringable, DBPrimaryPos { /** @var string One of (BINARY_LOG, GTID_MYSQL, GTID_MARIA) */ private $style; /** @var string|null Base name of all Binary Log files */ private $binLog; /** @var array<int,int|string>|null Binary Log position tuple (index number, event number) */ private $logPos; /** @var string[] Map of (server_uuid/gtid_domain_id => GTID) */ private $gtids = []; /** @var string|null Active GTID domain ID */ private $activeDomain; /** @var string|null ID of the server were DB writes originate */ private $activeServerId; /** @var string|null UUID of the server were DB writes originate */ private $activeServerUUID; /** @var float UNIX timestamp */ private $asOfTime = 0.0; private const BINARY_LOG = 'binary-log'; private const GTID_MARIA = 'gtid-maria'; private const GTID_MYSQL = 'gtid-mysql'; /** Key name of the 6 digit binary log index number of a position tuple */ public const CORD_INDEX = 0; /** Key name of the 64 bit binary log event number of a position tuple */ public const CORD_EVENT = 1; /** * @param string $position One of (comma separated GTID list, <binlog file>/<64 bit integer>) * @param float $asOfTime UNIX timestamp */ public function __construct( $position, $asOfTime ) { $this->init( $position, $asOfTime ); } /** * @param string $position * @param float $asOfTime */ protected function init( $position, $asOfTime ) { $m = []; if ( preg_match( '!^(.+)\.(\d+)/(\d+)$!', $position, $m ) ) { $this->binLog = $m[1]; // ideally something like host name $this->logPos = [ self::CORD_INDEX => (int)$m[2], self::CORD_EVENT => $m[3] ]; $this->style = self::BINARY_LOG; } else { $gtids = array_filter( array_map( 'trim', explode( ',', $position ) ) ); foreach ( $gtids as $gtid ) { $components = self::parseGTID( $gtid ); if ( !$components ) { throw new InvalidArgumentException( "Invalid GTID '$gtid'." ); } [ $domain, $eventNumber ] = $components; if ( isset( $this->gtids[$domain] ) ) { // For MySQL, handle the case where some past issue caused a gap in the // executed GTID set, e.g. [last_purged+1,N-1] and [N+1,N+2+K]. Ignore the // gap by using the GTID with the highest ending event number. [ , $otherEventNumber ] = self::parseGTID( $this->gtids[$domain] ); if ( $eventNumber > $otherEventNumber ) { $this->gtids[$domain] = $gtid; } } else { $this->gtids[$domain] = $gtid; } if ( is_string( $domain ) ) { $this->style = self::GTID_MARIA; // gtid_domain_id } else { $this->style = self::GTID_MYSQL; // server_uuid } } if ( !$this->gtids ) { throw new InvalidArgumentException( "GTID set cannot be empty." ); } } $this->asOfTime = $asOfTime; } public function asOfTime() { return $this->asOfTime; } public function hasReached( DBPrimaryPos $pos ) { if ( !( $pos instanceof self ) ) { throw new InvalidArgumentException( "Position not an instance of " . __CLASS__ ); } // Prefer GTID comparisons, which work with multi-tier replication $thisPosByDomain = $this->getActiveGtidCoordinates(); $thatPosByDomain = $pos->getActiveGtidCoordinates(); if ( $thisPosByDomain && $thatPosByDomain ) { $comparisons = []; // Check that this has positions reaching those in $pos for all domains in common foreach ( $thatPosByDomain as $domain => $thatPos ) { if ( isset( $thisPosByDomain[$domain] ) ) { $comparisons[] = ( $thatPos <= $thisPosByDomain[$domain] ); } } // Check that $this has a GTID for at least one domain also in $pos; due to MariaDB // quirks, prior primary switch-overs may result in inactive garbage GTIDs that cannot // be cleaned up. Assume that the domains in both this and $pos cover the relevant // active channels. return ( $comparisons && !in_array( false, $comparisons, true ) ); } // Fallback to the binlog file comparisons $thisBinPos = $this->getBinlogCoordinates(); $thatBinPos = $pos->getBinlogCoordinates(); if ( $thisBinPos && $thatBinPos && $thisBinPos['binlog'] === $thatBinPos['binlog'] ) { return ( $thisBinPos['pos'] >= $thatBinPos['pos'] ); } // Comparing totally different binlogs does not make sense return false; } /** * @return array<int,int|string>|null Tuple of (binary log file number, 64 bit event number) * @since 1.31 */ public function getLogPosition() { return $this->gtids ? null : $this->logPos; } /** * @return string|null Name of the binary log file for this position * @since 1.31 */ public function getLogFile() { // @phan-suppress-next-line PhanTypeArraySuspiciousNullable return $this->gtids ? null : "{$this->binLog}.{$this->logPos[self::CORD_INDEX]}"; } /** * @return array<string,string> Map of (server_uuid/gtid_domain_id => GTID) * @since 1.31 */ public function getGTIDs() { return $this->gtids; } /** * Set the GTID domain known to be used in new commits on a replication stream of interest * * This makes getRelevantActiveGTIDs() filter out GTIDs from other domains * * @see MySQLPrimaryPos::getRelevantActiveGTIDs() * @see https://mariadb.com/kb/en/library/gtid/#gtid_domain_id * * @param string|int|null $id @@gtid_domain_id of the active replication stream * @return MySQLPrimaryPos This instance (since 1.34) * @since 1.31 */ public function setActiveDomain( $id ) { $this->activeDomain = (string)$id; return $this; } /** * Set the server ID known to be used in new commits on a replication stream of interest * * This makes getRelevantActiveGTIDs() filter out GTIDs from other origin servers * * @see MySQLPrimaryPos::getRelevantActiveGTIDs() * * @param string|int|null $id @@server_id of the server were writes originate * @return MySQLPrimaryPos This instance (since 1.34) * @since 1.31 */ public function setActiveOriginServerId( $id ) { $this->activeServerId = (string)$id; return $this; } /** * Set the server UUID known to be used in new commits on a replication stream of interest * * This makes getRelevantActiveGTIDs() filter out GTIDs from other origin servers * * @see MySQLPrimaryPos::getRelevantActiveGTIDs() * * @param string|null $id @@server_uuid of the server were writes originate * @return MySQLPrimaryPos This instance (since 1.34) * @since 1.31 */ public function setActiveOriginServerUUID( $id ) { $this->activeServerUUID = $id; return $this; } /** * @param MySQLPrimaryPos $pos * @param MySQLPrimaryPos $refPos * @return string[] List of active GTIDs from $pos that have domains in $refPos * @since 1.34 */ public static function getRelevantActiveGTIDs( MySQLPrimaryPos $pos, MySQLPrimaryPos $refPos ) { return array_values( array_intersect_key( $pos->gtids, $pos->getActiveGtidCoordinates(), $refPos->gtids ) ); } /** * @see https://mariadb.com/kb/en/mariadb/gtid * @see https://dev.mysql.com/doc/refman/5.6/en/replication-gtids-concepts.html * @return array<string,int> Map of (server_uuid/gtid_domain_id => integer position) */ protected function getActiveGtidCoordinates() { $gtidInfos = []; foreach ( $this->gtids as $gtid ) { [ $domain, $pos, $server ] = self::parseGTID( $gtid ); $ignore = false; // Filter out GTIDs from non-active replication domains if ( $this->style === self::GTID_MARIA && $this->activeDomain !== null ) { $ignore = $ignore || ( $domain !== $this->activeDomain ); } // Likewise for GTIDs from non-active replication origin servers if ( $this->style === self::GTID_MARIA && $this->activeServerId !== null ) { $ignore = $ignore || ( $server !== $this->activeServerId ); } elseif ( $this->style === self::GTID_MYSQL && $this->activeServerUUID !== null ) { $ignore = $ignore || ( $server !== $this->activeServerUUID ); } if ( !$ignore ) { $gtidInfos[$domain] = $pos; } } return $gtidInfos; } /** * @param string $id GTID * @return string[]|null (domain ID, event number, source server ID) for MariaDB, * (source server UUID, event number, source server UUID) for MySQL, or null */ protected static function parseGTID( $id ) { $m = []; if ( preg_match( '!^(\d+)-(\d+)-(\d+)$!', $id, $m ) ) { // MariaDB style: "<32 bit domain ID>-<32 bit server id>-<64 bit event number>" $channelId = $m[1]; $originServerId = $m[2]; $eventNumber = $m[3]; } elseif ( preg_match( '!^(\w{8}-\w{4}-\w{4}-\w{4}-\w{12}):(?:\d+-|)(\d+)$!', $id, $m ) ) { // MySQL style: "<server UUID>:<64 bit event number>[-<64 bit event number>]". // Normally, the first number should reflect the point (gtid_purged) where older // binary logs where purged to save space. When doing comparisons, it may as well // be 1 in that case. Assume that this is generally the situation. $channelId = $m[1]; $originServerId = $m[1]; $eventNumber = $m[2]; } else { return null; } return [ $channelId, $eventNumber, $originServerId ]; } /** * @see https://dev.mysql.com/doc/refman/5.7/en/show-master-status.html * @see https://dev.mysql.com/doc/refman/5.7/en/show-slave-status.html * @return array|false Map of (binlog:<string>, pos:(<integer>, <integer>)) or false */ protected function getBinlogCoordinates() { return ( $this->binLog !== null && $this->logPos !== null ) ? [ 'binlog' => $this->binLog, 'pos' => $this->logPos ] : false; } public static function newFromArray( array $data ) { $pos = new self( $data['position'], $data['asOfTime'] ); if ( isset( $data['activeDomain'] ) ) { $pos->setActiveDomain( $data['activeDomain'] ); } if ( isset( $data['activeServerId'] ) ) { $pos->setActiveOriginServerId( $data['activeServerId'] ); } if ( isset( $data['activeServerUUID'] ) ) { $pos->setActiveOriginServerUUID( $data['activeServerUUID'] ); } return $pos; } public function toArray(): array { return [ '_type_' => get_class( $this ), 'position' => $this->__toString(), 'activeDomain' => $this->activeDomain, 'activeServerId' => $this->activeServerId, 'activeServerUUID' => $this->activeServerUUID, 'asOfTime' => $this->asOfTime ]; } /** * @return string GTID set or <binary log file>/<position> (e.g db1034-bin.000976/843431247) */ public function __toString() { return $this->gtids ? implode( ',', $this->gtids ) // @phan-suppress-next-line PhanTypeArraySuspiciousNullable : $this->getLogFile() . "/{$this->logPos[self::CORD_EVENT]}"; } } PK ! J�+T� � ( rdbms/database/position/DBPrimaryPos.phpnu �Iw�� <?php namespace Wikimedia\Rdbms; use Stringable; /** * An object representing a primary or replica DB position in a replicated setup. * * The implementation details of this opaque type are up to the database subclass. * * @since 1.37 */ interface DBPrimaryPos extends Stringable { /** * @since 1.25 * @return float UNIX timestamp */ public function asOfTime(); /** * @since 1.27 * @param DBPrimaryPos $pos * @return bool Whether this position is at or higher than $pos */ public function hasReached( DBPrimaryPos $pos ); /** * @since 1.27 * @return string */ public function __toString(); /** * Deserialization from storage * * @since 1.39 * @param array $data Representation as returned from ::toArray() * @return DBPrimaryPos */ public static function newFromArray( array $data ); /** * Serialization for storage * * @since 1.39 * @return array Representation for use by ::newFromArray() */ public function toArray(): array; } PK ! ��4� � rdbms/database/Database.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\Rdbms; use InvalidArgumentException; use LogicException; use Psr\Log\LoggerAwareInterface; use Psr\Log\LoggerInterface; use Psr\Log\NullLogger; use RuntimeException; use Stringable; use Throwable; use Wikimedia\AtEase\AtEase; use Wikimedia\Rdbms\Database\DatabaseFlags; use Wikimedia\Rdbms\Platform\SQLPlatform; use Wikimedia\Rdbms\Replication\ReplicationReporter; use Wikimedia\RequestTimeout\CriticalSectionProvider; use Wikimedia\RequestTimeout\CriticalSectionScope; use Wikimedia\ScopedCallback; /** * A single concrete connection to a relational database. * * This is the base class for all connection-specific relational database handles. * No two instances of this class should share the same underlying network connection. * * @see IDatabase * @ingroup Database * @since 1.28 */ abstract class Database implements Stringable, IDatabaseForOwner, IMaintainableDatabase, LoggerAwareInterface { /** @var CriticalSectionProvider|null */ protected $csProvider; /** @var LoggerInterface */ protected $logger; /** @var callable Error logging callback */ protected $errorLogger; /** @var callable Deprecation logging callback */ protected $deprecationLogger; /** @var callable|null */ protected $profiler; /** @var TransactionManager */ private $transactionManager; /** @var DatabaseDomain */ protected $currentDomain; /** @var DatabaseFlags */ protected $flagsHolder; // phpcs:ignore MediaWiki.Commenting.PropertyDocumentation.ObjectTypeHintVar /** @var object|resource|null Database connection */ protected $conn; /** @var string|null Readable name or host/IP of the database server */ protected $serverName; /** @var bool Whether this PHP instance is for a CLI script */ protected $cliMode; /** @var int|null Maximum seconds to wait on connection attempts */ protected $connectTimeout; /** @var int|null Maximum seconds to wait on receiving query results */ protected $receiveTimeout; /** @var string Agent name for query profiling */ protected $agent; /** @var array<string,mixed> Connection parameters used by initConnection() and open() */ protected $connectionParams; /** @var string[]|int[]|float[] SQL variables values to use for all new connections */ protected $connectionVariables; /** @var int Row batch size to use for emulated INSERT SELECT queries */ protected $nonNativeInsertSelectBatchSize; /** @var bool Whether to use SSL connections */ protected $ssl; /** @var bool Whether to check for warnings */ protected $strictWarnings; /** @var array Current LoadBalancer tracking information */ protected $lbInfo = []; /** @var string|false Current SQL query delimiter */ protected $delimiter = ';'; /** @var string|bool|null Stashed value of html_errors INI setting */ private $htmlErrors; /** @var array<string,array> Map of (lock name => (UNIX time,trx ID)) */ protected $sessionNamedLocks = []; /** @var array<string,array<string, TempTableInfo>> Map of (DB name => table name => info) */ protected $sessionTempTables = []; /** @var int Affected row count for the last statement to query() */ protected $lastQueryAffectedRows = 0; /** @var int|null Insert (row) ID for the last statement to query() (null if not supported) */ protected $lastQueryInsertId; /** @var int|null Affected row count for the last query method call; null if unspecified */ protected $lastEmulatedAffectedRows; /** @var int|null Insert (row) ID for the last query method call; null if unspecified */ protected $lastEmulatedInsertId; /** @var string Last error during connection; empty string if none */ protected $lastConnectError = ''; /** @var float UNIX timestamp of the last server response */ private $lastPing = 0.0; /** @var float|false UNIX timestamp of last write query */ private $lastWriteTime = false; /** @var string|false The last PHP error from a query or connection attempt */ private $lastPhpError = false; /** @var int|null Current critical section numeric ID */ private $csmId; /** @var string|null Last critical section caller name */ private $csmFname; /** @var DBUnexpectedError|null Last unresolved critical section error */ private $csmError; /** Whether the database is a file on disk */ public const ATTR_DB_IS_FILE = 'db-is-file'; /** Lock granularity is on the level of the entire database */ public const ATTR_DB_LEVEL_LOCKING = 'db-level-locking'; /** The SCHEMA keyword refers to a grouping of tables in a database */ public const ATTR_SCHEMAS_AS_TABLE_GROUPS = 'supports-schemas'; /** New Database instance will not be connected yet when returned */ public const NEW_UNCONNECTED = 0; /** New Database instance will already be connected when returned */ public const NEW_CONNECTED = 1; /** No errors occurred during the query */ protected const ERR_NONE = 0; /** Retry query due to a connection loss detected while sending the query (session intact) */ protected const ERR_RETRY_QUERY = 1; /** Abort query (no retries) due to a statement rollback (session/transaction intact) */ protected const ERR_ABORT_QUERY = 2; /** Abort any current transaction, by rolling it back, due to an error during the query */ protected const ERR_ABORT_TRX = 4; /** Abort and reset session due to server-side session-level state loss (locks, temp tables) */ protected const ERR_ABORT_SESSION = 8; /** Assume that queries taking this long to yield connection loss errors are at fault */ protected const DROPPED_CONN_BLAME_THRESHOLD_SEC = 3.0; /** @var string Idiom used when a cancelable atomic section started the transaction */ private const NOT_APPLICABLE = 'n/a'; /** How long before it is worth doing a dummy query to test the connection */ private const PING_TTL = 1.0; /** Dummy SQL query */ private const PING_QUERY = 'SELECT 1 AS ping'; /** Hostname or IP address to use on all connections */ protected const CONN_HOST = 'host'; /** Database server username to use on all connections */ protected const CONN_USER = 'user'; /** Database server password to use on all connections */ protected const CONN_PASSWORD = 'password'; /** Database name to use on initial connection */ protected const CONN_INITIAL_DB = 'dbname'; /** Schema name to use on initial connection */ protected const CONN_INITIAL_SCHEMA = 'schema'; /** Table prefix to use on initial connection */ protected const CONN_INITIAL_TABLE_PREFIX = 'tablePrefix'; /** @var SQLPlatform */ protected $platform; /** @var ReplicationReporter */ protected $replicationReporter; /** * @note exceptions for missing libraries/drivers should be thrown in initConnection() * @param array $params Parameters passed from Database::factory() */ public function __construct( array $params ) { $this->logger = $params['logger'] ?? new NullLogger(); $this->transactionManager = new TransactionManager( $this->logger, $params['trxProfiler'] ); $this->connectionParams = [ self::CONN_HOST => ( isset( $params['host'] ) && $params['host'] !== '' ) ? $params['host'] : null, self::CONN_USER => ( isset( $params['user'] ) && $params['user'] !== '' ) ? $params['user'] : null, self::CONN_INITIAL_DB => ( isset( $params['dbname'] ) && $params['dbname'] !== '' ) ? $params['dbname'] : null, self::CONN_INITIAL_SCHEMA => ( isset( $params['schema'] ) && $params['schema'] !== '' ) ? $params['schema'] : null, self::CONN_PASSWORD => is_string( $params['password'] ) ? $params['password'] : null, self::CONN_INITIAL_TABLE_PREFIX => (string)$params['tablePrefix'] ]; $this->lbInfo = $params['lbInfo'] ?? []; $this->connectionVariables = $params['variables'] ?? []; // Set SQL mode, default is turning them all off, can be overridden or skipped with null if ( is_string( $params['sqlMode'] ?? null ) ) { $this->connectionVariables['sql_mode'] = $params['sqlMode']; } $flags = (int)$params['flags']; $this->flagsHolder = new DatabaseFlags( $flags ); $this->ssl = $params['ssl'] ?? (bool)( $flags & self::DBO_SSL ); $this->connectTimeout = $params['connectTimeout'] ?? null; $this->receiveTimeout = $params['receiveTimeout'] ?? null; $this->cliMode = (bool)$params['cliMode']; $this->agent = (string)$params['agent']; $this->serverName = $params['serverName']; $this->nonNativeInsertSelectBatchSize = $params['nonNativeInsertSelectBatchSize'] ?? 10000; $this->strictWarnings = !empty( $params['strictWarnings'] ); $this->profiler = is_callable( $params['profiler'] ) ? $params['profiler'] : null; $this->errorLogger = $params['errorLogger']; $this->deprecationLogger = $params['deprecationLogger']; $this->csProvider = $params['criticalSectionProvider'] ?? null; // Set initial dummy domain until open() sets the final DB/prefix $this->currentDomain = new DatabaseDomain( $params['dbname'] != '' ? $params['dbname'] : null, $params['schema'] != '' ? $params['schema'] : null, $params['tablePrefix'] ); $this->platform = new SQLPlatform( $this, $this->logger, $this->currentDomain, $this->errorLogger ); // Children classes must set $this->replicationReporter. } /** * Initialize the connection to the database over the wire (or to local files) * * @throws LogicException * @throws InvalidArgumentException * @throws DBConnectionError * @since 1.31 */ final public function initConnection() { if ( $this->isOpen() ) { throw new LogicException( __METHOD__ . ': already connected' ); } // Establish the connection $this->open( $this->connectionParams[self::CONN_HOST], $this->connectionParams[self::CONN_USER], $this->connectionParams[self::CONN_PASSWORD], $this->connectionParams[self::CONN_INITIAL_DB], $this->connectionParams[self::CONN_INITIAL_SCHEMA], $this->connectionParams[self::CONN_INITIAL_TABLE_PREFIX] ); $this->lastPing = microtime( true ); } /** * Open a new connection to the database (closing any existing one) * * @param string|null $server Server host/address and optional port {@see connectionParams} * @param string|null $user User name {@see connectionParams} * @param string|null $password User password {@see connectionParams} * @param string|null $db Database name * @param string|null $schema Database schema name * @param string $tablePrefix * @throws DBConnectionError */ abstract protected function open( $server, $user, $password, $db, $schema, $tablePrefix ); /** * @return array Map of (Database::ATTR_* constant => value) * @since 1.31 */ public static function getAttributes() { return []; } /** * Set the PSR-3 logger interface to use. * * @param LoggerInterface $logger */ public function setLogger( LoggerInterface $logger ) { $this->logger = $logger; } public function getServerInfo() { return $this->getServerVersion(); } public function tablePrefix( $prefix = null ) { $old = $this->currentDomain->getTablePrefix(); if ( $prefix !== null ) { $this->currentDomain = new DatabaseDomain( $this->currentDomain->getDatabase(), $this->currentDomain->getSchema(), $prefix ); $this->platform->setCurrentDomain( $this->currentDomain ); } return $old; } public function dbSchema( $schema = null ) { $old = $this->currentDomain->getSchema(); if ( $schema !== null ) { if ( $schema !== '' && $this->getDBname() === null ) { throw new DBUnexpectedError( $this, "Cannot set schema to '$schema'; no database set" ); } $this->currentDomain = new DatabaseDomain( $this->currentDomain->getDatabase(), // DatabaseDomain uses null for unspecified schemas ( $schema !== '' ) ? $schema : null, $this->currentDomain->getTablePrefix() ); $this->platform->setCurrentDomain( $this->currentDomain ); } return (string)$old; } public function getLBInfo( $name = null ) { if ( $name === null ) { return $this->lbInfo; } if ( array_key_exists( $name, $this->lbInfo ) ) { return $this->lbInfo[$name]; } return null; } public function setLBInfo( $nameOrArray, $value = null ) { if ( is_array( $nameOrArray ) ) { $this->lbInfo = $nameOrArray; } elseif ( is_string( $nameOrArray ) ) { if ( $value !== null ) { $this->lbInfo[$nameOrArray] = $value; } else { unset( $this->lbInfo[$nameOrArray] ); } } else { throw new InvalidArgumentException( "Got non-string key" ); } } public function lastDoneWrites() { return $this->lastWriteTime ?: false; } /** * @return bool * @since 1.39 * @internal For use by Database/LoadBalancer only */ public function sessionLocksPending() { return (bool)$this->sessionNamedLocks; } /** * @return string|null ID of the active explicit transaction round being participating in */ final protected function getTransactionRoundId() { if ( $this->flagsHolder->hasImplicitTrxFlag() ) { // LoadBalancer transaction round participation is enabled for this DB handle; // get the ID of the active explicit transaction round (if any) $id = $this->getLBInfo( self::LB_TRX_ROUND_ID ); return is_string( $id ) ? $id : null; } return null; } public function isOpen() { return (bool)$this->conn; } public function getDomainID() { return $this->currentDomain->getId(); } /** * Wrapper for addslashes() * * @param string $s String to be slashed. * @return string Slashed string. */ abstract public function strencode( $s ); /** * Set a custom error handler for logging errors during database connection */ protected function installErrorHandler() { $this->lastPhpError = false; $this->htmlErrors = ini_set( 'html_errors', '0' ); set_error_handler( [ $this, 'connectionErrorLogger' ] ); } /** * Restore the previous error handler and return the last PHP error for this DB * * @return string|false */ protected function restoreErrorHandler() { restore_error_handler(); if ( $this->htmlErrors !== false ) { ini_set( 'html_errors', $this->htmlErrors ); } return $this->getLastPHPError(); } /** * @return string|false Last PHP error for this DB (typically connection errors) */ protected function getLastPHPError() { if ( $this->lastPhpError ) { $error = preg_replace( '!\[<a.*</a>\]!', '', $this->lastPhpError ); $error = preg_replace( '!^.*?:\s?(.*)$!', '$1', $error ); return $error; } return false; } /** * Error handler for logging errors during database connection * * @internal This method should not be used outside of Database classes * * @param int|string $errno * @param string $errstr */ public function connectionErrorLogger( $errno, $errstr ) { $this->lastPhpError = $errstr; } /** * Create a log context to pass to PSR-3 logger functions. * * @param array $extras Additional data to add to context * @return array */ protected function getLogContext( array $extras = [] ) { return array_merge( [ 'db_server' => $this->getServerName(), 'db_name' => $this->getDBname(), 'db_user' => $this->connectionParams[self::CONN_USER] ?? null, ], $extras ); } final public function close( $fname = __METHOD__ ) { $error = null; // error to throw after disconnecting $wasOpen = (bool)$this->conn; // This should mostly do nothing if the connection is already closed if ( $this->conn ) { // Roll back any dangling transaction first if ( $this->trxLevel() ) { $error = $this->transactionManager->trxCheckBeforeClose( $this, $fname ); // Rollback the changes and run any callbacks as needed $this->rollback( __METHOD__, self::FLUSHING_INTERNAL ); $this->runTransactionPostRollbackCallbacks(); } // Close the actual connection in the binding handle $closed = $this->closeConnection(); } else { $closed = true; // already closed; nothing to do } $this->conn = null; // Log any unexpected errors after having disconnected if ( $error !== null ) { // T217819, T231443: this is probably just LoadBalancer trying to recover from // errors and shutdown. Log any problems and move on since the request has to // end one way or another. Throwing errors is not very useful at some point. $this->logger->error( $error, [ 'db_log_category' => 'query' ] ); } // Note that various subclasses call close() at the start of open(), which itself is // called by replaceLostConnection(). In that case, just because onTransactionResolution() // callbacks are pending does not mean that an exception should be thrown. Rather, they // will be executed after the reconnection step. if ( $wasOpen ) { // Double check that no callbacks are dangling $fnames = $this->pendingWriteAndCallbackCallers(); if ( $fnames ) { throw new RuntimeException( "Transaction callbacks are still pending: " . implode( ', ', $fnames ) ); } } return $closed; } /** * Make sure there is an open connection handle (alive or not) * * This guards against fatal errors to the binding handle not being defined in cases * where open() was never called or close() was already called. * * @throws DBUnexpectedError */ final protected function assertHasConnectionHandle() { if ( !$this->isOpen() ) { throw new DBUnexpectedError( $this, "DB connection was already closed" ); } } /** * Closes underlying database connection * @return bool Whether connection was closed successfully * @since 1.20 */ abstract protected function closeConnection(); /** * Run a query and return a QueryStatus instance with the query result information * * This is meant to handle the basic command of actually sending a query to the * server via the driver. No implicit transaction, reconnection, nor retry logic * should happen here. The higher level query() method is designed to handle those * sorts of concerns. This method should not trigger such higher level methods. * * The lastError() and lastErrno() methods should meaningfully reflect what error, * if any, occurred during the last call to this method. Methods like executeQuery(), * query(), select(), insert(), update(), delete(), and upsert() implement their calls * to doQuery() such that an immediately subsequent call to lastError()/lastErrno() * meaningfully reflects any error that occurred during that public query method call. * * For SELECT queries, the result field contains either: * - a) A driver-specific IResultWrapper describing the query results * - b) False, on any query failure * * For non-SELECT queries, the result field contains either: * - a) A driver-specific IResultWrapper, only on success * - b) True, only on success (e.g. no meaningful result other than "OK") * - c) False, on any query failure * * @param string $sql Single-statement SQL query * @return QueryStatus * @since 1.39 */ abstract protected function doSingleStatementQuery( string $sql ): QueryStatus; /** * Determine whether a write query affects a permanent table. * This includes pseudo-permanent tables. * * @param Query $query * @return bool */ private function hasPermanentTable( Query $query ) { if ( $query->getVerb() === 'CREATE TEMPORARY' ) { // Temporary table creation is allowed return false; } $table = $query->getWriteTable(); if ( $table === null ) { // Parse error? Assume permanent. return true; } [ $db, $pt ] = $this->platform->getDatabaseAndTableIdentifier( $table ); $tempInfo = $this->sessionTempTables[$db][$pt] ?? null; return !$tempInfo || $tempInfo->pseudoPermanent; } /** * Register creation and dropping of temporary tables * * @param Query $query */ protected function registerTempTables( Query $query ) { $table = $query->getWriteTable(); if ( $table === null ) { return; } switch ( $query->getVerb() ) { case 'CREATE TEMPORARY': [ $db, $pt ] = $this->platform->getDatabaseAndTableIdentifier( $table ); $this->sessionTempTables[$db][$pt] = new TempTableInfo( $this->transactionManager->getTrxId(), (bool)( $query->getFlags() & self::QUERY_PSEUDO_PERMANENT ) ); break; case 'DROP': [ $db, $pt ] = $this->platform->getDatabaseAndTableIdentifier( $table ); unset( $this->sessionTempTables[$db][$pt] ); } } public function query( $sql, $fname = __METHOD__, $flags = 0 ) { if ( !( $sql instanceof Query ) ) { $flags = (int)$flags; // b/c; this field used to be a bool $sql = QueryBuilderFromRawSql::buildQuery( $sql, $flags, $this->currentDomain->getTablePrefix() ); } else { $flags = $sql->getFlags(); } // Make sure that this caller is allowed to issue this query statement $this->assertQueryIsCurrentlyAllowed( $sql->getVerb(), $fname ); // Send the query to the server and fetch any corresponding errors $status = $this->executeQuery( $sql, $fname, $flags ); if ( $status->res === false ) { // An error occurred; log, and, if needed, report an exception. // Errors that corrupt the transaction/session state cannot be silenced. $ignore = ( $this->flagsHolder::contains( $flags, self::QUERY_SILENCE_ERRORS ) && !$this->flagsHolder::contains( $status->flags, self::ERR_ABORT_SESSION ) && !$this->flagsHolder::contains( $status->flags, self::ERR_ABORT_TRX ) ); $this->reportQueryError( $status->message, $status->code, $sql->getSQL(), $fname, $ignore ); } return $status->res; } /** * Execute a query without enforcing public (non-Database) caller restrictions. * * Retry it if there is a recoverable connection loss (e.g. no important state lost). * * This does not precheck for transaction/session state errors or critical section errors. * * @see Database::query() * * @param Query $sql SQL statement * @param string $fname Name of the calling function * @param int $flags Bit field of ISQLPlatform::QUERY_* constants * @return QueryStatus * @throws DBUnexpectedError * @since 1.34 */ final protected function executeQuery( $sql, $fname, $flags ) { $this->assertHasConnectionHandle(); $isPermWrite = false; $isWrite = $sql->isWriteQuery(); if ( $isWrite ) { ChangedTablesTracker::recordQuery( $this->currentDomain, $sql ); // Permit temporary table writes on replica connections, but require a writable // master connection for writes to persistent tables. if ( $this->hasPermanentTable( $sql ) ) { $isPermWrite = true; $info = $this->getReadOnlyReason(); if ( $info ) { [ $reason, $source ] = $info; if ( $source === 'role' ) { throw new DBReadOnlyRoleError( $this, "Database is read-only: $reason" ); } else { throw new DBReadOnlyError( $this, "Database is read-only: $reason" ); } } // DBConnRef uses QUERY_REPLICA_ROLE to enforce replica roles during query() if ( $this->flagsHolder::contains( $sql->getFlags(), self::QUERY_REPLICA_ROLE ) ) { throw new DBReadOnlyRoleError( $this, "Cannot write; target role is DB_REPLICA" ); } } } // Whether a silent retry attempt is left for recoverable connection loss errors $retryLeft = !$this->flagsHolder::contains( $flags, self::QUERY_NO_RETRY ); $cs = $this->commenceCriticalSection( __METHOD__ ); do { // Start a DBO_TRX wrapper transaction as needed (throw an error on failure) if ( $this->beginIfImplied( $sql, $fname, $flags ) ) { // Since begin() was called, any connection loss was already handled $retryLeft = false; } // Send the query statement to the server and fetch any results. $status = $this->attemptQuery( $sql, $fname, $isPermWrite ); } while ( // An error occurred that can be recovered from via query retry $this->flagsHolder::contains( $status->flags, self::ERR_RETRY_QUERY ) && // The retry has not been exhausted (consume it now) // phpcs:ignore Generic.CodeAnalysis.AssignmentInCondition.FoundInWhileCondition $retryLeft && !( $retryLeft = false ) ); // Register creation and dropping of temporary tables if ( $status->res ) { $this->registerTempTables( $sql ); } $this->completeCriticalSection( __METHOD__, $cs ); return $status; } /** * Query method wrapper handling profiling, logging, affected row count tracking, and * automatic reconnections (without retry) on query failure due to connection loss * * Note that this does not handle DBO_TRX logic. * * This method handles profiling, debug logging, reconnection and the tracking of: * - write callers * - last write time * - affected row count of the last write * - whether writes occurred in a transaction * - last successful query time (confirming that the connection was not dropped) * * @see doSingleStatementQuery() * * @param Query $sql SQL statement * @param string $fname Name of the calling function * @param bool $isPermWrite Whether it's a query writing to permanent tables * @return QueryStatus statement result * @throws DBUnexpectedError */ private function attemptQuery( $sql, string $fname, bool $isPermWrite ) { // Transaction attributes before issuing this query $priorSessInfo = new CriticalSessionInfo( $this->transactionManager->getTrxId(), $this->transactionManager->explicitTrxActive(), $this->transactionManager->pendingWriteCallers(), $this->transactionManager->pendingPreCommitCallbackCallers(), $this->sessionNamedLocks, $this->sessionTempTables ); // Get the transaction-aware SQL string used for profiling $prefix = ( $this->replicationReporter->getTopologyRole() === self::ROLE_STREAMING_MASTER ) ? 'role-primary: ' : ''; // Start profile section if ( $sql->getCleanedSql() ) { $generalizedSql = $sql; $ps = $this->profiler ? ( $this->profiler )( $sql->getCleanedSql() ) : null; } else { $generalizedSql = new GeneralizedSql( $sql->getSQL(), $prefix ); $ps = $this->profiler ? ( $this->profiler )( $generalizedSql->stringify() ) : null; } // Add agent and calling method comments to the SQL $cStatement = $this->makeCommentedSql( $sql->getSQL(), $fname ); $startTime = microtime( true ); // Clear any overrides from a prior "query method". Note that this does not affect // any such methods that are currently invoking query() itself since those query // methods set these fields before returning. $this->lastEmulatedAffectedRows = null; $this->lastEmulatedInsertId = null; $status = $this->doSingleStatementQuery( $cStatement ); // End profile section $endTime = microtime( true ); $queryRuntime = max( $endTime - $startTime, 0.0 ); unset( $ps ); if ( $status->res !== false ) { $this->lastPing = $endTime; } $affectedRowCount = $status->rowsAffected; $returnedRowCount = $status->rowsReturned; $this->lastQueryAffectedRows = $affectedRowCount; if ( $status->res !== false ) { if ( $isPermWrite ) { $this->lastWriteTime = $startTime; if ( $this->trxLevel() ) { $this->transactionManager->transactionWritingIn( $this->getServerName(), $this->getDomainID(), $startTime ); $this->transactionManager->updateTrxWriteQueryReport( $sql->getSQL(), $queryRuntime, $affectedRowCount, $fname ); } } } $this->transactionManager->recordQueryCompletion( $generalizedSql, $startTime, $isPermWrite, $isPermWrite ? $affectedRowCount : $returnedRowCount, $this->getServerName() ); // Check if the query failed... $status->flags = $this->handleErroredQuery( $status, $sql, $fname, $queryRuntime, $priorSessInfo ); // Avoid the overhead of logging calls unless debug mode is enabled if ( $this->flagsHolder->getFlag( self::DBO_DEBUG ) ) { $this->logger->debug( "{method} [{runtime_ms}ms] {db_server}: {sql}", $this->getLogContext( [ 'method' => $fname, 'sql' => $sql->getSQL(), 'domain' => $this->getDomainID(), 'runtime_ms' => round( $queryRuntime * 1000, 3 ), 'db_log_category' => 'query' ] ) ); } return $status; } private function handleErroredQuery( QueryStatus $status, $sql, $fname, $queryRuntime, $priorSessInfo ) { $errflags = self::ERR_NONE; $error = $status->message; $errno = $status->code; if ( $status->res !== false ) { // Statement succeeded return $errflags; } if ( $this->isConnectionError( $errno ) ) { // Connection lost before or during the query... // Determine how to proceed given the lost session state $connLossFlag = $this->assessConnectionLoss( $sql->getVerb(), $queryRuntime, $priorSessInfo ); // Update session state tracking and try to reestablish a connection $reconnected = $this->replaceLostConnection( $errno, __METHOD__ ); // Check if important server-side session-level state was lost if ( $connLossFlag >= self::ERR_ABORT_SESSION ) { $ex = $this->getQueryException( $error, $errno, $sql->getSQL(), $fname ); $this->transactionManager->setSessionError( $ex ); } // Check if important server-side transaction-level state was lost if ( $connLossFlag >= self::ERR_ABORT_TRX ) { $ex = $this->getQueryException( $error, $errno, $sql->getSQL(), $fname ); $this->transactionManager->setTransactionError( $ex ); } // Check if the query should be retried (having made the reconnection attempt) if ( $connLossFlag === self::ERR_RETRY_QUERY ) { $errflags |= ( $reconnected ? self::ERR_RETRY_QUERY : self::ERR_ABORT_QUERY ); } else { $errflags |= $connLossFlag; } } elseif ( $this->isKnownStatementRollbackError( $errno ) ) { // Query error triggered a server-side statement-only rollback... $errflags |= self::ERR_ABORT_QUERY; if ( $this->trxLevel() ) { // Allow legacy callers to ignore such errors via QUERY_IGNORE_DBO_TRX and // try/catch. However, a deprecation notice will be logged on the next query. $cause = [ $error, $errno, $fname ]; $this->transactionManager->setTrxStatusIgnoredCause( $cause ); } } elseif ( $this->trxLevel() ) { // Some other error occurred during the query, within a transaction... // Server-side handling of errors during transactions varies widely depending on // the RDBMS type and configuration. There are several possible results: (a) the // whole transaction is rolled back, (b) only the queries after BEGIN are rolled // back, (c) the transaction is marked as "aborted" and a ROLLBACK is required // before other queries are permitted. For compatibility reasons, pessimistically // require a ROLLBACK query (not using SAVEPOINT) before allowing other queries. $ex = $this->getQueryException( $error, $errno, $sql->getSQL(), $fname ); $this->transactionManager->setTransactionError( $ex ); $errflags |= self::ERR_ABORT_TRX; } else { // Some other error occurred during the query, without a transaction... $errflags |= self::ERR_ABORT_QUERY; } return $errflags; } /** * @param string $sql * @param string $fname * @return string */ private function makeCommentedSql( $sql, $fname ): string { // Add trace comment to the begin of the sql string, right after the operator. // Or, for one-word queries (like "BEGIN" or COMMIT") add it to the end (T44598). // NOTE: Don't add varying ids such as request id or session id to the comment. // It would break aggregation of similar queries in analysis tools (see T193050#7512149) $encName = preg_replace( '/[\x00-\x1F\/]/', '-', "$fname {$this->agent}" ); return preg_replace( '/\s|$/', " /* $encName */ ", $sql, 1 ); } /** * Start an implicit transaction if DBO_TRX is enabled and no transaction is active * * @param Query $sql SQL statement * @param string $fname * @param int $flags Bit field of ISQLPlatform::QUERY_* constants * @return bool Whether an implicit transaction was started * @throws DBError */ private function beginIfImplied( $sql, $fname, $flags ) { if ( !$this->trxLevel() && $this->flagsHolder->hasApplicableImplicitTrxFlag( $flags ) ) { if ( $this->platform->isTransactableQuery( $sql ) ) { $this->begin( __METHOD__ . " ($fname)", self::TRANSACTION_INTERNAL ); $this->transactionManager->turnOnAutomatic(); return true; } } return false; } /** * Check if callers outside of Database can run the given query given the session state * * In order to keep the DB handle's session state tracking in sync, certain queries * like "USE", "BEGIN", "COMMIT", and "ROLLBACK" must not be issued directly from * outside callers. Such commands should only be issued through dedicated methods * like selectDomain(), begin(), commit(), and rollback(), respectively. * * This also checks if the session state tracking was corrupted by a prior exception. * * @param string $verb * @param string $fname * @throws DBUnexpectedError * @throws DBTransactionStateError */ private function assertQueryIsCurrentlyAllowed( string $verb, string $fname ) { if ( $verb === 'USE' ) { throw new DBUnexpectedError( $this, "Got USE query; use selectDomain() instead" ); } if ( $verb === 'ROLLBACK' ) { // Whole transaction rollback is used for recovery // @TODO: T269161; prevent "BEGIN"/"COMMIT"/"ROLLBACK" from outside callers return; } if ( $this->csmError ) { throw new DBTransactionStateError( $this, "Cannot execute query from $fname while session state is out of sync", [], $this->csmError ); } $this->transactionManager->assertSessionStatus( $this, $fname ); if ( $verb !== 'ROLLBACK TO SAVEPOINT' ) { $this->transactionManager->assertTransactionStatus( $this, $this->deprecationLogger, $fname ); } } /** * Determine how to handle a connection lost discovered during a query attempt * * This checks if explicit transactions, pending transaction writes, and important * session-level state (locks, temp tables) was lost. Point-in-time read snapshot loss * is considered acceptable for DBO_TRX logic. * * If state was lost, but that loss was discovered during a ROLLBACK that would have * destroyed that state anyway, treat the error as recoverable. * * @param string $verb SQL query verb * @param float $walltime How many seconds passes while attempting the query * @param CriticalSessionInfo $priorSessInfo Session state just before the query * @return int Recovery approach. One of the following ERR_* class constants: * - Database::ERR_RETRY_QUERY: reconnect silently, retry query * - Database::ERR_ABORT_QUERY: reconnect silently, do not retry query * - Database::ERR_ABORT_TRX: reconnect, throw error, enforce transaction rollback * - Database::ERR_ABORT_SESSION: reconnect, throw error, enforce session rollback */ private function assessConnectionLoss( string $verb, float $walltime, CriticalSessionInfo $priorSessInfo ) { if ( $walltime < self::DROPPED_CONN_BLAME_THRESHOLD_SEC ) { // Query failed quickly; the connection was probably lost before the query was sent $res = self::ERR_RETRY_QUERY; } else { // Query took a long time; the connection was probably lost during query execution $res = self::ERR_ABORT_QUERY; } // List of problems causing session/transaction state corruption $blockers = []; // Loss of named locks breaks future callers relying on those locks for critical sections foreach ( $priorSessInfo->namedLocks as $lockName => $lockInfo ) { if ( $lockInfo['trxId'] && $lockInfo['trxId'] === $priorSessInfo->trxId ) { // Treat lost locks acquired during the lost transaction as a transaction state // problem. Connection loss on ROLLBACK (non-SAVEPOINT) is tolerable since // rollback automatically triggered server-side. if ( $verb !== 'ROLLBACK' ) { $res = max( $res, self::ERR_ABORT_TRX ); $blockers[] = "named lock '$lockName'"; } } else { // Treat lost locks acquired either during prior transactions or during no // transaction as a session state problem. $res = max( $res, self::ERR_ABORT_SESSION ); $blockers[] = "named lock '$lockName'"; } } // Loss of temp tables breaks future callers relying on those tables for queries foreach ( $priorSessInfo->tempTables as $domainTempTables ) { foreach ( $domainTempTables as $tableName => $tableInfo ) { if ( $tableInfo->trxId && $tableInfo->trxId === $priorSessInfo->trxId ) { // Treat lost temp tables created during the lost transaction as a // transaction state problem. Connection loss on ROLLBACK (non-SAVEPOINT) // is tolerable since rollback automatically triggered server-side. if ( $verb !== 'ROLLBACK' ) { $res = max( $res, self::ERR_ABORT_TRX ); $blockers[] = "temp table '$tableName'"; } } else { // Treat lost temp tables created either during prior transactions or during // no transaction as a session state problem. $res = max( $res, self::ERR_ABORT_SESSION ); $blockers[] = "temp table '$tableName'"; } } } // Loss of transaction writes breaks future callers and DBO_TRX logic relying on those // writes to be atomic and still pending. Connection loss on ROLLBACK (non-SAVEPOINT) is // tolerable since rollback automatically triggered server-side. if ( $priorSessInfo->trxWriteCallers && $verb !== 'ROLLBACK' ) { $res = max( $res, self::ERR_ABORT_TRX ); $blockers[] = 'uncommitted writes'; } if ( $priorSessInfo->trxPreCommitCbCallers && $verb !== 'ROLLBACK' ) { $res = max( $res, self::ERR_ABORT_TRX ); $blockers[] = 'pre-commit callbacks'; } if ( $priorSessInfo->trxExplicit && $verb !== 'ROLLBACK' && $verb !== 'COMMIT' ) { // Transaction automatically rolled back, breaking the expectations of callers // relying on the continued existence of that transaction for things like atomic // writes, serializability, or reads from the same point-in-time snapshot. If the // connection loss occured on ROLLBACK (non-SAVEPOINT) or COMMIT, then we do not // need to mark the transaction state as corrupt, since no transaction would still // be open even if the query did succeed (T127428). $res = max( $res, self::ERR_ABORT_TRX ); $blockers[] = 'explicit transaction'; } if ( $blockers ) { $this->logger->warning( "cannot reconnect to {db_server} silently: {error}", $this->getLogContext( [ 'error' => 'session state loss (' . implode( ', ', $blockers ) . ')', 'exception' => new RuntimeException(), 'db_log_category' => 'connection' ] ) ); } return $res; } /** * Clean things up after session (and thus transaction) loss before reconnect */ private function handleSessionLossPreconnect() { // Clean up tracking of session-level things... // https://mariadb.com/kb/en/create-table/#create-temporary-table // https://www.postgresql.org/docs/9.2/static/sql-createtable.html (ignoring ON COMMIT) $this->sessionTempTables = []; // https://mariadb.com/kb/en/get_lock/ // https://www.postgresql.org/docs/9.4/static/functions-admin.html#FUNCTIONS-ADVISORY-LOCKS $this->sessionNamedLocks = []; // Session loss implies transaction loss (T67263) $this->transactionManager->onSessionLoss( $this ); // Clear additional subclass fields $this->doHandleSessionLossPreconnect(); } /** * Reset any additional subclass trx* and session* fields */ protected function doHandleSessionLossPreconnect() { // no-op } /** * Checks whether the cause of the error is detected to be a timeout. * * It returns false by default, and not all engines support detecting this yet. * If this returns false, it will be treated as a generic query error. * * @param int|string $errno Error number * @return bool * @since 1.39 */ protected function isQueryTimeoutError( $errno ) { return false; } /** * Report a query error * * If $ignore is set, emit a DEBUG level log entry and continue, * otherwise, emit an ERROR level log entry and throw an exception. * * @param string $error * @param int|string $errno * @param string $sql * @param string $fname * @param bool $ignore Whether to just log an error rather than throw an exception * @throws DBQueryError */ public function reportQueryError( $error, $errno, $sql, $fname, $ignore = false ) { if ( $ignore ) { $this->logger->debug( "SQL ERROR (ignored): $error", [ 'db_log_category' => 'query' ] ); } else { throw $this->getQueryExceptionAndLog( $error, $errno, $sql, $fname ); } } /** * @param string $error * @param string|int $errno * @param string $sql * @param string $fname * @return DBError */ private function getQueryExceptionAndLog( $error, $errno, $sql, $fname ) { // Information that instances of the same problem have in common should // not be normalized (T255202). $this->logger->error( "Error $errno from $fname, {error} {sql1line} {db_server}", $this->getLogContext( [ 'method' => __METHOD__, 'errno' => $errno, 'error' => $error, 'sql1line' => mb_substr( str_replace( "\n", "\\n", $sql ), 0, 5 * 1024 ), 'fname' => $fname, 'db_log_category' => 'query', 'exception' => new RuntimeException() ] ) ); return $this->getQueryException( $error, $errno, $sql, $fname ); } /** * @param string $error * @param string|int $errno * @param string $sql * @param string $fname * @return DBError */ private function getQueryException( $error, $errno, $sql, $fname ) { if ( $this->isQueryTimeoutError( $errno ) ) { return new DBQueryTimeoutError( $this, $error, $errno, $sql, $fname ); } elseif ( $this->isConnectionError( $errno ) ) { return new DBQueryDisconnectedError( $this, $error, $errno, $sql, $fname ); } else { return new DBQueryError( $this, $error, $errno, $sql, $fname ); } } /** * @param string $error * @return DBConnectionError */ final protected function newExceptionAfterConnectError( $error ) { // Connection was not fully initialized and is not safe for use. // Stash any error associated with the handle before destroying it. $this->lastConnectError = $error; $this->conn = null; $this->logger->error( "Error connecting to {db_server} as user {db_user}: {error}", $this->getLogContext( [ 'error' => $error, 'exception' => new RuntimeException(), 'db_log_category' => 'connection', ] ) ); return new DBConnectionError( $this, $error ); } /** * Get a SelectQueryBuilder bound to this connection. This is overridden by * DBConnRef. * * @return SelectQueryBuilder */ public function newSelectQueryBuilder(): SelectQueryBuilder { return new SelectQueryBuilder( $this ); } /** * Get a UnionQueryBuilder bound to this connection. This is overridden by * DBConnRef. * * @return UnionQueryBuilder */ public function newUnionQueryBuilder(): UnionQueryBuilder { return new UnionQueryBuilder( $this ); } /** * Get an UpdateQueryBuilder bound to this connection. This is overridden by * DBConnRef. * * @return UpdateQueryBuilder */ public function newUpdateQueryBuilder(): UpdateQueryBuilder { return new UpdateQueryBuilder( $this ); } /** * Get a DeleteQueryBuilder bound to this connection. This is overridden by * DBConnRef. * * @return DeleteQueryBuilder */ public function newDeleteQueryBuilder(): DeleteQueryBuilder { return new DeleteQueryBuilder( $this ); } /** * Get a InsertQueryBuilder bound to this connection. This is overridden by * DBConnRef. * * @return InsertQueryBuilder */ public function newInsertQueryBuilder(): InsertQueryBuilder { return new InsertQueryBuilder( $this ); } /** * Get a ReplaceQueryBuilder bound to this connection. This is overridden by * DBConnRef. * * @return ReplaceQueryBuilder */ public function newReplaceQueryBuilder(): ReplaceQueryBuilder { return new ReplaceQueryBuilder( $this ); } public function selectField( $tables, $var, $cond = '', $fname = __METHOD__, $options = [], $join_conds = [] ) { if ( $var === '*' ) { throw new DBUnexpectedError( $this, "Cannot use a * field" ); } elseif ( is_array( $var ) && count( $var ) !== 1 ) { throw new DBUnexpectedError( $this, 'Cannot use more than one field' ); } $options = $this->platform->normalizeOptions( $options ); $options['LIMIT'] = 1; $res = $this->select( $tables, $var, $cond, $fname, $options, $join_conds ); if ( $res === false ) { throw new DBUnexpectedError( $this, "Got false from select()" ); } $row = $res->fetchRow(); if ( $row === false ) { return false; } return reset( $row ); } public function selectFieldValues( $tables, $var, $cond = '', $fname = __METHOD__, $options = [], $join_conds = [] ): array { if ( $var === '*' ) { throw new DBUnexpectedError( $this, "Cannot use a * field" ); } elseif ( !is_string( $var ) ) { throw new DBUnexpectedError( $this, "Cannot use an array of fields" ); } $options = $this->platform->normalizeOptions( $options ); $res = $this->select( $tables, [ 'value' => $var ], $cond, $fname, $options, $join_conds ); if ( $res === false ) { throw new DBUnexpectedError( $this, "Got false from select()" ); } $values = []; foreach ( $res as $row ) { $values[] = $row->value; } return $values; } public function select( $tables, $vars, $conds = '', $fname = __METHOD__, $options = [], $join_conds = [] ) { $options = (array)$options; // Don't turn this into using platform directly, DatabaseMySQL overrides this. $sql = $this->selectSQLText( $tables, $vars, $conds, $fname, $options, $join_conds ); // Treat SELECT queries with FOR UPDATE as writes. This matches // how MySQL enforces read_only (FOR SHARE and LOCK IN SHADE MODE are allowed). $flags = in_array( 'FOR UPDATE', $options, true ) ? self::QUERY_CHANGE_ROWS : self::QUERY_CHANGE_NONE; $query = new Query( $sql, $flags, 'SELECT' ); return $this->query( $query, $fname ); } public function selectRow( $tables, $vars, $conds, $fname = __METHOD__, $options = [], $join_conds = [] ) { $options = (array)$options; $options['LIMIT'] = 1; $res = $this->select( $tables, $vars, $conds, $fname, $options, $join_conds ); if ( $res === false ) { throw new DBUnexpectedError( $this, "Got false from select()" ); } if ( !$res->numRows() ) { return false; } return $res->fetchObject(); } /** * @inheritDoc */ public function estimateRowCount( $tables, $var = '*', $conds = '', $fname = __METHOD__, $options = [], $join_conds = [] ): int { $conds = $this->platform->normalizeConditions( $conds, $fname ); $column = $this->platform->extractSingleFieldFromList( $var ); if ( is_string( $column ) && !in_array( $column, [ '*', '1' ] ) ) { $conds[] = "$column IS NOT NULL"; } $res = $this->select( $tables, [ 'rowcount' => 'COUNT(*)' ], $conds, $fname, $options, $join_conds ); $row = $res ? $res->fetchRow() : []; return isset( $row['rowcount'] ) ? (int)$row['rowcount'] : 0; } public function selectRowCount( $tables, $var = '*', $conds = '', $fname = __METHOD__, $options = [], $join_conds = [] ): int { $conds = $this->platform->normalizeConditions( $conds, $fname ); $column = $this->platform->extractSingleFieldFromList( $var ); if ( is_string( $column ) && !in_array( $column, [ '*', '1' ] ) ) { $conds[] = "$column IS NOT NULL"; } if ( in_array( 'DISTINCT', (array)$options ) ) { if ( $column === null ) { throw new DBUnexpectedError( $this, '$var cannot be empty when the DISTINCT option is given' ); } $innerVar = $column; } else { $innerVar = '1'; } $res = $this->select( [ 'tmp_count' => $this->platform->buildSelectSubquery( $tables, $innerVar, $conds, $fname, $options, $join_conds ) ], [ 'rowcount' => 'COUNT(*)' ], [], $fname ); $row = $res ? $res->fetchRow() : []; return isset( $row['rowcount'] ) ? (int)$row['rowcount'] : 0; } public function lockForUpdate( $table, $conds = '', $fname = __METHOD__, $options = [], $join_conds = [] ) { if ( !$this->trxLevel() && !$this->flagsHolder->hasImplicitTrxFlag() ) { throw new DBUnexpectedError( $this, __METHOD__ . ': no transaction is active nor is DBO_TRX set' ); } $options = (array)$options; $options[] = 'FOR UPDATE'; return $this->selectRowCount( $table, '*', $conds, $fname, $options, $join_conds ); } public function fieldExists( $table, $field, $fname = __METHOD__ ) { $info = $this->fieldInfo( $table, $field ); return (bool)$info; } abstract public function tableExists( $table, $fname = __METHOD__ ); public function indexExists( $table, $index, $fname = __METHOD__ ) { $info = $this->indexInfo( $table, $index, $fname ); return (bool)$info; } public function indexUnique( $table, $index, $fname = __METHOD__ ) { $info = $this->indexInfo( $table, $index, $fname ); return $info ? $info['unique'] : null; } /** * Get information about an index into an object * * @param string $table The unqualified name of a table * @param string $index Index name * @param string $fname Calling function name * @return array<string,mixed>|false Index info map; false if it does not exist * @phan-return array{unique:bool}|false */ abstract public function indexInfo( $table, $index, $fname = __METHOD__ ); public function insert( $table, $rows, $fname = __METHOD__, $options = [] ) { $query = $this->platform->dispatchingInsertSqlText( $table, $rows, $options ); if ( !$query ) { return true; } $this->query( $query, $fname ); if ( $this->strictWarnings ) { $this->checkInsertWarnings( $query, $fname ); } return true; } /** * Check for warnings after performing an INSERT query, and throw exceptions * if necessary. * * @param Query $query * @param string $fname * @return void */ protected function checkInsertWarnings( Query $query, $fname ) { } public function update( $table, $set, $conds, $fname = __METHOD__, $options = [] ) { $query = $this->platform->updateSqlText( $table, $set, $conds, $options ); $this->query( $query, $fname ); return true; } public function databasesAreIndependent() { return false; } final public function selectDomain( $domain ) { $cs = $this->commenceCriticalSection( __METHOD__ ); try { $this->doSelectDomain( DatabaseDomain::newFromId( $domain ) ); } catch ( DBError $e ) { $this->completeCriticalSection( __METHOD__, $cs ); throw $e; } $this->completeCriticalSection( __METHOD__, $cs ); } /** * @param DatabaseDomain $domain * @throws DBConnectionError * @throws DBError * @since 1.32 */ protected function doSelectDomain( DatabaseDomain $domain ) { $this->currentDomain = $domain; $this->platform->setCurrentDomain( $this->currentDomain ); } public function getDBname() { return $this->currentDomain->getDatabase(); } public function getServer() { return $this->connectionParams[self::CONN_HOST] ?? null; } public function getServerName() { return $this->serverName ?? $this->getServer() ?? 'unknown'; } public function addQuotes( $s ) { if ( $s instanceof RawSQLValue ) { return $s->toSql(); } if ( $s instanceof Blob ) { $s = $s->fetch(); } if ( $s === null ) { return 'NULL'; } elseif ( is_bool( $s ) ) { return (string)(int)$s; } elseif ( is_int( $s ) ) { return (string)$s; } else { return "'" . $this->strencode( $s ) . "'"; } } public function expr( string $field, string $op, $value ): Expression { return new Expression( $field, $op, $value ); } public function andExpr( array $conds ): AndExpressionGroup { return AndExpressionGroup::newFromArray( $conds ); } public function orExpr( array $conds ): OrExpressionGroup { return OrExpressionGroup::newFromArray( $conds ); } public function replace( $table, $uniqueKeys, $rows, $fname = __METHOD__ ) { $uniqueKey = $this->platform->normalizeUpsertParams( $uniqueKeys, $rows ); if ( !$rows ) { return; } $affectedRowCount = 0; $insertId = null; $this->startAtomic( $fname, self::ATOMIC_CANCELABLE ); try { foreach ( $rows as $row ) { // Delete any conflicting rows (including ones inserted from $rows) $query = $this->platform->deleteSqlText( $table, [ $this->platform->makeKeyCollisionCondition( [ $row ], $uniqueKey ) ] ); $this->query( $query, $fname ); // Insert the new row $query = $this->platform->dispatchingInsertSqlText( $table, $row, [] ); $this->query( $query, $fname ); $affectedRowCount += $this->lastQueryAffectedRows; $insertId = $insertId ?: $this->lastQueryInsertId; } $this->endAtomic( $fname ); } catch ( DBError $e ) { $this->cancelAtomic( $fname ); throw $e; } $this->lastEmulatedAffectedRows = $affectedRowCount; $this->lastEmulatedInsertId = $insertId; } public function upsert( $table, array $rows, $uniqueKeys, array $set, $fname = __METHOD__ ) { $uniqueKey = $this->platform->normalizeUpsertParams( $uniqueKeys, $rows ); if ( !$rows ) { return true; } $this->platform->assertValidUpsertSetArray( $set, $uniqueKey, $rows ); $encTable = $this->tableName( $table ); $sqlColumnAssignments = $this->makeList( $set, self::LIST_SET ); // Get any AUTO_INCREMENT/SERIAL column for this table so we can set insertId() $autoIncrementColumn = $this->getInsertIdColumnForUpsert( $table ); // Check if there is a SQL assignment expression in $set (as generated by SQLPlatform::buildExcludedValue) $useWith = (bool)array_filter( $set, static function ( $v, $k ) { return $v instanceof RawSQLValue || is_int( $k ); }, ARRAY_FILTER_USE_BOTH ); // Subclasses might need explicit type casting within "WITH...AS (VALUES ...)" // so that these CTE rows can be referenced within the SET clause assigments. $typeByColumn = $useWith ? $this->getValueTypesForWithClause( $table ) : []; $first = true; $affectedRowCount = 0; $insertId = null; $this->startAtomic( $fname, self::ATOMIC_CANCELABLE ); try { foreach ( $rows as $row ) { // Update any existing conflicting row (including ones inserted from $rows) [ $sqlColumns, $sqlTuples, $sqlVals ] = $this->platform->makeInsertLists( [ $row ], '__', $typeByColumn ); $sqlConditions = $this->platform->makeKeyCollisionCondition( [ $row ], $uniqueKey ); $query = new Query( ( $useWith ? "WITH __VALS ($sqlVals) AS (VALUES $sqlTuples) " : "" ) . "UPDATE $encTable SET $sqlColumnAssignments " . "WHERE ($sqlConditions)", self::QUERY_CHANGE_ROWS, 'UPDATE', $table ); $this->query( $query, $fname ); $rowsUpdated = $this->lastQueryAffectedRows; $affectedRowCount += $rowsUpdated; if ( $rowsUpdated > 0 ) { // Conflicting row found and updated if ( $first && $autoIncrementColumn !== null ) { // @TODO: use "RETURNING" instead (when supported by SQLite) $query = new Query( "SELECT $autoIncrementColumn AS id FROM $encTable " . "WHERE ($sqlConditions)", self::QUERY_CHANGE_NONE, 'SELECT' ); $sRes = $this->query( $query, $fname, self::QUERY_CHANGE_ROWS ); $insertId = (int)$sRes->fetchRow()['id']; } } else { // No conflicting row found $query = new Query( "INSERT INTO $encTable ($sqlColumns) VALUES $sqlTuples", self::QUERY_CHANGE_ROWS, 'INSERT', $table ); $this->query( $query, $fname ); $affectedRowCount += $this->lastQueryAffectedRows; } $first = false; } $this->endAtomic( $fname ); } catch ( DBError $e ) { $this->cancelAtomic( $fname ); throw $e; } $this->lastEmulatedAffectedRows = $affectedRowCount; $this->lastEmulatedInsertId = $insertId; return true; } /** * @param string $table The unqualified name of a table * @return string|null The AUTO_INCREMENT/SERIAL column; null if not needed */ protected function getInsertIdColumnForUpsert( $table ) { return null; } /** * @param string $table The unqualified name of a table * @return array<string,string> Map of (column => type); [] if not needed */ protected function getValueTypesForWithClause( $table ) { return []; } public function deleteJoin( $delTable, $joinTable, $delVar, $joinVar, $conds, $fname = __METHOD__ ) { $sql = $this->platform->deleteJoinSqlText( $delTable, $joinTable, $delVar, $joinVar, $conds ); $query = new Query( $sql, self::QUERY_CHANGE_ROWS, 'DELETE', $delTable ); $this->query( $query, $fname ); } public function delete( $table, $conds, $fname = __METHOD__ ) { $this->query( $this->platform->deleteSqlText( $table, $conds ), $fname ); return true; } final public function insertSelect( $destTable, $srcTable, $varMap, $conds, $fname = __METHOD__, $insertOptions = [], $selectOptions = [], $selectJoinConds = [] ) { static $hints = [ 'NO_AUTO_COLUMNS' ]; $insertOptions = $this->platform->normalizeOptions( $insertOptions ); $selectOptions = $this->platform->normalizeOptions( $selectOptions ); if ( $this->cliMode && $this->isInsertSelectSafe( $insertOptions, $selectOptions, $fname ) ) { // For massive migrations with downtime, we don't want to select everything // into memory and OOM, so do all this native on the server side if possible. $this->doInsertSelectNative( $destTable, $srcTable, $varMap, $conds, $fname, array_diff( $insertOptions, $hints ), $selectOptions, $selectJoinConds ); } else { $this->doInsertSelectGeneric( $destTable, $srcTable, $varMap, $conds, $fname, array_diff( $insertOptions, $hints ), $selectOptions, $selectJoinConds ); } return true; } /** * @param array $insertOptions * @param array $selectOptions * @param string $fname * @return bool Whether an INSERT SELECT with these options will be replication safe * @since 1.31 */ protected function isInsertSelectSafe( array $insertOptions, array $selectOptions, $fname ) { return true; } /** * Implementation of insertSelect() based on select() and insert() * * @see IDatabase::insertSelect() * @param string $destTable Unqualified name of destination table * @param string|array $srcTable Unqualified name of source table * @param array $varMap * @param array $conds * @param string $fname * @param array $insertOptions * @param array $selectOptions * @param array $selectJoinConds * @since 1.35 */ private function doInsertSelectGeneric( $destTable, $srcTable, array $varMap, $conds, $fname, array $insertOptions, array $selectOptions, $selectJoinConds ) { // For web requests, do a locking SELECT and then INSERT. This puts the SELECT burden // on only the primary DB (without needing row-based-replication). It also makes it easy to // know how big the INSERT is going to be. $fields = []; foreach ( $varMap as $dstColumn => $sourceColumnOrSql ) { $fields[] = $this->platform->fieldNameWithAlias( $sourceColumnOrSql, $dstColumn ); } $res = $this->select( $srcTable, implode( ',', $fields ), $conds, $fname, array_merge( $selectOptions, [ 'FOR UPDATE' ] ), $selectJoinConds ); $affectedRowCount = 0; $insertId = null; if ( $res ) { $this->startAtomic( $fname, self::ATOMIC_CANCELABLE ); try { $rows = []; foreach ( $res as $row ) { $rows[] = (array)$row; } // Avoid inserts that are too huge $rowBatches = array_chunk( $rows, $this->nonNativeInsertSelectBatchSize ); foreach ( $rowBatches as $rows ) { $query = $this->platform->dispatchingInsertSqlText( $destTable, $rows, $insertOptions ); $this->query( $query, $fname ); $affectedRowCount += $this->lastQueryAffectedRows; $insertId = $insertId ?: $this->lastQueryInsertId; } $this->endAtomic( $fname ); } catch ( DBError $e ) { $this->cancelAtomic( $fname ); throw $e; } } $this->lastEmulatedAffectedRows = $affectedRowCount; $this->lastEmulatedInsertId = $insertId; } /** * Native server-side implementation of insertSelect() for situations where * we don't want to select everything into memory * * @see IDatabase::insertSelect() * @param string $destTable The unqualified name of destination table * @param string|array $srcTable The unqualified name of source table * @param array $varMap * @param array $conds * @param string $fname * @param array $insertOptions * @param array $selectOptions * @param array $selectJoinConds * @since 1.35 */ protected function doInsertSelectNative( $destTable, $srcTable, array $varMap, $conds, $fname, array $insertOptions, array $selectOptions, $selectJoinConds ) { $sql = $this->platform->insertSelectNativeSqlText( $destTable, $srcTable, $varMap, $conds, $fname, $insertOptions, $selectOptions, $selectJoinConds ); $query = new Query( $sql, self::QUERY_CHANGE_ROWS, 'INSERT', $destTable ); $this->query( $query, $fname ); } /** * Do not use this method outside of Database/DBError classes * * @param int|string $errno * @return bool Whether the given query error was a connection drop * @since 1.38 */ protected function isConnectionError( $errno ) { return false; } /** * @param int|string $errno * @return bool Whether it is known that the last query error only caused statement rollback * @note This is for backwards compatibility for callers catching DBError exceptions in * order to ignore problems like duplicate key errors or foreign key violations * @since 1.39 */ protected function isKnownStatementRollbackError( $errno ) { return false; // don't know; it could have caused a transaction rollback } /** * @inheritDoc */ public function serverIsReadOnly() { return false; } final public function onTransactionResolution( callable $callback, $fname = __METHOD__ ) { $this->transactionManager->onTransactionResolution( $this, $callback, $fname ); } final public function onTransactionCommitOrIdle( callable $callback, $fname = __METHOD__ ) { if ( !$this->trxLevel() && $this->getTransactionRoundId() ) { // This DB handle is set to participate in LoadBalancer transaction rounds and // an explicit transaction round is active. Start an implicit transaction on this // DB handle (setting trxAutomatic) similar to how query() does in such situations. $this->begin( __METHOD__, self::TRANSACTION_INTERNAL ); } $this->transactionManager->addPostCommitOrIdleCallback( $callback, $fname ); if ( !$this->trxLevel() ) { $dbErrors = []; $this->runOnTransactionIdleCallbacks( self::TRIGGER_IDLE, $dbErrors ); if ( $dbErrors ) { throw $dbErrors[0]; } } } final public function onTransactionPreCommitOrIdle( callable $callback, $fname = __METHOD__ ) { if ( !$this->trxLevel() && $this->getTransactionRoundId() ) { // This DB handle is set to participate in LoadBalancer transaction rounds and // an explicit transaction round is active. Start an implicit transaction on this // DB handle (setting trxAutomatic) similar to how query() does in such situations. $this->begin( __METHOD__, self::TRANSACTION_INTERNAL ); } if ( $this->trxLevel() ) { $this->transactionManager->addPreCommitOrIdleCallback( $callback, $fname ); } else { // No transaction is active nor will start implicitly, so make one for this callback $this->startAtomic( __METHOD__, self::ATOMIC_CANCELABLE ); try { $callback( $this ); } catch ( Throwable $e ) { // Avoid confusing error reporting during critical section errors if ( !$this->csmError ) { $this->cancelAtomic( __METHOD__ ); } throw $e; } $this->endAtomic( __METHOD__ ); } } final public function onAtomicSectionCancel( callable $callback, $fname = __METHOD__ ) { $this->transactionManager->onAtomicSectionCancel( $this, $callback, $fname ); } final public function setTransactionListener( $name, ?callable $callback = null ) { $this->transactionManager->setTransactionListener( $name, $callback ); } /** * Whether to disable running of post-COMMIT/ROLLBACK callbacks * * @internal This method should not be used outside of Database/LoadBalancer * * @since 1.28 * @param bool $suppress */ final public function setTrxEndCallbackSuppression( $suppress ) { $this->transactionManager->setTrxEndCallbackSuppression( $suppress ); } /** * Consume and run any "on transaction idle/resolution" callbacks * * @internal This method should not be used outside of Database/LoadBalancer * * @since 1.20 * @param int $trigger IDatabase::TRIGGER_* constant * @param DBError[] &$errors DB exceptions caught [returned] * @return int Number of callbacks attempted * @throws DBUnexpectedError * @throws Throwable Any non-DBError exception thrown by a callback */ public function runOnTransactionIdleCallbacks( $trigger, array &$errors = [] ) { if ( $this->trxLevel() ) { throw new DBUnexpectedError( $this, __METHOD__ . ': a transaction is still open' ); } if ( $this->transactionManager->isEndCallbacksSuppressed() ) { // Execution deferred by LoadBalancer for explicit execution later return 0; } $cs = $this->commenceCriticalSection( __METHOD__ ); $count = 0; $autoTrx = $this->flagsHolder->hasImplicitTrxFlag(); // automatic begin() enabled? // Drain the queues of transaction "idle" and "end" callbacks until they are empty do { $callbackEntries = $this->transactionManager->consumeEndCallbacks( $trigger ); $count += count( $callbackEntries ); foreach ( $callbackEntries as $entry ) { $this->flagsHolder->clearFlag( self::DBO_TRX ); // make each query its own transaction try { $entry[0]( $trigger, $this ); } catch ( DBError $ex ) { call_user_func( $this->errorLogger, $ex ); $errors[] = $ex; // Some callbacks may use startAtomic/endAtomic, so make sure // their transactions are ended so other callbacks don't fail if ( $this->trxLevel() ) { $this->rollback( __METHOD__, self::FLUSHING_INTERNAL ); } } finally { if ( $autoTrx ) { $this->flagsHolder->setFlag( self::DBO_TRX ); // restore automatic begin() } else { $this->flagsHolder->clearFlag( self::DBO_TRX ); // restore auto-commit } } } } while ( $this->transactionManager->countPostCommitOrIdleCallbacks() ); $this->completeCriticalSection( __METHOD__, $cs ); return $count; } /** * Actually run any "transaction listener" callbacks * * @internal This method should not be used outside of Database/LoadBalancer * * @since 1.20 * @param int $trigger IDatabase::TRIGGER_* constant * @param DBError[] &$errors DB exceptions caught [returned] * @throws Throwable Any non-DBError exception thrown by a callback */ public function runTransactionListenerCallbacks( $trigger, array &$errors = [] ) { if ( $this->transactionManager->isEndCallbacksSuppressed() ) { // Execution deferred by LoadBalancer for explicit execution later return; } // These callbacks should only be registered in setup, thus no iteration is needed foreach ( $this->transactionManager->getRecurringCallbacks() as $callback ) { try { $callback( $trigger, $this ); } catch ( DBError $ex ) { ( $this->errorLogger )( $ex ); $errors[] = $ex; } } } /** * Handle "on transaction idle/resolution" and "transaction listener" callbacks post-COMMIT * * @throws DBError The first DBError exception thrown by a callback * @throws Throwable Any non-DBError exception thrown by a callback */ private function runTransactionPostCommitCallbacks() { $dbErrors = []; $this->runOnTransactionIdleCallbacks( self::TRIGGER_COMMIT, $dbErrors ); $this->runTransactionListenerCallbacks( self::TRIGGER_COMMIT, $dbErrors ); $this->lastEmulatedAffectedRows = 0; // for the sake of consistency if ( $dbErrors ) { throw $dbErrors[0]; } } /** * Handle "on transaction idle/resolution" and "transaction listener" callbacks post-ROLLBACK * * This will suppress and log any DBError exceptions * * @throws Throwable Any non-DBError exception thrown by a callback */ private function runTransactionPostRollbackCallbacks() { $this->runOnTransactionIdleCallbacks( self::TRIGGER_ROLLBACK ); $this->runTransactionListenerCallbacks( self::TRIGGER_ROLLBACK ); $this->lastEmulatedAffectedRows = 0; // for the sake of consistency } final public function startAtomic( $fname = __METHOD__, $cancelable = self::ATOMIC_NOT_CANCELABLE ) { $cs = $this->commenceCriticalSection( __METHOD__ ); if ( $this->trxLevel() ) { // This atomic section is only one part of a larger transaction $sectionOwnsTrx = false; } else { // Start an implicit transaction (sets trxAutomatic) try { $this->begin( $fname, self::TRANSACTION_INTERNAL ); } catch ( DBError $e ) { $this->completeCriticalSection( __METHOD__, $cs ); throw $e; } if ( $this->flagsHolder->hasImplicitTrxFlag() ) { // This DB handle participates in LoadBalancer transaction rounds; all atomic // sections should be buffered into one transaction (e.g. to keep web requests // transactional). Note that an implicit transaction round is considered to be // active when no there is no explicit transaction round. $sectionOwnsTrx = false; } else { // This DB handle does not participate in LoadBalancer transaction rounds; // each topmost atomic section will use its own transaction. $sectionOwnsTrx = true; } $this->transactionManager->setAutomaticAtomic( $sectionOwnsTrx ); } if ( $cancelable === self::ATOMIC_CANCELABLE ) { if ( $sectionOwnsTrx ) { // This atomic section is synonymous with the whole transaction; just // use full COMMIT/ROLLBACK in endAtomic()/cancelAtomic(), respectively $savepointId = self::NOT_APPLICABLE; } else { // This atomic section is only part of the whole transaction; use a SAVEPOINT // query so that its changes can be cancelled without losing the rest of the // transaction (e.g. changes from other sections or from outside of sections) try { $savepointId = $this->transactionManager->nextSavePointId( $this, $fname ); $sql = $this->platform->savepointSqlText( $savepointId ); $query = new Query( $sql, self::QUERY_CHANGE_TRX, 'SAVEPOINT' ); $this->query( $query, $fname ); } catch ( DBError $e ) { $this->completeCriticalSection( __METHOD__, $cs, $e ); throw $e; } } } else { $savepointId = null; } $sectionId = new AtomicSectionIdentifier; $this->transactionManager->addToAtomicLevels( $fname, $sectionId, $savepointId ); $this->completeCriticalSection( __METHOD__, $cs ); return $sectionId; } final public function endAtomic( $fname = __METHOD__ ) { [ $savepointId, $sectionId ] = $this->transactionManager->onEndAtomic( $this, $fname ); $runPostCommitCallbacks = false; $cs = $this->commenceCriticalSection( __METHOD__ ); // Remove the last section (no need to re-index the array) $finalLevelOfImplicitTrxPopped = $this->transactionManager->popAtomicLevel(); try { if ( $finalLevelOfImplicitTrxPopped ) { $this->commit( $fname, self::FLUSHING_INTERNAL ); $runPostCommitCallbacks = true; } elseif ( $savepointId !== null && $savepointId !== self::NOT_APPLICABLE ) { $sql = $this->platform->releaseSavepointSqlText( $savepointId ); $query = new Query( $sql, self::QUERY_CHANGE_TRX, 'RELEASE SAVEPOINT' ); $this->query( $query, $fname ); } } catch ( DBError $e ) { $this->completeCriticalSection( __METHOD__, $cs, $e ); throw $e; } $this->transactionManager->onEndAtomicInCriticalSection( $sectionId ); $this->completeCriticalSection( __METHOD__, $cs ); if ( $runPostCommitCallbacks ) { $this->runTransactionPostCommitCallbacks(); } } final public function cancelAtomic( $fname = __METHOD__, ?AtomicSectionIdentifier $sectionId = null ) { $this->transactionManager->onCancelAtomicBeforeCriticalSection( $this, $fname ); $pos = $this->transactionManager->getPositionFromSectionId( $sectionId ); if ( $pos < 0 ) { throw new DBUnexpectedError( $this, "Atomic section not found (for $fname)" ); } $cs = $this->commenceCriticalSection( __METHOD__ ); $runPostRollbackCallbacks = false; [ $savedFname, $excisedSectionIds, $newTopSectionId, $savedSectionId, $savepointId ] = $this->transactionManager->cancelAtomic( $pos ); try { if ( $savedFname !== $fname ) { $e = new DBUnexpectedError( $this, "Invalid atomic section ended (got $fname but expected $savedFname)" ); $this->completeCriticalSection( __METHOD__, $cs, $e ); throw $e; } // Remove the last section (no need to re-index the array) $this->transactionManager->popAtomicLevel(); $excisedSectionIds[] = $savedSectionId; $newTopSectionId = $this->transactionManager->currentAtomicSectionId(); if ( $savepointId !== null ) { // Rollback the transaction changes proposed within this atomic section if ( $savepointId === self::NOT_APPLICABLE ) { // Atomic section started the transaction; rollback the whole transaction // and trigger cancellation callbacks for all active atomic sections $this->rollback( $fname, self::FLUSHING_INTERNAL ); $runPostRollbackCallbacks = true; } else { // Atomic section nested within the transaction; rollback the transaction // to the state prior to this section and trigger its cancellation callbacks $sql = $this->platform->rollbackToSavepointSqlText( $savepointId ); $query = new Query( $sql, self::QUERY_CHANGE_TRX, 'ROLLBACK TO SAVEPOINT' ); $this->query( $query, $fname ); $this->transactionManager->setTrxStatusToOk(); // no exception; recovered $this->transactionManager->runOnAtomicSectionCancelCallbacks( $this, self::TRIGGER_CANCEL, $excisedSectionIds ); } } else { // Put the transaction into an error state if it's not already in one $trxError = new DBUnexpectedError( $this, "Uncancelable atomic section canceled (got $fname)" ); $this->transactionManager->setTransactionError( $trxError ); } } finally { // Fix up callbacks owned by the sections that were just cancelled. // All callbacks should have an owner that is present in trxAtomicLevels. $this->transactionManager->modifyCallbacksForCancel( $excisedSectionIds, $newTopSectionId ); } $this->lastEmulatedAffectedRows = 0; // for the sake of consistency $this->completeCriticalSection( __METHOD__, $cs ); if ( $runPostRollbackCallbacks ) { $this->runTransactionPostRollbackCallbacks(); } } final public function doAtomicSection( $fname, callable $callback, $cancelable = self::ATOMIC_NOT_CANCELABLE ) { $sectionId = $this->startAtomic( $fname, $cancelable ); try { $res = $callback( $this, $fname ); } catch ( Throwable $e ) { // Avoid confusing error reporting during critical section errors if ( !$this->csmError ) { $this->cancelAtomic( $fname, $sectionId ); } throw $e; } $this->endAtomic( $fname ); return $res; } final public function begin( $fname = __METHOD__, $mode = self::TRANSACTION_EXPLICIT ) { static $modes = [ self::TRANSACTION_EXPLICIT, self::TRANSACTION_INTERNAL ]; if ( !in_array( $mode, $modes, true ) ) { throw new DBUnexpectedError( $this, "$fname: invalid mode parameter '$mode'" ); } $this->transactionManager->onBegin( $this, $fname ); if ( $this->flagsHolder->hasImplicitTrxFlag() && $mode !== self::TRANSACTION_INTERNAL ) { $msg = "$fname: implicit transaction expected (DBO_TRX set)"; throw new DBUnexpectedError( $this, $msg ); } $this->assertHasConnectionHandle(); $cs = $this->commenceCriticalSection( __METHOD__ ); $timeStart = microtime( true ); try { $this->doBegin( $fname ); } catch ( DBError $e ) { $this->completeCriticalSection( __METHOD__, $cs ); throw $e; } $timeEnd = microtime( true ); // Treat "BEGIN" as a trivial query to gauge the RTT delay $rtt = max( $timeEnd - $timeStart, 0.0 ); $this->transactionManager->onBeginInCriticalSection( $mode, $fname, $rtt ); $this->replicationReporter->resetReplicationLagStatus( $this ); $this->completeCriticalSection( __METHOD__, $cs ); } /** * Issues the BEGIN command to the database server. * * @see Database::begin() * @param string $fname * @throws DBError */ protected function doBegin( $fname ) { $query = new Query( 'BEGIN', self::QUERY_CHANGE_TRX, 'BEGIN' ); $this->query( $query, $fname ); } final public function commit( $fname = __METHOD__, $flush = self::FLUSHING_ONE ) { static $modes = [ self::FLUSHING_ONE, self::FLUSHING_ALL_PEERS, self::FLUSHING_INTERNAL ]; if ( !in_array( $flush, $modes, true ) ) { throw new DBUnexpectedError( $this, "$fname: invalid flush parameter '$flush'" ); } if ( !$this->transactionManager->onCommit( $this, $fname, $flush ) ) { return; } $this->assertHasConnectionHandle(); $this->runOnTransactionPreCommitCallbacks(); $cs = $this->commenceCriticalSection( __METHOD__ ); try { if ( $this->trxLevel() ) { $query = new Query( 'COMMIT', self::QUERY_CHANGE_TRX, 'COMMIT' ); $this->query( $query, $fname ); } } catch ( DBError $e ) { $this->completeCriticalSection( __METHOD__, $cs ); throw $e; } $lastWriteTime = $this->transactionManager->onCommitInCriticalSection( $this ); if ( $lastWriteTime ) { $this->lastWriteTime = $lastWriteTime; } // With FLUSHING_ALL_PEERS, callbacks will run when requested by a dedicated phase // within LoadBalancer. With FLUSHING_INTERNAL, callbacks will run when requested by // the Database caller during a safe point. This avoids isolation and recursion issues. if ( $flush === self::FLUSHING_ONE ) { $this->runTransactionPostCommitCallbacks(); } $this->completeCriticalSection( __METHOD__, $cs ); } final public function rollback( $fname = __METHOD__, $flush = self::FLUSHING_ONE ) { if ( $flush !== self::FLUSHING_INTERNAL && $flush !== self::FLUSHING_ALL_PEERS && $this->flagsHolder->hasImplicitTrxFlag() ) { throw new DBUnexpectedError( $this, "$fname: Expected mass rollback of all peer transactions (DBO_TRX set)" ); } if ( !$this->trxLevel() ) { $this->transactionManager->setTrxStatusToNone(); $this->transactionManager->clearPreEndCallbacks(); if ( $this->transactionManager->trxLevel() === TransactionManager::STATUS_TRX_ERROR ) { $this->logger->info( "$fname: acknowledged server-side transaction loss on {db_server}", $this->getLogContext() ); } return; } $this->assertHasConnectionHandle(); if ( $this->csmError ) { // Since the session state is corrupt, we cannot just rollback the transaction // while preserving the non-transaction session state. The handle will remain // marked as corrupt until flushSession() is called to reset the connection // and deal with any remaining callbacks. $this->logger->info( "$fname: acknowledged client-side transaction loss on {db_server}", $this->getLogContext() ); return; } $cs = $this->commenceCriticalSection( __METHOD__ ); if ( $this->trxLevel() ) { // Disconnects cause rollback anyway, so ignore those errors $query = new Query( $this->platform->rollbackSqlText(), self::QUERY_SILENCE_ERRORS | self::QUERY_CHANGE_TRX, 'ROLLBACK' ); $this->query( $query, $fname ); } $this->transactionManager->onRollbackInCriticalSection( $this ); // With FLUSHING_ALL_PEERS, callbacks will run when requested by a dedicated phase // within LoadBalancer. With FLUSHING_INTERNAL, callbacks will run when requested by // the Database caller during a safe point. This avoids isolation and recursion issues. if ( $flush === self::FLUSHING_ONE ) { $this->runTransactionPostRollbackCallbacks(); } $this->completeCriticalSection( __METHOD__, $cs ); } /** * @internal Only for tests and highly discouraged * @param TransactionManager $transactionManager */ public function setTransactionManager( TransactionManager $transactionManager ) { $this->transactionManager = $transactionManager; } public function flushSession( $fname = __METHOD__, $flush = self::FLUSHING_ONE ) { if ( $flush !== self::FLUSHING_INTERNAL && $flush !== self::FLUSHING_ALL_PEERS && $this->flagsHolder->hasImplicitTrxFlag() ) { throw new DBUnexpectedError( $this, "$fname: Expected mass flush of all peer connections (DBO_TRX set)" ); } if ( $this->csmError ) { // If a critical section error occurred, such as Excimer timeout exceptions raised // before a query response was marshalled, destroy the connection handle and reset // the session state tracking variables. The value of trxLevel() is irrelevant here, // and, in fact, might be 1 due to rollback() deferring critical section recovery. $this->logger->info( "$fname: acknowledged client-side session loss on {db_server}", $this->getLogContext() ); $this->csmError = null; $this->csmFname = null; $this->replaceLostConnection( 2048, __METHOD__ ); return; } if ( $this->trxLevel() ) { // Any existing transaction should have been rolled back already throw new DBUnexpectedError( $this, "$fname: transaction still in progress (not yet rolled back)" ); } if ( $this->transactionManager->sessionStatus() === TransactionManager::STATUS_SESS_ERROR ) { // If the session state was already lost due to either an unacknowledged session // state loss error (e.g. dropped connection) or an explicit connection close call, // then there is nothing to do here. Note that in such cases, even temporary tables // and server-side config variables are lost (invocation of this method is assumed // to imply that such losses are tolerable). $this->logger->info( "$fname: acknowledged server-side session loss on {db_server}", $this->getLogContext() ); } elseif ( $this->isOpen() ) { // Connection handle exists; server-side session state must be flushed $this->doFlushSession( $fname ); $this->sessionNamedLocks = []; } $this->transactionManager->clearSessionError(); } /** * Reset the server-side session state for named locks and table locks * * Connection and query errors will be suppressed and logged * * @param string $fname * @since 1.38 */ protected function doFlushSession( $fname ) { // no-op } public function flushSnapshot( $fname = __METHOD__, $flush = self::FLUSHING_ONE ) { $this->transactionManager->onFlushSnapshot( $this, $fname, $flush, $this->getTransactionRoundId() ); if ( $this->transactionManager->sessionStatus() === TransactionManager::STATUS_SESS_ERROR || $this->transactionManager->trxStatus() === TransactionManager::STATUS_TRX_ERROR ) { $this->rollback( $fname, self::FLUSHING_INTERNAL ); } else { $this->commit( $fname, self::FLUSHING_INTERNAL ); } } public function duplicateTableStructure( $oldName, $newName, $temporary = false, $fname = __METHOD__ ) { throw new RuntimeException( __METHOD__ . ' is not implemented in descendant class' ); } public function listTables( $prefix = null, $fname = __METHOD__ ) { throw new RuntimeException( __METHOD__ . ' is not implemented in descendant class' ); } public function affectedRows() { $this->lastEmulatedAffectedRows ??= $this->lastQueryAffectedRows; return $this->lastEmulatedAffectedRows; } public function insertId() { if ( $this->lastEmulatedInsertId === null ) { // Guard against misuse of this method by checking affectedRows(). Note that calls // to insert() with "IGNORE" and calls to insertSelect() might not add any rows. if ( $this->affectedRows() ) { $this->lastEmulatedInsertId = $this->lastInsertId(); } else { $this->lastEmulatedInsertId = 0; } } return $this->lastEmulatedInsertId; } /** * Get a row ID from the last insert statement to implicitly assign one within the session * * If the statement involved assigning sequence IDs to multiple rows, then the return value * will be any one of those values (database-specific). If the statement was an "UPSERT" and * some existing rows were updated, then the result will either reflect only IDs of created * rows or it will reflect IDs of both created and updated rows (this is database-specific). * * The result is unspecified if the statement gave an error. * * @return int Sequence ID, 0 (if none) * @throws DBError */ abstract protected function lastInsertId(); public function ping() { if ( $this->isOpen() ) { // If the connection was recently used, assume that it is still good if ( ( microtime( true ) - $this->lastPing ) < self::PING_TTL ) { return true; } // Send a trivial query to test the connection, triggering an automatic // reconnection attempt if the connection was lost $query = new Query( self::PING_QUERY, self::QUERY_IGNORE_DBO_TRX | self::QUERY_SILENCE_ERRORS | self::QUERY_CHANGE_NONE, 'SELECT' ); $res = $this->query( $query, __METHOD__ ); $ok = ( $res !== false ); } else { // Try to re-establish a connection $ok = $this->replaceLostConnection( null, __METHOD__ ); } return $ok; } /** * Close any existing (dead) database connection and open a new connection * * @param int|null $lastErrno * @param string $fname * @return bool True if new connection is opened successfully, false if error */ protected function replaceLostConnection( $lastErrno, $fname ) { if ( $this->conn ) { $this->closeConnection(); $this->conn = null; $this->handleSessionLossPreconnect(); } try { $this->open( $this->connectionParams[self::CONN_HOST], $this->connectionParams[self::CONN_USER], $this->connectionParams[self::CONN_PASSWORD], $this->currentDomain->getDatabase(), $this->currentDomain->getSchema(), $this->tablePrefix() ); $this->lastPing = microtime( true ); $ok = true; $this->logger->warning( $fname . ': lost connection to {db_server} with error {errno}; reconnected', $this->getLogContext( [ 'exception' => new RuntimeException(), 'db_log_category' => 'connection', 'errno' => $lastErrno ] ) ); } catch ( DBConnectionError $e ) { $ok = false; $this->logger->error( $fname . ': lost connection to {db_server} with error {errno}; reconnection failed: {connect_msg}', $this->getLogContext( [ 'exception' => new RuntimeException(), 'db_log_category' => 'connection', 'errno' => $lastErrno, 'connect_msg' => $e->getMessage() ] ) ); } // Handle callbacks in trxEndCallbacks, e.g. onTransactionResolution(). // If callback suppression is set then the array will remain unhandled. $this->runOnTransactionIdleCallbacks( self::TRIGGER_ROLLBACK ); // Handle callbacks in trxRecurringCallbacks, e.g. setTransactionListener(). // If callback suppression is set then the array will remain unhandled. $this->runTransactionListenerCallbacks( self::TRIGGER_ROLLBACK ); return $ok; } /** * Merge the result of getSessionLagStatus() for several DBs * using the most pessimistic values to estimate the lag of * any data derived from them in combination * * This is information is useful for caching modules * * @see WANObjectCache::set() * @see WANObjectCache::getWithSetCallback() * * @param IReadableDatabase|null ...$dbs * Note: For backward compatibility, it is allowed for null values * to be passed among the parameters. This is deprecated since 1.36, * only IReadableDatabase objects should be passed. * * @return array Map of values: * - lag: highest lag of any of the DBs or false on error (e.g. replication stopped) * - since: oldest UNIX timestamp of any of the DB lag estimates * - pending: whether any of the DBs have uncommitted changes * @throws DBError * @since 1.27 */ public static function getCacheSetOptions( ?IReadableDatabase ...$dbs ) { $res = [ 'lag' => 0, 'since' => INF, 'pending' => false ]; foreach ( func_get_args() as $db ) { if ( $db instanceof IReadableDatabase ) { $status = $db->getSessionLagStatus(); if ( $status['lag'] === false ) { $res['lag'] = false; } elseif ( $res['lag'] !== false ) { $res['lag'] = max( $res['lag'], $status['lag'] ); } $res['since'] = min( $res['since'], $status['since'] ); } if ( $db instanceof IDatabaseForOwner ) { $res['pending'] = $res['pending'] ?: $db->writesPending(); } } return $res; } public function encodeBlob( $b ) { return $b; } public function decodeBlob( $b ) { if ( $b instanceof Blob ) { $b = $b->fetch(); } return $b; } public function setSessionOptions( array $options ) { } public function sourceFile( $filename, ?callable $lineCallback = null, ?callable $resultCallback = null, $fname = false, ?callable $inputCallback = null ) { AtEase::suppressWarnings(); $fp = fopen( $filename, 'r' ); AtEase::restoreWarnings(); if ( $fp === false ) { throw new RuntimeException( "Could not open \"{$filename}\"" ); } if ( !$fname ) { $fname = __METHOD__ . "( $filename )"; } try { return $this->sourceStream( $fp, $lineCallback, $resultCallback, $fname, $inputCallback ); } finally { fclose( $fp ); } } public function sourceStream( $fp, ?callable $lineCallback = null, ?callable $resultCallback = null, $fname = __METHOD__, ?callable $inputCallback = null ) { $delimiterReset = new ScopedCallback( function ( $delimiter ) { $this->delimiter = $delimiter; }, [ $this->delimiter ] ); $cmd = ''; while ( !feof( $fp ) ) { if ( $lineCallback ) { call_user_func( $lineCallback ); } $line = trim( fgets( $fp ) ); if ( $line == '' ) { continue; } if ( $line[0] == '-' && $line[1] == '-' ) { continue; } if ( $cmd != '' ) { $cmd .= ' '; } $done = $this->streamStatementEnd( $cmd, $line ); $cmd .= "$line\n"; if ( $done || feof( $fp ) ) { $cmd = $this->platform->replaceVars( $cmd ); if ( $inputCallback ) { $callbackResult = $inputCallback( $cmd ); if ( is_string( $callbackResult ) || !$callbackResult ) { $cmd = $callbackResult; } } if ( $cmd ) { $res = $this->query( $cmd, $fname ); if ( $resultCallback ) { $resultCallback( $res, $this ); } if ( $res === false ) { $err = $this->lastError(); return "Query \"{$cmd}\" failed with error code \"$err\".\n"; } } $cmd = ''; } } ScopedCallback::consume( $delimiterReset ); return true; } /** * Called by sourceStream() to check if we've reached a statement end * * @param string &$sql SQL assembled so far * @param string &$newLine New line about to be added to $sql * @return bool Whether $newLine contains end of the statement */ public function streamStatementEnd( &$sql, &$newLine ) { if ( $this->delimiter ) { $prev = $newLine; $newLine = preg_replace( '/' . preg_quote( $this->delimiter, '/' ) . '$/', '', $newLine ); if ( $newLine != $prev ) { return true; } } return false; } /** * @inheritDoc */ public function lockIsFree( $lockName, $method ) { // RDBMs methods for checking named locks may or may not count this thread itself. // In MySQL, IS_FREE_LOCK() returns 0 if the thread already has the lock. This is // the behavior chosen by the interface for this method. if ( isset( $this->sessionNamedLocks[$lockName] ) ) { $lockIsFree = false; } else { $lockIsFree = $this->doLockIsFree( $lockName, $method ); } return $lockIsFree; } /** * @see lockIsFree() * * @param string $lockName * @param string $method * @return bool Success * @throws DBError */ protected function doLockIsFree( string $lockName, string $method ) { return true; // not implemented } /** * @inheritDoc */ public function lock( $lockName, $method, $timeout = 5, $flags = 0 ) { $lockTsUnix = $this->doLock( $lockName, $method, $timeout ); if ( $lockTsUnix !== null ) { $locked = true; $this->sessionNamedLocks[$lockName] = [ 'ts' => $lockTsUnix, 'trxId' => $this->transactionManager->getTrxId() ]; } else { $locked = false; $this->logger->info( __METHOD__ . ": failed to acquire lock '{lockname}'", [ 'lockname' => $lockName, 'db_log_category' => 'locking' ] ); } return $this->flagsHolder::contains( $flags, self::LOCK_TIMESTAMP ) ? $lockTsUnix : $locked; } /** * @see lock() * * @param string $lockName * @param string $method * @param int $timeout * @return float|null UNIX timestamp of lock acquisition; null on failure * @throws DBError */ protected function doLock( string $lockName, string $method, int $timeout ) { return microtime( true ); // not implemented } /** * @inheritDoc */ public function unlock( $lockName, $method ) { if ( !isset( $this->sessionNamedLocks[$lockName] ) ) { $released = false; $this->logger->warning( __METHOD__ . ": trying to release unheld lock '$lockName'\n", [ 'db_log_category' => 'locking' ] ); } else { $released = $this->doUnlock( $lockName, $method ); if ( $released ) { unset( $this->sessionNamedLocks[$lockName] ); } else { $this->logger->warning( __METHOD__ . ": failed to release lock '$lockName'\n", [ 'db_log_category' => 'locking' ] ); } } return $released; } /** * @see unlock() * * @param string $lockName * @param string $method * @return bool Success * @throws DBError */ protected function doUnlock( string $lockName, string $method ) { return true; // not implemented } public function getScopedLockAndFlush( $lockKey, $fname, $timeout ) { $this->transactionManager->onGetScopedLockAndFlush( $this, $fname ); if ( !$this->lock( $lockKey, $fname, $timeout ) ) { return null; } $unlocker = new ScopedCallback( function () use ( $lockKey, $fname ) { // Note that the callback can be reached due to an exception making the calling // function end early. If the transaction/session is in an error state, avoid log // spam and confusing replacement of an original DBError with one about unlock(). // Unlock query will fail anyway; avoid possibly triggering errors in rollback() if ( $this->transactionManager->sessionStatus() === TransactionManager::STATUS_SESS_ERROR || $this->transactionManager->trxStatus() === TransactionManager::STATUS_TRX_ERROR ) { return; } if ( $this->trxLevel() ) { $this->onTransactionResolution( function () use ( $lockKey, $fname ) { $this->unlock( $lockKey, $fname ); }, $fname ); } else { $this->unlock( $lockKey, $fname ); } } ); $this->commit( $fname, self::FLUSHING_INTERNAL ); return $unlocker; } public function dropTable( $table, $fname = __METHOD__ ) { if ( !$this->tableExists( $table, $fname ) ) { return false; } $query = new Query( $this->platform->dropTableSqlText( $table ), self::QUERY_CHANGE_SCHEMA, 'DROP', $table ); $this->query( $query, $fname ); return true; } public function truncateTable( $table, $fname = __METHOD__ ) { $sql = "TRUNCATE TABLE " . $this->tableName( $table ); $query = new Query( $sql, self::QUERY_CHANGE_SCHEMA, 'TRUNCATE', $table ); $this->query( $query, $fname ); } public function isReadOnly() { return ( $this->getReadOnlyReason() !== null ); } /** * @return array|null Tuple of (reason string, "role" or "lb") if read-only; null otherwise */ protected function getReadOnlyReason() { $reason = $this->replicationReporter->getTopologyBasedReadOnlyReason(); if ( $reason ) { return $reason; } $reason = $this->getLBInfo( self::LB_READ_ONLY_REASON ); if ( is_string( $reason ) ) { return [ $reason, 'lb' ]; } return null; } /** * Get the underlying binding connection handle * * Makes sure the connection resource is set (disconnects and ping() failure can unset it). * This catches broken callers than catch and ignore disconnection exceptions. * Unlike checking isOpen(), this is safe to call inside of open(). * * @return mixed * @throws DBUnexpectedError * @since 1.26 */ protected function getBindingHandle() { if ( !$this->conn ) { throw new DBUnexpectedError( $this, 'DB connection was already closed or the connection dropped' ); } return $this->conn; } /** * Demark the start of a critical section of session/transaction state changes * * Use this to disable potentially DB handles due to corruption from highly unexpected * exceptions (e.g. from zend timers or coding errors) preempting execution of methods. * * Callers must demark completion of the critical section with completeCriticalSection(). * Callers should handle DBError exceptions that do not cause object state corruption by * catching them, calling completeCriticalSection(), and then rethrowing them. * * @code * $cs = $this->commenceCriticalSection( __METHOD__ ); * try { * //...send a query that changes the session/transaction state... * } catch ( DBError $e ) { * $this->completeCriticalSection( __METHOD__, $cs ); * throw $expectedException; * } * try { * //...send another query that changes the session/transaction state... * } catch ( DBError $trxError ) { * // Require ROLLBACK before allowing any other queries from outside callers * $this->completeCriticalSection( __METHOD__, $cs, $trxError ); * throw $expectedException; * } * // ...update session state fields of $this... * $this->completeCriticalSection( __METHOD__, $cs ); * @endcode * * @see Database::completeCriticalSection() * * @since 1.36 * @param string $fname Caller name * @return CriticalSectionScope|null RAII-style monitor (topmost sections only) * @throws DBUnexpectedError If an unresolved critical section error already exists */ protected function commenceCriticalSection( string $fname ) { if ( $this->csmError ) { throw new DBUnexpectedError( $this, "Cannot execute $fname critical section while session state is out of sync.\n\n" . $this->csmError->getMessage() . "\n" . $this->csmError->getTraceAsString() ); } if ( $this->csmId ) { $csm = null; // fold into the outer critical section } elseif ( $this->csProvider ) { $csm = $this->csProvider->scopedEnter( $fname, null, // emergency limit (default) null, // emergency callback (default) function () use ( $fname ) { // Mark a critical section as having been aborted by an error $e = new RuntimeException( "A critical section from {$fname} has failed" ); $this->csmError = $e; $this->csmId = null; } ); $this->csmId = $csm->getId(); $this->csmFname = $fname; } else { $csm = null; // not supported } return $csm; } /** * Demark the completion of a critical section of session/transaction state changes * * @see Database::commenceCriticalSection() * * @since 1.36 * @param string $fname Caller name * @param CriticalSectionScope|null $csm RAII-style monitor (topmost sections only) * @param Throwable|null $trxError Error that requires setting STATUS_TRX_ERROR (if any) */ protected function completeCriticalSection( string $fname, ?CriticalSectionScope $csm, ?Throwable $trxError = null ) { if ( $csm !== null ) { if ( $this->csmId === null ) { throw new LogicException( "$fname critical section is not active" ); } elseif ( $csm->getId() !== $this->csmId ) { throw new LogicException( "$fname critical section is not the active ({$this->csmFname}) one" ); } $csm->exit(); $this->csmId = null; } if ( $trxError ) { $this->transactionManager->setTransactionError( $trxError ); } } public function __toString() { $id = spl_object_id( $this ); $description = $this->getType() . ' object #' . $id; // phpcs:ignore MediaWiki.Usage.ForbiddenFunctions.is_resource if ( is_resource( $this->conn ) ) { $description .= ' (' . (string)$this->conn . ')'; // "resource id #<ID>" } elseif ( is_object( $this->conn ) ) { $handleId = spl_object_id( $this->conn ); $description .= " (handle id #$handleId)"; } return $description; } /** * Make sure that copies do not share the same client binding handle * @throws DBConnectionError */ public function __clone() { $this->logger->warning( "Cloning " . static::class . " is not recommended; forking connection", [ 'exception' => new RuntimeException(), 'db_log_category' => 'connection' ] ); if ( $this->isOpen() ) { // Open a new connection resource without messing with the old one $this->conn = null; $this->transactionManager->clearEndCallbacks(); $this->handleSessionLossPreconnect(); // no trx or locks anymore $this->open( $this->connectionParams[self::CONN_HOST], $this->connectionParams[self::CONN_USER], $this->connectionParams[self::CONN_PASSWORD], $this->currentDomain->getDatabase(), $this->currentDomain->getSchema(), $this->tablePrefix() ); $this->lastPing = microtime( true ); } } /** * Called by serialize. Throw an exception when DB connection is serialized. * This causes problems on some database engines because the connection is * not restored on unserialize. * @return never */ public function __sleep() { throw new RuntimeException( 'Database serialization may cause problems, since ' . 'the connection is not restored on wakeup' ); } /** * Run a few simple checks and close dangling connections */ public function __destruct() { if ( $this->transactionManager ) { // Tests mock this class and disable constructor. $this->transactionManager->onDestruct(); } $danglingWriters = $this->pendingWriteAndCallbackCallers(); if ( $danglingWriters ) { $fnames = implode( ', ', $danglingWriters ); trigger_error( "DB transaction writes or callbacks still pending ($fnames)" ); } if ( $this->conn ) { // Avoid connection leaks. Normally, resources close at script completion. // The connection might already be closed in PHP by now, so suppress warnings. AtEase::suppressWarnings(); $this->closeConnection(); AtEase::restoreWarnings(); $this->conn = null; } } /* Start of methods delegated to DatabaseFlags. Avoid using them outside of rdbms library */ public function setFlag( $flag, $remember = self::REMEMBER_NOTHING ) { $this->flagsHolder->setFlag( $flag, $remember ); } public function clearFlag( $flag, $remember = self::REMEMBER_NOTHING ) { $this->flagsHolder->clearFlag( $flag, $remember ); } public function restoreFlags( $state = self::RESTORE_PRIOR ) { $this->flagsHolder->restoreFlags( $state ); } public function getFlag( $flag ) { return $this->flagsHolder->getFlag( $flag ); } /* End of methods delegated to DatabaseFlags. */ /* Start of methods delegated to TransactionManager. Avoid using them outside of rdbms library */ final public function trxLevel() { // FIXME: A lot of tests disable constructor leading to trx manager being // null and breaking, this is unacceptable but hopefully this should // happen less by moving these functions to the transaction manager class. if ( !$this->transactionManager ) { $this->transactionManager = new TransactionManager( new NullLogger() ); } return $this->transactionManager->trxLevel(); } public function trxTimestamp() { return $this->transactionManager->trxTimestamp(); } public function trxStatus() { return $this->transactionManager->trxStatus(); } public function writesPending() { return $this->transactionManager->writesPending(); } public function writesOrCallbacksPending() { return $this->transactionManager->writesOrCallbacksPending(); } public function pendingWriteQueryDuration( $type = self::ESTIMATE_TOTAL ) { return $this->transactionManager->pendingWriteQueryDuration( $type ); } public function pendingWriteCallers() { if ( !$this->transactionManager ) { return []; } return $this->transactionManager->pendingWriteCallers(); } public function pendingWriteAndCallbackCallers() { if ( !$this->transactionManager ) { return []; } return $this->transactionManager->pendingWriteAndCallbackCallers(); } public function runOnTransactionPreCommitCallbacks() { return $this->transactionManager->runOnTransactionPreCommitCallbacks( $this ); } public function explicitTrxActive() { return $this->transactionManager->explicitTrxActive(); } /* End of methods delegated to TransactionManager. */ /* Start of methods delegated to SQLPlatform. Avoid using them outside of rdbms library */ public function implicitOrderby() { return $this->platform->implicitOrderby(); } public function selectSQLText( $tables, $vars, $conds = '', $fname = __METHOD__, $options = [], $join_conds = [] ) { return $this->platform->selectSQLText( $tables, $vars, $conds, $fname, $options, $join_conds ); } public function buildComparison( string $op, array $conds ): string { return $this->platform->buildComparison( $op, $conds ); } public function makeList( array $a, $mode = self::LIST_COMMA ) { return $this->platform->makeList( $a, $mode ); } public function makeWhereFrom2d( $data, $baseKey, $subKey ) { return $this->platform->makeWhereFrom2d( $data, $baseKey, $subKey ); } public function factorConds( $condsArray ) { return $this->platform->factorConds( $condsArray ); } public function bitNot( $field ) { return $this->platform->bitNot( $field ); } public function bitAnd( $fieldLeft, $fieldRight ) { return $this->platform->bitAnd( $fieldLeft, $fieldRight ); } public function bitOr( $fieldLeft, $fieldRight ) { return $this->platform->bitOr( $fieldLeft, $fieldRight ); } public function buildConcat( $stringList ) { return $this->platform->buildConcat( $stringList ); } public function buildGreatest( $fields, $values ) { return $this->platform->buildGreatest( $fields, $values ); } public function buildLeast( $fields, $values ) { return $this->platform->buildLeast( $fields, $values ); } public function buildSubstring( $input, $startPosition, $length = null ) { return $this->platform->buildSubstring( $input, $startPosition, $length ); } public function buildStringCast( $field ) { return $this->platform->buildStringCast( $field ); } public function buildIntegerCast( $field ) { return $this->platform->buildIntegerCast( $field ); } public function tableName( string $name, $format = 'quoted' ) { return $this->platform->tableName( $name, $format ); } public function tableNames( ...$tables ) { return $this->platform->tableNames( ...$tables ); } public function tableNamesN( ...$tables ) { return $this->platform->tableNamesN( ...$tables ); } public function addIdentifierQuotes( $s ) { return $this->platform->addIdentifierQuotes( $s ); } public function isQuotedIdentifier( $name ) { return $this->platform->isQuotedIdentifier( $name ); } public function buildLike( $param, ...$params ) { return $this->platform->buildLike( $param, ...$params ); } public function anyChar() { return $this->platform->anyChar(); } public function anyString() { return $this->platform->anyString(); } public function limitResult( $sql, $limit, $offset = false ) { return $this->platform->limitResult( $sql, $limit, $offset ); } public function unionSupportsOrderAndLimit() { return $this->platform->unionSupportsOrderAndLimit(); } public function unionQueries( $sqls, $all, $options = [] ) { return $this->platform->unionQueries( $sqls, $all, $options ); } public function conditional( $cond, $caseTrueExpression, $caseFalseExpression ) { return $this->platform->conditional( $cond, $caseTrueExpression, $caseFalseExpression ); } public function strreplace( $orig, $old, $new ) { return $this->platform->strreplace( $orig, $old, $new ); } public function timestamp( $ts = 0 ) { return $this->platform->timestamp( $ts ); } public function timestampOrNull( $ts = null ) { return $this->platform->timestampOrNull( $ts ); } public function getInfinity() { return $this->platform->getInfinity(); } public function encodeExpiry( $expiry ) { return $this->platform->encodeExpiry( $expiry ); } public function decodeExpiry( $expiry, $format = TS_MW ) { return $this->platform->decodeExpiry( $expiry, $format ); } public function setTableAliases( array $aliases ) { $this->platform->setTableAliases( $aliases ); } public function getTableAliases() { return $this->platform->getTableAliases(); } public function setIndexAliases( array $aliases ) { $this->platform->setIndexAliases( $aliases ); } public function buildGroupConcatField( $delim, $tables, $field, $conds = '', $join_conds = [] ) { return $this->platform->buildGroupConcatField( $delim, $tables, $field, $conds, $join_conds ); } public function buildSelectSubquery( $tables, $vars, $conds = '', $fname = __METHOD__, $options = [], $join_conds = [] ) { return $this->platform->buildSelectSubquery( $tables, $vars, $conds, $fname, $options, $join_conds ); } public function buildExcludedValue( $column ) { return $this->platform->buildExcludedValue( $column ); } public function setSchemaVars( $vars ) { $this->platform->setSchemaVars( $vars ); } /* End of methods delegated to SQLPlatform. */ /* Start of methods delegated to ReplicationReporter. */ public function primaryPosWait( DBPrimaryPos $pos, $timeout ) { return $this->replicationReporter->primaryPosWait( $this, $pos, $timeout ); } public function getPrimaryPos() { return $this->replicationReporter->getPrimaryPos( $this ); } public function getLag() { return $this->replicationReporter->getLag( $this ); } public function getSessionLagStatus() { return $this->replicationReporter->getSessionLagStatus( $this ); } /* End of methods delegated to ReplicationReporter. */ } PK ! �#�冻 �� rdbms/database/IDatabase.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\Rdbms; use Exception; use Wikimedia\ScopedCallback; /** * @defgroup Database Database * This group deals with database interface functions * and query specifics/optimisations. */ // Very long type annotations :( // phpcs:disable Generic.Files.LineLength /** * Interface to a relational database * * This is used for both primary databases and replicas, and used for both concrete * connections, as well as wrappers around shared connections, like DBConnRef. * * As such, callers should not assume that the object represents a live connection * (when using DBConnRef, the object may lazily defer the connection to the first query), * and should not assume that they have complete control over the connection * (when using DBConnRef, multiple objects may automatically share and reuse the same * underlying connection). * * @ingroup Database */ interface IDatabase extends IReadableDatabase { /** Callback triggered immediately due to no active transaction */ public const TRIGGER_IDLE = 1; /** Callback triggered by COMMIT */ public const TRIGGER_COMMIT = 2; /** Callback triggered by ROLLBACK */ public const TRIGGER_ROLLBACK = 3; /** Callback triggered by atomic section cancel (ROLLBACK TO SAVEPOINT) */ public const TRIGGER_CANCEL = 4; /** Transaction is requested by regular caller outside of the DB layer */ public const TRANSACTION_EXPLICIT = ''; /** Transaction is requested internally via DBO_TRX/startAtomic() */ public const TRANSACTION_INTERNAL = 'implicit'; /** Atomic section is not cancelable */ public const ATOMIC_NOT_CANCELABLE = ''; /** Atomic section is cancelable */ public const ATOMIC_CANCELABLE = 'cancelable'; /** Commit/rollback is from outside the IDatabase handle and connection manager */ public const FLUSHING_ONE = ''; /** * Commit/rollback is from the owning connection manager for the IDatabase handle * @internal Only for use within the rdbms library */ public const FLUSHING_ALL_PEERS = 'flush'; /** * Commit/rollback is from the IDatabase handle internally * @internal Only for use within the rdbms library */ public const FLUSHING_INTERNAL = 'flush-internal'; /** Estimate total time (RTT, scanning, waiting on locks, applying) */ public const ESTIMATE_TOTAL = 'total'; /** Estimate time to apply (scanning, applying) */ public const ESTIMATE_DB_APPLY = 'apply'; /** Flag to return the lock acquisition timestamp (null if not acquired) */ public const LOCK_TIMESTAMP = 1; /** Field for getLBInfo()/setLBInfo() */ public const LB_TRX_ROUND_ID = 'trxRoundId'; /** Field for getLBInfo()/setLBInfo() */ public const LB_READ_ONLY_REASON = 'readOnlyReason'; /** Primary server than can stream writes to replica servers */ public const ROLE_STREAMING_MASTER = 'streaming-master'; /** Replica server that receives writes from a primary server */ public const ROLE_STREAMING_REPLICA = 'streaming-replica'; /** Replica server within a static dataset */ public const ROLE_STATIC_CLONE = 'static-clone'; /** Server with unknown topology role */ public const ROLE_UNKNOWN = 'unknown'; /** * Gets the current transaction level. * * Historically, transactions were allowed to be "nested". This is no * longer supported, so this function really only returns a boolean. * * @return int The previous value */ public function trxLevel(); /** * Get the UNIX timestamp of the time that the transaction was established * * This can be used to reason about the staleness of SELECT data in REPEATABLE-READ * transaction isolation level. Callers can assume that if a view-snapshot isolation * is used, then the data read by SQL queries is *at least* up to date to that point * (possibly more up-to-date since the first SELECT defines the snapshot). * * @return float|null Returns null if there is not active transaction * @since 1.25 */ public function trxTimestamp(); /** * Check whether there is a transaction open at the specific request of a caller * * Explicit transactions are spawned by begin(), startAtomic(), and doAtomicSection(). * Note that explicit transactions should not be confused with explicit transaction rounds. * * @return bool * @since 1.28 */ public function explicitTrxActive(); /** * Get properties passed down from the server info array of the load balancer * * @internal should not be called outside of rdbms library. * * @param string|null $name The entry of the info array to get, or null to get the whole array * @return array|mixed|null */ public function getLBInfo( $name = null ); /** * Get the sequence-based ID assigned by the last query method call * * This method should only be called when all the following hold true: * - (a) A method call was made to insert(), upsert(), replace(), or insertSelect() * - (b) The method call attempts to insert exactly one row * - (c) The method call omits the value of exactly one auto-increment column * - (d) The method call succeeded * - (e) No subsequent method calls were made, with the exception of affectedRows(), * lastErrno(), lastError(), and getType() * * In all other cases, the return value is unspecified. * * When the query method is either insert() with "IGNORE", upsert(), or insertSelect(), * callers should first check affectedRows() before calling this method, making sure that * the query method actually created a row. Otherwise, an ID from a previous insert might * be incorrectly assumed to belong to last insert. * * @return int */ public function insertId(); /** * Get the number of rows affected by the last query method call * * This method should only be called when all the following hold true: * - (a) A method call was made to insert(), upsert(), replace(), update(), delete(), * insertSelect(), query() with a non-SELECT statement, or queryMulti() with a * non-SELECT terminal statement * - (b) The method call succeeded * - (c) No subsequent method calls were made, with the exception of affectedRows(), * lastErrno(), lastError(), and getType() * * In all other cases, the return value is unspecified. * * UPDATE queries consider rows affected even when all their new column values match * the previous values. Such rows can be excluded from the count by changing the WHERE * clause to filter them out. * * If the last query method call was to query() or queryMulti(), then the results * are based on the (last) statement provided to that call and are driver-specific. * * @return int */ public function affectedRows(); /** * Run an SQL query statement and return the result * * If a connection loss is detected, then an attempt to reconnect will be made. * For queries that involve no larger transactions or locks, they will be re-issued * for convenience, provided the connection was re-established. * * In new code, the query wrappers select(), insert(), update(), delete(), * etc. should be used where possible, since they give much better DBMS * independence and automatically quote or validate user input in a variety * of contexts. This function is generally only useful for queries which are * explicitly DBMS-dependent and are unsupported by the query wrappers, such * as CREATE TABLE. * * However, the query wrappers themselves should call this function. * * Callers should avoid the use of statements like BEGIN, COMMIT, and ROLLBACK. * Methods like startAtomic(), endAtomic(), and cancelAtomic() can be used instead. * * @param string|Query $sql Single-statement SQL query * @param-taint $sql exec_sql * @param string $fname Caller name; used for profiling/SHOW PROCESSLIST comments @phan-mandatory-param * @param int $flags Bit field of ISQLPlatform::QUERY_* constants * @return bool|IResultWrapper True for a successful write query, IResultWrapper object * for a successful read query, or false on failure if QUERY_SILENCE_ERRORS is set * @return-taint tainted * @throws DBQueryError If the query is issued, fails, and QUERY_SILENCE_ERRORS is not set * @throws DBExpectedError If the query is not, and cannot, be issued yet (non-DBQueryError) * @throws DBError If the query is inherently not allowed (non-DBExpectedError) */ public function query( $sql, $fname = __METHOD__, $flags = 0 ); /** * Get an UpdateQueryBuilder bound to this connection. This is overridden by * DBConnRef. * * @note A new query builder must be created per query. Query builders * should not be reused since this uses a fluent interface and the state of * the builder changes during the query which may cause unexpected results. * * @return UpdateQueryBuilder */ public function newUpdateQueryBuilder(): UpdateQueryBuilder; /** * Get an DeleteQueryBuilder bound to this connection. This is overridden by * DBConnRef. * * @note A new query builder must be created per query. Query builders * should not be reused since this uses a fluent interface and the state of * the builder changes during the query which may cause unexpected results. * * @return DeleteQueryBuilder */ public function newDeleteQueryBuilder(): DeleteQueryBuilder; /** * Get an InsertQueryBuilder bound to this connection. This is overridden by * DBConnRef. * * @note A new query builder must be created per query. Query builders * should not be reused since this uses a fluent interface and the state of * the builder changes during the query which may cause unexpected results. * * @return InsertQueryBuilder */ public function newInsertQueryBuilder(): InsertQueryBuilder; /** * Get an ReplaceQueryBuilder bound to this connection. This is overridden by * DBConnRef. * * @note A new query builder must be created per query. Query builders * should not be reused since this uses a fluent interface and the state of * the builder changes during the query which may cause unexpected results. * * @return ReplaceQueryBuilder */ public function newReplaceQueryBuilder(): ReplaceQueryBuilder; /** * Lock all rows meeting the given conditions/options FOR UPDATE * * @param string|string[] $table The unqualified name of table(s) (use an array for a join) * @param string|IExpression|array<string,?scalar|non-empty-array<int,?scalar>|RawSQLValue>|array<int,string|IExpression> $conds * Condition in the format of IDatabase::select() conditions * @param string $fname Function name for profiling @phan-mandatory-param * @param array $options Options for select ("FOR UPDATE" is added automatically) * @param array $join_conds Join conditions * @return int Number of matching rows found (and locked) * @throws DBError If an error occurs, {@see query} * @since 1.32 * @deprecated since 1.43; Use SelectQueryBuilder::acquireRowLocks */ public function lockForUpdate( $table, $conds = '', $fname = __METHOD__, $options = [], $join_conds = [] ); /** * Insert row(s) into a table, in the provided order * * This operation will be seen by affectedRows()/insertId() as one query statement, * regardless of how many statements are actually sent by the class implementation. * * @internal callers outside of rdbms library should use InsertQueryBuilder instead. * * @param string $table The unqualified name of a table * @param array|array[] $rows Row(s) to insert, as either: * - A string-keyed map of (column name => value) defining a new row. Values are * treated as literals and quoted appropriately; null is interpreted as NULL. * - An integer-keyed list of such string-keyed maps, defining a list of new rows. * The keys in each map must be identical to each other and in the same order. * The rows must not collide with each other. * @param string $fname Calling function name (use __METHOD__) for logs/profiling @phan-mandatory-param * @param string|array $options Combination map/list where each string-keyed entry maps * a non-boolean option to the option parameters and each integer-keyed value is the * name of a boolean option. Supported options are: * - IGNORE: Boolean: skip insertion of rows that would cause unique key conflicts. * IDatabase::affectedRows() can be used to determine how many rows were inserted. * @return bool Return true if no exception was thrown (deprecated since 1.33) * @throws DBError If an error occurs, {@see query} */ public function insert( $table, $rows, $fname = __METHOD__, $options = [] ); /** * Update all rows in a table that match a given condition * * This operation will be seen by affectedRows()/insertId() as one query statement, * regardless of how many statements are actually sent by the class implementation. * * @internal callers outside of rdbms library should use UpdateQueryBuilder instead. * * @param string $table The unqualified name of a table * @param-taint $table exec_sql * @param array<string,?scalar|RawSQLValue>|array<int,string> $set * Combination map/list where each string-keyed entry maps a column * to a literal assigned value and each integer-keyed value is a SQL expression in the * format of a column assignment within UPDATE...SET. The (column => value) entries are * convenient due to automatic value quoting and conversion of null to NULL. The SQL * assignment format is useful for updates like "column = column + X". All assignments * have no defined execution order, so they should not depend on each other. Do not * modify AUTOINCREMENT or UUID columns in assignments. * @param-taint $set exec_sql_numkey * @param string|IExpression|array<string,?scalar|non-empty-array<int,?scalar>|RawSQLValue>|array<int,string|IExpression> $conds * Condition in the format of IDatabase::select() conditions. * In order to prevent possible performance or replication issues or damaging a data * accidentally, an empty condition for 'update' queries isn't allowed. * IDatabase::ALL_ROWS should be passed explicitly in order to update all rows. * @param-taint $conds exec_sql_numkey * @param string $fname Calling function name (use __METHOD__) for logs/profiling @phan-mandatory-param * @param-taint $fname exec_sql * @param string|array $options Combination map/list where each string-keyed entry maps * a non-boolean option to the option parameters and each integer-keyed value is the * name of a boolean option. Supported options are: * - IGNORE: Boolean: skip update of rows that would cause unique key conflicts. * IDatabase::affectedRows() includes all matching rows, * that includes also rows not updated due to key conflict. * @param-taint $options none * @return bool Return true if no exception was thrown (deprecated since 1.33) * @return-taint none * @throws DBError If an error occurs, {@see query} */ public function update( $table, $set, $conds, $fname = __METHOD__, $options = [] ); /** * Insert row(s) into a table, in the provided order, while deleting conflicting rows * * Conflicts are determined by the provided unique indexes. Note that it is possible * for the provided rows to conflict even among themselves; it is preferable for the * caller to de-duplicate such input beforehand. * * Note some important implications of the deletion semantics: * - If the table has an AUTOINCREMENT column and $rows omit that column, then any * conflicting existing rows will be replaced with newer having higher values for * that column, even if nothing else changed. * - There might be worse contention than upsert() due to the use of gap-locking. * This does not apply to RDBMS types that use predicate locking nor those that * just lock the whole table or databases anyway. * * This operation will be seen by affectedRows()/insertId() as one query statement, * regardless of how many statements are actually sent by the class implementation. * * @internal callers outside of rdbms library should use ReplaceQueryBuilder instead. * * @param string $table The unqualified name of a table * @param string|string[]|string[][] $uniqueKeys Column name or non-empty list of column * name lists that define all applicable unique keys on the table. There must only be * one such key. Each unique key on the table is "applicable" unless either: * - It involves an AUTOINCREMENT column for which no values are assigned in $rows * - It involves a UUID column for which newly generated UUIDs are assigned in $rows * @param array|array[] $rows Row(s) to insert, in the form of either: * - A string-keyed map of (column name => value) defining a new row. Values are * treated as literals and quoted appropriately; null is interpreted as NULL. * Columns belonging to a key in $uniqueKeys must be defined here and non-null. * - An integer-keyed list of such string-keyed maps, defining a list of new rows. * The keys in each map must be identical to each other and in the same order. * The rows must not collide with each other. * @param string $fname Calling function name (use __METHOD__) for logs/profiling @phan-mandatory-param * @throws DBError If an error occurs, {@see query} */ public function replace( $table, $uniqueKeys, $rows, $fname = __METHOD__ ); /** * Upsert row(s) into a table, in the provided order, while updating conflicting rows * * Conflicts are determined by the provided unique indexes. Note that it is possible * for the provided rows to conflict even among themselves; it is preferable for the * caller to de-duplicate such input beforehand. * * This operation will be seen by affectedRows()/insertId() as one query statement, * regardless of how many statements are actually sent by the class implementation. * * @internal callers outside of rdbms library should use InsertQueryBuilder instead. * * @param string $table The unqualified name of a table * @param array|array[] $rows Row(s) to insert, in the form of either: * - A string-keyed map of (column name => value) defining a new row. Values are * treated as literals and quoted appropriately; null is interpreted as NULL. * Columns belonging to a key in $uniqueKeys must be defined here and non-null. * - An integer-keyed list of such string-keyed maps, defining a list of new rows. * The keys in each map must be identical to each other and in the same order. * The rows must not collide with each other. * @param string|string[]|string[][] $uniqueKeys Column name or non-empty list of column * name lists that define all applicable unique keys on the table. There must only be * one such key. Each unique key on the table is "applicable" unless either: * - It involves an AUTOINCREMENT column for which no values are assigned in $rows * - It involves a UUID column for which newly generated UUIDs are assigned in $rows * @param array<string,?scalar|RawSQLValue>|array<int,string> $set * Combination map/list where each string-keyed entry maps a column * to a literal assigned value and each integer-keyed value is a SQL assignment expression * of the form "<unquoted alphanumeric column> = <SQL expression>". The (column => value) * entries are convenient due to automatic value quoting and conversion of null to NULL. * The SQL assignment entries are useful for updates like "column = column + X". All of * the assignments have no defined execution order, so callers should make sure that they * not depend on each other. Do not modify AUTOINCREMENT or UUID columns in assignments, * even if they are just "secondary" unique keys. For multi-row upserts, use * buildExcludedValue() to reference the value of a column from the corresponding row * in $rows that conflicts with the current row. * @param string $fname Calling function name (use __METHOD__) for logs/profiling @phan-mandatory-param * @throws DBError If an error occurs, {@see query} * @since 1.22 */ public function upsert( $table, array $rows, $uniqueKeys, array $set, $fname = __METHOD__ ); /** * Delete all rows in a table that match a condition which includes a join * * For safety, an empty $conds will not delete everything. If you want to * delete all rows where the join condition matches, set $conds=IDatabase::ALL_ROWS. * * DO NOT put the join condition in $conds. * * This operation will be seen by affectedRows()/insertId() as one query statement, * regardless of how many statements are actually sent by the class implementation. * * @param string $delTable The unqualified name of the table to delete rows from. * @param string $joinTable The unqualified name of the reference table to join on. * @param string $delVar The variable to join on, in the first table. * @param string $joinVar The variable to join on, in the second table. * @param string|IExpression|array<string,?scalar|non-empty-array<int,?scalar>|RawSQLValue>|array<int,string|IExpression> $conds * Condition array of field names mapped to variables, * ANDed together in the WHERE clause * @param string $fname Calling function name (use __METHOD__) for logs/profiling @phan-mandatory-param * @throws DBError If an error occurs, {@see query} */ public function deleteJoin( $delTable, $joinTable, $delVar, $joinVar, $conds, $fname = __METHOD__ ); /** * Delete all rows in a table that match a condition * * This operation will be seen by affectedRows()/insertId() as one query statement, * regardless of how many statements are actually sent by the class implementation. * * @internal callers outside of rdbms library should use DeleteQueryBuilder instead. * * @param string $table The unqualified name of a table * @param-taint $table exec_sql * @param string|IExpression|array<string,?scalar|non-empty-array<int,?scalar>|RawSQLValue>|array<int,string|IExpression> $conds * Array of conditions. See $conds in IDatabase::select() * In order to prevent possible performance or replication issues or damaging a data * accidentally, an empty condition for 'delete' queries isn't allowed. * IDatabase::ALL_ROWS should be passed explicitly in order to delete all rows. * @param-taint $conds exec_sql_numkey * @param string $fname Name of the calling function @phan-mandatory-param * @param-taint $fname exec_sql * @return bool Return true if no exception was thrown (deprecated since 1.33) * @return-taint none * @throws DBError If an error occurs, {@see query} */ public function delete( $table, $conds, $fname = __METHOD__ ); /** * INSERT SELECT wrapper * * @warning If the insert will use an auto-increment or sequence to * determine the value of a column, this may break replication on * databases using statement-based replication if the SELECT is not * deterministically ordered. * * This operation will be seen by affectedRows()/insertId() as one query statement, * regardless of how many statements are actually sent by the class implementation. * * @param string $destTable Unqualified name of destination table * @param string|array $srcTable Unqualified name of source table(s) (use an array for a join) * @param array $varMap Must be an associative array of the form * [ 'dest1' => 'source1', ... ]. Source items may be literals * rather than field names, but strings should be quoted with * IDatabase::addQuotes() * @param string|IExpression|array<string,?scalar|non-empty-array<int,?scalar>|RawSQLValue>|array<int,string|IExpression> $conds * Condition array. See $conds in IDatabase::select() for * the details of the format of condition arrays. May be "*" to copy the * whole table. * @param string $fname The function name of the caller, from __METHOD__ @phan-mandatory-param * @param array $insertOptions Options for the INSERT part of the query, see * IDatabase::insert() for details. Also, one additional option is * available: pass 'NO_AUTO_COLUMNS' to hint that the query does not use * an auto-increment or sequence to determine any column values. * @param array $selectOptions Options for the SELECT part of the query, see * IDatabase::select() for details. * @param array $selectJoinConds Join conditions for the SELECT part of the query, see * IDatabase::select() for details. * @return bool Return true if no exception was thrown (deprecated since 1.33) * @throws DBError If an error occurs, {@see query} */ public function insertSelect( $destTable, $srcTable, $varMap, $conds, $fname = __METHOD__, $insertOptions = [], $selectOptions = [], $selectJoinConds = [] ); /** * Run a callback when the current transaction commits or rolls back * * An error is thrown if no transaction is pending. * * When transaction round mode (DBO_TRX) is set, the callback will run at the end * of the round, just after all peer transactions COMMIT/ROLLBACK. * * This IDatabase instance will start off in auto-commit mode when the callback starts. * The use of other IDatabase handles from the callback should be avoided unless they are * known to be in auto-commit mode. Callbacks that create transactions via begin() or * startAtomic() must have matching calls to commit()/endAtomic(). * * Use this method only for the following purposes: * - (a) Release of cooperative locks on resources * - (b) Cancellation of in-process deferred tasks * * The callback takes the following arguments: * - How the current atomic section (if any) or overall transaction (otherwise) ended * (IDatabase::TRIGGER_COMMIT or IDatabase::TRIGGER_ROLLBACK) * - This IDatabase instance (since 1.32) * * Callbacks will execute in the order they were enqueued. * * @note Use onAtomicSectionCancel() to take action as soon as an atomic section is cancelled * * @param callable $callback * @param string $fname Caller name @phan-mandatory-param * @throws DBError If an error occurs, {@see query} * @throws Exception If the callback runs immediately and an error occurs in it * @since 1.28 */ public function onTransactionResolution( callable $callback, $fname = __METHOD__ ); /** * Run a callback when the current transaction commits or now if there is none * * If there is a transaction and it is rolled back, then the callback is cancelled. * * When transaction round mode (DBO_TRX) is set, the callback will run at the end * of the round, just after all peer transactions COMMIT. If the transaction round * is rolled back, then the callback is cancelled. * * This IDatabase instance will start off in auto-commit mode when the callback starts. * The use of other IDatabase handles from the callback should be avoided unless they are * known to be in auto-commit mode. Callbacks that create transactions via begin() or * startAtomic() must have matching calls to commit()/endAtomic(). * * Use this method only for the following purposes: * - (a) RDBMS updates, prone to lock timeouts/deadlocks, that do not require * atomicity with respect to the updates in the current transaction (if any) * - (b) Purges to lightweight cache services due to RDBMS updates * - (c) Updates to secondary DBs/stores that must only commit once the updates in * the current transaction (if any) are committed (e.g. insert user account row * to DB1, then, initialize corresponding LDAP account) * * The callback takes the following arguments: * - How the transaction ended (IDatabase::TRIGGER_COMMIT or IDatabase::TRIGGER_IDLE) * - This IDatabase instance (since 1.32) * * Callbacks will execute in the order they were enqueued. * * @param callable $callback * @param string $fname Caller name @phan-mandatory-param * @throws DBError If an error occurs, {@see query} * @throws Exception If the callback runs immediately and an error occurs in it * @since 1.32 */ public function onTransactionCommitOrIdle( callable $callback, $fname = __METHOD__ ); /** * Run a callback before the current transaction commits or now if there is none * * If there is a transaction and it is rolled back, then the callback is cancelled. * * When transaction round mode (DBO_TRX) is set, the callback will run at the end * of the round, just after all peer transactions COMMIT. If the transaction round * is rolled back, then the callback is cancelled. * * If there is no current transaction, one will be created to wrap the callback. * Callbacks cannot use begin()/commit() to manage transactions. The use of other * IDatabase handles from the callback should be avoided. * * Use this method only for the following purposes: * - a) RDBMS updates, prone to lock timeouts/deadlocks, that require atomicity * with respect to the updates in the current transaction (if any) * - b) Purges to lightweight cache services due to RDBMS updates * * The callback takes the one argument: * - This IDatabase instance (since 1.32) * * Callbacks will execute in the order they were enqueued. * * @param callable $callback * @param string $fname Caller name @phan-mandatory-param * @throws DBError If an error occurs, {@see query} * @throws Exception If the callback runs immediately and an error occurs in it * @since 1.22 */ public function onTransactionPreCommitOrIdle( callable $callback, $fname = __METHOD__ ); /** * Run a callback when the atomic section is cancelled * * The callback is run just after the current atomic section, any outer * atomic section, or the whole transaction is rolled back. * * An error is thrown if no atomic section is pending. The atomic section * need not have been created with the ATOMIC_CANCELABLE flag. * * Queries in the function may be running in the context of an outer * transaction or may be running in AUTOCOMMIT mode. The callback should * use atomic sections if necessary. * * @note do not assume that *other* IDatabase instances will be AUTOCOMMIT mode * * The callback takes the following arguments: * - IDatabase::TRIGGER_CANCEL or IDatabase::TRIGGER_ROLLBACK * - This IDatabase instance * * @param callable $callback * @param string $fname Caller name @phan-mandatory-param * @since 1.34 */ public function onAtomicSectionCancel( callable $callback, $fname = __METHOD__ ); /** * Begin an atomic section of SQL statements * * Start an implicit transaction if no transaction is already active, set a savepoint * (if $cancelable is ATOMIC_CANCELABLE), and track the given section name to enforce * that the transaction is not committed prematurely. The end of the section must be * signified exactly once, either by endAtomic() or cancelAtomic(). Sections can have * have layers of inner sections (sub-sections), but all sections must be ended in order * of innermost to outermost. Transactions cannot be started or committed until all * atomic sections are closed. * * ATOMIC_CANCELABLE is useful when the caller needs to handle specific failure cases * by discarding the section's writes. This should not be used for failures when: * - upsert() could easily be used instead * - insert() with IGNORE could easily be used instead * - select() with FOR UPDATE could be checked before issuing writes instead * - The failure is from code that runs after the first write but doesn't need to * - The failures are from contention solvable via onTransactionPreCommitOrIdle() * - The failures are deadlocks; the RDBMs usually discard the whole transaction * * @note callers must use additional measures for situations involving two or more * (peer) transactions (e.g. updating two database servers at once). The transaction * and savepoint logic of this method only applies to this specific IDatabase instance. * * Example usage: * @code * // Start a transaction if there isn't one already * $dbw->startAtomic( __METHOD__ ); * // Serialize these thread table updates * $dbw->select( 'thread', '1', [ 'td_id' => $tid ], __METHOD__, 'FOR UPDATE' ); * // Add a new comment for the thread * $dbw->insert( 'comment', $row, __METHOD__ ); * $cid = $db->insertId(); * // Update thread reference to last comment * $dbw->update( 'thread', [ 'td_latest' => $cid ], [ 'td_id' => $tid ], __METHOD__ ); * // Demark the end of this conceptual unit of updates * $dbw->endAtomic( __METHOD__ ); * @endcode * * Example usage (atomic changes that might have to be discarded): * @code * // Start a transaction if there isn't one already * $sectionId = $dbw->startAtomic( __METHOD__, $dbw::ATOMIC_CANCELABLE ); * // Create new record metadata row * $dbw->insert( 'records', $row, __METHOD__ ); * // Figure out where to store the data based on the new row's ID * $path = $recordDirectory . '/' . $dbw->insertId(); * // Write the record data to the storage system * $status = $fileBackend->create( [ 'dst' => $path, 'content' => $data ] ); * if ( $status->isOK() ) { * // Try to cleanup files orphaned by transaction rollback * $dbw->onTransactionResolution( * function ( $type ) use ( $fileBackend, $path ) { * if ( $type === IDatabase::TRIGGER_ROLLBACK ) { * $fileBackend->delete( [ 'src' => $path ] ); * } * }, * __METHOD__ * ); * // Demark the end of this conceptual unit of updates * $dbw->endAtomic( __METHOD__ ); * } else { * // Discard these writes from the transaction (preserving prior writes) * $dbw->cancelAtomic( __METHOD__, $sectionId ); * } * @endcode * * @since 1.23 * @param string $fname @phan-mandatory-param * @param string $cancelable Pass self::ATOMIC_CANCELABLE to use a * savepoint and enable self::cancelAtomic() for this section. * @return AtomicSectionIdentifier section ID token * @throws DBError If an error occurs, {@see query} */ public function startAtomic( $fname = __METHOD__, $cancelable = self::ATOMIC_NOT_CANCELABLE ); /** * Ends an atomic section of SQL statements * * Ends the next section of atomic SQL statements and commits the transaction * if necessary. * * @since 1.23 * @see IDatabase::startAtomic * @param string $fname @phan-mandatory-param * @throws DBError If an error occurs, {@see query} */ public function endAtomic( $fname = __METHOD__ ); /** * Cancel an atomic section of SQL statements * * This will roll back only the statements executed since the start of the * most recent atomic section, and close that section. If a transaction was * open before the corresponding startAtomic() call, any statements before * that call are *not* rolled back and the transaction remains open. If the * corresponding startAtomic() implicitly started a transaction, that * transaction is rolled back. * * @note callers must use additional measures for situations involving two or more * (peer) transactions (e.g. updating two database servers at once). The transaction * and savepoint logic of startAtomic() are bound to specific IDatabase instances. * * Note that a call to IDatabase::rollback() will also roll back any open atomic sections. * * @note As an optimization to save rountrips, this method may only be called * when startAtomic() was called with the ATOMIC_CANCELABLE flag. * @since 1.31 * @see IDatabase::startAtomic * @param string $fname @phan-mandatory-param * @param AtomicSectionIdentifier|null $sectionId Section ID from startAtomic(); * passing this enables cancellation of unclosed nested sections [optional] * @throws DBError If an error occurs, {@see query} */ public function cancelAtomic( $fname = __METHOD__, ?AtomicSectionIdentifier $sectionId = null ); /** * Perform an atomic section of reversible SQL statements from a callback * * The $callback takes the following arguments: * - This database object * - The value of $fname * * This will execute the callback inside a pair of startAtomic()/endAtomic() calls. * If any exception occurs during execution of the callback, it will be handled as follows: * - If $cancelable is ATOMIC_CANCELABLE, cancelAtomic() will be called to back out any * (and only) statements executed during the atomic section. If that succeeds, then the * exception will be re-thrown; if it fails, then a different exception will be thrown * and any further query attempts will fail until rollback() is called. * - If $cancelable is ATOMIC_NOT_CANCELABLE, cancelAtomic() will be called to mark the * end of the section and the error will be re-thrown. Any further query attempts will * fail until rollback() is called. * * This method is convenient for letting calls to the caller of this method be wrapped * in a try/catch blocks for exception types that imply that the caller failed but was * able to properly discard the changes it made in the transaction. This method can be * an alternative to explicit calls to startAtomic()/endAtomic()/cancelAtomic(). * * Example usage, "RecordStore::save" method: * @code * $dbw->doAtomicSection( __METHOD__, function ( $dbw ) use ( $record ) { * // Create new record metadata row * $dbw->insert( 'records', $record->toArray(), __METHOD__ ); * // Figure out where to store the data based on the new row's ID * $path = $this->recordDirectory . '/' . $dbw->insertId(); * // Write the record data to the storage system; * // blob store throws StoreFailureException on failure * $this->blobStore->create( $path, $record->getJSON() ); * // Try to cleanup files orphaned by transaction rollback * $dbw->onTransactionResolution( * function ( $type ) use ( $path ) { * if ( $type === IDatabase::TRIGGER_ROLLBACK ) { * $this->blobStore->delete( $path ); * } * }, * __METHOD__ * ); * }, $dbw::ATOMIC_CANCELABLE ); * @endcode * * Example usage, caller of the "RecordStore::save" method: * @code * $dbw->startAtomic( __METHOD__ ); * // ...various SQL writes happen... * try { * $recordStore->save( $record ); * } catch ( StoreFailureException $e ) { * // ...various SQL writes happen... * } * // ...various SQL writes happen... * $dbw->endAtomic( __METHOD__ ); * @endcode * * @see Database::startAtomic * @see Database::endAtomic * @see Database::cancelAtomic * * @param string $fname Caller name (usually __METHOD__) @phan-mandatory-param * @param callable $callback Callback that issues write queries * @param string $cancelable Pass self::ATOMIC_CANCELABLE to use a * savepoint and enable self::cancelAtomic() for this section. * @return mixed Result of the callback (since 1.28) * @throws DBError If an error occurs, {@see query} * @throws Exception If an error occurs in the callback * @since 1.27; prior to 1.31 this did a rollback() instead of * cancelAtomic(), and assumed no callers up the stack would ever try to * catch the exception. */ public function doAtomicSection( $fname, callable $callback, $cancelable = self::ATOMIC_NOT_CANCELABLE ); /** * Begin a transaction * * Only call this from code with outer transaction scope. * See https://www.mediawiki.org/wiki/Database_transactions for details. * Nesting of transactions is not supported. * * Note that when the DBO_TRX flag is set (which is usually the case for web * requests, but not for maintenance scripts), any previous database query * will have started a transaction automatically. * * Nesting of transactions is not supported. Attempts to nest transactions * will cause a warning, unless the current transaction was started * automatically because of the DBO_TRX flag. * * @param string $fname Calling function name @phan-mandatory-param * @param string $mode A situationally valid IDatabase::TRANSACTION_* constant [optional] * @throws DBError If an error occurs, {@see query} */ public function begin( $fname = __METHOD__, $mode = self::TRANSACTION_EXPLICIT ); /** * Commits a transaction previously started using begin() * * If no transaction is in progress, a warning is issued. * * Only call this from code with outer transaction scope. * See https://www.mediawiki.org/wiki/Database_transactions for details. * Nesting of transactions is not supported. * * @param string $fname @phan-mandatory-param * @param string $flush Flush flag, set to situationally valid IDatabase::FLUSHING_* * constant to disable warnings about explicitly committing implicit transactions, * or calling commit when no transaction is in progress. * This will trigger an exception if there is an ongoing explicit transaction. * Only set the flush flag if you are sure that these warnings are not applicable, * and no explicit transactions are open. * @throws DBError If an error occurs, {@see query} */ public function commit( $fname = __METHOD__, $flush = self::FLUSHING_ONE ); /** * Rollback a transaction previously started using begin() * * Only call this from code with outer transaction scope. * See https://www.mediawiki.org/wiki/Database_transactions for details. * Nesting of transactions is not supported. If a serious unexpected error occurs, * throwing an Exception is preferable, using a pre-installed error handler to trigger * rollback (in any case, failure to issue COMMIT will cause rollback server-side). * * Query, connection, and onTransaction* callback errors will be suppressed and logged. * * @param string $fname Calling function name @phan-mandatory-param * @param string $flush Flush flag, set to a situationally valid IDatabase::FLUSHING_* * constant to disable warnings about explicitly rolling back implicit transactions. * This will silently break any ongoing explicit transaction. Only set the flush flag * if you are sure that it is safe to ignore these warnings in your context. * @throws DBError If an error occurs, {@see query} * @since 1.23 Added $flush parameter */ public function rollback( $fname = __METHOD__, $flush = self::FLUSHING_ONE ); /** * Commit any transaction but error out if writes or callbacks are pending * * This is intended for clearing out REPEATABLE-READ snapshots so that callers can * see a new point-in-time of the database. This is useful when one of many transaction * rounds finished and significant time will pass in the script's lifetime. It is also * useful to call on a replica server after waiting on replication to catch up to the * primary server. * * @param string $fname Calling function name @phan-mandatory-param * @param string $flush Flush flag, set to situationally valid IDatabase::FLUSHING_* * constant to disable warnings about explicitly committing implicit transactions, * or calling commit when no transaction is in progress. * This will trigger an exception if there is an ongoing explicit transaction. * Only set the flush flag if you are sure that these warnings are not applicable, * and no explicit transactions are open. * @throws DBError If an error occurs, {@see query} * @since 1.28 * @since 1.34 Added $flush parameter */ public function flushSnapshot( $fname = __METHOD__, $flush = self::FLUSHING_ONE ); /** * Override database's default behavior. * Not all options are supported on all database backends; * unsupported options are silently ignored. * * $options include: * - 'connTimeout': Set the connection timeout value in seconds. * May be useful for very long batch queries such as full-wiki dumps, * where a single query reads out over hours or days. * Only supported on MySQL and MariaDB. * - 'groupConcatMaxLen': Maximum length of a GROUP_CONCAT() result. * Only supported on MySQL and MariaDB. * * @param array $options * @return void * @throws DBError If an error occurs, {@see query} */ public function setSessionOptions( array $options ); /** * Check to see if a named lock is not locked by any thread (non-blocking) * * @param string $lockName Name of lock to poll * @param string $method Name of method calling us * @return bool * @throws DBError If an error occurs, {@see query} * @since 1.20 */ public function lockIsFree( $lockName, $method ); /** * Acquire a named lock * * Named locks are not related to transactions * * @param string $lockName Name of lock to acquire * @param string $method Name of the calling method * @param int $timeout Acquisition timeout in seconds (0 means non-blocking) * @param int $flags Bit field of IDatabase::LOCK_* constants * @return bool|float|null Success (bool); acquisition time (float/null) if LOCK_TIMESTAMP * @throws DBError If an error occurs, {@see query} */ public function lock( $lockName, $method, $timeout = 5, $flags = 0 ); /** * Release a lock * * Named locks are not related to transactions * * @param string $lockName Name of lock to release * @param string $method Name of the calling method * @return bool Success * @throws DBError If an error occurs, {@see query} */ public function unlock( $lockName, $method ); /** * Acquire a named lock, flush any transaction, and return an RAII style unlocker object * * Only call this from outer transaction scope and when only one DB server will be affected. * See https://www.mediawiki.org/wiki/Database_transactions for details. * * This is suitable for transactions that need to be serialized using cooperative locks, * where each transaction can see each others' changes. Any transaction is flushed to clear * out stale REPEATABLE-READ snapshot data. Once the returned object falls out of PHP scope, * the lock will be released unless a transaction is active. If one is active, then the lock * will be released when it either commits or rolls back. * * If the lock acquisition failed, then no transaction flush happens, and null is returned. * * @param string $lockKey Name of lock to release * @param string $fname Name of the calling method * @param int $timeout Acquisition timeout in seconds * @return ScopedCallback|null * @throws DBError If an error occurs, {@see query} * @since 1.27 */ public function getScopedLockAndFlush( $lockKey, $fname, $timeout ); /** * Check if this DB server is marked as read-only according to load balancer info * * @note LoadBalancer checks serverIsReadOnly() when setting the load balancer info array * * @return bool * @since 1.27 */ public function isReadOnly(); } PK ! (vUos s rdbms/database/DbQuoter.phpnu �Iw�� <?php namespace Wikimedia\Rdbms\Database; use Wikimedia\Rdbms\Blob; use Wikimedia\Rdbms\RawSQLValue; /** * @internal */ interface DbQuoter { /** * Escape and quote a raw value string for use in a SQL query * * @param ?scalar|RawSQLValue|Blob $s * @param-taint $s escapes_sql * @return string * @return-taint none */ public function addQuotes( $s ); } PK ! p�_�k k ( rdbms/database/domain/DatabaseDomain.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\Rdbms; use InvalidArgumentException; use Stringable; /** * Class to handle database/schema/prefix specifications for IDatabase * * The components of a database domain are defined as follows: * - database: name of a server-side collection of schemas that is client-selectable * - schema: name of a server-side collection of tables within the given database * - prefix: table name prefix of an application-defined table collection * * If an RDBMS does not support server-side collections of table collections (schemas) then * the schema component should be null and the "database" component treated as a collection * of exactly one table collection (the implied schema for that "database"). * * The above criteria should determine how components should map to RDBMS specific keywords * rather than "database"/"schema" always mapping to "DATABASE"/"SCHEMA" as used by the RDBMS. * * @ingroup Database */ class DatabaseDomain implements Stringable { /** @var string|null */ private $database; /** @var string|null */ private $schema; /** @var string */ private $prefix; /** @var string Cache of convertToString() */ private $equivalentString; /** * @param string|null $database Database name * @param string|null $schema Schema name * @param string $prefix Table prefix */ public function __construct( $database, $schema, $prefix ) { if ( $database !== null && ( !is_string( $database ) || $database === '' ) ) { throw new InvalidArgumentException( 'Database must be null or a non-empty string.' ); } $this->database = $database; if ( $schema !== null && ( !is_string( $schema ) || $schema === '' ) ) { throw new InvalidArgumentException( 'Schema must be null or a non-empty string.' ); } elseif ( $database === null && $schema !== null ) { throw new InvalidArgumentException( 'Schema must be null if database is null.' ); } $this->schema = $schema; if ( !is_string( $prefix ) ) { throw new InvalidArgumentException( "Prefix must be a string." ); } $this->prefix = $prefix; } /** * @param DatabaseDomain|string $domain Result of DatabaseDomain::toString() * @return DatabaseDomain */ public static function newFromId( $domain ): self { if ( $domain instanceof self ) { return $domain; } if ( !is_string( $domain ) ) { throw new InvalidArgumentException( "Domain must be a string or " . __CLASS__ ); } $parts = explode( '-', $domain ); foreach ( $parts as &$part ) { $part = strtr( $part, [ '?h' => '-', '??' => '?' ] ); } $schema = null; $prefix = ''; if ( count( $parts ) == 1 ) { $database = $parts[0]; } elseif ( count( $parts ) == 2 ) { [ $database, $prefix ] = $parts; } elseif ( count( $parts ) == 3 ) { [ $database, $schema, $prefix ] = $parts; } else { throw new InvalidArgumentException( "Domain '$domain' has too few or too many parts." ); } if ( $database === '' ) { $database = null; } if ( $schema === '' ) { $schema = null; } $instance = new self( $database, $schema, $prefix ); $instance->equivalentString = $domain; return $instance; } /** * @return DatabaseDomain */ public static function newUnspecified() { return new self( null, null, '' ); } /** * @param DatabaseDomain|string $other * @return bool Whether the domain instances are the same by value */ public function equals( $other ) { if ( $other instanceof self ) { return ( $this->database === $other->database && $this->schema === $other->schema && $this->prefix === $other->prefix ); } return ( $this->getId() === $other ); } /** * Check whether the domain $other meets the specifications of this domain * * If this instance has a null database specifier, then $other can have any database * specifier, including null. This is likewise true if the schema specifier is null. * This is not transitive like equals() since a domain that explicitly wants a certain * database or schema cannot be satisfied by one of another (nor null). If the prefix * is empty and the DB and schema are both null, then the entire domain is considered * unspecified, and any prefix of $other is considered compatible. * * @param DatabaseDomain|string $other * @return bool * @since 1.32 */ public function isCompatible( $other ) { if ( $this->isUnspecified() ) { return true; // even the prefix doesn't matter } $other = self::newFromId( $other ); return ( ( $this->database === $other->database || $this->database === null ) && ( $this->schema === $other->schema || $this->schema === null ) && $this->prefix === $other->prefix ); } /** * @return bool * @since 1.32 */ public function isUnspecified() { return ( $this->database === null && $this->schema === null && $this->prefix === '' ); } /** * @return string|null Database name */ public function getDatabase() { return $this->database; } /** * @return string|null Database schema */ public function getSchema() { return $this->schema; } /** * @return string Table prefix */ public function getTablePrefix() { return $this->prefix; } /** * @return string */ public function getId(): string { $this->equivalentString ??= $this->convertToString(); return $this->equivalentString; } /** * @return string */ private function convertToString(): string { $parts = [ (string)$this->database ]; if ( $this->schema !== null ) { $parts[] = $this->schema; } if ( $this->prefix != '' || $this->schema !== null ) { // If there is a schema, then we need the prefix to disambiguate. // For engines like Postgres that use schemas, this awkwardness is hopefully // avoided since it is easy to have one DB per server (to avoid having many users) // and use schema/prefix to have wiki farms. For example, a domain schemes could be // wiki-<project>-<language>, e.g. "wiki-fitness-es"/"wiki-sports-fr"/"wiki-news-en". $parts[] = $this->prefix; } foreach ( $parts as &$part ) { $part = strtr( $part, [ '-' => '?h', '?' => '??' ] ); } return implode( '-', $parts ); } /** * @return string */ public function __toString() { return $this->getId(); } } PK ! Ê�� � ! rdbms/database/IDatabaseFlags.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\Rdbms\Database; /** * @ingroup Database */ interface IDatabaseFlags { /** Do not remember the prior flags */ public const REMEMBER_NOTHING = ''; /** Remember the prior flags */ public const REMEMBER_PRIOR = 'remember'; /** Restore to the prior flag state */ public const RESTORE_PRIOR = 'prior'; /** Restore to the initial flag state */ public const RESTORE_INITIAL = 'initial'; /** Enable debug logging of all SQL queries */ public const DBO_DEBUG = 1; /** Unused since 1.34 */ public const DBO_NOBUFFER = 2; /** Unused since 1.31 */ public const DBO_IGNORE = 4; /** Automatically start a transaction before running a query if none is active */ public const DBO_TRX = 8; /** Join load balancer transaction rounds (which control DBO_TRX) in non-CLI mode */ public const DBO_DEFAULT = 16; /** Use DB persistent connections if possible */ public const DBO_PERSISTENT = 32; /** DBA session mode; was used by Oracle */ public const DBO_SYSDBA = 64; /** Schema file mode; was used by Oracle */ public const DBO_DDLMODE = 128; /** * Enable SSL/TLS in connection protocol * @deprecated since 1.39 use 'ssl' parameter */ public const DBO_SSL = 256; /** Enable compression in connection protocol */ public const DBO_COMPRESS = 512; /** Optimize connection for guaging server state (e.g. ILoadBalancer::CONN_UNTRACKED_GAUGE) */ public const DBO_GAUGE = 1024; /** * Set a flag for this connection * * @param int $flag One of (IDatabase::DBO_DEBUG, IDatabase::DBO_TRX) * @param string $remember IDatabase::REMEMBER_* constant [default: REMEMBER_NOTHING] */ public function setFlag( $flag, $remember = self::REMEMBER_NOTHING ); /** * Clear a flag for this connection * * @param int $flag One of (IDatabase::DBO_DEBUG, IDatabase::DBO_TRX) * @param string $remember IDatabase::REMEMBER_* constant [default: REMEMBER_NOTHING] */ public function clearFlag( $flag, $remember = self::REMEMBER_NOTHING ); /** * Restore the flags to their prior state before the last setFlag/clearFlag call * * @param string $state IDatabase::RESTORE_* constant. [default: RESTORE_PRIOR] * @since 1.28 */ public function restoreFlags( $state = self::RESTORE_PRIOR ); /** * Returns a boolean whether the flag $flag is set for this connection * * @param int $flag One of the class IDatabase::DBO_* constants * @return bool */ public function getFlag( $flag ); } PK ! �R��s s ) rdbms/database/QueryBuilderFromRawSql.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\Rdbms; use Wikimedia\Rdbms\Platform\SQLPlatform; /** * This is to contain any regex on SQL work and get rid of them eventually * * This is a radioactive swamp and an extremely flawed and buggy last resort * for when the information has not been provided via Query object. * Bugs are to be expected in the regexes here. * * @ingroup Database * @internal * @since 1.41 */ class QueryBuilderFromRawSql { /** All the bits of QUERY_WRITE_* flags */ private const QUERY_CHANGE_MASK = ( SQLPlatform::QUERY_CHANGE_NONE | SQLPlatform::QUERY_CHANGE_TRX | SQLPlatform::QUERY_CHANGE_ROWS | SQLPlatform::QUERY_CHANGE_SCHEMA | SQLPlatform::QUERY_CHANGE_LOCKS ); private const SCHEMA_CHANGE_VERBS = [ 'CREATE', 'CREATE TEMPORARY', 'CREATE INDEX', 'CREATE DATABASE', 'ALTER', 'ALTER DATABASE', 'DROP', 'DROP INDEX', 'DROP DATABASE', ]; private const TRX_VERBS = [ 'BEGIN', 'COMMIT', 'ROLLBACK', 'SAVEPOINT', 'RELEASE SAVEPOINT', 'ROLLBACK TO SAVEPOINT', ]; private static string $queryVerbRegex; /** * @param string $sql * @param int $flags * @param string $tablePrefix * @return Query */ public static function buildQuery( string $sql, $flags, string $tablePrefix = '' ) { $verb = self::getQueryVerb( $sql ); if ( ( $flags & self::QUERY_CHANGE_MASK ) == 0 ) { $isWriteQuery = self::isWriteQuery( $sql ); if ( $isWriteQuery ) { if ( in_array( $verb, self::SCHEMA_CHANGE_VERBS, true ) ) { $flags |= SQLPlatform::QUERY_CHANGE_SCHEMA; } else { $flags |= SQLPlatform::QUERY_CHANGE_ROWS; } } else { if ( in_array( $verb, self::TRX_VERBS, true ) ) { $flags |= SQLPlatform::QUERY_CHANGE_TRX; } else { $flags |= SQLPlatform::QUERY_CHANGE_NONE; } } } return new Query( $sql, $flags, $verb, self::getWriteTable( $sql, $tablePrefix ) ); } private static function isWriteQuery( $rawSql ) { // Treat SELECT queries without FOR UPDATE queries as non-writes. This matches // how MySQL enforces read_only (FOR SHARE and LOCK IN SHADE MODE are allowed). // Handle (SELECT ...) UNION (SELECT ...) queries in a similar fashion. if ( preg_match( '/^\s*\(?SELECT\b/i', $rawSql ) ) { return (bool)preg_match( '/\bFOR\s+UPDATE\)?\s*$/i', $rawSql ); } // BEGIN and COMMIT queries are considered non-write queries here. // Database backends and drivers (MySQL, MariaDB, php-mysqli) generally // treat these as write queries, in that their results have "affected rows" // as meta data as from writes, instead of "num rows" as from reads. // But, we treat them as non-write queries because when reading data (from // either replica or primary DB) we use transactions to enable repeatable-read // snapshots, which ensures we get consistent results from the same snapshot // for all queries within a request. Use cases: // - Treating these as writes would trigger ChronologyProtector (see method doc). // - We use this method to reject writes to replicas, but we need to allow // use of transactions on replicas for read snapshots. This is fine given // that transactions by themselves don't make changes, only actual writes // within the transaction matter, which we still detect. return !preg_match( '/^\s*(BEGIN|ROLLBACK|COMMIT|SAVEPOINT|RELEASE|SET|SHOW|EXPLAIN|USE)\b/i', $rawSql ); } /** * @param string $sql SQL query * @return string */ private static function getQueryVerb( $sql ) { // @phan-suppress-next-line PhanRedundantCondition https://github.com/phan/phan/issues/4720 if ( !isset( self::$queryVerbRegex ) ) { $multiwordVerbsRegex = implode( '|', array_map( fn ( $words ) => str_replace( ' ', '\s+', $words ), Query::MULTIWORD_VERBS ) ); self::$queryVerbRegex = "/^\s*($multiwordVerbsRegex|[a-z]+)/i"; } return preg_match( self::$queryVerbRegex, $sql, $m ) ? strtoupper( $m[1] ) : ''; } /** * @param string $sql * @param string $tablePrefix * @return string|null */ private static function getWriteTable( $sql, $tablePrefix ) { // Regex for basic queries that can create/change/drop temporary tables. // For simplicity, this only looks for tables with sensible alphanumeric names. // Temporary tables only need simple programming names anyway. $regex = <<<REGEX /^ (?: (?:INSERT|REPLACE)\s+(?:\w+\s+)*?INTO | UPDATE(?:\s+OR\s+\w+|\s+IGNORE|\s+ONLY)? | DELETE\s+(?:\w+\s+)*?FROM(?:\s+ONLY)? | CREATE\s+(?:TEMPORARY\s+)?TABLE(?:\s+IF\s+NOT\s+EXISTS)? | DROP\s+(?:TEMPORARY\s+)?TABLE(?:\s+IF\s+EXISTS)? | TRUNCATE\s+(?:TEMPORARY\s+)?TABLE | ALTER\s+TABLE ) \s+ (\w+|`\w+`|'\w+'|"\w+") /ix REGEX; if ( preg_match( $regex, $sql, $m ) ) { $tableName = trim( $m[1], "\"'`" ); if ( str_starts_with( $tableName, $tablePrefix ) ) { $tableName = substr( $tableName, strlen( $tablePrefix ) ); } return $tableName; } return null; } /** * Removes most variables from an SQL query and replaces them with X or N for numbers. * It's only slightly flawed. Don't use for anything important. * * @param string $sql A SQL Query * * @return string */ public static function generalizeSQL( $sql ) { # This does the same as the regexp below would do, but in such a way # as to avoid crashing php on some large strings. # $sql = preg_replace( "/'([^\\\\']|\\\\.)*'|\"([^\\\\\"]|\\\\.)*\"/", "'X'", $sql ); $sql = str_replace( "\\\\", '', $sql ); $sql = str_replace( "\\'", '', $sql ); $sql = str_replace( "\\\"", '', $sql ); $sql = preg_replace( "/'.*'/s", "'X'", $sql ); $sql = preg_replace( '/".*"/s', "'X'", $sql ); # All newlines, tabs, etc replaced by single space $sql = preg_replace( '/\s+/', ' ', $sql ); # All numbers => N, # except the ones surrounded by characters, e.g. l10n $sql = preg_replace( '/-?\d++(,-?\d++)+/', 'N,...,N', $sql ); $sql = preg_replace( '/(?<![a-zA-Z])-?\d+(?![a-zA-Z])/', 'N', $sql ); return $sql; } } PK ! ��q{ { . rdbms/database/utils/TransactionIdentifier.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\Rdbms; use Stringable; /** * Class used for token representing identifiers for atomic transactions from IDatabase instances * * @ingroup Database * @internal */ class TransactionIdentifier implements Stringable { /** @var string Application-side ID of the active transaction or an empty string otherwise */ private $id = ''; public function __construct() { static $nextId; $nextId = ( $nextId !== null ? $nextId++ : mt_rand() ) % 0xffff; $this->id = sprintf( '%06x', mt_rand( 0, 0xffffff ) ) . sprintf( '%04x', $nextId ); } public function __toString() { return $this->id; } } PK ! �nߟ � $ rdbms/database/utils/QueryStatus.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\Rdbms; /** * @since 1.39 * @ingroup Database */ class QueryStatus { /** @var ResultWrapper|bool|null Result set */ public $res; /** @var int Returned row count */ public $rowsReturned; /** @var int Affected row count */ public $rowsAffected; /** @var string Error message or empty string */ public $message; /** @var int|string Error code or zero */ public $code; /** @var int Error flag bit field of Database::ERR_* constants */ public $flags; /** * @internal Should only be constructed by Database * * @param ResultWrapper|bool|null $res * @param int $affected * @param string $error * @param int|string $errno */ public function __construct( $res, int $affected, string $error, $errno ) { if ( !( $res instanceof IResultWrapper ) && !is_bool( $res ) && $res !== null ) { throw new DBUnexpectedError( null, 'Got ' . get_debug_type( $res ) . ' instead of IResultWrapper|bool' ); } $this->res = $res; $this->rowsReturned = ( $res instanceof IResultWrapper ) ? $res->numRows() : 0; $this->rowsAffected = $affected; $this->message = $error; $this->code = $errno; $this->flags = 0; } } PK ! (�k�� � 0 rdbms/database/utils/AtomicSectionIdentifier.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\Rdbms; /** * Class used for token representing identifiers for atomic sections from IDatabase instances * * @ingroup Database * @internal */ class AtomicSectionIdentifier { } PK ! �/� p p , rdbms/database/utils/CriticalSessionInfo.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\Rdbms; /** * @ingroup Database * @internal This class should not be used outside of Database */ class CriticalSessionInfo { /** @var TransactionIdentifier|null */ public $trxId; /** @var bool */ public $trxExplicit; /** @var string[] */ public $trxWriteCallers; /** @var string[] */ public $trxPreCommitCbCallers; /** @var array<string,array> */ public $namedLocks; /** @var array<string,array<string, TempTableInfo>> */ public $tempTables; /** * @param TransactionIdentifier|null $trxId * @param bool $trxExplicit * @param array $trxWriteCallers * @param array $trxPreCommitCbCallers * @param array $namedLocks * @param array $tempTables */ public function __construct( ?TransactionIdentifier $trxId, bool $trxExplicit, array $trxWriteCallers, array $trxPreCommitCbCallers, array $namedLocks, array $tempTables ) { $this->trxId = $trxId; $this->trxExplicit = $trxExplicit; $this->trxWriteCallers = $trxWriteCallers; $this->trxPreCommitCbCallers = $trxPreCommitCbCallers; $this->namedLocks = $namedLocks; $this->tempTables = $tempTables; } } PK ! ��k�W W ' rdbms/database/utils/GeneralizedSql.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\Rdbms; /** * Lazy-loaded wrapper for simplification and scrubbing of SQL queries for profiling * * @since 1.34 * @ingroup Profiler * @ingroup Database */ class GeneralizedSql { /** @var string */ private $rawSql; /** @var string */ private $prefix; /** @var string|null */ private $genericSql; /** * @param string $rawSql * @param string $prefix */ public function __construct( $rawSql, $prefix ) { $this->rawSql = $rawSql; $this->prefix = $prefix; } /** * @return string */ public function stringify() { if ( $this->genericSql !== null ) { return $this->genericSql; } $this->genericSql = $this->prefix . substr( QueryBuilderFromRawSql::generalizeSQL( $this->rawSql ), 0, 255 ); return $this->genericSql; } public function getRawSql() { return $this->rawSql; } } PK ! ���IP P & rdbms/database/utils/TempTableInfo.phpnu �Iw�� <?php namespace Wikimedia\Rdbms; /** * @internal */ class TempTableInfo { /** * @var ?TransactionIdentifier The transaction ID in which the table was * created. This is used to judge whether a rollback is tolerable. */ public ?TransactionIdentifier $trxId; /** * @var bool Whether the table is a pseudo-permanent temporary table, that is, * duplicated for PHPUnit testing. */ public bool $pseudoPermanent; public function __construct( ?TransactionIdentifier $trxId, bool $pseudoPermanent ) { $this->trxId = $trxId; $this->pseudoPermanent = $pseudoPermanent; } } PK ! o��Yz Yz # rdbms/database/DatabasePostgres.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ // Suppress UnusedPluginSuppression because Phan on PHP 7.4 and PHP 8.1 need different suppressions // @phan-file-suppress UnusedPluginSuppression,UnusedPluginFileSuppression namespace Wikimedia\Rdbms; use RuntimeException; use Wikimedia\Rdbms\Platform\PostgresPlatform; use Wikimedia\Rdbms\Replication\ReplicationReporter; use Wikimedia\WaitConditionLoop; /** * Postgres database abstraction layer. * * @ingroup Database */ class DatabasePostgres extends Database { /** @var int */ private $port; /** @var string */ private $tempSchema; /** @var float|string */ private $numericVersion; /** @var resource|null */ private $lastResultHandle; /** @var PostgresPlatform */ protected $platform; /** * @see Database::__construct() * @param array $params Additional parameters include: * - port: A port to append to the hostname */ public function __construct( array $params ) { $this->port = intval( $params['port'] ?? null ); parent::__construct( $params ); $this->platform = new PostgresPlatform( $this, $this->logger, $this->currentDomain, $this->errorLogger ); $this->replicationReporter = new ReplicationReporter( $params['topologyRole'], $this->logger, $params['srvCache'] ); } public function getType() { return 'postgres'; } protected function open( $server, $user, $password, $db, $schema, $tablePrefix ) { if ( !function_exists( 'pg_connect' ) ) { throw $this->newExceptionAfterConnectError( "Postgres functions missing, have you compiled PHP with the --with-pgsql\n" . "option? (Note: if you recently installed PHP, you may need to restart your\n" . "webserver and database)" ); } $this->close( __METHOD__ ); $connectVars = [ // A database must be specified in order to connect to Postgres. If $dbName is not // specified, then use the standard "postgres" database that should exist by default. 'dbname' => ( $db !== null && $db !== '' ) ? $db : 'postgres', 'user' => $user, 'password' => $password ]; if ( $server !== null && $server !== '' ) { $connectVars['host'] = $server; } if ( $this->port > 0 ) { $connectVars['port'] = $this->port; } if ( $this->ssl ) { $connectVars['sslmode'] = 'require'; } $connectString = $this->makeConnectionString( $connectVars ); $this->installErrorHandler(); try { $this->conn = pg_connect( $connectString, PGSQL_CONNECT_FORCE_NEW ) ?: null; } catch ( RuntimeException $e ) { $this->restoreErrorHandler(); throw $this->newExceptionAfterConnectError( $e->getMessage() ); } $error = $this->restoreErrorHandler(); if ( !$this->conn ) { throw $this->newExceptionAfterConnectError( $error ?: $this->lastError() ); } try { // Since no transaction is active at this point, any SET commands should apply // for the entire session (e.g. will not be reverted on transaction rollback). // See https://www.postgresql.org/docs/8.3/sql-set.html $variables = [ 'client_encoding' => 'UTF8', 'datestyle' => 'ISO, YMD', 'timezone' => 'GMT', 'standard_conforming_strings' => 'on', 'bytea_output' => 'escape', 'client_min_messages' => 'ERROR' ]; foreach ( $variables as $var => $val ) { $sql = 'SET ' . $this->platform->addIdentifierQuotes( $var ) . ' = ' . $this->addQuotes( $val ); $query = new Query( $sql, self::QUERY_NO_RETRY | self::QUERY_CHANGE_TRX, 'SET' ); $this->query( $query, __METHOD__ ); } $this->determineCoreSchema( $schema ); $this->currentDomain = new DatabaseDomain( $db, $schema, $tablePrefix ); $this->platform->setCurrentDomain( $this->currentDomain ); } catch ( RuntimeException $e ) { throw $this->newExceptionAfterConnectError( $e->getMessage() ); } } public function databasesAreIndependent() { return true; } public function doSelectDomain( DatabaseDomain $domain ) { $database = $domain->getDatabase(); if ( $database === null ) { // A null database means "don't care" so leave it as is and update the table prefix $this->currentDomain = new DatabaseDomain( $this->currentDomain->getDatabase(), $domain->getSchema() ?? $this->currentDomain->getSchema(), $domain->getTablePrefix() ); $this->platform->setCurrentDomain( $this->currentDomain ); } elseif ( $this->getDBname() !== $database ) { // Postgres doesn't support selectDB in the same way MySQL does. // So if the DB name doesn't match the open connection, open a new one $this->open( $this->connectionParams[self::CONN_HOST], $this->connectionParams[self::CONN_USER], $this->connectionParams[self::CONN_PASSWORD], $database, $domain->getSchema(), $domain->getTablePrefix() ); } else { $this->currentDomain = $domain; $this->platform->setCurrentDomain( $domain ); } return true; } /** * @param string[] $vars * @return string */ private function makeConnectionString( $vars ) { $s = ''; foreach ( $vars as $name => $value ) { $s .= "$name='" . str_replace( [ "\\", "'" ], [ "\\\\", "\\'" ], $value ) . "' "; } return $s; } protected function closeConnection() { return $this->conn ? pg_close( $this->conn ) : true; } public function doSingleStatementQuery( string $sql ): QueryStatus { $conn = $this->getBindingHandle(); $sql = mb_convert_encoding( $sql, 'UTF-8' ); // Clear any previously left over result // phpcs:ignore Generic.CodeAnalysis.AssignmentInCondition.FoundInWhileCondition while ( $priorRes = pg_get_result( $conn ) ) { pg_free_result( $priorRes ); } if ( pg_send_query( $conn, $sql ) === false ) { throw new DBUnexpectedError( $this, "Unable to post new query to PostgreSQL\n" ); } // Newer PHP versions use PgSql\Result instead of resource variables // https://www.php.net/manual/en/function.pg-get-result.php $pgRes = pg_get_result( $conn ); // Phan on PHP 7.4 and PHP 8.1 need different suppressions // @phan-suppress-next-line PhanTypeMismatchProperty,PhanTypeMismatchPropertyProbablyReal $this->lastResultHandle = $pgRes; $res = pg_result_error( $pgRes ) ? false : $pgRes; return new QueryStatus( // @phan-suppress-next-line PhanTypeMismatchArgument is_bool( $res ) ? $res : new PostgresResultWrapper( $this, $conn, $res ), $pgRes ? pg_affected_rows( $pgRes ) : 0, $this->lastError(), $this->lastErrno() ); } protected function dumpError() { $diags = [ PGSQL_DIAG_SEVERITY, PGSQL_DIAG_SQLSTATE, PGSQL_DIAG_MESSAGE_PRIMARY, PGSQL_DIAG_MESSAGE_DETAIL, PGSQL_DIAG_MESSAGE_HINT, PGSQL_DIAG_STATEMENT_POSITION, PGSQL_DIAG_INTERNAL_POSITION, PGSQL_DIAG_INTERNAL_QUERY, PGSQL_DIAG_CONTEXT, PGSQL_DIAG_SOURCE_FILE, PGSQL_DIAG_SOURCE_LINE, PGSQL_DIAG_SOURCE_FUNCTION ]; foreach ( $diags as $d ) { $this->logger->debug( sprintf( "PgSQL ERROR(%d): %s", // @phan-suppress-next-line PhanTypeMismatchArgumentInternal $d, pg_result_error_field( $this->lastResultHandle, $d ) ) ); } } protected function lastInsertId() { // Avoid using query() to prevent unwanted side-effects like changing affected // row counts or connection retries. Note that lastval() is connection-specific. // Note that this causes "lastval is not yet defined in this session" errors if // nextval() was never directly or implicitly triggered (error out any transaction). $qs = $this->doSingleStatementQuery( "SELECT lastval() AS id" ); return $qs->res ? (int)$qs->res->fetchRow()['id'] : 0; } public function lastError() { if ( $this->conn ) { if ( $this->lastResultHandle ) { // @phan-suppress-next-line PhanTypeMismatchArgumentInternal return pg_result_error( $this->lastResultHandle ); } else { return pg_last_error() ?: $this->lastConnectError; } } return $this->getLastPHPError() ?: 'No database connection'; } public function lastErrno() { if ( $this->lastResultHandle ) { // @phan-suppress-next-line PhanTypeMismatchArgumentInternal $lastErrno = pg_result_error_field( $this->lastResultHandle, PGSQL_DIAG_SQLSTATE ); if ( $lastErrno !== false ) { return $lastErrno; } } return '00000'; } public function estimateRowCount( $table, $var = '*', $conds = '', $fname = __METHOD__, $options = [], $join_conds = [] ): int { $conds = $this->platform->normalizeConditions( $conds, $fname ); $column = $this->platform->extractSingleFieldFromList( $var ); if ( is_string( $column ) && !in_array( $column, [ '*', '1' ] ) ) { $conds[] = "$column IS NOT NULL"; } $options['EXPLAIN'] = true; $res = $this->select( $table, $var, $conds, $fname, $options, $join_conds ); $rows = -1; if ( $res ) { $row = $res->fetchRow(); $count = []; if ( preg_match( '/rows=(\d+)/', $row[0], $count ) ) { $rows = (int)$count[1]; } } return $rows; } public function indexInfo( $table, $index, $fname = __METHOD__ ) { $components = $this->platform->qualifiedTableComponents( $table ); if ( count( $components ) === 1 ) { $schema = $this->getCoreSchema(); $tableComponent = $components[0]; } elseif ( count( $components ) === 2 ) { [ $schema, $tableComponent ] = $components; } else { [ , $schema, $tableComponent ] = $components; } $encSchema = $this->addQuotes( $schema ); $encTable = $this->addQuotes( $tableComponent ); $encIndex = $this->addQuotes( $this->platform->indexName( $index ) ); $query = new Query( "SELECT indexname,indexdef FROM pg_indexes " . "WHERE schemaname=$encSchema AND tablename=$encTable AND indexname=$encIndex", self::QUERY_IGNORE_DBO_TRX | self::QUERY_CHANGE_NONE, 'SELECT' ); $res = $this->query( $query ); $row = $res->fetchObject(); if ( $row ) { return [ 'unique' => ( strpos( $row->indexdef, 'CREATE UNIQUE ' ) === 0 ) ]; } return false; } public function indexAttributes( $index, $schema = false ) { if ( $schema === false ) { $schemas = $this->getCoreSchemas(); } else { $schemas = [ $schema ]; } $eindex = $this->addQuotes( $index ); $flags = self::QUERY_IGNORE_DBO_TRX | self::QUERY_CHANGE_NONE; foreach ( $schemas as $schema ) { $eschema = $this->addQuotes( $schema ); /* * A subquery would be not needed if we didn't care about the order * of attributes, but we do */ $sql = <<<__INDEXATTR__ SELECT opcname, attname, i.indoption[s.g] as option, pg_am.amname FROM (SELECT generate_series(array_lower(isub.indkey,1), array_upper(isub.indkey,1)) AS g FROM pg_index isub JOIN pg_class cis ON cis.oid=isub.indexrelid JOIN pg_namespace ns ON cis.relnamespace = ns.oid WHERE cis.relname=$eindex AND ns.nspname=$eschema) AS s, pg_attribute, pg_opclass opcls, pg_am, pg_class ci JOIN pg_index i ON ci.oid=i.indexrelid JOIN pg_class ct ON ct.oid = i.indrelid JOIN pg_namespace n ON ci.relnamespace = n.oid WHERE ci.relname=$eindex AND n.nspname=$eschema AND attrelid = ct.oid AND i.indkey[s.g] = attnum AND i.indclass[s.g] = opcls.oid AND pg_am.oid = opcls.opcmethod __INDEXATTR__; $query = new Query( $sql, $flags, 'SELECT' ); $res = $this->query( $query, __METHOD__ ); $a = []; if ( $res ) { foreach ( $res as $row ) { $a[] = [ $row->attname, $row->opcname, $row->amname, $row->option ]; } return $a; } } return null; } protected function doInsertSelectNative( $destTable, $srcTable, array $varMap, $conds, $fname, array $insertOptions, array $selectOptions, $selectJoinConds ) { if ( in_array( 'IGNORE', $insertOptions ) ) { // Use "ON CONFLICT DO" if we have it for IGNORE $destTableEnc = $this->tableName( $destTable ); $selectSql = $this->selectSQLText( $srcTable, array_values( $varMap ), $conds, $fname, $selectOptions, $selectJoinConds ); $sql = "INSERT INTO $destTableEnc (" . implode( ',', array_keys( $varMap ) ) . ') ' . $selectSql . ' ON CONFLICT DO NOTHING'; $query = new Query( $sql, self::QUERY_CHANGE_ROWS, 'INSERT', $destTable ); $this->query( $query, $fname ); } else { parent::doInsertSelectNative( $destTable, $srcTable, $varMap, $conds, $fname, $insertOptions, $selectOptions, $selectJoinConds ); } } public function getValueTypesForWithClause( $table ) { $typesByColumn = []; $flags = self::QUERY_IGNORE_DBO_TRX | self::QUERY_CHANGE_NONE; $encTable = $this->addQuotes( $table ); foreach ( $this->getCoreSchemas() as $schema ) { $encSchema = $this->addQuotes( $schema ); $sql = "SELECT column_name,udt_name " . "FROM information_schema.columns " . "WHERE table_name = $encTable AND table_schema = $encSchema"; $query = new Query( $sql, $flags, 'SELECT' ); $res = $this->query( $query, __METHOD__ ); if ( $res->numRows() ) { foreach ( $res as $row ) { $typesByColumn[$row->column_name] = $row->udt_name; } break; } } return $typesByColumn; } protected function isConnectionError( $errno ) { // https://www.postgresql.org/docs/9.2/static/errcodes-appendix.html static $codes = [ '08000', '08003', '08006', '08001', '08004', '57P01', '57P03', '53300' ]; return in_array( $errno, $codes, true ); } protected function isQueryTimeoutError( $errno ) { // https://www.postgresql.org/docs/9.2/static/errcodes-appendix.html return ( $errno === '57014' ); } protected function isKnownStatementRollbackError( $errno ) { return false; // transaction has to be rolled-back from error state } public function duplicateTableStructure( $oldName, $newName, $temporary = false, $fname = __METHOD__ ) { $newNameE = $this->platform->addIdentifierQuotes( $newName ); $oldNameE = $this->platform->addIdentifierQuotes( $oldName ); $temporary = $temporary ? 'TEMPORARY' : ''; $query = new Query( "CREATE $temporary TABLE $newNameE " . "(LIKE $oldNameE INCLUDING DEFAULTS INCLUDING INDEXES)", self::QUERY_PSEUDO_PERMANENT | self::QUERY_CHANGE_SCHEMA, $temporary ? 'CREATE TEMPORARY' : 'CREATE', // Use a dot to avoid double-prefixing in Database::getTempTableWrites() '.' . $newName ); $ret = $this->query( $query, $fname ); if ( !$ret ) { return $ret; } $sql = 'SELECT attname FROM pg_class c' . ' JOIN pg_namespace n ON (n.oid = c.relnamespace)' . ' JOIN pg_attribute a ON (a.attrelid = c.oid)' . ' JOIN pg_attrdef d ON (c.oid=d.adrelid and a.attnum=d.adnum)' . ' WHERE relkind = \'r\'' . ' AND nspname = ' . $this->addQuotes( $this->getCoreSchema() ) . ' AND relname = ' . $this->addQuotes( $oldName ) . ' AND pg_get_expr(adbin, adrelid) LIKE \'nextval(%\''; $query = new Query( $sql, self::QUERY_IGNORE_DBO_TRX | self::QUERY_CHANGE_NONE, 'SELECT' ); $res = $this->query( $query, $fname ); $row = $res->fetchObject(); if ( $row ) { $field = $row->attname; $newSeq = "{$newName}_{$field}_seq"; $fieldE = $this->platform->addIdentifierQuotes( $field ); $newSeqE = $this->platform->addIdentifierQuotes( $newSeq ); $newSeqQ = $this->addQuotes( $newSeq ); $query = new Query( "CREATE $temporary SEQUENCE $newSeqE OWNED BY $newNameE.$fieldE", self::QUERY_CHANGE_SCHEMA, 'CREATE', // Do not treat this is as a table modification on top of the CREATE above. null ); $this->query( $query, $fname ); $query = new Query( "ALTER TABLE $newNameE ALTER COLUMN $fieldE SET DEFAULT nextval({$newSeqQ}::regclass)", self::QUERY_CHANGE_SCHEMA, 'ALTER', // Do not treat this is as a table modification on top of the CREATE above. null ); $this->query( $query, $fname ); } return $ret; } public function truncateTable( $table, $fname = __METHOD__ ) { $sql = "TRUNCATE TABLE " . $this->tableName( $table ) . " RESTART IDENTITY"; $query = new Query( $sql, self::QUERY_CHANGE_SCHEMA, 'TRUNCATE', $table ); $this->query( $query, $fname ); } /** * @param string $prefix Only show tables with this prefix, e.g. mw_ * @param string $fname Calling function name * @return string[] * @suppress SecurityCheck-SQLInjection array_map not recognized T204911 */ public function listTables( $prefix = '', $fname = __METHOD__ ) { $eschemas = implode( ',', array_map( [ $this, 'addQuotes' ], $this->getCoreSchemas() ) ); $query = new Query( "SELECT DISTINCT tablename FROM pg_tables WHERE schemaname IN ($eschemas)", self::QUERY_IGNORE_DBO_TRX | self::QUERY_CHANGE_NONE, 'SELECT' ); $result = $this->query( $query, $fname ); $endArray = []; foreach ( $result as $table ) { $vars = get_object_vars( $table ); $table = array_pop( $vars ); if ( $prefix == '' || strpos( $table, $prefix ) === 0 ) { $endArray[] = $table; } } return $endArray; } /** * Posted by cc[plus]php[at]c2se[dot]com on 25-Mar-2009 09:12 * to https://www.php.net/manual/en/ref.pgsql.php * * Parsing a postgres array can be a tricky problem, he's my * take on this, it handles multi-dimensional arrays plus * escaping using a nasty regexp to determine the limits of each * data-item. * * This should really be handled by PHP PostgreSQL module * * @since 1.19 * @param string $text Postgreql array returned in a text form like {a,b} * @param string[] &$output * @param int|false $limit * @param int $offset * @return string[] */ private function pg_array_parse( $text, &$output, $limit = false, $offset = 1 ) { if ( $limit === false ) { $limit = strlen( $text ) - 1; $output = []; } if ( $text == '{}' ) { return $output; } do { if ( $text[$offset] != '{' ) { preg_match( "/(\\{?\"([^\"\\\\]|\\\\.)*\"|[^,{}]+)+([,}]+)/", $text, $match, 0, $offset ); $offset += strlen( $match[0] ); $output[] = ( $match[1][0] != '"' ? $match[1] : stripcslashes( substr( $match[1], 1, -1 ) ) ); if ( $match[3] == '},' ) { return $output; } } else { $offset = $this->pg_array_parse( $text, $output, $limit, $offset + 1 ); } } while ( $limit > $offset ); return $output; } public function getSoftwareLink() { return '[{{int:version-db-postgres-url}} PostgreSQL]'; } /** * Return current schema (executes SELECT current_schema()) * Needs transaction * * @since 1.19 * @return string Default schema for the current session */ public function getCurrentSchema() { $query = new Query( "SELECT current_schema()", self::QUERY_IGNORE_DBO_TRX | self::QUERY_CHANGE_NONE, 'SELECT' ); $res = $this->query( $query, __METHOD__ ); $row = $res->fetchRow(); return $row[0]; } /** * Return list of schemas which are accessible without schema name * This is list does not contain magic keywords like "$user" * Needs transaction * * @see getSearchPath() * @see setSearchPath() * @since 1.19 * @return array List of actual schemas for the current session */ public function getSchemas() { $query = new Query( "SELECT current_schemas(false)", self::QUERY_IGNORE_DBO_TRX | self::QUERY_CHANGE_NONE, 'SELECT' ); $res = $this->query( $query, __METHOD__ ); $row = $res->fetchRow(); $schemas = []; /* PHP pgsql support does not support array type, "{a,b}" string is returned */ return $this->pg_array_parse( $row[0], $schemas ); } /** * Return search patch for schemas * This is different from getSchemas() since it contain magic keywords * (like "$user"). * Needs transaction * * @since 1.19 * @return array How to search for table names schemas for the current user */ public function getSearchPath() { $query = new Query( "SHOW search_path", self::QUERY_IGNORE_DBO_TRX | self::QUERY_CHANGE_NONE, 'SHOW' ); $res = $this->query( $query, __METHOD__ ); $row = $res->fetchRow(); /* PostgreSQL returns SHOW values as strings */ return explode( ",", $row[0] ); } /** * Update search_path, values should already be sanitized * Values may contain magic keywords like "$user" * @since 1.19 * * @param string[] $search_path List of schemas to be searched by default */ private function setSearchPath( $search_path ) { $query = new Query( "SET search_path = " . implode( ", ", $search_path ), self::QUERY_CHANGE_TRX, 'SET' ); $this->query( $query, __METHOD__ ); } /** * Determine default schema for the current application * Adjust this session schema search path if desired schema exists * and is not already there. * * We need to have name of the core schema stored to be able * to query database metadata. * * This will be also called by the installer after the schema is created * * @since 1.19 * * @param string|null $desiredSchema */ public function determineCoreSchema( $desiredSchema ) { if ( $this->trxLevel() ) { // We do not want the schema selection to change on ROLLBACK or INSERT SELECT. // See https://www.postgresql.org/docs/8.3/sql-set.html throw new DBUnexpectedError( $this, __METHOD__ . ": a transaction is currently active" ); } if ( $this->schemaExists( $desiredSchema ) ) { if ( in_array( $desiredSchema, $this->getSchemas() ) ) { $this->platform->setCoreSchema( $desiredSchema ); $this->logger->debug( "Schema \"" . $desiredSchema . "\" already in the search path\n" ); } else { // Prepend the desired schema to the search path (T17816) $search_path = $this->getSearchPath(); array_unshift( $search_path, $this->platform->addIdentifierQuotes( $desiredSchema ) ); $this->setSearchPath( $search_path ); $this->platform->setCoreSchema( $desiredSchema ); $this->logger->debug( "Schema \"" . $desiredSchema . "\" added to the search path\n" ); } } else { $this->platform->setCoreSchema( $this->getCurrentSchema() ); $this->logger->debug( "Schema \"" . $desiredSchema . "\" not found, using current \"" . $this->getCoreSchema() . "\"\n" ); } } /** * Return schema name for core application tables * * @since 1.19 * @return string Core schema name */ public function getCoreSchema() { return $this->platform->getCoreSchema(); } /** * Return schema names for temporary tables and core application tables * * @since 1.31 * @return string[] schema names */ public function getCoreSchemas() { if ( $this->tempSchema ) { return [ $this->tempSchema, $this->getCoreSchema() ]; } $query = new Query( "SELECT nspname FROM pg_catalog.pg_namespace n WHERE n.oid = pg_my_temp_schema()", self::QUERY_IGNORE_DBO_TRX | self::QUERY_CHANGE_NONE, 'SELECT' ); $res = $this->query( $query, __METHOD__ ); $row = $res->fetchObject(); if ( $row ) { $this->tempSchema = $row->nspname; return [ $this->tempSchema, $this->getCoreSchema() ]; } return [ $this->getCoreSchema() ]; } public function getServerVersion() { if ( !isset( $this->numericVersion ) ) { // Works on PG 7.4+ $this->numericVersion = pg_version( $this->getBindingHandle() )['server']; } return $this->numericVersion; } /** * Query whether a given relation exists (in the given schema, or the * default mw one if not given) * @param string $table * @param array|string $types * @return bool */ private function relationExists( $table, $types ) { if ( !is_array( $types ) ) { $types = [ $types ]; } $schemas = $this->getCoreSchemas(); $components = $this->platform->qualifiedTableComponents( $table ); $etable = $this->addQuotes( end( $components ) ); foreach ( $schemas as $schema ) { $eschema = $this->addQuotes( $schema ); $sql = "SELECT 1 FROM pg_catalog.pg_class c, pg_catalog.pg_namespace n " . "WHERE c.relnamespace = n.oid AND c.relname = $etable AND n.nspname = $eschema " . "AND c.relkind IN ('" . implode( "','", $types ) . "')"; $query = new Query( $sql, self::QUERY_IGNORE_DBO_TRX | self::QUERY_CHANGE_NONE, 'SELECT' ); $res = $this->query( $query, __METHOD__ ); if ( $res && $res->numRows() ) { return true; } } return false; } public function tableExists( $table, $fname = __METHOD__ ) { return $this->relationExists( $table, [ 'r', 'v' ] ); } public function sequenceExists( $sequence ) { return $this->relationExists( $sequence, 'S' ); } public function constraintExists( $table, $constraint ) { foreach ( $this->getCoreSchemas() as $schema ) { $sql = sprintf( "SELECT 1 FROM information_schema.table_constraints " . "WHERE constraint_schema = %s AND table_name = %s AND constraint_name = %s", $this->addQuotes( $schema ), $this->addQuotes( $table ), $this->addQuotes( $constraint ) ); $query = new Query( $sql, self::QUERY_IGNORE_DBO_TRX | self::QUERY_CHANGE_NONE, 'SELECT' ); $res = $this->query( $query, __METHOD__ ); if ( $res && $res->numRows() ) { return true; } } return false; } /** * Query whether a given schema exists. Returns true if it does, false if it doesn't. * @param string|null $schema * @return bool */ public function schemaExists( $schema ) { if ( !strlen( $schema ?? '' ) ) { return false; // short-circuit } $query = new Query( "SELECT 1 FROM pg_catalog.pg_namespace " . "WHERE nspname = " . $this->addQuotes( $schema ) . " LIMIT 1", self::QUERY_IGNORE_DBO_TRX | self::QUERY_CHANGE_NONE, 'SELECT' ); $res = $this->query( $query, __METHOD__ ); return ( $res->numRows() > 0 ); } /** * Returns true if a given role (i.e. user) exists, false otherwise. * @param string $roleName * @return bool */ public function roleExists( $roleName ) { $query = new Query( "SELECT 1 FROM pg_catalog.pg_roles " . "WHERE rolname = " . $this->addQuotes( $roleName ) . " LIMIT 1", self::QUERY_IGNORE_DBO_TRX | self::QUERY_CHANGE_NONE, 'SELECT' ); $res = $this->query( $query, __METHOD__ ); return ( $res->numRows() > 0 ); } /** * @param string $table * @param string $field * @return PostgresField|null */ public function fieldInfo( $table, $field ) { return PostgresField::fromText( $this, $table, $field ); } public function encodeBlob( $b ) { $conn = $this->getBindingHandle(); return new PostgresBlob( pg_escape_bytea( $conn, $b ) ); } public function decodeBlob( $b ) { if ( $b instanceof PostgresBlob ) { $b = $b->fetch(); } elseif ( $b instanceof Blob ) { return $b->fetch(); } return pg_unescape_bytea( $b ); } public function strencode( $s ) { // Should not be called by us return pg_escape_string( $this->getBindingHandle(), (string)$s ); } public function addQuotes( $s ) { if ( $s instanceof RawSQLValue ) { return $s->toSql(); } $conn = $this->getBindingHandle(); if ( $s === null ) { return 'NULL'; } elseif ( is_bool( $s ) ) { return (string)intval( $s ); } elseif ( is_int( $s ) ) { return (string)$s; } elseif ( $s instanceof Blob ) { if ( $s instanceof PostgresBlob ) { $s = $s->fetch(); } else { $s = pg_escape_bytea( $conn, $s->fetch() ); } return "'$s'"; } return "'" . pg_escape_string( $conn, (string)$s ) . "'"; } public function streamStatementEnd( &$sql, &$newLine ) { # Allow dollar quoting for function declarations if ( str_starts_with( $newLine, '$mw$' ) ) { if ( $this->delimiter ) { $this->delimiter = false; } else { $this->delimiter = ';'; } } return parent::streamStatementEnd( $sql, $newLine ); } public function doLockIsFree( string $lockName, string $method ) { $query = new Query( $this->platform->lockIsFreeSQLText( $lockName ), self::QUERY_CHANGE_LOCKS, 'SELECT' ); $res = $this->query( $query, $method ); $row = $res->fetchObject(); return (bool)$row->unlocked; } public function doLock( string $lockName, string $method, int $timeout ) { $query = new Query( $this->platform->lockSQLText( $lockName, $timeout ), self::QUERY_CHANGE_LOCKS, 'SELECT' ); $acquired = null; $loop = new WaitConditionLoop( function () use ( $query, $method, &$acquired ) { $res = $this->query( $query, $method ); $row = $res->fetchObject(); if ( $row->acquired !== null ) { $acquired = (float)$row->acquired; return WaitConditionLoop::CONDITION_REACHED; } return WaitConditionLoop::CONDITION_CONTINUE; }, $timeout ); $loop->invoke(); return $acquired; } public function doUnlock( string $lockName, string $method ) { $query = new Query( $this->platform->unlockSQLText( $lockName ), self::QUERY_CHANGE_LOCKS, 'SELECT' ); $result = $this->query( $query, $method ); $row = $result->fetchObject(); return (bool)$row->released; } protected function doFlushSession( $fname ) { $flags = self::QUERY_CHANGE_LOCKS | self::QUERY_NO_RETRY; // https://www.postgresql.org/docs/9.1/functions-admin.html $sql = "SELECT pg_advisory_unlock_all()"; $query = new Query( $sql, $flags, 'UNLOCK' ); $qs = $this->executeQuery( $query, __METHOD__, $flags ); if ( $qs->res === false ) { $this->reportQueryError( $qs->message, $qs->code, $sql, $fname, true ); } } public function serverIsReadOnly() { $query = new Query( "SHOW default_transaction_read_only", self::QUERY_IGNORE_DBO_TRX | self::QUERY_CHANGE_NONE, 'SHOW' ); $res = $this->query( $query, __METHOD__ ); $row = $res->fetchObject(); return $row && strtolower( $row->default_transaction_read_only ) === 'on'; } protected function getInsertIdColumnForUpsert( $table ) { $column = null; $flags = self::QUERY_IGNORE_DBO_TRX | self::QUERY_CHANGE_NONE; $components = $this->platform->qualifiedTableComponents( $table ); $encTable = $this->addQuotes( end( $components ) ); foreach ( $this->getCoreSchemas() as $schema ) { $encSchema = $this->addQuotes( $schema ); $query = new Query( "SELECT column_name,data_type,column_default " . "FROM information_schema.columns " . "WHERE table_name = $encTable AND table_schema = $encSchema", self::QUERY_IGNORE_DBO_TRX | self::QUERY_CHANGE_NONE, 'SELECT' ); $res = $this->query( $query, __METHOD__ ); if ( $res->numRows() ) { foreach ( $res as $row ) { if ( $row->column_default !== null && str_starts_with( $row->column_default, "nextval(" ) && in_array( $row->data_type, [ 'integer', 'bigint' ], true ) ) { $column = $row->column_name; } } break; } } return $column; } public static function getAttributes() { return [ self::ATTR_SCHEMAS_AS_TABLE_GROUPS => true ]; } } PK ! �Z�0�~ �~ % rdbms/database/TransactionManager.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\Rdbms; use Psr\Log\LoggerInterface; use Psr\Log\NullLogger; use RuntimeException; use Throwable; use UnexpectedValueException; /** * @ingroup Database * @internal This class should not be used outside of Database */ class TransactionManager { /** Transaction is in a error state requiring a full or savepoint rollback */ public const STATUS_TRX_ERROR = 1; /** Transaction is active and in a normal state */ public const STATUS_TRX_OK = 2; /** No transaction is active */ public const STATUS_TRX_NONE = 3; /** Session is in a error state requiring a reset */ public const STATUS_SESS_ERROR = 1; /** Session is in a normal state */ public const STATUS_SESS_OK = 2; /** @var float Guess of how many seconds it takes to replicate a small insert */ private const TINY_WRITE_SEC = 0.010; /** @var float Consider a write slow if it took more than this many seconds */ private const SLOW_WRITE_SEC = 0.500; /** Assume an insert of this many rows or less should be fast to replicate */ private const SMALL_WRITE_ROWS = 100; /** @var string Prefix to the atomic section counter used to make savepoint IDs */ private const SAVEPOINT_PREFIX = 'wikimedia_rdbms_atomic'; /** @var ?TransactionIdentifier Application-side ID of the active (server-side) transaction */ private $trxId; /** @var ?float UNIX timestamp of BEGIN for the last transaction */ private $trxTimestamp = null; /** @var ?float Round trip time estimate for queries during the last transaction */ private $trxRoundTripDelay = null; /** @var int STATUS_TRX_* constant indicating the transaction lifecycle state */ private $trxStatus = self::STATUS_TRX_NONE; /** @var ?Throwable The cause of any unresolved transaction lifecycle state error */ private $trxStatusCause; /** @var ?array Details of any unresolved statement-rollback error within a transaction */ private $trxStatusIgnoredCause; /** @var ?Throwable The cause of any unresolved session state loss error */ private $sessionError; /** @var string[] Write query callers of the last transaction */ private $trxWriteCallers = []; /** @var float Seconds spent in write queries for the last transaction */ private $trxWriteDuration = 0.0; /** @var int Number of write queries for the last transaction */ private $trxWriteQueryCount = 0; /** @var int Number of rows affected by write queries for the last transaction */ private $trxWriteAffectedRows = 0; /** @var float Like trxWriteQueryCount but excludes lock-bound, easy to replicate, queries */ private $trxWriteAdjDuration = 0.0; /** @var int Number of write queries counted in trxWriteAdjDuration */ private $trxWriteAdjQueryCount = 0; /** @var array Pending atomic sections; list of (name, unique ID, savepoint ID) */ private $trxAtomicLevels = []; /** @var bool Whether the last transaction was started implicitly due to DBO_TRX */ private $trxAutomatic = false; /** @var bool Whether the last transaction was started implicitly by startAtomic() */ private $trxAutomaticAtomic = false; /** @var ?string Name of the function that started the last transaction */ private $trxFname = null; /** @var int Counter for atomic savepoint identifiers for the last transaction */ private $trxAtomicCounter = 0; /** * @var array[] Pending postcommit callbacks; list of (callable, method name, atomic section id) * @phan-var array<array{0:callable,1:string,2:AtomicSectionIdentifier|null}> */ private $trxPostCommitOrIdleCallbacks = []; /** * @var array[] Pending precommit callbacks; list of (callable, method name, atomic section id) * @phan-var array<array{0:callable,1:string,2:AtomicSectionIdentifier|null}> */ private $trxPreCommitOrIdleCallbacks = []; /** * @var array[] Pending post-trx callbacks; list of (callable, method name, atomic section id) * @phan-var array<array{0:callable,1:string,2:AtomicSectionIdentifier|null}> */ private $trxEndCallbacks = []; /** * @var array[] Pending cancel callbacks; list of (callable, method name, atomic section id) * @phan-var array<array{0:callable,1:string,2:AtomicSectionIdentifier|null}> */ private $trxSectionCancelCallbacks = []; /** @var callable[] Listener callbacks; map of (name => callable) */ private $trxRecurringCallbacks = []; /** @var bool Whether to suppress triggering of transaction end callbacks */ private $trxEndCallbacksSuppressed = false; /** @var LoggerInterface */ private $logger; /** @var TransactionProfiler */ private $profiler; public function __construct( ?LoggerInterface $logger = null, $profiler = null ) { $this->logger = $logger ?? new NullLogger(); $this->profiler = $profiler ?? new TransactionProfiler(); } public function trxLevel() { return $this->trxId ? 1 : 0; } /** * Get the application-side transaction identifier instance * * @return ?TransactionIdentifier Token for the active transaction; null if there isn't one */ public function getTrxId() { return $this->trxId; } /** * Reset the application-side transaction identifier instance and return the old one * * @return ?TransactionIdentifier The old transaction token; null if there wasn't one */ private function consumeTrxId() { $old = $this->trxId; $this->trxId = null; return $old; } public function trxTimestamp(): ?float { return $this->trxLevel() ? $this->trxTimestamp : null; } /** * @return int One of the STATUS_TRX_* class constants */ public function trxStatus(): int { return $this->trxStatus; } public function setTrxStatusToOk() { $this->trxStatus = self::STATUS_TRX_OK; $this->trxStatusCause = null; $this->trxStatusIgnoredCause = null; } public function setTrxStatusToNone() { $this->trxStatus = self::STATUS_TRX_NONE; $this->trxStatusCause = null; $this->trxStatusIgnoredCause = null; } public function assertTransactionStatus( IDatabase $db, $deprecationLogger, $fname ) { if ( $this->trxStatus === self::STATUS_TRX_ERROR ) { throw new DBTransactionStateError( $db, "Cannot execute query from $fname while transaction status is ERROR", [], $this->trxStatusCause ); } elseif ( $this->trxStatus === self::STATUS_TRX_OK && $this->trxStatusIgnoredCause ) { [ $iLastError, $iLastErrno, $iFname ] = $this->trxStatusIgnoredCause; call_user_func( $deprecationLogger, "Caller from $fname ignored an error originally raised from $iFname: " . "[$iLastErrno] $iLastError" ); $this->trxStatusIgnoredCause = null; } } public function assertSessionStatus( IDatabase $db, $fname ) { if ( $this->sessionError ) { throw new DBSessionStateError( $db, "Cannot execute query from $fname while session status is ERROR", [], $this->sessionError ); } } /** * Mark the transaction as requiring rollback (STATUS_TRX_ERROR) due to an error * * @param Throwable $trxError */ public function setTransactionError( Throwable $trxError ) { if ( $this->trxStatus !== self::STATUS_TRX_ERROR ) { $this->trxStatus = self::STATUS_TRX_ERROR; $this->trxStatusCause = $trxError; } } /** * @param array|null $trxStatusIgnoredCause */ public function setTrxStatusIgnoredCause( ?array $trxStatusIgnoredCause ): void { $this->trxStatusIgnoredCause = $trxStatusIgnoredCause; } /** * Get the status of the current session (ephemeral server-side state tied to the connection) * * @return int One of the STATUS_SESSION_* class constants */ public function sessionStatus() { // Check if an unresolved error still exists return ( $this->sessionError ) ? self::STATUS_SESS_ERROR : self::STATUS_SESS_OK; } /** * Flag the session as needing a reset due to an error, if not already flagged * * @param Throwable $sessionError */ public function setSessionError( Throwable $sessionError ) { $this->sessionError ??= $sessionError; } /** * Unflag the session as needing a reset due to an error */ public function clearSessionError() { $this->sessionError = null; } /** * @param float $rtt * @return float Time to apply writes to replicas based on trxWrite* fields */ private function calculateLastTrxApplyTime( float $rtt ) { $rttAdjTotal = $this->trxWriteAdjQueryCount * $rtt; $applyTime = max( $this->trxWriteAdjDuration - $rttAdjTotal, 0.0 ); // For omitted queries, make them count as something at least $omitted = $this->trxWriteQueryCount - $this->trxWriteAdjQueryCount; $applyTime += self::TINY_WRITE_SEC * $omitted; return $applyTime; } public function pendingWriteCallers() { return $this->trxLevel() ? $this->trxWriteCallers : []; } /** * Update the estimated run-time of a query, not counting large row lock times * * LoadBalancer can be set to rollback transactions that will create huge replication * lag. It bases this estimate off of pendingWriteQueryDuration(). Certain simple * queries, like inserting a row can take a long time due to row locking. This method * uses some simple heuristics to discount those cases. * * @param string $queryVerb action in the write query * @param float $runtime Total runtime, including RTT * @param int $affected Affected row count * @param string $fname method name invoking the action */ public function updateTrxWriteQueryReport( $queryVerb, $runtime, $affected, $fname ) { // Whether this is indicative of replica DB runtime (except for RBR or ws_repl) $indicativeOfReplicaRuntime = true; if ( $runtime > self::SLOW_WRITE_SEC ) { // insert(), upsert(), replace() are fast unless bulky in size or blocked on locks if ( $queryVerb === 'INSERT' ) { $indicativeOfReplicaRuntime = $affected > self::SMALL_WRITE_ROWS; } elseif ( $queryVerb === 'REPLACE' ) { $indicativeOfReplicaRuntime = $affected > self::SMALL_WRITE_ROWS / 2; } } $this->trxWriteDuration += $runtime; $this->trxWriteQueryCount += 1; $this->trxWriteAffectedRows += $affected; if ( $indicativeOfReplicaRuntime ) { $this->trxWriteAdjDuration += $runtime; $this->trxWriteAdjQueryCount += 1; } $this->trxWriteCallers[] = $fname; } public function pendingWriteQueryDuration( $type = IDatabase::ESTIMATE_TOTAL ) { if ( !$this->trxLevel() ) { return false; } elseif ( !$this->trxWriteCallers ) { return 0.0; } if ( $type === IDatabase::ESTIMATE_DB_APPLY ) { return $this->calculateLastTrxApplyTime( $this->trxRoundTripDelay ); } return $this->trxWriteDuration; } /** * @return string */ private function flatAtomicSectionList() { return array_reduce( $this->trxAtomicLevels, static function ( $accum, $v ) { return $accum === null ? $v[0] : "$accum, " . $v[0]; } ); } public function resetTrxAtomicLevels() { $this->trxAtomicLevels = []; $this->trxAtomicCounter = 0; } public function explicitTrxActive() { return $this->trxLevel() && ( $this->trxAtomicLevels || !$this->trxAutomatic ); } public function trxCheckBeforeClose( IDatabaseForOwner $db, $fname ) { $error = null; if ( $this->trxAtomicLevels ) { // Cannot let incomplete atomic sections be committed $levels = $this->flatAtomicSectionList(); $error = "$fname: atomic sections $levels are still open"; } elseif ( $this->trxAutomatic ) { // Only the connection manager can commit non-empty DBO_TRX transactions // (empty ones we can silently roll back) if ( $db->writesOrCallbacksPending() ) { $error = "$fname: " . "expected mass rollback of all peer transactions (DBO_TRX set)"; } } else { // Manual transactions should have been committed or rolled // back, even if empty. $error = "$fname: transaction is still open (from {$this->trxFname})"; } if ( $this->trxEndCallbacksSuppressed && $error === null ) { $error = "$fname: callbacks are suppressed; cannot properly commit"; } return $error; } public function onAtomicSectionCancel( IDatabase $db, $callback, $fname ): void { if ( !$this->trxLevel() || !$this->trxAtomicLevels ) { throw new DBUnexpectedError( $db, "No atomic section is open (got $fname)" ); } $this->trxSectionCancelCallbacks[] = [ $callback, $fname, $this->currentAtomicSectionId() ]; } public function onCancelAtomicBeforeCriticalSection( IDatabase $db, $fname ): void { if ( !$this->trxLevel() || !$this->trxAtomicLevels ) { throw new DBUnexpectedError( $db, "No atomic section is open (got $fname)" ); } } /** * @return AtomicSectionIdentifier|null ID of the topmost atomic section level */ public function currentAtomicSectionId(): ?AtomicSectionIdentifier { if ( $this->trxLevel() && $this->trxAtomicLevels ) { $levelInfo = end( $this->trxAtomicLevels ); return $levelInfo[1]; } return null; } public function addToAtomicLevels( $fname, AtomicSectionIdentifier $sectionId, $savepointId ) { $this->trxAtomicLevels[] = [ $fname, $sectionId, $savepointId ]; $this->logger->debug( 'startAtomic: entering level ' . ( count( $this->trxAtomicLevels ) - 1 ) . " ($fname)", [ 'db_log_category' => 'trx' ] ); } public function onBegin( IDatabase $db, $fname ): void { // Protect against mismatched atomic section, transaction nesting, and snapshot loss if ( $this->trxLevel() ) { if ( $this->trxAtomicLevels ) { $levels = $this->flatAtomicSectionList(); $msg = "$fname: got explicit BEGIN while atomic section(s) $levels are open"; throw new DBUnexpectedError( $db, $msg ); } elseif ( !$this->trxAutomatic ) { $msg = "$fname: explicit transaction already active (from {$this->trxFname})"; throw new DBUnexpectedError( $db, $msg ); } else { $msg = "$fname: implicit transaction already active (from {$this->trxFname})"; throw new DBUnexpectedError( $db, $msg ); } } } /** * @param IDatabase $db * @param string $fname * @param string $flush one of IDatabase::FLUSHING_* values * @return bool false if the commit should go aborted, true otherwise. */ public function onCommit( IDatabase $db, $fname, $flush ): bool { if ( $this->trxLevel() && $this->trxAtomicLevels ) { // There are still atomic sections open; this cannot be ignored $levels = $this->flatAtomicSectionList(); throw new DBUnexpectedError( $db, "$fname: got COMMIT while atomic sections $levels are still open" ); } if ( $flush === IDatabase::FLUSHING_INTERNAL || $flush === IDatabase::FLUSHING_ALL_PEERS ) { if ( !$this->trxLevel() ) { return false; // nothing to do } elseif ( !$this->trxAutomatic ) { throw new DBUnexpectedError( $db, "$fname: flushing an explicit transaction, getting out of sync" ); } } elseif ( !$this->trxLevel() ) { $this->logger->error( "$fname: no transaction to commit, something got out of sync", [ 'exception' => new RuntimeException(), 'db_log_category' => 'trx' ] ); return false; // nothing to do } elseif ( $this->trxAutomatic ) { throw new DBUnexpectedError( $db, "$fname: expected mass commit of all peer transactions (DBO_TRX set)" ); } return true; } public function onEndAtomic( IDatabase $db, $fname ): array { if ( !$this->trxLevel() || !$this->trxAtomicLevels ) { throw new DBUnexpectedError( $db, "No atomic section is open (got $fname)" ); } // Check if the current section matches $fname $pos = count( $this->trxAtomicLevels ) - 1; [ $savedFname, $sectionId, $savepointId ] = $this->trxAtomicLevels[$pos]; $this->logger->debug( "endAtomic: leaving level $pos ($fname)", [ 'db_log_category' => 'trx' ] ); if ( $savedFname !== $fname ) { throw new DBUnexpectedError( $db, "Invalid atomic section ended (got $fname but expected $savedFname)" ); } return [ $savepointId, $sectionId ]; } public function getPositionFromSectionId( ?AtomicSectionIdentifier $sectionId = null ): ?int { if ( $sectionId !== null ) { // Find the (last) section with the given $sectionId $pos = -1; foreach ( $this->trxAtomicLevels as $i => [ , $asId, ] ) { if ( $asId === $sectionId ) { $pos = $i; } } } else { $pos = null; } return $pos; } public function cancelAtomic( $pos ) { $excisedIds = []; $excisedFnames = []; $newTopSection = $this->currentAtomicSectionId(); if ( $pos !== null ) { // Remove all descendant sections and re-index the array $len = count( $this->trxAtomicLevels ); for ( $i = $pos + 1; $i < $len; ++$i ) { $excisedFnames[] = $this->trxAtomicLevels[$i][0]; $excisedIds[] = $this->trxAtomicLevels[$i][1]; } $this->trxAtomicLevels = array_slice( $this->trxAtomicLevels, 0, $pos + 1 ); $newTopSection = $this->currentAtomicSectionId(); } // Check if the current section matches $fname $pos = count( $this->trxAtomicLevels ) - 1; [ $savedFname, $savedSectionId, $savepointId ] = $this->trxAtomicLevels[$pos]; if ( $excisedFnames ) { $this->logger->debug( "cancelAtomic: canceling level $pos ($savedFname) " . "and descendants " . implode( ', ', $excisedFnames ), [ 'db_log_category' => 'trx' ] ); } else { $this->logger->debug( "cancelAtomic: canceling level $pos ($savedFname)", [ 'db_log_category' => 'trx' ] ); } return [ $savedFname, $excisedIds, $newTopSection, $savedSectionId, $savepointId ]; } /** * @return bool Whether no levels remain and transaction was started by a popped level */ public function popAtomicLevel() { array_pop( $this->trxAtomicLevels ); return !$this->trxAtomicLevels && $this->trxAutomaticAtomic; } public function setAutomaticAtomic( $value ) { $this->trxAutomaticAtomic = $value; } public function turnOnAutomatic() { $this->trxAutomatic = true; } public function nextSavePointId( IDatabase $db, $fname ) { $savepointId = self::SAVEPOINT_PREFIX . ++$this->trxAtomicCounter; if ( strlen( $savepointId ) > 30 ) { // 30 == Oracle's identifier length limit (pre 12c) // With a 22 character prefix, that puts the highest number at 99999999. throw new DBUnexpectedError( $db, 'There have been an excessively large number of atomic sections in a transaction' . " started by $this->trxFname (at $fname)" ); } return $savepointId; } public function writesPending() { return $this->trxLevel() && $this->trxWriteCallers; } public function onDestruct() { if ( $this->trxLevel() && $this->trxWriteCallers ) { trigger_error( "Uncommitted DB writes (transaction from {$this->trxFname})" ); } } public function transactionWritingIn( $serverName, $domainId, float $startTime ) { if ( !$this->trxWriteCallers ) { $this->profiler->transactionWritingIn( $serverName, $domainId, (string)$this->trxId, $startTime ); } } public function transactionWritingOut( IDatabase $db, $oldId ) { if ( $this->trxWriteCallers ) { $this->profiler->transactionWritingOut( $db->getServerName(), $db->getDomainID(), $oldId, $this->pendingWriteQueryDuration( IDatabase::ESTIMATE_TOTAL ), $this->trxWriteAffectedRows ); } } public function recordQueryCompletion( $sql, $startTime, $isPermWrite, $rowCount, $serverName ) { $this->profiler->recordQueryCompletion( $sql, $startTime, $isPermWrite, $rowCount, (string)$this->trxId, $serverName ); } public function onTransactionResolution( IDatabase $db, callable $callback, $fname ) { if ( !$this->trxLevel() ) { throw new DBUnexpectedError( $db, "No transaction is active" ); } $this->trxEndCallbacks[] = [ $callback, $fname, $this->currentAtomicSectionId() ]; } public function addPostCommitOrIdleCallback( callable $callback, $fname ) { $this->trxPostCommitOrIdleCallbacks[] = [ $callback, $fname, $this->currentAtomicSectionId() ]; } final public function addPreCommitOrIdleCallback( callable $callback, $fname ) { $this->trxPreCommitOrIdleCallbacks[] = [ $callback, $fname, $this->currentAtomicSectionId() ]; } public function setTransactionListener( $name, ?callable $callback = null ) { if ( $callback ) { $this->trxRecurringCallbacks[$name] = $callback; } else { unset( $this->trxRecurringCallbacks[$name] ); } } /** * Whether to disable running of post-COMMIT/ROLLBACK callbacks * @param bool $suppress */ public function setTrxEndCallbackSuppression( bool $suppress ) { $this->trxEndCallbacksSuppressed = $suppress; } /** * Hoist callback ownership for callbacks in a section to a parent section. * All callbacks should have an owner that is present in trxAtomicLevels. * @param AtomicSectionIdentifier $old * @param AtomicSectionIdentifier $new */ public function reassignCallbacksForSection( AtomicSectionIdentifier $old, AtomicSectionIdentifier $new ) { foreach ( $this->trxPreCommitOrIdleCallbacks as $key => $info ) { if ( $info[2] === $old ) { $this->trxPreCommitOrIdleCallbacks[$key][2] = $new; } } foreach ( $this->trxPostCommitOrIdleCallbacks as $key => $info ) { if ( $info[2] === $old ) { $this->trxPostCommitOrIdleCallbacks[$key][2] = $new; } } foreach ( $this->trxEndCallbacks as $key => $info ) { if ( $info[2] === $old ) { $this->trxEndCallbacks[$key][2] = $new; } } foreach ( $this->trxSectionCancelCallbacks as $key => $info ) { if ( $info[2] === $old ) { $this->trxSectionCancelCallbacks[$key][2] = $new; } } } /** * Update callbacks that were owned by cancelled atomic sections. * * Callbacks for "on commit" should never be run if they're owned by a * section that won't be committed. * * Callbacks for "on resolution" need to reflect that the section was * rolled back, even if the transaction as a whole commits successfully. * * Callbacks for "on section cancel" should already have been consumed, * but errors during the cancellation itself can prevent that while still * destroying the section. Hoist any such callbacks to the new top section, * which we assume will itself have to be cancelled or rolled back to * resolve the error. * * @param AtomicSectionIdentifier[] $excisedSectionsId Cancelled section IDs * @param AtomicSectionIdentifier|null $newSectionId New top section ID * @throws UnexpectedValueException */ public function modifyCallbacksForCancel( array $excisedSectionsId, ?AtomicSectionIdentifier $newSectionId = null ) { // Cancel the "on commit" callbacks owned by this savepoint $this->trxPostCommitOrIdleCallbacks = array_filter( $this->trxPostCommitOrIdleCallbacks, static function ( $entry ) use ( $excisedSectionsId ) { return !in_array( $entry[2], $excisedSectionsId, true ); } ); $this->trxPreCommitOrIdleCallbacks = array_filter( $this->trxPreCommitOrIdleCallbacks, static function ( $entry ) use ( $excisedSectionsId ) { return !in_array( $entry[2], $excisedSectionsId, true ); } ); // Make "on resolution" callbacks owned by this savepoint to perceive a rollback foreach ( $this->trxEndCallbacks as $key => $entry ) { if ( in_array( $entry[2], $excisedSectionsId, true ) ) { $callback = $entry[0]; $this->trxEndCallbacks[$key][0] = static function ( $t, $db ) use ( $callback ) { return $callback( IDatabase::TRIGGER_ROLLBACK, $db ); }; // This "on resolution" callback no longer belongs to a section. $this->trxEndCallbacks[$key][2] = null; } } // Hoist callback ownership for section cancel callbacks to the new top section foreach ( $this->trxSectionCancelCallbacks as $key => $entry ) { if ( in_array( $entry[2], $excisedSectionsId, true ) ) { $this->trxSectionCancelCallbacks[$key][2] = $newSectionId; } } } public function consumeEndCallbacks( $trigger ): array { $callbackEntries = array_merge( $this->trxPostCommitOrIdleCallbacks, $this->trxEndCallbacks, ( $trigger === IDatabase::TRIGGER_ROLLBACK ) ? $this->trxSectionCancelCallbacks : [] // just consume them ); $this->trxPostCommitOrIdleCallbacks = []; // consumed (and recursion guard) $this->trxEndCallbacks = []; // consumed (recursion guard) $this->trxSectionCancelCallbacks = []; // consumed (recursion guard) return $callbackEntries; } /** * Consume and run any relevant "on atomic section cancel" callbacks for the active transaction * * @param IDatabase $db * @param int $trigger IDatabase::TRIGGER_* constant * @param AtomicSectionIdentifier[] $sectionIds IDs of the sections that where just cancelled * @throws Throwable Any exception thrown by a callback */ public function runOnAtomicSectionCancelCallbacks( IDatabase $db, int $trigger, array $sectionIds ) { // Drain the queue of matching "atomic section cancel" callbacks until there are none $unrelatedCallbackEntries = []; do { $callbackEntries = $this->trxSectionCancelCallbacks; $this->trxSectionCancelCallbacks = []; // consumed (recursion guard) foreach ( $callbackEntries as $entry ) { if ( in_array( $entry[2], $sectionIds, true ) ) { try { $entry[0]( $trigger, $db ); } catch ( Throwable $trxError ) { $this->setTransactionError( $trxError ); throw $trxError; } } else { $unrelatedCallbackEntries[] = $entry; } } // @phan-suppress-next-line PhanImpossibleConditionInLoop } while ( $this->trxSectionCancelCallbacks ); $this->trxSectionCancelCallbacks = $unrelatedCallbackEntries; } /** * Consume and run any "on transaction pre-commit" callbacks * * @param IDatabase $db * @return int Number of callbacks attempted * @throws Throwable Any exception thrown by a callback */ public function runOnTransactionPreCommitCallbacks( IDatabase $db ): int { $count = 0; // Drain the queues of transaction "precommit" callbacks until it is empty do { $callbackEntries = $this->trxPreCommitOrIdleCallbacks; $this->trxPreCommitOrIdleCallbacks = []; // consumed (and recursion guard) $count += count( $callbackEntries ); foreach ( $callbackEntries as $entry ) { try { $entry[0]( $db ); } catch ( Throwable $trxError ) { $this->setTransactionError( $trxError ); throw $trxError; } } // @phan-suppress-next-line PhanImpossibleConditionInLoop } while ( $this->trxPreCommitOrIdleCallbacks ); return $count; } public function clearPreEndCallbacks() { $this->trxPostCommitOrIdleCallbacks = []; $this->trxPreCommitOrIdleCallbacks = []; } public function clearEndCallbacks() { $this->trxEndCallbacks = []; // don't copy $this->trxSectionCancelCallbacks = []; // don't copy } public function writesOrCallbacksPending(): bool { return $this->trxLevel() && ( $this->trxWriteCallers || $this->trxPostCommitOrIdleCallbacks || $this->trxPreCommitOrIdleCallbacks || $this->trxEndCallbacks || $this->trxSectionCancelCallbacks ); } /** * List the methods that have write queries or callbacks for the current transaction * * @return string[] */ public function pendingWriteAndCallbackCallers(): array { $fnames = $this->pendingWriteCallers(); foreach ( [ $this->trxPostCommitOrIdleCallbacks, $this->trxPreCommitOrIdleCallbacks, $this->trxEndCallbacks, $this->trxSectionCancelCallbacks ] as $callbacks ) { foreach ( $callbacks as $callback ) { $fnames[] = $callback[1]; } } return $fnames; } /** * List the methods that have precommit callbacks for the current transaction * * @return string[] */ public function pendingPreCommitCallbackCallers(): array { $fnames = $this->pendingWriteCallers(); foreach ( $this->trxPreCommitOrIdleCallbacks as $callback ) { $fnames[] = $callback[1]; } return $fnames; } public function isEndCallbacksSuppressed(): bool { return $this->trxEndCallbacksSuppressed; } public function getRecurringCallbacks() { return $this->trxRecurringCallbacks; } public function countPostCommitOrIdleCallbacks() { return count( $this->trxPostCommitOrIdleCallbacks ); } /** * @param string $mode One of IDatabase::TRANSACTION_* values * @param string $fname method name * @param float $rtt Trivial query round-trip-delay */ public function onBeginInCriticalSection( $mode, $fname, $rtt ) { $this->trxId = new TransactionIdentifier(); $this->setTrxStatusToOk(); $this->resetTrxAtomicLevels(); $this->trxWriteCallers = []; $this->trxWriteDuration = 0.0; $this->trxWriteQueryCount = 0; $this->trxWriteAffectedRows = 0; $this->trxWriteAdjDuration = 0.0; $this->trxWriteAdjQueryCount = 0; // T147697: make explicitTrxActive() return true until begin() finishes. This way, // no caller triggered by getApproximateLagStatus() will think its OK to muck around // with the transaction just because startAtomic() has not yet finished updating the // tracking fields (e.g. trxAtomicLevels). $this->trxAutomatic = ( $mode === IDatabase::TRANSACTION_INTERNAL ); $this->trxAutomaticAtomic = false; $this->trxFname = $fname; $this->trxTimestamp = microtime( true ); $this->trxRoundTripDelay = $rtt; } public function onRollbackInCriticalSection( IDatabase $db ) { $oldTrxId = $this->consumeTrxId(); $this->setTrxStatusToNone(); $this->resetTrxAtomicLevels(); $this->clearPreEndCallbacks(); $this->transactionWritingOut( $db, (string)$oldTrxId ); } public function onCommitInCriticalSection( IDatabase $db ) { $lastWriteTime = null; $oldTrxId = $this->consumeTrxId(); $this->setTrxStatusToNone(); if ( $this->trxWriteCallers ) { $lastWriteTime = microtime( true ); $this->transactionWritingOut( $db, (string)$oldTrxId ); } return $lastWriteTime; } public function onSessionLoss( IDatabase $db ) { $oldTrxId = $this->consumeTrxId(); $this->clearPreEndCallbacks(); $this->transactionWritingOut( $db, (string)$oldTrxId ); } public function onEndAtomicInCriticalSection( $sectionId ) { // Hoist callback ownership for callbacks in the section that just ended; // all callbacks should have an owner that is present in trxAtomicLevels. $currentSectionId = $this->currentAtomicSectionId(); if ( $currentSectionId ) { $this->reassignCallbacksForSection( $sectionId, $currentSectionId ); } } public function onFlushSnapshot( IDatabase $db, $fname, $flush, $trxRoundId ) { if ( $this->explicitTrxActive() ) { // Committing this transaction would break callers that assume it is still open throw new DBUnexpectedError( $db, "$fname: Cannot flush snapshot; " . "explicit transaction '{$this->trxFname}' is still open" ); } elseif ( $this->writesOrCallbacksPending() ) { // This only flushes transactions to clear snapshots, not to write data $fnames = implode( ', ', $this->pendingWriteAndCallbackCallers() ); throw new DBUnexpectedError( $db, "$fname: Cannot flush snapshot; " . "writes from transaction {$this->trxFname} are still pending ($fnames)" ); } elseif ( $this->trxLevel() && $trxRoundId && $flush !== IDatabase::FLUSHING_INTERNAL && $flush !== IDatabase::FLUSHING_ALL_PEERS ) { $this->logger->warning( "$fname: Expected mass snapshot flush of all peer transactions " . "in the explicit transactions round '{$trxRoundId}'", [ 'exception' => new RuntimeException(), 'db_log_category' => 'trx' ] ); } } public function onGetScopedLockAndFlush( IDatabase $db, $fname ) { if ( $this->writesOrCallbacksPending() ) { // This only flushes transactions to clear snapshots, not to write data $fnames = implode( ', ', $this->pendingWriteAndCallbackCallers() ); throw new DBUnexpectedError( $db, "$fname: Cannot flush pre-lock snapshot; " . "writes from transaction {$this->trxFname} are still pending ($fnames)" ); } } } PK ! Z�"/�* �* " rdbms/database/DatabaseFactory.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\Rdbms; use InvalidArgumentException; use Psr\Log\NullLogger; use Throwable; use Wikimedia\ObjectCache\HashBagOStuff; use Wikimedia\RequestTimeout\CriticalSectionProvider; /** * Constructs Database objects * * @since 1.39 * @ingroup Database */ class DatabaseFactory { /** @var string Agent name for query profiling */ private $agent; /** @var callable Deprecation logger */ private $deprecationLogger; /** * @var callable|null An optional callback that returns a ScopedCallback instance, * meant to profile the actual query execution in {@see Database::doQuery} */ private $profiler; /** @var CriticalSectionProvider|null */ private $csProvider; /** @var bool Whether this PHP instance is for a CLI script */ private $cliMode; /** @var bool Log SQL queries in debug toolbar if set to true */ private $debugSql; public function __construct( array $params = [] ) { $this->agent = $params['agent'] ?? ''; $this->deprecationLogger = $params['deprecationLogger'] ?? static function ( $msg ) { trigger_error( $msg, E_USER_DEPRECATED ); }; $this->csProvider = $params['criticalSectionProvider'] ?? null; $this->profiler = $params['profiler'] ?? null; $this->cliMode = $params['cliMode'] ?? ( PHP_SAPI === 'cli' || PHP_SAPI === 'phpdbg' ); $this->debugSql = $params['debugSql'] ?? false; } /** * Construct a Database subclass instance given a database type and parameters * * This also connects to the database immediately upon object construction * * @param string $type A possible DB type (sqlite, mysql, postgres,...) * @param array $params Parameter map with keys: * - host : The hostname of the DB server * - user : The name of the database user the client operates under * - password : The password for the database user * - dbname : The name of the database to use where queries do not specify one. * The database must exist or an error might be thrown. Setting this to the empty string * will avoid any such errors and make the handle have no implicit database scope. This is * useful for queries like SHOW STATUS, CREATE DATABASE, or DROP DATABASE. Note that a * "database" in Postgres is rougly equivalent to an entire MySQL server. This the domain * in which user names and such are defined, e.g. users are database-specific in Postgres. * - schema : The database schema to use (if supported). A "schema" in Postgres is roughly * equivalent to a "database" in MySQL. Note that MySQL and SQLite do not use schemas. * - tablePrefix : Optional table prefix that is implicitly added on to all table names * recognized in queries. This can be used in place of schemas for handle site farms. * - flags : Optional bit field of DBO_* constants that define connection, protocol, * buffering, and transaction behavior. It is STRONGLY adviced to leave the DBO_DEFAULT * flag in place UNLESS this this database simply acts as a key/value store. * - ssl : Whether to use TLS connections. * - strictWarnings: Whether to check for warnings and throw an exception if an unacceptable * warning is found. * - driver: Optional name of a specific DB client driver. For MySQL, there is only the * 'mysqli' driver; the old one 'mysql' has been removed. * - variables: Optional map of session variables to set after connecting. This can be * used to adjust lock timeouts or encoding modes and the like. * - topologyRole: Optional IDatabase::ROLE_* constant for the server. * - lbInfo: Optional map of field/values for the managing load balancer instance. * The "master" and "replica" fields are used to flag the replication role of this * database server and whether methods like getLag() should actually issue queries. * - connectTimeout: Optional timeout, in seconds, for connection attempts. * - receiveTimeout: Optional timeout, in seconds, for receiving query results. * - logger: Optional PSR-3 logger interface instance. * - profiler : Optional callback that takes a section name argument and returns * a ScopedCallback instance that ends the profile section in its destructor. * These will be called in query(), using a simplified version of the SQL that * also includes the agent as a SQL comment. * - trxProfiler: Optional TransactionProfiler instance. * - errorLogger: Optional callback that takes an Exception and logs it. * - deprecationLogger: Optional callback that takes a string and logs it. * - cliMode: Whether to consider the execution context that of a CLI script. * - agent: Optional name used to identify the end-user in query profiling/logging. * - serverName: Optional human-readable server name * - srvCache: Optional BagOStuff instance to an APC-style cache. * - nonNativeInsertSelectBatchSize: Optional batch size for non-native INSERT SELECT. * @param int $connect One of the class constants (NEW_CONNECTED, NEW_UNCONNECTED) [optional] * @return Database|null If the database driver or extension cannot be found * @throws InvalidArgumentException If the database driver or extension cannot be found */ public function create( $type, $params = [], $connect = Database::NEW_CONNECTED ) { $class = $this->getClass( $type, $params['driver'] ?? null ); if ( class_exists( $class ) && is_subclass_of( $class, IDatabase::class ) ) { $params += [ // Default configuration 'host' => null, 'user' => null, 'password' => null, 'dbname' => null, 'schema' => null, 'tablePrefix' => '', 'variables' => [], 'lbInfo' => [], 'serverName' => null, 'topologyRole' => null, // Objects and callbacks 'srvCache' => $params['srvCache'] ?? new HashBagOStuff(), 'trxProfiler' => $params['trxProfiler'] ?? new TransactionProfiler(), 'logger' => $params['logger'] ?? new NullLogger(), 'errorLogger' => $params['errorLogger'] ?? static function ( Throwable $e ) { trigger_error( get_class( $e ) . ': ' . $e->getMessage(), E_USER_WARNING ); }, ]; $params['flags'] ??= 0; if ( $this->debugSql ) { $params['flags'] |= DBO_DEBUG; } $overrides = [ 'flags' => $this->initConnectionFlags( $params['flags'] ), 'cliMode' => $this->cliMode, 'agent' => $this->agent, 'profiler' => $this->profiler, 'deprecationLogger' => $this->deprecationLogger, 'criticalSectionProvider' => $this->csProvider, ]; /** @var Database $conn */ $conn = new $class( array_merge( $params, $overrides ) ); if ( $connect === Database::NEW_CONNECTED ) { $conn->initConnection(); } } else { $conn = null; } return $conn; } /** * @param string $dbType A possible DB type (sqlite, mysql, postgres,...) * @param string|null $driver Optional name of a specific DB client driver * @return array Map of (Database::ATTR_* constant => value) for all such constants * @throws DBUnexpectedError */ public function attributesFromType( $dbType, $driver = null ) { static $defaults = [ Database::ATTR_DB_IS_FILE => false, Database::ATTR_DB_LEVEL_LOCKING => false, Database::ATTR_SCHEMAS_AS_TABLE_GROUPS => false ]; $class = $this->getClass( $dbType, $driver ); if ( class_exists( $class ) ) { return call_user_func( [ $class, 'getAttributes' ] ) + $defaults; } else { throw new DBUnexpectedError( null, "$dbType is not a supported database type." ); } } /** * @param string $dbType A possible DB type (sqlite, mysql, postgres,...) * @param string|null $driver Optional name of a specific DB client driver * @return string Database subclass name to use * @throws InvalidArgumentException */ protected function getClass( $dbType, $driver = null ) { // For database types with built-in support, the below maps type to IDatabase // implementations. For types with multiple driver implementations (PHP extensions), // an array can be used, keyed by extension name. In case of an array, the // optional 'driver' parameter can be used to force a specific driver. Otherwise, // we auto-detect the first available driver. For types without built-in support, // a class named "Database<Type>" is used, eg. DatabaseFoo for type 'foo'. static $builtinTypes = [ 'mysql' => [ 'mysqli' => DatabaseMySQL::class ], 'sqlite' => DatabaseSqlite::class, 'postgres' => DatabasePostgres::class, ]; $dbType = strtolower( $dbType ); if ( !isset( $builtinTypes[$dbType] ) ) { // Not a built in type, assume standard naming scheme return 'Database' . ucfirst( $dbType ); } $class = false; $possibleDrivers = $builtinTypes[$dbType]; if ( is_string( $possibleDrivers ) ) { $class = $possibleDrivers; } elseif ( (string)$driver !== '' ) { if ( !isset( $possibleDrivers[$driver] ) ) { throw new InvalidArgumentException( __METHOD__ . " type '$dbType' does not support driver '{$driver}'" ); } $class = $possibleDrivers[$driver]; } else { foreach ( $possibleDrivers as $posDriver => $possibleClass ) { if ( extension_loaded( $posDriver ) ) { $class = $possibleClass; break; } } } if ( $class === false ) { throw new InvalidArgumentException( __METHOD__ . " no viable database extension found for type '$dbType'" ); } return $class; } /** * @see IDatabase::DBO_DEFAULT * @param int $flags Bit field of IDatabase::DBO_* constants from configuration * @return int Bit field of IDatabase::DBO_* constants to use with Database::factory() */ private function initConnectionFlags( int $flags ) { if ( self::fieldHasBit( $flags, IDatabase::DBO_DEFAULT ) ) { // Server is configured to participate in transaction rounds in non-CLI mode if ( $this->cliMode ) { $flags &= ~IDatabase::DBO_TRX; } else { $flags |= IDatabase::DBO_TRX; } } return $flags; } /** * @param int $flags A bitfield of flags * @param int $bit Bit flag constant * @return bool Whether the bit field has the specified bit flag set */ private function fieldHasBit( int $flags, int $bit ) { return ( ( $flags & $bit ) === $bit ); } } PK ! �DeB B 7 rdbms/database/replication/MysqlReplicationReporter.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\Rdbms\Replication; use InvalidArgumentException; use RuntimeException; use stdClass; use Wikimedia\Rdbms\DBPrimaryPos; use Wikimedia\Rdbms\DBQueryError; use Wikimedia\Rdbms\IDatabase; use Wikimedia\Rdbms\MySQLPrimaryPos; use Wikimedia\Rdbms\Platform\ISQLPlatform; use Wikimedia\Rdbms\Query; /** * @internal * @ingroup Database * @since 1.40 */ class MysqlReplicationReporter extends ReplicationReporter { /** @var MySQLPrimaryPos */ protected $lastKnownReplicaPos; /** @var string Method to detect replica DB lag */ protected $lagDetectionMethod; /** @var array Method to detect replica DB lag */ protected $lagDetectionOptions = []; /** @var bool bool Whether to use GTID methods */ protected $useGTIDs = false; /** @var stdClass|null */ private $replicationInfoRow; // Cache getServerId() for 24 hours private const SERVER_ID_CACHE_TTL = 86400; /** @var float Warn if lag estimates are made for transactions older than this many seconds */ private const LAG_STALE_WARN_THRESHOLD = 0.100; public function __construct( $topologyRole, $logger, $srvCache, $lagDetectionMethod, $lagDetectionOptions, $useGTIDs ) { parent::__construct( $topologyRole, $logger, $srvCache ); $this->lagDetectionMethod = $lagDetectionMethod; $this->lagDetectionOptions = $lagDetectionOptions; $this->useGTIDs = $useGTIDs; } protected function doGetLag( IDatabase $conn ) { if ( $this->lagDetectionMethod === 'pt-heartbeat' ) { return $this->getLagFromPtHeartbeat( $conn ); } else { return $this->getLagFromSlaveStatus( $conn ); } } /** * @param IDatabase $conn To make queries * @return int|false Second of lag */ protected function getLagFromSlaveStatus( IDatabase $conn ) { $query = new Query( 'SHOW SLAVE STATUS', ISQLPlatform::QUERY_SILENCE_ERRORS | ISQLPlatform::QUERY_IGNORE_DBO_TRX | ISQLPlatform::QUERY_CHANGE_NONE, 'SHOW', null, 'SHOW SLAVE STATUS' ); $res = $conn->query( $query, __METHOD__ ); $row = $res ? $res->fetchObject() : false; // If the server is not replicating, there will be no row if ( $row && strval( $row->Seconds_Behind_Master ) !== '' ) { // https://mariadb.com/kb/en/delayed-replication/ // https://dev.mysql.com/doc/refman/5.6/en/replication-delayed.html return intval( $row->Seconds_Behind_Master + ( $row->SQL_Remaining_Delay ?? 0 ) ); } return false; } /** * @param IDatabase $conn To make queries * @return float|false Seconds of lag */ protected function getLagFromPtHeartbeat( IDatabase $conn ) { $currentTrxInfo = $this->getRecordedTransactionLagStatus( $conn ); if ( $currentTrxInfo ) { // There is an active transaction and the initial lag was already queried $staleness = microtime( true ) - $currentTrxInfo['since']; if ( $staleness > self::LAG_STALE_WARN_THRESHOLD ) { // Avoid returning higher and higher lag value due to snapshot age // given that the isolation level will typically be REPEATABLE-READ // but UTC_TIMESTAMP() is not affected by point-in-time snapshots $this->logger->warning( "Using cached lag value for {db_server} due to active transaction", $this->getLogContext( $conn, [ 'method' => __METHOD__, 'age' => $staleness, 'exception' => new RuntimeException() ] ) ); } return $currentTrxInfo['lag']; } $ago = $this->fetchSecondsSinceHeartbeat( $conn ); if ( $ago !== null ) { return max( $ago, 0.0 ); } $this->logger->error( "Unable to find pt-heartbeat row for {db_server}", $this->getLogContext( $conn, [ 'method' => __METHOD__ ] ) ); return false; } /** * @param IDatabase $conn To make queries * @return float|null Elapsed seconds since the newest beat or null if none was found * @see https://www.percona.com/doc/percona-toolkit/2.1/pt-heartbeat.html */ protected function fetchSecondsSinceHeartbeat( IDatabase $conn ) { // Some setups might have pt-heartbeat running on each replica server. // Exclude the row for events originating on this DB server. Assume that // there is only one active replication channel and that any other row // getting updates must be the row for the primary DB server. $where = $conn->makeList( $this->lagDetectionOptions['conds'] ?? [ 'server_id != @@server_id' ], ISQLPlatform::LIST_AND ); // User mysql server time so that query time and trip time are not counted. // Use ORDER BY for channel based queries since that field might not be UNIQUE. $query = new Query( "SELECT TIMESTAMPDIFF(MICROSECOND,ts,UTC_TIMESTAMP(6)) AS us_ago " . "FROM heartbeat.heartbeat WHERE $where ORDER BY ts DESC LIMIT 1", ISQLPlatform::QUERY_SILENCE_ERRORS | ISQLPlatform::QUERY_IGNORE_DBO_TRX | ISQLPlatform::QUERY_CHANGE_NONE, 'SELECT', null, "SELECT TIMESTAMPDIFF(MICROSECOND,ts,UTC_TIMESTAMP(6)) AS us_ago " . "FROM heartbeat.heartbeat WHERE ? ORDER BY ts DESC LIMIT 1", ); $res = $conn->query( $query, __METHOD__ ); $row = $res ? $res->fetchObject() : false; return $row ? ( $row->us_ago / 1e6 ) : null; } public function getApproximateLagStatus( IDatabase $conn ) { if ( $this->lagDetectionMethod === 'pt-heartbeat' ) { // Disable caching since this is fast enough and we don't want // to be *too* pessimistic by having both the cache TTL and the // pt-heartbeat interval count as lag in getSessionLagStatus() return parent::getApproximateLagStatus( $conn ); } $key = $this->srvCache->makeGlobalKey( 'mysql-lag', $conn->getServerName() ); $approxLag = $this->srvCache->get( $key ); if ( !$approxLag ) { $approxLag = parent::getApproximateLagStatus( $conn ); $this->srvCache->set( $key, $approxLag, 1 ); } return $approxLag; } /** * @param IDatabase $conn To make queries * @param string $fname * @return stdClass Process cached row */ public function getReplicationSafetyInfo( IDatabase $conn, $fname ) { if ( $this->replicationInfoRow === null ) { $this->replicationInfoRow = $conn->selectRow( [], [ 'innodb_autoinc_lock_mode' => '@@innodb_autoinc_lock_mode', 'binlog_format' => '@@binlog_format', ], [], $fname ); } return $this->replicationInfoRow; } /** * @return bool Whether GTID support is used (mockable for testing) */ protected function useGTIDs() { return $this->useGTIDs; } public function primaryPosWait( IDatabase $conn, DBPrimaryPos $pos, $timeout ) { if ( !( $pos instanceof MySQLPrimaryPos ) ) { throw new InvalidArgumentException( "Position not an instance of MySQLPrimaryPos" ); } if ( $this->topologyRole === IDatabase::ROLE_STATIC_CLONE ) { $this->logger->debug( "Bypassed replication wait; database has a static dataset", $this->getLogContext( $conn, [ 'method' => __METHOD__, 'raw_pos' => $pos ] ) ); return 0; // this is a copy of a read-only dataset with no primary DB } elseif ( $this->lastKnownReplicaPos && $this->lastKnownReplicaPos->hasReached( $pos ) ) { $this->logger->debug( "Bypassed replication wait; replication known to have reached {raw_pos}", $this->getLogContext( $conn, [ 'method' => __METHOD__, 'raw_pos' => $pos ] ) ); return 0; // already reached this point for sure } // Call doQuery() directly, to avoid opening a transaction if DBO_TRX is set if ( $pos->getGTIDs() ) { // Get the GTIDs from this replica server too see the domains (channels) $refPos = $this->getReplicaPos( $conn ); if ( !$refPos ) { $this->logger->error( "Could not get replication position on replica DB to compare to {raw_pos}", $this->getLogContext( $conn, [ 'method' => __METHOD__, 'raw_pos' => $pos ] ) ); return -1; // this is the primary DB itself? } // GTIDs with domains (channels) that are active and are present on the replica $gtidsWait = $pos::getRelevantActiveGTIDs( $pos, $refPos ); if ( !$gtidsWait ) { $this->logger->error( "No active GTIDs in {raw_pos} share a domain with those in {current_pos}", $this->getLogContext( $conn, [ 'method' => __METHOD__, 'raw_pos' => $pos, 'current_pos' => $refPos ] ) ); return -1; // $pos is from the wrong cluster? } // Wait on the GTID set $gtidArg = $conn->addQuotes( implode( ',', $gtidsWait ) ); if ( strpos( $gtidArg, ':' ) !== false ) { // MySQL GTIDs, e.g "source_id:transaction_id" $query = new Query( "SELECT WAIT_FOR_EXECUTED_GTID_SET($gtidArg, $timeout)", ISQLPlatform::QUERY_IGNORE_DBO_TRX | ISQLPlatform::QUERY_CHANGE_NONE, 'SELECT', null, "SELECT WAIT_FOR_EXECUTED_GTID_SET(?, ?)" ); } else { // MariaDB GTIDs, e.g."domain:server:sequence" $query = new Query( "SELECT MASTER_GTID_WAIT($gtidArg, $timeout)", ISQLPlatform::QUERY_IGNORE_DBO_TRX | ISQLPlatform::QUERY_CHANGE_NONE, 'SELECT', null, "SELECT MASTER_GTID_WAIT(?, ?)" ); } $waitPos = implode( ',', $gtidsWait ); } else { // Wait on the binlog coordinates $encFile = $conn->addQuotes( $pos->getLogFile() ); // @phan-suppress-next-line PhanTypeArraySuspiciousNullable $encPos = intval( $pos->getLogPosition()[$pos::CORD_EVENT] ); $query = new Query( "SELECT MASTER_POS_WAIT($encFile, $encPos, $timeout)", ISQLPlatform::QUERY_IGNORE_DBO_TRX | ISQLPlatform::QUERY_CHANGE_NONE, 'SELECT', null, "SELECT MASTER_POS_WAIT(?, ?, ?)" ); $waitPos = $pos->__toString(); } $start = microtime( true ); $res = $conn->query( $query, __METHOD__ ); $row = $res->fetchRow(); $seconds = max( microtime( true ) - $start, 0 ); // Result can be NULL (error), -1 (timeout), or 0+ per the MySQL manual $status = ( $row[0] !== null ) ? intval( $row[0] ) : null; if ( $status === null ) { $this->logger->error( "An error occurred while waiting for replication to reach {wait_pos}", $this->getLogContext( $conn, [ 'raw_pos' => $pos, 'wait_pos' => $waitPos, 'sql' => $query->getSQL(), 'seconds_waited' => $seconds, 'exception' => new RuntimeException() ] ) ); } elseif ( $status < 0 ) { $this->logger->info( "Timed out waiting for replication to reach {wait_pos}", $this->getLogContext( $conn, [ 'raw_pos' => $pos, 'wait_pos' => $waitPos, 'timeout' => $timeout, 'sql' => $query->getSQL(), 'seconds_waited' => $seconds, ] ) ); } elseif ( $status >= 0 ) { $this->logger->debug( "Replication has reached {wait_pos}", $this->getLogContext( $conn, [ 'raw_pos' => $pos, 'wait_pos' => $waitPos, 'seconds_waited' => $seconds, ] ) ); // Remember that this position was reached to save queries next time $this->lastKnownReplicaPos = $pos; } return $status; } /** * Get the position of the primary DB from SHOW SLAVE STATUS * * @param IDatabase $conn To make queries * @return MySQLPrimaryPos|false */ public function getReplicaPos( IDatabase $conn ) { $now = microtime( true ); // as-of-time *before* fetching GTID variables if ( $this->useGTIDs() ) { // Try to use GTIDs, fallbacking to binlog positions if not possible $data = $this->getServerGTIDs( $conn, __METHOD__ ); // Use gtid_slave_pos for MariaDB and gtid_executed for MySQL foreach ( [ 'gtid_slave_pos', 'gtid_executed' ] as $name ) { if ( isset( $data[$name] ) && strlen( $data[$name] ) ) { return new MySQLPrimaryPos( $data[$name], $now ); } } } $data = $this->getServerRoleStatus( $conn, 'SLAVE', __METHOD__ ); if ( $data && strlen( $data['Relay_Master_Log_File'] ) ) { return new MySQLPrimaryPos( "{$data['Relay_Master_Log_File']}/{$data['Exec_Master_Log_Pos']}", $now ); } return false; } /** * Get the position of the primary DB from SHOW MASTER STATUS * * @param IDatabase $conn To make queries * @return MySQLPrimaryPos|false */ public function getPrimaryPos( IDatabase $conn ) { $now = microtime( true ); // as-of-time *before* fetching GTID variables $pos = false; if ( $this->useGTIDs() ) { // Try to use GTIDs, fallbacking to binlog positions if not possible $data = $this->getServerGTIDs( $conn, __METHOD__ ); // Use gtid_binlog_pos for MariaDB and gtid_executed for MySQL foreach ( [ 'gtid_binlog_pos', 'gtid_executed' ] as $name ) { if ( isset( $data[$name] ) && strlen( $data[$name] ) ) { $pos = new MySQLPrimaryPos( $data[$name], $now ); break; } } // Filter domains that are inactive or not relevant to the session if ( $pos ) { $pos->setActiveOriginServerId( $this->getServerId( $conn ) ); $pos->setActiveOriginServerUUID( $this->getServerUUID( $conn ) ); if ( isset( $data['gtid_domain_id'] ) ) { $pos->setActiveDomain( $data['gtid_domain_id'] ); } } } if ( !$pos ) { $data = $this->getServerRoleStatus( $conn, 'MASTER', __METHOD__ ); if ( $data && strlen( $data['File'] ) ) { $pos = new MySQLPrimaryPos( "{$data['File']}/{$data['Position']}", $now ); } } return $pos; } /** * @param IDatabase $conn To make queries * @return string Value of server_id (32-bit integer, unique to the replication topology) * @throws DBQueryError */ protected function getServerId( IDatabase $conn ) { $fname = __METHOD__; return $this->srvCache->getWithSetCallback( $this->srvCache->makeGlobalKey( 'mysql-server-id', $conn->getServerName() ), self::SERVER_ID_CACHE_TTL, static function () use ( $conn, $fname ) { $query = new Query( "SELECT @@server_id AS id", ISQLPlatform::QUERY_IGNORE_DBO_TRX | ISQLPlatform::QUERY_CHANGE_NONE, 'SELECT', null, "SELECT @@server_id AS id" ); $res = $conn->query( $query, $fname ); return $res->fetchObject()->id; } ); } /** * @param IDatabase $conn To make queries * @return string|null Value of server_uuid (hyphenated 128-bit hex string, globally unique) * @throws DBQueryError */ protected function getServerUUID( IDatabase $conn ) { $fname = __METHOD__; return $this->srvCache->getWithSetCallback( $this->srvCache->makeGlobalKey( 'mysql-server-uuid', $conn->getServerName() ), self::SERVER_ID_CACHE_TTL, static function () use ( $conn, $fname ) { $query = new Query( "SHOW GLOBAL VARIABLES LIKE 'server_uuid'", ISQLPlatform::QUERY_IGNORE_DBO_TRX | ISQLPlatform::QUERY_CHANGE_NONE, 'SHOW', null, "SHOW GLOBAL VARIABLES LIKE 'server_uuid'" ); $res = $conn->query( $query, $fname ); $row = $res->fetchObject(); return $row ? $row->Value : null; } ); } /** * @param IDatabase $conn To make queries * @param string $fname * @return string[] */ protected function getServerGTIDs( IDatabase $conn, $fname ) { $map = []; $flags = ISQLPlatform::QUERY_IGNORE_DBO_TRX | ISQLPlatform::QUERY_CHANGE_NONE; // Get global-only variables like gtid_executed $query = new Query( "SHOW GLOBAL VARIABLES LIKE 'gtid_%'", $flags, 'SHOW', null, "SHOW GLOBAL VARIABLES LIKE 'gtid_%'" ); $res = $conn->query( $query, $fname ); foreach ( $res as $row ) { $map[$row->Variable_name] = $row->Value; } // Get session-specific (e.g. gtid_domain_id since that is were writes will log) $query = new Query( "SHOW SESSION VARIABLES LIKE 'gtid_%'", $flags, 'SHOW', null, "SHOW SESSION VARIABLES LIKE 'gtid_%'" ); $res = $conn->query( $query, $fname ); foreach ( $res as $row ) { $map[$row->Variable_name] = $row->Value; } return $map; } /** * @param IDatabase $conn To make queries * @param string $role One of "MASTER"/"SLAVE" * @param string $fname * @return array<string,mixed>|null Latest available server status row; false on failure */ protected function getServerRoleStatus( IDatabase $conn, $role, $fname ) { $query = new Query( "SHOW $role STATUS", ISQLPlatform::QUERY_SILENCE_ERRORS | ISQLPlatform::QUERY_IGNORE_DBO_TRX | ISQLPlatform::QUERY_CHANGE_NONE, 'SHOW', null, "SHOW $role STATUS" ); $res = $conn->query( $query, $fname ); $row = $res ? $res->fetchRow() : false; return ( $row ?: null ); } } PK ! �� �� � 2 rdbms/database/replication/ReplicationReporter.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\Rdbms\Replication; use Psr\Log\LoggerInterface; use Wikimedia\ObjectCache\BagOStuff; use Wikimedia\Rdbms\DBError; use Wikimedia\Rdbms\DBPrimaryPos; use Wikimedia\Rdbms\IDatabase; /** * @internal * @ingroup Database * @since 1.40 */ class ReplicationReporter { /** @var string Replication topology role of the server; one of the class ROLE_* constants */ protected $topologyRole; /** @var LoggerInterface */ protected $logger; /** @var BagOStuff */ protected $srvCache; /** @var array|null Replication lag estimate at the time of BEGIN for the last transaction */ private $trxReplicaLagStatus = null; public function __construct( $topologyRole, $logger, $srvCache ) { $this->topologyRole = $topologyRole; $this->logger = $logger; $this->srvCache = $srvCache; } public function getTopologyRole() { return $this->topologyRole; } public function getLag( IDatabase $conn ) { if ( $this->topologyRole === IDatabase::ROLE_STREAMING_MASTER ) { return 0; // this is the primary DB } elseif ( $this->topologyRole === IDatabase::ROLE_STATIC_CLONE ) { return 0; // static dataset } return $this->doGetLag( $conn ); } /** * Get the amount of replication lag for this database server * * Callers should avoid using this method while a transaction is active * * @see getLag() * * @param IDatabase $conn To make queries * @return float|int|false Database replication lag in seconds or false on error * @throws DBError */ protected function doGetLag( IDatabase $conn ) { return 0; } /** * Get a replica DB lag estimate for this server at the start of a transaction * * This is a no-op unless the server is known a priori to be a replica DB * * @param IDatabase $conn To make queries * @return array ('lag': seconds or false on error, 'since': UNIX timestamp of estimate) * @since 1.27 in Database, moved to ReplicationReporter in 1.40 */ protected function getApproximateLagStatus( IDatabase $conn ) { if ( $this->topologyRole === IDatabase::ROLE_STREAMING_REPLICA ) { // Avoid exceptions as this is used internally in critical sections try { $lag = $this->getLag( $conn ); } catch ( DBError $e ) { $lag = false; } } else { $lag = 0; } return [ 'lag' => $lag, 'since' => microtime( true ) ]; } public function primaryPosWait( IDatabase $conn, DBPrimaryPos $pos, $timeout ) { // Real waits are implemented in the subclass. return 0; } public function getReplicaPos( IDatabase $conn ) { // Stub return false; } public function getPrimaryPos( IDatabase $conn ) { // Stub return false; } /** * @return array|null Tuple of (reason string, "role") if read-only; null otherwise */ public function getTopologyBasedReadOnlyReason() { if ( $this->topologyRole === IDatabase::ROLE_STREAMING_REPLICA ) { return [ 'Server is configured as a read-only replica database.', 'role' ]; } elseif ( $this->topologyRole === IDatabase::ROLE_STATIC_CLONE ) { return [ 'Server is configured as a read-only static clone database.', 'role' ]; } return null; } public function resetReplicationLagStatus( IDatabase $conn ) { // With REPEATABLE-READ isolation, the first SELECT establishes the read snapshot, // so get the replication lag estimate before any transaction SELECT queries come in. // This way, the lag estimate reflects what will actually be read. Also, if heartbeat // tables are used, this avoids counting snapshot lag as part of replication lag. $this->trxReplicaLagStatus = null; // clear cached value first $this->trxReplicaLagStatus = $this->getApproximateLagStatus( $conn ); } /** * Get the replica DB lag when the current transaction started * * This is useful given that transactions might use point-in-time read snapshots, * in which case the lag estimate should be recorded just before the transaction * establishes the read snapshot (either BEGIN or the first SELECT/write query). * * If snapshots are not used, it is still safe to be pessimistic. * * This returns null if there is no transaction or the lag status was not yet recorded. * * @param IDatabase $conn To make queries * @return array|null ('lag': seconds or false, 'since': UNIX timestamp of BEGIN) or null * @since 1.27 in Database, moved to ReplicationReporter in 1.40 */ final protected function getRecordedTransactionLagStatus( IDatabase $conn ) { return $conn->trxLevel() ? $this->trxReplicaLagStatus : null; } public function getSessionLagStatus( IDatabase $conn ) { return $this->getRecordedTransactionLagStatus( $conn ) ?: $this->getApproximateLagStatus( $conn ); } /** * Create a log context to pass to PSR-3 logger functions. * * @param IDatabase $conn To make queries * @param array $extras Additional data to add to context * @return array */ protected function getLogContext( IDatabase $conn, array $extras = [] ) { return array_merge( [ 'db_server' => $conn->getServerName(), 'db_name' => $conn->getDBname(), // TODO: Add db_user ], $extras ); } } PK ! CζDg g ! rdbms/database/DatabaseSqlite.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\Rdbms; use FSLockManager; use LockManager; use NullLockManager; use PDO; use PDOException; use PDOStatement; use RuntimeException; use Wikimedia\Rdbms\Platform\SqlitePlatform; use Wikimedia\Rdbms\Platform\SQLPlatform; use Wikimedia\Rdbms\Replication\ReplicationReporter; /** * This is the SQLite database abstraction layer. * * See docs/sqlite.txt for development notes about MediaWiki's sqlite schema. * * @ingroup Database */ class DatabaseSqlite extends Database { /** @var string|null Directory for SQLite database files listed under their DB name */ protected $dbDir; /** @var string|null Explicit path for the SQLite database file */ protected $dbPath; /** @var string Transaction mode */ protected $trxMode; /** @var PDO|null */ protected $conn; /** @var LockManager|null (hopefully on the same server as the DB) */ protected $lockMgr; /** @var string|null */ private $version; /** @var array List of shared database already attached to this connection */ private $sessionAttachedDbs = []; /** @var string[] See https://www.sqlite.org/lang_transaction.html */ private const VALID_TRX_MODES = [ '', 'DEFERRED', 'IMMEDIATE', 'EXCLUSIVE' ]; /** @var string[][] */ private const VALID_PRAGMAS = [ // Optimizations or requirements regarding fsync() usage 'synchronous' => [ 'EXTRA', 'FULL', 'NORMAL', 'OFF' ], // Optimizations for TEMPORARY tables 'temp_store' => [ 'FILE', 'MEMORY' ], // Optimizations for disk use and page cache 'mmap_size' => 'integer', // How many DB pages to keep in memory 'cache_size' => 'integer', ]; /** @var SQLPlatform */ protected $platform; /** * Additional params include: * - dbDirectory : directory containing the DB and the lock file directory * - dbFilePath : use this to force the path of the DB file * - trxMode : one of (deferred, immediate, exclusive) * @param array $params */ public function __construct( array $params ) { if ( isset( $params['dbFilePath'] ) ) { $this->dbPath = $params['dbFilePath']; if ( !isset( $params['dbname'] ) || $params['dbname'] === '' ) { $params['dbname'] = self::generateDatabaseName( $this->dbPath ); } } elseif ( isset( $params['dbDirectory'] ) ) { $this->dbDir = $params['dbDirectory']; } parent::__construct( $params ); $this->trxMode = strtoupper( $params['trxMode'] ?? '' ); $this->lockMgr = $this->makeLockManager(); $this->platform = new SqlitePlatform( $this, $this->logger, $this->currentDomain, $this->errorLogger ); $this->replicationReporter = new ReplicationReporter( $params['topologyRole'], $this->logger, $params['srvCache'] ); } public static function getAttributes() { return [ self::ATTR_DB_IS_FILE => true, self::ATTR_DB_LEVEL_LOCKING => true ]; } /** * @param string $filename * @param array $p Options map; supports: * - flags : (same as __construct counterpart) * - trxMode : (same as __construct counterpart) * - dbDirectory : (same as __construct counterpart) * @return DatabaseSqlite * @since 1.25 */ public static function newStandaloneInstance( $filename, array $p = [] ) { $p['dbFilePath'] = $filename; $p['schema'] = null; $p['tablePrefix'] = ''; /** @var DatabaseSqlite $db */ $db = ( new DatabaseFactory() )->create( 'sqlite', $p ); '@phan-var DatabaseSqlite $db'; return $db; } /** * @return string */ public function getType() { return 'sqlite'; } protected function open( $server, $user, $password, $db, $schema, $tablePrefix ) { $this->close( __METHOD__ ); // Note that for SQLite, $server, $user, and $pass are ignored if ( $schema !== null ) { throw $this->newExceptionAfterConnectError( "Got schema '$schema'; not supported." ); } if ( $this->dbPath !== null ) { $path = $this->dbPath; } elseif ( $this->dbDir !== null ) { $path = self::generateFileName( $this->dbDir, $db ); } else { throw $this->newExceptionAfterConnectError( "DB path or directory required" ); } // Check if the database file already exists but is non-readable if ( !self::isProcessMemoryPath( $path ) && is_file( $path ) && !is_readable( $path ) ) { throw $this->newExceptionAfterConnectError( 'SQLite database file is not readable' ); } elseif ( !in_array( $this->trxMode, self::VALID_TRX_MODES, true ) ) { throw $this->newExceptionAfterConnectError( "Got mode '{$this->trxMode}' for BEGIN" ); } $attributes = [ PDO::ATTR_ERRMODE => PDO::ERRMODE_SILENT, // Starting with PHP 8.1, The SQLite PDO returns proper types instead // of strings or null for everything. We cast every non-null value to // string to restore the old behavior. PDO::ATTR_STRINGIFY_FETCHES => true ]; if ( $this->getFlag( self::DBO_PERSISTENT ) ) { // Persistent connections can avoid some schema index reading overhead. // On the other hand, they can cause horrible contention with DBO_TRX. if ( $this->getFlag( self::DBO_TRX ) || $this->getFlag( self::DBO_DEFAULT ) ) { $this->logger->warning( __METHOD__ . ": ignoring DBO_PERSISTENT due to DBO_TRX or DBO_DEFAULT", $this->getLogContext() ); } else { $attributes[PDO::ATTR_PERSISTENT] = true; } } try { // Open the database file, creating it if it does not yet exist $this->conn = new PDO( "sqlite:$path", null, null, $attributes ); } catch ( PDOException $e ) { throw $this->newExceptionAfterConnectError( $e->getMessage() ); } $this->currentDomain = new DatabaseDomain( $db, null, $tablePrefix ); $this->platform->setCurrentDomain( $this->currentDomain ); try { // Enforce LIKE to be case sensitive, just like MySQL $query = new Query( 'PRAGMA case_sensitive_like = 1', self::QUERY_CHANGE_TRX | self::QUERY_NO_RETRY, 'PRAGMA' ); $this->query( $query, __METHOD__ ); // Set any connection-level custom PRAGMA options $pragmas = array_intersect_key( $this->connectionVariables, self::VALID_PRAGMAS ); $pragmas += $this->getDefaultPragmas(); foreach ( $pragmas as $name => $value ) { $allowed = self::VALID_PRAGMAS[$name]; if ( ( is_array( $allowed ) && in_array( $value, $allowed, true ) ) || ( is_string( $allowed ) && gettype( $value ) === $allowed ) ) { $query = new Query( "PRAGMA $name = $value", self::QUERY_CHANGE_TRX | self::QUERY_NO_RETRY, 'PRAGMA', null, "PRAGMA $name = '?'" ); $this->query( $query, __METHOD__ ); } } $this->attachDatabasesFromTableAliases(); } catch ( RuntimeException $e ) { throw $this->newExceptionAfterConnectError( $e->getMessage() ); } } /** * @return array Map of (name => value) for default values to set via PRAGMA */ private function getDefaultPragmas() { $variables = []; if ( !$this->cliMode ) { $variables['temp_store'] = 'MEMORY'; } return $variables; } /** * @return string|null SQLite DB file path * @throws DBUnexpectedError * @since 1.25 */ public function getDbFilePath() { return $this->dbPath ?? self::generateFileName( $this->dbDir, $this->getDBname() ); } /** * @return string|null Lock file directory */ public function getLockFileDirectory() { if ( $this->dbPath !== null && !self::isProcessMemoryPath( $this->dbPath ) ) { return dirname( $this->dbPath ) . '/locks'; } elseif ( $this->dbDir !== null && !self::isProcessMemoryPath( $this->dbDir ) ) { return $this->dbDir . '/locks'; } return null; } /** * Initialize/reset the LockManager instance * * @return LockManager */ private function makeLockManager(): LockManager { $lockDirectory = $this->getLockFileDirectory(); if ( $lockDirectory !== null ) { return new FSLockManager( [ 'domain' => $this->getDomainID(), 'lockDirectory' => $lockDirectory, ] ); } else { return new NullLockManager( [ 'domain' => $this->getDomainID() ] ); } } /** * Does not actually close the connection, just destroys the reference for GC to do its work * @return bool */ protected function closeConnection() { $this->conn = null; // Release all locks, via FSLockManager::__destruct, as the base class expects $this->lockMgr = null; return true; } /** * Generates a database file name. Explicitly public for installer. * @param string $dir Directory where database resides * @param string|null $dbName Database name (or null from Database::factory, validated here) * @return string * @throws DBUnexpectedError */ public static function generateFileName( $dir, $dbName ) { if ( $dir == '' ) { throw new DBUnexpectedError( null, __CLASS__ . ": no DB directory specified" ); } elseif ( self::isProcessMemoryPath( $dir ) ) { throw new DBUnexpectedError( null, __CLASS__ . ": cannot use process memory directory '$dir'" ); } elseif ( !strlen( $dbName ) ) { throw new DBUnexpectedError( null, __CLASS__ . ": no DB name specified" ); } return "$dir/$dbName.sqlite"; } /** * @param string $path * @return string */ private static function generateDatabaseName( $path ) { if ( preg_match( '/^(:memory:$|file::memory:)/', $path ) ) { // E.g. "file::memory:?cache=shared" => ":memory": return ':memory:'; } elseif ( preg_match( '/^file::([^?]+)\?mode=memory(&|$)/', $path, $m ) ) { // E.g. "file:memdb1?mode=memory" => ":memdb1:" return ":{$m[1]}:"; } else { // E.g. "/home/.../some_db.sqlite3" => "some_db" return preg_replace( '/\.sqlite\d?$/', '', basename( $path ) ); } } /** * @param string $path * @return bool */ private static function isProcessMemoryPath( $path ) { return preg_match( '/^(:memory:$|file:(:memory:|[^?]+\?mode=memory(&|$)))/', $path ); } /** * Returns version of currently supported SQLite fulltext search module or false if none present. * @return string|false */ public static function getFulltextSearchModule() { static $cachedResult = null; if ( $cachedResult !== null ) { return $cachedResult; } $cachedResult = false; $table = 'dummy_search_test'; $db = self::newStandaloneInstance( ':memory:' ); if ( $db->query( "CREATE VIRTUAL TABLE $table USING FTS3(dummy_field)", __METHOD__, IDatabase::QUERY_SILENCE_ERRORS ) ) { $cachedResult = 'FTS3'; } $db->close( __METHOD__ ); return $cachedResult; } /** * Attaches external database to the connection handle * * @see https://sqlite.org/lang_attach.html * * @param string $name Database name to be used in queries like * SELECT foo FROM dbname.table * @param bool|string $file Database file name. If omitted, will be generated * using $name and configured data directory * @param string $fname Calling function name @phan-mandatory-param * @return IResultWrapper */ public function attachDatabase( $name, $file = false, $fname = __METHOD__ ) { $file = is_string( $file ) ? $file : self::generateFileName( $this->dbDir, $name ); $encFile = $this->addQuotes( $file ); $query = new Query( "ATTACH DATABASE $encFile AS $name", self::QUERY_CHANGE_TRX, 'ATTACH' ); return $this->query( $query, $fname ); } protected function doSingleStatementQuery( string $sql ): QueryStatus { $res = $this->getBindingHandle()->query( $sql ); // Note that rowCount() returns 0 for SELECT for SQLite return new QueryStatus( $res instanceof PDOStatement ? new SqliteResultWrapper( $res ) : $res, $res ? $res->rowCount() : 0, $this->lastError(), $this->lastErrno() ); } protected function doSelectDomain( DatabaseDomain $domain ) { if ( $domain->getSchema() !== null ) { throw new DBExpectedError( $this, __CLASS__ . ": domain '{$domain->getId()}' has a schema component" ); } $database = $domain->getDatabase(); // A null database means "don't care" so leave it as is and update the table prefix if ( $database === null ) { $this->currentDomain = new DatabaseDomain( $this->currentDomain->getDatabase(), null, $domain->getTablePrefix() ); $this->platform->setCurrentDomain( $this->currentDomain ); return true; } if ( $database !== $this->getDBname() ) { throw new DBExpectedError( $this, __CLASS__ . ": cannot change database (got '$database')" ); } // Update that domain fields on success (no exception thrown) $this->currentDomain = $domain; $this->platform->setCurrentDomain( $domain ); return true; } protected function lastInsertId() { // PDO::lastInsertId yields a string :( return (int)$this->getBindingHandle()->lastInsertId(); } /** * @return string */ public function lastError() { if ( is_object( $this->conn ) ) { $e = $this->conn->errorInfo(); return $e[2] ?? $this->lastConnectError; } return 'No database connection'; } /** * @return int */ public function lastErrno() { if ( is_object( $this->conn ) ) { $info = $this->conn->errorInfo(); if ( isset( $info[1] ) ) { return $info[1]; } } return 0; } public function tableExists( $table, $fname = __METHOD__ ) { [ $db, $pt ] = $this->platform->getDatabaseAndTableIdentifier( $table ); if ( isset( $this->sessionTempTables[$db][$pt] ) ) { return true; // already known to exist } $encTable = $this->addQuotes( $pt ); $query = new Query( "SELECT 1 FROM sqlite_master WHERE type='table' AND name=$encTable", self::QUERY_IGNORE_DBO_TRX | self::QUERY_CHANGE_NONE, 'SELECT' ); $res = $this->query( $query, __METHOD__ ); return (bool)$res->numRows(); } public function indexInfo( $table, $index, $fname = __METHOD__ ) { $indexName = $this->platform->indexName( $index ); $components = $this->platform->qualifiedTableComponents( $table ); $tableRaw = end( $components ); $query = new Query( 'PRAGMA index_list(' . $this->addQuotes( $tableRaw ) . ')', self::QUERY_IGNORE_DBO_TRX | self::QUERY_CHANGE_NONE, 'PRAGMA' ); $res = $this->query( $query, $fname ); foreach ( $res as $row ) { if ( $row->name === $indexName ) { return [ 'unique' => (bool)$row->unique ]; } } return false; } public function replace( $table, $uniqueKeys, $rows, $fname = __METHOD__ ) { $this->platform->normalizeUpsertParams( $uniqueKeys, $rows ); if ( !$rows ) { return; } $encTable = $this->tableName( $table ); [ $sqlColumns, $sqlTuples ] = $this->platform->makeInsertLists( $rows ); // https://sqlite.org/lang_insert.html // Note that any auto-increment columns on conflicting rows will be reassigned // due to combined DELETE+INSERT semantics. This will be reflected in insertId(). $query = new Query( "REPLACE INTO $encTable ($sqlColumns) VALUES $sqlTuples", self::QUERY_CHANGE_ROWS, 'REPLACE', $table ); $this->query( $query, $fname ); } protected function isConnectionError( $errno ) { return $errno == 17; // SQLITE_SCHEMA; } protected function isKnownStatementRollbackError( $errno ) { // ON CONFLICT ROLLBACK clauses make it so that SQLITE_CONSTRAINT error is // ambiguous with regard to whether it implies a ROLLBACK or an ABORT happened. // https://sqlite.org/lang_createtable.html#uniqueconst // https://sqlite.org/lang_conflict.html return false; } public function serverIsReadOnly() { $this->assertHasConnectionHandle(); $path = $this->getDbFilePath(); return ( !self::isProcessMemoryPath( $path ) && !is_writable( $path ) ); } /** * @return string Wikitext of a link to the server software's web site */ public function getSoftwareLink() { return "[{{int:version-db-sqlite-url}} SQLite]"; } /** * @return string Version information from the database */ public function getServerVersion() { if ( $this->version === null ) { $this->version = $this->getBindingHandle()->getAttribute( PDO::ATTR_SERVER_VERSION ); } return $this->version; } /** * Get information about a given field * Returns false if the field does not exist. * * @param string $table * @param string $field * @return SQLiteField|false False on failure */ public function fieldInfo( $table, $field ) { $components = $this->platform->qualifiedTableComponents( $table ); $tableRaw = end( $components ); $query = new Query( 'PRAGMA table_info(' . $this->addQuotes( $tableRaw ) . ')', self::QUERY_IGNORE_DBO_TRX | self::QUERY_CHANGE_NONE, 'PRAGMA' ); $res = $this->query( $query, __METHOD__ ); foreach ( $res as $row ) { if ( $row->name == $field ) { return new SQLiteField( $row, $tableRaw ); } } return false; } protected function doBegin( $fname = '' ) { if ( $this->trxMode != '' ) { $sql = "BEGIN {$this->trxMode}"; } else { $sql = 'BEGIN'; } $query = new Query( $sql, self::QUERY_CHANGE_TRX, 'BEGIN' ); $this->query( $query, $fname ); } /** * @param string $s * @return string */ public function strencode( $s ) { return substr( $this->addQuotes( $s ), 1, -1 ); } /** * @param string $b * @return Blob */ public function encodeBlob( $b ) { return new Blob( $b ); } /** * @param Blob|string $b * @return string */ public function decodeBlob( $b ) { if ( $b instanceof Blob ) { $b = $b->fetch(); } if ( $b === null ) { // An empty blob is decoded as null in PHP before PHP 8.1. // It was probably fixed as a side-effect of caa710037e663fd78f67533b29611183090068b2 $b = ''; } return $b; } public function addQuotes( $s ) { if ( $s instanceof RawSQLValue ) { return $s->toSql(); } if ( $s instanceof Blob ) { return "x'" . bin2hex( $s->fetch() ) . "'"; } elseif ( is_bool( $s ) ) { return (string)(int)$s; } elseif ( is_int( $s ) ) { return (string)$s; } elseif ( strpos( (string)$s, "\0" ) !== false ) { // SQLite doesn't support \0 in strings, so use the hex representation as a workaround. // This is a known limitation of SQLite's mprintf function which PDO // should work around, but doesn't. I have reported this to php.net as bug #63419: // https://bugs.php.net/bug.php?id=63419 // There was already a similar report for SQLite3::escapeString, bug #62361: // https://bugs.php.net/bug.php?id=62361 // There is an additional bug regarding sorting this data after insert // on older versions of sqlite shipped with ubuntu 12.04 // https://phabricator.wikimedia.org/T74367 $this->logger->debug( __FUNCTION__ . ': Quoting value containing null byte. ' . 'For consistency all binary data should have been ' . 'first processed with self::encodeBlob()' ); return "x'" . bin2hex( (string)$s ) . "'"; } else { return $this->getBindingHandle()->quote( (string)$s ); } } public function doLockIsFree( string $lockName, string $method ) { // Only locks by this thread will be checked return true; } public function doLock( string $lockName, string $method, int $timeout ) { $status = $this->lockMgr->lock( [ $lockName ], LockManager::LOCK_EX, $timeout ); if ( $this->lockMgr instanceof FSLockManager && $status->hasMessage( 'lockmanager-fail-openlock' ) ) { throw new DBError( $this, "Cannot create directory \"{$this->getLockFileDirectory()}\"" ); } return $status->isOK() ? microtime( true ) : null; } public function doUnlock( string $lockName, string $method ) { return $this->lockMgr->unlock( [ $lockName ], LockManager::LOCK_EX )->isGood(); } /** * @param string $oldName * @param string $newName * @param bool $temporary * @param string $fname * @return bool|IResultWrapper * @throws RuntimeException */ public function duplicateTableStructure( $oldName, $newName, $temporary = false, $fname = __METHOD__ ) { $query = new Query( "SELECT sql FROM sqlite_master WHERE tbl_name=" . $this->addQuotes( $oldName ) . " AND type='table'", self::QUERY_IGNORE_DBO_TRX | self::QUERY_CHANGE_NONE, 'SELECT' ); $res = $this->query( $query, $fname ); $obj = $res->fetchObject(); if ( !$obj ) { throw new RuntimeException( "Couldn't retrieve structure for table $oldName" ); } $sqlCreateTable = $obj->sql; $sqlCreateTable = preg_replace( '/(?<=\W)"?' . preg_quote( trim( $this->platform->addIdentifierQuotes( $oldName ), '"' ), '/' ) . '"?(?=\W)/', $this->platform->addIdentifierQuotes( $newName ), $sqlCreateTable, 1 ); $flags = self::QUERY_CHANGE_SCHEMA | self::QUERY_PSEUDO_PERMANENT; if ( $temporary ) { if ( preg_match( '/^\\s*CREATE\\s+VIRTUAL\\s+TABLE\b/i', $sqlCreateTable ) ) { $this->logger->debug( "Table $oldName is virtual, can't create a temporary duplicate." ); } else { $sqlCreateTable = str_replace( 'CREATE TABLE', 'CREATE TEMPORARY TABLE', $sqlCreateTable ); } } $query = new Query( $sqlCreateTable, $flags, $temporary ? 'CREATE TEMPORARY' : 'CREATE', // Use a dot to avoid double-prefixing in Database::getTempTableWrites() '.' . $newName ); $res = $this->query( $query, $fname ); $query = new Query( 'PRAGMA INDEX_LIST(' . $this->addQuotes( $oldName ) . ')', self::QUERY_IGNORE_DBO_TRX | self::QUERY_CHANGE_NONE, 'PRAGMA' ); // Take over indexes $indexList = $this->query( $query, $fname ); foreach ( $indexList as $index ) { if ( strpos( $index->name, 'sqlite_autoindex' ) === 0 ) { continue; } if ( $index->unique ) { $sqlIndex = 'CREATE UNIQUE INDEX'; } else { $sqlIndex = 'CREATE INDEX'; } // Try to come up with a new index name, given indexes have database scope in SQLite $indexName = $newName . '_' . $index->name; $sqlIndex .= ' ' . $this->platform->addIdentifierQuotes( $indexName ) . ' ON ' . $this->platform->addIdentifierQuotes( $newName ); $query = new Query( 'PRAGMA INDEX_INFO(' . $this->addQuotes( $index->name ) . ')', self::QUERY_IGNORE_DBO_TRX | self::QUERY_CHANGE_NONE, 'PRAGMA' ); $indexInfo = $this->query( $query, $fname ); $fields = []; foreach ( $indexInfo as $indexInfoRow ) { $fields[$indexInfoRow->seqno] = $this->addQuotes( $indexInfoRow->name ); } $sqlIndex .= '(' . implode( ',', $fields ) . ')'; $query = new Query( $sqlIndex, self::QUERY_CHANGE_SCHEMA | self::QUERY_PSEUDO_PERMANENT, 'CREATE', $newName ); $this->query( $query, __METHOD__ ); } return $res; } /** * List all tables on the database * * @param string|null $prefix Only show tables with this prefix, e.g. mw_ * @param string $fname Calling function name * * @return array */ public function listTables( $prefix = null, $fname = __METHOD__ ) { $query = new Query( "SELECT name FROM sqlite_master WHERE type = 'table'", self::QUERY_IGNORE_DBO_TRX | self::QUERY_CHANGE_NONE, 'SELECT' ); $result = $this->query( $query, $fname ); $endArray = []; foreach ( $result as $table ) { $vars = get_object_vars( $table ); $table = array_pop( $vars ); if ( !$prefix || strpos( $table, $prefix ) === 0 ) { if ( strpos( $table, 'sqlite_' ) !== 0 ) { $endArray[] = $table; } } } return $endArray; } public function truncateTable( $table, $fname = __METHOD__ ) { $this->startAtomic( $fname ); // Use "truncate" optimization; https://www.sqlite.org/lang_delete.html $query = new Query( "DELETE FROM " . $this->tableName( $table ), self::QUERY_CHANGE_SCHEMA, 'DELETE', $table ); $this->query( $query, $fname ); $encMasterTable = $this->platform->addIdentifierQuotes( 'sqlite_sequence' ); $encSequenceName = $this->addQuotes( $this->tableName( $table, 'raw' ) ); $query = new Query( "DELETE FROM $encMasterTable WHERE name = $encSequenceName", self::QUERY_CHANGE_SCHEMA, 'DELETE', 'sqlite_sequence' ); $this->query( $query, $fname ); $this->endAtomic( $fname ); } public function setTableAliases( array $aliases ) { parent::setTableAliases( $aliases ); if ( $this->isOpen() ) { $this->attachDatabasesFromTableAliases(); } } /** * Issue ATTATCH statements for all unattached foreign DBs in table aliases */ private function attachDatabasesFromTableAliases() { foreach ( $this->platform->getTableAliases() as $params ) { if ( $params['dbname'] !== $this->getDBname() && !isset( $this->sessionAttachedDbs[$params['dbname']] ) ) { $this->attachDatabase( $params['dbname'], false, __METHOD__ ); $this->sessionAttachedDbs[$params['dbname']] = true; } } } public function databasesAreIndependent() { return true; } protected function doHandleSessionLossPreconnect() { $this->sessionAttachedDbs = []; // Release all locks, via FSLockManager::__destruct, as the base class expects; $this->lockMgr = null; // Create a new lock manager instance $this->lockMgr = $this->makeLockManager(); } protected function doFlushSession( $fname ) { // Release all locks, via FSLockManager::__destruct, as the base class expects $this->lockMgr = null; // Create a new lock manager instance $this->lockMgr = $this->makeLockManager(); } /** * @return PDO */ protected function getBindingHandle() { return parent::getBindingHandle(); } protected function getInsertIdColumnForUpsert( $table ) { $components = $this->platform->qualifiedTableComponents( $table ); $tableRaw = end( $components ); $query = new Query( 'PRAGMA table_info(' . $this->addQuotes( $tableRaw ) . ')', self::QUERY_IGNORE_DBO_TRX | self::QUERY_CHANGE_NONE, 'PRAGMA' ); $res = $this->query( $query, __METHOD__ ); foreach ( $res as $row ) { if ( $row->pk && strtolower( $row->type ) === 'integer' ) { return $row->name; } } return null; } } PK ! b���j �j rdbms/database/DBConnRef.phpnu �Iw�� <?php namespace Wikimedia\Rdbms; use InvalidArgumentException; use Stringable; /** * Helper class used for automatically re-using IDatabase connections and lazily * establishing the actual network connection to a database host. * * It does this by deferring to ILoadBalancer::getConnectionInternal, which in * turn ensures we share and re-use a single connection for a given database * wherever possible. * * This class previously used an RAII-style pattern where connections would be * claimed from a pool, and then added back to the pool for re-use only after * the calling code's variable for this object went out of scope (a __destruct * got called when the calling function returns or throws). This is no longer * needed today as LoadBalancer now permits re-use internally even for * overlapping callers, where two pieces of code may both obtain their own * DBConnRef object and where both are used alternatingly, and yet still share * the same connection. * * @par Example: * @code * function getRowData() { * $conn = $this->lb->getConnection( DB_REPLICA ); * $row = $conn->select( ... ); * return $row ? (array)$row : false; * } * @endcode * * @ingroup Database * @since 1.22 */ class DBConnRef implements Stringable, IMaintainableDatabase, IDatabaseForOwner { /** @var ILoadBalancer */ private $lb; /** @var Database|null Live connection handle */ private $conn; /** * @var array Map of (DBConnRef::FLD_* constant => connection parameter) * @phan-var array{0:int,1:array|string|false,2:DatabaseDomain,3:int} */ private $params; /** @var int One of DB_PRIMARY/DB_REPLICA */ private $role; /** * @var int Reference to the $modcount passed to the constructor. * $conn is valid if $modCountRef and $modCountFix are the same. */ private $modCountRef; /** * @var int Last known good value of $modCountRef * $conn is valid if $modCountRef and $modCountFix are the same. */ private $modCountFix; private const FLD_INDEX = 0; private const FLD_GROUPS = 1; private const FLD_DOMAIN = 2; private const FLD_FLAGS = 3; /** * @internal May not be used outside Rdbms LoadBalancer * @param ILoadBalancer $lb Connection manager for $conn * @param array $params [server index, query groups, domain, flags] * @param int $role The type of connection asked for; one of DB_PRIMARY/DB_REPLICA * @param null|int &$modcount Reference to a modification counter. This is for * LoadBalancer::reconfigure to indicate that a new connection should be acquired. */ public function __construct( ILoadBalancer $lb, $params, $role, &$modcount = 0 ) { if ( !is_array( $params ) || count( $params ) < 4 || $params[self::FLD_DOMAIN] === false ) { throw new InvalidArgumentException( "Missing lazy connection arguments." ); } $params[self::FLD_DOMAIN] = DatabaseDomain::newFromId( $params[self::FLD_DOMAIN] ); $this->lb = $lb; $this->params = $params; $this->role = $role; // $this->conn is valid as long as $this->modCountRef and $this->modCountFix are the same. $this->modCountRef = &$modcount; // remember reference $this->modCountFix = $modcount; // remember current value } /** * Connect to the database if we are not already connected. */ public function ensureConnection() { if ( $this->modCountFix !== $this->modCountRef ) { // Discard existing connection, unless we are in an ongoing transaction. // This is triggered by LoadBalancer::reconfigure(), to allow changed settings // to take effect. The primary use case are replica servers being taken out of // rotation, or the primary database changing. if ( $this->conn && !$this->conn->trxLevel() ) { $this->conn->close(); $this->conn = null; } } if ( $this->conn === null ) { $this->conn = $this->lb->getConnectionInternal( $this->params[self::FLD_INDEX], $this->params[self::FLD_GROUPS], $this->params[self::FLD_DOMAIN]->getId(), $this->params[self::FLD_FLAGS] ); $this->modCountFix = $this->modCountRef; } if ( !$this->params[self::FLD_DOMAIN]->equals( $this->conn->getDomainID() ) ) { // The underlying connection handle is likely being shared by other DBConnRef // instances in a load balancer. Make sure that each one routes queries by their // owner function to the domain that the owner expects. $this->conn->selectDomain( $this->params[self::FLD_DOMAIN] ); } } public function __call( $name, array $arguments ) { $this->ensureConnection(); return $this->conn->$name( ...$arguments ); } /** * @return int DB_PRIMARY when this *requires* the primary DB, otherwise DB_REPLICA * @since 1.33 */ public function getReferenceRole() { return $this->role; } public function getServerInfo() { return $this->__call( __FUNCTION__, func_get_args() ); } public function trxLevel() { return $this->__call( __FUNCTION__, func_get_args() ); } public function trxTimestamp() { return $this->__call( __FUNCTION__, func_get_args() ); } public function explicitTrxActive() { return $this->__call( __FUNCTION__, func_get_args() ); } public function tablePrefix( $prefix = null ) { if ( $prefix !== null ) { // Disallow things that might confuse the LoadBalancer tracking throw $this->getDomainChangeException(); } if ( $this->conn === null ) { // Avoid triggering a database connection $prefix = $this->params[self::FLD_DOMAIN]->getTablePrefix(); } else { // This will just return the prefix $prefix = $this->__call( __FUNCTION__, func_get_args() ); } return $prefix; } public function dbSchema( $schema = null ) { if ( $schema !== null ) { // Disallow things that might confuse the LoadBalancer tracking throw $this->getDomainChangeException(); } if ( $this->conn === null ) { // Avoid triggering a database connection $schema = (string)( $this->params[self::FLD_DOMAIN]->getSchema() ); } else { // This will just return the schema $schema = $this->__call( __FUNCTION__, func_get_args() ); } return $schema; } public function getLBInfo( $name = null ) { return $this->__call( __FUNCTION__, func_get_args() ); } public function setLBInfo( $nameOrArray, $value = null ) { // @phan-suppress-previous-line PhanPluginNeverReturnMethod // Disallow things that might confuse the LoadBalancer tracking throw $this->getDomainChangeException(); } public function implicitOrderby() { return $this->__call( __FUNCTION__, func_get_args() ); } public function lastDoneWrites() { return $this->__call( __FUNCTION__, func_get_args() ); } public function writesPending() { return $this->__call( __FUNCTION__, func_get_args() ); } public function writesOrCallbacksPending() { return $this->__call( __FUNCTION__, func_get_args() ); } public function pendingWriteQueryDuration( $type = self::ESTIMATE_TOTAL ) { return $this->__call( __FUNCTION__, func_get_args() ); } public function pendingWriteCallers() { return $this->__call( __FUNCTION__, func_get_args() ); } public function isOpen() { return $this->__call( __FUNCTION__, func_get_args() ); } public function setFlag( $flag, $remember = self::REMEMBER_NOTHING ) { return $this->__call( __FUNCTION__, func_get_args() ); } public function clearFlag( $flag, $remember = self::REMEMBER_NOTHING ) { return $this->__call( __FUNCTION__, func_get_args() ); } public function restoreFlags( $state = self::RESTORE_PRIOR ) { return $this->__call( __FUNCTION__, func_get_args() ); } public function getFlag( $flag ) { return $this->__call( __FUNCTION__, func_get_args() ); } public function getProperty( $name ) { return $this->__call( __FUNCTION__, func_get_args() ); } public function getDomainID() { if ( $this->conn === null ) { // Avoid triggering a database connection return $this->params[self::FLD_DOMAIN]->getId(); } return $this->__call( __FUNCTION__, func_get_args() ); } public function getType() { if ( $this->conn === null ) { // Avoid triggering a database connection $index = $this->normalizeServerIndex( $this->params[self::FLD_INDEX] ); if ( $index >= 0 ) { // In theory, if $index is DB_REPLICA, the type could vary return $this->lb->getServerType( $index ); } } return $this->__call( __FUNCTION__, func_get_args() ); } public function insertId() { return $this->__call( __FUNCTION__, func_get_args() ); } public function lastErrno() { return $this->__call( __FUNCTION__, func_get_args() ); } public function lastError() { return $this->__call( __FUNCTION__, func_get_args() ); } public function affectedRows() { return $this->__call( __FUNCTION__, func_get_args() ); } public function getSoftwareLink() { return $this->__call( __FUNCTION__, func_get_args() ); } public function getServerVersion() { return $this->__call( __FUNCTION__, func_get_args() ); } public function close( $fname = __METHOD__ ) { // @phan-suppress-previous-line PhanPluginNeverReturnMethod throw new DBUnexpectedError( $this->conn, 'Cannot close shared connection.' ); } public function query( $sql, $fname = __METHOD__, $flags = 0 ) { if ( $this->role !== ILoadBalancer::DB_PRIMARY ) { $flags |= IDatabase::QUERY_REPLICA_ROLE; } return $this->__call( __FUNCTION__, [ $sql, $fname, $flags ] ); } public function newSelectQueryBuilder(): SelectQueryBuilder { // Use $this not $this->conn so that the domain is preserved (T326377) return new SelectQueryBuilder( $this ); } public function newUnionQueryBuilder(): UnionQueryBuilder { // Use $this not $this->conn so that the domain is preserved (T326377) return new UnionQueryBuilder( $this ); } public function newUpdateQueryBuilder(): UpdateQueryBuilder { // Use $this not $this->conn so that the domain is preserved (T326377) return new UpdateQueryBuilder( $this ); } public function newDeleteQueryBuilder(): DeleteQueryBuilder { // Use $this not $this->conn so that the domain is preserved (T326377) return new DeleteQueryBuilder( $this ); } public function newInsertQueryBuilder(): InsertQueryBuilder { // Use $this not $this->conn so that the domain is preserved (T326377) return new InsertQueryBuilder( $this ); } public function newReplaceQueryBuilder(): ReplaceQueryBuilder { // Use $this not $this->conn so that the domain is preserved (T326377) return new ReplaceQueryBuilder( $this ); } public function selectField( $tables, $var, $cond = '', $fname = __METHOD__, $options = [], $join_conds = [] ) { return $this->__call( __FUNCTION__, func_get_args() ); } public function selectFieldValues( $tables, $var, $cond = '', $fname = __METHOD__, $options = [], $join_conds = [] ): array { return $this->__call( __FUNCTION__, func_get_args() ); } public function select( $tables, $vars, $conds = '', $fname = __METHOD__, $options = [], $join_conds = [] ) { return $this->__call( __FUNCTION__, func_get_args() ); } public function selectSQLText( $tables, $vars, $conds = '', $fname = __METHOD__, $options = [], $join_conds = [] ) { return $this->__call( __FUNCTION__, func_get_args() ); } public function limitResult( $sql, $limit, $offset = false ) { return $this->__call( __FUNCTION__, func_get_args() ); } public function selectRow( $tables, $vars, $conds, $fname = __METHOD__, $options = [], $join_conds = [] ) { return $this->__call( __FUNCTION__, func_get_args() ); } public function estimateRowCount( $tables, $vars = '*', $conds = '', $fname = __METHOD__, $options = [], $join_conds = [] ): int { return $this->__call( __FUNCTION__, func_get_args() ); } public function selectRowCount( $tables, $vars = '*', $conds = '', $fname = __METHOD__, $options = [], $join_conds = [] ): int { return $this->__call( __FUNCTION__, func_get_args() ); } public function lockForUpdate( $table, $conds = '', $fname = __METHOD__, $options = [], $join_conds = [] ) { $this->assertRoleAllowsWrites(); return $this->__call( __FUNCTION__, func_get_args() ); } public function fieldExists( $table, $field, $fname = __METHOD__ ) { return $this->__call( __FUNCTION__, func_get_args() ); } public function indexExists( $table, $index, $fname = __METHOD__ ) { return $this->__call( __FUNCTION__, func_get_args() ); } public function tableExists( $table, $fname = __METHOD__ ) { return $this->__call( __FUNCTION__, func_get_args() ); } public function insert( $table, $rows, $fname = __METHOD__, $options = [] ) { $this->assertRoleAllowsWrites(); return $this->__call( __FUNCTION__, func_get_args() ); } public function update( $table, $set, $conds, $fname = __METHOD__, $options = [] ) { $this->assertRoleAllowsWrites(); return $this->__call( __FUNCTION__, func_get_args() ); } public function buildComparison( string $op, array $conds ): string { return $this->__call( __FUNCTION__, func_get_args() ); } public function makeList( array $a, $mode = self::LIST_COMMA ) { return $this->__call( __FUNCTION__, func_get_args() ); } public function makeWhereFrom2d( $data, $baseKey, $subKey ) { return $this->__call( __FUNCTION__, func_get_args() ); } public function factorConds( $condsArray ) { return $this->__call( __FUNCTION__, func_get_args() ); } public function bitNot( $field ) { return $this->__call( __FUNCTION__, func_get_args() ); } public function bitAnd( $fieldLeft, $fieldRight ) { return $this->__call( __FUNCTION__, func_get_args() ); } public function bitOr( $fieldLeft, $fieldRight ) { return $this->__call( __FUNCTION__, func_get_args() ); } public function buildConcat( $stringList ) { return $this->__call( __FUNCTION__, func_get_args() ); } public function buildGroupConcatField( $delim, $tables, $field, $conds = '', $join_conds = [] ) { return $this->__call( __FUNCTION__, func_get_args() ); } public function buildGreatest( $fields, $values ) { return $this->__call( __FUNCTION__, func_get_args() ); } public function buildLeast( $fields, $values ) { return $this->__call( __FUNCTION__, func_get_args() ); } public function buildSubstring( $input, $startPosition, $length = null ) { return $this->__call( __FUNCTION__, func_get_args() ); } public function buildStringCast( $field ) { return $this->__call( __FUNCTION__, func_get_args() ); } public function buildIntegerCast( $field ) { return $this->__call( __FUNCTION__, func_get_args() ); } public function buildExcludedValue( $column ) { return $this->__call( __FUNCTION__, func_get_args() ); } public function buildSelectSubquery( $tables, $vars, $conds = '', $fname = __METHOD__, $options = [], $join_conds = [] ) { return $this->__call( __FUNCTION__, func_get_args() ); } public function databasesAreIndependent() { return $this->__call( __FUNCTION__, func_get_args() ); } public function selectDomain( $domain ) { // @phan-suppress-previous-line PhanPluginNeverReturnMethod // Disallow things that might confuse the LoadBalancer tracking throw $this->getDomainChangeException(); } public function getDBname() { if ( $this->conn === null ) { // Avoid triggering a database connection return $this->params[self::FLD_DOMAIN]->getDatabase(); } return $this->__call( __FUNCTION__, func_get_args() ); } public function getServer() { return $this->__call( __FUNCTION__, func_get_args() ); } public function getServerName() { if ( $this->conn === null ) { // Avoid triggering a database connection $index = $this->normalizeServerIndex( $this->params[self::FLD_INDEX] ); if ( $index >= 0 ) { // If $index is DB_REPLICA, the server name could vary return $this->lb->getServerName( $index ); } } return $this->__call( __FUNCTION__, func_get_args() ); } public function addQuotes( $s ) { return $this->__call( __FUNCTION__, func_get_args() ); } public function expr( string $field, string $op, $value ): Expression { // Does not use __call here to delay creating the db connection return new Expression( $field, $op, $value ); } public function andExpr( array $conds ): AndExpressionGroup { // Does not use __call here to delay creating the db connection return AndExpressionGroup::newFromArray( $conds ); } public function orExpr( array $conds ): OrExpressionGroup { // Does not use __call here to delay creating the db connection return OrExpressionGroup::newFromArray( $conds ); } public function addIdentifierQuotes( $s ) { return $this->__call( __FUNCTION__, func_get_args() ); } public function buildLike( $param, ...$params ) { return $this->__call( __FUNCTION__, func_get_args() ); } public function anyChar() { return $this->__call( __FUNCTION__, func_get_args() ); } public function anyString() { return $this->__call( __FUNCTION__, func_get_args() ); } public function replace( $table, $uniqueKeys, $rows, $fname = __METHOD__ ) { $this->assertRoleAllowsWrites(); return $this->__call( __FUNCTION__, func_get_args() ); } public function upsert( $table, array $rows, $uniqueKeys, array $set, $fname = __METHOD__ ) { $this->assertRoleAllowsWrites(); return $this->__call( __FUNCTION__, func_get_args() ); } public function deleteJoin( $delTable, $joinTable, $delVar, $joinVar, $conds, $fname = __METHOD__ ) { $this->assertRoleAllowsWrites(); $this->__call( __FUNCTION__, func_get_args() ); } public function delete( $table, $conds, $fname = __METHOD__ ) { $this->assertRoleAllowsWrites(); return $this->__call( __FUNCTION__, func_get_args() ); } public function insertSelect( $destTable, $srcTable, $varMap, $conds, $fname = __METHOD__, $insertOptions = [], $selectOptions = [], $selectJoinConds = [] ) { $this->assertRoleAllowsWrites(); return $this->__call( __FUNCTION__, func_get_args() ); } public function unionSupportsOrderAndLimit() { return $this->__call( __FUNCTION__, func_get_args() ); } public function unionQueries( $sqls, $all, $options = [] ) { return $this->__call( __FUNCTION__, func_get_args() ); } public function conditional( $cond, $caseTrueExpression, $caseFalseExpression ) { return $this->__call( __FUNCTION__, func_get_args() ); } public function strreplace( $orig, $old, $new ) { return $this->__call( __FUNCTION__, func_get_args() ); } public function primaryPosWait( DBPrimaryPos $pos, $timeout ) { return $this->__call( __FUNCTION__, func_get_args() ); } public function getPrimaryPos() { return $this->__call( __FUNCTION__, func_get_args() ); } public function serverIsReadOnly() { return $this->__call( __FUNCTION__, func_get_args() ); } public function onTransactionResolution( callable $callback, $fname = __METHOD__ ) { // DB_REPLICA role: caller might want to refresh cache after a REPEATABLE-READ snapshot return $this->__call( __FUNCTION__, func_get_args() ); } public function onTransactionCommitOrIdle( callable $callback, $fname = __METHOD__ ) { // DB_REPLICA role: caller might want to refresh cache after a REPEATABLE-READ snapshot return $this->__call( __FUNCTION__, func_get_args() ); } public function onTransactionPreCommitOrIdle( callable $callback, $fname = __METHOD__ ) { // DB_REPLICA role: caller might want to refresh cache after a cache mutex is released return $this->__call( __FUNCTION__, func_get_args() ); } public function onAtomicSectionCancel( callable $callback, $fname = __METHOD__ ) { return $this->__call( __FUNCTION__, func_get_args() ); } public function setTransactionListener( $name, ?callable $callback = null ) { return $this->__call( __FUNCTION__, func_get_args() ); } public function startAtomic( $fname = __METHOD__, $cancelable = IDatabase::ATOMIC_NOT_CANCELABLE ) { // Don't call assertRoleAllowsWrites(); caller might want a REPEATABLE-READ snapshot return $this->__call( __FUNCTION__, func_get_args() ); } public function endAtomic( $fname = __METHOD__ ) { // Don't call assertRoleAllowsWrites(); caller might want a REPEATABLE-READ snapshot return $this->__call( __FUNCTION__, func_get_args() ); } public function cancelAtomic( $fname = __METHOD__, ?AtomicSectionIdentifier $sectionId = null ) { // Don't call assertRoleAllowsWrites(); caller might want a REPEATABLE-READ snapshot return $this->__call( __FUNCTION__, func_get_args() ); } public function doAtomicSection( $fname, callable $callback, $cancelable = self::ATOMIC_NOT_CANCELABLE ) { // Don't call assertRoleAllowsWrites(); caller might want a REPEATABLE-READ snapshot return $this->__call( __FUNCTION__, func_get_args() ); } public function begin( $fname = __METHOD__, $mode = IDatabase::TRANSACTION_EXPLICIT ) { return $this->__call( __FUNCTION__, func_get_args() ); } public function commit( $fname = __METHOD__, $flush = self::FLUSHING_ONE ) { return $this->__call( __FUNCTION__, func_get_args() ); } public function rollback( $fname = __METHOD__, $flush = self::FLUSHING_ONE ) { return $this->__call( __FUNCTION__, func_get_args() ); } public function flushSession( $fname = __METHOD__, $flush = self::FLUSHING_ONE ) { return $this->__call( __FUNCTION__, func_get_args() ); } public function flushSnapshot( $fname = __METHOD__, $flush = self::FLUSHING_ONE ) { return $this->__call( __FUNCTION__, func_get_args() ); } public function timestamp( $ts = 0 ) { return $this->__call( __FUNCTION__, func_get_args() ); } public function timestampOrNull( $ts = null ) { return $this->__call( __FUNCTION__, func_get_args() ); } public function ping( &$rtt = null ) { return func_num_args() ? $this->__call( __FUNCTION__, [ &$rtt ] ) : $this->__call( __FUNCTION__, [] ); // method cares about null vs missing } public function getLag() { return $this->__call( __FUNCTION__, func_get_args() ); } public function getSessionLagStatus() { return $this->__call( __FUNCTION__, func_get_args() ); } public function encodeBlob( $b ) { return $this->__call( __FUNCTION__, func_get_args() ); } public function decodeBlob( $b ) { return $this->__call( __FUNCTION__, func_get_args() ); } public function setSessionOptions( array $options ) { $this->__call( __FUNCTION__, func_get_args() ); } public function setSchemaVars( $vars ) { return $this->__call( __FUNCTION__, func_get_args() ); } public function lockIsFree( $lockName, $method ) { $this->assertRoleAllowsWrites(); return $this->__call( __FUNCTION__, func_get_args() ); } public function lock( $lockName, $method, $timeout = 5, $flags = 0 ) { $this->assertRoleAllowsWrites(); return $this->__call( __FUNCTION__, func_get_args() ); } public function unlock( $lockName, $method ) { $this->assertRoleAllowsWrites(); return $this->__call( __FUNCTION__, func_get_args() ); } public function getScopedLockAndFlush( $lockKey, $fname, $timeout ) { $this->assertRoleAllowsWrites(); return $this->__call( __FUNCTION__, func_get_args() ); } public function getInfinity() { return $this->__call( __FUNCTION__, func_get_args() ); } public function encodeExpiry( $expiry ) { return $this->__call( __FUNCTION__, func_get_args() ); } public function decodeExpiry( $expiry, $format = TS_MW ) { return $this->__call( __FUNCTION__, func_get_args() ); } public function isReadOnly() { return $this->__call( __FUNCTION__, func_get_args() ); } public function setTableAliases( array $aliases ) { return $this->__call( __FUNCTION__, func_get_args() ); } public function getTableAliases() { return $this->__call( __FUNCTION__, func_get_args() ); } public function setIndexAliases( array $aliases ) { return $this->__call( __FUNCTION__, func_get_args() ); } public function tableName( $name, $format = 'quoted' ) { return $this->__call( __FUNCTION__, func_get_args() ); } public function tableNames( ...$tables ) { return $this->__call( __FUNCTION__, func_get_args() ); } public function tableNamesN( ...$tables ) { return $this->__call( __FUNCTION__, func_get_args() ); } public function sourceFile( $filename, ?callable $lineCallback = null, ?callable $resultCallback = null, $fname = false, ?callable $inputCallback = null ) { $this->assertRoleAllowsWrites(); return $this->__call( __FUNCTION__, func_get_args() ); } public function sourceStream( $fp, ?callable $lineCallback = null, ?callable $resultCallback = null, $fname = __METHOD__, ?callable $inputCallback = null ) { $this->assertRoleAllowsWrites(); return $this->__call( __FUNCTION__, func_get_args() ); } public function dropTable( $table, $fname = __METHOD__ ) { $this->assertRoleAllowsWrites(); return $this->__call( __FUNCTION__, func_get_args() ); } public function truncateTable( $table, $fname = __METHOD__ ) { $this->assertRoleAllowsWrites(); return $this->__call( __FUNCTION__, func_get_args() ); } public function streamStatementEnd( &$sql, &$newLine ) { return $this->__call( __FUNCTION__, [ &$sql, &$newLine ] ); } public function duplicateTableStructure( $oldName, $newName, $temporary = false, $fname = __METHOD__ ) { $this->assertRoleAllowsWrites(); return $this->__call( __FUNCTION__, func_get_args() ); } public function indexUnique( $table, $index, $fname = __METHOD__ ) { return $this->__call( __FUNCTION__, func_get_args() ); } public function listTables( $prefix = null, $fname = __METHOD__ ) { return $this->__call( __FUNCTION__, func_get_args() ); } public function fieldInfo( $table, $field ) { return $this->__call( __FUNCTION__, func_get_args() ); } public function __toString() { if ( $this->conn === null ) { return $this->getType() . ' object #' . spl_object_id( $this ); } return $this->__call( __FUNCTION__, func_get_args() ); } /** * Error out if the role is not DB_PRIMARY * * Note that the underlying connection may or may not itself be read-only. * It could even be to a writable primary (both server-side and to the application). * This error is meant for the case when a DB_REPLICA handle was requested but a * a write was attempted on that handle regardless. * * In configurations where the primary DB has some generic read load or is the only server, * DB_PRIMARY/DB_REPLICA will sometimes (or always) use the same connection to the primary DB. * This does not effect the role of DBConnRef instances. * @throws DBReadOnlyRoleError */ protected function assertRoleAllowsWrites() { // DB_PRIMARY is "prima facie" writable if ( $this->role !== ILoadBalancer::DB_PRIMARY ) { throw new DBReadOnlyRoleError( $this->conn, "Cannot write with role DB_REPLICA" ); } } /** * @return DBUnexpectedError */ protected function getDomainChangeException() { return new DBUnexpectedError( $this, "Cannot directly change the selected DB domain; any underlying connection handle " . "is owned by a LoadBalancer instance and possibly shared with other callers. " . "LoadBalancer automatically manages DB domain re-selection of unused handles." ); } /** * @param int $i Specific or virtual (DB_PRIMARY/DB_REPLICA) server index * @return int|mixed */ protected function normalizeServerIndex( $i ) { return ( $i === ILoadBalancer::DB_PRIMARY ) ? ServerInfo::WRITER_INDEX : $i; } } PK ! t[�@. . rdbms/database/Query.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\Rdbms; use Wikimedia\Rdbms\Platform\SQLPlatform; /** * Holds information on Query to be executed * * @ingroup Database * @internal * @since 1.41 */ class Query { /** * The possible multi-word values for getVerb(). * @internal For use by Query and QueryBuilderFromRawSQL only. */ public const MULTIWORD_VERBS = [ 'RELEASE SAVEPOINT', 'ROLLBACK TO SAVEPOINT', 'CREATE TEMPORARY', 'CREATE INDEX', 'DROP INDEX', 'CREATE DATABASE', 'ALTER DATABASE', 'DROP DATABASE', ]; private string $sql; private int $flags; private string $queryVerb; private ?string $writeTable; private string $cleanedSql; /** * @param string $sql SQL statement text * @param int $flags Bit field of ISQLPlatform::QUERY_CHANGE_* constants * @param string $queryVerb The first words of the SQL statement that convey what kind of * database/table/column/index command was specified. Except for the cases listed in * {@see MULTIWORD_VERBS}, this will be the first word of the SQL statement. * @param string|null $writeTable The table targeted for writes, if any. Can be omitted if * it would be hard to identify the table (e.g. when parsing an arbitrary SQL string). * @param string $cleanedSql Sanitized/simplified SQL statement text for logging. * Typically, this means replacing variables / parameter values with placeholders. * Can be omitted, in which case the code using the Query is responsible for sanitizing. */ public function __construct( string $sql, $flags, $queryVerb, ?string $writeTable = null, $cleanedSql = '' ) { $this->sql = $sql; $this->flags = $flags; $this->queryVerb = $queryVerb; $this->writeTable = $writeTable; $this->cleanedSql = substr( $cleanedSql, 0, 255 ); } public function isWriteQuery(): bool { // Check if a SQL wrapper method already flagged the query as a non-write if ( $this->fieldHasBit( $this->flags, SQLPlatform::QUERY_CHANGE_NONE ) || $this->fieldHasBit( $this->flags, SQLPlatform::QUERY_CHANGE_TRX ) || $this->fieldHasBit( $this->flags, SQLPlatform::QUERY_CHANGE_LOCKS ) ) { return false; } // Check if a SQL wrapper method already flagged the query as a write if ( $this->fieldHasBit( $this->flags, SQLPlatform::QUERY_CHANGE_ROWS ) || $this->fieldHasBit( $this->flags, SQLPlatform::QUERY_CHANGE_SCHEMA ) || $this->fieldHasBit( $this->flags, SQLPlatform::QUERY_PSEUDO_PERMANENT ) ) { return true; } throw new DBLanguageError( __METHOD__ . ' called with incorrect flags parameter' ); } public function getVerb(): string { return $this->queryVerb; } private function fieldHasBit( int $flags, int $bit ): bool { return ( ( $flags & $bit ) === $bit ); } public function getSQL(): string { return $this->sql; } public function getFlags(): int { // The whole concept of flags is terrible. This should be deprecated. return $this->flags; } /** * Get the table which is being written to, or null for a read query or if * the destination is unknown. */ public function getWriteTable(): ?string { return $this->writeTable; } /** * Get the cleaned/sanitized SQL statement text for logging. * Might return an empty string, which means sanitization is the caller's responsibility. */ public function getCleanedSql(): string { return $this->cleanedSql; } } PK ! ��� $ rdbms/database/IDatabaseForOwner.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\Rdbms; /** * Internal interface for relational database handles exposed to their owner * * Instances are either owned by a LoadBalancer object or owned by the caller that created * the instance using a constructor/factory function such as DatabaseFactory::create(). * * @ingroup Database * @internal Only for use within the rdbms library */ interface IDatabaseForOwner extends IDatabase { /** * Run a callback after each time any transaction commits or rolls back * * The callback takes two arguments: * - IDatabase::TRIGGER_COMMIT or IDatabase::TRIGGER_ROLLBACK * - This IDatabase object * Callbacks must commit any transactions that they begin. * * Registering a callback here will not affect writesOrCallbacks() pending. * * Since callbacks from this or onTransactionCommitOrIdle() can start and end transactions, * a single call to IDatabase::commit might trigger multiple runs of the listener callbacks. * * @param string $name Callback name * @param callable|null $callback Use null to unset a listener * @since 1.28 */ public function setTransactionListener( $name, ?callable $callback = null ); /** * @return bool Whether this DB server is running in server-side read-only mode * @throws DBError If an error occurs, {@see query} * @since 1.28 */ public function serverIsReadOnly(); /** * Get the replication position of this primary DB server * * @return DBPrimaryPos|false Position; false if this is not a primary DB * @throws DBError If an error occurs, {@see query} * @since 1.37 */ public function getPrimaryPos(); /** * Get the time spend running write queries for this transaction * * High values could be due to scanning, updates, locking, and such. * * @param string $type IDatabase::ESTIMATE_* constant [default: ESTIMATE_ALL] * @return float|false Returns false if not transaction is active * @since 1.26 */ public function pendingWriteQueryDuration( $type = self::ESTIMATE_TOTAL ); /** * Whether there is a transaction open with either possible write queries * or unresolved pre-commit/commit/resolution callbacks pending * * This does *not* count recurring callbacks, e.g. from setTransactionListener(). * * @return bool */ public function writesOrCallbacksPending(); /** * @return bool Whether there is a transaction open with possible write queries * @since 1.27 */ public function writesPending(); /** * Get the list of method names that did write queries for this transaction * * @return array * @since 1.27 */ public function pendingWriteCallers(); /** * Release important session-level state (named lock, table locks) as post-rollback cleanup * * This should only be called by a load balancer or if the handle is not attached to one. * Also, there must be no chance that a future caller will still be expecting some of the * lost session state. * * Connection and query errors will be suppressed and logged * * @param string $fname Calling function name @phan-mandatory-param * @param string $flush Flush flag, set to a situationally valid IDatabase::FLUSHING_* * constant to disable warnings about explicitly rolling back implicit transactions. * This will silently break any ongoing explicit transaction. Only set the flush flag * if you are sure that it is safe to ignore these warnings in your context. * @throws DBError If an error occurs, {@see query} * @since 1.38 */ public function flushSession( $fname = __METHOD__, $flush = self::FLUSHING_ONE ); /** * Get the last time the connection may have been used for a write query * * @return int|float|false UNIX timestamp or false * @since 1.24 */ public function lastDoneWrites(); /** * Set the entire array or a particular key of the managing load balancer info array * * Keys matching the IDatabase::LB_* constants are also used internally by subclasses * * @internal should not be called outside of rdbms library. * * @param array|string $nameOrArray The new array or the name of a key to set * @param array|mixed|null $value If $nameOrArray is a string, the new key value (null to unset) */ public function setLBInfo( $nameOrArray, $value = null ); /** * Wait for the replica server to catch up to a given primary server position * * Note that this does not start any new transactions. * * Callers might want to flush any existing transaction before invoking this method. * Upon success, this assures that replica server queries will reflect all changes up * to the given position, without interference from prior REPEATABLE-READ snapshots. * * @param DBPrimaryPos $pos * @param int $timeout The maximum number of seconds to wait for synchronisation * @return int|null Zero if the replica DB server was past that position already, * greater than zero if we waited for some period of time, less than * zero if it timed out, and null on error * @throws DBError If an error occurs, {@see query} * @since 1.37 */ public function primaryPosWait( DBPrimaryPos $pos, $timeout ); } PK ! ���D D rdbms/TransactionProfiler.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\Rdbms; use Psr\Log\LoggerAwareInterface; use Psr\Log\LoggerInterface; use Psr\Log\NullLogger; use RuntimeException; use Wikimedia\ScopedCallback; use Wikimedia\Stats\StatsFactory; /** * Detect high-contention DB queries via profiling calls. * * This class is meant to work with an IDatabase object, which manages queries. * * @internal For use by Database only * @since 1.24 * @ingroup Profiler * @ingroup Database */ class TransactionProfiler implements LoggerAwareInterface { /** @var LoggerInterface */ private $logger; /** @var StatsFactory */ private $statsFactory; /** @var array<string,array> Map of (event name => map of FLD_* class constants) */ private $expect; /** @var array<string,int> Map of (event name => current hits) */ private $hits; /** @var array<string,int> Map of (event name => violation counter) */ private $violations; /** @var array<string,int> Map of (event name => silence counter) */ private $silenced; /** * @var array<string,array> Map of (trx ID => (write start time, list of DBs involved)) * @phan-var array<string,array{start:float,conns:array<string,int>}> */ private $dbTrxHoldingLocks; /** * @var array[][] Map of (trx ID => list of (query name, start time, end time)) * @phan-var array<string,array<int,array{0:string,1:float,2:float}>> */ private $dbTrxMethodTimes; /** @var string|null HTTP request method; null for CLI mode */ private $method; /** @var float|null */ private $wallClockOverride; /** Treat locks as long-running if they last longer than this many seconds */ private const DB_LOCK_THRESHOLD_SEC = 3.0; /** Include events in any violation logs if they last longer than this many seconds */ private const EVENT_THRESHOLD_SEC = 0.25; /** List of event names */ private const EVENT_NAMES = [ 'writes', 'queries', 'conns', 'masterConns', 'maxAffected', 'readQueryRows', 'readQueryTime', 'writeQueryTime' ]; /** List of event names with hit counters */ private const COUNTER_EVENT_NAMES = [ 'writes', 'queries', 'conns', 'masterConns' ]; /** Key to max expected value */ private const FLD_LIMIT = 0; /** Key to the function that set the max expected value */ private const FLD_FNAME = 1; /** Any type of expectation */ public const EXPECTATION_ANY = 'any'; /** Any expectations about replica usage never occurring */ public const EXPECTATION_REPLICAS_ONLY = 'replicas-only'; public function __construct() { $this->initPlaceholderExpectations(); $this->dbTrxHoldingLocks = []; $this->dbTrxMethodTimes = []; $this->silenced = array_fill_keys( self::EVENT_NAMES, 0 ); $this->setLogger( new NullLogger() ); $this->statsFactory = StatsFactory::newNull(); } public function setLogger( LoggerInterface $logger ) { $this->logger = $logger; } /** * Set statsFactory * * @param StatsFactory $statsFactory * @return void */ public function setStatsFactory( StatsFactory $statsFactory ) { $this->statsFactory = $statsFactory; } /** * @param ?string $method HTTP method; null for CLI mode * @return void */ public function setRequestMethod( ?string $method ) { $this->method = $method; } /** * Temporarily ignore expectations until the returned object goes out of scope * * During this time, violation of expectations will not be logged and counters * for expectations (e.g. "conns") will not be incremented. * * This will suppress warnings about event counters which have a limit of zero. * The main use case is too avoid warnings about primary connections/writes and * warnings about getting any primary/replica connections at all. * * @param string $type Class EXPECTATION_* constant [default: TransactionProfiler::EXPECTATION_ANY] * @return ScopedCallback */ public function silenceForScope( string $type = self::EXPECTATION_ANY ) { if ( $type === self::EXPECTATION_REPLICAS_ONLY ) { $events = []; foreach ( [ 'writes', 'masterConns' ] as $event ) { if ( $this->expect[$event][self::FLD_LIMIT] === 0 ) { $events[] = $event; } } } else { $events = self::EVENT_NAMES; } foreach ( $events as $event ) { ++$this->silenced[$event]; } return new ScopedCallback( function () use ( $events ) { foreach ( $events as $event ) { --$this->silenced[$event]; } } ); } /** * Set performance expectations * * With conflicting expectations, the most narrow ones will be used * * @param string $event Event name, {@see self::EVENT_NAMES} * @param float|int $limit Maximum event count, event value, or total event value * @param string $fname Caller * @since 1.25 */ public function setExpectation( string $event, $limit, string $fname ) { if ( !isset( $this->expect[$event] ) ) { return; // obsolete/bogus expectation } if ( $limit <= $this->expect[$event][self::FLD_LIMIT] ) { // New limit is more restrictive $this->expect[$event] = [ self::FLD_LIMIT => $limit, self::FLD_FNAME => $fname ]; } } /** * Set one or multiple performance expectations * * With conflicting expectations, the most narrow ones will be used * * Use this to initialize expectations or make them stricter mid-request * * @param array $expects Map of (event name => limit), {@see self::EVENT_NAMES} * @param string $fname * @since 1.26 */ public function setExpectations( array $expects, string $fname ) { foreach ( $expects as $event => $value ) { $this->setExpectation( $event, $value, $fname ); } } /** * Reset all performance expectations and hit counters * * Use this for unit testing or before applying a totally different set of expectations * for a different part of the request, such as during "post-send" (execution after HTTP * response completion) * * @since 1.25 */ public function resetExpectations() { $this->initPlaceholderExpectations(); } /** * Clear all expectations and hit counters and set new performance expectations * * Use this to apply a totally different set of expectations for a different part * of the request, such as during "post-send" (execution after HTTP response completion) * * @param array $expects Map of (event name => limit), {@see self::EVENT_NAMES} * @param string $fname * @since 1.33 */ public function redefineExpectations( array $expects, string $fname ) { $this->initPlaceholderExpectations(); $this->setExpectations( $expects, $fname ); } /** * Mark a DB as having been connected to with a new handle * * Note that there can be multiple connections to a single DB. * * @param string $server DB server * @param string|null $db DB name * @param bool $isPrimaryWithReplicas If the server is the primary and there are replicas */ public function recordConnection( $server, $db, bool $isPrimaryWithReplicas ) { // Report when too many connections happen... if ( $this->pingAndCheckThreshold( 'conns' ) ) { $this->reportExpectationViolated( 'conns', "[connect to $server ($db)]", $this->hits['conns'] ); } // Report when too many primary connections happen... if ( $isPrimaryWithReplicas && $this->pingAndCheckThreshold( 'masterConns' ) ) { $this->reportExpectationViolated( 'masterConns', "[connect to $server ($db)]", $this->hits['masterConns'] ); } } /** * Mark a DB as in a transaction with one or more writes pending * * Note that there can be multiple connections to a single DB. * * @param string $server DB server * @param string|null $db DB name * @param string $id ID string of transaction * @param float $startTime UNIX timestamp */ public function transactionWritingIn( $server, $db, string $id, float $startTime ) { $name = "{$db} {$server} TRX#$id"; if ( isset( $this->dbTrxHoldingLocks[$name] ) ) { $this->logger->warning( "Nested transaction for '$name' - out of sync." ); } $this->dbTrxHoldingLocks[$name] = [ 'start' => $startTime, 'conns' => [], // all connections involved ]; $this->dbTrxMethodTimes[$name] = []; foreach ( $this->dbTrxHoldingLocks as $name => &$info ) { // Track all DBs in transactions for this transaction $info['conns'][$name] = 1; } } /** * Register the name and time of a method for slow DB trx detection * * This assumes that all queries are synchronous (non-overlapping) * * @param string|GeneralizedSql|Query $query Function name or generalized SQL * @param float $sTime Starting UNIX wall time * @param bool $isWrite Whether this is a write query * @param int|null $rowCount Number of affected/read rows * @param string $trxId Transaction id * @param string|null $serverName db host name like db1234 */ public function recordQueryCompletion( $query, float $sTime, bool $isWrite, ?int $rowCount, string $trxId, ?string $serverName = null ) { $eTime = $this->getCurrentTime(); $elapsed = ( $eTime - $sTime ); if ( $isWrite && $this->isAboveThreshold( $rowCount, 'maxAffected' ) ) { $this->reportExpectationViolated( 'maxAffected', $query, $rowCount, $trxId, $serverName ); } elseif ( !$isWrite && $this->isAboveThreshold( $rowCount, 'readQueryRows' ) ) { $this->reportExpectationViolated( 'readQueryRows', $query, $rowCount, $trxId, $serverName ); } // Report when too many writes/queries happen... if ( $this->pingAndCheckThreshold( 'queries' ) ) { $this->reportExpectationViolated( 'queries', $query, $this->hits['queries'], $trxId, $serverName ); } if ( $isWrite && $this->pingAndCheckThreshold( 'writes' ) ) { $this->reportExpectationViolated( 'writes', $query, $this->hits['writes'], $trxId, $serverName ); } // Report slow queries... if ( !$isWrite && $this->isAboveThreshold( $elapsed, 'readQueryTime' ) ) { $this->reportExpectationViolated( 'readQueryTime', $query, $elapsed, $trxId, $serverName ); } if ( $isWrite && $this->isAboveThreshold( $elapsed, 'writeQueryTime' ) ) { $this->reportExpectationViolated( 'writeQueryTime', $query, $elapsed, $trxId, $serverName ); } if ( !$this->dbTrxHoldingLocks ) { // Short-circuit return; } elseif ( !$isWrite && $elapsed < self::EVENT_THRESHOLD_SEC ) { // Not an important query nor slow enough return; } foreach ( $this->dbTrxHoldingLocks as $name => $info ) { $lastQuery = end( $this->dbTrxMethodTimes[$name] ); if ( $lastQuery ) { // Additional query in the trx... $lastEnd = $lastQuery[2]; if ( $sTime >= $lastEnd ) { if ( ( $sTime - $lastEnd ) > self::EVENT_THRESHOLD_SEC ) { // Add an entry representing the time spent doing non-queries $this->dbTrxMethodTimes[$name][] = [ '...delay...', $lastEnd, $sTime ]; } $this->dbTrxMethodTimes[$name][] = [ $query, $sTime, $eTime ]; } } else { // First query in the trx... if ( $sTime >= $info['start'] ) { $this->dbTrxMethodTimes[$name][] = [ $query, $sTime, $eTime ]; } } } } /** * Mark a DB as no longer in a transaction * * This will check if locks are possibly held for longer than * needed and log any affected transactions to a special DB log. * Note that there can be multiple connections to a single DB. * * @param string $server DB server * @param string|null $db DB name * @param string $id ID string of transaction * @param float $writeTime Time spent in write queries * @param int $affected Number of rows affected by writes */ public function transactionWritingOut( $server, $db, string $id, float $writeTime, int $affected ) { // Must match $name in transactionWritingIn() $name = "{$db} {$server} TRX#$id"; if ( !isset( $this->dbTrxMethodTimes[$name] ) ) { $this->logger->warning( "Detected no transaction for '$name' - out of sync." ); return; } $slow = false; // Warn if too much time was spend writing... if ( $this->isAboveThreshold( $writeTime, 'writeQueryTime' ) ) { $this->reportExpectationViolated( 'writeQueryTime', "[transaction writes to {$db} at {$server}]", $writeTime, $id ); $slow = true; } // Warn if too many rows were changed... if ( $this->isAboveThreshold( $affected, 'maxAffected' ) ) { $this->reportExpectationViolated( 'maxAffected', "[transaction writes to {$db} at {$server}]", $affected, $id ); } // Fill in the last non-query period... $lastQuery = end( $this->dbTrxMethodTimes[$name] ); if ( $lastQuery ) { $now = $this->getCurrentTime(); $lastEnd = $lastQuery[2]; if ( ( $now - $lastEnd ) > self::EVENT_THRESHOLD_SEC ) { $this->dbTrxMethodTimes[$name][] = [ '...delay...', $lastEnd, $now ]; } } // Check for any slow queries or non-query periods... foreach ( $this->dbTrxMethodTimes[$name] as $info ) { $elapsed = ( $info[2] - $info[1] ); if ( $elapsed >= self::DB_LOCK_THRESHOLD_SEC ) { $slow = true; break; } } if ( $slow ) { $trace = ''; foreach ( $this->dbTrxMethodTimes[$name] as $i => [ $query, $sTime, $end ] ) { $trace .= sprintf( "%-2d %.3fs %s\n", $i, ( $end - $sTime ), $this->getGeneralizedSql( $query ) ); } $this->logger->warning( "Suboptimal transaction [{dbs}]:\n{trace}", [ 'dbs' => implode( ', ', array_keys( $this->dbTrxHoldingLocks[$name]['conns'] ) ), 'trace' => mb_substr( $trace, 0, 2000 ) ] ); } unset( $this->dbTrxHoldingLocks[$name] ); unset( $this->dbTrxMethodTimes[$name] ); } private function initPlaceholderExpectations() { $this->expect = array_fill_keys( self::EVENT_NAMES, [ self::FLD_LIMIT => INF, self::FLD_FNAME => null ] ); $this->hits = array_fill_keys( self::COUNTER_EVENT_NAMES, 0 ); $this->violations = array_fill_keys( self::EVENT_NAMES, 0 ); } /** * @param float|int $value * @param string $event * @return bool */ private function isAboveThreshold( $value, string $event ) { if ( $this->silenced[$event] > 0 ) { return false; } return ( $value > $this->expect[$event][self::FLD_LIMIT] ); } /** * @param string $event * @return bool */ private function pingAndCheckThreshold( string $event ) { if ( $this->silenced[$event] > 0 ) { return false; } $newValue = ++$this->hits[$event]; $limit = $this->expect[$event][self::FLD_LIMIT]; return ( $newValue > $limit ); } /** * @param string $event * @param string|GeneralizedSql|Query $query * @param float|int $actual * @param string|null $trxId Transaction id * @param string|null $serverName db host name like db1234 */ private function reportExpectationViolated( $event, $query, $actual, ?string $trxId = null, ?string $serverName = null ) { $violations = ++$this->violations[$event]; // First violation; check if this is a web request if ( $violations === 1 && $this->method !== null ) { $this->statsFactory->getCounter( 'rdbms_trxprofiler_warnings_total' ) ->setLabel( 'event', $event ) ->setLabel( 'method', $this->method ) ->copyToStatsdAt( "rdbms_trxprofiler_warnings.$event.{$this->method}" ) ->increment(); } $max = $this->expect[$event][self::FLD_LIMIT]; $by = $this->expect[$event][self::FLD_FNAME]; $message = "Expectation ($event <= $max) by $by not met (actual: {actualSeconds})"; if ( $trxId ) { $message .= ' in trx #{trxId}'; } $message .= ":\n{query}\n"; $this->logger->warning( $message, [ 'db_log_category' => 'performance', 'measure' => $event, 'maxSeconds' => $max, 'by' => $by, 'actualSeconds' => $actual, 'query' => $this->getGeneralizedSql( $query ), 'exception' => new RuntimeException(), 'trxId' => $trxId, // Avoid truncated JSON in Logstash (T349140) 'fullQuery' => mb_substr( $this->getRawSql( $query ), 0, 2000 ), 'dbHost' => $serverName ] ); } /** * @param GeneralizedSql|string|Query $query * @return string */ private function getGeneralizedSql( $query ) { if ( $query instanceof Query ) { return $query->getCleanedSql(); } return $query instanceof GeneralizedSql ? $query->stringify() : $query; } /** * @param GeneralizedSql|string|Query $query * @return string */ private function getRawSql( $query ) { if ( $query instanceof Query ) { return $query->getSQL(); } return $query instanceof GeneralizedSql ? $query->getRawSql() : $query; } /** * @return float UNIX timestamp * @codeCoverageIgnore */ private function getCurrentTime() { return $this->wallClockOverride ?: microtime( true ); } /** * @param float|null &$time Mock UNIX timestamp for testing * @codeCoverageIgnore */ public function setMockTime( &$time ) { $this->wallClockOverride =& $time; } } PK ! �jؼ� � rdbms/DBAccessObjectUtils.phpnu �Iw�� <?php /** * This file contains database access object related constants. * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file * @ingroup Database */ namespace Wikimedia\Rdbms; use InvalidArgumentException; /** * Helper class for DAO classes * * @since 1.26 */ class DBAccessObjectUtils implements IDBAccessObject { /** * @param int $bitfield * @param int $flags IDBAccessObject::READ_* constant * @return bool Bitfield has flag $flag set */ public static function hasFlags( $bitfield, $flags ) { return ( $bitfield & $flags ) == $flags; } /** * Get an appropriate DB index and options * * @deprecated since 1.43 * @param int $bitfield Bitfield of IDBAccessObject::READ_* constants * @return array List of DB indexes and options in this order: * - DB_PRIMARY or DB_REPLICA constant for the initial query * - SELECT options array for the initial query */ public static function getDBOptions( $bitfield ) { wfDeprecated( __METHOD__, '1.43' ); if ( self::hasFlags( $bitfield, IDBAccessObject::READ_LATEST_IMMUTABLE ) ) { $index = DB_REPLICA; // override READ_LATEST if set } elseif ( self::hasFlags( $bitfield, IDBAccessObject::READ_LATEST ) ) { $index = DB_PRIMARY; } else { $index = DB_REPLICA; } $lockingOptions = []; if ( self::hasFlags( $bitfield, IDBAccessObject::READ_EXCLUSIVE ) ) { $lockingOptions[] = 'FOR UPDATE'; } elseif ( self::hasFlags( $bitfield, IDBAccessObject::READ_LOCKING ) ) { $lockingOptions[] = 'LOCK IN SHARE MODE'; } return [ $index, $lockingOptions ]; } /** * Takes $index from ::getDBOptions() and return proper Database object * * @deprecated since 1.42 * * @param IConnectionProvider $dbProvider * @param int $index either DB_REPLICA or DB_PRIMARY * @return IReadableDatabase */ public static function getDBFromIndex( IConnectionProvider $dbProvider, int $index ): IReadableDatabase { wfDeprecated( __METHOD__, '1.42' ); if ( $index === DB_PRIMARY ) { return $dbProvider->getPrimaryDatabase(); } elseif ( $index === DB_REPLICA ) { return $dbProvider->getReplicaDatabase(); } else { throw new InvalidArgumentException( '$index must be either DB_REPLICA or DB_PRIMARY' ); } } /** * @param IConnectionProvider $dbProvider * @param int $recency IDBAccessObject::READ_* constant * @return IReadableDatabase * @since 1.42 */ public static function getDBFromRecency( IConnectionProvider $dbProvider, int $recency ): IReadableDatabase { if ( self::hasFlags( $recency, IDBAccessObject::READ_LATEST ) ) { return $dbProvider->getPrimaryDatabase(); } return $dbProvider->getReplicaDatabase(); } } /** @deprecated class alias since 1.43 */ class_alias( DBAccessObjectUtils::class, 'DBAccessObjectUtils' ); PK ! ��xT�b �b rdbms/ChronologyProtector.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\Rdbms; use LogicException; use Psr\Log\LoggerAwareInterface; use Psr\Log\LoggerInterface; use Psr\Log\NullLogger; use Wikimedia\ObjectCache\BagOStuff; use Wikimedia\ObjectCache\EmptyBagOStuff; /** * Provide a given client with protection against visible database lag. * * ### In a nut shell * * This class tries to hide visible effects of database lag. It does this by temporarily remembering * the database positions after a client makes a write, and on their next web request we will prefer * non-lagged database replicas. When replica connections are established, we wait up to a few seconds * for sufficient replication to have occurred, if they were not yet caught up to that same point. * * This ensures a consistent ordering of events as seen by a client. Kind of like Hawking's * [Chronology Protection Agency](https://en.wikipedia.org/wiki/Chronology_protection_conjecture). * * ### Purpose * * For performance and scalability reasons, almost all data is queried from replica databases. * Only queries relating to writing data, are sent to a primary database. When rendering a web page * with content or activity feeds on it, the very latest information may thus not yet be there. * That's okay in general, but if, for example, a client recently changed their preferences or * submitted new data, we do our best to make sure their next web response does reflect at least * their own recent changes. * * ### How * * To explain how it works, we will look at an example lifecycle for a client. * * A client is browsing the site. Their web requests are generally read-only and display data from * database replicas, which may be a few seconds out of date if a client elsewhere in the world * recently modified that same data. If the application is run from multiple data centers, then * these web requests may be served from the nearest secondary DC. * * A client performs a POST request, perhaps to publish an edit or change their preferences. This * request is routed to the primary DC (this is the responsibility of infrastructure outside * the web app). There, the data is saved to the primary database, after which the database * host will asynchronously replicate this to its replicas in the same and any other DCs. * * Toward the end of the response to this POST request, the application takes note of the primary * database's current "position", and save this under a "clientId" key in the ChronologyProtector * store. The web response will also set two cookies that are similarly short-lived (about ten * seconds): `UseDC=master` and `cpPosIndex=<posIndex>@<write time>#<clientId>`. * * The ten seconds window is meant to account for the time needed for the database writes to have * replicated across all active database replicas, including the cross-dc latency for those * further away in any secondary DCs. The "clientId" is placed in the cookie to handle the case * where the client IP addresses frequently changes between web requests. * * Future web requests from the client should fall in one of two categories: * * 1. Within the ten second window. Their UseDC cookie will make them return * to the primary DC where we access the ChronologyProtector store and use * the database "position" to decide which local database replica to use * and on-demand wait a split second for replication to catch up if needed. * 2. After the ten second window. They will be routed to the nearest and * possibly different DC. Any local ChronologyProtector store existing there * will not be interacted with. A random database replica may be used as * the client's own writes are expected to have been applied here by now. * * @anchor ChronologyProtector-storage-requirements * * ### Storage requirements * * The store used by ChronologyProtector, as configured via {@link $wgMicroStashType}, * should meet the following requirements: * * - Low latencies. Nearly all web requests that involve a database connection will * unconditionally query this store first. It is expected to respond within the order * of one millisecond. * - Best effort persistence, without active eviction pressure. Data stored here cannot be * obtained elsewhere or recomputed. As such, under normal operating conditions, this store * should not be full, and should not evict values before their intended expiry time elapsed. * - No replication, local consistency. Each DC may have a fully independent dc-local store * associated with ChronologyProtector (no replication across DCs is needed). Local writes * must be immediately reflected in subsequent local reads. No intra-dc read lag is allowed. * - No redundancy, fast failure. Loss of data will likely be noticeable and disruptive to * clients, but the data is not considered essential. Under maintenance or unprecedented load, * it is recommended to lose some data, instead of compromising other requirements such as * latency or availability for new writes. The fallback is that users may be temporary * confused as they observe their own actions as not being immediately reflected. * For example, they might change their skin or language preference but still get a one or two * page views afterward with the old settings. Or they might have published an edit and briefly * not yet see it appear in their contribution history. * * ### Operational requirements * * These are the expectations a site administrator must meet for chronology protection: * * - If the application is run from multiple data centers, then you must designate one of them * as the "primary DC". The primary DC is where the primary database is located, from which * replication propagates to replica databases in that same DC and any other DCs. * * - Web requests that use the POST verb, or carry a `UseDC=master` cookie, must be routed to * the primary DC only. * * An exception is requests carrying the `Promise-Non-Write-API-Action: true` header, * which use the POST verb for large read queries, but don't actually require the primary DC. * * If you have legacy extensions deployed that perform queries on the primary database during * GET requests, then you will have to identify a way to route any of its relevant URLs to the * primary DC as well, or to accept that their reads do not enjoy chronology protection, and * that writes may be slower (due to cross-dc latency). * See [T91820](https://phabricator.wikimedia.org/T91820) for %Wikimedia Foundation's routing. * * @ingroup Database * @internal */ class ChronologyProtector implements LoggerAwareInterface { /** @var array Web request information about the client */ private $requestInfo; /** @var string Secret string for HMAC hashing */ private string $secret; private bool $cliMode; /** @var BagOStuff */ private $store; /** @var LoggerInterface */ protected $logger; /** @var string Storage key name */ protected $key; /** @var string Hash of client parameters */ protected $clientId; /** @var string[] Map of client information fields for logging */ protected $clientLogInfo; /** @var int|null Expected minimum index of the last write to the position store */ protected $waitForPosIndex; /** @var bool Whether reading/writing session consistency replication positions is enabled */ protected $enabled = true; /** @var float|null UNIX timestamp when the client data was loaded */ protected $startupTimestamp; /** @var array<string,DBPrimaryPos> Map of (primary server name => position) */ protected $startupPositionsByPrimary = []; /** @var array<string,DBPrimaryPos> Map of (primary server name => position) */ protected $shutdownPositionsByPrimary = []; /** @var array<string,float> Map of (DB cluster name => UNIX timestamp) */ protected $startupTimestampsByCluster = []; /** @var array<string,float> Map of (DB cluster name => UNIX timestamp) */ protected $shutdownTimestampsByCluster = []; /** @var float|null */ private $wallClockOverride; /** * Whether a clientId is new during this request. * * If the clientId wasn't passed by the incoming request, lazyStartup() * can skip fetching position data, and thus LoadBalancer can skip * its IDatabaseForOwner::primaryPosWait() call. * * See also: <https://phabricator.wikimedia.org/T314434> * * @var bool */ private $hasNewClientId = false; /** Seconds to store position write index cookies (safely less than POSITION_STORE_TTL) */ public const POSITION_COOKIE_TTL = 10; /** Seconds to store replication positions */ private const POSITION_STORE_TTL = 60; /** Lock timeout to use for key updates */ private const LOCK_TIMEOUT = 3; /** Lock expiry to use for key updates */ private const LOCK_TTL = 6; private const FLD_POSITIONS = 'positions'; private const FLD_TIMESTAMPS = 'timestamps'; private const FLD_WRITE_INDEX = 'writeIndex'; /** * @param BagOStuff|null $cpStash * @param string|null $secret Secret string for HMAC hashing [optional] * @param bool|null $cliMode Whether the context is CLI or not, setting it to true would disable CP * @param LoggerInterface|null $logger * @since 1.27 */ public function __construct( $cpStash = null, $secret = null, $cliMode = null, $logger = null ) { $this->requestInfo = [ 'IPAddress' => $_SERVER['REMOTE_ADDR'] ?? '', 'UserAgent' => $_SERVER['HTTP_USER_AGENT'] ?? '', // Headers application can inject via LBFactory::setRequestInfo() 'ChronologyClientId' => null, // prior $cpClientId value from LBFactory::shutdown() 'ChronologyPositionIndex' => null // prior $cpIndex value from LBFactory::shutdown() ]; $this->store = $cpStash ?? new EmptyBagOStuff(); $this->secret = $secret ?? ''; $this->logger = $logger ?? new NullLogger(); $this->cliMode = $cliMode ?? ( PHP_SAPI === 'cli' || PHP_SAPI === 'phpdbg' ); } private function load() { // Not enabled or already loaded, short-circuit. if ( !$this->enabled || $this->clientId ) { return; } $client = [ 'ip' => $this->requestInfo['IPAddress'], 'agent' => $this->requestInfo['UserAgent'], 'clientId' => $this->requestInfo['ChronologyClientId'] ?: null ]; if ( $this->cliMode ) { $this->setEnabled( false ); } elseif ( $this->store instanceof EmptyBagOStuff ) { // No where to store any DB positions and wait for them to appear $this->setEnabled( false ); $this->logger->debug( 'Cannot use ChronologyProtector with EmptyBagOStuff' ); } if ( isset( $client['clientId'] ) ) { $this->clientId = $client['clientId']; } else { $this->hasNewClientId = true; $this->clientId = ( $this->secret != '' ) ? hash_hmac( 'md5', $client['ip'] . "\n" . $client['agent'], $this->secret ) : md5( $client['ip'] . "\n" . $client['agent'] ); } $this->key = $this->store->makeGlobalKey( __CLASS__, $this->clientId, 'v4' ); $this->waitForPosIndex = $this->requestInfo['ChronologyPositionIndex']; $this->clientLogInfo = [ 'clientIP' => $client['ip'], 'clientAgent' => $client['agent'], 'clientId' => $client['clientId'] ?? null ]; } public function setRequestInfo( array $info ) { if ( $this->clientId ) { throw new LogicException( 'ChronologyProtector already initialized' ); } $this->requestInfo = $info + $this->requestInfo; } public function setLogger( LoggerInterface $logger ) { $this->load(); $this->logger = $logger; } /** * @return string Client ID hash * @since 1.32 */ public function getClientId() { $this->load(); return $this->clientId; } /** * @param bool $enabled Whether reading/writing session replication positions is enabled * @since 1.27 */ public function setEnabled( $enabled ) { $this->enabled = $enabled; } /** * Yield client "session consistency" replication position for a new ILoadBalancer * * If the stash has a previous primary position recorded, this will try to make * sure that the next query to a replica server of that primary will see changes up * to that position by delaying execution. The delay may timeout and allow stale * data if no non-lagged replica servers are available. * * @internal This method should only be called from LBFactory. * * @param ILoadBalancer $lb * @return DBPrimaryPos|null */ public function getSessionPrimaryPos( ILoadBalancer $lb ) { $this->load(); if ( !$this->enabled ) { return null; } $cluster = $lb->getClusterName(); $primaryName = $lb->getServerName( ServerInfo::WRITER_INDEX ); $pos = $this->getStartupSessionPositions()[$primaryName] ?? null; if ( $pos instanceof DBPrimaryPos ) { $this->logger->debug( "ChronologyProtector will wait for '$pos' on $cluster ($primaryName)'" ); } else { $this->logger->debug( "ChronologyProtector skips wait on $cluster ($primaryName)" ); } return $pos; } /** * Update client "session consistency" replication position for an end-of-life ILoadBalancer * * This remarks the replication position of the primary DB if this request made writes to * it using the provided ILoadBalancer instance. * * @internal This method should only be called from LBFactory. * * @param ILoadBalancer $lb * @return void */ public function stageSessionPrimaryPos( ILoadBalancer $lb ) { $this->load(); if ( !$this->enabled || !$lb->hasOrMadeRecentPrimaryChanges( INF ) ) { return; } $cluster = $lb->getClusterName(); $masterName = $lb->getServerName( ServerInfo::WRITER_INDEX ); if ( $lb->hasStreamingReplicaServers() ) { $pos = $lb->getPrimaryPos(); if ( $pos ) { $this->logger->debug( __METHOD__ . ": $cluster ($masterName) position now '$pos'" ); $this->shutdownPositionsByPrimary[$masterName] = $pos; $this->shutdownTimestampsByCluster[$cluster] = $pos->asOfTime(); } else { $this->logger->debug( __METHOD__ . ": $cluster ($masterName) position unknown" ); $this->shutdownTimestampsByCluster[$cluster] = $this->getCurrentTime(); } } else { $this->logger->debug( __METHOD__ . ": $cluster ($masterName) has no replication" ); $this->shutdownTimestampsByCluster[$cluster] = $this->getCurrentTime(); } } /** * Persist any staged client "session consistency" replication positions * * @internal This method should only be called from LBFactory. * * @param int|null &$clientPosIndex DB position key write counter; incremented on update * @return DBPrimaryPos[] Empty on success; map of (db name => unsaved position) on failure */ public function persistSessionReplicationPositions( &$clientPosIndex = null ) { $this->load(); if ( !$this->enabled ) { return []; } if ( !$this->shutdownTimestampsByCluster ) { $this->logger->debug( __METHOD__ . ": no primary positions data to save" ); return []; } $scopeLock = $this->store->getScopedLock( $this->key, self::LOCK_TIMEOUT, self::LOCK_TTL ); if ( $scopeLock ) { $positions = $this->mergePositions( $this->unmarshalPositions( $this->store->get( $this->key ) ), $this->shutdownPositionsByPrimary, $this->shutdownTimestampsByCluster, $clientPosIndex ); $ok = $this->store->set( $this->key, $this->marshalPositions( $positions ), self::POSITION_STORE_TTL ); unset( $scopeLock ); } else { $ok = false; } $clusterList = implode( ', ', array_keys( $this->shutdownTimestampsByCluster ) ); if ( $ok ) { $this->logger->debug( "ChronologyProtector saved position data for $clusterList" ); $bouncedPositions = []; } else { // Maybe position store is down $this->logger->warning( "ChronologyProtector failed to save position data for $clusterList" ); $clientPosIndex = null; $bouncedPositions = $this->shutdownPositionsByPrimary; } return $bouncedPositions; } /** * Get the UNIX timestamp when the client last touched the DB, if they did so recently * * @internal This method should only be called from LBFactory. * * @param ILoadBalancer $lb * @return float|false UNIX timestamp; false if not recent or on record * @since 1.35 */ public function getTouched( ILoadBalancer $lb ) { $this->load(); if ( !$this->enabled ) { return false; } $cluster = $lb->getClusterName(); $timestampsByCluster = $this->getStartupSessionTimestamps(); $timestamp = $timestampsByCluster[$cluster] ?? null; if ( $timestamp === null ) { $recentTouchTimestamp = false; } elseif ( ( $this->startupTimestamp - $timestamp ) > self::POSITION_COOKIE_TTL ) { // If the position store is not replicated among datacenters and the cookie that // sticks the client to the primary datacenter expires, then the touch timestamp // will be found for requests in one datacenter but not others. For consistency, // return false once the user is no longer routed to the primary datacenter. $recentTouchTimestamp = false; $this->logger->debug( __METHOD__ . ": old timestamp ($timestamp) for $cluster" ); } else { $recentTouchTimestamp = $timestamp; $this->logger->debug( __METHOD__ . ": recent timestamp ($timestamp) for $cluster" ); } return $recentTouchTimestamp; } /** * @return array<string,DBPrimaryPos> */ protected function getStartupSessionPositions() { $this->lazyStartup(); return $this->startupPositionsByPrimary; } /** * @return array<string,float> */ protected function getStartupSessionTimestamps() { $this->lazyStartup(); return $this->startupTimestampsByCluster; } /** * Load the stored replication positions and touch timestamps for the client * * @return void */ protected function lazyStartup() { if ( $this->startupTimestamp !== null ) { return; } $this->startupTimestamp = $this->getCurrentTime(); // There wasn't a client id in the cookie so we built one // There is no point in looking it up. if ( $this->hasNewClientId ) { $this->startupPositionsByPrimary = []; $this->startupTimestampsByCluster = []; return; } $this->logger->debug( 'ChronologyProtector using store ' . get_class( $this->store ) ); $this->logger->debug( "ChronologyProtector fetching positions for {$this->clientId}" ); $data = $this->unmarshalPositions( $this->store->get( $this->key ) ); $this->startupPositionsByPrimary = $data ? $data[self::FLD_POSITIONS] : []; $this->startupTimestampsByCluster = $data[self::FLD_TIMESTAMPS] ?? []; // When a stored array expires and is re-created under the same (deterministic) key, // the array value naturally starts again from index zero. As such, it is possible // that if certain store writes were lost (e.g. store down), that we unintentionally // point to an offset in an older incarnation of the array. // We don't try to detect or do something about this because: // 1. Waiting for an older offset is harmless and generally no-ops. // 2. The older value will have expired by now and thus treated as non-existing, // which means we wouldn't even "see" it here. $indexReached = is_array( $data ) ? $data[self::FLD_WRITE_INDEX] : null; if ( $this->waitForPosIndex > 0 ) { if ( $indexReached >= $this->waitForPosIndex ) { $this->logger->debug( 'expected and found position index {cpPosIndex}', [ 'cpPosIndex' => $this->waitForPosIndex, ] + $this->clientLogInfo ); } else { $this->logger->warning( 'expected but failed to find position index {cpPosIndex}', [ 'cpPosIndex' => $this->waitForPosIndex, 'indexReached' => $indexReached, 'exception' => new \RuntimeException(), ] + $this->clientLogInfo ); } } else { if ( $indexReached ) { $this->logger->debug( 'found position data with index {indexReached}', [ 'indexReached' => $indexReached ] + $this->clientLogInfo ); } } } /** * Merge the new replication positions with the currently stored ones (highest wins) * * @param array<string,mixed>|false $storedValue Current replication position data * @param array<string,DBPrimaryPos> $shutdownPositions New replication positions * @param array<string,float> $shutdownTimestamps New DB post-commit shutdown timestamps * @param int|null &$clientPosIndex New position write index * @return array<string,mixed> Combined replication position data */ protected function mergePositions( $storedValue, array $shutdownPositions, array $shutdownTimestamps, ?int &$clientPosIndex = null ) { /** @var array<string,DBPrimaryPos> $mergedPositions */ $mergedPositions = $storedValue[self::FLD_POSITIONS] ?? []; // Use the newest positions for each DB primary foreach ( $shutdownPositions as $masterName => $pos ) { if ( !isset( $mergedPositions[$masterName] ) || !( $mergedPositions[$masterName] instanceof DBPrimaryPos ) || $pos->asOfTime() > $mergedPositions[$masterName]->asOfTime() ) { $mergedPositions[$masterName] = $pos; } } /** @var array<string,float> $mergedTimestamps */ $mergedTimestamps = $storedValue[self::FLD_TIMESTAMPS] ?? []; // Use the newest touch timestamp for each DB primary foreach ( $shutdownTimestamps as $cluster => $timestamp ) { if ( !isset( $mergedTimestamps[$cluster] ) || $timestamp > $mergedTimestamps[$cluster] ) { $mergedTimestamps[$cluster] = $timestamp; } } $clientPosIndex = ( $storedValue[self::FLD_WRITE_INDEX] ?? 0 ) + 1; return [ self::FLD_POSITIONS => $mergedPositions, self::FLD_TIMESTAMPS => $mergedTimestamps, self::FLD_WRITE_INDEX => $clientPosIndex ]; } /** * @internal For testing only * @return float UNIX timestamp * @codeCoverageIgnore */ protected function getCurrentTime() { if ( $this->wallClockOverride ) { return $this->wallClockOverride; } $clockTime = (float)time(); // call this first // microtime() can severely drift from time() and the microtime() value of other threads. // Instead of seeing the current time as being in the past, use the value of time(). return max( microtime( true ), $clockTime ); } /** * @internal For testing only * @param float|null &$time Mock UNIX timestamp * @codeCoverageIgnore */ public function setMockTime( &$time ) { $this->load(); $this->wallClockOverride =& $time; } private function marshalPositions( array $positions ) { foreach ( $positions[ self::FLD_POSITIONS ] as $key => $pos ) { $positions[ self::FLD_POSITIONS ][ $key ] = $pos->toArray(); } return $positions; } /** * @param array|false $positions * @return array|false */ private function unmarshalPositions( $positions ) { if ( !$positions ) { return $positions; } foreach ( $positions[ self::FLD_POSITIONS ] as $key => $pos ) { $class = $pos[ '_type_' ]; $positions[ self::FLD_POSITIONS ][ $key ] = $class::newFromArray( $pos ); } return $positions; } /** * Build a string conveying the client and write index of the chronology protector data * * @param int $writeIndex * @param int $time UNIX timestamp; can be used to detect stale cookies (T190082) * @param string $clientId Client ID hash from ILBFactory::shutdown() * @return string Value to use for "cpPosIndex" cookie * @since 1.32 in LBFactory, moved to CP in 1.41 */ public static function makeCookieValueFromCPIndex( int $writeIndex, int $time, string $clientId ) { // Format is "<write index>@<write timestamp>#<client ID hash>" return "{$writeIndex}@{$time}#{$clientId}"; } /** * Parse a string conveying the client and write index of the chronology protector data * * @param string|null $value Value of "cpPosIndex" cookie * @param int $minTimestamp Lowest UNIX timestamp that a non-expired value can have * @return array (index: int or null, clientId: string or null) * @since 1.32 in LBFactory, moved to CP in 1.41 */ public static function getCPInfoFromCookieValue( ?string $value, int $minTimestamp ) { static $placeholder = [ 'index' => null, 'clientId' => null ]; if ( $value === null ) { return $placeholder; // not set } // Format is "<write index>@<write timestamp>#<client ID hash>" if ( !preg_match( '/^(\d+)@(\d+)#([0-9a-f]{32})$/', $value, $m ) ) { return $placeholder; // invalid } $index = (int)$m[1]; if ( $index <= 0 ) { return $placeholder; // invalid } elseif ( isset( $m[2] ) && $m[2] !== '' && (int)$m[2] < $minTimestamp ) { return $placeholder; // expired } $clientId = ( isset( $m[3] ) && $m[3] !== '' ) ? $m[3] : null; return [ 'index' => $index, 'clientId' => $clientId ]; } } PK ! | ��� � $ rdbms/querybuilder/JoinGroupBase.phpnu �Iw�� <?php namespace Wikimedia\Rdbms; use InvalidArgumentException; /** * Shared code between SelectQueryBuilder and JoinGroup to represent tables and join conditions. * * @internal */ abstract class JoinGroupBase { /** @var array */ protected $tables = []; /** @var array */ protected $joinConds = []; /** @var string|null */ protected $lastAlias; /** * Add a single table or a single parenthesized group. * * @param string|JoinGroup|SelectQueryBuilder $table The unqualified name of a table, * a table name of the form "information_schema.<unquoted identifier>", a JoinGroup * containing multiple tables, or a SelectQueryBuilder representing a subquery. * @param-taint $table exec_sql * @param string|null $alias The table alias, or null for no alias * @param-taint $alias exec_sql * @return $this */ public function table( $table, $alias = null ) { if ( $table instanceof JoinGroup ) { $alias ??= $table->getAlias(); $table = $table->getRawTables(); } elseif ( $table instanceof SelectQueryBuilder ) { $alias ??= $this->getAutoAlias(); $table = new Subquery( $table->getSQL() ); } elseif ( $table instanceof Subquery ) { if ( $alias === null ) { throw new InvalidArgumentException( __METHOD__ . ': Subquery as table must provide an alias.' ); } } elseif ( !is_string( $table ) ) { throw new InvalidArgumentException( __METHOD__ . ': $table must be either string, JoinGroup or SelectQueryBuilder' ); } if ( $alias === null ) { $this->tables[] = $table; $this->lastAlias = $table; } else { $this->tables[$alias] = $table; $this->lastAlias = $alias; } return $this; } /** * Left join a table or group of tables. This should be called after table(). * * @param string|JoinGroup|SelectQueryBuilder $table The unqualified name of a table, * a table name of the form "information_schema.<unquoted identifier>", a JoinGroup * containing multiple tables, or a SelectQueryBuilder representing a subquery. * @param string|null $alias The alias name, or null to automatically * generate an alias which will be unique to this builder * @param string|array $conds The conditions for the ON clause * @return $this */ public function leftJoin( $table, $alias = null, $conds = [] ) { $this->addJoin( 'LEFT JOIN', $table, $alias, $conds ); return $this; } /** * Inner join a table or group of tables. This should be called after table(). * * @param string|JoinGroup|SelectQueryBuilder $table The unqualified name of a table, * a table name of the form "information_schema.<unquoted identifier>", a JoinGroup * containing multiple tables, or a SelectQueryBuilder representing a subquery. * @param string|null $alias The alias name, or null to automatically * generate an alias which will be unique to this builder * @param string|array $conds The conditions for the ON clause * @return $this */ public function join( $table, $alias = null, $conds = [] ) { $this->addJoin( 'JOIN', $table, $alias, $conds ); return $this; } /** * Straight join a table or group of tables. This should be called after table(). * * @param string|JoinGroup|SelectQueryBuilder $table The unqualified name of a table, * a table name of the form "information_schema.<unquoted identifier>", a JoinGroup * containing multiple tables, or a SelectQueryBuilder representing a subquery. * @param string|null $alias The alias name, or null to automatically * generate an alias which will be unique to this builder * @param string|array $conds The conditions for the ON clause * @return $this */ public function straightJoin( $table, $alias = null, $conds = [] ) { $this->addJoin( 'STRAIGHT_JOIN', $table, $alias, $conds ); return $this; } /** * Private helper for functions that add joins * @param string $type * @param string|JoinGroup|SelectQueryBuilder $table * @param string|null $alias * @param string|array $joinConds */ private function addJoin( $type, $table, $alias, $joinConds ) { if ( !$this->tables ) { throw new \LogicException( __METHOD__ . ': cannot add a join unless a regular table is added first' ); } if ( $alias === null ) { if ( is_string( $table ) ) { $alias = $table; } else { $alias = $this->getAutoAlias(); } } if ( isset( $this->joinConds[$alias] ) ) { throw new \LogicException( __METHOD__ . ": a join with alias \"$alias\" has already been added" ); } if ( $table instanceof JoinGroup ) { $conflicts = array_intersect_key( $this->joinConds, $table->getRawJoinConds() ); if ( $conflicts ) { $conflict = reset( $conflicts ); throw new \LogicException( __METHOD__ . ": a join with alias \"$conflict\" has already been added" ); } $this->tables[$alias] = $table->getRawTables(); $this->joinConds += $table->getRawJoinConds(); } elseif ( $table instanceof SelectQueryBuilder ) { $this->tables[$alias] = new Subquery( $table->getSQL() ); } elseif ( is_string( $table ) ) { $this->tables[$alias] = $table; } else { throw new InvalidArgumentException( __METHOD__ . ': $table must be either string, JoinGroup or SelectQueryBuilder' ); } $this->joinConds[$alias] = [ $type, $joinConds ]; $this->lastAlias = $alias; } abstract protected function getAutoAlias(); } PK ! ����( �( ) rdbms/querybuilder/UpdateQueryBuilder.phpnu �Iw�� <?php namespace Wikimedia\Rdbms; use InvalidArgumentException; use UnexpectedValueException; // Very long type annotations :( // phpcs:disable Generic.Files.LineLength /** * Build UPDATE queries with a fluent interface. * * Each query builder object must be used for a single database query only, * and not be reused afterwards. To run multiple similar queries, you can * create a query builder to set up most of your query, which you can use * as a "template" to clone. You can then modify the cloned object for * each individual query. * * @since 1.41 * @stable to extend * @ingroup Database */ class UpdateQueryBuilder { /** * @var string The table name to be passed to IDatabase::update() */ private $table = ''; /** * @var array The set values to be passed to IDatabase::update() */ private $set = []; /** * @var array The conditions to be passed to IDatabase::update() */ private $conds = []; /** * @var string The caller (function name) to be passed to IDatabase::update() */ private $caller = __CLASS__; /** * @var array The options to be passed to IDatabase::update() */ protected $options = []; /** @var IDatabase */ protected $db; /** * Only for use in subclasses. To create a UpdateQueryBuilder instance, * use `$db->newUpdateQueryBuilder()` instead. * * @param IDatabase $db */ public function __construct( IDatabase $db ) { $this->db = $db; } /** * Change the IDatabase object the query builder is bound to. The specified * IDatabase will subsequently be used to execute the query. * * @param IDatabase $db * @return $this */ public function connection( IDatabase $db ) { if ( $this->db->getType() !== $db->getType() ) { throw new InvalidArgumentException( __METHOD__ . ' cannot switch to a database of a different type.' ); } $this->db = $db; return $this; } /** * Set the query parameters to the given values, appending to the values * which were already set. This can be used to interface with legacy code. * If a key is omitted, the previous value will be retained. * * The parameters must be formatted as required by Database::update. * * @param array $info Associative array of query info, with keys: * - table: The table name to be passed to Database::update() * - set: The set conditions * - conds: The conditions * - options: The query options * - caller: The caller signature. * * @return $this */ public function queryInfo( $info ) { if ( isset( $info['table'] ) ) { $this->table( $info['table'] ); } if ( isset( $info['set'] ) ) { $this->set( $info['set'] ); } if ( isset( $info['conds'] ) ) { $this->where( $info['conds'] ); } if ( isset( $info['options'] ) ) { $this->options( (array)$info['options'] ); } if ( isset( $info['caller'] ) ) { $this->caller( $info['caller'] ); } return $this; } /** * Manually set the table name to be passed to IDatabase::update() * * @param string $table The unqualified name of a table * @param-taint $table exec_sql * @return $this */ public function table( $table ) { $this->table = $table; return $this; } /** * Set table for the query. Alias for table(). * * @param string $table The unqualified name of a table * @param-taint $table exec_sql * @return $this */ public function update( string $table ) { return $this->table( $table ); } /** * Manually set an option in the $options array to be passed to * IDatabase::update() * * @param string $name The option name * @param mixed $value The option value, or null for a boolean option * @return $this */ public function option( $name, $value = null ) { if ( $value === null ) { $this->options[] = $name; } else { $this->options[$name] = $value; } return $this; } /** * Manually set multiple options in the $options array to be passed to * IDatabase::update(). * * @param array $options * @return $this */ public function options( array $options ) { $this->options = array_merge( $this->options, $options ); return $this; } /** * Add conditions to the query. The supplied conditions will be appended * to the existing conditions, separated by AND. * * @param string|IExpression|array<string,?scalar|non-empty-array<int,?scalar>|RawSQLValue>|array<int,string|IExpression> $conds * @param-taint $conds exec_sql_numkey * * May be either a string containing a single condition, or an array of * conditions. If an array is given, the conditions constructed from each * element are combined with AND. * * Array elements may take one of two forms: * * - Elements with a numeric key are interpreted as raw SQL fragments. * - Elements with a string key are interpreted as equality conditions, * where the key is the field name. * - If the value of such an array element is a scalar (such as a * string), it will be treated as data and thus quoted appropriately. * If it is null, an IS NULL clause will be added. * - If the value is an array, an IN (...) clause will be constructed * from its non-null elements, and an IS NULL clause will be added * if null is present, such that the field may match any of the * elements in the array. The non-null elements will be quoted. * * Note that expressions are often DBMS-dependent in their syntax. * DBMS-independent wrappers are provided for constructing several types of * expression commonly used in condition queries. See: * - IDatabase::buildLike() * - IDatabase::conditional() * * Untrusted user input is safe in the values of string keys, however untrusted * input must not be used in the array key names or in the values of numeric keys. * Escaping of untrusted input used in values of numeric keys should be done via * IDatabase::addQuotes() * * @return $this */ public function where( $conds ) { if ( is_array( $conds ) ) { foreach ( $conds as $key => $cond ) { if ( is_int( $key ) ) { $this->conds[] = $cond; } elseif ( isset( $this->conds[$key] ) ) { // @phan-suppress-previous-line PhanTypeMismatchDimFetch // T288882 $this->conds[] = $this->db->makeList( [ $key => $cond ], IDatabase::LIST_AND ); } else { $this->conds[$key] = $cond; } } } else { $this->conds[] = $conds; } return $this; } /** * Add conditions to the query. Alias for where(). * * @param string|IExpression|array<string,?scalar|non-empty-array<int,?scalar>|RawSQLValue>|array<int,string|IExpression> $conds * @param-taint $conds exec_sql_numkey * @return $this */ public function andWhere( $conds ) { return $this->where( $conds ); } /** * Add conditions to the query. Alias for where(). * * @param string|IExpression|array<string,?scalar|non-empty-array<int,?scalar>|RawSQLValue>|array<int,string|IExpression> $conds * @param-taint $conds exec_sql_numkey * @return $this */ public function conds( $conds ) { return $this->where( $conds ); } /** * Add SET part to the query. It takes an array containing arrays of column names map to * the set values. * * @param string|array<string,?scalar|RawSQLValue>|array<int,string> $set * @param-taint $set exec_sql_numkey * * Combination map/list where each string-keyed entry maps a column * to a literal assigned value and each integer-keyed value is a SQL expression in the * format of a column assignment within UPDATE...SET. The (column => value) entries are * convenient due to automatic value quoting and conversion of null to NULL. The SQL * assignment format is useful for updates like "column = column + X". All assignments * have no defined execution order, so they should not depend on each other. Do not * modify AUTOINCREMENT or UUID columns in assignments. * * Untrusted user input is safe in the values of string keys, however untrusted * input must not be used in the array key names or in the values of numeric keys. * Escaping of untrusted input used in values of numeric keys should be done via * IDatabase::addQuotes() * * @return $this */ public function set( $set ) { if ( is_array( $set ) ) { foreach ( $set as $key => $value ) { if ( is_int( $key ) ) { $this->set[] = $value; } else { $this->set[$key] = $value; } } } else { $this->set[] = $set; } return $this; } /** * Add set values to the query. Alias for set(). * * @param string|array<string,?scalar|RawSQLValue>|array<int,string> $set * @param-taint $set exec_sql_numkey * @return $this */ public function andSet( $set ) { return $this->set( $set ); } /** * Enable the IGNORE option. * * Skip update of rows that would cause unique key conflicts. * IDatabase::affectedRows() can be used to determine how many rows were updated. * * @return $this */ public function ignore() { $this->options[] = 'IGNORE'; return $this; } /** * Set the method name to be included in an SQL comment. * * @param string $fname * @param-taint $fname exec_sql * @return $this */ public function caller( $fname ) { $this->caller = $fname; return $this; } /** * Run the constructed UPDATE query. */ public function execute(): void { if ( !$this->conds ) { throw new UnexpectedValueException( __METHOD__ . ' expects at least one condition to be set' ); } if ( !$this->set ) { throw new UnexpectedValueException( __METHOD__ . ' can\t have empty $set value' ); } if ( $this->table === '' ) { throw new UnexpectedValueException( __METHOD__ . ' expects table not to be empty' ); } $this->db->update( $this->table, $this->set, $this->conds, $this->caller, $this->options ); } /** * Get an associative array describing the query in terms of its raw parameters to * Database::update(). This can be used to interface with legacy code. * * @return array The query info array, with keys: * - table: The table name * - set: The set array * - conds: The conditions * - options: The query options * - caller: The caller signature */ public function getQueryInfo() { $info = [ 'table' => $this->table, 'set' => $this->set, 'conds' => $this->conds, 'options' => $this->options, ]; if ( $this->caller !== __CLASS__ ) { $info['caller'] = $this->caller; } return $info; } } PK ! 4�d�� � ) rdbms/querybuilder/DeleteQueryBuilder.phpnu �Iw�� <?php namespace Wikimedia\Rdbms; use InvalidArgumentException; use UnexpectedValueException; // Very long type annotations :( // phpcs:disable Generic.Files.LineLength /** * A query builder for DELETE queries with a fluent interface. * * Any particular query builder object should only be used for a single database query, * and not be reused afterwards. However, to run multiple similar queries, * you can create a “template” query builder to set up most of the query, * and then clone the object (and potentially modify the clone) for each individual query. * * @stable to extend * @since 1.41 * @ingroup Database */ class DeleteQueryBuilder { /** * The table name to be passed to IDatabase::delete() */ private string $table = ''; /** * The conditions to be passed to IDatabase::delete() */ private array $conds = []; /** * The caller (function name) to be passed to IDatabase::delete() */ private string $caller = __CLASS__; protected IDatabase $db; /** * Only for use in subclasses and Database::newDeleteQueryBuilder. * To create a DeleteQueryBuilder instance, use `$db->newDeleteQueryBuilder()` instead. * * @param IDatabase $db */ public function __construct( IDatabase $db ) { $this->db = $db; } /** * Change the IDatabase object the query builder is bound to. The specified * IDatabase will subsequently be used to execute the query. * * @param IDatabase $db * @return $this */ public function connection( IDatabase $db ): DeleteQueryBuilder { if ( $this->db->getType() !== $db->getType() ) { throw new InvalidArgumentException( __METHOD__ . ' cannot switch to a database of a different type.' ); } $this->db = $db; return $this; } /** * Set the query parameters to the given values, appending to the values * which were already set. This can be used to interface with legacy code. * If a key is omitted, the previous value will be retained. * * The parameters must be formatted as required by Database::delete. * * @param array $info Associative array of query info, with keys: * - table: The table name to be passed to IDatabase::delete() * - conds: The conditions * - caller: The caller signature * * @return $this */ public function queryInfo( array $info ): DeleteQueryBuilder { if ( isset( $info['table'] ) ) { $this->table( $info['table'] ); } if ( isset( $info['conds'] ) ) { $this->where( $info['conds'] ); } if ( isset( $info['caller'] ) ) { $this->caller( $info['caller'] ); } return $this; } /** * Manually set the table name to be passed to IDatabase::delete() * * @param string $table The unqualified name of a table * @param-taint $table exec_sql * @return $this */ public function table( string $table ): DeleteQueryBuilder { $this->table = $table; return $this; } /** * Set table for the query. Alias for table(). * * @param string $table The unqualified name of a table * @param-taint $table exec_sql * @return $this */ public function deleteFrom( string $table ): DeleteQueryBuilder { return $this->table( $table ); } /** * Set table for the query. Alias for table(). * * @param string $table The unqualified name of a table * @param-taint $table exec_sql * @return $this */ public function delete( string $table ): DeleteQueryBuilder { return $this->table( $table ); } /** * Add conditions to the query. The supplied conditions will be appended * to the existing conditions, separated by AND. * * @param string|IExpression|array<string,?scalar|non-empty-array<int,?scalar>|RawSQLValue>|array<int,string|IExpression> $conds * @param-taint $conds exec_sql_numkey * * May be either a string containing a single condition, or an array of * conditions. If an array is given, the conditions constructed from each * element are combined with AND. * * Array elements may take one of two forms: * * - Elements with a numeric key are interpreted as raw SQL fragments. * - Elements with a string key are interpreted as equality conditions, * where the key is the field name. * - If the value of such an array element is a scalar (such as a * string), it will be treated as data and thus quoted appropriately. * If it is null, an IS NULL clause will be added. * - If the value is an array, an IN (...) clause will be constructed * from its non-null elements, and an IS NULL clause will be added * if null is present, such that the field may match any of the * elements in the array. The non-null elements will be quoted. * * Note that expressions are often DBMS-dependent in their syntax. * DBMS-independent wrappers are provided for constructing several types of * expression commonly used in condition queries. See: * - IDatabase::buildLike() * - IDatabase::conditional() * * Untrusted user input is safe in the values of string keys, however untrusted * input must not be used in the array key names or in the values of numeric keys. * Escaping of untrusted input used in values of numeric keys should be done via * IDatabase::addQuotes() * * @return $this */ public function where( $conds ): DeleteQueryBuilder { if ( is_array( $conds ) ) { foreach ( $conds as $key => $cond ) { if ( is_int( $key ) ) { $this->conds[] = $cond; } elseif ( isset( $this->conds[$key] ) ) { // @phan-suppress-previous-line PhanTypeMismatchDimFetch // T288882 $this->conds[] = $this->db->makeList( [ $key => $cond ], IDatabase::LIST_AND ); } else { $this->conds[$key] = $cond; } } } else { $this->conds[] = $conds; } return $this; } /** * Add conditions to the query. Alias for where(). * * @param string|IExpression|array<string,?scalar|non-empty-array<int,?scalar>|RawSQLValue>|array<int,string|IExpression> $conds * @param-taint $conds exec_sql_numkey * @return $this */ public function andWhere( $conds ): DeleteQueryBuilder { return $this->where( $conds ); } /** * Add conditions to the query. Alias for where(). * * @param string|IExpression|array<string,?scalar|non-empty-array<int,?scalar>|RawSQLValue>|array<int,string|IExpression> $conds * @param-taint $conds exec_sql_numkey * @return $this */ public function conds( $conds ): DeleteQueryBuilder { return $this->where( $conds ); } /** * Set the method name to be included in an SQL comment. * * @param string $fname * @param-taint $fname exec_sql * @return $this */ public function caller( string $fname ): DeleteQueryBuilder { $this->caller = $fname; return $this; } /** * Run the constructed DELETE query. */ public function execute(): void { if ( !$this->conds ) { throw new UnexpectedValueException( __METHOD__ . ' expects at least one condition to be set' ); } if ( $this->table === '' ) { throw new UnexpectedValueException( __METHOD__ . ' expects table not to be empty' ); } $this->db->delete( $this->table, $this->conds, $this->caller ); } /** * Get an associative array describing the query in terms of its raw parameters to * IDatabase::delete(). This can be used to interface with legacy code. * * @return array The query info array, with keys: * - table: The table name * - conds: The conditions * - caller: The caller signature */ public function getQueryInfo(): array { $info = [ 'table' => $this->table, 'conds' => $this->conds, ]; if ( $this->caller !== __CLASS__ ) { $info['caller'] = $this->caller; } return $info; } } PK ! �۫ � ( rdbms/querybuilder/UnionQueryBuilder.phpnu �Iw�� <?php namespace Wikimedia\Rdbms; use Wikimedia\Rdbms\Platform\ISQLPlatform; /** * A query builder for UNION queries takes SelectQueryBuilder objects * * Any particular query builder object should only be used for a single database query, * and not be reused afterwards. * * @since 1.41 * @ingroup Database */ class UnionQueryBuilder { /** sort the results in ascending order */ public const SORT_ASC = 'ASC'; /** sort the results in descending order */ public const SORT_DESC = 'DESC'; /** * @var SelectQueryBuilder[] */ private $sqbs = []; /** @var IDatabase */ private $db; /** @var bool */ private $all = IReadableDatabase::UNION_DISTINCT; /** @var array */ private $options = []; /** * @var string The caller (function name) to be passed to IDatabase::query() */ private $caller = __CLASS__; /** * To create a UnionQueryBuilder instance, use `$db->newUnionQueryBuilder()` instead. * * @param IDatabase $db */ public function __construct( IDatabase $db ) { $this->db = $db; } /** * Add a select query builder object to the list of union * * @return $this */ public function add( SelectQueryBuilder $selectQueryBuilder ) { $this->sqbs[] = $selectQueryBuilder; return $this; } /** * Enable UNION_ALL option, the default is UNION_DISTINCT * * @return $this */ public function all() { $this->all = $this->db::UNION_ALL; return $this; } /** * Set the query limit. Return at most this many rows. The rows are sorted * and then the first rows are taken until the limit is reached. Limit * is applied to a result set after offset. * * If the query builder already has a limit, the old limit will be discarded. * This would be also ignored if the DB does not support limit in union queries. * * @param int $limit * @return $this */ public function limit( $limit ) { if ( !$this->db->unionSupportsOrderAndLimit() ) { return $this; } $this->options['LIMIT'] = $limit; return $this; } /** * Set the offset. Skip this many rows at the start of the result set. Offset * with limit() can theoretically be used for paging through a result set, * but this is discouraged for performance reasons. * * If the query builder already has an offset, the old offset will be discarded. * This would be also ignored if the DB does not support offset in union queries. * * @param int $offset * @return $this */ public function offset( $offset ) { if ( !$this->db->unionSupportsOrderAndLimit() ) { return $this; } $this->options['OFFSET'] = $offset; return $this; } /** * Set the ORDER BY clause. If it has already been set, append the * additional fields to it. * * This would be ignored if the DB does not support order by in union queries. * * @param string[]|string $fields The field or list of fields to order by. * @param-taint $fields exec_sql * @param string|null $direction self::SORT_ASC or self::SORT_DESC. * If this is null then $fields is assumed to optionally contain ASC or DESC * after each field name. * @param-taint $direction exec_sql * @return $this */ public function orderBy( $fields, $direction = null ) { if ( !$this->db->unionSupportsOrderAndLimit() ) { return $this; } if ( $direction === null ) { $this->mergeOption( 'ORDER BY', $fields ); } elseif ( is_array( $fields ) ) { $fieldsWithDirection = []; foreach ( $fields as $field ) { $fieldsWithDirection[] = "$field $direction"; } $this->mergeOption( 'ORDER BY', $fieldsWithDirection ); } else { $this->mergeOption( 'ORDER BY', "$fields $direction" ); } return $this; } /** * Add a value to an option which may be not set or a string or array. * * @param string $name * @param string|string[] $newArrayOrValue */ private function mergeOption( $name, $newArrayOrValue ) { $value = isset( $this->options[$name] ) ? (array)$this->options[$name] : []; if ( is_array( $newArrayOrValue ) ) { $value = array_merge( $value, $newArrayOrValue ); } else { $value[] = $newArrayOrValue; } $this->options[$name] = $value; } /** * Set the method name to be included in an SQL comment. * * @param string $fname * @param-taint $fname exec_sql * @return $this */ public function caller( $fname ) { $this->caller = $fname; return $this; } /** * Run the constructed UNION query and return all results. * * @return IResultWrapper */ public function fetchResultSet() { $query = new Query( $this->getSQL(), ISQLPlatform::QUERY_CHANGE_NONE, 'SELECT' ); return $this->db->query( $query, $this->caller ); } /** * Run the constructed UNION query, and return a single field extracted * from the first result row. If there were no result rows, false is * returned. This may only be called when only one field has been added to * the constituent queries. * * @since 1.42 * @return mixed * @return-taint tainted */ public function fetchField() { $this->limit( 1 ); foreach ( $this->fetchResultSet() as $row ) { $row = (array)$row; if ( count( $row ) !== 1 ) { throw new \UnexpectedValueException( __METHOD__ . ' expects the query to have only one field' ); } return $row[ array_key_first( $row ) ]; } return false; } /** * Run the constructed UNION query, and extract a single field from each * result row, returning an array containing all the values. This may only * be called when only one field has been added to the constituent queries. * * @since 1.42 * @return array * @return-taint tainted */ public function fetchFieldValues() { $values = []; foreach ( $this->fetchResultSet() as $row ) { $row = (array)$row; if ( count( $row ) !== 1 ) { throw new \UnexpectedValueException( __METHOD__ . ' expects the query to have only one field' ); } $values[] = $row[ array_key_first( $row ) ]; } return $values; } /** * Run the constructed UNION query, and return the first result row. If * there were no results, return false. * * @since 1.42 * @return \stdClass|false * @return-taint tainted */ public function fetchRow() { $this->limit( 1 ); foreach ( $this->fetchResultSet() as $row ) { return $row; } return false; } /** * Get the SQL query string which would be used by fetchResultSet(). * * @since 1.42 * @return string */ public function getSQL() { $sqls = []; foreach ( $this->sqbs as $sqb ) { $sqls[] = $sqb->getSQL(); } return $this->db->unionQueries( $sqls, $this->all, $this->options ); } } PK ! �F��{ { * rdbms/querybuilder/ReplaceQueryBuilder.phpnu �Iw�� <?php namespace Wikimedia\Rdbms; use InvalidArgumentException; use UnexpectedValueException; /** * Build REPLACE queries with a fluent interface. * * Each query builder object must be used for a single database query only, * and not be reused afterwards. To run multiple similar queries, you can * create a query builder to set up most of your query, which you can use * as a "template" to clone. You can then modify the cloned object for * each individual query. * * @since 1.41 * @stable to extend * @ingroup Database */ class ReplaceQueryBuilder { /** * @var string The table name to be passed to IDatabase::replace() */ private $table = ''; /** * @var list<array> The rows to be passed to IDatabase::replace() */ private $rows = []; /** * @var string The caller (function name) to be passed to IDatabase::replace() */ private $caller = __CLASS__; /** * @var string[] The unique keys to be passed to IDatabase::replace() */ private $uniqueIndexFields = []; /** @var IDatabase */ protected $db; /** * Only for use in subclasses. To create a ReplaceQueryBuilder instance, * use `$db->newReplaceQueryBuilder()` instead. * * @param IDatabase $db */ public function __construct( IDatabase $db ) { $this->db = $db; } /** * Change the IDatabase object the query builder is bound to. The specified * IDatabase will subsequently be used to execute the query. * * @param IDatabase $db * @return $this */ public function connection( IDatabase $db ) { if ( $this->db->getType() !== $db->getType() ) { throw new InvalidArgumentException( __METHOD__ . ' cannot switch to a database of a different type.' ); } $this->db = $db; return $this; } /** * Set the query parameters to the given values, appending to the values * which were already set. This can be used to interface with legacy code. * If a key is omitted, the previous value will be retained. * * The parameters must be formatted as required by Database::replace. * * @param array $info Associative array of query info, with keys: * - table: The table name to be passed to Database::replace() * - rows: The rows to be inserted * - options: The query options * - caller: The caller signature * * @return $this */ public function queryInfo( $info ) { if ( isset( $info['table'] ) ) { $this->table( $info['table'] ); } if ( isset( $info['rows'] ) ) { $this->rows( $info['rows'] ); } if ( isset( $info['uniqueIndexFields'] ) ) { $this->uniqueIndexFields( (array)$info['uniqueIndexFields'] ); } if ( isset( $info['caller'] ) ) { $this->caller( $info['caller'] ); } return $this; } /** * Manually set the table name to be passed to IDatabase::replace() * * @param string $table The unqualified name of a table * @param-taint $table exec_sql * @return $this */ public function table( $table ) { $this->table = $table; return $this; } /** * Set table for the query. Alias for table(). * * @param string $table The unqualified name of a table * @param-taint $table exec_sql * @return $this */ public function replaceInto( string $table ) { return $this->table( $table ); } /** * Add rows to be inserted. * * @param list<array> $rows * $rows should be an integer-keyed list of such string-keyed maps, defining a list of new rows. * The keys in each map must be identical to each other and in the same order. * The rows must not collide with each other. * * @return $this */ public function rows( array $rows ) { $this->rows = array_merge( $this->rows, $rows ); return $this; } /** * Add one row to be inserted. * * @param array $row * $row must be a string-keyed map of (column name => value) defining a new row. Values are * treated as literals and quoted appropriately; null is interpreted as NULL. * * @return $this */ public function row( array $row ) { $this->rows[] = $row; return $this; } /** * Set the unique index fields * * @param string|string[] $uniqueIndexFields * @return $this */ public function uniqueIndexFields( $uniqueIndexFields ) { if ( is_string( $uniqueIndexFields ) ) { $uniqueIndexFields = [ $uniqueIndexFields ]; } $this->uniqueIndexFields = $uniqueIndexFields; return $this; } /** * Set the method name to be included in an SQL comment. * * @param string $fname * @param-taint $fname exec_sql * @return $this */ public function caller( $fname ) { $this->caller = $fname; return $this; } /** * Run the constructed REPLACE query and return the result. */ public function execute() { if ( !$this->rows ) { throw new UnexpectedValueException( __METHOD__ . ' can\'t have empty $rows value' ); } if ( $this->table === '' ) { throw new UnexpectedValueException( __METHOD__ . ' expects table not to be empty' ); } if ( !$this->uniqueIndexFields ) { throw new UnexpectedValueException( __METHOD__ . ' expects unique key to be provided' ); } $this->db->replace( $this->table, [ $this->uniqueIndexFields ], $this->rows, $this->caller ); } /** * Get an associative array describing the query in terms of its raw parameters to * Database::replace(). This can be used to interface with legacy code. * * @return array The query info array, with keys: * - table: The table name * - rows: The rows array * - options: The query options * - caller: The caller signature */ public function getQueryInfo() { $info = [ 'table' => $this->table, 'rows' => $this->rows, 'uniqueIndexFields' => $this->uniqueIndexFields, ]; if ( $this->caller !== __CLASS__ ) { $info['caller'] = $this->caller; } return $info; } } PK ! @u�Ұj �j ) rdbms/querybuilder/SelectQueryBuilder.phpnu �Iw�� <?php namespace Wikimedia\Rdbms; use Wikimedia\Rdbms\Platform\ISQLPlatform; // Very long type annotations :( // phpcs:disable Generic.Files.LineLength /** * Build SELECT queries with a fluent interface. * * Each query builder object must be used for a single database query only, * and not be reused afterwards. To run multiple similar queries, you can * create a query builder to set up most of your query, which you can use * as a "template" to clone. You can then modify the cloned object for * each individual query. * * Note that the methods in this class are not stable to override. * This class may be extended to create query builders for specific database * tables, such {@link \MediaWiki\Page\PageSelectQueryBuilder}, whilst still * providing the same fluent interface for adding arbitrary additional * conditions and such. * * @since 1.35 * @stable to extend * @ingroup Database */ class SelectQueryBuilder extends JoinGroupBase { /** sort the results in ascending order */ public const SORT_ASC = 'ASC'; /** sort the results in descending order */ public const SORT_DESC = 'DESC'; /** * @var array The fields to be passed to IReadableDatabase::select() */ private $fields = []; /** * @var array The conditions to be passed to IReadableDatabase::select() */ private $conds = []; /** * @var string The caller (function name) to be passed to IReadableDatabase::select() */ private $caller = __CLASS__; /** * @var array The options to be passed to IReadableDatabase::select() */ protected $options = []; /** * @var int An integer used to assign automatic aliases to tables and groups */ private $nextAutoAlias = 1; /** * @var bool True if $this->caller has been set */ private $isCallerOverridden = false; /** @var IReadableDatabase */ protected IReadableDatabase $db; /** * Only for use in subclasses. To create a SelectQueryBuilder instance, * use `$db->newSelectQueryBuilder()` instead. * * @param IReadableDatabase $db */ public function __construct( IReadableDatabase $db ) { $this->db = $db; } /** * Change the IReadableDatabase object the query builder is bound to. The specified * IReadableDatabase will subsequently be used to execute the query. * * @param IReadableDatabase $db * @return $this */ public function connection( IReadableDatabase $db ) { if ( $this->db->getType() !== $db->getType() ) { throw new \InvalidArgumentException( __METHOD__ . ' cannot switch to a database of a different type.' ); } $this->db = $db; return $this; } /** * Set the query parameters to the given values, appending to the values * which were already set. This can be used to interface with legacy code. * If a key is omitted, the previous value will be retained. * * The parameters must be formatted as required by IReadableDatabase::select. For * example, JoinGroup cannot be used. * * @param array $info Associative array of query info, with keys: * - tables: The raw array of tables to be passed to IReadableDatabase::select() * - fields: The fields * - conds: The conditions * - options: The query options * - join_conds: The join conditions * - joins: Alias for join_conds. If both joins and join_conds are * specified, the values will be merged. * - caller: The caller signature * * @return $this */ public function queryInfo( $info ) { if ( isset( $info['tables'] ) ) { $this->rawTables( $info['tables'] ); } if ( isset( $info['fields'] ) ) { $this->fields( $info['fields'] ); } if ( isset( $info['conds'] ) ) { $this->where( $info['conds'] ); } if ( isset( $info['options'] ) ) { $this->options( (array)$info['options'] ); } if ( isset( $info['join_conds'] ) ) { $this->joinConds( (array)$info['join_conds'] ); } if ( isset( $info['joins'] ) ) { $this->joinConds( (array)$info['joins'] ); } if ( isset( $info['caller'] ) ) { $this->caller( $info['caller'] ); } return $this; } /** * Given a table or table array as might be passed to IReadableDatabase::select(), * append it to the existing tables, interpreting nested arrays as join * groups. * * This can be used to interface with existing code that expresses join * groups as nested arrays. In new code, join groups should generally * be created with newJoinGroup(), which provides a fluent interface. * * @param string|array $tables Table references; see {@link IReadableDatabase::select} * for details * @return $this */ public function rawTables( $tables ) { if ( is_array( $tables ) ) { $this->tables = array_merge( $this->tables, $tables ); } elseif ( is_string( $tables ) ) { $this->tables[] = $tables; } else { throw new \InvalidArgumentException( __METHOD__ . ': $tables must be a string or array' ); } return $this; } /** * Merge another query builder with this one. Append the other builder's * tables, joins, fields, conditions and options to this one. * * @since 1.41 * @param SelectQueryBuilder $builder * @return $this */ public function merge( SelectQueryBuilder $builder ) { $this->rawTables( $builder->tables ); $this->fields( $builder->fields ); $this->where( $builder->conds ); $this->options( $builder->options ); $this->joinConds( $builder->joinConds ); if ( $builder->isCallerOverridden ) { $this->caller( $builder->caller ); } return $this; } /** * Get an empty SelectQueryBuilder which can be used to build a subquery * of this query. * @return SelectQueryBuilder */ public function newSubquery() { return new self( $this->db ); } /** * Add a single table to the SELECT query. Alias for table(). * * @param string|JoinGroup|SelectQueryBuilder $table Table reference; see {@link table} * for details * @param-taint $table exec_sql * @param string|null $alias The table alias, or null for no alias * @param-taint $alias exec_sql * @return $this */ public function from( $table, $alias = null ) { return $this->table( $table, $alias ); } /** * Add multiple tables. It's recommended to use join() and leftJoin() instead in new code. * * @param string[] $tables Table references (string keys are aliases). See {@link table} * for details. * @param-taint $tables exec_sql * @return $this */ public function tables( $tables ) { foreach ( $tables as $alias => $table ) { if ( is_string( $alias ) ) { $this->table( $table, $alias ); } else { $this->table( $table ); } } return $this; } /** * Add a field or an array of fields to the query. Each field is an SQL * fragment. If the array key is non-numeric, the key is taken to be an * alias for the field. * * @see IReadableDatabase::select() * * @param string|string[] $fields * @param-taint $fields exec_sql * @return $this */ public function fields( $fields ) { if ( is_array( $fields ) ) { $this->fields = array_merge( $this->fields, $fields ); } else { $this->fields[] = $fields; } return $this; } /** * Add a field or an array of fields to the query. Alias for fields(). * * @param string|string[] $fields * @param-taint $fields exec_sql * @return $this */ public function select( $fields ) { return $this->fields( $fields ); } /** * Add a single field to the query, optionally with an alias. The field is * an SQL fragment. It is unsafe to pass user input to this function. * * @param string $field * @param-taint $field exec_sql * @param string|null $alias * @param-taint $alias exec_sql * @return $this */ public function field( $field, $alias = null ) { if ( $alias === null ) { $this->fields[] = $field; } else { $this->fields[$alias] = $field; } return $this; } /** * Remove all fields from the query. * * @return $this */ public function clearFields() { $this->fields = []; return $this; } /** * Add conditions to the query. The supplied conditions will be appended * to the existing conditions, separated by AND. * * @param string|IExpression|array<string,?scalar|non-empty-array<int,?scalar>|RawSQLValue>|array<int,string|IExpression> $conds * @param-taint $conds exec_sql_numkey * * May be either a string containing a single condition, or an array of * conditions. If an array is given, the conditions constructed from each * element are combined with AND. * * Array elements may take one of two forms: * * - Elements with a numeric key are interpreted as raw SQL fragments. * - Elements with a string key are interpreted as equality conditions, * where the key is the field name. * - If the value of such an array element is a scalar (such as a * string), it will be treated as data and thus quoted appropriately. * If it is null, an IS NULL clause will be added. * - If the value is an array, an IN (...) clause will be constructed * from its non-null elements, and an IS NULL clause will be added * if null is present, such that the field may match any of the * elements in the array. The non-null elements will be quoted. * * Note that expressions are often DBMS-dependent in their syntax. * DBMS-independent wrappers are provided for constructing several types of * expression commonly used in condition queries. See: * - IReadableDatabase::buildLike() * - IReadableDatabase::conditional() * * Untrusted user input is safe in the values of string keys, however untrusted * input must not be used in the array key names or in the values of numeric keys. * Escaping of untrusted input used in values of numeric keys should be done via * IReadableDatabase::addQuotes() * * @return $this */ public function where( $conds ) { if ( is_array( $conds ) ) { foreach ( $conds as $key => $cond ) { if ( is_int( $key ) ) { $this->conds[] = $cond; } elseif ( isset( $this->conds[$key] ) ) { // @phan-suppress-previous-line PhanTypeMismatchDimFetch // T288882 $this->conds[] = $this->db->makeList( [ $key => $cond ], IReadableDatabase::LIST_AND ); } else { $this->conds[$key] = $cond; } } } else { $this->conds[] = $conds; } return $this; } /** * Add conditions to the query. Alias for where(). * * @param string|IExpression|array<string,?scalar|non-empty-array<int,?scalar>|RawSQLValue>|array<int,string|IExpression> $conds * @param-taint $conds exec_sql_numkey * @return $this */ public function andWhere( $conds ) { return $this->where( $conds ); } /** * Add conditions to the query. Alias for where(). * * @param string|IExpression|array<string,?scalar|non-empty-array<int,?scalar>|RawSQLValue>|array<int,string|IExpression> $conds * @param-taint $conds exec_sql_numkey * @return $this */ public function conds( $conds ) { return $this->where( $conds ); } /** * Manually append to the $join_conds array which will be passed to * IReadableDatabase::select(). This is not recommended for new code. Instead, * join() and leftJoin() should be used. * * @param array $joinConds * @return $this */ public function joinConds( array $joinConds ) { $this->joinConds = array_merge( $this->joinConds, $joinConds ); return $this; } /** * Get a table alias which is unique to this SelectQueryBuilder * * @return string */ protected function getAutoAlias() { return 'sqb' . ( $this->nextAutoAlias++ ); } /** * Create a parenthesized group of joins which can be added to the object * like a table. The group is initially empty. * * @return JoinGroup */ public function newJoinGroup() { return new JoinGroup( $this->getAutoAlias() ); } /** * Set the offset. Skip this many rows at the start of the result set. Offset * with limit() can theoretically be used for paging through a result set, * but this is discouraged for performance reasons. * * If the query builder already has an offset, the old offset will be discarded. * * @param int $offset * @return $this */ public function offset( $offset ) { $this->options['OFFSET'] = $offset; return $this; } /** * Set the query limit. Return at most this many rows. The rows are sorted * and then the first rows are taken until the limit is reached. Limit * is applied to a result set after offset. * * If the query builder already has a limit, the old limit will be discarded. * * @param int $limit * @return $this */ public function limit( $limit ) { $this->options['LIMIT'] = $limit; return $this; } /** * Enable the LOCK IN SHARE MODE option. Lock the returned rows so that * they can't be changed until the next COMMIT. Cannot be used with * aggregate functions (COUNT, MAX, etc., but also DISTINCT). * * @return $this */ public function lockInShareMode() { $this->options[] = 'LOCK IN SHARE MODE'; return $this; } /** * Enable the FOR UPDATE option. Lock the returned rows so that * they can't be changed until the next COMMIT. Cannot be used with * aggregate functions (COUNT, MAX, etc., but also DISTINCT). * * @return $this */ public function forUpdate() { $this->options[] = 'FOR UPDATE'; return $this; } /** * Enable the DISTINCT option. Return only unique result rows. * * @return $this */ public function distinct() { $this->options[] = 'DISTINCT'; return $this; } /** * Set MAX_EXECUTION_TIME for queries. * * @param int $time maximum allowed time in milliseconds * @return $this */ public function setMaxExecutionTime( int $time ) { $this->options['MAX_EXECUTION_TIME'] = $time; return $this; } /** * Add a GROUP BY clause. May be either an SQL fragment string naming a * field or expression to group by, or an array of such SQL fragments. * * If there is an existing GROUP BY clause, the new one will be appended. * * @param string|string[] $group * @param-taint $group exec_sql * @return $this */ public function groupBy( $group ) { $this->mergeOption( 'GROUP BY', $group ); return $this; } /** * Add a HAVING clause. May be either a string containing a HAVING clause * or an array of conditions building the HAVING clause. If an array is * given, the conditions constructed from each element are combined with * AND. * * If there is an existing HAVING clause, the new one will be appended. * * @param string|string[] $having * @param-taint $having exec_sql_numkey * @return $this */ public function having( $having ) { $this->mergeOption( 'HAVING', $having ); return $this; } /** * Set the ORDER BY clause. If it has already been set, append the * additional fields to it. * * @param string[]|string $fields The field or list of fields to order by. * @param-taint $fields exec_sql * @param string|null $direction Sorting direction applied to all fields, * self::SORT_ASC or self::SORT_DESC. If different fields need to be sorted in opposite * directions, then this parameter must be omitted, and $fields must contain 'ASC' or 'DESC' * after each field name. * @param-taint $direction exec_sql * @return $this */ public function orderBy( $fields, $direction = null ) { if ( $direction === null ) { $this->mergeOption( 'ORDER BY', $fields ); } elseif ( is_array( $fields ) ) { $fieldsWithDirection = []; foreach ( $fields as $field ) { $fieldsWithDirection[] = "$field $direction"; } $this->mergeOption( 'ORDER BY', $fieldsWithDirection ); } else { $this->mergeOption( 'ORDER BY', "$fields $direction" ); } return $this; } /** * Add a value to an option which may be not set or a string or array. * * @param string $name * @param string|string[] $newArrayOrValue */ private function mergeOption( $name, $newArrayOrValue ) { $value = isset( $this->options[$name] ) ? (array)$this->options[$name] : []; if ( is_array( $newArrayOrValue ) ) { $value = array_merge( $value, $newArrayOrValue ); } else { $value[] = $newArrayOrValue; } $this->options[$name] = $value; } /** * Set a USE INDEX option. * * If a string is given, the index hint is applied to the most recently * appended table or alias. If an array is given, it is assumed to be an * associative array with the alias names in the keys and the indexes in * the values, as in the USE INDEX option to IReadableDatabase::select(). The * array will be merged with the existing value. * * @param string|string[] $index * @param-taint $index exec_sql * @return $this */ public function useIndex( $index ) { $this->setIndexHint( 'USE INDEX', $index ); return $this; } /** * Set the IGNORE INDEX option. * * If a string is given, the index hint is applied to the most recently * appended table or alias. If an array is given, it is assumed to be an * associative array with the alias names in the keys and the indexes in * the values, as in the IGNORE INDEX option to IReadableDatabase::select(). The * array will be merged with the existing value. * * @param string|string[] $index * @param-taint $index exec_sql * @return $this */ public function ignoreIndex( $index ) { $this->setIndexHint( 'IGNORE INDEX', $index ); return $this; } /** * Private helper for methods that set index hints. * * @param string $type * @param string|string[] $value */ private function setIndexHint( $type, $value ) { if ( !isset( $this->options[$type] ) ) { $this->options[$type] = []; } elseif ( !is_array( $this->options[$type] ) ) { throw new \UnexpectedValueException( __METHOD__ . ": The $type option cannot be appended to " . 'because it is not an array. This may have been caused by a prior ' . 'call to option() or options().' ); } if ( is_array( $value ) ) { $this->options[$type] = array_merge( $this->options[$type], $value ); } elseif ( $this->lastAlias === null ) { throw new \UnexpectedValueException( __METHOD__ . ': Cannot append index value since there is no' . 'prior table' ); } else { $this->options[$type][$this->lastAlias] = $value; } } /** * Make the query be an EXPLAIN SELECT query instead of a SELECT query. * * @return $this */ public function explain() { $this->options['EXPLAIN'] = true; return $this; } /** * Enable the STRAIGHT_JOIN query option. * * @return $this */ public function straightJoinOption() { $this->options[] = 'STRAIGHT_JOIN'; return $this; } /** * Enable the SQL_BIG_RESULT option. * * @return $this */ public function bigResult() { $this->options[] = 'SQL_BIG_RESULT'; return $this; } /** * Enable the SQL_BUFFER_RESULT option. * * @return $this */ public function bufferResult() { $this->options[] = 'SQL_BUFFER_RESULT'; return $this; } /** * Enable the SQL_SMALL_RESULT option. * * @return $this */ public function smallResult() { $this->options[] = 'SQL_SMALL_RESULT'; return $this; } /** * Enable the SQL_CALC_FOUND_ROWS option. * * @return $this */ public function calcFoundRows() { $this->options[] = 'SQL_CALC_FOUND_ROWS'; return $this; } /** * Manually set an option in the $options array to be passed to * IReadableDatabase::select() * * @param string $name The option name * @param mixed $value The option value, or null for a boolean option * @return $this */ public function option( $name, $value = null ) { if ( $value === null ) { $this->options[] = $name; } else { $this->options[$name] = $value; } return $this; } /** * Manually set multiple options in the $options array to be passed to * IReadableDatabase::select(). * * @param array $options * @return $this */ public function options( array $options ) { $this->options = array_merge( $this->options, $options ); return $this; } /** * @param int $recency Bitfield of IDBAccessObject::READ_* constants * @return $this */ public function recency( $recency ) { if ( ( $recency & IDBAccessObject::READ_EXCLUSIVE ) == IDBAccessObject::READ_EXCLUSIVE ) { $this->forUpdate(); } elseif ( ( $recency & IDBAccessObject::READ_LOCKING ) == IDBAccessObject::READ_LOCKING ) { $this->lockInShareMode(); } return $this; } /** * Set the method name to be included in an SQL comment. * * @param string $fname * @param-taint $fname exec_sql * @return $this */ public function caller( $fname ) { $this->caller = $fname; $this->isCallerOverridden = true; return $this; } /** * get the method name of the caller, for use in sub classes * * @since 1.43 */ final protected function getCaller(): string { return $this->caller; } /** * Run the constructed SELECT query and return all results. * * @return IResultWrapper * @return-taint tainted */ public function fetchResultSet(): IResultWrapper { return $this->db->select( $this->tables, $this->fields, $this->conds, $this->caller, $this->options, $this->joinConds ); } /** * Run the constructed SELECT query, and return a single field extracted * from the first result row. This may only be called when only one field * has been added to the builder. * * @return mixed|false The value from the field, or false if nothing was found * @return-taint tainted */ public function fetchField() { if ( count( $this->fields ) !== 1 ) { throw new \UnexpectedValueException( __METHOD__ . ' expects the query to have only one field' ); } $field = reset( $this->fields ); return $this->db->selectField( $this->tables, $field, $this->conds, $this->caller, $this->options, $this->joinConds ); } /** * Run the constructed SELECT query, and extract a single field from each * result row, returning an array containing all the values. This may only * be called when only one field has been added to the builder. * * @return array * @return-taint tainted */ public function fetchFieldValues(): array { if ( count( $this->fields ) !== 1 ) { throw new \UnexpectedValueException( __METHOD__ . ' expects the query to have only one field' ); } $field = reset( $this->fields ); return $this->db->selectFieldValues( $this->tables, $field, $this->conds, $this->caller, $this->options, $this->joinConds ); } /** * Run the constructed SELECT query, and return the first result row. If * there were no results, return false. * * @return \stdClass|false * @return-taint tainted */ public function fetchRow() { return $this->db->selectRow( $this->tables, $this->fields, $this->conds, $this->caller, $this->options, $this->joinConds ); } /** * Run the SELECT query, and return the number of results. This typically * uses a subquery to discard the actual results on the server side, and * is useful when counting rows with a limit. * * To count rows without a limit, it's more efficient to use a normal * COUNT() expression, for example: * * $queryBuilder->select( 'COUNT(*)' )->from( 'page' )->fetchField() * * @return int */ public function fetchRowCount(): int { return $this->db->selectRowCount( $this->tables, $this->getRowCountVar(), $this->conds, $this->caller, $this->options, $this->joinConds ); } /** * Estimate the number of rows in dataset * * MySQL allows you to estimate the number of rows that would be returned * by a SELECT query, using EXPLAIN SELECT. The estimate is provided using * index cardinality statistics, and is notoriously inaccurate, especially * when large numbers of rows have recently been added or deleted. * * @return int */ public function estimateRowCount(): int { return $this->db->estimateRowCount( $this->tables, $this->getRowCountVar(), $this->conds, $this->caller, $this->options, $this->joinConds ); } /** * Private helper which extracts a field suitable for row counting from the * fields array * * @return string */ private function getRowCountVar() { if ( count( $this->fields ) === 0 ) { return '*'; } elseif ( count( $this->fields ) === 1 ) { return reset( $this->fields ); } else { throw new \UnexpectedValueException( __METHOD__ . ' expects the query to have at most one field' ); } } /** * Build a GROUP_CONCAT or equivalent statement for a query. * * This is useful for combining a field for several rows into a single string. * NULL values will not appear in the output, duplicated values will appear, * and the resulting delimiter-separated values have no defined sort order. * Code using the results may need to use the PHP unique() or sort() methods. * * @param string $delim * @return string */ public function buildGroupConcatField( $delim ) { if ( count( $this->fields ) !== 1 ) { throw new \UnexpectedValueException( __METHOD__ . ' expects the query to have only one field' ); } $field = reset( $this->fields ); return $this->db->buildGroupConcatField( $delim, $this->tables, $field, $this->conds, $this->joinConds ); } /** * Get the SQL query string which would be used by fetchResultSet(). * * @return string */ public function getSQL() { // Assume that whoever is calling this method is doing it to build a subquery $caller = $this->isCallerOverridden ? $this->caller : ISQLPlatform::CALLER_SUBQUERY; return $this->db->selectSQLText( $this->tables, $this->fields, $this->conds, $caller, $this->options, $this->joinConds ); } /** * Get an associative array describing the query in terms of its raw parameters to * IReadableDatabase::select(). This can be used to interface with legacy code. * * @param string $joinsName The name of the join_conds key * @return array The query info array, with keys: * - tables: The table array * - fields: The fields * - conds: The conditions * - options: The query options * - join_conds: The join conditions. This can also be given a different * name by passing a $joinsName parameter, since some legacy code uses * the name "joins". * - caller: The caller signature */ public function getQueryInfo( $joinsName = 'join_conds' ) { $info = [ 'tables' => $this->tables, 'fields' => $this->fields, 'conds' => $this->conds, 'options' => $this->options, ]; if ( $this->caller !== __CLASS__ ) { $info['caller'] = $this->caller; } $info[ $joinsName ] = $this->joinConds; return $info; } /** * Execute the query, but throw away the results. This is intended for * locking select queries. By calling this method, the caller is indicating * that the query is only done to acquire locks on the selected rows. The * field list is optional. * * Either forUpdate() or lockInShareMode() must be called before calling * this method. * * @see self::forUpdate() * @see self::lockInShareMode() * * @since 1.40 */ public function acquireRowLocks(): void { if ( !array_intersect( $this->options, [ 'FOR UPDATE', 'LOCK IN SHARE MODE' ] ) ) { throw new \UnexpectedValueException( __METHOD__ . ' can only be called ' . 'after forUpdate() or lockInShareMode()' ); } $fields = $this->fields ?: '1'; $this->db->select( $this->tables, $fields, $this->conds, $this->caller, $this->options, $this->joinConds ); } } PK ! p��� � rdbms/querybuilder/JoinGroup.phpnu �Iw�� <?php namespace Wikimedia\Rdbms; /** * Parenthesized group of table names and their join types and conditions. * * @internal */ class JoinGroup extends JoinGroupBase { /** @var string */ private $alias; /** @var int */ private $nextAutoAlias = 0; /** * Use SelectQueryBuilder::newJoinGroup() to create a join group * * @internal * @param string $alias */ public function __construct( $alias ) { $this->alias = $alias; } /** * Get a table alias which is unique to the parent SelectQueryBuilder * * @return string */ protected function getAutoAlias() { return $this->alias . '_' . ( $this->nextAutoAlias++ ); } /** * @internal * @return array */ public function getRawTables() { return $this->tables; } /** * @internal * @return array */ public function getRawJoinConds() { return $this->joinConds; } /** * @internal * @return string */ public function getAlias() { return $this->alias; } } PK ! �B�' ' ) rdbms/querybuilder/InsertQueryBuilder.phpnu �Iw�� <?php namespace Wikimedia\Rdbms; use InvalidArgumentException; use UnexpectedValueException; /** * Build INSERT queries with a fluent interface. * * Each query builder object must be used for a single database query only, * and not be reused afterwards. To run multiple similar queries, you can * create a query builder to set up most of your query, which you can use * as a "template" to clone. You can then modify the cloned object for * each individual query. * * @since 1.41 * @stable to extend * @ingroup Database */ class InsertQueryBuilder { /** * @var string The table name to be passed to IDatabase::insert() */ private $table = ''; /** * @var list<array> The rows to be passed to IDatabase::insert() */ private $rows = []; /** * @var string The caller (function name) to be passed to IDatabase::insert() */ private $caller = __CLASS__; /** * @var bool whether this is an upsert or not */ private $upsert = false; /** * @var array The set values to be passed to IDatabase::upsert() */ private $set = []; /** * @var string[] The unique keys to be passed to IDatabase::upsert() */ private $uniqueIndexFields = []; /** * @var array The options to be passed to IDatabase::insert() */ protected $options = []; /** @var IDatabase */ protected $db; /** * Only for use in subclasses. To create a InsertQueryBuilder instance, * use `$db->newInsertQueryBuilder()` instead. * * @param IDatabase $db */ public function __construct( IDatabase $db ) { $this->db = $db; } /** * Change the IDatabase object the query builder is bound to. The specified * IDatabase will subsequently be used to execute the query. * * @param IDatabase $db * @return $this */ public function connection( IDatabase $db ) { if ( $this->db->getType() !== $db->getType() ) { throw new InvalidArgumentException( __METHOD__ . ' cannot switch to a database of a different type.' ); } $this->db = $db; return $this; } /** * Set the query parameters to the given values, appending to the values * which were already set. This can be used to interface with legacy code. * If a key is omitted, the previous value will be retained. * * The parameters must be formatted as required by Database::insert. * * @param array $info Associative array of query info, with keys: * - table: The table name to be passed to Database::insert() * - rows: The rows to be inserted * - options: The query options * - upsert: Whether it's insert or upsert * - uniqueIndexFields: Fields of the unique index * - set: The set array * - caller: The caller signature * * @return $this */ public function queryInfo( $info ) { if ( isset( $info['table'] ) ) { $this->table( $info['table'] ); } if ( isset( $info['rows'] ) ) { $this->rows( $info['rows'] ); } if ( isset( $info['options'] ) ) { $this->options( (array)$info['options'] ); } if ( isset( $info['upsert'] ) ) { $this->onDuplicateKeyUpdate(); } if ( isset( $info['uniqueIndexFields'] ) ) { $this->uniqueIndexFields( (array)$info['uniqueIndexFields'] ); } if ( isset( $info['set'] ) ) { $this->set( (array)$info['set'] ); } if ( isset( $info['caller'] ) ) { $this->caller( $info['caller'] ); } return $this; } /** * Manually set the table name to be passed to IDatabase::insert() * * @param string $table The unqualified name of a table * @param-taint $table exec_sql * @return $this */ public function table( $table ) { $this->table = $table; return $this; } /** * Set table for the query. Alias for table(). * * @param string $table The unqualified name of a table * @param-taint $table exec_sql * @return $this */ public function insertInto( string $table ) { return $this->table( $table ); } /** * Set table for the query. Alias for table(). * * @param string $table The unqualified name of a table * @param-taint $table exec_sql * @return $this */ public function insert( string $table ) { return $this->table( $table ); } /** * Manually set an option in the $options array to be passed to * IDatabase::insert() * * @param string $name The option name * @param mixed $value The option value, or null for a boolean option * @return $this */ public function option( $name, $value = null ) { if ( $value === null ) { $this->options[] = $name; } else { $this->options[$name] = $value; } return $this; } /** * Manually set multiple options in the $options array to be passed to * IDatabase::insert(). * * @param array $options * @return $this */ public function options( array $options ) { $this->options = array_merge( $this->options, $options ); return $this; } /** * Add rows to be inserted. * * @param list<array> $rows * $rows should be an integer-keyed list of such string-keyed maps, defining a list of new rows. * The keys in each map must be identical to each other and in the same order. * The rows must not collide with each other. * * @return $this */ public function rows( array $rows ) { $this->rows = array_merge( $this->rows, $rows ); return $this; } /** * Add one row to be inserted. * * @param array $row * $row must be a string-keyed map of (column name => value) defining a new row. Values are * treated as literals and quoted appropriately; null is interpreted as NULL. * * @return $this */ public function row( array $row ) { $this->rows[] = $row; return $this; } /** * Enable the IGNORE option. * * Skip insertion of rows that would cause unique key conflicts. * IDatabase::affectedRows() can be used to determine how many rows were inserted. * * @return $this */ public function ignore() { $this->options[] = 'IGNORE'; return $this; } /** * Do an update instead of insert * * @return $this */ public function onDuplicateKeyUpdate() { $this->upsert = true; return $this; } /** * Set the unique index fields * * @param string|string[] $uniqueIndexFields * @return $this */ public function uniqueIndexFields( $uniqueIndexFields ) { if ( is_string( $uniqueIndexFields ) ) { $uniqueIndexFields = [ $uniqueIndexFields ]; } $this->uniqueIndexFields = $uniqueIndexFields; return $this; } /** * Add SET part to the query. It takes an array containing arrays of column names map to * the set values. * * @param string|array<string,?scalar|RawSQLValue>|array<int,string> $set * @param-taint $set exec_sql_numkey * * Combination map/list where each string-keyed entry maps a column * to a literal assigned value and each integer-keyed value is a SQL expression in the * format of a column assignment within UPDATE...SET. The (column => value) entries are * convenient due to automatic value quoting and conversion of null to NULL. The SQL * assignment format is useful for updates like "column = column + X". All assignments * have no defined execution order, so they should not depend on each other. Do not * modify AUTOINCREMENT or UUID columns in assignments. * * Untrusted user input is safe in the values of string keys, however untrusted * input must not be used in the array key names or in the values of numeric keys. * Escaping of untrusted input used in values of numeric keys should be done via * IDatabase::addQuotes() * * @return $this */ public function set( $set ) { if ( is_array( $set ) ) { foreach ( $set as $key => $value ) { if ( is_int( $key ) ) { $this->set[] = $value; } else { $this->set[$key] = $value; } } } else { $this->set[] = $set; } return $this; } /** * Add set values to the query. Alias for set(). * * @param string|array<string,?scalar|RawSQLValue>|array<int,string> $set * @param-taint $set exec_sql_numkey * @return $this */ public function andSet( $set ) { return $this->set( $set ); } /** * Set the method name to be included in an SQL comment. * * @param string $fname * @param-taint $fname exec_sql * @return $this */ public function caller( $fname ) { $this->caller = $fname; return $this; } /** * Run the constructed INSERT query. */ public function execute(): void { if ( !$this->rows ) { throw new UnexpectedValueException( __METHOD__ . ' can\'t have empty $rows value' ); } if ( $this->table === '' ) { throw new UnexpectedValueException( __METHOD__ . ' expects table not to be empty' ); } if ( $this->upsert && ( !$this->set || !$this->uniqueIndexFields ) ) { throw new UnexpectedValueException( __METHOD__ . ' called with upsert but no set value or unique key has been provided' ); } if ( !$this->upsert && ( $this->set || $this->uniqueIndexFields ) ) { throw new UnexpectedValueException( __METHOD__ . ' is not called with upsert but set value or unique key has been provided' ); } if ( $this->upsert ) { $this->db->upsert( $this->table, $this->rows, [ $this->uniqueIndexFields ], $this->set, $this->caller ); return; } $this->db->insert( $this->table, $this->rows, $this->caller, $this->options ); } /** * Get an associative array describing the query in terms of its raw parameters to * Database::insert(). This can be used to interface with legacy code. * * @return array The query info array, with keys: * - table: The table name * - rows: The rows array * - options: The query options * - upsert: Whether it's insert or upsert * - uniqueIndexFields: Fields of the unique index * - set: The set array * - caller: The caller signature */ public function getQueryInfo() { $info = [ 'table' => $this->table, 'rows' => $this->rows, 'upsert' => $this->upsert, 'set' => $this->set, 'uniqueIndexFields' => $this->uniqueIndexFields, 'options' => $this->options, ]; if ( $this->caller !== __CLASS__ ) { $info['caller'] = $this->caller; } return $info; } } PK ! ʎ�� � + rdbms/loadbalancer/LoadBalancerDisabled.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\Rdbms; use RuntimeException; /** * Placeholder LoadBalancer that throws an error upon attempts to access connections * * This is useful when running code with no config file present, e.g. during installation. * * @since 1.40 * @ingroup Database */ class LoadBalancerDisabled extends LoadBalancer { public function __construct( $params = [] ) { parent::__construct( [ 'servers' => [ [ 'type' => 'disabled', 'host' => '(disabled)', 'dbname' => null, 'load' => 1, ] ], 'trxProfiler' => $params['trxProfiler'] ?? null, 'srvCache' => $params['srvCache'] ?? null, 'wanCache' => $params['wanCache'] ?? null, 'localDomain' => $params['localDomain'] ?? '(disabled)', 'readOnlyReason' => $params['readOnlyReason'] ?? false, 'clusterName' => $params['clusterName'] ?? null, ] ); } /** * @param int $i * @param DatabaseDomain $domain * @param array $lbInfo * * @return never */ protected function reallyOpenConnection( $i, DatabaseDomain $domain, array $lbInfo ) { throw new RuntimeException( 'Database backend disabled' ); } /** * @param int $i Specific (overrides $groups) or virtual (DB_PRIMARY/DB_REPLICA) server index * @param string[]|string $groups Query group(s) in preference order; [] for the default group * @param string|false $domain DB domain ID or false for the local domain * @param int $flags Bitfield of CONN_* class constants * * @return never */ public function getConnection( $i, $groups = [], $domain = false, $flags = 0 ) { throw new RuntimeException( 'Database backend disabled' ); } /** * @internal Only to be used by DBConnRef * @param int $i Specific (overrides $groups) or virtual (DB_PRIMARY/DB_REPLICA) server index * @param string[]|string $groups Query group(s) in preference order; [] for the default group * @param string|false $domain DB domain ID or false for the local domain * @param int $flags Bitfield of CONN_* class constants (e.g. CONN_TRX_AUTOCOMMIT) * @return never */ public function getConnectionInternal( $i, $groups = [], $domain = false, $flags = 0 ): IDatabase { throw new RuntimeException( 'Database backend disabled' ); } /** * @param int $i Specific (overrides $groups) or virtual (DB_PRIMARY/DB_REPLICA) server index * @param string[]|string $groups Query group(s) in preference order; [] for the default group * @param string|false $domain DB domain ID or false for the local domain * @param int $flags Bitfield of CONN_* class constants * * @return never */ public function getConnectionRef( $i, $groups = [], $domain = false, $flags = 0 ): DBConnRef { throw new RuntimeException( 'Database backend disabled' ); } /** * @param int $i Specific (overrides $groups) or virtual (DB_PRIMARY/DB_REPLICA) server index * @param string[]|string $groups Query group(s) in preference order; [] for the default group * @param string|false $domain DB domain ID or false for the local domain * @param int $flags Bitfield of CONN_* class constants * * @return never */ public function getMaintenanceConnectionRef( $i, $groups = [], $domain = false, $flags = 0 ): DBConnRef { throw new RuntimeException( 'Database backend disabled' ); } } PK ! `O��� � # rdbms/loadbalancer/LoadBalancer.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\Rdbms; use ArrayUtils; use InvalidArgumentException; use Liuggio\StatsdClient\Factory\StatsdDataFactoryInterface; use LogicException; use Psr\Log\LoggerInterface; use Psr\Log\NullLogger; use RuntimeException; use Throwable; use UnexpectedValueException; use Wikimedia\ObjectCache\BagOStuff; use Wikimedia\ObjectCache\EmptyBagOStuff; use Wikimedia\ObjectCache\WANObjectCache; use Wikimedia\ScopedCallback; use Wikimedia\Stats\NullStatsdDataFactory; /** * @see ILoadBalancer * @ingroup Database */ class LoadBalancer implements ILoadBalancerForOwner { /** @var ILoadMonitor */ private $loadMonitor; /** @var BagOStuff */ private $srvCache; /** @var WANObjectCache */ private $wanCache; /** @var DatabaseFactory */ private $databaseFactory; /** @var TransactionProfiler */ private $trxProfiler; /** @var StatsdDataFactoryInterface */ private $statsd; /** @var LoggerInterface */ private $logger; /** @var callable Exception logger */ private $errorLogger; /** @var DatabaseDomain Local DB domain ID and default for new connections */ private $localDomain; /** @var array<string,array<int,Database[]>> Map of (connection pool => server index => Database[]) */ private $conns; /** @var string The name of the DB cluster */ private $clusterName; /** @var ServerInfo */ private $serverInfo; /** @var array<string,array<int,int|float>> Map of (group => server index => weight) */ private $groupLoads; /** @var string|null Default query group to use with getConnection() */ private $defaultGroup; /** @var array[] $aliases Map of (table => (dbname, schema, prefix) map) */ private $tableAliases = []; /** @var string[] Map of (index alias => index) */ private $indexAliases = []; /** @var DatabaseDomain[]|string[] Map of (domain alias => DB domain) */ private $domainAliases = []; /** @var callable[] Map of (name => callable) */ private $trxRecurringCallbacks = []; /** @var bool[] Map of (domain => whether to use "temp tables only" mode) */ private $tempTablesOnlyMode = []; /** @var string|false Explicit DBO_TRX transaction round active or false if none */ private $trxRoundId = false; /** @var string Stage of the current transaction round in the transaction round life-cycle */ private $trxRoundStage = self::ROUND_CURSORY; /** @var int[] The group replica server indexes keyed by group */ private $readIndexByGroup = []; /** @var DBPrimaryPos|null Replication sync position or false if not set */ private $waitForPos; /** @var bool Whether a lagged replica DB was used */ private $laggedReplicaMode = false; /** @var string|false Reason this instance is read-only or false if not */ private $readOnlyReason = false; /** @var int Total number of new connections ever made with this instance */ private $connectionCounter = 0; /** @var bool */ private $disabled = false; private ?ChronologyProtector $chronologyProtector = null; /** @var bool Whether the session consistency callback already executed */ private $chronologyProtectorCalled = false; /** @var Database|null The last connection handle that caused a problem */ private $lastErrorConn; /** @var DatabaseDomain[] Map of (domain ID => domain instance) */ private $nonLocalDomainCache = []; /** * @var int Modification counter for invalidating connections held by * DBConnRef instances. This is bumped by reconfigure(). */ private $modcount = 0; /** The "server index" LB info key; see {@link IDatabase::getLBInfo()} */ private const INFO_SERVER_INDEX = 'serverIndex'; /** The "connection category" LB info key; see {@link IDatabase::getLBInfo()} */ private const INFO_CONN_CATEGORY = 'connCategory'; /** Warn when this many connection are held */ private const CONN_HELD_WARN_THRESHOLD = 10; /** Default 'waitTimeout' when unspecified */ private const MAX_WAIT_DEFAULT = 10; /** Seconds to cache primary DB server read-only status */ private const TTL_CACHE_READONLY = 5; /** A category of connections that are tracked and transaction round aware */ private const CATEGORY_ROUND = 'round'; /** A category of connections that are tracked and in autocommit-mode */ private const CATEGORY_AUTOCOMMIT = 'auto-commit'; /** A category of connections that are untracked and in gauge-mode */ private const CATEGORY_GAUGE = 'gauge'; /** Transaction round, explicit or implicit, has not finished writing */ private const ROUND_CURSORY = 'cursory'; /** Transaction round writes are complete and ready for pre-commit checks */ private const ROUND_FINALIZED = 'finalized'; /** Transaction round passed final pre-commit checks */ private const ROUND_APPROVED = 'approved'; /** Transaction round was committed and post-commit callbacks must be run */ private const ROUND_COMMIT_CALLBACKS = 'commit-callbacks'; /** Transaction round was rolled back and post-rollback callbacks must be run */ private const ROUND_ROLLBACK_CALLBACKS = 'rollback-callbacks'; /** Transaction round encountered an error */ private const ROUND_ERROR = 'error'; /** @var int Idiom for getExistingReaderIndex() meaning "no index selected" */ private const READER_INDEX_NONE = -1; public function __construct( array $params ) { $this->configure( $params ); $this->conns = self::newTrackedConnectionsArray(); } /** * @param array $params A database configuration array, see $wgLBFactoryConf. * * @return void */ protected function configure( array $params ): void { $this->localDomain = isset( $params['localDomain'] ) ? DatabaseDomain::newFromId( $params['localDomain'] ) : DatabaseDomain::newUnspecified(); $this->serverInfo = new ServerInfo(); $this->groupLoads = [ self::GROUP_GENERIC => [] ]; foreach ( $this->serverInfo->normalizeServerMaps( $params['servers'] ?? [] ) as $i => $server ) { $this->serverInfo->addServer( $i, $server ); foreach ( $server['groupLoads'] as $group => $weight ) { $this->groupLoads[$group][$i] = $weight; } $this->groupLoads[self::GROUP_GENERIC][$i] = $server['load']; } // If the cluster name is not specified, fallback to the current primary name $this->clusterName = $params['clusterName'] ?? $this->serverInfo->getServerName( ServerInfo::WRITER_INDEX ); if ( isset( $params['readOnlyReason'] ) && is_string( $params['readOnlyReason'] ) ) { $this->readOnlyReason = $params['readOnlyReason']; } $this->srvCache = $params['srvCache'] ?? new EmptyBagOStuff(); $this->wanCache = $params['wanCache'] ?? WANObjectCache::newEmpty(); // Note: this parameter is normally absent. It is injectable for testing purposes only. $this->databaseFactory = $params['databaseFactory'] ?? new DatabaseFactory( $params ); $this->errorLogger = $params['errorLogger'] ?? static function ( Throwable $e ) { trigger_error( get_class( $e ) . ': ' . $e->getMessage(), E_USER_WARNING ); }; $this->logger = $params['logger'] ?? new NullLogger(); $this->trxProfiler = $params['trxProfiler'] ?? new TransactionProfiler(); $this->statsd = $params['statsdDataFactory'] ?? new NullStatsdDataFactory(); // Set up LoadMonitor $loadMonitorConfig = $params['loadMonitor'] ?? [ 'class' => LoadMonitorNull::class ]; $compat = [ 'LoadMonitor' => LoadMonitor::class, 'LoadMonitorNull' => LoadMonitorNull::class ]; $class = $loadMonitorConfig['class']; // @phan-suppress-next-line PhanImpossibleCondition if ( isset( $compat[$class] ) ) { $class = $compat[$class]; } $this->loadMonitor = new $class( $this, $this->srvCache, $this->wanCache, $loadMonitorConfig ); $this->loadMonitor->setLogger( $this->logger ); $this->loadMonitor->setStatsdDataFactory( $this->statsd ); if ( isset( $params['chronologyProtector'] ) ) { $this->chronologyProtector = $params['chronologyProtector']; } if ( isset( $params['roundStage'] ) ) { if ( $params['roundStage'] === self::STAGE_POSTCOMMIT_CALLBACKS ) { $this->trxRoundStage = self::ROUND_COMMIT_CALLBACKS; } elseif ( $params['roundStage'] === self::STAGE_POSTROLLBACK_CALLBACKS ) { $this->trxRoundStage = self::ROUND_ROLLBACK_CALLBACKS; } } $group = $params['defaultGroup'] ?? self::GROUP_GENERIC; $this->defaultGroup = isset( $this->groupLoads[ $group ] ) ? $group : self::GROUP_GENERIC; } private static function newTrackedConnectionsArray() { // Note that CATEGORY_GAUGE connections are untracked return [ self::CATEGORY_ROUND => [], self::CATEGORY_AUTOCOMMIT => [] ]; } public function getClusterName(): string { return $this->clusterName; } public function getLocalDomainID(): string { return $this->localDomain->getId(); } public function resolveDomainID( $domain ): string { return $this->resolveDomainInstance( $domain )->getId(); } /** * @param DatabaseDomain|string|false $domain * @return DatabaseDomain */ final protected function resolveDomainInstance( $domain ): DatabaseDomain { if ( $domain instanceof DatabaseDomain ) { return $domain; // already a domain instance } elseif ( $domain === false || $domain === $this->localDomain->getId() ) { return $this->localDomain; } elseif ( isset( $this->domainAliases[$domain] ) ) { $this->domainAliases[$domain] = DatabaseDomain::newFromId( $this->domainAliases[$domain] ); return $this->domainAliases[$domain]; } $cachedDomain = $this->nonLocalDomainCache[$domain] ?? null; if ( $cachedDomain === null ) { $cachedDomain = DatabaseDomain::newFromId( $domain ); $this->nonLocalDomainCache = [ $domain => $cachedDomain ]; } return $cachedDomain; } /** * Get the first group in $groups with assigned servers, falling back to the default group * * @param string[]|string|false $groups Query group(s) in preference order, [], or false * @param int $i Specific server index or DB_PRIMARY/DB_REPLICA * @return string Query group */ private function resolveGroups( $groups, $i ) { // If a specific replica server was specified, then $groups makes no sense if ( $i > 0 && $groups !== [] && $groups !== false ) { $list = implode( ', ', (array)$groups ); throw new LogicException( "Query group(s) ($list) given with server index (#$i)" ); } if ( $groups === [] || $groups === false || $groups === $this->defaultGroup ) { $resolvedGroup = $this->defaultGroup; } elseif ( is_string( $groups ) ) { $resolvedGroup = isset( $this->groupLoads[$groups] ) ? $groups : $this->defaultGroup; } elseif ( is_array( $groups ) ) { $resolvedGroup = $this->defaultGroup; foreach ( $groups as $group ) { if ( isset( $this->groupLoads[$group] ) ) { $resolvedGroup = $group; break; } } } else { $resolvedGroup = $this->defaultGroup; } return $resolvedGroup; } /** * Sanitize connection flags provided by a call to getConnection() * * @param int $flags Bitfield of class CONN_* constants * @param string $domain Database domain * @return int Sanitized bitfield */ protected function sanitizeConnectionFlags( $flags, $domain ) { if ( self::fieldHasBit( $flags, self::CONN_TRX_AUTOCOMMIT ) ) { // Callers use CONN_TRX_AUTOCOMMIT to bypass REPEATABLE-READ staleness without // resorting to row locks (e.g. FOR UPDATE) or to make small out-of-band commits // during larger transactions. This is useful for avoiding lock contention. // Assuming all servers are of the same type (or similar), which is overwhelmingly // the case, use the primary server information to get the attributes. The information // for $i cannot be used since it might be DB_REPLICA, which might require connection // attempts in order to be resolved into a real server index. $attributes = $this->getServerAttributes( ServerInfo::WRITER_INDEX ); if ( $attributes[Database::ATTR_DB_LEVEL_LOCKING] ) { // The RDBMS does not support concurrent writes (e.g. SQLite), so attempts // to use separate connections would just cause self-deadlocks. Note that // REPEATABLE-READ staleness is not an issue since DB-level locking means // that transactions are Strict Serializable anyway. $flags &= ~self::CONN_TRX_AUTOCOMMIT; $type = $this->serverInfo->getServerType( ServerInfo::WRITER_INDEX ); $this->logger->info( __METHOD__ . ": CONN_TRX_AUTOCOMMIT disallowed ($type)" ); } elseif ( isset( $this->tempTablesOnlyMode[$domain] ) ) { // T202116: integration tests are active and queries should be all be using // temporary clone tables (via prefix). Such tables are not visible across // different connections nor can there be REPEATABLE-READ snapshot staleness, // so use the same connection for everything. $flags &= ~self::CONN_TRX_AUTOCOMMIT; } } return $flags; } /** * @param IDatabase $conn * @param int $flags * @throws DBUnexpectedError */ private function enforceConnectionFlags( IDatabase $conn, $flags ) { if ( self::fieldHasBit( $flags, self::CONN_TRX_AUTOCOMMIT ) || // Handles with open transactions are avoided since they might be subject // to REPEATABLE-READ snapshots, which could affect the lag estimate query. self::fieldHasBit( $flags, self::CONN_UNTRACKED_GAUGE ) ) { if ( $conn->trxLevel() ) { throw new DBUnexpectedError( $conn, 'Handle requested with autocommit-mode yet it has a transaction' ); } $conn->clearFlag( $conn::DBO_TRX ); // auto-commit mode } } /** * @param array<int,int|float> $loads Map of (server index => weight) for a load group * @param int|float $sessionLagLimit Additional maximum lag threshold imposed by the session; * use INF if none applies. Servers will count as lagged if their lag exceeds either this * value or the configured "max lag" value. * @return int|false Index of a non-lagged server with non-zero weight; false if none */ private function getRandomNonLagged( array $loads, $sessionLagLimit = INF ) { $lags = $this->getLagTimes(); // Unset excessively lagged servers from the load group foreach ( $lags as $i => $lag ) { if ( $i !== ServerInfo::WRITER_INDEX ) { // How much lag normally counts as "excessive" for this server $maxServerLag = $this->serverInfo->getServerMaxLag( $i ); // How much lag counts as "excessive" for this server given the session $maxServerLag = min( $maxServerLag, $sessionLagLimit ); $srvName = $this->serverInfo->getServerName( $i ); if ( $lag === false && !is_infinite( $maxServerLag ) ) { $this->logger->debug( __METHOD__ . ": server {db_server} is not replicating?", [ 'db_server' => $srvName ] ); unset( $loads[$i] ); } elseif ( $lag > $maxServerLag ) { $this->logger->debug( __METHOD__ . ": server {db_server} has {lag} seconds of lag (>= {maxlag})", [ 'db_server' => $srvName, 'lag' => $lag, 'maxlag' => $maxServerLag ] ); unset( $loads[$i] ); } } } if ( array_sum( $loads ) == 0 ) { // All the replicas with non-zero weight are lagged and the primary has zero load. // Inform caller so that it can use switch to read-only mode and use a lagged replica. return false; } // Return a server index based on weighted random selection return ArrayUtils::pickRandom( $loads ); } public function getReaderIndex( $group = false ) { $group = is_string( $group ) ? $group : self::GROUP_GENERIC; if ( !$this->serverInfo->hasReplicaServers() ) { // There is only one possible server to use (the primary) return ServerInfo::WRITER_INDEX; } $index = $this->getExistingReaderIndex( $group ); if ( $index !== self::READER_INDEX_NONE ) { // A reader index was already selected for this query group. Keep using it, // since any session replication position was already waited on and any // active transaction will be reused (e.g. for point-in-time snapshots). return $index; } // Get the server weight array for this load group $loads = $this->groupLoads[$group] ?? []; if ( !$loads ) { $this->logger->info( __METHOD__ . ": no loads for group $group" ); return false; } // Load any session replication positions, before any connection attempts, // since reading them afterwards can only cause more delay due to possibly // seeing even higher replication positions (e.g. from concurrent requests). $this->loadSessionPrimaryPos(); // Scale the configured load weights according to each server's load/state. // This can sometimes trigger server connections due to cache regeneration. $this->loadMonitor->scaleLoads( $loads ); // Pick a server, accounting for load weights, lag, and session consistency $i = $this->pickReaderIndex( $loads ); if ( $i === false ) { // Connection attempts failed return false; } // If data seen by queries is expected to reflect writes from a prior transaction, // then wait for the chosen server to apply those changes. This is used to improve // session consistency. if ( !$this->awaitSessionPrimaryPos( $i ) ) { // Data will be outdated compared to what was expected $this->setLaggedReplicaMode(); } // Keep using this server for DB_REPLICA handles for this group if ( $i < 0 ) { throw new UnexpectedValueException( "Cannot set a negative read server index" ); } $this->readIndexByGroup[$group] = $i; $serverName = $this->getServerName( $i ); $this->logger->debug( __METHOD__ . ": using server $serverName for group '$group'" ); return $i; } /** * Get the server index chosen for DB_REPLICA connections for the given query group * * @param string $group Query group; use false for the generic group * @return int Specific server index or LoadBalancer::READER_INDEX_NONE if none was chosen */ protected function getExistingReaderIndex( $group ) { return $this->readIndexByGroup[$group] ?? self::READER_INDEX_NONE; } /** * Pick a server that is reachable and preferably non-lagged based on the load weights * * This will leave the server connection open within the pool for reuse * * @param array<int,int|float> $loads Map of (server index => weight) for a load group * @return int|false Server index to use as the load group reader index; false on failure */ private function pickReaderIndex( array $loads ) { if ( $loads === [] ) { throw new InvalidArgumentException( "Load group array is empty" ); } $i = false; // Quickly look through the available servers for a server that meets criteria... $currentLoads = $loads; while ( count( $currentLoads ) ) { if ( $this->waitForPos && $this->waitForPos->asOfTime() ) { $this->logger->debug( __METHOD__ . ": session has replication position" ); // ChronologyProtector::getSessionPrimaryPos called in loadSessionPrimaryPos() // sets "waitForPos" for session consistency. This triggers doWait() after // connect, so it's especially good to avoid lagged servers so as to avoid // excessive delay in that method. $ago = microtime( true ) - $this->waitForPos->asOfTime(); // Aim for <= 1 second of waiting (being too picky can backfire) $i = $this->getRandomNonLagged( $currentLoads, $ago + 1 ); } else { // Any server with less lag than it's 'max lag' param is preferable $i = $this->getRandomNonLagged( $currentLoads ); } if ( $i === false && count( $currentLoads ) ) { $this->setLaggedReplicaMode(); // All replica DBs lagged, just pick anything. $i = ArrayUtils::pickRandom( $currentLoads ); } if ( $i === false ) { // pickRandom() returned false. // This is permanent and means the configuration or LoadMonitor // wants us to return false. $this->logger->debug( __METHOD__ . ": no suitable server found" ); return false; } $serverName = $this->getServerName( $i ); $this->logger->debug( __METHOD__ . ": connecting to $serverName..." ); // Get a connection to this server without triggering complementary connections // to other servers (due to things like lag or read-only checks). We want to avoid // the risk of overhead and recursion here. $conn = $this->getServerConnection( $i, self::DOMAIN_ANY, self::CONN_SILENCE_ERRORS ); if ( !$conn ) { $this->logger->warning( __METHOD__ . ": failed connecting to $serverName" ); unset( $currentLoads[$i] ); // avoid this server next iteration continue; } // Return this server break; } // If all servers were down, quit now if ( $currentLoads === [] ) { $this->logger->error( __METHOD__ . ": all servers down" ); } return $i; } public function waitForAll( DBPrimaryPos $pos, $timeout = null ) { $timeout = $timeout ?: self::MAX_WAIT_DEFAULT; $oldPos = $this->waitForPos; try { $this->waitForPos = $pos; $failedReplicas = []; foreach ( $this->serverInfo->getStreamingReplicaIndexes() as $i ) { if ( $this->serverHasLoadInAnyGroup( $i ) ) { $start = microtime( true ); $ok = $this->awaitSessionPrimaryPos( $i, $timeout ); if ( !$ok ) { $failedReplicas[] = $this->getServerName( $i ); } $timeout -= intval( microtime( true ) - $start ); } } // Stop spamming logs when only one replica is lagging and we have 5+ replicas. // Mediawiki automatically stops sending queries to the lagged one. $failed = $failedReplicas && ( count( $failedReplicas ) > 1 || $this->getServerCount() < 5 ); if ( $failed ) { $this->logger->error( "Timed out waiting for replication to reach {raw_pos}", [ 'raw_pos' => $pos->__toString(), 'failed_hosts' => $failedReplicas, 'timeout' => $timeout, 'exception' => new RuntimeException() ] ); } return !$failed; } finally { // Restore the old position; this is used for throttling, not lag-protection $this->waitForPos = $oldPos; } } /** * @param int $i Specific server index * @return bool */ private function serverHasLoadInAnyGroup( $i ) { foreach ( $this->groupLoads as $loadsByIndex ) { if ( ( $loadsByIndex[$i] ?? 0 ) > 0 ) { return true; } } return false; } public function getAnyOpenConnection( $i, $flags = 0 ) { $i = ( $i === self::DB_PRIMARY ) ? ServerInfo::WRITER_INDEX : $i; $conn = false; foreach ( $this->conns as $type => $poolConnsByServer ) { if ( $i === self::DB_REPLICA ) { // Consider all existing connections to any server $applicableConnsByServer = $poolConnsByServer; } else { // Consider all existing connections to a specific server $applicableConnsByServer = isset( $poolConnsByServer[$i] ) ? [ $i => $poolConnsByServer[$i] ] : []; } $conn = $this->pickAnyOpenConnection( $applicableConnsByServer ); if ( $conn ) { $this->logger->debug( __METHOD__ . ": found '$type' connection to #$i." ); break; } } if ( $conn ) { $this->enforceConnectionFlags( $conn, $flags ); } return $conn; } /** * @param Database[][] $connsByServer Map of (server index => array of DB handles) * @return IDatabaseForOwner|false An appropriate open connection or false if none found */ private function pickAnyOpenConnection( array $connsByServer ) { foreach ( $connsByServer as $i => $conns ) { foreach ( $conns as $conn ) { if ( !$conn->isOpen() ) { $this->logger->warning( __METHOD__ . ": pooled DB handle for {db_server} (#$i) has no open connection.", $this->getConnLogContext( $conn ) ); continue; // some sort of error occurred? } return $conn; } } return false; } /** * Wait for a given replica DB to catch up to the primary DB pos stored in "waitForPos" * * @see loadSessionPrimaryPos() * * @param int $index Specific server index * @param int|null $timeout Max seconds to wait; default is "waitTimeout" * @return bool Success */ private function awaitSessionPrimaryPos( $index, $timeout = null ) { $timeout = max( 1, intval( $timeout ?: self::MAX_WAIT_DEFAULT ) ); if ( !$this->waitForPos || $index === ServerInfo::WRITER_INDEX ) { return true; } $srvName = $this->getServerName( $index ); // Check if we already know that the DB has reached this point $key = $this->srvCache->makeGlobalKey( __CLASS__, 'last-known-pos', $srvName, 'v2' ); /** @var DBPrimaryPos $knownReachedPos */ $position = $this->srvCache->get( $key ); if ( !is_array( $position ) ) { $knownReachedPos = null; } else { $class = $position['_type_']; $knownReachedPos = $class::newFromArray( $position ); } if ( $knownReachedPos instanceof DBPrimaryPos && $knownReachedPos->hasReached( $this->waitForPos ) ) { $this->logger->debug( __METHOD__ . ": replica DB {db_server} known to be caught up (pos >= $knownReachedPos).", [ 'db_server' => $srvName ] ); return true; } $close = false; // close the connection afterwards $flags = self::CONN_SILENCE_ERRORS; // Check if there is an existing connection that can be used $conn = $this->getAnyOpenConnection( $index, $flags ); if ( !$conn ) { // Get a connection to this server without triggering complementary connections // to other servers (due to things like lag or read-only checks). We want to avoid // the risk of overhead and recursion here. $conn = $this->getServerConnection( $index, self::DOMAIN_ANY, $flags ); if ( !$conn ) { $this->logger->warning( __METHOD__ . ': failed to connect to {db_server}', [ 'db_server' => $srvName ] ); return false; } // Avoid connection spam in waitForAll() when connections // are made just for the sake of doing this lag check. $close = true; } $this->logger->info( __METHOD__ . ': waiting for replica DB {db_server} to catch up...', $this->getConnLogContext( $conn ) ); $result = $conn->primaryPosWait( $this->waitForPos, $timeout ); $ok = ( $result !== null && $result != -1 ); if ( $ok ) { // Remember that the DB reached this point $this->srvCache->set( $key, $this->waitForPos->toArray(), BagOStuff::TTL_DAY ); } if ( $close ) { $this->closeConnection( $conn ); } return $ok; } public function getConnection( $i, $groups = [], $domain = false, $flags = 0 ) { if ( self::fieldHasBit( $flags, self::CONN_SILENCE_ERRORS ) ) { throw new UnexpectedValueException( __METHOD__ . ' got CONN_SILENCE_ERRORS; connection is already deferred' ); } $domain = $this->resolveDomainID( $domain ); $role = ( $i === self::DB_PRIMARY || $i === ServerInfo::WRITER_INDEX ) ? self::DB_PRIMARY : self::DB_REPLICA; return new DBConnRef( $this, [ $i, $groups, $domain, $flags ], $role, $this->modcount ); } public function getConnectionInternal( $i, $groups = [], $domain = false, $flags = 0 ): IDatabase { $domain = $this->resolveDomainID( $domain ); $group = $this->resolveGroups( $groups, $i ); $flags = $this->sanitizeConnectionFlags( $flags, $domain ); // If given DB_PRIMARY/DB_REPLICA, resolve it to a specific server index. Resolving // DB_REPLICA might trigger getServerConnection() calls due to the getReaderIndex() // connectivity checks or LoadMonitor::scaleLoads() server state cache regeneration. // The use of getServerConnection() instead of getConnection() avoids infinite loops. $serverIndex = $i; if ( $i === self::DB_PRIMARY ) { $serverIndex = ServerInfo::WRITER_INDEX; } elseif ( $i === self::DB_REPLICA ) { $groupIndex = $this->getReaderIndex( $group ); if ( $groupIndex !== false ) { // Group connection succeeded $serverIndex = $groupIndex; } if ( $serverIndex < 0 ) { $this->reportConnectionError( 'could not connect to any replica DB server' ); } } elseif ( !$this->serverInfo->hasServerIndex( $i ) ) { throw new UnexpectedValueException( "Invalid server index index #$i" ); } // Get an open connection to that server (might trigger a new connection) return $this->getServerConnection( $serverIndex, $domain, $flags ); } public function getServerConnection( $i, $domain, $flags = 0 ) { $domainInstance = DatabaseDomain::newFromId( $domain ); // Number of connections made before getting the server index and handle $priorConnectionsMade = $this->connectionCounter; // Get an open connection to this server (might trigger a new connection) $conn = $this->reuseOrOpenConnectionForNewRef( $i, $domainInstance, $flags ); // Throw an error or otherwise bail out if the connection attempt failed if ( !( $conn instanceof IDatabaseForOwner ) ) { if ( !self::fieldHasBit( $flags, self::CONN_SILENCE_ERRORS ) ) { $this->reportConnectionError(); } return false; } // Profile any new connections caused by this method if ( $this->connectionCounter > $priorConnectionsMade ) { $this->trxProfiler->recordConnection( $conn->getServerName(), $conn->getDBname(), ( $i === ServerInfo::WRITER_INDEX && $this->hasStreamingReplicaServers() ) ); } if ( !$conn->isOpen() ) { $this->lastErrorConn = $conn; // Connection was made but later unrecoverably lost for some reason. // Do not return a handle that will just throw exceptions on use, but // let the calling code, e.g. getReaderIndex(), try another server. if ( !self::fieldHasBit( $flags, self::CONN_SILENCE_ERRORS ) ) { $this->reportConnectionError(); } return false; } return $conn; } /** * @deprecated since 1.39. */ public function getConnectionRef( $i, $groups = [], $domain = false, $flags = 0 ): DBConnRef { wfDeprecated( __METHOD__, '1.39' ); // @phan-suppress-next-line PhanTypeMismatchReturnSuperType to be removed soon return $this->getConnection( $i, $groups, $domain, $flags ); } public function getMaintenanceConnectionRef( $i, $groups = [], $domain = false, $flags = 0 ): DBConnRef { if ( self::fieldHasBit( $flags, self::CONN_SILENCE_ERRORS ) ) { throw new UnexpectedValueException( __METHOD__ . ' CONN_SILENCE_ERRORS is not supported' ); } $domain = $this->resolveDomainID( $domain ); $role = ( $i === self::DB_PRIMARY || $i === ServerInfo::WRITER_INDEX ) ? self::DB_PRIMARY : self::DB_REPLICA; return new DBConnRef( $this, [ $i, $groups, $domain, $flags ], $role, $this->modcount ); } /** * Get a live connection handle to the given domain * * This will reuse an existing tracked connection when possible. In some cases, this * involves switching the DB domain of an existing handle in order to reuse it. If no * existing handles can be reused, then a new connection will be made. * * @param int $i Specific server index * @param DatabaseDomain $domain Database domain ID required by the reference * @param int $flags Bit field of class CONN_* constants * @return IDatabase|null Database or null on error * @throws DBError When database selection fails * @throws InvalidArgumentException When the server index is invalid * @throws UnexpectedValueException When the DB domain of the connection is corrupted * @throws DBAccessError If disable() was called */ private function reuseOrOpenConnectionForNewRef( $i, DatabaseDomain $domain, $flags = 0 ) { // Figure out which connection pool to use based on the flags if ( $this->fieldHasBit( $flags, self::CONN_UNTRACKED_GAUGE ) ) { // Use low timeouts, use autocommit mode, ignore transaction rounds $category = self::CATEGORY_GAUGE; } elseif ( self::fieldHasBit( $flags, self::CONN_TRX_AUTOCOMMIT ) ) { // Use autocommit mode, ignore transaction rounds $category = self::CATEGORY_AUTOCOMMIT; } else { // Respect DBO_DEFAULT, respect transaction rounds $category = self::CATEGORY_ROUND; } $conn = null; // Reuse a free connection in the pool from any domain if possible. There should only // be one connection in this pool unless either: // - a) IDatabase::databasesAreIndependent() returns true (e.g. postgres) and two // or more database domains have been used during the load balancer's lifetime // - b) Two or more nested function calls used getConnection() on different domains. foreach ( ( $this->conns[$category][$i] ?? [] ) as $poolConn ) { // Check if any required DB domain changes for the new reference are possible // Calling selectDomain() would trigger a reconnect, which will break if a // transaction is active or if there is any other meaningful session state. $isShareable = !( $poolConn->databasesAreIndependent() && $domain->getDatabase() !== null && $domain->getDatabase() !== $poolConn->getDBname() ); if ( $isShareable ) { $conn = $poolConn; // Make any required DB domain changes for the new reference if ( !$domain->isUnspecified() ) { $conn->selectDomain( $domain ); } $this->logger->debug( __METHOD__ . ": reusing connection for $i/$domain" ); break; } } // If necessary, try to open a new connection and add it to the pool if ( !$conn ) { $conn = $this->reallyOpenConnection( $i, $domain, [ self::INFO_CONN_CATEGORY => $category ] ); if ( $conn->isOpen() ) { // Make Database::isReadOnly() respect server-side and configuration-based // read-only mode. Note that replica handles are always seen as read-only // in Database::isReadOnly() and Database::assertIsWritablePrimary(). if ( $i === ServerInfo::WRITER_INDEX ) { if ( $this->readOnlyReason !== false ) { $readOnlyReason = $this->readOnlyReason; } elseif ( $this->isPrimaryRunningReadOnly( $conn ) ) { $readOnlyReason = 'The primary database server is running in read-only mode.'; } else { $readOnlyReason = false; } $conn->setLBInfo( $conn::LB_READ_ONLY_REASON, $readOnlyReason ); } // Connection obtained; check if it belongs to a tracked connection category if ( isset( $this->conns[$category] ) ) { // Track this connection for future reuse $this->conns[$category][$i][] = $conn; } } else { $this->logger->warning( __METHOD__ . ": connection error for $i/$domain" ); $this->lastErrorConn = $conn; $conn = null; } } if ( $conn instanceof IDatabaseForOwner ) { // Check to make sure that the right domain is selected $this->assertConnectionDomain( $conn, $domain ); // Check to make sure that the CONN_* flags are respected $this->enforceConnectionFlags( $conn, $flags ); } return $conn; } /** * Sanity check to make sure that the right domain is selected * * @param Database $conn * @param DatabaseDomain $domain * @throws DBUnexpectedError */ private function assertConnectionDomain( Database $conn, DatabaseDomain $domain ) { if ( !$domain->isCompatible( $conn->getDomainID() ) ) { throw new UnexpectedValueException( "Got connection to '{$conn->getDomainID()}', but expected one for '{$domain}'" ); } } public function getServerAttributes( $i ) { return $this->databaseFactory->attributesFromType( $this->getServerType( $i ), $this->serverInfo->getServerDriver( $i ) ); } /** * Open a new network connection to a server (uncached) * * Returns a Database object whether or not the connection was successful. * * @param int $i Specific server index * @param DatabaseDomain $domain Domain the connection is for, possibly unspecified * @param array $lbInfo Additional information for setLBInfo() * @return Database * @throws DBAccessError * @throws InvalidArgumentException */ protected function reallyOpenConnection( $i, DatabaseDomain $domain, array $lbInfo ) { if ( $this->disabled ) { throw new DBAccessError(); } $server = $this->serverInfo->getServerInfoStrict( $i ); if ( $lbInfo[self::INFO_CONN_CATEGORY] === self::CATEGORY_GAUGE ) { // Use low connection/read timeouts for connection used for gauging server health. // Gauge information should be cached and used to avoid outages. Indefinite hanging // while gauging servers would do the opposite. $server['connectTimeout'] = min( 1, $server['connectTimeout'] ?? INF ); $server['receiveTimeout'] = min( 1, $server['receiveTimeout'] ?? INF ); // Avoid implicit transactions and avoid any SET query for session variables during // Database::open(). If a server becomes slow, every extra query can cause significant // delays, even with low connect/receive timeouts. $server['flags'] ??= 0; $server['flags'] &= ~IDatabase::DBO_DEFAULT; $server['flags'] |= IDatabase::DBO_GAUGE; } else { // Use implicit transactions unless explicitly configured otherwise $server['flags'] ??= IDatabase::DBO_DEFAULT; } if ( !empty( $server['is static'] ) ) { $topologyRole = IDatabase::ROLE_STATIC_CLONE; } else { $topologyRole = ( $i === ServerInfo::WRITER_INDEX ) ? IDatabase::ROLE_STREAMING_MASTER : IDatabase::ROLE_STREAMING_REPLICA; } $conn = $this->databaseFactory->create( $server['type'], array_merge( $server, [ // Basic replication role information 'topologyRole' => $topologyRole, // Use the database specified in $domain (null means "none or entrypoint DB"); // fallback to the $server default if the RDBMs is an embedded library using a // file on disk since there would be nothing to access to without a DB/file name. 'dbname' => $this->getServerAttributes( $i )[Database::ATTR_DB_IS_FILE] ? ( $domain->getDatabase() ?? $server['dbname'] ?? null ) : $domain->getDatabase(), // Override the $server default schema with that of $domain if specified 'schema' => $domain->getSchema(), // Use the table prefix specified in $domain 'tablePrefix' => $domain->getTablePrefix(), 'srvCache' => $this->srvCache, 'logger' => $this->logger, 'errorLogger' => $this->errorLogger, 'trxProfiler' => $this->trxProfiler, 'lbInfo' => [ self::INFO_SERVER_INDEX => $i ] + $lbInfo ] ), Database::NEW_UNCONNECTED ); // Set alternative table/index names before any queries can be issued $conn->setTableAliases( $this->tableAliases ); $conn->setIndexAliases( $this->indexAliases ); // Account for any active transaction round and listeners if ( $i === ServerInfo::WRITER_INDEX ) { if ( $this->trxRoundId !== false ) { $this->applyTransactionRoundFlags( $conn ); } foreach ( $this->trxRecurringCallbacks as $name => $callback ) { $conn->setTransactionListener( $name, $callback ); } } // Make the connection handle live try { $conn->initConnection(); ++$this->connectionCounter; } catch ( DBConnectionError $e ) { $this->lastErrorConn = $conn; // ignore; let the DB handle the logging } if ( $conn->isOpen() ) { $this->logger->debug( __METHOD__ . ": opened new connection for $i/$domain" ); } else { $this->logger->warning( __METHOD__ . ": connection error for $i/{db_domain}", [ 'db_domain' => $domain->getId() ] ); } // Log when many connection are made during a single request/script $count = 0; foreach ( $this->conns as $poolConnsByServer ) { foreach ( $poolConnsByServer as $serverConns ) { $count += count( $serverConns ); } } if ( $count >= self::CONN_HELD_WARN_THRESHOLD ) { $this->logger->warning( __METHOD__ . ": {connections}+ connections made (primary={primarydb})", $this->getConnLogContext( $conn, [ 'connections' => $count, 'primarydb' => $this->serverInfo->getPrimaryServerName(), 'db_domain' => $domain->getId() ] ) ); } $this->assertConnectionDomain( $conn, $domain ); return $conn; } /** * Make sure that any "waitForPos" replication positions are loaded and available * * Each load balancer cluster has up to one replication position for the session. * These are used when data read by queries is expected to reflect writes caused * by a prior request/script from the same client. * * @see awaitSessionPrimaryPos() */ private function loadSessionPrimaryPos() { if ( !$this->chronologyProtectorCalled && $this->chronologyProtector ) { $this->chronologyProtectorCalled = true; $pos = $this->chronologyProtector->getSessionPrimaryPos( $this ); $this->logger->debug( __METHOD__ . ': executed chronology callback.' ); if ( $pos ) { if ( !$this->waitForPos || $pos->hasReached( $this->waitForPos ) ) { $this->waitForPos = $pos; } } } } /** * @param string $extraLbError Separat load balancer error * @throws DBConnectionError * @return never */ private function reportConnectionError( $extraLbError = '' ) { if ( $this->lastErrorConn instanceof IDatabaseForOwner ) { $srvName = $this->lastErrorConn->getServerName(); $lastDbError = $this->lastErrorConn->lastError() ?: 'unknown error'; $exception = new DBConnectionError( $this->lastErrorConn, $extraLbError ? "{$extraLbError}; {$lastDbError} ({$srvName})" : "{$lastDbError} ({$srvName})" ); if ( $extraLbError ) { $this->logger->warning( __METHOD__ . ": $extraLbError; {last_error} ({db_server})", $this->getConnLogContext( $this->lastErrorConn, [ 'method' => __METHOD__, 'last_error' => $lastDbError ] ) ); } } else { $exception = new DBConnectionError( null, $extraLbError ?: 'could not connect to the DB server' ); if ( $extraLbError ) { $this->logger->error( __METHOD__ . ": $extraLbError", [ 'method' => __METHOD__, 'last_error' => '(last connection error missing)' ] ); } } throw $exception; } public function getServerCount() { return $this->serverInfo->getServerCount(); } public function hasReplicaServers() { return $this->serverInfo->hasReplicaServers(); } public function hasStreamingReplicaServers() { return $this->serverInfo->hasStreamingReplicaServers(); } public function getServerName( $i ): string { return $this->serverInfo->getServerName( $i ); } public function getServerInfo( $i ) { return $this->serverInfo->getServerInfo( $i ); } public function getServerType( $i ) { return $this->serverInfo->getServerType( $i ); } public function getPrimaryPos() { $conn = $this->getAnyOpenConnection( ServerInfo::WRITER_INDEX ); if ( $conn ) { return $conn->getPrimaryPos(); } $conn = $this->getConnectionInternal( ServerInfo::WRITER_INDEX, self::CONN_SILENCE_ERRORS ); // @phan-suppress-next-line PhanRedundantCondition if ( !$conn ) { $this->reportConnectionError(); } // ::getConnectionInternal() should return IDatabaseForOwner but changing signature // is not straightforward (being implemented in Wikibase) '@phan-var IDatabaseForOwner $conn'; try { return $conn->getPrimaryPos(); } finally { $this->closeConnection( $conn ); } } /** * Apply updated configuration. * * This only unregisters servers that were removed in the new configuration. * It does not register new servers nor update the group load weights. * * This invalidates any open connections. However, existing connections may continue to be * used while they are in an active transaction. In that case, the old connection will be * discarded on the first operation after the transaction is complete. The next operation * will use a new connection based on the new configuration. * * @internal for use by LBFactory::reconfigure() * * @see DBConnRef::ensureConnection() * @see LBFactory::reconfigure() * * @param array $params A database configuration array, see $wgLBFactoryConf. * * @return void */ public function reconfigure( array $params ) { $anyServerDepooled = false; $paramServers = $params['servers']; $newIndexByServerIndex = $this->serverInfo->reconfigureServers( $paramServers ); foreach ( $newIndexByServerIndex as $i => $ni ) { if ( $ni !== null ) { // Server still exists in the new config $newWeightByGroup = $paramServers[$ni]['groupLoads'] ?? []; $newWeightByGroup[ILoadBalancer::GROUP_GENERIC] = $paramServers[$ni]['load']; // Check if the server was removed from any load groups foreach ( $this->groupLoads as $group => $weightByIndex ) { if ( isset( $weightByIndex[$i] ) && !isset( $newWeightByGroup[$group] ) ) { // Server no longer in this load group in the new config $anyServerDepooled = true; unset( $this->groupLoads[$group][$i] ); } } } else { // Server no longer exists in the new config $anyServerDepooled = true; // Note that if the primary server is depooled and a replica server promoted // to new primary, then DB_PRIMARY handles will fail with server index errors foreach ( $this->groupLoads as $group => $loads ) { unset( $this->groupLoads[$group][$i] ); } } } if ( $anyServerDepooled ) { // NOTE: We could close all connection here, but some may be in the middle of // a transaction. So instead, we leave it to DBConnRef to close the // connection when it detects that the modcount has changed and no // transaction is open. $this->logger->info( 'Reconfiguring dbs!' ); // Unpin DB_REPLICA connection groups from server indexes $this->readIndexByGroup = []; // We could close all connection here, but some may be in the middle of a // transaction. So instead, we leave it to DBConnRef to close the connection // when it detects that the modcount has changed and no transaction is open. $this->conns = self::newTrackedConnectionsArray(); // Bump modification counter to invalidate the connections held by DBConnRef // instances. This will cause the next call to a method on the DBConnRef // to get a new connection from getConnectionInternal() $this->modcount++; } } public function disable( $fname = __METHOD__ ) { $this->closeAll( $fname ); $this->disabled = true; } public function closeAll( $fname = __METHOD__ ) { /** @noinspection PhpUnusedLocalVariableInspection */ $scope = ScopedCallback::newScopedIgnoreUserAbort(); foreach ( $this->getOpenConnections() as $conn ) { $conn->close( $fname ); } $this->conns = self::newTrackedConnectionsArray(); } /** * Close a connection * * Using this function makes sure the LoadBalancer knows the connection is closed. * If you use $conn->close() directly, the load balancer won't update its state. * * @param IDatabaseForOwner $conn */ private function closeConnection( IDatabaseForOwner $conn ) { if ( $conn instanceof DBConnRef ) { // Avoid calling close() but still leaving the handle in the pool throw new RuntimeException( 'Cannot close DBConnRef instance; it must be shareable' ); } $domain = $conn->getDomainID(); $serverIndex = $conn->getLBInfo( self::INFO_SERVER_INDEX ); if ( $serverIndex === null ) { throw new UnexpectedValueException( "Handle on '$domain' missing server index" ); } $srvName = $this->serverInfo->getServerName( $serverIndex ); $found = false; foreach ( $this->conns as $type => $poolConnsByServer ) { $key = array_search( $conn, $poolConnsByServer[$serverIndex] ?? [], true ); if ( $key !== false ) { $found = true; unset( $this->conns[$type][$serverIndex][$key] ); } } if ( !$found ) { $this->logger->warning( __METHOD__ . ": orphaned connection to database {$this->stringifyConn( $conn )} at '$srvName'." ); } $this->logger->debug( __METHOD__ . ": closing connection to database {$this->stringifyConn( $conn )} at '$srvName'." ); $conn->close( __METHOD__ ); } public function finalizePrimaryChanges( $fname = __METHOD__ ) { $this->assertTransactionRoundStage( [ self::ROUND_CURSORY, self::ROUND_FINALIZED ] ); /** @noinspection PhpUnusedLocalVariableInspection */ $scope = ScopedCallback::newScopedIgnoreUserAbort(); $this->trxRoundStage = self::ROUND_ERROR; // "failed" until proven otherwise // Loop until callbacks stop adding callbacks on other connections $total = 0; do { $count = 0; // callbacks execution attempts foreach ( $this->getOpenPrimaryConnections() as $conn ) { // Run any pre-commit callbacks while leaving the post-commit ones suppressed. // Any error should cause all (peer) transactions to be rolled back together. $count += $conn->runOnTransactionPreCommitCallbacks(); } $total += $count; } while ( $count > 0 ); // Defer post-commit callbacks until after COMMIT/ROLLBACK happens on all handles foreach ( $this->getOpenPrimaryConnections() as $conn ) { $conn->setTrxEndCallbackSuppression( true ); } $this->trxRoundStage = self::ROUND_FINALIZED; return $total; } public function approvePrimaryChanges( int $maxWriteDuration, $fname = __METHOD__ ) { $this->assertTransactionRoundStage( self::ROUND_FINALIZED ); /** @noinspection PhpUnusedLocalVariableInspection */ $scope = ScopedCallback::newScopedIgnoreUserAbort(); $this->trxRoundStage = self::ROUND_ERROR; // "failed" until proven otherwise foreach ( $this->getOpenPrimaryConnections() as $conn ) { // Any atomic sections should have been closed by now and there definitely should // not be any open transactions started by begin() from callers outside Database. if ( $conn->explicitTrxActive() ) { throw new DBTransactionError( $conn, "Explicit transaction still active; a caller might have failed to call " . "endAtomic() or cancelAtomic()." ); } // Assert that the time to replicate the transaction will be reasonable. // If this fails, then all DB transactions will be rollback back together. $time = $conn->pendingWriteQueryDuration( $conn::ESTIMATE_DB_APPLY ); if ( $maxWriteDuration > 0 ) { if ( $time > $maxWriteDuration ) { $humanTimeSec = round( $time, 3 ); throw new DBTransactionSizeError( $conn, "Transaction spent {time}s in writes, exceeding the {$maxWriteDuration}s limit", // Message parameters for: transaction-duration-limit-exceeded [ $time, $maxWriteDuration ], null, [ 'time' => $humanTimeSec ] ); } elseif ( $time > 0 ) { $timeMs = $time * 1000; $humanTimeMs = round( $timeMs, $timeMs > 1 ? 0 : 3 ); $this->logger->debug( "Transaction spent {time_ms}ms in writes, under the {$maxWriteDuration}s limit", [ 'time_ms' => $humanTimeMs ] ); } } // If a connection sits idle for too long it might be dropped, causing transaction // writes and session locks to be lost. Ping all the server connections before making // any attempt to commit the transactions belonging to the active transaction round. if ( $conn->writesOrCallbacksPending() || $conn->sessionLocksPending() ) { if ( !$conn->ping() ) { throw new DBTransactionError( $conn, "Pre-commit ping failed on server {$conn->getServerName()}" ); } } } $this->trxRoundStage = self::ROUND_APPROVED; } public function beginPrimaryChanges( $fname = __METHOD__ ) { if ( $this->trxRoundId !== false ) { throw new DBTransactionError( null, "Transaction round '{$this->trxRoundId}' already started" ); } $this->assertTransactionRoundStage( self::ROUND_CURSORY ); /** @noinspection PhpUnusedLocalVariableInspection */ $scope = ScopedCallback::newScopedIgnoreUserAbort(); // Clear any empty transactions (no writes/callbacks) from the implicit round $this->flushPrimarySnapshots( $fname ); $this->trxRoundId = $fname; $this->trxRoundStage = self::ROUND_ERROR; // "failed" until proven otherwise // Mark applicable handles as participating in this explicit transaction round. // For each of these handles, any writes and callbacks will be tied to a single // transaction. The (peer) handles will reject begin()/commit() calls unless they // are part of an en masse commit or an en masse rollback. foreach ( $this->getOpenPrimaryConnections() as $conn ) { $this->applyTransactionRoundFlags( $conn ); } $this->trxRoundStage = self::ROUND_CURSORY; } public function commitPrimaryChanges( $fname = __METHOD__ ) { $this->assertTransactionRoundStage( self::ROUND_APPROVED ); /** @noinspection PhpUnusedLocalVariableInspection */ $scope = ScopedCallback::newScopedIgnoreUserAbort(); $failures = []; $restore = ( $this->trxRoundId !== false ); $this->trxRoundId = false; $this->trxRoundStage = self::ROUND_ERROR; // "failed" until proven otherwise // Commit any writes and clear any snapshots as well (callbacks require AUTOCOMMIT). // Note that callbacks should already be suppressed due to finalizePrimaryChanges(). foreach ( $this->getOpenPrimaryConnections() as $conn ) { try { $conn->commit( $fname, $conn::FLUSHING_ALL_PEERS ); } catch ( DBError $e ) { ( $this->errorLogger )( $e ); $failures[] = "{$conn->getServerName()}: {$e->getMessage()}"; } } if ( $failures ) { throw new DBTransactionError( null, "Commit failed on server(s) " . implode( "\n", array_unique( $failures ) ) ); } if ( $restore ) { // Unmark handles as participating in this explicit transaction round foreach ( $this->getOpenPrimaryConnections() as $conn ) { $this->undoTransactionRoundFlags( $conn ); } } $this->trxRoundStage = self::ROUND_COMMIT_CALLBACKS; } public function runPrimaryTransactionIdleCallbacks( $fname = __METHOD__ ) { if ( $this->trxRoundStage === self::ROUND_COMMIT_CALLBACKS ) { $type = IDatabase::TRIGGER_COMMIT; } elseif ( $this->trxRoundStage === self::ROUND_ROLLBACK_CALLBACKS ) { $type = IDatabase::TRIGGER_ROLLBACK; } else { throw new DBTransactionError( null, "Transaction should be in the callback stage (not '{$this->trxRoundStage}')" ); } /** @noinspection PhpUnusedLocalVariableInspection */ $scope = ScopedCallback::newScopedIgnoreUserAbort(); $oldStage = $this->trxRoundStage; $this->trxRoundStage = self::ROUND_ERROR; // "failed" until proven otherwise // Now that the COMMIT/ROLLBACK step is over, enable post-commit callback runs foreach ( $this->getOpenPrimaryConnections() as $conn ) { $conn->setTrxEndCallbackSuppression( false ); } $errors = []; $fname = __METHOD__; // Loop until callbacks stop adding callbacks on other connections do { // Run any pending callbacks for each connection... $count = 0; // callback execution attempts foreach ( $this->getOpenPrimaryConnections() as $conn ) { if ( $conn->trxLevel() ) { continue; // retry in the next iteration, after commit() is called } $count += $conn->runOnTransactionIdleCallbacks( $type, $errors ); } // Clear out any active transactions left over from callbacks... foreach ( $this->getOpenPrimaryConnections() as $conn ) { if ( $conn->writesPending() ) { // A callback from another handle wrote to this one and DBO_TRX is set $fnames = implode( ', ', $conn->pendingWriteCallers() ); $this->logger->info( "$fname: found writes pending ($fnames).", $this->getConnLogContext( $conn, [ 'exception' => new RuntimeException() ] ) ); } elseif ( $conn->trxLevel() ) { // A callback from another handle read from this one and DBO_TRX is set, // which can easily happen if there is only one DB (no replicas) $this->logger->debug( "$fname: found empty transaction." ); } try { $conn->commit( $fname, $conn::FLUSHING_ALL_PEERS ); } catch ( DBError $ex ) { $errors[] = $ex; } } } while ( $count > 0 ); $this->trxRoundStage = $oldStage; return $errors[0] ?? null; } public function runPrimaryTransactionListenerCallbacks( $fname = __METHOD__ ) { if ( $this->trxRoundStage === self::ROUND_COMMIT_CALLBACKS ) { $type = IDatabase::TRIGGER_COMMIT; } elseif ( $this->trxRoundStage === self::ROUND_ROLLBACK_CALLBACKS ) { $type = IDatabase::TRIGGER_ROLLBACK; } else { throw new DBTransactionError( null, "Transaction should be in the callback stage (not '{$this->trxRoundStage}')" ); } /** @noinspection PhpUnusedLocalVariableInspection */ $scope = ScopedCallback::newScopedIgnoreUserAbort(); $errors = []; $this->trxRoundStage = self::ROUND_ERROR; // "failed" until proven otherwise foreach ( $this->getOpenPrimaryConnections() as $conn ) { $conn->runTransactionListenerCallbacks( $type, $errors ); } $this->trxRoundStage = self::ROUND_CURSORY; return $errors[0] ?? null; } public function rollbackPrimaryChanges( $fname = __METHOD__ ) { /** @noinspection PhpUnusedLocalVariableInspection */ $scope = ScopedCallback::newScopedIgnoreUserAbort(); $restore = ( $this->trxRoundId !== false ); $this->trxRoundId = false; $this->trxRoundStage = self::ROUND_ERROR; // "failed" until proven otherwise foreach ( $this->getOpenPrimaryConnections() as $conn ) { $conn->rollback( $fname, $conn::FLUSHING_ALL_PEERS ); } if ( $restore ) { // Unmark handles as participating in this explicit transaction round foreach ( $this->getOpenPrimaryConnections() as $conn ) { $this->undoTransactionRoundFlags( $conn ); } } $this->trxRoundStage = self::ROUND_ROLLBACK_CALLBACKS; } public function flushPrimarySessions( $fname = __METHOD__ ) { $this->assertTransactionRoundStage( [ self::ROUND_CURSORY ] ); if ( $this->hasPrimaryChanges() ) { // Any transaction should have been rolled back beforehand throw new DBTransactionError( null, "Cannot reset session while writes are pending" ); } foreach ( $this->getOpenPrimaryConnections() as $conn ) { $conn->flushSession( $fname, $conn::FLUSHING_ALL_PEERS ); } } /** * @param string|string[] $stage * @throws DBTransactionError */ private function assertTransactionRoundStage( $stage ) { $stages = (array)$stage; if ( !in_array( $this->trxRoundStage, $stages, true ) ) { $stageList = implode( '/', array_map( static function ( $v ) { return "'$v'"; }, $stages ) ); throw new DBTransactionError( null, "Transaction round stage must be $stageList (not '{$this->trxRoundStage}')" ); } } /** * Make all DB servers with DBO_DEFAULT/DBO_TRX set join the transaction round * * Some servers may have neither flag enabled, meaning that they opt out of such * transaction rounds and remain in auto-commit mode. Such behavior might be desired * when a DB server is used for something like simple key/value storage. * * @param Database $conn */ private function applyTransactionRoundFlags( Database $conn ) { if ( $conn->getLBInfo( self::INFO_CONN_CATEGORY ) !== self::CATEGORY_ROUND ) { return; // transaction rounds do not apply to these connections } if ( $conn->getFlag( $conn::DBO_DEFAULT ) ) { // DBO_TRX is controlled entirely by CLI mode presence with DBO_DEFAULT. // Force DBO_TRX even in CLI mode since a commit round is expected soon. $conn->setFlag( $conn::DBO_TRX, $conn::REMEMBER_PRIOR ); } if ( $conn->getFlag( $conn::DBO_TRX ) ) { $conn->setLBInfo( $conn::LB_TRX_ROUND_ID, $this->trxRoundId ); } } /** * @param Database $conn */ private function undoTransactionRoundFlags( Database $conn ) { if ( $conn->getLBInfo( self::INFO_CONN_CATEGORY ) !== self::CATEGORY_ROUND ) { return; // transaction rounds do not apply to these connections } if ( $conn->getFlag( $conn::DBO_TRX ) ) { $conn->setLBInfo( $conn::LB_TRX_ROUND_ID, null ); // remove the round ID } if ( $conn->getFlag( $conn::DBO_DEFAULT ) ) { $conn->restoreFlags( $conn::RESTORE_PRIOR ); } } public function flushReplicaSnapshots( $fname = __METHOD__ ) { foreach ( $this->conns as $poolConnsByServer ) { foreach ( $poolConnsByServer as $serverIndex => $serverConns ) { if ( $serverIndex === ServerInfo::WRITER_INDEX ) { continue; // skip primary } foreach ( $serverConns as $conn ) { $conn->flushSnapshot( $fname ); } } } } public function flushPrimarySnapshots( $fname = __METHOD__ ) { foreach ( $this->getOpenPrimaryConnections() as $conn ) { $conn->flushSnapshot( $fname ); } } public function hasPrimaryConnection() { return (bool)$this->getAnyOpenConnection( ServerInfo::WRITER_INDEX ); } public function hasPrimaryChanges() { foreach ( $this->getOpenPrimaryConnections() as $conn ) { if ( $conn->writesOrCallbacksPending() ) { return true; } } return false; } public function lastPrimaryChangeTimestamp() { $lastTime = false; foreach ( $this->getOpenPrimaryConnections() as $conn ) { $lastTime = max( $lastTime, $conn->lastDoneWrites() ); } return $lastTime; } public function hasOrMadeRecentPrimaryChanges( $age = null ) { $age ??= self::MAX_WAIT_DEFAULT; return ( $this->hasPrimaryChanges() || $this->lastPrimaryChangeTimestamp() > microtime( true ) - $age ); } public function pendingPrimaryChangeCallers() { $fnames = []; foreach ( $this->getOpenPrimaryConnections() as $conn ) { $fnames = array_merge( $fnames, $conn->pendingWriteCallers() ); } return $fnames; } public function explicitTrxActive() { foreach ( $this->getOpenPrimaryConnections() as $conn ) { if ( $conn->explicitTrxActive() ) { return true; } } return false; } private function setLaggedReplicaMode(): void { $this->laggedReplicaMode = true; $this->logger->warning( __METHOD__ . ": setting lagged replica mode" ); } public function laggedReplicaUsed() { return $this->laggedReplicaMode; } public function getReadOnlyReason() { if ( $this->readOnlyReason !== false ) { return $this->readOnlyReason; } elseif ( $this->isPrimaryRunningReadOnly() ) { return 'The primary database server is running in read-only mode.'; } return false; } /** * @note This method suppresses DBError exceptions in order to avoid severe downtime * @param IDatabaseForOwner|null $conn Recently acquired primary connection; null if not applicable * @return bool Whether the entire primary DB server or the local domain DB is read-only */ private function isPrimaryRunningReadOnly( ?IDatabaseForOwner $conn = null ) { // Context will often be HTTP GET/HEAD; heavily cache the results return (bool)$this->wanCache->getWithSetCallback( // Note that table prefixes are not related to server-side read-only mode $this->wanCache->makeGlobalKey( 'rdbms-server-readonly', $this->serverInfo->getPrimaryServerName() ), self::TTL_CACHE_READONLY, function ( $oldValue ) use ( $conn ) { $scope = $this->trxProfiler->silenceForScope(); $conn ??= $this->getServerConnection( ServerInfo::WRITER_INDEX, self::DOMAIN_ANY, self::CONN_SILENCE_ERRORS ); if ( $conn ) { try { $value = (int)$conn->serverIsReadOnly(); } catch ( DBError $e ) { $value = is_int( $oldValue ) ? $oldValue : 0; } } else { $value = 0; } ScopedCallback::consume( $scope ); return $value; }, [ 'busyValue' => 0, 'pcTTL' => WANObjectCache::TTL_PROC_LONG ] ); } public function pingAll() { $success = true; foreach ( $this->getOpenConnections() as $conn ) { if ( !$conn->ping() ) { $success = false; } } return $success; } /** * Get all open connections * @return \Generator|Database[] */ private function getOpenConnections() { foreach ( $this->conns as $poolConnsByServer ) { foreach ( $poolConnsByServer as $serverConns ) { foreach ( $serverConns as $conn ) { yield $conn; } } } } /** * Get all open primary connections * @return \Generator|Database[] */ private function getOpenPrimaryConnections() { foreach ( $this->conns as $poolConnsByServer ) { /** @var IDatabaseForOwner $conn */ foreach ( ( $poolConnsByServer[ServerInfo::WRITER_INDEX] ?? [] ) as $conn ) { yield $conn; } } } public function getMaxLag() { $host = ''; $maxLag = -1; $maxIndex = 0; if ( $this->serverInfo->hasReplicaServers() ) { $lagTimes = $this->getLagTimes(); foreach ( $lagTimes as $i => $lag ) { // Allowing the value to be unset due to stale cache (T361824) $load = $this->groupLoads[self::GROUP_GENERIC][$i] ?? 0; if ( $load > 0 && $lag > $maxLag ) { $maxLag = $lag; $host = $this->serverInfo->getServerInfoStrict( $i, 'host' ); $maxIndex = $i; } } } return [ $host, $maxLag, $maxIndex ]; } public function getLagTimes() { if ( !$this->hasReplicaServers() ) { return [ ServerInfo::WRITER_INDEX => 0 ]; // no replication = no lag } $fname = __METHOD__; return $this->wanCache->getWithSetCallback( $this->wanCache->makeGlobalKey( 'rdbms-lags', $this->getClusterName() ), // Add jitter to avoid stampede 10 + mt_rand( 1, 10 ), function () use ( $fname ) { $lags = []; foreach ( $this->serverInfo->getStreamingReplicaIndexes() as $i ) { $conn = $this->getServerConnection( $i, self::DOMAIN_ANY, self::CONN_SILENCE_ERRORS | self::CONN_UNTRACKED_GAUGE ); if ( $conn ) { $lags[$i] = $conn->getLag(); $conn->close( $fname ); } else { $lags[$i] = false; } } return $lags; }, [ 'lockTSE' => 30 ] ); } public function waitForPrimaryPos( IDatabase $conn ) { if ( $conn->getLBInfo( self::INFO_SERVER_INDEX ) === ServerInfo::WRITER_INDEX ) { return true; // not a replica DB server } // Get the current primary DB position, opening a connection only if needed $flags = self::CONN_SILENCE_ERRORS; $primaryConn = $this->getAnyOpenConnection( ServerInfo::WRITER_INDEX, $flags ); if ( $primaryConn ) { $pos = $primaryConn->getPrimaryPos(); } else { $primaryConn = $this->getServerConnection( ServerInfo::WRITER_INDEX, self::DOMAIN_ANY, $flags ); if ( !$primaryConn ) { throw new DBReplicationWaitError( null, "Could not obtain a primary database connection to get the position" ); } $pos = $primaryConn->getPrimaryPos(); $this->closeConnection( $primaryConn ); } if ( $pos instanceof DBPrimaryPos && $conn instanceof IDatabaseForOwner ) { $this->logger->debug( __METHOD__ . ': waiting' ); $result = $conn->primaryPosWait( $pos, self::MAX_WAIT_DEFAULT ); $ok = ( $result !== null && $result != -1 ); if ( $ok ) { $this->logger->debug( __METHOD__ . ': done waiting (success)' ); } else { $this->logger->debug( __METHOD__ . ': done waiting (failure)' ); } } else { $ok = false; // something is misconfigured $this->logger->error( __METHOD__ . ': could not get primary pos for {db_server}', $this->getConnLogContext( $conn, [ 'exception' => new RuntimeException() ] ) ); } return $ok; } public function setTransactionListener( $name, ?callable $callback = null ) { if ( $callback ) { $this->trxRecurringCallbacks[$name] = $callback; } else { unset( $this->trxRecurringCallbacks[$name] ); } foreach ( $this->getOpenPrimaryConnections() as $conn ) { $conn->setTransactionListener( $name, $callback ); } } public function setTableAliases( array $aliases ) { $this->tableAliases = $aliases; } public function setIndexAliases( array $aliases ) { $this->indexAliases = $aliases; } public function setDomainAliases( array $aliases ) { $this->domainAliases = $aliases; } public function setLocalDomainPrefix( $prefix ) { $oldLocalDomain = $this->localDomain; $this->localDomain = new DatabaseDomain( $this->localDomain->getDatabase(), $this->localDomain->getSchema(), $prefix ); // Update the prefix for existing connections. // Existing DBConnRef handles will not be affected. foreach ( $this->getOpenConnections() as $conn ) { if ( $oldLocalDomain->equals( $conn->getDomainID() ) ) { $conn->tablePrefix( $prefix ); } } } public function redefineLocalDomain( $domain ) { $this->closeAll( __METHOD__ ); $this->localDomain = DatabaseDomain::newFromId( $domain ); } public function setTempTablesOnlyMode( $value, $domain ) { $old = $this->tempTablesOnlyMode[$domain] ?? false; if ( $value ) { $this->tempTablesOnlyMode[$domain] = true; } else { unset( $this->tempTablesOnlyMode[$domain] ); } return $old; } /** * @param IDatabase $conn * @return string Description of a connection handle for log messages * @throws InvalidArgumentException */ private function stringifyConn( IDatabase $conn ) { return $conn->getLBInfo( self::INFO_SERVER_INDEX ) . '/' . $conn->getDomainID(); } /** * @param int $flags A bitfield of flags * @param int $bit Bit flag constant * @return bool Whether the bit field has the specified bit flag set */ private function fieldHasBit( int $flags, int $bit ) { return ( ( $flags & $bit ) === $bit ); } /** * Create a log context to pass to PSR-3 logger functions. * * @param IDatabase $conn * @param array $extras Additional data to add to context * @return array */ protected function getConnLogContext( IDatabase $conn, array $extras = [] ) { return array_merge( [ 'db_server' => $conn->getServerName(), 'db_domain' => $conn->getDomainID() ], $extras ); } /** * @param float|null &$time Mock UNIX timestamp for testing * @internal * @codeCoverageIgnore */ public function setMockTime( &$time ) { $this->loadMonitor->setMockTime( $time ); } } PK ! �� �Q' Q' , rdbms/loadbalancer/ILoadBalancerForOwner.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\Rdbms; use Exception; /** * Internal interface for load balancer instances exposed to their owner * * Instances are either owned by an LBFactory object or owned by the caller that created * the instance using a constructor/factory function such as LBFactory::newMain(). * * @internal Only for use within LBFactory/LoadMonitor/ChronologyProtector * @since 1.39 * @ingroup Database */ interface ILoadBalancerForOwner extends ILoadBalancer { /** Manager of ILoadBalancer instances is running post-commit callbacks */ public const STAGE_POSTCOMMIT_CALLBACKS = 'stage-postcommit-callbacks'; /** Manager of ILoadBalancer instances is running post-rollback callbacks */ public const STAGE_POSTROLLBACK_CALLBACKS = 'stage-postrollback-callbacks'; /** * @param array $params Parameter map with keys: * - servers : List of server configuration maps, starting with either the global master * or local datacenter multi-master, and optionally followed by local datacenter replicas. * Each server configuration map has the same format as the Database::factory() $params * argument, with the following additional optional fields: * - type: the DB type (sqlite, mysql, postgres,...) * - groupLoads: map of (group => weight for this server) [optional] * - max lag: per-server override of the "max lag" [optional] * - is static: whether the dataset is static *and* this server has a copy [optional] * - localDomain: A DatabaseDomain or domain ID string * - loadMonitor : LoadMonitor::__construct() parameters with "class" field [optional] * - readOnlyReason : Reason the primary server is read-only (false if not) [optional] * - srvCache : BagOStuff object for server cache [optional] * - wanCache : WANObjectCache object [optional] * - databaseFactory: DatabaseFactory object [optional] * - chronologyProtector: ChronologyProtector object [optional] * - defaultGroup: Default query group; the generic group if not specified [optional] * - hostname : The name of the current server [optional] * - cliMode: Whether the execution context is a CLI script [optional] * - profiler : Callback that takes a section name argument and returns * a ScopedCallback instance that ends the profile section in its destructor [optional] * - trxProfiler: TransactionProfiler instance [optional] * - logger: PSR-3 logger instance [optional] * - errorLogger : Callback that takes an Exception and logs it [optional] * - deprecationLogger: Callback to log a deprecation warning [optional] * - roundStage: STAGE_POSTCOMMIT_* class constant; for internal use [optional] * - clusterName: The name of the overall (single/multi-datacenter) cluster of servers * managing the dataset, regardless of 'servers' excluding replicas and * multi-masters from remote datacenter [optional] * - criticalSectionProvider: CriticalSectionProvider instance [optional] */ public function __construct( array $params ); /** * Close all connections and disable this load balancer * * Any attempt to open a new connection will result in a DBAccessError. * * @param string $fname Caller name @phan-mandatory-param */ public function disable( $fname = __METHOD__ ); /** * Close all open connections * * @param string $fname Caller name @phan-mandatory-param * */ public function closeAll( $fname = __METHOD__ ); /** * Run pre-commit callbacks and defer execution of post-commit callbacks * * Use this only for multi-database commits * * @param string $fname Caller name @phan-mandatory-param * @return int Number of pre-commit callbacks run (since 1.32) * @since 1.37 */ public function finalizePrimaryChanges( $fname = __METHOD__ ); /** * Perform all pre-commit checks for things like replication safety * * Use this only for multi-database commits * * @param int $maxWriteDuration : max write query duration time in seconds * @param string $fname Caller name @phan-mandatory-param * @throws DBTransactionError * @since 1.37 */ public function approvePrimaryChanges( int $maxWriteDuration, $fname = __METHOD__ ); /** * Flush any primary transaction snapshots and set DBO_TRX (if DBO_DEFAULT is set) * * The DBO_TRX setting will be reverted to the default in each of these methods: * - commitPrimaryChanges() * - rollbackPrimaryChanges() * This allows for custom transaction rounds from any outer transaction scope. * * @param string $fname Caller name @phan-mandatory-param * @throws DBExpectedError * @since 1.37 */ public function beginPrimaryChanges( $fname = __METHOD__ ); /** * Issue COMMIT on all open primary connections to flush changes and view snapshots * @param string $fname Caller name @phan-mandatory-param * @throws DBExpectedError * @since 1.37 */ public function commitPrimaryChanges( $fname = __METHOD__ ); /** * Consume and run all pending post-COMMIT/ROLLBACK callbacks and commit dangling transactions * * @param string $fname Caller name @phan-mandatory-param * @return Exception|null The first exception or null if there were none * @since 1.37 */ public function runPrimaryTransactionIdleCallbacks( $fname = __METHOD__ ); /** * Run all recurring post-COMMIT/ROLLBACK listener callbacks * * @param string $fname Caller name @phan-mandatory-param * @return Exception|null The first exception or null if there were none * @since 1.37 */ public function runPrimaryTransactionListenerCallbacks( $fname = __METHOD__ ); /** * Issue ROLLBACK only on primary, only if queries were done on connection * * @param string $fname Caller name @phan-mandatory-param * @throws DBExpectedError * @since 1.37 */ public function rollbackPrimaryChanges( $fname = __METHOD__ ); /** * Release/destroy session-level named locks, table locks, and temp tables * * Only call this function right after calling rollbackPrimaryChanges() * * @param string $fname Caller name @phan-mandatory-param * @throws DBExpectedError * @since 1.38 */ public function flushPrimarySessions( $fname = __METHOD__ ); /** * Commit all replica DB transactions so as to flush any REPEATABLE-READ or SSI snapshots * * @param string $fname Caller name @phan-mandatory-param */ public function flushReplicaSnapshots( $fname = __METHOD__ ); /** * Commit all primary DB transactions so as to flush any REPEATABLE-READ or SSI snapshots * * An error will be thrown if a connection has pending writes or callbacks * * @param string $fname Caller name @phan-mandatory-param * @since 1.37 */ public function flushPrimarySnapshots( $fname = __METHOD__ ); /** * Get the list of callers that have pending primary changes * * @return string[] List of method names * @since 1.37 */ public function pendingPrimaryChangeCallers(); /** * Set a new table prefix for the existing local domain ID for testing * * @param string $prefix * @since 1.33 */ public function setLocalDomainPrefix( $prefix ); /** * Reconfigure using the given config array. * If the config changed, this invalidates all existing connections. * * @warning This must only be called in top level code, typically via * LBFactory::reconfigure. * * @since 1.39 * * @param array $conf A configuration array, using the same structure as * the one passed to the LoadBalancer's constructor. */ public function reconfigure( array $conf ); /** * Close all connection and redefine the local domain for testing or schema creation * * @param DatabaseDomain|string $domain * @since 1.33 */ public function redefineLocalDomain( $domain ); /** * @return bool Whether a primary connection is already open * @since 1.37 */ public function hasPrimaryConnection(); /** * Convert certain index names to alternative names before querying the DB * * Note that this applies to indexes regardless of the table they belong to. * * This can be employed when an index was renamed X => Y in code, but the new Y-named * indexes were not yet built on all DBs. After all the Y-named ones are added by the DBA, * the aliases can be removed, and then the old X-named indexes dropped. * * @param string[] $aliases * @since 1.31 */ public function setIndexAliases( array $aliases ); /** * Get the timestamp of the latest write query done by this thread * @return float|false UNIX timestamp or false * @since 1.37 */ public function lastPrimaryChangeTimestamp(); /** * Set the primary wait position and wait for ALL replica DBs to catch up to it * * This method is only intended for use a throttling mechanism for high-volume updates. * Unlike waitFor(), failure does not effect laggedReplicaUsed(). * * @param DBPrimaryPos $pos Primary position * @param int|null $timeout Max seconds to wait; default is mWaitTimeout * @return bool Success (able to connect and no timeouts reached) */ public function waitForAll( DBPrimaryPos $pos, $timeout = null ); /** * Whether a highly "lagged" replica database connection was queried. * * @note This method will never cause a new DB connection * @return bool */ public function laggedReplicaUsed(); } PK ! NH#wX wX $ rdbms/loadbalancer/ILoadBalancer.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\Rdbms; /** * This class is a delegate to ILBFactory for a given database cluster * * ILoadBalancer tracks the database connections and transactions for a given database cluster. * A "cluster" is considered to be the set of database servers that manage a given dataset. * Within a given cluster, each database server can have one of the following roles: * - sole-primary: the server used by this datacenter for writes from the application * - co-primary: one of several servers used by this datacenter for writes from the application, * relying on asynchronous replication to synchronize their copies of the dataset * - replica: a server used only for reads from the application, relying on asynchronous * replication to apply writes from the primary server or co-primary servers * - static clone: a server that only accepts reads from the application, does not replicate, * and has a copy of the final dataset, which must be static (all the servers reject writes) * * Single-datacenter database clusters consist of either: * - A sole-primary server and zero or more replica servers * - A set of static clone servers * * Multi-datacenter database clusters either consist of either: * - A sole-primary server and zero or more replica servers in the "primary datacenter" * (the one datacenter meant to handle requests/jobs that mutate the database), and zero or * more replica servers in each "secondary datacenter" (all the other datacenters) * - A co-primary server and zero or more replica servers within each datacenter * - A set of static clone servers in each datacenter * * The term "primary" refers to the server used by this datacenter for handling writes, * whether it is a sole-primary or co-primary. * * The "servers" configuration array contains the list of database servers to use for operations * originating from the the local datacenter. The first entry must refer to the server to use for * write and read-for-write operations (e.g. the "writer server"): * - If there is a primary server, then the first entry must refer to it, even if the primary * server resides in a remote datacenter * - If there are co-primary servers, then the first entry must refer to the one in the local * datacenter * - If the servers are static clones, then the first entry can refer to any of them, since the * concept of a "writer server" is merely nominal * * On an infrastructure level, circular replication setups can have more than one database server * act as a replication "source" within the same datacenter, provided that no more than one of the * servers are writable at any time, namely the "writer server". The other source servers will be * treated as replicas by the load balancer, but can be quickly promoted to the "writer server" by * the site admin as needed. * * Likewise, Galera Cluster setups still require the choice of a single "writer server" for each * datacenter. Limiting the number of servers that initiate transactions helps reduce the rate of * aborted transactions due to wsrep conflicts. * * By default, each DB server uses DBO_DEFAULT for its 'flags' setting, unless explicitly set * otherwise in configuration. DBO_DEFAULT behavior depends on whether 'cliMode' is set: * - In CLI mode, the flag has no effect with regards to LoadBalancer. * - In non-CLI mode, the flag causes implicit transactions to be used; the first query on * a database starts a transaction on that database. The transactions are meant to remain * pending until either commitPrimaryChanges() or rollbackPrimaryChanges() is called. The * application must have some point where it calls commitPrimaryChanges() near the end of * the PHP request. * Every iteration of beginPrimaryChanges()/commitPrimaryChanges() is called a "transaction round". * Rounds are useful on the primary DB connections because they make single-DB (and by and large * multi-DB) updates in web requests all-or-nothing. Also, transactions on replica DBs are useful * when REPEATABLE-READ or SERIALIZABLE isolation is used because all foreign keys and constraints * hold across separate queries in the DB transaction since the data appears within a consistent * point-in-time snapshot. * * The typical caller will use LoadBalancer::getConnection( DB_* ) to yield a database * connection handle. The choice of which DB server to use is based on pre-defined loads for * weighted random selection, adjustments thereof by LoadMonitor, and the amount of replication * lag on each DB server. Lag checks might cause problems in certain setups, so they should be * tuned in the server configuration maps as follows: * - Sole-primary + N Replica(s): set 'max lag' to an appropriate threshold for avoiding any * replica database lagged by this much or more. If all replicas are this lagged, then the * load balancer considers the cluster to be read-only. * - Per-datacenter co-primary + N Replica(s): set 'max lag' to an appropriate threshold for * avoiding any replica database lagged by this much or more. If all replicas are this * lagged, then the load balancer considers the cluster to be read-only. * - Read-only archive clones: set 'is static' in the server configuration maps. This will * treat all such DBs as having 0 lag. * - Externally updated dataset clones: set 'is static' in the server configuration maps. * This will treat all such DBs as having 0 lag. * - SQL load balancing proxy: any proxy should handle lag checks on its own, so the 'max lag' * parameter should probably be set to INF in the server configuration maps. This will make * the load balancer ignore whatever it detects as the lag of the logical replica is (which * would probably just randomly bounce around). * * If using a SQL proxy service, it would probably be best to have two proxy hosts for the load * balancer to talk to. One would be the 'host' of the "writer server" entry and another for the * (logical) replica server entry. The proxy could map the load balancer's "replica" DB to any * number of physical replica DBs. * * @since 1.28 * @ingroup Database */ interface ILoadBalancer { /** * Request a replica DB connection. Can't be used as a binary flag with bitwise operators! */ public const DB_REPLICA = -1; /** * Request a primary, write-enabled DB connection. Can't be used as a binary flag with bitwise * operators! * @since 1.36 */ public const DB_PRIMARY = -2; /** Domain specifier when no specific database needs to be selected */ public const DOMAIN_ANY = ''; /** The generic query group */ public const GROUP_GENERIC = ''; /** Yield a tracked autocommit-mode handle (reuse existing ones) */ public const CONN_TRX_AUTOCOMMIT = 1; /** * Yield an untracked, low-timeout, autocommit-mode handle (to gauge server health) * @internal */ public const CONN_UNTRACKED_GAUGE = 2; /** * Yield null on connection failure instead of throwing an exception * @internal */ public const CONN_SILENCE_ERRORS = 4; /** * Get the name of the overall cluster of database servers managing the dataset * * Note that the cluster might contain servers in multiple datacenters. * The load balancer instance only needs to be aware of the local replica servers, * along with either the sole-primary server or the local co-primary server. * * This is useful for identifying a cluster or replicated dataset, even when: * - The primary server is sometimes swapped with another one * - The cluster/dataset is replicated among multiple datacenters, with one "primary" * datacenter having the writable primary server and the other datacenters having a * read-only replica in the "primary" server slot * - The dataset is replicated among multiple datacenters, via circular replication, * with each datacenter having its own "co-primary" server * * @return string * @since 1.36 */ public function getClusterName(): string; /** * Get the local (and default) database domain ID of connection handles * * @see DatabaseDomain * @return string Database domain ID; this specifies DB name, schema, and table prefix * @since 1.31 */ public function getLocalDomainID(): string; /** * @param DatabaseDomain|string|false $domain Database domain * @return string Value of $domain if it is foreign or the local domain otherwise * @since 1.32 */ public function resolveDomainID( $domain ): string; /** * Indicate whether the tables on this domain are only temporary tables for testing * * In "temporary tables mode", the CONN_TRX_AUTOCOMMIT flag is ignored * * @param bool $value * @param string $domain * @return bool Whether "temporary tables mode" was active * @since 1.34 */ public function setTempTablesOnlyMode( $value, $domain ); /** * Get the specific server index of the reader connection for a given group * * This takes into account load ratios and lag times. It should return a consistent * index during the life time of the load balancer. This initially checks replica DBs * for connectivity to avoid returning an unusable server. This means that connections * might be attempted by calling this method (usually one at the most but possibly more). * Subsequent calls with the same $group will not need to make new connection attempts * since the acquired connection for each group is preserved. * * @param string|false $group Query group or false for the generic group * @return int|false Specific server index, or false if no DB handle can be obtained */ public function getReaderIndex( $group = false ); /** * Get a lazy-connecting database handle for a specific or virtual (DB_PRIMARY/DB_REPLICA) server index * * The server index, $i, can be one of the following: * - DB_REPLICA: a server index will be selected by the load balancer based on read * weight, connectivity, and replication lag. Note that the primary server might be * configured with read weight. If $groups is empty then it means "the generic group", * in which case all servers defined with read weight will be considered. Additional * query groups can be configured, having their own list of server indexes and read * weights. If a query group list is provided in $groups, then each recognized group * will be tried, left-to-right, until server index selection succeeds or all groups * have been tried, in which case the generic group will be tried. * - DB_PRIMARY: the primary server index will be used; the same as ServerInfo::WRITER_INDEX. * The value of $groups should be [] when using this server index. * - Specific server index: a positive integer can be provided to use the server with * that index. An error will be thrown in no such server index is recognized. This * server selection method is usually only useful for internal load balancing logic. * The value of $groups should be [] when using a specific server index. * * Handle sharing is very useful when callers get DB_PRIMARY handles that are transaction * round aware (the default). All such callers will operate within a single transaction as * a consequence. The same applies to DB_REPLICA that are samely query grouped (the default) * and transaction round aware (the default). * * Use CONN_TRX_AUTOCOMMIT to use a separate pool of only autocommit handles. This flag is * ignored for databases with ATTR_DB_LEVEL_LOCKING (e.g. sqlite) in order to avoid deadlocks. * getServerAttributes() can be used to check this attribute beforehand. Avoid using begin() * and commit() on such handles. If handle methods like startAtomic() and endAtomic() must be * used on the handles, callers should at least make sure that the atomic sections are closed * on failure via try/catch and cancelAtomic(). * * Use CONN_UNTRACKED_GAUGE to get a new, untracked, handle, that uses a low connection timeout, a low * read timeout, and autocommit mode. This flag is intended for use only be internal callers. * * CONN_UNTRACKED_GAUGE and CONN_TRX_AUTOCOMMIT are incompatible. * * @see ILoadBalancer::getServerAttributes() * * @param int $i Specific (overrides $groups) or virtual (DB_PRIMARY/DB_REPLICA) server index * @param string[]|string $groups Query group(s) in preference order; [] for the default group * @param string|false $domain DB domain ID or false for the local domain * @param int $flags Bitfield of CONN_* class constants * @return IDatabase|false This returns false on failure if CONN_SILENCE_ERRORS is set */ public function getConnection( $i, $groups = [], $domain = false, $flags = 0 ); /** * Get a DB handle for a specific server index * * This is an internal utility method for methods like LoadBalancer::getConnectionInternal() * and DBConnRef to create the underlying connection to a concrete server. * * The following is the responsibility of the caller: * * - translate any virtual server indexes (DB_PRIMARY/DB_REPLICA) to a real server index. * - enforce read-only mode on primary DB handle if there is high replication lag. * * @see ILoadBalancer::getConnection() * * @internal Only for use within ILoadBalancer/ILoadMonitor * @param int $i Specific server index * @param string $domain Resolved DB domain * @param int $flags Bitfield of class CONN_* constants * @return IDatabaseForOwner|false This returns false on failure if CONN_SILENCE_ERRORS is set * @throws DBError If no DB handle could be obtained and CONN_SILENCE_ERRORS is not set */ public function getServerConnection( $i, $domain, $flags = 0 ); /** * @deprecated since 1.39, use ILoadBalancer::getConnection() instead. * @param int $i Specific or virtual (DB_PRIMARY/DB_REPLICA) server index * @param string[]|string $groups Query group(s) in preference order; [] for the default group * @param string|false $domain DB domain ID or false for the local domain * @param int $flags Bitfield of CONN_* class constants (e.g. CONN_TRX_AUTOCOMMIT) * @return DBConnRef */ public function getConnectionRef( $i, $groups = [], $domain = false, $flags = 0 ): DBConnRef; /** * @internal Only to be used by DBConnRef * @param int $i Specific (overrides $groups) or virtual (DB_PRIMARY/DB_REPLICA) server index * @param string[]|string $groups Query group(s) in preference order; [] for the default group * @param string|false $domain DB domain ID or false for the local domain * @param int $flags Bitfield of CONN_* class constants (e.g. CONN_TRX_AUTOCOMMIT) * @return IDatabase */ public function getConnectionInternal( $i, $groups = [], $domain = false, $flags = 0 ): IDatabase; /** * Get a DB handle, suitable for migrations and schema changes, for a server index * * The DBConnRef methods simply proxy an underlying IDatabase object which * takes care of the actual connection and query logic. * * The CONN_TRX_AUTOCOMMIT flag is ignored for databases with ATTR_DB_LEVEL_LOCKING * (e.g. sqlite) in order to avoid deadlocks. getServerAttributes() * can be used to check such flags beforehand. Avoid the use of begin() or startAtomic() * on any CONN_TRX_AUTOCOMMIT connections. * * @see ILoadBalancer::getConnection() for parameter information * @param int $i Specific or virtual (DB_PRIMARY/DB_REPLICA) server index * @param string[]|string $groups Query group(s) in preference order; [] for the default group * @param string|false $domain DB domain ID or false for the local domain * @param int $flags Bitfield of CONN_* class constants (e.g. CONN_TRX_AUTOCOMMIT) * @return DBConnRef */ public function getMaintenanceConnectionRef( $i, $groups = [], $domain = false, $flags = 0 ): DBConnRef; /** * Get the number of servers defined in configuration * * @return int */ public function getServerCount(); /** * Whether there are any replica servers configured * * This scans the list of servers defined in configuration, checking for: * - Servers that are listed after the primary and not flagged with "is static"; * such servers are assumed to be typical streaming replicas * - Servers that are listed after the primary and flagged with "is static"; * such servers are assumed to have a clone of the static dataset (matching the primary) * * @return bool * @since 1.34 */ public function hasReplicaServers(); /** * Whether any replica servers use streaming replication from the primary server * * This scans the list of servers defined in configuration, checking for: * - Servers that are listed after the primary and not flagged with "is static"; * such servers are assumed to be typical streaming replicas * * It is possible for some replicas to be configured with "is static" but not * others, though it generally should either be set for all or none of the replicas. * * If this returns false, this means that there is generally no reason to execute * replication wait logic for session consistency and lag reduction. * * @return bool * @since 1.34 */ public function hasStreamingReplicaServers(); /** * Get the readable name of the server with the specified index * * @param int $i Specific server index * @return string Readable server name, falling back to the hostname or IP address */ public function getServerName( $i ): string; /** * Return the server configuration map for the server with the specified index * * @param int $i Specific server index * @return array|false Server configuration map; false if the index is invalid * @since 1.31 */ public function getServerInfo( $i ); /** * Get the RDBMS type of the server with the specified index (e.g. "mysql", "sqlite") * * @param int $i Specific server index * @return string One of (mysql,postgres,sqlite,...) or "unknown" for bad indexes * @since 1.30 */ public function getServerType( $i ); /** * Get basic attributes of the server with the specified index without connecting * * @param int $i Specific server index * @return array (Database::ATTRIBUTE_* constant => value) for all such constants * @since 1.31 */ public function getServerAttributes( $i ); /** * Get the current primary replication position * * @return DBPrimaryPos|false Returns false if not applicable * @throws DBError * @since 1.37 */ public function getPrimaryPos(); /** * Whether there are pending changes or callbacks in a transaction by this thread * @return bool * @since 1.37 */ public function hasPrimaryChanges(); /** * Determine whether an explicit transaction is active on any open primary * connection. * @return bool * @since 1.39 */ public function explicitTrxActive(); /** * Check if this load balancer object had any recent or still * pending writes issued against it by this PHP thread * * @param float|null $age How many seconds ago is "recent" [defaults to mWaitTimeout] * @return bool * @since 1.37 */ public function hasOrMadeRecentPrimaryChanges( $age = null ); /** * @note This method may trigger a DB connection if not yet done * @return string|false Reason the primary is read-only or false if it is not */ public function getReadOnlyReason(); /** * @return bool */ public function pingAll(); /** * Get the name and lag time of the most-lagged replica server * * This is useful for maintenance scripts that need to throttle their updates. * May attempt to open connections to replica DBs on the default DB. If there is * no lag, the maximum lag will be reported as -1. * * @return array{0:string,1:float|int|false,2:int} (host, max lag, index of max lagged host) */ public function getMaxLag(); /** * Get an estimate of replication lag (in seconds) for each server * * Results are cached for a short time in memcached/process cache * * Values may be "false" if replication is too broken to estimate * * @return float[]|int[]|false[] Map of (server index => lag) in order of server index */ public function getLagTimes(); /** * Wait for a replica DB to reach a specified primary position * * If $conn is not a replica server connection, then this will return true. * Otherwise, if $pos is not provided, this will connect to the primary server * to get an accurate position. * * @param IDatabase $conn Replica DB * @return bool Success * @since 1.37 */ public function waitForPrimaryPos( IDatabase $conn ); /** * Set a callback via IDatabase::setTransactionListener() on * all current and future primary connections of this load balancer * * @param string $name Callback name * @param callable|null $callback */ public function setTransactionListener( $name, ?callable $callback = null ); /** * Make certain table names use their own database, schema, and table prefix * when passed into SQL queries pre-escaped and without a qualified database name * * For example, "user" can be converted to "myschema.mydbname.user" for convenience. * Appearances like `user`, somedb.user, somedb.someschema.user will used literally. * * Calling this twice will completely clear any old table aliases. Also, note that * callers are responsible for making sure the schemas and databases actually exist. * * @param array[] $aliases Map of (table => (dbname, schema, prefix) map) */ public function setTableAliases( array $aliases ); /** * Convert certain database domains to alternative ones. * * This can be used for backwards compatibility logic. * * @param DatabaseDomain[]|string[] $aliases Map of (domain alias => domain) * @since 1.35 */ public function setDomainAliases( array $aliases ); } PK ! �y��_ _ ) rdbms/loadbalancer/LoadBalancerSingle.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\Rdbms; use InvalidArgumentException; /** * Trivial LoadBalancer that always returns an injected connection handle. * * @ingroup Database */ class LoadBalancerSingle extends LoadBalancer { /** @var Database */ private $conn; /** * You probably want to use {@link newFromConnection} instead. * * @param array $params An associative array with one member: * - connection: An IDatabase connection object */ public function __construct( array $params ) { /** @var Database $conn */ $conn = $params['connection'] ?? null; if ( !$conn ) { throw new InvalidArgumentException( "Missing 'connection' argument." ); } $this->conn = $conn; parent::__construct( [ 'servers' => [ [ 'type' => $conn->getType(), 'host' => $conn->getServer(), 'dbname' => $conn->getDBname(), 'load' => 1, ] ], 'trxProfiler' => $params['trxProfiler'] ?? null, 'srvCache' => $params['srvCache'] ?? null, 'wanCache' => $params['wanCache'] ?? null, 'localDomain' => $params['localDomain'] ?? $this->conn->getDomainID(), 'readOnlyReason' => $params['readOnlyReason'] ?? false, 'clusterName' => $params['clusterName'] ?? null, ] ); if ( isset( $params['readOnlyReason'] ) ) { $conn->setLBInfo( $conn::LB_READ_ONLY_REASON, $params['readOnlyReason'] ); } } /** * @param IDatabase $db Live connection handle * @param array $params Parameter map to LoadBalancerSingle::__constructs() * @return LoadBalancerSingle * @since 1.28 */ public static function newFromConnection( IDatabase $db, array $params = [] ) { return new static( array_merge( [ 'localDomain' => $db->getDomainID() ], $params, [ 'connection' => $db ] ) ); } protected function sanitizeConnectionFlags( $flags, $domain ) { // There is only one underlying connection handle. Also, this class is only meant to // be used during situations like site installation, where there should be no contenting // connections, and integration testing, where everything uses temporary tables. $flags &= ~self::CONN_TRX_AUTOCOMMIT; return $flags; } protected function reallyOpenConnection( $i, DatabaseDomain $domain, array $lbInfo ) { foreach ( $lbInfo as $k => $v ) { $this->conn->setLBInfo( $k, $v ); } return $this->conn; } public function __destruct() { // do nothing since the connection was injected } } PK ! pֱ]l l rdbms/IDBAccessObject.phpnu �Iw�� <?php /** * This file contains database access object related constants. * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file * @ingroup Database */ namespace Wikimedia\Rdbms; /** * Interface for database access objects. * * Classes using this support a set of constants in a bitfield argument to their data loading * functions. In general, objects should assume READ_NORMAL if no flags are explicitly given, * though certain objects may assume READ_LATEST for common use case or legacy reasons. * * There are four types of reads: * - READ_NORMAL : Potentially cached read of data (e.g. from a replica DB or stale replica) * - READ_LATEST : Up-to-date read as of transaction start (e.g. from primary or a quorum read) * - READ_LOCKING : Up-to-date read as of now, that locks (shared) the records * - READ_EXCLUSIVE : Up-to-date read as of now, that locks (exclusive) the records * All record locks persist for the duration of the transaction. * * A special constant READ_LATEST_IMMUTABLE can be used for fetching append-only data. Such * data is either (a) on a replica DB and up-to-date or (b) not yet there, but on the primary/quorum. * Because the data is append-only, it can never be stale on a replica DB if present. * * Callers should use READ_NORMAL (or pass in no flags) unless the read determines a write. * In theory, such cases may require READ_LOCKING, though to avoid contention, READ_LATEST is * often good enough. If UPDATE race condition checks are required on a row and expensive code * must run after the row is fetched to determine the UPDATE, it may help to do something like: * - a) Start transaction * - b) Read the current row with READ_LATEST * - c) Determine the new row (expensive, so we don't want to hold locks now) * - d) Re-read the current row with READ_LOCKING; if it changed then bail out * - e) otherwise, do the updates * - f) Commit transaction * * @stable to implement * * @since 1.20 */ interface IDBAccessObject { /** Constants for object loading bitfield flags (higher => higher QoS) */ /** Read from a replica DB/non-quorum */ public const READ_NORMAL = 0; /** Read from the primary/quorum */ public const READ_LATEST = 1; /** Read from the primary/quorum and lock out other writers */ public const READ_LOCKING = self::READ_LATEST | 2; // READ_LATEST (1) and "LOCK IN SHARE MODE" (2) /** Read from the primary/quorum and lock out other writers and locking readers */ public const READ_EXCLUSIVE = self::READ_LOCKING | 4; // READ_LOCKING (3) and "FOR UPDATE" (4) /** Read from a replica DB or without a quorum, using the primary/quorum on miss */ public const READ_LATEST_IMMUTABLE = 8; /** Convenience constant for tracking how data was loaded (higher => higher QoS) */ public const READ_NONE = -1; // not loaded yet (or the object was cleared) } /** @deprecated class alias since 1.43 */ class_alias( IDBAccessObject::class, 'IDBAccessObject' ); PK ! m$� � rdbms/encasing/IBlob.phpnu �Iw�� <?php namespace Wikimedia\Rdbms; /** * Wrapper allowing us to distinguish a blob from a normal string and an array of strings * @ingroup Database */ interface IBlob { /** * @return string */ public function fetch(); } PK ! O�Bw@ @ rdbms/encasing/Blob.phpnu �Iw�� <?php namespace Wikimedia\Rdbms; /** * @newable * @stable to extend */ class Blob implements IBlob { /** @var string */ protected $data; /** * @stable to call * @param string $data */ public function __construct( $data ) { $this->data = $data; } public function fetch() { return $this->data; } } PK ! 0��?\ \ rdbms/encasing/PostgresBlob.phpnu �Iw�� <?php namespace Wikimedia\Rdbms; /** * @newable */ class PostgresBlob extends Blob { } PK ! M�� � rdbms/encasing/Subquery.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\Rdbms; use Stringable; /** * @ingroup Database */ class Subquery implements Stringable { /** @var string */ private $sql; /** * @param string $sql SQL query defining the table */ public function __construct( $sql ) { $this->sql = $sql; } /** * @return string Original SQL query */ public function __toString() { return '(' . $this->sql . ')'; } } PK ! ��6K K rdbms/encasing/LikeMatch.phpnu �Iw�� <?php namespace Wikimedia\Rdbms; /** * Used by Database::buildLike() to represent characters that have special * meaning in SQL LIKE clauses and thus need no escaping. Don't instantiate it * manually, use Database::anyChar() and anyString() instead. */ class LikeMatch { /** @var string */ private $str; /** * Store a string into a LikeMatch marker object. * * @param string $s */ public function __construct( $s ) { $this->str = $s; } /** * Return the original stored string. * * @return string */ public function toString() { return $this->str; } } PK ! ��G� � rdbms/encasing/RawSQLValue.phpnu �Iw�� <?php namespace Wikimedia\Rdbms; /** * Raw SQL value to be used in query builders * * @note This should be used very rarely and NEVER with user input. * * @newable * @since 1.43 */ class RawSQLValue { private string $value = ''; /** * This should be used very rarely and NEVER with user input. * * Most common usecases is the value in a SET clause of UPDATE, * e.g. for updates like `total_pages = total_pages + 1`: * * $queryBuilder->set( [ 'total_pages' => new RawSQLValue( 'total_pages + 1' ) ] ) * * …or as one side of a comparison in a WHERE condition, * e.g. for conditions like `range_start = range_end`, `range_start != range_end`: * * $queryBuilder->where( [ 'range_start' => new RawSQLValue( 'range_end' ) ] ) * $queryBuilder->where( $db->expr( 'range_start', '!=', new RawSQLValue( 'range_end' ) ) ) * * (When all values are literals, consider whether using RawSQLExpression is more readable.) * * @param string $value Value (SQL fragment) * @param-taint $value exec_sql * @since 1.43 */ public function __construct( string $value ) { $this->value = $value; } /** * @internal to be used by rdbms library only */ public function toSql(): string { return $this->value; } } PK ! l���T T rdbms/ChangedTablesTracker.phpnu �Iw�� <?php namespace Wikimedia\Rdbms; use RuntimeException; /** * Utility class that keeps a list of DB tables that were (presumably) changed by write queries. This should only be * used in PHPUnit tests. * This class should remain a static util class, because it must never be replaced by a mock in tests. * * @ingroup Database * @internal */ class ChangedTablesTracker { private const TRACKED_VERBS = [ 'INSERT', 'UPDATE', 'REPLACE' ]; private static bool $trackingEnabled = false; /** @var array<string,array<string,true>> Map of [ domain => [ table name => true ] ] */ private static array $tableMap = []; /** * Enables query tracking and resets the list of changed tables. */ public static function startTracking(): void { if ( !defined( 'MW_PHPUNIT_TEST' ) ) { throw new RuntimeException( "This class is internal and should only be used in tests." ); } if ( self::$trackingEnabled ) { throw new RuntimeException( "Tracking is already enabled" ); } self::$trackingEnabled = true; self::$tableMap = []; } /** * Get the tables for a given domain ID * * @param string $domainId * @return string[] */ public static function getTables( string $domainId ): array { $tableMap = self::$tableMap[$domainId] ?? []; return array_keys( $tableMap ); } /** * Reset the internal list and disable tracking. */ public static function stopTracking(): void { if ( !self::$trackingEnabled ) { throw new RuntimeException( "Tracking is not enabled" ); } self::$tableMap = []; self::$trackingEnabled = false; } /** * When tracking is enabled and a query alters tables, record the list of tables that are altered. * Any table that gets dropped gets removed from the list of altered tables. */ public static function recordQuery( DatabaseDomain $domain, Query $query ): void { if ( !self::$trackingEnabled ) { return; } if ( !$query->isWriteQuery() ) { return; } $domainId = $domain->getId(); $queryVerb = $query->getVerb(); $tableName = $query->getWriteTable(); if ( $tableName === null ) { return; } if ( $queryVerb === 'DROP' ) { // Special case: if a table is being dropped, forget about it. unset( self::$tableMap[$domainId][$tableName] ); return; } if ( !in_array( $queryVerb, self::TRACKED_VERBS, true ) ) { return; } self::$tableMap[$domainId][$tableName] = true; } } PK ! Vu*� � rdbms/field/MySQLField.phpnu �Iw�� <?php namespace Wikimedia\Rdbms; class MySQLField implements Field { private string $name; private string $tablename; /** @var mixed */ private $default; /** @var int */ private $max_length; private bool $nullable; private bool $is_pk; private bool $is_unique; private bool $is_multiple; private bool $is_key; private string $type; private bool $binary; private bool $is_numeric; private bool $is_blob; private bool $is_unsigned; private bool $is_zerofill; public function __construct( $info ) { $this->name = $info->name; $this->tablename = $info->table; $this->default = $info->def; $this->max_length = $info->max_length; $this->nullable = !$info->not_null; $this->is_pk = $info->primary_key; $this->is_unique = $info->unique_key; $this->is_multiple = $info->multiple_key; $this->is_key = ( $this->is_pk || $this->is_unique || $this->is_multiple ); $this->type = $info->type; $this->binary = $info->binary ?? false; $this->is_numeric = $info->numeric ?? false; $this->is_blob = $info->blob ?? false; $this->is_unsigned = $info->unsigned ?? false; $this->is_zerofill = $info->zerofill ?? false; } /** * @return string */ public function name() { return $this->name; } /** * @return string */ public function tableName() { return $this->tablename; } /** * @return string */ public function type() { return $this->type; } /** * @return bool */ public function isNullable() { return $this->nullable; } public function defaultValue() { return $this->default; } /** * @return bool */ public function isKey() { return $this->is_key; } /** * @return bool */ public function isMultipleKey() { return $this->is_multiple; } /** * @return bool */ public function isBinary() { return $this->binary; } /** * @return bool */ public function isNumeric() { return $this->is_numeric; } /** * @return bool */ public function isBlob() { return $this->is_blob; } /** * @return bool */ public function isUnsigned() { return $this->is_unsigned; } /** * @return bool */ public function isZerofill() { return $this->is_zerofill; } } PK ! �ՂV6 6 rdbms/field/SQLiteField.phpnu �Iw�� <?php namespace Wikimedia\Rdbms; use stdClass; class SQLiteField implements Field { private stdClass $info; private string $tableName; public function __construct( stdClass $info, string $tableName ) { $this->info = $info; $this->tableName = $tableName; } public function name() { return $this->info->name; } public function tableName() { return $this->tableName; } public function defaultValue() { if ( is_string( $this->info->dflt_value ) ) { // Typically quoted if ( preg_match( '/^\'(.*)\'$/', $this->info->dflt_value, $matches ) ) { return str_replace( "''", "'", $matches[1] ); } } return $this->info->dflt_value; } /** * @return bool */ public function isNullable() { return !$this->info->notnull; } public function type() { return $this->info->type; } } PK ! ��> rdbms/field/Field.phpnu �Iw�� <?php namespace Wikimedia\Rdbms; /** * Base for all database-specific classes representing information about database fields * @ingroup Database */ interface Field { /** * Field name * @return string */ public function name(); /** * Name of table this field belongs to * @return string */ public function tableName(); /** * Database type * @return string */ public function type(); /** * Whether this field can store NULL values * @return bool */ public function isNullable(); } PK ! V}�j j rdbms/field/PostgresField.phpnu �Iw�� <?php namespace Wikimedia\Rdbms; class PostgresField implements Field { private string $name; private string $tablename; private string $type; private bool $nullable; /** @var int */ private $max_length; private bool $deferred; private bool $deferrable; private ?string $conname; private bool $has_default; /** @var mixed */ private $default; /** * @param DatabasePostgres $db * @param string $table * @param string $field * @return null|PostgresField */ public static function fromText( DatabasePostgres $db, $table, $field ) { $q = <<<SQL SELECT attnotnull, attlen, conname AS conname, atthasdef, pg_get_expr(adbin, adrelid) AS adsrc, COALESCE(condeferred, FALSE) AS deferred, COALESCE(condeferrable, FALSE) AS deferrable, CASE WHEN typname = 'int2' THEN 'smallint' WHEN typname = 'int4' THEN 'integer' WHEN typname = 'int8' THEN 'bigint' WHEN typname = 'bpchar' THEN 'char' ELSE typname END AS typname FROM pg_class c JOIN pg_namespace n ON (n.oid = c.relnamespace) JOIN pg_attribute a ON (a.attrelid = c.oid) JOIN pg_type t ON (t.oid = a.atttypid) LEFT JOIN pg_constraint o ON (o.conrelid = c.oid AND a.attnum = ANY(o.conkey) AND o.contype = 'f') LEFT JOIN pg_attrdef d on c.oid=d.adrelid and a.attnum=d.adnum WHERE relkind = 'r' AND nspname=%s AND relname=%s AND attname=%s; SQL; foreach ( $db->getCoreSchemas() as $schema ) { $res = $db->query( sprintf( $q, $db->addQuotes( $schema ), $db->addQuotes( $table ), $db->addQuotes( $field ) ), __METHOD__ ); $row = $res->fetchObject(); if ( !$row ) { continue; } $n = new PostgresField; $n->type = $row->typname; $n->nullable = !$row->attnotnull; $n->name = $field; $n->tablename = $table; $n->max_length = $row->attlen; $n->deferrable = (bool)$row->deferrable; $n->deferred = (bool)$row->deferred; $n->conname = $row->conname; $n->has_default = (bool)$row->atthasdef; $n->default = $row->adsrc; return $n; } return null; } public function name() { return $this->name; } public function tableName() { return $this->tablename; } public function type() { return $this->type; } public function isNullable() { return $this->nullable; } public function maxLength() { return $this->max_length; } public function is_deferrable() { return $this->deferrable; } public function is_deferred() { return $this->deferred; } public function conname() { return $this->conname; } /** * @since 1.19 * @return mixed|false */ public function defaultValue() { if ( $this->has_default ) { return $this->default; } else { return false; } } } PK ! �i� * rdbms/dbal/DoctrineAbstractSchemaTrait.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\Rdbms; use Doctrine\DBAL\Platforms\AbstractPlatform; use Doctrine\DBAL\Schema\Schema; /** * Trait for schema spec of doctrine-based abstract schema * @since 1.36 * @internal */ trait DoctrineAbstractSchemaTrait { private AbstractPlatform $platform; private function addTableToSchema( Schema $schema, array $schemaSpec ) { $prefix = $this->platform->getName() === 'postgresql' ? '' : '/*_*/'; $table = $schema->createTable( $prefix . $schemaSpec['name'] ); foreach ( $schemaSpec['columns'] as $column ) { $table->addColumn( $column['name'], $column['type'], $column['options'] ); } foreach ( $schemaSpec['indexes'] as $index ) { if ( $index['unique'] === true ) { $table->addUniqueIndex( $index['columns'], $index['name'], $index['options'] ?? [] ); } else { $table->addIndex( $index['columns'], $index['name'], $index['flags'] ?? [], $index['options'] ?? [] ); } } if ( isset( $schemaSpec['pk'] ) && $schemaSpec['pk'] !== [] ) { $table->setPrimaryKey( $schemaSpec['pk'] ); } if ( isset( $schemaSpec['table_options'] ) ) { $table->addOption( 'table_options', implode( ' ', $schemaSpec['table_options'] ) ); } else { $table->addOption( 'table_options', '/*$wgDBTableOptions*/' ); } return $schema; } } PK ! Z�q q rdbms/dbal/EnumType.phpnu �Iw�� <?php namespace Wikimedia\Rdbms; use Doctrine\DBAL\Platforms\AbstractPlatform; use Doctrine\DBAL\Types\Type; use InvalidArgumentException; /** * Custom handling for ENUM datatype * * NOTE: Use of this type is discouraged unless necessary. Please use * alternative types where possible. See T119173 for the RFC discussion * about this type and potential alternatives. * * @see https://phabricator.wikimedia.org/T119173 */ class EnumType extends Type { public const ENUM = 'mwenum'; /** * Gets the SQL declaration snippet for an ENUM column * * @param mixed[] $column Column definition * @param AbstractPlatform $platform * * @return string */ public function getSQLDeclaration( array $column, AbstractPlatform $platform ) { // SQLite does not support ENUM type if ( $platform->getName() == 'sqlite' ) { return 'TEXT'; } // PostgreSQL does support but needs custom handling. // This just returns a string name that references the // actual ENUM which will be created by CREATE TYPE command // If 'fixed' option is not passed, this field will use TEXT if ( $platform->getName() == 'postgresql' ) { if ( !$column['fixed'] ) { return 'TEXT'; } return strtoupper( $column['name'] . '_enum' ); } if ( $platform->getName() == 'mysql' ) { $enumValues = $this->formatValues( $column['enum_values'] ); return "ENUM( $enumValues )"; } } /** * Gets the sql portion to create ENUM for Postgres table column * * @param mixed[] $column * @param AbstractPlatform $platform * * @see MWPostgreSqlPlatform::_getCreateTableSQL() * @throws \InvalidArgumentException * @return string */ public function makeEnumTypeSql( $column, $platform ) { if ( $platform->getName() !== 'postgresql' ) { throw new InvalidArgumentException( __METHOD__ . ' can only be called on Postgres platform' ); } $enumName = strtoupper( $column['name'] . '_enum' ); $enumValues = $this->formatValues( $column['enum_values'] ); $typeSql = "\n\nCREATE TYPE $enumName AS ENUM( $enumValues )"; return $typeSql; } /** * Get the imploded values suitable for pushing directly into ENUM(); * * @param string[] $values * @return string */ public function formatValues( $values ) { $values = implode( "','", $values ); $enumValues = "'" . $values . "'"; return $enumValues; } public function getName() { return self::ENUM; } } PK ! �g�� � rdbms/dbal/MWMySQLPlatform.phpnu �Iw�� <?php namespace Wikimedia\Rdbms; use Doctrine\DBAL\Platforms\MySQLPlatform; class MWMySQLPlatform extends MySQLPlatform { /** * @inheritDoc */ public function getFloatDeclarationSQL( array $column ) { $double = $column['doublePrecision'] ?? false; $unsigned = $column['unsigned'] ?? false; $sql = $double ? 'DOUBLE PRECISION' : 'FLOAT'; return $sql . ( $unsigned ? ' UNSIGNED' : '' ); } } PK ! #R 9� � * rdbms/dbal/DoctrineSchemaChangeBuilder.phpnu �Iw�� <?php namespace Wikimedia\Rdbms; use Doctrine\DBAL\Platforms\AbstractPlatform; use Doctrine\DBAL\Schema\Comparator; use Doctrine\DBAL\Schema\Schema; /** * @experimental * @unstable */ class DoctrineSchemaChangeBuilder implements SchemaChangeBuilder { use DoctrineAbstractSchemaTrait; private AbstractPlatform $platform; /** * A builder object that take abstract schema definition and produces sql to create the tables. * * @param AbstractPlatform $platform A Doctrine Platform object, Can be Mysql, Sqlite, etc. */ public function __construct( AbstractPlatform $platform ) { $this->platform = $platform; } private function getTableSchema( array $tableSpec ): Schema { if ( !$tableSpec ) { // Used for not yet created tables. return new Schema(); } return $this->addTableToSchema( new Schema(), $tableSpec ); } public function getSchemaChangeSql( array $schemaChangeSpec ): array { $comparator = new Comparator(); $schemaDiff = $comparator->compare( $this->getTableSchema( $schemaChangeSpec['before'] ), $this->getTableSchema( $schemaChangeSpec['after'] ) ); return $schemaDiff->toSql( $this->platform ); } } PK ! z~� � rdbms/dbal/TinyIntType.phpnu �Iw�� <?php namespace Wikimedia\Rdbms; use Doctrine\DBAL\Platforms\AbstractPlatform; use Doctrine\DBAL\Types\PhpIntegerMappingType; use Doctrine\DBAL\Types\Type; /** * Handling smallest integer data type */ class TinyIntType extends Type implements PhpIntegerMappingType { public const TINYINT = 'mwtinyint'; public function getSQLDeclaration( array $fieldDeclaration, AbstractPlatform $platform ) { if ( $platform->getName() == 'mysql' ) { if ( !empty( $fieldDeclaration['length'] ) && is_numeric( $fieldDeclaration['length'] ) ) { $length = $fieldDeclaration['length']; return "TINYINT($length)" . $this->getCommonIntegerTypeDeclarationForMySQL( $fieldDeclaration ); } return 'TINYINT' . $this->getCommonIntegerTypeDeclarationForMySQL( $fieldDeclaration ); } return $platform->getSmallIntTypeDeclarationSQL( $fieldDeclaration ); } protected function getCommonIntegerTypeDeclarationForMySQL( array $columnDef ) { $autoinc = ''; if ( !empty( $columnDef['autoincrement'] ) ) { $autoinc = ' AUTO_INCREMENT'; } return !empty( $columnDef['unsigned'] ) ? ' UNSIGNED' . $autoinc : $autoinc; } public function getName() { return self::TINYINT; } } PK ! �i�9 9 rdbms/dbal/SchemaBuilder.phpnu �Iw�� <?php namespace Wikimedia\Rdbms; /** * Interface SchemaBuilder that gets a definition and produces SQL based on RDBMS * * @experimental * @unstable */ interface SchemaBuilder { /** * An example of $schema value: * [ * 'name' => 'actor', * 'columns' => [ * [ 'actor_id', 'bigint', [ 'Unsigned' => true, 'Notnull' => true ] ], * [ 'actor_user', 'integer', [ 'Unsigned' => true ] ], * [ 'actor_name', 'string', [ 'Length' => 255, 'Notnull' => true ] ], * ], * 'indexes' => [ * [ 'actor_user', [ 'actor_user' ], 'unique' => true ], * [ 'actor_name', [ 'actor_name' ], 'unique' => true ] * ], * 'pk' => [ 'actor_id' ] * ], * @param array $schema * @return void */ public function addTable( array $schema ); /** * @return string[] SQLs to run */ public function getSql(); } PK ! �"*� " rdbms/dbal/SchemaChangeBuilder.phpnu �Iw�� <?php namespace Wikimedia\Rdbms; /** * Interface SchemaChangeBuilder that gets a definition and produces ALTER TABLE SQL based on RDBMS * * @experimental * @unstable */ interface SchemaChangeBuilder { /** * An example of $schema value: * [ * 'comment' => 'Adding foo field', * 'before' => <Before snapshot of the abstract schema> * 'after' => <After snapshot of the abstract schema> * ], * @param array $schemaChangeSpec * @return string[] */ public function getSchemaChangeSql( array $schemaChangeSpec ): array; } PK ! z���l l $ rdbms/dbal/DoctrineSchemaBuilder.phpnu �Iw�� <?php namespace Wikimedia\Rdbms; use Doctrine\DBAL\Platforms\AbstractPlatform; use Doctrine\DBAL\Schema\Schema; /** * @experimental * @unstable */ class DoctrineSchemaBuilder implements SchemaBuilder { use DoctrineAbstractSchemaTrait; private Schema $schema; private AbstractPlatform $platform; /** * A builder object that take abstract schema definition and produces sql to create the tables. * * @param AbstractPlatform $platform A Doctrine Platform object, Can be Mysql, Sqlite, etc. */ public function __construct( AbstractPlatform $platform ) { $this->schema = new Schema(); $this->platform = $platform; } /** * @inheritDoc */ public function addTable( array $schema ) { $this->addTableToSchema( $this->schema, $schema ); } /** * @inheritDoc */ public function getSql() { return $this->schema->toSql( $this->platform ); } } PK ! R[z� � + rdbms/dbal/DoctrineSchemaBuilderFactory.phpnu �Iw�� <?php namespace Wikimedia\Rdbms; use Doctrine\DBAL\Platforms\AbstractPlatform; use Doctrine\DBAL\Platforms\SqlitePlatform; use Doctrine\DBAL\Types\Type; use InvalidArgumentException; /** * @experimental * @unstable */ class DoctrineSchemaBuilderFactory { /** * @param string $platform one of strings 'mysql', 'postgres' or 'sqlite' * @return DoctrineSchemaBuilder */ public function getSchemaBuilder( string $platform ) { return new DoctrineSchemaBuilder( $this->getPlatform( $platform ) ); } /** * @param string $platform one of strings 'mysql', 'postgres' or 'sqlite' * @return DoctrineSchemaChangeBuilder */ public function getSchemaChangeBuilder( $platform ) { return new DoctrineSchemaChangeBuilder( $this->getPlatform( $platform ) ); } /** * @param string $platform * @return AbstractPlatform */ private function getPlatform( string $platform ) { switch ( $platform ) { case 'mysql': $platformObject = new MWMySQLPlatform; break; case 'postgres': $platformObject = new MWPostgreSqlPlatform; break; case 'sqlite': $platformObject = new SqlitePlatform; break; default: throw new InvalidArgumentException( 'Unknown platform: ' . $platform ); } $customTypes = [ 'Enum' => [ EnumType::class, EnumType::ENUM ], 'Tinyint' => [ TinyIntType::class, TinyIntType::TINYINT ], 'Timestamp' => [ TimestampType::class, TimestampType::TIMESTAMP ], ]; foreach ( $customTypes as $type => [ $class, $name ] ) { if ( !Type::hasType( $name ) ) { Type::addType( $name, $class ); } $platformObject->registerDoctrineTypeMapping( $type, $name ); } return $platformObject; } } PK ! �@$w� � rdbms/dbal/TimestampType.phpnu �Iw�� <?php namespace Wikimedia\Rdbms; use Doctrine\DBAL\Platforms\AbstractPlatform; use Doctrine\DBAL\Types\Type; /** * Handling timestamp edge cases in mediawiki. * https://www.mediawiki.org/wiki/Manual:Timestamp */ class TimestampType extends Type { public const TIMESTAMP = 'mwtimestamp'; public function getSQLDeclaration( array $fieldDeclaration, AbstractPlatform $platform ) { if ( $platform->getName() == 'mysql' ) { // "infinite" (in expiry values has to be VARBINARY) if ( isset( $fieldDeclaration['allowInfinite'] ) && $fieldDeclaration['allowInfinite'] ) { return 'VARBINARY(14)'; } return 'BINARY(14)'; } if ( $platform->getName() == 'sqlite' ) { return 'BLOB'; } if ( $platform->getName() == 'postgresql' ) { return 'TIMESTAMPTZ'; } return $platform->getDateTimeTzTypeDeclarationSQL( $fieldDeclaration ); } public function getName() { return self::TIMESTAMP; } } PK ! s `� # rdbms/dbal/MWPostgreSqlPlatform.phpnu �Iw�� <?php namespace Wikimedia\Rdbms; use Doctrine\DBAL\Platforms\PostgreSQLPlatform; use Wikimedia\Timestamp\ConvertibleTimestamp; class MWPostgreSqlPlatform extends PostgreSQLPlatform { /** * Handles Postgres unique timestamp format * @inheritDoc * * @param mixed[] $column The column definition array. * @return string Postgres specific SQL code portion needed to set a default value. */ public function getDefaultValueDeclarationSQL( $column ) { $type = $column['type']; $default = $column['default'] ?? null; if ( $type instanceof TimestampType && $default ) { if ( isset( $column['allowInfinite'] ) && $column['allowInfinite'] && $default === 'infinity' ) { $pgTimestamp = $default; } else { $timestamp = new ConvertibleTimestamp( $default ); $pgTimestamp = $timestamp->getTimestamp( TS_POSTGRES ); } return " DEFAULT '$pgTimestamp' "; } return parent::getDefaultValueDeclarationSQL( $column ); } /** * @inheritDoc * phpcs:disable PSR2.Methods.MethodDeclaration.Underscore */ protected function _getCreateTableSQL( $name, $columns, array $options = [] ) { // phpcs:enable $tableSql = parent::_getCreateTableSQL( $name, $columns, $options ); foreach ( $columns as $column ) { if ( $column['type'] instanceof EnumType && $column['fixed'] ) { // PostgreSQL does support ENUM datatype but they need to be // created severally with CREATE TYPE command for each column // as it's not possible to feed the values directly in the // column declaration as it could be done in MySQL. $typeSql = $column['type']->makeEnumTypeSql( $column, $this ); array_unshift( $tableSql, $typeSql ); } } return $tableSql; } /** * @inheritDoc */ public function getBlobTypeDeclarationSQL( array $column ) { // MySQL goes with varbinary for collation reasons, but postgres can't // properly understand BYTEA type and works just fine with TEXT type // FIXME: This should be fixed at some point (T257755) return 'TEXT'; } /** * @inheritDoc */ public function getBinaryTypeDeclarationSQL( array $column ) { // MySQL goes with varbinary for collation reasons, but postgres can't // properly understand BYTEA type and works just fine with TEXT type // FIXME: This should be fixed at some point (T257755) return 'TEXT'; } /** * @inheritDoc */ public function getFloatDeclarationSQL( array $column ) { return 'FLOAT'; } /** * @inheritDoc */ public function getDateTimeTzTypeDeclarationSQL( array $column ) { return 'TIMESTAMPTZ'; } } PK ! �[Qy2 2 GhostFieldAccessTrait.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\Reflection; /** * Trait for accessing "ghost fields". * * Ghost fields are fields that have been created in an object instance * by PHP's unserialize() mechanism, though they no longer exist * in the current version of the corresponding class. * * Accessing non-public ghost fields offers some challenges due to * how they are handled by PHP internally. * * @see https://www.php.net/manual/en/language.types.array.php#language.types.array.casting * @since 1.36 */ trait GhostFieldAccessTrait { /** * Get the value of the ghost field named $name, * or null if the field does not exist. * * @param string $name * @param class-string ...$aliases * @return mixed|null */ private function getGhostFieldValue( string $name, string ...$aliases ) { if ( isset( $this->$name ) ) { return $this->$name; } $data = (array)$this; // Protected variables have a '*' prepended to the variable name. // These prepended values have null bytes on either side. $protectedName = "\x00*\x00{$name}"; if ( isset( $data[$protectedName] ) ) { return $data[$protectedName]; } // Private variables have the class name prepended to the variable name. // These prepended values have null bytes on either side. $thisClass = get_class( $this ); $privateName = "\x00{$thisClass}\x00{$name}"; if ( isset( $data[$privateName] ) ) { return $data[$privateName]; } // Check old aliased class names as well. foreach ( $aliases as $thisClass ) { $privateName = "\x00{$thisClass}\x00{$name}"; if ( isset( $data[$privateName] ) ) { return $data[$privateName]; } } return null; } /** * In PHP <= 8.1, private fields of a class are not properly restored * when the class is aliased to a new name, since the private fields are * prefixed with the *old* name of the class. This method can be used * to restore them if present after deserialization. * * @param string $name * @param class-string ...$aliases */ private function restoreAliasedGhostField( string $name, string ...$aliases ): void { $data = (array)$this; foreach ( $aliases as $thisClass ) { $privateName = "\x00{$thisClass}\x00{$name}"; if ( isset( $data[$privateName] ) ) { $this->$name = $data[$privateName]; unset( $data[$privateName] ); return; } } } } PK ! (ʧ�� � UDPTransport.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ use Wikimedia\IPUtils; /** * A generic class to send a message over UDP * * If a message prefix is provided to the constructor or via * UDPTransport::newFromString(), the payload of the UDP datagrams emitted * will be formatted with the prefix and a single space at the start of each * line. This is the payload format expected by the udp2log service. * * @since 1.25 */ class UDPTransport { // Limit to 64 KiB public const MAX_PAYLOAD_SIZE = 65507; private string $host; private int $port; /** @var bool|string */ private $prefix; private int $domain; /** * @param string $host IP address to send to * @param int $port port number * @param int $domain AF_INET or AF_INET6 constant * @param string|bool $prefix Prefix to use, false for no prefix */ public function __construct( $host, $port, $domain, $prefix = false ) { $this->host = $host; $this->port = $port; $this->domain = $domain; $this->prefix = $prefix; } /** * @param string $info In the format of "udp://host:port/prefix" * @return UDPTransport */ public static function newFromString( $info ) { if ( preg_match( '!^udp:(?://)?\[([0-9a-fA-F:]+)\]:(\d+)(?:/(.*))?$!', $info, $m ) ) { // IPv6 bracketed host $host = $m[1]; $port = intval( $m[2] ); $prefix = $m[3] ?? false; $domain = AF_INET6; } elseif ( preg_match( '!^udp:(?://)?([a-zA-Z0-9.-]+):(\d+)(?:/(.*))?$!', $info, $m ) ) { $host = $m[1]; if ( !IPUtils::isIPv4( $host ) ) { $host = gethostbyname( $host ); } $port = intval( $m[2] ); $prefix = $m[3] ?? false; $domain = AF_INET; } else { throw new InvalidArgumentException( __METHOD__ . ': Invalid UDP specification' ); } return new self( $host, $port, $domain, $prefix ); } /** * @param string $text */ public function emit( $text ): void { // Clean it up for the multiplexer if ( $this->prefix !== false ) { $text = preg_replace( '/^/m', $this->prefix . ' ', $text ); if ( strlen( $text ) > self::MAX_PAYLOAD_SIZE - 1 ) { $text = substr( $text, 0, self::MAX_PAYLOAD_SIZE - 1 ); } if ( substr( $text, -1 ) != "\n" ) { $text .= "\n"; } } elseif ( strlen( $text ) > self::MAX_PAYLOAD_SIZE ) { $text = substr( $text, 0, self::MAX_PAYLOAD_SIZE ); } $sock = socket_create( $this->domain, SOCK_DGRAM, SOL_UDP ); if ( !$sock ) { // @todo should this throw an exception? return; } socket_sendto( $sock, $text, strlen( $text ), 0, $this->host, $this->port ); socket_close( $sock ); } } PK ! �n�c8 8 HashRing.phpnu �Iw�� <?php /** * Convenience class for weighted consistent hash rings. * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ /** * Convenience class for weighted consistent hash rings * * This deterministically maps "keys" to a set of "locations" while avoiding clumping * * Each location is represented by a number of nodes on a ring proportionate to the ratio * of its weight compared to the total location weight. Note positions are deterministically * derived from the hash of the location name. Nodes are responsible for the portion of the * ring, counter-clockwise, up until the next node. Locations are responsible for all portions * of the ring that the location's nodes are responsible for. * * A location that is temporarily "ejected" is said to be absent from the "live" ring. * If no location ejections are active, then the base ring and live ring are identical. * * This class is designed in a way that using the "md5" algorithm will make it compatible * with libketama, e.g. OPT_LIBKETAMA_COMPATIBLE from the PECL memcached extension or "ketama" * from twemproxy. This can simplify the process of switching client libraries. However, note * that different clients might use incompatible 32-bit memcached value flag conventions. * * @since 1.22 */ class HashRing { /** @var string Hashing algorithm for hash() */ protected $algo; /** @var int[] Non-empty (location => integer weight) */ protected $weightByLocation; /** @var int[] Map of (location => UNIX timestamp) */ protected $ejectExpiryByLocation; /** @var array[] Non-empty position-ordered list of (position, location name) */ protected $baseRing; /** @var array[]|null Non-empty position-ordered list of (position, location name) */ protected $liveRing; /** @var integer Overall number of node groups per server */ private const HASHES_PER_LOCATION = 40; /** @var integer Number of nodes in a node group */ private const SECTORS_PER_HASH = 4; public const KEY_POS = 0; public const KEY_LOCATION = 1; /** @var int Consider all locations */ public const RING_ALL = 0; /** @var int Only consider "live" locations */ public const RING_LIVE = 1; /** * Make a consistent hash ring given a set of locations and their weight values * * @param int[] $map Map of (location => weight) * @param string $algo Hashing algorithm listed in hash_algos() [optional] * @param int[] $ejections Map of (location => UNIX timestamp) for ejection expiries * @since 1.31 */ public function __construct( array $map, $algo = 'sha1', array $ejections = [] ) { $this->init( $map, $algo, $ejections ); } /** * @param int[] $map Map of (location => integer) * @param string $algo Hashing algorithm * @param int[] $ejections Map of (location => UNIX timestamp) for ejection expires */ protected function init( array $map, $algo, array $ejections ) { if ( !in_array( $algo, hash_algos(), true ) ) { throw new RuntimeException( __METHOD__ . ": unsupported '$algo' hash algorithm." ); } $weightByLocation = array_filter( $map ); if ( $weightByLocation === [] ) { throw new UnexpectedValueException( "No locations with non-zero weight." ); } elseif ( min( $map ) < 0 ) { throw new InvalidArgumentException( "Location weight cannot be negative." ); } $this->algo = $algo; $this->weightByLocation = $weightByLocation; $this->ejectExpiryByLocation = $ejections; $this->baseRing = $this->buildLocationRing( $this->weightByLocation ); } /** * Get the location of an item on the ring * * @param string $item * @return string Location * @throws UnexpectedValueException */ final public function getLocation( $item ) { return $this->getLocations( $item, 1 )[0]; } /** * Get the location of an item on the ring followed by the next ring locations * * @param string $item * @param int $limit Maximum number of locations to return * @param int $from One of the RING_* class constants * @return string[] List of locations * @throws UnexpectedValueException */ public function getLocations( $item, $limit, $from = self::RING_ALL ) { if ( $from === self::RING_ALL ) { $ring = $this->baseRing; } elseif ( $from === self::RING_LIVE ) { $ring = $this->getLiveRing(); } else { throw new InvalidArgumentException( "Invalid ring source specified." ); } // Short-circuit for the common single-location case. Note that if there was only one // location and it was ejected from the live ring, getLiveRing() would have error out. if ( count( $this->weightByLocation ) == 1 ) { return ( $limit > 0 ) ? [ $ring[0][self::KEY_LOCATION] ] : []; } // Locate the node index for this item's position on the hash ring $itemIndex = $this->findNodeIndexForPosition( $this->getItemPosition( $item ), $ring ); $locations = []; $currentIndex = null; while ( count( $locations ) < $limit ) { if ( $currentIndex === null ) { $currentIndex = $itemIndex; } else { $currentIndex = $this->getNextClockwiseNodeIndex( $currentIndex, $ring ); if ( $currentIndex === $itemIndex ) { break; // all nodes visited } } // @phan-suppress-next-line PhanTypeMismatchDimFetchNullable False positive $nodeLocation = $ring[$currentIndex][self::KEY_LOCATION]; if ( !in_array( $nodeLocation, $locations, true ) ) { // Ignore other nodes for the same locations already added $locations[] = $nodeLocation; } } return $locations; } /** * @param float $position * @param array[] $ring Either the base or live ring * @return int|null */ private function findNodeIndexForPosition( $position, $ring ) { $count = count( $ring ); if ( $count === 0 ) { return null; } $index = null; $lowPos = 0; $highPos = $count; while ( true ) { $midPos = (int)( ( $lowPos + $highPos ) / 2 ); if ( $midPos === $count ) { $index = 0; break; } $midVal = $ring[$midPos][self::KEY_POS]; $midMinusOneVal = ( $midPos === 0 ) ? 0 : $ring[$midPos - 1][self::KEY_POS]; if ( $position <= $midVal && $position > $midMinusOneVal ) { $index = $midPos; break; } if ( $midVal < $position ) { $lowPos = $midPos + 1; } else { $highPos = $midPos - 1; } if ( $lowPos > $highPos ) { $index = 0; break; } } return $index; } /** * Get the map of locations to weight (does not include zero weight items) * * @return int[] */ public function getLocationWeights() { return $this->weightByLocation; } /** * Remove a location from the "live" hash ring * * @param string $location * @param int $ttl Seconds * @return bool Whether some non-ejected locations are left * @throws UnexpectedValueException */ public function ejectFromLiveRing( $location, $ttl ) { if ( !isset( $this->weightByLocation[$location] ) ) { throw new UnexpectedValueException( "No location '$location' in the ring." ); } $expiry = $this->getCurrentTime() + $ttl; $this->ejectExpiryByLocation[$location] = $expiry; $this->liveRing = null; // invalidate ring cache return ( count( $this->ejectExpiryByLocation ) < count( $this->weightByLocation ) ); } /** * Get the location of an item on the "live" ring * * @param string $item * @return string Location * @throws UnexpectedValueException */ final public function getLiveLocation( $item ) { return $this->getLocations( $item, 1, self::RING_LIVE )[0]; } /** * Get the location of an item on the "live" ring, as well as the next locations * * @param string $item * @param int $limit Maximum number of locations to return * @return string[] List of locations * @throws UnexpectedValueException */ final public function getLiveLocations( $item, $limit ) { return $this->getLocations( $item, $limit, self::RING_LIVE ); } /** * Get the map of "live" locations to weight (does not include zero weight items) * * @return int[] * @throws UnexpectedValueException */ public function getLiveLocationWeights() { $now = $this->getCurrentTime(); return array_diff_key( $this->weightByLocation, array_filter( $this->ejectExpiryByLocation, static function ( $expiry ) use ( $now ) { return ( $expiry > $now ); } ) ); } /** * @param int[] $weightByLocation * @return array[] */ private function buildLocationRing( array $weightByLocation ) { $locationCount = count( $weightByLocation ); $totalWeight = array_sum( $weightByLocation ); $ring = []; // Assign nodes to all locations based on location weight $claimed = []; // (position as string => (node, index)) foreach ( $weightByLocation as $location => $weight ) { $ratio = $weight / $totalWeight; // There $locationCount * (HASHES_PER_LOCATION * 4) nodes available; // assign a few groups of nodes to this location based on its weight. $nodesQuartets = intval( $ratio * self::HASHES_PER_LOCATION * $locationCount ); for ( $qi = 0; $qi < $nodesQuartets; ++$qi ) { // For efficiency, get 4 points per hash call and 4X node count. // If $algo is MD5, then this matches that of with libketama. // See https://github.com/RJ/ketama/blob/master/libketama/ketama.c $positions = $this->getNodePositionQuartet( "{$location}-{$qi}" ); foreach ( $positions as $gi => $position ) { $node = ( $qi * self::SECTORS_PER_HASH + $gi ) . "@$location"; $posKey = (string)$position; // large integer if ( isset( $claimed[$posKey] ) ) { // Disallow duplicates (name decides precedence) if ( $claimed[$posKey]['node'] > $node ) { continue; } else { unset( $ring[$claimed[$posKey]['index']] ); } } $ring[] = [ self::KEY_POS => $position, self::KEY_LOCATION => $location ]; $claimed[$posKey] = [ 'node' => $node, 'index' => count( $ring ) - 1 ]; } } } // Sort the locations into clockwise order based on the hash ring position usort( $ring, static function ( $a, $b ) { if ( $a[self::KEY_POS] === $b[self::KEY_POS] ) { throw new UnexpectedValueException( 'Duplicate node positions.' ); } return ( $a[self::KEY_POS] < $b[self::KEY_POS] ? -1 : 1 ); } ); return $ring; } /** * @param string $item Key * @return float Ring position; integral number in [0, 4294967296] (2^32) */ private function getItemPosition( $item ) { // If $algo is MD5, then this matches that of with libketama. // See https://github.com/RJ/ketama/blob/master/libketama/ketama.c $octets = substr( hash( $this->algo, (string)$item, true ), 0, 4 ); if ( strlen( $octets ) != 4 ) { throw new UnexpectedValueException( __METHOD__ . ": {$this->algo} is < 32 bits." ); } $pos = unpack( 'V', $octets )[1]; if ( $pos < 0 ) { // Most-significant-bit is set, causing unpack() to return a negative integer due // to the fact that it returns a signed int. Cast it to an unsigned integer string. $pos = sprintf( '%u', $pos ); } return (float)$pos; } /** * @param string $nodeGroupName * @return float[] Four ring positions on [0, 4294967296] (2^32) */ private function getNodePositionQuartet( $nodeGroupName ) { $octets = substr( hash( $this->algo, (string)$nodeGroupName, true ), 0, 16 ); if ( strlen( $octets ) != 16 ) { throw new UnexpectedValueException( __METHOD__ . ": {$this->algo} is < 128 bits." ); } $positions = []; foreach ( unpack( 'V4', $octets ) as $signed ) { $positions[] = (float)sprintf( '%u', $signed ); } return $positions; } /** * @param int $i Valid index for a node in the ring * @param array[] $ring Either the base or live ring * @return int Valid index for a node in the ring */ private function getNextClockwiseNodeIndex( $i, $ring ) { if ( !isset( $ring[$i] ) ) { throw new UnexpectedValueException( __METHOD__ . ": reference index is invalid." ); } $next = $i + 1; return ( $next < count( $ring ) ) ? $next : 0; } /** * Get the "live" hash ring (which does not include ejected locations) * * @return array[] * @throws UnexpectedValueException */ protected function getLiveRing() { if ( !$this->ejectExpiryByLocation ) { return $this->baseRing; // nothing ejected } $now = $this->getCurrentTime(); if ( $this->liveRing === null || min( $this->ejectExpiryByLocation ) <= $now ) { // Live ring needs to be regenerated... $this->ejectExpiryByLocation = array_filter( $this->ejectExpiryByLocation, static function ( $expiry ) use ( $now ) { return ( $expiry > $now ); } ); if ( count( $this->ejectExpiryByLocation ) ) { // Some locations are still ejected from the ring $liveRing = []; foreach ( $this->baseRing as $nodeInfo ) { $location = $nodeInfo[self::KEY_LOCATION]; if ( !isset( $this->ejectExpiryByLocation[$location] ) ) { $liveRing[] = $nodeInfo; } } } else { $liveRing = $this->baseRing; } $this->liveRing = $liveRing; } if ( !$this->liveRing ) { throw new UnexpectedValueException( "The live ring is currently empty." ); } return $this->liveRing; } /** * @return int UNIX timestamp */ protected function getCurrentTime() { return time(); } public function __serialize() { return [ 'algorithm' => $this->algo, 'locations' => $this->weightByLocation, 'ejections' => $this->ejectExpiryByLocation ]; } public function __unserialize( $data ) { if ( is_array( $data ) ) { $this->init( $data['locations'] ?? [], $data['algorithm'] ?? 'sha1', $data['ejections'] ?? [] ); } else { throw new UnexpectedValueException( __METHOD__ . ": unable to decode JSON." ); } } } PK ! 5go8 Timing.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ use Psr\Log\LoggerAwareInterface; use Psr\Log\LoggerInterface; use Psr\Log\NullLogger; /** * An interface to help developers measure the performance of their applications. * This interface closely matches the W3C's User Timing specification. * The key differences are: * * - The reference point for all measurements which do not explicitly specify * a start time is $_SERVER['REQUEST_TIME_FLOAT'], not navigationStart. * - Successive calls to mark() and measure() with the same entry name cause * the previous entry to be overwritten. This ensures that there is a 1:1 * mapping between names and entries. * - Because there is a 1:1 mapping, instead of getEntriesByName(), we have * getEntryByName(). * * The in-line documentation incorporates content from the User Timing Specification * https://www.w3.org/TR/user-timing/ * Copyright © 2013 World Wide Web Consortium, (MIT, ERCIM, Keio, Beihang). * https://www.w3.org/Consortium/Legal/2015/doc-license * * @since 1.27 */ class Timing implements LoggerAwareInterface { /** @var array[] */ private $entries = []; /** @var LoggerInterface */ protected $logger; public function __construct( array $params = [] ) { $this->clearMarks(); $this->setLogger( $params['logger'] ?? new NullLogger() ); } /** * Sets a logger instance on the object. * * @param LoggerInterface $logger */ public function setLogger( LoggerInterface $logger ) { $this->logger = $logger; } /** * Store a timestamp with the associated name (a "mark") * * @param string $markName The name associated with the timestamp. * If there already exists an entry by that name, it is overwritten. * @return array The mark that has been created. */ public function mark( $markName ) { $this->entries[$markName] = [ 'name' => $markName, 'entryType' => 'mark', 'startTime' => microtime( true ), 'duration' => 0, ]; return $this->entries[$markName]; } /** * @param string|null $markName The name of the mark that should * be cleared. If not specified, all marks will be cleared. */ public function clearMarks( $markName = null ) { if ( $markName !== null ) { unset( $this->entries[$markName] ); } else { $this->entries = [ 'requestStart' => [ 'name' => 'requestStart', 'entryType' => 'mark', 'startTime' => $_SERVER['REQUEST_TIME_FLOAT'], 'duration' => 0, ], ]; } } /** * This method stores the duration between two marks along with * the associated name (a "measure"). * * If neither the startMark nor the endMark argument is specified, * measure() will store the duration from $_SERVER['REQUEST_TIME_FLOAT'] to * the current time. * If the startMark argument is specified, but the endMark argument is not * specified, measure() will store the duration from the most recent * occurrence of the start mark to the current time. * If both the startMark and endMark arguments are specified, measure() * will store the duration from the most recent occurrence of the start * mark to the most recent occurrence of the end mark. * * @param string $measureName * @param string $startMark * @param string|null $endMark * @return array|bool The measure that has been created, or false if either * the start mark or the end mark do not exist. */ public function measure( $measureName, $startMark = 'requestStart', $endMark = null ) { $start = $this->getEntryByName( $startMark ); if ( $start === null ) { $this->logger->error( __METHOD__ . ": The mark '$startMark' does not exist" ); return false; } $startTime = $start['startTime']; if ( $endMark ) { $end = $this->getEntryByName( $endMark ); if ( $end === null ) { $this->logger->error( __METHOD__ . ": The mark '$endMark' does not exist" ); return false; } $endTime = $end['startTime']; } else { $endTime = microtime( true ); } $this->entries[$measureName] = [ 'name' => $measureName, 'entryType' => 'measure', 'startTime' => $startTime, 'duration' => $endTime - $startTime, ]; return $this->entries[$measureName]; } /** * Sort entries in chronological order with respect to startTime. */ private function sortEntries() { uasort( $this->entries, static function ( $a, $b ) { return $a['startTime'] <=> $b['startTime']; } ); } /** * @return array[] All entries in chronological order. */ public function getEntries() { $this->sortEntries(); return $this->entries; } /** * @param string $entryType * @return array[] Entries (in chronological order) that have the same value * for the entryType attribute as the $entryType parameter. */ public function getEntriesByType( $entryType ) { $this->sortEntries(); $entries = []; foreach ( $this->entries as $entry ) { if ( $entry['entryType'] === $entryType ) { $entries[] = $entry; } } return $entries; } /** * @param string $name * @return array|null Entry named $name or null if it does not exist. */ public function getEntryByName( $name ) { return $this->entries[$name] ?? null; } } PK ! ���� � MappedIterator.phpnu �Iw�� <?php /** * Convenience class for generating iterators from iterators. * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ /** * Convenience class for generating iterators from iterators. * * @since 1.21 */ class MappedIterator extends FilterIterator { /** @var callable */ protected $vCallback; /** @var callable|null */ protected $aCallback; /** @var array */ protected $cache = []; /** @var bool whether rewind() has been called */ protected $rewound = false; /** * Build a new iterator from a base iterator by having the former wrap the * later, returning the result of "value" callback for each current() invocation. * The callback takes the result of current() on the base iterator as an argument. * The keys of the base iterator are reused verbatim. * * An "accept" callback can also be provided which will be called for each value in * the base iterator (post-callback) and will return true if that value should be * included in iteration of the MappedIterator (otherwise it will be filtered out). * * @param Iterator|array $iter * @param callable $vCallback Value transformation callback * @param array $options Options map (includes "accept") (since 1.22) * @phan-param array{accept?:callable} $options * @throws UnexpectedValueException */ public function __construct( $iter, $vCallback, array $options = [] ) { if ( is_array( $iter ) ) { $baseIterator = new ArrayIterator( $iter ); } elseif ( $iter instanceof Iterator ) { $baseIterator = $iter; } else { throw new UnexpectedValueException( "Invalid base iterator provided." ); } parent::__construct( $baseIterator ); $this->vCallback = $vCallback; $this->aCallback = $options['accept'] ?? null; } public function next(): void { $this->cache = []; parent::next(); } public function rewind(): void { $this->rewound = true; $this->cache = []; parent::rewind(); } public function accept(): bool { $inner = $this->getInnerIterator(); '@phan-var Iterator $inner'; $value = call_user_func( $this->vCallback, $inner->current() ); $ok = ( $this->aCallback ) ? call_user_func( $this->aCallback, $value ) : true; if ( $ok ) { $this->cache['current'] = $value; } return $ok; } #[\ReturnTypeWillChange] public function key() { $this->init(); return parent::key(); } public function valid(): bool { $this->init(); return parent::valid(); } #[\ReturnTypeWillChange] public function current() { $this->init(); if ( parent::valid() ) { return $this->cache['current']; } else { return null; // out of range } } /** * Obviate the usual need for rewind() before using a FilterIterator in a manual loop */ protected function init() { if ( !$this->rewound ) { $this->rewind(); } } } PK ! �10�� � mime/defines.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file * @ingroup Mime */ /** @{ * Media types. * This defines constants for the value returned by File::getMediaType() */ // unknown format define( 'MEDIATYPE_UNKNOWN', 'UNKNOWN' ); // some bitmap image or image source (like psd, etc). Can't scale up. define( 'MEDIATYPE_BITMAP', 'BITMAP' ); // some vector drawing (SVG, WMF, PS, ...) or image source (oo-draw, etc). Can scale up. define( 'MEDIATYPE_DRAWING', 'DRAWING' ); // simple audio file (ogg, mp3, wav, midi, whatever) define( 'MEDIATYPE_AUDIO', 'AUDIO' ); // simple video file (ogg, mpg, etc; // no not include formats here that may contain executable sections or scripts!) define( 'MEDIATYPE_VIDEO', 'VIDEO' ); // Scriptable Multimedia (flash, advanced video container formats, etc) define( 'MEDIATYPE_MULTIMEDIA', 'MULTIMEDIA' ); // Office Documents, Spreadsheets (office formats possibly containing apples, scripts, etc) define( 'MEDIATYPE_OFFICE', 'OFFICE' ); // Plain text (possibly containing program code or scripts) define( 'MEDIATYPE_TEXT', 'TEXT' ); // binary executable define( 'MEDIATYPE_EXECUTABLE', 'EXECUTABLE' ); // archive file (zip, tar, etc) define( 'MEDIATYPE_ARCHIVE', 'ARCHIVE' ); // 3D file types (stl) define( 'MEDIATYPE_3D', '3D' ); /** @} */ PK ! 3>ش�< �< mime/XmlTypeCheck.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\Mime; use Exception; use XMLReader; /** * XML syntax and type checker. * * Since MediaWiki 1.24.2, this uses XMLReader instead of xml_parse, which gives us * more control over the expansion of XML entities. When passed to the * callback, entities will be fully expanded, but may report the XML is * invalid if expanding the entities are likely to cause a DoS. * * @newable * @since 1.12.0 * @ingroup Mime */ class XmlTypeCheck { /** * @var bool|null Will be set to true or false to indicate whether the file is * well-formed XML. Note that this doesn't check schema validity. */ public $wellFormed = null; /** * @var bool Will be set to true if the optional element filter returned * a match at some point. */ public $filterMatch = false; /** * Will contain the type of filter hit if the optional element filter returned * a match at some point. * @var mixed */ public $filterMatchType = false; /** * @var string Name of the document's root element, including any namespace * as an expanded URL. */ public $rootElement = ''; /** * @var string[] A stack of strings containing the data of each xml element as it's processed. * Append data to the top string of the stack, then pop off the string and process it when the * element is closed. */ protected $elementData = []; /** * @var array A stack of element names and attributes, as we process them. */ protected $elementDataContext = []; /** * @var int Current depth of the data stack. */ protected $stackDepth = 0; /** @var callable|null */ protected $filterCallback; /** * @var array Additional parsing options */ private $parserOptions = [ 'processing_instruction_handler' => null, 'external_dtd_handler' => '', 'dtd_handler' => '', 'require_safe_dtd' => true ]; /** * Allow filtering an XML file. * * Filters should return either true or a string to indicate something * is wrong with the file. $this->filterMatch will store if the * file failed validation (true = failed validation). * $this->filterMatchType will contain the validation error. * $this->wellFormed will contain whether the xml file is well-formed. * * @note If multiple filters are hit, only one of them will have the * result stored in $this->filterMatchType. * * @param string $input a filename or string containing the XML element * @param callable|null $filterCallback (optional) * Function to call to do additional custom validity checks from the * SAX element handler event. This gives you access to the element * namespace, name, attributes, and text contents. * Filter should return a truthy value describing the error. * @param bool $isFile (optional) indicates if the first parameter is a * filename (default, true) or if it is a string (false) * @param array $options list of additional parsing options: * processing_instruction_handler: Callback for xml_set_processing_instruction_handler * external_dtd_handler: Callback for the url of external dtd subset * dtd_handler: Callback given the full text of the <!DOCTYPE declaration. * require_safe_dtd: Only allow non-recursive entities in internal dtd (default true) */ public function __construct( $input, $filterCallback = null, $isFile = true, $options = [] ) { $this->filterCallback = $filterCallback; $this->parserOptions = array_merge( $this->parserOptions, $options ); $this->validateFromInput( $input, $isFile ); } /** * Alternative constructor: from filename * * @param string $fname the filename of an XML document * @param callable|null $filterCallback (optional) * Function to call to do additional custom validity checks from the * SAX element handler event. This gives you access to the element * namespace, name, and attributes, but not to text contents. * Filter should return 'true' to toggle on $this->filterMatch * @return XmlTypeCheck */ public static function newFromFilename( $fname, $filterCallback = null ) { return new self( $fname, $filterCallback, true ); } /** * Alternative constructor: from string * * @param string $string a string containing an XML element * @param callable|null $filterCallback (optional) * Function to call to do additional custom validity checks from the * SAX element handler event. This gives you access to the element * namespace, name, and attributes, but not to text contents. * Filter should return 'true' to toggle on $this->filterMatch * @return XmlTypeCheck */ public static function newFromString( $string, $filterCallback = null ) { return new self( $string, $filterCallback, false ); } /** * Get the root element. Simple accessor to $rootElement * * @return string */ public function getRootElement() { return $this->rootElement; } /** * @param string $xml * @param bool $isFile */ private function validateFromInput( $xml, $isFile ) { $reader = new XMLReader(); if ( $isFile ) { $s = $reader->open( $xml, null, LIBXML_NOERROR | LIBXML_NOWARNING ); } else { $s = $reader->XML( $xml, null, LIBXML_NOERROR | LIBXML_NOWARNING ); } if ( $s !== true ) { // Couldn't open the XML $this->wellFormed = false; } else { // phpcs:ignore Generic.PHP.NoSilencedErrors -- suppress deprecation per T268847 $oldDisable = @libxml_disable_entity_loader( true ); $reader->setParserProperty( XMLReader::SUBST_ENTITIES, true ); try { $this->validate( $reader ); } catch ( Exception $e ) { // Calling this malformed, because we didn't parse the whole // thing. Maybe just an external entity refernce. $this->wellFormed = false; $reader->close(); // phpcs:ignore Generic.PHP.NoSilencedErrors @libxml_disable_entity_loader( $oldDisable ); throw $e; } $reader->close(); // phpcs:ignore Generic.PHP.NoSilencedErrors @libxml_disable_entity_loader( $oldDisable ); } } private function readNext( XMLReader $reader ) { set_error_handler( function ( $line, $file ) { $this->wellFormed = false; return true; } ); $ret = $reader->read(); restore_error_handler(); return $ret; } private function validate( $reader ) { // First, move through anything that isn't an element, and // handle any processing instructions with the callback do { if ( !$this->readNext( $reader ) ) { // Hit the end of the document before any elements $this->wellFormed = false; return; } if ( $reader->nodeType === XMLReader::PI ) { $this->processingInstructionHandler( $reader->name, $reader->value ); } if ( $reader->nodeType === XMLReader::DOC_TYPE ) { $this->dtdHandler( $reader ); } } while ( $reader->nodeType != XMLReader::ELEMENT ); // Process the rest of the document do { switch ( $reader->nodeType ) { case XMLReader::ELEMENT: $name = $this->expandNS( $reader->name, $reader->namespaceURI ); if ( $this->rootElement === '' ) { $this->rootElement = $name; } $empty = $reader->isEmptyElement; $attrs = $this->getAttributesArray( $reader ); $this->elementOpen( $name, $attrs ); if ( $empty ) { $this->elementClose(); } break; case XMLReader::END_ELEMENT: $this->elementClose(); break; case XMLReader::WHITESPACE: case XMLReader::SIGNIFICANT_WHITESPACE: case XMLReader::CDATA: case XMLReader::TEXT: $this->elementData( $reader->value ); break; case XMLReader::ENTITY_REF: // Unexpanded entity (maybe external?), // don't send to the filter (xml_parse didn't) break; case XMLReader::COMMENT: // Don't send to the filter (xml_parse didn't) break; case XMLReader::PI: // Processing instructions can happen after the header too $this->processingInstructionHandler( $reader->name, $reader->value ); break; case XMLReader::DOC_TYPE: // We should never see a doctype after first // element. $this->wellFormed = false; break; default: // One of DOC, ENTITY, END_ENTITY, // NOTATION, or XML_DECLARATION // xml_parse didn't send these to the filter, so we won't. } } while ( $this->readNext( $reader ) ); if ( $this->stackDepth !== 0 ) { $this->wellFormed = false; } elseif ( $this->wellFormed === null ) { $this->wellFormed = true; } } /** * Get all of the attributes for an XMLReader's current node * @param XMLReader $r * @return array of attributes */ private function getAttributesArray( XMLReader $r ) { $attrs = []; while ( $r->moveToNextAttribute() ) { if ( $r->namespaceURI === 'http://www.w3.org/2000/xmlns/' ) { // XMLReader treats xmlns attributes as normal // attributes, while xml_parse doesn't continue; } $name = $this->expandNS( $r->name, $r->namespaceURI ); $attrs[$name] = $r->value; } return $attrs; } /** * @param string $name element or attribute name, maybe with a full or short prefix * @param string $namespaceURI * @return string the name prefixed with namespaceURI */ private function expandNS( $name, $namespaceURI ) { if ( $namespaceURI ) { $parts = explode( ':', $name ); $localname = array_pop( $parts ); return "$namespaceURI:$localname"; } return $name; } /** * @param string $name * @param array $attribs */ private function elementOpen( $name, $attribs ) { $this->elementDataContext[] = [ $name, $attribs ]; $this->elementData[] = ''; $this->stackDepth++; } private function elementClose() { [ $name, $attribs ] = array_pop( $this->elementDataContext ); $data = array_pop( $this->elementData ); $this->stackDepth--; $callbackReturn = false; if ( is_callable( $this->filterCallback ) ) { $callbackReturn = ( $this->filterCallback )( $name, $attribs, $data ); } if ( $callbackReturn ) { // Filter hit! $this->filterMatch = true; $this->filterMatchType = $callbackReturn; } } /** * @param string $data */ private function elementData( $data ) { // Collect any data here, and we'll run the callback in elementClose $this->elementData[ $this->stackDepth - 1 ] .= trim( $data ); } /** * @param string $target * @param string $data */ private function processingInstructionHandler( $target, $data ) { $callbackReturn = false; if ( $this->parserOptions['processing_instruction_handler'] ) { // @phan-suppress-next-line PhanTypeInvalidCallable false positive $callbackReturn = $this->parserOptions['processing_instruction_handler']( $target, $data ); } if ( $callbackReturn ) { // Filter hit! $this->filterMatch = true; $this->filterMatchType = $callbackReturn; } } /** * Handle coming across a <!DOCTYPE declaration. * * @param XMLReader $reader Reader currently pointing at DOCTYPE node. */ private function dtdHandler( XMLReader $reader ) { $externalCallback = $this->parserOptions['external_dtd_handler']; $generalCallback = $this->parserOptions['dtd_handler']; $checkIfSafe = $this->parserOptions['require_safe_dtd']; if ( !$externalCallback && !$generalCallback && !$checkIfSafe ) { return; } $dtd = $reader->readOuterXml(); $callbackReturn = false; if ( $generalCallback ) { $callbackReturn = $generalCallback( $dtd ); } if ( $callbackReturn ) { // Filter hit! $this->filterMatch = true; $this->filterMatchType = $callbackReturn; $callbackReturn = false; } $parsedDTD = $this->parseDTD( $dtd ); if ( $externalCallback && isset( $parsedDTD['type'] ) ) { $callbackReturn = $externalCallback( $parsedDTD['type'], $parsedDTD['publicid'] ?? null, $parsedDTD['systemid'] ?? null ); } if ( $callbackReturn ) { // Filter hit! $this->filterMatch = true; $this->filterMatchType = $callbackReturn; } if ( $checkIfSafe && isset( $parsedDTD['internal'] ) && !$this->checkDTDIsSafe( $parsedDTD['internal'] ) ) { $this->wellFormed = false; } } /** * Check if the internal subset of the DTD is safe. * * We whitelist an extremely restricted subset of DTD features. * * Safe is defined as: * * Only contains entity definitions (e.g. No <!ATLIST ) * * Entity definitions are not "system" entities * * Entity definitions are not "parameter" (i.e. %) entities * * Entity definitions do not reference other entities except & * and quotes. Entity aliases (where the entity contains only * another entity are allowed) * * Entity references aren't overly long (>255 bytes). * * <!ATTLIST svg xmlns:xlink CDATA #FIXED "http://www.w3.org/1999/xlink"> * allowed if matched exactly for compatibility with graphviz * * Comments. * * @param string $internalSubset The internal subset of the DTD * @return bool true if safe. */ private function checkDTDIsSafe( $internalSubset ) { $res = preg_match( '/^(?:\s*<!ENTITY\s+\S+\s+' . '(?:"(?:&[^"%&;]{1,64};|(?:[^"%&]|&|"){0,255})"' . '|\'(?:&[^\'%&;]{1,64};|(?:[^\'%&]|&|'){0,255})\')\s*>' . '|\s*<!--(?:[^-]|-[^-])*-->' . '|\s*<!ATTLIST svg xmlns:xlink CDATA #FIXED ' . '"http:\/\/www.w3.org\/1999\/xlink">)*\s*$/', $internalSubset ); return (bool)$res; } /** * Parse DTD into parts. * * If there is an error parsing the dtd, sets wellFormed to false. * * @param string $dtd * @return array Possibly containing keys publicid, systemid, type and internal. */ private function parseDTD( $dtd ) { $m = []; $res = preg_match( '/^<!DOCTYPE\s*\S+\s*' . '(?:(?P<typepublic>PUBLIC)\s*' . '(?:"(?P<pubquote>[^"]*)"|\'(?P<pubapos>[^\']*)\')' . // public identifer '\s*"(?P<pubsysquote>[^"]*)"|\'(?P<pubsysapos>[^\']*)\'' . // system identifier '|(?P<typesystem>SYSTEM)\s*' . '(?:"(?P<sysquote>[^"]*)"|\'(?P<sysapos>[^\']*)\')' . ')?\s*' . '(?:\[\s*(?P<internal>.*)\])?\s*>$/s', $dtd, $m ); if ( !$res ) { $this->wellFormed = false; return []; } $parsed = []; foreach ( $m as $field => $value ) { if ( $value === '' || is_numeric( $field ) ) { continue; } switch ( $field ) { case 'typepublic': case 'typesystem': $parsed['type'] = $value; break; case 'pubquote': case 'pubapos': $parsed['publicid'] = $value; break; case 'pubsysquote': case 'pubsysapos': case 'sysquote': case 'sysapos': $parsed['systemid'] = $value; break; case 'internal': $parsed['internal'] = $value; break; } } return $parsed; } } /** @deprecated class alias since 1.43 */ class_alias( XmlTypeCheck::class, 'XmlTypeCheck' ); PK ! �b n+ n+ mime/MSCompoundFileReader.phpnu �Iw�� <?php /* * Copyright 2019 Wikimedia Foundation * * Licensed under the Apache License, Version 2.0 (the "License"); you may * not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software distributed * under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS * OF ANY KIND, either express or implied. See the License for the * specific language governing permissions and limitations under the License. */ namespace Wikimedia\Mime; use RuntimeException; /** * Read the directory of a Microsoft Compound File Binary file, a.k.a. an OLE * file, and detect the MIME type. * * References: * - MS-CFB https://msdn.microsoft.com/en-us/library/dd942138.aspx * - MS-XLS https://msdn.microsoft.com/en-us/library/cc313154.aspx * - MS-PPT https://msdn.microsoft.com/en-us/library/cc313106.aspx * - MS-DOC https://msdn.microsoft.com/en-us/library/cc313153.aspx * - Python olefile https://github.com/decalage2/olefile * - OpenOffice.org's Documentation of the Microsoft Compound Document * File Format https://www.openoffice.org/sc/compdocfileformat.pdf * * @since 1.33 * @ingroup Mime */ class MSCompoundFileReader { /** @var resource */ private $file; /** @var array */ private $header; /** @var string */ private $mime; /** @var string */ private $mimeFromClsid; /** @var string|null */ private $error; /** @var int|null */ private $errorCode; /** @var bool */ private $valid = false; /** @var int */ private $sectorLength; /** @var int[] */ private $difat; /** @var int[][] */ private $fat = []; private const TYPE_UNALLOCATED = 0; private const TYPE_STORAGE = 1; private const TYPE_STREAM = 2; private const TYPE_ROOT = 5; public const ERROR_FILE_OPEN = 1; public const ERROR_SEEK = 2; public const ERROR_READ = 3; public const ERROR_INVALID_SIGNATURE = 4; public const ERROR_READ_PAST_END = 5; public const ERROR_INVALID_FORMAT = 6; private const MIMES_BY_CLSID = [ // From http://justsolve.archiveteam.org/wiki/Microsoft_Compound_File '00020810-0000-0000-C000-000000000046' => 'application/vnd.ms-excel', '00020820-0000-0000-C000-000000000046' => 'application/vnd.ms-excel', '00020906-0000-0000-C000-000000000046' => 'application/msword', '64818D10-4F9B-11CF-86EA-00AA00B929E8' => 'application/vnd.ms-powerpoint', ]; /** * Read a file by name * * @param string $fileName The full path to the file * @return array An associative array of information about the file: * - valid: true if the file is valid, false otherwise * - error: An error message in English, should be present if valid=false * - errorCode: One of the self::ERROR_* constants * - mime: The MIME type detected from the directory contents * - mimeFromClsid: The MIME type detected from the CLSID on the root * directory entry */ public static function readFile( $fileName ) { $handle = fopen( $fileName, 'r' ); if ( $handle === false ) { return [ 'valid' => false, 'error' => 'file does not exist', 'errorCode' => self::ERROR_FILE_OPEN ]; } return self::readHandle( $handle ); } /** * Read from an open seekable handle * * @param resource $fileHandle * @return array An associative array of information about the file: * - valid: true if the file is valid, false otherwise * - error: An error message in English, should be present if valid=false * - errorCode: One of the self::ERROR_* constants * - mime: The MIME type detected from the directory contents * - mimeFromClsid: The MIME type detected from the CLSID on the root * directory entry */ public static function readHandle( $fileHandle ) { $reader = new self( $fileHandle ); $info = [ 'valid' => $reader->valid, 'mime' => $reader->mime, 'mimeFromClsid' => $reader->mimeFromClsid ]; if ( $reader->error ) { $info['error'] = $reader->error; $info['errorCode'] = $reader->errorCode; } return $info; } private function __construct( $fileHandle ) { $this->file = $fileHandle; try { $this->init(); } catch ( RuntimeException $e ) { $this->valid = false; $this->error = $e->getMessage(); $this->errorCode = $e->getCode(); } } private function init() { $this->header = $this->unpackOffset( 0, [ 'header_signature' => 8, 'header_clsid' => 16, 'minor_version' => 2, 'major_version' => 2, 'byte_order' => 2, 'sector_shift' => 2, 'mini_sector_shift' => 2, 'reserved' => 6, 'num_dir_sectors' => 4, 'num_fat_sectors' => 4, 'first_dir_sector' => 4, 'transaction_signature_number' => 4, 'mini_stream_cutoff_size' => 4, 'first_mini_fat_sector' => 4, 'num_mini_fat_sectors' => 4, 'first_difat_sector' => 4, 'num_difat_sectors' => 4, 'difat' => 436, ] ); if ( $this->header['header_signature'] !== "\xd0\xcf\x11\xe0\xa1\xb1\x1a\xe1" ) { $this->error( 'invalid signature: ' . bin2hex( $this->header['header_signature'] ), self::ERROR_INVALID_SIGNATURE ); } $this->sectorLength = 1 << $this->header['sector_shift']; $this->readDifat(); $this->readDirectory(); $this->valid = true; } private function sectorOffset( $sectorId ) { return $this->sectorLength * ( $sectorId + 1 ); } private function decodeClsid( $binaryClsid ) { $parts = unpack( 'Va/vb/vc/C8d', $binaryClsid ); return sprintf( "%08X-%04X-%04X-%02X%02X-%02X%02X%02X%02X%02X%02X", $parts['a'], $parts['b'], $parts['c'], $parts['d1'], $parts['d2'], $parts['d3'], $parts['d4'], $parts['d5'], $parts['d6'], $parts['d7'], $parts['d8'] ); } /** * @param int $offset * @param int[] $struct * @return array */ private function unpackOffset( $offset, $struct ) { $block = $this->readOffset( $offset, array_sum( $struct ) ); return $this->unpack( $block, 0, $struct ); } /** * @param string $block * @param int $offset * @param int[] $struct * @return array */ private function unpack( $block, $offset, $struct ) { $data = []; foreach ( $struct as $key => $length ) { if ( $length > 4 ) { $data[$key] = substr( $block, $offset, $length ); } else { $data[$key] = $this->bin2dec( $block, $offset, $length ); } $offset += $length; } return $data; } private function bin2dec( $str, $offset, $length ) { $value = 0; for ( $i = $length - 1; $i >= 0; $i-- ) { $value *= 256; $value += ord( $str[$offset + $i] ); } return $value; } private function readOffset( $offset, $length ) { $this->fseek( $offset ); // phpcs:ignore Generic.PHP.NoSilencedErrors.Discouraged $block = @fread( $this->file, $length ); if ( $block === false ) { $this->error( 'error reading from file', self::ERROR_READ ); } if ( strlen( $block ) !== $length ) { $this->error( 'unable to read the required number of bytes from the file', self::ERROR_READ_PAST_END ); } return $block; } private function readSector( $sectorId ) { return $this->readOffset( $this->sectorOffset( $sectorId ), 1 << $this->header['sector_shift'] ); } /** * @param string $message * @param int $code * @return never */ private function error( $message, $code ) { throw new RuntimeException( $message, $code ); } private function fseek( $offset ) { // phpcs:ignore Generic.PHP.NoSilencedErrors.Discouraged $result = @fseek( $this->file, $offset ); if ( $result !== 0 ) { $this->error( "unable to seek to offset $offset", self::ERROR_SEEK ); } } private function readDifat() { $binaryDifat = $this->header['difat']; $nextDifatSector = $this->header['first_difat_sector']; for ( $i = 0; $i < $this->header['num_difat_sectors']; $i++ ) { $block = $this->readSector( $nextDifatSector ); $binaryDifat .= substr( $block, 0, $this->sectorLength - 4 ); $nextDifatSector = $this->bin2dec( $block, $this->sectorLength - 4, 4 ); if ( $nextDifatSector == 0xFFFFFFFE ) { break; } } $this->difat = []; for ( $pos = 0; $pos < strlen( $binaryDifat ); $pos += 4 ) { $fatSector = $this->bin2dec( $binaryDifat, $pos, 4 ); if ( $fatSector < 0xFFFFFFFC ) { $this->difat[] = $fatSector; } else { break; } } } private function getNextSectorIdFromFat( $sectorId ) { $entriesPerSector = intdiv( $this->sectorLength, 4 ); $fatSectorId = intdiv( $sectorId, $entriesPerSector ); $fatSectorArray = $this->getFatSector( $fatSectorId ); return $fatSectorArray[$sectorId % $entriesPerSector]; } private function getFatSector( $fatSectorId ) { if ( !isset( $this->fat[$fatSectorId] ) ) { $fat = []; if ( !isset( $this->difat[$fatSectorId] ) ) { $this->error( 'FAT sector requested beyond the end of the DIFAT', self::ERROR_INVALID_FORMAT ); } $absoluteSectorId = $this->difat[$fatSectorId]; $block = $this->readSector( $absoluteSectorId ); for ( $pos = 0; $pos < strlen( $block ); $pos += 4 ) { $fat[] = $this->bin2dec( $block, $pos, 4 ); } $this->fat[$fatSectorId] = $fat; } return $this->fat[$fatSectorId]; } private function readDirectory() { $dirSectorId = $this->header['first_dir_sector']; $binaryDir = ''; $seenSectorIds = []; while ( $dirSectorId !== 0xFFFFFFFE ) { if ( isset( $seenSectorIds[$dirSectorId] ) ) { $this->error( 'FAT loop detected', self::ERROR_INVALID_FORMAT ); } $seenSectorIds[$dirSectorId] = true; $binaryDir .= $this->readSector( $dirSectorId ); $dirSectorId = $this->getNextSectorIdFromFat( $dirSectorId ); } $struct = [ 'name_raw' => 64, 'name_length' => 2, 'object_type' => 1, 'color' => 1, 'sid_left' => 4, 'sid_right' => 4, 'sid_child' => 4, 'clsid' => 16, 'state_bits' => 4, 'create_time_low' => 4, 'create_time_high' => 4, 'modify_time_low' => 4, 'modify_time_high' => 4, 'first_sector' => 4, 'size_low' => 4, 'size_high' => 4, ]; $entryLength = array_sum( $struct ); for ( $pos = 0; $pos < strlen( $binaryDir ); $pos += $entryLength ) { $entry = $this->unpack( $binaryDir, $pos, $struct ); // According to [MS-CFB] size_high may contain garbage due to a // bug in a writer, it's best to pretend it is zero $entry['size_high'] = 0; $type = $entry['object_type']; if ( $type == self::TYPE_UNALLOCATED ) { continue; } $name = iconv( 'UTF-16LE', 'UTF-8', substr( $entry['name_raw'], 0, $entry['name_length'] - 2 ) ); $clsid = $this->decodeClsid( $entry['clsid'] ); if ( $type == self::TYPE_ROOT && isset( self::MIMES_BY_CLSID[$clsid] ) ) { $this->mimeFromClsid = self::MIMES_BY_CLSID[$clsid]; } if ( $name === 'Workbook' ) { $this->mime = 'application/vnd.ms-excel'; } elseif ( $name === 'WordDocument' ) { $this->mime = 'application/msword'; } elseif ( $name === 'PowerPoint Document' ) { $this->mime = 'application/vnd.ms-powerpoint'; } } } } /** @deprecated class alias since 1.43 */ class_alias( MSCompoundFileReader::class, 'MSCompoundFileReader' ); PK ! 6�IMl l mime/MimeMapMinimal.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\Mime; /** * Built-in MIME types that cannot be overridden by site configuration. * * This class exists for backward compatibility only. New MIME types must be * added to MimeMap instead. * * @internal * @ingroup Mime */ class MimeMapMinimal { public const MIME_EXTENSIONS = [ 'application/ogg' => [ 'ogx', 'ogg', 'ogm', 'ogv', 'oga', 'spx', 'opus' ], 'application/pdf' => [ 'pdf' ], 'application/vnd.oasis.opendocument.chart' => [ 'odc' ], 'application/vnd.oasis.opendocument.chart-template' => [ 'otc' ], 'application/vnd.oasis.opendocument.database' => [ 'odb' ], 'application/vnd.oasis.opendocument.formula' => [ 'odf' ], 'application/vnd.oasis.opendocument.formula-template' => [ 'otf' ], 'application/vnd.oasis.opendocument.graphics' => [ 'odg' ], 'application/vnd.oasis.opendocument.graphics-template' => [ 'otg' ], 'application/vnd.oasis.opendocument.image' => [ 'odi' ], 'application/vnd.oasis.opendocument.image-template' => [ 'oti' ], 'application/vnd.oasis.opendocument.presentation' => [ 'odp' ], 'application/vnd.oasis.opendocument.presentation-template' => [ 'otp' ], 'application/vnd.oasis.opendocument.spreadsheet' => [ 'ods' ], 'application/vnd.oasis.opendocument.spreadsheet-template' => [ 'ots' ], 'application/vnd.oasis.opendocument.text' => [ 'odt' ], 'application/vnd.oasis.opendocument.text-master' => [ 'otm' ], 'application/vnd.oasis.opendocument.text-template' => [ 'ott' ], 'application/vnd.oasis.opendocument.text-web' => [ 'oth' ], 'application/javascript' => [ 'js' ], 'application/x-shockwave-flash' => [ 'swf' ], 'audio/midi' => [ 'mid', 'midi', 'kar' ], 'audio/mpeg' => [ 'mpga', 'mpa', 'mp2', 'mp3' ], 'audio/x-aiff' => [ 'aif', 'aiff', 'aifc' ], 'audio/x-wav' => [ 'wav' ], 'audio/ogg' => [ 'oga', 'spx', 'ogg', 'opus' ], 'audio/opus' => [ 'opus', 'ogg', 'oga', 'spx' ], 'image/x-bmp' => [ 'bmp' ], 'image/gif' => [ 'gif' ], 'image/jpeg' => [ 'jpeg', 'jpg', 'jpe' ], 'image/png' => [ 'png' ], 'image/svg+xml' => [ 'svg' ], 'image/svg' => [ 'svg' ], 'image/tiff' => [ 'tiff', 'tif' ], 'image/vnd.djvu' => [ 'djvu' ], 'image/x.djvu' => [ 'djvu' ], 'image/x-djvu' => [ 'djvu' ], 'image/x-portable-pixmap' => [ 'ppm' ], 'image/x-xcf' => [ 'xcf' ], 'text/plain' => [ 'txt' ], 'text/html' => [ 'html', 'htm' ], 'video/ogg' => [ 'ogv', 'ogm', 'ogg' ], 'video/mpeg' => [ 'mpg', 'mpeg' ], ]; public const MEDIA_TYPES = [ MEDIATYPE_OFFICE => [ 'application/pdf', 'application/vnd.oasis.opendocument.chart', 'application/vnd.oasis.opendocument.chart-template', 'application/vnd.oasis.opendocument.database', 'application/vnd.oasis.opendocument.formula', 'application/vnd.oasis.opendocument.formula-template', 'application/vnd.oasis.opendocument.graphics', 'application/vnd.oasis.opendocument.graphics-template', 'application/vnd.oasis.opendocument.image', 'application/vnd.oasis.opendocument.image-template', 'application/vnd.oasis.opendocument.presentation', 'application/vnd.oasis.opendocument.presentation-template', 'application/vnd.oasis.opendocument.spreadsheet', 'application/vnd.oasis.opendocument.spreadsheet-template', 'application/vnd.oasis.opendocument.text', 'application/vnd.oasis.opendocument.text-template', 'application/vnd.oasis.opendocument.text-master', 'application/vnd.oasis.opendocument.text-web', ], MEDIATYPE_EXECUTABLE => [ 'application/javascript', 'text/javascript', 'application/x-javascript', ], MEDIATYPE_MULTIMEDIA => [ 'application/x-shockwave-flash', 'application/ogg', 'audio/ogg', 'video/ogg', ], MEDIATYPE_AUDIO => [ 'audio/midi', 'audio/x-aiff', 'audio/x-wav', 'audio/mp3', 'audio/mpeg', ], MEDIATYPE_BITMAP => [ 'image/x-bmp', 'image/x-ms-bmp', 'image/bmp', 'image/gif', 'image/jpeg', 'image/png', 'image/tiff', 'image/vnd.djvu', 'image/x-xcf', 'image/x-portable-pixmap', ], MEDIATYPE_DRAWING => [ 'image/svg+xml', ], MEDIATYPE_TEXT => [ 'text/plain', 'text/html', ], MEDIATYPE_VIDEO => [ 'video/ogg', 'video/mpeg', ], MEDIATYPE_UNKNOWN => [ 'unknown/unknown', 'application/octet-stream', 'application/x-empty', ], ]; public const MIME_TYPE_ALIASES = [ 'text/javascript' => 'application/javascript', 'application/x-javascript' => 'application/javascript', 'audio/mpeg' => 'audio/mp3', 'audio/ogg' => 'application/ogg', 'video/ogg' => 'application/ogg', 'image/x-ms-bmp' => 'image/x-bmp', 'image/bmp' => 'image/x-bmp', 'application/octet-stream' => 'unknown/unknown', 'application/x-empty' => 'unknown/unknown', ]; } PK ! �4�*L *L mime/MimeMap.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\Mime; /** * Map of MIME types to file extensions and media types. * * @internal * @ingroup Mime */ class MimeMap { /** @var array Map of MIME types to an array of file extensions */ public const MIME_EXTENSIONS = [ 'application/ogg' => [ 'ogx', 'ogg', 'ogm', 'ogv', 'oga', 'spx', 'opus' ], 'application/pdf' => [ 'pdf' ], 'application/vnd.apple.mpegurl' => [ 'm3u8', 'm3u' ], 'application/vnd.ms-opentype' => [ 'otf' ], 'application/vnd.oasis.opendocument.chart' => [ 'odc' ], 'application/vnd.oasis.opendocument.chart-template' => [ 'otc' ], 'application/vnd.oasis.opendocument.database' => [ 'odb' ], 'application/vnd.oasis.opendocument.formula' => [ 'odf' ], 'application/vnd.oasis.opendocument.formula-template' => [ 'otf' ], 'application/vnd.oasis.opendocument.graphics' => [ 'odg' ], 'application/vnd.oasis.opendocument.graphics-template' => [ 'otg' ], 'application/vnd.oasis.opendocument.image' => [ 'odi' ], 'application/vnd.oasis.opendocument.image-template' => [ 'oti' ], 'application/vnd.oasis.opendocument.presentation' => [ 'odp' ], 'application/vnd.oasis.opendocument.presentation-template' => [ 'otp' ], 'application/vnd.oasis.opendocument.spreadsheet' => [ 'ods' ], 'application/vnd.oasis.opendocument.spreadsheet-template' => [ 'ots' ], 'application/vnd.oasis.opendocument.text' => [ 'odt' ], 'application/vnd.oasis.opendocument.text-master' => [ 'otm', 'odm' ], 'application/vnd.oasis.opendocument.text-template' => [ 'ott' ], 'application/vnd.oasis.opendocument.text-web' => [ 'oth' ], 'application/javascript' => [ 'js' ], 'application/x-mpegurl' => [ 'm3u', 'm3u8' ], 'application/x-shockwave-flash' => [ 'swf' ], 'audio/midi' => [ 'mid', 'midi', 'kar' ], 'audio/mpeg' => [ 'mpga', 'mpa', 'mp2', 'mp3' ], 'audio/x-aiff' => [ 'aif', 'aiff', 'aifc' ], 'audio/x-wav' => [ 'wav' ], 'audio/ogg' => [ 'oga', 'spx', 'ogg', 'opus' ], 'audio/opus' => [ 'opus', 'ogg', 'oga', 'spx' ], 'image/x-bmp' => [ 'bmp' ], 'image/gif' => [ 'gif' ], 'image/jpeg' => [ 'jpeg', 'jpg', 'jpe', 'jps' ], 'image/png' => [ 'png', 'apng' ], 'image/svg+xml' => [ 'svg' ], 'image/svg' => [ 'svg' ], 'image/tiff' => [ 'tiff', 'tif' ], 'image/vnd.djvu' => [ 'djvu', 'djv' ], 'image/x.djvu' => [ 'djvu' ], 'image/x-djvu' => [ 'djvu' ], 'image/x-portable-pixmap' => [ 'ppm' ], 'image/x-xcf' => [ 'xcf' ], 'text/plain' => [ 'txt' ], 'text/html' => [ 'html', 'htm' ], 'video/ogg' => [ 'ogv', 'ogm', 'ogg' ], 'video/mpeg' => [ 'mpg', 'mpeg', 'mpe' ], 'application/acad' => [ 'dwg' ], 'application/andrew-inset' => [ 'ez' ], 'application/mac-binhex40' => [ 'hqx' ], 'application/mac-compactpro' => [ 'cpt' ], 'application/mathml+xml' => [ 'mathml' ], 'application/msword' => [ 'doc', 'dot' ], 'application/octet-stream' => [ 'bin', 'dms', 'lha', 'lzh', 'exe', 'class', 'so', 'dll' ], 'application/oda' => [ 'oda' ], 'application/postscript' => [ 'ai', 'eps', 'ps' ], 'application/rdf+xml' => [ 'rdf', 'owl' ], 'application/smil' => [ 'smi', 'smil' ], 'application/srgs' => [ 'gram' ], 'application/srgs+xml' => [ 'grxml' ], 'application/vnd.mif' => [ 'mif' ], 'application/vnd.ms-excel' => [ 'xls', 'xlt', 'xla' ], 'application/vnd.ms-powerpoint' => [ 'ppt', 'pot', 'pps', 'ppa' ], 'application/vnd.wap.wbxml' => [ 'wbxml' ], 'application/vnd.wap.wmlc' => [ 'wmlc' ], 'application/vnd.wap.wmlscriptc' => [ 'wmlsc' ], 'application/voicexml+xml' => [ 'vxml' ], 'application/x-7z-compressed' => [ '7z' ], 'application/x-bcpio' => [ 'bcpio' ], 'application/x-bzip' => [ 'bz' ], 'application/x-bzip2' => [ 'bz2' ], 'application/x-cdlink' => [ 'vcd' ], 'application/x-chess-pgn' => [ 'pgn' ], 'application/x-cpio' => [ 'cpio' ], 'application/x-csh' => [ 'csh' ], 'application/x-dia-diagram' => [ 'dia' ], 'application/x-director' => [ 'dcr', 'dir', 'dxr' ], 'application/x-dvi' => [ 'dvi' ], 'application/x-futuresplash' => [ 'spl' ], 'application/x-gtar' => [ 'gtar', 'tar' ], 'application/x-gzip' => [ 'gz' ], 'application/x-hdf' => [ 'hdf' ], 'application/x-jar' => [ 'jar' ], 'application/json' => [ 'json' ], 'application/x-koan' => [ 'skp', 'skd', 'skt', 'skm' ], 'application/x-latex' => [ 'latex' ], 'application/x-netcdf' => [ 'nc', 'cdf' ], 'application/x-sh' => [ 'sh' ], 'application/x-shar' => [ 'shar' ], 'application/x-stuffit' => [ 'sit' ], 'application/x-sv4cpio' => [ 'sv4cpio' ], 'application/x-sv4crc' => [ 'sv4crc' ], 'application/x-tar' => [ 'tar' ], 'application/x-tcl' => [ 'tcl' ], 'application/x-tex' => [ 'tex' ], 'application/x-texinfo' => [ 'texinfo', 'texi' ], 'application/x-troff' => [ 't', 'tr', 'roff' ], 'application/x-troff-man' => [ 'man' ], 'application/x-troff-me' => [ 'me' ], 'application/x-troff-ms' => [ 'ms' ], 'application/x-ustar' => [ 'ustar' ], 'application/x-wais-source' => [ 'src' ], 'application/x-xpinstall' => [ 'xpi' ], 'application/xhtml+xml' => [ 'xhtml', 'xht' ], 'application/xslt+xml' => [ 'xslt' ], 'application/xml' => [ 'xml', 'xsl', 'xsd', 'kml' ], 'application/xml-dtd' => [ 'dtd' ], 'application/zip' => [ 'zip', 'jar', 'xpi', 'sxc', 'stc', 'sxd', 'std', 'sxi', 'sti', 'sxm', 'stm', 'sxw', 'stw' ], 'application/x-rar' => [ 'rar' ], 'font/collection' => [ 'ttc' ], 'font/otf' => [ 'ttf', 'otf' ], 'font/sfnt' => [ 'ttf', 'otf' ], 'font/ttf' => [ 'ttf', 'otf' ], 'application/font-sfnt' => [ 'ttf' ], 'font/woff' => [ 'woff' ], 'application/font-woff' => [ 'woff' ], 'font/woff2' => [ 'woff2' ], 'application/font-woff2' => [ 'woff2' ], 'application/vnd.ms-fontobject' => [ 'eot' ], 'application/x-font-ttf' => [ 'ttf' ], 'audio/basic' => [ 'au', 'snd' ], 'video/webm' => [ 'webm' ], 'audio/webm' => [ 'webm' ], 'audio/x-matroska' => [ 'mka', 'mkv' ], 'audio/x-mpegurl' => [ 'm3u' ], 'audio/x-ogg' => [ 'oga', 'ogg', 'spx', 'opus' ], 'audio/x-pn-realaudio' => [ 'ram', 'rm' ], 'audio/x-pn-realaudio-plugin' => [ 'rpm' ], 'audio/x-realaudio' => [ 'ra' ], 'audio/wav' => [ 'wav' ], 'audio/x-flac' => [ 'flac' ], 'audio/flac' => [ 'flac' ], 'chemical/x-pdb' => [ 'pdb' ], 'chemical/x-xyz' => [ 'xyz' ], 'image/bmp' => [ 'bmp' ], 'image/cgm' => [ 'cgm' ], 'image/ief' => [ 'ief' ], 'image/jp2' => [ 'jp2', 'j2k', 'jpg2' ], 'image/jpx' => [ 'jpf', 'jpx' ], 'image/vnd.microsoft.icon' => [ 'ico' ], 'image/vnd.wap.wbmp' => [ 'wbmp' ], 'image/webp' => [ 'webp' ], 'image/x-cmu-raster' => [ 'ras' ], 'image/x-icon' => [ 'ico' ], 'image/x-jps' => [ 'jps' ], 'image/x-ms-bmp' => [ 'bmp' ], 'image/x-portable-anymap' => [ 'pnm' ], 'image/x-portable-bitmap' => [ 'pbm' ], 'image/x-portable-graymap' => [ 'pgm' ], 'image/x-rgb' => [ 'rgb' ], 'image/x-photoshop' => [ 'psd' ], 'image/x-xbitmap' => [ 'xbm' ], 'image/x-xpixmap' => [ 'xpm' ], 'image/x-xwindowdump' => [ 'xwd' ], 'model/iges' => [ 'igs', 'iges' ], 'model/mesh' => [ 'msh', 'mesh', 'silo' ], 'model/vrml' => [ 'wrl', 'vrml' ], 'text/calendar' => [ 'ics', 'ifb' ], 'text/css' => [ 'css' ], 'text/csv' => [ 'csv' ], 'text/richtext' => [ 'rtx' ], 'text/rtf' => [ 'rtf' ], 'text/sgml' => [ 'sgml', 'sgm' ], 'text/tab-separated-values' => [ 'tsv' ], 'text/vnd.wap.wml' => [ 'wml' ], 'text/vnd.wap.wmlscript' => [ 'wmls' ], 'text/xml' => [ 'xml', 'xsl', 'xslt', 'rss', 'rdf' ], 'text/x-component' => [ 'htc' ], 'text/x-setext' => [ 'etx' ], 'text/x-sawfish' => [ 'jl' ], 'video/mp4' => [ 'mp4', 'm4a', 'm4p', 'm4b', 'm4r', 'm4v' ], 'audio/mp4' => [ 'm4a' ], 'video/quicktime' => [ 'qt', 'mov' ], 'video/vnd.mpegurl' => [ 'mxu' ], 'video/x-flv' => [ 'flv' ], 'video/x-matroska' => [ 'mkv', 'mka' ], 'video/x-msvideo' => [ 'avi' ], 'video/x-ogg' => [ 'ogv', 'ogm', 'ogg' ], 'video/x-sgi-movie' => [ 'movie' ], 'x-conference/x-cooltalk' => [ 'ice' ], 'application/vnd.openxmlformats-officedocument.wordprocessingml.document' => [ 'docx' ], 'application/vnd.openxmlformats-officedocument.wordprocessingml.template' => [ 'dotx' ], 'application/vnd.ms-word.document.macroenabled.12' => [ 'docm' ], 'application/vnd.ms-word.template.macroenabled.12' => [ 'dotm' ], 'application/vnd.openxmlformats-officedocument.presentationml.template' => [ 'potx' ], 'application/vnd.openxmlformats-officedocument.presentationml.slideshow' => [ 'ppsx' ], 'application/vnd.openxmlformats-officedocument.presentationml.presentation' => [ 'pptx' ], 'application/vnd.ms-powerpoint.addin.macroenabled.12' => [ 'ppam' ], 'application/vnd.ms-powerpoint.presentation.macroenabled.12' => [ 'pptm', 'potm' ], 'application/vnd.ms-powerpoint.slideshow.macroenabled.12' => [ 'ppsm' ], 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet' => [ 'xlsx' ], 'application/vnd.openxmlformats-officedocument.spreadsheetml.template' => [ 'xltx' ], 'application/vnd.ms-excel.sheet.macroenabled.12' => [ 'xlsm' ], 'application/vnd.ms-excel.template.macroenabled.12' => [ 'xltm' ], 'application/vnd.ms-excel.addin.macroenabled.12' => [ 'xlam' ], 'application/vnd.ms-excel.sheet.binary.macroenabled.12' => [ 'xlsb' ], 'model/gltf-binary' => [ 'glb' ], 'model/gltf+json' => [ 'gltf' ], 'model/vnd.dwfx+xps' => [ 'dwfx' ], 'application/vnd.ms-xpsdocument' => [ 'xps' ], 'chemical/x-mdl-molfile' => [ 'mol' ], 'chemical/x-mdl-sdfile' => [ 'sdf' ], 'chemical/x-mdl-rxnfile' => [ 'rxn' ], 'chemical/x-mdl-rdfile' => [ 'rd' ], 'chemical/x-mdl-rgfile' => [ 'rg' ], 'application/x-amf' => [ 'amf' ], 'application/sla' => [ 'stl' ], 'application/wasm' => [ 'wasm' ], // Vague pseudo-types should be at the end so that they don't take // precedence over the more specific types above in getMimeTypesFromExtension() 'application/x-opc+zip' => [ 'docx', 'dotx', 'docm', 'dotm', 'potx', 'ppsx', 'pptx', 'ppam', 'pptm', 'potm', 'ppsm', 'xlsx', 'xltx', 'xlsm', 'xltm', 'xlam', 'xlsb', 'dwfx', 'xps' ], 'application/vnd.oasis.opendocument' => [ 'odt', 'ott', 'odg', 'otg', 'odp', 'otp', 'ods', 'ots', 'odc', 'otc', 'odi', 'oti', 'odf', 'otf', 'odm', 'oth', ] ]; /** @var array Map of built-in media types and their associated MIME types */ public const MEDIA_TYPES = [ MEDIATYPE_OFFICE => [ 'application/pdf', 'application/vnd.oasis.opendocument.chart', 'application/vnd.oasis.opendocument.chart-template', 'application/vnd.oasis.opendocument.database', 'application/vnd.oasis.opendocument.formula', 'application/vnd.oasis.opendocument.formula-template', 'application/vnd.oasis.opendocument.graphics', 'application/vnd.oasis.opendocument.graphics-template', 'application/vnd.oasis.opendocument.image', 'application/vnd.oasis.opendocument.image-template', 'application/vnd.oasis.opendocument.presentation', 'application/vnd.oasis.opendocument.presentation-template', 'application/vnd.oasis.opendocument.spreadsheet', 'application/vnd.oasis.opendocument.spreadsheet-template', 'application/vnd.oasis.opendocument.text', 'application/vnd.oasis.opendocument.text-template', 'application/vnd.oasis.opendocument.text-master', 'application/vnd.oasis.opendocument.text-web', 'application/pdf', 'application/acrobat', 'application/msword', 'application/vnd.ms-excel', 'application/vnd.ms-powerpoint', 'application/x-director', 'image/vnd.djvu', 'image/x.djvu', 'image/x-djvu', 'text/rtf', 'application/vnd.openxmlformats-officedocument.wordprocessingml.document', 'application/vnd.openxmlformats-officedocument.wordprocessingml.template', 'application/vnd.ms-word.document.macroenabled.12', 'application/vnd.ms-word.template.macroenabled.12', 'application/vnd.openxmlformats-officedocument.presentationml.template', 'application/vnd.openxmlformats-officedocument.presentationml.slideshow', 'application/vnd.openxmlformats-officedocument.presentationml.presentation', 'application/vnd.ms-powerpoint.addin.macroenabled.12', 'application/vnd.ms-powerpoint.presentation.macroenabled.12', 'application/vnd.ms-powerpoint.presentation.macroenabled.12', 'application/vnd.ms-powerpoint.slideshow.macroenabled.12', 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet', 'application/vnd.openxmlformats-officedocument.spreadsheetml.template', 'application/vnd.ms-excel.sheet.macroenabled.12', 'application/vnd.ms-excel.template.macroenabled.12', 'application/vnd.ms-excel.addin.macroenabled.12', 'application/vnd.ms-excel.sheet.binary.macroenabled.12', ], MEDIATYPE_EXECUTABLE => [ 'application/javascript', 'text/javascript', 'application/x-javascript', 'application/javascript', 'text/javascript', 'application/x-javascript', 'application/x-ecmascript', 'text/ecmascript', 'application/x-bash', 'application/x-sh', 'application/x-csh', 'application/x-tcsh', 'application/x-tcl', 'application/x-perl', 'application/x-python', 'application/wasm', ], MEDIATYPE_MULTIMEDIA => [ 'application/x-shockwave-flash', 'application/ogg', 'application/vnd.apple.mpegurl', 'application/x-mpegurl', 'audio/ogg', 'video/ogg', 'application/ogg', 'application/x-ogg', 'audio/ogg', 'audio/x-ogg', 'video/ogg', 'video/x-ogg', 'application/x-shockwave-flash', 'audio/x-pn-realaudio-plugin', 'model/iges', 'model/mesh', 'model/vrml', 'video/quicktime', 'video/x-msvideo', ], MEDIATYPE_AUDIO => [ 'audio/midi', 'audio/x-aiff', 'audio/x-wav', 'audio/mp3', 'audio/mpeg', 'audio/mpeg', 'audio/mp3', 'audio/mpeg3', 'audio/mp4', 'audio/wav', 'audio/x-wav', 'audio/wave', 'audio/midi', 'audio/mid', 'audio/basic', 'audio/ogg', 'audio/opus', 'audio/x-aiff', 'audio/x-pn-realaudio', 'audio/x-realaudio', 'audio/webm', 'audio/x-matroska', 'audio/x-flac', 'audio/flac', ], MEDIATYPE_BITMAP => [ 'image/x-bmp', 'image/x-ms-bmp', 'image/bmp', 'image/gif', 'image/jpeg', 'image/png', 'image/tiff', 'image/vnd.djvu', 'image/x-xcf', 'image/x-portable-pixmap', 'image/gif', 'image/png', 'image/x-png', 'image/ief', 'image/jpeg', 'image/x-jps', 'image/pjpeg', 'image/jp2', 'image/jpx', 'image/xbm', 'image/tiff', 'image/x-icon', 'image/x-ico', 'image/vnd.microsoft.icon', 'image/x-rgb', 'image/x-portable-pixmap', 'image/x-portable-graymap', 'image/x-portable-greymap', 'image/x-bmp', 'image/x-ms-bmp', 'image/bmp', 'application/x-bmp', 'application/bmp', 'image/x-photoshop', 'image/psd', 'image/x-psd', 'image/photoshop', 'image/vnd.adobe.photoshop', 'image/webp', ], MEDIATYPE_DRAWING => [ 'image/svg+xml', 'image/svg+xml', 'application/svg+xml', 'application/svg', 'image/svg', 'application/postscript', 'application/x-latex', 'application/x-tex', 'application/x-dia-diagram', 'application/acad', 'application/x-acad', 'application/autocad_dwg', 'image/x-dwg', 'application/dwg', 'application/x-dwg', 'application/x-autocad', 'image/vnd.dwg', 'drawing/dwg', 'chemical/x-mdl-molfile', 'chemical/x-mdl-sdfile', 'chemical/x-mdl-rxnfile', 'chemical/x-mdl-rdfile', 'chemical/x-mdl-rgfile', ], MEDIATYPE_TEXT => [ 'text/plain', 'text/html', 'text/plain', 'text/html', 'application/xhtml+xml', 'application/xml', 'text/xml', 'text', 'application/json', 'text/csv', 'text/tab-separated-values', ], MEDIATYPE_VIDEO => [ 'video/ogg', 'video/mpeg', 'video/mpeg', 'application/mpeg', 'video/ogg', 'video/x-sgi-video', 'video/x-flv', 'video/webm', 'video/x-matroska', 'video/mp4', ], MEDIATYPE_UNKNOWN => [ 'unknown/unknown', 'application/octet-stream', 'application/x-empty', ], MEDIATYPE_ARCHIVE => [ 'application/zip', 'application/x-zip', 'application/x-gzip', 'application/x-bzip', 'application/x-bzip2', 'application/x-tar', 'application/x-stuffit', 'application/x-opc+zip', 'application/x-7z-compressed', ], MEDIATYPE_3D => [ 'application/sla', 'model/gltf-binary', 'model/gltf+json', ], ]; /** @var array Map of variant MIME types to their canonical MIME type */ public const MIME_TYPE_ALIASES = [ 'text/javascript' => 'application/javascript', 'application/x-javascript' => 'application/javascript', 'audio/mpeg' => 'audio/mp3', 'audio/ogg' => 'application/ogg', 'video/ogg' => 'application/ogg', 'image/x-ms-bmp' => 'image/x-bmp', 'image/bmp' => 'image/x-bmp', 'application/octet-stream' => 'unknown/unknown', 'application/x-empty' => 'unknown/unknown', 'image/x-png' => 'image/png', 'image/pjpeg' => 'image/jpeg', 'image/x-ico' => 'image/x-icon', 'image/vnd.microsoft.icon' => 'image/x-icon', 'image/x-portable-greymap' => 'image/x-portable-graymap', 'application/x-bmp' => 'image/x-bmp', 'application/bmp' => 'image/x-bmp', 'image/psd' => 'image/x-photoshop', 'image/x-psd' => 'image/x-photoshop', 'image/photoshop' => 'image/x-photoshop', 'image/vnd.adobe.photoshop' => 'image/x-photoshop', 'application/svg+xml' => 'image/svg+xml', 'application/svg' => 'image/svg+xml', 'image/svg' => 'image/svg+xml', 'audio/mp3' => 'audio/mpeg', 'audio/mpeg3' => 'audio/mpeg', 'audio/x-wav' => 'audio/wav', 'audio/wave' => 'audio/wav', 'audio/mid' => 'audio/midi', 'application/mpeg' => 'video/mpeg', 'application/x-ogg' => 'application/ogg', 'audio/x-ogg' => 'application/ogg', 'video/x-ogg' => 'application/ogg', 'application/xhtml+xml' => 'text/html', 'text/xml' => 'application/xml', 'application/x-zip' => 'application/zip', 'application/x-ecmascript' => 'application/javascript', 'text/ecmascript' => 'application/javascript', 'application/acrobat' => 'application/pdf', 'image/x.djvu' => 'image/vnd.djvu', 'image/x-djvu' => 'image/vnd.djvu', 'application/x-acad' => 'application/acad', 'application/autocad_dwg' => 'application/acad', 'image/x-dwg' => 'application/acad', 'application/dwg' => 'application/acad', 'application/x-dwg' => 'application/acad', 'application/x-autocad' => 'application/acad', 'image/vnd.dwg' => 'application/acad', 'drawing/dwg' => 'application/acad', 'image/jpeg2000' => 'image/jp2', 'image/jpeg2000-image' => 'image/jp2', 'image/x-jpeg2000-image' => 'image/jp2', 'application/csv' => 'text/csv', 'application/x-csv' => 'text/csv', 'text/x-csv' => 'text/csv', 'text/comma-separated-values' => 'text/csv', 'text/x-comma-separated-values' => 'text/csv', ]; } PK ! � #��� �� mime/MimeAnalyzer.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\Mime; use Psr\Log\LoggerAwareInterface; use Psr\Log\LoggerInterface; use Psr\Log\NullLogger; use UnexpectedValueException; use Wikimedia\AtEase\AtEase; use ZipDirectoryReader; /** * @defgroup Mime Mime * * @ingroup Media */ /** * Detect MIME types of a file by mapping file extensions or parsing file contents. * * @since 1.28 * @ingroup Mime */ class MimeAnalyzer implements LoggerAwareInterface { /** @var string */ protected $typeFile; /** @var string */ protected $infoFile; /** @var string */ protected $xmlTypes; /** @var callable */ protected $initCallback; /** @var callable */ protected $detectCallback; /** @var callable */ protected $guessCallback; /** @var callable */ protected $extCallback; /** @var array Mapping of media types to arrays of MIME types */ protected $mediaTypes = null; /** @var array Map of MIME type aliases */ protected $mimeTypeAliases = null; /** @var array<string,string[]> Map of MIME types to file extensions */ protected $mimeToExts = []; /** @var array<string,string[]> Map of file extensions to MIME types */ protected $extToMimes = []; /** @var array Map of file extensions types to MIME types (as a space separated list) */ public $mExtToMime = []; // legacy name; field accessed by hooks /** @var string Extra MIME types, set for example by media handling extensions */ private $extraTypes = ''; /** @var string Extra MIME info, set for example by media handling extensions */ private $extraInfo = ''; /** @var LoggerInterface */ private $logger; /** @var string Use the full, built-in MIME mapping rather than load from a file */ public const USE_INTERNAL = 'internal'; /** * @param array $params Configuration map, includes: * - typeFile: path to file with the list of known MIME types * - infoFile: path to file with the MIME type info * - xmlTypes: map of root element names to XML MIME types * - initCallback: initialization callback that is passed this object [optional] * - detectCallback: alternative to finfo that returns the mime type for a file. * For example, the callback can return the output of "file -bi". [optional] * - guessCallback: callback to improve the guessed MIME type using the file data. * This is intended for fixing mistakes in fileinfo or "detectCallback". [optional] * - extCallback: callback to improve the guessed MIME type using the extension. [optional] * - logger: PSR-3 logger [optional] * @note Constructing these instances is expensive due to file reads. * A service or singleton pattern should be used to avoid creating instances again and again. */ public function __construct( array $params ) { $this->typeFile = $params['typeFile']; $this->infoFile = $params['infoFile']; $this->xmlTypes = $params['xmlTypes']; $this->initCallback = $params['initCallback'] ?? null; $this->detectCallback = $params['detectCallback'] ?? null; $this->guessCallback = $params['guessCallback'] ?? null; $this->extCallback = $params['extCallback'] ?? null; $this->logger = $params['logger'] ?? new NullLogger(); $this->loadFiles(); } protected function loadFiles(): void { # Allow media handling extensions adding MIME-types and MIME-info if ( $this->initCallback ) { call_user_func( $this->initCallback, $this ); } $rawTypes = $this->extraTypes; if ( $this->typeFile === self::USE_INTERNAL ) { $this->mimeToExts = MimeMap::MIME_EXTENSIONS; } else { $this->mimeToExts = MimeMapMinimal::MIME_EXTENSIONS; if ( $this->typeFile ) { $rawTypes = file_get_contents( $this->typeFile ) . "\n" . $this->extraTypes; } } if ( $rawTypes ) { $this->parseMimeTypes( $rawTypes ); } // Build the reverse mapping (extension => MIME type). foreach ( $this->mimeToExts as $mime => $exts ) { foreach ( $exts as $ext ) { $this->extToMimes[$ext][] = $mime; } } // Migrate items from the legacy $this->mExtToMime field. // TODO: Remove this when mExtToMime is finally removed. foreach ( $this->mExtToMime as $ext => $mimes ) { foreach ( explode( ' ', $mimes ) as $mime ) { $this->extToMimes[$ext][] = $mime; } } $rawInfo = $this->extraInfo; if ( $this->infoFile === self::USE_INTERNAL ) { $this->mimeTypeAliases = MimeMap::MIME_TYPE_ALIASES; $this->mediaTypes = MimeMap::MEDIA_TYPES; } else { $this->mimeTypeAliases = MimeMapMinimal::MIME_TYPE_ALIASES; $this->mediaTypes = MimeMapMinimal::MEDIA_TYPES; if ( $this->infoFile ) { $rawInfo = file_get_contents( $this->infoFile ) . "\n" . $this->extraInfo; } } if ( $rawInfo ) { $this->parseMimeInfo( $rawInfo ); } } protected function parseMimeTypes( string $rawMimeTypes ): void { $rawMimeTypes = str_replace( [ "\r\n", "\n\r", "\n\n", "\r\r", "\r" ], "\n", $rawMimeTypes ); $rawMimeTypes = str_replace( "\t", " ", $rawMimeTypes ); $lines = explode( "\n", $rawMimeTypes ); foreach ( $lines as $s ) { $s = trim( $s ); if ( $s === '' || str_starts_with( $s, '#' ) ) { continue; } $s = strtolower( $s ); $i = strpos( $s, ' ' ); if ( $i === false ) { continue; } $ext = trim( substr( $s, $i + 1 ) ); if ( !$ext ) { continue; } $tokens = preg_split( '/\s+/', $s, -1, PREG_SPLIT_NO_EMPTY ); if ( count( $tokens ) > 1 ) { $mime = array_shift( $tokens ); $this->mimeToExts[$mime] = array_values( array_unique( array_merge( $this->mimeToExts[$mime] ?? [], $tokens ) ) ); } } } protected function parseMimeInfo( string $rawMimeInfo ): void { $rawMimeInfo = str_replace( [ "\r\n", "\n\r", "\n\n", "\r\r", "\r" ], "\n", $rawMimeInfo ); $rawMimeInfo = str_replace( "\t", " ", $rawMimeInfo ); $lines = explode( "\n", $rawMimeInfo ); foreach ( $lines as $s ) { $s = trim( $s ); if ( $s === '' || str_starts_with( $s, '#' ) ) { continue; } $s = strtolower( $s ); $i = strpos( $s, ' ' ); if ( $i === false ) { continue; } # print "processing MIME INFO line $s<br>"; $match = []; if ( preg_match( '!\[\s*(\w+)\s*\]!', $s, $match ) ) { $s = preg_replace( '!\[\s*(\w+)\s*\]!', '', $s ); $mtype = trim( strtoupper( $match[1] ) ); } else { $mtype = MEDIATYPE_UNKNOWN; } $m = preg_split( '/\s+/', $s, -1, PREG_SPLIT_NO_EMPTY ); if ( !isset( $this->mediaTypes[$mtype] ) ) { $this->mediaTypes[$mtype] = []; } foreach ( $m as $mime ) { $mime = trim( $mime ); if ( !$mime ) { continue; } $this->mediaTypes[$mtype][] = $mime; } if ( count( $m ) > 1 ) { $main = $m[0]; $mCount = count( $m ); for ( $i = 1; $i < $mCount; $i += 1 ) { $mime = $m[$i]; $this->mimeTypeAliases[$mime] = $main; } } } } public function setLogger( LoggerInterface $logger ) { $this->logger = $logger; } /** * Adds to the list mapping MIME to file extensions. * * As an extension author, you are encouraged to submit patches to * MediaWiki's core to add new MIME types to MimeMap.php. * * @param string $types */ public function addExtraTypes( string $types ): void { $this->extraTypes .= "\n" . $types; } /** * Adds to the list mapping MIME to media type. * * As an extension author, you are encouraged to submit patches to * MediaWiki's core to add new MIME info to MimeMap.php. * * @param string $info */ public function addExtraInfo( string $info ): void { $this->extraInfo .= "\n" . $info; } /** * Returns a list of file extensions for a given MIME type as a space * separated string or null if the MIME type was unrecognized. Resolves * MIME type aliases. * * @deprecated since 1.35 Use getExtensionsFromMimeType() instead. * @param string $mime * @return string|null */ public function getExtensionsForType( $mime ) { $exts = $this->getExtensionsFromMimeType( $mime ); return $exts ? implode( ' ', $exts ) : null; } /** * Returns an array of file extensions associated with a given MIME type. * The returned array is empty if the MIME type was unrecognized. Resolves * MIME type aliases. * * @since 1.35 * @param string $mime * @return string[] */ public function getExtensionsFromMimeType( string $mime ): array { $mime = strtolower( $mime ); if ( !isset( $this->mimeToExts[$mime] ) && isset( $this->mimeTypeAliases[$mime] ) ) { $mime = $this->mimeTypeAliases[$mime]; } return $this->mimeToExts[$mime] ?? []; } /** * Returns an array of MIME types associated with a given file extension. * The returned array is empty if the file extension is not associated with * any MIME types. * * @since 1.35 * @param string $ext * @return string[] */ public function getMimeTypesFromExtension( string $ext ): array { $ext = strtolower( $ext ); return $this->extToMimes[$ext] ?? []; } /** * Returns a single MIME type for a given file extension or null if unknown. * This is always the first type from the list returned by getMimeTypesFromExtension($ext). * * @since 1.35 * @param string $ext * @return string|null */ public function getMimeTypeFromExtensionOrNull( string $ext ): ?string { $types = $this->getMimeTypesFromExtension( $ext ); return $types[0] ?? null; } /** * Returns a single file extension for a given MIME type or null if unknown. * This is always the first type from the list returned by getExtensionsFromMimeType($mime). * * @deprecated since 1.35 Use getMimeTypeFromExtensionOrNull() instead. * @param string $ext * @return string|null */ public function guessTypesForExtension( $ext ) { return $this->getMimeTypeFromExtensionOrNull( $ext ); } /** * Returns a list of MIME types for a given file extension as a space * separated string or null if the extension was unrecognized. * * @deprecated since 1.35 Use getMimeTypesFromExtension() instead. * @param string $ext * @return string|null */ public function getTypesForExtension( $ext ) { $types = $this->getMimeTypesFromExtension( $ext ); return $types ? implode( ' ', $types ) : null; } /** * Returns a single file extension for a given MIME type or null if unknown. * This is always the first type from the list returned by getExtensionsFromMimeType($mime). * * @since 1.35 * @param string $mime * @return string|null */ public function getExtensionFromMimeTypeOrNull( string $mime ): ?string { $exts = $this->getExtensionsFromMimeType( $mime ); return $exts[0] ?? null; } /** * Tests if the extension matches the given MIME type. Returns true if a * match was found, null if the MIME type is unknown, and false if the * MIME type is known but no matches where found. * * @param string $extension * @param string $mime * @return bool|null */ public function isMatchingExtension( string $extension, string $mime ): ?bool { $exts = $this->getExtensionsFromMimeType( $mime ); if ( !$exts ) { return null; // Unknown MIME type } return in_array( strtolower( $extension ), $exts ); } /** * Returns true if the MIME type is known to represent an image format * supported by the PHP GD library. * * @deprecated since 1.40 * @param string $mime * @return bool */ public function isPHPImageType( string $mime ): bool { wfDeprecated( __METHOD__, '1.40' ); // As defined by imagegetsize and image_type_to_mime static $types = [ 'image/gif', 'image/jpeg', 'image/png', 'image/x-bmp', 'image/xbm', 'image/tiff', 'image/jp2', 'image/jpeg2000', 'image/iff', 'image/xbm', 'image/x-xbitmap', 'image/vnd.wap.wbmp', 'image/vnd.xiff', 'image/x-photoshop', 'application/x-shockwave-flash', ]; return in_array( $mime, $types ); } /** * Returns true if the extension represents a type which can * be reliably detected from its content. Use this to determine * whether strict content checks should be applied to reject * invalid uploads; if we can't identify the type we won't * be able to say if it's invalid. * * @todo Be more accurate when using fancy MIME detector plugins; * right now this is the bare minimum getimagesize() list. * @param string $extension * @return bool */ public function isRecognizableExtension( string $extension ): bool { static $types = [ // Types recognized by getimagesize() 'gif', 'jpeg', 'jpg', 'png', 'swf', 'psd', 'bmp', 'tiff', 'tif', 'jpc', 'jp2', 'jpx', 'jb2', 'swc', 'iff', 'wbmp', 'xbm', // Formats we recognize magic numbers for 'djvu', 'ogx', 'ogg', 'ogv', 'oga', 'spx', 'opus', 'mid', 'pdf', 'wmf', 'xcf', 'webm', 'mkv', 'mka', 'webp', 'mp3', // XML formats we sure hope we recognize reliably 'svg', // 3D formats 'stl', 'glb', ]; return in_array( strtolower( $extension ), $types ); } /** * Improves a MIME type using the file extension. Some file formats are very generic, * so their MIME type is not very meaningful. A more useful MIME type can be derived * by looking at the file extension. Typically, this method would be called on the * result of guessMimeType(). * * XXX: Null-returning behavior is probably an accident and definitely confusing (T253483). * * @param string $mime The MIME type, typically guessed from a file's content. * @param string $ext The file extension, as taken from the file name * @return string|null The improved MIME type, or null if the MIME type is * unknown/unknown and the extension is not recognized. */ public function improveTypeFromExtension( string $mime, string $ext ): ?string { if ( $mime === 'unknown/unknown' ) { if ( $this->isRecognizableExtension( $ext ) ) { $this->logger->info( __METHOD__ . ': refusing to guess mime type for .' . "$ext file, we should have recognized it" ); } else { // Not something we can detect, so simply // trust the file extension $mime = $this->getMimeTypeFromExtensionOrNull( $ext ); } } elseif ( $mime === 'application/x-opc+zip' || $mime === 'application/vnd.oasis.opendocument' ) { if ( $this->isMatchingExtension( $ext, $mime ) ) { // A known file extension for an OPC/ODF file, // find the proper MIME type for that file extension $mime = $this->getMimeTypeFromExtensionOrNull( $ext ); } else { $this->logger->info( __METHOD__ . ": refusing to guess better type for $mime file, " . ".$ext is not a known OPC/ODF extension." ); $mime = 'application/zip'; } } elseif ( $mime === 'text/plain' && $this->findMediaType( ".$ext" ) === MEDIATYPE_TEXT ) { // Textual types are sometimes not recognized properly. // If detected as text/plain, and has an extension which is textual // improve to the extension's type. For example, csv and json are often // misdetected as text/plain. $mime = $this->getMimeTypeFromExtensionOrNull( $ext ); } # Media handling extensions can improve the MIME detected $callback = $this->extCallback; if ( $callback ) { $callback( $this, $ext, $mime /* by reference */ ); } if ( $mime !== null && isset( $this->mimeTypeAliases[$mime] ) ) { $mime = $this->mimeTypeAliases[$mime]; } $this->logger->info( __METHOD__ . ": improved mime type for .$ext: $mime" ); return $mime; } /** * MIME type detection. This uses detectMimeType to detect the MIME type * of the file, but applies additional checks to determine some well known * file formats that may be missed or misinterpreted by the default MIME * detection (namely XML based formats like XHTML or SVG, as well as ZIP * based formats like OPC/ODF files). * * @param string $file The file to check * @param string|bool $ext The file extension, or true (default) to extract * it from the filename. Set it to false to ignore the extension. DEPRECATED! * Set to false, use improveTypeFromExtension($mime, $ext) later to improve MIME type. * @return string The MIME type of $file */ public function guessMimeType( string $file, $ext = true ): string { if ( $ext ) { // TODO: make $ext default to false. Or better, remove it. $this->logger->info( __METHOD__ . ": WARNING: use of the \$ext parameter is deprecated. " . "Use improveTypeFromExtension(\$mime, \$ext) instead." ); } $mime = $this->doGuessMimeType( $file ); if ( !$mime ) { $this->logger->info( __METHOD__ . ": internal type detection failed for $file (.$ext)..." ); $mime = $this->detectMimeType( $file, $ext ); } if ( isset( $this->mimeTypeAliases[$mime] ) ) { $mime = $this->mimeTypeAliases[$mime]; } $this->logger->info( __METHOD__ . ": guessed mime type of $file: $mime" ); return $mime; } /** * Guess the MIME type from the file contents. * * @param string $file * @return bool|string * @throws UnexpectedValueException */ private function doGuessMimeType( string $file ) { // Read a chunk of the file AtEase::suppressWarnings(); $f = fopen( $file, 'rb' ); AtEase::restoreWarnings(); if ( !$f ) { return 'unknown/unknown'; } $fsize = filesize( $file ); if ( $fsize === false ) { return 'unknown/unknown'; } $head = fread( $f, 1024 ); $head16k = $head . fread( $f, 16384 - 1024 ); // some WebM files have big headers $tailLength = min( 65558, $fsize ); // 65558 = maximum size of a zip EOCDR if ( fseek( $f, -1 * $tailLength, SEEK_END ) === -1 ) { throw new UnexpectedValueException( "Seeking $tailLength bytes from EOF failed in " . __METHOD__ ); } $tail = $tailLength ? fread( $f, $tailLength ) : ''; $this->logger->info( __METHOD__ . ": analyzing head and tail of $file for magic numbers." ); // Hardcode a few magic number checks... $headers = [ // Multimedia... 'MThd' => 'audio/midi', 'OggS' => 'application/ogg', 'ID3' => 'audio/mpeg', "\xff\xfb" => 'audio/mpeg', // MPEG-1 layer 3 "\xff\xf3" => 'audio/mpeg', // MPEG-2 layer 3 (lower sample rates) "\xff\xe3" => 'audio/mpeg', // MPEG-2.5 layer 3 (very low sample rates) // Image formats... // Note that WMF may have a bare header, no magic number. "\x01\x00\x09\x00" => 'application/x-msmetafile', // Possibly prone to false positives? "\xd7\xcd\xc6\x9a" => 'application/x-msmetafile', '%PDF' => 'application/pdf', 'gimp xcf' => 'image/x-xcf', // 3D "glTF" => 'model/gltf-binary', // Some forbidden fruit... 'MZ' => 'application/octet-stream', // DOS/Windows executable "\xca\xfe\xba\xbe" => 'application/octet-stream', // Mach-O binary "\x7fELF" => 'application/octet-stream', // ELF binary ]; foreach ( $headers as $magic => $candidate ) { if ( str_starts_with( $head, $magic ) ) { $this->logger->info( __METHOD__ . ": magic header in $file recognized as $candidate" ); return $candidate; } } /* Look for WebM and Matroska files */ if ( str_starts_with( $head16k, pack( "C4", 0x1a, 0x45, 0xdf, 0xa3 ) ) ) { $doctype = strpos( $head16k, "\x42\x82" ); if ( $doctype ) { // Next byte is datasize, then data (sizes larger than 1 byte are stupid muxers) $data = substr( $head16k, $doctype + 3, 8 ); if ( str_starts_with( $data, "matroska" ) ) { $this->logger->info( __METHOD__ . ": recognized file as video/x-matroska" ); return "video/x-matroska"; } if ( str_starts_with( $data, "webm" ) ) { // XXX HACK look for a video track, if we don't find it, this is an audio file // This detection is very naive and doesn't parse the actual fields // 0x86 byte indicates start of codecname field // next byte is a variable length integer (vint) for the size of the value following it // 8 (first bit is 1) indicates the smallest size vint, a single byte // (unlikely we see larger vints here) // 5 indicates a length of 5 ( V_VP8 or V_VP9 or V_AV1 ) // Sometimes we see 0x86 instead of 0x85 because a // non-conforming muxer wrote a null terminated string $videotrack = str_contains( $head16k, "\x86\x85V_VP8" ) || str_contains( $head16k, "\x86\x85V_VP9" ) || str_contains( $head16k, "\x86\x85V_AV1" ) || str_contains( $head16k, "\x86\x86V_VP8\x0" ) || str_contains( $head16k, "\x86\x86V_VP9\x0" ) || str_contains( $head16k, "\x86\x86V_AV1\x0" ); if ( $videotrack ) { // There is a video track, so this is a video file. $this->logger->info( __METHOD__ . ": recognized file as video/webm" ); return "video/webm"; } $this->logger->info( __METHOD__ . ": recognized file as audio/webm" ); return "audio/webm"; } } $this->logger->info( __METHOD__ . ": unknown EBML file" ); return "unknown/unknown"; } /* Look for WebP */ if ( str_starts_with( $head, "RIFF" ) && substr( $head, 8, 7 ) === "WEBPVP8" ) { $this->logger->info( __METHOD__ . ": recognized file as image/webp" ); return "image/webp"; } /* Look for JPEG2000 */ if ( str_starts_with( $head, "\x00\x00\x00\x0cjP\x20\x20\x0d\x0a\x87\x0a" ) ) { $this->logger->info( __METHOD__ . ": recognized as JPEG2000" ); // we skip 4 bytes if ( substr( $head, 16, 8 ) === "ftypjp2 " ) { $this->logger->info( __METHOD__ . ": recognized file as image/jp2" ); return 'image/jp2'; } elseif ( substr( $head, 16, 8 ) === "ftypjpx " ) { $this->logger->info( __METHOD__ . ": recognized file as image/jpx" ); return 'image/jpx'; } } /* Look for MS Compound Binary (OLE) files */ if ( str_starts_with( $head, "\xd0\xcf\x11\xe0\xa1\xb1\x1a\xe1" ) ) { $this->logger->info( __METHOD__ . ': recognized MS CFB (OLE) file' ); return $this->detectMicrosoftBinaryType( $f ); } /** * Look for PHP. Check for this before HTML/XML... Warning: this is a * heuristic, and won't match a file with a lot of non-PHP before. It * will also match text files which could be PHP. :) * * @todo FIXME: For this reason, the check is probably useless -- an attacker * could almost certainly just pad the file with a lot of nonsense to * circumvent the check in any case where it would be a security * problem. On the other hand, it causes harmful false positives (bug * 16583). The heuristic has been cut down to exclude three-character * strings like "<? ", but should it be axed completely? */ if ( ( strpos( $head, '<?php' ) !== false ) || ( strpos( $head, "<\x00?\x00p\x00h\x00p" ) !== false ) || ( strpos( $head, "<\x00?\x00 " ) !== false ) || ( strpos( $head, "<\x00?\x00\n" ) !== false ) || ( strpos( $head, "<\x00?\x00\t" ) !== false ) || ( strpos( $head, "<\x00?\x00=" ) !== false ) ) { $this->logger->info( __METHOD__ . ": recognized $file as application/x-php" ); return 'application/x-php'; } /** * look for XML formats (XHTML and SVG) */ AtEase::suppressWarnings(); $xml = new XmlTypeCheck( $file ); AtEase::restoreWarnings(); if ( $xml->wellFormed ) { $xmlTypes = $this->xmlTypes; // @phan-suppress-next-line PhanTypeMismatchDimFetch False positive return $xmlTypes[$xml->getRootElement()] ?? 'application/xml'; } /** * look for shell scripts */ $script_type = null; # detect by shebang if ( str_starts_with( $head, "#!" ) ) { $script_type = "ASCII"; } elseif ( str_starts_with( $head, "\xef\xbb\xbf#!" ) ) { $script_type = "UTF-8"; } elseif ( str_starts_with( $head, "\xfe\xff\x00#\x00!" ) ) { $script_type = "UTF-16BE"; } elseif ( str_starts_with( $head, "\xff\xfe#\x00!" ) ) { $script_type = "UTF-16LE"; } if ( $script_type ) { if ( $script_type !== "UTF-8" && $script_type !== "ASCII" ) { // Quick and dirty fold down to ASCII! $pack = [ 'UTF-16BE' => 'n*', 'UTF-16LE' => 'v*' ]; $chars = unpack( $pack[$script_type], substr( $head, 2 ) ); $head = ''; foreach ( $chars as $codepoint ) { if ( $codepoint < 128 ) { $head .= chr( $codepoint ); } else { $head .= '?'; } } } $match = []; if ( preg_match( '%/?([^\s]+/)(\w+)%', $head, $match ) ) { $mime = "application/x-{$match[2]}"; $this->logger->info( __METHOD__ . ": shell script recognized as $mime" ); return $mime; } } // Check for ZIP variants (before getimagesize) $eocdrPos = strpos( $tail, "PK\x05\x06" ); if ( $eocdrPos !== false && $eocdrPos <= strlen( $tail ) - 22 ) { $this->logger->info( __METHOD__ . ": ZIP signature present in $file" ); // Check if it really is a ZIP file, make sure the EOCDR is at the end (T40432) $commentLength = unpack( "n", substr( $tail, $eocdrPos + 20 ) )[1]; if ( $eocdrPos + 22 + $commentLength !== strlen( $tail ) ) { $this->logger->info( __METHOD__ . ": ZIP EOCDR not at end. Not a ZIP file." ); } else { return $this->detectZipTypeFromFile( $f ); } } // Check for STL (3D) files // @see https://en.wikipedia.org/wiki/STL_(file_format) if ( $fsize >= 15 && stripos( $head, 'SOLID ' ) === 0 && preg_match( '/\RENDSOLID .*$/i', $tail ) ) { // ASCII STL file return 'application/sla'; } elseif ( $fsize > 84 ) { // binary STL file $triangles = substr( $head, 80, 4 ); $triangles = unpack( 'V', $triangles ); $triangles = reset( $triangles ); if ( $triangles !== false && $fsize === 84 + ( $triangles * 50 ) ) { return 'application/sla'; } } AtEase::suppressWarnings(); $gis = getimagesize( $file ); AtEase::restoreWarnings(); if ( $gis && isset( $gis['mime'] ) ) { $mime = $gis['mime']; $this->logger->info( __METHOD__ . ": getimagesize detected $file as $mime" ); return $mime; } # Media handling extensions can guess the MIME by content # It's intentionally here so that if core is wrong about a type (false positive), # people will hopefully nag and submit patches :) $mime = false; # Some strings by reference for performance - assuming well-behaved hooks $callback = $this->guessCallback; if ( $callback ) { $callback( $this, $head, $tail, $file, $mime /* by reference */ ); } return $mime; } /** * Detect application-specific file type of a given ZIP file. * If it can't tell, return 'application/zip'. * * @internal * @param resource $handle * @return string */ public function detectZipTypeFromFile( $handle ) { $types = []; $status = ZipDirectoryReader::readHandle( $handle, static function ( $entry ) use ( &$types ) { $name = $entry['name']; $names = [ $name ]; // If there is a null character, cut off the name at it, because JDK's // ZIP_GetEntry() uses strcmp() if the name hashes match. If a file name // were constructed which had ".class\0" followed by a string chosen to // make the hash collide with the truncated name, that file could be // returned in response to a request for the .class file. $nullPos = strpos( $entry['name'], "\000" ); if ( $nullPos !== false ) { $names[] = substr( $entry['name'], 0, $nullPos ); } // If there is a trailing slash in the file name, we have to strip it, // because that's what ZIP_GetEntry() does. if ( preg_grep( '!\.class/?$!', $names ) ) { $types[] = 'application/java'; } if ( $name === '[Content_Types].xml' ) { $types[] = 'application/x-opc+zip'; } elseif ( $name === 'mimetype' ) { $types[] = 'application/vnd.oasis.opendocument'; } } ); if ( !$status->isOK() ) { $this->logger->info( "Error reading zip file: " . (string)$status ); // This could be unknown/unknown but we have some weird phpunit test cases return 'application/zip'; } if ( in_array( 'application/java', $types ) ) { // For security, java detection takes precedence return 'application/java'; } elseif ( count( $types ) ) { return $types[0]; } else { return 'application/zip'; } } /** * Detect the type of a Microsoft Compound Binary a.k.a. OLE file. * These are old style pre-ODF files such as .doc and .xls * * @param resource $handle An opened seekable file handle * @return string The detected MIME type */ private function detectMicrosoftBinaryType( $handle ): string { $info = MSCompoundFileReader::readHandle( $handle ); if ( !$info['valid'] ) { $this->logger->info( __METHOD__ . ': invalid file format' ); return 'unknown/unknown'; } if ( !$info['mime'] ) { $this->logger->info( __METHOD__ . ": unrecognised document subtype" ); return 'unknown/unknown'; } return $info['mime']; } /** * Internal MIME type detection. Detection is done using the fileinfo * extension if it is available. It can be overridden by callback, which could * use an external program, for example. If detection fails and $ext is not false, * the MIME type is guessed from the file extension, using getMimeTypeFromExtensionOrNull. * * If the MIME type is still unknown, getimagesize is used to detect the * MIME type if the file is an image. If no MIME type can be determined, * this function returns 'unknown/unknown'. * * @param string $file The file to check * @param string|bool $ext The file extension, or true (default) to extract it from the filename. * Set it to false to ignore the extension. DEPRECATED! Set to false, use * improveTypeFromExtension($mime, $ext) later to improve MIME type. * @return string The MIME type of $file */ private function detectMimeType( string $file, $ext = true ): string { /** @todo Make $ext default to false. Or better, remove it. */ if ( $ext ) { $this->logger->info( __METHOD__ . ": WARNING: use of the \$ext parameter is deprecated. " . "Use improveTypeFromExtension(\$mime, \$ext) instead." ); } $callback = $this->detectCallback; if ( $callback ) { $m = $callback( $file ); } else { $m = mime_content_type( $file ); } if ( $m ) { # normalize $m = preg_replace( '![;, ].*$!', '', $m ); # strip charset, etc $m = trim( $m ); $m = strtolower( $m ); if ( !str_contains( $m, 'unknown' ) ) { $this->logger->info( __METHOD__ . ": magic mime type of $file: $m" ); return $m; } } // If desired, look at extension as a fallback. if ( $ext === true ) { $i = strrpos( $file, '.' ); $ext = strtolower( $i ? substr( $file, $i + 1 ) : '' ); } if ( $ext ) { if ( $this->isRecognizableExtension( $ext ) ) { $this->logger->info( __METHOD__ . ": refusing to guess mime type for .$ext file, " . "we should have recognized it" ); } else { $m = $this->getMimeTypeFromExtensionOrNull( $ext ); if ( $m ) { $this->logger->info( __METHOD__ . ": extension mime type of $file: $m" ); return $m; } } } // Unknown type $this->logger->info( __METHOD__ . ": failed to guess mime type for $file!" ); return 'unknown/unknown'; } /** * Determine the media type code for a file, using its MIME type, name and * possibly its contents. * * This function relies on the findMediaType(), mapping extensions and MIME * types to media types. * * @todo analyse file if need be * @todo look at multiple extension, separately and together. * * @param string|null $path Full path to the image file, in case we have to look at the contents * (if null, only the MIME type is used to determine the media type code). * @param string|null $mime MIME type. If null it will be guessed using guessMimeType. * @return string A value to be used with the MEDIATYPE_xxx constants. */ public function getMediaType( ?string $path = null, ?string $mime = null ): string { if ( !$mime && !$path ) { return MEDIATYPE_UNKNOWN; } // If MIME type is unknown, guess it if ( !$mime ) { // @phan-suppress-next-line PhanTypeMismatchArgumentNullable False positive $mime = $this->guessMimeType( $path, false ); } // Special code for ogg - detect if it's video (theora), // else label it as sound. if ( $mime == 'application/ogg' && is_string( $path ) && file_exists( $path ) ) { // Read a chunk of the file $f = fopen( $path, "rt" ); if ( !$f ) { return MEDIATYPE_UNKNOWN; } $head = fread( $f, 256 ); fclose( $f ); $head = str_replace( 'ffmpeg2theora', '', strtolower( $head ) ); // This is an UGLY HACK, file should be parsed correctly if ( strpos( $head, 'theora' ) !== false ) { return MEDIATYPE_VIDEO; } elseif ( strpos( $head, 'vorbis' ) !== false ) { return MEDIATYPE_AUDIO; } elseif ( strpos( $head, 'flac' ) !== false ) { return MEDIATYPE_AUDIO; } elseif ( strpos( $head, 'speex' ) !== false ) { return MEDIATYPE_AUDIO; } elseif ( strpos( $head, 'opus' ) !== false ) { return MEDIATYPE_AUDIO; } else { return MEDIATYPE_MULTIMEDIA; } } $type = null; // Check for entry for full MIME type if ( $mime ) { $type = $this->findMediaType( $mime ); if ( $type !== MEDIATYPE_UNKNOWN ) { return $type; } } // Check for entry for file extension if ( $path ) { $i = strrpos( $path, '.' ); $e = strtolower( $i ? substr( $path, $i + 1 ) : '' ); // TODO: look at multi-extension if this fails, parse from full path $type = $this->findMediaType( '.' . $e ); if ( $type !== MEDIATYPE_UNKNOWN ) { return $type; } } // Check major MIME type if ( $mime ) { $i = strpos( $mime, '/' ); if ( $i !== false ) { $major = substr( $mime, 0, $i ); $type = $this->findMediaType( $major ); if ( $type !== MEDIATYPE_UNKNOWN ) { return $type; } } } if ( !$type ) { $type = MEDIATYPE_UNKNOWN; } return $type; } /** * Returns a media code matching the given MIME type or file extension. * * File extensions are represented by a string starting with a dot (.) to * distinguish them from MIME types. * * @param string $extMime * @return int|string */ private function findMediaType( string $extMime ) { if ( strpos( $extMime, '.' ) === 0 ) { // If it's an extension, look up the MIME types $m = $this->getMimeTypesFromExtension( substr( $extMime, 1 ) ); if ( !$m ) { return MEDIATYPE_UNKNOWN; } } else { // Normalize MIME type if ( isset( $this->mimeTypeAliases[$extMime] ) ) { $extMime = $this->mimeTypeAliases[$extMime]; } $m = [ $extMime ]; } foreach ( $m as $mime ) { foreach ( $this->mediaTypes as $type => $codes ) { if ( in_array( $mime, $codes, true ) ) { return $type; } } } return MEDIATYPE_UNKNOWN; } /** * Returns an array of media types (MEDIATYPE_xxx constants) * * @return string[] */ public function getMediaTypes(): array { return array_keys( $this->mediaTypes ); } /** * Check if major_mime has a value accepted by enum in a database schema. * * @since 1.42.0 (also backported to 1.39.7, 1.40.3 and 1.41.1) * * @param string $type * @return bool */ public function isValidMajorMimeType( string $type ): bool { // From maintenance/tables-generated.sql => img_major_mime $types = [ 'unknown', 'application', 'audio', 'image', 'text', 'video', 'message', 'model', 'multipart', 'chemical', ]; return in_array( $type, $types ); } } /** @deprecated class alias since 1.43 */ class_alias( MimeAnalyzer::class, 'MimeAnalyzer' ); PK ! `7>�(B (B StatusValue.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ use Wikimedia\Assert\Assert; use Wikimedia\Message\MessageParam; use Wikimedia\Message\MessageSpecifier; use Wikimedia\Message\MessageValue; /** * Generic operation result class * Has warning/error list, boolean status and arbitrary value * * "Good" means the operation was completed with no warnings or errors. * * "OK" means the operation was partially or wholly completed. * * An operation which is not OK should have errors so that the user can be * informed as to what went wrong. Calling the fatal() function sets an error * message and simultaneously switches off the OK flag. * * The recommended pattern for functions returning StatusValue objects is * to return a StatusValue unconditionally, both on success and on failure * (similarly to Option, Maybe, Promise etc. objects in other languages) -- * so that the developer of the calling code is reminded that the function * can fail, and so that a lack of error-handling will be explicit. * * This class accepts any MessageSpecifier objects. The use of Message objects * should be avoided when serializability is needed. Use MessageValue in that * case instead. * * @newable * @stable to extend * @since 1.25 */ class StatusValue implements Stringable { /** * @var bool * @internal Only for use by Status. Use {@link self::isOK()} or {@link self::setOK()}. */ protected $ok = true; /** * @var array[] * @internal Only for use by Status. Use {@link self::getErrors()} (get full list), * {@link self::splitByErrorType()} (get errors/warnings), or * {@link self::fatal()}, {@link self::error()} or {@link self::warning()} (add error/warning). */ protected $errors = []; /** @var mixed */ public $value; /** @var bool[] Map of (key => bool) to indicate success of each part of batch operations */ public $success = []; /** @var int Counter for batch operations */ public $successCount = 0; /** @var int Counter for batch operations */ public $failCount = 0; /** @var mixed arbitrary extra data about the operation */ public $statusData; /** * Factory function for fatal errors * * @param string|MessageSpecifier $message Message key or object * @param mixed ...$parameters * @return static */ public static function newFatal( $message, ...$parameters ) { $result = new static(); $result->fatal( $message, ...$parameters ); return $result; } /** * Factory function for good results * * @param mixed|null $value * @return static */ public static function newGood( $value = null ) { $result = new static(); $result->value = $value; return $result; } /** * Splits this StatusValue object into two new StatusValue objects, one which contains only * the error messages, and one that contains the warnings, only. The returned array is * defined as: * [ * 0 => object(StatusValue) # the StatusValue with error messages, only * 1 => object(StatusValue) # The StatusValue with warning messages, only * ] * * @return static[] */ public function splitByErrorType() { $errorsOnlyStatusValue = static::newGood(); $warningsOnlyStatusValue = static::newGood(); $warningsOnlyStatusValue->setResult( true, $this->getValue() ); $errorsOnlyStatusValue->setResult( $this->isOK(), $this->getValue() ); foreach ( $this->errors as $item ) { if ( $item['type'] === 'warning' ) { $warningsOnlyStatusValue->errors[] = $item; } else { $errorsOnlyStatusValue->errors[] = $item; } } return [ $errorsOnlyStatusValue, $warningsOnlyStatusValue ]; } /** * Returns whether the operation completed and didn't have any error or * warnings * * @return bool */ public function isGood() { return $this->ok && !$this->errors; } /** * Returns whether the operation completed * * @return bool */ public function isOK() { return $this->ok; } /** * @return mixed */ public function getValue() { return $this->value; } /** * Get the list of errors * * Each error is a (message:string or MessageSpecifier,params:array) map * * @deprecated since 1.43 Use `->getMessages()` instead * @return array[] * @phan-return array{type:'warning'|'error', message:string|MessageSpecifier, params:array}[] */ public function getErrors() { return $this->errors; } /** * Change operation status * * @param bool $ok * @return $this */ public function setOK( $ok ) { $this->ok = $ok; return $this; } /** * Change operation result * * @param bool $ok Whether the operation completed * @param mixed|null $value * @return $this */ public function setResult( $ok, $value = null ) { $this->ok = (bool)$ok; $this->value = $value; return $this; } /** * Add a new error to the error array ($this->errors) if that error is not already in the * error array. Each error is passed as an array with the following fields: * * - type: 'error' or 'warning' * - message: a string (message key) or MessageSpecifier * - params: an array of string parameters * * If the new error is of type 'error' and it matches an existing error of type 'warning', * the existing error is upgraded to type 'error'. An error provided as a MessageSpecifier * will successfully match an error provided as the same string message key and array of * parameters as separate array elements. * * @param array $newError * @phan-param array{type:'warning'|'error', message:string|MessageSpecifier, params:array} $newError * @return $this */ private function addError( array $newError ) { [ 'type' => $newType, 'message' => $newKey, 'params' => $newParams ] = $newError; if ( $newKey instanceof MessageSpecifier ) { if ( $newParams ) { // Deprecate code like `Status::newFatal( wfMessage( 'foo' ), 'param' )` // - the parameters have always been ignored, so this is usually a mistake. wfDeprecatedMsg( 'Combining MessageSpecifier and parameters array' . ' was deprecated in MediaWiki 1.43', '1.43' ); } $newParams = $newKey->getParams(); $newKey = $newKey->getKey(); } foreach ( $this->errors as [ 'type' => &$type, 'message' => $key, 'params' => $params ] ) { if ( $key instanceof MessageSpecifier ) { $params = $key->getParams(); $key = $key->getKey(); } // This uses loose equality as we must support equality between MessageParam objects // (e.g. ScalarParam), including when they are created separate and not by-ref equal. if ( $newKey === $key && $newParams == $params ) { if ( $type === 'warning' && $newType === 'error' ) { $type = 'error'; } return $this; } } $this->errors[] = $newError; return $this; } /** * Add a new warning * * @param string|MessageSpecifier $message Message key or object * @param mixed ...$parameters * @return $this */ public function warning( $message, ...$parameters ) { return $this->addError( [ 'type' => 'warning', 'message' => $message, 'params' => $parameters ] ); } /** * Add an error, do not set fatal flag * This can be used for non-fatal errors * * @param string|MessageSpecifier $message Message key or object * @param mixed ...$parameters * @return $this */ public function error( $message, ...$parameters ) { return $this->addError( [ 'type' => 'error', 'message' => $message, 'params' => $parameters ] ); } /** * Add an error and set OK to false, indicating that the operation * as a whole was fatal * * @param string|MessageSpecifier $message Message key or object * @param mixed ...$parameters * @return $this */ public function fatal( $message, ...$parameters ) { $this->ok = false; return $this->error( $message, ...$parameters ); } /** * Merge another status object into this one * * @param StatusValue $other * @param bool $overwriteValue Whether to override the "value" member * @return $this */ public function merge( $other, $overwriteValue = false ) { if ( $this->statusData !== null && $other->statusData !== null ) { throw new RuntimeException( "Status cannot be merged, because they both have \$statusData" ); } else { $this->statusData ??= $other->statusData; } foreach ( $other->errors as $error ) { $this->addError( $error ); } $this->ok = $this->ok && $other->ok; if ( $overwriteValue ) { $this->value = $other->value; } $this->successCount += $other->successCount; $this->failCount += $other->failCount; return $this; } /** * Returns a list of status messages of the given type * * Each entry is a map of: * - message: string message key or MessageSpecifier * - params: array list of parameters * * @deprecated since 1.43 Use `->getMessages( $type )` instead * @param string $type * @return array[] * @phan-return array{type:'warning'|'error', message:string|MessageSpecifier, params:array}[] */ public function getErrorsByType( $type ) { $result = []; foreach ( $this->errors as $error ) { if ( $error['type'] === $type ) { $result[] = $error; } } return $result; } /** * Returns a list of error messages, optionally only those of the given type * * If the `warning()` or `error()` method was called with a MessageSpecifier object, * this method is guaranteed to return the same object. * * @since 1.43 * @param ?string $type If provided, only return messages of the type 'warning' or 'error' * @phan-param null|'warning'|'error' $type * @return MessageSpecifier[] */ public function getMessages( ?string $type = null ): array { Assert::parameter( $type === null || $type === 'warning' || $type === 'error', '$type', "must be null, 'warning', or 'error'" ); $result = []; foreach ( $this->errors as $error ) { if ( $type === null || $error['type'] === $type ) { [ 'message' => $key, 'params' => $params ] = $error; if ( $key instanceof MessageSpecifier ) { $result[] = $key; } else { $result[] = new MessageValue( $key, $params ); } } } return $result; } /** * Returns true if the specified message is present as a warning or error. * Any message using the same key will be found (ignoring the message parameters). * * @param string $message Message key to search for * (this parameter used to allow MessageSpecifier too, deprecated since 1.43) * @return bool */ public function hasMessage( $message ) { if ( $message instanceof MessageSpecifier ) { wfDeprecatedMsg( 'Passing MessageSpecifier to hasMessage()' . ' was deprecated in MediaWiki 1.43', '1.43' ); $message = $message->getKey(); } foreach ( $this->errors as [ 'message' => $key ] ) { if ( ( $key instanceof MessageSpecifier && $key->getKey() === $message ) || $key === $message ) { return true; } } return false; } /** * Returns true if any other message than the specified ones is present as a warning or error. * Any messages using the same keys will be found (ignoring the message parameters). * * @param string ...$messages Message keys to search for * (this parameter used to allow MessageSpecifier too, deprecated since 1.43) * @return bool */ public function hasMessagesExcept( ...$messages ) { $exceptedKeys = []; foreach ( $messages as $message ) { if ( $message instanceof MessageSpecifier ) { wfDeprecatedMsg( 'Passing MessageSpecifier to hasMessagesExcept()' . ' was deprecated in MediaWiki 1.43', '1.43' ); $message = $message->getKey(); } $exceptedKeys[] = $message; } foreach ( $this->errors as [ 'message' => $key ] ) { if ( $key instanceof MessageSpecifier ) { $key = $key->getKey(); } if ( !in_array( $key, $exceptedKeys, true ) ) { return true; } } return false; } /** * If the specified source message exists, replace it with the specified * destination message, but keep the same parameters as in the original error. * * When using a string as the `$source` parameter, any message using the same key will be replaced * (regardless of whether it was stored as string or as MessageSpecifier, and ignoring the * message parameters). * * When using a MessageSpecifier as the `$source` parameter, the message will only be replaced * when the same MessageSpecifier object was stored in the StatusValue (compared with `===`). * Since the only reliable way to obtain one is to use getErrors(), which is deprecated, * passing a MessageSpecifier is deprecated (since 1.43). * * @param string $source Message key to search for * (this parameter used to allow MessageSpecifier too, deprecated since 1.43) * @param MessageSpecifier|string $dest Replacement message key or object * @return bool Return true if the replacement was done, false otherwise. */ public function replaceMessage( $source, $dest ) { $replaced = false; if ( $source instanceof MessageSpecifier ) { wfDeprecatedMsg( 'Passing MessageSpecifier as $source to replaceMessage()' . ' was deprecated in MediaWiki 1.43', '1.43' ); } foreach ( $this->errors as [ 'message' => &$message, 'params' => &$params ] ) { if ( $message === $source || ( $message instanceof MessageSpecifier && $message->getKey() === $source ) ) { $message = $dest; if ( $dest instanceof MessageSpecifier ) { // 'params' will be ignored now, so remove them from the internal array $params = []; } $replaced = true; } } return $replaced; } /** * Returns a string representation of the status for debugging. * This is fairly verbose and may change without notice. * * @return string */ public function __toString() { $status = $this->isOK() ? "OK" : "Error"; if ( count( $this->errors ) ) { $errorcount = "collected " . ( count( $this->errors ) ) . " message(s) on the way"; } else { $errorcount = "no errors detected"; } if ( isset( $this->value ) ) { $valstr = get_debug_type( $this->value ) . " value set"; } else { $valstr = "no value set"; } $out = sprintf( "<%s, %s, %s>", $status, $errorcount, $valstr ); if ( count( $this->errors ) > 0 ) { $hdr = sprintf( "+-%'-8s-+-%'-25s-+-%'-36s-+\n", "", "", "" ); $out .= "\n" . $hdr; foreach ( $this->errors as [ 'type' => $type, 'message' => $key, 'params' => $params ] ) { if ( $key instanceof MessageSpecifier ) { $params = $key->getParams(); $key = $key->getKey(); } $keyChunks = mb_str_split( $key, 25 ); $paramsChunks = mb_str_split( $this->flattenParams( $params, " | " ), 36 ); // array_map(null,...) is like Python's zip() foreach ( array_map( null, [ $type ], $keyChunks, $paramsChunks ) as [ $typeChunk, $keyChunk, $paramsChunk ] ) { $out .= sprintf( "| %-8s | %-25s | %-36s |\n", $typeChunk, $keyChunk, $paramsChunk ); } } $out .= $hdr; } return $out; } /** * @param array $params Message parameters * @param string $joiner * * @return string String representation */ private function flattenParams( array $params, string $joiner = ', ' ): string { $ret = []; foreach ( $params as $p ) { if ( is_array( $p ) ) { $r = '[ ' . self::flattenParams( $p ) . ' ]'; } elseif ( $p instanceof MessageSpecifier ) { $r = '{ ' . $p->getKey() . ': ' . self::flattenParams( $p->getParams() ) . ' }'; } elseif ( $p instanceof MessageParam ) { $r = $p->dump(); } else { $r = (string)$p; } $ret[] = mb_strlen( $r ) > 100 ? mb_substr( $r, 0, 99 ) . "..." : $r; } return implode( $joiner, $ret ); } /** * Returns a list of status messages of the given type (or all if false) * * @internal Only for use by Status. * * @param string|bool $type * @return array[] */ protected function getStatusArray( $type = false ) { $result = []; foreach ( $this->getErrors() as $error ) { if ( !$type || $error['type'] === $type ) { if ( $error['message'] instanceof MessageSpecifier ) { $result[] = [ $error['message']->getKey(), ...$error['message']->getParams() ]; } else { $result[] = [ $error['message'], ...$error['params'] ]; } } } return $result; } } PK ! �vj Diff/TableDiffFormatter.phpnu �Iw�� <?php /** * Portions taken from phpwiki-1.3.3. * * Copyright © 2000, 2001 Geoffrey T. Dairiki <dairiki@dairiki.org> * You may copy this code freely under the conditions of the GPL. * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file * @ingroup DifferenceEngine */ namespace Wikimedia\Diff; use InvalidArgumentException; /** * MediaWiki default table style diff formatter * @todo document * @newable * @ingroup DifferenceEngine */ class TableDiffFormatter extends DiffFormatter { /** * Constants for diff sides. Note: these are also used for context lines. */ private const SIDE_DELETED = 'deleted'; private const SIDE_ADDED = 'added'; private const SIDE_CLASSES = [ self::SIDE_DELETED => 'diff-side-deleted', self::SIDE_ADDED => 'diff-side-added' ]; public function __construct() { $this->leadingContextLines = 2; $this->trailingContextLines = 2; } /** * @param string $msg * * @return string */ public static function escapeWhiteSpace( $msg ) { $msg = preg_replace( '/^ /m', "\u{00A0} ", $msg ); $msg = preg_replace( '/ $/m', " \u{00A0}", $msg ); $msg = preg_replace( '/ /', "\u{00A0} ", $msg ); return $msg; } /** * @param int $xbeg * @param int $xlen * @param int $ybeg * @param int $ylen * * @return string */ protected function blockHeader( $xbeg, $xlen, $ybeg, $ylen ) { // '<!--LINE \d+ -->' get replaced by a localised line number // in BaseTextDiffer::localizeLineNumbers return $this->rawElement( 'tr', [], $this->rawElement( 'td', [ 'colspan' => '2', 'class' => 'diff-lineno', 'id' => 'mw-diff-left-l' . $xbeg ], '<!--LINE ' . $xbeg . '-->' ) . "\n" . $this->rawElement( 'td', [ 'colspan' => '2', 'class' => 'diff-lineno' ], '<!--LINE ' . $ybeg . '-->' ) ) . "\n"; } /** @inheritDoc */ protected function startBlock( $header ) { $this->writeOutput( $header ); } /** @inheritDoc */ protected function endBlock() { } /** * @param string[] $lines * @param string $prefix * @param string $color */ protected function lines( $lines, $prefix = ' ', $color = 'white' ) { } /** * HTML-escape parameter before calling this * * @param string $line * * @return string */ protected function addedLine( $line ) { return $this->wrapLine( '+', [ 'diff-addedline', $this->getClassForSide( self::SIDE_ADDED ) ], $line ); } /** * HTML-escape parameter before calling this * * @param string $line * * @return string */ protected function deletedLine( $line ) { return $this->wrapLine( '−', [ 'diff-deletedline', $this->getClassForSide( self::SIDE_DELETED ) ], $line ); } /** * HTML-escape parameter before calling this * * @param string $line * @param string $side self::SIDE_DELETED or self::SIDE_ADDED * * @return string */ protected function contextLine( $line, string $side ) { return $this->wrapLine( '', [ 'diff-context', $this->getClassForSide( $side ) ], $line ); } /** * @param string $marker * @param string|string[] $class A single class or a list of classes * @param string $line * * @return string */ protected function wrapLine( $marker, $class, $line ) { if ( $line !== '' ) { // The <div> wrapper is needed for 'overflow: auto' style to scroll properly $line = $this->rawElement( 'div', [], $this->escapeWhiteSpace( $line ) ); } else { $line = '<br>'; } $markerAttrs = [ 'class' => 'diff-marker' ]; if ( $marker ) { $markerAttrs['data-marker'] = $marker; } if ( is_array( $class ) ) { $class = implode( ' ', $class ); } return $this->element( 'td', $markerAttrs ) . $this->rawElement( 'td', [ 'class' => $class ], $line ); } /** * @param string $side self::SIDE_DELETED or self::SIDE_ADDED * @return string */ protected function emptyLine( string $side ) { return $this->element( 'td', [ 'colspan' => '2', 'class' => $this->getClassForSide( $side ) ] ); } /** * Writes all lines to the output buffer, each enclosed in <tr>. * * @param string[] $lines */ protected function added( $lines ) { foreach ( $lines as $line ) { $this->writeOutput( $this->rawElement( 'tr', [], $this->emptyLine( self::SIDE_DELETED ) . $this->addedLine( $this->element( 'ins', [ 'class' => 'diffchange' ], $line ) ) ) . "\n" ); } } /** * Writes all lines to the output buffer, each enclosed in <tr>. * * @param string[] $lines */ protected function deleted( $lines ) { foreach ( $lines as $line ) { $this->writeOutput( $this->rawElement( 'tr', [], $this->deletedLine( $this->element( 'del', [ 'class' => 'diffchange' ], $line ) ) . $this->emptyLine( self::SIDE_ADDED ) ) . "\n" ); } } /** * Writes all lines to the output buffer, each enclosed in <tr>. * * @param string[] $lines */ protected function context( $lines ) { foreach ( $lines as $line ) { $this->writeOutput( $this->rawElement( 'tr', [], $this->contextLine( htmlspecialchars( $line ), self::SIDE_DELETED ) . $this->contextLine( htmlspecialchars( $line ), self::SIDE_ADDED ) ) . "\n" ); } } /** * Writes the two sets of lines to the output buffer, each enclosed in <tr>. * * @param string[] $orig * @param string[] $closing */ protected function changed( $orig, $closing ) { $diff = new WordLevelDiff( $orig, $closing ); $del = $diff->orig(); $add = $diff->closing(); # Notice that WordLevelDiff returns HTML-escaped output. # Hence, we will be calling addedLine/deletedLine without HTML-escaping. $ndel = count( $del ); $nadd = count( $add ); $n = max( $ndel, $nadd ); for ( $i = 0; $i < $n; $i++ ) { $delLine = $i < $ndel ? $this->deletedLine( $del[$i] ) : $this->emptyLine( self::SIDE_DELETED ); $addLine = $i < $nadd ? $this->addedLine( $add[$i] ) : $this->emptyLine( self::SIDE_ADDED ); $this->writeOutput( $this->rawElement( 'tr', [], $delLine . $addLine ) . "\n" ); } } /** * Get a class for the given diff side, or throw if the side is invalid. * * @param string $side self::SIDE_DELETED or self::SIDE_ADDED * @return string * @throws InvalidArgumentException */ private function getClassForSide( string $side ): string { if ( !isset( self::SIDE_CLASSES[$side] ) ) { throw new InvalidArgumentException( "Invalid diff side: $side" ); } return self::SIDE_CLASSES[$side]; } /** * Serialize an HTML element, with raw contents. * * @param string $element * @param string[] $attribs * @param string $contents The HTML element contents * @return string */ private function rawElement( $element, $attribs = [], $contents = '' ) { $ret = "<$element"; foreach ( $attribs as $name => $value ) { $ret .= " $name=\"" . htmlspecialchars( $value, ENT_QUOTES ) . '"'; } $ret .= ">$contents</$element>"; return $ret; } /** * Serialize an HTML element, encoding the text contents. * * @param string $element * @param string[] $attribs * @param string $contents The text contents * @return string */ private function element( $element, $attribs = [], $contents = '' ) { return $this->rawElement( $element, $attribs, htmlspecialchars( $contents, ENT_NOQUOTES ) ); } } /** @deprecated class alias since 1.41 */ class_alias( TableDiffFormatter::class, 'TableDiffFormatter' ); PK ! �!L� Diff/Diff.phpnu �Iw�� <?php /** * A PHP diff engine for phpwiki. (Taken from phpwiki-1.3.3) * * Copyright © 2000, 2001 Geoffrey T. Dairiki <dairiki@dairiki.org> * You may copy this code freely under the conditions of the GPL. * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file * @ingroup DifferenceEngine */ namespace Wikimedia\Diff; /** * Class representing a 'diff' between two sequences of strings. * @newable * @ingroup DifferenceEngine */ class Diff { /** * @var DiffOp[] */ public $edits; /** * @var int If this diff complexity is exceeded, a ComplexityException is thrown * 0 means no limit. */ protected $bailoutComplexity = 0; /** * Computes diff between sequences of strings. * * @stable to call * @todo Don't do work in the constructor, use a service to create diffs instead (T257472). * * @param string[] $from_lines An array of strings. * Typically these are lines from a file. * @param string[] $to_lines An array of strings. * @throws ComplexityException */ public function __construct( $from_lines, $to_lines ) { $eng = new DiffEngine; $eng->setBailoutComplexity( $this->bailoutComplexity ); $this->edits = $eng->diff( $from_lines, $to_lines ); } /** * @return DiffOp[] */ public function getEdits() { return $this->edits; } /** * Compute reversed Diff. * * SYNOPSIS: * * $diff = new Diff($lines1, $lines2); * $rev = $diff->reverse(); * * @return self A Diff object representing the inverse of the * original diff. */ public function reverse() { $rev = $this; $rev->edits = []; /** @var DiffOp $edit */ foreach ( $this->edits as $edit ) { $rev->edits[] = $edit->reverse(); } return $rev; } /** * Check for empty diff. * * @return bool True if two sequences were identical. */ public function isEmpty() { foreach ( $this->edits as $edit ) { if ( $edit->type != 'copy' ) { return false; } } return true; } /** * Compute the length of the Longest Common Subsequence (LCS). * * This is mostly for diagnostic purposed. * * @return int The length of the LCS. */ public function lcs() { $lcs = 0; foreach ( $this->edits as $edit ) { if ( $edit->type == 'copy' ) { $lcs += count( $edit->orig ); } } return $lcs; } /** * Get the original set of lines. * * This reconstructs the $from_lines parameter passed to the * constructor. * * @return string[] The original sequence of strings. */ public function orig() { $lines = []; foreach ( $this->edits as $edit ) { if ( $edit->orig ) { array_splice( $lines, count( $lines ), 0, $edit->orig ); } } return $lines; } /** * Get the closing set of lines. * * This reconstructs the $to_lines parameter passed to the * constructor. * * @return string[] The sequence of strings. */ public function closing() { $lines = []; foreach ( $this->edits as $edit ) { if ( $edit->closing ) { array_splice( $lines, count( $lines ), 0, $edit->closing ); } } return $lines; } } /** @deprecated class alias since 1.41 */ class_alias( Diff::class, 'Diff' ); PK ! �-Z� � Diff/DiffOp.phpnu �Iw�� <?php /** * A PHP diff engine for phpwiki. (Taken from phpwiki-1.3.3) * * Copyright © 2000, 2001 Geoffrey T. Dairiki <dairiki@dairiki.org> * You may copy this code freely under the conditions of the GPL. * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file * @ingroup DifferenceEngine * @defgroup DifferenceEngine DifferenceEngine */ namespace Wikimedia\Diff; /** * The base class for all other DiffOp classes. * * The classes that extend DiffOp are: DiffOpCopy, DiffOpDelete, DiffOpAdd and * DiffOpChange. FakeDiffOp also extends DiffOp, but it is not located in this file. * * @ingroup DifferenceEngine */ abstract class DiffOp { /** * @var string * @private Please use {@see getType} */ public $type; /** * @var string[]|false The left ("old") side of the diff, or false when it's an "add" * @private Please use {@see getOrig} */ public $orig; /** * @var string[]|false The right ("new") side of the diff, or false when it's a "delete" * @private Please use {@see getClosing} */ public $closing; /** * @return string Either "add", "change", "copy", or "delete" */ public function getType() { return $this->type; } /** * Returns either all lines on the left ("old") side of the diff, or false when it's an add * operation. * * @return string[]|false */ public function getOrig() { return $this->orig; } /** * Without a line number this returns either all lines on the right ("new") side of the diff, or * false when it's a delete operation. * * With a line number this returns either the line or null if the line doesn't exist. * * @param int|null $i Line number, or null for all lines in the operation * @return string[]|false|string|null */ public function getClosing( $i = null ) { if ( $i === null ) { return $this->closing; } if ( array_key_exists( $i, $this->closing ) ) { return $this->closing[$i]; } return null; } /** * @return self Inverted operation (a.k.a. revert or undo), e.g. "delete" becomes "add" */ abstract public function reverse(); /** * @return int Number of lines on the left ("old") side of the diff, {@see getOrig} */ public function norig() { return $this->orig ? count( $this->orig ) : 0; } /** * @return int Number of lines on the right ("new") side of the diff, see {@see getClosing} */ public function nclosing() { return $this->closing ? count( $this->closing ) : 0; } } /** @deprecated class alias since 1.41 */ class_alias( DiffOp::class, 'DiffOp' ); PK ! ��%�[ [ Diff/DiffFormatter.phpnu �Iw�� <?php /** * Base for diff rendering classes. Portions taken from phpwiki-1.3.3. * * Copyright © 2000, 2001 Geoffrey T. Dairiki <dairiki@dairiki.org> * You may copy this code freely under the conditions of the GPL. * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file * @ingroup DifferenceEngine */ namespace Wikimedia\Diff; use UnexpectedValueException; /** * Base class for diff formatters * * This class formats the diff in classic diff format. * It is intended that this class be customized via inheritance, * to obtain fancier outputs. * @todo document * @ingroup DifferenceEngine */ abstract class DiffFormatter { /** @var int Number of leading context "lines" to preserve. * * This should be left at zero for this class, but subclasses * may want to set this to other values. */ protected $leadingContextLines = 0; /** @var int Number of trailing context "lines" to preserve. * * This should be left at zero for this class, but subclasses * may want to set this to other values. */ protected $trailingContextLines = 0; /** @var string The output buffer; holds the output while it is built. */ private $result = ''; /** * Format a diff. * * @param Diff $diff * * @return string The formatted output. */ public function format( $diff ) { $xi = $yi = 1; $block = false; $context = []; $nlead = $this->leadingContextLines; $ntrail = $this->trailingContextLines; $this->startDiff(); // Initialize $x0 and $y0 to prevent IDEs from getting confused. $x0 = $y0 = 0; foreach ( $diff->edits as $edit ) { if ( $edit->type == 'copy' ) { if ( is_array( $block ) ) { if ( count( $edit->orig ) <= $nlead + $ntrail ) { $block[] = $edit; } else { if ( $ntrail ) { $context = array_slice( $edit->orig, 0, $ntrail ); $block[] = new DiffOpCopy( $context ); } $this->block( $x0, $ntrail + $xi - $x0, $y0, $ntrail + $yi - $y0, $block ); $block = false; } } $context = $edit->orig; } else { if ( !is_array( $block ) ) { $context = array_slice( $context, count( $context ) - $nlead ); $x0 = $xi - count( $context ); $y0 = $yi - count( $context ); $block = []; if ( $context ) { $block[] = new DiffOpCopy( $context ); } } $block[] = $edit; } if ( $edit->orig ) { $xi += count( $edit->orig ); } if ( $edit->closing ) { $yi += count( $edit->closing ); } } if ( is_array( $block ) ) { $this->block( $x0, $xi - $x0, $y0, $yi - $y0, $block ); } $end = $this->endDiff(); return $end; } /** * @param int $xbeg * @param int $xlen * @param int $ybeg * @param int $ylen * @param array &$edits */ protected function block( $xbeg, $xlen, $ybeg, $ylen, &$edits ) { $this->startBlock( $this->blockHeader( $xbeg, $xlen, $ybeg, $ylen ) ); foreach ( $edits as $edit ) { if ( $edit->type == 'copy' ) { $this->context( $edit->orig ); } elseif ( $edit->type == 'add' ) { $this->added( $edit->closing ); } elseif ( $edit->type == 'delete' ) { $this->deleted( $edit->orig ); } elseif ( $edit->type == 'change' ) { $this->changed( $edit->orig, $edit->closing ); } else { throw new UnexpectedValueException( "Unknown edit type: {$edit->type}" ); } } $this->endBlock(); } protected function startDiff() { $this->result = ''; } /** * Writes a string to the output buffer. * * @param string $text */ protected function writeOutput( $text ) { $this->result .= $text; } /** * @return string */ protected function endDiff() { $val = $this->result; $this->result = ''; return $val; } /** * @param int $xbeg * @param int $xlen * @param int $ybeg * @param int $ylen * * @return string */ protected function blockHeader( $xbeg, $xlen, $ybeg, $ylen ) { if ( $xlen > 1 ) { $xbeg .= ',' . ( $xbeg + $xlen - 1 ); } if ( $ylen > 1 ) { $ybeg .= ',' . ( $ybeg + $ylen - 1 ); } return $xbeg . ( $xlen ? ( $ylen ? 'c' : 'd' ) : 'a' ) . $ybeg; } /** * Called at the start of a block of connected edits. * This default implementation writes the header and a newline to the output buffer. * * @param string $header */ protected function startBlock( $header ) { $this->writeOutput( $header . "\n" ); } /** * Called at the end of a block of connected edits. * This default implementation does nothing. */ protected function endBlock() { } /** * Writes all (optionally prefixed) lines to the output buffer, separated by newlines. * * @param string[] $lines * @param string $prefix */ protected function lines( $lines, $prefix = ' ' ) { foreach ( $lines as $line ) { $this->writeOutput( "$prefix $line\n" ); } } /** * @param string[] $lines */ protected function context( $lines ) { $this->lines( $lines ); } /** * @param string[] $lines */ protected function added( $lines ) { $this->lines( $lines, '>' ); } /** * @param string[] $lines */ protected function deleted( $lines ) { $this->lines( $lines, '<' ); } /** * Writes the two sets of lines to the output buffer, separated by "---" and a newline. * * @param string[] $orig * @param string[] $closing */ protected function changed( $orig, $closing ) { $this->deleted( $orig ); $this->writeOutput( "---\n" ); $this->added( $closing ); } } /** @deprecated class alias since 1.41 */ class_alias( DiffFormatter::class, 'DiffFormatter' ); PK ! �tef f Diff/ArrayDiffFormatter.phpnu �Iw�� <?php /** * Portions taken from phpwiki-1.3.3. * * Copyright © 2000, 2001 Geoffrey T. Dairiki <dairiki@dairiki.org> * You may copy this code freely under the conditions of the GPL. * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file * @ingroup DifferenceEngine */ namespace Wikimedia\Diff; /** * A pseudo-formatter that just passes along the Diff::$edits array * @newable * @ingroup DifferenceEngine */ class ArrayDiffFormatter extends DiffFormatter { /** * @param Diff $diff A Diff object. * * @return array[] List of associative arrays, each describing a difference. * @suppress PhanParamSignatureMismatch */ public function format( $diff ) { $oldline = 1; $newline = 1; $retval = []; foreach ( $diff->getEdits() as $edit ) { switch ( $edit->getType() ) { case 'add': foreach ( $edit->getClosing() as $line ) { $retval[] = [ 'action' => 'add', 'new' => $line, 'newline' => $newline++ ]; } break; case 'delete': foreach ( $edit->getOrig() as $line ) { $retval[] = [ 'action' => 'delete', 'old' => $line, 'oldline' => $oldline++, ]; } break; case 'change': foreach ( $edit->getOrig() as $key => $line ) { $retval[] = [ 'action' => 'change', 'old' => $line, 'new' => $edit->getClosing( $key ), 'oldline' => $oldline++, 'newline' => $newline++, ]; } break; case 'copy': $oldline += $edit->norig(); $newline += $edit->norig(); } } return $retval; } } /** @deprecated class alias since 1.41 */ class_alias( ArrayDiffFormatter::class, 'ArrayDiffFormatter' ); PK ! ���� � Diff/WordLevelDiff.phpnu �Iw�� <?php /** * Copyright © 2000, 2001 Geoffrey T. Dairiki <dairiki@dairiki.org> * You may copy this code freely under the conditions of the GPL. * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file * @ingroup DifferenceEngine * @defgroup DifferenceEngine DifferenceEngine */ namespace Wikimedia\Diff; /** * Performs a word-level diff on several lines * * @newable * @ingroup DifferenceEngine */ class WordLevelDiff extends Diff { /** * @inheritDoc */ protected $bailoutComplexity = 40_000_000; // Roughly 6K x 6K words changed /** * @stable to call * @todo Don't do work in the constructor, use a service to create diffs instead (T257472). * * @param string[] $linesBefore * @param string[] $linesAfter */ public function __construct( $linesBefore, $linesAfter ) { [ $wordsBefore, $wordsBeforeStripped ] = $this->split( $linesBefore ); [ $wordsAfter, $wordsAfterStripped ] = $this->split( $linesAfter ); try { parent::__construct( $wordsBeforeStripped, $wordsAfterStripped ); } catch ( ComplexityException $ex ) { // Too hard to diff, just show whole paragraph(s) as changed $this->edits = [ new DiffOpChange( $linesBefore, $linesAfter ) ]; } $xi = $yi = 0; $editCount = count( $this->edits ); for ( $i = 0; $i < $editCount; $i++ ) { $orig = &$this->edits[$i]->orig; if ( is_array( $orig ) ) { $orig = array_slice( $wordsBefore, $xi, count( $orig ) ); $xi += count( $orig ); } $closing = &$this->edits[$i]->closing; if ( is_array( $closing ) ) { $closing = array_slice( $wordsAfter, $yi, count( $closing ) ); $yi += count( $closing ); } } } /** * @param string[] $lines * * @return array[] */ private function split( $lines ) { $words = []; $stripped = []; $first = true; foreach ( $lines as $line ) { if ( $first ) { $first = false; } else { $words[] = "\n"; $stripped[] = "\n"; } $m = []; if ( preg_match_all( '/ ( [^\S\n]+ | [0-9_A-Za-z\x80-\xff]+ | . ) (?: (?!< \n) [^\S\n])? /xs', $line, $m ) ) { foreach ( $m[0] as $word ) { $words[] = $word; } foreach ( $m[1] as $stripped_word ) { $stripped[] = $stripped_word; } } } return [ $words, $stripped ]; } /** * @return string[] */ public function orig() { $orig = new WordAccumulator; foreach ( $this->edits as $edit ) { if ( $edit->type == 'copy' ) { $orig->addWords( $edit->orig ); } elseif ( $edit->orig ) { $orig->addWords( $edit->orig, 'del' ); } } $lines = $orig->getLines(); return $lines; } /** * @return string[] */ public function closing() { $closing = new WordAccumulator; foreach ( $this->edits as $edit ) { if ( $edit->type == 'copy' ) { $closing->addWords( $edit->closing ); } elseif ( $edit->closing ) { $closing->addWords( $edit->closing, 'ins' ); } } $lines = $closing->getLines(); return $lines; } } /** @deprecated class alias since 1.41 */ class_alias( WordLevelDiff::class, 'WordLevelDiff' ); PK ! �1{I� � Diff/WordAccumulator.phpnu �Iw�� <?php /** * Copyright © 2000, 2001 Geoffrey T. Dairiki <dairiki@dairiki.org> * You may copy this code freely under the conditions of the GPL. * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file * @ingroup DifferenceEngine * @defgroup DifferenceEngine DifferenceEngine */ namespace Wikimedia\Diff; /** * Stores, escapes and formats the results of word-level diff */ class WordAccumulator { /** @var string */ public $insClass = ' class="diffchange diffchange-inline"'; /** @var string */ public $delClass = ' class="diffchange diffchange-inline"'; /** @var array */ private $lines = []; /** @var string */ private $line = ''; /** @var string */ private $group = ''; /** @var string */ private $tag = ''; /** * @param string $new_tag */ private function flushGroup( $new_tag ) { if ( $this->group !== '' ) { $encGroup = htmlspecialchars( $this->group, ENT_NOQUOTES ); if ( $this->tag == 'ins' ) { $this->line .= "<ins{$this->insClass}>$encGroup</ins>"; } elseif ( $this->tag == 'del' ) { $this->line .= "<del{$this->delClass}>$encGroup</del>"; } else { $this->line .= $encGroup; } } $this->group = ''; $this->tag = $new_tag; } /** * @param string $new_tag */ private function flushLine( $new_tag ) { $this->flushGroup( $new_tag ); if ( $this->line != '' ) { $this->lines[] = $this->line; } else { # make empty lines visible by inserting an NBSP $this->lines[] = "\u{00A0}"; } $this->line = ''; } /** * @param string[] $words * @param string $tag */ public function addWords( $words, $tag = '' ) { if ( $tag != $this->tag ) { $this->flushGroup( $tag ); } foreach ( $words as $word ) { // new-line should only come as first char of word. if ( $word == '' ) { continue; } if ( $word[0] == "\n" ) { $this->flushLine( $tag ); $word = substr( $word, 1 ); } // FIXME: Don't use assert() // phpcs:ignore MediaWiki.Usage.ForbiddenFunctions.assert assert( !strstr( $word, "\n" ) ); $this->group .= $word; } } /** * @return string[] */ public function getLines() { $this->flushLine( '~done' ); return $this->lines; } } /** @deprecated class alias since 1.41 */ class_alias( WordAccumulator::class, 'MediaWiki\\Diff\\WordAccumulator' ); PK ! k��R� � Diff/UnifiedDiffFormatter.phpnu �Iw�� <?php /** * Portions taken from phpwiki-1.3.3. * * Copyright © 2000, 2001 Geoffrey T. Dairiki <dairiki@dairiki.org> * You may copy this code freely under the conditions of the GPL. * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file * @ingroup DifferenceEngine */ namespace Wikimedia\Diff; /** * A formatter that outputs unified diffs * @newable * @ingroup DifferenceEngine */ class UnifiedDiffFormatter extends DiffFormatter { /** @var int */ protected $leadingContextLines = 2; /** @var int */ protected $trailingContextLines = 2; /** * @param string[] $lines * @param string $prefix */ protected function lines( $lines, $prefix = ' ' ) { foreach ( $lines as $line ) { $this->writeOutput( "{$prefix}{$line}\n" ); } } /** * @param string[] $lines */ protected function added( $lines ) { $this->lines( $lines, '+' ); } /** * @param string[] $lines */ protected function deleted( $lines ) { $this->lines( $lines, '-' ); } /** * @param string[] $orig * @param string[] $closing */ protected function changed( $orig, $closing ) { $this->deleted( $orig ); $this->added( $closing ); } /** * @param int $xbeg * @param int $xlen * @param int $ybeg * @param int $ylen * * @return string */ protected function blockHeader( $xbeg, $xlen, $ybeg, $ylen ) { return "@@ -$xbeg,$xlen +$ybeg,$ylen @@"; } } /** @deprecated class alias since 1.41 */ class_alias( UnifiedDiffFormatter::class, 'UnifiedDiffFormatter' ); PK ! [�'�4 4 Diff/DiffOpAdd.phpnu �Iw�� <?php /** * A PHP diff engine for phpwiki. (Taken from phpwiki-1.3.3) * * Copyright © 2000, 2001 Geoffrey T. Dairiki <dairiki@dairiki.org> * You may copy this code freely under the conditions of the GPL. * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file * @ingroup DifferenceEngine */ namespace Wikimedia\Diff; /** * Extends DiffOp. Used to mark strings that have been * added from the first string array. * * @ingroup DifferenceEngine */ class DiffOpAdd extends DiffOp { /** @inheritDoc */ public $type = 'add'; /** * @param string[] $lines */ public function __construct( $lines ) { $this->closing = $lines; $this->orig = false; } /** * @return DiffOpDelete */ public function reverse() { return new DiffOpDelete( $this->closing ); } } /** @deprecated class alias since 1.41 */ class_alias( DiffOpAdd::class, 'DiffOpAdd' ); PK ! !� � Diff/ComplexityException.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with this program; if not, write to the Free Software * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file * @ingroup DifferenceEngine */ namespace Wikimedia\Diff; use Exception; /** * @newable */ class ComplexityException extends Exception { /** * @stable to call */ public function __construct() { parent::__construct( 'Diff is too complex to generate' ); } } /** @deprecated class alias since 1.41 */ class_alias( ComplexityException::class, 'MediaWiki\\Diff\\ComplexityException' ); PK ! ���;� � Diff/DiffOpChange.phpnu �Iw�� <?php /** * A PHP diff engine for phpwiki. (Taken from phpwiki-1.3.3) * * Copyright © 2000, 2001 Geoffrey T. Dairiki <dairiki@dairiki.org> * You may copy this code freely under the conditions of the GPL. * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file * @ingroup DifferenceEngine */ namespace Wikimedia\Diff; /** * Extends DiffOp. Used to mark strings that have been * changed from the first string array (both added and subtracted). * * @ingroup DifferenceEngine */ class DiffOpChange extends DiffOp { /** @inheritDoc */ public $type = 'change'; /** * @param string[] $orig * @param string[] $closing */ public function __construct( $orig, $closing ) { $this->orig = $orig; $this->closing = $closing; } /** * @return DiffOpChange */ public function reverse() { return new DiffOpChange( $this->closing, $this->orig ); } } /** @deprecated class alias since 1.41 */ class_alias( DiffOpChange::class, 'DiffOpChange' ); PK ! ��\OhV hV Diff/DiffEngine.phpnu �Iw�� <?php /** * New version of the difference engine * * Copyright © 2008 Guy Van den Broeck <guy@guyvdb.eu> * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License * along with this program; if not, write to the Free Software * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file * @ingroup DifferenceEngine */ namespace Wikimedia\Diff; // FIXME: Don't use assert() in this file // phpcs:disable MediaWiki.Usage.ForbiddenFunctions.assert /** * This diff implementation is mainly lifted from the LCS algorithm of the Eclipse project which * in turn is based on Myers' "An O(ND) difference algorithm and its variations" * (http://citeseer.ist.psu.edu/myers86ond.html) with range compression (see Wu et al.'s * "An O(NP) Sequence Comparison Algorithm"). * * This implementation supports an upper bound on the execution time. * * Some ideas (and a bit of code) are from analyze.c, from GNU * diffutils-2.7, which can be found at: * ftp://gnudist.gnu.org/pub/gnu/diffutils/diffutils-2.7.tar.gz * * Complexity: O((M + N)D) worst case time, O(M + N + D^2) expected time, O(M + N) space * * @author Guy Van den Broeck, Geoffrey T. Dairiki, Tim Starling * @ingroup DifferenceEngine */ class DiffEngine { // Input variables /** @var string[] */ private $from; /** @var string[] */ private $to; /** @var int */ private $m; /** @var int */ private $n; /** @var int */ private $tooLong; /** @var float */ private $powLimit; /** @var int */ protected $bailoutComplexity = 0; // State variables /** @var float */ private $maxDifferences; /** @var bool */ private $lcsLengthCorrectedForHeuristic = false; // Output variables /** @var int */ public $length; /** @var array */ public $removed; /** @var array */ public $added; /** @var bool */ public $heuristicUsed; /** * @param int $tooLong * @param float $powLimit */ public function __construct( $tooLong = 2_000_000, $powLimit = 1.45 ) { $this->tooLong = $tooLong; $this->powLimit = $powLimit; } /** * Performs diff * * @param string[] $from_lines * @param string[] $to_lines * @throws ComplexityException * * @return DiffOp[] */ public function diff( $from_lines, $to_lines ) { // Diff and store locally $this->diffInternal( $from_lines, $to_lines ); // Merge edits when possible $this->shiftBoundaries( $from_lines, $this->removed, $this->added ); $this->shiftBoundaries( $to_lines, $this->added, $this->removed ); // Compute the edit operations. $n_from = count( $from_lines ); $n_to = count( $to_lines ); $edits = []; $xi = $yi = 0; while ( $xi < $n_from || $yi < $n_to ) { assert( $yi < $n_to || $this->removed[$xi] ); assert( $xi < $n_from || $this->added[$yi] ); // Skip matching "snake". $copy = []; while ( $xi < $n_from && $yi < $n_to && !$this->removed[$xi] && !$this->added[$yi] ) { $copy[] = $from_lines[$xi++]; ++$yi; } if ( $copy ) { $edits[] = new DiffOpCopy( $copy ); } // Find deletes & adds. $delete = []; while ( $xi < $n_from && $this->removed[$xi] ) { $delete[] = $from_lines[$xi++]; } $add = []; while ( $yi < $n_to && $this->added[$yi] ) { $add[] = $to_lines[$yi++]; } if ( $delete && $add ) { $edits[] = new DiffOpChange( $delete, $add ); } elseif ( $delete ) { $edits[] = new DiffOpDelete( $delete ); } elseif ( $add ) { $edits[] = new DiffOpAdd( $add ); } } return $edits; } /** * Sets the complexity (in comparison operations) that can't be exceeded * @param int $value */ public function setBailoutComplexity( $value ) { $this->bailoutComplexity = $value; } /** * Adjust inserts/deletes of identical lines to join changes * as much as possible. * * We do something when a run of changed lines include a * line at one end and has an excluded, identical line at the other. * We are free to choose which identical line is included. * `compareseq' usually chooses the one at the beginning, * but usually it is cleaner to consider the following identical line * to be the "change". * * This is extracted verbatim from analyze.c (GNU diffutils-2.7). * * @param string[] $lines * @param string[] &$changed * @param string[] $other_changed */ private function shiftBoundaries( array $lines, array &$changed, array $other_changed ) { $i = 0; $j = 0; assert( count( $lines ) == count( $changed ) ); $len = count( $lines ); $other_len = count( $other_changed ); while ( 1 ) { /* * Scan forwards to find beginning of another run of changes. * Also keep track of the corresponding point in the other file. * * Throughout this code, $i and $j are adjusted together so that * the first $i elements of $changed and the first $j elements * of $other_changed both contain the same number of zeros * (unchanged lines). * Furthermore, $j is always kept so that $j == $other_len or * $other_changed[$j] == false. */ while ( $j < $other_len && $other_changed[$j] ) { $j++; } while ( $i < $len && !$changed[$i] ) { assert( $j < $other_len && !$other_changed[$j] ); $i++; $j++; while ( $j < $other_len && $other_changed[$j] ) { $j++; } } if ( $i == $len ) { break; } $start = $i; // Find the end of this run of changes. while ( ++$i < $len && $changed[$i] ) { continue; } do { /* * Record the length of this run of changes, so that * we can later determine whether the run has grown. */ $runlength = $i - $start; /* * Move the changed region back, so long as the * previous unchanged line matches the last changed one. * This merges with previous changed regions. */ while ( $start > 0 && $lines[$start - 1] == $lines[$i - 1] ) { $changed[--$start] = 1; $changed[--$i] = false; // @phan-suppress-next-line PhanPluginLoopVariableReuse while ( $start > 0 && $changed[$start - 1] ) { $start--; } assert( $j > 0 ); while ( $other_changed[--$j] ) { continue; } assert( $j >= 0 && !$other_changed[$j] ); } /* * Set CORRESPONDING to the end of the changed run, at the last * point where it corresponds to a changed run in the other file. * CORRESPONDING == LEN means no such point has been found. */ $corresponding = $j < $other_len ? $i : $len; /* * Move the changed region forward, so long as the * first changed line matches the following unchanged one. * This merges with following changed regions. * Do this second, so that if there are no merges, * the changed region is moved forward as far as possible. */ while ( $i < $len && $lines[$start] == $lines[$i] ) { $changed[$start++] = false; $changed[$i++] = 1; while ( $i < $len && $changed[$i] ) { $i++; } assert( $j < $other_len && !$other_changed[$j] ); $j++; if ( $j < $other_len && $other_changed[$j] ) { $corresponding = $i; while ( $j < $other_len && $other_changed[$j] ) { $j++; } } } } while ( $runlength != $i - $start ); /* * If possible, move the fully-merged run of changes * back to a corresponding run in the other file. */ while ( $corresponding < $i ) { $changed[--$start] = 1; $changed[--$i] = 0; assert( $j > 0 ); while ( $other_changed[--$j] ) { continue; } assert( $j >= 0 && !$other_changed[$j] ); } } } /** * @param string[] $from * @param string[] $to * @throws ComplexityException */ protected function diffInternal( array $from, array $to ) { // remember initial lengths $m = count( $from ); $n = count( $to ); $this->heuristicUsed = false; // output $removed = $m > 0 ? array_fill( 0, $m, true ) : []; $added = $n > 0 ? array_fill( 0, $n, true ) : []; // reduce the complexity for the next step (intentionally done twice) // remove common tokens at the start $i = 0; while ( $i < $m && $i < $n && $from[$i] === $to[$i] ) { $removed[$i] = $added[$i] = false; unset( $from[$i], $to[$i] ); ++$i; } // remove common tokens at the end $j = 1; while ( $i + $j <= $m && $i + $j <= $n && $from[$m - $j] === $to[$n - $j] ) { $removed[$m - $j] = $added[$n - $j] = false; unset( $from[$m - $j], $to[$n - $j] ); ++$j; } $this->from = $newFromIndex = $this->to = $newToIndex = []; // remove tokens not in both sequences $shared = []; foreach ( $from as $key ) { $shared[$key] = false; } foreach ( $to as $index => &$el ) { if ( array_key_exists( $el, $shared ) ) { // keep it $this->to[] = $el; $shared[$el] = true; $newToIndex[] = $index; } } foreach ( $from as $index => &$el ) { if ( $shared[$el] ) { // keep it $this->from[] = $el; $newFromIndex[] = $index; } } unset( $shared, $from, $to ); $this->m = count( $this->from ); $this->n = count( $this->to ); if ( $this->bailoutComplexity > 0 && $this->m * $this->n > $this->bailoutComplexity ) { throw new ComplexityException(); } $this->removed = $this->m > 0 ? array_fill( 0, $this->m, true ) : []; $this->added = $this->n > 0 ? array_fill( 0, $this->n, true ) : []; if ( $this->m == 0 || $this->n == 0 ) { $this->length = 0; } else { $this->maxDifferences = ceil( ( $this->m + $this->n ) / 2.0 ); if ( $this->m * $this->n > $this->tooLong ) { // limit complexity to D^POW_LIMIT for long sequences $this->maxDifferences = floor( $this->maxDifferences ** ( $this->powLimit - 1.0 ) ); } /* * The common prefixes and suffixes are always part of some LCS, include * them now to reduce our search space */ $max = min( $this->m, $this->n ); for ( $forwardBound = 0; $forwardBound < $max && $this->from[$forwardBound] === $this->to[$forwardBound]; ++$forwardBound ) { $this->removed[$forwardBound] = $this->added[$forwardBound] = false; } $backBoundL1 = $this->m - 1; $backBoundL2 = $this->n - 1; while ( $backBoundL1 >= $forwardBound && $backBoundL2 >= $forwardBound && $this->from[$backBoundL1] === $this->to[$backBoundL2] ) { $this->removed[$backBoundL1--] = $this->added[$backBoundL2--] = false; } $temp = array_fill( 0, $this->m + $this->n + 1, 0 ); $V = [ $temp, $temp ]; $snake = [ 0, 0, 0 ]; $this->length = $forwardBound + $this->m - $backBoundL1 - 1 + $this->lcs_rec( $forwardBound, $backBoundL1, $forwardBound, $backBoundL2, $V, $snake ); } $this->m = $m; $this->n = $n; $this->length += $i + $j - 1; foreach ( $this->removed as $key => &$removed_elem ) { if ( !$removed_elem ) { $removed[$newFromIndex[$key]] = false; } } foreach ( $this->added as $key => &$added_elem ) { if ( !$added_elem ) { $added[$newToIndex[$key]] = false; } } $this->removed = $removed; $this->added = $added; } /** * @param int $bottoml1 * @param int $topl1 * @param int $bottoml2 * @param int $topl2 * @param array &$V * @param array &$snake * @return int */ private function lcs_rec( $bottoml1, $topl1, $bottoml2, $topl2, &$V, &$snake ) { // check that both sequences are non-empty if ( $bottoml1 > $topl1 || $bottoml2 > $topl2 ) { return 0; } $d = $this->find_middle_snake( $bottoml1, $topl1, $bottoml2, $topl2, $V, $snake ); // need to store these so we don't lose them when they're // overwritten by the recursion [ $startx, $starty, $len ] = $snake; // the middle snake is part of the LCS, store it for ( $i = 0; $i < $len; ++$i ) { $this->removed[$startx + $i] = $this->added[$starty + $i] = false; } if ( $d > 1 ) { return $len + $this->lcs_rec( $bottoml1, $startx - 1, $bottoml2, $starty - 1, $V, $snake ) + $this->lcs_rec( $startx + $len, $topl1, $starty + $len, $topl2, $V, $snake ); } elseif ( $d == 1 ) { /* * In this case the sequences differ by exactly 1 line. We have * already saved all the lines after the difference in the for loop * above, now we need to save all the lines before the difference. */ $max = min( $startx - $bottoml1, $starty - $bottoml2 ); for ( $i = 0; $i < $max; ++$i ) { $this->removed[$bottoml1 + $i] = $this->added[$bottoml2 + $i] = false; } return $max + $len; } return $len; } /** * @param int $bottoml1 * @param int $topl1 * @param int $bottoml2 * @param int $topl2 * @param array &$V * @param array &$snake * @return int */ private function find_middle_snake( $bottoml1, $topl1, $bottoml2, $topl2, &$V, &$snake ) { $from = &$this->from; $to = &$this->to; $V0 = &$V[0]; $V1 = &$V[1]; $snake0 = &$snake[0]; $snake1 = &$snake[1]; $snake2 = &$snake[2]; $bottoml1_min_1 = $bottoml1 - 1; $bottoml2_min_1 = $bottoml2 - 1; $N = $topl1 - $bottoml1_min_1; $M = $topl2 - $bottoml2_min_1; $delta = $N - $M; $maxabsx = $N + $bottoml1; $maxabsy = $M + $bottoml2; $limit = min( $this->maxDifferences, ceil( ( $N + $M ) / 2 ) ); // value_to_add_forward: a 0 or 1 that we add to the start // offset to make it odd/even if ( $M & 1 ) { $value_to_add_forward = 1; } else { $value_to_add_forward = 0; } if ( $N & 1 ) { $value_to_add_backward = 1; } else { $value_to_add_backward = 0; } $start_forward = -$M; $end_forward = $N; $start_backward = -$N; $end_backward = $M; $limit_min_1 = $limit - 1; $limit_plus_1 = $limit + 1; $V0[$limit_plus_1] = 0; $V1[$limit_min_1] = $N; $limit = min( $this->maxDifferences, ceil( ( $N + $M ) / 2 ) ); if ( $delta & 1 ) { for ( $d = 0; $d <= $limit; ++$d ) { $start_diag = max( $value_to_add_forward + $start_forward, -$d ); $end_diag = min( $end_forward, $d ); $value_to_add_forward = 1 - $value_to_add_forward; // compute forward furthest reaching paths for ( $k = $start_diag; $k <= $end_diag; $k += 2 ) { if ( $k == -$d || ( $k < $d && $V0[$limit_min_1 + $k] < $V0[$limit_plus_1 + $k] ) ) { $x = $V0[$limit_plus_1 + $k]; } else { $x = $V0[$limit_min_1 + $k] + 1; } $absx = $snake0 = $x + $bottoml1; $absy = $snake1 = $x - $k + $bottoml2; while ( $absx < $maxabsx && $absy < $maxabsy && $from[$absx] === $to[$absy] ) { ++$absx; ++$absy; } $x = $absx - $bottoml1; $snake2 = $absx - $snake0; $V0[$limit + $k] = $x; if ( $k >= $delta - $d + 1 && $k <= $delta + $d - 1 && $x >= $V1[$limit + $k - $delta] ) { return 2 * $d - 1; } // check to see if we can cut down the diagonal range if ( $x >= $N && $end_forward > $k - 1 ) { $end_forward = $k - 1; } elseif ( $absy - $bottoml2 >= $M ) { $start_forward = $k + 1; $value_to_add_forward = 0; } } $start_diag = max( $value_to_add_backward + $start_backward, -$d ); $end_diag = min( $end_backward, $d ); $value_to_add_backward = 1 - $value_to_add_backward; // compute backward furthest reaching paths for ( $k = $start_diag; $k <= $end_diag; $k += 2 ) { if ( $k == $d || ( $k != -$d && $V1[$limit_min_1 + $k] < $V1[$limit_plus_1 + $k] ) ) { $x = $V1[$limit_min_1 + $k]; } else { $x = $V1[$limit_plus_1 + $k] - 1; } $y = $x - $k - $delta; $snake2 = 0; while ( $x > 0 && $y > 0 && $from[$x + $bottoml1_min_1] === $to[$y + $bottoml2_min_1] ) { --$x; --$y; ++$snake2; } $V1[$limit + $k] = $x; // check to see if we can cut down our diagonal range if ( $x <= 0 ) { $start_backward = $k + 1; $value_to_add_backward = 0; } elseif ( $y <= 0 && $end_backward > $k - 1 ) { $end_backward = $k - 1; } } } } else { for ( $d = 0; $d <= $limit; ++$d ) { $start_diag = max( $value_to_add_forward + $start_forward, -$d ); $end_diag = min( $end_forward, $d ); $value_to_add_forward = 1 - $value_to_add_forward; // compute forward furthest reaching paths for ( $k = $start_diag; $k <= $end_diag; $k += 2 ) { if ( $k == -$d || ( $k < $d && $V0[$limit_min_1 + $k] < $V0[$limit_plus_1 + $k] ) ) { $x = $V0[$limit_plus_1 + $k]; } else { $x = $V0[$limit_min_1 + $k] + 1; } $absx = $snake0 = $x + $bottoml1; $absy = $snake1 = $x - $k + $bottoml2; while ( $absx < $maxabsx && $absy < $maxabsy && $from[$absx] === $to[$absy] ) { ++$absx; ++$absy; } $x = $absx - $bottoml1; $snake2 = $absx - $snake0; $V0[$limit + $k] = $x; // check to see if we can cut down the diagonal range if ( $x >= $N && $end_forward > $k - 1 ) { $end_forward = $k - 1; } elseif ( $absy - $bottoml2 >= $M ) { $start_forward = $k + 1; $value_to_add_forward = 0; } } $start_diag = max( $value_to_add_backward + $start_backward, -$d ); $end_diag = min( $end_backward, $d ); $value_to_add_backward = 1 - $value_to_add_backward; // compute backward furthest reaching paths for ( $k = $start_diag; $k <= $end_diag; $k += 2 ) { if ( $k == $d || ( $k != -$d && $V1[$limit_min_1 + $k] < $V1[$limit_plus_1 + $k] ) ) { $x = $V1[$limit_min_1 + $k]; } else { $x = $V1[$limit_plus_1 + $k] - 1; } $y = $x - $k - $delta; $snake2 = 0; while ( $x > 0 && $y > 0 && $from[$x + $bottoml1_min_1] === $to[$y + $bottoml2_min_1] ) { --$x; --$y; ++$snake2; } $V1[$limit + $k] = $x; if ( $k >= -$delta - $d && $k <= $d - $delta && $x <= $V0[$limit + $k + $delta] ) { $snake0 = $bottoml1 + $x; $snake1 = $bottoml2 + $y; return 2 * $d; } // check to see if we can cut down our diagonal range if ( $x <= 0 ) { $start_backward = $k + 1; $value_to_add_backward = 0; } elseif ( $y <= 0 && $end_backward > $k - 1 ) { $end_backward = $k - 1; } } } } /* * computing the true LCS is too expensive, instead find the diagonal * with the most progress and pretend a middle snake of length 0 occurs * there. */ $most_progress = self::findMostProgress( $M, $N, $limit, $V ); $snake0 = $bottoml1 + $most_progress[0]; $snake1 = $bottoml2 + $most_progress[1]; $snake2 = 0; // Computing the LCS is too expensive. Using a heuristic. $this->heuristicUsed = true; return 5; /* * HACK: since we didn't really finish the LCS computation * we don't really know the length of the SES. We don't do * anything with the result anyway, unless it's <=1. We know * for a fact SES > 1 so 5 is as good a number as any to * return here */ } /** * @param int $M * @param int $N * @param int $limit * @param array $V * @return array */ private static function findMostProgress( $M, $N, $limit, $V ) { $delta = $N - $M; if ( ( $M & 1 ) == ( $limit & 1 ) ) { $forward_start_diag = max( -$M, -$limit ); } else { $forward_start_diag = max( 1 - $M, -$limit ); } $forward_end_diag = min( $N, $limit ); if ( ( $N & 1 ) == ( $limit & 1 ) ) { $backward_start_diag = max( -$N, -$limit ); } else { $backward_start_diag = max( 1 - $N, -$limit ); } $backward_end_diag = -min( $M, $limit ); $temp = [ 0, 0, 0 ]; $max_progress = array_fill( 0, ceil( max( $forward_end_diag - $forward_start_diag, $backward_end_diag - $backward_start_diag ) / 2 ), $temp ); $num_progress = 0; // the 1st entry is current, it is initialized // with 0s // first search the forward diagonals for ( $k = $forward_start_diag; $k <= $forward_end_diag; $k += 2 ) { $x = $V[0][$limit + $k]; $y = $x - $k; if ( $x > $N || $y > $M ) { continue; } $progress = $x + $y; if ( $progress > $max_progress[0][2] ) { $num_progress = 0; $max_progress[0][0] = $x; $max_progress[0][1] = $y; $max_progress[0][2] = $progress; } elseif ( $progress == $max_progress[0][2] ) { ++$num_progress; $max_progress[$num_progress][0] = $x; $max_progress[$num_progress][1] = $y; $max_progress[$num_progress][2] = $progress; } } $max_progress_forward = true; // initially the maximum // progress is in the forward // direction // now search the backward diagonals for ( $k = $backward_start_diag; $k <= $backward_end_diag; $k += 2 ) { $x = $V[1][$limit + $k]; $y = $x - $k - $delta; if ( $x < 0 || $y < 0 ) { continue; } $progress = $N - $x + $M - $y; if ( $progress > $max_progress[0][2] ) { $num_progress = 0; $max_progress_forward = false; $max_progress[0][0] = $x; $max_progress[0][1] = $y; $max_progress[0][2] = $progress; } elseif ( $progress == $max_progress[0][2] && !$max_progress_forward ) { ++$num_progress; $max_progress[$num_progress][0] = $x; $max_progress[$num_progress][1] = $y; $max_progress[$num_progress][2] = $progress; } } // return the middle diagonal with maximal progress. return $max_progress[(int)floor( $num_progress / 2 )]; } /** * @return int */ public function getLcsLength() { if ( $this->heuristicUsed && !$this->lcsLengthCorrectedForHeuristic ) { $this->lcsLengthCorrectedForHeuristic = true; $this->length = $this->m - array_sum( $this->added ); } return $this->length; } } /** @deprecated class alias since 1.41 */ class_alias( DiffEngine::class, 'DiffEngine' ); PK ! � � 9 9 Diff/DiffOpDelete.phpnu �Iw�� <?php /** * A PHP diff engine for phpwiki. (Taken from phpwiki-1.3.3) * * Copyright © 2000, 2001 Geoffrey T. Dairiki <dairiki@dairiki.org> * You may copy this code freely under the conditions of the GPL. * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file * @ingroup DifferenceEngine */ namespace Wikimedia\Diff; /** * Extends DiffOp. Used to mark strings that have been * deleted from the first string array. * * @ingroup DifferenceEngine */ class DiffOpDelete extends DiffOp { /** @inheritDoc */ public $type = 'delete'; /** * @param string[] $lines */ public function __construct( $lines ) { $this->orig = $lines; $this->closing = false; } /** * @return DiffOpAdd */ public function reverse() { return new DiffOpAdd( $this->orig ); } } /** @deprecated class alias since 1.41 */ class_alias( DiffOpDelete::class, 'DiffOpDelete' ); PK ! �ۦ�� � Diff/DiffOpCopy.phpnu �Iw�� <?php /** * A PHP diff engine for phpwiki. (Taken from phpwiki-1.3.3) * * Copyright © 2000, 2001 Geoffrey T. Dairiki <dairiki@dairiki.org> * You may copy this code freely under the conditions of the GPL. * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file * @ingroup DifferenceEngine */ namespace Wikimedia\Diff; /** * Extends DiffOp. Used to mark strings that have been * copied from one string array to the other. * * @ingroup DifferenceEngine */ class DiffOpCopy extends DiffOp { /** @inheritDoc */ public $type = 'copy'; /** * @param string[] $orig * @param string[]|false $closing Should either be identical to $orig, or not given */ public function __construct( $orig, $closing = false ) { if ( !is_array( $closing ) ) { $closing = $orig; } $this->orig = $orig; $this->closing = $closing; } /** * @return DiffOpCopy */ public function reverse() { return new DiffOpCopy( $this->closing, $this->orig ); } } /** @deprecated class alias since 1.41 */ class_alias( DiffOpCopy::class, 'DiffOpCopy' ); PK ! ��{ { UnpackFailedException.phpnu �Iw�� <?php namespace MediaWiki\Libs; use Exception; /** * @since 1.42 */ class UnpackFailedException extends Exception { } PK ! �.�p� � iterators/IteratorDecorator.phpnu �Iw�� <?php /** * Allows extending classes to decorate an Iterator with * reduced boilerplate. * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @stable to extend * @file * @ingroup Maintenance */ abstract class IteratorDecorator implements Iterator { protected Iterator $iterator; /** * @stable to call * * @param Iterator $iterator */ public function __construct( Iterator $iterator ) { $this->iterator = $iterator; } /** * @inheritDoc * @stable to override */ #[\ReturnTypeWillChange] public function current() { return $this->iterator->current(); } /** * @inheritDoc * @stable to override */ #[\ReturnTypeWillChange] public function key() { return $this->iterator->key(); } /** * @inheritDoc * @stable to override */ public function next(): void { $this->iterator->next(); } /** * @inheritDoc * @stable to override */ public function rewind(): void { $this->iterator->rewind(); } /** * @inheritDoc * @stable to override */ public function valid(): bool { return $this->iterator->valid(); } } PK ! ��2 " iterators/NotRecursiveIterator.phpnu �Iw�� <?php /** * Wraps a non-recursive iterator with methods to be recursive * without children. * * Alternatively wraps a recursive iterator to prevent recursing deeper * than the wrapped iterator. * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file * @ingroup Maintenance */ class NotRecursiveIterator extends IteratorDecorator implements RecursiveIterator { public function hasChildren(): bool { return false; } public function getChildren(): ?RecursiveIterator { // @phan-suppress-next-line PhanTypeMismatchReturnProbablyReal False positive return null; } } PK ! E2 2 DnsSrvDiscoverer.phpnu �Iw�� <?php /** * Service discovery using DNS SRV records * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ /** * @since 1.29 */ class DnsSrvDiscoverer { /** * @var string */ private $service; /** * @var string */ private $protocol; /** * @var string|null */ private $domain; /** * @var callable */ private $resolver; /** * Construct a new discoverer for the given domain, service, and protocol. * * @param string $service Name of the service to discover. * @param string $protocol Service protocol. Defaults to 'tcp' * @param ?string $domain The hostname/domain on which to perform discovery * of the given service and protocol. Defaults to null which effectively * performs a query relative to the host's configured search domain. * @param ?callable $resolver Resolver function. Defaults to using * dns_get_record. Primarily useful in testing. */ public function __construct( string $service, string $protocol = 'tcp', ?string $domain = null, ?callable $resolver = null ) { $this->service = $service; $this->protocol = $protocol; $this->domain = $domain; $this->resolver = $resolver ?? static function ( $srv ) { return dns_get_record( $srv, DNS_SRV ); }; } /** * Queries the resolver for an SRV resource record matching the service, * protocol, and domain and returns all target/port/priority/weight * records. * * @return array */ public function getRecords() { $result = []; $records = ( $this->resolver )( $this->getSrvName() ); // Respect RFC 2782 with regard to a single '.' entry denoting a valid // empty response if ( !$records || ( count( $records ) === 1 && $records[0]['target'] === '.' ) ) { return $result; } foreach ( $records as $record ) { $result[] = [ 'target' => $record['target'], 'port' => (int)$record['port'], 'pri' => (int)$record['pri'], 'weight' => (int)$record['weight'], ]; } return $result; } /** * Performs discovery for the domain, service, and protocol, and returns a * list of resolved server name/ip and port number pairs sorted by each * record's priority, with servers of the same priority randomly shuffled. * * @return array */ public function getServers() { $records = $this->getRecords(); usort( $records, static function ( $a, $b ) { if ( $a['pri'] === $b['pri'] ) { return mt_rand( 0, 1 ) ? 1 : -1; } return $a['pri'] - $b['pri']; } ); $serversAndPorts = []; foreach ( $records as $record ) { $serversAndPorts[] = [ $record['target'], $record['port'] ]; } return $serversAndPorts; } /** * Returns the SRV resource record name. * * @return string */ public function getSrvName(): string { $srv = "_{$this->service}._{$this->protocol}"; if ( $this->domain === null || $this->domain === '' ) { return $srv; } return "$srv.{$this->domain}"; } } PK ! W�� � READMEnu �Iw�� The classes in this directory ./includes/libs are considered standalone from the remainder of the MediaWiki codebase. They do not call on any other portions of MediaWiki code, and can be used in other projects without dependency issues. PK ! b ��W W ! eventrelayer/EventRelayerNull.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\EventRelayer; /** * No-op class for publishing messages into a PubSub system */ class EventRelayerNull extends EventRelayer { public function doNotify( $channel, array $events ) { return true; } } /** @deprecated class alias since 1.41 */ class_alias( EventRelayerNull::class, 'EventRelayerNull' ); PK ! �ͨb� � " eventrelayer/EventRelayerGroup.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\EventRelayer; use UnexpectedValueException; /** * Factory class for spawning EventRelayer objects using configuration * * @since 1.27 */ class EventRelayerGroup { /** @var array[] */ protected $configByChannel = []; /** @var EventRelayer[] */ protected $relayers = []; /** * @param array[] $config Channel configuration */ public function __construct( array $config ) { $this->configByChannel = $config; } /** * @param string $channel * @return EventRelayer Relayer instance that handles the given channel */ public function getRelayer( $channel ) { $channelKey = isset( $this->configByChannel[$channel] ) ? $channel : 'default'; if ( !isset( $this->relayers[$channelKey] ) ) { if ( !isset( $this->configByChannel[$channelKey] ) ) { throw new UnexpectedValueException( "No config for '$channelKey'" ); } $config = $this->configByChannel[$channelKey]; $class = $config['class']; $this->relayers[$channelKey] = new $class( $config ); } return $this->relayers[$channelKey]; } } /** @deprecated class alias since 1.41 */ class_alias( EventRelayerGroup::class, 'EventRelayerGroup' ); PK ! �}�� � eventrelayer/EventRelayer.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\EventRelayer; use Psr\Log\LoggerAwareInterface; use Psr\Log\LoggerInterface; use Psr\Log\NullLogger; /** * Base class for reliable event relays * * @stable to extend */ abstract class EventRelayer implements LoggerAwareInterface { /** @var LoggerInterface */ protected $logger; /** * @stable to call * * @param array $params */ public function __construct( array $params ) { $this->logger = new NullLogger(); } /** * @param string $channel * @param array $event Event data map * @return bool Success */ final public function notify( $channel, $event ) { return $this->doNotify( $channel, [ $event ] ); } /** * @param string $channel * @param array $events List of event data maps * @return bool Success */ final public function notifyMulti( $channel, $events ) { return $this->doNotify( $channel, $events ); } public function setLogger( LoggerInterface $logger ) { $this->logger = $logger; } /** * @param string $channel * @param array $events List of event data maps * @return bool Success */ abstract protected function doNotify( $channel, array $events ); } /** @deprecated class alias since 1.41 */ class_alias( EventRelayer::class, 'EventRelayer' ); PK ! ��u u RiffExtractor.phpnu �Iw�� <?php /** * Extractor for the Resource Interchange File Format * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file * @author Bryan Tong Minh * @ingroup Media */ class RiffExtractor { public static function findChunksFromFile( $filename, $maxChunks = -1 ) { $file = fopen( $filename, 'rb' ); $info = self::findChunks( $file, $maxChunks ); fclose( $file ); return $info; } public static function findChunks( $file, $maxChunks = -1 ) { $riff = fread( $file, 4 ); if ( $riff !== 'RIFF' ) { return false; } // Next four bytes are fileSize $fileSize = fread( $file, 4 ); if ( !$fileSize || strlen( $fileSize ) != 4 ) { return false; } // Next four bytes are the FourCC $fourCC = fread( $file, 4 ); if ( !$fourCC || strlen( $fourCC ) != 4 ) { return false; } // Create basic info structure $info = [ 'fileSize' => self::extractUInt32( $fileSize ), 'fourCC' => $fourCC, 'chunks' => [], ]; $numberOfChunks = 0; // Find out the chunks while ( !feof( $file ) && !( $numberOfChunks >= $maxChunks && $maxChunks >= 0 ) ) { $chunkStart = ftell( $file ); $chunkFourCC = fread( $file, 4 ); if ( !$chunkFourCC || strlen( $chunkFourCC ) != 4 ) { return $info; } $chunkSize = fread( $file, 4 ); if ( !$chunkSize || strlen( $chunkSize ) != 4 ) { return $info; } $intChunkSize = self::extractUInt32( $chunkSize ); // Add chunk info to the info structure $info['chunks'][] = [ 'fourCC' => $chunkFourCC, 'start' => $chunkStart, 'size' => $intChunkSize ]; // Uneven chunks have padding bytes $padding = $intChunkSize % 2; // Seek to the next chunk fseek( $file, $intChunkSize + $padding, SEEK_CUR ); } return $info; } /** * Extract a little-endian uint32 from a 4 byte string * @param string $string 4-byte string * @return int */ public static function extractUInt32( $string ) { return unpack( 'V', $string )[1]; } } PK ! ۧ(� � Cookie.phpnu �Iw�� <?php /** * Cookie for HTTP requests. * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file * @ingroup HTTP */ class Cookie { /** @var string */ protected $name; /** @var string */ protected $value; /** @var int|false */ protected $expires; /** @var string|null */ protected $path; /** @var string|null */ protected $domain; /** @var bool */ protected $isSessionKey = true; // TO IMPLEMENT protected $secure // TO IMPLEMENT? protected $maxAge (add onto expires) // TO IMPLEMENT? protected $version // TO IMPLEMENT? protected $comment public function __construct( $name, $value, $attr ) { $this->name = $name; $this->set( $value, $attr ); } /** * Sets a cookie. Used before a request to set up any individual * cookies. Used internally after a request to parse the * Set-Cookie headers. * * @param string $value The value of the cookie * @param array $attr Possible key/values: * expires A date string * path The path this cookie is used on * domain Domain this cookie is used on */ public function set( $value, $attr ) { $this->value = $value; if ( isset( $attr['expires'] ) ) { $this->isSessionKey = false; $this->expires = strtotime( $attr['expires'] ); } $this->path = $attr['path'] ?? '/'; if ( isset( $attr['domain'] ) ) { if ( self::validateCookieDomain( $attr['domain'] ) ) { $this->domain = $attr['domain']; } } else { throw new InvalidArgumentException( '$attr must contain a domain' ); } } /** * Return the true if the cookie is valid is valid. Otherwise, * false. The uses a method similar to IE cookie security * described here: * http://kuza55.blogspot.com/2008/02/understanding-cookie-security.html * A better method might be to use a list like * http://publicsuffix.org/ * * @todo fixme fails to detect 3-letter top-level domains * @todo fixme fails to detect 2-letter top-level domains for single-domain use (probably * not a big problem in practice, but there are test cases) * * @param string $domain The domain to validate * @param string|null $originDomain (optional) the domain the cookie originates from * @return bool */ public static function validateCookieDomain( $domain, $originDomain = null ) { $dc = explode( ".", $domain ); // Don't allow a trailing dot or addresses without a or just a leading dot if ( substr( $domain, -1 ) == '.' || count( $dc ) <= 1 || ( count( $dc ) == 2 && $dc[0] === '' ) ) { return false; } // Only allow full, valid IP addresses if ( preg_match( '/^[0-9.]+$/', $domain ) ) { if ( count( $dc ) !== 4 || ip2long( $domain ) === false ) { return false; } if ( $originDomain == null || $originDomain == $domain ) { return true; } } // Don't allow cookies for "co.uk" or "gov.uk", etc, but allow "supermarket.uk" if ( strrpos( $domain, "." ) - strlen( $domain ) == -3 ) { if ( ( count( $dc ) == 2 && strlen( $dc[0] ) <= 2 ) || ( count( $dc ) == 3 && strlen( $dc[0] ) == 0 && strlen( $dc[1] ) <= 2 ) ) { return false; } if ( ( count( $dc ) == 2 || ( count( $dc ) == 3 && $dc[0] == '' ) ) && preg_match( '/(com|net|org|gov|edu)\...$/', $domain ) ) { return false; } } if ( $originDomain != null ) { if ( substr( $domain, 0, 1 ) != '.' && $domain != $originDomain ) { return false; } if ( substr( $domain, 0, 1 ) == '.' && substr_compare( $originDomain, $domain, -strlen( $domain ), strlen( $domain ), true ) != 0 ) { return false; } } return true; } /** * Serialize the cookie jar into a format useful for HTTP Request headers. * * @param string $path The path that will be used. Required. * @param string $domain The domain that will be used. Required. * @return string */ public function serializeToHttpRequest( $path, $domain ) { $ret = ''; if ( $this->canServeDomain( $domain ) && $this->canServePath( $path ) && $this->isUnExpired() ) { $ret = $this->name . '=' . $this->value; } return $ret; } /** * @param string $domain * @return bool */ protected function canServeDomain( $domain ) { if ( $domain == $this->domain || ( strlen( $domain ) > strlen( $this->domain ) && str_starts_with( $this->domain, '.' ) && substr_compare( $domain, $this->domain, -strlen( $this->domain ), strlen( $this->domain ), true ) == 0 ) ) { return true; } return false; } /** * @param string $path * @return bool */ protected function canServePath( $path ) { return ( $this->path && substr_compare( $this->path, $path, 0, strlen( $this->path ) ) == 0 ); } /** * @return bool */ protected function isUnExpired() { return $this->isSessionKey || $this->expires > time(); } } PK ! �>�H filebackend/FileBackendStore.phpnu �Iw�� <?php /** * Base class for all backends using particular storage medium. * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file * @ingroup FileBackend */ namespace Wikimedia\FileBackend; use InvalidArgumentException; use LockManager; use MapCacheLRU; use MediaWiki\Json\FormatJson; use Shellbox\Command\BoxedCommand; use StatusValue; use Traversable; use Wikimedia\AtEase\AtEase; use Wikimedia\FileBackend\FileIteration\FileBackendStoreShardDirIterator; use Wikimedia\FileBackend\FileIteration\FileBackendStoreShardFileIterator; use Wikimedia\FileBackend\FileOpHandle\FileBackendStoreOpHandle; use Wikimedia\FileBackend\FileOps\CopyFileOp; use Wikimedia\FileBackend\FileOps\CreateFileOp; use Wikimedia\FileBackend\FileOps\DeleteFileOp; use Wikimedia\FileBackend\FileOps\DescribeFileOp; use Wikimedia\FileBackend\FileOps\FileOp; use Wikimedia\FileBackend\FileOps\MoveFileOp; use Wikimedia\FileBackend\FileOps\NullFileOp; use Wikimedia\FileBackend\FileOps\StoreFileOp; use Wikimedia\FileBackend\FSFile\FSFile; use Wikimedia\ObjectCache\BagOStuff; use Wikimedia\ObjectCache\EmptyBagOStuff; use Wikimedia\ObjectCache\WANObjectCache; use Wikimedia\Timestamp\ConvertibleTimestamp; /** * @brief Base class for all backends using particular storage medium. * * This class defines the methods as abstract that subclasses must implement. * Outside callers should *not* use functions with "Internal" in the name. * * The FileBackend operations are implemented using basic functions * such as storeInternal(), copyInternal(), deleteInternal() and the like. * This class is also responsible for path resolution and sanitization. * * @stable to extend * @ingroup FileBackend * @since 1.19 */ abstract class FileBackendStore extends FileBackend { /** @var WANObjectCache */ protected $memCache; /** @var BagOStuff */ protected $srvCache; /** @var MapCacheLRU Map of paths to small (RAM/disk) cache items */ protected $cheapCache; /** @var MapCacheLRU Map of paths to large (RAM/disk) cache items */ protected $expensiveCache; /** @var array<string,array> Map of container names to sharding config */ protected $shardViaHashLevels = []; /** @var callable|null Method to get the MIME type of files */ protected $mimeCallback; /** @var int Size in bytes, defaults to 32 GiB */ protected $maxFileSize = 32 * 1024 * 1024 * 1024; protected const CACHE_TTL = 10; // integer; TTL in seconds for process cache entries protected const CACHE_CHEAP_SIZE = 500; // integer; max entries in "cheap cache" protected const CACHE_EXPENSIVE_SIZE = 5; // integer; max entries in "expensive cache" /** @var false Idiom for "no result due to missing file" (since 1.34) */ protected const RES_ABSENT = false; /** @var null Idiom for "no result due to I/O errors" (since 1.34) */ protected const RES_ERROR = null; /** @var string File does not exist according to a normal stat query */ protected const ABSENT_NORMAL = 'FNE-N'; /** @var string File does not exist according to a "latest"-mode stat query */ protected const ABSENT_LATEST = 'FNE-L'; /** * @see FileBackend::__construct() * Additional $config params include: * - srvCache : BagOStuff cache to APC or the like. * - wanCache : WANObjectCache object to use for persistent caching. * - mimeCallback : Callback that takes (storage path, content, file system path) and * returns the MIME type of the file or 'unknown/unknown'. The file * system path parameter should be used if the content one is null. * * @stable to call * * @param array $config */ public function __construct( array $config ) { parent::__construct( $config ); $this->mimeCallback = $config['mimeCallback'] ?? null; $this->srvCache = new EmptyBagOStuff(); // disabled by default $this->memCache = WANObjectCache::newEmpty(); // disabled by default $this->cheapCache = new MapCacheLRU( self::CACHE_CHEAP_SIZE ); $this->expensiveCache = new MapCacheLRU( self::CACHE_EXPENSIVE_SIZE ); } /** * Get the maximum allowable file size given backend * medium restrictions and basic performance constraints. * Do not call this function from places outside FileBackend and FileOp. * * @return int Bytes */ final public function maxFileSizeInternal() { return min( $this->maxFileSize, PHP_INT_MAX ); } /** * Check if a file can be created or changed at a given storage path in the backend * * FS backends should check that the parent directory exists, files can be written * under it, and that any file already there is both readable and writable. * Backends using key/value stores should check if the container exists. * * @param string $storagePath * @return bool */ abstract public function isPathUsableInternal( $storagePath ); /** * Create a file in the backend with the given contents. * This will overwrite any file that exists at the destination. * Do not call this function from places outside FileBackend and FileOp. * * $params include: * - content : the raw file contents * - dst : destination storage path * - headers : HTTP header name/value map * - async : StatusValue will be returned immediately if supported. * If the StatusValue is OK, then its value field will be * set to a FileBackendStoreOpHandle object. * - dstExists : Whether a file exists at the destination (optimization). * Callers can use "false" if no existing file is being changed. * * @param array $params * @return StatusValue */ final public function createInternal( array $params ) { /** @noinspection PhpUnusedLocalVariableInspection */ $ps = $this->scopedProfileSection( __METHOD__ . "-{$this->name}" ); if ( strlen( $params['content'] ) > $this->maxFileSizeInternal() ) { $status = $this->newStatus( 'backend-fail-maxsize', $params['dst'], $this->maxFileSizeInternal() ); } else { $status = $this->doCreateInternal( $params ); $this->clearCache( [ $params['dst'] ] ); if ( $params['dstExists'] ?? true ) { $this->deleteFileCache( $params['dst'] ); // persistent cache } } return $status; } /** * @see FileBackendStore::createInternal() * @param array $params * @return StatusValue */ abstract protected function doCreateInternal( array $params ); /** * Store a file into the backend from a file on disk. * This will overwrite any file that exists at the destination. * Do not call this function from places outside FileBackend and FileOp. * * $params include: * - src : source path on disk * - dst : destination storage path * - headers : HTTP header name/value map * - async : StatusValue will be returned immediately if supported. * If the StatusValue is OK, then its value field will be * set to a FileBackendStoreOpHandle object. * - dstExists : Whether a file exists at the destination (optimization). * Callers can use "false" if no existing file is being changed. * * @param array $params * @return StatusValue */ final public function storeInternal( array $params ) { /** @noinspection PhpUnusedLocalVariableInspection */ $ps = $this->scopedProfileSection( __METHOD__ . "-{$this->name}" ); if ( filesize( $params['src'] ) > $this->maxFileSizeInternal() ) { $status = $this->newStatus( 'backend-fail-maxsize', $params['dst'], $this->maxFileSizeInternal() ); } else { $status = $this->doStoreInternal( $params ); $this->clearCache( [ $params['dst'] ] ); if ( $params['dstExists'] ?? true ) { $this->deleteFileCache( $params['dst'] ); // persistent cache } } return $status; } /** * @see FileBackendStore::storeInternal() * @param array $params * @return StatusValue */ abstract protected function doStoreInternal( array $params ); /** * Copy a file from one storage path to another in the backend. * This will overwrite any file that exists at the destination. * Do not call this function from places outside FileBackend and FileOp. * * $params include: * - src : source storage path * - dst : destination storage path * - ignoreMissingSource : do nothing if the source file does not exist * - headers : HTTP header name/value map * - async : StatusValue will be returned immediately if supported. * If the StatusValue is OK, then its value field will be * set to a FileBackendStoreOpHandle object. * - dstExists : Whether a file exists at the destination (optimization). * Callers can use "false" if no existing file is being changed. * * @param array $params * @return StatusValue */ final public function copyInternal( array $params ) { /** @noinspection PhpUnusedLocalVariableInspection */ $ps = $this->scopedProfileSection( __METHOD__ . "-{$this->name}" ); $status = $this->doCopyInternal( $params ); $this->clearCache( [ $params['dst'] ] ); if ( $params['dstExists'] ?? true ) { $this->deleteFileCache( $params['dst'] ); // persistent cache } return $status; } /** * @see FileBackendStore::copyInternal() * @param array $params * @return StatusValue */ abstract protected function doCopyInternal( array $params ); /** * Delete a file at the storage path. * Do not call this function from places outside FileBackend and FileOp. * * $params include: * - src : source storage path * - ignoreMissingSource : do nothing if the source file does not exist * - async : StatusValue will be returned immediately if supported. * If the StatusValue is OK, then its value field will be * set to a FileBackendStoreOpHandle object. * * @param array $params * @return StatusValue */ final public function deleteInternal( array $params ) { /** @noinspection PhpUnusedLocalVariableInspection */ $ps = $this->scopedProfileSection( __METHOD__ . "-{$this->name}" ); $status = $this->doDeleteInternal( $params ); $this->clearCache( [ $params['src'] ] ); $this->deleteFileCache( $params['src'] ); // persistent cache return $status; } /** * @see FileBackendStore::deleteInternal() * @param array $params * @return StatusValue */ abstract protected function doDeleteInternal( array $params ); /** * Move a file from one storage path to another in the backend. * This will overwrite any file that exists at the destination. * Do not call this function from places outside FileBackend and FileOp. * * $params include: * - src : source storage path * - dst : destination storage path * - ignoreMissingSource : do nothing if the source file does not exist * - headers : HTTP header name/value map * - async : StatusValue will be returned immediately if supported. * If the StatusValue is OK, then its value field will be * set to a FileBackendStoreOpHandle object. * - dstExists : Whether a file exists at the destination (optimization). * Callers can use "false" if no existing file is being changed. * * @param array $params * @return StatusValue */ final public function moveInternal( array $params ) { /** @noinspection PhpUnusedLocalVariableInspection */ $ps = $this->scopedProfileSection( __METHOD__ . "-{$this->name}" ); $status = $this->doMoveInternal( $params ); $this->clearCache( [ $params['src'], $params['dst'] ] ); $this->deleteFileCache( $params['src'] ); // persistent cache if ( $params['dstExists'] ?? true ) { $this->deleteFileCache( $params['dst'] ); // persistent cache } return $status; } /** * @see FileBackendStore::moveInternal() * @param array $params * @return StatusValue */ abstract protected function doMoveInternal( array $params ); /** * Alter metadata for a file at the storage path. * Do not call this function from places outside FileBackend and FileOp. * * $params include: * - src : source storage path * - headers : HTTP header name/value map * - async : StatusValue will be returned immediately if supported. * If the StatusValue is OK, then its value field will be * set to a FileBackendStoreOpHandle object. * * @param array $params * @return StatusValue */ final public function describeInternal( array $params ) { /** @noinspection PhpUnusedLocalVariableInspection */ $ps = $this->scopedProfileSection( __METHOD__ . "-{$this->name}" ); if ( count( $params['headers'] ) ) { $status = $this->doDescribeInternal( $params ); $this->clearCache( [ $params['src'] ] ); $this->deleteFileCache( $params['src'] ); // persistent cache } else { $status = $this->newStatus(); // nothing to do } return $status; } /** * @see FileBackendStore::describeInternal() * @stable to override * @param array $params * @return StatusValue */ protected function doDescribeInternal( array $params ) { return $this->newStatus(); } /** * No-op file operation that does nothing. * Do not call this function from places outside FileBackend and FileOp. * * @param array $params * @return StatusValue */ final public function nullInternal( array $params ) { return $this->newStatus(); } final public function concatenate( array $params ) { /** @noinspection PhpUnusedLocalVariableInspection */ $ps = $this->scopedProfileSection( __METHOD__ . "-{$this->name}" ); $status = $this->newStatus(); // Try to lock the source files for the scope of this function /** @noinspection PhpUnusedLocalVariableInspection */ $scopeLockS = $this->getScopedFileLocks( $params['srcs'], LockManager::LOCK_UW, $status ); if ( $status->isOK() ) { // Actually do the file concatenation... $start_time = microtime( true ); $status->merge( $this->doConcatenate( $params ) ); $sec = microtime( true ) - $start_time; if ( !$status->isOK() ) { $this->logger->error( static::class . "-{$this->name}" . " failed to concatenate " . count( $params['srcs'] ) . " file(s) [$sec sec]" ); } } return $status; } /** * @see FileBackendStore::concatenate() * @stable to override * @param array $params * @return StatusValue */ protected function doConcatenate( array $params ) { $status = $this->newStatus(); $tmpPath = $params['dst']; unset( $params['latest'] ); // Check that the specified temp file is valid... AtEase::suppressWarnings(); $ok = ( is_file( $tmpPath ) && filesize( $tmpPath ) == 0 ); AtEase::restoreWarnings(); if ( !$ok ) { // not present or not empty $status->fatal( 'backend-fail-opentemp', $tmpPath ); return $status; } // Get local FS versions of the chunks needed for the concatenation... $fsFiles = $this->getLocalReferenceMulti( $params ); foreach ( $fsFiles as $path => &$fsFile ) { if ( !$fsFile ) { // chunk failed to download? $fsFile = $this->getLocalReference( [ 'src' => $path ] ); if ( !$fsFile ) { // retry failed? $status->fatal( $fsFile === self::RES_ERROR ? 'backend-fail-read' : 'backend-fail-notexists', $path ); return $status; } } } unset( $fsFile ); // unset reference so we can reuse $fsFile // Get a handle for the destination temp file $tmpHandle = fopen( $tmpPath, 'ab' ); if ( $tmpHandle === false ) { $status->fatal( 'backend-fail-opentemp', $tmpPath ); return $status; } // Build up the temp file using the source chunks (in order)... foreach ( $fsFiles as $virtualSource => $fsFile ) { // Get a handle to the local FS version $sourceHandle = fopen( $fsFile->getPath(), 'rb' ); if ( $sourceHandle === false ) { fclose( $tmpHandle ); $status->fatal( 'backend-fail-read', $virtualSource ); return $status; } // Append chunk to file (pass chunk size to avoid magic quotes) if ( !stream_copy_to_stream( $sourceHandle, $tmpHandle ) ) { fclose( $sourceHandle ); fclose( $tmpHandle ); $status->fatal( 'backend-fail-writetemp', $tmpPath ); return $status; } fclose( $sourceHandle ); } if ( !fclose( $tmpHandle ) ) { $status->fatal( 'backend-fail-closetemp', $tmpPath ); return $status; } clearstatcache(); // temp file changed return $status; } /** * @inheritDoc */ final protected function doPrepare( array $params ) { /** @noinspection PhpUnusedLocalVariableInspection */ $ps = $this->scopedProfileSection( __METHOD__ . "-{$this->name}" ); $status = $this->newStatus(); [ $fullCont, $dir, $shard ] = $this->resolveStoragePath( $params['dir'] ); if ( $dir === null ) { $status->fatal( 'backend-fail-invalidpath', $params['dir'] ); return $status; // invalid storage path } if ( $shard !== null ) { // confined to a single container/shard $status->merge( $this->doPrepareInternal( $fullCont, $dir, $params ) ); } else { // directory is on several shards $this->logger->debug( __METHOD__ . ": iterating over all container shards." ); [ , $shortCont, ] = self::splitStoragePath( $params['dir'] ); foreach ( $this->getContainerSuffixes( $shortCont ) as $suffix ) { $status->merge( $this->doPrepareInternal( "{$fullCont}{$suffix}", $dir, $params ) ); } } return $status; } /** * @see FileBackendStore::doPrepare() * @stable to override * @param string $container * @param string $dir * @param array $params * @return StatusValue Good status without value for success, fatal otherwise. */ protected function doPrepareInternal( $container, $dir, array $params ) { return $this->newStatus(); } final protected function doSecure( array $params ) { /** @noinspection PhpUnusedLocalVariableInspection */ $ps = $this->scopedProfileSection( __METHOD__ . "-{$this->name}" ); $status = $this->newStatus(); [ $fullCont, $dir, $shard ] = $this->resolveStoragePath( $params['dir'] ); if ( $dir === null ) { $status->fatal( 'backend-fail-invalidpath', $params['dir'] ); return $status; // invalid storage path } if ( $shard !== null ) { // confined to a single container/shard $status->merge( $this->doSecureInternal( $fullCont, $dir, $params ) ); } else { // directory is on several shards $this->logger->debug( __METHOD__ . ": iterating over all container shards." ); [ , $shortCont, ] = self::splitStoragePath( $params['dir'] ); foreach ( $this->getContainerSuffixes( $shortCont ) as $suffix ) { $status->merge( $this->doSecureInternal( "{$fullCont}{$suffix}", $dir, $params ) ); } } return $status; } /** * @see FileBackendStore::doSecure() * @stable to override * @param string $container * @param string $dir * @param array $params * @return StatusValue Good status without value for success, fatal otherwise. */ protected function doSecureInternal( $container, $dir, array $params ) { return $this->newStatus(); } final protected function doPublish( array $params ) { /** @noinspection PhpUnusedLocalVariableInspection */ $ps = $this->scopedProfileSection( __METHOD__ . "-{$this->name}" ); $status = $this->newStatus(); [ $fullCont, $dir, $shard ] = $this->resolveStoragePath( $params['dir'] ); if ( $dir === null ) { $status->fatal( 'backend-fail-invalidpath', $params['dir'] ); return $status; // invalid storage path } if ( $shard !== null ) { // confined to a single container/shard $status->merge( $this->doPublishInternal( $fullCont, $dir, $params ) ); } else { // directory is on several shards $this->logger->debug( __METHOD__ . ": iterating over all container shards." ); [ , $shortCont, ] = self::splitStoragePath( $params['dir'] ); foreach ( $this->getContainerSuffixes( $shortCont ) as $suffix ) { $status->merge( $this->doPublishInternal( "{$fullCont}{$suffix}", $dir, $params ) ); } } return $status; } /** * @see FileBackendStore::doPublish() * @stable to override * @param string $container * @param string $dir * @param array $params * @return StatusValue */ protected function doPublishInternal( $container, $dir, array $params ) { return $this->newStatus(); } final protected function doClean( array $params ) { /** @noinspection PhpUnusedLocalVariableInspection */ $ps = $this->scopedProfileSection( __METHOD__ . "-{$this->name}" ); $status = $this->newStatus(); // Recursive: first delete all empty subdirs recursively if ( !empty( $params['recursive'] ) && !$this->directoriesAreVirtual() ) { $subDirsRel = $this->getTopDirectoryList( [ 'dir' => $params['dir'] ] ); if ( $subDirsRel !== null ) { // no errors foreach ( $subDirsRel as $subDirRel ) { $subDir = $params['dir'] . "/{$subDirRel}"; // full path $status->merge( $this->doClean( [ 'dir' => $subDir ] + $params ) ); } unset( $subDirsRel ); // free directory for rmdir() on Windows (for FS backends) } } [ $fullCont, $dir, $shard ] = $this->resolveStoragePath( $params['dir'] ); if ( $dir === null ) { $status->fatal( 'backend-fail-invalidpath', $params['dir'] ); return $status; // invalid storage path } // Attempt to lock this directory... $filesLockEx = [ $params['dir'] ]; /** @noinspection PhpUnusedLocalVariableInspection */ $scopedLockE = $this->getScopedFileLocks( $filesLockEx, LockManager::LOCK_EX, $status ); if ( !$status->isOK() ) { return $status; // abort } if ( $shard !== null ) { // confined to a single container/shard $status->merge( $this->doCleanInternal( $fullCont, $dir, $params ) ); $this->deleteContainerCache( $fullCont ); // purge cache } else { // directory is on several shards $this->logger->debug( __METHOD__ . ": iterating over all container shards." ); [ , $shortCont, ] = self::splitStoragePath( $params['dir'] ); foreach ( $this->getContainerSuffixes( $shortCont ) as $suffix ) { $status->merge( $this->doCleanInternal( "{$fullCont}{$suffix}", $dir, $params ) ); $this->deleteContainerCache( "{$fullCont}{$suffix}" ); // purge cache } } return $status; } /** * @see FileBackendStore::doClean() * @stable to override * @param string $container * @param string $dir * @param array $params * @return StatusValue */ protected function doCleanInternal( $container, $dir, array $params ) { return $this->newStatus(); } final public function fileExists( array $params ) { /** @noinspection PhpUnusedLocalVariableInspection */ $ps = $this->scopedProfileSection( __METHOD__ . "-{$this->name}" ); $stat = $this->getFileStat( $params ); if ( is_array( $stat ) ) { return true; } return $stat === self::RES_ABSENT ? false : self::EXISTENCE_ERROR; } final public function getFileTimestamp( array $params ) { /** @noinspection PhpUnusedLocalVariableInspection */ $ps = $this->scopedProfileSection( __METHOD__ . "-{$this->name}" ); $stat = $this->getFileStat( $params ); if ( is_array( $stat ) ) { return $stat['mtime']; } return self::TIMESTAMP_FAIL; // all failure cases } final public function getFileSize( array $params ) { /** @noinspection PhpUnusedLocalVariableInspection */ $ps = $this->scopedProfileSection( __METHOD__ . "-{$this->name}" ); $stat = $this->getFileStat( $params ); if ( is_array( $stat ) ) { return $stat['size']; } return self::SIZE_FAIL; // all failure cases } final public function getFileStat( array $params ) { /** @noinspection PhpUnusedLocalVariableInspection */ $ps = $this->scopedProfileSection( __METHOD__ . "-{$this->name}" ); $path = self::normalizeStoragePath( $params['src'] ); if ( $path === null ) { return self::STAT_ERROR; // invalid storage path } // Whether to bypass cache except for process cache entries loaded directly from // high consistency backend queries (caller handles any cache flushing and locking) $latest = !empty( $params['latest'] ); // Whether to ignore cache entries missing the SHA-1 field for existing files $requireSHA1 = !empty( $params['requireSHA1'] ); $stat = $this->cheapCache->getField( $path, 'stat', self::CACHE_TTL ); // Load the persistent stat cache into process cache if needed if ( !$latest ) { if ( // File stat is not in process cache $stat === null || // Key/value store backends might opportunistically set file stat process // cache entries from object listings that do not include the SHA-1. In that // case, loading the persistent stat cache will likely yield the SHA-1. ( $requireSHA1 && is_array( $stat ) && !isset( $stat['sha1'] ) ) ) { $this->primeFileCache( [ $path ] ); // Get any newly process-cached entry $stat = $this->cheapCache->getField( $path, 'stat', self::CACHE_TTL ); } } if ( is_array( $stat ) ) { if ( ( !$latest || !empty( $stat['latest'] ) ) && ( !$requireSHA1 || isset( $stat['sha1'] ) ) ) { return $stat; } } elseif ( $stat === self::ABSENT_LATEST ) { return self::STAT_ABSENT; } elseif ( $stat === self::ABSENT_NORMAL ) { if ( !$latest ) { return self::STAT_ABSENT; } } // Load the file stat from the backend and update caches $stat = $this->doGetFileStat( $params ); $this->ingestFreshFileStats( [ $path => $stat ], $latest ); if ( is_array( $stat ) ) { return $stat; } return $stat === self::RES_ERROR ? self::STAT_ERROR : self::STAT_ABSENT; } /** * Ingest file stat entries that just came from querying the backend (not cache) * * @param array<string,array|false|null> $stats Map of storage path => {@see doGetFileStat} result * @param bool $latest Whether doGetFileStat()/doGetFileStatMulti() had the 'latest' flag * @return bool Whether all files have non-error stat replies */ final protected function ingestFreshFileStats( array $stats, $latest ) { $success = true; foreach ( $stats as $path => $stat ) { if ( is_array( $stat ) ) { // Strongly consistent backends might automatically set this flag $stat['latest'] ??= $latest; $this->cheapCache->setField( $path, 'stat', $stat ); if ( isset( $stat['sha1'] ) ) { // Some backends store the SHA-1 hash as metadata $this->cheapCache->setField( $path, 'sha1', [ 'hash' => $stat['sha1'], 'latest' => $latest ] ); } if ( isset( $stat['xattr'] ) ) { // Some backends store custom headers/metadata $stat['xattr'] = self::normalizeXAttributes( $stat['xattr'] ); $this->cheapCache->setField( $path, 'xattr', [ 'map' => $stat['xattr'], 'latest' => $latest ] ); } // Update persistent cache (@TODO: set all entries in one batch) $this->setFileCache( $path, $stat ); } elseif ( $stat === self::RES_ABSENT ) { $this->cheapCache->setField( $path, 'stat', $latest ? self::ABSENT_LATEST : self::ABSENT_NORMAL ); $this->cheapCache->setField( $path, 'xattr', [ 'map' => self::XATTRS_FAIL, 'latest' => $latest ] ); $this->cheapCache->setField( $path, 'sha1', [ 'hash' => self::SHA1_FAIL, 'latest' => $latest ] ); $this->logger->debug( __METHOD__ . ': File {path} does not exist', [ 'path' => $path ] ); } else { $success = false; $this->logger->error( __METHOD__ . ': Could not stat file {path}', [ 'path' => $path ] ); } } return $success; } /** * @see FileBackendStore::getFileStat() * @param array $params * @return array|false|null */ abstract protected function doGetFileStat( array $params ); public function getFileContentsMulti( array $params ) { /** @noinspection PhpUnusedLocalVariableInspection */ $ps = $this->scopedProfileSection( __METHOD__ . "-{$this->name}" ); $params = $this->setConcurrencyFlags( $params ); $contents = $this->doGetFileContentsMulti( $params ); foreach ( $contents as $path => $content ) { if ( !is_string( $content ) ) { $contents[$path] = self::CONTENT_FAIL; // used for all failure cases } } return $contents; } /** * @see FileBackendStore::getFileContentsMulti() * @stable to override * @param array $params * @return string[]|bool[]|null[] Map of (path => string, false (missing), or null (error)) */ protected function doGetFileContentsMulti( array $params ) { $contents = []; foreach ( $this->doGetLocalReferenceMulti( $params ) as $path => $fsFile ) { if ( $fsFile instanceof FSFile ) { AtEase::suppressWarnings(); $content = file_get_contents( $fsFile->getPath() ); AtEase::restoreWarnings(); $contents[$path] = is_string( $content ) ? $content : self::RES_ERROR; } else { // self::RES_ERROR or self::RES_ABSENT $contents[$path] = $fsFile; } } return $contents; } final public function getFileXAttributes( array $params ) { /** @noinspection PhpUnusedLocalVariableInspection */ $ps = $this->scopedProfileSection( __METHOD__ . "-{$this->name}" ); $path = self::normalizeStoragePath( $params['src'] ); if ( $path === null ) { return self::XATTRS_FAIL; // invalid storage path } $latest = !empty( $params['latest'] ); // use latest data? if ( $this->cheapCache->hasField( $path, 'xattr', self::CACHE_TTL ) ) { $stat = $this->cheapCache->getField( $path, 'xattr' ); // If we want the latest data, check that this cached // value was in fact fetched with the latest available data. if ( !$latest || $stat['latest'] ) { return $stat['map']; } } $fields = $this->doGetFileXAttributes( $params ); if ( is_array( $fields ) ) { $fields = self::normalizeXAttributes( $fields ); $this->cheapCache->setField( $path, 'xattr', [ 'map' => $fields, 'latest' => $latest ] ); } elseif ( $fields === self::RES_ABSENT ) { $this->cheapCache->setField( $path, 'xattr', [ 'map' => self::XATTRS_FAIL, 'latest' => $latest ] ); } else { $fields = self::XATTRS_FAIL; // used for all failure cases } return $fields; } /** * @see FileBackendStore::getFileXAttributes() * @stable to override * @param array $params * @return array[][]|false|null Attributes, false (missing file), or null (error) */ protected function doGetFileXAttributes( array $params ) { return [ 'headers' => [], 'metadata' => [] ]; // not supported } final public function getFileSha1Base36( array $params ) { /** @noinspection PhpUnusedLocalVariableInspection */ $ps = $this->scopedProfileSection( __METHOD__ . "-{$this->name}" ); $path = self::normalizeStoragePath( $params['src'] ); if ( $path === null ) { return self::SHA1_FAIL; // invalid storage path } $latest = !empty( $params['latest'] ); // use latest data? if ( $this->cheapCache->hasField( $path, 'sha1', self::CACHE_TTL ) ) { $stat = $this->cheapCache->getField( $path, 'sha1' ); // If we want the latest data, check that this cached // value was in fact fetched with the latest available data. if ( !$latest || $stat['latest'] ) { return $stat['hash']; } } $sha1 = $this->doGetFileSha1Base36( $params ); if ( is_string( $sha1 ) ) { $this->cheapCache->setField( $path, 'sha1', [ 'hash' => $sha1, 'latest' => $latest ] ); } elseif ( $sha1 === self::RES_ABSENT ) { $this->cheapCache->setField( $path, 'sha1', [ 'hash' => self::SHA1_FAIL, 'latest' => $latest ] ); } else { $sha1 = self::SHA1_FAIL; // used for all failure cases } return $sha1; } /** * @see FileBackendStore::getFileSha1Base36() * @stable to override * @param array $params * @return bool|string|null SHA1, false (missing file), or null (error) */ protected function doGetFileSha1Base36( array $params ) { $fsFile = $this->getLocalReference( $params ); if ( $fsFile instanceof FSFile ) { $sha1 = $fsFile->getSha1Base36(); return is_string( $sha1 ) ? $sha1 : self::RES_ERROR; } return $fsFile === self::RES_ERROR ? self::RES_ERROR : self::RES_ABSENT; } final public function getFileProps( array $params ) { /** @noinspection PhpUnusedLocalVariableInspection */ $ps = $this->scopedProfileSection( __METHOD__ . "-{$this->name}" ); $fsFile = $this->getLocalReference( $params ); return $fsFile ? $fsFile->getProps() : FSFile::placeholderProps(); } final public function getLocalReferenceMulti( array $params ) { /** @noinspection PhpUnusedLocalVariableInspection */ $ps = $this->scopedProfileSection( __METHOD__ . "-{$this->name}" ); $params = $this->setConcurrencyFlags( $params ); $fsFiles = []; // (path => FSFile) $latest = !empty( $params['latest'] ); // use latest data? // Reuse any files already in process cache... foreach ( $params['srcs'] as $src ) { $path = self::normalizeStoragePath( $src ); if ( $path === null ) { $fsFiles[$src] = self::RES_ERROR; // invalid storage path } elseif ( $this->expensiveCache->hasField( $path, 'localRef' ) ) { $val = $this->expensiveCache->getField( $path, 'localRef' ); // If we want the latest data, check that this cached // value was in fact fetched with the latest available data. if ( !$latest || $val['latest'] ) { $fsFiles[$src] = $val['object']; } } } // Fetch local references of any remaining files... $params['srcs'] = array_diff( $params['srcs'], array_keys( $fsFiles ) ); foreach ( $this->doGetLocalReferenceMulti( $params ) as $path => $fsFile ) { if ( $fsFile instanceof FSFile ) { $fsFiles[$path] = $fsFile; $this->expensiveCache->setField( $path, 'localRef', [ 'object' => $fsFile, 'latest' => $latest ] ); } else { // self::RES_ERROR or self::RES_ABSENT $fsFiles[$path] = $fsFile; } } return $fsFiles; } /** * @see FileBackendStore::getLocalReferenceMulti() * @stable to override * @param array $params * @return string[]|bool[]|null[] Map of (path => FSFile, false (missing), or null (error)) */ protected function doGetLocalReferenceMulti( array $params ) { return $this->doGetLocalCopyMulti( $params ); } final public function getLocalCopyMulti( array $params ) { /** @noinspection PhpUnusedLocalVariableInspection */ $ps = $this->scopedProfileSection( __METHOD__ . "-{$this->name}" ); $params = $this->setConcurrencyFlags( $params ); return $this->doGetLocalCopyMulti( $params ); } /** * @see FileBackendStore::getLocalCopyMulti() * @param array $params * @return string[]|bool[]|null[] Map of (path => TempFSFile, false (missing), or null (error)) */ abstract protected function doGetLocalCopyMulti( array $params ); /** * @see FileBackend::getFileHttpUrl() * @stable to override * @param array $params * @return string|null */ public function getFileHttpUrl( array $params ) { return self::TEMPURL_ERROR; // not supported } public function addShellboxInputFile( BoxedCommand $command, string $boxedName, array $params ) { $ref = $this->getLocalReference( [ 'src' => $params['src'] ] ); if ( $ref === false ) { return $this->newStatus( 'backend-fail-notexists', $params['src'] ); } elseif ( $ref === null ) { return $this->newStatus( 'backend-fail-read', $params['src'] ); } else { $file = $command->newInputFileFromFile( $ref->getPath() ) ->userData( __CLASS__, $ref ); $command->inputFile( $boxedName, $file ); return $this->newStatus(); } } final public function streamFile( array $params ) { /** @noinspection PhpUnusedLocalVariableInspection */ $ps = $this->scopedProfileSection( __METHOD__ . "-{$this->name}" ); $status = $this->newStatus(); // Always set some fields for subclass convenience $params['options'] ??= []; $params['headers'] ??= []; // Don't stream it out as text/html if there was a PHP error if ( ( empty( $params['headless'] ) || $params['headers'] ) && headers_sent() ) { print "Headers already sent, terminating.\n"; $status->fatal( 'backend-fail-stream', $params['src'] ); return $status; } $status->merge( $this->doStreamFile( $params ) ); return $status; } /** * @see FileBackendStore::streamFile() * @stable to override * @param array $params * @return StatusValue */ protected function doStreamFile( array $params ) { $status = $this->newStatus(); $flags = 0; $flags |= !empty( $params['headless'] ) ? HTTPFileStreamer::STREAM_HEADLESS : 0; $flags |= !empty( $params['allowOB'] ) ? HTTPFileStreamer::STREAM_ALLOW_OB : 0; $fsFile = $this->getLocalReference( $params ); if ( $fsFile ) { $streamer = new HTTPFileStreamer( $fsFile->getPath(), $this->getStreamerOptions() ); $res = $streamer->stream( $params['headers'], true, $params['options'], $flags ); } else { $res = false; HTTPFileStreamer::send404Message( $params['src'], $flags ); } if ( !$res ) { $status->fatal( 'backend-fail-stream', $params['src'] ); } return $status; } final public function directoryExists( array $params ) { [ $fullCont, $dir, $shard ] = $this->resolveStoragePath( $params['dir'] ); if ( $dir === null ) { return self::EXISTENCE_ERROR; // invalid storage path } if ( $shard !== null ) { // confined to a single container/shard return $this->doDirectoryExists( $fullCont, $dir, $params ); } else { // directory is on several shards $this->logger->debug( __METHOD__ . ": iterating over all container shards." ); [ , $shortCont, ] = self::splitStoragePath( $params['dir'] ); $res = false; // response foreach ( $this->getContainerSuffixes( $shortCont ) as $suffix ) { $exists = $this->doDirectoryExists( "{$fullCont}{$suffix}", $dir, $params ); if ( $exists === true ) { $res = true; break; // found one! } elseif ( $exists === self::RES_ERROR ) { $res = self::EXISTENCE_ERROR; } } return $res; } } /** * @see FileBackendStore::directoryExists() * * @param string $container Resolved container name * @param string $dir Resolved path relative to container * @param array $params * @return bool|null */ abstract protected function doDirectoryExists( $container, $dir, array $params ); final public function getDirectoryList( array $params ) { [ $fullCont, $dir, $shard ] = $this->resolveStoragePath( $params['dir'] ); if ( $dir === null ) { return self::EXISTENCE_ERROR; // invalid storage path } if ( $shard !== null ) { // File listing is confined to a single container/shard return $this->getDirectoryListInternal( $fullCont, $dir, $params ); } else { $this->logger->debug( __METHOD__ . ": iterating over all container shards." ); // File listing spans multiple containers/shards [ , $shortCont, ] = self::splitStoragePath( $params['dir'] ); return new FileBackendStoreShardDirIterator( $this, $fullCont, $dir, $this->getContainerSuffixes( $shortCont ), $params ); } } /** * Do not call this function from places outside FileBackend * * @see FileBackendStore::getDirectoryList() * * @param string $container Resolved container name * @param string $dir Resolved path relative to container * @param array $params * @return Traversable|array|null Iterable list or null (error) */ abstract public function getDirectoryListInternal( $container, $dir, array $params ); final public function getFileList( array $params ) { [ $fullCont, $dir, $shard ] = $this->resolveStoragePath( $params['dir'] ); if ( $dir === null ) { return self::LIST_ERROR; // invalid storage path } if ( $shard !== null ) { // File listing is confined to a single container/shard return $this->getFileListInternal( $fullCont, $dir, $params ); } else { $this->logger->debug( __METHOD__ . ": iterating over all container shards." ); // File listing spans multiple containers/shards [ , $shortCont, ] = self::splitStoragePath( $params['dir'] ); return new FileBackendStoreShardFileIterator( $this, $fullCont, $dir, $this->getContainerSuffixes( $shortCont ), $params ); } } /** * Do not call this function from places outside FileBackend * * @see FileBackendStore::getFileList() * * @param string $container Resolved container name * @param string $dir Resolved path relative to container * @param array $params * @return Traversable|string[]|null Iterable list or null (error) */ abstract public function getFileListInternal( $container, $dir, array $params ); /** * Return a list of FileOp objects from a list of operations. * Do not call this function from places outside FileBackend. * * The result must have the same number of items as the input. * An exception is thrown if an unsupported operation is requested. * * @param array[] $ops Same format as doOperations() * @return FileOp[] * @throws FileBackendError */ final public function getOperationsInternal( array $ops ) { $supportedOps = [ 'store' => StoreFileOp::class, 'copy' => CopyFileOp::class, 'move' => MoveFileOp::class, 'delete' => DeleteFileOp::class, 'create' => CreateFileOp::class, 'describe' => DescribeFileOp::class, 'null' => NullFileOp::class ]; $performOps = []; // array of FileOp objects // Build up ordered array of FileOps... foreach ( $ops as $operation ) { $opName = $operation['op']; if ( isset( $supportedOps[$opName] ) ) { $class = $supportedOps[$opName]; // Get params for this operation $params = $operation; // Append the FileOp class $performOps[] = new $class( $this, $params, $this->logger ); } else { throw new FileBackendError( "Operation '$opName' is not supported." ); } } return $performOps; } /** * Get a list of storage paths to lock for a list of operations * Returns an array with LockManager::LOCK_UW (shared locks) and * LockManager::LOCK_EX (exclusive locks) keys, each corresponding * to a list of storage paths to be locked. All returned paths are * normalized. * * @param FileOp[] $performOps List of FileOp objects * @return string[][] (LockManager::LOCK_UW => path list, LockManager::LOCK_EX => path list) */ final public function getPathsToLockForOpsInternal( array $performOps ) { // Build up a list of files to lock... $paths = [ 'sh' => [], 'ex' => [] ]; foreach ( $performOps as $fileOp ) { $paths['sh'] = array_merge( $paths['sh'], $fileOp->storagePathsRead() ); $paths['ex'] = array_merge( $paths['ex'], $fileOp->storagePathsChanged() ); } // Optimization: if doing an EX lock anyway, don't also set an SH one $paths['sh'] = array_diff( $paths['sh'], $paths['ex'] ); // Get a shared lock on the parent directory of each path changed $paths['sh'] = array_merge( $paths['sh'], array_map( 'dirname', $paths['ex'] ) ); return [ LockManager::LOCK_UW => $paths['sh'], LockManager::LOCK_EX => $paths['ex'] ]; } public function getScopedLocksForOps( array $ops, StatusValue $status ) { $paths = $this->getPathsToLockForOpsInternal( $this->getOperationsInternal( $ops ) ); return $this->getScopedFileLocks( $paths, 'mixed', $status ); } final protected function doOperationsInternal( array $ops, array $opts ) { /** @noinspection PhpUnusedLocalVariableInspection */ $ps = $this->scopedProfileSection( __METHOD__ . "-{$this->name}" ); $status = $this->newStatus(); // Fix up custom header name/value pairs $ops = array_map( [ $this, 'sanitizeOpHeaders' ], $ops ); // Build up a list of FileOps and involved paths $fileOps = $this->getOperationsInternal( $ops ); $pathsUsed = []; foreach ( $fileOps as $fileOp ) { $pathsUsed = array_merge( $pathsUsed, $fileOp->storagePathsReadOrChanged() ); } // Acquire any locks as needed for the scope of this function if ( empty( $opts['nonLocking'] ) ) { $pathsByLockType = $this->getPathsToLockForOpsInternal( $fileOps ); /** @noinspection PhpUnusedLocalVariableInspection */ $scopeLock = $this->getScopedFileLocks( $pathsByLockType, 'mixed', $status ); if ( !$status->isOK() ) { return $status; // abort } } // Clear any file cache entries (after locks acquired) if ( empty( $opts['preserveCache'] ) ) { $this->clearCache( $pathsUsed ); } // Enlarge the cache to fit the stat entries of these files $this->cheapCache->setMaxSize( max( 2 * count( $pathsUsed ), self::CACHE_CHEAP_SIZE ) ); // Load from the persistent container caches $this->primeContainerCache( $pathsUsed ); // Get the latest stat info for all the files (having locked them) $ok = $this->preloadFileStat( [ 'srcs' => $pathsUsed, 'latest' => true ] ); if ( $ok ) { // Actually attempt the operation batch... $opts = $this->setConcurrencyFlags( $opts ); $subStatus = FileOpBatch::attempt( $fileOps, $opts ); } else { // If we could not even stat some files, then bail out $subStatus = $this->newStatus( 'backend-fail-internal', $this->name ); foreach ( $ops as $i => $op ) { // mark each op as failed $subStatus->success[$i] = false; ++$subStatus->failCount; } $this->logger->error( static::class . "-{$this->name} " . " stat failure; aborted operations: " . FormatJson::encode( $ops ) ); } // Merge errors into StatusValue fields $status->merge( $subStatus ); $status->success = $subStatus->success; // not done in merge() // Shrink the stat cache back to normal size $this->cheapCache->setMaxSize( self::CACHE_CHEAP_SIZE ); return $status; } final protected function doQuickOperationsInternal( array $ops, array $opts ) { /** @noinspection PhpUnusedLocalVariableInspection */ $ps = $this->scopedProfileSection( __METHOD__ . "-{$this->name}" ); $status = $this->newStatus(); // Fix up custom header name/value pairs $ops = array_map( [ $this, 'sanitizeOpHeaders' ], $ops ); // Build up a list of FileOps and involved paths $fileOps = $this->getOperationsInternal( $ops ); $pathsUsed = []; foreach ( $fileOps as $fileOp ) { $pathsUsed = array_merge( $pathsUsed, $fileOp->storagePathsReadOrChanged() ); } // Clear any file cache entries for involved paths $this->clearCache( $pathsUsed ); // Parallel ops may be disabled in config due to dependencies (e.g. needing popen()) $async = ( $this->parallelize === 'implicit' && count( $ops ) > 1 ); $maxConcurrency = $this->concurrency; // throttle /** @var StatusValue[] $statuses */ $statuses = []; // array of (index => StatusValue) /** @var FileBackendStoreOpHandle[] $batch */ $batch = []; foreach ( $fileOps as $index => $fileOp ) { $subStatus = $async ? $fileOp->attemptAsyncQuick() : $fileOp->attemptQuick(); if ( $subStatus->value instanceof FileBackendStoreOpHandle ) { // async if ( count( $batch ) >= $maxConcurrency ) { // Execute this batch. Don't queue any more ops since they contain // open filehandles which are a limited resource (T230245). $statuses += $this->executeOpHandlesInternal( $batch ); $batch = []; } $batch[$index] = $subStatus->value; // keep index } else { // error or completed $statuses[$index] = $subStatus; // keep index } } if ( count( $batch ) ) { $statuses += $this->executeOpHandlesInternal( $batch ); } // Marshall and merge all the responses... foreach ( $statuses as $index => $subStatus ) { $status->merge( $subStatus ); if ( $subStatus->isOK() ) { $status->success[$index] = true; ++$status->successCount; } else { $status->success[$index] = false; ++$status->failCount; } } $this->clearCache( $pathsUsed ); return $status; } /** * Execute a list of FileBackendStoreOpHandle handles in parallel. * The resulting StatusValue object fields will correspond * to the order in which the handles where given. * * @param FileBackendStoreOpHandle[] $fileOpHandles * @return StatusValue[] Map of StatusValue objects * @throws FileBackendError */ final public function executeOpHandlesInternal( array $fileOpHandles ) { /** @noinspection PhpUnusedLocalVariableInspection */ $ps = $this->scopedProfileSection( __METHOD__ . "-{$this->name}" ); foreach ( $fileOpHandles as $fileOpHandle ) { if ( !( $fileOpHandle instanceof FileBackendStoreOpHandle ) ) { throw new InvalidArgumentException( "Expected FileBackendStoreOpHandle object." ); } elseif ( $fileOpHandle->backend->getName() !== $this->getName() ) { throw new InvalidArgumentException( "Expected handle for this file backend." ); } } $statuses = $this->doExecuteOpHandlesInternal( $fileOpHandles ); foreach ( $fileOpHandles as $fileOpHandle ) { $fileOpHandle->closeResources(); } return $statuses; } /** * @see FileBackendStore::executeOpHandlesInternal() * @stable to override * * @param FileBackendStoreOpHandle[] $fileOpHandles * * @throws FileBackendError * @return StatusValue[] List of corresponding StatusValue objects */ protected function doExecuteOpHandlesInternal( array $fileOpHandles ) { if ( count( $fileOpHandles ) ) { throw new FileBackendError( "Backend does not support asynchronous operations." ); } return []; } /** * Normalize and filter HTTP headers from a file operation * * This normalizes and strips long HTTP headers from a file operation. * Most headers are just numbers, but some are allowed to be long. * This function is useful for cleaning up headers and avoiding backend * specific errors, especially in the middle of batch file operations. * * @param array $op Same format as doOperation() * @return array */ protected function sanitizeOpHeaders( array $op ) { static $longs = [ 'content-disposition' ]; if ( isset( $op['headers'] ) ) { // op sets HTTP headers $newHeaders = []; foreach ( $op['headers'] as $name => $value ) { $name = strtolower( $name ); $maxHVLen = in_array( $name, $longs ) ? INF : 255; if ( strlen( $name ) > 255 || strlen( $value ) > $maxHVLen ) { $this->logger->error( "Header '{header}' is too long.", [ 'filebackend' => $this->name, 'header' => "$name: $value", ] ); } else { $newHeaders[$name] = strlen( $value ) ? $value : ''; // null/false => "" } } $op['headers'] = $newHeaders; } return $op; } final public function preloadCache( array $paths ) { $fullConts = []; // full container names foreach ( $paths as $path ) { [ $fullCont, , ] = $this->resolveStoragePath( $path ); $fullConts[] = $fullCont; } // Load from the persistent file and container caches $this->primeContainerCache( $fullConts ); $this->primeFileCache( $paths ); } final public function clearCache( ?array $paths = null ) { if ( is_array( $paths ) ) { $paths = array_map( [ FileBackend::class, 'normalizeStoragePath' ], $paths ); $paths = array_filter( $paths, 'strlen' ); // remove nulls } if ( $paths === null ) { $this->cheapCache->clear(); $this->expensiveCache->clear(); } else { foreach ( $paths as $path ) { $this->cheapCache->clear( $path ); $this->expensiveCache->clear( $path ); } } $this->doClearCache( $paths ); } /** * Clears any additional stat caches for storage paths * @stable to override * * @see FileBackend::clearCache() * * @param string[]|null $paths Storage paths (optional) */ protected function doClearCache( ?array $paths = null ) { } final public function preloadFileStat( array $params ) { /** @noinspection PhpUnusedLocalVariableInspection */ $ps = $this->scopedProfileSection( __METHOD__ . "-{$this->name}" ); $params['concurrency'] = ( $this->parallelize !== 'off' ) ? $this->concurrency : 1; $stats = $this->doGetFileStatMulti( $params ); if ( $stats === null ) { return true; // not supported } // Whether this queried the backend in high consistency mode $latest = !empty( $params['latest'] ); return $this->ingestFreshFileStats( $stats, $latest ); } /** * Get file stat information (concurrently if possible) for several files * @stable to override * * @see FileBackend::getFileStat() * * @param array $params Parameters include: * - srcs : list of source storage paths * - latest : use the latest available data * @return array<string,array|false|null>|null Null if not supported. Otherwise a map of storage * path to attribute map, false (missing file), or null (I/O error). * @since 1.23 */ protected function doGetFileStatMulti( array $params ) { return null; // not supported } /** * Is this a key/value store where directories are just virtual? * Virtual directories exists in so much as files exists that are * prefixed with the directory path followed by a forward slash. * * @return bool */ abstract protected function directoriesAreVirtual(); /** * Check if a short container name is valid * * This checks for length and illegal characters. * This may disallow certain characters that can appear * in the prefix used to make the full container name. * * @param string $container * @return bool */ final protected static function isValidShortContainerName( $container ) { // Suffixes like '.xxx' (hex shard chars) or '.seg' (file segments) // might be used by subclasses. Reserve the dot character. // The only way dots end up in containers (e.g. resolveStoragePath) // is due to the wikiId container prefix or the above suffixes. return self::isValidContainerName( $container ) && !preg_match( '/[.]/', $container ); } /** * Check if a full container name is valid * * This checks for length and illegal characters. * Limiting the characters makes migrations to other stores easier. * * @param string $container * @return bool */ final protected static function isValidContainerName( $container ) { // This accounts for NTFS, Swift, and Ceph restrictions // and disallows directory separators or traversal characters. // Note that matching strings URL encode to the same string; // in Swift/Ceph, the length restriction is *after* URL encoding. return (bool)preg_match( '/^[a-z0-9][a-z0-9-_.]{0,199}$/i', $container ); } /** * Splits a storage path into an internal container name, * an internal relative file name, and a container shard suffix. * Any shard suffix is already appended to the internal container name. * This also checks that the storage path is valid and within this backend. * * If the container is sharded but a suffix could not be determined, * this means that the path can only refer to a directory and can only * be scanned by looking in all the container shards. * * @param string $storagePath * @return array (container, path, container suffix) or (null, null, null) if invalid */ final protected function resolveStoragePath( $storagePath ) { [ $backend, $shortCont, $relPath ] = self::splitStoragePath( $storagePath ); if ( $backend === $this->name ) { // must be for this backend $relPath = self::normalizeContainerPath( $relPath ); if ( $relPath !== null && self::isValidShortContainerName( $shortCont ) ) { // Get shard for the normalized path if this container is sharded $cShard = $this->getContainerShard( $shortCont, $relPath ); // Validate and sanitize the relative path (backend-specific) $relPath = $this->resolveContainerPath( $shortCont, $relPath ); if ( $relPath !== null ) { // Prepend any domain ID prefix to the container name $container = $this->fullContainerName( $shortCont ); if ( self::isValidContainerName( $container ) ) { // Validate and sanitize the container name (backend-specific) $container = $this->resolveContainerName( "{$container}{$cShard}" ); if ( $container !== null ) { return [ $container, $relPath, $cShard ]; } } } } } return [ null, null, null ]; } /** * Like resolveStoragePath() except null values are returned if * the container is sharded and the shard could not be determined * or if the path ends with '/'. The latter case is illegal for FS * backends and can confuse listings for object store backends. * * This function is used when resolving paths that must be valid * locations for files. Directory and listing functions should * generally just use resolveStoragePath() instead. * * @see FileBackendStore::resolveStoragePath() * * @param string $storagePath * @return array (container, path) or (null, null) if invalid */ final protected function resolveStoragePathReal( $storagePath ) { [ $container, $relPath, $cShard ] = $this->resolveStoragePath( $storagePath ); if ( $cShard !== null && substr( $relPath, -1 ) !== '/' ) { return [ $container, $relPath ]; } return [ null, null ]; } /** * Get the container name shard suffix for a given path. * Any empty suffix means the container is not sharded. * * @param string $container Container name * @param string $relPath Storage path relative to the container * @return string|null Returns null if shard could not be determined */ final protected function getContainerShard( $container, $relPath ) { [ $levels, $base, $repeat ] = $this->getContainerHashLevels( $container ); if ( $levels == 1 || $levels == 2 ) { // Hash characters are either base 16 or 36 $char = ( $base == 36 ) ? '[0-9a-z]' : '[0-9a-f]'; // Get a regex that represents the shard portion of paths. // The concatenation of the captures gives us the shard. if ( $levels === 1 ) { // 16 or 36 shards per container $hashDirRegex = '(' . $char . ')'; } else { // 256 or 1296 shards per container if ( $repeat ) { // verbose hash dir format (e.g. "a/ab/abc") $hashDirRegex = $char . '/(' . $char . '{2})'; } else { // short hash dir format (e.g. "a/b/c") $hashDirRegex = '(' . $char . ')/(' . $char . ')'; } } // Allow certain directories to be above the hash dirs so as // to work with FileRepo (e.g. "archive/a/ab" or "temp/a/ab"). // They must be 2+ chars to avoid any hash directory ambiguity. $m = []; if ( preg_match( "!^(?:[^/]{2,}/)*$hashDirRegex(?:/|$)!", $relPath, $m ) ) { return '.' . implode( '', array_slice( $m, 1 ) ); } return null; // failed to match } return ''; // no sharding } /** * Check if a storage path maps to a single shard. * Container dirs like "a", where the container shards on "x/xy", * can reside on several shards. Such paths are tricky to handle. * * @param string $storagePath * @return bool */ final public function isSingleShardPathInternal( $storagePath ) { [ , , $shard ] = $this->resolveStoragePath( $storagePath ); return ( $shard !== null ); } /** * Get the sharding config for a container. * If greater than 0, then all file storage paths within * the container are required to be hashed accordingly. * * @param string $container * @return array (integer levels, integer base, repeat flag) or (0, 0, false) */ final protected function getContainerHashLevels( $container ) { if ( isset( $this->shardViaHashLevels[$container] ) ) { $config = $this->shardViaHashLevels[$container]; $hashLevels = (int)$config['levels']; if ( $hashLevels == 1 || $hashLevels == 2 ) { $hashBase = (int)$config['base']; if ( $hashBase == 16 || $hashBase == 36 ) { return [ $hashLevels, $hashBase, $config['repeat'] ]; } } } return [ 0, 0, false ]; // no sharding } /** * Get a list of full container shard suffixes for a container * * @param string $container * @return array */ final protected function getContainerSuffixes( $container ) { $shards = []; [ $digits, $base ] = $this->getContainerHashLevels( $container ); if ( $digits > 0 ) { $numShards = $base ** $digits; for ( $index = 0; $index < $numShards; $index++ ) { $shards[] = '.' . \Wikimedia\base_convert( (string)$index, 10, $base, $digits ); } } return $shards; } /** * Get the full container name, including the domain ID prefix * * @param string $container * @return string */ final protected function fullContainerName( $container ) { if ( $this->domainId != '' ) { return "{$this->domainId}-$container"; } else { return $container; } } /** * Resolve a container name, checking if it's allowed by the backend. * This is intended for internal use, such as encoding illegal chars. * Subclasses can override this to be more restrictive. * @stable to override * * @param string $container * @return string|null */ protected function resolveContainerName( $container ) { return $container; } /** * Resolve a relative storage path, checking if it's allowed by the backend. * This is intended for internal use, such as encoding illegal chars or perhaps * getting absolute paths (e.g. FS based backends). Note that the relative path * may be the empty string (e.g. the path is simply to the container). * @stable to override * * @param string $container Container name * @param string $relStoragePath Storage path relative to the container * @return string|null Path or null if not valid */ protected function resolveContainerPath( $container, $relStoragePath ) { return $relStoragePath; } /** * Get the cache key for a container * * @param string $container Resolved container name * @return string */ private function containerCacheKey( $container ) { return "filebackend:{$this->name}:{$this->domainId}:container:{$container}"; } /** * Set the cached info for a container * * @param string $container Resolved container name * @param array $val Information to cache */ final protected function setContainerCache( $container, array $val ) { if ( !$this->memCache->set( $this->containerCacheKey( $container ), $val, 14 * 86400 ) ) { $this->logger->warning( "Unable to set stat cache for container {container}.", [ 'filebackend' => $this->name, 'container' => $container ] ); } } /** * Delete the cached info for a container. * The cache key is salted for a while to prevent race conditions. * * @param string $container Resolved container name */ final protected function deleteContainerCache( $container ) { if ( !$this->memCache->delete( $this->containerCacheKey( $container ), 300 ) ) { $this->logger->warning( "Unable to delete stat cache for container {container}.", [ 'filebackend' => $this->name, 'container' => $container ] ); } } /** * Do a batch lookup from cache for container stats for all containers * used in a list of container names or storage paths objects. * This loads the persistent cache values into the process cache. * * @param array $items */ final protected function primeContainerCache( array $items ) { /** @noinspection PhpUnusedLocalVariableInspection */ $ps = $this->scopedProfileSection( __METHOD__ . "-{$this->name}" ); $paths = []; // list of storage paths $contNames = []; // (cache key => resolved container name) // Get all the paths/containers from the items... foreach ( $items as $item ) { if ( self::isStoragePath( $item ) ) { $paths[] = $item; } elseif ( is_string( $item ) ) { // full container name $contNames[$this->containerCacheKey( $item )] = $item; } } // Get all the corresponding cache keys for paths... foreach ( $paths as $path ) { [ $fullCont, , ] = $this->resolveStoragePath( $path ); if ( $fullCont !== null ) { // valid path for this backend $contNames[$this->containerCacheKey( $fullCont )] = $fullCont; } } $contInfo = []; // (resolved container name => cache value) // Get all cache entries for these container cache keys... $values = $this->memCache->getMulti( array_keys( $contNames ) ); foreach ( $values as $cacheKey => $val ) { $contInfo[$contNames[$cacheKey]] = $val; } // Populate the container process cache for the backend... $this->doPrimeContainerCache( array_filter( $contInfo, 'is_array' ) ); } /** * Fill the backend-specific process cache given an array of * resolved container names and their corresponding cached info. * Only containers that actually exist should appear in the map. * @stable to override * * @param array $containerInfo Map of resolved container names to cached info */ protected function doPrimeContainerCache( array $containerInfo ) { } /** * Get the cache key for a file path * * @param string $path Normalized storage path * @return string */ private function fileCacheKey( $path ) { return "filebackend:{$this->name}:{$this->domainId}:file:" . sha1( $path ); } /** * Set the cached stat info for a file path. * Negatives (404s) are not cached. By not caching negatives, we can skip cache * salting for the case when a file is created at a path were there was none before. * * @param string $path Storage path * @param array $val Stat information to cache */ final protected function setFileCache( $path, array $val ) { $path = FileBackend::normalizeStoragePath( $path ); if ( $path === null ) { return; // invalid storage path } $mtime = (int)ConvertibleTimestamp::convert( TS_UNIX, $val['mtime'] ); $ttl = $this->memCache->adaptiveTTL( $mtime, 7 * 86400, 300, 0.1 ); $key = $this->fileCacheKey( $path ); // Set the cache unless it is currently salted. if ( !$this->memCache->set( $key, $val, $ttl ) ) { $this->logger->warning( "Unable to set stat cache for file {path}.", [ 'filebackend' => $this->name, 'path' => $path ] ); } } /** * Delete the cached stat info for a file path. * The cache key is salted for a while to prevent race conditions. * Since negatives (404s) are not cached, this does not need to be called when * a file is created at a path were there was none before. * * @param string $path Storage path */ final protected function deleteFileCache( $path ) { $path = FileBackend::normalizeStoragePath( $path ); if ( $path === null ) { return; // invalid storage path } if ( !$this->memCache->delete( $this->fileCacheKey( $path ), 300 ) ) { $this->logger->warning( "Unable to delete stat cache for file {path}.", [ 'filebackend' => $this->name, 'path' => $path ] ); } } /** * Do a batch lookup from cache for file stats for all paths * used in a list of storage paths or FileOp objects. * This loads the persistent cache values into the process cache. * * @param array $items List of storage paths */ final protected function primeFileCache( array $items ) { /** @noinspection PhpUnusedLocalVariableInspection */ $ps = $this->scopedProfileSection( __METHOD__ . "-{$this->name}" ); $paths = []; // list of storage paths $pathNames = []; // (cache key => storage path) // Get all the paths/containers from the items... foreach ( $items as $item ) { if ( self::isStoragePath( $item ) ) { $path = FileBackend::normalizeStoragePath( $item ); if ( $path !== null ) { $paths[] = $path; } } } // Get all the corresponding cache keys for paths... foreach ( $paths as $path ) { [ , $rel, ] = $this->resolveStoragePath( $path ); if ( $rel !== null ) { // valid path for this backend $pathNames[$this->fileCacheKey( $path )] = $path; } } // Get all cache entries for these file cache keys. // Note that negatives are not cached by getFileStat()/preloadFileStat(). $values = $this->memCache->getMulti( array_keys( $pathNames ) ); // Load all of the results into process cache... foreach ( array_filter( $values, 'is_array' ) as $cacheKey => $stat ) { $path = $pathNames[$cacheKey]; // This flag only applies to stat info loaded directly // from a high consistency backend query to the process cache unset( $stat['latest'] ); $this->cheapCache->setField( $path, 'stat', $stat ); if ( isset( $stat['sha1'] ) && strlen( $stat['sha1'] ) == 31 ) { // Some backends store SHA-1 as metadata $this->cheapCache->setField( $path, 'sha1', [ 'hash' => $stat['sha1'], 'latest' => false ] ); } if ( isset( $stat['xattr'] ) && is_array( $stat['xattr'] ) ) { // Some backends store custom headers/metadata $stat['xattr'] = self::normalizeXAttributes( $stat['xattr'] ); $this->cheapCache->setField( $path, 'xattr', [ 'map' => $stat['xattr'], 'latest' => false ] ); } } } /** * Normalize file headers/metadata to the FileBackend::getFileXAttributes() format * * @param array $xattr * @return array * @since 1.22 */ final protected static function normalizeXAttributes( array $xattr ) { $newXAttr = [ 'headers' => [], 'metadata' => [] ]; foreach ( $xattr['headers'] as $name => $value ) { $newXAttr['headers'][strtolower( $name )] = $value; } foreach ( $xattr['metadata'] as $name => $value ) { $newXAttr['metadata'][strtolower( $name )] = $value; } return $newXAttr; } /** * Set the 'concurrency' option from a list of operation options * * @param array $opts Map of operation options * @return array */ final protected function setConcurrencyFlags( array $opts ) { $opts['concurrency'] = 1; // off if ( $this->parallelize === 'implicit' ) { if ( $opts['parallelize'] ?? true ) { $opts['concurrency'] = $this->concurrency; } } elseif ( $this->parallelize === 'explicit' ) { if ( !empty( $opts['parallelize'] ) ) { $opts['concurrency'] = $this->concurrency; } } return $opts; } /** * Get the content type to use in HEAD/GET requests for a file * @stable to override * * @param string $storagePath * @param string|null $content File data * @param string|null $fsPath File system path * @return string MIME type */ protected function getContentType( $storagePath, $content, $fsPath ) { if ( $this->mimeCallback ) { return call_user_func_array( $this->mimeCallback, func_get_args() ); } $mime = ( $fsPath !== null ) ? mime_content_type( $fsPath ) : false; return $mime ?: 'unknown/unknown'; } } /** @deprecated class alias since 1.43 */ class_alias( FileBackendStore::class, 'FileBackendStore' ); PK ! �",��� �� filebackend/FSFileBackend.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file * @ingroup FileBackend */ /** * File system based backend. * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file * @ingroup FileBackend */ namespace Wikimedia\FileBackend; use MapCacheLRU; use Shellbox\Command\BoxedCommand; use Shellbox\Shellbox; use StatusValue; use Wikimedia\AtEase\AtEase; use Wikimedia\FileBackend\FileIteration\FSFileBackendDirList; use Wikimedia\FileBackend\FileIteration\FSFileBackendFileList; use Wikimedia\FileBackend\FileOpHandle\FSFileOpHandle; use Wikimedia\FileBackend\FSFile\FSFile; use Wikimedia\FileBackend\FSFile\TempFSFile; use Wikimedia\Timestamp\ConvertibleTimestamp; /** * @brief Class for a file system (FS) based file backend. * * All "containers" each map to a directory under the backend's base directory. * For backwards-compatibility, some container paths can be set to custom paths. * The domain ID will not be used in any custom paths, so this should be avoided. * * Having directories with thousands of files will diminish performance. * Sharding can be accomplished by using FileRepo-style hash paths. * * StatusValue messages should avoid mentioning the internal FS paths. * PHP warnings are assumed to be logged rather than output. * * @ingroup FileBackend * @since 1.19 */ class FSFileBackend extends FileBackendStore { /** @var MapCacheLRU Cache for known prepared/usable directories */ protected $usableDirCache; /** @var string|null Directory holding the container directories */ protected $basePath; /** @var array<string,string> Map of container names to root paths for custom container paths */ protected $containerPaths; /** @var int Directory permission mode */ protected $dirMode; /** @var int File permission mode */ protected $fileMode; /** @var string Required OS username to own files */ protected $fileOwner; /** @var string Simpler version of PHP_OS_FAMILY */ protected $os; /** @var string OS username running this script */ protected $currentUser; /** @var bool[] Map of (stack index => whether a warning happened) */ private $warningTrapStack = []; /** * @see FileBackendStore::__construct() * Additional $config params include: * - basePath : File system directory that holds containers. * - containerPaths : Map of container names to custom file system directories. * This should only be used for backwards-compatibility. * - fileMode : Octal UNIX file permissions to use on files stored. * - directoryMode : Octal UNIX file permissions to use on directories created. * @param array $config */ public function __construct( array $config ) { parent::__construct( $config ); if ( PHP_OS_FAMILY === 'Windows' ) { $this->os = 'Windows'; } elseif ( PHP_OS_FAMILY === 'BSD' || PHP_OS_FAMILY === 'Darwin' ) { $this->os = 'BSD'; } else { $this->os = 'Linux'; } // Remove any possible trailing slash from directories if ( isset( $config['basePath'] ) ) { $this->basePath = rtrim( $config['basePath'], '/' ); // remove trailing slash } else { $this->basePath = null; // none; containers must have explicit paths } $this->containerPaths = []; foreach ( ( $config['containerPaths'] ?? [] ) as $container => $fsPath ) { $this->containerPaths[$container] = rtrim( $fsPath, '/' ); // remove trailing slash } $this->fileMode = $config['fileMode'] ?? 0644; $this->dirMode = $config['directoryMode'] ?? 0777; if ( isset( $config['fileOwner'] ) && function_exists( 'posix_getuid' ) ) { $this->fileOwner = $config['fileOwner']; // Cache this, assuming it doesn't change $this->currentUser = posix_getpwuid( posix_getuid() )['name']; } $this->usableDirCache = new MapCacheLRU( self::CACHE_CHEAP_SIZE ); } public function getFeatures() { return self::ATTR_UNICODE_PATHS; } protected function resolveContainerPath( $container, $relStoragePath ) { // Check that container has a root directory if ( isset( $this->containerPaths[$container] ) || isset( $this->basePath ) ) { // Check for sensible relative paths (assume the base paths are OK) if ( $this->isLegalRelPath( $relStoragePath ) ) { return $relStoragePath; } } return null; // invalid } /** * Check a relative file system path for validity * * @param string $fsPath Normalized relative path * @return bool */ protected function isLegalRelPath( $fsPath ) { // Check for file names longer than 255 chars if ( preg_match( '![^/]{256}!', $fsPath ) ) { // ext3/NTFS return false; } if ( $this->os === 'Windows' ) { // NTFS return !preg_match( '![:*?"<>|]!', $fsPath ); } else { return true; } } /** * Given the short (unresolved) and full (resolved) name of * a container, return the file system path of the container. * * @param string $shortCont * @param string $fullCont * @return string|null */ protected function containerFSRoot( $shortCont, $fullCont ) { if ( isset( $this->containerPaths[$shortCont] ) ) { return $this->containerPaths[$shortCont]; } elseif ( isset( $this->basePath ) ) { return "{$this->basePath}/{$fullCont}"; } return null; // no container base path defined } /** * Get the absolute file system path for a storage path * * @param string $storagePath * @return string|null */ protected function resolveToFSPath( $storagePath ) { [ $fullCont, $relPath ] = $this->resolveStoragePathReal( $storagePath ); if ( $relPath === null ) { return null; // invalid } [ , $shortCont, ] = FileBackend::splitStoragePath( $storagePath ); $fsPath = $this->containerFSRoot( $shortCont, $fullCont ); // must be valid if ( $relPath != '' ) { $fsPath .= "/{$relPath}"; } return $fsPath; } public function isPathUsableInternal( $storagePath ) { $fsPath = $this->resolveToFSPath( $storagePath ); if ( $fsPath === null ) { return false; // invalid } if ( $this->fileOwner !== null && $this->currentUser !== $this->fileOwner ) { trigger_error( __METHOD__ . ": PHP process owner is not '{$this->fileOwner}'." ); return false; } $fsDirectory = dirname( $fsPath ); $usable = $this->usableDirCache->get( $fsDirectory, MapCacheLRU::TTL_PROC_SHORT ); if ( $usable === null ) { AtEase::suppressWarnings(); $usable = is_dir( $fsDirectory ) && is_writable( $fsDirectory ); AtEase::restoreWarnings(); $this->usableDirCache->set( $fsDirectory, $usable ? 1 : 0 ); } return $usable; } protected function doCreateInternal( array $params ) { $status = $this->newStatus(); $fsDstPath = $this->resolveToFSPath( $params['dst'] ); if ( $fsDstPath === null ) { $status->fatal( 'backend-fail-invalidpath', $params['dst'] ); return $status; } if ( !empty( $params['async'] ) ) { // deferred $tempFile = $this->newTempFileWithContent( $params ); if ( !$tempFile ) { $status->fatal( 'backend-fail-create', $params['dst'] ); return $status; } $cmd = $this->makeCopyCommand( $tempFile->getPath(), $fsDstPath, false ); $handler = function ( $errors, StatusValue $status, array $params, $cmd ) { if ( $errors !== '' && !( $this->os === 'Windows' && $errors[0] === " " ) ) { $status->fatal( 'backend-fail-create', $params['dst'] ); trigger_error( "$cmd\n$errors", E_USER_WARNING ); // command output } }; $status->value = new FSFileOpHandle( $this, $params, $handler, $cmd ); $tempFile->bind( $status->value ); } else { // immediate write $created = false; // Use fwrite+rename since (a) this clears xattrs, (b) threads still reading the old // inode are unaffected since it writes to a new inode, and (c) new threads reading // the file will either totally see the old version or totally see the new version $fsStagePath = $this->makeStagingPath( $fsDstPath ); $this->trapWarningsIgnoringNotFound(); $stageHandle = fopen( $fsStagePath, 'xb' ); if ( $stageHandle ) { $bytes = fwrite( $stageHandle, $params['content'] ); $created = ( $bytes === strlen( $params['content'] ) ); fclose( $stageHandle ); $created = $created ? rename( $fsStagePath, $fsDstPath ) : false; } $hadError = $this->untrapWarnings(); if ( $hadError || !$created ) { $status->fatal( 'backend-fail-create', $params['dst'] ); return $status; } $this->chmod( $fsDstPath ); } return $status; } protected function doStoreInternal( array $params ) { $status = $this->newStatus(); $fsSrcPath = $params['src']; // file system path $fsDstPath = $this->resolveToFSPath( $params['dst'] ); if ( $fsDstPath === null ) { $status->fatal( 'backend-fail-invalidpath', $params['dst'] ); return $status; } if ( $fsSrcPath === $fsDstPath ) { $status->fatal( 'backend-fail-internal', $this->name ); return $status; } if ( !empty( $params['async'] ) ) { // deferred $cmd = $this->makeCopyCommand( $fsSrcPath, $fsDstPath, false ); $handler = function ( $errors, StatusValue $status, array $params, $cmd ) { if ( $errors !== '' && !( $this->os === 'Windows' && $errors[0] === " " ) ) { $status->fatal( 'backend-fail-store', $params['src'], $params['dst'] ); trigger_error( "$cmd\n$errors", E_USER_WARNING ); // command output } }; $status->value = new FSFileOpHandle( $this, $params, $handler, $cmd ); } else { // immediate write $stored = false; // Use fwrite+rename since (a) this clears xattrs, (b) threads still reading the old // inode are unaffected since it writes to a new inode, and (c) new threads reading // the file will either totally see the old version or totally see the new version $fsStagePath = $this->makeStagingPath( $fsDstPath ); $this->trapWarningsIgnoringNotFound(); $srcHandle = fopen( $fsSrcPath, 'rb' ); if ( $srcHandle ) { $stageHandle = fopen( $fsStagePath, 'xb' ); if ( $stageHandle ) { $bytes = stream_copy_to_stream( $srcHandle, $stageHandle ); $stored = ( $bytes !== false && $bytes === fstat( $srcHandle )['size'] ); fclose( $stageHandle ); $stored = $stored ? rename( $fsStagePath, $fsDstPath ) : false; } fclose( $srcHandle ); } $hadError = $this->untrapWarnings(); if ( $hadError || !$stored ) { $status->fatal( 'backend-fail-store', $params['src'], $params['dst'] ); return $status; } $this->chmod( $fsDstPath ); } return $status; } protected function doCopyInternal( array $params ) { $status = $this->newStatus(); $fsSrcPath = $this->resolveToFSPath( $params['src'] ); if ( $fsSrcPath === null ) { $status->fatal( 'backend-fail-invalidpath', $params['src'] ); return $status; } $fsDstPath = $this->resolveToFSPath( $params['dst'] ); if ( $fsDstPath === null ) { $status->fatal( 'backend-fail-invalidpath', $params['dst'] ); return $status; } if ( $fsSrcPath === $fsDstPath ) { return $status; // no-op } $ignoreMissing = !empty( $params['ignoreMissingSource'] ); if ( !empty( $params['async'] ) ) { // deferred $cmd = $this->makeCopyCommand( $fsSrcPath, $fsDstPath, $ignoreMissing ); $handler = function ( $errors, StatusValue $status, array $params, $cmd ) { if ( $errors !== '' && !( $this->os === 'Windows' && $errors[0] === " " ) ) { $status->fatal( 'backend-fail-copy', $params['src'], $params['dst'] ); trigger_error( "$cmd\n$errors", E_USER_WARNING ); // command output } }; $status->value = new FSFileOpHandle( $this, $params, $handler, $cmd ); } else { // immediate write $copied = false; // Use fwrite+rename since (a) this clears xattrs, (b) threads still reading the old // inode are unaffected since it writes to a new inode, and (c) new threads reading // the file will either totally see the old version or totally see the new version $fsStagePath = $this->makeStagingPath( $fsDstPath ); $this->trapWarningsIgnoringNotFound(); $srcHandle = fopen( $fsSrcPath, 'rb' ); if ( $srcHandle ) { $stageHandle = fopen( $fsStagePath, 'xb' ); if ( $stageHandle ) { $bytes = stream_copy_to_stream( $srcHandle, $stageHandle ); $copied = ( $bytes !== false && $bytes === fstat( $srcHandle )['size'] ); fclose( $stageHandle ); $copied = $copied ? rename( $fsStagePath, $fsDstPath ) : false; } fclose( $srcHandle ); } $hadError = $this->untrapWarnings(); if ( $hadError || ( !$copied && !$ignoreMissing ) ) { $status->fatal( 'backend-fail-copy', $params['src'], $params['dst'] ); return $status; } if ( $copied ) { $this->chmod( $fsDstPath ); } } return $status; } protected function doMoveInternal( array $params ) { $status = $this->newStatus(); $fsSrcPath = $this->resolveToFSPath( $params['src'] ); if ( $fsSrcPath === null ) { $status->fatal( 'backend-fail-invalidpath', $params['src'] ); return $status; } $fsDstPath = $this->resolveToFSPath( $params['dst'] ); if ( $fsDstPath === null ) { $status->fatal( 'backend-fail-invalidpath', $params['dst'] ); return $status; } if ( $fsSrcPath === $fsDstPath ) { return $status; // no-op } $ignoreMissing = !empty( $params['ignoreMissingSource'] ); if ( !empty( $params['async'] ) ) { // deferred $cmd = $this->makeMoveCommand( $fsSrcPath, $fsDstPath, $ignoreMissing ); $handler = function ( $errors, StatusValue $status, array $params, $cmd ) { if ( $errors !== '' && !( $this->os === 'Windows' && $errors[0] === " " ) ) { $status->fatal( 'backend-fail-move', $params['src'], $params['dst'] ); trigger_error( "$cmd\n$errors", E_USER_WARNING ); // command output } }; $status->value = new FSFileOpHandle( $this, $params, $handler, $cmd ); } else { // immediate write // Use rename() here since (a) this clears xattrs, (b) any threads still reading the // old inode are unaffected since it writes to a new inode, and (c) this is fast and // atomic within a file system volume (as is normally the case) $this->trapWarningsIgnoringNotFound(); $moved = rename( $fsSrcPath, $fsDstPath ); $hadError = $this->untrapWarnings(); if ( $hadError || ( !$moved && !$ignoreMissing ) ) { $status->fatal( 'backend-fail-move', $params['src'], $params['dst'] ); return $status; } } return $status; } protected function doDeleteInternal( array $params ) { $status = $this->newStatus(); $fsSrcPath = $this->resolveToFSPath( $params['src'] ); if ( $fsSrcPath === null ) { $status->fatal( 'backend-fail-invalidpath', $params['src'] ); return $status; } $ignoreMissing = !empty( $params['ignoreMissingSource'] ); if ( !empty( $params['async'] ) ) { // deferred $cmd = $this->makeUnlinkCommand( $fsSrcPath, $ignoreMissing ); $handler = function ( $errors, StatusValue $status, array $params, $cmd ) { if ( $errors !== '' && !( $this->os === 'Windows' && $errors[0] === " " ) ) { $status->fatal( 'backend-fail-delete', $params['src'] ); trigger_error( "$cmd\n$errors", E_USER_WARNING ); // command output } }; $status->value = new FSFileOpHandle( $this, $params, $handler, $cmd ); } else { // immediate write $this->trapWarningsIgnoringNotFound(); $deleted = unlink( $fsSrcPath ); $hadError = $this->untrapWarnings(); if ( $hadError || ( !$deleted && !$ignoreMissing ) ) { $status->fatal( 'backend-fail-delete', $params['src'] ); return $status; } } return $status; } /** * @inheritDoc */ protected function doPrepareInternal( $fullCont, $dirRel, array $params ) { $status = $this->newStatus(); [ , $shortCont, ] = FileBackend::splitStoragePath( $params['dir'] ); $contRoot = $this->containerFSRoot( $shortCont, $fullCont ); // must be valid $fsDirectory = ( $dirRel != '' ) ? "{$contRoot}/{$dirRel}" : $contRoot; // Create the directory and its parents as needed... $created = false; AtEase::suppressWarnings(); $alreadyExisted = is_dir( $fsDirectory ); // already there? if ( !$alreadyExisted ) { $created = mkdir( $fsDirectory, $this->dirMode, true ); if ( !$created ) { $alreadyExisted = is_dir( $fsDirectory ); // another thread made it? } } $isWritable = $created ?: is_writable( $fsDirectory ); // assume writable if created here AtEase::restoreWarnings(); if ( !$alreadyExisted && !$created ) { $this->logger->error( __METHOD__ . ": cannot create directory $fsDirectory" ); $status->fatal( 'directorycreateerror', $params['dir'] ); // fails on races } elseif ( !$isWritable ) { $this->logger->error( __METHOD__ . ": directory $fsDirectory is read-only" ); $status->fatal( 'directoryreadonlyerror', $params['dir'] ); } // Respect any 'noAccess' or 'noListing' flags... if ( $created ) { $status->merge( $this->doSecureInternal( $fullCont, $dirRel, $params ) ); } if ( $status->isGood() ) { $this->usableDirCache->set( $fsDirectory, 1 ); } return $status; } protected function doSecureInternal( $fullCont, $dirRel, array $params ) { $status = $this->newStatus(); [ , $shortCont, ] = FileBackend::splitStoragePath( $params['dir'] ); $contRoot = $this->containerFSRoot( $shortCont, $fullCont ); // must be valid $fsDirectory = ( $dirRel != '' ) ? "{$contRoot}/{$dirRel}" : $contRoot; // Seed new directories with a blank index.html, to prevent crawling... if ( !empty( $params['noListing'] ) && !is_file( "{$fsDirectory}/index.html" ) ) { $this->trapWarnings(); $bytes = file_put_contents( "{$fsDirectory}/index.html", $this->indexHtmlPrivate() ); $this->untrapWarnings(); if ( $bytes === false ) { $status->fatal( 'backend-fail-create', $params['dir'] . '/index.html' ); } } // Add a .htaccess file to the root of the container... if ( !empty( $params['noAccess'] ) && !is_file( "{$contRoot}/.htaccess" ) ) { AtEase::suppressWarnings(); $bytes = file_put_contents( "{$contRoot}/.htaccess", $this->htaccessPrivate() ); AtEase::restoreWarnings(); if ( $bytes === false ) { $storeDir = "mwstore://{$this->name}/{$shortCont}"; $status->fatal( 'backend-fail-create', "{$storeDir}/.htaccess" ); } } return $status; } protected function doPublishInternal( $fullCont, $dirRel, array $params ) { $status = $this->newStatus(); [ , $shortCont, ] = FileBackend::splitStoragePath( $params['dir'] ); $contRoot = $this->containerFSRoot( $shortCont, $fullCont ); // must be valid $fsDirectory = ( $dirRel != '' ) ? "{$contRoot}/{$dirRel}" : $contRoot; // Unseed new directories with a blank index.html, to allow crawling... if ( !empty( $params['listing'] ) && is_file( "{$fsDirectory}/index.html" ) ) { $exists = ( file_get_contents( "{$fsDirectory}/index.html" ) === $this->indexHtmlPrivate() ); if ( $exists && !$this->unlink( "{$fsDirectory}/index.html" ) ) { // reverse secure() $status->fatal( 'backend-fail-delete', $params['dir'] . '/index.html' ); } } // Remove the .htaccess file from the root of the container... if ( !empty( $params['access'] ) && is_file( "{$contRoot}/.htaccess" ) ) { $exists = ( file_get_contents( "{$contRoot}/.htaccess" ) === $this->htaccessPrivate() ); if ( $exists && !$this->unlink( "{$contRoot}/.htaccess" ) ) { // reverse secure() $storeDir = "mwstore://{$this->name}/{$shortCont}"; $status->fatal( 'backend-fail-delete', "{$storeDir}/.htaccess" ); } } return $status; } protected function doCleanInternal( $fullCont, $dirRel, array $params ) { $status = $this->newStatus(); [ , $shortCont, ] = FileBackend::splitStoragePath( $params['dir'] ); $contRoot = $this->containerFSRoot( $shortCont, $fullCont ); // must be valid $fsDirectory = ( $dirRel != '' ) ? "{$contRoot}/{$dirRel}" : $contRoot; $this->rmdir( $fsDirectory ); return $status; } protected function doGetFileStat( array $params ) { $fsSrcPath = $this->resolveToFSPath( $params['src'] ); if ( $fsSrcPath === null ) { return self::RES_ERROR; // invalid storage path } $this->trapWarnings(); // don't trust 'false' if there were errors $stat = is_file( $fsSrcPath ) ? stat( $fsSrcPath ) : false; // regular files only $hadError = $this->untrapWarnings(); if ( is_array( $stat ) ) { $ct = new ConvertibleTimestamp( $stat['mtime'] ); return [ 'mtime' => $ct->getTimestamp( TS_MW ), 'size' => $stat['size'] ]; } return $hadError ? self::RES_ERROR : self::RES_ABSENT; } protected function doClearCache( ?array $paths = null ) { if ( is_array( $paths ) ) { foreach ( $paths as $path ) { $fsPath = $this->resolveToFSPath( $path ); if ( $fsPath !== null ) { clearstatcache( true, $fsPath ); $this->usableDirCache->clear( $fsPath ); } } } else { clearstatcache( true ); // clear the PHP file stat cache $this->usableDirCache->clear(); } } protected function doDirectoryExists( $fullCont, $dirRel, array $params ) { [ , $shortCont, ] = FileBackend::splitStoragePath( $params['dir'] ); $contRoot = $this->containerFSRoot( $shortCont, $fullCont ); // must be valid $fsDirectory = ( $dirRel != '' ) ? "{$contRoot}/{$dirRel}" : $contRoot; $this->trapWarnings(); // don't trust 'false' if there were errors $exists = is_dir( $fsDirectory ); $hadError = $this->untrapWarnings(); return $hadError ? self::RES_ERROR : $exists; } /** * @see FileBackendStore::getDirectoryListInternal() * @param string $fullCont * @param string $dirRel * @param array $params * @return array|FSFileBackendDirList|null */ public function getDirectoryListInternal( $fullCont, $dirRel, array $params ) { [ , $shortCont, ] = FileBackend::splitStoragePath( $params['dir'] ); $contRoot = $this->containerFSRoot( $shortCont, $fullCont ); // must be valid $fsDirectory = ( $dirRel != '' ) ? "{$contRoot}/{$dirRel}" : $contRoot; $list = new FSFileBackendDirList( $fsDirectory, $params ); $error = $list->getLastError(); if ( $error !== null ) { if ( $this->isFileNotFoundError( $error ) ) { $this->logger->info( __METHOD__ . ": non-existant directory: '$fsDirectory'" ); return []; // nothing under this dir } elseif ( is_dir( $fsDirectory ) ) { $this->logger->warning( __METHOD__ . ": unreadable directory: '$fsDirectory'" ); return self::RES_ERROR; // bad permissions? } else { $this->logger->warning( __METHOD__ . ": unreachable directory: '$fsDirectory'" ); return self::RES_ERROR; } } return $list; } /** * @see FileBackendStore::getFileListInternal() * @param string $fullCont * @param string $dirRel * @param array $params * @return array|FSFileBackendFileList|null */ public function getFileListInternal( $fullCont, $dirRel, array $params ) { [ , $shortCont, ] = FileBackend::splitStoragePath( $params['dir'] ); $contRoot = $this->containerFSRoot( $shortCont, $fullCont ); // must be valid $fsDirectory = ( $dirRel != '' ) ? "{$contRoot}/{$dirRel}" : $contRoot; $list = new FSFileBackendFileList( $fsDirectory, $params ); $error = $list->getLastError(); if ( $error !== null ) { if ( $this->isFileNotFoundError( $error ) ) { $this->logger->info( __METHOD__ . ": non-existent directory: '$fsDirectory'" ); return []; // nothing under this dir } elseif ( is_dir( $fsDirectory ) ) { $this->logger->warning( __METHOD__ . ": unreadable directory: '$fsDirectory': $error" ); return self::RES_ERROR; // bad permissions? } else { $this->logger->warning( __METHOD__ . ": unreachable directory: '$fsDirectory': $error" ); return self::RES_ERROR; } } return $list; } protected function doGetLocalReferenceMulti( array $params ) { $fsFiles = []; // (path => FSFile) foreach ( $params['srcs'] as $src ) { $source = $this->resolveToFSPath( $src ); if ( $source === null ) { $fsFiles[$src] = self::RES_ERROR; // invalid path continue; } $this->trapWarnings(); // don't trust 'false' if there were errors $isFile = is_file( $source ); // regular files only $hadError = $this->untrapWarnings(); if ( $isFile ) { $fsFiles[$src] = new FSFile( $source ); } elseif ( $hadError ) { $fsFiles[$src] = self::RES_ERROR; } else { $fsFiles[$src] = self::RES_ABSENT; } } return $fsFiles; } protected function doGetLocalCopyMulti( array $params ) { $tmpFiles = []; // (path => TempFSFile) foreach ( $params['srcs'] as $src ) { $source = $this->resolveToFSPath( $src ); if ( $source === null ) { $tmpFiles[$src] = self::RES_ERROR; // invalid path continue; } // Create a new temporary file with the same extension... $ext = FileBackend::extensionFromPath( $src ); $tmpFile = $this->tmpFileFactory->newTempFSFile( 'localcopy_', $ext ); if ( !$tmpFile ) { $tmpFiles[$src] = self::RES_ERROR; continue; } $tmpPath = $tmpFile->getPath(); // Copy the source file over the temp file $this->trapWarnings(); // don't trust 'false' if there were errors $isFile = is_file( $source ); // regular files only $copySuccess = $isFile ? copy( $source, $tmpPath ) : false; $hadError = $this->untrapWarnings(); if ( $copySuccess ) { $this->chmod( $tmpPath ); $tmpFiles[$src] = $tmpFile; } elseif ( $hadError ) { $tmpFiles[$src] = self::RES_ERROR; // copy failed } else { $tmpFiles[$src] = self::RES_ABSENT; } } return $tmpFiles; } public function addShellboxInputFile( BoxedCommand $command, string $boxedName, array $params ) { $path = $this->resolveToFSPath( $params['src'] ); if ( $path === null ) { return $this->newStatus( 'backend-fail-invalidpath', $params['src'] ); } $command->inputFileFromFile( $boxedName, $path ); return $this->newStatus(); } protected function directoriesAreVirtual() { return false; } /** * @param FSFileOpHandle[] $fileOpHandles * * @return StatusValue[] */ protected function doExecuteOpHandlesInternal( array $fileOpHandles ) { $statuses = []; $pipes = []; foreach ( $fileOpHandles as $index => $fileOpHandle ) { $pipes[$index] = popen( $fileOpHandle->cmd, 'r' ); } $errs = []; foreach ( $pipes as $index => $pipe ) { // Result will be empty on success in *NIX. On Windows, // it may be something like " 1 file(s) [copied|moved].". $errs[$index] = stream_get_contents( $pipe ); fclose( $pipe ); } foreach ( $fileOpHandles as $index => $fileOpHandle ) { $status = $this->newStatus(); $function = $fileOpHandle->callback; $function( $errs[$index], $status, $fileOpHandle->params, $fileOpHandle->cmd ); $statuses[$index] = $status; } return $statuses; } /** * @param string $fsPath Absolute file system path * @return string Absolute file system path on the same device */ private function makeStagingPath( $fsPath ) { $time = dechex( time() ); // make it easy to find old orphans $hash = \Wikimedia\base_convert( md5( basename( $fsPath ) ), 16, 36, 25 ); $unique = \Wikimedia\base_convert( bin2hex( random_bytes( 16 ) ), 16, 36, 25 ); return dirname( $fsPath ) . "/.{$time}_{$hash}_{$unique}.tmpfsfile"; } /** * @param string $fsSrcPath Absolute file system path * @param string $fsDstPath Absolute file system path * @param bool $ignoreMissing Whether to no-op if the source file is non-existent * @return string Command */ private function makeCopyCommand( $fsSrcPath, $fsDstPath, $ignoreMissing ) { // Use copy+rename since (a) this clears xattrs, (b) threads still reading the old // inode are unaffected since it writes to a new inode, and (c) new threads reading // the file will either totally see the old version or totally see the new version $fsStagePath = $this->makeStagingPath( $fsDstPath ); $encSrc = Shellbox::escape( $this->cleanPathSlashes( $fsSrcPath ) ); $encStage = Shellbox::escape( $this->cleanPathSlashes( $fsStagePath ) ); $encDst = Shellbox::escape( $this->cleanPathSlashes( $fsDstPath ) ); if ( $this->os === 'Windows' ) { // https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/copy // https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/move $cmdWrite = "COPY /B /Y $encSrc $encStage 2>&1 && MOVE /Y $encStage $encDst 2>&1"; $cmd = $ignoreMissing ? "IF EXIST $encSrc $cmdWrite" : $cmdWrite; } else { // https://manpages.debian.org/buster/coreutils/cp.1.en.html // https://manpages.debian.org/buster/coreutils/mv.1.en.html $cmdWrite = "cp $encSrc $encStage 2>&1 && mv $encStage $encDst 2>&1"; $cmd = $ignoreMissing ? "test -f $encSrc && $cmdWrite" : $cmdWrite; // Clean up permissions on any newly created destination file $octalPermissions = '0' . decoct( $this->fileMode ); if ( strlen( $octalPermissions ) == 4 ) { $cmd .= " && chmod $octalPermissions $encDst 2>/dev/null"; } } return $cmd; } /** * @param string $fsSrcPath Absolute file system path * @param string $fsDstPath Absolute file system path * @param bool $ignoreMissing Whether to no-op if the source file is non-existent * @return string Command */ private function makeMoveCommand( $fsSrcPath, $fsDstPath, $ignoreMissing = false ) { // https://manpages.debian.org/buster/coreutils/mv.1.en.html // https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/move $encSrc = Shellbox::escape( $this->cleanPathSlashes( $fsSrcPath ) ); $encDst = Shellbox::escape( $this->cleanPathSlashes( $fsDstPath ) ); if ( $this->os === 'Windows' ) { $writeCmd = "MOVE /Y $encSrc $encDst 2>&1"; $cmd = $ignoreMissing ? "IF EXIST $encSrc $writeCmd" : $writeCmd; } else { $writeCmd = "mv -f $encSrc $encDst 2>&1"; $cmd = $ignoreMissing ? "test -f $encSrc && $writeCmd" : $writeCmd; } return $cmd; } /** * @param string $fsPath Absolute file system path * @param bool $ignoreMissing Whether to no-op if the file is non-existent * @return string Command */ private function makeUnlinkCommand( $fsPath, $ignoreMissing = false ) { // https://manpages.debian.org/buster/coreutils/rm.1.en.html // https://docs.microsoft.com/en-us/windows-server/administration/windows-commands/del $encSrc = Shellbox::escape( $this->cleanPathSlashes( $fsPath ) ); if ( $this->os === 'Windows' ) { $writeCmd = "DEL /Q $encSrc 2>&1"; $cmd = $ignoreMissing ? "IF EXIST $encSrc $writeCmd" : $writeCmd; } else { $cmd = $ignoreMissing ? "rm -f $encSrc 2>&1" : "rm $encSrc 2>&1"; } return $cmd; } /** * Chmod a file, suppressing the warnings * * @param string $fsPath Absolute file system path * @return bool Success */ protected function chmod( $fsPath ) { if ( $this->os === 'Windows' ) { return true; } AtEase::suppressWarnings(); $ok = chmod( $fsPath, $this->fileMode ); AtEase::restoreWarnings(); return $ok; } /** * Unlink a file, suppressing the warnings * * @param string $fsPath Absolute file system path * @return bool Success */ protected function unlink( $fsPath ) { AtEase::suppressWarnings(); $ok = unlink( $fsPath ); AtEase::restoreWarnings(); clearstatcache( true, $fsPath ); return $ok; } /** * Remove an empty directory, suppressing the warnings * * @param string $fsDirectory Absolute file system path * @return bool Success */ protected function rmdir( $fsDirectory ) { AtEase::suppressWarnings(); $ok = rmdir( $fsDirectory ); // remove directory if empty AtEase::restoreWarnings(); clearstatcache( true, $fsDirectory ); return $ok; } /** * @param array $params Parameters for FileBackend 'create' operation * @return TempFSFile|null */ protected function newTempFileWithContent( array $params ) { $tempFile = $this->tmpFileFactory->newTempFSFile( 'create_', 'tmp' ); if ( !$tempFile ) { return null; } AtEase::suppressWarnings(); if ( file_put_contents( $tempFile->getPath(), $params['content'] ) === false ) { $tempFile = null; } AtEase::restoreWarnings(); return $tempFile; } /** * Return the text of an index.html file to hide directory listings * * @return string */ protected function indexHtmlPrivate() { return ''; } /** * Return the text of a .htaccess file to make a directory private * * @return string */ protected function htaccessPrivate() { return "Require all denied\n" . "Satisfy All\n"; } /** * Clean up directory separators for the given OS * * @param string $fsPath * @return string */ protected function cleanPathSlashes( $fsPath ) { return ( $this->os === 'Windows' ) ? strtr( $fsPath, '/', '\\' ) : $fsPath; } /** * Listen for E_WARNING errors and track whether any that happen * * @param string|null $regexIgnore Optional regex of errors to ignore */ protected function trapWarnings( $regexIgnore = null ) { $this->warningTrapStack[] = false; set_error_handler( function ( $errno, $errstr ) use ( $regexIgnore ) { if ( $regexIgnore === null || !preg_match( $regexIgnore, $errstr ) ) { $this->logger->error( $errstr ); $this->warningTrapStack[count( $this->warningTrapStack ) - 1] = true; } return true; // suppress from PHP handler }, E_WARNING ); } /** * Track E_WARNING errors but ignore any that correspond to ENOENT "No such file or directory" */ protected function trapWarningsIgnoringNotFound() { $this->trapWarnings( $this->getFileNotFoundRegex() ); } /** * Stop listening for E_WARNING errors and get whether any happened * * @return bool Whether any warnings happened */ protected function untrapWarnings() { restore_error_handler(); return array_pop( $this->warningTrapStack ); } /** * Get a regex matching file not found errors * * @return string */ protected function getFileNotFoundRegex() { static $regex; if ( $regex === null ) { // "No such file or directory": string literal in spl_directory.c etc. $alternatives = [ ': No such file or directory' ]; if ( $this->os === 'Windows' ) { // 2 = The system cannot find the file specified. // 3 = The system cannot find the path specified. $alternatives[] = ' \(code: [23]\)'; } if ( function_exists( 'pcntl_strerror' ) ) { $alternatives[] = preg_quote( ': ' . pcntl_strerror( 2 ), '/' ); } elseif ( function_exists( 'socket_strerror' ) && defined( 'SOCKET_ENOENT' ) ) { $alternatives[] = preg_quote( ': ' . socket_strerror( SOCKET_ENOENT ), '/' ); } $regex = '/(' . implode( '|', $alternatives ) . ')$/'; } return $regex; } /** * Determine whether a given error message is a file not found error. * * @param string $error * @return bool */ protected function isFileNotFoundError( $error ) { return (bool)preg_match( $this->getFileNotFoundRegex(), $error ); } } /** @deprecated class alias since 1.43 */ class_alias( FSFileBackend::class, 'FSFileBackend' ); PK ! �9�_" " filebackend/fsfile/FSFile.phpnu �Iw�� <?php /** * Non-directory file on the file system. * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file * @ingroup FileBackend */ namespace Wikimedia\FileBackend\FSFile; use Wikimedia\AtEase\AtEase; use Wikimedia\Timestamp\ConvertibleTimestamp; /** * Class representing a non-directory file on the file system * * @ingroup FileBackend */ class FSFile { /** @var string Path to file */ protected $path; /** @var string File SHA-1 in base 36 */ protected $sha1Base36; /** * Sets up the file object * * @param string $path Path to temporary file on local disk */ public function __construct( $path ) { $this->path = $path; } /** * Returns the file system path * * @return string */ public function getPath() { return $this->path; } /** * Checks if the file exists * * @return bool */ public function exists() { return is_file( $this->path ); } /** * Get the file size in bytes * * @return int|bool */ public function getSize() { AtEase::suppressWarnings(); $size = filesize( $this->path ); AtEase::restoreWarnings(); return $size; } /** * Get the file's last-modified timestamp * * @return string|bool TS_MW timestamp or false on failure */ public function getTimestamp() { AtEase::suppressWarnings(); $timestamp = filemtime( $this->path ); AtEase::restoreWarnings(); if ( $timestamp !== false ) { $timestamp = ConvertibleTimestamp::convert( TS_MW, $timestamp ); } return $timestamp; } /** * Get an associative array containing information about * a file with the given storage path. * * Resulting array fields include: * - fileExists * - size (filesize in bytes) * - mime (as major/minor) * - file-mime (as major/minor) * - sha1 (in base 36) * - major_mime * - minor_mime * * @param string|bool $ext The file extension, or true to extract it from the filename. * Set it to false to ignore the extension. Currently unused. * @return array */ public function getProps( $ext = true ) { $info = self::placeholderProps(); $info['fileExists'] = $this->exists(); if ( $info['fileExists'] ) { $info['size'] = $this->getSize(); // bytes $info['sha1'] = $this->getSha1Base36(); $mime = mime_content_type( $this->path ); # MIME type according to file contents $info['file-mime'] = ( $mime === false ) ? 'unknown/unknown' : $mime; # logical MIME type $info['mime'] = $mime; if ( strpos( $mime, '/' ) !== false ) { [ $info['major_mime'], $info['minor_mime'] ] = explode( '/', $mime, 2 ); } else { [ $info['major_mime'], $info['minor_mime'] ] = [ $mime, 'unknown' ]; } } return $info; } /** * Placeholder file properties to use for files that don't exist * * Resulting array fields include: * - fileExists * - size (filesize in bytes) * - mime (as major/minor) * - file-mime (as major/minor) * - sha1 (in base 36) * - major_mime * - minor_mime * * @return array */ public static function placeholderProps() { $info = []; $info['fileExists'] = false; $info['size'] = 0; $info['file-mime'] = null; $info['major_mime'] = null; $info['minor_mime'] = null; $info['mime'] = null; $info['sha1'] = ''; return $info; } /** * Get a SHA-1 hash of a file in the local filesystem, in base-36 lower case * encoding, zero padded to 31 digits. * * 160 log 2 / log 36 = 30.95, so the 160-bit hash fills 31 digits in base 36 * fairly neatly. * * @param bool $recache * @return bool|string False on failure */ public function getSha1Base36( $recache = false ) { if ( $this->sha1Base36 !== null && !$recache ) { return $this->sha1Base36; } AtEase::suppressWarnings(); $this->sha1Base36 = sha1_file( $this->path ); AtEase::restoreWarnings(); if ( $this->sha1Base36 !== false ) { $this->sha1Base36 = \Wikimedia\base_convert( $this->sha1Base36, 16, 36, 31 ); } return $this->sha1Base36; } /** * Get the final file extension from a file system path * * @param string $path * @return string */ public static function extensionFromPath( $path ) { $i = strrpos( $path, '.' ); return strtolower( $i ? substr( $path, $i + 1 ) : '' ); } /** * Get an associative array containing information about a file in the local filesystem. * * @param string $path Absolute local filesystem path * @param string|bool $ext The file extension, or true to extract it from the filename. * Set it to false to ignore the extension. * @return array */ public static function getPropsFromPath( $path, $ext = true ) { $fsFile = new self( $path ); return $fsFile->getProps( $ext ); } /** * Get a SHA-1 hash of a file in the local filesystem, in base-36 lower case * encoding, zero padded to 31 digits. * * 160 log 2 / log 36 = 30.95, so the 160-bit hash fills 31 digits in base 36 * fairly neatly. * * @param string $path * @return false|string False on failure */ public static function getSha1Base36FromPath( $path ) { $fsFile = new self( $path ); return $fsFile->getSha1Base36(); } } /** @deprecated class alias since 1.43 */ class_alias( FSFile::class, 'FSFile' ); PK ! ��P(� � ( filebackend/fsfile/TempFSFileFactory.phpnu �Iw�� <?php namespace MediaWiki\FileBackend\FSFile; use Wikimedia\AtEase\AtEase; use Wikimedia\FileBackend\FSFile\TempFSFile; /** * @ingroup FileBackend */ class TempFSFileFactory { /** @var string|null */ private $tmpDirectory; /** * @param string|null $tmpDirectory A directory to put the temporary files in, e.g., * $wgTmpDirectory. If null, we'll try to find one ourselves. */ public function __construct( $tmpDirectory = null ) { $this->tmpDirectory = $tmpDirectory; } /** * Make a new temporary file on the file system. * Temporary files may be purged when the file object falls out of scope. * * @param string $prefix * @param string $extension Optional file extension * @return TempFSFile|null */ public function newTempFSFile( $prefix, $extension = '' ) { $ext = ( $extension != '' ) ? ".{$extension}" : ''; $tmpDirectory = $this->tmpDirectory; if ( !is_string( $tmpDirectory ) ) { $tmpDirectory = TempFSFile::getUsableTempDirectory(); } $attempts = 5; while ( $attempts-- ) { $hex = sprintf( '%06x%06x', mt_rand( 0, 0xffffff ), mt_rand( 0, 0xffffff ) ); $path = "$tmpDirectory/$prefix$hex$ext"; AtEase::suppressWarnings(); $newFileHandle = fopen( $path, 'x' ); AtEase::restoreWarnings(); if ( $newFileHandle ) { fclose( $newFileHandle ); $tmpFile = new TempFSFile( $path ); $tmpFile->autocollect(); // Safely instantiated, end loop. return $tmpFile; } } // Give up return null; // @codeCoverageIgnore } } PK ! rA� � ! filebackend/fsfile/TempFSFile.phpnu �Iw�� <?php /** * Location holder of files stored temporarily * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file * @ingroup FileBackend */ namespace Wikimedia\FileBackend\FSFile; use MediaWiki\FileBackend\FSFile\TempFSFileFactory; use RuntimeException; use WeakMap; use Wikimedia\AtEase\AtEase; /** * This class is used to hold the location and do limited manipulation * of files stored temporarily (this will be whatever wfTempDir() returns) * * @ingroup FileBackend */ class TempFSFile extends FSFile { /** @var bool Garbage collect the temp file */ protected $canDelete = false; /** @var array Map of (path => 1) for paths to delete on shutdown */ protected static $pathsCollect = null; /** * A WeakMap where the key is an object which depends on the file, and the * value is a TempFSFile responsible for deleting the file. This keeps each * TempFSFile alive until all associated objects have been destroyed. * @var WeakMap|null */ private static $references; /** * Do not call directly. Use TempFSFileFactory * * @param string $path */ public function __construct( $path ) { parent::__construct( $path ); if ( self::$pathsCollect === null ) { // @codeCoverageIgnoreStart self::$pathsCollect = []; register_shutdown_function( [ __CLASS__, 'purgeAllOnShutdown' ] ); // @codeCoverageIgnoreEnd } } /** * Make a new temporary file on the file system. * Temporary files may be purged when the file object falls out of scope. * * @deprecated since 1.34, use TempFSFileFactory directly * * @param string $prefix * @param string $extension Optional file extension * @param string|null $tmpDirectory Optional parent directory * @return TempFSFile|null */ public static function factory( $prefix, $extension = '', $tmpDirectory = null ) { return ( new TempFSFileFactory( $tmpDirectory ) )->newTempFSFile( $prefix, $extension ); } /** * @todo Is there any useful way to test this? Would it be useful to make this non-static on * TempFSFileFactory? * * @return string Filesystem path to a temporary directory * @throws RuntimeException if no writable temporary directory can be found */ public static function getUsableTempDirectory() { $tmpDir = array_map( 'getenv', [ 'TMPDIR', 'TMP', 'TEMP' ] ); $tmpDir[] = sys_get_temp_dir(); $tmpDir[] = ini_get( 'upload_tmp_dir' ); foreach ( $tmpDir as $tmp ) { if ( $tmp != '' && is_dir( $tmp ) && is_writable( $tmp ) ) { return $tmp; } } // PHP on Windows will detect C:\Windows\Temp as not writable even though PHP can write to // it so create a directory within that called 'mwtmp' with a suffix of the user running // the current process. // The user is included as if various scripts are run by different users they will likely // not be able to access each others temporary files. if ( PHP_OS_FAMILY === 'Windows' ) { $tmp = sys_get_temp_dir() . DIRECTORY_SEPARATOR . 'mwtmp-' . get_current_user(); if ( !is_dir( $tmp ) ) { mkdir( $tmp ); } if ( is_dir( $tmp ) && is_writable( $tmp ) ) { return $tmp; } } throw new RuntimeException( 'No writable temporary directory could be found. ' . 'Please explicitly specify a writable directory in configuration.' ); } /** * Purge this file off the file system * * @return bool Success */ public function purge() { $this->canDelete = false; // done AtEase::suppressWarnings(); $ok = unlink( $this->path ); AtEase::restoreWarnings(); unset( self::$pathsCollect[$this->path] ); return $ok; } /** * Clean up the temporary file only after an object goes out of scope * * @param mixed $object * @return TempFSFile This object */ public function bind( $object ) { if ( is_object( $object ) ) { // Use a WeakMap on PHP >= 8.0 to avoid dynamic property creation (T324894) if ( PHP_VERSION_ID >= 80000 ) { if ( self::$references === null ) { self::$references = new WeakMap; } self::$references[$object] = $this; } else { // PHP 7.4 if ( !isset( $object->tempFSFileReferences ) ) { // Init first since $object might use __get() and return only a copy variable $object->tempFSFileReferences = []; } $object->tempFSFileReferences[] = $this; } } return $this; } /** * Set flag to not clean up after the temporary file * * @return TempFSFile This object */ public function preserve() { $this->canDelete = false; unset( self::$pathsCollect[$this->path] ); return $this; } /** * Set flag clean up after the temporary file * * @return TempFSFile This object */ public function autocollect() { $this->canDelete = true; self::$pathsCollect[$this->path] = 1; return $this; } /** * Try to make sure that all files are purged on error * * This method should only be called internally * * @codeCoverageIgnore */ public static function purgeAllOnShutdown() { foreach ( self::$pathsCollect as $path => $unused ) { AtEase::suppressWarnings(); unlink( $path ); AtEase::restoreWarnings(); } } /** * Cleans up after the temporary file by deleting it */ public function __destruct() { if ( $this->canDelete ) { $this->purge(); } } } /** @deprecated class alias since 1.43 */ class_alias( TempFSFile::class, 'TempFSFile' ); PK ! ���` ` filebackend/SwiftFileBackend.phpnu �Iw�� <?php /** * OpenStack Swift based file backend. * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file * @ingroup FileBackend * @author Russ Nelson */ namespace Wikimedia\FileBackend; use Exception; use LockManager; use MapCacheLRU; use MediaWiki\Json\FormatJson; use MediaWiki\Utils\MWTimestamp; use Psr\Log\LoggerInterface; use Shellbox\Command\BoxedCommand; use StatusValue; use stdClass; use Wikimedia\AtEase\AtEase; use Wikimedia\FileBackend\FileIteration\SwiftFileBackendDirList; use Wikimedia\FileBackend\FileIteration\SwiftFileBackendFileList; use Wikimedia\FileBackend\FileOpHandle\SwiftFileOpHandle; use Wikimedia\Http\MultiHttpClient; use Wikimedia\ObjectCache\BagOStuff; use Wikimedia\ObjectCache\EmptyBagOStuff; use Wikimedia\ObjectCache\WANObjectCache; use Wikimedia\RequestTimeout\TimeoutException; /** * @brief Class for an OpenStack Swift (or Ceph RGW) based file backend. * * StatusValue messages should avoid mentioning the Swift account name. * Likewise, error suppression should be used to avoid path disclosure. * * @ingroup FileBackend * @since 1.19 */ class SwiftFileBackend extends FileBackendStore { private const DEFAULT_HTTP_OPTIONS = [ 'httpVersion' => 'v1.1' ]; private const AUTH_FAILURE_ERROR = 'Could not connect due to prior authentication failure'; /** @var MultiHttpClient */ protected $http; /** @var int TTL in seconds */ protected $authTTL; /** @var string Authentication base URL (without version) */ protected $swiftAuthUrl; /** @var string Override of storage base URL */ protected $swiftStorageUrl; /** @var string Swift user (account:user) to authenticate as */ protected $swiftUser; /** @var string Secret key for user */ protected $swiftKey; /** @var string Shared secret value for making temp URLs */ protected $swiftTempUrlKey; /** @var bool */ protected $canShellboxGetTempUrl; /** @var string|null */ protected $shellboxIpRange; /** @var string S3 access key (RADOS Gateway) */ protected $rgwS3AccessKey; /** @var string S3 authentication key (RADOS Gateway) */ protected $rgwS3SecretKey; /** @var array Additional users (account:user) with read permissions on public containers */ protected $readUsers; /** @var array Additional users (account:user) with write permissions on public containers */ protected $writeUsers; /** @var array Additional users (account:user) with read permissions on private containers */ protected $secureReadUsers; /** @var array Additional users (account:user) with write permissions on private containers */ protected $secureWriteUsers; /** @var BagOStuff */ protected $srvCache; /** @var MapCacheLRU Container stat cache */ protected $containerStatCache; /** @var array|null */ protected $authCreds; /** @var int|null UNIX timestamp */ protected $authErrorTimestamp = null; /** @var bool Whether the server is an Ceph RGW */ protected $isRGW = false; /** * @see FileBackendStore::__construct() * @param array $config Params include: * - swiftAuthUrl : Swift authentication server URL * - swiftUser : Swift user used by MediaWiki (account:username) * - swiftKey : Swift authentication key for the above user * - swiftAuthTTL : Swift authentication TTL (seconds) * - swiftTempUrlKey : Swift "X-Account-Meta-Temp-URL-Key" value on the account. * Do not set this until it has been set in the backend. * - canShellboxGetTempUrl : Set this to true to generate a TempURL allowing Shellbox to * directly fetch files from Swift. swiftTempUrlKey should be set. * - shellboxIpRange : An IP range string to use when generating TempURLs for Shellbox. * Specifying this will improve security by preventing exfiltrated * TempURLs from being usable outside the server. * - swiftStorageUrl : Swift storage URL (overrides that of the authentication response). * This is useful to set if a TLS proxy is in use. * - shardViaHashLevels : Map of container names to sharding config with: * - base : base of hash characters, 16 or 36 * - levels : the number of hash levels (and digits) * - repeat : hash subdirectories are prefixed with all the * parent hash directory names (e.g. "a/ab/abc") * - cacheAuthInfo : Whether to cache authentication tokens in APC, etc. * If those are not available, then the main cache will be used. * This is probably insecure in shared hosting environments. * - rgwS3AccessKey : Rados Gateway S3 "access key" value on the account. * Do not set this until it has been set in the backend. * This is used for generating expiring pre-authenticated URLs. * Only use this when using rgw and to work around * http://tracker.newdream.net/issues/3454. * - rgwS3SecretKey : Rados Gateway S3 "secret key" value on the account. * Do not set this until it has been set in the backend. * This is used for generating expiring pre-authenticated URLs. * Only use this when using rgw and to work around * http://tracker.newdream.net/issues/3454. * - readUsers : Swift users with read access to public containers (account:username) * - writeUsers : Swift users with write access to public containers (account:username) * - secureReadUsers : Swift users with read access to private containers (account:username) * - secureWriteUsers : Swift users with write access to private containers (account:username) * - connTimeout : The HTTP connect timeout to use when connecting to Swift, in * seconds. * - reqTimeout : The HTTP request timeout to use when communicating with Swift, in * seconds. */ public function __construct( array $config ) { parent::__construct( $config ); // Required settings $this->swiftAuthUrl = $config['swiftAuthUrl']; $this->swiftUser = $config['swiftUser']; $this->swiftKey = $config['swiftKey']; // Optional settings $this->authTTL = $config['swiftAuthTTL'] ?? 15 * 60; // some sensible number $this->swiftTempUrlKey = $config['swiftTempUrlKey'] ?? ''; $this->canShellboxGetTempUrl = $config['canShellboxGetTempUrl'] ?? false; $this->shellboxIpRange = $config['shellboxIpRange'] ?? null; $this->swiftStorageUrl = $config['swiftStorageUrl'] ?? null; $this->shardViaHashLevels = $config['shardViaHashLevels'] ?? ''; $this->rgwS3AccessKey = $config['rgwS3AccessKey'] ?? ''; $this->rgwS3SecretKey = $config['rgwS3SecretKey'] ?? ''; // HTTP helper client $httpOptions = []; foreach ( [ 'connTimeout', 'reqTimeout' ] as $optionName ) { if ( isset( $config[$optionName] ) ) { $httpOptions[$optionName] = $config[$optionName]; } } $this->http = new MultiHttpClient( $httpOptions ); $this->http->setLogger( $this->logger ); // Cache container information to mask latency if ( isset( $config['wanCache'] ) && $config['wanCache'] instanceof WANObjectCache ) { $this->memCache = $config['wanCache']; } // Process cache for container info $this->containerStatCache = new MapCacheLRU( 300 ); // Cache auth token information to avoid RTTs if ( !empty( $config['cacheAuthInfo'] ) && isset( $config['srvCache'] ) ) { $this->srvCache = $config['srvCache']; } else { $this->srvCache = new EmptyBagOStuff(); } $this->readUsers = $config['readUsers'] ?? []; $this->writeUsers = $config['writeUsers'] ?? []; $this->secureReadUsers = $config['secureReadUsers'] ?? []; $this->secureWriteUsers = $config['secureWriteUsers'] ?? []; // Per https://docs.openstack.org/swift/latest/overview_large_objects.html // we need to split objects if they are larger than 5 GB. Support for // splitting objects has not yet been implemented by this class // so limit max file size to 5GiB. $this->maxFileSize = 5 * 1024 * 1024 * 1024; } public function setLogger( LoggerInterface $logger ) { parent::setLogger( $logger ); $this->http->setLogger( $logger ); } public function getFeatures() { return ( self::ATTR_UNICODE_PATHS | self::ATTR_HEADERS | self::ATTR_METADATA ); } protected function resolveContainerPath( $container, $relStoragePath ) { if ( !mb_check_encoding( $relStoragePath, 'UTF-8' ) ) { return null; // not UTF-8, makes it hard to use CF and the swift HTTP API } elseif ( strlen( rawurlencode( $relStoragePath ) ) > 1024 ) { return null; // too long for Swift } return $relStoragePath; } public function isPathUsableInternal( $storagePath ) { [ $container, $rel ] = $this->resolveStoragePathReal( $storagePath ); if ( $rel === null ) { return false; // invalid } return is_array( $this->getContainerStat( $container ) ); } /** * Filter/normalize a header map to only include mutable "content-"/"x-content-" headers * * Mutable headers can be changed via HTTP POST even if the file content is the same * * @see https://docs.openstack.org/api-ref/object-store * @param string[] $headers Map of (header => value) for a swift object * @return string[] Map of (header => value) for Content-* headers mutable via POST */ protected function extractMutableContentHeaders( array $headers ) { $contentHeaders = []; // Normalize casing, and strip out illegal headers foreach ( $headers as $name => $value ) { $name = strtolower( $name ); if ( $name === 'x-delete-at' && is_numeric( $value ) ) { // Expects a Unix Epoch date $contentHeaders[$name] = $value; } elseif ( $name === 'x-delete-after' && is_numeric( $value ) ) { // Expects number of minutes time to live. $contentHeaders[$name] = $value; } elseif ( preg_match( '/^(x-)?content-(?!length$)/', $name ) ) { // Only allow content-* and x-content-* headers (but not content-length) $contentHeaders[$name] = $value; } elseif ( $name === 'content-type' && strlen( $value ) ) { // This header can be set to a value but not unset $contentHeaders[$name] = $value; } } // By default, Swift has annoyingly low maximum header value limits if ( isset( $contentHeaders['content-disposition'] ) ) { $maxLength = 255; // @note: assume FileBackend::makeContentDisposition() already used $offset = $maxLength - strlen( $contentHeaders['content-disposition'] ); if ( $offset < 0 ) { $pos = strrpos( $contentHeaders['content-disposition'], ';', $offset ); $contentHeaders['content-disposition'] = $pos === false ? '' : trim( substr( $contentHeaders['content-disposition'], 0, $pos ) ); } } return $contentHeaders; } /** * @see https://docs.openstack.org/api-ref/object-store * @param string[] $headers Map of (header => value) for a swift object * @return string[] Map of (metadata header name => metadata value) */ protected function extractMetadataHeaders( array $headers ) { $metadataHeaders = []; foreach ( $headers as $name => $value ) { $name = strtolower( $name ); if ( strpos( $name, 'x-object-meta-' ) === 0 ) { $metadataHeaders[$name] = $value; } } return $metadataHeaders; } /** * @see https://docs.openstack.org/api-ref/object-store * @param string[] $headers Map of (header => value) for a swift object * @return string[] Map of (metadata key name => metadata value) */ protected function getMetadataFromHeaders( array $headers ) { $prefixLen = strlen( 'x-object-meta-' ); $metadata = []; foreach ( $this->extractMetadataHeaders( $headers ) as $name => $value ) { $metadata[substr( $name, $prefixLen )] = $value; } return $metadata; } protected function doCreateInternal( array $params ) { $status = $this->newStatus(); [ $dstCont, $dstRel ] = $this->resolveStoragePathReal( $params['dst'] ); if ( $dstRel === null ) { $status->fatal( 'backend-fail-invalidpath', $params['dst'] ); return $status; } // Headers that are not strictly a function of the file content $mutableHeaders = $this->extractMutableContentHeaders( $params['headers'] ?? [] ); // Make sure that the "content-type" header is set to something sensible $mutableHeaders['content-type'] ??= $this->getContentType( $params['dst'], $params['content'], null ); $reqs = [ [ 'method' => 'PUT', 'container' => $dstCont, 'relPath' => $dstRel, 'headers' => array_merge( $mutableHeaders, [ 'etag' => md5( $params['content'] ), 'content-length' => strlen( $params['content'] ), 'x-object-meta-sha1base36' => \Wikimedia\base_convert( sha1( $params['content'] ), 16, 36, 31 ) ] ), 'body' => $params['content'] ] ]; $method = __METHOD__; $handler = function ( array $request, StatusValue $status ) use ( $method, $params ) { [ $rcode, $rdesc, , $rbody, $rerr ] = $request['response']; if ( $rcode === 201 || $rcode === 202 ) { // good } elseif ( $rcode === 412 ) { $status->fatal( 'backend-fail-contenttype', $params['dst'] ); } else { $this->onError( $status, $method, $params, $rerr, $rcode, $rdesc, $rbody ); } return SwiftFileOpHandle::CONTINUE_IF_OK; }; $opHandle = new SwiftFileOpHandle( $this, $handler, $reqs ); if ( !empty( $params['async'] ) ) { // deferred $status->value = $opHandle; } else { // actually write the object in Swift $status->merge( current( $this->executeOpHandlesInternal( [ $opHandle ] ) ) ); } return $status; } protected function doStoreInternal( array $params ) { $status = $this->newStatus(); [ $dstCont, $dstRel ] = $this->resolveStoragePathReal( $params['dst'] ); if ( $dstRel === null ) { $status->fatal( 'backend-fail-invalidpath', $params['dst'] ); return $status; } // Open a handle to the source file so that it can be streamed. The size and hash // will be computed using the handle. In the off chance that the source file changes // during this operation, the PUT will fail due to an ETag mismatch and be aborted. AtEase::suppressWarnings(); $srcHandle = fopen( $params['src'], 'rb' ); AtEase::restoreWarnings(); if ( $srcHandle === false ) { // source doesn't exist? $status->fatal( 'backend-fail-notexists', $params['src'] ); return $status; } // Compute the MD5 and SHA-1 hashes in one pass $srcSize = fstat( $srcHandle )['size']; $md5Context = hash_init( 'md5' ); $sha1Context = hash_init( 'sha1' ); $hashDigestSize = 0; while ( !feof( $srcHandle ) ) { $buffer = (string)fread( $srcHandle, 131_072 ); // 128 KiB hash_update( $md5Context, $buffer ); hash_update( $sha1Context, $buffer ); $hashDigestSize += strlen( $buffer ); } // Reset the handle back to the beginning so that it can be streamed rewind( $srcHandle ); if ( $hashDigestSize !== $srcSize ) { $status->fatal( 'backend-fail-hash', $params['src'] ); return $status; } // Headers that are not strictly a function of the file content $mutableHeaders = $this->extractMutableContentHeaders( $params['headers'] ?? [] ); // Make sure that the "content-type" header is set to something sensible $mutableHeaders['content-type'] ??= $this->getContentType( $params['dst'], null, $params['src'] ); $reqs = [ [ 'method' => 'PUT', 'container' => $dstCont, 'relPath' => $dstRel, 'headers' => array_merge( $mutableHeaders, [ 'content-length' => $srcSize, 'etag' => hash_final( $md5Context ), 'x-object-meta-sha1base36' => \Wikimedia\base_convert( hash_final( $sha1Context ), 16, 36, 31 ) ] ), 'body' => $srcHandle // resource ] ]; $method = __METHOD__; $handler = function ( array $request, StatusValue $status ) use ( $method, $params ) { [ $rcode, $rdesc, , $rbody, $rerr ] = $request['response']; if ( $rcode === 201 || $rcode === 202 ) { // good } elseif ( $rcode === 412 ) { $status->fatal( 'backend-fail-contenttype', $params['dst'] ); } else { $this->onError( $status, $method, $params, $rerr, $rcode, $rdesc, $rbody ); } return SwiftFileOpHandle::CONTINUE_IF_OK; }; $opHandle = new SwiftFileOpHandle( $this, $handler, $reqs ); $opHandle->resourcesToClose[] = $srcHandle; if ( !empty( $params['async'] ) ) { // deferred $status->value = $opHandle; } else { // actually write the object in Swift $status->merge( current( $this->executeOpHandlesInternal( [ $opHandle ] ) ) ); } return $status; } protected function doCopyInternal( array $params ) { $status = $this->newStatus(); [ $srcCont, $srcRel ] = $this->resolveStoragePathReal( $params['src'] ); if ( $srcRel === null ) { $status->fatal( 'backend-fail-invalidpath', $params['src'] ); return $status; } [ $dstCont, $dstRel ] = $this->resolveStoragePathReal( $params['dst'] ); if ( $dstRel === null ) { $status->fatal( 'backend-fail-invalidpath', $params['dst'] ); return $status; } $reqs = [ [ 'method' => 'PUT', 'container' => $dstCont, 'relPath' => $dstRel, 'headers' => array_merge( $this->extractMutableContentHeaders( $params['headers'] ?? [] ), [ 'x-copy-from' => '/' . rawurlencode( $srcCont ) . '/' . str_replace( "%2F", "/", rawurlencode( $srcRel ) ) ] ) ] ]; $method = __METHOD__; $handler = function ( array $request, StatusValue $status ) use ( $method, $params ) { [ $rcode, $rdesc, , $rbody, $rerr ] = $request['response']; if ( $rcode === 201 ) { // good } elseif ( $rcode === 404 ) { if ( empty( $params['ignoreMissingSource'] ) ) { $status->fatal( 'backend-fail-copy', $params['src'], $params['dst'] ); } } else { $this->onError( $status, $method, $params, $rerr, $rcode, $rdesc, $rbody ); } return SwiftFileOpHandle::CONTINUE_IF_OK; }; $opHandle = new SwiftFileOpHandle( $this, $handler, $reqs ); if ( !empty( $params['async'] ) ) { // deferred $status->value = $opHandle; } else { // actually write the object in Swift $status->merge( current( $this->executeOpHandlesInternal( [ $opHandle ] ) ) ); } return $status; } protected function doMoveInternal( array $params ) { $status = $this->newStatus(); [ $srcCont, $srcRel ] = $this->resolveStoragePathReal( $params['src'] ); if ( $srcRel === null ) { $status->fatal( 'backend-fail-invalidpath', $params['src'] ); return $status; } [ $dstCont, $dstRel ] = $this->resolveStoragePathReal( $params['dst'] ); if ( $dstRel === null ) { $status->fatal( 'backend-fail-invalidpath', $params['dst'] ); return $status; } $reqs = [ [ 'method' => 'PUT', 'container' => $dstCont, 'relPath' => $dstRel, 'headers' => array_merge( $this->extractMutableContentHeaders( $params['headers'] ?? [] ), [ 'x-copy-from' => '/' . rawurlencode( $srcCont ) . '/' . str_replace( "%2F", "/", rawurlencode( $srcRel ) ) ] ) ] ]; if ( "{$srcCont}/{$srcRel}" !== "{$dstCont}/{$dstRel}" ) { $reqs[] = [ 'method' => 'DELETE', 'container' => $srcCont, 'relPath' => $srcRel, 'headers' => [] ]; } $method = __METHOD__; $handler = function ( array $request, StatusValue $status ) use ( $method, $params ) { [ $rcode, $rdesc, , $rbody, $rerr ] = $request['response']; if ( $request['method'] === 'PUT' && $rcode === 201 ) { // good } elseif ( $request['method'] === 'DELETE' && $rcode === 204 ) { // good } elseif ( $rcode === 404 ) { if ( empty( $params['ignoreMissingSource'] ) ) { $status->fatal( 'backend-fail-move', $params['src'], $params['dst'] ); } else { // Leave Status as OK but skip the DELETE request return SwiftFileOpHandle::CONTINUE_NO; } } else { $this->onError( $status, $method, $params, $rerr, $rcode, $rdesc, $rbody ); } return SwiftFileOpHandle::CONTINUE_IF_OK; }; $opHandle = new SwiftFileOpHandle( $this, $handler, $reqs ); if ( !empty( $params['async'] ) ) { // deferred $status->value = $opHandle; } else { // actually move the object in Swift $status->merge( current( $this->executeOpHandlesInternal( [ $opHandle ] ) ) ); } return $status; } protected function doDeleteInternal( array $params ) { $status = $this->newStatus(); [ $srcCont, $srcRel ] = $this->resolveStoragePathReal( $params['src'] ); if ( $srcRel === null ) { $status->fatal( 'backend-fail-invalidpath', $params['src'] ); return $status; } $reqs = [ [ 'method' => 'DELETE', 'container' => $srcCont, 'relPath' => $srcRel, 'headers' => [] ] ]; $method = __METHOD__; $handler = function ( array $request, StatusValue $status ) use ( $method, $params ) { [ $rcode, $rdesc, , $rbody, $rerr ] = $request['response']; if ( $rcode === 204 ) { // good } elseif ( $rcode === 404 ) { if ( empty( $params['ignoreMissingSource'] ) ) { $status->fatal( 'backend-fail-delete', $params['src'] ); } } else { $this->onError( $status, $method, $params, $rerr, $rcode, $rdesc, $rbody ); } return SwiftFileOpHandle::CONTINUE_IF_OK; }; $opHandle = new SwiftFileOpHandle( $this, $handler, $reqs ); if ( !empty( $params['async'] ) ) { // deferred $status->value = $opHandle; } else { // actually delete the object in Swift $status->merge( current( $this->executeOpHandlesInternal( [ $opHandle ] ) ) ); } return $status; } protected function doDescribeInternal( array $params ) { $status = $this->newStatus(); [ $srcCont, $srcRel ] = $this->resolveStoragePathReal( $params['src'] ); if ( $srcRel === null ) { $status->fatal( 'backend-fail-invalidpath', $params['src'] ); return $status; } // Fetch the old object headers/metadata...this should be in stat cache by now $stat = $this->getFileStat( [ 'src' => $params['src'], 'latest' => 1 ] ); if ( $stat && !isset( $stat['xattr'] ) ) { // older cache entry $stat = $this->doGetFileStat( [ 'src' => $params['src'], 'latest' => 1 ] ); } if ( !$stat ) { $status->fatal( 'backend-fail-describe', $params['src'] ); return $status; } // Swift object POST clears any prior headers, so merge the new and old headers here. // Also, during, POST, libcurl adds "Content-Type: application/x-www-form-urlencoded" // if "Content-Type" is not set, which would clobber the header value for the object. $oldMetadataHeaders = []; foreach ( $stat['xattr']['metadata'] as $name => $value ) { $oldMetadataHeaders["x-object-meta-$name"] = $value; } $newContentHeaders = $this->extractMutableContentHeaders( $params['headers'] ?? [] ); $oldContentHeaders = $stat['xattr']['headers']; $reqs = [ [ 'method' => 'POST', 'container' => $srcCont, 'relPath' => $srcRel, 'headers' => $oldMetadataHeaders + $newContentHeaders + $oldContentHeaders ] ]; $method = __METHOD__; $handler = function ( array $request, StatusValue $status ) use ( $method, $params ) { [ $rcode, $rdesc, , $rbody, $rerr ] = $request['response']; if ( $rcode === 202 ) { // good } elseif ( $rcode === 404 ) { $status->fatal( 'backend-fail-describe', $params['src'] ); } else { $this->onError( $status, $method, $params, $rerr, $rcode, $rdesc, $rbody ); } }; $opHandle = new SwiftFileOpHandle( $this, $handler, $reqs ); if ( !empty( $params['async'] ) ) { // deferred $status->value = $opHandle; } else { // actually change the object in Swift $status->merge( current( $this->executeOpHandlesInternal( [ $opHandle ] ) ) ); } return $status; } /** * @inheritDoc */ protected function doPrepareInternal( $fullCont, $dir, array $params ) { $status = $this->newStatus(); // (a) Check if container already exists $stat = $this->getContainerStat( $fullCont ); if ( is_array( $stat ) ) { return $status; // already there } elseif ( $stat === self::RES_ERROR ) { $status->fatal( 'backend-fail-internal', $this->name ); $this->logger->error( __METHOD__ . ': cannot get container stat' ); } else { // (b) Create container as needed with proper ACLs $params['op'] = 'prepare'; $status->merge( $this->createContainer( $fullCont, $params ) ); } return $status; } protected function doSecureInternal( $fullCont, $dir, array $params ) { $status = $this->newStatus(); if ( empty( $params['noAccess'] ) ) { return $status; // nothing to do } $stat = $this->getContainerStat( $fullCont ); if ( is_array( $stat ) ) { $readUsers = array_merge( $this->secureReadUsers, [ $this->swiftUser ] ); $writeUsers = array_merge( $this->secureWriteUsers, [ $this->swiftUser ] ); // Make container private to end-users... $status->merge( $this->setContainerAccess( $fullCont, $readUsers, $writeUsers ) ); } elseif ( $stat === self::RES_ABSENT ) { $status->fatal( 'backend-fail-usable', $params['dir'] ); } else { $status->fatal( 'backend-fail-internal', $this->name ); $this->logger->error( __METHOD__ . ': cannot get container stat' ); } return $status; } protected function doPublishInternal( $fullCont, $dir, array $params ) { $status = $this->newStatus(); if ( empty( $params['access'] ) ) { return $status; // nothing to do } $stat = $this->getContainerStat( $fullCont ); if ( is_array( $stat ) ) { $readUsers = array_merge( $this->readUsers, [ $this->swiftUser, '.r:*' ] ); if ( !empty( $params['listing'] ) ) { array_push( $readUsers, '.rlistings' ); } $writeUsers = array_merge( $this->writeUsers, [ $this->swiftUser ] ); // Make container public to end-users... $status->merge( $this->setContainerAccess( $fullCont, $readUsers, $writeUsers ) ); } elseif ( $stat === self::RES_ABSENT ) { $status->fatal( 'backend-fail-usable', $params['dir'] ); } else { $status->fatal( 'backend-fail-internal', $this->name ); $this->logger->error( __METHOD__ . ': cannot get container stat' ); } return $status; } protected function doCleanInternal( $fullCont, $dir, array $params ) { $status = $this->newStatus(); // Only containers themselves can be removed, all else is virtual if ( $dir != '' ) { return $status; // nothing to do } // (a) Check the container $stat = $this->getContainerStat( $fullCont, true ); if ( $stat === self::RES_ABSENT ) { return $status; // ok, nothing to do } elseif ( $stat === self::RES_ERROR ) { $status->fatal( 'backend-fail-internal', $this->name ); $this->logger->error( __METHOD__ . ': cannot get container stat' ); } elseif ( is_array( $stat ) && $stat['count'] == 0 ) { // (b) Delete the container if empty $params['op'] = 'clean'; $status->merge( $this->deleteContainer( $fullCont, $params ) ); } return $status; } protected function doGetFileStat( array $params ) { $params = [ 'srcs' => [ $params['src'] ], 'concurrency' => 1 ] + $params; unset( $params['src'] ); $stats = $this->doGetFileStatMulti( $params ); return reset( $stats ); } /** * Convert dates like "Tue, 03 Jan 2012 22:01:04 GMT"/"2013-05-11T07:37:27.678360Z". * Dates might also come in like "2013-05-11T07:37:27.678360" from Swift listings, * missing the timezone suffix (though Ceph RGW does not appear to have this bug). * * @param string $ts * @param int $format Output format (TS_* constant) * @return string * @throws FileBackendError */ protected function convertSwiftDate( $ts, $format = TS_MW ) { try { $timestamp = new MWTimestamp( $ts ); return $timestamp->getTimestamp( $format ); } catch ( TimeoutException $e ) { throw $e; } catch ( Exception $e ) { throw new FileBackendError( $e->getMessage() ); } } /** * Fill in any missing object metadata and save it to Swift * * @param array $objHdrs Object response headers * @param string $path Storage path to object * @return array New headers */ protected function addMissingHashMetadata( array $objHdrs, $path ) { if ( isset( $objHdrs['x-object-meta-sha1base36'] ) ) { return $objHdrs; // nothing to do } /** @noinspection PhpUnusedLocalVariableInspection */ $ps = $this->scopedProfileSection( __METHOD__ . "-{$this->name}" ); $this->logger->error( __METHOD__ . ": {path} was not stored with SHA-1 metadata.", [ 'path' => $path ] ); $objHdrs['x-object-meta-sha1base36'] = false; // Find prior custom HTTP headers $postHeaders = $this->extractMutableContentHeaders( $objHdrs ); // Find prior metadata headers $postHeaders += $this->extractMetadataHeaders( $objHdrs ); $status = $this->newStatus(); /** @noinspection PhpUnusedLocalVariableInspection */ $scopeLockS = $this->getScopedFileLocks( [ $path ], LockManager::LOCK_UW, $status ); if ( $status->isOK() ) { $tmpFile = $this->getLocalCopy( [ 'src' => $path, 'latest' => 1 ] ); if ( $tmpFile ) { $hash = $tmpFile->getSha1Base36(); if ( $hash !== false ) { $objHdrs['x-object-meta-sha1base36'] = $hash; // Merge new SHA1 header into the old ones $postHeaders['x-object-meta-sha1base36'] = $hash; [ $srcCont, $srcRel ] = $this->resolveStoragePathReal( $path ); [ $rcode ] = $this->requestWithAuth( [ 'method' => 'POST', 'container' => $srcCont, 'relPath' => $srcRel, 'headers' => $postHeaders ] ); if ( $rcode >= 200 && $rcode <= 299 ) { $this->deleteFileCache( $path ); return $objHdrs; // success } } } } $this->logger->error( __METHOD__ . ': unable to set SHA-1 metadata for {path}', [ 'path' => $path ] ); return $objHdrs; // failed } protected function doGetFileContentsMulti( array $params ) { $ep = array_diff_key( $params, [ 'srcs' => 1 ] ); // for error logging // Blindly create tmp files and stream to them, catching any exception // if the file does not exist. Do not waste time doing file stats here. $reqs = []; // (path => op) // Initial dummy values to preserve path order $contents = array_fill_keys( $params['srcs'], self::RES_ERROR ); foreach ( $params['srcs'] as $path ) { // each path in this concurrent batch [ $srcCont, $srcRel ] = $this->resolveStoragePathReal( $path ); if ( $srcRel === null ) { continue; // invalid storage path } // Create a new temporary memory file... $handle = fopen( 'php://temp', 'wb' ); if ( $handle ) { $reqs[$path] = [ 'method' => 'GET', 'container' => $srcCont, 'relPath' => $srcRel, 'headers' => $this->headersFromParams( $params ), 'stream' => $handle, ]; } } $reqs = $this->requestMultiWithAuth( $reqs, [ 'maxConnsPerHost' => $params['concurrency'] ] ); foreach ( $reqs as $path => $op ) { [ $rcode, $rdesc, $rhdrs, $rbody, $rerr ] = $op['response']; if ( $rcode >= 200 && $rcode <= 299 ) { rewind( $op['stream'] ); // start from the beginning $content = (string)stream_get_contents( $op['stream'] ); $size = strlen( $content ); // Make sure that stream finished if ( $size === (int)$rhdrs['content-length'] ) { $contents[$path] = $content; } else { $contents[$path] = self::RES_ERROR; $rerr = "Got {$size}/{$rhdrs['content-length']} bytes"; $this->onError( null, __METHOD__, [ 'src' => $path ] + $ep, $rerr, $rcode, $rdesc ); } } elseif ( $rcode === 404 ) { $contents[$path] = self::RES_ABSENT; } else { $contents[$path] = self::RES_ERROR; $this->onError( null, __METHOD__, [ 'src' => $path ] + $ep, $rerr, $rcode, $rdesc, $rbody ); } fclose( $op['stream'] ); // close open handle } return $contents; } protected function doDirectoryExists( $fullCont, $dir, array $params ) { $prefix = ( $dir == '' ) ? null : "{$dir}/"; $status = $this->objectListing( $fullCont, 'names', 1, null, $prefix ); if ( $status->isOK() ) { return ( count( $status->value ) ) > 0; } return self::RES_ERROR; } /** * @see FileBackendStore::getDirectoryListInternal() * @param string $fullCont * @param string $dir * @param array $params * @return SwiftFileBackendDirList */ public function getDirectoryListInternal( $fullCont, $dir, array $params ) { return new SwiftFileBackendDirList( $this, $fullCont, $dir, $params ); } /** * @see FileBackendStore::getFileListInternal() * @param string $fullCont * @param string $dir * @param array $params * @return SwiftFileBackendFileList */ public function getFileListInternal( $fullCont, $dir, array $params ) { return new SwiftFileBackendFileList( $this, $fullCont, $dir, $params ); } /** * Do not call this function outside of SwiftFileBackendFileList * * @param string $fullCont Resolved container name * @param string $dir Resolved storage directory with no trailing slash * @param string|null &$after Resolved container relative path used for continuation paging * @param int $limit Max number of items to list * @param array $params Parameters for {@link getDirectoryList()} * @return string[] List of resolved container relative directories directly under $dir * @throws FileBackendError */ public function getDirListPageInternal( $fullCont, $dir, &$after, $limit, array $params ) { $dirs = []; if ( $after === INF ) { return $dirs; // nothing more } /** @noinspection PhpUnusedLocalVariableInspection */ $ps = $this->scopedProfileSection( __METHOD__ . "-{$this->name}" ); $prefix = ( $dir == '' ) ? null : "{$dir}/"; // Non-recursive: only list dirs right under $dir if ( !empty( $params['topOnly'] ) ) { $status = $this->objectListing( $fullCont, 'names', $limit, $after, $prefix, '/' ); if ( !$status->isOK() ) { throw new FileBackendError( "Iterator page I/O error." ); } $objects = $status->value; // @phan-suppress-next-line PhanTypeSuspiciousNonTraversableForeach foreach ( $objects as $object ) { // files and directories if ( substr( $object, -1 ) === '/' ) { $dirs[] = $object; // directories end in '/' } } } else { // Recursive: list all dirs under $dir and its subdirs $getParentDir = static function ( $path ) { return ( $path !== null && strpos( $path, '/' ) !== false ) ? dirname( $path ) : false; }; // Get directory from last item of prior page $lastDir = $getParentDir( $after ); // must be first page $status = $this->objectListing( $fullCont, 'names', $limit, $after, $prefix ); if ( !$status->isOK() ) { throw new FileBackendError( "Iterator page I/O error." ); } $objects = $status->value; // @phan-suppress-next-line PhanTypeSuspiciousNonTraversableForeach foreach ( $objects as $object ) { // files $objectDir = $getParentDir( $object ); // directory of object if ( $objectDir !== false && $objectDir !== $dir ) { // Swift stores paths in UTF-8, using binary sorting. // See function "create_container_table" in common/db.py. // If a directory is not "greater" than the last one, // then it was already listed by the calling iterator. if ( strcmp( $objectDir, $lastDir ) > 0 ) { $pDir = $objectDir; do { // add dir and all its parent dirs $dirs[] = "{$pDir}/"; $pDir = $getParentDir( $pDir ); } while ( $pDir !== false && strcmp( $pDir, $lastDir ) > 0 // not done already && strlen( $pDir ) > strlen( $dir ) // within $dir ); } $lastDir = $objectDir; } } } // Page on the unfiltered directory listing (what is returned may be filtered) if ( count( $objects ) < $limit ) { $after = INF; // avoid a second RTT } else { $after = end( $objects ); // update last item } return $dirs; } /** * Do not call this function outside of SwiftFileBackendFileList * * @param string $fullCont Resolved container name * @param string $dir Resolved storage directory with no trailing slash * @param string|null &$after Resolved container relative path of file to list items after * @param int $limit Max number of items to list * @param array $params Parameters for {@link getFileList()} * @return array[] List of (name, stat map or null) tuples under $dir * @throws FileBackendError */ public function getFileListPageInternal( $fullCont, $dir, &$after, $limit, array $params ) { $files = []; // list of (path, stat map or null) entries if ( $after === INF ) { return $files; // nothing more } /** @noinspection PhpUnusedLocalVariableInspection */ $ps = $this->scopedProfileSection( __METHOD__ . "-{$this->name}" ); $prefix = ( $dir == '' ) ? null : "{$dir}/"; // $objects will contain a list of unfiltered names or stdClass items // Non-recursive: only list files right under $dir if ( !empty( $params['topOnly'] ) ) { if ( !empty( $params['adviseStat'] ) ) { $status = $this->objectListing( $fullCont, 'info', $limit, $after, $prefix, '/' ); } else { $status = $this->objectListing( $fullCont, 'names', $limit, $after, $prefix, '/' ); } } else { // Recursive: list all files under $dir and its subdirs if ( !empty( $params['adviseStat'] ) ) { $status = $this->objectListing( $fullCont, 'info', $limit, $after, $prefix ); } else { $status = $this->objectListing( $fullCont, 'names', $limit, $after, $prefix ); } } // Reformat this list into a list of (name, stat map or null) entries if ( !$status->isOK() ) { throw new FileBackendError( "Iterator page I/O error." ); } $objects = $status->value; $files = $this->buildFileObjectListing( $objects ); // Page on the unfiltered object listing (what is returned may be filtered) if ( count( $objects ) < $limit ) { $after = INF; // avoid a second RTT } else { $after = end( $objects ); // update last item $after = is_object( $after ) ? $after->name : $after; } return $files; } /** * Build a list of file objects, filtering out any directories * and extracting any stat info if provided in $objects * * @param stdClass[]|string[] $objects List of stdClass items or object names * @return array[] List of (name, stat map or null) entries */ private function buildFileObjectListing( array $objects ) { $names = []; foreach ( $objects as $object ) { if ( is_object( $object ) ) { if ( isset( $object->subdir ) || !isset( $object->name ) ) { continue; // virtual directory entry; ignore } $stat = [ // Convert various random Swift dates to TS_MW 'mtime' => $this->convertSwiftDate( $object->last_modified, TS_MW ), 'size' => (int)$object->bytes, 'sha1' => null, // Note: manifest ETags are not an MD5 of the file 'md5' => ctype_xdigit( $object->hash ) ? $object->hash : null, 'latest' => false // eventually consistent ]; $names[] = [ $object->name, $stat ]; } elseif ( substr( $object, -1 ) !== '/' ) { // Omit directories, which end in '/' in listings $names[] = [ $object, null ]; } } return $names; } /** * Do not call this function outside of SwiftFileBackendFileList * * @param string $path Storage path * @param array $val Stat value */ public function loadListingStatInternal( $path, array $val ) { $this->cheapCache->setField( $path, 'stat', $val ); } protected function doGetFileXAttributes( array $params ) { $stat = $this->getFileStat( $params ); // Stat entries filled by file listings don't include metadata/headers if ( is_array( $stat ) && !isset( $stat['xattr'] ) ) { $this->clearCache( [ $params['src'] ] ); $stat = $this->getFileStat( $params ); } if ( is_array( $stat ) ) { return $stat['xattr']; } return $stat === self::RES_ERROR ? self::RES_ERROR : self::RES_ABSENT; } protected function doGetFileSha1base36( array $params ) { // Avoid using stat entries from file listings, which never include the SHA-1 hash. // Also, recompute the hash if it's not part of the metadata headers for some reason. $params['requireSHA1'] = true; $stat = $this->getFileStat( $params ); if ( is_array( $stat ) ) { return $stat['sha1']; } return $stat === self::RES_ERROR ? self::RES_ERROR : self::RES_ABSENT; } protected function doStreamFile( array $params ) { $status = $this->newStatus(); $flags = !empty( $params['headless'] ) ? HTTPFileStreamer::STREAM_HEADLESS : 0; [ $srcCont, $srcRel ] = $this->resolveStoragePathReal( $params['src'] ); if ( $srcRel === null ) { HTTPFileStreamer::send404Message( $params['src'], $flags ); $status->fatal( 'backend-fail-invalidpath', $params['src'] ); return $status; } if ( !is_array( $this->getContainerStat( $srcCont ) ) ) { HTTPFileStreamer::send404Message( $params['src'], $flags ); $status->fatal( 'backend-fail-stream', $params['src'] ); return $status; } // If "headers" is set, we only want to send them if the file is there. // Do not bother checking if the file exists if headers are not set though. if ( $params['headers'] && !$this->fileExists( $params ) ) { HTTPFileStreamer::send404Message( $params['src'], $flags ); $status->fatal( 'backend-fail-stream', $params['src'] ); return $status; } // Send the requested additional headers if ( empty( $params['headless'] ) ) { foreach ( $params['headers'] as $header ) { $this->header( $header ); } } if ( empty( $params['allowOB'] ) ) { // Cancel output buffering and gzipping if set $this->resetOutputBuffer(); } $handle = fopen( 'php://output', 'wb' ); [ $rcode, $rdesc, , $rbody, $rerr ] = $this->requestWithAuth( [ 'method' => 'GET', 'container' => $srcCont, 'relPath' => $srcRel, 'headers' => $this->headersFromParams( $params ) + $params['options'], 'stream' => $handle, 'flags' => [ 'relayResponseHeaders' => empty( $params['headless'] ) ] ] ); if ( $rcode >= 200 && $rcode <= 299 ) { // good } elseif ( $rcode === 404 ) { $status->fatal( 'backend-fail-stream', $params['src'] ); // Per T43113, nasty things can happen if bad cache entries get // stuck in cache. It's also possible that this error can come up // with simple race conditions. Clear out the stat cache to be safe. $this->clearCache( [ $params['src'] ] ); $this->deleteFileCache( $params['src'] ); } else { $this->onError( $status, __METHOD__, $params, $rerr, $rcode, $rdesc, $rbody ); } return $status; } protected function doGetLocalCopyMulti( array $params ) { $ep = array_diff_key( $params, [ 'srcs' => 1 ] ); // for error logging // Blindly create tmp files and stream to them, catching any exception // if the file does not exist. Do not waste time doing file stats here. $reqs = []; // (path => op) // Initial dummy values to preserve path order $tmpFiles = array_fill_keys( $params['srcs'], self::RES_ERROR ); foreach ( $params['srcs'] as $path ) { // each path in this concurrent batch [ $srcCont, $srcRel ] = $this->resolveStoragePathReal( $path ); if ( $srcRel === null ) { continue; // invalid storage path } // Get source file extension $ext = FileBackend::extensionFromPath( $path ); // Create a new temporary file... $tmpFile = $this->tmpFileFactory->newTempFSFile( 'localcopy_', $ext ); $handle = $tmpFile ? fopen( $tmpFile->getPath(), 'wb' ) : false; if ( $handle ) { $reqs[$path] = [ 'method' => 'GET', 'container' => $srcCont, 'relPath' => $srcRel, 'headers' => $this->headersFromParams( $params ), 'stream' => $handle, ]; $tmpFiles[$path] = $tmpFile; } } // Ceph RADOS Gateway is in use (strong consistency) or X-Newest will be used $latest = ( $this->isRGW || !empty( $params['latest'] ) ); $reqs = $this->requestMultiWithAuth( $reqs, [ 'maxConnsPerHost' => $params['concurrency'] ] ); foreach ( $reqs as $path => $op ) { [ $rcode, $rdesc, $rhdrs, $rbody, $rerr ] = $op['response']; fclose( $op['stream'] ); // close open handle if ( $rcode >= 200 && $rcode <= 299 ) { /** @var TempFSFile $tmpFile */ $tmpFile = $tmpFiles[$path]; // Make sure that the stream finished and fully wrote to disk $size = $tmpFile->getSize(); if ( $size !== (int)$rhdrs['content-length'] ) { $tmpFiles[$path] = self::RES_ERROR; $rerr = "Got {$size}/{$rhdrs['content-length']} bytes"; $this->onError( null, __METHOD__, [ 'src' => $path ] + $ep, $rerr, $rcode, $rdesc ); } // Set the file stat process cache in passing $stat = $this->getStatFromHeaders( $rhdrs ); $stat['latest'] = $latest; $this->cheapCache->setField( $path, 'stat', $stat ); } elseif ( $rcode === 404 ) { $tmpFiles[$path] = self::RES_ABSENT; $this->cheapCache->setField( $path, 'stat', $latest ? self::ABSENT_LATEST : self::ABSENT_NORMAL ); } else { $tmpFiles[$path] = self::RES_ERROR; $this->onError( null, __METHOD__, [ 'src' => $path ] + $ep, $rerr, $rcode, $rdesc, $rbody ); } } return $tmpFiles; } public function addShellboxInputFile( BoxedCommand $command, string $boxedName, array $params ) { if ( $this->canShellboxGetTempUrl ) { $urlParams = [ 'src' => $params['src'] ]; if ( $this->shellboxIpRange !== null ) { $urlParams['ipRange'] = $this->shellboxIpRange; } $url = $this->getFileHttpUrl( $urlParams ); if ( $url ) { $command->inputFileFromUrl( $boxedName, $url ); return $this->newStatus(); } } return parent::addShellboxInputFile( $command, $boxedName, $params ); } public function getFileHttpUrl( array $params ) { if ( $this->swiftTempUrlKey == '' && ( $this->rgwS3AccessKey == '' || $this->rgwS3SecretKey != '' ) ) { $this->logger->debug( "Can't get Swift file URL: no key available" ); return self::TEMPURL_ERROR; } [ $srcCont, $srcRel ] = $this->resolveStoragePathReal( $params['src'] ); if ( $srcRel === null ) { $this->logger->debug( "Can't get Swift file URL: can't resolve path" ); return self::TEMPURL_ERROR; // invalid path } $auth = $this->getAuthentication(); if ( !$auth ) { $this->logger->debug( "Can't get Swift file URL: authentication failed" ); return self::TEMPURL_ERROR; } $method = $params['method'] ?? 'GET'; $ttl = $params['ttl'] ?? 86400; $expires = time() + $ttl; if ( $this->swiftTempUrlKey != '' ) { $url = $this->storageUrl( $auth, $srcCont, $srcRel ); // Swift wants the signature based on the unencoded object name $contPath = parse_url( $this->storageUrl( $auth, $srcCont ), PHP_URL_PATH ); $messageParts = [ $method, $expires, "{$contPath}/{$srcRel}" ]; $query = [ 'temp_url_expires' => $expires, ]; if ( isset( $params['ipRange'] ) ) { array_unshift( $messageParts, "ip={$params['ipRange']}" ); $query['temp_url_ip_range'] = $params['ipRange']; } $signature = hash_hmac( 'sha1', implode( "\n", $messageParts ), $this->swiftTempUrlKey ); $query = [ 'temp_url_sig' => $signature ] + $query; return $url . '?' . http_build_query( $query ); } else { // give S3 API URL for rgw // Path for signature starts with the bucket $spath = '/' . rawurlencode( $srcCont ) . '/' . str_replace( '%2F', '/', rawurlencode( $srcRel ) ); // Calculate the hash $signature = base64_encode( hash_hmac( 'sha1', "{$method}\n\n\n{$expires}\n{$spath}", $this->rgwS3SecretKey, true // raw ) ); // See https://s3.amazonaws.com/doc/s3-developer-guide/RESTAuthentication.html. // Note: adding a newline for empty CanonicalizedAmzHeaders does not work. // Note: S3 API is the rgw default; remove the /swift/ URL bit. return str_replace( '/swift/v1', '', $this->storageUrl( $auth ) . $spath ) . '?' . http_build_query( [ 'Signature' => $signature, 'Expires' => $expires, 'AWSAccessKeyId' => $this->rgwS3AccessKey ] ); } } protected function directoriesAreVirtual() { return true; } /** * Get headers to send to Swift when reading a file based * on a FileBackend params array, e.g. that of getLocalCopy(). * $params is currently only checked for a 'latest' flag. * * @param array $params * @return array */ protected function headersFromParams( array $params ) { $hdrs = []; if ( !empty( $params['latest'] ) ) { $hdrs['x-newest'] = 'true'; } return $hdrs; } protected function doExecuteOpHandlesInternal( array $fileOpHandles ) { /** @var SwiftFileOpHandle[] $fileOpHandles */ '@phan-var SwiftFileOpHandle[] $fileOpHandles'; /** @var StatusValue[] $statuses */ $statuses = []; // Split the HTTP requests into stages that can be done concurrently $httpReqsByStage = []; // map of (stage => index => HTTP request) foreach ( $fileOpHandles as $index => $fileOpHandle ) { $reqs = $fileOpHandle->httpOp; foreach ( $reqs as $stage => $req ) { $httpReqsByStage[$stage][$index] = $req; } $statuses[$index] = $this->newStatus(); } // Run all requests for the first stage, then the next, and so on $reqCount = count( $httpReqsByStage ); for ( $stage = 0; $stage < $reqCount; ++$stage ) { $httpReqs = $this->requestMultiWithAuth( $httpReqsByStage[$stage] ); foreach ( $httpReqs as $index => $httpReq ) { /** @var SwiftFileOpHandle $fileOpHandle */ $fileOpHandle = $fileOpHandles[$index]; // Run the callback for each request of this operation $status = $statuses[$index]; ( $fileOpHandle->callback )( $httpReq, $status ); // On failure, abort all remaining requests for this operation. This is used // in "move" operations to abort the DELETE request if the PUT request fails. if ( !$status->isOK() || $fileOpHandle->state === $fileOpHandle::CONTINUE_NO ) { $stages = count( $fileOpHandle->httpOp ); for ( $s = ( $stage + 1 ); $s < $stages; ++$s ) { unset( $httpReqsByStage[$s][$index] ); } } } } return $statuses; } /** * Set read/write permissions for a Swift container. * * @see http://docs.openstack.org/developer/swift/misc.html#acls * * In general, we don't allow listings to end-users. It's not useful, isn't well-defined * (lists are truncated to 10000 item with no way to page), and is just a performance risk. * * @param string $container Resolved Swift container * @param array $readUsers List of the possible criteria for a request to have * access to read a container. Each item is one of the following formats: * - account:user : Grants access if the request is by the given user * - ".r:<regex>" : Grants access if the request is from a referrer host that * matches the expression and the request is not for a listing. * Setting this to '*' effectively makes a container public. * -".rlistings:<regex>" : Grants access if the request is from a referrer host that * matches the expression and the request is for a listing. * @param array $writeUsers A list of the possible criteria for a request to have * access to write to a container. Each item is of the following format: * - account:user : Grants access if the request is by the given user * @return StatusValue Good status without value for success, fatal otherwise. */ protected function setContainerAccess( $container, array $readUsers, array $writeUsers ) { $status = $this->newStatus(); [ $rcode, , , , ] = $this->requestWithAuth( [ 'method' => 'POST', 'container' => $container, 'headers' => [ 'x-container-read' => implode( ',', $readUsers ), 'x-container-write' => implode( ',', $writeUsers ) ] ] ); if ( $rcode != 204 && $rcode !== 202 ) { $status->fatal( 'backend-fail-internal', $this->name ); $this->logger->error( __METHOD__ . ': unexpected rcode value ({rcode})', [ 'rcode' => $rcode ] ); } return $status; } /** * Get a Swift container stat map, possibly from process cache. * Use $reCache if the file count or byte count is needed. * * @param string $container Container name * @param bool $bypassCache Bypass all caches and load from Swift * @return array|false|null False on 404, null on failure */ protected function getContainerStat( $container, $bypassCache = false ) { /** @noinspection PhpUnusedLocalVariableInspection */ $ps = $this->scopedProfileSection( __METHOD__ . "-{$this->name}" ); if ( $bypassCache ) { // purge cache $this->containerStatCache->clear( $container ); } elseif ( !$this->containerStatCache->hasField( $container, 'stat' ) ) { $this->primeContainerCache( [ $container ] ); // check persistent cache } if ( !$this->containerStatCache->hasField( $container, 'stat' ) ) { [ $rcode, $rdesc, $rhdrs, $rbody, $rerr ] = $this->requestWithAuth( [ 'method' => 'HEAD', 'container' => $container ] ); if ( $rcode === 204 ) { $stat = [ 'count' => $rhdrs['x-container-object-count'], 'bytes' => $rhdrs['x-container-bytes-used'] ]; if ( $bypassCache ) { return $stat; } else { $this->containerStatCache->setField( $container, 'stat', $stat ); // cache it $this->setContainerCache( $container, $stat ); // update persistent cache } } elseif ( $rcode === 404 ) { return self::RES_ABSENT; } else { $this->onError( null, __METHOD__, [ 'cont' => $container ], $rerr, $rcode, $rdesc, $rbody ); return self::RES_ERROR; } } return $this->containerStatCache->getField( $container, 'stat' ); } /** * Create a Swift container * * @param string $container Container name * @param array $params * @return StatusValue Good status without value for success, fatal otherwise. */ protected function createContainer( $container, array $params ) { $status = $this->newStatus(); // @see SwiftFileBackend::setContainerAccess() if ( empty( $params['noAccess'] ) ) { // public $readUsers = array_merge( $this->readUsers, [ '.r:*', $this->swiftUser ] ); if ( empty( $params['noListing'] ) ) { array_push( $readUsers, '.rlistings' ); } $writeUsers = array_merge( $this->writeUsers, [ $this->swiftUser ] ); } else { // private $readUsers = array_merge( $this->secureReadUsers, [ $this->swiftUser ] ); $writeUsers = array_merge( $this->secureWriteUsers, [ $this->swiftUser ] ); } [ $rcode, $rdesc, , $rbody, $rerr ] = $this->requestWithAuth( [ 'method' => 'PUT', 'container' => $container, 'headers' => [ 'x-container-read' => implode( ',', $readUsers ), 'x-container-write' => implode( ',', $writeUsers ) ] ] ); if ( $rcode === 201 ) { // new // good } elseif ( $rcode === 202 ) { // already there // this shouldn't really happen, but is OK } else { $this->onError( $status, __METHOD__, $params, $rerr, $rcode, $rdesc, $rbody ); } return $status; } /** * Delete a Swift container * * @param string $container Container name * @param array $params * @return StatusValue */ protected function deleteContainer( $container, array $params ) { $status = $this->newStatus(); [ $rcode, $rdesc, , $rbody, $rerr ] = $this->requestWithAuth( [ 'method' => 'DELETE', 'container' => $container ] ); if ( $rcode >= 200 && $rcode <= 299 ) { // deleted $this->containerStatCache->clear( $container ); // purge } elseif ( $rcode === 404 ) { // not there // this shouldn't really happen, but is OK } elseif ( $rcode === 409 ) { // not empty $this->onError( $status, __METHOD__, $params, $rerr, $rcode, $rdesc ); // race? } else { $this->onError( $status, __METHOD__, $params, $rerr, $rcode, $rdesc, $rbody ); } return $status; } /** * Get a list of objects under a container. * Either just the names or a list of stdClass objects with details can be returned. * * @param string $fullCont * @param string $type ('info' for a list of object detail maps, 'names' for names only) * @param int $limit * @param string|null $after * @param string|null $prefix * @param string|null $delim * @return StatusValue With the list as value */ private function objectListing( $fullCont, $type, $limit, $after = null, $prefix = null, $delim = null ) { $status = $this->newStatus(); $query = [ 'limit' => $limit ]; if ( $type === 'info' ) { $query['format'] = 'json'; } if ( $after !== null ) { $query['marker'] = $after; } if ( $prefix !== null ) { $query['prefix'] = $prefix; } if ( $delim !== null ) { $query['delimiter'] = $delim; } [ $rcode, $rdesc, , $rbody, $rerr ] = $this->requestWithAuth( [ 'method' => 'GET', 'container' => $fullCont, 'query' => $query, ] ); $params = [ 'cont' => $fullCont, 'prefix' => $prefix, 'delim' => $delim ]; if ( $rcode === 200 ) { // good if ( $type === 'info' ) { $status->value = FormatJson::decode( trim( $rbody ) ); } else { $status->value = explode( "\n", trim( $rbody ) ); } } elseif ( $rcode === 204 ) { $status->value = []; // empty container } elseif ( $rcode === 404 ) { $status->value = []; // no container } else { $this->onError( $status, __METHOD__, $params, $rerr, $rcode, $rdesc, $rbody ); } return $status; } protected function doPrimeContainerCache( array $containerInfo ) { foreach ( $containerInfo as $container => $info ) { $this->containerStatCache->setField( $container, 'stat', $info ); } } protected function doGetFileStatMulti( array $params ) { $stats = []; $reqs = []; // (path => op) // (a) Check the containers of the paths... foreach ( $params['srcs'] as $path ) { [ $srcCont, $srcRel ] = $this->resolveStoragePathReal( $path ); if ( $srcRel === null ) { // invalid storage path $stats[$path] = self::RES_ERROR; continue; } $cstat = $this->getContainerStat( $srcCont ); if ( $cstat === self::RES_ABSENT ) { $stats[$path] = self::RES_ABSENT; continue; // ok, nothing to do } elseif ( $cstat === self::RES_ERROR ) { $stats[$path] = self::RES_ERROR; continue; } $reqs[$path] = [ 'method' => 'HEAD', 'container' => $srcCont, 'relPath' => $srcRel, 'headers' => $this->headersFromParams( $params ) ]; } // (b) Check the files themselves... $reqs = $this->requestMultiWithAuth( $reqs, [ 'maxConnsPerHost' => $params['concurrency'] ] ); foreach ( $reqs as $path => $op ) { [ $rcode, $rdesc, $rhdrs, $rbody, $rerr ] = $op['response']; if ( $rcode === 200 || $rcode === 204 ) { // Update the object if it is missing some headers if ( !empty( $params['requireSHA1'] ) ) { $rhdrs = $this->addMissingHashMetadata( $rhdrs, $path ); } // Load the stat map from the headers $stat = $this->getStatFromHeaders( $rhdrs ); if ( $this->isRGW ) { $stat['latest'] = true; // strong consistency } } elseif ( $rcode === 404 ) { $stat = self::RES_ABSENT; } else { $stat = self::RES_ERROR; $this->onError( null, __METHOD__, $params, $rerr, $rcode, $rdesc, $rbody ); } $stats[$path] = $stat; } return $stats; } /** * @param array $rhdrs * @return array */ protected function getStatFromHeaders( array $rhdrs ) { // Fetch all of the custom metadata headers $metadata = $this->getMetadataFromHeaders( $rhdrs ); // Fetch all of the custom raw HTTP headers $headers = $this->extractMutableContentHeaders( $rhdrs ); return [ // Convert various random Swift dates to TS_MW 'mtime' => $this->convertSwiftDate( $rhdrs['last-modified'], TS_MW ), // Empty objects actually return no content-length header in Ceph 'size' => isset( $rhdrs['content-length'] ) ? (int)$rhdrs['content-length'] : 0, 'sha1' => $metadata['sha1base36'] ?? null, // Note: manifest ETags are not an MD5 of the file 'md5' => ctype_xdigit( $rhdrs['etag'] ) ? $rhdrs['etag'] : null, 'xattr' => [ 'metadata' => $metadata, 'headers' => $headers ] ]; } /** * Get the cached auth token. * * @return array|null Credential map */ protected function getAuthentication() { if ( $this->authErrorTimestamp !== null ) { $interval = time() - $this->authErrorTimestamp; if ( $interval < 60 ) { $this->logger->debug( 'rejecting request since auth failure occurred {interval} seconds ago', [ 'interval' => $interval ] ); return null; } else { // actually retry this time $this->authErrorTimestamp = null; } } // Authenticate with proxy and get a session key... if ( !$this->authCreds ) { $cacheKey = $this->getCredsCacheKey( $this->swiftUser ); $creds = $this->srvCache->get( $cacheKey ); // credentials // Try to use the credential cache if ( isset( $creds['auth_token'] ) && isset( $creds['storage_url'] ) && isset( $creds['expiry_time'] ) && $creds['expiry_time'] > time() ) { $this->setAuthCreds( $creds ); } else { // cache miss $this->refreshAuthentication(); } } return $this->authCreds; } /** * Update the auth credentials * * @param array|null $creds */ private function setAuthCreds( ?array $creds ) { $this->logger->debug( 'Using auth token with expiry_time={expiry_time}', [ 'expiry_time' => isset( $creds['expiry_time'] ) ? gmdate( 'c', $creds['expiry_time'] ) : 'null' ] ); $this->authCreds = $creds; // Ceph RGW does not use <account> in URLs (OpenStack Swift uses "/v1/<account>") if ( $creds && str_ends_with( $creds['storage_url'], '/v1' ) ) { $this->isRGW = true; // take advantage of strong consistency in Ceph } } /** * Fetch the auth token from the server, without caching. * * @return array|null Credential map */ private function refreshAuthentication() { [ $rcode, , $rhdrs, $rbody, ] = $this->http->run( [ 'method' => 'GET', 'url' => "{$this->swiftAuthUrl}/v1.0", 'headers' => [ 'x-auth-user' => $this->swiftUser, 'x-auth-key' => $this->swiftKey ] ], self::DEFAULT_HTTP_OPTIONS ); if ( $rcode >= 200 && $rcode <= 299 ) { // OK if ( isset( $rhdrs['x-auth-token-expires'] ) ) { $ttl = intval( $rhdrs['x-auth-token-expires'] ); } else { $ttl = $this->authTTL; } $expiryTime = time() + $ttl; $creds = [ 'auth_token' => $rhdrs['x-auth-token'], 'storage_url' => $this->swiftStorageUrl ?? $rhdrs['x-storage-url'], 'expiry_time' => $expiryTime, ]; $this->srvCache->set( $this->getCredsCacheKey( $this->swiftUser ), $creds, $expiryTime ); } elseif ( $rcode === 401 ) { $this->onError( null, __METHOD__, [], "Authentication failed.", $rcode ); $this->authErrorTimestamp = time(); $creds = null; } else { $this->onError( null, __METHOD__, [], "HTTP return code: $rcode", $rcode, $rbody ); $this->authErrorTimestamp = time(); $creds = null; } $this->setAuthCreds( $creds ); return $creds; } /** * @param array $creds From getAuthentication() * @param string|null $container * @param string|null $object * @return string */ protected function storageUrl( array $creds, $container = null, $object = null ) { $parts = [ $creds['storage_url'] ]; if ( strlen( $container ?? '' ) ) { $parts[] = rawurlencode( $container ); } if ( strlen( $object ?? '' ) ) { $parts[] = str_replace( "%2F", "/", rawurlencode( $object ) ); } return implode( '/', $parts ); } /** * @param array $creds From getAuthentication() * @return array */ protected function authTokenHeaders( array $creds ) { return [ 'x-auth-token' => $creds['auth_token'] ]; } /** * Get the cache key for a container * * @param string $username * @return string */ private function getCredsCacheKey( $username ) { return 'swiftcredentials:' . md5( $username . ':' . $this->swiftAuthUrl ); } /** * Perform an authenticated HTTP request * * @param array $req The request data, including: * - container: The name of the container (required) * - relPath: The relative path under the container. If this is omitted, * the request will refer to the container itself. * - headers: An array of request headers to send, in addition to the * auth headers. * - Other keys to be passed through to MultiHttpClient::run() * @param array $options Options to pass through to MultiHttpClient, in * addition to the default options DEFAULT_HTTP_OPTIONS * @return array The response array from MultiHttpClient::run() */ private function requestWithAuth( array $req, array $options = [] ) { return $this->requestMultiWithAuth( [ $req ], $options )[0]['response']; } /** * Perform a batch of authenticated HTTP requests * * @param array $reqs An array of request data arrays. See self::requestWithAuth() * @param array $options Options to pass through to MultiHttpClient, in * addition to the default options DEFAULT_HTTP_OPTIONS * @return array The request array with responses populated, as returned by * MultiHttpClient::runMulti() */ private function requestMultiWithAuth( array $reqs, $options = [] ) { $remainingTries = 2; $auth = $this->getAuthentication(); while ( true ) { if ( !$auth ) { foreach ( $reqs as &$req ) { if ( !isset( $req['response'] ) ) { $req['response'] = $this->getAuthFailureResponse(); } } break; } foreach ( $reqs as &$req ) { '@phan-var array $req'; // Not array[] if ( isset( $req['response'] ) ) { // Request was attempted before // Retry only if it gave a 401 response code if ( $req['response']['code'] !== 401 ) { continue; } } $req['headers'] = $this->authTokenHeaders( $auth ) + ( $req['headers'] ?? [] ); $req['url'] = $this->storageUrl( $auth, $req['container'], $req['relPath'] ?? null ); } unset( $req ); $reqs = $this->http->runMulti( $reqs, $options + self::DEFAULT_HTTP_OPTIONS ); if ( --$remainingTries > 0 ) { // Retry if any request failed with 401 "not authorized" foreach ( $reqs as $req ) { if ( $req['response']['code'] === 401 ) { $auth = $this->refreshAuthentication(); continue 2; } } } break; } return $reqs; } /** * Get a synthetic response to return from requestWithAuth() or requestMultiWithAuth() * if the request could not be issued due to failure of a prior authentication request. * This failure should not be logged as an HTTP error since the original failure would * have been logged. * * @return array */ private function getAuthFailureResponse() { return [ 'code' => 0, 0 => 0, 'reason' => '', 1 => '', 'headers' => [], 2 => [], 'body' => '', 3 => '', 'error' => self::AUTH_FAILURE_ERROR, 4 => self::AUTH_FAILURE_ERROR ]; } /** * Determine whether an HTTP response was generated by getAuthFailureResponse() * * @param int $code * @param string $error * @return bool */ private function isAuthFailureResponse( $code, $error ) { return $code === 0 && $error === self::AUTH_FAILURE_ERROR; } /** * Log an unexpected exception for this backend. * This also sets the StatusValue object to have a fatal error. * * @param StatusValue|null $status To add fatal errors to * @param string $func * @param array $params * @param string $err Error string * @param int $code HTTP status * @param string $desc HTTP StatusValue description * @param string $body HTTP body */ public function onError( $status, $func, array $params, $err = '', $code = 0, $desc = '', $body = '' ) { if ( $this->isAuthFailureResponse( $code, $err ) ) { if ( $status instanceof StatusValue ) { $status->fatal( 'backend-fail-connect', $this->name ); } // Already logged return; } if ( $status instanceof StatusValue ) { $status->fatal( 'backend-fail-internal', $this->name ); } $msg = "HTTP {code} ({desc}) in '{func}' (given '{req_params}')"; $msgParams = [ 'code' => $code, 'desc' => $desc, 'func' => $func, 'req_params' => FormatJson::encode( $params ), ]; if ( $err ) { $msg .= ': {err}'; $msgParams['err'] = $err; } if ( $code == 502 ) { $msg .= ' ({truncatedBody})'; $msgParams['truncatedBody'] = substr( strip_tags( $body ), 0, 100 ); } $this->logger->error( $msg, $msgParams ); } } /** @deprecated class alias since 1.43 */ class_alias( SwiftFileBackend::class, 'SwiftFileBackend' ); PK ! ���^ ^ ! filebackend/MemoryFileBackend.phpnu �Iw�� <?php /** * Simulation of a backend storage in memory. * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file * @ingroup FileBackend */ namespace Wikimedia\FileBackend; use Wikimedia\AtEase\AtEase; use Wikimedia\Timestamp\ConvertibleTimestamp; /** * Simulation of a backend storage in memory. * * All data in the backend is automatically deleted at the end of PHP execution. * Since the data stored here is volatile, this is only useful for staging or testing. * * @ingroup FileBackend * @since 1.23 */ class MemoryFileBackend extends FileBackendStore { /** @var array Map of (file path => (data,mtime) */ protected $files = []; public function getFeatures() { return self::ATTR_UNICODE_PATHS; } public function isPathUsableInternal( $storagePath ) { return ( $this->resolveHashKey( $storagePath ) !== null ); } protected function doCreateInternal( array $params ) { $status = $this->newStatus(); $dst = $this->resolveHashKey( $params['dst'] ); if ( $dst === null ) { $status->fatal( 'backend-fail-invalidpath', $params['dst'] ); return $status; } $this->files[$dst] = [ 'data' => $params['content'], 'mtime' => ConvertibleTimestamp::convert( TS_MW, time() ) ]; return $status; } protected function doStoreInternal( array $params ) { $status = $this->newStatus(); $dst = $this->resolveHashKey( $params['dst'] ); if ( $dst === null ) { $status->fatal( 'backend-fail-invalidpath', $params['dst'] ); return $status; } AtEase::suppressWarnings(); $data = file_get_contents( $params['src'] ); AtEase::restoreWarnings(); if ( $data === false ) { // source doesn't exist? $status->fatal( 'backend-fail-store', $params['src'], $params['dst'] ); return $status; } $this->files[$dst] = [ 'data' => $data, 'mtime' => ConvertibleTimestamp::convert( TS_MW, time() ) ]; return $status; } protected function doCopyInternal( array $params ) { $status = $this->newStatus(); $src = $this->resolveHashKey( $params['src'] ); if ( $src === null ) { $status->fatal( 'backend-fail-invalidpath', $params['src'] ); return $status; } $dst = $this->resolveHashKey( $params['dst'] ); if ( $dst === null ) { $status->fatal( 'backend-fail-invalidpath', $params['dst'] ); return $status; } if ( !isset( $this->files[$src] ) ) { if ( empty( $params['ignoreMissingSource'] ) ) { $status->fatal( 'backend-fail-copy', $params['src'], $params['dst'] ); } return $status; } $this->files[$dst] = [ 'data' => $this->files[$src]['data'], 'mtime' => ConvertibleTimestamp::convert( TS_MW, time() ) ]; return $status; } protected function doMoveInternal( array $params ) { $status = $this->newStatus(); $src = $this->resolveHashKey( $params['src'] ); if ( $src === null ) { $status->fatal( 'backend-fail-invalidpath', $params['src'] ); return $status; } $dst = $this->resolveHashKey( $params['dst'] ); if ( $dst === null ) { $status->fatal( 'backend-fail-invalidpath', $params['dst'] ); return $status; } if ( !isset( $this->files[$src] ) ) { if ( empty( $params['ignoreMissingSource'] ) ) { $status->fatal( 'backend-fail-move', $params['src'], $params['dst'] ); } return $status; } $this->files[$dst] = $this->files[$src]; unset( $this->files[$src] ); $this->files[$dst]['mtime'] = ConvertibleTimestamp::convert( TS_MW, time() ); return $status; } protected function doDeleteInternal( array $params ) { $status = $this->newStatus(); $src = $this->resolveHashKey( $params['src'] ); if ( $src === null ) { $status->fatal( 'backend-fail-invalidpath', $params['src'] ); return $status; } if ( !isset( $this->files[$src] ) ) { if ( empty( $params['ignoreMissingSource'] ) ) { $status->fatal( 'backend-fail-delete', $params['src'] ); } return $status; } unset( $this->files[$src] ); return $status; } protected function doGetFileStat( array $params ) { $src = $this->resolveHashKey( $params['src'] ); if ( $src === null ) { return self::RES_ERROR; // invalid path } if ( isset( $this->files[$src] ) ) { return [ 'mtime' => $this->files[$src]['mtime'], 'size' => strlen( $this->files[$src]['data'] ), ]; } return self::RES_ABSENT; } protected function doGetLocalCopyMulti( array $params ) { $tmpFiles = []; // (path => TempFSFile) foreach ( $params['srcs'] as $srcPath ) { $src = $this->resolveHashKey( $srcPath ); if ( $src === null ) { $fsFile = self::RES_ERROR; } elseif ( !isset( $this->files[$src] ) ) { $fsFile = self::RES_ABSENT; } else { // Create a new temporary file with the same extension... $ext = FileBackend::extensionFromPath( $src ); $fsFile = $this->tmpFileFactory->newTempFSFile( 'localcopy_', $ext ); if ( $fsFile ) { $bytes = file_put_contents( $fsFile->getPath(), $this->files[$src]['data'] ); if ( $bytes !== strlen( $this->files[$src]['data'] ) ) { $fsFile = self::RES_ERROR; } } } $tmpFiles[$srcPath] = $fsFile; } return $tmpFiles; } protected function doDirectoryExists( $container, $dir, array $params ) { $prefix = rtrim( "$container/$dir", '/' ) . '/'; foreach ( $this->files as $path => $data ) { if ( strpos( $path, $prefix ) === 0 ) { return true; } } return false; } public function getDirectoryListInternal( $container, $dir, array $params ) { $dirs = []; $prefix = rtrim( "$container/$dir", '/' ) . '/'; $prefixLen = strlen( $prefix ); foreach ( $this->files as $path => $data ) { if ( strpos( $path, $prefix ) === 0 ) { $relPath = substr( $path, $prefixLen ); if ( $relPath === false ) { continue; } elseif ( strpos( $relPath, '/' ) === false ) { continue; // just a file } $parts = array_slice( explode( '/', $relPath ), 0, -1 ); // last part is file name if ( !empty( $params['topOnly'] ) ) { $dirs[$parts[0]] = 1; // top directory } else { $current = ''; foreach ( $parts as $part ) { // all directories $dir = ( $current === '' ) ? $part : "$current/$part"; $dirs[$dir] = 1; $current = $dir; } } } } return array_keys( $dirs ); } public function getFileListInternal( $container, $dir, array $params ) { $files = []; $prefix = rtrim( "$container/$dir", '/' ) . '/'; $prefixLen = strlen( $prefix ); foreach ( $this->files as $path => $data ) { if ( strpos( $path, $prefix ) === 0 ) { $relPath = substr( $path, $prefixLen ); if ( $relPath === false ) { continue; } elseif ( !empty( $params['topOnly'] ) && strpos( $relPath, '/' ) !== false ) { continue; } $files[] = $relPath; } } return $files; } protected function directoriesAreVirtual() { return true; } /** * Get the absolute file system path for a storage path * * @param string $storagePath * @return string|null */ protected function resolveHashKey( $storagePath ) { [ $fullCont, $relPath ] = $this->resolveStoragePathReal( $storagePath ); if ( $relPath === null ) { return null; // invalid } return ( $relPath !== '' ) ? "$fullCont/$relPath" : $fullCont; } } /** @deprecated class alias since 1.43 */ class_alias( MemoryFileBackend::class, 'MemoryFileBackend' ); PK ! ��ܡ� � . filebackend/fileophandle/SwiftFileOpHandle.phpnu �Iw�� <?php /** * OpenStack Swift based file backend. * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file * @ingroup FileBackend * @author Russ Nelson */ namespace Wikimedia\FileBackend\FileOpHandle; use Closure; use Wikimedia\FileBackend\SwiftFileBackend; class SwiftFileOpHandle extends FileBackendStoreOpHandle { /** @var array[] List of HTTP request maps for SwiftFileBackend::requestWithAuth */ public $httpOp; /** @var Closure Function to run after each HTTP request finishes */ public $callback; /** @var int Class CONTINUE_* constant */ public $state = self::CONTINUE_IF_OK; /** @var int Continue with the next requests stages if no errors occurred */ public const CONTINUE_IF_OK = 0; /** @var int Cancel the next requests stages */ public const CONTINUE_NO = 1; /** * Construct a handle to be use with SwiftFileOpHandle::doExecuteOpHandlesInternal() * * The callback returns a class CONTINUE_* constant and takes the following parameters: * - An HTTP request map array with 'response' filled * - A StatusValue instance to be updated as needed * * @param SwiftFileBackend $backend * @param Closure $callback * @param array $httpOp Request to send via SwiftFileBackend::requestWithAuth() */ public function __construct( SwiftFileBackend $backend, Closure $callback, array $httpOp ) { $this->backend = $backend; $this->callback = $callback; $this->httpOp = $httpOp; } } /** @deprecated class alias since 1.43 */ class_alias( SwiftFileOpHandle::class, 'SwiftFileOpHandle' ); PK ! :�*� � + filebackend/fileophandle/FSFileOpHandle.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file * @ingroup FileBackend */ namespace Wikimedia\FileBackend\FileOpHandle; use Wikimedia\FileBackend\FSFileBackend; class FSFileOpHandle extends FileBackendStoreOpHandle { /** @var string Shell command */ public $cmd; /** @var callback Post-operation success/error handling and cleanup function */ public $callback; /** * @param FSFileBackend $backend * @param array $params * @param callable $call * @param string $cmd */ public function __construct( FSFileBackend $backend, array $params, callable $call, $cmd ) { $this->backend = $backend; $this->params = $params; $this->callback = $call; $this->cmd = $cmd; } } /** @deprecated class alias since 1.43 */ class_alias( FSFileOpHandle::class, 'FSFileOpHandle' ); PK ! ��j�z z 5 filebackend/fileophandle/FileBackendStoreOpHandle.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file * @ingroup FileBackend */ namespace Wikimedia\FileBackend\FileOpHandle; use Wikimedia\FileBackend\FileBackendStore; /** * FileBackendStore helper class for performing asynchronous file operations. * * For example, calling FileBackendStore::createInternal() with the "async" * param flag may result in a StatusValue that contains this object as a value. * This class is largely backend-specific and is mostly just "magic" to be * passed to FileBackendStore::executeOpHandlesInternal(). * * @stable to extend */ abstract class FileBackendStoreOpHandle { /** @var array */ public $params = []; // params to caller functions /** @var FileBackendStore */ public $backend; /** @var array */ public $resourcesToClose = []; /** @var callable name that identifies the function called */ public $call; /** * Close all open file handles */ public function closeResources() { // @phan-suppress-next-line PhanPluginUseReturnValueInternalKnown array_map( 'fclose', $this->resourcesToClose ); } } /** @deprecated class alias since 1.43 */ class_alias( FileBackendStoreOpHandle::class, 'FileBackendStoreOpHandle' ); PK ! �Z��� � filebackend/FileBackend.phpnu �Iw�� <?php /** * @defgroup FileBackend File backend * * File backend is used to interact with file storage systems, * such as the local file system, NFS, or cloud storage systems. * See [the architecture doc](@ref filebackendarch) for more information. */ /** * Base class for all file backends. * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file * @ingroup FileBackend */ namespace Wikimedia\FileBackend; use InvalidArgumentException; use LockManager; use MediaWiki\FileBackend\FSFile\TempFSFileFactory; use NullLockManager; use Psr\Log\LoggerAwareInterface; use Psr\Log\LoggerInterface; use Psr\Log\NullLogger; use ScopedLock; use Shellbox\Command\BoxedCommand; use StatusValue; use Wikimedia\FileBackend\FSFile\FSFile; use Wikimedia\FileBackend\FSFile\TempFSFile; use Wikimedia\ScopedCallback; /** * @brief Base class for all file backend classes (including multi-write backends). * * This class defines the methods as abstract that subclasses must implement. * Outside callers can assume that all backends will have these functions. * * All "storage paths" are of the format "mwstore://<backend>/<container>/<path>". * The "backend" portion is unique name for the application to refer to a backend, while * the "container" portion is a top-level directory of the backend. The "path" portion * is a relative path that uses UNIX file system (FS) notation, though any particular * backend may not actually be using a local filesystem. Therefore, the relative paths * are only virtual. * * Backend contents are stored under "domain"-specific container names by default. * A domain is simply a logical umbrella for entities, such as those belonging to a certain * application or portion of a website, for example. A domain can be local or global. * Global (qualified) backends are achieved by configuring the "domain ID" to a constant. * Global domains are simpler, but local domains can be used by choosing a domain ID based on * the current context, such as which language of a website is being used. * * For legacy reasons, the FSFileBackend class allows manually setting the paths of * containers to ones that do not respect the "domain ID". * * In key/value (object) stores, containers are the only hierarchy (the rest is emulated). * FS-based backends are somewhat more restrictive due to the existence of real * directory files; a regular file cannot have the same name as a directory. Other * backends with virtual directories may not have this limitation. Callers should * store files in such a way that no files and directories are under the same path. * * In general, this class allows for callers to access storage through the same * interface, without regard to the underlying storage system. However, calling code * must follow certain patterns and be aware of certain things to ensure compatibility: * - a) Always call prepare() on the parent directory before trying to put a file there; * key/value stores only need the container to exist first, but filesystems need * all the parent directories to exist first (prepare() is aware of all this) * - b) Always call clean() on a directory when it might become empty to avoid empty * directory buildup on filesystems; key/value stores never have empty directories, * so doing this helps preserve consistency in both cases * - c) Likewise, do not rely on the existence of empty directories for anything; * calling directoryExists() on a path that prepare() was previously called on * will return false for key/value stores if there are no files under that path * - d) Never alter the resulting FSFile returned from getLocalReference(), as it could * either be a copy of the source file in /tmp or the original source file itself * - e) Use a file layout that results in never attempting to store files over directories * or directories over files; key/value stores allow this but filesystems do not * - f) Use ASCII file names (e.g. base32, IDs, hashes) to avoid Unicode issues in Windows * - g) Do not assume that move operations are atomic (difficult with key/value stores) * - h) Do not assume that file stat or read operations always have immediate consistency; * various methods have a "latest" flag that should always be used if up-to-date * information is required (this trades performance for correctness as needed) * - i) Do not assume that directory listings have immediate consistency * * Methods of subclasses should avoid throwing exceptions at all costs. * As a corollary, external dependencies should be kept to a minimum. * * See [the architecture doc](@ref filebackendarch) for more information. * * @stable to extend * * @ingroup FileBackend * @since 1.19 */ abstract class FileBackend implements LoggerAwareInterface { /** @var string Unique backend name */ protected $name; /** @var string Unique domain name */ protected $domainId; /** @var string Read-only explanation message */ protected $readOnly; /** @var string When to do operations in parallel */ protected $parallelize; /** @var int How many operations can be done in parallel */ protected $concurrency; /** @var TempFSFileFactory */ protected $tmpFileFactory; /** @var LockManager */ protected $lockManager; /** @var LoggerInterface */ protected $logger; /** @var callable|null */ protected $profiler; /** @var callable */ private $obResetFunc; /** @var callable */ private $headerFunc; /** @var array Option map for use with HTTPFileStreamer */ protected $streamerOptions; /** @var callable|null */ protected $statusWrapper; /** Bitfield flags for supported features */ public const ATTR_HEADERS = 1; // files can be tagged with standard HTTP headers public const ATTR_METADATA = 2; // files can be stored with metadata key/values public const ATTR_UNICODE_PATHS = 4; // files can have Unicode paths (not just ASCII) /** @var false Idiom for "no info; non-existant file" (since 1.34) */ protected const STAT_ABSENT = false; /** @var null Idiom for "no info; I/O errors" (since 1.34) */ public const STAT_ERROR = null; /** @var null Idiom for "no file/directory list; I/O errors" (since 1.34) */ public const LIST_ERROR = null; /** @var null Idiom for "no temp URL; not supported or I/O errors" (since 1.34) */ public const TEMPURL_ERROR = null; /** @var null Idiom for "existence unknown; I/O errors" (since 1.34) */ public const EXISTENCE_ERROR = null; /** @var false Idiom for "no timestamp; missing file or I/O errors" (since 1.34) */ public const TIMESTAMP_FAIL = false; /** @var false Idiom for "no content; missing file or I/O errors" (since 1.34) */ public const CONTENT_FAIL = false; /** @var false Idiom for "no metadata; missing file or I/O errors" (since 1.34) */ public const XATTRS_FAIL = false; /** @var false Idiom for "no size; missing file or I/O errors" (since 1.34) */ public const SIZE_FAIL = false; /** @var false Idiom for "no SHA1 hash; missing file or I/O errors" (since 1.34) */ public const SHA1_FAIL = false; /** * Create a new backend instance from configuration. * This should only be called from within FileBackendGroup. * @stable to call * * @param array $config Parameters include: * - name : The unique name of this backend. * This should consist of alphanumberic, '-', and '_' characters. * This name should not be changed after use. * Note that the name is *not* used in actual container names. * - domainId : Prefix to container names that is unique to this backend. * It should only consist of alphanumberic, '-', and '_' characters. * This ID is what avoids collisions if multiple logical backends * use the same storage system, so this should be set carefully. * - lockManager : LockManager object to use for any file locking. * If not provided, then no file locking will be enforced. * - readOnly : Write operations are disallowed if this is a non-empty string. * It should be an explanation for the backend being read-only. * - parallelize : When to do file operations in parallel (when possible). * Allowed values are "implicit", "explicit" and "off". * - concurrency : How many file operations can be done in parallel. * - tmpDirectory : Directory to use for temporary files. * - tmpFileFactory : Optional TempFSFileFactory object. Only has an effect if * tmpDirectory is not set. If both are unset or null, then the backend will * try to discover a usable temporary directory. * - obResetFunc : alternative callback to clear the output buffer * - streamMimeFunc : alternative method to determine the content type from the path * - headerFunc : alternative callback for sending response headers * - logger : Optional PSR logger object. * - profiler : Optional callback that takes a section name argument and returns * a ScopedCallback instance that ends the profile section in its destructor. * - statusWrapper : Optional callback that is used to wrap returned StatusValues */ public function __construct( array $config ) { if ( !array_key_exists( 'name', $config ) ) { throw new InvalidArgumentException( 'Backend name not specified.' ); } $this->name = $config['name']; $this->domainId = $config['domainId'] // e.g. "my_wiki-en_" ?? $config['wikiId'] // b/c alias ?? null; if ( !is_string( $this->name ) || !preg_match( '!^[a-zA-Z0-9-_]{1,255}$!', $this->name ) ) { throw new InvalidArgumentException( "Backend name '{$this->name}' is invalid." ); } if ( !is_string( $this->domainId ) ) { throw new InvalidArgumentException( "Backend domain ID not provided for '{$this->name}'." ); } $this->lockManager = $config['lockManager'] ?? new NullLockManager( [] ); $this->readOnly = isset( $config['readOnly'] ) ? (string)$config['readOnly'] : ''; $this->parallelize = isset( $config['parallelize'] ) ? (string)$config['parallelize'] : 'off'; $this->concurrency = isset( $config['concurrency'] ) ? (int)$config['concurrency'] : 50; $this->obResetFunc = $config['obResetFunc'] ?? [ self::class, 'resetOutputBufferTheDefaultWay' ]; $this->headerFunc = $config['headerFunc'] ?? 'header'; $this->streamerOptions = [ 'obResetFunc' => $this->obResetFunc, 'headerFunc' => $this->headerFunc, 'streamMimeFunc' => $config['streamMimeFunc'] ?? null, ]; $this->profiler = $config['profiler'] ?? null; if ( !is_callable( $this->profiler ) ) { $this->profiler = null; } $this->logger = $config['logger'] ?? new NullLogger(); $this->statusWrapper = $config['statusWrapper'] ?? null; // tmpDirectory gets precedence for backward compatibility if ( isset( $config['tmpDirectory'] ) ) { $this->tmpFileFactory = new TempFSFileFactory( $config['tmpDirectory'] ); } else { $this->tmpFileFactory = $config['tmpFileFactory'] ?? new TempFSFileFactory(); } } protected function header( $header ) { ( $this->headerFunc )( $header ); } protected function resetOutputBuffer() { // By default, this ends up calling $this->defaultOutputBufferReset ( $this->obResetFunc )(); } public function setLogger( LoggerInterface $logger ) { $this->logger = $logger; } /** * Get the unique backend name * * We may have multiple different backends of the same type. * For example, we can have two Swift backends using different proxies. * * @return string */ final public function getName() { return $this->name; } /** * Get the domain identifier used for this backend (possibly empty). * * @return string * @since 1.28 */ final public function getDomainId() { return $this->domainId; } /** * Alias to getDomainId() * * @return string * @since 1.20 * @deprecated Since 1.34 Use getDomainId() */ final public function getWikiId() { return $this->getDomainId(); } /** * Check if this backend is read-only * * @return bool */ final public function isReadOnly() { return ( $this->readOnly != '' ); } /** * Get an explanatory message if this backend is read-only * * @return string|bool Returns false if the backend is not read-only */ final public function getReadOnlyReason() { return ( $this->readOnly != '' ) ? $this->readOnly : false; } /** * Get the a bitfield of extra features supported by the backend medium * @stable to override * * @return int Bitfield of FileBackend::ATTR_* flags * @since 1.23 */ public function getFeatures() { return self::ATTR_UNICODE_PATHS; } /** * Check if the backend medium supports a field of extra features * * @param int $bitfield Bitfield of FileBackend::ATTR_* flags * @return bool * @since 1.23 */ final public function hasFeatures( $bitfield ) { return ( $this->getFeatures() & $bitfield ) === $bitfield; } /** * This is the main entry point into the backend for write operations. * Callers supply an ordered list of operations to perform as a transaction. * Files will be locked, the stat cache cleared, and then the operations attempted. * If any serious errors occur, all attempted operations will be rolled back. * * $ops is an array of arrays. The outer array holds a list of operations. * Each inner array is a set of key value pairs that specify an operation. * * Supported operations and their parameters. The supported actions are: * - create * - store * - copy * - move * - delete * - describe (since 1.21) * - null * * FSFile/TempFSFile object support was added in 1.27. * * a) Create a new file in storage with the contents of a string * @code * [ * 'op' => 'create', * 'dst' => <storage path>, * 'content' => <string of new file contents>, * 'overwrite' => <boolean>, * 'overwriteSame' => <boolean>, * 'headers' => <HTTP header name/value map> # since 1.21 * ] * @endcode * * b) Copy a file system file into storage * @code * [ * 'op' => 'store', * 'src' => <file system path, FSFile, or TempFSFile>, * 'dst' => <storage path>, * 'overwrite' => <boolean>, * 'overwriteSame' => <boolean>, * 'headers' => <HTTP header name/value map> # since 1.21 * ] * @endcode * * c) Copy a file within storage * @code * [ * 'op' => 'copy', * 'src' => <storage path>, * 'dst' => <storage path>, * 'overwrite' => <boolean>, * 'overwriteSame' => <boolean>, * 'ignoreMissingSource' => <boolean>, # since 1.21 * 'headers' => <HTTP header name/value map> # since 1.21 * ] * @endcode * * d) Move a file within storage * @code * [ * 'op' => 'move', * 'src' => <storage path>, * 'dst' => <storage path>, * 'overwrite' => <boolean>, * 'overwriteSame' => <boolean>, * 'ignoreMissingSource' => <boolean>, # since 1.21 * 'headers' => <HTTP header name/value map> # since 1.21 * ] * @endcode * * e) Delete a file within storage * @code * [ * 'op' => 'delete', * 'src' => <storage path>, * 'ignoreMissingSource' => <boolean> * ] * @endcode * * f) Update metadata for a file within storage * @code * [ * 'op' => 'describe', * 'src' => <storage path>, * 'headers' => <HTTP header name/value map> * ] * @endcode * * g) Do nothing (no-op) * @code * [ * 'op' => 'null', * ] * @endcode * * Boolean flags for operations (operation-specific): * - ignoreMissingSource : The operation will simply succeed and do * nothing if the source file does not exist. * - overwrite : Any destination file will be overwritten. * - overwriteSame : If a file already exists at the destination with the * same contents, then do nothing to the destination file * instead of giving an error. This does not compare headers. * This option is ignored if 'overwrite' is already provided. * - headers : If supplied, the result of merging these headers with any * existing source file headers (replacing conflicting ones) * will be set as the destination file headers. Headers are * deleted if their value is set to the empty string. When a * file has headers they are included in responses to GET and * HEAD requests to the backing store for that file. * Header values should be no larger than 255 bytes, except for * Content-Disposition. The system might ignore or truncate any * headers that are too long to store (exact limits will vary). * Backends that don't support metadata ignore this. (since 1.21) * * $opts is an associative of boolean flags, including: * - force : Operation precondition errors no longer trigger an abort. * Any remaining operations are still attempted. Unexpected * failures may still cause remaining operations to be aborted. * - nonLocking : No locks are acquired for the operations. * This can increase performance for non-critical writes. * This has no effect unless the 'force' flag is set. * - parallelize : Try to do operations in parallel when possible. * - bypassReadOnly : Allow writes in read-only mode. (since 1.20) * - preserveCache : Don't clear the process cache before checking files. * This should only be used if all entries in the process * cache were added after the files were already locked. (since 1.20) * * @note Remarks on locking: * File system paths given to operations should refer to files that are * already locked or otherwise safe from modification from other processes. * Normally these files will be new temp files, which should be adequate. * * @par Return value: * * This returns a Status, which contains all warnings and fatals that occurred * during the operation. The 'failCount', 'successCount', and 'success' members * will reflect each operation attempted. * * The StatusValue will be "OK" unless: * - a) unexpected operation errors occurred (network partitions, disk full...) * - b) predicted operation errors occurred and 'force' was not set * * @param array[] $ops List of operations to execute in order * @phan-param array<int,array{ignoreMissingSource?:bool,overwrite?:bool,overwriteSame?:bool,headers?:bool}> $ops * @param array $opts Batch operation options * @phpcs:ignore Generic.Files.LineLength * @phan-param array{force?:bool,nonLocking?:bool,parallelize?:bool,bypassReadOnly?:bool,preserveCache?:bool} $opts * @return StatusValue */ final public function doOperations( array $ops, array $opts = [] ) { if ( empty( $opts['bypassReadOnly'] ) && $this->isReadOnly() ) { return $this->newStatus( 'backend-fail-readonly', $this->name, $this->readOnly ); } if ( $ops === [] ) { return $this->newStatus(); // nothing to do } $ops = $this->resolveFSFileObjects( $ops ); if ( empty( $opts['force'] ) ) { unset( $opts['nonLocking'] ); } /** @noinspection PhpUnusedLocalVariableInspection */ $scope = ScopedCallback::newScopedIgnoreUserAbort(); // try to ignore client aborts return $this->doOperationsInternal( $ops, $opts ); } /** * @see FileBackend::doOperations() * @param array $ops * @param array $opts * @return StatusValue */ abstract protected function doOperationsInternal( array $ops, array $opts ); /** * Same as doOperations() except it takes a single operation. * If you are doing a batch of operations that should either * all succeed or all fail, then use that function instead. * * @see FileBackend::doOperations() * * @param array $op Operation * @param array $opts Operation options * @return StatusValue */ final public function doOperation( array $op, array $opts = [] ) { return $this->doOperations( [ $op ], $opts ); } /** * Performs a single create operation. * This sets $params['op'] to 'create' and passes it to doOperation(). * * @see FileBackend::doOperation() * * @param array $params Operation parameters * @param array $opts Operation options * @return StatusValue */ final public function create( array $params, array $opts = [] ) { return $this->doOperation( [ 'op' => 'create' ] + $params, $opts ); } /** * Performs a single store operation. * This sets $params['op'] to 'store' and passes it to doOperation(). * * @see FileBackend::doOperation() * * @param array $params Operation parameters * @param array $opts Operation options * @return StatusValue */ final public function store( array $params, array $opts = [] ) { return $this->doOperation( [ 'op' => 'store' ] + $params, $opts ); } /** * Performs a single copy operation. * This sets $params['op'] to 'copy' and passes it to doOperation(). * * @see FileBackend::doOperation() * * @param array $params Operation parameters * @param array $opts Operation options * @return StatusValue */ final public function copy( array $params, array $opts = [] ) { return $this->doOperation( [ 'op' => 'copy' ] + $params, $opts ); } /** * Performs a single move operation. * This sets $params['op'] to 'move' and passes it to doOperation(). * * @see FileBackend::doOperation() * * @param array $params Operation parameters * @param array $opts Operation options * @return StatusValue */ final public function move( array $params, array $opts = [] ) { return $this->doOperation( [ 'op' => 'move' ] + $params, $opts ); } /** * Performs a single delete operation. * This sets $params['op'] to 'delete' and passes it to doOperation(). * * @see FileBackend::doOperation() * * @param array $params Operation parameters * @param array $opts Operation options * @return StatusValue */ final public function delete( array $params, array $opts = [] ) { return $this->doOperation( [ 'op' => 'delete' ] + $params, $opts ); } /** * Performs a single describe operation. * This sets $params['op'] to 'describe' and passes it to doOperation(). * * @see FileBackend::doOperation() * * @param array $params Operation parameters * @param array $opts Operation options * @return StatusValue * @since 1.21 */ final public function describe( array $params, array $opts = [] ) { return $this->doOperation( [ 'op' => 'describe' ] + $params, $opts ); } /** * Perform a set of independent file operations on some files. * * This does no locking, and possibly no stat calls. * Any destination files that already exist will be overwritten. * This should *only* be used on non-original files, like cache files. * * Supported operations and their parameters: * - create * - store * - copy * - move * - delete * - describe (since 1.21) * - null * * FSFile/TempFSFile object support was added in 1.27. * * a) Create a new file in storage with the contents of a string * @code * [ * 'op' => 'create', * 'dst' => <storage path>, * 'content' => <string of new file contents>, * 'headers' => <HTTP header name/value map> # since 1.21 * ] * @endcode * * b) Copy a file system file into storage * @code * [ * 'op' => 'store', * 'src' => <file system path, FSFile, or TempFSFile>, * 'dst' => <storage path>, * 'headers' => <HTTP header name/value map> # since 1.21 * ] * @endcode * * c) Copy a file within storage * @code * [ * 'op' => 'copy', * 'src' => <storage path>, * 'dst' => <storage path>, * 'ignoreMissingSource' => <boolean>, # since 1.21 * 'headers' => <HTTP header name/value map> # since 1.21 * ] * @endcode * * d) Move a file within storage * @code * [ * 'op' => 'move', * 'src' => <storage path>, * 'dst' => <storage path>, * 'ignoreMissingSource' => <boolean>, # since 1.21 * 'headers' => <HTTP header name/value map> # since 1.21 * ] * @endcode * * e) Delete a file within storage * @code * [ * 'op' => 'delete', * 'src' => <storage path>, * 'ignoreMissingSource' => <boolean> * ] * @endcode * * f) Update metadata for a file within storage * @code * [ * 'op' => 'describe', * 'src' => <storage path>, * 'headers' => <HTTP header name/value map> * ] * @endcode * * g) Do nothing (no-op) * @code * [ * 'op' => 'null', * ] * @endcode * * @par Boolean flags for operations (operation-specific): * - ignoreMissingSource : The operation will simply succeed and do * nothing if the source file does not exist. * - headers : If supplied with a header name/value map, the backend will * reply with these headers when GETs/HEADs of the destination * file are made. Header values should be smaller than 256 bytes. * Content-Disposition headers can be longer, though the system * might ignore or truncate ones that are too long to store. * Existing headers will remain, but these will replace any * conflicting previous headers, and headers will be removed * if they are set to an empty string. * Backends that don't support metadata ignore this. (since 1.21) * * $opts is an associative of boolean flags, including: * - bypassReadOnly : Allow writes in read-only mode (since 1.20) * * @par Return value: * This returns a Status, which contains all warnings and fatals that occurred * during the operation. The 'failCount', 'successCount', and 'success' members * will reflect each operation attempted for the given files. The StatusValue will be * considered "OK" as long as no fatal errors occurred. * * @param array $ops Set of operations to execute * @phan-param list<array{op:?string,src?:string,dst?:string,ignoreMissingSource?:bool,headers?:array}> $ops * @param array $opts Batch operation options * @phan-param array{bypassReadOnly?:bool} $opts * @return StatusValue * @since 1.20 */ final public function doQuickOperations( array $ops, array $opts = [] ) { if ( empty( $opts['bypassReadOnly'] ) && $this->isReadOnly() ) { return $this->newStatus( 'backend-fail-readonly', $this->name, $this->readOnly ); } if ( $ops === [] ) { return $this->newStatus(); // nothing to do } $ops = $this->resolveFSFileObjects( $ops ); foreach ( $ops as &$op ) { $op['overwrite'] = true; // avoids RTTs in key/value stores } /** @noinspection PhpUnusedLocalVariableInspection */ $scope = ScopedCallback::newScopedIgnoreUserAbort(); // try to ignore client aborts return $this->doQuickOperationsInternal( $ops, $opts ); } /** * @see FileBackend::doQuickOperations() * @param array $ops * @param array $opts * @return StatusValue * @since 1.20 */ abstract protected function doQuickOperationsInternal( array $ops, array $opts ); /** * Same as doQuickOperations() except it takes a single operation. * If you are doing a batch of operations, then use that function instead. * * @see FileBackend::doQuickOperations() * * @param array $op Operation * @param array $opts Batch operation options * @return StatusValue * @since 1.20 */ final public function doQuickOperation( array $op, array $opts = [] ) { return $this->doQuickOperations( [ $op ], $opts ); } /** * Performs a single quick create operation. * This sets $params['op'] to 'create' and passes it to doQuickOperation(). * * @see FileBackend::doQuickOperation() * * @param array $params Operation parameters * @param array $opts Operation options * @return StatusValue * @since 1.20 */ final public function quickCreate( array $params, array $opts = [] ) { return $this->doQuickOperation( [ 'op' => 'create' ] + $params, $opts ); } /** * Performs a single quick store operation. * This sets $params['op'] to 'store' and passes it to doQuickOperation(). * * @see FileBackend::doQuickOperation() * * @param array $params Operation parameters * @param array $opts Operation options * @return StatusValue * @since 1.20 */ final public function quickStore( array $params, array $opts = [] ) { return $this->doQuickOperation( [ 'op' => 'store' ] + $params, $opts ); } /** * Performs a single quick copy operation. * This sets $params['op'] to 'copy' and passes it to doQuickOperation(). * * @see FileBackend::doQuickOperation() * * @param array $params Operation parameters * @param array $opts Operation options * @return StatusValue * @since 1.20 */ final public function quickCopy( array $params, array $opts = [] ) { return $this->doQuickOperation( [ 'op' => 'copy' ] + $params, $opts ); } /** * Performs a single quick move operation. * This sets $params['op'] to 'move' and passes it to doQuickOperation(). * * @see FileBackend::doQuickOperation() * * @param array $params Operation parameters * @param array $opts Operation options * @return StatusValue * @since 1.20 */ final public function quickMove( array $params, array $opts = [] ) { return $this->doQuickOperation( [ 'op' => 'move' ] + $params, $opts ); } /** * Performs a single quick delete operation. * This sets $params['op'] to 'delete' and passes it to doQuickOperation(). * * @see FileBackend::doQuickOperation() * * @param array $params Operation parameters * @param array $opts Operation options * @return StatusValue * @since 1.20 */ final public function quickDelete( array $params, array $opts = [] ) { return $this->doQuickOperation( [ 'op' => 'delete' ] + $params, $opts ); } /** * Performs a single quick describe operation. * This sets $params['op'] to 'describe' and passes it to doQuickOperation(). * * @see FileBackend::doQuickOperation() * * @param array $params Operation parameters * @param array $opts Operation options * @return StatusValue * @since 1.21 */ final public function quickDescribe( array $params, array $opts = [] ) { return $this->doQuickOperation( [ 'op' => 'describe' ] + $params, $opts ); } /** * Concatenate a list of storage files into a single file system file. * The target path should refer to a file that is already locked or * otherwise safe from modification from other processes. Normally, * the file will be a new temp file, which should be adequate. * * @param array $params Operation parameters, include: * - srcs : ordered source storage paths (e.g. chunk1, chunk2, ...) * - dst : file system path to 0-byte temp file * - parallelize : try to do operations in parallel when possible * @return StatusValue */ abstract public function concatenate( array $params ); /** * Prepare a storage directory for usage. * This will create any required containers and parent directories. * Backends using key/value stores only need to create the container. * * The 'noAccess' and 'noListing' parameters works the same as in secure(), * except they are only applied *if* the directory/container had to be created. * These flags should always be set for directories that have private files. * However, setting them is not guaranteed to actually do anything. * Additional server configuration may be needed to achieve the desired effect. * * @param array $params Parameters include: * - dir : storage directory * - noAccess : try to deny file access (since 1.20) * - noListing : try to deny file listing (since 1.20) * - bypassReadOnly : allow writes in read-only mode (since 1.20) * @return StatusValue Good status without value for success, fatal otherwise. */ final public function prepare( array $params ) { if ( empty( $params['bypassReadOnly'] ) && $this->isReadOnly() ) { return $this->newStatus( 'backend-fail-readonly', $this->name, $this->readOnly ); } /** @noinspection PhpUnusedLocalVariableInspection */ $scope = ScopedCallback::newScopedIgnoreUserAbort(); // try to ignore client aborts return $this->doPrepare( $params ); } /** * @see FileBackend::prepare() * @param array $params * @return StatusValue Good status without value for success, fatal otherwise. */ abstract protected function doPrepare( array $params ); /** * Take measures to block web access to a storage directory and * the container it belongs to. FS backends might add .htaccess * files whereas key/value store backends might revoke container * access to the storage user representing end-users in web requests. * * This is not guaranteed to actually make files or listings publicly hidden. * Additional server configuration may be needed to achieve the desired effect. * * @param array $params Parameters include: * - dir : storage directory * - noAccess : try to deny file access * - noListing : try to deny file listing * - bypassReadOnly : allow writes in read-only mode (since 1.20) * @return StatusValue */ final public function secure( array $params ) { if ( empty( $params['bypassReadOnly'] ) && $this->isReadOnly() ) { return $this->newStatus( 'backend-fail-readonly', $this->name, $this->readOnly ); } /** @noinspection PhpUnusedLocalVariableInspection */ $scope = ScopedCallback::newScopedIgnoreUserAbort(); // try to ignore client aborts return $this->doSecure( $params ); } /** * @see FileBackend::secure() * @param array $params * @return StatusValue */ abstract protected function doSecure( array $params ); /** * Remove measures to block web access to a storage directory and * the container it belongs to. FS backends might remove .htaccess * files whereas key/value store backends might grant container * access to the storage user representing end-users in web requests. * This essentially can undo the result of secure() calls. * * This is not guaranteed to actually make files or listings publicly viewable. * Additional server configuration may be needed to achieve the desired effect. * * @param array $params Parameters include: * - dir : storage directory * - access : try to allow file access * - listing : try to allow file listing * - bypassReadOnly : allow writes in read-only mode (since 1.20) * @return StatusValue * @since 1.20 */ final public function publish( array $params ) { if ( empty( $params['bypassReadOnly'] ) && $this->isReadOnly() ) { return $this->newStatus( 'backend-fail-readonly', $this->name, $this->readOnly ); } /** @noinspection PhpUnusedLocalVariableInspection */ $scope = ScopedCallback::newScopedIgnoreUserAbort(); // try to ignore client aborts return $this->doPublish( $params ); } /** * @see FileBackend::publish() * @param array $params * @return StatusValue */ abstract protected function doPublish( array $params ); /** * Delete a storage directory if it is empty. * Backends using key/value stores may do nothing unless the directory * is that of an empty container, in which case it will be deleted. * * @param array $params Parameters include: * - dir : storage directory * - recursive : recursively delete empty subdirectories first (since 1.20) * - bypassReadOnly : allow writes in read-only mode (since 1.20) * @return StatusValue */ final public function clean( array $params ) { if ( empty( $params['bypassReadOnly'] ) && $this->isReadOnly() ) { return $this->newStatus( 'backend-fail-readonly', $this->name, $this->readOnly ); } /** @noinspection PhpUnusedLocalVariableInspection */ $scope = ScopedCallback::newScopedIgnoreUserAbort(); // try to ignore client aborts return $this->doClean( $params ); } /** * @see FileBackend::clean() * @param array $params * @return StatusValue */ abstract protected function doClean( array $params ); /** * Check if a file exists at a storage path in the backend. * This returns false if only a directory exists at the path. * * Callers that only care if a file is readily accessible can use non-strict * comparisons on the result. If "does not exist" and "existence is unknown" * must be distinguished, then strict comparisons to true/null should be used. * * @see FileBackend::EXISTENCE_ERROR * @see FileBackend::directoryExists() * * @param array $params Parameters include: * - src : source storage path * - latest : use the latest available data * @return bool|null Whether the file exists or null (I/O error) */ abstract public function fileExists( array $params ); /** * Get the last-modified timestamp of the file at a storage path. * * @see FileBackend::TIMESTAMP_FAIL * * @param array $params Parameters include: * - src : source storage path * - latest : use the latest available data * @return string|false TS_MW timestamp or false (missing file or I/O error) */ abstract public function getFileTimestamp( array $params ); /** * Get the contents of a file at a storage path in the backend. * This should be avoided for potentially large files. * * @see FileBackend::CONTENT_FAIL * * @param array $params Parameters include: * - src : source storage path * - latest : use the latest available data * @return string|false Content string or false (missing file or I/O error) */ final public function getFileContents( array $params ) { $contents = $this->getFileContentsMulti( [ 'srcs' => [ $params['src'] ] ] + $params ); return $contents[$params['src']]; } /** * Like getFileContents() except it takes an array of storage paths * and returns an order preserved map of storage paths to their content. * * @see FileBackend::getFileContents() * * @param array $params Parameters include: * - srcs : list of source storage paths * - latest : use the latest available data * - parallelize : try to do operations in parallel when possible * @return string[]|false[] Map of (path name => file content or false on failure) * @since 1.20 */ abstract public function getFileContentsMulti( array $params ); /** * Get metadata about a file at a storage path in the backend. * If the file does not exist, then this returns false. * Otherwise, the result is an associative array that includes: * - headers : map of HTTP headers used for GET/HEAD requests (name => value) * - metadata : map of file metadata (name => value) * Metadata keys and headers names will be returned in all lower-case. * Additional values may be included for internal use only. * * Use FileBackend::hasFeatures() to check how well this is supported. * * @see FileBackend::XATTRS_FAIL * * @param array $params * $params include: * - src : source storage path * - latest : use the latest available data * @return array|false File metadata array or false (missing file or I/O error) * @since 1.23 */ abstract public function getFileXAttributes( array $params ); /** * Get the size (bytes) of a file at a storage path in the backend. * * @see FileBackend::SIZE_FAIL * * @param array $params Parameters include: * - src : source storage path * - latest : use the latest available data * @return int|false File size in bytes or false (missing file or I/O error) */ abstract public function getFileSize( array $params ); /** * Get quick information about a file at a storage path in the backend. * If the file does not exist, then this returns false. * Otherwise, the result is an associative array that includes: * - mtime : the last-modified timestamp (TS_MW) * - size : the file size (bytes) * Additional values may be included for internal use only. * * @see FileBackend::STAT_ABSENT * @see FileBackend::STAT_ERROR * * @param array $params Parameters include: * - src : source storage path * - latest : use the latest available data * @return array|false|null Attribute map, false (missing file), or null (I/O error) */ abstract public function getFileStat( array $params ); /** * Get a SHA-1 hash of the content of the file at a storage path in the backend. * * @see FileBackend::SHA1_FAIL * * @param array $params Parameters include: * - src : source storage path * - latest : use the latest available data * @return string|false Hash string or false (missing file or I/O error) */ abstract public function getFileSha1Base36( array $params ); /** * Get the properties of the content of the file at a storage path in the backend. * This gives the result of FSFile::getProps() on a local copy of the file. * * @param array $params Parameters include: * - src : source storage path * - latest : use the latest available data * @return array Properties map; FSFile::placeholderProps() if file missing or on I/O error */ abstract public function getFileProps( array $params ); /** * Stream the content of the file at a storage path in the backend. * * If the file does not exists, an HTTP 404 error will be given. * Appropriate HTTP headers (Status, Content-Type, Content-Length) * will be sent if streaming began, while none will be sent otherwise. * Implementations should flush the output buffer before sending data. * * @param array $params Parameters include: * - src : source storage path * - headers : list of additional HTTP headers to send if the file exists * - options : HTTP request header map with lower case keys (since 1.28). Supports: * range : format is "bytes=(\d*-\d*)" * if-modified-since : format is an HTTP date * - headless : do not send HTTP headers (including those of "headers") (since 1.28) * - latest : use the latest available data * - allowOB : preserve any output buffers (since 1.28) * @return StatusValue */ abstract public function streamFile( array $params ); /** * Returns a file system file, identical in content to the file at a storage path. * The file returned is either: * - a) A TempFSFile local copy of the file at a storage path in the backend. * The temporary copy will have the same extension as the source. * Temporary files may be purged when the file object falls out of scope. * - b) An FSFile pointing to the original file at a storage path in the backend. * This is applicable for backends layered directly on top of file systems. * * Never modify the returned file since it might be the original, it might be shared * among multiple callers of this method, or the backend might internally keep FSFile * references for deferred operations. * * @param array $params Parameters include: * - src : source storage path * - latest : use the latest available data * @return FSFile|null|false Local file copy or false (missing) or null (error) */ final public function getLocalReference( array $params ) { $fsFiles = $this->getLocalReferenceMulti( [ 'srcs' => [ $params['src'] ] ] + $params ); return $fsFiles[$params['src']]; } /** * Like getLocalReference() except it takes an array of storage paths and * yields an order-preserved map of storage paths to temporary local file copies. * * Never modify the returned files since they might be originals, they might be shared * among multiple callers of this method, or the backend might internally keep FSFile * references for deferred operations. * * @see FileBackend::getLocalReference() * * @param array $params Parameters include: * - srcs : list of source storage paths * - latest : use the latest available data * - parallelize : try to do operations in parallel when possible * @return array Map of (path name => FSFile or false (missing) or null (error)) * @since 1.20 */ abstract public function getLocalReferenceMulti( array $params ); /** * Get a local copy on disk of the file at a storage path in the backend. * The temporary copy will have the same file extension as the source. * Temporary files may be purged when the file object falls out of scope. * * Multiple calls to this method for the same path will create new copies. * * @param array $params Parameters include: * - src : source storage path * - latest : use the latest available data * @return TempFSFile|null|false Temporary local file copy or false (missing) or null (error) */ final public function getLocalCopy( array $params ) { $tmpFiles = $this->getLocalCopyMulti( [ 'srcs' => [ $params['src'] ] ] + $params ); return $tmpFiles[$params['src']]; } /** * Like getLocalCopy() except it takes an array of storage paths and yields * an order preserved-map of storage paths to temporary local file copies. * * Multiple calls to this method for the same path will create new copies. * * @see FileBackend::getLocalCopy() * * @param array $params Parameters include: * - srcs : list of source storage paths * - latest : use the latest available data * - parallelize : try to do operations in parallel when possible * @return array Map of (path name => TempFSFile or false (missing) or null (error)) * @since 1.20 */ abstract public function getLocalCopyMulti( array $params ); /** * Return an HTTP URL to a given file that requires no authentication to use. * The URL may be pre-authenticated (via some token in the URL) and temporary. * This will return null if the backend cannot make an HTTP URL for the file. * * This is useful for key/value stores when using scripts that seek around * large files and those scripts (and the backend) support HTTP Range headers. * Otherwise, one would need to use getLocalReference(), which involves loading * the entire file on to local disk. * * @see FileBackend::TEMPURL_ERROR * * @param array $params Parameters include: * - src : source storage path * - ttl : lifetime (seconds) if pre-authenticated; default is 1 day * - latest : use the latest available data * - method : the allowed method; default GET * - ipRange : the allowed IP range; default unlimited * @return string|null URL or null (not supported or I/O error) * @since 1.21 */ abstract public function getFileHttpUrl( array $params ); /** * Add a file to a Shellbox command as an input file. * * @param BoxedCommand $command * @param string $boxedName * @param array $params Parameters include: * - src : source storage path * - latest : use the latest available data * @return StatusValue * @since 1.43 */ abstract public function addShellboxInputFile( BoxedCommand $command, string $boxedName, array $params ); /** * Check if a directory exists at a given storage path * * For backends using key/value stores, a directory is said to exist whenever * there exist any files with paths using the given directory path as a prefix * followed by a forward slash. For example, if there is a file called * "mwstore://backend/container/dir/path.svg" then directories are said to exist * at "mwstore://backend/container" and "mwstore://backend/container/dir". These * can be thought of as "virtual" directories. * * Backends that directly use a filesystem layer might enumerate empty directories. * The clean() method should always be used when files are deleted or moved if this * is a concern. This is a trade-off to avoid write amplication/contention on file * changes or read amplification when calling this method. * * Storage backends with eventual consistency might return stale data. * * @see FileBackend::EXISTENCE_ERROR * @see FileBackend::clean() * * @param array $params Parameters include: * - dir : storage directory * @return bool|null Whether a directory exists or null (I/O error) * @since 1.20 */ abstract public function directoryExists( array $params ); /** * Get an iterator to list *all* directories under a storage directory * * If the directory is of the form "mwstore://backend/container", * then all directories in the container will be listed. * If the directory is of form "mwstore://backend/container/dir", * then all directories directly under that directory will be listed. * Results will be storage directories relative to the given directory. * * Storage backends with eventual consistency might return stale data. * * Failures during iteration can result in FileBackendError exceptions (since 1.22). * * @see FileBackend::LIST_ERROR * @see FileBackend::directoryExists() * * @param array $params Parameters include: * - dir : storage directory * - topOnly : only return direct child dirs of the directory * @return \Traversable|array|null Directory list enumerator or null (initial I/O error) * @since 1.20 */ abstract public function getDirectoryList( array $params ); /** * Same as FileBackend::getDirectoryList() except only lists * directories that are immediately under the given directory. * * Storage backends with eventual consistency might return stale data. * * Failures during iteration can result in FileBackendError exceptions (since 1.22). * * @see FileBackend::LIST_ERROR * @see FileBackend::directoryExists() * * @param array $params Parameters include: * - dir : storage directory * @return \Traversable|array|null Directory list enumerator or null (initial I/O error) * @since 1.20 */ final public function getTopDirectoryList( array $params ) { return $this->getDirectoryList( [ 'topOnly' => true ] + $params ); } /** * Get an iterator to list *all* stored files under a storage directory * * If the directory is of the form "mwstore://backend/container", then all * files in the container will be listed. If the directory is of form * "mwstore://backend/container/dir", then all files under that directory will * be listed. Results will be storage paths relative to the given directory. * * Storage backends with eventual consistency might return stale data. * * Failures during iteration can result in FileBackendError exceptions (since 1.22). * * @see FileBackend::LIST_ERROR * * @param array $params Parameters include: * - dir : storage directory * - topOnly : only return direct child files of the directory (since 1.20) * - adviseStat : set to true if stat requests will be made on the files (since 1.22) * - forWrite : true if the list will inform a write operations (since 1.41) * @return \Traversable|array|null File list enumerator or null (initial I/O error) */ abstract public function getFileList( array $params ); /** * Same as FileBackend::getFileList() except only lists * files that are immediately under the given directory. * * Storage backends with eventual consistency might return stale data. * * Failures during iteration can result in FileBackendError exceptions (since 1.22). * * @see FileBackend::LIST_ERROR * * @param array $params Parameters include: * - dir : storage directory * - adviseStat : set to true if stat requests will be made on the files (since 1.22) * @return \Traversable|array|null File list enumerator or null on failure * @since 1.20 */ final public function getTopFileList( array $params ) { return $this->getFileList( [ 'topOnly' => true ] + $params ); } /** * Preload persistent file stat cache and property cache into in-process cache. * This should be used when stat calls will be made on a known list of a many files. * * @see FileBackend::getFileStat() * * @param array $paths Storage paths */ abstract public function preloadCache( array $paths ); /** * Invalidate any in-process file stat and property cache. * If $paths is given, then only the cache for those files will be cleared. * * @see FileBackend::getFileStat() * * @param array|null $paths Storage paths (optional) */ abstract public function clearCache( ?array $paths = null ); /** * Preload file stat information (concurrently if possible) into in-process cache. * * This should be used when stat calls will be made on a known list of a many files. * This does not make use of the persistent file stat cache. * * @see FileBackend::getFileStat() * * @param array $params Parameters include: * - srcs : list of source storage paths * - latest : use the latest available data * @return bool Whether all requests proceeded without I/O errors (since 1.24) * @since 1.23 */ abstract public function preloadFileStat( array $params ); /** * Lock the files at the given storage paths in the backend. * This will either lock all the files or none (on failure). * * Callers should consider using getScopedFileLocks() instead. * * @param array $paths Storage paths * @param int $type LockManager::LOCK_* constant * @param int $timeout Timeout in seconds (0 means non-blocking) (since 1.24) * @return StatusValue */ final public function lockFiles( array $paths, $type, $timeout = 0 ) { $paths = array_map( [ __CLASS__, 'normalizeStoragePath' ], $paths ); return $this->wrapStatus( $this->lockManager->lock( $paths, $type, $timeout ) ); } /** * Unlock the files at the given storage paths in the backend. * * @param array $paths Storage paths * @param int $type LockManager::LOCK_* constant * @return StatusValue */ final public function unlockFiles( array $paths, $type ) { $paths = array_map( [ __CLASS__, 'normalizeStoragePath' ], $paths ); return $this->wrapStatus( $this->lockManager->unlock( $paths, $type ) ); } /** * Lock the files at the given storage paths in the backend. * This will either lock all the files or none (on failure). * On failure, the StatusValue object will be updated with errors. * * Once the return value goes out scope, the locks will be released and * the StatusValue updated. Unlock fatals will not change the StatusValue "OK" value. * * @see ScopedLock::factory() * * @param array $paths List of storage paths or map of lock types to path lists * @param int|string $type LockManager::LOCK_* constant or "mixed" * @param StatusValue $status StatusValue to update on lock/unlock * @param int $timeout Timeout in seconds (0 means non-blocking) (since 1.24) * @return ScopedLock|null RAII-style self-unlocking lock or null on failure */ final public function getScopedFileLocks( array $paths, $type, StatusValue $status, $timeout = 0 ) { if ( $type === 'mixed' ) { foreach ( $paths as &$typePaths ) { $typePaths = array_map( [ __CLASS__, 'normalizeStoragePath' ], $typePaths ); } } else { $paths = array_map( [ __CLASS__, 'normalizeStoragePath' ], $paths ); } return ScopedLock::factory( $this->lockManager, $paths, $type, $status, $timeout ); } /** * Get an array of scoped locks needed for a batch of file operations. * * Normally, FileBackend::doOperations() handles locking, unless * the 'nonLocking' param is passed in. This function is useful if you * want the files to be locked for a broader scope than just when the * files are changing. For example, if you need to update DB metadata, * you may want to keep the files locked until finished. * * @see FileBackend::doOperations() * * @param array $ops List of file operations to FileBackend::doOperations() * @param StatusValue $status StatusValue to update on lock/unlock * @return ScopedLock|null RAII-style self-unlocking lock or null on failure * @since 1.20 */ abstract public function getScopedLocksForOps( array $ops, StatusValue $status ); /** * Get the root storage path of this backend. * All container paths are "subdirectories" of this path. * * @return string Storage path * @since 1.20 */ final public function getRootStoragePath() { return "mwstore://{$this->name}"; } /** * Get the storage path for the given container for this backend * * @param string $container Container name * @return string Storage path * @since 1.21 */ final public function getContainerStoragePath( $container ) { return $this->getRootStoragePath() . "/{$container}"; } /** * Convert FSFile 'src' paths to string paths (with an 'srcRef' field set to the FSFile) * * The 'srcRef' field keeps any TempFSFile objects in scope for the backend to have it * around as long it needs (which may vary greatly depending on configuration) * * @param array $ops File operation batch for FileBaclend::doOperations() * @return array File operation batch */ protected function resolveFSFileObjects( array $ops ) { foreach ( $ops as &$op ) { $src = $op['src'] ?? null; if ( $src instanceof FSFile ) { $op['srcRef'] = $src; $op['src'] = $src->getPath(); } } unset( $op ); return $ops; } /** * Check if a given path is a "mwstore://" path. * This does not do any further validation or any existence checks. * * @param string|null $path * @return bool */ final public static function isStoragePath( $path ) { return ( strpos( $path ?? '', 'mwstore://' ) === 0 ); } /** * Split a storage path into a backend name, a container name, * and a relative file path. The relative path may be the empty string. * This does not do any path normalization or traversal checks. * * @param string $storagePath * @return array (backend, container, rel object) or (null, null, null) */ final public static function splitStoragePath( $storagePath ) { if ( self::isStoragePath( $storagePath ) ) { // Remove the "mwstore://" prefix and split the path $parts = explode( '/', substr( $storagePath, 10 ), 3 ); if ( count( $parts ) >= 2 && $parts[0] != '' && $parts[1] != '' ) { if ( count( $parts ) == 3 ) { return $parts; // e.g. "backend/container/path" } else { return [ $parts[0], $parts[1], '' ]; // e.g. "backend/container" } } } return [ null, null, null ]; } /** * Normalize a storage path by cleaning up directory separators. * Returns null if the path is not of the format of a valid storage path. * * @param string $storagePath * @return string|null Normalized storage path or null on failure */ final public static function normalizeStoragePath( $storagePath ) { [ $backend, $container, $relPath ] = self::splitStoragePath( $storagePath ); if ( $relPath !== null ) { // must be for this backend $relPath = self::normalizeContainerPath( $relPath ); if ( $relPath !== null ) { return ( $relPath != '' ) ? "mwstore://{$backend}/{$container}/{$relPath}" : "mwstore://{$backend}/{$container}"; } } return null; } /** * Get the parent storage directory of a storage path. * This returns a path like "mwstore://backend/container", * "mwstore://backend/container/...", or null if there is no parent. * * @param string $storagePath * @return string|null Parent storage path or null on failure */ final public static function parentStoragePath( $storagePath ) { // XXX dirname() depends on platform and locale! If nothing enforces that the storage path // doesn't contain characters like '\', behavior can vary by platform. We should use // explode() instead. $storagePath = dirname( $storagePath ); [ , , $rel ] = self::splitStoragePath( $storagePath ); return ( $rel === null ) ? null : $storagePath; } /** * Get the final extension from a storage or FS path * * @param string $path * @param string $case One of (rawcase, uppercase, lowercase) (since 1.24) * @return string */ final public static function extensionFromPath( $path, $case = 'lowercase' ) { // This will treat a string starting with . as not having an extension, but store paths have // to start with 'mwstore://', so "garbage in, garbage out". $i = strrpos( $path ?? '', '.' ); $ext = $i ? substr( $path, $i + 1 ) : ''; if ( $case === 'lowercase' ) { $ext = strtolower( $ext ); } elseif ( $case === 'uppercase' ) { $ext = strtoupper( $ext ); } return $ext; } /** * Check if a relative path has no directory traversals * * @param string $path * @return bool * @since 1.20 */ final public static function isPathTraversalFree( $path ) { return ( self::normalizeContainerPath( $path ) !== null ); } /** * Build a Content-Disposition header value per RFC 6266. * * @param string $type One of (attachment, inline) * @param string $filename Suggested file name (should not contain slashes) * @return string * @since 1.20 */ final public static function makeContentDisposition( $type, $filename = '' ) { $parts = []; $type = strtolower( $type ); if ( !in_array( $type, [ 'inline', 'attachment' ] ) ) { throw new InvalidArgumentException( "Invalid Content-Disposition type '$type'." ); } $parts[] = $type; if ( strlen( $filename ) ) { $parts[] = "filename*=UTF-8''" . rawurlencode( basename( $filename ) ); } return implode( ';', $parts ); } /** * Validate and normalize a relative storage path. * Null is returned if the path involves directory traversal. * Traversal is insecure for FS backends and broken for others. * * This uses the same traversal protection as Title::secureAndSplit(). * * @param string $path Storage path relative to a container * @return string|null Normalized container path or null on failure */ final protected static function normalizeContainerPath( $path ) { // Normalize directory separators $path = strtr( $path, '\\', '/' ); // Collapse any consecutive directory separators $path = preg_replace( '![/]{2,}!', '/', $path ); // Remove any leading directory separator $path = ltrim( $path, '/' ); // Use the same traversal protection as Title::secureAndSplit() if ( strpos( $path, '.' ) !== false ) { if ( $path === '.' || $path === '..' || strpos( $path, './' ) === 0 || strpos( $path, '../' ) === 0 || strpos( $path, '/./' ) !== false || strpos( $path, '/../' ) !== false ) { return null; } } return $path; } /** * Yields the result of the status wrapper callback on either: * - StatusValue::newGood() if this method is called without parameters * - StatusValue::newFatal() with all parameters to this method if passed in * * @param mixed ...$args * @return StatusValue */ final protected function newStatus( ...$args ) { if ( count( $args ) ) { $sv = StatusValue::newFatal( ...$args ); } else { $sv = StatusValue::newGood(); } return $this->wrapStatus( $sv ); } /** * @param StatusValue $sv * @return StatusValue Modified status or StatusValue subclass */ final protected function wrapStatus( StatusValue $sv ) { return $this->statusWrapper ? call_user_func( $this->statusWrapper, $sv ) : $sv; } /** * @param string $section * @return ScopedCallback|null */ protected function scopedProfileSection( $section ) { return $this->profiler ? ( $this->profiler )( $section ) : null; } /** * Default behavior of resetOutputBuffer(). * @codeCoverageIgnore * @internal */ public static function resetOutputBufferTheDefaultWay() { // XXX According to documentation, ob_get_status() always returns a non-empty array and this // condition will always be true while ( ob_get_status() ) { if ( !ob_end_clean() ) { // Could not remove output buffer handler; abort now // to avoid getting in some kind of infinite loop. break; } } } /** * Return options for use with HTTPFileStreamer. * * @internal */ public function getStreamerOptions(): array { return $this->streamerOptions; } } /** @deprecated class alias since 1.43 */ class_alias( FileBackend::class, 'FileBackend' ); PK ! �as�x �x % filebackend/FileBackendMultiWrite.phpnu �Iw�� <?php /** * Proxy backend that mirrors writes to several internal backends. * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file * @ingroup FileBackend */ namespace Wikimedia\FileBackend; use InvalidArgumentException; use LockManager; use LogicException; use MediaWiki\Deferred\DeferredUpdates; use MediaWiki\Json\FormatJson; use Shellbox\Command\BoxedCommand; use StatusValue; use StringUtils; use Wikimedia\Timestamp\ConvertibleTimestamp; /** * @brief Proxy backend that mirrors writes to several internal backends. * * This class defines a multi-write backend. Multiple backends can be * registered to this proxy backend and it will act as a single backend. * Use this when all access to those backends is through this proxy backend. * At least one of the backends must be declared the "master" backend. * * Only use this class when transitioning from one storage system to another. * * Read operations are only done on the 'master' backend for consistency. * Except on getting list of thumbnails for write operations. * Write operations are performed on all backends, starting with the master. * This makes a best-effort to have transactional semantics, but since requests * may sometimes fail, the use of "autoResync" or background scripts to fix * inconsistencies is important. * * @ingroup FileBackend * @since 1.19 */ class FileBackendMultiWrite extends FileBackend { /** @var FileBackendStore[] Prioritized list of FileBackendStore objects */ protected $backends = []; /** @var int Index of master backend */ protected $masterIndex = -1; /** @var int Index of read affinity backend */ protected $readIndex = -1; /** @var int Bitfield */ protected $syncChecks = 0; /** @var string|bool */ protected $autoResync = false; /** @var bool */ protected $asyncWrites = false; /** @var int Compare file sizes among backends */ private const CHECK_SIZE = 1; /** @var int Compare file mtimes among backends */ private const CHECK_TIME = 2; /** @var int Compare file hashes among backends */ private const CHECK_SHA1 = 4; /** * Construct a proxy backend that consists of several internal backends. * Locking and read-only checks are handled by the proxy backend. * * Additional $config params include: * - backends : Array of backend config and multi-backend settings. * Each value is the config used in the constructor of a * FileBackendStore class, but with these additional settings: * - class : The name of the backend class * - isMultiMaster : This must be set for one backend. * - readAffinity : Use this for reads without 'latest' set. * - syncChecks : Integer bitfield of internal backend sync checks to perform. * Possible bits include the FileBackendMultiWrite::CHECK_* constants. * There are constants for SIZE, TIME, and SHA1. * The checks are done before allowing any file operations. * - autoResync : Automatically resync the clone backends to the master backend * when pre-operation sync checks fail. This should only be used * if the master backend is stable and not missing any files. * Use "conservative" to limit resyncing to copying newer master * backend files over older (or non-existing) clone backend files. * Cases that cannot be handled will result in operation abortion. * - replication : Set to 'async' to defer file operations on the non-master backends. * This will apply such updates post-send for web requests. Note that * any checks from "syncChecks" are still synchronous. * * @param array $config */ public function __construct( array $config ) { parent::__construct( $config ); $this->syncChecks = $config['syncChecks'] ?? self::CHECK_SIZE; $this->autoResync = $config['autoResync'] ?? false; $this->asyncWrites = isset( $config['replication'] ) && $config['replication'] === 'async'; // Construct backends here rather than via registration // to keep these backends hidden from outside the proxy. $namesUsed = []; foreach ( $config['backends'] as $index => $beConfig ) { $name = $beConfig['name']; if ( isset( $namesUsed[$name] ) ) { // don't break FileOp predicates throw new LogicException( "Two or more backends defined with the name $name." ); } $namesUsed[$name] = 1; // Alter certain sub-backend settings unset( $beConfig['readOnly'] ); // use proxy backend setting unset( $beConfig['lockManager'] ); // lock under proxy backend $beConfig['domainId'] = $this->domainId; // use the proxy backend wiki ID $beConfig['logger'] = $this->logger; // use the proxy backend logger if ( !empty( $beConfig['isMultiMaster'] ) ) { if ( $this->masterIndex >= 0 ) { throw new LogicException( 'More than one master backend defined.' ); } $this->masterIndex = $index; // this is the "master" } if ( !empty( $beConfig['readAffinity'] ) ) { $this->readIndex = $index; // prefer this for reads } // Create sub-backend object if ( !isset( $beConfig['class'] ) ) { throw new InvalidArgumentException( 'No class given for a backend config.' ); } $class = $beConfig['class']; $this->backends[$index] = new $class( $beConfig ); } if ( $this->masterIndex < 0 ) { // need backends and must have a master throw new LogicException( 'No master backend defined.' ); } if ( $this->readIndex < 0 ) { $this->readIndex = $this->masterIndex; // default } } final protected function doOperationsInternal( array $ops, array $opts ) { $status = $this->newStatus(); $fname = __METHOD__; $mbe = $this->backends[$this->masterIndex]; // convenience // Acquire any locks as needed $scopeLock = null; if ( empty( $opts['nonLocking'] ) ) { $scopeLock = $this->getScopedLocksForOps( $ops, $status ); if ( !$status->isOK() ) { return $status; // abort } } // Get the list of paths to read/write $relevantPaths = $this->fileStoragePathsForOps( $ops ); // Clear any cache entries (after locks acquired) $this->clearCache( $relevantPaths ); $opts['preserveCache'] = true; // only locked files are cached // Check if the paths are valid and accessible on all backends $status->merge( $this->accessibilityCheck( $relevantPaths ) ); if ( !$status->isOK() ) { return $status; // abort } // Do a consistency check to see if the backends are consistent $syncStatus = $this->consistencyCheck( $relevantPaths ); if ( !$syncStatus->isOK() ) { $this->logger->error( "$fname: failed sync check: " . FormatJson::encode( $relevantPaths ) ); // Try to resync the clone backends to the master on the spot if ( $this->autoResync === false || !$this->resyncFiles( $relevantPaths, $this->autoResync )->isOK() ) { $status->merge( $syncStatus ); return $status; // abort } } // Actually attempt the operation batch on the master backend $realOps = $this->substOpBatchPaths( $ops, $mbe ); $masterStatus = $mbe->doOperations( $realOps, $opts ); $status->merge( $masterStatus ); // Propagate the operations to the clone backends if there were no unexpected errors // and everything didn't fail due to predicted errors. If $ops only had one operation, // this might avoid backend sync inconsistencies. if ( $masterStatus->isOK() && $masterStatus->successCount > 0 ) { foreach ( $this->backends as $index => $backend ) { if ( $index === $this->masterIndex ) { continue; // done already } $realOps = $this->substOpBatchPaths( $ops, $backend ); if ( $this->asyncWrites && !$this->hasVolatileSources( $ops ) ) { // Bind $scopeLock to the callback to preserve locks DeferredUpdates::addCallableUpdate( function () use ( $backend, $realOps, $opts, $scopeLock, $relevantPaths, $fname ) { $this->logger->debug( "$fname: '{$backend->getName()}' async replication; paths: " . FormatJson::encode( $relevantPaths ) ); $backend->doOperations( $realOps, $opts ); } ); } else { $this->logger->debug( "$fname: '{$backend->getName()}' sync replication; paths: " . FormatJson::encode( $relevantPaths ) ); $status->merge( $backend->doOperations( $realOps, $opts ) ); } } } // Make 'success', 'successCount', and 'failCount' fields reflect // the overall operation, rather than all the batches for each backend. // Do this by only using success values from the master backend's batch. $status->success = $masterStatus->success; $status->successCount = $masterStatus->successCount; $status->failCount = $masterStatus->failCount; return $status; } /** * Check that a set of files are consistent across all internal backends * * This method should only be called if the files are locked or the backend * is in read-only mode * * @param array $paths List of storage paths * @return StatusValue */ public function consistencyCheck( array $paths ) { $status = $this->newStatus(); if ( $this->syncChecks == 0 || count( $this->backends ) <= 1 ) { return $status; // skip checks } // Preload all of the stat info in as few round trips as possible foreach ( $this->backends as $backend ) { $realPaths = $this->substPaths( $paths, $backend ); $backend->preloadFileStat( [ 'srcs' => $realPaths, 'latest' => true ] ); } foreach ( $paths as $path ) { $params = [ 'src' => $path, 'latest' => true ]; // Get the state of the file on the master backend $masterBackend = $this->backends[$this->masterIndex]; $masterParams = $this->substOpPaths( $params, $masterBackend ); $masterStat = $masterBackend->getFileStat( $masterParams ); if ( $masterStat === self::STAT_ERROR ) { $status->fatal( 'backend-fail-stat', $path ); continue; } if ( $this->syncChecks & self::CHECK_SHA1 ) { $masterSha1 = $masterBackend->getFileSha1Base36( $masterParams ); if ( ( $masterSha1 !== false ) !== (bool)$masterStat ) { $status->fatal( 'backend-fail-hash', $path ); continue; } } else { $masterSha1 = null; // unused } // Check if all clone backends agree with the master... foreach ( $this->backends as $index => $cloneBackend ) { if ( $index === $this->masterIndex ) { continue; // master } // Get the state of the file on the clone backend $cloneParams = $this->substOpPaths( $params, $cloneBackend ); $cloneStat = $cloneBackend->getFileStat( $cloneParams ); if ( $masterStat ) { // File exists in the master backend if ( !$cloneStat ) { // File is missing from the clone backend $status->fatal( 'backend-fail-synced', $path ); } elseif ( ( $this->syncChecks & self::CHECK_SIZE ) && $cloneStat['size'] !== $masterStat['size'] ) { // File in the clone backend is different $status->fatal( 'backend-fail-synced', $path ); } elseif ( ( $this->syncChecks & self::CHECK_TIME ) && abs( (int)ConvertibleTimestamp::convert( TS_UNIX, $masterStat['mtime'] ) - (int)ConvertibleTimestamp::convert( TS_UNIX, $cloneStat['mtime'] ) ) > 30 ) { // File in the clone backend is significantly newer or older $status->fatal( 'backend-fail-synced', $path ); } elseif ( ( $this->syncChecks & self::CHECK_SHA1 ) && $cloneBackend->getFileSha1Base36( $cloneParams ) !== $masterSha1 ) { // File in the clone backend is different $status->fatal( 'backend-fail-synced', $path ); } } else { // File does not exist in the master backend if ( $cloneStat ) { // Stray file exists in the clone backend $status->fatal( 'backend-fail-synced', $path ); } } } } return $status; } /** * Check that a set of file paths are usable across all internal backends * * @param array $paths List of storage paths * @return StatusValue */ public function accessibilityCheck( array $paths ) { $status = $this->newStatus(); if ( count( $this->backends ) <= 1 ) { return $status; // skip checks } foreach ( $paths as $path ) { foreach ( $this->backends as $backend ) { $realPath = $this->substPaths( $path, $backend ); if ( !$backend->isPathUsableInternal( $realPath ) ) { $status->fatal( 'backend-fail-usable', $path ); } } } return $status; } /** * Check that a set of files are consistent across all internal backends * and re-synchronize those files against the "multi master" if needed. * * This method should only be called if the files are locked * * @param array $paths List of storage paths * @param string|bool $resyncMode False, True, or "conservative"; see __construct() * @return StatusValue */ public function resyncFiles( array $paths, $resyncMode = true ) { $status = $this->newStatus(); $fname = __METHOD__; foreach ( $paths as $path ) { $params = [ 'src' => $path, 'latest' => true ]; // Get the state of the file on the master backend $masterBackend = $this->backends[$this->masterIndex]; $masterParams = $this->substOpPaths( $params, $masterBackend ); $masterPath = $masterParams['src']; $masterStat = $masterBackend->getFileStat( $masterParams ); if ( $masterStat === self::STAT_ERROR ) { $status->fatal( 'backend-fail-stat', $path ); $this->logger->error( "$fname: file '$masterPath' is not available" ); continue; } $masterSha1 = $masterBackend->getFileSha1Base36( $masterParams ); if ( ( $masterSha1 !== false ) !== (bool)$masterStat ) { $status->fatal( 'backend-fail-hash', $path ); $this->logger->error( "$fname: file '$masterPath' hash does not match stat" ); continue; } // Check of all clone backends agree with the master... foreach ( $this->backends as $index => $cloneBackend ) { if ( $index === $this->masterIndex ) { continue; // master } // Get the state of the file on the clone backend $cloneParams = $this->substOpPaths( $params, $cloneBackend ); $clonePath = $cloneParams['src']; $cloneStat = $cloneBackend->getFileStat( $cloneParams ); if ( $cloneStat === self::STAT_ERROR ) { $status->fatal( 'backend-fail-stat', $path ); $this->logger->error( "$fname: file '$clonePath' is not available" ); continue; } $cloneSha1 = $cloneBackend->getFileSha1Base36( $cloneParams ); if ( ( $cloneSha1 !== false ) !== (bool)$cloneStat ) { $status->fatal( 'backend-fail-hash', $path ); $this->logger->error( "$fname: file '$clonePath' hash does not match stat" ); continue; } if ( $masterSha1 === $cloneSha1 ) { // File is either the same in both backends or absent from both backends $this->logger->debug( "$fname: file '$clonePath' matches '$masterPath'" ); } elseif ( $masterSha1 !== false ) { // File is either missing from or different in the clone backend if ( $resyncMode === 'conservative' && $cloneStat && // @phan-suppress-next-line PhanTypeArraySuspiciousNullable $cloneStat['mtime'] > $masterStat['mtime'] ) { // Do not replace files with older ones; reduces the risk of data loss $status->fatal( 'backend-fail-synced', $path ); } else { // Copy the master backend file to the clone backend in overwrite mode $fsFile = $masterBackend->getLocalReference( $masterParams ); $status->merge( $cloneBackend->quickStore( [ 'src' => $fsFile, 'dst' => $clonePath ] ) ); } } elseif ( $masterStat === false ) { // Stray file exists in the clone backend if ( $resyncMode === 'conservative' ) { // Do not delete stray files; reduces the risk of data loss $status->fatal( 'backend-fail-synced', $path ); $this->logger->error( "$fname: not allowed to delete file '$clonePath'" ); } else { // Delete the stay file from the clone backend $status->merge( $cloneBackend->quickDelete( [ 'src' => $clonePath ] ) ); } } } } if ( !$status->isOK() ) { $this->logger->error( "$fname: failed to resync: " . FormatJson::encode( $paths ) ); } return $status; } /** * Get a list of file storage paths to read or write for a list of operations * * @param array $ops Same format as doOperations() * @return array List of storage paths to files (does not include directories) */ protected function fileStoragePathsForOps( array $ops ) { $paths = []; foreach ( $ops as $op ) { if ( isset( $op['src'] ) ) { // For things like copy/move/delete with "ignoreMissingSource" and there // is no source file, nothing should happen and there should be no errors. if ( empty( $op['ignoreMissingSource'] ) || $this->fileExists( [ 'src' => $op['src'] ] ) ) { $paths[] = $op['src']; } } if ( isset( $op['srcs'] ) ) { $paths = array_merge( $paths, $op['srcs'] ); } if ( isset( $op['dst'] ) ) { $paths[] = $op['dst']; } } return array_values( array_unique( array_filter( $paths, [ FileBackend::class, 'isStoragePath' ] ) ) ); } /** * Substitute the backend name in storage path parameters * for a set of operations with that of a given internal backend. * * @param array $ops List of file operation arrays * @param FileBackendStore $backend * @return array */ protected function substOpBatchPaths( array $ops, FileBackendStore $backend ) { $newOps = []; // operations foreach ( $ops as $op ) { $newOp = $op; // operation foreach ( [ 'src', 'srcs', 'dst', 'dir' ] as $par ) { if ( isset( $newOp[$par] ) ) { // string or array $newOp[$par] = $this->substPaths( $newOp[$par], $backend ); } } $newOps[] = $newOp; } return $newOps; } /** * Same as substOpBatchPaths() but for a single operation * * @param array $ops File operation array * @param FileBackendStore $backend * @return array */ protected function substOpPaths( array $ops, FileBackendStore $backend ) { $newOps = $this->substOpBatchPaths( [ $ops ], $backend ); return $newOps[0]; } /** * Substitute the backend of storage paths with an internal backend's name * * @param array|string $paths List of paths or single string path * @param FileBackendStore $backend * @return string[]|string */ protected function substPaths( $paths, FileBackendStore $backend ) { return preg_replace( '!^mwstore://' . preg_quote( $this->name, '!' ) . '/!', StringUtils::escapeRegexReplacement( "mwstore://{$backend->getName()}/" ), $paths // string or array ); } /** * Substitute the backend of internal storage paths with the proxy backend's name * * @param array|string $paths List of paths or single string path * @param FileBackendStore $backend internal storage backend * @return string[]|string */ protected function unsubstPaths( $paths, FileBackendStore $backend ) { return preg_replace( '!^mwstore://' . preg_quote( $backend->getName(), '!' ) . '/!', StringUtils::escapeRegexReplacement( "mwstore://{$this->name}/" ), $paths // string or array ); } /** * @param array[] $ops File operations for FileBackend::doOperations() * @return bool Whether there are file path sources with outside lifetime/ownership */ protected function hasVolatileSources( array $ops ) { foreach ( $ops as $op ) { if ( $op['op'] === 'store' && !isset( $op['srcRef'] ) ) { return true; // source file might be deleted anytime after do*Operations() } } return false; } protected function doQuickOperationsInternal( array $ops, array $opts ) { $status = $this->newStatus(); // Do the operations on the master backend; setting StatusValue fields $realOps = $this->substOpBatchPaths( $ops, $this->backends[$this->masterIndex] ); $masterStatus = $this->backends[$this->masterIndex]->doQuickOperations( $realOps ); $status->merge( $masterStatus ); // Propagate the operations to the clone backends... foreach ( $this->backends as $index => $backend ) { if ( $index === $this->masterIndex ) { continue; // done already } $realOps = $this->substOpBatchPaths( $ops, $backend ); if ( $this->asyncWrites && !$this->hasVolatileSources( $ops ) ) { DeferredUpdates::addCallableUpdate( static function () use ( $backend, $realOps ) { $backend->doQuickOperations( $realOps ); } ); } else { $status->merge( $backend->doQuickOperations( $realOps ) ); } } // Make 'success', 'successCount', and 'failCount' fields reflect // the overall operation, rather than all the batches for each backend. // Do this by only using success values from the master backend's batch. $status->success = $masterStatus->success; $status->successCount = $masterStatus->successCount; $status->failCount = $masterStatus->failCount; return $status; } protected function doPrepare( array $params ) { return $this->doDirectoryOp( 'prepare', $params ); } protected function doSecure( array $params ) { return $this->doDirectoryOp( 'secure', $params ); } protected function doPublish( array $params ) { return $this->doDirectoryOp( 'publish', $params ); } protected function doClean( array $params ) { return $this->doDirectoryOp( 'clean', $params ); } /** * @param string $method One of (doPrepare,doSecure,doPublish,doClean) * @param array $params Method arguments * @return StatusValue */ protected function doDirectoryOp( $method, array $params ) { $status = $this->newStatus(); $realParams = $this->substOpPaths( $params, $this->backends[$this->masterIndex] ); $masterStatus = $this->backends[$this->masterIndex]->$method( $realParams ); $status->merge( $masterStatus ); foreach ( $this->backends as $index => $backend ) { if ( $index === $this->masterIndex ) { continue; // already done } $realParams = $this->substOpPaths( $params, $backend ); if ( $this->asyncWrites ) { DeferredUpdates::addCallableUpdate( static function () use ( $backend, $method, $realParams ) { $backend->$method( $realParams ); } ); } else { $status->merge( $backend->$method( $realParams ) ); } } return $status; } public function concatenate( array $params ) { $status = $this->newStatus(); // We are writing to an FS file, so we don't need to do this per-backend $index = $this->getReadIndexFromParams( $params ); $realParams = $this->substOpPaths( $params, $this->backends[$index] ); $status->merge( $this->backends[$index]->concatenate( $realParams ) ); return $status; } public function fileExists( array $params ) { $index = $this->getReadIndexFromParams( $params ); $realParams = $this->substOpPaths( $params, $this->backends[$index] ); return $this->backends[$index]->fileExists( $realParams ); } public function getFileTimestamp( array $params ) { $index = $this->getReadIndexFromParams( $params ); $realParams = $this->substOpPaths( $params, $this->backends[$index] ); return $this->backends[$index]->getFileTimestamp( $realParams ); } public function getFileSize( array $params ) { $index = $this->getReadIndexFromParams( $params ); $realParams = $this->substOpPaths( $params, $this->backends[$index] ); return $this->backends[$index]->getFileSize( $realParams ); } public function getFileStat( array $params ) { $index = $this->getReadIndexFromParams( $params ); $realParams = $this->substOpPaths( $params, $this->backends[$index] ); return $this->backends[$index]->getFileStat( $realParams ); } public function getFileXAttributes( array $params ) { $index = $this->getReadIndexFromParams( $params ); $realParams = $this->substOpPaths( $params, $this->backends[$index] ); return $this->backends[$index]->getFileXAttributes( $realParams ); } public function getFileContentsMulti( array $params ) { $index = $this->getReadIndexFromParams( $params ); $realParams = $this->substOpPaths( $params, $this->backends[$index] ); $contentsM = $this->backends[$index]->getFileContentsMulti( $realParams ); $contents = []; // (path => FSFile) mapping using the proxy backend's name foreach ( $contentsM as $path => $data ) { $contents[$this->unsubstPaths( $path, $this->backends[$index] )] = $data; } return $contents; } public function getFileSha1Base36( array $params ) { $index = $this->getReadIndexFromParams( $params ); $realParams = $this->substOpPaths( $params, $this->backends[$index] ); return $this->backends[$index]->getFileSha1Base36( $realParams ); } public function getFileProps( array $params ) { $index = $this->getReadIndexFromParams( $params ); $realParams = $this->substOpPaths( $params, $this->backends[$index] ); return $this->backends[$index]->getFileProps( $realParams ); } public function streamFile( array $params ) { $index = $this->getReadIndexFromParams( $params ); $realParams = $this->substOpPaths( $params, $this->backends[$index] ); return $this->backends[$index]->streamFile( $realParams ); } public function getLocalReferenceMulti( array $params ) { $index = $this->getReadIndexFromParams( $params ); $realParams = $this->substOpPaths( $params, $this->backends[$index] ); $fsFilesM = $this->backends[$index]->getLocalReferenceMulti( $realParams ); $fsFiles = []; // (path => FSFile) mapping using the proxy backend's name foreach ( $fsFilesM as $path => $fsFile ) { $fsFiles[$this->unsubstPaths( $path, $this->backends[$index] )] = $fsFile; } return $fsFiles; } public function getLocalCopyMulti( array $params ) { $index = $this->getReadIndexFromParams( $params ); $realParams = $this->substOpPaths( $params, $this->backends[$index] ); $tempFilesM = $this->backends[$index]->getLocalCopyMulti( $realParams ); $tempFiles = []; // (path => TempFSFile) mapping using the proxy backend's name foreach ( $tempFilesM as $path => $tempFile ) { $tempFiles[$this->unsubstPaths( $path, $this->backends[$index] )] = $tempFile; } return $tempFiles; } public function getFileHttpUrl( array $params ) { $index = $this->getReadIndexFromParams( $params ); $realParams = $this->substOpPaths( $params, $this->backends[$index] ); return $this->backends[$index]->getFileHttpUrl( $realParams ); } public function addShellboxInputFile( BoxedCommand $command, string $boxedName, array $params ) { $index = $this->getReadIndexFromParams( $params ); $realParams = $this->substOpPaths( $params, $this->backends[$index] ); return $this->backends[$index]->addShellboxInputFile( $command, $boxedName, $realParams ); } public function directoryExists( array $params ) { $realParams = $this->substOpPaths( $params, $this->backends[$this->masterIndex] ); return $this->backends[$this->masterIndex]->directoryExists( $realParams ); } public function getDirectoryList( array $params ) { $realParams = $this->substOpPaths( $params, $this->backends[$this->masterIndex] ); return $this->backends[$this->masterIndex]->getDirectoryList( $realParams ); } public function getFileList( array $params ) { if ( isset( $params['forWrite'] ) && $params['forWrite'] ) { return $this->getFileListForWrite( $params ); } $realParams = $this->substOpPaths( $params, $this->backends[$this->masterIndex] ); return $this->backends[$this->masterIndex]->getFileList( $realParams ); } private function getFileListForWrite( $params ) { $files = []; // Get the list of thumbnails from all backends to allow // deleting all of them. Otherwise, old thumbnails existing on // one backend only won't get updated in reupload (T331138). foreach ( $this->backends as $backend ) { $realParams = $this->substOpPaths( $params, $backend ); $iterator = $backend->getFileList( $realParams ); if ( $iterator !== null ) { foreach ( $iterator as $file ) { $files[] = $file; } } } return array_unique( $files ); } public function getFeatures() { return $this->backends[$this->masterIndex]->getFeatures(); } public function clearCache( ?array $paths = null ) { foreach ( $this->backends as $backend ) { $realPaths = is_array( $paths ) ? $this->substPaths( $paths, $backend ) : null; $backend->clearCache( $realPaths ); } } public function preloadCache( array $paths ) { $realPaths = $this->substPaths( $paths, $this->backends[$this->readIndex] ); $this->backends[$this->readIndex]->preloadCache( $realPaths ); } public function preloadFileStat( array $params ) { $index = $this->getReadIndexFromParams( $params ); $realParams = $this->substOpPaths( $params, $this->backends[$index] ); return $this->backends[$index]->preloadFileStat( $realParams ); } public function getScopedLocksForOps( array $ops, StatusValue $status ) { $realOps = $this->substOpBatchPaths( $ops, $this->backends[$this->masterIndex] ); $fileOps = $this->backends[$this->masterIndex]->getOperationsInternal( $realOps ); // Get the paths to lock from the master backend $paths = $this->backends[$this->masterIndex]->getPathsToLockForOpsInternal( $fileOps ); // Get the paths under the proxy backend's name $pbPaths = [ LockManager::LOCK_UW => $this->unsubstPaths( $paths[LockManager::LOCK_UW], $this->backends[$this->masterIndex] ), LockManager::LOCK_EX => $this->unsubstPaths( $paths[LockManager::LOCK_EX], $this->backends[$this->masterIndex] ) ]; // Actually acquire the locks return $this->getScopedFileLocks( $pbPaths, 'mixed', $status ); } /** * @param array $params * @return int The master or read affinity backend index, based on $params['latest'] */ protected function getReadIndexFromParams( array $params ) { return !empty( $params['latest'] ) ? $this->masterIndex : $this->readIndex; } } /** @deprecated class alias since 1.43 */ class_alias( FileBackendMultiWrite::class, 'FileBackendMultiWrite' ); PK ! �N�ڄ$ �$ filebackend/HTTPFileStreamer.phpnu �Iw�� <?php /** * Functions related to the output of file content. * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\FileBackend; use HttpStatus; use Wikimedia\AtEase\AtEase; use Wikimedia\Timestamp\ConvertibleTimestamp; /** * Functions related to the output of file content * * @since 1.28 */ class HTTPFileStreamer { /** @var string */ protected $path; /** @var callable */ protected $obResetFunc; /** @var callable */ protected $streamMimeFunc; /** @var callable */ protected $headerFunc; // Do not send any HTTP headers (i.e. body only) public const STREAM_HEADLESS = 1; // Do not try to tear down any PHP output buffers public const STREAM_ALLOW_OB = 2; /** * Takes HTTP headers in a name => value format and converts them to the weird format * expected by stream(). * @param string[] $headers * @return array[] [ $headers, $optHeaders ] * @since 1.34 */ public static function preprocessHeaders( $headers ) { $rawHeaders = []; $optHeaders = []; foreach ( $headers as $name => $header ) { $nameLower = strtolower( $name ); if ( in_array( $nameLower, [ 'range', 'if-modified-since' ], true ) ) { $optHeaders[$nameLower] = $header; } else { $rawHeaders[] = "$name: $header"; } } return [ $rawHeaders, $optHeaders ]; } /** * @param string $path Local filesystem path to a file * @param array $params Options map, which includes: * - obResetFunc : alternative callback to clear the output buffer * - streamMimeFunc : alternative method to determine the content type from the path * - headerFunc : alternative method for sending response headers */ public function __construct( $path, array $params = [] ) { $this->path = $path; $this->obResetFunc = $params['obResetFunc'] ?? [ __CLASS__, 'resetOutputBuffers' ]; $this->streamMimeFunc = $params['streamMimeFunc'] ?? [ __CLASS__, 'contentTypeFromPath' ]; $this->headerFunc = $params['headerFunc'] ?? 'header'; } /** * Stream a file to the browser, adding all the headings and fun stuff. * Headers sent include: Content-type, Content-Length, Last-Modified, * and Content-Disposition. * * @param array $headers Any additional headers to send if the file exists * @param bool $sendErrors Send error messages if errors occur (like 404) * @param array $optHeaders HTTP request header map (e.g. "range") (use lowercase keys) * @param int $flags Bitfield of STREAM_* constants * @return bool Success */ public function stream( $headers = [], $sendErrors = true, $optHeaders = [], $flags = 0 ) { $headless = ( $flags & self::STREAM_HEADLESS ); // Don't stream it out as text/html if there was a PHP error if ( $headers && headers_sent() ) { echo "Headers already sent, terminating.\n"; return false; } $headerFunc = $headless ? static function ( $header ) { // no-op } : [ $this, 'header' ]; AtEase::suppressWarnings(); $info = stat( $this->path ); AtEase::restoreWarnings(); if ( !is_array( $info ) ) { if ( $sendErrors ) { self::send404Message( $this->path, $flags ); } return false; } // Send Last-Modified HTTP header for client-side caching $mtimeCT = new ConvertibleTimestamp( $info['mtime'] ); $headerFunc( 'Last-Modified: ' . $mtimeCT->getTimestamp( TS_RFC2822 ) ); if ( ( $flags & self::STREAM_ALLOW_OB ) == 0 ) { call_user_func( $this->obResetFunc ); } $type = call_user_func( $this->streamMimeFunc, $this->path ); if ( $type && $type != 'unknown/unknown' ) { $headerFunc( "Content-type: $type" ); } else { // Send a content type which is not known to Internet Explorer, to // avoid triggering IE's content type detection. Sending a standard // unknown content type here essentially gives IE license to apply // whatever content type it likes. $headerFunc( 'Content-type: application/x-wiki' ); } // Don't send if client has up to date cache if ( isset( $optHeaders['if-modified-since'] ) ) { $modsince = preg_replace( '/;.*$/', '', $optHeaders['if-modified-since'] ); if ( $mtimeCT->getTimestamp( TS_UNIX ) <= strtotime( $modsince ) ) { ini_set( 'zlib.output_compression', 0 ); $headerFunc( 304 ); return true; // ok } } // Send additional headers foreach ( $headers as $header ) { $headerFunc( $header ); } if ( isset( $optHeaders['range'] ) ) { $range = self::parseRange( $optHeaders['range'], $info['size'] ); if ( is_array( $range ) ) { $headerFunc( 206 ); $headerFunc( 'Content-Length: ' . $range[2] ); $headerFunc( "Content-Range: bytes {$range[0]}-{$range[1]}/{$info['size']}" ); } elseif ( $range === 'invalid' ) { if ( $sendErrors ) { $headerFunc( 416 ); $headerFunc( 'Cache-Control: no-cache' ); $headerFunc( 'Content-Type: text/html; charset=utf-8' ); $headerFunc( 'Content-Range: bytes */' . $info['size'] ); } return false; } else { // unsupported Range request (e.g. multiple ranges) $range = null; $headerFunc( 'Content-Length: ' . $info['size'] ); } } else { $range = null; $headerFunc( 'Content-Length: ' . $info['size'] ); } if ( is_array( $range ) ) { $handle = fopen( $this->path, 'rb' ); if ( $handle ) { $ok = true; fseek( $handle, $range[0] ); $remaining = $range[2]; while ( $remaining > 0 && $ok ) { $bytes = min( $remaining, 8 * 1024 ); $data = fread( $handle, $bytes ); $remaining -= $bytes; $ok = ( $data !== false ); print $data; } } else { return false; } } else { return readfile( $this->path ) !== false; // faster } return true; } /** * Send out a standard 404 message for a file * * @param string $fname Full name and path of the file to stream * @param int $flags Bitfield of STREAM_* constants * @since 1.24 */ public static function send404Message( $fname, $flags = 0 ) { if ( ( $flags & self::STREAM_HEADLESS ) == 0 ) { HttpStatus::header( 404 ); header( 'Cache-Control: no-cache' ); header( 'Content-Type: text/html; charset=utf-8' ); } $encFile = htmlspecialchars( $fname ); $encScript = htmlspecialchars( $_SERVER['SCRIPT_NAME'] ); echo "<!DOCTYPE html><html><body> <h1>File not found</h1> <p>Although this PHP script ($encScript) exists, the file requested for output ($encFile) does not.</p> </body></html> "; } /** * Convert a Range header value to an absolute (start, end) range tuple * * @param string $range Range header value * @param int $size File size * @return array|string Returns error string on failure (start, end, length) * @since 1.24 */ public static function parseRange( $range, $size ) { $m = []; if ( preg_match( '#^bytes=(\d*)-(\d*)$#', $range, $m ) ) { [ , $start, $end ] = $m; if ( $start === '' && $end === '' ) { $absRange = [ 0, $size - 1 ]; } elseif ( $start === '' ) { $absRange = [ $size - (int)$end, $size - 1 ]; } elseif ( $end === '' ) { $absRange = [ (int)$start, $size - 1 ]; } else { $absRange = [ (int)$start, (int)$end ]; } if ( $absRange[0] >= 0 && $absRange[1] >= $absRange[0] ) { if ( $absRange[0] < $size ) { $absRange[1] = min( $absRange[1], $size - 1 ); // stop at EOF $absRange[2] = $absRange[1] - $absRange[0] + 1; return $absRange; } elseif ( $absRange[0] == 0 && $size == 0 ) { return 'unrecognized'; // the whole file should just be sent } } return 'invalid'; } return 'unrecognized'; } protected static function resetOutputBuffers() { while ( ob_get_status() ) { if ( !ob_end_clean() ) { // Could not remove output buffer handler; abort now // to avoid getting in some kind of infinite loop. break; } } } /** * Determine the file type of a file based on the path * * @param string $filename Storage path or file system path * @return null|string */ protected static function contentTypeFromPath( $filename ) { $ext = strrchr( $filename, '.' ); $ext = $ext ? strtolower( substr( $ext, 1 ) ) : ''; switch ( $ext ) { case 'gif': return 'image/gif'; case 'png': return 'image/png'; case 'jpg': case 'jpeg': return 'image/jpeg'; // T366422: Support webp here as well for consistency case 'webp': return 'image/webp'; } return 'unknown/unknown'; } private function header( $header ) { if ( is_int( $header ) ) { $header = HttpStatus::getHeader( $header ); } ( $this->headerFunc )( $header ); } } /** @deprecated class alias since 1.43 */ class_alias( HTTPFileStreamer::class, 'HTTPFileStreamer' ); PK ! �1s~� � * filebackend/fileop/FileStatePredicates.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file * @ingroup FileBackend */ namespace Wikimedia\FileBackend\FileOps; use Closure; /** * Helper class for tracking counterfactual file states when pre-checking file operation batches * * The file states are represented with (existence,size,sha1) triples. When combined with the * current state of files in the backend, this can be used to simulate how a batch of operations * would play out as a "dry run". This is used in FileBackend::doOperations() to bail out if any * failure can be predicted before modifying any data. This includes file operation batches where * the same file gets modified by different operations within the batch. * * @internal Only for use within FileBackend */ class FileStatePredicates { protected const EXISTS = 'exists'; protected const SIZE = 'size'; protected const SHA1 = 'sha1'; /** @var array<string,array> Map of (storage path => file state map) */ private $fileStateByPath; public function __construct() { $this->fileStateByPath = []; } /** * Predicate that a file exists at the path * * @param string $path Storage path * @param int|false|Closure $size File size or idempotent function yielding the size * @param string|Closure $sha1Base36 File hash, or, idempotent function yielding the hash */ public function assumeFileExists( string $path, $size, $sha1Base36 ) { $this->fileStateByPath[$path] = [ self::EXISTS => true, self::SIZE => $size, self::SHA1 => $sha1Base36 ]; } /** * Predicate that no file exists at the path * * @param string $path Storage path */ public function assumeFileDoesNotExist( string $path ) { $this->fileStateByPath[$path] = [ self::EXISTS => false, self::SIZE => false, self::SHA1 => false ]; } /** * Get the hypothetical existance a file given predicated and current state of files * * @param string $path Storage path * @param Closure $curExistenceFunc Function to compute the current existence for a given path * @return bool|null Whether the file exists; null on error */ public function resolveFileExistence( string $path, $curExistenceFunc ) { return self::resolveFileProperty( $path, self::EXISTS, $curExistenceFunc ); } /** * Get the hypothetical size of a file given predicated and current state of files * * @param string $path Storage path * @param Closure $curSizeFunc Function to compute the current size for a given path * @return int|false Bytes; false on error */ public function resolveFileSize( string $path, $curSizeFunc ) { return self::resolveFileProperty( $path, self::SIZE, $curSizeFunc ); } /** * Get the hypothetical SHA-1 hash of a file given predicated and current state of files * * @param string $path Storage path * @param Closure $curSha1Func Function to compute the current SHA-1 hash for a given path * @return string|false Base 36 SHA-1 hash; false on error */ public function resolveFileSha1Base36( string $path, $curSha1Func ) { return self::resolveFileProperty( $path, self::SHA1, $curSha1Func ); } /** * @param string $path Storage path * @param string $property One of (self::EXISTS, self::SIZE, self::SHA1) * @param Closure $curValueFunc Function to compute the current value for a given path * @return mixed */ private function resolveFileProperty( $path, $property, $curValueFunc ) { if ( isset( $this->fileStateByPath[$path] ) ) { // File is predicated to have a counterfactual state $value = $this->fileStateByPath[$path][$property]; if ( $value instanceof Closure ) { $value = $value(); $this->fileStateByPath[$path][$property] = $value; } } else { // File is not predicated to have a counterfactual state; use the current state $value = $curValueFunc( $path ); } return $value; } /** * @param string[] $paths List of storage paths * @return self Clone predicates limited to the given paths */ public function snapshot( array $paths ) { $snapshot = new self(); foreach ( $paths as $path ) { if ( isset( $this->fileStateByPath[$path] ) ) { $snapshot->fileStateByPath[$path] = $this->fileStateByPath[$path]; } } return $snapshot; } } /** @deprecated class alias since 1.43 */ class_alias( FileStatePredicates::class, 'FileStatePredicates' ); PK ! /���� � % filebackend/fileop/DescribeFileOp.phpnu �Iw�� <?php /** * Helper class for representing operations with transaction support. * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file * @ingroup FileBackend */ namespace Wikimedia\FileBackend\FileOps; use StatusValue; use Wikimedia\FileBackend\FileBackend; /** * Change metadata for a file at the given storage path in the backend. * Parameters for this operation are outlined in FileBackend::doOperations(). */ class DescribeFileOp extends FileOp { protected function allowedParams() { return [ [ 'src' ], [ 'headers' ], [ 'src' ] ]; } protected function doPrecheck( FileStatePredicates $opPredicates, FileStatePredicates $batchPredicates ) { $status = StatusValue::newGood(); // Check source file existence $srcExists = $this->resolveFileExistence( $this->params['src'], $opPredicates ); if ( $srcExists === false ) { $status->fatal( 'backend-fail-notexists', $this->params['src'] ); return $status; } elseif ( $srcExists === FileBackend::EXISTENCE_ERROR ) { $status->fatal( 'backend-fail-stat', $this->params['src'] ); return $status; } // Update file existence predicates since the operation is expected to be allowed to run $srcSize = function () use ( $opPredicates ) { static $size = null; $size ??= $this->resolveFileSize( $this->params['src'], $opPredicates ); return $size; }; $srcSha1 = function () use ( $opPredicates ) { static $sha1 = null; $sha1 ??= $this->resolveFileSha1Base36( $this->params['src'], $opPredicates ); return $sha1; }; $batchPredicates->assumeFileExists( $this->params['src'], $srcSize, $srcSha1 ); return $status; // safe to call attempt() } protected function doAttempt() { // Update the source file's metadata return $this->backend->describeInternal( $this->setFlags( $this->params ) ); } public function storagePathsChanged() { return [ $this->params['src'] ]; } } /** @deprecated class alias since 1.43 */ class_alias( DescribeFileOp::class, 'DescribeFileOp' ); PK ! �2�% % # filebackend/fileop/DeleteFileOp.phpnu �Iw�� <?php /** * Helper class for representing operations with transaction support. * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file * @ingroup FileBackend */ namespace Wikimedia\FileBackend\FileOps; use StatusValue; use Wikimedia\FileBackend\FileBackend; /** * Delete a file at the given storage path from the backend. * Parameters for this operation are outlined in FileBackend::doOperations(). */ class DeleteFileOp extends FileOp { protected function allowedParams() { return [ [ 'src' ], [ 'ignoreMissingSource' ], [ 'src' ] ]; } protected function doPrecheck( FileStatePredicates $opPredicates, FileStatePredicates $batchPredicates ) { $status = StatusValue::newGood(); // Check source file existence $srcExists = $this->resolveFileExistence( $this->params['src'], $opPredicates ); if ( $srcExists === false ) { if ( $this->getParam( 'ignoreMissingSource' ) ) { $this->noOp = true; // no-op // Update file existence predicates (cache 404s) $batchPredicates->assumeFileDoesNotExist( $this->params['src'] ); return $status; // nothing to do } else { $status->fatal( 'backend-fail-notexists', $this->params['src'] ); return $status; } } elseif ( $srcExists === FileBackend::EXISTENCE_ERROR ) { $status->fatal( 'backend-fail-stat', $this->params['src'] ); return $status; } // Update file existence predicates since the operation is expected to be allowed to run $batchPredicates->assumeFileDoesNotExist( $this->params['src'] ); return $status; // safe to call attempt() } protected function doAttempt() { // Delete the source file return $this->backend->deleteInternal( $this->setFlags( $this->params ) ); } public function storagePathsChanged() { return [ $this->params['src'] ]; } } /** @deprecated class alias since 1.43 */ class_alias( DeleteFileOp::class, 'DeleteFileOp' ); PK ! �Ki�� � ! filebackend/fileop/MoveFileOp.phpnu �Iw�� <?php /** * Helper class for representing operations with transaction support. * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file * @ingroup FileBackend */ namespace Wikimedia\FileBackend\FileOps; use StatusValue; use Wikimedia\FileBackend\FileBackend; /** * Move a file from one storage path to another in the backend. * Parameters for this operation are outlined in FileBackend::doOperations(). */ class MoveFileOp extends FileOp { protected function allowedParams() { return [ [ 'src', 'dst' ], [ 'overwrite', 'overwriteSame', 'ignoreMissingSource', 'headers' ], [ 'src', 'dst' ] ]; } protected function doPrecheck( FileStatePredicates $opPredicates, FileStatePredicates $batchPredicates ) { $status = StatusValue::newGood(); // Check source file existence $srcExists = $this->resolveFileExistence( $this->params['src'], $opPredicates ); if ( $srcExists === false ) { if ( $this->getParam( 'ignoreMissingSource' ) ) { $this->noOp = true; // no-op // Update file existence predicates (cache 404s) $batchPredicates->assumeFileDoesNotExist( $this->params['src'] ); return $status; // nothing to do } else { $status->fatal( 'backend-fail-notexists', $this->params['src'] ); return $status; } } elseif ( $srcExists === FileBackend::EXISTENCE_ERROR ) { $status->fatal( 'backend-fail-stat', $this->params['src'] ); return $status; } // Check if an incompatible destination file exists $srcSize = function () use ( $opPredicates ) { static $size = null; $size ??= $this->resolveFileSize( $this->params['src'], $opPredicates ); return $size; }; $srcSha1 = function () use ( $opPredicates ) { static $sha1 = null; $sha1 ??= $this->resolveFileSha1Base36( $this->params['src'], $opPredicates ); return $sha1; }; $status->merge( $this->precheckDestExistence( $opPredicates, $srcSize, $srcSha1 ) ); $this->params['dstExists'] = $this->destExists; // see FileBackendStore::setFileCache() // Update file existence predicates if the operation is expected to be allowed to run if ( $status->isOK() ) { $batchPredicates->assumeFileExists( $this->params['dst'], $srcSize, $srcSha1 ); if ( $this->params['src'] !== $this->params['dst'] ) { $batchPredicates->assumeFileDoesNotExist( $this->params['src'] ); } } return $status; // safe to call attempt() } protected function doAttempt() { if ( $this->overwriteSameCase ) { if ( $this->params['src'] === $this->params['dst'] ) { // Do nothing to the destination (which is also the source) $status = StatusValue::newGood(); } else { // Just delete the source as the destination file needs no changes $status = $this->backend->deleteInternal( $this->setFlags( [ 'src' => $this->params['src'] ] ) ); } } elseif ( $this->params['src'] === $this->params['dst'] ) { // Just update the destination file headers $headers = $this->getParam( 'headers' ) ?: []; $status = $this->backend->describeInternal( $this->setFlags( [ 'src' => $this->params['dst'], 'headers' => $headers ] ) ); } else { // Move the file to the destination $status = $this->backend->moveInternal( $this->setFlags( $this->params ) ); } return $status; } public function storagePathsRead() { return [ $this->params['src'] ]; } public function storagePathsChanged() { return [ $this->params['src'], $this->params['dst'] ]; } } /** @deprecated class alias since 1.43 */ class_alias( MoveFileOp::class, 'MoveFileOp' ); PK ! �� # filebackend/fileop/CreateFileOp.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file * @ingroup FileBackend */ namespace Wikimedia\FileBackend\FileOps; use StatusValue; /** * Create a file in the backend with the given content. * Parameters for this operation are outlined in FileBackend::doOperations(). */ class CreateFileOp extends FileOp { protected function allowedParams() { return [ [ 'content', 'dst' ], [ 'overwrite', 'overwriteSame', 'headers' ], [ 'dst' ] ]; } protected function doPrecheck( FileStatePredicates $opPredicates, FileStatePredicates $batchPredicates ) { $status = StatusValue::newGood(); // Check if the source data is too big $sourceSize = $this->getSourceSize(); $maxFileSize = $this->backend->maxFileSizeInternal(); if ( $sourceSize > $maxFileSize ) { $status->fatal( 'backend-fail-maxsize', $this->params['dst'], $maxFileSize ); return $status; } // Check if an incompatible destination file exists $sourceSha1 = $this->getSourceSha1Base36(); $status->merge( $this->precheckDestExistence( $opPredicates, $sourceSize, $sourceSha1 ) ); $this->params['dstExists'] = $this->destExists; // see FileBackendStore::setFileCache() // Update file existence predicates if the operation is expected to be allowed to run if ( $status->isOK() ) { $batchPredicates->assumeFileExists( $this->params['dst'], $sourceSize, $sourceSha1 ); } return $status; // safe to call attempt() } protected function doAttempt() { if ( $this->overwriteSameCase ) { $status = StatusValue::newGood(); // nothing to do } else { // Create the file at the destination $status = $this->backend->createInternal( $this->setFlags( $this->params ) ); } return $status; } protected function getSourceSize() { return strlen( $this->params['content'] ); } protected function getSourceSha1Base36() { return \Wikimedia\base_convert( sha1( $this->params['content'] ), 16, 36, 31 ); } public function storagePathsChanged() { return [ $this->params['dst'] ]; } } /** @deprecated class alias since 1.43 */ class_alias( CreateFileOp::class, 'CreateFileOp' ); PK ! �^�� � ! filebackend/fileop/CopyFileOp.phpnu �Iw�� <?php /** * Helper class for representing operations with transaction support. * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file * @ingroup FileBackend */ namespace Wikimedia\FileBackend\FileOps; use StatusValue; use Wikimedia\FileBackend\FileBackend; /** * Copy a file from one storage path to another in the backend. * Parameters for this operation are outlined in FileBackend::doOperations(). */ class CopyFileOp extends FileOp { protected function allowedParams() { return [ [ 'src', 'dst' ], [ 'overwrite', 'overwriteSame', 'ignoreMissingSource', 'headers' ], [ 'src', 'dst' ] ]; } protected function doPrecheck( FileStatePredicates $opPredicates, FileStatePredicates $batchPredicates ) { $status = StatusValue::newGood(); // Check source file existence $srcExists = $this->resolveFileExistence( $this->params['src'], $opPredicates ); if ( $srcExists === false ) { if ( $this->getParam( 'ignoreMissingSource' ) ) { $this->noOp = true; // no-op // Update file existence predicates (cache 404s) $batchPredicates->assumeFileDoesNotExist( $this->params['src'] ); return $status; // nothing to do } else { $status->fatal( 'backend-fail-notexists', $this->params['src'] ); return $status; } } elseif ( $srcExists === FileBackend::EXISTENCE_ERROR ) { $status->fatal( 'backend-fail-stat', $this->params['src'] ); return $status; } // Check if an incompatible destination file exists $srcSize = function () use ( $opPredicates ) { static $size = null; $size ??= $this->resolveFileSize( $this->params['src'], $opPredicates ); return $size; }; $srcSha1 = function () use ( $opPredicates ) { static $sha1 = null; $sha1 ??= $this->resolveFileSha1Base36( $this->params['src'], $opPredicates ); return $sha1; }; $status->merge( $this->precheckDestExistence( $opPredicates, $srcSize, $srcSha1 ) ); $this->params['dstExists'] = $this->destExists; // see FileBackendStore::setFileCache() // Update file existence predicates if the operation is expected to be allowed to run if ( $status->isOK() ) { $batchPredicates->assumeFileExists( $this->params['dst'], $srcSize, $srcSha1 ); } return $status; // safe to call attempt() } protected function doAttempt() { if ( $this->overwriteSameCase ) { $status = StatusValue::newGood(); // nothing to do } elseif ( $this->params['src'] === $this->params['dst'] ) { // Just update the destination file headers $headers = $this->getParam( 'headers' ) ?: []; $status = $this->backend->describeInternal( $this->setFlags( [ 'src' => $this->params['dst'], 'headers' => $headers ] ) ); } else { // Copy the file to the destination $status = $this->backend->copyInternal( $this->setFlags( $this->params ) ); } return $status; } public function storagePathsRead() { return [ $this->params['src'] ]; } public function storagePathsChanged() { return [ $this->params['dst'] ]; } } /** @deprecated class alias since 1.43 */ class_alias( CopyFileOp::class, 'CopyFileOp' ); PK ! V�_ _ ! filebackend/fileop/NullFileOp.phpnu �Iw�� <?php /** * Helper class for representing operations with transaction support. * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file * @ingroup FileBackend */ namespace Wikimedia\FileBackend\FileOps; /** * Placeholder operation that has no params and does nothing */ class NullFileOp extends FileOp { } /** @deprecated class alias since 1.43 */ class_alias( NullFileOp::class, 'NullFileOp' ); PK ! O�ez8 z8 filebackend/fileop/FileOp.phpnu �Iw�� <?php /** * Helper class for representing operations with transaction support. * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file * @ingroup FileBackend */ namespace Wikimedia\FileBackend\FileOps; use Closure; use Exception; use InvalidArgumentException; use MediaWiki\Json\FormatJson; use Psr\Log\LoggerInterface; use StatusValue; use Wikimedia\FileBackend\FileBackend; use Wikimedia\FileBackend\FileBackendStore; use Wikimedia\RequestTimeout\TimeoutException; /** * FileBackend helper class for representing operations. * Do not use this class from places outside FileBackend. * * Methods called from FileOpBatch::attempt() should avoid throwing * exceptions at all costs. FileOp objects should be lightweight in order * to support large arrays in memory and serialization. * * @ingroup FileBackend * @since 1.19 */ abstract class FileOp { /** @var FileBackendStore */ protected $backend; /** @var LoggerInterface */ protected $logger; /** @var array */ protected $params = []; /** @var int Stage in the operation life-cycle */ protected $state = self::STATE_NEW; /** @var bool Whether the operation pre-check or attempt stage failed */ protected $failed = false; /** @var bool Whether the operation is part of a concurrent sub-batch of operation */ protected $async = false; /** @var bool Whether the operation pre-check stage marked the attempt stage as a no-op */ protected $noOp = false; /** @var bool|null */ protected $overwriteSameCase; /** @var bool|null */ protected $destExists; /** Operation has not yet been pre-checked nor run */ private const STATE_NEW = 1; /** Operation has been pre-checked but not yet attempted */ private const STATE_CHECKED = 2; /** Operation has been attempted */ private const STATE_ATTEMPTED = 3; /** * Build a new batch file operation transaction * * @param FileBackendStore $backend * @param array $params * @param LoggerInterface $logger PSR logger instance */ final public function __construct( FileBackendStore $backend, array $params, LoggerInterface $logger ) { $this->backend = $backend; $this->logger = $logger; [ $required, $optional, $paths ] = $this->allowedParams(); foreach ( $required as $name ) { if ( isset( $params[$name] ) ) { $this->params[$name] = $params[$name]; } else { throw new InvalidArgumentException( "File operation missing parameter '$name'." ); } } foreach ( $optional as $name ) { if ( isset( $params[$name] ) ) { $this->params[$name] = $params[$name]; } } foreach ( $paths as $name ) { if ( isset( $this->params[$name] ) ) { // Normalize paths so the paths to the same file have the same string $this->params[$name] = self::normalizeIfValidStoragePath( $this->params[$name] ); } } } /** * Normalize a string if it is a valid storage path * * @param string $path * @return string */ protected static function normalizeIfValidStoragePath( $path ) { if ( FileBackend::isStoragePath( $path ) ) { $res = FileBackend::normalizeStoragePath( $path ); return $res ?? $path; } return $path; } /** * Get the value of the parameter with the given name * * @param string $name * @return mixed Returns null if the parameter is not set */ final public function getParam( $name ) { return $this->params[$name] ?? null; } /** * Check if this operation failed precheck() or attempt() * * @return bool */ final public function failed() { return $this->failed; } /** * Get a new empty dependency tracking array for paths read/written to * * @return array */ final public static function newDependencies() { return [ 'read' => [], 'write' => [] ]; } /** * Update a dependency tracking array to account for this operation * * @param array $deps Prior path reads/writes; format of FileOp::newDependencies() * @return array */ final public function applyDependencies( array $deps ) { $deps['read'] += array_fill_keys( $this->storagePathsRead(), 1 ); $deps['write'] += array_fill_keys( $this->storagePathsChanged(), 1 ); return $deps; } /** * Check if this operation changes files listed in $paths * * @param array $deps Prior path reads/writes; format of FileOp::newDependencies() * @return bool */ final public function dependsOn( array $deps ) { foreach ( $this->storagePathsChanged() as $path ) { if ( isset( $deps['read'][$path] ) || isset( $deps['write'][$path] ) ) { return true; // "output" or "anti" dependency } } foreach ( $this->storagePathsRead() as $path ) { if ( isset( $deps['write'][$path] ) ) { return true; // "flow" dependency } } return false; } /** * Do a dry-run precondition check of the operation in the context of op batch * * Updates the batch predicates for all paths this op can change if an OK status is returned * * @param FileStatePredicates $predicates Counterfactual file states for the op batch * @return StatusValue */ final public function precheck( FileStatePredicates $predicates ) { if ( $this->state !== self::STATE_NEW ) { return StatusValue::newFatal( 'fileop-fail-state', self::STATE_NEW, $this->state ); } $this->state = self::STATE_CHECKED; $status = StatusValue::newGood(); foreach ( $this->storagePathsReadOrChanged() as $path ) { if ( !$this->backend->isPathUsableInternal( $path ) ) { $status->fatal( 'backend-fail-usable', $path ); } } if ( !$status->isOK() ) { return $status; } $opPredicates = $predicates->snapshot( $this->storagePathsReadOrChanged() ); $status = $this->doPrecheck( $opPredicates, $predicates ); if ( !$status->isOK() ) { $this->failed = true; } return $status; } /** * Do a dry-run precondition check of the operation in the context of op batch * * Updates the batch predicates for all paths this op can change if an OK status is returned * * @param FileStatePredicates $opPredicates Counterfactual file states for op paths at op start * @param FileStatePredicates $batchPredicates Counterfactual file states for the op batch * @return StatusValue */ protected function doPrecheck( FileStatePredicates $opPredicates, FileStatePredicates $batchPredicates ) { return StatusValue::newGood(); } /** * Attempt the operation * * @return StatusValue */ final public function attempt() { if ( $this->state !== self::STATE_CHECKED ) { return StatusValue::newFatal( 'fileop-fail-state', self::STATE_CHECKED, $this->state ); } elseif ( $this->failed ) { // failed precheck return StatusValue::newFatal( 'fileop-fail-attempt-precheck' ); } $this->state = self::STATE_ATTEMPTED; if ( $this->noOp ) { $status = StatusValue::newGood(); // no-op } else { $status = $this->doAttempt(); if ( !$status->isOK() ) { $this->failed = true; $this->logFailure( 'attempt' ); } } return $status; } /** * @return StatusValue */ protected function doAttempt() { return StatusValue::newGood(); } /** * Attempt the operation in the background * * @return StatusValue */ final public function attemptAsync() { $this->async = true; $result = $this->attempt(); $this->async = false; return $result; } /** * Attempt the operation without regards to prechecks * * @return StatusValue */ final public function attemptQuick() { $this->state = self::STATE_CHECKED; // bypassed return $this->attempt(); } /** * Attempt the operation in the background without regards to prechecks * * @return StatusValue */ final public function attemptAsyncQuick() { $this->state = self::STATE_CHECKED; // bypassed return $this->attemptAsync(); } /** * Get the file operation parameters * * @return array (required params list, optional params list, list of params that are paths) */ protected function allowedParams() { return [ [], [], [] ]; } /** * Adjust params to FileBackendStore internal file calls * * @param array $params * @return array (required params list, optional params list) */ protected function setFlags( array $params ) { return [ 'async' => $this->async ] + $params; } /** * Get a list of storage paths read from for this operation * * @return array */ public function storagePathsRead() { return []; } /** * Get a list of storage paths written to for this operation * * @return array */ public function storagePathsChanged() { return []; } /** * Get a list of storage paths read from or written to for this operation * * @return array */ final public function storagePathsReadOrChanged() { return array_values( array_unique( array_merge( $this->storagePathsRead(), $this->storagePathsChanged() ) ) ); } /** * Check for errors with regards to the destination file already existing * * Also set the destExists and overwriteSameCase member variables. * A bad StatusValue will be returned if there is no chance it can be overwritten. * * @param FileStatePredicates $opPredicates Counterfactual storage path states for this op * @param int|false|Closure $sourceSize Source size or idempotent function yielding the size * @param string|Closure $sourceSha1 Source hash, or, idempotent function yielding the hash * @return StatusValue */ protected function precheckDestExistence( FileStatePredicates $opPredicates, $sourceSize, $sourceSha1 ) { $status = StatusValue::newGood(); // Record the existence of destination file $this->destExists = $this->resolveFileExistence( $this->params['dst'], $opPredicates ); // Check if an incompatible file exists at the destination $this->overwriteSameCase = false; if ( $this->destExists ) { if ( $this->getParam( 'overwrite' ) ) { return $status; // OK, no conflict } elseif ( $this->getParam( 'overwriteSame' ) ) { // Operation does nothing other than return an OK or bad status $sourceSize = ( $sourceSize instanceof Closure ) ? $sourceSize() : $sourceSize; $sourceSha1 = ( $sourceSha1 instanceof Closure ) ? $sourceSha1() : $sourceSha1; $dstSha1 = $this->resolveFileSha1Base36( $this->params['dst'], $opPredicates ); $dstSize = $this->resolveFileSize( $this->params['dst'], $opPredicates ); // Check if hashes are valid and match each other... if ( !strlen( $sourceSha1 ) || !strlen( $dstSha1 ) ) { $status->fatal( 'backend-fail-hashes' ); } elseif ( !is_int( $sourceSize ) || !is_int( $dstSize ) ) { $status->fatal( 'backend-fail-sizes' ); } elseif ( $sourceSha1 !== $dstSha1 || $sourceSize !== $dstSize ) { // Give an error if the files are not identical $status->fatal( 'backend-fail-notsame', $this->params['dst'] ); } else { $this->overwriteSameCase = true; // OK } } else { $status->fatal( 'backend-fail-alreadyexists', $this->params['dst'] ); } } elseif ( $this->destExists === FileBackend::EXISTENCE_ERROR ) { $status->fatal( 'backend-fail-stat', $this->params['dst'] ); } return $status; } /** * Check if a file will exist in storage when this operation is attempted * * Ideally, the file stat entry should already be preloaded via preloadFileStat(). * Otherwise, this will query the backend. * * @param string $source Storage path * @param FileStatePredicates $opPredicates Counterfactual storage path states for this op * @return bool|null Whether the file will exist or null on error */ final protected function resolveFileExistence( $source, FileStatePredicates $opPredicates ) { return $opPredicates->resolveFileExistence( $source, function ( $path ) { return $this->backend->fileExists( [ 'src' => $path, 'latest' => true ] ); } ); } /** * Get the size a file in storage will have when this operation is attempted * * Ideally, file the stat entry should already be preloaded via preloadFileStat() and * the backend tracks hashes as extended attributes. Otherwise, this will query the backend. * Get the size of a file in storage when this operation is attempted * * @param string $source Storage path * @param FileStatePredicates $opPredicates Counterfactual storage path states for this op * @return int|false False on failure */ final protected function resolveFileSize( $source, FileStatePredicates $opPredicates ) { return $opPredicates->resolveFileSize( $source, function ( $path ) { return $this->backend->getFileSize( [ 'src' => $path, 'latest' => true ] ); } ); } /** * Get the SHA-1 of a file in storage when this operation is attempted * * @param string $source Storage path * @param FileStatePredicates $opPredicates Counterfactual storage path states for this op * @return string|false The SHA-1 hash the file will have or false if non-existent or on error */ final protected function resolveFileSha1Base36( $source, FileStatePredicates $opPredicates ) { return $opPredicates->resolveFileSha1Base36( $source, function ( $path ) { return $this->backend->getFileSha1Base36( [ 'src' => $path, 'latest' => true ] ); } ); } /** * Get the backend this operation is for * * @return FileBackendStore */ public function getBackend() { return $this->backend; } /** * Log a file operation failure and preserve any temp files * * @param string $action */ final public function logFailure( $action ) { $params = $this->params; $params['failedAction'] = $action; try { $this->logger->error( static::class . " failed: " . FormatJson::encode( $params ) ); } catch ( TimeoutException $e ) { throw $e; } catch ( Exception $e ) { // bad config? debug log error? } } } /** @deprecated class alias since 1.43 */ class_alias( FileOp::class, 'FileOp' ); PK ! �Z�W W " filebackend/fileop/StoreFileOp.phpnu �Iw�� <?php /** * Helper class for representing operations with transaction support. * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file * @ingroup FileBackend */ namespace Wikimedia\FileBackend\FileOps; use StatusValue; use Wikimedia\AtEase\AtEase; /** * Store a file into the backend from a file on the file system. * Parameters for this operation are outlined in FileBackend::doOperations(). */ class StoreFileOp extends FileOp { protected function allowedParams() { return [ [ 'src', 'dst' ], [ 'overwrite', 'overwriteSame', 'headers' ], [ 'src', 'dst' ] ]; } protected function doPrecheck( FileStatePredicates $opPredicates, FileStatePredicates $batchPredicates ) { $status = StatusValue::newGood(); // Check if the source file exists in the file system if ( !is_file( $this->params['src'] ) ) { $status->fatal( 'backend-fail-notexists', $this->params['src'] ); return $status; } // Check if the source file is too big $sourceSize = $this->getSourceSize(); $maxFileSize = $this->backend->maxFileSizeInternal(); if ( $sourceSize > $maxFileSize ) { $status->fatal( 'backend-fail-maxsize', $this->params['dst'], $maxFileSize ); return $status; } // Check if an incompatible destination file exists $sourceSha1 = function () { static $sha1 = null; $sha1 ??= $this->getSourceSha1Base36(); return $sha1; }; $status->merge( $this->precheckDestExistence( $opPredicates, $sourceSize, $sourceSha1 ) ); $this->params['dstExists'] = $this->destExists; // see FileBackendStore::setFileCache() // Update file existence predicates if the operation is expected to be allowed to run if ( $status->isOK() ) { $batchPredicates->assumeFileExists( $this->params['dst'], $sourceSize, $sourceSha1 ); } return $status; // safe to call attempt() } protected function doAttempt() { if ( $this->overwriteSameCase ) { $status = StatusValue::newGood(); // nothing to do } else { // Store the file at the destination $status = $this->backend->storeInternal( $this->setFlags( $this->params ) ); } return $status; } protected function getSourceSize() { AtEase::suppressWarnings(); $size = filesize( $this->params['src'] ); AtEase::restoreWarnings(); return $size; } protected function getSourceSha1Base36() { AtEase::suppressWarnings(); $hash = sha1_file( $this->params['src'] ); AtEase::restoreWarnings(); if ( $hash !== false ) { $hash = \Wikimedia\base_convert( $hash, 16, 36, 31 ); } return $hash; } public function storagePathsChanged() { return [ $this->params['dst'] ]; } } /** @deprecated class alias since 1.43 */ class_alias( StoreFileOp::class, 'StoreFileOp' ); PK ! i�cc c filebackend/FileBackendError.phpnu �Iw�� <?php namespace Wikimedia\FileBackend; use Exception; /** * File backend exception for checked exceptions (e.g. I/O errors) * * @newable * @stable to extend * @ingroup FileBackend * @since 1.22 */ class FileBackendError extends Exception { } /** @deprecated class alias since 1.43 */ class_alias( FileBackendError::class, 'FileBackendError' ); PK ! Δ�_� � filebackend/FileOpBatch.phpnu �Iw�� <?php /** * Helper class for representing batch file operations. * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file * @ingroup FileBackend */ namespace Wikimedia\FileBackend; use StatusValue; use Wikimedia\FileBackend\FileOpHandle\FileBackendStoreOpHandle; use Wikimedia\FileBackend\FileOps\FileOp; use Wikimedia\FileBackend\FileOps\FileStatePredicates; /** * Helper class for representing batch file operations. * Do not use this class from places outside FileBackend. * * Methods should avoid throwing exceptions at all costs. * * @ingroup FileBackend * @since 1.20 */ class FileOpBatch { /* Timeout related parameters */ private const MAX_BATCH_SIZE = 1000; // integer /** * Attempt to perform a series of file operations. * Callers are responsible for handling file locking. * * $opts is an array of options, including: * - force : Errors that would normally cause a rollback do not. * The remaining operations are still attempted if any fail. * - concurrency : Try to do this many operations in parallel when possible. * * The resulting StatusValue will be "OK" unless: * - a) unexpected operation errors occurred (network partitions, disk full...) * - b) predicted operation errors occurred and 'force' was not set * * @param FileOp[] $performOps List of FileOp operations * @param array $opts Batch operation options * @return StatusValue */ public static function attempt( array $performOps, array $opts ) { $status = StatusValue::newGood(); $n = count( $performOps ); if ( $n > self::MAX_BATCH_SIZE ) { $status->fatal( 'backend-fail-batchsize', $n, self::MAX_BATCH_SIZE ); return $status; } $ignoreErrors = !empty( $opts['force'] ); $maxConcurrency = $opts['concurrency'] ?? 1; $predicates = new FileStatePredicates(); // account for previous ops in prechecks $curBatch = []; // concurrent FileOp sub-batch accumulation $curBatchDeps = FileOp::newDependencies(); // paths used in FileOp sub-batch $pPerformOps = []; // ordered list of concurrent FileOp sub-batches $lastBackend = null; // last op backend name // Do pre-checks for each operation; abort on failure... foreach ( $performOps as $index => $fileOp ) { $backendName = $fileOp->getBackend()->getName(); // Decide if this op can be done concurrently within this sub-batch // or if a new concurrent sub-batch must be started after this one... if ( $fileOp->dependsOn( $curBatchDeps ) || count( $curBatch ) >= $maxConcurrency || ( $backendName !== $lastBackend && count( $curBatch ) ) ) { $pPerformOps[] = $curBatch; // push this batch $curBatch = []; // start a new sub-batch $curBatchDeps = FileOp::newDependencies(); } $lastBackend = $backendName; $curBatch[$index] = $fileOp; // keep index // Update list of affected paths in this batch $curBatchDeps = $fileOp->applyDependencies( $curBatchDeps ); // Simulate performing the operation... $subStatus = $fileOp->precheck( $predicates ); // updates $predicates $status->merge( $subStatus ); if ( !$subStatus->isOK() ) { // operation failed? $status->success[$index] = false; ++$status->failCount; if ( !$ignoreErrors ) { return $status; // abort } } } // Push the last sub-batch if ( count( $curBatch ) ) { $pPerformOps[] = $curBatch; } if ( $ignoreErrors ) { // treat precheck() fatals as mere warnings $status->setResult( true, $status->value ); } // Attempt each operation (in parallel if allowed and possible)... self::runParallelBatches( $pPerformOps, $status ); return $status; } /** * Attempt a list of file operations sub-batches in series. * * The operations *in* each sub-batch will be done in parallel. * The caller is responsible for making sure the operations * within any given sub-batch do not depend on each other. * This will abort remaining ops on failure. * * @param FileOp[][] $pPerformOps Batches of file ops (batches use original indexes) * @param StatusValue $status */ protected static function runParallelBatches( array $pPerformOps, StatusValue $status ) { $aborted = false; // set to true on unexpected errors foreach ( $pPerformOps as $performOpsBatch ) { if ( $aborted ) { // check batch op abort flag... // We can't continue (even with $ignoreErrors) as $predicates is wrong. // Log the remaining ops as failed for recovery... foreach ( $performOpsBatch as $i => $fileOp ) { $status->success[$i] = false; ++$status->failCount; $fileOp->logFailure( 'attempt_aborted' ); } continue; } /** @var StatusValue[] $statuses */ $statuses = []; $opHandles = []; // Get the backend; all sub-batch ops belong to a single backend /** @var FileBackendStore $backend */ $backend = reset( $performOpsBatch )->getBackend(); // Get the operation handles or actually do it if there is just one. // If attemptAsync() returns a StatusValue, it was either due to an error // or the backend does not support async ops and did it synchronously. foreach ( $performOpsBatch as $i => $fileOp ) { if ( !isset( $status->success[$i] ) ) { // didn't already fail in precheck() // Parallel ops may be disabled in config due to missing dependencies, // (e.g. needing popen()). When they are, $performOpsBatch has size 1. $subStatus = ( count( $performOpsBatch ) > 1 ) ? $fileOp->attemptAsync() : $fileOp->attempt(); if ( $subStatus->value instanceof FileBackendStoreOpHandle ) { $opHandles[$i] = $subStatus->value; // deferred } else { $statuses[$i] = $subStatus; // done already } } } // Try to do all the operations concurrently... $statuses += $backend->executeOpHandlesInternal( $opHandles ); // Marshall and merge all the responses (blocking)... foreach ( $performOpsBatch as $i => $fileOp ) { if ( !isset( $status->success[$i] ) ) { // didn't already fail in precheck() $subStatus = $statuses[$i]; $status->merge( $subStatus ); if ( $subStatus->isOK() ) { $status->success[$i] = true; ++$status->successCount; } else { $status->success[$i] = false; ++$status->failCount; $aborted = true; // set abort flag; we can't continue } } } } } } /** @deprecated class alias since 1.43 */ class_alias( FileOpBatch::class, 'FileOpBatch' ); PK ! J4~ 5 filebackend/fileiteration/SwiftFileBackendDirList.phpnu �Iw�� <?php /** * OpenStack Swift based file backend. * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file * @ingroup FileBackend * @author Russ Nelson */ namespace Wikimedia\FileBackend\FileIteration; /** * Iterator for listing directories */ class SwiftFileBackendDirList extends SwiftFileBackendList { /** * @see Iterator::current() * @return string|bool String (relative path) or false */ #[\ReturnTypeWillChange] public function current() { return substr( current( $this->iterableBuffer ), $this->suffixStart, -1 ); } protected function pageFromList( $container, $dir, &$after, $limit, array $params ) { return $this->backend->getDirListPageInternal( $container, $dir, $after, $limit, $params ); } } /** @deprecated class alias since 1.43 */ class_alias( SwiftFileBackendDirList::class, 'SwiftFileBackendDirList' ); PK ! �*&�_ _ ? filebackend/fileiteration/FileBackendStoreShardListIterator.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file * @ingroup FileBackend */ namespace Wikimedia\FileBackend\FileIteration; use AppendIterator; use FilterIterator; use Iterator; use Wikimedia\FileBackend\FileBackendStore; /** * FileBackendStore helper function to handle listings that span container shards. * Do not use this class from places outside of FileBackendStore. * * @ingroup FileBackend */ abstract class FileBackendStoreShardListIterator extends FilterIterator { /** @var FileBackendStore */ protected $backend; /** @var array */ protected $params; /** @var string Full container name */ protected $container; /** @var string Resolved relative path */ protected $directory; /** @var array */ protected $multiShardPaths = []; // (rel path => 1) /** * @param FileBackendStore $backend * @param string $container Full storage container name * @param string $dir Storage directory relative to container * @param array $suffixes List of container shard suffixes * @param array $params */ public function __construct( FileBackendStore $backend, $container, $dir, array $suffixes, array $params ) { $this->backend = $backend; $this->container = $container; $this->directory = $dir; $this->params = $params; $iter = new AppendIterator(); foreach ( $suffixes as $suffix ) { $iter->append( $this->listFromShard( $this->container . $suffix ) ); } parent::__construct( $iter ); } public function accept(): bool { $inner = $this->getInnerIterator(); '@phan-var AppendIterator $inner'; $rel = $inner->current(); // path relative to given directory $path = $this->params['dir'] . "/{$rel}"; // full storage path if ( $this->backend->isSingleShardPathInternal( $path ) ) { return true; // path is only on one shard; no issue with duplicates } elseif ( isset( $this->multiShardPaths[$rel] ) ) { // Don't keep listing paths that are on multiple shards return false; } else { $this->multiShardPaths[$rel] = 1; return true; } } public function rewind(): void { parent::rewind(); $this->multiShardPaths = []; } /** * Get the list for a given container shard * * @param string $container Resolved container name * @return Iterator */ abstract protected function listFromShard( $container ); } /** @deprecated class alias since 1.43 */ class_alias( FileBackendStoreShardListIterator::class, 'FileBackendStoreShardListIterator' ); PK ! _C�,� � 3 filebackend/fileiteration/FSFileBackendFileList.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file * @ingroup FileBackend */ namespace Wikimedia\FileBackend\FileIteration; class FSFileBackendFileList extends FSFileBackendList { protected function filterViaNext() { while ( $this->iter->valid() ) { if ( !$this->iter->current()->isFile() ) { $this->iter->next(); // skip non-files and dot files } else { break; } } } } /** @deprecated class alias since 1.43 */ class_alias( FSFileBackendFileList::class, 'FSFileBackendFileList' ); PK ! �ɕ�� � 6 filebackend/fileiteration/SwiftFileBackendFileList.phpnu �Iw�� <?php /** * OpenStack Swift based file backend. * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file * @ingroup FileBackend * @author Russ Nelson */ namespace Wikimedia\FileBackend\FileIteration; /** * Iterator for listing regular files */ class SwiftFileBackendFileList extends SwiftFileBackendList { /** * @see Iterator::current() * @return string|bool String (relative path) or false */ #[\ReturnTypeWillChange] public function current() { [ $path, $stat ] = current( $this->iterableBuffer ); $relPath = substr( $path, $this->suffixStart ); if ( is_array( $stat ) ) { $storageDir = rtrim( $this->params['dir'], '/' ); $this->backend->loadListingStatInternal( "$storageDir/$relPath", $stat ); } return $relPath; } protected function pageFromList( $container, $dir, &$after, $limit, array $params ) { return $this->backend->getFileListPageInternal( $container, $dir, $after, $limit, $params ); } } /** @deprecated class alias since 1.43 */ class_alias( SwiftFileBackendFileList::class, 'SwiftFileBackendFileList' ); PK ! žCj� � / filebackend/fileiteration/FSFileBackendList.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file * @ingroup FileBackend */ namespace Wikimedia\FileBackend\FileIteration; use DirectoryIterator; use FilesystemIterator; use Iterator; use RecursiveDirectoryIterator; use RecursiveIteratorIterator; use UnexpectedValueException; use Wikimedia\FileBackend\FileBackendError; /** * Wrapper around RecursiveDirectoryIterator/DirectoryIterator that * catches exception or does any custom behavior that we may want. * Do not use this class from places outside FSFileBackend. * * @ingroup FileBackend */ abstract class FSFileBackendList implements Iterator { /** @var Iterator|null */ protected $iter; /** @var string */ protected $lastError; /** @var int */ protected $suffixStart; /** @var int */ protected $pos = 0; /** @var array */ protected $params = []; /** * @param string $dir File system directory * @param array $params */ public function __construct( $dir, array $params ) { $path = realpath( $dir ); // normalize if ( $path === false ) { $path = $dir; } $this->suffixStart = strlen( $path ) + 1; // size of "path/to/dir/" $this->params = $params; try { $this->iter = $this->initIterator( $path ); } catch ( UnexpectedValueException $e ) { $this->iter = null; // bad permissions? deleted? $this->lastError = $e->getMessage(); } } /** * Return an appropriate iterator object to wrap * * @param string $dir File system directory * @return Iterator * @throws UnexpectedValueException */ protected function initIterator( $dir ) { if ( !empty( $this->params['topOnly'] ) ) { // non-recursive # Get an iterator that will get direct sub-nodes return new DirectoryIterator( $dir ); } else { // recursive # Get an iterator that will return leaf nodes (non-directories) # RecursiveDirectoryIterator extends FilesystemIterator. # FilesystemIterator::SKIP_DOTS default is inconsistent in PHP 5.3.x. $flags = FilesystemIterator::CURRENT_AS_SELF | FilesystemIterator::SKIP_DOTS; return new RecursiveIteratorIterator( new RecursiveDirectoryIterator( $dir, $flags ), RecursiveIteratorIterator::CHILD_FIRST // include dirs ); } } /** * @see Iterator::key() * @return int */ public function key(): int { return $this->pos; } /** * @see Iterator::current() * @return string|false */ #[\ReturnTypeWillChange] public function current() { return $this->getRelPath( $this->iter->current()->getPathname() ); } /** * @see Iterator::next() * @throws FileBackendError */ public function next(): void { try { $this->iter->next(); $this->filterViaNext(); } catch ( UnexpectedValueException $e ) { // bad permissions? deleted? $this->lastError = $e->getMessage(); throw new FileBackendError( "File iterator gave UnexpectedValueException." ); } ++$this->pos; } /** * @see Iterator::rewind() * @throws FileBackendError */ public function rewind(): void { $this->pos = 0; try { $this->iter->rewind(); $this->filterViaNext(); } catch ( UnexpectedValueException $e ) { // bad permissions? deleted? $this->lastError = $e->getMessage(); throw new FileBackendError( "File iterator gave UnexpectedValueException." ); } } /** * @see Iterator::valid() * @return bool */ public function valid(): bool { return $this->iter && $this->iter->valid(); } /** * @return string|null The last caught exception message */ public function getLastError() { return $this->lastError; } /** * Filter out items by advancing to the next ones */ protected function filterViaNext() { } /** * Return only the relative path and normalize slashes to FileBackend-style. * Uses the "real path" since the suffix is based upon that. * * @param string $dir * @return string */ protected function getRelPath( $dir ) { $path = realpath( $dir ); if ( $path === false ) { $path = $dir; } return strtr( substr( $path, $this->suffixStart ), '\\', '/' ); } } /** @deprecated class alias since 1.43 */ class_alias( FSFileBackendList::class, 'FSFileBackendList' ); PK ! �+�� � 2 filebackend/fileiteration/FSFileBackendDirList.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file * @ingroup FileBackend */ namespace Wikimedia\FileBackend\FileIteration; class FSFileBackendDirList extends FSFileBackendList { protected function filterViaNext() { while ( $this->iter->valid() ) { if ( $this->iter->current()->isDot() || !$this->iter->current()->isDir() ) { $this->iter->next(); // skip non-directories and dot files } else { break; } } } } /** @deprecated class alias since 1.43 */ class_alias( FSFileBackendDirList::class, 'FSFileBackendDirList' ); PK ! �ڕ�� � ? filebackend/fileiteration/FileBackendStoreShardFileIterator.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file * @ingroup FileBackend */ namespace Wikimedia\FileBackend\FileIteration; use ArrayIterator; /** * Iterator for listing regular files */ class FileBackendStoreShardFileIterator extends FileBackendStoreShardListIterator { protected function listFromShard( $container ) { $list = $this->backend->getFileListInternal( $container, $this->directory, $this->params ); if ( $list === null ) { return new ArrayIterator( [] ); } else { // @phan-suppress-next-line PhanTypeMismatchReturnSuperType return is_array( $list ) ? new ArrayIterator( $list ) : $list; } } } /** @deprecated class alias since 1.43 */ class_alias( FileBackendStoreShardFileIterator::class, 'FileBackendStoreShardFileIterator' ); PK ! �%n�� � > filebackend/fileiteration/FileBackendStoreShardDirIterator.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file * @ingroup FileBackend */ namespace Wikimedia\FileBackend\FileIteration; use ArrayIterator; /** * Iterator for listing directories */ class FileBackendStoreShardDirIterator extends FileBackendStoreShardListIterator { protected function listFromShard( $container ) { $list = $this->backend->getDirectoryListInternal( $container, $this->directory, $this->params ); if ( $list === null ) { return new ArrayIterator( [] ); } else { // @phan-suppress-next-line PhanTypeMismatchReturnSuperType return is_array( $list ) ? new ArrayIterator( $list ) : $list; } } } /** @deprecated class alias since 1.43 */ class_alias( FileBackendStoreShardDirIterator::class, 'FileBackendStoreShardDirIterator' ); PK ! �v/� � 2 filebackend/fileiteration/SwiftFileBackendList.phpnu �Iw�� <?php /** * OpenStack Swift based file backend. * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file * @ingroup FileBackend * @author Russ Nelson */ namespace Wikimedia\FileBackend\FileIteration; use Iterator; use Traversable; use Wikimedia\FileBackend\SwiftFileBackend; /** * SwiftFileBackend helper class to page through listings. * Swift also has a listing limit of 10,000 objects for performance. * Do not use this class from places outside SwiftFileBackend. * * @ingroup FileBackend */ abstract class SwiftFileBackendList implements Iterator { /** @var string[]|array[] Current page of entries; path list or (path,stat map) list */ protected $iterableBuffer = []; /** @var string|null Continuation marker; the next page starts *after* this path */ protected $continueAfter = null; /** @var int */ protected $pos = 0; /** @var array */ protected $params = []; /** @var SwiftFileBackend */ protected $backend; /** @var string Container name */ protected $container; /** @var string Storage directory */ protected $dir; /** @var int */ protected $suffixStart; private const PAGE_SIZE = 9000; // file listing buffer size /** * @param SwiftFileBackend $backend * @param string $fullCont Resolved container name * @param string $dir Resolved directory relative to container * @param array $params * @note This defers I/O by not buffering the first page (useful for AppendIterator use) * @note Do not call current()/valid() without calling rewind() first */ public function __construct( SwiftFileBackend $backend, $fullCont, $dir, array $params ) { $this->backend = $backend; $this->container = $fullCont; $this->dir = $dir; if ( substr( $this->dir, -1 ) === '/' ) { $this->dir = substr( $this->dir, 0, -1 ); // remove trailing slash } if ( $this->dir == '' ) { // whole container $this->suffixStart = 0; } else { // dir within container $this->suffixStart = strlen( $this->dir ) + 1; // size of "path/to/dir/" } $this->params = $params; } /** * @see Iterator::key() * @return int */ public function key(): int { return $this->pos; } /** * @inheritDoc */ public function next(): void { ++$this->pos; if ( $this->iterableBuffer === null ) { // Last page of entries failed to load return; } // Advance to the next entry in the page next( $this->iterableBuffer ); // Check if there are no entries left in this page and // advance to the next page if this page was not empty. if ( !$this->valid() && count( $this->iterableBuffer ) ) { $this->iterableBuffer = $this->pageFromList( $this->container, $this->dir, $this->continueAfter, self::PAGE_SIZE, $this->params ); } } /** * @inheritDoc */ public function rewind(): void { $this->pos = 0; $this->continueAfter = null; $this->iterableBuffer = $this->pageFromList( $this->container, $this->dir, // @phan-suppress-next-line PhanTypeMismatchArgumentPropertyReferenceReal $this->continueAfter, self::PAGE_SIZE, $this->params ); } /** * @see Iterator::valid() * @return bool */ public function valid(): bool { if ( $this->iterableBuffer === null ) { // Last page of entries failed to load return false; } // Note that entries (paths/tuples) are never boolean return ( current( $this->iterableBuffer ) !== false ); } /** * Get the next page of entries * * @param string $container Resolved container name * @param string $dir Resolved path relative to container * @param string &$after @phan-output-reference Continuation marker * @param int $limit * @param array $params * @return Traversable|array */ abstract protected function pageFromList( $container, $dir, &$after, $limit, array $params ); } /** @deprecated class alias since 1.43 */ class_alias( SwiftFileBackendList::class, 'SwiftFileBackendList' ); PK ! ^��I� � ExplodeIterator.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ /** * An iterator which works exactly like: * * foreach ( explode( $delim, $s ) as $element ) { * ... * } * * Except it doesn't use 193 byte per element */ class ExplodeIterator implements Iterator { /** @var string */ private $subject; /** @var int */ private $subjectLength; /** @var string */ private $delim; /** @var int */ private $delimLength; /** @var int|false The position of the start of the line */ private $curPos; /** @var int|false The position after the end of the next delimiter */ private $endPos; /** @var string|false The current token */ private $current; /** * Construct a DelimIterator * @param string $delim * @param string $subject */ public function __construct( $delim, $subject ) { $this->subject = $subject; $this->delim = $delim; // Micro-optimisation (theoretical) $this->subjectLength = strlen( $subject ); $this->delimLength = strlen( $delim ); $this->rewind(); } public function rewind(): void { $this->curPos = 0; $this->endPos = strpos( $this->subject, $this->delim ); $this->refreshCurrent(); } public function refreshCurrent() { if ( $this->curPos === false ) { $this->current = false; } elseif ( $this->curPos >= $this->subjectLength ) { $this->current = ''; } elseif ( $this->endPos === false ) { $this->current = substr( $this->subject, $this->curPos ); } else { $this->current = substr( $this->subject, $this->curPos, $this->endPos - $this->curPos ); } } /** * @return string|false */ #[\ReturnTypeWillChange] public function current() { return $this->current; } /** * @return int|false Current position or boolean false if invalid */ #[\ReturnTypeWillChange] public function key() { return $this->curPos; } /** * @return void */ public function next(): void { if ( $this->endPos === false ) { $this->curPos = false; } else { $this->curPos = $this->endPos + $this->delimLength; if ( $this->curPos >= $this->subjectLength ) { $this->endPos = false; } else { $this->endPos = strpos( $this->subject, $this->delim, $this->curPos ); } } $this->refreshCurrent(); } /** * @return bool */ public function valid(): bool { return $this->curPos !== false; } } PK ! n�ISg g MWCryptHash.phpnu �Iw�� <?php /** * Utility functions for generating hashes * * This is based in part on Drupal code as well as what we used in our own code * prior to introduction of this class, by way of MWCryptRand. * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ class MWCryptHash { /** * The hash algorithm being used */ protected static ?string $algo = null; /** * The number of bytes outputted by the hash algorithm */ protected static int $hashLength; /** * Decide on the best acceptable hash algorithm we have available for hash() * @return string A hash algorithm */ public static function hashAlgo() { $algorithm = self::$algo; if ( $algorithm !== null ) { return $algorithm; } $algos = hash_hmac_algos(); $preference = [ 'whirlpool', 'sha256' ]; foreach ( $preference as $algorithm ) { if ( in_array( $algorithm, $algos, true ) ) { self::$algo = $algorithm; return $algorithm; } } throw new DomainException( 'Could not find an acceptable hashing function.' ); } /** * Return the byte-length output of the hash algorithm we are * using in self::hash and self::hmac. * * @param bool $raw True to return the length for binary data, false to * return for hex-encoded * @return int Number of bytes the hash outputs */ public static function hashLength( $raw = true ) { self::$hashLength ??= strlen( self::hash( '', true ) ); // Optimisation: Skip computing the length of non-raw hashes. // The algos in hashAlgo() all produce a digest that is a multiple // of 8 bits, where hex is always twice the length of binary byte length. return $raw ? self::$hashLength : self::$hashLength * 2; } /** * Generate a cryptographic hash value (message digest) for a string, * making use of the best hash algorithm that we have available. * * @param string $data * @param bool $raw True to return binary data, false to return it hex-encoded * @return string A hash of the data */ public static function hash( $data, $raw = true ) { return hash( self::hashAlgo(), $data, $raw ); } /** * Generate a keyed cryptographic hash value (HMAC) for a string, * making use of the best hash algorithm that we have available. * * @param string $data * @param string $key * @param bool $raw True to return binary data, false to return it hex-encoded * @return string An HMAC hash of the data + key */ public static function hmac( $data, $key, $raw = true ) { if ( !is_string( $key ) ) { // hash_hmac tolerates non-string (would return null with warning) throw new InvalidArgumentException( 'Invalid key type: ' . get_debug_type( $key ) ); } return hash_hmac( self::hashAlgo(), $data, $key, $raw ); } } PK ! ��>X� � Deflate.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. * */ /** * Server-side helper for client-side compressed content. * * @since 1.32 */ class Deflate { /** * Whether the content is deflated * * @param string $data * * @return bool */ public static function isDeflated( string $data ): bool { return substr( $data, 0, 11 ) === 'rawdeflate,'; } /** * For content that has been compressed with deflate in the client, * try to uncompress it with inflate. * * If data is not prefixed with 'rawdeflate,' it will be returned unmodified. * * Data can be compressed in the client using the 'mediawiki.deflate' module: * * @code * mw.loader.using( 'mediawiki.deflate' ).then( function () { * var deflated = mw.deflate( myContent ); * } ); * @endcode * * @param string $data Deflated data * @return StatusValue Inflated data will be set as the value * @throws InvalidArgumentException If the data wasn't deflated */ public static function inflate( string $data ): StatusValue { if ( !self::isDeflated( $data ) ) { throw new InvalidArgumentException( 'Data does not begin with deflated prefix' ); } $deflated = base64_decode( substr( $data, 11 ), true ); if ( $deflated === false ) { return StatusValue::newFatal( 'deflate-invaliddeflate' ); } // phpcs:ignore Generic.PHP.NoSilencedErrors.Discouraged $inflated = @gzinflate( $deflated ); if ( $inflated === false ) { return StatusValue::newFatal( 'deflate-invaliddeflate' ); } return StatusValue::newGood( $inflated ); } } PK ! ߷և16 16 Message/README.mdnu �Iw�� Wikimedia Internationalization Library ====================================== This library provides interfaces and value objects for internationalization (i18n) of applications in PHP. It is based on the i18n code used in MediaWiki, and is also intended to be compatible with [jQuery.i18n], a JavaScript i18n library. Concepts -------- Any text string that is needed in an application is a **message**. This might be something like a button label, a sentence, or a longer text. Each message is assigned a **message key**, which is used as the identifier in code. Each message is translated into various languages, each represented by a **language code**. The message's text (as translated into each language) can contain **placeholders**, which represents a place in the message where a **parameter** is to be inserted, and **formatting commands**. It might be plain text other than these placeholders and formatting commands, or it might be in a **markup language** such as wikitext or Markdown. A **formatter** is used to convert the message key and parameters (that is, a **message specifier**) into a text representation in a particular language and **output format**. The library itself imposes few restrictions on all of these concepts; this document contains recommendations to help various implementations operate in compatible ways. Usage ----- <pre lang="php"> use Wikimedia\Message\MessageValue; use Wikimedia\Message\MessageParam; use Wikimedia\Message\ParamType; // Constructor interface $message = new MessageValue( 'message-key', [ 'parameter', new MessageValue( 'another-message' ), new MessageParam( ParamType::NUM, 12345 ), ] ); // Fluent interface $message = MessageValue::new( 'message-key' ) ->params( 'parameter', new MessageValue( 'another-message' ) ) ->numParams( 12345 ); // Formatting $messageFormatter = $serviceContainer->get( 'MessageFormatterFactory' )->getTextFormatter( 'de' ); $output = $messageFormatter->format( $message ); </pre> Class Overview -------------- ### Messages Messages and their parameters are represented by newable value objects. **MessageValue** represents an instance of a message, holding the key and any parameters. It is mutable in that parameters can be added to the object after creation. **MessageSpecifier** is an interface implemented by MessageValue (and, outside of the Wikimedia\Message namespace, also MediaWiki\Message\Message), which only provides getter methods for the key and parameters, and no way to mutate the object. It should be used in methods that output or inspect messages, but aren't supposed to modify them. **MessageParam** is an abstract value class representing a parameter to a message. It has a type (using constants defined in the **ParamType** class) and a value. It has two implementations: - **ScalarParam** represents a single-valued parameter, such as a text string, a number, or another message. - **ListParam** represents a list of values, which will be joined together with appropriate separators. It has a "list type" (using constants defined in the **ListType** class) defining the desired separators. #### Machine-readable messages **DataMessageValue** represents a message with additional machine-readable data. In addition to the key and message parameters, it holds a "code" and structured data that would be a useful representation of the message in an API response or the like. For example, a message for an "integer out of range" error might have one of three different keys depending on whether the range has a minimum, maximum, or both. But all should have the same code (representing the concept of "integer out of range") and should likely have structured data representing the range directly as `[ 'min' => 1, 'max' => 10 ]` rather than as a flat array of MessageParam objects. ### Formatters A formatter for a particular language is obtained from an implementation of **IMessageFormatterFactory**. No implementation of this interface is provided by this library. If an environment needs its formatters to vary behavior on things other than the language code, for example selecting among multiple sources of messages or markup language used for processing message texts, it should define a MessageFormatterFactoryFactory of some sort to provide appropriate IMessageFormatterFactory implementations. There is no one base interface for all formatters; the intent is that type hinting will ensure that the formatter being used will produce output in the expected output format. The defined output formats are: - **ITextFormatter** produces plain text output. No implementation of these interfaces are provided by this library. Formatter implementations are expected to perform the following procedure to generate the output string: 1. Fetch the message's translation in the formatter's language. Details of this fetching are unspecified here. - If no translation is found in the formatter's language, it should attempt to fall back to appropriate other languages. Details of the fallback are unspecified here. - If no translation can be found in any fallback language, a string should be returned that indicates at minimum the message key that was unable to be found. 2. Replace placeholders with parameter values. - Note that placeholders must not be replaced recursively. That is, if a parameter's value contains text that looks like a placeholder, it must not be replaced as if it really were a placeholder. - Certain types of parameters are not substituted directly at this stage. Instead their placeholders must be replaced with an opaque representation that will not be misinterpreted during later stages. - Parameters of type RAW or PLAINTEXT - TEXT parameters with a MessageValue as the value - LIST parameters with any late-substituted value as one of their values. 3. Process any formatting commands. 4. Process the source markup language to produce a string in the desired output format. This may be a no-op, and may be combined with the previous step if the markup language implements compatible formatting commands. 5. Replace any opaque representations from step 2 with the actual values of the corresponding parameters. Guidelines for Interoperability ------------------------------- Besides allowing for libraries to safely supply their own translations for every app using them, and apps to easily use libraries' translations instead of having to retranslate everything, following these guidelines will also help open source projects use [translatewiki.net] for crowdsourced volunteer translation into many languages. ### Language codes [BCP 47] language tags should be used for language codes. If a supplied language tag is not recognized, at minimum the corresponding tag with all optional subtags stripped should be tried as a fallback. All messages must have a translation in English (code "en"). All languages should fall back to English as a last resort. The English translations should use `{{PLURAL:...}}` and `{{GENDER:...}}` even when English doesn't make a grammatical distinction, to signal to translators that plural/gender support is available. Language code "qqq" is reserved for documenting messages. Documentation should describe the context in which the message is used and the values of all parameters used with the message. Generally this is written in English. Attempting to obtain a message formatter for "qqq" should return one for "en" instead. Language code "qqx" is reserved for debugging. Rather than retrieving translations from some underlying storage, every key should act as if it were translated as something `(key-name: $1, $2, $3)` with the number of placeholders depending on how many parameters are included in the MessageValue. ### Message keys Message keys intended for use with external implementations should follow certain guidelines for interoperability: - Keys should be restricted to the regular expression `/^[a-z][a-z0-9-]*$/`. That is, it should consist of lowercase ASCII letters, numbers, and hyphen only, and should begin with a letter. - Keys should be prefixed to help avoid collisions. For example, a library named "ApplePicker" should prefix its message keys with "applepicker-". - Common values needing translation, such as names of months and weekdays, should not be prefixed by each library. Libraries needing these should use keys from the [Common Locale Data Repository][CLDR] and document this requirement, and environments should provide these messages. ### Message format Placeholders are represented by `$1`, `$2`, `$3`, and so on. Text like `$100` is interpreted as a placeholder for parameter 100 if 100 or more parameters were supplied, as a placeholder for parameter 10 followed by text "0" if between ten and 99 parameters were supplied, and as a placeholder for parameter 1 followed by text "00" if between one and nine parameters were supplied. All formatting commands look like `{{NAME:$value1|$value2|$value3|...}}`. Braces are to be balanced, e.g. `{{NAME:foo|{{bar|baz}}}}` has $value1 as "foo" and $value2 as "{{bar|baz}}". The name is always case-insensitive. Anything syntactically resembling a placeholder or formatting command that does not correspond to an actual parameter or known command should be left unchanged for processing by the markup language processor. Libraries providing messages for use by externally-defined formatters should generally assume no markup language will be applied, and should avoid constructs used by common markup languages unless they also make sense when read as plain text. ### Formatting commands The following formatting commands should be supported. #### PLURAL `{{PLURAL:$count|$formA|$formB|...}}` is used to produce plurals. $count is a number, which may have been formatted with ParamType::NUM. The number of forms and which count corresponds to which form depend on the language, for example English uses `{{PLURAL:$1|one|other}}` while Arabic uses `{{PLURAL:$1|zero|one|two|few|many|other}}`. Details are defined in [CLDR][CLDR plurals]. It is not possible to "skip" positions while still suppling later ones. If too few values are supplied, the final form is repeated for subsequent positions. If there is an explicit plural form to be given for a specific number, it may be specified with syntax like `{{PLURAL:$1|one egg|$1 eggs|12=a dozen eggs}}`. #### GENDER `{{GENDER:$name|$masculine|$feminine|$unspecified}}` is used to handle grammatical gender, typically when messages refer to user accounts. This supports three grammatical genders: "male", "female", and a third option for cases where the gender is unspecified, unknown, or neither male nor female. It does not attempt to handle animate-inanimate or [T-V] distinctions. $name is a user account name or other similar identifier. If the name given does not correspond to any known user account, it should probably use the $unspecified gender. If $feminine and/or $unspecified is not specified, the value of $masculine is normally used in its place. #### GRAMMAR `{{GRAMMAR:$form|$term}}` converts a term to an appropriate grammatical form. If no mapping for $term to $form exists, $term should be returned unchanged. See [jQuery.i18n § Grammar][jQuery.i18n grammar] for details. #### BIDI `{{BIDI:$text}}` applies directional isolation to the wrapped text, to attempt to avoid errors where directionally-neutral characters are wrongly displayed when between LTR and RTL content. This should output U+202A (left-to-right embedding) or U+202B (right-to-left embedding) before the text, depending on the directionality of the first strongly-directional character in $text, and U+202C (pop directional formatting) after, or do something equivalent for the target output format. ### Supplying translations Code intending its messages to be used by externally-defined formatters should supply the translations as described by [jQuery.i18n § Message File Format][jQuery.i18n file format]. In brief, the base directory of the library should contain a directory named "i18n". This directory should contain JSON files named by code such as "en.json", "de.json", "qqq.json", each with contents like: ```json { "@metadata": { "authors": [ "Alice", "Bob", "Carol", "David" ], "last-updated": "2012-09-21" }, "appname-title": "Example Application", "appname-sub-title": "An example application", "appname-header-introduction": "Introduction", "appname-about": "About this application", "appname-footer": "Footer text" } ``` Formatter implementations should be able to consume message data supplied in this format, either directly via registration of i18n directories to check or by providing tooling to incorporate it during a build step. ### Machine-readable data Libraries producing MessageValues as error messages should generally produce DataMessageValues instead. Codes should be similar to message keys but need not be prefixed. Data should be restricted to values that will produce valid output when passed to `json_encode()`. Libraries producing MessageValues in other contexts should consider whether the same applies to those contexts. --- [jQuery.i18n]: https://github.com/wikimedia/jquery.i18n [BCP 47]: https://tools.ietf.org/rfc/bcp/bcp47.txt [CLDR]: http://cldr.unicode.org/ [CLDR plurals]: https://www.unicode.org/cldr/charts/latest/supplemental/language_plural_rules.html [jQuery.i18n grammar]: https://github.com/wikimedia/jquery.i18n#grammar [jQuery.i18n file format]: https://github.com/wikimedia/jquery.i18n#message-file-format [translatewiki.net]: https://translatewiki.net/wiki/Translating:New_project [T-V]: https://en.wikipedia.org/wiki/T%E2%80%93V_distinction PK ! !�kF F Message/ListType.phpnu �Iw�� <?php namespace Wikimedia\Message; /** * The constants used to specify list types. The values of the constants are an * unstable implementation detail. */ class ListType { /** A comma-separated list */ public const COMMA = 'comma'; /** A semicolon-separated list */ public const SEMICOLON = 'semicolon'; /** A pipe-separated list */ public const PIPE = 'pipe'; /** A natural-language list separated by "and" */ public const AND = 'text'; public static function cases(): array { return [ self::COMMA, self::SEMICOLON, self::PIPE, self::AND, ]; } } PK ! �$n)� � $ Message/IMessageFormatterFactory.phpnu �Iw�� <?php namespace Wikimedia\Message; /** * A simple factory providing a message formatter for a given language code. * * @see ITextFormatter */ interface IMessageFormatterFactory { /** * Get a text message formatter for a given language. * * @param string $langCode The language code * @return ITextFormatter */ public function getTextFormatter( $langCode ): ITextFormatter; } PK ! LyT=m+ m+ Message/MessageValue.phpnu �Iw�� <?php namespace Wikimedia\Message; use MediaWiki\Json\JsonDeserializable; use MediaWiki\Json\JsonDeserializableTrait; use MediaWiki\Json\JsonDeserializer; use Stringable; /** * Value object representing a message for i18n. * * A MessageValue holds a key and an array of parameters. It can be converted * to a string in a particular language using formatters obtained from an * IMessageFormatterFactory. * * MessageValues are pure value objects and are newable and (de)serializable. * * @newable */ class MessageValue implements JsonDeserializable, MessageSpecifier { use JsonDeserializableTrait; /** @var string */ private $key; /** @var MessageParam[] */ private $params; /** * @stable to call * * @param string $key * @param (MessageParam|MessageSpecifier|string|int|float)[] $params Values that are not instances * of MessageParam are wrapped using ParamType::TEXT. */ public function __construct( $key, $params = [] ) { $this->key = $key; $this->params = []; $this->params( ...$params ); } /** * Static constructor for easier chaining of `->params()` methods * @param string $key * @param (MessageParam|MessageSpecifier|string|int|float)[] $params * @return MessageValue */ public static function new( $key, $params = [] ) { return new MessageValue( $key, $params ); } /** * Convert from any MessageSpecifier to a MessageValue. * * When the given object is an instance of MessageValue, the same object is returned. * * @since 1.43 * @param MessageSpecifier $spec * @return MessageValue */ public static function newFromSpecifier( MessageSpecifier $spec ) { if ( $spec instanceof MessageValue ) { return $spec; } return new MessageValue( $spec->getKey(), $spec->getParams() ); } /** * Get the message key * * @return string */ public function getKey() { return $this->key; } /** * Get the parameter array * * @return MessageParam[] */ public function getParams() { return $this->params; } /** * Chainable mutator which adds text parameters and MessageParam parameters * * @param MessageParam|MessageSpecifier|string|int|float ...$values * @return $this */ public function params( ...$values ) { foreach ( $values as $value ) { if ( $value instanceof MessageParam ) { $this->params[] = $value; } else { $this->params[] = new ScalarParam( ParamType::TEXT, $value ); } } return $this; } /** * Chainable mutator which adds text parameters with a common type * * @param string $type One of the ParamType constants * @param MessageSpecifier|string|int|float ...$values Scalar values * @return $this */ public function textParamsOfType( $type, ...$values ) { foreach ( $values as $value ) { $this->params[] = new ScalarParam( $type, $value ); } return $this; } /** * Chainable mutator which adds object parameters * * @deprecated since 1.43 * @param Stringable ...$values stringable object values * @return $this */ public function objectParams( ...$values ) { wfDeprecated( __METHOD__, '1.43' ); foreach ( $values as $value ) { $this->params[] = new ScalarParam( ParamType::OBJECT, $value ); } return $this; } /** * Chainable mutator which adds list parameters with a common type * * @param string $listType One of the ListType constants * @param (MessageParam|MessageSpecifier|string|int|float)[] ...$values Each value * is an array of items suitable to pass as $params to ListParam::__construct() * @return $this */ public function listParamsOfType( $listType, ...$values ) { foreach ( $values as $value ) { $this->params[] = new ListParam( $listType, $value ); } return $this; } /** * Chainable mutator which adds parameters of type text (ParamType::TEXT). * * @param MessageSpecifier|string|int|float ...$values * @return $this */ public function textParams( ...$values ) { return $this->textParamsOfType( ParamType::TEXT, ...$values ); } /** * Chainable mutator which adds numeric parameters (ParamType::NUM). * * @param int|float ...$values * @return $this */ public function numParams( ...$values ) { return $this->textParamsOfType( ParamType::NUM, ...$values ); } /** * Chainable mutator which adds parameters which are a duration specified * in seconds (ParamType::DURATION_LONG). * * This is similar to shorDurationParams() except that the result will be * more verbose. * * @param int|float ...$values * @return $this */ public function longDurationParams( ...$values ) { return $this->textParamsOfType( ParamType::DURATION_LONG, ...$values ); } /** * Chainable mutator which adds parameters which are a duration specified * in seconds (ParamType::DURATION_SHORT). * * This is similar to longDurationParams() except that the result will be more * compact. * * @param int|float ...$values * @return $this */ public function shortDurationParams( ...$values ) { return $this->textParamsOfType( ParamType::DURATION_SHORT, ...$values ); } /** * Chainable mutator which adds parameters which are an expiry timestamp (ParamType::EXPIRY). * * @param string ...$values Timestamp as accepted by the Wikimedia\Timestamp library, * or "infinity" * @return $this */ public function expiryParams( ...$values ) { return $this->textParamsOfType( ParamType::EXPIRY, ...$values ); } /** * Chainable mutator which adds parameters which are a date-time timestamp (ParamType::DATETIME). * * @since 1.36 * @param string ...$values Timestamp as accepted by the Wikimedia\Timestamp library. * @return $this */ public function dateTimeParams( ...$values ) { return $this->textParamsOfType( ParamType::DATETIME, ...$values ); } /** * Chainable mutator which adds parameters which are a date timestamp (ParamType::DATE). * * @since 1.36 * @param string ...$values Timestamp as accepted by the Wikimedia\Timestamp library. * @return $this */ public function dateParams( ...$values ) { return $this->textParamsOfType( ParamType::DATE, ...$values ); } /** * Chainable mutator which adds parameters which are a time timestamp (ParamType::TIME). * * @since 1.36 * @param string ...$values Timestamp as accepted by the Wikimedia\Timestamp library. * @return $this */ public function timeParams( ...$values ) { return $this->textParamsOfType( ParamType::TIME, ...$values ); } /** * Chainable mutator which adds parameters which are a user group (ParamType::GROUP). * * @since 1.38 * @param string ...$values User Groups * @return $this */ public function userGroupParams( ...$values ) { return $this->textParamsOfType( ParamType::GROUP, ...$values ); } /** * Chainable mutator which adds parameters which are a number of bytes (ParamType::SIZE). * * @param int ...$values * @return $this */ public function sizeParams( ...$values ) { return $this->textParamsOfType( ParamType::SIZE, ...$values ); } /** * Chainable mutator which adds parameters which are a number of bits per * second (ParamType::BITRATE). * * @param int|float ...$values * @return $this */ public function bitrateParams( ...$values ) { return $this->textParamsOfType( ParamType::BITRATE, ...$values ); } /** * Chainable mutator which adds "raw" parameters (ParamType::RAW). * * Raw parameters are substituted after formatter processing. The caller is responsible * for ensuring that the value will be safe for the intended output format, and * documenting what that intended output format is. * * @param string ...$values * @return $this */ public function rawParams( ...$values ) { return $this->textParamsOfType( ParamType::RAW, ...$values ); } /** * Chainable mutator which adds plaintext parameters (ParamType::PLAINTEXT). * * Plaintext parameters are substituted after formatter processing. The value * will be escaped by the formatter as appropriate for the target output format * so as to be represented as plain text rather than as any sort of markup. * * @param string ...$values * @return $this */ public function plaintextParams( ...$values ) { return $this->textParamsOfType( ParamType::PLAINTEXT, ...$values ); } /** * Chainable mutator which adds comma lists (ListType::COMMA). * * The list parameters thus created are formatted as a comma-separated list, * or some local equivalent. * * @param (MessageParam|MessageSpecifier|string|int|float)[] ...$values Each value * is an array of items suitable to pass as $params to ListParam::__construct() * @return $this */ public function commaListParams( ...$values ) { return $this->listParamsOfType( ListType::COMMA, ...$values ); } /** * Chainable mutator which adds semicolon lists (ListType::SEMICOLON). * * The list parameters thus created are formatted as a semicolon-separated * list, or some local equivalent. * * @param (MessageParam|MessageSpecifier|string|int|float)[] ...$values Each value * is an array of items suitable to pass as $params to ListParam::__construct() * @return $this */ public function semicolonListParams( ...$values ) { return $this->listParamsOfType( ListType::SEMICOLON, ...$values ); } /** * Chainable mutator which adds pipe lists (ListType::PIPE). * * The list parameters thus created are formatted as a pipe ("|") -separated * list, or some local equivalent. * * @param (MessageParam|MessageSpecifier|string|int|float)[] ...$values Each value * is an array of items suitable to pass as $params to ListParam::__construct() * @return $this */ public function pipeListParams( ...$values ) { return $this->listParamsOfType( ListType::PIPE, ...$values ); } /** * Chainable mutator which adds natural-language lists (ListType::AND). * * The list parameters thus created, when formatted, are joined as in natural * language. In English, this means a comma-separated list, with the last * two elements joined with "and". * * @param (MessageParam|string)[] ...$values * @return $this */ public function textListParams( ...$values ) { return $this->listParamsOfType( ListType::AND, ...$values ); } /** * Dump the object for testing/debugging * * @return string */ public function dump() { $contents = ''; foreach ( $this->params as $param ) { $contents .= $param->dump(); } return '<message key="' . htmlspecialchars( $this->key ) . '">' . $contents . '</message>'; } protected function toJsonArray(): array { // WARNING: When changing how this class is serialized, follow the instructions // at <https://www.mediawiki.org/wiki/Manual:Parser_cache/Serialization_compatibility>! return [ 'key' => $this->key, 'params' => $this->params, ]; } public static function newFromJsonArray( JsonDeserializer $deserializer, array $json ) { // WARNING: When changing how this class is serialized, follow the instructions // at <https://www.mediawiki.org/wiki/Manual:Parser_cache/Serialization_compatibility>! return new self( $json['key'], $json['params'] ); } } PK ! �]� Message/DataMessageValue.phpnu �Iw�� <?php namespace Wikimedia\Message; use MediaWiki\Json\JsonDeserializer; /** * Value object representing a message for i18n with alternative * machine-readable data. * * This augments a MessageValue with an additional machine-readable code and * structured data. The intended use is to facilitate error reporting in APIs. * * For example, a MessageValue reporting an "integer out of range" error might * use one of three message keys, depending on whether there is a minimum, a * maximum, or both. But an API would likely want to use one code for all three * cases, and would likely want the endpoints represented along the lines of * `[ 'min' => 1, 'max' => 10 ]` rather than * `[ 0 => new ScalarParam( ParamType::TEXT, 1 ), 1 => new ScalarParam( ParamType::TEXT, 10 ) ]`. * * DataMessageValues are pure value objects and are newable and (de)serializable. * * @newable */ class DataMessageValue extends MessageValue { /** @var string */ private $code; /** @var array|null */ private $data; /** * @stable to call * * @param string $key * @param (MessageParam|MessageValue|string|int|float)[] $params * @param string|null $code String representing the concept behind * this message. * @param array|null $data Structured data representing the concept * behind this message. */ public function __construct( $key, $params = [], $code = null, ?array $data = null ) { parent::__construct( $key, $params ); $this->code = $code ?? $key; $this->data = $data; } /** * Static constructor for easier chaining of `->params()` methods * @param string $key * @param (MessageParam|MessageValue|string|int|float)[] $params * @param string|null $code * @param array|null $data * @return DataMessageValue */ public static function new( $key, $params = [], $code = null, ?array $data = null ) { return new DataMessageValue( $key, $params, $code, $data ); } /** * Get the message code * @return string */ public function getCode() { return $this->code; } /** * Get the message's structured data * @return array|null */ public function getData() { return $this->data; } public function dump() { $contents = ''; if ( $this->getParams() ) { $contents = '<params>'; foreach ( $this->getParams() as $param ) { $contents .= $param->dump(); } $contents .= '</params>'; } if ( $this->data !== null ) { $contents .= '<data>' . htmlspecialchars( json_encode( $this->data ), ENT_NOQUOTES ) . '</data>'; } return '<datamessage key="' . htmlspecialchars( $this->getKey() ) . '"' . ' code="' . htmlspecialchars( $this->code ) . '">' . $contents . '</datamessage>'; } protected function toJsonArray(): array { // WARNING: When changing how this class is serialized, follow the instructions // at <https://www.mediawiki.org/wiki/Manual:Parser_cache/Serialization_compatibility>! return parent::toJsonArray() + [ 'code' => $this->code, 'data' => $this->data, ]; } public static function newFromJsonArray( JsonDeserializer $deserializer, array $json ) { // WARNING: When changing how this class is serialized, follow the instructions // at <https://www.mediawiki.org/wiki/Manual:Parser_cache/Serialization_compatibility>! return new self( $json['key'], $json['params'], $json['code'], $json['data'] ); } } PK ! د��e e Message/MessageParam.phpnu �Iw�� <?php namespace Wikimedia\Message; use MediaWiki\Json\JsonDeserializable; use MediaWiki\Json\JsonDeserializableTrait; /** * Value object representing a message parameter that consists of a list of values. * * Message parameter classes are pure value objects and are newable and (de)serializable. */ abstract class MessageParam implements JsonDeserializable { use JsonDeserializableTrait; /** @var string */ protected $type; /** @var mixed */ protected $value; /** * Get the type of the parameter. * * @return string One of the ParamType constants */ public function getType() { return $this->type; } /** * Get the input value of the parameter * * @return mixed */ public function getValue() { return $this->value; } /** * Dump the object for testing/debugging * * @return string */ abstract public function dump(); } PK ! ��B Message/ParamType.phpnu �Iw�� <?php namespace Wikimedia\Message; /** * The constants used to specify parameter types. The values of the constants * are an unstable implementation detail. * * Unless otherwise noted, these should be used with an instance of ScalarParam. */ class ParamType { /** A simple text string or another MessageValue, not otherwise formatted. */ public const TEXT = 'text'; /** A number, to be formatted using local digits and separators */ public const NUM = 'num'; /** * A number of seconds, to be formatted as natural language text. * The value will be output exactly. */ public const DURATION_LONG = 'duration'; /** * A number of seconds, to be formatted as natural language text in an abbreviated way. * The output will be rounded to an appropriate magnitude. */ public const DURATION_SHORT = 'period'; /** * An expiry time. * * The input is either a timestamp in one of the formats accepted by the * Wikimedia\Timestamp library, or "infinity" if the thing doesn't expire. * * The output is a date and time in local format, or a string representing * an "infinite" expiry. */ public const EXPIRY = 'expiry'; /** * A date time in one of the formats accepted by the Wikimedia\Timestamp library. * * The output is a date and time in local format. */ public const DATETIME = 'datetime'; /** * A date in one of the formats accepted by the Wikimedia\Timestamp library. * * The output is a date in local format. */ public const DATE = 'date'; /** * A time in one of the formats accepted by the Wikimedia\Timestamp library. * * The output is a time in local format. */ public const TIME = 'time'; /** * User Group * @since 1.38 */ public const GROUP = 'group'; /** * For arbitrary stringable objects * @since 1.38 * @deprecated since 1.43 */ public const OBJECT = 'object'; /** A number of bytes. The output will be rounded to an appropriate magnitude. */ public const SIZE = 'size'; /** A number of bits per second. The output will be rounded to an appropriate magnitude. */ public const BITRATE = 'bitrate'; /** A list of values. Must be used with ListParam. */ public const LIST = 'list'; /** * A text parameter which is substituted after formatter processing. * * The creator of the parameter and message is responsible for ensuring * that the value will be safe for the intended output format, and * documenting what that intended output format is. */ public const RAW = 'raw'; /** * A text parameter which is substituted after formatter processing. * The output will be escaped as appropriate for the output format so * as to represent plain text rather than any sort of markup. */ public const PLAINTEXT = 'plaintext'; public static function cases(): array { return [ self::TEXT, self::NUM, self::DURATION_LONG, self::DURATION_SHORT, self::EXPIRY, self::DATETIME, self::DATE, self::TIME, self::GROUP, self::OBJECT, self::SIZE, self::BITRATE, self::LIST, self::RAW, self::PLAINTEXT, ]; } } PK ! ���B� � Message/ScalarParam.phpnu �Iw�� <?php namespace Wikimedia\Message; use InvalidArgumentException; use MediaWiki\Json\JsonDeserializer; use Stringable; /** * Value object representing a message parameter holding a single value. * * Message parameter classes are pure value objects and are safely newable. * * When using the deprecated ParamType::OBJECT, the parameter value * should be (de)serializable, otherwise (de)serialization of the * ScalarParam object will fail. * * @newable */ class ScalarParam extends MessageParam { /** * Construct a text parameter * * @stable to call. * * @param string $type One of the ParamType constants. * Using ParamType::OBJECT is deprecated since 1.43. * @param string|int|float|MessageSpecifier|Stringable $value */ public function __construct( $type, $value ) { if ( !in_array( $type, ParamType::cases() ) ) { throw new InvalidArgumentException( '$type must be one of the ParamType constants' ); } if ( $type === ParamType::LIST ) { throw new InvalidArgumentException( 'ParamType::LIST cannot be used with ScalarParam; use ListParam instead' ); } if ( $type === ParamType::OBJECT ) { wfDeprecatedMsg( 'Using ParamType::OBJECT was deprecated in MediaWiki 1.43', '1.43' ); } elseif ( $value instanceof MessageSpecifier ) { // Ensure that $this->value is JSON-serializable, even if $value is not // (but don't do it when using ParamType::OBJECT, since those objects may not expect it) $value = MessageValue::newFromSpecifier( $value ); } elseif ( is_object( $value ) && ( $value instanceof Stringable || is_callable( [ $value, '__toString' ] ) ) ) { // TODO: Remove separate '__toString' check above once we drop PHP 7.4 $value = (string)$value; } elseif ( !is_string( $value ) && !is_numeric( $value ) ) { $valType = get_debug_type( $value ); if ( $value === null || is_bool( $value ) ) { wfDeprecatedMsg( "Using $valType as message parameter was deprecated in MediaWiki 1.43", '1.43' ); $value = (string)$value; } else { throw new InvalidArgumentException( "Scalar parameter must be a string, number, Stringable, or MessageSpecifier; got $valType" ); } } $this->type = $type; $this->value = $value; } public function dump() { if ( $this->value instanceof MessageValue ) { $contents = $this->value->dump(); } else { $contents = htmlspecialchars( (string)$this->value ); } return "<{$this->type}>" . $contents . "</{$this->type}>"; } protected function toJsonArray(): array { // WARNING: When changing how this class is serialized, follow the instructions // at <https://www.mediawiki.org/wiki/Manual:Parser_cache/Serialization_compatibility>! return [ $this->type => $this->value, ]; } public static function newFromJsonArray( JsonDeserializer $deserializer, array $json ) { // WARNING: When changing how this class is serialized, follow the instructions // at <https://www.mediawiki.org/wiki/Manual:Parser_cache/Serialization_compatibility>! if ( count( $json ) !== 1 ) { throw new InvalidArgumentException( 'Invalid format' ); } // Use a dummy loop to get the first (and only) key/value pair in the array. foreach ( $json as $type => $value ) { return new self( $type, $value ); } } } PK ! C] A� � Message/MessageSpecifier.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\Message; /** * @stable for implementing */ interface MessageSpecifier { /** * Returns the message key * * If a list of multiple possible keys was supplied to the constructor, this method may * return any of these keys. After the message has been fetched, this method will return * the key that was actually used to fetch the message. * * @return string */ public function getKey(); /** * Returns the message parameters * * @return (MessageParam|MessageSpecifier|string|int|float)[] */ public function getParams(); } /** * @deprecated since 1.43 */ class_alias( MessageSpecifier::class, 'MessageSpecifier' ); PK ! WI?}� � Message/ITextFormatter.phpnu �Iw�� <?php namespace Wikimedia\Message; /** * Converts MessageSpecifier objects to localized plain text in a certain language. * * The caller cannot modify the details of message translation, such as which * of multiple sources the message is taken from. Any such flags may be injected * into the factory constructor. * * Implementations of TextFormatter are not required to perfectly format * any message in any language. Implementations should make a best effort to * produce human-readable text. * * @package MediaWiki\MessageFormatter */ interface ITextFormatter { /** * Get the internal language code in which format() is * @return string */ public function getLangCode(); /** * Convert a MessageSpecifier to text. * * The result is not safe for use as raw HTML. * * @param MessageSpecifier $message * @return string * @return-taint tainted */ public function format( MessageSpecifier $message ): string; } PK ! 7� Message/ListParam.phpnu �Iw�� <?php namespace Wikimedia\Message; use InvalidArgumentException; use MediaWiki\Json\JsonDeserializer; /** * Value object representing a message parameter that consists of a list of values. * * Message parameter classes are pure value objects and are newable and (de)serializable. * * @newable */ class ListParam extends MessageParam { /** @var string */ private $listType; /** * @stable to call. * * @param string $listType One of the ListType constants. * @param (MessageParam|MessageSpecifier|string|int|float)[] $elements Values in the list. * Values that are not instances of MessageParam are wrapped using ParamType::TEXT. */ public function __construct( $listType, array $elements ) { if ( !in_array( $listType, ListType::cases() ) ) { throw new InvalidArgumentException( '$listType must be one of the ListType constants' ); } $this->type = ParamType::LIST; $this->listType = $listType; $this->value = []; foreach ( $elements as $element ) { if ( $element instanceof MessageParam ) { $this->value[] = $element; } else { $this->value[] = new ScalarParam( ParamType::TEXT, $element ); } } } /** * Get the type of the list * * @return string One of the ListType constants */ public function getListType() { return $this->listType; } public function dump() { $contents = ''; foreach ( $this->value as $element ) { $contents .= $element->dump(); } return "<{$this->type} listType=\"{$this->listType}\">$contents</{$this->type}>"; } protected function toJsonArray(): array { // WARNING: When changing how this class is serialized, follow the instructions // at <https://www.mediawiki.org/wiki/Manual:Parser_cache/Serialization_compatibility>! return [ $this->type => $this->value, 'type' => $this->listType, ]; } public static function newFromJsonArray( JsonDeserializer $deserializer, array $json ) { // WARNING: When changing how this class is serialized, follow the instructions // at <https://www.mediawiki.org/wiki/Manual:Parser_cache/Serialization_compatibility>! if ( count( $json ) !== 2 || !isset( $json[ParamType::LIST] ) || !isset( $json['type'] ) ) { throw new InvalidArgumentException( 'Invalid format' ); } return new self( $json['type'], $json[ParamType::LIST] ); } } PK ! �#�) �) XhprofData.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ use Wikimedia\RunningStat; /** * Convenience class for working with XHProf profiling data * <https://github.com/phacility/xhprof>. XHProf can be installed via PECL. * * @copyright © 2014 Wikimedia Foundation and contributors * @since 1.28 */ class XhprofData { /** * @var array */ protected $config; /** * Hierarchical profiling data returned by xhprof. * @var array[] */ protected $hieraData; /** * Per-function inclusive data. * @var array[][] */ protected $inclusive; /** * Per-function inclusive and exclusive data. * @var array[] */ protected $complete; /** * Configuration data can contain: * - include: Array of function names to include in profiling. * - sort: Key to sort per-function reports on. * * @param array $data Xhprof profiling data, as returned by xhprof_disable() * @param array $config */ public function __construct( array $data, array $config = [] ) { $this->config = array_merge( [ 'include' => null, 'sort' => 'wt', ], $config ); $this->hieraData = $this->pruneData( $data ); } /** * Get raw data collected by xhprof. * * Each key in the returned array is an edge label for the call graph in * the form "caller==>callee". There is once special case edge labeled * simply "main()" which represents the global scope entry point of the * application. * * XHProf will collect different data depending on the flags that are used: * - ct: Number of matching events seen. * - wt: Inclusive elapsed wall time for this event in microseconds. * - cpu: Inclusive elapsed cpu time for this event in microseconds. * (XHPROF_FLAGS_CPU) * - mu: Delta of memory usage from start to end of callee in bytes. * (XHPROF_FLAGS_MEMORY) * - pmu: Delta of peak memory usage from start to end of callee in * bytes. (XHPROF_FLAGS_MEMORY) * - alloc: Delta of amount memory requested from malloc() by the callee, * in bytes. (XHPROF_FLAGS_MALLOC) * - free: Delta of amount of memory passed to free() by the callee, in * bytes. (XHPROF_FLAGS_MALLOC) * * @return array * @see getInclusiveMetrics() * @see getCompleteMetrics() */ public function getRawData() { return $this->hieraData; } /** * Convert an xhprof data key into an array of ['parent', 'child'] * function names. * * The resulting array is left padded with nulls, so a key * with no parent (eg 'main()') will return [null, 'function']. * * @param string $key * @return array */ public static function splitKey( $key ) { return array_pad( explode( '==>', $key, 2 ), -2, null ); } /** * Remove data for functions that are not included in the 'include' * configuration array. * * @param array[] $data Raw xhprof data * @return array[] */ protected function pruneData( $data ) { if ( !$this->config['include'] ) { return $data; } $want = array_fill_keys( $this->config['include'], true ); $want['main()'] = true; $keep = []; foreach ( $data as $key => $stats ) { [ $parent, $child ] = self::splitKey( $key ); if ( isset( $want[$parent] ) || isset( $want[$child] ) ) { $keep[$key] = $stats; } } return $keep; } /** * Get the inclusive metrics for each function call. Inclusive metrics * for given function include the metrics for all functions that were * called from that function during the measurement period. * * See getRawData() for a description of the metric that are returned for * each function call. The values for the wt, cpu, mu and pmu metrics are * arrays with these values: * - total: Cumulative value * - min: Minimum value * - mean: Mean (average) value * - max: Maximum value * - variance: Variance (spread) of the values * * @return array[][] * @see getRawData() * @see getCompleteMetrics() */ public function getInclusiveMetrics() { if ( $this->inclusive === null ) { $main = $this->hieraData['main()']; $hasCpu = isset( $main['cpu'] ); $hasMu = isset( $main['mu'] ); $hasAlloc = isset( $main['alloc'] ); $inclusive = []; foreach ( $this->hieraData as $key => $stats ) { [ , $child ] = self::splitKey( $key ); if ( !isset( $inclusive[$child] ) ) { $inclusive[$child] = [ 'ct' => 0, 'wt' => new RunningStat(), ]; if ( $hasCpu ) { $inclusive[$child]['cpu'] = new RunningStat(); } if ( $hasMu ) { $inclusive[$child]['mu'] = new RunningStat(); $inclusive[$child]['pmu'] = new RunningStat(); } if ( $hasAlloc ) { $inclusive[$child]['alloc'] = new RunningStat(); $inclusive[$child]['free'] = new RunningStat(); } } $inclusive[$child]['ct'] += $stats['ct']; foreach ( $stats as $stat => $value ) { if ( $stat === 'ct' ) { continue; } if ( !isset( $inclusive[$child][$stat] ) ) { // Ignore unknown stats continue; } for ( $i = 0; $i < $stats['ct']; $i++ ) { $inclusive[$child][$stat]->addObservation( $value / $stats['ct'] ); } } } // Convert RunningStat instances to static arrays and add // percentage stats. foreach ( $inclusive as $func => $stats ) { foreach ( $stats as $name => $value ) { if ( $value instanceof RunningStat ) { $total = $value->getMean() * $value->getCount(); $percent = ( isset( $main[$name] ) && $main[$name] ) ? 100 * $total / $main[$name] : 0; $inclusive[$func][$name] = [ 'total' => $total, 'min' => $value->min, 'mean' => $value->getMean(), 'max' => $value->max, 'variance' => $value->m2, 'percent' => $percent, ]; } } } uasort( $inclusive, self::makeSortFunction( $this->config['sort'], 'total' ) ); $this->inclusive = $inclusive; } return $this->inclusive; } /** * Get the inclusive and exclusive metrics for each function call. * * In addition to the normal data contained in the inclusive metrics, the * metrics have an additional 'exclusive' measurement which is the total * minus the totals of all child function calls. * * @return array[] * @see getRawData() * @see getInclusiveMetrics() */ public function getCompleteMetrics() { if ( $this->complete === null ) { // Start with inclusive data $this->complete = $this->getInclusiveMetrics(); foreach ( $this->complete as $func => $stats ) { foreach ( $stats as $stat => $value ) { if ( $stat === 'ct' ) { continue; } // Initialize exclusive data with inclusive totals $this->complete[$func][$stat]['exclusive'] = $value['total']; } // Add space for call tree information to be filled in later $this->complete[$func]['calls'] = []; $this->complete[$func]['subcalls'] = []; } foreach ( $this->hieraData as $key => $stats ) { [ $parent, $child ] = self::splitKey( $key ); if ( $parent !== null ) { // Track call tree information $this->complete[$child]['calls'][$parent] = $stats; $this->complete[$parent]['subcalls'][$child] = $stats; } if ( isset( $this->complete[$parent] ) ) { // Deduct child inclusive data from exclusive data foreach ( $stats as $stat => $value ) { if ( $stat === 'ct' ) { continue; } if ( !isset( $this->complete[$parent][$stat] ) ) { // Ignore unknown stats continue; } $this->complete[$parent][$stat]['exclusive'] -= $value; } } } uasort( $this->complete, self::makeSortFunction( $this->config['sort'], 'exclusive' ) ); } return $this->complete; } /** * Get a list of all callers of a given function. * * @param string $function Function name * @return array * @see getEdges() */ public function getCallers( $function ) { $edges = $this->getCompleteMetrics(); if ( isset( $edges[$function]['calls'] ) ) { return array_keys( $edges[$function]['calls'] ); } else { return []; } } /** * Get a list of all callees from a given function. * * @param string $function Function name * @return array * @see getEdges() */ public function getCallees( $function ) { $edges = $this->getCompleteMetrics(); if ( isset( $edges[$function]['subcalls'] ) ) { return array_keys( $edges[$function]['subcalls'] ); } else { return []; } } /** * Find the critical path for the given metric. * * @param string $metric Metric to find critical path for * @return array */ public function getCriticalPath( $metric = 'wt' ) { $func = 'main()'; $path = [ $func => $this->hieraData[$func], ]; while ( $func ) { $callees = $this->getCallees( $func ); $maxCallee = null; $maxCall = null; foreach ( $callees as $callee ) { $call = "{$func}==>{$callee}"; if ( $maxCall === null || $this->hieraData[$call][$metric] > $this->hieraData[$maxCall][$metric] ) { $maxCallee = $callee; $maxCall = $call; } } if ( $maxCall !== null ) { $path[$maxCall] = $this->hieraData[$maxCall]; } $func = $maxCallee; } return $path; } /** * Make a closure to use as a sort function. The resulting function will * sort by descending numeric values (largest value first). * * @param string $key Data key to sort on * @param string $sub Sub key to sort array values on * @return Closure */ public static function makeSortFunction( $key, $sub ) { return static function ( $a, $b ) use ( $key, $sub ) { if ( isset( $a[$key] ) && isset( $b[$key] ) ) { // Descending sort: larger values will be first in result. // Values for 'main()' will not have sub keys $valA = is_array( $a[$key] ) ? $a[$key][$sub] : $a[$key]; $valB = is_array( $b[$key] ) ? $b[$key][$sub] : $b[$key]; return $valB <=> $valA; } else { // Sort datum with the key before those without return isset( $a[$key] ) ? -1 : 1; } }; } } PK ! �?j6ik ik uuid/GlobalIdGenerator.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ namespace Wikimedia\UUID; use InvalidArgumentException; use RuntimeException; use Wikimedia\Assert\Assert; use Wikimedia\AtEase\AtEase; use Wikimedia\Timestamp\ConvertibleTimestamp; /** * Class for getting statistically unique IDs without a central coordinator * * @since 1.35 */ class GlobalIdGenerator { /** @var callable Callback for running shell commands */ protected $shellCallback; /** @var string Temporary directory */ protected $tmpDir; /** @var string * File prefix containing user ID to prevent collisions * if multiple users run MediaWiki (T268420) and getmyuid() is enabled */ protected $uniqueFilePrefix; /** @var string Local file path */ protected $nodeIdFile; /** @var string Node ID in binary (32 bits) */ protected $nodeId32; /** @var string Node ID in binary (48 bits) */ protected $nodeId48; /** @var bool Whether initialization completed */ protected $loaded = false; /** @var string Local file path */ protected $lockFile88; /** @var string Local file path */ protected $lockFile128; /** @var string Local file path */ protected $lockFileUUID; /** @var array Cached file handles */ protected $fileHandles = []; /** * Avoid using __CLASS__ so namespace separators aren't interpreted * as path components on Windows (T259693) */ private const FILE_PREFIX = 'mw-GlobalIdGenerator'; /** Key used in the serialized clock state map that is stored on disk */ private const CLOCK_TIME = 'time'; /** Key used in the serialized clock state map that is stored on disk */ private const CLOCK_COUNTER = 'counter'; /** Key used in the serialized clock state map that is stored on disk */ private const CLOCK_SEQUENCE = 'clkSeq'; /** Key used in the serialized clock state map that is stored on disk */ private const CLOCK_OFFSET = 'offset'; /** Key used in the serialized clock state map that is stored on disk */ private const CLOCK_OFFSET_COUNTER = 'offsetCounter'; /** * @param string|bool $tempDirectory A writable temporary directory * @param callback $shellCallback A callback that takes a shell command and returns the output */ public function __construct( $tempDirectory, $shellCallback ) { if ( func_num_args() >= 3 && !is_callable( $shellCallback ) ) { trigger_error( __CLASS__ . ' with a BagOStuff instance was deprecated in MediaWiki 1.37.', E_USER_DEPRECATED ); $shellCallback = func_get_arg( 2 ); } if ( !strlen( $tempDirectory ) ) { throw new InvalidArgumentException( "No temp directory provided" ); } $this->tmpDir = $tempDirectory; // Include the UID in the filename (T268420, T358768) if ( function_exists( 'posix_geteuid' ) ) { $fileSuffix = posix_geteuid(); } elseif ( function_exists( 'getmyuid' ) ) { $fileSuffix = getmyuid(); } else { $fileSuffix = ''; } $this->uniqueFilePrefix = self::FILE_PREFIX . $fileSuffix; $this->nodeIdFile = $tempDirectory . '/' . $this->uniqueFilePrefix . '-UID-nodeid'; // If different processes run as different users, they may have different temp dirs. // This is dealt with by initializing the clock sequence number and counters randomly. $this->lockFile88 = $tempDirectory . '/' . $this->uniqueFilePrefix . '-UID-88'; $this->lockFile128 = $tempDirectory . '/' . $this->uniqueFilePrefix . '-UID-128'; $this->lockFileUUID = $tempDirectory . '/' . $this->uniqueFilePrefix . '-UUID-128'; $this->shellCallback = $shellCallback; } /** * Get a statistically unique 88-bit unsigned integer ID string. * The bits of the UID are prefixed with the time (down to the millisecond). * * These IDs are suitable as values for the shard key of distributed data. * If a column uses these as values, it should be declared UNIQUE to handle collisions. * New rows almost always have higher UIDs, which makes B-TREE updates on INSERT fast. * They can also be stored "DECIMAL(27) UNSIGNED" or BINARY(11) in MySQL. * * UID generation is serialized on each server (as the node ID is for the whole machine). * * @param int $base Specifies a base other than 10 * @return string Number * @throws RuntimeException */ public function newTimestampedUID88( int $base = 10 ) { Assert::parameter( $base <= 36, '$base', 'must be <= 36' ); Assert::parameter( $base >= 2, '$base', 'must be >= 2' ); $info = $this->getTimeAndDelay( 'lockFile88', 1, 1024, 1024 ); $info[self::CLOCK_OFFSET_COUNTER] %= 1024; return \Wikimedia\base_convert( $this->getTimestampedID88( $info ), 2, $base ); } /** * @param array $info result of GlobalIdGenerator::getTimeAndDelay() * @return string 88 bits * @throws RuntimeException */ protected function getTimestampedID88( array $info ) { $time = $info[self::CLOCK_TIME]; $counter = $info[self::CLOCK_OFFSET_COUNTER]; // Take the 46 LSBs of "milliseconds since epoch" $id_bin = $this->millisecondsSinceEpochBinary( $time ); // Add a 10 bit counter resulting in 56 bits total $id_bin .= str_pad( decbin( $counter ), 10, '0', STR_PAD_LEFT ); // Add the 32 bit node ID resulting in 88 bits total $id_bin .= $this->getNodeId32(); // Convert to a 1-27 digit integer string if ( strlen( $id_bin ) !== 88 ) { throw new RuntimeException( "Detected overflow for millisecond timestamp." ); } return $id_bin; } /** * Get a statistically unique 128-bit unsigned integer ID string. * The bits of the UID are prefixed with the time (down to the millisecond). * * These IDs are suitable as globally unique IDs, without any enforced uniqueness. * New rows almost always have higher UIDs, which makes B-TREE updates on INSERT fast. * They can also be stored as "DECIMAL(39) UNSIGNED" or BINARY(16) in MySQL. * * UID generation is serialized on each server (as the node ID is for the whole machine). * * @param int $base Specifies a base other than 10 * @return string Number * @throws RuntimeException */ public function newTimestampedUID128( int $base = 10 ) { Assert::parameter( $base <= 36, '$base', 'must be <= 36' ); Assert::parameter( $base >= 2, '$base', 'must be >= 2' ); $info = $this->getTimeAndDelay( 'lockFile128', 16384, 1_048_576, 1_048_576 ); $info[self::CLOCK_OFFSET_COUNTER] %= 1_048_576; return \Wikimedia\base_convert( $this->getTimestampedID128( $info ), 2, $base ); } /** * @param array $info The result of GlobalIdGenerator::getTimeAndDelay() * @return string 128 bits * @throws RuntimeException */ protected function getTimestampedID128( array $info ) { $time = $info[self::CLOCK_TIME]; $counter = $info[self::CLOCK_OFFSET_COUNTER]; $clkSeq = $info[self::CLOCK_SEQUENCE]; // Take the 46 LSBs of "milliseconds since epoch" $id_bin = $this->millisecondsSinceEpochBinary( $time ); // Add a 20 bit counter resulting in 66 bits total $id_bin .= str_pad( decbin( $counter ), 20, '0', STR_PAD_LEFT ); // Add a 14 bit clock sequence number resulting in 80 bits total $id_bin .= str_pad( decbin( $clkSeq ), 14, '0', STR_PAD_LEFT ); // Add the 48 bit node ID resulting in 128 bits total $id_bin .= $this->getNodeId48(); // Convert to a 1-39 digit integer string if ( strlen( $id_bin ) !== 128 ) { throw new RuntimeException( "Detected overflow for millisecond timestamp." ); } return $id_bin; } /** * Return an RFC4122 compliant v1 UUID * * @return string * @throws RuntimeException */ public function newUUIDv1() { // There can be up to 10000 intervals for the same millisecond timestamp. // [0,4999] counter + [0,5000] offset is in [0,9999] for the offset counter. // Add this onto the timestamp to allow making up to 5000 IDs per second. return $this->getUUIDv1( $this->getTimeAndDelay( 'lockFileUUID', 16384, 5000, 5001 ) ); } /** * @param array $info Result of GlobalIdGenerator::getTimeAndDelay() * @return string 128 bits */ protected function getUUIDv1( array $info ) { $clkSeq_bin = \Wikimedia\base_convert( $info[self::CLOCK_SEQUENCE], 10, 2, 14 ); $time_bin = $this->intervalsSinceGregorianBinary( $info[self::CLOCK_TIME], $info[self::CLOCK_OFFSET_COUNTER] ); // Take the 32 bits of "time low" $id_bin = substr( $time_bin, 28, 32 ); // Add 16 bits of "time mid" resulting in 48 bits total $id_bin .= substr( $time_bin, 12, 16 ); // Add 4 bit version resulting in 52 bits total $id_bin .= '0001'; // Add 12 bits of "time high" resulting in 64 bits total $id_bin .= substr( $time_bin, 0, 12 ); // Add 2 bits of "variant" resulting in 66 bits total $id_bin .= '10'; // Add 6 bits of "clock seq high" resulting in 72 bits total $id_bin .= substr( $clkSeq_bin, 0, 6 ); // Add 8 bits of "clock seq low" resulting in 80 bits total $id_bin .= substr( $clkSeq_bin, 6, 8 ); // Add the 48 bit node ID resulting in 128 bits total $id_bin .= $this->getNodeId48(); // Convert to a 32 char hex string with dashes if ( strlen( $id_bin ) !== 128 ) { throw new RuntimeException( "Detected overflow for millisecond timestamp." ); } $hex = \Wikimedia\base_convert( $id_bin, 2, 16, 32 ); return sprintf( '%s-%s-%s-%s-%s', // "time_low" (32 bits) substr( $hex, 0, 8 ), // "time_mid" (16 bits) substr( $hex, 8, 4 ), // "time_hi_and_version" (16 bits) substr( $hex, 12, 4 ), // "clk_seq_hi_res" (8 bits) and "clk_seq_low" (8 bits) substr( $hex, 16, 4 ), // "node" (48 bits) substr( $hex, 20, 12 ) ); } /** * Return an RFC4122 compliant v1 UUID * * @return string 32 hex characters with no hyphens * @throws RuntimeException */ public function newRawUUIDv1() { return str_replace( '-', '', $this->newUUIDv1() ); } /** * Return an RFC4122 compliant v4 UUID * * @return string * @throws RuntimeException */ public function newUUIDv4() { $hex = bin2hex( random_bytes( 32 / 2 ) ); return sprintf( '%s-%s-%s-%s-%s', // "time_low" (32 bits) substr( $hex, 0, 8 ), // "time_mid" (16 bits) substr( $hex, 8, 4 ), // "time_hi_and_version" (16 bits) '4' . substr( $hex, 12, 3 ), // "clk_seq_hi_res" (8 bits, variant is binary 10x) and "clk_seq_low" (8 bits) dechex( 0x8 | ( hexdec( $hex[15] ) & 0x3 ) ) . $hex[16] . substr( $hex, 17, 2 ), // "node" (48 bits) substr( $hex, 19, 12 ) ); } /** * Return an RFC4122 compliant v4 UUID * * @return string 32 hex characters with no hyphens * @throws RuntimeException */ public function newRawUUIDv4() { return str_replace( '-', '', $this->newUUIDv4() ); } /** * Return an ID that is sequential *only* for this node and bucket * * These IDs are suitable for per-host sequence numbers, e.g. for some packet protocols. * * @param string $bucket Arbitrary bucket name (should be ASCII) * @param int $bits Bit size (<=48) of resulting numbers before wrap-around * @return float Integer value as float */ public function newSequentialPerNodeID( $bucket, $bits = 48 ) { return current( $this->newSequentialPerNodeIDs( $bucket, $bits, 1 ) ); } /** * Return IDs that are sequential *only* for this node and bucket * * @param string $bucket Arbitrary bucket name (should be ASCII) * @param int $bits Bit size (16 to 48) of resulting numbers before wrap-around * @param int $count Number of IDs to return * @return array Ordered list of float integer values * @see GlobalIdGenerator::newSequentialPerNodeID() */ public function newSequentialPerNodeIDs( $bucket, $bits, $count ) { return $this->getSequentialPerNodeIDs( $bucket, $bits, $count ); } /** * Get timestamp in a specified format from UUIDv1 * * @param string $uuid the UUID to get the timestamp from * @param int $format the format to convert the timestamp to. Default: TS_MW * @return string|false timestamp in requested format or false */ public function getTimestampFromUUIDv1( string $uuid, int $format = TS_MW ) { $components = []; if ( !preg_match( '/^([0-9a-f]{8})-([0-9a-f]{4})-(1[0-9a-f]{3})-([89ab][0-9a-f]{3})-([0-9a-f]{12})$/', $uuid, $components ) ) { throw new InvalidArgumentException( "Invalid UUIDv1 {$uuid}" ); } $timestamp = hexdec( substr( $components[3], 1 ) . $components[2] . $components[1] ); // The 60 bit timestamp value is constructed from fields of this UUID. // The timestamp is measured in 100-nanosecond units since midnight, October 15, 1582 UTC. $unixTime = ( $timestamp - 0x01b21dd213814000 ) / 1e7; return ConvertibleTimestamp::convert( $format, $unixTime ); } /** * Return IDs that are sequential *only* for this node and bucket * * @param string $bucket Arbitrary bucket name (should be ASCII) * @param int $bits Bit size (16 to 48) of resulting numbers before wrap-around * @param int $count Number of IDs to return * @return array Ordered list of float integer values * @throws RuntimeException * @see GlobalIdGenerator::newSequentialPerNodeID() */ protected function getSequentialPerNodeIDs( $bucket, $bits, $count ) { if ( $count <= 0 ) { return []; } if ( $bits < 16 || $bits > 48 ) { throw new RuntimeException( "Requested bit size ($bits) is out of range." ); } $path = $this->tmpDir . '/' . $this->uniqueFilePrefix . '-' . rawurlencode( $bucket ) . '-48'; // Get the UID lock file handle if ( isset( $this->fileHandles[$path] ) ) { $handle = $this->fileHandles[$path]; } else { $handle = fopen( $path, 'cb+' ); $this->fileHandles[$path] = $handle ?: null; } // Acquire the UID lock file if ( $handle === false ) { throw new RuntimeException( "Could not open '{$path}'." ); } if ( !flock( $handle, LOCK_EX ) ) { fclose( $handle ); throw new RuntimeException( "Could not acquire '{$path}'." ); } // Fetch the counter value and increment it... rewind( $handle ); // fetch as float $counter = floor( (float)trim( fgets( $handle ) ) ) + $count; // Write back the new counter value ftruncate( $handle, 0 ); rewind( $handle ); // Use fmod() to avoid "division by zero" on 32 bit machines // warp-around as needed fwrite( $handle, (string)fmod( $counter, 2 ** 48 ) ); fflush( $handle ); // Release the UID lock file flock( $handle, LOCK_UN ); $ids = []; $divisor = 2 ** $bits; // pre-increment counter value $currentId = floor( $counter - $count ); for ( $i = 0; $i < $count; ++$i ) { // Use fmod() to avoid "division by zero" on 32 bit machines $ids[] = fmod( ++$currentId, $divisor ); } return $ids; } /** * Get a (time,counter,clock sequence) where (time,counter) is higher * than any previous (time,counter) value for the given clock sequence. * This is useful for making UIDs sequential on a per-node basis. * * @param string $lockFile Name of a local lock file * @param int $clockSeqSize The number of possible clock sequence values * @param int $counterSize The number of possible counter values * @param int $offsetSize The number of possible offset values * @return array Array with the following keys: * - GlobalIdGenerator::CLOCK_TIME: (integer seconds, integer milliseconds) array * - GlobalIdGenerator::CLOCK_COUNTER: integer millisecond tie-breaking counter * - GlobalIdGenerator::CLOCK_SEQUENCE: integer clock identifier that is local to the node * - GlobalIdGenerator::CLOCK_OFFSET: integer offset for millisecond tie-breaking counter * - GlobalIdGenerator::CLOCK_OFFSET_COUNTER: integer; CLOCK_COUNTER with CLOCK_OFFSET applied * @throws RuntimeException */ protected function getTimeAndDelay( $lockFile, $clockSeqSize, $counterSize, $offsetSize ) { // Get the UID lock file handle if ( isset( $this->fileHandles[$this->$lockFile] ) ) { $handle = $this->fileHandles[$this->$lockFile]; } else { $handle = fopen( $this->$lockFile, 'cb+' ); $this->fileHandles[$this->$lockFile] = $handle ?: null; } // Acquire the UID lock file if ( $handle === false ) { throw new RuntimeException( "Could not open '{$this->$lockFile}'." ); } if ( !flock( $handle, LOCK_EX ) ) { fclose( $handle ); throw new RuntimeException( "Could not acquire '{$this->$lockFile}'." ); } // The formatters that use this method expect a timestamp with millisecond // precision and a counter upto a certain size. When more IDs than the counter // size are generated during the same timestamp, an exception is thrown as we // cannot increment further, because the formatted ID would not have enough // bits to fit the counter. // // To orchestrate this between independent PHP processes on the same host, // we must have a common sense of time so that we only have to maintain // a single counter in a single lock file. // // Given that: // * The system clock can be observed via time(), without milliseconds. // * Some other clock can be observed via microtime(), which also offers // millisecond precision. // * microtime() drifts in-process further and further away from the system // clock the longer a process runs for. // For example, on 2018-10-03 an HHVM 3.18 JobQueue process at WMF, // that ran for 9 min 55 sec, microtime drifted by 7 seconds. // time() does not have this problem. See https://bugs.php.net/bug.php?id=42659. // // We have two choices: // // 1. Use microtime() with the following caveats: // - The last stored time may be in the future, or our current time may be in the // past, in which case we'll frequently enter the slow timeWaitUntil() method to // try and "sync" the current process with the previous process. // We mustn't block for long though, max 10ms? // - For any drift above 10ms, we pretend that the clock went backwards, and treat // it the same way as after an NTP sync, by incrementing clock sequence instead. // Given the sequence rolls over automatically, and silently, and is meant to be // rare, this essentially sacrifices a reasonable guarantee of uniqueness. // - For long running processes (e.g. longer than a few seconds) the drift can // easily be more than 2 seconds. Because we only have a single lock file // and don't want to keep too many counters and deal with clearing those, // we fatal the user and refuse to make an ID. (T94522) // - This offers terrible service availability. // 2. Use time() instead, and expand the counter size by 1000x and use its // digits as if they were the millisecond fraction of our timestamp. // Known caveats or perf impact: None. We still need to read-write our // lock file on each generation, so might as well make the most of it. // // We choose the latter. $msecCounterSize = $counterSize * 1000; rewind( $handle ); // Format of lock file contents: // "<clk seq> <sec> <msec counter> <rand offset>" $data = explode( ' ', fgets( $handle ) ); if ( count( $data ) === 4 ) { // The UID lock file was already initialized $clkSeq = (int)$data[0] % $clockSeqSize; $prevSec = (int)$data[1]; $prevMsecCounter = (int)$data[2] % $msecCounterSize; $randOffset = (int)$data[3] % $counterSize; // If the system clock moved back or inter-process clock drift caused the last // writer process to record a higher time than the current process time, then // briefly wait for the current process clock to catch up. $sec = $this->timeWaitUntil( $prevSec ); if ( $sec === false ) { // There was too much clock drift to wait. Bump the clock sequence number to // avoid collisions between new and already-generated IDs with the same time. $clkSeq = ( $clkSeq + 1 ) % $clockSeqSize; $sec = time(); $msecCounter = 0; $randOffset = random_int( 0, $offsetSize - 1 ); trigger_error( "Clock was set back; sequence number incremented." ); } elseif ( $sec === $prevSec ) { // The time matches the last ID. Bump the tie-breaking counter. $msecCounter = $prevMsecCounter + 1; if ( $msecCounter >= $msecCounterSize ) { // More IDs generated with the same time than counterSize can accommodate flock( $handle, LOCK_UN ); throw new RuntimeException( "Counter overflow for timestamp value." ); } } else { // The time is higher than the last ID. Reset the tie-breaking counter. $msecCounter = 0; } } else { // Initialize UID lock file information $clkSeq = random_int( 0, $clockSeqSize - 1 ); $sec = time(); $msecCounter = 0; $randOffset = random_int( 0, $offsetSize - 1 ); } // Update and release the UID lock file ftruncate( $handle, 0 ); rewind( $handle ); fwrite( $handle, "{$clkSeq} {$sec} {$msecCounter} {$randOffset}" ); fflush( $handle ); flock( $handle, LOCK_UN ); // Split msecCounter back into msec and counter $msec = (int)( $msecCounter / 1000 ); $counter = $msecCounter % 1000; return [ self::CLOCK_TIME => [ $sec, $msec ], self::CLOCK_COUNTER => $counter, self::CLOCK_SEQUENCE => $clkSeq, self::CLOCK_OFFSET => $randOffset, self::CLOCK_OFFSET_COUNTER => $counter + $randOffset, ]; } /** * Wait till the current timestamp reaches $time and return the current * timestamp. This returns false if it would have to wait more than 10ms. * * @param int $time Result of time() * @return int|bool Timestamp or false */ protected function timeWaitUntil( $time ) { $start = microtime( true ); do { $ct = time(); // https://www.php.net/manual/en/language.operators.comparison.php if ( $ct >= $time ) { // current time is higher than or equal to than $time return $ct; } // up to 10ms } while ( ( microtime( true ) - $start ) <= 0.010 ); return false; } /** * @param array $time Array of second and millisecond integers * @return string 46 LSBs of "milliseconds since epoch" in binary (rolls over in 4201) * @throws RuntimeException */ protected function millisecondsSinceEpochBinary( array $time ) { [ $sec, $msec ] = $time; $ts = 1000 * $sec + $msec; if ( $ts > 2 ** 52 ) { throw new RuntimeException( __METHOD__ . ': sorry, this function doesn\'t work after the year 144680' ); } return substr( \Wikimedia\base_convert( (string)$ts, 10, 2, 46 ), -46 ); } /** * @param array $time Array of second and millisecond integers * @param int $delta Number of intervals to add on to the timestamp * @return string 60 bits of "100ns intervals since 15 October 1582" (rolls over in 3400) * @throws RuntimeException */ protected function intervalsSinceGregorianBinary( array $time, $delta = 0 ) { [ $sec, $msec ] = $time; $offset = '122192928000000000'; // 64 bit integers if ( PHP_INT_SIZE >= 8 ) { $ts = ( 1000 * $sec + $msec ) * 10000 + (int)$offset + $delta; $id_bin = str_pad( decbin( $ts % ( 2 ** 60 ) ), 60, '0', STR_PAD_LEFT ); } elseif ( extension_loaded( 'gmp' ) ) { // ms $ts = gmp_add( gmp_mul( (string)$sec, '1000' ), (string)$msec ); // 100ns intervals $ts = gmp_add( gmp_mul( $ts, '10000' ), $offset ); $ts = gmp_add( $ts, (string)$delta ); // wrap around $ts = gmp_mod( $ts, gmp_pow( '2', 60 ) ); $id_bin = str_pad( gmp_strval( $ts, 2 ), 60, '0', STR_PAD_LEFT ); } elseif ( extension_loaded( 'bcmath' ) ) { // ms $ts = bcadd( bcmul( $sec, '1000' ), $msec ); // 100ns intervals $ts = bcadd( bcmul( $ts, '10000' ), $offset ); $ts = bcadd( $ts, (string)$delta ); // wrap around $ts = bcmod( $ts, bcpow( '2', '60' ) ); $id_bin = \Wikimedia\base_convert( $ts, 10, 2, 60 ); } else { throw new RuntimeException( 'bcmath or gmp extension required for 32 bit machines.' ); } return $id_bin; } /** * Load the node ID information */ private function load() { if ( $this->loaded ) { return; } $this->loaded = true; // phpcs:ignore Generic.PHP.NoSilencedErrors.Discouraged $nodeId = @file_get_contents( $this->nodeIdFile ) ?: ''; // Try to get some ID that uniquely identifies this machine (RFC 4122)... if ( !preg_match( '/^[0-9a-f]{12}$/i', $nodeId ) ) { AtEase::suppressWarnings(); if ( PHP_OS_FAMILY === 'Windows' ) { // https://technet.microsoft.com/en-us/library/bb490913.aspx $csv = trim( ( $this->shellCallback )( 'getmac /NH /FO CSV' ) ); $line = substr( $csv, 0, strcspn( $csv, "\n" ) ); $info = str_getcsv( $line, ",", "\"", "\\" ); // @phan-suppress-next-line PhanTypeMismatchArgumentNullableInternal False positive $nodeId = isset( $info[0] ) ? str_replace( '-', '', $info[0] ) : ''; } elseif ( is_executable( '/sbin/ifconfig' ) ) { // Linux/BSD/Solaris/OS X // See https://linux.die.net/man/8/ifconfig $m = []; preg_match( '/\s([0-9a-f]{2}(?::[0-9a-f]{2}){5})\s/', ( $this->shellCallback )( '/sbin/ifconfig -a' ), $m ); $nodeId = isset( $m[1] ) ? str_replace( ':', '', $m[1] ) : ''; } AtEase::restoreWarnings(); if ( !preg_match( '/^[0-9a-f]{12}$/i', $nodeId ) ) { $nodeId = bin2hex( random_bytes( 12 / 2 ) ); // set multicast bit $nodeId[1] = dechex( hexdec( $nodeId[1] ) | 0x1 ); } file_put_contents( $this->nodeIdFile, $nodeId ); } $this->nodeId32 = \Wikimedia\base_convert( substr( sha1( $nodeId ), 0, 8 ), 16, 2, 32 ); $this->nodeId48 = \Wikimedia\base_convert( $nodeId, 16, 2, 48 ); } /** * @return string */ private function getNodeId32() { $this->load(); return $this->nodeId32; } /** * @return string */ private function getNodeId48() { $this->load(); return $this->nodeId48; } /** * Delete all cache files that have been created (T46850) * * This is a cleanup method primarily meant to be used from unit tests to * avoid polluting the local filesystem. If used outside of a unit test * environment it should be used with caution as it may destroy state saved * in the files. * * @see unitTestTearDown * @codeCoverageIgnore */ private function deleteCacheFiles() { foreach ( $this->fileHandles as $path => $handle ) { if ( $handle !== null ) { fclose( $handle ); } if ( is_file( $path ) ) { unlink( $path ); } unset( $this->fileHandles[$path] ); } if ( is_file( $this->nodeIdFile ) ) { unlink( $this->nodeIdFile ); } } /** * Cleanup resources when tearing down after a unit test (T46850) * * This is a cleanup method primarily meant to be used from unit tests to * avoid polluting the local filesystem. If used outside of a unit test * environment it should be used with caution as it may destroy state saved * in the files. * * @internal For use by unit tests * @see deleteCacheFiles * @codeCoverageIgnore */ public function unitTestTearDown() { $this->deleteCacheFiles(); } public function __destruct() { // @phan-suppress-next-line PhanPluginUseReturnValueInternalKnown array_map( 'fclose', array_filter( $this->fileHandles ) ); } } PK ! �� kn n ArrayUtils.phpnu �Iw�� <?php /** * Methods to play with arrays. * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file */ /** * A collection of static methods to play with arrays. * * @since 1.21 */ class ArrayUtils { /** * Sort the given array in a pseudo-random order which depends only on the * given key and each element value in $array. This is typically used for load * balancing between servers each with a local cache. * * Keys are preserved. The input array is modified in place. * * Note: Benchmarking on PHP 5.3 and 5.4 indicates that for small * strings, md5() is only 10% slower than hash('joaat',...) etc., * since the function call overhead dominates. So there's not much * justification for breaking compatibility with installations * compiled with ./configure --disable-hash. * * @param array &$array Array to sort * @param string $key * @param string $separator A separator used to delimit the array elements and the * key. This can be chosen to provide backwards compatibility with * various consistent hash implementations that existed before this * function was introduced. */ public static function consistentHashSort( &$array, $key, $separator = "\000" ) { $hashes = []; foreach ( $array as $elt ) { $hashes[$elt] = md5( $elt . $separator . $key ); } uasort( $array, static function ( $a, $b ) use ( $hashes ) { return strcmp( $hashes[$a], $hashes[$b] ); } ); } /** * Given an array of non-normalised probabilities, this function will select * an element and return the appropriate key * * @param array $weights * @return int|string|false */ public static function pickRandom( $weights ) { if ( !is_array( $weights ) || count( $weights ) == 0 ) { return false; } $sum = array_sum( $weights ); if ( $sum == 0 ) { # No loads on any of them # In previous versions, this triggered an unweighted random selection, # but this feature has been removed as of April 2006 to allow for strict # separation of query groups. return false; } $max = mt_getrandmax(); $rand = mt_rand( 0, $max ) / $max * $sum; $sum = 0; foreach ( $weights as $i => $w ) { $sum += $w; # Do not return keys if they have 0 weight. # Note that the "all 0 weight" case is handed above if ( $w > 0 && $sum >= $rand ) { break; } } return $i; } /** * Do a binary search, and return the index of the largest item that sorts * less than or equal to the target value. * * @since 1.23 * * @param callable $valueCallback A function to call to get the value with * a given array index. * @param int $valueCount The number of items accessible via $valueCallback, * indexed from 0 to $valueCount - 1 * @param callable $comparisonCallback A callback to compare two values, returning * -1, 0 or 1 in the style of strcmp(). * @param mixed $target The target value to find. * * @return int|bool The item index of the lower bound, or false if the target value * sorts before all items. */ public static function findLowerBound( $valueCallback, $valueCount, $comparisonCallback, $target ) { if ( $valueCount === 0 ) { return false; } $min = 0; $max = $valueCount; do { $mid = $min + ( ( $max - $min ) >> 1 ); $item = $valueCallback( $mid ); $comparison = $comparisonCallback( $target, $item ); if ( $comparison > 0 ) { $min = $mid; } elseif ( $comparison == 0 ) { $min = $mid; break; } else { $max = $mid; } } while ( $min < $max - 1 ); if ( $min == 0 ) { $item = $valueCallback( $min ); $comparison = $comparisonCallback( $target, $item ); if ( $comparison < 0 ) { // Before the first item return false; } } return $min; } /** * Do array_diff_assoc() on multi-dimensional arrays. * * Note: empty arrays are removed. * * @since 1.23 * * @param array $array1 The array to compare from * @param array ...$arrays More arrays to compare against * @return array An array containing all the values from array1 * that are not present in any of the other arrays. */ public static function arrayDiffAssocRecursive( $array1, ...$arrays ) { $ret = []; foreach ( $array1 as $key => $value ) { if ( is_array( $value ) ) { $args = [ $value ]; foreach ( $arrays as $array ) { if ( isset( $array[$key] ) ) { $args[] = $array[$key]; } } $valueret = self::arrayDiffAssocRecursive( ...$args ); if ( count( $valueret ) ) { $ret[$key] = $valueret; } } else { foreach ( $arrays as $array ) { if ( isset( $array[$key] ) && $array[$key] === $value ) { continue 2; } } $ret[$key] = $value; } } return $ret; } /** * Make an array consisting of every combination of the elements of the * input arrays. Each element of the output array is an array with a number * of elements equal to the number of input parameters. * * In mathematical terms, this is an n-ary Cartesian product. * * For example, ArrayUtils::cartesianProduct( [ 1, 2 ], [ 'a', 'b' ] ) * produces [ [ 1, 'a' ], [ 1, 'b' ], [ 2, 'a' ], [ 2, 'b' ] ] * * If any of the input arrays is empty, the result is the empty array []. * This is in keeping with the mathematical definition. * * If no parameters are given, the result is also the empty array. * * The array keys are ignored. This implementation uses the internal * pointers of the input arrays to keep track of the current position * without referring to the keys. * * @since 1.35 * * @param array ...$inputArrays * @return array */ public static function cartesianProduct( ...$inputArrays ) { $numInputs = count( $inputArrays ); if ( $numInputs === 0 ) { return []; } // Reset the internal pointers foreach ( $inputArrays as &$inputArray ) { if ( !count( $inputArray ) ) { return []; } reset( $inputArray ); } unset( $inputArray ); $outputArrays = []; $done = false; while ( !$done ) { // Construct the output array element $element = []; foreach ( $inputArrays as $inputArray ) { $element[] = current( $inputArray ); } $outputArrays[] = $element; // Increment the pointers starting from the least significant. // If the least significant rolls over back to the start of the // array, continue with the next most significant, and so on until // that stops happening. If all pointers roll over, we are done. $done = true; for ( $paramIndex = $numInputs - 1; $paramIndex >= 0; $paramIndex-- ) { next( $inputArrays[$paramIndex] ); if ( key( $inputArrays[$paramIndex] ) === null ) { reset( $inputArrays[$paramIndex] ); // continue } else { $done = false; break; } } } return $outputArrays; } } PK ! b�<. . HtmlArmor.phpnu �Iw�� <?php /** * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file * @license GPL-2.0-or-later * @author Kunal Mehta <legoktm@debian.org> */ /** * Marks HTML that shouldn't be escaped * * @newable * * @since 1.28 */ class HtmlArmor { /** * @var string|null */ private $value; /** * @stable to call * * @param string|null $value * @param-taint $value exec_html */ public function __construct( $value ) { $this->value = $value; } /** * Provide a string or HtmlArmor object * and get safe HTML back * * @param string|HtmlArmor $input * @return string|null safe for usage in HTML, or null * if the HtmlArmor instance was wrapping null. */ public static function getHtml( $input ) { if ( $input instanceof HtmlArmor ) { return $input->value; } else { return htmlspecialchars( $input, ENT_QUOTES ); } } } PK ! R�y� � ReverseArrayIterator.phpnu �Iw�� <?php /** * Convenience class for iterating over an array in reverse order. * * This program is free software; you can redistribute it and/or modify * it under the terms of the GNU General Public License as published by * the Free Software Foundation; either version 2 of the License, or * (at your option) any later version. * * This program is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * GNU General Public License for more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. * http://www.gnu.org/copyleft/gpl.html * * @file * @since 1.27 */ /** * Convenience class for iterating over an array in reverse order. * * @since 1.27 */ class ReverseArrayIterator implements Iterator, Countable { /** @var array */ protected $array; /** * Creates an iterator which will visit the keys in $array in * reverse order. If given an object, will visit the properties * of the object in reverse order. (Note that the default order * for PHP arrays and objects is declaration/assignment order.) * * @phpcs:ignore MediaWiki.Commenting.FunctionComment.ObjectTypeHintParam * @param array|object $array */ public function __construct( $array = [] ) { if ( is_array( $array ) ) { $this->array = $array; } elseif ( is_object( $array ) ) { $this->array = get_object_vars( $array ); } else { throw new InvalidArgumentException( __METHOD__ . ' requires an array or object' ); } $this->rewind(); } #[\ReturnTypeWillChange] public function current() { return current( $this->array ); } #[\ReturnTypeWillChange] public function key() { return key( $this->array ); } public function next(): void { prev( $this->array ); } public function rewind(): void { end( $this->array ); } public function valid(): bool { return key( $this->array ) !== null; } public function count(): int { return count( $this->array ); } } PK ! >���� � telemetry/README.mdnu �Iw�� PK ! ���3� � telemetry/Tracer.phpnu �Iw�� PK ! �;j j , telemetry/SpanContext.phpnu �Iw�� PK ! �#(|K K � telemetry/TracerState.phpnu �Iw�� PK ! ��H s' telemetry/TracerInterface.phpnu �Iw�� PK ! (��A� � �. telemetry/NoopSpan.phpnu �Iw�� PK ! J���1 1 �2 telemetry/ExporterInterface.phpnu �Iw�� PK ! X�M�� � P4 telemetry/OtlpHttpExporter.phpnu �Iw�� PK ! �.��� � �> telemetry/OtlpSerializer.phpnu �Iw�� PK ! ��*� �B telemetry/SamplerInterface.phpnu �Iw�� PK ! ���� � �D telemetry/Clock.phpnu �Iw�� PK ! �d_27 7 K telemetry/SpanInterface.phpnu �Iw�� PK ! q3nJ� � �V telemetry/Span.phpnu �Iw�� PK ! ��� � � �_ telemetry/NoopTracer.phpnu �Iw�� PK ! �.%y� � " �c telemetry/ProbabilisticSampler.phpnu �Iw�� PK ! ��� m m ~g ReplacementArray.phpnu �Iw�� PK ! �3� � /q MemoizedCallable.phpnu �Iw�� PK ! [2�C\& \& ! %� lockmanager/QuorumLockManager.phpnu �Iw�� PK ! ��o� ҩ lockmanager/ScopedLock.phpnu �Iw�� PK ! ���)S! S! "� lockmanager/RedisLockManager.phpnu �Iw�� PK ! -м�o- o- �� lockmanager/MemcLockManager.phpnu �Iw�� PK ! �)� � � lockmanager/FSLockManager.phpnu �Iw�� PK ! m��/� � �# lockmanager/NullLockManager.phpnu �Iw�� PK ! ܛy" y" x* lockmanager/LockManager.phpnu �Iw�� PK ! �W��� � <M objectcache/README.mdnu �Iw�� PK ! 3�T� � TZ objectcache/HashBagOStuff.phpnu �Iw�� PK ! �tu��C �C km objectcache/RedisBagOStuff.phpnu �Iw�� PK ! � � � K� objectcache/APCUBagOStuff.phpnu �Iw�� PK ! �!m�Jq Jq )� objectcache/BagOStuff.phpnu �Iw�� PK ! A�8�A� A� % �5 objectcache/utils/MemcachedClient.phpnu �Iw�� PK ! ���# # & R� objectcache/utils/StorageAwareness.phpnu �Iw�� PK ! 5p� n n ) �� objectcache/utils/ExpirationAwareness.phpnu �Iw�� PK ! �� �V" V" " �� objectcache/utils/RedisConnRef.phpnu �Iw�� PK ! �:��4 �4 ) :� objectcache/utils/RedisConnectionPool.phpnu �Iw�� PK ! ���4 4 �" objectcache/WANObjectCache.phpnu �Iw�� PK ! eA��� � * objectcache/CachedBagOStuff.phpnu �Iw�� PK ! �zJv@ @ " D objectcache/MemcachedBagOStuff.phpnu �Iw�� PK ! wj�i� � �\ objectcache/IStoreKeyEncoder.phpnu �Iw�� PK ! j2O%� � % �_ objectcache/MemcachedPhpBagOStuff.phpnu �Iw�� PK ! ^t��d� d� ' �x objectcache/MediumSpecificBagOStuff.phpnu �Iw�� PK ! �bt@ @ & { objectcache/MemcachedPeclBagOStuff.phpnu �Iw�� PK ! e�$v�3 �3 # �M objectcache/MultiWriteBagOStuff.phpnu �Iw�� PK ! `�w� � � objectcache/EmptyBagOStuff.phpnu �Iw�� PK ! ���eV, V, � objectcache/RESTBagOStuff.phpnu �Iw�� PK ! �E1� 3 �� objectcache/serialized/SerializedValueContainer.phpnu �Iw�� PK ! ~�Aww w � NonSerializableTrait.phpnu �Iw�� PK ! D�~ �� Stats/Metrics/GaugeMetric.phpnu �Iw�� PK ! �%�� � � Stats/Metrics/NullMetric.phpnu �Iw�� PK ! )�8�� � �� Stats/Metrics/BaseMetric.phpnu �Iw�� PK ! 2�1& & ! *� Stats/Metrics/MetricInterface.phpnu �Iw�� PK ! �6?�l l �� Stats/Metrics/MetricTrait.phpnu �Iw�� PK ! ��� � Z� Stats/Metrics/CounterMetric.phpnu �Iw�� PK ! �XT� � S Stats/Metrics/TimingMetric.phpnu �Iw�� PK ! V�6�� � % f Stats/Metrics/BaseMetricInterface.phpnu �Iw�� PK ! ۸/U� � �" Stats/NullStatsdDataFactory.phpnu �Iw�� PK ! U�wM �. Stats/SamplingStatsdClient.phpnu �Iw�� PK ! ���� � 2B Stats/OutputFormats.phpnu �Iw�� PK ! ��(�> > 5O Stats/StatsdAwareInterface.phpnu �Iw�� PK ! l�2aq q �Q Stats/StatsCache.phpnu �Iw�� PK ! ��p! v] Stats/Emitters/NullEmitter.phpnu �Iw�� PK ! ��x� �a Stats/Emitters/UDPEmitter.phpnu �Iw�� PK ! ��U� � # q Stats/Emitters/EmitterInterface.phpnu �Iw�� PK ! ��� � $ v Stats/BufferingStatsdDataFactory.phpnu �Iw�� PK ! �pz)� � F� Stats/Sample.phpnu �Iw�� PK ! ��x`e e % Q� Stats/IBufferingStatsdDataFactory.phpnu �Iw�� PK ! �E�� � � Stats/StatsFactory.phpnu �Iw�� PK ! ZF"� E� Stats/StatsUtils.phpnu �Iw�� PK ! d�^�� � 2 �� Stats/Exceptions/InvalidConfigurationException.phpnu �Iw�� PK ! eI�� . �� Stats/Exceptions/IllegalOperationException.phpnu �Iw�� PK ! �d�7� � / �� Stats/Exceptions/UnsupportedFormatException.phpnu �Iw�� PK ! �� W W ) �� Stats/PrefixingStatsdDataFactoryProxy.phpnu �Iw�� PK ! �Y�ŭ � ' �� Stats/Formatters/FormatterInterface.phpnu �Iw�� PK ! �pHz: : ' �� Stats/Formatters/DogStatsdFormatter.phpnu �Iw�� PK ! .��s s " � Stats/Formatters/NullFormatter.phpnu �Iw�� PK ! �\�G $ �� Stats/Formatters/StatsdFormatter.phpnu �Iw�� PK ! �����w �w ! ;� ParamValidator/ParamValidator.phpnu �Iw�� PK ! �<�� � (o ParamValidator/README.mdnu �Iw�� PK ! ��`� $ ?v ParamValidator/Util/UploadedFile.phpnu �Iw�� PK ! �v�� � * �� ParamValidator/Util/UploadedFileStream.phpnu �Iw�� PK ! zɎL L & �� ParamValidator/ValidationException.phpnu �Iw�� PK ! Ê�� � [� ParamValidator/Callbacks.phpnu �Iw�� PK ! ��� , , +� ParamValidator/TypeDef.phpnu �Iw�� PK ! � ѹ � $ �� ParamValidator/TypeDef/StringDef.phpnu �Iw�� PK ! ���%� � % �� ParamValidator/TypeDef/BooleanDef.phpnu �Iw�� PK ! &M�R� � % �� ParamValidator/TypeDef/NumericDef.phpnu �Iw�� PK ! �Q�E % � ParamValidator/TypeDef/IntegerDef.phpnu �Iw�� PK ! � �� � # � ParamValidator/TypeDef/FloatDef.phpnu �Iw�� PK ! 䏎ĉ � - " ParamValidator/TypeDef/PresenceBooleanDef.phpnu �Iw�� PK ! �bt� $ �+ ParamValidator/TypeDef/ExpiryDef.phpnu �Iw�� PK ! �!iX� � " ]B ParamValidator/TypeDef/EnumDef.phpnu �Iw�� PK ! )�Q� � & |` ParamValidator/TypeDef/PasswordDef.phpnu �Iw�� PK ! S���� � # fd ParamValidator/TypeDef/LimitDef.phpnu �Iw�� PK ! K��� � ' ;m ParamValidator/TypeDef/TimestampDef.phpnu �Iw�� PK ! ����� � $ [� ParamValidator/TypeDef/UploadDef.phpnu �Iw�� PK ! � �(4 4 " I� ParamValidator/SimpleCallbacks.phpnu �Iw�� PK ! G��a�( �( Ϝ ParamValidator/i18n/mk.jsonnu �Iw�� PK ! .��1�& �& � ParamValidator/i18n/uk.jsonnu �Iw�� PK ! �z��� � �� ParamValidator/i18n/ia.jsonnu �Iw�� PK ! {��� � ParamValidator/i18n/ja.jsonnu �Iw�� PK ! F��) ) �% ParamValidator/i18n/en.jsonnu �Iw�� PK ! �w � � f@ ParamValidator/i18n/lb.jsonnu �Iw�� PK ! c�)�* * JF ParamValidator/i18n/ru.jsonnu �Iw�� PK ! !�!�D D �p ParamValidator/i18n/tr.jsonnu �Iw�� PK ! ��2A~ ~ ;� ParamValidator/i18n/fr.jsonnu �Iw�� PK ! (x�\?. ?. � ParamValidator/i18n/qqq.jsonnu �Iw�� PK ! *w�� �� ParamValidator/i18n/br.jsonnu �Iw�� PK ! ڰ�� �� ParamValidator/i18n/pt-br.jsonnu �Iw�� PK ! b+��c c 9 ParamValidator/i18n/ca.jsonnu �Iw�� PK ! FO�i i � ParamValidator/i18n/zh-hans.jsonnu �Iw�� PK ! �R}H H �" ParamValidator/i18n/nl.jsonnu �Iw�� PK ! I��f f 3@ ParamValidator/i18n/gl.jsonnu �Iw�� PK ! ʚM�� � �] ParamValidator/i18n/he.jsonnu �Iw�� PK ! �X��G G . ParamValidator/i18n/zh-hant.jsonnu �Iw�� PK ! �B&� � Ř ParamValidator/i18n/es.jsonnu �Iw�� PK ! ��#�E E � ParamValidator/i18n/sl.jsonnu �Iw�� PK ! N�� � � �� ParamValidator/i18n/nb.jsonnu �Iw�� PK ! D�"� � x� ParamValidator/i18n/fa.jsonnu �Iw�� PK ! b=�� � �� ParamValidator/i18n/ur.jsonnu �Iw�� PK ! E[ �u! u! �� ParamValidator/i18n/ar.jsonnu �Iw�� PK ! ��k� � � ParamValidator/i18n/pl.jsonnu �Iw�� PK ! C�h�` ` N( ParamValidator/i18n/ban.jsonnu �Iw�� PK ! f��� �+ ParamValidator/i18n/ce.jsonnu �Iw�� PK ! ޗ� P4 ParamValidator/i18n/de.jsonnu �Iw�� PK ! {Jؒ� � �Q ParamValidator/i18n/pt.jsonnu �Iw�� PK ! �Nص� � �k ParamValidator/i18n/io.jsonnu �Iw�� PK ! �A9ß � }q ParamValidator/i18n/diq.jsonnu �Iw�� PK ! ��' � � hv ParamValidator/i18n/ko.jsonnu �Iw�� PK ! H1a�e e �� ParamValidator/i18n/sv.jsonnu �Iw�� PK ! �/��� � :� ParamValidator/i18n/en-gb.jsonnu �Iw�� PK ! �� � � �� ParamValidator/i18n/hu.jsonnu �Iw�� PK ! ��� � k� HttpStatus.phpnu �Iw�� PK ! ���y� � �� composer/ComposerJson.phpnu �Iw�� PK ! �#�7 s� composer/ComposerLock.phpnu �Iw�� PK ! [�;u� � �� composer/ComposerInstalled.phpnu �Iw�� PK ! � �(/ (/ �� MapCacheLRU.phpnu �Iw�� PK ! �7��/ �/ K StringUtils.phpnu �Iw�� PK ! ���^ ^ a; CookieJar.phpnu �Iw�� PK ! !h#] ] �F StaticArrayWriter.phpnu �Iw�� PK ! � ��� � �W DebugInfo/Placeholder.phpnu �Iw�� PK ! Wa� � � �Y DebugInfo/AnnotationReader.phpnu �Iw�� PK ! �WX X �] DebugInfo/DebugInfoTrait.phpnu �Iw�� PK ! �j Z� � O_ DebugInfo/DumpUtils.phpnu �Iw�� PK ! �VP& & 8d WRStats/README.mdnu �Iw�� PK ! c%�"H H �t WRStats/WRStatsFactory.phpnu �Iw�� PK ! @��� � 1� WRStats/WRStatsRateLimiter.phpnu �Iw�� PK ! �0� � � � WRStats/LocalEntityKey.phpnu �Iw�� PK ! ��v � *� WRStats/WRStatsWriter.phpnu �Iw�� PK ! �:�� � �� WRStats/EntityKey.phpnu �Iw�� PK ! R�] � WRStats/LimitBatch.phpnu �Iw�� PK ! '�[r r u� WRStats/RatePromise.phpnu �Iw�� PK ! vѯV V .� WRStats/MetricSpec.phpnu �Iw�� PK ! �pN�4 4 �� WRStats/LimitCondition.phpnu �Iw�� PK ! =NV�~! ~! H� WRStats/WRStatsReader.phpnu �Iw�� PK ! (��N� � � WRStats/GlobalEntityKey.phpnu �Iw�� PK ! ْ�� "� WRStats/TimeRange.phpnu �Iw�� PK ! ��ɐ � �� WRStats/BagOStuffStatsStore.phpnu �Iw�� PK ! K�c f� WRStats/SequenceSpec.phpnu �Iw�� PK ! K� '� � � WRStats/LimitOperation.phpnu �Iw�� PK ! ��� � WRStats/StatsStore.phpnu �Iw�� PK ! �f`xZ Z i WRStats/ArrayStatsStore.phpnu �Iw�� PK ! 6� � WRStats/WRStatsError.phpnu �Iw�� PK ! 9M��> > � WRStats/LimitOperationResult.phpnu �Iw�� PK ! M��� � � WRStats/LimitBatchResult.phpnu �Iw�� PK ! ڸ��; ; � Emptiable.phpnu �Iw�� PK ! ��t7 7 http/HttpAcceptParser.phpnu �Iw�� PK ! �.��$ $ " � http/TelemetryHeadersInterface.phpnu �Iw�� PK ! �>�w �w ! http/MultiHttpClient.phpnu �Iw�� PK ! p�7�� � � http/HttpAcceptNegotiator.phpnu �Iw�� PK ! 风eE E # � rdbms/lbfactory/LBFactorySimple.phpnu �Iw�� PK ! E�4�= �= " �� rdbms/lbfactory/LBFactoryMulti.phpnu �Iw�� PK ! ��� � ' � rdbms/lbfactory/IConnectionProvider.phpnu �Iw�� PK ! L�qR� � # rdbms/lbfactory/LBFactorySingle.phpnu �Iw�� PK ! w��Y �Y rdbms/lbfactory/LBFactory.phpnu �Iw�� PK ! p!9�J J Bs rdbms/lbfactory/ILBFactory.phpnu �Iw�� PK ! �v� �� rdbms/ConfiguredReadOnlyMode.phpnu �Iw�� PK ! *��"� � $ � rdbms/expression/ExpressionGroup.phpnu �Iw�� PK ! Y@/�� � % F� rdbms/expression/RawSQLExpression.phpnu �Iw�� PK ! =��p� � ' '� rdbms/expression/AndExpressionGroup.phpnu �Iw�� PK ! #��/ / -� rdbms/expression/IExpression.phpnu �Iw�� PK ! h�?�B B �� rdbms/expression/Expression.phpnu �Iw�� PK ! K�=" =� rdbms/expression/LikeValue.phpnu �Iw�� PK ! �� � & �� rdbms/expression/OrExpressionGroup.phpnu �Iw�� PK ! ]9� � � rdbms/ReadOnlyMode.phpnu �Iw�� PK ! �5��T T z rdbms/defines.phpnu �Iw�� PK ! M+� 2 2 rdbms/ServerInfo.phpnu �Iw�� PK ! F�2� � ' �" rdbms/exception/DBSessionStateError.phpnu �Iw�� PK ! *k�� # i& rdbms/exception/DBLanguageError.phpnu �Iw�� PK ! L;��� � , �* rdbms/exception/DBQueryDisconnectedError.phpnu �Iw�� PK ! '�ȁ� � + �0 rdbms/exception/DBTransactionStateError.phpnu �Iw�� PK ! ��ĉv v & �4 rdbms/exception/DBTransactionError.phpnu �Iw�� PK ! ���� � * �; rdbms/exception/DBTransactionSizeError.phpnu �Iw�� PK ! �ZI� � �? rdbms/exception/DBError.phpnu �Iw�� PK ! 'Qq� � ' �F rdbms/exception/DBReadOnlyRoleError.phpnu �Iw�� PK ! ߘ��� � # K rdbms/exception/DBReadOnlyError.phpnu �Iw�� PK ! �9 �� � % �N rdbms/exception/DBConnectionError.phpnu �Iw�� PK ! ;��; ; ! $T rdbms/exception/DBAccessError.phpnu �Iw�� PK ! �鮟E E �X rdbms/exception/DBQueryError.phpnu �Iw�� PK ! &pi i # E_ rdbms/exception/DBExpectedError.phpnu �Iw�� PK ! wJr� � % f rdbms/exception/DBUnexpectedError.phpnu �Iw�� PK ! dX�D� � * �i rdbms/exception/DBReplicationWaitError.phpnu �Iw�� PK ! �| � � ' �m rdbms/exception/DBQueryTimeoutError.phpnu �Iw�� PK ! ��Z�c �c t rdbms/platform/ISQLPlatform.phpnu �Iw�� PK ! �e�[; ; ! ,� rdbms/platform/SqlitePlatform.phpnu �Iw�� PK ! �|a� �� �� rdbms/platform/SQLPlatform.phpnu �Iw�� PK ! F`�p p �� rdbms/platform/MySQLPlatform.phpnu �Iw�� PK ! %�" �" # b� rdbms/platform/PostgresPlatform.phpnu �Iw�� PK ! 4�"p�, �, ! n rdbms/loadmonitor/LoadMonitor.phpnu �Iw�� PK ! R�:� � % �A rdbms/loadmonitor/LoadMonitorNull.phpnu �Iw�� PK ! �J9� � " �E rdbms/loadmonitor/ILoadMonitor.phpnu �Iw�� PK ! E��` ` - N rdbms/connectionmanager/ConnectionManager.phpnu �Iw�� PK ! q���� � > �Y rdbms/connectionmanager/SessionConsistentConnectionManager.phpnu �Iw�� PK ! ���� � 4 �e rdbms/database/resultwrapper/MysqliResultWrapper.phpnu �Iw�� PK ! ��D D / �q rdbms/database/resultwrapper/IResultWrapper.phpnu �Iw�� PK ! �3͂ � 2 | rdbms/database/resultwrapper/FakeResultWrapper.phpnu �Iw�� PK ! �kOi i 4 c� rdbms/database/resultwrapper/SqliteResultWrapper.phpnu �Iw�� PK ! -~��? ? . 0� rdbms/database/resultwrapper/ResultWrapper.phpnu �Iw�� PK ! 4tt� � 6 ͖ rdbms/database/resultwrapper/PostgresResultWrapper.phpnu �Iw�� PK ! ��H� k k $ � rdbms/database/IReadableDatabase.phpnu �Iw�� PK ! {'yf yf � rdbms/database/DatabaseMySQL.phpnu �Iw�� PK ! h]�� � ( Ms rdbms/database/IMaintainableDatabase.phpnu �Iw�� PK ! 0{_xl l z� rdbms/database/DatabaseFlags.phpnu �Iw�� PK ! ٯBM�+ �+ + 6� rdbms/database/position/MySQLPrimaryPos.phpnu �Iw�� PK ! J�+T� � ( "� rdbms/database/position/DBPrimaryPos.phpnu �Iw�� PK ! ��4� � ]� rdbms/database/Database.phpnu �Iw�� PK ! �#�冻 �� � rdbms/database/IDatabase.phpnu �Iw�� PK ! (vUos s `; rdbms/database/DbQuoter.phpnu �Iw�� PK ! p�_�k k ( = rdbms/database/domain/DatabaseDomain.phpnu �Iw�� PK ! Ê�� � ! �X rdbms/database/IDatabaseFlags.phpnu �Iw�� PK ! �R��s s ) �e rdbms/database/QueryBuilderFromRawSql.phpnu �Iw�� PK ! ��q{ { . �� rdbms/database/utils/TransactionIdentifier.phpnu �Iw�� PK ! �nߟ � $ i� rdbms/database/utils/QueryStatus.phpnu �Iw�� PK ! (�k�� � 0 \� rdbms/database/utils/AtomicSectionIdentifier.phpnu �Iw�� PK ! �/� p p , �� rdbms/database/utils/CriticalSessionInfo.phpnu �Iw�� PK ! ��k�W W ' `� rdbms/database/utils/GeneralizedSql.phpnu �Iw�� PK ! ���IP P & � rdbms/database/utils/TempTableInfo.phpnu �Iw�� PK ! o��Yz Yz # �� rdbms/database/DatabasePostgres.phpnu �Iw�� PK ! �Z�0�~ �~ % ` rdbms/database/TransactionManager.phpnu �Iw�� PK ! Z�"/�* �* " U� rdbms/database/DatabaseFactory.phpnu �Iw�� PK ! �DeB B 7 v� rdbms/database/replication/MysqlReplicationReporter.phpnu �Iw�� PK ! �� �� � 2 � rdbms/database/replication/ReplicationReporter.phpnu �Iw�� PK ! CζDg g ! ?" rdbms/database/DatabaseSqlite.phpnu �Iw�� PK ! b���j �j �� rdbms/database/DBConnRef.phpnu �Iw�� PK ! t[�@. . �� rdbms/database/Query.phpnu �Iw�� PK ! ��� $ rdbms/database/IDatabaseForOwner.phpnu �Iw�� PK ! ���D D s rdbms/TransactionProfiler.phpnu �Iw�� PK ! �jؼ� � �` rdbms/DBAccessObjectUtils.phpnu �Iw�� PK ! ��xT�b �b �n rdbms/ChronologyProtector.phpnu �Iw�� PK ! | ��� � $ �� rdbms/querybuilder/JoinGroupBase.phpnu �Iw�� PK ! ����( �( ) �� rdbms/querybuilder/UpdateQueryBuilder.phpnu �Iw�� PK ! 4�d�� � ) � rdbms/querybuilder/DeleteQueryBuilder.phpnu �Iw�� PK ! �۫ � ( . rdbms/querybuilder/UnionQueryBuilder.phpnu �Iw�� PK ! �F��{ { * H rdbms/querybuilder/ReplaceQueryBuilder.phpnu �Iw�� PK ! @u�Ұj �j ) �^ rdbms/querybuilder/SelectQueryBuilder.phpnu �Iw�� PK ! p��� � �� rdbms/querybuilder/JoinGroup.phpnu �Iw�� PK ! �B�' ' ) � rdbms/querybuilder/InsertQueryBuilder.phpnu �Iw�� PK ! ʎ�� � + �� rdbms/loadbalancer/LoadBalancerDisabled.phpnu �Iw�� PK ! `O��� � # � rdbms/loadbalancer/LoadBalancer.phpnu �Iw�� PK ! �� �Q' Q' , � rdbms/loadbalancer/ILoadBalancerForOwner.phpnu �Iw�� PK ! NH#wX wX $ S> rdbms/loadbalancer/ILoadBalancer.phpnu �Iw�� PK ! �y��_ _ ) � rdbms/loadbalancer/LoadBalancerSingle.phpnu �Iw�� PK ! pֱ]l l ֣ rdbms/IDBAccessObject.phpnu �Iw�� PK ! m$� � �� rdbms/encasing/IBlob.phpnu �Iw�� PK ! O�Bw@ @ �� rdbms/encasing/Blob.phpnu �Iw�� PK ! 0��?\ \ ?� rdbms/encasing/PostgresBlob.phpnu �Iw�� PK ! M�� � � rdbms/encasing/Subquery.phpnu �Iw�� PK ! ��6K K κ rdbms/encasing/LikeMatch.phpnu �Iw�� PK ! ��G� � e� rdbms/encasing/RawSQLValue.phpnu �Iw�� PK ! l���T T �� rdbms/ChangedTablesTracker.phpnu �Iw�� PK ! Vu*� � ;� rdbms/field/MySQLField.phpnu �Iw�� PK ! �ՂV6 6 � rdbms/field/SQLiteField.phpnu �Iw�� PK ! ��> �� rdbms/field/Field.phpnu �Iw�� PK ! V}�j j �� rdbms/field/PostgresField.phpnu �Iw�� PK ! �i� * �� rdbms/dbal/DoctrineAbstractSchemaTrait.phpnu �Iw�� PK ! Z�q q �� rdbms/dbal/EnumType.phpnu �Iw�� PK ! �g�� � �� rdbms/dbal/MWMySQLPlatform.phpnu �Iw�� PK ! #R 9� � * �� rdbms/dbal/DoctrineSchemaChangeBuilder.phpnu �Iw�� PK ! z~� � �� rdbms/dbal/TinyIntType.phpnu �Iw�� PK ! �i�9 9 o rdbms/dbal/SchemaBuilder.phpnu �Iw�� PK ! �"*� " � rdbms/dbal/SchemaChangeBuilder.phpnu �Iw�� PK ! z���l l $ e rdbms/dbal/DoctrineSchemaBuilder.phpnu �Iw�� PK ! R[z� � + % rdbms/dbal/DoctrineSchemaBuilderFactory.phpnu �Iw�� PK ! �@$w� � rdbms/dbal/TimestampType.phpnu �Iw�� PK ! s `� # � rdbms/dbal/MWPostgreSqlPlatform.phpnu �Iw�� PK ! �[Qy2 2 Q" GhostFieldAccessTrait.phpnu �Iw�� PK ! (ʧ�� � �. UDPTransport.phpnu �Iw�� PK ! �n�c8 8 �; HashRing.phpnu �Iw�� PK ! 5go8 $t Timing.phpnu �Iw�� PK ! ���� � j� MappedIterator.phpnu �Iw�� PK ! �10�� � _� mime/defines.phpnu �Iw�� PK ! 3>ش�< �< t� mime/XmlTypeCheck.phpnu �Iw�� PK ! �b n+ n+ w� mime/MSCompoundFileReader.phpnu �Iw�� PK ! 6�IMl l 2 mime/MimeMapMinimal.phpnu �Iw�� PK ! �4�*L *L � mime/MimeMap.phpnu �Iw�� PK ! � #��� �� Ol mime/MimeAnalyzer.phpnu �Iw�� PK ! `7>�(B (B &� StatusValue.phpnu �Iw�� PK ! �vj �; Diff/TableDiffFormatter.phpnu �Iw�� PK ! �!L� �[ Diff/Diff.phpnu �Iw�� PK ! �-Z� � 'k Diff/DiffOp.phpnu �Iw�� PK ! ��%�[ [ x Diff/DiffFormatter.phpnu �Iw�� PK ! �tef f �� Diff/ArrayDiffFormatter.phpnu �Iw�� PK ! ���� � _� Diff/WordLevelDiff.phpnu �Iw�� PK ! �1{I� � D� Diff/WordAccumulator.phpnu �Iw�� PK ! k��R� � O� Diff/UnifiedDiffFormatter.phpnu �Iw�� PK ! [�'�4 4 A� Diff/DiffOpAdd.phpnu �Iw�� PK ! !� � �� Diff/ComplexityException.phpnu �Iw�� PK ! ���;� � �� Diff/DiffOpChange.phpnu �Iw�� PK ! ��\OhV hV t� Diff/DiffEngine.phpnu �Iw�� PK ! � � 9 9 ' Diff/DiffOpDelete.phpnu �Iw�� PK ! �ۦ�� � �- Diff/DiffOpCopy.phpnu �Iw�� PK ! ��{ { �4 UnpackFailedException.phpnu �Iw�� PK ! �.�p� � �5 iterators/IteratorDecorator.phpnu �Iw�� PK ! ��2 " �< iterators/NotRecursiveIterator.phpnu �Iw�� PK ! E2 2 :B DnsSrvDiscoverer.phpnu �Iw�� PK ! W�� � �P READMEnu �Iw�� PK ! b ��W W ! �Q eventrelayer/EventRelayerNull.phpnu �Iw�� PK ! �ͨb� � " {V eventrelayer/EventRelayerGroup.phpnu �Iw�� PK ! �}�� � m^ eventrelayer/EventRelayer.phpnu �Iw�� PK ! ��u u �f RiffExtractor.phpnu �Iw�� PK ! ۧ(� � Zq Cookie.phpnu �Iw�� PK ! �>�H <� filebackend/FileBackendStore.phpnu �Iw�� PK ! �",��� �� ��! filebackend/FSFileBackend.phpnu �Iw�� PK ! �9�_" " �*" filebackend/fsfile/FSFile.phpnu �Iw�� PK ! ��P(� � ( �A" filebackend/fsfile/TempFSFileFactory.phpnu �Iw�� PK ! rA� � ! 6H" filebackend/fsfile/TempFSFile.phpnu �Iw�� PK ! ���` ` "`" filebackend/SwiftFileBackend.phpnu �Iw�� PK ! ���^ ^ ! �n# filebackend/MemoryFileBackend.phpnu �Iw�� PK ! ��ܡ� � . ��# filebackend/fileophandle/SwiftFileOpHandle.phpnu �Iw�� PK ! :�*� � + ��# filebackend/fileophandle/FSFileOpHandle.phpnu �Iw�� PK ! ��j�z z 5 �# filebackend/fileophandle/FileBackendStoreOpHandle.phpnu �Iw�� PK ! �Z��� � ӥ# filebackend/FileBackend.phpnu �Iw�� PK ! �as�x �x % �$ filebackend/FileBackendMultiWrite.phpnu �Iw�� PK ! �N�ڄ$ �$ �!% filebackend/HTTPFileStreamer.phpnu �Iw�� PK ! �1s~� � * �F% filebackend/fileop/FileStatePredicates.phpnu �Iw�� PK ! /���� � % �Z% filebackend/fileop/DescribeFileOp.phpnu �Iw�� PK ! �2�% % # �e% filebackend/fileop/DeleteFileOp.phpnu �Iw�� PK ! �Ki�� � ! p% filebackend/fileop/MoveFileOp.phpnu �Iw�� PK ! �� # �% filebackend/fileop/CreateFileOp.phpnu �Iw�� PK ! �^�� � ! s�% filebackend/fileop/CopyFileOp.phpnu �Iw�� PK ! V�_ _ ! ��% filebackend/fileop/NullFileOp.phpnu �Iw�� PK ! O�ez8 z8 A�% filebackend/fileop/FileOp.phpnu �Iw�� PK ! �Z�W W " �% filebackend/fileop/StoreFileOp.phpnu �Iw�� PK ! i�cc c ��% filebackend/FileBackendError.phpnu �Iw�� PK ! Δ�_� � d�% filebackend/FileOpBatch.phpnu �Iw�� PK ! J4~ 5 �& filebackend/fileiteration/SwiftFileBackendDirList.phpnu �Iw�� PK ! �*&�_ _ ? & filebackend/fileiteration/FileBackendStoreShardListIterator.phpnu �Iw�� PK ! _C�,� � 3 �& filebackend/fileiteration/FSFileBackendFileList.phpnu �Iw�� PK ! �ɕ�� � 6 & & filebackend/fileiteration/SwiftFileBackendFileList.phpnu �Iw�� PK ! žCj� � / }$& filebackend/fileiteration/FSFileBackendList.phpnu �Iw�� PK ! �+�� � 2 �7& filebackend/fileiteration/FSFileBackendDirList.phpnu �Iw�� PK ! �ڕ�� � ? =& filebackend/fileiteration/FileBackendStoreShardFileIterator.phpnu �Iw�� PK ! �%n�� � > eC& filebackend/fileiteration/FileBackendStoreShardDirIterator.phpnu �Iw�� PK ! �v/� � 2 �I& filebackend/fileiteration/SwiftFileBackendList.phpnu �Iw�� PK ! ^��I� � \& ExplodeIterator.phpnu �Iw�� PK ! n�ISg g 'h& MWCryptHash.phpnu �Iw�� PK ! ��>X� � �u& Deflate.phpnu �Iw�� PK ! ߷և16 16 �~& Message/README.mdnu �Iw�� PK ! !�kF F <�& Message/ListType.phpnu �Iw�� PK ! �$n)� � $ Ʒ& Message/IMessageFormatterFactory.phpnu �Iw�� PK ! LyT=m+ m+ ��& Message/MessageValue.phpnu �Iw�� PK ! �]� X�& Message/DataMessageValue.phpnu �Iw�� PK ! د��e e ��& Message/MessageParam.phpnu �Iw�� PK ! ��B Z�& Message/ParamType.phpnu �Iw�� PK ! ���B� � �' Message/ScalarParam.phpnu �Iw�� PK ! C] A� � �' Message/MessageSpecifier.phpnu �Iw�� PK ! WI?}� � �' Message/ITextFormatter.phpnu �Iw�� PK ! 7� �' Message/ListParam.phpnu �Iw�� PK ! �#�) �) �"' XhprofData.phpnu �Iw�� PK ! �?j6ik ik M' uuid/GlobalIdGenerator.phpnu �Iw�� PK ! �� kn n Ҹ' ArrayUtils.phpnu �Iw�� PK ! b�<. . ~�' HtmlArmor.phpnu �Iw�� PK ! R�y� � ��' ReverseArrayIterator.phpnu �Iw�� PK ss�� ��'
| ver. 1.1 | |
.
| PHP 8.4.18 | Ð“ÐµÐ½ÐµÑ€Ð°Ñ†Ð¸Ñ Ñтраницы: 0.33 |
proxy
|
phpinfo
|
ÐаÑтройка