wiki.techinc.nl/includes/Rest/ConditionalHeaderUtil.php

<?php

namespace MediaWiki\Rest;

use MediaWiki\Rest\HeaderParser\HttpDate;
use MediaWiki\Rest\HeaderParser\IfNoneMatch;
use RuntimeException;
use Wikimedia\Timestamp\ConvertibleTimestamp;

class ConditionalHeaderUtil {
	/** @var bool */
	private $varnishETagHack = true;
	/** @var string|null */
	private $eTag;
	/** @var int|null */
	private $lastModified;
	/** @var bool */
	private $hasRepresentation;

	/**
	 * Initialize the object with information about the requested resource.
	 *
	 * @param string|null $eTag The entity-tag (including quotes), or null if
	 *   it is unknown.
	 * @param string|int|null $lastModified The Last-Modified date in a format
	 *   accepted by ConvertibleTimestamp, or null if it is unknown.
	 * @param bool|null $hasRepresentation Whether the server has a current
	 *   representation of the target resource. This should be true if the
	 *   resource exists, and false if it does not exist. It is used for
	 *   wildcard validators -- the intended use case is to abort a PUT if the
	 *   resource does (or does not) exist. If null is passed, we assume that
	 *   the resource exists if an ETag was specified for it.
	 */
	public function setValidators( $eTag, $lastModified, $hasRepresentation ) {
		$this->eTag = $eTag;
		if ( $lastModified === null ) {
			$this->lastModified = null;
		} else {
			$this->lastModified = (int)ConvertibleTimestamp::convert( TS_UNIX, $lastModified );
		}
		$this->hasRepresentation = $hasRepresentation ?? ( $eTag !== null );
	}

	/**
	 * If the Varnish ETag hack is disabled by calling this method,
	 * strong ETag comparison will follow RFC 7232, rejecting all weak
	 * ETags for If-Match comparison.
	 *
	 * @param bool $hack
	 */
	public function setVarnishETagHack( $hack ) {
		$this->varnishETagHack = $hack;
	}

	/**
	 * Check conditional request headers in the order required by RFC 7232 section 6.
	 *
	 * @param RequestInterface $request
	 * @return int|null The status code to immediately return, or null to
	 *   continue processing the request.
	 */
	public function checkPreconditions( RequestInterface $request ) {
		$parser = new IfNoneMatch;
		if ( $this->eTag !== null ) {
			$resourceTag = $parser->parseETag( $this->eTag );
			if ( !$resourceTag ) {
				throw new RuntimeException( 'Invalid ETag returned by handler: `' .
					$parser->getLastError() . '`' );
			}
		} else {
			$resourceTag = null;
		}
		$getOrHead = in_array( $request->getMethod(), [ 'GET', 'HEAD' ] );
		if ( $request->hasHeader( 'If-Match' ) ) {
			$im = $request->getHeader( 'If-Match' );
			$match = false;
			foreach ( $parser->parseHeaderList( $im ) as $tag ) {
				if ( ( $tag['whole'] === '*' && $this->hasRepresentation ) ||
					$this->strongCompare( $resourceTag, $tag )
				) {
					$match = true;
					break;
				}
			}
			if ( !$match ) {
				return 412;
			}
		} elseif ( $request->hasHeader( 'If-Unmodified-Since' ) ) {
			$requestDate = HttpDate::parse( $request->getHeader( 'If-Unmodified-Since' )[0] );
			if ( $requestDate !== null
				&& ( $this->lastModified === null || $this->lastModified > $requestDate )
			) {
				return 412;
			}
		}
		if ( $request->hasHeader( 'If-None-Match' ) ) {
			$inm = $request->getHeader( 'If-None-Match' );
			foreach ( $parser->parseHeaderList( $inm ) as $tag ) {
				if ( ( $tag['whole'] === '*' && $this->hasRepresentation ) ||
					$this->weakCompare( $resourceTag, $tag )
				) {
					return $getOrHead ? 304 : 412;
				}
			}
		} elseif ( $getOrHead && $request->hasHeader( 'If-Modified-Since' ) ) {
			$requestDate = HttpDate::parse( $request->getHeader( 'If-Modified-Since' )[0] );
			if ( $requestDate !== null && $this->lastModified !== null
				&& $this->lastModified <= $requestDate
			) {
				return 304;
			}
		}
		// RFC 7232 states that If-Range should be evaluated here. However, the
		// purpose of If-Range is to cause the Range request header to be
		// conditionally ignored, not to immediately send a response, so it
		// doesn't fit here. RFC 7232 only requires that If-Range be checked
		// after the other conditional header fields, a requirement that is
		// satisfied if it is processed in Handler::execute().
		return null;
	}

	/**
	 * Set Last-Modified and ETag headers in the response according to the cached
	 * values set by setValidators(), which are also used for precondition checks.
	 *
	 * If the headers are already present in the response, the existing headers
	 * take precedence.
	 *
	 * @param ResponseInterface $response
	 */
	public function applyResponseHeaders( ResponseInterface $response ) {
		if ( $this->lastModified !== null && !$response->hasHeader( 'Last-Modified' ) ) {
			$response->setHeader( 'Last-Modified', HttpDate::format( $this->lastModified ) );
		}
		if ( $this->eTag !== null && !$response->hasHeader( 'ETag' ) ) {
			$response->setHeader( 'ETag', $this->eTag );
		}
	}

	/**
	 * The weak comparison function, per RFC 7232, section 2.3.2.
	 *
	 * @param array|null $resourceETag ETag generated by the handler, parsed tag info array
	 * @param array|null $headerETag ETag supplied by the client, parsed tag info array
	 * @return bool
	 */
	private function weakCompare( $resourceETag, $headerETag ) {
		if ( $resourceETag === null || $headerETag === null ) {
			return false;
		}
		return $resourceETag['contents'] === $headerETag['contents'];
	}

	/**
	 * The strong comparison function
	 *
	 * A strong ETag returned by the server may have been "weakened" by Varnish when applying
	 * compression. So optionally ignore the weakness of the header.
	 * {@link https://varnish-cache.org/docs/6.0/users-guide/compression.html}.
	 * @see T238849 and T310710
	 *
	 * @param array|null $resourceETag ETag generated by the handler, parsed tag info array
	 * @param array|null $headerETag ETag supplied by the client, parsed tag info array
	 *
	 * @return bool
	 */
	private function strongCompare( $resourceETag, $headerETag ) {
		if ( $resourceETag === null || $headerETag === null ) {
			return false;
		}

		return !$resourceETag['weak']
			&& ( $this->varnishETagHack || !$headerETag['weak'] )
			&& $resourceETag['contents'] === $headerETag['contents'];
	}

}