flamefront 0.0.0 → 0.1.0

package/src/route-prefetch.ts

@@ -0,0 +1,79 @@
+import type {
+  LoadRouteOptions,
+  MatchRouteOptions,
+  RouteDefinition,
+  RouteMatchForUrl,
+} from "./index.ts"
+
+/**
+ * Resources that a route-aware prefetcher can warm without taking over
+ * navigation. The framework adapter supplies the route fragment transport;
+ * callers can replace it when they own the transport.
+ */
+export interface RoutePrefetchResources<
+  Route extends RouteDefinition = RouteDefinition,
+> {
+  readonly routeFragment?: (
+    url: string | URL,
+    route: Route,
+    options?: LoadRouteOptions,
+  ) => void | Promise<void>
+}
+
+export type RouteModulePreloader = (entry: string) => void | Promise<void>
+
+export type RoutePrefetchCallback = (to: string) => void | Promise<void>
+
+type RoutePrefetchApp<Route extends RouteDefinition> = {
+  readonly match: (
+    url: string | URL,
+    options?: MatchRouteOptions,
+  ) => RouteMatchForUrl<Route, string> | null
+  readonly prefetch: (
+    url: string | URL,
+    options?: LoadRouteOptions,
+  ) => Promise<void>
+}
+
+/**
+ * Warm the resources used by a matched route. Client routes share route data
+ * and module caches. Server and static routes use the fragment resource and
+ * never import their route module as a browser rendering path.
+ */
+export async function prefetchRouteResources<
+  Route extends RouteDefinition = RouteDefinition,
+>(
+  app: RoutePrefetchApp<Route>,
+  preloadRoute: RouteModulePreloader,
+  url: string | URL,
+  options: LoadRouteOptions = {},
+  resources: RoutePrefetchResources<Route> = {},
+): Promise<void> {
+  const match = app.match(url)
+
+  if (!match) {
+    return
+  }
+
+  if (match.data.render !== "client") {
+    await resources.routeFragment?.(url, match.data, options)
+    return
+  }
+
+  await Promise.all([
+    app.prefetch(url, options),
+    preloadRoute(match.data.entry),
+  ])
+}
+
+/** Create the callback accepted by the generic browser router. */
+export function createRoutePrefetchCallback<
+  Route extends RouteDefinition = RouteDefinition,
+>(
+  app: RoutePrefetchApp<Route>,
+  preloadRoute: RouteModulePreloader,
+  resources: RoutePrefetchResources<Route> = {},
+): RoutePrefetchCallback {
+  return (to) =>
+    prefetchRouteResources(app, preloadRoute, to, undefined, resources)
+}

package/src/server.ts

@@ -0,0 +1,338 @@
+import {
+  type AppDefinition,
+  type MatchRouteOptions,
+  type RouteLoaderFor,
+  type RenderMode,
+  type RouteLoaderData,
+  type RouteMatchForUrl,
+  type RouteParams,
+  type RouteDefinition,
+} from "./index.ts"
+import { stripFlamefrontProtocolRequest } from "./fragment-protocol.ts"
+
+type LoaderPath<ContextOrPath, PathOrContext> =
+  ContextOrPath extends `/${string}`
+    ? ContextOrPath
+    : PathOrContext extends `/${string}`
+      ? PathOrContext
+      : string
+
+type LoaderContext<ContextOrPath, PathOrContext> =
+  ContextOrPath extends `/${string}`
+    ? PathOrContext extends `/${string}`
+      ? unknown
+      : PathOrContext
+    : ContextOrPath
+
+export interface LoaderArgs<ContextOrPath = unknown, PathOrContext = unknown> {
+  readonly request: Request
+  readonly params: Readonly<
+    RouteParams<LoaderPath<ContextOrPath, PathOrContext>>
+  >
+  readonly context: LoaderContext<ContextOrPath, PathOrContext>
+}
+
+export type Loader<
+  Data = unknown,
+  Context = unknown,
+  Path extends string = string,
+> = (args: LoaderArgs<Context, Path>) => Data | Promise<Data>
+
+export interface RouteModule<
+  Data = unknown,
+  Context = unknown,
+  Path extends string = string,
+> {
+  readonly default: unknown
+  readonly loader?: Loader<Data, Context, Path>
+}
+
+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<RouteParams<Route["path"]>>
+  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,
+  Path extends string = string,
+> = (entry: string) => Promise<RouteModule<Data, Context, Path>>
+
+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
+}
+
+/** A loaded route whose data follows the generated route-module map. */
+export type LoadedRouteFor<
+  Route extends RouteDefinition,
+  Context = unknown,
+> = Route extends RouteDefinition
+  ? RouteLoaderFor<Route["path"]> extends (
+      ...args: infer _Args
+    ) => infer _Result
+    ? Omit<
+        LoadedRoute<RouteLoaderData<Route["path"]>, Context, Route>,
+        "loaderData"
+      > & {
+        readonly loaderData: RouteLoaderData<Route["path"]>
+      }
+    : LoadedRoute<unknown, Context, Route>
+  : never
+
+/** Route-module shape selected from one authored route definition. */
+export type RouteModuleForRoute<
+  Route extends RouteDefinition,
+  Context = unknown,
+> = Route extends RouteDefinition
+  ? RouteLoaderFor<Route["path"]> extends (
+      ...args: infer _Args
+    ) => infer _Result
+    ? RouteModule<RouteLoaderData<Route["path"]>, Context, Route["path"]>
+    : RouteModule<unknown, Context, Route["path"]>
+  : never
+
+/** Importer shape for applications that own a typed route-module boundary. */
+export type RouteImporterFor<
+  Route extends RouteDefinition,
+  Context = unknown,
+> = (entry: Route["entry"]) => Promise<RouteModuleForRoute<Route, Context>>
+
+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,
+  ) => RouteMatchForUrl<Route, string> | null
+  readonly createRequestContext: (
+    request: Request,
+    options: RouteRuntimeContextOptions,
+  ) => Promise<Context | undefined>
+  readonly loadRoute: (
+    request: Request,
+    options?: RouteLoadOptions<Context>,
+  ) => Promise<LoadedRouteFor<Route, Context> | 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: RouteMatchForUrl<Route, string>,
+  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 as LoaderArgs<Context, string>["params"],
+        context: context as LoaderContext<Context, string>,
+      })
+    : undefined
+
+  return {
+    route: match.data,
+    module: routeModule,
+    loaderData,
+  }
+}
+
+export function createRouteRuntime<
+  Context = unknown,
+  Route extends RouteDefinition = RouteDefinition,
+>(
+  options: Omit<RouteRuntimeOptions<Context, Route>, "importRoute"> & {
+    readonly importRoute: RouteImporterFor<Route, Context>
+  },
+): RouteRuntime<Context, Route>
+
+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 ?? {}) as Readonly<RouteParams<Route["path"]>>,
+      purpose: contextOptions.purpose,
+      ...(contextOptions.mode === undefined
+        ? {}
+        : { mode: contextOptions.mode }),
+    })
+  }
+
+  const loadRouteForRequest = async (
+    request: Request,
+    loadOptions: RouteLoadOptions<Context> = {},
+  ): Promise<LoadedRouteFor<Route, Context> | 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,
+    ) as Promise<LoadedRouteFor<Route, 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 function loadRoute<
+  _Data = unknown,
+  Context = unknown,
+  Route extends RouteDefinition = RouteDefinition,
+>(
+  app: AppDefinition<Route>,
+  request: Request,
+  importRoute: RouteImporterFor<Route, Context>,
+  context?: Context,
+): Promise<LoadedRouteFor<Route, Context> | null>
+
+export function loadRoute<
+  Data = unknown,
+  Context = unknown,
+  Route extends RouteDefinition = RouteDefinition,
+>(
+  app: AppDefinition<Route>,
+  request: Request,
+  importRoute: RouteImporter<Data, Context>,
+  context?: Context,
+): Promise<LoadedRoute<Data, Context, Route> | null>
+
+export async function loadRoute<
+  Data = unknown,
+  Context = unknown,
+  Route extends RouteDefinition = RouteDefinition,
+>(
+  app: AppDefinition<Route>,
+  request: Request,
+  importRoute: RouteImporter<Data, Context>,
+  context?: Context,
+): Promise<LoadedRouteFor<Route, Context> | null> {
+  const sanitizedRequest = stripFlamefrontProtocolRequest(request)
+  const match = app.match(sanitizedRequest.url)
+
+  if (!match) {
+    return null
+  }
+
+  return loadMatchedRoute(
+    match,
+    sanitizedRequest,
+    importRoute,
+    context,
+  ) as Promise<LoadedRouteFor<Route, Context>>
+}

package/src/srvx.ts

@@ -0,0 +1,174 @@
+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 {
+  stripBasename,
+  type AppDefinition,
+  type RouteDefinition,
+} from "./index.ts"
+import { isRouteFragmentRequest } from "./fragment-protocol.ts"
+import {
+  createFetchServerEntry,
+  type ResponseHeadersHook,
+  type ServerDocuments,
+  type ServerEntryLifecycle,
+  type TemplateLoader,
+} from "./fetch.ts"
+import { staticRouteFragmentDataFile } from "./static-fragment-artifacts.ts"
+
+export type {
+  FetchMiddleware,
+  FetchServerAssets,
+  FetchServerEntryOptions,
+  FlamefrontFetchServerEntry,
+  ResponseHeaders,
+  ResponseHeadersContext,
+  ResponseHeadersHook,
+  ServerDocuments,
+  StaticFragmentContext,
+  StaticFragmentLoader,
+  TemplateContext,
+  TemplateLoader,
+} from "./fetch.ts"
+
+export type SrvxMiddleware = ServerMiddleware
+
+/** 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 type { ServerEntryLifecycle }
+
+/** 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: ServerDocuments
+  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 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 frameworkMiddleware: SrvxMiddleware = (request, next) => {
+    const url = new URL(request.url)
+
+    if (isRouteFragmentRequest(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 fetchEntry = createFetchServerEntry({
+    app: options.app,
+    documents: options.documents,
+    assets: {
+      loadTemplate,
+      loadStaticFragment: async ({ route }) => {
+        try {
+          return JSON.parse(
+            await readFile(
+              staticRouteFragmentDataFile(clientDirectory, route),
+              "utf8",
+            ),
+          )
+        } catch (error) {
+          if ((error as { code?: string }).code !== "ENOENT") {
+            throw error
+          }
+
+          return undefined
+        }
+      },
+    },
+    headers: options.headers,
+  })
+
+  return {
+    fetch: fetchEntry.fetch,
+    middleware: [...(options.middleware ?? []), frameworkMiddleware],
+    renderDocument: fetchEntry.renderDocument,
+    loadRouteData: fetchEntry.loadRouteData,
+    renderFragment: fetchEntry.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",
+  )
+}