davaux 0.8.0

package/src/router/handler.ts

@@ -0,0 +1,515 @@
+import type { IncomingMessage, ServerResponse } from 'node:http'
+import { dirname } from 'node:path'
+import type { OmlCacheConfig } from '../config.js'
+import { renderToHtml, renderToHtmlDev } from '../oml/render.js'
+import type { OmlNode } from '../oml/types.js'
+import type {
+  ActionFn,
+  ErrorPageHandler,
+  ErrorPageProps,
+  LayoutFile,
+  LayoutProps,
+  MiddlewareFile,
+  MiddlewareFn,
+  RequestContext,
+  RouteFile,
+  ScanResult,
+} from '../types.js'
+import {
+  makeContext,
+  type PayloadTooLargeError,
+  type RedirectError,
+  type ValidationError,
+} from '../types.js'
+import { createMatcher, type MatchFn } from './matcher.js'
+
+const METHOD_TYPES: Record<string, string[]> = {
+  GET: ['page', 'get'],
+  POST: ['post', 'page'], // 'page' to support defineAction exports
+  PUT: ['put'],
+  PATCH: ['patch'],
+  DELETE: ['delete'],
+  HEAD: ['head', 'page', 'get'],
+  OPTIONS: ['options'],
+}
+
+/** A route file paired with its compiled URL matcher, ready for dispatch. */
+export interface CompiledRoute {
+  route: RouteFile
+  match: MatchFn
+}
+
+/** The compiled representation of a Davaux application, ready to dispatch requests. */
+export interface CompiledApp {
+  routes: CompiledRoute[]
+  layouts: LayoutFile[]
+  middlewares: MiddlewareFile[]
+  /** Compiled path to `src/middleware.ts` — runs on every request before route matching. */
+  appMiddlewarePath?: string
+  isDev: boolean
+  /** Whether the visual editor and inspector overlay are active. Requires `editor.enabled: true` in config. */
+  editorEnabled: boolean
+  clientScripts: string[]
+  clientStylesheets: string[]
+  errorPage?: string
+  basePath: string
+  /**
+   * In-process OML cache. Keyed by filePath::pathname+search. Only populated in production
+   * for routes matched by `omlCacheConfig`. Stores the OmlNode and pre-rendered HTML string
+   * so cache hits require zero renderToHtml traversal.
+   */
+  omlCache: Map<string, { node: OmlNode; html: string }>
+  /** In dev mode, stores the last rendered OmlNode per URL for the inspector. Not populated in production. */
+  devOmlStore?: Map<string, OmlNode>
+  /**
+   * OML production cache configuration from `davaux.config.ts` `oml.cache`.
+   * When absent, no routes are cached in production.
+   */
+  omlCacheConfig?: OmlCacheConfig
+}
+
+/**
+ * Compile a scan result into a `CompiledApp` ready to dispatch requests.
+ * Typically called once at startup (or on each rebuild in dev mode).
+ */
+export function buildApp(
+  result: ScanResult,
+  isDev = false,
+  clientScripts: string[] = [],
+  clientStylesheets: string[] = [],
+  appMiddlewarePath?: string,
+  basePath = '',
+  editorEnabled = false,
+  omlCacheConfig?: OmlCacheConfig,
+): CompiledApp {
+  return {
+    routes: result.routes.map((route) => ({
+      route,
+      match: createMatcher(route.urlPattern),
+    })),
+    layouts: result.layouts,
+    middlewares: result.middlewares,
+    appMiddlewarePath,
+    isDev,
+    editorEnabled,
+    clientScripts,
+    clientStylesheets,
+    errorPage: result.errorPage,
+    basePath,
+    omlCache: new Map(),
+    devOmlStore: isDev && editorEnabled ? new Map() : undefined,
+    omlCacheConfig,
+  }
+}
+
+// ─── OML cache helpers ────────────────────────────────────────────────────────
+
+function matchesCachePattern(pathname: string, pattern: string): boolean {
+  const regexStr = pattern
+    .replace(/[.+?^${}()|[\]\\]/g, '\\$&') // escape regex special chars (not * or :)
+    .replace(/:[^/]+/g, '[^/]+') // :param → any non-slash segment
+    .replace(/\*/g, '.*') // * → anything
+  return new RegExp(`^${regexStr}$`).test(pathname)
+}
+
+function isOmlCacheable(pathname: string, config: OmlCacheConfig | undefined): boolean {
+  if (!config) return false
+  if ('include' in config) return config.include.some((p) => matchesCachePattern(pathname, p))
+  return !config.exclude.some((p) => matchesCachePattern(pathname, p))
+}
+
+function isOmlNode(value: unknown): value is OmlNode {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) return false
+  const t = (value as Record<string, unknown>).type
+  return t === 'element' || t === '#component' || t === '#fragment' || t === '#text' || t === '#raw'
+}
+
+async function importModule(filePath: string, isDev: boolean): Promise<Record<string, unknown>> {
+  const url = isDev ? `${filePath}?t=${Date.now()}` : filePath
+  try {
+    return await (import(url) as Promise<Record<string, unknown>>)
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err)
+    throw new Error(`[davaux] Failed to load module: ${filePath}\n  ${detail}`, { cause: err })
+  }
+}
+
+// Find layouts that apply to a given route file, ordered innermost → outermost.
+function findLayouts(routeFilePath: string, layouts: LayoutFile[]): LayoutFile[] {
+  const routeDir = dirname(routeFilePath)
+  return layouts
+    .filter((l) => routeDir === l.dirPath || routeDir.startsWith(`${l.dirPath}/`))
+    .sort((a, b) => b.dirPath.length - a.dirPath.length) // deepest first
+}
+
+// Find middlewares that apply to a given route file, ordered outermost → innermost.
+function findMiddlewares(routeFilePath: string, middlewares: MiddlewareFile[]): MiddlewareFile[] {
+  const routeDir = dirname(routeFilePath)
+  return middlewares
+    .filter((m) => routeDir === m.dirPath || routeDir.startsWith(`${m.dirPath}/`))
+    .sort((a, b) => a.dirPath.length - b.dirPath.length) // shallowest first
+}
+
+async function runWithMiddleware(
+  middlewares: MiddlewareFile[],
+  ctx: RequestContext,
+  isDev: boolean,
+  handler: () => Promise<void>,
+): Promise<void> {
+  const step = async (i: number): Promise<void> => {
+    if (i < middlewares.length) {
+      const mod = await importModule(middlewares[i].filePath, isDev)
+      const fn = mod.default as MiddlewareFn
+      await fn(ctx, () => step(i + 1))
+    } else {
+      await handler()
+    }
+  }
+  await step(0)
+}
+
+function sendPage(html: string, res: ServerResponse): void {
+  if (!res.headersSent) {
+    const trimmed = html.trimStart()
+    const full =
+      trimmed.startsWith('<') && !trimmed.startsWith('<!DOCTYPE') ? `<!DOCTYPE html>${html}` : html
+    res.writeHead(res.statusCode, {
+      'Content-Type': 'text/html; charset=utf-8',
+    })
+    res.end(full)
+  } else if (!res.writableEnded) {
+    res.end(html)
+  }
+}
+
+async function sendPageWithDeferred(
+  html: string,
+  ctx: import('../types.js').RequestContext,
+  res: ServerResponse,
+): Promise<void> {
+  if (ctx._deferredSlots.size === 0) {
+    sendPage(html, res)
+    return
+  }
+  if (res.headersSent) return
+  const trimmed = html.trimStart()
+  const shell =
+    trimmed.startsWith('<') && !trimmed.startsWith('<!DOCTYPE') ? `<!DOCTYPE html>${html}` : html
+  res.writeHead(res.statusCode, { 'Content-Type': 'text/html; charset=utf-8' })
+  res.write(shell)
+  for (const [name, contentPromise] of ctx._deferredSlots) {
+    const content = await contentPromise
+    const slotHtml = isOmlNode(content) ? renderToHtml(content) : (content as string)
+    res.write(`<template for="${name}">${slotHtml}</template>`)
+  }
+  res.end()
+}
+
+async function renderPage(
+  route: RouteFile,
+  ctx: RequestContext,
+  layouts: LayoutFile[],
+  isDev: boolean,
+  omlCache: Map<string, { node: OmlNode; html: string }>,
+  opts?: {
+    preloadedMod?: Record<string, unknown>
+    devOmlStore?: Map<string, OmlNode>
+    omlCacheConfig?: OmlCacheConfig
+  },
+): Promise<string> {
+  const { preloadedMod, devOmlStore, omlCacheConfig } = opts ?? {}
+  const mod = preloadedMod ?? (await importModule(route.filePath, isDev))
+  const handler = mod.default as (
+    ctx: RequestContext,
+  ) => string | OmlNode | Promise<string | OmlNode>
+
+  const cacheKey =
+    !isDev && isOmlCacheable(ctx.url.pathname, omlCacheConfig)
+      ? `${route.filePath}::${ctx.url.pathname}${ctx.url.search}`
+      : null
+  const cached = cacheKey ? omlCache.get(cacheKey) : undefined
+
+  let html: string
+  if (cached !== undefined) {
+    html = cached.html
+  } else {
+    const result = await handler(ctx)
+    if (isOmlNode(result)) {
+      html = isDev && devOmlStore ? renderToHtmlDev(result) : renderToHtml(result)
+      if (cacheKey) omlCache.set(cacheKey, { node: result, html })
+      if (devOmlStore) {
+        const sp = new URLSearchParams(ctx.url.search)
+        sp.delete('_editor')
+        const search = sp.toString()
+        devOmlStore.set(ctx.url.pathname + (search ? `?${search}` : ''), result)
+      }
+    } else {
+      html = result as string
+    }
+  }
+
+  // Wrap in applicable layouts from innermost to outermost
+  const applicable = findLayouts(route.filePath, layouts)
+  for (const layout of applicable) {
+    const lmod = await importModule(layout.filePath, isDev)
+    const lhandler = lmod.default as (
+      props: LayoutProps,
+    ) => string | OmlNode | Promise<string | OmlNode>
+    // Pass children as Promise<string> so the JSX runtime renders it without escaping
+    const lresult = await lhandler({
+      children: Object.assign(Promise.resolve(html), { toString: () => html }),
+      ctx,
+    })
+    html = isOmlNode(lresult) ? renderToHtml(lresult) : (lresult as string)
+  }
+
+  return html
+}
+
+function initCtx(
+  req: IncomingMessage,
+  res: ServerResponse,
+  params: Record<string, string>,
+  url: URL,
+  app: CompiledApp,
+): RequestContext {
+  const ctx = makeContext(req, res, params, url, app.basePath)
+  ctx.head.stylesheets.push(...app.clientStylesheets)
+  ctx.head.scripts.push(...app.clientScripts)
+  if (app.isDev) {
+    ctx.head.scripts.push('/_davaux/livereload.js')
+    if (app.editorEnabled && !url.searchParams.has('_editor')) {
+      ctx.head.scripts.push('/_davaux/inspector.js')
+    }
+  }
+  return ctx
+}
+
+async function sendErrorPage(
+  status: number,
+  message: string,
+  req: IncomingMessage,
+  res: ServerResponse,
+  url: URL,
+  app: CompiledApp,
+  existingCtx?: RequestContext,
+): Promise<void> {
+  if (res.headersSent) return
+  if (!app.errorPage) {
+    res.writeHead(status, { 'Content-Type': 'text/plain' })
+    res.end(message)
+    return
+  }
+  try {
+    const ctx = existingCtx ?? initCtx(req, res, {}, url, app)
+    const mod = await importModule(app.errorPage, app.isDev)
+    const handler = mod.default as ErrorPageHandler
+    const rawErrorResult = await handler({ status, message, ctx } satisfies ErrorPageProps)
+    let html = isOmlNode(rawErrorResult) ? renderToHtml(rawErrorResult) : (rawErrorResult as string)
+
+    // Apply layouts so error pages inherit site chrome
+    const applicable = findLayouts(app.errorPage, app.layouts)
+    for (const layout of applicable) {
+      const lmod = await importModule(layout.filePath, app.isDev)
+      const lhandler = lmod.default as (
+        props: LayoutProps,
+      ) => string | OmlNode | Promise<string | OmlNode>
+      const lresult = await lhandler({
+        children: Object.assign(Promise.resolve(html), { toString: () => html }),
+        ctx,
+      })
+      html = isOmlNode(lresult) ? renderToHtml(lresult) : (lresult as string)
+    }
+
+    const trimmed = html.trimStart()
+    const full =
+      trimmed.startsWith('<') && !trimmed.startsWith('<!DOCTYPE') ? `<!DOCTYPE html>${html}` : html
+    res.writeHead(status, { 'Content-Type': 'text/html; charset=utf-8' })
+    res.end(full)
+  } catch {
+    res.writeHead(status, { 'Content-Type': 'text/plain' })
+    res.end(message)
+  }
+}
+
+/**
+ * Dispatch a single HTTP request through the compiled app.
+ * Runs app middleware → route matching → scoped middleware → route handler.
+ * Handles redirects, validation errors, payload-too-large, and 404s internally.
+ */
+export async function dispatch(
+  req: IncomingMessage,
+  res: ServerResponse,
+  app: CompiledApp,
+): Promise<void> {
+  const method = (req.method ?? 'GET').toUpperCase()
+  const url = new URL(req.url ?? '/', `http://${req.headers.host ?? 'localhost'}`)
+  const allowed = METHOD_TYPES[method] ?? []
+
+  // ctx is created once and shared between global middleware and route handlers.
+  // params starts empty and is populated in-place after a route match.
+  const ctx = initCtx(req, res, {}, url, app)
+
+  // Inner handler: route matching → scoped middleware → route handler → 404.
+  // Never throws — all errors are caught and turned into responses here.
+  const handleRoutes = async (): Promise<void> => {
+    for (const { route, match } of app.routes) {
+      if (!allowed.includes(route.type)) continue
+
+      const result = match(url.pathname)
+      if (!result) continue
+
+      // Populate params into the shared ctx now that we have a match
+      Object.assign(ctx.params, result.params)
+
+      const applicable = findMiddlewares(route.filePath, app.middlewares)
+
+      try {
+        await runWithMiddleware(applicable, ctx, app.isDev, async () => {
+          if (route.type === 'page') {
+            if (method === 'POST') {
+              const mod = await importModule(route.filePath, app.isDev)
+              const actionFn = mod.action as ActionFn | undefined
+              if (typeof actionFn !== 'function') {
+                if (!res.headersSent) {
+                  res.writeHead(405, {
+                    Allow: 'GET, HEAD',
+                    'Content-Type': 'text/plain',
+                  })
+                  res.end('Method Not Allowed')
+                }
+                return
+              }
+              const result = await actionFn(ctx)
+              if (result !== undefined) ctx.state.actionResult = result
+              await sendPageWithDeferred(
+                await renderPage(route, ctx, app.layouts, app.isDev, app.omlCache, {
+                  preloadedMod: mod,
+                  devOmlStore: app.devOmlStore,
+                  omlCacheConfig: app.omlCacheConfig,
+                }),
+                ctx,
+                res,
+              )
+            } else {
+              await sendPageWithDeferred(
+                await renderPage(route, ctx, app.layouts, app.isDev, app.omlCache, {
+                  devOmlStore: app.devOmlStore,
+                  omlCacheConfig: app.omlCacheConfig,
+                }),
+                ctx,
+                res,
+              )
+            }
+          } else {
+            // API route
+            const mod = await importModule(route.filePath, app.isDev)
+            const handler = mod.default as (ctx: RequestContext) => unknown
+            const value = await handler(ctx)
+            if (!res.headersSent && value !== undefined) {
+              if (value instanceof Response) {
+                await writeWebResponse(value, res)
+              } else {
+                res.writeHead(res.statusCode, {
+                  'Content-Type': 'application/json; charset=utf-8',
+                })
+                res.end(JSON.stringify(value))
+              }
+            }
+          }
+        })
+      } catch (err) {
+        if (isRedirect(err)) throw err
+        if (isValidation(err)) throw err
+        if (isPayloadTooLarge(err)) throw err
+        console.error(`[davaux] Error in ${route.filePath}:`, err)
+        await sendErrorPage(
+          500,
+          err instanceof Error ? err.message : 'Internal Server Error',
+          req,
+          res,
+          url,
+          app,
+          ctx,
+        )
+      }
+      return // route matched — stop iterating
+    }
+
+    await sendErrorPage(404, 'Not Found', req, res, url, app, ctx)
+  }
+
+  // App middleware (src/middleware.ts) → routes.
+  // Errors thrown anywhere in the chain are caught here.
+  try {
+    if (app.appMiddlewarePath) {
+      const mod = await importModule(app.appMiddlewarePath, app.isDev)
+      const fn = mod.default as MiddlewareFn
+      await fn(ctx, handleRoutes)
+    } else {
+      await handleRoutes()
+    }
+  } catch (err) {
+    if (isRedirect(err)) {
+      if (!res.headersSent) {
+        res.writeHead(err.status, { Location: err.url })
+        res.end()
+      }
+      return
+    }
+    if (isValidation(err)) {
+      const body: Record<string, unknown> = { error: err.message }
+      const cause = err.cause
+      if (
+        cause != null &&
+        typeof cause === 'object' &&
+        Array.isArray((cause as { issues?: unknown }).issues)
+      ) {
+        body.issues = (cause as { issues: unknown }).issues
+      }
+      if (!res.headersSent) {
+        res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' })
+        res.end(JSON.stringify(body))
+      }
+      return
+    }
+    if (isPayloadTooLarge(err)) {
+      if (!res.headersSent) {
+        res.writeHead(413, { 'Content-Type': 'text/plain' })
+        res.end(err.message)
+      }
+      return
+    }
+    console.error('[davaux] Error in global middleware:', err)
+    await sendErrorPage(
+      500,
+      err instanceof Error ? err.message : 'Internal Server Error',
+      req,
+      res,
+      url,
+      app,
+      ctx,
+    )
+  }
+}
+
+async function writeWebResponse(webRes: Response, res: ServerResponse): Promise<void> {
+  const headers: Record<string, string> = {}
+  webRes.headers.forEach((value, key) => {
+    headers[key] = value
+  })
+  res.writeHead(webRes.status, headers)
+  res.end(Buffer.from(await webRes.arrayBuffer()))
+}
+
+function isRedirect(err: unknown): err is RedirectError {
+  return (err as RedirectError)?.isRedirect === true
+}
+
+function isValidation(err: unknown): err is ValidationError {
+  return (err as ValidationError)?.isValidation === true
+}
+
+function isPayloadTooLarge(err: unknown): err is PayloadTooLargeError {
+  return (err as PayloadTooLargeError)?.isPayloadTooLarge === true
+}

package/src/router/matcher.ts

@@ -0,0 +1,52 @@
+/** Result of a successful URL pattern match, containing the extracted named params. */
+export interface MatchResult {
+  params: Record<string, string>
+}
+
+/** A compiled URL matcher. Returns a `MatchResult` on match, `null` on miss. */
+export type MatchFn = (pathname: string) => MatchResult | null
+
+/**
+ * Compile a URL pattern string into a fast matcher function.
+ *
+ * Pattern segments:
+ * - `:param` — matches a single path segment and captures it by name.
+ * - `*param` — catch-all; matches the rest of the path including slashes.
+ * - anything else — matched literally.
+ *
+ * @example
+ * const match = createMatcher('/blog/:slug')
+ * match('/blog/hello') // → { params: { slug: 'hello' } }
+ * match('/about')      // → null
+ */
+export function createMatcher(urlPattern: string): MatchFn {
+  const paramNames: string[] = []
+
+  // Build regex from pattern segments
+  const regexParts = urlPattern.split('/').map((segment) => {
+    if (segment.startsWith('*')) {
+      paramNames.push(segment.slice(1))
+      return '(.+)' // catch-all: matches multiple path segments including slashes
+    }
+    if (segment.startsWith(':')) {
+      paramNames.push(segment.slice(1))
+      return '([^/]+)'
+    }
+    // Escape regex special chars in static segments
+    return segment.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  })
+
+  const pattern = new RegExp(`^${regexParts.join('\\/')}$`)
+
+  return (pathname: string): MatchResult | null => {
+    const match = pathname.match(pattern)
+    if (!match) return null
+
+    const params: Record<string, string> = {}
+    paramNames.forEach((name, i) => {
+      params[name] = decodeURIComponent(match[i + 1])
+    })
+
+    return { params }
+  }
+}