Cleaned up the API in Analytics to different namespaces

and documented the Analytics mechanism

Author: SOF3

dev.md

@@ -242,7 +242,47 @@ it creates new accounts based on initial setup specified by the schema.
 
 ### Analytics
 
-<!-- TODO -->
+The Analytics module consists of two parts: Single and Top.
+
+### Single metrics
+
+`Analytics\Single` computes single-value metrics.
+
+The `Analytics\Single\Query` interface abstracts different metric types
+parameterized by a generic parameter `P`.
+Use `CachedValue::loop` to spawn a refresh loop that fetches the latest metric value.
+If `P` is `Player`, use `PlayerInfoUpdater::registerListener()`
+to automatically spawn refresh loops for online players.
+
+### Top metrics
+
+`Analytics\Top` reports server-wide top metrics.
+
+Due to the label-oriented mechanism,
+it is not possible to efficiently fetch the top accounts directly
+because the SQL database cannot be indexed by a specific label.
+To allow efficient top metric queries,
+the metric is first computed for each grouping label value
+(usually the player UUID) and cached in the `capital_analytics_top_cache` table.
+
+A top metric query is defined by the following:
+
+- The aggregator to use.
+  This also defines whether the query operates on accounts or transactions.
+  Currently all aggregators are accounts-only or transactions-only,
+  but there will be aggregators on transactions for each account in the future.
+- The label selector that filters rows.
+  For example, if the aggregator is about number of transactions of each player,
+  the label selector filters away non-player accounts
+  (it is not a transaction label selector).
+- The grouping label name, where its values will be used to group rows.
+  For queries on top players, this is `AccountLabels::PLAYER_UUID`.
+
+These three values uniquely identify a top query for computation cache.
+These values are md5-hashed into the `capital_analytics_top_cache.query` column,
+which are reused on multiple servers.
+The computation takes place in batches, updating a subset of label values each time.
+Call `Analytics\Top\Mod::runRefreshLoop()` to start a refreshing loop.
 
 ### Transfer
 

phpstan-baseline.neon

@@ -3,7 +3,7 @@ parameters:
 		-
 			message: "#^While loop condition is always true\\.$#"
 			count: 1
-			path: src/SOFe/Capital/Analytics/ConfigTop.php
+			path: src/SOFe/Capital/Analytics/Top/Mod.php
 
 		-
 			message: "#^Method SOFe\\\\Capital\\\\Config\\\\Raw\\:\\:loadConfig\\(\\) should return T of SOFe\\\\Capital\\\\Config\\\\ConfigInterface but returns object\\.$#"

src/SOFe/Capital/Analytics/CachedSingleValue.php

@@ -28,9 +28,9 @@ final class Config implements Singleton, FromContext, ConfigInterface {
     use SingletonArgs, SingletonTrait, ConfigTrait;
 
     /**
-     * @param array<string, PlayerInfosManager> $singleQueries
+     * @param array<string, Single\PlayerInfoUpdater> $singleQueries
      * @param array<string, PlayerInfoCommand> $infoCommands
-     * @param list<ConfigTop> $topQueries
+     * @param list<Top\Config> $topQueries
      */
     public function __construct(
         public array $singleQueries,
@@ -102,7 +102,7 @@ public static function parse(Parser $config, Context $di, Raw $raw) : Generator
 
         foreach ($topPlayersConfig->getKeys() as $key) {
             $queryConfig = $topPlayersConfig->enter($key, null);
-            $topQueries[] = self::parseTopPlayerQuery($queryConfig, $schema, $key);
+            $topQueries[] = Top\Config::parse($queryConfig, $schema, $key);
         }
 
         return new self(
@@ -112,7 +112,7 @@ public static function parse(Parser $config, Context $di, Raw $raw) : Generator
         );
     }
 
-    private static function parseSingleQuery(Parser $infoConfig, Schema\Schema $schema, string $infoName) : PlayerInfosManager {
+    private static function parseSingleQuery(Parser $infoConfig, Schema\Schema $schema, string $infoName) : Single\PlayerInfoUpdater {
         $type = $infoConfig->expectString("of", "account", <<<'EOT'
             The data source of this info.
             If set to "account", the info is calculated from statistics of some of the player's accounts.
@@ -128,7 +128,7 @@ private static function parseSingleQuery(Parser $infoConfig, Schema\Schema $sche
 
             $metric = AccountQueryMetric::parseConfig($infoConfig, "metric");
 
-            $query = new AccountSingleQuery($metric, fn(Player $player) => $infoSchema->getSelector($player));
+            $query = new Single\AccountQuery($metric, fn(Player $player) => $infoSchema->getSelector($player));
         } elseif ($type === "transaction") {
             $selectorConfig = $infoConfig->enter("selector", "Filter transactions by labels");
             $labels = [];
@@ -139,7 +139,7 @@ private static function parseSingleQuery(Parser $infoConfig, Schema\Schema $sche
 
             $metric = TransactionQueryMetric::parseConfig($infoConfig, "metric");
 
-            $query = new TransactionSingleQuery($metric, fn(Player $player) => $labels->transform(new PlayerInfo($player)));
+            $query = new Single\TransactionQuery($metric, fn(Player $player) => $labels->transform(new PlayerInfo($player)));
         } else {
             throw new AssertionError("unreachable code");
         }
@@ -149,7 +149,7 @@ private static function parseSingleQuery(Parser $infoConfig, Schema\Schema $sche
             This will only affect displays and will not affect transactions.
             EOT) * 20.);
 
-        return new PlayerInfosManager($infoName, new CachedSingleQuery($query, $updateFrequencyTicks));
+        return new Single\PlayerInfoUpdater($infoName, new Single\Cached($query, $updateFrequencyTicks));
     }
 
     private static function parseInfoCommand(Parser $config, string $cmdName) : PlayerInfoCommand {
@@ -164,32 +164,4 @@ private static function parseInfoCommand(Parser $config, string $cmdName) : Play
 
         return new PlayerInfoCommand($command, $template);
     }
-
-    private static function parseTopPlayerQuery(Parser $infoConfig, Schema\Schema $schema, string $cmdName) : ConfigTop {
-        $cmdConfig = $infoConfig->enter("command", "The command that displays the information.");
-        $command = DynamicCommand::parse($cmdConfig, "analytics.top", $cmdName, "Displays the richest player", false);
-
-        $queryArgs = TopQueryArgs::parse($infoConfig, $schema);
-
-        $refreshConfig = $infoConfig->enter("refresh", <<<'EOT'
-            Refresh settings for the top query.
-            These settings depend on how many active accounts you have in the database
-            as well as how powerful the CPU of your database server is.
-            Try increasing the frequencies and reducing batch size if the database server is lagging.
-            EOT);
-        $refreshArgs = TopRefreshArgs::parse($refreshConfig);
-
-        $paginationConfig = $infoConfig->enter("pagination", <<<'EOT'
-            Pagination settings for the top query.
-            EOT);
-        $paginationArgs = TopPaginationArgs::parse($paginationConfig);
-
-        return new ConfigTop(
-            command: $command,
-            queryArgs: $queryArgs,
-            refreshArgs: $refreshArgs,
-            paginationArgs: $paginationArgs,
-            messages: TopMessages::parse($infoConfig->enter("messages", "Configures the displayed messages")),
-        );
-    }
 }

src/SOFe/Capital/Analytics/Config.php

@@ -4,36 +4,22 @@
 
 namespace SOFe\Capital\Analytics;
 
-use SOFe\AwaitStd\AwaitStd;
-use SOFe\Capital\Database\Database;
 use SOFe\Capital\Di\FromContext;
 use SOFe\Capital\Di\Singleton;
 use SOFe\Capital\Di\SingletonArgs;
 use SOFe\Capital\Di\SingletonTrait;
 use SOFe\Capital\Plugin\MainClass;
-use SOFe\InfoAPI\Info;
 
 final class Mod implements Singleton, FromContext {
     use SingletonArgs, SingletonTrait;
 
     public const API_VERSION = "0.1.0";
 
-    public static function fromSingletonArgs(Config $config, MainClass $plugin, AwaitStd $std, Database $db, DatabaseUtils $dbu) : self {
-        Info::registerByReflection("capital.analytics.top", PaginationInfo::class);
-        TopResultEntryInfo::initCommon();
-
-        foreach ($config->singleQueries as $manager) {
-            $manager->register($plugin, $std, $db);
-        }
-
+    public static function fromSingletonArgs(Config $config, MainClass $plugin, Single\Mod $_single, Top\Mod $_top) : self {
         foreach ($config->infoCommands as $cmd) {
             $cmd->register($plugin);
         }
 
-        foreach ($config->topQueries as $query) {
-            $query->register($plugin, $std, $dbu);
-        }
-
         return new self;
     }
 }

src/SOFe/Capital/Analytics/Mod.php

@@ -2,7 +2,7 @@
 
 declare(strict_types=1);
 
-namespace SOFe\Capital\Analytics;
+namespace SOFe\Capital\Analytics\Single;
 
 use Closure;
 use Generator;
@@ -12,9 +12,9 @@
 
 /**
  * @template P
- * @implements SingleQuery<P>
+ * @implements Query<P>
  */
-final class AccountSingleQuery implements SingleQuery {
+final class AccountQuery implements Query {
     /**
      * @param Closure(P): LabelSelector $labelSelector
      */

src/SOFe/Capital/Analytics/AccountSingleQuery.php src/SOFe/Capital/Analytics/Single/AccountQuery.php

@@ -2,19 +2,20 @@
 
 declare(strict_types=1);
 
-namespace SOFe\Capital\Analytics;
+namespace SOFe\Capital\Analytics\Single;
 
 use function min;
 
 /**
+ * The configuration for a SingleQuery whose result is cached locally and refreshd periodically.
  * @template P
  */
-final class CachedSingleQuery {
+final class Cached {
     /**
-     * @param SingleQuery<P> $query
+     * @param Query<P> $query
      */
     public function __construct(
-        public SingleQuery $query,
+        public Query $query,
         public int $updateFrequencyTicks,
     ) {
     }

src/SOFe/Capital/Analytics/CachedSingleQuery.php src/SOFe/Capital/Analytics/Single/Cached.php

@@ -0,0 +1,35 @@
+<?php
+
+declare(strict_types=1);
+
+namespace SOFe\Capital\Analytics\Single;
+
+use Closure;
+use Generator;
+use SOFe\AwaitStd\AwaitStd;
+use SOFe\Capital\Database\Database;
+use SOFe\InfoAPI\NumberInfo;
+
+final class CachedValue {
+    public function __construct(public ?float $value) {
+    }
+
+    public function asInfo() : ?NumberInfo {
+        return $this->value !== null ? new NumberInfo($this->value) : null;
+    }
+
+    /**
+     * @template P
+     * @param Closure(): bool $continue Whether to continue the loop.
+     * @param Cached<P> $cache The cached query.
+     * @param P $p
+     * @return VoidPromise
+     */
+    public function loop(Closure $continue, AwaitStd $std, Cached $cache, $p, Database $db) : Generator {
+        while ($continue()) {
+            $this->value = yield from $cache->query->fetch($p, $db);
+
+            yield from $std->sleep($cache->updateFrequencyTicks);
+        }
+    }
+}

src/SOFe/Capital/Analytics/Single/CachedValue.php

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace SOFe\Capital\Analytics\Single;
+
+use SOFe\AwaitStd\AwaitStd;
+use SOFe\Capital\Analytics;
+use SOFe\Capital\Database\Database;
+use SOFe\Capital\Di\FromContext;
+use SOFe\Capital\Di\Singleton;
+use SOFe\Capital\Di\SingletonArgs;
+use SOFe\Capital\Di\SingletonTrait;
+use SOFe\Capital\Plugin\MainClass;
+
+final class Mod implements Singleton, FromContext {
+    use SingletonArgs, SingletonTrait;
+
+    public const API_VERSION = "0.1.0";
+
+    public static function fromSingletonArgs(Analytics\Config $config, MainClass $plugin, AwaitStd $std, Database $db) : self {
+        foreach ($config->singleQueries as $manager) {
+            $manager->register($plugin, $std, $db);
+        }
+
+        return new self;
+    }
+}