Add stats command to show ASN registration statistics

lib/cli/help.ts

@@ -7,11 +7,13 @@ export function printHelp() {
 Usage: ${cmd} [command] [options]
 
 Commands:
-  server          Start the server (default)
-    --port <port> Port to listen on (defaults to the PORT environment variable)
-    --host <host> Hostname to listen on (defaults to localhost)
-  generate        Generate new ASNs
-    --count <n>   Number of ASNs to generate (defaults to 1)
+  server            Start the server (default)
+    --port <port>   Port to listen on (defaults to the PORT environment variable)
+    --host <host>   Hostname to listen on (defaults to localhost)
+  generate          Generate new ASNs
+    --count <n>     Number of ASNs to generate (defaults to 1)
+  stats             Show statistics about the rate of ASN registrations
+    --namespace <n> Show statistics for a specific namespace. Omit to show all.
 
 Options:
   --help  Show this help message

lib/cli/stats.ts

@@ -0,0 +1,100 @@
+import z from "@collinhacks/zod";
+import { CONFIG, TimeStats } from "$common/mod.ts";
+
+const generateArgs = z.object({
+  namespace: z.number({ coerce: true }).optional(),
+});
+
+/**
+ * Prints statistics about the ASNs.
+ * @param args the arguments to the command
+ * @param args.count the number of ASNs to generate (default: 1)
+ */
+export async function runStats(args: unknown) {
+  const parsedParams = generateArgs.parse(args);
+
+  console.log("Calculating statistics...");
+  console.log("Depending on the number of namespaces, this may take a while.");
+  console.log("---");
+
+  const namespaces = parsedParams.namespace
+    ? [parsedParams.namespace]
+    : allManagedNamespaces();
+
+  const stats = await Promise.all(
+    namespaces.map((v) => TimeStats.get(v)),
+  );
+
+  const strings = stats.map((stats) => {
+    return `${CONFIG.ASN_PREFIX}${stats.namespace}XXX: ` + stats.toString();
+  });
+
+  console.log(strings.join("\n"));
+  console.log("---");
+  console.log(
+    "Maximum Rate of ASN registrations per hour per namespace in the above namespaces:",
+  );
+  console.log(
+    `Filtered to only include namespaces with more than 3 ${CONFIG.ASN_PREFIX} numbers.`,
+  );
+
+  function maxHourlyRate(sigma: number) {
+    return stats
+      .filter((v) => v.count > 3)
+      .map((v) => v.getHighestRate(sigma))
+      .reduce((prev, curr) => Math.max(prev, curr)) * 60 * 1000;
+  }
+
+  console.log(
+    "1σ (68.27 %):",
+    maxHourlyRate(1).toPrecision(5),
+    `registered ${CONFIG.ASN_PREFIX} numbers per namespace per hour`,
+  );
+  console.log(
+    "2σ (95.45 %):",
+    maxHourlyRate(2).toPrecision(5),
+    `registered ${CONFIG.ASN_PREFIX} numbers per namespace per hour`,
+  );
+  console.log(
+    "3σ (99.73 %):",
+    maxHourlyRate(3).toPrecision(5),
+    `registered ${CONFIG.ASN_PREFIX} numbers per namespace per hour`,
+  );
+  console.log(
+    "6σ (99.99 %):",
+    maxHourlyRate(6).toPrecision(5),
+    `registered ${CONFIG.ASN_PREFIX} numbers per namespace per hour`,
+  );
+
+  console.log(
+    "When restoring a backup, bump each namespace by the hourly rate above multiplied by the number of hours since the last backup.",
+    "This way, you can avoid collisions from registrations that happened after the backup.",
+    "For example, if you want to restore a backup that is 24 hours old, and want to be 99.73 % sure that you won't get any conflicts,",
+    "bump each namespace by the 3σ rate above multiplied by 24.",
+  );
+
+  console.log("---");
+
+  console.log("Done.");
+
+  await Promise.resolve();
+}
+
+/**
+ * Exports a list of all managed namespaces.
+ * @returns all managed namespaces
+ */
+export function allManagedNamespaces() {
+  const minGeneric = Number.parseInt(
+    "1" + "0".repeat(CONFIG.ASN_NAMESPACE_RANGE.toString().length - 1),
+  );
+  const maxGeneric = CONFIG.ASN_NAMESPACE_RANGE - 1;
+
+  return [
+    ...Array.from(
+      { length: maxGeneric - minGeneric },
+      (_, i) => i + minGeneric,
+    ),
+    ...CONFIG.ADDITIONAL_MANAGED_NAMESPACES.map((v) => v.namespace),
+  ];
+}

main.ts

@@ -40,6 +40,7 @@ import { validateDB } from "$common/mod.ts";
 import { runServer } from "$cli/server.ts";
 import { printHelp } from "$cli/help.ts";
 import { runGenerate } from "$cli/generate.ts";
+import { runStats } from "$cli/stats.ts";
 
 export * from "$common/mod.ts";
 export * from "$http/mod.tsx";
@@ -58,6 +59,10 @@ if (import.meta.main) {
     await runGenerate(args);
   }
 
+  if (args._[0] === "stats") {
+    await runStats(args);
+  }
+
   if (args._[0] === "server" || args._.length === 0) {
     await runServer(args);
   }