Skip to content

An open-source, self-hostable PaaS alternative to Vercel, Heroku & Netlify that lets you easily deploy static sites, databases, full-stack applications and 360+ one-click services on your own servers.

feat(traffic): add Sentinel traffic pull client

Aditya Tripathi2ce3bce6086f
diff --git a/app/Services/SentinelTrafficClient.php b/app/Services/SentinelTrafficClient.php
new file mode 100644
index 0000000000..91209756f2
--- /dev/null
+++ b/app/Services/SentinelTrafficClient.php
@@ -0,0 +1,80 @@
+<?php
+
+namespace App\Services;
+
+use App\Data\Traffic\TrafficBreakdownData;
+use App\Data\Traffic\TrafficOverviewData;
+use App\Data\Traffic\TrafficPathData;
+use App\Models\Server;
+use Illuminate\Support\Collection;
+
+class SentinelTrafficClient
+{
+ private string $base = 'http://localhost:8888/api';
+
+ public function __construct(protected Server $server) {}
+
+ // NOTE: Sentinel's traffic API expects `from`/`to` as ISO-8601 Zulu strings
+ // (e.g. "2024-01-14T10:00:00Z"), confirmed against sentinel/API.md.
+ public function overview(?string $appKey, string $from, string $to): TrafficOverviewData
+ {
+ $path = $appKey ? "/app/{$appKey}/traffic/overview" : '/traffic/overview';
+ $json = json_decode($this->raw($this->url($path, ['from' => $from, 'to' => $to])), true) ?? [];
+
+ return TrafficOverviewData::fromSentinel($json);
+ }
+
+ public function paths(?string $appKey, string $from, string $to, int $limit = 50): Collection
+ {
+ $path = $appKey ? "/app/{$appKey}/traffic/paths" : '/traffic/paths';
+ $rows = json_decode($this->raw($this->url($path, ['from' => $from, 'to' => $to, 'limit' => $limit])), true) ?? [];
+
+ return collect($rows)->map(fn ($r) => TrafficPathData::fromSentinel($r));
+ }
+
+ public function breakdown(?string $appKey, string $dimension, string $from, string $to, int $limit = 50): Collection
+ {
+ $path = $appKey ? "/app/{$appKey}/traffic/breakdown/{$dimension}" : "/traffic/breakdown/{$dimension}";
+ $rows = json_decode($this->raw($this->url($path, ['from' => $from, 'to' => $to, 'limit' => $limit])), true) ?? [];
+
+ return collect($rows)->map(fn ($r) => TrafficBreakdownData::fromSentinel($r));
+ }
+
+ public function apps(): array
+ {
+ return json_decode($this->raw($this->url('/traffic/apps')), true) ?? [];
+ }
+
+ public function attribution(): ?string
+ {
+ $json = json_decode($this->raw($this->url('/traffic/attribution')), true) ?? [];
+
+ return data_get($json, 'attribution');
+ }
+
+ private function url(string $path, array $query = []): string
+ {
+ // Colons in ISO-8601 Zulu timestamps are safe in a query string; keep them
+ // unencoded to match Sentinel's expected `from`/`to` format.
+ $qs = empty($query) ? '' : '?'.str_replace('%3A', ':', http_build_query($query));
+
+ return $this->base.$path.$qs;
+ }
+
+ protected function raw(string $url): string
+ {
+ $token = $this->server->settings->ensureValidSentinelToken();
+ $response = instant_remote_process(
+ ["docker exec coolify-sentinel sh -c 'curl -H \"Authorization: Bearer {$token}\" {$url}'"],
+ $this->server,
+ false
+ );
+
+ if (str($response)->contains('"error"')) {
+ $error = data_get(json_decode($response, true), 'error', 'Traffic analytics request failed.');
+ throw new \Exception($error);
+ }
+
+ return $response;
+ }
+}
diff --git a/tests/Feature/TrafficAnalytics/SentinelTrafficClientTest.php b/tests/Feature/TrafficAnalytics/SentinelTrafficClientTest.php
new file mode 100644
index 0000000000..5e86d30aa2
--- /dev/null
+++ b/tests/Feature/TrafficAnalytics/SentinelTrafficClientTest.php
@@ -0,0 +1,50 @@
+<?php
+
+use App\Data\Traffic\TrafficOverviewData;
+use App\Models\Server;
+use App\Models\Team;
+use App\Services\SentinelTrafficClient;
+use Illuminate\Foundation\Testing\RefreshDatabase;
+
+uses(RefreshDatabase::class);
+
+beforeEach(function () {
+ $this->team = Team::factory()->create();
+});
+
+class FakeTrafficClient extends SentinelTrafficClient
+{
+ public array $captured = [];
+
+ public string $response = '{}';
+
+ protected function raw(string $url): string
+ {
+ $this->captured[] = $url;
+
+ return $this->response;
+ }
+}
+
+it('builds per-app overview url and parses response', function () {
+ $server = Server::factory()->create(['team_id' => $this->team->id]);
+ $client = new FakeTrafficClient($server);
+ $client->response = json_encode([
+ 'requests' => 3, 'bytes_in' => 1, 'bytes_out' => 2,
+ 'status' => ['s2xx' => 3, 's3xx' => 0, 's4xx' => 0, 's5xx' => 0],
+ 'latency' => ['p50' => 1, 'p95' => 2, 'p99' => 3], 'unique_visitors' => 2,
+ ]);
+
+ $dto = $client->overview('app-uuid', '2026-08-01T00:00:00Z', '2026-08-02T00:00:00Z');
+ expect($dto)->toBeInstanceOf(TrafficOverviewData::class)->and($dto->requests)->toBe(3);
+ expect($client->captured[0])->toContain('/api/app/app-uuid/traffic/overview')
+ ->toContain('from=2026-08-01T00:00:00Z')->toContain('to=2026-08-02T00:00:00Z');
+});
+
+it('builds server-wide overview url when appKey is null', function () {
+ $server = Server::factory()->create(['team_id' => $this->team->id]);
+ $client = new FakeTrafficClient($server);
+ $client->response = json_encode(['requests' => 0]);
+ $client->overview(null, 'a', 'b');
+ expect($client->captured[0])->toContain('/api/traffic/overview')->not->toContain('/app/');
+});