elm-ssr 0.1.0

package/src/http.ts

@@ -0,0 +1,86 @@
+export interface RenderFlagsContext {
+  request: Request;
+  url: URL;
+  path: string;
+  formData?: Record<string, string>;
+}
+
+export interface WorkerExecutionContext {
+  waitUntil(promise: Promise<unknown>): void;
+}
+
+export interface WorkerHandler {
+  fetch(request: Request, env?: unknown, executionCtx?: WorkerExecutionContext): Promise<Response>;
+}
+
+export interface AppContext {
+  request: Request;
+  url: URL;
+  requestId: string;
+  startedAt: number;
+  executionCtx?: WorkerExecutionContext;
+  env?: Record<string, unknown>;
+}
+
+export interface RouteDefinition {
+  path: string;
+  methods: string[];
+  description: string;
+}
+
+export interface RouteCatalog {
+  pages: RouteDefinition[];
+  assets: RouteDefinition[];
+  utility: RouteDefinition[];
+  api: RouteDefinition[];
+}
+
+export interface RenderResult {
+  html: string;
+  status: number;
+}
+
+export type RenderFlagsFactory = (context: RenderFlagsContext) => Record<string, unknown>;
+
+export type AppHandler = (context: AppContext) => Promise<Response>;
+
+export type Middleware = (context: AppContext, next: AppHandler) => Promise<Response>;
+
+export const withHeaders = (response: Response, headers: HeadersInit): Response => {
+  const merged = new Headers(response.headers);
+  new Headers(headers).forEach((value, key) => {
+    merged.set(key, value);
+  });
+
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers: merged
+  });
+};
+
+export const json = (body: unknown, init: ResponseInit = {}): Response => {
+  const headers = new Headers(init.headers);
+
+  if (!headers.has("content-type")) {
+    headers.set("content-type", "application/json; charset=utf-8");
+  }
+
+  return new Response(JSON.stringify(body, null, 2), {
+    ...init,
+    headers
+  });
+};
+
+export const text = (body: string, init: ResponseInit = {}): Response => {
+  const headers = new Headers(init.headers);
+
+  if (!headers.has("content-type")) {
+    headers.set("content-type", "text/plain; charset=utf-8");
+  }
+
+  return new Response(body, {
+    ...init,
+    headers
+  });
+};

package/src/middleware.ts

@@ -0,0 +1,104 @@
+import type { AppContext, AppHandler, Middleware } from "./http";
+import { json, text, withHeaders } from "./http";
+
+const runDetached = (context: AppContext, task: Promise<unknown>): void => {
+  if (context.executionCtx) {
+    context.executionCtx.waitUntil(task);
+    return;
+  }
+
+  void task.catch((error) => {
+    console.error("detached_middleware_task_failed", error);
+  });
+};
+
+export const composeMiddleware = (handler: AppHandler, middlewares: Middleware[]): AppHandler =>
+  middlewares.reduceRight<AppHandler>(
+    (next, middleware) => (context) => middleware(context, next),
+    handler
+  );
+
+export const requestIdMiddleware: Middleware = async (context, next) => {
+  const existing = context.request.headers.get("x-request-id");
+  context.requestId = existing && existing.length > 0 ? existing : crypto.randomUUID();
+
+  const response = await next(context);
+
+  return withHeaders(response, {
+    "x-request-id": context.requestId
+  });
+};
+
+export const timingMiddleware: Middleware = async (context, next) => {
+  const response = await next(context);
+  const durationMs = performance.now() - context.startedAt;
+
+  return withHeaders(response, {
+    "server-timing": `app;dur=${durationMs.toFixed(2)}`,
+    "x-response-time": `${durationMs.toFixed(2)}ms`
+  });
+};
+
+export const headMiddleware: Middleware = async (context, next) => {
+  const response = await next(context);
+
+  if (context.request.method !== "HEAD") {
+    return response;
+  }
+
+  return new Response(null, {
+    status: response.status,
+    statusText: response.statusText,
+    headers: response.headers
+  });
+};
+
+export const errorMiddleware: Middleware = async (context, next) => {
+  try {
+    return await next(context);
+  } catch (error) {
+    console.error("elm_ssr_request_failed", {
+      requestId: context.requestId,
+      path: context.url.pathname,
+      error
+    });
+
+    if (context.url.pathname.startsWith("/api/")) {
+      return json(
+        {
+          error: "internal_error",
+          requestId: context.requestId
+        },
+        { status: 500 }
+      );
+    }
+
+    return text("Internal Server Error", {
+      status: 500
+    });
+  }
+};
+
+export const loggingMiddleware = (logger: (entry: string) => void = console.log): Middleware =>
+  async (context, next) => {
+    const response = await next(context);
+    const durationMs = performance.now() - context.startedAt;
+
+    runDetached(
+      context,
+      Promise.resolve().then(() => {
+        logger(
+          JSON.stringify({
+            event: "request_completed",
+            requestId: context.requestId,
+            method: context.request.method,
+            path: context.url.pathname,
+            status: response.status,
+            durationMs: Number(durationMs.toFixed(2))
+          })
+        );
+      })
+    );
+
+    return response;
+  };

package/src/migrations.ts

@@ -0,0 +1,225 @@
+import { readdir, readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+
+/**
+ * SQL-file migration runner. Backend-neutral over a minimal `MigrationsAdapter`:
+ * wire it to bun:sqlite, Postgres (Bun.sql / node-postgres), Cloudflare D1, etc.
+ *
+ * Migrations live in `<dir>/*.sql`, ordered alphabetically (use a numeric
+ * prefix: `0001_init.sql`, `0002_add_users.sql`). Applied migrations are tracked
+ * in `__elm_ssr_migrations(name PRIMARY KEY, applied_at)`; re-runs are
+ * idempotent. Each migration runs inside a single `BEGIN…COMMIT` transaction
+ * together with its tracking insert, so a failing migration rolls back without
+ * leaving the schema partially applied (assuming a transactional backend).
+ */
+export interface MigrationsAdapter {
+  /** Execute possibly-multi-statement SQL (no params). */
+  exec(sql: string): Promise<void>;
+  /** Run a query and return the result rows as plain objects. */
+  list(sql: string): Promise<Array<Record<string, unknown>>>;
+  /** Optional: Run a set of operations in a transaction. */
+  runInTransaction?(fn: () => Promise<void>): Promise<void>;
+}
+
+export interface RunMigrationsOptions {
+  /** Directory containing `*.sql` migration files. */
+  dir: string;
+  /** Override the tracking table name (default `"__elm_ssr_migrations"`). */
+  tableName?: string;
+  /** Override the timestamp generator (useful for deterministic tests). */
+  now?: () => string;
+}
+
+export interface MigrationResult {
+  /** Migration filenames applied during this run, in order. */
+  applied: string[];
+  /** Migration filenames that were already applied. */
+  skipped: string[];
+}
+
+const escapeLiteral = (value: string): string => `'${value.replace(/'/g, "''")}'`;
+
+const validateTableName = (name: string): void => {
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
+    throw new Error(`Invalid migrations table name: ${name}`);
+  }
+};
+
+const isUpMigration = (name: string): boolean =>
+  name.endsWith(".sql") && !name.endsWith(".down.sql");
+
+const ensureTable = async (adapter: MigrationsAdapter, table: string): Promise<void> => {
+  await adapter.exec(
+    `CREATE TABLE IF NOT EXISTS ${table} (name TEXT PRIMARY KEY, applied_at TEXT NOT NULL)`
+  );
+};
+
+const runTransaction = async (adapter: MigrationsAdapter, work: () => Promise<void>): Promise<void> => {
+  if (adapter.runInTransaction) {
+    await adapter.runInTransaction(work);
+    return;
+  }
+
+  await adapter.exec("BEGIN");
+  try {
+    await work();
+    await adapter.exec("COMMIT");
+  } catch (error) {
+    try {
+      await adapter.exec("ROLLBACK");
+    } catch {
+      // ignore — backend may have already rolled back
+    }
+    throw error;
+  }
+};
+
+export const runMigrations = async (
+  adapter: MigrationsAdapter,
+  options: RunMigrationsOptions
+): Promise<MigrationResult> => {
+  const table = options.tableName ?? "__elm_ssr_migrations";
+  validateTableName(table);
+
+  const now = options.now ?? (() => new Date().toISOString());
+
+  await ensureTable(adapter, table);
+
+  const rows = await adapter.list(`SELECT name FROM ${table}`);
+  const alreadyApplied = new Set(rows.map((row) => String(row.name)));
+
+  const allFiles = (await readdir(options.dir)).filter(isUpMigration).sort();
+
+  const applied: string[] = [];
+  const skipped: string[] = [];
+
+  for (const file of allFiles) {
+    if (alreadyApplied.has(file)) {
+      skipped.push(file);
+      continue;
+    }
+
+    const raw = await readFile(resolve(options.dir, file), "utf8");
+    // Strip trailing whitespace + trailing semicolons so we can compose without `;;`.
+    const trimmed = raw.replace(/[\s;]+$/, "");
+    const insertSql = `INSERT INTO ${table} (name, applied_at) VALUES (${escapeLiteral(file)}, ${escapeLiteral(now())})`;
+
+    try {
+      await runTransaction(adapter, async () => {
+        if (trimmed.length > 0) {
+          await adapter.exec(trimmed);
+        }
+        await adapter.exec(insertSql);
+      });
+      applied.push(file);
+    } catch (error) {
+      throw new Error(`Migration "${file}" failed: ${String(error)}`);
+    }
+  }
+
+  return { applied, skipped };
+};
+
+// === Down migrations ===
+
+export interface RevertMigrationsOptions {
+  /** Directory containing the matching `<name>.down.sql` files. */
+  dir: string;
+  /** Override the tracking table name (default `"__elm_ssr_migrations"`). */
+  tableName?: string;
+  /** How many of the most-recently-applied migrations to revert. Default `1`. */
+  count?: number;
+}
+
+export interface RevertResult {
+  /** Migration filenames reverted in this run, most-recent-first. */
+  reverted: string[];
+}
+
+/**
+ * Revert the most-recently-applied migrations. For each one, runs the paired
+ * `<name>.down.sql` from `dir` and removes the tracking row, transactionally.
+ * Errors if a paired down file is missing — migrations are forward-only by
+ * default; opt in to reverts by shipping `*.down.sql` alongside `*.sql`.
+ */
+export const revertMigrations = async (
+  adapter: MigrationsAdapter,
+  options: RevertMigrationsOptions
+): Promise<RevertResult> => {
+  const table = options.tableName ?? "__elm_ssr_migrations";
+  validateTableName(table);
+
+  await ensureTable(adapter, table);
+
+  const rows = await adapter.list(`SELECT name FROM ${table} ORDER BY name DESC`);
+  const applied = rows.map((row) => String(row.name));
+  const count = Math.max(0, options.count ?? 1);
+  const toRevert = applied.slice(0, count);
+  const reverted: string[] = [];
+
+  for (const file of toRevert) {
+    const downName = file.replace(/\.sql$/, ".down.sql");
+    let downSql: string;
+    try {
+      downSql = await readFile(resolve(options.dir, downName), "utf8");
+    } catch {
+      throw new Error(`No down migration for "${file}" (expected ${downName})`);
+    }
+
+    const trimmed = downSql.replace(/[\s;]+$/, "");
+    const deleteSql = `DELETE FROM ${table} WHERE name = ${escapeLiteral(file)}`;
+
+    try {
+      await runTransaction(adapter, async () => {
+        if (trimmed.length > 0) {
+          await adapter.exec(trimmed);
+        }
+        await adapter.exec(deleteSql);
+      });
+      reverted.push(file);
+    } catch (error) {
+      throw new Error(`Reverting "${file}" failed: ${String(error)}`);
+    }
+  }
+
+  return { reverted };
+};
+
+// === Status ===
+
+export interface ListMigrationsOptions {
+  /** Directory containing `*.sql` migration files. */
+  dir: string;
+  /** Override the tracking table name (default `"__elm_ssr_migrations"`). */
+  tableName?: string;
+}
+
+export interface MigrationsStatus {
+  /** Already-applied migrations, oldest first. */
+  applied: Array<{ name: string; appliedAt: string }>;
+  /** On-disk migrations that haven't been applied yet. */
+  pending: string[];
+}
+
+/**
+ * Inspect the migration state: what's applied (with timestamps) and what
+ * remains. Creates the tracking table on first use.
+ */
+export const listMigrations = async (
+  adapter: MigrationsAdapter,
+  options: ListMigrationsOptions
+): Promise<MigrationsStatus> => {
+  const table = options.tableName ?? "__elm_ssr_migrations";
+  validateTableName(table);
+
+  await ensureTable(adapter, table);
+
+  const rows = await adapter.list(`SELECT name, applied_at FROM ${table} ORDER BY name`);
+  const applied = rows.map((row) => ({ name: String(row.name), appliedAt: String(row.applied_at) }));
+  const appliedSet = new Set(applied.map((entry) => entry.name));
+
+  const allFiles = (await readdir(options.dir)).filter(isUpMigration).sort();
+  const pending = allFiles.filter((file) => !appliedSet.has(file));
+
+  return { applied, pending };
+};

package/src/protocol.ts

@@ -0,0 +1,119 @@
+export interface SsrPropertyAttribute {
+  kind: "attribute";
+  name: string;
+  value: string;
+}
+
+export interface SsrEventAttribute {
+  kind: "event";
+  name: string;
+  payload: unknown;
+  capture: "none" | "value";
+}
+
+export type SsrAttribute = SsrPropertyAttribute | SsrEventAttribute;
+
+export interface SsrElementNode {
+  kind: "element";
+  tag: string;
+  attrs: SsrAttribute[];
+  children: SsrNode[];
+}
+
+export interface SsrVoidNode {
+  kind: "void";
+  tag: string;
+  attrs: SsrAttribute[];
+}
+
+export interface SsrTextNode {
+  kind: "text";
+  text: string;
+}
+
+export type SsrNode = SsrElementNode | SsrVoidNode | SsrTextNode;
+
+export interface SsrDocument {
+  status: number;
+  lang: string;
+  hasIslands: boolean;
+  head: SsrNode[];
+  body: SsrNode[];
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null;
+
+const isAttribute = (value: unknown): value is SsrAttribute => {
+  if (!isRecord(value) || typeof value.kind !== "string" || typeof value.name !== "string") {
+    return false;
+  }
+
+  if (value.kind === "attribute") {
+    return typeof value.value === "string";
+  }
+
+  if (value.kind === "event") {
+    return "payload" in value && (value.capture === "none" || value.capture === "value");
+  }
+
+  return false;
+};
+
+const isNode = (value: unknown): value is SsrNode => {
+  if (!isRecord(value) || typeof value.kind !== "string") {
+    return false;
+  }
+
+  if (value.kind === "text") {
+    return typeof value.text === "string";
+  }
+
+  if ((value.kind === "element" || value.kind === "void") && typeof value.tag === "string" && Array.isArray(value.attrs)) {
+    if (!value.attrs.every(isAttribute)) {
+      return false;
+    }
+
+    if (value.kind === "element") {
+      return Array.isArray(value.children) && value.children.every(isNode);
+    }
+
+    return true;
+  }
+
+  return false;
+};
+
+export const assertDocument = (value: unknown): SsrDocument => {
+  if (
+    !isRecord(value)
+    || typeof value.status !== "number"
+    || typeof value.lang !== "string"
+    || typeof value.hasIslands !== "boolean"
+    || !Array.isArray(value.head)
+    || !Array.isArray(value.body)
+    || !value.head.every(isNode)
+    || !value.body.every(isNode)
+  ) {
+    throw new Error("Elm SSR returned an invalid document payload.");
+  }
+
+  return value as unknown as SsrDocument;
+};
+
+export const toDomAttribute = (attribute: SsrAttribute): { name: string; value: string } => {
+  if (attribute.kind === "attribute") {
+    return {
+      name: attribute.name,
+      value: attribute.value
+    };
+  }
+
+  return {
+    name: `data-elmssr-event-${attribute.name}`,
+    value: encodeURIComponent(JSON.stringify({
+      ...((isRecord(attribute.payload) ? attribute.payload : {}) as Record<string, unknown>),
+      capture: attribute.capture
+    }))
+  };
+};

package/src/render.ts

@@ -0,0 +1,111 @@
+import { defaultEffectRunner, normalizeEffect, type EffectContext, type EffectRunner } from "./effects";
+import { assertDocument, type SsrDocument } from "./protocol";
+
+export interface ElmPorts {
+  rendered: {
+    subscribe(callback: (value: unknown) => void): void;
+  };
+  start: {
+    send(value: boolean): void;
+  };
+  effectRequest: {
+    subscribe(callback: (value: unknown) => void): void;
+  };
+  effectResult: {
+    send(value: unknown): void;
+  };
+}
+
+export interface ElmRuntimeInstance {
+  ports: ElmPorts;
+}
+
+export interface CompiledElmModule {
+  Main: {
+    init(options: { flags: Record<string, unknown> }): ElmRuntimeInstance;
+  };
+}
+
+export interface RenderedDocument {
+  document: SsrDocument;
+  status: number;
+  redirect?: string;
+  json?: unknown;
+}
+
+export interface RenderOptions {
+  effects?: EffectRunner;
+  effectContext?: EffectContext;
+  timeoutMs?: number;
+}
+
+interface ActionStep {
+  kind: "resolved" | "errored" | "redirect" | "json";
+  status?: number;
+  message?: string;
+  url?: string;
+  value?: unknown;
+}
+
+export const renderApp = async (
+  elmModule: CompiledElmModule,
+  flags: Record<string, unknown>,
+  options: RenderOptions = {}
+): Promise<RenderedDocument> => {
+  const runEffect = options.effects ?? defaultEffectRunner;
+  const effectContext = options.effectContext ?? {};
+  const timeoutMs = options.timeoutMs ?? 5000;
+
+  const payload = await new Promise<unknown>((resolve, reject) => {
+    const app = elmModule.Main.init({ flags });
+    const timeout = setTimeout(() => reject(new Error("Elm SSR render timed out.")), timeoutMs);
+
+    app.ports.rendered.subscribe((value: unknown) => {
+      clearTimeout(timeout);
+      resolve(value);
+    });
+
+    app.ports.effectRequest.subscribe((request: unknown) => {
+      void Promise.resolve()
+        .then(() => runEffect(normalizeEffect(request), effectContext))
+        .then((result) => app.ports.effectResult.send(result))
+        .catch((error: unknown) => app.ports.effectResult.send({ ok: false, error: String(error) }));
+    });
+
+    app.ports.start.send(true);
+  });
+
+  const step = payload as ActionStep;
+
+  if (step.kind === "redirect") {
+    return {
+      status: 302,
+      redirect: step.url,
+      document: { status: 302, lang: "en", hasIslands: false, head: [], body: [] }
+    };
+  }
+
+  if (step.kind === "json") {
+    return {
+      status: 200,
+      json: step.value,
+      document: { status: 200, lang: "en", hasIslands: false, head: [], body: [] }
+    };
+  }
+
+  if (step.kind === "errored") {
+    const status = step.status ?? 500;
+    const document = step.value ? assertDocument(step.value) : { status, lang: "en", hasIslands: false, head: [], body: [] };
+    return {
+      status,
+      document
+    };
+  }
+
+  const document = assertDocument(step.value);
+
+  return {
+    document,
+    status: document.status
+  };
+};