@nivalos/lithium.js 1.1.0

package/server/doctor.js

@@ -0,0 +1,132 @@
+import fs from "node:fs"
+import { dirname, join } from "node:path"
+import { fileURLToPath } from "node:url"
+
+import { PROXY_META, TRANSPORT_META, CORE_PACKAGES } from "./meta.js"
+import { check_packages } from "./pkgs.js"
+import { color } from "./color.js"
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+
+// Diagnoses a Lithium install. Never throws: problems are returned as data
+// so it works on exactly the installs that are broken.
+//   run_doctor({ proxy?, transport? }) -> { ok, errors, warnings, checks: [...] }
+export async function run_doctor(opts = {}) {
+  const checks = []
+  const add = (section, level, message, extra = {}) => checks.push({ section, level, message, ...extra })
+  const add_findings = (section, findings) => {
+    for (const f of findings) {
+      const { level, message, ...rest } = f
+      add(section, level, message, rest)
+    }
+  }
+
+  // ---- environment
+  let need = null
+  try {
+    const engines = JSON.parse(fs.readFileSync(join(HERE, "..", "package.json"), "utf8")).engines?.node
+    need = Number(/(\d+)/.exec(engines ?? "")?.[1]) || null
+  } catch {}
+  const have = Number(process.versions.node.split(".")[0])
+  if (need && have < need) {
+    add("Environment", "warn", `Node.js ${process.version} (Lithium.js declares node >=${need})`, { code: "NODE_VERSION" })
+  } else {
+    add("Environment", "ok", `Node.js ${process.version}`)
+  }
+
+  // ---- packages
+  add_findings("Core packages", check_packages(CORE_PACKAGES.map((p) => ({ ...p, role: "core" }))))
+
+  for (const [name, meta] of Object.entries(PROXY_META)) {
+    add_findings(`${meta.title} (${meta.interface} interface)`, check_packages(meta.packages.map((p) => ({ ...p, role: "proxy" }))))
+  }
+
+  for (const [tname, ifaces] of Object.entries(TRANSPORT_META)) {
+    const items = Object.entries(ifaces).map(([iface, m]) => ({
+      name: m.package, major: m.major, role: "transport", transport: tname, interface: iface,
+    }))
+    const findings = check_packages(items)
+    // label which generation each line is, that's the point of this section
+    findings.forEach((f, i) => { if (f.level !== "error") f.message += ` (${tname}, ${items[i].interface} generation)` })
+    add_findings("Transports", findings)
+  }
+
+  // ---- served files (needs the packages to be importable)
+  let reg = null
+  try {
+    reg = await import("./registry.js")
+  } catch (err) {
+    const first = String(err?.message ?? err).split("\n")[0]
+    add("Files", "error", `couldn't load Lithium's backends: ${first}`, {
+      code: "BACKENDS_LOAD_FAILED", hint: "a package is missing or broken, fix the errors above and run `npm install`",
+    })
+  }
+
+  const wanted_proxy = opts.proxy ?? "ultraviolet"
+  const wanted_transport = opts.transport ?? "epoxy"
+
+  if (reg) {
+    const seen = new Set()
+    for (const p of Object.keys(PROXY_META)) {
+      for (const t of Object.keys(TRANSPORT_META)) {
+        let mounts
+        try { mounts = reg.mounts_for(reg.resolve_backend(p, t)) } catch (err) {
+          add("Files", "error", `${p} + ${t}: ${err.message}`, { code: err.code ?? "MOUNT_FAILED" })
+          continue
+        }
+        for (const m of mounts) {
+          const key = `${m.url}|${m.dir}`
+          if (seen.has(key)) continue
+          seen.add(key)
+          const missing = m.files.filter((f) => !fs.existsSync(join(m.dir, f)))
+          if (missing.length) add("Files", "error", `${m.url} (${m.label}) is missing ${missing.join(", ")} in ${m.dir}`, { code: "FILES_MISSING", path: m.dir, missing })
+          else add("Files", "ok", `${m.url} (${m.label})`)
+        }
+      }
+    }
+
+    // ---- the configuration you're about to run
+    const compat = reg.get_compatibility(wanted_proxy, wanted_transport)
+    const section = `Configuration (proxy=${wanted_proxy}, transport=${wanted_transport})`
+    if (!compat.supported) {
+      add(section, "error", compat.reason, { code: "INCOMPATIBLE_TRANSPORT" })
+    } else {
+      add(section, "ok", `${wanted_proxy} and ${wanted_transport} are compatible (${compat.interface} interface)`)
+      const isolated = reg.proxies.get(wanted_proxy)?.isolation
+      add(section, "info", isolated
+        ? "cross-origin isolation: on (COOP/COEP headers are sent; your own page must not load third-party assets without CORS/CORP)"
+        : "cross-origin isolation: off")
+      add(section, "info", "service workers need https or localhost; Scramjet also needs the page to be cross-origin isolated")
+    }
+  }
+
+  const errors = checks.filter((c) => c.level === "error").length
+  const warnings = checks.filter((c) => c.level === "warn").length
+  return { ok: errors === 0, errors, warnings, checks }
+}
+
+const ICON = { ok: "✓", warn: "!", error: "✗", info: "•" }
+const PAINT = { ok: color.green, warn: color.yellow, error: color.red, info: color.gray }
+
+export function format_doctor(result) {
+  const lines = ["", "Lithium doctor", ""]
+  let section = null
+  for (const c of result.checks) {
+    if (c.section !== section) {
+      if (section !== null) lines.push("")
+      lines.push(c.section)
+      section = c.section
+    }
+    const paint = PAINT[c.level] ?? ((x) => x)
+    lines.push(`  ${paint(ICON[c.level] ?? "?")} ${c.message}`)
+    if ((c.level === "error" || c.level === "warn") && c.hint) lines.push(color.dim(`      → ${c.hint}`))
+  }
+  lines.push("")
+  lines.push(
+    result.ok
+      ? color.green(`No problems found${result.warnings ? ` (${result.warnings} warning${result.warnings === 1 ? "" : "s"})` : ""}.`)
+      : color.red(`${result.errors} problem${result.errors === 1 ? "" : "s"} found${result.warnings ? `, ${result.warnings} warning${result.warnings === 1 ? "" : "s"}` : ""}.`)
+  )
+  lines.push("")
+  return lines.join("\n")
+}

package/server/errors.js

@@ -0,0 +1,21 @@
+// Every error Lithium throws on purpose is a LithiumError, so you can branch
+// on `err.code` instead of parsing message strings.
+//
+//   try { create_lithium_server({ proxy: "nope" }) }
+//   catch (e) { if (e.code === "UNKNOWN_PROXY") console.log(e.details.available) }
+//
+// Codes: UNKNOWN_PROXY, UNKNOWN_TRANSPORT, INCOMPATIBLE_TRANSPORT,
+//        PACKAGE_MISSING, PACKAGE_VERSION_MISMATCH, TRANSPORT_VERSION_MISMATCH,
+//        BACKEND_EXISTS, INVALID_BACKEND, INVALID_OPTION
+export class LithiumError extends Error {
+  constructor(code, message, details = {}) {
+    super(message)
+    this.name = "LithiumError"
+    this.code = code
+    this.details = details
+  }
+
+  toJSON() {
+    return { name: this.name, code: this.code, message: this.message, details: this.details }
+  }
+}

package/server/index.js

@@ -0,0 +1,238 @@
+import express from "express"
+import { createServer } from "node:http"
+import { join, dirname, resolve, sep } from "node:path"
+import { fileURLToPath } from "node:url"
+import fs from "node:fs"
+import { load } from "cheerio"
+import { server as wisp } from "@mercuryworkshop/wisp-js/server"
+
+import { proxies, transports, supports, get_compatibility, resolve_backend, mounts_for, packages_for } from "./registry.js"
+import { check_packages, find_package } from "./pkgs.js"
+import { LithiumError } from "./errors.js"
+import { run_doctor } from "./doctor.js"
+import { color, set_color } from "./color.js"
+
+export { proxies, transports, supports, get_compatibility, LithiumError, run_doctor }
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+
+// generated service worker for custom proxies (built-ins use client/sw.js)
+const sw_source = (custom) => `// generated by lithium for the "${custom.name}" proxy
+self.addEventListener("install", () => self.skipWaiting())
+self.addEventListener("activate", (event) => event.waitUntil(self.clients.claim()))
+${custom.serviceWorker}
+`
+
+// main function
+//   proxy                 "ultraviolet" | "scramjet" | anything you registered
+//   transport             "epoxy" | "libcurl" | anything you registered
+//   staticDir, port       your frontend folder / the port to listen on
+//   crossOriginIsolation  send COOP/COEP (only for proxies that want it)
+//   middleware            [(req, res, next) => ...] runs before Lithium's routes
+//   wisp                  options for the wisp server, e.g. { allow_loopback_ips: true }
+//                         (wisp is one shared instance, so this is process-wide)
+//   strict                false: warn about version problems instead of throwing
+//   quiet                 no startup log line
+export function create_lithium_server(opts = {}) {
+  const static_dir = opts.staticDir || "public"
+  const port = opts.port || 8080
+  const proxy = opts.proxy || "ultraviolet"
+  const transport = opts.transport || "epoxy"
+  const isolation = opts.crossOriginIsolation !== false
+  const strict = opts.strict !== false
+  const quiet = opts.quiet === true
+  if (opts.color != null) set_color(Boolean(opts.color))
+
+  const middleware = opts.middleware ?? []
+  if (!Array.isArray(middleware) || middleware.some((m) => typeof m !== "function")) {
+    throw new LithiumError("INVALID_OPTION", "middleware must be an array of (req, res, next) functions", { option: "middleware" })
+  }
+  if (opts.wisp != null && (typeof opts.wisp !== "object" || Array.isArray(opts.wisp))) {
+    throw new LithiumError("INVALID_OPTION", "wisp must be an object of wisp-js server options", { option: "wisp" })
+  }
+
+  // Throws UNKNOWN_PROXY / UNKNOWN_TRANSPORT / INCOMPATIBLE_TRANSPORT
+  const backend = resolve_backend(proxy, transport)
+
+  // Wrong package generations "sort of work" and then die on random sites,
+  // so catch them at startup with an error that says what to do.
+  const findings = check_packages(packages_for(backend))
+  const bad = findings.filter((f) => f.level === "error")
+  if (bad.length) {
+    if (strict) {
+      const { message, hint, ...details } = bad[0]
+      throw new LithiumError(bad[0].code, hint ? `${message} (${hint})` : message, { ...details, all: bad })
+    }
+    for (const f of bad) console.warn(color.yellow(`[lithium] ${f.message}`))
+  }
+  for (const f of findings.filter((x) => x.level === "warn")) if (!quiet) console.warn(color.yellow(`[lithium] ${f.message}`))
+
+  if (opts.wisp) Object.assign(wisp.options, opts.wisp)
+
+  // absolute or relative, resolve() handles both (and Windows drive letters)
+  const static_path = resolve(process.cwd(), static_dir)
+  const client_path = join(__dirname, "..", "client")
+
+  const app = express()
+  const server = createServer(app)
+
+  for (const fn of middleware) app.use(fn)
+
+  // COOP/COEP make the page cross-origin isolated. Scramjet needs it (it
+  // passes the isolation on to every proxied site); Ultraviolet doesn't want it.
+  const isolated = Boolean(backend.proxy.isolation && isolation)
+  if (isolated) {
+    app.use((_req, res, next) => {
+      res.setHeader("Cross-Origin-Opener-Policy", "same-origin")
+      res.setHeader("Cross-Origin-Embedder-Policy", "require-corp")
+      next()
+    })
+  }
+
+  app.use("/client/", express.static(client_path))
+
+  // sw.js has to be served from the root so its scope covers the whole site.
+  // The client registers it as /sw.js?proxy=<name>; built-in proxies get the
+  // shared client/sw.js, custom ones a generated worker.
+  const custom_sw = backend.proxy.builtin ? null : sw_source(backend.proxy)
+  app.get("/sw.js", (_req, res) => {
+    res.setHeader("Service-Worker-Allowed", "/")
+    if (custom_sw) res.type("js").send(custom_sw)
+    else res.sendFile(join(client_path, "sw.js"))
+  })
+
+  // routes first (e.g. generated uv.config.js), so they win over static files
+  backend.proxy.routes?.(app)
+
+  // static folders. A missing file is reported once, here, instead of
+  // turning into a mystery 404 in the browser later.
+  const problems = []
+  let mounts
+  try {
+    mounts = mounts_for(backend)
+  } catch (err) {
+    throw new LithiumError("FILES_MISSING", `couldn't locate the files for ${proxy} + ${transport}: ${err.message}`, {
+      proxy, transport, cause: String(err?.message ?? err), hint: "run `npx lithium doctor`",
+    })
+  }
+  for (const m of mounts) {
+    app.use(m.url, express.static(m.dir))
+    for (const f of m.files) {
+      if (!fs.existsSync(join(m.dir, f))) {
+        problems.push({ code: "FILES_MISSING", label: m.label, file: f, dir: m.dir })
+        console.error(color.red(`[lithium] ${m.label}: expected "${f}" in ${m.dir} but it isn't there`))
+      }
+    }
+  }
+
+  // --- config injection ------------------------------------------------------
+  // The client reads window.__LITHIUM_CONFIG__ to know which proxy/transport
+  // the server was started with.
+  const impl = backend.impl
+  const injected = {
+    proxy,
+    transport,
+    interface: backend.interface,
+    transportUrl: impl.mount + (impl.entry ?? "index.mjs"),
+    ...(backend.proxy.builtin ? {} : { clientModule: backend.proxy.clientModule }),
+    isolated,
+  }
+  const config_script = "window.__LITHIUM_CONFIG__=" + JSON.stringify(injected).replace(/</g, "\\u003c") + ";"
+
+  function inject_config(html) {
+    try {
+      const $ = load(html)
+      const tag = `<script>${config_script}</script>`
+      if ($("head").length) $("head").prepend(tag)
+      else if ($("body").length) $("body").prepend(tag)
+      else return tag + html
+      return $.html()
+    } catch (err) {
+      console.error("[lithium] cheerio injection failed:", err)
+      return html
+    }
+  }
+
+  // map a request path to an .html file inside static_path, or null.
+  // Never returns anything outside static_path (no ../ tricks).
+  function html_file_for(req_path) {
+    let rel
+    try {
+      rel = decodeURIComponent(req_path)
+    } catch {
+      return null
+    }
+    if (rel.endsWith("/")) rel += "index.html"
+    if (!rel.endsWith(".html")) return null
+
+    const full = resolve(static_path, "." + rel)
+    if (full !== static_path && !full.startsWith(static_path + sep)) return null
+    try {
+      return fs.statSync(full).isFile() ? full : null
+    } catch {
+      return null
+    }
+  }
+
+  // parsing HTML on every request is wasteful, so cache by mtime
+  const html_cache = new Map()
+  function read_html(file) {
+    const mtime = fs.statSync(file).mtimeMs
+    const hit = html_cache.get(file)
+    if (hit && hit.mtime === mtime) return hit.html
+    const html = inject_config(fs.readFileSync(file, "utf8"))
+    html_cache.set(file, { mtime, html })
+    return html
+  }
+
+  app.use((req, res, next) => {
+    if (req.method !== "GET") return next()
+    const file = html_file_for(req.path)
+    if (!file) return next()
+    try {
+      return res.type("html").send(read_html(file))
+    } catch (err) {
+      console.error("[lithium] failed to read/inject file:", err)
+      next()
+    }
+  })
+
+  // everything else in the static dir (js, css, images, ...)
+  app.use(express.static(static_path))
+
+  // nothing in static dir matched "/" -> show that we're alive
+  app.get("/", (_req, res) => {
+    res.json({ msg: "lithium server running", proxy, transport, staticDir: static_path })
+  })
+
+  // wisp lives at /wisp/ and nowhere else
+  server.on("upgrade", (req, sock, head) => {
+    let pathname = null
+    try {
+      pathname = new URL(req.url ?? "/", "http://localhost").pathname
+    } catch {}
+
+    if (pathname === "/wisp/" && req.headers.upgrade?.toLowerCase() === "websocket") {
+      req.url = pathname
+      wisp.routeRequest(req, sock, head)
+    } else if (server.listenerCount("upgrade") === 1) {
+      // only close it if nobody else (e.g. your own ws handler) is listening
+      sock.destroy()
+    }
+  })
+
+  const info = {
+    proxy,
+    transport,
+    interface: backend.interface,
+    isolation: isolated,
+    packages: packages_for(backend).map((p) => ({ name: p.name, version: find_package(p.name)?.version ?? null })),
+    problems,
+  }
+  if (!quiet) {
+    const pkgs = info.packages.map((p) => `${p.name}@${color.dim(p.version ?? "?")}`).join(", ")
+    console.log(color.green(`[lithium] ${proxy} + ${transport}`) + color.dim(` (${backend.interface} interface${isolated ? ", cross-origin isolated" : ""}): `) + pkgs)
+  }
+
+  return { app, server, port, backend: info }
+}

package/server/meta.js

@@ -0,0 +1,55 @@
+// Plain data about the built-in backends. No imports of the proxy packages
+// here on purpose: `lithium doctor` uses this to diagnose an install where
+// those packages are missing or broken, so it has to load no matter what.
+
+// Two incompatible generations of transport packages exist:
+//   "bare-mux"          used by Ultraviolet 3.x (epoxy ^2, libcurl ^1)
+//   "proxy-transports"  used by Scramjet 2.x    (epoxy ^3, libcurl ^2)
+// A proxy speaks exactly one interface and can only use a transport that
+// ships that interface.
+
+export const PROXY_META = {
+  ultraviolet: {
+    title: "Ultraviolet",
+    interface: "bare-mux",
+    // send COOP/COEP headers (cross-origin isolation)? Scramjet needs it.
+    // Ultraviolet's service-worker responses don't opt in to COEP, so it
+    // would be blocked inside an isolated page.
+    isolation: false,
+    packages: [
+      { name: "@titaniumnetwork-dev/ultraviolet", major: 3 },
+      { name: "@mercuryworkshop/bare-mux", major: 2 },
+    ],
+  },
+  scramjet: {
+    title: "Scramjet",
+    interface: "proxy-transports",
+    isolation: true,
+    // pinned = the exact version Lithium was built and tested against. A
+    // different version is a warning (0.x releases break in minor bumps).
+    packages: [
+      { name: "@mercuryworkshop/scramjet", major: 2, pinned: "2.0.67-alpha.2" },
+      { name: "@mercuryworkshop/scramjet-controller", major: 0, pinned: "0.0.14" },
+      { name: "@mercuryworkshop/scramjet-utils", major: 0, pinned: "0.0.3" },
+    ],
+  },
+}
+
+// `package` is the npm install name (the *-bm ones are npm aliases, see
+// package.json), `major` the major version that speaks that interface.
+export const TRANSPORT_META = {
+  epoxy: {
+    "bare-mux": { package: "epoxy-transport-bm", major: 2 },
+    "proxy-transports": { package: "@mercuryworkshop/epoxy-transport", major: 3 },
+  },
+  libcurl: {
+    "bare-mux": { package: "libcurl-transport-bm", major: 1 },
+    "proxy-transports": { package: "@mercuryworkshop/libcurl-transport", major: 2 },
+  },
+}
+
+export const CORE_PACKAGES = [
+  { name: "express", major: 5 },
+  { name: "cheerio" },
+  { name: "@mercuryworkshop/wisp-js" },
+]

package/server/pkgs.js

@@ -0,0 +1,91 @@
+import fs from "node:fs"
+import { dirname, join, basename } from "node:path"
+import { fileURLToPath } from "node:url"
+import { TRANSPORT_META } from "./meta.js"
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+
+// Find an installed package the way Node would (nested node_modules first,
+// then hoisted ones), but by reading its package.json directly. That works
+// for npm aliases and for packages whose "exports" hide package.json, and it
+// never imports the package.
+export function find_package(name, from = HERE) {
+  let dir = from
+  for (;;) {
+    if (basename(dir) !== "node_modules") {
+      const pj = join(dir, "node_modules", ...name.split("/"), "package.json")
+      if (fs.existsSync(pj)) {
+        let version = null
+        try { version = JSON.parse(fs.readFileSync(pj, "utf8")).version ?? null } catch {}
+        return { name, dir: dirname(pj), version }
+      }
+    }
+    const up = dirname(dir)
+    if (up === dir) return null
+    dir = up
+  }
+}
+
+export function major_of(version) {
+  const m = /^(\d+)\./.exec(version ?? "")
+  return m ? Number(m[1]) : null
+}
+
+// which interface generation does this installed transport major belong to?
+function generation_of(transport, major) {
+  const meta = TRANSPORT_META[transport]
+  if (!meta) return null
+  for (const [iface, m] of Object.entries(meta)) if (m.major === major) return iface
+  return null
+}
+
+// items: [{ name, major?, pinned?, role: "proxy"|"transport"|"core",
+//           transport?, interface? }]
+// returns one finding per item: { level: "ok"|"warn"|"error", code?, package,
+//   installed, message, ...details }
+export function check_packages(items) {
+  return items.map((item) => {
+    const found = find_package(item.name)
+    const base = { package: item.name, role: item.role }
+
+    if (!found) {
+      return {
+        ...base, level: "error", code: "PACKAGE_MISSING", installed: null,
+        message: `${item.name} is not installed`,
+        hint: "run `npm install`",
+      }
+    }
+    const installed = found.version
+    const found_major = major_of(installed)
+
+    if (item.major != null && found_major !== item.major) {
+      if (item.role === "transport") {
+        const generation = generation_of(item.transport, found_major)
+        return {
+          ...base, level: "error", code: "TRANSPORT_VERSION_MISMATCH",
+          installed, expected: `${item.major}.x`, interface: item.interface,
+          detected: generation ? `${generation} generation` : `major ${found_major}`,
+          path: found.dir,
+          message:
+            `${item.name} ${installed} is installed but the ${item.interface} interface needs ${item.major}.x` +
+            (generation ? ` (${installed} is the ${generation} generation)` : ""),
+          hint: "don't change the transport package versions in package.json; see the README's transport section",
+        }
+      }
+      return {
+        ...base, level: "error", code: "PACKAGE_VERSION_MISMATCH",
+        installed, expected: `${item.major}.x`, path: found.dir,
+        message: `${item.name} ${installed} is installed but Lithium needs ${item.major}.x`,
+        hint: "reinstall lithium.js so its pinned dependency versions are used",
+      }
+    }
+
+    if (item.pinned && installed !== item.pinned) {
+      return {
+        ...base, level: "warn", code: "UNTESTED_VERSION", installed, expected: item.pinned,
+        message: `${item.name} ${installed} is installed, Lithium was tested with ${item.pinned}`,
+      }
+    }
+    return { ...base, level: "ok", installed, message: `${item.name} ${installed ?? "(unknown version)"}` }
+  })
+}