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.
PHP coolifydatabasesdeploymentdockerdocker-composeinertiajslaravelmariadbmysqlnextjsnodejsphppostgresredisself-hostedself-hostingserverstatic-sitesveltesvelte5
feat(analytics): use Sentinel resource scope for exact unique visitors
Andras Bacsai8d6871d1c746
diff --git a/app/Livewire/Analytics.php b/app/Livewire/Analytics.phpindex 2ebc6dc78f..9135147876 100644--- a/app/Livewire/Analytics.php+++ b/app/Livewire/Analytics.php@@ -331,7 +331,8 @@ class Analytics extends Component}[$from, $to] = $this->window();- // A selected application or service is queried under all of its Sentinel keys.+ // A selected application or service is queried in Sentinel's resource scope, or under+ // all of its keys on an older Sentinel.$resource = $this->selectedResource();$servers = $this->targetServers();$domainForKey = fn (string $key): ?string => $this->appMeta($key)['domain'];@@ -345,10 +346,9 @@ class Analytics extends Component$client = $this->trafficClient($server);if ($resource !== null) {- $keys = $client->prefetchResource($resource->uuid(), $from, $to, $this->breakdownDimensions, $this->range);- foreach ($keys as $key) {- $aggregator->collect($client, $key, $from, $to, $this->range, $domainForKey);- }+ // One server in Sentinel's resource scope is exact; a merge across servers+ // or the per-key fallback of an older Sentinel stays approximate.+ $aggregator->collectResource($client, $resource->uuid(), $from, $to, $this->range, $domainForKey);continue;}diff --git a/app/Livewire/Project/Application/TrafficOverview.php b/app/Livewire/Project/Application/TrafficOverview.phpindex 86a6ff64f4..6cc30605a0 100644--- a/app/Livewire/Project/Application/TrafficOverview.php+++ b/app/Livewire/Project/Application/TrafficOverview.php@@ -37,14 +37,19 @@ class TrafficOverview extends Componentif ($this->enabled && $server) {try {$client = app(SentinelTrafficClient::class, ['server' => $server]);- // Compose services and previews record under their own keys; sum all of them.- $keys = $client->resourceKeys($this->application->uuid);[$from, $to] = SentinelTrafficClient::rangeWindow('24h');- if (count($keys) > 1) {- $client->prefetchAppOverviews($keys, $from, $to);+ // Compose services and previews record under their own keys. Sentinel's resource+ // scope merges them exactly; an older Sentinel gets every key summed here.+ $overview = $client->tryResourceOverview($this->application->uuid, $from, $to);+ if ($overview === null) {+ $keys = $client->resourceKeys($this->application->uuid);+ if (count($keys) > 1) {+ $client->prefetchAppOverviews($keys, $from, $to);+ }+ $overviews = array_map(fn (string $key) => $client->overview($key, $from, $to), $keys);+ $overview = TrafficAnalyticsAggregator::sumOverviews($overviews)['overview'];}- $overviews = array_map(fn (string $key) => $client->overview($key, $from, $to), $keys);- $this->overview = TrafficAnalyticsAggregator::sumOverviews($overviews)['overview']->toArray();+ $this->overview = $overview->toArray();} catch (\Throwable $e) {$this->overview = null;}diff --git a/app/Livewire/Project/Shared/ResourceTrafficAnalytics.php b/app/Livewire/Project/Shared/ResourceTrafficAnalytics.phpindex 7ba0829855..a8a750f17e 100644--- a/app/Livewire/Project/Shared/ResourceTrafficAnalytics.php+++ b/app/Livewire/Project/Shared/ResourceTrafficAnalytics.php@@ -14,8 +14,8 @@ use Livewire\Component;/*** Traffic analytics tab of one resource (Application or Service). A resource can record- * under several Sentinel keys (compose services, previews); every key is fetched and- * merged into one view.+ * under several Sentinel keys (compose services, previews). Sentinel's resource scope+ * merges them exactly; an older Sentinel gets every key fetched and merged here.*/abstract class ResourceTrafficAnalytics extends Component{@@ -124,14 +124,10 @@ abstract class ResourceTrafficAnalytics extends Component[$from, $to] = SentinelTrafficClient::rangeWindow($this->range);$client = app(SentinelTrafficClient::class, ['server' => $resource->server()]);- // Resolve every key of this resource and warm all of them in one or two- // docker execs; the per-call methods below then read from cache.- $keys = $client->prefetchResource($resource->uuid(), $from, $to, $this->breakdownDimensions, $this->range);-+ // Sentinel's resource scope merges every key exactly in one docker exec. An older+ // Sentinel falls back to all keys of the resource, merged here (approximate).$aggregator = new TrafficAnalyticsAggregator($this->breakdownDimensions);- foreach ($keys as $key) {- $aggregator->collect($client, $key, $from, $to, $this->range, fn (string $appKey) => $resource->domainForKey($appKey));- }+ $aggregator->collectResource($client, $resource->uuid(), $from, $to, $this->range, fn (string $appKey) => $resource->domainForKey($appKey));$result = $aggregator->overview();$this->overview = $result['overview']->toArray();diff --git a/app/Services/SentinelTrafficClient.php b/app/Services/SentinelTrafficClient.phpindex 74e70367dd..cbbf9f971c 100644--- a/app/Services/SentinelTrafficClient.php+++ b/app/Services/SentinelTrafficClient.php@@ -17,6 +17,21 @@ class SentinelTrafficClient/** Record separator (0x1E) framing the batched curl responses in warm(). */private const RECORD_SEPARATOR = "\x1e";+ /**+ * Seconds to remember that this server's Sentinel has no `/api/resource/...` routes. Longer+ * than the data cache: every probe on an older Sentinel costs one or two wasted execs.+ */+ public const RESOURCE_SCOPE_ABSENCE_TTL = 300;++ /** Path segment of the per-key routes: `/api/app/{key}/traffic/...`. */+ private const SCOPE_APP = 'app';++ /**+ * Path segment of the resource routes: `/api/resource/{uuid}/traffic/...`. Sentinel merges+ * `{uuid}` and every `{uuid}-*` key exactly (HLL union for uniques, merged t-digests).+ */+ private const SCOPE_RESOURCE = 'resource';+/** @var array<int, string> */private const ALLOWED_DIMENSIONS = ['status', 'method', 'country', 'referer', 'browser', 'os', 'device', 'protocol', 'scheme', 'tls', 'cache', 'bot', 'agent', 'ip', 'useragent',@@ -28,9 +43,15 @@ class SentinelTrafficClient// (e.g. "2024-01-14T10:00:00Z"), confirmed against sentinel/API.md.public function overview(?string $appKey, string $from, string $to): TrafficOverviewData{- $json = json_decode($this->raw($this->overviewUrl($appKey, $from, $to)), true) ?? [];+ return $this->fetchOverview($this->overviewUrl($appKey, $from, $to));+ }- return TrafficOverviewData::fromSentinel($json);+ /**+ * Exact overview of one resource: every key of the resource merged by Sentinel.+ */+ public function resourceOverview(string $resourceUuid, string $from, string $to): TrafficOverviewData+ {+ return $this->fetchOverview($this->overviewUrl($resourceUuid, $from, $to, self::SCOPE_RESOURCE));}/**@@ -52,16 +73,25 @@ class SentinelTrafficClientpublic function paths(?string $appKey, string $from, string $to, int $limit = 50): Collection{- $rows = json_decode($this->raw($this->pathsUrl($appKey, $from, $to, $limit)), true) ?? [];+ return $this->fetchPaths($this->pathsUrl($appKey, $from, $to, $limit));+ }- return collect($rows)->map(fn ($r) => TrafficPathData::fromSentinel($r));+ /**+ * Top paths of one resource. Each row keeps the real Sentinel key in its `app` field.+ */+ public function resourcePaths(string $resourceUuid, string $from, string $to, int $limit = 50): Collection+ {+ return $this->fetchPaths($this->pathsUrl($resourceUuid, $from, $to, $limit, self::SCOPE_RESOURCE));}public function breakdown(?string $appKey, string $dimension, string $from, string $to, int $limit = 50): Collection{- $rows = json_decode($this->raw($this->breakdownUrl($appKey, $dimension, $from, $to, $limit)), true) ?? [];+ return $this->fetchBreakdown($this->breakdownUrl($appKey, $dimension, $from, $to, $limit));+ }- return collect($rows)->map(fn ($r) => TrafficBreakdownData::fromSentinel($r));+ public function resourceBreakdown(string $resourceUuid, string $dimension, string $from, string $to, int $limit = 50): Collection+ {+ return $this->fetchBreakdown($this->breakdownUrl($resourceUuid, $dimension, $from, $to, $limit, self::SCOPE_RESOURCE));}/**@@ -77,13 +107,84 @@ class SentinelTrafficClient*/public function series(?string $appKey, string $range = '24h'): Collection{- $rows = json_decode($this->raw($this->seriesUrl($appKey, $range)), true);+ return $this->fetchSeries($this->seriesUrl($appKey, $range));+ }- if (! is_array($rows) || $rows === []) {- return collect();+ /**+ * @return Collection<int, TrafficSeriesBucketData>+ */+ public function resourceSeries(string $resourceUuid, string $range = '24h'): Collection+ {+ return $this->fetchSeries($this->seriesUrl($resourceUuid, $range, self::SCOPE_RESOURCE));+ }++ /**+ * False while this server's Sentinel is known to lack the resource routes; callers then+ * use the per-key path (resourceKeys() and a merge in TrafficAnalyticsAggregator).+ */+ public function supportsResourceScope(): bool+ {+ return Cache::get($this->resourceScopeAbsenceKey()) !== true;+ }++ /**+ * Exact overview of one resource, or null when Sentinel has no resource routes. A failed+ * probe is remembered (see RESOURCE_SCOPE_ABSENCE_TTL), so later calls return null at once.+ */+ public function tryResourceOverview(string $resourceUuid, string $from, string $to): ?TrafficOverviewData+ {+ $url = $this->overviewUrl($resourceUuid, $from, $to, self::SCOPE_RESOURCE);+ if (! $this->supportsResourceScope()) {+ return null;}- return collect($rows)->map(fn ($r) => TrafficSeriesBucketData::fromSentinel($r));+ $overview = $this->genuineOverview($url);+ if ($overview === null) {+ $this->markResourceScopeAbsent();++ return null;+ }++ return TrafficOverviewData::fromSentinel($overview);+ }++ /**+ * Warm every resource endpoint in one exec with the resource dashboard bundle. When the+ * bundle is unavailable, batch the individual resource endpoints instead. Returns false+ * (and remembers it) when Sentinel has no resource routes; the caller then uses the+ * per-key path with prefetchResource().+ *+ * @param array<int, string> $dimensions+ */+ public function prefetchResourceScope(string $resourceUuid, string $from, string $to, array $dimensions, string $range, int $pathLimit = 50, int $breakdownLimit = 50): bool+ {+ $this->assertSafeKey($resourceUuid);+ if (! $this->supportsResourceScope()) {+ return false;+ }++ $bundle = $this->fetchBundle($this->dashboardUrl($resourceUuid, $from, $to, $range, $pathLimit, $breakdownLimit, 0, self::SCOPE_RESOURCE));+ if ($bundle !== null) {+ $this->seedFromDashboard($resourceUuid, $from, $to, $range, $dimensions, $pathLimit, $breakdownLimit, $bundle, self::SCOPE_RESOURCE);++ return true;+ }++ $overviewUrl = $this->overviewUrl($resourceUuid, $from, $to, self::SCOPE_RESOURCE);+ $this->warm([+ ...$this->endpointUrls($resourceUuid, $from, $to, $dimensions, $range, $pathLimit, $breakdownLimit, self::SCOPE_RESOURCE),+ $this->attributionUrl(),+ ]);++ // After a real batch, an uncached overview means the route is absent: no second probe.+ $supported = (! $this->usesBatchableTransport() || Cache::has($this->cacheKey($overviewUrl)))+ && $this->genuineOverview($overviewUrl) !== null;++ if (! $supported) {+ $this->markResourceScopeAbsent();+ }++ return $supported;}public function apps(): array@@ -298,21 +399,90 @@ class SentinelTrafficClientreturn null;}- try {- $decoded = json_decode($this->raw($this->dashboardUrl($appKey, $from, $to, $range, $pathLimit, $breakdownLimit, $appsLimit)), true);- } catch (\Throwable) {+ $bundle = $this->fetchBundle($this->dashboardUrl($appKey, $from, $to, $range, $pathLimit, $breakdownLimit, $appsLimit));+ if ($bundle === null) {Cache::put($absenceKey, true, 60);+ }+ return $bundle;+ }++ /**+ * Fetch one dashboard bundle, or null when the route is absent or the response is not a+ * real bundle (no `overview` member).+ *+ * @return array<string, mixed>|null+ */+ private function fetchBundle(string $url): ?array+ {+ try {+ $decoded = json_decode($this->raw($url), true);+ } catch (\Throwable) {return null;}- if (! is_array($decoded) || ! array_key_exists('overview', $decoded)) {- Cache::put($absenceKey, true, 60);+ return is_array($decoded) && array_key_exists('overview', $decoded) ? $decoded : null;+ }+ /**+ * The decoded overview at $url, or null when the route is absent or the body is not a+ * real overview. Sentinel always sends `requests`, also for an empty range, so a stub+ * (`{}`) does not count as support.+ *+ * @return array<string, mixed>|null+ */+ private function genuineOverview(string $url): ?array+ {+ try {+ $decoded = json_decode($this->raw($url), true);+ } catch (\Throwable) {return null;}- return $decoded;+ return is_array($decoded) && array_key_exists('requests', $decoded) ? $decoded : null;+ }++ private function markResourceScopeAbsent(): void+ {+ Cache::put($this->resourceScopeAbsenceKey(), true, self::RESOURCE_SCOPE_ABSENCE_TTL);+ }++ private function resourceScopeAbsenceKey(): string+ {+ return 'traffic:resource-scope-absent:'.$this->server->uuid;+ }++ private function fetchOverview(string $url): TrafficOverviewData+ {+ return TrafficOverviewData::fromSentinel(json_decode($this->raw($url), true) ?? []);+ }++ private function fetchPaths(string $url): Collection+ {+ $rows = json_decode($this->raw($url), true) ?? [];++ return collect($rows)->map(fn ($r) => TrafficPathData::fromSentinel($r));+ }++ private function fetchBreakdown(string $url): Collection+ {+ $rows = json_decode($this->raw($url), true) ?? [];++ return collect($rows)->map(fn ($r) => TrafficBreakdownData::fromSentinel($r));+ }++ /**+ * @return Collection<int, TrafficSeriesBucketData>+ */+ private function fetchSeries(string $url): Collection+ {+ $rows = json_decode($this->raw($url), true);++ if (! is_array($rows) || $rows === []) {+ return collect();+ }++ return collect($rows)->map(fn ($r) => TrafficSeriesBucketData::fromSentinel($r));}/**@@ -323,18 +493,18 @@ class SentinelTrafficClient* @param array<int, string> $dimensions* @param array<string, mixed> $bundle*/- private function seedFromDashboard(?string $appKey, string $from, string $to, string $range, array $dimensions, int $pathLimit, int $breakdownLimit, array $bundle): void+ private function seedFromDashboard(?string $appKey, string $from, string $to, string $range, array $dimensions, int $pathLimit, int $breakdownLimit, array $bundle, string $scope = self::SCOPE_APP): void{$put = fn (string $url, $member) => Cache::put($this->cacheKey($url), json_encode($member), 60);- $put($this->overviewUrl($appKey, $from, $to), $bundle['overview'] ?? []);- $put($this->pathsUrl($appKey, $from, $to, $pathLimit), $bundle['paths'] ?? []);- $put($this->seriesUrl($appKey, $range), $bundle['series'] ?? []);+ $put($this->overviewUrl($appKey, $from, $to, $scope), $bundle['overview'] ?? []);+ $put($this->pathsUrl($appKey, $from, $to, $pathLimit, $scope), $bundle['paths'] ?? []);+ $put($this->seriesUrl($appKey, $range, $scope), $bundle['series'] ?? []);$put($this->attributionUrl(), ['attribution' => $bundle['attribution'] ?? null]);$breakdowns = $bundle['breakdowns'] ?? [];foreach ($dimensions as $dimension) {- $put($this->breakdownUrl($appKey, $dimension, $from, $to, $breakdownLimit), $breakdowns[$dimension] ?? []);+ $put($this->breakdownUrl($appKey, $dimension, $from, $to, $breakdownLimit, $scope), $breakdowns[$dimension] ?? []);}foreach ($bundle['apps'] ?? [] as $app) {@@ -369,51 +539,51 @@ class SentinelTrafficClient* @param array<int, string> $dimensions* @return array<int, string>*/- private function endpointUrls(?string $appKey, string $from, string $to, array $dimensions, string $range, int $pathLimit, int $breakdownLimit): array+ private function endpointUrls(?string $appKey, string $from, string $to, array $dimensions, string $range, int $pathLimit, int $breakdownLimit, string $scope = self::SCOPE_APP): array{$urls = [- $this->overviewUrl($appKey, $from, $to),- $this->pathsUrl($appKey, $from, $to, $pathLimit),- $this->seriesUrl($appKey, $range),+ $this->overviewUrl($appKey, $from, $to, $scope),+ $this->pathsUrl($appKey, $from, $to, $pathLimit, $scope),+ $this->seriesUrl($appKey, $range, $scope),];foreach ($dimensions as $dimension) {- $urls[] = $this->breakdownUrl($appKey, $dimension, $from, $to, $breakdownLimit);+ $urls[] = $this->breakdownUrl($appKey, $dimension, $from, $to, $breakdownLimit, $scope);}return $urls;}- private function overviewUrl(?string $appKey, string $from, string $to): string+ private function overviewUrl(?string $appKey, string $from, string $to, string $scope = self::SCOPE_APP): string{- $path = $this->appScopedPath($appKey, 'overview');+ $path = $this->appScopedPath($appKey, 'overview', $scope);return $this->url($path, ['from' => $from, 'to' => $to]);}- private function pathsUrl(?string $appKey, string $from, string $to, int $limit): string+ private function pathsUrl(?string $appKey, string $from, string $to, int $limit, string $scope = self::SCOPE_APP): string{- $path = $this->appScopedPath($appKey, 'paths');+ $path = $this->appScopedPath($appKey, 'paths', $scope);return $this->url($path, ['from' => $from, 'to' => $to, 'limit' => (int) $limit]);}- private function breakdownUrl(?string $appKey, string $dimension, string $from, string $to, int $limit): string+ private function breakdownUrl(?string $appKey, string $dimension, string $from, string $to, int $limit, string $scope = self::SCOPE_APP): string{$this->assertSafeDimension($dimension);- $path = $this->appScopedPath($appKey, "breakdown/{$dimension}");+ $path = $this->appScopedPath($appKey, "breakdown/{$dimension}", $scope);return $this->url($path, ['from' => $from, 'to' => $to, 'limit' => (int) $limit]);}- private function seriesUrl(?string $appKey, string $range): string+ private function seriesUrl(?string $appKey, string $range, string $scope = self::SCOPE_APP): string{$range = in_array($range, ['24h', '7d', '30d'], true) ? $range : '24h';- $path = $this->appScopedPath($appKey, 'series');+ $path = $this->appScopedPath($appKey, 'series', $scope);return $this->url($path, ['range' => $range]);}- private function dashboardUrl(?string $appKey, string $from, string $to, string $range, int $pathLimit, int $breakdownLimit, int $appsLimit): string+ private function dashboardUrl(?string $appKey, string $from, string $to, string $range, int $pathLimit, int $breakdownLimit, int $appsLimit, string $scope = self::SCOPE_APP): string{$range = in_array($range, ['24h', '7d', '30d'], true) ? $range : '24h';$query = [@@ -429,9 +599,8 @@ class SentinelTrafficClientreturn $this->url('/traffic/dashboard', $query);}- $this->assertSafeKey($appKey);- return $this->url("/app/{$appKey}/traffic/dashboard", $query);+ return $this->url($this->appScopedPath($appKey, 'dashboard', $scope), $query);}private function appsUrl(): string@@ -445,16 +614,17 @@ class SentinelTrafficClient}/**- * Build a traffic path, optionally scoped to a single (validated) app key.+ * Build a traffic path, optionally scoped to a single (validated) app key, or with+ * SCOPE_RESOURCE to a resource uuid and all of its `{uuid}-*` keys.*/- private function appScopedPath(?string $appKey, string $suffix): string+ private function appScopedPath(?string $appKey, string $suffix, string $scope = self::SCOPE_APP): string{if ($appKey === null) {return "/traffic/{$suffix}";}$this->assertSafeKey($appKey);- return "/app/{$appKey}/traffic/{$suffix}";+ return "/{$scope}/{$appKey}/traffic/{$suffix}";}/**diff --git a/app/Services/TrafficAnalyticsAggregator.php b/app/Services/TrafficAnalyticsAggregator.phpindex 8ff50dc0fa..bc50a41e57 100644--- a/app/Services/TrafficAnalyticsAggregator.php+++ b/app/Services/TrafficAnalyticsAggregator.php@@ -8,6 +8,8 @@ use App\Data\Traffic\TrafficOverviewData;* Merges Sentinel traffic data from several sources (servers, or the several app keys of* one resource) into one view. Counters are summed; latency takes the worst value and* uniques are summed, so both are flagged approximate once more than one source is merged.+ * A resource on a Sentinel with resource routes is one source: Sentinel merges its keys+ * exactly, so one server stays exact.*/class TrafficAnalyticsAggregator{@@ -73,17 +75,47 @@ class TrafficAnalyticsAggregator*/public function collect(SentinelTrafficClient $client, ?string $appKey, string $from, string $to, string $range, callable $domainForKey, int $limit = 50): void{- $this->addOverview($client->overview($appKey, $from, $to));- $this->addPaths($client->paths($appKey, $from, $to, $limit), $appKey, $domainForKey);+ $this->collectScope($client, $appKey, false, $from, $to, $range, $domainForKey, $limit);+ }++ /**+ * Fetch every shape for one resource on one server and merge it in. Uses Sentinel's+ * resource scope when the server has it (one exact source). Otherwise every key of the+ * resource is fetched and merged as its own source, as before.+ *+ * @param callable(string): ?string $domainForKey resolves a path row's app key to its domain+ */+ public function collectResource(SentinelTrafficClient $client, string $resourceUuid, string $from, string $to, string $range, callable $domainForKey, int $limit = 50): void+ {+ if ($client->prefetchResourceScope($resourceUuid, $from, $to, $this->dimensions, $range, $limit, $limit)) {+ $this->collectScope($client, $resourceUuid, true, $from, $to, $range, $domainForKey, $limit);++ return;+ }++ foreach ($client->prefetchResource($resourceUuid, $from, $to, $this->dimensions, $range, $limit, $limit) as $key) {+ $this->collect($client, $key, $from, $to, $range, $domainForKey, $limit);+ }+ }++ /**+ * @param callable(string): ?string $domainForKey+ */+ private function collectScope(SentinelTrafficClient $client, ?string $key, bool $resourceScope, string $from, string $to, string $range, callable $domainForKey, int $limit): void+ {+ $this->addOverview($resourceScope ? $client->resourceOverview($key, $from, $to) : $client->overview($key, $from, $to));+ $this->addPaths($resourceScope ? $client->resourcePaths($key, $from, $to, $limit) : $client->paths($key, $from, $to, $limit), $key, $domainForKey);foreach ($this->dimensions as $dimension) {- $this->addBreakdown($dimension, $client->breakdown($appKey, $dimension, $from, $to, $limit));+ $this->addBreakdown($dimension, $resourceScope+ ? $client->resourceBreakdown($key, $dimension, $from, $to, $limit)+ : $client->breakdown($key, $dimension, $from, $to, $limit));}$this->attribution ??= $client->attribution();try {- $this->addSeries($client->series($appKey, $range));+ $this->addSeries($resourceScope ? $client->resourceSeries($key, $range) : $client->series($key, $range));} catch (\Throwable) {// Leave this source out of the series; the donut fallback covers it.}diff --git a/tests/Feature/TrafficAnalytics/ResourceScopeTrafficTest.php b/tests/Feature/TrafficAnalytics/ResourceScopeTrafficTest.phpnew file mode 100644index 0000000000..36ef965c08--- /dev/null+++ b/tests/Feature/TrafficAnalytics/ResourceScopeTrafficTest.php@@ -0,0 +1,457 @@+<?php++use App\Livewire\Analytics as GlobalAnalytics;+use App\Livewire\Project\Application\Analytics as ApplicationAnalytics;+use App\Livewire\Project\Application\TrafficOverview;+use App\Livewire\Project\Service\Analytics as ServiceAnalytics;+use App\Models\Application;+use App\Models\Environment;+use App\Models\PrivateKey;+use App\Models\Project;+use App\Models\Server;+use App\Models\Service;+use App\Models\ServiceApplication;+use App\Models\StandaloneDocker;+use App\Models\Team;+use App\Models\User;+use App\Services\SentinelTrafficClient;+use App\Services\TrafficAnalyticsAggregator;+use Illuminate\Foundation\Testing\RefreshDatabase;+use Illuminate\Support\Facades\Cache;+use Livewire\Livewire;++uses(RefreshDatabase::class);++/**+ * Serves canned bodies by the first needle contained in the url (insertion order) and logs+ * every requested url across all instances, so a test can prove which routes were queried.+ */+class FakeResourceScopeTrafficClient extends SentinelTrafficClient+{+ /** @var array<int, string> */+ public static array $requested = [];++ public array $responses = [];++ protected function raw(string $url): string+ {+ self::$requested[] = $url;++ foreach ($this->responses as $needle => $response) {+ if (str_contains($url, $needle)) {+ if ($response instanceof Throwable) {+ throw $response;+ }++ return $response;+ }+ }++ return '{}';+ }+}++function resourceScopeOverview(int $requests, int $uniques, float $p95 = 20.0): array+{+ return [+ 'requests' => $requests,+ 'bytes_in' => $requests * 10,+ 'bytes_out' => $requests * 100,+ 'status' => ['s2xx' => $requests, 's3xx' => 0, 's4xx' => 0, 's5xx' => 0],+ 'latency' => ['p50' => 5.0, 'p95' => $p95, 'p99' => 50.0],+ 'unique_visitors' => $uniques,+ ];+}++/**+ * Sentinel answers an absent route with 404 and an empty body; raw() then throws.+ */+function resourceRouteAbsent(): RuntimeException+{+ return new RuntimeException('Traffic analytics returned an invalid response.');+}++function bindResourceScopeFake(array $responses): void+{+ app()->bind(SentinelTrafficClient::class, function ($app, $params) use ($responses) {+ $client = new FakeResourceScopeTrafficClient($params['server']);+ $client->responses = $responses;++ return $client;+ });+}++/**+ * @return array<int, string>+ */+function requestedResourceScopeUrls(string $needle): array+{+ return array_values(array_filter(FakeResourceScopeTrafficClient::$requested, fn (string $url) => str_contains($url, $needle)));+}++/**+ * Canned responses for a Sentinel with the resource routes: the resource bundle and the+ * individual resource endpoints. Every per-key route throws, so a per-key query fails the test.+ */+function resourceScopeResponses(string $uuid, array $overview, array $paths = []): array+{+ return [+ "/resource/{$uuid}/traffic/dashboard" => json_encode([+ 'overview' => $overview,+ 'paths' => $paths,+ 'breakdowns' => ['country' => [['value' => 'US', 'requests' => $overview['requests']]]],+ 'series' => [],+ 'attribution' => null,+ ]),+ "/resource/{$uuid}/traffic/overview" => json_encode($overview),+ "/resource/{$uuid}/traffic/paths" => json_encode($paths),+ "/resource/{$uuid}/traffic/breakdown/country" => json_encode([['value' => 'US', 'requests' => $overview['requests']]]),+ "/resource/{$uuid}/traffic/series" => json_encode([['bucket' => 1000, 's2xx' => $overview['requests'], 'unique_visitors' => $overview['unique_visitors']]]),+ '/app/' => new RuntimeException('per-key route must not be queried when the resource scope exists'),+ '/traffic/apps' => new RuntimeException('the key list must not be queried when the resource scope exists'),+ ];+}++beforeEach(function () {+ config()->set('app.maintenance.store', 'array');+ Cache::flush();+ Server::flushIdentityMap();+ FakeResourceScopeTrafficClient::$requested = [];++ $this->team = Team::factory()->create();+ $this->user = User::factory()->create();+ $this->team->members()->attach($this->user->id, ['role' => 'owner']);+ $this->actingAs($this->user);+ session(['currentTeam' => $this->team]);++ $this->privateKey = PrivateKey::factory()->create(['team_id' => $this->team->id]);+ $this->server = Server::factory()->create([+ 'team_id' => $this->team->id,+ 'private_key_id' => $this->privateKey->id,+ ]);+ $this->server->settings->is_traffic_analytics_enabled = true;+ $this->server->settings->save();+ $this->destination = StandaloneDocker::where('server_id', $this->server->id)->first()+ ?? StandaloneDocker::factory()->create(['server_id' => $this->server->id, 'network' => 'coolify-test']);++ $this->project = Project::factory()->create(['team_id' => $this->team->id, 'name' => 'Storefront']);+ $this->environment = Environment::factory()->create(['project_id' => $this->project->id]);++ $this->application = Application::factory()->create([+ 'name' => 'Compose Shop',+ 'build_pack' => 'dockercompose',+ 'fqdn' => null,+ 'docker_compose_domains' => json_encode([+ 'api' => ['domain' => 'https://api.shop.test'],+ 'web' => ['domain' => 'https://www.shop.test'],+ ]),+ 'environment_id' => $this->environment->id,+ 'destination_id' => $this->destination->id,+ 'destination_type' => StandaloneDocker::class,+ ]);+ $this->apiKey = $this->application->uuid.'-'.traefikSafeServiceNameSegment('api');+ $this->webKey = $this->application->uuid.'-'.traefikSafeServiceNameSegment('web');+});++/**+ * Canned responses for an older Sentinel: resource routes are absent, per-key routes answer.+ */+function perKeyFallbackResponses(string $uuid, string $apiKey, string $webKey): array+{+ return [+ '/resource/' => resourceRouteAbsent(),+ '/traffic/apps' => json_encode([$apiKey, $webKey]),+ "/app/{$apiKey}/traffic/overview" => json_encode(resourceScopeOverview(100, 10, 20.0)),+ "/app/{$webKey}/traffic/overview" => json_encode(resourceScopeOverview(50, 8, 40.0)),+ "/app/{$apiKey}/traffic/paths" => json_encode([['path' => '/v1/orders', 'app' => $apiKey, 'requests' => 100]]),+ "/app/{$webKey}/traffic/paths" => json_encode([['path' => '/checkout', 'app' => $webKey, 'requests' => 50]]),+ "/app/{$uuid}/traffic" => new RuntimeException('bare uuid must not be queried when compose keys exist'),+ ];+}++it('builds the url of every resource endpoint', function () {+ $client = new FakeResourceScopeTrafficClient($this->server);+ $client->responses = ['/overview' => json_encode(resourceScopeOverview(1, 1)), '' => '[]'];++ $client->resourceOverview('res-uuid', '2026-08-01T00:00:00Z', '2026-08-02T00:00:00Z');+ $client->resourcePaths('res-uuid', 'F', 'T', 25);+ $client->resourceBreakdown('res-uuid', 'country', 'F', 'T', 10);+ $client->resourceSeries('res-uuid', '7d');+ $client->prefetchResourceScope('res-uuid', 'F', 'T', [], '30d', 25, 10);++ $urls = FakeResourceScopeTrafficClient::$requested;+ expect($urls[0])->toBe('http://localhost:8888/api/resource/res-uuid/traffic/overview?from=2026-08-01T00:00:00Z&to=2026-08-02T00:00:00Z')+ ->and($urls[1])->toBe('http://localhost:8888/api/resource/res-uuid/traffic/paths?from=F&to=T&limit=25')+ ->and($urls[2])->toBe('http://localhost:8888/api/resource/res-uuid/traffic/breakdown/country?from=F&to=T&limit=10')+ ->and($urls[3])->toBe('http://localhost:8888/api/resource/res-uuid/traffic/series?range=7d')+ ->and($urls[4])->toBe('http://localhost:8888/api/resource/res-uuid/traffic/dashboard?from=F&to=T&range=30d&paths_limit=25&breakdown_limit=10');+});++it('rejects an unsafe resource uuid or dimension before any request', function () {+ $client = new FakeResourceScopeTrafficClient($this->server);++ expect(fn () => $client->resourceOverview("x'; touch /tmp/pwned; '", 'F', 'T'))->toThrow(InvalidArgumentException::class)+ ->and(fn () => $client->prefetchResourceScope('a b', 'F', 'T', [], '24h'))->toThrow(InvalidArgumentException::class)+ ->and(fn () => $client->tryResourceOverview('a/b', 'F', 'T'))->toThrow(InvalidArgumentException::class)+ ->and(fn () => $client->resourceBreakdown('res', 'not-a-dimension', 'F', 'T'))->toThrow(InvalidArgumentException::class);+ expect(FakeResourceScopeTrafficClient::$requested)->toBeEmpty();+});++it('serves every resource endpoint from one resource dashboard exec', function () {+ $client = new class($this->server) extends SentinelTrafficClient+ {+ public array $fetched = [];++ protected function remoteFetch(string $url): string+ {+ $this->fetched[] = $url;+ if (str_contains($url, '/resource/res/traffic/dashboard')) {+ return json_encode([+ 'overview' => resourceScopeOverview(9, 4),+ 'paths' => [['path' => '/', 'app' => 'res-web', 'requests' => 9]],+ 'breakdowns' => ['country' => [['value' => 'US', 'requests' => 9]]],+ 'series' => [['bucket' => 1000, 's2xx' => 9]],+ 'attribution' => 'MaxMind',+ ]);+ }+ throw new RuntimeException("unexpected fetch: {$url}");+ }++ protected function batchRemoteFetch(array $urls): string+ {+ throw new RuntimeException('no batch expected');+ }+ };++ expect($client->prefetchResourceScope('res', 'F', 'T', ['country'], '24h'))->toBeTrue()+ ->and($client->resourceOverview('res', 'F', 'T')->uniqueVisitors)->toBe(4)+ ->and($client->resourcePaths('res', 'F', 'T')->first()->toArray()['app'])->toBe('res-web')+ ->and($client->resourceBreakdown('res', 'country', 'F', 'T'))->toHaveCount(1)+ ->and($client->resourceSeries('res', '24h'))->toHaveCount(1)+ ->and($client->attribution())->toBe('MaxMind')+ ->and($client->fetched)->toHaveCount(1);+});++it('falls back to one batch of individual resource endpoints when the resource dashboard is absent', function () {+ $client = new class($this->server) extends SentinelTrafficClient+ {+ public int $batchCalls = 0;++ protected function remoteFetch(string $url): string+ {+ if (str_contains($url, '/traffic/dashboard')) {+ return '';+ }+ throw new RuntimeException("unexpected fetch: {$url}");+ }++ protected function batchRemoteFetch(array $urls): string+ {+ $this->batchCalls++;++ return implode("\x1e", array_map(fn ($url) => match (true) {+ str_contains($url, '/resource/res/traffic/overview') => json_encode(resourceScopeOverview(3, 2)),+ str_contains($url, '/attribution') => '{"attribution":"demo"}',+ str_contains($url, '/resource/res/traffic/') => '[]',+ default => throw new RuntimeException("unexpected batch url: {$url}"),+ }, $urls))."\x1e";+ }+ };++ expect($client->prefetchResourceScope('res', 'F', 'T', ['country'], '24h'))->toBeTrue()+ ->and($client->batchCalls)->toBe(1)+ ->and($client->resourceOverview('res', 'F', 'T')->requests)->toBe(3)+ ->and($client->attribution())->toBe('demo');+ $client->resourceBreakdown('res', 'country', 'F', 'T');+});++it('remembers absent resource routes and does not probe them again within the ttl', function () {+ $client = new class($this->server) extends SentinelTrafficClient+ {+ public int $remoteFetches = 0;++ public int $batchCalls = 0;++ protected function remoteFetch(string $url): string+ {+ $this->remoteFetches++;++ return '';+ }++ protected function batchRemoteFetch(array $urls): string+ {+ $this->batchCalls++;++ return implode("\x1e", array_fill(0, count($urls), ''))."\x1e";+ }+ };++ expect($client->prefetchResourceScope('res', 'F', 'T', ['country'], '24h'))->toBeFalse()+ ->and($client->prefetchResourceScope('res', 'F', 'T', ['country'], '24h'))->toBeFalse()+ ->and($client->tryResourceOverview('res', 'F', 'T'))->toBeNull()+ ->and($client->remoteFetches)->toBe(1)+ ->and($client->batchCalls)->toBe(1)+ ->and($client->supportsResourceScope())->toBeFalse();++ $this->travel(SentinelTrafficClient::RESOURCE_SCOPE_ABSENCE_TTL + 1)->seconds();++ expect($client->supportsResourceScope())->toBeTrue();+});++it('queries an application once in the resource scope, with exact uniques and no approximate badges', function () {+ $paths = [+ ['path' => '/v1/orders', 'app' => $this->apiKey, 'requests' => 100],+ ['path' => '/checkout', 'app' => $this->webKey, 'requests' => 50],+ ];+ bindResourceScopeFake(resourceScopeResponses($this->application->uuid, resourceScopeOverview(150, 12, 30.0), $paths));++ $component = loadLazy(Livewire::test(ApplicationAnalytics::class, ['application' => $this->application]))+ ->assertOk()+ ->assertSet('latencyApproximate', false)+ ->assertSet('uniquesApproximate', false)+ ->assertDontSee('double-counted')+ ->assertDontSee('not a true merged percentile');++ $instance = $component->instance();+ $paths = collect($instance->topPaths)->keyBy('path');+ expect($instance->overview['requests'])->toBe(150)+ ->and($instance->overview['uniqueVisitors'])->toBe(12)+ ->and($instance->overview['latencyP95'])->toBe(30.0)+ ->and($paths['/v1/orders']['domain'])->toBe('api.shop.test')+ ->and($paths['/checkout']['domain'])->toBe('www.shop.test')+ ->and(requestedResourceScopeUrls('/resource/'.$this->application->uuid.'/traffic/overview'))->toHaveCount(1)+ ->and(requestedResourceScopeUrls('/app/'))->toBeEmpty()+ ->and(requestedResourceScopeUrls('/traffic/apps'))->toBeEmpty();+});++it('queries a service in the resource scope with no approximate badges', function () {+ $service = Service::factory()->create([+ 'name' => 'Umami',+ 'server_id' => $this->server->id,+ 'destination_id' => $this->destination->id,+ 'destination_type' => $this->destination->getMorphClass(),+ 'environment_id' => $this->environment->id,+ ]);+ foreach (['web' => 'https://app.svc.test', 'admin' => 'https://admin.svc.test'] as $name => $fqdn) {+ ServiceApplication::create(['service_id' => $service->id, 'name' => $name, 'image' => 'nginx:alpine', 'fqdn' => $fqdn]);+ }+ $adminKey = $service->uuid.'-'.traefikSafeServiceNameSegment('admin');+ bindResourceScopeFake(resourceScopeResponses($service->uuid, resourceScopeOverview(320, 7), [+ ['path' => '/login', 'app' => $adminKey, 'requests' => 20],+ ]));++ $component = loadLazy(Livewire::test(ServiceAnalytics::class, ['service' => $service]))+ ->assertOk()+ ->assertSee('admin.svc.test')+ ->assertSet('latencyApproximate', false)+ ->assertSet('uniquesApproximate', false);++ expect($component->instance()->overview['uniqueVisitors'])->toBe(7)+ ->and(requestedResourceScopeUrls('/app/'))->toBeEmpty();+});++it('falls back to the per-key merge with approximate badges when Sentinel lacks the resource routes', function () {+ bindResourceScopeFake(perKeyFallbackResponses($this->application->uuid, $this->apiKey, $this->webKey));++ $component = loadLazy(Livewire::test(ApplicationAnalytics::class, ['application' => $this->application]))+ ->assertOk()+ ->assertSet('latencyApproximate', true)+ ->assertSet('uniquesApproximate', true)+ ->assertSee('double-counted');++ expect($component->instance()->overview['requests'])->toBe(150)+ ->and($component->instance()->overview['uniqueVisitors'])->toBe(18)+ ->and($component->instance()->overview['latencyP95'])->toBe(40.0);++ $probes = count(requestedResourceScopeUrls('/resource/'));+ expect($probes)->toBeGreaterThan(0);++ // The absence is cached: a refresh within the ttl goes straight to the per-key path.+ $component->call('loadData')->assertSet('uniquesApproximate', true);+ loadLazy(Livewire::test(TrafficOverview::class, ['application' => $this->application]))->assertOk();++ expect(requestedResourceScopeUrls('/resource/'))->toHaveCount($probes);+});++it('shows the resource overview in the application traffic card', function () {+ bindResourceScopeFake(resourceScopeResponses($this->application->uuid, resourceScopeOverview(4200, 33)));++ $component = loadLazy(Livewire::test(TrafficOverview::class, ['application' => $this->application]))+ ->assertOk()+ ->assertSee('4,200');++ expect($component->instance()->overview['uniqueVisitors'])->toBe(33)+ ->and(requestedResourceScopeUrls('/resource/'))->toHaveCount(1)+ ->and(requestedResourceScopeUrls('/traffic/dashboard'))->toBeEmpty();+});++it('sums the keys in the application traffic card when Sentinel lacks the resource routes', function () {+ bindResourceScopeFake(perKeyFallbackResponses($this->application->uuid, $this->apiKey, $this->webKey));++ loadLazy(Livewire::test(TrafficOverview::class, ['application' => $this->application]))+ ->assertOk()+ ->assertSee('150');+});++it('uses the resource scope when the global analytics filter selects a resource', function () {+ bindResourceScopeFake([+ ...resourceScopeResponses($this->application->uuid, resourceScopeOverview(150, 12)),+ '/traffic/overview' => json_encode(resourceScopeOverview(999, 99)),+ ]);++ $component = loadLazy(Livewire::withQueryParams(['app' => $this->application->uuid])->test(GlobalAnalytics::class))+ ->assertOk()+ ->assertSet('appUuid', $this->application->uuid)+ ->assertSet('latencyApproximate', false)+ ->assertSet('uniquesApproximate', false);++ expect($component->instance()->overview['requests'])->toBe(150)+ ->and($component->instance()->overview['uniqueVisitors'])->toBe(12)+ ->and(requestedResourceScopeUrls('/app/'))->toBeEmpty()+ ->and(requestedResourceScopeUrls('/traffic/apps'))->toBeEmpty();+});++it('keeps the unfiltered leaderboard on per-key rows without resource queries', function () {+ bindResourceScopeFake([+ '/resource/' => new RuntimeException('the leaderboard must not query the resource scope'),+ '/traffic/apps' => json_encode([$this->apiKey, $this->webKey]),+ "/app/{$this->apiKey}/traffic/overview" => json_encode(resourceScopeOverview(100, 10)),+ "/app/{$this->webKey}/traffic/overview" => json_encode(resourceScopeOverview(50, 8)),+ '/traffic/overview' => json_encode(resourceScopeOverview(150, 15)),+ ]);++ $instance = loadLazy(Livewire::test(GlobalAnalytics::class))->assertOk()->instance();++ expect($instance->topApps[0]['uuid'])->toBe($this->application->uuid)+ ->and($instance->topApps[0]['requests'])->toBe(150)+ ->and($instance->overview['uniqueVisitors'])->toBe(15)+ ->and(requestedResourceScopeUrls('/resource/'))->toBeEmpty();+});++it('keeps a merge of one resource across several servers approximate', function () {+ $otherServer = Server::factory()->create(['team_id' => $this->team->id, 'private_key_id' => $this->privateKey->id]);+ $uuid = $this->application->uuid;++ $first = new FakeResourceScopeTrafficClient($this->server);+ $first->responses = resourceScopeResponses($uuid, resourceScopeOverview(100, 10, 20.0));+ $second = new FakeResourceScopeTrafficClient($otherServer);+ $second->responses = resourceScopeResponses($uuid, resourceScopeOverview(50, 5, 40.0));++ $aggregator = new TrafficAnalyticsAggregator(['country']);+ $aggregator->collectResource($first, $uuid, 'F', 'T', '24h', fn () => null);+ $aggregator->collectResource($second, $uuid, 'F', 'T', '24h', fn () => null);++ $result = $aggregator->overview();+ expect($result['overview']->requests)->toBe(150)+ ->and($result['overview']->uniqueVisitors)->toBe(15)+ ->and($result['latencyApproximate'])->toBeTrue()+ ->and($result['uniquesApproximate'])->toBeTrue()+ ->and(requestedResourceScopeUrls('/app/'))->toBeEmpty();++ // One server in the resource scope is exact.+ $single = new TrafficAnalyticsAggregator(['country']);+ $single->collectResource($first, $uuid, 'F', 'T', '24h', fn () => null);+ expect($single->overview()['latencyApproximate'])->toBeFalse()+ ->and($single->overview()['uniquesApproximate'])->toBeFalse();+});