@k2b/cloud 0.43.0 → 0.45.0

package/src/services/app-details.ts

@@ -0,0 +1,224 @@
+import { type SQL, sql } from "bun";
+import { resolveCapabilityManifestPresentation } from "../_internal/capabilities";
+import { getApp, listCapabilities } from "../_internal/registry";
+import {
+  APP_DETAILS_FAILED_LIMIT,
+  APP_DETAILS_LIST_LIMIT,
+  APP_SUBSCRIPTION_NEW_WINDOW_MS,
+  type AppDetails,
+} from "../contracts/app-details";
+import { type NotificationDefinitionPresentationCatalog, resolveNotificationDefinitionPresentation } from "../contracts/notification-types";
+import type { AppRegistryEntry, CapabilityRegistryEntry } from "../contracts/registry";
+import type { RequestAuthority } from "../server/middleware/auth";
+import { resolveAppIdentityPresentation } from "../shared/app-presentation";
+import { AppAccessManagementError, appAccessGrantCounts, canRepairAppAccess } from "./app-access-management";
+import type { StoredDeclaration } from "./app-events/declarations";
+
+type SubscriptionRow = {
+  id: string;
+  event_type: string;
+  version: number;
+  state: AppDetails["hears"][number]["state"];
+  reason: string | null;
+  first_seen_at: Date;
+  is_new: boolean;
+  publisher_app_id: string | null;
+  title: string | null;
+  total: number;
+};
+type NotificationRow = {
+  id: string;
+  kind: string;
+  label: string;
+  description: string;
+  presentation: NotificationDefinitionPresentationCatalog | null;
+  recipient_kind: "user" | "email";
+  required_channels: string[];
+  recommended_channels: string[];
+  excluded_channels: string[];
+  excluded_reason: string | null;
+  total: number;
+};
+type Dependencies = {
+  db?: SQL;
+  getApp?: (appId: string) => Promise<AppRegistryEntry | null>;
+  capabilities?: () => Promise<CapabilityRegistryEntry[]>;
+  grantCounts?: typeof appAccessGrantCounts;
+};
+
+/** Core-owned administration read shared by SSR and HTTP; app access is not administrator authority. */
+export function createAppDetailsService(dependencies: Dependencies = {}) {
+  const db = dependencies.db ?? sql;
+  return async (appId: string, options: { authority: RequestAuthority; locale?: string }): Promise<AppDetails | null> => {
+    if (!canRepairAppAccess(options.authority))
+      throw new AppAccessManagementError("FORBIDDEN", "Cloud administration authority is required.");
+    const locale = options.locale ?? "en";
+    const [app, known] = await Promise.all([
+      (dependencies.getApp ?? getApp)(appId),
+      db<{ known: boolean }[]>`
+        SELECT EXISTS (
+          SELECT FROM events.app_manifests WHERE app_id = ${appId}
+          UNION ALL SELECT FROM events.app_declarations WHERE app_id = ${appId}
+          UNION ALL SELECT FROM events.app_subscriptions WHERE app_id = ${appId}
+          UNION ALL SELECT FROM notifications.definitions WHERE app_id = ${appId}
+          UNION ALL SELECT FROM auth.app_access_state WHERE app_id = ${appId}
+          UNION ALL SELECT FROM auth.app_access WHERE app_id = ${appId}
+        ) AS known
+      `,
+    ]);
+    if (!app && !known[0]?.known) return null;
+
+    const [capabilities, declarations, subscriptions, definitions, grantCounts] = await Promise.all([
+      (dependencies.capabilities ?? listCapabilities)(),
+      db<(StoredDeclaration & { subscriber_count: number; total: number })[]>`
+        SELECT declaration.*, count(*) OVER()::int AS total,
+          (SELECT count(*)::int FROM events.app_subscriptions subscription
+            WHERE subscription.event_type = declaration.type AND subscription.version = declaration.version
+              AND subscription.state <> 'cancelled') AS subscriber_count
+        FROM events.app_declarations declaration
+        WHERE declaration.app_id = ${appId} AND declaration.retired_at IS NULL
+        ORDER BY declaration.type, declaration.version
+        LIMIT ${APP_DETAILS_LIST_LIMIT}
+      `,
+      db<SubscriptionRow[]>`
+        SELECT subscription.id, subscription.event_type, subscription.version, subscription.state,
+          subscription.reason, subscription.first_seen_at, declaration.app_id AS publisher_app_id,
+          subscription.first_seen_at >= now() - ${APP_SUBSCRIPTION_NEW_WINDOW_MS} * interval '1 millisecond' AS is_new,
+          declaration.title, count(*) OVER()::int AS total
+        FROM events.app_subscriptions subscription
+        LEFT JOIN events.app_declarations declaration
+          ON declaration.type = subscription.event_type AND declaration.version = subscription.version
+        WHERE subscription.app_id = ${appId}
+        ORDER BY subscription.first_seen_at DESC, subscription.id
+        LIMIT ${APP_DETAILS_LIST_LIMIT}
+      `,
+      db<NotificationRow[]>`
+        SELECT id, kind, label, description, presentation, recipient_kind,
+          required_channels, recommended_channels, excluded_channels, excluded_reason, count(*) OVER()::int AS total
+        FROM notifications.definitions
+        WHERE app_id = ${appId} AND active = true
+        ORDER BY id
+        LIMIT ${APP_DETAILS_LIST_LIMIT}
+      `,
+      app?.access?.kind === "grants"
+        ? (dependencies.grantCounts ?? appAccessGrantCounts)(options.authority, [app])
+        : Promise.resolve(new Map<string, number>()),
+    ]);
+    const presentations = new Map<string, { title: string; description: string }>(
+      capabilities.flatMap((entry) =>
+        (resolveCapabilityManifestPresentation(entry.manifest, entry.presentation, locale).events ?? []).map(
+          (event) => [`${entry.appId}.${event.localId}@${event.version}`, event] as const,
+        ),
+      ),
+    );
+    const subscriptionIds = subscriptions.map((subscription) => subscription.id);
+    const [deliveryCounts, failedDeliveries] = subscriptionIds.length
+      ? await Promise.all([
+          db<{ subscription_id: string; state: keyof AppDetails["hears"][number]["counts"]; count: number }[]>`
+            SELECT subscription_id, state, count(*)::int AS count
+            FROM events.app_deliveries
+            WHERE subscription_id IN ${db(subscriptionIds)}
+            GROUP BY subscription_id, state
+          `,
+          db<
+            {
+              subscription_id: string;
+              id: string;
+              eventId: string;
+              code: string | null;
+              lastError: string | null;
+              attempts: number;
+              lastAttemptAt: Date | null;
+            }[]
+          >`
+            SELECT subscription.id AS subscription_id, failed.*
+            FROM events.app_subscriptions subscription
+            CROSS JOIN LATERAL (
+              SELECT id, event_id AS "eventId", code, left(last_error, 1000) AS "lastError",
+                attempts, last_attempt_at AS "lastAttemptAt"
+              FROM events.app_deliveries
+              WHERE subscription_id = subscription.id AND state = 'failed'
+              ORDER BY last_attempt_at DESC NULLS LAST, seq DESC
+              LIMIT ${APP_DETAILS_FAILED_LIMIT}
+            ) failed
+            WHERE subscription.id IN ${db(subscriptionIds)}
+            ORDER BY subscription.id, failed."lastAttemptAt" DESC NULLS LAST, failed.id
+          `,
+        ])
+      : [[], []];
+    const hears = subscriptions.map((subscription): AppDetails["hears"][number] => {
+      const counts: AppDetails["hears"][number]["counts"] = { pending: 0, retrying: 0, done: 0, failed: 0, cancelled: 0 };
+      for (const row of deliveryCounts) if (row.subscription_id === subscription.id) counts[row.state] = row.count;
+      return {
+        subscriptionId: subscription.id,
+        eventType: subscription.event_type,
+        version: subscription.version,
+        publisherAppId: subscription.publisher_app_id ?? subscription.event_type.split(".")[0] ?? subscription.event_type,
+        title: presentations.get(`${subscription.event_type}@${subscription.version}`)?.title ?? subscription.title,
+        state: subscription.state,
+        reason: subscription.reason,
+        firstSeenAt: subscription.first_seen_at.toISOString(),
+        isNew: subscription.is_new,
+        counts,
+        failedDeliveries: failedDeliveries
+          .filter((row) => row.subscription_id === subscription.id)
+          .map(({ subscription_id: _subscriptionId, lastAttemptAt, ...row }) => ({
+            ...row,
+            lastAttemptAt: lastAttemptAt?.toISOString() ?? null,
+          })),
+      };
+    });
+    return {
+      app: {
+        id: appId,
+        ...(app ? resolveAppIdentityPresentation(app, locale) : { name: appId, description: null }),
+        icon: app?.icon ?? null,
+        accent: app?.appearance?.accent ?? null,
+        online: app !== null,
+      },
+      access: {
+        kind: app ? (app.access?.kind ?? "legacy") : null,
+        roles: app?.access?.kind === "roles" ? [...app.access.roles] : [],
+        grantCount: app?.access?.kind === "grants" ? (grantCounts.get(appId) ?? 0) : null,
+        platformPermissions: [...(app?.platformPermissions ?? [])],
+      },
+      sends: declarations.map((declaration) => {
+        const presentation = presentations.get(`${declaration.type}@${declaration.version}`);
+        return {
+          type: declaration.type,
+          version: declaration.version,
+          title: presentation?.title ?? declaration.title,
+          description: presentation?.description ?? declaration.description,
+          subject: `${declaration.app_id}.${declaration.subject}`,
+          place: declaration.place ? `${declaration.app_id}.${declaration.place}` : null,
+          automation: declaration.automation,
+          subscriberCount: declaration.subscriber_count,
+        };
+      }),
+      hears,
+      notifications: definitions.map((definition) => {
+        const presentation = resolveNotificationDefinitionPresentation(
+          { ...definition, excludedReason: definition.excluded_reason ?? undefined },
+          locale,
+        );
+        return {
+          id: definition.id,
+          kind: definition.kind,
+          ...presentation,
+          recipientKind: definition.recipient_kind,
+          requiredChannels: definition.required_channels,
+          recommendedChannels: definition.recommended_channels,
+          excludedChannels: definition.excluded_channels,
+          excludedReason: presentation.excludedReason ?? null,
+        };
+      }),
+      totals: {
+        sends: declarations[0]?.total ?? 0,
+        hears: subscriptions[0]?.total ?? 0,
+        notifications: definitions[0]?.total ?? 0,
+      },
+    };
+  };
+}
+
+export const appDetails = createAppDetailsService();

package/src/services/app-discovery.ts

@@ -18,10 +18,11 @@ export const discoverableAppEntries = async <T extends { appId: string }>(
   authority: RequestAuthority | null,
   entries: readonly T[],
   registry: () => Promise<AppRegistryEntry[]> = listApps,
+  options: { signal?: AbortSignal } = {},
 ): Promise<T[]> => {
   if (!entries.length) return [];
   const ids = new Set(entries.map((entry) => entry.appId));
   const apps = (await registry()).filter((app) => ids.has(app.id));
-  const usable = await usableAppIds(authority, apps);
+  const usable = await usableAppIds(authority, apps, options);
   return entries.filter((entry) => usable.has(entry.appId));
 };

package/src/services/app-event-shapes.ts

@@ -0,0 +1,139 @@
+import { createHash } from "node:crypto";
+import { z } from "zod";
+
+type Schema = Record<string, unknown>;
+const object = (value: unknown): Schema | null =>
+  typeof value === "object" && value !== null && !Array.isArray(value) ? (value as Schema) : null;
+const valid = (schema: Schema, value: unknown) => z.fromJSONSchema(schema).safeParse(value).success;
+const UUID = "00000000-0000-4000-8000-000000000001";
+
+export type RecordedAppEventShape =
+  | { keys: Record<string, RecordedAppEventShape> }
+  | { length: number; items: RecordedAppEventShape[] }
+  | null;
+
+/** Retains key presence and bucketed array structure, without scalar values. */
+export function recordedAppEventShape(data: unknown): RecordedAppEventShape {
+  if (Array.isArray(data)) {
+    const length = data.length === 0 ? 0 : data.length === 1 ? 1 : data.length <= 4 ? 2 : data.length <= 16 ? 5 : 17;
+    const items = [
+      ...new Map(
+        data.map((item) => {
+          const shape = recordedAppEventShape(item);
+          return [JSON.stringify(shape), shape] as const;
+        }),
+      ).entries(),
+    ]
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([, shape]) => shape);
+    return { length, items };
+  }
+  const properties = object(data);
+  return properties
+    ? {
+        keys: Object.fromEntries(
+          Object.keys(properties)
+            .sort()
+            .map((key) => [key, recordedAppEventShape(properties[key])]),
+        ),
+      }
+    : null;
+}
+
+export const appEventShapeId = (type: string, version: number, shape: RecordedAppEventShape) => {
+  const hash = createHash("sha256")
+    .update(JSON.stringify([type, version, shape]))
+    .digest("hex");
+  return `${hash.slice(0, 8)}-${hash.slice(8, 12)}-4${hash.slice(13, 16)}-8${hash.slice(17, 20)}-${hash.slice(20, 32)}`;
+};
+
+/** Synthesizes values from the declaration, using only recorded structure when supplied. */
+export const appEventShape = (schema: Schema, depth = 0, shape?: RecordedAppEventShape): unknown => {
+  if (depth > 16) throw new Error("shape_unavailable");
+  if ("const" in schema) return schema.const;
+  if (Array.isArray(schema.enum)) return schema.enum[0];
+  for (const key of ["anyOf", "oneOf"]) {
+    if (Array.isArray(schema[key]))
+      for (const branch of schema[key]) {
+        const sub = object(branch);
+        if (!sub) continue;
+        try {
+          const value = appEventShape(sub, depth + 1, shape);
+          if (valid(schema, value)) return value;
+        } catch {}
+      }
+  }
+  if (Array.isArray(schema.type))
+    for (const type of schema.type) {
+      try {
+        const value = appEventShape({ ...schema, type }, depth + 1, shape);
+        if (valid(schema, value)) return value;
+      } catch {}
+    }
+  if (schema.type === "null") return null;
+  if (schema.type === "boolean") return false;
+  if (schema.type === "number" || schema.type === "integer") {
+    const step = typeof schema.multipleOf === "number" ? schema.multipleOf : 1;
+    let n =
+      typeof schema.minimum === "number"
+        ? schema.minimum
+        : typeof schema.exclusiveMinimum === "number"
+          ? schema.exclusiveMinimum + step
+          : 0;
+    if (typeof schema.maximum === "number") n = Math.min(n, schema.maximum);
+    if (typeof schema.exclusiveMaximum === "number") n = Math.min(n, schema.exclusiveMaximum - step);
+    n = Math.ceil(n / step) * step;
+    if (valid(schema, n)) return n;
+  }
+  if (schema.type === "string") {
+    const min = typeof schema.minLength === "number" ? schema.minLength : 0;
+    const max = typeof schema.maxLength === "number" ? schema.maxLength : 256;
+    if (min > 4096) throw new Error("shape_unavailable");
+    const exact = typeof schema.pattern === "string" ? schema.pattern.match(/^\^([a-zA-Z0-9_.@:/ -]+)\$$/)?.[1] : undefined;
+    const candidates = [
+      exact,
+      UUID,
+      "2000-01-01T00:00:00.000Z",
+      "2000-01-01",
+      "00:00:00",
+      "https://example.invalid/",
+      "fixture@example.invalid",
+      "127.0.0.1",
+      "fixture",
+      "local",
+      "ipa",
+      "a".repeat(Math.max(1, min)),
+      "0".repeat(Math.max(1, min)),
+      "",
+    ];
+    for (const value of candidates) if (typeof value === "string" && value.length <= max && valid(schema, value)) return value;
+  }
+  if (schema.type === "array") {
+    const minimum = typeof schema.minItems === "number" ? schema.minItems : 0;
+    const count = Math.max(minimum, shape && "length" in shape ? shape.length : 0);
+    if (count > 100) throw new Error("shape_unavailable");
+    const item = object(schema.items);
+    const value = Array.from({ length: count }, (_, index) =>
+      appEventShape(
+        object(Array.isArray(schema.prefixItems) ? schema.prefixItems[index] : null) ?? item ?? { type: "null" },
+        depth + 1,
+        shape && "items" in shape ? shape.items[index % shape.items.length] : undefined,
+      ),
+    );
+    if (valid(schema, value)) return value;
+  }
+  if (schema.type === "object") {
+    const properties = object(schema.properties) ?? {};
+    const required = Array.isArray(schema.required) ? schema.required : [];
+    const value: Record<string, unknown> = {};
+    const keys = shape && "keys" in shape ? [...new Set([...required, ...Object.keys(shape.keys)])] : required;
+    for (const key of keys) {
+      if (typeof key !== "string") throw new Error("shape_unavailable");
+      const property = object(properties[key]);
+      if (!property) throw new Error("shape_unavailable");
+      value[key] = appEventShape(property, depth + 1, shape && "keys" in shape ? shape.keys[key] : undefined);
+    }
+    if (valid(schema, value)) return value;
+  }
+  throw new Error("shape_unavailable");
+};

package/src/services/app-events/accept.ts

@@ -0,0 +1,116 @@
+import type { SQL } from "bun";
+import { z } from "zod";
+import { assertAppEventSize } from "../../_internal/app-event-schemas";
+import { AppEventEnvelopeSchema } from "../../contracts/app-events";
+import { logger } from "../logging";
+import type { StoredDeclaration } from "./declarations";
+
+const log = logger("app-events:accept");
+// Additive envelope metadata from a newer publisher is compatible with older Core.
+const Envelope = AppEventEnvelopeSchema.strip().extend({ version: z.number().int().min(1).max(2_147_483_647) });
+const Metadata = z.object({
+  id: z.uuid(),
+  type: Envelope.shape.type.catch("unknown"),
+  source: Envelope.shape.source.catch("unknown"),
+  version: Envelope.shape.version.catch(1),
+});
+
+export function createEventAcceptance(db: SQL, reconcile: () => Promise<void>) {
+  const markSeen = async (sequence: number, tx: SQL = db) => {
+    // Keep holes until replay or the periodic DLQ/retention check accounts for them.
+    // Advancing the high watermark alone would hide eviction before the next tick.
+    await tx`
+      UPDATE events.app_broker_status SET
+        unseen_sequences = (unseen_sequences + CASE WHEN last_sequence + 1 < ${sequence} THEN
+          int8multirange(int8range(last_sequence + 1, ${sequence}::bigint, '[)')) ELSE '{}'::int8multirange END)
+          - int8multirange(int8range(${sequence}::bigint, ${sequence + 1}::bigint, '[)')),
+        last_sequence = GREATEST(last_sequence, ${sequence}), updated_at = now()
+      WHERE id = true AND (last_sequence < ${sequence} OR unseen_sequences @> ${sequence}::bigint)
+    `;
+  };
+  const reject = async (input: unknown, sequence: number, code: string) => {
+    const metadata = Metadata.safeParse(input);
+    if (!metadata.success) {
+      log.warn("Discarding invalid app event without a usable ID", { sequence, code });
+      await markSeen(sequence);
+      return;
+    }
+    const { id, type, source, version } = metadata.data;
+    await db.begin(async (tx) => {
+      // Invalid or oversized input is represented by metadata only, never a second failing payload insert.
+      await tx`
+        INSERT INTO events.app_events(id, type, version, source, subject_key, envelope, state, code)
+        VALUES (${id}::uuid, ${type}, ${version}, ${source}, ${`unknown:${id}`}, '{}'::jsonb, 'rejected', ${code})
+        ON CONFLICT(id) DO NOTHING
+      `;
+      await markSeen(sequence, tx);
+    });
+  };
+  const accept = async (input: unknown, sequence: number, attempt = 3) => {
+    const parsed = Envelope.safeParse(input);
+    if (!parsed.success) return reject(input, sequence, "invalid_envelope");
+    const envelope = parsed.data;
+    try {
+      assertAppEventSize(envelope);
+    } catch {
+      return reject(envelope, sequence, "event_too_large");
+    }
+    // Persisted declarations remain authoritative while discovery is unavailable.
+    try {
+      await reconcile();
+    } catch {
+      log.warn("Declaration refresh failed; accepting against persisted declarations", { sequence });
+    }
+    const [declaration] = await db<StoredDeclaration[]>`
+      SELECT * FROM events.app_declarations
+      WHERE app_id = ${envelope.source} AND type = ${envelope.type} AND version = ${envelope.version}
+    `;
+    let code: string | null = null;
+    if (!declaration) {
+      if (attempt < 3) throw new Error("Event declaration registration is not ready");
+      code = "event_not_declared";
+    } else if (declaration.retired_at) {
+      code = "event_not_declared";
+    } else if (
+      envelope.subject.type !== `${declaration.app_id}.${declaration.subject}` ||
+      (declaration.place ? envelope.place?.type !== `${declaration.app_id}.${declaration.place}` : envelope.place !== undefined)
+    ) {
+      code = "reference_mismatch";
+    } else {
+      try {
+        if (!z.fromJSONSchema(declaration.data_schema).safeParse(envelope.data).success) code = "schema_mismatch";
+      } catch {
+        code = "invalid_declaration_schema";
+      }
+    }
+    const subjectKey = `${envelope.subject.type}:${envelope.subject.id}`;
+    try {
+      await db.begin(async (tx) => {
+        const inserted = await tx`
+          INSERT INTO events.app_events(id, type, version, source, subject_key, envelope, state, code)
+          VALUES (${envelope.id}::uuid, ${envelope.type}, ${envelope.version}, ${envelope.source}, ${subjectKey},
+            ${JSON.stringify(envelope)}::text::jsonb, ${code ? "rejected" : "accepted"}, ${code})
+          ON CONFLICT(id) DO NOTHING RETURNING id
+        `;
+        if (inserted.length && !code) {
+          await tx`
+            INSERT INTO events.app_deliveries(id, subscription_id, event_id, subject_key)
+            SELECT gen_random_uuid(), id, ${envelope.id}::uuid, ${subjectKey} FROM events.app_subscriptions
+            WHERE event_type = ${envelope.type} AND version = ${envelope.version} AND state = 'active'
+            ON CONFLICT(subscription_id, event_id) DO NOTHING
+          `;
+        }
+        await markSeen(sequence, tx);
+      });
+    } catch (error) {
+      // PostgreSQL data exceptions and CHECK failures are deterministic; infrastructure failures retry.
+      const sqlState = error instanceof Error && "errno" in error ? error.errno : undefined;
+      if (typeof sqlState === "string" && (sqlState.startsWith("22") || sqlState === "23514")) {
+        await reject(envelope, sequence, sqlState === "23514" ? "event_too_large" : "invalid_envelope");
+        return;
+      }
+      throw error;
+    }
+  };
+  return { accept, markSeen };
+}