}|EmailError $failure */
+ #[DataProvider('retriedUploadFailures')]
+ public function testAnUploadThatFailsOnTheWayIsRetried($failure): void
+ {
+ $this->reply(self::slots(self::uploadSlot(self::INVITE)), $failure, [200, '', []]);
+
+ $result = $this->emails()->send(self::sendWithFiles([self::invite()]));
+
+ $this->assertSame('msg_1', $result->getId());
+ $this->assertSame(self::INVITE, $this->stored[self::INVITE_SHA256]);
+ $this->assertCount(1, $this->queued);
+ }
+
+ public function testStorageThrottlingThatOutlastsTheRetriesIsARateLimit(): void
+ {
+ $slowDown = [429, 'SlowDownReduce your rate', []];
+ $this->reply(self::slots(self::uploadSlot(self::INVITE)), $slowDown);
+
+ $error = $this->sendError(self::sendWithFiles([self::invite()]), $this->emails(['maxRetries' => 0]));
+
+ $this->assertSame('attachment_upload_failed', $error->getErrorCode());
+ $this->assertSame('rate_limit_exceeded', $error->getErrorName());
+ $this->assertSame([], $this->queued, 'no email was sent');
+ }
+
+ public function testAStorageRetryAfterOverThirtySecondsFailsAtOnce(): void
+ {
+ $slowDown = 'SlowDownSlow down';
+ $this->reply(self::slots(self::uploadSlot(self::INVITE)), [503, $slowDown, ['Retry-After: 60']]);
+
+ $error = $this->sendError(self::sendWithFiles([self::invite()]));
+
+ $this->assertSame('attachment_upload_failed', $error->getErrorCode());
+ $this->assertSame(60_000, $error->getRetryAfterMs());
+ $this->assertSame([], $this->storageWrites);
+ $this->assertSame([], $this->queued);
+ }
+
+ public static function shutdownsDuringTheUploads(): array
+ {
+ return ['after the upload request' => [1, 0], 'after an upload' => [2, 1], 'after the last upload' => [3, 2]];
+ }
+
+ #[DataProvider('shutdownsDuringTheUploads')]
+ public function testAClientShutDownDuringTheUploadsSendsNothingMore(
+ int $requestsBeforeTheShutdown,
+ int $filesStored
+ ): void {
+ $emails = $this->emails(['isClosed' => fn(): bool => count($this->requests) >= $requestsBeforeTheShutdown]);
+ $this->reply(
+ self::slots(self::uploadSlot(self::INVITE), self::uploadSlot(self::PNG)),
+ [200, '', []],
+ [200, '', []]
+ );
+
+ $error = $this->sendError(
+ self::sendWithFiles([self::invite(), ['filename' => 'logo.png', 'content' => self::PNG]]),
+ $emails
+ );
+
+ $this->assertSame('client_closed', $error->getErrorCode());
+ $this->assertCount($filesStored, $this->storageWrites);
+ $this->assertSame([], $this->queued);
+ }
+
+ public function testAnUploadRefusalNamesTheAttachmentAndSendsNothing(): void
+ {
+ $this->reply([400, json_encode([
+ 'type' => 'invalid_request',
+ 'code' => 'message_too_large',
+ 'detail' => 'These files are too large for one email, so PostHog didn\'t prepare the uploads.',
+ 'attr' => 'files__1__size',
+ 'why' => 'An email can be at most 40 MB after Base64 encoding, about 29 MB of files.',
+ 'fix' => 'Send fewer or smaller files, or link to large files from the email body.',
+ ]), []]);
+
+ $error = $this->sendError(self::sendWithFiles([
+ self::invite(),
+ self::invite(['filename' => 'copy.ics']),
+ ['filename' => 'logo.png', 'content' => self::PNG],
+ ]));
+
+ $this->assertSame('message_too_large', $error->getErrorCode());
+ $this->assertSame('validation_error', $error->getErrorName());
+ $this->assertSame('attachments__2__content', $error->getField());
+ $this->assertSame('Send fewer or smaller files, or link to large files from the email body.', $error->getFix());
+ $this->assertSame([], $this->storageWrites);
+ $this->assertSame([], $this->queued, 'no email was sent');
+ }
+
+ public function testBytesThatDoNotMatchTheSignedChecksumAreRefusedByStorageAndNothingIsSent(): void
+ {
+ $slot = self::uploadSlot(self::INVITE);
+ $slot['headers']['x-amz-checksum-sha256'] = base64_encode(hash('sha256', self::PNG, true));
+ $this->reply(self::slots($slot));
+
+ $error = $this->sendError(self::sendWithFiles([self::invite()]));
+
+ $this->assertSame('attachment_upload_failed', $error->getErrorCode());
+ $this->assertSame(400, $error->getStatusCode());
+ $this->assertStringContainsString('BadDigest', $error->getMessage());
+ $this->assertSame([], $this->storageWrites);
+ $this->assertSame([], $this->queued);
+ }
+
+ public function testTheDailyUploadLimitIsNotRetried(): void
+ {
+ $this->reply([429, '{"code":"upload_quota_exceeded","detail":"No more uploads today."}', []]);
+
+ $error = $this->sendError(self::sendWithFiles([self::invite()]));
+
+ $this->assertSame('upload_quota_exceeded', $error->getErrorCode());
+ $this->assertSame([], $this->storageWrites);
+ $this->assertSame([], $this->queued, 'no email was sent');
+ }
+
+ public static function uploadRouteNotFound(): array
+ {
+ return [
+ "PostHog's answer" => [
+ '{"type":"invalid_request","code":"not_found","detail":"Endpoint not found.","attr":null}',
+ 'Endpoint not found.',
+ ],
+ 'an answer without JSON' => ['Not Found', 'PostHog answered HTTP 404.'],
+ ];
+ }
+
+ #[DataProvider('uploadRouteNotFound')]
+ public function testAnUploadRouteNotFoundReportsPostHogsAnswerAndSendsNothing(string $answer, string $message): void
+ {
+ $this->reply([404, $answer, []]);
+
+ $error = $this->sendError(self::sendWithFiles([self::invite()]));
+
+ $this->assertSame('not_found', $error->getErrorCode());
+ $this->assertSame('not_found', $error->getErrorName());
+ $this->assertSame(404, $error->getStatusCode());
+ $this->assertSame('attachments', $error->getField());
+ $this->assertSame($message, $error->getMessage());
+ $this->assertSame([], $this->storageWrites);
+ $this->assertSame([], $this->queued, 'no email was sent');
+ }
+
+ public function testAnUnavailableUploadRouteIsRetried(): void
+ {
+ $this->reply([503, '{"code":"delivery_unavailable"}', []], self::slots(self::presentSlot(self::INVITE_SHA256)));
+
+ $result = $this->emails()->send(self::sendWithFiles([self::invite()]));
+
+ $this->assertSame('msg_1', $result->getId());
+ $this->assertCount(1, $this->queued);
+ }
+
+ public static function unusableUploadAnswers(): array
+ {
+ $slot = self::uploadSlot(self::INVITE);
+
+ return [
+ 'no slot for the file' => [['files' => [self::presentSlot(self::PNG_SHA256)]]],
+ 'no files' => [[]],
+ 'no status' => [['files' => [['sha256' => self::INVITE_SHA256]]]],
+ 'an unknown status' => [['files' => [['status' => 'later'] + $slot]]],
+ 'a file URL' => [['files' => [['url' => 'file:///etc/passwd'] + $slot]]],
+ 'another method' => [['files' => [['method' => 'POST'] + $slot]]],
+ 'a header with a line break' => [['files' => [['headers' => ['X-A' => "a\r\nAuthorization: b"]] + $slot]]],
+ 'headers as a list' => [['files' => [['headers' => ['Content-Length: 32']] + $slot]]],
+ ];
+ }
+
+ #[DataProvider('unusableUploadAnswers')]
+ public function testAnUploadAnswerTheClientCannotFollowSendsNothing(array $answer): void
+ {
+ $this->reply([200, json_encode($answer), []]);
+ set_error_handler(static function (int $severity, string $message): never {
+ throw new \ErrorException($message, 0, $severity);
+ });
+
+ try {
+ $error = $this->sendError(self::sendWithFiles([self::invite()]));
+ } finally {
+ restore_error_handler();
+ }
+
+ $this->assertSame('api_error', $error->getErrorCode());
+ $this->assertSame([], $this->storageWrites);
+ $this->assertSame([], $this->queued, 'no email was sent');
+ }
+
+ public function testAPlainHttpUploadUrlIsRefusedBeforeAnyUpload(): void
+ {
+ $plainUrl = 'http://attachments.example/team/2/' . self::INVITE_SHA256 . self::SIGNATURE;
+ $this->reply(self::slots(['url' => $plainUrl] + self::uploadSlot(self::INVITE)));
+
+ $error = $this->sendError(self::sendWithFiles([self::invite()]));
+
+ $this->assertSame('api_error', $error->getErrorCode());
+ $this->assertSame('attachments__0__content', $error->getField());
+ $this->assertStringContainsString('invite.ics', $error->getMessage());
+ $this->assertStringContainsString("Fix the file storage's URL", $error->getFix());
+ $this->assertStringNotContainsString('attachments.example', $error->getMessage() . $error->getFix());
+ $this->assertSame([], $this->storageWrites);
+ $this->assertSame([], $this->queued, 'no email was sent');
+ }
+
+ public function testAPlainHttpAppHostForLocalDevelopmentUploadsOverPlainHttp(): void
+ {
+ $plainUrl = 'http://localhost:8333/team/2/' . self::INVITE_SHA256 . self::SIGNATURE;
+ $this->reply(self::slots(['url' => $plainUrl] + self::uploadSlot(self::INVITE)), [200, '', []]);
+
+ $result = $this->emails(['appHost' => 'http://localhost:8010'])->send(self::sendWithFiles([self::invite()]));
+
+ $this->assertSame('msg_1', $result->getId());
+ $this->assertSame(self::INVITE, $this->stored[self::INVITE_SHA256]);
+ }
+
+ public static function subjectsAndTheLargestFileThatFits(): array
+ {
+ return [
+ 'a 12-byte subject adds 75' => ['Your receipt', 29_182_812],
+ '42 ASCII bytes add 75' => [str_repeat('s', 42), 29_182_812],
+ '43 ASCII bytes add 150' => [str_repeat('s', 43), 29_182_758],
+ '21 two-byte characters add 75' => [str_repeat('é', 21), 29_182_812],
+ '22 two-byte characters add 150' => [str_repeat('é', 22), 29_182_758],
+ ];
+ }
+
+ #[DataProvider('subjectsAndTheLargestFileThatFits')]
+ public function testTheLargestFileThatFitsBesideTheSubjectIsUploaded(string $subject, int $largest): void
+ {
+ $file = str_repeat('a', $largest);
+ $this->reply(self::slots(self::presentSlot(hash('sha256', $file))));
+
+ $result = $this->emails()->send(
+ self::sendWithFiles([['filename' => 'big.pdf', 'content' => $file]], ['subject' => $subject])
+ );
+
+ $this->assertSame('msg_1', $result->getId());
+ }
+
+ #[DataProvider('subjectsAndTheLargestFileThatFits')]
+ public function testOneByteMoreThanFitsBesideTheSubjectIsRefused(string $subject, int $largest): void
+ {
+ $file = str_repeat('a', $largest + 1);
+
+ $error = $this->sendError(
+ self::sendWithFiles([['filename' => 'big.pdf', 'content' => $file]], ['subject' => $subject])
+ );
+
+ $this->assertSame('message_too_large', $error->getErrorCode());
+ $this->assertSame([], $this->storageWrites);
+ $this->assertSame([], $this->queued, 'no email was sent');
+ }
+
+ public static function messagesTooLarge(): array
+ {
+ return [
+ 'a body that leaves no room' => [[str_repeat('a', 29_000_000)], ['text' => str_repeat('b', 200_000)]],
+ 'files that only fit alone' => [[str_repeat('a', 15_000_000), str_repeat('b', 15_000_000)], []],
+ 'an HTML body that fits once but not again as its derived text' => [
+ [str_repeat('a', 29_000_000)],
+ ['html' => str_repeat('h', 100_000), 'text' => ''],
+ ],
+ ];
+ }
+
+ #[DataProvider('messagesTooLarge')]
+ public function testAMessageOverFortyMegabytesIsRefusedBeforeAnyRequest(array $contents, array $email): void
+ {
+ $files = array_map(
+ static fn(string $content): array => ['filename' => 'f.pdf', 'content' => $content],
+ $contents
+ );
+
+ $error = $this->sendError(self::sendWithFiles($files, $email));
+
+ $this->assertSame('message_too_large', $error->getErrorCode());
+ $this->assertSame('validation_error', $error->getErrorName());
+ $this->assertSame('attachments', $error->getField());
+ $this->assertNull($error->getStatusCode());
+ $this->assertStringContainsString('40 MB', $error->getMessage());
+ $this->assertStringContainsString('about 29 MB of files', $error->getWhy());
+ $this->assertSame([], $this->storageWrites);
+ $this->assertSame([], $this->queued, 'no email was sent');
+ }
+
+ public function testMoreThanTenFilesAreRefusedBeforeAnyRequest(): void
+ {
+ $error = $this->sendError(self::sendWithFiles(array_fill(0, 11, self::invite())));
+
+ $this->assertSame('too_many_attachments', $error->getErrorCode());
+ $this->assertSame('validation_error', $error->getErrorName());
+ $this->assertSame('attachments', $error->getField());
+ $this->assertSame([], $this->storageWrites);
+ $this->assertSame([], $this->queued, 'no email was sent');
+ }
+
+ public function testEmptyCopyAndAttachmentListsAreLeftOut(): void
+ {
+ $this->emails()->send([
+ 'to' => 'user@example.com',
+ 'template_key' => 'receipt',
+ 'subject' => 'Your receipt',
+ 'text' => 'Thanks!',
+ 'cc' => [],
+ 'bcc' => [],
+ 'attachments' => [],
+ ]);
+
+ $this->assertSame([
+ 'template_key' => 'receipt',
+ 'subject' => 'Your receipt',
+ 'text' => 'Thanks!',
+ 'to' => 'user@example.com',
+ ], $this->body());
+ }
+
public function testAGeneratedIdempotencyKeyIsAUuidV4ReusedOnEveryAttempt(): void
{
$this->reply([503, '{"code":"unavailable"}', []], [202, '{"message_id":"msg_1"}', []]);
@@ -371,7 +1031,14 @@ public static function argumentErrors(): array
],
'tracking with a template' => [$template + ['tracking' => false], 'invalid_form', 'tracking'],
'sensitive with a template' => [$template + ['sensitive' => true], 'invalid_form', 'sensitive'],
- 'unknown option' => [$template + ['cc' => 'boss@example.com'], 'invalid_form', 'cc'],
+ 'unknown option' => [$template + ['headers' => ['X-A' => 'b']], 'invalid_form', 'headers'],
+ 'cc with a template' => [$template + ['cc' => 'boss@example.com'], 'invalid_form', 'cc'],
+ 'bcc with a template' => [$template + ['bcc' => ['boss@example.com']], 'invalid_form', 'bcc'],
+ 'attachments with a template' => [
+ $template + ['attachments' => [['filename' => 'a.txt', 'content' => 'hi']]],
+ 'invalid_form',
+ 'attachments',
+ ],
'template_data with code' => [$code + ['template_data' => ['a' => 1]], 'invalid_form', 'template_data'],
'bad template key' => [['template_key' => 'pass word'] + $code, 'invalid_template_key', 'template_key'],
'template key too long' => [
@@ -386,6 +1053,9 @@ public static function argumentErrors(): array
'html not a string' => [['html' => ['']] + $code, 'invalid_form', 'html'],
'empty from' => [$code + ['from' => ''], 'invalid_form', 'from'],
'blank reply_to' => [$code + ['reply_to' => ['a@example.com', ' ']], 'invalid_form', 'reply_to'],
+ 'blank cc' => [$code + ['cc' => ' '], 'invalid_form', 'cc'],
+ 'bcc not text' => [$code + ['bcc' => [123]], 'invalid_form', 'bcc'],
+ 'cc as a map' => [$code + ['cc' => ['boss' => 'boss@example.com']], 'invalid_form', 'cc'],
'capture_engagement not a bool' => [
$code + ['capture_engagement' => 'no'],
'invalid_form',
@@ -423,6 +1093,84 @@ public function testAFailedArgumentCheckSendsNothing(array $email, string $code,
$this->assertSame([], $this->requests);
}
+ public static function attachmentErrors(): array
+ {
+ $file = ['filename' => 'a.txt', 'content' => self::SECRET_CONTENT];
+
+ return [
+ 'one file, not a list' => [$file, 'attachments'],
+ 'content, not a list' => [self::SECRET_CONTENT, 'attachments'],
+ 'file not an array' => [[self::SECRET_CONTENT], 'attachments__0'],
+ 'file as a list' => [[['a.txt', self::SECRET_CONTENT]], 'attachments__0'],
+ 'no content' => [[['filename' => 'a.txt']], 'attachments__0__content'],
+ 'content as a list of bytes' => [
+ [['filename' => 'a.txt', 'content' => array_map('ord', str_split(self::SECRET_CONTENT))]],
+ 'attachments__0__content',
+ ],
+ 'no filename' => [[['content' => self::SECRET_CONTENT]], 'attachments__0__filename'],
+ 'empty content' => [[['filename' => 'a.txt', 'content' => '']], 'attachments__0__content'],
+ 'filename not text' => [[['filename' => 1] + $file], 'attachments__0__filename'],
+ 'path' => [[$file + ['path' => '/tmp/a.txt']], 'attachments__0__path'],
+ 'unknown field' => [[$file + ['contentType' => 'text/plain']], 'attachments__0__contentType'],
+ 'second file with content_type not text' => [
+ [$file, $file + ['content_type' => 1]],
+ 'attachments__1__content_type',
+ ],
+ 'content_id not text' => [[$file + ['content_id' => ['logo']]], 'attachments__0__content_id'],
+ 'filename not UTF-8' => [[['filename' => "Rechnung_M\xE4rz.pdf"] + $file], 'attachments__0__filename'],
+ 'content_type not UTF-8' => [[$file + ['content_type' => "text/pl\xE4in"]], 'attachments__0__content_type'],
+ 'content_id not UTF-8' => [[$file + ['content_id' => "l\xF6go"]], 'attachments__0__content_id'],
+ ];
+ }
+
+ public static function invalidOptionsBesideFiles(): array
+ {
+ return [
+ 'sensitive not a bool' => [['sensitive' => 'yes'], 'sensitive'],
+ 'tracking not a bool or array' => [['tracking' => 'off'], 'tracking'],
+ ];
+ }
+
+ #[DataProvider('invalidOptionsBesideFiles')]
+ public function testAnInvalidOptionOnASendWithFilesUploadsNothing(array $option, string $field): void
+ {
+ $this->reply(self::NEGOTIATE, [200, '', []], [202, '{"message_id":"msg_1"}', []]);
+
+ $error = $this->sendError([
+ 'to' => 'user@example.com',
+ 'template_key' => 'invite',
+ 'subject' => 'You are invited',
+ 'text' => 'See you there',
+ 'attachments' => [['filename' => 'invite.ics', 'content' => self::INVITE]],
+ ] + $option);
+
+ $this->assertSame('invalid_form', $error->getErrorCode());
+ $this->assertSame($field, $error->getField());
+ $this->assertSame([], $this->storageWrites, 'no file was uploaded');
+ $this->assertSame([], $this->queued, 'nothing was sent');
+ }
+
+ #[DataProvider('attachmentErrors')]
+ public function testAnAttachmentTheClientCannotSendIsRefusedWithoutRepeatingItsContent(
+ mixed $attachments,
+ string $field
+ ): void {
+ $error = $this->sendError([
+ 'to' => 'user@example.com',
+ 'template_key' => 'receipt',
+ 'subject' => 'Your receipt',
+ 'text' => 'Thanks!',
+ 'attachments' => $attachments,
+ ]);
+
+ $this->assertSame('invalid_attachment', $error->getErrorCode());
+ $this->assertSame('validation_error', $error->getErrorName());
+ $this->assertSame($field, $error->getField());
+ $this->assertStringNotContainsString(self::SECRET_CONTENT, $error->getMessage() . $error->getFix());
+ $this->assertSame([], $this->storageWrites);
+ $this->assertSame([], $this->queued);
+ }
+
public function testAnOptionOfTheOtherFormSaysHowToSendIt(): void
{
$error = $this->sendError([
diff --git a/test/LocalHttpServer.php b/test/LocalHttpServer.php
index bebe15c0..f74c188b 100644
--- a/test/LocalHttpServer.php
+++ b/test/LocalHttpServer.php
@@ -41,6 +41,23 @@ public function address(): string
}
public function requests(): array
+ {
+ return array_map(static function (array $request): array {
+ unset($request['status']);
+ return $request;
+ }, $this->answered());
+ }
+
+ /** The requests the server answered with a 2xx status, which it took. */
+ public function acceptedRequests(): array
+ {
+ return array_values(array_map(static function (array $request): array {
+ unset($request['status']);
+ return $request;
+ }, array_filter($this->answered(), static fn(array $request): bool => intdiv($request['status'], 100) === 2)));
+ }
+
+ private function answered(): array
{
return array_map(
static fn(string $line): array => json_decode($line, true, 512, JSON_THROW_ON_ERROR),
diff --git a/test/fixtures/http-server.php b/test/fixtures/http-server.php
index feae8073..729f3539 100644
--- a/test/fixtures/http-server.php
+++ b/test/fixtures/http-server.php
@@ -31,13 +31,35 @@
if (($headers['content-encoding'] ?? '') === 'gzip') {
$body = gzdecode($body);
}
+ $next = $responses[0] ?? [];
+ $refusal = null;
+ foreach ($next['accepts'] ?? [] as $name => $expected) {
+ $actual = match ($name) {
+ 'request_line' => $requestLine,
+ 'json_body' => json_decode($body, true),
+ default => $headers[$name] ?? null,
+ };
+ if ($name === 'json_body' ? $actual != $expected : $actual !== $expected) {
+ $refusal = $next['refusal'];
+ }
+ }
+ $checksum = $headers['x-amz-checksum-sha256'] ?? null;
+ if ($checksum !== null && $checksum !== base64_encode(hash('sha256', $body, true))) {
+ $refusal = ['status' => 400, 'body' => 'BadDigest'
+ . 'The SHA256 you specified did not match the calculated checksum.'];
+ }
+ if (str_contains($requestLine, 'X-Amz-Signature=') && isset($headers['authorization'])) {
+ $refusal = ['status' => 400, 'body' => ''
+ . 'InvalidArgumentOnly one auth mechanism allowed'];
+ }
+ $response = $refusal ?? array_shift($responses) ?? [];
file_put_contents($argv[1], json_encode([
'requestLine' => $requestLine,
'headers' => $headers,
'body' => $body,
+ 'status' => $response['status'] ?? 200,
], JSON_THROW_ON_ERROR) . "\n", FILE_APPEND);
-
- $response = array_shift($responses) ?? [];
+ usleep(($response['delay_ms'] ?? 0) * 1000);
$closeServer = $response['close_server'] ?? false;
if ($closeServer) {
fclose($server);