@k2b/cloud 0.41.0 → 0.42.0

package/src/events/live.ts

@@ -1,72 +1,18 @@
-import type { Topic, TopicConfig } from "@k2b/sync";
-import { type ServerWebSocket, type SQL, sql } from "bun";
+import type { ServerWebSocket } from "bun";
 import { type Context, Hono } from "hono";
 import { upgradeWebSocket } from "hono/bun";
 import type { z } from "zod";
-import { lazySync } from "../_internal/process-sync";
+import { guardAppAccessSocket } from "../server/middleware/app-access";
 import { type AuthContext, auth } from "../server/middleware/auth";
 import { rateLimit } from "../server/middleware/rate-limit";
-import { logger } from "../services/logging";
-import { createPgOutbox } from "../services/outbox";
 import * as settings from "../services/settings";
 import { publicCloudOrigin } from "../shared/app-url";
-import {
-  createLiveEngine,
-  type LiveChannel,
-  type LiveConnectionHandle,
-  type LiveEngine,
-  type LiveEnvelope,
-  type LiveViewer,
-} from "./live-engine";
+import { defineLivePublisher, liveTopic, startLiveDelivery } from "./live-delivery";
+import { createLiveEngine, type LiveChannel, type LiveConnectionHandle, type LiveEngine, type LiveViewer } from "./live-engine";
 
+export { liveOutbox, liveTopicConfig } from "./live-delivery";
 export type { LiveChannel, LiveViewer } from "./live-engine";
 
-const RECONCILE_INTERVAL_MS = 1_000;
-const STALE_CHECK_INTERVAL_MS = 60_000;
-
-/**
- * The live topic of one application. Frozen: Sync rejects a declaration that
- * differs from the existing stream, so two releases with different values
- * would break each other during a rollout. A change ships under a new id.
- */
-export const liveTopicConfig = (appId: string) =>
-  ({
-    id: `cloud:live:${appId}`,
-    owner: "cloud",
-    retention: { maxAgeMs: 24 * 3_600_000, maxBytes: 64 * 1024 ** 2 },
-    maxPayloadBytes: 40 * 1024,
-    deadLetterRetention: { maxBytes: 1024 ** 2 },
-  }) satisfies TopicConfig;
-
-type LiveOutboxRow = { id: string; attempts: number; ordering_key: string; payload: LiveEnvelope };
-
-const log = logger("events:live");
-
-const liveTopics = lazySync((sync) => {
-  const topics = new Map<string, Topic<LiveEnvelope>>();
-  return (appId: string): Topic<LiveEnvelope> => {
-    const existing = topics.get(appId);
-    if (existing) return existing;
-    const topic = sync.topic<LiveEnvelope>(liveTopicConfig(appId));
-    topics.set(appId, topic);
-    return topic;
-  };
-});
-
-/** Dispatcher of one application's live rows: ordered per key, deleted once published. */
-export const liveOutbox = (appId: string, publish: (row: LiveOutboxRow) => Promise<unknown>) =>
-  createPgOutbox<LiveOutboxRow>({
-    table: "events.outbox",
-    name: `events:live:${appId}`,
-    where: { kind: "live", app_id: appId },
-    orderBy: "ordering_key",
-    sequence: "seq",
-    reconcileIntervalMs: RECONCILE_INTERVAL_MS,
-    publish,
-  });
-
-/** Applications whose live updates this process defines, with the wake of their running dispatcher. */
-const dispatchers = new Map<string, (() => void) | null>();
 /** Applications whose live socket this process mounts; only the started application may be among them. */
 const served = new Set<string>();
 /** Live sockets served by this process; they close when the application stops. */
@@ -80,23 +26,7 @@ export const stopLiveEngines = () => {
   for (const engine of engines) engine.stop();
 };
 
-const logStaleRows = async (appId: string): Promise<void> => {
-  const [row] = await sql<{ count: number; oldest_seconds: number | null }[]>`
-    SELECT COUNT(*)::int AS count, EXTRACT(EPOCH FROM now() - MIN(created_at))::int AS oldest_seconds
-    FROM events.outbox
-    WHERE kind = 'live' AND app_id = ${appId} AND created_at < now() - interval '60 seconds'
-  `;
-  if (row && row.count > 0) log.warn("Live updates wait to be published", { appId, count: row.count, oldestSeconds: row.oldest_seconds });
-};
-
-/**
- * Publishes the rows of the started application's live definitions. `app.start()`
- * calls it with the started application's ID. A definition of another
- * application only reads that application's cursor, and its rows are published
- * by that application. It does nothing without a definition of the started
- * application, and fails when this process mounts the socket of another
- * application or Core has not created the outbox yet.
- */
+/** Starts delivery only for the application whose live sockets this process serves. */
 export const startLiveOutbox = async (appId: string): Promise<(() => Promise<void>) | null> => {
   const foreign = [...served].filter((other) => other !== appId);
   if (foreign.length > 0) {
@@ -104,35 +34,16 @@ export const startLiveOutbox = async (appId: string): Promise<(() => Promise<voi
       `This process mounts the live socket of "${foreign.join('", "')}", but starts "${appId}". Use the ID from the application's declaration.`,
     );
   }
-  if (!dispatchers.has(appId)) return null;
-  const [installed] = await sql<{ ready: boolean }[]>`
-    SELECT to_regprocedure('events.enqueue(uuid,text,text,text,jsonb,text)') IS NOT NULL AS ready
-  `;
-  if (!installed?.ready) {
-    throw new Error(
-      `"${appId}" writes live updates to events.outbox, which does not exist. Update Cloud Core first: its migration creates the outbox.`,
-    );
-  }
+  const stopDelivery = await startLiveDelivery(appId);
+  if (!stopDelivery) return null;
   // Delivery starts again: the engines stopped before give way to new ones.
   if (stopped) {
     engines.clear();
     stopped = false;
   }
-  const topic = liveTopics()(appId);
-  const outbox = liveOutbox(appId, (row) => topic.publish({ data: row.payload, orderingKey: row.ordering_key, idempotencyKey: row.id }));
-  outbox.start();
-  dispatchers.set(appId, () => void outbox.notify());
-  const staleCheck = setInterval(() => {
-    logStaleRows(appId).catch((error) =>
-      log.warn("Live outbox check failed", { appId, error: error instanceof Error ? error.message : String(error) }),
-    );
-  }, STALE_CHECK_INTERVAL_MS);
-  staleCheck.unref();
   return async () => {
     stopLiveEngines();
-    clearInterval(staleCheck);
-    dispatchers.set(appId, null);
-    await outbox.stop();
+    await stopDelivery();
   };
 };
 
@@ -217,36 +128,9 @@ const refusalOf = async (c: Context<AuthContext>): Promise<Refusal | null> => {
  * write updates; only the application itself publishes and serves them.
  */
 export const defineLive = <const Event extends z.ZodType>(definition: { appId: string; event: Event }) => {
-  const { appId, event } = definition;
-  if (!dispatchers.has(appId)) dispatchers.set(appId, null);
+  const { appId } = definition;
   return {
-    /**
-     * Writes one update in `tx`, the transaction that makes the change: a
-     * rollback writes nothing, a commit publishes it at least once. Data above
-     * 32 KiB becomes a reload hint for `key`; `data` must not hold anything a
-     * reader of `key` may not see. `access: true` announces that who may read
-     * `key` changed, in a row of its own before the data: every replica checks
-     * its subscribers of `key` again before it delivers the data, and its
-     * collections right after.
-     */
-    publish: async (
-      tx: SQL,
-      input: { key: string; data: z.input<Event>; access?: true } | { key: string; data?: undefined; access: true },
-    ): Promise<void> => {
-      // Store the JSON form of the input, and validate exactly that form here:
-      // the browser parses it, and data that does not survive JSON fails this write.
-      const data: unknown = input.data === undefined ? undefined : JSON.parse(JSON.stringify(input.data));
-      if (data !== undefined) event.parse(data);
-      const enqueue = (envelope: LiveEnvelope) =>
-        tx`SELECT events.enqueue(${crypto.randomUUID()}::uuid, ${appId}, 'live', ${input.key}, ${JSON.stringify(envelope)}::text::jsonb)`;
-      // The access change is a row of its own, so data too large for the outbox cannot drop it.
-      if (input.access) await enqueue({ v: 1, k: input.key, a: true });
-      if (data !== undefined) await enqueue({ v: 1, k: input.key, d: data });
-    },
-    /** Publishes committed updates now instead of within the next second. Call it after the commit. */
-    wake: (): void => dispatchers.get(appId)?.(),
-    /** The topic head. Read it before loading the snapshot it belongs to. */
-    cursor: (): Promise<string> => liveTopics()(appId).head(),
+    ...defineLivePublisher(definition),
     /**
      * The live socket with these channels. Mount it once, at `/api/<app>/live`,
      * in the application's own process: `app.start()` of another application fails.
@@ -261,7 +145,7 @@ export const defineLive = <const Event extends z.ZodType>(definition: { appId: s
       let engine: LiveEngine | null = null;
       const serve = (): LiveEngine => {
         if (engine && engines.has(engine)) return engine;
-        engine = createLiveEngine({ appId, topic: () => liveTopics()(appId), channels });
+        engine = createLiveEngine({ appId, topic: () => liveTopic(appId), channels });
         engines.add(engine);
         // A socket that opens while the application stops closes with 1012 and starts nothing.
         if (stopped) engine.stop();
@@ -284,13 +168,13 @@ export const defineLive = <const Event extends z.ZodType>(definition: { appId: s
           const viewer = viewerOf(c);
           const revalidate = revalidator(c);
           let connection: LiveConnectionHandle | null = null;
-          return {
+          return guardAppAccessSocket(c, appId, {
             onOpen: (_event, ws) => {
               connection = serve().open(ws.raw as ServerWebSocket<unknown>, viewer, revalidate);
             },
             onMessage: (message) => connection?.message(message.data),
             onClose: () => connection?.closed(),
-          };
+          });
         }),
       );
     },

package/src/geo/CloudMap.tsx

@@ -0,0 +1,95 @@
+import { MapView, MapViewFrame, type MapViewProps, mapAttribution, useLocale } from "@k2b/ui";
+import { createSignal, For, onCleanup, Show, splitProps } from "solid-js";
+import type { z } from "zod";
+import { invokeCapabilityWithDataSchema } from "../capabilities/client";
+import { type GeoAvailabilityDataSchema, geoContract } from "../contracts/geo";
+import { mapMessages } from "./map-messages";
+
+export type CloudMapProps = Omit<MapViewProps, "style" | "attribution"> & {
+  /** The authorized SSR snapshot keeps the first browser render identical. */
+  availability?: z.infer<typeof GeoAvailabilityDataSchema>;
+};
+
+/** Cloud's same-origin, budgeted map. Domain lists and recovery actions belong to the host. */
+export function CloudMap(props: CloudMapProps) {
+  const [local, map] = splitProps(props, ["availability", "onStateChange", "notice"]);
+  const locale = useLocale();
+  const [recovery, setRecovery] = createSignal("");
+  const controller = new AbortController();
+  onCleanup(() => controller.abort());
+  let generation = 0;
+  const onStateChange: NonNullable<MapViewProps["onStateChange"]> = (state) => {
+    local.onStateChange?.(state);
+    const current = ++generation;
+    if (state !== "error") {
+      setRecovery("");
+      return;
+    }
+    void invokeCapabilityWithDataSchema(
+      { kind: "query", appId: "core", capabilityId: geoContract.availability.id, input: {}, signal: controller.signal },
+      geoContract.availability.data,
+    )
+      .then((result) => {
+        if (!result.ok || controller.signal.aborted || current !== generation) return;
+        const availability = result.data.data;
+        const t = mapMessages.resolve([locale()]).t;
+        if (!availability.configured) setRecovery(t.notConfigured);
+        else if (availability.cloud.exhausted || availability.person.exhausted) {
+          const exhausted = availability.cloud.exhausted ? availability.cloud : availability.person;
+          const reset = new Intl.DateTimeFormat(locale(), { dateStyle: "short", timeStyle: "short" }).format(new Date(exhausted.resetsAt));
+          setRecovery(availability.cloud.exhausted ? t.cloudBudget({ reset }) : t.personBudget({ reset }));
+        }
+      })
+      .catch(() => {
+        /* MapView already displays its retry state. */
+      });
+  };
+  const language = () => encodeURIComponent(new Intl.Locale(locale()).language);
+  const enabled = () =>
+    !local.availability || (local.availability.configured && !local.availability.cloud.exhausted && !local.availability.person.exhausted);
+  return (
+    <Show
+      when={enabled()}
+      fallback={
+        <div class="relative" style={{ height: `${map.height}px` }}>
+          <MapViewFrame {...map} attribution={<CloudMapAttribution />} />
+          <Show when={local.notice}>
+            <div class="k2b-map-view__messages">
+              <div class="k2b-map-view__notice">{local.notice}</div>
+            </div>
+          </Show>
+        </div>
+      }
+    >
+      <MapView
+        {...map}
+        onStateChange={onStateChange}
+        notice={
+          <>
+            {local.notice}
+            <Show when={recovery()}>
+              <span role="status">{recovery()}</span>
+            </Show>
+          </>
+        }
+        style={{ light: `/api/geo/style?theme=light&locale=${language()}`, dark: `/api/geo/style?theme=dark&locale=${language()}` }}
+        attribution={<CloudMapAttribution />}
+      />
+    </Show>
+  );
+}
+
+export function CloudMapAttribution() {
+  return (
+    <For each={mapAttribution}>
+      {(item, index) => (
+        <>
+          {index() > 0 && " · "}
+          <a href={item.href} target="_blank" rel="noopener noreferrer">
+            {item.label}
+          </a>
+        </>
+      )}
+    </For>
+  );
+}

package/src/geo/map-messages.ts

@@ -0,0 +1,17 @@
+import { i18n } from "@k2b/stdlib";
+
+export const mapMessages = i18n.define({
+  baseLocale: "en",
+  messages: {
+    en: {
+      notConfigured: "Maps are not set up. The saved places remain available.",
+      cloudBudget: ({ reset }: { reset: string }) => `The Cloud map budget is used up until ${reset}.`,
+      personBudget: ({ reset }: { reset: string }) => `Your map budget is used up until ${reset}.`,
+    },
+    de: {
+      notConfigured: "Karten sind nicht eingerichtet. Die gespeicherten Orte bleiben verfügbar.",
+      cloudBudget: ({ reset }) => `Das Kartenbudget der Cloud ist bis ${reset} aufgebraucht.`,
+      personBudget: ({ reset }) => `Dein Kartenbudget ist bis ${reset} aufgebraucht.`,
+    },
+  },
+});

package/src/geo/ui.ts

@@ -0,0 +1 @@
+export { CloudMap, CloudMapAttribution, type CloudMapProps } from "./CloudMap";

package/src/index.ts

@@ -36,6 +36,8 @@ export type { RuntimeCompatibilityIssue } from "./_internal/runtime-compatibilit
 export { assessRuntimeCompatibility } from "./_internal/runtime-compatibility";
 export { buildRuntimeFromRegistry } from "./_internal/runtime-context";
 export { type AppSkillDefinition, skill } from "./ai/app-skills";
+export type { AppAccessDeclaration, AppAccessRule, FixedAppAccessRule } from "./contracts/app-access";
+export { appAccess } from "./contracts/app-access";
 export { defineCapabilities } from "./contracts/capabilities";
 export type {
   AnyBoundNotificationDefinition,

package/src/server/client-ip.ts

@@ -1,5 +1,41 @@
+import { isIP } from "node:net";
 import type { Context } from "hono";
 
 // The gateway (packages/gateway/src/client-address.ts) resolves this address using GATEWAY_TRUSTED_PROXIES.
 export const clientIp = (c: Context): string =>
   c.req.header("x-forwarded-for")?.split(",")[0]?.trim() ?? c.req.header("x-real-ip") ?? "unknown";
+
+/** Stable network key for IP budgets: IPv4 addresses and IPv6 /64 networks. */
+export const clientIpBucket = (ip: string): string => {
+  if (isIP(ip) !== 6) return `ip:${ip}`;
+
+  let address = ip.split("%", 1)[0]!;
+  if (address.includes(".")) {
+    const tail = address.lastIndexOf(":") + 1;
+    const value = address
+      .slice(tail)
+      .split(".")
+      .reduce((value, octet) => value * 256 + Number(octet), 0);
+    address = `${address.slice(0, tail)}${(value >>> 16).toString(16)}:${(value & 0xffff).toString(16)}`;
+  }
+  const [head = "", tail = ""] = address.split("::");
+  const left = head ? head.split(":") : [];
+  const right = tail ? tail.split(":") : [];
+  const groups = (address.includes("::") ? [...left, ...Array<string>(8 - left.length - right.length).fill("0"), ...right] : left).map(
+    (group) => Number.parseInt(group, 16),
+  );
+  const ipv4 = (high: number, low: number) => `ip:${[high >> 8, high & 255, low >> 8, low & 255].join(".")}`;
+  const [g0, g1, g2, g3, g4, g5, g6 = 0, g7 = 0] = groups;
+  if (g0 === 0 && g1 === 0 && g2 === 0 && g3 === 0 && g4 === 0 && g5 === 0xffff) return ipv4(g6, g7);
+  // NAT64 (64:ff9b::/96) and Teredo (2001::/32, inverted) carry the client's IPv4 address in the low 32 bits;
+  // their /64 names a translator or relay that unrelated clients share.
+  if (g0 === 0x64 && g1 === 0xff9b && g2 === 0 && g3 === 0 && g4 === 0 && g5 === 0) return ipv4(g6, g7);
+  if (g0 === 0x2001 && g1 === 0) return ipv4(g6 ^ 0xffff, g7 ^ 0xffff);
+  // 6to4 (2002::/16) gives one IPv4 holder a whole /48; key it by that IPv4 address instead of 65,536 /64 budgets.
+  if (g0 === 0x2002) return ipv4(g1 ?? 0, g2 ?? 0);
+  // One subscriber usually has at least a /64; rotating host addresses must not reset the budget.
+  return `ip6:${groups
+    .slice(0, 4)
+    .map((group) => group.toString(16))
+    .join(":")}::/64`;
+};

package/src/server/index.ts

@@ -1,5 +1,6 @@
 export { buildMetadata } from "../_internal/build-metadata";
 export { loadPendingApprovals } from "../api/approvals-loader";
+export { geoClient } from "../capabilities/geo-client";
 export { expectUserBackedActor, getUserBackedActor, isAppSessionActor, userFromActor } from "./actor";
 export type { ApiErrorBody, ApiErrorResponse, ApiErrorStatus } from "./api";
 export { api, respond, respondMessage } from "./api";
@@ -7,6 +8,7 @@ export type { CreateApiClientConfig } from "./api-client";
 export { api as apiClient } from "./api-client";
 export { appAssetPath } from "./app-assets";
 export type { AppContext } from "./app-context";
+export { clientIp, clientIpBucket } from "./client-ip";
 export { defineHelp, defineHelpCollection, type HelpCollection, type HelpDefinition, type HelpDefinitionDocument } from "./help";
 export { DEFAULT_LOCALE, getLocale, LOCALE_COOKIE, LOCALE_HEADER, locale, preferredLocale, resolveLocale } from "./locale";
 export type {
@@ -39,6 +41,7 @@ export {
   v,
   validator,
 } from "./middleware";
+export { guardAppAccessSocket } from "./middleware/app-access";
 export { RateLimitError, type RateLimiter, type RateLimiterConfig, type RateLimitResult, ratelimit } from "./ratelimit";
 export { REQUEST_IDLE_TIMEOUT_MAX_SECONDS, REQUEST_IDLE_TIMEOUT_SECONDS, setRequestTimeout } from "./request-timeout";
 export type {
@@ -49,8 +52,6 @@ export type {
   AccessUser,
   AccessUserSource,
   EffectiveGroup,
-  GeoPlace,
-  GeoService,
   PageParams,
   Paginated,
   PermissionLevel,
@@ -72,8 +73,6 @@ export {
   fail,
   freeipa,
   generatePassword,
-  geo,
-  geoService,
   getAccess,
   getEffectiveGroupIds,
   getEffectiveGroups,