@opengeni/api-router 0.30.1 → 1.0.0

package/src/routes/insights-response-cache.ts

@@ -0,0 +1,83 @@
+import { createHmac, randomBytes } from "node:crypto";
+import { HTTPException } from "hono/http-exception";
+
+export const INSIGHTS_RESPONSE_TTL_MS = 60_000;
+const MAX_ENTRIES = 128,
+  MAX_BYTES = 8 * 1024 * 1024,
+  MAX_ENTRY_BYTES = 1024 * 1024;
+
+/** Ephemeral keyed digest: raw credentials never become retained map keys or logs. */
+export function createInsightsCredentialPartition() {
+  const secret = randomBytes(32);
+  return (authorization: string | undefined, cookie: string | undefined) =>
+    createHmac("sha256", secret)
+      .update(JSON.stringify([authorization ?? null, cookie ?? null]))
+      .digest("hex");
+}
+
+export function createInsightsResponseCache(clock: () => number = () => Date.now()) {
+  const entries = new Map<
+    string,
+    { json: string; fence: string; expiresAt: number; bytes: number }
+  >();
+  let bytes = 0;
+  const remove = (key: string) => {
+    const entry = entries.get(key);
+    if (entry) {
+      bytes -= entry.bytes;
+      entries.delete(key);
+    }
+  };
+  return {
+    get<T>(key: string, fence: string): T | null {
+      const entry = entries.get(key);
+      if (!entry) return null;
+      if (entry.expiresAt <= clock() || entry.fence !== fence) {
+        remove(key);
+        return null;
+      }
+      // The TTL is never extended by a hit, and callers receive isolated objects.
+      return JSON.parse(entry.json) as T;
+    },
+    put(key: string, fence: string, value: unknown): void {
+      const json = JSON.stringify(value),
+        size = Buffer.byteLength(json);
+      if (size > MAX_ENTRY_BYTES) return;
+      for (const [existingKey, entry] of entries)
+        if (entry.expiresAt <= clock()) remove(existingKey);
+      remove(key);
+      for (const existingKey of entries.keys()) {
+        if (entries.size < MAX_ENTRIES && bytes + size <= MAX_BYTES) break;
+        remove(existingKey);
+      }
+      entries.set(key, { json, fence, expiresAt: clock() + INSIGHTS_RESPONSE_TTL_MS, bytes: size });
+      bytes += size;
+    },
+    get size() {
+      return entries.size;
+    },
+  };
+}
+
+/** Match existing bounded cause-chain PostgreSQL timeout handling; never expose SQL. */
+export async function insightsWithFriendlyTimeout<T>(read: () => Promise<T>): Promise<T> {
+  try {
+    return await read();
+  } catch (error) {
+    let current = error;
+    for (let depth = 0; depth < 4 && current && typeof current === "object"; depth++) {
+      const candidate = current as { code?: unknown; message?: unknown; cause?: unknown };
+      if (
+        candidate.code === "57014" ||
+        (typeof candidate.message === "string" &&
+          candidate.message.toLowerCase().includes("statement timeout"))
+      ) {
+        throw new HTTPException(408, {
+          message: "This range has too much data right now. Try a shorter range.",
+        });
+      }
+      current = candidate.cause;
+    }
+    throw error;
+  }
+}

package/src/routes/insights-usage.ts

@@ -0,0 +1,345 @@
+import {
+  InsightsCallsResponse,
+  InsightsUsageResponse,
+  OrganizationInsightsCallsQuery,
+  OrganizationInsightsUsageQuery,
+  WorkspaceInsightsCallsQuery,
+  WorkspaceInsightsUsageQuery,
+} from "@opengeni/contracts/insights-usage";
+import type { AccessContext } from "@opengeni/contracts";
+import {
+  accountScopedApiKeyWorkspaceAuthority,
+  getInsightsUsage,
+  hasPermission,
+  listInsightsCalls,
+  requireAccessContext,
+  requireAccessGrant,
+  type ApiRouteDeps,
+  type InsightsQueryScope,
+} from "@opengeni/core";
+import {
+  currentSessionRlsActorIdentityKey,
+  InvalidInsightsCallsCursorError,
+  readInsightsResponseCacheFence,
+} from "@opengeni/db";
+import type { Context, Hono } from "hono";
+import { createHash } from "node:crypto";
+import { HTTPException } from "hono/http-exception";
+import { requireSelectedAccount, withBillingUsageActor } from "./billing";
+import { createInFlightCoalescer } from "./insights";
+import {
+  createInsightsCredentialPartition,
+  createInsightsResponseCache,
+  insightsWithFriendlyTimeout,
+} from "./insights-response-cache";
+
+/** Keep repeated filters, but reject repeated scalar options in the strict schema. */
+export function insightsQueryParameters(
+  query: Record<string, string[]>,
+): Record<string, string | string[]> {
+  return Object.fromEntries(
+    Object.entries(query).map(([key, values]) => [key, values.length === 1 ? values[0]! : values]),
+  );
+}
+
+/** Frozen interim capabilities: a newer additive contract must not silently widen a raw query. */
+export function insightsRawQuerySupported(
+  query: Record<string, unknown>,
+  organization: boolean,
+  calls: boolean,
+): boolean {
+  const keys = new Set([
+    "range",
+    "provider",
+    "model",
+    "payer",
+    "projectId",
+    "person",
+    "rootSessionId",
+    "scheduleId",
+    "limit",
+    ...(organization ? ["workspaceId"] : []),
+    ...(calls ? ["cursor"] : ["groupBy", "seriesGroups"]),
+  ]);
+  if (Object.keys(query).some((key) => !keys.has(key))) return false;
+  if (
+    query.range !== undefined &&
+    !new Set(["today", "week", "month", "30d", "90d", "ytd"]).has(String(query.range))
+  )
+    return false;
+  return (
+    query.groupBy === undefined ||
+    new Set([
+      "model",
+      "provider",
+      "payer",
+      "project",
+      "rootSession",
+      "person",
+      "schedule",
+      ...(organization ? ["workspace"] : []),
+    ]).has(String(query.groupBy))
+  );
+}
+
+function organizationCacheAuthority(context: AccessContext, accountId: string) {
+  const key = accountScopedApiKeyWorkspaceAuthority(context);
+  return [
+    context.subjectId,
+    context.accountGrants
+      .filter((g) => g.accountId === accountId)
+      .map((g) => [g.subjectId, g.role, [...g.permissions].sort()]),
+    context.workspaceGrants
+      .filter((g) => g.accountId === accountId)
+      .map((g) => [g.workspaceId, g.subjectId, g.permissionMode, [...g.permissions].sort()])
+      .sort(),
+    key
+      ? [key.accountId, key.permissionMode, [...key.permissions].sort(), key.workspaceScope]
+      : null,
+  ];
+}
+
+function rawUsageResponse(response: Awaited<ReturnType<typeof getInsightsUsage>>) {
+  const parsed = InsightsUsageResponse.parse(response);
+  // A newer contract can supply an additive default. Absence is a capability
+  // signal, so this raw implementation must not manufacture source support.
+  if (!Object.hasOwn(response.facets, "sources")) Reflect.deleteProperty(parsed.facets, "sources");
+  return parsed;
+}
+
+/** The actor and its canonical detail authority are part of every sharing key. */
+export function insightsUsageCoalesceKey(
+  scope: InsightsQueryScope,
+  query: unknown,
+  actor: string | null,
+): string {
+  return JSON.stringify([
+    scope.accountId,
+    scope.workspaceId,
+    [...(scope.detailsWorkspaceIds ?? [])].sort(),
+    scope.detailsSharedWorkspaces === true,
+    query,
+    actor,
+  ]);
+}
+
+/** Reuse canonical read grants, never infer session access from billing authority. */
+export function organizationInsightsScope(
+  context: AccessContext,
+  accountId: string,
+): InsightsQueryScope {
+  const authority = accountScopedApiKeyWorkspaceAuthority(context);
+  if (authority?.accountId === accountId) {
+    const readable = hasPermission(
+      authority.permissions,
+      "sessions:read",
+      authority.permissionMode,
+    );
+    return {
+      accountId,
+      workspaceId: null,
+      detailsWorkspaceIds:
+        readable && authority.workspaceScope.kind === "selected"
+          ? [...authority.workspaceScope.workspaceIds].sort()
+          : [],
+      detailsSharedWorkspaces: readable && authority.workspaceScope.kind === "all",
+    };
+  }
+  return {
+    accountId,
+    workspaceId: null,
+    detailsWorkspaceIds: [
+      ...new Set(
+        context.workspaceGrants
+          .filter(
+            (grant) =>
+              grant.accountId === accountId &&
+              grant.subjectId === context.subjectId &&
+              hasPermission(grant.permissions, "sessions:read", grant.permissionMode),
+          )
+          .map((grant) => grant.workspaceId),
+      ),
+    ].sort(),
+    detailsSharedWorkspaces: false,
+  };
+}
+
+async function callsWithValidation(
+  read: () => Promise<Awaited<ReturnType<typeof listInsightsCalls>>>,
+) {
+  try {
+    return await read();
+  } catch (error) {
+    if (error instanceof InvalidInsightsCallsCursorError)
+      throw new HTTPException(400, { message: "invalid Insights calls cursor" });
+    throw error;
+  }
+}
+
+export function registerInsightsUsageRoutes(app: Hono, deps: ApiRouteDeps): void {
+  const usage = createInFlightCoalescer<InsightsUsageResponse>();
+  const calls = createInFlightCoalescer<InsightsCallsResponse>();
+  const cache = createInsightsResponseCache();
+  const credentialPartition = createInsightsCredentialPartition();
+  async function cached<T>(
+    c: Context,
+    kind: "usage" | "calls",
+    scope: InsightsQueryScope,
+    query: object,
+    authority: unknown,
+    coalescer: { run(key: string, work: () => Promise<T>): Promise<T> },
+    read: () => Promise<T>,
+  ): Promise<T> {
+    // This runs only after this request's normal authentication and scope checks.
+    const normalized = Object.fromEntries(
+      Object.entries(query)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([key, value]) => [key, Array.isArray(value) ? [...new Set(value)].sort() : value]),
+    );
+    const key = createHash("sha256")
+      .update(
+        JSON.stringify([
+          kind,
+          authority,
+          insightsUsageCoalesceKey(scope, normalized, currentSessionRlsActorIdentityKey()),
+          credentialPartition(c.req.header("authorization"), c.req.header("cookie")),
+          new Date().toISOString().slice(0, 10),
+        ]),
+      )
+      .digest("hex");
+    const fence = await readInsightsResponseCacheFence(deps.db, scope);
+    if (fence !== null) {
+      const hit = cache.get<T>(key, fence);
+      if (hit !== null) return hit;
+    }
+    return await coalescer.run(`${key}:${fence ?? "uncached"}`, async () => {
+      const response = await insightsWithFriendlyTimeout(read);
+      // Store validated successes only, and only if metadata remained stable.
+      if (fence !== null && fence === (await readInsightsResponseCacheFence(deps.db, scope)))
+        cache.put(key, fence, response);
+      return response;
+    });
+  }
+
+  app.get("/v1/workspaces/:workspaceId/insights/usage", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "workspace:admin");
+    const query = insightsQueryParameters(c.req.queries());
+    if (!insightsRawQuerySupported(query, false, false))
+      throw new HTTPException(400, { message: "unsupported interim Insights query" });
+    const parsed = WorkspaceInsightsUsageQuery.safeParse(query);
+    if (!parsed.success) throw new HTTPException(400, { message: "invalid Insights usage query" });
+    const scope = {
+      accountId: grant.accountId,
+      workspaceId,
+      detailsWorkspaceIds: hasPermission(grant.permissions, "sessions:read", grant.permissionMode)
+        ? [workspaceId]
+        : [],
+    };
+    // The API's workspace middleware already binds/revalidates this grant's RLS actor.
+    const response = await cached(
+      c,
+      "usage",
+      scope,
+      parsed.data,
+      [grant.subjectId, grant.permissionMode, [...grant.permissions].sort()],
+      usage,
+      async () =>
+        rawUsageResponse(await getInsightsUsage(deps.db, { ...scope, query: parsed.data })),
+    );
+    c.header("cache-control", "private, no-store");
+    c.header("x-opengeni-insights-max-staleness-seconds", "60");
+    return c.json(response);
+  });
+
+  app.get("/v1/workspaces/:workspaceId/insights/calls", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "workspace:admin");
+    const query = insightsQueryParameters(c.req.queries());
+    if (!insightsRawQuerySupported(query, false, true))
+      throw new HTTPException(400, { message: "unsupported interim Insights query" });
+    const parsed = WorkspaceInsightsCallsQuery.safeParse(query);
+    if (!parsed.success) throw new HTTPException(400, { message: "invalid Insights calls query" });
+    const scope = {
+      accountId: grant.accountId,
+      workspaceId,
+      detailsWorkspaceIds: hasPermission(grant.permissions, "sessions:read", grant.permissionMode)
+        ? [workspaceId]
+        : [],
+    };
+    const response = await cached(
+      c,
+      "calls",
+      scope,
+      parsed.data,
+      [grant.subjectId, grant.permissionMode, [...grant.permissions].sort()],
+      calls,
+      async () =>
+        InsightsCallsResponse.parse(
+          await callsWithValidation(() =>
+            listInsightsCalls(deps.db, { ...scope, query: parsed.data }),
+          ),
+        ),
+    );
+    c.header("cache-control", "private, no-store");
+    c.header("x-opengeni-insights-max-staleness-seconds", "60");
+    return c.json(response);
+  });
+
+  app.get("/v1/organizations/:accountId/insights/usage", async (c) => {
+    const context = await requireAccessContext(c, deps);
+    const accountId = requireSelectedAccount(context, c.req.param("accountId"), "billing:read");
+    const query = insightsQueryParameters(c.req.queries());
+    if (!insightsRawQuerySupported(query, true, false))
+      throw new HTTPException(400, { message: "unsupported interim Insights query" });
+    const parsed = OrganizationInsightsUsageQuery.safeParse(query);
+    if (!parsed.success) throw new HTTPException(400, { message: "invalid Insights usage query" });
+    const scope = organizationInsightsScope(context, accountId);
+    const response = await withBillingUsageActor(deps, context, accountId, () =>
+      cached(
+        c,
+        "usage",
+        scope,
+        parsed.data,
+        organizationCacheAuthority(context, accountId),
+        usage,
+        async () =>
+          rawUsageResponse(await getInsightsUsage(deps.db, { ...scope, query: parsed.data })),
+      ),
+    );
+    c.header("cache-control", "private, no-store");
+    c.header("x-opengeni-insights-max-staleness-seconds", "60");
+    return c.json(response);
+  });
+
+  app.get("/v1/organizations/:accountId/insights/calls", async (c) => {
+    const context = await requireAccessContext(c, deps);
+    const accountId = requireSelectedAccount(context, c.req.param("accountId"), "billing:read");
+    const query = insightsQueryParameters(c.req.queries());
+    if (!insightsRawQuerySupported(query, true, true))
+      throw new HTTPException(400, { message: "unsupported interim Insights query" });
+    const parsed = OrganizationInsightsCallsQuery.safeParse(query);
+    if (!parsed.success) throw new HTTPException(400, { message: "invalid Insights calls query" });
+    const scope = organizationInsightsScope(context, accountId);
+    // Call readers intersect these canonical grants with current actor visibility.
+    const response = await withBillingUsageActor(deps, context, accountId, () =>
+      cached(
+        c,
+        "calls",
+        scope,
+        parsed.data,
+        organizationCacheAuthority(context, accountId),
+        calls,
+        async () =>
+          InsightsCallsResponse.parse(
+            await callsWithValidation(() =>
+              listInsightsCalls(deps.db, { ...scope, query: parsed.data }),
+            ),
+          ),
+      ),
+    );
+    c.header("cache-control", "private, no-store");
+    c.header("x-opengeni-insights-max-staleness-seconds", "60");
+    return c.json(response);
+  });
+}

package/src/routes/insights.ts

@@ -1,30 +1,164 @@
 import { InsightsRange, WorkspaceInsightsResponse } from "@opengeni/contracts";
-import { getWorkspaceInsights, requireAccessGrant, type ApiRouteDeps } from "@opengeni/core";
+import {
+  getWorkspaceInsights,
+  measureInsightsPhase,
+  workspaceInsightsPhaseMetricObserver,
+  normalizeWorkspaceInsightsFilter,
+  normalizeWorkspaceInsightsSessionScope,
+  requireAccessGrant,
+  WorkspaceInsightsFilterValidationError,
+  type ApiRouteDeps,
+  type WorkspaceInsightsFilterField,
+} from "@opengeni/core";
+import { currentSessionRlsActorIdentityKey } from "@opengeni/db";
+import { workspaceInsightsMetricObserver } from "@opengeni/observability";
 import type { Hono } from "hono";
 import { HTTPException } from "hono/http-exception";
 
+export function normalizeWorkspaceInsightsQueryFilter(
+  value: string | null | undefined,
+  field: WorkspaceInsightsFilterField,
+): string | null {
+  try {
+    return field === "rootSessionId" || field === "sessionId"
+      ? normalizeWorkspaceInsightsSessionScope(value, field)
+      : normalizeWorkspaceInsightsFilter(value, field);
+  } catch (error) {
+    if (error instanceof WorkspaceInsightsFilterValidationError) {
+      throw new HTTPException(400, { message: error.message });
+    }
+    throw error;
+  }
+}
+
+/**
+ * Share one in-flight computation between identical concurrent callers.
+ *
+ * A reload, a second tab, or a retried fetch joins the rollup already running
+ * instead of starting another multi-second aggregate on the database.
+ * Authorization and filter validation still run per request before a caller
+ * may join; the map only ever holds running work. The caller supplies the
+ * complete sharing key, which must identify everything the result depends on.
+ */
+export function createInFlightCoalescer<T>(): {
+  run: (key: string, work: () => Promise<T>) => Promise<T>;
+  readonly size: number;
+} {
+  const inFlight = new Map<string, Promise<T>>();
+  return {
+    run(key, work) {
+      const pending = inFlight.get(key);
+      if (pending) return pending;
+      const started: Promise<T> = work().finally(() => {
+        if (inFlight.get(key) === started) inFlight.delete(key);
+      });
+      inFlight.set(key, started);
+      return started;
+    },
+    get size() {
+      return inFlight.size;
+    },
+  };
+}
+
+/**
+ * Insights rows are filtered by the database RLS actor (private sessions are
+ * visible only to their owner), so two administrators of one workspace can
+ * legitimately receive different responses. The actor identity is part of
+ * the key; requests share work only when every visibility input is equal.
+ */
+export function workspaceInsightsCoalesceKey(input: {
+  workspaceId: string;
+  range: string;
+  provider: string | null;
+  model: string | null;
+  rootSessionId?: string | null;
+  sessionId?: string | null;
+  rlsActor: string | null;
+}): string {
+  return JSON.stringify([
+    input.workspaceId,
+    input.range,
+    input.provider,
+    input.model,
+    input.rootSessionId ?? null,
+    input.sessionId ?? null,
+    input.rlsActor,
+  ]);
+}
+
 export function registerInsightsRoutes(app: Hono, deps: ApiRouteDeps): void {
+  const observeRequest = workspaceInsightsMetricObserver(deps.observability);
+  const observePhase = workspaceInsightsPhaseMetricObserver(deps.observability);
+  const coalesce = createInFlightCoalescer<Awaited<ReturnType<typeof getWorkspaceInsights>>>();
   app.get("/v1/workspaces/:workspaceId/insights", async (c) => {
-    const workspaceId = c.req.param("workspaceId");
-    await requireAccessGrant(c, deps, workspaceId, "workspace:admin");
-
+    const startedAtMs = performance.now();
     const rangeRaw = c.req.query("range") ?? "week";
-    const rangeParsed = InsightsRange.safeParse(rangeRaw);
-    if (!rangeParsed.success) {
-      throw new HTTPException(400, {
-        message: "range must be one of today|week|month|ytd",
+    const providerRaw = c.req.query("provider");
+    const modelRaw = c.req.query("model");
+    const rootSessionIdRaw = c.req.query("rootSessionId");
+    const sessionIdRaw = c.req.query("sessionId");
+    let provider: string | null = null;
+    let model: string | null = null;
+    let outcome = "failed";
+
+    try {
+      const workspaceId = c.req.param("workspaceId");
+      await measureInsightsPhase(observePhase, "auth", () =>
+        requireAccessGrant(c, deps, workspaceId, "workspace:admin"),
+      );
+
+      const rangeParsed = InsightsRange.safeParse(rangeRaw);
+      if (!rangeParsed.success) {
+        throw new HTTPException(400, {
+          message: "range must be one of today|week|month|ytd",
+        });
+      }
+      provider = normalizeWorkspaceInsightsQueryFilter(providerRaw, "provider");
+      model = normalizeWorkspaceInsightsQueryFilter(modelRaw, "model");
+      const rootSessionId = normalizeWorkspaceInsightsQueryFilter(
+        rootSessionIdRaw,
+        "rootSessionId",
+      );
+      const sessionId = normalizeWorkspaceInsightsQueryFilter(sessionIdRaw, "sessionId");
+
+      const response = await coalesce.run(
+        workspaceInsightsCoalesceKey({
+          workspaceId,
+          range: rangeParsed.data,
+          provider,
+          model,
+          rootSessionId,
+          sessionId,
+          rlsActor: currentSessionRlsActorIdentityKey(),
+        }),
+        () =>
+          getWorkspaceInsights(
+            deps.db,
+            deps.settings,
+            {
+              workspaceId,
+              range: rangeParsed.data,
+              provider,
+              model,
+              rootSessionId,
+              sessionId,
+            },
+            observePhase,
+          ),
+      );
+      c.header("cache-control", "private, no-store");
+      const result = c.json(WorkspaceInsightsResponse.parse(response));
+      outcome = "completed";
+      return result;
+    } finally {
+      observeRequest({
+        range: rangeRaw,
+        providerFiltered: provider !== null,
+        modelFiltered: model !== null,
+        outcome,
+        durationMs: performance.now() - startedAtMs,
       });
     }
-    const provider = c.req.query("provider");
-    const model = c.req.query("model");
-
-    const response = await getWorkspaceInsights(deps.db, deps.settings, {
-      workspaceId,
-      range: rangeParsed.data,
-      provider: provider && provider !== "all" ? provider : null,
-      model: model && model !== "all" ? model : null,
-    });
-    c.header("cache-control", "private, no-store");
-    return c.json(WorkspaceInsightsResponse.parse(response));
   });
 }