@iann29/rastro 0.1.0-alpha.5 → 0.1.0-alpha.7

package/scripts/benchmark-ingest.mjs

@@ -67,16 +67,19 @@ function parseOptions(argv) {
   const values = new Map();
   for (let index = 0; index < argv.length; index += 1) {
     const argument = argv[index];
-    if (!argument.startsWith("--")) throw new Error(`unexpected argument: ${argument}`);
+    if (!argument.startsWith("--"))
+      throw new Error(`unexpected argument: ${argument}`);
     const [rawName, inlineValue] = argument.slice(2).split("=", 2);
-    if (!OPTION_NAMES.has(rawName)) throw new Error(`unknown option: --${rawName}`);
+    if (!OPTION_NAMES.has(rawName))
+      throw new Error(`unknown option: --${rawName}`);
     if (values.has(rawName)) throw new Error(`duplicate option: --${rawName}`);
     if (rawName === "dry-run" || rawName === "certify") {
       values.set(rawName, "true");
       continue;
     }
     const value = inlineValue ?? argv[++index];
-    if (!value || value.startsWith("--")) throw new Error(`missing value for --${rawName}`);
+    if (!value || value.startsWith("--"))
+      throw new Error(`missing value for --${rawName}`);
     values.set(rawName, value);
   }
   const profile = values.get("profile") ?? "realistic";
@@ -95,7 +98,10 @@ function parseOptions(argv) {
     maximumRequests: values.has("requests")
       ? positiveInteger(values.get("requests"), "requests")
       : Number.POSITIVE_INFINITY,
-    concurrency: positiveInteger(values.get("concurrency") ?? "100", "concurrency"),
+    concurrency: positiveInteger(
+      values.get("concurrency") ?? "100",
+      "concurrency",
+    ),
     batchSize: positiveInteger(
       values.get("batch-size") ?? String(defaults.batchSize),
       "batch-size",
@@ -112,20 +118,23 @@ function parseOptions(argv) {
 
 function positiveNumber(value, name) {
   const parsed = Number(value);
-  if (!Number.isFinite(parsed) || parsed <= 0) throw new Error(`--${name} must be positive`);
+  if (!Number.isFinite(parsed) || parsed <= 0)
+    throw new Error(`--${name} must be positive`);
   return parsed;
 }
 
 function positiveInteger(value, name) {
   const parsed = positiveNumber(value, name);
-  if (!Number.isSafeInteger(parsed)) throw new Error(`--${name} must be an integer`);
+  if (!Number.isSafeInteger(parsed))
+    throw new Error(`--${name} must be an integer`);
   return parsed;
 }
 
 function eventFor(profile, session, sequence, timestamp) {
-  const path = profile === "lean"
-    ? `/benchmark/lean/${sequence % 4}`
-    : REALISTIC_PATHS[sequence % REALISTIC_PATHS.length];
+  const path =
+    profile === "lean"
+      ? `/benchmark/lean/${sequence % 4}`
+      : REALISTIC_PATHS[sequence % REALISTIC_PATHS.length];
   const base = {
     eventId: `${session.id}.${sequence.toString(36)}`,
     sessionId: session.id,
@@ -151,10 +160,20 @@ function eventFor(profile, session, sequence, timestamp) {
   if (profile === "feature") {
     const step = sequence % 3;
     if (step === 0) {
-      return { ...base, type: "pageview", path: "/", affiliateSlug: "creator-club" };
+      return {
+        ...base,
+        type: "pageview",
+        path: "/",
+        affiliateSlug: "creator-club",
+      };
     }
     if (step === 1) {
-      return { ...base, type: "pageview", path: "/pricing", affiliateSlug: "creator-club" };
+      return {
+        ...base,
+        type: "pageview",
+        path: "/pricing",
+        affiliateSlug: "creator-club",
+      };
     }
     return {
       ...base,
@@ -172,7 +191,10 @@ function eventFor(profile, session, sequence, timestamp) {
     return {
       ...base,
       type: "pageview",
-      referrer: sequence % 2 === 0 ? "https://www.google.com/search?q=rastro" : undefined,
+      referrer:
+        sequence % 2 === 0
+          ? "https://www.google.com/search?q=rastro"
+          : undefined,
     };
   }
   if (kind < 13) return { ...base, type: "click", target: "Get started" };
@@ -184,7 +206,11 @@ function eventFor(profile, session, sequence, timestamp) {
       properties: { placement: "hero", experiment: `variant-${sequence % 3}` },
     };
   }
-  return { ...base, type: "outbound", href: "https://github.com/amageweb/amage-rastro" };
+  return {
+    ...base,
+    type: "outbound",
+    href: "https://github.com/amageweb/amage-rastro",
+  };
 }
 
 function requestContext(session) {
@@ -200,15 +226,19 @@ function requestContext(session) {
 
 function percentile(sorted, fraction) {
   if (sorted.length === 0) return 0;
-  return sorted[Math.min(sorted.length - 1, Math.ceil(sorted.length * fraction) - 1)];
+  return sorted[
+    Math.min(sorted.length - 1, Math.ceil(sorted.length * fraction) - 1)
+  ];
 }
 
 function hasValidSessionTotals(value) {
-  return value !== null &&
+  return (
+    value !== null &&
     typeof value === "object" &&
     [value.requestedSessions, value.foundSessions, value.storedEvents].every(
       (total) => Number.isSafeInteger(total) && total >= 0,
-    );
+    )
+  );
 }
 
 async function main() {
@@ -249,15 +279,16 @@ async function main() {
   const durations = [];
 
   const buildRequest = (requestIndex) => {
-    const session = options.profile === "lean"
-      ? {
-          id: `bench-${runId}-${requestIndex}`,
-          visitorId: `visitor-${runId}-${requestIndex}`,
-          sequence: 0,
-          locationIndex: requestIndex % LOCATIONS.length,
-          userAgentIndex: requestIndex % USER_AGENTS.length,
-        }
-      : sessions[requestIndex % sessions.length];
+    const session =
+      options.profile === "lean"
+        ? {
+            id: `bench-${runId}-${requestIndex}`,
+            visitorId: `visitor-${runId}-${requestIndex}`,
+            sequence: 0,
+            locationIndex: requestIndex % LOCATIONS.length,
+            userAgentIndex: requestIndex % USER_AGENTS.length,
+          }
+        : sessions[requestIndex % sessions.length];
     const sequenceStart = session.sequence;
     session.sequence += options.batchSize;
     const now = Date.now();
@@ -276,18 +307,26 @@ async function main() {
     throw new Error("generated request exceeds the 64 KiB HTTP limit");
   }
   if (options.dryRun) {
-    process.stdout.write(`${JSON.stringify({
-      profile: options.profile,
-      batchSize: options.batchSize,
-      requestBytes: Buffer.byteLength(dryRequest.body),
-      heartbeats: dryRequest.heartbeats,
-      location: requestContext(sessions[0]),
-    }, null, 2)}\n`);
+    process.stdout.write(
+      `${JSON.stringify(
+        {
+          profile: options.profile,
+          batchSize: options.batchSize,
+          requestBytes: Buffer.byteLength(dryRequest.body),
+          heartbeats: dryRequest.heartbeats,
+          location: requestContext(sessions[0]),
+        },
+        null,
+        2,
+      )}\n`,
+    );
     return;
   }
   if (options.profile !== "lean") sessions[0].sequence = 0;
   if (!options.url || !options.siteId) {
-    throw new Error("--url and --site-id are required unless --dry-run is used");
+    throw new Error(
+      "--url and --site-id are required unless --dry-run is used",
+    );
   }
 
   const stopForSignal = (signal) => {
@@ -299,7 +338,9 @@ async function main() {
   process.once("SIGINT", stopForInterrupt);
   process.once("SIGTERM", stopForTermination);
 
-  const convex = options.convexUrl ? new ConvexHttpClient(options.convexUrl) : null;
+  const convex = options.convexUrl
+    ? new ConvexHttpClient(options.convexUrl)
+    : null;
   if (convex) {
     const preflight = await convex.query(reconcileSessionsQuery, {
       siteId: options.siteId,
@@ -333,7 +374,9 @@ async function main() {
       const request = buildRequest(requestIndex);
       const requestBytes = Buffer.byteLength(request.body);
       if (requestBytes > 64 * 1024) {
-        throw new Error(`generated request ${requestIndex} exceeds the 64 KiB HTTP limit`);
+        throw new Error(
+          `generated request ${requestIndex} exceeds the 64 KiB HTTP limit`,
+        );
       }
       sentBytes += requestBytes;
       sentEvents += options.batchSize;
@@ -368,7 +411,8 @@ async function main() {
             ![result.accepted, result.duplicates, result.rejected].every(
               (value) => Number.isSafeInteger(value) && value >= 0,
             ) ||
-            result.accepted + result.duplicates + result.rejected !== options.batchSize
+            result.accepted + result.duplicates + result.rejected !==
+              options.batchSize
           ) {
             throw new Error("response has invalid event accounting");
           }
@@ -384,7 +428,9 @@ async function main() {
       } catch (error) {
         failures += 1;
         failedEvents += options.batchSize;
-        recordError(`fetch:${error instanceof Error ? error.message : "unknown"}`);
+        recordError(
+          `fetch:${error instanceof Error ? error.message : "unknown"}`,
+        );
       } finally {
         durations.push(performance.now() - requestStartedAt);
         completedRequests += 1;
@@ -393,11 +439,14 @@ async function main() {
   };
 
   const progress = setInterval(() => {
-    const elapsedSeconds = Math.max(0.001, (performance.now() - startedAt) / 1_000);
+    const elapsedSeconds = Math.max(
+      0.001,
+      (performance.now() - startedAt) / 1_000,
+    );
     process.stderr.write(
       `[${options.label}] ${Math.round(elapsedSeconds)}s ` +
-      `${accepted} accepted ${Math.round(accepted / elapsedSeconds)} events/s ` +
-      `${failures} failures\n`,
+        `${accepted} accepted ${Math.round(accepted / elapsedSeconds)} events/s ` +
+        `${failures} failures\n`,
     );
   }, options.progressSeconds * 1_000);
   progress.unref();
@@ -405,14 +454,16 @@ async function main() {
   clearInterval(progress);
 
   const elapsedMs = performance.now() - startedAt;
-  terminationReason ??= performance.now() >= deadline ? "duration" : "completed";
+  terminationReason ??=
+    performance.now() >= deadline ? "duration" : "completed";
   process.removeListener("SIGINT", stopForInterrupt);
   process.removeListener("SIGTERM", stopForTermination);
   const durationCompleted = terminationReason === "duration";
   durations.sort((left, right) => left - right);
-  const expectedSessions = options.profile === "lean"
-    ? nextRequest
-    : Math.min(nextRequest, options.sessionCount);
+  const expectedSessions =
+    options.profile === "lean"
+      ? nextRequest
+      : Math.min(nextRequest, options.sessionCount);
   let sessionTotals = null;
   if (convex && expectedSessions > 0) {
     try {
@@ -490,7 +541,8 @@ async function main() {
     },
     concurrency: options.concurrency,
     batchSize: options.batchSize,
-    sessionPool: options.profile === "lean" ? "unique-per-request" : options.sessionCount,
+    sessionPool:
+      options.profile === "lean" ? "unique-per-request" : options.sessionCount,
     maximumRequests: Number.isFinite(options.maximumRequests)
       ? options.maximumRequests
       : null,
@@ -513,9 +565,10 @@ async function main() {
       estimatedEventsPerDay: durationCompleted
         ? Math.round((accepted * 86_400_000) / elapsedMs)
         : null,
-      estimatedStoredEventsPerDay: durationCompleted && reconciliationPassed
-        ? Math.round((storedEvents * 86_400_000) / elapsedMs)
-        : null,
+      estimatedStoredEventsPerDay:
+        durationCompleted && reconciliationPassed
+          ? Math.round((storedEvents * 86_400_000) / elapsedMs)
+          : null,
       certifiedEventsPerDay: certificationPassed
         ? Math.round((accepted * 86_400_000) / elapsedMs)
         : null,

package/src/component/_generated/api.ts

@@ -30,6 +30,7 @@ import type * as sites from "../sites.js";
 import type * as useragent from "../useragent.js";
 import type * as validators from "../validators.js";
 import type * as visitors from "../visitors.js";
+import type * as vitals from "../vitals.js";
 
 import type {
   ApiFromModules,
@@ -61,6 +62,7 @@ const fullApi: ApiFromModules<{
   useragent: typeof useragent;
   validators: typeof validators;
   visitors: typeof visitors;
+  vitals: typeof vitals;
 }> = anyApi as any;
 
 /**

package/src/component/_generated/component.ts

@@ -207,7 +207,9 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
               | "custom"
               | "conversion"
               | "heartbeat"
-              | "outbound";
+              | "outbound"
+              | "vital";
+            value?: number;
             visitorId: string;
           }>;
           origin: string;
@@ -303,7 +305,8 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
               | "conversions"
               | "goals"
               | "funnels"
-              | "affiliates";
+              | "affiliates"
+              | "vitals";
           }>;
           from: number;
           siteId: string;
@@ -691,7 +694,8 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
               | "custom"
               | "conversion"
               | "heartbeat"
-              | "outbound";
+              | "outbound"
+              | "vital";
             visitorId: string;
           }>;
           pageStatus?: "SplitRecommended" | "SplitRequired" | null;
@@ -739,11 +743,69 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             | "custom"
             | "conversion"
             | "heartbeat"
-            | "outbound";
+            | "outbound"
+            | "vital";
           visitorId: string;
         }>,
         Name
       >;
+      vitalsReport: FunctionReference<
+        "query",
+        "internal",
+        { from: number; siteId: string; to: number },
+        {
+          metadata: {
+            basis: "dailyRollup" | "boundedLegacy";
+            coverage: {
+              availableFrom: number | null;
+              availableThrough: number | null;
+              generation: number | null;
+              retainedBefore: number | null;
+              state: "complete" | "partial" | "retained" | "unavailable";
+            };
+            range: {
+              boundary: "inclusive";
+              from: number;
+              timezone: "UTC";
+              to: number;
+            };
+          };
+          metrics: Array<{
+            average: number;
+            count: number;
+            devices: Array<{
+              average: number;
+              count: number;
+              device: string;
+              good: number;
+              needsImprovement: number;
+              p75: number;
+              poor: number;
+            }>;
+            good: number;
+            metric: "LCP" | "CLS" | "INP" | "FCP" | "TTFB";
+            needsImprovement: number;
+            p75: number;
+            pages: Array<{
+              average: number;
+              count: number;
+              good: number;
+              needsImprovement: number;
+              p75: number;
+              page: string;
+              poor: number;
+            }>;
+            poor: number;
+            timeSeries: Array<{
+              count: number;
+              p75: number;
+              timestamp: number;
+            }>;
+          }>;
+          truncated: boolean;
+        },
+        Name
+      >;
     };
     retention: {
       cleanup: FunctionReference<
@@ -765,6 +827,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             | "goalRollups"
             | "funnelRollups"
             | "affiliateRollups"
+            | "vitalRollups"
             | "attributions"
             | "liveSessions"
             | "ingestWindows"
@@ -799,6 +862,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             | "goalRollups"
             | "funnelRollups"
             | "affiliateRollups"
+            | "vitalRollups"
             | "attributions"
             | "liveSessions"
             | "ingestWindows"
@@ -844,6 +908,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
               | "goalRollups"
               | "funnelRollups"
               | "affiliateRollups"
+              | "vitalRollups"
               | "attributions"
               | "liveSessions"
               | "ingestWindows"

package/src/component/affiliates.ts

@@ -22,16 +22,27 @@ export const upsert = mutation({
   },
   returns: v.id("affiliates"),
   handler: async (ctx, args) => {
-    if (!(await ctx.db.get("sites", args.siteId))) fail("NOT_FOUND", "site not found");
-    if (!Number.isSafeInteger(args.commissionBps) || args.commissionBps < 0 || args.commissionBps > 10_000) {
-      fail("INVALID_ARGUMENT", "commissionBps must be an integer between 0 and 10000");
+    if (!(await ctx.db.get("sites", args.siteId)))
+      fail("NOT_FOUND", "site not found");
+    if (
+      !Number.isSafeInteger(args.commissionBps) ||
+      args.commissionBps < 0 ||
+      args.commissionBps > 10_000
+    ) {
+      fail(
+        "INVALID_ARGUMENT",
+        "commissionBps must be an integer between 0 and 10000",
+      );
     }
     if (
       !Number.isSafeInteger(args.attributionWindowDays) ||
       args.attributionWindowDays < 1 ||
       args.attributionWindowDays > 365
     ) {
-      fail("INVALID_ARGUMENT", "attributionWindowDays must be an integer between 1 and 365");
+      fail(
+        "INVALID_ARGUMENT",
+        "attributionWindowDays must be an integer between 1 and 365",
+      );
     }
     let slug: string;
     try {
@@ -52,7 +63,11 @@ export const upsert = mutation({
       )
       .unique();
     const affiliateId = args.affiliateId ?? existingBySlug?._id;
-    if (args.affiliateId && existingBySlug && existingBySlug._id !== args.affiliateId) {
+    if (
+      args.affiliateId &&
+      existingBySlug &&
+      existingBySlug._id !== args.affiliateId
+    ) {
       fail("CONFLICT", "another affiliate already uses this slug");
     }
     const now = Date.now();

package/src/component/cardinality.ts

@@ -60,13 +60,14 @@ export function unionVisitorSketches(
 export function estimateVisitors(sketch: VisitorSketch): number {
   const registers = checkedRegisters(sketch);
   const count = registers.length;
-  const alpha = count === 16
-    ? 0.673
-    : count === 32
-      ? 0.697
-      : count === 64
-        ? 0.709
-        : 0.7213 / (1 + 1.079 / count);
+  const alpha =
+    count === 16
+      ? 0.673
+      : count === 32
+        ? 0.697
+        : count === 64
+          ? 0.709
+          : 0.7213 / (1 + 1.079 / count);
   let denominator = 0;
   let empty = 0;
   for (const register of registers) {

package/src/component/constants.ts

@@ -7,8 +7,9 @@ export const MAX_BYTES_PER_SESSION_WINDOW = 256 * 1024;
 export const SITE_INGEST_SHARDS = 4_096;
 export const MAX_SITE_EVENTS_PER_SHARD_WINDOW = 300;
 export const MAX_SITE_BYTES_PER_SHARD_WINDOW = 512 * 1024;
-export const LIVE_SESSION_TTL_MS = 60_000;
+export const LIVE_SESSION_TTL_MS = 5 * 60_000;
 export const LIVE_SWEEP_INTERVAL_MS = 5_000;
+export const CLOCK_SKEW_TOLERANCE_MS = 30_000;
 export const AGGREGATE_SHARDS = 128;
 export const HOURLY_AGGREGATE_SHARDS = 256;
 export const SECONDARY_AGGREGATE_SHARDS = 16;
@@ -36,6 +37,17 @@ export const FEATURE_REPORT_DOCUMENT_RESERVE = 500;
 export const REPORT_ROLLUP_SHARDS = 2;
 export const ROLLUP_SAFETY_DELAY_MS = 5 * 60_000;
 export const RETENTION_LEASE_MS = 60_000;
+// Shared Web Vitals histogram edges. Every Google rating threshold (LCP
+// 2500/4000, CLS×1000 100/250, INP 200/500, FCP 1800/3000, TTFB 800/1800) is
+// an edge, so rating counts stay exact while one layout serves all metrics.
+export const VITAL_HISTOGRAM_EDGES = [
+  100, 200, 250, 300, 500, 800, 1_000, 1_200, 1_800, 2_500, 3_000, 4_000, 5_000,
+  7_500, 10_000,
+];
+export const MAX_VITAL_VALUE = 600_000;
+export const VITAL_PAGE_SLOTS = 48;
+export const MAX_VITALS_REPORT_ROWS = 5_000;
+export const VITALS_REPORT_PAGE_LIMIT = 12;
 
 export const DAY_MS = 86_400_000;
 export const HOUR_MS = 3_600_000;

package/src/component/diagnostics.ts

@@ -29,7 +29,8 @@ export const sessionEventTotals = query({
     try {
       sessionIds = args.sessionIds.map((sessionId) => {
         const sanitized = sanitizeOpaqueId(sessionId, "sessionId");
-        if (sanitized !== sessionId) throw new Error("sessionId is not canonical");
+        if (sanitized !== sessionId)
+          throw new Error("sessionId is not canonical");
         return sanitized;
       });
     } catch (error) {
@@ -49,7 +50,7 @@ export const sessionEventTotals = query({
           .withIndex("by_siteId_and_sessionId", (range) =>
             range.eq("siteId", args.siteId).eq("sessionId", sessionId),
           )
-          .unique()
+          .unique(),
       ),
     );
     return {