srvmd 0.1.0

package/src/server/http/respond.ts

@@ -0,0 +1,74 @@
+import type { ApiErrorPayload } from "../../shared/contracts.ts";
+import type { ResolvedPath } from "../types.ts";
+import { baseHeaders } from "./headers.ts";
+import { applyValidators, computeValidators, isNotModified } from "./validators.ts";
+
+export function htmlResponse(body: string, status: number, method: string, cors: boolean): Response {
+  const headers = baseHeaders(cors);
+  headers.set("Content-Type", "text/html; charset=utf-8");
+  headers.set("Cache-Control", "no-store");
+  if (method === "HEAD") {
+    headers.set("Content-Length", String(Buffer.byteLength(body)));
+    return new Response(null, { status, headers });
+  }
+  return new Response(body, { status, headers });
+}
+
+/**
+ * Serve a file with validators. Bun's manual file responses handle Range
+ * requests but not ETag/Last-Modified, so add them (and 304s) here.
+ */
+export function fileResponse(file: ResolvedPath, request: Request, cors: boolean, contentType?: string): Response {
+  const headers = baseHeaders(cors);
+  if (contentType) headers.set("Content-Type", contentType);
+
+  const validators = computeValidators(file.stats);
+  applyValidators(headers, validators);
+  if (isNotModified(request, validators, file.stats)) {
+    return new Response(null, { status: 304, headers });
+  }
+
+  return new Response(Bun.file(file.path), { headers });
+}
+
+export function redirectResponse(location: string, method: string, cors: boolean): Response {
+  const headers = baseHeaders(cors);
+  headers.set("Location", location);
+  return new Response(method === "HEAD" ? null : "", { status: 301, headers });
+}
+
+export function preflightResponse(cors: boolean): Response {
+  return new Response(null, { status: 204, headers: baseHeaders(cors) });
+}
+
+export function methodNotAllowedResponse(cors: boolean): Response {
+  const headers = baseHeaders(cors);
+  headers.set("Allow", "GET, HEAD, OPTIONS");
+  return new Response("Method Not Allowed", { status: 405, headers });
+}
+
+function bodyResponse(body: string, status: number, method: string, cors: boolean, contentType: string): Response {
+  const headers = baseHeaders(cors);
+  headers.set("Content-Type", contentType);
+  headers.set("Cache-Control", "no-store");
+
+  if (method === "HEAD") {
+    headers.set("Content-Length", String(Buffer.byteLength(body)));
+    return new Response(null, { status, headers });
+  }
+
+  return new Response(body, { status, headers });
+}
+
+export function jsonResponse(body: unknown, status: number, method: string, cors: boolean): Response {
+  return bodyResponse(JSON.stringify(body), status, method, cors, "application/json; charset=utf-8");
+}
+
+export function jsonError(status: number, message: string, method: string, cors: boolean): Response {
+  const payload: ApiErrorPayload = { error: { status, message } };
+  return jsonResponse(payload, status, method, cors);
+}
+
+export function textResponse(body: string, status: number, method: string, cors: boolean): Response {
+  return bodyResponse(body, status, method, cors, "text/plain; charset=utf-8");
+}

package/src/server/http/validators.ts

@@ -0,0 +1,37 @@
+import type { Stats } from "node:fs";
+
+export type Validators = {
+  etag: string;
+  lastModified: string;
+};
+
+/** Build the weak ETag / Last-Modified pair Bun's routes would otherwise add. */
+export function computeValidators(stats: Stats): Validators {
+  return {
+    etag: `W/"${stats.size.toString(16)}-${stats.mtime.getTime().toString(16)}"`,
+    lastModified: stats.mtime.toUTCString(),
+  };
+}
+
+export function applyValidators(headers: Headers, validators: Validators): void {
+  headers.set("ETag", validators.etag);
+  headers.set("Last-Modified", validators.lastModified);
+  headers.set("Accept-Ranges", "bytes");
+}
+
+/**
+ * Evaluate If-None-Match first, then If-Modified-Since (the same precedence
+ * RFC 9110 requires). Returns true when the client already has this version.
+ */
+export function isNotModified(request: Request, validators: Validators, stats: Stats): boolean {
+  const noneMatch = request.headers.get("if-none-match");
+  if (noneMatch) {
+    return noneMatch.split(",").some(value => value.trim() === validators.etag);
+  }
+
+  const modifiedSince = request.headers.get("if-modified-since");
+  if (!modifiedSince) return false;
+  const since = Date.parse(modifiedSince);
+  if (!Number.isFinite(since)) return false;
+  return Math.floor(stats.mtime.getTime() / 1000) <= Math.floor(since / 1000);
+}

package/src/server/markdown/frontmatter.ts

@@ -0,0 +1,29 @@
+import type { FrontmatterData } from "../types.ts";
+
+export type FrontmatterResult = {
+  data: FrontmatterData;
+  body: string;
+  raw?: string;
+  error?: string;
+};
+
+/** Split a leading YAML frontmatter block from the Markdown body. */
+export function parseFrontmatter(source: string): FrontmatterResult {
+  const match = /^---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/.exec(source);
+  if (!match) return { data: {}, body: source };
+
+  const raw = match[1] ?? "";
+  let data: FrontmatterData = {};
+  let error: string | undefined;
+
+  try {
+    const parsed = Bun.YAML.parse(raw);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      data = parsed as FrontmatterData;
+    }
+  } catch (cause) {
+    error = `Invalid frontmatter: ${cause instanceof Error ? cause.message : String(cause)}`;
+  }
+
+  return { data, body: source.slice(match[0].length), raw, error };
+}

package/src/server/markdown/highlight.ts

@@ -0,0 +1,100 @@
+import { type Highlighter, createHighlighter as shikiCreateHighlighter } from "shiki";
+import { decodeEntities } from "./text.ts";
+
+const THEMES = { light: "github-light", dark: "github-dark" } as const;
+
+/**
+ * Languages bundled eagerly. Anything else is loaded lazily on first use,
+ * so docs only pay for what they contain.
+ */
+const PRELOADED_LANGUAGES = [
+  "bash",
+  "c",
+  "cpp",
+  "csharp",
+  "css",
+  "diff",
+  "docker",
+  "go",
+  "graphql",
+  "html",
+  "ini",
+  "java",
+  "javascript",
+  "json",
+  "jsx",
+  "markdown",
+  "php",
+  "python",
+  "ruby",
+  "rust",
+  "scss",
+  "sql",
+  "svelte",
+  "toml",
+  "tsx",
+  "typescript",
+  "vue",
+  "xml",
+  "yaml",
+];
+
+const CODE_BLOCK_RE = /<pre><code class="language-([^"]+)">([\s\S]*?)<\/code><\/pre>/g;
+const FENCE_RE = /^(?:```|~~~)[ \t]*([A-Za-z0-9_+#.-]+)/gm;
+
+/**
+ * Create a highlighter instance. Returns null when highlighting is
+ * unavailable so callers can continue without it. No module-level singleton:
+ * the instance is owned by the server context.
+ */
+export async function createHighlighterService(): Promise<Highlighter | null> {
+  try {
+    return await shikiCreateHighlighter({
+      themes: [THEMES.light, THEMES.dark],
+      langs: PRELOADED_LANGUAGES,
+    });
+  } catch (error) {
+    console.warn(`[srvmd] syntax highlighting disabled: ${error instanceof Error ? error.message : error}`);
+    return null;
+  }
+}
+
+/** Load every language fenced in the document that is not loaded yet. */
+export async function ensureLanguages(
+  highlighter: Highlighter,
+  markdown: string,
+  skipLanguage?: string,
+): Promise<void> {
+  const requested = new Set<string>();
+  for (const match of markdown.matchAll(FENCE_RE)) {
+    const language = match[1]?.toLowerCase();
+    if (language && language !== skipLanguage) requested.add(language);
+  }
+
+  const loaded = new Set(highlighter.getLoadedLanguages());
+  await Promise.all(
+    [...requested].map(async language => {
+      if (loaded.has(language)) return;
+      try {
+        await highlighter.loadLanguage(language as never);
+        loaded.add(language);
+      } catch {
+        // Unknown language: the block falls back to plain <pre><code>.
+      }
+    }),
+  );
+}
+
+export function highlightCodeBlocks(html: string, highlighter: Highlighter): string {
+  return html.replace(CODE_BLOCK_RE, (match, language: string, escaped: string) => {
+    const code = decodeEntities(escaped).replace(/\n$/, "");
+    try {
+      return highlighter.codeToHtml(code, {
+        lang: language,
+        themes: { light: THEMES.light, dark: THEMES.dark },
+      });
+    } catch {
+      return match;
+    }
+  });
+}

package/src/server/markdown/index.ts

@@ -0,0 +1,8 @@
+export type { FrontmatterResult } from "./frontmatter.ts";
+export { parseFrontmatter } from "./frontmatter.ts";
+export { createHighlighterService, ensureLanguages, highlightCodeBlocks } from "./highlight.ts";
+export type { MermaidTransform } from "./mermaid.ts";
+export { renderMermaidBlocks } from "./mermaid.ts";
+export type { RenderedDocument, Renderer, RendererOptions, RenderOptions } from "./render.ts";
+export { createRenderer, renderMarkdown } from "./render.ts";
+export { extractToc, injectHeadingAnchors } from "./toc.ts";

package/src/server/markdown/mermaid.ts

@@ -0,0 +1,30 @@
+import type { MermaidSource } from "../../shared/types.ts";
+import { MERMAID_LANGUAGE } from "../constants.ts";
+import { decodeEntities } from "./text.ts";
+
+const MERMAID_BLOCK_RE = new RegExp(`<pre><code class="language-${MERMAID_LANGUAGE}">([\\s\\S]*?)</code></pre>`, "g");
+
+export type MermaidTransform = {
+  html: string;
+  /** Raw diagram sources, decoded for the browser runtime. */
+  sources: MermaidSource[];
+};
+
+/**
+ * Turn ```mermaid fences into empty slots plus structured sources. The Svelte
+ * client mounts a diagram component into each slot.
+ *
+ * The captured source is HTML-escaped by Bun's Markdown renderer; it is decoded
+ * once here so the API can hand raw Mermaid source to the browser.
+ */
+export function renderMermaidBlocks(html: string): MermaidTransform {
+  const sources: MermaidSource[] = [];
+
+  const output = html.replace(MERMAID_BLOCK_RE, (_match, source: string) => {
+    const id = `mermaid-${sources.length + 1}`;
+    sources.push({ id, source: decodeEntities(source) });
+    return `<div class="mermaid-slot" data-mermaid-slot="${id}"></div>`;
+  });
+
+  return { html: output, sources };
+}

package/src/server/markdown/render.ts

@@ -0,0 +1,119 @@
+import type { Highlighter } from "shiki";
+import type { MermaidSource, TocItem } from "../../shared/types.ts";
+import { MERMAID_LANGUAGE } from "../constants.ts";
+import type { FrontmatterData, HtmlMode } from "../types.ts";
+import { parseFrontmatter } from "./frontmatter.ts";
+import { createHighlighterService, ensureLanguages, highlightCodeBlocks } from "./highlight.ts";
+import { renderMermaidBlocks } from "./mermaid.ts";
+import { extractToc, injectHeadingAnchors } from "./toc.ts";
+
+export type RenderOptions = {
+  /** Syntax highlight fenced code blocks with shiki. Default: true. */
+  highlight?: boolean;
+  /** How to treat raw HTML inside Markdown. Default: "filter". */
+  html?: HtmlMode;
+  /** Enable $inline$ / $$display$$ math. Default: false. */
+  math?: boolean;
+  /** Render ```mermaid fences as client-side diagrams. Default: true. */
+  mermaid?: boolean;
+  /** Reuse an existing shiki instance (the server does this). */
+  highlighter?: Highlighter | null;
+};
+
+export type RenderedDocument = {
+  html: string;
+  toc: TocItem[];
+  title?: string;
+  frontmatter: FrontmatterData;
+  warning?: string;
+  /** Structured diagram sources for the Svelte client. */
+  mermaid: MermaidSource[];
+  raw: string;
+};
+
+export type RendererOptions = {
+  highlighter: Highlighter | null;
+  html: HtmlMode;
+  math: boolean;
+  /** Render ```mermaid fences as client-side diagrams. Default: true. */
+  mermaid?: boolean;
+};
+
+export type Renderer = {
+  render(source: string): Promise<RenderedDocument>;
+};
+
+export function createRenderer(options: RendererOptions): Renderer {
+  return {
+    async render(source) {
+      const frontmatter = parseFrontmatter(source);
+      const { highlighter } = options;
+      const mermaidEnabled = options.mermaid !== false;
+
+      if (highlighter)
+        await ensureLanguages(highlighter, frontmatter.body, mermaidEnabled ? MERMAID_LANGUAGE : undefined);
+
+      let html = Bun.markdown.html(frontmatter.body, {
+        tables: true,
+        strikethrough: true,
+        tasklists: true,
+        autolinks: true,
+        headings: { ids: true },
+        latexMath: options.math,
+        tagFilter: options.html === "filter",
+        noHtmlBlocks: options.html === "off",
+        noHtmlSpans: options.html === "off",
+      });
+
+      let mermaidSources: MermaidSource[] = [];
+      if (mermaidEnabled) {
+        const mermaid = renderMermaidBlocks(html);
+        html = mermaid.html;
+        mermaidSources = mermaid.sources;
+      }
+
+      if (highlighter) html = highlightCodeBlocks(html, highlighter);
+
+      const toc = extractToc(html);
+      html = injectHeadingAnchors(html);
+
+      const titleValue = frontmatter.data.title;
+      const title =
+        typeof titleValue === "string"
+          ? titleValue
+          : titleValue == null
+            ? toc.find(item => item.level === 1)?.text
+            : String(titleValue);
+
+      return {
+        html,
+        toc,
+        title,
+        frontmatter: frontmatter.data,
+        warning: frontmatter.error,
+        mermaid: mermaidSources,
+        raw: source,
+      };
+    },
+  };
+}
+
+/**
+ * Convenience API for one-off rendering. When no highlighter is supplied and
+ * highlighting is enabled, a temporary instance is created and disposed.
+ */
+export async function renderMarkdown(source: string, options: RenderOptions = {}): Promise<RenderedDocument> {
+  const ownsHighlighter = options.highlight !== false && !options.highlighter;
+  const highlighter = options.highlighter ?? (ownsHighlighter ? await createHighlighterService() : null);
+
+  try {
+    return await createRenderer({
+      highlighter,
+      html: options.html ?? "filter",
+      math: options.math === true,
+      mermaid: options.mermaid !== false,
+    }).render(source);
+  } finally {
+    if (ownsHighlighter) highlighter?.dispose();
+  }
+}

package/src/server/markdown/text.ts

@@ -0,0 +1,30 @@
+const ENTITIES: Record<string, string> = {
+  amp: "&",
+  lt: "<",
+  gt: ">",
+  quot: '"',
+  nbsp: "\u00a0",
+};
+
+/** Decode HTML entities emitted by Bun's markdown renderer. */
+export function decodeEntities(input: string): string {
+  return input.replace(/&(#x[0-9a-f]+|#[0-9]+|[a-z][a-z0-9]+);/gi, (match, name: string) => {
+    const lower = name.toLowerCase();
+
+    if (lower.startsWith("#x") || lower.startsWith("#")) {
+      const code = Number.parseInt(lower.slice(lower.startsWith("#x") ? 2 : 1), lower.startsWith("#x") ? 16 : 10);
+      if (!Number.isFinite(code)) return match;
+      try {
+        return String.fromCodePoint(code);
+      } catch {
+        return match;
+      }
+    }
+
+    return ENTITIES[lower] ?? match;
+  });
+}
+
+export function stripTags(input: string): string {
+  return decodeEntities(input.replace(/<[^>]*>/g, ""));
+}

package/src/server/markdown/toc.ts

@@ -0,0 +1,29 @@
+import type { TocItem } from "../../shared/types.ts";
+import { stripTags } from "./text.ts";
+
+const HEADING_RE = /<h([1-6])\b([^>]*)>([\s\S]*?)<\/h\1>/gi;
+const ID_ATTR_RE = /\bid="([^"]*)"/;
+
+/** Pull a table of contents out of the HTML Bun generated (ids come from Bun). */
+export function extractToc(html: string): TocItem[] {
+  const toc: TocItem[] = [];
+  for (const match of html.matchAll(HEADING_RE)) {
+    const level = Number(match[1]);
+    const attrs = match[2] ?? "";
+    const id = ID_ATTR_RE.exec(attrs)?.[1];
+    if (!id) continue;
+    const text = stripTags(match[3] ?? "").trim();
+    if (!text) continue;
+    toc.push({ level, id, text });
+  }
+  return toc;
+}
+
+/** Add a hoverable # anchor next to every heading that has an id. */
+export function injectHeadingAnchors(html: string): string {
+  return html.replace(HEADING_RE, (match, level: string, attrs: string, inner: string) => {
+    const id = ID_ATTR_RE.exec(attrs)?.[1];
+    if (!id || /\bclass="/.test(attrs)) return match;
+    return `<h${level}${attrs} class="heading"><a class="heading-anchor" href="#${id}" aria-hidden="true">#</a>${inner}</h${level}>`;
+  });
+}

package/src/server/path.ts

@@ -0,0 +1,9 @@
+import { sep } from "node:path";
+
+export function isInside(root: string, target: string): boolean {
+  return target === root || target.startsWith(root.endsWith(sep) ? root : root + sep);
+}
+
+export function isHiddenRelativePath(relativePath: string): boolean {
+  return relativePath.split(/[\\/]/).some(segment => segment.startsWith(".") && segment !== "." && segment !== "..");
+}

package/src/server/resolve/path.ts

@@ -0,0 +1,43 @@
+import { realpath, stat } from "node:fs/promises";
+import { relative, resolve, sep } from "node:path";
+import { isHiddenRelativePath, isInside } from "../path.ts";
+import type { ResolvedPath } from "../types.ts";
+
+export type ResolveResult =
+  | { ok: true; resolved: ResolvedPath }
+  | { ok: false; status: 400 | 403 | 404; reason: string };
+
+/** Validate and resolve a request path inside the served root (symlink-safe). */
+export async function resolveRequest(root: string, pathname: string): Promise<ResolveResult> {
+  let decoded: string;
+  try {
+    decoded = decodeURIComponent(pathname);
+  } catch {
+    return { ok: false, status: 400, reason: "Malformed URL" };
+  }
+
+  if (decoded.includes("\0")) {
+    return { ok: false, status: 400, reason: "Malformed URL" };
+  }
+
+  const candidate = resolve(root, `.${decoded}`);
+  if (!isInside(root, candidate)) {
+    return { ok: false, status: 403, reason: "Path escapes the served directory" };
+  }
+
+  const real = await realpath(candidate).catch(() => null);
+  if (!real) return { ok: false, status: 404, reason: "Not found" };
+  if (!isInside(root, real)) {
+    return { ok: false, status: 403, reason: "Path escapes the served directory" };
+  }
+
+  const stats = await stat(real).catch(() => null);
+  if (!stats) return { ok: false, status: 404, reason: "Not found" };
+
+  const rel = relative(root, real).split(sep).join("/");
+  if (rel && isHiddenRelativePath(rel)) {
+    return { ok: false, status: 404, reason: "Hidden paths are not served" };
+  }
+
+  return { ok: true, resolved: { path: real, stats, relative: rel } };
+}

package/src/server/resolve/resource.ts

@@ -0,0 +1,88 @@
+import { extname } from "node:path";
+import { CLEAN_URL_SUFFIXES } from "../constants.ts";
+import { isHtmlFile, isMarkdownFile } from "../file-kinds.ts";
+import type { ResolvedPath } from "../types.ts";
+import { resolveRequest } from "./path.ts";
+
+export type Resource =
+  | { kind: "markdown"; file: ResolvedPath }
+  | { kind: "html"; file: ResolvedPath }
+  | { kind: "file"; file: ResolvedPath }
+  | { kind: "directory"; directory: ResolvedPath }
+  | { kind: "redirect"; location: string }
+  | { kind: "error"; status: 400 | 403 | 404; reason: string };
+
+export type ResolveOptions = {
+  root: string;
+  cleanUrls: boolean;
+  single: boolean;
+  directoryListing: boolean;
+};
+
+function classifyFile(file: ResolvedPath): Resource {
+  if (isMarkdownFile(file.path)) return { kind: "markdown", file };
+  if (isHtmlFile(file.path)) return { kind: "html", file };
+  return { kind: "file", file };
+}
+
+async function resolveCleanUrl(root: string, pathname: string): Promise<ResolvedPath | null> {
+  if (extname(pathname) !== "") return null;
+  for (const suffix of CLEAN_URL_SUFFIXES) {
+    const result = await resolveRequest(root, pathname + suffix);
+    if (result.ok && result.resolved.stats.isFile()) return result.resolved;
+  }
+  return null;
+}
+
+async function resolveSingleFallback(root: string): Promise<ResolvedPath | null> {
+  for (const pathname of ["/index.md", "/index.html"]) {
+    const result = await resolveRequest(root, pathname);
+    if (result.ok && result.resolved.stats.isFile()) return result.resolved;
+  }
+  return null;
+}
+
+async function resolveDirectory(options: ResolveOptions, pathname: string, directory: ResolvedPath): Promise<Resource> {
+  for (const name of ["index.md", "index.html"]) {
+    const candidate = await resolveRequest(options.root, `${pathname}${name}`);
+    if (candidate.ok && candidate.resolved.stats.isFile()) return classifyFile(candidate.resolved);
+  }
+
+  if (!options.directoryListing) {
+    return { kind: "error", status: 404, reason: "Directory listing is disabled." };
+  }
+  return { kind: "directory", directory };
+}
+
+/**
+ * Turn a request URL into a resource the response layer can render.
+ * This is the single place that knows about clean URLs, directory indexes
+ * and the SPA fallback.
+ */
+export async function resolveResource(options: ResolveOptions, url: URL): Promise<Resource> {
+  const result = await resolveRequest(options.root, url.pathname);
+
+  if (result.ok) {
+    const resolved = result.resolved;
+    if (resolved.stats.isDirectory()) {
+      if (!url.pathname.endsWith("/")) {
+        return { kind: "redirect", location: `${url.pathname}/${url.search}` };
+      }
+      return resolveDirectory(options, url.pathname, resolved);
+    }
+    return classifyFile(resolved);
+  }
+
+  if (result.status === 404) {
+    if (options.cleanUrls) {
+      const clean = await resolveCleanUrl(options.root, url.pathname);
+      if (clean) return classifyFile(clean);
+    }
+    if (options.single) {
+      const fallback = await resolveSingleFallback(options.root);
+      if (fallback) return classifyFile(fallback);
+    }
+  }
+
+  return { kind: "error", status: result.status, reason: result.reason };
+}