@hajimism/dek 0.1.0

package/src/server/routes.ts

@@ -0,0 +1,286 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { fileInside, readTheme } from "../core/assets.ts";
+import { DekError, errorFields } from "../core/error.ts";
+import { escapeAttr, escapeHtml } from "../core/escape.ts";
+import { deckSlides, htmlShell, slidePlace, stampSlide } from "../core/html.ts";
+import { decodePosition } from "../core/live-protocol.ts";
+import { markedPositions, toggleMark } from "../core/marks.ts";
+import type { Project, ProjectDeck } from "../core/resolve.ts";
+import { voiceCacheFile } from "../core/voice.ts";
+import { deckRoutePath, parseDeckRoute, splitDeckPath, type VoiceFile } from "../runtime/routes.ts";
+import { EVENT_EXPOSURE, type Exposure, mayRead, type Route } from "./auth.ts";
+import type { EventHub } from "./hub.ts";
+import type { RoomClient, Rooms } from "./rooms.ts";
+
+/** What a socket carries: its deck's room, and whether it may move the room. */
+export type WsData = { room: string; control: boolean };
+
+/** What the routes read: the server's scope, its project as it is now, and its state. */
+export type RouteContext = {
+  /** The deck a server scoped to one deck serves. */
+  scopedDeckName?: string;
+  deckDir?: string;
+  project(): Project;
+  hub: EventHub;
+  rooms: Rooms<RoomClient>;
+  /** A deck's live page. */
+  deckPage(dir: string, mode: "player" | "presenter"): Response;
+  /** The project's list of decks. */
+  indexPage(): Response;
+  /** Turn the request into a socket; false when it asked for none. */
+  upgrade(req: Request, data: WsData): boolean;
+};
+
+export type Routed = {
+  route: Route;
+  respond: (seen: Exposure) => Response | undefined | Promise<Response | undefined>;
+};
+
+/**
+ * Which route a request names, and how it answers. The server checks the route's exposure
+ * before it answers, so no route guards itself; `seen` is what the request is cleared for.
+ */
+export function routeRequest(req: Request, ctx: RouteContext): Routed {
+  const url = new URL(req.url);
+  const split = splitDeckPath(url.pathname, ctx.scopedDeckName);
+  if (!split) {
+    return url.pathname === "/" || url.pathname === ""
+      ? { route: "index", respond: () => ctx.indexPage() }
+      : MISSING;
+  }
+  const route = parseDeckRoute(split.rest);
+  if (!route) {
+    return MISSING;
+  }
+  const { deckName } = split;
+  const deck = ctx.project().decks.find((entry) => entry.name === deckName);
+  // A server scoped to a deck serves its page even while the script fails to parse.
+  const dir = ctx.scopedDeckName !== undefined ? ctx.deckDir : deck?.dir;
+  switch (route.kind) {
+    case "socket":
+      return {
+        route: "socket",
+        respond: (seen) =>
+          ctx.upgrade(req, { room: deckName, control: seen === "presenter" })
+            ? undefined
+            : new Response("Expected WebSocket", { status: 400 }),
+      };
+    case "events":
+      return { route: "events", respond: (seen) => sseResponse(ctx.hub, deckName, seen) };
+    case "slide":
+      return {
+        route: "slide",
+        respond: () => {
+          // A slide the script does not list has no place in the deck, so no page shows it.
+          const sections = deck?.deck.sections ?? [];
+          const index = sections.findIndex((section) => section.slug === route.slug);
+          const html = deck && index >= 0 && deckSlides(deck).written(route.slug);
+          return html
+            ? htmlResponse(
+                stampSlide(html, { slug: route.slug, place: slidePlace(sections, index) }),
+              )
+            : notFound();
+        },
+      };
+    case "theme":
+      return {
+        route: "theme",
+        respond: () =>
+          deck
+            ? new Response(readTheme(deck.dir, false), {
+                headers: {
+                  "content-type": "text/css; charset=utf-8",
+                  "cache-control": "no-store",
+                },
+              })
+            : notFound(),
+      };
+    case "voice":
+      return { route: "voice", respond: () => voiceResponse(deck, route.file) };
+    case "current":
+    case "goto":
+      return {
+        route: "control",
+        respond: () => navResponse(req, { room: deckName, action: route.kind }, ctx.rooms),
+      };
+    case "marks":
+      return {
+        route: "marks",
+        respond: () =>
+          deck ? marksResponse(req, ctx.project().root, deck) : jsonNotFound(deckName),
+      };
+    case "asset": {
+      const asset = dir && safeDeckAsset(dir, route.path);
+      return asset
+        ? {
+            route: "asset",
+            respond: () =>
+              new Response(Bun.file(asset), { headers: { "cache-control": "no-store" } }),
+          }
+        : MISSING;
+    }
+    case "player":
+    case "presenter": {
+      const mode = route.kind;
+      return dir ? { route: mode, respond: () => ctx.deckPage(dir, mode) } : MISSING;
+    }
+  }
+}
+
+const MISSING: Routed = { route: "missing", respond: notFound };
+
+function voiceResponse(deck: ProjectDeck | undefined, file: VoiceFile): Response {
+  const path = deck && voiceCacheFile(deck.dir, file);
+  if (!path || !existsSync(path)) {
+    return notFound();
+  }
+  return new Response(Bun.file(path), {
+    headers: {
+      "content-type": file === "audio.wav" ? "audio/wav" : "application/json; charset=utf-8",
+      "cache-control": "no-store",
+    },
+  });
+}
+
+/** `dekc current` and `dekc goto`: where a deck stands, or send it to a slide. */
+async function navResponse(
+  req: Request,
+  nav: { room: string; action: "current" | "goto" },
+  rooms: Rooms<RoomClient>,
+): Promise<Response> {
+  if (nav.action === "current" && req.method === "GET") {
+    return jsonResponse({ ok: true, ...rooms.current(nav.room) });
+  }
+  if (nav.action === "goto" && req.method === "POST") {
+    let body: { slug?: string } = {};
+    try {
+      body = (await req.json()) as { slug?: string };
+    } catch {
+      body = {};
+    }
+    const slug = body.slug?.trim();
+    if (!slug) {
+      return jsonResponse(
+        { ok: false, error: { message: 'the request names no slide: send {"slug": "<slug>"}' } },
+        400,
+      );
+    }
+    const moved = rooms.goto(nav.room, slug);
+    return moved.ok
+      ? jsonResponse({ ok: true, ...moved.at })
+      : jsonResponse({ ok: false, error: { message: moved.message } }, 404);
+  }
+  return new Response("Method not allowed", { status: 405 });
+}
+
+/**
+ * The presenter's marks on a deck: GET lists where they are, and a POST of a position marks the
+ * beat there, or unmarks it when it is marked. Both answer with where the deck's marks are now.
+ */
+async function marksResponse(req: Request, root: string, deck: ProjectDeck): Promise<Response> {
+  if (req.method === "GET") {
+    return jsonResponse({ ok: true, positions: markedPositions(root, deck) });
+  }
+  if (req.method !== "POST") {
+    return new Response("Method not allowed", { status: 405 });
+  }
+  let body: unknown;
+  try {
+    body = await req.json();
+  } catch {
+    body = undefined;
+  }
+  const position = decodePosition(body);
+  if (!position) {
+    return jsonResponse(
+      {
+        ok: false,
+        error: { message: 'the request names no beat: send {"slideIndex": n, "beatIndex": n}' },
+      },
+      400,
+    );
+  }
+  try {
+    return jsonResponse({ ok: true, ...toggleMark(root, deck, position) });
+  } catch (error) {
+    if (!(error instanceof DekError)) {
+      throw error;
+    }
+    return jsonResponse({ ok: false, error: errorFields(error) }, 404);
+  }
+}
+
+function jsonNotFound(deckName: string): Response {
+  return jsonResponse({ ok: false, error: { message: `deck "${deckName}" not found` } }, 404);
+}
+
+function safeDeckAsset(deckDir: string, relative: string): string | undefined {
+  const root = join(deckDir, "assets");
+  const found = fileInside(join(root, relative), root);
+  return found.kind === "file" ? found.path : undefined;
+}
+
+function jsonResponse(body: unknown, status = 200): Response {
+  return new Response(`${JSON.stringify(body)}\n`, {
+    status,
+    headers: { "content-type": "application/json; charset=utf-8" },
+  });
+}
+
+export function htmlResponse(html: string, status = 200): Response {
+  return new Response(html, {
+    status,
+    headers: {
+      "content-type": "text/html; charset=utf-8",
+      "cache-control": "no-store",
+    },
+  });
+}
+
+export function errorPage(error: unknown): string {
+  const { message, hint } = errorFields(error);
+  return htmlShell({
+    title: "dek",
+    body: `<pre>${escapeHtml(hint ? `${message}\n${hint}` : message)}</pre>`,
+  });
+}
+
+/** The project's list of decks, each with its presenter view, and the decks that failed to load. */
+export function renderIndexHtml(
+  decks: Array<{ name: string; title: string }>,
+  failed: Array<{ name: string }> = [],
+): string {
+  const items = decks
+    .map(
+      (deck) =>
+        `<li><a href="${escapeAttr(deckRoutePath(deck.name, { kind: "player" }))}">${escapeHtml(deck.name)} — ${escapeHtml(deck.title)}</a> · <a href="${escapeAttr(deckRoutePath(deck.name, { kind: "presenter" }))}">presenter</a></li>`,
+    )
+    .join("");
+  const failedItems = failed.map((entry) => `<li>${escapeHtml(entry.name)}</li>`).join("");
+  const failedBlock = failed.length > 0 ? `<h2>failed</h2><ul>${failedItems}</ul>` : "";
+  return htmlShell({
+    title: "dek",
+    body: `<h1>decks</h1>
+  <ul>${items}</ul>
+  ${failedBlock}`,
+  });
+}
+
+/** A deck's event stream, carrying only the events the request is cleared to read. */
+function sseResponse(hub: EventHub, deckName: string, seen: Exposure): Response {
+  return new Response(
+    hub.sse((event) => event.deck === deckName && mayRead(seen, EVENT_EXPOSURE[event.type])),
+    {
+      headers: {
+        "content-type": "text/event-stream; charset=utf-8",
+        "cache-control": "no-store",
+        connection: "keep-alive",
+      },
+    },
+  );
+}
+
+function notFound(): Response {
+  return new Response("Not found", { status: 404 });
+}

package/src/server/serial.ts

@@ -0,0 +1,25 @@
+export function createSerialTask(run: () => Promise<void>): () => void {
+  let running = false;
+  let queued = false;
+  return () => {
+    if (running) {
+      queued = true;
+      return;
+    }
+    running = true;
+    void (async () => {
+      try {
+        do {
+          queued = false;
+          try {
+            await run();
+          } catch {
+            /* keep draining the trailing run */
+          }
+        } while (queued);
+      } finally {
+        running = false;
+      }
+    })();
+  };
+}

package/src/server/watch.ts

@@ -0,0 +1,308 @@
+import { existsSync, watch } from "node:fs";
+import { basename } from "node:path";
+import { deckPaths } from "../core/deck-paths.ts";
+import { type Diagnostic, errorDiagnostic } from "../core/diagnostic.ts";
+import { DekError, errorFields } from "../core/error.ts";
+import { lintDeckAsync, lintProject, unreadableScriptDiagnostics } from "../core/lint.ts";
+import type { LiveEvent } from "../core/live-protocol.ts";
+import { ScriptError } from "../core/parse.ts";
+import type { PlaywrightRunner } from "../core/playwright.ts";
+import { resolveDeck } from "../core/resolve.ts";
+import { type SyncResult, syncDeck } from "../core/sync.ts";
+import { lintVisualDeck } from "../core/visual.ts";
+import {
+  type DiagnoseScope,
+  diffSnapshot,
+  mergeScope,
+  slideMtimes,
+  takeSnapshot,
+} from "./deck-snapshot.ts";
+import { createSerialTask } from "./serial.ts";
+
+export type Stoppable = { close: () => void };
+
+/** How often a watcher re-scans for edits fs.watch missed; shared by the deck and project polls. */
+export const POLL_INTERVAL_MS = 2000;
+
+type WatchDeckOptions = {
+  visual?: boolean;
+  visualRunner?: PlaywrightRunner;
+  pollIntervalMs?: number;
+  setInterval?: typeof setInterval;
+  clearInterval?: typeof clearInterval;
+  synthVoice?: () => Promise<void>;
+};
+
+/**
+ * Watch one deck and `emit` what its open pages must do: each scan diffs the deck's files
+ * against the last scan (see `diffSnapshot`), then syncs, lints, and synthesizes as it says.
+ */
+export function watchDeck(
+  deckDir: string,
+  emit: (event: LiveEvent) => void,
+  options: WatchDeckOptions = {},
+): Stoppable {
+  let snapshot = takeSnapshot(deckDir);
+  let closed = false;
+  const isClosed = () => closed;
+  const diagnose = createDiagnose(deckDir, options);
+  const requestDiagnostics = createDiagnosticsQueue(diagnose, emit, isClosed);
+  const synthVoice = createVoiceSynth(deckDir, emit, isClosed, options.synthVoice);
+
+  const syncScript = (announceEmpty: boolean): void => {
+    const event = syncEvent(syncQuietly(deckDir), announceEmpty);
+    // A sync event reloads the whole page, so the slides it wrote need no reload-slide.
+    snapshot = { ...snapshot, slides: slideMtimes(deckDir) };
+    if (event) {
+      emit(event);
+    }
+  };
+
+  const scanOnce = (): void => {
+    const next = takeSnapshot(deckDir);
+    const change = diffSnapshot(snapshot, next);
+    snapshot = next;
+    if (change.sync) {
+      syncScript(true);
+    }
+    for (const event of change.events) {
+      emit(event);
+    }
+    if (change.diagnose) {
+      requestDiagnostics(change.diagnose);
+    }
+    if (change.synth) {
+      synthVoice();
+    }
+  };
+
+  const scan = (): void => {
+    if (closed) {
+      return;
+    }
+    // A scan runs from a timer, where a throw would end the server: a folder that turned into a
+    // link out of the project, or one deleted between the listing and the read, is reported.
+    try {
+      scanOnce();
+    } catch (error) {
+      if (!closed && existsSync(deckDir)) {
+        emit({ type: "diagnostics", diagnostics: [watchErrorDiagnostic(error)] });
+      }
+    }
+  };
+
+  const triggers = startScanTriggers(deckDir, scan, options, isClosed);
+  // A script written before the server started still gets its skeletons.
+  syncScript(false);
+  requestDiagnostics({});
+
+  return {
+    close() {
+      closed = true;
+      triggers.close();
+    },
+  };
+}
+
+/**
+ * Run `scan` shortly after fs.watch reports an edit, and on a poll for the edits it misses; a
+ * watcher that fails turns the poll on even when it was off.
+ */
+function startScanTriggers(
+  deckDir: string,
+  scan: () => void,
+  options: WatchDeckOptions,
+  isClosed: () => boolean,
+): Stoppable {
+  const startInterval = options.setInterval ?? setInterval;
+  const stopInterval = options.clearInterval ?? clearInterval;
+  let debounce: ReturnType<typeof setTimeout> | undefined;
+  let timer: ReturnType<typeof setInterval> | undefined;
+
+  const schedule = (): void => {
+    if (debounce) {
+      clearTimeout(debounce);
+    }
+    debounce = setTimeout(scan, 20);
+  };
+  const startPoll = (ms: number): void => {
+    if (timer || isClosed() || ms <= 0) {
+      return;
+    }
+    timer = startInterval(scan, ms);
+  };
+
+  const watcher = watch(deckDir, { recursive: true }, schedule);
+  startPoll(options.pollIntervalMs ?? POLL_INTERVAL_MS);
+  if (typeof watcher.on === "function") {
+    watcher.on("error", () => {
+      startPoll(options.pollIntervalMs || POLL_INTERVAL_MS);
+    });
+  }
+
+  return {
+    close() {
+      if (debounce) {
+        clearTimeout(debounce);
+      }
+      if (timer) {
+        stopInterval(timer);
+      }
+      watcher.close();
+    },
+  };
+}
+
+/** One diagnostics pass over the deck: the lint rules, then the visual pass when it is on. */
+function createDiagnose(
+  deckDir: string,
+  options: WatchDeckOptions,
+): (scope: DiagnoseScope) => Promise<Diagnostic[]> {
+  // A browser that is not installed turns the visual pass off until one is found again.
+  let visualEnabled = options.visual === true;
+  return async (scope) => {
+    const { diagnostics, resolved } = await lintPass(deckDir);
+    if (visualEnabled && resolved) {
+      try {
+        const visual = await lintVisualDeck(resolved, {
+          ...(scope.slug !== undefined ? { slug: scope.slug } : {}),
+          ...(options.visualRunner ? { runner: options.visualRunner } : {}),
+        });
+        visualEnabled = visual !== null;
+        diagnostics.push(...(visual ?? []));
+      } catch (error) {
+        diagnostics.push(watchErrorDiagnostic(error));
+      }
+    }
+    return diagnostics;
+  };
+}
+
+/** The lint rules over the deck, and the deck as resolved when it resolves. */
+async function lintPass(
+  deckDir: string,
+): Promise<{ diagnostics: Diagnostic[]; resolved?: ReturnType<typeof resolveDeck> }> {
+  let resolved: ReturnType<typeof resolveDeck> | undefined;
+  try {
+    resolved = resolveDeck(deckDir);
+    return {
+      diagnostics: [...lintProject(resolved.project), ...(await lintDeckAsync(resolved))],
+      resolved,
+    };
+  } catch (error) {
+    // A script that does not read says every reason at once, as lint does.
+    const diagnostics =
+      error instanceof ScriptError
+        ? unreadableScriptDiagnostics({ scriptPath: deckPaths(deckDir).script, error })
+        : [watchErrorDiagnostic(error)];
+    // A deck that resolved but failed to lint still gets its visual pass.
+    return { diagnostics, ...(resolved ? { resolved } : {}) };
+  }
+}
+
+/** Run one diagnostics pass at a time and `emit` what each finds, unless the watch closed. */
+function createDiagnosticsQueue(
+  diagnose: (scope: DiagnoseScope) => Promise<Diagnostic[]>,
+  emit: (event: LiveEvent) => void,
+  isClosed: () => boolean,
+): (scope: DiagnoseScope) => void {
+  // Edits that land while a pass runs are merged into one pass after it.
+  let pending: DiagnoseScope | undefined;
+  const run = createSerialTask(async () => {
+    const scope = pending;
+    pending = undefined;
+    if (!scope || isClosed()) {
+      return;
+    }
+    const diagnostics = await diagnose(scope);
+    if (!isClosed()) {
+      emit({ type: "diagnostics", diagnostics });
+    }
+  });
+  return (scope) => {
+    pending = mergeScope(pending, scope);
+    run();
+  };
+}
+
+/** Synthesize the deck's voice, one run at a time, and tell its pages the timeline changed. */
+function createVoiceSynth(
+  deckDir: string,
+  emit: (event: LiveEvent) => void,
+  isClosed: () => boolean,
+  synthVoice: (() => Promise<void>) | undefined,
+): () => void {
+  const synth = async (): Promise<boolean> => {
+    if (synthVoice) {
+      await synthVoice();
+      return true;
+    }
+    const { hasVoice } = await import("../core/voice.ts");
+    if (!hasVoice(deckDir)) {
+      return false;
+    }
+    const { synthDeck } = await import("../voice/synth.ts");
+    await synthDeck(deckDir);
+    return true;
+  };
+  return createSerialTask(async () => {
+    try {
+      // A synthesis that outlives the watch has no pages left to tell.
+      if ((await synth()) && !isClosed()) {
+        emit({ type: "timeline" });
+      }
+    } catch (error) {
+      // Voice is optional: an engine that is not running is worth a line, not a stack trace.
+      console.error(voiceFailureLine(error));
+    }
+  });
+}
+
+/**
+ * Create skeletons for sections without slide HTML. A script the author cannot parse yet is
+ * reported by the diagnostics pass that follows, so the failure itself stays quiet here.
+ */
+function syncQuietly(deckDir: string): SyncResult {
+  try {
+    return syncDeck(deckDir);
+  } catch {
+    // resolveDeck in diagnose reports the same error with its path and line.
+    return {
+      created: [],
+      updated: [],
+      removed: [],
+      kept: [],
+      dekFiles: { created: [], updated: [] },
+    };
+  }
+}
+
+/** The sync event a page hears, or none when nothing changed and none is owed. */
+function syncEvent(result: SyncResult, announceEmpty: boolean): LiveEvent | undefined {
+  // Slides go by slug: the stream reaches the audience, and a path on disk names the
+  // presenter's home and user.
+  const slugs = (paths: string[]) => paths.map((path) => basename(path, ".html"));
+  const created = slugs(result.created);
+  const updated = slugs(result.updated);
+  const removed = slugs(result.removed);
+  if (created.length === 0 && updated.length === 0 && removed.length === 0 && !announceEmpty) {
+    return undefined;
+  }
+  return {
+    type: "sync",
+    created,
+    ...(updated.length > 0 ? { updated } : {}),
+    ...(removed.length > 0 ? { removed } : {}),
+  };
+}
+
+/** A failed synthesis as one line on the server's stderr: what failed, then the fix. */
+export function voiceFailureLine(error: unknown): string {
+  const { message, hint } = errorFields(error);
+  return `voice: ${message}${hint ? ` (${hint})` : ""}`;
+}
+
+/** A failure while watching, as the diagnostic a page shows: a DekError keeps its hint. */
+export function watchErrorDiagnostic(error: unknown): Diagnostic {
+  return errorDiagnostic(error instanceof DekError ? "parse" : "error", errorFields(error));
+}