@pathmx/core 0.5.0

package/server/http.ts

@@ -0,0 +1,333 @@
+import {
+  ActionNotFoundError,
+  ActionUnavailableError,
+  ActionValidationError,
+  dispatchAction,
+  type ActionInput,
+} from "../actions/actions.ts"
+import type { Engine } from "../host/engine.ts"
+import { actionProblem } from "../problem.ts"
+import type { Source } from "../source/index.ts"
+import {
+  anonymousPrincipal,
+  principalFor,
+  type CredentialSession,
+  type Principal,
+} from "../authority/model.ts"
+import { renderPage } from "../host/render.ts"
+import { privateResponse, withReadCache } from "../host/response.ts"
+import { pageNotFound, requestScheme } from "./page.ts"
+import { AGENT_BROWSING_PLUGIN_ID, protocolRoute } from "./protocols.ts"
+import { prefersMarkdown, withMarkdownAlternate } from "./representations.ts"
+import { resolveRoute } from "./router.ts"
+
+const anonymousSession = Object.freeze({
+  type: "anonymous",
+  signIn: null,
+}) satisfies CredentialSession
+
+function formInput(body: string) {
+  const input: ActionInput = {}
+  for (const [name, value] of new URLSearchParams(body)) {
+    const current = input[name]
+    input[name] =
+      current == null
+        ? value
+        : Array.isArray(current)
+          ? [...current, value]
+          : [current, value]
+  }
+  return input
+}
+
+function resolveTarget(
+  app: Engine,
+  input: ActionInput,
+  referer: string | null,
+) {
+  const targetInput = input._target
+  const hinted = typeof targetInput === "string" ? targetInput.trim() : ""
+  if (hinted) {
+    const source = app.resolve(hinted) ?? app.repo.get(hinted)
+    return { source, required: true }
+  }
+  if (!referer) return
+  try {
+    return { source: app.resolve(new URL(referer).pathname), required: false }
+  } catch {
+    return
+  }
+}
+
+function sameOriginMutation(req: Request, url: URL) {
+  const origin = req.headers.get("origin")
+  if (origin) return origin === url.origin
+  const referer = req.headers.get("referer")
+  if (!referer) return false
+  try {
+    return new URL(referer).origin === url.origin
+  } catch {
+    return false
+  }
+}
+
+async function handleAction(
+  app: Engine,
+  req: Request,
+  url: URL,
+  session: CredentialSession,
+) {
+  if (req.method !== "POST") {
+    return new Response("Method Not Allowed", { status: 405 })
+  }
+  if (session.type !== "authenticated") return pageNotFound()
+  if (!sameOriginMutation(req, url)) {
+    return actionProblem(req, 403, "Cross-origin mutation denied.")
+  }
+
+  const name = url.pathname.slice("/actions/".length)
+  const input = formInput(await req.text())
+  const resolvedTarget = resolveTarget(app, input, req.headers.get("referer"))
+  const target = resolvedTarget?.source
+  if (resolvedTarget?.required && !target) return pageNotFound()
+  if (
+    target &&
+    !app.hasSourceCapability(
+      { type: "actor", actor: session.actor },
+      target,
+      "execute",
+    )
+  ) {
+    return pageNotFound()
+  }
+  let outcome: Awaited<ReturnType<typeof dispatchAction>>
+  try {
+    outcome = await dispatchAction(app, name, input, session.actor, target)
+  } catch (error) {
+    if (error instanceof ActionNotFoundError) {
+      return actionProblem(req, 404, error.message)
+    }
+    if (error instanceof ActionValidationError) {
+      return actionProblem(req, 400, error.message)
+    }
+    if (error instanceof ActionUnavailableError) {
+      return actionProblem(req, 403, error.message)
+    }
+    const message = error instanceof Error ? error.message : "Action failed."
+    return actionProblem(req, 400, message)
+  }
+
+  if (req.headers.get("accept")?.includes("application/json")) {
+    return privateResponse(
+      Response.json({
+        ok: true,
+        action: name,
+        target: target?.id,
+        output: outcome.value,
+        receipt: { applied: outcome.commit.applied.length },
+      }),
+    )
+  }
+
+  return privateResponse(
+    new Response(null, {
+      status: 303,
+      headers: { Location: req.headers.get("referer") || "/" },
+    }),
+  )
+}
+
+export async function handleRequest(app: Engine, req: Request) {
+  return handleRoutedRequest(app, req, new URL(req.url))
+}
+
+/** @internal Render a canonical route at a different public publication URL. */
+export async function handleRequestAtPath(
+  app: Engine,
+  req: Request,
+  pathname: string,
+) {
+  const publicUrl = new URL(req.url)
+  const routeUrl = new URL(pathname, publicUrl.origin)
+  return handleRoutedRequest(app, req, routeUrl, publicUrl)
+}
+
+async function handleRoutedRequest(
+  app: Engine,
+  req: Request,
+  url: URL,
+  publicUrl = url,
+) {
+  const start = performance.now()
+
+  return app.perf.measureAsync(
+    "http.request",
+    async () => {
+      const response = await dispatchRequest(app, req, url, publicUrl)
+      const ms = performance.now() - start
+      response.headers.set("Server-Timing", `render;dur=${ms.toFixed(1)}`)
+      app.log.debug("http.perf", {
+        path: url.pathname,
+        ms: Number(ms.toFixed(1)),
+        status: response.status,
+      })
+      return response
+    },
+    publicUrl.pathname,
+  )
+}
+
+async function dispatchRequest(
+  app: Engine,
+  req: Request,
+  url: URL,
+  publicUrl: URL,
+) {
+  if (req.method === "GET" || req.method === "HEAD") {
+    const served = serveGenerated(app, url.pathname, req.method === "HEAD")
+    if (served) return served
+  }
+
+  if (
+    protocolRoute(url.pathname) &&
+    (req.method === "GET" || req.method === "HEAD")
+  ) {
+    const authored = await serveAsset(
+      app,
+      url.pathname,
+      req.method === "HEAD",
+      anonymousSession,
+      anonymousPrincipal,
+    )
+    if (authored) return authored
+  }
+
+  const serverRoute = await app.serverRoute(req, url, publicUrl)
+  if (serverRoute) return serverRoute
+  if (url.pathname === "/api" || url.pathname.startsWith("/api/")) {
+    return pageNotFound()
+  }
+
+  const session = await app.resolveCredentials(req)
+  const principal = principalFor(session)
+  return dispatch(app, req, url, session, principal)
+}
+
+function serveGenerated(app: Engine, pathname: string, head: boolean) {
+  if (!pathname.startsWith("/.pmx/")) return
+  const asset = app.servedAsset(pathname)
+  if (!asset) return
+  return new Response(head ? null : asset.body, {
+    headers: {
+      "Content-Type": asset.contentType,
+      "Cache-Control": "public, max-age=31536000, immutable",
+    },
+  })
+}
+
+async function dispatch(
+  app: Engine,
+  req: Request,
+  url: URL,
+  session: CredentialSession,
+  principal: Principal,
+) {
+  if (url.pathname.startsWith("/actions/")) {
+    return handleAction(app, req, url, session)
+  }
+  if (req.method !== "GET" && req.method !== "HEAD") {
+    return new Response("Method Not Allowed", { status: 405 })
+  }
+
+  // One canonical URL per page: the edge normalizes trailing slashes so
+  // canonicalPath stays strict and cache keys stay unique.
+  if (url.pathname.length > 1 && url.pathname.endsWith("/")) {
+    return new Response(null, {
+      status: 308,
+      headers: { Location: url.pathname.replace(/\/+$/, "") + url.search },
+    })
+  }
+
+  const route = resolveRoute(app.repo, url.pathname)
+  if (route?.type === "source") {
+    return serveSource(
+      app,
+      req.method === "HEAD",
+      session,
+      principal,
+      route.source,
+    )
+  }
+  if (route?.type === "page") {
+    const agentBrowsing = app.hasPlugin(AGENT_BROWSING_PLUGIN_ID)
+    if (agentBrowsing && prefersMarkdown(req)) {
+      return withMarkdownAlternate(
+        serveSource(
+          app,
+          req.method === "HEAD",
+          session,
+          principal,
+          route.source,
+        ),
+        route.source.path,
+      )
+    }
+    let response = await renderPage(app, session, principal, route.source, {
+      scheme: requestScheme(req),
+    })
+    if (req.method === "HEAD") response = new Response(null, response)
+    return agentBrowsing
+      ? withMarkdownAlternate(response, route.source.path)
+      : response
+  }
+
+  return (
+    (await serveAsset(
+      app,
+      url.pathname,
+      req.method === "HEAD",
+      session,
+      principal,
+    )) ?? pageNotFound()
+  )
+}
+
+function serveSource(
+  app: Engine,
+  head: boolean,
+  session: CredentialSession,
+  principal: Principal,
+  source: Source,
+) {
+  const access = app.readAccess(principal, source)
+  if (access === "denied") return pageNotFound()
+  return withReadCache(
+    new Response(head ? null : source.content, {
+      headers: { "Content-Type": "text/markdown; charset=utf-8" },
+    }),
+    access,
+    session,
+  )
+}
+
+async function serveAsset(
+  app: Engine,
+  pathname: string,
+  head: boolean,
+  session: CredentialSession,
+  principal: Principal,
+) {
+  let path: string
+  try {
+    path = decodeURIComponent(pathname)
+  } catch {
+    return
+  }
+  if (path.includes("..")) return
+  const storagePath = app.repo.storagePath(path)
+  if (!storagePath || !(await app.repo.isFile(path))) return
+  const access = app.readAccess(principal, path)
+  if (access === "denied") return pageNotFound()
+  const body = head ? null : await app.environment.storage.readBlob(storagePath)
+  return withReadCache(new Response(body), access, session)
+}

package/server/page.ts

@@ -0,0 +1,21 @@
+const SCHEME_COOKIE = "pathmx-scheme"
+
+export { pageNotFound } from "../host/render.ts"
+
+function cookieValue(header: string | null, name: string) {
+  if (!header) return
+  for (const part of header.split(";")) {
+    const equals = part.indexOf("=")
+    if (equals === -1 || part.slice(0, equals).trim() !== name) continue
+    try {
+      return decodeURIComponent(part.slice(equals + 1).trim())
+    } catch {
+      return
+    }
+  }
+}
+
+export function requestScheme(request: Request) {
+  const value = cookieValue(request.headers.get("cookie"), SCHEME_COOKIE)
+  if (value === "light" || value === "dark") return value
+}

package/server/protocols.ts

@@ -0,0 +1,12 @@
+export const AGENT_BROWSING_PLUGIN_ID = "agent-browsing"
+
+const protocolRoutes: Readonly<Record<string, string>> = Object.freeze({
+  "/llms.txt": `/api/${AGENT_BROWSING_PLUGIN_ID}/llms.txt`,
+  "/robots.txt": `/api/${AGENT_BROWSING_PLUGIN_ID}/robots.txt`,
+  "/sitemap.xml": `/api/${AGENT_BROWSING_PLUGIN_ID}/sitemap.xml`,
+})
+
+/** @internal Map core-owned standard URLs onto their namespaced Plugin route. */
+export function protocolRoute(pathname: string) {
+  return protocolRoutes[pathname]
+}

package/server/representations.ts

@@ -0,0 +1,66 @@
+function acceptedQuality(header: string, target: string) {
+  const [targetType, targetSubtype] = target.split("/")
+  let quality = 0
+  let specificity = -1
+
+  for (const entry of header.split(",")) {
+    const [range = "", ...parameters] = entry.split(";")
+    const [type, subtype] = range.trim().toLowerCase().split("/")
+    if (
+      !type ||
+      !subtype ||
+      (type !== "*" && type !== targetType) ||
+      (subtype !== "*" && subtype !== targetSubtype)
+    ) {
+      continue
+    }
+
+    const candidateSpecificity =
+      (type === "*" ? 0 : 1) + (subtype === "*" ? 0 : 1)
+    const q = parameters
+      .map((parameter) => parameter.trim().match(/^q\s*=\s*(.+)$/i)?.[1])
+      .find((value) => value !== undefined)
+    const parsed = q === undefined ? 1 : Number(q)
+    const candidateQuality =
+      Number.isFinite(parsed) && parsed >= 0 && parsed <= 1 ? parsed : 0
+
+    if (
+      candidateSpecificity > specificity ||
+      (candidateSpecificity === specificity && candidateQuality > quality)
+    ) {
+      specificity = candidateSpecificity
+      quality = candidateQuality
+    }
+  }
+
+  return quality
+}
+
+export function prefersMarkdown(request: Request) {
+  const accept = request.headers.get("Accept")
+  if (!accept) return false
+  const markdown = acceptedQuality(accept, "text/markdown")
+  return markdown > 0 && markdown > acceptedQuality(accept, "text/html")
+}
+
+function appendVary(headers: Headers, name: string) {
+  const values = (headers.get("Vary") ?? "")
+    .split(",")
+    .map((value) => value.trim())
+    .filter(Boolean)
+  if (!values.some((value) => value.toLowerCase() === name.toLowerCase())) {
+    values.push(name)
+  }
+  headers.set("Vary", values.join(", "))
+}
+
+export function withMarkdownAlternate(response: Response, sourcePath: string) {
+  if (response.status >= 400) return response
+  appendVary(response.headers, "Accept")
+  const markdownPath = new URL(sourcePath, "http://pathmx.local").pathname
+  response.headers.append(
+    "Link",
+    `<${markdownPath}>; rel="alternate"; type="text/markdown"`,
+  )
+  return response
+}

package/server/router.ts

@@ -0,0 +1,131 @@
+import type { Repository } from "../repository.ts"
+import { resolveSourceId, type Source } from "../source/index.ts"
+import { tryCanonicalPath } from "../canonical.ts"
+import { isActorSource } from "../authority/actors.ts"
+
+type IndexRouteTable = {
+  revision: number
+  byDirectory: Map<string, Source[]>
+}
+
+const indexRouteTables = new WeakMap<Repository, IndexRouteTable>()
+
+export type Route =
+  { type: "page"; source: Source } | { type: "source"; source: Source }
+
+// Index-ness is name position only. Types and qualifiers are domain-defined
+// (`index` may be a valid type), so the name slot is the only unambiguous
+// place routing semantics can live — the route table stays inferable from
+// the file listing alone.
+export function isIndexSource(source: Source) {
+  return source.name === "index"
+}
+
+export function isPageSource(source: Source) {
+  return (
+    source.type !== "layout" &&
+    source.type !== "navigation" &&
+    !isActorSource(source)
+  )
+}
+
+export function sourceDirectory(source: Source) {
+  const slash = source.path.lastIndexOf("/")
+  return slash <= 0 ? "/" : source.path.slice(0, slash)
+}
+
+export function publicPath(source: Source) {
+  if (isPageSource(source) && isIndexSource(source))
+    return sourceDirectory(source)
+  return source.id
+}
+
+function sourceById(repo: Repository, path: string) {
+  return repo.atPath(path) ?? repo.get(resolveSourceId(path, {}))
+}
+
+function normalizePathname(pathname: string) {
+  let path: string
+  try {
+    path = decodeURIComponent(pathname)
+  } catch {
+    return
+  }
+  return tryCanonicalPath(path || "/")
+}
+
+export function resolveRoute(
+  repo: Repository,
+  pathname: string,
+): Route | undefined {
+  const path = normalizePathname(pathname)
+
+  if (!path) return
+
+  if (path.endsWith(".md")) {
+    const source = sourceById(repo, path)
+    return source ? { type: "source", source } : undefined
+  }
+
+  const exact = repo.get(resolveSourceId(path, {}))
+  if (exact && isPageSource(exact) && exact.id === path)
+    return { type: "page", source: exact }
+
+  const index = indexCandidates(repo, path)[0]
+
+  if (index) return { type: "page", source: index }
+}
+
+// Ties break by resolved id in codepoint order (not localeCompare — host
+// locale must not change routing). Bare `index.md` participates under its
+// default-typed id.
+function indexCandidates(repo: Repository, dir: string) {
+  return indexRouteTable(repo).byDirectory.get(dir) ?? []
+}
+
+function sortIndexCandidates(sources: Source[]) {
+  return sources.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0))
+}
+
+function indexRouteTable(repo: Repository) {
+  const cached = indexRouteTables.get(repo)
+  if (cached?.revision === repo.revision) return cached
+
+  const byDirectory = new Map<string, Source[]>()
+  for (const source of repo.all()) {
+    if (!isPageSource(source) || !isIndexSource(source)) continue
+    const dir = sourceDirectory(source)
+    const candidates = byDirectory.get(dir)
+    if (candidates) candidates.push(source)
+    else byDirectory.set(dir, [source])
+  }
+  for (const candidates of byDirectory.values()) {
+    sortIndexCandidates(candidates)
+  }
+  const table = { revision: repo.revision, byDirectory }
+  indexRouteTables.set(repo, table)
+  return table
+}
+
+export type IndexRouteConflict = {
+  dir: string
+  winner: Source
+  shadowed: Source[]
+}
+
+/** Directories where more than one index source claims the route. */
+export function indexRouteConflicts(repo: Repository) {
+  const conflicts: IndexRouteConflict[] = []
+  const { byDirectory } = indexRouteTable(repo)
+  for (const dir of [...byDirectory.keys()].sort()) {
+    const candidates = byDirectory.get(dir)!
+    if (candidates.length > 1) {
+      conflicts.push({
+        dir,
+        winner: candidates[0]!,
+        shadowed: candidates.slice(1),
+      })
+    }
+  }
+  return conflicts
+}