@jundle/cloudflare 0.0.0-stage → 0.0.1-0

package/src/index.js

@@ -0,0 +1,446 @@
+// @jundle/cloudflare — the Cloudflare Workers runtime for the
+// jundle dev server (SPEC §16.3). It IS the workerd runtime:
+// a dev entry names it as its `runtime` (SPEC §6.12, §16.2).
+// Miniflare + wrangler are dependencies of THIS package, not
+// jundle core (so apps that only use Node never install
+// workerd). Wrangler is pinned (see config.js) because its
+// config utilities are `unstable_`.
+// Runtime plugin shape (SPEC §16.2): { createRunner,
+// defaultOptions } (a single runtime, not a map). The dev
+// server calls createRunner for a dev entry whose runtime
+// is this package.
+// createRunner({ configDir, entryUrl, exportShape,
+//   options }) -> { config, wranglerFile, options,
+//   fetch(request), invalidate(invalidated, opts?),
+//   dispose(), start({ baseUrl })?, ...extras }
+// options is the entry's options object, opaque to core:
+// wranglerConfig (path, resolved against configDir),
+// remoteBindings (names of remote bindings from the
+// wrangler file), serviceWorkers ({ name: script } local
+// service-binding targets via Miniflare's workers array
+// (CF-3 multi-worker; the main worker stays in the array,
+// since the array replaces the top-level script)).
+// The runner runs a Worker in Miniflare with the full binding
+// surface from the wrangler file. start(script) is the
+// standalone/test path (startScript); the remaining extras
+// (dispatchFetch, dispatchScheduled, getQueueProducer,
+// setScript) are plugin-specific, not part of the interface.
+import fs from "node:fs";
+import path from "node:path";
+import { Log, LogLevel, Miniflare } from "miniflare";
+import { readWranglerConfig } from "./config.js";
+import { wranglerToMiniflareOptions } from "./bindings.js";
+
+// Module-runner harness (SPEC §16.11): the static worker
+// script (harness.js) is read as text and passed to
+// Miniflare as the main worker's script, with generated
+// export wrappers substituted for the placeholder. The
+// harness evaluates app modules inside workerd through the
+// unsafe-eval binding — a dev-only Miniflare option, never
+// a wrangler binding, never production.
+const HARNESS_TEMPLATE = fs.readFileSync(new URL("./harness.js", import.meta.url), "utf8");
+const EVAL_BINDING_NAME = "__jundle_runner_eval";
+const BASE_BINDING_NAME = "__jundle_runner_base";
+const ENTRY_BINDING_NAME = "__jundle_runner_entry";
+const IDENT = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+
+// Console forwarding (SPEC §16.11): Miniflare's `log`
+// option is the logger for its own errors, warnings and
+// informative messages. Without it the core service
+// defaults to NoOpLog, so Miniflare's own warnings and
+// errors are swallowed (worker console.log/error reach
+// the terminal anyway, via workerd's stdio pipe —
+// log/info/debug to stdout, warn/error to stderr — and
+// the `log` option does not duplicate them). Miniflare's
+// own Log writes every level to stdout (its log() is
+// console.log for all levels), so this subclass routes
+// by level instead — ERROR/WARN to stderr, the rest to
+// stdout — with the same `[mf:<level>]` prefix shape.
+const LOG_LEVEL_NAME = ["", "error", "warn", "info", "debug", "verbose"];
+class JundleLog extends Log {
+  logWithLevel(level, message) {
+    if (level <= 0 || level > this.level) return;
+    const line = `[mf:${LOG_LEVEL_NAME[level]}] ${message}`;
+    if (level <= LogLevel.WARN) console.error(line);
+    else console.log(line);
+  }
+}
+
+// Generate the static export wrappers for DO / Workflow /
+// entrypoint class exports (SPEC §16.11). Workers require
+// static exports, so the harness cannot export app classes
+// dynamically: each wrapper extends the real base class,
+// lazily constructs the real class from the evaluated entry
+// (after a version check, so alarms never use a stale
+// class), and delegates every discovered method. The names
+// `__jundleReal` / `__jundleRealInstance` / `__jundleCtx` /
+// `__jundleEnv` are reserved (a real class method of those
+// names is dropped rather than shadowing the
+// lazy-construction machinery).
+function buildWrappers(classes) {
+  const bases = {
+    "durable-object": "cwNs.DurableObject",
+    workflow: "cwNs.WorkflowEntrypoint",
+    entrypoint: "cwNs.WorkerEntrypoint",
+  };
+  return (classes || [])
+    .map(({ name, kind, methods }) => {
+      if (!IDENT.test(name))
+        throw new Error(
+          `CF plugin: refusing to generate wrapper for non-identifier export '${name}'`,
+        );
+      const base = bases[kind];
+      if (!base) throw new Error(`CF plugin: unknown export class kind '${kind}' for '${name}'`);
+      const methodLines = (methods || [])
+        .filter(
+          (m) =>
+            IDENT.test(m) &&
+            m !== "constructor" &&
+            m !== "__jundleReal" &&
+            m !== "__jundleRealInstance" &&
+            m !== "__jundleCtx" &&
+            m !== "__jundleEnv",
+        )
+        .map(
+          (m) =>
+            `  async ${m}(...args) { return (await this.__jundleReal())[${JSON.stringify(m)}](...args); }`,
+        );
+      return `export class ${name} extends ${base} {
+  constructor(ctx, env) {
+    super(ctx, env);
+    this.__jundleCtx = ctx;
+    this.__jundleEnv = env;
+    this.__jundleRealInstance = null;
+  }
+  async __jundleReal() {
+    if (!this.__jundleRealInstance) {
+      const m = await __jundleImportEntry();
+      const C = m[${JSON.stringify(name)}];
+      if (typeof C !== "function")
+        throw new Error("ModuleRunner: entry export " + ${JSON.stringify(name)} + " is not a class in the evaluated entry.");
+      this.__jundleRealInstance = new C(this.__jundleCtx, stripEnv(this.__jundleEnv));
+    }
+    return this.__jundleRealInstance;
+  }
+${methodLines.join("\n")}
+}`;
+    })
+    .join("\n");
+}
+
+function buildHarnessScript(exportShape) {
+  // Anchor on the standalone placeholder line: the header
+  // comment mentions the marker name, so a bare replace
+  // would substitute there instead of at the real line.
+  const replaced = HARNESS_TEMPLATE.replace(
+    "\n// __JUNDLE_WRAPPERS__\n",
+    `\n${buildWrappers(exportShape && exportShape.classes)}\n`,
+  );
+  if (replaced === HARNESS_TEMPLATE)
+    throw new Error("CF plugin: harness template is missing its __JUNDLE_WRAPPERS__ line");
+  return replaced;
+}
+
+// Find the built server entry chunk in a bundle dir.
+// Primary signal: server-manifest.json's `entries` —
+// the entry carrying a `runtime` is the process entry
+// (SPEC §6.12). Chunk file names are content-hashed
+// and change with the chunking policy, so no name
+// pattern or content sniffing is the primary lookup.
+// Fallback, for bundles built before `entries` existed:
+// it is the entry chunk that is NOT any page's
+// entryFile in page-manifest.json (pages are
+// server-entry modules; the runner is the remaining
+// server entry).
+// Workers require a static module graph: a variable dynamic
+// import (import(chunkId)) cannot be resolved, even if it is
+// never called. The browser shim (src/runtime/shim.js) has
+// exactly that — its loadChunk dynamic-imports the chunk URL
+// string (SPEC §6.11 manifest-free browser loading). SSR in
+// the Worker never calls it (SSR loads chunks through the
+// server shim's literal-import manifest), so the Worker's
+// copy of the bundle patches it to a throw. The browser still
+// gets the ORIGINAL bundle (served by the dev server as a dev
+// module, or in prod from the client dir at /assets/*), so
+// hydration is unaffected. Only files
+// containing a variable import are patched; a file with no
+// such import is copied verbatim.
+export async function createRunner({
+  configDir,
+  entryUrl,
+  exportShape,
+  options: entryOptions = {},
+}) {
+  const wranglerConfig = entryOptions.wranglerConfig
+    ? path.resolve(configDir, entryOptions.wranglerConfig)
+    : undefined;
+  const serviceWorkers = entryOptions.serviceWorkers;
+  const {
+    file: wranglerFile,
+    config,
+    devVars,
+  } = await readWranglerConfig({ configDir, wranglerConfig });
+  const options = wranglerToMiniflareOptions({
+    config,
+    devVars,
+    configDir,
+    wranglerFile,
+    remoteBindings: entryOptions.remoteBindings,
+  });
+  let mf = null;
+  // Runner state (SPEC §16.11): the entry dev URL + export
+  // shape from creation, and the dev-server base URL once
+  // start() runs after the server binds.
+  let runnerState = { entryUrl, exportShape, baseUrl: null };
+
+  // Build the Miniflare constructor args for a main worker.
+  // Single-worker (no serviceWorkers): the current top-level
+  // form (script or scriptPath). Multi-worker: Miniflare's
+  // `workers` array REPLACES the top-level script (CF-1
+  // quirk), so the main worker must be IN the array, carrying
+  // its bindings, with the Shared persist/compat options at
+  // top level. Unknown keys are stripped by Miniflare's Zod
+  // schemas, so passing the full mapped options on the main
+  // worker entry is safe (Shared-only keys like persist paths
+  // are stripped there and land via the top-level shared).
+  // Logging (see JundleLog above): pass a Log so
+  // Miniflare's own warnings/errors reach the terminal, and
+  // disable per-request logging — the dev server prints its
+  // own boot lines and no request logs, so Miniflare's
+  // "[mf:info] GET / 200 OK" lines would be noise. The
+  // `log` option is a shared (core) option, so it lands at
+  // top level in both forms.
+  const logging = { log: new JundleLog(LogLevel.INFO), logRequests: false };
+  function buildArgs(mainScript) {
+    if (!serviceWorkers || !Object.keys(serviceWorkers).length) {
+      return { ...options, ...logging, ...mainScript };
+    }
+    const shared = { ...logging };
+    for (const k of [
+      "kvPersist",
+      "r2Persist",
+      "d1Persist",
+      "durableObjectsPersist",
+      "workflowsPersist",
+      "compatibilityDate",
+      "compatibilityFlags",
+    ]) {
+      if (options[k] !== undefined) shared[k] = options[k];
+    }
+    const mainWorker = { name: options.name, ...options, ...mainScript };
+    const workers = [mainWorker];
+    for (const [name, script] of Object.entries(serviceWorkers)) {
+      // Service scripts are ESM (export default); without
+      // modules:true Miniflare parses them as CommonJS and
+      // `export` is a syntax error (same .js->CJS default as
+      // the CF-2 bundle chunks).
+      workers.push({ name, script, modules: true });
+    }
+    // The unsafe-eval binding is a per-worker option in the
+    // array form (and top-level in the single-worker form);
+    // include it in the shared options too, so it lands
+    // whichever schema Miniflare validates against. Unknown
+    // keys are stripped, so the duplicate is harmless.
+    if (mainScript.unsafeEvalBinding) shared.unsafeEvalBinding = mainScript.unsafeEvalBinding;
+    return { ...shared, workers };
+  }
+
+  async function applyMigrations(target) {
+    // D1 migrations (mapped in bindings.js as d1Migrations,
+    // NOT a Miniflare option — wrangler dev applies them
+    // itself). After Miniflare starts, execute each migration
+    // file's SQL against its D1 binding via getD1Database.
+    // `target` lets a reload run migrations against the new
+    // instance before it is swapped in; defaults to the live one.
+    // Applied files are tracked per binding in a
+    // __jundle_migrations table (same idea as wrangler's own
+    // tracking): a reconstruction or bundle reload builds a
+    // NEW Miniflare against the SAME persisted D1, and
+    // re-running CREATE TABLE fails with "table already
+    // exists" (and re-running data migrations would
+    // duplicate rows). New files still apply; a file whose
+    // exec fails is not recorded, so it retries next time.
+    const inst = target || mf;
+    for (const m of options.d1Migrations || []) {
+      const db = await inst.getD1Database(m.binding);
+      await db.exec("CREATE TABLE IF NOT EXISTS __jundle_migrations (filename TEXT PRIMARY KEY)");
+      const applied = new Set(
+        (await db.prepare("SELECT filename FROM __jundle_migrations").all()).results.map(
+          (r) => r.filename,
+        ),
+      );
+      for (const f of fs
+        .readdirSync(m.dir)
+        .filter((x) => x.endsWith(".sql"))
+        .sort()) {
+        if (applied.has(f)) continue;
+        await db.exec(fs.readFileSync(path.join(m.dir, f), "utf8"));
+        await db.prepare("INSERT INTO __jundle_migrations (filename) VALUES (?)").bind(f).run();
+      }
+    }
+  }
+
+  async function startRunnerInternal({ entryUrl, baseUrl, exportShape }) {
+    // The harness statically imports node: builtins, so it
+    // requires nodejs_compat from the wrangler file (the
+    // single source of truth — jundle never injects
+    // compatibility flags). Without it, Miniflare fails
+    // the first dispatch with a cryptic string-script
+    // module error; fail fast with the actual fix instead.
+    if (!(options.compatibilityFlags || []).includes("nodejs_compat")) {
+      throw new Error(
+        `CF plugin: the module runner requires "nodejs_compat" in compatibility_flags in ${wranglerFile} (the harness imports node: builtins); add it to the wrangler file.`,
+      );
+    }
+    // One static harness worker per session: the harness
+    // script (with wrappers for the export shape) + the
+    // unsafe-eval binding + the wrangler-derived bindings
+    // (merged with the harness's internal bindings, which
+    // the harness strips before app code sees env). App code
+    // is never a Miniflare option. Construct-before-dispose
+    // applies here too (see invalidate).
+    const script = buildHarnessScript(exportShape);
+    const harnessBindings = {
+      ...options.bindings,
+      [BASE_BINDING_NAME]: baseUrl,
+      [ENTRY_BINDING_NAME]: entryUrl,
+    };
+    const builtArgs = buildArgs({
+      script,
+      modules: true,
+      unsafeEvalBinding: EVAL_BINDING_NAME,
+      bindings: harnessBindings,
+    });
+    const next = new Miniflare(builtArgs);
+    try {
+      await applyMigrations(next);
+    } catch (e) {
+      // Mirror the bundle path: a failed construction must
+      // not leak its workerd child (an undisposed instance
+      // keeps the dev-server process alive at exit).
+      await next.dispose().catch(() => {});
+      throw e;
+    }
+    return next;
+  }
+
+  return {
+    config,
+    wranglerFile,
+    options,
+    // Uniform runner interface (SPEC §16.2): fetch serves
+    // the app, invalidate reconstructs on an export-shape
+    // change (otherwise a no-op — the harness pulls the
+    // recorded batch via the version route on next
+    // dispatch), dispose tears down Miniflare, and start
+    // (optional) starts the harness once the dev server
+    // has bound (it needs the base URL).
+    async fetch(request) {
+      if (!mf) throw new Error("CF plugin: runner not started (call start first)");
+      // Miniflare's dispatchFetch does a cross-realm
+      // instanceof Request check that Node's Request fails,
+      // falling through to new URL("[object Request]") —
+      // so dispatch uses plain values (URL string, plain
+      // headers object, string body), NOT the incoming
+      // Request object. Both parts must be forwarded:
+      // dropping init silently downgrades every request to
+      // a bare GET, so POST /action arrived as GET /action
+      // and the app 404'd on route no-match (GETs worked,
+      // which hid the bug).
+      const init = {
+        method: request.method,
+        headers: Object.fromEntries(request.headers.entries()),
+      };
+      if (request.method !== "GET" && request.method !== "HEAD") {
+        init.body = await request.text();
+      }
+      return mf.dispatchFetch(request.url, init);
+    },
+    async invalidate(_invalidated, opts) {
+      if (!opts?.exportShape) return;
+      if (!mf || !runnerState) throw new Error("CF plugin: cannot reconstruct before start");
+      // Export-shape change (SPEC §16.11): the export set is
+      // construction-time, so a new DO / Workflow / entrypoint
+      // class export (or a removed one) requires rebuilding
+      // Miniflare with new wrappers. Same bindings and
+      // persistence root (wrangler file unchanged), and the
+      // new instance is built before the old one is disposed.
+      const next = await startRunnerInternal({
+        entryUrl: runnerState.entryUrl,
+        baseUrl: runnerState.baseUrl,
+        exportShape: opts.exportShape,
+      });
+      const oldMf = mf;
+      mf = next;
+      runnerState = { ...runnerState, exportShape: opts.exportShape };
+      await oldMf.dispose();
+      // Observable like the "built in" line: a
+      // reconstruction costs a fresh Miniflare, so the dev
+      // server says so instead of silently stalling; tests
+      // capture this line as the positive reconstruction
+      // signal.
+      console.log("jundle: runner reconstructed (export shape changed)");
+    },
+    async start({ baseUrl }) {
+      if (mf) await mf.dispose();
+      mf = await startRunnerInternal({
+        entryUrl: runnerState.entryUrl,
+        baseUrl,
+        exportShape: runnerState.exportShape,
+      });
+      runnerState = { ...runnerState, baseUrl };
+    },
+    // Standalone/test path: start Miniflare with a given
+    // script (no harness). Not part of the interface.
+    async startScript(script) {
+      if (mf) await mf.dispose();
+      mf = new Miniflare(buildArgs({ script }));
+      await applyMigrations();
+      return mf;
+    },
+    // dispatchFetch takes (url, init) — plain values, not a
+    // Request object (Miniflare's dispatchFetch does a
+    // cross-realm instanceof check that Node's Request
+    // fails). Both args must be forwarded: dropping init
+    // silently downgrades every request to a bare GET, so POST
+    // /action arrived as GET /action and the app 404'd on route
+    // no-match (GETs worked, which hid the bug).
+    async dispatchFetch(url, init) {
+      if (!mf) throw new Error("CF plugin: runner not started (call start first)");
+      return mf.dispatchFetch(url, init);
+    },
+    async setScript(script) {
+      if (!mf) throw new Error("CF plugin: runner not started (call start first)");
+      await mf.setOptions({ script });
+    },
+    // Event handlers (SPEC §16.3, CF-3): fetch via
+    // dispatchFetch (above), plus scheduled + queue.
+    // Scheduled: Miniflare's getWorker().scheduled({ cron })
+    // (the documented dispatch path; there is no
+    // dispatchScheduled on Miniflare itself in v4).
+    async dispatchScheduled(cron) {
+      if (!mf) throw new Error("CF plugin: runner not started (call start first)");
+      const worker = await mf.getWorker();
+      return worker.scheduled({ cron: cron || "" });
+    },
+    // Queue: producers send (Miniflare delivers to the
+    // consumer Worker's queue() handler — the real path, not
+    // a synthetic dispatch). This returns the producer for a
+    // binding so callers can send; the consumer runs
+    // automatically on delivery.
+    async getQueueProducer(binding) {
+      if (!mf) throw new Error("CF plugin: runner not started (call start first)");
+      return mf.getQueueProducer(binding);
+    },
+    async dispose() {
+      if (mf) {
+        await mf.dispose();
+        mf = null;
+      }
+    },
+  };
+}
+
+export const defaultOptions = { wranglerConfig: null };
+
+export default { createRunner, defaultOptions };

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.