@valentinkolb/cloud 0.2.0 → 0.3.0

package/README.md

@@ -68,10 +68,10 @@ A standard app declares four prefixes (`/api/<id>`, `/app/<id>`, `/admin/<id>`,
 
 ## Documentation
 
-Full walkthroughs, the per-app anatomy, deployment templates, and a reference app live in the repo:
+Full walkthroughs, the per-app anatomy, deployment templates, and a reference app:
 
-- **[APPS.md](https://github.com/ValentinKolb/cloud/blob/main/APPS.md)** — end-to-end app authoring guide
-- **[github.com/ValentinKolb/cloud](https://github.com/ValentinKolb/cloud)** — monorepo, docker images, prod compose template
+- **[github.com/ValentinKolb/cloud-template](https://github.com/ValentinKolb/cloud-template)** — starter repo with a working reference app + the complete app-authoring guide
+- **[github.com/ValentinKolb/cloud](https://github.com/ValentinKolb/cloud)** — the platform monorepo (gateway, core, all platform apps)
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@valentinkolb/cloud",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Modular Hono+SolidJS framework for building per-app docker services behind a dynamic gateway. Powers cloud.stuve-ulm.de.",
   "license": "MIT",
   "repository": {
@@ -39,9 +39,11 @@
     "@scalar/hono-api-reference": "^0.10.9",
     "@scalar/openapi-to-markdown": "^0.5.6",
     "@tabler/icons-webfont": "^3.36.1",
+    "@tailwindcss/typography": "^0.5.19",
     "@valentinkolb/ssr": "0.9.0",
     "@valentinkolb/stdlib": "0.3.0",
     "@valentinkolb/sync": "^5.0.0",
+    "bun-plugin-tailwind": "^0.1.2",
     "hono": "^4.11.1",
     "hono-openapi": "^1.1.2",
     "katex": "^0.16.28",
@@ -51,19 +53,17 @@
     "nodemailer": "^7.0.12",
     "sanitize-html": "^2.17.0",
     "solid-js": "^1.9.10",
+    "tailwindcss": "^4.1.18",
     "zod": "^4.3.4"
   },
   "devDependencies": {
     "@babel/core": "^7.28.5",
     "@babel/preset-typescript": "^7.28.5",
-    "@tailwindcss/typography": "^0.5.19",
     "@types/bun": "1.3.9",
     "@types/mustache": "^4.2.6",
     "@types/nodemailer": "^7.0.5",
     "@types/sanitize-html": "^2.16.0",
     "babel-preset-solid": "^1.9.10",
-    "bun-plugin-tailwind": "^0.1.2",
-    "tailwindcss": "^4.1.18",
     "typescript": "^5.9.3"
   }
 }

package/src/_internal/define-app.ts

@@ -20,14 +20,12 @@ import type { AppRegistryEntry } from "../contracts/registry";
 import type { Role } from "../contracts/shared";
 import type { AppSettingsMap, KindToType } from "../contracts/settings-types";
 import { createSettingsAPI, type SettingsAPI } from "../services/settings/api";
-import { loadSnapshot } from "../services/settings/snapshot";
 import { registerSettings, type SettingDef } from "../services/settings/defaults";
 import { auth } from "../server/middleware/auth";
 import { logger } from "../services/logging";
 import { get, set, loadCache as loadSettingsCache } from "../services/settings";
-import { appRegistry, listApps } from "./registry";
 import { createHeartbeat } from "./heartbeat";
-import { buildRuntimeFromRegistry } from "./runtime-context";
+import { ensureRuntimeWatcher, getCurrentRuntime, stopRuntimeWatcher } from "./runtime-watcher";
 
 /** Cache-busting version stamp — changes on every server start / rebuild. */
 const v = Date.now();
@@ -119,16 +117,23 @@ export type AppOptions<S extends AppSettingsMap = {}> = {
 
 export type StartOptions = {
   /**
-   * Single Hono instance mounted at `/` of the app's container. The app owns
-   * its full URL space — routes are written with their absolute paths
-   * (`/api/<id>`, `/app/<id>`, `/admin/<id>`, …), matching what the app
-   * declared in `defineApp({ routes: [...] })`.
+   * Web-standard fetch handler. Mounted at `/` of the app's container.
+   * Typically you pass a Hono instance's `.fetch`:
    *
-   * Framework-owned mounts (`/_ssr/*`, `/public/*`, `/api/_internal/search`)
-   * register before this router so they take precedence — apps can ignore
-   * those paths.
+   *   const router = new Hono<AuthContext>()
+   *     .use("*", middleware.runtime())
+   *     .use("*", middleware.settings())
+   *     .route("/api/<id>", apiRoutes)
+   *     .route("/app/<id>", pageRoutes);
+   *
+   *   app.start({ fetch: router.fetch });
+   *
+   * The framework owns `/_ssr/*`, `/public/*`, and `/api/_internal/search`
+   * (the last only when `capabilities.search` is set) and registers them
+   * before this fetch — they take precedence over any catch-all the app
+   * might register.
    */
-  router: Hono<any>;
+  fetch: (req: Request) => Response | Promise<Response>;
   lifecycle?: AppLifecycle;
   capabilities?: AppCapabilities;
   port?: number;
@@ -296,47 +301,19 @@ export const defineApp = <const S extends AppSettingsMap = {}>(opts: AppOptions<
     await heartbeat.start();
     log.info(`Registered "${meta.id}"`, { baseUrl });
 
-    // Runtime context (navigation, app discovery)
-    const ac = new AbortController();
-    let currentRuntime = buildRuntimeFromRegistry(await listApps());
+    // Runtime context — start the registry watcher so middleware.runtime() and
+    // the lifecycle context below see populated cluster state. Idempotent: the
+    // watcher is a module-level singleton, only one runs per process.
+    await ensureRuntimeWatcher();
 
-    const refreshRuntime = async () => {
-      currentRuntime = buildRuntimeFromRegistry(await listApps());
-    };
-
-    (async () => {
-      try {
-        const snap = await appRegistry.snapshot({ prefix: "apps/" });
-        for await (const ev of appRegistry.reader({ prefix: "apps/", after: snap.cursor }).stream({ signal: ac.signal })) {
-          if (ev.type === "overflow") {
-            await refreshRuntime();
-            continue;
-          }
-          await refreshRuntime();
-        }
-      } catch (err) {
-        if (err instanceof Error && err.name === "AbortError") return;
-        log.error("Registry watcher failed", { error: err instanceof Error ? err.message : String(err) });
-      }
-    })();
-
-    // Build Hono server
+    // Build Hono server. Framework owns three mounts (registered first so
+    // they take precedence over any catch-all in the user's fetch):
+    //   /_ssr/*                 island chunks (SSR adapter)
+    //   /public/*               serveStatic + terminal 404
+    //   /api/_internal/search   only when capabilities.search is declared
     const ssrMountPath = config.basePath ? `${config.basePath}/_ssr` : "/_ssr";
 
-    // Per-request settings snapshot: skip static-asset paths so each /public,
-    // /branding, /favicon, /_ssr request isn't paying the snapshot cost.
-    const SNAPSHOT_SKIP_PREFIXES = ["/public/", "/_ssr/", "/branding/", "/favicon"];
-
     const server = new Hono()
-      .use("*", async (c, next) => {
-        (c as any).set("runtime", currentRuntime);
-        const path = c.req.path;
-        const skip = SNAPSHOT_SKIP_PREFIXES.some((p) => path.startsWith(p));
-        if (!skip) {
-          (c as any).set("settings", await loadSnapshot());
-        }
-        await next();
-      })
       .route(ssrMountPath, routes(config))
       .use("/public/*", serveStatic({
         root: "./",
@@ -346,11 +323,9 @@ export const defineApp = <const S extends AppSettingsMap = {}>(opts: AppOptions<
       }))
       // serveStatic calls next() on miss — terminate /public/* here so a
       // missing asset is a clean 404 instead of falling through to the app
-      // router (which might render an HTML page for the missing path).
+      // fetch (which might render an HTML page for the missing path).
       .all("/public/*", (c) => c.notFound());
 
-    // Framework-internal endpoints register BEFORE the app router so they
-    // take precedence over any catch-all the app might mount.
     if (startOpts.capabilities?.search) {
       const searchRun = startOpts.capabilities.search.run;
       server.post("/api/_internal/search", auth.requireRole("authenticated"), async (c) => {
@@ -361,13 +336,16 @@ export const defineApp = <const S extends AppSettingsMap = {}>(opts: AppOptions<
       });
     }
 
-    server.route("/", startOpts.router);
+    // User's fetch handles everything else. The framework doesn't inject any
+    // context vars here — the user's router is expected to register the
+    // middlewares it needs (middleware.runtime, middleware.settings, …).
+    server.all("*", (c) => Promise.resolve(startOpts.fetch(c.req.raw)));
 
     // Lifecycle
     const cloudCtx: CloudContext = {
       logger,
       settings: { get, set },
-      runtime: currentRuntime,
+      runtime: getCurrentRuntime(),
     };
 
     if (!startOpts.skipSetup && startOpts.lifecycle?.setup) {
@@ -389,7 +367,7 @@ export const defineApp = <const S extends AppSettingsMap = {}>(opts: AppOptions<
       stopping = true;
       log.info(`Stopping: ${meta.id}`);
       try { if (startOpts.lifecycle?.stop) await startOpts.lifecycle.stop(cloudCtx); } catch {}
-      ac.abort();
+      stopRuntimeWatcher();
       await heartbeat.stop();
     };
 

package/src/_internal/runtime-watcher.ts

@@ -0,0 +1,61 @@
+/**
+ * Module-level singleton for the live cluster registry snapshot.
+ *
+ * `defineApp().start()` and the `middleware.runtime()` factory both call
+ * `ensureRuntimeWatcher()` — the first call subscribes to the Redis
+ * registry and starts refreshing on every event; subsequent calls are
+ * no-ops. Reads happen via `getCurrentRuntime()`.
+ *
+ * One process = one app = one watcher; lives until `stopRuntimeWatcher()`
+ * (called from defineApp's shutdown handler) or process exit.
+ */
+import { logger } from "../services/logging";
+import type { CloudRuntime } from "../contracts/app";
+import { appRegistry, listApps } from "./registry";
+import { buildRuntimeFromRegistry } from "./runtime-context";
+
+const log = logger("runtime-watcher");
+
+let current: CloudRuntime | undefined;
+let started = false;
+let abort: AbortController | undefined;
+
+const refresh = async () => {
+  current = buildRuntimeFromRegistry(await listApps());
+};
+
+export const ensureRuntimeWatcher = async (): Promise<void> => {
+  if (started) return;
+  started = true;
+  await refresh();
+  abort = new AbortController();
+  void (async () => {
+    try {
+      const snap = await appRegistry.snapshot({ prefix: "apps/" });
+      for await (const _ev of appRegistry
+        .reader({ prefix: "apps/", after: snap.cursor })
+        .stream({ signal: abort.signal })) {
+        await refresh();
+      }
+    } catch (err) {
+      if (err instanceof Error && err.name === "AbortError") return;
+      log.error("Registry watcher failed", { error: err instanceof Error ? err.message : String(err) });
+    }
+  })();
+};
+
+export const stopRuntimeWatcher = (): void => {
+  abort?.abort();
+  abort = undefined;
+  started = false;
+  current = undefined;
+};
+
+export const getCurrentRuntime = (): CloudRuntime => {
+  if (!current) {
+    throw new Error(
+      "Runtime not initialized — register middleware.runtime() in your router or call ensureRuntimeWatcher() during setup",
+    );
+  }
+  return current;
+};

package/src/server/middleware/middleware.ts

@@ -1,47 +1,45 @@
-import { auth } from "./auth";
-import { imageResponse, jsonResponse, openApiMeta, requiresAdmin, requiresAuth, requiresIpa, requiresIpaUser, requiresUser } from "./openapi";
+/**
+ * The `middleware` namespace bundles the request-lifecycle primitives
+ * that every cloud app composes into its own router. Apps register
+ * what they need; the framework no longer injects anything implicitly.
+ *
+ *   import { middleware, auth } from "@valentinkolb/cloud/server"
+ *
+ *   const router = new Hono<AuthContext>()
+ *     .use("*", middleware.logger())
+ *     .use("*", middleware.runtime())     // for Layout / Sidebar / dashboard / search
+ *     .use("*", middleware.settings())    // for c.get("settings")
+ *     .use("*", middleware.ratelimit())
+ *     .use(auth.requireRole("user"))
+ *     .post(
+ *       "/",
+ *       middleware.validator("json", Schema),
+ *       middleware.openapi({ tags: ["foo"], summary: "Create" }),
+ *       handler,
+ *     )
+ *
+ * `auth` lives separately because it has its own surface
+ * (requireRole, redirectToLogin, session.*) and is conceptually
+ * orthogonal to the request lifecycle.
+ */
+import { describeRoute } from "hono-openapi";
 import { rateLimit } from "./rate-limit";
 import { requestLogger } from "./request-logger";
-import { validator, v } from "./validator";
+import { runtime } from "./runtime";
+import { settings } from "./settings";
+import { validator } from "./validator";
 
 export const middleware = {
-  get auth() {
-    return auth;
-  },
-  get jsonResponse() {
-    return jsonResponse;
-  },
-  get imageResponse() {
-    return imageResponse;
-  },
-  get openApiMeta() {
-    return openApiMeta;
-  },
-  get requiresAuth() {
-    return requiresAuth;
-  },
-  get requiresAdmin() {
-    return requiresAdmin;
-  },
-  get requiresIpa() {
-    return requiresIpa;
-  },
-  get requiresIpaUser() {
-    return requiresIpaUser;
-  },
-  get requiresUser() {
-    return requiresUser;
-  },
-  get rateLimit() {
-    return rateLimit;
-  },
-  get requestLogger() {
-    return requestLogger;
-  },
-  get validator() {
-    return validator;
-  },
-  get v() {
-    return v;
-  },
+  /** Live cluster registry on `c.get("runtime")`. Required for Layout/Sidebar. */
+  runtime,
+  /** Frozen per-request settings snapshot on `c.get("settings")`. */
+  settings,
+  /** HTTP request logger (logs 5xx as error, 429 as warn, 401/403 as info). */
+  logger: () => requestLogger,
+  /** Sliding-window rate limiter, keyed by user id (auto fallback to IP). */
+  ratelimit: rateLimit,
+  /** Zod input validator. `c.req.valid(target)` is fully typed afterward. */
+  validator,
+  /** OpenAPI route metadata — re-export of hono-openapi's `describeRoute`. */
+  openapi: describeRoute,
 } as const;

package/src/server/middleware/runtime.ts

@@ -0,0 +1,18 @@
+/**
+ * Per-request middleware that exposes the live cluster registry on
+ * `c.get("runtime")`. The first call to this middleware kicks off the
+ * Redis registry watcher (idempotent); subsequent requests read from
+ * the in-memory snapshot.
+ *
+ * Required by anything that renders the framework's `<Layout>`,
+ * `<Sidebar>`, dashboard widget aggregator, or `Cmd+K` global search.
+ */
+import { createMiddleware } from "hono/factory";
+import { ensureRuntimeWatcher, getCurrentRuntime } from "../../_internal/runtime-watcher";
+
+export const runtime = () =>
+  createMiddleware(async (c, next) => {
+    await ensureRuntimeWatcher();
+    (c as unknown as { set: (k: string, v: unknown) => void }).set("runtime", getCurrentRuntime());
+    await next();
+  });

package/src/server/middleware/settings.ts

@@ -0,0 +1,29 @@
+/**
+ * Per-request middleware that exposes a frozen settings snapshot on
+ * `c.get("settings")`. Backed by Redis cache-aside (5-minute TTL),
+ * so the per-request cost is a single Redis read at most.
+ *
+ * Required by anything that reads typed settings inside an HTTP
+ * handler via `c.get("settings").<key>`.
+ *
+ * `skipPrefixes` defaults to `["/public/", "/_ssr/", "/branding/", "/favicon"]`
+ * — those paths never read settings, so skipping the snapshot load
+ * keeps static-asset requests free. Apps that mount settings only on
+ * /api or /app can avoid the option entirely by scoping the
+ * `.use()` path instead.
+ */
+import { createMiddleware } from "hono/factory";
+import { loadSnapshot } from "../../services/settings/snapshot";
+
+const DEFAULT_SKIP = ["/public/", "/_ssr/", "/branding/", "/favicon"] as const;
+
+export const settings = (opts?: { skipPrefixes?: readonly string[] }) => {
+  const skip = opts?.skipPrefixes ?? DEFAULT_SKIP;
+  return createMiddleware(async (c, next) => {
+    const path = c.req.path;
+    if (!skip.some((p) => path.startsWith(p))) {
+      (c as unknown as { set: (k: string, v: unknown) => void }).set("settings", await loadSnapshot());
+    }
+    await next();
+  });
+};