<?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\ImapClient;
use seekquarry\yioop\library\UnitTest;
/**
* Test-only subclass of ImapClient that re-exposes the two protected
* static error classifiers as public methods so they can be unit
* tested directly. classifyConnectError() and certReasonDetail() are
* pure functions of their string argument; exercising them does not
* require a socket, so the real connect path (integration territory)
* is left alone. Nothing here changes ImapClient's own API surface.
*
* @author Chris Pollett
*/
class TestableImapClient extends ImapClient
{
/**
* Public passthrough to the protected classifyConnectError().
*
* @param string $raw raw PHP-level stream error text
* @return string one of the ImapClient ERROR_* tokens, cert and
* connect-failed tokens suffixed with ": <detail>"
*/
public static function classify(string $raw): string
{
return self::classifyConnectError($raw);
}
/**
* Public passthrough to the protected certReasonDetail().
*
* @param string $raw raw PHP-level TLS warning text
* @return string the concise human-meaningful reason
*/
public static function certReason(string $raw): string
{
return self::certReasonDetail($raw);
}
}
/**
* Unit tests for ImapClient against a scripted server pipe. Each test
* opens a stream_socket_pair, hands one end to ImapClient via the
* injected-socket constructor argument, writes the server's scripted
* responses onto the other end, and asserts the client parses them
* the way RFC 3501 implies.
*
* Real network round-trips are not exercised here; the connect and
* STARTTLS / IMAPS handshake paths are integration territory that
* requires a real server. Everything that lives entirely in the
* parser or in the static error classifiers, however, is covered.
*
* @author Chris Pollett
*/
class ImapClientTest extends UnitTest
{
/**
* Server side of a stream_socket_pair held across test setup so the
* setUp method can write scripted responses onto it before
* each test invokes ImapClient.
* @var resource
*/
public $server_side;
/**
* Client side of the same pair, passed to ImapClient as its
* "injected socket" so the class does not try a real network
* connection.
* @var resource
*/
public $client_side;
/**
* Creates the socket pair the per-test setup will drive.
*/
public function setUp()
{
$pair = stream_socket_pair(STREAM_PF_UNIX, STREAM_SOCK_STREAM,
STREAM_IPPROTO_IP);
$this->server_side = $pair[0];
$this->client_side = $pair[1];
}
/**
* Closes both ends of the test pair if the test did not.
*/
public function tearDown()
{
if (is_resource($this->server_side)) {
fclose($this->server_side);
}
if (is_resource($this->client_side)) {
fclose($this->client_side);
}
}
/**
* Convenience: queue a string onto the server end of the pair so
* the client's next socket read sees it.
*
* @param string $bytes raw bytes (callers responsible for any
* required CRLF framing)
*/
public function pushServer($bytes)
{
fwrite($this->server_side, $bytes);
}
/**
* A bare "* OK ready" greeting plus a single tagged OK response
* to one LOGIN command should round-trip cleanly: status "OK",
* empty untagged list besides the greeting itself, no literals.
*/
public function loginOkTestCase()
{
$this->pushServer("* OK IMAP ready\r\n");
$this->pushServer("X1 OK LOGIN completed\r\n");
$client = new ImapClient("test.invalid", 143, 5, $this->client_side);
$response = $client->send('LOGIN "alice" "secret"');
$this->assertEqual("OK", $response['status'],
"LOGIN OK comes back as status OK");
$this->assertEqual("LOGIN completed", $response['detail'],
"Detail line is what follows the status token");
$this->assertEqual(0, count($response['untagged']),
"No untagged lines between greeting drain and tagged OK");
$this->assertEqual(0, count($response['literals']),
"No literal payloads on a plain LOGIN");
}
/**
* A LOGIN that the server refuses should surface as status "NO"
* with the server's detail string carried through verbatim.
*/
public function loginNoTestCase()
{
$this->pushServer("* OK IMAP ready\r\n");
$this->pushServer("X1 NO LOGIN failed: bad credentials\r\n");
$client = new ImapClient("test.invalid", 143, 5, $this->client_side);
$response = $client->send('LOGIN "alice" "wrong"');
$this->assertEqual("NO", $response['status'],
"Refused LOGIN comes back as status NO");
$this->assertEqual("LOGIN failed: bad credentials",
$response['detail'],
"Server's reason text is preserved");
}
/**
* SELECT INBOX with the typical untagged EXISTS / FLAGS / RECENT
* stanza should return those as $response['untagged'] in order,
* with no literals.
*/
public function selectInboxUntaggedTestCase()
{
$this->pushServer("* OK IMAP ready\r\n");
$this->pushServer("* 42 EXISTS\r\n");
$this->pushServer("* 3 RECENT\r\n");
$this->pushServer("* FLAGS (\\Answered \\Flagged \\Deleted " .
"\\Seen \\Draft)\r\n");
$this->pushServer("* OK [UIDVALIDITY 1234567890] UIDs valid\r\n");
$this->pushServer("X1 OK [READ-WRITE] SELECT completed\r\n");
$client = new ImapClient("test.invalid", 143, 5, $this->client_side);
$response = $client->send('SELECT "INBOX"');
$this->assertEqual("OK", $response['status'],
"SELECT completes with status OK");
$this->assertEqual(4, count($response['untagged']),
"EXISTS, RECENT, FLAGS, UIDVALIDITY each captured");
$this->assertTrue(
str_contains($response['untagged'][0], "EXISTS"),
"First untagged line is EXISTS");
$this->assertTrue(
str_contains($response['untagged'][2], "FLAGS"),
"Third untagged line is FLAGS");
}
/**
* A FETCH that returns a literal payload (the {N} form) must
* read exactly N bytes and place them in $response['literals']
* keyed by the untagged-line index where they appeared.
*/
public function fetchWithLiteralPayloadTestCase()
{
$body = "From: alice@example.com\r\n" .
"Subject: hi\r\n\r\n" .
"Body text.\r\n";
$size = strlen($body);
$this->pushServer("* OK IMAP ready\r\n");
$this->pushServer("* 1 FETCH (RFC822 {{$size}}\r\n");
$this->pushServer($body);
$this->pushServer(")\r\n");
$this->pushServer("X1 OK FETCH completed\r\n");
$client = new ImapClient("test.invalid", 143, 5, $this->client_side);
$response = $client->send('FETCH 1 RFC822');
$this->assertEqual("OK", $response['status'],
"FETCH completes OK");
$this->assertEqual(1, count($response['literals']),
"Exactly one literal payload captured");
$this->assertEqual($body, $response['literals'][0],
"Literal payload is byte-identical to what server sent");
}
/**
* A tagged response with no detail (just "X1 OK" + CRLF) should
* still parse: status is "OK", detail is the empty string,
* untagged and literals are empty.
*/
public function bareTaggedOkTestCase()
{
$this->pushServer("* OK IMAP ready\r\n");
$this->pushServer("X1 OK\r\n");
$client = new ImapClient("test.invalid", 143, 5, $this->client_side);
$response = $client->send('NOOP');
$this->assertEqual("OK", $response['status'],
"Bare OK is still status OK");
$this->assertEqual("", $response['detail'],
"No detail when nothing follows the status token");
}
/**
* The IMAP greeting on connect must begin with "* OK"; any other
* shape is a fatal session error and the constructor must throw.
*/
public function rejectsBadGreetingTestCase()
{
$this->pushServer("* BYE banned\r\n");
try {
new ImapClient("test.invalid", 143, 5, $this->client_side);
$this->assertTrue(false,
"Bad greeting should have thrown but didn't");
} catch (\Exception $e) {
$this->assertTrue(
str_contains($e->getMessage(),
ImapClient::ERROR_BAD_GREETING),
"Exception carries the bad-greeting token");
}
}
/**
* Tags must increment per call so the server can disambiguate
* pipelined commands. Three sequential sends should issue tags
* X1, X2, X3.
*/
public function tagsIncrementTestCase()
{
$this->pushServer("* OK ready\r\n");
$this->pushServer("X1 OK first\r\n");
$this->pushServer("X2 OK second\r\n");
$this->pushServer("X3 OK third\r\n");
$client = new ImapClient("test.invalid", 143, 5, $this->client_side);
$a = $client->send("NOOP");
$b = $client->send("NOOP");
$c = $client->send("NOOP");
$this->assertEqual("first", $a['detail'],
"First send matches X1");
$this->assertEqual("second", $b['detail'],
"Second send matches X2");
$this->assertEqual("third", $c['detail'],
"Third send matches X3");
}
/**
* classifyConnectError() must separate the three certificate
* failure modes. A name mismatch is its own token even though
* PHP's error text for it also contains "certificate verify
* failed" — the hostname check runs first and wins, so the user
* is pointed at the Host field rather than the self-signed
* option. An expired certificate gets its own token too, and a
* generic verification failure with no more specific marker
* falls through to ERROR_CERT_VERIFY. All three carry a
* ": <detail>" suffix.
*/
public function classifyCertErrorsTestCase()
{
$hostname_raw = "stream_socket_enable_crypto(): SSL operation " .
"failed with code 1. OpenSSL Error messages: " .
"error:0A000086:SSL routines::certificate verify failed. " .
"Peer certificate CN=`mail.example.net` did not match " .
"expected CN=`pollett.org`";
$hostname = TestableImapClient::classify($hostname_raw);
$this->assertTrue(
str_starts_with($hostname, ImapClient::ERROR_CERT_HOSTNAME),
"Name-mismatch text classifies as the cert-hostname token");
$this->assertTrue(
!str_starts_with($hostname, ImapClient::ERROR_CERT_VERIFY),
"Hostname check wins over the cert-verify substring");
$this->assertTrue(str_contains($hostname, ":"),
"Cert-hostname token carries a ': detail' suffix");
$expired_raw = "stream_socket_enable_crypto(): SSL operation " .
"failed with code 1. OpenSSL Error messages: " .
"error:0A000086:SSL routines::certificate has expired";
$expired = TestableImapClient::classify($expired_raw);
$this->assertTrue(
str_starts_with($expired, ImapClient::ERROR_CERT_EXPIRED),
"Expired-certificate text classifies as the cert-expired token");
$verify_raw = "stream_socket_enable_crypto(): SSL operation " .
"failed with code 1. OpenSSL Error messages: " .
"error:0A000086:SSL routines::certificate verify failed";
$verify = TestableImapClient::classify($verify_raw);
$this->assertTrue(
str_starts_with($verify, ImapClient::ERROR_CERT_VERIFY),
"Generic verify failure falls through to the cert-verify token");
$refused = TestableImapClient::classify("Connection refused");
$this->assertEqual(ImapClient::ERROR_CONNECTION_REFUSED, $refused,
"A non-cert error still classifies to its plain token");
}
/**
* certReasonDetail() pulls the actionable part out of PHP's
* boilerplate-wrapped TLS warnings: a "Peer certificate ... did
* not match expected ..." notice is lifted verbatim, and
* otherwise the text after the last "SSL routines:" marker is
* used. A string with no known marker comes back trimmed but
* otherwise whole.
*/
public function certReasonDetailTestCase()
{
$mismatch = "SSL operation failed with code 1. OpenSSL Error " .
"messages: error:0A000086:SSL routines::certificate verify " .
"failed. Peer certificate CN=`mail.example.net` did not " .
"match expected CN=`pollett.org`";
$lifted = TestableImapClient::certReason($mismatch);
$this->assertTrue(str_starts_with($lifted, "Peer certificate"),
"The peer-certificate clause is lifted out verbatim");
$this->assertTrue(
!str_contains($lifted, "SSL operation failed"),
"The OpenSSL boilerplate prefix is dropped");
$selfsigned = "SSL operation failed with code 1. OpenSSL Error " .
"messages: error:0A000086:SSL routines::self signed certificate";
$reason = TestableImapClient::certReason($selfsigned);
$this->assertEqual("self signed certificate", $reason,
"Text after the SSL-routines marker is what is returned");
$bare = TestableImapClient::certReason(" odd unwrapped text ");
$this->assertEqual("odd unwrapped text", $bare,
"A string with no known marker comes back trimmed but whole");
}
/**
* When a command's response has not arrived yet and the client is
* running inside a fiber, the read gives the event loop back with
* Fiber::suspend() rather than blocking; once the server answers and
* the fiber is resumed, the read completes and the response parses
* normally. This is what keeps one slow mail server from freezing the
* single-process web server.
*/
public function cooperativeReadSuspendsTestCase()
{
$this->pushServer("* OK IMAP ready\r\n");
$client = new ImapClient("test.invalid", 143, 5,
$this->client_side);
$fiber = new \Fiber(function () use ($client) {
return $client->send('NOOP');
});
$waited = $fiber->start();
$this->assertTrue($fiber->isSuspended(),
"the read suspends the fiber when no response is ready yet");
$this->assertTrue(is_array($waited) && isset($waited['read']),
"the fiber suspends asking to wait for the socket to read");
$this->pushServer("X1 OK NOOP done\r\n");
while ($fiber->isSuspended()) {
$fiber->resume();
}
$response = $fiber->getReturn();
$this->assertEqual("OK", $response['status'],
"once the response arrives the suspended read completes");
}
}
(c) 2026 Seekquarry - Open Source Search Engine Software