flamefront 0.0.0 → 0.1.0

package/src/fetch.ts

@@ -0,0 +1,280 @@
+import {
+  joinBasename,
+  type AppDefinition,
+  type RouteDefinition,
+} from "./index.ts"
+import type { OctaneDocuments } from "./octane.tsx"
+import type { DocumentMode, RenderedDocument } from "./server.ts"
+import {
+  isRouteFragmentRequest,
+  stripFlamefrontProtocolRequest,
+} from "./fragment-protocol.ts"
+import type { RouteFragmentArtifact } from "./fragment-client.ts"
+
+export interface TemplateContext<
+  Route extends RouteDefinition = RouteDefinition,
+> {
+  readonly request: Request
+  readonly route: Route | null
+  readonly mode: DocumentMode
+}
+
+export type TemplateLoader<Route extends RouteDefinition = RouteDefinition> = (
+  context: TemplateContext<Route>,
+) => string | Promise<string>
+
+export interface StaticFragmentContext<
+  Route extends RouteDefinition = RouteDefinition,
+> {
+  readonly request: Request
+  readonly route: Route
+}
+
+/** Load a pre-rendered static fragment from the host's asset system. */
+export type StaticFragmentLoader<
+  Route extends RouteDefinition = RouteDefinition,
+> = (
+  context: StaticFragmentContext<Route>,
+) =>
+  RouteFragmentArtifact | undefined | Promise<RouteFragmentArtifact | undefined>
+
+export interface ResponseHeadersContext<
+  Route extends RouteDefinition = RouteDefinition,
+> {
+  readonly request: Request
+  readonly route: Route | null
+  readonly mode: DocumentMode
+  readonly document: RenderedDocument
+}
+
+export type ResponseHeaders = HeadersInit
+
+/** Add or override response headers after document rendering. */
+export type ResponseHeadersHook<
+  Route extends RouteDefinition = RouteDefinition,
+> = (
+  context: ResponseHeadersContext<Route>,
+) => ResponseHeaders | Promise<ResponseHeaders>
+
+export type FetchMiddleware = (
+  request: Request,
+  next: () => Response | Promise<Response>,
+) => Response | Promise<Response>
+
+export type ServerDocuments = Pick<
+  OctaneDocuments,
+  "renderDocument" | "loadRouteData"
+> &
+  Partial<Pick<OctaneDocuments, "renderFragment">>
+
+/** Lifecycle operations shared by all Flamefront server adapters. */
+export interface ServerEntryLifecycle {
+  readonly renderDocument: OctaneDocuments["renderDocument"]
+  readonly loadRouteData: OctaneDocuments["loadRouteData"]
+  readonly renderFragment?: OctaneDocuments["renderFragment"]
+}
+
+/** A Web Fetch-compatible server entry. */
+export interface FlamefrontFetchServerEntry extends ServerEntryLifecycle {
+  readonly fetch: (request: Request) => Response | Promise<Response>
+}
+
+export interface FetchServerAssets<
+  Route extends RouteDefinition = RouteDefinition,
+> {
+  readonly loadTemplate: TemplateLoader<Route>
+  readonly loadStaticFragment?: StaticFragmentLoader<Route>
+}
+
+export interface FetchServerEntryOptions<
+  Route extends RouteDefinition = RouteDefinition,
+> {
+  readonly app: AppDefinition<Route>
+  readonly documents: ServerDocuments
+  readonly assets: FetchServerAssets<Route>
+  /** Applied outermost first, in declaration order. */
+  readonly middleware?: readonly FetchMiddleware[]
+  readonly headers?: ResponseHeadersHook<Route>
+}
+
+function mergeHeaders(target: Headers, source: HeadersInit | undefined): void {
+  if (source === undefined) {
+    return
+  }
+
+  for (const [name, value] of new Headers(source)) {
+    target.set(name, value)
+  }
+}
+
+function composeMiddleware(
+  middleware: readonly FetchMiddleware[],
+  handler: (request: Request) => Promise<Response>,
+): (request: Request) => Promise<Response> {
+  return middleware.reduceRight<(request: Request) => Promise<Response>>(
+    (next, current) => async (request) => current(request, () => next(request)),
+    handler,
+  )
+}
+
+/**
+ * Create the transport-neutral Flamefront request handler. Hosts can expose
+ * the returned `fetch` function directly or wrap it in their own adapter.
+ */
+export function createFetchServerEntry<
+  Route extends RouteDefinition = RouteDefinition,
+>(options: FetchServerEntryOptions<Route>): FlamefrontFetchServerEntry {
+  const defaultClientRoute = options.app.routes.find(
+    (route) => route.render === "client",
+  )
+
+  const handleRequest = async (request: Request): Promise<Response> => {
+    const url = new URL(request.url)
+    const match = options.app.match(url)
+
+    try {
+      if (
+        url.pathname === options.app.routing.basename &&
+        !match &&
+        defaultClientRoute
+      ) {
+        return new Response(null, {
+          status: 302,
+          headers: {
+            Location: joinBasename(
+              options.app.routing.basename,
+              defaultClientRoute.path,
+            ),
+          },
+        })
+      }
+
+      if (url.pathname === options.app.routing.dataPath) {
+        return options.documents.loadRouteData(request)
+      }
+
+      if (isRouteFragmentRequest(url)) {
+        const sanitizedRequest = stripFlamefrontProtocolRequest(request)
+        const fragmentMatch = options.app.match(sanitizedRequest.url)
+
+        if (!fragmentMatch || fragmentMatch.data.render === "client") {
+          return new Response("Not found", { status: 404 })
+        }
+
+        let artifact: RouteFragmentArtifact | undefined
+
+        if (
+          fragmentMatch.data.render === "static" &&
+          options.assets.loadStaticFragment
+        ) {
+          artifact = await options.assets.loadStaticFragment({
+            request: sanitizedRequest,
+            route: fragmentMatch.data,
+          })
+        }
+
+        if (!artifact && options.documents.renderFragment) {
+          artifact = await options.documents.renderFragment(sanitizedRequest)
+        }
+
+        if (!artifact) {
+          return new Response("Not found", { status: 404 })
+        }
+
+        const responseHeaders = new Headers({
+          "Content-Type":
+            "application/vnd.flamefront.fragment+json; charset=utf-8",
+        })
+
+        if (options.headers) {
+          mergeHeaders(
+            responseHeaders,
+            await options.headers({
+              request: sanitizedRequest,
+              route: fragmentMatch.data,
+              mode: fragmentMatch.data.render,
+              document: {
+                html: artifact.html,
+                routeData: artifact.routeData,
+                status: artifact.status,
+              },
+            }),
+          )
+        }
+
+        return new Response(JSON.stringify(artifact), {
+          status: artifact.status ?? 200,
+          headers: responseHeaders,
+        })
+      }
+
+      if (!match) {
+        return new Response("Not found", { status: 404 })
+      }
+
+      const mode: DocumentMode = url.searchParams.has("__flamefront_shell")
+        ? "shell"
+        : match.data.render
+      const template = await options.assets.loadTemplate({
+        request,
+        route: match.data,
+        mode,
+      })
+      const document = await options.documents.renderDocument(
+        template,
+        request,
+        { mode },
+      )
+      const responseHeaders = new Headers({
+        "Content-Type": "text/html; charset=utf-8",
+      })
+
+      mergeHeaders(responseHeaders, document.headers)
+      if (options.headers) {
+        mergeHeaders(
+          responseHeaders,
+          await options.headers({
+            request,
+            route: match.data,
+            mode,
+            document,
+          }),
+        )
+      }
+
+      return new Response(document.html, {
+        status: document.status ?? 200,
+        headers: responseHeaders,
+      })
+    } catch (error) {
+      if (error instanceof Response) {
+        return error
+      }
+
+      throw error
+    }
+  }
+
+  const composedFetch = composeMiddleware(
+    options.middleware ?? [],
+    handleRequest,
+  )
+  const fetch = async (request: Request): Promise<Response> => {
+    try {
+      return await composedFetch(request)
+    } catch (error) {
+      if (error instanceof Response) {
+        return error
+      }
+
+      throw error
+    }
+  }
+
+  return {
+    fetch,
+    renderDocument: options.documents.renderDocument,
+    loadRouteData: options.documents.loadRouteData,
+    renderFragment: options.documents.renderFragment,
+  }
+}

package/src/fragment-client.ts

@@ -0,0 +1,271 @@
+import type { HydrationMode, RouteBoundaryKind } from "./index.ts"
+import {
+  stripFlamefrontProtocolParams,
+  withRouteFragmentProtocol,
+} from "./fragment-protocol.ts"
+
+export const routeFragmentProtocol = "flamefront-route-fragment-v1" as const
+
+export type RouteFragmentCachePolicy = "server" | "static"
+
+export interface RouteFragmentBoundary {
+  readonly id: string
+  readonly boundary: string
+  readonly kind: RouteBoundaryKind
+  readonly parent?: string
+  readonly html: string
+}
+
+export interface RouteFragmentArtifact {
+  readonly protocol: typeof routeFragmentProtocol
+  readonly route: string
+  readonly boundary: string
+  readonly html: string
+  readonly routeData: unknown
+  readonly boundaries: readonly RouteFragmentBoundary[]
+  readonly hydration?: HydrationMode
+  readonly status?: number
+}
+
+export interface RouteFragmentLoadOptions {
+  readonly policy: RouteFragmentCachePolicy
+  readonly signal?: AbortSignal
+  readonly reload?: boolean
+}
+
+export interface RouteFragmentRoutingOptions {
+  readonly basename?: string
+}
+
+export function shouldHydrateRouteFragment(
+  hydration: HydrationMode | undefined,
+): boolean {
+  return hydration !== "none"
+}
+
+const staticFragmentRequests = new Map<string, Promise<RouteFragmentArtifact>>()
+const serverFragmentRequests = new Map<string, Promise<RouteFragmentArtifact>>()
+const latestRouteFragments = new Map<string, RouteFragmentArtifact>()
+
+function resolveRouteUrl(input: string | URL): URL {
+  const browserOrigin =
+    typeof location === "undefined" ? undefined : location.origin
+
+  if (!browserOrigin && typeof input === "string" && !URL.canParse(input)) {
+    throw new TypeError(
+      "flamefront route fragments require an absolute URL outside the browser.",
+    )
+  }
+
+  return stripFlamefrontProtocolParams(new URL(input, browserOrigin))
+}
+
+function basenamePath(pathname: string, basename: string): string | null {
+  if (basename === "/") {
+    return pathname
+  }
+
+  if (pathname === basename) {
+    return "/"
+  }
+
+  if (!pathname.startsWith(`${basename}/`)) {
+    return null
+  }
+
+  return pathname.slice(basename.length) || "/"
+}
+
+function staticFragmentKey(url: URL, basename: string): string {
+  const pathname = basenamePath(url.pathname, basename) ?? url.pathname
+
+  return `${url.origin}${pathname}`
+}
+
+function routeFragmentKey(url: URL, basename = "/"): string {
+  const pathname = basenamePath(url.pathname, basename) ?? url.pathname
+
+  return `${url.origin}${pathname}${url.search}${url.hash}`
+}
+
+function abortable<Data>(
+  pending: Promise<Data>,
+  signal: AbortSignal | undefined,
+): Promise<Data> {
+  if (!signal) {
+    return pending
+  }
+
+  if (signal.aborted) {
+    return Promise.reject(signal.reason)
+  }
+
+  return new Promise<Data>((resolve, reject) => {
+    const onAbort = () => reject(signal.reason)
+
+    signal.addEventListener("abort", onAbort, { once: true })
+    pending.then(
+      (value) => {
+        signal.removeEventListener("abort", onAbort)
+        resolve(value)
+      },
+      (error) => {
+        signal.removeEventListener("abort", onAbort)
+        reject(error)
+      },
+    )
+  })
+}
+
+export function isRouteFragmentArtifact(
+  value: unknown,
+): value is RouteFragmentArtifact {
+  if (!value || typeof value !== "object") {
+    return false
+  }
+
+  const artifact = value as Partial<RouteFragmentArtifact>
+
+  return (
+    artifact.protocol === routeFragmentProtocol &&
+    typeof artifact.route === "string" &&
+    typeof artifact.boundary === "string" &&
+    typeof artifact.html === "string" &&
+    Array.isArray(artifact.boundaries)
+  )
+}
+
+export function assertRouteFragmentArtifact(
+  value: unknown,
+): RouteFragmentArtifact {
+  if (!isRouteFragmentArtifact(value)) {
+    throw new Error(
+      "flamefront route fragment response has an invalid protocol.",
+    )
+  }
+
+  return value
+}
+
+export function getRouteFragment(
+  url: string | URL,
+  routing: RouteFragmentRoutingOptions = {},
+): RouteFragmentArtifact | undefined {
+  return latestRouteFragments.get(
+    routeFragmentKey(resolveRouteUrl(url), routing.basename ?? "/"),
+  )
+}
+
+function fetchRouteFragment(
+  routeUrl: URL,
+  basename: string,
+  signal: AbortSignal | undefined,
+): Promise<RouteFragmentArtifact> {
+  const endpoint = withRouteFragmentProtocol(routeUrl)
+
+  return globalThis
+    .fetch(endpoint, {
+      headers: { Accept: "application/vnd.flamefront.fragment+json" },
+      ...(signal ? { signal } : {}),
+    })
+    .then(async (response) => {
+      if (response.redirected) {
+        const location = stripFlamefrontProtocolParams(response.url)
+        const pathname =
+          basenamePath(location.pathname, basename) ?? location.pathname
+
+        throw new Response(null, {
+          status: 302,
+          headers: {
+            Location: `${pathname}${location.search}${location.hash}`,
+          },
+        })
+      }
+
+      if (response.status >= 300 && response.status < 400) {
+        throw response
+      }
+
+      let value: unknown
+
+      try {
+        value = await response.json()
+      } catch {
+        if (!response.ok) {
+          throw new Error(
+            `flamefront route fragment request failed with ${response.status}.`,
+          )
+        }
+
+        throw new Error(
+          "flamefront route fragment response has an invalid protocol.",
+        )
+      }
+
+      return assertRouteFragmentArtifact(value)
+    })
+}
+
+export function loadRouteFragment(
+  url: string | URL,
+  routing: RouteFragmentRoutingOptions = {},
+  options: RouteFragmentLoadOptions,
+): Promise<RouteFragmentArtifact> {
+  const routeUrl = resolveRouteUrl(url)
+  const handoffKey = routeFragmentKey(routeUrl, routing.basename ?? "/")
+  const requests =
+    options.policy === "static"
+      ? staticFragmentRequests
+      : serverFragmentRequests
+  const requestKey =
+    options.policy === "static"
+      ? staticFragmentKey(routeUrl, routing.basename ?? "/")
+      : routeUrl.href
+
+  if (options.reload) {
+    requests.delete(requestKey)
+  }
+
+  let pending = requests.get(requestKey)
+
+  if (!pending) {
+    pending = fetchRouteFragment(
+      routeUrl,
+      routing.basename ?? "/",
+      options.signal,
+    )
+    requests.set(requestKey, pending)
+
+    const evict = () => {
+      if (requests.get(requestKey) === pending) {
+        requests.delete(requestKey)
+      }
+    }
+
+    if (options.policy === "static") {
+      void pending.catch(evict)
+    } else {
+      void pending.then(evict, evict)
+    }
+  }
+
+  return abortable(pending, options.signal).then((artifact) => {
+    latestRouteFragments.set(handoffKey, artifact)
+    return artifact
+  })
+}
+
+export async function prefetchRouteFragment(
+  url: string | URL,
+  policy: RouteFragmentCachePolicy,
+  routing: RouteFragmentRoutingOptions = {},
+  options: Omit<RouteFragmentLoadOptions, "policy"> = {},
+): Promise<void> {
+  await loadRouteFragment(url, routing, { ...options, policy })
+}
+
+export type {
+  GeneratedHydration,
+  GeneratedRouteMetadata,
+  HydrationMode,
+} from "./index.ts"

package/src/fragment-hydration-client.tsx

@@ -0,0 +1,81 @@
+import {
+  createRoot,
+  hydrateRoot,
+  setDangerouslySetInnerHTML,
+  setHTML,
+} from "octane"
+import { outletIdentifierPrefix } from "./identifier-prefix.ts"
+
+type RenderableComponent = (props: Record<string, unknown>) => unknown
+
+interface OutletRoot {
+  unmount(): void
+  render(Component: RenderableComponent, props?: Record<string, unknown>): void
+}
+
+function removeHostChildRange(html: string): string {
+  const start = "<!--[-->"
+  const end = "<!--]-->"
+
+  return html.startsWith(start) && html.endsWith(end)
+    ? html.slice(start.length, -end.length)
+    : html
+}
+
+function createOutletRoot(root: ReturnType<typeof createRoot>): OutletRoot {
+  return {
+    unmount: () => root.unmount(),
+    render: (nextComponent, props) => {
+      root.render(nextComponent, props)
+    },
+  }
+}
+
+/** Transfer inserted fragment DOM from the outer root to a nested Octane root. */
+export function hydrateRouteFragment(
+  host: HTMLDivElement,
+  Component: RenderableComponent,
+): OutletRoot {
+  const html = host.innerHTML
+
+  setDangerouslySetInnerHTML(host, null)
+  setHTML(host, html)
+
+  const root = hydrateRoot(host, Component, undefined, {
+    identifierPrefix: outletIdentifierPrefix,
+  })
+
+  return {
+    unmount: () => root.unmount(),
+    render: (nextComponent) => root.render(nextComponent),
+  }
+}
+
+/** Mount a routed outlet into its own root after the outer shell commits. */
+export function renderRouteOutlet(
+  host: HTMLDivElement,
+  Component: RenderableComponent,
+  hydrate: boolean,
+): OutletRoot {
+  if (hydrate) {
+    const html = removeHostChildRange(host.innerHTML)
+
+    setDangerouslySetInnerHTML(host, null)
+    setHTML(host, html)
+
+    const root = hydrateRoot(host, Component, undefined, {
+      identifierPrefix: outletIdentifierPrefix,
+    })
+
+    return createOutletRoot(root)
+  }
+
+  setDangerouslySetInnerHTML(host, null)
+  setHTML(host, "")
+
+  const root = createRoot(host, { identifierPrefix: outletIdentifierPrefix })
+
+  root.render(Component)
+
+  return createOutletRoot(root)
+}

package/src/fragment-protocol.ts

@@ -0,0 +1,39 @@
+export const flamefrontFragmentQueryParam = "__flamefront_fragment"
+export const flamefrontShellQueryParam = "__flamefront_shell"
+export const flamefrontFragmentQueryValue = "1"
+
+/** Remove framework-only query parameters before a URL reaches app code. */
+export function stripFlamefrontProtocolParams(input: string | URL): URL {
+  const url = new URL(input, "http://flamefront.local")
+
+  url.searchParams.delete(flamefrontFragmentQueryParam)
+  url.searchParams.delete(flamefrontShellQueryParam)
+  return url
+}
+
+export function isRouteFragmentRequest(input: string | URL): boolean {
+  const url = new URL(input, "http://flamefront.local")
+
+  return (
+    url.searchParams.get(flamefrontFragmentQueryParam) ===
+    flamefrontFragmentQueryValue
+  )
+}
+
+/** Mark a route URL for the fragment transport. */
+export function withRouteFragmentProtocol(input: string | URL): URL {
+  const url = stripFlamefrontProtocolParams(input)
+
+  url.searchParams.set(
+    flamefrontFragmentQueryParam,
+    flamefrontFragmentQueryValue,
+  )
+  return url
+}
+
+/** Pass a request to a loader without leaking framework protocol parameters. */
+export function stripFlamefrontProtocolRequest(request: Request): Request {
+  const url = stripFlamefrontProtocolParams(request.url)
+
+  return new Request(url, request)
+}