flamefront 0.0.0 → 0.1.0-alpha.0

package/src/server.ts

@@ -0,0 +1,240 @@
+import type { Match } from "@remix-run/route-pattern/match"
+import {
+  type AppDefinition,
+  type MatchRouteOptions,
+  type RenderMode,
+  type RouteDefinition,
+} from "./index.ts"
+import { stripFlamefrontProtocolRequest } from "./fragment-protocol.ts"
+
+export interface LoaderArgs<Context = unknown> {
+  readonly request: Request
+  readonly params: Readonly<Record<string, string | undefined>>
+  readonly context: Context
+}
+
+export type Loader<Data = unknown, Context = unknown> = (
+  args: LoaderArgs<Context>,
+) => Data | Promise<Data>
+
+export interface RouteModule<Data = unknown, Context = unknown> {
+  readonly default: unknown
+  readonly loader?: Loader<Data, Context>
+}
+
+export type DocumentMode = "shell" | RenderMode
+export type RequestPurpose = "data" | "document"
+
+/** Inputs for constructing one request-scoped value for route work. */
+export interface RequestContextArgs<
+  Route extends RouteDefinition = RouteDefinition,
+> {
+  readonly request: Request
+  readonly route: Route | null
+  readonly params: Readonly<Record<string, string | undefined>>
+  readonly purpose: RequestPurpose
+  readonly mode?: DocumentMode
+}
+
+export type RequestContextFactory<
+  Context = unknown,
+  Route extends RouteDefinition = RouteDefinition,
+> = (args: RequestContextArgs<Route>) => Context | Promise<Context>
+
+/** Import a generated or application-provided route module by its entry ID. */
+export type RouteImporter<Data = unknown, Context = unknown> = (
+  entry: string,
+) => Promise<RouteModule<Data, Context>>
+
+export interface RenderedDocument {
+  readonly html: string
+  readonly routeData?: unknown
+  readonly status?: number
+  readonly headers?: HeadersInit
+}
+
+export type RenderDocumentResult = string | RenderedDocument
+
+export interface LoadedRoute<
+  Data = unknown,
+  Context = unknown,
+  Route extends RouteDefinition = RouteDefinition,
+> {
+  readonly route: Route
+  readonly module: RouteModule<Data, Context>
+  readonly loaderData: Data | undefined
+}
+
+export interface RouteRuntimeContextOptions {
+  readonly purpose: RequestPurpose
+  readonly mode?: DocumentMode
+}
+
+export interface RouteLoadOptions<Context = unknown> {
+  readonly context?: Context
+  readonly mode?: DocumentMode
+}
+
+export interface RouteRuntime<
+  Context = unknown,
+  Route extends RouteDefinition = RouteDefinition,
+> {
+  readonly app: AppDefinition<Route>
+  readonly importRoute: RouteImporter<unknown, Context>
+  readonly match: (
+    url: string | URL,
+    options?: MatchRouteOptions,
+  ) => Match<string, Route> | null
+  readonly createRequestContext: (
+    request: Request,
+    options: RouteRuntimeContextOptions,
+  ) => Promise<Context | undefined>
+  readonly loadRoute: (
+    request: Request,
+    options?: RouteLoadOptions<Context>,
+  ) => Promise<LoadedRoute<unknown, Context, Route> | null>
+  readonly loadRouteData: (request: Request) => Promise<Response>
+}
+
+export interface RouteRuntimeOptions<
+  Context = unknown,
+  Route extends RouteDefinition = RouteDefinition,
+> {
+  readonly app: AppDefinition<Route>
+  readonly importRoute: RouteImporter<unknown, Context>
+  /** Build request context for data requests and document router queries. */
+  readonly requestContext?: RequestContextFactory<Context, Route>
+}
+
+async function loadMatchedRoute<
+  Data = unknown,
+  Context = unknown,
+  Route extends RouteDefinition = RouteDefinition,
+>(
+  match: Match<string, Route>,
+  request: Request,
+  importRoute: RouteImporter<Data, Context>,
+  context?: Context,
+): Promise<LoadedRoute<Data, Context, Route>> {
+  const routeModule = await importRoute(match.data.entry)
+  const loaderData = routeModule.loader
+    ? await routeModule.loader({
+        request,
+        params: match.params,
+        context: context as Context,
+      })
+    : undefined
+
+  return {
+    route: match.data,
+    module: routeModule,
+    loaderData,
+  }
+}
+
+export function createRouteRuntime<
+  Context = unknown,
+  Route extends RouteDefinition = RouteDefinition,
+>(options: RouteRuntimeOptions<Context, Route>): RouteRuntime<Context, Route> {
+  const createRequestContext = async (
+    request: Request,
+    contextOptions: RouteRuntimeContextOptions,
+    match = options.app.match(request.url),
+  ): Promise<Context | undefined> => {
+    if (!options.requestContext) {
+      return undefined
+    }
+
+    return options.requestContext({
+      request,
+      route: match?.data ?? null,
+      params: match?.params ?? {},
+      purpose: contextOptions.purpose,
+      ...(contextOptions.mode === undefined
+        ? {}
+        : { mode: contextOptions.mode }),
+    })
+  }
+
+  const loadRouteForRequest = async (
+    request: Request,
+    loadOptions: RouteLoadOptions<Context> = {},
+  ): Promise<LoadedRoute<unknown, Context, Route> | null> => {
+    const sanitizedRequest = stripFlamefrontProtocolRequest(request)
+    const match = options.app.match(sanitizedRequest.url)
+
+    if (!match) {
+      return null
+    }
+
+    const context =
+      "context" in loadOptions
+        ? loadOptions.context
+        : await createRequestContext(
+            sanitizedRequest,
+            { purpose: "data", mode: loadOptions.mode },
+            match,
+          )
+
+    return loadMatchedRoute(
+      match,
+      sanitizedRequest,
+      options.importRoute,
+      context,
+    )
+  }
+
+  const loadRouteData = async (request: Request): Promise<Response> => {
+    const routeUrl = new URL(request.url).searchParams.get("url")
+
+    if (!routeUrl) {
+      return new Response("Missing route URL.", { status: 400 })
+    }
+
+    const loaded = await loadRouteForRequest(
+      stripFlamefrontProtocolRequest(
+        new Request(routeUrl, {
+          method: "GET",
+          headers: request.headers,
+          signal: request.signal,
+        }),
+      ),
+    )
+
+    if (!loaded) {
+      return new Response("Not found.", { status: 404 })
+    }
+
+    return Response.json(loaded.loaderData ?? null)
+  }
+
+  return {
+    app: options.app,
+    importRoute: options.importRoute,
+    match: options.app.match,
+    createRequestContext: (request, contextOptions) =>
+      createRequestContext(request, contextOptions),
+    loadRoute: loadRouteForRequest,
+    loadRouteData,
+  }
+}
+
+export async function loadRoute<
+  Data = unknown,
+  Context = unknown,
+  Route extends RouteDefinition = RouteDefinition,
+>(
+  app: AppDefinition<Route>,
+  request: Request,
+  importRoute: (entry: string) => Promise<RouteModule<Data, Context>>,
+  context?: Context,
+): Promise<LoadedRoute<Data, Context, Route> | null> {
+  const sanitizedRequest = stripFlamefrontProtocolRequest(request)
+  const match = app.match(sanitizedRequest.url)
+
+  if (!match) {
+    return null
+  }
+
+  return loadMatchedRoute(match, sanitizedRequest, importRoute, context)
+}

package/src/srvx.ts

@@ -0,0 +1,314 @@
+import { readFile } from "node:fs/promises"
+import { fileURLToPath } from "node:url"
+import { resolve } from "node:path"
+import { staticMiddleware } from "srvx/static"
+import type { ServerMiddleware, ServerOptions } from "srvx"
+import {
+  joinBasename,
+  stripBasename,
+  type AppDefinition,
+  type RouteDefinition,
+} from "./index.ts"
+import type { OctaneDocuments } from "./octane.ts"
+import type { DocumentMode, RenderedDocument } from "./server.ts"
+import {
+  isStaticFragmentRequest,
+  stripFlamefrontProtocolRequest,
+} from "./fragment-protocol.ts"
+import { staticRouteFragmentDataFile } from "./static-fragment-artifacts.ts"
+import type { StaticFragmentArtifact } from "./fragment-client.ts"
+
+export type SrvxMiddleware = ServerMiddleware
+
+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>
+
+/** Client asset location and the optional replacement for template lookup. */
+export interface ServerAssets<Route extends RouteDefinition = RouteDefinition> {
+  readonly clientDirectory: string | URL
+  readonly loadTemplate?: TemplateLoader<Route>
+}
+
+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>
+
+/** Lifecycle operations exposed alongside the srvx server options. */
+export interface ServerEntryLifecycle {
+  readonly renderDocument: OctaneDocuments["renderDocument"]
+  readonly loadRouteData: OctaneDocuments["loadRouteData"]
+  readonly renderFragment?: OctaneDocuments["renderFragment"]
+}
+
+/** The single default-export value consumed by Flamefront's lifecycle. */
+export type FlamefrontServerEntry = ServerOptions & ServerEntryLifecycle
+
+/** Inputs for composing the transport around an Octane document service. */
+export interface SrvxServerEntryOptions<
+  Route extends RouteDefinition = RouteDefinition,
+> {
+  readonly app: AppDefinition<Route>
+  readonly documents: Pick<
+    OctaneDocuments,
+    "renderDocument" | "loadRouteData"
+  > &
+    Partial<Pick<OctaneDocuments, "renderFragment">>
+  readonly assets: ServerAssets<Route>
+  /** Applied outermost first, in declaration order, around framework transport. */
+  readonly middleware?: readonly SrvxMiddleware[]
+  readonly headers?: ResponseHeadersHook<Route>
+}
+
+function asPath(directory: string | URL): string {
+  return directory instanceof URL ? fileURLToPath(directory) : directory
+}
+
+async function loadDefaultTemplate(clientDirectory: string): Promise<string> {
+  let lastError: unknown
+  const candidates = [
+    resolve(clientDirectory, "..", "server", "index.html"),
+    resolve(clientDirectory, "index.html"),
+    resolve(clientDirectory, "..", "index.html"),
+  ]
+
+  for (const filename of candidates) {
+    try {
+      return await readFile(filename, "utf8")
+    } catch (error) {
+      lastError = error
+    }
+  }
+
+  throw lastError
+}
+
+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 staticRequest(request: Request, basename: string): Request {
+  if (
+    basename === "/" ||
+    (request.method !== "GET" && request.method !== "HEAD")
+  ) {
+    return request
+  }
+
+  const url = new URL(request.url)
+  const pathname = stripBasename(url.pathname, basename)
+
+  if (!pathname || pathname === url.pathname) {
+    return request
+  }
+
+  url.pathname = pathname
+  return new Request(url, request)
+}
+
+/**
+ * Compose the srvx transport and the mode-aware document/data lifecycle into
+ * the one default server entry consumed by Flamefront's lifecycle.
+ */
+export function createSrvxServerEntry<
+  Route extends RouteDefinition = RouteDefinition,
+>(options: SrvxServerEntryOptions<Route>): FlamefrontServerEntry {
+  const clientDirectory = asPath(options.assets.clientDirectory)
+  const loadTemplate =
+    options.assets.loadTemplate ?? (() => loadDefaultTemplate(clientDirectory))
+  const serveClientFile = staticMiddleware({ dir: clientDirectory })
+  const defaultClientRoute = options.app.routes.find(
+    (route) => route.render === "client",
+  )
+
+  const frameworkMiddleware: SrvxMiddleware = (request, next) => {
+    const url = new URL(request.url)
+
+    if (isStaticFragmentRequest(url)) {
+      return next()
+    }
+
+    if (url.pathname === options.app.routing.dataPath) {
+      return next()
+    }
+
+    const match = options.app.match(url)
+
+    if (url.pathname === options.app.routing.basename && !match) {
+      return next()
+    }
+
+    if (match?.data.render === "client" || match?.data.render === "server") {
+      return next()
+    }
+
+    return serveClientFile(
+      staticRequest(request, options.app.routing.basename),
+      next,
+    )
+  }
+
+  const fetch = 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 (isStaticFragmentRequest(url)) {
+        const sanitizedRequest = stripFlamefrontProtocolRequest(request)
+        const fragmentMatch = options.app.match(sanitizedRequest.url)
+
+        if (!fragmentMatch || fragmentMatch.data.render !== "static") {
+          return new Response("Not found", { status: 404 })
+        }
+
+        let artifact: StaticFragmentArtifact | undefined
+
+        try {
+          artifact = JSON.parse(
+            await readFile(
+              staticRouteFragmentDataFile(clientDirectory, fragmentMatch.data),
+              "utf8",
+            ),
+          ) as StaticFragmentArtifact
+        } catch (error) {
+          if ((error as { code?: string }).code !== "ENOENT") {
+            throw error
+          }
+
+          if (!options.documents.renderFragment) {
+            return new Response("Not found", { status: 404 })
+          }
+
+          artifact = await options.documents.renderFragment(sanitizedRequest)
+        }
+
+        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: "static",
+              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 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
+    }
+  }
+
+  return {
+    fetch,
+    middleware: [...(options.middleware ?? []), frameworkMiddleware],
+    renderDocument: options.documents.renderDocument,
+    loadRouteData: options.documents.loadRouteData,
+    renderFragment: options.documents.renderFragment,
+  }
+}

package/src/static-fragment-artifacts.ts

@@ -0,0 +1,86 @@
+import { relative, resolve, sep } from "node:path"
+import type { RouteDefinition } from "./index.ts"
+
+function isWithin(directory: string, filePath: string): boolean {
+  const pathFromDirectory = relative(directory, filePath)
+
+  return (
+    pathFromDirectory === "" ||
+    (pathFromDirectory !== ".." &&
+      !pathFromDirectory.startsWith(`..${sep}`) &&
+      !pathFromDirectory.startsWith(sep))
+  )
+}
+
+function staticRoutePath(
+  clientDirectory: string,
+  route: RouteDefinition,
+): string {
+  if (/[:*]/.test(route.path)) {
+    throw new Error(
+      `Cannot prerender parameterized static route ${JSON.stringify(route.path)} without concrete paths.`,
+    )
+  }
+
+  const segments = route.path
+    .split("/")
+    .filter(Boolean)
+    .map((segment) => decodeURIComponent(segment))
+
+  if (
+    segments.some(
+      (segment) => segment === "." || segment === ".." || segment.includes("/"),
+    )
+  ) {
+    throw new Error(
+      `Cannot write unsafe static route path ${JSON.stringify(route.path)}.`,
+    )
+  }
+
+  const filePath = resolve(clientDirectory, ...segments, "index.html")
+
+  if (!isWithin(clientDirectory, filePath)) {
+    throw new Error(
+      `Cannot write static route outside the client build: ${JSON.stringify(route.path)}.`,
+    )
+  }
+
+  return filePath
+}
+
+export function staticRouteFile(
+  clientDirectory: string,
+  route: RouteDefinition,
+): string {
+  return staticRoutePath(clientDirectory, route)
+}
+
+export function staticRouteDataFile(
+  clientDirectory: string,
+  route: RouteDefinition,
+): string {
+  return staticRoutePath(clientDirectory, route).replace(
+    /\.html$/,
+    ".data.json",
+  )
+}
+
+export function staticRouteFragmentFile(
+  clientDirectory: string,
+  route: RouteDefinition,
+): string {
+  return staticRoutePath(clientDirectory, route).replace(
+    /\.html$/,
+    ".fragment.html",
+  )
+}
+
+export function staticRouteFragmentDataFile(
+  clientDirectory: string,
+  route: RouteDefinition,
+): string {
+  return staticRoutePath(clientDirectory, route).replace(
+    /\.html$/,
+    ".fragment.json",
+  )
+}

package/src/virtual-remix-routes.d.ts

@@ -0,0 +1,20 @@
+declare module "virtual:flamefront/remix-routes" {
+  import type { RouteObject } from "@octanejs/remix-router"
+  import type { RouterDocument as RouterDocumentComponent } from "./octane.ts"
+  import type {
+    GeneratedRouteMetadata,
+    NormalizedRoutingOptions,
+  } from "./index.ts"
+
+  export const RouterDocument: RouterDocumentComponent
+  export const routes: RouteObject[]
+  export const routing: NormalizedRoutingOptions
+  export const routeMetadata: readonly GeneratedRouteMetadata[]
+  export function preloadRoute(entry: string): Promise<void>
+}
+
+declare module "virtual:flamefront/server-routes" {
+  import type { RouteModule } from "./server.ts"
+
+  export function importRoute(entry: string): Promise<RouteModule>
+}