<?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\atto\MailSite;
use seekquarry\atto\FileMailStorage;
use seekquarry\atto\RamMailStorage;
use seekquarry\yioop\library\UnitTest;
/**
* Drives the daemon's command-fiber frame with a stub command that
* yields once, standing in for a store-lock wait.
*/
class CommandFiberProbeMailSite extends MailSite
{
/** @var int how many times the stub command ran */
public $process_calls = 0;
/**
* Stub command: yields on its first run (as a contended store lock
* would), then reports no more input.
* @param int $key connection key
* @return bool true on the first run so the caller loops
*/
protected function processOne($key)
{
$this->process_calls++;
if ($this->process_calls === 1) {
\Fiber::suspend();
return true;
}
return false;
}
/**
* Registers a minimal connection context so the frame treats the
* key as a live connection.
* @param int $key connection key
* @return void
*/
public function registerContext($key)
{
$this->in_streams[self::CONTEXT][$key] = ['PROTOCOL' => 'IMAP'];
}
/**
* @param int $key connection key
* @return void
*/
public function drive($key)
{
$this->driveConnectionFiber($key);
}
/**
* @return void
*/
public function resumeAll()
{
$this->resumePendingFibers();
}
/**
* @return int number of parked connection fibers
*/
public function pendingCount()
{
return count($this->pending_fibers);
}
}
/**
* Exposes FileMailStorage's protected cooperative lock helper so a test
* can drive it directly, without standing up a whole mail store.
*/
class CooperativeFlockProbe extends FileMailStorage
{
/**
* Public wrapper around the protected cooperativeFlock().
*
* @param resource $handle open file handle to lock
* @param int $operation the lock to take, LOCK_SH or LOCK_EX
* @return bool true once the lock is held
*/
public static function probe($handle, $operation)
{
return self::cooperativeFlock($handle, $operation);
}
}
/**
* Exposes FileMailStorage's bounded folder-index cache so a test can
* drive its store-and-evict and most-recently-used promotion entirely
* in memory, without standing up a real mail store on disk.
*/
class FolderIndexCacheProbe extends FileMailStorage
{
/**
* Caches an empty index under a key, exercising the bounded
* insert that drops the least recently used folder when full.
*
* @param string $cache_key the cache key to store under
*/
public function store($cache_key)
{
$this->storeFolderIndex($cache_key, [], 0);
}
/**
* Reads a cached index back, which promotes its folder to most
* recently used.
*
* @param string $cache_key the cache key to read
* @return array|null the cached entry, or null on a miss
*/
public function fetch($cache_key)
{
return $this->cachedFolderIndex($cache_key);
}
}
/**
* MailSite subclass that captures queueWrite output into a string
* (or discards it when measuring memory) so the protected FETCH
* emitter can be exercised without a real client socket.
*
* @author Chris Pollett chris@pollett.org
*/
class ProbeMailSiteForFetch extends MailSite
{
/**
* Concatenated bytes passed to queueWrite during a call.
* @var string
*/
public $taken = "";
/**
* When true, queued bytes are counted but not retained, so a
* memory measurement reflects only what the emitter itself
* holds rather than the captured transcript.
* @var bool
*/
public $drop_taken = false;
/**
* Runs the protected FETCH emitter.
* @param int $sequence_number message sequence number
* @param array $meta message metadata (uid, flags, size,
* internal_date)
* @param string $body raw message bytes
* @param string $items the FETCH items list
* @param bool $is_uid_variant whether this is UID FETCH
* @param bool $mark_seen set true when a non-peek body is read
*/
public function emit($sequence_number, $meta, $body, $items,
$is_uid_variant, &$mark_seen)
{
$this->taken = "";
$this->imapEmitFetch(0, $sequence_number, $meta, $body,
$items, $is_uid_variant, $mark_seen);
}
/**
* Captures queued bytes instead of writing to a socket.
* @param int $key connection key (ignored)
* @param string $bytes bytes that would be sent to the client
* @return void
*/
protected function queueWrite($key, $bytes)
{
if (!$this->drop_taken) {
$this->taken .= $bytes;
}
}
}
/**
* MailSite subclass that exposes the protected handshake state
* machinery and supplies test sockets and a throwaway certificate.
*
* @author Chris Pollett chris@pollett.org
*/
class ProbeMailSiteForHandshake extends MailSite
{
/**
* Initializes the stream tables and server globals the
* handshake methods read, the way listen() would.
*/
public function __construct()
{
$this->default_server_globals = [
'TLS_HANDSHAKE_TIMEOUT' => 5,
'CONNECTION_TIMEOUT' => 1800,
];
$this->in_streams = [self::CONNECTION => [], self::DATA => [],
self::CONTEXT => [], self::MODIFIED_TIME => []];
$this->out_streams = [self::CONNECTION => [], self::DATA => [],
self::CONTEXT => [], self::MODIFIED_TIME => []];
}
/**
* Returns a connected pair of non-blocking sockets for tests.
* @return array two stream resources
*/
public function makePair()
{
$pair = stream_socket_pair(STREAM_PF_UNIX,
STREAM_SOCK_STREAM, 0);
stream_set_blocking($pair[0], 0);
stream_set_blocking($pair[1], 0);
return $pair;
}
/**
* Starts a handshake through the protected beginHandshake.
* @param resource $connection socket resource
* @param int $key stream key
* @param string $mode handshake mode
* @param string $protocol protocol name
* @param string $addr remote address
* @param int $port remote port
*/
public function begin($connection, $key, $mode, $protocol,
$addr, $port)
{
$this->beginHandshake($connection, $key, $mode, $protocol,
$addr, $port, null);
}
/**
* Seeds a pending handshake entry directly, as if a step had
* returned "needs more I/O", so the cull logic can be tested
* without a live TLS peer (a socketpair cannot complete a real
* handshake, and a raw TCP socket's "needs I/O" state is not
* deterministic in a unit test).
* @param resource $connection socket resource
* @param int $key stream key
* @param float $deadline absolute microtime deadline
*/
public function seedPending($connection, $key, $deadline)
{
$this->in_streams[self::CONNECTION][$key] = $connection;
$this->in_streams[self::MODIFIED_TIME][$key] = time();
$this->handshakes[$key] = [
'mode' => 'implicit',
'protocol' => 'SMTP',
'remote_addr' => '198.51.100.7',
'remote_port' => 12345,
'listener' => null,
'deadline' => $deadline,
];
}
/**
* Returns the pending-handshakes table for assertions.
* @return array the handshakes table
*/
public function pendingHandshakes()
{
return $this->handshakes;
}
/**
* Runs the cull pass that evicts stalled handshakes.
*/
public function cull()
{
$this->cullDeadStreams();
}
}
/**
* Minimal MailSite subclass that exposes the protected MIME entity
* parser so the bounds can be tested directly.
*
* @author Chris Pollett chris@pollett.org
*/
class ProbeMailSiteForMime extends MailSite
{
/**
* Parses raw entity bytes through the protected parser.
* @param string $bytes the entity bytes to parse
* @return array the parsed MIME entity
*/
public function parse($bytes)
{
return $this->imapParseEntity($bytes);
}
}
/**
* MailSite subclass that drives the protected SMTP DATA-phase consumer
* with a caller-owned buffer, and records whether the connection was
* dropped and what was written back, so the message-size cap can be
* checked without sockets.
*
* @author Chris Pollett chris@pollett.org
*/
class ProbeMailSiteForSmtpData extends MailSite
{
/** @var bool whether the consumer dropped the connection */
public $was_shut_down = false;
/** @var string bytes the consumer queued back to the client */
public $written = "";
/**
* Sets just the message-size limit the DATA consumer reads.
* @param int $max_message_len byte ceiling for one message
*/
public function __construct($max_message_len)
{
$this->default_server_globals = [
'MAX_MESSAGE_LEN' => $max_message_len,
];
}
/**
* Records a drop rather than closing a real socket.
* @param int $key connection key
* @return void
*/
protected function shutdownStream($key)
{
$this->was_shut_down = true;
}
/**
* Captures bytes bound for the client rather than queueing them
* on an out stream.
* @param int $key connection key
* @param string $bytes bytes to send
* @return void
*/
protected function queueWrite($key, $bytes)
{
$this->written .= $bytes;
}
/**
* Runs the protected DATA consumer once and returns its result and
* the buffer left after it ran.
* @param int $key connection key
* @param string $buffer bytes received so far in the DATA phase
* @param array $context per-session context
* @return array [bool consumed, string leftover buffer]
*/
public function feedData($key, $buffer, $context)
{
$result = $this->consumeSmtpDataPhase($key, $buffer, $context);
return [$result, $buffer];
}
}
/**
* Gathers the tests for the atto MailSite server in one place: its
* command fibers, cooperative file locking, fetch memory use, the TLS
* handshake reaper, MIME parsing, standard-folder provisioning, and
* UID-restricted expunge. Each group sets up only what it needs through
* its own helper, called at the start of its cases, since the server is
* self-contained and the cases run against in-memory or temporary
* storage with no network.
*
* @author Chris Pollett
*/
class MailSiteTest extends UnitTest
{
/**
* The probe mail server a group's cases drive by hand.
* @var object
*/
public $probe;
/**
* Path of the temporary lock file a cooperative-flock case makes,
* empty when no such file is outstanding.
* @var string
*/
public $path = "";
/**
* In-memory mail storage the folder and expunge cases work against.
* @var object
*/
public $storage;
/**
* The mail server the folder and expunge cases work against.
* @var object
*/
public $mail_site;
/**
* Name of the mailbox account the folder and expunge cases use.
* @var string
*/
public $account;
/**
* Uid of the first seeded message in the expunge cases.
* @var int
*/
public $first_uid;
/**
* Uid of the second seeded message in the expunge cases.
* @var int
*/
public $second_uid;
/**
* Uid of the third seeded message in the expunge cases.
* @var int
*/
public $third_uid;
/**
* Required by the test runner. Each group sets up its own
* state through its helper at the start of its cases, so
* there is nothing to do here.
*/
public function setUp()
{
}
/**
* Builds the state the CommandFiber cases need, called
* at the start of each of those cases.
*/
/**
* Builds the probe.
*/
public function setUpCommandFiber()
{
$this->probe = new CommandFiberProbeMailSite();
}
/**
* Builds the state the Flock cases need, called
* at the start of each of those cases.
*/
/**
* Makes a throwaway file for the lock cases.
*/
public function setUpFlock()
{
$this->path = tempnam(sys_get_temp_dir(), "msf");
}
/**
* Builds the state the Fetch cases need, called
* at the start of each of those cases.
*/
/**
* Builds the probe instance used by every case.
*/
public function setUpFetch()
{
$this->probe = new ProbeMailSiteForFetch();
}
/**
* Builds the state the Handshake cases need, called
* at the start of each of those cases.
*/
/**
* Builds the probe used by every case.
*/
public function setUpHandshake()
{
$this->probe = new ProbeMailSiteForHandshake();
}
/**
* Builds the state the Mime cases need, called
* at the start of each of those cases.
*/
/**
* Builds the probe instance used by every case.
*/
public function setUpMime()
{
$this->probe = new ProbeMailSiteForMime();
}
/**
* Builds the state the Folders cases need, called
* at the start of each of those cases.
*/
/**
* Provisions a fresh account with the standard folders.
*/
public function setUpFolders()
{
$this->account = "bob";
$this->mail_site = new MailSite();
$this->storage = new RamMailStorage();
$this->storage->ensureUser($this->account);
$this->storage->ensureStandardFolders($this->account);
}
/**
* Builds the state the Expunge cases need, called
* at the start of each of those cases.
*/
/**
* Seeds three INBOX messages, two of them flagged deleted.
*/
public function setUpExpunge()
{
$this->account = "alice";
$this->mail_site = new MailSite();
$this->storage = new RamMailStorage();
$this->mail_site->storage($this->storage);
for ($number = 1; $number <= 3; $number++) {
$this->storage->appendMessage($this->account, 'INBOX',
"Subject: message $number\r\n\r\nbody $number\r\n");
}
$messages = $this->storage->listMessages($this->account,
'INBOX');
$this->first_uid = $messages[0]['uid'];
$this->second_uid = $messages[1]['uid'];
$this->third_uid = $messages[2]['uid'];
$this->storage->setFlags($this->account, 'INBOX',
$this->first_uid, [MailSite::FLAG_DELETED]);
$this->storage->setFlags($this->account, 'INBOX',
$this->second_uid, [MailSite::FLAG_DELETED]);
}
/**
* Removes any temporary lock file a cooperative-flock case
* created; the other groups leave nothing on disk to clean.
*/
public function tearDown()
{
if ($this->path !== "" && is_file($this->path)) {
unlink($this->path);
}
}
/**
* A command that yields parks its fiber; resuming runs it to the end
* and unparks it.
*/
public function commandFiberParksAndDrainsTestCase()
{
$this->setUpCommandFiber();
$this->probe->registerContext(7);
$this->probe->drive(7);
$this->assertTrue($this->probe->pendingCount() === 1,
"a command that yields parks its fiber");
$this->assertTrue($this->probe->process_calls === 1,
"the fiber suspended mid-command");
$this->probe->resumeAll();
$this->assertTrue($this->probe->pendingCount() === 0,
"resuming finishes the command and unparks the fiber");
$this->assertTrue($this->probe->process_calls === 2,
"the command ran to completion once resumed");
}
/**
* With another handle holding the file exclusively, a shared-lock
* read started inside a fiber suspends instead of blocking; once the
* exclusive lock is released and the fiber is resumed, the read
* acquires its lock and finishes. This is what keeps one local-mailbox
* read from freezing every other web connection while the mail daemon
* is mid-write.
*/
public function sharedReadYieldsWhileExclusiveHeldTestCase()
{
$this->setUpFlock();
$blocker = fopen($this->path, "rb+");
flock($blocker, LOCK_EX);
$reader = fopen($this->path, "rb");
$acquired = false;
$fiber = new \Fiber(function () use ($reader, &$acquired) {
CooperativeFlockProbe::probe($reader, LOCK_SH);
$acquired = true;
});
$fiber->start();
$this->assertTrue($fiber->isSuspended(),
"the read suspends while the file is held exclusively");
$this->assertTrue($acquired === false,
"the lock has not been taken yet while suspended");
flock($blocker, LOCK_UN);
while ($fiber->isSuspended()) {
$fiber->resume();
}
$this->assertTrue($acquired,
"the read takes its lock once the exclusive lock frees");
fclose($reader);
fclose($blocker);
}
/**
* Outside a fiber the helper is a plain blocking lock, so the mail
* daemon and the command-line tools behave exactly as before; an
* uncontended shared lock is taken at once.
*/
public function uncontendedLockTakenDirectlyTestCase()
{
$this->setUpFlock();
$reader = fopen($this->path, "rb");
CooperativeFlockProbe::probe($reader, LOCK_SH);
$this->assertTrue(flock($reader, LOCK_UN),
"an uncontended shared lock is held and can be released");
fclose($reader);
}
/**
* A delivery's exclusive lock behaves the same way inside a fiber:
* while another handle holds the file, it suspends; once that frees
* and the fiber resumes, it takes the lock and reports success.
*/
public function exclusiveWriteYieldsWhileHeldTestCase()
{
$this->setUpFlock();
$blocker = fopen($this->path, "rb+");
flock($blocker, LOCK_EX);
$writer = fopen($this->path, "rb+");
$result = null;
$fiber = new \Fiber(function () use ($writer, &$result) {
$result = CooperativeFlockProbe::probe($writer, LOCK_EX);
});
$fiber->start();
$this->assertTrue($fiber->isSuspended(),
"the write lock suspends while the file is held");
flock($blocker, LOCK_UN);
while ($fiber->isSuspended()) {
$fiber->resume();
}
$this->assertTrue($result === true,
"the write lock is taken and reports success once free");
fclose($writer);
fclose($blocker);
}
/**
* A small FETCH of FLAGS and RFC822.SIZE produces the exact
* untagged response line with both items inside one set of
* parentheses.
*/
public function smallFetchWireFormatTestCase()
{
$this->setUpFetch();
$meta = ['uid' => 7, 'flags' => ['\\Seen'],
'internal_date' => 0, 'size' => 5];
$mark_seen = false;
$this->probe->emit(3, $meta, "hello", "FLAGS RFC822.SIZE",
false, $mark_seen);
$output = $this->probe->taken;
$this->assertEqual(
"* 3 FETCH (FLAGS (\\Seen) RFC822.SIZE 5)\r\n", $output,
"small fetch emits one correct untagged FETCH line");
}
/**
* A BODY[] fetch returns the whole message as an IMAP literal
* with the right byte count and trailing bytes.
*/
public function bodyFetchEmitsLiteralTestCase()
{
$this->setUpFetch();
$body = str_repeat("A", 1000);
$meta = ['uid' => 1, 'flags' => [],
'internal_date' => 0, 'size' => 1000];
$mark_seen = false;
$this->probe->emit(1, $meta, $body, "BODY[]", false,
$mark_seen);
$output = $this->probe->taken;
$this->assertTrue(
str_contains($output, "BODY[] {1000}\r\n"),
"body literal announces the correct byte count");
$this->assertTrue(str_ends_with($output, ")\r\n"),
"response closes the FETCH parenthesis");
$this->assertTrue($mark_seen,
"non-peek BODY[] marks the message seen");
}
/**
* Emitting a large body must not retain several copies of it.
* The emitter queues pieces directly instead of building a
* parts array and imploding, so peak memory growth across the
* call should stay well under the multiple-copy cost of the
* old path (which held three-plus copies). We allow up to two
* body-sizes of headroom and assert we stay below three.
*/
public function largeBodyDoesNotMultiplyCopiesTestCase()
{
$this->setUpFetch();
$size = 8388608;
$body = str_repeat("B", $size);
$meta = ['uid' => 2, 'flags' => [],
'internal_date' => 0, 'size' => $size];
$mark_seen = false;
$this->probe->drop_taken = true;
$before = memory_get_usage();
$this->probe->emit(2, $meta, $body, "BODY[]", false,
$mark_seen);
$after = memory_get_usage();
$growth = $after - $before;
$this->assertTrue($growth < 3 * $size,
"emitting a large body holds fewer than three copies");
}
/**
* Starting a handshake without a configured certificate drops
* the socket: prepareCrypto fails, so nothing is left pending.
*/
public function beginWithoutCertDropsTestCase()
{
$this->setUpHandshake();
list($near, $far) = $this->probe->makePair();
$key = (int) $near;
$this->probe->begin($near, $key, 'implicit', 'SMTP',
'198.51.100.7', 12345);
$pending = $this->probe->pendingHandshakes();
$this->assertTrue(!isset($pending[$key]),
"no certificate means no pending handshake");
is_resource($far) && fclose($far);
}
/**
* A pending handshake whose deadline has passed is removed by
* the cull pass, so a client that opens a socket and never
* finishes the handshake cannot hold the slot or block.
*/
public function stalledHandshakeIsEvictedTestCase()
{
$this->setUpHandshake();
list($near, $far) = $this->probe->makePair();
$key = (int) $near;
$this->probe->seedPending($near, $key, microtime(true) - 1);
$before = $this->probe->pendingHandshakes();
$this->assertTrue(isset($before[$key]),
"handshake is pending before the cull");
$this->probe->cull();
$after = $this->probe->pendingHandshakes();
$this->assertTrue(!isset($after[$key]),
"a handshake past its deadline is evicted");
is_resource($far) && fclose($far);
}
/**
* A pending handshake still within its deadline survives a cull
* pass, so a handshake that is merely mid-negotiation is not
* torn down prematurely.
*/
public function freshHandshakeSurvivesCullTestCase()
{
$this->setUpHandshake();
list($near, $far) = $this->probe->makePair();
$key = (int) $near;
$this->probe->seedPending($near, $key, microtime(true) + 30);
$this->probe->cull();
$after = $this->probe->pendingHandshakes();
$this->assertTrue(isset($after[$key]),
"a handshake within its deadline is kept");
is_resource($near) && fclose($near);
is_resource($far) && fclose($far);
}
/**
* A multipart entity that declares an empty boundary must not
* recurse: an empty boundary degenerates to the delimiter "--",
* which would otherwise match throughout the body and split it
* into a runaway number of parts.
*/
public function emptyBoundaryProducesNoPartsTestCase()
{
$this->setUpMime();
$bytes = "Content-Type: multipart/mixed; boundary=\"\"\r\n" .
"\r\n" . str_repeat("X", 2000) .
"\r\n--\r\nfiller\r\n--\r\n";
$entity = $this->probe->parse($bytes);
$this->assertEqual('multipart', $entity['type'],
"empty boundary still parses as multipart at top");
$this->assertEqual(0, count($entity['parts']),
"empty boundary yields no child parts, no runaway");
}
/**
* A message whose parts keep declaring themselves multipart
* with the same boundary must stop at the depth bound rather
* than recursing until memory is exhausted.
*/
public function deeplyNestedMultipartIsDepthBoundedTestCase()
{
$this->setUpMime();
$bytes = "Content-Type: multipart/mixed; boundary=b\r\n\r\n";
$nested = "";
for ($i = 0; $i < 200; $i++) {
$nested .= "--b\r\nContent-Type: multipart/mixed; " .
"boundary=b\r\n\r\n";
}
$bytes .= $nested . "--b--\r\n";
$before = memory_get_usage();
$entity = $this->probe->parse($bytes);
$delta = memory_get_usage() - $before;
$this->assertTrue(is_array($entity['parts']),
"deeply nested message parses without exhausting memory");
$this->assertTrue($delta < 16 * 1024 * 1024,
"depth-bounded parse stays well under the memory limit");
}
/**
* A normal two-part multipart/alternative message still parses
* into its two child entities, so the bounds do not disturb
* ordinary mail.
*/
public function normalMultipartStillParsesTestCase()
{
$this->setUpMime();
$bytes = "Content-Type: multipart/alternative; " .
"boundary=xyz\r\n\r\n" .
"--xyz\r\nContent-Type: text/plain\r\n\r\nHello\r\n" .
"--xyz\r\nContent-Type: text/html\r\n\r\n" .
"<p>Hi</p>\r\n--xyz--\r\n";
$entity = $this->probe->parse($bytes);
$this->assertEqual('multipart', $entity['type'],
"normal message parses as multipart");
$this->assertEqual('alternative', $entity['subtype'],
"subtype preserved");
$this->assertEqual(2, count($entity['parts']),
"both child parts are parsed");
}
/**
* A multipart body larger than the structure-parse cap is not
* split into parts and its body string is not materialized, so
* a message dominated by a large attachment cannot blow up
* memory during a BODYSTRUCTURE fetch. The reported size still
* reflects the real body length.
*/
public function oversizedBodyIsNotSplitTestCase()
{
$this->setUpMime();
$filler_length = MailSite::MAX_STRUCTURE_PARSE_BYTES + 1024;
$bytes = "Content-Type: multipart/mixed; boundary=b\r\n\r\n" .
"--b\r\nContent-Type: application/octet-stream\r\n\r\n" .
str_repeat("A", $filler_length) . "\r\n--b--\r\n";
$entity = $this->probe->parse($bytes);
$this->assertEqual('multipart', $entity['type'],
"oversized message still parses as multipart at top");
$this->assertEqual(0, count($entity['parts']),
"oversized body is left unsplit");
$this->assertEqual('', $entity['body'],
"oversized body string is not materialized");
$this->assertTrue($entity['size'] >= $filler_length,
"reported size still reflects the real body length");
}
/**
* The four special-use folders plus INBOX exist after
* provisioning.
*/
public function standardFoldersProvisionedTestCase()
{
$this->setUpFolders();
foreach ([MailSite::FOLDER_INBOX, MailSite::FOLDER_SENT,
MailSite::FOLDER_DRAFTS, MailSite::FOLDER_JUNK,
MailSite::FOLDER_TRASH] as $folder) {
$this->assertTrue($this->storage->folderExists(
$this->account, $folder),
"$folder exists after provisioning");
}
}
/**
* Provisioning twice does not error or duplicate folders;
* createFolder is idempotent, which matters because the
* provisioning runs on every login.
*/
public function provisioningIsIdempotentTestCase()
{
$this->setUpFolders();
$before = $this->storage->listFolders($this->account);
$this->storage->ensureStandardFolders($this->account);
$after = $this->storage->listFolders($this->account);
sort($before);
sort($after);
$this->assertEqual($before, $after,
"re-provisioning leaves the folder set unchanged");
}
/**
* An Apple-style delete (copy to Trash, flag the source
* \Deleted, expunge) removes the message from INBOX and
* leaves a copy in Trash.
*/
public function copyToTrashThenExpungeDeletesTestCase()
{
$this->setUpFolders();
$uid = $this->storage->appendMessage($this->account,
'INBOX', "Subject: remove me\r\n\r\nbody\r\n");
$body = $this->storage->fetchMessage($this->account,
'INBOX', $uid);
$this->storage->appendMessage($this->account,
MailSite::FOLDER_TRASH, $body, [], 0);
$this->storage->setFlags($this->account, 'INBOX', $uid,
[MailSite::FLAG_DELETED]);
$this->storage->expunge($this->account, 'INBOX');
$this->assertEqual(0, $this->storage->messageCount(
$this->account, 'INBOX'),
"the deleted message left INBOX");
$this->assertEqual(1, $this->storage->messageCount(
$this->account, MailSite::FOLDER_TRASH),
"a copy of the deleted message is in Trash");
}
/**
* Deleting an existing non-INBOX folder succeeds, and a
* folder that was never created reports as absent. These are
* the storage primitives behind the protocol layer answering
* OK to a DELETE of an already-gone folder (so a client can
* clear a phantom folder from its cache).
*/
public function deleteFolderAndPhantomTestCase()
{
$this->setUpFolders();
$this->storage->createFolder($this->account, 'Archive');
$this->assertTrue($this->storage->folderExists(
$this->account, 'Archive'),
"Archive exists before deletion");
$this->assertTrue($this->storage->deleteFolder(
$this->account, 'Archive'),
"deleting an existing folder succeeds");
$this->assertFalse($this->storage->folderExists(
$this->account, 'Archive'),
"Archive is gone after deletion");
$this->assertFalse($this->storage->folderExists(
$this->account, 'Deleted Messages'),
"a folder that was never created reports as absent");
}
/**
* A pre-existing non-canonical role folder (e.g. "Deleted
* Messages" for Trash, "Sent Messages" for Sent) is
* consolidated into the canonical folder: its messages move
* over and the non-canonical folder is removed. Running the
* consolidation again is a no-op.
*/
public function consolidatesNonCanonicalFoldersTestCase()
{
$this->setUpFolders();
$this->storage->createFolder($this->account,
'Deleted Messages');
$this->storage->appendMessage($this->account,
'Deleted Messages', "Subject: old\r\n\r\nx\r\n");
$this->storage->appendMessage($this->account,
'Deleted Messages', "Subject: old two\r\n\r\ny\r\n");
$this->storage->createFolder($this->account,
'Sent Messages');
$this->storage->appendMessage($this->account,
'Sent Messages', "Subject: out\r\n\r\nz\r\n");
$this->storage->ensureStandardFolders($this->account);
$this->assertFalse($this->storage->folderExists(
$this->account, 'Deleted Messages'),
"non-canonical Trash folder was removed");
$this->assertFalse($this->storage->folderExists(
$this->account, 'Sent Messages'),
"non-canonical Sent folder was removed");
$this->assertEqual(2, $this->storage->messageCount(
$this->account, MailSite::FOLDER_TRASH),
"Trash received both consolidated messages");
$this->assertEqual(1, $this->storage->messageCount(
$this->account, MailSite::FOLDER_SENT),
"Sent received the consolidated message");
$this->storage->ensureStandardFolders($this->account);
$this->assertEqual(2, $this->storage->messageCount(
$this->account, MailSite::FOLDER_TRASH),
"a second consolidation run does not duplicate mail");
}
/**
* ensureStandardFolders returns a summary describing each
* consolidation it performed, and returns an empty list when
* an account is already clean.
*/
public function consolidationSummaryReturnedTestCase()
{
$this->setUpFolders();
$clean = $this->storage->ensureStandardFolders(
$this->account);
$this->assertEqual([], $clean,
"a clean account reports no consolidations");
$this->storage->createFolder($this->account,
'Deleted Messages');
$this->storage->appendMessage($this->account,
'Deleted Messages', "Subject: a\r\n\r\nb\r\n");
$summary = $this->storage->ensureStandardFolders(
$this->account);
$this->assertEqual(1, count($summary),
"one consolidation is reported");
$this->assertEqual('Deleted Messages',
$summary[0]['from'],
"summary names the removed folder");
$this->assertEqual(MailSite::FOLDER_TRASH,
$summary[0]['into'],
"summary names the canonical target");
$this->assertEqual(1, $summary[0]['moved'],
"summary reports the moved message count");
}
/**
* Multiple registered onLog callbacks each receive MailSite
* log events in registration order, and emitLog is a no-op
* when none are registered.
*/
public function onLogHandlerReceivesEventsTestCase()
{
$this->setUpFolders();
$reflection = new \ReflectionMethod($this->mail_site,
'emitLog');
$reflection->invoke($this->mail_site, "before any handler");
$first = [];
$second = [];
$this->mail_site->onLog(function ($message) use (&$first) {
$first[] = $message;
});
$this->mail_site->onLog(function ($message) use (&$second) {
$second[] = $message;
});
$reflection->invoke($this->mail_site, "hello log");
$this->assertEqual(["hello log"], $first,
"the first registered handler received the message");
$this->assertEqual(["hello log"], $second,
"the second registered handler received the message");
}
/**
* Folders with spaces and hierarchy are stored as literal,
* nested directories: a space stays a space (no percent
* encoding) and "Archive/2026" nests under "Archive". Listing
* returns the slash-joined paths, messages are addressable at
* each level, and a parent that still has children cannot be
* deleted.
*/
public function nestedAndSpacedFoldersTestCase()
{
$this->setUpFolders();
$this->storage->createFolder($this->account,
'Seekquarry Leads');
$this->storage->createFolder($this->account, 'Archive/2026');
$this->storage->appendMessage($this->account,
'Seekquarry Leads', "Subject: lead\r\n\r\nx\r\n");
$this->storage->appendMessage($this->account,
'Archive/2026', "Subject: arc\r\n\r\ny\r\n");
$folders = $this->storage->listFolders($this->account);
$this->assertTrue(in_array('Seekquarry Leads', $folders,
true), "the spaced folder is listed by its literal name");
$this->assertTrue(in_array('Archive', $folders, true),
"the intermediate parent folder is listed");
$this->assertTrue(in_array('Archive/2026', $folders, true),
"the nested child folder is listed by its path");
$this->assertEqual(1, $this->storage->messageCount(
$this->account, 'Seekquarry Leads'),
"messages are addressable in the spaced folder");
$this->assertEqual(1, $this->storage->messageCount(
$this->account, 'Archive/2026'),
"messages are addressable in the nested folder");
$this->assertFalse($this->storage->deleteFolder(
$this->account, 'Archive'),
"a parent with a child folder cannot be deleted");
$this->assertTrue($this->storage->deleteFolder(
$this->account, 'Archive/2026'),
"the leaf child folder can be deleted");
$this->assertTrue($this->storage->deleteFolder(
$this->account, 'Archive'),
"the parent can be deleted once it has no children");
}
/**
* When a message in a non-canonical folder cannot be copied
* into its canonical folder, consolidation keeps the source
* folder holding exactly the uncopied message (no data loss),
* moves the rest, and a later retry that can read the message
* finishes the move without duplicating the mail that already
* landed in the canonical folder.
*/
public function partialFailureKeepsSourceTestCase()
{
$this->setUpFolders();
$storage = new class extends RamMailStorage {
/**
* uid whose fetchMessage returns false.
* @var int
*/
public $fail_uid = 0;
/**
* Refuses the designated uid; otherwise defers to the
* in-memory parent.
* @param string $user username (no @domain)
* @param string $folder folder name with hierarchy
* @param int $uid persistent IMAP unique identifier
* @return string|false bytes, or false when designated
*/
public function fetchMessage($user, $folder, $uid)
{
if ((int) $uid === $this->fail_uid) {
return false;
}
return parent::fetchMessage($user, $folder, $uid);
}
};
$storage->ensureUser($this->account);
$storage->ensureStandardFolders($this->account);
$storage->createFolder($this->account, 'Sent Messages');
$good = $storage->appendMessage($this->account,
'Sent Messages', "Subject: copies\r\n\r\nx\r\n");
$bad = $storage->appendMessage($this->account,
'Sent Messages', "Subject: stuck\r\n\r\ny\r\n");
$storage->fail_uid = $bad;
$summary = $storage->ensureStandardFolders($this->account);
$this->assertTrue($storage->folderExists($this->account,
'Sent Messages'),
"source folder is kept when a copy fails");
$this->assertEqual(1, $storage->messageCount($this->account,
'Sent Messages'),
"only the uncopied message remains in the source");
$this->assertEqual(1, $storage->messageCount($this->account,
MailSite::FOLDER_SENT),
"the copyable message reached the canonical folder");
$entry = null;
foreach ($summary as $consolidation) {
if ($consolidation['from'] === 'Sent Messages') {
$entry = $consolidation;
}
}
$this->assertTrue($entry !== null &&
$entry['failed'] === 1 && $entry['deleted'] === false,
"summary reports the failure and that the source stayed");
$storage->fail_uid = 0;
$storage->ensureStandardFolders($this->account);
$this->assertFalse($storage->folderExists($this->account,
'Sent Messages'),
"a retry that can read the message removes the source");
$this->assertEqual(2, $storage->messageCount($this->account,
MailSite::FOLDER_SENT),
"the retry moves the last message without duplicating");
}
/**
* A UID-restricted expunge removes only the deleted message
* whose UID is in the restriction, leaving the other deleted
* message in place.
*/
public function uidRestrictedExpungeRemovesOnlyNamedTestCase()
{
$this->setUpExpunge();
$removed = $this->storage->expunge($this->account, 'INBOX',
[$this->first_uid]);
$this->assertEqual([$this->first_uid], $removed,
"only the restricted deleted UID is expunged");
$remaining = [];
foreach ($this->storage->listMessages($this->account,
'INBOX') as $meta) {
$remaining[] = $meta['uid'];
}
sort($remaining);
$expected = [$this->second_uid, $this->third_uid];
sort($expected);
$this->assertEqual($expected, $remaining,
"the other deleted message and the live message stay");
}
/**
* A UID restriction naming a non-deleted message expunges
* nothing, since only deleted messages are ever removed.
*/
public function uidRestrictionOnLiveMessageRemovesNothingTestCase()
{
$this->setUpExpunge();
$removed = $this->storage->expunge($this->account, 'INBOX',
[$this->third_uid]);
$this->assertEqual([], $removed,
"a live message named in the set is not expunged");
$this->assertEqual(3, count($this->storage->listMessages(
$this->account, 'INBOX')),
"no messages were removed");
}
/**
* An unrestricted expunge still removes every deleted
* message, preserving the plain EXPUNGE behavior desktop
* clients rely on.
*/
public function unrestrictedExpungeRemovesAllDeletedTestCase()
{
$this->setUpExpunge();
$removed = $this->storage->expunge($this->account, 'INBOX');
sort($removed);
$expected = [$this->first_uid, $this->second_uid];
sort($expected);
$this->assertEqual($expected, $removed,
"plain expunge removes all deleted messages");
$this->assertEqual(1, count($this->storage->listMessages(
$this->account, 'INBOX')),
"only the one live message remains");
}
/**
* Caching more folders than the limit allows drops the oldest and
* holds the count at the limit, so a mail server that visits many
* mailboxes over its life does not grow without bound.
*/
public function folderIndexCacheEvictsOldestTestCase()
{
$probe = new FolderIndexCacheProbe(sys_get_temp_dir());
$limit = FileMailStorage::MAX_CACHED_FOLDER_INDEXES;
for ($i = 0; $i < $limit; $i++) {
$probe->store("folder" . $i);
}
$probe->store("overflow");
$this->assertTrue($probe->fetch("folder0") === null,
"the oldest folder is evicted once the limit is passed");
$this->assertTrue($probe->fetch("overflow") !== null,
"the newest folder is resident");
}
/**
* Reading a folder marks it most recently used, so a later
* overflow evicts a different, untouched folder rather than the
* one still in active use.
*/
public function folderIndexCachePromotesOnReadTestCase()
{
$probe = new FolderIndexCacheProbe(sys_get_temp_dir());
$limit = FileMailStorage::MAX_CACHED_FOLDER_INDEXES;
for ($i = 0; $i < $limit; $i++) {
$probe->store("folder" . $i);
}
$probe->fetch("folder0");
$probe->store("overflow");
$this->assertTrue($probe->fetch("folder0") !== null,
"the touched folder survives the eviction");
$this->assertTrue($probe->fetch("folder1") === null,
"the next-oldest untouched folder is evicted instead");
}
/**
* A DATA body that runs past the size limit without ever sending its
* end-of-message marker drops the connection instead of buffering
* without bound, the crash this cap prevents.
*/
public function unterminatedOversizeDataDropsTestCase()
{
$probe = new ProbeMailSiteForSmtpData(1024);
$buffer = str_repeat("x", 4096);
[$result, $left] = $probe->feedData(7,
$buffer, ['STATE' => 'DATA']);
$this->assertFalse($result,
"an unterminated over-limit body reports no command consumed");
$this->assertTrue($probe->was_shut_down,
"the connection is dropped rather than buffered without bound");
}
/**
* A partial body still under the limit waits for more input and keeps
* the connection, so the cap does not fire on ordinary streaming.
*/
public function underLimitPartialDataWaitsTestCase()
{
$probe = new ProbeMailSiteForSmtpData(1024);
$buffer = str_repeat("y", 200);
[$result, $left] = $probe->feedData(7,
$buffer, ['STATE' => 'DATA']);
$this->assertFalse($result,
"a short partial body reports no command consumed yet");
$this->assertFalse($probe->was_shut_down,
"an under-limit partial body keeps the connection open");
}
/**
* An over-limit body that does arrive with its terminator still gets
* the 552 reply and keeps the connection, the courteous path the cap
* leaves intact.
*/
public function terminatedOversizeDataGets552TestCase()
{
$probe = new ProbeMailSiteForSmtpData(1024);
$buffer = str_repeat("z", 4096) . "\r\n.\r\n";
[$result, $left] = $probe->feedData(7,
$buffer, ['STATE' => 'DATA', 'MAILFROM' => 'a@b.c',
'RCPTTO' => []]);
$this->assertTrue($result,
"a terminated over-limit body is consumed and answered");
$this->assertTrue(strpos($probe->written, "552") !== false,
"the client is told the message exceeds the size limit");
$this->assertFalse($probe->was_shut_down,
"the terminated over-limit path replies instead of dropping");
}
}
(c) 2026 Seekquarry - Open Source Search Engine Software