uniweb 1.0.0 → 1.0.2

package/src/utils/code-upload.js

@@ -0,0 +1,394 @@
+/**
+ * Foundation code delivery — the phase-2 client of `uniweb register`.
+ *
+ * After a successful schema registration, the foundation's built `dist/`
+ * bytes are delivered to the registry in two steps (contract:
+ * foundation-code-upload.md, beside uwx-format.md):
+ *
+ *   1. PLAN   — POST {apiBase}/dev/registry/code-uploads with the file list
+ *               ({ path, content_type, size, sha256? }). The response carries
+ *               one entry per file: `present: true` for a file the backend
+ *               already stores for this version (no URL — it is skipped), or an
+ *               upload target ({ path, method, url, headers }). Plus mode:
+ *               'direct' (dev — URLs point back at the backend) or 'presigned'
+ *               (prod — storage PUTs; bytes never transit the backend). The CLI
+ *               never branches on the mode.
+ *   2. UPLOAD — PUT each file's raw bytes to its URL with the given headers.
+ *               The ENTRY uploads LAST: a partial upload never yields a
+ *               loadable version (practical atomicity — there is no server
+ *               confirm step by design).
+ *
+ * When the plan tells us where the version will be readable, the entry is
+ * fetched back from that location and compared byte-for-byte — the e2e proof
+ * that the version is live. The location is ALWAYS read from the plan's
+ * `serve_base`, never derived: where a backend serves uploaded code is its
+ * own business, and a producer that reconstructs the path is both coupled to
+ * it and wrong wherever a delivery tier mints the URL instead. No
+ * `serve_base` simply means "not verifiable from here" — not a fallback guess.
+ *
+ * Rules encoded here (the backend validates too — reject, never repair):
+ *   - paths are dist/-relative, '/'-separated, URL-safe verbatim
+ *   - `meta/**` is EXCLUDED from the upload set: schema custody is the
+ *     registry's entity store, and the gateway serves anonymously while
+ *     schemas are authenticated content everywhere else (no public catalog)
+ *   - `*.map` sourcemaps are EXCLUDED: they are dev-only debugging artifacts,
+ *     not part of the CDN-served runtime. (A Shiki-heavy foundation emits a
+ *     map per highlighted-grammar chunk, which is what pushes a build past the
+ *     plan step's per-version file cap — the cap is an abuse guard, the maps
+ *     simply don't belong on the CDN.)
+ *   - a registered version is immutable, code included — changed bytes mean
+ *     a new version. A stored file is never re-sent (the plan marks it
+ *     `present`), and one declared at a different size is refused (422)
+ */
+
+import { createHash } from 'node:crypto'
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+import { fetchWithRetry, isTransientStatus } from './fetch-retry.js'
+
+// Extension → declared content type. Extension-honest by construction (Vite
+// output); anything unknown ships as octet-stream.
+const CONTENT_TYPES = {
+  js: 'text/javascript',
+  mjs: 'text/javascript',
+  css: 'text/css',
+  map: 'application/json',
+  json: 'application/json',
+  wasm: 'application/wasm',
+  woff2: 'font/woff2',
+  woff: 'font/woff',
+  ttf: 'font/ttf',
+  png: 'image/png',
+  jpg: 'image/jpeg',
+  jpeg: 'image/jpeg',
+  gif: 'image/gif',
+  svg: 'image/svg+xml',
+  webp: 'image/webp',
+  avif: 'image/avif',
+  ico: 'image/x-icon',
+  txt: 'text/plain',
+  html: 'text/html'
+}
+
+export function contentTypeFor(path) {
+  const ext = path.slice(path.lastIndexOf('.') + 1).toLowerCase()
+  return CONTENT_TYPES[ext] || 'application/octet-stream'
+}
+
+/** The dist-root entry file — uploaded last, verified after. */
+export const ENTRY_PATH = 'entry.js'
+
+/**
+ * Walk a built dist/ and produce the upload file list.
+ * Excludes `meta/**` and `*.map` sourcemaps (see header). Paths are
+ * POSIX-relative to distDir.
+ *
+ * @param {string} distDir
+ * @returns {Array<{ path: string, content_type: string, size: number, sha256: string }>}
+ */
+export function collectDistFiles(distDir) {
+  const files = []
+  const walk = (dir, prefix) => {
+    for (const name of readdirSync(dir).sort()) {
+      const full = join(dir, name)
+      const rel = prefix ? `${prefix}/${name}` : name
+      const st = statSync(full)
+      if (st.isDirectory()) {
+        if (rel === 'meta') continue // schema custody + no-public-catalog
+        walk(full, rel)
+      } else if (st.isFile()) {
+        if (rel.endsWith('.map')) continue // sourcemaps: dev-only, not CDN-served
+        const bytes = readFileSync(full)
+        files.push({
+          path: rel,
+          content_type: contentTypeFor(rel),
+          size: st.size,
+          sha256: createHash('sha256').update(bytes).digest('hex')
+        })
+      }
+    }
+  }
+  walk(distDir, '')
+  return files
+}
+
+/** Entry-last upload order (practical atomicity — see header). */
+export function uploadOrder(files) {
+  const entry = files.filter((f) => f.path === ENTRY_PATH)
+  const rest = files.filter((f) => f.path !== ENTRY_PATH)
+  return [...rest, ...entry]
+}
+
+/**
+ * The deterministic content digest of a built foundation — the freshness
+ * fingerprint `register` records and `publish`/`status` later compare against
+ * (shipping-model.md §4.1). It answers one question — "did the foundation change
+ * since it was released?" — with NO local state, so it has to be reproducible:
+ * the same source, built on any machine, must yield the same digest.
+ *
+ * Algorithm (§4.1): `sha256` over the newline-joined, SORTED list of the
+ * per-file `sha256` (hex) of exactly what `register` ships for a foundation —
+ *   - the code-upload set (`collectDistFiles`: entry + chunks + assets, with
+ *     `meta/**` and `*.map` already excluded), and
+ *   - the schema source (`meta/schema.json`) — NOT uploaded as a file, and not
+ *     sent verbatim: register submits its *content* as the foundation-schema
+ *     ENTITY in the `.uwx`. It's read here only to fold the schema into the
+ *     local freshness fingerprint (so a schema edit shows as "changed").
+ * Hashes are SORTED (so the digest is order-independent) and taken over file
+ * CONTENTS, not names, so content-hashed chunk filenames don't perturb it.
+ * Returns null when there's nothing to hash (no usable dist), so callers skip
+ * cleanly rather than fingerprinting emptiness.
+ *
+ * The result is OPAQUE to the backend — it stores the string and returns it
+ * verbatim; the framework owns the algorithm end-to-end and can change it
+ * freely (a digest only ever compares against one the same CLI computed).
+ *
+ * @param {string} distDir - the built `dist/` directory
+ * @returns {string|null} `sha256:<hex>` or null when there's nothing to hash
+ */
+/**
+ * The `@uniweb/runtime` version a built foundation linked against, from
+ * `dist/runtime-pin.json`.
+ *
+ * ⭐ **This is the ONLY reader of that file, and it exists so the pin can reach
+ * a party that can act on it.** The pin is a compatibility FLOOR — the lowest
+ * runtime this build is known to work against. A site loads a primary
+ * foundation plus N extensions, so a site's floor is `max()` over all of their
+ * pins, and the producer publishing one foundation cannot compute that: it does
+ * not hold the others. Whoever holds every foundation a site loads can.
+ *
+ * So the split is: the producer STATES its own floor, and a party that resolves
+ * a whole site CHECKS them. Riding it in the identity card next to `digest` is
+ * what makes the first half possible — and until it did, a consumer storing the
+ * value had no way to ever receive one.
+ *
+ * Returns null when the pin is absent (the build could not resolve
+ * `@uniweb/runtime`) or malformed. ⚠️ **null means UNKNOWN, not unconstrained** —
+ * a floor that is absent cannot be proven satisfied by anything, and a
+ * consumer's `max()` that skips nulls silently computes a floor over only the
+ * foundations that happened to declare one.
+ *
+ * @param {string} distDir - the built `dist/` directory
+ * @returns {string|null} e.g. `'0.9.8'`
+ */
+export function readRuntimePin(distDir) {
+  try {
+    const pin = JSON.parse(readFileSync(join(distDir, 'runtime-pin.json'), 'utf8'))
+    return typeof pin?.runtime === 'string' && pin.runtime ? pin.runtime : null
+  } catch {
+    return null // absent or unparseable — both are "unknown"
+  }
+}
+
+export function computeFoundationDigest(distDir) {
+  const hashes = collectDistFiles(distDir).map((f) => f.sha256)
+  // The schema rides in the register `.uwx`, not the code-upload set, so fold
+  // it in explicitly — a schema-only change is still a foundation change.
+  const schemaPath = join(distDir, 'meta', 'schema.json')
+  if (existsSync(schemaPath)) {
+    hashes.push(
+      createHash('sha256').update(readFileSync(schemaPath)).digest('hex')
+    )
+  }
+  if (!hashes.length) return null
+  hashes.sort()
+  return (
+    'sha256:' + createHash('sha256').update(hashes.join('\n')).digest('hex')
+  )
+}
+
+/*
+ * There is deliberately no serve-URL builder here. A previous version exported
+ * `gatewayUrl()`, which reconstructed the backend's serve path from the ref —
+ * mirroring its storage convention, scope-without-the-'@' and all. That was
+ * wrong twice over: it encoded another service's route layout in a public
+ * package, and it can only ever be right on the one deployment shape where the
+ * backend also serves the bytes. Read `serve_base` from the upload plan.
+ */
+
+/**
+ * Deliver a foundation's code: plan, upload (entry last), verify (direct
+ * mode). Returns a result object; throws only on plan-level failures.
+ *
+ * @param {object} opts
+ * @param {string} opts.apiBase  - registry origin (e.g. http://localhost:8080)
+ * @param {string} opts.token    - bearer (same session as register)
+ * @param {string} opts.name     - '@scope/name'
+ * @param {string} opts.version  - the registered semver
+ * @param {string} opts.distDir  - the built dist/ directory
+ * @param {Array}  [opts.files]  - pre-collected file list (default: collect)
+ * @param {(msg: string) => void} [opts.onProgress]
+ * @returns {Promise<{ mode: string, uploaded: string[], stored: string[], failed: Array<{path, status, detail}>, verified: boolean|null, serveBase: string|null }>}
+ *   `stored` — files the plan reported as already stored (`present: true`), not re-sent.
+ * @throws {Error} when the plan is refused — with `status`, and the problem+json
+ *   `detail` and `code` when the body carries them
+ */
+export async function uploadFoundationCode({
+  apiBase,
+  token,
+  name,
+  version,
+  distDir,
+  files,
+  onProgress = () => {}
+}) {
+  const list = files || collectDistFiles(distDir)
+  if (!list.length) {
+    return {
+      mode: 'none',
+      uploaded: [],
+      failed: [],
+      verified: null,
+      serveBase: null
+    }
+  }
+
+  const origin = apiBase.replace(/\/$/, '')
+  const planRes = await fetch(`${origin}/dev/registry/code-uploads`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${token}`
+    },
+    body: JSON.stringify({
+      name,
+      version,
+      files: list.map(({ path, content_type, size, sha256 }) => ({
+        path,
+        content_type,
+        size,
+        // Optional integrity hint (ignored by the v1 backend; flows so a
+        // future checksum-bearing presign needs no CLI change).
+        sha256
+      }))
+    })
+  })
+  if (!planRes.ok) {
+    const body = await planRes.text().catch(() => '')
+    // A refusal is problem+json, and its `detail` is a sentence written for the
+    // person reading — for a changed file it says what to do. Carry it (and the
+    // `code`) instead of a raw body the reader has to dig the sentence out of.
+    let problem = null
+    try {
+      problem = JSON.parse(body)
+    } catch {
+      problem = null
+    }
+    const detail = typeof problem?.detail === 'string' ? problem.detail : null
+    const err = new Error(
+      `code-uploads plan rejected: HTTP ${planRes.status}${detail ? ` — ${detail}` : body ? ` — ${body.slice(0, 300)}` : ''}`
+    )
+    err.status = planRes.status
+    err.detail = detail
+    err.code = typeof problem?.code === 'string' ? problem.code : null
+    throw err
+  }
+  const plan = await planRes.json()
+  const targets = new Map((plan.uploads || []).map((u) => [u.path, u]))
+  const serveBase = plan.serve_base || null
+  // The ONE mode-aware bit: direct-mode PUTs are bearer-authed backend
+  // routes; presigned URLs are self-authorizing and must NOT carry a
+  // bearer (foreign auth headers can break signed-request validation).
+  const authHeaders =
+    plan.mode === 'direct' ? { Authorization: `Bearer ${token}` } : {}
+
+  const uploaded = []
+  const stored = []
+  const failed = []
+  for (const file of uploadOrder(list)) {
+    const target = targets.get(file.path)
+    if (!target) {
+      failed.push({
+        path: file.path,
+        status: 0,
+        detail: 'no upload target in plan'
+      })
+      continue
+    }
+    // ⭐ A file the backend already stores for this version comes back
+    // `present: true`, with no URL — a stored file of a registered version is
+    // never overwritten. Skip it. This is what lets an interrupted upload
+    // resume, and a re-run on a fully uploaded version pass.
+    //
+    // ⛔ Before this branch existed, a present entry was PUT to
+    // `new URL(undefined, origin)`, which does not throw — it resolves to
+    // `<origin>/undefined` — and came back as a failed upload.
+    if (target.present === true) {
+      stored.push(file.path)
+      onProgress(`${file.path} (already stored)`)
+      continue
+    }
+    if (!target.url) {
+      failed.push({
+        path: file.path,
+        status: 0,
+        detail: 'the plan gave no upload URL'
+      })
+      continue
+    }
+    const bytes = readFileSync(join(distDir, file.path))
+    try {
+      // ⭐ **Retried.** A single connection-level failure used to fail the whole
+      // verb after every other file had already gone up. The PUT is idempotent
+      // here — same bytes, same target, verified by `x-uniweb-sha256` on receipt
+      // — so repeating it is safe by construction, which is why this opts in to
+      // `retryOnStatus` rather than inheriting it.
+      //
+      // ⚠️ 120s per attempt, not the helper's 30s default: this bounds the time
+      // to send a whole BODY, and aborting a legitimately slow upload only to
+      // retry it is worse than not timing out at all.
+      const res = await fetchWithRetry(new URL(target.url, origin), {
+        method: target.method || 'PUT',
+        // x-uniweb-sha256: optional integrity guard — direct mode verifies
+        // the received bytes and 400s on mismatch (corruption-in-flight).
+        headers: {
+          ...(target.headers || {}),
+          ...authHeaders,
+          'x-uniweb-sha256': file.sha256
+        },
+        body: bytes
+      }, { timeoutMs: 120_000, retryOnStatus: isTransientStatus })
+      if (res.ok) {
+        uploaded.push(file.path)
+        onProgress(`${file.path} (${file.size} bytes)`)
+      } else {
+        failed.push({
+          path: file.path,
+          status: res.status,
+          detail: (await res.text().catch(() => '')).slice(0, 200)
+        })
+      }
+    } catch (err) {
+      failed.push({ path: file.path, status: 0, detail: err.message })
+    }
+  }
+
+  // Prove the version is live — fetch the entry back and compare bytes.
+  // Gated on `serveBase`, NOT on the plan's mode: the question is only ever
+  // "did the backend tell us where to look", and inferring a location from the
+  // mode is the coupling this lane used to carry. A plan without a serve_base
+  // (a delivery tier owns the URL) leaves `verified` null.
+  let verified = null
+  const entry = list.find((f) => f.path === ENTRY_PATH)
+  if (serveBase && entry && !failed.length) {
+    try {
+      // serve_base may be origin-relative — resolve against the backend origin.
+      const url = new URL(
+        `${serveBase.replace(/\/$/, '')}/${ENTRY_PATH}`,
+        origin
+      ).toString()
+      const res = await fetch(url)
+      if (res.ok) {
+        const served = Buffer.from(await res.arrayBuffer())
+        const local = readFileSync(join(distDir, ENTRY_PATH))
+        verified = served.equals(local)
+      } else {
+        verified = false
+      }
+    } catch {
+      verified = false
+    }
+  }
+
+  return { mode: plan.mode || 'direct', uploaded, stored, failed, verified, serveBase }
+}