Merge pull request #12508 from appwrite/realtime-tail-logs

Realtime tail logs
This commit is contained in:
Jake Barnby authored and GitHub committed 2026-06-24 19:14:22 +12:00
commit fdc3e61b9c
10 files changed
+1398 -4

No files matched your search

+2
View File
@@ -153,3 +153,5 @@ _TESTS_OAUTH2_GITHUB_CLIENT_SECRET=
_APP_WORKERS_NUM=1
_APP_WORKER_MAX_COROUTINES=1
_APP_REALTIME_TAIL_RATE=50
+4
View File
@@ -288,6 +288,10 @@ const API_KEY_STANDARD = 'standard';
const API_KEY_EPHEMERAL = 'ephemeral';
const API_KEY_ORGANIZATION = 'organization';
const API_KEY_ACCOUNT = 'account';
// Realtime
const CONSOLE_TAIL_CHANNEL_PREFIX = 'console.tail';
// Usage metrics
const METRIC_TEAMS = 'teams';
const METRIC_USERS = 'users';
+54 -4
View File
@@ -9,6 +9,7 @@ use Appwrite\Messaging\Adapter\Realtime;
use Appwrite\Network\Validator\Origin;
use Appwrite\Presences\State as PresenceState;
use Appwrite\PubSub\Adapter\Pool as PubSubPool;
use Appwrite\Realtime\EventTailRegistry;
use Appwrite\Realtime\Message\Dispatcher as MessageDispatcher;
use Appwrite\Realtime\Message\Handlers\Authentication as AuthenticationHandler;
use Appwrite\Realtime\Message\Handlers\Ping as PingHandler;
@@ -336,6 +337,9 @@ if (!function_exists('checkForProjectUsage')) {
$realtime = getRealtime();
$presenceState = new PresenceState();
$eventTailRegistry = new EventTailRegistry(
rate: (int) System::getEnv('_APP_REALTIME_TAIL_RATE', 50)
);
$messageDispatcher = (new MessageDispatcher())
->addHandler(new PingHandler())
@@ -496,7 +500,7 @@ $server->onStart(function () use ($stats, $containerId, &$statsDocument) {
}
});
$server->onWorkerStart(function (int $workerId) use ($server, $register, $stats, $realtime) {
$server->onWorkerStart(function (int $workerId) use ($server, $register, $stats, $realtime, $eventTailRegistry) {
Console::success('Worker ' . $workerId . ' started successfully');
$telemetry = getTelemetry($workerId);
@@ -525,6 +529,13 @@ $server->onWorkerStart(function (int $workerId) use ($server, $register, $stats,
$attempts = 0;
$start = time();
// Flush coalesced console live-tail buffers to their connections (~150ms).
// Must run per-worker: the registry is mutated by this worker's subscribe handler
// and pub/sub ingest, which are not visible to the master process.
Timer::tick(150, function () use ($server, $eventTailRegistry) {
$eventTailRegistry->flush($server);
});
Timer::tick(5000, function () use ($server, $realtime, $stats) {
/**
* Sending current connections to project channels on the console project every 5 seconds.
@@ -634,7 +645,7 @@ $server->onWorkerStart(function (int $workerId) use ($server, $register, $stats,
Console::error('Pub/sub failed (worker: ' . $workerId . ')');
}
$pubsub->subscribe(['realtime'], function (mixed $redis, string $channel, string $payload) use ($server, $workerId, $stats, $register, $realtime) {
$pubsub->subscribe(['realtime'], function (mixed $redis, string $channel, string $payload) use ($server, $workerId, $stats, $register, $realtime, $eventTailRegistry) {
$event = json_decode($payload, true);
$eventTimestamp = $event['data']['timestamp'] ?? null;
@@ -716,6 +727,11 @@ $server->onWorkerStart(function (int $workerId) use ($server, $register, $stats,
if ($subscriptionDelta !== 0) {
$register->get('telemetry.workerSubscriptionCounter')->add($subscriptionDelta, $register->get('telemetry.workerAttributes'));
}
// Tail entries live outside the subscription tree, so the rebuild
// above doesn't touch them. Drop any whose authorizing team role
// the connection no longer holds (membership revoked / project moved).
$eventTailRegistry->revalidateConnection($connection, $roles);
}
}
}
@@ -797,6 +813,31 @@ $server->onWorkerStart(function (int $workerId) use ($server, $register, $stats,
triggerStats($metrics, $projectId);
}
}
// Console live event tail: runs for EVERY firehose event, regardless of
// whether it had regular subscribers ($total). The firehose is published
// unconditionally, so a project tailed from the console with no other
// realtime clients must still be observed here.
//
// Most events carry the owning project in $event['project']. But some
// project-owned events (schema changes, deployments, rules, migrations,
// project settings) are rerouted by fromPayload() to project='console';
// for those the real project id lives in the `projects.<id>` channel.
// Resolve that so the tail still receives them.
$tailProjectId = $event['project'] ?? '';
if ($tailProjectId === 'console') {
$tailProjectId = '';
foreach (($event['data']['channels'] ?? []) as $channel) {
if (\str_starts_with($channel, 'projects.')) {
$tailProjectId = \substr($channel, \strlen('projects.'));
break;
}
}
}
if ($tailProjectId !== '' && $eventTailRegistry->isTailed($tailProjectId)) {
$eventTailRegistry->ingest($tailProjectId, Realtime::toTailMetadata($event), \microtime(true));
}
});
} catch (Throwable $th) {
@@ -1085,7 +1126,7 @@ $server->onOpen(function (int $connection, SwooleRequest $request) use ($server,
}
});
$server->onMessage(function (int $connection, string $message) use ($container, $server, $realtime, $containerId, $register, $presenceState, $messageDispatcher) {
$server->onMessage(function (int $connection, string $message) use ($container, $server, $realtime, $containerId, $register, $presenceState, $messageDispatcher, $eventTailRegistry) {
$project = null;
$authorization = null;
$projectId = $realtime->connections[$connection]['projectId'] ?? null;
@@ -1206,6 +1247,8 @@ $server->onMessage(function (int $connection, string $message) use ($container,
$messageContainer->set('projectId', fn () => $projectId);
$messageContainer->set('queueForEvents', fn () => getQueueForEvents());
$messageContainer->set('queueForRealtime', fn () => getQueueForRealtime());
$messageContainer->set('eventTailRegistry', fn () => $eventTailRegistry);
$messageContainer->set('dbForConsole', fn () => getConsoleDB());
$responsePayload = $messageDispatcher->dispatch($messageContainer, $message);
@@ -1281,7 +1324,7 @@ $server->onMessage(function (int $connection, string $message) use ($container,
}
});
$server->onClose(function (int $connection) use ($realtime, $stats, $register, $container, $presenceState) {
$server->onClose(function (int $connection) use ($realtime, $stats, $register, $container, $presenceState, $eventTailRegistry) {
$projectId = null;
$userId = null;
$subscriptionsBeforeClose = 0;
@@ -1428,6 +1471,13 @@ $server->onClose(function (int $connection) use ($realtime, $stats, $register, $
Span::current()?->setError($th);
}
try {
$eventTailRegistry->removeConnection($connection);
} catch (\Throwable $th) {
Console::error('Realtime onClose tail cleanup error: ' . $th->getMessage());
Span::current()?->setError($th);
}
Span::add('realtime.success', $success);
if (!empty($projectId)) {
Span::add('project.id', $projectId);
+1
View File
@@ -310,6 +310,7 @@ services:
- _APP_WORKER_PER_CORE
- _APP_OPTIONS_ABUSE
- _APP_OPTIONS_ROUTER_PROTECTION
- _APP_REALTIME_TAIL_RATE
- _APP_OPENSSL_KEY_V1
- _APP_REDIS_HOST
- _APP_REDIS_PORT
@@ -16,6 +16,11 @@ class Realtime extends MessagingAdapter
{
public const SUPPORTED_ACTIONS = ['create', 'update', 'upsert', 'delete'];
// The database family is published under several event prefixes (legacy `databases`
// plus the per-type projections). They share the same `databases.<db>.<collections|tables>.<id>…`
// shape, so the tail normalizes them to `databases` for consistent metadata + filtering.
public const DATABASE_EVENT_PREFIXES = ['databases', 'tablesdb', 'documentsdb', 'vectorsdb'];
// Resources whose channels receive an action-suffixed sibling at publish time.
// The suffix loop in fromPayload() treats any channel whose last OR second-to-last
// segment matches an entry here as a candidate for `.{action}` suffixing.
@@ -500,6 +505,90 @@ class Realtime extends MessagingAdapter
return $receivers;
}
/**
*
* @param array<string,mixed> $event decoded event published to the `realtime` channel
* @return array<string,mixed>
*/
public static function toTailMetadata(array $event): array
{
$events = $event['data']['events'] ?? [];
$name = \is_array($events) ? ($events[0] ?? '') : '';
$parts = $name === '' ? [] : \explode('.', $name);
$count = \count($parts);
$type = $parts[0] ?? null;
// The database family is published under several prefixes (databases/tablesdb/
// documentsdb/vectorsdb). `type` keeps the actual prefix (more informative), but
// scope ids are extracted for all of them so databaseId/collectionId filters work
// across the whole family.
$isDatabaseFamily = \in_array($type, self::DATABASE_EVENT_PREFIXES, true);
$action = null;
if ($count >= 1 && \in_array($parts[$count - 1], self::SUPPORTED_ACTIONS, true)) {
$action = $parts[$count - 1];
} elseif ($count >= 2 && \in_array($parts[$count - 2], self::SUPPORTED_ACTIONS, true)) {
$action = $parts[$count - 2];
}
$payload = $event['data']['payload'] ?? [];
if (!\is_array($payload)) {
$payload = [];
}
$metadata = [
'event' => $name,
'type' => $type,
'action' => $action,
'userId' => $event['userId'] ?? null,
'timestamp' => $event['data']['timestamp'] ?? null,
'resourceId' => $payload['$id'] ?? null,
];
// Attach only the scope ids that belong to this resource type. Derived from the
// (concrete) event name rather than the payload: for a top-level resource event
// (e.g. `teams.T.create`) the payload's id lives at $id, not at a teamId field,
// so a payload lookup would drop the scope and silently break filters. The event
// name encodes the id at every level — parts[1] is the top-level resource id and
// parts[3] the collection/table id.
$scope = [];
if ($isDatabaseFamily) {
if (isset($parts[1])) {
$scope['databaseId'] = $parts[1];
}
if (isset($parts[2], $parts[3]) && \in_array($parts[2], ['collections', 'tables'], true)) {
$scope['collectionId'] = $parts[3];
}
} else {
switch ($type) {
case 'buckets':
if (isset($parts[1])) {
$scope['bucketId'] = $parts[1];
}
break;
case 'functions':
if (isset($parts[1])) {
$scope['functionId'] = $parts[1];
}
break;
case 'teams':
if (isset($parts[1])) {
$scope['teamId'] = $parts[1];
}
break;
}
}
foreach ($scope as $key => $value) {
// Skip wildcard/empty segments (defensive: events[0] is concrete, but guard anyway).
if ($value !== '' && $value !== '*') {
$metadata[$key] = $value;
}
}
return $metadata;
}
/**
* Converts the channels from the Query Params into an array.
* Also renames the account channel to account.USER_ID, rewrites action-suffixed
+247
View File
@@ -0,0 +1,247 @@
<?php
namespace Appwrite\Realtime;
use Appwrite\Utopia\Database\RuntimeQuery;
use Utopia\WebSocket\Server;
/**
* Per-worker token-bucket + buffers for console event-tail subscriptions.
*
* Each tail of a single project is one entry, keyed by (connId, subId, projectId).
*/
class EventTailRegistry
{
/** @var array<int, array<string, array<string, array{
* role:string,
* filters:array<string,mixed>,
* tokens:float,
* lastRefill:float,
* dropped:int,
* delivered:int,
* buffer:array<int,array<string,mixed>>
* }>>> connId => subId => projectId => state */
private array $entries = [];
/** @var array<string, array<int, array<string,true>>> projectId => connId => set of subIds */
private array $projectIndex = [];
private int $rate;
private int $batchMax;
/**
* @param int $rate tokens per second per subscription
* @param int $batchMax max frames per flushed websocket frame (kept under setPackageMaxLength)
*/
public function __construct(int $rate = 50, int $batchMax = 200)
{
$this->rate = \max(1, $rate);
$this->batchMax = \max(1, $batchMax);
}
/**
* Build the tail channel string for a project.
*/
public static function channel(string $projectId): string
{
return CONSOLE_TAIL_CHANNEL_PREFIX . '.' . $projectId;
}
/**
* Extract the projectId from a `console.tail.<projectId>` channel, or null if the
* channel isn't a tail channel.
*/
public static function projectFromChannel(string $channel): ?string
{
$prefix = CONSOLE_TAIL_CHANNEL_PREFIX . '.';
if (!\str_starts_with($channel, $prefix)) {
return null;
}
$projectId = \substr($channel, \strlen($prefix));
return $projectId === '' ? null : $projectId;
}
/**
* Register a tail of one project under (connId, subId). Additive, mirroring the
* realtime adapter's subscribe(): adding a new channel never drops channels already
* associated with the subscription id. Re-adding the SAME (connId, subId, projectId)
* overwrites in place with fresh state — that's how a reused subscription id updates
* its filter without leaving a stale entry behind. Entries are dropped only by
* remove()/removeConnection() (i.e. unsubscribe or disconnect), matching the tree.
*
* @param array<string,mixed> $filters result of RuntimeQuery::compile()
* @param string $role the team role this tail was authorized with
*/
public function add(int $connId, string $subId, string $projectId, array $filters, float $now, string $role = ''): void
{
$this->entries[$connId][$subId][$projectId] = [
'role' => $role,
'filters' => $filters,
'tokens' => (float) $this->rate,
'lastRefill' => $now,
'dropped' => 0,
'delivered' => 0,
'buffer' => [],
];
$this->projectIndex[$projectId][$connId][$subId] = true;
}
/**
* Remove every entry for a (connId, subId) — covers a subscription that tailed
* multiple projects. No-op for unknown subscriptions.
*/
public function remove(int $connId, string $subId): void
{
foreach (\array_keys($this->entries[$connId][$subId] ?? []) as $projectId) {
$this->detachEntry($connId, $subId, (string) $projectId);
}
}
public function removeConnection(int $connId): void
{
foreach (\array_keys($this->entries[$connId] ?? []) as $subId) {
$this->remove($connId, (string) $subId);
}
}
/**
* Drop any tail whose authorizing team role the connection no longer holds. Called
* from the permissions-changed path (which already recomputes a connection's roles
* and rebuilds its tree) so a membership revocation or project transfer stops the
* tail mid-connection instead of streaming until disconnect.
*
* @param array<int,string> $roles the connection's current roles
*/
public function revalidateConnection(int $connId, array $roles): void
{
foreach (($this->entries[$connId] ?? []) as $subId => $byProject) {
foreach ($byProject as $projectId => $entry) {
$role = $entry['role'];
if ($role !== '' && !\in_array($role, $roles, true)) {
$this->detachEntry($connId, (string) $subId, (string) $projectId);
}
}
}
}
private function detachEntry(int $connId, string $subId, string $projectId): void
{
unset($this->projectIndex[$projectId][$connId][$subId]);
if (empty($this->projectIndex[$projectId][$connId])) {
unset($this->projectIndex[$projectId][$connId]);
}
if (empty($this->projectIndex[$projectId])) {
unset($this->projectIndex[$projectId]);
}
unset($this->entries[$connId][$subId][$projectId]);
if (empty($this->entries[$connId][$subId])) {
unset($this->entries[$connId][$subId]);
}
if (empty($this->entries[$connId])) {
unset($this->entries[$connId]);
}
}
/**
* O(1) gate for the hot path: does THIS worker hold any tail for the project?
*/
public function isTailed(string $projectId): bool
{
return !empty($this->projectIndex[$projectId]);
}
/**
* For one decoded firehose event: filter FIRST, then sample into each matching
* entry's buffer. The sampling budget is therefore spent only on events that pass
* the filter.
*
* @param array<string,mixed> $payload compact metadata from Realtime::toTailMetadata()
*/
public function ingest(string $projectId, array $payload, float $now): void
{
foreach (($this->projectIndex[$projectId] ?? []) as $connId => $subs) {
foreach (\array_keys($subs) as $subId) {
$entry = &$this->entries[$connId][$subId][$projectId];
// 1) FILTER FIRST — reuse RuntimeQuery against the compact frame
if (RuntimeQuery::filter($entry['filters'], $payload) === null) {
unset($entry);
continue;
}
// 2) THEN SAMPLE — lazy token-bucket refill + consume.
// tokens is a fractional value that refills with elapsed time, capped at rate.
$elapsed = \max(0.0, $now - $entry['lastRefill']);
$entry['tokens'] = \min((float) $this->rate, $entry['tokens'] + $elapsed * $this->rate);
$entry['lastRefill'] = $now;
if ($entry['tokens'] >= 1.0) {
$entry['tokens'] -= 1.0;
$entry['buffer'][] = $payload;
$entry['delivered']++;
} else {
$entry['dropped']++;
}
unset($entry);
}
}
}
/**
* Flush all non-empty buffers as one (or more) batched websocket frame(s) per
* entry, plus a counter frame whenever events were dropped. Call from a Timer::tick
* inside onWorkerStart.
*/
public function flush(Server $server): void
{
foreach ($this->entries as $connId => $bySub) {
foreach ($bySub as $subId => $byProject) {
foreach (\array_keys($byProject) as $projectId) {
$entry = &$this->entries[$connId][$subId][$projectId];
$channel = self::channel((string) $projectId);
if (!empty($entry['buffer'])) {
// Chunk so a single frame stays under the websocket package max length.
foreach (\array_chunk($entry['buffer'], $this->batchMax) as $chunk) {
$server->send([$connId], (string) \json_encode([
'type' => 'event',
'data' => [
'channels' => [$channel],
'events' => ['console.tail'],
'subscriptions' => [(string) $subId],
'payload' => $chunk,
],
]));
}
$entry['buffer'] = [];
}
// Counter frame — emit the true rate vs dropped count when sampling kicked in.
if ($entry['dropped'] > 0) {
$server->send([$connId], (string) \json_encode([
'type' => 'event',
'data' => [
'channels' => [$channel],
'events' => ['console.tail.stats'],
'subscriptions' => [(string) $subId],
'payload' => [
'$type' => 'tail.stats',
'delivered' => $entry['delivered'],
'dropped' => $entry['dropped'],
],
],
]));
}
// Reset counters every flush window (~150ms).
$entry['delivered'] = 0;
$entry['dropped'] = 0;
unset($entry);
}
}
}
}
}
@@ -4,8 +4,11 @@ namespace Appwrite\Realtime\Message\Handlers;
use Appwrite\Extend\Exception;
use Appwrite\Messaging\Adapter\Realtime;
use Appwrite\Realtime\EventTailRegistry;
use Appwrite\Realtime\Message\Dispatcher;
use Appwrite\Realtime\Message\Validators\SubscribePayload as SubscribePayloadValidator;
use Appwrite\Utopia\Database\RuntimeQuery;
use Utopia\Database\Database;
use Utopia\Database\Exception\Query as QueryException;
use Utopia\Database\Helpers\ID;
use Utopia\Database\Helpers\Role;
@@ -26,6 +29,8 @@ class Subscribe extends Action
->inject('realtime')
->inject('register')
->inject('projectId')
->inject('eventTailRegistry')
->inject('dbForConsole')
->callback($this->action(...));
}
@@ -39,6 +44,8 @@ class Subscribe extends Action
Realtime $realtime,
Registry $register,
?string $projectId,
EventTailRegistry $eventTailRegistry,
Database $dbForConsole,
): array {
$roles = $realtime->connections[$connectionId]['roles'] ?? [Role::guests()->toString()];
$userId = $realtime->connections[$connectionId]['userId'] ?? '';
@@ -69,6 +76,64 @@ class Subscribe extends Action
];
}
// Console live event tail: authorize every `console.tail.<projectId>` channel
// FIRST — before any subscription state is mutated — so a batch mixing authorized
// and unauthorized tails can't leave partial state behind. Each tail is authorized
// by team membership of the target project's owning team, with ownership resolved
// fresh (projects can be transferred between teams, so a cached teamId could
// authorize the wrong team).
$now = \microtime(true);
$pendingTails = [];
foreach ($parsedPayloads as $parsedPayload) {
$compiled = null;
foreach ($parsedPayload['convertedChannels'] as $channel) {
$targetProjectId = EventTailRegistry::projectFromChannel($channel);
if ($targetProjectId === null) {
continue;
}
// Tail channels are console-only. A normal project websocket (even for a
// team member) must not tail — that would expose compact metadata for
// resources the user could not read through the project API. Only a
// connection to the `console` project may register a tail.
if ($projectId !== 'console') {
throw new Exception(
Exception::REALTIME_POLICY_VIOLATION,
'Console live tail is only available on the console connection.'
);
}
// Resolve ownership fresh (projects can move between teams). Treat any
// lookup failure (missing/invalid project) as a policy violation so the
// connection is closed with 1008, consistent with an unauthorized tail —
// rather than leaking a raw not-found error and staying open.
try {
$project = $dbForConsole->getAuthorization()->skip(
fn () => $dbForConsole->getDocument('projects', $targetProjectId)
);
} catch (\Throwable) {
throw new Exception(
Exception::REALTIME_POLICY_VIOLATION,
'Not authorized to tail project "' . $targetProjectId . '".'
);
}
$teamId = (string) $project->getAttribute('teamId', '');
$requiredRole = Role::team($teamId)->toString();
if ($teamId === '' || !\in_array($requiredRole, $roles, true)) {
throw new Exception(
Exception::REALTIME_POLICY_VIOLATION,
'Not authorized to tail project "' . $targetProjectId . '".'
);
}
$compiled ??= RuntimeQuery::compile($parsedPayload['queries']);
// Carry the authorizing role so the tail can be revoked if the viewer
// later loses team membership (or the project is transferred).
$pendingTails[] = [$parsedPayload['subscriptionId'], $targetProjectId, $compiled, $requiredRole];
}
}
foreach ($parsedPayloads as $parsedPayload) {
$realtime->subscribe(
$projectId,
@@ -80,6 +145,14 @@ class Subscribe extends Action
);
}
// All tail channels passed authorization above — register them additively. The
// registry is keyed by (connId, subId, projectId): re-subscribing the same channel
// overwrites its filter in place, while a reused subscription id that names a new
// tail channel keeps the ones already registered (mirrors the tree).
foreach ($pendingTails as [$subId, $targetProjectId, $compiled, $role]) {
$eventTailRegistry->add($connectionId, $subId, $targetProjectId, $compiled, $now, $role);
}
$subscriptionsAfter = \count($realtime->getSubscriptionMetadata($connectionId));
$subscriptionDelta = $subscriptionsAfter - $subscriptionsBefore;
$subscriptionsRequested = \count($parsedPayloads);
@@ -3,6 +3,7 @@
namespace Appwrite\Realtime\Message\Handlers;
use Appwrite\Messaging\Adapter\Realtime;
use Appwrite\Realtime\EventTailRegistry;
use Appwrite\Realtime\Message\Dispatcher;
use Appwrite\Realtime\Message\Validators\UnsubscribePayload as UnsubscribePayloadValidator;
use Utopia\Platform\Action;
@@ -21,6 +22,7 @@ class Unsubscribe extends Action
->inject('connectionId')
->inject('realtime')
->inject('register')
->inject('eventTailRegistry')
->callback($this->action(...));
}
@@ -33,6 +35,7 @@ class Unsubscribe extends Action
int $connectionId,
Realtime $realtime,
Registry $register,
EventTailRegistry $eventTailRegistry,
): array {
$subscriptionsBefore = \count($realtime->getSubscriptionMetadata($connectionId));
@@ -43,6 +46,9 @@ class Unsubscribe extends Action
'subscriptionId' => $subscriptionId,
'removed' => $realtime->unsubscribeSubscription($connectionId, $subscriptionId),
];
// No-op if it wasn't a tail subscription. Connection-scoped: subscription
// IDs are only unique within a connection.
$eventTailRegistry->remove($connectionId, $subscriptionId);
}
$subscriptionsAfter = \count($realtime->getSubscriptionMetadata($connectionId));
@@ -895,4 +895,345 @@ final class RealtimeCustomClientQueryTestWithMessage extends Scope
$client->close();
}
/**
* Create a database + collection (Role::any) with a string attribute, BEFORE the
* tail connection opens, so the setup events don't appear in the tail.
*
* @return array{databaseId:string, collectionId:string}
*/
private function setupTailCollection(): array
{
$headers = [
'content-type' => 'application/json',
'x-appwrite-project' => $this->getProject()['$id'],
'x-appwrite-key' => $this->getProject()['apiKey'],
];
$database = $this->client->call(Client::METHOD_POST, '/databases', $headers, [
'databaseId' => ID::unique(),
'name' => 'Tail DB',
]);
$this->assertEquals(201, $database['headers']['status-code']);
$databaseId = $database['body']['$id'];
$collection = $this->client->call(Client::METHOD_POST, '/databases/' . $databaseId . '/collections', $headers, [
'collectionId' => ID::unique(),
'name' => 'Actors',
'permissions' => [
Permission::read(Role::any()),
Permission::create(Role::any()),
Permission::update(Role::any()),
Permission::delete(Role::any()),
],
]);
$this->assertEquals(201, $collection['headers']['status-code']);
$collectionId = $collection['body']['$id'];
$this->client->call(Client::METHOD_POST, '/databases/' . $databaseId . '/collections/' . $collectionId . '/attributes/string', $headers, [
'key' => 'name',
'size' => 256,
'required' => true,
]);
$this->assertEventually(function () use ($databaseId, $collectionId, $headers) {
$attribute = $this->client->call(Client::METHOD_GET, '/databases/' . $databaseId . '/collections/' . $collectionId . '/attributes/name', $headers);
$this->assertEquals(200, $attribute['headers']['status-code']);
$this->assertEquals('available', $attribute['body']['status']);
}, 120000, 500);
return ['databaseId' => $databaseId, 'collectionId' => $collectionId];
}
/**
* Open a console connection (root session) in message mode and subscribe to a
* `console.tail.<projectId>` channel with optional filter queries.
*
* @param array<int,string> $queries
*/
private function openConsoleTail(string $targetProjectId, array $queries = [], string $subscriptionId = 'tail-1'): WebSocketClient
{
$queryString = \http_build_query(['project' => 'console']);
$client = new WebSocketClient(
'ws://appwrite.test/v1/realtime?' . $queryString,
[
'headers' => [
'origin' => 'http://localhost',
'cookie' => 'a_session_console=' . $this->getRoot()['session'],
],
'timeout' => 10,
]
);
$connected = \json_decode($client->receive(), true);
$this->assertEquals('connected', $connected['type'] ?? null);
$sub = ['channels' => ['console.tail.' . $targetProjectId], 'subscriptionId' => $subscriptionId];
if (!empty($queries)) {
$sub['queries'] = $queries;
}
$client->send(\json_encode(['type' => 'subscribe', 'data' => [$sub]]));
$response = \json_decode($client->receive(), true);
$this->assertEquals('response', $response['type'] ?? null);
$this->assertEquals('subscribe', $response['data']['to'] ?? null);
$this->assertTrue($response['data']['success'] ?? false);
return $client;
}
/**
* Receive frames until a `console.tail` event arrives, returning its payload (an
* array of compact frames). Skips the periodic `console.tail.stats` counter frames.
*
* @return array<int,array<string,mixed>>
*/
private function receiveTailFrames(WebSocketClient $client, int $maxFrames = 5): array
{
for ($i = 0; $i < $maxFrames; $i++) {
$message = \json_decode($client->receive(), true);
$this->assertEquals('event', $message['type']);
if (($message['data']['events'][0] ?? null) === 'console.tail') {
return $message['data']['payload'];
}
}
$this->fail('No console.tail event frame received.');
}
public function testConsoleTailReceivesCompactMetadata(): void
{
['databaseId' => $databaseId, 'collectionId' => $collectionId] = $this->setupTailCollection();
$projectId = $this->getProject()['$id'];
$client = $this->openConsoleTail($projectId);
$document = $this->client->call(Client::METHOD_POST, '/databases/' . $databaseId . '/collections/' . $collectionId . '/documents', [
'content-type' => 'application/json',
'x-appwrite-project' => $projectId,
'x-appwrite-key' => $this->getProject()['apiKey'],
], [
'documentId' => ID::unique(),
'data' => ['name' => 'Spiderman'],
]);
$this->assertEquals(201, $document['headers']['status-code']);
$documentId = $document['body']['$id'];
$frames = $this->receiveTailFrames($client);
$match = null;
foreach ($frames as $frame) {
if (($frame['resourceId'] ?? null) === $documentId) {
$match = $frame;
break;
}
}
$this->assertNotNull($match, 'document.create not present in tail: ' . \json_encode($frames));
$this->assertSame('databases', $match['type']);
$this->assertSame('create', $match['action']);
$this->assertSame($databaseId, $match['databaseId']);
$this->assertSame($collectionId, $match['collectionId']);
// Compact: no full document body, and no scope ids from other resource types.
$this->assertArrayNotHasKey('name', $match);
$this->assertArrayNotHasKey('functionId', $match);
$this->assertArrayNotHasKey('bucketId', $match);
$client->close();
}
public function testConsoleTailServerSideFilter(): void
{
['databaseId' => $databaseId, 'collectionId' => $collectionId] = $this->setupTailCollection();
$projectId = $this->getProject()['$id'];
// Only deletes should reach this tail.
$client = $this->openConsoleTail($projectId, [Query::equal('action', ['delete'])->toString()]);
$headers = [
'content-type' => 'application/json',
'x-appwrite-project' => $projectId,
'x-appwrite-key' => $this->getProject()['apiKey'],
];
// create — must be filtered out (never reaches the token bucket).
$document = $this->client->call(Client::METHOD_POST, '/databases/' . $databaseId . '/collections/' . $collectionId . '/documents', $headers, [
'documentId' => ID::unique(),
'data' => ['name' => 'Ironman'],
]);
$this->assertEquals(201, $document['headers']['status-code']);
$documentId = $document['body']['$id'];
// delete — must pass the filter.
$deleted = $this->client->call(Client::METHOD_DELETE, '/databases/' . $databaseId . '/collections/' . $collectionId . '/documents/' . $documentId, $headers);
$this->assertEquals(204, $deleted['headers']['status-code']);
$frames = $this->receiveTailFrames($client);
foreach ($frames as $frame) {
$this->assertSame('delete', $frame['action'], 'filter leaked a non-delete event: ' . \json_encode($frame));
}
$deleteFrames = \array_filter($frames, fn ($f) => ($f['resourceId'] ?? null) === $documentId);
$this->assertNotEmpty($deleteFrames, 'expected the delete event in the tail');
$client->close();
}
public function testConsoleTailUnauthorizedProjectIsRejected(): void
{
$queryString = \http_build_query(['project' => 'console']);
$client = new WebSocketClient(
'ws://appwrite.test/v1/realtime?' . $queryString,
[
'headers' => [
'origin' => 'http://localhost',
'cookie' => 'a_session_console=' . $this->getRoot()['session'],
],
'timeout' => 10,
]
);
$connected = \json_decode($client->receive(), true);
$this->assertEquals('connected', $connected['type'] ?? null);
// A project the console user's team does not own (does not exist) → policy violation.
$client->send(\json_encode([
'type' => 'subscribe',
'data' => [['channels' => ['console.tail.nonexistentproject'], 'subscriptionId' => 'tail-x']],
]));
// A 1008 policy violation sends the error frame and then closes the connection.
// Depending on flush/close timing the client may read the error frame, or the
// socket may already be dead — both are valid rejections. What must NOT happen
// is a successful `response` subscription.
try {
$response = \json_decode($client->receive(), true);
$this->assertEquals('error', $response['type'] ?? null);
$this->assertEquals(1008, $response['data']['code'] ?? null);
} catch (ConnectionException) {
$this->addToAssertionCount(1);
}
// close() can itself throw on an already-closed socket — best effort.
try {
$client->close();
} catch (ConnectionException) {
// already closed by the server
}
}
public function testConsoleTailSeesEventsNotReadableByTheConsoleUser(): void
{
// The tail authorizes the *viewer* by team membership at subscribe time and then
// forwards every project event regardless of the resource's read ACL. A document
// readable only by some OTHER user (not `any`, not the console user) must still
// appear in the console tail.
$projectId = $this->getProject()['$id'];
$headers = [
'content-type' => 'application/json',
'x-appwrite-project' => $projectId,
'x-appwrite-key' => $this->getProject()['apiKey'],
];
$database = $this->client->call(Client::METHOD_POST, '/databases', $headers, [
'databaseId' => ID::unique(),
'name' => 'Tail ACL DB',
]);
$this->assertEquals(201, $database['headers']['status-code']);
$databaseId = $database['body']['$id'];
// documentSecurity ON and NO read(any) at the collection level, so the only read
// grant comes from the document's own (restricted) permission.
$collection = $this->client->call(Client::METHOD_POST, '/databases/' . $databaseId . '/collections', $headers, [
'collectionId' => ID::unique(),
'name' => 'Secrets',
'documentSecurity' => true,
'permissions' => [Permission::create(Role::any())],
]);
$this->assertEquals(201, $collection['headers']['status-code']);
$collectionId = $collection['body']['$id'];
$this->client->call(Client::METHOD_POST, '/databases/' . $databaseId . '/collections/' . $collectionId . '/attributes/string', $headers, [
'key' => 'name',
'size' => 256,
'required' => true,
]);
$this->assertEventually(function () use ($databaseId, $collectionId, $headers) {
$attribute = $this->client->call(Client::METHOD_GET, '/databases/' . $databaseId . '/collections/' . $collectionId . '/attributes/name', $headers);
$this->assertEquals(200, $attribute['headers']['status-code']);
$this->assertEquals('available', $attribute['body']['status']);
}, 120000, 500);
$client = $this->openConsoleTail($projectId);
// Read restricted to a user that is NOT the console user → the console viewer
// could never read this document directly, yet the tail must surface its event.
$document = $this->client->call(Client::METHOD_POST, '/databases/' . $databaseId . '/collections/' . $collectionId . '/documents', $headers, [
'documentId' => ID::unique(),
'data' => ['name' => 'top secret'],
'permissions' => [Permission::read(Role::user('not-the-console-user'))],
]);
$this->assertEquals(201, $document['headers']['status-code']);
$documentId = $document['body']['$id'];
$frames = $this->receiveTailFrames($client);
$match = null;
foreach ($frames as $frame) {
if (($frame['resourceId'] ?? null) === $documentId) {
$match = $frame;
break;
}
}
$this->assertNotNull($match, 'restricted-read document.create not present in tail: ' . \json_encode($frames));
$this->assertSame('databases', $match['type']);
$this->assertSame('create', $match['action']);
$this->assertArrayNotHasKey('name', $match); // still no document body
$client->close();
}
public function testProjectConnectionCannotTail(): void
{
// A normal project websocket (not the console project) must not be able to tail,
// even for a team member — only the console connection may. Expect a 1008 reject.
$user = $this->getUser();
$session = $user['session'] ?? '';
$projectId = $this->getProject()['$id'];
$queryString = \http_build_query(['project' => $projectId]); // NOT console
$client = new WebSocketClient(
'ws://appwrite.test/v1/realtime?' . $queryString,
[
'headers' => [
'origin' => 'http://localhost',
'cookie' => 'a_session_' . $projectId . '=' . $session,
],
'timeout' => 10,
]
);
$connected = \json_decode($client->receive(), true);
$this->assertEquals('connected', $connected['type'] ?? null);
$client->send(\json_encode([
'type' => 'subscribe',
'data' => [['channels' => ['console.tail.' . $projectId], 'subscriptionId' => 'tail-proj']],
]));
try {
$response = \json_decode($client->receive(), true);
$this->assertEquals('error', $response['type'] ?? null);
$this->assertEquals(1008, $response['data']['code'] ?? null);
} catch (ConnectionException) {
$this->addToAssertionCount(1);
}
try {
$client->close();
} catch (ConnectionException) {
// already closed by the server
}
}
}
@@ -0,0 +1,581 @@
<?php
declare(strict_types=1);
namespace Tests\Unit\Realtime;
use Appwrite\Messaging\Adapter\Realtime;
use Appwrite\Realtime\EventTailRegistry;
use Appwrite\Utopia\Database\RuntimeQuery;
use PHPUnit\Framework\TestCase;
use Utopia\Database\Query;
use Utopia\WebSocket\Server;
/**
* Unit tests for the console live event tail: the compact-metadata projection
* (Realtime::toTailMetadata) and the per-worker filter-then-sample registry
* (EventTailRegistry). All exercised through the public API with an injected clock
* and a mocked websocket Server — no Swoole coroutines.
*/
final class EventTailRegistryTest extends TestCase
{
/**
* Mocked Server that records every send() as a decoded payload.
*
* @param array<int,array<string,mixed>> $sent
*/
private function server(array &$sent): Server
{
// A stub (not a mock): we only capture sends, no expectations to verify.
$server = $this->createStub(Server::class);
$server->method('send')->willReturnCallback(
function (array $connections, string $message) use (&$sent): void {
$sent[] = json_decode($message, true);
}
);
return $server;
}
/**
* Like server(), but records the target connection id alongside each frame so tests
* can assert per-connection isolation.
*
* @param array<int,array{connId:mixed, frame:array<string,mixed>}> $sent
*/
private function serverWithConn(array &$sent): Server
{
$server = $this->createStub(Server::class);
$server->method('send')->willReturnCallback(
function (array $connections, string $message) use (&$sent): void {
$sent[] = ['connId' => $connections[0] ?? null, 'frame' => json_decode($message, true)];
}
);
return $server;
}
/** @param array<int,\Utopia\Database\Query> $queries */
private function compile(array $queries): array
{
return RuntimeQuery::compile($queries);
}
// ---- Realtime::toTailMetadata ----
public function testTailMetadataDocumentEvent(): void
{
$event = [
'userId' => 'user-1',
'data' => [
'events' => ['databases.main.collections.posts.documents.p1.create'],
'timestamp' => '2026-06-06T00:00:00.000+00:00',
'payload' => ['$id' => 'p1', '$databaseId' => 'main', '$collectionId' => 'posts', 'title' => 'hello'],
],
];
$meta = Realtime::toTailMetadata($event);
$this->assertSame('databases.main.collections.posts.documents.p1.create', $meta['event']);
$this->assertSame('databases', $meta['type']);
$this->assertSame('create', $meta['action']);
$this->assertSame('user-1', $meta['userId']);
$this->assertSame('p1', $meta['resourceId']);
$this->assertSame('main', $meta['databaseId']);
$this->assertSame('posts', $meta['collectionId']);
// No full document body leaks through.
$this->assertArrayNotHasKey('title', $meta);
// Scope is type-specific: a databases event carries no bucket/function ids.
$this->assertArrayNotHasKey('bucketId', $meta);
$this->assertArrayNotHasKey('functionId', $meta);
}
public function testTailMetadataScopeIsTypeSpecific(): void
{
$fn = Realtime::toTailMetadata([
'userId' => 'u1',
'data' => [
'events' => ['functions.fn1.deployments.d1.create'],
'payload' => ['$id' => 'd1', 'functionId' => 'fn1'],
],
]);
$this->assertSame('functions', $fn['type']);
$this->assertSame('fn1', $fn['functionId']);
$this->assertArrayNotHasKey('databaseId', $fn);
$this->assertArrayNotHasKey('bucketId', $fn);
$file = Realtime::toTailMetadata([
'userId' => 'u1',
'data' => [
'events' => ['buckets.b1.files.f1.create'],
'payload' => ['$id' => 'f1', 'bucketId' => 'b1'],
],
]);
$this->assertSame('buckets', $file['type']);
$this->assertSame('b1', $file['bucketId']);
$this->assertArrayNotHasKey('functionId', $file);
$this->assertArrayNotHasKey('collectionId', $file);
// Scope comes from the event name, so it's present even when the payload (here an
// execution doc) carries no functionId field — resourceId is the leaf ($id).
$exec = Realtime::toTailMetadata([
'data' => ['events' => ['functions.fn1.executions.e1.create'], 'payload' => ['$id' => 'e1']],
]);
$this->assertSame('fn1', $exec['functionId']);
$this->assertSame('e1', $exec['resourceId']);
}
public function testTailMetadataTopLevelResourceEventsCarryScope(): void
{
// Top-level resource events: the payload is the resource doc itself (id at $id,
// not at a teamId/bucketId/functionId field). Scope must still be present so a
// filter like equal('teamId', ['T']) matches the team's own create/update events.
$teamCreate = Realtime::toTailMetadata([
'data' => ['events' => ['teams.T.create'], 'payload' => ['$id' => 'T', 'name' => 'Acme']],
]);
$this->assertSame('teams', $teamCreate['type']);
$this->assertSame('T', $teamCreate['teamId']);
$this->assertSame('T', $teamCreate['resourceId']);
// Nested membership event: same teamId scope, leaf resourceId is the membership.
$membership = Realtime::toTailMetadata([
'data' => ['events' => ['teams.T.memberships.M.create'], 'payload' => ['$id' => 'M', 'teamId' => 'T']],
]);
$this->assertSame('T', $membership['teamId']);
$this->assertSame('M', $membership['resourceId']);
$bucketCreate = Realtime::toTailMetadata([
'data' => ['events' => ['buckets.B.create'], 'payload' => ['$id' => 'B']],
]);
$this->assertSame('B', $bucketCreate['bucketId']);
$functionCreate = Realtime::toTailMetadata([
'data' => ['events' => ['functions.F.create'], 'payload' => ['$id' => 'F']],
]);
$this->assertSame('F', $functionCreate['functionId']);
}
public function testTailMetadataTablesUsesTableIdAsCollection(): void
{
$meta = Realtime::toTailMetadata([
'userId' => 'u1',
'data' => [
'events' => ['databases.main.tables.t1.rows.r1.create'],
'payload' => ['$id' => 'r1', '$databaseId' => 'main', '$tableId' => 't1'],
],
]);
$this->assertSame('databases', $meta['type']);
$this->assertSame('main', $meta['databaseId']);
$this->assertSame('t1', $meta['collectionId']);
}
public function testTailMetadataExtractsScopeForAllDatabasePrefixes(): void
{
// The database family is published under several prefixes. `type` keeps the
// actual prefix, and databaseId/collectionId are extracted for every one of them
// (so scope filters work across the whole family regardless of the variant).
foreach (['databases', 'tablesdb', 'documentsdb', 'vectorsdb'] as $prefix) {
$meta = Realtime::toTailMetadata([
'userId' => 'u1',
'data' => [
'events' => ["{$prefix}.main.collections.posts.documents.p1.create"],
'payload' => ['$id' => 'p1'],
],
]);
$this->assertSame($prefix, $meta['type'], 'type preserves the actual prefix');
$this->assertSame('main', $meta['databaseId']);
$this->assertSame('posts', $meta['collectionId']);
}
// `tables` sub-resource under a projected prefix still maps to collectionId.
$rows = Realtime::toTailMetadata([
'data' => ['events' => ['tablesdb.main.tables.t1.rows.r1.create'], 'payload' => ['$id' => 'r1']],
]);
$this->assertSame('tablesdb', $rows['type']);
$this->assertSame('main', $rows['databaseId']);
$this->assertSame('t1', $rows['collectionId']);
}
public function testTailMetadataAttributeTrailingAction(): void
{
// `users.U.update.email` — action is the second-to-last segment.
$meta = Realtime::toTailMetadata([
'userId' => 'u9',
'data' => ['events' => ['users.u9.update.email'], 'payload' => ['$id' => 'u9']],
]);
$this->assertSame('users', $meta['type']);
$this->assertSame('update', $meta['action']);
$this->assertSame('u9', $meta['resourceId']);
}
public function testTailMetadataHandlesMissingPayload(): void
{
$meta = Realtime::toTailMetadata(['data' => ['events' => ['functions.f1.executions.e1.delete']]]);
$this->assertSame('functions', $meta['type']);
$this->assertSame('delete', $meta['action']);
$this->assertNull($meta['userId']);
$this->assertNull($meta['resourceId']);
}
// ---- channel helpers ----
public function testChannelHelpers(): void
{
$this->assertSame('console.tail.proj1', EventTailRegistry::channel('proj1'));
$this->assertSame('proj1', EventTailRegistry::projectFromChannel('console.tail.proj1'));
$this->assertNull(EventTailRegistry::projectFromChannel('documents'));
$this->assertNull(EventTailRegistry::projectFromChannel('console.tail.'));
}
// ---- filter THEN sample ----
public function testFilterIsAppliedBeforeSampling(): void
{
$registry = new EventTailRegistry(rate: 100);
$registry->add(1, 'sub-a', 'projX', $this->compile([Query::equal('type', ['databases'])]), 0.0);
$registry->ingest('projX', ['type' => 'databases', 'action' => 'create'], 0.0);
$registry->ingest('projX', ['type' => 'buckets', 'action' => 'create'], 0.0);
$sent = [];
$registry->flush($this->server($sent));
// Exactly one event frame, carrying only the databases frame; no stats frame
// because the filtered-out bucket event never consumed a token.
$this->assertCount(1, $sent);
$this->assertSame(['console.tail'], $sent[0]['data']['events']);
$this->assertCount(1, $sent[0]['data']['payload']);
$this->assertSame('databases', $sent[0]['data']['payload'][0]['type']);
}
public function testTokenBucketDropsExcessAndEmitsCounter(): void
{
$registry = new EventTailRegistry(rate: 5);
$registry->add(1, 'sub-a', 'projX', $this->compile([]), 0.0); // selectAll
for ($i = 0; $i < 20; $i++) {
$registry->ingest('projX', ['type' => 'databases', 'seq' => $i], 0.0);
}
$sent = [];
$registry->flush($this->server($sent));
$eventFrames = array_values(array_filter($sent, fn ($f) => $f['data']['events'] === ['console.tail']));
$statsFrames = array_values(array_filter($sent, fn ($f) => $f['data']['events'] === ['console.tail.stats']));
$this->assertCount(1, $eventFrames);
$this->assertCount(5, $eventFrames[0]['data']['payload'], 'rate=5 → only 5 delivered at the same instant');
$this->assertCount(1, $statsFrames);
$this->assertSame('tail.stats', $statsFrames[0]['data']['payload']['$type']);
$this->assertSame(5, $statsFrames[0]['data']['payload']['delivered']);
$this->assertSame(15, $statsFrames[0]['data']['payload']['dropped']);
// delivered + dropped accounts for every ingested event.
$this->assertSame(20, $statsFrames[0]['data']['payload']['delivered'] + $statsFrames[0]['data']['payload']['dropped']);
}
public function testNoCounterFrameWhenNothingDropped(): void
{
$registry = new EventTailRegistry(rate: 100);
$registry->add(1, 'sub-a', 'projX', $this->compile([]), 0.0);
$registry->ingest('projX', ['type' => 'databases'], 0.0);
$sent = [];
$registry->flush($this->server($sent));
// Only the event frame — no stats frame because nothing was dropped.
$this->assertCount(1, $sent);
$this->assertSame(['console.tail'], $sent[0]['data']['events']);
}
public function testDroppedAccumulatesAcrossIngestsInWindow(): void
{
$registry = new EventTailRegistry(rate: 2);
$registry->add(1, 'sub-a', 'projX', $this->compile([]), 0.0);
// Three separate ingests at the same instant: 2 delivered, 1 dropped.
$registry->ingest('projX', ['type' => 'databases', 'seq' => 1], 0.0);
$registry->ingest('projX', ['type' => 'databases', 'seq' => 2], 0.0);
$registry->ingest('projX', ['type' => 'databases', 'seq' => 3], 0.0);
$sent = [];
$registry->flush($this->server($sent));
$statsFrames = array_values(array_filter($sent, fn ($f) => $f['data']['events'] === ['console.tail.stats']));
$this->assertCount(1, $statsFrames);
$this->assertSame(2, $statsFrames[0]['data']['payload']['delivered']);
$this->assertSame(1, $statsFrames[0]['data']['payload']['dropped']);
}
public function testCounterResetsBetweenWindows(): void
{
$registry = new EventTailRegistry(rate: 1);
$registry->add(1, 'sub-a', 'projX', $this->compile([]), 0.0);
// Window 1: 3 events at t=0 → 1 delivered, 2 dropped → stats frame emitted.
for ($i = 0; $i < 3; $i++) {
$registry->ingest('projX', ['type' => 'databases', 'seq' => $i], 0.0);
}
$sent = [];
$registry->flush($this->server($sent));
$statsFrames = array_values(array_filter($sent, fn ($f) => $f['data']['events'] === ['console.tail.stats']));
$this->assertCount(1, $statsFrames);
$this->assertSame(2, $statsFrames[0]['data']['payload']['dropped']);
// Window 2: a single event well after refill → delivered, nothing dropped → no stats frame
// and the previous window's dropped count does not carry over.
$registry->ingest('projX', ['type' => 'databases'], 100.0);
$sent = [];
$registry->flush($this->server($sent));
$statsFrames = array_values(array_filter($sent, fn ($f) => $f['data']['events'] === ['console.tail.stats']));
$this->assertCount(0, $statsFrames);
}
public function testLargeBufferIsChunkedAcrossFrames(): void
{
// rate high enough to admit all, batchMax forces splitting on flush.
$registry = new EventTailRegistry(rate: 100, batchMax: 2);
$registry->add(1, 'sub-a', 'projX', $this->compile([]), 0.0);
for ($i = 0; $i < 5; $i++) {
$registry->ingest('projX', ['type' => 'databases', 'seq' => $i], 0.0);
}
$sent = [];
$registry->flush($this->server($sent));
$eventFrames = array_values(array_filter($sent, fn ($f) => $f['data']['events'] === ['console.tail']));
// 5 buffered frames, batchMax 2 → 3 websocket frames (2 + 2 + 1).
$this->assertCount(3, $eventFrames);
$this->assertCount(2, $eventFrames[0]['data']['payload']);
$this->assertCount(2, $eventFrames[1]['data']['payload']);
$this->assertCount(1, $eventFrames[2]['data']['payload']);
// No event is lost across the chunk boundaries.
$total = array_sum(array_map(fn ($f) => count($f['data']['payload']), $eventFrames));
$this->assertSame(5, $total);
}
public function testTokensRefillOverTime(): void
{
$registry = new EventTailRegistry(rate: 5);
$registry->add(1, 'sub-a', 'projX', $this->compile([]), 0.0);
// Drain the bucket at t=0.
for ($i = 0; $i < 10; $i++) {
$registry->ingest('projX', ['type' => 'databases'], 0.0);
}
$sent = [];
$registry->flush($this->server($sent)); // resets the per-window counters
// One second later, the bucket has refilled to the cap (rate=5).
for ($i = 0; $i < 10; $i++) {
$registry->ingest('projX', ['type' => 'databases'], 1.0);
}
$sent = [];
$registry->flush($this->server($sent));
$eventFrames = array_values(array_filter($sent, fn ($f) => $f['data']['events'] === ['console.tail']));
$this->assertCount(5, $eventFrames[0]['data']['payload']);
}
public function testFlushClearsBufferBetweenWindows(): void
{
$registry = new EventTailRegistry(rate: 100);
$registry->add(1, 'sub-a', 'projX', $this->compile([]), 0.0);
$registry->ingest('projX', ['type' => 'databases'], 0.0);
$sent = [];
$registry->flush($this->server($sent));
$this->assertCount(1, $sent);
// Nothing new ingested → second flush sends nothing.
$sent = [];
$registry->flush($this->server($sent));
$this->assertCount(0, $sent);
}
public function testRemoveConnectionStopsDelivery(): void
{
$registry = new EventTailRegistry(rate: 100);
$registry->add(7, 'sub-a', 'projX', $this->compile([]), 0.0);
$registry->add(7, 'sub-b', 'projY', $this->compile([]), 0.0);
$this->assertTrue($registry->isTailed('projX'));
$this->assertTrue($registry->isTailed('projY'));
$registry->removeConnection(7);
$this->assertFalse($registry->isTailed('projX'));
$this->assertFalse($registry->isTailed('projY'));
$registry->ingest('projX', ['type' => 'databases'], 0.0);
$sent = [];
$registry->flush($this->server($sent));
$this->assertCount(0, $sent);
}
public function testRemoveSingleSubscription(): void
{
$registry = new EventTailRegistry(rate: 100);
$registry->add(7, 'sub-a', 'projX', $this->compile([]), 0.0);
$registry->add(7, 'sub-b', 'projX', $this->compile([]), 0.0);
$registry->remove(7, 'sub-a');
$this->assertTrue($registry->isTailed('projX'), 'sub-b still tails projX');
$registry->remove(7, 'sub-b');
$this->assertFalse($registry->isTailed('projX'));
// Removing an unknown subscription is a no-op.
$registry->remove(7, 'does-not-exist');
$this->assertFalse($registry->isTailed('projX'));
}
public function testSameSubscriptionIdOnDifferentConnectionsIsolated(): void
{
// Subscription IDs are only unique within a connection. Two connections both
// using 'dup' must stay fully isolated — no cross-project/connection leakage.
$registry = new EventTailRegistry(rate: 100);
$registry->add(1, 'dup', 'projA', $this->compile([]), 0.0);
$registry->add(2, 'dup', 'projB', $this->compile([]), 0.0);
$registry->ingest('projA', ['type' => 'databases', 'resourceId' => 'a1'], 0.0);
$registry->ingest('projB', ['type' => 'databases', 'resourceId' => 'b1'], 0.0);
$sent = [];
$registry->flush($this->serverWithConn($sent));
$byConn = [];
foreach ($sent as $s) {
$byConn[$s['connId']][] = $s['frame']['data']['channels'][0];
}
// Connection 1 only ever receives projA's channel; connection 2 only projB's.
$this->assertSame(['console.tail.projA'], $byConn[1] ?? []);
$this->assertSame(['console.tail.projB'], $byConn[2] ?? []);
// Removing one connection's 'dup' must not touch the other's.
$registry->remove(1, 'dup');
$this->assertFalse($registry->isTailed('projA'));
$this->assertTrue($registry->isTailed('projB'));
}
public function testMultipleProjectsUnderOneSubscription(): void
{
// A subscription naming several tail channels tails each project independently;
// none overwrites another, and removing the subscription clears them all.
$registry = new EventTailRegistry(rate: 100);
$registry->add(1, 'sub-multi', 'projA', $this->compile([]), 0.0);
$registry->add(1, 'sub-multi', 'projB', $this->compile([]), 0.0);
$this->assertTrue($registry->isTailed('projA'));
$this->assertTrue($registry->isTailed('projB'));
$registry->ingest('projA', ['type' => 'databases', 'resourceId' => 'a1'], 0.0);
$registry->ingest('projB', ['type' => 'databases', 'resourceId' => 'b1'], 0.0);
$sent = [];
$registry->flush($this->serverWithConn($sent));
$channels = array_map(fn ($s) => $s['frame']['data']['channels'][0], $sent);
$this->assertContains('console.tail.projA', $channels);
$this->assertContains('console.tail.projB', $channels);
// Both frames carry the same (real) subscription id.
foreach ($sent as $s) {
$this->assertSame(['sub-multi'], $s['frame']['data']['subscriptions']);
}
$registry->remove(1, 'sub-multi');
$this->assertFalse($registry->isTailed('projA'));
$this->assertFalse($registry->isTailed('projB'));
}
public function testReAddingSameChannelOverwritesFilterWithoutStaleEntry(): void
{
// Reusing a subscription id on the SAME tail channel updates its filter in place
// (keyed by connId/subId/projectId) — no stale entry, no duplicate delivery.
$registry = new EventTailRegistry(rate: 100);
$registry->add(1, 'x', 'projA', $this->compile([Query::equal('action', ['create'])]), 0.0);
$registry->add(1, 'x', 'projA', $this->compile([Query::equal('action', ['delete'])]), 0.0);
$registry->ingest('projA', ['action' => 'create', 'resourceId' => 'c1'], 0.0);
$registry->ingest('projA', ['action' => 'delete', 'resourceId' => 'd1'], 0.0);
$sent = [];
$registry->flush($this->server($sent));
$eventFrames = array_values(array_filter($sent, fn ($f) => $f['data']['events'] === ['console.tail']));
// A lingering create-filter entry would surface the create and/or add a 2nd frame.
$this->assertCount(1, $eventFrames);
$this->assertCount(1, $eventFrames[0]['data']['payload']);
$this->assertSame('delete', $eventFrames[0]['data']['payload'][0]['action']);
$this->assertSame('d1', $eventFrames[0]['data']['payload'][0]['resourceId']);
}
public function testAddingChannelPreservesExistingTail(): void
{
// Review scenario: subscribe id 'x' to tail A, later add tail B under the same id.
// Registration is additive (mirrors Realtime::subscribe()), so A must keep delivering.
$registry = new EventTailRegistry(rate: 100);
$registry->add(1, 'x', 'projA', $this->compile([]), 0.0);
// ... later, the same subscription id also tails projB.
$registry->add(1, 'x', 'projB', $this->compile([]), 0.0);
$this->assertTrue($registry->isTailed('projA'), 'projA must remain tailed after adding projB');
$this->assertTrue($registry->isTailed('projB'));
$registry->ingest('projA', ['type' => 'databases', 'resourceId' => 'a1'], 0.0);
$registry->ingest('projB', ['type' => 'databases', 'resourceId' => 'b1'], 0.0);
$sent = [];
$registry->flush($this->serverWithConn($sent));
$channels = array_map(fn ($s) => $s['frame']['data']['channels'][0], $sent);
$this->assertContains('console.tail.projA', $channels, 'projA stopped delivering after projB was added');
$this->assertContains('console.tail.projB', $channels);
}
public function testRateClampedToAtLeastOne(): void
{
// A misconfigured non-positive rate must not disable the tail entirely.
foreach ([0, -5] as $badRate) {
$registry = new EventTailRegistry(rate: $badRate);
$registry->add(1, 'x', 'projA', $this->compile([]), 0.0);
$registry->ingest('projA', ['type' => 'databases'], 0.0);
$sent = [];
$registry->flush($this->server($sent));
$eventFrames = array_values(array_filter($sent, fn ($f) => $f['data']['events'] === ['console.tail']));
$this->assertCount(1, $eventFrames, "rate {$badRate} must clamp to >=1 so events still flow");
$this->assertCount(1, $eventFrames[0]['data']['payload']);
}
}
public function testRevalidateConnectionDropsTailsWithRevokedRole(): void
{
$registry = new EventTailRegistry(rate: 100);
$registry->add(1, 'x', 'projA', $this->compile([]), 0.0, 'team:teamA');
$registry->add(1, 'y', 'projB', $this->compile([]), 0.0, 'team:teamB');
$this->assertTrue($registry->isTailed('projA'));
$this->assertTrue($registry->isTailed('projB'));
// The connection keeps teamB membership but loses teamA.
$registry->revalidateConnection(1, ['user:u1', 'team:teamB']);
$this->assertFalse($registry->isTailed('projA'), 'tail for the revoked team must be dropped');
$this->assertTrue($registry->isTailed('projB'), 'tail for the still-held team must remain');
}
public function testRevalidateConnectionKeepsEntriesWithoutRole(): void
{
// Entries registered without an authorizing role are never pruned (defensive).
$registry = new EventTailRegistry(rate: 100);
$registry->add(1, 'x', 'projA', $this->compile([]), 0.0);
$registry->revalidateConnection(1, ['user:u1']);
$this->assertTrue($registry->isTailed('projA'));
}
}