@jxsuite/server 2.0.0 → 2.1.0

package/src/site-output.ts

@@ -0,0 +1,111 @@
+/**
+ * Serve a project's BUILT output at the routes the built pages actually reference.
+ *
+ * A built page is written for its published origin: `dist/basics/counter/index.html` links to
+ * `/basics/counter` and pulls `/components/fetch-demo.css`, both root-absolute. Studio's `View:
+ * Open in Browser` used to hand the browser `…/dist/basics/counter/index.html` — the file's path
+ * rather than the page's URL — and the consequences were exactly what those two absolutes predict:
+ * the HTML arrived, every stylesheet and script 404'd against the server root, and the first link
+ * the reader clicked left the built site entirely. The page loaded and nothing else worked.
+ *
+ * So the fix is not in the URL alone. A site is only "as if published" when it is served AT A ROOT,
+ * which is what this module does for whichever project a server is showing: `/basics/counter` and
+ * `/basics/counter/` both resolve to `<outDir>/basics/counter/index.html`, `/` to
+ * `<outDir>/index.html`, and every asset the page names resolves the same way it will in
+ * production.
+ *
+ * **It is a LAST resort, deliberately.** `serveProjectFile` tries the mounts, the absolute path,
+ * the root-relative source file and `public/` before it gets here, so this step can only answer
+ * requests that were already going to 404 — it can never shadow a source file that resolves today.
+ * That property is what makes it safe to mount for every project on every server rather than behind
+ * a flag.
+ *
+ * `jx dev`'s own `createDistMiddleware` is a different thing and stays: it runs BEFORE the source
+ * files (a site project's dev server is showing the built site, not its sources) and it injects the
+ * live-reload client. This one is the fallback for the servers that are showing a project's sources
+ * — the monorepo dev server and the desktop's project server — where the built site is something a
+ * reader is visiting, not the thing being edited.
+ */
+
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+import { serveContained } from "./net-guard.ts";
+
+/** What `project.json` says the build writes to, cached per root against its mtime. */
+const outDirCache = new Map<string, { mtime: number; outDir: string | null }>();
+
+/** Reset the output-directory cache (test hook). */
+export function resetSiteOutput(): void {
+  outDirCache.clear();
+}
+
+/**
+ * The project's absolute output directory, or `null` when it is not a site project.
+ *
+ * Read from `project.json` rather than assumed to be `dist`, because `build.outDir` is a documented
+ * setting and a project that moved it would otherwise be served its stale old output for ever. The
+ * mtime guard is the same idiom `jx-mounts.ts` uses: a config edit is picked up, a request is not a
+ * file read.
+ */
+export function siteOutDir(projectRoot: string): string | null {
+  const configPath = resolve(projectRoot, "project.json");
+  if (!existsSync(configPath)) {
+    return null;
+  }
+  const { mtimeMs } = statSync(configPath);
+  const cached = outDirCache.get(projectRoot);
+  if (cached && cached.mtime === mtimeMs) {
+    return cached.outDir;
+  }
+  let outDir: string | null = null;
+  try {
+    const config = JSON.parse(readFileSync(configPath, "utf8")) as {
+      build?: { outDir?: unknown };
+    };
+    const declared = config.build?.outDir;
+    outDir = resolve(projectRoot, typeof declared === "string" && declared ? declared : "dist");
+  } catch {
+    // An unparseable project.json is the editor's problem to report, not this server's to guess
+    // At. No output directory means this fallback simply declines, and the request 404s as before.
+    outDir = null;
+  }
+  outDirCache.set(projectRoot, { mtime: mtimeMs, outDir });
+  return outDir;
+}
+
+/**
+ * Serve `decodedPath` from the project's built output, or `null` when it names nothing there.
+ *
+ * The mapping is the compiler's own, read backwards: a request for a route gets that route's
+ * `index.html` whether or not the reader typed the trailing slash, because a built site is browsed
+ * by its routes and a reader does not know which spelling the `trailingSlash` setting produced.
+ * `<route>.html` is tried too, which is what `trailingSlash: "never"` writes.
+ */
+export async function serveSiteOutput(
+  decodedPath: string,
+  projectRoot: string,
+): Promise<Response | null> {
+  const outDir = siteOutDir(projectRoot);
+  if (!outDir || !existsSync(outDir)) {
+    return null;
+  }
+  const rel = decodedPath.replace(/^\/+/, "");
+  const direct = resolve(outDir, `./${rel}`);
+
+  // A file (an asset, or a page under `trailingSlash: "never"`).
+  if (existsSync(direct) && statSync(direct).isFile()) {
+    return serveContained(direct, outDir);
+  }
+  // A route: its directory's index.html, with or without the trailing slash the reader typed.
+  const asIndex = join(direct, "index.html");
+  if (existsSync(asIndex)) {
+    return serveContained(asIndex, outDir);
+  }
+  // `trailingSlash: "never"` writes `<route>.html` beside its siblings.
+  const asHtml = `${direct.replace(/\/+$/, "")}.html`;
+  if (rel !== "" && existsSync(asHtml)) {
+    return serveContained(asHtml, outDir);
+  }
+  return null;
+}

package/src/site-preview.ts

@@ -0,0 +1,106 @@
+/**
+ * The built site on its own origin — what `View: Open in Browser` opens.
+ *
+ * A built page is written for its published origin and addresses everything ROOT-absolutely:
+ * `dist/basics/fetch/index.html` links to `/basics/counter` and loads `/components/fetch-demo.js`.
+ * So it is only browsable when those paths resolve against the OUTPUT — and on the editor's server
+ * they resolve against the project's SOURCES, because that is the editor's whole job. The two are
+ * the same URLs holding different bytes: `/components/fetch-demo.js` is the module of formulas the
+ * compiler reads in the sources, and the custom-element definition the page needs in the output.
+ *
+ * Serving the output as a 404 fallback on the editor's server looks like it works — the page and
+ * the assets that exist in only one of the two spaces arrive — and then the reader gets the source
+ * module for anything that exists in both. Measured: the page rendered, `customElements.get(...)`
+ * was null, and nothing on it did anything. No ordering fixes that; one origin cannot hold two
+ * meanings for one path.
+ *
+ * Hence a second server, rooted AT the output directory, where every path has exactly the meaning
+ * the published site gives it. Nothing is injected — no live-reload client, no rewriting — because
+ * the point is to hand the reader the bytes that will be deployed. `View: Open in Browser` builds,
+ * then opens a URL here.
+ *
+ * It is bound to loopback and serves only files under the output directory, which is the artefact
+ * the author is about to publish; it carries none of the editor's privileged routes and needs no
+ * token. Servers are reused per project root — opening ten pages opens one port — and they live for
+ * the life of the process: the map is keyed by root and two windows on one project share an origin,
+ * so no single window's teardown may close it.
+ */
+
+import { serveSiteOutput, siteOutDir } from "./site-output.ts";
+import { problem } from "./problem.ts";
+
+/** A running preview server for one project. */
+export interface SitePreview {
+  /** Origin to prefix a route with, e.g. `http://127.0.0.1:41234`. */
+  origin: string;
+  port: number;
+}
+
+interface Running extends SitePreview {
+  server: { stop: (closeActiveConnections?: boolean) => void };
+}
+
+/** One server per project root — a second `Open in Browser` reuses the first one's port. */
+const running = new Map<string, Running>();
+
+/**
+ * Start (or reuse) the preview server for `projectRoot`, or `null` when there is nothing to serve:
+ * not a site project, or a site nobody has built yet. A caller that has just built gets a server;
+ * one that has not gets the honest answer rather than a port that 404s everything.
+ */
+export function startSitePreview(projectRoot: string): SitePreview | null {
+  const outDir = siteOutDir(projectRoot);
+  if (!outDir) {
+    return null;
+  }
+  const existing = running.get(projectRoot);
+  if (existing) {
+    return { origin: existing.origin, port: existing.port };
+  }
+  const server = Bun.serve({
+    fetch: async (req: Request) => {
+      const url = new URL(req.url);
+      let decoded: string;
+      try {
+        decoded = decodeURIComponent(url.pathname);
+      } catch {
+        return problem("invalidRequest", "Bad request");
+      }
+      const res = await serveSiteOutput(decoded, projectRoot);
+      if (res) {
+        return res;
+      }
+      /* The site's OWN 404 page when it has one, at the status the published site would send.
+         A generated `404.html` is a page the author wrote; showing it is more faithful than
+         showing this server's opinion, and it is how the static hosts serve it. */
+      const notFound = await serveSiteOutput("/404.html", projectRoot);
+      return notFound
+        ? new Response(notFound.body, { headers: notFound.headers, status: 404 })
+        : problem("notFound", "Not found");
+    },
+    hostname: "127.0.0.1",
+    port: 0,
+  });
+  // `server.url` rather than `server.port`: the origin is the thing being handed to a browser, and
+  // Reading it from the server that is actually listening cannot disagree with it.
+  const entry: Running = {
+    origin: server.url.origin,
+    port: Number(server.url.port),
+    server,
+  };
+  running.set(projectRoot, entry);
+  return { origin: entry.origin, port: entry.port };
+}
+
+/** The origin already serving `projectRoot`, without starting one. */
+export function sitePreviewOrigin(projectRoot: string): string | null {
+  return running.get(projectRoot)?.origin ?? null;
+}
+
+/** Stop every preview server (process teardown, and the hook tests close their ports with). */
+export function stopSitePreviews(): void {
+  for (const entry of running.values()) {
+    entry.server.stop(true);
+  }
+  running.clear();
+}