RecoveryDisposition.php

<?php

namespace USIPS\NCMEC;

use USIPS\NCMEC\Exception\CaseClosedToChanges;
use USIPS\NCMEC\Exception\IncidentAssociationBatchFailure;

/** Missing-at-review metadata settles bookkeeping, never source deletion. */
class RecoveryDisposition
{
    private static array $activeIncidentAssociationTransactions = [];

    public static function lock(\XF\App $app, int $caseId): bool
    {
        return (int)$app->db()->fetchOne('SELECT GET_LOCK(?, 0)', 'usipsNcmecCase' . $caseId) === 1;
    }

    public static function unlock(\XF\App $app, int $caseId): void
    {
        $app->db()->fetchOne('SELECT RELEASE_LOCK(?)', 'usipsNcmecCase' . $caseId);
    }

    /**
     * Run a database operation in a transaction/savepoint and restore exactly
     * the transaction depth owned by the caller if any Throwable escapes.
     */
    public static function withTransaction(\XF\Db\AbstractAdapter $db, callable $callback)
    {
        $startedInTransaction = $db->inTransaction();
        $startingSavepointDepth = self::savepointDepth($db);
        $db->beginTransaction();

        try
        {
            $result = $callback();
            $db->commit();
            return $result;
        }
        catch (\Throwable $e)
        {
            if (!self::rollbackToTransactionState($db, $startedInTransaction, $startingSavepointDepth))
            {
                throw new \RuntimeException(
                    'The NCMEC operation could not restore its caller transaction; the caller transaction was aborted.',
                    0,
                    $e
                );
            }
            throw $e;
        }
    }

    /**
     * Keep the case and incident rows locked for the full association operation.
     * A nested Creator/AttachmentManager call on the same incident reuses the
     * caller's transaction and locks; the database savepoint stack remains owned
     * by XenForo and each wrapper unwinds only its own level.
     */
    public static function withIncidentAssociationTransaction(\XF\App $app, int $incidentId, callable $callback)
    {
        if ($incidentId < 1)
        {
            throw new \RuntimeException('An incident is required before NCMEC associations can be changed.');
        }

        $db = $app->db();
        $lockKey = spl_object_id($db) . ':' . $incidentId;
        if (!empty(self::$activeIncidentAssociationTransactions[$lockKey]))
        {
            return $callback();
        }

        $state = (object)['batchFailures' => []];
        try
        {
            $result = self::withTransaction($db, function () use ($app, $incidentId, $callback, $lockKey, $state)
            {
                self::lockIncidentAssociationRows($app, $incidentId);
                self::$activeIncidentAssociationTransactions[$lockKey] = $state;
                try
                {
                    try
                    {
                        return $callback();
                    }
                    catch (IncidentAssociationBatchFailure $e)
                    {
                        if ($e->getIncidentId() !== $incidentId)
                        {
                            throw $e;
                        }

                        // The explicit batch disposition keeps successful
                        // items, but unwinds composed work before reaching
                        // this outermost case transaction boundary.
                        $state->batchFailures[] = $e;
                        return null;
                    }
                }
                finally
                {
                    unset(self::$activeIncidentAssociationTransactions[$lockKey]);
                }
            });
        }
        catch (\Throwable $e)
        {
            $state->batchFailures = [];
            throw $e;
        }

        $batchFailures = $state->batchFailures;
        $state->batchFailures = [];
        if ($batchFailures)
        {
            $messages = array_values(array_unique(array_map(
                static function (IncidentAssociationBatchFailure $failure): string
                {
                    return $failure->getMessage();
                },
                $batchFailures
            )));
            throw new IncidentAssociationBatchFailure($incidentId, implode('; ', $messages));
        }

        return $result;
    }

    /**
     * Called from entity source-write hooks after XenForo has opened its write
     * transaction. The row locks then live through the actual save/delete commit.
     */
    public static function assertIncidentAssociationOpen(\XF\App $app, int $incidentId): void
    {
        if ($incidentId < 1)
        {
            throw new \RuntimeException('The incident no longer exists; the evidence change was not applied.');
        }

        $lockKey = spl_object_id($app->db()) . ':' . $incidentId;
        if (!empty(self::$activeIncidentAssociationTransactions[$lockKey]))
        {
            return;
        }

        self::lockIncidentAssociationRows($app, $incidentId);
    }

    /**
     * Lock old and new cases in ascending order before the incident row, then
     * verify the persisted mapping still matches the entity's original state.
     */
    public static function lockIncidentCaseReassignment(
        \XF\App $app,
        int $incidentId,
        int $expectedOldCaseId,
        int $newCaseId,
        bool $isInsert = false
    ): void
    {
        $db = $app->db();
        if (!$isInsert)
        {
            $currentCaseId = (int)$db->fetchOne('SELECT case_id FROM xf_usips_ncmec_incident WHERE incident_id = ?', $incidentId);
            if ($currentCaseId !== $expectedOldCaseId)
            {
                throw new \RuntimeException('The incident case assignment changed; retry the operation.');
            }
            $expectedOldCaseId = $currentCaseId;
        }

        $caseIds = array_values(array_unique(array_filter([$expectedOldCaseId, $newCaseId])));
        sort($caseIds, SORT_NUMERIC);
        foreach ($caseIds as $caseId)
        {
            self::lockOpenCaseRow($db, (int)$caseId);
        }

        if (!$isInsert)
        {
            $incident = $db->fetchRow('SELECT case_id FROM xf_usips_ncmec_incident WHERE incident_id = ? FOR UPDATE', $incidentId);
            if (!$incident || (int)$incident['case_id'] !== $expectedOldCaseId)
            {
                throw new \RuntimeException('The incident case assignment changed; retry the operation.');
            }
        }
    }

    private static function lockIncidentAssociationRows(\XF\App $app, int $incidentId): void
    {
        $db = $app->db();
        $incidentSnapshot = $db->fetchRow('SELECT case_id FROM xf_usips_ncmec_incident WHERE incident_id = ?', $incidentId);
        if (!$incidentSnapshot)
        {
            throw new \RuntimeException('The incident no longer exists; the evidence change was not applied.');
        }

        $caseId = (int)$incidentSnapshot['case_id'];
        if ($caseId > 0)
        {
            self::lockOpenCaseRow($db, $caseId);
        }

        $incident = $db->fetchRow('SELECT case_id FROM xf_usips_ncmec_incident WHERE incident_id = ? FOR UPDATE', $incidentId);
        if (!$incident || (int)$incident['case_id'] !== $caseId)
        {
            throw new \RuntimeException('The incident case assignment changed; retry the evidence change.');
        }
    }

    private static function lockOpenCaseRow(\XF\Db\AbstractAdapter $db, int $caseId): void
    {
        $case = $db->fetchRow('SELECT finalized_on, submitted_on
            FROM xf_usips_ncmec_case WHERE case_id = ? FOR UPDATE', $caseId);
        if (!$case)
        {
            throw new \RuntimeException('The NCMEC case no longer exists; the change was not applied.');
        }
        if ($case['finalized_on'] || $case['submitted_on'])
        {
            throw new CaseClosedToChanges();
        }
    }

    /**
     * Roll back exactly one transaction level: the one an entity delete()/save()
     * opened around a failing source hook. Unlike rollbackAll() this leaves an
     * unrelated outer caller transaction (and its savepoints) intact.
     */
    public static function abortOwnedWriteLevel(\XF\Db\AbstractAdapter $db): void
    {
        try
        {
            $db->rollback();
        }
        catch (\Throwable $ignored)
        {
            // The initiating failure is the one worth reporting.
        }
    }

    private static function savepointDepth(\XF\Db\AbstractAdapter $db): int
    {
        $property = new \ReflectionProperty(\XF\Db\AbstractAdapter::class, 'savePoints');
        $property->setAccessible(true);
        $savePoints = $property->getValue($db);

        return is_array($savePoints) ? count($savePoints) : 0;
    }

    private static function rollbackToTransactionState(
        \XF\Db\AbstractAdapter $db,
        bool $startedInTransaction,
        int $startingSavepointDepth
    ): bool
    {
        try
        {
            while ($db->inTransaction() && self::savepointDepth($db) > $startingSavepointDepth)
            {
                $db->rollback();
            }

            if (!$startedInTransaction && $db->inTransaction())
            {
                if (self::savepointDepth($db) !== 0)
                {
                    throw new \LogicException('The transaction depth could not be restored.');
                }
                $db->rollback();
            }

            return $db->inTransaction() === $startedInTransaction
                && self::savepointDepth($db) === $startingSavepointDepth;
        }
        catch (\Throwable $rollbackError)
        {
            // A transaction-aborting database error may already have invalidated
            // the caller's transaction. Clear the adapter rather than leak a
            // transaction or replace the initiating failure with a rollback one.
            try
            {
                $db->rollbackAll();
            }
            catch (\Throwable $ignored)
            {
            }
            return false;
        }
    }

    public static function records(\XF\App $app, int $reportId): array
    {
        $records = $app->db()->fetchAllColumn('SELECT decision.review_data FROM xf_usips_ncmec_recovery_log AS decision
            INNER JOIN xf_usips_ncmec_report AS report ON report.report_id = decision.report_id
                AND report.case_id = decision.case_id AND report.ncmec_report_id = decision.ncmec_report_id
            WHERE decision.report_id = ? AND decision.action = ? AND report.submitted_on > 0
                AND report.superseded_by_report_id IS NULL ORDER BY decision.recovery_id DESC LOCK IN SHARE MODE',
            [$reportId, 'missing-review']);
        return array_map(static fn($json) => json_decode($json, true, 512, JSON_THROW_ON_ERROR), $records);
    }

    public static function contentMissing(\XF\App $app, array $association, array $records): bool
    {
        if (!self::matches($association, 'missing_content', $records))
        {
            return false;
        }
        return ContentExport::sourceMissing($app, $association);
    }

    public static function attachmentMissing(\XF\App $app, array $association, array $records): bool
    {
        if (!self::matches($association, 'missing_attachments', $records))
        {
            return false;
        }
        return !$app->db()->fetchOne('SELECT data_id FROM xf_attachment_data WHERE data_id = ? LOCK IN SHARE MODE',
            (int)$association['data_id']);
    }

    private static function matches(array $association, string $key, array $records): bool
    {
        $snapshot = ContentExport::fingerprint($association);
        foreach ($records as $record)
        {
            if (!in_array((int)$association['user_id'], $record['subject_user_ids'] ?? [], true))
            {
                continue;
            }
            foreach ($record[$key] ?? [] as $missing)
            {
                if (($missing['source_status'] ?? '') === 'missing-at-review'
                    && is_string($missing['association_snapshot'] ?? null)
                    && hash_equals($missing['association_snapshot'], $snapshot))
                {
                    return true;
                }
            }
        }
        return false;
    }
}