feat: add attachment support

Author: Litarnus

src/Attachment/Attachment.php

@@ -0,0 +1,75 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Sentry\Attachment;
+
+abstract class Attachment
+{
+    private const DEFAULT_CONTENT_TYPE = 'application/octet-stream';
+
+    /**
+     * @var string
+     */
+    private $filename;
+
+    /**
+     * @var string
+     */
+    private $contentType;
+
+    public function __construct(string $filename, string $contentType)
+    {
+        $this->filename = $filename;
+        $this->contentType = $contentType;
+    }
+
+    public function getFilename(): string
+    {
+        return $this->filename;
+    }
+
+    public function getContentType(): string
+    {
+        return $this->contentType;
+    }
+
+    /**
+     * Returns the size in bytes for the attachment. This method should aim to use a low overhead
+     * way of determining the size because it will be called more than once.
+     * For example, for file attachments it should read the file size from the filesystem instead of
+     * reading the file in memory and then calculating the length.
+     * If no low overhead way exists, then the result should be cached so that calling it multiple times
+     * does not decrease performance.
+     *
+     * @return int the size in bytes or null if the length could not be determined, for example if the file
+     *             does not exist
+     */
+    abstract public function getSize(): ?int;
+
+    /**
+     * Fetches and returns the data. Calling this can have a non-trivial impact on memory usage, depending
+     * on the type and size of attachment.
+     *
+     * @return string the content as bytes or null if the content could not be retrieved, for example if the file
+     *                does not exist
+     */
+    abstract public function getData(): ?string;
+
+    /**
+     * Creates a new attachment representing a file referenced by a path.
+     * The file is not validated and the content is not read when creating the attachment.
+     */
+    public static function fromFile(string $path, string $contentType = self::DEFAULT_CONTENT_TYPE): Attachment
+    {
+        return new FileAttachment($path, $contentType);
+    }
+
+    /**
+     * Creates a new attachment representing a slice of bytes that lives in memory.
+     */
+    public static function fromBytes(string $filename, string $data, string $contentType = self::DEFAULT_CONTENT_TYPE): Attachment
+    {
+        return new ByteAttachment($filename, $contentType, $data);
+    }
+}

src/Attachment/ByteAttachment.php

@@ -0,0 +1,30 @@
+<?php
+
+namespace Sentry\Attachment;
+
+/**
+ * Represents an attachment that is stored in memory and will not be read from the filesystem.
+ */
+class ByteAttachment extends Attachment
+{
+    /**
+     * @var string
+     */
+    private $data;
+
+    public function __construct(string $filename, string $contentType, string $data)
+    {
+        parent::__construct($filename, $contentType);
+        $this->data = $data;
+    }
+
+    public function getSize(): ?int
+    {
+        return \strlen($this->data);
+    }
+
+    public function getData(): ?string
+    {
+        return $this->data;
+    }
+}

src/Attachment/FileAttachment.php

@@ -0,0 +1,31 @@
+<?php
+
+namespace Sentry\Attachment;
+
+/**
+ * Represents a file that is readable by using a path.
+ */
+class FileAttachment extends Attachment
+{
+
+    /**
+     * @var string
+     */
+    private $path;
+
+    public function __construct(string $path, string $contentType)
+    {
+        parent::__construct(basename($path), $contentType);
+        $this->path = $path;
+    }
+
+    public function getSize(): ?int
+    {
+        return @filesize($this->path) ?: null;
+    }
+
+    public function getData(): ?string
+    {
+        return @file_get_contents($this->path) ?: null;
+    }
+}

src/Event.php

@@ -4,6 +4,7 @@
 
 namespace Sentry;
 
+use Sentry\Attachment\Attachment;
 use Sentry\Context\OsContext;
 use Sentry\Context\RuntimeContext;
 use Sentry\Logs\Log;
@@ -204,6 +205,11 @@ final class Event
      */
     private $profile;
 
+    /**
+     * @var Attachment[]
+     */
+    private $attachments = [];
+
     private function __construct(?EventId $eventId, EventType $eventType)
     {
         $this->id = $eventId ?? EventId::generate();
@@ -241,6 +247,11 @@ public static function createLogs(?EventId $eventId = null): self
         return new self($eventId, EventType::logs());
     }
 
+    public static function createAttachments(?EventId $eventId = null): self
+    {
+        return new self($eventId, EventType::attachment());
+    }
+
     /**
      * Gets the ID of this event.
      */
@@ -933,4 +944,20 @@ public function getTraceId(): ?string
 
         return null;
     }
+
+    /**
+     * @return Attachment[]
+     */
+    public function getAttachments(): array
+    {
+        return $this->attachments;
+    }
+
+    /**
+     * @param Attachment[] $attachments
+     */
+    public function setAttachments(array $attachments): void
+    {
+        $this->attachments = $attachments;
+    }
 }

src/EventType.php

@@ -47,6 +47,11 @@ public static function logs(): self
         return self::getInstance('log');
     }
 
+    public static function attachment(): self
+    {
+        return self::getInstance('attachment');
+    }
+
     /**
      * List of all cases on the enum.
      *
@@ -59,6 +64,7 @@ public static function cases(): array
             self::transaction(),
             self::checkIn(),
             self::logs(),
+            self::attachment()
         ];
     }
 

src/Serializer/EnvelopItems/AttachmentItem.php

@@ -0,0 +1,67 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Sentry\Serializer\EnvelopItems;
+
+use Sentry\Attachment\Attachment;
+use Sentry\Event;
+use Sentry\Util\JSON;
+
+class AttachmentItem implements EnvelopeItemInterface
+{
+    /**
+     * {@inheritDoc}
+     */
+    public static function toEnvelopeItem(Event $event)
+    {
+        $attachments = $event->getAttachments();
+
+        $items = [];
+
+        foreach ($attachments as $attachment) {
+            $header = [
+                'filename' => $attachment->getFilename(),
+                'content_type' => $attachment->getContentType(),
+                'attachment_type' => 'event.attachment',
+            ];
+
+            $items[] = \sprintf("%s\n%s", JSON::encode($header), file_get_contents($attachment->getFilename()));
+        }
+
+        return $items;
+    }
+
+    public static function toAttachmentItem(Attachment $attachment): ?string
+    {
+        $data = $attachment->getData();
+        if ($data === null) {
+            return null;
+        }
+
+        $header = [
+            'type' => 'attachment',
+            'filename' => $attachment->getFilename(),
+            'content_type' => $attachment->getContentType(),
+            'attachment_type' => 'event.attachment',
+            'length' => $attachment->getSize(),
+        ];
+
+        return \sprintf("%s\n%s", JSON::encode($header), $data);
+    }
+
+    /**
+     * Returns the total size of all attachments in bytes.
+     *
+     * @param Attachment[] $attachments
+     */
+    public static function totalAttachmentSize(array $attachments): int
+    {
+        $sum = 0;
+        foreach ($attachments as $attachment) {
+            $sum += $attachment->getSize();
+        }
+
+        return $sum;
+    }
+}

src/Serializer/EnvelopItems/EnvelopeItemInterface.php

@@ -11,5 +11,9 @@
  */
 interface EnvelopeItemInterface
 {
-    public static function toEnvelopeItem(Event $event): ?string;
+    /**
+     * @param Event $event
+     * @return ?string|string[]
+     */
+    public static function toEnvelopeItem(Event $event);
 }

src/Serializer/PayloadSerializer.php

@@ -7,6 +7,7 @@
 use Sentry\Event;
 use Sentry\EventType;
 use Sentry\Options;
+use Sentry\Serializer\EnvelopItems\AttachmentItem;
 use Sentry\Serializer\EnvelopItems\CheckInItem;
 use Sentry\Serializer\EnvelopItems\EventItem;
 use Sentry\Serializer\EnvelopItems\LogsItem;
@@ -23,6 +24,11 @@
  */
 final class PayloadSerializer implements PayloadSerializerInterface
 {
+    /**
+     * Attachments have a limit of 100MB before compression.
+     */
+    private const MAX_ATTACHMENT_SIZE = 100000000;
+
     /**
      * @var Options The SDK client options
      */
@@ -75,6 +81,13 @@ public function serialize(Event $event): string
                 break;
         }
 
+        // If attachments are exceeding the limit, then we drop all attachments
+        if (AttachmentItem::totalAttachmentSize($event->getAttachments()) <= self::MAX_ATTACHMENT_SIZE) {
+            foreach ($event->getAttachments() as $attachment) {
+                $items[] = AttachmentItem::toAttachmentItem($attachment);
+            }
+        }
+
         return \sprintf("%s\n%s", JSON::encode($envelopeHeader), implode("\n", array_filter($items)));
     }
 }

src/State/Hub.php

@@ -5,6 +5,7 @@
 namespace Sentry\State;
 
 use Psr\Log\NullLogger;
+use Sentry\Attachment\Attachment;
 use Sentry\Breadcrumb;
 use Sentry\CheckIn;
 use Sentry\CheckInStatus;
@@ -231,6 +232,19 @@ public function addBreadcrumb(Breadcrumb $breadcrumb): bool
         return $breadcrumb !== null;
     }
 
+    public function addAttachment(Attachment $attachment): bool
+    {
+        $client = $this->getClient();
+
+        if ($client === null) {
+            return false;
+        }
+
+        $this->getScope()->addAttachment($attachment);
+
+        return true;
+    }
+
     /**
      * {@inheritdoc}
      */

src/State/HubInterface.php

@@ -4,6 +4,7 @@
 
 namespace Sentry\State;
 
+use Sentry\Attachment\Attachment;
 use Sentry\Breadcrumb;
 use Sentry\CheckInStatus;
 use Sentry\ClientInterface;
@@ -152,4 +153,6 @@ public function getSpan(): ?Span;
      * Sets the span on the Hub.
      */
     public function setSpan(?Span $span): HubInterface;
+
+    public function addAttachment(Attachment $attachment): bool;
 }