@goodbones/browser 0.1.0-beta.1

package/src/server/serve.ts

@@ -0,0 +1,100 @@
+import { createReadStream, existsSync, statSync } from "node:fs";
+import { createServer, type Server } from "node:http";
+import type { AddressInfo } from "node:net";
+import * as path from "node:path";
+
+import { type Handler } from "./handler.js";
+
+// The bin's server: the prebuilt page from `build/site`, and the handler's
+// routes in front of it. No framework — the page is static files and the
+// data is four routes.
+
+const TYPES: Readonly<Record<string, string>> = {
+  ".html": "text/html; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".mjs": "text/javascript; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".ico": "image/x-icon",
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+  ".txt": "text/plain; charset=utf-8",
+  ".map": "application/json; charset=utf-8",
+};
+
+export type ServeOptions = {
+  readonly siteDir: string;
+  readonly handler: Handler;
+  readonly port: number;
+  readonly host: string;
+};
+
+export type Served = {
+  readonly server: Server;
+  readonly url: string;
+  readonly close: () => Promise<void>;
+};
+
+// A path inside the site directory, or nothing for one that escapes it.
+const fileFor = (siteDir: string, pathname: string): string | null => {
+  const decoded = decodeURIComponent(pathname);
+  const wanted = decoded.endsWith("/") ? `${decoded}index.html` : decoded;
+  const resolved = path.resolve(siteDir, `.${wanted}`);
+  if (!resolved.startsWith(siteDir)) return null;
+  if (existsSync(resolved) && statSync(resolved).isFile()) return resolved;
+  // `/architecture` for `architecture.html`, as the build's `format: file`
+  // emits pages.
+  const asPage = `${resolved}.html`;
+  if (existsSync(asPage) && statSync(asPage).isFile()) return asPage;
+  return null;
+};
+
+export const serve = (options: ServeOptions): Promise<Served> =>
+  new Promise((resolve, reject) => {
+    const siteDir = path.resolve(options.siteDir);
+    const server = createServer((request, response) => {
+      options
+        .handler(request, response)
+        .then((handled) => {
+          if (handled) return;
+          const url = new URL(request.url ?? "/", "http://localhost");
+          const file = fileFor(siteDir, url.pathname);
+          if (file === null) {
+            response.statusCode = 404;
+            response.setHeader("content-type", "text/plain; charset=utf-8");
+            response.end("not found");
+            return;
+          }
+          response.statusCode = 200;
+          response.setHeader(
+            "content-type",
+            TYPES[path.extname(file)] ?? "application/octet-stream",
+          );
+          response.setHeader("cache-control", "no-cache");
+          createReadStream(file).pipe(response);
+        })
+        .catch((cause: unknown) => {
+          response.statusCode = 500;
+          response.setHeader("content-type", "text/plain; charset=utf-8");
+          response.end(String(cause));
+        });
+    });
+    server.once("error", reject);
+    server.listen(options.port, options.host, () => {
+      const address = server.address() as AddressInfo;
+      const host = options.host === "0.0.0.0" || options.host === "::" ? "localhost" : options.host;
+      resolve({
+        server,
+        url: `http://${host}:${String(address.port)}/`,
+        close: () =>
+          new Promise<void>((done) => {
+            server.closeAllConnections();
+            server.close(() => {
+              done();
+            });
+          }),
+      });
+    });
+  });

package/src/server/site.ts

@@ -0,0 +1,6 @@
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+
+// Where `astro build` put the page: `build/site`, beside this module's
+// `build/esm`. The bin serves it; a static export copies it.
+export const SITE_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../site");

package/src/server/source.ts

@@ -0,0 +1,89 @@
+import { collect, type Collected, type CollectOptions } from "./collect.js";
+import { watchRepository } from "./watch.js";
+
+// What the handler serves: the two models, computed once and kept until the
+// repository changes, and a feed of those changes for the page to refetch on.
+
+export type Change = { readonly files: ReadonlyArray<string>; readonly at: string };
+
+export type Source = {
+  readonly current: () => Promise<Collected>;
+  readonly subscribe: (listener: (change: Change) => void) => () => void;
+  readonly invalidate: (files: ReadonlyArray<string>) => void;
+  readonly live: boolean;
+  readonly close: () => void;
+};
+
+export type SourceOptions = CollectOptions & {
+  readonly watch?: boolean | undefined;
+  readonly debounceMs?: number | undefined;
+  // For tests: what to compute instead of walking the repository.
+  readonly compute?: (() => Promise<Collected>) | undefined;
+};
+
+export const makeSource = (options: SourceOptions): Source => {
+  const listeners = new Set<(change: Change) => void>();
+  let cached: Promise<Collected> | null = null;
+  const compute = options.compute ?? (() => collect(options));
+
+  const current = (): Promise<Collected> => {
+    if (cached === null) {
+      const started = compute();
+      cached = started;
+      // A failed computation is not kept: the next request tries again,
+      // after the author has fixed the manifest.
+      started.catch(() => {
+        if (cached === started) cached = null;
+      });
+    }
+    return cached;
+  };
+
+  const invalidate = (files: ReadonlyArray<string>): void => {
+    cached = null;
+    const change: Change = { files, at: new Date().toISOString() };
+    for (const listener of listeners) listener(change);
+  };
+
+  let stopWatching: (() => void) | null = null;
+  if (options.watch === true) {
+    // The extensions and the ledger directory come from the policy, once it
+    // has loaded; until then every change under the roots counts.
+    stopWatching = watchRepository({
+      repoRoot: options.repoRoot,
+      extensions: [".ts", ".tsx", ".mts", ".cts", ".js", ".jsx", ".mjs", ".cjs"],
+      ledgerDir: ".architecture-campaigns",
+      debounceMs: options.debounceMs,
+      onChange: invalidate,
+    });
+    void current()
+      .then((collected) => {
+        stopWatching?.();
+        stopWatching = watchRepository({
+          repoRoot: options.repoRoot,
+          extensions: [".ts", ".tsx", ".mts", ".cts", ".js", ".jsx", ".mjs", ".cjs"],
+          ledgerDir: collected.campaigns.ledgerDir,
+          debounceMs: options.debounceMs,
+          onChange: invalidate,
+        });
+      })
+      .catch(() => {
+        // Keep the first watcher: the manifest that failed to load is one of
+        // the files it watches, and its fix is the next change.
+      });
+  }
+
+  return {
+    current,
+    subscribe: (listener) => {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    invalidate,
+    live: options.watch === true,
+    close: () => {
+      stopWatching?.();
+      listeners.clear();
+    },
+  };
+};

package/src/server/vite-plugin.ts

@@ -0,0 +1,32 @@
+import type { Plugin } from "vite";
+
+import { makeHandler } from "./handler.js";
+import { makeSource } from "./source.js";
+
+// For working on the browsers themselves: `astro dev` in this package, with
+// the routes mounted on Vite's own server over whichever repository
+// `GOODBONES_REPO` names (this one, by default). The page then has Vite's
+// hot reload for its own source and the feed for the repository's.
+export type BrowserPluginOptions = {
+  readonly repoRoot: string;
+  readonly roots: ReadonlyArray<string>;
+  readonly configFilename?: string | undefined;
+};
+
+export const goodbonesBrowser = (options: BrowserPluginOptions): Plugin => ({
+  name: "goodbones-browser",
+  configureServer(server) {
+    const source = makeSource({ ...options, watch: true });
+    const handle = makeHandler(source);
+    server.middlewares.use((request, response, next) => {
+      handle(request, response)
+        .then((handled) => {
+          if (!handled) next();
+        })
+        .catch(next);
+    });
+    server.httpServer?.once("close", () => {
+      source.close();
+    });
+  },
+});

package/src/server/watch.ts

@@ -0,0 +1,65 @@
+import { type FSWatcher, watch } from "node:fs";
+import * as path from "node:path";
+
+// The repository, watched: a change to a source file, a manifest or a ledger
+// is what redraws the browsers. Node's recursive watcher, so no dependency;
+// events are debounced, since an editor's save is several of them.
+
+const IGNORED = ["node_modules", ".git", "build", "dist", ".nx", ".astro", "coverage"];
+
+export type WatchOptions = {
+  readonly repoRoot: string;
+  // File extensions that count as source, with their dots.
+  readonly extensions: ReadonlyArray<string>;
+  // Repo-relative directory of the ledgers.
+  readonly ledgerDir: string;
+  readonly debounceMs?: number | undefined;
+  readonly onChange: (files: ReadonlyArray<string>) => void;
+};
+
+const MANIFEST = /(^|\/)architecture(\.config)?\.(ya?ml|json|mjs)$/;
+
+export const isRelevant = (
+  file: string,
+  extensions: ReadonlyArray<string>,
+  ledgerDir: string,
+): boolean => {
+  const segments = file.split("/");
+  if (segments.some((segment) => IGNORED.includes(segment))) return false;
+  if (MANIFEST.test(file)) return true;
+  if (ledgerDir !== "" && (file === ledgerDir || file.startsWith(`${ledgerDir}/`))) return true;
+  return extensions.includes(path.extname(file));
+};
+
+export const watchRepository = (options: WatchOptions): (() => void) => {
+  const delay = options.debounceMs ?? 150;
+  let pending = new Set<string>();
+  let timer: NodeJS.Timeout | null = null;
+  const flush = (): void => {
+    timer = null;
+    const files = [...pending].sort();
+    pending = new Set();
+    if (files.length > 0) options.onChange(files);
+  };
+  let watcher: FSWatcher | null = null;
+  try {
+    watcher = watch(options.repoRoot, { recursive: true }, (_event, filename) => {
+      if (filename === null) return;
+      const file = String(filename).split(path.sep).join("/");
+      if (!isRelevant(file, options.extensions, options.ledgerDir)) return;
+      pending.add(file);
+      if (timer !== null) clearTimeout(timer);
+      timer = setTimeout(flush, delay);
+    });
+    watcher.on("error", () => {
+      // A watcher that dies leaves the page static; the next request still
+      // recomputes, so nothing is wrong, only not live.
+    });
+  } catch {
+    watcher = null;
+  }
+  return () => {
+    if (timer !== null) clearTimeout(timer);
+    watcher?.close();
+  };
+};