<?php
/**
 * SeekQuarry/Yioop --
 * Open Source Pure PHP Search Engine, Crawler, and Indexer
 *
 * Copyright (C) 2009 - 2026  Chris Pollett chris@pollett.org
 *
 * LICENSE:
 *
 * 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 3 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, see <https://www.gnu.org/licenses/>.
 *
 * END LICENSE
 *
 * @author Chris Pollett chris@pollett.org
 * @license https://www.gnu.org/licenses/ GPL3
 * @link https://www.seekquarry.com/
 * @copyright 2009 - 2026
 * @filesource
 */
namespace seekquarry\yioop\tests;

use seekquarry\yioop\library\mail\ImapMailBackend;
use seekquarry\yioop\library\UnitTest;

/**
 * Unit tests for the resilient message-listing parts of
 * ImapMailBackend: the sequence-keyed envelope parser and the
 * adaptive fetch loop that keeps an inbox view filling even when a
 * server struggles with large requests or has a corrupt message.
 *
 * The tests drive the backend with a scripted stand-in for the IMAP
 * client, so each rule (batch growth, halving on failure, a
 * placeholder for a message that cannot be fetched, order
 * preservation) is checked with no live mail server. The backend's
 * protected methods are reached through a tiny subclass below.
 *
 * @author Chris Pollett
 */
class ImapMailBackendTest extends UnitTest
{
    /**
     * The backend under test, rebuilt before each case
     * @var object
     */
    public $backend;
    /**
     * The scripted stand-in IMAP client the backend talks to
     * @var object
     */
    public $client;
    /**
     * Builds a backend wired to a scripted client and a do-nothing
     * logger, ready for a case to script replies and call in.
     */
    public function setUp()
    {
        $this->client = new FakeListingClient();
        $this->backend = new TestableImapBackend([],
            new FakeListingComponent());
        $this->backend->useClient($this->client);
    }
    /**
     * No tearDown
     */
    public function tearDown()
    {
    }
    /**
     * defaultFolder returns the account's configured folder, and
     * falls back to INBOX when none is set on the account.
     */
    public function defaultFolderTestCase()
    {
        $this->assertEqual("INBOX", $this->backend->defaultFolder(),
            "an account with no default folder opens to INBOX");
        $configured = new TestableImapBackend(
            ["DEFAULT_FOLDER" => "Archive"],
            new FakeListingComponent());
        $this->assertEqual("Archive", $configured->defaultFolder(),
            "a configured default folder is used");
    }
    /**
     * annotateUnreadCounts asks the server for each selectable
     * folder's unread count and records it, then serves a second
     * pass from the cache without asking the server again.
     */
    public function annotateUnreadCountsTestCase()
    {
        $_SESSION = [];
        $backend = new TestableImapBackend(["ID" => 7],
            new FakeListingComponent());
        $backend->useClient($this->client);
        $this->client->responses = [
            ['status' => 'OK',
                'untagged' => ['* STATUS "INBOX" (UNSEEN 3)']],
            ['status' => 'OK',
                'untagged' => ['* STATUS "Sent" (UNSEEN 0)']]];
        $folders = [
            ['NAME' => 'INBOX', 'SELECTABLE' => true],
            ['NAME' => 'Sent', 'SELECTABLE' => true]];
        $backend->annotateUnreadCounts($folders);
        $this->assertEqual(3, $folders[0]['UNREAD'],
            'INBOX unread count comes from the STATUS reply');
        $this->assertEqual(0, $folders[1]['UNREAD'],
            'Sent unread count comes from the STATUS reply');
        $sent_after_first = count($this->client->sent);
        $folders_again = [
            ['NAME' => 'INBOX', 'SELECTABLE' => true],
            ['NAME' => 'Sent', 'SELECTABLE' => true]];
        $backend->annotateUnreadCounts($folders_again);
        $this->assertEqual(3, $folders_again[0]['UNREAD'],
            'the second pass serves INBOX from the cache');
        $this->assertEqual($sent_after_first,
            count($this->client->sent),
            'the cached pass sends no further STATUS commands');
        $_SESSION = [];
    }
    /**
     * Builds one FETCH untagged line carrying a UID, a flags list,
     * and an envelope, in the form a real server sends, so the
     * parser and loop get realistic input.
     *
     * @param int $seq the sequence number for the line
     * @param int $uid the message UID
     * @param string $flags the flags list contents, for example
     *      "\\Seen" or the empty string
     * @param string $subject the subject to embed in the envelope
     * @return string a single untagged FETCH line
     */
    public function fetchLine($seq, $uid, $flags, $subject)
    {
        return '* ' . $seq . ' FETCH (UID ' . $uid . ' FLAGS (' .
            $flags . ') ENVELOPE (' .
            '"Wed, 13 May 2026 20:59:19 +0000" "' . $subject . '" ' .
            '(("Jane Roe" NIL "jane" "example.com")) ' .
            '(("Jane Roe" NIL "jane" "example.com")) ' .
            '(("Jane Roe" NIL "jane" "example.com")) ' .
            '(("You" NIL "you" "pollett.org")) NIL NIL NIL ' .
            '"<msg-' . $uid . '@example.com>"))';
    }
    /**
     * A successful FETCH reply, ready to push onto the client's
     * script.
     *
     * @param array $untagged the untagged lines to return
     * @return array a reply with OK status
     */
    public function okReply($untagged)
    {
        return ['status' => 'OK', 'untagged' => $untagged,
            'detail' => ''];
    }
    /**
     * parseSeqEnvelopes should read the sequence number, UID, flag
     * states, and envelope fields off a FETCH line, leave the
     * subject and sender raw for the controller to clean, and derive
     * the sender display name.
     */
    public function parseSeqEnvelopesTestCase()
    {
        $line = $this->fetchLine(5, 100, '\\Seen', 'Hello there');
        $rows = $this->backend->callParseSeqEnvelopes([$line]);
        $this->assertEqual(1, count($rows), "one line yields one row");
        $row = $rows[0];
        $this->assertEqual(5, $row['SEQ'], "sequence number is read");
        $this->assertEqual(100, $row['UID'], "UID is read");
        $this->assertFalse($row['IS_UNREAD'],
            "the Seen flag marks the message read");
        $this->assertEqual('Hello there', $row['SUBJECT'],
            "subject comes through raw");
        $this->assertEqual('Jane Roe <jane@example.com>',
            $row['FROM'], "sender address is formatted from envelope");
        $this->assertEqual('Jane Roe', $row['FROM_NAME'],
            "sender display name is derived");
    }
    /**
     * parseSeqEnvelopes should treat a message with no Seen flag as
     * unread.
     */
    public function parseSeqEnvelopesUnreadTestCase()
    {
        $line = $this->fetchLine(6, 101, '', 'Unseen one');
        $rows = $this->backend->callParseSeqEnvelopes([$line]);
        $this->assertTrue($rows[0]['IS_UNREAD'],
            "no Seen flag means the message is unread");
    }
    /**
     * adaptiveFetch should return one row per sequence number, in
     * the requested order, when a single batch succeeds.
     */
    public function adaptiveFetchAllAtOnceTestCase()
    {
        $this->client->responses = [
            $this->okReply([
                $this->fetchLine(1, 100, '', 'One'),
                $this->fetchLine(2, 101, '', 'Two'),
                $this->fetchLine(3, 102, '', 'Three'),
            ]),
        ];
        $rows = $this->backend->callAdaptiveFetch([1, 2, 3],
            'Unreadable');
        $this->assertEqual([1, 2, 3],
            [$rows[0]['SEQ'], $rows[1]['SEQ'], $rows[2]['SEQ']],
            "rows come back in the requested order");
        $this->assertEqual(1, count($this->client->sent),
            "a clean fetch takes a single request");
    }
    /**
     * adaptiveFetch should recover from a failed large batch by
     * halving and retrying, and still return every message.
     */
    public function adaptiveFetchHalvesOnFailureTestCase()
    {
        /* four messages: the first batch of four fails, so the loop
           halves to two and fetches [1,2], then grows back to two
           and fetches [3,4]. */
        $this->client->responses = [
            ['status' => 'NO', 'untagged' => [], 'detail' => 'busy'],
            $this->okReply([
                $this->fetchLine(1, 100, '', 'One'),
                $this->fetchLine(2, 101, '', 'Two'),
            ]),
            $this->okReply([
                $this->fetchLine(3, 102, '', 'Three'),
                $this->fetchLine(4, 103, '', 'Four'),
            ]),
        ];
        $rows = $this->backend->callAdaptiveFetch([1, 2, 3, 4],
            'Unreadable');
        $this->assertEqual(4, count($rows),
            "every message is recovered after halving");
        $this->assertEqual([1, 2, 3, 4],
            array_map(function ($row) {
                return $row['SEQ'];
            }, $rows),
            "recovered rows keep the requested order");
    }
    /**
     * adaptiveFetch should drop in a placeholder for a single
     * message that fails even on its own, keep the good messages
     * around it, and mark the placeholder with the passed-in
     * subject.
     */
    public function adaptiveFetchPlaceholderTestCase()
    {
        /* two messages: the batch of two fails, the loop halves to
           one, fetches seq 1 fine, then seq 2 fails on its own and
           becomes a placeholder. */
        $this->client->responses = [
            ['status' => 'NO', 'untagged' => [], 'detail' => 'busy'],
            $this->okReply([$this->fetchLine(1, 100, '', 'One')]),
            ['status' => 'NO', 'untagged' => [], 'detail' => 'bad'],
        ];
        $rows = $this->backend->callAdaptiveFetch([1, 2],
            'Unreadable message');
        $this->assertEqual(2, count($rows),
            "the good message and the placeholder both appear");
        $this->assertEqual('One', $rows[0]['SUBJECT'],
            "the fetchable message keeps its subject");
        $this->assertTrue(!empty($rows[1]['IS_PLACEHOLDER']),
            "the unfetchable message becomes a placeholder");
        $this->assertEqual('Unreadable message', $rows[1]['SUBJECT'],
            "the placeholder shows the passed-in subject");
    }
    /**
     * A SELECT reply carrying an EXISTS count.
     *
     * @param int $exists the message count to report
     * @return array a SELECT reply
     */
    public function selectReply($exists)
    {
        return ['status' => 'OK',
            'untagged' => ['* ' . $exists . ' EXISTS'],
            'detail' => ''];
    }
    /**
     * A CAPABILITY reply that does or does not advertise SORT.
     *
     * @param bool $has_sort whether to advertise the SORT extension
     * @return array a CAPABILITY reply
     */
    public function capabilityReply($has_sort)
    {
        $line = '* CAPABILITY IMAP4rev1' .
            ($has_sort ? ' SORT' : '');
        return ['status' => 'OK', 'untagged' => [$line],
            'detail' => ''];
    }
    /**
     * A SORT reply listing sequence numbers in order.
     *
     * @param array $seqs the ordered sequence numbers
     * @return array a SORT reply
     */
    public function sortReply($seqs)
    {
        return ['status' => 'OK',
            'untagged' => ['* SORT ' . implode(' ', $seqs)],
            'detail' => ''];
    }
    /**
     * A FETCH reply with one envelope line per sequence number.
     *
     * @param array $seqs the sequence numbers to include
     * @return array a FETCH reply
     */
    public function fetchReply($seqs)
    {
        $lines = [];
        foreach ($seqs as $seq) {
            $lines[] = $this->fetchLine($seq, 100 + $seq, '',
                'Subject ' . $seq);
        }
        return $this->okReply($lines);
    }
    /**
     * listMessages on the default newest-first view should select,
     * range-fetch the newest window, and return the rows newest-
     * first with no sort or search sent.
     */
    public function listMessagesFastPathTestCase()
    {
        $this->client->responses = [
            $this->selectReply(3),
            $this->capabilityReply(false),
            $this->fetchReply([1, 2, 3]),
        ];
        $result = $this->backend->listMessages('INBOX',
            ['window' => 25, 'unreadable_subject' => 'x']);
        $this->assertEqual('range', $result['mode'],
            "the default view pages by sequence range");
        $this->assertEqual([3, 2, 1],
            array_map(function ($row) {
                return $row['SEQ'];
            }, $result['messages']),
            "rows come back newest-first");
        $this->assertEqual(3, $result['total'],
            "total reflects the folder's message count");
        $this->assertFalse($result['has_more'],
            "a window covering the whole folder has no more");
    }
    /**
     * listMessages with a non-default sort should ask the server to
     * SORT and then fetch the messages in the order it returned.
     */
    public function listMessagesServerSortTestCase()
    {
        $this->client->responses = [
            $this->selectReply(3),
            $this->capabilityReply(true),
            $this->sortReply([2, 1, 3]),
            $this->fetchReply([2, 1, 3]),
        ];
        $result = $this->backend->listMessages('INBOX',
            ['window' => 25, 'unreadable_subject' => 'x',
            'sort' => ['key' => 'subject', 'reverse' => false]]);
        $this->assertEqual('sorted', $result['mode'],
            "a non-default sort pages by position in the sorted list");
        $this->assertEqual([2, 1, 3],
            array_map(function ($row) {
                return $row['SEQ'];
            }, $result['messages']),
            "rows follow the server's SORT order");
        $this->assertTrue(strpos(implode('|', $this->client->sent),
            'SORT (SUBJECT)') !== false,
            "a SORT command was issued for the subject sort");
    }
    /**
     * When the request carries a sort_supported hint, listMessages
     * trusts it and does not ask the server for its capabilities.
     */
    public function listMessagesSortHintTestCase()
    {
        $this->client->responses = [
            $this->selectReply(3),
            $this->sortReply([2, 1, 3]),
            $this->fetchReply([2, 1, 3]),
        ];
        $result = $this->backend->listMessages('INBOX',
            ['window' => 25, 'unreadable_subject' => 'x',
            'sort_supported' => true,
            'sort' => ['key' => 'subject', 'reverse' => false]]);
        $this->assertEqual([2, 1, 3],
            array_map(function ($row) {
                return $row['SEQ'];
            }, $result['messages']),
            "the sorted view still works using the hint");
        $this->assertTrue(strpos(implode('|', $this->client->sent),
            'CAPABILITY') === false,
            "no CAPABILITY was sent when the hint was supplied");
    }
    /**
     * listMessages with a range cursor should fetch the older window
     * just below the oldest sequence already shown.
     */
    public function listMessagesLoadMoreRangeTestCase()
    {
        $this->client->responses = [
            $this->selectReply(20),
            $this->capabilityReply(false),
            $this->fetchReply([5, 6, 7, 8, 9]),
        ];
        $result = $this->backend->listMessages('INBOX',
            ['window' => 5, 'unreadable_subject' => 'x',
            'cursor' => ['mode' => 'range', 'before' => 10]]);
        $this->assertEqual([9, 8, 7, 6, 5],
            array_map(function ($row) {
                return $row['SEQ'];
            }, $result['messages']),
            "the older window returns newest-first");
        $this->assertTrue($result['has_more'],
            "more remains below sequence five");
        $this->assertEqual(5, $result['next_cursor']['before'],
            "the next cursor stops just below this window");
    }
}
/**
 * A scripted stand-in for ImapClient. Each call to send() returns
 * the next reply queued in $responses (or throws it, when the queued
 * item is an exception) and records the command in $sent, so a test
 * can both drive the loop and check what it asked for.
 *
 * @author Chris Pollett
 */
class FakeListingClient
{
    /**
     * Queue of replies (or exceptions) send() hands back in turn
     * @var array
     */
    public $responses = [];
    /**
     * Commands that have been sent, in order
     * @var array
     */
    public $sent = [];
    /**
     * Records the command and returns (or throws) the next scripted
     * reply.
     *
     * @param string $command the IMAP command line
     * @param mixed $timeout ignored; present to match the real
     *      client's shape
     * @return array the next scripted reply
     */
    public function send($command, $timeout = null)
    {
        $this->sent[] = $command;
        $next = array_shift($this->responses);
        if ($next instanceof \Exception) {
            throw $next;
        }
        return $next;
    }
}
/**
 * A do-nothing stand-in for the component the backend logs through,
 * so listing tests do not write to the mail log.
 *
 * @author Chris Pollett
 */
class FakeListingComponent
{
    /**
     * Swallows a log call.
     *
     * @param string $tag the event tag
     * @param array $fields the log fields
     */
    public function userMailLog($tag, $fields = [])
    {
    }
}
/**
 * Exposes the backend's protected listing methods so the test can
 * call them directly.
 *
 * @author Chris Pollett
 */
class TestableImapBackend extends ImapMailBackend
{
    /**
     * Injects a stand-in client so the listing methods talk to it
     * instead of opening a real connection.
     *
     * @param object $client the stand-in IMAP client
     */
    public function useClient($client)
    {
        $this->client = $client;
    }
    /**
     * Calls the protected parseSeqEnvelopes.
     *
     * @param array $untagged untagged FETCH lines
     * @return array the parsed rows
     */
    public function callParseSeqEnvelopes($untagged)
    {
        return $this->parseSeqEnvelopes($untagged);
    }
    /**
     * Calls the protected adaptiveFetch.
     *
     * @param array $sequence_numbers the sequence numbers to fetch
     * @param string $unreadable_subject placeholder subject text
     * @return array the resulting rows
     */
    public function callAdaptiveFetch($sequence_numbers,
        $unreadable_subject)
    {
        return $this->adaptiveFetch($sequence_numbers,
            $unreadable_subject);
    }
}
