fix(client): code the pre-send failures so callers can replay them

Connection validation runs ahead of the send, so both failures it raises
leave the command unsent and nothing applied - the one class of failure
a caller may safely replay. Both carried code 0, making that legible
only in the message text, and a caller that classifies on text turns a
permanent failure into an advertised-retryable one the moment a message
quotes a caller-chosen value. A cloud connection pool consequently could
not tell a replayable refusal from a post-send timeout of unknown
outcome, and surfaced the former to clients as a 500 during a backing
resize.

Both now carry MongoDB's own HostUnreachable, with isUnsentError() to
read it. The messages are unchanged, so the client's own internal
reconnect check that matches on them still behaves identically.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Jake BarnbyandClaude Opus 5 committed 2026-08-02 11:49:57 +12:00
1 parent ef3313807d
commit b395b0e35b
3 files changed
+67 -2

No files matched your search

+5 -2
View File
@@ -2178,13 +2178,16 @@ class Client
}
}
// Both throws are raised ahead of the send, so the command never
// reached the server and a caller may safely replay it. They carry
// HostUnreachable to say so in a code rather than in text.
if (!$this->isConnected) {
throw new Exception('Client is not connected to MongoDB');
throw new Exception('Client is not connected to MongoDB', Exception::HOST_UNREACHABLE);
}
if (!$this->client->isConnected()) {
$this->isConnected = false;
throw new Exception('Connection to MongoDB has been lost');
throw new Exception('Connection to MongoDB has been lost', Exception::HOST_UNREACHABLE);
}
}
+22
View File
@@ -9,6 +9,19 @@ namespace Utopia\Mongo;
*/
class Exception extends \Exception
{
/**
* The connection was gone before the command left the client.
*
* MongoDB's own HostUnreachable. Carried by every throw raised out of
* connection validation, which runs ahead of the send: the command was
* never on the wire, so nothing was applied and a caller may safely
* replay it. Distinguishing this from a post-send failure used to be
* possible only by matching the message text, which callers cannot do
* safely - a message quotes caller-chosen values, a code cannot be
* spelled by a caller.
*/
public const int HOST_UNREACHABLE = 6;
protected array $errorLabels = [];
protected ?array $writeErrors = null;
protected ?array $writeConcernErrors = null;
@@ -105,6 +118,15 @@ class Exception extends \Exception
*
* @return bool
*/
/**
* Whether the command was still unsent when this failure was raised, so
* nothing was applied and the caller may replay it.
*/
public function isUnsentError(): bool
{
return $this->code === self::HOST_UNREACHABLE;
}
public function isTimeoutError(): bool
{
$timeoutCodes = [
+40
View File
@@ -0,0 +1,40 @@
<?php
namespace Utopia\Tests;
use PHPUnit\Framework\TestCase;
use Utopia\Mongo\Exception;
/**
* Connection validation runs ahead of the send, so every failure it raises
* leaves the command unsent and nothing applied - the one class of failure a
* caller may safely replay. That distinction was previously legible only in
* the message text, which a caller cannot classify on safely, and a cloud
* pool consequently surfaced a replayable refusal to the client as a 500.
*/
final class UnsentErrorTest extends TestCase
{
public function testAnUnsentFailureIsDistinguishableByCode(): void
{
$unsent = new Exception('Client is not connected to MongoDB', Exception::HOST_UNREACHABLE);
$this->assertTrue($unsent->isUnsentError());
$this->assertFalse($unsent->isTimeoutError(), 'An unsent failure must not be confused with a post-send timeout');
}
public function testAPostSendTimeoutIsNotReportedAsUnsent(): void
{
$timeout = new Exception('Receive timeout: no data received within reasonable time', 11601);
$this->assertTrue($timeout->isTimeoutError());
$this->assertFalse(
$timeout->isUnsentError(),
'The command was already on the wire, so its outcome is unknown and it must never be replayed blindly',
);
}
public function testAnUncodedFailureIsNotAssumedUnsent(): void
{
$this->assertFalse(new Exception('something went wrong')->isUnsentError());
}
}