run402 1.34.2 → 1.35.0

package/cli.mjs

@@ -28,7 +28,8 @@ Commands:
   deploy      Deploy a full-stack app or static site (requires active tier)
   functions   Manage serverless functions (deploy, invoke, logs, list, delete)
   secrets     Manage project secrets (set, list, delete)
-  storage     Manage file storage (upload, download, list, delete)
+  blob        Direct-to-S3 blob storage (put, get, ls, rm, sign) — up to 5 TiB
+  storage     Legacy file storage (deprecated — sunset 2026-06-01, use 'blob')
   sites       Deploy static sites
   subdomains  Manage custom subdomains (claim, list, delete)
   domains     Manage custom domains (add, list, status, delete)
@@ -115,10 +116,19 @@ switch (cmd) {
     break;
   }
   case "storage": {
+    process.stderr.write(
+      "run402 storage is deprecated — sunset 2026-06-01. Use `run402 blob` instead.\n" +
+      "See https://run402.com/docs/blob#migration\n\n",
+    );
     const { run } = await import("./lib/storage.mjs");
     await run(sub, rest);
     break;
   }
+  case "blob": {
+    const { run } = await import("./lib/blob.mjs");
+    await run(sub, rest);
+    break;
+  }
   case "sites": {
     const { run } = await import("./lib/sites.mjs");
     await run(sub, rest);

package/lib/blob.mjs

@@ -0,0 +1,449 @@
+/**
+ * run402 blob — direct-to-S3 storage CLI.
+ *
+ * Usage:
+ *   run402 blob put <file> [files...] [--project <id>] [--key <dest>] [--private] [--immutable] [--concurrency N] [--no-resume]
+ *   run402 blob get <key> --output <file> [--project <id>]
+ *   run402 blob ls [--project <id>] [--prefix <p>] [--limit <n>]
+ *   run402 blob rm <key> [--project <id>]
+ *   run402 blob sign <key> [--project <id>] [--ttl <seconds>]
+ *
+ * For any file ≤ 5 GiB a single presigned PUT is used. Larger files use S3
+ * multipart uploads with 16 MiB parts (640 parts at 10 GiB; up to 10 000
+ * parts at 5 TiB). The gateway never carries upload bytes — PUTs go straight
+ * to S3 from the client.
+ *
+ * Resumable uploads are enabled by default. The CLI persists per-upload
+ * state to ~/.run402/uploads/<upload_id>.json so a Ctrl-C'd upload can be
+ * resumed by re-running the same command.
+ */
+
+import {
+  createReadStream,
+  statSync,
+  readFileSync,
+  writeFileSync,
+  mkdirSync,
+  existsSync,
+  unlinkSync,
+  readdirSync,
+  createWriteStream,
+} from "node:fs";
+import { createHash } from "node:crypto";
+import { basename, dirname, join, resolve as resolvePath } from "node:path";
+import { homedir } from "node:os";
+import { pipeline } from "node:stream/promises";
+
+import { findProject, API } from "./config.mjs";
+
+const HELP = `run402 blob — Direct-to-S3 blob storage
+
+Usage:
+  run402 blob put <file> [files...] [options]
+  run402 blob get <key> --output <file> [options]
+  run402 blob ls [options]
+  run402 blob rm <key> [options]
+  run402 blob sign <key> [options]
+
+Options:
+  --project <id>      Project ID (defaults to active project from 'run402 projects use')
+  --key <dest>        Destination key (put only; defaults to file basename)
+  --private           Upload as private (not served by CDN; apikey required to read)
+  --immutable         Adds a content-hash suffix to the URL so overwrites produce distinct URLs.
+                      Requires computing SHA-256 over the file (CLI does this automatically).
+  --concurrency N     Concurrent part PUTs (default 4)
+  --no-resume         Start fresh; ignore any cached state
+  --json              NDJSON progress events (for agent consumption)
+  --prefix <p>        Prefix filter (ls only)
+  --limit <n>         Max results (ls only; default 100, max 1000)
+  --ttl <seconds>     Signed-URL TTL (sign only; default 3600, max 604800)
+
+Examples:
+  run402 blob put ./artifact.tgz --project abc123
+  run402 blob put ./dist/**/*.png --project abc123 --key assets/
+  run402 blob put huge.bin --project abc123 --immutable
+  run402 blob get images/logo.png --output /tmp/logo.png --project abc123
+  run402 blob ls --project abc123 --prefix images/
+  run402 blob rm images/logo.png --project abc123
+  run402 blob sign images/logo.png --project abc123 --ttl 600
+`;
+
+const UPLOAD_STATE_DIR = join(homedir(), ".run402", "uploads");
+
+function die(msg, code = 1) {
+  console.error(JSON.stringify({ status: "error", message: msg }));
+  process.exit(code);
+}
+
+function parseArgs(args) {
+  const out = { positional: [], project: null, key: null, private: false, immutable: false,
+                 concurrency: 4, resume: true, json: false, prefix: null, limit: null,
+                 output: null, ttl: null };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "--project") out.project = args[++i];
+    else if (a === "--key") out.key = args[++i];
+    else if (a === "--private") out.private = true;
+    else if (a === "--immutable") out.immutable = true;
+    else if (a === "--concurrency") out.concurrency = parseInt(args[++i], 10);
+    else if (a === "--no-resume") out.resume = false;
+    else if (a === "--json") out.json = true;
+    else if (a === "--prefix") out.prefix = args[++i];
+    else if (a === "--limit") out.limit = parseInt(args[++i], 10);
+    else if (a === "--output" || a === "-o") out.output = args[++i];
+    else if (a === "--ttl") out.ttl = parseInt(args[++i], 10);
+    else if (!a.startsWith("--")) out.positional.push(a);
+  }
+  return out;
+}
+
+function resolveProject(projectId) {
+  if (!projectId) die("--project is required (or run 'run402 projects use <id>' to set default)");
+  const p = findProject(projectId);
+  if (!p) die(`Project not found: ${projectId}`);
+  return p;
+}
+
+async function sha256File(filePath) {
+  const h = createHash("sha256");
+  const stream = createReadStream(filePath);
+  for await (const chunk of stream) h.update(chunk);
+  return h.digest("hex");
+}
+
+function loadState(uploadId) {
+  const path = join(UPLOAD_STATE_DIR, `${uploadId}.json`);
+  if (!existsSync(path)) return null;
+  try { return JSON.parse(readFileSync(path, "utf8")); }
+  catch { return null; }
+}
+
+function saveState(state) {
+  mkdirSync(UPLOAD_STATE_DIR, { recursive: true });
+  writeFileSync(join(UPLOAD_STATE_DIR, `${state.upload_id}.json`), JSON.stringify(state, null, 2));
+}
+
+function removeState(uploadId) {
+  const path = join(UPLOAD_STATE_DIR, `${uploadId}.json`);
+  if (existsSync(path)) unlinkSync(path);
+}
+
+function findResumableStateForFile(projectId, localPath, key) {
+  if (!existsSync(UPLOAD_STATE_DIR)) return null;
+  for (const f of readdirSync(UPLOAD_STATE_DIR)) {
+    if (!f.endsWith(".json")) continue;
+    try {
+      const s = JSON.parse(readFileSync(join(UPLOAD_STATE_DIR, f), "utf8"));
+      if (s.project_id === projectId && s.local_path === localPath && s.key === key) return s;
+    } catch { /* ignore */ }
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// put
+// ---------------------------------------------------------------------------
+
+async function putOne(project, filePath, opts) {
+  const stat = statSync(filePath);
+  const size = stat.size;
+  const destKey = computeDestKey(filePath, opts.key);
+  const absLocal = resolvePath(filePath);
+
+  // Compute sha256 for immutable uploads up front; otherwise lazy.
+  const needSha = opts.immutable;
+  const sha256 = needSha ? await sha256File(filePath) : undefined;
+
+  // Attempt to resume
+  let state = opts.resume
+    ? findResumableStateForFile(project.id, absLocal, destKey)
+    : null;
+  let initRes;
+  if (state) {
+    // Re-poll the session; if it's still active, resume. Otherwise start fresh.
+    const poll = await apiFetch(`${API}/storage/v1/uploads/${state.upload_id}`, "GET", project, null);
+    if (poll.status === 200 && poll.body.status === "active") {
+      log(opts, { event: "resume", upload_id: state.upload_id, key: destKey });
+      initRes = { upload_id: state.upload_id, mode: state.mode, parts: state.parts, part_count: state.part_count, part_size_bytes: state.part_size_bytes };
+    } else {
+      removeState(state.upload_id);
+      state = null;
+    }
+  }
+
+  if (!state) {
+    const init = await apiFetch(`${API}/storage/v1/uploads`, "POST", project, {
+      key: destKey,
+      size_bytes: size,
+      content_type: guessContentType(destKey),
+      visibility: opts.private ? "private" : "public",
+      immutable: opts.immutable,
+      sha256,
+    });
+    if (init.status !== 201) die(`Init failed: HTTP ${init.status}: ${JSON.stringify(init.body)}`);
+    initRes = init.body;
+    saveState({
+      upload_id: initRes.upload_id,
+      project_id: project.id,
+      local_path: absLocal,
+      key: destKey,
+      mode: initRes.mode,
+      part_size_bytes: initRes.part_size_bytes,
+      part_count: initRes.part_count,
+      parts: initRes.parts,
+      parts_done: {},
+      sha256,
+      started_at: new Date().toISOString(),
+    });
+    state = loadState(initRes.upload_id);
+  }
+
+  // Upload parts with concurrency limit. For single-PUT mode part_count=1 and
+  // this loop runs once.
+  const etags = Array(initRes.part_count);
+  for (const pn of Object.keys(state.parts_done || {})) {
+    const pd = state.parts_done[pn];
+    // Legacy resume state stored just the etag string; new code stores
+    // { etag, sha256 }. Normalize on load.
+    etags[parseInt(pn, 10) - 1] = typeof pd === "string" ? { etag: pd, sha256: undefined } : pd;
+  }
+
+  // Presigned URLs are signed WITHOUT ChecksumAlgorithm (see gateway
+  // s3-presign.ts). The client-asserted sha256 declared at init is the
+  // integrity attestation — no x-amz-checksum-sha256 header on PUTs, and
+  // the gateway trusts the declared value at complete when S3 has none.
+  const todo = initRes.parts.filter((p) => !(state.parts_done || {})[String(p.part_number)]);
+  await withConcurrency(todo, opts.concurrency, async (part) => {
+    const { etag } = await putPart(filePath, part);
+    etags[part.part_number - 1] = { etag };
+    state.parts_done[String(part.part_number)] = { etag };
+    saveState(state);
+    log(opts, { event: "part", upload_id: state.upload_id, part_number: part.part_number, etag });
+  });
+
+  // Complete
+  const body = initRes.mode === "multipart"
+    ? { parts: etags.map((e, i) => ({ part_number: i + 1, etag: e.etag })) }
+    : {};
+  const complete = await apiFetch(`${API}/storage/v1/uploads/${state.upload_id}/complete`, "POST", project, body);
+  if (complete.status !== 200) die(`Complete failed: HTTP ${complete.status}: ${JSON.stringify(complete.body)}`);
+
+  removeState(state.upload_id);
+  log(opts, { event: "done", ...complete.body });
+  return complete.body;
+}
+
+function computeDestKey(filePath, keyOpt) {
+  if (!keyOpt) return basename(filePath);
+  if (keyOpt.endsWith("/")) return keyOpt + basename(filePath);
+  return keyOpt;
+}
+
+async function putPart(filePath, part) {
+  const start = part.byte_start ?? 0;
+  const end = part.byte_end ?? (statSync(filePath).size - 1);
+  const stream = createReadStream(filePath, { start, end });
+  const chunks = [];
+  for await (const c of stream) chunks.push(c);
+  const body = Buffer.concat(chunks);
+
+  const res = await fetch(part.url, { method: "PUT", body });
+  if (!res.ok) {
+    const errBody = await res.text().catch(() => "");
+    throw new Error(`Part ${part.part_number} PUT failed: ${res.status} ${res.statusText}${errBody ? " — " + errBody.slice(0, 200) : ""}`);
+  }
+  const etag = res.headers.get("etag") ?? "";
+  return { etag };
+}
+
+async function withConcurrency(items, limit, worker) {
+  const running = [];
+  for (const item of items) {
+    const p = Promise.resolve().then(() => worker(item));
+    running.push(p);
+    if (running.length >= limit) {
+      await Promise.race(running.map((r) => r.catch(() => {})));
+      for (let i = running.length - 1; i >= 0; i--) {
+        if (isSettled(running[i])) running.splice(i, 1);
+      }
+    }
+  }
+  await Promise.all(running);
+}
+
+function isSettled(p) {
+  const marker = {};
+  return Promise.race([p, marker]).then(
+    (v) => v !== marker,
+    () => true,
+  );
+}
+
+async function put(projectId, argv) {
+  const opts = parseArgs(argv);
+  opts.project = opts.project || projectId;
+  const project = resolveProject(opts.project);
+
+  if (opts.positional.length === 0) die("At least one file path is required");
+  if (opts.immutable && opts.positional.length > 1 && opts.key && !opts.key.endsWith("/")) {
+    die("--key with --immutable across multiple files requires a directory prefix (ending with /)");
+  }
+
+  const results = [];
+  for (const filePath of opts.positional) {
+    if (!existsSync(filePath)) die(`File not found: ${filePath}`);
+    const r = await putOne(project, filePath, opts);
+    results.push({ file: filePath, ...r });
+  }
+  if (!opts.json) console.log(JSON.stringify(results, null, 2));
+}
+
+// ---------------------------------------------------------------------------
+// get
+// ---------------------------------------------------------------------------
+
+async function get(projectId, argv) {
+  const opts = parseArgs(argv);
+  opts.project = opts.project || projectId;
+  const project = resolveProject(opts.project);
+  if (opts.positional.length === 0) die("Key required");
+  if (!opts.output) die("--output <file> required");
+  const key = opts.positional[0];
+
+  const res = await fetch(`${API}/storage/v1/blob/${encodeKey(key)}`, {
+    headers: { apikey: project.anon_key, Authorization: `Bearer ${project.anon_key}` },
+  });
+  if (!res.ok) die(`GET failed: HTTP ${res.status}`);
+  if (!res.body) die("Empty response body");
+
+  mkdirSync(dirname(resolvePath(opts.output)), { recursive: true });
+  await pipeline(res.body, createWriteStream(opts.output));
+  console.log(JSON.stringify({ status: "ok", key, output: opts.output }));
+}
+
+// ---------------------------------------------------------------------------
+// ls
+// ---------------------------------------------------------------------------
+
+async function ls(projectId, argv) {
+  const opts = parseArgs(argv);
+  opts.project = opts.project || projectId;
+  const project = resolveProject(opts.project);
+
+  const qs = new URLSearchParams();
+  if (opts.prefix) qs.set("prefix", opts.prefix);
+  if (opts.limit) qs.set("limit", String(opts.limit));
+  const url = `${API}/storage/v1/blobs${qs.toString() ? "?" + qs.toString() : ""}`;
+
+  const res = await fetch(url, {
+    headers: { apikey: project.anon_key, Authorization: `Bearer ${project.anon_key}` },
+  });
+  const data = await res.json();
+  if (!res.ok) { console.error(JSON.stringify({ status: "error", http: res.status, ...data })); process.exit(1); }
+  console.log(JSON.stringify(data, null, 2));
+}
+
+// ---------------------------------------------------------------------------
+// rm
+// ---------------------------------------------------------------------------
+
+async function rm(projectId, argv) {
+  const opts = parseArgs(argv);
+  opts.project = opts.project || projectId;
+  const project = resolveProject(opts.project);
+  if (opts.positional.length === 0) die("Key required");
+  const key = opts.positional[0];
+
+  const res = await fetch(`${API}/storage/v1/blob/${encodeKey(key)}`, {
+    method: "DELETE",
+    headers: { apikey: project.anon_key, Authorization: `Bearer ${project.anon_key}` },
+  });
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok) { console.error(JSON.stringify({ status: "error", http: res.status, ...data })); process.exit(1); }
+  console.log(JSON.stringify(data, null, 2));
+}
+
+// ---------------------------------------------------------------------------
+// sign
+// ---------------------------------------------------------------------------
+
+async function sign(projectId, argv) {
+  const opts = parseArgs(argv);
+  opts.project = opts.project || projectId;
+  const project = resolveProject(opts.project);
+  if (opts.positional.length === 0) die("Key required");
+  const key = opts.positional[0];
+
+  const res = await fetch(`${API}/storage/v1/blob/${encodeKey(key)}/sign`, {
+    method: "POST",
+    headers: { "content-type": "application/json", apikey: project.anon_key, Authorization: `Bearer ${project.anon_key}` },
+    body: JSON.stringify(opts.ttl ? { ttl_seconds: opts.ttl } : {}),
+  });
+  const data = await res.json();
+  if (!res.ok) { console.error(JSON.stringify({ status: "error", http: res.status, ...data })); process.exit(1); }
+  console.log(JSON.stringify(data, null, 2));
+}
+
+// ---------------------------------------------------------------------------
+// Shared helpers
+// ---------------------------------------------------------------------------
+
+function encodeKey(key) {
+  // Encode each path segment; preserve `/` as separator.
+  return key.split("/").map(encodeURIComponent).join("/");
+}
+
+function guessContentType(key) {
+  const ext = key.slice(key.lastIndexOf(".") + 1).toLowerCase();
+  const map = {
+    png: "image/png", jpg: "image/jpeg", jpeg: "image/jpeg", gif: "image/gif",
+    svg: "image/svg+xml", webp: "image/webp",
+    html: "text/html", css: "text/css", js: "text/javascript", json: "application/json",
+    txt: "text/plain", md: "text/markdown", pdf: "application/pdf",
+    mp4: "video/mp4", webm: "video/webm", mov: "video/quicktime",
+    zip: "application/zip", tgz: "application/gzip", gz: "application/gzip",
+  };
+  return map[ext] ?? "application/octet-stream";
+}
+
+async function apiFetch(url, method, project, body) {
+  const res = await fetch(url, {
+    method,
+    headers: {
+      "content-type": "application/json",
+      apikey: project.anon_key,
+      Authorization: `Bearer ${project.anon_key}`,
+    },
+    body: body === null ? undefined : JSON.stringify(body ?? {}),
+  });
+  const txt = await res.text();
+  let parsed; try { parsed = txt ? JSON.parse(txt) : null; } catch { parsed = txt; }
+  return { status: res.status, body: parsed };
+}
+
+function log(opts, event) {
+  if (opts.json) console.log(JSON.stringify(event));
+}
+
+// ---------------------------------------------------------------------------
+// Dispatch
+// ---------------------------------------------------------------------------
+
+export async function run(sub, args) {
+  if (!sub || sub === "--help" || sub === "-h") {
+    console.log(HELP);
+    process.exit(0);
+  }
+  const defaultProject = process.env.RUN402_PROJECT ?? null;
+  switch (sub) {
+    case "put":   await put(defaultProject, args); break;
+    case "get":   await get(defaultProject, args); break;
+    case "ls":    await ls(defaultProject, args); break;
+    case "rm":    await rm(defaultProject, args); break;
+    case "sign":  await sign(defaultProject, args); break;
+    default:
+      console.error(`Unknown subcommand: ${sub}`);
+      console.log(HELP);
+      process.exit(1);
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "run402",
-  "version": "1.34.2",
+  "version": "1.35.0",
   "description": "CLI for Run402 — provision Postgres databases, deploy static sites, generate images, and manage wallets via x402 and MPP micropayments.",
   "type": "module",
   "bin": {