anbaric-cloud-hosting 1.51.0 → 1.52.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "anbaric-cloud-hosting",
-  "version": "1.51.0",
+  "version": "1.52.0",
   "description": "Anbaric Cloud hosting service: Postgres-backed job persistence and queuing exposed over an HTTP API",
   "license": "MIT",
   "author": "chris@anbaric.ai",
@@ -18,18 +18,18 @@
     "@aws-sdk/client-s3": "^3.1110.0",
     "@aws-sdk/client-secrets-manager": "^3.700.0",
     "@aws-sdk/client-servicediscovery": "^3.1110.0",
-    "anbaric-data-store": "^1.51.0",
-    "anbaric-plugins": "^1.51.0",
-    "anbaric-tsapi": "^1.51.0",
-    "anbaric-web": "^1.51.0",
+    "anbaric-data-store": "^1.52.0",
+    "anbaric-plugins": "^1.52.0",
+    "anbaric-tsapi": "^1.52.0",
+    "anbaric-web": "^1.52.0",
     "esbuild": "^0.28.2",
     "pg": "^8.16.0"
   },
   "devDependencies": {
     "@types/node": "^26.2.0",
     "@types/pg": "^8.15.0",
-    "anbaric-impl-cloud": "^1.51.0",
-    "anbaric-state-machine": "^1.51.0",
+    "anbaric-impl-cloud": "^1.52.0",
+    "anbaric-state-machine": "^1.52.0",
     "tsx": "^4.20.0",
     "typescript": "^7.0.2"
   },

package/src/app-management/appHostname.ts

@@ -0,0 +1,39 @@
+/* An app is reachable at a hostname of its own, so that it is served at the
+   root of it and works exactly as it did when it was built locally. Two tenants
+   will both have a hello-world, so the tenant is part of the name.
+
+   One label, not two: a TLS wildcard matches a single label, so app.tenant.domain
+   would need a certificate and a DNS record for every tenant, which would put a
+   person in the middle of a self-serve signup. app--tenant.domain needs neither,
+   ever. The separator is a double hyphen because an underscore is not legal in a
+   hostname and would be rejected by certificates and by some browsers. */
+
+const SEPARATOR = "--";
+
+// A DNS label may not exceed 63 characters, and the whole label is the app and
+// the tenant together, so the limit is shared between them.
+const LABEL_LIMIT = 63;
+
+const SHAPE = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/;
+
+const hostLabelFor = (appName : string, tenant : string) : string => `${appName}${SEPARATOR}${tenant}`;
+
+/* Why this name cannot have a hostname, or undefined when it can. Returned as a
+   sentence because it is shown to whoever ran the deploy. */
+const hostnameObjection = (appName : string, tenant : string) : string | undefined => {
+    if (! SHAPE.test(appName)) {
+        return `"${appName}" must be lower-case letters, numbers and hyphens, starting and ending with a letter or number`;
+    }
+    if (appName.includes(SEPARATOR)) {
+        return `"${appName}" cannot contain "${SEPARATOR}" - it is what separates the app from the tenant in its hostname`;
+    }
+    if (! tenant) return undefined;
+
+    const label = hostLabelFor(appName, tenant);
+    if (label.length > LABEL_LIMIT) {
+        return `"${appName}" is too long for a hostname alongside tenant "${tenant}": ${label.length} characters, and a hostname label allows ${LABEL_LIMIT}`;
+    }
+    return undefined;
+};
+
+export { hostLabelFor, hostnameObjection, SEPARATOR, LABEL_LIMIT };

package/src/hosting/HostingServer.ts

@@ -38,6 +38,7 @@ import {PluginsHandler} from "./handlers/PluginsHandler";
 import {AuthenticationMiddleware} from "./middleware/AuthenticationMiddleware";
 import {SessionMiddleware} from "./middleware/SessionMiddleware";
 import {TenantRoutingMiddleware} from "./middleware/TenantRoutingMiddleware";
+import {AppHostMiddleware} from "./middleware/AppHostMiddleware";
 import {LoadedPlugin} from "../plugins/Plugin";
 import {Request} from "./Request";
 import {Router} from "./Router";
@@ -109,9 +110,10 @@ class HostingServer {
             publicRouter.register("authorize-cli", new AuthorizeCliHandler(cliAuthorizer, pages, tenant));
             publicRouter.registerApi("keys", new KeysHandler(cliAuthorizer));
         }
-        if (buildLayer) {
-            publicRouter.registerApi("apps", new AppsHandler(buildLayer));
-            publicRouter.register("app", new AppProxyHandler(buildLayer));
+        const appProxy = buildLayer ? new AppProxyHandler(buildLayer) : undefined;
+        if (buildLayer && appProxy) {
+            publicRouter.registerApi("apps", new AppsHandler(buildLayer, tenant));
+            publicRouter.register("app", appProxy);
         }
         // An unrouted absolute path carrying an app Referer is an app-internal
         // link the proxy's prefix-stripping left bare; send it back to its app.
@@ -143,6 +145,9 @@ class HostingServer {
         this.publicServer = new Server(publicRouter, [
             new SessionMiddleware(),
             new TenantRoutingMiddleware(tenant),
+            // Before routing: an app on its own hostname owns every path, so
+            // there is nothing for the platform's own routes to match against.
+            new AppHostMiddleware(appProxy),
             new AuthenticationMiddleware(authenticator, tokenAuthenticator, openRequests, undefined, userDirectory, memberships),
         ]);
         this.internalServer = new Server(internalRouter);

package/src/hosting/Request.ts

@@ -2,6 +2,7 @@ import {randomUUID} from "node:crypto";
 import {IncomingMessage, ServerResponse} from "node:http";
 import {Tenant} from "../auth/Tenant";
 import {User} from "../auth/User";
+import {ErrorPage, NOT_FOUND, render} from "./pages/ErrorPage";
 
 /* One inbound request: the parsed URL and body plus everything the server's
    middleware decorates it with - session, user, tenant, ray trace id -
@@ -125,7 +126,32 @@ class Request {
     }
 
     notFound() : void {
-        this.reply(404, { error: "Not found" });
+        this.replyProblem(NOT_FOUND);
+    }
+
+    /* Answers in whatever the caller can read: a person gets a page that says
+       what happened, a client gets the json it was expecting. Deciding by the
+       Accept header rather than by the route means an api call never has html
+       pushed at it, and a browser never sees a bare error object. */
+    replyProblem(page : ErrorPage) : void {
+        const retry = page.retryAfter ? { "retry-after": String(page.retryAfter) } : {};
+
+        if (! this.wantsHtml()) {
+            this.response.writeHead(page.status, { "content-type": "application/json", ...retry });
+            this.response.end(JSON.stringify({ error: page.heading, detail: page.detail }));
+            return;
+        }
+
+        this.response.writeHead(page.status, {
+            "content-type": "text/html; charset=utf-8",
+            "cache-control": "no-store",
+            ...retry,
+        });
+        this.response.end(render(page));
+    }
+
+    private wantsHtml() : boolean {
+        return String(this.header("accept") ?? "").includes("text/html");
     }
 
 }

package/src/hosting/handlers/AppProxyHandler.ts

@@ -2,6 +2,7 @@ import {IncomingHttpHeaders, OutgoingHttpHeaders, request as httpRequest} from "
 import {BuildLayer} from "../../app-management/BuildLayer";
 import {Request} from "../Request";
 import {RequestHandler} from "../RequestHandler";
+import {DEPLOYING, FAILED, NOT_RUNNING} from "../pages/ErrorPage";
 
 /* Headers that describe a single hop and must not be forwarded across the
    proxy in either direction. */
@@ -21,13 +22,36 @@ class AppProxyHandler implements RequestHandler {
     constructor(private buildLayer : BuildLayer) {}
 
     async handle(request : Request) : Promise<void> {
-        await this.buildLayer.ensureHydrated();
         const appName = request.id;
-        if (!appName) return request.notFound();
+        if (! appName) return request.notFound();
+
+        // Under /app/<name> the app is mounted on a sub-path, so it is told
+        // where it really lives and the prefix is taken off what it receives.
+        await this.serve(request, appName, request.url.pathname.slice(`/app/${appName}`.length) || "/", `/app/${appName}`);
+    }
+
+    /* The same app, reached by its own hostname. Nothing is stripped and there
+       is no prefix to announce, because the app is at the root of that host -
+       exactly where it was when it was built and run locally. */
+    async serveAtRoot(request : Request, appName : string) : Promise<void> {
+        await this.serve(request, appName, request.url.pathname, "");
+    }
+
+    private async serve(request : Request, appName : string, appPath : string, prefix : string) : Promise<void> {
+        await this.buildLayer.ensureHydrated();
         const app = this.buildLayer.status(appName);
-        if (!app || app.status !== "running") return request.notFound();
+        if (! app) return request.notFound();
+
+        /* An app is torn down while its replacement builds, so a visitor who
+           arrives mid-deploy would otherwise be told the app does not exist.
+           It does; it is just between versions, and saying so - with a page
+           that comes back on its own - is the difference between a blip and an
+           outage as far as anyone watching is concerned. */
+        if (app.status !== "running") {
+            return request.replyProblem(
+                app.status === "building" ? DEPLOYING : app.status === "failed" ? FAILED : NOT_RUNNING);
+        }
 
-        const appPath = request.url.pathname.slice(`/app/${appName}`.length) || "/";
         const body = request.method === "GET" || request.method === "HEAD" ? undefined : await request.rawBody();
 
         await new Promise<void>((resolve, reject) => {
@@ -36,7 +60,7 @@ class AppProxyHandler implements RequestHandler {
                 port: app.appPort,
                 method: request.method,
                 path: `${appPath}${request.url.search}`,
-                headers: this.forwardHeaders(request, appName),
+                headers: this.forwardHeaders(request, prefix),
             }, response => {
                 request.rawResponse.writeHead(response.statusCode ?? 502, this.passThrough(response.headers));
                 response.pipe(request.rawResponse);
@@ -49,10 +73,10 @@ class AppProxyHandler implements RequestHandler {
         });
     }
 
-    private forwardHeaders(request : Request, appName : string) : OutgoingHttpHeaders {
+    private forwardHeaders(request : Request, prefix : string) : OutgoingHttpHeaders {
         const headers = this.passThrough(request.raw.headers);
         delete headers.host;
-        headers["x-forwarded-prefix"] = `/app/${appName}`;
+        headers["x-forwarded-prefix"] = prefix;
         headers["x-forwarded-host"] = request.raw.headers.host;
         headers["x-forwarded-proto"] = "https";
         return headers;

package/src/hosting/handlers/AppsHandler.ts

@@ -1,11 +1,12 @@
 import {BuildLayer} from "../../app-management/BuildLayer";
 import {deniesBuild} from "../../auth/TenantRole";
 import {Request} from "../Request";
+import {hostnameObjection} from "../../app-management/appHostname";
 import {RequestHandler} from "../RequestHandler";
 
 class AppsHandler implements RequestHandler {
 
-    constructor(private buildLayer : BuildLayer) {}
+    constructor(private buildLayer : BuildLayer, private tenant? : string) {}
 
     async handle(request : Request) : Promise<void> {
         // Changing what is deployed is a builder's job; a USER may look.
@@ -50,6 +51,13 @@ class AppsHandler implements RequestHandler {
     private async handleDeploy(request : Request, appName : string) : Promise<void> {
         switch (request.method) {
             case "POST": {
+                /* Refused here rather than at the edge: a name that cannot be
+                   part of a hostname would deploy happily and then simply not
+                   be reachable by its own address, which is a worse thing to
+                   discover later. */
+                const objection = hostnameObjection(appName, this.tenant ?? "");
+                if (objection) return request.reply(400, { error: objection });
+
                 const appPort = Number(request.query("port"));
                 if (!Number.isInteger(appPort) || appPort <= 0) {
                     return request.reply(400, { error: "Expected a numeric ?port query parameter - the app's internal port (\"internalPort\" in .anbaric/app-config.json)" });

package/src/hosting/middleware/AppHostMiddleware.ts

@@ -0,0 +1,31 @@
+import {AppProxyHandler} from "../handlers/AppProxyHandler";
+import {Middleware} from "../Middleware";
+import {Request} from "../Request";
+
+/* An app reached by its own hostname is served at the root of it, so a page
+   that asks for /styles.css or calls fetch("/api/thing") works exactly as it
+   did on the author's machine. Under /app/<name> those same requests escape the
+   app and land on the platform, which is why an app built locally has to be
+   rewritten before it can be deployed - the thing this removes.
+
+   The edge resolves the hostname and names the app in a header; it overwrites
+   whatever the client sent, so this is not something a caller can choose. Even
+   if it were, naming an app is not a privilege: the same app is reachable at
+   /app/<name> anyway, and the platform authenticates either way. */
+const APP_HOST_HEADER = "x-anbaric-app-host";
+
+class AppHostMiddleware implements Middleware {
+
+    constructor(private proxy : AppProxyHandler | undefined) {}
+
+    async apply(request : Request) : Promise<boolean> {
+        const appName = String(request.header(APP_HOST_HEADER) ?? "").trim();
+        if (! this.proxy || ! appName) return true;
+
+        await this.proxy.serveAtRoot(request, appName);
+        return false;
+    }
+
+}
+
+export { AppHostMiddleware, APP_HOST_HEADER };

package/src/hosting/pages/ErrorPage.ts

@@ -0,0 +1,112 @@
+/* Pages for the moments when there is nothing to show. These are served by the
+   platform itself rather than the console bundle, so they carry no assets and
+   no stylesheet: the values below are the design system's own tokens, copied
+   because the platform has no way to read that package at runtime. Keep them in
+   step with anbaric-design-system/tokens.css.
+
+   A page that says "back in a moment" is worth more than a stack trace to
+   someone who only wanted to look at an app while it happened to be mid-deploy. */
+
+const TOKENS = {
+    background: "#f7f8fa",
+    surface: "#ffffff",
+    edge: "#eaebef",
+    foreground: "#14131c",
+    muted: "#6f6f7c",
+    primary: "#e4637b",
+    title: '"Founders Grotesk", "Inter", system-ui, -apple-system, sans-serif',
+};
+
+type ErrorPage = {
+    status : number,
+    heading : string,
+    detail : string,
+
+    /* Seconds until the page reloads itself. Only for states that are known to
+       be temporary: a page that retries something permanently broken is just a
+       flicker, and it hides the fact that nothing is going to change. */
+    retryAfter? : number,
+};
+
+const escapeHtml = (text : string) : string =>
+    text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+
+const render = (page : ErrorPage) : string => `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${escapeHtml(page.heading)}</title>
+${page.retryAfter ? `<meta http-equiv="refresh" content="${page.retryAfter}">` : ""}
+<style>
+  :root { color-scheme: light }
+  body {
+    margin: 0;
+    min-height: 100dvh;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    background: ${TOKENS.background};
+    color: ${TOKENS.foreground};
+    font-family: ${TOKENS.title};
+    padding: 1.5rem;
+    box-sizing: border-box;
+  }
+  main {
+    max-width: 30rem;
+    width: 100%;
+    background: ${TOKENS.surface};
+    border: 1px solid ${TOKENS.edge};
+    border-radius: 1.125rem;
+    padding: 2rem;
+  }
+  .brand {
+    font-size: 0.8rem;
+    font-weight: 700;
+    letter-spacing: 0.12em;
+    text-transform: uppercase;
+    color: ${TOKENS.primary};
+    margin: 0 0 1.5rem;
+  }
+  h1 { margin: 0 0 0.5rem; font-size: 1.4rem; line-height: 1.25; text-transform: uppercase }
+  p { margin: 0; color: ${TOKENS.muted}; font-size: 0.95rem; line-height: 1.6 }
+  .waiting { margin-top: 1.5rem; font-size: 0.85rem; color: ${TOKENS.muted} }
+</style>
+</head>
+<body>
+  <main>
+    <p class="brand">Anbaric</p>
+    <h1>${escapeHtml(page.heading)}</h1>
+    <p>${escapeHtml(page.detail)}</p>
+    ${page.retryAfter ? `<p class="waiting">This page checks again every ${page.retryAfter} seconds.</p>` : ""}
+  </main>
+</body>
+</html>`;
+
+const NOT_FOUND : ErrorPage = {
+    status: 404,
+    heading: "Nothing here",
+    detail: "That address does not match anything on this platform. If you followed a link, it may be out of date.",
+};
+
+const DEPLOYING : ErrorPage = {
+    status: 503,
+    heading: "Just a moment",
+    detail: "This app is being deployed. It will be back as soon as the new version is running.",
+    retryAfter: 5,
+};
+
+const NOT_RUNNING : ErrorPage = {
+    status: 503,
+    heading: "Not running",
+    detail: "This app is not running at the moment. Someone with access can start it again from the console.",
+};
+
+const FAILED : ErrorPage = {
+    status: 503,
+    heading: "This app did not start",
+    detail: "Its last deployment failed, so there is nothing to serve yet. The console has the build log.",
+};
+
+export { render, NOT_FOUND, DEPLOYING, NOT_RUNNING, FAILED };
+export type { ErrorPage };

package/src/index.ts

@@ -58,6 +58,8 @@ export * from "./hosting/Server";
 export * from "./hosting/middleware/AuthenticationMiddleware";
 export * from "./hosting/middleware/SessionMiddleware";
 export * from "./hosting/middleware/TenantRoutingMiddleware";
+export * from "./hosting/middleware/AppHostMiddleware";
+export * from "./app-management/appHostname";
 export * from "./hosting/handlers/AppProxyHandler";
 export * from "./hosting/handlers/AppsHandler";
 export * from "./hosting/handlers/AuditsHandler";