@pathmx/core 0.5.0

package/host/plugin-host.ts

@@ -0,0 +1,487 @@
+import type { Engine } from "./engine.ts"
+import {
+  anonymousCredentialHost,
+  type CredentialHost,
+} from "../authority/credentials.ts"
+import {
+  ViewComponentRegistry,
+  type CompiledViewPlan,
+} from "../view/components.ts"
+import {
+  canonicalPluginId,
+  type AppContext,
+  type CompileContext,
+  type DocumentAssetContext,
+  type PageContext,
+  type Plugin,
+  type PluginContext,
+  type PluginFactory,
+  type PluginInvalidation,
+  type SourceTransition,
+  type ViewContext,
+} from "../plugins/types.ts"
+import type { Source } from "../source/index.ts"
+import type { KnownActorIndex, Principal } from "../authority/model.ts"
+import { PluginDatabases } from "../database.ts"
+import { createAppContext, createPluginContext } from "../plugins/context.ts"
+import { ServerRouteRegistry } from "../server/routes.ts"
+import {
+  describeAction,
+  type ActionAffordance,
+  type ActionContribution,
+} from "../actions/actions.ts"
+import { applicationSchemaView, SchemaRegistry } from "../schema/registry.ts"
+import { instantiatePlugin } from "../plugins/preset.ts"
+import type { HtmlRewriteRule } from "../environment.ts"
+import type { QueryContribution } from "../query/model.ts"
+
+export type { CompiledViewPlan }
+
+export class PluginRegistrationError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = "PluginRegistrationError"
+  }
+}
+
+type HookErrorHandler = (error: unknown) => boolean
+
+function validatePluginRequirements(plugins: readonly Plugin[]) {
+  const positions = new Map(plugins.map((plugin, index) => [plugin.id, index]))
+  for (const plugin of plugins) {
+    if (plugin.requires === undefined) continue
+    if (!Array.isArray(plugin.requires)) {
+      throw new PluginRegistrationError(
+        `Plugin ${plugin.id} requires must be a list of plugin ids.`,
+      )
+    }
+    const seen = new Set<string>()
+    for (const dependency of plugin.requires) {
+      try {
+        canonicalPluginId(dependency)
+      } catch (error) {
+        throw new PluginRegistrationError(
+          error instanceof Error ? error.message : String(error),
+        )
+      }
+      if (dependency === plugin.id) {
+        throw new PluginRegistrationError(
+          `Plugin ${plugin.id} cannot require itself.`,
+        )
+      }
+      if (seen.has(dependency)) {
+        throw new PluginRegistrationError(
+          `Plugin ${plugin.id} requires ${dependency} more than once.`,
+        )
+      }
+      seen.add(dependency)
+      const dependencyPosition = positions.get(dependency)
+      if (dependencyPosition === undefined) {
+        throw new PluginRegistrationError(
+          `Plugin ${plugin.id} requires missing plugin ${dependency}.`,
+        )
+      }
+      if (dependencyPosition > positions.get(plugin.id)!) {
+        throw new PluginRegistrationError(
+          `Plugin ${plugin.id} requires plugin ${dependency} to be registered first.`,
+        )
+      }
+    }
+  }
+}
+
+/** Own plugin installation, View Components, routes, and ordered hook phases. */
+export class PluginHost {
+  private installed: Plugin[] = []
+  private ids = new Set<string>()
+  private frozen = false
+  private credentialHost: CredentialHost = anonymousCredentialHost()
+  private credentialOwner?: string
+  private credentialClosing?: Promise<void>
+  private closing?: Promise<void>
+  private views = new ViewComponentRegistry()
+  private routes = new ServerRouteRegistry()
+  private actions = new Map<string, ActionContribution>()
+  private lifecycleContexts = new Map<string, PluginContext>()
+  private appContexts = new Map<string, AppContext>()
+  private schemaRegistry = new SchemaRegistry()
+  readonly schema = applicationSchemaView(this.schemaRegistry)
+
+  constructor(
+    private databases = new PluginDatabases(undefined, ".pathmx/state"),
+  ) {}
+
+  get plugins(): readonly Plugin[] {
+    return this.installed
+  }
+
+  has(id: string) {
+    return this.ids.has(id)
+  }
+
+  register(plugin: PluginFactory | Plugin) {
+    if (this.frozen) {
+      throw new PluginRegistrationError(
+        "Plugin registration is frozen after the engine is ready.",
+      )
+    }
+
+    const instance = instantiatePlugin(plugin)
+    canonicalPluginId(instance.id)
+    if (this.ids.has(instance.id)) {
+      throw new PluginRegistrationError(`Duplicate plugin id: ${instance.id}`)
+    }
+    if (instance.credentials && this.credentialOwner) {
+      throw new PluginRegistrationError(
+        `Credential provider already registered by plugin ${this.credentialOwner}.`,
+      )
+    }
+    let routes: ReturnType<ServerRouteRegistry["prepare"]>
+    let actions: readonly (readonly [string, ActionContribution])[]
+    let schema: ReturnType<SchemaRegistry["prepare"]>
+    let database
+    try {
+      database = instance.database
+        ? this.databases.prepare(instance.database)
+        : undefined
+      routes = this.routes.prepare(instance)
+      schema = this.schemaRegistry.prepare(instance.id, instance.schema)
+      actions = this.prepareActions(schema.actions)
+      this.views.register(instance)
+    } catch (error) {
+      throw new PluginRegistrationError(
+        error instanceof Error ? error.message : String(error),
+      )
+    }
+
+    if (database) this.databases.register(instance.id, database)
+    this.routes.register(routes)
+    for (const [name, action] of actions) this.actions.set(name, action)
+    this.schemaRegistry.register(schema)
+    if (instance.credentials) {
+      this.credentialHost = instance.credentials
+      this.credentialOwner = instance.id
+    }
+    this.ids.add(instance.id)
+    this.installed.push(instance)
+  }
+
+  private prepareActions(
+    actions: readonly (readonly [string, ActionContribution])[],
+  ) {
+    for (const [name, action] of actions) {
+      if (this.actions.has(name)) {
+        throw new Error(`Duplicate Plugin Action: ${name}`)
+      }
+    }
+    return actions
+  }
+
+  action(name: string) {
+    return this.actions.get(name)
+  }
+
+  async actionAffordances(
+    principal: Principal,
+    target: Source,
+    env: Engine,
+  ): Promise<readonly ActionAffordance[]> {
+    const described = await Promise.all(
+      [...this.actions].map(([name, action]) =>
+        describeAction(name, action, {
+          principal,
+          target,
+          yaml: env.environment.yaml,
+          can: (capability) =>
+            env.hasSourceCapability(principal, target, capability),
+        }),
+      ),
+    )
+    return Object.freeze(
+      described.filter((item): item is ActionAffordance => item !== undefined),
+    )
+  }
+
+  freeze() {
+    validatePluginRequirements(this.installed)
+    this.frozen = true
+  }
+
+  private lifecycleContext(plugin: Plugin | string, engine: Engine) {
+    const id = typeof plugin === "string" ? plugin : plugin.id
+    const existing = this.lifecycleContexts.get(id)
+    if (existing) return existing
+    const context = createPluginContext(id, engine, this.databases.get(id))
+    this.lifecycleContexts.set(id, context)
+    return context
+  }
+
+  appContext(plugin: Plugin | string, engine: Engine) {
+    const id = typeof plugin === "string" ? plugin : plugin.id
+    const existing = this.appContexts.get(id)
+    if (existing) return existing
+    const context = createAppContext(
+      this.lifecycleContext(id, engine),
+      engine,
+      this.componentContext(id, engine),
+    )
+    this.appContexts.set(id, context)
+    return context
+  }
+
+  private componentContext(
+    plugin: string,
+    engine: Engine,
+  ): AppContext["components"] {
+    return Object.freeze({
+      claim: (sourcePath, tags) =>
+        this.replaceAuthoredComponents(sourcePath, tags),
+      release: (sourcePath) => this.deleteAuthoredComponents(sourcePath),
+      has: (tag) => this.hasView(tag),
+      replaceData: (sourcePath, components) =>
+        this.replaceAuthoredDataComponents(plugin, sourcePath, components),
+      prepareData: (tag, props, origin, ctx) =>
+        this.prepareDataComponent(tag, props, origin, ctx, engine),
+      renderData: (prepared, data, ctx) =>
+        this.renderDataComponent(prepared, data, ctx, engine),
+    })
+  }
+
+  async setup(env: Engine) {
+    for (const plugin of this.installed) {
+      await plugin.setup?.(this.lifecycleContext(plugin, env))
+    }
+  }
+
+  private async shutdown(env: Engine) {
+    const errors: unknown[] = []
+    try {
+      await this.closeCredentials()
+    } catch (error) {
+      errors.push(error)
+    }
+    for (const plugin of [...this.installed].reverse()) {
+      try {
+        await plugin.close?.(this.lifecycleContext(plugin, env))
+      } catch (error) {
+        errors.push(error)
+      }
+    }
+    try {
+      await this.databases.close()
+    } catch (error) {
+      errors.push(error)
+    }
+    if (errors.length)
+      throw new AggregateError(errors, "Plugin shutdown failed.")
+  }
+
+  close(env: Engine) {
+    return (this.closing ??= this.shutdown(env))
+  }
+
+  private async measure<T>(
+    plugin: Plugin,
+    hook: string,
+    label: string | undefined,
+    env: Engine,
+    run: () => T | Promise<T>,
+  ) {
+    const start = performance.now()
+    try {
+      return await run()
+    } finally {
+      env.perf.record(
+        `${plugin.name ?? "plugin"}.${hook}`,
+        performance.now() - start,
+        label,
+      )
+    }
+  }
+
+  index(source: Source, env: Engine, onError?: HookErrorHandler) {
+    this.schemaRegistry.index(source, onError)
+    for (const plugin of this.installed) {
+      try {
+        plugin.index?.(source, this.appContext(plugin, env))
+      } catch (error) {
+        if (!onError?.(error)) throw error
+      }
+    }
+  }
+
+  unindex(sourcePath: string, env: Engine) {
+    for (const plugin of this.installed) {
+      plugin.unindex?.(sourcePath, this.appContext(plugin, env))
+    }
+  }
+
+  async precompile(markdown: string, ctx: CompileContext, env: Engine) {
+    for (const plugin of this.installed) {
+      if (!plugin.precompile) continue
+      markdown =
+        (await this.measure(plugin, "precompile", ctx.source.path, env, () =>
+          plugin.precompile!(markdown, ctx, this.appContext(plugin, env)),
+        )) ?? markdown
+    }
+    return this.views.compileSyntax(markdown, ctx)
+  }
+
+  compileVariables(markdown: string, ctx: CompileContext) {
+    return this.views.compileVariables(markdown, ctx)
+  }
+
+  async postcompile(html: string, ctx: CompileContext, env: Engine) {
+    html = this.views.restoreSyntax(html, ctx)
+    if (this.views.hasAny(ctx.elements)) {
+      html = this.views.stampOrigins(
+        html,
+        ctx.source.path,
+        env.environment.rewriteHtml,
+      )
+    }
+    for (const plugin of this.installed) {
+      if (!plugin.postcompile) continue
+      html =
+        (await this.measure(plugin, "postcompile", ctx.source.path, env, () =>
+          plugin.postcompile!(html, ctx, this.appContext(plugin, env)),
+        )) ?? html
+    }
+    return html
+  }
+
+  async page(
+    html: string,
+    ctx: PageContext,
+    env: Engine,
+    excludedPluginId?: string,
+  ) {
+    for (const plugin of this.installed) {
+      if (!plugin.page || plugin.id === excludedPluginId) continue
+      html =
+        (await this.measure(plugin, "page", ctx.source.path, env, () =>
+          plugin.page!(html, ctx, this.appContext(plugin, env)),
+        )) ?? html
+    }
+    return html
+  }
+
+  invalidations(transition: SourceTransition, env: Engine) {
+    const invalidations: PluginInvalidation[] = []
+    for (const plugin of this.installed) {
+      const invalidation = plugin.invalidate?.(
+        transition,
+        this.appContext(plugin, env),
+      )
+      if (invalidation) invalidations.push(invalidation)
+    }
+    return invalidations
+  }
+
+  async documentAssets(ctx: DocumentAssetContext, env: Engine) {
+    for (const plugin of this.installed) {
+      await plugin.documentAssets?.(ctx, this.appContext(plugin, env))
+    }
+  }
+
+  replaceAuthoredComponents(sourcePath: string, tags: Iterable<string>) {
+    this.views.replaceAuthored(sourcePath, tags)
+  }
+
+  replaceAuthoredDataComponents(
+    plugin: string,
+    sourcePath: string,
+    components: Parameters<ViewComponentRegistry["replaceData"]>[2],
+  ) {
+    this.views.replaceData(plugin, sourcePath, components)
+  }
+
+  deleteAuthoredComponents(sourcePath: string) {
+    this.views.deleteAuthored(sourcePath)
+  }
+
+  hasView(tag: string) {
+    return this.views.has(tag)
+  }
+
+  prepareDataComponent(
+    tag: string,
+    props: Readonly<Record<string, string>>,
+    origin: Source,
+    ctx: PageContext,
+    env: Engine,
+  ) {
+    return this.views.prepareData(tag, props, origin, ctx, env)
+  }
+
+  renderDataComponent(
+    prepared: unknown,
+    data: unknown,
+    ctx: ViewContext,
+    env: Engine,
+  ) {
+    return this.views.renderData(prepared, data, ctx, env)
+  }
+
+  query(reference: string | QueryContribution) {
+    return this.schemaRegistry.registeredQuery(reference)
+  }
+
+  queries() {
+    return this.schemaRegistry.queries()
+  }
+
+  compileViewComponents(
+    html: string,
+    source: Source,
+    ctx: PageContext,
+    env: Engine,
+  ) {
+    return this.views.compile(html, source, ctx, env)
+  }
+
+  async renderView(
+    html: string,
+    plan: CompiledViewPlan | undefined,
+    ctx: ViewContext,
+    env: Engine,
+    init?: ResponseInit,
+  ) {
+    const segments = await this.views.renderSegments(html, plan, ctx, env)
+    const rules: HtmlRewriteRule[] = []
+    for (const plugin of this.installed) {
+      if (!plugin.streamSelectors) continue
+      for (const [selector, handler] of Object.entries(
+        plugin.streamSelectors(ctx, this.appContext(plugin, env)),
+      )) {
+        rules.push([selector, handler])
+      }
+    }
+    const body = new Blob(segments, { type: "text/html; charset=utf-8" })
+    return env.environment.rewriteHtml(new Response(body, init), rules)
+  }
+
+  resolveCredentials(request: Request, actors: KnownActorIndex, env: Engine) {
+    return env.perf.measureAsync(
+      "credentials.resolve",
+      () => this.credentialHost.resolve(request, actors),
+      new URL(request.url).pathname,
+    )
+  }
+
+  credentialRequest(request: Request, actors: KnownActorIndex) {
+    return this.credentialHost.fetch(request, actors)
+  }
+
+  readyCredentials(actors: KnownActorIndex) {
+    return this.credentialHost.ready(actors)
+  }
+
+  closeCredentials() {
+    return (this.credentialClosing ??= this.credentialHost.close())
+  }
+
+  serverRoute(request: Request, url: URL, env: Engine, publicUrl = url) {
+    return this.routes.dispatch(request, url, env, publicUrl)
+  }
+}

package/host/render.ts

@@ -0,0 +1,102 @@
+import type { CredentialSession, Principal } from "../authority/model.ts"
+import { interpolateText, type Source } from "../source/index.ts"
+import { escapeHtml } from "../util.ts"
+import type { CompiledPage } from "../plugins/types.ts"
+import type { Engine } from "./engine.ts"
+import { withReadCache } from "./response.ts"
+import shellHtml from "./shell.html" with { type: "text" }
+
+// Bun types `*.html` as HTMLBundle; `type: "text"` inlines the file as a string.
+const shell = shellHtml as unknown as string
+
+export type PageRenderOptions = Readonly<{
+  status?: number
+  headers?: HeadersInit
+  scheme?: "light" | "dark"
+}>
+
+export function pageNotFound() {
+  return new Response(
+    "# Not Found\n\nThe requested resource does not exist or is not available. Start at [the site root](/) or browse the public index in [/llms.txt](/llms.txt).\n",
+    {
+      status: 404,
+      headers: { "Content-Type": "text/markdown; charset=utf-8" },
+    },
+  )
+}
+
+async function renderCompiledPage(
+  app: Engine,
+  session: CredentialSession,
+  principal: Principal,
+  source: Source,
+  page: CompiledPage,
+  options: PageRenderOptions = {},
+) {
+  const assets = await app.documentHead(page)
+  const htmlAttrs = options.scheme
+    ? ` data-pmx-scheme="${options.scheme}" style="color-scheme: ${options.scheme}"`
+    : ""
+  const actorId = principal.type === "actor" ? principal.actor.id : ""
+  const html = interpolateText(shell, {
+    head: assets,
+    html_attrs: htmlAttrs,
+    route: escapeHtml(page.route),
+    actor: escapeHtml(actorId),
+    content: page.html,
+  })
+  const headers = new Headers(options.headers)
+  if (!headers.has("Content-Type")) {
+    headers.set("Content-Type", "text/html; charset=utf-8")
+  }
+  return app.rewrite(session, html, source, {
+    status: options.status,
+    headers,
+  })
+}
+
+/** Render one Source through the canonical cached server pipeline. */
+export async function renderPage(
+  app: Engine,
+  session: CredentialSession,
+  principal: Principal,
+  source: Source,
+  options: PageRenderOptions = {},
+) {
+  const access = app.readAccess(principal, source)
+  if (access === "denied") return pageNotFound()
+  const response = await renderCompiledPage(
+    app,
+    session,
+    principal,
+    source,
+    await app.ensurePage(source),
+    options,
+  )
+  return withReadCache(response, access, session)
+}
+
+/** Render once without retaining live recompilation state. */
+export async function renderUncachedPage(
+  app: Engine,
+  session: CredentialSession,
+  principal: Principal,
+  source: Source,
+  options: PageRenderOptions = {},
+) {
+  const access = app.readAccess(principal, source)
+  if (access === "denied") return pageNotFound()
+  try {
+    const response = await renderCompiledPage(
+      app,
+      session,
+      principal,
+      source,
+      await app.compilePage(source),
+      options,
+    )
+    return withReadCache(response, access, session)
+  } finally {
+    app.forgetCompiledPage(source.path)
+  }
+}

package/host/response.ts

@@ -0,0 +1,20 @@
+import type { CredentialSession } from "../authority/model.ts"
+
+export function privateResponse(response: Response) {
+  response.headers.set("Cache-Control", "private, no-store")
+  const vary = response.headers.get("Vary")
+  if (!vary?.split(",").some((value) => value.trim() === "Cookie")) {
+    response.headers.append("Vary", "Cookie")
+  }
+  return response
+}
+
+export function withReadCache(
+  response: Response,
+  access: "public" | "private",
+  session: CredentialSession,
+) {
+  return access === "private" || session.type === "authenticated"
+    ? privateResponse(response)
+    : response
+}

package/host/shell.html

@@ -0,0 +1,15 @@
+<!doctype html>
+<html lang="en" data-pmx-document="1" {{ html_attrs }}>
+  <head>
+    {{ head }}
+  </head>
+  <body>
+    <div
+      data-pmx-view
+      data-pmx-route="{{ route }}"
+      data-pmx-actor="{{ actor }}"
+    >
+      {{ content }}
+    </div>
+  </body>
+</html>