HtmlOutputRendererHelper.php

Go to the documentation of this file.

<?php
namespace MediaWiki\Rest\Handler\Helper;
 
use InvalidArgumentException;
use MediaWiki\Content\Content;
use MediaWiki\Content\IContentHandlerFactory;
use MediaWiki\Content\UnknownContentModelException;
use MediaWiki\Edit\ParsoidOutputStash;
use MediaWiki\Edit\ParsoidRenderID;
use MediaWiki\Edit\SelserContext;
use MediaWiki\Exception\HttpError;
use MediaWiki\Language\LanguageCode;
use MediaWiki\Language\LanguageFactory;
use MediaWiki\Logger\LoggerFactory;
use MediaWiki\MainConfigNames;
use MediaWiki\MediaWikiServices;
use MediaWiki\Page\PageIdentity;
use MediaWiki\Page\PageLookup;
use MediaWiki\Page\PageRecord;
use MediaWiki\Page\ParserOutputAccess;
use MediaWiki\Parser\ContentHolder;
use MediaWiki\Parser\ParserOptions;
use MediaWiki\Parser\ParserOutput;
use MediaWiki\Parser\Parsoid\Config\SiteConfig as ParsoidSiteConfig;
use MediaWiki\Parser\Parsoid\HtmlTransformFactory;
use MediaWiki\Parser\Parsoid\PageBundleParserOutputConverter;
use MediaWiki\Permissions\Authority;
use MediaWiki\Rest\Handler;
use MediaWiki\Rest\HttpException;
use MediaWiki\Rest\LocalizedHttpException;
use MediaWiki\Rest\ResponseInterface;
use MediaWiki\Revision\MutableRevisionRecord;
use MediaWiki\Revision\RevisionAccessException;
use MediaWiki\Revision\RevisionLookup;
use MediaWiki\Revision\RevisionRecord;
use MediaWiki\Revision\RevisionRenderer;
use MediaWiki\Revision\SlotRecord;
use MediaWiki\Status\Status;
use MediaWiki\Title\Title;
use RuntimeException;
use Wikimedia\Assert\Assert;
use Wikimedia\Bcp47Code\Bcp47Code;
use Wikimedia\Bcp47Code\Bcp47CodeValue;
use Wikimedia\Message\MessageValue;
use Wikimedia\ParamValidator\ParamValidator;
use Wikimedia\Parsoid\Core\ClientError;
use Wikimedia\Parsoid\Core\HtmlPageBundle;
use Wikimedia\Parsoid\Core\ResourceLimitExceededException;
use Wikimedia\Parsoid\DOM\DocumentFragment;
use Wikimedia\Parsoid\DOM\Element;
use Wikimedia\Parsoid\Parsoid;
use Wikimedia\Parsoid\Utils\DOMUtils;
use Wikimedia\Parsoid\Utils\WTUtils;
use Wikimedia\Stats\StatsFactory;
 
class HtmlOutputRendererHelper implements HtmlOutputHelper {
    use RestAuthorizeTrait;
    use RestStatusTrait;
 
    public const CONSTRUCTOR_OPTIONS = [
        MainConfigNames::ParsoidCacheConfig
    ];
 
    private const OUTPUT_FLAVORS = [ 'view', 'stash', 'fragment', 'edit' ];
 
    private $page = null;
 
    private $revisionOrId = null;
 
    private $pageLanguage = null;
 
    private $flavor = null;
 
    private $stash = false;
 
    private $authority;
 
    private $parserOutput;
 
    private $processedParserOutput;
 
    private $sourceLanguage = null;
 
    private $targetLanguage = null;
 
    private bool $lenientRevHandling = false;
 
    private $parsoidOptions = [];
 
    private ?ParserOptions $parserOptions = null;
 
    private $isCacheable = true;
 
    private ParsoidOutputStash $parsoidOutputStash;
    private StatsFactory $statsFactory;
    private ParserOutputAccess $parserOutputAccess;
    private PageLookup $pageLookup;
    private RevisionLookup $revisionLookup;
    private RevisionRenderer $revisionRenderer;
    private ParsoidSiteConfig $parsoidSiteConfig;
    private HtmlTransformFactory $htmlTransformFactory;
    private IContentHandlerFactory $contentHandlerFactory;
    private LanguageFactory $languageFactory;
 
    public function __construct(
        ParsoidOutputStash $parsoidOutputStash,
        StatsFactory $statsFactory,
        ParserOutputAccess $parserOutputAccess,
        PageLookup $pageLookup,
        RevisionLookup $revisionLookup,
        RevisionRenderer $revisionRenderer,
        ParsoidSiteConfig $parsoidSiteConfig,
        HtmlTransformFactory $htmlTransformFactory,
        IContentHandlerFactory $contentHandlerFactory,
        LanguageFactory $languageFactory,
        ?PageIdentity $page = null,
        array $parameters = [],
        ?Authority $authority = null,
        $revision = null,
        bool $lenientRevHandling = false,
        ?ParserOptions $parserOptions = null
    ) {
        $this->parsoidOutputStash = $parsoidOutputStash;
        $this->statsFactory = $statsFactory;
        $this->parserOutputAccess = $parserOutputAccess;
        $this->pageLookup = $pageLookup;
        $this->revisionLookup = $revisionLookup;
        $this->revisionRenderer = $revisionRenderer;
        $this->parsoidSiteConfig = $parsoidSiteConfig;
        $this->htmlTransformFactory = $htmlTransformFactory;
        $this->contentHandlerFactory = $contentHandlerFactory;
        $this->languageFactory = $languageFactory;
        $this->lenientRevHandling = $lenientRevHandling;
        $this->parserOptions = $parserOptions;
        if ( $page === null || $authority === null ) {
            // Constructing without $page and $authority parameters
            // is deprecated since 1.43.
            wfDeprecated( __METHOD__ . ' without $page or $authority', '1.43' );
        } else {
            $this->initInternal( $page, $parameters, $authority, $revision );
        }
    }
 
    public function setFlavor( string $flavor ): void {
        if ( !in_array( $flavor, self::OUTPUT_FLAVORS ) ) {
            throw new InvalidArgumentException( 'Invalid flavor supplied' );
        }
 
        if ( $this->stash ) {
            // XXX: throw?
            $flavor = 'stash';
        }
 
        $this->flavor = $flavor;
    }
 
    public function getFlavor(): string {
        return $this->flavor;
    }
 
    public function setOutputProfileVersion( $version ) {
        $outputContentVersion = Parsoid::resolveContentVersion( $version );
 
        if ( !$outputContentVersion ) {
            throw new LocalizedHttpException(
                new MessageValue( "rest-unsupported-profile-version", [ $version ] ), 406
            );
        }
 
        // Only set the option if the value isn't the default!
        if ( $outputContentVersion !== Parsoid::defaultHTMLVersion() ) {
            throw new LocalizedHttpException(
                new MessageValue( "rest-unsupported-profile-version", [ $version ] ), 406
            );
 
            // TODO: (T347426) At some later point, we may reintroduce support for
            // non-default content versions as part of work on the content
            // negotiation protocol.
            //
            // // See Parsoid::wikitext2html
            // $this->parsoidOptions['outputContentVersion'] = $outputContentVersion;
            // $this->isCacheable = false;
        }
    }
 
    public function setStashingEnabled( bool $stash ): void {
        $this->stash = $stash;
 
        if ( $stash ) {
            $this->setFlavor( 'stash' );
        } elseif ( $this->flavor === 'stash' ) {
            $this->setFlavor( 'view' );
        }
    }
 
    public function setRevision( $revisionOrId ): void {
        Assert::parameterType( [ RevisionRecord::class, 'integer' ], $revisionOrId, '$revision' );
 
        if ( is_int( $revisionOrId ) && $revisionOrId <= 0 ) {
            throw new HttpError( 400, "Bad revision ID: $revisionOrId" );
        }
 
        $this->revisionOrId = $revisionOrId;
 
        if ( $this->getRevisionId() === null ) {
            // If we have a RevisionRecord but no revision ID, we are dealing with a fake
            // revision used for editor previews or mode switches. The wikitext is coming
            // from the request, not the database, so the result is not cacheable for re-use
            // by others (though it can be stashed for use by the same client).
            $this->isCacheable = false;
        }
    }
 
    public function setContent( Content $content ): void {
        $this->setRevision(
            MutableRevisionRecord::newFromContent( $this->page, $content )
                ->setId( 0 )
                ->setPageId( $this->page->getId() )
        );
    }
 
    public function setContentSource( string $source, string $model ): void {
        try {
            $handler = $this->contentHandlerFactory->getContentHandler( $model );
            $content = $handler->unserializeContent( $source );
            $this->setContent( $content );
        } catch ( UnknownContentModelException ) {
            throw new LocalizedHttpException( new MessageValue( "rest-bad-content-model", [ $model ] ), 400 );
        }
    }
 
    public function setPageLanguage( $pageLanguage ): void {
        if ( is_string( $pageLanguage ) ) {
            $pageLanguage = new Bcp47CodeValue( $pageLanguage );
        }
        $this->pageLanguage = $pageLanguage;
    }
 
    public function init(
        PageIdentity $page,
        array $parameters,
        Authority $authority,
        $revision = null
    ) {
        wfDeprecated( __METHOD__, '1.43' );
        $this->initInternal( $page, $parameters, $authority, $revision );
    }
 
    private function initInternal(
        PageIdentity $page,
        array $parameters,
        Authority $authority,
        $revision = null
    ) {
        $this->page = $page;
        $this->authority = $authority;
        $this->stash = $parameters['stash'] ?? false;
 
        if ( $revision !== null ) {
            $this->setRevision( $revision );
        }
 
        if ( $this->stash ) {
            $this->setFlavor( 'stash' );
        } else {
            $this->setFlavor( $parameters['flavor'] ?? 'view' );
        }
        $this->parserOptions ??= ParserOptions::newFromAnon();
    }
 
    public function setVariantConversionLanguage(
        $targetLanguage,
        $sourceLanguage = null
    ): void {
        if ( is_string( $targetLanguage ) ) {
            $targetLanguage = $this->getAcceptedTargetLanguage( $targetLanguage );
            $targetLanguage = LanguageCode::normalizeNonstandardCodeAndWarn(
                $targetLanguage
            );
        }
        if ( is_string( $sourceLanguage ) ) {
            $sourceLanguage = LanguageCode::normalizeNonstandardCodeAndWarn(
                $sourceLanguage
            );
        }
        $this->targetLanguage = $targetLanguage;
        $this->sourceLanguage = $sourceLanguage;
    }
 
    public static function getAcceptedTargetLanguage( string $targetLanguage ): string {
        // We could try to identify the most desirable language here,
        // following the rules for Accept-Language headers in RFC9100.
        // For now, just take the first language code.
 
        if ( preg_match( '/^\s*([-\w]+)/', $targetLanguage, $m ) ) {
            return $m[1];
        } else {
            // "undetermined" per RFC5646
            return 'und';
        }
    }
 
    public function getHtml(): ParserOutput {
        if ( $this->processedParserOutput ) {
            return $this->processedParserOutput;
        }
 
        $parserOutput = $this->getParserOutput();
 
        if ( $this->stash ) {
            $this->authorizeWriteOrThrow( $this->authority, 'stashbasehtml', $this->page );
 
            $isFakeRevision = $this->getRevisionId() === null;
            $parsoidStashKey = ParsoidRenderID::newFromParserOutput( $parserOutput );
            $stashSuccess = $this->parsoidOutputStash->set(
                $parsoidStashKey,
                new SelserContext(
                    // Stash a full document (head + body) so the later html2wt
                    // selser round-trip keeps working once the canonical
                    // ParserOutput is body-only (T393295)
                    PageBundleParserOutputConverter::htmlPageBundleFromParserOutput(
                        $parserOutput, $this->parsoidSiteConfig, bodyOnly: false,
                    ),
                    $parsoidStashKey->getRevisionID(),
                    $isFakeRevision ? $this->revisionOrId->getContent( SlotRecord::MAIN ) : null
                )
            );
            if ( !$stashSuccess ) {
                $this->statsFactory->getCounter( 'htmloutputrendererhelper_stash_total' )
                    ->setLabel( 'status', 'fail' )
                    ->increment();
 
                $errorData = [ 'parsoid-stash-key' => $parsoidStashKey ];
                LoggerFactory::getInstance( 'HtmlOutputRendererHelper' )->error(
                    "Parsoid stash failure",
                    $errorData
                );
                throw new LocalizedHttpException(
                    MessageValue::new( 'rest-html-stash-failure' ),
                    500,
                    $errorData
                );
            }
            $this->statsFactory->getCounter( 'htmloutputrendererhelper_stash_total' )
                ->setLabel( 'status', 'save' )
                ->increment();
        }
 
        // Check if variant conversion has to be performed
        // NOTE: Variant conversion is performed on the fly, and kept outside the stash.
        if ( $this->targetLanguage ) {
            $languageVariantConverter = $this->htmlTransformFactory->getLanguageVariantConverter( $this->page );
            $parserOutput = $languageVariantConverter->convertParserOutputVariant(
                $parserOutput,
                $this->targetLanguage,
                $this->sourceLanguage
            );
        }
 
        if ( $this->flavor === 'edit' ) {
            // The 'edit' flavor inlines data-parsoid/data-mw attributes so the
            // editor can round-trip.
            $pb = PageBundleParserOutputConverter::htmlPageBundleFromParserOutput(
                $parserOutput, $this->parsoidSiteConfig, bodyOnly: true
            );
            $parserOutput->setContentHolder(
                ContentHolder::createFromParsoidPageBundle(
                    $this->convertToInline( $pb ), $this->parsoidSiteConfig
                )
            );
        }
 
        $this->processedParserOutput = $parserOutput;
        return $parserOutput;
    }
 
    private function convertToInline( HtmlPageBundle $pb ): HtmlPageBundle {
        $fragments = [];
        $html = $pb->toInlineAttributeHtml(
            siteConfig: $this->parsoidSiteConfig,
            fragments: $fragments
        );
        return new HtmlPageBundle(
            html: $html,
            counters: $pb->counters,
            version: $pb->version,
            headers: $pb->headers,
            contentmodel: $pb->contentmodel,
            fragments: $fragments,
        );
    }
 
    public function getETag( string $suffix = '' ): ?string {
        $parserOutput = $this->getParserOutput();
 
        $renderID = ParsoidRenderID::newFromParserOutput( $parserOutput )->getKey();
 
        if ( $suffix !== '' ) {
            $eTag = "$renderID/{$this->flavor}/$suffix";
        } else {
            $eTag = "$renderID/{$this->flavor}";
        }
 
        if ( $this->targetLanguage ) {
            $eTag .= "+lang:{$this->targetLanguage->toBcp47Code()}";
        }
 
        return "\"{$eTag}\"";
    }
 
    private function isLatest(): bool {
        $revId = $this->getRevisionId();
 
        if ( $revId === null ) {
            return false; // un-saved revision
        }
 
        if ( $revId === 0 ) {
            return true; // latest revision
        }
 
        $page = $this->getPageRecord();
 
        if ( !$page ) {
            return false; // page doesn't exist. shouldn't happen.
        }
 
        return $revId === $page->getLatest();
    }
 
    public function getLastModified(): ?string {
        if ( $this->isLatest() ) {
            $page = $this->getPageRecord();
 
            // $page should never be null here.
            // If it's null, getParserOutput() will fail nicely below.
            if ( $page ) {
                // Using the touch timestamp for this purpose is in line with
                // the behavior of ViewAction::show(). However,
                // OutputPage::checkLastModified() applies a lot of additional
                // limitations.
                return $page->getTouched();
            }
        }
 
        return $this->getParserOutput()->getCacheTime();
    }
 
    public static function getParamSettings(): array {
        return [
            'stash' => [
                Handler::PARAM_SOURCE => 'query',
                ParamValidator::PARAM_TYPE => 'boolean',
                ParamValidator::PARAM_DEFAULT => false,
                ParamValidator::PARAM_REQUIRED => false,
                Handler::PARAM_DESCRIPTION => new MessageValue( 'rest-param-desc-html-output-stash' )
            ],
            'flavor' => [
                Handler::PARAM_SOURCE => 'query',
                ParamValidator::PARAM_TYPE => self::OUTPUT_FLAVORS,
                ParamValidator::PARAM_DEFAULT => 'view',
                ParamValidator::PARAM_REQUIRED => false,
                Handler::PARAM_DESCRIPTION => new MessageValue( 'rest-param-desc-html-output-flavor' )
            ],
        ];
    }
 
    private function getDefaultPageLanguage(): Bcp47Code {
        // NOTE: keep in sync with Parser::getTargetLanguage!
 
        // XXX: Inject a TitleFactory just for this?! We need a better way to determine the page language...
        $title = Title::castFromPageIdentity( $this->page );
 
        if ( $this->parserOptions->getInterfaceMessage() ) {
            return $this->parserOptions->getUserLangObj();
        }
 
        return $title->getPageLanguage();
    }
 
    // See ParserOptions::optionsHash
    private function getDefaultVariant(): Bcp47Code {
        $services = MediaWikiServices::getInstance();
        $lang = Title::castFromPageIdentity( $this->page )->getPageLanguage();
        $converter = $services->getLanguageConverterFactory()->getLanguageConverter( $lang );
        return $this->languageFactory->getLanguage(
            $converter->getPreferredVariant()
        );
    }
 
    private function getParserOutput(): ParserOutput {
        if ( !$this->parserOutput ) {
            $this->parserOptions->setRenderReason( __METHOD__ );
 
            $defaultLanguage = $this->getDefaultPageLanguage();
            $defaultVariant = $this->getDefaultVariant();
 
            if ( $this->pageLanguage
                 && ( !$this->pageLanguage->isSameCodeAs( $defaultLanguage ) ||
                     // T418549: if we're asking for the base but the URL
                     // specifies a variant, we need to fork the cache
                     // T267067 should fix this properly.
                     !$this->pageLanguage->isSameCodeAs( $defaultVariant ) )
            ) {
                $languageObj = $this->languageFactory->getLanguage( $this->pageLanguage );
                $this->parserOptions->setTargetLanguage( $languageObj );
                // Ensure target language splits the parser cache, when
                // non-default; targetLanguage is not in
                // ParserOptions::$cacheVaryingOptionsHash for the legacy
                // parser.
                $this->parserOptions->addExtraKey( 'target=' . $languageObj->getCode() );
            }
 
            try {
                $status = $this->getParserOutputInternal();
            } catch ( RevisionAccessException $e ) {
                throw new LocalizedHttpException(
                    MessageValue::new( 'rest-nonexistent-title' ),
                    404,
                    [ 'reason' => $e->getMessage() ]
                );
            }
 
            if ( !$status->isOK() ) {
                if ( $status->hasMessage( 'parsoid-client-error' ) ) {
                    $this->throwExceptionForStatus( $status, 'rest-html-backend-error', 400 );
                } elseif ( $status->hasMessage( 'parsoid-resource-limit-exceeded' ) ) {
                    $this->throwExceptionForStatus( $status, 'rest-resource-limit-exceeded', 413 );
                } elseif ( $status->hasMessage( 'missing-revision-permission' ) ) {
                    $this->throwExceptionForStatus( $status, 'rest-permission-denied-revision', 403 );
                } elseif ( $status->hasMessage( 'parsoid-revision-access' ) ) {
                    $this->throwExceptionForStatus( $status, 'rest-specified-revision-unavailable', 404 );
                } else {
                    $this->logStatusError( $status, 'Parsoid backend error', 'HtmlOutputRendererHelper' );
                    $this->throwExceptionForStatus( $status, 'rest-html-backend-error', 500 );
                }
            }
 
            $this->parserOutput = $status->getValue();
        }
 
        Assert::invariant( $this->parserOutput->getRenderId() !== null, "no render id" );
        return $this->parserOutput;
    }
 
    public function getHtmlOutputContentLanguage(): Bcp47Code {
        $contentLanguage = $this->getHtml()->getLanguage();
 
        // This shouldn't happen, but don't crash if it does:
        if ( !$contentLanguage ) {
            if ( $this->pageLanguage ) {
                LoggerFactory::getInstance( 'HtmlOutputRendererHelper' )->warning(
                    "ParserOutput does not specify a language"
                );
 
                $contentLanguage = $this->pageLanguage;
            } else {
                LoggerFactory::getInstance( 'HtmlOutputRendererHelper' )->warning(
                    "ParserOutput does not specify a language and no page language set in helper.",
                    // (T387453) Add a stack trace to help debug the sources of this issue
                    [ 'fauxerror' => new RuntimeException( 'Dummy error for a trace' ) ]
                );
 
                $title = Title::newFromPageIdentity( $this->page );
                $contentLanguage = $title->getPageLanguage();
            }
        }
 
        return $contentLanguage;
    }
 
    public function putHeaders( ResponseInterface $response, bool $forHtml = true ): void {
        $pb = $this->getPageBundle();
        $headers = $forHtml ? [
            // default headers
            'content-type' => ParsoidFormatHelper::getContentType(
                ParsoidFormatHelper::FORMAT_HTML, $pb->version
            ),
            'content-language' => $this->getHtmlOutputContentLanguage()
                ->toBcp47Code(),
        ] : [];
        foreach ( $pb->headers ?? [] as $name => $value ) {
            // ensure header names are lowercase and unique
            $headers[strtolower( $name )] = $value;
        }
        if ( !$forHtml ) {
            // For HTML, we want to set the Content-Language. For JSON, we probably don't.
            unset( $headers['content-language'] );
        }
        foreach ( $headers as $name => $value ) {
            $response->setHeader( $name, $value );
        }
 
        if ( $this->targetLanguage ) {
            // Ensure 'Accept-Language' is included among other 'vary' headers
            $response->addHeader( 'Vary', 'Accept-Language' );
        }
 
        // XXX: if Parsoid returns Vary headers, set them here?!
 
        if ( !$this->isCacheable ) {
            $response->setHeader( 'Cache-Control', 'private,no-cache,s-maxage=0' );
        }
 
        // TODO: cache control for stable HTML? See ContentHelper::setCacheControl
 
        if ( $this->getRevisionId() ) {
            $response->setHeader( 'Content-Revision-Id', (string)$this->getRevisionId() );
        }
    }
 
    public function getPageBundle(): HtmlPageBundle {
        // XXX: converting between HtmlPageBundle and ParserOutput is inefficient!
        $parserOutput = $this->getParserOutput();
        // Check if variant conversion has to be performed
        // NOTE: Variant conversion is performed on the fly, and kept outside the stash.
        if ( $this->targetLanguage ) {
            $languageVariantConverter = $this->htmlTransformFactory->getLanguageVariantConverter( $this->page );
            $parserOutput = $languageVariantConverter->convertParserOutputVariant(
                $parserOutput,
                $this->targetLanguage,
                $this->sourceLanguage,
            );
        }
 
        // An HtmlPageBundle always carries the full document (head +
        // body, with the <head> rebuilt from metadata). Request it
        // explicitly so this keeps emitting a full document once the
        // canonical ParserOutput is body-only (T393295).
        $pb = PageBundleParserOutputConverter::htmlPageBundleFromParserOutput(
            $parserOutput, $this->parsoidSiteConfig, bodyOnly: false,
        );
 
        if ( $this->flavor === 'edit' ) {
            // The 'edit' flavor inlines data-parsoid/data-mw attributes so the
            // editor can round-trip.
            $pb = $this->convertToInline( $pb );
        }
 
        return $pb;
    }
 
    public function getRevisionId(): ?int {
        if ( !$this->revisionOrId ) {
            // If we don't have a revision set, or it's 0, we are rendering the current revision.
            return 0;
        }
 
        if ( $this->revisionOrId instanceof RevisionRecord ) {
            // NOTE: return null even if getId() gave us 0
            return $this->revisionOrId->getId() ?: null;
        }
 
        // It's a revision ID, just return it
        return (int)$this->revisionOrId;
    }
 
    private function stripParsoidSectionTags( DocumentFragment|Element $elt ): void {
        $n = $elt->firstChild;
        while ( $n ) {
            $next = $n->nextSibling;
            if ( $n instanceof Element ) {
                // Recurse into subtree before stripping this
                $this->stripParsoidSectionTags( $n );
                // Strip <section> tags and synthetic extended-annotation-region wrappers
                if ( WTUtils::isParsoidSectionTag( $n ) ) {
                    $parent = $n->parentNode;
                    // Help out phan
                    '@phan-var Element $parent';
                    DOMUtils::migrateChildren( $n, $parent, $n );
                    $parent->removeChild( $n );
                }
            }
            $n = $next;
        }
    }
 
    private function getPageRecord(): ?PageRecord {
        if ( $this->page === null ) {
            return null;
        }
 
        if ( !$this->page instanceof PageRecord ) {
            $page = $this->pageLookup->getPageByReference( $this->page );
            if ( !$page ) {
                return null;
            }
 
            $this->page = $page;
        }
 
        return $this->page;
    }
 
    private function getParserOutputInternal(): Status {
        // NOTE: ParserOutputAccess::getParserOutput() should be used for revisions
        //       that come from the database. Either this revision is null to indicate
        //       the current revision or the revision must have an ID.
        // If we have a revision and the ID is 0 or null, then it's a fake revision
        // representing a preview.
        $parsoidOptions = $this->parsoidOptions;
 
        if ( $this->getRevisionId() === null ) {
            $this->isCacheable = false;
        }
 
        $parserOutputAccessOptions = [
            // Use pool counter (T387478).
            // Use it even if the output is not cacheable, to protect against
            // load spikes.
            ParserOutputAccess::OPT_POOL_COUNTER =>
                ParserOutputAccess::POOL_COUNTER_REST_API
        ];
 
        // Find page
        $pageRecord = $this->getPageRecord();
        $revision = $this->revisionOrId;
 
        // NOTE: If we have a RevisionRecord already and this is
        //       not cacheable, just use it, there is no need to
        //       resolve $page to a PageRecord (and it may not be
        //       possible if the page doesn't exist).
        if ( $this->isCacheable ) {
            if ( !$pageRecord ) {
                if ( $this->page ) {
                    throw new RevisionAccessException(
                        'Page {name} not found',
                        [ 'name' => "{$this->page}" ]
                    );
                } else {
                    throw new RevisionAccessException( "No page" );
                }
            }
 
            $revision ??= $pageRecord->getLatest();
 
            if ( is_int( $revision ) ) {
                $revId = $revision;
                $revision = $this->revisionLookup->getRevisionById( $revId );
 
                if ( !$revision ) {
                    throw new RevisionAccessException(
                        'Revision {revId} not found',
                        [ 'revId' => $revId ]
                    );
                }
            }
 
            if ( $pageRecord->getId() !== $revision->getPageId() ) {
                if ( $this->lenientRevHandling ) {
                    $pageRecord = $this->pageLookup->getPageById( $revision->getPageId() );
                    if ( !$pageRecord ) {
                        // This should ideally never trigger!
                        throw new \RuntimeException(
                            "Unexpected NULL page for pageid " . $revision->getPageId() .
                            " from revision " . $revision->getId()
                        );
                    }
                    // Don't cache this!
                    $parserOutputAccessOptions[ ParserOutputAccess::OPT_NO_UPDATE_CACHE ] = true;
                } else {
                    throw new RevisionAccessException(
                        'Revision {revId} does not belong to page {name}',
                        [ 'name' => $pageRecord->getDBkey(), 'revId' => $revision->getId() ]
                    );
                }
            }
        }
 
        $contentModel = $revision->getMainContentModel();
        if ( $this->parsoidSiteConfig->supportsContentModel( $contentModel ) ) {
            $this->parserOptions->setUseParsoid();
        }
        if ( $this->isCacheable ) {
            // phan can't tell that we must have used the block above to
            // resolve $pageRecord to a PageRecord if we've made it to this block.
            '@phan-var PageRecord $pageRecord';
            try {
                $status = $this->parserOutputAccess->getParserOutput(
                    $pageRecord, $this->parserOptions, $revision, $parserOutputAccessOptions
                );
            } catch ( ClientError $e ) {
                $status = Status::newFatal( 'parsoid-client-error', $e->getMessage() );
            } catch ( ResourceLimitExceededException $e ) {
                $status = Status::newFatal( 'parsoid-resource-limit-exceeded', $e->getMessage() );
            }
        } else {
            '@phan-var RevisionRecord $revision';
            $status = $this->parseUncacheable( $revision );
        }
        if ( $status->isOK() && $this->flavor === 'fragment' ) {
            // Unwrap sections and return body_only content
            // NOTE: This introduces an extra html -> dom -> html roundtrip
            // This will get addressed once HtmlHolder work is complete
            $parserOutput = $status->getValue();
            $body = $parserOutput->getContentHolder()->getAsDom(
                ContentHolder::BODY_FRAGMENT
            );
            '@phan-var DocumentFragment $body';
            $this->stripParsoidSectionTags( $body );
        }
        Assert::invariant( $status->isOK() ? $status->getValue()->getRenderId() !== null : true, "no render id" );
        return $status;
    }
 
    // See ParserOutputAccess::renderRevision() -- but of course this method
    // bypasses any caching.
    private function parseUncacheable( RevisionRecord $revision ): Status {
        // Enforce caller expectation
        $revId = $revision->getId();
        if ( $revId !== 0 && $revId !== null ) {
            return Status::newFatal( 'parsoid-revision-access',
                "parseUncacheable should not be called for a real revision" );
        }
        try {
            $renderedRev = $this->revisionRenderer->getRenderedRevision(
                $revision,
                $this->parserOptions,
                // ParserOutputAccess uses 'null' for the authority and
                // 'audience' => RevisionRecord::RAW, presumably because
                // the access checks are already handled by the
                // RestAuthorizeTrait
                $this->authority,
                [ 'audience' => RevisionRecord::RAW ]
            );
            if ( $renderedRev === null ) {
                return Status::newFatal( 'parsoid-revision-access' );
            }
            $parserOutput = $renderedRev->getRevisionParserOutput();
            // Ensure this isn't accidentally cached
            $parserOutput->updateCacheExpiry( 0, 'uncacheable-render' );
            return Status::newGood( $parserOutput );
        } catch ( ClientError $e ) {
            return Status::newFatal( 'parsoid-client-error', $e->getMessage() );
        } catch ( ResourceLimitExceededException $e ) {
            return Status::newFatal( 'parsoid-resource-limit-exceeded', $e->getMessage() );
        }
    }
 
    public function isParsoidContent(): bool {
        return $this->getParserOutput()->getContentHolder()->isParsoidContent();
    }
 
}