@foldspace_npm/harness 0.1.31 → 0.1.33

package/src/video/share.mjs

@@ -0,0 +1,284 @@
+// foldspace share - the bytes half of sharing a video by a Foldspace link.
+//
+// The CLI holds no Foldspace sign-in (the editor's MCP does), so sharing is
+// three steps the agent takes, only after the human said yes:
+//   1. `npx foldspace share inspect` - sizes and checks the MP4 and poster here
+//   2. MCP `create_video_share` - returns one-time signed upload targets
+//      (`upload_command`), then `npx foldspace share upload` sends the files
+//      straight to Foldspace's video storage with them
+//   3. MCP `publish_video_share` - the server checks the files and returns
+//      the public link
+// Nothing here talks to Foldspace except the upload targets the MCP issued,
+// and nothing prints them: a target is a bearer credential for one object.
+
+import fs from "node:fs";
+import path from "node:path";
+
+/** GCS requires every chunk but the last to be a multiple of 256 KiB. */
+export const CHUNK_UNIT_BYTES = 256 * 1024;
+export const DEFAULT_CHUNK_BYTES = 32 * CHUNK_UNIT_BYTES; // 8 MiB
+const MAX_ATTEMPTS_PER_CHUNK = 4;
+
+/**
+ * The only hosts an upload may go to: Google Cloud Storage, where Foldspace's video bucket is, and
+ * this machine for the local demo. A target anywhere else is refused, so a tampered or injected
+ * upload command cannot send the human's recording somewhere else.
+ */
+export function isAllowedUploadUrl(value) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    return false;
+  }
+  if (url.protocol === "https:" && url.hostname === "storage.googleapis.com") return true;
+  return url.protocol === "http:" && (url.hostname === "localhost" || url.hostname === "127.0.0.1");
+}
+
+/** Mirrors the server's caps (share-service SHARE_MAX_*): checked here so a too-big file fails before any upload. */
+export const MAX_VIDEO_BYTES = 500 * 1024 * 1024;
+export const MAX_POSTER_BYTES = 5 * 1024 * 1024;
+
+export class ShareError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+  }
+}
+
+/** The newest video/*.mp4 that `record` made, with its poster beside it. */
+export function defaultVideo(projectDir) {
+  const dir = path.join(projectDir, "video");
+  let names = [];
+  try {
+    names = fs.readdirSync(dir).filter((name) => name.endsWith(".mp4"));
+  } catch {
+    // no video folder
+  }
+  if (!names.length) {
+    throw new ShareError("NO_VIDEO", "No video/*.mp4 in this project. Make one with `npx foldspace record`, or pass the MP4's path.");
+  }
+  const newest = names
+    .map((name) => ({ name, mtime: fs.statSync(path.join(dir, name)).mtimeMs }))
+    .sort((a, b) => b.mtime - a.mtime)[0].name;
+  return path.join(dir, newest);
+}
+
+export function posterFor(videoPath) {
+  return videoPath.replace(/\.mp4$/i, ".jpg");
+}
+
+/**
+ * Sizes the two files and runs the same structural checks the server's publish
+ * check runs (MP4 with ftyp, moov before mdat; JPEG poster), so the agent hears
+ * "re-encode with faststart" before uploading 500 MB rather than after.
+ */
+export function inspectForShare({ videoPath, posterPath }) {
+  const video = statFile(videoPath, "NO_VIDEO", "video");
+  const poster = statFile(posterPath, "NO_POSTER", "poster");
+  if (video.bytes > MAX_VIDEO_BYTES) throw new ShareError("TOO_LARGE", `The video is ${mb(video.bytes)} MB; the limit is ${mb(MAX_VIDEO_BYTES)} MB.`);
+  if (poster.bytes > MAX_POSTER_BYTES) throw new ShareError("TOO_LARGE", `The poster is ${mb(poster.bytes)} MB; the limit is ${mb(MAX_POSTER_BYTES)} MB.`);
+
+  const head = readSlice(posterPath, 0, 3);
+  if (!(head[0] === 0xff && head[1] === 0xd8 && head[2] === 0xff)) {
+    throw new ShareError("NOT_JPEG", "The poster must be a JPEG image.");
+  }
+  const durationS = readMp4Duration(videoPath, video.bytes);
+  return { video: { ...video, durationS }, poster };
+}
+
+/** Walks top-level boxes: ftyp first, moov before mdat; returns mvhd duration in seconds. */
+function readMp4Duration(file, size) {
+  const first = boxAt(file, 0, size);
+  if (!first || first.type !== "ftyp") throw new ShareError("NOT_MP4", "The video is not an MP4 file.");
+  let offset = first.size;
+  for (let i = 0; i < 64 && offset < size; i++) {
+    const box = boxAt(file, offset, size);
+    if (!box) throw new ShareError("NOT_MP4", "The MP4 is truncated or damaged.");
+    if (box.type === "mdat") {
+      throw new ShareError("NOT_FAST_START", "The MP4 is not fast-start (its moov box comes after the video data). Re-encode it with `-movflags +faststart`.");
+    }
+    if (box.type === "moov") {
+      const body = readSlice(file, offset + box.header, Math.min(box.size - box.header, 16 * 1024 * 1024));
+      return mvhdDurationSeconds(body);
+    }
+    offset += box.size;
+  }
+  throw new ShareError("NOT_MP4", "The MP4 has no moov box.");
+}
+
+function mvhdDurationSeconds(moov) {
+  let offset = 0;
+  while (offset + 8 <= moov.length) {
+    const size = moov.readUInt32BE(offset);
+    const type = moov.toString("latin1", offset + 4, offset + 8);
+    if (size < 8) break;
+    if (type === "mvhd") {
+      const body = moov.subarray(offset + 8, offset + size);
+      if (body[0] === 1) return Number(body.readBigUInt64BE(24)) / body.readUInt32BE(20);
+      return body.readUInt32BE(16) / body.readUInt32BE(12);
+    }
+    offset += size;
+  }
+  throw new ShareError("NOT_MP4", "The MP4 has no movie header.");
+}
+
+function boxAt(file, offset, fileSize) {
+  if (offset + 8 > fileSize) return null;
+  const head = readSlice(file, offset, 16);
+  let size = head.readUInt32BE(0);
+  let header = 8;
+  if (size === 1) {
+    size = Number(head.readBigUInt64BE(8));
+    header = 16;
+  } else if (size === 0) {
+    size = fileSize - offset;
+  }
+  if (size < header || offset + size > fileSize) return null;
+  return { type: head.toString("latin1", 4, 8), size, header };
+}
+
+/**
+ * Parses the `--targets` JSON that `create_video_share` put in the upload
+ * command: { video: {url, method, headers}, poster: {...} }.
+ */
+export function parseTargets(text) {
+  let parsed;
+  try {
+    parsed = JSON.parse(String(text || ""));
+  } catch {
+    throw new ShareError("BAD_TARGETS", "--targets is not valid JSON. Copy the upload command from create_video_share exactly.");
+  }
+  for (const name of ["video", "poster"]) {
+    const target = parsed?.[name];
+    if (!target || typeof target.url !== "string" || target.method !== "POST" || typeof target.headers !== "object") {
+      throw new ShareError("BAD_TARGETS", `--targets has no valid ${name} target. Copy the upload command from create_video_share exactly.`);
+    }
+    if (!isAllowedUploadUrl(target.url)) {
+      throw new ShareError("BAD_TARGETS", `The ${name} upload target is not Foldspace's video storage (https://storage.googleapis.com). Use only the command create_video_share returned.`);
+    }
+  }
+  return parsed;
+}
+
+/**
+ * GCS resumable upload: POST the signed URL to start a session, then PUT the
+ * file in chunks with Content-Range. On a dropped connection it asks the
+ * session how much arrived (`bytes * /total`) and resumes from there.
+ * Errors name the HTTP status and GCS's error code, never the URL.
+ */
+export async function resumableUpload(target, filePath, { fetchImpl = fetch, chunkBytes = DEFAULT_CHUNK_BYTES, label = "file" } = {}) {
+  if (chunkBytes % CHUNK_UNIT_BYTES !== 0) throw new Error("chunkBytes must be a multiple of 256 KiB");
+  const total = fs.statSync(filePath).size;
+  if (total === 0) throw new ShareError("UPLOAD_FAILED", `The ${label} is empty.`);
+  // redirect: "manual" everywhere, never "error": GCS answers every unfinished chunk with 308 "Resume
+  // Incomplete", which fetch would turn into a network error. A 3xx that names a Location is a real
+  // redirect, and is refused (rejectRedirect): storage never sends an upload somewhere else.
+  const start = rejectRedirect(await fetchImpl(target.url, { method: "POST", headers: target.headers, body: "", redirect: "manual" }), label);
+  if (start.status !== 200 && start.status !== 201) {
+    throw new ShareError("UPLOAD_REFUSED", `Starting the ${label} upload failed: ${await describe(start)}. The upload targets last 30 minutes; if they expired, call create_video_share again.`);
+  }
+  const session = start.headers.get("location");
+  if (!session || !isAllowedUploadUrl(session)) throw new ShareError("UPLOAD_REFUSED", `Starting the ${label} upload returned no usable session.`);
+
+  let offset = 0;
+  let attempts = 0;
+  const handle = fs.openSync(filePath, "r");
+  const buffer = Buffer.alloc(Math.min(chunkBytes, total)); // one buffer, reused for every chunk
+  try {
+    while (offset < total) {
+      const end = Math.min(offset + chunkBytes, total) - 1;
+      const length = end - offset + 1;
+      fs.readSync(handle, buffer, 0, length, offset);
+      const chunk = buffer.subarray(0, length);
+      let response;
+      try {
+        response = await fetchImpl(session, {
+          method: "PUT",
+          headers: { "content-range": `bytes ${offset}-${end}/${total}` },
+          body: chunk,
+          redirect: "manual",
+        });
+      } catch (error) {
+        if (++attempts >= MAX_ATTEMPTS_PER_CHUNK) throw new ShareError("UPLOAD_FAILED", `The ${label} upload kept failing: ${error.message}`);
+        offset = await committedBytes(fetchImpl, session, total);
+        continue;
+      }
+      rejectRedirect(response, label);
+      if (response.status === 200 || response.status === 201) return { bytes: total };
+      if (response.status === 308) {
+        // Progress resets the retry count; a 308 whose committed range did not move counts as a failed
+        // attempt, so a session that never advances ends instead of looping forever.
+        const next = rangeEnd(response.headers.get("range"));
+        if (next > offset) attempts = 0;
+        else if (++attempts >= MAX_ATTEMPTS_PER_CHUNK) throw new ShareError("UPLOAD_FAILED", `The ${label} upload stopped moving: storage kept the same ${next} bytes.`);
+        offset = next;
+        continue;
+      }
+      if (response.status >= 500 && ++attempts < MAX_ATTEMPTS_PER_CHUNK) {
+        offset = await committedBytes(fetchImpl, session, total);
+        continue;
+      }
+      throw new ShareError("UPLOAD_FAILED", `The ${label} upload failed: ${await describe(response)}.`);
+    }
+  } finally {
+    fs.closeSync(handle);
+  }
+  throw new ShareError("UPLOAD_FAILED", `The ${label} upload did not finish.`);
+}
+
+async function committedBytes(fetchImpl, session, total) {
+  const status = rejectRedirect(await fetchImpl(session, { method: "PUT", headers: { "content-range": `bytes */${total}` }, body: "", redirect: "manual" }), "file");
+  if (status.status === 200 || status.status === 201) return total;
+  return rangeEnd(status.headers.get("range"));
+}
+
+/** A 3xx with a Location is a redirect away from storage: refused. (GCS's 308 Resume Incomplete has none.) */
+function rejectRedirect(response, label) {
+  if (response.status >= 300 && response.status < 400 && response.headers.get("location")) {
+    throw new ShareError("UPLOAD_REFUSED", `The ${label} upload was redirected; uploads go only to Foldspace's video storage.`);
+  }
+  return response;
+}
+
+/** "bytes=0-1048575" → 1048576 (the next byte to send); no header → 0. */
+function rangeEnd(header) {
+  const match = /bytes=0-(\d+)/.exec(header || "");
+  return match ? Number(match[1]) + 1 : 0;
+}
+
+async function describe(response) {
+  let code = "";
+  try {
+    const text = await response.text();
+    code = /<Code>([^<]{1,64})<\/Code>/.exec(text)?.[1] ?? "";
+  } catch {
+    // no body
+  }
+  return `HTTP ${response.status}${code ? ` ${code}` : ""}`;
+}
+
+function statFile(file, code, label) {
+  try {
+    const stat = fs.statSync(file);
+    if (!stat.isFile()) throw new Error("not a file");
+    return { path: file, bytes: stat.size };
+  } catch {
+    throw new ShareError(code, `No ${label} at ${file}.`);
+  }
+}
+
+function readSlice(file, offset, length) {
+  const handle = fs.openSync(file, "r");
+  try {
+    const buffer = Buffer.alloc(length);
+    const read = fs.readSync(handle, buffer, 0, length, offset);
+    return buffer.subarray(0, read);
+  } finally {
+    fs.closeSync(handle);
+  }
+}
+
+function mb(bytes) {
+  return Math.round(bytes / (1024 * 1024));
+}