<?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\UnitTest;
use seekquarry\yioop\library\mail\MailSiteFactory;

/**
 * Gathers the tests for MailSiteFactory: the rule that decides whether
 * a member account may use a given email address, and the outbound
 * spool state machine that relays authenticated local mail to remote
 * recipients. The address rule is a plain function of its arguments, so
 * those cases need no set-up; the outbound-spool cases build a temporary
 * spool directory through their own helper first.
 *
 * @author Chris Pollett
 */
class MailSiteFactoryTest extends UnitTest
{
    /**
     * Probe exposing the spool with a scripted delivery outcome, built
     * by the outbound-spool cases.
     * @var ProbeMailSiteFactoryForOutbound
     */
    public $probe;
    /**
     * Absolute path of the temporary spool directory an outbound-spool
     * case uses, empty when none is outstanding.
     * @var string
     */
    public $spool = "";
    /**
     * Required by the test runner. The address-rule cases are plain
     * functions of their arguments and the outbound-spool cases build
     * their own spool through a helper, so there is nothing to do here.
     */
    public function setUp()
    {
    }
    /**
     * Builds a fresh temporary spool directory and a probe bound to it,
     * called at the start of each outbound-spool case.
     */
    public function setUpOutboundSpool()
    {
        $this->spool = sys_get_temp_dir() . "/yioop_outbound_" .
            uniqid("", true);
        ProbeMailSiteFactoryForOutbound::$spool_override =
            $this->spool;
        ProbeMailSiteFactoryForOutbound::$delivery_result =
            ['ok' => true, 'error' => ''];
        ProbeMailSiteFactoryForOutbound::$bounces = [];
        $this->probe = new ProbeMailSiteFactoryForOutbound();
    }
    /**
     * Removes the temporary spool directory an outbound-spool case made;
     * the address-rule cases leave nothing on disk.
     */
    public function tearDown()
    {
        if (is_dir($this->spool)) {
            foreach (glob($this->spool . "/*") as $path) {
                @unlink($path);
            }
            @rmdir($this->spool);
        }
    }
    /**
     * The bot's own address on a managed domain is always refused, even
     * when same-domain accounts are otherwise allowed.
     */
    public function botAddressAlwaysRefusedTestCase()
    {
        $this->assertTrue(MailSiteFactory::accountEmailRefused(
            "bot@example.com", "bot", ["example.com"], false),
            "bot address on a managed domain is refused");
    }
    /**
     * An ordinary person on a managed domain is allowed by default, so
     * an in-house install where everyone shares the domain still works.
     */
    public function sameDomainAllowedByDefaultTestCase()
    {
        $this->assertFalse(MailSiteFactory::accountEmailRefused(
            "chris@example.com", "bot", ["example.com"], false),
            "non-bot same-domain address is allowed when not strict");
    }
    /**
     * Turning on the strict flag refuses every address on a managed
     * domain, not just the bot's.
     */
    public function sameDomainRefusedWhenStrictTestCase()
    {
        $this->assertTrue(MailSiteFactory::accountEmailRefused(
            "chris@example.com", "bot", ["example.com"], true),
            "non-bot same-domain address is refused when strict");
    }
    /**
     * An address on a domain the site does not handle is allowed even
     * under the strict flag.
     */
    public function otherDomainAllowedTestCase()
    {
        $this->assertFalse(MailSiteFactory::accountEmailRefused(
            "chris@other.com", "bot", ["example.com"], true),
            "address off the managed domains is allowed");
    }
    /**
     * The bot is refused at any of several managed domains, not only the
     * first one.
     */
    public function botRefusedAtAnyManagedDomainTestCase()
    {
        $this->assertTrue(MailSiteFactory::accountEmailRefused(
            "bot@two.com", "bot", ["one.com", "two.com"], false),
            "bot address is refused at any managed domain");
    }
    /**
     * The localhost placeholder that a site without mail domains
     * reports is never treated as managed, so on such a site no address
     * is refused.
     */
    public function localhostNeverManagedTestCase()
    {
        $this->assertFalse(MailSiteFactory::accountEmailRefused(
            "bot@localhost", "bot", ["localhost"], true),
            "localhost is not a managed domain");
    }
    /**
     * Both the mailbox name and the domain are compared without regard
     * to letter case.
     */
    public function caseInsensitiveTestCase()
    {
        $this->assertTrue(MailSiteFactory::accountEmailRefused(
            "BOT@EXAMPLE.COM", "bot", ["Example.com"], false),
            "comparison ignores letter case");
    }
    /**
     * A string with no at-sign is not an address and is never refused.
     */
    public function malformedAddressAllowedTestCase()
    {
        $this->assertFalse(MailSiteFactory::accountEmailRefused(
            "not-an-address", "bot", ["example.com"], true),
            "a string without an at-sign is not refused");
    }
    /**
     * Queues all the spool files for one message and counts them.
     * @return int number of envelope files in the spool
     */
    protected function envelopeCount()
    {
        if (!is_dir($this->spool)) {
            return 0;
        }
        return count(glob($this->spool . "/*.envelope"));
    }
    /**
     * The onOutbound hook writes a matching eml and envelope pair
     * carrying the sender, recipients, and a zero attempt count.
     */
    public function enqueueWritesSpoolPairTestCase()
    {
        $this->setUpOutboundSpool();
        $this->probe->enqueue(
            ['from' => 'chris@pollett.org',
            'recipients' => ['carol@sjsu.edu'],
            'bytes' => "Subject: hi\r\n\r\nbody"], []);
        $this->assertEqual(1, $this->envelopeCount(),
            "one envelope queued");
        $emls = glob($this->spool . "/*.eml");
        $this->assertEqual(1, count($emls),
            "one message body queued");
        $envelopes = glob($this->spool . "/*.envelope");
        $record = json_decode(
            file_get_contents($envelopes[0]), true);
        $this->assertEqual('chris@pollett.org', $record['from'],
            "sender recorded");
        $this->assertEqual(0, $record['attempts'],
            "attempt counter starts at zero");
    }
    /**
     * A successful drain delivers the message and removes both of
     * its spool files.
     */
    public function successfulDrainClearsSpoolTestCase()
    {
        $this->setUpOutboundSpool();
        $this->probe->enqueue(
            ['from' => 'chris@pollett.org',
            'recipients' => ['carol@sjsu.edu'],
            'bytes' => "Subject: hi\r\n\r\nbody"], []);
        ProbeMailSiteFactoryForOutbound::$delivery_result =
            ['ok' => true, 'error' => ''];
        $stats = $this->probe->drain();
        $this->assertEqual(1, $stats['sent'], "one message sent");
        $this->assertEqual(0, $this->envelopeCount(),
            "spool cleared after successful delivery");
    }
    /**
     * A transient failure leaves the message queued, increments
     * its attempt counter, and schedules a later retry.
     */
    public function transientFailureRetriesTestCase()
    {
        $this->setUpOutboundSpool();
        $this->probe->enqueue(
            ['from' => 'chris@pollett.org',
            'recipients' => ['carol@sjsu.edu'],
            'bytes' => "Subject: hi\r\n\r\nbody"], []);
        ProbeMailSiteFactoryForOutbound::$delivery_result =
            ['ok' => false, 'error' => 'could not connect'];
        $stats = $this->probe->drain();
        $this->assertEqual(1, $stats['retried'],
            "message retried, not sent or bounced");
        $this->assertEqual(1, $this->envelopeCount(),
            "message still queued after transient failure");
        $envelopes = glob($this->spool . "/*.envelope");
        $record = json_decode(
            file_get_contents($envelopes[0]), true);
        $this->assertEqual(1, $record['attempts'],
            "attempt counter incremented");
        $this->assertTrue($record['next_attempt'] > time(),
            "retry scheduled in the future");
    }
    /**
     * Once the attempt cap is reached the message is bounced to its
     * local sender and removed from the spool.
     */
    public function permanentFailureBouncesTestCase()
    {
        $this->setUpOutboundSpool();
        $this->probe->enqueue(
            ['from' => 'chris@pollett.org',
            'recipients' => ['carol@sjsu.edu'],
            'bytes' => "Subject: hi\r\n\r\nbody"], []);
        ProbeMailSiteFactoryForOutbound::$delivery_result =
            ['ok' => false, 'error' => 'mailbox unavailable'];
        $envelopes = glob($this->spool . "/*.envelope");
        $record = json_decode(
            file_get_contents($envelopes[0]), true);
        $record['attempts'] = 2;
        file_put_contents($envelopes[0], json_encode($record));
        $stats = $this->probe->drain();
        $this->assertEqual(1, $stats['bounced'],
            "message bounced at the attempt cap");
        $this->assertEqual(0, $this->envelopeCount(),
            "spool cleared after a bounce");
        $bounces = ProbeMailSiteFactoryForOutbound::$bounces;
        $this->assertEqual(1, count($bounces),
            "one bounce delivered");
        $this->assertEqual('chris@pollett.org', $bounces[0]['to'],
            "bounce returned to the local sender");
    }
}
/**
 * MailSiteFactory subclass that redirects the spool to a temporary
 * directory, scripts the direct-MX delivery outcome, and captures
 * bounces instead of posting them to a real mailbox, so the spool
 * state machine can be tested without the network or a live store.
 *
 * @author Chris Pollett chris@pollett.org
 */
class ProbeMailSiteFactoryForOutbound extends MailSiteFactory
{
    /**
     * Temporary spool directory used in place of MAIL_DIR/outbound.
     * @var string
     */
    public static $spool_override = "";
    /**
     * Scripted result returned by the overridden delivery step.
     * @var array
     */
    public static $delivery_result = ['ok' => true, 'error' => ''];
    /**
     * Captured bounce notices: each entry has 'to' and 'error'.
     * @var array
     */
    public static $bounces = [];
    /**
     * Returns the temporary spool directory for tests.
     * @return string spool directory path
     */
    public static function outboundSpoolDir()
    {
        return self::$spool_override;
    }
    /**
     * Calls the onOutbound enqueue path under test.
     * @param array $info outbound details (from, recipients, bytes)
     * @param array $context unused session context
     */
    public function enqueue($info, $context)
    {
        self::enqueueOutbound($info, $context);
    }
    /**
     * Runs the drain under test.
     * @param int|null $now current time override
     * @return array drain stats
     */
    public function drain($now = null)
    {
        return self::drainOutbound($now);
    }
    /**
     * Returns the scripted delivery result instead of doing real
     * MX delivery.
     * @param array $envelope decoded envelope record
     * @param string $eml_path path to message bytes
     * @return array delivery outcome
     */
    protected static function deliverOutboundFile($envelope,
        $eml_path)
    {
        return self::$delivery_result;
    }
    /**
     * Captures the bounce target and reason rather than building a
     * MailSite and posting to a mailbox.
     * @param array $envelope decoded envelope record
     * @param string $eml_path path to message bytes
     * @param string $error final delivery error
     * @return void
     */
    protected static function bounceOutbound($envelope, $eml_path,
        $error)
    {
        self::$bounces[] = ['to' => $envelope['from'] ?? '',
            'error' => $error];
    }
}
