elm-ssr 0.1.0

package/src/request-handler.ts

@@ -0,0 +1,208 @@
+import type { IslandMetadata } from "./app";
+import { createIslandsRuntimeSource } from "./client-runtime/islands";
+import type { AppContext, AppHandler, RenderFlagsFactory, RouteCatalog } from "./http";
+import { json, text } from "./http";
+import { type EffectRunner } from "./effects";
+import { renderApp, type CompiledElmModule } from "./render";
+import { renderHtmlDocument } from "./serialize";
+import { assetHeaders, cssHeaders, htmlHeaders, jsonHeaders } from "./response-headers";
+
+const isReadMethod = (method: string): boolean => method === "GET" || method === "HEAD";
+
+const isSupportedMethod = (method: string): boolean => method === "GET" || method === "HEAD" || method === "POST";
+
+const methodNotAllowed = (context: AppContext): Response => {
+  if (context.url.pathname.startsWith("/api/")) {
+    return json(
+      {
+        error: "method_not_allowed",
+        allowed: ["GET", "HEAD", "POST"]
+      },
+      { status: 405, headers: jsonHeaders }
+    );
+  }
+
+  return text("Method Not Allowed", { status: 405 });
+};
+
+const parseFormData = async (request: Request): Promise<Record<string, string>> => {
+  if (request.method !== "POST") {
+    return {};
+  }
+
+  const contentType = request.headers.get("content-type") || "";
+
+  if (contentType.includes("application/x-www-form-urlencoded") || contentType.includes("multipart/form-data")) {
+    try {
+      const formData = await request.formData();
+      const data: Record<string, string> = {};
+      for (const [key, value] of formData.entries()) {
+        if (typeof value === "string") {
+          data[key] = value;
+        }
+      }
+      return data;
+    } catch {
+      return {};
+    }
+  }
+
+  if (contentType.includes("application/json")) {
+    try {
+      const data = await request.json();
+      return typeof data === "object" && data !== null ? (data as Record<string, string>) : {};
+    } catch {
+      return {};
+    }
+  }
+
+  return {};
+};
+
+const createFlagsFromContext = async (
+  context: AppContext,
+  path: string,
+  createFlags: RenderFlagsFactory
+): Promise<Record<string, unknown>> => {
+  const formData = await parseFormData(context.request);
+  return createFlags({
+    request: context.request,
+    url: context.url,
+    path,
+    formData
+  });
+};
+
+export interface RequestHandlerOptions {
+  elmModule: CompiledElmModule;
+  islands?: Record<string, IslandMetadata>;
+  islandsBundle?: string;
+  stylesheet: string;
+  routes: RouteCatalog;
+  createFlags: RenderFlagsFactory;
+  effects?: EffectRunner;
+}
+
+export const createRequestHandler = ({
+  elmModule,
+  islands,
+  islandsBundle,
+  stylesheet,
+  routes,
+  createFlags,
+  effects
+}: RequestHandlerOptions): AppHandler =>
+  async (context) => {
+    if (!isSupportedMethod(context.request.method)) {
+      return methodNotAllowed(context);
+    }
+
+    if (context.url.pathname === "/health") {
+      return text("ok", { status: 200 });
+    }
+
+    if (context.url.pathname === "/styles.css") {
+      return new Response(stylesheet, {
+        status: 200,
+        headers: cssHeaders
+      });
+    }
+
+    if (context.url.pathname === "/__elm-ssr/islands.js" && islands && Object.keys(islands).length > 0) {
+      return new Response(createIslandsRuntimeSource(islands), {
+        status: 200,
+        headers: assetHeaders
+      });
+    }
+
+    if (context.url.pathname === "/__elm-ssr/islands-bundle.js" && islandsBundle) {
+      return new Response(islandsBundle, {
+        status: 200,
+        headers: assetHeaders
+      });
+    }
+
+    if (context.url.pathname === "/api/health") {
+      return json(
+        {
+          ok: true,
+          service: "elmssr",
+          runtime: "cloudflare-worker",
+          requestId: context.requestId
+        },
+        { status: 200, headers: jsonHeaders }
+      );
+    }
+
+    if (context.url.pathname === "/api/routes") {
+      return json(routes, {
+        status: 200,
+        headers: jsonHeaders
+      });
+    }
+
+    if (context.url.pathname === "/api/render") {
+      const targetPath = context.url.searchParams.get("path");
+
+      if (!targetPath || !targetPath.startsWith("/")) {
+        return json(
+          {
+            error: "invalid_path",
+            message: "Use /api/render?path=/some-route"
+          },
+          { status: 400, headers: jsonHeaders }
+        );
+      }
+
+      const flags = await createFlagsFromContext(context, targetPath, createFlags);
+      const rendered = await renderApp(elmModule, flags, {
+        effects,
+        effectContext: {
+          env: context.env,
+          request: context.request,
+          waitUntil: context.executionCtx ? (promise) => context.executionCtx?.waitUntil(promise) : undefined
+        }
+      });
+
+      if (rendered.redirect) {
+        return json({ redirect: rendered.redirect }, { status: 200, headers: jsonHeaders });
+      }
+
+      if (rendered.json) {
+        return json(rendered.json, { status: 200, headers: jsonHeaders });
+      }
+
+      return json(
+        {
+          path: targetPath,
+          status: rendered.status,
+          html: renderHtmlDocument(rendered.document)
+        },
+        { status: 200, headers: jsonHeaders }
+      );
+    }
+
+    const flags = await createFlagsFromContext(context, context.url.pathname + context.url.search, createFlags);
+    const rendered = await renderApp(elmModule, flags, {
+      effects,
+      effectContext: { env: context.env, request: context.request }
+    });
+
+    if (rendered.redirect) {
+      return new Response(null, {
+        status: 302,
+        headers: { location: rendered.redirect }
+      });
+    }
+
+    if (rendered.json) {
+      return json(rendered.json, { status: 200, headers: jsonHeaders });
+    }
+
+    const html = renderHtmlDocument(rendered.document);
+
+    return new Response(html, {
+      status: rendered.status,
+      headers: htmlHeaders
+    });
+  };

package/src/response-headers.ts

@@ -0,0 +1,18 @@
+export const htmlHeaders = {
+  "content-type": "text/html; charset=utf-8",
+  "cache-control": "public, max-age=0, s-maxage=60"
+};
+
+export const cssHeaders = {
+  "content-type": "text/css; charset=utf-8",
+  "cache-control": "public, max-age=300"
+};
+
+export const assetHeaders = {
+  "content-type": "text/javascript; charset=utf-8",
+  "cache-control": "public, max-age=300"
+};
+
+export const jsonHeaders = {
+  "cache-control": "no-store"
+};

package/src/serialize.ts

@@ -0,0 +1,47 @@
+import type { SsrAttribute, SsrDocument, SsrNode } from "./protocol";
+import { toDomAttribute } from "./protocol";
+
+const escapeHtml = (value: string): string =>
+  value
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll("\"", "&quot;")
+    .replaceAll("'", "&#39;");
+
+const renderNodeAttributes = (attributes: SsrAttribute[]): string => {
+  if (attributes.length === 0) {
+    return "";
+  }
+
+  return attributes
+    .map((attribute) => {
+      const domAttribute = toDomAttribute(attribute);
+      return ` ${domAttribute.name}="${escapeHtml(domAttribute.value)}"`;
+    })
+    .join("");
+};
+
+const renderNode = (node: SsrNode): string => {
+  if (node.kind === "text") {
+    return escapeHtml(node.text);
+  }
+
+  const attrs = renderNodeAttributes(node.attrs);
+
+  if (node.kind === "void") {
+    return `<${node.tag}${attrs}>`;
+  }
+
+  return `<${node.tag}${attrs}>${node.children.map(renderNode).join("")}</${node.tag}>`;
+};
+
+export const renderNodes = (nodes: SsrNode[]): string =>
+  nodes.map(renderNode).join("");
+
+// A page ships no JS unless it embeds an island; islands pull their own bootstrap.
+const renderIslandShell = (document: SsrDocument): string =>
+  document.hasIslands ? `<script type="module" src="/__elm-ssr/islands.js"></script>` : "";
+
+export const renderHtmlDocument = (document: SsrDocument): string =>
+  `<!doctype html><html lang="${escapeHtml(document.lang)}"><head>${renderNodes(document.head)}</head><body><div id="elm-ssr-root">${renderNodes(document.body)}</div>${renderIslandShell(document)}</body></html>`;

package/src/tasks.ts

@@ -0,0 +1,139 @@
+import type { EffectContext, EffectRunner } from "./effects";
+import type { WorkerExecutionContext } from "./http";
+
+/**
+ * A background task handler. It receives the payload the Elm side enqueued and
+ * the request's effect context (env, request, …). Its result is ignored — tasks
+ * are fire-and-forget.
+ */
+export type TaskHandler = (payload: unknown, context: EffectContext) => unknown | Promise<unknown>;
+
+export type TaskHandlers = Record<string, TaskHandler>;
+
+/**
+ * Wrap an effect runner so `Loader.enqueue { task, payload }` schedules a named
+ * task to run AFTER the response. On Cloudflare this uses `ctx.waitUntil` to keep
+ * the isolate alive; locally (no waitUntil) it runs fire-and-forget. All other
+ * effects pass through to the wrapped runner unchanged.
+ */
+export const withTasks = (runner: EffectRunner, tasks: TaskHandlers): EffectRunner =>
+  async (effect, context) => {
+    if (effect.kind !== "enqueue") {
+      return runner(effect, context);
+    }
+
+    const name = String(effect.payload.task);
+    const handler = tasks[name];
+
+    if (!handler) {
+      return { ok: false, error: `No task handler registered for "${name}".` };
+    }
+
+    const job = Promise.resolve()
+      .then(() => handler(effect.payload.payload, context))
+      .catch((error) => {
+        console.error(`elm-ssr: background task "${name}" failed`, error);
+      });
+
+    if (typeof context.waitUntil === "function") {
+      context.waitUntil(job);
+    } else {
+      void job;
+    }
+
+    return { ok: true, value: null };
+  };
+
+// === Cloudflare Queues (durable background jobs) ===
+
+interface QueueLike {
+  send(message: unknown): Promise<void>;
+}
+
+export interface QueueProducerConfig {
+  /** env binding name of the Cloudflare Queue. Default `"QUEUE"`. */
+  queueBinding?: string;
+}
+
+/**
+ * Composable alternative to `withTasks` for durable jobs: an `enqueue` effect
+ * sends `{ task, payload }` to a Cloudflare Queue via `context.env[binding]`
+ * instead of running it inline via `waitUntil`. All other effects pass through.
+ *
+ *     effects: withQueueProducer(inMemoryEffects({...}), { queueBinding: "JOBS" })
+ *
+ * Consume the queue in your CF entry with `createQueueConsumer(tasks)`.
+ */
+export const withQueueProducer = (runner: EffectRunner, config: QueueProducerConfig = {}): EffectRunner => {
+  const binding = config.queueBinding ?? "QUEUE";
+
+  return async (effect, context) => {
+    if (effect.kind !== "enqueue") {
+      return runner(effect, context);
+    }
+
+    const env = (context.env ?? {}) as Record<string, unknown>;
+    const queue = env[binding] as QueueLike | undefined;
+
+    if (!queue) {
+      return { ok: false, error: `Missing queue binding "${binding}"` };
+    }
+
+    try {
+      await queue.send({ task: String(effect.payload.task), payload: effect.payload.payload });
+      return { ok: true, value: null };
+    } catch (error) {
+      return { ok: false, error: `Queue send failed: ${String(error)}` };
+    }
+  };
+};
+
+interface QueueMessage {
+  body: unknown;
+  ack(): void;
+  retry(): void;
+}
+
+export interface QueueBatch {
+  messages: QueueMessage[];
+  queue: string;
+}
+
+/**
+ * Build the `queue` handler for a Cloudflare consumer worker. Maps each message
+ * `{ task, payload }` (produced by `withQueueProducer` or `Loader.enqueue` on
+ * any producer) to the named handler in `tasks`. Acks on success, retries on
+ * failure or missing handler.
+ *
+ *     export default {
+ *       fetch: worker.fetch,
+ *       queue: createQueueConsumer({ sendEmail, warmCache })
+ *     }
+ */
+export const createQueueConsumer = (tasks: TaskHandlers) =>
+  async (batch: QueueBatch, env?: unknown, executionCtx?: WorkerExecutionContext): Promise<void> => {
+    const context: EffectContext = {
+      env: (env ?? undefined) as Record<string, unknown> | undefined,
+      waitUntil: executionCtx ? (promise) => executionCtx.waitUntil(promise) : undefined
+    };
+
+    for (const message of batch.messages) {
+      const body = (message.body ?? {}) as { task?: string; payload?: unknown };
+      const name = typeof body.task === "string" ? body.task : "";
+      const handler = tasks[name];
+
+      if (!handler) {
+        console.error(`elm-ssr: queue consumer has no handler for "${name}"`);
+        message.retry();
+        continue;
+      }
+
+      try {
+        await handler(body.payload, context);
+        message.ack();
+      } catch (error) {
+        console.error(`elm-ssr: queue task "${name}" failed`, error);
+        message.retry();
+      }
+    }
+  };