feat: wrap tail log responses in typed TailLog value object

spec/SupervisorSpec.php

@@ -6,6 +6,7 @@
 use PhpSpec\ObjectBehavior;
 use Supervisor\Process;
 use Supervisor\Supervisor;
+use Supervisor\TailLog;
 
 class SupervisorSpec extends ObjectBehavior
 {
@@ -83,4 +84,30 @@ function it_returns_a_process_(ClientInterface $client)
         $process->shouldHaveType(Process::class);
         $process->getName()->shouldReturn('process_name');
     }
+
+    function it_tails_process_stdout_log(ClientInterface $client)
+    {
+        $client->call('supervisor.tailProcessStdoutLog', ['process_name', 0, 100])
+            ->willReturn(['log content', 11, false]);
+
+        $result = $this->tailProcessStdoutLog('process_name', 0, 100);
+
+        $result->shouldHaveType(TailLog::class);
+        $result->getBytes()->shouldReturn('log content');
+        $result->getOffset()->shouldReturn(11);
+        $result->isOverflow()->shouldReturn(false);
+    }
+
+    function it_tails_process_stderr_log(ClientInterface $client)
+    {
+        $client->call('supervisor.tailProcessStderrLog', ['process_name', 0, 100])
+            ->willReturn(['error content', 13, true]);
+
+        $result = $this->tailProcessStderrLog('process_name', 0, 100);
+
+        $result->shouldHaveType(TailLog::class);
+        $result->getBytes()->shouldReturn('error content');
+        $result->getOffset()->shouldReturn(13);
+        $result->isOverflow()->shouldReturn(true);
+    }
 }

spec/TailLogSpec.php

@@ -0,0 +1,56 @@
+<?php
+
+namespace spec\Supervisor;
+
+use PhpSpec\ObjectBehavior;
+use Supervisor\TailLog;
+use Supervisor\TailLogInterface;
+
+class TailLogSpec extends ObjectBehavior
+{
+    function let()
+    {
+        $this->beConstructedWith('log content', 11, false);
+    }
+
+    function it_is_initializable()
+    {
+        $this->shouldHaveType(TailLog::class);
+    }
+
+    function it_implements_tail_log_interface()
+    {
+        $this->shouldImplement(TailLogInterface::class);
+    }
+
+    function it_returns_bytes()
+    {
+        $this->getBytes()->shouldReturn('log content');
+    }
+
+    function it_returns_offset()
+    {
+        $this->getOffset()->shouldReturn(11);
+    }
+
+    function it_returns_overflow_flag()
+    {
+        $this->isOverflow()->shouldReturn(false);
+    }
+
+    function it_can_be_built_from_tail_log_response()
+    {
+        $this->beConstructedThrough('fromTailLog', [['log content', 11, false]]);
+
+        $this->getBytes()->shouldReturn('log content');
+        $this->getOffset()->shouldReturn(11);
+        $this->isOverflow()->shouldReturn(false);
+    }
+
+    function it_casts_overflow_to_bool_when_built_from_response()
+    {
+        $this->beConstructedThrough('fromTailLog', [['data', 5, 1]]);
+
+        $this->isOverflow()->shouldReturn(true);
+    }
+}

src/Supervisor.php

@@ -37,8 +37,6 @@
  * @method bool removeProcessGroup(string $name)
  * @method string readProcessStdoutLog(string $name, integer $offset, integer $limit)
  * @method string readProcessStderrLog(string $name, integer $offset, integer $limit)
- * @method array tailProcessStdoutLog(string $name, integer $offset, integer $limit)
- * @method array tailProcessStderrLog(string $name, integer $offset, integer $limit)
  * @method bool clearProcessLogs(string $name)
  * @method array clearAllProcessLogs()
  * @method array reloadConfig()
@@ -156,6 +154,26 @@ public function getProcess(string $name): ProcessInterface
         return new Process($process);
     }
 
+    /**
+     * @inheritDoc
+     */
+    public function tailProcessStdoutLog(string $name, int $offset, int $limit): TailLogInterface
+    {
+        return TailLog::fromTailLog(
+            $this->call('supervisor', 'tailProcessStdoutLog', [$name, $offset, $limit])
+        );
+    }
+
+    /**
+     * @inheritDoc
+     */
+    public function tailProcessStderrLog(string $name, int $offset, int $limit): TailLogInterface
+    {
+        return TailLog::fromTailLog(
+            $this->call('supervisor', 'tailProcessStderrLog', [$name, $offset, $limit])
+        );
+    }
+
     /**
      * @inheritDoc
      */

src/SupervisorInterface.php

@@ -35,8 +35,6 @@
  * @method bool removeProcessGroup(string $name)
  * @method string readProcessStdoutLog(string $name, integer $offset, integer $limit)
  * @method string readProcessStderrLog(string $name, integer $offset, integer $limit)
- * @method array tailProcessStdoutLog(string $name, integer $offset, integer $limit)
- * @method array tailProcessStderrLog(string $name, integer $offset, integer $limit)
  * @method bool clearProcessLogs(string $name)
  * @method array clearAllProcessLogs()
  * @method array reloadConfig()
@@ -107,6 +105,10 @@ public function getAllProcesses(): array;
      */
     public function getProcess(string $name): ProcessInterface;
 
+    public function tailProcessStdoutLog(string $name, int $offset, int $limit): TailLogInterface;
+
+    public function tailProcessStderrLog(string $name, int $offset, int $limit): TailLogInterface;
+
     /**
      * Reload configuration and apply process changes immediately, i.e.:
      *   - Start any processes newly added in the configuration,

src/TailLog.php

@@ -0,0 +1,38 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Supervisor;
+
+final class TailLog implements TailLogInterface
+{
+    public function __construct(
+        private readonly string $bytes,
+        private readonly int $offset,
+        private readonly bool $overflow,
+    ) {}
+
+    public static function fromTailLog(array $data): self
+    {
+        return new self(
+            bytes: $data[0],
+            offset: $data[1],
+            overflow: (bool) $data[2],
+        );
+    }
+
+    public function getBytes(): string
+    {
+        return $this->bytes;
+    }
+
+    public function getOffset(): int
+    {
+        return $this->offset;
+    }
+
+    public function isOverflow(): bool
+    {
+        return $this->overflow;
+    }
+}

src/TailLogInterface.php

@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Supervisor;
+
+interface TailLogInterface
+{
+    public function getBytes(): string;
+
+    public function getOffset(): int;
+
+    /**
+     * True when the log output was truncated due to length; fetch again from getOffset() to get more.
+     */
+    public function isOverflow(): bool;
+}