astroidjs 0.7.1 → 0.8.0

package/dist/config.d.ts

@@ -268,6 +268,43 @@ export interface TenancyConfig {
      * built from `Astro.url` stay public and correct.
      */
     rewritePrefix?: string;
+    /**
+     * First-party apps on their own labels, mapped to the internal path prefix
+     * each serves from — `{ studio: "/studio" }` serves
+     * `studio.example.com/<path>` from `src/pages/studio/<path>`.
+     *
+     * This is the missing half of {@link PwaConfig.emitDir}'s subdomain story:
+     * an app label is not a tenant (there is no lookup — the studio exists
+     * whether or not any tenant does) and not merely reserved (a reserved label
+     * renders the ordinary site, which turns the admin host into a second copy
+     * of the marketing homepage). It is a static rewrite, decided at config time.
+     *
+     * An app label is implicitly reserved: `tenantLabel` never offers it to
+     * `resolveTenant`, and listing it in `reserved` too is refused — one list
+     * per fact, or the two drift.
+     *
+     * Same internal-rewrite semantics as tenants: the visitor's URL never
+     * changes, and the path form stays reachable on the apex — which is what
+     * makes local dev work, since `wrangler dev` cannot serve subdomains.
+     */
+    apps?: Record<string, string>;
+    /**
+     * What a syntactically-valid tenant host whose label resolves to NOTHING
+     * (`resolveTenant` returned `null`) should get.
+     *
+     * `"fallthrough"` (the default) renders the ordinary site — which means a
+     * stranger who points a CNAME at your zone gets your homepage. `"404"` emits
+     * a guard that refuses the request instead, which is the right answer the
+     * moment tenant hosts are commercial surfaces: an unknown storefront must be
+     * unambiguously *not a page*, not a copy of the marketing site under someone
+     * else's name.
+     *
+     * Either way the decision stays visible in config rather than buried in the
+     * seam: `resolveTenant` decides *what exists*; this decides what not-existing
+     * means. Reserved labels, app labels, the apex, and off-pattern hosts are
+     * never affected — they aren't tenant candidates at all.
+     */
+    unknown?: "fallthrough" | "404";
 }
 export interface AstroidCron {
     /** Standard 5-field cron, UTC — e.g. `"*&#47;15 * * * *"`. */

package/dist/config.js

@@ -141,6 +141,24 @@ function assertTenancy(config) {
             "A wildcard route does not match its own apex, so the apex would 404. " +
             `Add "${apex}" to \`hosts\`.`);
     }
+    // App labels: each failure below otherwise surfaces as a rewrite to a path
+    // that renders the wrong page, with nothing pointing back at the config.
+    for (const [label, prefix] of Object.entries(tenancy.apps ?? {})) {
+        if (!label || label.includes(".")) {
+            throw new AstroidConfigError(`\`tenancy.apps\` label "${label}" must be a single subdomain label — ` +
+                "Cloudflare's wildcard matches one level.");
+        }
+        if ((tenancy.reserved ?? []).includes(label)) {
+            throw new AstroidConfigError(`"${label}" is in both \`tenancy.apps\` and \`tenancy.reserved\`. ` +
+                "An app label is implicitly reserved — keep it in `apps` only, or the " +
+                "two lists drift and `reserved` silently wins.");
+        }
+        if (!prefix.startsWith("/") || prefix === "/" || prefix.endsWith("/")) {
+            throw new AstroidConfigError(`\`tenancy.apps.${label}\` must be an internal path prefix like "/studio" ` +
+                `(leading slash, no trailing slash, not "/") — got "${prefix}". ` +
+                'The rewrite is `prefix + pathname`, so "/" or a trailing slash produces "//…".');
+        }
+    }
 }
 export function defineAstroid(config) {
     if (!config.key || config.key.trim().length === 0) {

package/dist/tenancy/index.d.ts

@@ -15,14 +15,26 @@ export declare function tenancyZone(tenancy: TenancyConfig): string;
  * The subdomain label for a host under the wildcard, or `null` when the host is
  * not a tenant candidate at all.
  *
- * `null` covers three distinct cases that all mean "render the ordinary site":
- * the apex itself (a wildcard does not match its own apex), a host outside the
- * pattern (a preview domain, `localhost`), and a reserved label.
+ * `null` covers four distinct cases that all mean "not a tenant": the apex
+ * itself (a wildcard does not match its own apex), a host outside the pattern
+ * (a preview domain, `localhost`), a reserved label, and an app label — which
+ * has its own static rewrite via {@link appPrefix} instead of a lookup.
  *
  * Exported and pure so a site can unit-test its own reserved list without
  * standing up a request.
  */
 export declare function tenantLabel(host: string, tenancy: TenancyConfig): string | null;
+/**
+ * The internal path prefix an app host rewrites to, or `null` when the host is
+ * not an app host — `appPrefix("studio.example.com", …)` → `"/studio"` under
+ * `apps: { studio: "/studio" }`.
+ *
+ * Static by design: an app exists whether or not any tenant does, so there is
+ * no per-request lookup and nothing to cache. Same host handling as
+ * {@link tenantLabel} (port and case ignored, one label only), so `wrangler
+ * dev` behaves like production.
+ */
+export declare function appPrefix(host: string, tenancy: TenancyConfig): string | null;
 /**
  * The scaffold-once `src/tenancy.ts` — the seam holding every decision Astroid
  * refuses to make for a site.

package/dist/tenancy/index.js

@@ -23,30 +23,61 @@ export function tenancyZone(tenancy) {
     return tenancy.zone ?? tenancy.hostPattern.replace(/^\*\./, "");
 }
 /**
- * The subdomain label for a host under the wildcard, or `null` when the host is
- * not a tenant candidate at all.
- *
- * `null` covers three distinct cases that all mean "render the ordinary site":
- * the apex itself (a wildcard does not match its own apex), a host outside the
- * pattern (a preview domain, `localhost`), and a reserved label.
- *
- * Exported and pure so a site can unit-test its own reserved list without
- * standing up a request.
+ * The single subdomain label under the wildcard, before any policy — or `null`
+ * for the apex, an off-pattern host, or a dotted label. Shared by
+ * {@link tenantLabel} and {@link appPrefix} so their host handling (port,
+ * case, one-level-only) cannot drift.
  */
-export function tenantLabel(host, tenancy) {
+function hostLabel(host, tenancy) {
     const suffix = tenancy.hostPattern.replace(/^\*\./, "");
     // Strip a port: `acme.example.com:8788` under `wrangler dev`.
     const hostname = host.split(":")[0]?.toLowerCase() ?? "";
     if (!hostname.endsWith(`.${suffix}`))
         return null;
     const label = hostname.slice(0, -(suffix.length + 1));
-    // Only a single label is a tenant. `a.b.example.com` under `*.example.com` is
+    // Only a single label counts. `a.b.example.com` under `*.example.com` is
     // not `a.b` — Cloudflare's wildcard matches one level, and treating a dotted
     // string as a slug would put a `/` in a rewrite path.
     if (!label || label.includes("."))
         return null;
-    const reserved = tenancy.reserved ?? [];
-    return reserved.includes(label) ? null : label;
+    return label;
+}
+/**
+ * The subdomain label for a host under the wildcard, or `null` when the host is
+ * not a tenant candidate at all.
+ *
+ * `null` covers four distinct cases that all mean "not a tenant": the apex
+ * itself (a wildcard does not match its own apex), a host outside the pattern
+ * (a preview domain, `localhost`), a reserved label, and an app label — which
+ * has its own static rewrite via {@link appPrefix} instead of a lookup.
+ *
+ * Exported and pure so a site can unit-test its own reserved list without
+ * standing up a request.
+ */
+export function tenantLabel(host, tenancy) {
+    const label = hostLabel(host, tenancy);
+    if (!label)
+        return null;
+    if ((tenancy.reserved ?? []).includes(label))
+        return null;
+    return tenancy.apps && label in tenancy.apps ? null : label;
+}
+/**
+ * The internal path prefix an app host rewrites to, or `null` when the host is
+ * not an app host — `appPrefix("studio.example.com", …)` → `"/studio"` under
+ * `apps: { studio: "/studio" }`.
+ *
+ * Static by design: an app exists whether or not any tenant does, so there is
+ * no per-request lookup and nothing to cache. Same host handling as
+ * {@link tenantLabel} (port and case ignored, one label only), so `wrangler
+ * dev` behaves like production.
+ */
+export function appPrefix(host, tenancy) {
+    const apps = tenancy.apps;
+    if (!apps)
+        return null;
+    const label = hostLabel(host, tenancy);
+    return label ? (apps[label] ?? null) : null;
 }
 /**
  * The scaffold-once `src/tenancy.ts` — the seam holding every decision Astroid
@@ -84,8 +115,8 @@ export function generateAstroidTenancy(config) {
         " *",
         " * `null` falls through to the ordinary site — which is a real choice, not a",
         " * default: a stranger's subdomain then renders your homepage. If that is wrong",
-        " * for this project, return null here and refuse it in the middleware's `guard`",
-        " * with a 404, so an unknown host is unambiguously not a page.",
+        ' * for this project, set `tenancy.unknown: "404"` in astroid.config.ts and the',
+        " * generated middleware refuses the host instead — unambiguously not a page.",
         " *",
         " * This runs on EVERY request to a tenant host, so a database lookup here is a",
         " * query per request. Cache it — a module-scope Map is enough within an isolate,",

package/dist/worker/generate.js

@@ -475,6 +475,7 @@ export function generateAstroidMiddleware(config) {
         // two import statements for the same module is legal and reads as an
         // oversight in a file nobody is supposed to hand-edit.
         `import { ${[
+            ...(tenancy && Object.keys(tenancy.apps ?? {}).length ? ["appPrefix"] : []),
             ...(portal ? ["astroidPortalGuardConfig"] : []),
             "astroidRateRules",
             ...(portal ? ["guardResponse", "portalGuard", "resolvePortalSession"] : []),
@@ -546,20 +547,36 @@ export function generateAstroidMiddleware(config) {
                 "  },",
             ]
             : []),
-        ...(portal
+        ...(portal || tenancy?.unknown === "404"
             ? [
-                "  // Route guard: the declarative prefix→roles table from your config.",
-                "  // An /api/* route always answers in JSON — redirecting fetch() to an",
-                "  // HTML login page returns 200 and markup, which reads as success.",
                 "  guard: (context) => {",
-                "    const decision = portalGuard(",
-                "      context.url.pathname,",
-                "      context.locals.portalUser,",
-                "      PORTAL_GUARD,",
-                "    );",
-                "    if (!decision) return undefined;",
-                '    if (decision.kind === "redirect") return context.redirect(decision.location);',
-                "    return guardResponse(decision) ?? undefined;",
+                ...(tenancy?.unknown === "404"
+                    ? [
+                        "    // A syntactically-valid tenant host whose label resolved to nothing is",
+                        '    // NOT a page (config `tenancy.unknown: "404"`). Falling through would',
+                        "    // render the marketing homepage on a stranger's subdomain. Reserved",
+                        "    // labels, app labels, and the apex never reach here — tenantLabel",
+                        "    // returns null for all of them, so they are not tenant candidates.",
+                        "    if (tenantLabel(context.url.hostname, TENANCY) && !context.locals.tenant) {",
+                        '      return new Response("Not found", { status: 404 });',
+                        "    }",
+                    ]
+                    : []),
+                ...(portal
+                    ? [
+                        "    // Route guard: the declarative prefix→roles table from your config.",
+                        "    // An /api/* route always answers in JSON — redirecting fetch() to an",
+                        "    // HTML login page returns 200 and markup, which reads as success.",
+                        "    const decision = portalGuard(",
+                        "      context.url.pathname,",
+                        "      context.locals.portalUser,",
+                        "      PORTAL_GUARD,",
+                        "    );",
+                        "    if (!decision) return undefined;",
+                        '    if (decision.kind === "redirect") return context.redirect(decision.location);',
+                        "    return guardResponse(decision) ?? undefined;",
+                    ]
+                    : ["    return undefined;"]),
                 "  },",
             ]
             : []),
@@ -571,9 +588,18 @@ export function generateAstroidMiddleware(config) {
                 "  // redirect — so links built from Astro.url stay correct.",
                 "  //",
                 "  // An unknown subdomain is YOUR decision: `resolveTenant` returning null",
-                "  // falls through to the ordinary site below. Return a 404 from `guard`",
-                "  // instead if a stranger's subdomain should not render your homepage.",
+                "  // falls through to the ordinary site below — or 404s first, when the",
+                '  // config sets `tenancy.unknown: "404"` (see the guard above).',
                 "  rewrite: (context) => {",
+                ...(Object.keys(tenancy.apps ?? {}).length
+                    ? [
+                        "    // First-party app hosts (config `tenancy.apps`): a static label→prefix",
+                        "    // map, checked before the tenant — an app exists whether or not any",
+                        "    // tenant does, and needs no lookup.",
+                        "    const app = appPrefix(context.url.hostname, TENANCY);",
+                        "    if (app) return `${app}${context.url.pathname}`;",
+                    ]
+                    : []),
                 "    const tenant = context.locals.tenant;",
                 `    return tenant ? \`${rewritePrefix}/\${tenant.slug}\${context.url.pathname}\` : undefined;`,
                 "  },",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "astroidjs",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "description": "Astroid — an opinionated meta-framework over Louise Toolkit and Astro for building editable, multi-editor sites on Cloudflare Workers.",
   "keywords": [
     "astro",
@@ -60,7 +60,7 @@
     "access": "public"
   },
   "dependencies": {
-    "louise-toolkit": "0.24.0"
+    "louise-toolkit": "0.25.1"
   },
   "devDependencies": {
     "@types/node": "^24.13.3",